@vgai/engine 0.5.12 → 0.5.14

package/src/adapter/authoring.ts

@@ -182,7 +182,10 @@ export interface HierarchyProvider {
 
 export interface SelectionProvider {
   get(): string[];
-  set(ids: string[]): void;
+  /** Set the selected authoring subjects. `exact` is for projections that
+   * 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. */
@@ -220,7 +223,14 @@ export interface TransformProvider {
   /** Pause whatever controller fights the gizmo (physics/script) for editing. */
   beginEdit(id: string): void;
   apply(id: string, t: Transform): void;
-  endEdit(id: string): void;
+  /**
+   * Close the gesture — and, for an adapter that persists, ANSWER FOR IT: the
+   * returned {@link WriteAck} is this edit's own outcome, produced after the
+   * write it triggered has settled. Returning nothing is the honest report of
+   * an adapter that performed no write, and the shell then reports the
+   * live-only floor rather than borrowing an answer from somewhere else.
+   */
+  endEdit(id: string): void | WriteAck | Promise<void | WriteAck>;
 }
 
 /**
@@ -238,7 +248,18 @@ export interface InspectorProvider {
   /** Schema-driven — NOT fixed to `SceneEntity`. */
   properties(id: string): PropertyDescriptor[];
   get(id: string, path: string): unknown;
-  set(id: string, path: string, value: unknown): void | Promise<void>;
+  /**
+   * Write one property — and, for an adapter that persists, ANSWER FOR IT: the
+   * returned {@link WriteAck} is this edit's own outcome (same contract as
+   * {@link TransformProvider.endEdit}). Returning nothing means no write was
+   * performed by this provider, and the shell reports the live-only floor.
+   */
+  set(id: string, path: string, value: unknown): void | WriteAck | Promise<void | WriteAck>;
+  /** Optional per-subject write preflight for shell affordances outside the
+   * Inspector field grid (notably hierarchy eye/lock controls). The property
+   * descriptor remains the Inspector's source of `readonly`; this gives other
+   * generic surfaces the same answer and its adapter-authored reason. */
+  editability?(id: string, path: string): { writable: boolean; reason?: string };
   /**
    * Optional — REMOVE a property's authored override entirely (not "set to a
    * value"), letting whatever governs it in its absence take over. The one
@@ -294,6 +315,47 @@ export interface RelatedSubjectsProvider {
   links(id: string): readonly RelatedSubjectLink[];
 }
 
+/** One source-owned prop that differs from its component's declared default. */
+export interface ComponentInstanceOverride {
+  /** The owning Inspector field path; stable and agent-addressable. */
+  readonly path: string;
+  readonly label: string;
+  readonly value: unknown;
+  /** Source text of the component default, when the declaration exposes one. */
+  readonly defaultText?: string;
+  /** Applying requires a literal callsite value and a literal declared default. */
+  readonly canApplyToComponent: boolean;
+  readonly applyUnavailableReason?: string;
+  /** Placed instances that will inherit this default after the apply. */
+  readonly affectedInstanceCount: number;
+}
+
+/** Derived prefab-instance facts. Nothing in this shape is persisted separately. */
+export interface ComponentInstanceDescription {
+  readonly componentName: string;
+  readonly sourcePath?: string;
+  readonly overrides: readonly ComponentInstanceOverride[];
+}
+
+export interface ComponentInstanceApplyResult {
+  readonly changed: boolean;
+  readonly message: string;
+}
+
+/**
+ * Source-derived component-instance operations. A provider exists only when an
+ * adapter can prove component identity and write the component's native source.
+ * No override store is implied: describe is a diff, revert removes callsite
+ * props, and apply edits the component declaration itself.
+ */
+export interface ComponentInstancesProvider {
+  describe(id: string): ComponentInstanceDescription | null;
+  /** Open the native component/prefab board for this instance's surface. */
+  openComponent?(id: string): void;
+  revert(id: string, paths: readonly string[]): Promise<void>;
+  applyToComponent(id: string, path: string): Promise<ComponentInstanceApplyResult>;
+}
+
 export interface StructureProvider {
   create(kind: string, parentId?: string): string;
   /**
@@ -357,6 +419,23 @@ export interface StructureProvider {
    * is a harmless no-op.
    */
   removeMany?(ids: readonly string[]): void | Promise<void>;
+  /** Copy authored entities through the host clipboard. The adapter owns the
+   * native payload (JSX for a source-backed Three/Canvas world, native records
+   * for a data-backed adapter); the shell never serializes an engine-private
+   * shape. */
+  copy?(ids: readonly string[]): boolean | Promise<boolean>;
+  /** Honest affordance preflight. Omit when copy is never offered. */
+  canCopy?(ids: readonly string[]): boolean;
+  /** Copy, then remove the same authored entities only after the clipboard
+   * write succeeds. One adapter operation owns that ordering. */
+  cut?(ids: readonly string[]): boolean | Promise<boolean>;
+  /** Paste as children of `parentId`; `null` means the adapter document root.
+   * The shell derives the current selection's parent so ordinary Paste creates
+   * siblings, matching scene-hierarchy editors. */
+  paste?(parentId: string | null): boolean | Promise<boolean>;
+  /** Honest affordance preflight. It need only cover adapter/session state;
+   * the actual paste still validates the live system clipboard. */
+  canPaste?(parentId: string | null): boolean;
 }
 
 /**
@@ -367,6 +446,10 @@ export interface StructureProvider {
  */
 export interface PersistenceProvider {
   isDirty(): boolean;
+  /** The last persistence failure that still requires attention. Successful
+   * subsequent persistence clears it. Auto-saving source adapters use this to
+   * report a rolled-back source write without inventing a dirty document. */
+  lastError?(): string | null;
   /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
   save(): Promise<void>;
   /**
@@ -400,6 +483,13 @@ export interface PersistenceProvider {
 /** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
 export interface PickProvider {
   pick(clientX: number, clientY: number): string | null;
+  /**
+   * Every authorable subject below the point, frontmost first. The shell uses
+   * this for the ordinary scene-editor "pick from overlap" menu; adapters
+   * that cannot enumerate an overlap may omit it and still provide the
+   * single-hit floor through {@link pick}.
+   */
+  candidates?(clientX: number, clientY: number): readonly string[];
 }
 
 /** D4 — storybook stories. */
@@ -413,6 +503,14 @@ export interface StoriesProvider {
   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;
 }
 
 /**
@@ -424,11 +522,22 @@ export interface StoriesProvider {
  */
 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';
+      };
 }
 
 /** Asset drop (hierarchy + viewport). */
 export interface AssetDropProvider {
-  accepts(nodeId: string, assetPath: string): boolean;
+  accepts(nodeId: string, assetPath: string, context?: AssetDropContext): boolean;
   drop(nodeId: string, assetPath: string, context?: AssetDropContext): void | Promise<void>;
 }
 
