animl 0.0.0-stage → 0.1.1

package/packages/core/src/modules.d.ts

@@ -0,0 +1,65 @@
+import { type ElementForm, DOC, FILL, STROKE, PAINT, PAINTED, nodeShape, type Prop, type Shape } from './registry.js';
+import type { Diags } from './diag.js';
+import { load, inputExpression, resolveAddress, type Addr, type Model, type NodeM, type Value } from './load.js';
+import { Player, sampleTrack, mixValues } from './player.js';
+import type { DrawTree, DrawNode, DrawEntry, DrawFrame } from './draw.js';
+export interface ModuleEntry {
+    target: string;
+    /** Declare a new node type; load/draw hooks compile or resolve its geometry. */
+    node?: {
+        painted?: boolean;
+    };
+    shapes: Record<string, Shape>;
+    props?: Record<string, Prop>;
+    required?: string[];
+    elements?: Record<string, ElementForm>;
+}
+export interface ModuleRegistry {
+    DOC: typeof DOC;
+    nodeShape: typeof nodeShape;
+    load: typeof load;
+    Player: typeof Player;
+    sampleTrack: typeof sampleTrack;
+    mixValues: typeof mixValues;
+    resolveAddress: typeof resolveAddress;
+    inputExpression: typeof inputExpression;
+    PAINTED: typeof PAINTED;
+    FILL: typeof FILL;
+    STROKE: typeof STROKE;
+    PAINT: typeof PAINT;
+}
+export interface Module {
+    name: string;
+    /** Ordering constraints among the modules present, not implicit imports. */
+    after?: readonly string[];
+    init?(registry: ReadonlyMap<string, Module>, shapes: ModuleRegistry): Module;
+    entries: ModuleEntry[];
+    expression?(source: string, types: ReadonlyMap<string, string>, expected: string, pointer: string, diag: Diags, read?: (name: string) => void): ((scope: ReadonlyMap<string, Value>) => Value) | undefined;
+    ease?(source: string, pointer: string, diag: Diags): import('./ease.js').EaseFn | undefined;
+    track?(track: import('./load.js').TrackM, addr: Addr, keys: unknown[][], pointer: string, diag: Diags): void;
+    prepare?(model: Model, diag: Diags): void;
+    resolve?(model: Model, diag: Diags): void;
+    load?(model: Model, raw: Model['doc'], diag: Diags): void;
+    /** Resolve additional addresses to the existing number/colour/bool sampling slots. */
+    model?(node: NodeM, key: string): Pick<Addr, 'prop' | 'rest'> | undefined;
+    value?(addr: Addr, value: unknown, pointer: string, diag: Diags): Value | undefined;
+    outline?(player: Player, node: number): {
+        pts: number[];
+        closed: boolean;
+    }[] | undefined;
+    /** Override fill containment in local coordinates, preserving the stroke/padding outline. */
+    fillContains?(player: Player, node: number, outline: {
+        pts: number[];
+        closed: boolean;
+    }[], x: number, y: number): boolean | undefined;
+    interpolate?(a: Value, b: Value, weight: number): Value | undefined;
+    draw?: {
+        end?(player: Player, frame: DrawFrame): void;
+        tree?(model: Model, tree: DrawTree): void;
+        frame?(player: Player, node: number, data: DrawNode, entry: DrawEntry, frame: DrawFrame): void;
+    };
+}
+export declare const modules: Map<string, Module>;
+export declare const FEATURES: string[];
+/** Idempotent by name; compose from declarations, independent of arrival order. */
+export declare function registerModule(m: Module): void;

package/packages/core/src/modules.js

