@vgai/engine 0.5.5 → 0.5.6

package/dist/adapter/ingest/structural-ids.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Structural identity — the deterministic id scheme (and the small material
+ * reflection helper that rides along with it) the editor's live-three authoring
+ * adapter uses to address the objects of a world whose source carries no
+ * serve-time identity stamps
+ * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ *
+ * Identity: each object gets a **structural-path id** — deterministic from the
+ * scene's shape (position in the tree + three.js type + name), so the SAME id
+ * re-binds to the SAME object after the game rebuilds its scene within a
+ * session. It is also written to `userData.entityId` so the editor's object map
+ * / gizmo / selection (which key on `entityId`) bind to foreign objects with no
+ * further shim.
+ *
+ * This module used to be the shared core of a per-game JSON sidecar
+ * persistence system, which was deleted outright (2026-08-02) — ingest edits
+ * are LIVE-ONLY now. The id scheme survives because it is what makes the live
+ * hierarchy/selection/inspector work at all; nothing here reads or writes a
+ * file.
+ */
+import type * as THREE from 'three';
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export declare const CAMERA_ID = "ingest:camera";
+/**
+ * The material whose colour a mesh's swatch reflects, if it has one.
+ *
+ * A multi-material mesh reflects its FIRST slot — that is what a single swatch
+ * can honestly stand for, and it is also the slot a creation-site anchor for
+ * `material.color` resolves against. Returns `null` for anything with no
+ * `color` at all rather than fabricating one.
+ */
+export declare function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null;
+/** Result of a structural-path walk: the id→object map plus a few reflection stats. */
+export interface StructuralIdWalk {
+    byId: Map<string, THREE.Object3D>;
+    count: number;
+    meshes: number;
+    lights: number;
+}
+/**
+ * (Re)assign structural-path ids to every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — so a re-walk after the game rebuilds part of its
+ * tree re-binds the same ids to the same objects.
+ *
+ * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
+ * cosmetic. In ingest mode the editor adds its grid, lights, particle
+ * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
+ * they arrive asynchronously — some before the walk, some after. Indexing them
+ * made a game object's path depend on how much editor furniture happened to be
+ * attached at walk time, so the same mesh changed id across a re-walk (observed
+ * in the games-fps ingest: an object addressed as `ingest:106/0/0/0:…` came
+ * back as `ingest:102/0:Mesh:Cube004` — four root slots earlier, exactly the
+ * grid + two editor lights + BatchedRenderer).
+ *
+ * Skipping the furniture entirely — not merely declining to give it an id —
+ * is what fixes that: the game's own children occupy 0..N-1 whatever else is
+ * parented alongside them. It also keeps gizmo handles and the grid out of the
+ * hierarchy/inspector projections built on this walk, where they were
+ * selectable and colorable as if they were game content.
+ */
+export declare function assignStructuralIds(scene: THREE.Object3D, camera?: THREE.Object3D | undefined): StructuralIdWalk;
+//# sourceMappingURL=structural-ids.d.ts.map

package/dist/adapter/ingest/structural-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-ids.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/structural-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,0FAA0F;AAC1F,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAoBzC;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAKpF;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CAgClB"}

package/dist/adapter/ingest/structural-ids.js

