Bundle STYLE_10 through STYLE_12 into one focused usability standardization PR.

Implement interaction flow, visual hierarchy/readability, and component consistency on the migrated shell tools while preserving the shared shell/layout foundation.

PR: BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION

Author: DavidQ

docs/dev/reports/style_10_12_bundle_rationale.txt

@@ -0,0 +1,9 @@
+Bundling rationale
+
+User requested as few PRs as possible.
+This bundle safely groups:
+- STYLE_10 Interaction & Flow
+- STYLE_11 Visual Hierarchy & Readability
+- STYLE_12 Component Standardization
+
+These three items are tightly related and can be validated together on the same migrated tool set without starting broader theming/color work.

docs/dev/roadmaps/MASTER_ROADMAP_STYLE.md

@@ -336,39 +336,39 @@ This explanation should be kept visible in related UI/help text so launch choice
 
 ### STYLE_10 — Interaction & Flow
 
-[ ] Primary actions accessible via keyboard (Enter)
-[ ] Escape cancels or resets where applicable
-[ ] Logical tab flow across panels (left → center → right)
-[ ] Initial focus set correctly on load
-[ ] Focus preserved after actions
-[ ] Buttons reflect active/disabled state
-[ ] No layout shift during interaction
-[ ] Interaction patterns consistent across migrated tools
-[ ] No inline `style=""`
-[ ] No JS-driven layout changes
-[ ] Pages are visually stable and usable
+[x] Primary actions accessible via keyboard (Enter)
+[x] Escape cancels or resets where applicable
+[x] Logical tab flow across panels (left → center → right)
+[x] Initial focus set correctly on load
+[x] Focus preserved after actions
+[x] Buttons reflect active/disabled state
+[x] No layout shift during interaction
+[x] Interaction patterns consistent across migrated tools
+[x] No inline `style=""`
+[x] No JS-driven layout changes
+[x] Pages are visually stable and usable
 
 ### STYLE_11 — Visual Hierarchy & Readability
 
-[ ] Clear heading hierarchy across tools
-[ ] Panel titles consistent in size and spacing
-[ ] Section grouping visually obvious
-[ ] Spacing rhythm consistent across panels
-[ ] Labels and helper text clearly distinguishable
-[ ] No visual clutter in dense layouts
-[ ] No layout breakage
-[ ] Pages remain easy to scan quickly
+[x] Clear heading hierarchy across tools
+[x] Panel titles consistent in size and spacing
+[x] Section grouping visually obvious
+[x] Spacing rhythm consistent across panels
+[x] Labels and helper text clearly distinguishable
+[x] No visual clutter in dense layouts
+[x] No layout breakage
+[x] Pages remain easy to scan quickly
 
 ### STYLE_12 — Component Standardization
 
-[ ] Buttons visually consistent across all tools
-[ ] Inputs and textareas standardized
-[ ] Labels aligned and consistently styled
-[ ] Panels share common structure and spacing
-[ ] Debug/readout areas visually consistent
-[ ] No one-off component styling remains
-[ ] No inline `style=""`
-[ ] No layout regressions
+[x] Buttons visually consistent across all tools
+[x] Inputs and textareas standardized
+[x] Labels aligned and consistently styled
+[x] Panels share common structure and spacing
+[x] Debug/readout areas visually consistent
+[x] No one-off component styling remains
+[x] No inline `style=""`
+[x] No layout regressions
 
 ### STYLE_13 — Color System & Theming
 

docs/operations/dev/codex_commands.md

@@ -2,25 +2,29 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_STYLE_07_LAUNCH_CLARITY_AND_ROADMAP_APPEND_ONLY
+Create BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION
 
 Rules:
+- complete the lowest unfinished STYLE first
+- this PR is valid only after STYLE_07 is complete
+- bundle STYLE_10 through STYLE_12 in this PR only
+- do NOT start STYLE_13+ implementation work
 - output ONLY the final zip to:
-  <project folder>/tmp/BUILD_PR_STYLE_07_LAUNCH_CLARITY_AND_ROADMAP_APPEND_ONLY.zip
+  <project folder>/tmp/BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION.zip
 - do NOT create staging folders in <project folder>/tmp
-- complete existing unfinished STYLE items before new ones
-- lowest unfinished STYLE number first
-- do NOT start STYLE_10 implementation work in this PR
-- roadmap updates happen during execution only
+- do NOT modify roadmap in the PR bundle
+- Codex updates roadmap during execution only
 - roadmap changes are append-only except for execution-backed status markers
 - do NOT delete existing roadmap text
 - do NOT rewrite existing roadmap text
 
 Required work:
