@flatkit/player 0.1.0

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/headless.ts"],"sourcesContent":["// -----------------------------------------------------------------------------\n//  headless.ts -- plays a Doc WITHOUT a real canvas and replays a gesture SCRIPT.\n//\n//  Automatable verification of interactions (CI, LLM loop): we instantiate the\n//  `FlatPlayer` on a fake canvas (client coords = scene coords, scale 1), fire\n//  synthetic PointerEvents, and collect the emitted `send`s plus the final state\n//  of the variables. Pure Node: stubs the missing DOM globals.\n// -----------------------------------------------------------------------------\nimport { FlatPlayer } from './player'\nimport { itemBoundsByName, dropZoneBounds } from '@flatkit/engine/groups'\nimport { isGroup } from '@flatkit/engine/layers'\nimport type { Doc, Item } from '@flatkit/types'\nexport type { Gesture } from './player' // defined on the player side (reused by `--record`)\nimport type { Gesture } from './player'\n\ntype Box = { minX: number; minY: number; maxX: number; maxY: number }\n/** Cap on the moves a `scratch` synthesizes (anti-DoS: a huge bbox / tiny brush must not blow up). */\nconst MAX_SWEEP = 2000\n\n/** First named item matching `name` (walks groups). Used to find the reveal interactor's brush. */\nfunction findItemByName(items: Item[], name: string): Item | null {\n  for (const it of items) {\n    if ('name' in it && it.name === name) return it\n    if (isGroup(it)) for (const l of it.layers) { const r = findItemByName(l.items, name); if (r) return r }\n  }\n  return null\n}\n/** Brush radius (= grid) of the `reveal` interactor on a named target; default 24 if none. */\nfunction revealBrushFor(doc: Doc, name: string): number {\n  let id: string | null = null\n  for (const l of doc.layers) { const it = findItemByName(l.items, name); if (it) { id = it.id; break } }\n  const inter = id ? doc.interactors?.find((x) => x.targetId === id) : undefined\n  return inter?.grid && inter.grid > 0 ? inter.grid : 24\n}\n/** Boustrophedon sweep over `b` at ~`brush` spacing (cell centers), bounded to MAX_SWEEP points. */\nfunction sweepPoints(b: Box, brush: number): { x: number; y: number }[] {\n  const w = b.maxX - b.minX, h = b.maxY - b.minY\n  let step = Math.max(1, brush)\n  let cols = Math.max(1, Math.ceil(w / step)), rows = Math.max(1, Math.ceil(h / step))\n  if (cols * rows > MAX_SWEEP) { // too fine -> coarsen to stay bounded (coverage may be < 1; documented)\n    const f = Math.sqrt((cols * rows) / MAX_SWEEP)\n    step *= f; cols = Math.max(1, Math.ceil(w / step)); rows = Math.max(1, Math.ceil(h / step))\n  }\n  const pts: { x: number; y: number }[] = []\n  for (let r = 0; r < rows; r++) {\n    const y = Math.min(b.maxY, b.minY + (r + 0.5) * step)\n    const cs = Array.from({ length: cols }, (_v, c) => c)\n    if (r % 2) cs.reverse() // zig-zag: continuous stroke, no jump back to the left edge\n    for (const c of cs) pts.push({ x: Math.min(b.maxX, b.minX + (c + 0.5) * step), y })\n  }\n  return pts\n}\n\nexport type PlayResult = {\n  sends: { name: string; value?: number | string }[]\n  vars: Record<string, number | number[]>\n  steps?: TraceStep[] // present if `trace`: one record per gesture (inspection / debug-player)\n  expectFailures?: string[] // mismatches reported by the `expect` gestures (empty/absent = all verified) -> exit != 0 in CLI\n}\n\n/** Trace of ONE gesture: its description, the `send`s emitted during it, and the variable diff. */\nexport type TraceStep = {\n  gesture: string\n  sends: { name: string; value?: number | string }[]\n  changed: Record<string, [number | number[] | undefined, number | number[]]> // var -> [before, after]\n}\n\ntype Handlers = Record<string, (e: { clientX: number; clientY: number; pointerId: number }) => void>\n\nconst fakeCtx = (): CanvasRenderingContext2D =>\n  new Proxy({}, {\n    get: (_t, p) => (p === 'measureText' ? () => ({ width: 0 }) : p === 'getTransform' ? () => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }) : () => {}),\n    set: () => true,\n  }) as unknown as CanvasRenderingContext2D\n\nconst fakeCanvas = (handlers: Handlers, w: number, h: number): HTMLCanvasElement => ({\n  getContext: () => fakeCtx(),\n  getBoundingClientRect: () => ({ width: w, height: h, left: 0, top: 0, right: w, bottom: h }),\n  addEventListener: (type: string, fn: Handlers[string]) => { handlers[type] = fn },\n  removeEventListener: (type: string) => { delete handlers[type] },\n  setPointerCapture: () => {},\n  releasePointerCapture: () => {},\n  style: {},\n} as unknown as HTMLCanvasElement)\n\n/** Stubs the missing DOM globals (pure Node); returns a restore function. */\nfunction ensureDomGlobals(): () => void {\n  const g = globalThis as Record<string, unknown>\n  const undo: (() => void)[] = []\n  const set = (k: string, v: unknown) => { if (g[k] === undefined) { g[k] = v; undo.push(() => { delete g[k] }) } }\n  set('window', { addEventListener: () => {}, removeEventListener: () => {}, devicePixelRatio: 1 })\n  set('requestAnimationFrame', () => 0)\n  set('cancelAnimationFrame', () => {})\n  set('addEventListener', () => {})\n  set('removeEventListener', () => {})\n  return () => undo.forEach((f) => f())\n}\n\n/** Describes a gesture for the trace. */\nconst describeGesture = (g: Gesture): string =>\n  g.type === 'drag' ? `drag ${g.source}->${g.target}` : g.type === 'tap' ? `tap ${g.target}`\n    : g.type === 'connect' ? `connect ${g.source}->${g.target}` : g.type === 'scratch' ? `scratch ${g.target}`\n      : g.type === 'set' ? `set ${g.name}=${g.value}` : g.type === 'wait' ? `wait ${g.frames}` : g.type === 'expect' ? 'expect' : `${g.type} (${g.x},${g.y})`\n\n/** Plays `doc`, replays `gestures`, returns the collected `send`s plus the final state of the variables.\n *  `trace`: adds `steps` (sends + variable diff PER gesture) -- for inspection / the debug-player. */\nexport function playHeadless(doc: Doc, gestures: Gesture[], opts: { trace?: boolean } = {}): PlayResult {\n  const restore = ensureDomGlobals()\n  const handlers: Handlers = {}\n  const sends: PlayResult['sends'] = []\n  const pl = new FlatPlayer(fakeCanvas(handlers, doc.width, doc.height), doc, { input: true, padding: 0, render: false, onEvent: (e) => sends.push(e) })\n  const ev = (x: number, y: number, id = 1) => ({ clientX: x, clientY: y, pointerId: id })\n  const fire = (type: string, p: { x: number; y: number }, id = 1) => { const h = handlers[`pointer${type}`]; if (h) h(ev(p.x, p.y, id)) }\n  // GRAB: the RESOLVED position of the object (expressions included -> we touch the object exactly where it is).\n  const grabPoint = (name: string): { x: number; y: number } => {\n    const c = pl.objectCenter(name)\n    if (c) return c\n    const b = itemBoundsByName(doc, name)\n    if (!b) throw new Error(`gesture: object \"${name}\" not found in the scene`)\n    return { x: (b.minX + b.maxX) / 2, y: (b.minY + b.maxY) / 2 }\n  }\n  // DROP: center of the drop zone (static bbox / hitbox) -- that is what the drop is tested against.\n  const dropPoint = (name: string): { x: number; y: number } => {\n    const b = dropZoneBounds(doc, name)\n    if (!b) throw new Error(`gesture: zone \"${name}\" not found in the scene`)\n    return { x: (b.minX + b.maxX) / 2, y: (b.minY + b.maxY) / 2 }\n  }\n  // `expect`: self-verified assertions. `sendCursor` = window of sends SINCE the last `expect`.\n  let sendCursor = 0\n  const expectFailures: string[] = []\n  const applyGesture = (g: Gesture): void => {\n    if (g.type === 'set') { pl.setVar(g.name, g.value); return }\n    if (g.type === 'wait') { pl.stepSim(g.frames); return }\n    if (g.type === 'drag') { const id = g.id ?? 1, t = dropPoint(g.target); fire('down', grabPoint(g.source), id); fire('move', t, id); fire('up', t, id); return }\n    if (g.type === 'tap') { const id = g.id ?? 1, c = grabPoint(g.target); fire('down', c, id); fire('up', c, id); return }\n    if (g.type === 'connect') { const id = g.id ?? 1, t = grabPoint(g.target); fire('down', grabPoint(g.source), id); fire('move', t, id); fire('up', t, id); return } // pull a link wire source -> target\n    if (g.type === 'scratch') { // sweep the reveal target's bbox so its coverage reaches ~1\n      const id = g.id ?? 1\n      const b = itemBoundsByName(doc, g.target)\n      if (!b) throw new Error(`gesture: object \"${g.target}\" not found in the scene`)\n      const pts = sweepPoints(b, revealBrushFor(doc, g.target))\n      fire('down', pts[0], id)\n      for (let i = 1; i < pts.length; i++) fire('move', pts[i], id)\n      fire('up', pts[pts.length - 1], id)\n      return\n    }\n    if (g.type === 'expect') {\n      const got = sends.slice(sendCursor).map((s) => s.name) // sequence of send names emitted since the last expect\n      sendCursor = sends.length\n      if (g.sends && JSON.stringify(got) !== JSON.stringify(g.sends)) expectFailures.push(`expect: expected sends [${g.sends.join(', ')}], received [${got.join(', ')}]`)\n      if (g.vars) for (const [k, v] of Object.entries(g.vars)) { const cur = pl.getVar(k); if (JSON.stringify(cur) !== JSON.stringify(v)) expectFailures.push(`expect: ${k} expected ${JSON.stringify(v)}, got ${JSON.stringify(cur)}`) }\n      return\n    }\n    fire(g.type, { x: g.x, y: g.y }, g.id) // low-level (down/move/up/cancel)\n  }\n  try {\n    const steps: TraceStep[] = []\n    for (const g of gestures) {\n      if (!opts.trace) { applyGesture(g); continue }\n      const before = pl.allVars(), sIdx = sends.length\n      applyGesture(g)\n      const after = pl.allVars()\n      const changed: TraceStep['changed'] = {}\n      for (const k of new Set([...Object.keys(before), ...Object.keys(after)]))\n        if (JSON.stringify(before[k]) !== JSON.stringify(after[k])) changed[k] = [before[k], after[k]]\n      steps.push({ gesture: describeGesture(g), sends: sends.slice(sIdx), changed })\n    }\n    return { sends, vars: pl.allVars(), ...(opts.trace ? { steps } : {}), ...(expectFailures.length ? { expectFailures } : {}) }\n  } finally {\n    pl.destroy()\n    restore()\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+export { F as FlatPlayer, G as Gesture, P as PlayerOptions, s as sameOriginAssetResolver } from './player-Bxx8wsSa.js';
+import { Region, Doc, Item, Layer } from '@flatkit/types';
+export { Cel, Doc, Easing, Item, Keyframe, Layer, Path, Pose, Region, Seg, Subpath, Timeline, TimelineTrack } from '@flatkit/types';
+import { ExprContext } from '@flatkit/engine/expr';
+import { Transform } from '@flatkit/engine/transform';
+export { evaluateTimeline, resolveInstanceFrame } from '@flatkit/engine/timeline';
+export { resolveLayerAt } from '@flatkit/engine/cel';
+export { clonePath, pathBBox, pathToBezier, pathToPolygons, polygonsToPath, transformPath, translatePath } from '@flatkit/engine/path';
+
+/**
+ * Render context for a scope: fps (for `time` expressions) + expression context.
+ * `freezeNested` (EDITOR): we only animate the current scope; nested symbols are frozen
+ * at their frame 0 (their position follows the scope's tween, but their internal timeline does not play).
+ * The player leaves `freezeNested` absent -> full, composed animation.
+ */
+type RenderCtx = {
+    fps: number;
+    expr?: ExprContext;
+    freezeNested?: boolean;
+    image?: (assetId: string) => CanvasImageSource | null;
+    itemState?: (id: string) => {
+        hovered: number;
+        grabbed: number;
+        pressed: number;
+    } | undefined;
+    preview?: {
+        ids: Set<string>;
+        m: Transform;
+    };
+    filterCache?: Map<string, FilterCacheEntry>;
+    imageEpoch?: number;
+};
+/** Entry of the filtered composite cache: FINAL bitmap (content+tint+filter) in screen px at (ox,oy).
+ *  `canvas` absent = we have only RECORDED the signature (1 observation frame before baking) -- used
+ *  to NOT bake an object that moves every frame (unstable signature => we would always stay in miss). */
+type FilterCacheEntry = {
+    canvas?: HTMLCanvasElement;
+    sig: string;
+    ox: number;
+    oy: number;
+    ow: number;
+    oh: number;
+};
+declare function applyTransform(ctx: CanvasRenderingContext2D, t: Transform): void;
+/**
+ * Bezier path of a region (outline + holes), shiftable. Hybrid model: the
+ * subpaths without handles are smoothed (Catmull-Rom, matter look), those with handles
+ * render their literal cubic (see engine/path.ts).
+ */
+declare function regionPath(region: Region, dx?: number, dy?: number): Path2D;
+/** Draws a list of ALREADY RESOLVED items (poses applied) at a frame. */
+declare function renderItems(ctx: CanvasRenderingContext2D, doc: Doc, items: Item[], frame: number, hidden: Set<string> | null, seen: Set<string>, rctx: RenderCtx, parent?: Transform, depth?: number): void;
+/** Draws a stack of layers at a frame (each layer resolves its content via the cels). */
+declare function renderLayers(ctx: CanvasRenderingContext2D, doc: Doc, layers: Layer[], frame: number, hidden: Set<string> | null, seen: Set<string>, rctx: RenderCtx, parent?: Transform, // WORLD transform of the scope (for toLocal/toGlobal conversions in binding)
+depth?: number): void;
+
+export { applyTransform, regionPath, renderItems, renderLayers };

