@voltro/plugin-rooms 0.0.0-stage → 0.88.0

package/dist/ports.js

@@ -0,0 +1,10 @@
+import { roomsSystemContractManifest as e } from "./systemManifest.js";
+import { RoomReplayPort as t } from "./replayPorts.js";
+import { RoomHostDrainPort as n } from "./hostDrainPorts.js";
+import { RoomLockstepJournalPort as r } from "./lockstepJournalPorts.js";
+import { RoomLockstepAdmissionPort as i } from "./lockstepAdmissionPorts.js";
+import { RoomLockstepTerminalPort as a } from "./lockstepTerminalPorts.js";
+import { Context as o } from "effect";
+// src/ports.ts
+var s = class extends o.Service()("@voltro/WorldClientControlPort") {}, c = class extends o.Service()("@voltro/RoomReservePort") {}, l = class extends o.Service()("@voltro/RoomSubjectPrivacyPort") {}, u = class extends o.Service()("@voltro/RoomCheckpointPort") {}, d = class extends o.Service()("@voltro/RoomSnapshotBlobPort") {}, f = class extends o.Service()("@voltro/RoomDirectoryPort") {}, p = class extends o.Service()("@voltro/RoomAppCommandPort") {}, m = class extends o.Service()("@voltro/RoomRecoveryPort") {}, h = class extends o.Service()("@voltro/RoomHostAdoptionPort") {}, g = class extends o.Service()("@voltro/RoomHostControlPort") {}, _ = class extends o.Service()("@voltro/RoomHostWithdrawalPort") {}, v = class extends o.Service()("@voltro/RoomHostKickPort") {}, y = class extends o.Service()("@voltro/RoomExternalWorkWithdrawalPort") {}, b = class extends o.Service()("@voltro/RoomErasurePort") {}, x = class extends o.Service()("@voltro/RoomReaperPort") {};
+export { p as RoomAppCommandPort, u as RoomCheckpointPort, f as RoomDirectoryPort, b as RoomErasurePort, y as RoomExternalWorkWithdrawalPort, h as RoomHostAdoptionPort, g as RoomHostControlPort, n as RoomHostDrainPort, v as RoomHostKickPort, _ as RoomHostWithdrawalPort, i as RoomLockstepAdmissionPort, r as RoomLockstepJournalPort, a as RoomLockstepTerminalPort, x as RoomReaperPort, m as RoomRecoveryPort, t as RoomReplayPort, c as RoomReservePort, d as RoomSnapshotBlobPort, l as RoomSubjectPrivacyPort, s as WorldClientControlPort, e as roomsSystemContractManifest };

package/dist/quaternion.js

