@volter/editor-blender 0.1.150 → 0.1.151

package/contributions/blender-outliner-model.ts

@@ -1,18 +1,4 @@
-/**
- * WHAT THE OUTLINER IS LOOKING AT — the page-side half of the TREE door
- * (WORK.md §Blender in the tab is Blender, "Inspection parity", I3).
- *
- * The same shape as `blender-properties-model.ts`, and deliberately: a plain
- * React-free store with `subscribe` / `version` / `state`, one read driven by
- * the thing that displays it, re-read on every PRESENT because every mutation
- * presents (`session.py::dispatch`) and a frame is the tab's one signal that
- * what it is showing is stale.
- *
- * WHAT IT IS NOT. It holds no tree of its own making: `rows` is the engine's
- * answer, kept verbatim, and the only thing this module derives is the two
- * indexes a hierarchy provider needs — a row by id, and a row's parent — so
- * `HierarchyProvider.node(id)` is a lookup rather than a walk.
- */
+/** Page-side Outliner store: retain the engine’s rows verbatim and derive indexes by row id and parent id. subscribe/version/state serve React and the adapter; frames and restriction writes invalidate the tree. */
 
 import type { BlenderOutlinerRow, BlenderOutlinerTree } from '@volter/blender-engine/browser/rna';
 import { editorHost } from '@volter/sdk/host';
@@ -24,10 +10,7 @@ import {
   blenderSessionStarted,
 } from '../host/blender-runtime-host';
 
