@voltro/plugin-rooms 0.0.0-stage → 0.88.0

package/dist/room.d.ts

@@ -0,0 +1,1006 @@
+import { DeclaredAccess } from '@voltro/protocol';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+
+/** Validate and detach a Room's listing; keys in a stable order so equal listings compare equal. */
+export declare const captureRoomListing: (room: string, value: unknown) => RoomListing;
+
+/** Validate and detach seat attributes; keys in a stable order so equal attributes compare equal. */
+export declare const captureRoomSeatAttributes: (room: string, value: unknown) => RoomSeatAttributes;
+
+declare type CollisionBody2D = {
+    readonly kind: 'circle';
+    readonly radius: number;
+} | {
+    readonly kind: 'aabb';
+    readonly halfWidth: number;
+    readonly halfHeight: number;
+};
+
+declare interface CollisionResult2D {
+    readonly transform: Transform2D;
+    readonly collided: ReadonlyArray<string>;
+    readonly iterations: number;
+}
+
+/** Actual default budget slot; every value is configuration, not a proof. */
+export declare const defaultRoomBudgets: (overrides?: Partial<RoomBudgets>) => RoomBudgets;
+
+export declare const defaultRoomReconnectPolicy: (options?: Partial<{
+    readonly graceMs: number;
+}>) => {
+    readonly graceMs: number;
+};
+
+/** Actual checkpoint cadence/encoding default, captured when the Room is defined.
+ * Commands, initial publication and terminal persistence bypass this cadence. */
+export declare const defaultRoomSnapshotPolicy: <S>(options?: Readonly<Partial<RoomSnapshotPolicy<S>>>) => RoomSnapshotPolicy<S>;
+
+/** Configuration only; no capacity assertion, history allocation or authority. */
+export declare const defaultRoomSpectatorPolicy: (input?: Readonly<Partial<RoomSpectatorPolicy>>) => RoomSpectatorPolicy;
+
+/** Per-client output remains detached even for the full-state default. */
+export declare const defaultRoomView: <S>(context: RoomViewContext<S>) => S;
+
+export declare function defineRoom<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(definition: RoomLockstepDefinition<S, I, O>): RoomLockstepDescriptor<S, I, O>;
+
+export declare function defineRoom<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(definition: RoomDefinition<S, I, O>): RoomDescriptor<S, I, O>;
+
+export declare function defineRoom<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(definition: RoomDefinition<S, I, O> | RoomLockstepDefinition<S, I, O>): RoomDescriptor<S, I, O> | RoomLockstepDescriptor<S, I, O>;
+
+export declare const defineRoomExtension: <S, I>(definition: RoomExtension<S, I>) => RoomExtension<S, I>;
+
+export declare const dequantize: (value: number, options: Quantization) => number;
+
+export declare const fieldId: (id: number) => <S extends Schema.Codec<unknown, unknown>>(schema: S) => S;
+
+/** Exact reduced integer ratio over admitted coordinates/differences of magnitude <= u32.
+ * Shared 2D/3D slab arithmetic; never round a fraction before comparing it. */
+declare interface FixedSlabFraction {
+    readonly numerator: number;
+    readonly denominator: number;
+}
+
+declare interface GeometryBoxOverlapOptions {
+    readonly maxTests?: number;
+}
+
+declare type GeometryChunk = GeometryTileChunk | GeometryHeightfieldChunk | GeometryShapesChunk | GeometryVoxelChunk;
+
+declare interface GeometryGridRayHit {
+    readonly kind: '2d-tiles' | '3d-voxel';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly cell: {
+        readonly x: number;
+        readonly y: number;
+        readonly z?: number;
+    };
+    /** Exact reduced infimum entry fraction on the offered segment, not a
+     * rounded contact point or a floating-point distance. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    readonly visitedCells: number;
+}
+
+declare interface GeometryGridRayOptions {
+    readonly maxVisitedCells?: number;
+}
+
+declare interface GeometryGridSweepHit {
+    readonly kind: '2d-tiles' | '3d-voxel';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly cell: {
+        readonly x: number;
+        readonly y: number;
+        readonly z?: number;
+    };
+    /** Infimum/supremum of positive-volume overlap, clipped to [0,1]. Contact
+     * alone is not an overlap; fractions are exact reduced integer ratios. */
+    readonly entry: FixedSlabFraction;
+    readonly exit: FixedSlabFraction;
+    readonly initialOverlap: boolean;
+    readonly testedCells: number;
+}
+
+/** A half-open raw box `[min, max)` on all three axes; a heightfield box needs its z extent. */
+declare interface GeometryHeightfieldBoxRaw {
+    readonly minXRaw: number;
+    readonly minYRaw: number;
+    readonly minZRaw: number;
+    readonly maxXRaw: number;
+    readonly maxYRaw: number;
+    readonly maxZRaw: number;
+}
+
+declare type GeometryHeightfieldChunk = (typeof GeometryHeightfieldChunkSchema)["Type"];
+
+declare const GeometryHeightfieldChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"2d-heightfield">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly sampleSpacingRaw: Schema.Int;
+    readonly baseHeightRaw: Schema.Int;
+    readonly heightQuantumRaw: Schema.Int;
+    readonly heights: Schema.$Array<Schema.Int>;
+}>;
+
+declare interface GeometryHeightfieldRayHit {
+    readonly kind: '2d-heightfield';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    /** The first point on the segment at or below the surface, in global raw units. */
+    readonly point: GeometryHeightfieldRayPoint;
+    /** Exact reduced position on the offered segment whose raw-grid point is `point`. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    readonly visitedSamples: number;
+}
+
+declare interface GeometryHeightfieldRayPoint {
+    readonly xRaw: number;
+    readonly yRaw: number;
+    readonly zRaw: number;
+}
+
+declare interface GeometryHeightfieldSweepHit {
+    readonly kind: '2d-heightfield';
+    /** The first box position along the path that reaches under the surface, on the raw grid. */
+    readonly box: GeometryHeightfieldBoxRaw;
+    /** Exact reduced position of `box` on the path: raw steps along the longest axis over its length. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    /** The start box already reaches under the surface (fraction 0). */
+    readonly initialOverlap: boolean;
+    /** Overlap evaluations used, coarse and refining together. */
+    readonly evaluations: number;
+}
+
+declare type GeometryKind = GeometryChunk['kind'];
+
+declare interface GeometryPersistenceScope {
+    readonly tenantId: string;
+    readonly kind: GeometryKind;
+    readonly worldId: string;
+    readonly version: string;
+    readonly layerSetId: string;
+    readonly cx: number;
+    readonly cy: number;
+    readonly cz?: number | undefined;
+}
+
+declare interface GeometryPreparedScope {
+    readonly tenantId: string;
+    readonly kind: GeometryKind;
+    readonly worldId: string;
+    readonly layerSetId: string;
+    readonly version: string;
+}
+
+declare type GeometryShape = (typeof GeometryShapeSchema)["Type"];
+
+declare interface GeometryShapeRayHit {
+    readonly kind: '3d-shapes';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    /** Native LOCAL shape; scope identifies its owning chunk. */
+    readonly shape: GeometryShape;
+    /** Encloses the exact infimum entry time; width <= 2^-52. Presentation only.
+     * Selection and ownership decisions never use these rounded bounds. */
+    readonly fractionBounds: {
+        readonly lower: number;
+        readonly upper: number;
+    };
+    readonly visitedChunks: number;
+    readonly testedShapes: number;
+}
+
+declare const GeometryShapeSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly halfXRaw: Schema.Int;
+    readonly halfYRaw: Schema.Int;
+    readonly halfZRaw: Schema.Int;
+    readonly id: Schema.String;
+    readonly xRaw: Schema.Int;
+    readonly yRaw: Schema.Int;
+    readonly zRaw: Schema.Int;
+    readonly kind: Schema.Literal<"aabb">;
+}>, Schema.Struct<{
+    readonly radiusRaw: Schema.Int;
+    readonly id: Schema.String;
+    readonly xRaw: Schema.Int;
+    readonly yRaw: Schema.Int;
+    readonly zRaw: Schema.Int;
+    readonly kind: Schema.Literal<"sphere">;
+}>]>;
+
+declare type GeometryShapesChunk = (typeof GeometryShapesChunkSchema)["Type"];
+
+declare const GeometryShapesChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"3d-shapes">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+        readonly cz: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly extentXRaw: Schema.Int;
+    readonly extentYRaw: Schema.Int;
+    readonly extentZRaw: Schema.Int;
+    readonly shapes: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly halfXRaw: Schema.Int;
+        readonly halfYRaw: Schema.Int;
+        readonly halfZRaw: Schema.Int;
+        readonly id: Schema.String;
+        readonly xRaw: Schema.Int;
+        readonly yRaw: Schema.Int;
+        readonly zRaw: Schema.Int;
+        readonly kind: Schema.Literal<"aabb">;
+    }>, Schema.Struct<{
+        readonly radiusRaw: Schema.Int;
+        readonly id: Schema.String;
+        readonly xRaw: Schema.Int;
+        readonly yRaw: Schema.Int;
+        readonly zRaw: Schema.Int;
+        readonly kind: Schema.Literal<"sphere">;
+    }>]>>;
+}>;
+
+declare type GeometryTileChunk = (typeof GeometryTileChunkSchema)["Type"];
+
+declare const GeometryTileChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"2d-tiles">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly tileSizeRaw: Schema.Int;
+    readonly palette: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly solid: Schema.Boolean;
+    }>>;
+    readonly runs: Schema.$Array<Schema.Struct<{
+        readonly paletteIndex: Schema.Int;
+        readonly length: Schema.Int;
+    }>>;
+}>;
+
+declare interface GeometryTileCollisionOptions {
+    /** Total visited cells across every solver query, including its final check.
+     * May only narrow the world's maxOverlapTests. */
+    readonly maxTests?: number;
+    /** Existing discrete solver limit; defaults to 8, maximum 256. */
+    readonly maxIterations?: number;
+}
+
+declare type GeometryTileMaterial = (typeof GeometryTileMaterialSchema)["Type"];
+
+declare const GeometryTileMaterialSchema: Schema.Struct<{
+    readonly key: Schema.String;
+    readonly solid: Schema.Boolean;
+}>;
+
+declare type GeometryVoxelChunk = (typeof GeometryVoxelChunkSchema)["Type"];
+
+declare const GeometryVoxelChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"3d-voxel">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+        readonly cz: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly side: Schema.Int;
+    readonly voxelSizeRaw: Schema.Int;
+    readonly palette: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly solid: Schema.Boolean;
+    }>>;
+    readonly sections: Schema.$Array<Schema.Struct<{
+        readonly sx: Schema.Int;
+        readonly sy: Schema.Int;
+        readonly sz: Schema.Int;
+        readonly runs: Schema.$Array<Schema.Struct<{
+            readonly paletteIndex: Schema.Int;
+            readonly length: Schema.Int;
+        }>>;
+    }>>;
+}>;
+
+/** Nonempty half-open raw box. Three-dimensional kinds require both Z fields. */
+declare interface GeometryWorldBoxRaw {
+    readonly minXRaw: number;
+    readonly minYRaw: number;
+    readonly maxXRaw: number;
+    readonly maxYRaw: number;
+    readonly minZRaw?: number;
+    readonly maxZRaw?: number;
+}
+
+declare interface GeometryWorldPointRaw {
+    readonly xRaw: number;
+    readonly yRaw: number;
+    readonly zRaw?: number;
+}
+
+declare type GeometryWorldRayHit = GeometryGridRayHit | GeometryShapeRayHit | GeometryHeightfieldRayHit;
+
+declare interface GeometryWorldRayOptions extends GeometryGridRayOptions {
+    /** Shapes only; narrows maxOverlapTests for the total shape scan. */
+    readonly maxTests?: number;
+}
+
+declare interface GeometryWorldShapeHit {
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly shape: GeometryShape;
+}
+
+declare interface GeometryWorldView {
+    readonly kind: GeometryKind;
+    readonly scope: GeometryPreparedScope;
+    /** Discrete AABB/circle resolution in world units against current tile data.
+     * Reuses the Transform solver; no swept movement or velocity integration. */
+    collide(transform: Transform2D, body: CollisionBody2D, options?: GeometryTileCollisionOptions): CollisionResult2D;
+    /** Tiles/voxels only. Unloaded coordinates refuse, never implicit empty terrain. */
+    materialAtRaw(point: GeometryWorldPointRaw): GeometryTileMaterial;
+    /** Tiles/voxels/shapes: the stored solidity. Heightfields (points with `zRaw`): terrain is solid at and
+     * below its surface, the same surface `raycastRaw` hits. Heightfield material is not invented. */
+    solidAtRaw(point: GeometryWorldPointRaw): boolean;
+    /** Heightfield only, with exact existing native interpolation. */
+    heightAtRaw(point: GeometryWorldPointRaw): number;
+    /** Shapes only; hit volumes retain native LOCAL coordinates and exact chunk scope. */
+    shapesAtRaw(point: GeometryWorldPointRaw): ReadonlyArray<GeometryWorldShapeHit>;
+    /** Tiles/voxels return exact rational entry; shapes select exact quadratic
+     * entry and expose enclosing presentation bounds; heightfields (points with
+     * `zRaw`) return the first sampled point at or below the surface, refined to
+     * one raw unit (`raycastGeometryHeightfield`). Missing coverage refuses. */
+    raycastRaw(from: GeometryWorldPointRaw, to: GeometryWorldPointRaw, options?: GeometryWorldRayOptions): GeometryWorldRayHit | null;
+    /** Tiles/voxels/closed native shapes, clipped by half-open chunk ownership. Heightfields need the z extent:
+     * the box touches terrain when the highest surface point over its footprint is at or above `minZRaw`
+     * (`overlapsGeometryHeightfieldBox`). Nonempty half-open raw boxes only; missing data or work exhaustion refuses. */
+    overlapsBoxRaw(box: GeometryWorldBoxRaw, options?: GeometryBoxOverlapOptions): boolean;
+    /** Translation-only tile/voxel sweep. Shares maxOverlapTests; validates the
+     * whole swept bounding region before publishing the earliest overlap. */
+    sweepBoxRaw(from: GeometryWorldBoxRaw, to: GeometryWorldBoxRaw, options?: GeometryBoxOverlapOptions): GeometryGridSweepHit | null;
+    /** Heightfields only (boxes with a z extent): the first raw-grid position that reaches under the surface
+     * (`sweepGeometryHeightfieldBox`), coarse steps of a quarter sample spacing, at most
+     * `geometry.budgets.maxRayCells` overlap evaluations of `maxTests` reads each. */
+    sweepHeightfieldBoxRaw(from: GeometryHeightfieldBoxRaw, to: GeometryHeightfieldBoxRaw, options?: GeometryBoxOverlapOptions): GeometryHeightfieldSweepHit | null;
+}
+
+export declare const interpolate: (mode?: "linear" | "angle" | "none") => <S extends Schema.Codec<unknown, unknown>>(schema: S) => S;
+
+declare type LockstepDesyncAction = 'resync' | 'end' | 'flag';
+
+declare interface LockstepDesyncContext {
+    readonly tick: number;
+    readonly playerId: number;
+    readonly expected: Uint64Words;
+    readonly received: Uint64Words;
+}
+
+declare type LockstepInputPrediction<I> = 'repeat-last' | 'none' | ((last: I, context: {
+    readonly playerId: number;
+    readonly tick: number;
+}) => I);
+
+declare interface LockstepPolicyStrategies {
+    readonly refereeLag?: (configuredTicks: number) => number;
+    readonly stallPolicy?: (options: LockstepStallPolicyOptions) => LockstepStallPolicy;
+    readonly onDesync?: (incident: LockstepDesyncContext, configuredAction: LockstepDesyncAction) => LockstepDesyncAction;
+}
+
+declare interface LockstepStallPolicy {
+    readonly afterTicks: number;
+    readonly action: 'pause' | 'drop-player';
+}
+
+declare interface LockstepStallPolicyOptions {
+    readonly afterTicks?: number;
+    readonly action?: 'pause' | 'drop-player';
+}
+
+/** Cosmetic state remains schema-validated and copied, but is excluded from simulation hashes. */
+export declare const nonAuthoritative: () => <S extends Schema.Codec<unknown, unknown>>(schema: S) => S;
+
+/** 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;
+}
+
+export declare const precision: (format: "f32" | "f64") => <S extends Schema.Codec<unknown, unknown>>(schema: S) => S;
+
+export declare interface Quantization {
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number | undefined;
+    readonly bits?: number | undefined;
+}
+
+export declare const quantizationStep: (options: Quantization) => number;
+
+export declare const quantize: (value: number, options: Quantization) => number;
+
+export declare const quantized: (options: Quantization) => <S extends Schema.Codec<unknown, unknown>>(schema: S) => S;
+
+/** Commands are staged in memory and drained outside the tick. */
+export declare interface RoomAppBridge {
+    publish(event: string, payload: unknown, options: {
+        readonly key: string;
+    }): string;
+    run(descriptor: string, input: unknown): string;
+}
+
+export declare interface RoomAuthoringStrategies<S = unknown> {
+    readonly budgets?: (options: Readonly<Partial<RoomBudgets>>) => RoomBudgets;
+    readonly reconnectPolicy?: (options: Readonly<Partial<{
+        readonly graceMs: number;
+    }>>) => {
+        readonly graceMs: number;
+    };
+    readonly snapshotPolicy?: (options: Readonly<Partial<RoomSnapshotPolicy<S>>>) => RoomSnapshotPolicy<S>;
+    readonly spectatorPolicy?: (options: Readonly<Partial<RoomSpectatorPolicy>>) => RoomSpectatorPolicy;
+}
+
+export declare interface RoomBudgets {
+    readonly inputsPerSecond: number;
+    readonly bytesPerSecond: number;
+    readonly burst: number;
+    readonly maxQueuedInputs: number;
+    readonly maxOutboxCommands: number;
+    readonly maxScheduledHooks: number;
+    readonly maxQueuedLifecycleHooks: number;
+    readonly maxNpcs: number;
+    /** A player input acting on state older than this many milliseconds behind the newest state
+     * the Host sent that client is dropped (it arrived too late to apply fairly). */
+    readonly inputLatencyBudgetMs: number;
+}
+
+export declare interface RoomChannel {
+    readonly schema: Schema.Codec<unknown, unknown>;
+    readonly direction: 'both' | 'server' | 'client';
+    readonly reliable: boolean;
+}
+
+export declare interface RoomClient {
+    readonly sessionId: string;
+    readonly subjectId: string | null;
+    readonly tenantId: string;
+    /** App data the API resolved for this seat (`seatAttributes` on the Rooms API binding), signed into
+     * the seat; absent without one. Not a secret from the player: it travels in their seat token. */
+    readonly attributes?: RoomSeatAttributes | undefined;
+    /** Actor-owned classification, never accepted from a socket input. */
+    readonly isBot?: boolean | undefined;
+    readonly countsAsPlayer?: boolean | undefined;
+    send(channel: string, payload: unknown): void;
+    kick(reason: string): void;
+}
+
+export declare interface RoomClock {
+    now(): number;
+}
+
+declare interface RoomCodecLimits {
+    readonly maxBytes: number;
+    readonly maxCollectionLength: number;
+    readonly maxFieldId: number;
+}
+
+export declare interface RoomDefinition<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly mode?: 'state-sync';
+    readonly state: S;
+    readonly auth?: 'subject' | 'public';
+    readonly guards?: DeclaredAccess;
+    readonly openAccess?: string | undefined;
+    readonly input: I;
+    readonly options: O;
+    /** Author-owned initial state; no game values are guessed by the host. */
+    readonly initialState?: (options: (O)["Type"]) => (S)["Type"];
+    readonly tickRate?: number;
+    readonly sendRate?: number;
+    readonly maxClients?: number;
+    readonly maxCatchUpTicks?: number;
+    readonly lifecycleTimeoutMs?: number;
+    readonly budgets?: Partial<RoomBudgets>;
+    readonly strategies?: RoomAuthoringStrategies<(S)["Type"]> | undefined;
+    readonly reconnect?: {
+        readonly graceMs: number;
+    };
+    readonly autoDispose?: {
+        readonly afterEmptyMs: number;
+        readonly hibernate?: boolean;
+    };
+    readonly snapshot?: Partial<RoomSnapshotPolicy<(S)["Type"]>>;
+    /** Opt-in shared history; host must supply the actual common view/admission. */
+    readonly spectator?: Partial<RoomSpectatorPolicy> | undefined;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+    readonly view?: (context: RoomViewContext<(S)["Type"]>) => (S)["Type"];
+    readonly viewBudgetMs?: number;
+    /** How the Room appears in `rooms.list`, derived from its state: `private` takes it off the list
+     * (it stays joinable by ID), `locked` refuses every new seat, `metadata` is shown to listers.
+     * Omitted fields keep their current value. The Host writes a change with the next checkpoint,
+     * which a change triggers at once. Synchronous and pure, like `view`. */
+    readonly listing?: (context: RoomListingContext<(S)["Type"], (O)["Type"]>) => RoomListing;
+    readonly extensions?: ReadonlyArray<RoomExtension<(S)["Type"], (I)["Type"]>>;
+    readonly world?: RoomWorldHooks<(S)["Type"]> | undefined;
+    readonly onCreate?: RoomSyncHook<Omit<RoomMemberContext<(S)["Type"], (O)["Type"]>, 'client'>>;
+    readonly onRehydrate?: RoomSyncHook<Omit<RoomMemberContext<(S)["Type"], (O)["Type"]>, 'client'>>;
+    readonly onJoin?: RoomLifecycleHook<RoomMemberContext<(S)["Type"], (O)["Type"]>>;
+    readonly onLeave?: RoomLifecycleHook<RoomMemberContext<(S)["Type"], (O)["Type"]> & {
+        readonly reason: RoomLeaveReason;
+    }>;
+    readonly onTick: RoomSyncHook<RoomTickContext<(S)["Type"], (I)["Type"]>>;
+    readonly onSchedule?: RoomSyncHook<RoomTickContext<(S)["Type"], (I)["Type"]> & {
+        readonly label: string;
+    }>;
+    readonly onDispose?: RoomLifecycleHook<{
+        readonly state: RoomState<(S)["Type"]> | undefined;
+        readonly app: RoomAppBridge;
+        readonly geometry?: GeometryWorldView;
+    }> | undefined;
+}
+
+export declare interface RoomDescriptor<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> extends RoomDefinition<S, I, O> {
+    readonly _tag: 'RoomDescriptor';
+    readonly auth: 'subject' | 'public';
+    readonly guards: DeclaredAccess;
+    readonly tickRate: number;
+    readonly sendRate: number;
+    readonly maxClients: number;
+    readonly maxCatchUpTicks: number;
+    readonly lifecycleTimeoutMs: number;
+    readonly budgets: RoomBudgets;
+    readonly view: (context: RoomViewContext<(S)["Type"]>) => (S)["Type"];
+    readonly reconnect: {
+        readonly graceMs: number;
+    };
+    readonly autoDispose: {
+        readonly afterEmptyMs: number;
+        readonly hibernate: boolean;
+    };
+    readonly snapshot: RoomSnapshotPolicy<(S)["Type"]>;
+    readonly spectator?: RoomSpectatorPolicy | undefined;
+    readonly messages: Readonly<Record<string, RoomChannel>>;
+    readonly viewBudgetMs: number;
+    readonly extensions: ReadonlyArray<RoomExtension<(S)["Type"], (I)["Type"]>>;
+}
+
+export declare interface RoomExtension<S, I> {
+    readonly name: string;
+    readonly fields: ReadonlyArray<Extract<keyof S, string>>;
+    readonly channel: string;
+    readonly tickBudgetMs: number;
+    readonly beforeTick?: RoomSyncHook<RoomExtensionContext<S, I>>;
+    readonly afterTick?: RoomSyncHook<RoomExtensionContext<S, I>>;
+}
+
+export declare interface RoomExtensionContext<S, I> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<Partial<S>>;
+    readonly tick: number;
+    readonly dt: number;
+    readonly inputs: ReadonlyArray<Omit<RoomInput<I>, 'client'> & {
+        readonly client: Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId' | 'isBot' | 'countsAsPlayer' | 'attributes'>;
+    }>;
+    readonly clock: RoomClock;
+    send(sessionId: string, payload: unknown): void;
+}
+
+export declare const RoomFieldId: unique symbol;
+
+export declare interface RoomInput<I> {
+    readonly client: RoomClient;
+    readonly seq: number;
+    readonly tickHint: number;
+    readonly input: I;
+}
+
+export declare const RoomInterpolation: unique symbol;
+
+export declare type RoomLeaveReason = 'left' | 'kicked' | 'reconnecting' | 'timeout' | 'disposed';
+
+/** Lifecycle Effects are run by the host outside the synchronous tick. `void` admits block bodies;
+ * a returned Promise is refused at runtime with an authoring error. */
+export declare type RoomLifecycleHook<C> = (context: C) => void | Effect.Effect<void, unknown>;
+
+/** A Room's own listing; scalar metadata only, at most 16 keys and 2 KiB. */
+export declare interface RoomListing {
+    readonly metadata?: Readonly<Record<string, RoomScalar>>;
+    readonly private?: boolean;
+    readonly locked?: boolean;
+}
+
+export declare interface RoomListingContext<S, O> {
+    readonly state: S;
+    readonly options: O;
+}
+
+export declare interface RoomLockstepDefinition<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly mode: 'lockstep';
+    readonly simulation: Simulation<S, I, O>;
+    readonly lockstep?: RoomLockstepOptions<I> | undefined;
+    readonly guards?: DeclaredAccess;
+    readonly openAccess?: string | undefined;
+    readonly auth?: 'subject';
+    readonly tickRate?: number;
+    readonly maxCatchUpTicks?: number;
+    readonly lifecycleTimeoutMs?: number;
+    readonly budgets?: Partial<RoomBudgets>;
+    readonly reconnect?: {
+        readonly graceMs: number;
+    };
+    readonly strategies?: Pick<RoomAuthoringStrategies, 'reconnectPolicy'> | undefined;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+    readonly onMessage?: (context: RoomLockstepMessageContext) => undefined;
+}
+
+export declare interface RoomLockstepDescriptor<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> extends RoomLockstepDefinition<S, I, O> {
+    readonly _tag: 'RoomDescriptor';
+    /** Lockstep rooms never join a World; declared so mixed descriptor reads narrow on it. */
+    readonly world?: undefined;
+    readonly auth: 'subject';
+    readonly state: S;
+    readonly input: I;
+    readonly options: O;
+    readonly guards: DeclaredAccess;
+    readonly tickRate: number;
+    readonly maxCatchUpTicks: number;
+    readonly lifecycleTimeoutMs: number;
+    readonly maxClients: number;
+    readonly budgets: RoomBudgets;
+    readonly reconnect: {
+        readonly graceMs: number;
+    };
+    readonly messages: Readonly<Record<string, RoomChannel>>;
+    readonly lockstep: RoomLockstepOptions<I> & {
+        readonly inputSchema: I;
+        readonly inputDelayTicks: number;
+        readonly rollbackHorizonTicks: number;
+        readonly inputPrediction: LockstepInputPrediction<(I)["Type"]>;
+        readonly maxPlayers: number;
+    };
+    /** State-sync lifecycle/spectators are never manufactured for a lockstep declaration. */
+    readonly initialState?: never;
+    readonly spectator?: never | undefined;
+}
+
+declare interface RoomLockstepDesync {
+    readonly tick: number;
+    readonly playerId: number;
+    readonly expected: Uint64Words;
+    readonly received: Uint64Words;
+}
+
+export declare interface RoomLockstepMessageContext {
+    readonly roomId: string;
+    readonly tenantId: string;
+    readonly epoch: number;
+    readonly client: {
+        readonly sessionId: string;
+        readonly subjectId: string;
+        readonly tenantId: string;
+    };
+    readonly channel: string;
+    readonly payload: unknown;
+    /** Stage an ephemeral reply to the same current native Session. */
+    reply(channel: string, payload: unknown): void;
+    /** Stage an ephemeral message to the currently activated player Sessions. */
+    broadcast(channel: string, payload: unknown): void;
+}
+
+export declare interface RoomLockstepOptions<I extends Schema.Codec<unknown, unknown>> extends RoomLockstepServerOptions {
+    readonly inputSchema?: I;
+    readonly inputDelayTicks?: number;
+    readonly rollbackHorizonTicks?: number;
+    readonly inputPrediction?: LockstepInputPrediction<(I)["Type"]>;
+    /** Admit players after Start (late join). Each joins at a tick chosen by the Host, ahead of
+     * the confirmed frontier by the input delay; every simulation sees it at that tick. */
+    readonly lateJoin?: boolean;
+}
+
+declare interface RoomLockstepRosterOptions {
+    readonly initialTick?: number;
+    readonly maxPlayers?: number;
+    readonly maxFutureTicks?: number;
+    readonly maxBatchInputs?: number;
+    readonly maxPendingInputs?: number;
+    readonly maxPendingBytes?: number | undefined;
+}
+
+declare interface RoomLockstepServerOptions extends Omit<RoomLockstepRosterOptions, 'initialTick'> {
+    readonly strategies?: LockstepPolicyStrategies | undefined;
+    readonly stallPolicy?: LockstepStallPolicyOptions;
+    readonly serverRole?: RoomLockstepServerRole;
+    readonly refereeLagTicks?: number;
+    readonly hashEvery?: number;
+    readonly hashHistoryTicks?: number;
+    readonly maxQueuedTicks?: number;
+    readonly maxQueuedInputBytes?: number;
+    readonly maxPendingHashes?: number;
+    readonly maxRefereeSteps?: number;
+    readonly maxReplayTicks?: number;
+    readonly maxReplayInputBytes?: number;
+    readonly maxSnapshotBudgetBytes?: number;
+    readonly maxRejectionAttempts?: number;
+    readonly onDesync?: 'resync' | 'end' | 'flag' | ((incident: RoomLockstepDesync) => 'resync' | 'end' | 'flag');
+}
+
+declare type RoomLockstepServerRole = 'relay' | 'referee' | 'full';
+
+export declare interface RoomMemberContext<S, O> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<S>;
+    readonly options: O;
+    readonly client: RoomClient;
+    readonly app: RoomAppBridge;
+    readonly clock: RoomClock;
+    readonly scheduler: RoomScheduler;
+    /** World Rooms, ordinary player join: the server-owned entity this Session controls and
+     * its last persisted `persistEntity` data. Build the state entity from it when absent. */
+    readonly world?: RoomWorldMember | undefined;
+}
+
+export declare const RoomNonAuthoritative: unique symbol;
+
+export declare const RoomPrecision: unique symbol;
+
+export declare const RoomQuantization: unique symbol;
+
+export declare type RoomScalar = string | number | boolean | null;
+
+export declare interface RoomScheduler {
+    after(milliseconds: number, label: string): void;
+    every(milliseconds: number, label: string): void;
+    cancel(label: string): void;
+}
+
+/** App data for one seat, resolved by the API when the seat is reserved (`seatAttributes`) and signed
+ * into it; scalars only, at most 16 keys and 2 KiB. */
+export declare type RoomSeatAttributes = Readonly<Record<string, RoomScalar>>;
+
+export declare interface RoomSnapshotPolicy<S> {
+    readonly everyMs: number;
+    readonly onlyIfChanged: boolean;
+    readonly mode: 'full' | 'delta';
+    readonly fullEvery: number;
+    readonly keepFulls: number;
+    readonly store: 'auto';
+    /** Maximum inline codec payload; the host may impose a smaller cutoff. */
+    readonly maxInlineBytes: number;
+    /** Full-schema projection of volatile data; never a partial-state format. */
+    readonly pick: (state: S) => S;
+}
+
+export declare interface RoomSpectatorPolicy {
+    readonly delayMs: number;
+    readonly retentionMs: number;
+    readonly maxFrames: number;
+    readonly maxBytes: number;
+    readonly maxFrameBytes: number;
+    readonly checkpointEveryMs: number;
+    readonly maxDeliveryFrames: number;
+}
+
+/** Plain mutable state; the author receives no store or database capability. */
+export declare type RoomState<A> = A extends ReadonlyArray<infer V> ? Array<RoomState<V>> : A extends object ? {
+    -readonly [K in keyof A]: RoomState<A[K]>;
+} : A;
+
+/** Synchronous hook. `void` admits parameterless block bodies (TypeScript cannot narrow those to
+ * `undefined`); any returned value, a Promise included, is refused at runtime with an authoring error. */
+export declare type RoomSyncHook<C> = (context: C) => void;
+
+export declare interface RoomTickContext<S, I> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<S>;
+    readonly tick: number;
+    readonly dt: number;
+    readonly inputs: ReadonlyArray<RoomInput<I>>;
+    readonly app: RoomAppBridge;
+    readonly clock: RoomClock;
+    readonly scheduler: RoomScheduler;
+    broadcast(channel: string, payload: unknown): void;
+}
+
+export declare const RoomTransform: unique symbol;
+
+export declare interface RoomViewContext<S> {
+    readonly state: S;
+    readonly client: Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId' | 'isBot' | 'countsAsPlayer' | 'attributes'>;
+    readonly role: 'player' | 'spectator';
+    readonly tick: number;
+}
+
+/** World Rooms keep their authored entities in the declared state record. */
+export declare type RoomWorldEntity<S> = S extends {
+    readonly entities: Readonly<Record<string, infer E>>;
+} ? RoomState<E> & {
+    readonly id: string;
+} : never;
+
+export declare interface RoomWorldHookContext<S> {
+    readonly state: RoomState<S>;
+    readonly phase: 'prepare' | 'commit' | 'rollback';
+    readonly requestId?: string | undefined;
+    readonly entity: RoomWorldEntity<S>;
+}
+
+export declare interface RoomWorldHookInput<E = unknown> {
+    /** Actual target placement, distinct from the source location. Only guarded
+     * target entry uses it; source rollback must restore its exact snapshot. */
+    readonly arrival?: WorldEntityLocation;
+    readonly epoch: number;
+    readonly entity: E;
+    readonly location: WorldEntityLocation;
+    readonly requestId?: string | undefined;
+}
+
+export declare interface RoomWorldHooks<S> {
+    /** Opt-in cell movement: synchronous author projection/write, no I/O. */
+    readonly movement?: RoomWorldMovement<S>;
+    /** Retained checkpoint receipts awaiting confirmed transition retirement. */
+    readonly maxPendingTransitions?: number;
+    readonly onEnter: RoomLifecycleHook<RoomWorldHookContext<S> & {
+        readonly from: WorldEntityLocation;
+        readonly to?: WorldEntityLocation;
+    }>;
+    readonly onExit: RoomLifecycleHook<RoomWorldHookContext<S> & {
+        readonly to: WorldEntityLocation;
+    }>;
+    /** Publish a projection on commit; remove that projection on rollback. Never
+     * promote it into authoritative entities. Rollback may retry after failure. */
+    readonly onGhost: RoomLifecycleHook<RoomWorldHookContext<S>>;
+    /** Synchronous, bounded JSON projection; no SQL or asynchronous effect here. */
+    readonly persistEntity: (context: {
+        readonly entity: RoomWorldEntity<S>;
+    }) => unknown;
+    /** A player who arrived by a World transition is now an active member. `onJoin` does not run for
+     * such arrivals (the entity came with `onEnter`); this is where the Room sees the arriving client,
+     * e.g. its seat attributes (`client.attributes`). */
+    readonly onMemberEnter?: RoomLifecycleHook<{
+        readonly state: RoomState<S>;
+        readonly client: RoomClient;
+        readonly entityId: string;
+    }>;
+}
+
+/** The server-owned entity an ordinary World player Session controls, as last persisted.
+ * The Room's `onJoin` receives it as `world` and builds the state entity when absent. */
+declare interface RoomWorldMember {
+    readonly entityId: string;
+    readonly worldId: string;
+    readonly zoneId: string;
+    readonly cellId: string;
+    readonly layer: number;
+    readonly revision: number;
+    /** The Room's `persistEntity` projection from the entity's last write. */
+    readonly data: unknown;
+}
+
+export declare interface RoomWorldMovement<S> {
+    readonly maxEntities: number;
+    readonly maxBytesPerTick: number;
+    readonly position: (entity: RoomWorldEntity<S>) => WorldPoint;
+    readonly move: (entity: RoomWorldEntity<S>, at: WorldPoint) => void;
+}
+
+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 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"];
+
+/** Exact unsigned 64-bit integer as independent 32-bit words. */
+declare interface Uint64Words {
+    readonly hi: number;
+    readonly lo: number;
+}
+
+declare interface WorldEntityLocation {
+    readonly worldId: string;
+    readonly zoneId: string;
+    readonly at: WorldPoint;
+    readonly layer: number;
+    readonly roomId: string;
+    readonly epoch: number;
+}
+
+declare type WorldPoint = readonly [x: number, y: number];
+
+export { }