@volter/editor-blender 0.1.150 → 0.1.151

package/src/model-play-extension.ts

@@ -0,0 +1,173 @@
+/**
+ * THE MODEL DOCUMENT'S PLAY, which editor-blender owns and offers in its API (`registerModelPlay`,
+ * `docs/adr/plugin-apis.md`). A Play tool owns its controls, state and runner; the model document
+ * lends that runner its detached stage. play registers its tool from its own `activate`, through
+ * the API; the host hears only whether a document plays (`@volter/sdk/document-play-extension`).
+ */
+import { setDocumentPlaySignal } from '@volter/sdk/document-play-extension';
+import type { ComponentType } from 'react';
+
+export interface DocumentPlayControlProps {
+  readonly documentId: string | undefined;
+  readonly onClose: () => void;
+}
+/** Where the document's own area stands while its game runs (`DocumentPlayStage.edit`): a box is in fractions of the
+ *  stage. */
+export type DocumentPlayEditArea = 'live' | 'hidden' | { readonly left: number; readonly top: number; readonly width: number; readonly height: number };
+export interface DocumentPlayStage {
+  readonly documentId: string;
+  readonly sourcePath: string;
+  readonly report: (title: string, detail: string) => void;
+  /** Where the tool draws its game, over the document's own area. */
+  readonly container: HTMLElement;
+  /** The game's first frame stands. */
+  readonly ready: () => void;
+  /** THE DOCUMENT'S OWN AREA WHILE THE GAME RUNS ON: `live` brings the editing area back in front, live for editing
+   *  (its keys the editor's); a box shows it drawing in that part of the stage, taking no press (a tile among the
+   *  game's views); `hidden` puts the game in front again. */
+  readonly edit?: (area: DocumentPlayEditArea) => void;
+  /** A layer over the editing area and the play area alike, for the tool's view controls, which stand whichever area
+   *  is in front; it takes no press itself. */
+  readonly overlay?: HTMLElement;
+}
+
+/**
+ * A RUNNING GAME'S CLOCK, as the Play tool keeps it: the game's own seconds and frames, which stand still while paused
+ * and run at `speed` times the page's own clock otherwise.
+ */
+export interface DocumentPlayClock {
+  /** The game's seconds since this run began. */
+  readonly time: number;
+  /** The frames the game has run since this run began. */
+  readonly tick: number;
+  readonly paused: boolean;
+  /** Simulation seconds per real second; one of the transport's `speeds`. */
+  readonly speed: number;
+  /** While playing with no game running because the game failed to start or threw: why. The
+   *  run stays playing (a save of the game retries it); a running game clears it. */
+  readonly failure?: string | null;
+  /** A game has started in this run and is running (its first update ran). False while the run
+   *  is still preparing, and while it plays with a `failure`. A reader that must know whether Play
+   *  WORKED (the CLI's `play`) waits for this or for `failure`, never for "playing" alone. */
+  readonly running: boolean;
+}
+/**
+ * THE GAME'S TRANSPORT — what a Play tool offers beyond Play and Stop, for a layout that draws a
+ * game panel (Cyclotron's Game mode, `@volter/editor-blender`). Optional: a tool without
+ * one still plays and stops, and a layout draws only the controls a tool answers.
+ */
+export interface DocumentPlayTransport {
+  /** The speeds `setSpeed` accepts, slowest first. */
+  readonly speeds: readonly number[];
+  clock(documentId: string): DocumentPlayClock;
+  /** The clock moves every played frame, so it has a subscription of its own: `subscribe` would
+   *  re-render everything that only asks whether a document plays. */
+  subscribeClock(listener: () => void): () => void;
+  /** Hold or release the game; the answer settles once the game has. */
+  setPaused(documentId: string, paused: boolean): void | Promise<void>;
+  /** `frames` frames (one when absent), pausing the game first. */
+  step(documentId: string, frames?: number): void | Promise<void>;
+  setSpeed(documentId: string, speed: number): void | Promise<void>;
+  /** Begin the run again on a FRESH detached copy, the clock at zero. */
+  restart(documentId: string): void;
+  /** Changes on every restart. The document that lends the stage keys its detached copy on it,
+   *  so a new generation is a new copy; the change is announced through `subscribe`. */
+  generation(documentId: string): number;
+  /** Whether the running game's own bot drives the player in view, and the goals it offers; a change is announced
+   *  through `subscribeClock`. Absent, the tool has no autoplay. */
+  autoplay?(documentId: string): DocumentPlayAutoplay;
+  /** Switch the bot on (it must be offered, and the game playing) or off. On plays `goal` (the game's own when
+   *  absent); the answer settles once the goal has started. */
+  setAutoplay?(documentId: string, on: boolean, by: 'panel' | 'cli', goal?: string): void | Promise<void>;
+  /** While stopped, ask the next start to switch the bot on with `goal` as soon as its player joins. Absent, autoplay
+   *  can only be switched while running. */
+  armAutoplay?(documentId: string, armed: boolean, goal?: string): void;
+}
+/**
+ * AUTOPLAY, AS THE EDITOR OWNS IT: a game offers a bot and its goals, the editor decides whether it drives the player
+ * in view. A person's own press in the game takes it back (`takeover`).
+ */
+export interface DocumentPlayAutoplay {
+  readonly on: boolean;
+  /** The bot can be switched on for the player in view. */
+  readonly available: boolean;
+  /** Why the bot cannot be switched on now, in the tool's words (no goals, a view with no player, a player not yet
+   *  joined): the Game panel and `play state` say it. */
+  readonly unavailable?: string | null;
+  /** Who made the last change. */
+  readonly by: 'panel' | 'cli' | 'takeover' | null;
+  /** Armed while stopped (`armAutoplay`): the next start turns it on once its player joins. */
+  readonly armed?: boolean;
+  /** The goals the game's bot offers, and the one driving, armed, or the game's own. */
+  readonly behaviors?: readonly string[];
+  readonly behavior?: string | null;
+  /** A goal played where the person is not looking (a std game's headless play), and how it stands: `<goal>:
+   *  playing`, `<goal>: achieved` or `<goal>: failed — why`; null before any. */
+  readonly state?: string | null;
+}
+export interface DocumentPlayExtension {
+  readonly Control: ComponentType<DocumentPlayControlProps>;
+  readonly Menu: ComponentType<DocumentPlayControlProps>;
+  /** The run's panel, which a document's layout shows in its bottom area while it plays, when the tool has one. */
+  readonly Panel?: ComponentType;
+  playing(documentId: string): boolean;
+  /** Intended live frame shape; absent/null lets the document fill its area. */
+  aspectRatio?(documentId: string): number | null;
+  setPlaying(documentId: string, value: boolean): void;
+  escape?(documentId: string): void;
+  subscribe(listener: () => void): () => void;
+  run(stage: DocumentPlayStage): () => void;
+  /** Pause, step, speed, restart and the clock, when the tool keeps them. */
+  readonly transport?: DocumentPlayTransport;
+  /** What this tool runs to play a document's source file (a game's dev server command). */
+  scriptPath?(sourcePath: string): string;
+  /** Whether the document's source has a game to play: `null` while the tool has not looked yet. A change is announced
+   *  through `subscribe`. A layout uses it to open a document as a game or as a model. */
+  hasScript?(sourcePath: string): boolean | null;
+}
+
+let registered: DocumentPlayExtension | null = null;
+const listeners = new Set<() => void>();
+function publish(): void { for (const listener of listeners) listener(); }
+
+/** The registered Play tool, or `null` while none is. */
+export function modelPlayExtension(): DocumentPlayExtension | null {
+  return registered;
+}
+/** A registration, and every change the registered tool announces. */
+export function subscribeModelPlayExtension(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/** Whether a document's Play runs and is paused, for the host. A pause is a clock change, and the
+ *  clock moves every played frame, so its subscribers are readers whose snapshot changes rarely. */
+function signal(extension: DocumentPlayExtension) {
+  return {
+    state(documentId: string): 'playing' | 'paused' | 'stopped' {
+      if (!extension.playing(documentId)) return 'stopped';
+      return extension.transport?.clock(documentId).paused ? 'paused' : 'playing';
+    },
+    subscribe(listener: () => void): () => void {
+      const stopPlay = extension.subscribe(listener);
+      const stopClock = extension.transport?.subscribeClock(listener);
+      return () => { stopPlay(); stopClock?.(); };
+    },
+  };
+}
+
+/** The API's `registerModelPlay`: one Play tool for model documents at a time. */
+export function registerModelPlay(extension: DocumentPlayExtension): () => void {
+  if (registered) throw new Error('A Play tool already plays model documents.');
+  registered = extension;
+  const stop = extension.subscribe(publish);
+  setDocumentPlaySignal('model', signal(extension));
+  publish();
+  return () => {
+    stop();
+    if (registered !== extension) return;
+    registered = null;
+    setDocumentPlaySignal('model', null);
+    publish();
+  };
+}

package/src/node-view-state.ts

@@ -1,23 +1,4 @@
-/**
- * THE NODE VIEW'S OWN STATE, and the reason it is a module rather than a
- * `useState` inside the component.
- *
- * `editor.document.*` is scoped to the ACTIVE CENTER DOCUMENT by design — its
- * own header says so: "a selector resolving outside that document's container
- * is refused by a message naming the scope". The node editor is a DRAWER
- * utility, so nothing in the product could read or drive it: the sighted door
- * (`editor.captureEditorChrome`, `cyclotron screenshot editor`) photographs it, and
- * a photograph cannot click.
- *
- * So the view's actions are SESSION VERBS, which is the pattern the keyboard
- * ruling already asks for — a `volter.*` command per action rather than a raw
- * listener — and this module is the one place their state lives. The component
- * subscribes to it; `blender-node-view` (the command) reads and writes it. One
- * store, two readers, no second copy.
- *
- * It imports NOTHING: the host handler and the contribution both reach it, and
- * a store either of them could not import would not be one store.
- */
+/** Shared node-view store for the component and blender-node-view command. Keep pan, zoom, focus, drawing measurements and refusal in one React-free module. */
 
 export interface NodeViewTransform {
   /** The tree-space point at the view's centre. */
@@ -48,7 +29,7 @@ export interface NodeViewState {
   readonly drawn: readonly DrawnNode[];
 }
 
-export interface DrawnNode {
+interface DrawnNode {
   readonly name: string;
   readonly x: number;
   readonly yTop: number;
@@ -62,10 +43,7 @@ export interface DrawnNode {
   readonly firstSocketBelowTop: number | null;
   /** The header's colour, as drawn. */
   readonly header: string;
-  /** SOCKET PANELS, as drawn: how many the node stood and how many of those
-   *  are collapsed. A node that declares panels and drew them FLAT instead
-   *  carries the reason in `panelFallback` — the ruling's own condition,
-   *  readable rather than merely displayed. */
+  /** Count drawn socket panels and collapsed panels; panelFallback names a flat-layout limitation. */
   readonly panels: number;
   readonly collapsedPanels: number;
   readonly panelFallback: string | null;

package/src/play-mode.ts

@@ -1,35 +1,8 @@
-/**
- * GAME OR ANIMATION — what a model document's bottom area shows. It is not mutually exclusive:
- * animation is used by games too.
- *
- * - **Animation** is Blender's animation editors: the Timeline, the Dope Sheet's Action Editor and
- *   the NLA editor (`../contributions/blender-animation-editors.tsx`). While a game runs they show
- *   what the game is animating, read-only.
- * - **Game** is the Game panel (`../contributions/blender-game-panel.tsx`): the ONE Play, and the
- *   run's pause, step, speed, restart and clock.
- *
- * They are two views of one bottom area, not two exclusive states: switching to Animation leaves a
- * running game running.
- *
- * The switch is the bottom area's own, at the leading edge of its header row in the Game panel
- * and the Timeline alike (`PlayModeSwitch`, `blender-game-panel.tsx`); this module is the state
- * both sides read. A document opens as a
- * Game when its model has a play script (`*.play.ts` beside the `.blend`, as the Play tool finds
- * it — `DocumentPlayExtension.hasScript`) and in Animation otherwise, and the person's own pick
- * then stands for that document for the browser session, kept the way `area-split.ts` keeps the
- * split, per document id — in session storage rather than local, because the default is what a
- * fresh session should start from.
- *
- * THE BOTTOM AREA SERVES ONE DOCUMENT, the model document on screen. The Timeline was always
- * that (it binds the presented-view singleton, and cannot name a document), but a game panel
- * needs the id to drive a run, and clicking into the panel makes the PANEL the active workspace
- * document — so the model document announces itself here ({@link noteModelDocument}) rather
- * than the panel asking the workspace which document is active.
- */
+/** The model’s bottom area shows animation editors or the Play tool’s Game panel. Switching views leaves a run active. Remember the person’s mode per document for this browser session; otherwise use hasScript to choose the default. The Model announces its identity so focusing the bottom-area document does not change the run’s target. */
 import {
-  documentPlayExtension,
-  subscribeDocumentPlayExtensions,
-} from '@volter/sdk/kit/document-play-extension';
+  modelPlayExtension,
+  subscribeModelPlayExtension,
+} from './model-play-extension';
 
 export type ModelPlayMode = 'game' | 'animation';
 
@@ -40,6 +13,8 @@ export function playModeOf(value: unknown): ModelPlayMode | null {
 
 const STORAGE_PREFIX = 'volter.blender.play-mode:';
 const listeners = new Set<() => void>();
+/** Verbs waiting for a document to be on screen (`documentOnScreen`), told at every change. */
+const waiters = new Set<() => void>();
 /** The person's pick per document; `null` once storage was read and held none. */
 const chosen = new Map<string, ModelPlayMode | null>();
 /** Each model document's `.blend`, as the document reported it. */
@@ -50,6 +25,7 @@ let version = 0;
 function publish(): void {
   version += 1;
   for (const listener of [...listeners]) listener();
+  for (const waiter of [...waiters]) waiter();
 }
 
 function stored(documentId: string): ModelPlayMode | null {
@@ -105,6 +81,57 @@ export function servedModelDocument(): string | null {
   return served;
 }
 
+/** Model documents on screen whose file is still opening (read and first presented), the newest last. */
+const opening: string[] = [];
+
+/** An opening Model document does not serve the bottom area until presentation completes. Return its withdrawal function; documentOnScreen waits for it rather than reporting no model. */
+export function noteModelOpening(documentId: string): () => void {
+  opening.push(documentId);
+  publish();
+  return () => {
+    const at = opening.lastIndexOf(documentId);
+    if (at < 0) return;
+    opening.splice(at, 1);
+    publish();
+  };
+}
+
+/** The model document still opening on screen, or `null` with none. */
+export function openingModelDocument(): string | null {
+  return opening.at(-1) ?? null;
+}
+
+/**
+ * THE MODEL DOCUMENT ON SCREEN, once it is: the one served now, else the one opening, waited for at most `waitMs`.
+ * Answers `{ served }` once one serves the bottom area, `{ opening }` when one is still opening at the end of the wait
+ * (the caller asks again: an open can take minutes), and `null` when none is on screen or opening.
+ */
+export function documentOnScreen(waitMs: number): Promise<{ readonly served: string } | { readonly opening: string } | null> {
+  const now = (): { readonly served: string } | { readonly opening: string } | null =>
+    served !== null ? { served } : opening.length > 0 ? { opening: opening.at(-1)! } : null;
+  const first = now();
+  if (first === null || 'served' in first || waitMs <= 0) return Promise.resolve(first);
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (answer: ReturnType<typeof now>): void => {
+      waiters.delete(check);
+      clearTimeout(timer);
+      clearTimeout(recheck);
+      resolve(answer);
+    };
+    let recheck: ReturnType<typeof setTimeout> | undefined;
+    function check(): void {
+      const answer = now();
+      if (answer !== null && 'served' in answer) { clearTimeout(recheck); settle(answer); return; }
+      // (an opening withdrawn is read again a task later: the document's own commit withdraws it before its
+      // viewport announces itself, both in one commit, and only an open that ended with nothing on screen is none)
+      if (answer === null) { clearTimeout(recheck); recheck = setTimeout(() => { const later = now(); if (later === null || 'served' in later) settle(later); }, 0); }
+    }
+    waiters.add(check);
+    timer = setTimeout(() => settle(now()), waitMs);
+  });
+}
+
 /** The `.blend` a model document reported, if it has a file of its own. */
 export function modelDocumentSource(documentId: string): string | undefined {
   return sources.get(documentId);
@@ -112,12 +139,12 @@ export function modelDocumentSource(documentId: string): string | undefined {
 
 /**
  * THE MODE A DOCUMENT IS IN: Animation whenever no Play tool is installed (there is no game to
- * switch to), else the person's pick, else Game exactly when the model has a play script. A
- * script not yet looked for counts as none, so a document opens on the Timeline and turns to
+ * switch to), else the person's pick, else Game exactly when the level has a game. A
+ * game not yet looked for counts as none, so a document opens on the Timeline and turns to
  * the Game panel when the answer arrives.
  */
 export function modelPlayMode(documentId: string): ModelPlayMode {
-  const extension = documentPlayExtension('model');
+  const extension = modelPlayExtension();
   if (extension === null) return 'animation';
   const pick = chosenPlayMode(documentId);
   if (pick !== null) return pick;
@@ -135,15 +162,14 @@ export function playModeVersion(): number {
  * THE PLAY TOOL'S ANSWERS MOVE THE VERSION TOO, because the version is the snapshot every reader
  * takes (`useSyncExternalStore(subscribePlayMode, playModeVersion)`): a script found after the
  * first render, a run starting or stopping, a restart. Handing the tool's publications straight to
- * the reader's listener re-ran a snapshot that had not changed, so React kept the old render — a
- * document with a play script stayed in Animation, and the Game panel kept showing Stop after the game
- * had stopped. One subscription to the tool's registry, held while anything reads this store,
+ * the reader's listener would re-run a snapshot that had not changed, so React would keep the old
+ * render. One subscription to the tool's registry, held while anything reads this store,
  * bumps the version and then tells the readers.
  */
 let stopToolWatch: (() => void) | null = null;
 export function subscribePlayMode(listener: () => void): () => void {
   listeners.add(listener);
-  stopToolWatch ??= subscribeDocumentPlayExtensions(publish);
+  stopToolWatch ??= subscribeModelPlayExtension(publish);
   return () => {
     listeners.delete(listener);
     if (listeners.size === 0 && stopToolWatch) {

package/src/presentation.ts

@@ -1,5 +1,5 @@
 /**
- * HOW THE BLENDER STAGE BEHAVES, as its starting presentation (`@volter/sdk/kit/
+ * HOW THE BLENDER STAGE BEHAVES, as its starting presentation (`@volter/sdk/
  * viewport-presentation`): this package builds the `model` stage, so it states the stage's
  * function there, beneath every person's choice and never in the look (ARCHITECTURE.md rule 7).
  */
@@ -7,7 +7,7 @@ import {
   DOCUMENT_STUDIO_PRESET,
   registerStartingPresentation,
   type ViewportCamera,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 
 /**
  * A 3D View's field of view for its lens, as Blender computes it (`BKE_camera_params_from_view3d`,
@@ -22,19 +22,10 @@ export function blenderViewFieldOfView(lens: number): ViewportCamera['fov'] {
 }
 
 const release = registerStartingPresentation('model', {
-  // BLENDER'S VIEW: the factory `View3D.lens` of 50 mm (read back from Blender 5.2), a 71.5°
-  // angle on the larger side; and its default user perspective, elevation 26.5° and azimuth
-  // −23.8° about the up axis, SOLVED from the reference's two floor axes (projected slopes
-  // +1.0093 for X and −0.1969 for Y in `modeling-edit-none.png`), in three's Y-up frame. A file's
-  // own saved view and lens are its document's (`blender-runtime.document.tsx`).
+  // The factory Blender lens is 50 mm. The default view uses the reference floor-axis orientation in the presenter’s Y-up frame; a saved document supplies its own view and lens.
   camera: { fov: blenderViewFieldOfView(50), opening: [0.8187, 0.4458, 0.3617] },
   interaction: {
-    // BLENDER'S SHELF OPENS ON SELECT BOX, so a selected object carries no transform gizmo until
-    // one of the four transform tools is armed (`space_toolsystem_toolbar.py`:
-    // `_defs_view3d_generic.select_box` is the first entry of the Object Mode `_tools_default`
-    // tuple). Photographed at the engine's pin: `gizmo-select-box.png` has Select Box lit in the
-    // shelf, the default cube selected and outlined, and nothing at its origin but the 3D cursor
-    // and the object dot; `gizmo-move.png` has Move lit in the same frame.
+    // Open on Select Box, the first Object Mode shelf tool in space_toolsystem_toolbar.py. Show the transform gizmo only when a transform tool is armed.
     bootTool: 'select',
     // BLENDER'S SELECT BOX IS A TOUCH TEST: its object-mode box select reads the object-id buffer
     // under the rectangle, so any drawn part of an object inside it selects that object.
@@ -47,9 +38,7 @@ const release = registerStartingPresentation('model', {
   // SOLID (`clay`, and Wireframe with it) is lit by Blender's four studio lights, the document's
   // view-locked studio, and drawn under STANDARD: Blender gives Solid the display's default view
   // and none of the scene's settings (`draw_color_management.cc`, `ViewTransform`), and the sRGB
-  // display's default is Standard (`config.ocio`). Blender 5.2's Workbench under Standard gives
-  // the factory cube 142 / 131 / 112 in the default view and 162 on the front face, agreeing with
-  // the viewport's own frames (141 / 129 / 111, 161). The scene's AgX is the two modes' below.
+  // display's default is Standard (`config.ocio`). Material Preview and Rendered use AgX below.
   all: {
     lighting: {
       source: 'studio',
@@ -93,8 +82,7 @@ const release = registerStartingPresentation('model', {
     },
   },
   overlays: {
-    // BLENDER DRAWS THE SELECTED OBJECTS' ORIGINS (Overlays › Origins, on by default): the dot at
-    // the default cube's centre in every reference frame (`gizmo-select-box.png`).
+    // Draw the selected objects’ origins when the Origins overlay is enabled.
     selection: { origins: true },
   },
   world: {

package/src/regions.ts

@@ -7,53 +7,13 @@ import type { WorkspaceLayoutContribution } from '@volter/sdk/looks';
 
 export const BLENDER_REGIONS: NonNullable<WorkspaceLayoutContribution['regions']> = {
   workspaceTabs: 'shown',
-  // Blender has no document tab strip over its areas (the host's own note
-  // in `workspace-presets.ts` says so; the bundle contradicted it).
   header: 'shown',
   shelf: 'shown',
   inspector: 'properties',
-  // Measured on `modeling.png`: Blender's top-right corner carries two quiet
-  // wells (Scene, ViewLayer) and nothing brighter than the 216 its labels
-  // ink at. Ours drew a yellow FPS/ms readout, an orange sparkline and a lit
-  // audio meter there — the brightest, highest-chroma thing in the frame and
-  // the first place the eye lands. The numbers keep their door (the Profiler
-  // utility, which the readout's own tooltip names).
-  telemetry: 'hidden',
-  // Measured on `outliner.png`: Scene Collection, Collection, Camera, Cube
-  // and Light each carry their NAME and nothing after it — no type text
-  // anywhere in the frame. The type is the GLYPH, which is why the glyph is
-  // coloured by category in the first place; a row that also spelled the
-  // type would say it twice. Ours printed `Hero Box ·HeroBox` at
-  // `content.dim` in a 10px face, one `space-2` past the name.
+  // Hide hierarchy type suffixes; glyph categories identify row types.
   hierarchyTypeSuffix: 'hidden',
-  // Measured across all three Outliner frames — `outliner.png` (edit mode),
-  // `modeling-object-none.png` (object mode, nothing selected) and
-  // `modeling-object-selected.png` (object mode, everything selected):
-  // Blender draws NO rule, dotted or solid, under any name in that panel, in
-  // any selection state. Ours drew an orange dotted rule under every
-  // component-instance name — six of this scaffold's eleven rows — which is a
-  // mark with no counterpart in the frame at all. The instance fact keeps its
-  // doors (the label's tooltip, Go to Callsite / Open Component Source, the
-  // inspector's component sections); only the paint yields.
+  // Hide component-instance underline marks; tooltips, source navigation and inspector sections retain the instance information.
   hierarchyInstanceRule: 'hidden',
-  // Measured on `outliner.png`: every object row carries an EYE (CSS ink
-  // 257.5-270.5, 32 px in from the area's right edge) and a render CAMERA
-  // (277.5-290.5, 12 px in) on a 20 px column pitch, and no lock glyph
-  // anywhere — Blender's Disable Selection column is off by default. Ours
-  // drew a lock 29-41 px in and the eye 6-18 px in, so the LOCK was sitting
-  // in Blender's eye column and the eye outboard of its camera column. The
-  // lock goes, and the render column is reserved blank so the eye lands on
-  // Blender's own; `workspace-regions.ts` carries why it stays blank.
+  // Hide the selection-lock column and reserve the render-camera column so the eye occupies Blender’s column.
   hierarchyRestrictions: 'viewport+render',
-  // Measured at native 2x on `outliner.png` AND on the Properties area of
-  // `modeling-edit-none.png` — device x relative to each area's own left
-  // edge, and the two agree to half a pixel: every Blender area begins with
-  // an EDITOR-TYPE WELL at x 17..80, i.e. 8.5 CSS in and 32 CSS wide, 20
-  // tall, its glyph and a chevron inside a 1 px `#3c3c3c` outline over a
-  // `#272727` inner. It is there whether the area holds one editor or a
-  // dozen, and its dropdown is how an area changes editor. Ours began with
-  // a 203 px strip of WORDS, which is what squeezed the Outliner's search
-  // to 64 px against Blender's 115, truncated the third tab to `Libr`, and
-  // left the Properties area — a lone panel declaring no header controls —
-  // with no header band at all.
 };

package/src/start-document.ts

@@ -0,0 +1,15 @@
+/** blender-start uses an explicit file first, otherwise the active Model file before the bound pane. During Save As, the active tab can lead pane binding. An unlisted-file follow keeps the session’s new file on the tab it left. */
+export function startDocument(input: {
+  /** The file the start names, if any. */
+  readonly requested: string | undefined;
+  /** The file the editor is showing as the Model: the active tab's, else the bound pane's. */
+  readonly shown: string | undefined;
+  /** A Save As to an unlisted file, from the tab it left, for this session. */
+  readonly follow: { readonly from: string; readonly document: string } | null;
+  /** The standing Model's file, for a project with no `.blend` of its own. */
+  readonly fallback: string;
+}): string {
+  if (input.requested !== undefined) return input.requested;
+  const shown = input.shown ?? input.fallback;
+  return input.follow !== null && input.follow.from === shown ? input.follow.document : shown;
+}

package/src/timeline-view-state.ts

@@ -1,32 +1,13 @@
-/**
- * THE TIMELINE'S OWN VIEW STATE — the pan/zoom of its ruler, the last refusal,
- * the measured box, and what it drew.
- *
- * THE PLAYBACK STATE IS NOT HERE. The frame, the play/pause and the keyframe
- * columns live in the presenter's `BlenderSkinDirector`
- * (`../contributions/blender-runtime-skin.ts`), because that object OWNS the
- * `AnimationMixer` and a second copy of "what frame is it" is exactly the
- * disagreement the whole design exists to avoid. This module holds only what
- * is about the DRAWING.
- *
- * WHAT DRIVES IT IS NOT A SESSION VERB. U8's ruling 1 (2026-09-19): every view
- * publishes `volter.<view>.<verb>` commands through `@volter/sdk/views`, one
- * table behind the frame's command service and standalone `cyclotron edit`'s
- * session verb — so this view adds no `blender-*` verb of its own.
- *
- * It imports NOTHING, for the reason the node and UV stores do: the view and
- * the verb table both reach it, and a store either of them could not import
- * would not be one store.
- */
+/** React-free Timeline drawing state: ruler pan/zoom, refusal, measured box and drawn geometry. Playback belongs to BlenderSkinDirector. The page registers actions as volter.<view>.<verb> commands. */
 
-export interface TimelineTransform {
+interface TimelineTransform {
   /** The FRAME at the view's left edge, and the CSS pixels per frame. Blender's
    *  own `View2D.cur` for a time editor is exactly this pair. */
   readonly startFrame: number;
   readonly pixelsPerFrame: number;
 }
 
-export interface TimelineDrawn {
+interface TimelineDrawn {
   /** The action being played, and whose keys the summary row draws. */
   readonly action: string | null;
   readonly object: string | null;
@@ -72,23 +53,7 @@ export interface TimelineViewState {
   readonly size: { readonly w: number; readonly h: number };
   readonly framedAt: number;
   readonly drawn: TimelineDrawn | null;
-  /**
-   * BLENDER'S `show_keys_from_selected_only`, and it is VIEW state here for a
-   * reason a headless Blender forces: the flag Blender's Timeline reads is
-   * `Scene.flag & SCE_KEYS_NO_SELONLY` (`anim_filter.cc:254-270`), and this
-   * surface is an INSPECTION surface that does not write the file — so the
-   * filter's position is ours to hold and the data it filters on
-   * (`Object.select_get()`) stays Blender's.
-   *
-   * DEFAULTS ON, as Blender's does: `SCE_KEYS_NO_SELONLY` is a NEGATIVE flag
-   * and a new scene does not carry it, so a factory Blender's Timeline shows
-   * the selected objects' keys only. The reference read recorded exactly that
-   * — the probe's own Timeline drew an EMPTY summary row with the rig
-   * unselected while its Dope Sheet drew all five keys.
-   *
-   * IT DECIDES WHAT THE ROW DRAWS, NEVER WHAT PLAYS. Playback moves every
-   * object regardless, in Blender and here.
-   */
+  /** Only Show Selected is Timeline view state; keyframe subjects still come from Blender’s selection. Default it on, matching Blender’s scene flag, without writing the inspection filter into the file. */
   readonly onlySelected: boolean;
   /** Which of Blender's animation editors the bottom area shows in Animation mode: the
    *  Timeline, the Dope Sheet's Action Editor, or the NLA editor (Blender's editor-type menu). */

package/src/uv-view-state.ts

@@ -1,22 +1,6 @@
-/**
- * THE UV VIEW'S OWN STATE, and the reason it is a module rather than a
- * `useState` inside the component — the same reason `node-view-state.ts`
- * records: `editor.document.*` reaches only the ACTIVE CENTRE DOCUMENT by its
- * own contract, and this view is not one, so a `useState` here would be a
- * surface nothing in the product could read or drive.
- *
- * WHAT DRIVES IT IS NOT A SESSION VERB. U8's ruling 1 (2026-09-19): every view
- * publishes `volter.<view>.<verb>` commands through `@volter/sdk/views`,
- * one table behind the frame's command service and standalone `cyclotron edit`'s
- * session verb — so this view adds NO `blender-*` verb of its own, which is
- * exactly what the ruling asked the remaining I5 views to stop paying for.
- *
- * It imports NOTHING, for the reason the node view's store does: the view and
- * the verb table both reach it, and a store either of them could not import
- * would not be one store.
- */
+/** React-free UV drawing state shared by the view and page commands. Actions are registered as volter.blender-uv-view.<verb>. */
 
-export interface UvViewTransform {
+interface UvViewTransform {
   /** The UV-space point at the view's centre. UV space is Y-UP (v increases
    *  upward, as Blender's image space does); the view flips it once, at the
    *  SVG transform, so nothing downstream carries a sign. */
@@ -45,12 +29,12 @@ export interface UvViewState {
   readonly drawn: UvViewDrawn | null;
 }
 
-export interface UvViewDrawn {
+interface UvViewDrawn {
   readonly object: string | null;
   readonly mesh: string | null;
   readonly layer: string | null;
   readonly layers: readonly string[];
-  /** Blender's mode at the read — named, never required (ruling 1). */
+  /** Blender’s mode at the read. */
   readonly mode: string;
   readonly loops: number;
   readonly polygons: number;