Add Sprite Creator animation preview

Author: ToolboxAid

assets/toolbox/sprites/js/index.js

@@ -36,6 +36,10 @@ const editorHistory = {
   redoStack: [],
   undoStack: [],
 };
+const animationPreview = {
+  frameIndex: 0,
+  timerId: null,
+};
 
 function gridLabel(size) {
   return `Sprite Creator ${size} by ${size} pixel canvas`;
@@ -467,12 +471,12 @@ function renderPixelsToCanvas(canvas, paintedPixels, gridSize) {
   }
 }
 
-function renderPreview() {
+function renderPreview(frame = currentFrame()) {
   const canvas = document.querySelector("[data-sprites-preview-canvas]");
   if (!canvas) {
     return;
   }
-  renderPixelsToCanvas(canvas, editorState.paintedPixels, editorState.gridSize);
+  renderPixelsToCanvas(canvas, frame.paintedPixels, editorState.gridSize);
 }
 
 function renderFrameStrip() {
@@ -558,6 +562,63 @@ function deleteFrame() {
   updateHistoryControls();
 }
 
+function updateAnimationControls(isPlaying) {
+  const playButton = document.querySelector("[data-sprites-play-animation]");
+  const stopButton = document.querySelector("[data-sprites-stop-animation]");
+  if (playButton) {
+    playButton.disabled = isPlaying;
+  }
+  if (stopButton) {
+    stopButton.disabled = !isPlaying;
+  }
+}
+
+function animationStatusText(prefix, frameIndex = editorState.activeFrameIndex) {
+  return `${prefix} Frame ${frameIndex + 1} of ${editorState.frames.length}. Unsaved preview only.`;
+}
+
+function showAnimationFrame(frameIndex) {
+  const normalizedIndex = frameIndex % editorState.frames.length;
+  animationPreview.frameIndex = normalizedIndex;
+  renderPreview(editorState.frames[normalizedIndex]);
+  const status = document.querySelector("[data-sprites-animation-status]");
+  if (status) {
+    status.textContent = animationStatusText("Playing", normalizedIndex);
+  }
+}
+
+function stopAnimationPreview(message = "Animation preview stopped.") {
+  if (animationPreview.timerId) {
+    clearInterval(animationPreview.timerId);
+    animationPreview.timerId = null;
+  }
+  renderPreview(currentFrame());
+  updateAnimationControls(false);
+  const status = document.querySelector("[data-sprites-animation-status]");
+  if (status) {
+    status.textContent = `${message} Selected Frame ${currentFrame().frameNumber} is shown.`;
+  }
+}
+
+function playAnimationPreview() {
+  const status = document.querySelector("[data-sprites-animation-status]");
+  if (editorState.frames.length < 2) {
+    if (status) {
+      status.textContent = "Animation preview needs at least two unsaved frames.";
+    }
+    return;
+  }
+  if (animationPreview.timerId) {
+    clearInterval(animationPreview.timerId);
+  }
+  animationPreview.frameIndex = 0;
+  updateAnimationControls(true);
+  showAnimationFrame(animationPreview.frameIndex);
+  animationPreview.timerId = setInterval(() => {
+    showAnimationFrame((animationPreview.frameIndex + 1) % editorState.frames.length);
+  }, DEFAULT_FRAME_DURATION_MS);
+}
+
 function exportPreviewPng() {
   const canvas = document.querySelector("[data-sprites-preview-canvas]");
   const status = document.querySelector("[data-sprites-export-status]");
@@ -701,6 +762,18 @@ function wireFrameActions() {
   }
 }
 
+function wireAnimationActions() {
+  const playButton = document.querySelector("[data-sprites-play-animation]");
+  if (playButton) {
+    playButton.addEventListener("click", playAnimationPreview);
+  }
+
+  const stopButton = document.querySelector("[data-sprites-stop-animation]");
+  if (stopButton) {
+    stopButton.addEventListener("click", () => stopAnimationPreview());
+  }
+}
+
 function wireHistoryActions() {
   const undoButton = document.querySelector("[data-sprites-undo]");
   if (undoButton) {
@@ -741,6 +814,7 @@ wireDrawingTools();
 wirePaletteButtons();
 wireCanvasActions();
 wireFrameActions();
+wireAnimationActions();
 wireHistoryActions();
 wireZoomControls();
 wireExportButton();
@@ -751,3 +825,4 @@ setZoomLevel(editorState.zoomLevel);
 updateHistoryControls();
 renderPreview();
 renderFrameStrip();
+updateAnimationControls(false);

dev/tests/playwright/tools/SpritesToolShell.spec.mjs

@@ -271,6 +271,7 @@ test("Sprite Creator shell loads with visible tool, canvas, details, and status
     await expect(page.getByRole("heading", { level: 2, name: "Sprite Details" })).toBeVisible();
     await expect(page.locator("[data-sprites-frame-strip]")).toBeVisible();
     await expect(page.locator("[data-sprites-frame-status]")).toContainText("1 unsaved frame");
+    await expect(page.locator("[data-sprites-animation-status]")).toContainText("Animation preview is stopped");
     await expect(page.locator("[data-sprites-toolbar]")).toBeVisible();
     await expect(page.getByRole("button", { name: "Pencil tool" })).toBeEnabled();
     await expect(page.getByRole("button", { name: "Eraser tool" })).toBeEnabled();
@@ -535,3 +536,33 @@ test("Sprite Creator edits unsaved frame strip frames", async ({ page }) => {
     await server.close();
   }
 });
+
+test("Sprite Creator previews unsaved animation frames", async ({ page }) => {
+  const server = await startSpriteShellTestServer();
+  const failures = collectPageFailures(page);
+
+  try {
+    await page.goto(`${server.baseUrl}/toolbox/sprites/index.html`, { waitUntil: "networkidle" });
+
+    await page.getByRole("button", { name: "Gold editor color" }).click();
+    await spriteCell(page, 1, 1).click();
+    await page.getByRole("button", { name: "Add Frame" }).click();
+    await page.getByRole("button", { name: "Blue editor color" }).click();
+    await spriteCell(page, 1, 1).click();
+
+    await page.getByRole("button", { name: "Play Preview" }).click();
+    await expect(page.getByRole("button", { name: "Stop Preview" })).toBeEnabled();
+    await expect(page.locator("[data-sprites-animation-status]")).toContainText("Playing Frame 1");
+    await expect(page.locator("[data-sprites-animation-status]")).toContainText("Playing Frame 2", { timeout: 1500 });
+
+    await page.getByRole("button", { name: "Stop Preview" }).click();
+    await expect(page.locator("[data-sprites-animation-status]")).toContainText("Selected Frame 2 is shown");
+    await expectCenterAndPreviewPainted(page, 1, 1, "sprite-canvas-cell--blue");
+
+    expect(failures.failedRequests).toEqual([]);
+    expect(failures.pageErrors).toEqual([]);
+    expect(failures.consoleErrors).toEqual([]);
+  } finally {
+    await server.close();
+  }
+});

docs_build/dev/reports/PR_26179_CHARLIE_036-sprites-animation-preview.md

@@ -0,0 +1,63 @@
+# PR_26179_CHARLIE_036-sprites-animation-preview
+
+Team: CHARLIE
+
+Mode: Batch governance stacked feature workflow
+
+Base branch: PR_26179_CHARLIE_035-sprites-frame-editing
+
+Branch: PR_26179_CHARLIE_036-sprites-animation-preview
+
+## Summary
+
+Added unsaved animation preview playback for Sprite Creator. Play Preview cycles the right preview canvas through unsaved page-session frames, and Stop Preview returns the preview to the selected frame. No persistence, database, API, schema, save-to-library, or publishing behavior was introduced.
+
+## Branch Validation
+
+PASS
+
+- Built from `PR_26179_CHARLIE_035-sprites-frame-editing`.
+- Scope stayed limited to unsaved animation preview.
+- No DB/API/schema changes.
+- No saved product data or browser-owned authoritative product data added.
+- No start_of_day files changed.
+- ZIP package created at the requested path.
+
+## Requirement Checklist
+
+PASS - Animation preview controls added.
+
+PASS - Preview requires unsaved frame strip frames only.
+
+PASS - Play cycles through unsaved frames in the right preview canvas.
+
+PASS - Stop returns the preview to the selected frame.
+
+PASS - No persistence added.
+
+PASS - Targeted Playwright coverage updated.
+
+## Validation Lane
+
+PASS - `node --check assets/toolbox/sprites/js/index.js`
+
+PASS - `node --check dev/tests/playwright/tools/SpritesToolShell.spec.mjs`
+
+PASS - `git diff --check -- toolbox/sprites/index.html assets/toolbox/sprites/js/index.js dev/tests/playwright/tools/SpritesToolShell.spec.mjs`
+
+PASS - Runtime guard scan found no prohibited inline style/script/event-handler or stale placeholder text in touched runtime files.
+
+PASS - `npx playwright test dev/tests/playwright/tools/SpritesToolShell.spec.mjs --workers=1 --reporter=list`
+
+## Manual Validation Notes
+
+1. Open `toolbox/sprites/index.html`.
+2. Draw Frame 1.
+3. Add Frame 2 and draw a different draft.
+4. Click Play Preview and confirm the right preview cycles frames.
+5. Click Stop Preview and confirm the selected frame is shown.
+6. Confirm no save, publish, API, database, or library behavior is introduced.
+
+## ZIP
+
+`dev/workspace/zip/PR_26179_CHARLIE_036-sprites-animation-preview_delta.zip`

docs_build/dev/reports/codex_changed_files.txt

@@ -1,6 +1,6 @@
 assets/toolbox/sprites/js/index.js
 dev/tests/playwright/tools/SpritesToolShell.spec.mjs
-docs_build/dev/reports/PR_26179_CHARLIE_035-sprites-frame-editing.md
+docs_build/dev/reports/PR_26179_CHARLIE_036-sprites-animation-preview.md
 docs_build/dev/reports/codex_changed_files.txt
 docs_build/dev/reports/codex_review.diff
 toolbox/sprites/index.html