chore: update to OHIF 3.13.12

.agents/skills/ohif-test-agent/assets/spec-template.ts

@@ -0,0 +1,54 @@
+import {
+  checkForScreenshot,
+  expect,
+  screenShotPaths,
+  test,
+  visitStudy,
+  waitForViewportRenderCycle,
+} from './utils';
+
+test.beforeEach(async ({ page }) => {
+  // Pick the right UID + mode for your feature (see references/patterns-by-feature.md)
+  const studyInstanceUID = '1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5';
+  const mode = 'viewer';
+  await visitStudy(page, studyInstanceUID, mode, 2000);
+});
+
+test.describe('FEATURE NAME', () => {
+  test('describes the behaviour in one sentence', async ({
+    page,
+    viewportPageObject,
+    mainToolbarPageObject,
+    rightPanelPageObject,
+    DOMOverlayPageObject, // capital D on purpose
+  }) => {
+    // 1. Arrange — select a tool, open a panel, etc.
+
+    // 2. Act — interact with the viewport.
+    //    Prefer normalized (0–1) coordinates:
+    //    const activeViewport = await viewportPageObject.active;
+    //    await activeViewport.normalizedClickAt([{ x: 0.3, y: 0.3 }, { x: 0.7, y: 0.7 }]);
+
+    //    For actions that re-render the viewport, gate on the render cycle
+    //    instead of sleeping — start the watcher BEFORE the action:
+    //    const cycle = waitForViewportRenderCycle(page);
+    //    await action();
+    //    await cycle;
+
+    // 3. Handle prompts (first measurement prompts for tracking; SEG/RT/SR prompts for hydration)
+    //    await DOMOverlayPageObject.viewport.measurementTracking.confirm.click();
+
+    // 4. Assert canvas output via visual regression — object form, scoped to the
+    //    viewport via a locator (not the full page). normalizedClip is only for
+    //    clipping to a sub-region of that locator.
+    //    await checkForScreenshot({
+    //      page,
+    //      locator: viewportPageObject.grid,
+    //      screenshotPath: screenShotPaths.YOUR_CATEGORY.YOUR_KEY,
+    //    });
+
+    // 5. Assert DOM state directly
+    //    const count = await rightPanelPageObject.measurementsPanel.panel.getMeasurementCount();
+    //    expect(count).toBe(1);
+  });
+});

.agents/skills/ohif-test-agent/references/failure-triage.md

