@sobree/core 0.1.27 → 0.1.29

package/dist/editor/internal/applyMutation.d.ts

@@ -0,0 +1,9 @@
+import { EditResult } from '../../doc/api';
+import { DocumentMutationResult, MutationInput } from '../../doc/mutations';
+import { EditorContext } from '../context';
+/** Build the engine input from the live editor context. The `BlockRegistry`
+ *  satisfies `BlockRegistryView` directly. */
+export declare function mutationInput(ctx: EditorContext): MutationInput;
+/** Apply a mutation result through `ctx.commit`, or pass the failure
+ *  through unchanged. */
+export declare function applyMutation<T>(ctx: EditorContext, result: DocumentMutationResult<T>): EditResult<T>;

package/dist/editor/internal/mutations.d.ts

@@ -1,67 +1,8 @@
 import { RunPropertiesPatch } from '../../doc/runs';
-import { Block, NamedStyle, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument } from '../../doc/types';
-import { NamedStylePatch, ParagraphPropertiesPatch, SectionPropertiesPatch, WrapTag } from '../types';
-/**
- * One registry-level operation produced by a mutation. The caller
- * applies these to the BlockRegistry after committing the new doc:
- * `insert` adds an id, `remove` drops one, `bump` keeps the same id
- * but increments its version.
- */
-export type Mutation = {
-    type: "bump";
-    index: number;
-} | {
-    type: "insert";
-    index: number;
-} | {
-    type: "remove";
-    index: number;
-};
-/**
- * Index in `sections` of the section that ENDS at the section_break at
- * `breakIndex`. Sections are 1:1 with section_breaks; the first
- * section ends at the first break (or at the end of `body` if there's
- * no break).
- *
- *   body = [p, p, break, p, break, p]
- *   sections = [s0, s1, s2]
- *
- *   breakIndex = 2 → 0 (the first break ends section 0)
- *   breakIndex = 4 → 1 (the second break ends section 1)
- */
-export declare function removedSectionIndex(body: readonly Block[], breakIndex: number): number;
-/**
- * Drop the section at `endingIndex + 1` from `sections` — that's the
- * section the now-removed break STARTED. The section ENDED by the
- * removed break (at `endingIndex`) absorbs whatever content used to
- * belong to its successor. Properties of the surviving section are
- * preserved verbatim; nothing about the removed section's settings is
- * carried over.
- *
- * If `sections` doesn't have a successor (the removed break was the
- * last one and there's only one section), the array is returned
- * unchanged.
- */
-export declare function mergeSectionsAcross(sections: readonly SectionProperties[], endingIndex: number): SectionProperties[];
-/**
- * Merge a `ParagraphPropertiesPatch` into existing properties.
- * `undefined` in the patch removes a field; everything else
- * overwrites.
- */
-export declare function mergeParagraphProps(prev: ParagraphProperties, patch: ParagraphPropertiesPatch): ParagraphProperties;
-/**
- * Merge a {@link SectionPropertiesPatch} onto existing section properties.
- * `pageSize` / `pageMargins` are FIELD-merged (a partial stays valid); the
- * other fields replace wholesale. For the optional fields (`columns`,
- * `titlePage`, `type`, `vAlign`) an explicit `undefined` clears them, while
- * the required `headerRefs` / `footerRefs` only replace when present.
- */
-export declare function mergeSectionProps(prev: SectionProperties, patch: SectionPropertiesPatch): SectionProperties;
-/** Merge a {@link NamedStylePatch} onto an existing style. Each present
- *  field replaces the style's field wholesale; an explicit `undefined`
- *  clears an OPTIONAL field. The required `type` / `displayName` are never
- *  cleared (an undefined for them is ignored). */
-export declare function mergeNamedStyle(prev: NamedStyle, patch: NamedStylePatch): NamedStyle;
+import { SobreeDocument } from '../../doc/types';
+import { WrapTag } from '../types';
+export type { Mutation } from '../../doc/mutations';
+export { mergeNamedStyle, mergeParagraphProps, mergeSectionProps, mergeSectionsAcross, removedSectionIndex, } from '../../doc/mutations';
 /**
  * Map a semantic "wrap" tag to the run-property patch that achieves it.
  * Same mapping the browser editor uses for toolbar buttons.
@@ -73,4 +14,3 @@ export declare function mimeToExtension(mime: string): string;
 export declare function allocateMediaPath(doc: SobreeDocument, ext: string): string;
 /** Convert pixels (CSS @ 96 dpi) to OOXML's EMU (914400 per inch). */
 export declare function pxToEmu(px: number): number;
