@vgai/engine 0.5.14 → 0.5.16

package/dist/adapter/native-debug-module.js

@@ -0,0 +1,230 @@
+/**
+ * The ordinary module surface a native game may expose to its own debugger.
+ *
+ * A root entry re-exports one `debug` object from the project's command module:
+ *
+ *   export { debug } from './commands';
+ *
+ * The command module imports no vgai API. Its functions are the application's
+ * own functions over its own stores; the native adapter merely projects that
+ * existing registry onto the session debug/input doors after the root mounts.
+ * Loading through the root entry is load-bearing: the functions close over the
+ * exact module graph the mounted application uses, never a separately evaluated
+ * copy of its stores.
+ */
+import { DebugError, getDebugRegistry, } from '../runtime/debug-registry';
+export const NATIVE_INPUT_VALUE_TYPES = [
+    'digital',
+    'scalar',
+    'vector2',
+    'pointerDelta',
+    'pointerPosition',
+];
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, at) {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw new Error(`${at} has unknown ${unknown.length === 1 ? 'key' : 'keys'}: ${unknown.join(', ')}`);
+    }
+}
+function functionRecord(value, at) {
+    if (!isRecord(value))
+        throw new Error(`${at} must be an object of named functions.`);
+    const out = {};
+    for (const [name, candidate] of Object.entries(value)) {
+        if (!name)
+            throw new Error(`${at} contains an empty name.`);
+        if (typeof candidate !== 'function')
+            throw new Error(`${at}.${name} must be a function.`);
+        out[name] = candidate;
+    }
+    return out;
+}
+function parseActions(value) {
+    if (!isRecord(value)) {
+        throw new Error('debug.input.actions must be an object mapping action names to value types.');
+    }
+    const actions = {};
+    for (const [name, valueType] of Object.entries(value)) {
+        if (!name)
+            throw new Error('debug.input.actions contains an empty action name.');
+        if (!NATIVE_INPUT_VALUE_TYPES.includes(valueType)) {
+            throw new Error(`debug.input.actions.${name} must be one of ${NATIVE_INPUT_VALUE_TYPES.join(', ')}.`);
+        }
+        actions[name] = valueType;
+    }
+    return actions;
+}
+function parseInput(value) {
+    if (!isRecord(value))
+        throw new Error('debug.input must be an object.');
+    rejectUnknownKeys(value, ['actions', 'set', 'clear', 'tap', 'scheduleAtTick'], 'debug.input');
+    const set = value['set'];
+    const clear = value['clear'];
+    const tap = value['tap'];
+    const scheduleAtTick = value['scheduleAtTick'];
+    if (typeof set !== 'function')
+        throw new Error('debug.input.set must be a function.');
+    if (typeof clear !== 'function')
+        throw new Error('debug.input.clear must be a function.');
+    if (tap !== undefined && typeof tap !== 'function') {
+        throw new Error('debug.input.tap must be a function when provided.');
+    }
+    if (scheduleAtTick !== undefined && typeof scheduleAtTick !== 'function') {
+        throw new Error('debug.input.scheduleAtTick must be a function when provided.');
+    }
+    return {
+        actions: parseActions(value['actions']),
+        set: set,
+        clear: clear,
+        ...(typeof tap === 'function' ? { tap: tap } : {}),
+        ...(typeof scheduleAtTick === 'function'
+            ? {
+                scheduleAtTick: scheduleAtTick,
+            }
+            : {}),
+    };
+}
+/** Read the single native `debug` export from an already-loaded root module. */
+export function nativeDebugBindingFromEntryModule(rootId, entryModule) {
+    if (!isRecord(entryModule) || entryModule['debug'] === undefined)
+        return null;
+    if (!isRecord(entryModule['debug'])) {
+        throw new Error(`Root "${rootId}" exports \`debug\`, but it is not an object.`);
+    }
+    const raw = entryModule['debug'];
+    rejectUnknownKeys(raw, ['commands', 'state', 'input'], `Root "${rootId}" debug export`);
+    const commands = raw['commands'] === undefined ? undefined : functionRecord(raw['commands'], 'debug.commands');
+    const state = raw['state'] === undefined ? undefined : functionRecord(raw['state'], 'debug.state');
+    const input = raw['input'] === undefined ? undefined : parseInput(raw['input']);
+    if (!commands && !state && !input) {
+        throw new Error(`Root "${rootId}" exports an empty \`debug\` object.`);
+    }
+    return {
+        rootId,
+        debug: {
+            ...(commands ? { commands } : {}),
+            ...(state ? { state } : {}),
+            ...(input ? { input } : {}),
+        },
+    };
+}
+function valueMatches(type, value) {
+    if (type === 'digital')
+        return typeof value === 'boolean';
+    if (type === 'scalar')
+        return typeof value === 'number' && Number.isFinite(value);
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.x === 'number' &&
+        Number.isFinite(value.x) &&
+        typeof value.y === 'number' &&
+        Number.isFinite(value.y));
+}
+function installInput(game, registry, binding, input) {
+    const trace = [];
+    let recording = false;
+    const requireAction = (action, value) => {
+        const type = input.actions[action];
+        if (!type) {
+            throw new DebugError('INPUT_ACTION_NOT_FOUND', `Native input has no action named "${action}".`, {
+                registered: Object.keys(input.actions),
+            });
+        }
+        if (!valueMatches(type, value)) {
+            throw new DebugError('INPUT_ACTION_VALUE_TYPE', `Native input action "${action}" expects ${type}, not ${typeof value}.`, { action, expected: type });
+        }
+        return type;
+    };
+    const apply = (action, value, tick) => {
+        requireAction(action, value);
+        input.set(action, value);
+        if (recording)
+            trace.push({ tick, action, value });
+    };
+    const unsupportedSource = (method) => {
+        throw new DebugError('NATIVE_INPUT_SOURCE_UNSUPPORTED', `${method} addresses an engine test source, but this game exposes an app-owned action store. Drive it by action name instead.`);
+    };
+    const target = {
+        setVirtualAction(action, value) {
+            apply(action, value, registry.getGameTick());
+            return { delivered: true };
+        },
+        tapVirtualAction(action) {
+            if (!input.tap) {
+                throw new DebugError('NATIVE_INPUT_TAP_UNSUPPORTED', `Native input for root "${binding.rootId}" does not export tap(); use setVirtualAction through the app-owned store.`);
+            }
+            requireAction(action, true);
+            input.tap(action);
+            return { delivered: true };
+        },
+        clearVirtualActions() {
+            input.clear();
+        },
+        scheduleActionAtTick(tick, action, value) {
+            const currentTick = registry.getGameTick();
+            if (!Number.isInteger(tick) || tick < currentTick) {
+                throw new DebugError('TICK_ALREADY_PASSED', `Cannot schedule native input for tick ${tick}; current tick is ${currentTick}.`, { tick, currentTick });
+            }
+            requireAction(action, value);
+            if (!input.scheduleAtTick) {
+                throw new DebugError('NATIVE_INPUT_SCHEDULE_UNSUPPORTED', `Native input for root "${binding.rootId}" does not export scheduleAtTick(); the adapter will not create a host scheduler for it.`);
+            }
+            input.scheduleAtTick(tick, action, value);
+        },
+        startInputRecording() {
+            trace.length = 0;
+            recording = true;
+        },
+        stopInputRecording() {
+            recording = false;
+        },
+        isInputRecording() {
+            return recording;
+        },
+        injectAxis() {
+            unsupportedSource('injectAxis');
+        },
+        injectVector2() {
+            unsupportedSource('injectVector2');
+        },
+        injectPointerDelta() {
+            unsupportedSource('injectPointerDelta');
+        },
+        injectPointerPosition() {
+            unsupportedSource('injectPointerPosition');
+        },
+    };
+    registry.setInputActionsSource(binding.rootId, () => Object.entries(input.actions).map(([name, valueType]) => ({ name, valueType })));
+    registry.setInputTraceSource(binding.rootId, () => ({
+        version: 1,
+        seed: null,
+        fixedDt: game.loop.fixedDt,
+        ticks: [...trace],
+    }));
+    registry.setVirtualInputTarget(binding.rootId, target);
+}
+/** Project native registries onto the existing session debugger after mount. */
+export function installNativeDebugBindings(game, bindings) {
+    if (bindings.length === 0)
+        return;
+    const registry = getDebugRegistry(game);
+    if (!registry)
+        throw new Error('Cannot install native debug bindings: mounted Game has no debug registry.');
+    for (const binding of bindings) {
+        if (!game.world(binding.rootId)) {
+            throw new Error(`Native debug binding names unmounted root "${binding.rootId}".`);
+        }
+        const root = registry.forRoot(binding.rootId);
+        for (const [name, read] of Object.entries(binding.debug.state ?? {})) {
+            root.registerStateProvider(name, read, { tier: 'assisted' });
+        }
+        for (const [name, command] of Object.entries(binding.debug.commands ?? {})) {
+            root.registerCommand(name, { locus: 'client' }, command);
+        }
+        if (binding.debug.input)
+            installInput(game, registry, binding, binding.debug.input);
+    }
+}

