Add frame state contextual help and remove hardcoded idle frame naming - PR_26133_047-frame-state-help-and-frame-id-generation-fix

Author: DavidQ

docs/dev/reports/playwright_v8_coverage_report.md

@@ -1,6 +1,6 @@
-# PR_26133_046 Playwright V8 Coverage Report
+# PR_26133_047 Playwright V8 Coverage Report
 
-Task: PR_26133_046-object-vector-frame-palette-and-shape-action-cleanup
+Task: PR_26133_047-frame-state-help-and-frame-id-generation-fix
 Date: 2026-05-15
 
 ## Result
@@ -37,4 +37,4 @@ PASS - Coverage reporting was generated during `npm run test:workspace-v2`.
 
 ## PR-Specific Note
 
-The Workspace V2 run exercised Object Vector Studio V2 frame creation/duplication/deletion/reordering, palette sort controls, Paint/Stroke mode application through canvas clicks, and icon-only shape order/group controls under Objects.
+The Workspace V2 run exercised Object Vector Studio V2 state selection, contextual state help text, legacy state/frame manifest loading, generic frame duplication, playback, runtime preview, and export paths.

docs/dev/reports/playwright_workspace_v2_results.md

@@ -1,6 +1,6 @@
-# PR_26133_046 Workspace V2 Playwright Results
+# PR_26133_047 Workspace V2 Playwright Results
 
-Task: PR_26133_046-object-vector-frame-palette-and-shape-action-cleanup
+Task: PR_26133_047-frame-state-help-and-frame-id-generation-fix
 Date: 2026-05-15
 
 ## Result
@@ -14,21 +14,14 @@ PASS - `npm run test:workspace-v2` completed successfully.
 
 ## PR-Specific Coverage
 
-- Verified Delete Frame removes a selected frame and refuses to delete the final remaining frame.
-- Verified generated and canonical Asteroids frame IDs use `frame-x` instead of state-prefixed frame IDs.
-- Verified Left/Right frame controls and Frame Earlier/Frame Later reorder frames through the same sequence-safe path.
-- Verified palette sort buttons show ascending/descending caret indicators and toggle sort direction.
-- Verified Paint/Stroke buttons switch action mode without changing selected shape style.
-- Verified canvas clicks still apply the currently selected Paint/Stroke color.
-- Verified shape order/group actions moved under Objects and render as icon-only controls with titles.
+- Verified the Object Vector Studio V2 frame state dropdown renders beside a `?` help button.
+- Verified the `idle` help text title is `Default stationary state.` and `No movement or action animation active.`
+- Verified the `move` help text title is `Movement/action state.` and `Used for thrusting, walking, flying, or active movement visuals.`
+- Verified new schema-valid state IDs include `move` while legacy `thrust` manifests still load.
+- Verified duplicate frame generation uses generic `frame-x` IDs and does not continue legacy `idle-frame-x` naming.
+- Verified a legacy `idle-frame-1` import duplicates into `frame-1`.
 
 ## Additional Validation
 
-- Targeted Playwright check passed for Object Vector Studio layout, animation frame controls, and Asteroids runtime rendering.
-- Node syntax checks passed for `tools/object-vector-studio-v2/js/ToolStarterApp.js` and `tools/object-vector-studio-v2/js/bootstrap.js`.
-- Node schema-service check passed for `games/Asteroids/game.manifest.json` and its workspace manifest.
+- Targeted Playwright check passed for `supports Object Vector Studio V2 animation states and frame timeline foundation`.
 - `git diff --check` passed.
-
-## Frame Control Note
-
-`Left` and `Right` are directional aliases for the same frame-order mutation used by `Frame Earlier` and `Frame Later`; all four controls preserve the selected state linkage and only change frame order.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -3982,8 +3982,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
                     ]
                   }
                 ],
-                id: "thrust",
-                name: "Thrust"
+                id: "move",
+                name: "Move"
               }
             ],
             tags: []
@@ -3997,6 +3997,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator('[data-object-id="object.animation.ship-template"]')).toHaveAttribute("aria-pressed", "true");
       await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-state-id='idle']")).toHaveCount(1);
       await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-frame-id='frame-1']")).toHaveAttribute("aria-pressed", "true");
