feat(M13 chunk 11a): PlaybackControls component

First half of chunk 11. Speed selector (0.25×/1×/4×) + play-pause +
prev/next scene + jump-to-live. Click-to-expand affordance lands
in 11b; chunk-11 checkbox stays unchecked until then.

PlaybackControls component:
- Pure render. Takes state + controls + optional liveSceneIndex.
- Play/pause toggle (amber when playing, emerald when paused).
- Prev/Next scene buttons (◂◂ / ▸▸), each disabled at the
  start/end boundary respectively.
- Speed radiogroup: 0.25× / 1× / 4× per PLAYBACK_SPEEDS. Active
  speed gets cyan accent + aria-checked.
- Jump-to-live (⇥ Live, violet accent). Disabled when
  liveSceneIndex is null OR equals state.sceneIndex.
- Scene-position label at right ("Scene 5 / 20 · t = 0.42").
- role="toolbar" + aria-label="Playback controls".

CinematicViz wiring:
- Imports PlaybackControls; mounts between PipelineProgressBar
  and the canvas row.
- Computes liveSceneIndex from tokenEvents:
    no events                   → null
    token.received but !final   → 18 (autoregressive-loop)
    is_final                    → 20 (detokenize / EOS)

14 new Vitest tests in PlaybackControls.test.tsx:
- All four control groups render.
- Toggle label flips with playing state + calls controls.toggle.
- Prev/next call correct controls; disabled at start/end.
- Three speed buttons render; active one is aria-checked;
  click calls setSpeed.
- Jump-to-live disabled when liveSceneIndex is null;
  enabled + calls setScene when distinct; disabled when equal.
- Scene-position label format.
- Toolbar role + aria-label.

Full suite: 87 files / 881 tests pass; tsc --noEmit clean.

phase1.md: chunk-11 checkbox stays unchecked (11b lands the rest).
Decisions block for chunk 11a added (10 bullets).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: CyberSecDef

docs/phase1.md

@@ -1066,6 +1066,18 @@ Bonus M12 work beyond the SPEC's two exit criteria:
 - **Real run continues independently.** The M6 streaming pipeline + the M8 `useRunStream` hook keep doing exactly what they do. The chat bubble subscribes to the same WebSocket events and displays tokens as they arrive. Scenes 18-20 use the same event timeline to drive the autoregressive-loop pacing, but the viz lagging behind is expected + acceptable.
 - **WebSocket → Scene coupling.** Scenes 5-17 fire once per *generated* token. The current `RunEvent` schema (M6) emits one `token.received` per token; the SceneRunner subscribes + advances. For the input tokens (the prompt), the runner enters Scenes 0-4 at submit time without waiting for the WebSocket.
 
+**Decisions (chunk 11a):** (PlaybackControls — chunk 11 is mid-flight; checkbox stays unchecked until 11b lands the click-to-expand panel.)
+- **`useSceneRunner` controls already covered the needs.** Speed (PLAYBACK_SPEEDS already `[0.25, 1, 4]`), play/pause/toggle, prev/next scene (= "step to scene-boundary" per chunk-11 spec). No runner changes needed — chunk 11a is pure UI + jump-to-live derivation.
+- **`PlaybackControls` is a pure render component** taking `state + controls + liveSceneIndex`. CinematicViz computes `liveSceneIndex` from the events stream and passes it through. Same pattern as the chunk-1 `PipelineProgressBar` (state + onSelectScene). Keeps the chunk-11 component pure-render, easy to test.
+- **Jump-to-live heuristic** matches the chunk-11 design decision: no events → null → button disabled; any token.received → setScene(18); is_final → setScene(20). Documented in the inline comment + tested explicitly. The button is also disabled when the live target equals the current scene — "no jump needed" UX state.
+- **Step = `nextScene()` / `prevScene()` only.** Spec explicitly calls out scene-boundary step, not event-boundary step. The runner already exposes both; mapping them to `◂◂` / `▸▸` is straightforward. No event-stepping mode — would conflict with the synthetic-vs-real timing split.
+- **Speed selector is `role="radiogroup"` with three `role="radio"` buttons.** Per the M12 chunk-2 a11y pattern: the active speed is `aria-checked="true"`; the inactive two are `aria-checked="false"`. Single button visually pressed via cyan background. focus-visible ring chain present.
+- **Play/pause uses semantic colors** (amber when playing → "pause to interrupt", emerald when paused → "play to resume"). Picked for color-blind safety (the verb is in the label, not just the color) and to differentiate from the cyan speed buttons.
+- **Jump-to-live uses violet accent.** Distinct from cyan (speed) / emerald (play) / amber (pause) — a fourth semantic slot for "fast-forward through the run." Disabled state uses the muted-foreground/30 pattern.
+- **Scene-position label "Scene N / M · t = X.XX" mounted at the right of the toolbar.** Read-only, informative. Helps debug-mode users see exactly where the runner is. Could be hidden behind a flag in chunk 13; for now visible.
+- **PlaybackControls mounted between PipelineProgressBar and the canvas row in CinematicViz.** Pipeline progress (overview) → playback controls (action) → canvas (content). Top-to-bottom visual hierarchy matches the spec's "PipelineProgressBar at the very top, PlaybackControls just below."
+- **The click-to-expand affordance lands in chunk 11b.** Chunk-11 checkbox stays unchecked until 11b ships the VectorInspectionProvider + NumericalValuesPanel.
+
 **Decisions (chunk 10b):** (ChatBubble + WebSocket events wiring — completing chunk 10.)
 - **ChatBubble accepts `tokens: string[]` + `isFinal: boolean`** — the simplest contract that matches both data sources. CinematicViz does the events-vs-state selection upstream; ChatBubble itself doesn't know which source produced the array.
 - **Events-primary, state-fallback selection in CinematicViz.** When the `events` prop contains any `token.received` entries, the bubble reads from those. When empty (chunk-10 isolated testing, replay without a stream), it falls back to `state.pipelineState.generatedTokens.map(t => t.string)`. This delivers the spec's "ahead-of-viz" property automatically: live events stream from the real run independent of which scene the viz is on; chunk-10 tests + replays without a stream still show something.

