@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/prosemirror/plugins/aiCitationDecorations.js

@@ -0,0 +1,90 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+//#region src/prosemirror/plugins/aiCitationDecorations.ts
+const aiCitationDecorationsKey = new PluginKey("aiCitationDecorations");
+const SET_META = "set";
+const ACTIVE_META = "active";
+function buildDecorationSet(doc, citations, activeId) {
+	if (citations.length === 0) return DecorationSet.empty;
+	const docSize = doc.content.size;
+	const decorations = [];
+	for (const c of citations) {
+		const from = Math.max(0, Math.min(c.from, docSize));
+		const to = Math.max(from, Math.min(c.to, docSize));
+		if (to === from) continue;
+		const isActive = activeId === c.id;
+		decorations.push(Decoration.inline(from, to, {
+			class: ["folio-ai-citation", isActive ? "folio-ai-citation--active" : ""].filter(Boolean).join(" "),
+			"data-folio-ai-citation-id": c.id
+		}, {
+			inclusiveStart: false,
+			inclusiveEnd: false
+		}));
+	}
+	return DecorationSet.create(doc, decorations);
+}
+/**
+* ProseMirror plugin that renders AI citations as inline highlights.
+* Use {@link setAICitationsMeta} / {@link setActiveCitationMeta} to
+* update which ranges are shown and which one is currently active
+* (e.g., the one the user just clicked).
+*/
+function createAICitationDecorationsPlugin() {
+	return new Plugin({
+		key: aiCitationDecorationsKey,
+		state: {
+			init(_, state) {
+				return {
+					citations: [],
+					activeId: null,
+					decorationSet: buildDecorationSet(state.doc, [], null)
+				};
+			},
+			apply(tr, prev, _oldState, newState) {
+				const meta = tr.getMeta(aiCitationDecorationsKey);
+				if (meta?.type === SET_META) return {
+					citations: meta.citations,
+					activeId: prev.activeId,
+					decorationSet: buildDecorationSet(newState.doc, meta.citations, prev.activeId)
+				};
+				if (meta?.type === ACTIVE_META) return {
+					citations: prev.citations,
+					activeId: meta.activeId,
+					decorationSet: buildDecorationSet(newState.doc, prev.citations, meta.activeId)
+				};
+				if (tr.docChanged) {
+					const mapped = prev.decorationSet.map(tr.mapping, tr.doc);
+					return {
+						citations: prev.citations,
+						activeId: prev.activeId,
+						decorationSet: mapped
+					};
+				}
+				return prev;
+			}
+		},
+		props: { decorations(state) {
+			return aiCitationDecorationsKey.getState(state)?.decorationSet ?? null;
+		} }
+	});
+}
+function setAICitationsMeta(citations) {
+	return {
+		key: aiCitationDecorationsKey,
+		payload: {
+			type: SET_META,
+			citations
+		}
+	};
+}
+function setActiveCitationMeta(activeId) {
+	return {
+		key: aiCitationDecorationsKey,
+		payload: {
+			type: ACTIVE_META,
+			activeId
+		}
+	};
+}
+//#endregion
+export { aiCitationDecorationsKey, createAICitationDecorationsPlugin, setAICitationsMeta, setActiveCitationMeta };

package/dist/prosemirror/plugins/aiSuggestionDecorations.d.ts

