reladraw 0.20.0 → 0.22.0

package/dist/render.js

@@ -3,7 +3,7 @@ import { SourceError } from './errors.js';
 import { ICON_STROKE } from './icons.js';
 import { insideOutline, isBoxy, isRound, placePath, shapeOf, SUBPROCESS_INSET } from './outline.js';
 import { monospaceMeasurer } from './measure.js';
-import { joinedToText } from './model.js';
+import { joinedToText, outlineStated } from './model.js';
 import { DARK_THEME, THEMES, overlapFill, regionTint, textOnFill, themeColor } from './themes.js';
 import { crossingPoints, planLines, traceRoute, visibleRuns } from './lines.js';
 import { patchPadding, placeLineTexts } from './linetexts.js';
@@ -11,22 +11,21 @@ import { plain } from './text.js';
 const CORNER = 8;
 /** Turn solved geometry into a standalone SVG document. */
 export function render(layout, options = {}) {
+    return drawing(layout, options)(false);
+}
+/**
+ * The SVG as `render` gives it, and the same drawing with each thing wrapped in
+ * a group naming it and its statement's line, for a page that points at things
+ * (`--page`). Drawn once, so the two can't disagree.
+ */
+export function renderTagged(layout, options = {}) {
+    const assemble = drawing(layout, options);
+    return { svg: assemble(false), tagged: assemble(true) };
+}
+function drawing(layout, options) {
     const measurer = options.measurer ?? monospaceMeasurer();
     const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
-    // A theme passed in — the command line's `--theme` — beats the one the file
-    // names, so one source renders in either. `diagram background:` and `text:`
-    // are the author overruling a color of whichever theme that is, and a color
-    // written by hand wins over any theme, so they are folded in afterwards and
-    // everything downstream sees one theme.
-    const named = layout.diagram['theme'];
-    const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
-    const page = layout.diagram['background'];
-    const words = layout.diagram['text.color'];
-    const theme = {
-        ...base,
-        ...(page !== undefined && { background: themeColor(page, base) }),
-        ...(words !== undefined && { text: themeColor(words, base) }),
-    };
+    const theme = themeOf(layout, options);
     // Guides are shown by the viewer (`--guides`), or by a file that explains
     // its own construction (`diagram guides: show`).
     const guides = {
@@ -110,8 +109,8 @@ export function render(layout, options = {}) {
     }
     const lineSvg = new Map(lines.map((line) => [line.key, line.svg]));
     const body = sequence
-        .map((item) => lineSvg.get(item.key) ?? item.svg)
-        .filter((svg) => svg.length > 0);
+        .map((item) => ({ item, svg: lineSvg.get(item.key) ?? item.svg }))
+        .filter(({ svg }) => svg.length > 0);
     // An edge's geometry is measured rather than solved for, so the resolver sized
     // the canvas from the boxes alone. A curve out of a `top` side, or a text
     // riding above one, lands outside that — so the page grows to hold it and the
@@ -135,8 +134,11 @@ export function render(layout, options = {}) {
                 markers.set(markerId(mark, color, free), [mark, color, free]);
         }
     }
-    const svg = [
+    return (tagged) => ownIds([
         `<svg xmlns="http://www.w3.org/2000/svg" width="${canvas.width}" height="${canvas.height}" viewBox="${canvas.x} ${canvas.y} ${canvas.width} ${canvas.height}" font-family=${quote(measurer.fontFamily)} font-size="${fontSize}px">`,
+        // `diagram title:` — what a browser shows on the tab when the SVG is opened
+        // on its own, and what a screen reader announces.
+        ...(layout.diagram['title'] === undefined ? [] : [`  <title>${escapeXml(layout.diagram['title'])}</title>`]),
         '  <defs>',
         ...[...markers.values()].map(([mark, color, free]) => markMarker(mark, color, theme.background, free)),
         // Each mask covers the whole page, in page units: the default region is the
@@ -150,11 +152,51 @@ export function render(layout, options = {}) {
         ].join('\n')),
         '  </defs>',
         `  <rect x="${canvas.x}" y="${canvas.y}" width="${canvas.width}" height="${canvas.height}" fill="${theme.background}"/>`,
-        ...body,
+        ...body.map(({ item, svg }) => (tagged ? tag(layout, item, svg) : svg)),
         '</svg>',
         '',
-    ].join('\n');
-    return ownIds(svg);
+    ].join('\n'));
+}
+/**
+ * The colors a drawing is made in. A theme passed in — the command line's
+ * `--theme` — beats the one the file names, so one source renders in either.
+ * `diagram background:` and `text:` are the author overruling a color of
+ * whichever theme that is, and a color written by hand wins over any theme, so
+ * they are folded in afterwards and everything downstream sees one theme.
+ */
+export function themeOf(layout, options = {}) {
+    const named = layout.diagram['theme'];
+    const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
+    const page = layout.diagram['background'];
+    const words = layout.diagram['text.color'];
+    return {
+        ...base,
+        ...(page !== undefined && { background: themeColor(page, base) }),
+        ...(words !== undefined && { text: themeColor(words, base) }),
+    };
+}
+/**
+ * `<g data-name="api" data-line="12">` round each thing drawn: what a page
+ * shows on hover, and what a finding about that line lights up.
+ */
+function tag(layout, item, svg) {
+    let name;
+    let line;
+    if (item.node) {
+        ({ name, line } = item.node);
+    }
+    else if (item.key.startsWith('edge ')) {
+        const edge = layout.edges[Number(item.key.slice('edge '.length))];
+        name = edge.name ?? `${edge.from.name} ${edge.arrow} ${edge.to.name}`;
+        line = edge.line;
+    }
+    else {
+        const mark = layout.marks.find((one) => one.name === item.key);
+        if (!mark)
+            return svg;
+        ({ name, line } = mark);
+    }
+    return `<g data-name="${escapeXml(name).replace(/"/g, '&quot;')}" data-line="${line}">\n${svg}\n</g>`;
 }
 /**
  * Gives every id in a drawing a prefix of its own, taken from a hash of the
@@ -305,7 +347,7 @@ function drawNode(node, theme, measurer, fontSize, markup, guides, inherited) {
  * cards drawn back to front, so the first, the front card, is on top.
  */
 function drawDeck(node, theme, measurer, fontSize, markup, guides, url) {
-    const outlined = node.appearance['fill'] !== undefined || node.appearance['border'] !== undefined;
+    const outlined = outlineStated(node.appearance);
     const drawn = outlined ? node : { ...node, appearance: { ...node.appearance, fill: 'none', border: 'none' } };
     const cards = node.children.filter((child) => child !== node.heading && !joinedToText(child));
     // The cards are the same thing, so each looks like the front one unless it says otherwise.
@@ -364,8 +406,29 @@ function borderSvg(node, theme) {
     if (node.body.kind !== 'shape')
         return '';
     const face = faceOf(node);
+    const d = outlinePath(node.body.outline, face.x, face.y, face.width, face.height, node.corners, node.body.look);
+    const stroke = borderStroke(node.borderWidth, `<path d="${d}"/>`, `rim-${node.name.replace(/[^\w.-]/g, '_')}`);
     const border = borderOf(node.appearance, theme, theme.containerStroke);
-    return `  <path d="${outlinePath(node.body.outline, face.x, face.y, face.width, face.height, node.corners, node.body.look)}" fill="none" stroke="${border}"/>`;
+    return `${stroke.clip}  <path d="${d}" fill="none" stroke="${border}"${stroke.attr}/>`;
+}
+/**
+ * How a border is stroked. A thick border lies wholly inside the outline: the
+ * outline is stroked twice as wide and clipped to itself, so only the inner
+ * half shows, and its outer edge is the outline exactly, along every side and
+ * at every corner and point of every shape, where a line ends and a gap is
+ * measured from (design.org 9.1). A normal border straddles the outline, as
+ * every box's always did, and writes nothing here. `detail` is for the lines
+ * drawn inside a shape, such as a cylinder's rim, which are as wide as the
+ * border and straddle where they run.
+ */
+function borderStroke(width, outline, id) {
+    if (width === undefined)
+        return { clip: '', attr: '', detail: '' };
+    return {
+        clip: `  <clipPath id="${id}">${outline}</clipPath>\n`,
+        attr: ` stroke-width="${round(width * 2)}" clip-path="url(#${id})"`,
+        detail: ` stroke-width="${round(width)}" clip-path="url(#${id})"`,
+    };
 }
 /** What a node draws of its own, without its children, which are drawn as items of their own. */
 function nodeSvg(node, theme, measurer, fontSize, markup) {
@@ -431,18 +494,22 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
     // and the fill, drawn without a stroke, still shows behind the title's inner
     // half.
     const onBorder = node.lines.length > 0 && node.textAttrs['place']?.startsWith('on ') === true;
+    const d = outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look);
+    const stroke = borderStroke(node.borderWidth, `<path d="${d}"/>`, `border-${node.name.replace(/[^\w.-]/g, '_')}`);
+    if (stroke.clip)
+        parts.push(stroke.clip.trimEnd());
     if (onBorder) {
         const id = `title-${node.name.replace(/[^\w.-]/g, '_')}`;
         const room = PAD / 2;
         const hole = node.textBox;
         const grown = { x: face.x - PAD, y: face.y - PAD, w: face.width + PAD * 2, h: face.height + PAD * 2 };
-        parts.push(`  <mask id="${id}" maskUnits="userSpaceOnUse" x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}">`, `    <rect x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}" fill="white"/>`, `    <rect x="${round(node.x + hole.x - room)}" y="${round(node.y + hole.y)}" width="${round(hole.width + room * 2)}" height="${round(hole.height)}" fill="black"/>`, '  </mask>', `  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="${fill}" stroke="none"/>`, `  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="none" stroke="${border}" mask="url(#${id})"/>`);
+        parts.push(`  <mask id="${id}" maskUnits="userSpaceOnUse" x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}">`, `    <rect x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}" fill="white"/>`, `    <rect x="${round(node.x + hole.x - room)}" y="${round(node.y + hole.y)}" width="${round(hole.width + room * 2)}" height="${round(hole.height)}" fill="black"/>`, '  </mask>', `  <path d="${d}" fill="${fill}" stroke="none"/>`, `  <path d="${d}" fill="none" stroke="${border}"${stroke.attr} mask="url(#${id})"/>`);
     }
     else {
-        parts.push(`  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="${fill}" stroke="${border}"/>`);
+        parts.push(`  <path d="${d}" fill="${fill}" stroke="${border}"${stroke.attr}/>`);
     }
     for (const extra of outlineDetail(outline, face.x, face.y, face.width, face.height, look)) {
-        parts.push(`  <path d="${extra}" fill="none" stroke="${border}"/>`);
+        parts.push(`  <path d="${extra}" fill="none" stroke="${border}"${stroke.detail}/>`);
     }
     // A leaf's text defaults to the middle of its box, a container's to the top
     // left of the band; both then read `at` for where it really goes. Where the
@@ -493,6 +560,11 @@ function markSvg(mark, theme, guides, markup, fontSize) {
         ? `d="M${round(mark.x)} ${round(mark.y)}L${round(mark.x + mark.width)} ${round(mark.y + mark.height)}"`
         : `x="${round(mark.x)}" y="${round(mark.y)}" width="${round(mark.width)}" height="${round(mark.height)}" rx="4"`;
     const shape = flat ? 'path' : 'rect';
+    // A thick border lies inside the region's stated edge, as a box's does; one
+    // drawn as a line has no inside, so it is only wider.
+    const edge = flat
+        ? { clip: '', attr: mark.borderWidth === undefined ? '' : ` stroke-width="${round(mark.borderWidth)}"` }
+        : borderStroke(mark.borderWidth, `<rect ${box}/>`, `edge-${mark.name.replace(/[^\w.-]/g, '_')}`);
     // A text on the border breaks it, as a title on a box's border does.
     const hole = mark.text && mark.text.textAttrs['place']?.startsWith('on ') ? mark.text.box : undefined;
     const id = `region-${mark.name.replace(/[^\w.-]/g, '_')}`;
@@ -506,13 +578,13 @@ function markSvg(mark, theme, guides, markup, fontSize) {
     if (mark.guide) {
         const fill = color(said('fill')) ?? 'none';
         const border = color(said('border')) ?? guides.color;
-        return `${masked}  <${shape} ${box} fill="${fill}" stroke="${border}" stroke-dasharray="${GUIDE_DASH}"${mask}/>${label}`;
+        return `${edge.clip}${masked}  <${shape} ${box} fill="${fill}" stroke="${border}"${edge.attr} stroke-dasharray="${GUIDE_DASH}"${mask}/>${label}`;
     }
     const fill = regionFill(mark, theme);
     const border = color(said('border'));
     const opacity = fill.color === 'none' || fill.opacity >= 1 ? '' : ` fill-opacity="${round(fill.opacity)}"`;
-    return (`${masked}  <${shape} ${box} fill="${fill.color}"${opacity}` +
-        ` stroke="${border ?? theme.primary.color}"${border === undefined ? ' stroke-opacity="0.5"' : ''} stroke-width="1"${mask}/>${label}`);
+    return (`${edge.clip}${masked}  <${shape} ${box} fill="${fill.color}"${opacity}` +
+        ` stroke="${border ?? theme.primary.color}"${border === undefined ? ' stroke-opacity="0.5"' : ''}${edge.attr || ' stroke-width="1"'}${mask}/>${label}`);
 }
 /**
  * A region's fill (design.org 8.3): what it states, or the theme's tint, at

package/dist/resolve.d.ts

@@ -26,3 +26,17 @@ export interface ResolveOptions {
  * sits on is ever decided here, because the author wrote it down.
  */
 export declare function resolve(doc: Document, options?: ResolveOptions): Layout;
+/**
+ * How a node's corners are drawn. A value is checked wherever it came from — a
+ * style's `corners: sharpp` is as much a typo as a node's — but a circle refuses
+ * `corners:` only when the node itself says it, since a circle has none. From a
+ * style or a default it lands on the outlines that have corners, the way a
+ * line's `corners: rounded` from a style lands only on lines with corners. A
+ * node drawn as a picture or with no body has no outline; `checkAttrs` has
+ * already refused the word written on one, and a style's is unused.
+ */
+/**
+ * A border's thickness in pixels: `thin`, `normal`, `thick`, a multiple of
+ * normal, or `px`, read as a line's is (design.org 3.8).
+ */
+export declare function borderWidthOf(what: string, value: string | undefined, line: number): number;

package/dist/resolve.js

@@ -1,12 +1,12 @@
 import { TEXT_GAP } from './linetexts.js';
 import { POINT_KEYS, REGION_KEYS, ALL_ATTR_KEYS, ATTR_KEYS, MARKS, COLOR_KEYS, COLOR_PARTS, CHILD_ALIGNMENTS, GATHER_PLACES, CONTENT_WIDTHS, SIZE_KEY_NAMES, LINE_VALUES, NODE_CORNERS, PADDING_SIDES, describePlacement, nameTarget, partWordHint, } from './ast.js';
-import { DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, ICON_GAP, ICON_LINES, LINE_WIDTH, PAD, THICKNESS, fontSizeFor, widestLine, } from './constants.js';
+import { DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, ICON_GAP, ICON_LINES, LINE_WIDTH, PAD, THICKNESS, BORDER_THICKNESS, BORDER_WIDTH, fontSizeFor, widestLine, } from './constants.js';
 import { SourceError } from './errors.js';
 import { bodyFor, pastedIcon } from './icons.js';
 import { monospaceMeasurer } from './measure.js';
 import { isBoxy, middleOf, sizeFor, SUBPROCESS_INSET } from './outline.js';
 import { markupStyles, parseMarkup, plain, splitRuns, wrapLine } from './text.js';
-import { joinedToText } from './model.js';
+import { joinedToText, outlineStated } from './model.js';
 import { checkOpacity, gapPixels, Placer, regionTextAt } from './place.js';
 /**
  * What a node's own contents make of it, before anything is placed: a leaf's
@@ -31,12 +31,15 @@ function factsFor(node, measurer, fontSize) {
     const venn = vennOf(node);
     const circle = isCircle(node);
     // A deck that draws no outline of its own is its cards, with nothing round them.
-    const undrawnDeck = node.appearance['layout'] === 'deck' && node.appearance['fill'] === undefined && node.appearance['border'] === undefined;
+    const undrawnDeck = node.appearance['layout'] === 'deck' && !outlineStated(node.appearance);
+    // A thick border is drawn inside the outline, so the padding is measured
+    // from its inner edge and the box grows by the extra (design.org 9.1).
+    const extra = (node.borderWidth ?? BORDER_WIDTH) - BORDER_WIDTH;
     const padding = node.body.kind === 'none' || (undrawnDeck && node.appearance['padding'] === undefined)
         ? 0
-        : node.appearance['padding'] !== undefined
+        : (node.appearance['padding'] !== undefined
             ? gapPixels(node.appearance['padding'], `"${node.name}" padding:`, node.line)
-            : PAD;
+            : PAD) + extra;
     // `padding-right: 4`: one side's padding, over `padding:` there.
     const pad = { top: padding, right: padding, bottom: padding, left: padding };
     for (const side of PADDING_SIDES) {
@@ -46,7 +49,7 @@ function factsFor(node, measurer, fontSize) {
         if (circle) {
             throw new SourceError(`"${node.name}" padding-${side}: a circle has no sides to pad one of — use padding:`, node.line);
         }
-        pad[side] = gapPixels(written, `"${node.name}" padding-${side}:`, node.line);
+        pad[side] = gapPixels(written, `"${node.name}" padding-${side}:`, node.line) + extra;
     }
     // A subprocess's bars stand inside its sides, so its text keeps its padding clear of them.
     if (node.body.kind === 'shape' && node.body.outline === 'flow-subprocess') {
@@ -486,6 +489,7 @@ function buildMarks(named, placed, styles, texts = new Map()) {
         else if (text) {
             box = pointTextBox(at.x, at.y, text);
         }
+        const borderWidth = borderWidthOf(`region "${name}"`, appearance['border.thickness'], stmt.line);
         marks.push({
             kind: stmt.kind,
             name,
@@ -493,6 +497,7 @@ function buildMarks(named, placed, styles, texts = new Map()) {
             names,
             appearance,
             guide: stmt.guide === true,
+            ...(borderWidth !== BORDER_WIDTH ? { borderWidth } : {}),
             ...(text && box ? { text: { lines: text.lines, textAttrs: text.textAttrs, size: text.size, lineHeight: text.lineHeight, box } } : {}),
             line: stmt.line,
         });
@@ -781,6 +786,10 @@ function buildTree(statements, styles, defaults, icons) {
         // the renderer does for its colors; its own words beat both.
         const guideLook = stmt.guide ? defaults.get('guide node')?.['corners'] : undefined;
         node.corners = cornersOf(node, stmt.attrs['corners'] ?? guideLook ?? appearance['corners'], stmt.attrs['corners'] !== undefined);
+        const guideBorder = stmt.guide ? defaults.get('guide node')?.['border.thickness'] : undefined;
+        const borderWidth = borderWidthOf(`"${node.name}"`, stmt.attrs['border.thickness'] ?? guideBorder ?? appearance['border.thickness'], stmt.line);
+        if (borderWidth !== BORDER_WIDTH)
+            node.borderWidth = borderWidth;
         const cut = stmt.name.lastIndexOf('.');
         if (cut === -1) {
             roots.push(node);
@@ -1097,7 +1106,7 @@ function checkAttrs(kind, name, attrs, line) {
         // Quoted back the way it was written. A bracketed value arrives one dotted
         // key at a time, and `contents: match` is not a line anybody could look for.
         // A deck's cards are stored joined on a line break; quote them back as written.
-        const shown = key === 'cards' ? value.split('\n').map((text) => `"${text}"`).join(' ') : value;
+        const shown = key === 'cards' ? value.split('\n').map((text) => `"${text}"`).join(' ') : key === 'title' ? `"${value}"` : value;
         const wrote = written === key ? `${key}: ${shown}` : `${key}: (${written.slice(key.length + 1)}: ${shown})`;
         if (!ALL_ATTR_KEYS.includes(key)) {
             // Nothing anywhere in the language answers to this word, so the only
@@ -1144,6 +1153,23 @@ function checkAttrs(kind, name, attrs, line) {
  * node drawn as a picture or with no body has no outline; `checkAttrs` has
  * already refused the word written on one, and a style's is unused.
  */
+/**
+ * A border's thickness in pixels: `thin`, `normal`, `thick`, a multiple of
+ * normal, or `px`, read as a line's is (design.org 3.8).
+ */
+export function borderWidthOf(what, value, line) {
+    if (value === undefined)
+        return BORDER_WIDTH;
+    const named = BORDER_THICKNESS[value];
+    if (named !== undefined)
+        return named;
+    const number = /^(\d*\.?\d+)(px)?$/.exec(value);
+    if (!number || Number(number[1]) <= 0) {
+        throw new SourceError(`${what}: "border: (thickness: ${value})" — a thickness is thin, normal, thick, ` +
+            'a multiple of normal greater than zero such as `thickness: 2`, or pixels such as `thickness: 3px`', line);
+    }
+    return number[2] ? Number(number[1]) : BORDER_WIDTH * Number(number[1]);
+}
 function cornersOf(node, value, written) {
     if (node.body.kind !== 'shape' || value === undefined)
         return NODE_CORNERS[0];

package/dist/themes.d.ts

@@ -72,6 +72,7 @@ export declare function themeColor(value: string, theme: Theme): string;
  * A hand-picked fill is left alone — the theme has no say over it.
  */
 export declare function textOnFill(fill: string, theme: Theme): string | undefined;
+export declare function luminance(hex: string): number;
 /**
  * Sampled out of `examples/reference/arch.png` rather than invented,
  * so the benchmark render and the drawing it is measured against differ by

package/dist/themes.js

@@ -86,7 +86,7 @@ export function textOnFill(fill, theme) {
     const apart = (color) => Math.abs(luminance(color) - under);
     return apart(theme.text) >= apart(theme.background) ? theme.text : theme.background;
 }
-function luminance(hex) {
+export function luminance(hex) {
     const [r, g, b] = [1, 3, 5].map((at) => {
         const c = parseInt(hex.slice(at, at + 2), 16) / 255;
         return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;

package/dist/viewer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The pan and zoom shared by the page `render --page` writes and the
+ * playground, so the two look at a diagram the same way: − and +, Fit, 100%,
+ * the zoom always shown and saying "Fit" while fitted, the wheel, a pinch, a
+ * drag, a double-click, and the keys + - 0 1.
+ *
+ * It is browser code kept as a string, since it runs in a page, not here: the
+ * page writes it into its script, and the playground's build writes it into
+ * its own. Calling `panZoom(view, stage, label, buttons)` returns the controls
+ * the page and the playground need beyond it.
+ *
+ * `view` clips and takes the pointer; `stage` holds the SVG and is moved
+ * inside it; `label` shows the zoom; `buttons` holds the elements for out, in,
+ * fit and 100%, any of which may be missing.
+ */
+export declare const PAN_ZOOM: string;

package/dist/viewer.js

@@ -0,0 +1,185 @@
+/**
+ * The pan and zoom shared by the page `render --page` writes and the
+ * playground, so the two look at a diagram the same way: − and +, Fit, 100%,
+ * the zoom always shown and saying "Fit" while fitted, the wheel, a pinch, a
+ * drag, a double-click, and the keys + - 0 1.
+ *
+ * It is browser code kept as a string, since it runs in a page, not here: the
+ * page writes it into its script, and the playground's build writes it into
+ * its own. Calling `panZoom(view, stage, label, buttons)` returns the controls
+ * the page and the playground need beyond it.
+ *
+ * `view` clips and takes the pointer; `stage` holds the SVG and is moved
+ * inside it; `label` shows the zoom; `buttons` holds the elements for out, in,
+ * fit and 100%, any of which may be missing.
+ */
+export const PAN_ZOOM = String.raw `
+function panZoom(view, stage, label, buttons) {
+  var MIN = 0.05;
+  var MAX = 20;
+  var svg = null;
+  var natural = { w: 1, h: 1 };
+  // The drawing is resized rather than scaled with a transform, so the
+  // browser draws it afresh at every size and it stays sharp.
+  var at = { x: 0, y: 0, s: 1 };
+  // Until the reader pans or zooms, a change of size redraws the view the way
+  // it was asked for: as it opened, or fitted.
+  var fitted = 'open';
+
+  function apply() {
+    if (!svg) {
+      label.textContent = '';
+      return;
+    }
+    svg.setAttribute('width', natural.w * at.s);
+    svg.setAttribute('height', natural.h * at.s);
+    stage.style.transform = 'translate(' + at.x + 'px,' + at.y + 'px)';
+    // The zoom always shows. Fitted, it says so too, since 62% alone doesn't
+    // say whether that is the whole diagram or a zoom that happens to be 62%.
+    // A large diagram opens fitted; a small one opens at 100%, not fitted.
+    var isFit = fitted === 'fit' || (fitted === 'open' && at.s < 1);
+    label.innerHTML = (isFit ? '<span class="fitted">Fit</span> · ' : '') + Math.round(at.s * 100) + '%';
+  }
+
+  function size() {
+    return { w: view.clientWidth, h: view.clientHeight };
+  }
+
+  function center(s) {
+    var room = size();
+    at = { s: s, x: (room.w - natural.w * s) / 2, y: (room.h - natural.h * s) / 2 };
+    apply();
+  }
+
+  function fitScale() {
+    var room = size();
+    return Math.max(MIN, Math.min((room.w - 32) / natural.w, (room.h - 32) / natural.h));
+  }
+
+  function fit() {
+    fitted = 'fit';
+    center(fitScale());
+  }
+
+  function actual() {
+    fitted = false;
+    center(1);
+  }
+
+  // A diagram smaller than the view opens at its own size; a larger one
+  // opens fitted.
+  function open() {
+    fitted = 'open';
+    center(Math.min(1, fitScale()));
+  }
+
+  function refit() {
+    if (!svg) return;
+    if (fitted === 'fit') fit();
+    else if (fitted === 'open') open();
+    else apply();
+  }
+
+  // Zoom about a point of the view, which stays where it is on screen.
+  function zoomAt(factor, px, py) {
+    if (!svg) return;
+    var s = Math.min(MAX, Math.max(MIN, at.s * factor));
+    var k = s / at.s;
+    at = { s: s, x: px - (px - at.x) * k, y: py - (py - at.y) * k };
+    fitted = false;
+    apply();
+  }
+
+  function zoomMiddle(factor) {
+    var room = size();
+    zoomAt(factor, room.w / 2, room.h / 2);
+  }
+
+  function pan(dx, dy) {
+    at.x += dx;
+    at.y += dy;
+    fitted = false;
+    apply();
+  }
+
+  // A new drawing in the stage. The view stays as the reader left it: fitted
+  // stays fitted to the new drawing, and a zoom keeps its scale and place.
+  function show() {
+    svg = stage.querySelector('svg');
+    if (!svg) return apply();
+    var box = svg.viewBox.baseVal;
+    natural = box && box.width ? { w: box.width, h: box.height } : { w: parseFloat(svg.getAttribute('width')) || 1, h: parseFloat(svg.getAttribute('height')) || 1 };
+    refit();
+  }
+
+  if (buttons.out) buttons.out.onclick = function () { zoomMiddle(0.8); };
+  if (buttons.in) buttons.in.onclick = function () { zoomMiddle(1.25); };
+  if (buttons.fit) buttons.fit.onclick = fit;
+  if (buttons.actual) buttons.actual.onclick = actual;
+
+  view.addEventListener('wheel', function (event) {
+    event.preventDefault();
+    var rect = view.getBoundingClientRect();
+    // A pinch on a trackpad arrives as a wheel with ctrl held, in small steps.
+    var step = event.deltaMode === 1 ? event.deltaY * 16 : event.deltaY;
+    zoomAt(Math.exp(-step * (event.ctrlKey ? 0.01 : 0.0015)), event.clientX - rect.left, event.clientY - rect.top);
+  }, { passive: false });
+
+  // Dragging pans; two fingers pinch.
+  var pointers = new Map();
+  var pinch = null;
+  view.addEventListener('pointerdown', function (event) {
+    if (event.button !== 0) return;
+    if (event.target.closest('a')) return;
+    view.setPointerCapture(event.pointerId);
+    pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+    if (pointers.size === 2) {
+      var two = Array.from(pointers.values());
+      pinch = Math.hypot(two[0].x - two[1].x, two[0].y - two[1].y);
+    }
+    view.classList.add('dragging');
+  });
+  view.addEventListener('pointermove', function (event) {
+    var last = pointers.get(event.pointerId);
+    if (!last) return;
+    var now = { x: event.clientX, y: event.clientY };
+    pointers.set(event.pointerId, now);
+    if (pointers.size === 2 && pinch) {
+      var two = Array.from(pointers.values());
+      var apart = Math.hypot(two[0].x - two[1].x, two[0].y - two[1].y);
+      var rect = view.getBoundingClientRect();
+      zoomAt(apart / pinch, (two[0].x + two[1].x) / 2 - rect.left, (two[0].y + two[1].y) / 2 - rect.top);
+      pinch = apart;
+      return;
+    }
+    pan(now.x - last.x, now.y - last.y);
+  });
+  function release(event) {
+    pointers.delete(event.pointerId);
+    if (pointers.size < 2) pinch = null;
+    if (pointers.size === 0) view.classList.remove('dragging');
+  }
+  view.addEventListener('pointerup', release);
+  view.addEventListener('pointercancel', release);
+  view.addEventListener('dblclick', function (event) {
+    var rect = view.getBoundingClientRect();
+    zoomAt(event.shiftKey ? 0.5 : 2, event.clientX - rect.left, event.clientY - rect.top);
+  });
+
+  // The view's own size, not the window's: a dragged divider changes it too.
+  new ResizeObserver(refit).observe(view);
+
+  document.addEventListener('keydown', function (event) {
+    if (event.ctrlKey || event.metaKey || event.altKey) return;
+    if (event.target.closest && event.target.closest('input, textarea, select, [contenteditable]')) return;
+    if (event.key === '+' || event.key === '=') zoomMiddle(1.25);
+    else if (event.key === '-' || event.key === '_') zoomMiddle(0.8);
+    else if (event.key === '0') fit();
+    else if (event.key === '1') actual();
+    else return;
+    event.preventDefault();
+  });
+
+  return { show: show, open: open, fit: fit, pan: pan };
+}
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
+    ".claude/skills",
     "dist",
     "NOTICE",
     "SYNTAX.md"