@wxxb789/anc 0.0.1

package/src/scripts/link-preview.js

@@ -0,0 +1,334 @@
+/**
+ * Hover and focus link previews.
+ *
+ * A preview is a **projection lookup, not a page fetch**. The slug in the link's
+ * path is looked up in the page's bound SQLite snapshot through the shared lazy
+ * Worker, which returns the note's title, excerpt, author-ordered aliases, and
+ * effective language. A link whose target is not in the snapshot previews
+ * nothing, and there is no code path that could read anything else: no page is
+ * fetched, no markup is parsed, and no field outside the snapshot's
+ * `nodes`/`aliases` rows exists to show. That is the
+ * property worth keeping — a scrape-the-target design previews whatever the
+ * anchor happens to point at, which on a privacy projection is a hole rather
+ * than an inconsistency.
+ *
+ * Everything the panel shows is already on the page it links to and in the
+ * public snapshot, so a preview adds speed and never information (requirements
+ * section 14: it never replaces the underlying link). A reader with no pointer,
+ * no scripting, or no interest loses nothing.
+ *
+ * The placement arithmetic and the payload reader live in `preview-model.ts` so
+ * they can be tested without a browser; this file is the event wiring.
+ *
+ * No motion, by construction: the panel appears and disappears with no
+ * transition and no animation, so a reduced-motion reader has nothing to opt out
+ * of. The global `@media (prefers-reduced-motion: reduce)` block in `global.css`
+ * covers anything a later change adds.
+ */
+import { noteSlugFromPath } from "../lib/route-path.js";
+import { placePreview, previewFragment, previewTitle } from "../lib/preview-model.js";
+import { requestPreview } from "./snapshot-client.js";
+/**
+ * Hover intent. Long enough that crossing a link on the way somewhere else costs
+ * nothing, short enough that a reader who paused is not kept waiting.
+ */
+const OPEN_DELAY_MS = 120;
+/**
+ * The grace period between leaving the link and the panel closing.
+ *
+ * WCAG 2.2 SC 1.4.13 requires hover-triggered content to be *hoverable* — the
+ * pointer must be able to reach it, which means crossing the gap between the
+ * link and the panel without it vanishing. It applies only once the panel is
+ * visible; before that, leaving cancels outright, which is what the ticket asks
+ * for and what stops a panel appearing for a link the reader already left.
+ */
+const CLOSE_DELAY_MS = 160;
+const panel = document.querySelector('#link-preview');
+if (panel)
+    install(panel);
+/**
+ * The previewable note behind a link, or nothing.
+ *
+ * The origin comparison, rather than an `href^="/"` selector, is what makes
+ * "same site" true instead of merely likely: `href="//example.com/notes/x/"`
+ * starts with `/` and has a perfectly good-looking note `pathname`, so a prefix
+ * test would hand a third-party origin a preview of one of *our* notes.
+ * Asking for `.origin` puts the question to the browser's own URL parser, and
+ * it also admits an absolute same-origin href, which is public and previewable
+ * and which the prefix selector silently excluded.
+ *
+ * A link to the page already open is **not** previewable, and that guard is
+ * load-bearing rather than tidy. Every `href="#section"` on a note page
+ * resolves to that note's own `pathname`, so without it the table of contents,
+ * all fifteen heading anchors, and — worst — the skip link all preview the note
+ * the reader is currently reading. On the published note page that is 29 such
+ * anchors, and the *first* Tab on the page opened a panel describing the page
+ * itself and pointed the skip link's `aria-describedby` at it. A preview of the
+ * open page is not information, it is noise in front of the one control a
+ * keyboard reader meets first. `tests/rendered-page.test.ts` gates it over the
+ * real anchors on real note pages — counted there rather than trusted from
+ * here, and it fails when this line is deleted.
+ *
+ * The slug comes back with the link rather than being re-derived at display
+ * time. One call to `noteSlugFromPath` is what makes this the single decision
+ * about whether a link is previewable — a second copy downstream would make
+ * each of them look optional, and a check nothing depends on is a check that
+ * gets deleted.
+ */
+function previewTarget(node) {
+    const link = node instanceof Element ? node.closest('a[href]') : undefined;
+    if (!(link instanceof HTMLAnchorElement) || link.origin !== location.origin)
+        return undefined;
+    if (link.pathname === location.pathname)
+        return undefined;
+    // A link inside a `<dialog>` — the modal search dialog — is never previewed.
+    // The panel lives behind the modal, so a preview would be covered by it,
+    // `aria-describedby` would point at an element outside the reader's reach,
+    // and arrowing through results would download the whole SQLite runtime for
+    // nothing. `tests/preview-intent.test.ts` gates both effects.
+    if (link.closest('dialog') !== null)
+        return undefined;
+    // Only a note route carries a previewable slug. Reading the route through the
+    // shared helper is what keeps this from previewing `/tags/<tag>/` as though
+    // the tag were a note, and it means the route model moves in one place.
+    const slug = noteSlugFromPath(link.pathname);
+    return slug === undefined ? undefined : { link, slug };
+}
+function hide(state) {
+    clearTimeout(state.openTimer);
+    clearTimeout(state.closeTimer);
+    state.openTimer = undefined;
+    state.closeTimer = undefined;
+    // Only while the panel is showing. A description pointing at a hidden element
+    // announces nothing, so leaving the attribute behind would tell a screen
+    // reader the link has a description that is not there.
+    state.current?.removeAttribute('aria-describedby');
+    state.current = undefined;
+    state.panel.hidden = true;
+}
+/** Whether an event's target or `relatedTarget` is the panel or inside it. */
+function isInPanel(panel, node) {
+    return node instanceof Node && panel.contains(node);
+}
+/** The pointer came back to the link, or reached the panel. */
+function keep(state) {
+    clearTimeout(state.closeTimer);
+    state.closeTimer = undefined;
+}
+/**
+ * The pointer left. A visible panel gets the grace period; a pending one does
+ * not, so a reader who brushes past a link never sees it open at all.
+ */
+function leave(state) {
+    if (state.current === undefined)
+        return;
+    if (state.panel.hidden)
+        hide(state);
+    else if (state.closeTimer === undefined)
+        state.closeTimer = setTimeout(() => hide(state), CLOSE_DELAY_MS);
+}
+/**
+ * Fill and place the panel for a previewable link, if it is still the one
+ * wanted.
+ *
+ * The re-check after the await is the reason this is not written inline: the
+ * index fetch can resolve long after the pointer has moved on, and without it a
+ * reader who brushed past a link gets a panel for it seconds later, anchored to
+ * a rectangle that may have scrolled away in the meantime.
+ */
+async function show(state, { link, slug }) {
+    let entry;
+    try {
+        entry = (await requestPreview(slug)).preview;
+    }
+    catch {
+        // A failed Worker, fetch, digest, or schema falls back to the static page:
+        // the link stays usable and nothing stale is shown. The client clears its
+        // failed initialization so a later intent can retry.
+        entry = null;
+    }
+    if (state.current !== link)
+        return;
+    if (entry === null) {
+        // Nothing to show: a failed index load, or a slug the projection does not
+        // carry. `current` is released because it means "the link whose preview is
+        // showing or scheduled", and after a miss neither is true. Leaving it set
+        // makes the next `pointerover` on that same link take the "already here"
+        // branch instead of retrying, and the preview never comes back.
+        //
+        // The gesture that reaches it is **moving between a link's own child
+        // elements**. `pointerout` is correctly swallowed — the pointer has not
+        // left the link — but crossing the internal boundary fires a fresh
+        // `pointerover` for the same anchor, and that is the one this releases for.
+        // An earlier version of this comment claimed no such gesture existed; it
+        // was wrong, and the mistake was testing jitter *within* one element, which
+        // fires no events at all. Reproduced on `/notes/accessibility-baseline/`
+        // moving between the collection pager's two spans: without this line the
+        // preview stays dead, with it the crossing re-arms.
+        //
+        // Not hypothetical markup: the collection pager in
+        // `src/pages/notes/[slug].astro` wraps `<span class="pager-direction">`
+        // and `<span class="pager-title">` in every anchor, and the fixture corpus
+        // builds **50** of them. `tests/rendered-page.test.ts` gates it on those
+        // real anchors.
+        state.current = undefined;
+        return;
+    }
+    renderPanel(state.panel, entry, link);
+}
+/**
+ * Fill the panel with a preview entry and place it beside its link.
+ *
+ * Stateless: it reads only its arguments and the document's own geometry and
+ * language, and the caller has already decided the entry is still wanted.
+ */
+function renderPanel(panel, entry, link) {
+    // Text nodes throughout — `textContent`, never `innerHTML` — so every string
+    // from the snapshot stays data and is never parsed as markup.
+    const pageLanguage = document.documentElement.lang || 'en';
+    const markLanguage = (element, language) => {
+        if (language.toLowerCase() !== pageLanguage.toLowerCase())
+            element.lang = language;
+    };
+    const title = document.createElement('strong');
+    title.textContent = previewTitle(entry);
+    markLanguage(title, entry.language);
+    const excerpt = document.createElement('p');
+    excerpt.textContent = entry.excerpt;
+    markLanguage(excerpt, entry.language);
+    const fragment = previewFragment(link.hash);
+    if (fragment === undefined)
+        panel.replaceChildren(title, excerpt);
+    else {
+        // A heading-target link says which section it lands on. The projection
+        // carries nothing per heading, so this is the fragment itself rather than a
+        // de-slugged guess at the heading's prose — see `previewFragment`.
+        const section = document.createElement('span');
+        section.className = 'preview-fragment';
+        section.textContent = fragment;
+        panel.replaceChildren(title, section, excerpt);
+    }
+    // Unhidden before measuring, because a `display: none` element has no size to
+    // measure. Both happen inside this one task, so the browser paints the placed
+    // panel and never the provisional position.
+    panel.hidden = false;
+    const { left, top } = placePreview(link.getBoundingClientRect(), panel.getBoundingClientRect(), {
+        // Not `window.innerWidth`, which counts a classic scrollbar the panel
+        // cannot occupy. `clientWidth`/`clientHeight` are the box a fixed-position
+        // element is laid out in, so the arithmetic and the CSS agree on the edge.
+        width: document.documentElement.clientWidth,
+        height: document.documentElement.clientHeight,
+    });
+    panel.style.left = `${left}px`;
+    panel.style.top = `${top}px`;
+    link.setAttribute('aria-describedby', panel.id);
+}
+/**
+ * Arm the intent delay for a link, replacing whatever was pending.
+ *
+ * The `current === link` branch is the pointer arriving somewhere it already
+ * counts as being — onto a `<code>` or `<em>` inside the link it is already
+ * over, or back from the panel — so it cancels a pending close rather than
+ * restarting the open. Restarting would let a pointer drifting across a link's
+ * inner elements postpone the preview indefinitely.
+ */
+function open(state, target) {
+    if (state.current === target.link) {
+        keep(state);
+        return;
+    }
+    hide(state);
+    state.current = target.link;
+    state.openTimer = setTimeout(() => {
+        state.openTimer = undefined;
+        void show(state, target);
+    }, OPEN_DELAY_MS);
+}
+function install(panel) {
+    const state = { panel, current: undefined, openTimer: undefined, closeTimer: undefined };
+    document.addEventListener('pointerover', (event) => {
+        // Touch raises `pointerover` as part of the tap it precedes, so without this
+        // a tap would flash a panel over the page it is navigating to. A pen hovers
+        // like a mouse and is left alone.
+        if (event.pointerType === 'touch')
+            return;
+        const target = previewTarget(event.target);
+        if (target)
+            open(state, target);
+        else if (isInPanel(panel, event.target))
+            keep(state);
+        else
+            leave(state);
+    });
+    document.addEventListener('pointerout', (event) => {
+        if (event.pointerType === 'touch')
+            return;
+        // Moving deeper into the same link — a `<code>` or `<em>` inside it, or the
+        // collection pager's two spans — is not leaving it, and neither is crossing
+        // onto the panel. `relatedTarget` is the element being entered, and is null
+        // when the pointer leaves the window.
+        //
+        // Belt and braces with `open`'s `keep()`, deliberately. In the ordering
+        // browsers actually use — `pointerout` for the parent, then `pointerover`
+        // for the child — either mechanism alone suffices, and mutation testing
+        // confirms removing either one keeps the gate green. The pair matters for
+        // the opposite ordering: `pointerover` first would call `keep()` with no
+        // timer to clear, and the `pointerout` behind it would then arm a close
+        // while the pointer was still inside the link. One line against an ordering
+        // assumption is cheaper than the flicker it prevents.
+        if (previewTarget(event.relatedTarget)?.link === state.current)
+            return;
+        if (isInPanel(panel, event.relatedTarget))
+            return;
+        leave(state);
+    });
+    // `focusin`/`focusout` rather than `focus`/`blur`: the latter do not bubble, so
+    // a document-level listener would never see them. This is the half Quartz does
+    // not have at all — a keyboard reader tabbing through a backlinks list gets the
+    // same preview a pointer does.
+    //
+    // `:focus-visible` is what keeps this from firing on touch. A tap focuses the
+    // link too, so an unqualified `focusin` would flash a panel over the page the
+    // tap is navigating to — the same defect the `pointerType` guards close on the
+    // pointer path, arriving by the other door. The browser already decides whether
+    // a focus deserves a visible indicator, and that decision is exactly the one
+    // this needs: keyboard yes, touch and mouse no. Reusing it beats tracking the
+    // last input type by hand, and it is the same signal the stylesheet's focus
+    // ring uses, so a reader who sees the ring is the reader who gets the preview.
+    document.addEventListener('focusin', (event) => {
+        const target = previewTarget(event.target);
+        if (target && target.link.matches(':focus-visible'))
+            open(state, target);
+        else
+            hide(state);
+    });
+    document.addEventListener('focusout', (event) => {
+        if (state.current !== undefined && previewTarget(event.target)?.link === state.current)
+            hide(state);
+    });
+    document.addEventListener('keydown', (event) => {
+        // Not `preventDefault`: Escape belongs to the reader. Consuming it would
+        // break the search dialog's own dismissal on a page where both are open, and
+        // dismissing a tooltip is not a reason to take the key away from everything
+        // else.
+        if (event.key === 'Escape' && state.current !== undefined)
+            hide(state);
+    });
+    // `capture`, so a scroll inside any container dismisses rather than leaving the
+    // panel pinned to a rectangle that has moved. Dismissing is cheaper and
+    // steadier than re-placing on every scroll frame, and it is what a reader
+    // expects: they moved the page, so the transient thing went away.
+    //
+    // A *pending* preview is deliberately left armed, and that is not a shortcut.
+    // Tabbing to a link below the fold makes the browser scroll it into view, and
+    // the scroll event lands after `focusin` — so dismissing unconditionally would
+    // cancel the open timer and a keyboard reader would never see a preview for any
+    // link that was off screen. Nothing is stale either way: the panel is placed
+    // from a rectangle read when it is shown, not when it was scheduled.
+    const dismissIfShowing = () => {
+        if (!panel.hidden)
+            hide(state);
+    };
+    window.addEventListener('scroll', dismissIfShowing, { passive: true, capture: true });
+    window.addEventListener('resize', dismissIfShowing, { passive: true });
+}