-1. Implement STYLE_07 launch clarity/help text in the relevant UI.
-2. Use exactly this wording:
-   - Open Tool = launch the tool directly/standalone
-   - Open In Host = launch the same tool inside a shared host shell/container
-3. Append the bundled STYLE_07 and STYLE_10 through STYLE_17 sections to docs/dev/roadmaps/MASTER_ROADMAP_STYLE.md.
-4. Mark STYLE_07 completion boxes only if execution-backed by the implemented change.
+1. Implement STYLE_10 interaction and flow improvements on the migrated shell tools.
+2. Implement STYLE_11 visual hierarchy and readability improvements on the same tool set.
+3. Implement STYLE_12 component standardization on the same tool set.
+4. Preserve the shared shell/layout from STYLE_06–09.
 5. Keep the change narrow, testable, and free of inline/embedded styling.
+6. Update MASTER_ROADMAP_STYLE.md during execution:
+   - mark STYLE_10, STYLE_11, STYLE_12 only if execution-backed
+   - append STYLE_10–STYLE_17 sections only if any are still missing
+   - do not delete or rewrite existing roadmap text

docs/operations/dev/commit_comment.txt

@@ -1,6 +1,5 @@
-Complete STYLE_07 first by adding clear launch/help text for Open Tool vs Open In Host.
+Bundle STYLE_10 through STYLE_12 into one focused usability standardization PR.
 
-Append the queued STYLE_10 through STYLE_17 roadmap sections without rewriting existing roadmap text.
-Keep roadmap handling append-only plus execution-backed status updates.
+Implement interaction flow, visual hierarchy/readability, and component consistency on the migrated shell tools while preserving the shared shell/layout foundation.
 
-PR: BUILD_PR_STYLE_07_LAUNCH_CLARITY_AND_ROADMAP_APPEND_ONLY
+PR: BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION

docs/pr/BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION.md

@@ -0,0 +1,86 @@
+# BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION
+
+## Purpose
+Complete the next smallest safe grouped style slice after STYLE_07 by bundling STYLE_10 through STYLE_12 into one execution-backed PR.
+
+## Single PR Purpose
+Standardize how tools are used and read:
+- interaction flow
+- visual hierarchy/readability
+- component consistency
+
+This bundle intentionally groups only the tightly related layers that improve usability without changing broader theming strategy.
+
+## Sequence Rule
+- Complete the lowest unfinished STYLE first.
+- This PR is valid only after STYLE_07 is complete.
+- Do not start STYLE_13+ implementation work in this PR.
+- Keep roadmap handling execution-backed and append-only.
+
+## Included Style Items
+- STYLE_10 — Interaction & Flow
+- STYLE_11 — Visual Hierarchy & Readability
+- STYLE_12 — Component Standardization
+
+## Scope
+- improve keyboard-first flow on migrated tools
+- improve focus management and button/action state consistency
+- improve heading/panel/label readability and grouping
+- standardize buttons, inputs, labels, panels, and readout areas across migrated tools
+- keep the shared shell/layout from STYLE_06–09 intact
+- do not redesign tools
+- do not start full color-system/theming work
+- do not create per-tool forks unless required for functionality
+
+## Required Rules
+1. Preserve existing shared theme and tool shell foundations.
+2. No embedded `<style>` blocks.
+3. No inline `style=""`.
+4. No JS-generated styling.
+5. Keep layout changes minimal; this is not a shell redesign PR.
+6. Keyboard/focus work must not introduce layout shift.
+7. Component standardization must reuse shared theme files where possible.
+8. Keep changes visually testable and narrow relative to the three bundled style items.
+
+## STYLE_10 — Interaction & Flow
+Implement on the already migrated tool set:
+- primary actions accessible via Enter where appropriate
+- Escape cancels/resets where appropriate
+- logical tab flow across panels
+- initial focus set correctly on load where appropriate
+- focus preserved after actions where practical
+- buttons reflect active/disabled state
+- no layout shift during interaction
+
+## STYLE_11 — Visual Hierarchy & Readability
+Implement on the already migrated tool set:
+- clear heading hierarchy
+- consistent panel title spacing/size
+- visually obvious section grouping
+- consistent spacing rhythm across panels
+- readable labels/helper text
+- no clutter introduced by dense layouts
+
+## STYLE_12 — Component Standardization
+Implement on the already migrated tool set:
+- buttons visually consistent
+- inputs/textareas standardized
+- labels consistently styled/aligned
+- panels use common structure/spacing
+- debug/readout areas visually consistent
+- remove one-off component styling where safe
+
+## Validation Targets
+Use the existing migrated shell tools as the validation set:
+- tools/State Inspector/index.html
+- tools/Performance Profiler/index.html
+- tools/Replay Visualizer/index.html
+- tools/Physics Sandbox/index.html
+
+## Acceptance
+- STYLE_10 interaction behavior is execution-backed on migrated tools
+- STYLE_11 readability improvements are visible and consistent
+- STYLE_12 component consistency is visible across migrated tools
+- no layout shell regression
+- no inline/embedded styling added
+- change remains visually testable

