@sobree/core 0.1.29 → 0.1.31

package/dist/doc/api.d.ts

@@ -50,6 +50,20 @@ export type BlockExpectations = Record<string, number>;
 export interface InlinePosition {
     block: BlockRef;
     offset: number;
+    /**
+     * Set when the position is inside a table cell: the rendered cell address
+     * the `offset` is measured within — `row` (the cell's `<tr>` index in the
+     * table), `col` (its cell index in that row), `blockIndex` (which content
+     * block inside the cell). Absent for ordinary block positions, where
+     * `offset` is the character offset into `block` itself. Lets caret capture
+     * / restore (e.g. undo) land back in the same cell instead of collapsing to
+     * the table boundary.
+     */
+    cell?: {
+        row: number;
+        col: number;
+        blockIndex: number;
+    };
 }
 /**
  * Inclusive range from `from` to `to` — both inline positions. Single-

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

@@ -12,24 +12,22 @@ export declare function positionFromDomPoint(hosts: readonly HTMLElement[], regi
 export declare function rangeFromDomRange(hosts: readonly HTMLElement[], registry: BlockRegistry, range: Range): ApiRange | null;
 /** Read `window.getSelection()` as a model `Selection`. */
 export declare function selectionFromDom(hosts: readonly HTMLElement[], registry: BlockRegistry): Selection;
-/** Resolve an `InlinePosition` to a DOM `{ node, offset }` point. */
-export declare function domPointFromPosition(hosts: readonly HTMLElement[], registry: BlockRegistry, pos: InlinePosition): {
+/** Resolve an `InlinePosition` to a DOM `{ node, offset }` point. Locates the
+ *  block by its stable `data-block-id` — robust to paper / column / list
+ *  nesting, where the block is never a direct host child. */
+export declare function domPointFromPosition(hosts: readonly HTMLElement[], pos: InlinePosition): {
     node: Node;
     offset: number;
 } | null;
 /** Apply a model `Selection` to `window.getSelection()`. */
-export declare function applySelectionToDom(hosts: readonly HTMLElement[], registry: BlockRegistry, selection: Selection): boolean;
+export declare function applySelectionToDom(hosts: readonly HTMLElement[], selection: Selection): boolean;
 /** Total character-count length of a block, per the counting rules above. */
 export declare function blockLength(blockEl: Element): number;
-/**
- * Enumerate blocks across all content hosts in document order,
- * expanding `<ul>`/`<ol>` children as one block each. Returns the
- * total block count.
- */
-export declare function countBlocks(hosts: readonly HTMLElement[]): number;
-/**
- * Return the DOM element that hosts a given block index. For list-item
- * blocks this is the `<li>`; for everything else it's the direct host
- * child.
- */
+/** The DOM element for body block `index` via the positional `data-block-index`
+ *  stamp. Requires `data-block-id` too, so table cell paragraphs (which carry a
+ *  cell-internal `data-block-index` but no id) can't shadow a body block. Valid
+ *  against a freshly-rendered DOM (index === body position). */
 export declare function blockElementAtIndex(hosts: readonly HTMLElement[], index: number): HTMLElement | null;
+/** Count distinct blocks in the rendered DOM. Dedups by id so a block split
+ *  across a page boundary (two fragments, one id) counts once. */
+export declare function countBlocks(hosts: readonly HTMLElement[]): number;

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,11 +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 keeps table
- *     edits at the block boundary today — operate on `Table` blocks
- *     directly via `replaceBlock` unless a dedicated headless table
- *     API is added.
+ *
+ * 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
  *
@@ -106,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. */

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';