@volter/editor-blender 0.1.149 → 0.1.151

package/contributions/blender-outliner-authoring.ts

@@ -1,60 +1,4 @@
-/**
- * THE OUTLINER IS BLENDER'S DATABLOCK TREE, DRAWN BY OUR HIERARCHY PANEL
- * (ARCHITECTURE-CORE §Blender north star, "Inspection parity, not editing
- * parity"; WORK.md §Blender in the tab is Blender, "Inspection parity", I3).
- *
- * The Model document's rows used to be the PRESENTER's three.js graph — "Model
- * › ModelLighting, Cube, Probe", a reading of Blender's data by the thing that
- * draws the photograph. What Blender's own Outliner shows is the VIEW LAYER:
- * Scene Collection, its collections, their objects, and under each object the
- * datablocks it carries. That tree is the engine's, `rna_outliner` answers it,
- * and this is the `HierarchyProvider` that hands it to `GameHierarchy`.
- *
- * IT REPLACES NOTHING ELSE. `ToolObject3DAuthoringProps.authoring` hands the
- * document the host's DEFAULT adapter for delegation, and everything that is
- * genuinely about the three.js presentation still goes to it: the transform
- * the gizmo reads, the object a raycast hit, the selection the viewport
- * outlines. What this overrides is the TREE and what a row means — because
- * only the engine knows there is a Subdivision modifier on that cube.
- *
- * THE TWO ID SPACES, and the one place they meet. A row's id is Blender's own
- * address (`bpy.data.objects["Cube"].modifiers["Subdivision"]`); the default
- * adapter's ids are the presenter's three ids. They meet at `object3D`: a row
- * that names an OBJECT resolves through the presented frame's own table
- * (`BlenderRuntimeView.objectForBlenderName`, a lookup by the frame's id and
- * never by `object.name`), and every delegation below goes through that one
- * function. A row with no object — a collection, a vertex group, a bone —
- * simply has none, which is the honest answer and the one the shell already
- * treats as "no object here".
- *
- * AND THE SPACES MEET BOTH WAYS, which is the half that was missing.
- * `selection.set` PUBLISHES the presentation's ids into the shell store (so
- * the viewport's own selection machinery keeps working), and the viewport
- * then asks THIS adapter about those ids: `editor-viewport.ts` computes its
- * gizmo subject from `store.selectedEntityId` and runs it through
- * `hierarchy.node` / `transforms.editability` / `_objectForAuthoringId`. So
- * every id arriving from outside is normalized by {@link rowIdFor} — a row id
- * passes through, a presentation id is resolved to its object and mapped back
- * to the row that names it.
- *
- * SELECTING A DATABLOCK SELECTS ITS OBJECT, which is Blender's own behaviour
- * rather than a convenience: `outliner_select.cc`'s activation walks back to
- * the owning object (`outliner_search_back_te(te, ID_OB)`, `:863`) and sets
- * the index on IT, which is why clicking a shape key in Blender moves the
- * Properties editor to that object. The door carries the owning object per row
- * (`BlenderOutlinerRow.object`) and that is what this selects.
- *
- * AND IT WRITES NOW — the "inspection parity, not editing parity" the first
- * line cites is the order the UI was BUILT in, and the editing half of it is
- * on the release's critical path as of the owner's 2026-09-21 amendment to
- * ARCHITECTURE-CORE §Blender north star goal 3 ("the key to the edit is just
- * macro adjustments"). Three providers here write, each one bpy call through a
- * door that already existed: {@link transforms} (`rna-set` of `matrix_world`,
- * B5), the `name` half of {@link inspector} (`rna-set` of `Object.name`), and
- * {@link structure} (`bpy.ops.*` through the script door — add, delete,
- * duplicate). Every one of them is Blender running its own code; none of them
- * reimplements an operator.
- */
+
 
 import type { BlenderOutlinerRow } from '@volter/blender-engine/browser/rna';
 import type { ToolObject3DDocumentAuthoringFactory } from '@volter/editor-threejs/object3d-contributions';
@@ -119,30 +63,19 @@ function isObjectRow(row: BlenderOutlinerRow | undefined): row is BlenderOutline
   return row?.type === 'TSE_SOME_ID' && row.struct === 'Object' && row.object !== undefined;
 }
 
