feat(library): curated "See also" + "Surprise me" #86

Merged

manlycucumber merged 1 commit from feat/library-cross-links into develop

2026-07-10 22:00:39 +00:00

manlycucumber commented

2026-07-10 21:59:11 +00:00

(Migrated from github.com)

The first half of the Library's connective tissue (v0.3.0 PR2). Extends the tiered-content spine from #85.

What ships

Curated "See also." An additive, optional related: [category/slug] frontmatter field. validateCrossLinks() (pure, in the content plugin's collect()) fails the build on a dangling, gated-out, self-, or duplicate link — and because it runs over the already-gated set, in production it enforces approved → approved, so a "See also" link can never dangle or surface unreviewed content. A host-agnostic SeeAlso.svelte renders the resolved topics as TopicCard links at heading level + 1 (h1→h2 standalone, h2→h3 in-window), so it routes in-window and standalone alike.
"Surprise me." A real random-topic <a>. The href is seeded deterministically (the first topic) so prerender and hydration agree — no Math.random() baked at build — then re-rolled on the client on focus/pointerdown, both of which fire before the click reads the href. So it reuses the existing delegated in-window intercept with zero host branching; base-aware href; renders nothing on an empty catalogue.

Deliberately deferred → PR2b (#35)

Inline prose cross-links and the glossary — the remark-plugin half that rewrites body text — were split out by a 4-lens design review. That half concentrated the risk: a gate value the mdsvex preprocessor can't read, raw-HTML→Svelte brace-escaping, HMR cache invalidation, a {base} assertion, and — most importantly — a doctrine gate for glossary definitions of faith terms plus a toggletip a11y pattern. It gets its own focused review. This turns the 5-PR Library plan into 6.

Also fixed

A latent hover bug: color-mix() was fed the --surface-titlebar gradient (an <image>, not a <color>), which blanks the fill to transparent on hover. Fixed in the new Surprise pill and the pre-existing .lib-back button by mixing against a solid token. Verified in-browser: the corrected mix computes to an opaque colour; the old form to rgba(0,0,0,0).

Design + review trail

Design critique (4 lenses → synthesis) before implementation → the scope re-slice and the must-fix list (deterministic Surprise seed, base-aware href, WCAG 2.5.3 name, SeeAlso heading level+1, build-time related validation).
Adversarial review (4 lenses → per-finding verify) of the implemented diff → 0 correctness bugs in the feature code; confirmed findings were the one hover CSS bug (fixed) and test-coverage gaps on the Surprise re-roll (now closed).

Verification

pnpm build green (all routes prerender, gated); guard:external / content / colour / offline all green — the offline smoke now also pins the prerendered Surprise seed and asserts the "See also" section + its resolved target render in static HTML.
59 unit + 12 e2e pass; svelte-check 0/0; prettier + eslint clean.
e2e cover: standalone See-also; in-window See-also (no navigation, sibling window survives); the Surprise client re-roll to a non-seed pick (stubbed RNG); axe over the Library home. Negative build path proven manually (a bogus related fails the build with a clear message).

Closes the See-also + Surprise-me scope of the v0.3.0 Library milestone.

The first half of the Library's **connective tissue** (v0.3.0 PR2). Extends the tiered-content spine from #85. ## What ships - **Curated "See also."** An additive, optional `related: [category/slug]` frontmatter field. `validateCrossLinks()` (pure, in the content plugin's `collect()`) fails the build on a dangling, gated-out, self-, or duplicate link — and because it runs over the already-gated set, in production it enforces **approved → approved**, so a "See also" link can never dangle or surface unreviewed content. A host-agnostic `SeeAlso.svelte` renders the resolved topics as `TopicCard` links at heading **level + 1** (h1→h2 standalone, h2→h3 in-window), so it routes in-window and standalone alike. - **"Surprise me."** A real random-topic `<a>`. The href is **seeded deterministically** (the first topic) so prerender and hydration agree — no `Math.random()` baked at build — then **re-rolled on the client** on `focus`/`pointerdown`, both of which fire before the click reads the href. So it reuses the existing delegated in-window intercept with zero host branching; base-aware href; renders nothing on an empty catalogue. ## Deliberately deferred → PR2b (#35) Inline prose cross-links and the glossary — the **remark-plugin** half that rewrites body text — were split out by a 4-lens design review. That half concentrated the risk: a gate value the mdsvex preprocessor can't read, raw-HTML→Svelte brace-escaping, HMR cache invalidation, a `{base}` assertion, and — most importantly — **a doctrine gate for glossary definitions of faith terms** plus a toggletip a11y pattern. It gets its own focused review. This turns the 5-PR Library plan into 6. ## Also fixed A latent hover bug: `color-mix()` was fed the `--surface-titlebar` **gradient** (an `<image>`, not a `<color>`), which blanks the fill to transparent on hover. Fixed in the new Surprise pill **and** the pre-existing `.lib-back` button by mixing against a solid token. Verified in-browser: the corrected mix computes to an opaque colour; the old form to `rgba(0,0,0,0)`. ## Design + review trail - **Design critique** (4 lenses → synthesis) before implementation → the scope re-slice and the must-fix list (deterministic Surprise seed, base-aware href, WCAG 2.5.3 name, SeeAlso heading level+1, build-time `related` validation). - **Adversarial review** (4 lenses → per-finding verify) of the implemented diff → **0 correctness bugs in the feature code**; confirmed findings were the one hover CSS bug (fixed) and test-coverage gaps on the Surprise re-roll (now closed). ## Verification - `pnpm build` green (all routes prerender, gated); **guard:external / content / colour / offline** all green — the offline smoke now also pins the **prerendered Surprise seed** and asserts the **"See also"** section + its resolved target render in static HTML. - **59 unit** + **12 e2e** pass; `svelte-check` 0/0; prettier + eslint clean. - e2e cover: standalone See-also; in-window See-also (no navigation, sibling window survives); the Surprise **client re-roll** to a non-seed pick (stubbed RNG); axe over the Library home. Negative build path proven manually (a bogus `related` fails the build with a clear message). Closes the See-also + Surprise-me scope of the v0.3.0 Library milestone.