@wxxb789/anc 0.0.1

package/src/scripts/toc-active.js

@@ -0,0 +1,38 @@
+/** Mark the section currently crossing the reading offset in the static TOC. */
+export {};
+const links = [...document.querySelectorAll('.toc a[href^="#"]')];
+const targets = links.flatMap((link) => {
+    const id = decodeURIComponent(link.hash.slice(1));
+    const heading = document.getElementById(id);
+    return heading instanceof HTMLElement ? [{ heading, link }] : [];
+});
+if (targets.length > 0) {
+    let frame;
+    const update = () => {
+        frame = undefined;
+        const scrollPadding = Number.parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 0;
+        const offset = Math.min(scrollPadding + 1, window.innerHeight / 3);
+        let active = targets[0];
+        for (const target of targets) {
+            if (target.heading.getBoundingClientRect().top > offset)
+                break;
+            active = target;
+        }
+        for (const target of targets) {
+            if (target === active)
+                target.link.setAttribute('aria-current', 'location');
+            else
+                target.link.removeAttribute('aria-current');
+        }
+    };
+    const schedule = () => {
+        if (frame === undefined)
+            frame = window.requestAnimationFrame(update);
+    };
+    update();
+    // This static site has no client navigation: one module instance and these
+    // listeners share the document lifetime, so there is no teardown boundary.
+    // Smooth hash navigation emits scroll events throughout its movement.
+    window.addEventListener('scroll', schedule, { passive: true });
+    window.addEventListener('resize', schedule, { passive: true });
+}

package/src/styles/code.css

@@ -0,0 +1,152 @@
+/*
+ * Syntax highlighting, loaded only by pages that contain a code fence.
+ *
+ * Split out of `global.css` rather than merged into it because owner decision 7
+ * makes every heavy asset load per page and per invocation, and `token-*` is the
+ * first asset that qualifies: it is the largest single block of rendered-Markdown
+ * CSS and it is dead weight on the many notes with no code in them.
+ * `RenderedNote.hasCode` is the gate, and `src/pages/notes/[slug].astro` emits
+ * the `<link>` only when it is true. TK-15 adds the math and Mermaid sheets
+ * behind `hasMath` and `hasMermaid` through the same mechanism.
+ *
+ * Only the `token-*` map moved. `.code-block` stays in `global.css`: a Mermaid
+ * fence also renders as `figure.code-block` while setting `hasMermaid` rather
+ * than `hasCode`, so gating the figure's own rules on `hasCode` would ship an
+ * unstyled block on a diagram-only page. Nothing emits a `token-*` span except
+ * the highlighter, which never runs for Mermaid or math, so this file's gate is
+ * exact.
+ *
+ * Every colour is a token declared in `tokens.css`, which the global stylesheet
+ * has already loaded by the time this one applies. `tests/design-tokens.test.ts`
+ * measures both syntax hues on all three backgrounds in both themes.
+ */
+
+/*
+ * Prism's token vocabulary is open-ended and this maps it onto four roles, not
+ * onto Prism's own names: keywords and operators, literals (numbers, booleans,
+ * constants), strings, and comments. Anything unmapped inherits the body colour,
+ * which is a readable default rather than an invisible one — the failure mode
+ * of a highlighting theme should be "less colour", never "no text".
+ *
+ * Colour is never the only signal: comments are italic, keywords are bold. A
+ * reader with any colour vision deficiency, or reading a printed page, still
+ * sees the structure.
+ *
+ * Eight of these names are here because TK-11's fixture corpus produced them
+ * and the published one-note corpus never had: Python, JavaScript, and
+ * PowerShell fences emit `builtin`, `class-name`, `control-flow`, `module`,
+ * `arrow`, `function-variable`, `doc-comment`, and `triple-quoted-string`. Each
+ * is folded into the role it already belongs to rather than given a fifth
+ * colour. Seven of them nest inside an already-mapped token, so only
+ * `token-builtin` changed what a reader sees; the rest close the coverage gate
+ * on a class that could ship alone the day a grammar emits it that way.
+ */
+.token-comment,
+.token-doc-comment,
+.token-prolog,
+.token-doctype,
+.token-cdata {
+  color: var(--color-muted);
+  font-style: italic;
+}
+
+.token-keyword,
+.token-control-flow,
+/* bash grammar spells a for/select loop this way; it is control flow. */
+.token-for-or-select,
+.token-module,
+.token-operator,
+.token-arrow,
+.token-atrule,
+.token-important,
+.token-selector,
+.token-tag {
+  color: var(--color-syntax-keyword);
+  font-weight: 600;
+}
+
+/*
+ * Container tokens, which wrap other tokens rather than marking a leaf: batch's
+ * `command` spans a whole command line with `keyword` nested inside it, and
+ * `namespace` wraps a qualified name. Colouring one paints everything it
+ * contains — a whole command line came out entirely purple — so
+ * they inherit and let the nested token carry the meaning. `inherit` is
+ * declared rather than omitted so the intent is visible and the rule exists.
+ */
+.token-command,
+.token-namespace {
+  color: inherit;
+}
+
+.token-string,
+.token-triple-quoted-string,
+.token-char,
+.token-attr-value,
+.token-regex {
+  color: var(--color-accent);
+}
+
+.token-number,
+.token-boolean,
+.token-constant,
+.token-symbol,
+.token-property,
+.token-attr-name,
+.token-variable,
+.token-parameter,
+.token-function,
+.token-function-variable,
+/* `method` and `property-access` are what Prism calls a function and a field
+   reached through a receiver, in the grammars that distinguish them —
+   JavaScript among them. Both were missing while every fence in this
+   repository's own corpus was `cmd`, which produces neither, so the gate that
+   requires every shipped class to be styled had nothing to catch. Replacing
+   that corpus with one carrying a JavaScript fence is what surfaced them.
+   Grouped with `function` because they are the same things with a dot in
+   front. */
+.token-method,
+.token-property-access,
+.token-builtin,
+.token-class-name {
+  color: var(--color-syntax-literal);
+}
+
+/* Structure, not meaning: punctuation stays body-coloured so it recedes. */
+.token-punctuation,
+.token-entity {
+  color: var(--color-text);
+}
+
+/* Inserted by `code-copy.ts`, so no scripting means no dead control. */
+.code-copy {
+  display: block;
+  margin: 0 0 var(--space-2) auto;
+  padding: var(--space-1) var(--space-2);
+  border: 1px solid var(--color-line-strong);
+  border-radius: var(--radius-sm);
+  background: var(--color-surface);
+  color: var(--color-text);
+  font: inherit;
+  font-size: var(--text-sm);
+  cursor: pointer;
+}
+
+.code-copy:disabled {
+  cursor: wait;
+  opacity: 0.75;
+}
+
+/*
+ * Deliberately unstyled classes are recorded once, in `global.css`'s
+ * "deliberately unstyled" block, which is the list `tests/built-output.test.ts`
+ * reads and asserts against. Restating it here would be a second copy that gate
+ * does not check, and therefore a copy free to drift.
+ *
+ * One thing does belong here, because it is a property of the split rather than
+ * of either file: **no rule in `global.css` may style `.token` or any
+ * `token-*`.** The built `<head>` currently orders this sheet *before* the
+ * layout's, so an equal-specificity rule there would win over every rule above
+ * and repaint the whole token stream in one colour. Nothing styles them there
+ * today, so the order is not load-bearing — but it is the one way this split
+ * could fail silently, and it is why the classes stay together in one file.
+ */