@@ -488,8 +597,9 @@ export interface BoxEditReferencePoint {
   y: number;
 }
 
-/** Spatial gesture → source/data write, for non-Object3D (DOM) nodes. Distinct from the
- *  3D TransformProvider. begin/apply/end bracket a single undo step; apply is live-preview. */
+/** Spatial gesture → source/data write for native 2D boxes (DOM or canvas).
+ * Distinct from the 3D TransformProvider. begin/apply/end bracket a single
+ * undo step; apply is live-preview. */
 export interface BoxEditProvider {
   begin(id: string): void;
   /** patch: any of x,y,width,height,marginTop… paddingLeft… — px deltas or absolutes.
@@ -499,6 +609,11 @@ export interface BoxEditProvider {
    * source units and any placement-preserving compensation. */
   apply(id: string, patch: Record<string, number>): void;
   end(id: string): void;
+  /** Native transform origin for the viewport gizmo, in the same host-space
+   * frame as {@link RectProvider}. A 2D scene uses this instead of guessing
+   * from the visual bounds: sprites can have anchors, containers can have
+   * pivots, and neither necessarily sits at the box center. */
+  gizmoOrigin?(id: string): { x: number; y: number } | null;
   /** Optional single native anchor/pivot affordance for this node. */
   referencePoint?(id: string): BoxEditReferencePoint | null;
 }