-/** The presented view, as much of it as this module reads — structurally
- *  typed for the same reason `blender-properties-model.ts` narrows it: the
- *  document that published it and the reader are two modules meeting over one
- *  object, and `@volter/editor-blender` holds no host import. */
+/** The Model context fields this SDK-host reader uses, validated at publication. */
 export interface PresentedView {
   readonly root: THREE.Object3D;
   subscribeFrames(listener: () => void): () => void;
@@ -45,7 +28,7 @@ export interface PresentedView {
   setStageMode(mode: string | null): void;
   /** A pose moved mid-gesture, drawn by the other views of the model — see
    *  `BlenderRuntimeView.mirrorPose`. */
-  mirrorPose?(object: THREE.Object3D): void;
+  mirrorPose(object: THREE.Object3D): void;
 }
 
 const isPresentedView = (value: unknown): value is PresentedView =>
@@ -145,14 +128,7 @@ export function blenderOutlinerState(): BlenderOutlinerState {
   return state;
 }
 
-/**
- * THE READ NEVER STARTS INSIDE A RENDER, and that is I1's correction applied
- * here rather than rediscovered: the hierarchy asks for the tree from inside
- * React's render pass, and the read's first act is to publish `loading`, which
- * is a `setState` in every subscriber ("Cannot update a component … while
- * rendering a different component"). The WANT is recorded synchronously so a
- * second ask in the same pass queues nothing; the read runs on the next turn.
- */
+/** Retain the latest selection and defer its tree read outside React render; newer requests supersede it. */
 function scheduleRead(key: string): void {
   if (scheduled === key) return;
   scheduled = key;
@@ -168,17 +144,10 @@ function scheduleRead(key: string): void {
  *
  * Two reads can be in flight at once: a frame arrives and schedules one
  * (`onFrame`), and a structural verb asks for one of its own
- * ({@link refreshBlenderOutliner}). Staleness used to be judged by comparing
- * `readFor` against the read's own key, which answers a different question —
- * "is this still the selection anyone wants?" — and gets the ordering wrong
- * the moment the two reads carry DIFFERENT keys: whichever started last owns
- * `readFor`, so the other one's answer is thrown away even when it is newer.
- *
- * MEASURED 2026-09-21: Add ▸ Mesh ▸ UV Sphere created the sphere, the verb's
- * own read was discarded by that comparison, and the verb then looked for the
- * new row in the tree from BEFORE the add and found none — so nothing was
- * selected. The frame's read landed a moment later and the row appeared, which
- * is why the defect looked like "selection only".
+ * ({@link refreshBlenderOutliner}). Judging staleness by comparing `readFor`
+ * against the read's own key answers a different question — "is this still the
+ * selection anyone wants?" — and gets the ordering wrong when the two reads
+ * carry DIFFERENT keys, throwing away a newer answer.
  *
  * The sequence says exactly what the guard means: the LAST READ STARTED is the
  * one whose answer the panel shows. {@link readFor} keeps its other job, which
@@ -216,17 +185,7 @@ async function read(selected: readonly string[]): Promise<void> {
   }
 }
 
-/**
- * A frame arrived: the tree the engine holds may be a different tree (an object
- * added, a modifier stacked, a collection excluded). Re-read it.
- *
- * IT RE-READS THE LAST SELECTION, NOT `readFor`, and that distinction is the
- * second half of the defect above: `readFor` is the IDEMPOTENCE marker and a
- * successful column write clears it deliberately (the value it holds is now
- * stale), so a frame arriving after one found nothing to re-read and the eye
- * it had just written never moved. The selection the tree was last read for is
- * its own fact and outlives both.
- */
+/** A presented frame invalidates the tree. Re-read lastSelectionKey; readFor only tracks idempotence and can be cleared by a write. */
 function onFrame(): void {
   readFor = null;
   scheduleRead(lastSelectionKey);
@@ -254,27 +213,9 @@ export function onBlenderFrame(listener: () => void): () => void {
   };
 }
 
-/**
- * TAKE THE FRAME SUBSCRIPTION, AND WAIT FOR THE DOCUMENT IF IT IS NOT THERE
- * YET — which is the shape of the defect the I3 walk found: the hierarchy asks
- * for the tree the moment the panel first renders, and the Model document
- * publishes its context on its own mount, so the FIRST ask can legitimately
- * find no view. Retrying "next time someone asks" is not enough, because
- * {@link showBlenderOutliner} is idempotent by selection: nothing asks again
- * until the selection moves, so a scene mutated by a script updated the
- * viewport and left the Outliner showing the old tree for good (measured
- * 2026-09-19 — `outliner_set` hid an object and its row's eye never moved).
- * `documents.waitForContext` is the door for exactly this.
- */
+/** Subscribe to frames after the document publishes its context. The first hierarchy read can precede mount, so waitForContext completes that subscription. */
 let awaitingView = false;
-/** WHICH view the live {@link frameSubscription} is against. A document that
- *  remounts, or an engine restarted with `blender-start --fresh`, PUBLISHES A
- *  NEW `BlenderRuntimeView`; the old one's `subscribeFrames` set goes with it,
- *  so a subscription held against it is a subscription to nothing and every
- *  later present reaches no reader — the tree, and now the selection, freeze
- *  on what they last read while the viewport goes on drawing the new frames.
- *  Holding the view this subscription belongs to is what makes the identity
- *  check below possible; `frameSubscription !== null` alone cannot see it. */
+/** The view identity owning frameSubscription. Replace the subscription when a document remounts or its engine restarts. */
 let subscribedView: unknown = null;
 
 function watchFrames(): void {
@@ -317,40 +258,13 @@ export function showBlenderOutliner(selected: readonly string[]): void {
   scheduleRead(key);
 }
 
-/**
- * RE-READ THE TREE NOW, AND ANSWER WHEN IT HAS LANDED — the awaited half of
- * {@link showBlenderOutliner}, for a caller that has just CHANGED the tree and
- * must address a row that did not exist a moment ago.
- *
- * The structural verbs are the callers (`blender-outliner-authoring.ts`'s
- * `StructureProvider`): `bpy.ops.mesh.primitive_uv_sphere_add()` returns, the
- * present that follows ships a frame, {@link onFrame} schedules a read on the
- * next turn — and the verb's contract is to hand its caller the new row's id
- * and select it, which it cannot do against the tree from before the add. So
- * it asks for the read itself and awaits it, instead of polling for a row to
- * appear.
- *
- * It is the SAME read the panel drives, not a second one: `readFor` and
- * `lastSelectionKey` move with it, so the frame's own scheduled read finds the
- * selection already current and does nothing.
- */
+/** Cancel a queued read and await the current tree, following any newer read until its winner publishes. */
 export async function refreshBlenderOutliner(selected: readonly string[]): Promise<void> {
   if (!blenderSessionStarted()) return;
   // Any read already QUEUED is superseded by this one before it starts.
   scheduled = null;
   let awaited = startRead([...selected].sort());
-  // AND IT WAITS FOR WHICHEVER READ WINS, not merely for its own: a frame's
-  // read can start WHILE this one is in flight and take the sequence, in which
-  // case this one's answer is dropped and the caller must still not look at
-  // the tree until the winner has published (see {@link readSeq}).
-  //
-  // THE CHECK IS AFTER THE AWAIT, not before it, and that is the whole
-  // mechanism — a pre-test loop finds nothing newer at entry (the frame's read
-  // is scheduled on a later turn), exits at once, and returns having published
-  // nothing. Measured 2026-09-21: the first cut of this loop was pre-test, and
-  // Add ▸ Mesh ▸ Monkey still resolved its new row against the tree from
-  // before the add. It ends because each turn follows a read that started
-  // strictly later than the last.
+  // After awaiting, follow any newer read until its winner publishes. Each iteration joins a strictly later sequence, so the caller sees the current tree.
   for (;;) {
     await awaited;
     if (latestRead === awaited) return;
@@ -358,13 +272,7 @@ export async function refreshBlenderOutliner(selected: readonly string[]): Promi
   }
 }
 
-/**
- * WRITE ONE RESTRICTION COLUMN. The engine refuses a column it draws on no row
- * of that type BY NAME and this surfaces the refusal verbatim; a successful
- * write presents, and the frame that comes back re-reads the whole tree
- * through {@link onFrame} — so the eye shows the state the ENGINE holds rather
- * than the one that was clicked.
- */
+/** Write one restriction column and schedule a tree read even when unchanged frame bytes emit no signal. */
 export async function writeBlenderOutlinerColumn(
   path: string,
   column: string,
@@ -372,12 +280,7 @@ export async function writeBlenderOutlinerColumn(
 ): Promise<boolean> {
   try {
     await blenderOutlinerSet(path, column, value);
-    // RE-READ THE TREE HERE, rather than waiting for the frame the write
-    // presented. A present is not a reliable signal for a COLUMN: `hide_render`
-    // changes nothing the presenter draws, so the frame is identical and the
-    // session ships nothing — measured 2026-09-19, the render camera toggled in
-    // the engine and the row never moved. The write's own outcome is what the
-    // row has to show, so the write asks for it.
+    // Re-read after a successful column write. A change such as hide_render can leave the rendered frame identical and emit no frame signal.
     readFor = null;
     scheduleRead(lastSelectionKey);
     return true;

package/contributions/blender-play-area.tsx

@@ -0,0 +1,100 @@
+/** The bottom area shows animation editors or the model Play tool’s Panel. PlayModeSwitch stays in the header of either view, and exists only with a Play tool and model. Each switch applies the mode’s area ratio; the person’s sash resize holds between switches. */
+import { type MouseEvent, type ReactNode, useSyncExternalStore } from 'react';
+import { modelPlayExtension, subscribeModelPlayExtension } from '../src/model-play-extension';
+import { blenderSkin } from './blender-runtime-skin';
+import { type ModelPlayMode, modelPlayMode, playModeVersion, servedModelDocument, setChosenPlayMode, subscribePlayMode } from '../src/play-mode';
+import { TIMELINE_CHROME, TIMELINE_THEME } from './blender-timeline-geometry';
+
+/** Reserve 20% of the column for the Game panel; the person can resize its sash. */
+export const PLAY_PANEL_RATIO = 0.2;
+
+const extension = () => modelPlayExtension();
+
+/**
+ * FLIP A DOCUMENT BETWEEN GAME AND ANIMATION. A running game keeps running when Animation is
+ * chosen: the animation editors then show what it animates. The file's animation playing in the
+ * Timeline when Game is chosen is paused (Game has no Timeline transport).
+ */
+export function switchPlayMode(documentId: string, mode: ModelPlayMode): void {
+  if (mode === 'game' && blenderSkin.transport?.snapshot().playbackState === 'playing') blenderSkin.transport.pause();
+  setChosenPlayMode(documentId, mode);
+}
+
+/** A panel button keeps the keyboard where it was. Focus left on a button would turn the
+ *  player's next Space — a jump, in most games — into a second click on Pause. */
+const keepFocus = (event: MouseEvent): void => event.preventDefault();
+
+/** The play area's button: the Timeline header's widget, at its height, keeping the keyboard where it was. */
+export function PlayAreaButton({ label, testId, disabled, pressed, wide, onClick, children }: {
+  readonly label: string;
+  readonly testId: string;
+  readonly disabled?: boolean;
+  readonly pressed?: boolean;
+  readonly wide?: boolean;
+  readonly onClick: () => void;
+  readonly children: ReactNode;
+}) {
+  const unit = TIMELINE_CHROME.unit;
+  return (
+    <button
+      type="button"
+      data-testid={testId}
+      title={label}
+      aria-label={label}
+      aria-pressed={pressed}
+      disabled={disabled}
+      onMouseDown={keepFocus}
+      onClick={onClick}
+      style={{
+        minWidth: unit,
+        height: unit,
+        padding: wide ? '0 6px' : 0,
+        border: `1px solid ${TIMELINE_CHROME.widgetOutline}`,
+        background: pressed ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widget,
+        color: TIMELINE_CHROME.widgetText,
+        font: 'inherit',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 4,
+        cursor: disabled ? 'not-allowed' : 'pointer',
+        opacity: disabled ? 0.4 : 1,
+      }}
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * GAME | ANIMATION, at the leading edge of the bottom area's header row, in the run's panel and the
+ * Timeline alike (the head of this file says why it is here). Two joined cells with the current
+ * one lit in the playhead's blue — the same widgets as the transport beside it, at the same
+ * height, so it reads as one of this row's controls and not a smaller one. It serves the model
+ * document the bottom area serves. With no Play tool installed, or no model on screen, there is
+ * nothing to switch, and the row keeps its `title` instead.
+ */
+export function PlayModeSwitch({ title }: { readonly title: string }) {
+  useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
+  const found = useSyncExternalStore(subscribeModelPlayExtension, extension, () => null);
+  const documentId = servedModelDocument();
+  if (found === null || documentId === null) return <span style={{ color: TIMELINE_CHROME.text }}>{title}</span>;
+  const mode = modelPlayMode(documentId);
+  const cell = (value: ModelPlayMode, label: string, tip: string) => (
+    <PlayAreaButton
+      testId={`model-play-mode-${value}`}
+      label={tip}
+      pressed={mode === value}
+      wide
+      onClick={() => switchPlayMode(documentId, value)}
+    >
+      {label}
+    </PlayAreaButton>
+  );
+  return (
+    <div role="group" aria-label="Game or Animation" data-testid="model-play-mode" style={{ display: 'flex' }}>
+      {cell('game', 'Game', 'Game: this area is the Game panel, with Play, pause, step, speed, restart and autoplay')}
+      {cell('animation', 'Animation', 'Animation: this area is Blender’s animation editors (Timeline, Action Editor, NLA); a running game keeps running and they show what it animates')}
+    </div>
+  );
+}