pageship 0.1.0 → 0.2.0

package/dist/skills/pageship-diagram/references/layout.mjs

@@ -0,0 +1,310 @@
+// Lays out a graph with ELK and prints the inline SVG figure for it, in the markup of svg.md.
+// Usage: node layout.mjs < spec.json > figure.html. See computed-layout.md for the spec.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const charWidth = 8;
+const up8 = (n) => Math.ceil(n / 8) * 8;
+const round = (n) => Math.round(n);
+const escape = (text) =>
+  String(text).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll('"', "&quot;");
+
+// ELK is elkjs's single-file build, pinned to one release and checked by its hash. It comes
+// from PAGESHIP_ELK when set, such as an installed node_modules/elkjs/lib/elk.bundled.js, or
+// from a copy downloaded once into the temporary folder.
+const elk = {
+  version: "0.12.0",
+  url: "https://cdn.jsdelivr.net/npm/elkjs@0.12.0/lib/elk.bundled.js",
+  sha384: "ww57TDqx4cGknIavPm0QKO+aygLUR1BLSn2Vhbnt1XdYKWcwLyWTFKX7aZMaKIi2",
+};
+const hashOf = (bytes) => createHash("sha384").update(bytes).digest("base64");
+
+const loadElk = async () => {
+  let file = process.env.PAGESHIP_ELK && resolve(process.env.PAGESHIP_ELK);
+  if (!file) {
+    file = join(tmpdir(), "pageship-layout", `elk-${elk.version}.js`);
+    if (!existsSync(file)) {
+      let bytes;
+      try {
+        const response = await fetch(elk.url);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        bytes = Buffer.from(await response.arrayBuffer());
+      } catch (error) {
+        fail(
+          `Could not download ELK from ${elk.url} (${error.message}). Without it, draw the graph with Mermaid as mermaid.md says.`,
+        );
+      }
+      if (hashOf(bytes) !== elk.sha384)
+        fail(`The download from ${elk.url} does not match elkjs ${elk.version}.`);
+      mkdirSync(join(tmpdir(), "pageship-layout"), { recursive: true });
+      writeFileSync(file, bytes);
+    }
+  }
+  if (hashOf(readFileSync(file)) !== elk.sha384)
+    fail(`${file} does not match elkjs ${elk.version}.`);
+  return createRequire(import.meta.url)(file);
+};
+
+const fail = (message) => {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+};
+
+// A box fits 8px per character of its longest line plus 32, and 48 high plus 16 per extra line.
+const boxSize = (label) => {
+  const lines = label.split("\n");
+  return {
+    width: up8(Math.max(...lines.map((line) => line.length)) * charWidth + 32),
+    height: 48 + 16 * (lines.length - 1),
+  };
+};
+
+const toElkGraph = (spec) => ({
+  id: "root",
+  layoutOptions: {
+    "elk.algorithm": "layered",
+    "elk.direction": spec.direction === "right" ? "RIGHT" : "DOWN",
+    "elk.edgeRouting": "ORTHOGONAL",
+    "elk.layered.cycleBreaking.strategy": "MODEL_ORDER",
+    "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
+    "elk.spacing.nodeNode": "48",
+    "elk.layered.spacing.nodeNodeBetweenLayers": "64",
+    "elk.spacing.edgeNode": "24",
+    "elk.layered.spacing.edgeNodeBetweenLayers": "24",
+    "elk.spacing.edgeEdge": "16",
+    "elk.layered.spacing.edgeEdgeBetweenLayers": "16",
+    "elk.spacing.edgeLabel": "8",
+    "elk.spacing.portPort": "16",
+    "elk.padding": "[top=24,left=24,bottom=24,right=24]",
+  },
+  // One port per connector end, so each connector gets its own attach point and a busy
+  // node grows to keep them 16px apart. Connector and port ids contain a colon, which a
+  // node id can't, so they never collide.
+  children: spec.nodes.map((node) => {
+    const size = boxSize(node.label);
+    return {
+      id: node.id,
+      ...size,
+      layoutOptions: {
+        "elk.portConstraints": "FREE",
+        "elk.nodeSize.constraints": "PORTS MINIMUM_SIZE",
+        "elk.nodeSize.minimum": `(${size.width},${size.height})`,
+      },
+      ports: spec.edges.flatMap((edge, i) => [
+        ...(edge.from === node.id ? [{ id: `edge:${i}:out`, width: 0, height: 0 }] : []),
+        ...(edge.to === node.id ? [{ id: `edge:${i}:in`, width: 0, height: 0 }] : []),
+      ]),
+    };
+  }),
+  edges: spec.edges.map((edge, i) => ({
+    id: `edge:${i}`,
+    sources: [`edge:${i}:out`],
+    targets: [`edge:${i}:in`],
+    labels: edge.label
+      ? [
+          {
+            id: `edge:${i}:label`,
+            text: edge.label,
+            width: edge.label.length * charWidth,
+            height: 16,
+          },
+        ]
+      : [],
+  })),
+});
+
+// Writes a route as M, H and V commands. Each step moves along the axis it changes most,
+// so a rounding difference never becomes a slanted segment.
+const pathOf = (points) => {
+  let [x, y] = [round(points[0].x), round(points[0].y)];
+  let d = `M ${x} ${y}`;
+  for (const point of points.slice(1)) {
+    const [nx, ny] = [round(point.x), round(point.y)];
+    if (Math.abs(nx - x) >= Math.abs(ny - y)) {
+      if (nx !== x) d += ` H ${(x = nx)}`;
+    } else {
+      d += ` V ${(y = ny)}`;
+    }
+  }
+  return d;
+};
+
+// ELK reserves 8px per character for a label, but the text is narrower. Anchor the text on
+// the side that faces the nearest vertical segment of its own connector, so it sits 8px off it.
+// The label names its connector's two nodes, as the connector does, for the pointer script.
+const labelOf = (label, points, ends) => {
+  const y = label.y + label.height / 2;
+  let [anchor, x, best] = ["middle", label.x + label.width / 2, Infinity];
+  for (const [a, b] of points.slice(1).map((point, i) => [points[i], point])) {
+    if (Math.abs(a.x - b.x) > 0.5) continue;
+    if (y < Math.min(a.y, b.y) - 8 || y > Math.max(a.y, b.y) + 8) continue;
+    const right = a.x - (label.x + label.width);
+    const left = label.x - a.x;
+    if (right >= 0 && right < best) [anchor, x, best] = ["end", label.x + label.width, right];
+    if (left >= 0 && left < best) [anchor, x, best] = ["start", label.x, left];
+  }
+  return `<text class="edge-label" ${ends} x="${round(x)}" y="${round(y)}" text-anchor="${anchor}">${escape(label.text)}</text>`;
+};
+
+// Each kind's border, in the order of the look's series colours. The legend names it, so the
+// kind never shows by colour alone.
+const kindBorders = ["solid", "dashed", "dotted", "dash-dot"];
+const kindClass = (spec, node) =>
+  node.kind === undefined ? "" : ` series-${spec.kinds.indexOf(node.kind) + 1}`;
+
+const legendOf = (kinds) =>
+  kinds?.length
+    ? [
+        '  <ul class="diagram-legend">',
+        ...kinds.map(
+          (kind, i) =>
+            `    <li class="series-${i + 1}">${escape(kind)}: ${kindBorders[i]} border</li>`,
+        ),
+        "  </ul>",
+        "",
+      ].join("\n")
+    : "";
+
+const nodeOf = (slug, node, box, kind) => {
+  const lines = node.label.split("\n");
+  const x = round(box.x + box.width / 2);
+  const y = round(box.y + box.height / 2 - 8 * (lines.length - 1));
+  const text =
+    lines.length === 1
+      ? escape(node.label)
+      : lines
+          .map((line, i) => `<tspan x="${x}"${i ? ' dy="16"' : ""}>${escape(line)}</tspan>`)
+          .join("");
+  return [
+    `      <g class="node${kind}${node.accent ? " accent" : ""}" id="${slug}-${node.id}">`,
+    `        <rect x="${round(box.x)}" y="${round(box.y)}" width="${round(box.width)}" height="${round(box.height)}" rx="6" />`,
+    `        <text x="${x}" y="${y}">${text}</text>`,
+    "      </g>",
+  ].join("\n");
+};
+
+const figureOf = async (spec, ELK) => {
+  const result = await new ELK().layout(toElkGraph(spec));
+  const slug = spec.slug;
+  const [width, height] = [round(result.width), round(result.height)];
+  const edges = [];
+  const labels = [];
+  result.edges.forEach((routed, i) => {
+    const edge = spec.edges[i];
+    const points = (routed.sections ?? []).flatMap((section) => [
+      section.startPoint,
+      ...(section.bendPoints ?? []),
+      section.endPoint,
+    ]);
+    const start = edge.both ? ` marker-start="url(#${slug}-arrow)"` : "";
+    const ends = `data-from="${slug}-${edge.from}" data-to="${slug}-${edge.to}"`;
+    edges.push(
+      `      <path class="edge" ${ends} d="${pathOf(points)}"${start} marker-end="url(#${slug}-arrow)" />`,
+    );
+    for (const label of routed.labels ?? []) labels.push(`      ${labelOf(label, points, ends)}`);
+  });
+  const nodes = result.children.map((box) => {
+    const node = spec.nodes.find((candidate) => candidate.id === box.id);
+    return nodeOf(slug, node, box, kindClass(spec, node));
+  });
+  return `<figure class="diagram" id="${slug}">
+  <div class="scroll" tabindex="0" role="region" aria-label="${escape(spec.title)}">
+    <svg role="img" aria-labelledby="${slug}-title ${slug}-desc" data-layout="computed" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+      <title id="${slug}-title">${escape(spec.title)}</title>
+      <desc id="${slug}-desc">${escape(spec.description)}</desc>
+      <defs>
+        <marker id="${slug}-arrow" viewBox="0 0 10 10" refX="10" refY="5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse">
+          <path d="M0 0 L10 5 L0 10 Z" />
+        </marker>
+      </defs>
+${[...edges, ...labels, ...nodes].join("\n")}
+    </svg>
+  </div>
+${legendOf(spec.kinds)}  <figcaption>${escape(spec.caption)}</figcaption>
+</figure>
+`;
+};
+
+// Every problem with the spec, in words the author can act on.
+const problemsOf = (spec) => {
+  const problems = [];
+  const word = /^[a-z][a-z0-9-]*$/u;
+  if (typeof spec.slug !== "string" || !word.test(spec.slug)) {
+    problems.push("slug must be lowercase letters, digits and hyphens, starting with a letter");
+  }
+  for (const field of ["title", "description", "caption"]) {
+    if (typeof spec[field] !== "string" || !spec[field].trim())
+      problems.push(`${field} is missing`);
+  }
+  if (!["down", "right", undefined].includes(spec.direction)) {
+    problems.push('direction must be "down" or "right"');
+  }
+  const nodes = Array.isArray(spec.nodes) ? spec.nodes : [];
+  const edges = Array.isArray(spec.edges) ? spec.edges : [];
+  if (!nodes.length) problems.push("nodes is missing");
+  if (nodes.length > 30)
+    problems.push(`${nodes.length} nodes; the limit is 30, so split the figure by area`);
+  if (edges.length > 40)
+    problems.push(`${edges.length} edges; the limit is 40, so split the figure by area`);
+  const ids = new Set();
+  for (const [i, node] of nodes.entries()) {
+    if (typeof node.id !== "string" || !word.test(node.id)) {
+      problems.push(`node ${i + 1} needs an id of lowercase letters, digits and hyphens`);
+    } else if (ids.has(node.id)) {
+      problems.push(`node id "${node.id}" is used twice`);
+    } else if (["title", "desc", "arrow"].includes(node.id)) {
+      problems.push(`node id "${node.id}" is reserved for the figure's own elements`);
+    }
+    ids.add(node.id);
+    if (typeof node.label !== "string" || !node.label.trim())
+      problems.push(`node ${i + 1} needs a label`);
+  }
+  const kinds = spec.kinds ?? [];
+  if (!Array.isArray(kinds) || kinds.some((kind) => typeof kind !== "string" || !kind.trim())) {
+    problems.push("kinds must be a list of names");
+  } else if (kinds.length > 4) {
+    problems.push(`${kinds.length} kinds; the limit is 4`);
+  }
+  for (const [i, node] of nodes.entries()) {
+    if (node.kind !== undefined && !(Array.isArray(kinds) && kinds.includes(node.kind)))
+      problems.push(`node ${i + 1}'s kind "${node.kind}" is not one of the kinds`);
+  }
+  const accents = nodes.filter((node) => node.accent).length;
+  if (accents > 2) problems.push(`${accents} accent nodes; the limit is 2`);
+  for (const [i, edge] of edges.entries()) {
+    for (const end of ["from", "to"]) {
+      if (!ids.has(edge[end])) {
+        problems.push(
+          `edge ${i + 1} ${end === "from" ? "comes from" : "goes to"} "${edge[end]}", which is not a node`,
+        );
+      }
+    }
+    if (edge.label !== undefined) {
+      if (typeof edge.label !== "string" || !edge.label.trim())
+        problems.push(`edge ${i + 1}'s label is empty`);
+      else if (edge.label.trim().split(/\s+/u).length > 3)
+        problems.push(`edge ${i + 1}'s label has more than three words`);
+    }
+  }
+  return problems;
+};
+
+let spec;
+try {
+  spec = JSON.parse(readFileSync(0, "utf8"));
+} catch (error) {
+  fail(`The spec is not valid JSON: ${error.message}`);
+}
+const problems = problemsOf(spec);
+if (problems.length) fail(`The spec needs changes:\n${problems.map((p) => `- ${p}`).join("\n")}`);
+const figure = await figureOf(spec, await loadElk());
+const width = Number(figure.match(/ width="(\d+)"/u)[1]);
+if (width > 1088) {
+  process.stderr.write(
+    `Note: the figure is ${width}px wide; the limit is 1088px. Try the other direction, or split the figure.\n`,
+  );
+}
+process.stdout.write(figure);