-export type { RunProperties };

package/dist/editor/internal/readbackMerge.d.ts

@@ -0,0 +1,27 @@
+import { Block } from '../../doc/types';
+/**
+ * Merge a freshly DOM-serialised body into the previous AST body, preserving
+ * everything the contentEditable DOM can't represent.
+ *
+ * The DOM is a LOSSY projection of the AST: it carries run text and inline
+ * marks (bold, colour, font), but NOT block-level properties — paragraph
+ * spacing / indent / borders, table style-id / look / cell margins,
+ * section-break targets. A text edit changes a block's CONTENT, never those
+ * properties, so re-deriving the whole AST from the DOM on every keystroke
+ * silently strips them — the document degrades a little with each edit and
+ * falls apart on the first re-render (undo / redo / remote).
+ *
+ * So we keep each previous block and overlay only the re-read content: runs
+ * for a paragraph, cell content for a table. Properties survive.
+ *
+ * Matching a re-read block to its previous block is by stable id (the
+ * renderer's `data-block-id`), resolved by the caller — so properties
+ * survive structural edits too (Enter / Backspace / paste / reorder), not
+ * just same-length typing. A re-read block with no prior match (a freshly
+ * inserted block) keeps the DOM block as-is. Falls back to the DOM block
+ * whenever kinds or nested shape diverge: structure is the one thing the
+ * DOM IS authoritative about.
+ */
+export declare function mergeReadbackBlocks(next: readonly Block[], resolvePrev: (index: number) => Block | undefined): Block[];
+/** Positional convenience wrapper: match each block to `prev[i]`. */
+export declare function mergeReadbackPreservingProps(prev: readonly Block[], next: readonly Block[]): Block[];

package/dist/editor/ops/blocks.d.ts

@@ -4,9 +4,10 @@ import { EditorContext } from '../context';
 import { ParagraphPropertiesPatch } from '../types';
 /**
  * Block-level mutations: replace / insert / delete whole blocks and
- * patch paragraph properties. All enforce optimistic locking via
- * `ctx.checkRefs` and route through `ctx.commit`. Section-break removal
- * merges the two sections it delimited. Track-changes mode stamps
+ * patch paragraph properties. The plain document transform lives in the
+ * shared `doc/mutations` engine (lock check + body splice + section-break
+ * merge); these wrappers add the browser-only track-changes behaviour and
+ * apply the engine's patch through `ctx.commit`. Track-changes mode stamps
  * paragraph insert/delete markers instead of moving content outright.
  */
 /** Replace the block at `target`'s index with `block`. */
@@ -35,7 +36,7 @@ export declare function insertBlockAfter(ctx: EditorContext, target: BlockRef, b
  * `ins` marker (a paragraph the user themselves just created), the block
  * is removed outright — cancelling an un-committed insert, matching the
  * inline `deleteRange` semantics. Non-paragraph blocks (tables, section
- * breaks) bypass tracking in v1 — they remove plainly.
+ * breaks) bypass tracking in v1 — they remove plainly via the engine.
  */
 export declare function deleteBlock(ctx: EditorContext, target: BlockRef): EditResult<void>;
 /** Merge a patch into each target paragraph's properties. */

package/dist/editor/view/docSerialize/block.d.ts

