@volter/editor-blender 0.1.150 → 0.1.152

package/contributions/blender-properties-model.ts

@@ -1,37 +1,4 @@
-/**
- * WHAT THE PROPERTIES SECTIONS ARE LOOKING AT — the page-side half of the RNA
- * door (WORK.md §Blender in the tab is Blender, "Inspection parity", I1).
- *
- * React-free ON PURPOSE: this module is a plain store with `subscribe` /
- * `version` / `state`, so the host's Blender side can import it without
- * pulling React into its closure, and the sections read it through one
- * `useSyncExternalStore` (`blender-properties-view.tsx`).
- *
- * THE SUBJECT IS THE PRESENTED BLENDER CONTEXT. The person clicks a node
- * in our viewport; the adapter hands that node's `THREE.Object3D`; the
- * presented view answers which Blender object that three object IS
- * (`BlenderRuntimeView.blenderObjectName`, a lookup by object identity in the
- * frame's own table — never a name match). That name goes to
- * `rna_context(object=…)`, which builds the Properties context around it
- * exactly as `buttons_context.cc` builds one around
- * `BKE_view_layer_active_object_get`. Reading our selection never WRITES the
- * engine's active object: that is a mutation, and the document would save it.
- * With no selected node, the presented frame's active object remains the
- * Properties subject; no active object resolves the scene instead.
- *
- * WHEN IT RE-READS. Three times, and each is a signal rather than a poll:
- *  - a PRESENT (`BlenderRuntimeView.subscribeFrames`) — every mutation
- *    presents (`session.py::dispatch`), so a frame is "what you are showing is
- *    stale";
- *  - the RNA DOOR'S OWN VERSION (`subscribeBlenderRna`, ruling 3 of
- *    2026-09-19) — because a write can change what RNA answers and nothing the
- *    presenter draws, so no frame ships: `Node.panel_states[n].is_collapsed`
- *    and `Object.hide_render` are the two measured cases;
- *  - the SELECTION moving to another datablock.
- * A re-read that changes which TABS exist also calls the host door's
- * `documents.contextChanged`, because the tab rail IS the section list and
- * nothing in a host store moved.
- */
+/** React-free Properties store over the RNA door. Resolve the subject from the presented Blender context without mutating selection. Re-read on presented frames, RNA writes and selection changes; notify documents.contextChanged whenever the resolved tab context changes. */
 
 import type { BlenderRnaContext, BlenderRnaView } from '@volter/blender-engine/browser/rna';
 import { editorHost } from '@volter/sdk/host';
@@ -41,9 +8,12 @@ import {
   blenderRna,
   blenderRnaContext,
   blenderRnaSet,
+  blenderModelChanging,
+  blenderModelConflict,
   blenderSessionStarted,
   noteBlenderRnaChanged,
   subscribeBlenderRna,
+  subscribeBlenderStarting,
 } from '../host/blender-runtime-host';
 import { blenderOutlinerState } from './blender-outliner-model';
 
@@ -65,13 +35,10 @@ const isPresentedView = (value: unknown): value is PresentedView =>
   typeof (value as PresentedView).blenderObjectName === 'function' &&
   typeof (value as PresentedView).blenderSelection === 'function';
 
-/** The active authoring adapter, as much of it as this module reads. The
- *  adapter is deliberately `unknown` at the contribution point (adapter-native
- *  API, never a fabricated projection), and `@volter/editor-blender` holds no host
- *  import — so the shape it needs is stated here and checked at runtime. */
+/** The adapter-native fields this SDK-host reader uses, checked at runtime. */
 interface Object3DAuthoringLike {
   readonly documentId: string;
-  readonly hierarchy: { object3D(id: string): THREE.Object3D | null };
+  readonly hierarchy: { nativeObject(id: string): THREE.Object3D | null };
   readonly documentRootObject: THREE.Object3D | null;
 }
 
@@ -79,7 +46,7 @@ const isObject3DAuthoring = (value: unknown): value is Object3DAuthoringLike =>
   typeof value === 'object' &&
   value !== null &&
   typeof (value as Object3DAuthoringLike).documentId === 'string' &&
