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

package/dist/ai-suggestions/types.d.ts

@@ -0,0 +1,199 @@
+//#region src/ai-suggestions/types.d.ts
+/**
+ * AI Suggestion Types
+ *
+ * AI suggestions are external review items, not document changes.
+ * They sit in a separate queue, render as non-mutating decorations,
+ * and only become document changes when the user accepts them.
+ */
+type AISuggestionSeverity = "typo" | "style" | "substantive";
+type AISuggestionStatus = "pending" | "accepted" | "rejected" | "stale";
+type AISuggestionApplyMode = "direct" | "tracked-changes";
+/**
+ * A single AI suggestion sitting in the review queue.
+ *
+ * The `range` is a ProseMirror position range captured at generation time.
+ * The `originalText` plus `contextBefore`/`contextAfter` form the anchor
+ * used to detect staleness if the document is edited between generation
+ * and apply.
+ */
+type AISuggestion = {
+  id: string;
+  topic: string;
+  severity: AISuggestionSeverity;
+  range: {
+    from: number;
+    to: number;
+  };
+  originalText: string;
+  suggestedText: string;
+  contextBefore: string;
+  contextAfter: string;
+  rationale: string; /** 0..1 model confidence. Optional — not displayed prominently. */
+  confidence?: number;
+  status: AISuggestionStatus;
+  /**
+   * Optional display metadata the host may attach to describe the
+   * suggestion's payload with badges (e.g., a template-field proposal's
+   * value type and whether a person or AI fills it). Folio stays
+   * agnostic: `valueKind` is an opaque string the host resolves against
+   * its own registry; unknown values simply render no badge.
+   */
+  display?: {
+    valueKind?: string; /** `personAi`: a person writes a stub and AI adapts it in place. */
+    filledBy?: "person" | "ai" | "personAi";
+  };
+};
+/**
+ * Conversation mode — intent dial passed from the bar to the
+ * generator. The model decides what to do; mode just tells it
+ * what kind of response the user wants.
+ */
+type AIChatMode = "ask" | "edit";
+/**
+ * Input passed to the host's generate function.
+ */
+type AIGenerateInput = {
+  /**
+   * Free-form instruction the user typed into the bar (or the prompt
+   * text of the preset they picked). Empty string means "general
+   * review — surface anything notable".
+   */
+  prompt: string;
+  /**
+   * Conversation mode the user is in.
+   * - "ask": no edit suggestions; pure answer.
+   * - "edit": text + suggestions allowed, accept UI rendered.
+   */
+  mode: AIChatMode; /** Selected text, if any. Empty string when no selection. */
+  selectionText: string; /** PM range of the selection, or null when there is no selection. */
+  selectionRange: {
+    from: number;
+    to: number;
+  } | null;
+  /**
+   * Last known cursor position (Folio only). Always set when a PM
+   * view is available, even when the selection is collapsed; null
+   * for non-PM viewers (PDF). Drives "near my cursor" prompts.
+   */
+  cursorPosition: {
+    from: number;
+    to: number;
+  } | null; /** Plain-text snapshot of the document body. */
+  documentText: string;
+  /**
+   * Subset of `documentText` currently visible in the viewport. Lets
+   * the model bias its answer toward what the user is looking at.
+   * Empty string when the host can't infer the visible range.
+   */
+  visibleText: string;
+  /**
+   * PM range of the visible region (Folio only). null when the host
+   * can't compute it (PDF, or before the first paint).
+   */
+  visibleRange: {
+    from: number;
+    to: number;
+  } | null;
+  /**
+   * If the prompt came from a preset, its id is forwarded so the
+   * generator can take a faster path or attribute the request.
+   */
+  presetId?: string;
+};
+/**
+ * A pre-saved instruction the user can pick from a dropdown next to
+ * the prompt input. Presets bundle a one-line label, an icon glyph,
+ * the prompt text that will be sent to the generator, and the
+ * conversation mode the prompt is naturally meant for.
+ */
+type AISuggestionPreset = {
+  id: string; /** Short label shown in the dropdown (e.g., "Catch typos"). */
+  label: string; /** Optional one-line description shown beneath the label. */
+  description?: string; /** Prompt text sent to the generator when the preset is picked. */
+  prompt: string;
+  /**
+   * Mode the preset is naturally meant for. Picking it switches the
+   * bar's mode globally. Default: "edit" (most legacy presets are
+   * edit-shaped).
+   */
+  mode?: AIChatMode;
+};
+/**
+ * Citation — a pointer from an AI answer back to the source range in
+ * the document. Folio (DOCX) cites by PM range; PDF cites by bounding
+ * box.
+ *
+ * The `pdf-bbox` shape is flat and byte-compatible with `BoundingBox`
+ * from `@stll/api/types` — same field names, same semantics — so a
+ * Stella API justification can be lifted into an `AICitationSource`
+ * (and vice versa) with `{ kind: "pdf-bbox", ...box }`. We don't
+ * import the API type directly to avoid a folio→api package edge
+ * for what is universally a PDF bbox shape.
+ */
+type AICitationSource = {
+  kind: "folio-range"; /** ProseMirror positions in the live document. */
+  from: number;
+  to: number;
+} | {
+  kind: "pdf-bbox";
+  pageNumber: number;
+  xMin: number;
+  yMin: number;
+  xMax: number;
+  yMax: number;
+};
+type AICitation = {
+  /** Stable id within the message (e.g., used as `[1]` reference). */id: string; /** Short label rendered in the inline chip ("1", "§3.2", etc.). */
+  label: string; /** Verbatim quoted text from the source — surfaces on hover/expand. */
+  quote: string; /** Where the cited text lives in the source document. */
+  source: AICitationSource;
+};
+/**
+ * Bar status, surfaced by Folio to the user.
+ */
+type AIBarStatus = "idle" | "generating" | "review-ready" | "applying" | "error";
+/**
+ * Configuration for the AI suggestions feature.
+ */
+type AISuggestionsConfig = {
+  /**
+   * Called when the user requests new suggestions. Returns the suggestions
+   * to be queued for review. Folio handles all UI state, conflict
+   * detection, and apply orchestration.
+   */
+  onGenerate: (input: AIGenerateInput) => Promise<AISuggestion[]>;
+  /**
+   * Pre-saved prompts shown in the bar's dropdown. When omitted,
+   * Folio falls back to a small set of generic legal-drafting presets.
+   */
+  presets?: AISuggestionPreset[];
+  /**
+   * Placeholder text shown in the prompt input when it is empty.
+   * Defaults to a neutral "Ask AI to review…" prompt.
+   */
+  inputPlaceholder?: string;
+  /**
+   * Default apply mode. The user can toggle in the panel.
+   * Defaults to "direct".
+   */
+  defaultApplyMode?: AISuggestionApplyMode; /** Author label used when applying as tracked changes. */
+  applyAuthor?: string;
+  /**
+   * Called when the user accepts a suggestion while the editor is
+   * read-only. The host should transition the editor into editing
+   * mode (e.g., acquire the file lock); Folio queues the accepted
+   * suggestions and applies them once the editor becomes editable.
+   *
+   * If omitted, accept buttons are inert in read-only mode.
+   */
+  onUnlockRequest?: () => void;
+};
+/**
+ * Default presets used when the host provides none. Each is tagged
+ * with the mode it's naturally meant for; picking the preset flips
+ * the bar to that mode.
+ */
+declare const DEFAULT_AI_SUGGESTION_PRESETS: AISuggestionPreset[];
+//#endregion
+export { AIBarStatus, AIChatMode, AICitation, AICitationSource, AIGenerateInput, AISuggestion, AISuggestionApplyMode, AISuggestionPreset, AISuggestionSeverity, AISuggestionStatus, AISuggestionsConfig, DEFAULT_AI_SUGGESTION_PRESETS };

