Load Palette Manager V2 sample preset JSON from launch URL into active palette state - PR_26124_076-palette-manager-url-preset-load

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,22 +1,25 @@
-# Codex Commands - PR_26124_075-palette-browser-launch-registration-fix
+# Codex Commands - PR_26124_076-palette-manager-url-preset-load
 
 ```bash
-npx @openai/codex run --model gpt-5.5 --reasoning high "Run full workflow for PR_26124_075-palette-browser-launch-registration-fix. Follow PROJECT_INSTRUCTIONS.md exactly."
+npx @openai/codex run --model gpt-5.5 --reasoning high "Run full workflow for PR_26124_076-palette-manager-url-preset-load. Follow PROJECT_INSTRUCTIONS.md exactly."
 ```
 
 ## Validation Commands
 
 ```bash
-node --input-type=module <sample metadata registry validation>
-node --input-type=module <targeted Samples index launch validation>
+node --check tools/palette-manager-v2/main.js
+node --check tools/palette-manager-v2/modules/PaletteManagerApp.js
+node --check tools/palette-manager-v2/modules/PaletteValidationService.js
+node tests/tools/PaletteManagerV2Baseline.test.mjs
+node --input-type=module <targeted Palette Manager V2 URL preset validation>
 git diff --check
 npm run test:workspace-v2
 npm run codex:review-artifacts
 ```
 
 ## Playwright
 
-Targeted Samples index launch validation confirms palette-backed samples no longer render `Tool "palette-browser" is not registered in toolRegistry.` and their launch links resolve to Palette Manager V2.
+Targeted Palette Manager V2 validation confirms the tool baseline still loads and that a `samplePresetPath` URL loads sample palette JSON into active Palette Manager V2 state.
 
 `npm run test:workspace-v2` failed because `package.json` does not define the `test:workspace-v2` script.
 

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Fix Palette Manager V2 sample launch registration id - PR_26124_075-palette-browser-launch-registration-fix
+Load Palette Manager V2 sample presets from URL params - PR_26124_076-palette-manager-url-preset-load

docs/dev/reports/PR_26124_076_report.md

@@ -0,0 +1,36 @@
+# PR_26124_076 Palette Manager URL Preset Load Report
+
+## Scope
+- `tools/palette-manager-v2/main.js`
+- `tools/palette-manager-v2/modules/PaletteManagerApp.js`
+- `tools/palette-manager-v2/modules/PaletteValidationService.js`
+- PR workflow docs and review artifacts.
+
+## Result
+Palette Manager V2 reads `samplePresetPath` on startup, fetches the referenced sample palette JSON, validates through the same import path used by manual JSON import, and renders the loaded swatches in User Palette and Palette JSON.
+
+## Data Handling
+- Direct sample palette documents are accepted when they contain top-level `swatches`.
+- Swatches are cloned before normalization.
+- Missing direct swatch `source` values are filled from direct palette metadata such as `sourceId`.
+- The incoming sample JSON object is not mutated.
+- Existing wrapped `tools.palette-browser` import/export JSON remains supported.
+
+## Validation
+- PASS: changed JavaScript syntax checks.
+- PASS: existing Palette Manager V2 Playwright baseline.
+- PASS: targeted URL preset validation for sample `0219`.
+- PASS: targeted invalid URL preset failure validation.
+- PASS: `git diff --check`.
+- FAIL: `npm run test:workspace-v2` because `package.json` does not define `test:workspace-v2`.
+- SKIPPED: full samples smoke test by instruction.
+
+## Manual Validation
+Open Palette Manager V2 with:
+
+`/tools/palette-manager-v2/index.html?sampleId=0219&sampleTitle=Sprite%20Atlas%20Image%20Rendering&samplePresetPath=/samples/phase-02/0219/sample.0219.palette.json`
+
+Expected:
+- User Palette shows the six sample swatches.
+- Palette JSON shows `tools.palette-browser.swatches`.
+- Status indicates the sample preset loaded.

docs/dev/reports/codex_changed_files.txt

@@ -1,11 +1,16 @@
 # git status --short
