@voltro/plugin-rooms 0.0.0-stage → 0.87.0

package/dist/replay.d.ts

@@ -0,0 +1,273 @@
+import { Result } from 'effect';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+/** Captures the exact recorder/player budgets without starting a recording. */
+export declare const captureRoomReplayLimits: (input?: Partial<RoomReplayLimits>) => RoomReplayLimits;
+
+/** Archived data has unknown application types. Ordinary ReplayPlayer admission
+ * still checks the complete chain; the header alone never admits an archive. */
+export declare const openArchivedReplay: (input: Uint8Array, config?: Partial<RoomReplayLimits>, options?: ReplaySchemaOptions) => Result.Result<ReplayPlayer<Schema.Codec<unknown>>, ProtocolError>;
+
+export declare const openReplay: <S extends Schema.Codec<unknown, unknown>>(codec: RoomStateCodec<S>, bytes: Uint8Array, limits?: Partial<RoomReplayLimits>) => Result.Result<ReplayPlayer<S>, ProtocolError>;
+
+declare class ProtocolError extends ProtocolError_base {
+    get message(): string;
+}
+
+declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruct<"ProtocolError", {
+    readonly detail: Schema.String;
+}>, YieldableError>;
+
+/** Explicit render-clock turns only. No timer, RAF, network or simulation. */
+export declare class ReplayPlayback<S extends Schema.Codec<unknown, unknown>> {
+    private positionMs;
+    private playing;
+    private rate;
+    private lastNow;
+    private readonly duration;
+    private readonly read;
+    constructor(player: ReplayPlayer<S>);
+    private clock;
+    private turn;
+    advance(nowMs: number): Result.Result<RoomReplaySnapshot<(S)["Type"]>, ProtocolError>;
+    play(nowMs: number): Result.Result<void, ProtocolError>;
+    pause(nowMs: number): Result.Result<void, ProtocolError>;
+    seek(atMs: number, nowMs: number): Result.Result<RoomReplaySnapshot<(S)["Type"]>, ProtocolError>;
+    setSpeed(speed: number, nowMs: number): Result.Result<void, ProtocolError>;
+    status(): RoomReplayPlaybackStatus;
+}
+
+/** Validates the entire chain once; seeking decodes from the preceding Full.
+ * A matching compiled codec is required, including for an archived schema. */
+export declare class ReplayPlayer<S extends Schema.Codec<unknown, unknown>> {
+    private readonly codec;
+    private readonly records;
+    private readonly checkpoints;
+    private readonly checkpointEveryMs;
+    readonly metadata: RoomReplayMetadata;
+    readonly highlights: ReadonlyArray<RoomReplayHighlight>;
+    constructor(codec: RoomStateCodec<S>, input: Uint8Array, config?: Partial<RoomReplayLimits>);
+    seek(atMs: number): Result.Result<RoomReplaySnapshot<(S)["Type"]>, ProtocolError>;
+    /** Cuts the validated ordinary state stream at a preceding Full checkpoint.
+     * It preserves original ticks/epochs/patches, rebases only archive times and
+     * reports actual boundaries; no interpolated state or video is fabricated. */
+    clip(fromMs: number, toMs: number, config?: Partial<RoomReplayLimits>): Result.Result<RoomReplayClip, ProtocolError>;
+}
+
+/** Caller supplies an authorized, already selected view outside the tick.
+ * The recorder owns memory only; it has no storage, transport or authority. */
+export declare class ReplayRecorder<S extends Schema.Codec<unknown, unknown>> {
+    private readonly codec;
+    readonly limits: RoomReplayLimits;
+    private readonly description;
+    private readonly records;
+    private readonly markers;
+    private previous;
+    private checkpointAt;
+    private byteCount;
+    private sealed;
+    constructor(codec: RoomStateCodec<S>, limits?: Partial<RoomReplayLimits>);
+    append(snapshot: RoomReplaySnapshot<(S)["Type"]>): Result.Result<void, ProtocolError>;
+    /** Reuse one authorized group's already encoded wire frame. This is only
+     * codec/history admission; it does not authorize the supplied view. */
+    appendFrame(atMs: number, input: Uint8Array): Result.Result<void, ProtocolError>;
+    private commitFrame;
+    highlight(highlight: RoomReplayHighlight): Result.Result<void, ProtocolError>;
+    finish(): Result.Result<Uint8Array, ProtocolError>;
+    /** Erases this owner's retained memory; previously returned bytes remain caller-owned. */
+    clear(): void;
+}
+
+export declare interface ReplaySchemaOptions {
+    readonly maxDescriptionBytes?: number | undefined;
+    readonly maxSchemaNodes?: number | undefined;
+    readonly maxSchemaDepth?: number | undefined;
+    readonly codecLimits?: Partial<RoomCodecLimits> | undefined;
+}
+
+/** Restores only descriptive binary shapes, never original author functions,
+ * refinements, simulation or authority. Recompilation must match every byte of
+ * the archived description; no alternate decoder or guessed layout is used. */
+export declare const restoreReplayCodec: (description: string, options?: ReplaySchemaOptions) => Result.Result<RoomStateCodec<Schema.Codec<unknown>>, ProtocolError>;
+
+declare interface RoomCodecLimits {
+    readonly maxBytes: number;
+    readonly maxCollectionLength: number;
+    readonly maxFieldId: number;
+}
+
+export declare interface RoomReplayClip {
+    readonly bytes: Uint8Array;
+    /** Actual source boundaries, including preceding Full checkpoint pre-roll. */
+    readonly fromMs: number;
+    readonly toMs: number;
+    readonly requestedFromMs: number;
+    readonly requestedToMs: number;
+}
+
+export declare interface RoomReplayHighlight {
+    readonly atMs: number;
+    readonly kind: string;
+}
+
+export declare interface RoomReplayLimits {
+    readonly maxBytes: number;
+    readonly maxFrameBytes: number;
+    readonly maxFrames: number;
+    readonly maxHighlights: number;
+    readonly maxSchemaBytes: number;
+    readonly maxDurationMs: number;
+    readonly checkpointEveryMs: number;
+}
+
+export declare interface RoomReplayMetadata {
+    readonly formatVersion: 1;
+    readonly schemaHash: number;
+    readonly schemaDescription: string;
+    readonly durationMs: number;
+    readonly frames: number;
+    readonly checkpoints: number;
+    readonly bytes: number;
+}
+
+export declare interface RoomReplayPlaybackStatus {
+    readonly positionMs: number;
+    readonly playing: boolean;
+    readonly speed: number;
+}
+
+export declare interface RoomReplaySnapshot<A> {
+    readonly atMs: number;
+    readonly tick: number;
+    readonly epoch: number;
+    readonly state: A;
+}
+
+declare interface RoomSpectatorPolicy {
+    readonly delayMs: number;
+    readonly retentionMs: number;
+    readonly maxFrames: number;
+    readonly maxBytes: number;
+    readonly maxFrameBytes: number;
+    readonly checkpointEveryMs: number;
+    readonly maxDeliveryFrames: number;
+}
+
+/** Input and channel schemas are not state schemas: sorted field names derive
+ * their binary order, while server state always requires explicit field IDs. */
+declare class RoomStateCodec<S extends Schema.Codec<unknown, unknown>> {
+    readonly schema: S;
+    private readonly codec;
+    constructor(schema: S, config?: Partial<RoomCodecLimits>);
+    get schemaHash(): number;
+    get limits(): RoomCodecLimits;
+    /** Canonical binary layout, including quantization and static movement rules.
+     * This is descriptive data; it grants neither authority nor a schema loader. */
+    schemaDescription(): string;
+    fieldManifest(): ReadonlyArray<RoomStateField>;
+    transformRulesManifest(): ReadonlyArray<RoomStateTransformRules>;
+    full(state: (S)["Type"]): Result.Result<Uint8Array, ProtocolError>;
+    decodeFull(bytes: Uint8Array): Result.Result<(S)["Type"], ProtocolError>;
+    delta(state: (S)["Type"], baseline: (S)["Type"], includeUnchanged?: boolean): Result.Result<Uint8Array | null, ProtocolError>;
+    decodeDelta(bytes: Uint8Array, baseline: (S)["Type"]): Result.Result<(S)["Type"], ProtocolError>;
+}
+
+declare interface RoomStateField {
+    /** Parent scope is formed from field IDs, not mutable author field names. */
+    readonly scope: string;
+    readonly id: number;
+    readonly name: string;
+}
+
+declare interface RoomStateTransformRules {
+    readonly scope: string;
+    readonly rules: TransformRules;
+}
+
+/** One already-authorized view group's contiguous Full/Delta history. Feed and
+ * delivery happen outside ticks. This does not install a spectator or timer. */
+export declare class SpectatorDelayBuffer<S extends Schema.Codec<unknown, unknown>> {
+    private readonly codec;
+    readonly limits: SpectatorDelayLimits;
+    private records;
+    private previous;
+    private checkpointAt;
+    private sequence;
+    private observedNow;
+    private cached;
+    constructor(codec: RoomStateCodec<S>, limits?: Partial<SpectatorDelayLimits>);
+    /** Exact selected-view layout; it grants no group/seat authority. */
+    schemaDescription(): string;
+    append(atMs: number, input: Uint8Array): Result.Result<void, ProtocolError>;
+    delivery(nowMs: number, after?: SpectatorDelayCursor): Result.Result<SpectatorDelayDelivery, ProtocolError>;
+    /** No previously returned frame or external peer is erased by this call. */
+    clear(): void;
+}
+
+/** Opaque history position only; never a seat, credential or authorization. */
+export declare interface SpectatorDelayCursor {
+    readonly sequence: number;
+    readonly tick: number;
+    readonly epoch: number;
+}
+
+export declare type SpectatorDelayDelivery = {
+    readonly kind: 'unavailable';
+} | {
+    readonly kind: 'unchanged';
+    readonly cursor: SpectatorDelayCursor;
+    readonly atMs: number;
+} | {
+    readonly kind: 'full';
+    readonly cursor: SpectatorDelayCursor;
+    readonly atMs: number;
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'deltas';
+    readonly cursor: SpectatorDelayCursor;
+    readonly atMs: number;
+    readonly frames: ReadonlyArray<{
+        readonly atMs: number;
+        readonly bytes: Uint8Array;
+    }>;
+};
+
+export declare type SpectatorDelayLimits = RoomSpectatorPolicy;
+
+declare type TransformRules = TransformRules2D | TransformRules3D;
+
+declare interface TransformRules2D {
+    readonly bounds: {
+        readonly min: readonly [number, number];
+        readonly max: readonly [number, number];
+    };
+    readonly maxSpeed: number;
+    readonly maxAccel: number;
+    readonly precision: number;
+    readonly rotation?: {
+        readonly bits: number;
+    } | undefined;
+    readonly velocity?: 'send' | 'derive' | 'none' | undefined;
+    readonly interpolation: 'linear' | 'hermite' | 'none';
+    readonly extrapolateMs: number;
+    readonly teleportThreshold: number;
+}
+
+declare interface TransformRules3D {
+    readonly bounds: {
+        readonly min: readonly [number, number, number];
+        readonly max: readonly [number, number, number];
+    };
+    readonly maxSpeed: number;
+    readonly maxAccel: number;
+    readonly precision: number;
+    readonly rotation?: {
+        readonly bits: number;
+    } | undefined;
+    readonly interpolation: 'linear' | 'hermite' | 'none';
+    readonly extrapolateMs: number;
+    readonly teleportThreshold: number;
+}
+
+export { }