package/dist/ai-suggestions/types.js

@@ -0,0 +1,59 @@
+//#region src/ai-suggestions/types.ts
+/**
+* Default presets used when the host provides none. Each is tagged
+* with the mode it's naturally meant for; picking the preset flips
+* the bar to that mode.
+*/
+const DEFAULT_AI_SUGGESTION_PRESETS = [
+	{
+		id: "summary",
+		label: "Summarise this document",
+		description: "Quick overview of the parties, subject, and key terms.",
+		prompt: "Summarise this document. List parties, subject matter, and key terms.",
+		mode: "ask"
+	},
+	{
+		id: "governing-law",
+		label: "Identify governing law",
+		description: "Surface the governing-law clause and the chosen forum.",
+		prompt: "What is the governing law and the dispute-resolution forum?",
+		mode: "ask"
+	},
+	{
+		id: "typos",
+		label: "Catch typos and spelling",
+		description: "Flag misspellings and small surface errors only.",
+		prompt: "Find typos, misspellings, and small surface errors only.",
+		mode: "edit"
+	},
+	{
+		id: "concision",
+		label: "Tighten language",
+		description: "Cut verbose phrases and prefer plain alternatives.",
+		prompt: "Tighten verbose phrases and prefer plain alternatives.",
+		mode: "edit"
+	},
+	{
+		id: "defined-terms",
+		label: "Check defined terms",
+		description: "Flag inconsistent capitalization of defined terms.",
+		prompt: "Flag inconsistent capitalization or usage of defined terms across the document.",
+		mode: "edit"
+	},
+	{
+		id: "shall",
+		label: "Plain-language pass",
+		description: "Replace “shall” and other archaisms with modern equivalents.",
+		prompt: "Replace “shall” and other legal archaisms with modern equivalents.",
+		mode: "edit"
+	},
+	{
+		id: "general",
+		label: "General review",
+		description: "Surface anything notable — typos, style, substantive.",
+		prompt: "",
+		mode: "edit"
+	}
+];
+//#endregion
+export { DEFAULT_AI_SUGGESTION_PRESETS };

