@glw907/cairn-cms 0.59.0 → 0.60.0

package/dist/components/spellcheck.js

@@ -0,0 +1,541 @@
+import { frontmatterSpan, fenceTokens } from './markdown-directives.js';
+import { parseMediaToken } from '../media/reference.js';
+import { objectiveErrors } from './objective-errors.js';
+// The Lezer node kinds that are never spellchecked, verified empirically against the actual
+// @codemirror/lang-markdown grammar (parse a fixture, inspect node names) rather than trusting the
+// spec list blind. The grammar models:
+//   code: InlineCode, FencedCode, CodeText, CodeBlock (CodeBlock is the indented form; its body is a
+//     CodeText too). CodeMark/CodeInfo are the fence/lang markers.
+//   links and URLs: URL (a link destination and the URL inside an autolink), Autolink (the whole
+//     <...> form), LinkLabel (a [ref] label and a reference-definition label), LinkReference (the
+//     whole `[ref]: url "title"` definition), LinkTitle (the quoted title on a definition).
+//   HTML: HTMLTag (inline), HTMLBlock.
+//   emphasis/strong MARKERS: EmphasisMark (the *,_,**,__ runs), not the prose inside Emphasis or
+//     StrongEmphasis. The same goes for the other *Mark nodes (LinkMark, HeaderMark, ListMark,
+//     QuoteMark), which are punctuation, never prose.
+// Note the spec listed "link destinations, autolinks, link labels, reference definitions"; the real
+// node names for those are URL, Autolink, LinkLabel, and LinkReference. LinkTitle is added because
+// the grammar emits the definition's quoted title as its own node and it is machinery, not prose.
+const SKIP_NODES = new Set([
+    'InlineCode',
+    'FencedCode',
+    'CodeText',
+    'CodeBlock',
+    'CodeMark',
+    'CodeInfo',
+    'URL',
+    'Autolink',
+    'LinkLabel',
+    'LinkReference',
+    'LinkTitle',
+    'HTMLTag',
+    'HTMLBlock',
+    'EmphasisMark',
+    'LinkMark',
+    'HeaderMark',
+    'ListMark',
+    'QuoteMark',
+]);
+// A bare `media:` token shaped like the reference grammar (a slug-and-hash or bare-hash run with no
+// surrounding whitespace). A token inside an image is already caught by the URL skip; this catches
+// the form authors type directly in prose, so it is never split into "media" plus a flagged hash.
+const MEDIA_TOKEN = /media:[\w.-]+/g;
+/** Merge overlapping or touching ranges into a sorted, disjoint set, so the keep-span computation
+ *  subtracts one clean list of skip regions. */
+function mergeRanges(ranges) {
+    if (ranges.length === 0)
+        return [];
+    const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
+    const out = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const next = sorted[i];
+        const last = out[out.length - 1];
+        if (next.from <= last.to)
+            last.to = Math.max(last.to, next.to);
+        else
+            out.push({ ...next });
+    }
+    return out;
+}
+/** Every absolute skip range in the document, from all three mechanisms, merged. This is the single
+ *  skip authority the spec calls for: the tree decides node kind, frontmatterSpan covers the `---`
+ *  region, and fenceTokens covers the directive machinery the tree parses as plain text. */
+function skipRanges(text, tree) {
+    const skips = [];
+    // 1. The Lezer tree: the single authority for node-kind skips.
+    tree.iterate({
+        enter(node) {
+            if (SKIP_NODES.has(node.name))
+                skips.push({ from: node.from, to: node.to });
+        },
+    });
+    // 2. The frontmatter `---` region (slugs, dates, keys never flagged). The grammar models no
+    //    frontmatter node, so this deterministic helper is the only authority for the region.
+    const fm = frontmatterSpan(text);
+    if (fm)
+        skips.push(fm);
+    // 3. The directive machinery, line by line: the colon runs, the `{attrs}` braces, and the
+    //    directive name. A `[label]`'s prose and the directive body stay checkable, so only the
+    //    machinery tokens are skipped. fenceTokens emits the directive name and a bracket label both
+    //    as `label` kind; the name is the lone `label` that precedes any bracket on the line, so it is
+    //    skipped while the bracketed label is kept.
+    let lineStart = 0;
+    for (const line of text.split('\n')) {
+        const tokens = fenceTokens(line);
+        if (tokens.length > 0) {
+            let seenBracket = false;
+            for (const token of tokens) {
+                // A single-character `[` mark opens the bracket label; everything after it on this line is
+                // bracketed, so the directive name can only be a `label` before it.
+                const isOpenBracket = token.kind === 'mark' && line[token.from] === '[';
+                if (token.kind === 'mark') {
+                    skips.push({ from: lineStart + token.from, to: lineStart + token.to });
+                    if (isOpenBracket)
+                        seenBracket = true;
+                }
+                else if (token.kind === 'label' && !seenBracket) {
+                    // The directive name (a label before any bracket) is machinery, not prose.
+                    skips.push({ from: lineStart + token.from, to: lineStart + token.to });
+                }
+            }
+        }
+        // 4. A bare `media:` token anywhere on the line, kept whole so the hash never reads as a word.
+        for (const m of line.matchAll(MEDIA_TOKEN)) {
+            if (parseMediaToken(m[0])) {
+                skips.push({ from: lineStart + m.index, to: lineStart + m.index + m[0].length });
+            }
+        }
+        lineStart += line.length + 1;
+    }
+    return mergeRanges(skips);
+}
+/**
+ * The keep spans inside one text window [from, to): the window with every skip range subtracted.
+ * This is the lower-level primitive {@link spellcheckRanges} composes over the whole document, and
+ * the one the lint source runs over `view.visibleRanges` plus a margin. The skip authority and its
+ * precedence live in {@link skipRanges}.
+ */
+export function classifyProse(text, tree, from, to) {
+    const skips = skipRanges(text, tree);
+    const out = [];
+    let cursor = from;
+    for (const skip of skips) {
+        if (skip.to <= from || skip.from >= to)
+            continue; // outside the window
+        const start = Math.max(skip.from, from);
+        if (start > cursor)
+            out.push({ from: cursor, to: start });
+        cursor = Math.max(cursor, Math.min(skip.to, to));
+    }
+    if (cursor < to)
+        out.push({ from: cursor, to });
+    return out;
+}
+/** The prose ranges worth checking across the whole document. The lint source narrows this to the
+ *  visible window; the unit test reads the whole-document set. */
+export function spellcheckRanges(text, tree) {
+    return classifyProse(text, tree, 0, text.length);
+}
+// A word boundary that keeps intra-word apostrophes and hyphens (so "it's" and "well-known" stay
+// whole) while breaking on everything else. The class is Unicode letters and digits via the u flag,
+// with the inner apostrophe (straight or curly) and hyphen allowed only between word characters.
+const WORD = /[\p{L}\p{N}]+(?:[-'’][\p{L}\p{N}]+)*/gu;
+const ALL_DIGITS = /^\p{N}+$/u;
+/** Whether a word is worth a lookup. Words under three characters, pure numbers, and all-caps tokens
+ *  are skipped to cut false positives (the conservative posture VSCode's spell checker takes). */
+function isCheckable(word) {
+    if (word.length < 3)
+        return false;
+    if (ALL_DIGITS.test(word))
+        return false;
+    // An all-caps token (acronym or constant) is skipped; a word with any lowercase letter is checked.
+    if (word === word.toUpperCase() && word !== word.toLowerCase())
+        return false;
+    return true;
+}
+/**
+ * The checkable words inside [from, to), each lowercased for lookup with its absolute range recorded
+ * so a verdict maps straight back to an underline. Sub-three-character words, pure numbers, and
+ * all-caps tokens are dropped.
+ */
+export function extractWords(text, from, to) {
+    const slice = text.slice(from, to);
+    const out = [];
+    for (const m of slice.matchAll(WORD)) {
+        const raw = m[0];
+        if (!isCheckable(raw))
+            continue;
+        const start = from + m.index;
+        out.push({ text: raw.toLowerCase(), from: start, to: start + raw.length });
+    }
+    return out;
+}
+// The most suggestions shown in one tooltip. SymSpell can return a long ranked list; five is the
+// spec cap, enough to cover the likely correction without burying the management actions below a
+// wall of near-ties.
+const MAX_SUGGESTIONS = 5;
+/**
+ * Build the correction popover for one misspelled word, as a @codemirror/lint Diagnostic whose
+ * `actions` CodeMirror renders as tooltip buttons (no custom popover code). The actions, in order:
+ * up to five ranked suggestions (each replaces the word's range with one transaction), then "Add to
+ * dictionary", then "Ignore". The severity is `info` so the underline is quiet, and the message names
+ * the word so the underline is never the only signal. Pure: it takes canned suggestions and callbacks,
+ * so the unit test asserts the actions array without a browser or a real Worker.
+ */
+export function buildSpellDiagnostic(word, range, suggestions, callbacks) {
+    const ranked = suggestions.slice(0, MAX_SUGGESTIONS).map((suggestion) => ({
+        name: suggestion,
+        // CodeMirror passes the diagnostic's current position, which may have shifted since the lint ran;
+        // the replace uses that live range so a suggestion never overwrites the wrong span after an edit.
+        apply: (view, from, to) => {
+            view.dispatch({ changes: { from, to, insert: suggestion } });
+        },
+    }));
+    return {
+        from: range.from,
+        to: range.to,
+        severity: 'info',
+        source: 'cairn-spellcheck',
+        message: `\`${word}\` may be misspelled.`,
+        actions: [
+            ...ranked,
+            {
+                name: 'Add to dictionary',
+                apply: () => callbacks.onAddWord(word),
+            },
+            {
+                name: 'Ignore',
+                apply: () => callbacks.onIgnoreWord(word),
+            },
+        ],
+    };
+}
+/** Build a fresh {@link SeqArbiter}. */
+export function arbitrateChecked() {
+    let current = 0;
+    return {
+        next() {
+            current += 1;
+            return current;
+        },
+        accept(seq) {
+            if (seq < current)
+                return false;
+            current = seq;
+            return true;
+        },
+    };
+}
+/**
+ * Build the quick-fix popover for one objective-error finding, as a @codemirror/lint Diagnostic whose
+ * one `actions` entry applies the finding's deterministic fix. The severity is `info` so the underline
+ * shares the spellcheck surface and the locked amber color (an editor reads spelling and these
+ * mechanical errors as one "spellcheck" layer). The fix range is recomputed from the live diagnostic
+ * position CodeMirror passes, offset by the same delta as the original finding, so an edit elsewhere
+ * never makes the fix overwrite the wrong span. Pure: it takes a finding, so the unit test asserts the
+ * diagnostic without a browser.
+ */
+export function buildObjectiveDiagnostic(error) {
+    // The fix range sits inside the flagged range; record its offset from the flagged start so the apply
+    // can re-anchor against the live position CodeMirror reports (which may have shifted since the lint).
+    const fixOffsetFrom = error.fix.from - error.from;
+    const fixOffsetTo = error.fix.to - error.from;
+    const insert = error.fix.insert;
+    return {
+        from: error.from,
+        to: error.to,
+        severity: 'info',
+        source: 'cairn-objective',
+        message: error.message,
+        actions: [
+            {
+                name: 'Fix',
+                apply: (view, from) => {
+                    view.dispatch({
+                        changes: { from: from + fixOffsetFrom, to: from + fixOffsetTo, insert },
+                    });
+                },
+            },
+        ],
+    };
+}
+// ----- The linter() wiring (the CodeMirror side) -----
+//
+// Only this half touches CodeMirror, and it never value-imports an @codemirror/* package at module
+// scope: EditPage imports the component .ts helpers statically, so a static value import here would
+// pull CodeMirror into a consumer's server bundle (the editor-boundary test enforces this). The
+// modules resolve lazily inside the source, the same boundary link-completion.ts keeps. The Worker
+// construction sits behind a small injectable seam so the lint logic can be exercised without a real
+// Worker; production passes the seam that builds the spike's `new Worker(...)`.
+let lintMod = null;
+let langMod = null;
+let viewMod = null;
+let stateMod = null;
+/** Construct the real spellcheck Worker, the spike's delivery shape. Kept behind the seam so the
+ *  lint source never references `Worker` at module scope and a test can swap it. */
+export function createSpellWorker() {
+    return new Worker(new URL('./spellcheck-worker.js', import.meta.url), {
+        type: 'module',
+    });
+}
+// The wasm and dictionary URLs are resolved module-relative with `import.meta.url`, the same
+// mechanism createSpellWorker uses for the worker. The spike (docs/internal/design/
+// 2026-06-20-editor-copyedit-spike-result.md) proved Vite's `?worker`/`?url` package-subpath imports
+// from CONSUMER app code; the library's own source cannot self-import by package name, so it uses the
+// portable `new URL('./asset', import.meta.url)` form Vite resolves inside dependencies too. Task 16's
+// showcase E2E proves the whole chain through the real consumer build; if resolution ever fails there,
+// only these two URL lines change. The dictionary filename is the dialect-resolved one the main thread
+// passes in; the wasm filename is fixed.
+/** The real wasm asset URL, resolved module-relative the same way the worker is. */
+export function resolveWasmUrl() {
+    return new URL('./spellcheck-assets/spellchecker-wasm.wasm', import.meta.url).href;
+}
+/** The real dictionary asset URL for a dictionary filename, resolved module-relative. The caller
+ *  passes the dialect-resolved filename (default `dictionary-en-us.txt`). */
+export function resolveDictionaryUrl(dictionaryFile) {
+    return new URL(`./spellcheck-assets/${dictionaryFile}`, import.meta.url).href;
+}
+/** How far past the visible viewport to lint, so a small scroll does not re-lint from scratch. */
+const VIEWPORT_MARGIN = 1000;
+// The lint underline is LOCKED to --cairn-warning-ink (a muted amber, the closest shipped token to
+// the spec's "neither the directive accent nor error red"; there is no --cairn-info-ink). Spellcheck
+// diagnostics carry severity `info`, so the override targets the `info` underline and tooltip row.
+// --cairn-error-ink red is reserved for tidy deletions, so a spellcheck underline and a tidy deletion
+// are never the same color. The tooltip rides the admin Warm Stone tokens and the focus rules; the
+// lint action buttons are CodeMirror's own focusable buttons, so the theme only restores a visible
+// focus ring (the admin base button reset strips the UA outline). The wavy underline uses a CSS
+// text-decoration so the locked token resolves at render rather than being baked into a static SVG.
+function lockedUnderlineTheme(EditorViewMod) {
+    return EditorViewMod.theme({
+        // The amber wavy underline, the one spellcheck underline color across the feature.
+        '.cm-lintRange-info': {
+            backgroundImage: 'none',
+            textDecoration: 'underline wavy var(--cairn-warning-ink, oklch(50% 0.13 70))',
+            textDecorationSkipInk: 'none',
+            textUnderlineOffset: '0.2em',
+        },
+        // The tooltip surface rides the admin Warm Stone tokens.
+        '.cm-tooltip.cm-tooltip-lint': {
+            backgroundColor: 'var(--color-base-100, #fff)',
+            border: '1px solid var(--color-base-300, oklch(90% 0.01 75))',
+            borderRadius: '0.5rem',
+            color: 'var(--color-base-content, oklch(28% 0.01 75))',
+        },
+        '.cm-diagnostic-info': {
+            borderLeftColor: 'var(--cairn-warning-ink, oklch(50% 0.13 70))',
+        },
+        // The action buttons are real focusable buttons; the admin base reset strips the UA outline, so a
+        // visible focus ring is restored here to keep them keyboard-discoverable (the a11y focus rule).
+        '.cm-diagnosticAction:focus-visible': {
+            outline: '2px solid var(--cairn-warning-ink, oklch(50% 0.13 70))',
+            outlineOffset: '1px',
+        },
+    });
+}
+/**
+ * The @codemirror/lint linter() source, made markdown-aware by the Lezer tree. It runs over the
+ * visible viewport plus a margin (not the whole document), extracts the checkable words via the pure
+ * classifier, posts them to the Worker keyed by a monotonic latest-wins seq, and maps the
+ * `correct: false` answers back to ranges. Each wrong word becomes a correction popover: the source
+ * fetches the ranked suggestions in the same batch, then {@link buildSpellDiagnostic} wires the
+ * quick-fix actions (the suggestions, then add-to-dictionary, then ignore). The returned extension
+ * bundles the spellcheck linter, a second deterministic objective-error linter over the same prose
+ * spans (doubled words, double spaces, repeated punctuation), and the locked amber underline theme,
+ * so Task 7's single on/off toggle gates both surfaces by reconfiguring this one extension.
+ */
+export async function cairnSpellcheck(options = {}) {
+    // Reuse the caller's already-loaded modules when supplied (the editor passes its own view/language
+    // copies so the lint extension lands on the same instances), else lazily value-import them. The lazy
+    // imports keep CodeMirror off the server bundle (the boundary the editor relies on) and match how
+    // link-completion.ts resolves @codemirror/language inside its source.
+    lintMod = options.modules?.lint ?? lintMod ?? (await import('@codemirror/lint'));
+    langMod = options.modules?.language ?? langMod ?? (await import('@codemirror/language'));
+    viewMod = options.modules?.view ?? viewMod ?? (await import('@codemirror/view'));
+    stateMod = options.modules?.state ?? stateMod ?? (await import('@codemirror/state'));
+    const { linter, forceLinting } = lintMod;
+    const { syntaxTree } = langMod;
+    const { EditorView } = viewMod;
+    const { StateEffect } = stateMod;
+    // A re-lint nudge for the no-doc-change case. Add-to-dictionary and ignore change the Worker's merged
+    // set but not the document, and @codemirror/lint's forceLinting() is a no-op when the editor is idle
+    // (its internal force() only fires when a lint is already scheduled). The linter's needsRefresh hook
+    // is the supported way to schedule a run on a state change that is not a doc edit: a callback
+    // dispatches this effect, needsRefresh sees it and schedules the lint, and forceLinting then runs it
+    // at once so the underlines clear immediately.
+    const relintEffect = StateEffect.define();
+    const createWorker = options.createWorker ?? createSpellWorker;
+    const pendingAdditions = options.pendingAdditions ?? new Set();
+    // The committed site dictionary words, seeded into the Worker's personal layer at init.
+    const siteWords = options.siteWords ?? [];
+    const arbiter = arbitrateChecked();
+    // The wasm and dictionary URLs the Worker fetches, resolved module-relative unless the caller
+    // overrides them (a test injecting a fake Worker passes canned URLs). The dictionary filename is the
+    // dialect-resolved one; the wasm filename is fixed.
+    const assetUrls = options.assetUrls ?? {
+        wasmUrl: resolveWasmUrl(),
+        dictionaryUrl: resolveDictionaryUrl(options.dictionaryFile ?? 'dictionary-en-us.txt'),
+    };
+    let worker = null;
+    // The Worker answers `ready` once its dictionary has streamed into wasm; until then a lint run paints
+    // nothing rather than throwing. A test can set assumeReady to skip the wait when its fake Worker does
+    // not answer `ready`.
+    let ready = options.assumeReady ?? false;
+    // The view from the latest lint run, captured so a management action can re-lint through it. The
+    // action callbacks fire long after the source promise resolved, so the source cannot close over a
+    // run-local view; it stores the last one here.
+    let lastView = null;
+    // The in-flight check requests keyed by their seq, each resolved by the matching `checked` answer.
+    const pending = new Map();
+    // A monotonic seq for suggest round-trips, separate from the check seq so the two answer streams
+    // never collide on a shared counter.
+    let suggestSeq = 0;
+    // Re-run the lint at once after a state change that is not a doc edit (the Worker became ready, or a
+    // word was added or ignored). The dispatched effect makes the linter's needsRefresh schedule a run,
+    // so the following forceLinting is no longer a no-op (its internal force() only fires on a scheduled
+    // lint), and the underlines repaint immediately.
+    function relint() {
+        if (!lastView)
+            return;
+        lastView.dispatch({ effects: relintEffect.of(null) });
+        forceLinting(lastView);
+    }
+    function ensureWorker() {
+        if (worker)
+            return worker;
+        worker = createWorker();
+        worker.addEventListener('message', (event) => {
+            const data = event.data;
+            // The init ack: lookups are live. Re-lint so the viewport paints the underlines the not-ready
+            // runs withheld; the latest-wins seq keeps the re-lint from racing an in-flight run.
+            if (data.type === 'ready') {
+                ready = true;
+                relint();
+                return;
+            }
+            // An init or lookup failure: log it and leave the editor usable (no underlines is the graceful
+            // degrade, never a thrown error). A `check` that arrives after this still resolves to [] below.
+            if (data.type === 'error') {
+                console.warn('cairn spellcheck worker error:', data.detail ?? 'unknown');
+                return;
+            }
+            if (data.type !== 'checked' || typeof data.seq !== 'number')
+                return;
+            const request = pending.get(data.seq);
+            if (!request)
+                return;
+            pending.delete(data.seq);
+            // Drop a stale answer that landed after a newer run; only the latest seq paints underlines.
+            if (!arbiter.accept(data.seq)) {
+                request.resolve([]);
+                return;
+            }
+            const wrongIds = new Set((data.results ?? []).filter((r) => !r.correct).map((r) => r.id));
+            const wrong = request.words.filter((_, id) => wrongIds.has(id));
+            // Fetch the ranked suggestions for every wrong word, then build the popovers from the answers.
+            void buildDiagnostics(wrong).then(request.resolve);
+        });
+        // The handshake: post init so the Worker streams its dictionary, then wait for `ready` before any
+        // check/suggest. The Worker answers `error` on a check that lands before ready, so the not-ready
+        // early return in the lint source keeps a check from ever racing the init.
+        worker.postMessage({ type: 'init', ...assetUrls });
+        // Seed the personal layer from the committed site dictionary. The Worker merges addWord into its
+        // in-memory personal set regardless of ready state (it touches no engine), so a site word answers
+        // correct from the first lint without waiting for the dialect stream.
+        if (siteWords.length > 0)
+            worker.postMessage({ type: 'addWord', words: siteWords });
+        return worker;
+    }
+    /** Fetch a single word's ranked suggestions over the Worker, a one-shot listener removed on the
+     *  answer. The suggest path is independent of the check seq, so a slow suggest never blocks a fresh
+     *  check; an empty list (the engine returned nothing) still yields a popover with the two
+     *  management actions. */
+    function fetchSuggestions(w, word) {
+        suggestSeq += 1;
+        const seq = suggestSeq;
+        return new Promise((resolve) => {
+            const listener = (event) => {
+                const data = event.data;
+                if (data.type !== 'suggested' || data.seq !== seq)
+                    return;
+                w.removeEventListener('message', listener);
+                resolve(data.suggestions ?? []);
+            };
+            w.addEventListener('message', listener);
+            w.postMessage({ type: 'suggest', seq, word });
+        });
+    }
+    /** Turn the wrong words into correction popovers, each carrying its ranked suggestions and the two
+     *  management actions. */
+    async function buildDiagnostics(wrong) {
+        const w = ensureWorker();
+        const callbacks = {
+            onAddWord(word) {
+                // Post addWord so the Worker's merged set now answers correct, record the pending addition for
+                // Task 9 to commit, and re-lint so every instance of the word clears at once.
+                w.postMessage({ type: 'addWord', word });
+                pendingAdditions.add(word.toLowerCase());
+                relint();
+            },
+            onIgnoreWord(word) {
+                // Session-only ignore, never persisted; re-lint so the underline clears everywhere.
+                w.postMessage({ type: 'ignoreWord', word });
+                relint();
+            },
+        };
+        return Promise.all(wrong.map(async (word) => {
+            const suggestions = await fetchSuggestions(w, word.text);
+            return buildSpellDiagnostic(word.text, { from: word.from, to: word.to }, suggestions, callbacks);
+        }));
+    }
+    // The prose keep-spans for one view, scoped to the visible viewport plus a margin. The spellcheck
+    // source and the objective source both run over exactly these spans, so a doubled word inside a
+    // code fence is never flagged and the two surfaces can never drift on what counts as prose.
+    function visibleProseSpans(view) {
+        const text = view.state.doc.toString();
+        const tree = syntaxTree(view.state);
+        const docLength = text.length;
+        const spans = [];
+        for (const vr of view.visibleRanges) {
+            const from = Math.max(0, vr.from - VIEWPORT_MARGIN);
+            const to = Math.min(docLength, vr.to + VIEWPORT_MARGIN);
+            spans.push(...classifyProse(text, tree, from, to));
+        }
+        return { text, spans };
+    }
+    const source = linter(async (view) => {
+        lastView = view;
+        // Create the Worker (and post init) on the first run even when not yet ready, so the dictionary
+        // starts streaming. Until `ready` lands this run paints nothing; the `ready` handler re-lints.
+        ensureWorker();
+        if (!ready)
+            return [];
+        const { text, spans } = visibleProseSpans(view);
+        const words = [];
+        for (const span of spans) {
+            words.push(...extractWords(text, span.from, span.to));
+        }
+        if (words.length === 0)
+            return [];
+        const seq = arbiter.next();
+        const checkWords = words.map((word, id) => ({ id, word: word.text }));
+        return new Promise((resolve) => {
+            pending.set(seq, { words, resolve });
+            ensureWorker().postMessage({ type: 'check', seq, words: checkWords });
+        });
+    }, {
+        // Schedule a fresh lint when relint() dispatches its effect. The hook covers the state changes that
+        // are not doc edits (the Worker became ready, a word was added or ignored); without it the linter
+        // only re-runs on a doc change, so an add-to-dictionary would never clear the standing underlines.
+        needsRefresh: (update) => update.transactions.some((tr) => tr.effects.some((e) => e.is(relintEffect))),
+    });
+    // The objective-error source: a second linter() over the SAME viewport-scoped prose spans the
+    // spellcheck source uses, so a doubled word inside a code fence is never flagged. It is synchronous
+    // and deterministic (no Worker, no dictionary), and its diagnostics carry `info` so they share the
+    // locked amber underline. It ships in the same returned extension as the spellcheck source, so the
+    // Task 7 toggle reconfigures one compartment to gate both surfaces at once.
+    const objectiveSource = linter((view) => {
+        const { text, spans } = visibleProseSpans(view);
+        return objectiveErrors(text, spans).map(buildObjectiveDiagnostic);
+    });
+    return [source, objectiveSource, lockedUnderlineTheme(EditorView)];
+}

package/dist/components/tidy-categorize.d.ts

@@ -0,0 +1,67 @@
+import type { Change } from './tidy-diff.js';
+import type { TidyConventions } from '../nav/site-config.js';
+/** A change's locally-inferred category. The first four are objective (safe to sweep); `normalization`
+ *  and `grammar` are judgment (held undecided, never swept by Accept-fixes). `normalization` carries
+ *  the convention key that authorized it, so the surface can name the setting and label the badge. */
+export type TidyCategory = {
+    kind: 'spelling';
+} | {
+    kind: 'typo';
+} | {
+    kind: 'doubled';
+} | {
+    kind: 'whitespace';
+} | {
+    kind: 'normalization';
+    convention: NormalizationKey;
+} | {
+    kind: 'grammar';
+};
+/** True for the objective categories: the safe, pre-kept, Accept-fixes-swept rank. A judgment
+ *  category (`normalization` or `grammar`) returns false. The bulk action and the surface both read
+ *  this, so the safety rank is one source of truth. */
+export declare function isObjective(category: TidyCategory): boolean;
+/** The enabled-convention keys a normalization can be attributed to. Each maps to one config field on
+ *  TidyConventions and to a because-line. A change is only ever labelled a normalization when it matches
+ *  one of these AND the config has the matching variant enabled; otherwise it is never a normalization. */
+export type NormalizationKey = 'oxfordComma' | 'numberStyle' | 'measurements' | 'percent' | 'emDash' | 'enDashRanges' | 'ellipsis' | 'timeFormat' | 'smartQuotes';
+/**
+ * Categorize one change against the captured original and the resolved conventions. The rules are
+ * deterministic and ordered by safety, objective first:
+ *   1. a pure whitespace change (both sides whitespace, or a whitespace insert/delete) is whitespace;
+ *   2. a removed repeated word (the original run is two of the same word collapsing to one) is doubled;
+ *   3. a single-token punctuation-only change is a typo;
+ *   4. a single word replaced by another single word is spelling;
+ *   5. a change matching an ENABLED config convention's signature is that convention's normalization;
+ *   6. anything else (a multi-token reword) is grammar.
+ * A change that looks like a normalization but whose convention is not enabled falls through to typo,
+ * spelling, or grammar by its shape, never to a normalization it cannot name. So the surface never
+ * offers a normalization that cannot cite an enabled setting.
+ */
+export declare function categorize(change: Change, original: string, conventions: TidyConventions): TidyCategory;
+/** The because-line data for a hunk: the convention's display name and the variant phrasing, both pure
+ *  strings derived from the config. The surface renders "Your <label> setting is <variant>, ..." from
+ *  these. Only a normalization carries a because-line; an objective or grammar hunk returns null (a
+ *  grammar hunk's rationale, when shown, is the local subject-verb note the surface composes, not a
+ *  config citation). */
+export interface BecauseLine {
+    /** The convention's display label, e.g. "Oxford-comma". */
+    label: string;
+    /** The setting's variant phrasing, e.g. "always" or "5 PM". */
+    variant: string;
+    /** The trailing clause describing what tidy did, e.g. the serial-comma effect. */
+    effect: string;
+}
+/**
+ * Build the because-line for a normalization category. Its ONLY data source is the config-declared
+ * setting that authorized the hunk: the convention key indexes the enabled variant on the conventions,
+ * and the line names that setting and variant. It NEVER counts the author's own usage. Counting the
+ * author's habit to justify a change is the harmonize-to-author judgment cairn must never make, so no
+ * code path here reads the buffer or any usage statistic; the conventions are the sole input. Returns
+ * null when the convention is somehow not enabled (defensive: categorize never produces such a hunk).
+ */
+export declare function buildBecause(key: NormalizationKey, conventions: TidyConventions): BecauseLine | null;
+/** The human badge label for a category, the word shown in the hunk's category pill. A normalization's
+ *  label is the convention's display name (its comma style, its time format), never "consistency" and
+ *  never a count. */
+export declare function categoryLabel(category: TidyCategory): string;