dsviz 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Williamson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# dsviz
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript library for interactive, animated SVG diagrams for teaching: data structures and algorithms,
+plots, probability, geometry, CPU scheduling and memory. You describe the picture as data; dsviz draws it
+and animates every change. Framework-free core, thin React layer.
+
+```
+state ──▶ layout functions ──▶ Scene (plain data, stable ids) ──▶ <Diagram> / createView / toSVG
+```
+
+## Use it in a project
+
+```sh
+npm install dsviz
+```
+
+```tsx
+import { array, combine, pointer } from 'dsviz';
+import { Diagram } from 'dsviz/react';
+
+const arr = array([3, 8, 12, 17], { tones: { 2: 'active' } });
+<Diagram scene={combine(arr, pointer({ id: 'i', at: arr.top(2), label: 'i' }))} />
+```
+
+Families: data structures at the top level (`array`, `pointer`, `linkedList`, `binaryTree`, `graph`, `grid`,
+`stack`, `queue`) and the namespaces `plot`, `prob`, `geom`, `sched`, `mem`. Colours are CSS variables
+(`--dv-*`) you can override; dark mode via `[data-theme="dark"]`.
+
+## This repo
+
+- `npm run dev` — the docs and examples site (`site/`)
+- `npm test` — unit tests
+- `npm run build` — library build into `dist/`
+- `npm run build:site` — static site into `site-dist/` (deployed to GitHub Pages by CI)
+
+See `CLAUDE.md` for design notes.

package/dist/camera.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where the camera (the viewBox) should be.
+ *
+ * Rule of thumb for teaching diagrams: the camera should almost never move.
+ * Whatever moves on screen is what the learner reads as "the change", so a
+ * camera that refits on every step makes everything appear to move at once.
+ *
+ *   - fixed      You pass a viewBox. Use this for plots and anything draggable.
+ *   - fitViewBox The union of every frame you'll ever show (e.g. all of an
+ *                algorithm's steps), computed up front, then fixed.
+ *   - 'grow'     The default for `viewBox: 'auto'`: grow only when something
+ *                would fall outside, and shrink only when the content is much
+ *                smaller than the frame, never on small wobbles.
+ *   - 'fit'      Refit to the scene on every render (the old behaviour).
+ */
+import { Part } from './scene';
+export type ViewBox = [number, number, number, number];
+/** A viewBox around everything in all the given parts (e.g. one scene per frame). */
+export declare function fitViewBox(parts: Part | readonly Part[], pad?: number | [number, number, number, number]): ViewBox;
+/**
+ * The next camera, given the current one and the padded box around the new content.
+ * 'grow': stay put while the content fits; grow to include it when it doesn't;
+ * shrink back to it only when it fills less than half the frame.
+ */
+export declare function nextCamera(current: ViewBox | null, content: ViewBox, mode?: 'grow' | 'fit'): ViewBox;

package/dist/camera.js

@@ -0,0 +1,27 @@
+import { bounds, combine } from "./scene.js";
+function fitViewBox(parts, pad = 24) {
+  const b = bounds(combine(parts));
+  const [t, r, bt, l] = typeof pad === "number" ? [pad, pad, pad, pad] : pad;
+  return snap([b.x - l, b.y - t, b.w + l + r, b.h + t + bt]);
+}
+const snap = ([x, y, w, h]) => {
+  const x0 = Math.floor(x), y0 = Math.floor(y);
+  return [x0, y0, Math.max(1, Math.ceil(x + w) - x0), Math.max(1, Math.ceil(y + h) - y0)];
+};
+const contains = (a, b) => b[0] >= a[0] && b[1] >= a[1] && b[0] + b[2] <= a[0] + a[2] && b[1] + b[3] <= a[1] + a[3];
+const union = (a, b) => {
+  const x0 = Math.min(a[0], b[0]), y0 = Math.min(a[1], b[1]);
+  return [x0, y0, Math.max(a[0] + a[2], b[0] + b[2]) - x0, Math.max(a[1] + a[3], b[1] + b[3]) - y0];
+};
+function nextCamera(current, content, mode = "grow") {
+  const c = snap(content);
+  if (!current || mode === "fit") return c;
+  if (!contains(current, c)) return union(current, c);
+  const fill = c[2] * c[3] / (current[2] * current[3]);
+  return fill < 0.5 ? c : current;
+}
+export {
+  fitViewBox,
+  nextCamera
+};
+//# sourceMappingURL=camera.js.map