+      await expect(page.locator("#objectVectorStudioV2StateSelect")).toHaveValue("idle");
+      await expect(page.locator("#objectVectorStudioV2StateHelpButton")).toHaveAttribute("title", "Default stationary state.\nNo movement or action animation active.");
       await expect(page.locator("#objectVectorStudioV2JsonDetails")).toContainText('"id": "idle"');
       await expect(page.locator("#objectVectorStudioV2ObjectDetails")).not.toContainText("Selected Shape");
       await expect(page.locator("#objectVectorStudioV2ObjectDetails")).not.toContainText("ship-template-hull");
@@ -4042,10 +4044,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#objectVectorStudioV2RenderSurface [data-onion-skin-frame='frame-2']")).toHaveCount(1);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Onion-skin preview enabled\./);
 
-      await page.evaluate(() => window.__objectVectorStudioV2App.selectState("thrust", "test state selection"));
+      await page.evaluate(() => window.__objectVectorStudioV2App.selectState("move", "test state selection"));
       await expect(page.locator('[data-object-id="object.animation.ship-template"]')).toHaveAttribute("aria-pressed", "true");
-      await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-state-id='thrust']")).toHaveCount(1);
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Selected state Thrust from test state selection; active object remains Ship Template\./);
+      await expect(page.locator("#objectVectorStudioV2StateSelect")).toHaveValue("move");
+      await expect(page.locator("#objectVectorStudioV2StateHelpButton")).toHaveAttribute("title", "Movement/action state.\nUsed for thrusting, walking, flying, or active movement visuals.");
+      await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-state-id='move']")).toHaveCount(1);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Selected state Move from test state selection; active object remains Ship Template\./);
       await page.evaluate(() => window.__objectVectorStudioV2App.selectState("idle", "test state selection"));
       await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-state-id='idle']")).toHaveCount(2);
 
@@ -4070,7 +4074,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
 
       await page.locator("#objectVectorStudioV2CopyJsonButton").click();
       const copiedPayload = await page.evaluate(() => JSON.parse(sessionStorage.getItem("object-vector-studio-v2.animation-copied-json")));
-      expect(copiedPayload.objects[0].states.map((state) => state.id)).toEqual(expect.arrayContaining(["idle", "thrust"]));
+      expect(copiedPayload.objects[0].states.map((state) => state.id)).toEqual(expect.arrayContaining(["idle", "move"]));
       expect(copiedPayload.objects[0].states.find((state) => state.id === "idle").frames).toHaveLength(2);
 
       const svgDownloadPromise = page.waitForEvent("download");
@@ -4082,6 +4086,29 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(exportedSvg).toContain('data-object-state="idle"');
       expect(exportedSvg).toContain('"frameId"');
 
+      const legacyPayloadPath = testInfo.outputPath("object-vector-legacy-frame-id.json");
+      const legacyPayload = JSON.parse(JSON.stringify(copiedPayload));
+      legacyPayload.objects[0].states.find((state) => state.id === "idle").frames = [
+        {
+          durationFrames: 1,
+          id: "idle-frame-1",
+          order: 1,
+          shapeOverrides: [
+            {
+              shapeIndex: 0,
+              transform: { origin: { x: 0, y: 0 }, rotation: 0, scaleX: 1, scaleY: 1, x: 12, y: 6 },
+              visible: true
+            }
+          ]
+        }
+      ];
+      await writeFile(legacyPayloadPath, JSON.stringify(legacyPayload, null, 2), "utf8");
+      await page.locator("#objectVectorStudioV2ImportJsonInput").setInputFiles(legacyPayloadPath);
+      await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-frame-id='idle-frame-1']")).toHaveAttribute("aria-pressed", "true");
+      await page.locator("#objectVectorStudioV2DuplicateFrameButton").click();
+      await expect(page.locator("#objectVectorStudioV2FrameTimeline [data-frame-id='frame-1']")).toHaveAttribute("aria-pressed", "true");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Duplicated frame idle-frame-1 as frame-1\./);
+
       const invalidPayloadPath = testInfo.outputPath("object-vector-invalid-animation.json");
       await writeFile(invalidPayloadPath, JSON.stringify({
         name: "Invalid Animation Payload",
@@ -4104,7 +4131,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         version: 1
       }, null, 2), "utf8");
       await page.locator("#objectVectorStudioV2ImportJsonInput").setInputFiles(invalidPayloadPath);
