@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/dist/adapter/ingest/scene-capture.js

@@ -1,248 +0,0 @@
-/**
- * Scene capture — the core primitive of unmodified-game ingestion.
- *
- * An external three.js game owns its own `WebGLRenderer`, `Scene`, camera, and
- * render loop. To let the editor inspect/edit that live scene WITHOUT touching
- * the game's code, we need a handle to the game's `Scene`+camera the moment it
- * first renders. The robust way to obtain it is an **accessor trap** on
- * `WebGLRenderer.prototype.render`:
- *
- *   - `WebGLRenderer` assigns `this.render` as an OWN instance property inside
- *     its constructor (not on the prototype), and `THREE.WebGLRenderer` is a
- *     read-only module export (can't subclass-swap it). A naive "wrap render"
- *     hook therefore captures nothing.
- *   - Installing a getter/setter for `render` on the PROTOTYPE means the
- *     constructor's `this.render = realFn` hits our setter (the instance has no
- *     own `render` yet), we stash the real fn, and our getter returns a wrapper
- *     that captures `(scene, camera, renderer)` on the first real frame.
- *
- * This is the hardened, typed form of the `ingest-study` spike
- * (`docs/ingest-study-spike/vgai-ingest-adapter.js`), proven against an
- * unmodified `three.js/examples/games_fps` game.
- *
- * CRITICAL: the trap must be installed on the SAME `three` module instance the
- * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
- * three`), an external ESM game's `import 'three'` resolves to that one instance,
- * so passing the host's `THREE` here traps the game's renderer too. A game that
- * bundles its own copy of `three` cannot be captured this way (see
- * `docs/UNMODIFIED-GAME-INGESTION-STUDY.md` §4A — the module-identity gatekeeper).
- *
- * Wave 17 (`docs/WAVE17-F13-COMPOSER-RESIZE-FIX-DESIGN.md`) adds an OPTIONAL,
- * ADDITIVE composer capture: a game rendering through its own three.js addon
- * `EffectComposer` (`three/examples/jsm/postprocessing/EffectComposer.js`)
- * still trips the `render` trap above (its `RenderPass` calls
- * `renderer.render(scene,camera)` internally), but the renderer holds no
- * reference back to the composer, so the host previously could not resize the
- * composer's own (intentionally non-1:1, progressively-downsampled — see
- * `UnrealBloomPass`) render targets when the host resizes the game's pane.
- * Unlike `WebGLRenderer`, `EffectComposer` is a plain ES class whose methods
- * (including `render`) live on the PROTOTYPE, not assigned as own instance
- * properties in the constructor — so a direct method-wrapper (no getter/
- * setter indirection) on `EffectComposer.prototype.render` is sufficient: it
- * calls through to the real `render`, then — AFTER that call, so any nested
- * `renderer.render()` the pass makes has already hit the trap above and set
- * `captured` — records `this` (the composer instance) if its `.renderer` is
- * the captured one. This is deduped/shared-trappable for the same reason
- * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
- * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
- * instance — not a separate package with its own dedupe question. Proven
- * live against the `bloom-composer` fixture
- * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
- */
-/**
- * Install the render accessor trap on `threeNamespace.WebGLRenderer.prototype`.
- * Pass the host's `three` module so the game (which shares it) is trapped.
- *
- * `effectComposerCtor` is OPTIONAL (Wave 17, D-C2): pass the host's
- * `EffectComposer` class (`three/examples/jsm/postprocessing/EffectComposer.js`)
- * to also trap composer construction/rendering on that shared addon, so
- * `resizeComposers()` can reach it. Omitting it (or a game never constructing
- * one) leaves capture byte-identical to before this wave.
- *
- * Idempotent per call site is NOT guaranteed — install once per ingest session
- * and `uninstall()` on teardown.
- */
-export function installSceneCapture(threeNamespace, effectComposerCtor) {
-    const THREE_NS = threeNamespace;
-    const proto = THREE_NS.WebGLRenderer.prototype;
-    // Stash the real render fn per-instance under a unique symbol so multiple
-    // renderers (editor's + game's) never collide.
-    const REAL = Symbol('vgai.realRender');
-    let captured = null;
-    let drawCount = 0;
-    const waiters = [];
-    // Preserve any descriptor already on the prototype so uninstall can restore it.
-    const priorDescriptor = Object.getOwnPropertyDescriptor(proto, 'render');
-    // Trap setAnimationLoop to record each renderer's game loop callback, so the host
-    // can freeze (set null) and resume (re-set) the game's own rAF for stable editing.
-    // CRITICAL: like `render`, WebGLRenderer assigns `this.setAnimationLoop` as an OWN
-    // instance property in its constructor — NOT on the prototype. A naive value-wrapper
-    // on the prototype is therefore shadowed by the instance's own property and never
-    // runs (resume could never recover the callback). So we mirror the `render` trap: a
-    // prototype getter/setter. The constructor's `this.setAnimationLoop = realFn` hits
-    // our SETTER (the instance has no own property yet) and we stash realFn per-instance;
-    // the GETTER returns a wrapper that records each non-null callback before forwarding.
-    const REAL_SAL = Symbol('vgai.realSetAnimationLoop');
-    const loopCallbacks = new WeakMap();
-    const priorSAL = Object.getOwnPropertyDescriptor(proto, 'setAnimationLoop');
-    Object.defineProperty(proto, 'setAnimationLoop', {
-        configurable: true,
-        set(fn) {
-            this[REAL_SAL] = fn;
-        },
-        get() {
-            const self = this;
-            return function setAnimationLoop(cb) {
-                if (cb)
-                    loopCallbacks.set(self, cb);
-                const real = self[REAL_SAL];
-                return typeof real === 'function'
-                    ? real.call(self, cb)
-                    : undefined;
-            };
-        },
-    });
-    Object.defineProperty(proto, 'render', {
-        configurable: true,
-        set(fn) {
-            this[REAL] = fn;
-        },
-        get() {
-            const self = this;
-            return function render(...args) {
-                const [scene, camera] = args;
-                drawCount++;
-                if (!captured && scene && scene.isScene) {
-                    captured = {
-                        scene: scene,
-                        camera: camera,
-                        renderer: self,
-                    };
-                    for (const resolve of waiters.splice(0))
-                        resolve(captured);
-                }
-                // Forward to the renderer's real render with the original args.
-                return self[REAL].apply(self, args);
-            };
-        },
-    });
-    // ---- Wave 17 (D-C2): additive composer capture, only when a composer ctor
-    // was passed. `EffectComposer` methods (including `render`) live on the
-    // PROTOTYPE (a plain ES class — the constructor never does `this.render =
-    // …`), so a direct method-wrapper suffices — no getter/setter indirection
-    // like the `render`/`setAnimationLoop` traps above need. ----
-    const composers = new Set();
-    let composerProto;
-    let priorComposerRender;
-    if (effectComposerCtor) {
-        const EC = effectComposerCtor;
-        composerProto = EC.prototype;
-        priorComposerRender = composerProto['render'];
-        composerProto['render'] = function (...args) {
-            // Call the real render FIRST: a composer's RenderPass calls
-            // `renderer.render(scene,camera)` internally, which is what actually
-            // sets `captured` (above) on the game's first frame. Checking after
-            // ensures a composer's very first render is still collected.
-            const result = priorComposerRender?.apply(this, args);
-            if (captured && this.renderer === captured.renderer) {
-                composers.add(this);
-            }
-            return result;
-        };
-    }
-    // Extracted so `uninstall()`'s own cognitive complexity doesn't grow with
-    // this additive Wave-17 restore step (biome's noExcessiveCognitiveComplexity).
-    function restoreComposerTrap() {
-        if (!composerProto)
-            return;
-        if (priorComposerRender)
-            composerProto['render'] = priorComposerRender;
-        else
-            delete composerProto['render'];
-    }
-    return {
-        get captured() {
-            return captured;
-        },
-        getDrawCount() {
-            return drawCount;
-        },
-        getAnimationLoop(renderer) {
-            return loopCallbacks.get(renderer) ?? null;
-        },
-        resizeComposers(w, h) {
-            // No composer ctor passed (or none constructed yet) → no-op, and never
-            // touches `renderer.getPixelRatio()` — a non-composer game's captured
-            // renderer need not even expose that method for this to stay a no-op.
-            if (!captured || composers.size === 0)
-                return;
-            const pixelRatio = captured.renderer.getPixelRatio();
-            for (const composer of composers) {
-                composer.setSize(w, h);
-                composer.setPixelRatio(pixelRatio);
-            }
-        },
-        waitForCapture(timeoutMs = 10_000) {
-            if (captured)
-                return Promise.resolve(captured);
-            return new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    const i = waiters.indexOf(wrapped);
-                    if (i >= 0)
-                        waiters.splice(i, 1);
-                    reject(new Error(`Scene capture timed out after ${timeoutMs}ms — the game never rendered, ` +
-                        `or it bundles its own (un-shared) copy of three.`));
-                }, timeoutMs);
-                const wrapped = (rt) => {
-                    clearTimeout(timer);
-                    resolve(rt);
-                };
-                waiters.push(wrapped);
-            });
-        },
-        uninstall() {
-            // Restore the captured renderer's real render as an OWN property so its
-            // loop keeps working after the prototype trap is removed.
-            if (captured) {
-                const r = captured.renderer;
-                const real = r[REAL];
-                if (typeof real === 'function') {
-                    Object.defineProperty(captured.renderer, 'render', {
-                        configurable: true,
-                        writable: true,
-                        value: real,
-                    });
-                }
-            }
-            if (priorDescriptor) {
-                Object.defineProperty(proto, 'render', priorDescriptor);
-            }
-            else {
-                delete proto['render'];
-            }
-            // Restore the captured renderer's real setAnimationLoop as an OWN property (the
-            // prototype getter/setter intercepted the constructor's assignment, so the
-            // instance has none) — else removing the prototype trap would leave it without
-            // setAnimationLoop and freeze its loop.
-            if (captured) {
-                const r = captured.renderer;
-                const realSal = r[REAL_SAL];
-                if (typeof realSal === 'function') {
-                    Object.defineProperty(captured.renderer, 'setAnimationLoop', {
-                        configurable: true,
-                        writable: true,
-                        value: realSal,
-                    });
-                }
-            }
-            if (priorSAL)
-                Object.defineProperty(proto, 'setAnimationLoop', priorSAL);
-            else
-                delete proto['setAnimationLoop'];
-            // Wave 17: fully restore the composer addon's `render` (a plain
-            // prototype method — no per-instance own-property to restore, unlike
-            // the renderer/loop traps above).
-            restoreComposerTrap();
-        },
-    };
-}