package/dist/camera.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/camera.ts"],
+  "sourcesContent": ["/**\n * Where the camera (the viewBox) should be.\n *\n * Rule of thumb for teaching diagrams: the camera should almost never move.\n * Whatever moves on screen is what the learner reads as \"the change\", so a\n * camera that refits on every step makes everything appear to move at once.\n *\n *   - fixed      You pass a viewBox. Use this for plots and anything draggable.\n *   - fitViewBox The union of every frame you'll ever show (e.g. all of an\n *                algorithm's steps), computed up front, then fixed.\n *   - 'grow'     The default for `viewBox: 'auto'`: grow only when something\n *                would fall outside, and shrink only when the content is much\n *                smaller than the frame, never on small wobbles.\n *   - 'fit'      Refit to the scene on every render (the old behaviour).\n */\nimport { Part, bounds, combine } from './scene';\n\nexport type ViewBox = [number, number, number, number];\n\n/** A viewBox around everything in all the given parts (e.g. one scene per frame). */\nexport function fitViewBox(parts: Part | readonly Part[], pad: number | [number, number, number, number] = 24): ViewBox {\n  const b = bounds(combine(parts as Part));\n  const [t, r, bt, l] = typeof pad === 'number' ? [pad, pad, pad, pad] : pad;\n  return snap([b.x - l, b.y - t, b.w + l + r, b.h + t + bt]);\n}\n\n/** Round outward to whole units, so tiny bounds changes can't make the camera twitch. */\nconst snap = ([x, y, w, h]: number[]): ViewBox => {\n  const x0 = Math.floor(x), y0 = Math.floor(y);\n  return [x0, y0, Math.max(1, Math.ceil(x + w) - x0), Math.max(1, Math.ceil(y + h) - y0)];\n};\n\nconst contains = (a: ViewBox, b: ViewBox) => b[0] >= a[0] && b[1] >= a[1] && b[0] + b[2] <= a[0] + a[2] && b[1] + b[3] <= a[1] + a[3];\nconst union = (a: ViewBox, b: ViewBox): ViewBox => {\n  const x0 = Math.min(a[0], b[0]), y0 = Math.min(a[1], b[1]);\n  return [x0, y0, Math.max(a[0] + a[2], b[0] + b[2]) - x0, Math.max(a[1] + a[3], b[1] + b[3]) - y0];\n};\n\n/**\n * The next camera, given the current one and the padded box around the new content.\n * 'grow': stay put while the content fits; grow to include it when it doesn't;\n * shrink back to it only when it fills less than half the frame.\n */\nexport function nextCamera(current: ViewBox | null, content: ViewBox, mode: 'grow' | 'fit' = 'grow'): ViewBox {\n  const c = snap(content);\n  if (!current || mode === 'fit') return c;\n  if (!contains(current, c)) return union(current, c);\n  const fill = (c[2] * c[3]) / (current[2] * current[3]);\n  return fill < 0.5 ? c : current;\n}\n"],
+  "mappings": "AAeA,SAAe,QAAQ,eAAe;AAK/B,SAAS,WAAW,OAA+B,MAAiD,IAAa;AACtH,QAAM,IAAI,OAAO,QAAQ,KAAa,CAAC;AACvC,QAAM,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,OAAO,QAAQ,WAAW,CAAC,KAAK,KAAK,KAAK,GAAG,IAAI;AACvE,SAAO,KAAK,CAAC,EAAE,IAAI,GAAG,EAAE,IAAI,GAAG,EAAE,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC;AAC3D;AAGA,MAAM,OAAO,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,MAAyB;AAChD,QAAM,KAAK,KAAK,MAAM,CAAC,GAAG,KAAK,KAAK,MAAM,CAAC;AAC3C,SAAO,CAAC,IAAI,IAAI,KAAK,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;AACxF;AAEA,MAAM,WAAW,CAAC,GAAY,MAAe,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;AACpI,MAAM,QAAQ,CAAC,GAAY,MAAwB;AACjD,QAAM,KAAK,KAAK,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;AACzD,SAAO,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;AAClG;AAOO,SAAS,WAAW,SAAyB,SAAkB,OAAuB,QAAiB;AAC5G,QAAM,IAAI,KAAK,OAAO;AACtB,MAAI,CAAC,WAAW,SAAS,MAAO,QAAO;AACvC,MAAI,CAAC,SAAS,SAAS,CAAC,EAAG,QAAO,MAAM,SAAS,CAAC;AAClD,QAAM,OAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,QAAQ,CAAC,IAAI,QAAQ,CAAC;AACpD,SAAO,OAAO,MAAM,IAAI;AAC1B;",
+  "names": []
+}

package/dist/connector.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Connectors: a line between two boxes (or points) with a decoration at either
+ * end. This is what UML relationships and architecture links are made of.
+ *
+ *   ─────▷   'triangle'        hollow triangle (inheritance, realisation)
+ *   ─────▶   'arrow'           solid triangle  (a message, a request)
+ *   ─────>   'open'            open chevron    (association, dependency, async)
+ *   ◇─────   'diamond'         hollow diamond  (aggregation, at the owner)
+ *   ◆─────   'diamond-filled'  solid diamond   (composition, at the owner)
+ *
+ * Each end marker is its own small closed path with a role (`end-solid`,
+ * `end-hollow`, `end-open`), so the stylesheet decides how it looks. The line
+ * stops where the marker begins, so it never shows through a hollow head.
+ */
+import { Box, Scene, Tone } from './scene';
+import { Vec } from './vec';
+export type ConnectorEnd = 'none' | 'arrow' | 'open' | 'triangle' | 'diamond' | 'diamond-filled';
+/** A box given by its CENTRE and size, like a rect node. */
+export interface Frame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Where the ray from a box's centre toward `toward` leaves the box.
+ * The ray is centre + t·d. It hits the vertical sides at t = (w/2)/|dx| and the
+ * horizontal sides at t = (h/2)/|dy|; whichever comes first is the exit.
+ */
+export declare function rectEdge(f: Frame, toward: Vec): Vec;
+/** A centred Frame from a top-left Box. */
+export declare const frameOf: (b: Box) => Frame;
+export interface ConnectorOptions {
+    id: string;
+    from: Vec | Frame;
+    to: Vec | Frame;
+    /** 'straight' (default) or 'elbow': right-angled, leaving and entering through the facing sides. */
+    route?: 'straight' | 'elbow';
+    start?: ConnectorEnd;
+    end?: ConnectorEnd;
+    dashed?: boolean;
+    tone?: Tone;
+    width?: number;
+    /** Text at the middle of the line. */
+    label?: string;
+    /** Small text near each end (UML multiplicities like '1' and '0..*'). */
+    startLabel?: string;
+    endLabel?: string;
+    /** Points to pass through on the way (overrides `route`), e.g. a self-message loop. */
+    via?: readonly Vec[];
+    /** Gap left between the line and a point endpoint (boxes already stop at their edge). */
+    gap?: number;
+    opacity?: number;
+}
+export interface ConnectorScene extends Scene {
+    /** The route actually drawn, before trimming for the end markers. */
+    points: Vec[];
+    /** A point a fraction t (0..1) of the way along the route, by length. */
+    along(t: number): Vec;
+}
+/** The route between the two ends, as a polyline. */
+export declare function route(from: Vec | Frame, to: Vec | Frame, kind?: 'straight' | 'elbow', gap?: number): Vec[];
+/** Point a fraction t along a polyline, measured by length. */
+export declare function pointAlong(pts: readonly Vec[], t: number): Vec;
+export declare function connector(o: ConnectorOptions): ConnectorScene;

package/dist/connector.js

