@stll/folio-core 0.35.1 → 0.37.0

package/dist/compare/content-types.d.ts

@@ -0,0 +1,100 @@
+//#region src/compare/content-types.d.ts
+/** How callers expect a block identifier to behave across document revisions. */
+type FolioContentIdStability = "stable" | "positional";
+/** One enclosing structural container, ordered outermost to innermost in a block path. */
+type FolioContentContainerPathEntry = {
+  kind: string;
+  id: string;
+};
+/** Boolean inline properties represented by content snapshots. */
+type FolioContentInlineBooleanProperty = "bold" | "italic" | "underline" | "strike";
+type FolioContentInlineFormatting = Partial<Record<FolioContentInlineBooleanProperty, boolean>> & {
+  fontFamily?: string | null;
+  fontSizePt?: number | null;
+  color?: string | null;
+};
+/**
+ * An inline-formatting mutation: `false` is an explicit off value, while
+ * `null` removes the direct property so its inherited value becomes effective.
+ */
+type FolioContentInlineFormattingPatch = Omit<FolioContentInlineFormatting, FolioContentInlineBooleanProperty> & Partial<Record<FolioContentInlineBooleanProperty, boolean | null>>;
+type FolioContentRun = {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strike?: boolean;
+  fontFamily?: string;
+  fontSizePt?: number;
+  color?: string;
+  /** Authored run properties only; paragraph and named-style values stay inherited. */
+  directFormatting?: FolioContentInlineFormatting;
+};
+/**
+ * Where a block sits inside its innermost enclosing table. Every index is
+ * zero-based: `tableIndex` counts tables in document order across the story,
+ * `rowIndex` is the row's index in that table, `cellIndex` is the cell's
+ * physical index within the row (a merged cell occupies one slot, so this is
+ * not a grid column), and `paragraphIndex` orders the block among the cell's
+ * own blocks. Absent on a block that is not inside a table.
+ */
+type FolioContentTableLocation = {
+  /**
+   * Document-order index of the outermost table the block sits in. This equals
+   * `tableIndex` unless tables nest.
+   */
+  outerTableIndex: number;
+  tableIndex: number;
+  rowIndex: number;
+  cellIndex: number;
+  /** Grid column occupied by the cell's left edge. */
+  gridColumnIndex: number;
+  /** Number of grid columns occupied by this physical cell. */
+  columnSpan: number;
+  /** Number of grid rows occupied by this physical cell. */
+  rowSpan: number;
+  paragraphIndex: number;
+};
+/** Direct paragraph alignment understood by the neutral comparison model. */
+type FolioContentParagraphAlignment = "left" | "center" | "right" | "both" | "distribute" | "mediumKashida" | "highKashida" | "lowKashida" | "thaiDistribute";
+/** Line-height interpretation understood by the neutral comparison model. */
+type FolioContentLineSpacingRule = "auto" | "exact" | "atLeast";
+/**
+ * The complete modeled attribute set of direct paragraph spacing. Optional
+ * fields distinguish an absent attribute from an explicit zero or false value.
+ */
+type FolioContentParagraphSpacing = {
+  spaceBefore?: number;
+  spaceAfter?: number;
+  lineSpacing?: number;
+  lineSpacingRule?: FolioContentLineSpacingRule;
+  beforeAutospacing?: boolean;
+  afterAutospacing?: boolean;
+};
+/** A representation-neutral block in one ordered document story. */
+type FolioContentBlock<Kind extends string = string> = {
+  id: string;
+  kind: Kind;
+  text: string;
+  idStability?: FolioContentIdStability;
+  /** One-based heading depth when the block has outline semantics. */
+  headingLevel?: number;
+  displayLabel?: string;
+  styleId?: string;
+  /** Direct paragraph alignment; absent when alignment comes only from a style. */
+  directAlignment?: FolioContentParagraphAlignment;
+  /** Direct paragraph spacing; absent when every spacing value is inherited. */
+  directSpacing?: FolioContentParagraphSpacing;
+  /** Zero-based list indent level when the block carries numbering. */
+  listLevel?: number;
+  previewRuns?: readonly FolioContentRun[];
+  table?: FolioContentTableLocation;
+  /** Structural ancestry, ordered from the outermost to the innermost container. */
+  containerPath?: readonly FolioContentContainerPathEntry[];
+};
+/** Every block of one story, in document order. */
+type FolioContentSnapshot<Block extends FolioContentBlock = FolioContentBlock> = {
+  blocks: readonly Block[];
+};
+//#endregion
+export { FolioContentBlock, FolioContentContainerPathEntry, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentParagraphAlignment, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation };

package/dist/compare/content.d.ts

