@volter/editor-blender 0.1.150 → 0.1.152

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.
- */
+/** A model's bottom area shows Blender's animation editors or the Play tool's Game panel; switching leaves a running game running. Remember the person's mode per model for this browser session; otherwise a model opens in Game where the project has a game (`PlayTool.hasGame`). The model on screen announces itself, so focusing the bottom area does not change which model it serves. */
 import {
-  documentPlayExtension,
-  subscribeDocumentPlayExtensions,
-} from '@volter/sdk/kit/document-play-extension';
+  playTool,
+  subscribePlayTool,
+} from './play-tool';
 
 export type ModelPlayMode = 'game' | 'animation';
 
@@ -62,7 +35,7 @@ function stored(documentId: string): ModelPlayMode | null {
 }
 
 /** The person's own pick for a document, or `null` when the default stands. */
-export function chosenPlayMode(documentId: string): ModelPlayMode | null {
+function chosenPlayMode(documentId: string): ModelPlayMode | null {
   let value = chosen.get(documentId);
   if (value === undefined) {
     value = stored(documentId);
@@ -112,17 +85,16 @@ 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 project 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');
-  if (extension === null) return 'animation';
+  const tool = playTool();
+  if (tool === null) return 'animation';
   const pick = chosenPlayMode(documentId);
   if (pick !== null) return pick;
-  const blend = sources.get(documentId);
-  return blend !== undefined && extension.hasScript?.(blend) === true ? 'game' : 'animation';
+  return sources.has(documentId) && tool.hasGame() === true ? 'game' : 'animation';
 }
 
 export function playModeVersion(): number {
@@ -135,15 +107,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 ??= subscribePlayTool(publish);
   return () => {
     listeners.delete(listener);
     if (listeners.size === 0 && stopToolWatch) {

package/src/play-tool.ts

@@ -0,0 +1,44 @@
+/**
+ * PLAY, THE PROJECT'S, as editor-blender's bottom area shows it (`registerPlay` in its API, `docs/adr/plugin-apis.md`):
+ * a Play tool (play's) owns its run, its controls and its Game view; the bottom area shows the tool's panel under every
+ * document but a model in its Animation mode, and asks the tool whether the project has a game, by which a model opens
+ * in Game or Animation (`play-mode.ts`).
+ */
+import type { ComponentType } from 'react';
+
+export interface PlayTool {
+  /** The run's panel: Play, its transport and its log. */
+  readonly Panel: ComponentType;
+  /** Whether the project has a game to play: `null` while the tool has not looked yet. */
+  hasGame(): boolean | null;
+  /** Every change of what the tool answers. */
+  subscribe(listener: () => void): () => void;
+}
+
+let registered: PlayTool | 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 playTool(): PlayTool | null {
+  return registered;
+}
+/** A registration, and every change the registered tool announces. */
+export function subscribePlayTool(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/** The API's `registerPlay`: one Play tool at a time. */
+export function registerPlay(tool: PlayTool): () => void {
+  if (registered) throw new Error('A Play tool is already registered.');
+  registered = tool;
+  const stop = tool.subscribe(publish);
+  publish();
+  return () => {
+    stop();
+    if (registered !== tool) return;
+    registered = null;
+    publish();
+  };
+}

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;