@@ -10,6 +10,17 @@ export interface BlockSerializeContext {
         numId: number;
         ordered: boolean;
     } | null;
+    /**
+     * Running count of section breaks seen so far (across all hosts). The Nth
+     * section break transitions to section N — matching the renderer's
+     * order-based section assignment — so the count IS the break's
+     * `toSectionIndex`. Reconstructing it is load-bearing: the renderer reads
+     * a break's page-break-vs-continuous behaviour from `sections[toSectionIndex]`,
+     * so a wrong index (e.g. a hardcoded 0) makes a continuous break re-render
+     * as a forced page break, exploding the layout on the next re-render
+     * (undo/redo/remote).
+     */
+    sectionBreaks: number;
     /**
      * Capture each paragraph's effective base run style (from the rendered
      * `<p>`'s inline font) into `ParagraphProperties.runDefaults`.
@@ -25,5 +36,15 @@ export interface BlockSerializeContext {
      * styles, which must stay style-linked across edits.
      */
     captureRunDefaults?: boolean;
+    /**
+     * Optional sink for each emitted block's source DOM element (or `null`
+     * for a bare text node), kept strictly parallel to the returned blocks.
+     * The editor reads each element's stable `data-block-id` to match a
+     * re-read block back to its previous AST block — so block-level
+     * properties (spacing, table style, …) survive a read-back across plain
+     * typing AND structural edits, where positional matching can't. Left
+     * unset for callers that don't need provenance (frame read-back, tests).
+     */
+    sources?: (HTMLElement | null)[];
 }
 export declare function blocksFromNodes(nodes: readonly Node[], ctx: BlockSerializeContext): Block[];

package/dist/editor/view/docSerialize/index.d.ts

@@ -15,3 +15,15 @@ export interface SerializeHostsOptions {
     captureRunDefaults?: boolean;
 }
 export declare function serializeHostsToDocument(hosts: readonly HTMLElement[], options?: SerializeHostsOptions): SobreeDocument;
+/**
+ * Like {@link serializeHostsToDocument}, but also returns each block's
+ * source DOM element (parallel to `document.body`, `null` for bare text
+ * nodes). The editor reads each element's stable `data-block-id` to match a
+ * re-read block back to its previous AST block — so block-level properties
+ * the contentEditable DOM can't carry survive the read-back across plain
+ * typing AND structural edits (Enter / Backspace / paste / reorder).
+ */
+export declare function serializeHostsWithSources(hosts: readonly HTMLElement[], options?: SerializeHostsOptions): {
+    document: SobreeDocument;
+    sources: (HTMLElement | null)[];
+};

package/dist/headless.d.ts

@@ -43,9 +43,10 @@ import { History } from './history';
  *     parsing, etc. HeadlessSobree skips all that — if you need
  *     them, mount a real Editor.
  *   - A *table editor*. The browser `Editor` has a rich table API
- *     (`editor.table.insertRow`, etc.). HeadlessSobree v0 doesn't
- *     wrap that — operate on `Table` blocks directly via
- *     `replaceBlock` until Phase 4.x adds a parallel table API.
+ *     (`editor.table.insertRow`, etc.). HeadlessSobree keeps table
+ *     edits at the block boundary today — operate on `Table` blocks
+ *     directly via `replaceBlock` unless a dedicated headless table
+ *     API is added.
  *
  * # Origin tagging
  *
@@ -176,7 +177,12 @@ export declare class HeadlessSobree {
      * in the local cache. No-op when no `blobStore` is configured.
      */
     ensurePartsLoaded(): Promise<void>;
-    private checkRefs;
+    /** Build the engine input from this peer's live state. The
+     *  `BlockRegistry` satisfies `BlockRegistryView` directly. */
+    private mutationInput;
+    /** Apply a mutation engine result through `commit`, or pass the failure
+     *  through unchanged. */
+    private applyPatch;
     private commit;
     private fireChange;
     private summariseBlock;