package/dist/adapter/ingest/upstream-pin.d.ts

@@ -1,47 +0,0 @@
-/**
- * Upstream-pin extraction — R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/
- * §7.1 item 9): the fix for the overlay identity gap the structural-id +
- * `authoredAgainst.gameVersion` scheme (T7.7/D9) does not close. A re-vendor
- * of a vendored upstream game that keeps a slot's shape (index + three.js
- * type + name unchanged) reapplies a saved overlay onto a semantically
- * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning
- * success — because `authoredAgainst.gameVersion` is the MANIFEST's own
- * `version` (hand-set by whoever wrote `vgai.game.json`, e.g. every
- * `public/ingest/*` vendored game ships `"version": "0.1.0"` regardless of
- * which upstream commit it vendors — see `public/ingest/{tanks,racing-game,
- * simcity}/vgai.game.json`), never tied to the thing that actually changes on
- * a re-vendor: the `UPSTREAM.md` pin.
- *
- * This module is the pure, dependency-free half (parse text -> pin, or
- * `null`): NO file I/O here, so it is usable from any context (editor
- * save/apply-time hooks over a fetched `/UPSTREAM.md`, a future Node-side
- * CLI check, tests). READ-ONLY by construction — it has no writer; this
- * codebase never generates or edits an `UPSTREAM.md` (the anti-shim rule:
- * adapters never fabricate first-party data, and a game's own vendoring
- * provenance is exactly that).
- *
- * Format (established convention, not invented here — see every
- * `public/ingest/*\/UPSTREAM.md`'s `## Upstream` section, e.g.
- * `public/ingest/tanks/UPSTREAM.md`):
- *
- *   ## Upstream
- *
- *   - Repo: https://github.com/colyseus/realtime-tanks-demo
- *   - Commit: **`6339493130b4b1d4d28f0f52d17b2fba738c7d47`**
- *
- * i.e. a Markdown bullet whose label is `Commit:` and whose value is a bold,
- * backtick-code full (or abbreviated) git SHA. Every vendored game in this
- * repo (`tanks`, `racing-game`, `simcity`) follows this exact shape.
- */
-/**
- * Extract the pinned upstream commit hash from a vendored game's
- * `UPSTREAM.md` prose, or `null` if the file doesn't follow the convention
- * (or wasn't found — the caller decides what a missing file means; this
- * function only parses text it's handed). Never throws — an unparseable
- * document is an honest `null`, not an error (anti-shim: no guessing, no
- * fabricating a pin from a game folder that doesn't declare one, e.g. an
- * externally-authored non-vendored project opened via the CLI-on-folder
- * route).
- */
-export declare function extractUpstreamPin(markdown: string): string | null;
-//# sourceMappingURL=upstream-pin.d.ts.map

