@volter/editor-blender 0.1.149 → 0.1.151

package/contributions/blender-timeline.document.tsx

@@ -1,45 +1,7 @@
-/**
- * THE TIMELINE — Blender's, at the bottom of the Model workspace (owner,
- * 2026-09-20: "doesn't blender have a timeline at the bottom?"). It does: the
- * default Layout screen's `DOPESHEET_EDITOR` in `TIMELINE` mode, and the model
- * editor is not Blender-shaped without it.
- *
- * ## It is an AREA, so it is an editor group
- *
- * RULED 2026-09-19 (orchestrator): "A Blender editor AREA is an editor group;
- * the drawer holds utilities." Blender's Layout screen puts the Timeline
- * full-width UNDER the 3D viewport, and `model.layout.ts` declares it as an
- * `areas` entry with Blender's own measured proportion. This is a
- * `workspace.document`, never a drawer utility.
- *
- * ## THREE.JS PLAYS IT; BLENDER HOLDS IT
- *
- * Owner rule, 2026-09-20: "we visualize with three.js, not Blender." The scrub
- * does NOT ask Blender to evaluate frame N and re-export the mesh — it moves an
- * `AnimationMixer` over a `SkinnedMesh` the presenter bound once
- * (`blender-runtime-skin.ts`), so a scrub and a played frame cost ZERO calls
- * into the engine. `state` reports `engineCalls` precisely so that claim is
- * checkable rather than asserted.
- *
- * Blender's `scene.frame_current` IS written — ONCE, on pause and at
- * scrub-end, through the RNA door — so bpy readers and the Properties rail
- * agree with what the person is looking at. Never per frame.
- *
- * ## Every constant it draws with is `./blender-timeline-geometry.ts`
- *
- * Read from Blender's source at the engine's pin AND confirmed against a pixel
- * in Blender's own frame — this is the first unit of the inspection arc with a
- * sighted read behind it (`scripts/blender-reference-frames.py`).
- *
- * ## It never edits, and every gesture that would is refused BY NAME
- *
- * Setting the range, inserting a key and moving a key all write the file.
- * `frame` is the ONE verb that changes anything, and what it changes is where
- * you are looking.
- */
+/** The Timeline is the Model workspace’s bottom editor area. three.js plays animation; Blender’s frame bookmark is written only at pause or scrub end. Geometry comes from blender-timeline-geometry.ts. Transport and frame navigation are supported; range and key edits refuse by name. */
 
