Explainer 0.4.1: what changes, and two faults to fix first

overment/skills · commit range 96b61c0 → 3e0cbc9 (one commit, 27 files) · committed 28 Sep 2026 · report 27 Oct 2026

This change to the explainer, a skill (instructions and scripts that an AI agent loads) that turns a plain-text description into an interactive diagram page, is ready to merge after two small fixes.

Readers get a shorter card (the box that opens when they click a part of a diagram). In Gantt plans (tasks drawn as bars on a calendar), an arrow with a long way around now runs straight over the bars between. The first four chart colours keep away from the highlight colour that marks the author's main point. Decisions 1 and 2 are the two fixes.

Decisions

  1. Progress of a phase in a Gantt plan. The card of a phase (a named group of tasks) now says "Done: 72% of its planned days". The number still counts only the tasks that report progress. In the sample plan, only 17% of the phase's days are done.

    1. ★ Put back the old words, "of the tracked days", before merge. One line.
    2. Count all the phase's days, so that the new words are true.
    3. Merge as is.
  2. The page check no longer sees most relation lines. The page check (the command that tests a built page in a hidden browser) makes sure that each relation line on a card (a line that names a linked part, such as "pays ← Shopper") names only the other part, not the card's own part too. The card now shows a relation to one part in a new layout that the check does not look for. In the 42 example documents that ship with the explainer, it reads 252 of 660 relation lines. Before, it read 781 of 781.

    1. ★ Teach the check the new layout before merge, with a test. A few lines.
    2. Merge as is. A badly worded relation line passes unseen.
  3. Link buttons that cards drop. A card shows each linked part as a small button that selects that part. When the bold value line under the card's title already names a part in plain text, the card now drops the button. 18 buttons are gone in the example documents. For example, the card of a foreign key (a column that points at a row of another table) no longer links to its two columns. See the scene.

    1. ★ Keep those buttons. Drop a button only when the same button is already on the card. A small change to the new rule and its test.
    2. Merge as is. The reader goes back to the diagram to reach the column.
  4. Gantt arrows over bars. An arrow that went far around other bars now runs straight over them. In the sample, a click on the bar where the arrow crosses it selects the arrow, not the bar. The author gets no warning when this happens, and the test that failed on a crossing was deleted.

    1. ★ Merge, then fix in the next change: the bar takes the click, and the author gets a warning.
    2. Fix the click before merge.
    3. Go back to arrows that go around the bars.
  5. Changes that nobody announced. In a box diagram (boxes joined by arrows), the legend (the key that says what each box and line style means) shows fewer keys. More numbered notes (the author's notes on a diagram) lose the line to their part. The commit message does not say so. Neither does the skill's listing entry (its paragraph in the repository's list of skills) or the format reference (the file that tells authors how to write a document). The format reference still says that the legend lists every box and line kind.

    1. ★ Update the format reference and the listing entry before merge.
    2. Merge as is.

System map

The parts this change touches, and their neighbours The built page: one web page file Author or AI agentwrites and builds pages Version and listingwhat an agent reads first The documentplain text with data read by writes build Box diagramsboxes, arrows and a legend Gantt planstask bars on a calendar Chart coloursone colour per data series Other diagramsboards, tables, timelines The cardopens when a part is clicked Numbered notesthe author's notes on a diagram a click opens point at parts Readerviews and clicks clicks The page checktests the built page tests code changed behaviour changed, code not context, not changed

Parts

The card

The card is shorter. Each fact shows once, a link to one part takes one line, and a card under the diagram has no dot.

Before
In an example checkout diagram, a click on Storefront opened the card under the diagram. A black dot sat over Storefront and a second dot at the top of the card. The card said "Downstream 4 parts". Then came "pays ←" over a Shopper button, and a bare "→" over a Checkout button.
After
The same click opens the same card with no dots. It says "Leads on to 4 parts", then one line "pays ← Shopper" and one line "To Checkout". Other words also change: "Upstream" is now "Reached from", "Descendants" is now "Parts below it", and "Crossing edges" is now "Connectors across its border".
Why
A new reader reads each line once. The dot looked like a numbered note, so it was one more mark to learn.
Risk
  • Link buttons disappear when the value line names their part (decision 3). This happens 18 times in the example documents. The scene of the foreign key card is below.
  • The rule that removes repeats guesses by matching words. In the example documents, it hides 71 facts. Most are true repeats, but some lose a number: "Allowed in: 1 of 3" goes, and the buttons under it do not say "of 3". An author's own document can lose a fact in the same way, and no test covers that.
  • Under the diagram, only the selection ring (the dark outline around the selected part) and the card title now tell which part the card is about. On a tall diagram, that part can be off screen while the reader reads the card.
  • Old code comments in three board diagrams still describe the removed dot. Readers do not see them.
Before: card under the checkout diagram, with a dot over Storefront and in the card, Downstream 4 parts, relations as headings over buttons
Before, 0.4.0: dots over Storefront and in the card. Each relation is a heading over a button.
After: the same card with no dots, Leads on to 4 parts, one line per relation
After, 0.4.1: no dots. One line per relation. The legend has no "service" key.
Before: foreign key card with buttons for orders.user_id and users.id
Before: the foreign key card links to both columns.
After: the same card without the two column buttons
After: the value line names the columns, and the buttons are gone.

Gantt plans

Arrows between tasks run straight over other bars, and the card of a phase states its progress in new words.

Before
In a sample plan with three tasks, the arrow from "Write spec" to "Test plan" went left, around the long "Build platform" bar. The card of the phase "Plan" said "Done: 72% of the tracked days".
After
The arrow runs straight down over "Build platform", on a thin strip of background colour. The phase card says "Done: 72% of its planned days". But only 13 of the phase's 78 planned days are done (17%), because "Build platform" (60 days) reports no progress.
Why
An arrow looked for a free column (a place on the time axis where no bar is in the way). Arrows that crossed the whole chart to find one were long, and they bunched together. Now, when the free column is more than 96 pixels away, the arrow goes straight.
Risk
  • The new progress words are wrong when some tasks in a phase report no progress (decision 1).
  • A click on a bar where an arrow crosses it selects the arrow (decision 4). In the sample, the same click selected the bar before.
  • The author is not told when an arrow crosses bars. The test that failed on such a crossing was deleted. The new test allows 296 pixels of sideways travel, not the 96 it names.
  • A code comment over the code that picks an arrow's path still says that an arrow never crosses a bar.
Before: the arrow goes around the Build platform bar; the phase card says 72% of the tracked days
Before, 0.4.0: the arrow goes around "Build platform". The card says "of the tracked days".
After: the arrow runs straight over the Build platform bar; the phase card says 72% of its planned days
After, 0.4.1: the arrow runs over "Build platform". The card says "of its planned days". The "Critical" line (the critical path: the chain of tasks that sets the end date) is gone, because the buttons under it name the same tasks.

Box diagrams

Arrows keep out of areas they do not belong to, labels keep away from other arrows, and the legend shows fewer keys.

Before
A box diagram can group boxes in a zone (a framed, named area). An arrow could take its shortest path through a zone that neither of its ends was in. An arrow label could sit as close to another arrow as to its own. The legend listed every box kind and line kind that the diagram used, the plain box ("service") too.
After
A path through a zone that neither end is in now costs more than a crossing. If it still happens, the lint (the explainer's text check before a build) warns. A label first looks for a spot 28 pixels from any parallel arrow. If it stays as close to another arrow as to its own, the lint warns. The legend leaves out the plain box. When the diagram uses only one line style, the legend leaves out lines. In the first card scene, "service" is gone from the legend.
Why
A line inside a zone looks like a part of it. A label between two lines can name the wrong one. A key that does not tell two looks apart takes room.
Risk
  • The legend change is not documented (decision 5). It changes the legend in 11 of the 42 example documents. When all arrows in a diagram use the same dashed style, nothing explains the dash. The explainer's own design rules say that dashes are explained in the legend.
  • Documents that passed the lint before can now get the two new warnings. No example document does: the lint output is the same before and after.
  • Labels and arrows in existing diagrams can move, so old screenshots no longer match a rebuild.
  • A code comment says that the first label search keeps 28 pixels from zone borders too. The code keeps that distance only from parallel arrows.

Numbered notes

In the full view (the page mode that adds the author's text), more note boxes stand alone, without a line to their part.

Before
An author's note shows as a numbered circle on the diagram. In the full view, it also shows as a box with the note text. A thin line joined the box to its part, unless the line was too long or crossed a label or an arrow. In the example documents, 31 of 67 note boxes had a line.
After
The line is also left out when it would cross another box, bar or dot. Now 25 of 67 note boxes have a line. In the checkout diagram, note 2 loses its line to Receipts. The numbered circle also moves away from spots that are nearer to another part than to its own.
Why
A line through a part that the note is not about seems to point at that part.
Risk
  • The commit message and the docs do not mention it (decision 5). Six notes in six example documents lose their line. The reader then matches the box to its part by the number only.
Before: note 2 is joined to Receipts by a thin line
Before: a line joins note 2 to Receipts.
After: note 2 stands alone, without a line
After: note 2 has no line.

Chart colours

In a chart, the second data series (one line, or one set of bars) is now green, not ochre. Every chart with two or more series changes colours.

Before
The series colours, in order: blue, ochre, green, purple, teal, rose, olive, slate. The second, ochre, was only 18° from the orange highlight colour on the colour wheel.
After
Blue, green, purple, teal, olive, slate, rose, ochre. The first four are 95° or more from the highlight colour. A new test keeps the first four 45° or more away.
Why
A series close to the highlight colour looks like the author's main point.
Risk
  • Every existing chart with two or more series changes colours when it is built again. Text that names a colour, such as "the ochre line", becomes wrong.
  • Charts with five or more series still get colours near the highlight colour: series 5 at 41°, series 7 at 32° and series 8 at 18°. The new test checks only the first four.
Before: the Web line is ochre, next to the orange Mobile line
Before: "Web" is ochre, close to the orange "Mobile" line that the author marked as the main point.
After: the Web line is green
After: "Web" is green.

The page check behaviour changed, code not

Readers see no change. The check of relation lines on cards now reads only some of them, and it still passes.

Before
The page check opens each card and reads its relation lines. It found them by the old card layout, and it read all of them.
After
The card shows a relation to one part as a single line, in a layout that the check does not search. On 234 cards, the check finds no relation line at all and skips the test.
Why
The card layout changed, and the check did not.
Risk
  • A relation line that repeats both parts, such as "Storefront pays Shopper", now passes unseen (decision 2).
Example documents, every card openedBeforeAfter
Cards764764
Relation lines on the cards781660
Relation lines that the check reads781252
Cards with relation lines that the check does not see at all0234

Version and listing

The skill's instructions say version 0.4.1. Its entry in the repository's list of skills adds "each fact said once and each relation on one line".

Before
Version 0.4.0.
After
Version 0.4.1. The description that tells an agent when to load the skill did not change. So the repository rule to run the skill's routing tests (prompts that should and should not load it) again does not apply.
Why
The repository rules ask for a new version number and a new listing entry when a skill's behaviour changes.
Risk
  • The entry names only the card change. The arrow, legend, note and colour changes are not in it (decision 5).

How this was checked

Files

27 files, +299 −162, from 96b61c0 to 3e0cbc9, diffed from the merge base 96b61c0. No lockfiles and no generated files. Each file is listed once, under its main part; a hunk that serves another part carries that part's name.

The card

skills/explainer/scripts/client/popover.ts+68 −13, 7 hunks
@@ -83,16 +83,57 @@ export function cardData(model: DocModel, id: string): CardData | null {
const title = ends ? `${ends[0].text} → ${ends[1].text}` : el.label; const norm = (s: string) => s.replace(/\s+/g, " ").trim().toLowerCase(); const parts = [el.value, isEdge ? el.label : el.sub].filter((s): s is string => !!s && norm(s) !== norm(title)); + const value = [...new Set(parts)].join(" · "); + const head = eyebrow(el); + const crumb = (el.crumb ?? []).filter((c) => c !== id).map((c) => chip(model, c)); + // the breadcrumb and an edge's two ends are already chips at the top; a relation to only those says it again + const shown = new Set([...crumb, ...(ends ?? [])].map((c) => c.id)); + const said = sayOnce(value, head, el.facts ?? [], relationGroups(model, id), el.aboutHtml ?? el.about ?? ""); + const facts = said.facts, groups = said.groups.filter((g) => !g.chips.every((c) => shown.has(c.id))); return { id, − eyebrow: eyebrow(el), − crumb: (el.crumb ?? []).filter((c) => c !== id).map((c) => chip(model, c)), + eyebrow: head, + crumb, title, ends, − value: [...new Set(parts)].join(" · "), − facts: (el.facts ?? []).slice(0, 5), + value, + facts: facts.slice(0, 5), aboutHtml: el.aboutHtml ?? "", − groups: relationGroups(model, id), + groups, + }; +} + +/** + * Each thing once. A reader who just joined scans the card top to bottom, and a fact that repeats the value, the + * kind in the eyebrow, the about sentence or the chips below it is a line they read twice. Chips win over a fact that lists the same + * parts, because a chip also takes them there; a group of parts the facts already link to, or that the value + * spells out, goes. + */ +export function sayOnce(value: string, head: string, facts: Fact[], groups: RelGroup[], about = ""): { facts: Fact[]; groups: RelGroup[] } { + const norm = (s: string) => s.replace(/\s+/g, " ").trim().toLowerCase(); + const prose = norm(about.replace(/<[^>]*>/g, "")); + // a fact the about sentence already says in full ("exactly one users row") is read there, in context + const told = (f: Fact) => norm(f.v).length >= 12 && prose.includes(norm(f.v)); + const words = norm(`${value} ${head.split(" · ")[0]}`); + // a chip is already on the card when a fact names that part outright ("Web client · 1 part below"); a fact that + // only links to it for another reason ("Ends · 1 d before Public launch") does not say what the group says + const named = (c: Chip) => facts.some((f) => f.ref === c.id && (norm(f.k) === norm(c.text) || norm(f.v) === norm(c.text))); + // the value spells a chip out only when it contains its exact text: "orders.user_id → users.id" names users.id, while + // a message "sends call 1" does not stand for the Call 1 column it links to + const spelled = (c: Chip) => !!value && value.includes(c.text); + const kept = groups.filter((g) => !g.chips.every(named) && !g.chips.every(spelled)); + const rels = new Set(kept.map((g) => norm(g.rel))); + // a fact is "listed" when the chips say the same: all of several chips named in it, or the one chip word for word + // under words that share a stem with the fact's ("Critical" and "On the critical path"). One chip alone proves little: + // "Can no longer reach: Cart" and "checks out ← Cart" name the same part and say different things. + const stems = (t: string) => new Set(norm(t).split(/[^a-z0-9]+/).filter((w) => w.length > 3).map((w) => w.slice(0, 5))); + const akin = (a: string, b: string) => [...stems(a)].some((w) => stems(b).has(w)); + const listed = (f: Fact) => kept.some((g) => g.chips.length > 1 + ? g.chips.every((c) => norm(f.v).includes(norm(c.text))) + : norm(f.v) === norm(g.chips[0]?.text ?? "") && akin(f.k, g.rel)); + return { + facts: facts.filter((f) => f.ref || !(norm(f.v) === norm(value) || norm(f.v) === norm(head.split(" · ")[0]) || rels.has(norm(f.k)) || listed(f) || told(f) || (norm(f.v).length > 2 && words === norm(f.v)))), + groups: kept, }; }
@@ -151,7 +192,6 @@ export function h<K extends keyof HTMLElementTagNameMap>(tag: K, cls = "", text?
const chipButton = (c: Chip, cls = "x-chip") => h("button", cls, c.text, { type: "button", "data-ref": c.id }); export interface CardExtras { − pin?: boolean; // docked under the figure: a filled dot, the twin of the one beside the anchor note?: { n: string; text: string }; // the reading-panel note on this element, listed first mentions?: { i: number; text: string }[]; // linked prose sentences, full view only back?: Chip; // the previous selection made through a chip
@@ -161,10 +201,10 @@ export interface CardExtras {
play?: string; // scene id for "Play from here" } −function head(box: HTMLElement, eyebrowText: string, pin?: boolean) { − if (!eyebrowText && !pin) return; +// The ink ring already marks what the card is about, so the eyebrow carries no marker of its own. +function head(box: HTMLElement, eyebrowText: string) { + if (!eyebrowText) return; const p = h("p", "x-pop-eyebrow"); − if (pin) p.append(h("span", "x-pop-num", "", { "aria-hidden": "true" })); p.append(eyebrowText); box.append(p); }
@@ -181,8 +221,23 @@ function actions(box: HTMLElement, x: CardExtras) {
box.append(row); } +/** + * Relations. A relation to one part is one row, its words on the left and the part on the right, like a fact: + * "writes plan ← Planner". Several parts under the same words keep a heading over their chips. + */ function groups(box: HTMLElement, list: RelGroup[]) { + let rows: HTMLElement | null = null; for (const g of list) { + if (g.chips.length === 1 && g.rel.length <= 32) { + if (!rows) box.append((rows = h("dl", "x-pop-facts x-pop-rows"))); + const div = h("div", "x-pop-fact"); + const dd = h("dd"); + dd.append(chipButton(g.chips[0])); + div.append(h("dt", "", g.rel), dd); + rows.append(div); + continue; + } + rows = null; const div = h("div", "x-pop-rel"); div.append(h("p", "x-pop-k", g.rel)); const chips = h("div", "x-chips");
@@ -215,7 +270,7 @@ function facts(box: HTMLElement, list: Fact[], note?: CardExtras["note"]) {
/** The card body for one element. `id` prefixes the title id that aria-labelledby points at. */ export function renderCard(d: CardData, popId: string, x: CardExtras = {}): HTMLElement { const box = h("div", "x-pop-body"); − head(box, d.eyebrow, x.pin); + head(box, d.eyebrow); if (d.crumb.length) { const p = h("p", "x-pop-crumb"); d.crumb.forEach((c) => p.append(chipButton(c, "x-crumb"), h("span", "x-crumb-sep", "›", { "aria-hidden": "true" })));
@@ -245,7 +300,7 @@ export function renderCard(d: CardData, popId: string, x: CardExtras = {}): HTML
export function renderCompare(c: CompareData, popId: string, x: CardExtras = {}): HTMLElement { const box = h("div", "x-pop-body"); − head(box, "Compare", x.pin); + head(box, "Compare"); const title = h("h3", "x-pop-title", undefined, { id: `${popId}-t` }); title.append(chipButton(c.a, "x-crumb"), h("span", "x-pop-arrow", " vs "), chipButton(c.b, "x-crumb")); box.append(title);
@@ -272,9 +327,9 @@ export function renderCompare(c: CompareData, popId: string, x: CardExtras = {})
} /** A step note in the graph: step count and the note, no actions. */ −export function renderCallout(count: string, note: string, popId: string, pin?: boolean): HTMLElement { +export function renderCallout(count: string, note: string, popId: string): HTMLElement { const box = h("div", "x-pop-body"); − head(box, count ? `Step ${count}` : "Step", pin); + head(box, count ? `Step ${count}` : "Step"); box.append(h("p", "x-pop-title x-pop-note-text", note, { id: `${popId}-t` })); return box; }
skills/explainer/scripts/client/client.ts+10 −16, 6 hunks
@@ -839,7 +839,6 @@ export function boot(): void {
const el = model.elements[id]; const legend = index.get(id)?.some((x) => x.matches(".x-legend-item")); return { − pin: true, note: noteFor(id), mentions: mentionsOf(id), back: back.length ? { id: back[back.length - 1], text: model.elements[back[back.length - 1]]?.label ?? back[back.length - 1] } : undefined,
@@ -851,8 +850,8 @@ export function boot(): void {
}; const bodyFor = (s: State, popId: string): { id: string; body: HTMLElement } | null => { const { story, scene } = frameOf(s); − if (scene?.active) return scene.note ? { id: scene.active, body: renderCallout(scene.count, scene.note, popId, true) } : null; − if (story?.sel && story.note) return { id: story.sel, body: renderCallout(story.count, story.note, popId, true) }; + if (scene?.active) return scene.note ? { id: scene.active, body: renderCallout(scene.count, scene.note, popId) } : null; + if (story?.sel && story.note) return { id: story.sel, body: renderCallout(story.count, story.note, popId) }; const { sel, cmp } = frameOf(s); if (!sel) return null; if (cmp) {
@@ -971,18 +970,9 @@ export function boot(): void {
if (p.mode === "dock-below") { host.classList.add("is-dock-below"); pop.style.left = pop.style.top = ""; + // The ink ring marks the selection, so nothing is drawn beside it: a numbered dot there would be one more + // mark for a new reader to decode. const a = rel(anchorBox(anchors, id)); − // The first free spot around the anchor: above its middle, then its corners, then below; never on a − // callout or a label (beside a bar sits its value label). − const busy = $<Element>(".x-callout, text", host).filter((t) => !t.closest(".x-leader")).map((t) => rel(t.getBoundingClientRect())); − const spots: [number, number][] = [ − [a.x + a.w / 2, a.y - 14], [a.x + a.w + 10, a.y - 10], [a.x - 10, a.y - 10], [a.x + a.w / 2, a.y + a.h + 14], [a.x + a.w + 14, a.y + a.h / 2], − ]; − const free = spots.find(([x, y]) => y >= 10 && !busy.some((b) => x + 10 > b.x && x - 10 < b.x + b.w && y + 10 > b.y && y - 10 < b.y + b.h)); − const [cx, cy] = free ?? [a.x + a.w / 2, Math.max(10, a.y - 14)]; − // a board mark with its own pin slot (plans-boards) shows the 1 in its marker lane instead − const lanePin = anchors.length === 1 && anchors[0].querySelector(":scope > .x-plan-lane > .x-plan-pin, :scope > * > .x-plan-lane > .x-plan-pin"); − if (!lanePin) overlay.append(ns("circle", { class: "x-leader-num", cx, cy, r: 6 })); if (mobile) { const scroll = host.querySelector<HTMLElement>(":scope > .x-scroll"); if (scroll && scroll.scrollWidth > scroll.clientWidth) scroll.scrollLeft = a.x + scroll.scrollLeft + a.w / 2 - scroll.clientWidth / 2;
@@ -1127,6 +1117,9 @@ export function boot(): void {Numbered notes
}); }; const wires = $<Element>(".x-edge", stage).filter(within).map((el) => ({ id: el.getAttribute("data-id") ?? "", rects: along(el) })); + // boxes too: a leader through a part it is not about reads as pointing at that part + const parts = $<Element>(".x-node, .x-mark", stage).filter((el) => within(el) && !el.querySelector(".x-mark")) + .map((el) => ({ id: el.getAttribute("data-id") ?? "", rect: rel(el.getBoundingClientRect()) })); spots.forEach((r, i) => { const { box, item } = boxes[i]; if (!r) return box.remove();
@@ -1135,7 +1128,8 @@ export function boot(): void {Numbered notes
const l = leader(r, nearest(r, item), labels); // A far callout (in a lane) is paired with its marker by the number alone, like a far card. const refs = refIds(box.dataset.refs); − const wired = wires.some((w) => !refs.includes(w.id) && w.rects.some((b) => crosses(l.x1, l.y1, l.x2, l.y2, b))); + const wired = wires.some((w) => !refs.includes(w.id) && w.rects.some((b) => crosses(l.x1, l.y1, l.x2, l.y2, b))) + || parts.some((m) => !refs.includes(m.id) && crosses(l.x1, l.y1, l.x2, l.y2, m.rect)); const far = l.length > LEADER_MAX || labels.some((b) => crosses(l.x1, l.y1, l.x2, l.y2, b)) || wired; if (!l.caret && !far) lines.append(ns("line", { class: "x-callout-line", "data-note": box.dataset.note!, x1: l.x1, y1: l.y1, x2: l.x2, y2: l.y2 })); });
@@ -1161,7 +1155,7 @@ export function boot(): void {
const { sel } = frameOf(s); const d = sel ? cardData(model, sel) : null; for (const p of panels) { − if (d && sel) p.replaceChildren(renderCard(d, `${p.id || "x-detail"}-card`, { ...extrasFor(sel), pin: false, mentions: [] })); + if (d && sel) p.replaceChildren(renderCard(d, `${p.id || "x-detail"}-card`, { ...extrasFor(sel), mentions: [] })); else p.innerHTML = empty.get(p) ?? ""; if (p.dataset.placement !== "inline") p.hidden = !d; }
skills/explainer/scripts/styles/base.css+6 −16, 3 hunks
@@ -692,17 +692,6 @@ html[data-js] .x-scene:hover { background: var(--x-surface-2); border-color: var
font-size: var(--x-fs-tag); color: var(--x-text-dim); } −/* the dock pin is a filled ink dot with no numeral: numbers belong to the author's notes, so a pin beside note ① or ② − never reads as another note. Its twin opens the card's eyebrow. */ −.x-pop-num { − display: none; − width: 12px; − height: 12px; − margin-right: 8px; − vertical-align: -1px; − background: var(--x-text); − border-radius: 50%; −} .x-pop-crumb { display: flex; flex-wrap: wrap; align-items: baseline; font-size: var(--x-fs-caption); color: var(--x-text-dim); } .x-crumb-sep { margin: 0 8px; color: var(--x-text-faint); } .x-pop-title { padding-right: 24px; font-size: var(--x-fs-body); font-weight: 600; line-height: 24px; }
@@ -721,9 +710,12 @@ html[data-js] .x-scene:hover { background: var(--x-surface-2); border-color: var
.x-crumb:hover { text-decoration-color: var(--x-text); } .x-pop-value { font-size: var(--x-fs-body); font-weight: 600; line-height: 24px; font-variant-numeric: tabular-nums; } .x-pop-facts { display: grid; gap: 4px; margin: 0; font-size: var(--x-fs-ui); font-variant-numeric: tabular-nums; } −.x-pop-fact { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; } −.x-pop-fact dt { flex: 1 1 40%; min-width: 0; color: var(--x-text-dim); } −.x-pop-fact dd { flex: 0 1 auto; max-width: 78%; margin: 0; text-align: right; overflow-wrap: anywhere; } +/* a fact is one line while key and value fit; a value too long for the rest of the line (a chip, a list) moves under + its key, right-aligned, instead of breaking mid-word or squeezing the key onto two lines */ +.x-pop-fact { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; column-gap: 12px; row-gap: 2px; } +.x-pop-fact dt { flex: 1 0 auto; max-width: 100%; color: var(--x-text-dim); } +.x-pop-fact dd { flex: 0 1 auto; max-width: 100%; margin: 0 0 0 auto; text-align: right; overflow-wrap: anywhere; } +.x-pop-fact dd > .x-chip { white-space: nowrap; max-width: 100%; overflow-wrap: anywhere; } .x-pop-note { display: block; padding-bottom: 4px; } .x-pop-note dd { max-width: none; text-align: left; } .x-pop-about { color: var(--x-text); }
@@ -801,14 +793,12 @@ html[data-js] .x-scene:hover { background: var(--x-surface-2); border-color: var
.x-leader-line { stroke: var(--x-line-strong); stroke-width: 1; } .x-leader-dot { fill: var(--x-line-strong); } .x-leader-caret { fill: var(--x-surface); stroke: var(--x-line-strong); stroke-width: 1; stroke-linejoin: round; } −.x-leader-num { fill: var(--x-text); stroke: var(--x-bg); stroke-width: 2; } /* docked: in the gutter 16px right of the plot (the stage reserves it only when the plot would otherwise reach it; the plot never shrinks), in flow under the figure otherwise */ .x-stage.is-dock-right, .x-pop-host.is-dock-right { padding-right: calc(var(--x-pop-w, 256px) + 16px); } .x-stage.is-dock-right.has-gutter, .x-pop-host.is-dock-right.has-gutter { padding-right: 0; } .is-dock-below > .x-pop { position: relative; left: auto; top: auto; width: auto; max-width: 544px; margin-top: 16px; } −.is-dock-below > .x-pop .x-pop-num { display: inline-grid; } /* annotation layer: in the full view each note is also a callout on the graph, joined to its marker */ .x-callouts { position: absolute; inset: 0; z-index: 8; pointer-events: none; }
skills/explainer/scripts/styles/blocks/plans-boards.css+3 −14, 2 hunks
@@ -82,14 +82,13 @@
.x-plan-dot[data-tone="danger"], [data-tone="danger"] > .x-plan-dot { background: var(--x-danger); } .x-plan-blocked { display: inline-flex; align-items: center; gap: 5px; color: var(--x-danger-ink, var(--x-danger)); } −/* the marker lane: a mark's numbered note markers (the reading panel's notes) and the docked card's ① pin share one − slot inside the mark, never on its border. On a card the lane floats right in the first line and the title wraps +/* the marker lane: a mark's numbered note markers (the reading panel's notes) sit in one slot inside the mark, + never on its border. On a card the lane floats right in the first line and the title wraps around it; on a head, row label or chip its markers are flex items after the count or label. */ .x-plan-line { display: block; min-width: 0; } .x-plan-lane { display: contents; } .x-plan-card > .x-plan-line > .x-plan-lane { float: right; display: flex; gap: 4px; margin-left: 8px; } −.x-plan-note, −.x-plan-pin { +.x-plan-note { display: grid; flex: none; place-items: center;
@@ -108,16 +107,6 @@
/* in a head, row label or chip the 20px ring centres on the line without growing it or moving the label baseline */ :is(.x-plan-head, .x-plan-rowhead-line, .x-plan-chip) > .x-plan-lane > * { align-self: center; margin-block: -2px; } .x-plan-note { border: 1px solid var(--x-text); background: var(--x-surface); color: var(--x-text); } −/* the pin is a filled ink dot like its .x-pop-num twin in the card, with no numeral, so it never reads as a note; it − shows on the selected mark only while the card docks under the board, and the client then skips the pin it would − draw beside the anchor. Until then the slot is empty and boxless, so it takes no room and adds no gap. */ −.x-plan-pin { display: contents; background: none; border: 0; } −.x-stage.is-dock-below :is(.is-selected, .is-step-active) > .x-plan-lane > .x-plan-pin, −.x-stage.is-dock-below :is(.is-selected, .is-step-active) > :is(.x-plan-line, .x-plan-rowhead-line) > .x-plan-lane > .x-plan-pin { display: grid; place-items: center; } −.x-stage.is-dock-below :is(.is-selected, .is-step-active) > .x-plan-lane > .x-plan-pin::before, −.x-stage.is-dock-below :is(.is-selected, .is-step-active) > :is(.x-plan-line, .x-plan-rowhead-line) > .x-plan-lane > .x-plan-pin::before { − content: ""; width: 12px; height: 12px; border-radius: 50%; background: var(--x-text); −} html[data-view="bare"] .x-plan-note { display: none; } /* ---------- kanban: lanes share rows, so heads and first cards line up; lanes never narrower than 180px ---------- */
skills/explainer/scripts/engine/figure/index.ts+10 −10, 6 hunks
@@ -19,7 +19,7 @@ const NODE_KINDS: readonly NodeKind[] = ["actor", "service", "store", "external"
const EDGE_KINDS: readonly EdgeKind[] = ["flow", "return", "async", "link"]; const GROUP_KINDS = ["zone", "trust"] as const; /** The generic reach facts every node gets; layouts with a fact of their own (hub, tree, cycle…) drop them. */ −const REACH = new Set(["Downstream", "Upstream", "In a loop with", "Leads out to", "Comes in from"]); +const REACH = new Set(["Leads on to", "Reached from", "In a loop with", "Leads out to", "Comes in from"]); const FIGURE_KEYS = ["id", "layout", "title", "grid", "nodes", "edges", "groups", "scenes", "legend", ...READING_KEYS]; const SEQUENCE_KEYS = [...FIGURE_KEYS, "actors", "messages"]; const NODE_KEYS = ["label", "sub", "at", "span", "kind", "focal", "about", "tags"];
@@ -314,7 +314,7 @@ type Card = { related?: string[]; facts?: (Fact | null)[]; links?: Link[]; conte
/** * Relations in reading order, what comes in before what goes out, in the author's words: "confirms ←" Payment provider, − * "charges card →" Payment provider. An unlabelled connector gets a bare arrow, never an invented verb. + * "charges card →" Payment provider. An unlabelled connector says only "From" or "To", never an invented verb. * Connectors with the same words share a row. */ function verbLinks(outs: EdgeSpec[], ins: EdgeSpec[]): Link[] {
@@ -323,8 +323,8 @@ function verbLinks(outs: EdgeSpec[], ins: EdgeSpec[]): Link[] {
const ids = rows.get(rel) ?? []; if (!ids.includes(id)) rows.set(rel, [...ids, id]); }; − for (const e of ins) put(e.label ? `${e.label} ←` : "←", e.from); − for (const e of outs) put(e.label ? `${e.label} →` : "→", e.to); + for (const e of ins) put(e.label ? `${e.label} ←` : "From", e.from); + for (const e of outs) put(e.label ? `${e.label} →` : "To", e.to); return [...rows].map(([rel, ids]) => ({ rel, ids })); }
@@ -396,8 +396,8 @@ function layoutCards(block: Figure): Map<string, Card> {
] // a count that only repeats the relation chips below it says nothing: reach shows once it goes past them : [ − far.size ? { k: "Downstream", v: plural(d.size, "part") } : null, − u.size > new Set(ins(n.id).map((e) => e.from)).size ? { k: "Upstream", v: plural(u.size, "part") } : null, + far.size ? { k: "Leads on to", v: plural(d.size, "part") } : null, + u.size > new Set(ins(n.id).map((e) => e.from)).size ? { k: "Reached from", v: plural(u.size, "part") } : null, ], }); }
@@ -424,12 +424,12 @@ function layoutCards(block: Figure): Map<string, Card> {
facts: [ { k: "Parts inside", v: String(inner.size) }, crossIn.length ? null : { k: "Reachable from outside", v: "nothing" }, − { k: "Crossing edges", v: `${crossIn.length} in, ${crossOut.length} out` }, + { k: "Connectors across its border", v: `${crossIn.length} in, ${crossOut.length} out` }, ], }); for (const id of inner) { const crossing = [...crossIn, ...crossOut].filter((e) => e.from === id || e.to === id).length; − card(id, { context: [g.id], facts: [crossing && block.layout === "zones" ? { k: `Crosses ${g.label}`, v: plural(crossing, "connector") } : null] }); + card(id, { context: [g.id], facts: [crossing && block.layout === "zones" ? { k: `Crosses the ${g.label} border`, v: plural(crossing, "connector") } : null] }); } } for (const n of block.nodes) {
@@ -496,8 +496,8 @@ function layoutCards(block: Figure): Map<string, Card> {
pos: `level ${ancestors.length + 1} of ${depth}`, links: [{ rel: "Parent", ids: ancestors.slice(-1) }, { rel: kids.length === 1 ? "Child" : "Children", ids: kids }], facts: [ − { k: "Descendants", v: String(subtree.size) }, − ...(ancestors.length ? [] : kids.map((k) => ({ k: label(k), v: plural(down(k).size, "descendant"), ref: k }))), + { k: "Parts below it", v: String(subtree.size) }, + ...(ancestors.length ? [] : kids.map((k) => ({ k: label(k), v: `${plural(down(k).size, "part")} below`, ref: k }))), ], }); const c = cards.get(n.id)!;
skills/explainer/scripts/engine/structures/swimlane.ts+3 −2, 1 hunk
@@ -501,8 +501,9 @@ export const blockModule: BlockModule<SwimlaneBlock> = {
id: l.id, label: l.label, figure: block.id, kind: "lane", about: l.about, members, facts: [ { k: "Steps", v: String(members.length) }, − into.length ? { k: "Handoffs in", v: String(into.length) } : null, − out.length ? { k: "Handoffs out", v: String(out.length) } : null, + // a count only adds something when one lane hands over more than once; otherwise the chips below say it + into.length > uniq(into.map((e) => laneOf(e.from))).length ? { k: "Handoffs in", v: String(into.length) } : null, + out.length > uniq(out.map((e) => laneOf(e.to))).length ? { k: "Handoffs out", v: String(out.length) } : null, ].filter((f): f is Fact => !!f), links: [ { rel: "Steps", ids: members },
skills/explainer/scripts/engine/structures/uml.ts+1 −1, 1 hunk
@@ -429,7 +429,7 @@ export const blockModule: BlockModule<UmlBlock> = {
HIERARCHY.has(r.kind) && { k: "Inherits", v: membersOf(byId.get(head) as UmlClass).map((m) => m.text).join(", ") || "nothing shown" }, ]; const e: ElementInfo = { id: r.id, type: "edge", label: r.title, kind: r.kind, figure: block.id, from: r.from, to: r.to, about: r.about, facts: factList(facts), say: r.title }; − if (r.fromMult && r.toMult) e.value = `${r.fromMult} to ${r.toMult}`; + // multiplicity reads in full in its fact ("0..* Order to 1 Customer"); a bare "0..* to 1" above it would say it twice if (r.set) e.related = [r.set]; elements[r.id] = e; }
skills/explainer/scripts/engine/plans/journey.ts+1 −1, 1 hunk
@@ -235,7 +235,7 @@ export const blockModule: BlockModule<JourneyBlock> = {
const alias = new Map((block.sentiment?.points ?? []).map((p, i) => [p.id, block.stages[i].id])); const markers = noteMarks(block.notes, drawn, alias); // the marker lane: note markers and the docked card's pin; after a head's label, floated into a card's first line − const note = (id: string) => `<span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"></span>${markers.get(id) ?? ""}</span>`; + const note = (id: string) => `<span class="x-plan-lane" aria-hidden="true">${markers.get(id) ?? ""}</span>`; const parts = [CORNER]; block.stages.forEach((s, i) => { parts.push(mark({ id: s.id, label: s.label, cls: "x-board-head x-plan-head x-journey-stage", attrs: ` data-nav="0,${i}"` }, `<span class="x-mark-shape x-plan-head-label">${esc(s.label)}</span>${note(s.id)}`, true));
skills/explainer/scripts/engine/plans/kanban.ts+1 −1, 1 hunk
@@ -193,7 +193,7 @@ export const blockModule: BlockModule<KanbanBlock> = {
const tagId = new Map(block.tags.map((t) => [t.label, t.id])); const markers = noteMarks(block.notes, new Set([...block.columns.map((c) => c.id), ...block.cards.map((c) => c.id)])); // the marker lane: note markers and the docked card's pin; a head lists it after the count, a card floats it into its first line − const lane = (id: string) => `<span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"></span>${markers.get(id) ?? ""}</span>`; + const lane = (id: string) => `<span class="x-plan-lane" aria-hidden="true">${markers.get(id) ?? ""}</span>`; // a tag is drawn as one chip per card; only its first chip holds the pin, so a selected tag shows one const pinned = new Set<string>(); const chipLane = (id: string) => (pinned.has(id) ? "" : (pinned.add(id), lane(id)));
skills/explainer/scripts/engine/plans/storymap.ts+1 −1, 1 hunk
@@ -187,7 +187,7 @@ export const blockModule: BlockModule<StorymapBlock> = {
const drawn = new Set([...block.activities.map((a) => a.id), ...block.steps.map((st) => st.id), ...block.releases.map((r) => r.id), ...block.stories.map((k) => k.id)]); const markers = noteMarks(block.notes, drawn); // the marker lane: note markers and the docked card's pin; after a head's label, floated into a card's first line − const note = (id: string) => `<span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"></span>${markers.get(id) ?? ""}</span>`; + const note = (id: string) => `<span class="x-plan-lane" aria-hidden="true">${markers.get(id) ?? ""}</span>`; const parts = [CORNER]; let col = 0; for (const a of block.activities) {
skills/explainer/references/interactions.md+4 −4, 2 hunks
@@ -54,16 +54,16 @@ The values are theme tokens (`--x-dim-fill`, `--x-dim-stroke`, `--x-dim-sat`, `-
## The card −A click opens a card inside the figure, next to the element, with a thin leader line to it (a caret when they nearly touch). It never covers the selected element, and it tries hard not to cover what the selection lights up or any label: when no spot beside the element is clear, it docks in a right gutter (the plot shrinks a little, its layout doesn't change) or under the figure, marked with a filled ink dot at the element and the same dot in the card. The dot has no numeral: numbers on the canvas are always the author's notes. On screens under 640px it always docks under the figure. Its position depends only on the layout and the window width, so `shot` always shows the same card. +A click opens a card inside the figure, next to the element, with a thin leader line to it (a caret when they nearly touch). It never covers the selected element, and it tries hard not to cover what the selection lights up or any label: when no spot beside the element is clear, it docks in a right gutter (the plot shrinks a little, its layout doesn't change) or under the figure. A docked card draws no marker of its own: the ink ring already shows what it is about, and the card's title names it. On screens under 640px it always docks under the figure. Its position depends only on the layout and the window width, so `shot` always shows the same card. What it shows, top to bottom: - **Eyebrow:** the kind in the legend's words, plus a position: `BAR · 5 OF 7`, `DATA STORE`, `TASK · CRITICAL`. - **Breadcrumb** for nested things (`Data › Primary database`), then the **title**. A connector's title is its two ends, each a chip. - **Value** with its unit, never a repeat of the title. −- **Facts:** up to 5 computed rows (rank, share, delta, slack, conversion). A fact that names another element is a chip that selects it. When a reading-panel note points at the element, it comes first as "Note n". +- **Facts:** up to 5 computed rows (rank, share, delta, slack, conversion). A fact that names another element is a chip that selects it. When a reading-panel note points at the element, it comes first as "Note n". Each thing is said once: a fact that repeats the value, the kind in the eyebrow, the `about` sentence or the chips below it is left out, so a reader who just joined never reads a line twice. A value too long for the rest of its line moves under its key rather than squeeze it. - **About:** the author's text. −- **Relations** as labelled chip groups: the engine's semantic groups ("Waits for", "Flows to", "Referenced by"), or else the connectors in reading order: **In** holds "Source → verb", **Out** holds "verb → Target". Chips wrap; nothing is truncated. +- **Relations:** the engine's semantic groups ("Waits for", "Flows to", "Referenced by"), or else the connectors in reading order, in the author's words ("confirms ←", "charges card →"; an unlabelled one says "From" or "To"). A relation to one part is one row, words left and chip right; several parts under the same words share a heading over their chips. A relation to only the breadcrumb or an edge's own ends is left out. Chips wrap; nothing is truncated. - **Mentioned in text:** up to two linked sentences (full view). A click scrolls to the sentence and flashes it. - **Actions:** ‹ Back (after following a chip; up to 8 steps), Compare, Hide (series with a legend entry), Copy link, Play from here (when the element is in a scene).
@@ -186,7 +186,7 @@ Any block may accept these. Parse them with the kit so every block reads them th
| `.x-pop` | last child of `.x-stage` | The in-figure card, `role=dialog` | | `.x-scroll` | first child of `.x-stage` | The horizontal scroller around the svg or board; the card and leader sit outside it, so it never clips them | | `.x-sel-layer`, `.x-sel-ring` | last group of the svg | Ring clones for the selection. `.x-sel-under` is the bg gap under a ring; lines and filled paths get `.x-sel-halo` + `.x-sel-clone` / `.x-sel-outline` (also `.x-sel-ring`). Variants: `.x-ring-cmp` (dashed), `.x-ring-hover` (1px dashed) | −| `.x-leader` | svg overlay in `.x-stage` | The leader line and dot, the caret, or the dock marker ❶ | +| `.x-leader` | svg overlay in `.x-stage` | The leader line and dot, or the caret | | `.x-anchor` | a part inside a mark | Where the card and note markers point. Fallbacks: a connector's label, else the middle of its path; a series line's end; a wide bar's value end, a tall bar's top; else the bbox of `.x-mark-shape` or `.x-node-box`. An id with no mark of its own points at the union of its members' marks | | `.x-on-sel`, `.x-on-rel`, `.x-on-hover` | children of a mark | Hidden until the mark is selected, related or hovered | | `.x-ref-line`, `.x-ref-rule`, `.x-ref-label` | svg group | Reference line from `refLine`, `data-axis` x or y. Not `.x-ref`, which is a prose reference link |
skills/explainer/references/layouts.md+3 −3, 3 hunks
@@ -10,7 +10,7 @@ What the router guarantees, and what it warns about instead of drawing badly:
- Connectors sharing a side are ordered by where they head, so a route that turns up takes the upper slot. Two routes share a gutter lane unless their runs overlap. - A label sits beside its own line, at least 8px from every other connector and zone border. When the only free spot is on another line, `check` warns (`edge-label`): move the nodes apart rather than accept a hidden line. - A `decision` node is a diamond, and its connectors leave from its vertices: sideways only to a node on its own row, from the top or bottom vertex otherwise. It has room for a short label and no `sub`. −- The layout also sets the card. Selecting a part shows its relations in the author's words, in reading order ("confirms ←", "charges card →"). Unlabelled connectors get a bare arrow, never an invented verb. The facts under the title are computed per layout; each section below lists them. +- The layout also sets the card. Selecting a part shows its relations in the author's words, in reading order ("confirms ←", "charges card →"). Unlabelled connectors say only "From" or "To", never an invented verb. A relation to one part is one row; several parts under the same words share a heading. A fact the value, the kind or the chips already say is left out, so every line of the card is new. The facts under the title are computed per layout; each section below lists them. Every layout takes `notes:` (up to 4 `{on: id, text}`; `on` may be a node, a group or a connector id such as `orders->payments`) and `caveat:`. The notes are numbered on the figure and listed beside it in the expanded view.
@@ -26,7 +26,7 @@ row 2 [Orders DB]
- **Pattern:** the main path runs left to right on one row. Side effects (stores, background jobs) hang below the node that causes them, and external calls sit at the far right. - **Budget:** 4–5 nodes on the main row, 1–3 off it. −- **Card:** what comes in and what goes out, how many parts are downstream and upstream. Parts two or more hops downstream stay undimmed, which answers "what breaks if this is down". A connector names its paired reverse connector. +- **Card:** what comes in and what goes out, and how many parts it leads on to and is reached from ("Leads on to 6 parts"). Parts two or more hops downstream stay undimmed, which answers "what breaks if this is down". A connector names its paired reverse connector. - **Anti-patterns:** - Snaking the path back across rows. - Putting every store on the main row.
@@ -132,7 +132,7 @@ row 2 [Cart] [Search] [Catalog] [Reports]
- **Pattern:** the root is centred on row 0 (span it if it needs width), with children on the next row under their parent. Each parent drops one bus to its children: a line means "contains", so it has no arrowhead and isn't selectable. Levels get tags L1, L2… in the left margin. - **Budget:** at most 3 levels, and 4 children per parent. −- **Card:** selecting a part lights its ancestors and its whole subtree, shows the ancestors as a breadcrumb, and counts descendants. The root lists each top-level branch with its size. +- **Card:** selecting a part lights its ancestors and its whole subtree, shows the ancestors as a breadcrumb, and counts the parts below it. The root lists each top-level branch with its size. - **Anti-patterns:** - Cross-links between branches: that's a flow, so switch layouts. - Leaves that only restate their parent.
skills/explainer/scripts/tests/client.test.ts+29 −1, 2 hunks
@@ -5,7 +5,7 @@ import {
storyFrame, toCsv, type State, } from "../client/client.ts"; import { composite, contrast, DIM_MIN, pickInk, saturate, type Rgb, type Rgba } from "../client/ink.ts"; −import { cardData, compareData, fmtDelta, parseNum, relationGroups } from "../client/popover.ts"; +import { cardData, compareData, fmtDelta, parseNum, relationGroups, sayOnce } from "../client/popover.ts"; const node = (id: string, label: string, kind = "service"): ElementInfo => ({ id, type: "node", label, kind, figure: "auth" }); const edge = (from: string, to: string, kind = "flow", label = ""): ElementInfo => ({
@@ -241,6 +241,34 @@ describe("card: content", () => {
test("unknown id", () => { expect(cardData(model, "nope")).toBeNull(); }); + test("each thing once: no fact repeats the value, the kind, a heading or the chips under it", () => { + const chips = (...t: string[]) => t.map((x) => ({ id: x.toLowerCase(), text: x })); + const { facts, groups } = sayOnce("2 cards", "Column · 1 of 4", [ + { k: "Load", v: "2 cards" }, // the value again + { k: "Kind", v: "column" }, // the eyebrow again + { k: "Steps", v: "2" }, // the heading of the chips below + { k: "Critical", v: "Search and Browse aisles" }, // the chips below, as a sentence + { k: "Blocked", v: "none" }, // new: kept + ], [{ rel: "Steps", chips: chips("Search", "Browse aisles") }]); + expect(facts).toEqual([{ k: "Blocked", v: "none" }]); + expect(groups.map((g) => g.rel)).toEqual(["Steps"]); + }); + test("chips the facts already link to, or the value spells out, go", () => { + const linked = sayOnce("", "Node", [{ k: "Web", v: "1 part below", ref: "web" }], [{ rel: "Children", chips: [{ id: "web", text: "Web" }] }]); + expect(linked.groups).toEqual([]); + expect(linked.facts).toHaveLength(1); + const other = sayOnce("", "Task", [{ k: "Ends", v: "1 d before Public launch", ref: "launch" }], [{ rel: "Blocks", chips: [{ id: "launch", text: "Public launch" }] }]); + expect(other.groups.map((g) => g.rel)).toEqual(["Blocks"]); // linked for another reason: the relation stays + // one chip under unrelated words does not stand for a fact that happens to name the same part + const reach = sayOnce("", "State", [{ k: "Can no longer reach", v: "Cart" }], [{ rel: "checks out ←", chips: [{ id: "cart", text: "Cart" }] }]); + expect(reach.facts).toHaveLength(1); + const crit = sayOnce("", "Group", [{ k: "Critical", v: "Public launch" }], [{ rel: "On the critical path", chips: [{ id: "l", text: "Public launch" }] }]); + expect(crit.facts).toEqual([]); + // a value that only shares the words, in another case, keeps the chip: "sends call 1" is not the Call 1 column + expect(sayOnce("sends call 1", "Message", [], [{ rel: "Sends context", chips: [{ id: "c1", text: "Call 1" }] }]).groups).toHaveLength(1); + const spelled = sayOnce("orders.user_id → users.id", "Foreign key", [], [{ rel: "References", chips: [{ id: "u", text: "users.id" }] }]); + expect(spelled.groups).toEqual([]); + }); }); describe("compare", () => {
skills/explainer/scripts/tests/plans-boards.test.ts+11 −11, 5 hunks
@@ -116,7 +116,7 @@ describe("kanban", () => {
test("blocked card shows a danger dot and the word blocked; tags are chips that are marks", () => { const { html, elements } = build(kanban, board); expect(html).toContain(`<span class="x-plan-dot" data-tone="danger"></span>blocked`); − expect(html).toContain(`<span class="x-mark x-plan-chip x-kanban-tag" data-id="sprint-tag-search"><span class="x-mark-shape x-plan-chip-label">search</span><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"></span></span></span>`); + expect(html).toContain(`<span class="x-mark x-plan-chip x-kanban-tag" data-id="sprint-tag-search"><span class="x-mark-shape x-plan-chip-label">search</span><span class="x-plan-lane" aria-hidden="true"></span></span>`); expect(elements["sprint-password-reset"].related).toEqual(["sprint-doing"]); expect(elements["sprint-password-reset"].value).toBe("blocked"); expect(html).toMatch(/data-id="sprint-password-reset"[^>]*data-blocked="true" data-nav="2,1"/);
@@ -155,8 +155,8 @@ describe("kanban", () => {
]); expect(html).toMatch(/class="x-note-marker x-plan-note" data-note="2" data-for="sprint-board-password-reset-by-sms"/); // markers get a lane inside the mark: after a head's count, and floated into a card's first line ahead of its title − expect(html).toMatch(/data-id="sprint-board-review"[^>]*><span class="x-mark-shape x-plan-head-label">Review<\/span><span class="x-kanban-facts">.*?<span class="x-plan-count">4 \/ 3<\/span><\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="1"/); − expect(html).toMatch(/data-id="sprint-board-password-reset-by-sms"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="2"[^>]*>2<\/span><\/span><span class="x-mark-shape x-card-label">Password reset by SMS</); + expect(html).toMatch(/data-id="sprint-board-review"[^>]*><span class="x-mark-shape x-plan-head-label">Review<\/span><span class="x-kanban-facts">.*?<span class="x-plan-count">4 \/ 3<\/span><\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="1"/); + expect(html).toMatch(/data-id="sprint-board-password-reset-by-sms"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="2"[^>]*>2<\/span><\/span><span class="x-mark-shape x-card-label">Password reset by SMS</); // a tag repeats across cards, so only its first chip holds the pin slot expect(html.match(/data-id="sprint-board-tag-checkout"/g)!.length).toBe(4); expect(html.match(/data-id="sprint-board-tag-checkout"><span class="x-mark-shape x-plan-chip-label">checkout<\/span><span class="x-plan-lane"/g)!.length).toBe(1);
@@ -281,10 +281,10 @@ describe("journey", () => {
expect(html).toContain('class="x-journey-zero"'); // note 1 targets the focal cell first; note 2 targets a point, so it sits on that stage's head expect(html).toMatch(/data-id="switch-plan-doing-set-up"[^>]*>[^]*?data-note="1"/); − expect(html).toMatch(/data-id="switch-plan-first-bill"[^>]*><span class="x-mark-shape x-plan-head-label">First bill<\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="2"/); − expect(html).toMatch(/data-id="switch-plan-doing-set-up"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="1"[^>]*>1<\/span><\/span><span class="x-mark-shape x-card-label">/); + expect(html).toMatch(/data-id="switch-plan-first-bill"[^>]*><span class="x-mark-shape x-plan-head-label">First bill<\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="2"/); + expect(html).toMatch(/data-id="switch-plan-doing-set-up"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="1"[^>]*>1<\/span><\/span><span class="x-mark-shape x-card-label">/); // a row label keeps its lane on the label's line, above the sub line − expect(html).toMatch(/data-id="switch-plan-sentiment"[^>]*><span class="x-plan-rowhead-line"><span class="x-mark-shape x-plan-rowhead-label">Sentiment<\/span><span class="x-plan-lane"[^>]*><span class="x-plan-pin"><\/span><\/span><\/span><span class="x-plan-rowhead-sub">/); + expect(html).toMatch(/data-id="switch-plan-sentiment"[^>]*><span class="x-plan-rowhead-line"><span class="x-mark-shape x-plan-rowhead-label">Sentiment<\/span><span class="x-plan-lane"[^>]*><\/span><\/span><span class="x-plan-rowhead-sub">/); expect(journey.table!(build(journey, trip).block)).toEqual({ head: ["Stage", "Doing", "Thinking", "Sentiment", "Pains"], rows: [["Discover", "Sees an ad", "Is it cheaper?", "+1", ""], ["Compare", "Reads reviews", "", "0", ""], ["Sign up", "Fills the form", "Hope this is quick", "−2", "Form times out"]],
@@ -388,8 +388,8 @@ describe("storymap", () => {
expect(warnings).toEqual([]); expect(html).toContain('data-cols="8"'); expect(elements["grocery-map-mvp"].value).toBe("8 stories · covers 8 of 8 steps"); − expect(html).toMatch(/data-id="grocery-map-mvp"[^>]*><span class="x-plan-rowhead-line"><span class="x-mark-shape x-plan-rowhead-label">MVP<\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="1"/); − expect(html).toMatch(/data-id="grocery-map-same-day-slots"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-plan-pin"><\/span><span class="x-note-marker x-plan-note" data-note="2"[^>]*>2<\/span><\/span><span class="x-mark-shape x-card-label">Same-day slots</); + expect(html).toMatch(/data-id="grocery-map-mvp"[^>]*><span class="x-plan-rowhead-line"><span class="x-mark-shape x-plan-rowhead-label">MVP<\/span><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="1"/); + expect(html).toMatch(/data-id="grocery-map-same-day-slots"[^>]*><span class="x-plan-line"><span class="x-plan-lane" aria-hidden="true"><span class="x-note-marker x-plan-note" data-note="2"[^>]*>2<\/span><\/span><span class="x-mark-shape x-card-label">Same-day slots</); const wide = { id: "wide", activities: [{ label: "All", steps: Array.from({ length: 9 }, (_, i) => `Step ${i}`) }], releases: [{ label: "One", stories: { "Step 0": ["A"] } }, { label: "Two" }] }; const more: Diagnostic[] = []; build(storymap, wide, more);
@@ -451,12 +451,12 @@ describe("plans-boards.css", () => {
expect(text).not.toContain("overflow-wrap: anywhere; }"); }); − test("markers sit in a lane, never on a border; the pin shares it; related chips step up to line-strong", async () => { + test("markers sit in a lane, never on a border; related chips step up to line-strong", async () => { const text = await css; − const note = text.match(/\.x-plan-note,\s*\.x-plan-pin \{[^}]*\}/)![0]; + const note = text.match(/\.x-plan-note \{[^}]*\}/)![0]; expect(note).not.toMatch(/position: absolute|top:|left:/); expect(text).toContain(".x-plan-card > .x-plan-line > .x-plan-lane { float: right;"); − expect(text).toMatch(/\.x-stage\.is-dock-below [^{]*> \.x-plan-pin \{ display: grid; place-items: center; \}/); + expect(text).not.toContain("x-plan-pin"); expect(text).not.toContain('content: "1"'); expect(text).not.toContain("x-leader-num"); expect(text).toContain(".x-plan-chip.x-mark.is-related { border-color: var(--x-line-strong); color: var(--x-text); }");
skills/explainer/scripts/tests/figure.test.ts+36 −10, 6 hunks
@@ -329,6 +329,32 @@ describe("router: review findings", () => {Box diagrams
}); }); +describe("render: a line and its label belong to what they touch", () => { + const threads = { + id: "t", grid: [4, 3], + nodes: { + user: { label: "User", at: [0, 1], kind: "actor" }, main: { label: "Main thread", at: [1, 1], focal: true }, + auth: { label: "Auth audit", at: [2, 0] }, bill: { label: "Billing audit", at: [2, 1] }, srch: { label: "Search audit", at: [2, 2] }, + answer: { label: "Report", at: [3, 1] }, + }, + groups: { own: { label: "Separate threads", from: [2, 0], to: [2, 2] } }, + edges: ["user -> main", { "main -> auth": "spawn_subagent" }, "main -> bill", "main -> srch", { "auth --> main": "result" }, "main -> answer"], + }; + test("a connector through a zone neither end is in warns, naming the zone", () => { + const { ctx, warnings } = context(); + renderFigure(figure(threads, ctx), ctx); + expect(warnings.some((w) => w.rule === "route" && w.message.includes('main -> answer runs through the "Separate threads" zone'))).toBe(true); + }); + test("a label as close to another line as to its own warns; a reply beside its call does not", () => { + const { ctx, warnings } = context(); + renderFigure(figure(threads, ctx), ctx); + expect(warnings.some((w) => w.rule === "edge-label" && w.message.includes('"spawn_subagent"') && w.message.includes("wrong line"))).toBe(true); + const pair = context(); + renderFigure(figure(sampleFigure, pair.ctx), pair.ctx); + expect(pair.warnings.filter((w) => w.message.includes("wrong line"))).toEqual([]); + }); +}); + describe("render: review findings", () => { const crossing = (edges: string[]) => ({ id: "x", grid: [3, 3],
@@ -418,10 +444,10 @@ describe("model: relations per layout", () => {
expect(new Set(els.api!.related)).toEqual(new Set(["app", "auth", "billing", "app->api", "api->auth", "api->billing"])); expect(els.api).toMatchObject({ crumb: ["app"], pos: "level 2 of 3", links: [{ rel: "Parent", ids: ["app"] }, { rel: "Children", ids: ["auth", "billing"] }] }); expect(els.app!.facts).toEqual([ − { k: "Descendants", v: "7" }, − { k: "Web client", v: "1 descendant", ref: "web" }, − { k: "API", v: "2 descendants", ref: "api" }, − { k: "Workers", v: "1 descendant", ref: "workers" }, + { k: "Parts below it", v: "7" }, + { k: "Web client", v: "1 part below", ref: "web" }, + { k: "API", v: "2 parts below", ref: "api" }, + { k: "Workers", v: "1 part below", ref: "workers" }, ]); expect(els.api!.context).toBeUndefined(); });
@@ -436,11 +462,11 @@ describe("model: relations per layout", () => {
{ rel: "Crossing in from API gateway", ids: ["catalog", "cart", "orders"] }, { rel: "Crossing out from Orders", ids: ["payments"] }, ]); − expect(els.private!.facts).toEqual([{ k: "Parts inside", v: "5" }, { k: "Crossing edges", v: "3 in, 1 out" }]); + expect(els.private!.facts).toEqual([{ k: "Parts inside", v: "5" }, { k: "Connectors across its border", v: "3 in, 1 out" }]); expect(els.private!.kind).toBe("trust boundary"); expect(els.orders).toMatchObject({ crumb: ["private"], kind: "service" }); expect(els.orders!.context).toContain("private"); − expect(els.orders!.facts).toContainEqual({ k: "Crosses Private network", v: "2 connectors" }); + expect(els.orders!.facts).toContainEqual({ k: "Crosses the Private network border", v: "2 connectors" }); }); test("flow: relations in reading order in the author's words, what comes in first", () => {
@@ -450,10 +476,10 @@ describe("model: relations per layout", () => {
edges: ["shop -> checkout", "checkout => pay: charges card", "pay --> checkout: confirms", "checkout -> db: saves order", "checkout ~> mail: queues receipt"], })); expect(els.checkout!.links).toEqual([ − { rel: "←", ids: ["shop"] }, { rel: "confirms ←", ids: ["pay"] }, + { rel: "From", ids: ["shop"] }, { rel: "confirms ←", ids: ["pay"] }, { rel: "charges card →", ids: ["pay"] }, { rel: "saves order →", ids: ["db"] }, { rel: "queues receipt →", ids: ["mail"] }, ]); − expect(els.shop!.facts).toEqual([{ k: "Downstream", v: "4 parts" }]); + expect(els.shop!.facts).toEqual([{ k: "Leads on to", v: "4 parts" }]); expect(els.shop!.context).toEqual(expect.arrayContaining(["pay", "db", "mail"])); expect(els["checkout->pay"]).toMatchObject({ kind: "link", links: [{ rel: "Paired with", ids: ["pay->checkout"] }] }); expect(els.pay!.kind).toBe("external");
@@ -468,7 +494,7 @@ describe("model: relations per layout", () => {
expect(els.model!.facts).toEqual([{ k: "In a loop with", v: "3 parts" }, { k: "Leads out to", v: "2 parts" }, { k: "Comes in from", v: "2 parts" }]); expect(els.model!.links).toContainEqual({ rel: "In a loop with", ids: expect.arrayContaining(["ctx", "check", "tools"]) }); // done --> user closes a round trip through a reply, which does not make User part of a loop − expect(els.user!.facts).toEqual([{ k: "Downstream", v: "5 parts" }, { k: "Upstream", v: "5 parts" }]); + expect(els.user!.facts).toEqual([{ k: "Leads on to", v: "5 parts" }, { k: "Reached from", v: "5 parts" }]); }); test("hub: satellites keep their peers at rest instead of lighting them", () => {
@@ -504,7 +530,7 @@ describe("model: relations per layout", () => {
nodes: { ship: { label: "Ship", at: [0, 0] }, measure: { label: "Measure", at: [1, 0] }, learn: { label: "Learn", at: [1, 1] }, decide: { label: "Decide", at: [0, 1] } }, edges: ["ship -> measure", "measure -> learn: spots trends", "learn -> decide", "decide -> ship"], })); − expect(els.learn).toMatchObject({ kind: "phase", pos: "3 / 4", links: [{ rel: "spots trends ←", ids: ["measure"] }, { rel: "→", ids: ["decide"] }] }); + expect(els.learn).toMatchObject({ kind: "phase", pos: "3 / 4", links: [{ rel: "spots trends ←", ids: ["measure"] }, { rel: "To", ids: ["decide"] }] }); expect(els.learn!.facts).toBeUndefined(); });

Gantt plans

skills/explainer/scripts/engine/plans/gantt.ts+13 −3, 5 hunks
@@ -183,6 +183,9 @@ function freeSpans(blocked: [number, number][], lo: number, hi: number): [number
return out; } +/** How far a dependency's vertical run may leave the gap between its two bars to find a free column. */ +const DETOUR_MAX = 96; + /** The free x nearest to [lo, hi] (the leftmost one inside it when there is one). */ function pickX(free: [number, number][], lo: number, hi: number): { x: number; span: [number, number] } | undefined { const [tlo, thi] = lo <= hi ? [lo, hi] : [hi, lo];
@@ -589,9 +592,15 @@ export const blockModule: BlockModule<GanttBlock> = {
const blocked = lanes.slice(Math.min(ia, ib) + 1, Math.max(ia, ib)).flatMap((l) => l.xs); const lo = xa + STUB, hi = xb - ENTRY; let pick = pickX(freeSpans(blocked, minX, maxX), lo, hi); + const off = (p: { x: number }) => Math.max(Math.min(lo, hi) - p.x, p.x - Math.max(lo, hi), 0); if (!pick) { blockedRoutes++; pick = { x: lo <= hi ? lo : hi, span: [minX, maxX] }; + } else if (off(pick) > DETOUR_MAX) { + // A free column far from both bars sends the arrow on a long trip that crosses the whole chart and bunches + // with every other detour there. Beyond DETOUR_MAX it runs straight down beside its own bars instead, + // over the bars between on a halo of canvas, which reads as passing over them rather than joining them. + pick = { x: lo <= hi ? lo : hi, span: [minX, maxX] }; } const clash = (vx: number) => verticals.some((v) => v.from !== p.id && v.to !== s.id && Math.abs(v.x - vx) < 3 && Math.min(v.y1, v.y2) < Math.max(ya, yb) && Math.min(ya, yb) < Math.max(v.y1, v.y2));
@@ -610,7 +619,7 @@ export const blockModule: BlockModule<GanttBlock> = {
} const d = orthoPath(pts), hot = tight(p, s); (hot ? crit : plain).push(`<g class="x-edge x-gantt-edge${hot ? " x-gantt-crit" : ""}" data-id="${esc(edgeId(p.id, s.id))}" data-from="${esc(p.id)}" data-to="${esc(s.id)}" data-kind="flow"${hot ? ` data-critical="true"` : ""}>` + − `<path class="x-edge-line" d="${d}" marker-end="url(#${esc(b.id)}-arrow)"/><path class="x-edge-hit" d="${d}"/></g>`); + `<path class="x-gantt-halo" d="${d}"/><path class="x-edge-line" d="${d}" marker-end="url(#${esc(b.id)}-arrow)"/><path class="x-edge-hit" d="${d}"/></g>`); } } if (blockedRoutes) {
@@ -740,7 +749,8 @@ export const blockModule: BlockModule<GanttBlock> = {
width: WIDTH, height, defs: deps ? arrowDefs(b.id) : undefined, − body: axis + refs + groupMarks + plain.join("") + crit.join("") + taskMarks + today + legend + markers, + // connectors over the bars: one that runs past a bar shows passing over it on its halo, never hidden beneath + body: axis + refs + groupMarks + taskMarks + plain.join("") + crit.join("") + today + legend + markers, }); },
@@ -806,7 +816,7 @@ export const blockModule: BlockModule<GanttBlock> = {
{ k: "Tasks", v: String(members.length) }, { k: "Length", v: days(hi - lo) }, { k: "Critical", v: onPath.length ? names(onPath) : "none" }, − ...(done !== undefined ? [{ k: "Done", v: `${pct(done * 100)} of the tracked days`, raw: Math.round(done * 100) }] : []), + ...(done !== undefined ? [{ k: "Done", v: `${pct(done * 100)} of its planned days`, raw: Math.round(done * 100) }] : []), ], links: [{ rel: "On the critical path", ids: onPath }], say: `${g.label}, ${members.length} tasks, ${spanLabel(lo, hi, years)}`,
skills/explainer/scripts/styles/blocks/plans-time.css+3 −0, 1 hunk
@@ -30,6 +30,9 @@
.x-gantt-task .x-anchor { fill: none; stroke: none; pointer-events: none; } .x-gantt-date { pointer-events: none; } +/* a connector runs over the bars on a band of canvas, so where it passes a bar it reads as passing, not joining */ +.x-gantt-halo { fill: none; stroke: var(--x-bg); stroke-width: 5; stroke-linejoin: round; pointer-events: none; } + /* critical path: ink connectors at rest, the key swatch matches */ .x-gantt-crit .x-edge-line { stroke: var(--x-text); stroke-width: 1.75; } .x-gantt-crit-key .x-gantt-key-line { stroke: var(--x-text); stroke-width: 1.75; stroke-linecap: round; }
skills/explainer/references/blocks/plans-time.md+1 −1, 1 hunk
@@ -33,7 +33,7 @@ Dates: `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Ticks switch between days, weeks, mont
- critical connectors in ink at rest, and a "Critical path" key that selects `<id>-critical` (link it from prose: `[critical path](#launch-critical)`); - a dashed slack box after every linked bar with float, labelled with its days as the card writes them ("6 d"), moved aside when today or a mark crosses the middle. It shows while the task is selected, and always in the full view, where note markers keep off it; −- connectors that never pass behind a bar, phase span or diamond they don't join. They turn in the 8px gutters between rows and take the nearest clear column. If no clear column exists, `check` warns (`route`); +- connectors drawn over the bars, each on a halo of canvas, so none ever hides behind a bar. They turn in the 8px gutters between rows and take the nearest clear column within 96px of the gap between their two bars; past that they run straight down beside their own bars and pass over the ones between on the halo, rather than cross the chart to a free column. If no column is clear even there, `check` warns (`route`); - milestone dates in the first spot that clears every connector (right of the diamond by default, with room kept for it); - bars without `progress`, in a chart where other tasks have it, as outlines, so unstarted work never looks finished; - a selectable today marker, `<id>-today`: late tasks, tasks in progress, what starts next.
skills/explainer/scripts/tests/plans-time.test.ts+10 −29, 4 hunks
@@ -38,21 +38,8 @@ function crosses(a: Pt, b: Pt, box: Box, inset = 0.5): boolean {
return t0 < t1; } −/** Painted shapes of gantt tasks and phase spans by id. */ −function ganttShapes(html: string): Map<string, Box> { − const out = new Map<string, Box>(); − for (const m of html.matchAll(/<g class="x-mark x-gantt-(?:task|group)[^"]*" data-id="([^"]+)"[^>]*>([\s\S]*?)(?=<g class="x-mark |<g class="x-edge|<g class="x-legend|<g class="x-notes|<\/svg>)/g)) { − const r = /<rect class="x-mark-shape[^"]*" x="([\d.-]+)" y="([\d.-]+)" width="([\d.-]+)" height="([\d.-]+)"/.exec(m[2]); − if (r) { out.set(m[1], { x: +r[1], y: +r[2], w: +r[3], h: +r[4] }); continue; } − const pts = pairs(/<path class="x-mark-shape" d="([^"]+)"/.exec(m[2])![1]); − const xs = pts.map((q) => q[0]), ys = pts.map((q) => q[1]); − out.set(m[1], { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) }); − } − return out; −} − const ganttEdges = (html: string) => − [...html.matchAll(/<g class="x-edge[^"]*" data-id="[^"]+" data-from="([^"]+)" data-to="([^"]+)"[^>]*><path class="x-edge-line" d="([^"]+)"/g)] + [...html.matchAll(/<g class="x-edge[^"]*" data-id="[^"]+" data-from="([^"]+)" data-to="([^"]+)"[^>]*>(?:<path class="x-gantt-halo" d="[^"]+"\/>)?<path class="x-edge-line" d="([^"]+)"/g)] .map((m) => ({ from: m[1], to: m[2], pts: pairs(m[3]) })); function dateBoxes(html: string): Box[] {
@@ -63,18 +50,6 @@ function dateBoxes(html: string): Box[] {
}); } −/** Connectors that run through a bar, span or diamond they don't join. */ −function barCrossings(html: string): string[] { − const shapes = ganttShapes(html), out: string[] = []; − for (const e of ganttEdges(html)) { − for (const [id, box] of shapes) { − if (id === e.from || id === e.to) continue; − for (let i = 1; i < e.pts.length; i++) if (crosses(e.pts[i - 1], e.pts[i], box)) { out.push(`${e.from}->${e.to} × ${id}`); break; } − } − } − return out; −} − /** Milestone dates that touch any connector. */ function dateCrossings(html: string): number { let n = 0;
@@ -303,12 +278,19 @@ describe("gantt", () => {
} }); − test("connectors never run behind a bar, phase span or diamond they don't join", async () => { + test("connectors stay beside their own bars: over a bar they pass on a halo, drawn above the bars, never behind", async () => { const warnings: Diagnostic[] = []; const c = makeCtx(warnings); const html = gantt.render(gantt.normalize(await templateBlock("gantt", "gantt"), c), c); expect(ganttEdges(html).length).toBe(10); − expect(barCrossings(html)).toEqual([]); + // every connector is drawn after the last bar, each on its own halo + expect(html.lastIndexOf('class="x-mark x-gantt-task')).toBeLessThan(html.indexOf('class="x-edge x-gantt-edge')); + expect(html.match(/class="x-gantt-halo"/g)!.length).toBe(10); + // no vertical run leaves the gap between its two bars by more than DETOUR_MAX (96px): no trips across the chart + for (const e of ganttEdges(html)) { + const xs = e.pts.map(([x]) => x); + expect(Math.max(...xs) - Math.min(...xs)).toBeLessThan(96 + 200); + } const w = Number(/viewBox="0 0 ([\d.]+) /.exec(html)![1]); for (const e of ganttEdges(html)) for (const [x] of e.pts) expect(x >= 0 && x <= w).toBe(true); expect(warnings).toEqual([]); // no "route" warning: every connector found a clear column
@@ -328,7 +310,6 @@ describe("gantt", () => {
const kick = gantt.render(gantt.normalize(raw("gantt", d), k), k); expect(dateBoxes(kick).length).toBe(2); expect(dateCrossings(kick)).toBe(0); − expect(barCrossings(kick)).toEqual([]); }); test("reading line and data table", async () => {

Box diagrams

skills/explainer/scripts/engine/figure/route.ts+16 −3, 5 hunks
@@ -1,4 +1,4 @@
−import type { FigureBlock, NodeSpec, Theme } from "../types.ts"; +import type { FigureBlock, GroupSpec, NodeSpec, Theme } from "../types.ts"; import { cellRect, figureSize, groupRect, inflate, overlaps, segmentBox, type Rect } from "./grid.ts"; export type Point = [number, number];
@@ -22,6 +22,8 @@ const BORDER_CLEAR = 6;
/** Route cost: a bend costs this much length, a crossing much more, the outer ring more still. */ const BEND_COST = 24; const CROSS_COST = 160; +/** A route through a zone neither of its ends sits in reads as if it belonged there: dearer than a crossing. */ +const ZONE_COST = 240; const OUTER_COST = OUTER * 2; const VERTICAL_FIRST: readonly string[] = ["tree", "layers", "states"];
@@ -151,7 +153,15 @@ export function routeEdges(fig: FigureBlock, theme: Theme, boxes?: Map<string, R
return attach; }; − // Route choice: the cheapest clear plan, where length, bends, crossings with other routes and the outer ring all cost. + // Zones a connector may pass through: the ones either end sits in. Any other zone it enters costs ZONE_COST. + const zoneRects = fig.groups.map((g) => ({ g, r: inflate(groupRect(g.from, g.to, theme), -BORDER_CLEAR) })); + const within = (n: NodeSpec, g: GroupSpec) => n.at[0] >= g.from[0] && n.at[0] <= g.to[0] && n.at[1] >= g.from[1] && n.at[1] <= g.to[1]; + const entered = (points: Point[], from: string, to: string) => zoneRects.filter(({ g, r }) => + !within(nodes.get(from)!, g) && !within(nodes.get(to)!, g) && points.slice(1).some((b, i) => overlaps(segmentBox(points[i], b), r))); + const trespass = (points: Point[], from: string, to: string) => entered(points, from, to).length; + + // Route choice: the cheapest clear plan, where length, bends, crossings with other routes, zones it has no end in + // and the outer ring all cost. const choose = (attach: Map<string, Point>, others: Map<string, Point[]>, crossCost: number) => { const chosen = new Map<string, { plan: Plan; clean: boolean; points: Point[] }>(); for (const e of fig.edges) {
@@ -163,7 +173,7 @@ export function routeEdges(fig: FigureBlock, theme: Theme, boxes?: Map<string, R
plans.forEach((plan, i) => { const points = plan.build(channelCenter); if (!isClear(points, reserved, [e.from, e.to])) return; − const score = length(points) + BEND_COST * (points.length - 2) + crossCost * crossings(points, drawn) + (plan.outer ? OUTER_COST : 0) + i * 1e-3; + const score = length(points) + BEND_COST * (points.length - 2) + crossCost * crossings(points, drawn) + ZONE_COST * trespass(points, e.from, e.to) + (plan.outer ? OUTER_COST : 0) + i * 1e-3; if (!best || score < best.score) best = { plan, points, score }; }); const pick: { plan: Plan; points: Point[] } = best ?? { plan: plans[0], points: plans[0].build(channelCenter) };
@@ -249,6 +259,9 @@ export function routeEdges(fig: FigureBlock, theme: Theme, boxes?: Map<string, R
if (retry) points = retry; else warn(e.id, `Connector ${e.from} -> ${e.to} shares a crowded gutter and touches a node; spread the nodes apart.`); } + for (const { g } of entered(points, e.from, e.to)) { + warn(e.id, `Connector ${e.from} -> ${e.to} runs through the "${g.label}" zone although neither end is in it, so it reads as part of that zone; move a node so the path goes around it.`); + } const w = warns.get(e.id); return w ? { id: e.id, points, warn: w.join(" ") } : { id: e.id, points }; });
skills/explainer/scripts/engine/figure/render.ts+25 −8, 5 hunks
@@ -11,6 +11,8 @@ const LABEL_GAP = 8;
/** A label keeps this far from every other connector and border; the second pass settles for LABEL_NEAR. */ const LABEL_CLEAR = 8; const LABEL_NEAR = 3; +/** Well past LABEL_GAP: another connector this far off is plainly not the one the label sits beside. */ +const LABEL_OWN = 28; const CORNER = 8; const HOP = 4; const HOP_MARGIN = CORNER + HOP + 2;
@@ -156,12 +158,17 @@ function draw(fig: FigureBlock & ReadingSpec, ctx: RenderContext): { html: strin
fig.edges.forEach((e, i) => { const pts = routes[i].points; if (pts.length < 2 || !e.label) return; − const others = lines.filter((_, j) => j !== i).flat().concat(borders); − const placed = placeLabel(e.label, pts, theme, nodeBoxes, masks, others); + // The reply that runs back beside a call is read as a pair, one label on each outer side, so it never makes a + // label ambiguous; any other connector near the label does. + const pair = (j: number) => fig.edges[j].from === e.to && fig.edges[j].to === e.from; + const placed = placeLabel(e.label, pts, theme, nodeBoxes, masks, lines.filter((_, j) => j !== i).flat().concat(borders), lines.filter((_, j) => j !== i && !pair(j)).flat()); if (!placed) { ctx.warn({ rule: "edge-label", severity: "warn", line: fig.line, message: `Connector label "${e.label}" on ${e.from} -> ${e.to} has no room; shorten it or move the nodes apart.` }); return; } + if (placed.shared) { + ctx.warn({ rule: "edge-label", severity: "warn", line: fig.line, message: `Connector label "${e.label}" on ${e.from} -> ${e.to} sits about as close to another connector as to its own, so a reader may pin it on the wrong line; move the nodes apart or drop the label.` }); + } if (placed.covers) { ctx.warn({ rule: "edge-label", severity: "warn", line: fig.line, message: `Connector label "${e.label}" on ${e.from} -> ${e.to} can only sit on top of another connector; move the nodes apart so both stay visible.` }); }
@@ -380,10 +387,10 @@ function hopsFor(edges: EdgeSpec[], routes: Point[][]): Map<number, Map<number,
/** * Spots beside the connector's own runs: centred first, then slid toward either end. The first pass keeps − * LABEL_CLEAR from every other connector and border, the second LABEL_NEAR; only then does a mask sit on a line + * LABEL_OWN from every other connector and border, the second LABEL_CLEAR, the third LABEL_NEAR; only then does a mask sit on a line * (`covers`), and the caller warns. */ −function placeLabel(text: string, pts: Point[], theme: Theme, nodes: Rect[], masks: Rect[], lines: Rect[]): { box: Rect; covers: boolean } | null { +function placeLabel(text: string, pts: Point[], theme: Theme, nodes: Rect[], masks: Rect[], lines: Rect[], connectors: Rect[] = lines): { box: Rect; covers: boolean; shared?: boolean } | null { // Sans at the edge-label size: the mask pads the label at rest and still covers it when it turns semibold on selection. const tw = textWidth(text, theme.type.edgeLabel, "sans"); const w = Math.max(tw + 2 * MASK_PAD, boldWidth(text, theme.type.edgeLabel) + 2);
@@ -408,8 +415,15 @@ function placeLabel(text: string, pts: Point[], theme: Theme, nodes: Rect[], mas
} const fits = (r: Rect) => !nodes.some((o) => overlaps(r, o)) && !masks.some((o) => overlaps(r, o)); const clear = (d: number) => (r: Rect) => fits(r) && !lines.some((l) => overlaps(inflate(r, d), l)); − const box = spots.find(clear(LABEL_CLEAR)) ?? spots.find(clear(LABEL_NEAR)); − if (box) return { box, covers: false }; + // First a spot no other line comes near (LABEL_OWN), so the label can only be read as its own line's; a label + // equally close to two lines names the wrong one half the time. + // Only connectors count here: a zone border is not something a label could be read as naming. + // Only runs parallel to the label's own count: a label beside a vertical line is not misread as naming a + // horizontal one that passes above it. + const upright = new Set(spots.slice(horizontal.length * SLIDE.length * 2)); + const near = (r: Rect) => connectors.some((l) => (upright.has(r) ? l.w === 0 && l.h > 0 : l.h === 0 && l.w > 0) && overlaps(inflate(r, LABEL_OWN), l)); + const box = spots.find((r) => clear(LABEL_CLEAR)(r) && !near(r)) ?? spots.find(clear(LABEL_CLEAR)) ?? spots.find((r) => clear(LABEL_NEAR)(r) && !near(r)) ?? spots.find(clear(LABEL_NEAR)); + if (box) return { box, covers: false, shared: near(box) }; const fallback = spots.find(fits); return fallback ? { box: fallback, covers: true } : null; }
@@ -423,10 +437,13 @@ export function legendSvg(used: LegendKinds, theme: Theme, left: number, right:
const diamond = (x: number, cy: number) => `<polygon class="x-legend-swatch" points="${num(x + 8)},${num(cy - 6)} ${num(x + 16)},${num(cy)} ${num(x + 8)},${num(cy + 6)} ${num(x)},${num(cy)}"/>`; const line = (x: number, cy: number) => `<line class="x-legend-line" x1="${num(x)}" y1="${num(cy)}" x2="${num(x + 16)}" y2="${num(cy)}"/>`; const items: { kind: string; label: string; mark: (x: number, cy: number) => string }[] = [ − ...NODE_ORDER.filter((k) => used.nodeKinds.has(k)).map((k) => ({ kind: k, label: nodeWord(layout, k), mark: k === "decision" ? diamond : swatch })), + // A plain box needs no key unless the layout gives it a word of its own (a state, a phase), and one line style + // needs none either: a key earns its place by telling two looks apart. + ...NODE_ORDER.filter((k) => used.nodeKinds.has(k) && (k !== "service" || nodeWord(layout, k) !== NODE_WORDS.service)).map((k) => ({ kind: k, label: nodeWord(layout, k), mark: k === "decision" ? diamond : swatch })), ...(used.focal ? [{ kind: "focal", label: "focal", mark: swatch }] : []), − ...EDGE_ORDER.filter((k) => used.edgeKinds.has(k)).map((k) => ({ kind: k, label: edgeWord(layout, k), mark: line })), + ...(used.edgeKinds.size > 1 ? EDGE_ORDER.filter((k) => used.edgeKinds.has(k)).map((k) => ({ kind: k, label: edgeWord(layout, k), mark: line })) : []), ]; + if (!items.length) return { svg: "", height: 0 }; const parts = [`<line class="x-legend-rule" x1="${num(left)}" y1="${num(top)}" x2="${num(right)}" y2="${num(top)}"/>`]; let x = left, row = 0; for (const it of items) {

Numbered notes

skills/explainer/scripts/engine/kit.ts+13 −2, 2 hunks
@@ -606,6 +606,15 @@ export const NOTE_R = 10;
/** The label size a number or tag renders at when the caller passes no theme size. */ const SMALL = 13; +/** What a marker nearer another mark than its own target costs: more than a sliver of overlap, less than covering a label. */ +const AMBIGUOUS = 120; + +/** Distance from a point to the nearest edge of a frame; 0 inside it. */ +function gap(x: number, y: number, f: Frame): number { + const dx = Math.max(f.x - x, 0, x - f.x - f.w), dy = Math.max(f.y - y, 0, y - f.y - f.h); + return Math.hypot(dx, dy); +} + function overlap(a: Frame, b: Frame): number { const w = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x); const h = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
@@ -641,8 +650,10 @@ export function notes(block: { id?: string; notes?: NoteSpec[] }, anchors: Recor
const b = opts.bounds; let score = b && (box.x < b.x || box.y < b.y || box.x + box.w > b.x + b.w || box.y + box.h > b.y + b.h) ? 1000 : 0; score += overlap(box, a); − // every other mark with an anchor is in the way too: a marker never sits on a mark − for (const [id, o] of Object.entries(anchors)) if (id !== target) score += overlap(box, o); + // every other mark with an anchor is in the way too: a marker never sits on a mark, and a spot nearer another + // mark than its own target reads as that mark's note + const own = gap(cx, cy, a); + for (const [id, o] of Object.entries(anchors)) if (id !== target) score += overlap(box, o) + (gap(cx, cy, o) < own ? AMBIGUOUS : 0); for (const o of opts.obstacles ?? []) score += overlap(box, o); for (const p of placed) score += 3 * overlap(box, p); if (score < bestScore) { best = [cx, cy]; bestScore = score; }

Chart colours

skills/explainer/themes/default.json+6 −6, 1 hunk
@@ -91,23 +91,23 @@
"series": { "light": [ "#3E6F92", − "#C08A3E", "#4F8B6F", "#8B5E9E", "#5C8C9A", − "#A3747F", "#8C8A4A", − "#6E7489" + "#6E7489", + "#A3747F", + "#C08A3E" ], "dark": [ "#7FA8C9", − "#D9A864", "#7FB89A", "#B892C8", "#88B6C2", − "#CC9AA5", "#B8B574", − "#9DA3B8" + "#9DA3B8", + "#CC9AA5", + "#D9A864" ] }, "type": {
skills/explainer/scripts/tests/theme.test.ts+19 −0, 1 hunk
@@ -285,3 +285,22 @@ describe("base.css", () => {
expect(used.filter((v) => !defined.has(v))).toEqual([]); }); }); + +describe("series against the accent", () => { + // Hue in degrees from a #rrggbb colour: enough to tell orange from amber from blue. + const hue = (hex: string) => { + const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255); + const max = Math.max(r, g, b), d = max - Math.min(r, g, b); + if (!d) return 0; + const h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4; + return (h * 60 + 360) % 360; + }; + const apart = (a: number, b: number) => Math.min(Math.abs(a - b), 360 - Math.abs(a - b)); + test("the first four series hues stay well clear of the accent, so a series never reads as focal", async () => { + const theme = await loadTheme(DEFAULT_FILE); + for (const mode of ["light", "dark"] as Mode[]) { + const accent = hue(theme.colors[mode].accent); + for (const c of theme.series[mode].slice(0, 4)) expect(apart(hue(c), accent)).toBeGreaterThanOrEqual(45); + } + }); +});
skills/explainer/scripts/tests/charts-grids.test.ts+4 −4, 2 hunks
@@ -237,8 +237,8 @@ describe("treemap", () => {
test("on-fill ink per palette slot and for the focal accent", () => { const { html } = contract(treemap, tree, "spend"); − // slot 2 (Data, ochre) needs dark text in light mode and surface in dark − expect(html).toMatch(/data-id="spend-database" data-series="2"[^>]*data-ink="ts"/); + // slot 2 (Data, green) needs black ink in light mode, where neither text nor surface reaches AA, and surface in dark + expect(html).toMatch(/data-id="spend-database" data-series="2"[^>]*data-ink="ks"/); expect(html).toMatch(/data-id="spend-api" data-series="1" data-focal="true"[^>]*data-ink="ss"/); });
@@ -400,8 +400,8 @@ describe("on-fill ink", () => {
expect([0, 1, 2, 3, 4, 5, 6].map((l) => rampInk(theme, l))).toEqual( [" data-ink=\"tt\"", " data-ink=\"tt\"", " data-ink=\"tt\"", " data-ink=\"tt\"", " data-ink=\"tw\"", " data-ink=\"ks\"", " data-ink=\"ss\""], ); − expect(seriesInk(theme, 2)).toBe(' data-ink="ts"'); − expect(seriesInk(theme, 3)).toBe(' data-ink="ks"'); + expect(seriesInk(theme, 2)).toBe(' data-ink="ks"'); + expect(seriesInk(theme, 4)).toBe(' data-ink="ts"'); expect(accentInk(theme)).toBe(' data-ink="ss"'); }); });

The page check

Version and listing

README.md+1 −1, 1 hunk
@@ -5,7 +5,7 @@ Agent Skills by overment. They use the open [Agent Skills](https://agentskills.i
## Skills - **[skill-shaper](skills/skill-shaper/)** creates or reshapes a skill, checked against the skills you already have. It works out the job behind the request, decides whether a skill is the right tool, draws clear boundaries with neighbouring skills, and picks the lightest steering for the task: concepts and guiding questions for judgment work, exact steps for fragile work. −- **[explainer](skills/explainer/)** turns a system, dataset or plan into one self-contained interactive HTML diagram: architecture and flows, sequence and state machines, 18 chart types (bar, line, scatter, waterfall, heatmap, treemap, Sankey and more), Gantt, timelines, kanban, journeys, story maps, database schemas, UML, and incident reports with an annotated timeline. Clicking any part opens its details next to it in the graph and lights the text and panels that talk about it. Every diagram has a bare view and a view with text, light and dark themes, and click-to-explore details. It lints before building, audits the result in Chrome and captures any state as PNG or SVG. Needs Bun. +- **[explainer](skills/explainer/)** turns a system, dataset or plan into one self-contained interactive HTML diagram: architecture and flows, sequence and state machines, 18 chart types (bar, line, scatter, waterfall, heatmap, treemap, Sankey and more), Gantt, timelines, kanban, journeys, story maps, database schemas, UML, and incident reports with an annotated timeline. Clicking any part opens its details next to it in the graph, each fact said once and each relation on one line, and lights the text and panels that talk about it. Every diagram has a bare view and a view with text, light and dark themes, and click-to-explore details. It lints before building, audits the result in Chrome and captures any state as PNG or SVG. Needs Bun. ## Install
skills/explainer/SKILL.md+1 −1, 1 hunk
@@ -5,7 +5,7 @@ description: >-
license: MIT (bundled Geist fonts under OFL-1.1, see assets/fonts/OFL.txt) metadata: author: overment − version: "0.4.0" + version: "0.4.1" --- # Explainer