@@ -0,0 +1,42 @@
+import { AISuggestion, AISuggestionSeverity } from "../../ai-suggestions/types.js";
+import { Plugin, PluginKey } from "prosemirror-state";
+import { DecorationSet } from "prosemirror-view";
+
+//#region src/prosemirror/plugins/aiSuggestionDecorations.d.ts
+declare const aiSuggestionDecorationsKey: PluginKey<AISuggestionDecorationState>;
+declare const SET_META = "set";
+declare const FOCUS_META = "focus";
+type AISuggestionDecorationState = {
+  suggestions: AISuggestion[];
+  focusedId: string | null;
+  decorationSet: DecorationSet;
+};
+/**
+ * Severity → CSS modifier class. Shared with the paged editor's
+ * suggestion overlay so both renderers stay on the same class names.
+ */
+declare const AI_SUGGESTION_SEVERITY_CLASS: Record<AISuggestionSeverity, string>;
+/**
+ * ProseMirror plugin that renders AI suggestions as inline decorations.
+ *
+ * Use {@link setAISuggestionsMeta} to update the list, and
+ * {@link setFocusedSuggestionMeta} to highlight the active one when the
+ * user navigates the review panel.
+ */
+declare function createAISuggestionDecorationsPlugin(): Plugin<AISuggestionDecorationState>;
+declare function setAISuggestionsMeta(suggestions: AISuggestion[]): {
+  key: PluginKey<AISuggestionDecorationState>;
+  payload: {
+    type: typeof SET_META;
+    suggestions: AISuggestion[];
+  };
+};
+declare function setFocusedSuggestionMeta(focusedId: string | null): {
+  key: PluginKey<AISuggestionDecorationState>;
+  payload: {
+    type: typeof FOCUS_META;
+    focusedId: string | null;
+  };
+};
+//#endregion
+export { AI_SUGGESTION_SEVERITY_CLASS, aiSuggestionDecorationsKey, createAISuggestionDecorationsPlugin, setAISuggestionsMeta, setFocusedSuggestionMeta };

package/dist/prosemirror/plugins/aiSuggestionDecorations.js

@@ -0,0 +1,135 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+//#region src/prosemirror/plugins/aiSuggestionDecorations.ts
+const aiSuggestionDecorationsKey = new PluginKey("aiSuggestionDecorations");
+const SET_META = "set";
+const FOCUS_META = "focus";
+/**
+* Severity → CSS modifier class. Shared with the paged editor's
+* suggestion overlay so both renderers stay on the same class names.
+*/
+const AI_SUGGESTION_SEVERITY_CLASS = {
+	typo: "folio-ai-suggestion--typo",
+	style: "folio-ai-suggestion--style",
+	substantive: "folio-ai-suggestion--substantive"
+};
+/**
+* Lazy DOM factory for the focused suggestion's in-text replacement
+* preview. Returned as a closure so the element is only created when
+* the view draws the widget (keeps the build side-effect free for
+* headless state updates).
+*/
+function buildReplacementWidget(suggestion) {
+	return () => {
+		const span = document.createElement("span");
+		span.className = "folio-ai-suggestion--focused-replacement";
+		span.dataset["folioAiSuggestionId"] = suggestion.id;
+		span.contentEditable = "false";
+		span.textContent = suggestion.suggestedText;
+		return span;
+	};
+}
+function buildDecorationSet(doc, suggestions, focusedId) {
+	if (suggestions.length === 0) return DecorationSet.empty;
+	const docSize = doc.content.size;
+	const decorations = [];
+	for (const suggestion of suggestions) {
+		if (suggestion.status !== "pending") continue;
+		const from = Math.max(0, Math.min(suggestion.range.from, docSize));
+		const to = Math.max(from, Math.min(suggestion.range.to, docSize));
+		if (to === from) continue;
+		const isFocused = focusedId === suggestion.id;
+		decorations.push(Decoration.inline(from, to, {
+			class: [
+				"folio-ai-suggestion",
+				AI_SUGGESTION_SEVERITY_CLASS[suggestion.severity],
+				isFocused ? "folio-ai-suggestion--focused" : "",
+				isFocused ? "folio-ai-suggestion--focused-original" : ""
+			].filter(Boolean).join(" "),
+			"data-folio-ai-suggestion-id": suggestion.id
+		}, {
+			inclusiveStart: false,
+			inclusiveEnd: false
+		}));
+		if (isFocused && suggestion.suggestedText.length > 0) decorations.push(Decoration.widget(to, buildReplacementWidget(suggestion), {
+			side: 1,
+			marks: [],
+			ignoreSelection: true,
+			key: `folio-ai-suggestion-replacement-${suggestion.id}`
+		}));
+	}
+	return DecorationSet.create(doc, decorations);
+}
+/**
+* ProseMirror plugin that renders AI suggestions as inline decorations.
+*
+* Use {@link setAISuggestionsMeta} to update the list, and
+* {@link setFocusedSuggestionMeta} to highlight the active one when the
+* user navigates the review panel.
+*/
+function createAISuggestionDecorationsPlugin() {
+	return new Plugin({
+		key: aiSuggestionDecorationsKey,
+		state: {
+			init(_, state) {
+				return {
+					suggestions: [],
+					focusedId: null,
+					decorationSet: buildDecorationSet(state.doc, [], null)
+				};
+			},
+			apply(tr, prev, _oldState, newState) {
+				const setMeta = tr.getMeta(aiSuggestionDecorationsKey);
+				if (setMeta?.type === SET_META) return {
+					suggestions: setMeta.suggestions,
+					focusedId: prev.focusedId,
+					decorationSet: buildDecorationSet(newState.doc, setMeta.suggestions, prev.focusedId)
+				};
+				if (setMeta?.type === FOCUS_META) return {
+					suggestions: prev.suggestions,
+					focusedId: setMeta.focusedId,
+					decorationSet: buildDecorationSet(newState.doc, prev.suggestions, setMeta.focusedId)
+				};
+				if (tr.docChanged) {
+					if (prev.suggestions.length === 0) return prev;
+					const mapped = prev.decorationSet.map(tr.mapping, tr.doc);
+					return {
+						suggestions: prev.suggestions.map((suggestion) => ({
+							...suggestion,
+							range: {
+								from: tr.mapping.map(suggestion.range.from, 1),
+								to: tr.mapping.map(suggestion.range.to, -1)
+							}
+						})),
+						focusedId: prev.focusedId,
+						decorationSet: mapped
+					};
+				}
+				return prev;
+			}
+		},
+		props: { decorations(state) {
+			return aiSuggestionDecorationsKey.getState(state)?.decorationSet ?? null;
+		} }
+	});
+}
+function setAISuggestionsMeta(suggestions) {
+	return {
+		key: aiSuggestionDecorationsKey,
+		payload: {
+			type: SET_META,
+			suggestions
+		}
+	};
+}
+function setFocusedSuggestionMeta(focusedId) {
+	return {
+		key: aiSuggestionDecorationsKey,
+		payload: {
+			type: FOCUS_META,
+			focusedId
+		}
+	};
+}
+//#endregion
+export { AI_SUGGESTION_SEVERITY_CLASS, aiSuggestionDecorationsKey, createAISuggestionDecorationsPlugin, setAISuggestionsMeta, setFocusedSuggestionMeta };