-import type { StageTransportHandle } from '@volter/sdk/host';
-import { registerViewVerbs } from '@volter/sdk/views';
+import { editorHost, type StageTransportHandle } from '@volter/sdk/host';
+import type { ViewVerb } from '@volter/sdk/commands';
 import {
   type ReactNode,
   useCallback,
@@ -64,10 +26,9 @@ import {
   timelineViewVersion,
 } from '../src/timeline-view-state';
 import { blenderSkin, blenderSkinVersion, subscribeBlenderSkin } from './blender-runtime-skin';
-import { BlenderGamePanel, GAME_PANEL_RATIO, PlayModeSwitch } from './blender-game-panel';
+import { PLAY_PANEL_RATIO, PlayModeSwitch } from './blender-play-area';
+import { modelPlayExtension, subscribeModelPlayExtension } from '../src/model-play-extension';
 import { AnimationEditorMenu, BlenderActionEditor, BlenderNlaEditor } from './blender-animation-editors';
-import { liveAnimation, subscribeLiveAnimation } from '../src/play-live';
-import { setWorkspaceAreaRatio } from '@volter/sdk/kit/workspace-areas';
 import { modelPlayMode, playModeVersion, servedModelDocument, subscribePlayMode } from '../src/play-mode';
 import {
   CHANNEL_HEIGHT,
@@ -90,11 +51,7 @@ import {
 } from './blender-timeline-geometry';
 
 export const point = 'workspace.document';
-/** Blender's own name for this editor: `rna_space.cc`'s `SPACE_ACTION` item
- *  reads "Timeline" when `SpaceAction.mode` is `TIMELINE`
- *  (`rna_space.cc:257`), which is the mode the Layout workspace opens it in
- *  (measured on the engine: that screen's `DOPESHEET_EDITOR` area answers
- *  `ui_type: 'TIMELINE'`). */
+/** Blender’s SPACE_ACTION title is Timeline when SpaceAction.mode is TIMELINE. */
 export const title = 'Timeline';
 
 const ZOOM_MIN = 0.25;
@@ -116,20 +73,10 @@ const REFUSALS = {
 
 /** The scene clock is available with or without an action. Only a missing
  * scene/transport prevents timeline navigation. */
-const GAME_RUNNING = 'A game is running; the Timeline is read-only until it stops (Stop in the Game panel).';
 const NOT_PLAYABLE =
   'No scene transport is attached yet; open the model document first.';
 
-/**
- * THE TRANSPORT THIS LOOK DRIVES — the Model document's, attached by
- * `blenderSkin.attachTo` (Step 6). The Timeline cannot name a document id (it
- * binds to the `blenderModelView` singleton), so it reads the handle the skin
- * was given rather than looking one up.
- *
- * `null` before the Model document attaches. A gesture then refuses by name
- * instead of silently doing nothing — a Timeline with no transport is a
- * Timeline over nothing.
- */
+/** Read the Model transport attached through blenderSkin.attachTo. Before attachment, gestures refuse by name. */
 function transport(): StageTransportHandle | null {
   return blenderSkin.transport;
 }
@@ -170,10 +117,7 @@ const KEY_TYPE_RANK: Record<string, number> = {
  * WHAT THE FILTER DOES NOT TOUCH is what PLAYS: the mixer holds the bound
  * action whatever the row draws, in Blender and here.
  *
- * The reference read is why the default is ON: with the probe's rig
- * unselected, Blender's own Timeline drew a ruler, a playhead, the range
- * shading and an EMPTY summary row while its Dope Sheet drew all five keys in
- * the same file.
+ * The selection filter defaults to ON, matching Blender’s Timeline.
  */
 function summaryColumns(
   summary: ReturnType<typeof blenderSkin.state>['summary'],
@@ -223,25 +167,8 @@ function report(): unknown {
   };
 }
 
-/** THE SCRUB. It moves the mixer and forces the bones' world matrices; the
- *  stage's own render loop draws the next frame from them. Blender is not
- *  called — `state().engineCalls` is how that is checked.
- *
- *  IT REFUSES WITHOUT A SCENE TRANSPORT, for the reason {@link NOT_PLAYABLE}
- *  states and with that one sentence: `#seek` returns at its first line with
- *  no mixer (`blender-runtime-skin.ts`), so the seek was a no-op and
- *  `report()` then answered `frame: 1` — the playhead's honest position and a
- *  complete lie about the gesture. Measured on walk 5 over a fresh
- *  `cyclotron create` scaffold: `volter.timeline.frame {frame:120}` and
- *  `volter.timeline.jump-end` (frame 250) both answered `frame: 1`,
- *  `refusal: null`. This is the half of walk 4's W5 (#7740) that the header
- *  got and the VERBS did not — there the buttons were disabled wearing this
- *  sentence as their title while `play` threw it, and the five verbs that
- *  route through here kept answering as if they had moved something. All five
- *  are fixed by this one guard: `frame`, `jump-start`, `jump-end`,
- *  `next-keyframe`, `prev-keyframe`. */
+/** Scrub through the scene mixer with no Blender call. Refuse without a playable transport rather than report a frame that the gesture could not reach. */
 function scrubTo(frame: number): unknown {
-  if (liveAnimation() !== null) return refuse(GAME_RUNNING);
   if (!blenderSkin.playable) return refuse(NOT_PLAYABLE);
   const handle = transport();
   if (!handle) return refuse('No stage transport is attached yet; open the model document first.');
@@ -249,152 +176,124 @@ function scrubTo(frame: number): unknown {
   return report();
 }
 
-registerViewVerbs({
-  view: 'timeline',
-  title,
-  verbs: [
-    { id: 'state', run: () => report() },
-    {
-      // BLENDER'S EDITOR-TYPE MENU for this area: the Timeline, the Action Editor or the NLA.
-      id: 'editor',
-      title: 'Animation: Show Editor',
-      run: (args) => {
-        const editor = args?.['editor'] ?? args?.['to'];
-        if (editor !== 'timeline' && editor !== 'action' && editor !== 'nla')
-          return refuse('editor is `timeline`, `action` (the Action Editor) or `nla`.');
-        setTimelineViewState({ editor });
-        return report();
-      },
+/** The view's verbs: the Code-OSS commands `volter.timeline.<verb>`, registered by editor-blender's page half. */
+export const TIMELINE_VIEW_VERBS: readonly ViewVerb[] = [
+  { id: 'state', run: () => report() },
+  {
+    // BLENDER'S EDITOR-TYPE MENU for this area: the Timeline, the Action Editor or the NLA.
+    id: 'editor',
+    run: (args) => {
+      const editor = args?.['editor'] ?? args?.['to'];
+      if (editor !== 'timeline' && editor !== 'action' && editor !== 'nla')
+        return refuse('editor is `timeline`, `action` (the Action Editor) or `nla`.');
+      setTimelineViewState({ editor });
+      return report();
     },
-    {
-      id: 'frame',
-      title: 'Timeline: Set Frame',
-      run: (args) => {
-        const frame = Number(args?.['frame'] ?? args?.['to']);
-        if (!Number.isFinite(frame))
-          throw new Error('frame needs a numeric `frame` — a Blender frame number.');
-        return scrubTo(frame);
-      },
+  },
+  {
+    id: 'frame',
+    run: (args) => {
+      const frame = Number(args?.['frame'] ?? args?.['to']);
+      if (!Number.isFinite(frame))
+        throw new Error('frame needs a numeric `frame` — a Blender frame number.');
+      return scrubTo(frame);
     },
-    {
-      id: 'play',
-      title: 'Timeline: Play',
-      run: () => {
-        if (liveAnimation() !== null) throw new Error(GAME_RUNNING);
-        if (!blenderSkin.playable) throw new Error(NOT_PLAYABLE);
-        const handle = transport();
-        if (!handle)
-          throw new Error('No stage transport is attached yet; open the model document first.');
-        handle.play();
-        return report();
-      },
+  },
+  {
+    id: 'play',
+    run: () => {
+      if (!blenderSkin.playable) throw new Error(NOT_PLAYABLE);
+      const handle = transport();
+      if (!handle)
+        throw new Error('No stage transport is attached yet; open the model document first.');
+      handle.play();
+      return report();
     },
-    {
-      id: 'pause',
-      title: 'Timeline: Pause',
-      run: () => {
-        // The bookmark write is no longer this look's: pausing SETTLES the
-        // transport, and the skin's `onSettled` subscription is what writes
-        // `frame_current` once.
-        const handle = transport();
-        if (!handle) return refuse('No stage transport is attached yet.');
-        handle.pause();
-        return report();
-      },
+  },
+  {
+    id: 'pause',
+    run: () => {
+      // The bookmark write is not this look's: pausing SETTLES the
+      // transport, and the skin's `onSettled` subscription is what writes
+      // `frame_current` once.
+      const handle = transport();
+      if (!handle) return refuse('No stage transport is attached yet.');
+      handle.pause();
+      return report();
     },
-    {
-      id: 'jump-start',
-      title: 'Timeline: Jump to Start',
-      run: () => scrubTo(blenderSkin.state().start),
+  },
+  {
+    id: 'jump-start',
+    run: () => scrubTo(blenderSkin.state().start),
+  },
+  {
+    id: 'jump-end',
+    run: () => scrubTo(blenderSkin.state().end),
+  },
+  {
+    id: 'next-keyframe',
+    run: () => {
+      const frame = blenderSkin.frame();
+      const next = summaryFrames().find((key) => key > frame + 1e-4);
+      if (next === undefined) return report();
+      return scrubTo(next);
     },
-    {
-      id: 'jump-end',
-      title: 'Timeline: Jump to End',
-      run: () => scrubTo(blenderSkin.state().end),
+  },
+  {
+    id: 'prev-keyframe',
+    run: () => {
+      const frame = blenderSkin.frame();
+      const previous = summaryFrames()
+        .reverse()
+        .find((key) => key < frame - 1e-4);
+      if (previous === undefined) return report();
+      return scrubTo(previous);
     },
-    {
-      id: 'next-keyframe',
-      title: 'Timeline: Next Keyframe',
-      run: () => {
-        const frame = blenderSkin.frame();
-        const next = summaryFrames().find((key) => key > frame + 1e-4);
-        if (next === undefined) return report();
-        return scrubTo(next);
-      },
+  },
+  {
+    id: 'view-all',
+    run: () => {
+      requestTimelineViewAll();
+      return report();
     },
-    {
-      id: 'prev-keyframe',
-      title: 'Timeline: Previous Keyframe',
-      run: () => {
-        const frame = blenderSkin.frame();
-        const previous = summaryFrames()
-          .reverse()
-          .find((key) => key < frame - 1e-4);
-        if (previous === undefined) return report();
-        return scrubTo(previous);
-      },
+  },
+  {
+    id: 'zoom',
+    run: (args) => {
+      const to = Number(args?.['to'] ?? args?.['zoom']);
+      if (!Number.isFinite(to))
+        throw new Error('zoom needs a numeric `to` — CSS pixels per frame, 0.25 … 200.');
+      const { transform, size } = timelineViewState();
+      const centre = transform.startFrame + size.w / 2 / transform.pixelsPerFrame;
+      const pixelsPerFrame = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, to));
+      setTimelineViewState({
+        transform: { pixelsPerFrame, startFrame: centre - size.w / 2 / pixelsPerFrame },
+      });
+      return report();
     },
-    {
-      id: 'view-all',
-      title: 'Timeline: View All',
-      run: () => {
-        requestTimelineViewAll();
-        return report();
-      },
+  },
+  {
+    id: 'pan',
+    run: (args) => {
+      const frames = Number(args?.['frames'] ?? 0);
+      if (!Number.isFinite(frames)) throw new Error('pan needs a numeric `frames`.');
+      const { transform } = timelineViewState();
+      setTimelineViewState({
+        transform: { ...transform, startFrame: transform.startFrame + frames },
+      });
+      return report();
     },
-    {
-      id: 'zoom',
-      title: 'Timeline: Zoom',
-      run: (args) => {
-        const to = Number(args?.['to'] ?? args?.['zoom']);
-        if (!Number.isFinite(to))
-          throw new Error('zoom needs a numeric `to` — CSS pixels per frame, 0.25 … 200.');
-        const { transform, size } = timelineViewState();
-        const centre = transform.startFrame + size.w / 2 / transform.pixelsPerFrame;
-        const pixelsPerFrame = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, to));
-        setTimelineViewState({
-          transform: { pixelsPerFrame, startFrame: centre - size.w / 2 / pixelsPerFrame },
-        });
-        return report();
-      },
-    },
-    {
-      id: 'pan',
-      title: 'Timeline: Pan',
-      run: (args) => {
-        const frames = Number(args?.['frames'] ?? 0);
-        if (!Number.isFinite(frames)) throw new Error('pan needs a numeric `frames`.');
-        const { transform } = timelineViewState();
-        setTimelineViewState({
-          transform: { ...transform, startFrame: transform.startFrame + frames },
-        });
-        return report();
-      },
-    },
-    ...(Object.keys(REFUSALS) as (keyof typeof REFUSALS)[]).map((id) => ({
-      id,
-      run: () => refuse(REFUSALS[id]),
-    })),
-  ],
-});
+  },
+  ...(Object.keys(REFUSALS) as (keyof typeof REFUSALS)[]).map((id) => ({
+    id,
+    run: () => refuse(REFUSALS[id]),
+  })),
+];
 
 /** This area's id in `model.layout.ts`, the one workspace that places this document. */
 const BOTTOM_AREA = 'timeline';
 
-/**
- * THE BOTTOM AREA IS BLENDER'S ANIMATION EDITORS IN ANIMATION MODE (the Timeline, the Action
- * Editor or the NLA, by the editor-type menu) AND THE GAME PANEL IN GAME MODE
- * (`../src/play-mode.ts`, for the model document on screen). Same area: the
- * layout's `areas` entry names this document either way. NOT THE SAME SIZE:
- * Blender's measured Timeline strip (`model.layout.ts`) left the Game panel's
- * play log one clipped line, so Game mode asks the area for the panel's own
- * share (`GAME_PANEL_RATIO`) and Movie mode hands Blender's back. Each switch
- * stands the area up at its mode's size; a person's resize holds until the
- * next switch. The Timeline unmounts in Game mode; a document that opens as a
- * game therefore never pays for the rig bind (the cost note in
- * `BlenderTimeline`), and one bound earlier keeps its bind, which the Timeline
- * never undoes.
- */
+/** The bottom area swaps animation editors for the Play tool’s Panel. Each mode applies its own area ratio; manual resizing holds until the next switch. Animation unmounts during Game mode and keeps any existing rig bind. */
 export default function BlenderBottomArea() {
   useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
   useSyncExternalStore(subscribeTimelineView, timelineViewVersion, timelineViewVersion);
@@ -404,18 +303,17 @@ export default function BlenderBottomArea() {
   // The Timeline keeps Blender's strip; the Action Editor and NLA list channels, so they take the
   // Game panel's share, as a person would drag the area up to read them.
   const tall = game || editor !== 'timeline';
-  useEffect(() => setWorkspaceAreaRatio(BOTTOM_AREA, tall ? GAME_PANEL_RATIO : null), [tall]);
-  useEffect(() => () => setWorkspaceAreaRatio(BOTTOM_AREA, null), []);
-  if (game) return <BlenderGamePanel />;
+  const Panel = useSyncExternalStore(subscribeModelPlayExtension, () => modelPlayExtension()?.Panel ?? null, () => null);
+  useEffect(() => editorHost().workspace.setAreaRatio(BOTTOM_AREA, tall ? PLAY_PANEL_RATIO : null), [tall]);
+  useEffect(() => () => editorHost().workspace.setAreaRatio(BOTTOM_AREA, null), []);
+  if (game) return Panel ? <Panel /> : null;
   if (editor === 'action') return <BlenderActionEditor />;
   if (editor === 'nla') return <BlenderNlaEditor />;
   return <BlenderTimeline />;
 }
 
 function BlenderTimeline() {
-  // THE FRESHNESS IS THE RNA DOOR'S (ruling 3, 2026-09-19): every write and
-  // every presented frame bumps it, which is exactly when a rig or an action
-  // can have moved.
+  // RNA writes and presented frames bump the version that invalidates rig and action reads.
   useSyncExternalStore(
     subscribeBlenderRna,
     blenderRnaVersion,
@@ -450,10 +348,7 @@ function BlenderTimeline() {
   // the measured box, which the verb does not have.
   const request = timelineViewAllRequest();
   useEffect(() => {
-    // `framed` starts at −1 so the FIRST pass frames and every later one waits
-    // for a real ask. It was `0` against a request counter that also starts at
-    // 0, with a `request !== 0` escape — which re-framed on every render and
-    // was one of the two feedback loops the first walk found.
+    // Start framed at −1 so the first pass frames, then wait for the view-all request counter to change.
     if (request === framed.current) return;
     framed.current = request;
     const { w } = timelineViewState().size;
@@ -476,8 +371,7 @@ function BlenderTimeline() {
   );
 
   // THE SUMMARY ROW'S OWN COLUMNS — the door's per-object report put through
-  // Blender's selection filter. `play.keyframes` is the SUBJECT's action and
-  // stays what the mixer plays; this is what the row DRAWS.
+  // Blender's selection filter. Keyframe columns describe the row; sampled tracks drive playback.
   const summary = useMemo(
     () => summaryColumns(play.summary, onlySelected),
     [play.summary, onlySelected],
@@ -505,13 +399,7 @@ function BlenderTimeline() {
     for (let frame = first; frame <= transform.startFrame + viewFrames; frame += major)
       majors.push(frame);
     const minors: number[] = [];
-    // `view2d_draw_lines` (`view2d_draw.cc:273-275`): the minor lines draw
-    // only while `(pixel_width / view_width) * (major / divisor)` — the minor
-    // step's own PIXEL distance — stays above `MIN_MAJOR_LINE_DISTANCE / 5`.
-    // It is the STEP's distance, not the frame's; dropping the step from the
-    // product hid every minor line at any zoom below 7 px per frame, which is
-    // most of them (measured on the probe: 4.76 px/frame, minor step 6, so
-    // 28.6 px between minor lines against a 7-px floor).
+    // Draw minor lines only when their pixel spacing exceeds MIN_MAJOR_LINE_DISTANCE / 5 (view2d_draw.cc). Include the minor step in the spacing calculation.
     if (minor !== null && minor * transform.pixelsPerFrame >= MIN_MAJOR_LINE_DISTANCE / 5) {
       const firstMinor = Math.ceil(transform.startFrame / minor) * minor;
       for (let frame = firstMinor; frame <= transform.startFrame + viewFrames; frame += minor)
@@ -534,17 +422,17 @@ function BlenderTimeline() {
         "Nothing in this file carries an action, so the summary row is empty — which is Blender's own empty state for a Timeline over a still file.",
       );
     warnings.push(
-      'While a clip plays, the picture is three.js evaluating the skin over the mesh columns Blender exported at the BIND frame. Anything else Blender would re-evaluate per frame — shape keys, a Displace or Cloth modifier reading the frame, a geometry driver — does not follow the playhead.',
+      'Playback samples exported object, camera, material and shape-key tracks. Modifiers and geometry drivers that require per-frame Blender evaluation are not re-evaluated by the preview.',
     );
     warnings.push(
-      `Blender puts this view's ONLY-SHOW-SELECTED toggle in the Timeline header's View MENU (\`TIME_MT_view\`'s \`layout.prop(scene, "show_keys_from_selected_only")\`, \`space_time.py\`); this header has no menu region, so the same toggle is drawn as a header button at the leading edge, where that menu sits. The filter itself is Blender's — \`ADS_FILTER_ONLYSEL\`, \`anim_filter.cc:254-270\`, tested per object at \`:2307\`.`,
+      'The View menu owns Only Show Selected; its filter applies to the summary row, while sampled playback tracks remain unchanged.',
     );
     if (onlySelected && summary.objects.length === 0 && play.summary.length > 0)
       warnings.push(
         `The summary row is empty because nothing animated is SELECTED, which is Blender's own answer with this filter on. ${play.summary.map((entry) => entry.object).join(', ')} carr${play.summary.length === 1 ? 'ies' : 'y'} an action; select it, or turn the filter off.`,
       );
     warnings.push(
-      "Markers, the cache bar and the preview range are drawn by Blender's Timeline and not here; the door carries none of them.",
+      "Movie markers are carried in the scene data; this view does not draw markers, the cache bar or preview range.",
     );
     const next = {
       drawn: {
@@ -573,14 +461,7 @@ function BlenderTimeline() {
         warnings,
       },
     };
-    // PUBLISHED ONLY WHEN IT CHANGED, and that is not an optimisation — it is
-    // the fix for a REAL LOOP the first walk found: this effect's inputs
-    // include `play`, which is a fresh object every render, so an
-    // unconditional publish re-rendered, which re-ran the effect, which
-    // published again. React caught it by name ("Maximum update depth
-    // exceeded ... Tool crashed: blender-timeline.document.tsx") and the whole
-    // area painted the crash card instead of a Timeline. A published
-    // measurement is a VALUE, so comparing values is what stops it.
+    // Publish drawing measurements only when their values change; fresh render objects alone must not create another store publication.
     if (JSON.stringify(next.drawn) !== JSON.stringify(timelineViewState().drawn))
       setTimelineViewState(next);
   }, [ruler, play, summary, onlySelected]);
@@ -589,7 +470,7 @@ function BlenderTimeline() {
   const scrubFromPointer = useCallback(
     (clientX: number) => {
       const element = canvas.current;
-      if (!element || liveAnimation() !== null) return;
+      if (!element) return;
       const box = element.getBoundingClientRect();
       transport()?.seekFrame(Math.round(toFrame(clientX - box.left)));
     },
@@ -604,11 +485,7 @@ function BlenderTimeline() {
     <div
       data-testid="blender-timeline"
       style={{
-        // FILLED FROM THE HOST BOX, NOT `height: 100%` — the measured
-        // difference between a drawer panel and an EDITOR GROUP that the UV
-        // view's walk found: in an area's auto-height content box `100%`
-        // resolves to ZERO and the view reads everything it needs with nowhere
-        // to draw it.
+        // Fill the host box with absolute positioning; percentage height has no fixed reference in an auto-height editor area.
         position: 'absolute',
         inset: 0,
         display: 'flex',
@@ -640,8 +517,7 @@ function BlenderTimeline() {
             // NOTHING IS WRITTEN HERE. Scrub-end is the TRANSPORT's — the
             // quiet after the last seek settles it, and the skin's `onSettled`
             // subscription writes `frame_current` once. A second write here
-            // would race that one and re-introduce the per-gesture double
-            // write this step removed.
+            // would race that one and write twice per gesture.
           }}
         >
           <title>Timeline</title>
@@ -696,34 +572,22 @@ function BlenderTimeline() {
               y={15.5}
               textAnchor="middle"
               fill={TIMELINE_THEME.scrubText}
-              // `draw_horizontal_scale_indicators` (`view2d_draw.cc:340-348`):
-              // the baseline is `rect.ymin + 4 * UI_SCALE_FAC` and the label is
-              // centred on the line by `x − trunc(width / 2)`. Confirmed in
-              // Blender's frame: the glyph rows are 34…41 under a 26-px header,
-              // i.e. a baseline 15.5 px below the region's top edge.
+              // draw_horizontal_scale_indicators places the baseline at rect.ymin + 4 × UI_SCALE_FAC and centers labels by x − trunc(width / 2).
               fontSize={11}
             >
               {Math.round(frame)}
             </text>
           ))}
-          {/* THE SUMMARY ROW'S DISCLOSURE TRIANGLE, at the region's leading
-              edge — Blender draws one there for the collapsed summary channel
-              (`ANIM_channel_draw`'s expand icon; measured on Blender 5.2.0 LTS
-              as a small `>` at x~4 on the channel row). It is DRAWN, not
-              clickable: expanding the summary would list per-object channels,
-              which is the Dope Sheet's job and is not built — the same reason
-              `insert-key` and friends are recorded refusals rather than
-              controls. */}
+          {/* The summary disclosure is drawn read-only. Per-object channels belong to the Action Editor; channel and key edits refuse by name. */}
           <path
             d={`M3,${rowCentre - 3.5} L6.5,${rowCentre} L3,${rowCentre + 3.5} Z`}
             fill={TIMELINE_THEME.scrubText}
           />
           {/* THE SUMMARY ROW'S KEYS. Blender's Timeline draws exactly one
-              channel — see `TIMELINE_ROWS` for the two source facts that make
-              that so — and its diamonds are the shader's shape. The columns
+              channel (`anim_filter.cc:3845-3849`; the names region is hidden in
+              Timeline mode, `space_action.cc:785-790`) — and its diamonds are the shader's shape. The columns
               are the SELECTION-FILTERED merge (`summaryColumns`), which is
-              what `show_keys_from_selected_only` decides; the action the mixer
-              plays is `play.keyframes` and is unaffected. */}
+              what `show_keys_from_selected_only` decides; sampled playback tracks are unaffected. */}
           {summary.columns.map((key) => {
             const factor = KEY_SIZE_FACTOR[key.type] ?? 1;
             const radius = DIAMOND_RADIUS * factor;
@@ -786,47 +650,7 @@ function BlenderTimeline() {
   );
 }
 
-/**
- * THE HEADER — `space_time.py`'s `playback_controls`, read as the
- * SPECIFICATION of what to draw and never run (the standing ruling). Its order
- * is that function's, top to bottom: the Playback popover, a spacer, the
- * auto-key toggle, the SIX transport buttons
- * (`screen.frame_jump` REW → `screen.keyframe_jump` PREV_KEYFRAME →
- * `screen.animation_play` PLAY_REVERSE → PLAY → `keyframe_jump` NEXT_KEYFRAME
- * → `frame_jump` FF), the time-jump pair, the snap toggle, a spacer, the frame
- * field, and the Start/End pair.
- *
- * WHAT IS DRAWN AND WHAT IS NOT. The six transport buttons and the frame field
- * are real — they are the scrub, which is the one thing this surface changes.
- * Start and End are READ-ONLY readouts, because writing them writes the file
- * (`set-range` refuses by name). The Playback and snap popovers are not drawn
- * at all: every control in them sets a preference or a tool setting that this
- * view does not read, and a popover that opens onto nothing is worse than an
- * absent one. Named here rather than painted.
- *
- * THE BUTTONS ARE 20 px — `UI_UNIT_X` (`wm_window.cc:779`'s `widget_unit`),
- * confirmed in Blender's own frame: the block of six spans exactly 120 px.
- * Their glyphs are TRACED from Blender's own icon sources the way I2's tab
- * glyphs are — see `blender-icons.source.mjs`; until that trace covers the
- * transport family they are drawn here as the plain geometric marks
- * `release/datafiles/icons_svg/{rew,prev_keyframe,play,ff}.svg` are built from
- * (a triangle, a triangle with a bar, a pair), which is a KNOWN gap and is in
- * the view's own warnings rather than implied to be Blender's mark.
- */
-/**
- * THE VIEW MENU — Blender's `TIME_MT_view`, and the reason this exists is a
- * deviation the old header admitted in its own comment: `show_keys_from_selected_only`
- * belongs in a View MENU (`space_time.py`'s `layout.prop`), and with no menu
- * region it was drawn as a lone toggle at the leading edge instead.
- *
- * Measured against Blender 5.2.0 LTS at 1728x997: its header's leading cluster
- * is an editor-type dropdown then `View`, `Marker` and `Playback`. This builds
- * `View` and ONLY `View`, because View is the one whose items this surface
- * actually has — `Only Show Selected` and `Frame All`. `Marker` and `Playback`
- * would be empty shells over behaviour that does not exist here, and a menu
- * that exists to look like Blender is exactly the invented affordance the
- * program forbids. Their absence is a STATED gap in WORK.md, not a pretence.
- */
+/** View exposes Only Show Selected and Frame All. Marker and Playback menus are omitted because their actions are unsupported. */
 function TimelineViewMenu() {
   useSyncExternalStore(subscribeTimelineView, timelineViewVersion, timelineViewVersion);
   const { onlySelected } = timelineViewState();
@@ -900,22 +724,20 @@ function TimelineViewMenu() {
   );
 }
 
+/** Transport and frame controls follow Blender's Timeline order and draw inline SVG marks; range readouts stay read-only. */
 function TimelineHeader() {
   useSyncExternalStore(subscribeBlenderSkin, blenderSkinVersion, blenderSkinVersion);
   useSyncExternalStore(subscribeTimelineView, timelineViewVersion, timelineViewVersion);
   const play = blenderSkin.state();
   const unit = TIMELINE_CHROME.unit;
-  // WHILE A GAME RUNS the transport is held: the game owns its copy, and moving the document's
-  // frame under it would put two clocks on one picture.
-  const gameRunning = useSyncExternalStore(subscribeLiveAnimation, liveAnimation, () => null) !== null;
   // Static scenes have a timeline too. Disable only while its scene/transport
   // is unavailable, using the same condition as the command door.
-  const playable = blenderSkin.playable && !gameRunning;
+  const playable = blenderSkin.playable;
   const button = (key: string, glyph: ReactNode, onClick: () => void, label: string) => (
     <button
       key={key}
       type="button"
-      title={playable ? label : `${label} — ${gameRunning ? GAME_RUNNING : NOT_PLAYABLE}`}
+      title={playable ? label : `${label} — ${NOT_PLAYABLE}`}
       aria-label={label}
       disabled={!playable}
       onClick={onClick}
@@ -954,16 +776,11 @@ function TimelineHeader() {
       }}
     >
       {/* GAME | ANIMATION in place of the title, as in the Game panel, so the person switches back
-          from either (`blender-game-panel.tsx`); without a Play tool or a model, the title. */}
+          from either (`blender-play-area.tsx`); without a Play tool or a model, the title. */}
       <PlayModeSwitch title="Timeline" />
       <AnimationEditorMenu />
       <TimelineViewMenu />
-      {/* TWO SPACERS, which is what CENTRES the transport. Blender's Timeline
-          header is three clusters: the menus at the leading edge, the
-          transport in the MIDDLE, and the frame/range fields trailing
-          (measured against Blender 5.2.0 LTS at 1728x997 — its transport sits
-          at roughly x 860-1160 of 2832, dead centre; ours was hard against
-          the right edge beside the frame field). */}
+      {/* Two spacers centre transport between the leading menus and trailing frame/range fields. */}
       <div style={{ flex: 1 }} />
       <div style={{ display: 'flex' }}>
         {button(
@@ -972,11 +789,7 @@ function TimelineHeader() {
           () => transport()?.seekFrame(play.start),
           'Jump to Start',
         )}
-        {/* PREV/NEXT KEYFRAME are a DOUBLE triangle in Blender, distinct from
-            jump-to-start/end's bar-and-triangle. We drew the same path for
-            both, so four buttons carried two glyphs and a person could not
-            tell "go to the start" from "go to the previous key" — caught by
-            putting our header beside Blender's, not by reading the code. */}
+        {/* Previous and next keyframe use double triangles, distinct from jump-to-boundary bar-and-triangle marks. */}
         {button(
           'prev-key',
           mark('M5 2.5v7L1.5 6zM8.5 3.2L11 6L8.5 8.8L6 6z'),
@@ -988,10 +801,7 @@ function TimelineHeader() {
           },
           'Jump to Previous Keyframe',
         )}
-        {/* PLAY REVERSE, which Blender has beside play and we did not. The
-            engine's clock has carried the direction all along
-            (`AnimationClock.play(direction)`); nothing new is invented here,
-            the button just asks for the arm that already existed. */}
+        {/* Reverse playback uses the stage transport's direction. */}
         {playable && playing()
           ? button('pause-rev', mark('M3 2h2v8H3zM7 2h2v8H7z'), () => transport()?.pause(), 'Pause')
           : button(