@@ -0,0 +1,209 @@
+import { FolioContentBlock, FolioContentIdStability, FolioContentInlineFormattingPatch, FolioContentParagraphSpacing, FolioContentSnapshot } from "./content-types.js";
+import { WordDiffGranularity, createWordDiffSession } from "../ai-edits/word-diff.js";
+import { FolioContentAlignmentStep, FolioContentAlignmentWorkSession } from "./content-alignment.js";
+import { Result } from "better-result";
+//#region src/compare/content.d.ts
+/** Hard resource ceilings for one representation-neutral comparison. */
+declare const FOLIO_CONTENT_COMPARISON_LIMITS: Readonly<{
+  readonly blocksPerSnapshot: 100000;
+  readonly changes: 10000;
+  readonly blockCodeUnits: 1048576;
+  readonly textCodeUnitsPerSnapshot: 8000000;
+  readonly previewRunsPerBlock: 65536;
+  readonly previewRunsPerSnapshot: 1000000;
+  readonly containerDepth: 64;
+  readonly containerEntriesPerSnapshot: 1000000;
+  readonly attributeCodeUnits: 16384;
+  readonly attributeCodeUnitsPerSnapshot: 8000000;
+}>;
+type FolioContentComparisonLimit = keyof typeof FOLIO_CONTENT_COMPARISON_LIMITS;
+declare const InvalidFolioContentComparisonError_base: import("better-result").TaggedErrorClass<"InvalidFolioContentComparisonError">;
+declare class InvalidFolioContentComparisonError extends InvalidFolioContentComparisonError_base<{
+  message: string;
+  input: "options" | "base" | "revised";
+  blockIndex?: number;
+  field: string;
+}> {}
+declare const FolioContentComparisonLimitError_base: import("better-result").TaggedErrorClass<"FolioContentComparisonLimitError">;
+declare class FolioContentComparisonLimitError extends FolioContentComparisonLimitError_base<{
+  message: string;
+  input: "base" | "revised" | "result";
+  limit: FolioContentComparisonLimit;
+  maximum: number;
+  actual: number;
+  blockIndex?: number;
+  field?: string;
+}> {}
+/** Errors returned by {@link compareContent}. */
+type FolioContentComparisonError = InvalidFolioContentComparisonError | FolioContentComparisonLimitError;
+/** One Folio word-diff segment with JavaScript-slice-compatible offsets. */
+type FolioContentTextSegment = {
+  type: "equal" | "del" | "ins";
+  text: string;
+  baseStart: number;
+  baseEnd: number;
+  revisedStart: number;
+  revisedEnd: number;
+};
+/** Target-side paragraph properties that differ from the base block. */
+type FolioContentParagraphFormattingPatch = {
+  styleId?: string | null;
+  listLevel?: number | null;
+  alignment?: FolioContentBlock["directAlignment"] | null;
+  spacing?: FolioContentParagraphSpacing | null;
+};
+/** Presentation differences for one text-aligned block pair. */
+type FolioContentFormatRange = {
+  startOffset: number;
+  endOffset: number;
+  formatting: FolioContentInlineFormattingPatch;
+};
+/** Presentation differences for one text-aligned block pair. */
+type FolioContentFormattingChange = {
+  paragraph?: FolioContentParagraphFormattingPatch;
+  ranges: readonly FolioContentFormatRange[];
+};
+/** Non-presentation block fields that changed on a paired block. */
+type FolioContentBlockProperty = "kind" | "headingLevel" | "displayLabel";
+type PairedEvent<Block extends FolioContentBlock> = {
+  baseBlocks: readonly [Block];
+  revisedBlocks: readonly [Block];
+};
+type BaseOnlyEvent<Block extends FolioContentBlock> = {
+  baseBlocks: readonly [Block];
+  revisedBlocks: readonly [];
+};
+type RevisedOnlyEvent<Block extends FolioContentBlock> = {
+  baseBlocks: readonly [];
+  revisedBlocks: readonly [Block];
+};
+/**
+ * One item in the complete comparison stream. Tuple cardinality is fixed by
+ * the discriminator, making both document projections mechanically exact.
+ */
+type FolioContentComparisonEvent<Block extends FolioContentBlock = FolioContentBlock> = ({
+  type: "unchanged";
+} & PairedEvent<Block>) | ({
+  type: "modified";
+  segments: readonly FolioContentTextSegment[];
+  changedProperties: readonly FolioContentBlockProperty[];
+  formatting?: FolioContentFormattingChange;
+} & PairedEvent<Block>) | ({
+  type: "formatting";
+  formatting: FolioContentFormattingChange;
+} & PairedEvent<Block>) | ({
+  type: "inserted";
+  structuralChangeId?: number;
+} & RevisedOnlyEvent<Block>) | ({
+  type: "deleted";
+  structuralChangeId?: number;
+} & BaseOnlyEvent<Block>) | ({
+  type: "movedFrom";
+  moveId: number;
+} & BaseOnlyEvent<Block>) | ({
+  type: "movedTo";
+  moveId: number;
+  baseBlockId: string;
+  segments?: readonly FolioContentTextSegment[];
+  changedProperties?: readonly FolioContentBlockProperty[];
+  formatting?: FolioContentFormattingChange;
+} & RevisedOnlyEvent<Block>) | {
+  type: "split";
+  baseBlocks: readonly [Block];
+  revisedBlocks: readonly [Block, Block];
+  offset: number;
+  separator: string;
+} | {
+  type: "merge";
+  baseBlocks: readonly [Block, Block];
+  revisedBlocks: readonly [Block];
+  separator: string;
+};
+type BaseStructuralChange = {
+  id: number;
+  baseBlockIds: readonly string[];
+};
+type RevisedStructuralChange = {
+  id: number;
+  revisedBlockIds: readonly string[];
+};
+/** A grouped table operation referenced by its block-granular stream events. */
+type FolioContentStructuralChange = ({
+  type: "table-delete";
+  tableIndex: number;
+} & BaseStructuralChange) | ({
+  type: "table-insert";
+  tableIndex: number;
+} & RevisedStructuralChange) | ({
+  type: "table-row-delete";
+  tableIndex: number;
+  rowIndex: number;
+} & BaseStructuralChange) | ({
+  type: "table-row-insert";
+  tableIndex: number;
+  rowIndex: number;
+} & RevisedStructuralChange) | ({
+  type: "table-column-delete";
+  tableIndex: number;
+  columnIndex: number;
+} & BaseStructuralChange) | ({
+  type: "table-column-insert";
+  tableIndex: number;
+  columnIndex: number;
+} & RevisedStructuralChange);
+/** Result of one representation-neutral story comparison. */
+type FolioContentComparison<Block extends FolioContentBlock = FolioContentBlock> = {
+  events: readonly FolioContentComparisonEvent<Block>[];
+  structuralChanges: readonly FolioContentStructuralChange[];
+};
+/** Inputs to {@link compareContent}. */
+type CompareContentOptions<Block extends FolioContentBlock = FolioContentBlock> = {
+  base: FolioContentSnapshot<Block>;
+  revised: FolioContentSnapshot<Block>;
+  /** Token size for modified-block segments; defaults to `"word"`. */
+  granularity?: WordDiffGranularity;
+};
+type FolioContentComparisonWorkSession = {
+  alignment: FolioContentAlignmentWorkSession;
+  remainingMoveComparisons: number;
+  remainingMoveTokenLookups: number;
+  diffText: ReturnType<typeof createWordDiffSession>["diff"];
+};
+declare const createContentComparisonWorkSession: (granularity?: WordDiffGranularity) => FolioContentComparisonWorkSession;
+declare const changedFolioContentParagraphFormatting: (base: FolioContentBlock, revised: FolioContentBlock) => FolioContentParagraphFormattingPatch | null;
+type ParagraphMarkPlan<Block extends FolioContentBlock> = {
+  type: "split";
+  baseBlock: Block;
+  revisedBlocks: readonly [Block, Block];
+  offset: number;
+  separator: string;
+} | {
+  type: "merge";
+  baseBlocks: readonly [Block, Block];
+  revisedBlock: Block;
+  separator: string;
+};
+declare const detectFolioContentParagraphMarkPlans: <Block extends FolioContentBlock>(steps: readonly FolioContentAlignmentStep<Block>[]) => ReadonlyMap<number, ParagraphMarkPlan<Block>>;
+type MovePair<Block extends FolioContentBlock> = {
+  baseBlock: Block;
+  revisedBlock: Block;
+};
+declare const detectFolioContentMoves: <Block extends FolioContentBlock>({ steps, consumedStepIndexes, workSession, idStability }: {
+  steps: readonly FolioContentAlignmentStep<Block>[];
+  consumedStepIndexes: ReadonlySet<number>;
+  workSession: FolioContentComparisonWorkSession;
+  idStability?: (block: Block) => FolioContentIdStability;
+}) => readonly MovePair<Block>[];
+type CompareAlignedContentOptions<Block extends FolioContentBlock> = {
+  baseBlocks: readonly Block[];
+  revisedBlocks: readonly Block[];
+  steps: readonly FolioContentAlignmentStep<Block>[];
+  workSession: FolioContentComparisonWorkSession;
+  maxChanges: number;
+  idStability?: (block: Block) => FolioContentIdStability;
+};
+declare const compareAlignedFolioContent: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }: CompareAlignedContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonLimitError>;
+/** Compare two representation-neutral ordered content snapshots. */
+declare const compareContent: <Block extends FolioContentBlock = FolioContentBlock>(options: CompareContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonError>;
+//#endregion
+export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, FolioContentFormatRange, FolioContentFormattingChange, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };