@wxxb789/anc 0.0.1

package/src/scripts/snapshot-client.js

@@ -0,0 +1,157 @@
+/**
+ * Main-thread client for the lazy snapshot Worker.
+ *
+ * Ordinary reading must download zero SQLite assets, so this module creates the
+ * Worker only on first explicit intent and shares one instance for previews,
+ * tag browsing, and graph exploration. It owns request ids, deadlines, and the
+ * pending bound: a reply from a torn-down Worker is discarded rather than
+ * attached to the current UI.
+ */
+import { WORKER_LIMITS, } from "../lib/worker-protocol.js";
+export class SnapshotClientError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = 'SnapshotClientError';
+        this.code = code;
+    }
+}
+let worker;
+let nextId = 1;
+let initialized = false;
+const pending = new Map();
+function failAll(code) {
+    for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(new SnapshotClientError(code));
+    }
+    pending.clear();
+}
+function reset(code) {
+    worker?.terminate();
+    worker = undefined;
+    initialized = false;
+    failAll(code);
+}
+function ensureWorker() {
+    if (worker !== undefined)
+        return worker;
+    const created = new Worker(new URL('./snapshot-worker.js', import.meta.url), { type: 'module' });
+    created.addEventListener('message', (event) => {
+        const reply = event.data;
+        const entry = pending.get(reply.id);
+        if (entry === undefined)
+            return;
+        const elapsed = performance.now() - entry.started;
+        pending.delete(reply.id);
+        clearTimeout(entry.timer);
+        if (reply.ok) {
+            initialized = true;
+            // Observability seam for the benchmark harness, armed explicitly by the
+            // measurer: the operation, its dispatch-to-validated-result time, and the
+            // Worker's own operation time (its queries plus selection). Goal 0005
+            // requires the two recorded separately for goal 0008. No corpus data is
+            // carried, and an ordinary reader dispatches nothing. An armed request
+            // also gets the reply's measurement-only fields when a measured Worker
+            // sent them; they are added to the detail only when present, so a reply
+            // without them keeps the shape this seam always had.
+            if (typeof window !== 'undefined' && window.__snapshotMeasurement === true) {
+                const detail = {
+                    type: reply.result.type,
+                    ms: elapsed,
+                    operationMs: reply.operationMs,
+                };
+                if (reply.sqlMs !== undefined)
+                    detail.sqlMs = reply.sqlMs;
+                if (reply.phases !== undefined)
+                    detail.phases = reply.phases;
+                document.dispatchEvent(new CustomEvent('snapshot-result', { detail }));
+            }
+            entry.resolve(reply.result);
+        }
+        else {
+            entry.reject(new SnapshotClientError(reply.code));
+        }
+    });
+    const crashed = () => reset('terminated');
+    created.addEventListener('error', crashed);
+    created.addEventListener('messageerror', crashed);
+    worker = created;
+    return created;
+}
+/**
+ * Release the Worker and settle what it owed.
+ *
+ * A document's snapshot cannot change in place — its binding is compiled into
+ * the page — so the lifecycle contract's "snapshot change" case arrives as a
+ * new document with a new binding, and teardown is the only in-place
+ * transition. Registering it on `pagehide` releases the Worker (and its
+ * deserialized database) with the document, without an idle timer that would
+ * make a later preview cold.
+ */
+export function dispose() {
+    reset('cancelled');
+}
+// `typeof window` keeps this module loadable in Node for the client gate; a
+// browser is the only environment where the listener has anything to release.
+if (typeof window !== 'undefined')
+    window.addEventListener('pagehide', () => dispose());
+/**
+ * Send one named operation.
+ *
+ * @throws {SnapshotClientError} with a small code on failure, a bounded reject
+ *   when too many requests are already pending, and on a deadline.
+ */
+export function request(message) {
+    // The bound applies at every stage: a ready Worker must not accumulate an
+    // unbounded queue of closures and timers just because initialization finished.
+    if (pending.size >= WORKER_LIMITS.maxPendingRequests) {
+        return Promise.reject(new SnapshotClientError('busy'));
+    }
+    let instance;
+    try {
+        instance = ensureWorker();
+    }
+    catch {
+        // A Worker the document may not construct (CSP refusal, unsupported engine)
+        // rejects this request instead of throwing past an awaiting caller; the
+        // client's init state stays clean, so the next intent tries again.
+        return Promise.reject(new SnapshotClientError('terminated'));
+    }
+    const deadline = initialized ? WORKER_LIMITS.requestDeadlineMs : WORKER_LIMITS.startupDeadlineMs;
+    return new Promise((resolve, reject) => {
+        const id = message.id;
+        const timer = setTimeout(() => {
+            // A cancel message cannot interrupt synchronous SQL already running in the
+            // Worker, so the only bounded stop is terminating it.
+            reset('timeout');
+        }, deadline);
+        pending.set(id, { resolve, reject, timer, started: performance.now() });
+        // Arming is read at dispatch, and the added flag is written on a copy: the
+        // function's callers construct their message inline, but a caller that
+        // holds its object must get it back unmutated. Unarmed, the identical
+        // object posted before this seam existed is what goes out.
+        const armed = typeof window !== 'undefined' && window.__snapshotMeasurement === true;
+        instance.postMessage(armed ? { ...message, measure: true } : message);
+    });
+}
+/** Mint the next request id. */
+function nextRequestId() {
+    return nextId++;
+}
+/** Preview one published note. */
+export function requestPreview(slug) {
+    return request({ id: nextRequestId(), type: 'preview', slug });
+}
+/** One page of a tag's members. */
+export function requestByTag(tagKey, cursor, pageSize) {
+    return request({ id: nextRequestId(), type: 'byTag', tagKey, cursor, pageSize });
+}
+/** The local neighbourhood of one note. */
+export function requestLocalGraph(slug) {
+    return request({ id: nextRequestId(), type: 'localGraph', slug });
+}
+/** The global graph, optionally filtered to one tag. */
+export function requestGlobalGraph(tagKey) {
+    return request({ id: nextRequestId(), type: 'globalGraph', tagKey });
+}

