@vgai/engine 0.5.4 → 0.5.6

package/dist/adapter/adapter-surface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `AdapterSurface` — the kinds of render surface a world can be (T7.1/T7.3/T6.2).
+ *
+ * Moved here from `runtime/game.ts`
+ * so `adapter/root-adapter.ts`'s kind-tagged `MountedRoot` types can name it
+ * without a value-level import cycle (`runtime/game.ts` type-imports from
+ * `adapter/root-adapter.ts` already). This is a leaf module — it imports
+ * nothing — so anything may import it with zero risk of a cycle.
+ * `runtime/game.ts` re-exports this SAME type (`export type { AdapterSurface }`),
+ * so no existing `import type { AdapterSurface } from '../runtime/game'` call site
+ * needed to change.
+ */
+export type AdapterSurface = 'three' | 'canvas' | 'dom';
+/**
+ * Exhaustiveness guard for `AdapterSurface` dispatch (v4 architecture-review
+ * §7.4-2: a hypothetical 4th kind must fail to COMPILE at every kind-dispatch
+ * site, not silently contribute nothing or silently default to an existing
+ * kind). Lives here — colocated with the kind vocabulary itself, not in a
+ * generic util module — so the three call sites that need it
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * `resolveAllRoots`, `editor/play-mode.ts`'s `installMultiRootAuthoring`)
+ * import it from the same leaf module that defines `AdapterSurface`, keeping the
+ * type and its guard from drifting apart. The `never` parameter is the
+ * compile-time half of the guard (TS refuses to call this with anything the
+ * compiler hasn't already narrowed to zero remaining variants); the thrown
+ * Error is the runtime half, in case a value's static type lied (e.g. data
+ * crossing a JSON boundary).
+ */
+export declare function assertNever(value: never, context?: string): never;
+//# sourceMappingURL=adapter-surface.d.ts.map

package/dist/adapter/adapter-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-surface.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAIjE"}

package/dist/adapter/adapter-surface.js

@@ -0,0 +1,18 @@
+/**
+ * Exhaustiveness guard for `AdapterSurface` dispatch (v4 architecture-review
+ * §7.4-2: a hypothetical 4th kind must fail to COMPILE at every kind-dispatch
+ * site, not silently contribute nothing or silently default to an existing
+ * kind). Lives here — colocated with the kind vocabulary itself, not in a
+ * generic util module — so the three call sites that need it
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * `resolveAllRoots`, `editor/play-mode.ts`'s `installMultiRootAuthoring`)
+ * import it from the same leaf module that defines `AdapterSurface`, keeping the
+ * type and its guard from drifting apart. The `never` parameter is the
+ * compile-time half of the guard (TS refuses to call this with anything the
+ * compiler hasn't already narrowed to zero remaining variants); the thrown
+ * Error is the runtime half, in case a value's static type lied (e.g. data
+ * crossing a JSON boundary).
+ */
+export function assertNever(value, context) {
+    throw new Error(`Unreachable${context ? ` ${context}` : ''}: unexpected value ${JSON.stringify(value)}`);
+}

package/dist/adapter/authoring.d.ts

