@sciflow/editor-start 0.0.3 → 0.1.1

package/dist/lib/format-bar.js

@@ -59,6 +59,16 @@ let SciFlowFormatBarElement = class SciFlowFormatBarElement extends LitElement {
         super(...arguments);
         /** Reference to the editor element. May be passed directly via property binding. */
         this.editor = null;
+        /**
+         * Space- or comma-separated list of command-metadata `group` names to omit
+         * from rendering (e.g. `"align"`). Suppresses the toolbar buttons for that
+         * group without touching command registration — the commands stay
+         * schema-legal and remain reachable via `editor.commands`/`runner.available()`.
+         * Use this for structured-manuscript contexts (e.g. a JATS-based export)
+         * where a UI-exposed capability isn't representable in the export content
+         * model. See docs/pages/user-guide/web-component-api.md.
+         */
+        this.hiddenGroups = '';
         this.selectionVersion = 0;
         this.styleMenuOpen = false;
         this.insertMenuOpen = false;
@@ -109,7 +119,7 @@ let SciFlowFormatBarElement = class SciFlowFormatBarElement extends LitElement {
      */
     render() {
         const runner = this.getCommandRunner();
-        const commandMetadata = runner?.commandsMeta?.() ?? {};
+        const commandMetadata = this.filterHiddenGroups(runner?.commandsMeta?.() ?? {});
         const commandGroups = this.getCommandGroups(commandMetadata);
         const tableGroup = 'table';
         const mediaGroup = 'media';
@@ -255,6 +265,13 @@ let SciFlowFormatBarElement = class SciFlowFormatBarElement extends LitElement {
     /* --------------------------------------------------------- */
     /*  Insert dropdown (icon + chevron → popover)               */
     /* --------------------------------------------------------- */
+    /**
+     * The trigger shows the localised "Insert" label next to the `+` icon: the
+     * word only appeared on the menu items before, leaving sighted users with a
+     * bare glyph. The visible label and `aria-label` are read from the same key,
+     * so they cannot diverge — and because `aria-label` replaces a button's text
+     * content for assistive tech, the word is still announced exactly once.
+     */
     renderInsertDropdown(runner, metadata) {
         const availability = runner?.available?.() ?? null;
         // Collect block-level insert commands (media group + table insert + footnote)
@@ -275,25 +292,32 @@ let SciFlowFormatBarElement = class SciFlowFormatBarElement extends LitElement {
           @click=${this.toggleInsertMenu}
         >
           <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="12" y1="5" x2="12" y2="19"></line><line x1="5" y1="12" x2="19" y2="12"></line></svg>
+          <span class="insert-dropdown-label">${t('formatBar.insert')}</span>
           <span class="dropdown-chevron">${chevronSvg}</span>
         </button>
         ${this.insertMenuOpen
             ? html `
-            <div class="insert-dropdown-menu" role="menu">
+            <div class="insert-dropdown-menu" role="menu" aria-label=${t('formatBar.insert')}>
               ${insertCommands.map(([name, meta]) => {
                 const canExecute = availability?.[name] ? availability[name]() : true;
+                // The trigger above already says "Insert", so an item shows its
+                // short wording when the command offers one ("Figure", not
+                // "Insert figure"). The full label stays the accessible name,
+                // so nothing is lost for a screen-reader user.
+                const fullLabel = meta?.label ?? name;
                 return html `
                   <button
                     type="button"
                     role="menuitem"
                     class="insert-menu-item"
+                    aria-label=${fullLabel}
                     ?disabled=${!canExecute}
                     @click=${() => this.executeInsertCommand(name, runner)}
                   >
                     ${meta?.icon && materialIcons[meta.icon]
                     ? html `<span class="cmd-icon" aria-hidden="true">${unsafeHTML(materialIcons[meta.icon])}</span>`
                     : nothing}
-                    ${meta?.label ?? name}
+                    ${meta?.shortLabel ?? fullLabel}
                   </button>
                 `;
             })}
@@ -663,6 +687,29 @@ let SciFlowFormatBarElement = class SciFlowFormatBarElement extends LitElement {
       </button>
     `;
     }
+    /**
+     * Parse the `hidden-groups` attribute into a set of group names to suppress.
+     * Accepts whitespace- and/or comma-separated values (e.g. `"align table"`, `"align,table"`).
+     */
+    get hiddenGroupSet() {
+        return new Set(this.hiddenGroups
+            .split(/[\s,]+/)
+            .map((group) => group.trim())
+            .filter(Boolean));
+    }
+    /**
+     * Drop metadata entries whose `group` is listed in `hidden-groups` before any
+     * rendering derivation runs. This is a rendering-only filter: it does not touch
+     * command registration, so hidden commands stay schema-legal and remain reachable
+     * via `editor.commands`/`runner.available()` — only the toolbar buttons disappear.
+     */
+    filterHiddenGroups(metadata) {
+        const hidden = this.hiddenGroupSet;
+        if (hidden.size === 0) {
+            return metadata;
+        }
+        return Object.fromEntries(Object.entries(metadata).filter(([, meta]) => !meta?.group || !hidden.has(meta.group)));
+    }
     /**
      * Determine which groups should be displayed and in which order based on command metadata.
      */
@@ -699,6 +746,9 @@ __decorate([
 __decorate([
     property({ type: String, attribute: 'for' })
 ], SciFlowFormatBarElement.prototype, "for", void 0);
+__decorate([
+    property({ type: String, attribute: 'hidden-groups' })
+], SciFlowFormatBarElement.prototype, "hiddenGroups", void 0);
 __decorate([
     state()
 ], SciFlowFormatBarElement.prototype, "selectionVersion", void 0);

package/dist/lib/outline.d.ts

@@ -69,6 +69,23 @@ export declare class SciFlowOutlineElement extends LitElement {
     private localeListener?;
     private themeUnsub?;
     private themeStyleElements;
+    /**
+     * Re-attempts `for`/`editor` resolution whenever ANY `<sciflow-editor>` in the
+     * document announces readiness. `resolveEditorReference()` otherwise only runs once
+     * (`connectedCallback`) and again whenever the `for`/`editor` property itself
+     * changes — but a host that computes `for` once from a stable id (e.g. derived from
+     * a route param, not from load state) never re-sets it, so if the target editor
+     * doesn't exist yet — or exists but hasn't loaded its document yet — at the moment
+     * this element first connects, the outline was stuck empty forever even after the
+     * editor became ready. `editor-ready` is dispatched with
+     * `bubbles: true, composed: true` (see `editor-element.ts`), so listening for it on
+     * `document` reaches this element regardless of shadow-root nesting or DOM order,
+     * without requiring any change on the consumer side. `resolveEditorReference()` is
+     * idempotent — it no-ops when the resolved target hasn't changed — so listening
+     * broadly (rather than only for the specific target id) is safe even with several
+     * editor/outline pairs on one page.
+     */
+    private documentEditorReadyListener?;
     static styles: import("lit").CSSResult;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -79,7 +96,29 @@ export declare class SciFlowOutlineElement extends LitElement {
     private handleCrossReferenceDragStart;
     private handleInsertCrossReference;
     private handleHeadingKeydown;
+    private handleFigureKeydown;
     private handleHeadingClick;
+    /**
+     * A figure entry was activated. Same navigation as a heading — the outline is a way of walking
+     * the document, and a figure is one of the places you walk to.
+     *
+     * Until now figure rows had no click handler at all: they rendered `role="listitem"` with no
+     * `@click` and no `@keydown`, so clicking one did nothing and keyboard users could tab to a row
+     * that could not be activated. Only headings were navigable.
+     *
+     * The position resolution below is what makes this work for a node that is not a textblock:
+     * `commands.setSelection` builds a `TextSelection.near()`, which lands on the closest text
+     * position to the figure — its caption, in practice — and scrolling that into view brings the
+     * figure with it.
+     */
+    private handleFigureClick;
+    /**
+     * Move the editor to an outline entry, and tell listeners.
+     *
+     * One path for both entry kinds on purpose: the heading version was the only one that existed,
+     * and a second copy for figures is how the two would drift apart the first time either is fixed.
+     */
+    private navigateToEntry;
     private resolveEditorReference;
     private resolveEditor;
     private attachEditorListeners;
@@ -90,6 +129,11 @@ export declare class SciFlowOutlineElement extends LitElement {
     private updateActiveHeading;
     private findHeadingForSelection;
     private headingKey;
+    /**
+     * The active-entry key for a figure. Namespaced, because both lists share one `activeHeadingKey`
+     * and a figure's id could otherwise collide with a heading's and highlight two rows at once.
+     */
+    private figureKey;
     private getHeadingSelectionPosition;
     private extractDocFromEditor;
     private normalizeClickBehavior;

package/dist/lib/outline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/lib/outline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/lib/outline.ts"],"names":[],"mappings":"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"}

package/dist/lib/outline.js

@@ -3,6 +3,7 @@ import { css, html, LitElement, nothing, unsafeCSS } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { SourceField, t, LOCALE_CHANGE_EVENT, } from '@sciflow/editor-core';
+import { texToHeadingText } from '@sciflow/schema-core';
 import { setTransparentDragImage } from './drag-preview.js';
 import outlineStyles from './outline.css?inline';
 import { applyThemeStylesToRoot, subscribeToSciFlowTheme } from './theme.js';
@@ -46,6 +47,49 @@ const parseLevelsFromAttribute = (value) => {
  * When a ProseMirror document is available, positions and node boundaries are
  * included so navigation and selection syncing can be precise.
  */
+/**
+ * Reduce a heading's content to plain text: a
+ * `math` child contributes `texToHeadingText(attrs.tex)` instead of nothing, so a heading
+ * containing math never renders empty/truncated in the outline, drag-and-drop, or the
+ * cross-reference target list.
+ *
+ * Deliberately walks only DIRECT children (`node.forEach`), not `node.textContent` (which
+ * recurses into every descendant). That recursion is what let a `footnote` child's own text leak
+ * into the heading string — this must never happen (H8 corpus case): a footnote is content
+ * *about* the heading, not part of its title. Any other non-text child (`bookmark`, or a future
+ * addition) contributes nothing, matching `textContent`'s existing behavior for atoms with no
+ * text — only `math` gets special handling, per R1.
+ */
+function headingTextFromPmNode(node) {
+    let text = '';
+    node.forEach((child) => {
+        if (child.isText) {
+            text += child.text ?? '';
+        }
+        else if (child.type.name === 'math') {
+            text += texToHeadingText(typeof child.attrs?.tex === 'string' ? child.attrs.tex : '');
+        }
+    });
+    return text.trim();
+}
+/**
+ * Slow-path (doc-only JSON) counterpart to `headingTextFromPmNode` — same R1 reduction, applied to
+ * a heading's `content` array instead of a live ProseMirror node. Already excludes a `footnote`
+ * child's text by construction (a footnote node carries no top-level `.text`, only nested
+ * `.content`), matching the fast path's H8 behavior.
+ */
+function headingTextFromJsonChildren(content) {
+    return content
+        .map((child) => {
+        if (child?.type === 'math') {
+            const tex = typeof child?.attrs?.tex === 'string' ? child.attrs.tex : '';
+            return texToHeadingText(tex);
+        }
+        return child?.text ?? '';
+    })
+        .join('')
+        .trim();
+}
 function figureLabel(node) {
     const text = node.textContent?.trim();
     if (text)
@@ -85,7 +129,7 @@ export function collectDocumentOutline(doc, pmDoc = null) {
         pmDoc.descendants((node, position) => {
             if (node.type.name === 'heading') {
                 outline.headings.push({
-                    text: node.textContent.trim(),
+                    text: headingTextFromPmNode(node),
                     level: node.attrs?.level ?? null,
                     id: node.attrs?.id ?? null,
                     position,
@@ -119,7 +163,7 @@ export function collectDocumentOutline(doc, pmDoc = null) {
         }
         const { type, attrs = {}, content = [] } = node;
         if (type === 'heading') {
-            const headingText = content.map((child) => child?.text ?? '').join('').trim();
+            const headingText = headingTextFromJsonChildren(content);
             outline.headings.push({
                 text: headingText,
                 level: attrs.level ?? null,
@@ -192,6 +236,8 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
         });
         this.localeListener = () => this.requestUpdate();
         document.addEventListener(LOCALE_CHANGE_EVENT, this.localeListener);
+        this.documentEditorReadyListener = () => this.resolveEditorReference();
+        document.addEventListener('editor-ready', this.documentEditorReadyListener);
         this.resolveEditorReference();
     }
     disconnectedCallback() {
@@ -200,6 +246,10 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
             document.removeEventListener(LOCALE_CHANGE_EVENT, this.localeListener);
             this.localeListener = undefined;
         }
+        if (this.documentEditorReadyListener) {
+            document.removeEventListener('editor-ready', this.documentEditorReadyListener);
+            this.documentEditorReadyListener = undefined;
+        }
         this.themeUnsub?.();
         this.themeUnsub = undefined;
         super.disconnectedCallback();
@@ -291,17 +341,25 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
         const id = figure.id?.trim();
         const draggable = Boolean(id);
         const label = figure.text?.trim() || (id ?? `${t('outline.figure')} ${index + 1}`);
+        // Same gate as a heading: navigable when clicks are enabled and the entry knows where it is.
+        const clickable = this.clickBehavior !== 'none' && figure.position !== null && figure.position !== undefined;
+        const key = this.figureKey(figure, index);
+        const isActive = this.activeHeadingKey === key;
         return html `
       <li
         class=${classMap({
             'outline-item': true,
             'outline-item--figure': true,
+            'outline-item--active': isActive,
         })}
-        part="item"
+        part=${`item${isActive ? ' item-active' : ''}`}
         data-outline-id=${figure.id ?? ''}
-        role="listitem"
-        tabindex="0"
+        role=${clickable ? 'button' : 'listitem'}
+        tabindex=${clickable ? 0 : -1}
+        aria-current=${isActive ? 'true' : 'false'}
         draggable=${draggable ? 'true' : 'false'}
+        @click=${clickable ? () => this.handleFigureClick(figure, index) : undefined}
+        @keydown=${clickable ? (event) => this.handleFigureKeydown(event, figure, index) : undefined}
         @dragstart=${draggable && id ? (e) => this.handleCrossReferenceDragStart(e, 'figure', id, label) : undefined}
       >
         <span class="outline-level outline-level--figure" aria-hidden="true">Fig</span>
@@ -376,7 +434,45 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
             this.handleHeadingClick(heading, index);
         }
     }
+    handleFigureKeydown(event, figure, index) {
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            this.handleFigureClick(figure, index);
+        }
+    }
     handleHeadingClick(heading, index) {
+        this.navigateToEntry(heading, this.headingKey(heading, index), { kind: 'heading', heading });
+    }
+    /**
+     * A figure entry was activated. Same navigation as a heading — the outline is a way of walking
+     * the document, and a figure is one of the places you walk to.
+     *
+     * Until now figure rows had no click handler at all: they rendered `role="listitem"` with no
+     * `@click` and no `@keydown`, so clicking one did nothing and keyboard users could tab to a row
+     * that could not be activated. Only headings were navigable.
+     *
+     * The position resolution below is what makes this work for a node that is not a textblock:
+     * `commands.setSelection` builds a `TextSelection.near()`, which lands on the closest text
+     * position to the figure — its caption, in practice — and scrolling that into view brings the
+     * figure with it.
+     */
+    handleFigureClick(figure, index) {
+        const asEntry = {
+            text: figure.text,
+            level: null,
+            id: figure.id,
+            position: figure.position,
+            end: figure.end,
+        };
+        this.navigateToEntry(asEntry, this.figureKey(figure, index), { kind: 'figure', figure });
+    }
+    /**
+     * Move the editor to an outline entry, and tell listeners.
+     *
+     * One path for both entry kinds on purpose: the heading version was the only one that existed,
+     * and a second copy for figures is how the two would drift apart the first time either is fixed.
+     */
+    navigateToEntry(heading, activeKey, origin) {
         if (this.clickBehavior === 'none') {
             return;
         }
@@ -414,10 +510,15 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
                 }
             }
         }
-        this.activeHeadingKey = this.headingKey(heading, index);
+        this.activeHeadingKey = activeKey;
         this.dispatchEvent(new CustomEvent('sciflow-outline-navigate', {
             detail: {
+                // `heading` is kept on every event, whatever the kind, so existing listeners are
+                // untouched; `kind` and `figure` are additive. For a figure, `heading` carries the same
+                // text/id/position in the shape listeners already read.
                 heading,
+                kind: origin.kind,
+                ...(origin.kind === 'figure' ? { figure: origin.figure } : {}),
                 behavior: this.clickBehavior,
                 selectionPosition: selectionPosition ?? heading.position,
             },
@@ -579,6 +680,19 @@ let SciFlowOutlineElement = class SciFlowOutlineElement extends LitElement {
         }
         return `idx-${index}`;
     }
+    /**
+     * The active-entry key for a figure. Namespaced, because both lists share one `activeHeadingKey`
+     * and a figure's id could otherwise collide with a heading's and highlight two rows at once.
+     */
+    figureKey(figure, index = this.figures.indexOf(figure)) {
+        if (figure.id) {
+            return `figure:${figure.id}`;
+        }
+        if (figure.position !== null && figure.position !== undefined) {
+            return `figure:pos-${figure.position}`;
+        }
+        return `figure:idx-${index}`;
+    }
     getHeadingSelectionPosition(position, editor) {
         if (!Number.isFinite(position)) {
             return null;

package/dist/lib/range-decorations.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @module range-decorations
+ *
+ * A generic, data-driven ProseMirror decorations Feature factory. Renders a
+ * caller-supplied list of `{ from, to?, class? }` ranges as native
+ * `Decoration.inline` (a real `[from, to)` span) or `Decoration.widget` (a
+ * zero-width point marker, when `to` is omitted or equal to `from`) — no
+ * highlighting/diff semantics live here, only the mechanism.
+ *
+ * # Why this exists — the dual-package hazard, for decorations specifically
+ *
+ * `Feature.addPlugins()` (`docs/pages/user-guide/customization/adding-plugins.md`)
+ * is the documented, supported way to add a plain ProseMirror `Plugin` to the
+ * editor from a HOST APPLICATION — and that part works even when the plugin is
+ * built with the app's OWN `prosemirror-state` copy (a plain object shape is
+ * all `Editor.create()` requires; confirmed live: the plugin registers in
+ * `view.state.plugins`, `PluginKey.getState()` resolves it correctly).
+ *
+ * Decorations are a DIFFERENT story. `@sciflow/editor-start/bundle` inlines
+ * `prosemirror-view` (`external: []` in `vite.config.ts`) — a host app's own
+ * `prosemirror-view` copy (from ITS `node_modules`) is a genuinely different
+ * module instance. A single app-authored decorating plugin renders fine in
+ * isolation, but the moment a SECOND decoration source coexists (any other
+ * feature/plugin that also implements `props.decorations` — realistic, not a
+ * corner case), `prosemirror-view`'s internal `DecorationGroup.from()` merges
+ * all sources and branches on `instanceof DecorationSet`: a `DecorationSet`
+ * built from the app's own module fails that check, falls through to reading
+ * `.members` on it (a property only `DecorationGroup` has, not `DecorationSet`
+ * — this is `undefined`), and the resulting merged group contains `undefined`
+ * entries. The very next render crashes inside the bundle's own
+ * `DecorationGroup.locals()` (`Cannot read properties of undefined (reading
+ * 'localsInner')`), taking the whole `editor.mount()` down with it — not a
+ * silent no-op. Verified live before writing this fix (not assumed): a
+ * single app-side decorating plugin renders correctly; two simultaneous
+ * app-side decorating plugins reproduce the crash above, byte for byte.
+ *
+ * The fix: `Decoration`/`Decoration Set` must be built with the BUNDLE's OWN
+ * `prosemirror-view` copy. This factory does exactly that — entirely inside
+ * `@sciflow/editor-start` — and hands the host app back only an opaque
+ * `PluginKey` and a `Feature`; the app never imports `prosemirror-state` or
+ * `prosemirror-view` itself for this, and only ever exchanges PLAIN DATA
+ * (`RangeDecorationSpec[]`, positions + a CSS class string) across the
+ * package boundary via the already-documented `editor.plugins.dispatchMeta()`
+ * API (`adding-plugins.md` § "Accessing Plugin State").
+ *
+ * # Usage
+ *
+ * ```ts
+ * import { createRangeDecorationsFeature } from '@sciflow/editor-start/bundle';
+ *
+ * const { feature, key } = createRangeDecorationsFeature('my-diff-decorations');
+ * await editor.configureFeatures([...otherFeatures, feature]);
+ *
+ * // Whenever the ranges to highlight change:
+ * editor.plugins.dispatchMeta(key, [
+ *   { from: 12, to: 40, class: 'my-added' },
+ *   { from: 40, class: 'my-removed' }, // no `to` — a point marker
+ * ]);
+ * ```
+ *
+ * Style decoration classes via global CSS scoped to `.sf-editable-surface`
+ * (see `adding-plugins.md` § "Styling Plugin Decorations") — the SAME
+ * mechanism `ghostCursorFeature` already relies on, not a new one.
+ */
+import { PluginKey } from 'prosemirror-state';
+import type { Feature } from '@sciflow/editor-core';
+/** One decorated range, in the CURRENT doc's position space. `to` omitted (or
+ *  equal to `from`) renders a zero-width point marker (`Decoration.widget`)
+ *  instead of a highlighted span — e.g. content that no longer exists at this
+ *  position in the doc, so there's nothing to highlight, only a point to
+ *  mark. `class` is applied to the decoration's DOM node (the widget span,
+ *  or the inline span's own class list) — style it via global CSS, never
+ *  inline styles, per the package's styling convention. */
+export interface RangeDecorationSpec {
+    from: number;
+    to?: number;
+    class?: string;
+    /**
+     * Rendered as the point-marker widget's visible `textContent` (only
+     * applies to the `Decoration.widget` branch above — a real `[from, to)`
+     * span has its own content already and ignores this field). Absent (the
+     * default) or an empty string reproduces today's behaviour byte-for-byte:
+     * an empty `aria-hidden="true"` marker span with no visible content (e.g.
+     * a thin caret-style tick).
+     *
+     * When a non-empty string is given, the widget instead renders it inline —
+     * e.g. a change-tracking host's deleted-run text, kept visible/struck-through at the
+     * point of deletion — and the marker is made readable to assistive
+     * technology instead of hidden from it (content a sighted user can still
+     * see should be announced too): `aria-hidden` is dropped and
+     * `aria-label="Deleted text: <text>"` is set instead, so AT gets context
+     * rather than just the bare string sitting mid-sentence. The widget also
+     * gets `data-with-text="true"`, a package-owned styling hook that lets one
+     * consumer `class` render the empty-marker and text-bearing cases
+     * differently (e.g. `.my-removed[data-with-text] { padding: 0 2px; }`)
+     * without computing two different `class` strings upstream.
+     *
+     * This factory renders whatever string it's given, verbatim, with no
+     * length cap or ellipsis — truncation policy (if any) is the CALLER's,
+     * decided before the range reaches `dispatchMeta`.
+     */
+    text?: string;
+}
+/**
+ * Build a fresh, independently-keyed range-decorations `Feature`. Call once
+ * per logical decoration layer (a second call with the same `name` still
+ * works — `PluginKey` de-dupes same-named keys internally — but a distinct
+ * `name` per layer keeps `dispatchMeta` targeting unambiguous when a host
+ * uses more than one).
+ *
+ * Returns the `Feature` to pass into `configureFeatures()`/`features`, and
+ * the `PluginKey` to read (`editor.plugins.getState(key)`) or update
+ * (`editor.plugins.dispatchMeta(key, ranges)`) the live range list — both
+ * already-public, already-documented `<sciflow-editor>` APIs.
+ */
+export declare function createRangeDecorationsFeature(name: string): {
+    feature: Feature;
+    key: PluginKey<RangeDecorationSpec[]>;
+};
+//# sourceMappingURL=range-decorations.d.ts.map

package/dist/lib/range-decorations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range-decorations.d.ts","sourceRoot":"","sources":["../../src/lib/range-decorations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAU,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;;2DAM2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,GACX;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC,mBAAmB,EAAE,CAAC,CAAA;CAAE,CAmC7D"}

package/dist/lib/range-decorations.js

@@ -0,0 +1,131 @@
+/**
+ * @module range-decorations
+ *
+ * A generic, data-driven ProseMirror decorations Feature factory. Renders a
+ * caller-supplied list of `{ from, to?, class? }` ranges as native
+ * `Decoration.inline` (a real `[from, to)` span) or `Decoration.widget` (a
+ * zero-width point marker, when `to` is omitted or equal to `from`) — no
+ * highlighting/diff semantics live here, only the mechanism.
+ *
+ * # Why this exists — the dual-package hazard, for decorations specifically
+ *
+ * `Feature.addPlugins()` (`docs/pages/user-guide/customization/adding-plugins.md`)
+ * is the documented, supported way to add a plain ProseMirror `Plugin` to the
+ * editor from a HOST APPLICATION — and that part works even when the plugin is
+ * built with the app's OWN `prosemirror-state` copy (a plain object shape is
+ * all `Editor.create()` requires; confirmed live: the plugin registers in
+ * `view.state.plugins`, `PluginKey.getState()` resolves it correctly).
+ *
+ * Decorations are a DIFFERENT story. `@sciflow/editor-start/bundle` inlines
+ * `prosemirror-view` (`external: []` in `vite.config.ts`) — a host app's own
+ * `prosemirror-view` copy (from ITS `node_modules`) is a genuinely different
+ * module instance. A single app-authored decorating plugin renders fine in
+ * isolation, but the moment a SECOND decoration source coexists (any other
+ * feature/plugin that also implements `props.decorations` — realistic, not a
+ * corner case), `prosemirror-view`'s internal `DecorationGroup.from()` merges
+ * all sources and branches on `instanceof DecorationSet`: a `DecorationSet`
+ * built from the app's own module fails that check, falls through to reading
+ * `.members` on it (a property only `DecorationGroup` has, not `DecorationSet`
+ * — this is `undefined`), and the resulting merged group contains `undefined`
+ * entries. The very next render crashes inside the bundle's own
+ * `DecorationGroup.locals()` (`Cannot read properties of undefined (reading
+ * 'localsInner')`), taking the whole `editor.mount()` down with it — not a
+ * silent no-op. Verified live before writing this fix (not assumed): a
+ * single app-side decorating plugin renders correctly; two simultaneous
+ * app-side decorating plugins reproduce the crash above, byte for byte.
+ *
+ * The fix: `Decoration`/`Decoration Set` must be built with the BUNDLE's OWN
+ * `prosemirror-view` copy. This factory does exactly that — entirely inside
+ * `@sciflow/editor-start` — and hands the host app back only an opaque
+ * `PluginKey` and a `Feature`; the app never imports `prosemirror-state` or
+ * `prosemirror-view` itself for this, and only ever exchanges PLAIN DATA
+ * (`RangeDecorationSpec[]`, positions + a CSS class string) across the
+ * package boundary via the already-documented `editor.plugins.dispatchMeta()`
+ * API (`adding-plugins.md` § "Accessing Plugin State").
+ *
+ * # Usage
+ *
+ * ```ts
+ * import { createRangeDecorationsFeature } from '@sciflow/editor-start/bundle';
+ *
+ * const { feature, key } = createRangeDecorationsFeature('my-diff-decorations');
+ * await editor.configureFeatures([...otherFeatures, feature]);
+ *
+ * // Whenever the ranges to highlight change:
+ * editor.plugins.dispatchMeta(key, [
+ *   { from: 12, to: 40, class: 'my-added' },
+ *   { from: 40, class: 'my-removed' }, // no `to` — a point marker
+ * ]);
+ * ```
+ *
+ * Style decoration classes via global CSS scoped to `.sf-editable-surface`
+ * (see `adding-plugins.md` § "Styling Plugin Decorations") — the SAME
+ * mechanism `ghostCursorFeature` already relies on, not a new one.
+ */
+import { Plugin, PluginKey } from 'prosemirror-state';
+import { Decoration, DecorationSet } from 'prosemirror-view';
+function toDecoration(spec) {
+    if (spec.to !== undefined && spec.to > spec.from) {
+        return Decoration.inline(spec.from, spec.to, spec.class ? { class: spec.class } : {});
+    }
+    const el = document.createElement('span');
+    if (spec.class)
+        el.className = spec.class;
+    if (spec.text) {
+        el.textContent = spec.text;
+        el.setAttribute('data-with-text', 'true');
+        el.setAttribute('aria-label', `Deleted text: ${spec.text}`);
+    }
+    else {
+        el.setAttribute('aria-hidden', 'true');
+    }
+    return Decoration.widget(spec.from, el, { side: 0 });
+}
+/**
+ * Build a fresh, independently-keyed range-decorations `Feature`. Call once
+ * per logical decoration layer (a second call with the same `name` still
+ * works — `PluginKey` de-dupes same-named keys internally — but a distinct
+ * `name` per layer keeps `dispatchMeta` targeting unambiguous when a host
+ * uses more than one).
+ *
+ * Returns the `Feature` to pass into `configureFeatures()`/`features`, and
+ * the `PluginKey` to read (`editor.plugins.getState(key)`) or update
+ * (`editor.plugins.dispatchMeta(key, ranges)`) the live range list — both
+ * already-public, already-documented `<sciflow-editor>` APIs.
+ */
+export function createRangeDecorationsFeature(name) {
+    const key = new PluginKey(name);
+    const plugin = new Plugin({
+        key,
+        state: {
+            init: () => [],
+            apply(tr, ranges) {
+                const meta = tr.getMeta(key);
+                if (meta !== undefined)
+                    return meta;
+                if (!tr.docChanged || ranges.length === 0)
+                    return ranges;
+                // Remap stored positions through every transaction rather than
+                // letting them drift from the doc they describe.
+                return ranges.map((r) => ({
+                    ...r,
+                    from: tr.mapping.map(r.from),
+                    to: r.to !== undefined ? tr.mapping.map(r.to) : undefined,
+                }));
+            },
+        },
+        props: {
+            decorations(state) {
+                const ranges = key.getState(state);
+                if (!ranges || ranges.length === 0)
+                    return DecorationSet.empty;
+                return DecorationSet.create(state.doc, ranges.map(toDecoration));
+            },
+        },
+    });
+    const feature = {
+        name,
+        addPlugins: () => [plugin],
+    };
+    return { feature, key };
+}