@stll/folio-core 0.8.0 → 0.10.0

package/README.md

@@ -32,6 +32,45 @@ bun add @stll/folio-core
 | `@stll/folio-core/server`   | DOM-free helpers for server-side use (block-id derivation, document creation, re-zip)                                                                              |
 | `@stll/folio-core/*`        | the source-mirrored module tree (e.g. `@stll/folio-core/types/document`, `@stll/folio-core/prosemirror/schema`) for adapters that need lower-level building blocks |
 
+## New documents and reusable style sets
+
+Create a legal-shaped blank document with the built-in preset:
+
+```ts
+import { createDocx, createEmptyDocument, createStellaStyleDocumentPreset } from "@stll/folio-core";
+
+const document = createEmptyDocument({
+  preset: createStellaStyleDocumentPreset(),
+});
+const docx = await createDocx(document);
+```
+
+Style sets are content-free JSON values. Inspect a source file before presenting
+styles for selection, extract the selected dependency closure, persist the
+result, and load it into any later document:
+
+```ts
+import {
+  createEmptyDocument,
+  extractDocumentStyleSetFromDocx,
+  inspectDocumentStylesFromDocx,
+} from "@stll/folio-core";
+
+const catalog = await inspectDocumentStylesFromDocx(sourceDocx);
+const styleSet = await extractDocumentStyleSetFromDocx(sourceDocx, {
+  name: "Firm contract styles",
+  styleIds: catalog.styles
+    .filter(({ role }) => role === "default" || role === "quick")
+    .map(({ styleId }) => styleId),
+});
+
+const document = createEmptyDocument({ styleSet });
+```
+
+Extraction excludes document content, metadata, relationships, media, comments,
+and revision data. It keeps only the selected styles and the numbering, theme,
+font-table, and settings data required to reproduce their formatting.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/dist/ai-edits/apply.js