package/dist/adapter/object3d-authoring-subject.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Transient authoring identity for a native subject represented by an
+ * Object3D proxy.
+ *
+ * Some ecosystem-native objects are not Object3Ds themselves: Rapier bodies
+ * and joints are the first examples. A project library may already own a
+ * viewport proxy for one of those objects. This mark lets the ordinary
+ * Object3D authoring projection name and inspect that proxy without teaching
+ * the editor shell the library's nouns or creating a persisted sidecar.
+ *
+ * The mark is observation only. Its values are read from the native owner at
+ * the moment they are requested, and any authored change still belongs in the
+ * owning TS/TSX or ecosystem artifact.
+ */
+import type * as THREE from 'three';
+import type { PropertyDescriptor } from './authoring';
+export interface Object3DAuthoringSubjectField extends PropertyDescriptor {
+    /** Read the current value from the native subject. */
+    readonly value: () => unknown;
+}
+export interface Object3DAuthoringSubjectMark {
+    readonly label: string;
+    readonly kind: string;
+    readonly typeLabel?: string;
+    readonly fields?: () => readonly Object3DAuthoringSubjectField[];
+    /** Presentation-only selection feedback for proxies hidden by default. */
+    readonly selectionChanged?: (selected: boolean) => void;
+}
+export declare function object3DAuthoringSubjectOf(object: THREE.Object3D | null | undefined): Object3DAuthoringSubjectMark | null;
+export declare function setObject3DAuthoringSubject(object: THREE.Object3D, mark: Object3DAuthoringSubjectMark): void;
+export declare function clearObject3DAuthoringSubject(object: THREE.Object3D): void;
+//# sourceMappingURL=object3d-authoring-subject.d.ts.map

