@volter/editor-blender 0.1.149 → 0.1.151

package/contributions/blender-gltf-export.verbs.ts

@@ -0,0 +1,312 @@
+/**
+ * RFC 0007'S EXPORTS (`blender-export-component`, `blender-export-level`, session
+ * verbs): the model on screen, written by Blender's own glTF exporter (`bpy.ops.export_scene.gltf`
+ * in this tab's Blender, `@volter/blender-engine`'s `gltf_export.py`) into the project.
+ *
+ * - A COMPONENT (`.volter/export/components/<name>.glb`): one collection named after it, every
+ *   action as a glTF animation, Y-up, the authoring collections `Notes` and `References` left out.
+ * - A LEVEL (`.volter/export/levels/<name>.glb`): the level's own objects, a placement marker in
+ *   place of every library-override placement and every instance of a linked collection
+ *   (`extras.component`, `extras.action`, `extras.tint`, `KHR_node_visibility`), and the timeline
+ *   as one scene animation plus the scene's `extras.timeline`. Its answer names the components the
+ *   markers reference (`cyclotron export level` exports or confirms each).
+ *
+ * A MANIFEST beside each file (`<name>.json`) records the `.blend`'s SHA-256, the exporter and its
+ * settings, and the file's SHA-256: the project's earlier manifest is handed to Blender, and when
+ * nothing it records has changed, nothing is exported (`current`).
+ *
+ * BOUNDED STEPS. An export of a large model holds Blender for longer than one call should last,
+ * so a call waits at most {@link STEP_MS} for it: an export still running answers
+ * `{ pending: true, token }`, and the same verb with that `token` waits again for the same export.
+ * Blender is never asked twice; the file is written once, when the export is done.
+ *
+ * `blend` names the `.blend` the caller means (project-relative); a model not yet presented is
+ * refused with "has not been presented yet", which the CLI waits on. `force` exports even when
+ * the manifest says the earlier export stands.
+ */
+import type { GltfExportAnswer, GltfExportKind, GltfExportManifest } from '@volter/blender-engine/browser/protocol';
+import { blenderModelView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import type { EditorCommandResult, VerbHandler } from '@volter/sdk/commands';
+import { editorHost } from '@volter/sdk/host';
+import { blenderEngineFile, blenderGltfExport, flushModelDocument, presentedModelBlend } from '../host/blender-runtime-host';
+
+/** The longest one call waits for an export before answering `pending` (well inside a 95 s call). */
+const STEP_MS = 60_000;
+/** How long a finished export's answer is kept for a caller that has not asked for it yet. */
+const KEEP_MS = 5 * 60_000;
+
+/** Where each kind is written in the project. */
+export const GLTF_EXPORT_DIRS: Readonly<Record<GltfExportKind, string>> = {
+  component: '.volter/export/components',
+  level: '.volter/export/levels',
+};
+/** One display LUT per project and per view settings, named by their key (`gltf_export.py`). */
+export const GLTF_DISPLAY_DIR = '.volter/export/display';
+
+/** The record of the LUTs carried in: each key and the SHA-256 its file had (read as one file: the standalone
+ *  editor's file door lists only `public/**`, so the folder is never listed). */
+const LUT_RECORD = `${GLTF_DISPLAY_DIR}/luts.json`;
+
+async function lutRecord(): Promise<Record<string, string>> {
+  try {
+    const record = JSON.parse(await editorHost().files.read(LUT_RECORD)) as unknown;
+    return record && typeof record === 'object' ? record as Record<string, string> : {};
+  } catch { return {}; }
+}
+
+/** THE DISPLAY LUTS THE PROJECT HOLDS INTACT, by key, each with its SHA-256 as recorded when it was carried
+ *  in (`luts.json` beside them). Checked on every export: a LUT whose bytes are not the ones recorded
+ *  (damaged, replaced, gone) or that has no record is left out, so Blender bakes it again when the view
+ *  settings name it. Blender bakes one only for view settings that have none. */
+async function heldLuts(): Promise<Record<string, string>> {
+  const held: Record<string, string> = {};
+  await Promise.all(Object.entries(await lutRecord()).map(async ([key, recorded]) => {
+    // (a LUT that is gone has no hash: left out)
+    if (typeof recorded === 'string' && await fileSha256(`${GLTF_DISPLAY_DIR}/${key}.cube`).catch(() => null) === recorded) held[key] = recorded;
+  }));
+  return held;
+}
+
+interface Run {
+  readonly kind: GltfExportKind;
+  readonly blend: string;
+  readonly started: number;
+  readonly done: Promise<EditorCommandResult>;
+  settled: boolean;
+  expiry?: ReturnType<typeof setTimeout>;
+}
+const runs = new Map<string, Run>();
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', bytes as BufferSource);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Cache each project file’s SHA-256 by size and modification time, persisting hashes in HASH_CACHE across reloads. A null file stat requires hashing on every read. */
+const knownHashes = new Map<string, { readonly size: number; readonly mtime: number; readonly sha256: string }>();
+const HASH_CACHE = '.volter/cache/file-hashes.json';
+let hashesRead: Promise<void> | null = null;
+let hashesDue: ReturnType<typeof setTimeout> | null = null;
+function readHashes(): Promise<void> {
+  return hashesRead ??= (async () => {
+    try {
+      const kept = JSON.parse(await editorHost().files.read(HASH_CACHE)) as Record<string, { size?: unknown; mtime?: unknown; sha256?: unknown }>;
+      for (const [path, entry] of Object.entries(kept))
+        if (typeof entry?.size === 'number' && typeof entry.mtime === 'number' && typeof entry.sha256 === 'string' && !knownHashes.has(path))
+          knownHashes.set(path, { size: entry.size, mtime: entry.mtime, sha256: entry.sha256 });
+    } catch { /* none kept yet, or unreadable: each file is hashed when asked */ }
+  })();
+}
+/** The hashes written back a second after the last new one (one write for an export's several). */
+function keepHashes(): void {
+  if (hashesDue !== null) return;
+  hashesDue = setTimeout(() => {
+    hashesDue = null;
+    void editorHost().files.write(HASH_CACHE, `${JSON.stringify(Object.fromEntries(knownHashes))}\n`).catch(() => {});
+  }, 1000);
+}
+async function fileSha256(path: string): Promise<string> {
+  const files = editorHost().files;
+  await readHashes();
+  const stat = await files.stat(path).catch(() => null);
+  const known = knownHashes.get(path);
+  if (stat && known && known.size === stat.size && known.mtime === stat.mtime) return known.sha256;
+  const hash = await sha256(await files.readBytes(path));
+  // (stat again after the read: a write landing between the two leaves no entry rather than a stale one)
+  const after = stat ? await files.stat(path).catch(() => null) : null;
+  if (stat && after && after.size === stat.size && after.mtime === stat.mtime) knownHashes.set(path, { size: stat.size, mtime: stat.mtime, sha256: hash });
+  else knownHashes.delete(path);
+  keepHashes();
+  return hash;
+}
+
+/** Cache a project manifest by its size and modification time; return undefined when absent. */
+const knownManifests = new Map<string, { readonly size: number; readonly mtime: number; readonly manifest: GltfExportManifest }>();
+async function readManifest(path: string): Promise<GltfExportManifest | undefined> {
+  const files = editorHost().files;
+  const stat = await files.stat(path).catch(() => null);
+  if (!stat) return undefined;
+  const known = knownManifests.get(path);
+  if (known && known.size === stat.size && known.mtime === stat.mtime) return known.manifest;
+  try {
+    const manifest = JSON.parse(await files.read(path)) as GltfExportManifest;
+    knownManifests.set(path, { size: stat.size, mtime: stat.mtime, manifest });
+    return manifest;
+  } catch { return undefined; }
+}
+
+/** Cache an imported export’s SHA-256 and parsed manifest while its size matches the written bytes. Re-read any differing file. */
+async function heldAsWritten(path: string, bytes: Uint8Array, manifest?: GltfExportManifest): Promise<void> {
+  const stat = await editorHost().files.stat(path).catch(() => null);
+  if (!stat || stat.size !== bytes.length) return;
+  if (manifest) {
+    if (typeof manifest.sha256 === 'string' && manifest.bytes === bytes.length) {
+      knownHashes.set(path, { size: stat.size, mtime: stat.mtime, sha256: manifest.sha256 });
+      keepHashes();
+    }
+  } else if (path.endsWith('.json')) {
+    try { knownManifests.set(path, { size: stat.size, mtime: stat.mtime, manifest: JSON.parse(new TextDecoder().decode(bytes)) as GltfExportManifest }); }
+    catch { knownManifests.delete(path); }
+  }
+}
+
+/** What Blender's currency check reads of an earlier manifest (`gltf_export.py`'s `_current` and
+ *  `_lut_missing`), so a request carries that and not the whole manifest; a current answer echoes it back. */
+function currencyOf(manifest: GltfExportManifest): GltfExportManifest {
+  const whole = manifest as unknown as Record<string, unknown>;
+  const kept: Record<string, unknown> = {};
+  for (const key of ['format', 'blendSha256', 'exporter', 'settings', 'sha256', 'display']) if (key in whole) kept[key] = whole[key];
+  return kept as unknown as GltfExportManifest;
+}
+
+/** The project's earlier export of this file, as Blender compares it: its manifest and its file's hash. */
+async function previousExport(dir: string, name: string): Promise<{ manifest: GltfExportManifest; sha256: string | null } | undefined> {
+  const files = editorHost().files;
+  // (the manifest and the file's hash at once: neither waits on the other)
+  const [manifest, sha256] = await Promise.all([readManifest(`${dir}/${name}.json`), fileSha256(`${dir}/${name}.glb`).catch(() => null)]);
+  if (!manifest) return undefined;
+  // A level's placements' own actions live beside it: one gone, the level is exported again.
+  const own = Object.values((manifest as { placementActions?: Record<string, { file?: unknown }> }).placementActions ?? {});
+  const present = await Promise.all(own.map(async (entry) =>
+    typeof entry.file !== 'string' || (await files.stat(`${dir}/${entry.file}`).catch(() => null)) !== null));
+  return present.every(Boolean) ? { manifest, sha256 } : undefined;
+}
+
+/** What a caller is told about an export: its paths and the manifest's counts, not the whole manifest. */
+function summary(blend: string, dir: string, answer: GltfExportAnswer): Record<string, unknown> {
+  const manifest = answer.manifest;
+  return {
+    kind: answer.kind,
+    blend,
+    out: `${dir}/${answer.name}.glb`,
+    manifest: `${dir}/${answer.name}.json`,
+    current: answer.current,
+    ms: answer.ms,
+    bytes: manifest.bytes,
+    sha256: manifest.sha256,
+    exporter: manifest.exporter,
+    nodes: manifest.nodes,
+    animations: manifest.animations.length,
+    hiddenNodes: manifest.hiddenNodes,
+    warnings: manifest.warnings,
+    ...(manifest.markers ? { markers: manifest.markers.length } : {}),
+    ...(manifest.components ? { components: manifest.components } : {}),
+    ...(manifest.unsupported ? { unsupported: manifest.unsupported } : {}),
+    ...(manifest.collections ? { collections: manifest.collections } : {}),
+    // (what a component of this Blender is exported with: `cyclotron export level` checks the
+    // components' manifests against it without opening them)
+    componentSettings: answer.settings.component,
+  };
+}
+
+async function runExport(kind: GltfExportKind, blend: string, force: boolean): Promise<EditorCommandResult> {
+  const dir = GLTF_EXPORT_DIRS[kind];
+  const name = (blend.split('/').pop() ?? blend).replace(/\.blend$/i, '');
+  // (where the round trip's time goes, in ms: the earlier export read and hashed, the `.blend` hashed, the LUTs
+  // checked, Blender's answer, and its files carried into the project)
+  // (the first three run at once, each timed on its own)
+  const steps: Record<string, number> = {};
+  const began = performance.now();
+  const timed = async <T>(step: string, work: Promise<T>): Promise<T> => {
+    try { return await work; } finally { steps[step] = Math.round(performance.now() - began); }
+  };
+  await flushModelDocument(blend);
+  const [previous, blendSha256, luts] = await Promise.all([
+    timed('previous', force ? Promise.resolve(undefined) : previousExport(dir, name)),
+    // The `.blend` as the project holds it: Blender streamed it in and keeps no copy to hash.
+    timed('blendHash', fileSha256(blend)),
+    // The project's LUTs that are intact, with their recorded SHA-256s (which every manifest records): a damaged one is baked again.
+    timed('luts', heldLuts()),
+  ]);
+  let at = performance.now();
+  const lap = (step: string): void => { const now = performance.now(); steps[step] = Math.round(now - at); at = now; };
+  // (Blender is sent what its currency check reads of the earlier manifest; a current answer echoes that back,
+  // and stands for the whole one held here)
+  const sent = await blenderGltfExport({ kind, blendSha256, luts, ...(force ? { force: true } : {}),
+    ...(previous ? { previous: { manifest: currencyOf(previous.manifest), sha256: previous.sha256 } } : {}) });
+  lap('blenderAnswer');
+  const answer = sent !== null && sent.current && previous ? { ...sent, manifest: previous.manifest } : sent;
+  if (answer === null) return { ok: false, error: "Blender's session is not started: open the model, then export again." };
+  if (answer.document !== blend)
+    return { ok: false, error: `Blender exported ${answer.document}, not ${blend}: the view moved to another file during the export.` };
+  // The export is in Blender's own filesystem: carry it into the project, the file before its manifest.
+  const files = editorHost().files;
+  // (the carry's time split in its reads from Blender's filesystem and its writes into the project)
+  let reads = 0, writes = 0;
+  for (const path of [...answer.files].sort((a, b) => Number(a.endsWith('.json')) - Number(b.endsWith('.json')))) {
+    const reading = performance.now();
+    const bytes = await blenderEngineFile(path);
+    reads += performance.now() - reading;
+    const writing = performance.now();
+    const name = path.split('/').pop()!;
+    if (name.endsWith('.cube')) {
+      // A LUT carried in is recorded as it arrived: the next exports check it against this.
+      await files.write(`${GLTF_DISPLAY_DIR}/${name}`, bytes);
+      const record = await lutRecord();
+      record[name.slice(0, -'.cube'.length)] = await sha256(bytes);
+      await files.write(LUT_RECORD, `${JSON.stringify(record, null, 2)}\n`);
+    } else {
+      await files.write(`${dir}/${name}`, bytes);
+      const own = name === `${answer.name}.glb`;
+      await heldAsWritten(`${dir}/${name}`, bytes, own ? answer.manifest : undefined);
+    }
+    writes += performance.now() - writing;
+  }
+  lap('carry');
+  if (answer.files.length > 0) { steps['carryRead'] = Math.round(reads); steps['carryWrite'] = Math.round(writes); }
+  return { ok: true, data: { ...summary(blend, dir, answer), steps } };
+}
+
+async function step(token: string, run: Run): Promise<EditorCommandResult> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const waiting = new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), STEP_MS); });
+  const result = await Promise.race([run.done, waiting]).finally(() => clearTimeout(timer));
+  if (result === null)
+    return { ok: true, data: { pending: true, token, kind: run.kind, blend: run.blend, elapsedMs: Math.round(performance.now() - run.started) } };
+  if (run.expiry !== undefined) clearTimeout(run.expiry);
+  runs.delete(token);
+  return result;
+}
+
+async function exportModel(kind: GltfExportKind, command: Record<string, unknown>): Promise<EditorCommandResult> {
+  const verb = `blender-export-${kind}`;
+  const token = command['token'];
+  if (token !== undefined) {
+    if (typeof token !== 'string') return { ok: false, error: `${verb}'s token is the one its pending answer gave, a string.` };
+    const run = runs.get(token);
+    if (!run || run.kind !== kind) return { ok: false, error: `${verb} has no export with token ${token}: start the export again.` };
+    return step(token, run);
+  }
+  const wanted = command['blend'];
+  if (wanted !== undefined && (typeof wanted !== 'string' || !/\.blend$/i.test(wanted)))
+    return { ok: false, error: `${verb}'s blend is a project-relative .blend path; it was given ${JSON.stringify(wanted)}.` };
+  const force = command['force'];
+  if (force !== undefined && typeof force !== 'boolean') return { ok: false, error: `${verb}'s force is true or false.` };
+  // WHAT THE VIEW SHOWS NOW, not what was asked to open: just after a switch the view still holds the last file.
+  const blend = presentedModelBlend(blenderModelView);
+  if (blend === null || (wanted !== undefined && blend !== wanted))
+    return { ok: false, error: `${wanted ?? 'The model'} has not been presented yet${blend ? ` (the view still shows ${blend})` : ''}: wait for it to show, then export it.` };
+  // A caller that lost its token (it was stopped while it waited) joins the export it started.
+  const running = [...runs.entries()].find(([, one]) => !one.settled);
+  if (running && running[1].kind === kind && running[1].blend === blend && force !== true) return step(running[0], running[1]);
+  if (running) return { ok: false, error: `An export of ${running[1].blend} is still running; ask ${`blender-export-${running[1].kind}`} with its token, then export again.` };
+  const id = crypto.randomUUID();
+  const run: Run = {
+    kind, blend, started: performance.now(), settled: false,
+    done: runExport(kind, blend, force === true).catch((error: unknown) => ({ ok: false, error: `${verb} ${blend}: ${message(error)}` })),
+  };
+  void run.done.then(() => {
+    run.settled = true;
+    run.expiry = setTimeout(() => { if (runs.get(id) === run) runs.delete(id); }, KEEP_MS);
+  });
+  runs.set(id, run);
+  return step(id, run);
+}
+
+export const gltfExportVerbs: Readonly<Record<string, VerbHandler>> = {
+  // Each call waits at most STEP_MS for its export, then answers pending with a token.
+  'blender-export-component': (command) => exportModel('component', command as Record<string, unknown>),
+  'blender-export-level': (command) => exportModel('level', command as Record<string, unknown>),
+};

