@volter/project 0.5.211 → 0.5.213

package/src/adapter/authoring.ts

@@ -1,33 +1,13 @@
 /**
- * AuthoringAdapter — the editor's authoring contract. The editor talks to THIS,
- * keyed by opaque string node ids, instead of to a concrete document format.
+ * Authoring providers expose document operations through opaque node ids. Each
+ * integration owns its model and adapter; the editor consumes these interfaces
+ * and declared capabilities without selecting an implementation by type.
  *
- * An implementer's document model is its own private business; an ingested
- * game's adapter implements the same
- * providers directly over its live `Object3D` tree. The editor sees only the
- * interface and the advertised `capabilities` — it never branches on which
- * implementer it is talking to.
- *
- * The interface lives in the engine (not the editor) so `MountedThreeRoot.authoring`
- * can reference it without the engine depending on the editor; implementers live
- * in `packages/editor/src/authoring/`.
- *
- * **Reserved inspector paths convention:** the property paths `name`, `visible`,
- * `locked`, `renderVisible` and `exclude` are reserved — an adapter that
- * supports them exposes them through the ordinary `InspectorProvider.get`/`set`
- * (no separate provider). The shell renders the hierarchy panel's rename field,
- * eye (visibility) toggle, lock toggle, render-camera toggle and
- * exclude checkbox against these paths, generically, for any adapter that
- * reports them via `InspectorProvider.properties`.
- *
- * A COLUMN FOLLOWS WHAT THE ADAPTER ANSWERS, never a chrome knob (owner ruling,
- * 2026-09-19). `renderVisible` and `exclude` are answered by almost nothing —
- * three.js has ONE `Object3D.visible` governing viewport and render alike, and
- * nothing but a view layer has an exclusion — so their columns are absent or a
- * reserved blank cell, and appear the moment an adapter whose truth really does
- * separate them says so. `exclude` and `renderVisible` are reported in the
- * sense their name carries: `exclude: true` means EXCLUDED, `renderVisible:
- * false` means hidden from renders.
+ * Reserved inspector paths `name`, `visible`, `locked`, `renderVisible` and
+ * `exclude` use ordinary InspectorProvider properties/get/set. Hierarchy columns
+ * follow the properties the adapter reports. `exclude: true` means excluded;
+ * `renderVisible: false` means hidden from renders. An adapter with one shared
+ * visibility flag need not invent separate render visibility or exclusion.
  */
 
 import type { Transform } from './transform';
@@ -48,7 +28,7 @@ export interface AuthoringCapabilities {
 
 /**
  * The adapter's own answer to "what is truth behind these rows, and how
- * writable is it" (spec 29 §5). Provenance never varies WITHIN one adapter's
+ * writable is it". Provenance never varies WITHIN one adapter's
  * rows — it is a property of the world boundary — so it is declared ONCE per
  * adapter and rendered at the SEAM (the composite's `world:<id>` group row,
  * or the panel header for a bare adapter), never per row. Only the adapter
@@ -62,11 +42,11 @@ export interface AuthoringProvenance {
   /**
    * What the rows project:
    * - `document` — an authored data file the editor owns (e.g. a scene file);
-   * - `source-code` — the game's own source is the document (e.g. JSX);
+   * - `source-code` — the project's own source is the document (e.g. JSX);
    * - `foreign` — a live tree the editor does not own (an unmodified external
-   *   game, or any world edited only through an overlay); edits go to the
+   *   project, or any world edited only through an overlay); edits go to the
    *   overlay, never the source;
-   * - `live` — a running game adopted at play time; ordinary edits are not persisted;
+   * - `live` — a running project adopted at play time; ordinary edits are not persisted;
    * - `boundary` — a declared world with no live editing surface here.
    */
   source: 'document' | 'source-code' | 'foreign' | 'live' | 'boundary';
@@ -82,7 +62,7 @@ export interface AuthoringProvenance {
  * Semantic place a node occupies in the universal authoring hierarchy.
  *
  * `kind` below remains the adapter's native kind (`mesh`, `button`,
- * `pixi-container`, ...). `role` says what the row MEANS to the editor shell,
+ * `sprite`,...). `role` says what the row MEANS to the editor shell,
  * so presentation and interaction never have to infer semantics from an id,
  * label, or substrate-specific kind string.
  */