resources/js/Components/Viz/CinematicViz.tsx

@@ -15,6 +15,7 @@ import VocabSidebar from '@/Components/Viz/VocabSidebar';
 import ChatBubble from '@/Components/Viz/ChatBubble';
 import LayerCounterHud from '@/Components/Viz/LayerCounterHud';
 import PipelineProgressBar from '@/Components/Viz/PipelineProgressBar';
+import PlaybackControls from '@/Components/Viz/PlaybackControls';
 import { Card, CardContent } from '@/Components/ui/card';
 import type { RunEvent } from '@/types/runs';
 
@@ -176,6 +177,18 @@ export default function CinematicViz({
             ? tokenEvents[tokenEvents.length - 1]?.payload.is_final === true
             : state.sceneId === 'detokenize' && state.t >= 0.9;
 
+    // M13 chunk 11a: jump-to-live target. Per chunk-11 decisions:
+    //   no token events                → null (button disabled)
+    //   token.received but not final   → 18 (autoregressive loop)
+    //   final token received           → 20 (detokenize / EOS)
+    // CinematicViz computes this here so PlaybackControls stays a
+    // pure render component.
+    const liveSceneIndex: number | null = (() => {
+        if (tokenEvents.length === 0) return null;
+        const lastIsFinal = tokenEvents[tokenEvents.length - 1].payload.is_final === true;
+        return lastIsFinal ? 20 : 18;
+    })();
+
     // M13 chunk 10: LayerCounterHud visibility + values. Visible
     // during scenes 5-12 (the per-layer + tower scenes); hidden on
     // tokenization (0-4) + output (13-20). currentLayer defaults to
@@ -228,6 +241,12 @@ export default function CinematicViz({
                     }}
                 />
 
+                <PlaybackControls
+                    state={state}
+                    controls={controls}
+                    liveSceneIndex={liveSceneIndex}
+                />
+
                 <div className="flex min-h-[400px] gap-2">
                     <VocabSidebar
                         tokens={vocabTokens}

resources/js/Components/Viz/PlaybackControls.tsx

@@ -0,0 +1,183 @@
+import { cn } from '@/lib/utils';
+import {
+    PLAYBACK_SPEEDS,
+    type SceneRunnerControls,
+    type SceneRunnerState,
+    type SceneSpeed,
+} from '@/Components/Viz/useSceneRunner';
+
+/*
+ * PlaybackControls (M13 chunk 11a) — scene-level playback control
+ * surface mounted below the canvas. Adapts the M8 chunk-8
+ * `PlaybackControls` component (deleted in M13 chunk 1) to the
+ * scene-runner contract:
+ *
+ *   - Play/pause toggle
+ *   - Prev / Next scene (advances to next scene-boundary, NOT next
+ *     event — per the chunk-11 spec literal)
+ *   - Speed selector: 0.25× / 1× / 4× (PLAYBACK_SPEEDS)
+ *   - Jump-to-live: skips to the scene matching the current
+ *     token-stream position. Heuristic per chunk-11 decisions:
+ *       no events            → no-op (button disabled)
+ *       token.received only  → setScene(18) (autoregressive-loop)
+ *       is_final received    → setScene(20) (detokenize / EOS)
+ *
+ * Per `phase1.md:1036` + `docs/visualization.md`. Visual style
+ * matches the chunk-1 PipelineProgressBar (same border, padding,
+ * focus-visible ring pattern from M12 chunk 2).
+ */
+
+export interface PlaybackControlsProps {
+    state: SceneRunnerState;
+    controls: SceneRunnerControls;
+    /** Target scene for the "jump to live" button. Null disables
+     *  the button. Computed by the parent from the events stream. */
+    liveSceneIndex?: number | null;
+}
+
+export default function PlaybackControls({
+    state,
+    controls,
+    liveSceneIndex = null,
+}: PlaybackControlsProps) {
+    const canJumpLive = liveSceneIndex !== null && liveSceneIndex !== state.sceneIndex;
+
+    return (
+        <div
+            className="flex flex-wrap items-center gap-2 rounded-md border border-border bg-card/40 p-2 text-[10px]"
+            role="toolbar"
+            aria-label="Playback controls"
+            data-testid="viz-playback-controls"
+        >
+            {/* Play / pause */}
+            <button
+                type="button"
+                onClick={controls.toggle}
+                className={cn(
+                    'rounded px-2 py-1 font-medium uppercase tracking-wider transition-colors',
+                    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+                    state.playing
+                        ? 'bg-amber-500/20 text-amber-200 hover:bg-amber-500/30'
+                        : 'bg-emerald-500/20 text-emerald-200 hover:bg-emerald-500/30',
+                )}
+                aria-label={state.playing ? 'Pause playback' : 'Resume playback'}
+                aria-pressed={state.playing}
+                data-testid="viz-playback-toggle"
+            >
+                {state.playing ? 'Pause' : 'Play'}
+            </button>
+
+            {/* Prev / Next scene */}
+            <div
+                className="flex items-center gap-px rounded border border-border bg-card/60"
+                data-testid="viz-playback-step-group"
+            >
+                <button
+                    type="button"
+                    onClick={controls.prevScene}
+                    disabled={state.sceneIndex === 0}
+                    className={cn(
+                        'rounded-l px-2 py-1 transition-colors',
+                        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+                        state.sceneIndex === 0
+                            ? 'cursor-not-allowed text-muted-foreground/30'
+                            : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground',
+                    )}
+                    aria-label="Previous scene"
+                    data-testid="viz-playback-prev"
+                >
+                    ◂◂
+                </button>
+                <button
+                    type="button"
+                    onClick={controls.nextScene}
+                    disabled={state.sceneIndex >= state.totalScenes - 1}
+                    className={cn(
+                        'rounded-r px-2 py-1 transition-colors',
+                        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+                        state.sceneIndex >= state.totalScenes - 1
+                            ? 'cursor-not-allowed text-muted-foreground/30'
+                            : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground',
+                    )}
+                    aria-label="Next scene"
+                    data-testid="viz-playback-next"
+                >
+                    ▸▸
+                </button>
+            </div>
+
+            {/* Speed selector */}
+            <div
+                className="flex items-center gap-px rounded border border-border bg-card/60"
+                role="radiogroup"
+                aria-label="Playback speed"
+                data-testid="viz-playback-speed-group"
+            >
+                {PLAYBACK_SPEEDS.map((s, i) => {
+                    const active = state.speed === s;
+                    return (
+                        <button
+                            key={s}
+                            type="button"
+                            role="radio"
+                            aria-checked={active}
+                            onClick={() => controls.setSpeed(s as SceneSpeed)}
+                            className={cn(
+                                'px-2 py-1 font-mono tabular-nums transition-colors',
+                                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+                                i === 0 ? 'rounded-l' : '',
+                                i === PLAYBACK_SPEEDS.length - 1 ? 'rounded-r' : '',
+                                active
+                                    ? 'bg-cyan-500/30 text-cyan-100 font-semibold'
+                                    : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground',
+                            )}
+                            data-testid={`viz-playback-speed-${s}`}
+                        >
+                            {formatSpeed(s)}
+                        </button>
+                    );
+                })}
+            </div>
+
+            {/* Jump-to-live */}
+            <button
+                type="button"
+                onClick={() => {
+                    if (liveSceneIndex !== null) controls.setScene(liveSceneIndex);
+                }}
+                disabled={!canJumpLive}
+                className={cn(
+                    'rounded px-2 py-1 font-medium uppercase tracking-wider transition-colors',
+                    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+                    canJumpLive
+                        ? 'bg-violet-500/20 text-violet-200 hover:bg-violet-500/30'
+                        : 'cursor-not-allowed text-muted-foreground/30',
+                )}
+                aria-label="Jump to live"
+                aria-disabled={!canJumpLive}
+                data-testid="viz-playback-jump-live"
+                title={
+                    canJumpLive
+                        ? 'Jump the visualization forward to the latest run scene'
+                        : 'No live data ahead of the visualization'
+                }
+            >
+                ⇥ Live
+            </button>
+
+            {/* Scene-position label (informational) */}
+            <span
+                className="ml-auto font-mono tabular-nums text-muted-foreground/70"
+                data-testid="viz-playback-scene-label"
+            >
+                Scene {state.sceneIndex} / {state.totalScenes - 1}
+                {' · '}t = {state.t.toFixed(2)}
+            </span>
+        </div>
+    );
+}
+
+function formatSpeed(s: number): string {
+    if (Number.isInteger(s)) return `${s}×`;
+    return `${s}×`;
+}