package/dist/adapter/object3d-authoring-subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object3d-authoring-subject.d.ts","sourceRoot":"","sources":["../../src/adapter/object3d-authoring-subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,6BAA8B,SAAQ,kBAAkB;IACvE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,SAAS,6BAA6B,EAAE,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CACzD;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,GACxC,4BAA4B,GAAG,IAAI,CAGrC;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,KAAK,CAAC,QAAQ,EACtB,IAAI,EAAE,4BAA4B,GACjC,IAAI,CAEN;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAE1E"}

package/dist/adapter/object3d-authoring-subject.js

@@ -0,0 +1,25 @@
+/**
+ * Transient authoring identity for a native subject represented by an
+ * Object3D proxy.
+ *
+ * Some ecosystem-native objects are not Object3Ds themselves: Rapier bodies
+ * and joints are the first examples. A project library may already own a
+ * viewport proxy for one of those objects. This mark lets the ordinary
+ * Object3D authoring projection name and inspect that proxy without teaching
+ * the editor shell the library's nouns or creating a persisted sidecar.
+ *
+ * The mark is observation only. Its values are read from the native owner at
+ * the moment they are requested, and any authored change still belongs in the
+ * owning TS/TSX or ecosystem artifact.
+ */
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+export function object3DAuthoringSubjectOf(object) {
+    const mark = getUserData(object, 'authoringSubject');
+    return mark && typeof mark.label === 'string' && typeof mark.kind === 'string' ? mark : null;
+}
+export function setObject3DAuthoringSubject(object, mark) {
+    setUserData(object, 'authoringSubject', mark);
+}
+export function clearObject3DAuthoringSubject(object) {
+    deleteUserData(object, 'authoringSubject');
+}

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

