pageship 0.1.1 → 0.2.0

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

@@ -0,0 +1,92 @@
+---
+name: pageship-explainer
+description: HTML explainers, as the second step of pageship-docs. For any request to explain how something works, or to write, regenerate, edit or move an explainer, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Explainer
+
+An explainer shows the reader how something works: the parts, what passes between them, and the rules that decide what happens next. Figures carry the explanation and short prose sits around them. A reader who looks only at the figures and their captions still learns the mechanism.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file), with steps 2 to 4 below in place of its Sort. Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## 1. Gather
+
+When the source is code or configuration, what its lines do is the source. Read the files the request points to, then any project file they call that you need to explain them.
+
+- Code you can't read is a gap: give its name and what the calling code shows about it, such as the arguments it receives and what happens after it returns, and nothing about what it does inside, whatever its name or file suggests.
+- A setting no code you read uses is only declared: say what the file sets and that the code you read doesn't use it, never what it does.
+
+## 2. Trace the mechanism
+
+Write down the reader's question in their words, and the answer in one or two sentences from the source. The answer opens the document. It holds for every case the source covers: name an exception in a clause rather than leave it out.
+
+Trace only what the answer needs. Other behaviour in the same files, such as metrics, logging or a neighbouring feature, stays out.
+
+Then write yourself a trace:
+
+- **Parts.** Each thing that holds a state or acts, such as a queue, a function, a ticket status or a team. A part with no move or rule is only a name: find in the source what moves it on and where it goes, or make the missing rule an open question.
+- **Moves.** What passes or changes between parts, and in what order.
+- **Rules.** Each condition that decides which way a move goes or what value it gets, with its numbers and where they live, such as "statuses 408, 425, 429, 500, 502, 503 and 504 are retried (`retryableStatuses`, line 9)". Keep every condition the source checks, and which one wins when two overlap, such as an error that makes the status irrelevant.
+- **Ends.** Every way the source says the process stops or settles. Say that something stops only where the source says so. A branch whose next step the source doesn't give ends at the last thing the source says, such as "the ticket is a breach", with an open question when the reader would ask what happens next.
+
+A statement that depends on something the source doesn't show, such as whether a count includes the current attempt, says so where you make it and points to the open question.
+
+A value the source computes keeps the source's form: the formula or rule, and where each input comes from. A random value stays a range. Add a worked example only when every input comes from the source, labelled as a worked example, with the arithmetic shown.
+
+Done when every part has its moves and rules or an open question for each one the source leaves out, every branch reaches an end the source gives, and each entry names where in the source it comes from.
+
+## 3. Order the concepts
+
+List every concept the reader needs: each glossary term, part, state and rule, and each name from the code or configuration the explainer will use. A word you coin, such as "allowlist" for a set the code names otherwise, is a concept too; prefer the source's name. Mark the ones the reader already knows from who the request says they are, such as "ticket" for new responders. Introduce every other concept where the text or a figure first names it, in one clause or sentence. Order the list so each concept comes after every concept its introduction uses.
+
+The answer comes first, so it introduces each concept it uses, for example "Every ticket gets a target time for its first response (the first public reply a responder sends)". When that makes the answer long, use fewer concepts in it.
+
+Plan the sections from that order:
+
+1. An overview of the whole mechanism, introducing its parts.
+2. One section per stage or rule, in the order the mechanism runs.
+3. Exceptions and limits the source gives that fit no stage.
+
+Done when every concept's first use, text inside figures included, comes at or after its introduction.
+
+## 4. Plan the figures
+
+Give each section one figure that makes one claim. Before planning the first diagram, load `pageship-diagram`.
+
+- **The claim** is one sentence about the mechanism, in the source's words, that the figure's shapes, arrows, rows or marks show and none of them contradicts, such as "A delivery is dead-lettered as soon as an attempt fails with a status that isn't retryable." A topic, such as "Retry logic", is not a claim, and neither is a list of the figure's rules. The claim is the caption. When a caption would join two statements with "and" or a semicolon, keep the one the drawing shows and move the other to the text.
+- **Only what the claim needs.** A second claim gets a second figure. A worked example's caption states what the example shows, not the rules around it.
+- **Every arrow labelled** with what moves along it or the condition that sends things that way, from the source, such as "status 429", "fewer than 8 attempts" or "customer replies". Labels, box text and captions use the glossary's terms in full, such as "first response" rather than "response" or "reply". An arrow the source gives no label for is a gap: leave it out and add an open question. Where `pageship-diagram` would leave connectors unlabelled, such as a large Mermaid graph, split the figure until every connector carries a label.
+
+The overview is always a figure, and its claim is the answer's main point. Any other section takes a list, sentence or table when [the form of each figure](../pageship-docs/references/design.md#the-form-of-each-figure) gives one.
+
+A code block shows the line a rule lives in beside the figure, never instead of it: at most one excerpt per section. It keeps the label `pageship-code-block` gives it, not a claim.
+
+Done when every figure has one claim and every arrow has a label from the source.
+
+## 5. Order of the file
+
+Headings, text and figure labels use the glossary's terms.
+
+1. **Title and answer.** An `h1` naming what the explainer covers, then the answer, with the date and author when the source gives them.
+2. **Overview.** The overview figure, after the sentences that introduce its parts.
+3. **One section per stage or rule.** Each holds at most two short paragraphs around its figure: one before it introducing what the figure adds, and one after it only for a number or exception the figure doesn't show. A section that needs more prose becomes two sections, each with its own claim and figure.
+4. **Exceptions and limits**, when there are any.
+5. **Open questions.**
+6. **Sources.** Each file, with line numbers for code, and each document the explainer draws on, as the source names them.
+
+Done when every part, move, rule and end of the trace is in a figure or the text beside it.
+
+## Check
+
+Read the file from the top against your concept list, your trace and each figure's claim, and fix what breaks a rule above. The answer still holds against each section: a condition, exception or open question that changes it, such as a check that runs on one branch only, is in the answer too, or the answer says less.
+
+Then get a fresh reading. Your own reading follows your trace, so it passes the sentences you meant to write. Start a subagent that has seen neither this conversation nor your trace, and give it only this task: "Read-only. Read [file] beside [each source file] and the Claims section of [the path of `pageship-docs/references/check.md`]. Quote every sentence, caption, label and tooltip that claims more than the source's words state, each with the source line it goes past. Then compare each figure's drawing with its caption and the source: quote every caption the drawing doesn't show, such as an arrow that starts at a part the source doesn't give that move, and every caption that makes two claims." Wait for its answer before you fix anything or hand over. Fix each quote it returns, or keep it and say in the hand-over why the source states it. Without subagents, read the file once more from the source's side: for each sentence, find the source line before you read the next, then compare each figure's drawing with its caption.
+
+Done when every quote is fixed or its reason is in the hand-over.
+
+## Hand over
+
+The structure you introduced includes the sections and their order, each figure's form and why, and any worked example. Also list the behaviour you left out as outside the question.

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