@@ -0,0 +1,597 @@
+/**
+ * AuthoringAdapter — the editor's authoring contract. The editor talks to THIS,
+ * keyed by opaque string node ids, instead of to a concrete document format.
+ *
+ * `.vscn` / `SceneEntity` is the private model of ONE implementer
+ * (`VgaiSceneAuthoringAdapter`); 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`,
+ * and `locked` 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, and lock
+ * toggle against these three paths, generically, for any adapter that reports
+ * them via `InspectorProvider.properties`.
+ */
+import type * as THREE from 'three';
+import type { Transform } from './transform';
+/**
+ * Booleans the editor UI gates affordances on (hide what an adapter can't do).
+ *
+ * Deliberately SMALL: a capability flag earns its place only when the shell
+ * actually branches on it. Structural affordances (create/delete/reparent) are
+ * gated by `structure` PROVIDER PRESENCE instead — the flag and the provider
+ * cannot disagree that way. (WO-2 deleted `material`/`create`/`delete`/
+ * `reparent`/`layout`, which no shell code ever read.)
+ */
+export interface AuthoringCapabilities {
+    transform: boolean;
+    inspectorFields: boolean;
+    persist: boolean;
+}
+/**
+ * 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
+ * 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
+ * knows its truth: the shell must read this field, never guess from adapter
+ * identity (rule zero). Machine-readable operation gates stay in {@link
+ * AuthoringCapabilities}/provider presence — this type carries the HUMAN
+ * explanation those gates can point at when an affordance is present but
+ * unavailable.
+ */
+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);
+     * - `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
+     *   overlay, never the source;
+     * - `live` — a running game adopted at play time; edits are not persisted;
+     * - `boundary` — a declared world with no live editing surface here.
+     */
+    source: 'document' | 'source-code' | 'foreign' | 'live' | 'boundary';
+    /** Short badge text the shell shows verbatim at the seam (e.g. "scene",
+     *  "jsx", "overlay", "read-only", "live"). */
+    label: string;
+    /** One sentence explaining the truth/writability — shown as the seam
+     *  badge's tooltip and as the reason on disabled affordances. */
+    detail: string;
+}
+/**
+ * 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,
+ * so presentation and interaction never have to infer semantics from an id,
+ * label, or substrate-specific kind string.
+ */
+export type EditorNodeRole = 'folder' | 'root' | 'document' | 'story' | 'component' | 'instance' | 'element' | 'entity' | 'boundary';
+/** A node in the authoring hierarchy — format-neutral (not a `SceneEntity`). */
+export interface EditorNode {
+    /** STABLE id — survives reload (see ingest structural-path ids). */
+    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. */
+    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. */
+    secondaryLabel?: string;
+    kind: 'mesh' | 'light' | 'camera' | 'group' | 'object' | (string & {});
+    /**
+     * What to CALL this node's type in the inspector header — the component or
+     * class an author thinks of it as, when that differs from the native `kind`
+     * the shell uses to pick an icon. An `<Enemy>` renders a `group`, but "group"
+     * is a fact about its implementation, not its identity; Godot names the class
+     * here and Unity names the prefab. Adapters that omit it keep showing `kind`.
+     */
+    typeLabel?: string;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface PropertyDescriptor {
+    path: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'vec3' | 'color' | 'enum' | 'asset' | 'json';
+    readonly?: boolean;
+    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.
+     */
+    group?: string;
+    /**
+     * The value shown is the DECLARED DEFAULT — the document does not carry this
+     * property, the thing that owns it does. Every mainstream inspector
+     * distinguishes these (Unity greys an unmodified field and bolds an
+     * overridden one) because otherwise you cannot tell what a document actually
+     * says from what it merely inherits. Editing a defaulted property writes it
+     * into the document for the first time.
+     */
+    defaulted?: boolean;
+    /**
+     * This property can be REMOVED from the document, reverting it to the
+     * declared default — Unity's revert arrow, Godot's reset arrow. Only set when
+     * removal is legal: the owner declares the property optional (or gives it a
+     * default), so dropping it leaves a still-valid document. The inverse of
+     * editing a `defaulted` property.
+     */
+    resettable?: boolean;
+    /**
+     * The SOURCE TEXT of the default a revert returns this property to (`1.55`,
+     * `'raider'`), so the revert affordance can name its destination instead of
+     * saying "default" and hoping.
+     *
+     * Set ONLY when the owner actually declares a default the adapter can read.
+     * Absence is the honest, common case: an optional property with no declared
+     * default is still removable — what takes over is then the owner's own
+     * internal fallback or nothing at all, which this side does not know. Never
+     * fill it with the property's CURRENT value: that is what the author is
+     * discarding, not what they get back.
+     */
+    revertsTo?: string;
+}
+export interface HierarchyProvider {
+    roots(): EditorNode[];
+    node(id: string): EditorNode | null;
+    /**
+     * OPTIONAL, THREE-SPECIFIC — the live `Object3D` for raycast/gizmo binding
+     * (null for a node this adapter has no object for). A Pixi, DOM or React
+     * adapter has no `Object3D` 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`).
+     */
+    object3D?(id: string): THREE.Object3D | null;
+    /** OPTIONAL, THREE-SPECIFIC — inverse of {@link object3D}. Same rule: an
+     *  adapter with no `Object3D` tree omits it. */
+    idForObject3D?(o: THREE.Object3D): string | null;
+}
+export interface SelectionProvider {
+    get(): string[];
+    set(ids: string[]): 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?(rawId: string, options?: {
+        intent?: 'normal' | 'deep';
+        scopeId?: string | null;
+    }): SelectionResolution | null;
+}
+/** Adapter-owned result of semantic selection resolution: the raw native/render
+ * hit mapped to the node the author actually means. (The former
+ * `inspectorId`/`transformId`/`boundaryId` aliases were never read by the
+ * shell — deleted in WO-2.) */
+export interface SelectionResolution {
+    /** Hierarchy selection and Inspector subject. */
+    id: string;
+}
+export type TransformChannel = 'position' | 'rotation' | 'scale';
+export interface TransformEditability {
+    writable: boolean;
+    /** Human-facing explanation for a disabled gizmo/field. */
+    reason?: string;
+}
+export interface TransformProvider {
+    /** Honest inspector presentation for the substrate's transform vocabulary. */
+    dimensions?(id: string): '2d' | '3d' | null;
+    get(id: string): Transform;
+    /** Pre-gesture persistence check. Omitted means the adapter's transform
+     * capability applies uniformly. A false result must suppress manipulation
+     * before the live object is moved, never discover refusal at drag end. */
+    editability?(id: string, channel: TransformChannel): TransformEditability;
+    /** Pause whatever controller fights the gizmo (physics/script) for editing. */
+    beginEdit(id: string): void;
+    apply(id: string, t: Transform): void;
+    endEdit(id: string): void;
+}
+/**
+ * One transform gesture event (see {@link AuthoringAdapter.observeTransforms}).
+ * `live` is a mid-gesture preview pose (the gizmo's live drag path); `commit`
+ * closes the gesture.
+ */
+export interface TransformObservation {
+    readonly id: string;
+    readonly transform: Transform;
+    readonly phase: 'live' | 'commit';
+}
+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;
+    /**
+     * Optional — REMOVE a property's authored override entirely (not "set to a
+     * value"), letting whatever governs it in its absence take over. The one
+     * concrete need today: a longhand CSS override (`style.borderTopLeftRadius`)
+     * that a uniform edit of its shorthand (`style.borderRadius`) must clear so
+     * the shorthand actually wins, instead of leaving a stale longhand that
+     * silently overrides it on reload (spec 27 §5 C2, U2). Adapters with no
+     * removable-override concept simply omit it — callers optional-chain.
+     */
+    remove?(id: string, path: string): void;
+}
+/**
+ * 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;
+    }>;
+}
+export interface StructureProvider {
+    create(kind: string, parentId?: string): string;
+    /**
+     * Remove `id`. May optionally return an awaitable (`Promise<void>`) when the
+     * underlying write is asynchronous (e.g. a react-world source-file edit) —
+     * `deleteSelection` (`editor-hotkeys.ts`) awaits it per id so a same-file
+     * 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.
+     */
+    remove(id: string): void | Promise<void>;
+    duplicate(id: string): string;
+    reparent(id: string, newParentId: string | null): void;
+    /** Reorder `id` to sit immediately before `beforeSiblingId` among its siblings
+     *  (`null` = move to the end). Absent ⇒ the shell has no sibling-reorder UI
+     *  for this adapter. */
+    reorder?(id: string, beforeSiblingId: string | null): void;
+    /**
+     * The kinds `create` accepts for a given parent (`null` parentId = a new
+     * root), each with a display label — drives the shell's creation palette.
+     * Absent ⇒ the palette shows nothing for this adapter, even though `create`
+     * itself may still work when called directly (e.g. programmatically, or by
+     * an adapter-specific affordance outside the generic palette).
+     */
+    creatableKinds?(parentId: string | null): {
+        kind: string;
+        label: string;
+    }[];
+    /** D3 (spec 27 §6) — 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): void;
+    /** D3 (spec 27 §6) — 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): void;
+    /** Group sibling authoring objects beneath one new spatial parent. The
+     * adapter owns transform preservation, persistence, and undo semantics.
+     * Returns the new group id, or null when the selection cannot be grouped. */
+    group?(ids: readonly string[]): string | null;
+    /** Dissolve a plain spatial group and return the ids of its promoted
+     * children. Absent means this adapter has no lossless ungroup operation. */
+    ungroup?(id: string): string[];
+    /** 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
+     * 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
+     * hasn't implemented batching. May optionally return an awaitable
+     * (`Promise<void>`), same widening `remove` documents above and for the
+     * same reason (delete-order-residual fix): `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.
+     */
+    removeMany?(ids: readonly string[]): void | Promise<void>;
+}
+/**
+ * PersistenceProvider — whether and where an adapter's edits persist (design).
+ * The ACTIVE adapter's provider is the ONE place this is decided — the host
+ * (editor) never hard-codes a destination or guards on session flags; it asks the
+ * provider.
+ */
+export interface PersistenceProvider {
+    isDirty(): boolean;
+    /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
+    save(): Promise<void>;
+    /**
+     * Human/agent-readable destination this provider persists to — e.g.
+     * `"scenes/main.vscn.json"`, `"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
+     * the session (e.g. the first-party provider tracks the loaded `.vscn` path)
+     * 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 `.vscn` or the overlay). Absent ⇒ the host must remount to
+     * pick up external changes (the honest floor). Implemented (T3.2 slice 3) by
+     * the first-party provider (`applyExternalUpdate`) and the ingest overlay
+     * provider (`applyOverlay`); absent (correctly) on the ephemeral provider.
+     *
+     * `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.
+     */
+    applyExternal?(content: unknown, rawContent?: string): void;
+}
+/** D8 — mutually-exclusive root groups (radio roots): e.g. a "Scenes" group whose
+ *  members are the game's scene roots, only one of which is loaded/active at a
+ *  time (unlike ordinary sibling roots, which all coexist). */
+export interface RootGroup {
+    id: string;
+    label: string;
+    memberRootIds: string[];
+    activeRootId: string | null;
+}
+export interface RootGroupsProvider {
+    groups(): RootGroup[];
+    activate(groupId: string, rootId: string): Promise<void> | void;
+}
+/** D8 — data-file → root mapping ("opening a file" = activating its root). */
+export interface FileMapProvider {
+    /** project-relative path → node id this adapter maps it to, else null. */
+    rootForFile(path: string): string | null;
+}
+/** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
+export interface PickProvider {
+    pick(clientX: number, clientY: number): string | null;
+}
+/** D4 — storybook stories. */
+export interface StoryRef {
+    id: string;
+    label: string;
+}
+export interface StoriesProvider {
+    storiesFor(nodeId: string): StoryRef[];
+    active(nodeId: string): string | null;
+    apply(nodeId: string, storyId: string | null): void;
+    /** Render ONLY this node against the story (storybook canvas); null exits. */
+    isolate?(nodeId: string | null, storyId?: string): void;
+}
+/**
+ * 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.
+ */
+export interface AssetDropContext {
+    readonly position?: readonly [number, number, number];
+}
+/** Asset drop (hierarchy + viewport). */
+export interface AssetDropProvider {
+    accepts(nodeId: string, assetPath: string): boolean;
+    drop(nodeId: string, assetPath: string, context?: AssetDropContext): void | Promise<void>;
+}
+/** Plain-object rect shape shared by {@link RectProvider} — the same fields a real
+ *  `DOMRect` carries (a subset, so a real `DOMRect` satisfies this structurally too).
+ *  See {@link RectProvider} for the coordinate space (host-relative, not viewport). */
+export interface DOMRectLike {
+    x: number;
+    y: number;
+    width: number;
+    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.) */
+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;
+    /** rects of layout-relevant neighbours, for snap/measure/box-model overlays */
+    contextRects?(id: string): {
+        parent?: DOMRectLike;
+        siblings?: DOMRectLike[];
+        paddingBox?: DOMRectLike;
+    };
+    /**
+     * D3 (spec 27 §6) — 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
+     * overlay's dashed empty-container hint. Host-relative, same coordinate
+     * space as {@link rect}. Absent ⇒ this adapter has no "empty container"
+     * concept (e.g. an adapter with no structural containers at all) — no
+     * hints are drawn for it.
+     */
+    emptyContainers?(): {
+        id: string;
+        rect: DOMRectLike;
+        displayName: string;
+    }[];
+}
+/** One adapter-owned reference point rendered by the shared world overlay.
+ * Coordinates are host-relative px, the same frame as {@link RectProvider}.
+ * A provider deliberately exposes at most one point for a node so coincident
+ * native concepts (for example an anchor and pivot) never become ambiguous. */
+export interface BoxEditReferencePoint {
+    /** True when the native source constrains this point (for example a
+     * normalized 0..1 Sprite anchor). The overlay then uses only exact native
+     * snap points, never an unreachable axis-aligned bounding-box target. */
+    bounded?: boolean;
+    id: string;
+    kind: 'anchor' | 'pivot';
+    label: string;
+    /** Exact host-space points the native reference can reach and should snap
+     * to. Useful for transformed corner/edge/center grids on rotated content. */
+    snapPoints?: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    x: number;
+    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. */
+export interface BoxEditProvider {
+    begin(id: string): void;
+    /** patch: any of x,y,width,height,marginTop… paddingLeft… — px deltas or absolutes.
+     * `referenceX`/`referenceY` are the absolute host-relative coordinates of
+     * the active {@link referencePoint}; only providers exposing that optional
+     * capability receive those keys. The provider owns conversion to native
+     * source units and any placement-preserving compensation. */
+    apply(id: string, patch: Record<string, number>): void;
+    end(id: string): void;
+    /** Optional single native anchor/pivot affordance for this node. */
+    referencePoint?(id: string): BoxEditReferencePoint | null;
+}
+/** Text-content editing — currently OFF-contract (the react adapter has an `editText(id)`
+ *  method, react-world-authoring-adapter.ts:728, not reachable via the contract). Bring it
+ *  on so the overlay's double-click-to-edit-text (D3) is contract-driven. */
+export interface TextProvider {
+    /** the element's editable pure-text, or null if the body is dynamic/has child elements */
+    get(id: string): string | null;
+    set(id: string, text: string): void;
+}
+/**
+ * D3 (spec 27 §6) — 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,
+ * not a color) and from `InspectorProvider.get('style.backgroundColor')`
+ * (which NORMALIZES to `#rrggbb` and so loses the "transparent" signal a
+ * color CHAIN walk needs — see `ui-source/inspect.ts:effectiveColorFromChain`'s
+ * doc comment: it walks raw, un-normalized CSS values looking for the first
+ * non-transparent one).
+ */
+export interface ColorSampleProvider {
+    /** Raw (un-normalized) CSS `background-color` values, hit-element FIRST,
+     *  walking up its ancestor chain — the exact shape
+     *  `effectiveColorFromChain` consumes. `null` when nothing is hit at the
+     *  point. Client (viewport) px, matching {@link PickProvider}. */
+    backgroundChainAt(clientX: number, clientY: number): string[] | null;
+}
+/**
+ * WO-IDX1 — where a node's live object was CREATED in the game's own source.
+ *
+ * `display` is the `file:line` 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).
+ */
+export type NodeCreationSite = {
+    anchored: true;
+    file: string;
+    line: number;
+    col: number;
+    display: string;
+} | {
+    anchored: false;
+    reason: string;
+};
+/**
+ * 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).
+ * Present ⇒ every id gets an answer, anchored or reasoned.
+ */
+export interface CreationSiteProvider {
+    anchor(id: string): NodeCreationSite;
+}
+export interface AuthoringAdapter {
+    readonly capabilities: AuthoringCapabilities;
+    /** Spec 29 §5 — 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;
+    readonly hierarchy: HierarchyProvider;
+    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 structure?: StructureProvider;
+    readonly persistence?: PersistenceProvider;
+    /** D8 — mutually-exclusive root groups (radio roots). Absent ⇒ no grouped roots. */
+    readonly rootGroups?: RootGroupsProvider;
+    /** D8 — data-file → root mapping. Absent ⇒ this adapter maps no files to roots. */
+    readonly files?: FileMapProvider;
+    /** D12 — 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/
+     *  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. */
+    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. */
+    readonly text?: TextProvider;
+    /** D3 (spec 27 §6) — 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. */
+    readonly stories?: StoriesProvider;
+    /** WO-IDX1 — the source location that constructed a node's live object.
+     *  Absent ⇒ this adapter indexes no creation sites. */
+    readonly creationSite?: CreationSiteProvider;
+    /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
+    readonly assetDrop?: AssetDropProvider;
+    /** Change notification → UI refresh. */
+    subscribe?(listener: () => void): () => void;
+    /**
+     * Observe transform GESTURES on this adapter's nodes — the one seam the
+     * animation sequencer needs to record a drag as keyframes and to refresh its
+     * design baselines. Deliberately narrow (one event shape, one consumer, no
+     * general event bus): before it existed, the sequencer could only observe
+     * the first-party store's own `.vscn` transform path, so a live or
+     * source-backed world's gestures were invisible to it. Absent ⇒ this
+     * adapter reports no gestures.
+     */
+    observeTransforms?(listener: (event: TransformObservation) => void): () => void;
+}
+//# sourceMappingURL=authoring.d.ts.map