package/src/styles/diagram.css

@@ -0,0 +1,149 @@
+/*
+ * Diagrams.
+ *
+ * Loaded only on pages whose body contains one, via the conditional `<link>` in
+ * `src/pages/notes/[slug].astro` gated on `RenderedNote.hasMermaid` — owner
+ * decision 7. A page with no diagram pays nothing, asserted in both directions
+ * by `tests/math-and-diagrams.test.ts`.
+ *
+ * This is the *whole* diagram stylesheet, in both modes, and it is small on
+ * purpose. `src/lib/mermaid-render.ts` flattens Mermaid's own injected
+ * stylesheet onto the elements as SVG presentation attributes at build time, so
+ * nothing here reproduces Mermaid's theming. The alternative — hoisting that
+ * stylesheet into 23 per-diagram-type files — was rejected on a measurement:
+ * 86% of its rules (1,279 of 1,495) match no element in any rendered diagram,
+ * because Mermaid emits the union of every shape it could draw.
+ *
+ * Colour is likewise absent here. Each diagram carries its own
+ * `light-dark(light, dark)` values, paired at build time from two renders, so
+ * one SVG follows the system preference and the site's own theme toggle with no
+ * second file and no script.
+ */
+
+.diagram {
+  margin-block: var(--space-6);
+  /* `figure` has a user-agent margin-inline of 40px, which would indent the
+     diagram relative to the prose around it. */
+  margin-inline: 0;
+}
+
+/*
+ * The diagram itself.
+ *
+ * The SVG carries a `width` attribute holding its intrinsic size and no
+ * `height`, so `max-width: 100%` lets it shrink to fit a 320 px viewport while
+ * the `viewBox` preserves its aspect ratio. Without `height: auto` a browser
+ * would keep the attribute width's implied height and distort it.
+ */
+.diagram svg {
+  max-width: 100%;
+  height: auto;
+}
+
+/*
+ * The diagram is laid out at 16 px and must render at 16 px.
+ *
+ * Mermaid computes every box from its own measurement of the label text at its
+ * configured `fontSize`, which is 16. This site's body text is `--text-base`,
+ * 1.0625rem — **17 px** — and the labels inherit it, so each one rendered 6%
+ * wider than the box built for it and every multi-word label was visibly
+ * clipped: "Private vault" showed as "Private vaul". Measured in Chromium, not
+ * inferred; the two-thousandths-of-an-em font-metric differences between Arial
+ * and the site's stack are within 2.7% and were *not* the cause.
+ *
+ * Pinning the size here rather than raising Mermaid's is the smaller fix: the
+ * diagram's geometry is baked into the SVG at build time, so the number the
+ * renderer measured with is the only number that can be correct. `px` rather
+ * than `rem` for the same reason — a reader who scales the root font size
+ * scales the whole SVG, which keeps the label inside its box, whereas scaling
+ * only the text would reintroduce exactly this clipping.
+ *
+ * **Restricted to `foreignObject` content.** An SVG `<text>` is deliberately
+ * excluded: those carry their own `font-size` presentation attribute — 12 px on
+ * a radar axis label, 38 px on a treemap label, 32 px on the info banner — which
+ * the flattening pass wrote from Mermaid's own stylesheet, and a class rule
+ * beats a presentation attribute. An earlier version of this rule included
+ * `text` and silently resized 139 elements across seven diagram types. Caught by
+ * comparing computed styles against the unflattened SVG in a real browser.
+ */
+.diagram foreignObject div,
+.diagram foreignObject span {
+  font-size: 16px;
+}
+
+.diagram-canvas {
+  /* A wide diagram scrolls rather than widening the page. Centred, because a
+     diagram narrower than the measure otherwise sits oddly against the text.
+     `tabindex="0"` is on the element itself: a scrollable region must be
+     reachable by keyboard, and the browser then scrolls it with the arrows. */
+  overflow-x: auto;
+  text-align: center;
+}
+
+.diagram-canvas:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+/*
+ * Client mode only: the diagram's source, shown until the runtime replaces it.
+ *
+ * This is also what a reader without JavaScript is left with, which is why it
+ * is styled as a legible code block rather than hidden. Requirements §5.2 and
+ * §5.3 ask for the static baseline to be the product; client mode is a
+ * deliberate carve-out from that, and showing the source is the honest form of
+ * the carve-out — a hidden element would present the same page as complete
+ * while silently missing a figure.
+ */
+.diagram-source {
+  margin: 0;
+  padding: var(--space-4);
+  overflow-x: auto;
+  background: var(--color-surface-alt);
+  border: 1px solid var(--color-line);
+  border-radius: var(--radius-md);
+  font-family: var(--font-mono);
+  font-size: var(--text-sm);
+  line-height: var(--leading-body);
+  color: var(--color-text);
+}
+
+.diagram figcaption {
+  margin-top: var(--space-2);
+  color: var(--color-muted);
+  font-size: var(--text-sm);
+  text-align: center;
+}
+
+/*
+ * Classes the flattening pass writes.
+ *
+ * The six non-presentational declarations that survive flattening, from
+ * `LAYOUT_CLASSES` in `src/lib/mermaid-render.ts`. Every other declaration in
+ * Mermaid's stylesheet is an SVG presentation attribute and is written onto the
+ * element itself, which is why this list is six rules rather than a stylesheet.
+ */
+.diagram-center { text-align: center; }
+.diagram-left { text-align: left; }
+.diagram-start { text-align: start; }
+.diagram-nowrap { white-space: nowrap; }
+.diagram-line { line-height: 1.5; }
+.diagram-blend { mix-blend-mode: multiply; }
+.diagram-table { display: table; }
+
+/*
+ * A diagram's HTML labels live in a `foreignObject`, outside the article's own
+ * cascade for margins: the browser applies the default `p` margin there and
+ * pushes the label off its own centre.
+ */
+.diagram foreignObject p {
+  margin: 0;
+}
+
+@media print {
+  /* A scroll container prints as its visible window, cutting the diagram off at
+     the page edge. Letting it size itself prints the whole figure. */
+  .diagram-canvas {
+    overflow-x: visible;
+  }
+}