package/dist/prosemirror/plugins/anonymizationDecorations.d.ts

@@ -0,0 +1,60 @@
+import { EditorState, Plugin, PluginKey } from "prosemirror-state";
+
+//#region src/prosemirror/plugins/anonymizationDecorations.d.ts
+type AnonymizationTerm = {
+  /** Canonical surface form, displayed in tooltips. */canonical: string; /** Label slug (e.g. "person", "organization"). */
+  label: string; /** Optional alternate surface forms also matched verbatim. */
+  variants?: readonly string[];
+};
+type AnonymizationMatch = {
+  /** Inclusive PM doc position of the match start. */from: number; /** Exclusive PM doc position of the match end. */
+  to: number;
+  label: string;
+  canonical: string;
+};
+declare const SET_META = "set";
+type AnonymizationDecorationState = {
+  terms: readonly AnonymizationTerm[];
+  matches: readonly AnonymizationMatch[];
+};
+declare const anonymizationDecorationsKey: PluginKey<AnonymizationDecorationState>;
+declare const slugAnonymizationLabel: (label: string) => string;
+/**
+ * Plugin that keeps a list of anonymization-term match ranges
+ * synced with the document. Host pushes terms via
+ * {@link setAnonymizationTermsMeta}; the paged-editor reads
+ * the matches and paints the overlay.
+ */
+type AnonymizationPluginOptions = {
+  /**
+   * Push-side bridge for hosts that need to mirror the current
+   * match list outside the PM state tree (e.g. an inspector
+   * facet showing a "N highlighted" counter, or per-doc analytics).
+   * Called on plugin init, after every transaction that changes
+   * the match set, and on plugin teardown (with an empty list).
+   * The same list is reachable via `getAnonymizationMatches`;
+   * use the callback when you need updates without polling.
+   */
+  onMatchesChange?: (matches: readonly AnonymizationMatch[]) => void;
+};
+declare const createAnonymizationDecorationsPlugin: ({
+  onMatchesChange
+}?: AnonymizationPluginOptions) => Plugin<AnonymizationDecorationState>;
+declare const setAnonymizationTermsMeta: (terms: readonly AnonymizationTerm[]) => {
+  key: PluginKey<AnonymizationDecorationState>;
+  payload: {
+    type: typeof SET_META;
+    terms: readonly AnonymizationTerm[];
+  };
+};
+/**
+ * Read the plugin's current match list out of a Folio editor
+ * view. Lives inside the same module as the plugin key so a host
+ * that imports it via `@stll/folio` gets the *same* key instance
+ * as the plugin registration — bypassing the dev-HMR hazard
+ * where re-evaluating the plugin module would create a second
+ * PluginKey and break key-based lookups.
+ */
+declare const getAnonymizationMatches: (state: EditorState) => readonly AnonymizationMatch[];
+//#endregion
+export { AnonymizationMatch, AnonymizationPluginOptions, AnonymizationTerm, anonymizationDecorationsKey, createAnonymizationDecorationsPlugin, getAnonymizationMatches, setAnonymizationTermsMeta, slugAnonymizationLabel };

