hayao 0.2.0 → 0.3.0

package/dist/rasterize-worker-lite.mjs

@@ -0,0 +1,13 @@
+// Lite rasterize worker shipped in the npm package (dist/): SVG file → PNG in
+// an isolated process, no repo-only helpers (no sanitize pass, system fonts).
+// @resvg/resvg-js resolves from the CONSUMER's node_modules — install it as a
+// devDependency to enable inspect_moment PNGs; without it this exits non-zero
+// and the MCP server degrades to probe + hash.
+//   node rasterize-worker-lite.mjs <in.svg> <width> <out.png>
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [, , svgPath, width, outPath] = process.argv;
+const { Resvg } = await import('@resvg/resvg-js');
+const svg = readFileSync(svgPath, 'utf8');
+const png = new Resvg(svg, { fitTo: { mode: 'width', value: Number(width) }, font: { loadSystemFonts: true } }).render().asPng();
+writeFileSync(outPath, png);

package/dist/render/canvas.d.ts

@@ -1,5 +1,6 @@
 import { type DrawCommand } from './commands';
-import type { Renderer, RendererConfig } from './renderer';
+import { type Renderer, type RendererConfig } from './renderer';
+import type { Vec2 } from '../core/math';
 export declare class Canvas2DRenderer implements Renderer {
     readonly width: number;
     readonly height: number;
@@ -11,9 +12,13 @@ export declare class Canvas2DRenderer implements Renderer {
     mount(parent: HTMLElement): void;
     private resize;
     draw(commands: DrawCommand[]): void;
+    /** Resolve a fill: a gradient (mapped to the shape's bbox) or a solid color. */
+    private fillFor;
     private stroke;
     private paint;
     private roundRect;
     get element(): HTMLCanvasElement;
+    /** Map a pointer event's clientX/Y into design space (undoes the letterbox). */
+    toDesign(clientX: number, clientY: number): Vec2;
     dispose(): void;
 }

package/dist/render/commands.d.ts

@@ -1,4 +1,39 @@
 import type { Transform } from '../core/math';
+/** One color stop of a gradient. `offset` is 0..1 along the gradient axis. */
+export interface GradientStop {
+    offset: number;
+    color: string;
+}
+/**
+ * A gradient fill in OBJECT-BOUNDING-BOX space: all coordinates are 0..1
+ * relative to the painted shape's bounds, so the same gradient reads correctly
+ * on a shape of any size or position (matches SVG `gradientUnits`).
+ */
+export interface LinearGradient {
+    type: 'linear';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stops: GradientStop[];
+}
+export interface RadialGradient {
+    type: 'radial';
+    /** Center + radius, all 0..1 in object-bounding-box space. */
+    cx: number;
+    cy: number;
+    r: number;
+    stops: GradientStop[];
+}
+export type Gradient = LinearGradient | RadialGradient;
+/** A soft shadow / outer glow. `dx=dy=0` is a symmetric glow; offset = drop. */
+export interface Shadow {
+    color: string;
+    /** Blur radius in local px. */
+    blur: number;
+    dx?: number;
+    dy?: number;
+}
 export interface Paint {
     fill?: string;
     stroke?: string;
@@ -6,6 +41,10 @@ export interface Paint {
     opacity?: number;
     /** Round line joins/caps for organic shapes. */
     round?: boolean;
+    /** A gradient fill; when present it overrides `fill` for the shape body. */
+    gradient?: Gradient;
+    /** A soft outer glow / drop shadow applied to the shape. */
+    shadow?: Shadow;
 }
 export type TextAlign = 'left' | 'center' | 'right';
 interface Base extends Paint {
@@ -13,6 +52,13 @@ interface Base extends Paint {
     transform: Transform;
     /** Painter's-order key; ties broken by tree order. Default 0. */
     z: number;
+    /**
+     * Transient view chrome — a drifting popup, particle, or tween that lives for
+     * a moment and is never something the player reads for meaning. Layout lints
+     * (see verify/layout) skip these by default: a "+10" floating over a HUD label
+     * is motion, not a collision. Set by cosmetic emitters (FloatingText/Particles).
+     */
+    transient?: boolean;
 }
 export interface RectCommand extends Base {
     kind: 'rect';

package/dist/render/paint.d.ts

@@ -0,0 +1,33 @@
+import type { DrawCommand, Gradient, GradientStop, LinearGradient, RadialGradient, Shadow } from './commands';
+type StopInput = string | GradientStop;
+/**
+ * A linear gradient by angle in degrees (0 = left→right, 90 = top→bottom).
+ * Stops are colors (auto-spaced) or explicit `{offset, color}`.
+ */
+export declare function linearGradient(stops: readonly StopInput[], angleDeg?: number): LinearGradient;
+/** A radial gradient centered in the shape by default (inner stop first). */
+export declare function radialGradient(stops: readonly StopInput[], opts?: {
+    cx?: number;
+    cy?: number;
+    r?: number;
+}): RadialGradient;
+/** A symmetric soft outer glow. */
+export declare function glow(color: string, blur: number): Shadow;
+/** A soft drop shadow, offset by (dx,dy). */
+export declare function dropShadow(color: string, blur: number, dx?: number, dy?: number): Shadow;
+export declare function gradientDef(g: Gradient, id: string): string;
+export declare function shadowDef(s: Shadow, id: string): string;
+export interface BBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Local-space bounding box of a shape command (null for paths/text/image). */
+export declare function shapeBBox(c: DrawCommand): BBox | null;
+/** Build a Canvas gradient mapped from object-bounding-box space into `bbox`. */
+export declare function canvasGradient(ctx: {
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
+}, g: Gradient, bbox: BBox): CanvasGradient;
+export {};

package/dist/render/renderer.d.ts

@@ -1,4 +1,5 @@
 import type { DrawCommand } from './commands';
+import type { Vec2 } from '../core/math';
 /** A backend that paints a display list into a host (DOM, canvas, or nothing). */
 export interface Renderer {
     readonly width: number;
@@ -7,6 +8,16 @@ export interface Renderer {
     draw(commands: DrawCommand[]): void;
     /** Attach to a DOM parent (browser backends). */
     mount?(parent: HTMLElement): void;
+    /** The mounted DOM node (canvas or svg), for attaching pointer listeners. */
+    readonly element?: HTMLElement | SVGElement;
+    /**
+     * Invert the display transform: a browser pointer event's clientX/clientY →
+     * design-space coordinates. The backend owns the letterbox (`object-fit:
+     * contain` / `preserveAspectRatio`) and DPR, so it's the only place that can
+     * undo them correctly. Returns design coords even outside the letterbox
+     * (values fall outside 0..width/height there).
+     */
+    toDesign?(clientX: number, clientY: number): Vec2;
     dispose?(): void;
 }
 export interface RendererConfig {
@@ -14,3 +25,14 @@ export interface RendererConfig {
     height: number;
     background?: string;
 }
+/**
+ * Undo a centered uniform-fit (`object-fit: contain` / SVG `xMidYMid meet`):
+ * map a client pixel inside `rect` back to the design box `width×height`. Shared
+ * by every DOM backend so the letterbox math lives in exactly one place.
+ */
+export declare function clientToDesign(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, width: number, height: number, clientX: number, clientY: number): Vec2;

package/dist/render/svg.d.ts

@@ -1,5 +1,6 @@
 import type { DrawCommand } from './commands';
-import type { Renderer, RendererConfig } from './renderer';
+import { type Renderer, type RendererConfig } from './renderer';
+import type { Vec2 } from '../core/math';
 export declare class SvgRenderer implements Renderer {
     readonly width: number;
     readonly height: number;
@@ -12,5 +13,7 @@ export declare class SvgRenderer implements Renderer {
     draw(commands: DrawCommand[]): void;
     setBackground(color: string): void;
     get element(): SVGSVGElement;
+    /** Map a pointer event's clientX/Y into design space (undoes the letterbox). */
+    toDesign(clientX: number, clientY: number): Vec2;
     dispose(): void;
 }

package/dist/render/svgString.d.ts

@@ -1,5 +1,9 @@
 import { type DrawCommand } from './commands';
-/** Inner SVG markup for a display list (no wrapping <svg>). */
-export declare function commandsToSVGInner(commands: DrawCommand[]): string;
+/**
+ * Inner SVG markup for a display list (no wrapping <svg>). `idPrefix` salts the
+ * ids of any gradient/shadow <defs> so several inner markups can share one SVG
+ * document (e.g. a filmstrip) without their `url(#…)` references colliding.
+ */
+export declare function commandsToSVGInner(commands: DrawCommand[], idPrefix?: string): string;
 /** A complete, standalone SVG document string for a frame — a headless screenshot. */
 export declare function renderToSVGString(commands: DrawCommand[], width: number, height: number, background?: string): string;

package/dist/scene/cameraController.d.ts

@@ -0,0 +1,42 @@
+import { Node, type NodeConfig } from './node';
+import { type Vec2 } from '../core/math';
+import type { Camera2D } from './nodes';
+/** World-space rectangle the camera CENTER is kept inside (before viewport inset). */
+export interface CameraBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface CameraControllerConfig extends NodeConfig {
+    /** Node to follow. May be set later via `follow()`. */
+    target?: Node;
+    /** Camera to drive. Defaults to the world's active camera each step. */
+    camera?: Camera2D;
+    /** Half-extents of a slack box the target may roam before the camera chases. */
+    deadzone?: number | Vec2;
+    /** Per-step chase factor in [0,1]; 1 snaps, lower trails. Default 0.15. */
+    smooth?: number;
+    /** Clamp the view to a world rectangle (the level bounds) so no void shows. */
+    bounds?: CameraBounds;
+}
+export declare class CameraController extends Node {
+    readonly type = "CameraController";
+    cosmetic: boolean;
+    target: Node | null;
+    private cameraRef;
+    deadzone: Vec2;
+    smooth: number;
+    bounds: CameraBounds | null;
+    constructor(config?: CameraControllerConfig);
+    /** Point the controller at a node to follow. */
+    follow(target: Node): this;
+    private host;
+    private camera;
+    /** Where the camera wants to sit: the target position, clamped to bounds. */
+    private desired;
+    /** Jump the camera straight to its desired position (no smoothing). */
+    snap(): void;
+    protected onReady(): void;
+    protected onProcess(): void;
+}

package/dist/scene/node.d.ts

@@ -1,12 +1,20 @@
 import type { Rng } from '../core/rng';
 import type { Clock } from '../core/clock';
+import type { InputState } from '../input/actions';
 import { Signal } 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. */
@@ -15,7 +23,8 @@ export interface WorldContext {
 /** 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;
@@ -50,8 +59,12 @@ export declare class Node {
     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;

package/dist/scene/nodes.d.ts

@@ -1,11 +1,25 @@
 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.
+ *  - `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`.
+ * (`Text` is anchored by its `align`, not centered — see the Text node.)
+ */
 export type Shape = {
     kind: 'rect';
     w: number;
     h: number;
     r?: number;
+    anchor?: 'center' | 'topLeft';
 } | {
     kind: 'circle';
     radius: number;

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/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;