package/src/scripts/snapshot-worker.js

@@ -0,0 +1,341 @@
+/**
+ * The lazy, read-only snapshot Worker.
+ *
+ * Owns the snapshot download, digest verification, WASM initialization,
+ * read-only import, schema validation, and query execution. The main thread
+ * never learns the database URL and never sends SQL: the binding is compiled
+ * into this module, and requests are one of the named operations.
+ *
+ * Lifecycle (`docs/core-design/build-and-runtime.md`): one init promise per
+ * document/snapshot; a failure clears it so a later explicit intent can retry;
+ * every failure falls back to the already-rendered static page.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import "../lib/build-bindings.js";
+import { assertSnapshotRows } from "../lib/snapshot-contract.js";
+import { edgePage, globalGraph, localGraph, preview, tagPage } from "../lib/snapshot-operations.js";
+import { isSnapshotMessage, requestPageSize, WORKER_LIMITS, } from "../lib/worker-protocol.js";
+/**
+ * The instant this module begins evaluating, before any load work.
+ *
+ * `load`'s `totalMs` is measured from here, so a measured reply reports the
+ * Worker's whole cold path rather than only the piece after `load` is called.
+ * That matters for goal 0008: the module's own evaluation and the shared
+ * initialization promise both precede the first reply, and a number that began
+ * at the fetch would silently omit them.
+ */
+const moduleStarted = performance.now();
+/** Minimal Worker global, avoiding a webworker/DOM lib declaration clash. */
+const scope = self;
+const SQLITE_MAGIC = [0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74, 0x20, 0x33, 0x00];
+/** A typed failure the reply maps back to a small error code. */
+function fault(code) {
+    const error = new Error(code);
+    error.code = code;
+    throw error;
+}
+function codeOf(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : 'sql';
+}
+/**
+ * Fetch with a running decoded-byte cap, cancelled before the cap is exceeded.
+ *
+ * The optional `signal` lets `load` abort the sibling download when the other
+ * one fails, so a failed initialization cannot leave a response draining toward
+ * its cap behind the failure. Exported for
+ * `tests/snapshot-fetch-bounded.test.ts`, which drives it against a server whose
+ * `Content-Length` disagrees with the body; `load` is the only production
+ * caller.
+ */
+export async function fetchBounded(url, limit, signal) {
+    let response;
+    try {
+        response = await fetch(url, { credentials: 'same-origin', redirect: 'error', signal });
+    }
+    catch {
+        return fault('fetch');
+    }
+    if (!response.ok) {
+        // Release the connection rather than leaving the body undrained behind the
+        // failure the caller is about to see.
+        if (response.body !== null)
+            await response.body.cancel().catch(() => { });
+        fault('fetch');
+    }
+    const reader = response.body?.getReader();
+    if (reader === undefined) {
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        if (buffer.byteLength > limit)
+            fault('integrity');
+        return buffer;
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel();
+            fault('integrity');
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function sha256(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * The WASM linear memory's capacity, or `null` when it is not reachable.
+ *
+ * The pinned package types `sqlite3.config.memory` as a `WebAssembly.Memory`
+ * (the Emscripten heap, the same object as the untyped `wasm.memory`), so the
+ * size is its `buffer.byteLength`: capacity after import, not bytes in use and
+ * not the decoded DB size. A build that stops exposing either location yields
+ * `null` — the phase field is documented as unknown — rather than a fabricated
+ * number, and the `instanceof` keeps a foreign stand-in from being read as one.
+ */
+function wasmMemorySize(sqlite3) {
+    const memory = sqlite3.config?.memory ?? sqlite3.wasm.memory;
+    return memory instanceof WebAssembly.Memory ? memory.buffer.byteLength : null;
+}
+/**
+ * Load the pinned runtime from its same-origin entry.
+ *
+ * The URL is read from a variable so Vite leaves the import for the browser
+ * (`@vite-ignore`): bundling the package inlined its Emscripten glue into this
+ * chunk and made the residue scan read the library's strings as ANC findings.
+ */
+async function initSqlite(bytes, wasmUrl) {
+    const moduleUrl = __ANC_WASM_MODULE_URL__;
+    const module = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ moduleUrl, true)));
+    const init = module.default;
+    return init({ wasmBinary: bytes.buffer, locateFile: () => wasmUrl });
+}
+/**
+ * Deserialize the snapshot bytes and validate the imported schema.
+ *
+ * Exported for `tests/snapshot-worker-init.test.ts`, which drives it with a
+ * fake `sqlite3` and counts open handles; `load` is the only production caller.
+ *
+ * The `oo1.DB` handle owns a FREEONCLOSE copy of the bytes — up to
+ * `WORKER_LIMITS.maxSnapshotBytes` — and `database()` clears a failed loading
+ * promise so a later intent retries here, so every failure after the handle
+ * exists closes it before rethrowing. Without the close each retry would hold
+ * another handle and another copy; `docs/core-design/build-and-runtime.md`
+ * requires the release on failing initialization.
+ */
+export function importSnapshot(sqlite3, databaseBytes) {
+    const database = new sqlite3.oo1.DB();
+    try {
+        const pointer = sqlite3.wasm.allocFromTypedArray(databaseBytes);
+        const result = sqlite3.capi.sqlite3_deserialize(database.pointer, 'main', pointer, databaseBytes.byteLength, databaseBytes.byteLength, sqlite3.capi.SQLITE_DESERIALIZE_READONLY | sqlite3.capi.SQLITE_DESERIALIZE_FREEONCLOSE);
+        // On failure with FREEONCLOSE, SQLite has already freed the buffer, so only
+        // the handle is left for the close below.
+        if (result !== 0)
+            fault('format');
+        database.exec('PRAGMA query_only = ON');
+        if (database.selectValue('PRAGMA query_only') !== 1)
+            fault('format');
+        // A deserialize sizes its page list from the buffer length, so a file whose
+        // last page is partial still imports — and `PRAGMA integrity_check` calls it
+        // `ok`. The producer's snapshot is exactly its pages; any other byte length
+        // is truncated or padded, and the import refuses it. The page size comes
+        // from the file's own header (offset 16, big-endian; 1 means 65536) rather
+        // than `PRAGMA page_size`, which on the pinned WASM build reports the
+        // connection's compiled-in default for a freshly deserialized database.
+        // This is the second line: `load` already fails truncated data on the
+        // digest before import.
+        const headerPageSize = (databaseBytes[16] << 8) | databaseBytes[17];
+        const pageSize = headerPageSize === 1 ? 65536 : headerPageSize;
+        let pageCount;
+        try {
+            pageCount = Number(database.selectValue('PRAGMA page_count'));
+        }
+        catch {
+            // A buffer too corrupt to answer `page_count` is refused as a format
+            // fault rather than escaping as a raw driver error.
+            fault('format');
+        }
+        if (!Number.isInteger(pageCount) || pageSize * pageCount !== databaseBytes.byteLength)
+            fault('format');
+        try {
+            assertSnapshotRows((sql) => database.selectObjects(sql));
+        }
+        catch {
+            fault('schema');
+        }
+        return database;
+    }
+    catch (error) {
+        // Best effort: a close error must not replace the failure being diagnosed.
+        try {
+            database.close();
+        }
+        catch {
+            // The original error is the diagnosis.
+        }
+        throw error;
+    }
+}
+async function load() {
+    const snapshotBinding = __ANC_SNAPSHOT_BINDING__;
+    const wasmBinding = __ANC_WASM_BINDING__;
+    if (snapshotBinding === null || wasmBinding === null)
+        fault('not-ready');
+    // Neither download depends on the other, and both are on the cold path. One
+    // controller bounds the pair: whichever fails first settles the `Promise.all`
+    // and aborts the sibling, so a failed load cannot leave a response draining
+    // toward its cap behind the failure.
+    const controller = new AbortController();
+    const fetchStarted = performance.now();
+    const [databaseBytes, wasmBytes] = await Promise.all([
+        fetchBounded(snapshotBinding.url, WORKER_LIMITS.maxSnapshotBytes, controller.signal),
+        fetchBounded(wasmBinding.url, WORKER_LIMITS.maxWasmBytes, controller.signal),
+    ]).finally(() => controller.abort());
+    const fetchMs = performance.now() - fetchStarted;
+    const digestStarted = performance.now();
+    const [databaseDigest, wasmDigest] = await Promise.all([sha256(databaseBytes), sha256(wasmBytes)]);
+    const digestMs = performance.now() - digestStarted;
+    if (databaseDigest !== snapshotBinding.digest)
+        fault('integrity');
+    if (databaseBytes.length < 100)
+        fault('header');
+    for (const [index, byte] of SQLITE_MAGIC.entries()) {
+        if (databaseBytes[index] !== byte)
+            fault('header');
+    }
+    // Bytes 18/19 are the file-format write/read versions: 1 is rollback journal,
+    // 2 is WAL, which cannot be deserialized as a standalone snapshot.
+    if (databaseBytes[18] !== 1 || databaseBytes[19] !== 1)
+        fault('format');
+    if (wasmDigest !== wasmBinding.digest)
+        fault('integrity');
+    let sqlite3;
+    const wasmInitStarted = performance.now();
+    try {
+        sqlite3 = await initSqlite(wasmBytes, wasmBinding.url);
+    }
+    catch {
+        return fault('wasm');
+    }
+    const wasmInitMs = performance.now() - wasmInitStarted;
+    // The schema validation inside `importSnapshot` is part of this phase: goal
+    // 0008's startup decomposition is fetch/hash/init/import, and `totalMs` is
+    // the whole module-to-ready span that also covers the header checks above.
+    const importStarted = performance.now();
+    const database = importSnapshot(sqlite3, databaseBytes);
+    const importMs = performance.now() - importStarted;
+    return {
+        db: { select: (sql, params) => database.selectObjects(sql, params ? [...params] : undefined) },
+        phases: {
+            totalMs: performance.now() - moduleStarted,
+            fetchMs,
+            digestMs,
+            wasmInitMs,
+            importMs,
+            wasmMemoryBytes: wasmMemorySize(sqlite3),
+        },
+    };
+}
+let loading;
+/** One shared initialization promise; a failure clears it so intent can retry. */
+function database() {
+    loading ??= load().catch((error) => {
+        loading = undefined;
+        throw error;
+    });
+    return loading;
+}
+function run(db, message) {
+    switch (message.type) {
+        case 'preview':
+            return { type: 'preview', preview: preview(db, message.slug) };
+        case 'outgoing':
+            return { type: 'outgoing', ...edgePage(db, 'outgoing', message.slug, message.cursor, requestPageSize(message)) };
+        case 'backlinks':
+            return { type: 'backlinks', ...edgePage(db, 'backlinks', message.slug, message.cursor, requestPageSize(message)) };
+        case 'byTag':
+            return { type: 'byTag', page: tagPage(db, message.tagKey, message.cursor, requestPageSize(message)) };
+        case 'localGraph':
+            return { type: 'localGraph', graph: localGraph(db, message.slug) };
+        case 'globalGraph':
+            return { type: 'globalGraph', graph: globalGraph(db, message.tagKey ?? undefined) };
+    }
+}
+function reply(message) {
+    scope.postMessage(message);
+}
+async function handle(value) {
+    if (!isSnapshotMessage(value)) {
+        const id = value?.id;
+        if (typeof id === 'number')
+            reply({ id, ok: false, code: 'bad-request' });
+        return;
+    }
+    try {
+        const loaded = await database();
+        // The measured request gets a wrapping adapter that sums every `select`
+        // span; an unmeasured request runs against the same adapter as before, so
+        // its reply shape and behavior are unchanged. The wrapper never changes
+        // what is executed or returned: `select` delegates straight through.
+        let sqlMs = 0;
+        const db = value.measure === true
+            ? {
+                select(sql, params) {
+                    const selectStarted = performance.now();
+                    try {
+                        return loaded.db.select(sql, params);
+                    }
+                    finally {
+                        sqlMs += performance.now() - selectStarted;
+                    }
+                },
+            }
+            : loaded.db;
+        // The measurement goal needs the operation's SQL/Worker time separated from
+        // main-thread dispatch and rendering time, so a successful reply carries the
+        // span around `run()` alone: the shared initialization promise is awaited
+        // first so a cold start's download, hashing, WASM init, import, and schema
+        // validation can never land in a reply's duration. The span still covers
+        // the operation's selection and induced-edge work beside its queries; that
+        // is the worker-side half goal 0005 records for goal 0008. A request that
+        // asked to measure additionally gets `sqlMs`, the subset of that span spent
+        // inside `select` calls, and `phases`, the decomposition of the cold start
+        // that preceded it.
+        const started = performance.now();
+        const result = run(db, value);
+        const operationMs = performance.now() - started;
+        if (value.measure === true) {
+            reply({ id: value.id, ok: true, result, operationMs, sqlMs, phases: loaded.phases });
+        }
+        else {
+            reply({ id: value.id, ok: true, result, operationMs });
+        }
+    }
+    catch (error) {
+        reply({ id: value.id, ok: false, code: codeOf(error) });
+    }
+}
+scope.addEventListener('message', (event) => {
+    void handle(event.data);
+});

package/src/scripts/tag-browser.js

@@ -0,0 +1,153 @@
+/**
+ * Reader-facing tag browsing over the shared lazy snapshot runtime.
+ *
+ * `byTag` is a named operation with cursor pagination; this is its reader-facing
+ * consumer. It is mounted on `/tags/` (a tag chooser) and `/tags/<tag>/` (one
+ * fixed tag), and every chrome string arrives as a `data-` attribute the build
+ * wrote, so no locale table ships to the browser and no tag is normalized here —
+ * the key is sent exactly as the static route spells it.
+ *
+ * The static `NoteList`/`FacetIndex` above it remains the complete no-JS route;
+ * this region is hidden until the script runs and unhides the static list on any
+ * failure.
+ */
+import { noteRoute } from "../lib/route-path.js";
+import { classifyTagPage, TAG_PAGE_SIZE } from "../lib/tag-browser-model.js";
+import { partLanguage, TAG_BROWSE_DATASET } from "../lib/translations.js";
+import { requestByTag } from "./snapshot-client.js";
+const root = document.querySelector('#tag-browser');
+if (root)
+    install(root);
+function install(root) {
+    const mode = root.dataset['mode'] === 'switch' ? 'switch' : 'fixed';
+    const pageSize = Number(root.dataset['pageSize']) || TAG_PAGE_SIZE;
+    const staticList = document.querySelector('#tag-static-list');
+    const chooser = root.querySelector('#tag-browser-select');
+    const start = root.querySelector('#tag-browse-start');
+    const more = root.querySelector('#tag-browse-more');
+    const results = root.querySelector('#tag-browser-results');
+    const status = root.querySelector('#tag-browser-status');
+    const current = root.querySelector('#tag-browser-current');
+    const string = (key) => root.dataset[key] ?? '';
+    let generation = 0;
+    let tagKey = mode === 'fixed' ? (root.dataset['tagKey'] ?? '') : '';
+    let cursor = null;
+    root.hidden = false;
+    const reset = () => {
+        results.replaceChildren();
+        if (more !== null)
+            more.hidden = true;
+        current.hidden = true;
+        status.textContent = '';
+    };
+    async function load(after, forGeneration) {
+        if (tagKey === '') {
+            reset();
+            return;
+        }
+        // One continuation may be in flight at a time. `#tag-browse-more` is the only
+        // way to dispatch one, and a second click before the first reply lands would
+        // send the same cursor again — both replies pass the generation guard below
+        // and append the same page. Marked busy synchronously, before the first
+        // await, so a double click cannot get two handlers in; the cursor advances
+        // only when a reply lands, and the `finally` clears the mark for the next
+        // explicit continuation.
+        //
+        // `aria-disabled` plus the click handler's own check, **not** `disabled`.
+        // Disabling the button that holds focus drops focus to `<body>`, so a
+        // keyboard reader who pressed Enter on "Load more" was thrown back to the
+        // top of the tab order on every page. `tests/tag-browser.test.ts` asserts
+        // `document.activeElement` across a continuation.
+        if (more !== null)
+            more.setAttribute('aria-disabled', 'true');
+        status.textContent = string(TAG_BROWSE_DATASET.loading);
+        let page;
+        try {
+            page = (await requestByTag(tagKey, after, pageSize)).page;
+        }
+        catch {
+            if (forGeneration !== generation)
+                return;
+            // The static list is never removed before page 1 renders, so a failure
+            // leaves the complete no-JS list on screen.
+            if (staticList !== null)
+                staticList.hidden = false;
+            status.textContent = string(TAG_BROWSE_DATASET.failed);
+            return;
+        }
+        finally {
+            if (more !== null)
+                more.removeAttribute('aria-disabled');
+        }
+        if (forGeneration !== generation)
+            return; // a stale tag's reply cannot replace this one
+        const state = classifyTagPage(page);
+        if (state.kind === 'unknown') {
+            if (more !== null)
+                more.hidden = true;
+            status.textContent = string(TAG_BROWSE_DATASET.unknown);
+            return;
+        }
+        if (state.kind === 'empty') {
+            if (more !== null)
+                more.hidden = true;
+            status.textContent = string(TAG_BROWSE_DATASET.empty);
+            return;
+        }
+        // `partLanguage` compares case-insensitively, so the page's raw tag is fine.
+        const language = document.documentElement.lang || 'en';
+        let firstAppended;
+        for (const note of state.notes) {
+            const item = document.createElement('li');
+            const link = document.createElement('a');
+            link.href = noteRoute(note.slug);
+            link.textContent = note.title;
+            // The static tag list marks a foreign title through `partLanguage`;
+            // calling it here keeps the enhanced list from drifting from it.
+            const lang = partLanguage(note.language, language);
+            if (lang !== undefined)
+                link.lang = lang;
+            item.append(link);
+            results.append(item);
+            firstAppended ??= link;
+        }
+        if (page.known) {
+            current.textContent = page.tag.label;
+            current.hidden = false;
+        }
+        cursor = state.nextCursor;
+        if (cursor === null) {
+            // Hiding the focused button would drop focus to `<body>` just as above,
+            // so a reader who reached the last page from "Load more" continues at
+            // the first result that page added.
+            if (more !== null && document.activeElement === more)
+                firstAppended?.focus();
+            if (more !== null)
+                more.hidden = true;
+            status.textContent = string(TAG_BROWSE_DATASET.exhausted);
+        }
+        else {
+            if (more !== null)
+                more.hidden = false;
+            status.textContent = '';
+        }
+    }
+    /** Explicit intent: choosing a tag or pressing Start. */
+    function select(nextKey) {
+        const forGeneration = ++generation; // invalidates any in-flight reply
+        tagKey = nextKey;
+        cursor = null;
+        reset();
+        if (staticList !== null)
+            staticList.hidden = true; // only after a selection is made
+        void load(null, forGeneration);
+    }
+    start?.addEventListener('click', () => select(mode === 'fixed' ? (root.dataset['tagKey'] ?? '') : ''));
+    chooser?.addEventListener('change', () => select(chooser.value));
+    more?.addEventListener('click', () => {
+        if (more.getAttribute('aria-disabled') === 'true')
+            return; // a continuation is in flight
+        const forGeneration = generation;
+        void load(cursor, forGeneration);
+    });
+}

package/src/scripts/theme-init.js

@@ -0,0 +1,35 @@
+/**
+ * Applies the stored display preferences before first paint.
+ *
+ * Kept a classic script with no imports or exports so `Layout.astro` can load
+ * it render-blocking; see the comment there for why that matters. Ships to
+ * every visitor in the critical path, so it stays short.
+ */
+(function () {
+  var root = document.documentElement;
+
+  /** Blocked storage throws on access, not on read. */
+  function stored(key) {
+    try {
+      return localStorage.getItem(key);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  // No attribute is the default: CSS then follows `prefers-color-scheme`
+  // through `light-dark()`. These express only an explicit override.
+  //
+  // The `publish:` prefix is duplicated from `preferences.ts`, which this file
+  // cannot import; `tests/design-tokens.test.ts` asserts the two agree. It names
+  // what wrote the value rather than this project, so a stranger's visitor does
+  // not carry the tool's name in their own browser storage.
+  var theme = stored('publish:theme');
+  if (theme === 'light' || theme === 'dark') root.dataset.theme = theme;
+
+  if (stored('publish:reader') === 'on') root.dataset.reader = 'on';
+
+  // Reveals the controls that only work with scripting; without this they stay
+  // hidden rather than rendering as buttons that do nothing.
+  root.dataset.js = 'on';
+})();