package/src/scripts/math-disabled.js

@@ -0,0 +1,18 @@
+/**
+ * The math runtime, in the mode that does not have one.
+ *
+ * `astro.config.mjs` aliases `src/scripts/math.ts` to this file whenever
+ * `MATH_MODE` is `'build-time'`. The mode that ships is `'client'`
+ * (`src/lib/math-mode.ts`), so this stub is bundled only when that constant is
+ * flipped. The page's
+ * `<script>` is bundled eagerly by Astro regardless of any condition around it,
+ * so the only way to keep Temml out of `dist/` is to make the module it hangs
+ * from import nothing.
+ *
+ * An empty module rather than a deleted `<script>`: the tag still exists, so the
+ * two modes emit the same page shape, and the difference between them is exactly
+ * one aliased import instead of a divergence in the template. The sibling of
+ * `src/scripts/diagram-disabled.ts`, which documents the same arrangement for
+ * diagrams.
+ */
+export {};

package/src/scripts/math.js

@@ -0,0 +1,133 @@
+/**
+ * Client-mode math rendering.
+ *
+ * Loaded only when `MATH_MODE` is `'client'` and only on pages that contain an
+ * expression. In the shipped mode (`'build-time'`) this file is never imported,
+ * so none of it — and none of Temml — reaches any page. See
+ * `src/lib/math-mode.ts` for what the two modes cost.
+ *
+ * ## What this deliberately does *not* copy from `src/scripts/diagram.ts`
+ *
+ * That file is the template, and two thirds of its machinery is unnecessary
+ * here. Both omissions are measurements rather than judgements:
+ *
+ * 1. **No theme re-rendering.** Mermaid bakes its palette into the SVG at render
+ *    time, so a theme toggle leaves a diagram frozen in the old colours and the
+ *    runtime has to re-run `initialize` and redraw. MathML does not: it inherits
+ *    CSS colour like any other element, and measured, Temml's output carries no
+ *    colour attribute at all except `\rule`'s hardcoded `black` — which
+ *    `src/lib/math.ts` already rewrites to `currentColor` at build time and
+ *    which {@link currentColorRule} applies here for the same reason. A
+ *    `MutationObserver` on `data-theme` would be complexity for nothing.
+ * 2. **No serialized render passes.** The diagram runtime chains its renders
+ *    because Mermaid's `render()` is async and two overlapping passes can
+ *    interleave a half-painted figure. `temml.renderToString` is **synchronous**
+ *    — measured, it returns a `string` rather than a `Promise` — so there is no
+ *    interleaving to prevent and nothing to serialize.
+ *
+ * ## What it does keep, because these are the properties that matter
+ *
+ * 1. **Nothing loads until it is needed.** The import is deferred behind an
+ *    `IntersectionObserver`, so a reader who never scrolls to an expression
+ *    never fetches the ~59 KB gzip.
+ * 2. **The source stays until the MathML replaces it.** The `<code>` the
+ *    renderer emitted is removed only after a successful render, so a failure at
+ *    any point leaves the reader with the TeX rather than an empty span. This is
+ *    load-bearing in a way it is not for diagrams: `src/lib/math.ts` sets
+ *    `throwOnError: true` and a malformed expression aborts the *build*, so
+ *    under client rendering there is no build-time gate at all and a throw would
+ *    otherwise leave the element empty — measured.
+ */
+import { currentColorRules, extractStyles } from "../lib/math-output.js";
+/** Every span the client branch of `mathPlugin` emits, display and inline. */
+const MATH_SELECTOR = 'span.math-display > code.language-math, span.math-inline > code.language-math';
+/** Temml is imported at most once per page, on the first expression in view. */
+let runtime;
+function loadTemml() {
+    runtime ??= import('temml').then((module) => module.default);
+    return runtime;
+}
+/**
+ * Render one expression in place, leaving the source alone if anything fails.
+ *
+ * **Parsed rather than assigned through `innerHTML` on the live element**, so a
+ * failure cannot half-replace the source: the MathML is built in a detached
+ * container first, and only a container that actually produced a `<math>` root
+ * is swapped in. A `parsererror` document still has a root element, so the check
+ * is for the element this expects rather than for "something parsed".
+ */
+function renderInto(host, temml) {
+    const code = host.querySelector('code.language-math');
+    if (code === null)
+        return;
+    const tex = code.textContent ?? '';
+    if (tex.trim() === '')
+        return;
+    let html;
+    try {
+        // `throwOnError` is **off** here, and that is the opposite of the build-time
+        // setting for a reason the two modes do not share. At build time a throw
+        // aborts the build and names the expression, which is the strongest possible
+        // signal. In the browser there is nobody to tell: a throw would leave the
+        // element empty and the reader would lose the expression entirely.
+        //
+        // **And it is not sufficient on its own**, which is why the build-time
+        // validation in `mathPlugin` matters more than this setting does. Measured:
+        // `x^`, `x_`, `^` and `a^^` throw a `TypeError` out of Temml *regardless* of
+        // `throwOnError`, which only governs its own `ParseError` path. Under client
+        // mode those never reach a reader, because `mathPlugin` runs `renderMath` —
+        // with `throwOnError: true` — over every expression at build time, so a
+        // corpus containing one fails the build exactly as it does today.
+        //
+        // What remains for this `catch` is the case that setting cannot cover: a
+        // Temml version whose browser build disagrees with the one that validated,
+        // or an expression that renders at build time and throws in a browser. In
+        // that case the reader keeps the TeX, which is the whole point of the
+        // fallback.
+        html = temml.renderToString(tex, {
+            displayMode: host.classList.contains('math-display'),
+            throwOnError: false,
+            trust: false,
+            maxExpand: 1000,
+            maxSize: [500, 500],
+            annotate: false,
+        });
+    }
+    catch {
+        return;
+    }
+    const container = document.createElement('span');
+    // **`extractStyles` before `innerHTML`, and it is the difference between 0 CSP
+    // violations and one per styled element.** At build time the sanitizer drops
+    // every `style` attribute that survives this call; here there is no sanitizer,
+    // so an unextracted `style` becomes a real attribute and `style-src 'self'`
+    // blocks it. Measured in Chromium under the shipped policy without this call:
+    // `\begin{pmatrix}` violated 4 times, `\begin{aligned}` and `\begin{array}` 4
+    // each, `\boxed` once — none of which are the two commands the received
+    // account named. With it, all four are silent.
+    container.innerHTML = currentColorRules(extractStyles(html));
+    const math = container.querySelector('math');
+    if (math === null)
+        return;
+    // The source is removed only now, which is what makes every `return` above a
+    // safe exit: the reader keeps the TeX in each of them.
+    code.remove();
+    host.append(math);
+}
+const hosts = [...document.querySelectorAll(MATH_SELECTOR)].map((code) => code.parentElement);
+if (hosts.length > 0) {
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (!entry.isIntersecting)
+                continue;
+            observer.unobserve(entry.target);
+            const host = entry.target;
+            void loadTemml().then((temml) => renderInto(host, temml));
+        }
+    }, 
+    // A margin, so an expression just below the fold is typeset before it
+    // arrives rather than visibly swapping under the reader.
+    { rootMargin: '200px' });
+    for (const host of hosts)
+        observer.observe(host);
+}