@@ -1,26 +1,10 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the HOST depends on. It replaces the old
- * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`
- * — that is the internal of ONE implementer
- * (`SetupThreeRootAdapter`). First-party content and an unmodified external game
- * are peer implementers of THIS interface; the host has no branch on which.
- *
- * It was `GameAdapter` until WO-9 #60, and the rename is an ONTOLOGY fix, not
- * taste. Under D20 a *game* is the manifest's whole `roots` array — that is
- * what `runtime/game.ts`'s `Game` is. Every implementer of THIS interface
- * adapts exactly ONE root. So `Game` and `GameAdapter` sat at different levels
- * of the ontology while sharing a name-stem, which reads as though one were
- * the adapter for the other. The surrounding vocabulary had already moved:
- * `MountedRootBase`, `MountedRoot`, `MountedRootFor`, `RootStateObserver`,
- * `SurfaceAdapterFor`, `RootInstance`, `mountManifestRoots` — and, decisively,
- * the resolver that PRODUCES these (`resolveRootAdapter`, `RootAdapterSchema`,
- * `resolveThreeRootAdapter`) already said root. The interface was the last
- * holdout, out of step with its own resolver.
- *
- * The `K = 'three'` default below is KEPT deliberately (see the note on the
- * interface).
+ * This is the interface the host depends on. `GameSetupFn` is private to one
+ * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
+ * external games are peer root adapters. A game is the manifest's complete
+ * roots array, while each adapter owns exactly one root.
  */
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
@@ -59,12 +43,9 @@ export interface RootStateObserver {
     snapshot(): unknown;
 }
 /**
- * Everything a mounted world provides EXCEPT its render surface: THREE.Scene/
- * THREE.Camera typing is replaced with kind-tagged world surfaces. Split out
- * of the old flat
- * `MountedThreeRoot` so a non-threejs world can carry its own kind-appropriate
- * surface field (a pixi `stage`, a react `container`) instead of being
- * force-fit through THREE `scene`/`camera` fields it doesn't have.
+ * Everything a mounted world provides except its render surface. Tagged
+ * mounted-root variants carry their native surface fields: a Three scene and
+ * camera, a Pixi stage, or a DOM container.
  */
 export interface MountedRootBase {
     /**
@@ -96,11 +77,8 @@ export interface MountedRootBase {
      *  field. */
     readonly observe?: RootStateObserver;
 }
-/** A live, mounted three world. The host obtains `scene`/`camera` to
- *  render+author. Until WO-9 task #9 this type also had a `MountedGame` alias,
- *  which every pre-T7.5 threejs call site named; the alias is deleted, because
- *  what it aliased is one three ROOT and a game is the manifest's whole set of
- *  roots (D20). */
+/** A live, mounted Three world. The host obtains `scene`/`camera` to render
+ * and author it. */
 export interface MountedThreeRoot extends MountedRootBase {
     readonly kind: 'three';
     /** The live scene + camera the editor inspects/renders for authoring. */
@@ -141,38 +119,29 @@ export interface MountedReactRoot extends MountedRootBase {
     readonly kind: 'dom';
     readonly container: HTMLElement;
 }
-/** Every kind of live, mounted world (T7.5) — the union `RootInstance.mounted`
- *  is typed against now, replacing the THREE-only `MountedThreeRoot`. */
+/** Every kind of live, mounted world. */
 export type MountedRoot = MountedThreeRoot | MountedPixiRoot | MountedReactRoot;
 /** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
  *  `BodyOf`/`ColliderOf` in `ecs/behavior.ts`) — lets generic code over
  *  `K extends AdapterSurface` name the right surface without a manual union. */
 export type MountedRootFor<K extends AdapterSurface> = K extends 'three' ? MountedThreeRoot : K extends 'canvas' ? MountedPixiRoot : K extends 'dom' ? MountedReactRoot : never;
 /**
- * The interface every game implements to run on the host. Generic over
- * {@link AdapterSurface} (T7.5) so a non-threejs implementer's `mount` returns
- * its OWN kind-tagged surface instead of being cast through the three shape —
- * defaults to `'three'` so every pre-T7.5 implementer/call site
- * (`RootAdapter`, unparameterized) keeps compiling unchanged.
+ * The interface every root implements to run on the host. Generic over
+ * {@link AdapterSurface} so `mount` receives and returns its native surface
+ * types. Bare `RootAdapter` denotes the first-party Three surface.
  *
- * `K` parameterizes BOTH halves of `mount` (P-8): until then only the RETURN
- * type was kind-tagged, while the PARAMETER was always the three-shaped
- * `ThreeHostContext` — so a `RootAdapter<'canvas'>` was, by its own type, handed a
- * `THREE.WebGLRenderer` it cannot use, and the production Pixi/React adapters
- * could not be `RootAdapter`s at all (they were separate structural types over
- * `CanvasHostContext`/`DomHostContext`, and `RootAdapter<'canvas'>` existed only in
- * tests). With `HostContextFor<K>` the surface tag picks the context type, and
- * those production adapters are now genuine `RootAdapter<K>` subtypes —
+ * `K` parameterizes both halves of `mount`: `HostContextFor<K>` selects the
+ * host context and `MountedRootFor<K>` selects the mounted result. Production
+ * adapters are genuine `RootAdapter<K>` subtypes —
  * `Pixi2DRootAdapter extends RootAdapter<'canvas'>`, `ReactRootAdapter extends
  * RootAdapter<'dom'>` (`runtime/create-runtime.ts`).
  */
 /**
- * On the `= 'three'` default (WO-9 #60 considered removing it, and did not):
- * this default is type-level only: an author who writes bare `RootAdapter` for
+ * The `= 'three'` default is type-level only: an author who writes bare
+ * `RootAdapter` for
  * a pixi root gets a compile error on `mount`'s return type, because
  * `MountedRootFor<'three'>` demands `scene`/`camera` a `MountedPixiRoot` has
- * not got. Wrong-by-default is caught by tsc, so removing this default would
- * be churn across ~125 bare call sites for no defect it could catch.
+ * not got.
  */
 export interface RootAdapter<K extends AdapterSurface = 'three'> {
     /** Stable id (telemetry/registry/conformance). */
@@ -184,17 +153,13 @@ export interface RootAdapter<K extends AdapterSurface = 'three'> {
 /**
  * One surface tag paired with an adapter typed FOR that surface (WO-34).
  *
- * Why this exists: a resolver that turns a manifest root into a mountable
+ * A resolver that turns a manifest root into a mountable
  * adapter handles every surface in one function, so its return type has to
  * span all three. Returning the bare union `RootAdapter<'three'> |
  * RootAdapter<'canvas'> | RootAdapter<'dom'>` does NOT work — a union of
  * function types INTERSECTS its parameters, so `.mount(host)` becomes
  * uncallable with any single host value (no one object is simultaneously a
- * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`). The historical
- * workaround was to declare the whole channel `RootAdapter<'three'>` and
- * re-assert the real kind at each call site with `as unknown as` — kind
- * ERASURE: the surface tag the manifest already knew was thrown away and
- * guessed back.
+ * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`).
  *
  * Carrying the tag ALONGSIDE the adapter fixes that structurally: this is a
  * discriminated union on `surface`, so `switch (resolved.surface)` narrows

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

@@ -1 +1 @@
-{"version":3,"file":"root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/root-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/root-adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter/root-adapter.js

@@ -1,25 +1,9 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the HOST depends on. It replaces the old
- * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`
- * — that is the internal of ONE implementer
- * (`SetupThreeRootAdapter`). First-party content and an unmodified external game
- * are peer implementers of THIS interface; the host has no branch on which.
- *
- * It was `GameAdapter` until WO-9 #60, and the rename is an ONTOLOGY fix, not
- * taste. Under D20 a *game* is the manifest's whole `roots` array — that is
- * what `runtime/game.ts`'s `Game` is. Every implementer of THIS interface
- * adapts exactly ONE root. So `Game` and `GameAdapter` sat at different levels
- * of the ontology while sharing a name-stem, which reads as though one were
- * the adapter for the other. The surrounding vocabulary had already moved:
- * `MountedRootBase`, `MountedRoot`, `MountedRootFor`, `RootStateObserver`,
- * `SurfaceAdapterFor`, `RootInstance`, `mountManifestRoots` — and, decisively,
- * the resolver that PRODUCES these (`resolveRootAdapter`, `RootAdapterSchema`,
- * `resolveThreeRootAdapter`) already said root. The interface was the last
- * holdout, out of step with its own resolver.
- *
- * The `K = 'three'` default below is KEPT deliberately (see the note on the
- * interface).
+ * This is the interface the host depends on. `GameSetupFn` is private to one
+ * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
+ * external games are peer root adapters. A game is the manifest's complete
+ * roots array, while each adapter owns exactly one root.
  */
 export {};