package/dist/content-controls/errors.d.ts

@@ -0,0 +1,52 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/content-controls/errors.d.ts
+declare const ContentControlLockedError_base: import("better-result").TaggedErrorClass<"ContentControlLockedError", {
+  message: string;
+  lock: NonNullable<document_d_exports.SdtProperties["lock"]>;
+  tag?: string;
+  alias?: string;
+}>;
+/**
+ * Refused because the target control's `w:lock` forbids the requested
+ * mutation. Caller can override with `{ force: true }` if they understand
+ * the consequences (overrides apply per call, not per document).
+ */
+declare class ContentControlLockedError extends ContentControlLockedError_base {}
+declare const ContentControlBoundError_base: import("better-result").TaggedErrorClass<"ContentControlBoundError", {
+  message: string;
+  xpath: string;
+  storeItemID?: string;
+  tag?: string;
+  alias?: string;
+}>;
+/**
+ * Refused because the target control is bound to a `<w:dataBinding>`.
+ *
+ * Word regenerates the SDT body from the bound XML on every open, so a
+ * direct write to `<w:t>` is silently overwritten and the caller's edit
+ * disappears on next open. Aspose.Words handles this by requiring an
+ * explicit `XmlMapping.Delete()` before write; folio mirrors that
+ * pattern: throw by default, accept `{ force: true }` as an opt-in that
+ * strips the binding inline (the same destructive choice the caller
+ * would have made explicitly via Aspose's API).
+ *
+ * Reference: python-docx #965, Aspose forum thread on removing custom
+ * XML mapping before content updates.
+ */
+declare class ContentControlBoundError extends ContentControlBoundError_base {}
+declare const ContentControlTypeError_base: import("better-result").TaggedErrorClass<"ContentControlTypeError", {
+  message: string;
+  sdtType: document_d_exports.SdtProperties["sdtType"];
+  reason: string;
+  tag?: string;
+  alias?: string;
+}>;
+/**
+ * Refused because the requested operation does not make sense for the
+ * control's type — e.g. setting free text on a checkbox, or unwrapping a
+ * `w15:repeatingSection` (which would orphan its row items).
+ */
+declare class ContentControlTypeError extends ContentControlTypeError_base {}
+//#endregion
+export { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError };

package/dist/content-controls/errors.js

@@ -0,0 +1,36 @@
+import { TaggedError } from "better-result";
+//#region src/content-controls/errors.ts
+/**
+* Tagged errors for the content-controls API. Every write helper that
+* refuses a mutation throws one of these; consumers can either bubble the
+* error or retry with `{ force: true }`.
+*/
+/**
+* Refused because the target control's `w:lock` forbids the requested
+* mutation. Caller can override with `{ force: true }` if they understand
+* the consequences (overrides apply per call, not per document).
+*/
+var ContentControlLockedError = class extends TaggedError("ContentControlLockedError")() {};
+/**
+* Refused because the target control is bound to a `<w:dataBinding>`.
+*
+* Word regenerates the SDT body from the bound XML on every open, so a
+* direct write to `<w:t>` is silently overwritten and the caller's edit
+* disappears on next open. Aspose.Words handles this by requiring an
+* explicit `XmlMapping.Delete()` before write; folio mirrors that
+* pattern: throw by default, accept `{ force: true }` as an opt-in that
+* strips the binding inline (the same destructive choice the caller
+* would have made explicitly via Aspose's API).
+*
+* Reference: python-docx #965, Aspose forum thread on removing custom
+* XML mapping before content updates.
+*/
+var ContentControlBoundError = class extends TaggedError("ContentControlBoundError")() {};
+/**
+* Refused because the requested operation does not make sense for the
+* control's type — e.g. setting free text on a checkbox, or unwrapping a
+* `w15:repeatingSection` (which would orphan its row items).
+*/
+var ContentControlTypeError = class extends TaggedError("ContentControlTypeError")() {};
+//#endregion
+export { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError };

