@sobree/core 0.1.28 → 0.1.30

package/dist/editor/index.d.ts

@@ -7,10 +7,11 @@ import { History } from '../history';
 import { BlockRegistry } from './internal/blockRegistry';
 import { countBlocks } from './internal/positionMap';
 import { EditorNumbering } from './numbering';
+import { RenderedDocumentIndex } from './renderedDocument';
 import { EditorSections } from './sections';
 import { EditorSelection } from './selection';
 import { EditorStyles } from './styles';
-import { EditorTable } from './table';
+import { TableApi } from './table';
 import { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, KeyDownPayload, NamedStylePatch, OutlineItem, ParagraphPropertiesPatch, RevisionSpan, SectionPropertiesPatch, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag } from './types';
 import * as Y from "yjs";
 export { EditorCommands } from './commands';
@@ -28,7 +29,7 @@ export declare class Editor {
      * unmerge, cell-level properties. Every method returns an `EditResult`
      * and inherits optimistic-lock checking via `replaceBlock`.
      */
-    readonly table: EditorTable;
+    readonly table: TableApi;
     /**
      * Section-level edit operations — page size / margins, columns,
      * header/footer references, vertical alignment. Grouped here (rather
@@ -56,6 +57,10 @@ export declare class Editor {
      * keyboard / toolbar / agent / MCP all dispatch through `execute()`.
      */
     readonly commands: CommandBus;
+    /** Typed lookup mapping rendered DOM elements ↔ document concepts
+     *  (blocks, revision marks, comment ranges) — the bridge plugins use
+     *  instead of hardcoding renderer selectors. See `./renderedDocument`. */
+    readonly renderedDocument: RenderedDocumentIndex;
     /**
      * Y.Doc backing the document. The Editor's `this.doc` field is a
      * cached projection of this Y.Doc — every local mutation mirrors

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/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/renderedDocument/blocks.d.ts

@@ -0,0 +1,14 @@
+import { BlockRef } from '../../doc/api';
+import { BlockRegistry } from '../internal/blockRegistry';
+/** Id of the nearest block ancestor of `el` (including `el`), or `null`. */
+export declare function blockIdFromElement(el: Element): string | null;
+/**
+ * Live, versioned ref of the nearest block ancestor of `el`, or `null`.
+ * Returns `null` when the id isn't live in the registry (e.g. the block
+ * was just deleted) — the registry is the source of truth for versions.
+ */
+export declare function blockRefFromElement(el: Element, registry: BlockRegistry): BlockRef | null;
+/** Rendered element bearing `blockId`, searched across `roots`, or `null`. */
+export declare function elementForBlockId(blockId: string, roots: readonly ParentNode[]): HTMLElement | null;
+/** Rendered element for a block ref (matched by id), or `null`. */
+export declare function elementForBlock(ref: BlockRef, roots: readonly ParentNode[]): HTMLElement | null;

package/dist/editor/renderedDocument/comments.d.ts

@@ -0,0 +1,6 @@
+import { BlockRegistry } from '../internal/blockRegistry';
+import { RenderedCommentRange } from './types';
+/** Every comment range under `root`. */
+export declare function commentRanges(root: ParentNode, registry: BlockRegistry): RenderedCommentRange[];
+/** Nearest comment range at or above `target`, or `null`. */
+export declare function nearestCommentRange(target: Element, registry: BlockRegistry): RenderedCommentRange | null;

package/dist/editor/renderedDocument/index.d.ts

@@ -0,0 +1,27 @@
+import { BlockRef } from '../../doc/api';
+import { BlockRegistry } from '../internal/blockRegistry';
+import { RenderedCommentRange, RenderedDocumentIndex, RenderedRevisionMark } from './types';
+export type { RenderedBlockLookup, RenderedCommentLookup, RenderedCommentRange, RenderedDocumentIndex, RenderedRevisionKind, RenderedRevisionLookup, RenderedRevisionMark, } from './types';
+/**
+ * The slice of Editor internals `RenderedDocument` reads — its
+ * decoupling seam, so this module never imports the concrete `Editor`
+ * class. `roots()` returns the default search scope (the editor's
+ * content hosts, where every block / revision / comment element renders).
+ */
+export interface RenderedDocumentHost {
+    roots(): readonly HTMLElement[];
+    registry(): BlockRegistry;
+}
+/** Concrete `RenderedDocumentIndex` over an editor's rendered DOM. */
+export declare class RenderedDocument implements RenderedDocumentIndex {
+    private readonly host;
+    constructor(host: RenderedDocumentHost);
+    elementForBlock(ref: BlockRef): HTMLElement | null;
+    elementForBlockId(blockId: string): HTMLElement | null;
+    blockRefFromElement(element: Element): BlockRef | null;
+    blockIdFromElement(element: Element): string | null;
+    revisionMarks(root?: ParentNode): RenderedRevisionMark[];
+    nearestRevisionMark(target: Element): RenderedRevisionMark | null;
+    commentRanges(root?: ParentNode): RenderedCommentRange[];
+    nearestCommentRange(target: Element): RenderedCommentRange | null;
+}

package/dist/editor/renderedDocument/revisions.d.ts

@@ -0,0 +1,11 @@
+import { BlockRegistry } from '../internal/blockRegistry';
+import { RenderedRevisionMark } from './types';
+/** Every revision mark under `root` — inline, paragraph, then format. */
+export declare function revisionMarks(root: ParentNode, registry: BlockRegistry): RenderedRevisionMark[];
+/**
+ * Nearest revision mark at or above `target`. Specificity order matches
+ * the renderer's nesting: an inserted + format-changed run is wrapped in
+ * BOTH, and accepting the inline insert covers the format change too, so
+ * the inline mark wins.
+ */
+export declare function nearestRevisionMark(target: Element, registry: BlockRegistry): RenderedRevisionMark | null;

package/dist/editor/renderedDocument/selectors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The rendered-DOM protocol — the ONE place the attribute/class names
+ * that cross the renderer ↔ plugin boundary are declared.
+ *
+ * Two sides import this module:
+ *   - the **writer**: `view/docRenderer/*` stamps these onto rendered
+ *     elements,
+ *   - the **reader**: `renderedDocument/*` (and, through it, the
+ *     `block-tools` / `review` plugins) queries them.
+ *
+ * Plugins MUST NOT hardcode these strings — they go through the typed
+ * `editor.renderedDocument` surface, which is the only sanctioned reader.
+ * Keeping both sides on these constants means a rename is one edit with
+ * compiler-checked callers, never a silent cross-package break (AGENTS.md
+ * Rule 0: no `data-*` threaded as an inter-module protocol).
+ *
+ * Scope is deliberately narrow: only attributes/classes that are read
+ * across the package boundary live here. Purely-internal renderer
+ * attributes (layout/flow markers like `data-col-count`, `data-page-break`)
+ * stay local to their module.
+ */
+export declare const BLOCK_ID_ATTR = "data-block-id";
+export declare const BLOCK_REVISION_ATTR = "data-block-revision";
+export declare const BLOCK_REVISION_AUTHOR_ATTR = "data-block-revision-author";
+export declare const BLOCK_REVISION_DATE_ATTR = "data-block-revision-date";
+export declare const REVISION_AUTHOR_ATTR = "data-revision-author";
+export declare const REVISION_DATE_ATTR = "data-revision-date";
+export declare const REVISION_FORMAT_AUTHOR_ATTR = "data-revision-format-author";
+export declare const REVISION_FORMAT_DATE_ATTR = "data-revision-format-date";
+export declare const COMMENT_IDS_ATTR = "data-comment-ids";
+export declare const CLS_REVISION = "sobree-revision";
+export declare const CLS_REVISION_FORMAT = "sobree-revision-format";
+export declare const CLS_COMMENT_RANGE = "sobree-comment-range";
+/** Matches every inline tracked-change wrapper (`<ins>` / `<del>`). */
+export declare const INLINE_REVISION_SELECTOR = "ins[data-revision-author], del[data-revision-author]";
+/** Matches every paragraph-mark revision (the block element). */
+export declare const BLOCK_REVISION_SELECTOR = "[data-block-revision]";
+/** Matches every format-change wrapper. */
+export declare const FORMAT_REVISION_SELECTOR = "span.sobree-revision-format";
+/** Matches every comment-range highlight wrapper. */
+export declare const COMMENT_RANGE_SELECTOR = ".sobree-comment-range";
+/** Matches any element carrying a block id (the nearest block ancestor). */
+export declare const BLOCK_ID_SELECTOR = "[data-block-id]";
+/** Selector for the element bearing a specific block id. */
+export declare function blockIdSelector(id: string): string;
+/**
+ * Minimal `CSS.escape` fallback for environments without it (jsdom,
+ * older browsers). Block ids are alphanumeric + underscore in practice,
+ * so a tight regex suffices.
+ */
+export declare function cssEscape(s: string): string;

package/dist/editor/renderedDocument/types.d.ts

@@ -0,0 +1,59 @@
+import { BlockRef } from '../../doc/api';
+/** Which kind of tracked-change a rendered revision mark represents. */
+export type RenderedRevisionKind = "inline-insert" | "inline-delete" | "paragraph" | "format";
+/** A tracked-change mark discovered in the rendered DOM. */
+export interface RenderedRevisionMark {
+    /** What the mark represents — inline insert/delete, a paragraph-mark
+     *  revision, or a run format change. */
+    kind: RenderedRevisionKind;
+    /** The element carrying the mark (the `<ins>`/`<del>`, the format
+     *  `<span>`, or the paragraph block element). */
+    element: HTMLElement;
+    /** Revision author, when stamped. */
+    author?: string;
+    /** Revision date (ISO string), when stamped. */
+    date?: string;
+    /** Ref of the block the mark lives in, when resolvable. */
+    blockRef?: BlockRef;
+}
+/** A comment-range highlight discovered in the rendered DOM. */
+export interface RenderedCommentRange {
+    /** The wrapping highlight `<span>`. */
+    element: HTMLElement;
+    /** Ids of every comment anchored to this range (a range may carry
+     *  more than one when comment ranges overlap). */
+    commentIds: string[];
+    /** Ref of the block the range lives in, when resolvable. */
+    blockRef?: BlockRef;
+}
+/** Map between rendered block elements and document block refs. */
+export interface RenderedBlockLookup {
+    /** Element for a block ref, or `null` if not currently rendered. */
+    elementForBlock(ref: BlockRef): HTMLElement | null;
+    /** Element for a block id, or `null` if not currently rendered. */
+    elementForBlockId(blockId: string): HTMLElement | null;
+    /** Ref of the nearest block ancestor of `element` (a live, versioned
+     *  ref), or `null` if `element` isn't inside a rendered block. */
+    blockRefFromElement(element: Element): BlockRef | null;
+    /** Id of the nearest block ancestor of `element`, or `null`. */
+    blockIdFromElement(element: Element): string | null;
+}
+/** Discover tracked-change marks in the rendered DOM. */
+export interface RenderedRevisionLookup {
+    /** Every revision mark under `root` (defaults to the whole document). */
+    revisionMarks(root?: ParentNode): RenderedRevisionMark[];
+    /** The nearest revision mark at or above `target`, or `null`. Inline
+     *  marks win over format, which win over paragraph — matching the
+     *  nesting order the renderer produces. */
+    nearestRevisionMark(target: Element): RenderedRevisionMark | null;
+}
+/** Discover comment ranges in the rendered DOM. */
+export interface RenderedCommentLookup {
+    /** Every comment range under `root` (defaults to the whole document). */
+    commentRanges(root?: ParentNode): RenderedCommentRange[];
+    /** The nearest comment range at or above `target`, or `null`. */
+    nearestCommentRange(target: Element): RenderedCommentRange | null;
+}
+/** The combined rendered-document lookup surface (`editor.renderedDocument`). */
+export interface RenderedDocumentIndex extends RenderedBlockLookup, RenderedRevisionLookup, RenderedCommentLookup {
+}

package/dist/editor/table.d.ts

@@ -1,11 +1,13 @@
 import { BlockRef, EditResult } from '../doc/api';
 import { SobreeDocument, Block, ParagraphAlignment, Table, TableCell, TableProperties } from '../doc/types';
 /**
- * Minimal slice of `Editor` that `EditorTable` actually needs. Defining
- * it here (rather than `import type { Editor } from "./"`) keeps this
- * module a leaf in the editor/* import graph — no cycle with index.ts.
+ * Minimal slice of an editor-like peer that `TableApi` needs. Both the
+ * browser `Editor` and the no-DOM `HeadlessSobree` satisfy it structurally,
+ * so the same table surface drives `editor.table` and `headless.table`.
+ * Defining it here (rather than `import type { Editor } from "./"`) keeps
+ * this module a leaf in the editor/* import graph — no cycle with index.ts.
  */
-export interface EditorTableHost {
+export interface TableHost {
     getDocument(): SobreeDocument;
     getBlockById(id: string): {
         kind: string;
@@ -55,20 +57,24 @@ export interface MergeCellsOpts {
     colSpan?: number;
 }
 /**
- * Ergonomic table mutation surface. Lives on `editor.table`.
+ * Ergonomic table mutation surface. Lives on `editor.table` (browser) and
+ * `headless.table` (no-DOM peer / LLM agents) — same code, via {@link TableHost}.
  *
  * Every method does the same three steps under the hood:
  *   1. Resolve the target table by `BlockRef` (inherits optimistic-lock
- *      checking from `editor.replaceBlock`).
+ *      checking from the host's `replaceBlock`).
  *   2. Clone and mutate the table immutably.
- *   3. Delegate to `editor.replaceBlock(ref, nextTable)`.
+ *   3. Delegate to the host's `replaceBlock(ref, nextTable)`.
  *
  * No new plumbing; lock semantics, affected-block tracking, and event
- * emission come from the underlying core.
+ * emission come from the underlying core. Because every edit ultimately
+ * round-trips the whole table block, callers never hand-build a `Table`
+ * just to tweak one cell — but at the Y.Doc layer it is still a
+ * whole-table write (per-cell CRDT is a separate, future change).
  */
-export declare class EditorTable {
-    private readonly editor;
-    constructor(editor: EditorTableHost);
+export declare class TableApi {
+    private readonly host;
+    constructor(host: TableHost);
     insertRow(ref: BlockRef, opts: InsertRowOpts): EditResult<BlockRef>;
     deleteRow(ref: BlockRef, index: number): EditResult<BlockRef>;
     insertColumn(ref: BlockRef, opts: InsertColumnOpts): EditResult<BlockRef>;

package/dist/headless.d.ts

@@ -2,6 +2,7 @@ import { BlobCache, BlobStore } from './blob';
 import { BlockRef, EditError, EditResult, Selection } from './doc/api';
 import { Block, NamedStyle, NumberingDefinition, NumberingLevel, ParagraphAlignment, ParagraphProperties, SobreeDocument } from './doc/types';
 import { ParagraphPropertiesPatch, BlockInfo, CommandBus, NamedStylePatch, OutlineItem, SectionPropertiesPatch } from './editor';
+import { TableApi } from './editor/table';
 import { History } from './history';
 /**
  * HeadlessSobree — a no-DOM Sobree peer for LLM agents, automation,
@@ -42,10 +43,11 @@ import { History } from './history';
  *     contentEditable event handling, image-resize handles, paste
  *     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.
+ *
+ * It DOES share the granular table surface: `headless.table.*` is the
+ * same {@link TableApi} as `editor.table.*` (insert/delete rows and
+ * columns, merge/unmerge, set cell content + properties), so agents
+ * never hand-build a `Table` block just to tweak one cell.
  *
  * # Origin tagging
  *
@@ -105,6 +107,8 @@ export declare class HeadlessSobree {
     readonly ydoc: Y.Doc;
     readonly commands: CommandBus;
     readonly history: History;
+    /** Granular table mutations — same {@link TableApi} as `editor.table`. */
+    readonly table: TableApi;
     readonly origin: string;
     /** Optional content-hashed blob layer. Mirrors the browser `Editor`'s
      *  `blobStore` field — null when no store is configured. */
@@ -176,7 +180,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;

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export { Sobree } from './sobree';
 export type { SobreeMode, SobreeOptions, SobreeEvent, SobreeEventPayload, SobreeUnsubscribe, } from './sobree';
 export type { SobreePlugin, SobreePluginInstance, PluginContext, } from './plugin';
 export { Editor } from './editor';
+export { RenderedDocument } from './editor/renderedDocument';
+export type { RenderedBlockLookup, RenderedCommentLookup, RenderedCommentRange, RenderedDocumentIndex, RenderedRevisionKind, RenderedRevisionLookup, RenderedRevisionMark, } from './editor/renderedDocument';
 export type { ApiRangeType, RevisionSpan, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, EditError, EditResult, KeyDownPayload, OutlineItem, ParagraphPropertiesPatch, RunPropertiesPatch, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag, CellRef, InsertAt, InsertColumnOpts, InsertRowOpts, MergeCellsOpts, } from './editor';
 export * from './doc/types';
 export * from './doc/builders';