package/dist/adapter/root-seam-contract.d.ts

@@ -0,0 +1,124 @@
+/** Exhaustive proof requirements for substrate mount/lifecycle seams. */
+export declare const ROOT_ADAPTER_SHAPE: {
+    readonly id: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly mount: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+};
+export declare const MOUNTED_ROOT_BASE_SHAPE: {
+    readonly drivesOwnLoop: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly update: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly fixedUpdate: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly setPaused: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly step: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly resize: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly dispose: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly authoring: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly systems: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly observe: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+};
+export declare const ROOT_STATE_OBSERVER_SHAPE: {
+    readonly subscribe: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly snapshot: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "operation";
+    };
+};
+export declare const MOUNTED_THREE_SURFACE_SHAPE: {
+    readonly kind: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly scene: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly camera: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly rendererConfig: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+};
+export declare const MOUNTED_CANVAS_SURFACE_SHAPE: {
+    readonly kind: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly stage: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+};
+export declare const MOUNTED_DOM_SURFACE_SHAPE: {
+    readonly kind: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly container: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+};
+//# sourceMappingURL=root-seam-contract.d.ts.map

package/dist/adapter/root-seam-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-seam-contract.d.ts","sourceRoot":"","sources":["../../src/adapter/root-seam-contract.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAazE,eAAO,MAAM,kBAAkB;;;;;;;;;;;CAG7B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWlC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;CAGpC,CAAC;AAMH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;CAKtC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;;;;CAGvC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;CAGpC,CAAC"}