@@ -0,0 +1,69 @@
+import { ProtocolError as e, RoomAuthoringError as t } from "./errors.js";
+import { Result as n } from "effect";
+// src/quaternion.ts
+var r = [
+	"qx",
+	"qy",
+	"qz",
+	"qw"
+], i = (e) => {
+	if (!Number.isSafeInteger(e) || e < 4 || e > 20) throw new t({
+		room: "quaternion",
+		detail: "Smallest-three bits must be between four and twenty"
+	});
+	return e;
+}, a = (e = 10) => Math.ceil((2 + 3 * i(e)) / 8);
+function o(t) {
+	throw new e({ detail: t });
+}
+var s = (t) => {
+	try {
+		return n.succeed(t());
+	} catch (t) {
+		return n.fail(t instanceof e ? t : new e({ detail: "Invalid quaternion representation" }));
+	}
+}, c = (e, t = 10) => (i(t), s(() => {
+	let n = r.map((t) => e[t]);
+	n.some((e) => typeof e != "number" || !Number.isFinite(e)) && o("Quaternion components must be finite");
+	let i = Math.max(...n.map(Math.abs));
+	i === 0 && o("Zero quaternion has no rotation");
+	let s = Math.hypot(...n.map((e) => e / i)), c = n.map((e) => e / i / s), l = 0;
+	for (let e = 1; e < c.length; e++) Math.abs(c[e]) > Math.abs(c[l]) && (l = e);
+	let u = c[l] < 0 ? -1 : 1, d = Math.SQRT1_2, f = 2 ** t - 1, p = BigInt(l), m = 2n;
+	for (let e = 0; e < c.length; e++) {
+		if (e === l) continue;
+		let n = Math.max(0, Math.min(f, Math.round((c[e] * u + d) / (2 * d) * f)));
+		p |= BigInt(n) << m, m += BigInt(t);
+	}
+	let h = new Uint8Array(a(t));
+	for (let e = 0; e < h.length; e++) h[e] = Number(p & 255n), p >>= 8n;
+	return h;
+})), l = (e, t = 10) => (i(t), s(() => {
+	e instanceof Uint8Array && e.length === a(t) || o("Invalid quaternion byte length");
+	let n = 0n;
+	for (let t = e.length - 1; t >= 0; t--) n = n << 8n | BigInt(e[t]);
+	let r = 2 + 3 * t;
+	n >> BigInt(r) !== 0n && o("Nonzero quaternion padding");
+	let i = Number(n & 3n), s = 2 ** t - 1, c = BigInt(s), l = Math.SQRT1_2;
+	n >>= 2n;
+	let u = [
+		0,
+		0,
+		0,
+		0
+	], d = 0;
+	for (let e = 0; e < u.length; e++) {
+		if (e === i) continue;
+		let r = Number(n & c) / s * 2 * l - l;
+		n >>= BigInt(t), u[e] = r, d += r * r;
+	}
+	(!Number.isFinite(d) || d > 1) && o("Quaternion residual is not real");
+	let f = Math.sqrt(1 - d), p = 2 * l / s * 2;
+	return u.some((e) => Math.abs(e) > f + p) && o("Quaternion omitted component is not dominant"), u[i] = f, {
+		qx: u[0],
+		qy: u[1],
+		qz: u[2],
+		qw: u[3]
+	};
+}));
+export { l as decodeQuaternionSmallestThree, c as encodeQuaternionSmallestThree, a as quaternionByteLength };

package/dist/react.d.ts