tools/Performance Profiler/main.js

@@ -6,6 +6,7 @@ import {
 import { readToolHostSharedContextFromLocation } from "../shared/toolHostSharedContext.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
 import { isFiniteNumber } from "../../src/shared/number/index.js";
+import { setupDebugToolInteractionFlow } from "../shared/debugToolInteractionFlow.js";
 
 const refs = {
   runWorkloadButton: document.getElementById("runWorkloadButton"),
@@ -23,6 +24,8 @@ const state = {
   frameSampling: false
 };
 
+let disposeInteractionFlow = null;
+
 function setStatus(message) {
   if (refs.statusText instanceof HTMLElement) {
     refs.statusText.textContent = message;
@@ -75,6 +78,20 @@ function stopFrameSampling() {
     state.frameHandle = 0;
   }
   state.frameSampling = false;
+  updateControlState();
+}
+
+function updateControlState() {
+  const running = state.frameSampling;
+  if (refs.runWorkloadButton instanceof HTMLButtonElement) {
+    refs.runWorkloadButton.disabled = running;
+  }
+  if (refs.runFrameSampleButton instanceof HTMLButtonElement) {
+    refs.runFrameSampleButton.disabled = running;
+  }
+  if (refs.stopButton instanceof HTMLButtonElement) {
+    refs.stopButton.disabled = !running;
+  }
 }
 
 function runFrameSample() {
@@ -84,6 +101,7 @@ function runFrameSample() {
   let lastTimestamp = 0;
   let sampleCount = 0;
   state.frameSampling = true;
+  updateControlState();
 
   function tick(timestamp) {
     if (!state.frameSampling) {
@@ -159,6 +177,15 @@ const performanceProfilerApi = {
 function bootPerformanceProfiler() {
   if (!initialized) {
     bindEvents();
+    disposeInteractionFlow = setupDebugToolInteractionFlow({
+      primaryButton: refs.runWorkloadButton,
+      escapeAction: () => {
+        stopFrameSampling();
+        setStatus("Profiler reset to idle.");
+      },
+      statusElement: refs.statusText
+    });
+    updateControlState();
     const hostContext = readToolHostSharedContextFromLocation(window.location);
     if (hostContext?.state && typeof hostContext.state === "object") {
       performanceProfilerApi.applyProjectState(hostContext.state);
@@ -174,6 +201,10 @@ registerToolBootContract("performance-profiler", {
   init: bootPerformanceProfiler,
   destroy() {
     stopFrameSampling();
+    if (typeof disposeInteractionFlow === "function") {
+      disposeInteractionFlow();
+      disposeInteractionFlow = null;
+    }
     return true;
   },
   getApi() {

tools/Physics Sandbox/main.js

@@ -1,6 +1,7 @@
 import { integrateVelocity2D, stepArcadeBody } from "../../src/engine/physics/index.js";
 import { safeParseJson, toPrettyJson } from "../shared/debugInspectorData.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
+import { setupDebugToolInteractionFlow } from "../shared/debugToolInteractionFlow.js";
 
 const refs = {
   runButton: document.getElementById("runPhysicsStepButton"),
@@ -9,6 +10,9 @@ const refs = {
   output: document.getElementById("physicsSandboxOutput")
 };
 
+let disposeInteractionFlow = null;
+let initialized = false;
+
 function setStatus(message) {
   if (refs.statusText instanceof HTMLElement) {
     refs.statusText.textContent = message;
@@ -46,9 +50,24 @@ function runStep() {
 }
 
 function bootPhysicsSandbox() {
+  if (initialized) {
+    return {
+      runStep
+    };
+  }
   if (refs.runButton instanceof HTMLButtonElement) {
     refs.runButton.addEventListener("click", runStep);
   }
+  disposeInteractionFlow = setupDebugToolInteractionFlow({
+    primaryButton: refs.runButton,
+    escapeAction: () => {
+      if (refs.output instanceof HTMLElement) {
+        refs.output.textContent = "Run a step to inspect updated body state.";
+      }
+      setStatus("Sandbox reset to ready state.");
+    },
+    statusElement: refs.statusText
+  });
   if (refs.input instanceof HTMLTextAreaElement && !refs.input.value.trim()) {
     refs.input.value = toPrettyJson({
       x: 0,
@@ -63,6 +82,7 @@ function bootPhysicsSandbox() {
       maxSpeedY: 140
     });
   }
+  initialized = true;
   return {
     runStep
   };
@@ -71,6 +91,10 @@ function bootPhysicsSandbox() {
 registerToolBootContract("physics-sandbox", {
   init: bootPhysicsSandbox,
   destroy() {
+    if (typeof disposeInteractionFlow === "function") {
+      disposeInteractionFlow();
+      disposeInteractionFlow = null;
+    }
     return true;
   },
   getApi() {