package/dist/adapter/ingest/upstream-pin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"upstream-pin.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/upstream-pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAElE"}

package/dist/adapter/ingest/upstream-pin.js

@@ -1,50 +0,0 @@
-/**
- * Upstream-pin extraction — R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/
- * §7.1 item 9): the fix for the overlay identity gap the structural-id +
- * `authoredAgainst.gameVersion` scheme (T7.7/D9) does not close. A re-vendor
- * of a vendored upstream game that keeps a slot's shape (index + three.js
- * type + name unchanged) reapplies a saved overlay onto a semantically
- * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning
- * success — because `authoredAgainst.gameVersion` is the MANIFEST's own
- * `version` (hand-set by whoever wrote `vgai.game.json`, e.g. every
- * `public/ingest/*` vendored game ships `"version": "0.1.0"` regardless of
- * which upstream commit it vendors — see `public/ingest/{tanks,racing-game,
- * simcity}/vgai.game.json`), never tied to the thing that actually changes on
- * a re-vendor: the `UPSTREAM.md` pin.
- *
- * This module is the pure, dependency-free half (parse text -> pin, or
- * `null`): NO file I/O here, so it is usable from any context (editor
- * save/apply-time hooks over a fetched `/UPSTREAM.md`, a future Node-side
- * CLI check, tests). READ-ONLY by construction — it has no writer; this
- * codebase never generates or edits an `UPSTREAM.md` (the anti-shim rule:
- * adapters never fabricate first-party data, and a game's own vendoring
- * provenance is exactly that).
- *
- * Format (established convention, not invented here — see every
- * `public/ingest/*\/UPSTREAM.md`'s `## Upstream` section, e.g.
- * `public/ingest/tanks/UPSTREAM.md`):
- *
- *   ## Upstream
- *
- *   - Repo: https://github.com/colyseus/realtime-tanks-demo
- *   - Commit: **`6339493130b4b1d4d28f0f52d17b2fba738c7d47`**
- *
- * i.e. a Markdown bullet whose label is `Commit:` and whose value is a bold,
- * backtick-code full (or abbreviated) git SHA. Every vendored game in this
- * repo (`tanks`, `racing-game`, `simcity`) follows this exact shape.
- */
-/** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */
-const COMMIT_BULLET_RE = /-\s*Commit:\s*\*\*`([0-9a-fA-F]{7,40})`\*\*/;
-/**
- * Extract the pinned upstream commit hash from a vendored game's
- * `UPSTREAM.md` prose, or `null` if the file doesn't follow the convention
- * (or wasn't found — the caller decides what a missing file means; this
- * function only parses text it's handed). Never throws — an unparseable
- * document is an honest `null`, not an error (anti-shim: no guessing, no
- * fabricating a pin from a game folder that doesn't declare one, e.g. an
- * externally-authored non-vendored project opened via the CLI-on-folder
- * route).
- */
-export function extractUpstreamPin(markdown) {
-    return COMMIT_BULLET_RE.exec(markdown)?.[1] ?? null;
-}

