feat: Add customization URL parameter (#5992)

* Add customization URL parameter

* fix: Preserve should be customizeable

* Update customizations docs

* fix: Overlay items on patient name

* Add customization test

* Fix resolve to absolute path

* fix: Warn on no data in load

* Remove unused customization stuff

* fix: PR comments

* Update stored parameters to only use an array for mulitples

* Remove requires ohif.* special call out

* Remove strict mode

* PR comments

* Document segmentation examples

* Add three examples as requested

* PR comments

* lock

* Remove old customizatoin export

* fix: Ordering issues on customization loads

* fix: Use correct default for dev builds app config

* Fixes for conflicts

* chore: restore pnpm-lock.yaml to match master

The lockfile diff was incidental peer-descriptor churn and carried no
functional dependency change. It tripped the CircleCI security-audit gate
(which only runs when pnpm-lock.yaml is in the PR diff), surfacing a
pre-existing critical `decompress` transitive vuln that also exists on
master. Restoring master's lockfile removes the audit trigger.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ci): restore json5 lockfile entry; ignore unfixable decompress GHSA

The previous commit restored pnpm-lock.yaml from master, which dropped the
json5@2.2.3 entry that platform/core legitimately depends on (JSONC parsing
for the customization feature). That broke `--frozen-lockfile` install
(ERR_PNPM_OUTDATED_LOCKFILE). This restores the correct lockfile.

Because the lockfile must change (json5), the CircleCI security-audit gate
runs and previously failed on a critical `decompress` <=4.2.1 zip-slip
advisory. This is a pre-existing transitive vuln (present on master too) with
no published patch — decompress's latest release is 4.2.1, so no version
bump/override can resolve it. It reaches the tree only via @itk-wasm/dam, a
build/data-asset extraction tool under @cornerstonejs/labelmap-interpolation.

Add GHSA-mp2f-45pm-3cg9 to the existing pnpm-workspace.yaml auditConfig
ignoreGhsas accepted-risk list, matching how the repo already exempts other
build-tooling advisories. `pnpm audit --audit-level high` now passes locally
(1 critical ignored, 0 high).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(e2e): fix visitStudy URL encoding that broke mpr2 study load

The visitStudy rewrite (added for the ?customization= option) built the URL
with new URLSearchParams({ StudyInstanceUIDs: studyInstanceUID }), which
percent-encodes the value. mpr2.spec.ts embeds an extra param in the UID
string ('<uid>&hangingprotocolid=mpr'), so the & and = were encoded and the
whole thing collapsed into one invalid StudyInstanceUIDs value -> the study
could not be found ('studies are not available'), the viewer never rendered,
and the side-panel-header-right click timed out.

Restore master's raw concatenation for StudyInstanceUIDs (so embedded params
survive as separate query params) while still appending the customization
option separately. Only mpr2 embeds & in the UID, matching the single failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* PR comments

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/Customization.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test, visitStudyOptions } from './utils';
+
+test('should apply customization from URL query parameter', async ({ page }) => {
+  const studyInstanceUID = '2.25.96975534054447904995905761963464388233';
+
+  await visitStudyOptions(page, studyInstanceUID, {
+    customization: 'veterinaryOverlay',
+  });
+
+  const patientNameOverlayItem = page
+    .locator('[data-cy="viewport-overlay-top-left"] [title="Patient name"]')
+    .first();
+
+  await expect(patientNameOverlayItem).toBeVisible({ timeout: 60_000 });
+
+  const patientNameOverlayText = (await patientNameOverlayItem.textContent())?.trim() ?? '';
+  const patientNameValue = patientNameOverlayText.replace(/^Patient\s*/, '');
+
+  expect(patientNameValue.length).toBeGreaterThan(0);
+  expect(patientNameValue).not.toContain('[object Object]');
+  expect(patientNameValue).toMatch(/horse/i);
+});

tests/utils/index.ts

@@ -1,5 +1,8 @@
-import { visitStudy } from './visitStudy';
-import { addOHIFConfiguration, addOHIFGlobalCustomizations } from './OHIFConfiguration';
+import { visitStudy, visitStudyOptions } from './visitStudy';
+import {
+  addOHIFConfiguration,
+  addOHIFGlobalCustomizations,
+} from './OHIFConfiguration';
 import { checkForScreenshot } from './checkForScreenshot';
 import { screenShotPaths } from './screenShotPaths';
 import {
@@ -36,6 +39,7 @@ import {
 
 export {
   visitStudy,
+  visitStudyOptions,
   addOHIFConfiguration,
   addOHIFGlobalCustomizations,
   checkForScreenshot,

tests/utils/visitStudy.ts

@@ -1,4 +1,11 @@
-import { Page } from 'playwright-test-coverage';
+import type { Page } from '@playwright/test';
+
+type VisitStudyOptions = {
+  mode?: string;
+  delay?: number;
+  datasources?: string;
+  customization?: string;
+};
 
 /**
  * Visit the study
@@ -8,18 +15,44 @@ import { Page } from 'playwright-test-coverage';
  * @param delay - The delay to wait after visiting the study
  * @param datasources - the data source to load the study from
  */
-export async function visitStudy(
+export async function visitStudyOptions(
   page: Page,
   studyInstanceUID: string,
-  mode: string,
-  delay: number = 0,
-  datasources = 'ohif'
+  options: VisitStudyOptions = {}
 ) {
+  const mode = options.mode || 'viewer';
+  const resolvedDelay = options.delay ?? 0;
+  const resolvedDatasources = options.datasources || 'ohif';
+  const { customization } = options;
+
   // await page.goto(`/?resultsPerPage=100&datasources=${datasources}`);
   // await page.getByTestId(studyInstanceUID).click();
   // await page.getByRole('button', { name: mode }).click();
-  await page.goto(`/${mode}/${datasources}?StudyInstanceUIDs=${studyInstanceUID}`);
+  // studyInstanceUID may itself carry extra query params appended with `&`
+  // (e.g. `<uid>&hangingprotocolid=mpr`), so concatenate it raw rather than
+  // running it through URLSearchParams, which would percent-encode the `&`/`=`
+  // and collapse everything into a single invalid StudyInstanceUIDs value.
+  let url = `/${mode}/${resolvedDatasources}?StudyInstanceUIDs=${studyInstanceUID}`;
+  if (customization) {
+    url += `&customization=${encodeURIComponent(customization)}`;
+  }
+
+  await page.goto(url);
   await page.waitForLoadState('domcontentloaded');
   await page.waitForLoadState('networkidle');
-  await page.waitForTimeout(delay);
+  await page.waitForTimeout(resolvedDelay);
+}
+
+export async function visitStudy(
+  page: Page,
+  studyInstanceUID: string,
+  mode = 'viewer',
+  delay: number = 0,
+  datasources = 'ohif'
+) {
+  return visitStudyOptions(page, studyInstanceUID, {
+    mode,
+    delay,
+    datasources,
+  });
 }