-  typeof (value as Object3DAuthoringLike).hierarchy?.object3D === 'function';
+  typeof (value as Object3DAuthoringLike).hierarchy?.nativeObject === 'function';
 
 function presentedView(): PresentedView | null {
   const published = editorHost().documents.context(blenderPresentationDocumentId());
@@ -127,20 +94,14 @@ export function resolveBlenderSubject(
   if (node.id === adapter.documentId)
     return adapter.documentRootObject === view.root ? { kind: 'scene' } : null;
   // A COLLECTION ROW HAS NO OBJECT, so it has to be resolved before the object
-  // lookup rather than after it — `object3D` answers null for one, which is the
-  // honest answer and used to end the resolution here (I3's standing OPEN: the
-  // rail simply stayed on the previous subject). The row table is this
+  // lookup rather than after it — `nativeObject` answers null for one, which would
+  // leave the rail on the previous subject. The row table is this
   // package's own (`blender-outliner-model.ts`), so this is a map lookup.
   const row = blenderOutlinerState().byId.get(node.id);
   if (row?.type === 'TSE_LAYER_COLLECTION') return { kind: 'collection', path: row.path };
-  const object = adapter.hierarchy.object3D(node.id);
+  const object = adapter.hierarchy.nativeObject(node.id);
   if (object === null) return null;
-  // THE SCENE COLLECTION IS THE SCENE SUBJECT. Under I3 the hierarchy is
-  // Blender's Outliner, whose root row is the Scene Collection and NOT a
-  // document row of the host's — so the row that stands for the whole file is
-  // the one whose object is the presented ROOT, and it stands for exactly what
-  // the document row did: the tabs that need no object (Render, Output, View
-  // Layer, Scene, World, Collection).
+  // The Scene Collection root resolves the scene subject and its object-independent Properties tabs.
   if (object === view.root) return { kind: 'scene' };
   const name = view.blenderObjectName(object);
   return name === null ? null : { kind: 'object', name };
@@ -185,6 +146,8 @@ let contextRequest = 0;
 /** Views read at the current generation. A held view outside this set is
  *  STALE: still shown, re-read on the next ask. */
 const fresh = new Set<string>();
+/** Paths Blender answered with nothing at the current generation: it holds no model. */
+const answeredNothing = new Set<string>();
 
 function publish(next: Partial<BlenderPropertiesState>, tabsMayHaveChanged = false): void {
   state = { ...state, ...next };
@@ -211,50 +174,30 @@ export function blenderPropertiesState(): BlenderPropertiesState {
   return state;
 }
 
-/** THE ENGINE MOVED: everything read off it is stale. The CONTEXT is
- *  re-read immediately (the tabs may have changed — a modifier was added, a
- *  bone became active); the datablock views are dropped and re-read by
- *  whichever section is still showing them.
- *
- *  Two things call this, and the second is why it is no longer named
- *  `onFrame`: a PRESENTED FRAME, and the RNA door's own version (ruling 3,
- *  2026-09-19 — `blenderRnaVersion`). A write that changes nothing the
- *  presenter draws ships no frame, and before this the rail simply kept the
- *  values it had. */
+/** Invalidate datablock caches and re-read context on RNA version changes, including writes that produce no presented-frame change. */
 function onEngineMoved(): void {
   // STALE, NOT EMPTY. The generation moves, so every answer already in flight
   // is dropped when it lands (a deleted duplicate's late read cannot overwrite
   // the new selection) -- but the panel keeps showing what it holds until the
-  // re-read answers. Clearing here blanked and repainted the whole Properties
-  // panel on every edit, because every edit presents a frame.
+  // re-read answers. Keep the settled panel visible while each edit presents its frame.
   const subject = readFor;
   readGeneration += 1;
   inFlight.clear();
   fresh.clear();
+  answeredNothing.clear();
   if (subject !== null) scheduleContextRead(subject, true);
   else publish({});
 }
 
-// THE FRAME IS ONE SIGNAL AND THE RNA DOOR IS THE OTHER. This subscription is
-// module-level rather than taken beside the frame one, because the RNA door
-// exists from the first import while the document's view arrives later — and a
-// write made before the first present is exactly the case that went unseen.
+// Subscribe on module import so RNA writes before the first presented frame
+// also invalidate the context. Frame changes provide the other signal.
 subscribeBlenderRna(() => {
   onEngineMoved();
 });
 
-/**
- * THE READ NEVER STARTS INSIDE A RENDER. `showBlenderSubject` is called from a
- * tab's `match()`, which the host runs while it is RENDERING the workspace —
- * and the read's first act is to publish `loading`, which is a `setState` in
- * every subscribed component. React said so by name ("Cannot update a
- * component (BlenderPropertiesSection) while rendering a different
- * component"), measured live 2026-09-19. The WANT is recorded
- * synchronously so a second matcher in the same pass does not queue a second
- * read; the read itself runs on the next turn of the loop, outside the render.
- */
 let scheduledKey: string | null = null;
 
+/** Queue the context read outside React render; record the request synchronously to deduplicate matchers in the same composition. */
 function scheduleContextRead(key: string, refresh = false): void {
   if (scheduledKey === key) return;
   scheduledKey = key;
@@ -278,12 +221,7 @@ function watchFrames(): void {
   if (frameSubscription !== null) return;
   const view = presentedView();
   if (view === null) return;
-  // A FRAME IS REPORTED TO THE RNA DOOR'S VERSION, not consumed here. The
-  // subscription lives in this module because this module is what the document
-  // publishes its view to, but the signal belongs to every view over the
-  // engine — so it is minted in ONE place (ruling 3) and this module hears its
-  // own frame back through `subscribeBlenderRna` above, exactly as the node
-  // view and the UV view do.
+  // Report frames through the shared RNA version so Properties, node and UV views receive the same engine-change signal.
   frameSubscription = view.subscribeFrames(noteBlenderRnaChanged);
 }
 
@@ -297,6 +235,7 @@ async function readContext(key: string, refresh = false): Promise<void> {
     readGeneration += 1;
     inFlight.clear();
     fresh.clear();
+    answeredNothing.clear();
   }
   const generation = readGeneration;
   const request = ++contextRequest;
@@ -311,17 +250,22 @@ async function readContext(key: string, refresh = false): Promise<void> {
       publish({ loading: false, error: null });
       return;
     }
-    // ALWAYS a tab-rail notification, and that is a correction rather than a
-    // convenience: the gate a tab matches on is BOTH the subject this context
-    // was read for and the tab list, so comparing only the list missed the
-    // case that actually happens — selecting the Cube after the document row
-    // reads the SAME thirteen tabs for a different subject, the gated tabs'
-    // `state.object !== object` went false, and nothing ever said so. Measured
-    // live 2026-09-19: Collection/Modifiers/Particles/Object Data/Material
-    // disappeared on the first selection and only came back on a re-select.
+    // Notify the tab rail after every context read; both the subject identity and tab list determine matches.
     publish({ context, loading: false, error: null }, true);
   } catch (error) {
     if (generation !== readGeneration || request !== contextRequest) return;
+    if (blenderModelChanging()) {
+      // Refused while Blender changes its model (a switch): still reading, and read again once the
+      // change is over, when the tabs ask for their subject again.
+      readFor = null;
+      publish({ loading: true, error: null });
+      const stop = subscribeBlenderStarting(() => {
+        if (blenderModelChanging()) return;
+        stop();
+        publish({}, true);
+      });
+      return;
+    }
     publish({ context: null, loading: false, error: describe(error) }, true);
   }
 }
@@ -354,7 +298,11 @@ export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
       if (generation !== readGeneration) return;
       inFlight.delete(path);
       fresh.add(path);
-      if (view === null) return;
+      if (view === null) {
+        answeredNothing.add(path);
+        publish({});
+        return;
+      }
       const views = new Map(state.views);
       views.set(path, view);
       publish({ views, error: null });
@@ -362,11 +310,30 @@ export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
     .catch((error: unknown) => {
       if (generation !== readGeneration) return;
       inFlight.delete(path);
+      // Refused while Blender changes its model (a switch): the read waits for it and is asked again
+      // once the change is over (`subscribeBlenderRnaAvailability`), rather than failing.
+      if (blenderModelChanging()) return;
       publish({ error: describe(error) });
     });
   return held;
 }
 
+/** Why `path` cannot be read, in a person's words, or null while its read may still come: Blender is on another
+ *  document than the editor shows, or holds no model, or answered nothing for it. While Blender starts or changes its
+ *  model (a switch) the read waits. Its section says the reason rather than waiting on a read that will not come. */
+export function blenderRnaUnavailable(path: string): string | null {
+  if (state.views.get(path) !== undefined || blenderModelChanging()) return null;
+  const conflict = blenderModelConflict();
+  if (conflict !== null) return conflict;
+  if (!blenderSessionStarted() || answeredNothing.has(path)) return `Blender holds no model, so ${path} cannot be read.`;
+  return null;
+}
+
+/** Hear when what {@link blenderRnaUnavailable} answers may have changed. */
+export function subscribeBlenderRnaAvailability(listener: () => void): () => void {
+  return subscribeBlenderStarting(listener);
+}
+
 /**
  * WRITE ONE PROPERTY. The engine refuses a read-only one by name and this
  * surfaces that refusal verbatim; a successful write presents, and the frame
@@ -384,6 +351,7 @@ export async function writeBlenderRnaProperty(
     // The write presented; a re-read of this one datablock closes the loop
     // even if the frame listener has not been taken yet.
     fresh.delete(path);
+    answeredNothing.delete(path);
     publish({ error: null });
     return true;
   } catch (error) {

package/contributions/blender-properties-tab.tsx

@@ -1,39 +1,4 @@
-/**
- * ONE PROPERTIES TAB IS ONE `selection.inspector` CONTRIBUTION — the factory
- * every `properties-*.inspector.tsx` in this package is built from (WORK.md
- * §Blender in the tab is Blender, "Inspection parity", I1, item 3).
- *
- * WHY A TAB IS A SECTION, and not a rail of our own: under the `properties`
- * presentation the inspector's sections ARE the vertical icon rail, 1:1
- * (`packages/sdk/src/kit/components/InspectionProjection.tsx`,
- * `PropertiesColumn`). So the way to make Blender's tab rail appear is to
- * contribute Blender's tabs as sections — which is also exactly the shape I2
- * needs, because each of these modules then grows a CURATED body over the same
- * door while the generic view stays beneath it.
- *
- * WHICH TABS STAND is `buttons_context.cc`'s answer, computed in the engine
- * (`session.py::rna_context`) and read here. Two kinds of tab:
- *
- *  - `standing: 'any' | 'object'` — a tab `buttons_context.cc` builds a path
- *    to UNCONDITIONALLY given a scene (`buttons_context_path_scene`,
- *    `_view_layer`, `_world`) or given an object at all
- *    (`buttons_context_path_object`, of which only the OBJECT tab is standing
- *    here — Physics and Constraints share that path but are context-gated,
- *    because Blender's Properties editor follows the ACTIVE OBJECT rather
- *    than the row that was clicked, and only the door knows there is one).
- *    These match from the SELECTION alone, synchronously.
- *  - everything else — Modifiers (an object type set), Particles (a mesh),
- *    Object Data (the object has data), Bone (an active bone), Material,
- *    Collection, Texture — which only the engine can answer, so they match
- *    against the context the door last returned.
- *
- * THE STANDING TABS EXIST SO THE RAIL IS NEVER EMPTY: `match()` is
- * synchronous and the first composition has read nothing, so if every tab
- * waited on the door there would be no rail at all. The READ itself is driven
- * from `match` (see the note there), and when its answer lands it calls
- * `documents.contextChanged`, which re-derives the whole inspection and brings
- * the rest of the rail in.
- */
+/** Build one selection.inspector contribution per Blender Properties tab. Standing scene/object tabs match synchronously; context-dependent tabs use the engine’s answer. Matchers drive the shared read, whose publication recomposes the rail; only the active tab mounts its body. */
 
 import type {
   ToolContributionNode,
@@ -52,11 +17,7 @@ export interface BlenderPropertiesTab {
   /** Whether this tab needs the engine's answer to exist, or stands on the
    *  selection alone — see the header. */
   readonly standing?: 'any' | 'object';
-  /** BLENDER'S OWN PANELS for this tab, in Blender's order, transcribed from
-   *  the matching `scripts/startup/bl_ui/properties_*.py`
-   *  ({@link BlenderCuratedPanel}). The generic RNA view stays beneath them
-   *  under "All properties"; a tab that declares none is the generic view
-   *  alone, which is what I1 shipped. */
+  /** Curated panels follow Blender’s panel order. The generic RNA view remains beneath them under All properties. */
   readonly curated?: readonly BlenderCuratedPanel[];
 }
 
@@ -64,15 +25,7 @@ export function blenderPropertiesTabMatch(tab: BlenderPropertiesTab) {
   return (node: ToolContributionNode | null, adapter: unknown): boolean => {
     const subject = resolveBlenderSubject(node, adapter);
     if (subject === null) return false;
-    // THE READ IS DRIVEN FROM `match`, NOT FROM A BODY, and that is a
-    // correction the live walk forced: under the `properties` presentation
-    // the host mounts ONLY THE ACTIVE TAB's body, so a read driven from a
-    // body never happened at all unless the person had already clicked a
-    // Blender tab — the rail showed the standing tabs and nothing else, for
-    // good (measured 2026-09-19). A matcher runs on every composition,
-    // active tab or not, so this is the one place that always sees the
-    // subject. It is idempotent by construction: `showBlenderSubject`
-    // returns immediately unless the subject moved.
+    // Drive the idempotent subject read from match, which runs for every composition even when this tab’s body is unmounted.
     showBlenderSubject(subject);
     if (tab.standing === 'any') return true;
     if (tab.standing === 'object') return subject.kind === 'object';