@@ -0,0 +1,103 @@
+import {
+  resetRegistry,
+  TIMELINE,
+  STATE,
+  TRANSITION,
+  ELEMENTS,
+  DOC,
+  FILL,
+  STROKE,
+  PAINT,
+  OWN,
+  STATIC,
+  NODE_TYPES,
+  PAINTED,
+  nodeShape
+} from "./registry.js";
+import {
+  load,
+  inputExpression,
+  resolveAddress
+} from "./load.js";
+import { Player, sampleTrack, mixValues } from "./player.js";
+const modules = /* @__PURE__ */ new Map();
+const FEATURES = ["knockout"];
+const declarations = /* @__PURE__ */ new Map();
+function registerModule(m) {
+  if (!/^[a-z][a-z0-9]*(?:@[1-9]\d*)?$/.test(m.name)) throw new Error("invalid module name");
+  if (declarations.has(m.name)) return;
+  declarations.set(m.name, m);
+  const pending = new Map([...declarations].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+  const ordered = [];
+  while (pending.size) {
+    const ready = [...pending.values()].find(
+      (m2) => (m2.after ?? []).every((name) => !pending.has(name))
+    );
+    if (!ready) {
+      declarations.delete(m.name);
+      throw new Error("module dependency cycle");
+    }
+    ordered.push(ready);
+    pending.delete(ready.name);
+  }
+  resetRegistry();
+  for (const key of Object.keys(ELEMENTS)) Reflect.deleteProperty(ELEMENTS, key);
+  modules.clear();
+  FEATURES.splice(1);
+  for (let module of ordered) {
+    module = module.init?.(modules, {
+      DOC,
+      nodeShape,
+      PAINTED,
+      FILL,
+      STROKE,
+      PAINT,
+      resolveAddress,
+      inputExpression,
+      load,
+      Player,
+      sampleTrack,
+      mixValues
+    }) ?? module;
+    modules.set(module.name, module);
+    FEATURES.push(module.name, ...module.name.includes("@") ? [module.name.split("@")[0]] : []);
+    for (const e of module.entries) {
+      const targets = e.target === "node" ? NODE_TYPES : e.target === "painted" ? PAINTED : [e.target];
+      for (const target of targets) applyEntry(module, e, target);
+    }
+  }
+  for (const module of modules.values())
+    for (const e of module.entries) {
+      if (e.target === "node" || e.target === "painted")
+        for (const target of e.target === "node" ? NODE_TYPES : PAINTED)
+          applyEntry(module, e, target);
+    }
+}
+function applyEntry(m, e, target) {
+  const type = target;
+  if (e.node && !NODE_TYPES.includes(type)) {
+    NODE_TYPES.push(type);
+    OWN[type] = {};
+    STATIC[type] = {};
+    if (e.node.painted) PAINTED.push(type);
+  }
+  if (NODE_TYPES.includes(type)) {
+    for (const [k, v] of Object.entries(e.shapes)) if (!e.props?.[k]) STATIC[type][k] = v;
+  }
+  if (e.props)
+    for (const [k, v] of Object.entries(e.props))
+      (PAINT[target] ?? OWN[target])[k] = {
+        ...v,
+        feature: m.name
+      };
+  const s = target === "fill" ? FILL : target === "stroke" ? STROKE : target === "timeline" ? TIMELINE : target === "state" ? STATE : target === "transition" ? TRANSITION : target === "document" ? DOC : target === "layer" ? DOC.p.machine.p.layers.of : target === "listener" ? DOC.p.listeners.of : nodeShape(target);
+  if (e.node) s.p.type = { ...s.p.type, feature: m.name };
+  for (const [k, v] of Object.entries(e.shapes)) s.p[k] = { ...v, feature: v.feature ?? m.name };
+  Object.assign(ELEMENTS, e.elements);
+  if (e.required) s.req = e.required;
+}
+export {
+  FEATURES,
+  modules,
+  registerModule
+};

package/packages/core/src/path.d.ts

@@ -0,0 +1,47 @@
+/** Segment opcodes in `Subpath.segs`: M x y, L x y, C x1 y1 x2 y2 x y, Z. */
+export declare const M = 0;
+export declare const L = 1;
+export declare const C = 2;
+export declare const Z = 3;
+export interface Subpath {
+    /** Source text range [start, end) of this subpath in the original `d`. */
+    start: number;
+    end: number;
+    /** True when the source slice can stand alone (it starts with an absolute `M`). */
+    absolute: boolean;
+    /** Flat list: opcode followed by its absolute coordinates. */
+    segs: number[];
+}
+export declare class PathError extends Error {
+    readonly at: number;
+    constructor(message: string, at: number);
+}
+/** Parse path data. Throws `PathError` with the offending offset. */
+export declare function parsePath(d: string): Subpath[];
+/** Serialise subpaths to absolute M/L/C/Z path data. */
+export declare function formatSegs(subpaths: Subpath[]): string;
+/**
+ * Path data for a selection of subpaths. When every selected subpath can stand alone in the
+ * source, the result is made of source slices, so selecting all of a Glyphy path returns its
+ * `d` byte for byte (spec §1.2).
+ */
+export declare function selectPath(d: string, all: Subpath[], pick?: readonly number[]): string;
+/** Resolve geometry and source-preserving path data together, sorting the selection once. */
+export declare function selectSubpaths(d: string, all: Subpath[], pick?: readonly number[]): {
+    geom: Subpath[];
+    d: string;
+};
+/**
+ * Flatten subpaths into closed polylines (for hit testing): one flat [x0, y0, x1, y1, …] array per
+ * subpath, curves subdivided into `steps` chords.
+ */
+export declare function flatten(subpaths: Subpath[], steps?: number, tolerance?: number): {
+    pts: number[];
+    closed: boolean;
+}[];
+/**
+ * Natural outline length in local grid units. Cubics use de Casteljau subdivision until
+ * control-polygon length minus chord ≤ tolerance (0.0001 grid units), or depth 20.
+ * Each accepted chord uses (polygon + chord)/2. Arcs use parsePath's ≤90° cubic conversion.
+ */
+export declare function pathLength(d: string, tolerance?: number): number;

package/packages/core/src/path.js

@@ -0,0 +1,288 @@
+import { VERBOSE as V } from "./flags.js";
+const M = 0;
+const L = 1;
+const C = 2;
+const Z = 3;
+class PathError extends Error {
+  at;
+  constructor(message, at) {
+    super(message);
+    this.at = at;
+  }
+}
+const ARGS = { m: 2, l: 2, h: 1, v: 1, c: 6, s: 4, q: 4, t: 2, a: 7, z: 0 };
+const NUM = /[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/y;
+function parsePath(d) {
+  const out = [];
+  let i = 0;
+  const n = d.length;
+  const fail = (message, at = i) => {
+    throw new PathError(message, at);
+  };
+  const ws = () => {
+    while (i < n && /[\s,]/.test(d[i])) i++;
+  };
+  const num = () => {
+    ws();
+    NUM.lastIndex = i;
+    const m = NUM.exec(d);
+    if (!m || !isFinite(+m[0])) return fail(V ? "expected a finite number" : "");
+    i += m[0].length;
+    return +m[0];
+  };
+  const flag = () => {
+    ws();
+    const c = d[i++];
+    return c === "0" || c === "1" ? +c : fail(V ? "expected an arc flag (0 or 1)" : "", i - 1);
+  };
+  let cur;
+  let x = 0, y = 0, sx = 0, sy = 0;
+  let cx = 0, cy = 0;
+  let prev = "";
+  let cmd = "";
+  const seg = (op, ...v) => cur.segs.push(op, ...v);
+  ws();
+  while (i < n) {
+    const ch = d[i];
+    if (/[a-z]/i.test(ch)) {
+      if (!(ch.toLowerCase() in ARGS)) fail(V ? `unknown command "${ch}"` : "");
+      cmd = ch;
+      i++;
+    } else if (!cmd) fail(V ? "path data must start with a moveto" : "");
+    else if (cmd === "z" || cmd === "Z") fail(V ? "closepath takes no arguments" : "");
+    const lc = cmd.toLowerCase();
+    const rel = cmd === lc;
+    if (!cur && lc !== "m") fail(V ? "path data must start with a moveto" : "", i - 1);
+    const start = i - 1;
+    const a = [];
+    for (let k = 0; k < ARGS[lc]; k++) a.push(lc === "a" && (k === 3 || k === 4) ? flag() : num());
+    const ox = rel ? x : 0;
+    const oy = rel ? y : 0;
+    if (lc === "a") {
+      a[5] += ox;
+      a[6] += oy;
+    } else if (lc === "v") a[0] += oy;
+    else a.forEach((v, k) => a[k] = v + (k % 2 ? oy : ox));
+    if (lc === "s" || lc === "t")
+      a.unshift(...(lc === "s" ? /[cs]/ : /[qt]/).test(prev) ? [2 * x - cx, 2 * y - cy] : [x, y]);
+    if (lc === "m") {
+      if (cur) cur.end = start;
+      cur = { start, end: n, absolute: !rel, segs: [] };
+      out.push(cur);
+      seg(M, x = sx = a[0], y = sy = a[1]);
+      cmd = rel ? "l" : "L";
+    } else if (lc === "z") {
+      seg(Z);
+      x = sx;
+      y = sy;
+    } else if (lc === "c" || lc === "s") {
+      seg(C, ...a);
+      [cx, cy, x, y] = a.slice(2);
+    } else if (lc === "q" || lc === "t") {
+      const [qx, qy, ex, ey] = a;
+      seg(
+        C,
+        x + 2 / 3 * (qx - x),
+        y + 2 / 3 * (qy - y),
+        ex + 2 / 3 * (qx - ex),
+        ey + 2 / 3 * (qy - ey),
+        ex,
+        ey
+      );
+      [cx, cy, x, y] = a;
+    } else if (lc === "a") {
+      arcToCubics(x, y, a, cur.segs);
+      x = a[5];
+      y = a[6];
+    } else {
+      if (lc === "h") a.push(y);
+      if (lc === "v") a.unshift(x);
+      seg(L, x = a[0], y = a[1]);
+    }
+    prev = lc === "m" ? "l" : lc;
+    ws();
+  }
+  if (!out.length) fail(V ? "empty path data" : "", 0);
+  return out;
+}
+function arcToCubics(x1, y1, arc, segs) {
+  const [, , phiDeg, fa, fs, x2, y2] = arc;
+  let rx = Math.abs(arc[0]);
+  let ry = Math.abs(arc[1]);
+  if (x1 === x2 && y1 === y2 || !rx || !ry) {
+    if (x1 !== x2 || y1 !== y2) segs.push(L, x2, y2);
+    return;
+  }
+  const phi = phiDeg * Math.PI / 180;
+  const cos = Math.cos(phi);
+  const sin = Math.sin(phi);
+  const dx = (x1 - x2) / 2;
+  const dy = (y1 - y2) / 2;
+  const xp = cos * dx + sin * dy;
+  const yp = -sin * dx + cos * dy;
+  const lam = xp * xp / (rx * rx) + yp * yp / (ry * ry);
+  if (lam > 1) {
+    rx *= Math.sqrt(lam);
+    ry *= Math.sqrt(lam);
+  }
+  const num = rx * rx * ry * ry - rx * rx * yp * yp - ry * ry * xp * xp;
+  const den = rx * rx * yp * yp + ry * ry * xp * xp;
+  const k = (fa === fs ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+  const cxp = k * rx * yp / ry;
+  const cyp = -k * ry * xp / rx;
+  const ccx = cos * cxp - sin * cyp + (x1 + x2) / 2;
+  const ccy = sin * cxp + cos * cyp + (y1 + y2) / 2;
+  const ang = (ux, uy, vx, vy) => Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+  const t1 = ang(1, 0, (xp - cxp) / rx, (yp - cyp) / ry);
+  let dt = ang((xp - cxp) / rx, (yp - cyp) / ry, (-xp - cxp) / rx, (-yp - cyp) / ry);
+  if (!fs && dt > 0) dt -= 2 * Math.PI;
+  if (fs && dt < 0) dt += 2 * Math.PI;
+  const pieces = Math.ceil(Math.abs(dt) / (Math.PI / 2) - 1e-9);
+  const step = dt / pieces;
+  const kk = 4 / 3 * Math.tan(step / 4);
+  const pt = (t) => {
+    const c = Math.cos(t), s = Math.sin(t);
+    return [
+      ccx + rx * c * cos - ry * s * sin,
+      ccy + rx * c * sin + ry * s * cos,
+      -rx * s * cos - ry * c * sin,
+      -rx * s * sin + ry * c * cos
+    ];
+  };
+  for (let p = 0; p < pieces; p++) {
+    const a = pt(t1 + p * step);
+    const b = pt(t1 + (p + 1) * step);
+    const end = p === pieces - 1 ? [x2, y2] : [b[0], b[1]];
+    segs.push(
+      C,
+      a[0] + kk * a[2],
+      a[1] + kk * a[3],
+      b[0] - kk * b[2],
+      b[1] - kk * b[3],
+      end[0],
+      end[1]
+    );
+  }
+}
+const fmt = (v) => String(Math.round(v * 1e4) / 1e4 || 0);
+function formatSegs(subpaths) {
+  let s = "";
+  for (const sp of subpaths) {
+    const g = sp.segs;
+    for (let i = 0; i < g.length; ) {
+      const op = g[i++];
+      const k = op === C ? 6 : op === Z ? 0 : 2;
+      s += "MLCZ"[op] + g.slice(i, i + k).map(fmt).join(" ");
+      i += k;
+    }
+  }
+  return s;
+}
+function selectPath(d, all, pick) {
+  return selectSubpaths(d, all, pick).d;
+}
+function selectSubpaths(d, all, pick) {
+  const geom = pick ? [...pick].sort((a, b) => a - b).map((i) => all[i]) : all;
+  return {
+    geom,
+    d: geom.length === all.length ? d : geom.every((sp) => sp.absolute) ? geom.map((sp) => d.slice(sp.start, sp.end).trim()).join("") : formatSegs(geom)
+  };
+}
+function flatten(subpaths, steps = 12, tolerance = Infinity) {
+  const out = [];
+  for (const sp of subpaths) {
+    const g = sp.segs;
+    let pts = [];
+    let closed = false;
+    let x = 0, y = 0, sx = 0, sy = 0;
+    for (let i = 0; i < g.length; ) {
+      const op = g[i++];
+      if (closed && op !== M) {
+        out.push({ pts, closed });
+        pts = [x, y];
+        closed = false;
+      }
+      if (op === M) {
+        if (pts.length) out.push({ pts, closed });
+        pts = [sx = x = g[i++], sy = y = g[i++]];
+        closed = false;
+      } else if (op === L) {
+        pts.push(x = g[i++], y = g[i++]);
+      } else if (op === C) {
+        const [x1, y1, x2, y2, x3, y3] = g.slice(i, i += 6);
+        const n = Math.min(
+          1e4,
+          Math.max(
+            steps,
+            Math.ceil(
+              Math.sqrt(
+                0.75 * Math.max(
+                  Math.hypot(x - 2 * x1 + x2, y - 2 * y1 + y2),
+                  Math.hypot(x1 - 2 * x2 + x3, y1 - 2 * y2 + y3)
+                ) / tolerance
+              )
+            ) || 0
+            // NaN when coordinates overflow
+          )
+        );
+        for (let k = 1; k <= n; k++) {
+          const t = k / n, r = 1 - t;
+          pts.push(
+            r * r * r * x + 3 * r * r * t * x1 + 3 * r * t * t * x2 + t * t * t * x3,
+            r * r * r * y + 3 * r * r * t * y1 + 3 * r * t * t * y2 + t * t * t * y3
+          );
+        }
+        x = x3;
+        y = y3;
+      } else {
+        closed = true;
+        x = sx;
+        y = sy;
+      }
+    }
+    if (pts.length) out.push({ pts, closed });
+  }
+  return out;
+}
+function pathLength(d, tolerance = 1e-4) {
+  const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+  const mid = (a, b) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+  const cubic = (a, b, c, e, depth) => {
+    const chord = dist(a, e), polygon = dist(a, b) + dist(b, c) + dist(c, e);
+    if (depth === 20 || polygon - chord <= tolerance) return (polygon + chord) / 2;
+    const ab = mid(a, b), bc = mid(b, c), ce = mid(c, e), abc = mid(ab, bc), bce = mid(bc, ce), centre = mid(abc, bce);
+    return cubic(a, ab, abc, centre, depth + 1) + cubic(centre, bce, ce, e, depth + 1);
+  };
+  let total = 0;
+  for (const sp of parsePath(d)) {
+    let at = [0, 0], start = at;
+    for (let i = 0; i < sp.segs.length; ) {
+      const op = sp.segs[i++];
+      if (op === Z) {
+        total += dist(at, start);
+        at = start;
+        continue;
+      }
+      const end = sp.segs.slice(i + (op === C ? 4 : 0), i + (op === C ? 6 : 2));
+      if (op === M) start = end;
+      else
+        total += op === C ? cubic(at, sp.segs.slice(i, i + 2), sp.segs.slice(i + 2, i + 4), end, 0) : dist(at, end);
+      at = end;
+      i += op === C ? 6 : 2;
+    }
+  }
+  return total;
+}
+export {
+  C,
+  L,
+  M,
+  PathError,
+  Z,
+  flatten,
+  formatSegs,
+  parsePath,
+  pathLength,
+  selectPath,
+  selectSubpaths
+};

package/packages/core/src/player.d.ts

@@ -0,0 +1,109 @@
+import { type Mat } from './geom.js';
+import type { ListenerM, Model, PlaybackPolicy, TrackM, Value } from './load.js';
+import { type DrawFrame } from './draw.js';
+import type { RandomSource } from './random.js';
+export interface AnimaEvent {
+    name: string;
+    layer: string | null;
+    time: number;
+    payload?: Record<string, number | boolean | string>;
+    url?: string;
+    target?: string;
+    audio?: string;
+    volume?: number;
+}
+export interface LayerInspect {
+    layer: string;
+    state: string;
+    prev: string | null;
+    blend: number | null;
+    locked: boolean;
+    timeline: string | null;
+    time: number | null;
+}
+export interface StepResult {
+    events: AnimaEvent[];
+    settled: boolean;
+}
+/** Optional nested-player seam; implemented entirely by the components module. */
+export interface PlayerExtension {
+    input(op: string, name: string, value?: Value): boolean;
+    get(name: string): Value | undefined;
+    states(): Record<string, string>;
+    values(): Record<string, number | boolean | string | [number, number]>;
+    inspect(): LayerInspect[];
+    pointer(kind: PointerKind, x: number, y: number): void;
+    hits(node: number, x: number, y: number): boolean | undefined;
+    step(dt: number): StepResult;
+}
+export type PointerKind = 'move' | 'down' | 'up' | 'leave';
+/** Spec §5 sampling. */
+export declare function sampleTrack(tr: TrackM, t: number, player?: Player): Value;
+export declare const mixValues: (a: Value, b: Value, w: number) => Value;
+export declare class Player {
+    #private;
+    skinPoints?: (node: number, xy: number[]) => void;
+    /** Installed by random-capable modules; the base runtime does not allocate a source. */
+    readonly randomSource: RandomSource;
+    readonly seed?: number;
+    readonly model: Model;
+    readonly playbackPolicy?: PlaybackPolicy;
+    /** Optional module wake callback, installed by a host. */
+    onChange?: () => void;
+    readonly nested?: PlayerExtension;
+    /** Animated addresses, in slot order. */
+    readonly addrs: string[];
+    /** Draw consumers track changes independently of takeDirty(). */
+    readonly drawVersions: number[];
+    drawRevision: number;
+    /** Renderer cache; step output and dirty-slot reads do not depend on it. */
+    drawData?: import('./draw.js').DrawFrame;
+    /** Reduced motion (spec §10): re-resolves active play states at the next step. */
+    reducedMotion: boolean;
+    /** Total step time. */
+    time: number;
+    constructor(model: Model, opts?: {
+        reducedMotion?: boolean;
+        seed?: number;
+    });
+    /** Queue a write to a bool or number input (applied by the next step). */
+    set(name: string, value: Value): void;
+    fire(name: string): void;
+    toggle(name: string): void;
+    /** Current value of a bool or number input (before queued writes). */
+    get(name: string): Value | undefined;
+    get busy(): boolean;
+    /** Current state of each layer. */
+    states(): Record<string, string>;
+    /**
+     * Per layer, what an inspector shows: the current and previous state, the blend in progress
+     * (0–1, or null when none; `locked` when it is non-interruptible), and the timeline the state
+     * plays with its local time.
+     */
+    inspect(): LayerInspect[];
+    /** Resolved value of an animated address, colours as hex. */
+    value(addr: string): number | boolean | string | [number, number] | undefined;
+    /** Every animated address and its resolved value. */
+    values(): Record<string, number | boolean | string | [number, number]>;
+    /** Addresses contributed by the current layers, including fading-out writes. */
+    writes(): string[];
+    /** Slots changed since the last call. */
+    takeDirty(): number[];
+    /** A node property's current value (animated or rest), by key (`rotate`, `fill.color`, …). */
+    prop(node: number, key: string): Value | string | undefined;
+    /** A numeric node property, or `def` when the document leaves it out. */
+    num(node: number, key: string, def: number): number;
+    /** The node's local matrix from its current values (spec §4). */
+    local(node: number): Mat;
+    /** Optional resolved-geometry source for modules that allocate geometry. */
+    hitFrame?: () => DrawFrame;
+    world(node: number): Mat;
+    visible(node: number): boolean;
+    /** Report a pointer event in grid units. Listener actions are queued for the next step. */
+    pointer(kind: PointerKind, x?: number, y?: number): void;
+    /** Queue an already validated listener, including actions routed by an optional module. */
+    act(l: ListenerM): void;
+    /** Does the listener's target contain the point? */
+    hits(l: ListenerM, x: number, y: number): boolean;
+    step(dt: number, base?: (address: string) => Value | undefined): StepResult;
+}