@@ -0,0 +1,108 @@
+import { path, text } from "./scene.js";
+import { V2, vadd, vdist, vnorm, vperp, vscale, vsub } from "./vec.js";
+const isFrame = (v) => "w" in v && "h" in v;
+function rectEdge(f, toward) {
+  const dx = toward.x - f.x, dy = toward.y - f.y;
+  if (dx === 0 && dy === 0) return V2(f.x, f.y);
+  const tx = dx === 0 ? Infinity : f.w / 2 / Math.abs(dx);
+  const ty = dy === 0 ? Infinity : f.h / 2 / Math.abs(dy);
+  const t = Math.min(tx, ty);
+  return V2(f.x + dx * t, f.y + dy * t);
+}
+const frameOf = (b) => ({ x: b.x + b.w / 2, y: b.y + b.h / 2, w: b.w, h: b.h });
+const MARKERS = {
+  arrow: { len: 11, half: 5, trim: 9 },
+  open: { len: 10, half: 6, trim: 0 },
+  triangle: { len: 14, half: 8, trim: 14 },
+  diamond: { len: 22, half: 7, trim: 22 },
+  "diamond-filled": { len: 22, half: 7, trim: 22 }
+};
+function route(from, to, kind = "straight", gap = 0) {
+  const c0 = V2(from.x, from.y), c1 = V2(to.x, to.y);
+  if (kind === "elbow" && isFrame(from) && isFrame(to)) {
+    const dx = c1.x - c0.x, dy = c1.y - c0.y;
+    if (Math.abs(dy) * 1.2 >= Math.abs(dx)) {
+      const s2 = Math.sign(dy) || 1;
+      const a3 = V2(c0.x, c0.y + s2 * from.h / 2), b3 = V2(c1.x, c1.y - s2 * to.h / 2);
+      if (Math.abs(a3.x - b3.x) < 1) return [a3, b3];
+      const my = (a3.y + b3.y) / 2;
+      return [a3, V2(a3.x, my), V2(b3.x, my), b3];
+    }
+    const s = Math.sign(dx) || 1;
+    const a2 = V2(c0.x + s * from.w / 2, c0.y), b2 = V2(c1.x - s * to.w / 2, c1.y);
+    if (Math.abs(a2.y - b2.y) < 1) return [a2, b2];
+    const mx = (a2.x + b2.x) / 2;
+    return [a2, V2(mx, a2.y), V2(mx, b2.y), b2];
+  }
+  const a = isFrame(from) ? rectEdge(from, c1) : vadd(c0, vscale(vnorm(vsub(c1, c0)), gap));
+  const b = isFrame(to) ? rectEdge(to, c0) : vadd(c1, vscale(vnorm(vsub(c0, c1)), gap));
+  return [a, b];
+}
+function pointAlong(pts, t) {
+  const lens = pts.slice(1).map((p, i) => vdist(pts[i], p));
+  let d = Math.max(0, Math.min(1, t)) * lens.reduce((s, l) => s + l, 0);
+  for (let i = 0; i < lens.length; i++) {
+    if (d <= lens[i] || i === lens.length - 1) {
+      const k = lens[i] ? d / lens[i] : 0;
+      return V2(pts[i].x + (pts[i + 1].x - pts[i].x) * k, pts[i].y + (pts[i + 1].y - pts[i].y) * k);
+    }
+    d -= lens[i];
+  }
+  return pts[0];
+}
+function marker(kind, tip, dir) {
+  const { len, half } = MARKERS[kind];
+  const back = (k) => vsub(tip, vscale(dir, k));
+  const side = vperp(dir);
+  const at = (k, s) => vadd(back(k), vscale(side, s));
+  switch (kind) {
+    case "arrow":
+      return { pts: [tip, at(len, half), at(len, -half)], closed: true, role: "end-solid" };
+    case "open":
+      return { pts: [at(len, half), tip, at(len, -half)], closed: false, role: "end-open" };
+    case "triangle":
+      return { pts: [tip, at(len, half), at(len, -half)], closed: true, role: "end-hollow" };
+    case "diamond":
+    case "diamond-filled":
+      return { pts: [tip, at(len / 2, half), back(len), at(len / 2, -half)], closed: true, role: kind === "diamond" ? "end-hollow" : "end-solid" };
+  }
+}
+function connector(o) {
+  const pts = o.via?.length ? [V2(o.from.x, o.from.y), ...o.via.map((p) => V2(p.x, p.y)), V2(o.to.x, o.to.y)] : route(o.from, o.to, o.route, o.gap ?? 0);
+  const start = o.start ?? "none", end = o.end ?? "arrow";
+  const n = pts.length;
+  const dirEnd = vnorm(vsub(pts[n - 1], pts[n - 2]));
+  const dirStart = vnorm(vsub(pts[0], pts[1]));
+  const line = pts.map((p) => V2(p.x, p.y));
+  if (end !== "none") line[n - 1] = vsub(pts[n - 1], vscale(dirEnd, MARKERS[end].trim));
+  if (start !== "none") line[0] = vsub(pts[0], vscale(dirStart, MARKERS[start].trim));
+  const common = { tone: o.tone, opacity: o.opacity };
+  const nodes = [
+    path({ id: `${o.id}:line`, points: line.map((p) => [p.x, p.y]), role: "connector", dashed: o.dashed, width: o.width ?? 1.5, ...common })
+  ];
+  for (const [k, kind, tip, dir] of [["start", start, pts[0], dirStart], ["end", end, pts[n - 1], dirEnd]]) {
+    if (kind === "none") continue;
+    const m = marker(kind, tip, dir);
+    nodes.push(path({ id: `${o.id}:${k}`, points: m.pts.map((p) => [p.x, p.y]), closed: m.closed, role: m.role, width: o.width ?? 1.5, ...common }));
+  }
+  if (o.label) {
+    const m = pointAlong(pts, 0.5);
+    nodes.push(text({ id: `${o.id}:label`, x: m.x, y: m.y, text: o.label, size: 12, role: "edge-label", ...common }));
+  }
+  const endLabel = (k, s, tip, dir) => {
+    if (!s) return;
+    const p = vadd(vsub(tip, vscale(dir, 20)), vscale(vperp(dir), 11));
+    nodes.push(text({ id: `${o.id}:${k}-label`, x: p.x, y: p.y, text: s, size: 11, role: "end-label", ...common }));
+  };
+  endLabel("start", o.startLabel, pts[0], dirStart);
+  endLabel("end", o.endLabel, pts[n - 1], dirEnd);
+  return { nodes, points: pts, along: (t) => pointAlong(pts, t) };
+}
+export {
+  connector,
+  frameOf,
+  pointAlong,
+  rectEdge,
+  route
+};
+//# sourceMappingURL=connector.js.map

