@vgai/engine 0.5.13 → 0.5.14

package/dist/adapter/ingest/visible-capture-window.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The capture window is a budget of VISIBLE time, not of wall-clock time.
+ *
+ * WHY THIS MODULE EXISTS. An ingest mount waits for the game to render its
+ * first frame and fails by name when that never happens
+ * (`scene-capture.ts`'s `waitForCapture`). That wait used to be a plain
+ * `setTimeout`, i.e. a wall-clock deadline started AT BOOT — and a game cannot
+ * render while its tab is hidden, because the browser parks `requestAnimation
+ * Frame` for a backgrounded document. The two facts together make one
+ * deterministic failure: a tab that opens in the BACKGROUND (the normal human
+ * path — `vgai edit` auto-opens a tab that routinely lands behind the current
+ * window) burns its whole capture window unable to draw, the deadline fires,
+ * the mount dies terminally, and foregrounding the tab later changes nothing.
+ * Agents, whose tabs happen to be visible, never saw it.
+ *
+ * So the clock only runs while the document is VISIBLE. Hidden time is not
+ * spent, and while a tab is hidden the wait PARKS rather than expiring: the
+ * capture trap stays installed, the game's modules stay live, and the first
+ * frame the tab draws after the human brings it forward is trapped exactly as
+ * it would have been at boot. That is the retry — no second mount, no
+ * re-running `load()` (which would re-construct module-level state: the
+ * ARCHITECTURE-CORE "LOADING CONSTRUCTS, once" contract), and no forcing of a
+ * frame: the game's own loop resumes on its own when the browser un-parks it.
+ *
+ * There is deliberately no wall-clock cap on the parked state. An unspent
+ * budget is not a failure — a human returning to the tab is what spends it —
+ * and a cap would be exactly the boot-time clock this module exists to
+ * remove. The parked wait is reported instead of being silent: see
+ * `CaptureWaitObserver` in `scene-capture.ts` and `vgai status`'s
+ * `ingestCaptureWait`.
+ *
+ * The state machine is a pure function of (banked segments, now, hidden) so
+ * the whole accrual rule is testable with no browser and no timers
+ * (`packages/engine/test/visible-capture-window.test.ts`); the runtime half
+ * below is only the timer arm/disarm around it.
+ */
+/**
+ * Everything the budget reads about the outside world. Injected so the pure
+ * core stays pure and the runtime half is drivable by a fake in tests — and,
+ * as a side effect, so this module never hard-depends on `document` existing
+ * (unit runners, SSR).
+ */
+export interface VisibilityClock {
+    /** Milliseconds, monotonic-ish; `performance.now()`/`Date.now()` both fit. */
+    now(): number;
+    /** True while the document is hidden (no rAF, so no frame can be captured). */
+    hidden(): boolean;
+    /** Subscribe to visibility transitions; returns the unsubscribe. */
+    subscribe(onChange: () => void): () => void;
+}
+/** The real one: `document.visibilityState` + `visibilitychange`. Falls back
+ *  to permanently-visible where there is no `document` at all, which is the
+ *  honest answer for a headless caller — it has no tab to background. */
+export declare function documentVisibilityClock(): VisibilityClock;
+/**
+ * The banked halves of the wait plus the segment currently running. Immutable:
+ * every transition returns a new value, so a caller can hold one and compare.
+ */
+export interface VisibleBudgetState {
+    /** The window, in VISIBLE milliseconds. */
+    readonly budgetMs: number;
+    /** Visible time banked from completed segments. */
+    readonly visibleMs: number;
+    /** Hidden time banked from completed segments (reported, never spent). */
+    readonly hiddenMs: number;
+    /** When the current segment started. */
+    readonly since: number;
+    /** Whether the current segment is a hidden one. */
+    readonly hidden: boolean;
+}
+/** Open the window at `now`, in whichever visibility the document is in. */
+export declare function beginVisibleBudget(budgetMs: number, now: number, hidden: boolean): VisibleBudgetState;
+/**
+ * Apply the document's current visibility at `now`: bank the segment that just
+ * ended into its own bucket and start the next one. A call that does not change
+ * visibility is a no-op *by value* (same accrual, same segment start), so a
+ * duplicate `visibilitychange` can never bank a zero-length segment twice or
+ * restart the clock.
+ */
+export declare function applyVisibility(state: VisibleBudgetState, now: number, hidden: boolean): VisibleBudgetState;
+/** Visible time spent so far, including the segment in flight. */
+export declare function visibleElapsedMs(state: VisibleBudgetState, now: number): number;
+/** Hidden time so far, including the segment in flight. Never spent — it is
+ *  reported so a failure message can say what the window did NOT count. */
+export declare function hiddenElapsedMs(state: VisibleBudgetState, now: number): number;
+/** Visible time left in the window; `0` once it is spent. */
+export declare function visibleRemainingMs(state: VisibleBudgetState, now: number): number;
+/** A live view of one running window, for the status wire and the failure message. */
+export interface VisibleCaptureWindow {
+    /** The window's size, in visible milliseconds. */
+    readonly budgetMs: number;
+    /** Visible milliseconds spent so far. */
+    elapsedVisibleMs(): number;
+    /** Milliseconds this window has spent parked while hidden (not counted). */
+    elapsedHiddenMs(): number;
+    /** Whether the wait is parked right now because the document is hidden. */
+    isHidden(): boolean;
+    /** Stop the timer and drop the visibility listener. Idempotent. */
+    cancel(): void;
+}
+/**
+ * Start a window that calls `onExpire` after `budgetMs` of VISIBLE time.
+ * While the document is hidden the timer is disarmed entirely (so a throttled
+ * background timer cannot fire it late either) and re-armed with the remaining
+ * budget when the document comes back.
+ */
+export declare function startVisibleCaptureWindow(opts: {
+    budgetMs: number;
+    onExpire: () => void;
+    /** Defaults to the document's own visibility. */
+    clock?: VisibilityClock;
+    /** Defaults to `setTimeout`/`clearTimeout`. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}): VisibleCaptureWindow;
+//# sourceMappingURL=visible-capture-window.d.ts.map

package/dist/adapter/ingest/visible-capture-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-capture-window.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/visible-capture-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,IAAI,MAAM,CAAC;IACd,+EAA+E;IAC/E,MAAM,IAAI,OAAO,CAAC;IAClB,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED;;yEAEyE;AACzE,wBAAgB,uBAAuB,IAAI,eAAe,CAWzD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,GACd,kBAAkB,CAEpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,GACd,kBAAkB,CAUpB;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,gBAAgB,IAAI,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,eAAe,IAAI,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,IAAI,OAAO,CAAC;IACpB,mEAAmE;IACnE,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,iDAAiD;IACjD,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC,GAAG,oBAAoB,CAmDvB"}

package/dist/adapter/ingest/visible-capture-window.js

@@ -0,0 +1,141 @@
+/**
+ * The capture window is a budget of VISIBLE time, not of wall-clock time.
+ *
+ * WHY THIS MODULE EXISTS. An ingest mount waits for the game to render its
+ * first frame and fails by name when that never happens
+ * (`scene-capture.ts`'s `waitForCapture`). That wait used to be a plain
+ * `setTimeout`, i.e. a wall-clock deadline started AT BOOT — and a game cannot
+ * render while its tab is hidden, because the browser parks `requestAnimation
+ * Frame` for a backgrounded document. The two facts together make one
+ * deterministic failure: a tab that opens in the BACKGROUND (the normal human
+ * path — `vgai edit` auto-opens a tab that routinely lands behind the current
+ * window) burns its whole capture window unable to draw, the deadline fires,
+ * the mount dies terminally, and foregrounding the tab later changes nothing.
+ * Agents, whose tabs happen to be visible, never saw it.
+ *
+ * So the clock only runs while the document is VISIBLE. Hidden time is not
+ * spent, and while a tab is hidden the wait PARKS rather than expiring: the
+ * capture trap stays installed, the game's modules stay live, and the first
+ * frame the tab draws after the human brings it forward is trapped exactly as
+ * it would have been at boot. That is the retry — no second mount, no
+ * re-running `load()` (which would re-construct module-level state: the
+ * ARCHITECTURE-CORE "LOADING CONSTRUCTS, once" contract), and no forcing of a
+ * frame: the game's own loop resumes on its own when the browser un-parks it.
+ *
+ * There is deliberately no wall-clock cap on the parked state. An unspent
+ * budget is not a failure — a human returning to the tab is what spends it —
+ * and a cap would be exactly the boot-time clock this module exists to
+ * remove. The parked wait is reported instead of being silent: see
+ * `CaptureWaitObserver` in `scene-capture.ts` and `vgai status`'s
+ * `ingestCaptureWait`.
+ *
+ * The state machine is a pure function of (banked segments, now, hidden) so
+ * the whole accrual rule is testable with no browser and no timers
+ * (`packages/engine/test/visible-capture-window.test.ts`); the runtime half
+ * below is only the timer arm/disarm around it.
+ */
+/** The real one: `document.visibilityState` + `visibilitychange`. Falls back
+ *  to permanently-visible where there is no `document` at all, which is the
+ *  honest answer for a headless caller — it has no tab to background. */
+export function documentVisibilityClock() {
+    const doc = typeof document === 'undefined' ? null : document;
+    return {
+        now: () => (typeof performance === 'undefined' ? Date.now() : performance.now()),
+        hidden: () => doc?.hidden === true,
+        subscribe(onChange) {
+            if (!doc)
+                return () => { };
+            doc.addEventListener('visibilitychange', onChange);
+            return () => doc.removeEventListener('visibilitychange', onChange);
+        },
+    };
+}
+/** Open the window at `now`, in whichever visibility the document is in. */
+export function beginVisibleBudget(budgetMs, now, hidden) {
+    return { budgetMs, visibleMs: 0, hiddenMs: 0, since: now, hidden };
+}
+/**
+ * Apply the document's current visibility at `now`: bank the segment that just
+ * ended into its own bucket and start the next one. A call that does not change
+ * visibility is a no-op *by value* (same accrual, same segment start), so a
+ * duplicate `visibilitychange` can never bank a zero-length segment twice or
+ * restart the clock.
+ */
+export function applyVisibility(state, now, hidden) {
+    if (hidden === state.hidden)
+        return state;
+    const elapsed = Math.max(0, now - state.since);
+    return {
+        budgetMs: state.budgetMs,
+        visibleMs: state.hidden ? state.visibleMs : state.visibleMs + elapsed,
+        hiddenMs: state.hidden ? state.hiddenMs + elapsed : state.hiddenMs,
+        since: now,
+        hidden,
+    };
+}
+/** Visible time spent so far, including the segment in flight. */
+export function visibleElapsedMs(state, now) {
+    return state.visibleMs + (state.hidden ? 0 : Math.max(0, now - state.since));
+}
+/** Hidden time so far, including the segment in flight. Never spent — it is
+ *  reported so a failure message can say what the window did NOT count. */
+export function hiddenElapsedMs(state, now) {
+    return state.hiddenMs + (state.hidden ? Math.max(0, now - state.since) : 0);
+}
+/** Visible time left in the window; `0` once it is spent. */
+export function visibleRemainingMs(state, now) {
+    return Math.max(0, state.budgetMs - visibleElapsedMs(state, now));
+}
+/**
+ * Start a window that calls `onExpire` after `budgetMs` of VISIBLE time.
+ * While the document is hidden the timer is disarmed entirely (so a throttled
+ * background timer cannot fire it late either) and re-armed with the remaining
+ * budget when the document comes back.
+ */
+export function startVisibleCaptureWindow(opts) {
+    const clock = opts.clock ?? documentVisibilityClock();
+    const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+    let state = beginVisibleBudget(opts.budgetMs, clock.now(), clock.hidden());
+    let timer = null;
+    let done = false;
+    function disarm() {
+        if (timer !== null) {
+            clearTimer(timer);
+            timer = null;
+        }
+    }
+    function arm() {
+        disarm();
+        if (done || state.hidden)
+            return;
+        timer = setTimer(() => {
+            timer = null;
+            if (done)
+                return;
+            done = true;
+            unsubscribe();
+            opts.onExpire();
+        }, visibleRemainingMs(state, clock.now()));
+    }
+    const unsubscribe = clock.subscribe(() => {
+        if (done)
+            return;
+        state = applyVisibility(state, clock.now(), clock.hidden());
+        arm();
+    });
+    arm();
+    return {
+        budgetMs: opts.budgetMs,
+        elapsedVisibleMs: () => visibleElapsedMs(state, clock.now()),
+        elapsedHiddenMs: () => hiddenElapsedMs(state, clock.now()),
+        isHidden: () => state.hidden,
+        cancel() {
+            if (done)
+                return;
+            done = true;
+            disarm();
+            unsubscribe();
+        },
+    };
+}

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) on
+ * its own: 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
@@ -10,8 +10,7 @@
  * 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
+ * Pure compute + message-formatting — 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

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

@@ -1 +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"}
+{"version":3,"file":"loop-gate-report.d.ts","sourceRoot":"","sources":["../../src/adapter/loop-gate-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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,7 +1,7 @@
 /**
  * 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
+ * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) on
+ * its own: 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
@@ -10,8 +10,7 @@
  * 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
+ * Pure compute + message-formatting — 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

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

@@ -24,6 +24,7 @@
  */
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
+import type { WorldRendererConfig } from '../world3d-react/renderer-config';
 import type { AdapterSurface } from './adapter-surface';
 import type { AuthoringAdapter } from './authoring';
 import type { HostContextFor } from './host-context';
@@ -75,8 +76,8 @@ export interface MountedRootBase {
      *    not a promise: implement `setPaused`/`step` only where the game exposes
      *    a sanctioned pause/step mechanism. Gating a raw-rAF loop from outside
      *    was demonstrated and REJECTED (D5 — it halts the loop rather than
-     *    pausing it); such games are the "composited, unsynchronized" tier:
-     *    `setPaused` absent, host degrades loudly (T7.6 owns the tier surface).
+     *    pausing it). Where `setPaused` is absent the host reports the
+     *    shortfall loudly, naming the mechanism that would close it (T7.6).
      */
     readonly drivesOwnLoop: boolean;
     update?(dt: number): void;
@@ -105,6 +106,25 @@ export interface MountedThreeRoot extends MountedRootBase {
     /** The live scene + camera the editor inspects/renders for authoring. */
     readonly scene: THREE.Scene;
     readonly camera: THREE.Camera;
+    /**
+     * The colour pipeline this world was authored for, REPORTED rather than
+     * applied — the adapter has already applied it to the renderer its own host
+     * handed it (`world3d-react/renderer-config.ts`).
+     *
+     * It is here because the host that MOUNTS a world is not always the host
+     * that DRAWS it. The editor's design session mounts against a
+     * non-rasterizing renderer on purpose and then draws the mounted scene with
+     * the editor viewport's own `WebGLRenderer`, so the world's declaration
+     * lands on a surface with no pixels while the surface with pixels never
+     * hears it. Reporting the declaration is what lets that host apply the same
+     * config, through the same `applyWorldRendererConfig`, to the renderer that
+     * actually produces the frame.
+     *
+     * Absent means the world declared nothing and the drawing host should leave
+     * its own configuration alone — the same "absent = don't touch" rule the
+     * config's own fields follow.
+     */
+    readonly rendererConfig?: WorldRendererConfig | undefined;
 }
 /** A live, mounted canvas world (T7.3) — the pixi analog of
  *  {@link MountedThreeRoot}. `stage` is the pixi world container the host

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/setup-three-root-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-three-root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/setup-three-root-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAmCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAO/F,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGpE,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,qBAAsB,YAAW,WAAW;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,oBAAyB;IAKxD,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAu0BpE"}
+{"version":3,"file":"setup-three-root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/setup-three-root-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAoCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAO/F,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGpE,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,qBAAsB,YAAW,WAAW;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,oBAAyB;IAKxD,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAs1BpE"}

package/dist/adapter/setup-three-root-adapter.js

@@ -40,6 +40,7 @@ import { createCollisionSystem } from '../physics/collision-system';
 import { createPhysicsRegistry } from '../physics/physics-registry';
 import { createTransformWriter } from '../physics/transform-writer';
 import { updateSceneLODs } from '../render/lod';
+import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
 import { disposeSparkRendererWhenIdle, SPARK_DISCOVERY_INTERVAL_MS, sceneHasGaussianSplat, shouldDiscoverGaussianSplat, } from '../render/spark-renderer-lifecycle';
 import { ViewportShadingRenderer } from '../render/viewport-shading';
 import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
@@ -125,6 +126,10 @@ export class SetupThreeRootAdapter {
         const audio = headless ? headlessAudio() : setupAudio(camera);
         // --- Particles (three.quarks BatchedRenderer) ---
         const particles = setupParticles(scene);
+        // Scene depth for any soft-particle system registered against this world.
+        // Inert (not one traversal, not one draw) until `registerParticleSystem`
+        // arms it — see `../render/soft-particle-depth.ts`.
+        const softParticleDepth = createSoftParticleDepthPass();
         // --- Debug draw / assets ---
         const debugDraw = createDebugDraw(scene);
         const assets = host.assets;
@@ -218,6 +223,13 @@ export class SetupThreeRootAdapter {
                 // the assembled capture to a pending captureFrame() and restores the
                 // patched context — in the SAME finally as gpuTimer.end(). Spark is
                 // added before this so its draws fall inside the captured frame.
+                // Soft-particle scene depth goes in FRONT of the frame's own draw:
+                // the fade samples the geometry behind the particle, which cannot be
+                // the depth attachment the particle is drawn into. Deliberately
+                // OUTSIDE the capture and profiler brackets below — it is a prepass,
+                // not part of the frame's presentation, and a captured frame should
+                // show the draws the user sees.
+                softParticleDepth.render(renderer, scene, camera);
                 renderDebugWiring?.beforeRender();
                 // Issue #1504: CPU render submission, bracketed as its OWN profiler
                 // phase nested inside the frame's enclosing `render` phase. This is
@@ -720,6 +732,9 @@ export class SetupThreeRootAdapter {
                 renderVitals?.dispose();
                 renderVitals = null;
             });
+            // This mount created the depth pass, so this mount ends it — the render
+            // target it holds is drawing-buffer sized and nothing else can reach it.
+            safeStep('softParticleDepth.dispose', () => softParticleDepth.dispose());
             // Release analyser taps BEFORE the audio teardown below. A consumer
             // (the editor's meter poll) should dispose its own handle, but Stop must
             // never leak taps regardless.

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

@@ -13,7 +13,58 @@
 import type * as THREE from 'three';
 import type { RenderMemorySnapshot } from '../dev/render-memory';
 import type { FrameCapture } from '../dev/webgl-frame-capture';
+import type { PhysicsAdapter2D } from '../pixi/system-adapters';
 import type { Transform, TransformOwner } from './transform';
+export type PhysicsColliderShape = {
+    readonly type: 'cuboid';
+    readonly halfExtents: readonly [number, number, number];
+} | {
+    readonly type: 'ball';
+    readonly radius: number;
+} | {
+    readonly type: 'capsule';
+    readonly halfHeight: number;
+    readonly radius: number;
+};
+/** Plain-data projection of one native 3D physics collider. The owning
+ * physics implementation keeps the actual collider; editor authoring only
+ * receives the geometry needed to inspect and draw it. */
+export interface PhysicsColliderSnapshot {
+    readonly id: string;
+    readonly shape: PhysicsColliderShape;
+    readonly position: readonly [number, number, number];
+    readonly rotation: readonly [number, number, number, number];
+    /** Absolute world scale used when the native shape was created. Source
+     * dimensions divide by this to recover @react-three/rapier's local args. */
+    readonly scale: readonly [number, number, number];
+    readonly sensor: boolean;
+}
+export type PhysicsJointType = 'fixed' | 'spherical' | 'revolute' | 'prismatic' | 'rope' | 'spring' | 'generic';
+/** Plain-data projection of one native 3D impulse joint. Anchors are exposed
+ * in both native body-local space (for persistence) and world space (for
+ * viewport instruments); the actual joint remains owned by the physics lib. */
+export interface PhysicsJointSnapshot {
+    readonly id: string;
+    readonly type: PhysicsJointType;
+    readonly body1: string;
+    readonly body2: string;
+    readonly anchor1: readonly [number, number, number];
+    readonly anchor2: readonly [number, number, number];
+    readonly worldAnchor1: readonly [number, number, number];
+    readonly worldAnchor2: readonly [number, number, number];
+    readonly body1Position: readonly [number, number, number];
+    readonly body2Position: readonly [number, number, number];
+    readonly body1Rotation: readonly [number, number, number, number];
+    readonly body2Rotation: readonly [number, number, number, number];
+    /** The free axis in body-1 local/world space for revolute/prismatic joints. */
+    readonly axis?: readonly [number, number, number];
+    readonly worldAxis?: readonly [number, number, number];
+    readonly limits?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly contactsEnabled: boolean;
+}
 /**
  * Physics coordination so the editor can stably edit an object a simulation
  * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
@@ -22,11 +73,36 @@ import type { Transform, TransformOwner } from './transform';
  * Object3D keying made this seam structurally unreachable for any non-three
  * world: a Pixi or React world could never expose a physics inspector, because
  * the seam spoke a vocabulary it has no values in — which is why the Pixi
- * surface grew a parallel `PhysicsAdapter2D` (`pixi/system-adapters.ts`)
+ * surface grew a parallel {@link PhysicsAdapter2D} (`pixi/system-adapters.ts`)
  * instead of implementing this. Substrate-specific resolution (id → the native
  * object) is the IMPLEMENTER's job, done once at its own boundary.
+ *
+ * ## `keyedBy`, and why the physics slot's union is TAGGED
+ *
+ * `SystemAdapters['physics']` holds EITHER shape ({@link PhysicsCarrier}),
+ * because a carrier addresses the thing being edited in its surface's own
+ * vocabulary and the canvas lane's is the display object itself. But the two
+ * shapes carry the SAME four member names and are otherwise indistinguishable
+ * at runtime, while the registry that holds them
+ * (`editor/src/authoring/active-systems.ts`) is GAME-scoped and surface-blind —
+ * one object every editor panel reads. An untagged union would therefore be one
+ * nothing could narrow, and every three-lane consumer
+ * (`getActivePhysics()?.freeze(nodeId)`, `play-mode.ts`'s `physics.commit(id,
+ * transform)`) would have to reach it through a cast asserting a fact nobody
+ * checked.
+ *
+ * So `keyedBy` is a real discriminant, and it is REQUIRED on
+ * {@link PhysicsAdapter2D} while OPTIONAL here on purpose: node-id keying is
+ * this seam's original and — until the canvas lane — only vocabulary, so every
+ * existing implementer stays valid untouched, and the shape that needs telling
+ * apart is the one obliged to say so. {@link nodeKeyedPhysics} /
+ * {@link displayKeyedPhysics} are the two narrowings; nothing else should test
+ * the tag by hand.
  */
 export interface PhysicsAdapter {
+    /** Optional tag; see the interface comment. `'node-id'` is the only value,
+     *  and omitting it means the same thing. */
+    readonly keyedBy?: 'node-id';
     /** Returns `'physics'` when a body drives this node, else another owner. */
     ownerOf(nodeId: string): TransformOwner;
     /** Pause the body driving `nodeId` (kinematic / sleep / detach) for editing. */
@@ -51,6 +127,17 @@ export interface PhysicsAdapter {
      * geometry).
      */
     contactPoints?(): Float32Array;
+    /** Optional native collider inspection for one authored node. Implementers
+     * return only shapes they can describe exactly; absence means the editor
+     * offers no collider component UI. */
+    colliders?(nodeId: string): readonly PhysicsColliderSnapshot[];
+    /** Optional gesture preview against the implementation's real collider.
+     * Source persistence remains the AuthoringAdapter's responsibility. */
+    previewCollider?(colliderId: string, shape: PhysicsColliderShape): void;
+    /** Optional native impulse-joint inspection for joints attached to one node. */
+    joints?(nodeId: string): readonly PhysicsJointSnapshot[];
+    /** Optional gesture preview against the implementation's real local anchor. */
+    previewJointAnchor?(jointId: string, endpoint: 0 | 1, anchor: readonly [number, number, number]): void;
 }
 export interface NetPeer {
     id: string;
@@ -347,10 +434,67 @@ export interface AudioAdapter {
      *  environment cannot meter (headless world with no real AudioContext) —
      *  the UI says so rather than showing frozen zeros. */
     acquireMeters?(): AudioMeterHandle | null;
+    /** Optional: tap the real mixed output for a gameplay recording. The
+     * returned stream is the implementation's native browser audio stream; the
+     * caller must dispose the tap when recording ends. Absence means video can
+     * still be recorded, honestly without an audio track. */
+    acquireRecordingStream?(): AudioRecordingHandle | null;
     /** Optional: the audio event ring (bounded, drops oldest). `sinceSeq`
      *  filters to `seq > sinceSeq` — the consumer's fence. */
     audioEvents?(sinceSeq?: number): AudioDebugEvent[];
 }
+/** One temporary tap of an audio adapter's mixed output. */
+export interface AudioRecordingHandle {
+    readonly stream: MediaStream;
+    dispose(): void;
+}
+/** One native camera known to a runtime camera controller.
+ *
+ * `id` is the controller's own stable key (a shot name, virtual-camera id,
+ * etc.). `nativeId` is OPTIONAL identity from the underlying scene object —
+ * Three.js implementations normally use `Object3D.uuid`; another adapter may
+ * use its renderer's equivalent. The editor uses it only to correlate an
+ * already-selected native camera with this read-only runtime projection. */
+export interface CameraRuntimeCamera {
+    id: string;
+    label: string;
+    nativeId?: string;
+    /** Optional because ownership/cut controllers do not necessarily arbitrate
+     * by priority. A camera brain that does may expose the real value it uses. */
+    priority?: number;
+    enabled?: boolean;
+}
+/** A transition the controller is evaluating now. Plain data only: no
+ * renderer camera, tween, graph node, or editor-authored state crosses the
+ * seam. */
+export interface CameraRuntimeTransition {
+    fromCameraId: string | null;
+    toCameraId: string;
+    durationSeconds: number;
+    elapsedSeconds: number;
+    progress: number;
+}
+/** Read-only runtime state for a selected native camera's Inspector section.
+ * Runtime follow/aim/collision stays project behavior; this snapshot merely
+ * reports what that behavior already decided. */
+export interface CameraRuntimeSnapshot {
+    cameras: readonly CameraRuntimeCamera[];
+    activeCameraId: string | null;
+    /** The behavior/cinematic currently allowed to drive the rendered camera. */
+    activeControllerId: string | null;
+    ownershipDepth: number;
+    transition: CameraRuntimeTransition | null;
+}
+/** Camera-controller INTROSPECTION — not a camera graph or controller API.
+ *
+ * Games continue to author ordinary native cameras and drive them with their
+ * own TS/TSX. A controller registers this adapter only when it can truthfully
+ * expose its active camera, priority and blend state. Absence hides the
+ * runtime UI; the editor never infers a brain from scene structure. */
+export interface CameraAdapter {
+    snapshot(): CameraRuntimeSnapshot;
+    subscribe(listener: () => void): Unsubscribe;
+}
 /** One tick-stamped debug event (`ctx.debug.emit`, spec §3.3): `tick`/`simT`
  *  are the engine's own counters AT EMISSION, so events and state reads
  *  correlate frame-exactly across every door (in-page bridge, relay, panels).
@@ -438,15 +582,30 @@ export interface RenderDebugAdapter {
     captureFrame(): Promise<FrameCapture>;
     memorySnapshot?(): RenderMemorySnapshot;
 }
+/**
+ * A physics carrier in EITHER surface's vocabulary — node-id keyed for a three
+ * world, display-object keyed for a canvas one. Tagged by `keyedBy`; see
+ * {@link PhysicsAdapter}'s comment for why, and use the two narrowings below
+ * rather than reading the tag directly.
+ */
+export type PhysicsCarrier = PhysicsAdapter | PhysicsAdapter2D;
+/** The carrier a NODE-ID-keyed consumer may call, or `null` — including when
+ *  the slot holds a display-keyed carrier, which such a consumer must not
+ *  call and cannot correctly address. */
+export declare function nodeKeyedPhysics(carrier: PhysicsCarrier | null | undefined): PhysicsAdapter | null;
+/** The carrier a DISPLAY-keyed consumer may call, or `null`. Mirror of
+ *  {@link nodeKeyedPhysics}. */
+export declare function displayKeyedPhysics(carrier: PhysicsCarrier | null | undefined): PhysicsAdapter2D | null;
 /**
  * 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;
+    physics?: PhysicsCarrier;
     networking?: NetworkingAdapter;
     navigation?: NavigationAdapter;
     audio?: AudioAdapter;
+    camera?: CameraAdapter;
     debug?: DebugAdapter;
     renderDebug?: RenderDebugAdapter;
 }