@@ -0,0 +1,110 @@
+/**
+ * Structural identity — the deterministic id scheme (and the small material
+ * reflection helper that rides along with it) the editor's live-three authoring
+ * adapter uses to address the objects of a world whose source carries no
+ * serve-time identity stamps
+ * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ *
+ * Identity: each object gets a **structural-path id** — deterministic from the
+ * scene's shape (position in the tree + three.js type + name), so the SAME id
+ * re-binds to the SAME object after the game rebuilds its scene within a
+ * session. It is also written to `userData.entityId` so the editor's object map
+ * / gizmo / selection (which key on `entityId`) bind to foreign objects with no
+ * further shim.
+ *
+ * This module used to be the shared core of a per-game JSON sidecar
+ * persistence system, which was deleted outright (2026-08-02) — ingest edits
+ * are LIVE-ONLY now. The id scheme survives because it is what makes the live
+ * hierarchy/selection/inspector work at all; nothing here reads or writes a
+ * file.
+ */
+import { setUserData } from '../../ecs/user-data';
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export const CAMERA_ID = 'ingest:camera';
+/**
+ * The editor parks its OWN objects — grid, its two lights, the particle
+ * BatchedRenderer, every TransformControls/gizmo helper — on layer 31
+ * (`packages/editor/src/editor-layers.ts`'s `EDITOR_LAYER`) so the game camera
+ * never sees them. In ingest mode those objects are added to the GAME'S OWN
+ * scene, which is the same tree this walk indexes.
+ */
+const EDITOR_ONLY_LAYER_MASK = 1 << 31;
+/**
+ * Editor furniture, not game content. Excluded from the walk entirely — see
+ * {@link assignStructuralIds} for why that exclusion is what makes the id
+ * scheme's central promise true.
+ */
+function isEditorOnly(o) {
+    return (o.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0;
+}
+/**
+ * The material whose colour a mesh's swatch reflects, if it has one.
+ *
+ * A multi-material mesh reflects its FIRST slot — that is what a single swatch
+ * can honestly stand for, and it is also the slot a creation-site anchor for
+ * `material.color` resolves against. Returns `null` for anything with no
+ * `color` at all rather than fabricating one.
+ */
+export function colorMaterialOf(o) {
+    const mat = o.material;
+    if (!mat)
+        return null;
+    const m = (Array.isArray(mat) ? mat[0] : mat);
+    return m?.color ? m : null;
+}
+/**
+ * (Re)assign structural-path ids to every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — so a re-walk after the game rebuilds part of its
+ * tree re-binds the same ids to the same objects.
+ *
+ * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
+ * cosmetic. In ingest mode the editor adds its grid, lights, particle
+ * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
+ * they arrive asynchronously — some before the walk, some after. Indexing them
+ * made a game object's path depend on how much editor furniture happened to be
+ * attached at walk time, so the same mesh changed id across a re-walk (observed
+ * in the games-fps ingest: an object addressed as `ingest:106/0/0/0:…` came
+ * back as `ingest:102/0:Mesh:Cube004` — four root slots earlier, exactly the
+ * grid + two editor lights + BatchedRenderer).
+ *
+ * Skipping the furniture entirely — not merely declining to give it an id —
+ * is what fixes that: the game's own children occupy 0..N-1 whatever else is
+ * parented alongside them. It also keeps gizmo handles and the grid out of the
+ * hierarchy/inspector projections built on this walk, where they were
+ * selectable and colorable as if they were game content.
+ */
+export function assignStructuralIds(scene, camera) {
+    const byId = new Map();
+    let count = 0;
+    let meshes = 0;
+    let lights = 0;
+    const visit = (o, path) => {
+        const id = `ingest:${path}:${o.type}:${o.name || ''}`;
+        setUserData(o, 'entityId', id);
+        byId.set(id, o);
+        count++;
+        if (o.isLight)
+            lights++;
+        else if (o.isMesh)
+            meshes++;
+        visitChildren(o, path);
+    };
+    const visitChildren = (o, path) => {
+        let i = 0;
+        for (const c of o.children) {
+            if (isEditorOnly(c))
+                continue;
+            visit(c, path ? `${path}/${i}` : `${i}`);
+            i++;
+        }
+    };
+    visitChildren(scene, '');
+    if (camera) {
+        setUserData(camera, 'entityId', CAMERA_ID);
+        byId.set(CAMERA_ID, camera);
+        count++;
+    }
+    return { byId, count, meshes, lights };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Upstream-pin extraction — R5 ((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 the ingest manifest, e.g. every `public/ingest/*` vendored game
+ * ships `"version": "0.1.0"` regardless of which upstream commit it vendors), 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

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

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

@@ -0,0 +1,47 @@
+/**
+ * Upstream-pin extraction — R5 ((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 the ingest manifest, e.g. every `public/ingest/*` vendored game
+ * ships `"version": "0.1.0"` regardless of which upstream commit it vendors), 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

@@ -0,0 +1,34 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. §(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 (`MountedRootBase.setPaused`/`step`) —
+ * otherwise it "honestly reports so" rather than a silent no-op (the
+ * D5 §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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,37 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. §(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 (`MountedRootBase.setPaused`/`step`) —
+ * otherwise it "honestly reports so" rather than a silent no-op (the
+ * D5 §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. ` +
+        `${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

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ *
+ * The seam is keyed by NODE ID (P-4), so THIS is where the three-specific
+ * `id → Object3D` step happens: once, at the implementer's own boundary,
+ * through the `resolve` function its constructor is handed. Nothing above this
+ * line — not the editor, not the seam — needs to know an `Object3D` exists.
+ */
+import type * as THREE from 'three';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { PhysicsContext } from '../setup/setup-physics';
+import type { PhysicsAdapter } from './system-adapter';
+/**
+ * Exactly what {@link createRapierBodyEditing} touches on a Rapier rigid body,
+ * declared STRUCTURALLY rather than as `RAPIER.RigidBody`.
+ *
+ * Not a wrapper and not an abstraction — it names five of Rapier's own methods
+ * with Rapier's own semantics, and every caller keeps passing Rapier's own
+ * objects. It exists because this repo legitimately resolves TWO copies of
+ * `@dimforge/rapier3d-compat`: the engine's own (0.14) and the one
+ * `@react-three/rapier` pins for R3F worlds (0.19). Their `RigidBody` classes
+ * are unrelated NOMINAL types, so a shared helper that named either one could
+ * not serve both callers.
+ */
+export interface RapierEditableBody {
+    isFixed(): boolean;
+    bodyType(): number;
+    setBodyType(type: number, wakeUp: boolean): void;
+    setTranslation(translation: {
+        x: number;
+        y: number;
+        z: number;
+    }, wakeUp: boolean): void;
+    setRotation(rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }, wakeUp: boolean): void;
+}
+/**
+ * The four REQUIRED `PhysicsAdapter` members, over nothing but "which Rapier
+ * body drives this node" — the `freeze → apply → unfreeze` protocol itself,
+ * with no opinion about where the body came from.
+ *
+ * Split out of {@link createRapierPhysicsAdapter} (it is that function's own
+ * `ownerOf`/`freeze`/`commit`/`unfreeze`, unchanged) because the FIRST-PARTY
+ * mount is no longer the only Rapier in this engine: an R3F world does its
+ * physics with `@react-three/rapier` inside the fiber tree, which owns its own
+ * bodies and its own `Object3D` mapping, and reaches these same four verbs
+ * through `world3d-react/rapier-physics-bridge.tsx`. The optional members
+ * (`debugDraw`, `setDebugDrawEnabled`, `contactPoints`) are NOT here: each is
+ * answered differently by each Rapier owner, and a caller that cannot answer
+ * one honestly omits it.
+ */
+export declare function createRapierBodyEditing(bodyFor: (nodeId: string) => RapierEditableBody | null | undefined): Pick<PhysicsAdapter, 'ownerOf' | 'freeze' | 'commit' | 'unfreeze'>;
+export declare function createRapierPhysicsAdapter(registry: PhysicsRegistry, physics: PhysicsContext | null | undefined, 
+/**
+ * The world's own `id → Object3D` map. Injected rather than derived here so
+ * this file never hard-codes an identity convention (e.g. reading the
+ * first-party `userData.entityId` key off foreign objects, which is the
+ * ingest-stamping leak the retirement playbook deliberately parked).
+ */
+resolve: (nodeId: string) => THREE.Object3D | null): PhysicsAdapter;
+//# sourceMappingURL=rapier-physics-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rapier-physics-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/rapier-physics-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,OAAO,CAAC;IACnB,QAAQ,IAAI,MAAM,CAAC;IACnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,WAAW,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACxF,WAAW,CAAC,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,GAAG,SAAS,GACjE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,CAqCpE;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS;AAC1C;;;;;GAKG;AACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC,QAAQ,GAAG,IAAI,GACjD,cAAc,CA+DhB"}

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

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ *
+ * The seam is keyed by NODE ID (P-4), so THIS is where the three-specific
+ * `id → Object3D` step happens: once, at the implementer's own boundary,
+ * through the `resolve` function its constructor is handed. Nothing above this
+ * line — not the editor, not the seam — needs to know an `Object3D` exists.
+ */
+/**
+ * The four REQUIRED `PhysicsAdapter` members, over nothing but "which Rapier
+ * body drives this node" — the `freeze → apply → unfreeze` protocol itself,
+ * with no opinion about where the body came from.
+ *
+ * Split out of {@link createRapierPhysicsAdapter} (it is that function's own
+ * `ownerOf`/`freeze`/`commit`/`unfreeze`, unchanged) because the FIRST-PARTY
+ * mount is no longer the only Rapier in this engine: an R3F world does its
+ * physics with `@react-three/rapier` inside the fiber tree, which owns its own
+ * bodies and its own `Object3D` mapping, and reaches these same four verbs
+ * through `world3d-react/rapier-physics-bridge.tsx`. The optional members
+ * (`debugDraw`, `setDebugDrawEnabled`, `contactPoints`) are NOT here: each is
+ * answered differently by each Rapier owner, and a caller that cannot answer
+ * one honestly omits it.
+ */
+export function createRapierBodyEditing(bodyFor) {
+    /** Saved body types while frozen, so unfreeze can restore them. */
+    const frozen = new Map();
+    return {
+        ownerOf(nodeId) {
+            const body = bodyFor(nodeId);
+            if (!body)
+                return 'editor';
+            // A fixed body never moves on its own → the editor owns its transform.
+            return body.isFixed() ? 'editor' : 'physics';
+        },
+        freeze(nodeId) {
+            const body = bodyFor(nodeId);
+            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(nodeId, t) {
+            const body = bodyFor(nodeId);
+            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(nodeId) {
+            const body = bodyFor(nodeId);
+            if (!body)
+                return;
+            const prev = frozen.get(body);
+            if (prev !== undefined) {
+                body.setBodyType(prev, true);
+                frozen.delete(body);
+            }
+        },
+    };
+}
+export function createRapierPhysicsAdapter(registry, physics, 
+/**
+ * The world's own `id → Object3D` map. Injected rather than derived here so
+ * this file never hard-codes an identity convention (e.g. reading the
+ * first-party `userData.entityId` key off foreign objects, which is the
+ * ingest-stamping leak the retirement playbook deliberately parked).
+ */
+resolve) {
+    /**
+     * Reused backing store for `contactPoints` (grown ×2 on demand, never
+     * shrunk) — the seam contract says the returned view is only valid until
+     * the next call, exactly so this never allocates per frame once warm.
+     */
+    let contactBuf = new Float32Array(64 * 3);
+    let contactCount = 0;
+    const pushContact = (x, y, z) => {
+        if ((contactCount + 1) * 3 > contactBuf.length) {
+            const grown = new Float32Array(contactBuf.length * 2);
+            grown.set(contactBuf);
+            contactBuf = grown;
+        }
+        contactBuf[contactCount * 3] = x;
+        contactBuf[contactCount * 3 + 1] = y;
+        contactBuf[contactCount * 3 + 2] = z;
+        contactCount++;
+    };
+    const appendManifoldContacts = (manifold) => {
+        const count = manifold.numSolverContacts();
+        for (let i = 0; i < count; i++) {
+            // Solver contacts are WORLD-space (unlike localContactPoint1/2).
+            const p = manifold.solverContactPoint(i);
+            if (p)
+                pushContact(p.x, p.y, p.z);
+        }
+    };
+    const collectContactPoints = () => {
+        if (!physics)
+            return contactBuf.subarray(0, 0);
+        const world = physics.rapierWorld;
+        contactCount = 0;
+        for (const [, refs] of registry.entries()) {
+            world.contactPairsWith(refs.collider, (other) => {
+                // Each touching pair is enumerated from BOTH sides — process it only
+                // from the lower-handle side (also skips self).
+                if (other.handle <= refs.collider.handle)
+                    return;
+                world.contactPair(refs.collider, other, appendManifoldContacts);
+            });
+        }
+        return contactBuf.subarray(0, contactCount * 3);
+    };
+    /** The one place this adapter crosses from node id into Three's vocabulary. */
+    const bodyFor = (nodeId) => {
+        const o = resolve(nodeId);
+        return o ? registry.get(o)?.body : undefined;
+    };
+    return {
+        ...createRapierBodyEditing(bodyFor),
+        debugDraw: () => physics?.debugMesh ?? null,
+        setDebugDrawEnabled(enabled) {
+            if (!physics)
+                return;
+            // Same two fields the in-game KeyP toggle flips — the adapter's render
+            // system reads `debugEnabled` and feeds `debugRender()` into the mesh.
+            physics.debugEnabled = enabled;
+            physics.debugMesh.visible = enabled;
+        },
+        contactPoints: collectContactPoints,
+    };
+}