hayao 0.2.0 → 0.4.0

package/dist/scene/node.d.ts

@@ -1,25 +1,70 @@
 import type { Rng } from '../core/rng';
 import type { Clock } from '../core/clock';
-import { Signal } from '../core/events';
+import type { InputState } from '../input/actions';
+import { Signal, type EventBus } from '../core/events';
 import { type Transform, type Vec2 } from '../core/math';
 import type { DrawCommand } from '../render/commands';
-/** What a live node can see of its host world. The World implements this. */
+/**
+ * What a live node can see of its host world. The World implements this — it is
+ * exactly the read-only context handed to update callbacks, so a behaviour can
+ * reach input/rng/clock/time WITHOUT closing over the `world` from build(). That
+ * closure-free property is what lets a node be lifted out and reused verbatim.
+ */
 export interface WorldContext {
     readonly rng: Rng;
     readonly clock: Clock;
+    /** Sampled input for this step — `ctx.input.isDown('jump')`, `ctx.input.axis('pointer.x')`. */
+    readonly input: InputState;
     /** Queue a node to be freed at the end of the current step (safe during iteration). */
     requestFree(node: Node): void;
     /** Seconds elapsed in sim time. */
     readonly time: number;
+    /**
+     * Canonical out-of-tree game state (hashed + snapshotted) — the same object
+     * as `world.state`, so behaviours read/write shared sim data without closing
+     * over the world or stashing it in module variables.
+     */
+    readonly state: Record<string, unknown>;
+    /** The world event bus — emit/subscribe without a `world` closure. */
+    readonly events: EventBus<Record<string, unknown>>;
+    /** Design-space dimensions (what the camera letterboxes to). */
+    readonly width: number;
+    readonly height: number;
+    /** True while the world is paused (only `pauseMode: 'always'` subtrees update). */
+    readonly paused: boolean;
+    /** Sim-time multiplier (1 = realtime); `'always'` subtrees receive unscaled dt. */
+    readonly timeScale: number;
+    /**
+     * The active camera's world position + zoom, or null when none is current.
+     * Structural (no Camera2D import needed) — enough for parallax, culling, and
+     * screen-edge logic without a sibling search through the tree.
+     */
+    camera(): {
+        pos: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    } | null;
 }
 /** A composable update unit attached to a node (favour over deep inheritance). */
 export interface Behavior {
     ready?(node: Node): void;
-    update?(node: Node, dt: number): void;
+    /** `ctx` is the host world (input/rng/clock/time) — self-contained, no closure needed. */
+    update?(node: Node, dt: number, ctx: WorldContext): void;
     exit?(node: Node): void;
     /** Optional tag for lookup/serialization. */
     readonly kind?: string;
 }
