pageship 0.1.0 → 0.2.0

package/dist/skills/pageship-decision-record/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pageship-decision-record
+description: HTML decision records, as the second step of pageship-docs. For any request to record, write, regenerate, edit or move a decision, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Decision record
+
+A decision record tells the reader what was decided, what else was considered and why it lost, and what follows. A reader who stops after the first lines knows the decision and its status. A reader who goes on compares the options on the same points.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file). Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## Parts
+
+- **Decision.** What was chosen, in the source's words, with its status exactly as the source gives it, such as decided, agreed, proposed, or awaiting sign-off. Add the date, scope, duration, owner and approver when the source gives them. When the source chooses nothing yet, the decision says so.
+- **Context.** The problem that called for a decision, and the facts behind it.
+- **Options.** Every option the source considers, the chosen one included, under the source's name. For each: what it is, who raised it when the source says, what the source says for and against it, and its outcome in the source's words, such as chosen, dropped or kept in part. A rejected option carries the reason the source gives, in its words. A drawback the source lists is a reason only when the source ties it to the outcome, as in "dropped because ..." or "rejected as too costly". When the source drops or changes an option without a reason, say that it gives none, and add an open question asking why.
+- **Consequences.** What the source says follows from the decision: what changes, who must act, costs, risks and expected results. Each keeps the standing the source gives it, such as expected, a target, agreed or still to confirm. One the source says nobody has checked yet is still to confirm. One the source gives no standing is written as stated, with no label.
+- **Assumptions**, when the source states any.
+- **Open questions.**
+
+## The comparison
+
+Build one comparison of the options:
+
+- The points are the criteria the source weighs at least one option on, such as cost, effort, effect, readiness or risk, plus the outcome and the reason, named in the source's words.
+- Every option gets a value on every point: what the source says about that option on that point, in its units and wording. Where the source says nothing, write "Not stated", never a value you would have to infer, such as "low" for an option whose cost the source never gives.
+- Keep the source's order of options, and mark the chosen one in words.
+
+## Order
+
+1. **Title and decision.** An `h1` naming what was decided, then at once the decision in one or two sentences in the source's words, and a line with its status and the date, owner and scope the source gives.
+2. **Context.**
+3. **Options considered.** The comparison as a table. Anything longer than a short phrase goes under the table, in a list by option.
+4. **Consequences.** Each with its standing, and who checks and when if the source says.
+5. **Open questions.**
+6. **Sources.** As the source names them.
+
+## Hand over
+
+The structure you introduced includes the comparison points you chose.