@@ -547,10 +662,10 @@ export interface ColorSampleProvider {
  *  - `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
  *    written.
- *  - `data` is the sibling a level-based game needs. Descent's placed cargo —
- *    the robots, the powerups, the hostages — reaches no source literal at all;
- *    it is binary records inside `descent.hog` that the game parses at load. An
- *    authored move of a robot is therefore an edit to THE GAME'S OWN DATA, and
+ *  - `data` is the sibling a level-based game 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
  *    the honest anchor is the data file plus the index of the record that
  *    addresses the object inside it.
  *
@@ -576,6 +691,134 @@ export type NodeCreationSite =
     }
   | { anchored: false; reason: string };
 
+/**
+ * WHERE AN AUTHORED WRITE LANDS — the vocabulary of anchor KINDS, and the
+ * closed set of them.
+ *
+ * {@link NodeCreationSite} answers "where did this object come from"; a kind
+ * answers the write-side question beside it: WHICH LANE would carry an edit to
+ * this node, and therefore WHAT has to be true for that edit to be correct. The
+ * 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:
+ *
+ *  - `source-prop` — the value is a literal PROP on an element of the game'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`.
+ *  - `construction-literal` — the value is a literal in the CONSTRUCTION
+ *    EXPRESSION that built the object (`new THREE.Mesh(…)` in the game'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
+ *    props the `useBox(…)`/`<RigidBody>` hook takes). It carries the two
+ *    contracts above AND ONE MORE: the authored value must SURVIVE RE-SETTLE —
+ *    after the world re-derives from source and the design-time settle runs, the
+ *    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
+ *    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
+ *    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'
+  | 'construction-literal'
+  | 'physics-binding'
+  | 'data-record'
+  | '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`.
+ *
+ * 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.
+ */
+export interface WriteAck {
+  /** Where THIS edit's bytes landed, in the writer's own words — or the
+   *  live-only/ephemeral floor when none did. */
+  readonly destination: string;
+  /** Whether a byte actually moved for THIS edit. */
+  readonly persisted: boolean;
+}
+
+/**
+ * The exhaustiveness pin, the same shape and for the same reason as
+ * {@link AUTHORING_PROVIDER_PRESENCE}: a `Record` over the union, so a lane that
+ * starts producing a new kind of anchor cannot ship without joining the
+ * vocabulary (the `Record` would be missing a key) and cannot invent a key the
+ * union does not have (excess-property error). The values are `true` and carry
+ * no meaning — the KEYS are the payload.
+ *
+ * What this buys downstream: the per-kind write-reach counts and `vgai doctor`'s
+ * edit-write walk both enumerate {@link WRITE_ANCHOR_KINDS} rather than a
+ * hand-written list, so a new kind arrives already measured and already walked
+ * instead of silently untested.
+ */
+const WRITE_ANCHOR_KIND_PRESENCE: Readonly<Record<WriteAnchorKind, true>> = {
+  'source-prop': true,
+  'construction-literal': true,
+  'physics-binding': true,
+  'data-record': true,
+  'live-only': true,
+};
+
+/**
+ * The vocabulary as an ordered list — most-addressable first, `live-only` last,
+ * so two reports of the same world are diffable line for line.
+ *
+ * Derived from {@link WRITE_ANCHOR_KIND_PRESENCE} rather than spelled a second
+ * time: one list the compiler pins to the union, and nothing downstream can
+ * enumerate a different set.
+ */
+export const WRITE_ANCHOR_KINDS: readonly WriteAnchorKind[] = Object.keys(
+  WRITE_ANCHOR_KIND_PRESENCE,
+) as WriteAnchorKind[];
+
+/** Zero counts for every kind — the starting point of any per-kind tally, so a
+ *  tally can never omit a kind by forgetting to initialize it. */
+export function emptyWriteAnchorKindCounts(): Record<WriteAnchorKind, number> {
+  const counts = {} as Record<WriteAnchorKind, number>;
+  for (const kind of WRITE_ANCHOR_KINDS) counts[kind] = 0;
+  return counts;
+}
+
 /**
  * Absent ⇒ this adapter's substrate has no creation-site index at all (a
  * document-backed world's truth is the document, not a construction site).
@@ -583,6 +826,112 @@ export type NodeCreationSite =
  */
 export interface CreationSiteProvider {
   anchor(id: string): NodeCreationSite;
+  /**
+   * The write-side sibling of {@link anchor}: which LANE would carry an edit to
+   * this node's transform, in the closed vocabulary above. Exposed beside the
+   * anchor because that is where every reader already looks, and because a
+   * caller sweeping a hierarchy needs it to find a representative node per kind
+   * (`vgai doctor`'s edit-write walk is that caller).
+   *
+   * Absent ⇒ this adapter plans no lanes it can distinguish; the reader has only
+   * the anchor's own shape, which cannot tell two source lanes apart.
+   * `undefined` for a particular id ⇒ this adapter plans no write for THAT id
+   * (a synthetic hierarchy row, an id no child of a composite owns) — which is
+   * not the same as `live-only`, a lane that really does land on a live object.
+   */
+  writeAnchorKind?(id: string): WriteAnchorKind | undefined;
+}
+
+/** A plain world-space point. Component handles cross the authoring seam as
+ * data; a substrate object or renderer handle never does. */
+export type SpatialPoint3 = readonly [x: number, y: number, z: number];
+
+/** Non-interactive geometry an adapter asks the viewport to draw for one
+ * spatial component. The vocabulary is intentionally geometric rather than
+ * domain-shaped: audio attenuation, light range and a collider radius can all
+ * use the same sphere without teaching the shell any of those concepts. */
+export type SpatialHandleGuide =
+  | {
+      readonly kind: 'line';
+      readonly points: readonly SpatialPoint3[];
+      readonly color: string;
+      readonly opacity?: number;
+      readonly dashed?: boolean;
+    }
+  | {
+      readonly kind: 'sphere';
+      readonly center: SpatialPoint3;
+      readonly radius: number;
+      readonly color: string;
+      readonly opacity?: number;
+      readonly dashed?: boolean;
+    }
+  | {
+      readonly kind: 'cone';
+      readonly origin: SpatialPoint3;
+      readonly direction: SpatialPoint3;
+      readonly length: number;
+      /** Full opening angle in degrees, matching Web Audio and authoring UIs. */
+      readonly angle: number;
+      readonly color: string;
+      readonly opacity?: number;
+      readonly dashed?: boolean;
+    }
+  | {
+      readonly kind: 'box';
+      readonly center: SpatialPoint3;
+      readonly rotation: readonly [x: number, y: number, z: number, w: number];
+      readonly halfExtents: SpatialPoint3;
+      readonly color: string;
+      readonly opacity?: number;
+      readonly dashed?: boolean;
+    }
+  | {
+      readonly kind: 'capsule';
+      readonly center: SpatialPoint3;
+      readonly rotation: readonly [x: number, y: number, z: number, w: number];
+      readonly radius: number;
+      readonly halfHeight: number;
+      readonly color: string;
+      readonly opacity?: number;
+      readonly dashed?: boolean;
+    };
+
+/** One draggable point. `id` is stable only within its owning node; `label`
+ * feeds accessible/editor hints rather than becoming a persisted name. */
+export interface SpatialDragHandle {
+  readonly id: string;
+  readonly label: string;
+  readonly position: SpatialPoint3;
+  readonly color: string;
+  readonly writable: boolean;
+  readonly reason?: string;
+}
+
+/** One adapter-owned component projection. `category` is a viewport overlay
+ * channel (for example `audio`), not a game-object kind; unknown categories
+ * obey the master Helpers toggle instead of being rejected. */
+export interface SpatialHandleLayer {
+  readonly id: string;
+  readonly category: string;
+  readonly guides: readonly SpatialHandleGuide[];
+  readonly handles: readonly SpatialDragHandle[];
+}
+
+/**
+ * Format-neutral direct-manipulation seam for component-owned spatial values.
+ *
+ * The viewport draws only the returned geometry. During a drag it returns a
+ * world-space point to the adapter; the adapter alone knows whether that means
+ * an AudioSource distance, a light cone, a collider extent, or something else,
+ * and the adapter alone owns live preview + source persistence. `commit` runs
+ * once at gesture end, so source/HMR/history are never hammered per pointer
+ * move. Absent means this adapter has no spatial component handles.
+ */
+export interface SpatialHandlesProvider {
+  layers(id: string): readonly SpatialHandleLayer[];
+  preview(id: string, handleId: string, worldPosition: SpatialPoint3): void;
+  commit(id: string, handleId: string, worldPosition: SpatialPoint3): void | Promise<void>;
 }
 
 export interface AuthoringAdapter {
@@ -598,6 +947,8 @@ export interface AuthoringAdapter {
   /** 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. */
@@ -619,6 +970,8 @@ export interface AuthoringAdapter {
   /** WO-IDX1 — the source location that constructed a node's live object.
    *  Absent ⇒ this adapter indexes no creation sites. */
   readonly creationSite?: CreationSiteProvider;
+  /** Adapter-owned component guides and direct-manipulation points. */
+  readonly spatialHandles?: SpatialHandlesProvider;
   /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
   readonly assetDrop?: AssetDropProvider;
   /** Change notification → UI refresh. */
@@ -634,3 +987,80 @@ export interface AuthoringAdapter {
    */
   observeTransforms?(listener: (event: TransformObservation) => 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.
+ */
+export type AuthoringProviderKey = Exclude<keyof AuthoringAdapter, 'capabilities' | 'hierarchy'>;
+
+/**
+ * The exhaustiveness pin. A `Record` over the key union, so the compiler — not
+ * a scan, not a reviewer — is what refuses a vocabulary that has drifted from
+ * the interface above. The values are `true` and carry no meaning: the KEYS are
+ * the payload.
+ */
+const AUTHORING_PROVIDER_PRESENCE: Readonly<Record<AuthoringProviderKey, true>> = {
+  provenance: true,
+  selection: true,
+  transforms: true,
+  inspector: true,
+  assetSubject: true,
+  related: true,
+  instances: true,
+  structure: true,
+  persistence: true,
+  pickable: true,
+  rects: true,
+  boxEdit: true,
+  text: true,
+  colorSample: true,
+  stories: true,
+  creationSite: true,
+  spatialHandles: true,
+  assetDrop: true,
+  subscribe: true,
+  observeTransforms: true,
+};
+
+/**
+ * The vocabulary as an ordered list — declaration order of the interface, so
+ * two reports of the same root are diffable line for line.
+ *
+ * Derived from {@link AUTHORING_PROVIDER_PRESENCE} rather than spelled a second
+ * time: one list that the compiler pins to the type, and nothing downstream can
+ * enumerate a different set.
+ */
+export const AUTHORING_PROVIDER_KEYS: readonly AuthoringProviderKey[] = Object.keys(
+  AUTHORING_PROVIDER_PRESENCE,
+) as AuthoringProviderKey[];
+
+/**
+ * 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
+ * heard of gets the same answer as one it has.
+ */
+export function measureAuthoringProviders(
+  adapter: AuthoringAdapter,
+): Readonly<Record<AuthoringProviderKey, boolean>> {
+  const measured = {} as Record<AuthoringProviderKey, boolean>;
+  for (const key of AUTHORING_PROVIDER_KEYS) {
+    measured[key] = (adapter as unknown as Record<string, unknown>)[key] !== undefined;
+  }
+  return measured;
+}

package/src/adapter/constraint.ts

@@ -15,7 +15,7 @@ export type ConstraintStatus = 'ready' | 'disabled' | 'unresolved' | 'error';
 export interface ConstraintConfig {
   /** Stable only within this mounted owner. */
   readonly id: string;
-  readonly type: 'two-bone-ik' | 'ccd-ik' | (string & {});
+  readonly type: 'two-bone-ik' | 'ccd-ik' | 'aim' | 'rotation' | (string & {});
   readonly label: string;
   readonly enabled: boolean;
   readonly weight: number;
@@ -23,15 +23,22 @@ export interface ConstraintConfig {
   readonly order: number;
 }
 
+export interface ConstraintError {
+  readonly value: number;
+  readonly unit: 'metres' | 'degrees';
+}
+
 export interface ConstraintSnapshot {
   readonly status: ConstraintStatus;
   readonly message?: string;
   /** Root → effector, using the real bones from the live skeleton. */
   readonly chain: readonly THREE.Object3D[];
+  /** The ordinary object whose transform the constraint affects. */
+  readonly constrained: THREE.Object3D | null;
   readonly target: THREE.Object3D | null;
   readonly pole: THREE.Object3D | null;
-  /** Effector-to-target distance after the latest solve, in world units. */
-  readonly error: number | null;
+  /** Residual after the latest solve, in the constraint's native unit. */
+  readonly error: ConstraintError | null;
 }
 
 export interface ConstraintMark {

package/src/adapter/finders/finder-result.ts

@@ -0,0 +1,29 @@
+/**
+ * What every finder answers with.
+ *
+ * A finder is a PURE function over project source/files with explicit inputs
+ * and outputs — it never reads a filesystem, never fetches, and never consults
+ * ambient state. What it cannot answer it says so in {@link FinderResult.notes}
+ * rather than degrading silently: "has none" and "nobody could look" are
+ * different facts, and only the second is a defect.
+ */
+
+import type { SceneEntry } from '../adapter-module';
+
+export interface FinderResult {
+  /** Scene-table entries this finder produced, in discovery order. */
+  readonly entries: readonly SceneEntry[];
+  /**
+   * The entry this finder's own answer makes the default, when its answer
+   * settles it UNAMBIGUOUSLY (one candidate). A finder never picks between
+   * candidates — that is the adapter author's declaration to make, and an
+   * absent default stays the honest fact that none was declared.
+   */
+  readonly default?: string;
+  /**
+   * Loud, non-fatal diagnostics: a selection identifier that is not in the
+   * source, an entrypoint whose bytes could not be read. Every note names the
+   * file it is about. The host surfaces these; it never swallows them.
+   */
+  readonly notes: readonly string[];
+}