-M  docs/dev/codex_commands.md
-M  docs/dev/commit_comment.txt
-A  docs/dev/reports/PR_26124_075_report.md
-A  docs/pr/PR_26124_075-palette-browser-launch-registration-fix/APPLY_PR.md
-A  docs/pr/PR_26124_075-palette-browser-launch-registration-fix/BUILD_PR.md
-A  docs/pr/PR_26124_075-palette-browser-launch-registration-fix/PLAN_PR.md
-M  samples/metadata/samples.index.metadata.json
+M docs/dev/codex_commands.md
+ M docs/dev/commit_comment.txt
+ M tools/palette-manager-v2/main.js
+ M tools/palette-manager-v2/modules/PaletteManagerApp.js
+ M tools/palette-manager-v2/modules/PaletteValidationService.js
+?? docs/dev/reports/PR_26124_076_report.md
+?? docs/pr/PR_26124_076-palette-manager-url-preset-load/
 
 # git diff --stat
-(no output)
+docs/dev/codex_commands.md                         | 13 +++--
+ docs/dev/commit_comment.txt                        |  2 +-
+ tools/palette-manager-v2/main.js                   | 67 ++++++++++++++++++++++
+ .../modules/PaletteManagerApp.js                   | 13 +++--
+ .../modules/PaletteValidationService.js            | 29 +++++++++-
+ 5 files changed, 109 insertions(+), 15 deletions(-)

docs/dev/reports/codex_review.diff

@@ -0,0 +1,40 @@
+# APPLY_PR - PR_26124_076-palette-manager-url-preset-load
+
+## Summary
+Palette Manager V2 now loads sample palette JSON from a `samplePresetPath` URL parameter during startup.
+
+## Applied Changes
+- Added startup URL parameter handling in `tools/palette-manager-v2/main.js`.
+- Fetches `samplePresetPath` when present and reports visible fetch/JSON failures.
+- Reuses `PaletteManagerApp.importPaletteDocument` for URL-loaded preset JSON.
+- Extended `PaletteValidationService.extractImportedPaletteDocument` to accept:
+  - existing wrapped `tools.palette-browser` import/export JSON,
+  - direct sample palette documents with top-level `swatches`.
+- Direct sample palette swatches are cloned and given missing `source` from palette metadata before validation.
+- Manual Import JSON behavior remains unchanged.
+
+## Runtime/Data Result
+- Launching Palette Manager V2 with sample `0219` URL parameters loads `sample.0219.palette.json` into active Palette Manager V2 memory.
+- User Palette renders the loaded sample swatches.
+- Palette JSON renders the loaded swatches under `tools.palette-browser`.
+- Incoming sample JSON is not mutated.
+- Failed fetch or schema validation shows a clear Validation/Error Viewer message and does not silently fallback.
+
+## Validation
+- PASS: `node --check tools/palette-manager-v2/main.js`
+- PASS: `node --check tools/palette-manager-v2/modules/PaletteManagerApp.js`
+- PASS: `node --check tools/palette-manager-v2/modules/PaletteValidationService.js`
+- PASS: `node tests/tools/PaletteManagerV2Baseline.test.mjs`
+- PASS: targeted Palette Manager V2 URL preset validation for sample `0219`
+- PASS: targeted invalid `samplePresetPath` validation shows fetch failure
+- PASS: `git diff --check`
+- FAIL: `npm run test:workspace-v2` is unavailable because `package.json` does not define a `test:workspace-v2` script.
+- SKIPPED: full samples smoke test, by instruction.
+
+## Manual Test
+1. Open `/tools/palette-manager-v2/index.html?sampleId=0219&sampleTitle=Sprite%20Atlas%20Image%20Rendering&samplePresetPath=/samples/phase-02/0219/sample.0219.palette.json`.
+2. Confirm User Palette contains six sample swatches.
+3. Confirm Palette JSON shows `tools.palette-browser.swatches`.
+4. Confirm status says the sample preset loaded.
+5. Open `/tools/palette-manager-v2/index.html?samplePresetPath=/samples/missing-palette.json`.
+6. Confirm Validation/Error Viewer shows a sample preset fetch failure.

docs/pr/PR_26124_076-palette-manager-url-preset-load/APPLY_PR.md