@@ -0,0 +1,406 @@
+import { FunctionComponentElement } from 'react';
+import { ProviderProps } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+declare type LockstepAdvance<S> = {
+    readonly _tag: 'advanced';
+    readonly snapshot: SimulationSnapshot<S>;
+    readonly predictedPlayers: ReadonlyArray<number>;
+} | {
+    readonly _tag: 'stalled';
+    readonly tick: number;
+    readonly reason: 'inputs' | 'horizon';
+    readonly missingTick: number;
+    readonly waitingFor: ReadonlyArray<number>;
+};
+
+declare interface LockstepClientOptions<I> {
+    readonly localPlayerId: number;
+    /** Optional actual complete starting matrix; absent waits for server tick1. */
+    readonly initialInputs?: ReadonlyArray<SimulationPlayerInput<I>>;
+    /** Complete admitted roster when no starting intention matrix is supplied. */
+    readonly playerIds?: ReadonlyArray<number>;
+    readonly inputDelayTicks?: number;
+    readonly rollbackHorizonTicks?: number;
+    readonly maxFutureTicks?: number;
+    readonly maxPlayers?: number;
+    readonly maxRejectionAttempts?: number;
+    readonly inputPrediction?: LockstepInputPrediction<I>;
+    /** The local player joins a running match: it is not in `playerIds` yet and enters the
+     * roster through `join` at the tick the server announces. */
+    readonly lateJoin?: boolean;
+}
+
+declare type LockstepInputPrediction<I> = 'repeat-last' | 'none' | ((last: I, context: {
+    readonly playerId: number;
+    readonly tick: number;
+}) => I);
+
+/** PCG-XSH-RR 64/32. Numeric seeds are unsigned 32-bit; word seeds retain 64 bits.
+ * Algorithm reference: https://www.pcg-random.org/using-pcg-c-basic.html
+ * No global generator, BigInt, native dependency or implicit time/entropy seed. */
+declare class Pcg32 {
+    #private;
+    constructor(seed: Pcg32Seed, stream?: Pcg32Seed, maxRejectionAttempts?: number);
+    get maxRejectionAttempts(): number;
+    nextU32(): number;
+    /** Rejection removes modulo bias. Exhaustion consumes exactly the bounded
+     * draws and fails; it never returns a biased fallback or substitutes entropy. */
+    bounded(bound: number): number;
+    snapshot(): Pcg32Snapshot;
+    restore(offered: Pcg32Snapshot): void;
+    clone(): Pcg32;
+    /** Exact skip-ahead modulo 2^64; at most 32 iterations for this delta API. */
+    advance(delta: number): void;
+}
+
+declare type Pcg32Seed = number | Uint64Words;
+
+declare interface Pcg32Snapshot {
+    readonly stateHi: number;
+    readonly stateLo: number;
+    readonly incrementHi: number;
+    readonly incrementLo: number;
+}
+
+declare class ProtocolError extends ProtocolError_base {
+    get message(): string;
+}
+
+declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruct<"ProtocolError", {
+    readonly detail: Schema.String;
+}>, YieldableError>;
+
+declare interface RoomAnimationFramePort {
+    request(callback: (localTimeMs: number) => void): number;
+    cancel(id: number): void;
+}
+
+declare interface RoomChannel {
+    readonly schema: Schema.Codec<unknown, unknown>;
+    readonly direction: 'both' | 'server' | 'client';
+    readonly reliable: boolean;
+}
+
+declare interface RoomCodecLimits {
+    readonly maxBytes: number;
+    readonly maxCollectionLength: number;
+    readonly maxFieldId: number;
+}
+
+declare interface RoomDatagramLane {
+    readonly maxDatagramBytes: number;
+    send(frame: Uint8Array): void;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+export declare interface RoomLockstepClientObservation<S> {
+    readonly status: RoomLockstepClientSessionStatus;
+    readonly sessionId: string | null;
+    readonly epoch: number | null;
+    readonly localPlayerId: number | null;
+    readonly roster: ReadonlyArray<RoomLockstepClientRosterPlayer> | null;
+    readonly snapshot: SimulationSnapshot<S> | null;
+    readonly metrics: ReturnType<RoomLockstepClientSession<Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>>['metrics']>;
+}
+
+declare type RoomLockstepClientRosterPlayer = RoomLockstepWirePlayer;
+
+/** Browser-safe network owner over the current Room codec/transport and actual
+ * pure rollback consumer. Reliable host mapping precedes all author initialization.
+ * No SQL/Store/secret/timer or client state-submit capability is acquired. */
+declare class RoomLockstepClientSession<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    #private;
+    constructor(transport: RoomTransport, simulation: Simulation<S, I, O>, manifest: RoomWireManifest<S, I>, offered: RoomLockstepClientSessionOptions<(I)["Type"]>);
+    private work;
+    private live;
+    private current;
+    private notify;
+    subscribe(listener: () => void): () => void;
+    onMessage(channelName: string, listener: (payload: unknown) => void): () => void;
+    get status(): RoomLockstepClientSessionStatus;
+    get failure(): ProtocolError | null;
+    get id(): string | null;
+    get epoch(): number | null;
+    roster(): ReadonlyArray<RoomLockstepClientRosterPlayer> | null;
+    /** Start roster plus joins effective by `tick`, in slot order (the wire matrix order). */
+    private rosterAt;
+    get localPlayerId(): number | null;
+    snapshot(): SimulationSnapshot<S["Type"]> | null;
+    /** Stable read identity between actual notifications, suitable for React's
+     * external-store contract. Owns no timer or native connection. */
+    observation(): RoomLockstepClientObservation<(S)["Type"]>;
+    metrics(): Readonly<{
+        status: RoomLockstepClientSessionStatus;
+        tick: number | null;
+        confirmedThroughTick: number | null;
+        catchUpTicks: number;
+        pendingWrites: number;
+        pendingIntent: boolean;
+        retainedLocalInputs: number;
+        retainedHashClaims: number;
+        stalls: number;
+        resyncs: number;
+        hashFlags: number;
+        waitingFor: Uint64Words | null;
+        observerErrors: number;
+        rollbackReplays: number;
+        rollbackSteps: number;
+    }>;
+    private encode;
+    private write;
+    start(token: Uint8Array): Promise<void>;
+    /** The existing Room message wire is separate from authoritative intentions. */
+    message(channelName: string, payload: unknown): Promise<void>;
+    private receive;
+    private prune;
+    advance(): LockstepAdvance<(S)["Type"]>;
+    sendIntent(input: (I)["Type"]): Promise<void>;
+    private deliverIntent;
+    /** A reliable write handed to the transport now, in order; `accepted` when the transport took it. */
+    private handOff;
+    sendInitialIntents(input?: (I)["Type"]): Promise<void>;
+    resendRetainedIntent(): Promise<void>;
+    retryIntent(): Promise<void>;
+    sendHash(tick: number): Promise<void>;
+    private release;
+    close(): void;
+    closeAsync(): Promise<void>;
+    settled(): Promise<void>;
+}
+
+declare interface RoomLockstepClientSessionOptions<I> extends Omit<LockstepClientOptions<I>, 'playerIds' | 'localPlayerId'> {
+    /** Optional expected identity; actual admission always comes from reliable LsStart. */
+    readonly localPlayerId?: number;
+    readonly roster?: ReadonlyArray<RoomLockstepClientRosterPlayer>;
+    readonly redundantInputs?: number;
+    readonly hashEvery?: number;
+    /** Retains actual immutable claim provenance independently of rollback state. */
+    readonly hashHistoryTicks?: number;
+    readonly maxPendingWrites?: number | undefined;
+    readonly maxFrameBytes?: number;
+    /** Work budget for reliable actual input-history bootstrap, not a load claim. */
+    readonly maxBootstrapTicks?: number;
+}
+
+declare type RoomLockstepClientSessionStatus = 'connecting' | 'waitingStart' | 'joined' | 'stalled' | 'left' | 'kicked' | 'faulted';
+
+/** Public opaque simulation identities, never Subjects or Session credentials. */
+declare interface RoomLockstepWirePlayer {
+    readonly slot: number;
+    readonly playerId: number;
+}
+
+export declare interface RoomOwnTransformView2D {
+    render(): Transform2D;
+}
+
+declare interface RoomReliableLane {
+    send(frame: Uint8Array): Promise<void>;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+/** Plain mutable state; the author receives no store or database capability. */
+declare type RoomState<A> = A extends ReadonlyArray<infer V> ? Array<RoomState<V>> : A extends object ? {
+    -readonly [K in keyof A]: RoomState<A[K]>;
+} : A;
+
+declare interface RoomTransformFrame2D {
+    readonly localTimeMs: number;
+    readonly serverTimeMs: number | null;
+    readonly entities: ReadonlyArray<{
+        readonly id: string;
+        readonly sample: RoomTransformSample2D;
+    }>;
+}
+
+export declare interface RoomTransformFrameHookOptions extends RoomTransformHookOptions {
+    readonly view?: RoomTransformView2D;
+}
+
+export declare interface RoomTransformHookHandle {
+    readonly error: unknown;
+    /** Drain cleanup work; does not close a borrowed source or hide render errors. */
+    settled(): Promise<void>;
+    retryCleanup(): Promise<void>;
+}
+
+export declare interface RoomTransformHookOptions {
+    readonly frames?: RoomAnimationFramePort;
+    readonly maxRetainedLoops?: number;
+}
+
+/** Supplies a borrowed view; owns neither its subscription nor its connection. */
+export declare const RoomTransformProvider: ({ view, children }: RoomTransformProviderProps) => FunctionComponentElement<ProviderProps<RoomTransformView2D | null>>;
+
+export declare interface RoomTransformProviderProps {
+    readonly view: RoomTransformView2D;
+    readonly children?: ReactNode;
+}
+
+export declare interface RoomTransformRef<T> extends RefObject<T | null> {
+    readonly lifecycle: RoomTransformHookHandle;
+}
+
+declare interface RoomTransformSample2D {
+    readonly epoch: number;
+    readonly tick: number;
+    readonly transform: Transform2D;
+    readonly stale: boolean;
+    readonly data?: unknown;
+}
+
+declare interface RoomTransformView2D {
+    ids(): ReadonlyArray<string>;
+    renderTime(): number | null;
+    at(id: string, renderTimeMs: number): RoomTransformSample2D | null;
+}
+
+declare interface RoomTransport {
+    readonly name: 'ws' | 'wt';
+    readonly reliable: RoomReliableLane;
+    readonly unreliable?: RoomDatagramLane | undefined;
+    readonly signal: AbortSignal;
+    stats(): {
+        readonly rttMs: number | null;
+        readonly queuedBytes: number;
+        readonly droppedDatagrams: number;
+    };
+    close(code: number, reason: string): void;
+    /** When provided, joins actual parent/stream withdrawal and permits retry.
+     * Synchronous close alone does not establish native terminal evidence. */
+    closeAsync?(code: number, reason: string): Promise<void>;
+}
+
+declare interface RoomWireManifest<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>> {
+    readonly state: S;
+    readonly input: I;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+}
+
+declare interface Simulation<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly definition: SimulationDefinition<S, I, O>;
+    readonly stateCodec: SimulationStateCodec<S>;
+    readonly inputCodec: SimulationStateCodec<I>;
+    readonly optionsCodec: SimulationStateCodec<O>;
+}
+
+declare interface SimulationDefinition<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly state: S;
+    readonly input: I;
+    readonly options: O;
+    readonly init: (seed: number, options: (O)["Type"]) => (S)["Type"];
+    readonly step: (state: RoomState<(S)["Type"]>, inputs: ReadonlyArray<SimulationPlayerInput<(I)["Type"]>>, tick: number, rng: Pcg32) => (S)["Type"];
+    readonly hash?: (state: (S)["Type"]) => Uint64Words;
+    /** Late join: runs before `step` at the tick a player's input first appears (it was absent
+     * from the previous tick's inputs), in player-ID order, e.g. to spawn the player. Pure and
+     * deterministic like `step`. Start players are `init`'s job: tick 1 runs no join. */
+    readonly join?: (state: RoomState<(S)["Type"]>, playerId: number, tick: number, rng: Pcg32) => (S)["Type"];
+    readonly limits?: Partial<SimulationValueLimits>;
+}
+
+declare interface SimulationPlayerInput<I> {
+    readonly playerId: number;
+    readonly input: I;
+}
+
+declare interface SimulationSnapshot<S> {
+    readonly tick: number;
+    readonly state: S;
+    readonly rng: Pcg32Snapshot;
+    readonly hash: Uint64Words;
+}
+
+declare interface SimulationStateCodec<S extends Schema.Codec<unknown, unknown>> {
+    readonly limits: SimulationValueLimits;
+    /** Admitted capture/hash plan, not a binary Room wire schema. */
+    schemaDescription?(): string;
+    capture(value: unknown): (S)["Type"];
+    hash(value: (S)["Type"]): Uint64Words;
+}
+
+declare interface SimulationValueLimits extends RoomCodecLimits {
+    readonly maxNodes: number;
+}
+
+declare const Transform2D: Schema.Struct<{
+    readonly x: Schema.Number;
+    readonly y: Schema.Number;
+    readonly rot: Schema.Number;
+    readonly vx: Schema.optional<Schema.Number>;
+    readonly vy: Schema.optional<Schema.Number>;
+}>;
+
+declare type Transform2D = (typeof Transform2D)["Type"];
+
+/** Semantic, non-modal in-game surface. It shows actual orchestration steps,
+ * never fabricated percentage, asset completion or successful rollback. */
+export declare const TransitionScreen: ({ client, locale, showSeamless, tip, className }: TransitionScreenProps) => ReactNode;
+
+export declare interface TransitionScreenProps {
+    readonly client: WorldTransitionView;
+    readonly locale: 'en' | 'de';
+    /** Seamless operations remain invisible during ordinary gameplay. */
+    readonly showSeamless?: boolean;
+    readonly tip?: ReactNode;
+    readonly className?: string;
+}
+
+/** Exact unsigned 64-bit integer as independent 32-bit words. */
+declare interface Uint64Words {
+    readonly hi: number;
+    readonly lo: number;
+}
+
+/** Stable bound intention methods; no polling, implicit sample or state upload. */
+export declare const useLocalInput: <S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(session: RoomLockstepClientSession<S, I, O>) => Readonly<{
+    sendIntent: (input: I["Type"]) => Promise<void>;
+    sendInitialIntents: (input?: I["Type"] | undefined) => Promise<void>;
+    retryIntent: () => Promise<void>;
+    resendRetainedIntent: () => Promise<void>;
+}>;
+
+/** Observe a borrowed current network owner. Creation/start/advance/native
+ * shutdown belong to its caller; mounting and unmounting own only subscription. */
+export declare const useLockstepRoom: <S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(session: RoomLockstepClientSession<S, I, O>) => RoomLockstepClientObservation<S["Type"]>;
+
+/** Render the already-authorized prediction; this hook sends no intentions. */
+export declare const useOwnTransform: (prediction: RoomOwnTransformView2D, options?: RoomTransformHookOptions) => RoomTransformRef<Transform2D>;
+
+/** Projection equality retains the prior result across unrelated notifications.
+ * Null is the actual absence of initialized state, never an invented initial state. */
+export declare const useSimState: <S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>, T>(session: RoomLockstepClientSession<S, I, O>, selector: (state: S["Type"] | null) => T, equals?: (previous: T, next: T) => boolean) => T;
+
+/** Detached sample ref for a visible entity; animation and pose share a tick. */
+export declare const useTransform: (entityId: string, options?: RoomTransformFrameHookOptions) => RoomTransformRef<RoomTransformSample2D>;
+
+/** One ref/callback frame lifetime; no React state update on animation ticks. */
+export declare const useTransformFrame: (callback: (frame: RoomTransformFrame2D) => void | Promise<void>, options?: RoomTransformFrameHookOptions) => RoomTransformHookHandle;
+
+export declare const useWorldTransition: (client: WorldTransitionView) => WorldClientObservation;
+
+declare interface WorldClientObservation {
+    readonly status: WorldClientStatus;
+    readonly step: WorldClientStep;
+    readonly mode: 'seamless' | 'portal' | null;
+    readonly bufferedInputs: number;
+    readonly bufferedBytes: number;
+    readonly committed: boolean;
+    readonly error: 'incomplete' | null;
+}
+
+declare type WorldClientStatus = 'idle' | 'preparing' | 'loading' | 'switching' | 'settled' | 'failed' | 'closed';
+
+declare type WorldClientStep = 'reserve' | 'connect' | 'welcome' | 'geometry' | 'assets' | 'commit' | 'cleanup' | null;
+
+export declare interface WorldTransitionView {
+    readonly observation: WorldClientObservation;
+    subscribe(listener: () => void): () => void;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+}
+
+export { }