package/dist/skills/pageship-diagram/references/mermaid.md

@@ -0,0 +1,89 @@
+# Mermaid
+
+Mermaid lays out a large graph in the reader's browser. Use only these diagram types: `flowchart`, `stateDiagram-v2`, `sequenceDiagram` and `erDiagram`.
+
+## Markup
+
+Load Mermaid with the exact tag in [the file rules](../../pageship-docs/references/file.md#trusted-libraries-only), once per file, at the end of the `<body>`, then run it:
+
+```html
+<figure class="diagram" id="systems">
+  <div class="scroll" tabindex="0" role="region" aria-label="Map of help desk integrations">
+    <pre class="mermaid">
+flowchart LR
+  accTitle: Help desk integrations
+  accDescr: Web chat, email and the phone system create tickets in the help desk. The help desk sends closed tickets to the survey tool.
+  chat["Web chat"] -->|"chats become tickets"| desk["Help desk"]
+  desk -->|"closed tickets"| survey["Survey tool"]
+  classDef accent stroke-width:3px
+  class desk accent
+  class chat series-1
+  class survey series-2
+    </pre>
+  </div>
+  <ul class="diagram-legend">
+    <li class="series-1">Channels: solid border</li>
+    <li class="series-2">Tools: dashed border</li>
+  </ul>
+  <figcaption>Every channel customers use ends up as a ticket in the help desk.</figcaption>
+</figure>
+<details>
+  <summary>The integrations as a table</summary>
+  <table>
+    ...one row per connection: from, to, what flows...
+  </table>
+</details>
+
+<!-- the pointer script, then the Mermaid tag from the file rules -->
+<script>
+  // Mermaid reads colours as rgb(), so each look variable, which must be opaque, passes
+  // through a canvas pixel.
+  const look = (name) => {
+    const probe = document.createElement("i");
+    probe.style.color = `var(${name})`;
+    document.body.append(probe);
+    const pixel = document.createElement("canvas").getContext("2d");
+    pixel.fillStyle = getComputedStyle(probe).color;
+    pixel.fillRect(0, 0, 1, 1);
+    probe.remove();
+    const [r, g, b] = pixel.getImageData(0, 0, 1, 1).data;
+    return `rgb(${r}, ${g}, ${b})`;
+  };
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme: "base",
+    themeVariables: {
+      darkMode: matchMedia("(prefers-color-scheme: dark)").matches,
+      background: look("--bg"),
+      primaryColor: look("--surface"),
+      primaryTextColor: look("--fg"),
+      primaryBorderColor: look("--fg"),
+      textColor: look("--fg"),
+      lineColor: look("--muted"),
+      signalColor: look("--muted"),
+      edgeLabelBackground: look("--bg"),
+    },
+    fontFamily: "system-ui, sans-serif",
+    flowchart: { useMaxWidth: false },
+    state: { useMaxWidth: false },
+    sequence: { useMaxWidth: false },
+    er: { useMaxWidth: false },
+  });
+  // Gives the drawn nodes their pointer states.
+  mermaid.run({ querySelector: ".mermaid" }).then(preparePointer);
+</script>
+```
+
+## Rules
+
+- **Accessible title and description.** The first lines of the definition are `accTitle:` and `accDescr:`, which become the SVG's `<title>` and `<desc>`.
+- **The same facts as a table.** After the figure, give every connection as a table by `pageship-table`, one row each, with what flows in the source's words. Put it inside `<details>` when the connectors carry labels, and `<details open>` when they don't.
+- **Its own size.** Keep `useMaxWidth: false`. Never scale the graph down to fit.
+- **Mermaid's own routing.** Keep Mermaid's default curved lines.
+- **One line per pair.** When two nodes send something both ways, draw one line with arrowheads at both ends (`a <--> b`) and give both directions in the table.
+- **Labels only when they fit.** Label connectors when the graph has 12 connectors or fewer. Above that, leave every connector unlabelled and let the table say what flows.
+- **Labels and ids.** Node ids are short ASCII words. Put every node and connector label in double quotes, in the source's words, three words at most on a connector.
+- **Pointer states.** Add [the pointer style and script](../../pageship-interaction/references/pointer.md) where the markup shows. Use `flowchart` for a map whose nodes the reader follows, so hovering a node highlights its connections.
+- **Colours.** The one or two nodes the caption's claim is about take the `accent` class. A node of a [kind](../SKILL.md#colours) takes the kind's class, `series-1` to `series-4`, with a `class` line and no `classDef`. Add [the kinds and accents CSS](svg.md#kinds-and-accents) to the stylesheet; it colours both.
+- **Direction.** `LR` for wide maps, `TB` for deep ones. When lines run together or through nodes, or labels overlap, in the screenshot, change the direction, reorder the lines of the definition so linked nodes sit next to each other, or split the graph by area.

package/dist/skills/pageship-diagram/references/svg.md

@@ -0,0 +1,205 @@
+# SVG rules
+
+Hand-drawn diagrams are inline SVG that you lay out yourself, coordinate by coordinate. [check-diagram.js](check-diagram.js) checks these rules in a browser, so follow the classes and attributes below exactly.
+
+## Markup
+
+```html
+<figure class="diagram" id="path">
+  <div class="scroll" tabindex="0" role="region" aria-label="Ticket path diagram">
+    <svg
+      role="img"
+      aria-labelledby="path-title path-desc"
+      width="304"
+      height="256"
+      viewBox="0 0 304 256"
+    >
+      <title id="path-title">Path of a ticket in the escalation pilot</title>
+      <desc id="path-desc">
+        A ticket arrives in triage, is tagged billing, bug or other, and moves to its queue.
+      </desc>
+      <defs>
+        <marker
+          id="path-arrow"
+          viewBox="0 0 10 10"
+          refX="10"
+          refY="5"
+          markerUnits="userSpaceOnUse"
+          markerWidth="12"
+          markerHeight="12"
+          orient="auto-start-reverse"
+        >
+          <path d="M0 0 L10 5 L0 10 Z" />
+        </marker>
+      </defs>
+      <path
+        class="edge"
+        data-from="path-triage"
+        data-to="path-billing"
+        d="M 200 96 V 136 H 104 V 176"
+        marker-end="url(#path-arrow)"
+      />
+      <text
+        class="edge-label"
+        data-from="path-triage"
+        data-to="path-billing"
+        x="96"
+        y="156"
+        text-anchor="end"
+      >
+        billing
+      </text>
+      <g class="node accent" id="path-triage">
+        <rect x="128" y="48" width="144" height="48" rx="6" />
+        <text x="200" y="72">Triage queue</text>
+      </g>
+      <g class="node" id="path-billing">
+        <rect x="32" y="176" width="144" height="48" rx="6" />
+        <text x="104" y="200">Billing queue</text>
+      </g>
+    </svg>
+  </div>
+  <figcaption>Every ticket passes through triage before it reaches a queue.</figcaption>
+</figure>
+```
+
+- Prefix every `id` with the figure's slug (`path-title`, `path-arrow`, `path-triage`).
+- Each node is a `<g class="node">` with an `id`, holding its shape and its text. Each connector is one `<path class="edge">` with `data-from` and `data-to` naming the nodes it joins. Its label, a `<text class="edge-label">`, carries the same `data-from` and `data-to`. Containers that group nodes use `class="group"`, never `node`.
+- Put the connectors before the nodes in the markup.
+- Give the one or two elements the caption's claim is about `class="accent"`.
+- A node of a [kind](../SKILL.md#colours) adds the kind's class, such as `class="node series-2"`, and a legend after the `div class="scroll"` names every kind:
+
+  ```html
+  <ul class="diagram-legend">
+    <li class="series-1">Triage: solid border</li>
+    <li class="series-2">Queues: dashed border</li>
+  </ul>
+  ```
+
+- `width` and `height` equal the `viewBox` size. Keep the drawing 1088 wide at most, and 720 or less when the content allows it.
+
+Style the figure in the document's `<style>`. Set no colours in the SVG markup.
+
+```css
+.diagram svg {
+  display: block;
+  font:
+    14px system-ui,
+    sans-serif;
+}
+.diagram .node rect {
+  fill: var(--surface);
+  stroke: var(--fg);
+  stroke-width: 1.5;
+}
+.diagram text {
+  fill: var(--fg);
+  dominant-baseline: central;
+}
+.diagram .node text {
+  text-anchor: middle;
+}
+.diagram .edge-label {
+  fill: var(--muted);
+}
+.diagram .edge {
+  fill: none;
+  stroke: var(--muted);
+  stroke-width: 1.5;
+}
+.diagram marker path {
+  fill: var(--muted);
+}
+@media print {
+  .diagram svg {
+    max-width: 100%;
+    height: auto;
+  }
+}
+```
+
+Text outside a node sets its own `text-anchor` attribute. A label beside a vertical line uses `start` or `end`, so it grows away from the line.
+
+### Kinds and accents
+
+Add this after it, for hand-drawn, computed and Mermaid figures alike. `!important` wins over Mermaid's own styles.
+
+```css
+.diagram .series-1 {
+  --kind: var(--series-1);
+}
+.diagram .series-2 {
+  --kind: var(--series-2);
+  --dash: 6 4;
+}
+.diagram .series-3 {
+  --kind: var(--series-3);
+  --dash: 2 3;
+}
+.diagram .series-4 {
+  --kind: var(--series-4);
+  --dash: 12 4 2 4;
+}
+.diagram .node:is(.series-1, .series-2, .series-3, .series-4) > :is(rect, polygon, circle, path) {
+  stroke: var(--kind) !important;
+  stroke-width: 2px !important;
+  stroke-dasharray: var(--dash, none) !important;
+}
+.diagram .node.accent > :is(rect, polygon, circle, path),
+.diagram .edge.accent {
+  stroke: var(--accent) !important;
+  stroke-width: 3px !important;
+}
+.diagram-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 1.25rem;
+  margin: 0.5rem 0 0;
+  padding: 0;
+  list-style: none;
+}
+.diagram-legend li::before {
+  content: "";
+  display: inline-block;
+  width: 0.75rem;
+  height: 0.75rem;
+  margin-right: 0.5rem;
+  background: var(--kind);
+}
+```
+
+## Plan the layout
+
+Before writing the SVG, write the plan in your working notes, not in the file:
+
+1. **Grid.** Put nodes in rows and columns. A flowchart runs top to bottom, so it fits a phone. Nodes of the same rank share a row. Every coordinate and size is a multiple of 8.
+2. **Boxes.** For 14px text, a box is at least 8px per character of its longest line plus 32, and 48 high for one line, 16 more per extra line (`<tspan x=".." dy="16">`). Keep 48px or more between boxes, so connectors and labels have room.
+3. **Connectors.** List each connector's points, from the source box edge to the target box edge, turning only at right angles.
+4. **Labels.** Give each label its box: about 8px per character wide and 16 high, beside its segment.
+5. **Arithmetic.** Check each connector rule below against the numbers.
+
+## Connector rules
+
+1. **Right angles.** A connector is one path of horizontal and vertical segments, written with `M`, `H` and `V`.
+2. **Own attach point.** A connector starts on its source box's edge and ends with its arrowhead on the target's edge. Two connectors on the same edge sit at least 16px apart and 12px from a corner. Connectors never merge into one line.
+3. **Around boxes.** A connector never passes through or behind a box that isn't one of its two ends. Route it around, 16px or more clear of the box.
+4. **No overlap.** No two connectors share a segment. Parallel segments stay at least 12px apart along their whole length.
+5. **Labels beside their line.** A connector label sits beside the middle of its own segment, 6 to 12px from it, never on it, and at least 6px from every other line, label and box. Keep labels to the source's words, three words at most.
+6. **Few crossings.** Order the nodes so connectors don't cross. When one crossing is left, it meets at a right angle, away from any bend, label or arrowhead.
+
+Line style carries meaning only with a legend: say what a dashed line means in a line of text under the figure.
+
+## Timelines
+
+A timeline places events along one time axis, and the distance between two events shows how far apart they were.
+
+- **One linear scale.** Pick a scale, such as 40px per hour or 12px per day, and place each event at `x = start + (time − first time) × scale`. Never space events evenly when the times aren't.
+- **A labelled axis.** Draw ticks at a regular interval, such as every hour or every week, and label them with dates or times in the source's time zone. Name the time zone in the axis label when the source gives one.
+- **Breaks only in empty time.** When a long stretch with no events would squeeze the rest, cut it out of the axis. Cut only time that holds no events. Mark the cut on the axis with a visible gap and two short parallel strokes, and label it with the time it removes, such as "20 days not shown". Both sides of the break keep the same scale.
+- **A detail timeline for a dense cluster.** When events crowd into a short span, draw a second timeline below with a finer scale, label it as a close-up of that span ("3 Aug, 09:00 to 17:00"), and mark the span on the main axis. Never give two parts of one axis different scales.
+- **Spans as bars.** Something that lasted from one time to another, such as an outage, is a bar from its start to its end on the same scale.
+- **The source's precision.** An event the source dates only to the day sits on that day's tick and its label gives only the date. A time the source gives as approximate is labelled "about".
+- **Events take pointer states.** The timeline's `<svg>` carries `data-layout="timeline"`. Each event's point is a `<g class="node" id="…">` holding a `<title>` with the event's time and label, the point's shape, such as a `<circle>`, and then `<circle class="hit" r="12">` at the same centre, so a finger can tap it. Its label and leader line sit outside the node. [The pointer script](../../pageship-interaction/references/pointer.md) makes each event focusable and shows its title as the tooltip.
+- **Readable labels.** Each event label sits above or below the axis, joined to its point by a short vertical leader line that stops 6px short of the label. Alternate above and below, or move labels to more rows, until no two labels overlap. No line, leader or tick crosses or touches any text, tick labels included: move a tick label, or leave out a tick, that would collide with an event.
+
+Draw the axis, ticks and leader lines as `<line>` elements without the `edge` class.

package/dist/skills/pageship-docs/NOTICES.md

@@ -0,0 +1,35 @@
+# Notices
+
+The Pageship authoring skills (`pageship-docs` and the `pageship-*` kind and pattern skills) are written in our own words. We learned from the skills below and credit each one with its licence. No text or code from them is copied into these skills. If a later change copies or adapts any of their wording or code, that change must add the full licence text for that source here.
+
+| Skill                | Author            | Licence    | Copyright notice                                                                 | Source                                                                |
+| -------------------- | ----------------- | ---------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| effective-html       | plannotator       | MIT        | Copyright (c) 2026 plannotator                                                   | https://github.com/plannotator/effective-html                         |
+| visual-explainer     | Nico Bailon       | MIT        | Copyright (c) 2025 Nico Bailon                                                   | https://github.com/nicobailon/visual-explainer                        |
+| diagram-design       | Cathryn Lavery    | MIT        | Copyright (c) 2025 Cathryn Lavery                                                | https://github.com/cathrynlavery/diagram-design                       |
+| frontend-design      | Anthropic         | Apache-2.0 | The licence file carries no copyright line and the repository has no NOTICE file | https://github.com/anthropics/skills/tree/main/skills/frontend-design |
+| Taste Skill stack    | Leonxlnx          | MIT        | Copyright (c) 2026 Leonxlnx                                                      | https://github.com/Leonxlnx/taste-skill                               |
+| html-ppt             | lewis (lewislulu) | MIT        | Copyright (c) 2026 lewis                                                         | https://github.com/lewislulu/html-ppt-skill                           |
+| Matt Pocock's skills | Matt Pocock       | MIT        | Copyright (c) 2026 Matt Pocock                                                   | https://github.com/mattpocock/skills                                  |
+
+Licence texts are in each repository: `LICENSE` at the root, and for frontend-design `skills/frontend-design/LICENSE.txt`.
+
+## Versions we read
+
+- **effective-html:** commit `2ac1dfecb0f2474e75260cb6d3c9b9d6d9b5062e` (2026-09-14).
+- **visual-explainer:** commit `7163c3e10660912e0b89e1af465db9f387282b88` (2026-08-28, package 0.11.0).
+- **diagram-design:** commit `57148ac6f7cf8f2d0080f23437ab2929bca15f3e` (2026-09-29, skill v2.6).
+- **frontend-design:** anthropics/skills commit `8a1541c4a3ffa5a20a5a91de0dcf3f0bab1d1ef4` (2026-09-29). The last commit to change `skills/frontend-design` before it is `41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f` (2026-09-03).
+- **Taste Skill stack:** the copy installed on 2026-09-29. Its install records folder hashes, not a commit, so we can't name the commit we read. When we checked, the repository's latest commit was `ce26fc25c0e5e8cab638f883de62d9a86ee5e45b` (2026-09-26).
+- **html-ppt:** commit `fd1629067909ff55b36b905476de4e5f26062a1f` (2026-09-14).
+- **Matt Pocock's skills:** plugin `mattpocock-skills` 1.2.3, commit `0ab1b63a410a03d3627979a109c8695de27af954`.
+
+## What we learned from each
+
+- **effective-html.** One router that picks a narrow skill for the job, an authority order that puts the user's instructions and the project's design system first, one self-contained file with motion only where it explains, and choosing a chart from the comparison the reader needs to make, with honest scales and no facts left to tooltips. Its plan skill taught us to keep a plan's commitments recognisable and to add no timeline, progress figure or status the source doesn't support.
+- **visual-explainer.** Picking the representation from the content, a caption that states each figure's one claim, drawing the mechanism instead of naming it, labelling every arrow, and minimum type sizes. Its slide decks taught us to map every source item to a slide before writing, to add slides rather than drop content, and to check each slide for overflow.
+- **diagram-design.** Deleting nodes before drawing, the node and connector limits, right-angle connectors, labels kept off lines, one or two accent elements, accessible titles and descriptions, asking whether a table would do instead, timelines spaced to an honest scale, and motion that starts and ends on the complete figure.
+- **frontend-design.** Grounding the look in the subject, and avoiding the generated-design clichés. Our design rules defer to it for the look, ahead of the Taste Skill stack.
+- **Taste Skill stack.** Reading the brief before choosing a design direction, and treating the look as the design skill's job. Our design rules defer to it for the look when frontend-design is not installed.
+- **html-ppt.** Keyboard-first slide decks in one file, with speaker material kept off the slide, and a fixed slide canvas scaled to fit the screen.
+- **Matt Pocock's skills.** Writing skills for agents with context pointers, steps that end on a checkable condition and one source of truth for shared rules, and testing at agreed seams.