feat(next): native Generic Viewport migration (useNextViewports)

.scripts/check-next-viewports-flag-reads.mjs

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Guards the `useNextViewports` flag-read surface (migration plan §4.2).
+ *
+ * The native ("next") GenericViewport opt-in flag must be read in only a small,
+ * fixed set of places so the legacy (flag-off) path cannot drift. This check fails
+ * if any OTHER file under extensions/cornerstone/src reads the flag, via either
+ * `isNextViewportsEnabled()` or `appConfig.useNextViewports`.
+ *
+ * Sanctioned readers (keep this list and the plan §4.2 in sync):
+ *   - utils/getCornerstoneViewportType.ts  — sanctioned read #1 (viewport type selection)
+ *   - services/ViewportService/CornerstoneViewportService.ts — sanctioned read #2 (backend selection)
+ *   - services/SegmentationService/SegmentationService.ts — sanctioned read #3 (the one viewport-less
+ *                                             seg-backend dispatch: a DICOM SEG's single- vs multi-layer
+ *                                             overlap data shape is fixed at load, before any target
+ *                                             viewport exists, so it cannot use a capability predicate)
+ *   - utils/nextViewports.ts                — the accessor module itself (defines get/set)
+ *   - init.tsx                              — the single setup site that reads appConfig.useNextViewports
+ *                                             to seed the accessor
+ *   - getToolbarModule.tsx                  — TEMP dev toggle evaluator (remove at M7; see
+ *                                             TODO_BEFORE_MERGE.md, and drop this entry then)
+ *   - *.test.ts(x)                          — unit tests exercising the mapping
+ *
+ * Everywhere else, branch on cornerstone CONTENT/CAPABILITY predicates
+ * (csUtils.isGenericViewport / viewportIsInVolumeMode / viewportIsInStackMode), or
+ * route the viewport through the Legacy/Next backend twins — never the flag.
+ */
+
+const SRC_DIR = path.resolve(process.cwd(), 'extensions', 'cornerstone', 'src');
+
+// Allowlisted files, relative to SRC_DIR (POSIX separators).
+const ALLOWLIST = new Set([
+  'utils/getCornerstoneViewportType.ts',
+  'services/ViewportService/CornerstoneViewportService.ts',
+  'services/SegmentationService/SegmentationService.ts',
+  'utils/nextViewports.ts',
+  'init.tsx',
+  // TEMP — remove together with the dev toggle button (TODO_BEFORE_MERGE.md):
+  'getToolbarModule.tsx',
+]);
+
+// Matches an actual flag READ: the accessor call or the appConfig field access.
+const READ_PATTERNS = [/\bisNextViewportsEnabled\s*\(/, /\bappConfig[?.]*\.useNextViewports\b/];
+
+function isCommentLine(line) {
+  const t = line.trim();
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*');
+}
+
+function walk(dir, out) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, out);
+    } else if (/\.tsx?$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+if (!fs.existsSync(SRC_DIR)) {
+  console.error(`[next:check-flag-reads] Source dir not found: ${SRC_DIR}`);
+  process.exit(1);
+}
+
+const offenders = [];
+
+for (const file of walk(SRC_DIR, [])) {
+  const rel = path.relative(SRC_DIR, file).split(path.sep).join('/');
+  if (ALLOWLIST.has(rel) || /\.test\.tsx?$/.test(rel)) {
+    continue;
+  }
+
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  lines.forEach((line, i) => {
+    if (isCommentLine(line)) {
+      return;
+    }
+    if (READ_PATTERNS.some(re => re.test(line))) {
+      offenders.push(`${rel}:${i + 1}: ${line.trim()}`);
+    }
+  });
+}
+
+if (offenders.length > 0) {
+  console.error(
+    '[next:check-flag-reads] The useNextViewports flag is read outside the sanctioned set (plan §4.2).\n' +
+      'Branch on cornerstone content/capability predicates or the Legacy/Next backend twins instead,\n' +
+      'or add the file to the allowlist in .scripts/check-next-viewports-flag-reads.mjs if the read is\n' +
+      'genuinely a sanctioned seam. Offending reads:\n' +
+      offenders.map(o => `  - ${o}`).join('\n')
+  );
+  process.exit(1);
+}
+
+console.log('[next:check-flag-reads] OK: useNextViewports is read only in the sanctioned set.');

TODO_BEFORE_MERGE.md

@@ -0,0 +1,56 @@
+# TODO before merge
+
+Temporary / dev-only changes added while building the native GenericViewport
+("next") migration behind `appConfig.useNextViewports`. Remove or revert all of
+these before merging to `master`. They exist only to make the native path easy
+to exercise and compare locally; none of them should ship.
+
+## 1. Dev config flag (flips the default for everyone)
+- `platform/app/public/config/default.js` — remove the `useNextViewports: true`
+  line. The flag must stay opt-in (default off); committing it on would change
+  the default backend for every deployment using this config.
+
+## 2. In-toolbar legacy/next backend toggle button (debug only)
+A throwaway toolbar button + supporting plumbing to flip the backend at runtime
+and reload. Remove all of:
+- `extensions/cornerstone/src/utils/nextViewports.ts` — remove
+  `resolveNextViewportsEnabled`, `toggleNextViewportsAndReload`, and the
+  `NEXT_VIEWPORTS_OVERRIDE_KEY` localStorage block. Keep
+  `set/isNextViewportsEnabled`.
+- `extensions/cornerstone/src/init.tsx` — revert to
+  `setNextViewportsEnabled(Boolean(appConfig.useNextViewports));` (drop the
+  `resolveNextViewportsEnabled` override and its import).
+- `extensions/cornerstone/src/commandsModule.ts` — remove the
+  `toggleNextViewports` action, its entry in the commands map, and the
+  `toggleNextViewportsAndReload` import.
+- `extensions/cornerstone/src/getToolbarModule.tsx` — remove the
+  `evaluate.cornerstone.nextViewportsToggle` evaluator and the
+  `isNextViewportsEnabled` import. Then also drop `getToolbarModule.tsx` from the
+  allowlist in `.scripts/check-next-viewports-flag-reads.mjs` (it is the one
+  TEMP-only entry there).
+- `modes/basic/src/toolbarButtons.ts` — remove the `ToggleNextViewport` button.
+- `modes/basic/src/index.tsx` — remove `'ToggleNextViewport'` from the primary
+  toolbar section.
+
+Each temporary block is marked with a `TEMP (remove before merge ...)` comment,
+so `git grep "remove before merge"` finds every site.
+
+## 3. Flag-read allowlist guard (permanent — keep)
+
+`yarn next:check-flag-reads` (`.scripts/check-next-viewports-flag-reads.mjs`)
+enforces migration plan §4.2: the `useNextViewports` flag may be read only in the
+sanctioned set — `getCornerstoneViewportType.ts` (type selection),
+`CornerstoneViewportService.ts` (backend selection), `nextViewports.ts` (the
+accessor), `init.tsx` (the one `appConfig.useNextViewports` read that seeds the
+accessor), and — temporarily — `getToolbarModule.tsx` (the dev toggle). Everywhere
+else, branch on cornerstone content/capability predicates or the Legacy/Next
+backend twins. This guard is NOT a dev-only revert; it stays after merge.
+
+## 4. Verify
+After removing the above:
+- `git grep "remove before merge"` returns nothing.
+- `git grep useNextViewports -- platform/app/public/config` returns nothing.
+- `yarn next:check-flag-reads` still passes (with `getToolbarModule.tsx` dropped
+  from its allowlist).
+- The native path is still reachable purely by setting `useNextViewports: true`
+  in a deployment config (the feature itself stays).