package/dist/skills/pageship-diagram/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: pageship-diagram
+description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for diagrams in a Pageship HTML document, such as a process, a timeline, a system map or states, loaded by a pageship- kind skill before it draws a diagram.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Diagram
+
+A diagram shows the reader something a paragraph can't show at once: a path with branches, how far apart events were, what connects to what. Each diagram makes one claim, stated in its caption, and draws only what the source says.
+
+Unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## 1. Pick the diagram
+
+Write down the reader's question the figure answers, in a few words, and take the row closest to it.
+
+| The reader asks                                 | Diagram                                 | Drawn with                         |
+| ----------------------------------------------- | --------------------------------------- | ---------------------------------- |
+| What happens next, and where does it branch?    | Flowchart, top to bottom                | SVG, with a [step-through][steps]  |
+| Who hands what to whom, in what order?          | Swimlane or sequence                    | SVG, with a [step-through][steps]  |
+| When did each thing happen, and how far apart?  | [Timeline](references/svg.md#timelines) | SVG, always                        |
+| What states can it be in, and what moves it on? | State diagram                           | SVG, [computed][layout] when large |
+| What connects to what?                          | System map or dependency graph          | SVG, [computed][layout] when large |
+| What is part of what?                           | Tree or nested boxes                    | SVG                                |
+
+A process or a change over time of three to eight steps gets the [step-through][steps], unless its layout is computed.
+
+## 2. Fit the limits
+
+Count what the figure will hold against these limits:
+
+| Drawn with              | Nodes | Connectors | Accent elements | Steps |
+| ----------------------- | ----- | ---------- | --------------- | ----- |
+| SVG, laid out by hand   | 9     | 12         | 2               | 8     |
+| SVG, [computed][layout] | 30    | 40         | 2               | none  |
+| [Mermaid][mermaid]      | 30    | 40         | 2               | none  |
+
+A node is a box or other shape that stands for one thing. A timeline counts its events against a limit of 12.
+
+When the count is over, cut in this order:
+
+1. Merge nodes that always go together, and drop a connector the layout already shows. Each node stays one idea from the source, named in the source's words.
+2. Split the figure: an overview with one node per group, then one figure per group.
+3. When the reader needs the whole graph in one picture, such as a map of every system or every state a ticket can be in, and it fits the computed limits, [compute the layout][layout]. Use [Mermaid][mermaid] for it only when you can't run Node or the layout script can't get ELK. Over these limits, split by area.
+
+Content you merge or move stays in the document, in a figure or the text beside it. Leave nothing out to make the figure fit.
+
+## 3. Draw
+
+- With SVG, follow [the SVG rules](references/svg.md).
+- With a computed layout, follow [the computed layout steps][layout].
+- With Mermaid, follow [the Mermaid rules][mermaid].
+- For a process or change over time laid out by hand, add [the step-through][steps].
+
+Every figure, however drawn:
+
+- Sits in a `<figure>` with a `<figcaption>` stating its one claim in the source's words, such as "Every ticket passes through triage before it reaches a queue". The caption and the description say only what the source states: a rule you read off the graph's shape, such as "only" or "never", stays out unless the source says it.
+- Has a `<title>` naming the subject and a `<desc>` saying in one or two sentences what the figure shows.
+- Labels every node, and every connector the [Mermaid rules][mermaid] or [computed layout steps][layout] don't leave unlabelled, in the source's and the glossary's terms. A node that several paths reach says only what the source gives for every one of them.
+- Takes its colours as [Colours](#colours) says.
+- Takes [the pointer states](../pageship-interaction/references/pointer.md), so hovering, focusing or tapping a node or a timeline's event shows its detail.
+
+## Colours
+
+Colour a diagram from [the look's colour variables](../pageship-docs/references/design.md#the-looks-colour-variables) and no other colour. [The SVG stylesheet](references/svg.md#markup) sets these for hand-drawn and computed figures, and [the Mermaid script](references/mermaid.md#markup) for Mermaid:
+
+| Part                                                                     | Variable                                   |
+| ------------------------------------------------------------------------ | ------------------------------------------ |
+| Node boxes                                                               | `--surface` fill, `--fg` border            |
+| Text                                                                     | `--fg`                                     |
+| Connectors, arrowheads and connector labels                              | `--muted`                                  |
+| Accent elements: the one or two nodes or connectors the caption is about | `--accent`, with a thicker line            |
+| Node kinds                                                               | `--series-1` to `--series-4` on the border |
+
+When the source sorts the nodes into two to four named groups, such as the team or queue that handles each step, or kinds of system, give each group a kind. Number the kinds in the order they first appear: kind 1 takes `series-1` and a solid border, kind 2 `series-2` and dashed, kind 3 `series-3` and dotted, kind 4 `series-4` and dash-dot. A legend under the figure names each kind and its border, so colour never carries the kind alone. An accent node keeps its kind's border style.
+
+## Check
+
+- In a browser, run [check-diagram.js](references/check-diagram.js) in the page at 1280px and at 390px wide, for example `agent-browser eval "$(cat <this skill's folder>/references/check-diagram.js)"`. It returns a list of problems with every SVG you drew or computed. Fix each one and run it again until the list is empty. A line starting with "note" is a crossing to remove if you can.
+- For a step-through, run [its check](../pageship-interaction/references/step-through.md#check).
+- For Mermaid, look at the screenshot at both widths and confirm every node and label is readable, no two lines run together, and no line runs through a node or a label.
+- Without a browser, check your layout plan by arithmetic as [the SVG rules](references/svg.md#plan-the-layout) say.
+
+## Hand over
+
+The structure you introduced includes the form you chose for each figure and why, and any merges, splits or overviews. When a graph over the hand-drawn limits went to Mermaid instead of a computed layout, say why.
+
+[steps]: ../pageship-interaction/references/step-through.md
+[mermaid]: references/mermaid.md
+[layout]: references/computed-layout.md

package/dist/skills/pageship-diagram/references/check-diagram.js

@@ -0,0 +1,301 @@
+// Checks every hand-drawn diagram in the open page against the pageship-diagram rules.
+// Run the whole file in the page, for example with `agent-browser eval "$(cat check-diagram.js)"`
+// or Playwright's `page.evaluate`. It returns a list of problems; an empty list passes.
+// Mermaid diagrams are skipped: Mermaid lays them out itself.
+(() => {
+  const problems = [];
+  const gap = 4; // How close text may come to a connector, in screen pixels.
+
+  const rectOf = (element) => {
+    const r = element.getBoundingClientRect();
+    return { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+  };
+  const grow = (r, by) => ({
+    left: r.left - by,
+    top: r.top - by,
+    right: r.right + by,
+    bottom: r.bottom + by,
+  });
+  const overlaps = (a, b) =>
+    a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+  const contains = (outer, inner) =>
+    inner.left >= outer.left - 1 &&
+    inner.right <= outer.right + 1 &&
+    inner.top >= outer.top - 1 &&
+    inner.bottom <= outer.bottom + 1;
+  // Whether a segment passes through a rectangle, by clipping the segment to it.
+  const segmentHits = (s, r) => {
+    if (r.left >= r.right || r.top >= r.bottom) return false;
+    const dx = s.x2 - s.x1;
+    const dy = s.y2 - s.y1;
+    let from = 0;
+    let to = 1;
+    for (const [p, q] of [
+      [-dx, s.x1 - r.left],
+      [dx, r.right - s.x1],
+      [-dy, s.y1 - r.top],
+      [dy, r.bottom - s.y1],
+    ]) {
+      if (p === 0) {
+        if (q <= 0) return false;
+      } else if (p < 0) {
+        from = Math.max(from, q / p);
+      } else {
+        to = Math.min(to, q / p);
+      }
+    }
+    return from < to || (from === to && dx === 0 && dy === 0);
+  };
+
+  // The points of a path drawn with M, L, H and V, in screen pixels.
+  const segmentsOf = (path) => {
+    const d = path.getAttribute("d") ?? "";
+    if (/[^MmLlHhVvZz\d\s,.+\-eE]/u.test(d)) return null;
+    const tokens = d.match(/[MmLlHhVvZz]|[-+]?(?:\d*\.\d+|\d+\.?)(?:[eE][-+]?\d+)?/gu) ?? [];
+    const points = [];
+    let x = 0;
+    let y = 0;
+    let command = "M";
+    for (let i = 0; i < tokens.length;) {
+      if (/^[MmLlHhVvZz]$/u.test(tokens[i])) command = tokens[i++];
+      const relative = command === command.toLowerCase();
+      const upper = command.toUpperCase();
+      if (upper === "Z") {
+        if (points.length) points.push({ ...points[0] });
+        continue;
+      }
+      const read = () => Number(tokens[i++]);
+      if (upper === "M" || upper === "L") {
+        const nx = read();
+        const ny = read();
+        x = relative ? x + nx : nx;
+        y = relative ? y + ny : ny;
+        if (upper === "M" && points.length) return null; // One connector per path.
+        if (upper === "M") command = relative ? "l" : "L";
+      } else if (upper === "H") {
+        const nx = read();
+        x = relative ? x + nx : nx;
+      } else if (upper === "V") {
+        const ny = read();
+        y = relative ? y + ny : ny;
+      }
+      points.push({ x, y });
+    }
+    const matrix = path.getScreenCTM();
+    const screen = points.map((p) => new DOMPoint(p.x, p.y).matrixTransform(matrix));
+    const segments = [];
+    for (let i = 1; i < screen.length; i++) {
+      const [a, b] = [screen[i - 1], screen[i]];
+      if (Math.abs(a.x - b.x) < 0.01 && Math.abs(a.y - b.y) < 0.01) continue;
+      segments.push({ x1: a.x, y1: a.y, x2: b.x, y2: b.y });
+    }
+    return segments;
+  };
+  const horizontal = (s) => Math.abs(s.y1 - s.y2) < 0.5;
+  const vertical = (s) => Math.abs(s.x1 - s.x2) < 0.5;
+
+  document.querySelectorAll("svg").forEach((svg, index) => {
+    if (svg.closest(".mermaid") || svg.hasAttribute("aria-roledescription")) return;
+    const nodes = [...svg.querySelectorAll(".node")];
+    const edges = [...svg.querySelectorAll(".edge")];
+    const texts = [...svg.querySelectorAll("text")].filter((t) => t.getBBox().width > 0);
+    if (nodes.length === 0 && edges.length === 0 && texts.length === 0) return;
+    const name = svg.querySelector("title")?.textContent.trim() || `SVG ${index + 1}`;
+    const report = (message) => problems.push(`${name}: ${message}`);
+
+    // Accessible title and description.
+    const first = svg.firstElementChild;
+    const labelled = (svg.getAttribute("aria-labelledby") ?? "")
+      .split(/\s+/u)
+      .filter(Boolean)
+      .map((id) => document.getElementById(id));
+    if (svg.getAttribute("role") !== "img") report('the svg needs role="img"');
+    if (first?.tagName !== "title" || !first.textContent.trim()) {
+      report("the first child must be a <title> with text");
+    }
+    const desc = svg.querySelector(":scope > desc");
+    if (!desc?.textContent.trim()) report("it needs a <desc> with text");
+    if (!labelled.includes(first) || !labelled.includes(desc)) {
+      report("aria-labelledby must name the <title> and <desc> ids");
+    }
+
+    // Drawn at its own size, scrolling inside its container when wide.
+    const scale = svg.getScreenCTM()?.a ?? 1;
+    if (svg.viewBox.baseVal && svg.viewBox.baseVal.width > 0 && Math.abs(scale - 1) > 0.02) {
+      report(`it is drawn at ${Math.round(scale * 100)}% of its size; give it the viewBox size`);
+    }
+    let scroller = svg.parentElement;
+    while (scroller && !/(auto|scroll)/u.test(getComputedStyle(scroller).overflowX)) {
+      scroller = scroller.parentElement;
+    }
+    if (!scroller || scroller === document.documentElement || scroller === document.body) {
+      report('it needs a wrapper with overflow-x: auto, such as <div class="scroll">');
+    }
+
+    // Width: the page's column.
+    const width = svg.width.baseVal.value;
+    if (width > 1088) {
+      const fix =
+        svg.dataset.layout === "computed"
+          ? "try the other direction or split the figure"
+          : "redraw it narrower or split the figure";
+      report(`it is ${Math.round(width)}px wide; the limit is 1088px, so ${fix}`);
+    }
+
+    // Counts. A figure laid out by layout.mjs has the computed-layout limits, and a timeline,
+    // marked data-layout="timeline", counts its events against 12.
+    const timeline = svg.dataset.layout === "timeline";
+    const [nodeLimit, edgeLimit] =
+      svg.dataset.layout === "computed" ? [30, 40] : [timeline ? 12 : 9, 12];
+    if (nodes.length > nodeLimit) {
+      report(`${nodes.length} ${timeline ? "events" : "nodes"}; the limit is ${nodeLimit}`);
+    }
+    if (edges.length > edgeLimit) report(`${edges.length} connectors; the limit is ${edgeLimit}`);
+    const accents = svg.querySelectorAll(".accent").length;
+    if (accents > 2) report(`${accents} accent elements; the limit is 2`);
+
+    // Type size.
+    for (const text of texts) {
+      const matrix = text.getScreenCTM();
+      const size =
+        parseFloat(getComputedStyle(text).fontSize) * (matrix ? Math.hypot(matrix.a, matrix.b) : 1);
+      if (size < 12.5)
+        report(`"${text.textContent.trim()}" is ${size.toFixed(1)}px; the minimum is 13px`);
+    }
+
+    // Boxes.
+    const boxes = nodes.map((node) => ({
+      node,
+      id: node.id,
+      rect: rectOf(node.querySelector("rect, circle, ellipse, polygon, path") ?? node),
+    }));
+    for (const [i, a] of boxes.entries()) {
+      for (const b of boxes.slice(i + 1)) {
+        if (overlaps(a.rect, b.rect)) report(`nodes ${a.id || i} and ${b.id || "?"} overlap`);
+      }
+    }
+
+    // Connectors.
+    const routes = [];
+    for (const edge of edges) {
+      const label = `connector ${edge.dataset.from ?? "?"} → ${edge.dataset.to ?? "?"}`;
+      const ends = [edge.dataset.from, edge.dataset.to];
+      if (ends.some((id) => !id || !boxes.some((box) => box.id === id))) {
+        report(`${label} needs data-from and data-to naming node ids`);
+      }
+      const segments = edge.tagName === "path" ? segmentsOf(edge) : null;
+      if (!segments?.length) {
+        report(`${label} must be one path drawn with M, H and V only`);
+        continue;
+      }
+      for (const s of segments) {
+        if (!horizontal(s) && !vertical(s)) report(`${label} has a slanted segment`);
+      }
+      for (const box of boxes) {
+        if (ends.includes(box.id)) continue;
+        if (segments.some((s) => segmentHits(s, grow(box.rect, -1)))) {
+          report(`${label} passes through or behind node ${box.id}`);
+        }
+      }
+      routes.push({ label, segments });
+    }
+    let crossings = 0;
+    for (const [i, a] of routes.entries()) {
+      for (const b of routes.slice(i + 1)) {
+        for (const s of a.segments) {
+          for (const t of b.segments) {
+            const bothH = horizontal(s) && horizontal(t);
+            const bothV = vertical(s) && vertical(t);
+            if (bothH || bothV) {
+              const apart = bothH ? Math.abs(s.y1 - t.y1) : Math.abs(s.x1 - t.x1);
+              const [s1, s2] = bothH ? [s.x1, s.x2] : [s.y1, s.y2];
+              const [t1, t2] = bothH ? [t.x1, t.x2] : [t.y1, t.y2];
+              const shared =
+                Math.min(Math.max(s1, s2), Math.max(t1, t2)) -
+                Math.max(Math.min(s1, s2), Math.min(t1, t2));
+              if (apart < 12 && shared > 1) {
+                report(`${a.label} and ${b.label} run within 12px of each other`);
+              }
+            } else if ((horizontal(s) && vertical(t)) || (vertical(s) && horizontal(t))) {
+              const [h, v] = horizontal(s) ? [s, t] : [t, s];
+              const within = (value, a, b, margin) =>
+                value > Math.min(a, b) + margin && value < Math.max(a, b) - margin;
+              if (within(v.x1, h.x1, h.x2, 1) && within(h.y1, v.y1, v.y2, 1)) {
+                crossings++;
+              } else if (within(v.x1, h.x1, h.x2, -1) && within(h.y1, v.y1, v.y2, -1)) {
+                report(`${a.label} and ${b.label} meet at a bend or an end`);
+              }
+            }
+          }
+        }
+      }
+    }
+    if (crossings > 0) {
+      problems.push(
+        `${name}: note, ${crossings} connector crossing(s); reorder nodes to remove them`,
+      );
+    }
+
+    // Other straight lines, such as a timeline's axis, ticks and leader lines.
+    const lines = [];
+    for (const element of svg.querySelectorAll("line, polyline, path")) {
+      if (element.closest(".node, marker, defs, .edge") || element.matches(".edge, .edge-hit"))
+        continue;
+      let segments = null;
+      if (element.tagName === "line") {
+        const matrix = element.getScreenCTM();
+        const [a, b] = [
+          [element.x1, element.y1],
+          [element.x2, element.y2],
+        ].map(([x, y]) => new DOMPoint(x.baseVal.value, y.baseVal.value).matrixTransform(matrix));
+        segments = [{ x1: a.x, y1: a.y, x2: b.x, y2: b.y }];
+      } else if (element.tagName === "polyline") {
+        const matrix = element.getScreenCTM();
+        const points = [...element.points].map((p) =>
+          new DOMPoint(p.x, p.y).matrixTransform(matrix),
+        );
+        segments = points
+          .slice(1)
+          .map((b, i) => ({ x1: points[i].x, y1: points[i].y, x2: b.x, y2: b.y }));
+      } else {
+        segments = segmentsOf(element);
+      }
+      if (segments?.length) lines.push(segments);
+    }
+
+    // Text: clear of every line, of other text and of boxes it doesn't belong to.
+    const textRects = texts.map((text) => ({
+      text,
+      rect: rectOf(text),
+      words: text.textContent.trim(),
+      box: boxes.find((box) => box.node.contains(text)),
+    }));
+    for (const [i, t] of textRects.entries()) {
+      for (const route of routes) {
+        if (route.segments.some((s) => segmentHits(s, grow(t.rect, gap)))) {
+          report(`"${t.words}" touches ${route.label}`);
+        }
+      }
+      if (lines.some((segments) => segments.some((s) => segmentHits(s, grow(t.rect, gap))))) {
+        report(`"${t.words}" touches a line`);
+      }
+      if (
+        t.text.matches(".edge-label") &&
+        !routes.some((route) => route.segments.some((s) => segmentHits(s, grow(t.rect, 16))))
+      ) {
+        report(`"${t.words}" is a connector label more than 12px from any connector`);
+      }
+      for (const box of boxes) {
+        if (t.box === box) {
+          if (!contains(box.rect, t.rect)) report(`"${t.words}" spills out of node ${box.id}`);
+        } else if (!t.box && overlaps(t.rect, box.rect)) {
+          report(`"${t.words}" overlaps node ${box.id}`);
+        }
+      }
+      for (const u of textRects.slice(i + 1)) {
+        if (overlaps(t.rect, u.rect)) report(`"${t.words}" overlaps "${u.words}"`);
+      }
+    }
+  });
+  return problems;
+})();

package/dist/skills/pageship-diagram/references/computed-layout.md

@@ -0,0 +1,49 @@
+# Computed layout
+
+[layout.mjs](layout.mjs) runs ELK on a list of nodes and connectors while you write, and prints the figure as inline SVG in [the SVG markup](svg.md#markup). The file loads no library.
+
+## What it needs
+
+- **Node.js 18 or later.**
+- **ELK.** The script downloads elkjs 0.12.0's single-file build once into the temporary folder. To skip that, set `PAGESHIP_ELK` to the path of a copy you already have, such as a project's `node_modules/elkjs/lib/elk.bundled.js`.
+
+Without Node, or when the script says it could not download ELK, draw the graph with [Mermaid](mermaid.md) and tell the user why in the hand-over.
+
+## 1. Write the spec
+
+The spec is JSON:
+
+| Field         | Holds                                                                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `slug`        | The figure's slug, lowercase, which prefixes every `id` in it.                                                                                 |
+| `title`       | The `<title>`, naming the subject.                                                                                                             |
+| `description` | The `<desc>`, saying in one or two sentences what the figure shows.                                                                            |
+| `caption`     | The `<figcaption>`, the figure's one claim in the source's words.                                                                              |
+| `direction`   | `"down"` (the default) or `"right"`.                                                                                                           |
+| `kinds`       | The names of the node [kinds](../SKILL.md#colours), in order, when the nodes have kinds. The script prints the legend.                         |
+| `nodes`       | `{ "id", "label", "accent", "kind" }` for each node. `"\n"` in a label starts a second line. Two accents at most. `kind` names one of `kinds`. |
+| `edges`       | `{ "from", "to", "label", "both" }` for each connector. `label` and `both` are optional.                                                       |
+
+- List nodes and connectors in the order the reader follows them, starting point first. The layout keeps that order where it can, so in a cycle the start stays at the top and the connector back to it runs upwards.
+- Label each connector whose meaning the reader can't tell from its two ends, such as a state change or a branch's condition, in three words at most. When every line means the same thing, such as "sends data to", leave them unlabelled and let the table say what flows.
+- When two nodes send something both ways and neither direction carries a label, give one connector `"both": true`, which draws arrowheads at both ends. When each direction has its own label, such as two state changes, give each direction its own connector and label.
+
+## 2. Run the script
+
+Pass the spec on standard input:
+
+```sh
+node <this skill's folder>/references/layout.mjs <<'EOF'
+{ "slug": "states", "title": "...", "description": "...", "caption": "...", "nodes": [...], "edges": [...] }
+EOF
+```
+
+It prints the whole `<figure>`. Put it in the document as printed. To change the drawing, change the spec and run the script again; the coordinates come only from the script.
+
+"Note: the figure is …px wide" means it is over the column's 1088px, which check-diagram.js reports. Try the other `direction`. When both are over, split the figure by area.
+
+## 3. Finish the figure
+
+- Style it with the CSS in [the SVG rules](svg.md#markup), kinds and accents included.
+- After the figure, give every connection as a table by `pageship-table`, one row each, with what flows or what moves it on in the source's words, in `<details>` when the connectors carry labels and `<details open>` when they don't.
+- A crossing note from check-diagram.js that reordering the spec did not remove may stay.