package/dist/content-controls/findContentControls.d.ts

@@ -0,0 +1,55 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/content-controls/findContentControls.d.ts
+type ContentControlFilter = {
+  tag?: string;
+  alias?: string; /** OOXML numeric `w:id`. */
+  id?: number;
+  sdtType?: document_d_exports.SdtProperties["sdtType"];
+  /**
+   * ProseMirror absolute position of the blockSdt's open token. The
+   * widgets plugin uses this to disambiguate SDTs that share a tag: each
+   * clicked control resolves to exactly one position, so the mutation
+   * lands on the intended instance even when multiple share the same
+   * tag/alias. Only meaningful for PM-layer addressing (see
+   * `prosemirror/commands/contentControls`). The headless walker matches
+   * on it too, but `findContentControls` over the headless model does
+   * not produce PM positions — so this filter is effectively a no-op
+   * when called on a headless Document.
+   */
+  pmPos?: number;
+};
+/**
+ * Source location of a matched content control. Main-body matches stay
+ * the silent default; matches inside a footnote or endnote carry the
+ * note's numeric id so callers can route the right mutate API at it.
+ */
+type ContentControlLocation = {
+  kind: "body";
+} | {
+  kind: "footnote";
+  noteId: number;
+} | {
+  kind: "endnote";
+  noteId: number;
+};
+type ContentControlMatch = {
+  control: document_d_exports.BlockSdt; /** Outer→inner stack of enclosing controls (empty when at the body root). */
+  ancestry: document_d_exports.BlockSdt[]; /** Indices to walk back into the doc, outer→inner. */
+  path: number[];
+  /**
+   * Where in the document this match was found. Defaults to the main
+   * body; populated for matches in `doc.package.footnotes` /
+   * `doc.package.endnotes`.
+   */
+  location: ContentControlLocation;
+};
+declare function findContentControls(doc: document_d_exports.Document, filter?: ContentControlFilter): ContentControlMatch[];
+declare function findContentControl(doc: document_d_exports.Document, filter: ContentControlFilter): ContentControlMatch | null;
+/**
+ * Concatenated plain text of every paragraph descendant inside a control,
+ * separated by newlines. Useful for template/agent read paths.
+ */
+declare function getContentControlText(control: document_d_exports.BlockSdt): string;
+//#endregion
+export { ContentControlFilter, ContentControlLocation, ContentControlMatch, findContentControl, findContentControls, getContentControlText };

package/dist/content-controls/findContentControls.js

@@ -0,0 +1,75 @@
+//#region src/content-controls/findContentControls.ts
+function matches(control, filter) {
+	if (filter.pmPos !== void 0) return false;
+	if (filter.tag !== void 0 && control.properties.tag !== filter.tag) return false;
+	if (filter.alias !== void 0 && control.properties.alias !== filter.alias) return false;
+	if (filter.id !== void 0 && control.properties.id !== filter.id) return false;
+	if (filter.sdtType !== void 0 && control.properties.sdtType !== filter.sdtType) return false;
+	return true;
+}
+function walk(blocks, filter, out, ancestry, path, location) {
+	for (let i = 0; i < blocks.length; i += 1) {
+		const block = blocks[i];
+		if (!block) continue;
+		if (block.type === "blockSdt") {
+			if (matches(block, filter)) out.push({
+				control: block,
+				ancestry: [...ancestry],
+				path: [...path, i],
+				location
+			});
+			walk(block.content, filter, out, [...ancestry, block], [...path, i], location);
+		} else if (block.type === "table") for (let r = 0; r < block.rows.length; r += 1) {
+			const row = block.rows[r];
+			if (!row) continue;
+			for (let c = 0; c < row.cells.length; c += 1) {
+				const cell = row.cells[c];
+				if (!cell) continue;
+				walk(cell.content, filter, out, ancestry, [
+					...path,
+					i,
+					r,
+					c
+				], location);
+			}
+		}
+	}
+}
+function findContentControls(doc, filter = {}) {
+	const out = [];
+	walk(doc.package.document.content, filter, out, [], [], { kind: "body" });
+	for (const footnote of doc.package.footnotes ?? []) walk(footnote.content, filter, out, [], [], {
+		kind: "footnote",
+		noteId: footnote.id
+	});
+	for (const endnote of doc.package.endnotes ?? []) walk(endnote.content, filter, out, [], [], {
+		kind: "endnote",
+		noteId: endnote.id
+	});
+	return out;
+}
+function findContentControl(doc, filter) {
+	for (const match of findContentControls(doc, filter)) return match;
+	return null;
+}
+/**
+* Concatenated plain text of every paragraph descendant inside a control,
+* separated by newlines. Useful for template/agent read paths.
+*/
+function getContentControlText(control) {
+	const parts = [];
+	const visit = (blocks) => {
+		for (const block of blocks) if (block.type === "paragraph") {
+			const paraText = [];
+			for (const item of block.content) if (item.type === "run") {
+				for (const child of item.content) if (child.type === "text") paraText.push(child.text);
+			}
+			parts.push(paraText.join(""));
+		} else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) visit(cell.content);
+		else visit(block.content);
+	};
+	visit(control.content);
+	return parts.join("\n");
+}
+//#endregion
+export { findContentControl, findContentControls, getContentControlText };