package/dist/adapter/loop-gate-report.d.ts

@@ -1,34 +0,0 @@
-/**
- * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
- * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
- * (`gated | self-driven`) as independent of capability tier: a `self-driven`
- * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
- * its adapter implements an explicit loop-gate capability
- * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
- * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
- * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
- * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
- * silence a world's audio on pause must report, not pretend.
- *
- * Pure compute + message-formatting, same split as `achieved-tier.ts`
- * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
- * `console.warn`/`editorConsole.warn` call; this module never logs.
- */
-/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
- *  could not actually be gated). */
-export declare const LOOP_GATE_PREFIX = "loop-gate";
-/** Greppable prefix for an audio-gate shortfall (pause requested, world's
- *  audio could not actually be silenced). */
-export declare const AUDIO_GATE_PREFIX = "audio-gate";
-/** One shortfall instance: which world, and why the capability wasn't there. */
-export interface CapabilityGateReport {
-    readonly worldId: string;
-    readonly reason: string;
-}
-/** Format a loop-gate shortfall message (a `self-driven` world with no
- *  working pause capability). */
-export declare function formatLoopGateMessage(report: CapabilityGateReport): string;
-/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
- *  whose adapter cannot actually silence it). */
-export declare function formatAudioGateMessage(report: CapabilityGateReport): string;
-//# sourceMappingURL=loop-gate-report.d.ts.map