@@ -99,11 +79,13 @@ export type EditorNodeRole =
 
 /** A node in the authoring hierarchy — format-neutral. */
 export interface EditorNode {
-  /** STABLE id — survives reload (see ingest structural-path ids). */
+  /** Stable node id that survives reload. */
   id: string;
   label: string;
-  /** Adapter-declared semantic role. Optional for third-party/older adapters;
-   * the shell falls back to the native `kind` only for icon selection. */
+  /**
+   * Optional semantic role. Icon selection uses the native `kind` when no role
+   * is declared.
+   */
   role?: EditorNodeRole;
   /** Optional source-owned context kept visually subordinate to `label`, such
    * as `<header>` beneath a React component name or a document's file path. */
@@ -121,16 +103,14 @@ export interface EditorNode {
   childIds: string[];
   /**
    * THIS ADAPTER'S OWN DEFAULT OPEN STATE for this row, overriding the shell's
-   * shape heuristic (`GameHierarchy.tsx`'s `defaultExpansionByNode`, which
+   * shape heuristic (`Hierarchy.tsx`'s `defaultExpansionByNode`, which
    * infers openness from authored depth and branch shape).
    *
    * It exists because one adapter genuinely knows better than any shape rule
-   * can: Blender's Outliner has an explicit per-element flag
-   * (`outliner_tree.cc:139` makes every fresh element CLOSED; only the Scene
-   * Collection and the layer collections clear it,
-   * `tree_display_view_layer.cc:130,167`), so "collections open, objects
-   * closed" is a fact about the tree rather than a guess about it. Omitted —
-   * which is every other adapter — leaves the heuristic exactly as it was.
+   * can: a tree whose own model stores an explicit per-element open flag
+   * answers "collections open, objects closed" as a fact about the tree rather
+   * than a guess about it. Omitted — which is every adapter without such a
+   * flag — leaves the heuristic exactly as it was.
    */
   defaultExpanded?: boolean;
   /** Opaque project-owned identity shared by authored rows across adapter roots. */
@@ -160,15 +140,9 @@ export interface PropertyDescriptor {
   readonlyReason?: string;
   options?: unknown[];
   /**
-   * Optional domain-shaped grouping (T3.4 slice 2): properties sharing the
-   * same `group` label render together under a titled sub-section in the
-   * generic inspector, instead of the flat property grid. Backward-compatible
-   * — omitted (or two descriptors with different/no `group`) renders exactly
-   * as before this field existed. This is the ONLY authoring-richness
-   * addition v1 makes; there is no schema and no new PropertyDescriptor
-   * `type` — a custom adapter reports its own domain concepts
-   * (health/score/an enum, …) through the SAME provider, merely labeled into
-   * a named group.
+   * Optional domain grouping. Properties with the same `group` label render in a
+   * named subsection of the generic inspector. Ungrouped properties retain the
+   * flat grid; grouping does not change descriptor types or write semantics.
    */
   group?: string;
   /**
@@ -216,18 +190,18 @@ export interface HierarchyProvider {
    */
   crossSurfaceStructureSignature?(): string | null;
   /**
-   * OPTIONAL, THREE-SURFACE — the live scene object for raycast/gizmo binding
-   * (null for a node this adapter has no object for), opaque here: its Three
-   * typing is `@volter/editor-threejs`'s `threeHierarchy`. A Pixi, DOM or React
+   * OPTIONAL, STAGE-SURFACE — the live scene object for raycast/gizmo binding
+   * (null for a node this adapter has no object for), opaque here: its native
+   * typing is the 3D integration's. A canvas, DOM or React
    * adapter has no scene object at all: it OMITS this method rather than
    * implementing a `() => null` stub that pretends the concept applies. Callers
    * already treat `null` as "no object here", so absence and `null` mean the
-   * same thing to them — optional-chain it (`hierarchy.object3D?.(id) ?? null`).
+   * same thing to them — optional-chain it (`hierarchy.nativeObject?.(id) ?? null`).
    */
-  object3D?(id: string): unknown;
-  /** OPTIONAL, THREE-SURFACE — inverse of {@link object3D}. Same rule: an
+  nativeObject?(id: string): unknown;
+  /** OPTIONAL, STAGE-SURFACE — inverse of {@link nativeObject}. Same rule: an
    *  adapter with no scene-object tree omits it. */
-  idForObject3D?(o: unknown): string | null;
+  idForNativeObject?(o: unknown): string | null;
 }
 
 export interface SelectionProvider {
@@ -236,9 +210,11 @@ export interface SelectionProvider {
    * already name a real node (for example a folded-internal light inventory);
    * the default keeps the adapter's normal semantic component resolution. */
   set(ids: string[], options?: { intent?: 'semantic' | 'exact' }): void;
-  /** Resolve a raw native/render hit to the semantic authoring subject. The
-   * shell must not infer ownership from ancestry or substrate-specific kinds.
-   * Older adapters may omit this; raw ids then remain the selection ids. */
+  /**
+   * Resolve a native/render hit to its semantic authoring subject. The shell
+   * does not infer ownership from ancestry or substrate-specific kinds.
+   * Without this optional resolver, raw ids are the selection ids.
+   */
   resolve?(
     rawId: string,
     options?: { intent?: 'normal' | 'deep'; scopeId?: string | null },
@@ -274,16 +250,9 @@ export interface TransformEditability {
    * protocol's removal door refuses by name instead of acking a revert it did
    * not perform.
    *
-   * EACH HALF IS ANSWERED BY WHOEVER CAN SEE IT, and a lane that cannot read
-   * its own document may not invent the first. A source lane holding the
-   * file's text answers both (the first-party R3F lane reads the callsite's
-   * attributes before saying yes). A lane whose client holds only an
-   * oid → file:line index and writes through a server that resolves the
-   * address — the vendored-ingest lane — can honestly answer only the SECOND,
-   * so that is what it answers, and `remove`'s own {@link WriteAck} reports
-   * whether an attribute was actually dropped (`persisted: false` when the
-   * callsite carried none). The inverse is what is forbidden on every lane:
-   * acking a drop that took no byte.
+   * A provider reads its own document before declaring an override. A client with only a
+   * source address leaves the decision to its writer; the removal's WriteAck reports whether
+   * bytes were removed, with persisted: false when the document carried no override.
    */
   removable?: boolean;
 }
@@ -362,7 +331,7 @@ export interface InspectorProvider {
   /**
    * Optional — SHOW a value without writing it, for a control the user drags.
    *
-   * The gizmo already has this pair ({@link TransformProvider.writeTransform}
+   * The gizmo already has this pair ({@link TransformProvider.apply}
    * live, {@link TransformProvider.endEdit} persisting), and a colour picker
    * needs the same shape: it streams values continuously while the pointer
    * moves, and persisting each one is a write burst the absorb cycle cannot
@@ -392,7 +361,7 @@ export interface InspectorProvider {
    * edit/revert round trip and grades UNVERIFIABLE rather than passing.
    *
    * SAME ACK CONTRACT AS {@link set} — the pipe's per-edit {@link WriteAck}
-   * (`editor/src/authoring/write-pipe.ts`), awaited. Removal is a write; it
+   * awaited. Removal is a write; it
    * moves bytes, and the caller has the same right to be told where they went
    * and whether they moved. Returning nothing means this provider performed no
    * persisted write, and the shell reports the live-only floor.
@@ -406,36 +375,6 @@ export interface InspectorProvider {
   remove?(id: string, path: string): void | WriteAck | Promise<void | WriteAck>;
 }
 
-/**
- * An authored node that is itself an asset, even when its bytes are embedded
- * in another source document instead of living at a standalone project path.
- *
- * The first concrete case is inline SVG in a DOM/React root: its `<path>` and
- * `<g>` implementation is no more part of the authoring hierarchy than the
- * meshes inside an imported model. The adapter owns the native-to-asset
- * conversion; the shell only opens the returned image in its ordinary Asset
- * Editor document.
- */
-export interface AuthoringAssetSubject {
-  readonly kind: 'image';
-  readonly name: string;
-  readonly mediaType: 'image/svg+xml';
-  readonly text: string;
-  /** Project-root-relative source definition, when the adapter can prove it. */
-  readonly sourcePath?: string;
-}
-
-export interface AssetSubjectProvider {
-  get(id: string): AuthoringAssetSubject | null;
-  /**
-   * Assets known to this authoring document even when they are not in its
-   * currently focused hierarchy projection. React story boards use this to
-   * expose SVGs mounted in inactive story frames without flattening those
-   * frames into the active hierarchy.
-   */
-  entries?(): ReadonlyArray<{ id: string; subject: AuthoringAssetSubject }>;
-}
-
 /** A semantic jump from one authored subject to another document/subject.
  * The adapter owns resolution and opening; the inspector only presents the
  * title and exposes the same verb to human and serialized projections. */
@@ -502,8 +441,7 @@ export interface ComponentInstancesProvider {
  * `void` is the honest answer for a lane whose verb performs no write of its
  * own (an in-memory adapter mutating a graph it already owns); a lane that
  * writes returns the persistence pipe's own {@link WriteAck}
- * (`editor/src/authoring/write-pipe.ts`), awaited, so a caller that awaits the
- * verb has awaited the byte.
+ * awaited, so a caller that awaits the verb has awaited the byte.
  *
  * A structural verb resolves on ITS OWN verb: `remove` asks whether the struct
  * writer is bound, never whether the PROP writer is — resolving on a
@@ -537,10 +475,7 @@ export type StructuralWriteOutcome = void | WriteAck | Promise<void | WriteAck>;
  * `ack: undefined` (no write was attempted, which is exactly what `void` means
  * in {@link StructuralWriteOutcome}).
  *
- * Firing the write and dropping the promise on the floor — `void structOp(…)`
- * behind a `return ''` — is the shape this type exists to make unrepresentable:
- * it left the caller unable to await the byte, which is how N same-file
- * duplicates went out together, each reading the file before any wrote back.
+ * Callers await ack before starting another write to the same file.
  */
 export interface StructuralIdWrite<Id extends string | null = string> {
   /** The id the op produced — `''` when the lane cannot know it until its own
@@ -583,8 +518,7 @@ export interface StructureProvider {
    * multi-delete's writes land strictly one at a time (see that function's own
    * doc comment for why serialization + deletion order together are what make
    * a per-id loop sound for an adapter whose OID index isn't reindexed between
-   * writes). An adapter with a synchronous/in-memory remove (e.g.
-   * `UIAuthoringAdapter`) returns `void` — `await`ing it is a harmless no-op.
+   * writes). An adapter with a synchronous in-memory remove can return void.
    *
    * A source-writing lane returns THIS removal's own {@link WriteAck} (see
    * {@link StructuralWriteOutcome}).
@@ -613,12 +547,12 @@ export interface StructureProvider {
    * an adapter-specific affordance outside the generic palette).
    */
   creatableKinds?(parentId: string | null): CreatableKind[];
-  /** D3 (spec 27 §6) — wrap `id` in a new container element (default tag
+  /** wrap `id` in a new container element (default tag
    *  adapter-chosen, e.g. a `div`), re-parenting `id` as that container's sole
    *  child. Absent ⇒ the shell's context menu shows no Wrap item for this
    *  adapter. */
   wrap?(id: string, wrapperTag?: string): StructuralWriteOutcome;
-  /** D3 (spec 27 §6) — replace `id` with its own children (the inverse of
+  /** replace `id` with its own children (the inverse of
    *  `wrap`). Absent ⇒ the shell's context menu shows no Unwrap item for this
    *  adapter. */
   unwrap?(id: string): StructuralWriteOutcome;
@@ -636,25 +570,23 @@ export interface StructureProvider {
   /** Preflight for an Ungroup affordance. Omit when ungroup is never offered. */
   canUngroup?(id: string): boolean;
   /**
-   * D4.R2 (spec27 §6 D4 reopen) — remove every id in `ids` as ONE undoable
+   * remove every id in `ids` as ONE undoable
    * op (a single Ctrl+Z restores the whole batch), instead of the caller
    * looping `remove(id)` per id (which — one `remove` call = one undo push
    * per adapter, by design — produces N separate undo entries: Ctrl+Z then
    * restores them one at a time, asymmetric with the first-party adapter's
    * own single batched multi-delete undo). Absent ⇒ the shell falls back to
-   * the per-id `remove` loop (today's N-entry behavior, unchanged) — an
-   * honest degrade, not a silent behavior change, for any adapter that
+   * the per-id `remove` loop — an honest degrade for any adapter that
    * hasn't implemented batching. May optionally return an awaitable, same
    * widening `remove` documents above ({@link StructuralWriteOutcome}) and for
-   * the same reason (delete-order-residual fix): `deleteSelection`
+   * the same reason: `deleteSelection`
    * (`editor-hotkeys.ts`) awaits it so the caller can rely on the whole
    * batch's write having landed before it returns. A synchronous/in-memory
-   * implementation (e.g. `UIAuthoringAdapter`'s) returns `void` — awaiting it
-   * is a harmless no-op.
+   * implementation can return void.
    */
   removeMany?(ids: readonly string[]): StructuralWriteOutcome;
   /** Copy authored entities through the host clipboard. The adapter owns the
-   * native payload (JSX for a source-backed Three/Canvas world, native records
+   * native payload (JSX for a source-backed stage or canvas world, native records
    * for a data-backed adapter); the shell never serializes an engine-private
    * shape. */
   copy?(ids: readonly string[]): boolean | Promise<boolean>;
@@ -691,30 +623,21 @@ export interface PersistenceProvider {
    * Human/agent-readable destination this provider persists to — e.g.
    * `"src/world.tsx"`, `"live-only (not saved)"`, or `"ephemeral
    * (discarded on stop)"`. Drives the save-status UI and makes routing
-   * inspectable (design §2). Implementers whose destination can change during
+   * inspectable. Implementers whose destination can change during
    * the session (a provider that tracks the currently focused document, say)
    * should expose this as a live getter rather than a value captured once.
    */
   readonly destination: string;
   /**
-   * The reload contract (design §5): apply an external change to this
-   * provider's persisted artifact into the RUNNING session (e.g. a file-watcher
-   * update to the artifact). Absent ⇒ the host must remount to
-   * pick up external changes — the honest floor, and correctly what the
-   * ephemeral provider reports.
-   *
-   * `rawContent`, when the host has it (the file-watcher SSE payload carries the
-   * artifact's exact bytes), is an OPTIONAL second parameter enabling own-echo
-   * detection — an event that is exactly what this provider itself last wrote is
-   * its own save reflected back, and should be skipped even outside the normal
-   * debounce window (see `EditorStore.applyExternalUpdate`'s doc comment). This
-   * stays optional/provider-specific — only the first-party provider currently
-   * uses it — so other implementers can ignore the parameter entirely.
+   * Optional adapter hook for applying an external artifact change to the
+   * running session. The adapter owns delivery of these changes and chooses
+   * whether to update in place or remount. A caller can supply exact artifact
+   * bytes in `rawContent` for provider-specific own-write detection.
    */
   applyExternal?(content: unknown, rawContent?: string): void;
 }
 
-/** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
+/** per-layer viewport picking. Coordinates are client (browser) px. */
 export interface PickProvider {
   pick(clientX: number, clientY: number): string | null;
   /**
@@ -727,7 +650,7 @@ export interface PickProvider {
   candidates?(clientX: number, clientY: number, options?: { includeLocked?: boolean }): readonly string[];
 }
 
-/** D4 — storybook stories. */
+/** Storybook stories. */
 export interface StoryRef {
   id: string;
   label: string;
@@ -736,57 +659,39 @@ export interface StoriesProvider {
   storiesFor(nodeId: string): StoryRef[]; // [] = none
   active(nodeId: string): string | null;
   apply(nodeId: string, storyId: string | null): void; // null clears
-  /** Render ONLY this node against the story (storybook canvas); null exits. */
-  isolate?(nodeId: string | null, storyId?: string): void;
-  /**
-   * Display vocabulary for this provider's section — e.g. an ingested game's
-   * contract scenes say "Scenes"; absent means the default "Stories". The
-   * states are the same seam either way; only the word the human reads
-   * changes, so a game's own screens are never labelled with a design-time
-   * term the game never uses.
-   */
-  readonly title?: string;
   /**
    * Why this provider could not enumerate, or `null` when it did. An empty
    * `storiesFor` and an UNREAD one look identical from the section that draws
    * them, and only the provider knows which it is — so the PROVIDER answers,
    * and the shell never reaches past it into one particular provider's own
-   * discovery to find out (a CSF registry, a game contract's screen list).
+   * discovery to find out (a CSF registry, a project contract's screen list).
    * Absent means the provider always ran.
    */
   unavailable?(): string | null;
 }
 
 /**
- * Where a drop landed, when the shell knows. The VIEWPORT knows a world point
- * (its ground-plane raycast under the cursor); the hierarchy panel does not,
- * and passes nothing. Optional both ways: an adapter with no placement concept
- * ignores it, and a caller with no point omits it — so neither side has to
- * pretend. Coordinates are world-space, in the adapter's own units.
+ * What a drop places: a project component, named by its source module and
+ * export, and the surface it mounts on. The project's native source remains
+ * truth.
  */
 export interface AssetDropContext {
-  readonly position?: readonly [number, number, number];
-  /** Transient drag metadata. The project's native source remains truth; this
-   * only tells an adapter whether the path names a file or a source component. */
-  readonly item?:
-    | { readonly kind: 'file'; readonly name: string }
-    | {
-        readonly kind: 'component';
-        readonly name: string;
-        readonly sourcePath: string;
-        readonly exportKind: 'default' | 'named';
-        readonly surface: 'three' | 'canvas' | 'dom' | 'unknown';
-      };
+  readonly item: {
+    readonly name: string;
+    readonly sourcePath: string;
+    readonly exportKind: 'default' | 'named';
+    readonly surface: 'stage' | 'canvas' | 'dom' | 'unknown';
+  };
 }
 
-/** Asset drop (hierarchy + viewport). */
+/** Component drop (the canvas Add menu's project components). */
 export interface AssetDropProvider {
-  accepts(nodeId: string, assetPath: string, context?: AssetDropContext): boolean;
-  /** A drop that lands as an ELEMENT in the game's own source is a structural
+  accepts(nodeId: string, assetPath: string, context: AssetDropContext): boolean;
+  /** A drop that lands as an ELEMENT in the project's own source is a structural
    *  write, so it answers with the same {@link StructuralWriteOutcome} the rest
    *  of {@link StructureProvider}'s writing verbs do — a lane whose drop only
    *  mutates the running graph returns `void`. */
-  drop(nodeId: string, assetPath: string, context?: AssetDropContext): StructuralWriteOutcome;
+  drop(nodeId: string, assetPath: string, context: AssetDropContext): StructuralWriteOutcome;
 }
 
 /** Plain-object rect shape shared by {@link RectProvider} — the same fields a real
@@ -799,11 +704,11 @@ export interface DOMRectLike {
   height: number;
 }
 
-/** Per-node screen geometry — the KEYSTONE omission today (nothing produces rects the
- *  ported inspect.ts math consumes). Coordinates are **host-relative** px: relative to
- *  the adapter's own mounted world surface (its `position:absolute; inset:0` layer), the
- *  same surface the A3 selection overlay is hosted over, so the overlay can draw against
- *  these rects directly. (NOT viewport-client — the JSDoc formerly said so in error.) */
+/**
+ * Per-node screen geometry in host-relative pixels: relative to the adapter’s
+ * mounted surface, where the selection overlay draws. These are not viewport
+ * client coordinates.
+ */
 export interface RectProvider {
   /** selectable node id → its current bounding rect, or null if unmounted/offscreen */
   rect(id: string): { x: number; y: number; width: number; height: number } | null;
@@ -814,7 +719,7 @@ export interface RectProvider {
     paddingBox?: DOMRectLike;
   };
   /**
-   * D3 (spec 27 §6) — every currently-empty container this adapter's tree
+   * every currently-empty container this adapter's tree
    * contains right now: no visible children, no text, a collapsed dimension
    * (the `ui-source/inspect.ts:findEmptyContainers` math) — each with a
    * grown-to-tappable placeholder rect and a display name, driving the
@@ -881,11 +786,10 @@ export interface BoxEditProvider {
   referencePoint?(id: string): BoxEditReferencePoint | null;
 }
 
-/** Text-content editing, ON the contract: the react-world adapter implements this
- *  provider (`react-world-authoring-adapter.ts`'s `readonly text: TextProvider`),
- *  bringing its own `editText(id)` write path onto the seam, so the overlay's
- *  double-click-to-edit-text (D3) is contract-driven rather than reaching for a
- *  concrete adapter's method. */
+/**
+ * Text-content editing through the authoring contract. The overlay delegates
+ * in-place text edits to the owning adapter through this provider.
+ */
 export interface TextProvider {
   /** the element's editable pure-text, or null if the body is dynamic/has child elements */
   get(id: string): string | null;
@@ -893,7 +797,7 @@ export interface TextProvider {
 }
 
 /**
- * D3 (spec 27 §6) — background-color sampling at a viewport point, for the
+ * background-color sampling at a viewport point, for the
  * eyedropper's FALLBACK path (browsers with no native `EyeDropper` API). The
  * native API, where available, samples real rendered pixels itself and needs
  * none of this. Distinct from {@link PickProvider} (which returns a node id,
@@ -912,23 +816,23 @@ export interface ColorSampleProvider {
 }
 
 /**
- * Where a node's live object CAME FROM in the game's own truth.
+ * Where a node's live object CAME FROM in the project's own truth.
  *
  * `display` is the string the editor shows verbatim. The unanchored shape
  * carries a `reason` rather than a blank, because "we don't know" and "a
  * library built it" are different facts and neither may present as silence
  * (the honest-floor rule).
  *
- * TWO ANCHORED KINDS, because a game has two kinds of truth and only one of
+ * TWO ANCHORED KINDS, because a project has two kinds of truth and only one of
  * them is source.
  *
  *  - `source` is the original: a `new` expression at a `file:line:col` in the
- *    game's own code, which is where an edit to a constructor literal has to be
+ *    project's own code, which is where an edit to a constructor literal has to be
  *    written.
- *  - `data` is the sibling a level-based game needs. Its placed cargo — the
+ *  - `data` is the sibling a level-based project needs. Its placed cargo — the
  *    enemies, the pickups, the objectives — reaches no source literal at all;
- *    it is binary records inside a level file that the game parses at load. An
- *    authored move of one is therefore an edit to THE GAME'S OWN DATA, and
+ *    it is binary records inside a level file that the project parses at load. An
+ *    authored move of one is therefore an edit to THE PROJECT'S OWN DATA, and
  *    the honest anchor is the data file plus the index of the record that
  *    addresses the object inside it.
  *
@@ -946,7 +850,7 @@ export type NodeCreationSite =
   | {
       anchored: true;
       kind: 'data';
-      /** Project-relative path of the game's own data file, POSIX separators. */
+      /** Project-relative path of the project's own data file, POSIX separators. */
       file: string;
       /** Index of the record inside that file which addresses this object. */
       record: number;
@@ -964,15 +868,14 @@ export type NodeCreationSite =
  * two are not the same fact — two nodes can both be `{ kind: 'source' }` at a
  * `file:line` and still be written by different lanes with different gates.
  *
- * Each kind's CORRECTNESS CONTRACT, and the named test that proves it:
+ * Each kind's persistence contract:
  *
- *  - `source-prop` — the value is a literal PROP on an element of the game's own
+ *  - `source-prop` — the value is a literal PROP on an element of the project's own
  *    source (a JSX attribute the serve-time authoring stamp addresses). Lands at
  *    the anchor; survives a cold remount, because the file is truth and the next
  *    mount re-derives from it.
- *    Proof: `packages/editor/test/oid-source-persistence.test.ts`.
  *  - `source-structure` — the edit is not a VALUE at all: it adds, removes,
- *    moves or re-nests an ELEMENT of the game's own source (`delete`,
+ *    moves or re-nests an ELEMENT of the project's own source (`delete`,
  *    `duplicate`, `wrap`/`unwrap`, `create`, `reorder`, `reparent`, `group`).
  *    It is a kind rather than a flavour of `source-prop` because it resolves on
  *    a DIFFERENT DOOR — the dialect's structural writer, not its attribute
@@ -983,13 +886,11 @@ export type NodeCreationSite =
  *    does not have: the write is WHOLE-FILE and checksum-guarded, so an op
  *    resolved against a stale element index must fail rather than land at the
  *    wrong offset.
- *    Proof: `packages/editor/test/structural-write-pipe.test.ts`.
  *  - `construction-literal` — the value is a literal in the CONSTRUCTION
- *    EXPRESSION that built the object (`new THREE.Mesh(…)` in the game's own
+ *    EXPRESSION that built the object (a constructor call in the project's own
  *    served module). Same landing/remount contract, plus one gate the prop lane
  *    does not have: a site that constructed more than one object is refused,
  *    because rewriting its literal would move all of them.
- *    Proof: `packages/editor/test/ingest-source-persistence.test.ts`.
  *  - `physics-binding` — the node's own transform props are DEAD: a simulated
  *    body writes its matrix every frame from a spawn it reads elsewhere, so the
  *    write lands at the literal that binding reads (the component callsite whose
@@ -999,20 +900,14 @@ export type NodeCreationSite =
  *    body must have re-spawned at the AUTHORED pose, not at the old one. Being
  *    silently re-posed by the owner is this kind's whole failure mode, and the
  *    reason it is a kind rather than a flavour of `source-prop`.
- *    Proof: `packages/editor/test/r3f-physics-binding.test.ts`.
- *  - `data-record` — the value is a field of a RECORD in the game's own data
+ *  - `data-record` — the value is a field of a RECORD in the project's own data
  *    file, addressed by index; no source literal mentions it. Lands in that
- *    file through the game's own declared writer; survives a cold remount for
+ *    file through the project's own declared writer; survives a cold remount for
  *    the same reason source does.
- *    Proof: `packages/editor/test/ingest-source-persistence.test.ts`
- *    ("a level-data record is an anchor too").
  *  - `live-only` — there is no anchor. The edit lands on the running object for
  *    the session and NOTHING else, and the contract is that the surface SAYS SO:
  *    a write ack that claims a destination it did not reach is the lie this kind
  *    exists to keep nameable.
- *    Proof: `packages/editor/test/oid-source-persistence.test.ts`
- *    ("an object with no source stamp is refused by name")
- *    + `packages/editor/test/inspection-write-destination.test.ts`.
  */
 export type WriteAnchorKind =
   | 'source-prop'
@@ -1023,29 +918,15 @@ export type WriteAnchorKind =
   | 'live-only';
 
 /**
- * WHAT ONE EDIT DID — the ack the persistence pipe returns for THAT edit, from
- * the component that actually performed the write.
- *
- * It is deliberately NOT a property of an adapter, a session or a surface. The
- * fact it carries is per-edit, because that is the only granularity at which it
- * can be true: one composite may hold a source-backed three root beside a
- * live-only DOM root, and one three root holds body-placed nodes beside
- * ordinary JSX props. An answer computed from the SURFACE rather than from the
- * edit reports whichever child happened to be persist-capable — measured on the
- * vendored racing game, where a three-root edit acked the other root's
- * destination with `persisted: true`.
- *
- * `persisted: false` is an ANSWER, never a failure: `live-only` is a real
- * anchor kind and the contract of that kind is that the surface SAYS SO. What
- * is forbidden is a `destination` no byte reached being reported with
- * `persisted: true`.
+ * The persistence result for one edit, returned by the component that performed
+ * the write. Composite roots and nodes may have different destinations, so an
+ * adapter-wide destination cannot describe an individual edit.
  *
- * A provider that performs a write returns this; one that has no write to
- * perform returns nothing and the shell reports the live-only floor. There is
- * no third answer, and in particular there is no adapter-wide blanket
- * destination standing in for one — {@link PersistenceProvider.destination}
- * answers the different question "where do this surface's SAVES go", for the
- * save-status chrome.
+ * `persisted: false` is a valid live-only result. `persisted: true` requires that
+ * bytes reached the reported destination. A provider with no write result
+ * returns nothing and the shell reports the live-only floor.
+ * {@link PersistenceProvider.destination} describes where saves go for status
+ * chrome; it does not substitute for a per-edit result.
  */
 export interface WriteAck {
   /** Where THIS edit's bytes landed, in the writer's own words — or the
@@ -1103,7 +984,7 @@ export function emptyWriteAnchorKindCounts(): Record<WriteAnchorKind, number> {
  * Present ⇒ every id gets an answer, anchored or reasoned.
  */
 export interface AuthoringTruth {
-  /** Where the runtime object came from in the game's own source or data. */
+  /** Where the runtime object came from in the project's own source or data. */
   readonly site: NodeCreationSite;
   /** The lane THIS property edit would actually take. `undefined` means the
    * subject is synthetic or otherwise has no write plan; `live-only` is a real
@@ -1111,12 +992,8 @@ export interface AuthoringTruth {
   readonly writeAnchorKind: WriteAnchorKind | undefined;
 }
 
-/**
- * The TRUTH-family binding. One resolution answers both where a subject came
- * from and where an edit to one of its properties lands. A caller may not read
- * those facts through separate providers: that was the classifier/writer split
- * the persistence pipe exists to remove.
- */
+/** One truth resolution describes a subject's creation site and the
+ * destination of its property writes. */
 export interface TruthProvider {
   resolve(id: string, property: string): AuthoringTruth;
 }
@@ -1188,7 +1065,7 @@ export interface SpatialDragHandle {
 }
 
 /** One adapter-owned component projection. `category` is a viewport overlay
- * channel (for example `audio`), not a game-object kind; unknown categories
+ * channel (for example `audio`), not a scene-object kind; unknown categories
  * obey the master Helpers toggle instead of being rejected. */
 export interface SpatialHandleLayer {
   readonly id: string;
@@ -1218,7 +1095,7 @@ export interface SpatialHandlesProvider {
 
 export interface AuthoringAdapter {
   readonly capabilities: AuthoringCapabilities;
-  /** Spec 29 §5 — seam-level provenance ("what is truth behind these rows").
+  /** Seam-level provenance ("what is truth behind these rows").
    *  Absent ⇒ the shell shows no provenance badge (degrade silently — never
    *  fabricate a claim the adapter didn't make). */
   readonly provenance?: AuthoringProvenance;
@@ -1226,57 +1103,42 @@ export interface AuthoringAdapter {
   readonly selection?: SelectionProvider;
   readonly transforms?: TransformProvider;
   readonly inspector?: InspectorProvider;
-  /** The selected node is an atomic asset that can open in the Asset Editor. */
-  readonly assetSubject?: AssetSubjectProvider;
   readonly related?: RelatedSubjectsProvider;
   /** Source-derived prefab/component instance overrides and native writes. */
   readonly instances?: ComponentInstancesProvider;
   readonly structure?: StructureProvider;
   readonly persistence?: PersistenceProvider;
-  /** D12 — per-layer viewport picking. Absent ⇒ this adapter is not pickable. */
+  /** per-layer viewport picking. Absent ⇒ this adapter is not pickable. */
   readonly pickable?: PickProvider;
-  /** T0 (spec 27 §2) — per-node screen geometry for a DOM visual editor's overlay/
+  /** per-node screen geometry for a DOM visual editor's overlay/
    *  snap/measure math. Absent ⇒ this adapter produces no rects (no overlay). */
   readonly rects?: RectProvider;
-  /** T0 (spec 27 §2) — spatial drag-resize/move → source/data write for non-Object3D
-   *  (DOM) nodes. Absent ⇒ no box-edit gesture for this adapter. */
+  /** spatial drag-resize/move → source/data write for DOM
+   *  nodes, which have no scene object. Absent ⇒ no box-edit gesture for this adapter. */
   readonly boxEdit?: BoxEditProvider;
-  /** T0 (spec 27 §2) — double-click-to-edit-text on the contract (wires the react
-   *  adapter's existing off-contract `editText`). Absent ⇒ no in-place text edit. */
+  /**
+   * Optional in-place text editing. Absent means this adapter does not
+   * support the overlay’s double-click text edit gesture.
+   */
   readonly text?: TextProvider;
-  /** D3 (spec 27 §6) — eyedropper fallback color sampling. Absent ⇒ the
+  /** eyedropper fallback color sampling. Absent ⇒ the
    *  canvas eyedropper swatch has no non-native path for this adapter. */
   readonly colorSample?: ColorSampleProvider;
-  /** D4 — storybook stories. Absent ⇒ no stories for any node in this adapter. */
+  /** Storybook stories. Absent ⇒ no stories for any node in this adapter. */
   readonly stories?: StoriesProvider;
   /** Projection subject → source/data anchor and write lane, resolved together. */
   readonly truth?: TruthProvider;
   /** Adapter-owned component guides and direct-manipulation points. */
   readonly spatialHandles?: SpatialHandlesProvider;
-  /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
+  /** Component drop (the canvas Add menu). Absent ⇒ this adapter accepts no drops. */
   readonly assetDrop?: AssetDropProvider;
   /** Change notification → UI refresh. */
   subscribe?(listener: () => void): () => void;
 }
 
-/**
- * THE PROVIDER VOCABULARY — every member of {@link AuthoringAdapter} beyond the
- * two an adapter cannot exist without.
- *
- * Why this exists: the editor's coverage warnings are supposed to make stopping
- * short of a native root IMPOSSIBLE, and they cannot do that while the row
- * vocabulary is a hand-written list frozen at what its author happened to know.
- * A list like that goes quiet at "all warnings closed" while whole capabilities
- * — stories, asset drop, related subjects, structure — were never enumerated at
- * all, so nothing ever warned about them. So the vocabulary IS the type: adding
- * a provider to `AuthoringAdapter` and forgetting it here is a COMPILE ERROR
- * (the `Record` below is missing a key), and inventing a key the type does not
- * have is an excess-property error. There is no third way to add a provider.
- *
- * `capabilities` and `hierarchy` are excluded because they are required members
- * — every adapter has them by construction, so "absent" is not a state they can
- * be in and a row about them could never say anything.
- */
+/** Provider vocabulary derived from AuthoringAdapter. The exhaustive Record
+ * requires an entry for each optional provider and rejects unknown keys.
+ * Required capabilities and hierarchy are excluded because every adapter has them. */
 export type AuthoringProviderKey = Exclude<keyof AuthoringAdapter, 'capabilities' | 'hierarchy'>;
 
 /**
@@ -1290,7 +1152,6 @@ const AUTHORING_PROVIDER_PRESENCE: Readonly<Record<AuthoringProviderKey, true>>
   selection: true,
   transforms: true,
   inspector: true,
-  assetSubject: true,
   related: true,
   instances: true,
   structure: true,
@@ -1322,7 +1183,7 @@ export const AUTHORING_PROVIDER_KEYS: readonly AuthoringProviderKey[] = Object.k
 /**
  * Which providers this adapter actually exposes — PRESENCE, measured off the
  * object itself. Nothing here consults `capabilities`, the adapter's class, the
- * route that built it, or the game's id: an adapter this function has never
+ * route that built it, or the project's id: an adapter this function has never
  * heard of gets the same answer as one it has.
  */
 export function measureAuthoringProviders(