@heyramzi/ui 1.54.2 → 2.0.1

package/src/canvas/headless/fit-viewport.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vite-plus/test";
+import type { CanvasNode } from "../types.js";
+import { diagramBounds, fitViewport, viewShowsContent } from "./fit-viewport.js";
+
+function node(id: string, x: number, y: number, size?: Partial<CanvasNode>): CanvasNode {
+  return { id, position: { x, y }, data: {}, ...size } as CanvasNode;
+}
+
+describe("diagramBounds", () => {
+  it("spans every top-level node, size read off the style object", () => {
+    const bounds = diagramBounds([
+      node("a", 0, 0, { style: { width: 520, height: 1484 } }),
+      node("b", 1600, 0, { style: { width: 460, height: 446 } }),
+    ]);
+    expect(bounds).toEqual({ x: 0, y: 0, width: 2060, height: 1484 });
+  });
+
+  it("ignores children, whose positions are relative to their parent", () => {
+    const bounds = diagramBounds([
+      node("parent", 0, 0, { style: { width: 500, height: 500 } }),
+      node("child", 20, 20, { parentId: "parent", style: { width: 460, height: 200 } }),
+    ]);
+    expect(bounds).toEqual({ x: 0, y: 0, width: 500, height: 500 });
+  });
+
+  it("returns null when there is nothing to frame", () => {
+    expect(diagramBounds([])).toBeNull();
+  });
+});
+
+describe("fitViewport", () => {
+  it("scales to the tighter axis and centres what is left over", () => {
+    const nodes = [node("a", 0, 0, { style: { width: 1000, height: 500 } })];
+    const viewport = fitViewport(nodes, { width: 500, height: 500 }, 0);
+
+    expect(viewport?.zoom).toBe(0.5);
+    expect(viewport?.x).toBe(0);
+    // 500 tall at zoom 0.5 is 250, so 125 of slack above and below.
+    expect(viewport?.y).toBe(125);
+  });
+
+  it("pulls a negative origin back into frame", () => {
+    const nodes = [node("a", -280, 120, { style: { width: 1000, height: 500 } })];
+    const viewport = fitViewport(nodes, { width: 1000, height: 500 }, 0);
+
+    expect(viewport?.zoom).toBe(1);
+    expect(viewport?.x).toBe(280);
+    expect(viewport?.y).toBe(-120);
+  });
+
+  it("honours padding as a fraction of the container", () => {
+    const nodes = [node("a", 0, 0, { style: { width: 1000, height: 1000 } })];
+    expect(fitViewport(nodes, { width: 500, height: 500 }, 0.1)?.zoom).toBeCloseTo(0.4);
+  });
+
+  it("returns null when the container has no size yet", () => {
+    const nodes = [node("a", 0, 0, { style: { width: 100, height: 100 } })];
+    expect(fitViewport(nodes, { width: 0, height: 0 })).toBeNull();
+  });
+});
+
+describe("viewShowsContent", () => {
+  const nodes = [{ position: { x: 0, y: 0 }, width: 400, height: 200 }];
+  const pane = { width: 1000, height: 700 };
+
+  it("accepts a view that frames the board", () => {
+    expect(viewShowsContent(nodes, { x: 200, y: 100, zoom: 1 }, pane, { left: 88 })).toBe(true);
+  });
+
+  it("rejects a view with no card on screen", () => {
+    expect(viewShowsContent(nodes, { x: -5000, y: 0, zoom: 1 }, pane)).toBe(false);
+  });
+
+  it("rejects a board that fits but sits cut off on the left", () => {
+    expect(viewShowsContent(nodes, { x: -60, y: 100, zoom: 1 }, pane, { left: 88 })).toBe(false);
+  });
+
+  it("lets a deliberate zoom into a part of a big board stand", () => {
+    expect(viewShowsContent(nodes, { x: -300, y: 0, zoom: 4 }, pane, { left: 88 })).toBe(true);
+  });
+
+  it("has nothing to miss on an empty board", () => {
+    expect(viewShowsContent([], { x: 9999, y: 0, zoom: 1 }, pane)).toBe(true);
+  });
+});

package/src/canvas/headless/fit-viewport.ts