package/dist/connector.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/connector.ts"],
+  "sourcesContent": ["/**\n * Connectors: a line between two boxes (or points) with a decoration at either\n * end. This is what UML relationships and architecture links are made of.\n *\n *   \u2500\u2500\u2500\u2500\u2500\u25B7   'triangle'        hollow triangle (inheritance, realisation)\n *   \u2500\u2500\u2500\u2500\u2500\u25B6   'arrow'           solid triangle  (a message, a request)\n *   \u2500\u2500\u2500\u2500\u2500>   'open'            open chevron    (association, dependency, async)\n *   \u25C7\u2500\u2500\u2500\u2500\u2500   'diamond'         hollow diamond  (aggregation, at the owner)\n *   \u25C6\u2500\u2500\u2500\u2500\u2500   'diamond-filled'  solid diamond   (composition, at the owner)\n *\n * Each end marker is its own small closed path with a role (`end-solid`,\n * `end-hollow`, `end-open`), so the stylesheet decides how it looks. The line\n * stops where the marker begins, so it never shows through a hollow head.\n */\nimport { Box, Scene, SceneNode, Tone, path, text } from './scene';\nimport { V2, Vec, vadd, vdist, vnorm, vperp, vscale, vsub } from './vec';\n\nexport type ConnectorEnd = 'none' | 'arrow' | 'open' | 'triangle' | 'diamond' | 'diamond-filled';\n\n/** A box given by its CENTRE and size, like a rect node. */\nexport interface Frame {\n  x: number;\n  y: number;\n  w: number;\n  h: number;\n}\n\nconst isFrame = (v: Vec | Frame): v is Frame => 'w' in v && 'h' in v;\n\n/**\n * Where the ray from a box's centre toward `toward` leaves the box.\n * The ray is centre + t\u00B7d. It hits the vertical sides at t = (w/2)/|dx| and the\n * horizontal sides at t = (h/2)/|dy|; whichever comes first is the exit.\n */\nexport function rectEdge(f: Frame, toward: Vec): Vec {\n  const dx = toward.x - f.x, dy = toward.y - f.y;\n  if (dx === 0 && dy === 0) return V2(f.x, f.y);\n  const tx = dx === 0 ? Infinity : f.w / 2 / Math.abs(dx);\n  const ty = dy === 0 ? Infinity : f.h / 2 / Math.abs(dy);\n  const t = Math.min(tx, ty);\n  return V2(f.x + dx * t, f.y + dy * t);\n}\n\n/** A centred Frame from a top-left Box. */\nexport const frameOf = (b: Box): Frame => ({ x: b.x + b.w / 2, y: b.y + b.h / 2, w: b.w, h: b.h });\n\nexport interface ConnectorOptions {\n  id: string;\n  from: Vec | Frame;\n  to: Vec | Frame;\n  /** 'straight' (default) or 'elbow': right-angled, leaving and entering through the facing sides. */\n  route?: 'straight' | 'elbow';\n  start?: ConnectorEnd;\n  end?: ConnectorEnd;\n  dashed?: boolean;\n  tone?: Tone;\n  width?: number;\n  /** Text at the middle of the line. */\n  label?: string;\n  /** Small text near each end (UML multiplicities like '1' and '0..*'). */\n  startLabel?: string;\n  endLabel?: string;\n  /** Points to pass through on the way (overrides `route`), e.g. a self-message loop. */\n  via?: readonly Vec[];\n  /** Gap left between the line and a point endpoint (boxes already stop at their edge). */\n  gap?: number;\n  opacity?: number;\n}\n\nexport interface ConnectorScene extends Scene {\n  /** The route actually drawn, before trimming for the end markers. */\n  points: Vec[];\n  /** A point a fraction t (0..1) of the way along the route, by length. */\n  along(t: number): Vec;\n}\n\n/** Marker length (how far back along the line it reaches) and half-width. */\nconst MARKERS: Record<Exclude<ConnectorEnd, 'none'>, { len: number; half: number; trim: number }> = {\n  arrow: { len: 11, half: 5, trim: 9 },\n  open: { len: 10, half: 6, trim: 0 },\n  triangle: { len: 14, half: 8, trim: 14 },\n  diamond: { len: 22, half: 7, trim: 22 },\n  'diamond-filled': { len: 22, half: 7, trim: 22 },\n};\n\n/** The route between the two ends, as a polyline. */\nexport function route(from: Vec | Frame, to: Vec | Frame, kind: 'straight' | 'elbow' = 'straight', gap = 0): Vec[] {\n  const c0 = V2(from.x, from.y), c1 = V2(to.x, to.y);\n  if (kind === 'elbow' && isFrame(from) && isFrame(to)) {\n    const dx = c1.x - c0.x, dy = c1.y - c0.y;\n    // Leave through the sides that face each other. Mostly-vertical pairs (a\n    // class and its parent) go top/bottom, so inheritance trees read top-down.\n    if (Math.abs(dy) * 1.2 >= Math.abs(dx)) {\n      const s = Math.sign(dy) || 1;\n      const a = V2(c0.x, c0.y + (s * from.h) / 2), b = V2(c1.x, c1.y - (s * to.h) / 2);\n      if (Math.abs(a.x - b.x) < 1) return [a, b];\n      const my = (a.y + b.y) / 2;\n      return [a, V2(a.x, my), V2(b.x, my), b];\n    }\n    const s = Math.sign(dx) || 1;\n    const a = V2(c0.x + (s * from.w) / 2, c0.y), b = V2(c1.x - (s * to.w) / 2, c1.y);\n    if (Math.abs(a.y - b.y) < 1) return [a, b];\n    const mx = (a.x + b.x) / 2;\n    return [a, V2(mx, a.y), V2(mx, b.y), b];\n  }\n  const a = isFrame(from) ? rectEdge(from, c1) : vadd(c0, vscale(vnorm(vsub(c1, c0)), gap));\n  const b = isFrame(to) ? rectEdge(to, c0) : vadd(c1, vscale(vnorm(vsub(c0, c1)), gap));\n  return [a, b];\n}\n\n/** Point a fraction t along a polyline, measured by length. */\nexport function pointAlong(pts: readonly Vec[], t: number): Vec {\n  const lens = pts.slice(1).map((p, i) => vdist(pts[i], p));\n  let d = Math.max(0, Math.min(1, t)) * lens.reduce((s, l) => s + l, 0);\n  for (let i = 0; i < lens.length; i++) {\n    if (d <= lens[i] || i === lens.length - 1) {\n      const k = lens[i] ? d / lens[i] : 0;\n      return V2(pts[i].x + (pts[i + 1].x - pts[i].x) * k, pts[i].y + (pts[i + 1].y - pts[i].y) * k);\n    }\n    d -= lens[i];\n  }\n  return pts[0];\n}\n\n/**\n * The marker at `tip`, pointing along `dir` (unit vector, pointing OUT of the line).\n * Returns the outline and how much of the line it covers.\n */\nfunction marker(kind: Exclude<ConnectorEnd, 'none'>, tip: Vec, dir: Vec): { pts: Vec[]; closed: boolean; role: string } {\n  const { len, half } = MARKERS[kind];\n  const back = (k: number) => vsub(tip, vscale(dir, k));\n  const side = vperp(dir);\n  const at = (k: number, s: number) => vadd(back(k), vscale(side, s));\n  switch (kind) {\n    case 'arrow':\n      return { pts: [tip, at(len, half), at(len, -half)], closed: true, role: 'end-solid' };\n    case 'open':\n      return { pts: [at(len, half), tip, at(len, -half)], closed: false, role: 'end-open' };\n    case 'triangle':\n      return { pts: [tip, at(len, half), at(len, -half)], closed: true, role: 'end-hollow' };\n    case 'diamond':\n    case 'diamond-filled':\n      return { pts: [tip, at(len / 2, half), back(len), at(len / 2, -half)], closed: true, role: kind === 'diamond' ? 'end-hollow' : 'end-solid' };\n  }\n}\n\nexport function connector(o: ConnectorOptions): ConnectorScene {\n  const pts = o.via?.length\n    ? [V2(o.from.x, o.from.y), ...o.via.map((p) => V2(p.x, p.y)), V2(o.to.x, o.to.y)]\n    : route(o.from, o.to, o.route, o.gap ?? 0);\n  const start = o.start ?? 'none', end = o.end ?? 'arrow';\n  const n = pts.length;\n  const dirEnd = vnorm(vsub(pts[n - 1], pts[n - 2]));\n  const dirStart = vnorm(vsub(pts[0], pts[1]));\n  // trim the line so it stops where each marker begins\n  const line = pts.map((p) => V2(p.x, p.y));\n  if (end !== 'none') line[n - 1] = vsub(pts[n - 1], vscale(dirEnd, MARKERS[end].trim));\n  if (start !== 'none') line[0] = vsub(pts[0], vscale(dirStart, MARKERS[start].trim));\n\n  const common = { tone: o.tone, opacity: o.opacity };\n  const nodes: SceneNode[] = [\n    path({ id: `${o.id}:line`, points: line.map((p) => [p.x, p.y] as const), role: 'connector', dashed: o.dashed, width: o.width ?? 1.5, ...common }),\n  ];\n  for (const [k, kind, tip, dir] of [['start', start, pts[0], dirStart], ['end', end, pts[n - 1], dirEnd]] as const) {\n    if (kind === 'none') continue;\n    const m = marker(kind, tip, dir);\n    nodes.push(path({ id: `${o.id}:${k}`, points: m.pts.map((p) => [p.x, p.y] as const), closed: m.closed, role: m.role, width: o.width ?? 1.5, ...common }));\n  }\n  if (o.label) {\n    const m = pointAlong(pts, 0.5);\n    nodes.push(text({ id: `${o.id}:label`, x: m.x, y: m.y, text: o.label, size: 12, role: 'edge-label', ...common }));\n  }\n  // multiplicities sit just off the line, a little way in from each end\n  const endLabel = (k: string, s: string | undefined, tip: Vec, dir: Vec) => {\n    if (!s) return;\n    const p = vadd(vsub(tip, vscale(dir, 20)), vscale(vperp(dir), 11));\n    nodes.push(text({ id: `${o.id}:${k}-label`, x: p.x, y: p.y, text: s, size: 11, role: 'end-label', ...common }));\n  };\n  endLabel('start', o.startLabel, pts[0], dirStart);\n  endLabel('end', o.endLabel, pts[n - 1], dirEnd);\n  return { nodes, points: pts, along: (t) => pointAlong(pts, t) };\n}\n"],
+  "mappings": "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",
+  "names": ["s", "a", "b"]
+}