package/dist/prosemirror/plugins/anonymizationDecorations.js

@@ -0,0 +1,120 @@
+import { collectBlockChunks, joinChunks, offsetToDocPos } from "./pmTextScan.js";
+import { Plugin, PluginKey } from "prosemirror-state";
+//#region src/prosemirror/plugins/anonymizationDecorations.ts
+const SET_META = "set";
+const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.anonymizationDecorationsKey");
+const keyHolder = globalThis;
+const anonymizationDecorationsKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("anonymizationDecorations"));
+const slugAnonymizationLabel = (label) => label.toLowerCase().replace(/[^a-z0-9]+/gu, "-");
+const buildMatcher = (terms) => {
+	const escapeChar = (value) => value.replaceAll(/[\\^$.*+?()[\]{}|]/gu, "\\$&").replaceAll(/\s+/gu, "\\s+");
+	const compiled = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const term of terms) {
+		const surfaces = [term.canonical, ...term.variants ?? []].filter((surface) => surface.length > 0);
+		if (surfaces.length === 0) continue;
+		surfaces.sort((a, b) => b.length - a.length);
+		const key = surfaces.join("|").toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const alternation = surfaces.map(escapeChar).join("|");
+		compiled.push({
+			term,
+			regex: new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternation})(?![\\p{L}\\p{N}])`, "giu")
+		});
+	}
+	return compiled;
+};
+const buildMatches = (doc, terms) => {
+	const compiled = buildMatcher(terms);
+	if (compiled.length === 0) return [];
+	const matches = [];
+	for (const chunks of collectBlockChunks(doc)) {
+		const joined = joinChunks(chunks);
+		for (const { regex, term } of compiled) {
+			regex.lastIndex = 0;
+			let match = regex.exec(joined);
+			while (match !== null) {
+				const from = offsetToDocPos(chunks, match.index);
+				const to = offsetToDocPos(chunks, match.index + match[0].length);
+				matches.push({
+					from,
+					to,
+					label: term.label,
+					canonical: term.canonical
+				});
+				if (regex.lastIndex === match.index) regex.lastIndex += 1;
+				match = regex.exec(joined);
+			}
+		}
+	}
+	matches.sort((a, b) => a.from !== b.from ? a.from - b.from : b.to - a.to);
+	const result = [];
+	let cursor = -1;
+	for (const m of matches) {
+		if (m.from < cursor) continue;
+		result.push(m);
+		cursor = m.to;
+	}
+	return result;
+};
+const createAnonymizationDecorationsPlugin = ({ onMatchesChange } = {}) => {
+	const spec = {
+		key: anonymizationDecorationsKey,
+		state: {
+			init() {
+				return {
+					terms: [],
+					matches: []
+				};
+			},
+			apply(tr, prev, _oldState, newState) {
+				const setMeta = tr.getMeta(anonymizationDecorationsKey);
+				if (setMeta?.type === SET_META) return {
+					terms: setMeta.terms,
+					matches: buildMatches(newState.doc, setMeta.terms)
+				};
+				if (tr.docChanged) return {
+					terms: prev.terms,
+					matches: buildMatches(newState.doc, prev.terms)
+				};
+				return prev;
+			}
+		}
+	};
+	if (onMatchesChange) spec.view = (view) => {
+		let last = anonymizationDecorationsKey.getState(view.state)?.matches;
+		if (last) onMatchesChange(last);
+		return {
+			update(updatedView) {
+				const next = anonymizationDecorationsKey.getState(updatedView.state)?.matches;
+				if (next && next !== last) {
+					last = next;
+					onMatchesChange(next);
+				}
+			},
+			destroy() {
+				onMatchesChange([]);
+			}
+		};
+	};
+	return new Plugin(spec);
+};
+const setAnonymizationTermsMeta = (terms) => ({
+	key: anonymizationDecorationsKey,
+	payload: {
+		type: SET_META,
+		terms
+	}
+});
+/**
+* Read the plugin's current match list out of a Folio editor
+* view. Lives inside the same module as the plugin key so a host
+* that imports it via `@stll/folio` gets the *same* key instance
+* as the plugin registration — bypassing the dev-HMR hazard
+* where re-evaluating the plugin module would create a second
+* PluginKey and break key-based lookups.
+*/
+const getAnonymizationMatches = (state) => anonymizationDecorationsKey.getState(state)?.matches ?? [];
+//#endregion
+export { anonymizationDecorationsKey, createAnonymizationDecorationsPlugin, getAnonymizationMatches, setAnonymizationTermsMeta, slugAnonymizationLabel };

package/dist/prosemirror/plugins/autocompleteSuggestion.d.ts

@@ -0,0 +1,123 @@
+import { EditorState, Plugin, PluginKey, Transaction } from "prosemirror-state";
+import { DecorationSet } from "prosemirror-view";
+
+//#region src/prosemirror/plugins/autocompleteSuggestion.d.ts
+type AutocompleteSuggestionStatus = "idle" | "streaming" | "shown";
+type AutocompleteSuggestionState = {
+  status: "idle";
+  anchor: null;
+  text: "";
+  requestId: null;
+} | {
+  status: "streaming" | "shown";
+  anchor: number;
+  text: string;
+  requestId: string;
+};
+declare const autocompleteSuggestionKey: PluginKey<AutocompleteSuggestionPluginState>;
+type AutocompleteSuggestionPluginState = {
+  suggestion: AutocompleteSuggestionState;
+  decorations: DecorationSet;
+};
+type AutocompleteSuggestionPluginOptions = {
+  /**
+   * When `true`, the plugin paints the ghost text and the
+   * "stella" caret as a single inline widget decoration. Use
+   * this in standard (non-paged) ProseMirror views where PM
+   * decorations reach the visible DOM.
+   *
+   * When `false` (default), the plugin emits an invisible
+   * zero-width anchor widget only; the visible ghost text is
+   * painted by {@link AutocompleteCaretOverlay} reading the
+   * plugin state from outside the editor. This is the path
+   * folio's hidden-PM + paged-painter editor uses.
+   */
+  renderInline?: boolean;
+  /**
+   * When `true`, the plugin intercepts keys via
+   * `props.handleKeyDown`:
+   *   - Tab            → accept full suggestion (only if shown)
+   *   - Mod-ArrowRight → accept the next word
+   *   - Escape         → dismiss
+   * Handlers return `false` (i.e. don't consume the event) when
+   * no suggestion is active, so existing keymap entries — list
+   * indentation on Tab, etc. — continue to work unchanged.
+   *
+   * The plugin must sit early in the editor's plugin array for
+   * its `handleKeyDown` to run before competing keymap plugins.
+   */
+  keymap?: boolean;
+};
+declare const autocompleteSuggestionPlugin: (options?: AutocompleteSuggestionPluginOptions) => Plugin<AutocompleteSuggestionPluginState>;
+declare const getAutocompleteSuggestion: (state: EditorState) => AutocompleteSuggestionState;
+declare const startAutocompleteSuggestion: (tr: Transaction, anchor: number, requestId: string) => Transaction;
+declare const appendAutocompleteToken: (tr: Transaction, requestId: string, delta: string) => Transaction;
+declare const finishAutocompleteSuggestion: (tr: Transaction, requestId: string) => Transaction;
+declare const clearAutocompleteSuggestion: (tr: Transaction) => Transaction;
+type AcceptAutocompleteResult = {
+  accepted: false;
+} | {
+  accepted: true;
+  from: number;
+  to: number;
+  text: string;
+};
+/**
+ * Commit the current suggestion as a real text insertion at its
+ * anchor. Returns metadata so the caller can record the accept
+ * event (for telemetry / future training feedback) without
+ * re-reading plugin state after the dispatch.
+ *
+ * Single transaction: insert text + clear suggestion state, so
+ * undo restores both the doc and the (now-gone) ghost atomically.
+ */
+declare const acceptAutocompleteSuggestion: (state: EditorState, dispatch?: (tr: Transaction) => void) => AcceptAutocompleteResult;
+/**
+ * Consume the next "word" from the suggestion: insert it at the
+ * anchor in a single transaction and shrink the remaining ghost
+ * text. Lets the user "graze" through a long suggestion one word
+ * at a time with ⌘→ / Ctrl→ instead of accept-all-or-discard.
+ *
+ * A word here is "leading whitespace + the next non-whitespace
+ * run + an optional trailing space" — so successive calls eat the
+ * suggestion cleanly without leaving stray spaces. When the
+ * remaining suggestion is shorter than one word, this falls
+ * through to {@link acceptAutocompleteSuggestion}.
+ */
+declare const acceptAutocompleteWord: (state: EditorState, dispatch?: (tr: Transaction) => void) => AcceptAutocompleteResult;
+type AutocompleteTriggerSkipReason = "selection-non-empty" | "midword" | "deadzone" | "empty-doc";
+type AutocompleteTriggerCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reason: AutocompleteTriggerSkipReason;
+  detail?: string;
+};
+/**
+ * Node type names that should suppress autocomplete entirely. The
+ * defaults cover prose-adjacent zones across ProseMirror schemas
+ * we encounter in folio + bare playgrounds. Pass a custom list via
+ * options to extend (citations, math, frontmatter, etc.).
+ */
+declare const DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES: readonly string[];
+type AutocompleteTriggerOptions = {
+  /** Additional node type names to treat as dead zones. */extraDeadZoneNodes?: readonly string[];
+};
+/**
+ * Decide whether autocomplete should fire at the current cursor.
+ * Designed to be called from a debounced trigger in the host app
+ * before sending a request to the model. Returns a structured
+ * skip reason rather than a bare boolean so callers (and debug
+ * UIs) can explain why no suggestion appeared.
+ *
+ * Gates applied:
+ *  - selection must be a collapsed caret (no range selection)
+ *  - the cursor must not be inside a dead-zone node (heading,
+ *    code, citation, math, etc.) anywhere in the ancestor chain
+ *  - the character immediately before the cursor must not be a
+ *    word-continuation char — if it is, the model would be
+ *    completing a partial token and almost always misreads intent
+ */
+declare const shouldTriggerAutocomplete: (state: EditorState, options?: AutocompleteTriggerOptions) => AutocompleteTriggerCheck;
+//#endregion
+export { AcceptAutocompleteResult, AutocompleteSuggestionPluginOptions, AutocompleteSuggestionState, AutocompleteSuggestionStatus, AutocompleteTriggerCheck, AutocompleteTriggerOptions, AutocompleteTriggerSkipReason, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acceptAutocompleteWord, appendAutocompleteToken, autocompleteSuggestionKey, autocompleteSuggestionPlugin, clearAutocompleteSuggestion, finishAutocompleteSuggestion, getAutocompleteSuggestion, shouldTriggerAutocomplete, startAutocompleteSuggestion };