@sciflow/editor-start 0.0.3 → 0.1.1

package/dist/testing/external-widget-simulator.js

@@ -0,0 +1,350 @@
+/**
+ * @module external-widget-simulator
+ * @internal
+ *
+ * INTERNAL TESTING UTILITY — NOT STABLE PUBLIC API.
+ * This module is exported from the `@sciflow/editor-start` package solely to
+ * enable automated tests and the interactive demo page to verify light-DOM
+ * reachability.  Its API may change without a semver notice.  Do not depend on
+ * it in production code.
+ *
+ * A vanilla-JS simulator that models the three key behaviours of browser
+ * proofreading and AI writing extensions (e.g. Grammarly, the LanguageTool
+ * browser add-on, DeepL Write, etc.) when they interact with a page's
+ * editable surface.
+ *
+ * Design constraints
+ * ------------------
+ * - Zero runtime dependencies — only public web APIs.
+ * - Never traverses into any ShadowRoot.  Extensions operate exclusively on
+ *   the flat document tree; they have no access to shadow-DOM internals.
+ * - Suitable for both automated tests (jsdom / vitest) and manual in-browser
+ *   testing via the demo page.
+ *
+ * The three capabilities modelled
+ * --------------------------------
+ * 1. `discover(root?)` — walks the light DOM for editable targets exactly as a
+ *    real extension would: `querySelectorAll` on [contenteditable], textarea,
+ *    and text inputs, then filters to nodes whose root is the document (i.e.
+ *    not behind a shadow boundary).
+ *
+ * 2. `markRange(target, from, to, options?)` — draws underline-style overlay
+ *    markers over a character range inside a text node the way widgets render
+ *    grammar/spell highlights.  Uses Range + getClientRects() and places
+ *    absolutely-positioned <span> elements in an overlay layer that is a
+ *    sibling of the editable (never inside it).
+ *
+ * 3. DOM mutation operations that mimic extensions touching the editable
+ *    directly, bypassing the editor's own transaction mechanism:
+ *    - `injectMarker(target, from, to)` — wraps a text sub-range in a
+ *      `<span data-extn-marker="1">` (how widgets tag matches for hover
+ *      interactions without accepting/rejecting them yet).
+ *    - `applyCorrection(target, from, to, replacement)` — replaces a text
+ *      sub-range via raw Range manipulation (the "accept suggestion" action).
+ *
+ * Threat/usage model
+ * ------------------
+ * A ProseMirror contenteditable mounted inside a shadow root is INVISIBLE to
+ * extensions because they do not call `shadowRoot.querySelector`.  This
+ * simulator encodes that exact distinction: `discover()` returns only light-DOM
+ * editables whose `getRootNode() === document`.  The fact that a slotted
+ * element satisfies this condition while a shadow-buried element does not is
+ * the core regression guard for the light-DOM spike (Option B).
+ *
+ * jsdom limitation
+ * ----------------
+ * `getClientRects()` is not implemented in jsdom and always returns an empty
+ * DOMRectList.  `markRange()` therefore cannot be meaningfully tested in the
+ * standard vitest suite — it is exercised through the manual demo page instead.
+ * `discover()`, `injectMarker()`, and `applyCorrection()` are all jsdom-safe
+ * and form the automated test surface.
+ */
+// ---------------------------------------------------------------------------
+// 1. discover
+// ---------------------------------------------------------------------------
+/**
+ * Walk the light DOM for editable targets, exactly as browser extensions do.
+ *
+ * Extensions use `document.querySelectorAll` (or equivalent TreeWalker
+ * traversals) to find `[contenteditable]`, `textarea`, and `input[type=text]`.
+ * Critically, they do NOT call `shadowRoot.querySelectorAll` or otherwise
+ * traverse into shadow trees — they only see what is in the flat document tree.
+ *
+ * This function replicates that: it queries from `root` (defaulting to
+ * `document`) and then filters the results to those whose `getRootNode()` is
+ * the passed `root`.  An editable that lives inside a shadow root will NOT
+ * satisfy this condition and will NOT be returned.
+ *
+ * @param root  The root to query from.  Defaults to `document`.
+ * @returns     An array of `EditableTarget` objects for each discovered field.
+ *
+ * @example
+ * // Asserts the editor's contenteditable is reachable from the document root:
+ * const targets = discover(document);
+ * const ce = targets.find(t => t.element.hasAttribute('contenteditable'));
+ * assert(ce?.isLightDom === true);
+ * assert(ce?.rootNode === document);
+ */
+export function discover(root = document) {
+    // Determine both the query root and the "expected" root node.
+    //
+    // We cannot reliably use `instanceof Document` across different window
+    // contexts (e.g. jsdom creates its own Document subclass that does not share
+    // the identity of the global `Document`).  Instead we duck-type: a Document
+    // has no `ownerDocument` of its own, while an Element does.
+    //
+    // queryRoot  — the node we call querySelectorAll on (must support that API).
+    // expectedRoot — the node we expect `el.getRootNode()` to equal for a
+    //                light-DOM element.  For a Document this is the Document
+    //                itself; for an Element it is the Element's ownerDocument.
+    const isDocument = !('ownerDocument' in root && root.ownerDocument !== null);
+    const queryRoot = isDocument
+        ? root
+        : (root.ownerDocument ?? root);
+    const expectedRoot = isDocument
+        ? root
+        : (root.ownerDocument ?? root);
+    const results = [];
+    // Selector mirrors what real extensions use:
+    //  - [contenteditable] covers both contenteditable="true" and contenteditable=""
+    //  - textarea
+    //  - input[type=text] (and inputs without an explicit type, which default to text)
+    const elements = queryRoot.querySelectorAll('[contenteditable], textarea, input[type=text], input:not([type])');
+    for (const el of Array.from(elements)) {
+        const rootNode = el.getRootNode();
+        results.push({
+            element: el,
+            rootNode,
+            isLightDom: rootNode === expectedRoot,
+        });
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// 2. markRange  (overlay positioning — in-browser only; jsdom returns empty rects)
+// ---------------------------------------------------------------------------
+/**
+ * Position overlay underline markers over a character range inside `target`.
+ *
+ * Mimics how extensions draw underlines: they create a DOM Range, call
+ * `getClientRects()` to obtain the line boxes, and then absolutely-position
+ * overlay `<span>` elements in a sibling container at those coordinates.
+ * Critically, the overlay is NOT inserted inside the contenteditable — it is
+ * a sibling to avoid invalidating the editable's DOM tree from the extension's
+ * perspective.
+ *
+ * NOTE: `getClientRects()` always returns an empty list in jsdom.  This
+ * function is a no-op in that environment and is intended for manual
+ * in-browser verification via the demo page.  The automated test suite
+ * tests `discover`, `injectMarker`, and `applyCorrection` instead.
+ *
+ * @param target   The editable element to overlay.
+ * @param from     Character offset (from the start of `target.textContent`) of
+ *                 the range start.
+ * @param to       Character offset of the range end.
+ * @param options  Visual options.
+ * @returns        The overlay container element, or `null` when `getClientRects`
+ *                 returned nothing (jsdom / hidden element).
+ */
+export function markRange(target, from, to, options = {}) {
+    const { color = '#ef4444', offsetY = 2, zIndex = '9999' } = options;
+    const range = resolveCharRange(target, from, to);
+    if (!range)
+        return null;
+    const rects = Array.from(range.getClientRects());
+    if (rects.length === 0)
+        return null; // jsdom / invisible element
+    // Ensure the overlay container exists as a sibling of the editable.
+    let overlay = target.parentElement?.querySelector('[data-extn-overlay]');
+    if (!overlay) {
+        overlay = document.createElement('div');
+        overlay.setAttribute('data-extn-overlay', '');
+        overlay.style.cssText = `
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 0;
+      height: 0;
+      overflow: visible;
+      pointer-events: none;
+      z-index: ${zIndex};
+    `;
+        target.parentElement?.appendChild(overlay);
+    }
+    for (const rect of rects) {
+        const marker = document.createElement('span');
+        marker.setAttribute('data-extn-underline', '');
+        marker.style.cssText = `
+      position: fixed;
+      left: ${rect.left}px;
+      top: ${rect.bottom + offsetY}px;
+      width: ${rect.width}px;
+      height: 2px;
+      background: ${color};
+      border-radius: 1px;
+      pointer-events: none;
+    `;
+        overlay.appendChild(marker);
+    }
+    return overlay;
+}
+// ---------------------------------------------------------------------------
+// 3a. injectMarker
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a character sub-range of `target` in a `<span data-extn-marker="1">`.
+ *
+ * This is what extensions do to tag a match for subsequent accept/reject
+ * interactions — they insert a wrapper span *inside* the contenteditable via
+ * raw DOM Range manipulation without going through the editor's transaction
+ * system.
+ *
+ * From ProseMirror's perspective this is a foreign DOM mutation.  ProseMirror's
+ * DOMObserver will observe the mutation and attempt to reconcile its internal
+ * model.  The mutation-tolerance tests in the spec verify that this does not
+ * corrupt the document or cause PM to throw.
+ *
+ * @param target   The contenteditable element to mutate.
+ * @param from     Character offset of the range start (within `target.textContent`).
+ * @param to       Character offset of the range end.
+ * @returns        An `InjectedMarker` handle with a `remove()` method for cleanup.
+ *                 Returns `null` when the range cannot be resolved.
+ */
+export function injectMarker(target, from, to) {
+    const range = resolveCharRange(target, from, to);
+    if (!range)
+        return null;
+    const span = document.createElement('span');
+    span.setAttribute('data-extn-marker', '1');
+    try {
+        range.surroundContents(span);
+    }
+    catch {
+        // surroundContents throws if the range crosses element boundaries.
+        // Fall back to extracting and wrapping manually.
+        const fragment = range.extractContents();
+        span.appendChild(fragment);
+        range.insertNode(span);
+    }
+    return {
+        span,
+        remove() {
+            if (!span.parentNode)
+                return;
+            const frag = document.createDocumentFragment();
+            while (span.firstChild)
+                frag.appendChild(span.firstChild);
+            span.parentNode.replaceChild(frag, span);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 3b. applyCorrection
+// ---------------------------------------------------------------------------
+/**
+ * Replace a character sub-range of `target` with `replacement` via raw DOM.
+ *
+ * This is the "accept suggestion" operation: the extension overwrites a word
+ * by creating a Range, deleting its contents, and inserting a new text node.
+ * It does NOT fire a ProseMirror transaction.
+ *
+ * The test that calls this should follow up with a normal PM transaction (e.g.
+ * `view.dispatch(view.state.tr.insertText(...))`) to verify that ProseMirror
+ * reconciles the foreign mutation cleanly and does not produce corrupted or
+ * duplicated content.
+ *
+ * @param target       The contenteditable element.
+ * @param from         Character offset of the range to replace.
+ * @param to           Character offset of the range end.
+ * @param replacement  The text to insert in place of the matched range.
+ * @returns            A `CorrectionResult` describing what was swapped, or
+ *                     `null` when the range cannot be resolved.
+ */
+export function applyCorrection(target, from, to, replacement) {
+    const range = resolveCharRange(target, from, to);
+    if (!range)
+        return null;
+    const replaced = range.toString();
+    range.deleteContents();
+    range.insertNode(document.createTextNode(replacement));
+    return { replaced, inserted: replacement };
+}
+/**
+ * Find all occurrences of `searchString` within `target.textContent` and
+ * return their character-offset ranges.
+ *
+ * This is the bridge between "a word I want to underline" and the `{from, to}`
+ * pair that `markRange`, `injectMarker`, and `applyCorrection` consume.
+ * Extensions compute positions exactly this way: read the full `textContent`
+ * of the editable as one flat string, locate every match, then use those
+ * offsets to build DOM Ranges.
+ *
+ * @param target        The element whose `textContent` is searched.
+ * @param searchString  The literal string to find (case-sensitive).
+ * @returns             Array of `{from, to}` ranges, one per occurrence,
+ *                      in document order.  Empty array when there are no matches.
+ *
+ * @example
+ * const hits = findTextOccurrences(editable, 'SciFlow');
+ * for (const { from, to } of hits) {
+ *   markRange(editable, from, to, { color: '#f97316' });
+ * }
+ */
+export function findTextOccurrences(target, searchString) {
+    if (!searchString)
+        return [];
+    const text = target.textContent ?? '';
+    const results = [];
+    let pos = 0;
+    while (pos <= text.length - searchString.length) {
+        const idx = text.indexOf(searchString, pos);
+        if (idx === -1)
+            break;
+        results.push({ from: idx, to: idx + searchString.length });
+        pos = idx + 1; // advance by 1 to find overlapping matches too
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a character-offset range within `target.textContent` to a DOM
+ * `Range` object, walking the element's text nodes.
+ *
+ * Character offsets are counted across all text nodes in document order,
+ * which matches how extensions typically calculate positions (they read
+ * `textContent` as a single string, then locate the text node containing
+ * each offset).
+ */
+function resolveCharRange(target, from, to) {
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_TEXT);
+    let offset = 0;
+    let startNode = null;
+    let startOffset = 0;
+    let endNode = null;
+    let endOffset = 0;
+    let node;
+    // eslint-disable-next-line no-cond-assign
+    while ((node = walker.nextNode())) {
+        const text = node;
+        const len = text.nodeValue?.length ?? 0;
+        if (startNode === null && offset + len > from) {
+            startNode = text;
+            startOffset = from - offset;
+        }
+        if (endNode === null && offset + len >= to) {
+            endNode = text;
+            endOffset = to - offset;
+            break;
+        }
+        offset += len;
+    }
+    // Also handle the case where `to` falls exactly at the start of a node.
+    if (startNode === null || endNode === null)
+        return null;
+    const range = document.createRange();
+    range.setStart(startNode, startOffset);
+    range.setEnd(endNode, endOffset);
+    return range;
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@sciflow/editor-start",
-  "version": "0.0.3",
+  "version": "0.1.1",
+  "license": "MIT",
   "private": false,
   "homepage": "https://docs.sciflow.org",
   "type": "module",
@@ -24,6 +25,8 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.fixtures.*",
+    "!dist/**/*.tsbuildinfo",
     "bin",
     "THIRD_PARTY_LICENSES"
   ],
@@ -49,11 +52,12 @@
       "bundle": {
         "executor": "nx:run-commands",
         "outputs": [
-          "{projectRoot}/dist/bundle"
+          "{projectRoot}/dist/bundle",
+          "{projectRoot}/demo/build"
         ],
         "options": {
           "cwd": "packages/editor/start",
-          "command": "echo 'Building bundle...' && vite build --config vite.config.ts --mode production && echo 'Bundle complete!'"
+          "command": "echo 'Building bundle...' && vite build --config vite.config.ts --mode production && echo 'Building demo import bundle...' && vite build --config vite.import.config.ts --mode production && echo 'Bundle complete!'"
         },
         "configurations": {
           "watch": {
@@ -72,7 +76,7 @@
           "cwd": "packages/editor/start",
           "parallel": true,
           "commands": [
-            "tsc --build ../../core/tsconfig.lib.json --watch",
+            "tsc --build ../core/tsconfig.lib.json --watch",
             "vite build --config vite.config.ts --watch",
             "vite dev --open"
           ]
@@ -92,24 +96,32 @@
     }
   },
   "dependencies": {
+    "@sciflow/schema-core": "0.1.1",
     "lit": "^3.2.1",
     "prosemirror-commands": "1.7.1",
     "prosemirror-keymap": "1.2.3",
-    "prosemirror-state": "1.4.4",
-    "prosemirror-view": "1.41.8",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "@sciflow/editor-core": "0.0.3",
-    "@sciflow/schema-prosemirror": "0.0.3",
-    "prosemirror-model": "^1.25.4"
+    "@sciflow/editor-core": "0.1.1",
+    "@sciflow/schema-prosemirror": "0.1.1",
+    "prosemirror-model": "1.25.8",
+    "prosemirror-state": "1.4.4",
+    "prosemirror-view": "1.41.8"
   },
   "devDependencies": {
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/theme-one-dark": "^6.1.3",
     "@material-symbols/svg-400": "^0.44.0",
-    "@sciflow/editor-core": "0.0.3",
-    "@sciflow/schema-prosemirror": "0.0.3",
+    "@sciflow/editor-core": "0.1.1",
+    "@sciflow/pandoc-web": "0.1.1",
+    "@sciflow/schema-prosemirror": "0.1.1",
+    "codemirror": "^6.0.2",
     "jsdom": "^29.0.2",
-    "prosemirror-model": "1.25.4",
-    "vitest": "^4.1.3"
+    "prosemirror-model": "1.25.8",
+    "vitest": "^4.1.3",
+    "prosemirror-state": "1.4.4",
+    "prosemirror-view": "1.41.8"
   }
 }

package/dist/lib/test-fixtures/soak-documents.d.ts

@@ -1,13 +0,0 @@
-import type { SciFlowDocJSON } from '@sciflow/editor-core';
-type SoakDocSize = {
-    headingCount: number;
-    paragraphsPerHeading: number;
-    wordsPerParagraph: number;
-    figureEvery: number;
-};
-export declare const createSoakDocFixture: (size: SoakDocSize) => SciFlowDocJSON;
-export declare const SMALL_SOAK_DOC: SciFlowDocJSON;
-export declare const MEDIUM_SOAK_DOC: SciFlowDocJSON;
-export declare const LARGE_SOAK_DOC: SciFlowDocJSON;
-export {};
-//# sourceMappingURL=soak-documents.d.ts.map

package/dist/lib/test-fixtures/soak-documents.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"soak-documents.d.ts","sourceRoot":"","sources":["../../../src/lib/test-fixtures/soak-documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,KAAK,WAAW,GAAG;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAoCF,eAAO,MAAM,oBAAoB,GAAI,MAAM,WAAW,KAAG,cAwBxD,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAK3B,CAAC;AAEH,eAAO,MAAM,eAAe,EAAE,cAK5B,CAAC;AAEH,eAAO,MAAM,cAAc,EAAE,cAK3B,CAAC"}

package/dist/lib/test-fixtures/soak-documents.js

@@ -1,69 +0,0 @@
-const WORD = 'sciflow';
-const paragraphText = (wordCount) => Array.from({ length: wordCount }, () => WORD).join(' ');
-const createParagraph = (wordCount) => ({
-    type: 'paragraph',
-    attrs: { id: null },
-    content: [{ type: 'text', text: paragraphText(wordCount) }],
-});
-const createFigure = (id, caption) => ({
-    type: 'figure',
-    attrs: {
-        id,
-        src: `https://example.com/${id}.png`,
-        alt: caption,
-        type: 'figure',
-        orientation: 'portrait',
-    },
-    content: [
-        {
-            type: 'caption',
-            content: [
-                {
-                    type: 'paragraph',
-                    attrs: { id: null },
-                    content: [{ type: 'text', text: caption }],
-                },
-            ],
-        },
-    ],
-});
-export const createSoakDocFixture = (size) => {
-    const content = [];
-    for (let headingIndex = 0; headingIndex < size.headingCount; headingIndex += 1) {
-        const headingId = `section-${headingIndex + 1}`;
-        content.push({
-            type: 'heading',
-            attrs: { level: ((headingIndex % 3) + 1), id: headingId },
-            content: [{ type: 'text', text: `Section ${headingIndex + 1}` }],
-        });
-        for (let paragraphIndex = 0; paragraphIndex < size.paragraphsPerHeading; paragraphIndex += 1) {
-            content.push(createParagraph(size.wordsPerParagraph));
-        }
-        if ((headingIndex + 1) % size.figureEvery === 0) {
-            const figureId = `figure-${headingIndex + 1}`;
-            content.push(createFigure(figureId, `Figure for ${headingId}`));
-        }
-    }
-    return {
-        type: 'doc',
-        content,
-    };
-};
-export const SMALL_SOAK_DOC = createSoakDocFixture({
-    headingCount: 6,
-    paragraphsPerHeading: 2,
-    wordsPerParagraph: 25,
-    figureEvery: 3,
-});
-export const MEDIUM_SOAK_DOC = createSoakDocFixture({
-    headingCount: 20,
-    paragraphsPerHeading: 4,
-    wordsPerParagraph: 40,
-    figureEvery: 2,
-});
-export const LARGE_SOAK_DOC = createSoakDocFixture({
-    headingCount: 60,
-    paragraphsPerHeading: 6,
-    wordsPerParagraph: 50,
-    figureEvery: 2,
-});