@@ -678,10 +678,24 @@ const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId,
 	}
 	if (operation.type === "deleteBlock" || operation.type === "replaceBlock") {
 		const range = getTextRangeFromCleanBlock(cleanBlock);
-		if (!range) return {
-			type: "skip",
-			reason: "unsupportedBlock"
-		};
+		if (!range) {
+			const insertionPoint = cleanBlock.offsets.at(0);
+			if (operation.type === "replaceBlock" && currentText.length === 0 && operation.text.length > 0 && insertionPoint !== void 0) return {
+				type: "resolved",
+				operation: {
+					operation,
+					from: insertionPoint,
+					to: insertionPoint,
+					blockFrom,
+					blockTo,
+					blockNode
+				}
+			};
+			return {
+				type: "skip",
+				reason: "unsupportedBlock"
+			};
+		}
 		if (operation.type === "replaceBlock" && operation.text === currentText) return {
 			type: "skip",
 			reason: "noopOperation"

package/dist/ai-edits/headless.d.ts

@@ -30,19 +30,61 @@ type FolioGetContentAsTextOptions = {
    */
   annotated?: boolean;
 };
+declare const FOLIO_REVIEWED_VIEWS: readonly ["original", "current-markup", "final"];
+type FolioReviewedView = (typeof FOLIO_REVIEWED_VIEWS)[number];
+declare const FOLIO_RESOLVED_REVIEWED_VIEWS: readonly ["original", "final"];
+type FolioResolvedReviewedView = (typeof FOLIO_RESOLVED_REVIEWED_VIEWS)[number];
 type FolioDocumentStoryHandle = {
   type: "main";
 } | {
-  type: "header" | "footer";
+  type: "header";
   relationshipId: string;
 } | {
-  type: "footnote" | "endnote";
+  type: "footer";
+  relationshipId: string;
+} | {
+  type: "footnote";
+  noteId: number;
+} | {
+  type: "endnote";
   noteId: number;
 };
+type FolioEditableDocumentStoryHandle = FolioDocumentStoryHandle;
 type FolioDocumentStory = {
   handle: FolioDocumentStoryHandle;
   text: string;
 };
+type FolioReadReviewedStoryOptions = {
+  story?: FolioEditableDocumentStoryHandle;
+  view?: FolioReviewedView;
+};
+type FolioResolveReviewedStoryOptions = {
+  story?: FolioEditableDocumentStoryHandle;
+  view: FolioResolvedReviewedView;
+};
+type FolioReviewedStory = {
+  story: FolioEditableDocumentStoryHandle;
+  view: FolioReviewedView;
+  snapshot: FolioAIEditSnapshot;
+  text: string;
+  changes: FolioReviewChange[];
+};
+declare const UnsupportedFolioReviewedViewError_base: import("better-result").TaggedErrorClass<"UnsupportedFolioReviewedViewError", {
+  message: string;
+  receivedView: unknown;
+}>;
+declare class UnsupportedFolioReviewedViewError extends UnsupportedFolioReviewedViewError_base {}
+declare const FolioDocumentStoryNotFoundError_base: import("better-result").TaggedErrorClass<"FolioDocumentStoryNotFoundError", {
+  message: string;
+  story: FolioEditableDocumentStoryHandle;
+}>;
+declare class FolioDocumentStoryNotFoundError extends FolioDocumentStoryNotFoundError_base {}
+type FolioApplyDocumentOperationsToStoryOptions = FolioApplyDocumentOperationsOptions & {
+  story: FolioEditableDocumentStoryHandle;
+  batch: FolioDocumentOperationBatch;
+};
+declare const isFolioReviewedView: (value: unknown) => value is FolioReviewedView;
+declare const isFolioResolvedReviewedView: (value: unknown) => value is FolioResolvedReviewedView;
 /** Filter for {@link FolioDocxReviewer.getChanges}. */
 type FolioReviewChangeFilter = {
   author?: string;
@@ -97,6 +139,7 @@ declare class FolioDocxReviewer {
   private readonly baseDocument;
   private readonly originalBuffer;
   private state;
+  private readonly secondaryStoryStates;
   private readonly createdComments;
   private readonly documentOperationUndoEntries;
   /**
@@ -116,6 +159,17 @@ declare class FolioDocxReviewer {
    * the anchor map the apply layer resolves operations against.
    */
   snapshot(): FolioAIEditSnapshot;
+  /** Return parsed package metadata without exposing the mutable document model. */
+  getDocumentProperties(): Readonly<NonNullable<document_d_exports.Document["package"]["properties"]>> | null;
+  /** Snapshot one editable story into stable, operation-ready blocks. */
+  snapshotStory(story: FolioEditableDocumentStoryHandle): FolioAIEditSnapshot | null;
+  /** Read one story through an immutable reviewed-view projection. */
+  readReviewedStory(options?: FolioReadReviewedStoryOptions): FolioReviewedStory | null;
+  /** Resolve one editable story to its original or final state. */
+  resolveReviewedStory({
+    story,
+    view
+  }: FolioResolveReviewedStoryOptions): boolean;
   /**
    * Apply operations against the current state. Reuses the live-editor applier
    * verbatim via a headless `{ state, dispatch }` seam; the resulting state
@@ -129,6 +183,12 @@ declare class FolioDocxReviewer {
    * edit semantics.
    */
   applyDocumentOperations(batch: FolioDocumentOperationBatch, options?: FolioApplyDocumentOperationsOptions): FolioDocumentOperationResult;
+  /** Apply a versioned operation batch to one editable document story. */
+  applyDocumentOperationsToStory({
+    story,
+    batch,
+    snapshot
+  }: FolioApplyDocumentOperationsToStoryOptions): FolioDocumentOperationResult;
   private applyDocumentOperationsInternal;
   /** Undo the latest unchanged document-operation batch and its created comments. */
   undoDocumentOperations(undoHandle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
@@ -153,9 +213,8 @@ declare class FolioDocxReviewer {
   /**
    * Header / footer and footnote / endnote text as labeled, LLM-ready lines,
    * one per non-empty part: `[header default] …`, `[footer default] …`,
-   * `[footnote #N] …`, `[endnote #N] …`. Read-only — note bodies are outside
-   * the reviewer's body-only apply scope, so this reflects the parsed source.
-   * Empty parts and separator notes are omitted.
+   * `[footnote #N] …`, `[endnote #N] …`. Lines reflect in-memory edits. Empty
+   * parts and separator notes are omitted.
    */
   getNotesAsText(): string;
   /** Discover every readable document story through a typed, serializable handle. */
@@ -239,6 +298,14 @@ declare class FolioDocxReviewer {
    * is the graceful handling — no separate error surface is needed here.
    */
   private trySelectiveSave;
+  private getEditableStoryState;
+  private requireEditableStoryState;
+  private setEditableStoryState;
+  private getHeaderFooterStory;
+  private getNoteStory;
+  private getHeaderFooterStoryText;
+  private getNoteStoryText;
+  private mergeEditedSecondaryStories;
   /**
    * Count every tracked change an accept-all / reject-all sweep resolves: the
    * inline insertion / deletion groups {@link getChanges} enumerates, plus the
@@ -283,4 +350,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyDocumentOperationsOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocxReviewer, FolioDocxReviewerOptions, FolioGetContentAsTextOptions, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };