@glw907/cairn-cms 0.58.0 → 0.60.0

package/dist/components/spellcheck-assets/spellchecker-wasm-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Justin Wilaby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/components/spellcheck-worker.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The thin engine seam. The handler talks only to this interface, so the merged-set logic is a pure
+ * unit and any dialect-dictionary backend (spellchecker-wasm today, nspell tomorrow) can drop in.
+ */
+export interface SpellEngine {
+    /** True when the word is correct per the loaded dialect dictionary (case-insensitive). */
+    check(word: string): boolean;
+    /** Ranked replacement terms for the word, the word itself dropped. */
+    suggest(word: string): string[];
+}
+/** A batch spell check: each word carries a caller-side id so answers map back in any order. */
+interface CheckMessage {
+    readonly type: 'check';
+    readonly seq: number;
+    readonly words: ReadonlyArray<{
+        readonly id: number;
+        readonly word: string;
+    }>;
+}
+/** A suggestion request for a single word. */
+interface SuggestMessage {
+    readonly type: 'suggest';
+    readonly seq: number;
+    readonly word: string;
+}
+/** Add a word (or a batch) to the in-memory personal dictionary, so a later check answers correct. */
+interface AddWordMessage {
+    readonly type: 'addWord';
+    readonly word?: string;
+    readonly words?: ReadonlyArray<string>;
+}
+/** Add a word to the in-memory session ignore list, so a later check answers correct for it. */
+interface IgnoreWordMessage {
+    readonly type: 'ignoreWord';
+    readonly word: string;
+}
+/** A message the handler can act on without the engine (every kind except init). */
+type HandlerMessage = CheckMessage | SuggestMessage | AddWordMessage | IgnoreWordMessage;
+/** The init ack, posted once the dictionary has streamed in and lookups are live. */
+interface ReadyMessage {
+    readonly type: 'ready';
+}
+/** The check answer: one verdict per requested word, correctness keyed by the caller's id. */
+interface CheckResult {
+    readonly type: 'checked';
+    readonly seq: number;
+    readonly results: ReadonlyArray<{
+        readonly id: number;
+        readonly correct: boolean;
+    }>;
+}
+/** The suggest answer: a ranked list of replacement terms for the word. */
+interface SuggestResult {
+    readonly type: 'suggested';
+    readonly seq: number;
+    readonly word: string;
+    readonly suggestions: ReadonlyArray<string>;
+}
+/** An init or lookup failure, surfaced to the main thread rather than thrown into the void. */
+interface ErrorResult {
+    readonly type: 'error';
+    readonly detail: string;
+}
+export type OutboundMessage = ReadyMessage | CheckResult | SuggestResult | ErrorResult;
+/** A capturing sink for outbound messages, so the handler never references `self` or `Worker`. */
+type Post = (message: OutboundMessage) => void;
+/**
+ * The pure message handler. It owns the personal dictionary and the session ignore set and answers
+ * `check`/`suggest`/`addWord`/`ignoreWord` against the injected engine. It holds NO reference to a
+ * Worker context: it posts through the sink it is handed, so a test drives it with a fake engine and
+ * a capturing post.
+ *
+ * The merged set is layered: dialect (the engine), then site/personal, then session ignore. For a
+ * boolean correctness verdict the order does not change the answer, but the layers are kept distinct
+ * so the source of a verdict stays clear (and a future per-layer behavior has somewhere to live).
+ */
+export declare function createSpellcheckHandler(engine: SpellEngine): {
+    handle(message: HandlerMessage, post: Post): void;
+};
+export {};

package/dist/components/spellcheck-worker.js

@@ -0,0 +1,161 @@
+// The spellcheck Web Worker. It owns the spellchecker-wasm (SymSpell) instance and the dictionary,
+// so the main thread never holds the 1.5MB corpus and never runs a lookup on the typing thread.
+//
+// This module is loaded the same dynamic-import way CodeMirror is: the editor constructs it with
+// `new Worker(new URL('./spellcheck-worker.js', import.meta.url), { type: 'module' })`, and the
+// consumer build (Vite) resolves and emits this file plus the wasm and dictionary it fetches. The
+// wasm and dictionary are NEVER bundled into this JS; they arrive as two `fetch` Responses whose URLs
+// the main thread passes in the `init` message, so they stay out-of-bundle fetched assets.
+//
+// spellchecker-wasm's browser entry is CommonJS and its class is not reachable as a typed named
+// export under NodeNext, so the surface is typed structurally and the dynamic import is cast, the
+// same pattern the carta editor uses.
+//
+// The Worker owns the MERGED SET, not just the dialect dictionary: a word is correct if the engine
+// (the loaded dialect dictionary) says so, OR it is in the personal dictionary, OR it is in the
+// session ignore list. The layering and message handling live in a pure handler factory below so
+// they unit-test without a Worker or wasm; the engine sits behind a thin interface so the real wasm
+// wrapper is injected in production and a fake is injected in tests (and nspell could drop in too).
+// Drives the check path. `includeSelf: true` makes a known word return itself at edit distance 0, so
+// correctness is a distance-0 self match rather than the absence of suggestions (a rare misspelling
+// can also return no suggestions). Verbosity Closest keeps the suggestion set tight.
+const CHECK_OPTIONS = {
+    verbosity: 1,
+    maxEditDistance: 2,
+    includeUnknown: false,
+    includeSelf: true,
+};
+// Drives the suggest path. `includeSelf: false` drops the word itself, so the list is replacements.
+const SUGGEST_OPTIONS = {
+    verbosity: 1,
+    maxEditDistance: 2,
+    includeUnknown: false,
+    includeSelf: false,
+};
+/**
+ * The pure message handler. It owns the personal dictionary and the session ignore set and answers
+ * `check`/`suggest`/`addWord`/`ignoreWord` against the injected engine. It holds NO reference to a
+ * Worker context: it posts through the sink it is handed, so a test drives it with a fake engine and
+ * a capturing post.
+ *
+ * The merged set is layered: dialect (the engine), then site/personal, then session ignore. For a
+ * boolean correctness verdict the order does not change the answer, but the layers are kept distinct
+ * so the source of a verdict stays clear (and a future per-layer behavior has somewhere to live).
+ */
+export function createSpellcheckHandler(engine) {
+    const personal = new Set();
+    const ignored = new Set();
+    function isCorrect(word) {
+        const lower = word.toLowerCase();
+        // Dialect first, then personal, then ignore. Sets are matched lowercased to mirror the engine's
+        // case-insensitive lookup, so "Cairn" added once answers for "cairn".
+        return engine.check(word) || personal.has(lower) || ignored.has(lower);
+    }
+    return {
+        handle(message, post) {
+            switch (message.type) {
+                case 'check': {
+                    const results = message.words.map(({ id, word }) => ({ id, correct: isCorrect(word) }));
+                    post({ type: 'checked', seq: message.seq, results });
+                    break;
+                }
+                case 'suggest': {
+                    post({
+                        type: 'suggested',
+                        seq: message.seq,
+                        word: message.word,
+                        suggestions: engine.suggest(message.word),
+                    });
+                    break;
+                }
+                case 'addWord': {
+                    if (message.word)
+                        personal.add(message.word.toLowerCase());
+                    if (message.words)
+                        for (const w of message.words)
+                            personal.add(w.toLowerCase());
+                    break;
+                }
+                case 'ignoreWord': {
+                    ignored.add(message.word.toLowerCase());
+                    break;
+                }
+            }
+        },
+    };
+}
+/**
+ * The real engine: the spellchecker-wasm wrapper. SymSpell calls a result handler synchronously after
+ * each lookup, so the wrapper captures the most recent items in a closure variable and reads them
+ * right after `checkSpelling()` returns. This is the production engine handed to the handler on init.
+ */
+function createWasmEngine(instance, latest) {
+    return {
+        check(word) {
+            latest.items = [];
+            instance.checkSpelling(word, CHECK_OPTIONS);
+            // A word is correct when the lookup returns it unchanged at edit distance 0 (case-insensitive).
+            const lower = word.toLowerCase();
+            return latest.items.some((item) => item.distance === 0 && item.term.toLowerCase() === lower);
+        },
+        suggest(word) {
+            latest.items = [];
+            instance.checkSpelling(word, SUGGEST_OPTIONS);
+            // SymSpell returns the items ranked by edit distance then frequency. Drop the word itself (a
+            // distance-0 self match) so the list is replacements only.
+            const lower = word.toLowerCase();
+            return latest.items.filter((item) => item.term.toLowerCase() !== lower).map((item) => item.term);
+        },
+    };
+}
+async function createEngine(message) {
+    // The browser class accepts fetch Responses for both assets and streams the dictionary into wasm
+    // memory in chunks, so the 1.5MB corpus is never held as one JS string. Import the class module
+    // directly, not the package's `browser/index.js` UMD bundle: that bundle's UMD prelude references
+    // `window` as the global root, which is undefined in a Worker. The class module is plain CommonJS
+    // that Vite interops, so it loads off the main thread cleanly.
+    const mod = (await import('spellchecker-wasm/lib/browser/SpellcheckerWasm.js'));
+    const latest = { items: [] };
+    const instance = new mod.SpellcheckerWasm((items) => {
+        latest.items = items;
+    });
+    const [wasmResponse, dictionaryResponse] = await Promise.all([
+        fetch(message.wasmUrl),
+        fetch(message.dictionaryUrl),
+    ]);
+    await instance.prepareSpellchecker(wasmResponse, dictionaryResponse);
+    return createWasmEngine(instance, latest);
+}
+// The module-scope wiring runs only inside a Worker, where `self` and `addEventListener` exist. It is
+// guarded so this module imports cleanly in node (the unit test imports the handler factory and the
+// engine seam without a Worker context). On `init` it constructs the real wasm engine and a handler
+// bound to it; every other message is delegated to the handler, which posts back through `self`.
+if (typeof self !== 'undefined' && typeof self.addEventListener === 'function') {
+    const worker = self;
+    const post = (message) => worker.postMessage(message);
+    let handler = null;
+    worker.addEventListener('message', (event) => {
+        const message = event.data;
+        try {
+            if (message.type === 'init') {
+                void createEngine(message)
+                    .then((engine) => {
+                    handler = createSpellcheckHandler(engine);
+                    post({ type: 'ready' });
+                })
+                    .catch((err) => {
+                    post({ type: 'error', detail: err instanceof Error ? err.message : String(err) });
+                });
+            }
+            else if (!handler) {
+                post({ type: 'error', detail: 'spellchecker not ready' });
+            }
+            else {
+                handler.handle(message, post);
+            }
+        }
+        catch (err) {
+            post({ type: 'error', detail: err instanceof Error ? err.message : String(err) });
+        }
+    });
+}

package/dist/components/spellcheck.d.ts

@@ -0,0 +1,146 @@
+import type { Tree } from '@lezer/common';
+import type { Diagnostic } from '@codemirror/lint';
+import type { Extension } from '@codemirror/state';
+import { type ObjectiveError } from './objective-errors.js';
+/** An absolute character range in the document. */
+export interface Range {
+    from: number;
+    to: number;
+}
+/** A word extracted for lookup: the lowercased form the Worker checks, and its absolute range so a
+ *  verdict maps straight back to an underline. */
+export interface ExtractedWord {
+    /** The lowercased word, as the engine's case-insensitive lookup expects. */
+    text: string;
+    from: number;
+    to: number;
+}
+/**
+ * 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 declare function classifyProse(text: string, tree: Tree, from: number, to: number): Range[];
+/** 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 declare function spellcheckRanges(text: string, tree: Tree): Range[];
+/**
+ * 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 declare function extractWords(text: string, from: number, to: number): ExtractedWord[];
+/** The callbacks the management actions invoke. The lint source supplies these so the pure builder
+ *  never touches the Worker or the re-lint mechanism: it only wires the buttons to these handlers. */
+export interface SpellDiagnosticActions {
+    /** Add the word to the personal dictionary (posts addWord, records the pending addition, re-lints). */
+    onAddWord(word: string): void;
+    /** Ignore the word for this session only (posts ignoreWord, re-lints). */
+    onIgnoreWord(word: string): void;
+}
+/**
+ * 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 declare function buildSpellDiagnostic(word: string, range: Range, suggestions: readonly string[], callbacks: SpellDiagnosticActions): Diagnostic;
+/**
+ * The latest-wins arbiter (the media-preview settling pattern). The lint source hands out a
+ * monotonic seq with {@link next} on each run and posts it on the check message; when a `checked`
+ * answer lands, {@link accept} returns true only for the highest seq seen, so a stale answer from an
+ * older document state is dropped and the underlines never lag the text. Pure, so the seq logic
+ * unit-tests without a Worker.
+ */
+export interface SeqArbiter {
+    /** The next monotonic seq, recorded as the current run. */
+    next(): number;
+    /** True when this seq is still the latest one issued or accepted, false for a stale answer. */
+    accept(seq: number): boolean;
+}
+/** Build a fresh {@link SeqArbiter}. */
+export declare function arbitrateChecked(): SeqArbiter;
+/**
+ * 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 declare function buildObjectiveDiagnostic(error: ObjectiveError): Diagnostic;
+/** The narrow Worker surface the lint source drives: it posts check, suggest, addWord, and ignoreWord
+ *  messages and listens for the answers. A `suggest` answer is a one-shot, so the source removes its
+ *  own listener once it lands. A test injects a fake; production injects a real Worker. */
+export interface SpellWorker {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** 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 declare function createSpellWorker(): SpellWorker;
+/** The real wasm asset URL, resolved module-relative the same way the worker is. */
+export declare function resolveWasmUrl(): string;
+/** 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 declare function resolveDictionaryUrl(dictionaryFile: string): string;
+/** Options for {@link cairnSpellcheck}, so the unit and component layers can inject a fake Worker
+ *  factory in place of the real `new Worker(...)`. */
+export interface SpellcheckOptions {
+    /** The Worker factory; defaults to {@link createSpellWorker}. Created lazily on the first lint. */
+    createWorker?: () => SpellWorker;
+    /** The pending personal-dictionary additions, owned by the caller. When an author chooses "Add to
+     *  dictionary" the source posts addWord to the Worker (the underline clears at once) and records the
+     *  word here. The set is the seam Task 9 commits to the git-backed dictionary file; this source only
+     *  fills it and never persists. A caller that does not pass one gets a fresh internal set. */
+    pendingAdditions?: Set<string>;
+    /** The committed personal-dictionary words (spec 1.6) the source seeds the Worker's personal layer
+     *  with, posted as one batch `addWord` right after `init`. The git-backed site dictionary is the
+     *  durable layer; the editor reads it at load (EditData.siteDictionary) and hands it here, so a word
+     *  another editor committed answers correct from the first lint. Empty by default (dialect-only). */
+    siteWords?: ReadonlyArray<string>;
+    /** The dialect-resolved dictionary filename, e.g. "dictionary-en-us.txt". The source resolves it to
+     *  a real asset URL and posts it in the Worker's `init`. Defaults to US English. */
+    dictionaryFile?: string;
+    /** Override the resolved wasm and dictionary URLs the source posts in `init`. The real resolution
+     *  uses {@link resolveWasmUrl}/{@link resolveDictionaryUrl} (module-relative `import.meta.url`); a
+     *  component test that injects a fake Worker can pass canned URLs so it never touches the asset
+     *  resolver. */
+    assetUrls?: {
+        wasmUrl: string;
+        dictionaryUrl: string;
+    };
+    /** Treat the Worker as ready without waiting for a `ready` message. The production path is strict
+     *  (it posts `init` and waits for `ready` before painting); a fake Worker in a test that does not
+     *  answer `ready` can set this so a lint run is not held back. Defaults to false. */
+    assumeReady?: boolean;
+    /** The already-loaded CodeMirror modules to reuse instead of importing them again. The editor
+     *  component loads `@codemirror/view`/`@codemirror/language` for its own extensions, so passing them
+     *  here keeps the lint source on the SAME module instances; a second dynamic import can resolve to a
+     *  separate copy (the test bundler's dedup quirk), and CodeMirror's instanceof checks then reject the
+     *  extension. When omitted, the source imports them itself (the standalone path). `@codemirror/lint`
+     *  is loaded here when not supplied, since the editor does not otherwise need it. */
+    modules?: {
+        lint?: typeof import('@codemirror/lint');
+        language?: typeof import('@codemirror/language');
+        view?: typeof import('@codemirror/view');
+        state?: typeof import('@codemirror/state');
+    };
+}
+/**
+ * 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 declare function cairnSpellcheck(options?: SpellcheckOptions): Promise<Extension>;