Align Sprite Editor to unified contract and fix preview rendering mismatch - PR 10.9

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,13 +1,11 @@
 model: gpt-5.3-codex
 reasoning: medium
 
-Apply PR_10_8_ASSET_BROWSER_UAT
+Apply PR_10_9_SPRITE_EDITOR_UAT
 
-- Enforce empty state messaging
-- Implement first-item auto-selection
-- Add selection highlight
+- Add first-frame auto-selection
+- Fix preview rendering mismatch
 - Enforce control enable/disable rules
 - Ensure no flicker/reset
 - Ensure workspace stability
-- Do not modify data layer
-- Do not refactor unrelated files
+- Do not modify sprite data

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Stabilize Asset Browser under unified UX contract with proper empty state, selection, and control behavior - PR 10.8
+Align Sprite Editor to unified contract and fix preview rendering mismatch - PR 10.9

docs/dev/reports/PR_10_9_sprite_editor_uat_report.md

@@ -0,0 +1,45 @@
+# PR 10.9 Sprite Editor UAT Report
+
+## Scope
+- Tool: `tools/Sprite Editor`
+- Goal: apply only PR 10.9 UAT behavior updates.
+- Constraints honored: no sprite data/schema changes, no unrelated refactor.
+
+## Implemented
+1. First-frame auto-selection
+- Added frame-selection guard helpers and enforced first-frame selection on sample-preset and project-file loads.
+- Ensured active frame index is clamped and valid before render/control sync.
+
+2. Preview rendering mismatch fix (render pipeline only)
+- Updated preview rendering to draw from `createImageFromFrame(...)` with nearest-neighbor scaling (`imageSmoothingEnabled = false`) so preview uses the same pixel transform path as export-style rendering.
+- Avoided unnecessary preview canvas dimension resets when size is unchanged to reduce redraw churn.
+
+3. Control enable/disable enforcement
+- Frame-dependent controls now require a valid selected frame:
+  - add/duplicate/delete/prev/next frame
+  - import/export frame/sheet
+  - preview play/pause/reset and FPS
+- Existing palette-edit gating remains intact.
+
+4. Stability
+- Added centralized frame-selection normalization before render cycles to prevent invalid-index resets/flicker.
+- Preserved workspace apply-state flow; no reload logic was added.
+
+5. Visible selection cue
+- Added `is-frame-selected` visual class on frame counter when a frame is selected.
+
+## Acceptance Check
+- First frame auto-selected: PASS
+- Preview render path aligned for sample-matching pixel output: PASS
+- Controls disabled without valid frame selection and enabled with selection: PASS
+- No flicker/reset behavior introduced in render loop: PASS
+- Workspace stability preserved (no reload behavior added): PASS
+
+## Files Changed
+- `tools/Sprite Editor/modules/spriteEditorApp.js`
+- `tools/Sprite Editor/spriteEditor.css`
+
+## Validation
+- `node --check tools/Sprite Editor/modules/spriteEditorApp.js` PASS
+- `npm run test:launch-smoke:games` PASS (12/12)
+- `npm run test:sample-standalone:data-flow` PASS

docs/dev/reports/REPORT_PR_10_9.md

@@ -0,0 +1,9 @@
+# REPORT_PR_10_9
+
+Sprite Editor stabilized.
+
+Fixes:
+- Selection consistency
+- Preview rendering alignment
+- Control state correctness
+- Workspace behavior

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-28T14:11:29.585Z
+Generated: 2026-04-28T14:26:54.354Z
 
 Filters: games=true, samples=false, tools=false, sampleRange=all
 

docs/pr/PR_10_9_SPRITE_EDITOR_UAT/BUILD.md

@@ -0,0 +1,25 @@
+# BUILD_PR_10_9_SPRITE_EDITOR_UAT
+
+## Behavior
+
+### Selection
+- First sprite/frame auto-selected
+- Visible highlight
+
+### Preview
+- Render output must match sample preview
+- Do not modify sprite data
+- Fix transform/render pipeline only
+
+### Controls
+- Disabled without selection
+- Enabled with selection
+
+### Stability
+- No flicker
+- No reset on interaction
+- No workspace reload
+
+## Constraints
+- No data changes
+- No feature additions

docs/pr/PR_10_9_SPRITE_EDITOR_UAT/PLAN.md

@@ -0,0 +1,17 @@
+# PLAN_PR_10_9_SPRITE_EDITOR_UAT
+
+## Purpose
+Align Sprite Editor behavior with unified UX contract and fix preview mismatch.
+
+## Scope
+- Enforce selection (sprite/frame)
+- Fix preview vs sample mismatch (render only, not data)
+- Enforce control enablement
+- Ensure no reset/flicker
+- No data changes
+
+## Acceptance
+- Sprite preview matches sample output
+- First frame auto-selected
+- Controls enabled only with selection
+- Stable inside workspace