@@ -0,0 +1,40 @@
+# BUILD_PR - PR_26124_076-palette-manager-url-preset-load
+
+## Purpose
+Add one scoped Palette Manager V2 startup path that loads and validates sample palette JSON from the `samplePresetPath` URL parameter.
+
+## Scope
+- `tools/palette-manager-v2/main.js`
+- `tools/palette-manager-v2/modules/PaletteManagerApp.js`
+- `tools/palette-manager-v2/modules/PaletteValidationService.js`
+- Required PR workflow docs and review artifacts.
+
+## Implementation
+1. Add startup URL parameter handling in `main.js`.
+2. If `samplePresetPath` is absent, preserve current startup behavior.
+3. If `samplePresetPath` is present:
+   - fetch the JSON path,
+   - reject failed fetches with a visible validation/error message,
+   - reject invalid JSON with a visible validation/error message,
+   - pass parsed JSON to `PaletteManagerApp.importPaletteDocument`.
+4. Extend `PaletteValidationService.extractImportedPaletteDocument` so it still accepts wrapped `tools.palette-browser` import JSON and also accepts direct sample palette documents with top-level `swatches`.
+5. For direct sample palette documents, clone swatches and populate missing `source` from direct palette metadata before validation; do not mutate the incoming JSON object.
+6. Add optional status text parameters to import/reject methods only where needed for startup preset messages.
+7. Preserve manual Import JSON behavior and existing export shape.
+
+## Boundaries
+- Do not modify workspace/toolState behavior.
+- Do not touch sample JSON.
+- Do not modify `tools/shared`.
+- Do not add fallback/default data.
+- Do not add dependencies.
+- Do not modify Palette Manager CSS or layout.
+- Do not run the full samples smoke test.
+
+## Validation
+- Syntax check changed JavaScript files.
+- Run targeted Palette Manager V2 Playwright baseline test if present.
+- Run targeted URL preset load validation for sample `0219`.
+- Run `npm run test:workspace-v2`.
+- Run `git diff --check`.
+- Skip the full samples smoke test.

docs/pr/PR_26124_076-palette-manager-url-preset-load/BUILD_PR.md

@@ -0,0 +1,41 @@
+# PLAN_PR - PR_26124_076-palette-manager-url-preset-load
+
+## Goal
+Load a Palette Manager V2 sample preset when the tool opens with a `samplePresetPath` URL parameter.
+
+## Scope
+- `tools/palette-manager-v2/main.js`
+- `tools/palette-manager-v2/modules/PaletteManagerApp.js`
+- `tools/palette-manager-v2/modules/PaletteValidationService.js`
+- Required PR workflow docs and review artifacts.
+
+## Boundaries
+- Do not modify workspace/toolState behavior.
+- Do not touch sample JSON.
+- Do not modify `tools/shared`.
+- Do not add fallback/default data.
+- Do not add dependencies.
+- Do not run the full samples smoke test.
+
+## Implementation Plan
+1. Read `URLSearchParams` during Palette Manager V2 startup.
+2. When `samplePresetPath` exists, fetch that JSON path.
+3. Reject fetch, JSON parse, and schema failures with clear Validation/Error Viewer messages.
+4. Reuse the same Palette Manager import validation path used by manual JSON import.
+5. Accept direct sample palette documents with top-level `swatches` by normalizing cloned swatches into the active Palette Manager swatch contract without mutating the incoming JSON.
+6. Render User Palette, Palette JSON, and validation state from the loaded preset.
+7. Preserve manual Import JSON behavior.
+
+## Playwright
+- Targeted Palette Manager V2 Playwright validates baseline tool loading and existing palette behaviors.
+- Targeted URL preset validation loads sample `0219` through `samplePresetPath` and checks that User Palette and Palette JSON reflect the fetched preset.
+- Expected pass behavior: sample preset swatches render in Palette Manager V2 with no runtime errors.
+- Expected fail behavior: fetch or validation failure appears in the Validation/Error Viewer and the app does not silently fallback.
+- Default requested gate: `npm run test:workspace-v2`
+
+## Manual Validation
+1. Open `/tools/palette-manager-v2/index.html?sampleId=0219&sampleTitle=Sprite%20Atlas%20Image%20Rendering&samplePresetPath=/samples/phase-02/0219/sample.0219.palette.json`.
+2. Confirm User Palette contains the sample palette swatches.
+3. Confirm Palette JSON contains `tools.palette-browser.swatches`.
+4. Confirm status indicates the sample preset loaded.
+5. Open the same tool with an invalid `samplePresetPath` and confirm a clear validation/error message is shown.