@@ -0,0 +1,72 @@
+# Failure triage
+
+Before debugging, classify. Most OHIF test failures are timing or hydration — not real regressions.
+
+| Category | Symptom | Fix |
+|----------|---------|-----|
+| Timing | Element not visible, action timeout | Add / increase the `delay` param of `visitStudy`; for actions that re-render viewports, use `waitForViewportRenderCycle(page)` (started before the action) instead of `waitForTimeout`; wrap the assertion in `expect.toPass({ timeout })` |
+| Selector | Element not found | Verify `data-cy` on the target; confirm the panel is open (`toggle()` / `select()` before interacting); check for capital `D` in `DOMOverlayPageObject` when destructuring |
+| Hydration | Segmentation/RT/SR not interactive | Ensure the `segmentationHydration.yes.click()` fired; wait for an observable hydrated state such as measurement/segment rows or the target series overlay, then wait for the resulting viewport render |
+| Data | Study not found, empty viewport | Confirm the UID is in the canonical list (see [patterns-by-feature.md](patterns-by-feature.md)); confirm the mode supports the feature (segmentation tools aren't in `viewer` mode) |
+| Visual drift | Screenshot mismatch but feature works | Have a human review the diff, then regenerate the baseline with `TEST_ENV=true pnpm exec playwright test --update-snapshots`. Do not adjust `maxDiffPixelRatio` or `threshold` to make a failing screenshot pass. |
+| Real regression | Feature is actually broken | Report as a bug — this is the test doing its job |
+
+## Prefer render-cycle waits over sleeps
+
+If you're tempted to add `await page.waitForTimeout(2000)` after an action, ask whether the action re-rendered the viewport. If it did, use:
+
+```ts
+const cycle = waitForViewportRenderCycle(page);
+await action();
+await cycle;
+await check();
+```
+
+The watcher must be created **before** the action — it waits for `needsRender` first, and that transition is gone by the time the action returns. See the "Wait for renders, don't sleep" section in [SKILL.md](../SKILL.md) and `tests/SEGHydrationFromMPR.spec.ts`.
+
+### When the cycle helper times out at `waitForAnyViewportNeedsRender`
+
+Symptom: the test fails inside `waitForAnyViewportNeedsRender` after 5s, with the action having actually completed in the UI. The action just doesn't transition the viewport through `needsRender` synchronously. Known cases:
+
+- Hanging-protocol changes.
+- **RTSTRUCT / contour segmentation hydration confirm.** SEG (labelmap) hydration does fire `needsRender`; contour does not. The fix is to gate on the actual end-state — for hydration in `beforeEach`, `await expect(page.getByTestId('data-row')).toHaveCount(N)` is the right wait.
+
+Don't react by raising the cycle's timeout — the transition isn't coming. Replace the cycle wrapper with an auto-retrying DOM/SVG assertion, or `expect.toPass({ timeout })` around the assertion block.
+
+An immediate `waitForViewportsRendered(page)` can also return too early when a click dispatches work through an asynchronous state machine: the old viewport is already `rendered` before the new series or annotations are applied. In that case, first wait for the target state (for example, hydrated measurement rows or the expected series overlay), then call `waitForViewportsRendered(page)` to settle that state's render.
+
+## The `toPass` pattern
+
+When an assertion needs to wait for async render / propagation:
+
+```ts
+await expect(async () => {
+  await rightPanelPageObject.labelMapSegmentationPanel.panel.segmentByText('Spleen').click();
+  await expect(activeViewport.overlayText.bottomRight.instanceNumber).toContainText('17/');
+}).toPass({ timeout: 10_000 });
+```
+
+`toPass` reruns the assertion block until it succeeds or the timeout expires — cleaner than a hand-rolled retry loop and surfaces the last failure reason if it times out.
+
+## Common `DOMOverlayPageObject` mistake
+
+The fixture key is capital-D `DOMOverlayPageObject`, not lowercase. If your destructure is silently `undefined`, check the casing.
+
+## `press` import mistake
+
+`press` is NOT re-exported from `./utils`. `import { press } from './utils'` resolves to `undefined` and fails at runtime. Use:
+
+```ts
+import { press } from './utils/keyboardUtils';
+await press({ page, key: 'ArrowDown', nTimes: 50 }); // object param, not (page, key)
+```
+
+## Visual regression iteration
+
+Screenshots live under `tests/screenshots/chromium/<testFilePath>/`. To accept new output as the baseline:
+
+```sh
+TEST_ENV=true pnpm exec playwright test tests/YourSpec.spec.ts --update-snapshots
+```
+
+Review the resulting PNGs carefully — an agent-accepted baseline that's subtly wrong is worse than a failing test.

.agents/skills/ohif-test-agent/references/page-objects.md

@@ -0,0 +1,120 @@
+# OHIF Page Object guide
+
+> This file documents the **stable structural rules** of the page object system. For the current list of methods and properties on any class, **read the source under `tests/pages/`** — it is always authoritative, and it evolves as the product does. A static method table in a reference file goes stale the moment someone refactors; the source does not.
+
+## How to discover the API of a page object
+
+1. Find the relevant class in `tests/pages/`. File names match class names.
+2. Read it end-to-end once — most are under a few hundred lines.
+3. Some classes compose sub-objects (e.g. `RightPanelPageObject` holds a measurementsPanel, contourSegmentationPanel, labelMapSegmentationPanel, tmtvPanel, etc.). Those sub-objects usually live in the same file or a sibling under `tests/pages/`.
+4. To see how a method is actually used, grep `tests/` or open the seed spec listed in [patterns-by-feature.md](patterns-by-feature.md). Real usage beats a synthesized signature every time.
+
+Do not try to memorize a method surface from this file — it intentionally does not list one. It lists only the rules you cannot derive from the source by reading a single file.
+
+---
+
+## Stable rules
+
+### Fixture keys (case-sensitive)
+
+These are injected via `tests/utils/fixture.ts`. Destructure them from the test function's first argument — do not `new` them, because the fixture wires sub-objects to the correct `page` and hand-constructed instances skip that wiring.
+
+- `viewportPageObject`
+- `mainToolbarPageObject`
+- `leftPanelPageObject`
+- `rightPanelPageObject`
+- `DOMOverlayPageObject` — **capital D**. A silent `undefined` destructure is almost always a casing typo here.
+- `notFoundStudyPageObject`
+
+If the fixture file is updated and new keys are added, they will show up there first — check it if something feels missing.
+
+### Non-fixture page objects
+
+Some page object classes are not fixture-injected. They are reached through an injected fixture:
+
+- `DicomTagBrowserPageObject` → via `DOMOverlayPageObject.dialog.dicomTagBrowser`
+- `DataOverlayPageObject` → via `viewportPageObject.getById(viewportId).overlayMenu.dataOverlay`
+
+Both can be constructed manually (`new DataOverlayPageObject(page)`) if a test really needs a fresh instance, but the accessor path is the idiomatic one.
+
+### Viewport wrapper vs. viewport instance
+
+`viewportPageObject` is a **wrapper**. You almost always want a specific viewport out of it first:
+
+- `await viewportPageObject.active` — the currently focused viewport
+- `viewportPageObject.getAll()` — every viewport in the grid
+- `viewportPageObject.getNth(i)` — zero-indexed
+- `viewportPageObject.getById(cornerstoneViewportId)` — e.g. `'default'`, `'ctAXIAL'`
+
+The object these return is the one with `normalizedClickAt`, `normalizedDragAt`, `overlayText`, `nthAnnotation`, etc. Reach for the viewport instance first, then call methods on it.
+
+### Panel access order
+
+Every `rightPanelPageObject` sub-panel follows the same three-step idiom: **open the side panel, `.select()` the sub-panel tab, then interact with `.panel.*`**. Skipping either of the first two is the most common cause of "element not found".
+
+```ts
+await rightPanelPageObject.toggle();
+await rightPanelPageObject.measurementsPanel.select();
+const count = await rightPanelPageObject.measurementsPanel.panel.getMeasurementCount();
+```
+
+The exact row/action methods vary by panel — check the source file for the one you need.
+
+### Layout identifiers are camelCase JS properties
+
+`mainToolbarPageObject.layoutSelection.<layout>.click()` — access layouts by camelCase property name (e.g. `threeDFourUp`, `axialPrimary`), not with bracket-escaped DICOM-ish strings like `['3DFourUp']`. This is a convention enforced by how the class exposes its tools.
+
+### Sub-tools auto-open their dropdown
+
+Tools nested inside a toolbar dropdown (measurement tools, more tools, layouts) each expose a `.click()` that opens the parent menu for you. You almost never need to open the menu first. `await mainToolbarPageObject.measurementTools.length.click()` does both the expand and the select.
+
+### When the control you need isn't covered yet — create or augment
+
+The page objects here cover what the suite currently exercises. When your test needs a
+control that isn't exposed, **extend the page object system rather than dropping a raw
+`page.getByTestId(...)` into the spec.** A raw selector in a spec is the clearest tell
+that the author didn't read the existing tests — it duplicates a locator that should
+live in one place and bypasses the fixture wiring.
+
+| What you need | Where it goes | Precedent to copy |
+|---|---|---|
+| A toolbar button/tool (Zoom, Pan) | a getter on `MainToolbarPageObject` | `crosshairs`, `measurementTools` |
+| A menu / prompt / context menu / small dialog | `DOMOverlayPageObject` | `viewport.measurementTracking`, `dialog.input` |
+| A large dialog with its own fields (User Preferences) | a **new** page object class reached via `DOMOverlayPageObject` | `DicomTagBrowserPageObject` (`DOMOverlayPageObject.dialog.dicomTagBrowser`) |
+| Individual fields/rows in that dialog | methods/sub-objects on the dialog's page object | `DicomTagBrowserPageObject.seriesSelect` |
+| Side-panel controls | `LeftPanelPageObject` / `RightPanelPageObject` | existing sub-panels |
+
+Two more expectations:
+
+- **Missing `data-cy`?** Add it to the source component and target it; don't fall back
+  to `getByRole`/text. `testIdAttribute` is `data-cy`, so `getByTestId('Zoom')` resolves
+  `[data-cy="Zoom"]`. Mention any attribute you added so it ships in the same PR.
+- **Mirror the existing shape.** A new getter should look like its neighbors (return a
+  locator, or a small object with `.click()` etc.) so the new surface is
+  indistinguishable from what was already there.
+
+Example — a "set the Zoom hotkey" test should make `mainToolbarPageObject.zoom`, an
+options-menu accessor on `DOMOverlayPageObject`, and a `userPreferences` dialog page
+object (with a per-hotkey field accessor) exist — then the spec reads as steps, not
+selectors.
+
+---
+
+## Page object map — what each class is *for*
+
+This table exists to help you pick the right file to open, not to enumerate methods. Source of truth for any specific method remains the `.ts` file.
+
+| Class | File | Covers |
+|-------|------|--------|
+| ViewportPageObject | `tests/pages/ViewportPageObject.ts` | Cornerstone viewports — clicks, drags, overlays, annotations, crosshairs |
+| MainToolbarPageObject | `tests/pages/MainToolbarPageObject.ts` | Top toolbar — measurement tools, more tools, layouts, crosshairs, pan |
+| LeftPanelPageObject | `tests/pages/LeftPanelPageObject.ts` | Study browser — thumbnails, load by modality or description |
+| RightPanelPageObject | `tests/pages/RightPanelPageObject.ts` | Side panels — measurements, contour seg, labelmap seg, TMTV, microscopy |
+| DOMOverlayPageObject | `tests/pages/DOMOverlayPageObject.ts` | DOM overlays — dialogs, hydration/tracking prompts, context menus, tag-browser accessor |
+| NotFoundStudyPageObject | `tests/pages/NotFoundStudyPageObject.ts` | Study-not-found error page |
+| DicomTagBrowserPageObject | `tests/pages/DicomTagBrowserPageObject.ts` | Tag-browser dialog (non-fixture; reach via `DOMOverlayPageObject.dialog`) |
+| DataOverlayPageObject | `tests/pages/DataOverlayPageObject.ts` | Data-overlay menu (non-fixture; reach via `viewport.overlayMenu`) |
+
+If the directory adds or renames a file, that diff is your first clue and this table is your second — trust the directory.
+
+For live usage, the seed spec in [patterns-by-feature.md](patterns-by-feature.md) shows how a class is actually called; the source file tells you everything else that's on it.