package/dist/adapter/loop-gate-report.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loop-gate-report.d.ts","sourceRoot":"","sources":["../../src/adapter/loop-gate-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;oCACoC;AACpC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;6CAC6C;AAC7C,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAcD;iCACiC;AACjC,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE1E;AAED;iDACiD;AACjD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE3E"}

package/dist/adapter/loop-gate-report.js

@@ -1,37 +0,0 @@
-/**
- * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
- * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
- * (`gated | self-driven`) as independent of capability tier: a `self-driven`
- * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
- * its adapter implements an explicit loop-gate capability
- * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
- * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
- * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
- * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
- * silence a world's audio on pause must report, not pretend.
- *
- * Pure compute + message-formatting, same split as `achieved-tier.ts`
- * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
- * `console.warn`/`editorConsole.warn` call; this module never logs.
- */
-/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
- *  could not actually be gated). */
-export const LOOP_GATE_PREFIX = 'loop-gate';
-/** Greppable prefix for an audio-gate shortfall (pause requested, world's
- *  audio could not actually be silenced). */
-export const AUDIO_GATE_PREFIX = 'audio-gate';
-function formatGateMessage(prefix, capability, report) {
-    return (`${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
-        `(${report.reason}) — reporting honestly instead of silently no-op-ing ` +
-        `(docs/CAPABILITY-TIERS.md §d). ${prefix} ${JSON.stringify(report)}`);
-}
-/** Format a loop-gate shortfall message (a `self-driven` world with no
- *  working pause capability). */
-export function formatLoopGateMessage(report) {
-    return formatGateMessage(LOOP_GATE_PREFIX, "this world's loop", report);
-}
-/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
- *  whose adapter cannot actually silence it). */
-export function formatAudioGateMessage(report) {
-    return formatGateMessage(AUDIO_GATE_PREFIX, "this world's audio", report);
-}

package/dist/adapter/rapier-physics-adapter.d.ts

@@ -1,12 +0,0 @@
-/**
- * RapierPhysicsAdapter — the first-party `PhysicsAdapter` over the existing
- * `PhysicsRegistry` (Object3D ↔ Rapier body/collider). This is the generalized,
- * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
- * the editor freeze a body, apply a gizmo edit, and resume — without the editor
- * knowing Rapier exists.
- */
-import type * as THREE from 'three';
-import type { PhysicsRegistry } from '../physics/physics-registry';
-import type { PhysicsAdapter } from './system-adapter';
-export declare function createRapierPhysicsAdapter(registry: PhysicsRegistry, debugMesh?: THREE.Object3D | null): PhysicsAdapter;
-//# sourceMappingURL=rapier-physics-adapter.d.ts.map

package/dist/adapter/rapier-physics-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rapier-physics-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/rapier-physics-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAChC,cAAc,CAsChB"}

package/dist/adapter/rapier-physics-adapter.js

@@ -1,46 +0,0 @@
-/**
- * RapierPhysicsAdapter — the first-party `PhysicsAdapter` over the existing
- * `PhysicsRegistry` (Object3D ↔ Rapier body/collider). This is the generalized,
- * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
- * the editor freeze a body, apply a gizmo edit, and resume — without the editor
- * knowing Rapier exists.
- */
-export function createRapierPhysicsAdapter(registry, debugMesh) {
-    /** Saved body types while frozen, so unfreeze can restore them. */
-    const frozen = new Map();
-    return {
-        ownerOf(o) {
-            const body = registry.get(o)?.body;
-            if (!body)
-                return 'editor';
-            // A fixed body never moves on its own → the editor owns its transform.
-            return body.isFixed() ? 'editor' : 'physics';
-        },
-        freeze(o) {
-            const body = registry.get(o)?.body;
-            if (!body || frozen.has(body))
-                return;
-            frozen.set(body, body.bodyType());
-            // Kinematic-position: the body stops simulating but tracks the pose we set.
-            body.setBodyType(2 /* KinematicPositionBased */, true);
-        },
-        commit(o, t) {
-            const body = registry.get(o)?.body;
-            if (!body)
-                return;
-            body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
-            body.setRotation({ x: t.rotation[0], y: t.rotation[1], z: t.rotation[2], w: t.rotation[3] }, true);
-        },
-        unfreeze(o) {
-            const body = registry.get(o)?.body;
-            if (!body)
-                return;
-            const prev = frozen.get(body);
-            if (prev !== undefined) {
-                body.setBodyType(prev, true);
-                frozen.delete(body);
-            }
-        },
-        debugDraw: () => debugMesh ?? null,
-    };
-}

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

@@ -1,133 +0,0 @@
-/**
- * System adapters — optional subsystem capability providers hung off a mounted
- * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
- * coordinate with WITHOUT owning the implementation. The first-party
- * implementers wrap Rapier / Colyseus / the InputManager; an external game
- * supplies its own or none, and the editor degrades per `capabilities`.
- *
- * These are introspection/coordination boundaries, NOT re-implementations: e.g.
- * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
- * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
- * edit it".
- */
-import type * as THREE from 'three';
-import type { ActionValueType, Vector2 } from '../input/input-types';
-import type { Transform, TransformOwner } from './transform';
-/**
- * Physics coordination so the editor can stably edit an object a simulation
- * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
- */
-export interface PhysicsAdapter {
-    /** Returns `'physics'` when a body drives this object, else another owner. */
-    ownerOf(o: THREE.Object3D): TransformOwner;
-    /** Pause the body driving `o` (kinematic / sleep / detach) for editing. */
-    freeze(o: THREE.Object3D): void;
-    /** Teleport the body to the edited pose (so the sim continues from there). */
-    commit(o: THREE.Object3D, t: Transform): void;
-    /** Resume simulation of `o`. */
-    unfreeze(o: THREE.Object3D): void;
-    /** Optional debug-draw object (collider wireframes). */
-    debugDraw?(): THREE.Object3D | null;
-}
-export interface NetPeer {
-    id: string;
-    label?: string;
-}
-/** The live connection lifecycle, for the editor's network inspector. */
-export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
-/** Identity of the room the local peer is currently in, or `null` when not connected. */
-export interface RoomInfo {
-    roomId: string;
-    sessionId: string;
-    roomName: string;
-}
-/** Lightweight replication counters for the editor's network inspector. */
-export interface ReplicationStats {
-    /** Number of replicated entities currently known (e.g. players + NPCs). */
-    entities: number;
-    /** Approximate inbound replication activity (state changes observed per second). */
-    msgsInPerSec: number;
-    /** Approximate outbound message rate (client → server sends per second). */
-    msgsOutPerSec: number;
-}
-export type Unsubscribe = () => void;
-/** INTROSPECTION over replication state — NOT a networking transport. */
-export interface NetworkingAdapter {
-    peers(): NetPeer[];
-    networkId(o: THREE.Object3D): string | null;
-    authority(o: THREE.Object3D): 'local' | 'remote' | 'server';
-    /** Remote/server-authoritative objects → inspect-only in the editor. */
-    editable(o: THREE.Object3D): boolean;
-    /** Current connection lifecycle state. */
-    getConnectionState(): ConnectionState;
-    /** The active room's identity, or `null` when not connected to a room. */
-    getRoomInfo(): RoomInfo | null;
-    /** Replication activity snapshot, for a live network inspector panel. */
-    getReplicationStats(): ReplicationStats;
-    /** Subscribe to changes in connection state / room / replication stats. */
-    subscribe(cb: () => void): Unsubscribe;
-}
-/** One action's current value, tagged with its declared shape (F1 `ActionValueType`) so a
- *  consumer (editor input inspector, conformance suite) can render/assert on the real typed
- *  value instead of a lossy digital coercion. `value` is a `number` for `'digital'`
- *  (1 = pressed, 0 = not) and `'scalar'`, or a `Vector2` for `'vector2'`/`'pointerDelta'`/
- *  `'pointerPosition'` — narrow on `type` to know which. */
-export interface ActionValueSnapshot {
-    type: ActionValueType;
-    value: number | Vector2;
-}
-export interface InputAdapter {
-    poll(): void;
-    /** Every named action's current value, faithfully typed per its declared `ActionValueType`
-     *  (F1, spec §12) — digital reads as 1/0, scalar as its float, vector2/pointerDelta/
-     *  pointerPosition as `{x,y}`. Never coerces a non-digital action down to 0/1. */
-    actions(): Readonly<Record<string, ActionValueSnapshot>>;
-}
-/** URL remap so an ingested game's relative asset paths resolve under the host. */
-export interface AssetAdapter {
-    resolve(url: string): string;
-}
-export interface NavPoint {
-    x: number;
-    y: number;
-    z: number;
-}
-/**
- * Inspect a game's navigation mesh: whether one is built, query a path, and get a
- * debug overlay. Coordination/introspection only — the editor doesn't own the build.
- */
-export interface NavigationAdapter {
-    hasNavMesh(): boolean;
-    findPath(start: NavPoint, end: NavPoint): NavPoint[];
-    debugMesh(scene: THREE.Scene): THREE.Object3D | null;
-}
-/**
- * Silence/restore a world's own audio (D10, T7.6) — NOT a mixer/bus API. This
- * is the seam `Game.play.pause()` calls so a paused world's audio goes quiet
- * too (`docs/DECISIONS-PENDING.md` §D10: "an audio seam in `SystemAdapters` so
- * pause can silence game audio (howler et al.) or explicitly report it
- * cannot"). Absence on a world's `mounted.systems` means exactly that:
- * `Game.play.pause()` reports it loudly once per world rather than silently
- * leaving that world's audio playing under a "paused" game.
- */
-export interface AudioAdapter {
-    /** `true` silences this world's audio; `false` restores it to whatever
-     *  level it was at before silencing (an implementer's own concern — the
-     *  first-party adapter restores its master-gain value, not a hardcoded 1). */
-    setMuted(muted: boolean): void;
-    /** Current muted state, for inspection (editor mute UI, proofs). */
-    isMuted(): boolean;
-}
-/**
- * The set of optional subsystem providers a mounted game may expose. Absence of
- * a provider means "capability not supported" — the editor degrades gracefully.
- */
-export interface SystemAdapters {
-    physics?: PhysicsAdapter;
-    networking?: NetworkingAdapter;
-    input?: InputAdapter;
-    assets?: AssetAdapter;
-    navigation?: NavigationAdapter;
-    audio?: AudioAdapter;
-}
-//# sourceMappingURL=system-adapter.d.ts.map

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

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

package/dist/adapter/system-adapter.js

@@ -1,13 +0,0 @@
-/**
- * System adapters — optional subsystem capability providers hung off a mounted
- * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
- * coordinate with WITHOUT owning the implementation. The first-party
- * implementers wrap Rapier / Colyseus / the InputManager; an external game
- * supplies its own or none, and the editor degrades per `capabilities`.
- *
- * These are introspection/coordination boundaries, NOT re-implementations: e.g.
- * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
- * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
- * edit it".
- */
-export {};