+/**
+ * How a node behaves while the world is paused. `'inherit'` (default) takes the
+ * parent's effective mode (the root default is pausable), `'always'` keeps its
+ * subtree updating through a pause (pause menus, transitions), `'stopped'`
+ * halts its subtree even when the world is running.
+ */
+export type PauseMode = 'inherit' | 'always' | 'stopped';
+/** A resolved pause mode — what 'inherit' collapses to as it flows down the tree. */
+type EffectivePauseMode = 'pausable' | 'always' | 'stopped';
 /** Deterministic id source — reset by the World on load so ids are reproducible. */
 export declare function resetNodeIds(start?: number): void;
 export interface NodeConfig {
@@ -47,29 +92,73 @@ export declare class Node {
      * particles, tweened positions) never pollutes the canonical, verifiable state.
      */
     cosmetic: boolean;
+    /**
+     * Pause behaviour for this subtree (see PauseMode). Serialized only when
+     * non-default, so existing trees keep their pinned hashes.
+     */
+    pauseMode: PauseMode;
+    /**
+     * Screen-space overlay: this subtree ignores the camera — its transforms
+     * compose from IDENTITY (design-space coordinates) — and every command it
+     * emits is tagged `layer: 1` so HUD/overlay content always paints above the
+     * world, whatever the z values. Serialized only when true.
+     */
+    screenSpace: boolean;
+    /**
+     * Optional local anchor: when set, rotation/scale pivot around this point in
+     * local space instead of the node origin (the local transform gains a
+     * trailing translation of −pivot). Serialized only when set.
+     */
+    pivot?: Vec2;
     parent: Node | null;
     readonly children: Node[];
     world: WorldContext | null;
-    /** Optional inline update without subclassing: node.onUpdate = (n, dt) => {…}. */
-    onUpdate?: (node: Node, dt: number) => void;
+    /**
+     * Optional inline update without subclassing. The third argument is the host
+     * world context (input/rng/clock/time), so the callback is self-contained —
+     * `node.onUpdate = (n, dt, ctx) => { if (ctx.input.isDown('jump')) … }`.
+     */
+    onUpdate?: (node: Node, dt: number, ctx: WorldContext) => void;
     private behaviors;
     private signals;
     private _ready;
     private _freed;
     constructor(config?: NodeConfig);
+    /** Shorthand for `pos.x` — reads and writes the same vector. */
+    get x(): number;
+    set x(v: number);
+    /** Shorthand for `pos.y` — reads and writes the same vector. */
+    get y(): number;
+    set y(v: number);
     addChild<T extends Node>(child: T): T;
     removeChild(child: Node): void;
     /** Deferred free: runs exit hooks and detaches at the end of the step. */
     free(): void;
+    /**
+     * Immediately exit + detach ALL children. Unlike `free()` this is NOT
+     * deferred — the children are gone when the call returns (safe here because
+     * it iterates a snapshot of the array). Use it to rebuild a container's
+     * contents wholesale; prefer `free()` for removals during an update.
+     */
+    clearChildren(): void;
     /** Depth-first find by name. */
     find(name: string): Node | null;
+    /** Depth-first find of the first node (self included) that is an instance of `ctor` — typed. */
+    findOfType<T extends Node>(ctor: new (...args: never[]) => T): T | null;
     /** All descendants (and self) of a given type tag. */
     query(type: string, out?: Node[]): Node[];
     addBehavior(b: Behavior): this;
     signal<T = void>(name: string): Signal<T>;
     emit<T>(name: string, payload: T): void;
     enterTree(world: WorldContext): void;
-    updateTree(dt: number): void;
+    /**
+     * Advance this subtree. `dt` is the (time-scaled) step delta; `unscaledDt`
+     * and `paused` come from the world, and `parentMode` is the effective pause
+     * mode flowing down the tree. The walk always descends — a paused node just
+     * skips its callbacks — so an `'always'` descendant (pause menu, transition)
+     * keeps running inside a paused parent.
+     */
+    updateTree(dt: number, unscaledDt?: number, parentMode?: EffectivePauseMode, paused?: boolean): void;
     exitTree(): void;
     get isFreed(): boolean;
     localTransform(): Transform;
@@ -95,6 +184,9 @@ export interface SerializedNode {
     scale: Vec2;
     z: number;
     visible: boolean;
+    /** Local rotation/scale anchor (absent when unset). */
+    pivot?: Vec2;
     props: Record<string, unknown>;
     children: SerializedNode[];
 }
+export {};

package/dist/scene/nodes.d.ts

@@ -1,14 +1,49 @@
 import type { Transform } from '../core/math';
 import type { DrawCommand, Paint, TextAlign } from '../render/commands';
 import { Node, type NodeConfig } from './node';
+/**
+ * A Sprite's shape. ORIGIN CONVENTIONS differ per kind — a Sprite's `pos` is the
+ * node origin, and each shape places itself relative to it:
+ *  - `rect`   → CENTER-anchored by default: drawn from (-w/2,-h/2), so `pos` is its
+ *               middle. Pass `anchor: 'topLeft'` to place `pos` at the top-left
+ *               corner instead (the canvas mental model) — no half-size offset.
+ *  - `circle` → CENTER-anchored: `pos` is the center.
+ *  - `ellipse`→ CENTER-anchored: `pos` is the center; `rx`/`ry` are the semi-axes.
+ *  - `arc`    → CENTER-anchored: `pos` is the arc's center. Radians, clockwise
+ *               from +x (y-down screen convention), running `start` → `end`.
+ *               `sector: true` closes through the center (a pie slice).
+ *  - `glyph`  → CENTER-anchored (align 'center').
+ *  - `poly`   → LOCAL coordinates: `points` are relative to `pos` as-is (put your
+ *               own 0,0 wherever you like).
+ *  - `path`   → LOCAL coordinates: `d` is drawn relative to `pos`.
+ *  - `diamond`→ CENTER-anchored: a `w×h` rhombus (iso tile). `pos` is its middle.
+ *  - `regularPoly` → CENTER-anchored: `sides`-gon of circumradius `r`. `rotation`
+ *               (radians) turns it; 0 puts the first vertex straight up.
+ * (`Text` is anchored by its `align`, not centered — see the Text node.)
+ *
+ * `diamond` and `regularPoly` are pure sugar over `poly` (resolved at draw time,
+ * no renderer change) — they exist so an iso tile or a hex reads as intent, not
+ * as four hand-typed corner numbers.
+ */
 export type Shape = {
     kind: 'rect';
     w: number;
     h: number;
     r?: number;
+    anchor?: 'center' | 'topLeft';
 } | {
     kind: 'circle';
     radius: number;
+} | {
+    kind: 'ellipse';
+    rx: number;
+    ry: number;
+} | {
+    kind: 'arc';
+    radius: number;
+    start: number;
+    end: number;
+    sector?: boolean;
 } | {
     kind: 'poly';
     points: number[];
@@ -20,7 +55,20 @@ export type Shape = {
     kind: 'glyph';
     char: string;
     size: number;
+} | {
+    kind: 'diamond';
+    w: number;
+    h: number;
+} | {
+    kind: 'regularPoly';
+    sides: number;
+    r: number;
+    rotation?: number;
 };
+/** Local poly points for a center-anchored `w×h` diamond (top, right, bottom, left). */
+export declare function diamondPoints(w: number, h: number): number[];
+/** Local poly points for a center-anchored regular `sides`-gon of circumradius `r`. */
+export declare function regularPolyPoints(sides: number, r: number, rotation?: number): number[];
 export interface SpriteConfig extends NodeConfig, Paint {
     shape: Shape;
 }

package/dist/scene/parallax.d.ts

@@ -0,0 +1,15 @@
+import { Node, type NodeConfig } from './node';
+export interface ParallaxLayerConfig extends NodeConfig {
+    /** Scroll fraction: 0 = pinned to screen (far), 1 = full world scroll (near). */
+    factor: number;
+}
+export declare class ParallaxLayer extends Node {
+    readonly type = "ParallaxLayer";
+    cosmetic: boolean;
+    factor: number;
+    constructor(config: ParallaxLayerConfig);
+    /** Re-sync to the current camera; called each process tick (and on demand). */
+    sync(): void;
+    protected onReady(): void;
+    protected onProcess(): void;
+}

package/dist/scene/particles.d.ts

@@ -42,6 +42,25 @@ export declare class Particles extends Node {
     private gravity;
     private drag;
     private shrink;
+    private emitRate;
+    private emitAcc;
+    private emitStyle;
+    private emitOrigin;
+    /**
+     * Start (or retune) continuous emission at `ratePerSec` particles per second.
+     * `style.at` sets the node-local origin (default 0,0); the rest styles
+     * particles exactly like `burst()`. Omitting `style` keeps the previous
+     * emitter style (falling back to the `burst` preset if none was ever set).
+     *
+     * The signal form `emit(name, payload)` inherited from Node still works —
+     * the overload dispatches on the first argument's type.
+     */
+    emit(ratePerSec: number, style?: ParticleStyle & {
+        at?: Vec2;
+    }): void;
+    emit<T>(name: string, payload: T): void;
+    /** Stop continuous emission. Live particles finish their lives naturally. */
+    stopEmit(): void;
     protected onProcess(dt: number): void;
     protected draw(out: DrawCommand[], world: Transform): void;
     get liveCount(): number;

package/dist/scene/verletChain.d.ts

@@ -0,0 +1,76 @@
+import { type Transform, type Vec2 } from '../core/math';
+import type { DrawCommand } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+export interface VerletChainConfig extends NodeConfig {
+    /** Number of segments (points = segments + 1). */
+    segments: number;
+    /** Total rest length of the chain, px. */
+    length: number;
+    /** Acceleration applied to free points, px/s² in WORLD space (+y is down). */
+    gravity?: Vec2;
+    /** Per-step velocity retention 0..1 (1 = undamped). Default 0.985. */
+    damping?: number;
+    /** Constraint-relaxation passes per step. Default 3. */
+    iterations?: number;
+    /** Pin the tail too (set `tailTarget` for where). Default false. */
+    pinTail?: boolean;
+    /** Stroke color for draw(). Default '#333'. */
+    stroke?: string;
+    /** Stroke width at the head, px. Default 3. */
+    strokeWidth?: number;
+    /** Taper the stroke toward the tail (draws per-segment polys). Default false. */
+    taper?: boolean;
+}
+/**
+ * The rope node. Read `points` (node-local) to attach child sprites along the
+ * chain, `segmentAngle(i)` to orient them, and call `impulse(v)` to flick it.
+ */
+export declare class VerletChain extends Node {
+    readonly type: string;
+    gravity: Vec2;
+    damping: number;
+    iterations: number;
+    pinTail: boolean;
+    stroke: string;
+    strokeWidth: number;
+    taper: boolean;
+    /**
+     * Where the tail is pinned when `pinTail` is true, in NODE-LOCAL space
+     * (same space as `points`). null leaves the tail free even with pinTail set.
+     */
+    tailTarget: Vec2 | null;
+    readonly segments: number;
+    /** Rest length of one segment. */
+    readonly segmentLength: number;
+    private px;
+    private py;
+    private prevx;
+    private prevy;
+    /** Node-local mirror of the sim points, updated after each step. */
+    private readonly local;
+    private initialized;
+    private impX;
+    private impY;
+    constructor(config: VerletChainConfig);
+    /**
+     * Chain points in NODE-LOCAL space, head first (`points[0]` ≈ {0,0}).
+     * The Vec2 objects are reused across steps — read, don't retain copies-by-ref.
+     */
+    get points(): readonly Vec2[];
+    /**
+     * Direction of segment i (0..segments-1) in node-local space, radians
+     * (0 = +x, y-down screen convention). Map child sprites to segments with
+     * `sprite.pos = chain.points[i]; sprite.rotation = chain.segmentAngle(i)`.
+     */
+    segmentAngle(i: number): number;
+    /** Flick the chain: add a velocity (world px/s) to every free point next step. */
+    impulse(v: Vec2): void;
+    protected onProcess(dt: number): void;
+    /**
+     * Stroked open poly of the chain. `points` are node-local and `world` is the
+     * self-inclusive world transform handed to draw(), so commands emit with it
+     * directly. With `taper`, each segment is its own 2-point poly at a linearly
+     * decreasing width (segments are few, so this stays cheap); otherwise one poly.
+     */
+    protected draw(out: DrawCommand[], world: Transform): void;
+}

package/dist/studio/mcpMain.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/studio/mcpServer.d.ts

@@ -0,0 +1,2 @@
+/** Start serving over stdio (the entry points call this — never on import). */
+export declare function startStudioMcp(): Promise<void>;

package/dist/studio/record.d.ts

@@ -0,0 +1,54 @@
+import type { EndReason, KnobEvent, PlaytestSession, ScreenEvent, VariantRef, WallClockMark } from './session';
+import type { TuningValues } from '../app/tuning';
+import type { WorldSnapshot } from '../world';
+export interface RecorderInit {
+    game: string;
+    seed: number;
+    tuningValues: TuningValues;
+    variant?: VariantRef;
+    buildRef?: string;
+    startedAt?: string;
+    id?: string;
+    /** Segment sessions (post hot-swap) replay from this snapshot. */
+    startSnapshot?: WorldSnapshot;
+}
+export declare class SessionRecorder {
+    private frames;
+    private axesLog;
+    private lastAxes;
+    private knobEvents;
+    private screenEvents;
+    private wallClockMarks;
+    private annotations;
+    private readonly init;
+    private readonly startedAt;
+    readonly id: string;
+    /** Set once the dev server reports the git sha (fetched async by runStudio). */
+    buildRef: string;
+    constructor(init: RecorderInit);
+    /** Frames recorded so far — event hooks stamp themselves with this. */
+    get frame(): number;
+    /** Live view of the recorded input frames (the scrub timeline re-steps these). */
+    get liveInputFrames(): readonly string[][];
+    /** Live view of the delta-encoded axes log. */
+    get liveAxesLog(): ReadonlyArray<readonly [number, string, number]>;
+    /** Live view of mid-play knob changes (scrubbing reapplies them exactly). */
+    get liveKnobEvents(): readonly KnobEvent[];
+    /**
+     * Record one sim step: the action set it saw and (optionally) the analog
+     * axes. Axes are delta-encoded — an entry lands only when a value changed.
+     */
+    step(actions: readonly string[], axes?: ReadonlyMap<string, number>): void;
+    knob(key: string, value: number | string): void;
+    screen(kind: ScreenEvent['kind'], detail?: string): void;
+    mark(kind: WallClockMark['kind'], t: number): void;
+    annotate(tag: string, note?: string): void;
+    /**
+     * A rewind-and-resume forked the timeline: everything after `frame` never
+     * happened in the final run. Drop those frames plus the events stamped in
+     * them, so the artifact stays exactly replayable as what the player kept.
+     */
+    truncate(frame: number): void;
+    /** Finalize into the artifact. The recorder can keep recording afterwards (autosave). */
+    toSession(endReason: EndReason): PlaytestSession;
+}

package/dist/studio/run.d.ts

@@ -0,0 +1,78 @@
+import { type GameHandle, type RunOptions } from '../app/browser';
+import { type TuningSpec, type TuningValues, type Variant } from '../app/tuning';
+import { type GameDefinition } from '../app/game';
+import type { EndReason, PlaytestSession, VariantRef } from './session';
+/** The slice of Vite's import.meta.hot the carryover needs (structural, no vite type dep). */
+export interface HotContext {
+    data: Record<string, unknown>;
+    dispose(cb: (data: Record<string, unknown>) => void): void;
+}
+export interface StudioOptions extends RunOptions {
+    /**
+     * Named A/B variants of this game. `?variant=<name>` picks one: its `patch`
+     * rewrites the definition, its `tuning` seeds the knob values (explicit
+     * `?tuning=`/opts overrides still win). Sessions are stamped with the name.
+     */
+    variants?: Record<string, Variant>;
+    /** Variant identity override (worktree builds stamp commit info here). */
+    variant?: VariantRef;
+    /**
+     * Pass `import.meta.hot` (only the game's own entry module has it) to carry
+     * the live world ACROSS code hot-swaps: snapshot on dispose, restore into
+     * the re-executed module. The old session flushes as 'hot-swap'; the new
+     * segment records the restored snapshot so it stays fully replayable.
+     *
+     * The entry MUST also contain the literal line `import.meta.hot?.accept();`
+     * — Vite decides HMR boundaries by statically scanning module source, so an
+     * accept() call inside this library cannot mark your entry self-accepting.
+     */
+    hot?: HotContext;
+}
+export interface StudioHandle extends GameHandle {
+    /** Live-change a tuning knob: rebuild-with-carryover, recorded as a knob event. */
+    setKnob(key: string, value: number | string): void;
+    /** Current resolved tuning values. */
+    knobValues(): TuningValues;
+    /** The game's declared knob spec (the Studio panel builds its controls from this). */
+    tuningSpec(): TuningSpec | undefined;
+    /** Declared A/B variants: name → label. */
+    variants(): Record<string, string>;
+    /** The variant this run is playing (name + kind, worktrees include commit). */
+    activeVariant(): VariantRef;
+    /** The game title (the Studio page labels panes with it). */
+    title(): string;
+    /** Drop a human annotation at the current frame ("felt bad here"). */
+    annotate(tag: string, note?: string): void;
+    /** Freeze/unfreeze the sim (rendering continues; no pause overlay). */
+    setFrozen(frozen: boolean): void;
+    frozen(): boolean;
+    /**
+     * Time-travel to a recorded frame (freezes first). Exact: restores the
+     * nearest ring snapshot and re-steps the recorded inputs. Returns the frame
+     * reached, or null if it's off the ring. Resuming after a rewind FORKS the
+     * timeline: the discarded future is truncated from the session.
+     */
+    scrub(frame: number): number | null;
+    /** Scrub bounds + position: min reachable frame, current, recorded max. */
+    timeline(): {
+        min: number;
+        frame: number;
+        max: number;
+    };
+    /**
+     * 'live' = playing + recording; 'replay' = watching a past session loaded
+     * via ?session=<id> (read-only: scrub/playback over the whole recording,
+     * knobs and annotation disabled, nothing records).
+     */
+    mode(): 'live' | 'replay';
+    /** Flush the session artifact to the dev server now. */
+    flush(reason?: EndReason): void;
+    /** The in-progress session (for inspection/tests). */
+    session(): PlaytestSession;
+}
+declare global {
+    interface Window {
+        __studio?: StudioHandle;
+    }
+}
+export declare function runStudio(baseDef: GameDefinition, mount: HTMLElement, opts?: StudioOptions): StudioHandle;

package/dist/studio/session.d.ts

@@ -0,0 +1,80 @@
+import { type GameDefinition } from '../app/game';
+import type { TuningValues } from '../app/tuning';
+import type { InputLog } from '../input/actions';
+import type { World, WorldSnapshot } from '../world';
+/** Which build/variant produced a session — a report is never ambiguous about code. */
+export interface VariantRef {
+    name: string;
+    kind: 'dev' | 'module' | 'worktree';
+    commit?: string;
+}
+export interface ScreenEvent {
+    frame: number;
+    kind: 'pause' | 'resume' | 'restart' | 'overlay-show' | 'overlay-hide' | 'knob' | 'variant' | 'hot-swap' | 'scrub';
+    detail?: string;
+}
+/** Wall-clock context the sim can't see (tab hidden ≠ hesitation). */
+export interface WallClockMark {
+    frame: number;
+    /** ms since session start (wall clock — context only, never sim input). */
+    t: number;
+    kind: 'visibility-hidden' | 'visibility-visible' | 'blur' | 'focus';
+}
+export interface Annotation {
+    frame: number;
+    tag: string;
+    note?: string;
+}
+/** A mid-play tuning change (Studio knob): replay applies it AT its frame. */
+export interface KnobEvent {
+    frame: number;
+    key: string;
+    value: number | string;
+}
+export type EndReason = 'goal' | 'quit' | 'restart' | 'navigate' | 'idle' | 'hot-swap';
+export interface PlaytestSession {
+    id: string;
+    game: string;
+    startedAt: string;
+    /** Git short sha of the code that ran (from the Studio dev server). */
+    buildRef: string;
+    seed: number;
+    variant: VariantRef;
+    /** Tuning at session start (resolved values). */
+    tuningValues: TuningValues;
+    /**
+     * When play continued across a code hot-swap, the new segment records the
+     * world it resumed FROM — replay restores it before stepping, so even
+     * mid-development sessions stay bit-exactly re-executable.
+     */
+    startSnapshot?: WorldSnapshot;
+    knobEvents: KnobEvent[];
+    inputLog: InputLog;
+    /** Delta-encoded analog axes: [frame, axis, value] whenever a value changed. */
+    axesLog: Array<[number, string, number]>;
+    screenEvents: ScreenEvent[];
+    wallClockMarks: WallClockMark[];
+    annotations: Annotation[];
+    endReason: EndReason;
+    /** Invited-playtester fields — creator sessions leave them unset. */
+    playerId?: string;
+    consent?: {
+        recorded: boolean;
+        at: string;
+    };
+}
+export interface ReplayOptions {
+    toFrame?: number;
+    /** Observer called once with the fresh world BEFORE any step (subscribe to events here). */
+    onWorld?: (world: World) => void;
+    /** Observer called AFTER each step with the frame index just played. */
+    onFrame?: (world: World, frame: number) => void;
+}
+/**
+ * Replay a session headlessly to `toFrame` (default: the whole log) and return
+ * the live world. Bit-exact with the original run: axes deltas are applied
+ * before the step that first saw them; knob events rebuild-with-carryover at
+ * their frame exactly as the Studio panel did (including `def.attach`).
+ * A bare number as `opts` is `toFrame`.
+ */
+export declare function replaySession(def: GameDefinition, session: PlaytestSession, opts?: number | ReplayOptions): World;

package/dist/studio/timeline.d.ts

@@ -0,0 +1,35 @@
+import type { GameDefinition } from '../app/game';
+import type { World, WorldSnapshot } from '../world';
+import type { KnobEvent } from './session';
+export interface TimelineEntry {
+    frame: number;
+    snap: WorldSnapshot;
+}
+/**
+ * Periodic snapshot keeper. Every `stride` frames costs one snapshot; `cap`
+ * bounds memory (oldest evicted), so scrub range ≈ stride × cap frames back.
+ */
+export declare class SnapshotRing {
+    readonly stride: number;
+    readonly cap: number;
+    private entries;
+    constructor(stride?: number, cap?: number);
+    /** Call after every recorded step; keeps frame 0 and every stride-th frame. */
+    push(frame: number, world: World): void;
+    /** Nearest entry at or before `frame` (null if it fell off the ring). */
+    nearest(frame: number): TimelineEntry | null;
+    /** Oldest reachable frame (scrubbing earlier than this is off the ring). */
+    get minFrame(): number;
+    /** Drop entries after `frame` — a rewind-and-resume forked the timeline. */
+    truncate(frame: number): void;
+    clear(): void;
+}
+/**
+ * Scrub a live world to `target`: restore the nearest ring snapshot, then
+ * re-step the recorded inputs. `inputFrames[i]` is the input DURING step i, so
+ * stepping frames[entry..target-1] lands the world exactly AT `target`.
+ * Returns the frame actually reached (clamped to the ring's reachable range),
+ * or null if the ring is empty. `def.attach` runs after the restore — the same
+ * contract as every other restore path.
+ */
+export declare function scrubTo(world: World, def: GameDefinition, ring: SnapshotRing, inputFrames: readonly string[][], axesLog: ReadonlyArray<readonly [number, string, number]>, knobEvents: readonly KnobEvent[], target: number): number | null;

package/dist/studio/vitePlugin.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+export interface StudioPluginOptions {
+    /** Where session/knob/variant files live. Default: `.studio` under the project root. */
+    dir?: string;
+}
+export declare function hayaoStudio(opts?: StudioPluginOptions): Plugin;