docs/pr/PR_26124_076-palette-manager-url-preset-load/PLAN_PR.md

@@ -18,6 +18,72 @@ function reportBootstrapError(error) {
   console.error(error);
 }
 
+function normalizeSamplePresetPath(samplePresetPath) {
+  const cleanPath = typeof samplePresetPath === "string"
+    ? samplePresetPath.trim().replace(/\\/g, "/")
+    : "";
+  if (!cleanPath || cleanPath.includes("..") || !cleanPath.startsWith("/samples/")) {
+    return "";
+  }
+  return cleanPath;
+}
+
+function getSamplePresetLabel(searchParams, samplePresetPath) {
+  const sampleId = (searchParams.get("sampleId") || "").trim();
+  const sampleTitle = (searchParams.get("sampleTitle") || "").trim();
+  if (sampleId && sampleTitle) {
+    return `sample ${sampleId} (${sampleTitle})`;
+  }
+  if (sampleId) {
+    return `sample ${sampleId}`;
+  }
+  if (sampleTitle) {
+    return sampleTitle;
+  }
+  return samplePresetPath;
+}
+
+async function loadSamplePresetFromUrl(app) {
+  const searchParams = new URLSearchParams(window.location.search);
+  const samplePresetPath = searchParams.get("samplePresetPath");
+  if (!samplePresetPath) {
+    return;
+  }
+
+  const presetPath = normalizeSamplePresetPath(samplePresetPath);
+  if (!presetPath) {
+    app.rejectImport([`samplePresetPath is invalid: ${samplePresetPath}`], "Sample preset load failed.");
+    return;
+  }
+
+  let response;
+  try {
+    response = await fetch(presetPath, { cache: "no-store" });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    app.rejectImport([`Sample preset fetch failed for ${presetPath}: ${message}`], "Sample preset load failed.");
+    return;
+  }
+
+  if (!response.ok) {
+    app.rejectImport([`Sample preset fetch failed (${response.status}) for ${presetPath}.`], "Sample preset load failed.");
+    return;
+  }
+
+  let documentValue;
+  try {
+    documentValue = await response.json();
+  } catch {
+    app.rejectImport([`Sample preset is not valid JSON: ${presetPath}.`], "Sample preset load failed.");
+    return;
+  }
+
+  app.importPaletteDocument(documentValue, {
+    failureStatus: "Sample preset load failed.",
+    successStatus: `Loaded ${getSamplePresetLabel(searchParams, presetPath)} palette preset.`
+  });
+}
+
 try {
   const app = new PaletteManagerApp({
     documentRef: document,
@@ -27,6 +93,7 @@ try {
   });
   app.init();
   window.paletteManagerV2App = app.getPublicApi();
+  void loadSamplePresetFromUrl(app);
 } catch (error) {
   reportBootstrapError(error);
 }

tools/palette-manager-v2/main.js

@@ -998,15 +998,15 @@ export class PaletteManagerApp {
     });
   }
 
-  rejectImport(errors) {
-    this.setActionState(errors, "Import rejected.");
+  rejectImport(errors, status = "Import rejected.") {
+    this.setActionState(errors, status);
   }
 
-  importPaletteDocument(documentValue) {
+  importPaletteDocument(documentValue, options = {}) {
     const importResult = this.validator.extractImportedPaletteDocument(documentValue);
     if (importResult.errors.length > 0) {
-      this.setActionState(importResult.errors, "Import rejected.");
-      return;
+      this.setActionState(importResult.errors, sanitizeText(options.failureStatus) || "Import rejected.");
+      return false;
     }
 
     this.state.userSwatches = importResult.swatches.map(cloneSwatch);
@@ -1015,7 +1015,8 @@ export class PaletteManagerApp {
     this.checkedUserSwatchIndexes.clear();
     this.editorControl.clearForm();
     this.resetHistorySnapshot();
-    this.setActionState([], `Imported ${this.state.userSwatches.length} user swatches.`);
+    this.setActionState([], sanitizeText(options.successStatus) || `Imported ${this.state.userSwatches.length} user swatches.`);
+    return true;
   }
 
   preparePaletteDocument(blockedStatus) {