dsviz 0.0.0-stage → 2.0.0

package/dist/mem/stackHeap.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/mem/stackHeap.ts"],
+  "sourcesContent": ["/**\n * Python-Tutor-style memory pictures: stack frames on the left, heap objects\n * on the right, and an arrow for every reference.\n *\n * The thing this makes visible is ALIASING. `b = a` doesn't copy a list; it\n * adds a second arrow to the same object. `b.append(3)` then changes what `a`\n * points at too, and you can see why.\n *\n * Primitives (numbers, strings, None) are drawn inline in their slot. A\n * `{ ref: 'id' }` value draws a dot in the slot and an arrow to heap object `id`.\n */\nimport { Scene, SceneNode, Tone, arrow, circle, estimateTextWidth, rect, text } from '../scene';\nimport { V2, Vec } from '../vec';\n\nexport type MemValue = number | string | boolean | null | { ref: string };\n\nexport interface StackFrame {\n  name: string;\n  vars: ReadonlyArray<{ name: string; value: MemValue }>;\n}\n\nexport interface HeapObject {\n  id: string;\n  /** Shown above the object: 'list', 'tuple', 'dict', a class name\u2026 */\n  kind: string;\n  /** Sequence items, or [key, value] pairs for dicts / instances. */\n  items: ReadonlyArray<MemValue> | ReadonlyArray<readonly [string, MemValue]>;\n}\n\nexport interface StackHeapOptions {\n  id?: string;\n  x?: number;\n  y?: number;\n  frameWidth?: number;\n  /** x of the heap column. Default frameWidth + 110. */\n  heapX?: number;\n  rowHeight?: number;\n  /** Tones keyed by `frame.var` (e.g. 'Global.a') or heap object id. */\n  tones?: Record<string, Tone | undefined>;\n  /** Heap layout: explicit positions per object id, relative to (heapX, y). */\n  positions?: Record<string, Vec>;\n}\n\nexport interface StackHeapDiagram extends Scene {\n  slot(frame: string, name: string): Vec;\n  object(id: string): Vec;\n}\n\nconst show = (v: MemValue) => (v === null ? 'None' : typeof v === 'string' ? `\"${v}\"` : typeof v === 'boolean' ? (v ? 'True' : 'False') : String(v));\nconst isRef = (v: MemValue): v is { ref: string } => typeof v === 'object' && v !== null;\n\nexport function stackHeap(frames: readonly StackFrame[], heap: readonly HeapObject[], o: StackHeapOptions = {}): StackHeapDiagram {\n  const id = o.id ?? 'mem';\n  const x0 = o.x ?? 0, y0 = o.y ?? 0;\n  const fw = o.frameWidth ?? 150;\n  const hx = o.heapX ?? x0 + fw + 110;\n  const rh = o.rowHeight ?? 28;\n  const cellW = 40;\n  const nodes: SceneNode[] = [];\n  const arrows: SceneNode[] = [];\n  const slots = new Map<string, Vec>();\n  const objPos = new Map<string, Vec>();\n\n  // \u2500\u2500 heap layout first (arrows need to know where objects are) \u2500\u2500\n  let hy = y0 + 18;\n  for (const obj of heap) {\n    const p = o.positions?.[obj.id];\n    const at = p ? V2(hx + p.x, y0 + p.y) : V2(hx, hy);\n    objPos.set(obj.id, at);\n    if (!p) hy += rh + 40;\n  }\n\n  // \u2500\u2500 stack frames \u2500\u2500\n  let fy = y0;\n  for (const f of frames) {\n    const h = 26 + f.vars.length * rh + 8;\n    nodes.push(rect({ id: `${id}:frame:${f.name}`, x: x0 + fw / 2, y: fy + h / 2, w: fw, h, rx: 6, role: 'frame' }));\n    nodes.push(text({ id: `${id}:frame:${f.name}:t`, x: x0 + 10, y: fy + 13, text: f.name, size: 11, role: 'caption', anchor: 'start' }));\n    f.vars.forEach((v, i) => {\n      const cy = fy + 26 + i * rh + rh / 2;\n      const key = `${f.name}.${v.name}`;\n      const tone = o.tones?.[key];\n      const slotX = x0 + fw - 34;\n      slots.set(key, V2(slotX, cy));\n      nodes.push(text({ id: `${id}:var:${key}`, x: slotX - 26, y: cy, text: v.name, size: 13, role: 'value', anchor: 'end', tone }));\n      nodes.push(rect({ id: `${id}:slot:${key}`, x: slotX, y: cy, w: 40, h: rh - 6, rx: 4, tone }));\n      if (isRef(v.value)) {\n        nodes.push(circle({ id: `${id}:dot:${key}`, x: slotX, y: cy, r: 3.5, role: 'dot', tone }));\n        const t = objPos.get(v.value.ref);\n        if (t) arrows.push(refArrow(`${id}:ref:${key}`, V2(slotX, cy), V2(t.x - 4, t.y), tone));\n      } else {\n        nodes.push(text({ id: `${id}:val:${key}`, x: slotX, y: cy, text: show(v.value), size: 12, role: 'value', tone }));\n      }\n    });\n    fy += h + 12;\n  }\n\n  // \u2500\u2500 heap objects \u2500\u2500\n  for (const obj of heap) {\n    const at = objPos.get(obj.id)!;\n    const tone = o.tones?.[obj.id];\n    nodes.push(text({ id: `${id}:obj:${obj.id}:kind`, x: at.x, y: at.y - rh / 2 - 9, text: obj.kind, size: 11, role: 'caption', anchor: 'start' }));\n    const pairs = obj.items.length && Array.isArray(obj.items[0]);\n    obj.items.forEach((item, i) => {\n      const [k, v] = pairs ? (item as readonly [string, MemValue]) : [String(i), item as MemValue];\n      const w = pairs ? Math.max(cellW, estimateTextWidth(k, 11) + 14) + cellW : cellW;\n      const cx = at.x + i * (pairs ? w : cellW) + (pairs ? w : cellW) / 2;\n      nodes.push(rect({ id: `${id}:obj:${obj.id}:${i}`, x: cx, y: at.y, w: pairs ? w : cellW, h: rh - 4, rx: 3, tone, enter: { x: cx + 20 } }));\n      nodes.push(text({ id: `${id}:obj:${obj.id}:${i}:i`, x: pairs ? cx - w / 2 + 7 : cx, y: pairs ? at.y : at.y + rh / 2 + 7, text: k, size: pairs ? 11 : 9, role: 'index', anchor: pairs ? 'start' : 'middle' }));\n      const vx = pairs ? cx + w / 2 - cellW / 2 : cx;\n      if (isRef(v)) {\n        nodes.push(circle({ id: `${id}:obj:${obj.id}:${i}:dot`, x: vx, y: at.y, r: 3.5, role: 'dot' }));\n        const t = objPos.get(v.ref);\n        if (t) arrows.push(refArrow(`${id}:ref:${obj.id}:${i}`, V2(vx, at.y), V2(t.x - 4, t.y), tone, true));\n      } else nodes.push(text({ id: `${id}:obj:${obj.id}:${i}:v`, x: vx, y: at.y, text: show(v), size: 12, role: 'value', tone, enter: { x: vx + 20 } }));\n    });\n    if (!obj.items.length) nodes.push(rect({ id: `${id}:obj:${obj.id}:empty`, x: at.x + 14, y: at.y, w: 28, h: rh - 4, rx: 3, tone: 'ghost' }));\n  }\n  return { nodes: [...nodes, ...arrows], slot: (f, n) => slots.get(`${f}.${n}`) ?? V2(0, 0), object: (oid) => objPos.get(oid) ?? V2(0, 0) };\n}\n\nfunction refArrow(id: string, from: Vec, to: Vec, tone?: Tone, fromHeap = false): SceneNode {\n  // bow arrows that go up or down so parallel references don't overlap\n  const dy = to.y - from.y;\n  const bend = fromHeap ? -40 : Math.abs(dy) < 4 ? 0 : Math.sign(dy) * -Math.min(30, Math.abs(dy) * 0.25);\n  return arrow({ id, x1: from.x, y1: from.y, x2: to.x, y2: to.y, bend, width: 1.5, tone });\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/path.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Path geometry: SVG path data for a point list, and resampling.
+ *
+ * Resampling is the interesting part. To tween shape A (n points) into shape B
+ * (m points) you need a point-to-point pairing. Walking along each shape by
+ * ARC LENGTH gives a natural one: "the point 30% of the way along" in A pairs
+ * with the point 30% of the way along in B. So we resample the old shape to m
+ * evenly spaced points and tween those.
+ */
+import { NumericProps } from './scene';
+type Pt = readonly [number, number];
+/**
+ * `d` attribute for the points. Straight segments, or (smooth) a Catmull-Rom
+ * spline converted to cubic Béziers: for the segment P1→P2 the control points
+ * are P1 + (P2-P0)/6 and P2 - (P3-P1)/6. Endpoints reuse themselves as their
+ * missing neighbour (open) or wrap around (closed).
+ */
+export declare function pathData(pts: ReadonlyArray<Pt>, closed: boolean, smooth: boolean): string;
+/** `count` points spaced evenly by arc length along the polyline through `pts`. */
+export declare function resample(pts: ReadonlyArray<Pt>, count: number, closed?: boolean): Array<[number, number]>;
+/** Resample the points stored in a flat numeric bag (p0 p1 …), returning a bag with `to` points. */
+export declare function resampleProps(cur: NumericProps, from: number, to: number, closed: boolean): NumericProps;
+export {};

package/dist/path.js

@@ -0,0 +1,49 @@
+const r = (v) => String(Math.round(v * 100) / 100);
+function pathData(pts, closed, smooth) {
+  const n = pts.length;
+  if (n === 0) return "";
+  if (n === 1) return `M${r(pts[0][0])} ${r(pts[0][1])}`;
+  const at = (i) => closed ? pts[(i % n + n) % n] : pts[Math.max(0, Math.min(n - 1, i))];
+  let d = `M${r(pts[0][0])} ${r(pts[0][1])}`;
+  const segs = closed ? n : n - 1;
+  for (let i = 0; i < segs; i++) {
+    const p1 = at(i), p2 = at(i + 1);
+    if (!smooth) d += `L${r(p2[0])} ${r(p2[1])}`;
+    else {
+      const p0 = at(i - 1), p3 = at(i + 2);
+      d += `C${r(p1[0] + (p2[0] - p0[0]) / 6)} ${r(p1[1] + (p2[1] - p0[1]) / 6)} ${r(p2[0] - (p3[0] - p1[0]) / 6)} ${r(p2[1] - (p3[1] - p1[1]) / 6)} ${r(p2[0])} ${r(p2[1])}`;
+    }
+  }
+  return closed ? d + "Z" : d;
+}
+function resample(pts, count, closed = false) {
+  if (!pts.length || count <= 0) return [];
+  if (pts.length === 1) return Array.from({ length: count }, () => [pts[0][0], pts[0][1]]);
+  const ring = closed ? [...pts, pts[0]] : pts;
+  const cum = [0];
+  for (let i = 1; i < ring.length; i++) cum.push(cum[i - 1] + Math.hypot(ring[i][0] - ring[i - 1][0], ring[i][1] - ring[i - 1][1]));
+  const total = cum[cum.length - 1];
+  const out = [];
+  let seg = 1;
+  for (let k = 0; k < count; k++) {
+    const frac = count === 1 ? 0 : closed ? k / count : k / (count - 1);
+    const target = frac * total;
+    while (seg < cum.length - 1 && cum[seg] < target) seg++;
+    const span = cum[seg] - cum[seg - 1];
+    const t = span === 0 ? 0 : (target - cum[seg - 1]) / span;
+    out.push([ring[seg - 1][0] + (ring[seg][0] - ring[seg - 1][0]) * t, ring[seg - 1][1] + (ring[seg][1] - ring[seg - 1][1]) * t]);
+  }
+  return out;
+}
+function resampleProps(cur, from, to, closed) {
+  const pts = Array.from({ length: from }, (_, i) => [cur[`p${2 * i}`], cur[`p${2 * i + 1}`]]);
+  const out = {};
+  resample(pts, to, closed).forEach(([x, y], i) => (out[`p${2 * i}`] = x, out[`p${2 * i + 1}`] = y));
+  return out;
+}
+export {
+  pathData,
+  resample,
+  resampleProps
+};
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/path.ts"],
+  "sourcesContent": ["/**\n * Path geometry: SVG path data for a point list, and resampling.\n *\n * Resampling is the interesting part. To tween shape A (n points) into shape B\n * (m points) you need a point-to-point pairing. Walking along each shape by\n * ARC LENGTH gives a natural one: \"the point 30% of the way along\" in A pairs\n * with the point 30% of the way along in B. So we resample the old shape to m\n * evenly spaced points and tween those.\n */\nimport { NumericProps } from './scene';\n\ntype Pt = readonly [number, number];\n\nconst r = (v: number) => String(Math.round(v * 100) / 100);\n\n/**\n * `d` attribute for the points. Straight segments, or (smooth) a Catmull-Rom\n * spline converted to cubic B\u00E9ziers: for the segment P1\u2192P2 the control points\n * are P1 + (P2-P0)/6 and P2 - (P3-P1)/6. Endpoints reuse themselves as their\n * missing neighbour (open) or wrap around (closed).\n */\nexport function pathData(pts: ReadonlyArray<Pt>, closed: boolean, smooth: boolean): string {\n  const n = pts.length;\n  if (n === 0) return '';\n  if (n === 1) return `M${r(pts[0][0])} ${r(pts[0][1])}`;\n  const at = (i: number): Pt => (closed ? pts[((i % n) + n) % n] : pts[Math.max(0, Math.min(n - 1, i))]);\n  let d = `M${r(pts[0][0])} ${r(pts[0][1])}`;\n  const segs = closed ? n : n - 1;\n  for (let i = 0; i < segs; i++) {\n    const p1 = at(i), p2 = at(i + 1);\n    if (!smooth) d += `L${r(p2[0])} ${r(p2[1])}`;\n    else {\n      const p0 = at(i - 1), p3 = at(i + 2);\n      d += `C${r(p1[0] + (p2[0] - p0[0]) / 6)} ${r(p1[1] + (p2[1] - p0[1]) / 6)} ${r(p2[0] - (p3[0] - p1[0]) / 6)} ${r(p2[1] - (p3[1] - p1[1]) / 6)} ${r(p2[0])} ${r(p2[1])}`;\n    }\n  }\n  return closed ? d + 'Z' : d;\n}\n\n/** `count` points spaced evenly by arc length along the polyline through `pts`. */\nexport function resample(pts: ReadonlyArray<Pt>, count: number, closed = false): Array<[number, number]> {\n  if (!pts.length || count <= 0) return [];\n  if (pts.length === 1) return Array.from({ length: count }, () => [pts[0][0], pts[0][1]]);\n  const ring = closed ? [...pts, pts[0]] : pts;\n  const cum = [0];\n  for (let i = 1; i < ring.length; i++) cum.push(cum[i - 1] + Math.hypot(ring[i][0] - ring[i - 1][0], ring[i][1] - ring[i - 1][1]));\n  const total = cum[cum.length - 1];\n  const out: Array<[number, number]> = [];\n  let seg = 1;\n  for (let k = 0; k < count; k++) {\n    // closed shapes don't repeat the start point; open ones end exactly on the last point\n    const frac = count === 1 ? 0 : closed ? k / count : k / (count - 1);\n    const target = frac * total;\n    while (seg < cum.length - 1 && cum[seg] < target) seg++;\n    const span = cum[seg] - cum[seg - 1];\n    const t = span === 0 ? 0 : (target - cum[seg - 1]) / span;\n    out.push([ring[seg - 1][0] + (ring[seg][0] - ring[seg - 1][0]) * t, ring[seg - 1][1] + (ring[seg][1] - ring[seg - 1][1]) * t]);\n  }\n  return out;\n}\n\n/** Resample the points stored in a flat numeric bag (p0 p1 \u2026), returning a bag with `to` points. */\nexport function resampleProps(cur: NumericProps, from: number, to: number, closed: boolean): NumericProps {\n  const pts: Pt[] = Array.from({ length: from }, (_, i) => [cur[`p${2 * i}`], cur[`p${2 * i + 1}`]] as Pt);\n  const out: NumericProps = {};\n  resample(pts, to, closed).forEach(([x, y], i) => ((out[`p${2 * i}`] = x), (out[`p${2 * i + 1}`] = y)));\n  return out;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/player.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Step through an algorithm frame by frame.
+ *
+ * Pattern: write your algorithm as a generator that `yield`s a SNAPSHOT of its
+ * state at each interesting moment. The player runs it to completion up front
+ * and keeps every frame, which is what makes "previous step" and a scrubber
+ * possible — you can't run a generator backwards, but you can index an array.
+ *
+ *   function* binarySearch(a, target) {
+ *     let lo = 0, hi = a.length - 1;
+ *     while (lo <= hi) {
+ *       const mid = (lo + hi) >> 1;
+ *       yield { lo, hi, mid };              // ← snapshot
+ *       ...
+ *     }
+ *   }
+ *
+ * ⚠ Yield COPIES of mutable data (`[...arr]`, `structuredClone(x)`). If you
+ * yield the same array you keep mutating, every stored frame points at the
+ * same final array and the animation looks frozen.
+ */
+export interface PlayerOptions<S> {
+    /** ms between frames when playing. Default 700. */
+    interval?: number;
+    loop?: boolean;
+    /** Safety cap for runaway generators. Default 10 000. */
+    maxFrames?: number;
+    /** Called on every frame change (including the initial one). */
+    onFrame?: (frame: S, index: number, player: Player<S>) => void;
+}
+export interface Player<S> {
+    readonly frames: readonly S[];
+    readonly index: number;
+    readonly frame: S;
+    readonly playing: boolean;
+    readonly atEnd: boolean;
+    next(): void;
+    prev(): void;
+    seek(i: number): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Replace the frames (e.g. after the user changes the input). */
+    load(source: Iterable<S>): void;
+    setInterval(ms: number): void;
+    subscribe(fn: (frame: S, index: number, player: Player<S>) => void): () => void;
+    destroy(): void;
+}
+export declare function createPlayer<S>(source: Iterable<S>, o?: PlayerOptions<S>): Player<S>;

package/dist/player.js

@@ -0,0 +1,100 @@
+function createPlayer(source, o = {}) {
+  let interval = o.interval ?? 700;
+  const max = o.maxFrames ?? 1e4;
+  let frames = [];
+  let index = 0;
+  let timer = null;
+  const subs = /* @__PURE__ */ new Set();
+  if (o.onFrame) subs.add(o.onFrame);
+  const collect = (src) => {
+    const out = [];
+    for (const f of src) {
+      out.push(f);
+      if (out.length >= max) {
+        console.warn(`[dsviz] player stopped collecting at ${max} frames`);
+        break;
+      }
+    }
+    return out;
+  };
+  const notify = () => {
+    if (!frames.length) return;
+    for (const fn of subs) fn(frames[index], index, player);
+  };
+  const tick = () => {
+    if (index >= frames.length - 1) {
+      if (!o.loop) return pause();
+      index = -1;
+    }
+    index++;
+    notify();
+    timer = setTimeout(tick, interval);
+  };
+  function pause() {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    notify();
+  }
+  const player = {
+    get frames() {
+      return frames;
+    },
+    get index() {
+      return index;
+    },
+    get frame() {
+      return frames[index];
+    },
+    get playing() {
+      return timer !== null;
+    },
+    get atEnd() {
+      return index >= frames.length - 1;
+    },
+    next() {
+      if (index < frames.length - 1) index++, notify();
+    },
+    prev() {
+      if (index > 0) index--, notify();
+    },
+    seek(i) {
+      const j = Math.max(0, Math.min(frames.length - 1, Math.round(i)));
+      if (j !== index) index = j, notify();
+    },
+    play() {
+      if (timer) return;
+      if (index >= frames.length - 1) index = -1;
+      timer = setTimeout(tick, 0);
+    },
+    pause,
+    toggle() {
+      timer ? pause() : player.play();
+    },
+    load(src) {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      frames = collect(src);
+      index = 0;
+      notify();
+    },
+    setInterval(ms) {
+      interval = ms;
+    },
+    subscribe(fn) {
+      subs.add(fn);
+      return () => subs.delete(fn);
+    },
+    destroy() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      subs.clear();
+    }
+  };
+  frames = collect(source);
+  queueMicrotask(notify);
+  return player;
+}
+export {
+  createPlayer
+};
+//# sourceMappingURL=player.js.map

package/dist/player.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/player.ts"],
+  "sourcesContent": ["/**\n * Step through an algorithm frame by frame.\n *\n * Pattern: write your algorithm as a generator that `yield`s a SNAPSHOT of its\n * state at each interesting moment. The player runs it to completion up front\n * and keeps every frame, which is what makes \"previous step\" and a scrubber\n * possible \u2014 you can't run a generator backwards, but you can index an array.\n *\n *   function* binarySearch(a, target) {\n *     let lo = 0, hi = a.length - 1;\n *     while (lo <= hi) {\n *       const mid = (lo + hi) >> 1;\n *       yield { lo, hi, mid };              // \u2190 snapshot\n *       ...\n *     }\n *   }\n *\n * \u26A0 Yield COPIES of mutable data (`[...arr]`, `structuredClone(x)`). If you\n * yield the same array you keep mutating, every stored frame points at the\n * same final array and the animation looks frozen.\n */\n\nexport interface PlayerOptions<S> {\n  /** ms between frames when playing. Default 700. */\n  interval?: number;\n  loop?: boolean;\n  /** Safety cap for runaway generators. Default 10 000. */\n  maxFrames?: number;\n  /** Called on every frame change (including the initial one). */\n  onFrame?: (frame: S, index: number, player: Player<S>) => void;\n}\n\nexport interface Player<S> {\n  readonly frames: readonly S[];\n  readonly index: number;\n  readonly frame: S;\n  readonly playing: boolean;\n  readonly atEnd: boolean;\n  next(): void;\n  prev(): void;\n  seek(i: number): void;\n  play(): void;\n  pause(): void;\n  toggle(): void;\n  /** Replace the frames (e.g. after the user changes the input). */\n  load(source: Iterable<S>): void;\n  setInterval(ms: number): void;\n  subscribe(fn: (frame: S, index: number, player: Player<S>) => void): () => void;\n  destroy(): void;\n}\n\nexport function createPlayer<S>(source: Iterable<S>, o: PlayerOptions<S> = {}): Player<S> {\n  let interval = o.interval ?? 700;\n  const max = o.maxFrames ?? 10_000;\n  let frames: S[] = [];\n  let index = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  const subs = new Set<(f: S, i: number, p: Player<S>) => void>();\n  if (o.onFrame) subs.add(o.onFrame);\n\n  const collect = (src: Iterable<S>) => {\n    const out: S[] = [];\n    for (const f of src) {\n      out.push(f);\n      if (out.length >= max) {\n        console.warn(`[dsviz] player stopped collecting at ${max} frames`);\n        break;\n      }\n    }\n    return out;\n  };\n\n  const notify = () => {\n    if (!frames.length) return;\n    for (const fn of subs) fn(frames[index], index, player);\n  };\n\n  const tick = () => {\n    if (index >= frames.length - 1) {\n      if (!o.loop) return pause();\n      index = -1;\n    }\n    index++;\n    notify();\n    timer = setTimeout(tick, interval);\n  };\n\n  function pause() {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    notify(); // so UIs can update their play/pause button\n  }\n\n  const player: Player<S> = {\n    get frames() {\n      return frames;\n    },\n    get index() {\n      return index;\n    },\n    get frame() {\n      return frames[index];\n    },\n    get playing() {\n      return timer !== null;\n    },\n    get atEnd() {\n      return index >= frames.length - 1;\n    },\n    next() {\n      if (index < frames.length - 1) (index++, notify());\n    },\n    prev() {\n      if (index > 0) (index--, notify());\n    },\n    seek(i) {\n      const j = Math.max(0, Math.min(frames.length - 1, Math.round(i)));\n      if (j !== index) (index = j, notify());\n    },\n    play() {\n      if (timer) return;\n      if (index >= frames.length - 1) index = -1; // restart from the top\n      timer = setTimeout(tick, 0);\n    },\n    pause,\n    toggle() {\n      timer ? pause() : player.play();\n    },\n    load(src) {\n      if (timer) clearTimeout(timer);\n      timer = null;\n      frames = collect(src);\n      index = 0;\n      notify();\n    },\n    setInterval(ms) {\n      interval = ms;\n    },\n    subscribe(fn) {\n      subs.add(fn);\n      return () => subs.delete(fn);\n    },\n    destroy() {\n      if (timer) clearTimeout(timer);\n      timer = null;\n      subs.clear();\n    },\n  };\n\n  frames = collect(source);\n  queueMicrotask(notify); // let the caller finish wiring up before the first frame\n  return player;\n}\n"],
+  "mappings": "AAmDO,SAAS,aAAgB,QAAqB,IAAsB,CAAC,GAAc;AACxF,MAAI,WAAW,EAAE,YAAY;AAC7B,QAAM,MAAM,EAAE,aAAa;AAC3B,MAAI,SAAc,CAAC;AACnB,MAAI,QAAQ;AACZ,MAAI,QAA8C;AAClD,QAAM,OAAO,oBAAI,IAA6C;AAC9D,MAAI,EAAE,QAAS,MAAK,IAAI,EAAE,OAAO;AAEjC,QAAM,UAAU,CAAC,QAAqB;AACpC,UAAM,MAAW,CAAC;AAClB,eAAW,KAAK,KAAK;AACnB,UAAI,KAAK,CAAC;AACV,UAAI,IAAI,UAAU,KAAK;AACrB,gBAAQ,KAAK,wCAAwC,GAAG,SAAS;AACjE;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS,MAAM;AACnB,QAAI,CAAC,OAAO,OAAQ;AACpB,eAAW,MAAM,KAAM,IAAG,OAAO,KAAK,GAAG,OAAO,MAAM;AAAA,EACxD;AAEA,QAAM,OAAO,MAAM;AACjB,QAAI,SAAS,OAAO,SAAS,GAAG;AAC9B,UAAI,CAAC,EAAE,KAAM,QAAO,MAAM;AAC1B,cAAQ;AAAA,IACV;AACA;AACA,WAAO;AACP,YAAQ,WAAW,MAAM,QAAQ;AAAA,EACnC;AAEA,WAAS,QAAQ;AACf,QAAI,MAAO,cAAa,KAAK;AAC7B,YAAQ;AACR,WAAO;AAAA,EACT;AAEA,QAAM,SAAoB;AAAA,IACxB,IAAI,SAAS;AACX,aAAO;AAAA,IACT;AAAA,IACA,IAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAAA,IACA,IAAI,QAAQ;AACV,aAAO,OAAO,KAAK;AAAA,IACrB;AAAA,IACA,IAAI,UAAU;AACZ,aAAO,UAAU;AAAA,IACnB;AAAA,IACA,IAAI,QAAQ;AACV,aAAO,SAAS,OAAO,SAAS;AAAA,IAClC;AAAA,IACA,OAAO;AACL,UAAI,QAAQ,OAAO,SAAS,EAAG,CAAC,SAAS,OAAO;AAAA,IAClD;AAAA,IACA,OAAO;AACL,UAAI,QAAQ,EAAG,CAAC,SAAS,OAAO;AAAA,IAClC;AAAA,IACA,KAAK,GAAG;AACN,YAAM,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,SAAS,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC;AAChE,UAAI,MAAM,MAAO,CAAC,QAAQ,GAAG,OAAO;AAAA,IACtC;AAAA,IACA,OAAO;AACL,UAAI,MAAO;AACX,UAAI,SAAS,OAAO,SAAS,EAAG,SAAQ;AACxC,cAAQ,WAAW,MAAM,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA,SAAS;AACP,cAAQ,MAAM,IAAI,OAAO,KAAK;AAAA,IAChC;AAAA,IACA,KAAK,KAAK;AACR,UAAI,MAAO,cAAa,KAAK;AAC7B,cAAQ;AACR,eAAS,QAAQ,GAAG;AACpB,cAAQ;AACR,aAAO;AAAA,IACT;AAAA,IACA,YAAY,IAAI;AACd,iBAAW;AAAA,IACb;AAAA,IACA,UAAU,IAAI;AACZ,WAAK,IAAI,EAAE;AACX,aAAO,MAAM,KAAK,OAAO,EAAE;AAAA,IAC7B;AAAA,IACA,UAAU;AACR,UAAI,MAAO,cAAa,KAAK;AAC7B,cAAQ;AACR,WAAK,MAAM;AAAA,IACb;AAAA,EACF;AAEA,WAAS,QAAQ,MAAM;AACvB,iBAAe,MAAM;AACrB,SAAO;AACT;",
+  "names": []
+}