-/** What the shell calls this row's TYPE on the inspector's identity row.
- *  Blender's Outliner prints no type text at all (`blender.style.ts`'s
- *  `hierarchyTypeSuffix: 'hidden'` measured that on `outliner.png`), so this
- *  is only ever read where a type is genuinely asked for. */
-function typeLabel(row: BlenderOutlinerRow): string | undefined {
-  if (row.struct) return row.struct;
-  // A base row is a LABEL in Blender ("Modifiers", "Vertex Groups", "Pose"),
-  // and `TSE_MODIFIER_BASE` is not a noun a person says. Nothing here.
-  return undefined;
-}
-
 function nodeFor(row: BlenderOutlinerRow, parentId: string | null): EditorNode {
   return {
     id: row.id,
     label: row.name,
     // EVERY BLENDER ROW IS `entity`, INCLUDING THE COLLECTIONS. `folder` reads
-    // as structural to the shell (`GameHierarchy.tsx`'s `STRUCTURAL_ROLES`),
+    // as structural to the shell (`Hierarchy.tsx`'s `STRUCTURAL_ROLES`),
     // and a structural row is drawn NO restriction columns — while Blender
     // draws a collection the same eye and camera it draws an object
     // (`outliner_draw.cc:1620-1700`). The role is what the shell branches on;
     // the KIND is what says what this is.
     role: 'entity',
     kind: blenderOutlinerKind(row.icon),
-    ...(typeLabel(row) ? { typeLabel: typeLabel(row) as string } : {}),
+    ...(row.struct ? { typeLabel: row.struct } : {}),
     parentId,
     childIds: row.children.map((child) => child.id),
     // BLENDER'S OWN DEFAULT OPEN STATE, not the shell's shape heuristic: a
@@ -169,13 +102,13 @@ const CAPABILITIES: AuthoringCapabilities = {
  * `documentId` and `documentRootObject` are not on `AuthoringAdapter` — which
  * is exactly why `blender-properties-model.ts`'s `isObject3DAuthoring` checks
  * for them structurally — so they have to be declared somewhere for this
- * literal to typecheck. Here, once, rather than at each getter: the literal
- * used to carry a conditional spread, and a spread is what was silently
- * suppressing TypeScript's excess-property check on them.
+ * literal to typecheck. Here, once, rather than at each getter: a conditional
+ * spread in the literal would silently suppress TypeScript's excess-property
+ * check on them.
  */
 interface BlenderOutlinerAdapter extends AuthoringAdapter {
-  readonly documentId: string | undefined;
-  readonly documentRootObject: THREE.Object3D | null | undefined;
+  readonly documentId: string;
+  readonly documentRootObject: THREE.Object3D | null;
 }
 
 /**
@@ -190,7 +123,7 @@ interface BlenderOutlinerAdapter extends AuthoringAdapter {
  * provider's.
  */
 export interface BlenderOutlinerHandle {
-  readonly documentId: string | undefined;
+  readonly documentId: string;
   /** The Blender object NAMES the panel's selection covers — the header's
    *  subject for every Object-menu row, and for Select ▸ Invert. */
   selectedObjectNames(): readonly string[];
@@ -206,27 +139,17 @@ export interface BlenderOutlinerHandle {
    *  `_rna_address`' own identifier escaping and `_outliner_unique`'s
    *  disambiguating suffix, neither of which a caller can reconstruct. */
   rowIdForObject(name: string): string | null;
-  readonly structure: StructureProvider;
-  subscribe(listener: () => void): () => void;
+  readonly structure: StructureProvider & Required<Pick<StructureProvider, 'duplicateMany' | 'removeMany'>>;
 }
 
 /**
  * THE LIVE OUTLINERS, by the document each is the Outliner of.
  *
- * A Set rather than a Map because the adapter's `documentId` is a GETTER off
- * the default adapter (see {@link BlenderOutlinerAdapter}) and is not
- * necessarily resolved when the factory runs, so there is no key to register
- * under at that moment.
+ * Each stage retains its own handle, including stages showing the same document.
  */
 const liveOutliners = new Set<BlenderOutlinerHandle>();
 
-/**
- * A HANDLE ARRIVING IS NEWS. A header drawn before its document's stage made an Outliner has no
- * subject and draws nothing; the tree's own version does not move when a handle registers, so
- * without this it stayed empty until the next edit (measured: a cold load showed no View, Select,
- * Add or Object until a script changed the tree). Notified on the next turn, never inside the
- * render that made the handle.
- */
+/** Publish handle registration on the next turn so headers waiting for an Outliner subject update outside the render pass. */
 let liveOutlinersVersion = 0;
 const liveOutlinerListeners = new Set<() => void>();
 function liveOutlinersChanged(): void {
@@ -271,41 +194,7 @@ const NO_TRANSFORM = (): Transform => ({
   scale: [1, 1, 1],
 });
 
-/**
- * A presented object's pose, back in BLENDER's space and in the shape the RNA
- * door's WRITE half takes.
- *
- * The presented root carries the signed axis permutation P that takes
- * Blender's Z-up into three's Y-up — written as an exact matrix in
- * `blender-runtime-view.ts`'s constructor precisely so it inverts exactly —
- * and every presented object hangs under it. So `P⁻¹ · object.matrixWorld` is
- * the matrix Blender calls `matrix_world`. The root's own WORLD matrix is what
- * is inverted, not the literal, so any transform the stage puts above it is
- * divided out too.
- *
- * THE TWO HALVES OF `matrix_world` USE OPPOSITE ORDERS, and that is measured
- * rather than reasoned (2026-09-21, live, through `blender-rna-set` on the
- * default cube):
- *
- *   sent `[[1,0,0,0.5],[0,1,0,0],[0,0,1,0],[0,0,0,1]]` → `location` stayed
- *     `[0,0,0]` and the next depsgraph evaluation put `matrix_world` back to
- *     identity — Blender read the translation as the projective row, found
- *     none to decompose, and recomputed the matrix from loc/rot/scale;
- *   sent `[[1,0,0,0],[0,1,0,0],[0,0,1,0],[0.5,0,0,1]]` → `location` reads
- *     `[0.5,0,0]` and `matrix_world` reads back `[1,0,0,0.5, …]`.
- *
- * So the WRITE goes into Blender's C `float[4][4]` in C order — entry `i` is
- * the i-th COLUMN of the `mathutils.Matrix` a Python read returns — while the
- * READ (`session.py`'s `_rna_value`, and the frame's
- * `[[float(v) for v in row] for row in obj.matrix_world]`) is that Matrix's
- * ROWS. The frame's reader is right to be row-major
- * (`blender-runtime-view.ts` feeds it to `Matrix4.set`, which is row-major);
- * this writer is its transpose.
- *
- * Which makes the code the simplest form of all: `THREE.Matrix4.elements` is
- * ALREADY column-major, so the four groups of four are the four entries
- * Blender wants, in order.
- */
+/** Convert a presented world matrix back through the document root’s inverse, removing Blender-to-stage axes and any stage transform. The RNA write consumes columns while the read returns rows; Matrix4.elements already holds the required column-major order. */
 function blenderWorldMatrixRows(object: THREE.Object3D, root: THREE.Object3D): number[][] {
   // The ancestors too: a presented object owns its matrix
   // (`matrixAutoUpdate = false`), so nothing recomposes it for us.
@@ -319,44 +208,7 @@ function blenderWorldMatrixRows(object: THREE.Object3D, root: THREE.Object3D): n
   ];
 }
 
-/**
- * BLENDER'S ADD MENU, AS KINDS — every row `VIEW3D_MT_add` draws in Object
- * Mode, each with Blender's OWN label and the `bpy.ops` call its row runs
- * (`scripts/startup/bl_ui/space_view3d.py` at the engine's pin, cited per
- * row). The menu's SHAPE — Blender's order, its separators and which rows are
- * submenus — is `blender-header-menus.tsx`'s `ADD_MENU`, which names these
- * kinds; this table is what each one DOES.
- *
- * EVERY ONE IS BLENDER RUNNING ITS OWN OPERATOR. There is no second
- * implementation of a primitive's defaults, its vertex count or its shading
- * here; the kind names the operator and the engine does the rest.
- *
- * A NEW OBJECT LANDS AT THE 3D CURSOR, as in Blender: no row states a
- * `location`, and an unset one is `scene->cursor.location`
- * (`editors/object/object_add.cc`, `location_from_view`). The cursor is drawn
- * and placed on the Model document (`blender-runtime-cursor.ts`).
- *
- * A ROW THAT NEEDS A FILE IS DRAWN DISABLED WITH THE REASON, never as a
- * gesture that cannot complete (the shape B6 set for Set Origin ▸ Origin to 3D
- * Cursor). Blender's Image ▸ Reference/Background/Mesh Plane and Volume ▸
- * Import OpenVDB open a FILE BROWSER; this editor has no door to open one
- * through — `EditorHost.files` (`@volter/sdk/host`) reads and writes
- * project-relative paths and has no "pick a file" member at all — so those
- * rows carry {@link BlenderCreatableKind.refusal} instead. Measured at the
- * engine on 2026-09-21: `object.empty_image_add` answers "poll() failed,
- * context is incorrect / Please select at least one image", and
- * `image.import_as_mesh_planes` and `object.volume_import` both return
- * `CANCELLED` having created nothing — so the alternative was a row that
- * looked like it worked.
- *
- * Blender's OWN conditional rows are read as conditions, not copied: `Search…`
- * (`:2689`) draws only under `EXEC_REGION_WIN` and opens a menu-search dialog
- * this editor does not have; Armature and Camera draw as SUBMENUS only when an
- * add-on has extended them (`is_extended()`, `:2713`/`:2732`) and this engine
- * loads none, so both are the flat row Blender falls through to; Curve's
- * `Random` row (`:2471`) stands on `preferences.experimental.use_new_curves_tools`
- * and this build reports `bpy.app.build_options.experimental_features` False.
- */
+/** The Add table maps Blender’s Object Mode menu kinds to bpy operators. Blender supplies defaults and active-collection placement at the 3D cursor. File-browser operators carry a named refusal because this host has no file-picker door. Read Blender’s conditional rows against the engine’s available add-ons and experimental features. */
 export interface BlenderCreatableKind {
   /** The `kind` string the shell round-trips into {@link StructureProvider.create}. */
   readonly kind: string;
@@ -594,13 +446,7 @@ export const CREATABLE_KINDS: readonly BlenderCreatableKind[] = [
   // `VIEW3D_MT_add`, `space_view3d.py:2716` — the flat row Blender falls
   // through to when no add-on has extended `VIEW3D_MT_armature_add`.
   { kind: 'armature', label: 'Armature', group: null, call: 'object.armature_add' },
-  // `VIEW3D_MT_lattice_add`, `space_view3d.py:2656-2657`. The first row is the
-  // GENERIC add operator with a type, not a `lattice_add` of its own. Its kind
-  // is `lattice.lattice` and not `lattice` because the header stamps a row's
-  // test id from its kind and a submenu's from its group label — measured
-  // 2026-09-21: a bare `lattice` made `blender-add-lattice` name BOTH the
-  // submenu trigger and the row inside it, and the row's own click re-opened
-  // the submenu and added nothing.
+  // VIEW3D_MT_lattice_add uses the generic add operator. lattice.lattice gives the row a distinct test id from its lattice submenu.
   {
     kind: 'lattice.lattice',
     label: 'Lattice',
@@ -849,10 +695,7 @@ function addCall(kind: BlenderCreatableKind): string {
   return `bpy.ops.${call}(${args.join(', ')})`;
 }
 
-/** A Python string literal for one Blender name. JSON's own escaping is a
- *  subset of Python's for every character a datablock name can hold, which is
- *  why the transform writer above addresses `bpy.data.objects[…]` the same
- *  way. */
+/** Encode a Blender datablock name as a Python string literal. */
 function py(name: string): string {
   return JSON.stringify(name);
 }
@@ -861,11 +704,10 @@ function py(name: string): string {
  * THE STEP'S LABEL IS THE OPERATOR'S OWN NAME, the one Blender's Edit menu shows: Add › Cone is
  * "Undo Add Cone", not "Undo Blender Python". Blender's names do not follow the menu rows (a Point
  * light is "Add Light"), so they are Blender's, read from this build with
- * `bpy.ops.<id>.get_rna_type().name` (`ot->name`) for every operator these menus run and every
- * `object.*_add`. An id not here keeps the script door's label.
+ * `bpy.ops.<id>.get_rna_type().name` (`ot->name`) for the operators these menus run.
+ * An id not here keeps the script door's label.
  *
- * A TABLE, NOT A QUESTION PER CLICK: asking Blender before every operator cost a round trip each
- * time for a name that never changes within a build.
+ * Cache these build-stable operator names instead of querying Blender on each click.
  */
 const OPERATOR_NAMES: Readonly<Record<string, string>> = {
   'curve.primitive_bezier_circle_add': "Add B\u00e9zier Circle",
@@ -873,7 +715,6 @@ const OPERATOR_NAMES: Readonly<Record<string, string>> = {
   'curve.primitive_nurbs_circle_add': "Add Nurbs Circle",
   'curve.primitive_nurbs_curve_add': "Add Nurbs Curve",
   'curve.primitive_nurbs_path_add': "Add Path",
-  'image.import_as_mesh_planes': "Import Images as Planes",
   'mesh.primitive_circle_add': "Add Circle",
   'mesh.primitive_cone_add': "Add Cone",
   'mesh.primitive_cube_add': "Add Cube",
@@ -886,41 +727,25 @@ const OPERATOR_NAMES: Readonly<Record<string, string>> = {
   'mesh.primitive_uv_sphere_add': "Add UV Sphere",
   'object.armature_add': "Add Armature",
   'object.camera_add': "Add Camera",
-  'object.collection_add': "Add to Collection",
   'object.collection_instance_add': "Add Collection Instance",
-  'object.constraint_add': "Add Constraint",
   'object.curves_empty_hair_add': "Add Empty Curves",
-  'object.curves_random_add': "Add Random Curves",
-  'object.data_instance_add': "Add Object Data Instance",
-  'object.delete': "Delete",
-  'object.duplicate': "Duplicate Objects",
   'object.effector_add': "Add Effector",
   'object.empty_add': "Add Empty",
-  'object.empty_image_add': "Add Empty Image/Drop Image to Empty",
   'object.grease_pencil_add': "Add Grease Pencil",
-  'object.grease_pencil_dash_modifier_segment_add': "Add Segment",
-  'object.grease_pencil_time_modifier_segment_add': "Add Segment",
   'object.lattice_add_to_selected': "Add Lattice Deformer",
   'object.light_add': "Add Light",
   'object.lightprobe_add': "Add Light Probe",
   'object.location_clear': "Clear Location",
-  'object.material_slot_add': "Add Material Slot",
   'object.metaball_add': "Add Metaball",
-  'object.modifier_add': "Add Modifier",
   'object.origin_set': "Set Origin",
-  'object.particle_system_add': "Add Particle System Slot",
   'object.pointcloud_random_add': "Add Point Cloud",
   'object.quick_fur': "Quick Fur",
   'object.rotation_clear': "Clear Rotation",
   'object.scale_clear': "Clear Scale",
-  'object.shaderfx_add': "Add Effect",
-  'object.shape_key_add': "Add Shape Key",
   'object.speaker_add': "Add Speaker",
   'object.text_add': "Add Text",
   'object.transform_apply': "Apply Object Transform",
-  'object.vertex_group_add': "Add Vertex Group",
   'object.volume_add': "Add Volume",
-  'object.volume_import': "Import OpenVDB Volume",
   'surface.primitive_nurbs_surface_circle_add': "Add Surface Circle",
   'surface.primitive_nurbs_surface_curve_add': "Add Surface Curve",
   'surface.primitive_nurbs_surface_cylinder_add': "Add Surface Cylinder",
@@ -972,35 +797,7 @@ async function runBlenderOperator(
   return { made, error: null };
 }
 
-/**
- * THE SELECTION IS BLENDER'S, AND THIS IS THE WRITE (WORK.md §THE BLENDER
- * RELEASE, B11; ARCHITECTURE-CORE §Blender north star goal 1 — *"through the
- * Blender MCP interface an agent cannot tell it is using anything other than
- * real Blender"*).
- *
- * Every selection gesture on the Model document ends here: a viewport click, a
- * box, an Outliner row, Select ▸ All/None/Invert, and the selection an
- * operator leaves behind. ONE script per gesture, because a selection is one
- * act — `select_set` per object in the view layer and one assignment to
- * `view_layer.objects.active` — and because the script door PRESENTS when it
- * returns, so the frame that comes back already carries the new `selected` and
- * `active` for {@link blenderEngineSelection} to read.
- *
- * WHY IT IS A WRITE AT ALL, when `rna_outliner` deliberately takes the
- * caller's selection instead of making one: reading a tree must not mutate the
- * document, and that rule stands. This is not a read — it is the gesture
- * itself. Before it, WALK 5 measured a click that picked the cube in this
- * editor while `bpy.context.active_object` still answered `Point`, and the
- * Shader Editor and UV Editing — which key on Blender's ACTIVE object and
- * nothing else — drew a cube's material as "No material" and its unwrap as
- * blank. There is no second selection to reconcile now: the engine holds it.
- *
- * THE LOOP IS OVER `view_layer.objects`, not `bpy.data.objects`: an object
- * outside the view layer has no selection flag to set and `select_set` refuses
- * it by name. `bpy.data.objects.get` for the active is the same care — a name
- * the tree still holds but the engine has deleted answers None rather than
- * raising, and None is what Blender's own "no active object" is.
- */
+
 async function writeBlenderSelection(
   names: readonly string[],
   active: string | null,
@@ -1030,12 +827,7 @@ async function writeBlenderSelection(
  * menu runs (`blender-header-menus.tsx`: Apply, Clear, Set Origin), and the
  * same shape {@link StructureProvider}'s own delete and duplicate use.
  *
- * THE CONTEXT OVERRIDE IS THE WHOLE POINT. Every one of these operators reads
- * `context.selected_objects` (and `selected_editable_objects`); the engine runs
- * headless with no 3D view, and its selection is not the panel's, so the
- * subject is STATED per call rather than written into the engine first — a
- * write the document would then save, and the one `rna_outliner` already
- * refuses to make for the same reason.
+ * Supply the named objects through a context override for the headless operator.
  *
  * `call` is the bare `bpy.ops.…(…)` expression, so a caller reads exactly what
  * Blender will run and the ack can quote it.
@@ -1069,9 +861,7 @@ const PROVENANCE: AuthoringProvenance = {
     'Editing the model is a bpy call; the eye and render columns write the engine directly.',
 };
 
-/** The eye is not what excluded a collection, and a row whose eye refuses must
- *  say which column did. The checkbox is beside it now (I3 follow-up (b)), so
- *  this names it rather than apologising for its absence. */
+/** An eye refusal names the restriction column that excludes the collection; the checkbox is beside it. */
 const EXCLUDED_REASON =
   'This collection is excluded from the view layer (LayerCollection.exclude), so its viewport ' +
   'visibility is not what is hiding it. Clear the Exclude checkbox on this row first.';
@@ -1080,7 +870,7 @@ const EXCLUDED_REASON =
  * THE OUTLINER AUTHORING FOR A STAGE DRAWING `presented`: the rows are Blender's either way, and
  * the view is where a row meets the three object its stage picks, outlines and moves. The Model
  * document's own area draws the published view ({@link createBlenderOutlinerAuthoring}); a split
- * area draws a follower of it (`BlenderRuntimeView.follow`, `blender-render-view.tsx`).
+ * area draws a follower of it (`BlenderRuntimeView.follow`).
  */
 export function blenderOutlinerAuthoringFor(
   presented: () => PresentedView | null,
@@ -1121,7 +911,7 @@ export function blenderOutlinerAuthoringFor(
   const rows = (): ReadonlyMap<string, BlenderOutlinerRow> => blenderOutlinerState().byId;
 
   /** The object a ROW belongs to, as a three object — the place the two id
-   *  spaces meet (see the header). */
+   *  spaces meet. */
   const objectForRow = (id: string): THREE.Object3D | null => {
     const row = rows().get(id);
     const view = presented();
@@ -1130,8 +920,7 @@ export function blenderOutlinerAuthoringFor(
     return row.object === undefined ? null : view.objectForBlenderName(row.object);
   };
 
-  /** The row for a presented OBJECT: its address is the object's own, so this
-   *  is a map lookup rather than a walk. */
+  /** Find the object row whose presented Blender object has this identity. */
   const rowIdForObject = (object: THREE.Object3D): string | null => {
     const view = presented();
     if (view === null) return null;
@@ -1149,19 +938,7 @@ export function blenderOutlinerAuthoringFor(
     return null;
   };
 
-  /**
-   * THE SAME MEETING POINT, RUN BACKWARDS — normalize an id that arrived from
-   * outside into one of OUR rows (see the header's "both ways").
-   *
-   * A row id passes straight through. Anything else is the PRESENTATION's id,
-   * because that is what `selection.set` below publishes into the shell store
-   * — and the gizmo block reads `store.selectedEntityId`, so the viewport asks
-   * this adapter about ids it minted itself. Measured 2026-09-21 on a cold
-   * model scaffold: without this, `adapterOnlyToolOwner` (which gates on
-   * `hierarchy.node(id) !== null`) answered null for every selection, so the
-   * 3D tool context never claimed the surface and the gizmo stayed detached
-   * even with `capabilities.transform` true.
-   */
+  /** Normalize external presentation ids to Outliner row ids. Existing row ids pass through; foreign ids resolve through their presented object. */
   const rowIdFor = (id: string): string | null => {
     if (rows().has(id)) return id;
     const object = threeObject(defaultAdapter.hierarchy, id);
@@ -1177,14 +954,12 @@ export function blenderOutlinerAuthoringFor(
   /** An id in the DEFAULT adapter's space, for the reads it owns. */
   const presentationIdFor = (id: string): string | null => {
     const object = objectFor(id);
-    return object === null ? null : (defaultAdapter.hierarchy.idForObject3D?.(object) ?? null);
+    return object === null ? null : defaultAdapter.hierarchy.idForNativeObject(object);
   };
 
   const hierarchy: HierarchyProvider = {
     roots: () => {
-      // THE READ IS DRIVEN FROM HERE, for I1's reason: the panel is the only
-      // thing that always runs, and `showBlenderOutliner` is idempotent and
-      // schedules its work outside the render pass.
+      // Drive the idempotent Outliner read from the panel; it schedules work outside the render pass.
       showBlenderOutliner(selectedObjects());
       const state = blenderOutlinerState();
       return (state.tree?.rows ?? []).map((row) => nodeFor(row, null));
@@ -1200,8 +975,8 @@ export function blenderOutlinerAuthoringFor(
       const row = rowId === null ? undefined : state.byId.get(rowId);
       return row === undefined ? null : nodeFor(row, state.parentOf.get(row.id) ?? null);
     },
-    object3D: (id) => objectFor(id),
-    idForObject3D: (object: THREE.Object3D) => rowIdForObject(object),
+    nativeObject: (id) => objectFor(id),
+    idForNativeObject: (object: THREE.Object3D) => rowIdForObject(object),
   };
 
   /** The Blender object NAMES our selection covers — what the door wants. */
@@ -1217,16 +992,16 @@ export function blenderOutlinerAuthoringFor(
 
   /** Keep the PRESENTATION in step: the viewport's selection outline and the
    *  gizmo bind to the default adapter's own ids, so a Blender row's object is
-   *  pushed through its `idForObject3D`. The one place that push happens — a
+   *  pushed through its `idForNativeObject`. The one place that push happens — a
    *  gesture and a frame both end here. */
   const publishPresentation = (): void => {
     const mapped: string[] = [];
     for (const id of selected) {
       const object = objectFor(id);
-      const mappedId = object === null ? null : defaultAdapter.hierarchy.idForObject3D?.(object);
+      const mappedId = object === null ? null : defaultAdapter.hierarchy.idForNativeObject(object);
       if (mappedId) mapped.push(mappedId);
     }
-    defaultAdapter.selection?.set(mapped, { intent: 'exact' });
+    defaultAdapter.selection.set(mapped, { intent: 'exact' });
     notify();
   };
 
@@ -1248,9 +1023,9 @@ export function blenderOutlinerAuthoringFor(
   const syncFromEngine = (): void => {
     if (disposed || pendingSelection !== null) return;
     const engine = blenderEngineSelection();
-    const key = `${blenderOutlinerVersion()}${engine.active ?? ''}${[...engine.selected]
+    const key = `${blenderOutlinerVersion()}\0${engine.active ?? ''}\0${[...engine.selected]
       .sort()
-      .join('
')}`;
+      .join('\u0001')}`;
     if (key === lastEngineKey) return;
     lastEngineKey = key;
     const names = engine.selected.filter((name) => name !== engine.active);
@@ -1267,22 +1042,7 @@ export function blenderOutlinerAuthoringFor(
       if (disposed) return;
       const request = Symbol('Blender selection');
       pendingSelection = request;
-      // NORMALIZED, because ids arrive in BOTH SPACES (the header's "both
-      // ways"). A hierarchy click and this adapter's own verbs speak ROW ids;
-      // the viewport's MARQUEE speaks the presentation's, because it picks
-      // three objects and hands back whatever the default adapter calls them.
-      //
-      // MEASURED 2026-09-21: a box select across the scene left `selection`
-      // holding nine `source-object:…` ids, so every row in the Outliner read
-      // as unselected, the Properties rail had no Blender subject, and the
-      // gizmo's own `rowIdFor` was the only thing in the file still working.
-      // `rowIdFor` is the one function that answers for either space, and this
-      // is the other end of the same seam `hierarchy.node` already normalizes.
-      // An id that resolves to no row is DROPPED rather than stored: a row id
-      // is this provider's whole currency and a foreign one is not a selection.
-      // The WRITE below still names a presented object that has no row yet.
-      // One row lookup per id: `rowIdForObject` scans the object rows, and a marquee over a
-      // large scene passes every object it covers.
+      // Normalize row and presentation ids through rowIdFor once per id. Drop ids with no row; the write can still name a presented object awaiting its tree row.
       const rowIds = ids.map(rowIdFor);
       selected = rowIds.filter((id): id is string => id !== null);
       publishPresentation();
@@ -1311,12 +1071,7 @@ export function blenderOutlinerAuthoringFor(
           else if (!names.includes(name)) names.push(name);
           return;
         }
-        // A PRESENTED OBJECT PAST THE TREE'S PAGE IS STILL BLENDER'S. `rna_outliner`
-        // answers the first `_OUTLINER_PAGE` rows of every child list, so in a larger
-        // scene the viewport picks objects that have no row yet (Canyon Comet: 1,146 rows
-        // under its one collection, 64 answered, all six karts among the rest). The view
-        // names the object by identity; the tree read for the frame this write presents
-        // keeps the selection's rows (`page_tree`), and `syncFromEngine` takes the row up.
+        // A presented object outside the Outliner page remains selectable by frame identity. The next tree read includes the selected rows, and syncFromEngine maps them into selection.
         const object = threeObject(defaultAdapter.hierarchy, id);
         const name = object === null ? null : (view?.blenderObjectName(object) ?? null);
         if (name === null) unnamed.push(id);
@@ -1360,12 +1115,7 @@ export function blenderOutlinerAuthoringFor(
       if (restrict === undefined) return [];
       const row = rows().get(id);
       const properties: PropertyDescriptor[] = [
-        // WRITABLE ON AN OBJECT ROW since 2026-09-21 — Blender renames a
-        // datablock on a double-click or F2 in its own Outliner, and the
-        // "this Outliner inspects" refusal this replaced stopped being true
-        // when the gizmo started writing. {@link InspectorProvider.editability}
-        // is where the per-row answer is, and it is what a COLLECTION row
-        // still refuses.
+        // Object rows support rename. InspectorProvider.editability supplies the per-row refusal for other datablocks.
         { path: 'name', label: 'Name', type: 'string', readonly: !isObjectRow(row) },
       ];
       // The RESERVED paths the hierarchy's restriction columns read
@@ -1375,11 +1125,7 @@ export function blenderOutlinerAuthoringFor(
         properties.push({ path: 'visible', label: 'Show in Viewport', type: 'boolean' });
       if (restrict.render !== undefined)
         properties.push({ path: 'renderVisible', label: 'Show in Renders', type: 'boolean' });
-      // THE EXCLUDE CHECKBOX, on the rows Blender draws it on — layer
-      // collections, and only under the View Layer display
-      // (`outliner_draw.cc:1634-1653`, guarded by `SO_RESTRICT_ENABLE`, which
-      // is in the default set at `space_outliner.cc:399`). The door already
-      // answered `exclude` for those rows; what was missing was the column.
+      // Draw the exclude checkbox only on layer collections in the View Layer display (outliner_draw.cc, SO_RESTRICT_ENABLE).
       if (restrict.exclude !== undefined)
         properties.push({ path: 'exclude', label: 'Exclude from View Layer', type: 'boolean' });
       return properties;
@@ -1403,15 +1149,7 @@ export function blenderOutlinerAuthoringFor(
       const row = rows().get(id);
       if (row === undefined) return { writable: false };
       if (path === 'name') {
-        // BLENDER RENAMES IN ITS OWN OUTLINER — a double-click on the name, or
-        // F2 (`outliner_item_rename`, `outliner_tools.cc`) — and the refusal
-        // that used to stand here ("this Outliner inspects") stopped being
-        // true the moment the transform gizmo started writing `matrix_world`.
-        // It is withdrawn for OBJECT rows, and only those: a collection, a
-        // modifier, a vertex group and a bone each rename through a different
-        // datablock's own `name`, and this unit does not reach them (WORK.md
-        // §THE BLENDER RELEASE, B6 — "Collections stay read-only for this
-        // unit, by name").
+        // Object rows rename through their object datablock. Other row types require their own datablock writer and remain read-only.
         if (isObjectRow(row)) return { writable: true };
         return {
           writable: false,
@@ -1445,10 +1183,7 @@ export function blenderOutlinerAuthoringFor(
         const name = String(value);
         if (name === row.name || name.length === 0) return;
         await blenderRnaSet(`bpy.data.objects[${py(row.object)}]`, 'name', name);
-        // EVERY ROW ID THIS NAME OWNED IS NOW STALE — a row's id IS its RNA
-        // address (`bpy.data.objects["Cube"]`), so a rename changes it. Re-read
-        // and re-publish the selection, or the panels go on addressing a
-        // datablock `bpy.data.objects` no longer has.
+        // RNA-address row ids change on rename. Re-read the tree and re-publish selection against the new addresses.
         await refreshBlenderOutliner([name]);
         const renamed = rowIdForName(name);
         if (renamed !== null) selection.set([renamed]);
@@ -1464,40 +1199,7 @@ export function blenderOutlinerAuthoringFor(
     },
   };
 
-  /**
-   * THE GIZMO IS ONE MORE bpy WRITER (owner, 2026-09-21: *"I don't see the
-   * gizmo in the blender app. Why not?"*).
-   *
-   * The precedent is the Object tab's Transform panel, transcribed by METHOD:
-   * a field there writes through `blender-properties-model.ts`'s
-   * `writeBlenderRnaProperty` → `blenderRnaSet` → `session.py::rna_set`, and
-   * the write PRESENTS, so the picture that comes back is the engine's own
-   * reading rather than ours. This provider is that same door driven by a
-   * drag: `apply` moves the PRESENTED object so the picture follows the
-   * pointer, and `endEdit` makes exactly ONE write when the gesture closes.
-   *
-   * WHAT IS WRITTEN IS `matrix_world`, not `location`/`rotation_euler`/`scale`.
-   * Blender's own setter (`rna_Object_matrix_world_update` →
-   * `BKE_object_apply_mat4`) decomposes a world matrix through the parent,
-   * `matrix_parent_inverse`, the delta transforms and the object's
-   * `rotation_mode`. That is Blender's math and it stays Blender's; we hand it
-   * the matrix.
-   *
-   * THE ORIENTATION IS GATED BY THE ROUND TRIP, not by a claim. `blenderRnaSet`
-   * bumps the RNA version and the write presents, so the frame that follows
-   * re-sets this object's matrix from the engine — if the rows/columns or the
-   * axis permutation were wrong, the object would JUMP the moment it came
-   * back. No jump is the proof.
-   *
-   * LOCKS ARE NOT READ, and that is stated rather than silently skipped:
-   * `lock_location`/`lock_rotation`/`lock_scale` constrain Blender's own
-   * interactive transform operators, not a matrix assignment, and the Outliner
-   * rows this adapter draws do not carry them.
-   *
-   * There is deliberately no `remove`: a Blender object has no absent
-   * transform channel to drop, so the protocol's removal door refuses by name
-   * instead of falling back to a value write.
-   */
+  /** The gizmo previews changes on the presented object and writes matrix_world once at endEdit through the RNA door. Blender decomposes it through parent, delta transforms and rotation mode; the returned frame supplies the authoritative pose. Matrix assignment does not enforce interactive transform locks. Transform-channel removal refuses by name. */
   const transforms: TransformProvider = {
     get: (id) => {
       // THE DEFAULT ADAPTER'S OWN READER, on the mapped id. A presented object
@@ -1506,14 +1208,12 @@ export function blenderOutlinerAuthoringFor(
       // decomposes instead — inventing a second reader here is how the two
       // would drift.
       const mapped = presentationIdFor(id);
-      return (
-        (mapped === null ? undefined : defaultAdapter.transforms?.get(mapped)) ?? NO_TRANSFORM()
-      );
+      return mapped === null ? NO_TRANSFORM() : defaultAdapter.transforms.get(mapped);
     },
     /** WHAT THIS DOES NOT ASK: the object's `lock_location`/`lock_rotation`/
      *  `lock_scale`. Those constrain Blender's own interactive operators, not a
      *  matrix assignment, and an Outliner row does not carry them — so a locked
-     *  channel still moves here. See the header. */
+     *  channel still moves here. */
     editability: (id) => {
       const rowId = rowIdFor(id);
       const row = rowId === null ? undefined : rows().get(rowId);
@@ -1531,7 +1231,7 @@ export function blenderOutlinerAuthoringFor(
      *  without writing — `dragging-changed` fires on pointerdown, and a write
      *  that changes nothing still presents and still dirties the `.blend`.
      *  Keyed by the OBJECT rather than the id, because the viewport addresses
-     *  one gesture in both id spaces (see the header). */
+     *  one gesture in both id spaces. */
     beginEdit: (id) => {
       const object = objectFor(id);
       if (object !== null && !gestureStart.has(object)) {
@@ -1554,8 +1254,9 @@ export function blenderOutlinerAuthoringFor(
       // `matrixWorld`, would sit still with them.
       object.updateMatrix();
       object.updateMatrixWorld(true);
-      // And every other area drawing the model moves with it, as Blender redraws them all.
-      presented()?.mirrorPose?.(object);
+      // And every other area drawing the model moves with it, as Blender redraws them all; the
+      // move is signalled as a change of what the views draw, this one's included.
+      presented()?.mirrorPose(object);
     },
     endEdit: async (id): Promise<WriteAck | undefined> => {
       const object = gestureObjects.get(id) ?? objectFor(id);
@@ -1613,41 +1314,13 @@ export function blenderOutlinerAuthoringFor(
    * is what keeps the Outliner, the Properties rail and the viewport's gizmo
    * looking at one subject.
    */
-  const selectAfterOperator = async (made: readonly string[]): Promise<string> => {
+  const selectAfterOperator = async (made: readonly string[]): Promise<void> => {
     await refreshBlenderOutliner(made);
     const ids = made.map(rowIdForName).filter((id): id is string => id !== null);
     if (ids.length > 0) selection.set(ids);
-    return ids[0] ?? '';
   };
 
-  /**
-   * ADD, DELETE, DUPLICATE — BLENDER'S OWN OPERATORS, NAMED HERE AND RUN THERE
-   * (WORK.md §THE BLENDER RELEASE, B6; ARCHITECTURE-CORE §Blender north star
-   * goal 3 as amended: "can make MACRO adjustments at the screen — move,
-   * rotate, scale a part, add or remove one, rename it … each a bpy call
-   * through the doors that exist").
-   *
-   * Every verb is one `bpy.ops` call through the script door
-   * (`blenderExecute`), which presents afterwards, so what comes back is the
-   * engine's reading and never ours. The operators carry semantics we would
-   * otherwise have to reimplement and get subtly wrong — `object.delete`
-   * unparents a deleted object's children the way Blender does, which
-   * `bpy.data.objects.remove` does not; `object.duplicate` copies the object's
-   * data, its modifiers, its material slots and its parent relationship under
-   * the user's own duplication preferences — so naming the operator IS the
-   * implementation.
-   *
-   * THE CONTEXT OVERRIDE IS WHAT MAKES A ROW THE SUBJECT. `object.delete` and
-   * `object.duplicate` read `context.selected_objects`; the engine runs
-   * headless with no view3d and its selection is not the panel's, so each verb
-   * states its subject with `bpy.context.temp_override(...)` rather than
-   * writing the engine's selection first — a write the document would then
-   * save.
-   *
-   * The script door checkpoints Blender's native undo stack and records its
-   * callback in Code-OSS. These operators are undone by restoring Blender's
-   * state, never by constructing an inverse operator or replaying the script.
-   */
+
   /**
    * ADD ▸ CAMERA LOOKS THE WAY THE VIEW LOOKS, AND IS THE SCENE'S CAMERA WHEN THERE IS NONE: what
    * `object_camera_add_exec` does with the 3D View it runs in (`object_add.cc`: `align` forced to
@@ -1657,7 +1330,7 @@ export function blenderOutlinerAuthoringFor(
    * location (the 3D cursor) kept, and the scene camera after it.
    */
   const cameraAddCall = (): string => {
-    const areaId = (defaultAdapter as { documentId?: string }).documentId?.replace(/^object3d-document:/, '');
+    const areaId = defaultAdapter.documentId.replace(/^object3d-document:/, '');
     const camera = viewportStages().find((one) => one.documentId === areaId)?.rig().drawCamera() ?? null;
     const view = presented();
     const lines = ['bpy.ops.object.camera_add()', 'added = bpy.context.view_layer.objects.active'];
@@ -1671,7 +1344,7 @@ export function blenderOutlinerAuthoringFor(
     return lines.join('\n');
   };
 
-  const structure: StructureProvider = {
+  const structure: BlenderOutlinerHandle['structure'] = {
     /**
      * BLENDER'S ADD MENU, FOR EVERY PARENT — `parentId` is deliberately not
      * read. Blender's Add adds to the ACTIVE COLLECTION, never under whatever
@@ -1708,12 +1381,7 @@ export function blenderOutlinerAuthoringFor(
         ack: (async (): Promise<WriteAck> => {
           const { made, error } = await runBlenderOperator(call);
           if (error !== null) return refuse(error);
-          // AN OPERATOR THAT MADE NOTHING IS A REFUSAL, not a quiet success.
-          // Blender's file-browser operators answer `{'CANCELLED'}` — a status
-          // the script door reports no error for — with `bpy.data.objects`
-          // unchanged, which is exactly the silent degrade `_absent_capability`
-          // exists to stop (`session.py`'s own note). The set difference this
-          // door already computes is what catches it.
+          // Treat an operator with no new object as a refusal even when Blender returns CANCELLED without a script error.
           if (made.length === 0)
             return refuse(
               `Blender ran ${call} and created nothing. The operator reported no error, so it ` +
@@ -1728,7 +1396,7 @@ export function blenderOutlinerAuthoringFor(
         })(),
       };
     },
-    remove: (id) => structure.removeMany?.([id]) ?? undefined,
+    remove: (id) => structure.removeMany([id]),
     /**
      * BLENDER'S OWN DELETE, for one row or a whole selection. `object.delete`
      * is the operator the X key runs (`blender_default.py:4552`, with
@@ -1740,7 +1408,8 @@ export function blenderOutlinerAuthoringFor(
       for (const id of ids) {
         const name = objectNameFor(id);
         if (name === null) {
-          const row = rowIdFor(id) === null ? undefined : rows().get(rowIdFor(id)!);
+          const rowId = rowIdFor(id);
+          const row = rowId === null ? undefined : rows().get(rowId);
           return refuse(
             `Only an object can be deleted here; this row is a ${row?.struct ?? row?.type ?? 'row'}. ` +
               'Deleting a collection, a modifier or a vertex group is that datablock’s own bpy call.',
@@ -1824,12 +1493,7 @@ export function blenderOutlinerAuthoringFor(
         persisted: true,
       };
     },
-    /** REFUSED BY NAME. Parenting in Blender is `object.parent_set`, and it is
-     *  a gesture of its own with a type to choose (Object, Object Keep
-     *  Transform, Armature Deform, …) and a `matrix_parent_inverse` to settle.
-     *  A drag in a tree cannot mean one of those without saying which, so this
-     *  unit does not guess (WORK.md §THE BLENDER RELEASE, B6 — parenting is
-     *  not in it). */
+    /** Refuse tree reparenting: Blender parenting requires an explicit operator type and matrix_parent_inverse choice. */
     reparent: () =>
       refuse(
         "Reparenting is Blender's `bpy.ops.object.parent_set`, which needs a parent TYPE " +
@@ -1839,22 +1503,12 @@ export function blenderOutlinerAuthoringFor(
   };
 
   const adapter: BlenderOutlinerAdapter = {
-    // THE DOCUMENT'S OWN IDENTITY CARRIES OVER, and forgetting it is what the
-    // walk caught first: this package's Properties sections resolve their
-    // subject by asking the ACTIVE adapter for `documentId`, `hierarchy.object3D`
-    // and `documentRootObject` (`blender-properties-model.ts`,
-    // `isObject3DAuthoring`) — a structural check, because a contributed
-    // package holds no host type. An adapter that overrides the tree and drops
-    // those two members is a DIFFERENT adapter to that check, and the whole
-    // Properties rail silently stopped matching: selecting the Rig drew the
-    // host's bare identity row instead of Blender's tabs (measured 2026-09-19).
-    // They are getters rather than copies because the default adapter answers
-    // both from live state.
+    // Delegate the document identity and root; the hierarchy resolves each row's presented object.
     get documentId() {
-      return (defaultAdapter as { documentId?: string }).documentId;
+      return defaultAdapter.documentId;
     },
     get documentRootObject() {
-      return (defaultAdapter as { documentRootObject?: THREE.Object3D | null }).documentRootObject;
+      return defaultAdapter.documentRootObject;
     },
     capabilities: CAPABILITIES,
     provenance: PROVENANCE,
@@ -1866,7 +1520,7 @@ export function blenderOutlinerAuthoringFor(
     subscribe: (listener) => {
       listeners.add(listener);
       const stopTree = subscribeBlenderOutliner(listener);
-      const stopDefault = defaultAdapter.subscribe?.(listener) ?? (() => {});
+      const stopDefault = defaultAdapter.subscribe(listener);
       return () => {
         listeners.delete(listener);
         stopTree();
@@ -1895,14 +1549,6 @@ export function blenderOutlinerAuthoringFor(
     },
     rowIdForObject: (name) => rowIdForName(name),
     structure,
-    subscribe: (listener) => {
-      listeners.add(listener);
-      const stopTree = subscribeBlenderOutliner(listener);
-      return () => {
-        listeners.delete(listener);
-        stopTree();
-      };
-    },
   };
   liveOutliners.add(handle);
   // A factory is called during the stage's React render. Notify the other roots