-      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Object Vector Studio V2 schema validation failed from import:object-vector-invalid-animation\.json: root\.objects\[0\]\.states\[0\]\.id must be one of idle, thrust, damaged, destroyed, active, inactive\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Object Vector Studio V2 schema validation failed from import:object-vector-invalid-animation\.json: root\.objects\[0\]\.states\[0\]\.id must be one of idle, move, active, inactive, damaged, destroyed, thrust\./);
 
       expect(pageErrors).toEqual([]);
     } finally {

tools/object-vector-studio-v2/index.html

@@ -165,6 +165,10 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
               <div id="objectVectorStudioV2ObjectPreviewFooter" class="object-vector-studio-v2__preview-footer">Object ID: none</div>
               <hr class="object-vector-studio-v2__separator">
               <div class="object-vector-studio-v2__animation-controls" aria-label="Animation controls">
+                <select id="objectVectorStudioV2StateSelect" class="object-vector-studio-v2__state-select" aria-label="Frame state" disabled>
+                  <option value="">No state</option>
+                </select>
+                <button id="objectVectorStudioV2StateHelpButton" class="object-vector-studio-v2__state-help" type="button" disabled title="Disabled until a state is selected" aria-label="State help">?</button>
                 <button id="objectVectorStudioV2PlayButton" type="button" disabled title="Disabled until a state frame is selected">Play</button>
                 <button id="objectVectorStudioV2PauseButton" type="button" disabled title="Disabled until playback starts">Pause</button>
                 <button id="objectVectorStudioV2StopButton" type="button" disabled title="Disabled until a state frame is selected">Stop</button>

tools/object-vector-studio-v2/js/ToolStarterApp.js

@@ -110,17 +110,28 @@ const OBJECT_VECTOR_STUDIO_STATIC_ICON_TARGETS = Object.freeze([
   [".object-vector-studio-v2__z-icon--ungroup", "ungroup"]
 ]);
 
-const OBJECT_STATE_IDS = Object.freeze(["idle", "thrust", "damaged", "destroyed", "active", "inactive"]);
+const OBJECT_STATE_IDS = Object.freeze(["idle", "move", "active", "inactive", "damaged", "destroyed", "thrust"]);
 
 const OBJECT_STATE_LABELS = Object.freeze({
   active: "Active",
   damaged: "Damaged",
   destroyed: "Destroyed",
   idle: "Idle",
   inactive: "Inactive",
+  move: "Move",
   thrust: "Thrust"
 });
 
+const OBJECT_STATE_HELP = Object.freeze({
+  active: ["Object is enabled and participating in gameplay.", "Typically the default active runtime state."],
+  damaged: ["Object is visually damaged but still active."],
+  destroyed: ["Object destruction/death state.", "Usually final or transitional before removal."],
+  idle: ["Default stationary state.", "No movement or action animation active."],
+  inactive: ["Object is disabled, hidden, sleeping, or not participating in gameplay."],
+  move: ["Movement/action state.", "Used for thrusting, walking, flying, or active movement visuals."],
+  thrust: ["Movement/action state.", "Used for thrusting, walking, flying, or active movement visuals."]
+});
+
 const SHAPE_TYPE_DETAILS = Object.freeze({
   arc: "Arc primitive metadata with center, radius, and angle span.",
   circle: "Circle primitive metadata with center point and radius.",
@@ -620,6 +631,7 @@ export class ToolStarterApp {
   }
 
   bindAnimationControls() {
+    this.elements.stateSelect.addEventListener("change", () => this.selectState(this.elements.stateSelect.value, "state dropdown"));
     this.elements.deleteFrameButton.addEventListener("click", () => this.deleteSelectedFrame());
     this.elements.duplicateFrameButton.addEventListener("click", () => this.duplicateSelectedFrame());
     this.elements.frameLeftButton.addEventListener("click", () => this.moveSelectedFrame("earlier", "left"));
@@ -1560,6 +1572,7 @@ export class ToolStarterApp {
   }
 
   renderFrameTimeline() {
+    this.renderStateSelect();
     this.elements.frameTimeline.replaceChildren();
     const object = this.selectedObject();
     const state = this.selectedState();
@@ -1591,6 +1604,61 @@ export class ToolStarterApp {
     this.updateAnimationActionState();
   }
 
+  renderStateSelect() {
+    const object = this.selectedObject();
+    const states = this.objectStates(object);
+    this.elements.stateSelect.replaceChildren();
+    if (!object || !states.length) {
+      const option = document.createElement("option");
+      option.value = "";
+      option.textContent = "No state";
+      this.elements.stateSelect.append(option);
+      this.elements.stateSelect.value = "";
+      this.elements.stateSelect.disabled = true;
+      this.updateStateHelpButton(null);
+      return;
+    }
+
+    const currentState = this.selectedState();
+    if (!currentState) {
+      const option = document.createElement("option");
+      option.value = "";
+      option.textContent = "No state";
+      this.elements.stateSelect.append(option);
+    }
+    states.forEach((state) => {
+      const option = document.createElement("option");
+      option.value = state.id;
+      option.textContent = state.id;
+      this.elements.stateSelect.append(option);
+    });
+    this.elements.stateSelect.disabled = false;
+    this.elements.stateSelect.value = currentState?.id || "";
+    this.updateStateHelpButton(currentState);
+  }
+
+  updateStateHelpButton(state) {
+    const hasState = Boolean(state);
+    this.elements.stateHelpButton.disabled = !hasState;
+    this.elements.stateHelpButton.setAttribute("aria-disabled", String(!hasState));
+    if (!hasState) {
+      this.elements.stateHelpButton.title = "Disabled until a state is selected";
+      this.elements.stateHelpButton.dataset.stateHelp = "";
+      this.elements.stateHelpButton.setAttribute("aria-label", "State help");
+      return;
+    }
+
+    const helpText = this.stateHelpText(state.id);
+    this.elements.stateHelpButton.title = helpText;
+    this.elements.stateHelpButton.dataset.stateHelp = helpText;
+    this.elements.stateHelpButton.setAttribute("aria-label", `State help for ${state.id}: ${helpText.replace(/\s+/gu, " ")}`);
+  }
+
+  stateHelpText(stateId) {
+    const helpLines = OBJECT_STATE_HELP[stateId] || [`No contextual help is available for state ${stateId || "unknown"}.`];
+    return helpLines.join("\n");
+  }
+
   createFrameThumbnail(object, frame) {
     const svg = document.createElementNS(SVG_NS, "svg");
     svg.classList.add("object-vector-studio-v2__frame-thumbnail");
@@ -2826,7 +2894,7 @@ export class ToolStarterApp {
     this.selectedFrameId = sortedFrames(state)[0]?.id || "";
     this.stopPlaybackTimer();
     this.renderPayload();
-    this.statusLog.write(`OK Selected state ${OBJECT_STATE_LABELS[state.id]} from ${sourceLabel}; active object remains ${object.name}.`);
+    this.statusLog.write(`OK Selected state ${OBJECT_STATE_LABELS[state.id] || state.id} from ${sourceLabel}; active object remains ${object.name}.`);
   }
 
   selectFrame(frameId, sourceLabel) {
@@ -2856,11 +2924,11 @@ export class ToolStarterApp {
     }
     const stateId = "idle";
     if (!OBJECT_STATE_IDS.includes(stateId)) {
-      this.statusLog.write("FAIL Create state blocked: choose idle, thrust, damaged, destroyed, active, or inactive.");
+      this.statusLog.write(`FAIL Create state blocked: choose ${OBJECT_STATE_IDS.join(", ")}.`);
       return;
     }
     if (this.objectStates(object).some((state) => state.id === stateId)) {
-      this.statusLog.write(`WARN Create state skipped: ${OBJECT_STATE_LABELS[stateId]} already exists for ${object.name}.`);
+      this.statusLog.write(`WARN Create state skipped: ${OBJECT_STATE_LABELS[stateId] || stateId} already exists for ${object.name}.`);
       this.selectState(stateId, "existing state");
       return;
     }
@@ -2872,9 +2940,9 @@ export class ToolStarterApp {
     nextObject.states.push({
       frames: [frame],
       id: stateId,
-      name: OBJECT_STATE_LABELS[stateId]
+      name: OBJECT_STATE_LABELS[stateId] || stateId
     });
-    this.commitPayloadUpdate(nextPayload, object.id, this.selectedShapeIndex, `OK Created state ${OBJECT_STATE_LABELS[stateId]} with frame ${frame.id}.`, "Create state failed schema validation", {
+    this.commitPayloadUpdate(nextPayload, object.id, this.selectedShapeIndex, `OK Created state ${OBJECT_STATE_LABELS[stateId] || stateId} with frame ${frame.id}.`, "Create state failed schema validation", {
       selectedFrameId: frame.id,
       selectedStateId: stateId
     });
@@ -2917,7 +2985,7 @@ export class ToolStarterApp {
     }
     const frames = sortedFrames(state);
     if (frames.length <= 1) {
-      this.statusLog.write(`WARN Delete frame skipped: frame ${frame.id} is the only frame in ${OBJECT_STATE_LABELS[state.id]}.`);
+      this.statusLog.write(`WARN Delete frame skipped: frame ${frame.id} is the only frame in ${OBJECT_STATE_LABELS[state.id] || state.id}.`);
       return;
     }
     const index = frames.findIndex((candidate) => candidate.id === frame.id);
@@ -2930,7 +2998,7 @@ export class ToolStarterApp {
     });
     nextState.frames = nextFrames;
     const nextSelectedFrame = nextFrames[Math.min(index, nextFrames.length - 1)] || nextFrames[0];
-    this.commitPayloadUpdate(nextPayload, object.id, this.selectedShapeIndex, `OK Deleted frame ${frame.id} from ${OBJECT_STATE_LABELS[state.id]}.`, "Delete frame failed schema validation", {
+    this.commitPayloadUpdate(nextPayload, object.id, this.selectedShapeIndex, `OK Deleted frame ${frame.id} from ${OBJECT_STATE_LABELS[state.id] || state.id}.`, "Delete frame failed schema validation", {
       selectedFrameId: nextSelectedFrame.id,
       selectedStateId: state.id
     });
@@ -2987,7 +3055,7 @@ export class ToolStarterApp {
     this.isAnimationPlaying = true;
     this.updateAnimationActionState();
     this.playbackTimerId = this.window.setInterval(() => this.advancePlaybackFrame(), Math.round(1000 / fps));
-    this.statusLog.write(`OK Playback started for state ${OBJECT_STATE_LABELS[state.id]} at ${fps} FPS.`);
+    this.statusLog.write(`OK Playback started for state ${OBJECT_STATE_LABELS[state.id] || state.id} at ${fps} FPS.`);
   }
 
   pauseAnimation() {
@@ -3041,7 +3109,7 @@ export class ToolStarterApp {
       return;
     }
     this.stopPlaybackTimer();
-    this.statusLog.write(`OK Playback completed for state ${OBJECT_STATE_LABELS[state.id]}.`);
+    this.statusLog.write(`OK Playback completed for state ${OBJECT_STATE_LABELS[state.id] || state.id}.`);
   }
 
   addObject() {
@@ -4968,7 +5036,7 @@ export class ToolStarterApp {
 
   uniqueFrameId(state) {
     const usedIds = new Set(sortedFrames(state).map((frame) => frame.id));
-    let suffix = usedIds.size + 1;
+    let suffix = 1;
     let candidate = `frame-${suffix}`;
     while (usedIds.has(candidate)) {
       suffix += 1;