package/dist/react.js

@@ -0,0 +1,108 @@
+import { BudgetExceeded as e, RoomAuthoringError as t } from "./errors.js";
+import { RoomAnimationFrameLoop as n, RoomTransformFrameLoop2D as r } from "./transformFrames.js";
+import { TransitionScreen as i, useWorldTransition as a } from "./worldReact.js";
+import { useLocalInput as o, useLockstepRoom as s, useSimState as c } from "./lockstepReact.js";
+import { createContext as l, createElement as u, useCallback as d, useContext as f, useEffect as p, useLayoutEffect as m, useMemo as h, useRef as g, useState as _ } from "react";
+// src/react.ts
+var v = class {
+	capacity;
+	retained = /* @__PURE__ */ new Map();
+	active = null;
+	observedError = null;
+	constructor(e) {
+		if (this.capacity = e, !Number.isSafeInteger(e) || e < 1 || e > 128) throw new t({
+			room: "transform-react",
+			detail: "Hook lifetime budget must be positive and bounded"
+		});
+	}
+	get error() {
+		return this.active?.error ?? this.observedError;
+	}
+	fail(e) {
+		this.observedError ??= e;
+	}
+	start(t) {
+		if (this.retained.size >= this.capacity) throw new e({
+			budget: "transformHookLifetimes",
+			limit: this.capacity
+		});
+		this.active = t;
+		try {
+			t.start();
+		} catch (e) {
+			throw this.fail(e), this.retire(t), e;
+		}
+	}
+	track(e) {
+		let t = {
+			task: e.close(),
+			error: null
+		};
+		this.retained.set(e, t), t.task.then(() => {
+			e.error !== null && this.fail(e.error), this.retained.get(e) === t && this.retained.delete(e);
+		}, (e) => {
+			t.error = e, this.fail(e);
+		});
+	}
+	retire(e) {
+		this.active === e && (this.active = null), this.retained.has(e) || this.track(e);
+	}
+	async settled() {
+		let e = (await Promise.allSettled([...this.retained.values()].map((e) => e.task))).flatMap((e) => e.status === "rejected" ? [e.reason] : []);
+		if (e.length) throw AggregateError(e, "Transform hook cleanup remains incomplete");
+	}
+	async retryCleanup() {
+		for (let [e, t] of this.retained) t.error !== null && this.track(e);
+		await this.settled();
+	}
+}, y = l(null), b = ({ view: e, children: t }) => u(y.Provider, { value: e }, t), x = (e, t) => {
+	let [n] = _(() => new v(t));
+	return p(() => {
+		let t;
+		try {
+			t = e(), n.start(t);
+		} catch (e) {
+			n.fail(e);
+			return;
+		}
+		return () => {
+			n.retire(t);
+		};
+	}, [e, n]), n;
+}, S = (e, n = {}) => {
+	let i = f(y), a = n.view ?? i;
+	if (a === null) throw new t({
+		room: "transform-react",
+		detail: "A transform provider or explicit view is required"
+	});
+	let o = g(e), s = n.frames;
+	return m(() => {
+		o.current = e;
+	}, [e]), x(d(() => new r(a, (e) => o.current(e), s), [a, s]), n.maxRetainedLoops ?? 16);
+}, C = (e, n = {}) => {
+	if (typeof e != "string" || !e.trim() || e.length > 191) throw new t({
+		room: "transform-react",
+		detail: "Transform entity identity must be nonempty and bounded"
+	});
+	let r = g(null), i = f(y), a = n.view ?? i;
+	m(() => {
+		r.current = null;
+	}, [e, a]);
+	let o = S((t) => {
+		r.current = t.entities.find((t) => t.id === e)?.sample ?? null;
+	}, n);
+	return h(() => Object.assign(r, { lifecycle: o }), [r, o]);
+}, w = (e, t = {}) => {
+	let r = g(null), i = t.frames;
+	m(() => {
+		r.current = null;
+	}, [e]);
+	let a = x(d(() => {
+		let t = e.render.bind(e);
+		return new n(() => {
+			r.current = structuredClone(t());
+		}, i);
+	}, [e, i]), t.maxRetainedLoops ?? 16);
+	return h(() => Object.assign(r, { lifecycle: a }), [r, a]);
+};
+export { b as RoomTransformProvider, i as TransitionScreen, o as useLocalInput, s as useLockstepRoom, w as useOwnTransform, c as useSimState, C as useTransform, S as useTransformFrame, a as useWorldTransition };