package/src/scripts/preferences.js

@@ -0,0 +1,123 @@
+/**
+ * Theme and reader-mode toggles.
+ *
+ * Bundled by Astro as an external module, so the built HTML carries no inline
+ * script and no inline event handler. `theme-init.js` has already applied the
+ * stored preferences before paint; this module only handles later changes.
+ *
+ * Both preferences are expressed as one attribute on `<html>` that CSS already
+ * understands, so the toggles are the only JavaScript involved and their
+ * absence degrades to the system theme rather than to a broken page.
+ */
+/* Astro concatenates these scripts into one bundle. An import makes this file a
+   module with its own top-level scope, so TK-06 and TK-07 can each declare
+   `root`, `dialog`, or `preview` without colliding with the other's file. It was
+   a bare `export {}` until TK-16 gave the file a real import. */
+import { THEME_DATASET, THEME_NAMES } from "../lib/translations.js";
+/*
+ * These two keys are also read by `src/scripts/theme-init.js`, which cannot
+ * import them: it must stay a classic, import-free script to load render-
+ * blocking before first paint. Renaming either key here without changing it
+ * there silently orphans the stored preference, so `tests/design-tokens.test.ts`
+ * asserts the two files agree.
+ *
+ * **The prefix names the thing stored, not the tool that stored it**, which is
+ * plan decision D2 applied to the one identifier a reader's own browser keeps.
+ * It was this project's own name and a colon, written into the local storage
+ * of every visitor to every site built with this tool, visible in any
+ * devtools pane. Nothing needed it: `localStorage` is partitioned by origin, so
+ * two sites' keys are already distinct whatever they are called, and the prefix
+ * was buying isolation the platform provides while carrying an identity the
+ * site does not have. `publish:` describes what wrote the value and belongs to
+ * nobody.
+ *
+ * **Deliberately not configurable**, for the reason the plan gives at §4.2:
+ * making it a config key would buy nothing the origin partition does not
+ * already give, and would cost the invariant the gate below holds — that these
+ * two files agree on a literal.
+ */
+const THEME_KEY = 'publish:theme';
+const READER_KEY = 'publish:reader';
+/**
+ * `system` is the absence of a stored value, which is what lets CSS decide.
+ *
+ * Imported rather than restated. This is a *client* module, so an import here
+ * ships whatever it pulls in — but `THEME_NAMES` is a three-string array with no
+ * dependencies, and Rollup tree-shakes the locale tables beside it out of the
+ * bundle. `tests/built-routes.test.ts` proves no chrome string reaches a shipped
+ * script, so the claim is measured rather than assumed.
+ */
+const THEMES = THEME_NAMES;
+const root = document.documentElement;
+/** Storage can be unavailable or full; a failed write must not break the toggle. */
+function persist(key, value) {
+    try {
+        if (value === null)
+            localStorage.removeItem(key);
+        else
+            localStorage.setItem(key, value);
+    }
+    catch {
+        /* Preference is not persisted; the current page still reflects the choice. */
+    }
+}
+function currentTheme() {
+    const value = root.dataset.theme;
+    return THEMES.includes(value) ? value : 'system';
+}
+/**
+ * The label carries the state in text, not only in the rendered colours.
+ *
+ * The three labels are read off the button's own `data-label-*` attributes,
+ * which `Layout.astro` filled from the translation resolved for *this document*
+ * — so a Chinese note's toggle cycles "主题：跟随系统 / 浅色 / 深色" and an
+ * English one cycles "Theme: system / light / dark", from one shared script.
+ * TK-16 could have shipped a locale table in the bundle instead; that would put
+ * both languages on the wire for every reader and grow with each language added,
+ * to say the same words the server already knew. The fallback keeps the toggle
+ * operable rather than blank if the markup and this file ever disagree.
+ */
+function showTheme(theme, button) {
+    button.textContent = button.dataset[THEME_DATASET[theme]] ?? theme;
+}
+function showReader(on, button) {
+    button.setAttribute('aria-pressed', String(on));
+}
+function applyTheme(theme, button) {
+    if (theme === 'system')
+        delete root.dataset.theme;
+    else
+        root.dataset.theme = theme;
+    persist(THEME_KEY, theme === 'system' ? null : theme);
+    showTheme(theme, button);
+}
+function applyReader(on, button) {
+    if (on)
+        root.dataset.reader = 'on';
+    else
+        delete root.dataset.reader;
+    persist(READER_KEY, on ? 'on' : null);
+    showReader(on, button);
+}
+/*
+ * The initial sync only reads. `currentTheme()` reflects the DOM, not storage,
+ * so if `theme-init.js` failed to load — a stale cached page against a rotated
+ * asset hash, an extension, a CDN miss — it reports `system`. Routing that
+ * through `applyTheme` would call `removeItem` and destroy a preference the
+ * user actually set, rather than merely failing to apply it this once.
+ */
+const themeButton = document.querySelector('#theme-toggle');
+if (themeButton) {
+    showTheme(currentTheme(), themeButton);
+    themeButton.addEventListener('click', () => {
+        const next = THEMES[(THEMES.indexOf(currentTheme()) + 1) % THEMES.length] ?? 'system';
+        applyTheme(next, themeButton);
+    });
+}
+const readerButton = document.querySelector('#reader-toggle');
+if (readerButton) {
+    showReader(root.dataset.reader === 'on', readerButton);
+    readerButton.addEventListener('click', () => {
+        applyReader(root.dataset.reader !== 'on', readerButton);
+    });
+}