package/dist/describe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Turning a node into SVG, split into two halves:
+ *
+ *  - numericProps(node): the numbers that can be tweened (x, y, r, opacity…)
+ *  - describe(node, props): which SVG tag + attributes to draw for those numbers
+ *
+ * The DOM renderer calls describe() every animation frame with interpolated
+ * props; the string renderer calls it once with the final props. Sharing this
+ * one function means both renderers can never disagree about what a node looks like.
+ */
+import { NumericProps, SceneNode } from './scene';
+import { Geometry } from './themes';
+import { Vec } from './vec';
+/** Path points live in the flat numeric bag as p0, p1, … (x0 y0 x1 y1 …) so the tween engine needs no special case. */
+export declare function numericProps(n: SceneNode): NumericProps;
+export type SvgTag = 'circle' | 'rect' | 'text' | 'path';
+export interface Description {
+    tag: SvgTag;
+    attrs: Record<string, string>;
+    text?: string;
+    /** Inner SVG markup instead of plain text (maths labels become <tspan>s). */
+    html?: string;
+}
+export declare const tagFor: (kind: SceneNode['kind']) => SvgTag;
+/** Read the flat bag back into points. */
+export declare function pointsOf(p: NumericProps, count: number): Array<[number, number]>;
+export declare function classFor(n: SceneNode): string;
+export declare function describe(n: SceneNode, p: NumericProps, g?: Geometry): Description;
+/** Control point of a bent line: midpoint pushed `bend` px sideways. */
+export declare function bendControl(a: Vec, b: Vec, bend: number): Vec;
+/**
+ * Path data for a (possibly curved) line plus its arrowhead, as ONE path so a
+ * single element can be tweened.
+ *
+ *  - 'chevron':  an open "V" — stroke only.
+ *  - 'triangle': a closed triangle that CSS fills (class dv-head-solid).
+ *    Filling a path fills EVERY sub-path, and an open curve "M a Q c b" would
+ *    fill the lens between the curve and its chord. So the line part retraces
+ *    itself back to the start: a shape that goes there and back encloses zero
+ *    area, so only the triangle gets filled. (A straight line has zero area anyway.)
+ */
+export declare function arrowPath(a: Vec, b: Vec, bend: number, head: boolean, width: number, style?: 'chevron' | 'triangle', headScale?: number): string;
+/** Point at parameter t on the (possibly curved) line — handy for edge labels. */
+export declare function pointOnArrow(a: Vec, b: Vec, bend: number, t: number): Vec;