package/dist/content-controls/index.d.ts

@@ -0,0 +1,4 @@
+import { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError } from "./errors.js";
+import { ContentControlFilter, ContentControlMatch, findContentControl, findContentControls, getContentControlText } from "./findContentControls.js";
+import { SetContentControlContentInput, SetContentControlValueInput, removeContentControl, setContentControlContent, setContentControlValue } from "./mutateContentControls.js";
+export { ContentControlBoundError, type ContentControlFilter, ContentControlLockedError, type ContentControlMatch, ContentControlTypeError, type SetContentControlContentInput, type SetContentControlValueInput, findContentControl, findContentControls, getContentControlText, removeContentControl, setContentControlContent, setContentControlValue };

package/dist/content-controls/index.js

@@ -0,0 +1,4 @@
+import { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError } from "./errors.js";
+import { findContentControl, findContentControls, getContentControlText } from "./findContentControls.js";
+import { removeContentControl, setContentControlContent, setContentControlValue } from "./mutateContentControls.js";
+export { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError, findContentControl, findContentControls, getContentControlText, removeContentControl, setContentControlContent, setContentControlValue };

package/dist/content-controls/mutateContentControls.d.ts

@@ -0,0 +1,51 @@
+import { document_d_exports } from "../types/document.js";
+import { ContentControlFilter } from "./findContentControls.js";
+
+//#region src/content-controls/mutateContentControls.d.ts
+type ForceOption = {
+  force?: boolean;
+};
+type SetContentControlContentInput = string | document_d_exports.BlockContent[];
+type SetContentControlValueInput = {
+  kind: "dropdown";
+  value: string;
+} | {
+  kind: "checkbox";
+  checked: boolean;
+} | {
+  kind: "date";
+  date: string;
+};
+/**
+ * Replace a control's inner content. Plain text becomes one paragraph; an
+ * explicit `BlockContent[]` is deep-cloned to preserve immutability. The
+ * `showingPlcHdr` flag is cleared so the new content is not styled as
+ * placeholder.
+ *
+ * Applies to SDTs in the main body AND inside `doc.package.footnotes` /
+ * `doc.package.endnotes`. NOTE: save-path propagation for note SDTs is a
+ * known follow-up — `repackDocxFromRaw` currently replays
+ * `word/footnotes.xml` and `word/endnotes.xml` verbatim from the source
+ * zip, so changes to note SDTs land on the in-memory model but the
+ * saved DOCX still contains the original note text. Read APIs
+ * (`findContentControls`, `getFootnoteText`) reflect the update in the
+ * same session; persisting requires extending the selective-save layer
+ * to re-serialize note parts.
+ */
+declare function setContentControlContent(doc: document_d_exports.Document, filter: ContentControlFilter, input: SetContentControlContentInput, options?: ForceOption): document_d_exports.Document;
+/**
+ * Set a structured value on a typed control. Dropdown / checkbox / date
+ * each get their own input shape so the input is type-checked at the
+ * call site.
+ */
+declare function setContentControlValue(doc: document_d_exports.Document, filter: ContentControlFilter, input: SetContentControlValueInput, options?: ForceOption): document_d_exports.Document;
+/**
+ * Remove a control. With `{ keepContent: true }` the inner blocks survive
+ * in-place; otherwise the control and its children are dropped. Refuses to
+ * unwrap a `w15:repeatingSection` (would orphan w15 row items).
+ */
+declare function removeContentControl(doc: document_d_exports.Document, filter: ContentControlFilter, options?: ForceOption & {
+  keepContent?: boolean;
+}): document_d_exports.Document;
+//#endregion
+export { SetContentControlContentInput, SetContentControlValueInput, removeContentControl, setContentControlContent, setContentControlValue };