tools/Sprite Editor/modules/spriteEditorApp.js

@@ -1032,6 +1032,44 @@ function ensureEditingEnabled(state, blockedMessage = "Select and lock a palette
   return false;
 }
 
+function getSelectedFrame(state) {
+  const frames = Array.isArray(state.project?.frames) ? state.project.frames : [];
+  if (frames.length <= 0) {
+    return null;
+  }
+  const index = clamp(state.project?.currentFrameIndex, 0, frames.length - 1, 0);
+  return frames[index] ?? null;
+}
+
+function ensureFrameSelection(state, options = {}) {
+  const preferFirstFrame = options.preferFirstFrame === true;
+  const syncPreview = options.syncPreview !== false;
+  const frames = Array.isArray(state.project?.frames) ? state.project.frames : [];
+  if (frames.length <= 0) {
+    state.project.currentFrameIndex = 0;
+    state.preview.frameIndex = 0;
+    return false;
+  }
+  let changed = false;
+  const nextCurrentIndex = preferFirstFrame
+    ? 0
+    : clamp(state.project.currentFrameIndex, 0, frames.length - 1, 0);
+  if (nextCurrentIndex !== state.project.currentFrameIndex) {
+    state.project.currentFrameIndex = nextCurrentIndex;
+    changed = true;
+  }
+  if (syncPreview) {
+    const nextPreviewIndex = state.preview.playing
+      ? clamp(state.preview.frameIndex, 0, frames.length - 1, nextCurrentIndex)
+      : nextCurrentIndex;
+    if (nextPreviewIndex !== state.preview.frameIndex) {
+      state.preview.frameIndex = nextPreviewIndex;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
 function renderPaletteSelect(state) {
   const select = state.elements.paletteSelect;
   select.innerHTML = "";
@@ -1137,6 +1175,8 @@ function hydratePaletteFromRefIfPossible(state) {
 function updateEditGateDisabledState(state) {
   const editable = isEditingEnabled(state);
   const paletteLocked = isPaletteLocked(state.project);
+  const hasFrameSelection = Boolean(getSelectedFrame(state));
+  const frameActionEnabled = editable && hasFrameSelection;
   const toolButtons = state.elements.toolButtons.querySelectorAll("[data-tool]");
 
   toolButtons.forEach((button) => {
@@ -1147,18 +1187,22 @@ function updateEditGateDisabledState(state) {
 
   state.elements.canvasWidthInput.disabled = !editable;
   state.elements.canvasHeightInput.disabled = !editable;
-  state.elements.addFrameButton.disabled = !editable;
-  state.elements.duplicateFrameButton.disabled = !editable;
-  state.elements.deleteFrameButton.disabled = !editable;
-  state.elements.prevFrameButton.disabled = !editable;
-  state.elements.nextFrameButton.disabled = !editable;
-  state.elements.importPngButton.disabled = !editable;
-  state.elements.exportPngButton.disabled = !editable;
-  state.elements.exportSheetButton.disabled = !editable;
+  state.elements.addFrameButton.disabled = !frameActionEnabled;
+  state.elements.duplicateFrameButton.disabled = !frameActionEnabled;
+  state.elements.deleteFrameButton.disabled = !frameActionEnabled;
+  state.elements.prevFrameButton.disabled = !frameActionEnabled;
+  state.elements.nextFrameButton.disabled = !frameActionEnabled;
+  state.elements.importPngButton.disabled = !frameActionEnabled;
+  state.elements.exportPngButton.disabled = !frameActionEnabled;
+  state.elements.exportSheetButton.disabled = !frameActionEnabled;
   state.elements.gridToggle.disabled = !editable;
   state.elements.onionSkinToggle.disabled = !editable;
   state.elements.undoButton.disabled = !editable || state.history.undoStack.length === 0;
   state.elements.redoButton.disabled = !editable || state.history.redoStack.length === 0;
+  state.elements.playPreviewButton.disabled = !hasFrameSelection;
+  state.elements.pausePreviewButton.disabled = !hasFrameSelection;
+  state.elements.resetPreviewButton.disabled = !hasFrameSelection;
+  state.elements.fpsInput.disabled = !hasFrameSelection;
   state.elements.color1SelectorButton.disabled = !paletteLocked || !normalizeProjectColor(state.elements.color1SelectorButton.dataset.color);
   state.elements.color2SelectorButton.disabled = !paletteLocked || !normalizeProjectColor(state.elements.color2SelectorButton.dataset.color);
   state.elements.colorPicker.disabled = true;
@@ -1387,6 +1431,7 @@ function renderHud(state) {
   state.elements.activeColorSwatch.style.backgroundSize = "12px 12px";
 
   state.elements.frameCounter.textContent = `Frame ${state.project.currentFrameIndex + 1} / ${state.project.frames.length}`;
+  state.elements.frameCounter.classList.toggle("is-frame-selected", Boolean(getSelectedFrame(state)));
   state.elements.pixelSizeValue.textContent = String(state.project.pixelSize);
   state.elements.fpsValue.textContent = String(state.preview.fps);
   state.elements.colorPicker.value = typeof state.project.activeColor === "string"
@@ -1442,31 +1487,37 @@ function renderEditor(state) {
 function renderPreview(state) {
   const { previewCanvas } = state.elements;
   const project = state.project;
+  const selectedFrame = getSelectedFrame(state);
 
   const maxTarget = 220;
   const previewScale = Math.max(1, Math.floor(maxTarget / Math.max(project.width, project.height)));
-  previewCanvas.width = project.width * previewScale;
-  previewCanvas.height = project.height * previewScale;
+  const targetWidth = project.width * previewScale;
+  const targetHeight = project.height * previewScale;
+  if (previewCanvas.width !== targetWidth) {
+    previewCanvas.width = targetWidth;
+  }
+  if (previewCanvas.height !== targetHeight) {
+    previewCanvas.height = targetHeight;
+  }
 
   const context = previewCanvas.getContext("2d");
   if (!context) {
     return;
   }
 
+  context.clearRect(0, 0, previewCanvas.width, previewCanvas.height);
   createCheckerboard(context, previewCanvas.width, previewCanvas.height, Math.max(6, Math.floor(previewScale * 1.5)));
+  if (!selectedFrame) {
+    return;
+  }
 
   const frameIndexToRender = state.preview.playing
-    ? state.preview.frameIndex
+    ? clamp(state.preview.frameIndex, 0, project.frames.length - 1, project.currentFrameIndex)
     : project.currentFrameIndex;
-
-  drawFramePixels(
-    context,
-    project.frames[frameIndexToRender],
-    project.width,
-    project.height,
-    previewScale,
-    1
-  );
+  const frameToRender = project.frames[frameIndexToRender] ?? selectedFrame;
+  const frameCanvas = createImageFromFrame(frameToRender, project.width, project.height);
+  context.imageSmoothingEnabled = false;
+  context.drawImage(frameCanvas, 0, 0, project.width, project.height, 0, 0, previewCanvas.width, previewCanvas.height);
 }
 
 function emitSpriteEditorControlReadiness(state, options = {}) {
@@ -1650,6 +1701,7 @@ function emitSpriteEditorControlReadiness(state, options = {}) {
 }
 
 function renderAll(state) {
+  ensureFrameSelection(state);
   renderHud(state);
   renderEditor(state);
   renderPreview(state);
@@ -1952,8 +2004,8 @@ async function loadProjectJson(state, file) {
 
   const validation = validateSpriteProjectAssets(state);
   setSampleSource(state, { mode: "tool", fileName: file?.name || "" });
+  ensureFrameSelection(state, { preferFirstFrame: true });
   syncControlsFromProject(state);
-  state.preview.frameIndex = state.project.currentFrameIndex;
   setStatus(state, `Loaded ${file.name} (${state.project.width}x${state.project.height}, ${state.project.frames.length} frames, ${lockMessage}, validation: ${summarizeAssetValidation(validation)}).`);
   renderAll(state);
 }
@@ -2030,6 +2082,7 @@ function applySamplePreset(state, rawPreset, sampleId, samplePresetPath, sampleT
   }
 
   state.project = ensureProjectShape(presetProject);
+  ensureFrameSelection(state, { preferFirstFrame: true });
 
   const presetAssetRegistry = extractSpriteAssetRegistryFromSamplePreset(rawPreset);
   const presetTitle = typeof sampleTitleHint === "string" && sampleTitleHint.trim()
@@ -3093,6 +3146,7 @@ export function initializeSpriteEditorApp() {
     state.preview.fps = Number.isFinite(Number(snapshot?.preview?.fps)) ? Number(snapshot.preview.fps) : DEFAULT_FPS;
     state.preview.frameIndex = Number.isFinite(Number(snapshot?.preview?.frameIndex)) ? Number(snapshot.preview.frameIndex) : state.project.currentFrameIndex;
     state.preview.playing = snapshot?.preview?.playing === true;
+    ensureFrameSelection(state);
     setSampleSource(state, { mode: "workspace" });
     validateSpriteProjectAssets(state);
     syncControlsFromProject(state);

tools/Sprite Editor/spriteEditor.css

@@ -273,6 +273,13 @@ spriteEditor.css
   color: var(--se-muted);
 }
 
+.frame-counter.is-frame-selected {
+  border: 1px solid var(--se-accent);
+  border-radius: 8px;
+  padding: 0.25rem 0.45rem;
+  background: color-mix(in srgb, var(--se-panel) 75%, var(--se-accent));
+}
+
 .hint-text {
   margin: 0.45rem 0 0;
   color: var(--se-muted);