package/dist/plot/index.d.ts

@@ -0,0 +1,2 @@
+export * from './plane';
+export * from './marks';

package/dist/plot/index.js

@@ -0,0 +1,3 @@
+export * from "./plane.js";
+export * from "./marks.js";
+//# sourceMappingURL=index.js.map

package/dist/plot/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/plot/index.ts"],
+  "sourcesContent": ["export * from './plane';\nexport * from './marks';\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/plot/marks.d.ts

@@ -0,0 +1,120 @@
+import { Scene, Tone } from '../scene';
+import { Vec } from '../vec';
+import { Plane } from './plane';
+type Fn = (x: number) => number;
+export interface AxesOptions {
+    id?: string;
+    /** Tick positions, or a step. Default: nice ticks. */
+    xTicks?: number[] | number;
+    yTicks?: number[] | number;
+    grid?: boolean;
+    /** Tick labels. Default true. */
+    labels?: boolean;
+    xLabel?: string;
+    yLabel?: string;
+    /** Hide the 0 label at the origin (it collides with both axes). Default true. */
+    hideZero?: boolean;
+}
+/**
+ * Axes through the origin (or along the edge when 0 is out of range), with
+ * optional grid lines and tick labels. Ticks are keyed by VALUE, so if the
+ * plane's range changes the tick for "2" slides to its new place.
+ */
+export declare function axes(p: Plane, o?: AxesOptions): Scene;
+export interface FnOptions {
+    id?: string;
+    tone?: Tone;
+    width?: number;
+    /** Sample count across the domain. Default 160. Keep it fixed so the curve can morph point-for-point. */
+    samples?: number;
+    /** Plot only this x-range. Default: the plane's. */
+    domain?: [number, number];
+    dashed?: boolean;
+}
+/**
+ * Sample y = f(x) into path(s), clipped to the plane. The curve is SPLIT
+ * wherever f is undefined (NaN / ±Infinity), leaves the visible y-range, or
+ * jumps by more than the plane's height between two samples (tan x, 1/x), so
+ * you never get a vertical line through an asymptote.
+ * Pieces are keyed `id:0`, `id:1`, … so the main piece keeps its identity.
+ */
+export declare function fn(p: Plane, f: Fn, o?: FnOptions): Scene;
+export interface PointOptions {
+    id: string;
+    label?: string;
+    tone?: Tone;
+    draggable?: boolean;
+    r?: number;
+    /** Where the label sits relative to the point, in px. Default (8, -10). */
+    labelOffset?: Vec;
+    data?: unknown;
+    /** Pulse a "drag me" ring (turn off once touched). */
+    hint?: boolean;
+}
+/** A dot at world (x, y). With `draggable`, it gets a big hit target; drag events carry `data`. */
+export declare function point(p: Plane, x: number, y: number, o: PointOptions): Scene;
+export interface LineOptions {
+    id: string;
+    tone?: Tone;
+    width?: number;
+    dashed?: boolean;
+    role?: string;
+}
+/** Straight segment between two world points. */
+export declare function segment(p: Plane, a: Vec, b: Vec, o: LineOptions): Scene;
+/** An arrow from `from` to `to` (world coordinates), e.g. a vector. */
+export declare function vector(p: Plane, from: Vec, to: Vec, o: LineOptions & {
+    label?: string;
+}): Scene;
+/** Numerical derivative (central difference). Good to ~1e-6 for smooth f. */
+export declare const derivative: (f: Fn, x: number, h?: number) => number;
+/**
+ * The tangent line to f at x0, drawn `span` world units either side, clipped
+ * to the plane. Returns the scene plus the slope it used.
+ */
+/**
+ * The part of segment a→b inside the plane's x/y ranges (Liang–Barsky).
+ * Write the segment as a + t·(b − a), t ∈ [0, 1]. Each of the four edges of
+ * the box cuts off t below or above some value; keep the t-range that survives
+ * all four. Returns null if nothing is left.
+ */
+export declare function clipToPlane(p: Plane, a: Vec, b: Vec): [Vec, Vec] | null;
+export declare function tangent(p: Plane, f: Fn, x0: number, o?: LineOptions & {
+    span?: number;
+}): Scene & {
+    slope: number;
+};
+export interface AreaOptions {
+    id?: string;
+    tone?: Tone;
+    samples?: number;
+    /** Shade between f and g instead of f and the x-axis. */
+    g?: Fn;
+}
+/** Shaded region between f and the x-axis (or g) for a ≤ x ≤ b, as one closed path. */
+export declare function area(p: Plane, f: Fn, a: number, b: number, o?: AreaOptions): Scene;
+export type RiemannRule = 'left' | 'right' | 'mid' | 'trap';
+/**
+ * Riemann sum of f over [a, b] with n pieces. Each piece is keyed by its INDEX,
+ * so changing n makes existing rectangles resize and new ones fade in, rather
+ * than everything being replaced. `trap` draws trapezoids (closed paths).
+ * Returns the scene and the numeric sum.
+ */
+export declare function riemann(p: Plane, f: Fn, a: number, b: number, n: number, rule?: RiemannRule, o?: {
+    id?: string;
+    tone?: Tone;
+}): Scene & {
+    sum: number;
+};
+/** Numerical integral by Simpson's rule (n even). */
+export declare function integrate(f: Fn, a: number, b: number, n?: number): number;
+/** A maths label at world (x, y): italic serif via role 'math'. */
+export declare function label(p: Plane, x: number, y: number, s: string, o: {
+    id: string;
+    tone?: Tone;
+    size?: number;
+    anchor?: 'start' | 'middle' | 'end';
+    dx?: number;
+    dy?: number;
+}): Scene;
+export {};

package/dist/plot/marks.js

@@ -0,0 +1,200 @@
+import { handle } from "../handle.js";
+import { arrow, path, text } from "../scene.js";
+import { V2 } from "../vec.js";
+import { niceTicks } from "./plane.js";
+const fmt = (v) => (Number.isInteger(v) ? String(v) : String(+v.toFixed(2))).replace("-", "\u2212");
+const ticksFor = (spec, lo, hi) => {
+  if (Array.isArray(spec)) return spec;
+  if (typeof spec === "number") {
+    const out = [];
+    for (let v = Math.ceil(lo / spec) * spec; v <= hi + 1e-9; v += spec) out.push(+v.toPrecision(12));
+    return out;
+  }
+  return niceTicks(lo, hi);
+};
+function axes(p, o = {}) {
+  const id = o.id ?? "axes";
+  const xs = ticksFor(o.xTicks, p.x[0], p.x[1]);
+  const ys = ticksFor(o.yTicks, p.y[0], p.y[1]);
+  const ax = p.sy(Math.min(p.y[1], Math.max(p.y[0], 0)));
+  const ay = p.sx(Math.min(p.x[1], Math.max(p.x[0], 0)));
+  const nodes = [];
+  if (o.grid ?? true) {
+    for (const v of xs) nodes.push(path({ id: `${id}:gx:${v}`, points: [[p.sx(v), 0], [p.sx(v), p.height]], role: "grid", width: 1 }));
+    for (const v of ys) nodes.push(path({ id: `${id}:gy:${v}`, points: [[0, p.sy(v)], [p.width, p.sy(v)]], role: "grid", width: 1 }));
+  }
+  nodes.push(
+    arrow({ id: `${id}:x`, x1: 0, y1: ax, x2: p.width + 8, y2: ax, role: "axis", width: 1.25 }),
+    arrow({ id: `${id}:y`, x1: ay, y1: p.height, x2: ay, y2: -8, role: "axis", width: 1.25 })
+  );
+  const hideZero = o.hideZero ?? true;
+  if (o.labels ?? true) {
+    for (const v of xs) {
+      if (hideZero && v === 0) continue;
+      nodes.push(path({ id: `${id}:tx:${v}`, points: [[p.sx(v), ax - 3], [p.sx(v), ax + 3]], role: "tick", width: 1 }));
+      nodes.push(text({ id: `${id}:lx:${v}`, x: p.sx(v), y: ax + 15, text: fmt(v), size: 12, role: "tick-label" }));
+    }
+    for (const v of ys) {
+      if (hideZero && v === 0) continue;
+      nodes.push(path({ id: `${id}:ty:${v}`, points: [[ay - 3, p.sy(v)], [ay + 3, p.sy(v)]], role: "tick", width: 1 }));
+      nodes.push(text({ id: `${id}:ly:${v}`, x: ay - 8, y: p.sy(v), text: fmt(v), size: 12, role: "tick-label", anchor: "end" }));
+    }
+  }
+  if (o.xLabel) nodes.push(text({ id: `${id}:xl`, x: p.width + 14, y: ax, text: o.xLabel, size: 15, role: "math", anchor: "start" }));
+  if (o.yLabel) nodes.push(text({ id: `${id}:yl`, x: ay, y: -20, text: o.yLabel, size: 15, role: "math" }));
+  return { nodes };
+}
+function fn(p, f, o = {}) {
+  const id = o.id ?? "f";
+  const [a, b] = o.domain ?? p.x;
+  const n = Math.max(2, o.samples ?? 160);
+  const [ylo, yhi] = p.y;
+  const span = yhi - ylo;
+  const inside = (y) => y >= ylo && y <= yhi;
+  const pieces = [];
+  let cur = [];
+  let prev = null;
+  const end = () => {
+    if (cur.length > 1) pieces.push(cur);
+    cur = [];
+  };
+  for (let i = 0; i < n; i++) {
+    const x = a + (b - a) * i / (n - 1);
+    const y = f(x);
+    if (!Number.isFinite(y)) {
+      end();
+      prev = null;
+      continue;
+    }
+    if (prev) {
+      if (Math.abs(y - prev.y) > span) {
+        end();
+      } else if (inside(prev.y) !== inside(y)) {
+        const edge = (inside(prev.y) ? y : prev.y) > yhi ? yhi : ylo;
+        const t = (edge - prev.y) / (y - prev.y);
+        const ex = prev.x + (x - prev.x) * t;
+        cur.push([p.sx(ex), p.sy(edge)]);
+        if (inside(prev.y)) end();
+      }
+    }
+    if (inside(y)) cur.push([p.sx(x), p.sy(y)]);
+    prev = { x, y };
+  }
+  end();
+  return {
+    nodes: pieces.map((pts, k) => path({ id: `${id}:${k}`, points: pts, role: "curve", tone: o.tone, width: o.width ?? 2.25, dashed: o.dashed }))
+  };
+}
+function point(p, x, y, o) {
+  const c = p.toPx(x, y);
+  const off = o.labelOffset ?? V2(8, -12);
+  const nodes = handle({ id: o.id, x: c.x, y: c.y, r: o.r ?? 5, tone: o.tone, draggable: !!o.draggable, hint: o.hint, data: o.data ?? { id: o.id } });
+  if (o.label) nodes.push(text({ id: `${o.id}:label`, x: c.x + off.x, y: c.y + off.y, text: o.label, size: 13, role: "math", tone: o.tone, anchor: off.x < 0 ? "end" : "start" }));
+  return { nodes };
+}
+function segment(p, a, b, o) {
+  const A = p.toPx(a), B = p.toPx(b);
+  return { nodes: [path({ id: o.id, points: [[A.x, A.y], [B.x, B.y]], role: o.role ?? "curve", tone: o.tone, width: o.width ?? 1.75, dashed: o.dashed })] };
+}
+function vector(p, from, to, o) {
+  const A = p.toPx(from), B = p.toPx(to);
+  const nodes = [arrow({ id: o.id, x1: A.x, y1: A.y, x2: B.x, y2: B.y, tone: o.tone ?? "accent", width: o.width ?? 2.25, dashed: o.dashed })];
+  if (o.label) {
+    const mx = (A.x + B.x) / 2, my = (A.y + B.y) / 2;
+    const dx = B.x - A.x, dy = B.y - A.y, l = Math.hypot(dx, dy) || 1;
+    nodes.push(text({ id: `${o.id}:label`, x: mx + dy / l * 14, y: my - dx / l * 14, text: o.label, size: 14, role: "math", tone: o.tone ?? "accent" }));
+  }
+  return { nodes };
+}
+const derivative = (f, x, h = 1e-4) => (f(x + h) - f(x - h)) / (2 * h);
+function clipToPlane(p, a, b) {
+  const dx = b.x - a.x, dy = b.y - a.y;
+  let t0 = 0, t1 = 1;
+  const edges = [
+    [-dx, a.x - p.x[0]],
+    [dx, p.x[1] - a.x],
+    [-dy, a.y - p.y[0]],
+    [dy, p.y[1] - a.y]
+  ];
+  for (const [q, r] of edges) {
+    if (q === 0) {
+      if (r < 0) return null;
+      continue;
+    }
+    const t = r / q;
+    if (q < 0) t0 = Math.max(t0, t);
+    else t1 = Math.min(t1, t);
+    if (t0 > t1) return null;
+  }
+  return [V2(a.x + dx * t0, a.y + dy * t0), V2(a.x + dx * t1, a.y + dy * t1)];
+}
+function tangent(p, f, x0, o = { id: "tangent" }) {
+  const m = derivative(f, x0);
+  const y0 = f(x0);
+  const span = o.span ?? (p.x[1] - p.x[0]) / 4;
+  const maxDx = Math.abs(m) > 1e-9 ? (p.y[1] - p.y[0]) / Math.abs(m) / 1.5 : span;
+  const d = Math.min(span, maxDx);
+  const [s0, s1] = clipToPlane(p, V2(x0 - d, y0 - m * d), V2(x0 + d, y0 + m * d)) ?? [V2(x0, y0), V2(x0, y0)];
+  return { ...segment(p, s0, s1, { ...o, tone: o.tone ?? "active" }), slope: m };
+}
+function area(p, f, a, b, o = {}) {
+  const n = o.samples ?? 80;
+  const lo = Math.min(a, b), hi = Math.max(a, b);
+  const top = [], bottom = [];
+  const g = o.g ?? (() => 0);
+  for (let i = 0; i < n; i++) {
+    const x = lo + (hi - lo) * i / (n - 1);
+    top.push([p.sx(x), p.sy(clampY(p, f(x)))]);
+    bottom.push([p.sx(x), p.sy(clampY(p, g(x)))]);
+  }
+  return { nodes: [path({ id: o.id ?? "area", points: [...top, ...bottom.reverse()], closed: true, role: "area", tone: o.tone })] };
+}
+const clampY = (p, y) => Number.isFinite(y) ? Math.min(p.y[1], Math.max(p.y[0], y)) : 0;
+function riemann(p, f, a, b, n, rule = "left", o = {}) {
+  const id = o.id ?? "riemann";
+  const w = (b - a) / n;
+  const nodes = [];
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const xl = a + i * w, xr = xl + w;
+    let pts;
+    if (rule === "trap") {
+      const yl = f(xl), yr = f(xr);
+      sum += (yl + yr) / 2 * w;
+      pts = [[xl, 0], [xl, yl], [xr, yr], [xr, 0]];
+    } else {
+      const h = f(rule === "left" ? xl : rule === "right" ? xr : (xl + xr) / 2);
+      sum += h * w;
+      pts = [[xl, 0], [xl, h], [xr, h], [xr, 0]];
+    }
+    const px = pts.map(([x, y]) => [p.sx(x), p.sy(clampY(p, y))]);
+    const neg = rule === "trap" ? f(xl) + f(xr) < 0 : px[1][1] > px[0][1];
+    nodes.push(path({ id: `${id}:${i}`, points: px, closed: true, role: "bar", tone: o.tone ?? (neg ? "danger" : "accent"), width: 1 }));
+  }
+  return { nodes, sum };
+}
+function integrate(f, a, b, n = 400) {
+  const h = (b - a) / n;
+  let s = f(a) + f(b);
+  for (let i = 1; i < n; i++) s += f(a + i * h) * (i % 2 ? 4 : 2);
+  return s * h / 3;
+}
+function label(p, x, y, s, o) {
+  const c = p.toPx(x, y);
+  return { nodes: [text({ id: o.id, x: c.x + (o.dx ?? 0), y: c.y + (o.dy ?? 0), text: s, size: o.size ?? 14, role: "math", tone: o.tone, anchor: o.anchor })] };
+}
+export {
+  area,
+  axes,
+  clipToPlane,
+  derivative,
+  fn,
+  integrate,
+  label,
+  point,
+  riemann,
+  segment,
+  tangent,
+  vector
+};
+//# sourceMappingURL=marks.js.map