package/dist/index.js

@@ -0,0 +1,32 @@
+import {
+  FlatPlayer,
+  applyTransform,
+  regionPath,
+  renderItems,
+  renderLayers,
+  sameOriginAssetResolver
+} from "./chunk-BXKJAHHO.js";
+
+// src/index.ts
+import { evaluateTimeline, resolveInstanceFrame } from "@flatkit/engine/timeline";
+import { resolveLayerAt } from "@flatkit/engine/cel";
+import { polygonsToPath, pathToPolygons, pathToBezier, transformPath, translatePath, pathBBox, clonePath } from "@flatkit/engine/path";
+export {
+  FlatPlayer,
+  applyTransform,
+  clonePath,
+  evaluateTimeline,
+  pathBBox,
+  pathToBezier,
+  pathToPolygons,
+  polygonsToPath,
+  regionPath,
+  renderItems,
+  renderLayers,
+  resolveInstanceFrame,
+  resolveLayerAt,
+  sameOriginAssetResolver,
+  transformPath,
+  translatePath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// -----------------------------------------------------------------------------\n//  runtime/index.ts -- public surface of the FlatInk runtime (player + drawing core).\n//  Importable on its own, without anything from the editor. The played format = the FlatInk `Doc` JSON.\n// -----------------------------------------------------------------------------\nexport { FlatPlayer, sameOriginAssetResolver, type PlayerOptions } from './player'\n// `Gesture` stays here (FlatPlayer.stopRecording returns Gesture[]). The headless replay tools\n// (playHeadless, trace) live under `@flatkit/player/debug` — not needed for plain playback.\nexport type { Gesture } from './player'\nexport { renderLayers, renderItems, regionPath, applyTransform } from './drawScene'\nexport { evaluateTimeline, resolveInstanceFrame } from '@flatkit/engine/timeline'\nexport { resolveLayerAt } from '@flatkit/engine/cel'\nexport { polygonsToPath, pathToPolygons, pathToBezier, transformPath, translatePath, pathBBox, clonePath } from '@flatkit/engine/path'\nexport type { Doc, Timeline, TimelineTrack, Keyframe, Easing, Item, Layer, Region, Cel, Pose, Path, Subpath, Seg } from '@flatkit/types'\n"],"mappings":";;;;;;;;;;AASA,SAAS,kBAAkB,4BAA4B;AACvD,SAAS,sBAAsB;AAC/B,SAAS,gBAAgB,gBAAgB,cAAc,eAAe,eAAe,UAAU,iBAAiB;","names":[]}

package/dist/player-Bxx8wsSa.d.ts

@@ -0,0 +1,252 @@
+import { Doc, Asset, Point } from '@flatkit/types';
+
+/** A replayable gesture (`--play` / `--record` format). Coords in SCENE units. `id` = pointerId (default 1).
+ *  Prefer SEMANTIC gestures (`drag`/`tap` by object NAME): robust, readable, and it is the engine that
+ *  resolves the coords (cf. [[flatink-semantic-gestures]]). The low-level gestures remain for special cases. */
+type Gesture = {
+    type: 'drag';
+    source: string;
+    target: string;
+    id?: number;
+} | {
+    type: 'tap';
+    target: string;
+    id?: number;
+} | {
+    type: 'scratch';
+    target: string;
+    id?: number;
+} | {
+    type: 'connect';
+    source: string;
+    target: string;
+    id?: number;
+} | {
+    type: 'down' | 'move' | 'up' | 'cancel';
+    x: number;
+    y: number;
+    id?: number;
+} | {
+    type: 'set';
+    name: string;
+    value: number;
+} | {
+    type: 'wait';
+    frames: number;
+} | {
+    type: 'expect';
+    sends?: string[];
+    vars?: Record<string, number | number[]>;
+};
+type PlayerOptions = {
+    autoplay?: boolean;
+    loop?: boolean;
+    padding?: number;
+    audio?: boolean;
+    input?: boolean;
+    render?: boolean;
+    image?: (assetId: string) => CanvasImageSource | null;
+    resolveAsset?: (asset: Asset) => string | null;
+    onEvent?: (event: {
+        name: string;
+        value?: number | string;
+    }) => void;
+};
+/**
+ * Resolver for EXTERNAL (non-embedded) assets. Pass it as `PlayerOptions.resolveAsset` to serve media from
+ * a host-controlled folder instead of embedding everything as `data:`. It treats `asset.data` as a RELATIVE
+ * key, resolves it against the host-trusted `baseUrl`, and returns the URL only if it stays SAME-ORIGIN as
+ * baseUrl. An embedded `data:` URI is passed through; any absolute URL / scheme / protocol-relative `//host`
+ * in `asset.data` (a document trying to pick its own origin) yields null. The HOST owns the origin; the
+ * untrusted document only supplies a key — so the no-arbitrary-fetch contract still holds.
+ */
+declare function sameOriginAssetResolver(baseUrl: string): (asset: Asset) => string | null;
+declare class FlatPlayer {
+    private readonly canvas;
+    private readonly ctx;
+    private doc;
+    private readonly loop;
+    private readonly pad;
+    private dpr;
+    private cssW;
+    private cssH;
+    private view;
+    private frame;
+    private playing;
+    private raf;
+    private last;
+    private simAcc;
+    private prevSimVars;
+    private simAlpha;
+    private simActive;
+    private audioOn;
+    private readonly onEvent?;
+    private renderOn;
+    private readonly imageProvider?;
+    private readonly resolveAsset;
+    private recording;
+    private recordFrame;
+    private readonly filterCache;
+    private imageEpoch;
+    private activeSources;
+    private vars;
+    private procs;
+    private valueFuncs;
+    private funcDepth;
+    private readonly mouse;
+    private readonly heldKeys;
+    private readonly keyProxy;
+    private hovered;
+    private hoverIds;
+    private selfChannels;
+    private selfParent;
+    private namedCache;
+    private namedFrame;
+    private grabbed;
+    private grabStart;
+    private dragActive;
+    private readonly revealStates;
+    private longPressTimer;
+    private lastFrameInt;
+    private readonly onResize;
+    /** Invalidates the named-objects cache (input changed outside of a frame advance). */
+    private bustNamed;
+    private readonly onKeyDown;
+    private readonly onKeyUp;
+    private readonly onPointerLeave;
+    private worldPoint;
+    /**
+     * Target of an event at a point: we walk ALL the hit chains (top to bottom) and, within each,
+     * from deepest to root. The first item carrying a handler for `event` wins. This way a click
+     * "falls through" a non-interactive item placed on top down to the clickable one below, instead
+     * of being swallowed by it.
+     */
+    private pickTarget;
+    private interactorFor;
+    /** Is the drag active? `enabled` absent = always; otherwise true iff the expression is != 0. */
+    private interactorEnabled;
+    /** Topmost grabbable item carrying an ACTIVE (drag) interactor, at a point. */
+    private pickInteractor;
+    /** Applies the current drag: position = pointer + grab offset, then snap, then confine; writes varX/varY.
+     *  Snap/confine are in WORLD space (where the visual grid and the zone bbox live); the result is brought back into
+     *  the object's PARENT space (`parentInv` cached at grab time -- no scene walk per movement). */
+    /** Writes a gesture output: simple variable `name`, or array element `name[idx]` (idx is EVALUATED).
+     *  The indexed form is the natural output under `each` (e.g. `drag hx[i], hy[i]` -> `hx[0]`... after unfolding). */
+    private writeOut;
+    private applyDrag;
+    /** Reveal state for a target: the grid of cells (side = brush) over its WORLD bbox, with the ticked cells
+     *  PERSISTED across grabs (`revealStates`) so coverage accumulates monotonically over several strokes. */
+    private revealGridFor;
+    /** On release of a `link`: 1st target (named child of the group) containing the pointer -> index 1..n (0 = none).
+     *  If linked, the wire end (endX/endY) sticks to the target center; otherwise it stays at the pointer (the author handles
+     *  the "return" via target == 0). Several links coexist: one `link` interactor per source object. */
+    private resolveLink;
+    /** On release: `when dropped on Zone` whose tested point falls within the zone bbox.
+     *  Tested point = the object's CENTER by default, or the POINTER if `at pointer`. Zone = the group's
+     *  explicit `hitbox` if present, otherwise the (static) bbox of its content. */
+    private fireDrops;
+    private fireEvent;
+    private readonly onPointerMove;
+    private readonly onPointerDown;
+    private readonly onPointerUp;
+    private readonly onPointerCancel;
+    private cancelLongPress;
+    private clearGrab;
+    /** Surface exposed to the action interpreter (frame-actions, future onClick). */
+    private readonly host;
+    constructor(canvas: HTMLCanvasElement, doc: Doc, opts?: PlayerOptions);
+    /**
+     * Timelines of "active" symbols (referenced by >=1 instance), deduplicated,
+     * with a representative local frame. NB (v1): single playhead -> the symbol
+     * actions share the global state; gotoFrame/play acts on the root.
+     */
+    private activeSymbolTimelines;
+    /** Actions on load (onLoad): root + active symbols. */
+    private fireLoad;
+    /** (Re)compiles the available functions: imported packages (`use ...`) + doc functions (`fn ...`,
+     *  which TAKE PRECEDENCE on a name clash). -> procedures + value functions. */
+    private buildFunctions;
+    /** Calls a procedure `fn name(p) { ... }`: binds the params (save/restore), bounds the recursion. */
+    private callProc;
+    /** Runtime context for expressions: variables (flattened), mouse, keys, random, value functions,
+     *  + scene objects by name (`Hero.x`, cf. sceneRefs). */
+    private exprCtx;
+    private evalNumber;
+    /**
+     * Emits a `send` event toward the host. Silent no-op if no `onEvent` is provided
+     * (e.g. editor preview). Defense-in-depth validation (the parser already guarantees the name):
+     * conforming name, finite number (NaN -> 0, DSL convention), text <= MAX_SEND_TEXT (truncated).
+     * If the host callback throws, we catch and log -- the player does not break.
+     */
+    private emit;
+    /** Live content of a Text item resolved by id OR name (for `text("...")`). `''` + warning if absent. */
+    private textContent;
+    /**
+     * Looks up a Text item in the scene (layers + groups) and the library symbols.
+     * Resolves by `id` first (stable id set via `text "..." as "<id>"`), then by `name` as a fallback --
+     * like the rest of the text format references by name (`object "x"`, `instance "Sym" as "y"`).
+     */
+    private findText;
+    /** Plays an audio clip (asset) as a one-shot (`sound "id"` DSL). No-op if audio is off / asset absent. */
+    private playSound;
+    get fps(): number;
+    get duration(): number;
+    get currentFrame(): number;
+    get isPlaying(): boolean;
+    /**
+     * Reads a state variable (Layer B) from the host: score, difficulty... `undefined` if absent.
+     * Returns a COPY of the arrays (the host cannot mutate the internal state by reference).
+     */
+    getVar(name: string): number | number[] | undefined;
+    /** Snapshot (copied) of all the state variables -- for debugging / the headless harness. */
+    allVars(): Record<string, number | number[]>;
+    /** Starts recording (clears the previous one). Play the activity by hand, then `stopRecording()`. */
+    startRecording(): void;
+    /** Stops recording and returns the gesture script (replayable by `--play` / `playHeadless`). */
+    stopRecording(): Gesture[];
+    get isRecording(): boolean;
+    /** Center (RESOLVED origin, expressions included) of a named object, in world coords -- for the
+     *  semantic gestures `drag`/`tap` by name. `null` if the object does not exist. */
+    objectCenter(name: string): Point | null;
+    /** Captures a gesture (no-op outside recording). Inserts a `wait` = frames elapsed since the last gesture. */
+    private record;
+    /**
+     * Writes a state variable (Layer B) from the host, then redraws -> bidirectional
+     * driving channel (the host sets the difficulty, injects a value, etc.). Clones the arrays.
+     */
+    setVar(name: string, value: number | number[]): void;
+    /** Replaces the played document (resets the framing + the variables, keeps the frame). */
+    load(doc: Doc): void;
+    private measure;
+    /** Draws the current frame (pure, without advancing time). */
+    render(): void;
+    /** Interaction state of an item for `self.hovered`/`self.grabbed`/`self.pressed` in its channel exprs.
+     *  Returns undefined when the item is neither hovered nor grabbed (the cheap, common path → flags 0). */
+    private itemStateFor;
+    private imageFor;
+    seek(frame: number): void;
+    /**
+     * Advances the simulation by `steps` FIXED steps (60 Hz) without RAF: runs `onEnterFrame`
+     * (root + active symbols) and advances the playhead as if real time elapsed.
+     * Used by the headless mode (`--play`, `wait` gesture) to let a physics simulation
+     * unfold between two gestures -- in Node, requestAnimationFrame does not exist.
+     */
+    stepSim(steps: number): void;
+    get audioEnabled(): boolean;
+    /** Enables/disables audio (cuts immediately if off; (re)starts if on and playing). */
+    setAudio(on: boolean): void;
+    private stopAudio;
+    private decodeAudio;
+    /** (Re)schedules the audio clips for a playback starting from `fromFrame`. */
+    private startAudio;
+    /** Triggers the frame-actions when the playhead enters a new whole frame. */
+    private fireFrameActions;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    stop(): void;
+    /** Releases the listeners. To be called when the player is no longer used. */
+    destroy(): void;
+}
+
+export { FlatPlayer as F, type Gesture as G, type PlayerOptions as P, sameOriginAssetResolver as s };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@flatkit/player",
+  "version": "0.1.0",
+  "description": "The lightweight FlatInk player: load a .flatpack and play it in a <canvas>. No editor, no heavy deps.",
+  "license": "MIT",
+  "author": "Zwyk Studio",
+  "homepage": "http://flatink.zwyk-studio.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zwykstudio/flatkit.git",
+    "directory": "packages/player"
+  },
+  "bugs": "https://github.com/zwykstudio/flatkit/issues",
+  "keywords": [
+    "flatink",
+    "flatpack",
+    "animation",
+    "canvas",
+    "player",
+    "interactive"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./debug": {
+      "types": "./dist/debug.d.ts",
+      "import": "./dist/debug.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@flatkit/engine": "0.1.0",
+    "@flatkit/types": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "module": "./dist/index.js"
+}