@@ -0,0 +1,137 @@
+// WHY not SvelteFlow's `fitView`: it needs a paint to measure, and a deck slide
+// reads at once, so it blew up one corner of the drawing.
+
+// The saved diagram holds the geometry, so the viewport is computed from it.
+
+import type { CanvasViewport } from "../types.js";
+
+/** What a node occupies when the saved data does not say. */
+const FALLBACK_NODE = { width: 240, height: 80 };
+
+type Sized = { x: number; y: number; width: number; height: number };
+
+// WHY not `CanvasNode`: bounds only read geometry, so an xyflow `Node` fits too
+// and neither side of the boundary needs a cast.
+type GeometryNode = {
+  parentId?: string;
+  position: { x: number; y: number };
+  width?: number | null;
+  height?: number | null;
+  style?: unknown;
+};
+
+type Size = { width: number; height: number };
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function cssDim(css: string, prop: "width" | "height"): number | null {
+  const found = css.match(new RegExp(`(?:^|[;\\s])${prop}:\\s*(\\d+(?:\\.\\d+)?)px`))?.[1];
+  return found ? Number(found) : null;
+}
+
+/** A stored node often has a width and no height (the DOM measures it), so each side is read alone. */
+function styleDim(style: unknown, prop: "width" | "height"): number | null {
+  if (typeof style === "string") return cssDim(style, prop);
+  if (!style || typeof style !== "object") return null;
+  return num((style as Record<string, unknown>)[prop]);
+}
+
+function readSize(node: GeometryNode): Size {
+  return {
+    width: num(node.width) ?? styleDim(node.style, "width") ?? FALLBACK_NODE.width,
+    height: num(node.height) ?? styleDim(node.style, "height") ?? FALLBACK_NODE.height,
+  };
+}
+
+/**
+ * The box every top-level node sits in. Children are parent-relative, so
+ * counting them would push the bounds out and shrink the drawing.
+ */
+export function diagramBounds(nodes: GeometryNode[]): Sized | null {
+  const boxes = nodes
+    .filter((node) => !node.parentId)
+    .map((node) => ({ ...readSize(node), x: node.position.x, y: node.position.y }));
+  if (boxes.length === 0) return null;
+
+  const minX = Math.min(...boxes.map((box) => box.x));
+  const minY = Math.min(...boxes.map((box) => box.y));
+  const maxX = Math.max(...boxes.map((box) => box.x + box.width));
+  const maxY = Math.max(...boxes.map((box) => box.y + box.height));
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/**
+ * The viewport that centres `nodes` inside a `container` of the given size.
+ * `padding` is a fraction of the container, matching fitView's own meaning.
+ */
+export function fitViewport(
+  nodes: GeometryNode[],
+  container: { width: number; height: number },
+  padding = 0.04,
+): CanvasViewport | null {
+  const bounds = diagramBounds(nodes);
+  if (!bounds || bounds.width <= 0 || bounds.height <= 0) return null;
+  if (container.width <= 0 || container.height <= 0) return null;
+
+  const usableWidth = container.width * (1 - padding * 2);
+  const usableHeight = container.height * (1 - padding * 2);
+  const zoom = Math.min(usableWidth / bounds.width, usableHeight / bounds.height);
+
+  return {
+    x: (container.width - bounds.width * zoom) / 2 - bounds.x * zoom,
+    y: (container.height - bounds.height * zoom) / 2 - bounds.y * zoom,
+    zoom,
+  };
+}
+
+/** Below this a whole-board fit is too small to read a card's text. */
+const MIN_READABLE_ZOOM = 0.3;
+
+/*
+ * Where a board with no view opens: a board that fits reads whole, but a tall
+ * wall fits at 8%, so it fits its width and starts at the top.
+ */
+export function openingViewport(
+  nodes: GeometryNode[],
+  container: { width: number; height: number },
+  padding = 0.04,
+  gutter = 0,
+): CanvasViewport | null {
+  const whole = fitViewport(nodes, container, padding);
+  if (!whole || whole.zoom >= MIN_READABLE_ZOOM) return whole;
+
+  const bounds = diagramBounds(nodes);
+  if (!bounds) return null;
+  const inset = container.width * padding;
+  const left = inset + gutter;
+  const zoom = Math.min((container.width - left - inset) / bounds.width, 1);
+  return { x: left - bounds.x * zoom, y: inset - bounds.y * zoom, zoom };
+}
+
+/**
+ * Whether a saved view still shows the board: a card is on screen, and a fitting board isn't
+ * pushed off the left. `inset` is the tool rail's strip.
+ */
+export function viewShowsContent(
+  nodes: GeometryNode[],
+  viewport: CanvasViewport,
+  container: { width: number; height: number },
+  inset = { left: 0 },
+): boolean {
+  const bounds = diagramBounds(nodes);
+  if (!bounds || viewport.zoom <= 0) return true;
+  const left = (inset.left - viewport.x) / viewport.zoom;
+  const right = (container.width - viewport.x) / viewport.zoom;
+  const top = -viewport.y / viewport.zoom;
+  const bottom = (container.height - viewport.y) / viewport.zoom;
+  const onScreen =
+    bounds.x < right &&
+    bounds.x + bounds.width > left &&
+    bounds.y < bottom &&
+    bounds.y + bounds.height > top;
+  if (!onScreen) return false;
+  const fits = bounds.width * viewport.zoom <= container.width - inset.left;
+  return !(fits && bounds.x < left - 4 / viewport.zoom);
+}

package/src/canvas/headless/grid.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vite-plus/test";
+import { GRID_SIZE, snapWrittenNodes } from "./grid.js";
+
+const node = (id: string, x: number, y: number, extra: Record<string, unknown> = {}) => ({
+  id,
+  type: "note",
+  position: { x, y },
+  data: {},
+  ...extra,
+});
+
+// An agent wrote --x=103 --y=57 and the card sat between the dots.
+describe("snapWrittenNodes", () => {
+  it("snaps what a write created or moved and leaves the rest where it was", () => {
+    const before = [node("old", 103, 57), node("moved", 0, 0), node("frame", 1003, 57)];
+    const after = [
+      node("old", 103, 57),
+      node("moved", 117, 251),
+      node("frame", 1003, 57),
+      node("fresh", 103, 57),
+      node("inside", 43.5, 17, { parentId: "frame", extent: "parent" }),
+      node("pen", 103, 57, { type: "stroke" }),
+    ];
+    const byId = Object.fromEntries(snapWrittenNodes(before, after).map((n) => [n.id, n.position]));
+
+    expect(GRID_SIZE).toBe(20);
+    expect(byId.old).toEqual({ x: 103, y: 57 });
+    expect(byId.moved).toEqual({ x: 120, y: 260 });
+    expect(byId.fresh).toEqual({ x: 100, y: 60 });
+    // A frame at 1003,57 isn't on a dot, so a child snaps on the page, where the dots are: 1046.5 becomes 1040.
+    expect((byId.inside as { x: number }).x + 1003).toBe(1040);
+    expect(byId.pen).toEqual({ x: 103, y: 57 });
+  });
+});

package/src/canvas/headless/grid.ts

@@ -0,0 +1,94 @@
+// The magnets: the grid the editor snaps cards to. A write that isn't a drag snaps through here.
+
+import { STROKE_NODE } from "../pen/types.js";
+
+/** Flow units between two dots at the finest level. */
+export const GRID_SIZE = 20;
+
+/** The value xyflow's `snapGrid` prop takes. */
+export const SNAP_GRID: [number, number] = [GRID_SIZE, GRID_SIZE];
+
+/** Node types that keep their exact points. A stroke's origin is its bounding box, so moving it shifts the drawing. */
+export const FREEHAND_NODE_TYPES: ReadonlySet<string> = new Set([STROKE_NODE]);
+
+/** The nearest dot on one axis, rounded the way xyflow rounds a drag. */
+export function snapToGrid(value: number): number {
+  return GRID_SIZE * Math.round(value / GRID_SIZE);
+}
+
+type RawNode = Record<string, unknown>;
+type Point = { x: number; y: number };
+
+function pointOf(value: unknown): Point | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { x, y } = value as Record<string, unknown>;
+  return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y)
+    ? { x, y }
+    : null;
+}
+
+function stringOf(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Snaps the nodes a write created or moved and leaves the rest. A child snaps on the page, then goes back to relative. */
+export function snapWrittenNodes<N extends RawNode>(
+  before: readonly RawNode[],
+  after: readonly N[],
+  exempt: ReadonlySet<string> = FREEHAND_NODE_TYPES,
+): N[] {
+  const prior = new Map<string, { at: Point | null; parent?: string }>();
+  for (const node of before) {
+    const id = stringOf(node.id);
+    if (id) prior.set(id, { at: pointOf(node.position), parent: stringOf(node.parentId) });
+  }
+  const byId = new Map<string, N>();
+  for (const node of after) {
+    const id = stringOf(node.id);
+    if (id) byId.set(id, node);
+  }
+
+  const written = (node: N): boolean => {
+    const was = prior.get(String(node.id));
+    const at = pointOf(node.position);
+    const type = stringOf(node.type);
+    if (!at || (type !== undefined && exempt.has(type))) return false;
+    if (!was?.at) return true;
+    return was.at.x !== at.x || was.at.y !== at.y || was.parent !== stringOf(node.parentId);
+  };
+
+  // Parents settle first, because a child's page position rides on its parent's.
+  const settled = new Map<string, { local: Point; page: Point }>();
+  const visiting = new Set<string>();
+
+  const settle = (node: N): { local: Point; page: Point } => {
+    const id = String(node.id);
+    const done = settled.get(id);
+    if (done) return done;
+    const local = pointOf(node.position) ?? { x: 0, y: 0 };
+    const parentId = stringOf(node.parentId);
+    const parent = parentId ? byId.get(parentId) : undefined;
+    let origin: Point = { x: 0, y: 0 };
+    if (parent && !visiting.has(id)) {
+      visiting.add(id);
+      origin = settle(parent).page;
+      visiting.delete(id);
+    }
+    const page = { x: origin.x + local.x, y: origin.y + local.y };
+    const result = written(node)
+      ? {
+          local: { x: snapToGrid(page.x) - origin.x, y: snapToGrid(page.y) - origin.y },
+          page: { x: snapToGrid(page.x), y: snapToGrid(page.y) },
+        }
+      : { local, page };
+    settled.set(id, result);
+    return result;
+  };
+
+  return after.map((node) => {
+    if (!stringOf(node.id)) return node;
+    const at = pointOf(node.position);
+    const next = settle(node).local;
+    return at && (next.x !== at.x || next.y !== at.y) ? { ...node, position: next } : node;
+  });
+}

package/src/canvas/headless/icon-node.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vite-plus/test";
+import { ICON_SIZE, ICON_W, iconGeometry } from "./icon-node.js";
+
+describe("iconGeometry", () => {
+  it("centres a labelled-below mark and hands off at its own edges", () => {
+    const geo = iconGeometry({ label: "Acme" });
+    expect(geo.markX).toBe((ICON_W - ICON_SIZE) / 2);
+    expect(geo.left).toEqual({ x: geo.markX, y: ICON_SIZE / 2 });
+    expect(geo.right).toEqual({ x: geo.markX + ICON_SIZE, y: ICON_SIZE / 2 });
+    expect(geo.height).toBeGreaterThan(ICON_SIZE);
+  });
+
+  it("leaves a right-labelled mark from the box edge, level with the mark's centre", () => {
+    const geo = iconGeometry(
+      { label: "Delivery", lines: ["a", "b"], labelSide: "right", size: 60 },
+      400,
+    );
+    expect(geo.left.x).toBe(0);
+    expect(geo.right.x).toBe(400);
+    expect(geo.left.y).toBe(geo.right.y);
+    expect(geo.left.y).toBe(geo.markY + 30);
+  });
+});

package/src/canvas/headless/icon-node.ts

@@ -0,0 +1,66 @@
+// An icon node's geometry from its data alone. The node, the board compiler and the sizer
+// all read it, so a curve lands on the mark, not a guess.
+
+export type IconShape = "tile" | "ring";
+export type IconLabelSide = "below" | "right";
+
+export type IconGeometryInput = {
+  size?: number;
+  labelSide?: IconLabelSide;
+  label?: string;
+  lines?: string[];
+};
+
+export type IconGeometry = {
+  size: number;
+  /** Top-left of the mark inside the node box. */
+  markX: number;
+  markY: number;
+  height: number;
+  /** Where curves arrive (left) and leave (right), in node-local px. */
+  left: { x: number; y: number };
+  right: { x: number; y: number };
+};
+
+export const ICON_SIZE = 56;
+export const ICON_W = 120;
+/** Gap between the mark and its label, either side. */
+export const ICON_LABEL_GAP = 12;
+export const ICON_LABEL_H = 22;
+export const ICON_LINE_H = 20;
+/** A right-hand label is set larger: it names an area, not a tool. */
+export const ICON_SIDE_LABEL_H = 28;
+/** Space between the port line and the first line under it. */
+export const ICON_PORT_GAP = 6;
+
+/**
+ * A label below centres the mark and hands off at its edges. A right label starts it
+ * at x 0 and leaves from the box's right edge.
+ */
+export function iconGeometry(icon: IconGeometryInput, width: number = ICON_W): IconGeometry {
+  const size = icon.size ?? ICON_SIZE;
+  const lines = icon.lines?.length ?? 0;
+  const mid = size / 2;
+  if (icon.labelSide === "right") {
+    // The label sits across the port line: name above it, lines below.
+    const top = Math.max(0, (icon.label ? ICON_SIDE_LABEL_H : 0) - mid);
+    return {
+      size,
+      markX: 0,
+      markY: top,
+      height: Math.max(top + size, top + mid + ICON_PORT_GAP + lines * ICON_LINE_H),
+      left: { x: 0, y: top + mid },
+      right: { x: Math.max(width, size), y: top + mid },
+    };
+  }
+  const markX = (Math.max(width, size) - size) / 2;
+  const text = (icon.label ? ICON_LABEL_H : 0) + lines * ICON_LINE_H;
+  return {
+    size,
+    markX,
+    markY: 0,
+    height: size + (text ? ICON_LABEL_GAP + text : 0),
+    left: { x: markX, y: mid },
+    right: { x: markX + size, y: mid },
+  };
+}

package/src/canvas/headless/index.ts

@@ -0,0 +1,9 @@
+// What a CLI or a server needs to build a board without a browser.
+
+export {
+  compilePenMark,
+  penMarkSchema,
+  placeInFrame,
+  type FramePositions,
+  type PenMark,
+} from "./pen-marks.js";

package/src/canvas/headless/linkify.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vite-plus/test";
+import { hasLink, linkify } from "./linkify.js";
+
+describe("linkify", () => {
+  it("splits a link out of a line and leaves the words around it", () => {
+    expect(linkify("OPEN: the board, https://app.example.com/1/v/b/2 then go")).toEqual([
+      { text: "OPEN: the board, " },
+      { text: "https://app.example.com/1/v/b/2", href: "https://app.example.com/1/v/b/2" },
+      { text: " then go" },
+    ]);
+  });
+
+  it("keeps sentence punctuation out of the link", () => {
+    const parts = linkify("See https://example.com/a.");
+    expect(parts[1].href).toBe("https://example.com/a");
+    expect(parts[2].text).toBe(".");
+  });
+
+  it("returns plain text as one part", () => {
+    expect(linkify("no link here")).toEqual([{ text: "no link here" }]);
+    expect(hasLink("no link here")).toBe(false);
+  });
+});

package/src/canvas/headless/linkify.ts

@@ -0,0 +1,25 @@
+/** A run of text on a board line: plain, or a link the reader can click. */
+export type LinkPart = { text: string; href?: string };
+
+const URL_RE = /https?:\/\/[^\s<>"]+/g;
+/** Sentence punctuation that follows a link without belonging to it. */
+const TRAILING = /[.,;:!?)\]'”]+$/;
+
+/** Splits a line so each http(s) link is its own part, minus the punctuation after it. */
+export function linkify(text: string): LinkPart[] {
+  const parts: LinkPart[] = [];
+  let last = 0;
+  for (const match of text.matchAll(URL_RE)) {
+    const start = match.index ?? 0;
+    const href = match[0].replace(TRAILING, "");
+    if (start > last) parts.push({ text: text.slice(last, start) });
+    parts.push({ text: href, href });
+    last = start + href.length;
+  }
+  if (last < text.length) parts.push({ text: text.slice(last) });
+  return parts;
+}
+
+export function hasLink(text: string): boolean {
+  return /https?:\/\//.test(text);
+}

package/src/canvas/headless/pen-marks.ts

@@ -0,0 +1,133 @@
+// Pen marks written as JSON, built into the same nodes the pen tool draws,
+// so a CLI can import a whole drawing in one call.
+
+import { z } from "zod";
+import { buildStrokeNode } from "../pen/geometry.js";
+import { buildShapeNode, buildTextNode } from "../pen/shapes.js";
+import { PEN_COLORS, SHAPE_KINDS, type PenNodeInput } from "../pen/types.js";
+import type { CanvasNode } from "../types.js";
+
+// =========================
+// SCHEMAS
+// =========================
+
+const colorSchema = z.enum(PEN_COLORS);
+const pointSchema = z.tuple([z.number(), z.number()]);
+
+/** One stroke past this is a scribble pasted from a file, not a drawing. */
+const MAX_POINTS = 5000;
+
+/** The frame this mark sits in: its id, with the mark's coordinates still on the page. */
+const inFrame = z.string().min(1).optional();
+
+const strokeMark = z.object({
+  kind: z.literal("stroke"),
+  id: z.string().min(1).optional(),
+  in: inFrame,
+  /** Flow coordinates: x, y, then an optional 0 to 1 pressure. Simplified on the way in. */
+  points: z
+    .array(z.tuple([z.number(), z.number()]).rest(z.number()))
+    .min(1)
+    .max(MAX_POINTS),
+  color: colorSchema.optional(),
+  size: z.number().positive().optional(),
+  tool: z.enum(["pen", "highlighter"]).optional(),
+});
+
+const textMark = z.object({
+  kind: z.literal("text"),
+  id: z.string().min(1).optional(),
+  in: inFrame,
+  /** Top-left of the first line, as [x, y]. */
+  at: pointSchema,
+  text: z.string().min(1),
+  color: colorSchema.optional(),
+  fontSize: z.number().positive().optional(),
+});
+
+const shapeMark = z.object({
+  kind: z.literal("shape"),
+  id: z.string().min(1).optional(),
+  in: inFrame,
+  shape: z.enum(SHAPE_KINDS),
+  /** [x, y, width, height]. */
+  box: z.tuple([z.number(), z.number(), z.number().nonnegative(), z.number().nonnegative()]),
+  color: colorSchema.optional(),
+  filled: z.boolean().optional(),
+  label: z.string().optional(),
+});
+
+export const penMarkSchema = z.discriminatedUnion("kind", [strokeMark, textMark, shapeMark]);
+
+export type PenMark = z.infer<typeof penMarkSchema>;
+
+// =========================
+// COMPILE
+// =========================
+
+/** Where each frame sits on the page, by id. A node inside one stores its place relative to it. */
+export type FramePositions = ReadonlyMap<string, { x: number; y: number }>;
+
+/** An unknown frame throws, so a typo in `in` stops the import instead of misplacing the mark. */
+export function placeInFrame<N extends CanvasNode>(
+  node: N,
+  frameId: string,
+  frames: FramePositions,
+  where: string,
+): N {
+  const frame = frames.get(frameId);
+  if (!frame) throw new Error(`${where}: no frame "${frameId}" to put it in`);
+  return {
+    ...node,
+    parentId: frameId,
+    extent: "parent",
+    position: { x: node.position.x - frame.x, y: node.position.y - frame.y },
+  };
+}
+
+function toNode(node: PenNodeInput<Record<string, unknown>>, id: string): CanvasNode {
+  return {
+    id,
+    type: node.type,
+    position: node.position,
+    data: node.data,
+    width: node.width,
+    height: node.height,
+  };
+}
+
+/**
+ * Builds the node for one mark. A mark with no id gets `pen-<n>` from its place in the list,
+ * so a rerun of the same file writes the same ids.
+ */
+export function compilePenMark(mark: PenMark, index: number, frames: FramePositions): CanvasNode {
+  const where = `marks[${index}]`;
+  const id = mark.id ?? `pen-${index + 1}`;
+  let node: CanvasNode;
+  if (mark.kind === "stroke") {
+    const built = buildStrokeNode(mark.points, {
+      color: mark.color,
+      size: mark.size,
+      tool: mark.tool,
+    });
+    if (!built) throw new Error(`${where}: a stroke needs at least one point`);
+    node = toNode(built, id);
+  } else if (mark.kind === "text") {
+    const [x, y] = mark.at;
+    node = toNode(
+      buildTextNode({ x, y }, { text: mark.text, color: mark.color, fontSize: mark.fontSize }),
+      id,
+    );
+  } else {
+    const [x, y, width, height] = mark.box;
+    node = toNode(
+      buildShapeNode(
+        mark.shape,
+        { x, y, width, height },
+        { color: mark.color, filled: mark.filled, label: mark.label },
+      ),
+      id,
+    );
+  }
+  return mark.in ? placeInFrame(node, mark.in, frames, where) : node;
+}