@@ -0,0 +1,115 @@
+---
+name: pageship-interaction
+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 controls in a Pageship HTML document, such as stepping through stages, tracing a path, tabs, filters, revealing detail and pointer states on charts and diagrams, loaded by a pageship- kind skill before it adds any control.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Interaction
+
+A control lets the reader ask the document a question and see the answer: what comes after this stage, which items are mine, what sits behind this summary. The document reads in full without it.
+
+Unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill). Named for just a control, the file holds the control and the content it works on.
+
+## 1. Name the reader's question
+
+For each control you plan, write down the question it answers in the reader's words, such as "Which follow-ups are mine?", and take its pattern from this table.
+
+| The reader asks                                   | Pattern                           |
+| ------------------------------------------------- | --------------------------------- |
+| What comes next, and in what order?               | [Step-through](#step-through)     |
+| How does something get from one place to another? | [Path trace](#path-trace)         |
+| Which items match what I care about?              | [Filter](#filter)                 |
+| Show me one of several parallel versions          | [Tabs](#tabs)                     |
+| What is behind this line?                         | [Reveal detail](#reveal-detail)   |
+| What exactly is this mark, and what links here?   | [Pointer states](#pointer-states) |
+
+Every chart and every diagram with nodes takes [pointer states](#pointer-states). For the other patterns, add no control when:
+
+- the reader compares the items, such as Q2 against Q3: show them side by side in a table, because tabs or a toggle would hide one side;
+- the content fits on one screen and reads well in order;
+- a list is short enough to scan, about ten items or fewer;
+- the answer is one value;
+- the control would only decorate: carousels, a second view of the same data the reader didn't ask for.
+
+When the user asks for a control this list rules out, add it, keep everything visible as step 2 says, and say in your hand-over what the control hides.
+
+## 2. Build each control on complete content
+
+Write the full content in the HTML first, then add the controls with script on top of it. Every pattern keeps these three states complete:
+
+- **Before the reader touches anything**, every item shows, with every number, name, date, owner and decision the source gives for it. A control may hold back only the sentences that explain them.
+- **In print**, every step, panel, item and detail shows, in reading order, and the controls are hidden. Hide anything with classes that apply only under `@media screen`, so the print stylesheet never has to undo them. When a name doubles as a button, such as a stage name in the overview, print it as plain text instead of hiding it.
+- **Without script**, the page reads as a plain document with everything in it. Script creates or reveals the controls themselves, so a reader without script never sees a button that does nothing.
+
+Then build each control by its pattern below and the rules under [Controls](#controls).
+
+## Check
+
+- Before any input, take a screenshot and confirm that every item, and every number, name and date the source gives for it, is on screen.
+- Tab through the page. Every control and each chart and diagram takes focus in reading order. Tabs, and the marks or nodes of a figure, also move with the arrow keys.
+- Use each control that selects or toggles, and confirm its state changed in its attribute and on screen.
+- Emulate print media and confirm every step, panel, item and detail shows.
+- Without a browser, read the script and confirm every control is a `button`, link, `summary` or labelled input with the state its pattern names.
+
+## Patterns
+
+### Step-through
+
+For a sequence of three to eight stages the reader follows one at a time.
+
+- All stages are an ordered list in the HTML, each with its number, its name and its essential values. Every stage shows on load and in print; stepping marks one stage as current and dims the later ones.
+- The current stage carries `aria-current="step"` and a mark that is not colour alone, such as weight and a border.
+- Previous and Next buttons move one stage, and Next after the last stage shows every stage again. A "Show all steps" button returns to every stage at once. A status line beside them, such as "Step 2 of 5: Triage", has `aria-live="polite"`.
+- The URL fragment records the current stage, and the page opens on the stage it names.
+- Left and Right arrow keys step while focus is on the step-through's buttons. Nothing advances by itself; for a timed sequence, see `pageship-motion`.
+- Copy [the step-through markup, style and script](references/step-through.md) unchanged.
+
+### Path trace
+
+A step-through over a diagram, for something that travels: a ticket through queues, a request through services. Draw the diagram as inline SVG by `pageship-diagram`, with every node keeping its text label at all times, and build the step-through around it as [the step-through reference](references/step-through.md) shows. The same current stage drives the list and the diagram: the current node and the connector into it take a thicker stroke.
+
+### Filter
+
+For a list or table the reader narrows to what concerns them.
+
+- Every item shows on load, with a line such as "Showing all 14 follow-ups".
+- Use one toggle button per value, with `aria-pressed`, and an "All" button that resets them. Group the buttons by field, such as owner and status, each group with a visible label.
+- After each change, update the line, such as "Showing 4 of 14: Priya", with `aria-live="polite"`. When nothing matches, say so in place of the empty list.
+- Totals and summary figures stay computed on the full set. A figure that follows the filter says so in its label.
+
+### Tabs
+
+For parallel versions of the same content that the reader reads one at a time, such as the same steps for two platforms.
+
+- Follow the ARIA tabs pattern: a `role="tablist"` of `button` elements with `role="tab"` and `aria-selected`, each controlling a `role="tabpanel"`. Left and Right arrows move between tabs, and only the selected tab is in the Tab order.
+- Each panel starts with its own heading, so print and the no-script page read as plain sections.
+
+### Reveal detail
+
+For supporting detail behind a summary line.
+
+- Use `details` and `summary`.
+- The summary line holds the essential value, such as "Finance review: 1 day 4 h median wait". The detail holds the supporting text only.
+
+### Pointer states
+
+For chart marks, diagram nodes and connectors, so the reader can point at one for its detail.
+
+- Hover, keyboard focus and a tap show one state: the mark, node or connector stands out by more than colour, such as a thicker outline, the other series or the unconnected parts of a diagram dim, and a tooltip shows.
+- Each chart and diagram is one tab stop. From it, the arrow keys move focus between its marks or nodes, and focus shows the same state as hover.
+- Connectors take hover and tap only. Keyboard users reach the same detail from the tooltips of the nodes at either end.
+- A tooltip may add detail the figure leaves out, such as an exact value or a node's connections, when the same detail is on the page or in the figure's table.
+- Under reduced motion, states switch without transitions.
+- For charts and diagrams, copy [the pointer style and script](references/pointer.md) unchanged.
+
+## Controls
+
+- **Real elements.** Use `button type="button"` for actions, `a href="#..."` for jumps, `summary` for revealed detail, and an `input` with a label, outside any `form`, for typed text such as a search. Click handlers go on buttons and links only, never on a `div`, `span`, list item or SVG shape; the pointer script's tap is the one exception.
+- **Keyboard.** Use no positive `tabindex`. Arrow keys work only inside the widget that owns them.
+- **Focus.** Every control keeps its `:focus-visible` outline.
+- **Active state.** A control that selects or toggles something shows its state twice: in the attribute its pattern names (`aria-current`, `aria-pressed`, `aria-selected`, or `open` on `details`) and on screen by more than colour, such as weight, a border, an underline or a word. Style the active look from the attribute, such as `[aria-pressed="true"]`.
+- **Size.** Every control is at least 24 by 24 pixels, and its label says what it does ("Next stage", not "›" alone).
+- **State.** Keep it in page variables and the URL fragment.
+- **Script.** Put the script at the end of `body`.

package/dist/skills/pageship-interaction/references/pointer.md

@@ -0,0 +1,271 @@
+# Pointer states for charts and diagrams
+
+The style and script for [pointer states](../SKILL.md#pointer-states). Copy both unchanged.
+
+## Markup
+
+The script finds its targets from the markup the chart and diagram rules already give:
+
+- **Chart.** Each data mark inside a series' `<g data-series="…">`, a bar or a point's marker, holds a `<title>` with its tooltip text. The script makes the mark reachable by the arrow keys, names it with the title, shows the title as the tooltip and dims the other series; a chart of one series dims nothing.
+- **Diagram, hand-drawn or computed.** Each `<g class="node" id="…">`, each `<path class="edge">` and each `<text class="edge-label">` with `data-from` and `data-to`. A node's `<title>`, such as a timeline event's, becomes its name. The script makes each labelled node reachable by the arrow keys and builds its tooltip from its label and connections, such as "Help desk / → Survey tool (closed tickets) / ← Web chat". Its connectors, their labels and the nodes at their other ends stay bright. A connector takes hover and tap through a wider invisible line laid over it, and its tooltip names both ends and its label.
+- **Mermaid.** The same as a diagram for a `flowchart`. Other Mermaid types get the node's label as the tooltip and no connection highlight, and a `sequenceDiagram`, which draws no nodes, gets no pointer states.
+
+## Style
+
+Add this to the document's `<style>`.
+
+```css
+.figure-tip {
+  position: absolute;
+  z-index: 10;
+  max-width: min(20rem, calc(100vw - 16px));
+  padding: 0.375rem 0.625rem;
+  border-radius: 6px;
+  font:
+    0.875rem/1.4 system-ui,
+    sans-serif;
+  white-space: pre-line;
+  color: var(--bg);
+  background: var(--fg);
+  pointer-events: none;
+}
+.diagram svg .hit {
+  fill: transparent;
+  stroke: none;
+}
+.diagram svg .edge-hit {
+  fill: none;
+  stroke: transparent;
+  stroke-width: 12px;
+  pointer-events: stroke;
+}
+@media screen {
+  .chart svg [data-tip].is-active,
+  .diagram svg .node.is-active > :is(rect, polygon, circle, path):not(.hit),
+  .diagram svg .is-linked:is(.edge, .flowchart-link) {
+    stroke: var(--fg) !important;
+    stroke-width: 3px !important;
+  }
+  .chart svg.has-active [data-series]:not(:has(.is-active)),
+  .diagram
+    svg.has-active
+    :is(.node, .edge, .edge-label, .flowchart-link, g.edgeLabel):not(.is-active, .is-linked) {
+    opacity: 0.25;
+  }
+}
+@media screen and (prefers-reduced-motion: no-preference) {
+  :is(.chart, .diagram)
+    svg
+    :is([data-series], .node, .edge, .edge-label, .flowchart-link, g.edgeLabel) {
+    transition: opacity 0.15s;
+  }
+}
+```
+
+## Script
+
+Copy this script once, at the end of the `<body>`.
+
+```html
+<script>
+  // Hover, keyboard focus and a tap on a chart mark or a diagram node show the same state.
+  // A connector takes hover and tap only; keyboard users reach its detail from its nodes.
+  // Each figure is one tab stop, and the arrow keys move focus between its marks or nodes.
+  const pointer = { links: new Map(), active: null, tip: document.createElement("div") };
+  pointer.tip.className = "figure-tip";
+  pointer.tip.setAttribute("role", "tooltip");
+  pointer.tip.hidden = true;
+  document.body.append(pointer.tip);
+
+  function preparePointer() {
+    // Joins every text node with a space, so the lines of a label in <tspan>s stay apart.
+    const words = (element) => {
+      const parts = [];
+      const walker = element ? document.createTreeWalker(element, NodeFilter.SHOW_TEXT) : null;
+      while (walker?.nextNode()) parts.push(walker.currentNode.textContent);
+      return parts.join(" ").replace(/\s+/g, " ").trim();
+    };
+    // The figure's tab stop is its scroll box, or its SVG when it has none. The script
+    // focuses each mark or node itself, so none is a tab stop of its own.
+    const enlist = (target) => {
+      target.tabIndex = -1;
+      const svg = target.closest("svg");
+      const stop = svg.closest(".scroll") ?? svg;
+      stop.tabIndex = 0;
+      stop.dataset.marks = "";
+      if (!stop.hasAttribute("role")) stop.setAttribute("role", "group");
+      if (!stop.hasAttribute("aria-label") && !stop.hasAttribute("aria-labelledby")) {
+        stop.setAttribute("aria-label", words(svg.querySelector(":scope > title")) || "Figure");
+      }
+    };
+    // A chart mark's tooltip is its <title>, which the browser shows without script too.
+    for (const title of document.querySelectorAll(".chart [data-series] title")) {
+      const mark = title.parentElement;
+      if (mark.matches("g, .target, .forecast")) continue;
+      mark.dataset.tip = words(title);
+      mark.setAttribute("aria-label", mark.dataset.tip);
+      enlist(mark);
+      title.remove();
+    }
+    for (const svg of document.querySelectorAll(".diagram svg")) {
+      // A node's <title>, such as a timeline event's, becomes its name and its one tooltip.
+      for (const title of svg.querySelectorAll(".node > title")) {
+        title.parentElement.dataset.label = words(title);
+        title.parentElement.setAttribute("aria-label", words(title));
+        title.remove();
+      }
+      const label = (node) => node.dataset.label || words(node);
+      const nodes = [...svg.querySelectorAll(".node")].filter((node) => label(node));
+      // Mermaid names a flowchart node "<svg id>-flowchart-<id>-<n>" and a link "L_<from>_<to>_<n>".
+      const prefix = `${svg.id}-flowchart-`;
+      const named = new Map(
+        nodes
+          .filter((node) => svg.id && node.id.startsWith(prefix))
+          .map((node) => [node.id.slice(prefix.length).replace(/-\d+$/, ""), node]),
+      );
+      const ends = (line) => {
+        if (line.dataset.from) {
+          return [line.dataset.from, line.dataset.to].map((id) =>
+            nodes.find((node) => node.id === id),
+          );
+        }
+        for (const [name, node] of named) {
+          if (!line.dataset.id?.startsWith(`L_${name}_`)) continue;
+          const other = named.get(line.dataset.id.slice(name.length + 3).replace(/_\d+$/, ""));
+          if (other) return [node, other];
+        }
+        return [];
+      };
+      const links = [...svg.querySelectorAll(".edge, .flowchart-link")].map((line) => {
+        const [from, to] = ends(line);
+        const text = line.dataset.from
+          ? svg.querySelector(
+              `.edge-label[data-from="${line.dataset.from}"][data-to="${line.dataset.to}"]`,
+            )
+          : svg.querySelector(`.edgeLabel [data-id="${line.dataset.id}"]`)?.closest(".edgeLabel");
+        return { line, from, to, text, both: line.hasAttribute("marker-start") };
+      });
+      for (const old of svg.querySelectorAll(".edge-hit")) old.remove();
+      for (const { line, from, to, text, both } of links) {
+        if (!from || !to) continue;
+        const hit = document.createElementNS("http://www.w3.org/2000/svg", "path");
+        hit.setAttribute("class", "edge-hit");
+        hit.setAttribute("d", line.getAttribute("d"));
+        hit.dataset.tip = `${label(from)} ${both ? "↔" : "→"} ${label(to)}${words(text) ? ` (${words(text)})` : ""}`;
+        line.after(hit);
+        pointer.links.set(hit, [line, from, to, ...(text ? [text] : [])]);
+      }
+      for (const node of nodes) {
+        const lines = [label(node)];
+        const parts = [];
+        for (const { line, from, to, text, both } of links) {
+          if (!from || !to || (from !== node && to !== node)) continue;
+          const other = from === node ? to : from;
+          const arrow = both ? "↔" : from === node ? "→" : "←";
+          lines.push(`${arrow} ${label(other)}${words(text) ? ` (${words(text)})` : ""}`);
+          parts.push(line, other, ...(text ? [text] : []));
+        }
+        node.dataset.tip = lines.join("\n");
+        enlist(node);
+        pointer.links.set(node, parts);
+      }
+    }
+  }
+
+  const showPointer = (target) => {
+    if (target === pointer.active) return;
+    hidePointer();
+    pointer.active = target;
+    target.closest("svg").classList.add("has-active");
+    target.classList.add("is-active");
+    for (const part of pointer.links.get(target) ?? []) part.classList.add("is-linked");
+    const { tip } = pointer;
+    tip.textContent = target.dataset.tip;
+    tip.hidden = false;
+    // A chart mark's tooltip clears the mark's own printed value: a text of its series within
+    // 24px of the mark that the tooltip repeats, other than the series' name.
+    const mark = target.getBoundingClientRect();
+    const gap = (a) =>
+      Math.hypot(
+        Math.max(0, a.left - mark.right, mark.left - a.right),
+        Math.max(0, a.top - mark.bottom, mark.top - a.bottom),
+      );
+    const series = target.closest(".chart [data-series]");
+    const value =
+      [...(series?.querySelectorAll("text") ?? [])]
+        .map((text) => [text.textContent.trim(), text.getBoundingClientRect()])
+        .filter(([words, box]) => words && words !== series.dataset.series.trim() && gap(box) <= 24)
+        .filter(([words]) => tip.textContent.includes(words))
+        .map(([, box]) => box)
+        .sort((a, b) => gap(a) - gap(b))[0] ?? mark;
+    const box = {
+      left: Math.min(mark.left, value.left),
+      top: Math.min(mark.top, value.top),
+      right: Math.max(mark.right, value.right),
+      bottom: Math.max(mark.bottom, value.bottom),
+    };
+    const width = document.documentElement.clientWidth;
+    const left = Math.min(
+      Math.max((box.left + box.right) / 2 - tip.offsetWidth / 2, 8),
+      width - tip.offsetWidth - 8,
+    );
+    const above = box.top - tip.offsetHeight - 8;
+    tip.style.left = `${left + scrollX}px`;
+    tip.style.top = `${(above >= 0 ? above : box.bottom + 8) + scrollY}px`;
+  };
+  const hidePointer = () => {
+    const target = pointer.active;
+    if (!target) return;
+    target.closest("svg").classList.remove("has-active");
+    target.classList.remove("is-active");
+    for (const part of pointer.links.get(target) ?? []) part.classList.remove("is-linked");
+    pointer.tip.hidden = true;
+    pointer.active = null;
+  };
+  const targetOf = (event) => event.target.closest?.("[data-tip]");
+  document.addEventListener("pointerover", (event) => {
+    if (event.pointerType !== "touch" && targetOf(event)) showPointer(targetOf(event));
+  });
+  document.addEventListener("pointerout", (event) => {
+    const target = targetOf(event);
+    if (event.pointerType === "touch") return;
+    if (target && target === pointer.active && !target.contains(event.relatedTarget)) {
+      if (document.activeElement !== target) hidePointer();
+    }
+  });
+  document.addEventListener("focusin", (event) =>
+    targetOf(event) ? showPointer(targetOf(event)) : hidePointer(),
+  );
+  document.addEventListener("focusout", (event) => {
+    const target = targetOf(event);
+    if (target && target === pointer.active && !target.matches(":hover")) hidePointer();
+  });
+  // A tap shows what hover shows until the reader taps elsewhere; a mark or node takes focus.
+  document.addEventListener("click", (event) => {
+    const target = targetOf(event);
+    if (target) {
+      if (target.hasAttribute("tabindex")) target.focus();
+      showPointer(target);
+    } else if (pointer.active && !pointer.active.matches(":focus")) hidePointer();
+  });
+  // From the figure's tab stop, an arrow key or Home focuses its first mark or node, and End
+  // its last; from a mark, the arrow keys move to the next or previous one in drawing order.
+  const moves = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1, Home: -1e9, End: 1e9 };
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") hidePointer();
+    const stop = event.target.closest?.("[data-marks]");
+    const move = moves[event.key];
+    if (!stop || !move) return;
+    const targets = [...stop.querySelectorAll("[data-tip][tabindex]")];
+    const at = targets.indexOf(event.target);
+    const next = at === -1 && move < 1e9 ? 0 : Math.min(Math.max(at + move, 0), targets.length - 1);
+    event.preventDefault();
+    targets[next]?.focus();
+  });
+  preparePointer();
+</script>
+```
+
+## Check
+
+Hover the first mark or node of each figure: it stands out and its tooltip shows. Tab to the figure, which is one tab stop, press the Right arrow key and confirm the same state on the first mark or node, then emulate reduced motion and confirm the state switches without a fade.

package/dist/skills/pageship-interaction/references/step-through.md

@@ -0,0 +1,146 @@
+# Step-through
+
+The markup, style and script for [the step-through](../SKILL.md#step-through) and [the path trace](../SKILL.md#path-trace). Copy them unchanged; change only the ids, the steps and the labels.
+
+## Markup
+
+Give the step-through an `id` and the class `stepper`. List the steps as an ordered list, numbered with `data-step` from 1. Each step starts with its name in a `<strong>`, then its essential values. A path trace or a diagram's step-through puts its diagram, drawn by `pageship-diagram`, before the list, and marks each node and connector with the step that brings it in, using the same numbers. The controls and the status line carry `hidden`, so a reader without script never sees them.
+
+```html
+<figure class="diagram stepper" id="path">
+  <div class="scroll" tabindex="0" role="region" aria-label="Ticket path diagram">
+    <svg ...>
+      ...
+      <path class="edge" data-step="2" data-from="path-triage" data-to="path-billing" ... />
+      <g class="node" data-step="1" id="path-triage">...</g>
+    </svg>
+  </div>
+  <ol class="steps">
+    <li data-step="1"><strong>Triage</strong>: a ticket arrives in the triage queue.</li>
+    <li data-step="2">
+      <strong>Tagging</strong>: the triage responder tags it billing, bug or other.
+    </li>
+  </ol>
+  <div class="step-controls" role="toolbar" aria-label="Step through the path" hidden>
+    <button type="button" data-go="previous">Previous step</button>
+    <button type="button" data-go="next">Next step</button>
+    <button type="button" data-go="all">Show all steps</button>
+  </div>
+  <p class="step-status" role="status" aria-live="polite" hidden></p>
+  <figcaption>...</figcaption>
+</figure>
+```
+
+A step-through without a diagram is the same markup with a `<section class="stepper" id="...">` in place of the figure, a heading in place of the caption, and no SVG.
+
+## Style
+
+```css
+.stepper .is-current rect,
+.stepper .edge.is-current {
+  stroke: var(--accent);
+  stroke-width: 3;
+}
+.stepper li.is-current {
+  font-weight: 600;
+  border-left: 3px solid var(--accent);
+  padding-left: 0.5rem;
+}
+.step-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0.75rem 0;
+}
+.step-controls[hidden],
+.step-status[hidden] {
+  display: none;
+}
+.step-controls button {
+  font: inherit;
+  min-height: 44px;
+  padding: 0.25rem 0.875rem;
+  color: var(--fg);
+  background: var(--surface);
+  border: 1px solid var(--muted);
+  border-radius: 6px;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .stepper [data-step] {
+    transition: opacity 0.2s;
+  }
+  .stepper .is-later {
+    opacity: 0.25;
+  }
+}
+@media print {
+  .stepper .is-later {
+    opacity: 1;
+  }
+  .step-controls,
+  .step-status {
+    display: none;
+  }
+}
+```
+
+## Script
+
+Copy this script once, at the end of the `<body>`. It drives every `.stepper` on the page.
+
+```html
+<script>
+  for (const stepper of document.querySelectorAll(".stepper")) {
+    const parts = stepper.querySelectorAll("[data-step]");
+    const steps = stepper.querySelectorAll("ol.steps > li");
+    const status = stepper.querySelector(".step-status");
+    const controls = stepper.querySelector(".step-controls");
+    let current = 0; // 0 shows every step.
+    const show = (step, record = true) => {
+      current = step;
+      for (const part of parts) {
+        const n = Number(part.dataset.step);
+        part.classList.toggle("is-current", current > 0 && n === current);
+        part.classList.toggle("is-later", current > 0 && n > current);
+        if (part.tagName === "LI") {
+          if (current > 0 && n === current) part.setAttribute("aria-current", "step");
+          else part.removeAttribute("aria-current");
+        }
+      }
+      const name = (li) => (li.querySelector("strong") ?? li).textContent.trim();
+      status.textContent =
+        current === 0
+          ? `Showing all ${steps.length} steps.`
+          : `Step ${current} of ${steps.length}: ${name(steps[current - 1])}`;
+      if (record) {
+        const url = current ? `#${stepper.id}-${current}` : location.href.split("#")[0];
+        history.replaceState(null, "", url);
+      }
+    };
+    // Next runs from every step shown through each step and back; Previous runs the other way.
+    const go = {
+      next: () => (current + 1) % (steps.length + 1),
+      previous: () => (current + steps.length) % (steps.length + 1),
+      all: () => 0,
+    };
+    for (const button of controls.querySelectorAll("[data-go]")) {
+      button.addEventListener("click", () => show(go[button.dataset.go]()));
+    }
+    controls.addEventListener("keydown", (event) => {
+      const move = { ArrowRight: "next", ArrowLeft: "previous" }[event.key];
+      if (!move) return;
+      event.preventDefault();
+      show(go[move]());
+    });
+    controls.hidden = false;
+    status.hidden = false;
+    const opened = Number(location.hash.slice(stepper.id.length + 2));
+    const named = location.hash.startsWith(`#${stepper.id}-`) && opened >= 1;
+    show(named && opened <= steps.length ? opened : 0, false);
+  }
+</script>
+```
+
+## Check
+
+Press each control by keyboard, and the Left and Right arrow keys on them. Confirm the page opens showing every step, Next walks each step in turn and then shows every step again, the current step's list item carries `aria-current="step"`, and with reduced motion emulated every step stays at full strength. Open the page with a step's fragment, such as `#path-2`, and confirm it opens on that step.