@volter/editor-blender 0.1.0

package/contributions/blender-palette.source.mjs

@@ -0,0 +1,319 @@
+/**
+ * THE SOURCE of `blender.palette.json` — Blender's own default theme, read
+ * from Blender's own theme TABLE rather than eyedropped from a screenshot
+ * (WORK.md §Blender in the tab is Blender, "Inspection parity", I2 decision 7;
+ * ARCHITECTURE-CORE §Blender north star, "The reference is Blender's SOURCE as
+ * well as its frames").
+ *
+ * Run `node packages/blender/contributions/blender-palette.source.mjs` to
+ * rewrite the JSON; `--check` reports what would change and exits non-zero if
+ * anything would. It reads
+ * `release/datafiles/userdef/userdef_default_theme.c` from a Blender checkout
+ * at the engine's pin (`$BLENDER_SRC`, default `~/volter/blender-src`; the
+ * checkout recipe is in WORK.md §Blender in the tab is Blender, "Inspection
+ * parity"). That file is itself generated — `tools/utils/blender_theme_as_c.py`
+ * writes it from the shipped theme — so it is the closest thing Blender has to
+ * a machine-readable palette.
+ *
+ * ## Why this exists
+ *
+ * Every value in `blender.palette.json` used to be eyedropped off a reference
+ * frame, and I1 measured the drift that produces: `surface.panel` carried
+ * `#2f2f2f` where `.space_properties.back` is `#303030`, and `content.primary`
+ * `#e5e5e5` against `.text`'s `#e6e6e6`. One level each — invisible, and
+ * exactly the kind of error an eyedropper makes (a screenshot is a COMPOSITE:
+ * a panel fill sits under a hairline outline at 6.7% white, and a PNG's own
+ * colour management can move a level besides). The source has no such
+ * ambiguity.
+ *
+ * ## What is NOT derived, and why each one
+ *
+ * A key is derived only when its meaning is EXACTLY one theme member. The
+ * rest are stated as literals with their reason, because a false citation is
+ * worse than an honest measurement:
+ *
+ *  - a COMPOSITE Blender draws by blending two members (the viewport's axis
+ *    lines) — the source value is an input to what you see, not what you see;
+ *  - a member Blender declares with an ALPHA it composites over a surface the
+ *    palette does not carry (a region header, a popover back);
+ *  - a semantic colour Blender's theme has no member for at all (our
+ *    danger/warning/success set, which is the editor's own vocabulary).
+ *
+ * Nothing here invents a colour: every literal below names where it came from.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+// ------------------------------------------------- Blender's theme table
+
+const CHECKOUT = process.env['BLENDER_SRC'] ?? `${homedir()}/volter/blender-src`;
+const THEME = 'release/datafiles/userdef/userdef_default_theme.c';
+
+/**
+ * `userdef_default_theme.c` as `{ 'tui.panel_header': { hex, alpha, line } }`.
+ *
+ * The file is machine-generated and utterly regular — one `.member = {` per
+ * nesting level, one `.member = RGBA(0x…)` per colour — so this is a brace
+ * walk rather than a C parser. A member the walk does not recognise is
+ * skipped; a member the TABLE below names and the walk did not find is a hard
+ * error, which is what keeps this honest when Blender renames one.
+ */
+function readTheme() {
+  let text;
+  try {
+    text = readFileSync(`${CHECKOUT}/${THEME}`, 'utf8');
+  } catch {
+    throw new Error(
+      `${THEME} is not in the Blender checkout at ${CHECKOUT}. Set BLENDER_SRC, or add the ` +
+        'directory to the sparse checkout (`git sparse-checkout add release/datafiles/userdef`) ' +
+        'and re-run the LFS-off checkout line in WORK.md §Blender in the tab is Blender.',
+    );
+  }
+  const members = {};
+  const stack = [];
+  text.split('\n').forEach((line, index) => {
+    const open = /^\s*\.(\w+)\s*=\s*\{\s*$/.exec(line);
+    if (open !== null) {
+      stack.push(open[1]);
+      return;
+    }
+    if (/^\s*\},?\s*$/.test(line)) {
+      stack.pop();
+      return;
+    }
+    const value = /^\s*\.(\w+)\s*=\s*RGBA?\(0x([0-9a-fA-F]+)\)/.exec(line);
+    if (value === null) return;
+    const digits = value[2].padStart(8, '0');
+    members[[...stack, value[1]].join('.')] = {
+      hex: `#${digits.slice(0, 6).toLowerCase()}`,
+      alpha: Number.parseInt(digits.slice(6, 8), 16) / 255,
+      line: index + 1,
+    };
+  });
+  return members;
+}
+
+// ------------------------------------------------------------ the mapping
+
+/** A theme member, taken OPAQUE: Blender's `back` members carry an alpha byte
+ *  that the region fill does not use (`.space_properties.back` is `0x30303000`
+ *  and the properties editor is plainly not transparent), and a palette
+ *  surface is one colour. */
+const rgb = (member) => ({ member });
+/** A theme member taken WITH its alpha — for the members whose alpha is the
+ *  point (`.tui.widget_emboss`, `.tui.panel_outline`). */
+const rgba = (member) => ({ member, alpha: true });
+/** A value the theme has no single member for. `why` is mandatory. */
+const held = (value, why) => ({ value, why });
+
+/**
+ * PALETTE KEY → THEME MEMBER. Dotted on both sides; the left is a path into
+ * `theme.color`, the right a path into `U_theme_default`.
+ */
+const MAPPING = {
+  'surface.shell': rgb('tui.editor_border'),
+  'surface.panel': rgb('space_properties.back'),
+  'surface.chrome': held(
+    '#1c1c1c',
+    'a region HEADER is `.header` at alpha 0xb3 (`space_properties.header`) composited over the ' +
+      'window, and this palette carries ONE opaque colour for every header in the editor. ' +
+      'Measured on the reference frames.',
+  ),
+  'surface.raised': rgb('tui.wcol_regular.inner'),
+  'surface.inset': rgb('tui.wcol_text.inner'),
+  'surface.overlay': held(
+    'rgba(48,48,48,0.94)',
+    'a popover in the source is `.tui.wcol_menu_back.inner` #181818 opaque; ours floats over the ' +
+      'editor and the frames measure it as the properties back at 94%. Our own compositing, not ' +
+      "Blender's.",
+  ),
+
+  'boundary.default': rgb('tui.wcol_regular.outline'),
+  'boundary.strong': rgb('tui.wcol_regular.outline'),
+  'boundary.area': rgb('tui.editor_border'),
+  'boundary.indent': held(
+    '#656565',
+    "the Outliner's indent guides, which `outliner_draw.cc` draws as a shade of the row rather " +
+      'than from a member of its own. Measured on `outliner.png`.',
+  ),
+  'boundary.divider': held(
+    '#2e2e2e',
+    'the rule inside one region, which Blender draws as a shade of the region back rather than ' +
+      'from a member of its own. Measured on the reference frames.',
+  ),
+
+  'content.primary': rgb('tui.wcol_regular.text'),
+  'content.muted': rgb('space_outliner.text'),
+  'content.dim': held(
+    '#969696',
+    'Blender dims text by drawing the same `.text` at reduced alpha (`widget_alpha_factor`), not ' +
+      'from a second member. #969696 is `.tui.wcol_regular.text` #e6e6e6 at 0.5 over ' +
+      '`.space_properties.back` #303030.',
+  ),
+  'content.onAccent': rgb('tui.wcol_regular.text_sel'),
+  'content.menu': rgb('tui.wcol_menu_item.text'),
+  'content.status': rgb('space_statusbar.header_text'),
+  'content.placeholder': held(
+    '#5e5e5e',
+    "Blender's fields draw no placeholder text at all; this is the editor's own affordance, set " +
+      'between `.tui.wcol_text.inner` and `.text`.',
+  ),
+  'content.active': rgb('space_view3d.active'),
+  'content.selected': rgb('space_outliner.selected_object'),
+  'content.onBright.primary': held(
+    '#1d1d1d',
+    '`.tui.wcol_regular.item` #1d1d1d — the ink Blender puts ON a filled widget — read opaque.',
+  ),
+  'content.onBright.muted': held('rgba(29,29,29,0.82)', 'the same ink, our own two dim steps.'),
+  'content.onBright.dim': held('rgba(29,29,29,0.7)', 'the same ink, our own two dim steps.'),
+
+  'accent.default': rgb('tui.wcol_regular.inner_sel'),
+  'accent.muted': rgb('tui.wcol_regular.inner_sel'),
+
+  'widget.regular': rgb('tui.wcol_regular.inner'),
+  'widget.menu': rgb('tui.wcol_menu.inner'),
+  'widget.field': rgb('tui.wcol_text.inner'),
+  'widget.emboss': rgba('tui.widget_emboss'),
+
+  'viewport.background': rgb('space_view3d.back'),
+  'viewport.grid': rgb('space_view3d.grid_major'),
+  'viewport.axisX': held(
+    '#cb293f',
+    "the grid's axis line is a BLEND of `.space_view3d.grid_major` and `.tui.xaxis` #ff3352 " +
+      '(the overlay engine blends them per line; `draw/engines/overlay` is outside the sparse ' +
+      'checkout). The source value is an input to what is drawn, not what is drawn — measured.',
+  ),
+  'viewport.axisY': held(
+    '#69aa15',
+    'the same blend over `.tui.yaxis` #8bdc00 — measured, see axisX.',
+  ),
+  // There is no `viewport.axisZ`: `EditorTheme.color.viewport` declares X and
+  // Y only (`packages/editor/src/theme.ts`), because the editor's grid plane
+  // draws two axis lines. `.tui.zaxis` #2890ff is the member a third would
+  // cite when one exists — a palette key no reader reads is a name with no
+  // caller.
+  'viewport.selection': rgb('space_view3d.select'),
+  'viewport.active': rgb('space_view3d.active'),
+
+  'region.outliner': rgb('space_outliner.back'),
+  'region.properties': rgb('space_properties.back'),
+
+  // The icon groups, `interface_icons.cc:126-132`'s `DEF_ICON_<GROUP>` macros
+  // through `interface/resources.cc:1059-1078` to these members. The two new
+  // names are I2's: `scene` for the Render/Output/View Layer/Scene tabs and
+  // `collection` for the Collection tab.
+  'category.object': rgb('tui.icon_object'),
+  'category.modifier': rgb('tui.icon_modifier'),
+  'category.material': rgb('tui.icon_shading'),
+  'category.data': rgb('tui.icon_object_data'),
+  'category.scene': rgb('tui.icon_scene'),
+  'category.collection': rgb('tui.icon_collection'),
+  'category.tool': held(
+    '#cbcbcb',
+    'Blender declares no icon group for the Tool tab — `ICON_TOOL_SETTINGS` is a plain ' +
+      '`DEF_ICON`, drawn in `.text`. Measured on the reference frames, and a level below ' +
+      '`.tui.icon_scene` #cccccc, which is what it sits beside.',
+  ),
+  'category.operator': held(
+    '#95dab2',
+    "Blender's edit-mode tool column tints its creating operators green; no theme member carries " +
+      'it. Measured on `modeling-edit-none.png`.',
+  ),
+
+  // The editor's OWN vocabulary. Blender's theme has no danger/warning/success
+  // group: a Blender error is a report banner, not a themed colour, so these
+  // are ours and are stated as ours.
+  'semantic.danger': held('#e0524a', "the editor's own; Blender's theme has no error colour."),
+  'semantic.dangerMuted': held('rgba(224,82,74,0.28)', 'the same, at our own two alphas.'),
+  'semantic.dangerFaint': held('rgba(224,82,74,0.12)', 'the same, at our own two alphas.'),
+  'semantic.warning': held('#e5b83c', "the editor's own."),
+  'semantic.warningMuted': held('rgba(229,184,60,0.28)', "the editor's own."),
+  'semantic.success': held('#6fbf5f', "the editor's own."),
+  'semantic.successMuted': held('rgba(111,191,95,0.28)', "the editor's own."),
+  'semantic.dynamic': held('#e5b83c', "the editor's own."),
+  'semantic.dynamicMuted': held('rgba(229,184,60,0.18)', "the editor's own."),
+  'semantic.instance': held(
+    '#ffa028',
+    "`.space_view3d.active` #ffa028 — the editor's instance badge reuses Blender's active ink.",
+  ),
+
+  'neutralOverlay.hover': held(
+    'rgba(255,255,255,0.08)',
+    "Blender lightens a widget by SHADE (`widget_state`'s `+15` on the inner colour), not by " +
+      'an overlay; ours is an overlay because our widgets are CSS. The alpha matches that shade.',
+  ),
+  'neutralOverlay.active': held('rgba(255,255,255,0.14)', 'the same shade rule, one step up.'),
+  scrim: held('rgba(0,0,0,0.6)', 'a modal scrim is ours — Blender dims nothing behind a popup.'),
+};
+
+/** Groups the emitted document keeps verbatim: not colours. */
+const TYPOGRAPHY = {
+  sans: "'Inter', 'DejaVu Sans', system-ui, sans-serif",
+  mono: "'DejaVu Sans Mono', Menlo, monospace",
+};
+
+// ------------------------------------------------------------------- emit
+
+function set(target, path, value) {
+  const parts = path.split('.');
+  let node = target;
+  for (const part of parts.slice(0, -1)) node = node[part] ??= {};
+  node[parts.at(-1)] = value;
+}
+
+function get(source, path) {
+  return path.split('.').reduce((node, part) => node?.[part], source);
+}
+
+function cssOf(entry, withAlpha) {
+  if (!withAlpha || entry.alpha === 1) return entry.hex;
+  const [r, g, b] = [1, 3, 5].map((i) => Number.parseInt(entry.hex.slice(i, i + 2), 16));
+  return `rgba(${r},${g},${b},${Math.round(entry.alpha * 1000) / 1000})`;
+}
+
+const theme = readTheme();
+const color = {};
+const citations = {};
+for (const [key, rule] of Object.entries(MAPPING)) {
+  if (rule.member === undefined) {
+    set(color, key, rule.value);
+    citations[key] = `held — ${rule.why}`;
+    continue;
+  }
+  const entry = theme[rule.member];
+  if (entry === undefined)
+    throw new Error(
+      `${THEME} has no member \`${rule.member}\`, which \`${key}\` cites. Blender renamed or ` +
+        'removed it; re-read the theme and update the mapping rather than dropping the key.',
+    );
+  set(color, key, cssOf(entry, rule.alpha === true));
+  citations[key] = `${rule.member} (${THEME}:${entry.line})`;
+}
+
+const target = new URL('./blender.palette.json', import.meta.url);
+const before = JSON.parse(readFileSync(target, 'utf8'));
+const document = {
+  schemaVersion: 3,
+  name: 'Blender',
+  theme: { id: 'blender', color, typography: TYPOGRAPHY },
+};
+
+const changes = [];
+for (const key of Object.keys(MAPPING)) {
+  const was = get(before.theme.color, key);
+  const now = get(color, key);
+  if (was !== now)
+    changes.push(`  ${key.padEnd(28)} ${String(was)} -> ${now}   [${citations[key]}]`);
+}
+for (const line of changes) console.log(line);
+console.log(
+  `blender.palette.json — ${Object.keys(MAPPING).length} keys, ` +
+    `${Object.values(MAPPING).filter((rule) => rule.member !== undefined).length} derived from ` +
+    `${THEME}, ${changes.length} changed`,
+);
+
+if (process.argv.includes('--check')) {
+  if (changes.length > 0) process.exit(1);
+} else {
+  writeFileSync(target, `${JSON.stringify(document, null, 2)}\n`);
+}