package/dist/adapter/root-seam-contract.js

@@ -0,0 +1,36 @@
+/** Exhaustive proof requirements for substrate mount/lifecycle seams. */
+import { defineSeamShape } from './seam-evidence';
+export const ROOT_ADAPTER_SHAPE = defineSeamShape()({
+    id: { optional: false, kind: 'value', required: 'shape' },
+    mount: { optional: false, kind: 'function', required: 'effect' },
+});
+export const MOUNTED_ROOT_BASE_SHAPE = defineSeamShape()({
+    drivesOwnLoop: { optional: false, kind: 'value', required: 'shape' },
+    update: { optional: true, kind: 'function', required: 'effect' },
+    fixedUpdate: { optional: true, kind: 'function', required: 'effect' },
+    setPaused: { optional: true, kind: 'function', required: 'effect' },
+    step: { optional: true, kind: 'function', required: 'effect' },
+    resize: { optional: true, kind: 'function', required: 'effect' },
+    dispose: { optional: false, kind: 'function', required: 'effect' },
+    authoring: { optional: true, kind: 'value', required: 'operation' },
+    systems: { optional: true, kind: 'value', required: 'operation' },
+    observe: { optional: true, kind: 'value', required: 'effect' },
+});
+export const ROOT_STATE_OBSERVER_SHAPE = defineSeamShape()({
+    subscribe: { optional: false, kind: 'function', required: 'effect' },
+    snapshot: { optional: false, kind: 'function', required: 'operation' },
+});
+export const MOUNTED_THREE_SURFACE_SHAPE = defineSeamShape()({
+    kind: { optional: false, kind: 'value', required: 'shape' },
+    scene: { optional: false, kind: 'value', required: 'effect' },
+    camera: { optional: false, kind: 'value', required: 'effect' },
+    rendererConfig: { optional: true, kind: 'value', required: 'shape' },
+});
+export const MOUNTED_CANVAS_SURFACE_SHAPE = defineSeamShape()({
+    kind: { optional: false, kind: 'value', required: 'shape' },
+    stage: { optional: false, kind: 'value', required: 'effect' },
+});
+export const MOUNTED_DOM_SURFACE_SHAPE = defineSeamShape()({
+    kind: { optional: false, kind: 'value', required: 'shape' },
+    container: { optional: false, kind: 'value', required: 'effect' },
+});