package/dist/describe.js

@@ -0,0 +1,131 @@
+import { geometry } from "./themes.js";
+import { pathData } from "./path.js";
+import { mathTspans, parseMath } from "./mathtext.js";
+import { V2, vadd, vnorm, vperp, vscale, vsub } from "./vec.js";
+function numericProps(n) {
+  const opacity = n.opacity ?? 1;
+  switch (n.kind) {
+    case "path": {
+      const o = { width: n.width ?? 1.5, opacity };
+      n.points.forEach(([x, y], i) => (o[`p${2 * i}`] = x, o[`p${2 * i + 1}`] = y));
+      return o;
+    }
+    case "circle":
+      return { x: n.x, y: n.y, r: n.r, opacity };
+    case "rect":
+      return { x: n.x, y: n.y, w: n.w, h: n.h, rx: n.rx ?? 0, opacity };
+    case "text":
+      return { x: n.x, y: n.y, size: n.size ?? 16, opacity };
+    case "arrow":
+      return { x1: n.x1, y1: n.y1, x2: n.x2, y2: n.y2, bend: n.bend ?? 0, width: n.width ?? 2, opacity };
+  }
+}
+const tagFor = (kind) => kind === "arrow" ? "path" : kind;
+function pointsOf(p, count) {
+  return Array.from({ length: count }, (_, i) => [p[`p${2 * i}`], p[`p${2 * i + 1}`]]);
+}
+function classFor(n) {
+  const c = ["dv", `dv-${n.kind}`, `dv-tone-${n.tone ?? "default"}`];
+  if (n.role) c.push(`dv-role-${n.role}`);
+  if (n.kind === "path" && !n.closed) c.push("dv-open");
+  if (n.dashed) c.push("dv-dashed");
+  if (n.draggable) c.push("dv-draggable");
+  if (n.interactive || n.draggable) c.push("dv-interactive");
+  return c.join(" ");
+}
+const f = (v) => String(Math.round(v * 100) / 100);
+function describe(n, p, g = geometry) {
+  const solidHead = n.kind === "arrow" && (n.head ?? true) && g.head === "triangle";
+  const attrs = {
+    class: classFor(n) + (solidHead ? " dv-head-solid" : ""),
+    "data-id": n.id,
+    opacity: f(p.opacity),
+    // draggable things are reachable with Tab and movable with the arrow keys
+    ...n.draggable ? { tabindex: "0" } : {}
+  };
+  switch (n.kind) {
+    case "circle":
+      return { tag: "circle", attrs: { ...attrs, cx: f(p.x), cy: f(p.y), r: f(Math.max(0, p.r)) } };
+    case "rect":
+      return {
+        tag: "rect",
+        attrs: {
+          ...attrs,
+          x: f(p.x - p.w / 2),
+          y: f(p.y - p.h / 2),
+          width: f(Math.max(0, p.w)),
+          height: f(Math.max(0, p.h)),
+          rx: f(p.rx * g.rxScale)
+        }
+      };
+    case "text":
+      return {
+        tag: "text",
+        // role 'math' is typeset: italic variables, upright numbers, real superscripts
+        ...n.role === "math" ? { html: mathTspans(parseMath(n.text), p.size) } : { text: n.text },
+        attrs: {
+          ...attrs,
+          x: f(p.x),
+          y: f(p.y),
+          "font-size": f(p.size),
+          "text-anchor": n.anchor ?? "middle",
+          "dominant-baseline": "central",
+          ...n.weight != null ? { "font-weight": String(n.weight) } : {}
+        }
+      };
+    case "path":
+      return {
+        tag: "path",
+        attrs: { ...attrs, d: pathData(pointsOf(p, n.points.length), !!n.closed, !!n.smooth), "stroke-width": f(p.width) }
+      };
+    case "arrow": {
+      const w = p.width * g.strokeScale;
+      return {
+        tag: "path",
+        attrs: {
+          ...attrs,
+          d: arrowPath(V2(p.x1, p.y1), V2(p.x2, p.y2), p.bend, n.head ?? true, w, g.head, g.headScale),
+          "stroke-width": f(w)
+        }
+      };
+    }
+  }
+}
+function bendControl(a, b, bend) {
+  const mid = V2((a.x + b.x) / 2, (a.y + b.y) / 2);
+  return vadd(mid, vscale(vperp(vnorm(vsub(b, a))), bend));
+}
+function arrowPath(a, b, bend, head, width, style = "chevron", headScale = 1) {
+  const curved = Math.abs(bend) > 0.5;
+  const c = curved ? bendControl(a, b, bend) : null;
+  const dir = vnorm(vsub(b, c ?? a));
+  const hasHead = head && (dir.x !== 0 || dir.y !== 0);
+  const size = (6 + width * 1.5) * headScale;
+  const solid = hasHead && style === "triangle";
+  const end = solid ? vsub(b, vscale(dir, size * 0.8)) : b;
+  let d = c ? `M${f(a.x)} ${f(a.y)}Q${f(c.x)} ${f(c.y)} ${f(end.x)} ${f(end.y)}` : `M${f(a.x)} ${f(a.y)}L${f(end.x)} ${f(end.y)}`;
+  if (solid && c) d += `Q${f(c.x)} ${f(c.y)} ${f(a.x)} ${f(a.y)}`;
+  if (!hasHead) return d;
+  const back = vsub(b, vscale(dir, size));
+  const spread = solid ? 0.55 : 0.6;
+  const side = vscale(vperp(dir), size * spread);
+  const l = vadd(back, side), r = vsub(back, side);
+  d += solid ? `M${f(b.x)} ${f(b.y)}L${f(l.x)} ${f(l.y)}L${f(r.x)} ${f(r.y)}Z` : `M${f(l.x)} ${f(l.y)}L${f(b.x)} ${f(b.y)}L${f(r.x)} ${f(r.y)}`;
+  return d;
+}
+function pointOnArrow(a, b, bend, t) {
+  const c = bendControl(a, b, bend);
+  const u = 1 - t;
+  return V2(u * u * a.x + 2 * u * t * c.x + t * t * b.x, u * u * a.y + 2 * u * t * c.y + t * t * b.y);
+}
+export {
+  arrowPath,
+  bendControl,
+  classFor,
+  describe,
+  numericProps,
+  pointOnArrow,
+  pointsOf,
+  tagFor
+};
+//# sourceMappingURL=describe.js.map