package/contributions/blender-header-menus.tsx

@@ -1,50 +1,4 @@
-/**
- * THE MODEL DOCUMENT'S HEADER IS BLENDER'S 3D VIEWPORT HEADER, in Object Mode
- * (WORK.md §THE BLENDER RELEASE, B6; ARCHITECTURE-CORE §Blender north star
- * goal 3 as amended — the person "can make MACRO adjustments at the screen …
- * each a bpy call through the doors that exist").
- *
- * `VIEW3D_MT_editor_menus` (`scripts/startup/bl_ui/space_view3d.py:1143-1210`)
- * draws four menu words in Object Mode, in this order: **View**
- * (`:1153`), **Select** (`:1166`, `VIEW3D_MT_select_object`), **Add**
- * (`:1169`, `VIEW3D_MT_add`) and **Object** (`:1210`, `VIEW3D_MT_object`).
- * All four are here.
- *
- * VIEW CARRIES ITS AREA ROWS AND NOTHING ELSE. Its camera-view rows — Front / Right / Top /
- * Perspective 3/4, and the Perspective–Orthographic pair — are already a menu in THIS SAME HEADER
- * STRIP: the host draws `Object3DDocumentToolbar` at the strip's trailing edge for every document
- * with a 3D session, which is exactly where Blender's viewport header carries them too
- * (`DocumentHeaderStrip`'s own note), so repeating them here would be the same control twice in
- * one row. What View owns that no other control does is **Area** (`VIEW3D_MT_view`'s
- * `layout.menu("INFO_MT_area")`, `space_view3d.py:1520`; `space_info.py`'s `INFO_MT_area`): the
- * split that puts a second area beside this one. Blender's standard way to watch the render while
- * modeling is exactly that — split the viewport and set the new area to Rendered shading through
- * the camera — so Vertical Split opens a second 3D viewport beside the model, set up that way
- * (`blender-runtime.document.tsx`), and Close Area closes it. The other rows of `INFO_MT_area` (Horizontal Split, the new-window, maximize and fullscreen toggles) and
- * the rest of View — the sidebar and tool-shelf toggles, local view, the view-point and view-axis
- * submenus, Frame Selected, Viewport Render — are not drawn.
- *
- * WHAT IS DRAWN IS WHAT ACTS. A row Blender draws that this unit does not act
- * on is simply not here — never a row that opens a dialog we do not have, and
- * never one that no-ops. Where a row exists in Blender and is REFUSED here it
- * is drawn disabled with the refusal as its reason: the four Add rows that want a FILE
- * (Image ▸ Reference…/Background…/Mesh Plane…, Volume ▸ Import OpenVDB… —
- * `BlenderCreatableKind.refusal` carries each sentence). Add is the whole of
- * `VIEW3D_MT_add` now, so "not here" means Blender's menu-search row and
- * nothing else.
- *
- * EVERY ROW IS BLENDER RUNNING ITS OWN OPERATOR, through the doors B6 built:
- * `StructureProvider` for Add / Duplicate / Delete, and
- * `runBlenderObjectOperator` for Apply / Clear / Set Origin. Nothing here
- * reimplements a transform apply or an origin move.
- *
- * NO GAME CONTROLS (owner, 2026-10-06: "it's very confusing that the timeline at the bottom has
- * a play button AND there's a play button at the top"). The header carries no Play of its own,
- * nor View's Play row: in Game mode the one Play is the Game panel's (`blender-game-panel.tsx`),
- * in Movie mode the one transport is the Timeline's. The Game / Movie switch that chooses
- * between them is the bottom area's, at the leading edge of its header row (`PlayModeSwitch`),
- * because switching modes swaps that area and nothing here.
- */
+
 
 import type { ToolNotice } from '@volter/sdk/contributions';
 import {
@@ -70,14 +24,7 @@ import { areaSplit, setAreaSplit, subscribeAreaSplit } from '../src/area-split';
 
 type MenuId = 'view' | 'select' | 'add' | 'object';
 
-/**
- * BLENDER'S OWN ROWS for the three transform submenus of `VIEW3D_MT_object`,
- * each citing the line it is transcribed from. The rows Blender draws in those
- * submenus that this unit does not act on — Apply's five delta rows, its
- * Visual Transform / Visual Geometry to Mesh / Parent Inverse block, Clear's
- * Origin row, Set Origin's two centre-of-mass rows — are not here, for the
- * reason the header's own note gives.
- */
+/** Supported transform rows from Blender's VIEW3D_MT_object submenus. */
 const APPLY_ROWS: readonly { readonly label: string; readonly call: string }[] = [
   // `VIEW3D_MT_object_apply`, `space_view3d.py:3206-3219`: one
   // `object.transform_apply` per row with the three booleans set.
@@ -98,7 +45,6 @@ const CLEAR_ROWS: readonly { readonly label: string; readonly call: string }[] =
 const ORIGIN_ROWS: readonly {
   readonly label: string;
   readonly type: string;
-  readonly refusal?: string;
 }[] = [
   // `VIEW3D_MT_object`, `space_view3d.py:2817` — one
   // `operator_menu_enum("object.origin_set", "type")`, so the labels are the
@@ -110,67 +56,47 @@ const ORIGIN_ROWS: readonly {
   { label: 'Origin to 3D Cursor', type: 'ORIGIN_CURSOR' },
 ];
 
-/**
- * `VIEW3D_MT_add`'S OWN ROWS, in its own order, with its own separators
- * (`space_view3d.py:2699-2764`, read at the engine's pin) — EIGHTEEN
- * top-level rows, each carrying the line it is transcribed from.
- *
- * Eighteen and not seventeen: `:2707` is Point Cloud
- * (`object.pointcloud_random_add`), a flat row between Text and Volume that a
- * count taken from Blender's manual misses. The pinned source is the
- * reference, so it is drawn.
- *
- * A SUBMENU NAMES A GROUP OF {@link CREATABLE_KINDS}, which is where each
- * row's label, call and refusal live; a flat row names one kind. The one
- * dynamic submenu is Collection Instance, whose rows are the file's own
- * collections (`liveCollectionKinds`).
- *
- * WHAT BLENDER DRAWS THAT IS NOT HERE, and why — the same rule the header's
- * note states: `Search…` (`:2689`) draws only under `EXEC_REGION_WIN` and
- * opens the menu-search dialog this editor has no door for. Everything else
- * `VIEW3D_MT_add` draws is here, including the rows that refuse (they are
- * drawn disabled with the engine's own reason rather than omitted, because a
- * person looking for Reference… should find it and be told why it cannot run).
- */
+/** Blender's VIEW3D_MT_add row order. Groups resolve current blenderCreatableKinds;
+ * Collection Instance resolves the file's live collections. Unsupported operations expose their refusal. */
 type AddRow =
   /** `layout.separator()`, at this line — which is also the row's key. */
   | { readonly separatorAt: string }
   /** A row `VIEW3D_MT_add` draws directly, by its kind id. */
-  | { readonly kind: string; readonly at: string }
-  /** A submenu: the label Blender gives it, and the `CREATABLE_KINDS` group
+  | { readonly kind: string }
+  /** A submenu: the label Blender gives it, and the creatable-kind group
    *  whose rows fill it (the same string). */
-  | { readonly submenu: string; readonly at: string };
+  | { readonly submenu: string };
 
 const ADD_MENU: readonly AddRow[] = [
-  { submenu: 'Mesh', at: '2699' },
-  { submenu: 'Curve', at: '2702' },
-  { submenu: 'Surface', at: '2704' },
-  { submenu: 'Metaball', at: '2705' },
-  { kind: 'text', at: '2706' },
-  { kind: 'point-cloud', at: '2707' },
-  { submenu: 'Volume', at: '2708' },
-  { submenu: 'Grease Pencil', at: '2709' },
+  { submenu: 'Mesh' },
+  { submenu: 'Curve' },
+  { submenu: 'Surface' },
+  { submenu: 'Metaball' },
+  { kind: 'text' },
+  { kind: 'point-cloud' },
+  { submenu: 'Volume' },
+  { submenu: 'Grease Pencil' },
   { separatorAt: '2711' },
   // `:2713` asks `VIEW3D_MT_armature_add.is_extended()`; no add-on extends it
   // in this engine, so Blender's own `else` branch — the flat row — is drawn.
-  { kind: 'armature', at: '2716' },
-  { submenu: 'Lattice', at: '2718' },
+  { kind: 'armature' },
+  { submenu: 'Lattice' },
   { separatorAt: '2720' },
-  { submenu: 'Empty', at: '2722' },
-  { submenu: 'Image', at: '2723' },
+  { submenu: 'Empty' },
+  { submenu: 'Image' },
   { separatorAt: '2725' },
-  { submenu: 'Light', at: '2727' },
-  { submenu: 'Light Probe', at: '2728' },
+  { submenu: 'Light' },
+  { submenu: 'Light Probe' },
   { separatorAt: '2730' },
   // `:2732`'s `is_extended()` is false the same way, so `VIEW3D_MT_camera_add`
   // draws its single row INTO this menu (`:2735`).
-  { kind: 'camera', at: '2735' },
+  { kind: 'camera' },
   { separatorAt: '2737' },
-  { kind: 'speaker', at: '2739' },
+  { kind: 'speaker' },
   { separatorAt: '2741' },
-  { submenu: 'Force Field', at: '2743' },
+  { submenu: 'Force Field' },
   { separatorAt: '2745' },
-  { submenu: 'Collection Instance', at: '2759' },
+  { submenu: 'Collection Instance' },
 ];
 
 /** BLENDER'S OWN TEXT for a Collection Instance row with no collection to
@@ -199,7 +125,7 @@ function MenuWord({
         aria-expanded={open === id}
         onClick={() => setOpen(open === id ? null : id)}
         // BLENDER'S OWN BAR BEHAVIOUR: with one menu open, moving across the
-        // bar opens the next. The same rule `ApplicationMenus` transcribes for
+        // bar opens the next. The same rule the native menu follows for
         // the title bar's words.
         onPointerEnter={() => {
           if (open) setOpen(id);
@@ -210,7 +136,7 @@ function MenuWord({
       </MenuTrigger>
       {open === id && (
         // PORTALED, not `position: absolute` — the document header strip is
-        // 26 px tall and clips, the same fact `ApplicationMenus` records about
+        // 26 px tall and clips, the same fact the menu documents about
         // the workbench's own title bar.
         <AnchoredMenu
           anchorRef={anchorRef}
@@ -228,20 +154,7 @@ function MenuWord({
   );
 }
 
-/**
- * WHAT A ROW DID, SAID OUT LOUD. Every row here is a bpy call whose success and
- * whose REFUSAL are both invisible on screen — an added object appears, but a
- * refused `transform_apply` on a linked mesh, a Blender traceback, or an
- * operator the headless build has no context for all look exactly like a menu
- * that closed. So each row's `WriteAck` is read and reported through the host's
- * own notice door (`ToolContributionProps.notify`).
- *
- * MEASURED 2026-09-21, which is why this exists rather than being tidy: Add ▸
- * Mesh ▸ UV Sphere created the sphere and never selected it, and the ONLY
- * evidence was `bpy.data.objects` read from a second door — the menu itself
- * reported nothing either way. An ack that says `persisted: false` now carries
- * Blender's own sentence to the screen.
- */
+/** Report each menu row’s WriteAck through the host notice door. A refused Blender operator or unpersisted write must remain visible after the menu closes. */
 function reportAck(
   notify: ((notice: ToolNotice) => () => void) | undefined,
   label: string,
@@ -270,7 +183,6 @@ export function BlenderObjectModeHeader({
   // And on the set of live Outliners: the handle this bar acts through may arrive after its first render.
   useSyncExternalStore(subscribeBlenderOutlinerHandles, blenderOutlinerHandlesVersion, blenderOutlinerHandlesVersion);
   const [open, setOpen] = useState<MenuId | null>(null);
-  const rootRef = useRef<HTMLDivElement>(null);
   const viewRef = useRef<HTMLDivElement>(null);
   const selectRef = useRef<HTMLDivElement>(null);
   const addRef = useRef<HTMLDivElement>(null);
@@ -281,9 +193,7 @@ export function BlenderObjectModeHeader({
     () => false,
   );
   const handle = blenderOutlinerHandle(documentId);
-  // NOTHING RATHER THAN A DEAD BAR: with no Outliner published for this
-  // document there is no subject for any of these rows, and a menu of rows
-  // that cannot act is the inert control this file's header rules out.
+  // Without a published Outliner this document offers no menu subject.
   if (handle === null) return null;
 
   const run = (
@@ -299,14 +209,9 @@ export function BlenderObjectModeHeader({
   const all = handle.allObjectNames();
   const nothingSelected = selected.length === 0 ? 'Nothing is selected.' : undefined;
 
-  // THE ADD MENU'S ROWS. The kinds are read fresh on every render because one
-  // submenu's rows are the file's own collections, which change as the person
-  // works (`liveCollectionKinds`) — and this bar already re-renders on the
-  // Outliner's version, which is where that tree comes from.
+  // Resolve current creatable kinds, including the file's live collections, on each Outliner render.
   const kinds = blenderCreatableKinds();
-  /** One row: Blender's label, its kind's call, and — where the kind refuses —
-   *  drawn DISABLED with that sentence as its reason, the shape Set Origin ▸
-   *  Origin to 3D Cursor set. */
+  /** Draw each kind's refusal as a disabled row with its reason. */
   const addItem = (kind: BlenderCreatableKind): ReactNode => (
     <MenuItem
       key={kind.kind}
@@ -358,10 +263,9 @@ export function BlenderObjectModeHeader({
       compact
       label="Blender Object Mode menus"
       data-testid="blender-object-mode-menus"
-      ref={rootRef}
     >
       {/* VIEW ▸ AREA — `INFO_MT_area`'s split and close, for the second 3D viewport beside the
-          model (this file's header). */}
+          model. */}
       <MenuWord id="view" open={open} setOpen={setOpen} anchorRef={viewRef}>
         <MenuSubmenu label="Area" data-testid="blender-view-area">
           <MenuItem
@@ -423,7 +327,7 @@ export function BlenderObjectModeHeader({
 
       {/* ADD — `VIEW3D_MT_add`, `space_view3d.py:2679-2764`, EVERY ROW IT
           DRAWS, in its order, with its separators and its submenus. The shape
-          is `ADD_MENU` above; what each row DOES is `CREATABLE_KINDS`. */}
+          is ADD_MENU; blenderCreatableKinds supplies each operation. */}
       <MenuWord id="add" open={open} setOpen={setOpen} anchorRef={addRef}>
         {ADD_MENU.map((row) => addRowNode(row))}
       </MenuWord>
@@ -443,8 +347,8 @@ export function BlenderObjectModeHeader({
             <MenuItem
               key={row.type}
               data-testid={`blender-origin-${row.type}`}
-              disabled={row.refusal !== undefined || selected.length === 0}
-              title={row.refusal ?? nothingSelected}
+              disabled={selected.length === 0}
+              title={nothingSelected}
               onSelect={run(`Set Origin ▸ ${row.label}`, (outliner) =>
                 runBlenderObjectOperator(
                   outliner.selectedObjectNames(),
@@ -498,7 +402,7 @@ export function BlenderObjectModeHeader({
             const ids = outliner.selectedObjectNames()
               .map(name => outliner.rowIdForObject(name))
               .filter((id): id is string => id !== null);
-            return outliner.structure.duplicateMany?.(ids);
+            return outliner.structure.duplicateMany(ids);
           })}
         >
           Duplicate Objects
@@ -512,7 +416,7 @@ export function BlenderObjectModeHeader({
               .selectedObjectNames()
               .map((name) => outliner.rowIdForObject(name))
               .filter((id): id is string => id !== null);
-            return outliner.structure.removeMany?.(ids);
+            return outliner.structure.removeMany(ids);
           })}
         >
           Delete