package/contributions/blender-properties-model.ts

@@ -0,0 +1,351 @@
+/**
+ * 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 OUR SELECTION, RESOLVED BY IDENTITY. 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.
+ *
+ * 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.
+ */
+
+import type { BlenderRnaContext, BlenderRnaView } from '@volter/blender-engine/browser/rna';
+import { editorHost } from '@volter/editor-sdk/host';
+import type * as THREE from 'three';
+import {
+  blenderPresentationDocumentId,
+  blenderRna,
+  blenderRnaContext,
+  blenderRnaSet,
+  blenderSessionStarted,
+  noteBlenderRnaChanged,
+  subscribeBlenderRna,
+} from '../host/blender-runtime-host';
+import { blenderOutlinerState } from './blender-outliner-model';
+
+/** The published Model-document context, as much of it as this module reads.
+ *  Structurally typed rather than imported as the class, for the same reason
+ *  `blender-runtime-host.ts` narrows its `RuntimeView`: the document that
+ *  published it and the reader are two modules meeting over one object. */
+interface PresentedView {
+  readonly root: THREE.Object3D;
+  subscribeFrames(listener: () => void): () => void;
+  blenderObjectName(object: THREE.Object3D): string | null;
+}
+
+const isPresentedView = (value: unknown): value is PresentedView =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as PresentedView).subscribeFrames === 'function' &&
+  typeof (value as PresentedView).blenderObjectName === '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. */
+interface Object3DAuthoringLike {
+  readonly documentId: string;
+  readonly hierarchy: { object3D(id: string): THREE.Object3D | null };
+  readonly documentRootObject: THREE.Object3D | null;
+}
+
+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';
+
+function presentedView(): PresentedView | null {
+  const published = editorHost().documents.context(blenderPresentationDocumentId());
+  return isPresentedView(published) ? published : null;
+}
+
+/**
+ * WHAT THE SELECTED NODE IS, to Blender.
+ *
+ *  - `{ kind: 'object', name }` — the node is one of the engine's objects;
+ *  - `{ kind: 'collection', path }` — the node is a LAYER COLLECTION row of
+ *    the Outliner. Clicking one in Blender calls `BKE_layer_collection_activate`
+ *    (`tree_element_layer_collection_activate`, `outliner_select.cc:812-821`)
+ *    and the Collection tab then shows THAT collection; activating it here
+ *    would be a mutation the document saves, so the row's own address goes to
+ *    the door as a parameter instead (`rna_context(collection_path=…)`), the
+ *    same way the looked-at OBJECT does;
+ *  - `{ kind: 'scene' }` — the node is the Scene Collection row, which is the
+ *    whole file rather than an object in it, so only the tabs that need no
+ *    object (Render, Output, View Layer, Scene, World, Collection) stand;
+ *  - `null` — not a Blender subject at all, and no section of ours matches.
+ *
+ * Synchronous and cheap: `match()` runs on every inspector composition.
+ */
+export type BlenderSubject =
+  | { kind: 'object'; name: string }
+  | { kind: 'collection'; path: string }
+  | { kind: 'scene' };
+
+export function resolveBlenderSubject(
+  node: { readonly id: string } | null,
+  adapter: unknown,
+): BlenderSubject | null {
+  if (node === null || !isObject3DAuthoring(adapter)) return null;
+  const view = presentedView();
+  if (view === null) return null;
+  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
+  // 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);
+  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).
+  if (object === view.root) return { kind: 'scene' };
+  const name = view.blenderObjectName(object);
+  return name === null ? null : { kind: 'object', name };
+}
+
+// ---- the store ------------------------------------------------------------
+
+export interface BlenderPropertiesState {
+  /** The object the context was read around, or null for the scene subject. */
+  readonly object: string | null;
+  /** The layer collection the context was read around, when the subject is a
+   *  collection row; null otherwise. */
+  readonly collection: string | null;
+  readonly context: BlenderRnaContext | null;
+  /** Fetched datablock views, keyed by RNA path. */
+  readonly views: ReadonlyMap<string, BlenderRnaView>;
+  /** The last refusal the door answered with, verbatim. */
+  readonly error: string | null;
+  readonly loading: boolean;
+}
+
+let state: BlenderPropertiesState = {
+  object: null,
+  collection: null,
+  context: null,
+  views: new Map(),
+  error: null,
+  loading: false,
+};
+let version = 0;
+const listeners = new Set<() => void>();
+/** The frame subscription, taken once the document has published its view. */
+let frameSubscription: (() => void) | null = null;
+/** Paths a fetch is already in flight for — a render must not queue a second. */
+const inFlight = new Set<string>();
+/** The subject the last context was read for, so a re-render does not refetch. */
+let readFor: string | null = null;
+
+function publish(next: Partial<BlenderPropertiesState>, tabsMayHaveChanged = false): void {
+  state = { ...state, ...next };
+  version += 1;
+  for (const listener of [...listeners]) listener();
+  // THE TAB RAIL IS THE SECTION LIST, and section matching is the host's
+  // composition — which no store of ours can move. This is the one door that
+  // re-derives it (`@volter/editor-sdk/host`, `documents.contextChanged`).
+  if (tabsMayHaveChanged) editorHost().documents.contextChanged(blenderPresentationDocumentId());
+}
+
+export function subscribeBlenderProperties(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function blenderPropertiesVersion(): number {
+  return version;
+}
+
+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. */
+function onEngineMoved(): void {
+  const subject = readFor;
+  readFor = null;
+  publish({ views: new Map() });
+  if (subject !== null) scheduleContextRead(subject);
+}
+
+// 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.
+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;
+
+function scheduleContextRead(key: string): void {
+  if (scheduledKey === key) return;
+  scheduledKey = key;
+  setTimeout(() => {
+    if (scheduledKey !== key) return;
+    scheduledKey = null;
+    void readContext(key);
+  }, 0);
+}
+
+/** The read KEY is the subject, spelled so one string round-trips: `''` is the
+ *  scene, `collection:<address>` a layer collection, anything else an object
+ *  NAME. A collection's address is an RNA path and always contains a `.`, so
+ *  the prefix cannot collide with a datablock name. */
+function subjectKey(subject: BlenderSubject): string {
+  if (subject.kind === 'scene') return '';
+  return subject.kind === 'collection' ? `collection:${subject.path}` : subject.name;
+}
+
+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.
+  frameSubscription = view.subscribeFrames(noteBlenderRnaChanged);
+}
+
+async function readContext(key: string): Promise<void> {
+  const collection = key.startsWith('collection:') ? key.slice('collection:'.length) : null;
+  const object = collection === null && key !== '' ? key : null;
+  readFor = key;
+  publish({ loading: true, object, collection });
+  try {
+    const context = await blenderRnaContext(object ?? undefined, collection ?? undefined);
+    if (readFor !== key) 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.
+    publish({ context, loading: false, error: null }, true);
+  } catch (error) {
+    if (readFor !== key) return;
+    publish({ context: null, loading: false, error: describe(error) }, true);
+  }
+}
+
+/**
+ * WHAT THE PANEL IS LOOKING AT — called by every tab's `match()` on every
+ * composition, and by the section bodies. Idempotent: a repeat of the subject
+ * already read (or already queued) does nothing, and the read it does start
+ * runs outside the render pass (see {@link scheduleContextRead}).
+ */
+export function showBlenderSubject(subject: BlenderSubject): void {
+  if (!blenderSessionStarted()) return;
+  watchFrames();
+  const key = subjectKey(subject);
+  if (readFor === key) return;
+  scheduleContextRead(key);
+}
+
+/** The view of one datablock, fetching it on first ask. `undefined` means
+ *  "not read yet", which is what a section renders as its loading state. */
+export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
+  const held = state.views.get(path);
+  if (held !== undefined) return held;
+  if (inFlight.has(path) || !blenderSessionStarted()) return undefined;
+  inFlight.add(path);
+  void blenderRna(path)
+    .then((view) => {
+      inFlight.delete(path);
+      if (view === null) return;
+      const views = new Map(state.views);
+      views.set(path, view);
+      publish({ views, error: null });
+    })
+    .catch((error: unknown) => {
+      inFlight.delete(path);
+      publish({ error: describe(error) });
+    });
+  return undefined;
+}
+
+/**
+ * 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
+ * that comes back re-reads everything through {@link onEngineMoved}, so the field
+ * shows the value the ENGINE holds rather than the one that was typed.
+ */
+export async function writeBlenderRnaProperty(
+  path: string,
+  property: string,
+  value: unknown,
+  index?: number,
+): Promise<boolean> {
+  try {
+    await blenderRnaSet(path, property, value, index);
+    // The write presented; a re-read of this one datablock closes the loop
+    // even if the frame listener has not been taken yet.
+    const views = new Map(state.views);
+    views.delete(path);
+    publish({ views, error: null });
+    return true;
+  } catch (error) {
+    publish({ error: describe(error) });
+    return false;
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}