Add persistent Sprite Editor sample source details and fix sample 1414 preset preview layering/positioning

DavidQ · DavidQ · commit 631fef5b9273 · 2026-04-24T12:16:49.000-04:00
diff --git a/samples/index.render.js b/samples/index.render.js
@@ -116,7 +116,7 @@ function buildRoundtripLinks(sample, toolRegistryMap) {
     let label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
     if (shouldUsePresetRoundtrip(sample, toolId)) {
       const presetPath = getRoundtripPresetPath(sample, toolId);
-      href = `${baseHref}?sampleId=${encodeURIComponent(sample.id)}&samplePresetPath=${encodeURIComponent(presetPath)}`;
+      href = `${baseHref}?sampleId=${encodeURIComponent(sample.id)}&sampleTitle=${encodeURIComponent(sample.title || "")}&samplePresetPath=${encodeURIComponent(presetPath)}`;
     }
 
     links.push({ toolId, href, label });
diff --git a/samples/phase-14/1414/TextureSpritePreprocessPipelineScene.js b/samples/phase-14/1414/TextureSpritePreprocessPipelineScene.js
@@ -1,21 +1,79 @@
-import { Scene } from '/src/engine/scene/index.js'; import { drawFrame, drawPanel } from '/src/engine/debug/index.js'; import { Theme, ThemeTokens } from '/src/engine/theme/index.js'; import { TexturePreprocessPipeline } from '/tools/shared/pipeline/index.js'; import { drawSpriteProjectFrame, loadSpriteProjectPreset } from '/samples/shared/spritePresetRuntime.js';
+import { Scene } from "/src/engine/scene/index.js";
+import { drawFrame, drawPanel } from "/src/engine/debug/index.js";
+import { Theme, ThemeTokens } from "/src/engine/theme/index.js";
+import { TexturePreprocessPipeline } from "/tools/shared/pipeline/index.js";
+import { drawSpriteProjectFrame, loadSpriteProjectPreset } from "/samples/shared/spritePresetRuntime.js";
+
 const theme = new Theme(ThemeTokens);
-const SPRITE_PRESET_PATH = '/samples/phase-14/1414/sample-1414-sprite-editor.json';
+const SPRITE_PRESET_PATH = "/samples/phase-14/1414/sample-1414-sprite-editor.json";
+
 export default class TextureSpritePreprocessPipelineScene extends Scene {
-  constructor() { super(); this.pipeline = new TexturePreprocessPipeline(); this.texture = null; this.status = 'Preprocess a texture record.'; this.spriteProject = null; this.spriteStatus = 'loading'; this.spriteError = ''; void this.loadSpriteProject(); }
-  async loadSpriteProject() { try { this.spriteProject = await loadSpriteProjectPreset(SPRITE_PRESET_PATH); this.spriteStatus = 'loaded'; this.spriteError = ''; } catch (error) { this.spriteProject = null; this.spriteStatus = 'fallback'; this.spriteError = error instanceof Error ? error.message : 'unknown preset error'; } }
-  run() { this.texture = this.pipeline.run({ width: 64, height: 32 }); this.status = 'Texture preprocessing complete.'; }
+  constructor() {
+    super();
+    this.pipeline = new TexturePreprocessPipeline();
+    this.texture = null;
+    this.status = "Preprocess a texture record.";
+    this.spriteProject = null;
+    this.spriteStatus = "loading";
+    this.spriteError = "";
+    void this.loadSpriteProject();
+  }
+
+  async loadSpriteProject() {
+    try {
+      this.spriteProject = await loadSpriteProjectPreset(SPRITE_PRESET_PATH);
+      this.spriteStatus = "loaded";
+      this.spriteError = "";
+    } catch (error) {
+      this.spriteProject = null;
+      this.spriteStatus = "fallback";
+      this.spriteError = error instanceof Error ? error.message : "unknown preset error";
+    }
+  }
+
+  run() {
+    this.texture = this.pipeline.run({ width: 64, height: 32 });
+    this.status = "Texture preprocessing complete.";
+  }
+
   render(renderer) {
-    const presetStatus = this.spriteStatus === 'loaded'
-      ? 'Sprite preset loaded from sample-1414-sprite-editor.json'
-      : this.spriteStatus === 'loading'
-        ? 'Loading shared sprite preset...'
-        : `Sprite preset unavailable (${this.spriteError || 'using pipeline-only view'})`;
-    drawFrame(renderer, theme, ['Engine Sample 1414', 'Texture preprocessing normalizes visual content in one centralized step.', 'This sample and Sprite Editor load the same sample-1414-sprite-editor.json source.', this.status, presetStatus]);
-    drawPanel(renderer, 120, 220, 540, 220, 'Texture Output', [`Width: ${this.texture?.width ?? 0}`, `Height: ${this.texture?.height ?? 0}`, `Padded: ${this.texture?.padded ?? false}`, `Atlas Ready: ${this.texture?.atlasReady ?? false}`, `Preset Frames: ${this.spriteProject?.frames?.length ?? 0}`]);
-    if (this.spriteProject) {
-      drawSpriteProjectFrame(renderer, this.spriteProject, 0, { x: 690, y: 260, pixelSize: 4 });
-      drawPanel(renderer, 660, 220, 240, 220, 'Sprite Preset Preview', ['Frame source: sample-1414-sprite-editor.json', `Size: ${this.spriteProject.width}x${this.spriteProject.height}`, 'Edit in Sprite Editor, then relaunch sample.']);
+    const presetStatus = this.spriteStatus === "loaded"
+      ? "Sprite preset loaded from sample-1414-sprite-editor.json"
+      : this.spriteStatus === "loading"
+        ? "Loading shared sprite preset..."
+        : `Sprite preset unavailable (${this.spriteError || "using pipeline-only view"})`;
+
+    drawFrame(renderer, theme, [
+      "Engine Sample 1414",
+      "Texture preprocessing normalizes visual content in one centralized step.",
+      "This sample and Sprite Editor load the same sample-1414-sprite-editor.json source.",
+      this.status,
+      presetStatus
+    ]);
+
+    drawPanel(renderer, 120, 220, 540, 220, "Texture Output", [
+      `Width: ${this.texture?.width ?? 0}`,
+      `Height: ${this.texture?.height ?? 0}`,
+      `Padded: ${this.texture?.padded ?? false}`,
+      `Atlas Ready: ${this.texture?.atlasReady ?? false}`,
+      `Preset Frames: ${this.spriteProject?.frames?.length ?? 0}`
+    ]);
+
+    if (!this.spriteProject) {
+      return;
     }
+
+    const previewPanel = { x: 660, y: 220, width: 240, height: 220 };
+    drawPanel(renderer, previewPanel.x, previewPanel.y, previewPanel.width, previewPanel.height, "Sprite Preset Preview", [
+      "Frame source: sample-1414-sprite-editor.json",
+      `Size: ${this.spriteProject.width}x${this.spriteProject.height}`,
+      "Edit in Sprite Editor, then relaunch sample."
+    ]);
+
+    drawSpriteProjectFrame(renderer, this.spriteProject, 0, {
+      x: previewPanel.x + 16,
+      y: previewPanel.y + 98,
+      pixelSize: 4
+    });
   }
 }
diff --git a/tools/Sprite Editor/index.html b/tools/Sprite Editor/index.html
@@ -181,6 +181,7 @@ <h3>Recent</h3>
         <details id="rightPanelStatus" class="panel-accordion">
           <summary class="panel-accordion__summary"><h2>Status</h2></summary>
           <div id="statusPanel" class="panel-accordion__body">
+            <p id="sampleSourceDetailText" class="status-text">Source details: Tool mode.</p>
             <p id="statusText" class="status-text">Ready.</p>
             <p id="remediationSummaryText" class="status-text">No remediation actions available.</p>
             <div class="io-controls">
diff --git a/tools/Sprite Editor/modules/spriteEditorApp.js b/tools/Sprite Editor/modules/spriteEditorApp.js
@@ -731,6 +731,14 @@ function setSampleSource(state, source = {}) {
   };
 }
 
+function buildSampleSourceDetailLabel(source = {}) {
+  const summary = buildSampleSourceLabel(source);
+  const samplePresetPath = typeof source.samplePresetPath === "string" ? source.samplePresetPath.trim() : "";
+  const fileName = typeof source.fileName === "string" ? source.fileName.trim() : "";
+  const detail = samplePresetPath || fileName;
+  return detail ? `${summary} (${detail})` : summary;
+}
+
 function isPaletteSelected(project) {
   return Boolean(project.paletteRef?.id && project.paletteRef.id !== NO_PALETTE_ID);
 }
@@ -982,6 +990,7 @@ function updateToolStateText(state) {
   const toolName = state.projectTool[0].toUpperCase() + state.projectTool.slice(1);
   state.elements.toolStateText.textContent = `Tool: ${toolName}`;
   state.elements.sampleSourceText.textContent = `Source: ${buildSampleSourceLabel(state.sampleSource)}`;
+  state.elements.sampleSourceDetailText.textContent = `Source details: ${buildSampleSourceDetailLabel(state.sampleSource)}.`;
   state.elements.activeColorText.textContent = `Color: ${state.project.activeColor ?? "none"}`;
   state.elements.frameStateText.textContent = `Frame: ${state.project.currentFrameIndex + 1} / ${state.project.frames.length}`;
   state.elements.toggleStateText.textContent = `Grid: ${state.project.showGrid ? "On" : "Off"} | Onion: ${state.project.onionSkin ? "On" : "Off"}`;
@@ -1486,7 +1495,7 @@ function extractSpriteAssetRegistryFromSamplePreset(rawPreset) {
   return null;
 }
 
-function applySamplePreset(state, rawPreset, sampleId, samplePresetPath) {
+function applySamplePreset(state, rawPreset, sampleId, samplePresetPath, sampleTitleHint = "") {
   const presetProject = extractSpriteProjectFromSamplePreset(rawPreset);
   if (!presetProject || typeof presetProject !== "object") {
     throw new Error("Preset payload did not include a sprite project.");
@@ -1495,9 +1504,11 @@ function applySamplePreset(state, rawPreset, sampleId, samplePresetPath) {
   state.project = ensureProjectShape(presetProject);
 
   const presetAssetRegistry = extractSpriteAssetRegistryFromSamplePreset(rawPreset);
-  const presetTitle = typeof rawPreset?.title === "string"
-    ? rawPreset.title
-    : (typeof rawPreset?.payload?.title === "string" ? rawPreset.payload.title : "");
+  const presetTitle = typeof sampleTitleHint === "string" && sampleTitleHint.trim()
+    ? sampleTitleHint.trim()
+    : (typeof rawPreset?.title === "string"
+      ? rawPreset.title
+      : (typeof rawPreset?.payload?.title === "string" ? rawPreset.payload.title : ""));
   state.assetRegistry = presetAssetRegistry
     ? sanitizeAssetRegistry(presetAssetRegistry)
     : createAssetRegistry({ projectId: "sprite-project" });
@@ -1533,16 +1544,31 @@ async function tryLoadPresetFromQuery(state) {
     return false;
   }
   const sampleId = String(searchParams.get("sampleId") || "").trim();
+  const sampleTitle = normalizeSampleLabel(searchParams.get("sampleTitle") || "");
+  setSampleSource(state, {
+    mode: "sample",
+    sampleId,
+    sampleTitle,
+    samplePresetPath
+  });
+  renderHud(state);
   try {
     const presetUrl = new URL(samplePresetPath, window.location.href);
     const response = await fetch(presetUrl.toString(), { cache: "no-store" });
     if (!response.ok) {
       throw new Error(`Preset request failed (${response.status}).`);
     }
     const rawPreset = await response.json();
-    applySamplePreset(state, rawPreset, sampleId, samplePresetPath);
+    applySamplePreset(state, rawPreset, sampleId, samplePresetPath, sampleTitle);
     return true;
   } catch (error) {
+    setSampleSource(state, {
+      mode: "sample",
+      sampleId,
+      sampleTitle,
+      samplePresetPath
+    });
+    renderHud(state);
     setStatus(state, `Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);
     return false;
   }
@@ -2189,6 +2215,7 @@ export function initializeSpriteEditorApp() {
       applyRemediationButton: getRequiredElement("applyRemediationButton"),
       saveAssetRegistryButton: getRequiredElement("saveAssetRegistryButton"),
       saveProjectButton: getRequiredElement("saveProjectButton"),
+      sampleSourceDetailText: getRequiredElement("sampleSourceDetailText"),
       sampleSourceText: getRequiredElement("sampleSourceText"),
       statusBarText: getRequiredElement("statusBarText"),
       statusText: getRequiredElement("statusText"),
diff --git a/tools/shared/platformShell.js b/tools/shared/platformShell.js
@@ -783,10 +783,15 @@ function initPlatformShell() {
 
   const currentToolId = document.body.dataset.toolId || "";
   const currentTool = currentToolId ? getToolById(currentToolId) : null;
+  const searchParams = typeof window !== "undefined"
+    ? new URLSearchParams(window.location.search)
+    : new URLSearchParams();
+  const launchedFromSamplePreset = searchParams.has("samplePresetPath");
 
   if (currentToolId) {
     workspaceController = createWorkspaceSystemController({
       toolId: currentToolId,
+      skipInitialToolStateApply: launchedFromSamplePreset,
       onChange(payload) {
         const manifest = payload?.manifest || {};
         const uiStateKey = JSON.stringify({
diff --git a/tools/shared/projectSystem.js b/tools/shared/projectSystem.js
@@ -71,6 +71,7 @@ export function createWorkspaceSystemController(options = {}) {
   const toolId = safeString(options.toolId, "");
   const toolEntry = getToolById(toolId);
   const isReadOnlyTool = toolEntry?.readOnly === true;
+  const skipInitialToolStateApply = options.skipInitialToolStateApply === true;
   const onChange = typeof options.onChange === "function" ? options.onChange : () => {};
   const onStatus = typeof options.onStatus === "function" ? options.onStatus : () => {};
   const adapter = () => getProjectAdapter(toolId);
@@ -80,7 +81,7 @@ export function createWorkspaceSystemController(options = {}) {
     baselineHash: "",
     lastObservedHash: "",
     adapterReady: false,
-    appliedInitialState: false
+    appliedInitialState: skipInitialToolStateApply
   };
 
   function serializeForDirtyComparison(manifest) {

Original file line number	Diff line number	Diff line change
`@@ -116,7 +116,7 @@ function buildRoundtripLinks(sample, toolRegistryMap) {`
`116`	`116`	let label = `Open ${normalize(tool.displayName) \|\| normalize(tool.name) \|\| toolId}`;
`117`	`117`	`if (shouldUsePresetRoundtrip(sample, toolId)) {`
`118`	`118`	`const presetPath = getRoundtripPresetPath(sample, toolId);`
`119`		- href = `${baseHref}?sampleId=${encodeURIComponent(sample.id)}&samplePresetPath=${encodeURIComponent(presetPath)}`;
	`119`	+ href = `${baseHref}?sampleId=${encodeURIComponent(sample.id)}&sampleTitle=${encodeURIComponent(sample.title \|\| "")}&samplePresetPath=${encodeURIComponent(presetPath)}`;
`120`	`120`	`}`
`121`	`121`
`122`	`122`	`links.push({ toolId, href, label });`