package/dist/reaper-app/rooms.reaper.workflow.server.tsx

@@ -0,0 +1,5 @@
+import type { AppContext } from '@voltro/runtime'
+import { roomReaperWorkflowExecutor } from '@voltro/plugin-rooms'
+
+/** Services come from the normal app handler/workflow runtime, not globals. */
+export default (_context: AppContext): typeof roomReaperWorkflowExecutor => roomReaperWorkflowExecutor

package/dist/reaper-app/rooms.reaper.workflow.tsx

@@ -0,0 +1,13 @@
+import { workflow } from '@voltro/workflow/define'
+import { Schema } from 'effect'
+import { RoomReaperWorkflowPayload, RoomReaperWorkflowResult, BudgetExceeded, ProtocolError } from '@voltro/plugin-rooms/rpc'
+
+/** Internal API-lane workflow. The ordinary scheduler owns firing and overlap. */
+export const RoomsReaper = workflow({ name: 'rooms.reaper', payload: RoomReaperWorkflowPayload,
+  success: RoomReaperWorkflowResult, error: Schema.Union([ProtocolError, BudgetExceeded]),
+  internal: true, controls: { guards: [{ scope: 'rooms:operate' }] },
+  idempotencyKey: ({ runKey }) => `rooms.reaper:${runKey}`,
+  singleton: { key: () => 'rooms.reaper', mode: 'skip' },
+  schedule: { cron: '*/5 * * * * *', timezone: 'UTC', onOverlap: 'skip', backfill: 'skip',
+    payload: ({ scheduledAt }) => ({ runKey: scheduledAt.toISOString(), maxPages: 128 }) },
+})