package/dist/describe.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/describe.ts"],
+  "sourcesContent": ["/**\n * Turning a node into SVG, split into two halves:\n *\n *  - numericProps(node): the numbers that can be tweened (x, y, r, opacity\u2026)\n *  - describe(node, props): which SVG tag + attributes to draw for those numbers\n *\n * The DOM renderer calls describe() every animation frame with interpolated\n * props; the string renderer calls it once with the final props. Sharing this\n * one function means both renderers can never disagree about what a node looks like.\n */\nimport { NumericProps, SceneNode } from './scene';\nimport { Geometry, geometry } from './themes';\nimport { pathData } from './path';\nimport { mathTspans, parseMath } from './mathtext';\nimport { V2, Vec, vadd, vnorm, vperp, vscale, vsub } from './vec';\n\n/** Path points live in the flat numeric bag as p0, p1, \u2026 (x0 y0 x1 y1 \u2026) so the tween engine needs no special case. */\n\nexport function numericProps(n: SceneNode): NumericProps {\n  const opacity = n.opacity ?? 1;\n  switch (n.kind) {\n    case 'path': {\n      const o: NumericProps = { width: n.width ?? 1.5, opacity };\n      n.points.forEach(([x, y], i) => ((o[`p${2 * i}`] = x), (o[`p${2 * i + 1}`] = y)));\n      return o;\n    }\n    case 'circle':\n      return { x: n.x, y: n.y, r: n.r, opacity };\n    case 'rect':\n      return { x: n.x, y: n.y, w: n.w, h: n.h, rx: n.rx ?? 0, opacity };\n    case 'text':\n      return { x: n.x, y: n.y, size: n.size ?? 16, opacity };\n    case 'arrow':\n      return { x1: n.x1, y1: n.y1, x2: n.x2, y2: n.y2, bend: n.bend ?? 0, width: n.width ?? 2, opacity };\n  }\n}\n\nexport type SvgTag = 'circle' | 'rect' | 'text' | 'path';\n\nexport interface Description {\n  tag: SvgTag;\n  attrs: Record<string, string>;\n  text?: string;\n  /** Inner SVG markup instead of plain text (maths labels become <tspan>s). */\n  html?: string;\n}\n\nexport const tagFor = (kind: SceneNode['kind']): SvgTag => (kind === 'arrow' ? 'path' : kind);\n\n/** Read the flat bag back into points. */\nexport function pointsOf(p: NumericProps, count: number): Array<[number, number]> {\n  return Array.from({ length: count }, (_, i) => [p[`p${2 * i}`], p[`p${2 * i + 1}`]] as [number, number]);\n}\n\nexport function classFor(n: SceneNode): string {\n  const c = ['dv', `dv-${n.kind}`, `dv-tone-${n.tone ?? 'default'}`];\n  if (n.role) c.push(`dv-role-${n.role}`);\n  if (n.kind === 'path' && !n.closed) c.push('dv-open');\n  if (n.dashed) c.push('dv-dashed');\n  if (n.draggable) c.push('dv-draggable');\n  if (n.interactive || n.draggable) c.push('dv-interactive');\n  return c.join(' ');\n}\n\n/** Round to 2 decimals so the DOM / SVG strings stay readable. */\nconst f = (v: number) => String(Math.round(v * 100) / 100);\n\nexport function describe(n: SceneNode, p: NumericProps, g: Geometry = geometry): Description {\n  const solidHead = n.kind === 'arrow' && (n.head ?? true) && g.head === 'triangle';\n  const attrs: Record<string, string> = {\n    class: classFor(n) + (solidHead ? ' dv-head-solid' : ''),\n    'data-id': n.id,\n    opacity: f(p.opacity),\n    // draggable things are reachable with Tab and movable with the arrow keys\n    ...(n.draggable ? { tabindex: '0' } : {}),\n  };\n  switch (n.kind) {\n    case 'circle':\n      return { tag: 'circle', attrs: { ...attrs, cx: f(p.x), cy: f(p.y), r: f(Math.max(0, p.r)) } };\n    case 'rect':\n      return {\n        tag: 'rect',\n        attrs: {\n          ...attrs,\n          x: f(p.x - p.w / 2),\n          y: f(p.y - p.h / 2),\n          width: f(Math.max(0, p.w)),\n          height: f(Math.max(0, p.h)),\n          rx: f(p.rx * g.rxScale),\n        },\n      };\n    case 'text':\n      return {\n        tag: 'text',\n        // role 'math' is typeset: italic variables, upright numbers, real superscripts\n        ...(n.role === 'math' ? { html: mathTspans(parseMath(n.text), p.size) } : { text: n.text }),\n        attrs: {\n          ...attrs,\n          x: f(p.x),\n          y: f(p.y),\n          'font-size': f(p.size),\n          'text-anchor': n.anchor ?? 'middle',\n          'dominant-baseline': 'central',\n          ...(n.weight != null ? { 'font-weight': String(n.weight) } : {}),\n        },\n      };\n    case 'path':\n      return {\n        tag: 'path',\n        attrs: { ...attrs, d: pathData(pointsOf(p, n.points.length), !!n.closed, !!n.smooth), 'stroke-width': f(p.width) },\n      };\n    case 'arrow': {\n      const w = p.width * g.strokeScale;\n      return {\n        tag: 'path',\n        attrs: {\n          ...attrs,\n          d: arrowPath(V2(p.x1, p.y1), V2(p.x2, p.y2), p.bend, n.head ?? true, w, g.head, g.headScale),\n          'stroke-width': f(w),\n        },\n      };\n    }\n  }\n}\n\n/** Control point of a bent line: midpoint pushed `bend` px sideways. */\nexport function bendControl(a: Vec, b: Vec, bend: number): Vec {\n  const mid = V2((a.x + b.x) / 2, (a.y + b.y) / 2);\n  return vadd(mid, vscale(vperp(vnorm(vsub(b, a))), bend));\n}\n\n/**\n * Path data for a (possibly curved) line plus its arrowhead, as ONE path so a\n * single element can be tweened.\n *\n *  - 'chevron':  an open \"V\" \u2014 stroke only.\n *  - 'triangle': a closed triangle that CSS fills (class dv-head-solid).\n *    Filling a path fills EVERY sub-path, and an open curve \"M a Q c b\" would\n *    fill the lens between the curve and its chord. So the line part retraces\n *    itself back to the start: a shape that goes there and back encloses zero\n *    area, so only the triangle gets filled. (A straight line has zero area anyway.)\n */\nexport function arrowPath(\n  a: Vec,\n  b: Vec,\n  bend: number,\n  head: boolean,\n  width: number,\n  style: 'chevron' | 'triangle' = 'chevron',\n  headScale = 1,\n): string {\n  const curved = Math.abs(bend) > 0.5;\n  const c = curved ? bendControl(a, b, bend) : null;\n  // A quadratic curve arrives along (end - control), a straight line along (end - start).\n  const dir = vnorm(vsub(b, c ?? a));\n  const hasHead = head && (dir.x !== 0 || dir.y !== 0);\n  const size = (6 + width * 1.5) * headScale;\n  const solid = hasHead && style === 'triangle';\n  // A solid head covers the last bit of the line, so stop the line at its base.\n  const end = solid ? vsub(b, vscale(dir, size * 0.8)) : b;\n\n  let d = c ? `M${f(a.x)} ${f(a.y)}Q${f(c.x)} ${f(c.y)} ${f(end.x)} ${f(end.y)}` : `M${f(a.x)} ${f(a.y)}L${f(end.x)} ${f(end.y)}`;\n  if (solid && c) d += `Q${f(c.x)} ${f(c.y)} ${f(a.x)} ${f(a.y)}`; // retrace: zero fill area\n  if (!hasHead) return d;\n\n  const back = vsub(b, vscale(dir, size));\n  const spread = solid ? 0.55 : 0.6;\n  const side = vscale(vperp(dir), size * spread);\n  const l = vadd(back, side), r = vsub(back, side);\n  d += solid\n    ? `M${f(b.x)} ${f(b.y)}L${f(l.x)} ${f(l.y)}L${f(r.x)} ${f(r.y)}Z`\n    : `M${f(l.x)} ${f(l.y)}L${f(b.x)} ${f(b.y)}L${f(r.x)} ${f(r.y)}`;\n  return d;\n}\n\n/** Point at parameter t on the (possibly curved) line \u2014 handy for edge labels. */\nexport function pointOnArrow(a: Vec, b: Vec, bend: number, t: number): Vec {\n  const c = bendControl(a, b, bend);\n  const u = 1 - t;\n  return V2(u * u * a.x + 2 * u * t * c.x + t * t * b.x, u * u * a.y + 2 * u * t * c.y + t * t * b.y);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/ds/array.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Arrays: a row of cells, with index labels underneath.
+ *
+ * The important design decision is WHAT A CELL'S ID IS:
+ *  - the cell box + value text are identified by the element's `key`
+ *    (default: its index). Give elements stable keys and a swap becomes two
+ *    cells sliding past each other instead of two numbers changing in place.
+ *  - the index labels (0, 1, 2…) are identified by POSITION, because index 3
+ *    is always index 3 no matter what value sits in it.
+ */
+import { Part, Scene, Tone } from '../scene';
+import { Vec } from '../vec';
+import { Key, ToneSpec } from './common';
+export interface ArrayOptions<T = unknown> {
+    id?: string;
+    /** Top-left corner of the first cell. */
+    x?: number;
+    y?: number;
+    /** Cell size in px. Default 48. */
+    cell?: number;
+    gap?: number;
+    /** Stable identity per element (must be unique). Default: the index. */
+    keys?: Key[];
+    /** Tone per INDEX: `{ 2: 'active' }` or `(i, v) => …`. */
+    tones?: ToneSpec<number, T>;
+    showIndices?: boolean;
+    /** Text to show instead of String(value). */
+    format?: (v: T, i: number) => string;
+    /** Lay the cells out top-to-bottom instead of left-to-right. */
+    vertical?: boolean;
+    /** Where new cells fly in from / old cells fly out to (offset in px). */
+    enterOffset?: Vec;
+    exitOffset?: Vec;
+    interactive?: boolean;
+}
+export interface ArrayDiagram extends Scene {
+    length: number;
+    cell: number;
+    center(i: number): Vec;
+    top(i: number): Vec;
+    bottom(i: number): Vec;
+    left(i: number): Vec;
+    right(i: number): Vec;
+    /** A highlight band behind cells lo..hi (inclusive). Put it BEFORE the array in combine(). */
+    window(lo: number, hi: number, o?: {
+        id?: string;
+        tone?: Tone;
+        pad?: number;
+    }): Part;
+}
+export declare function array<T>(values: readonly T[], o?: ArrayOptions<T>): ArrayDiagram;