@sobree/core 0.1.0

package/dist/sobree.d.ts

@@ -0,0 +1,211 @@
+import { PageSetup } from './paperStack/pageSetup';
+import { Editor, OutlineItem, TrackChangesState } from './editor';
+import { SobreeDocument } from './doc/types';
+export type SobreeMode = "edit" | "read";
+export type SobreeEvent = "change" | "paginate" | "setup" | "mode-change" | "track-changes-change" | "docx:import" | "docx:export";
+export interface SobreeEventPayload {
+    change: {
+        doc: SobreeDocument;
+        /** @deprecated Use `doc`. Alias kept for backwards compatibility. */
+        document: SobreeDocument;
+        revision: number;
+    };
+    paginate: {
+        pageCount: number;
+    };
+    setup: {
+        setup: PageSetup;
+    };
+    "mode-change": {
+        mode: SobreeMode;
+    };
+    /**
+     * Fires when track-changes mode flips on/off or the author changes.
+     * Re-emitted from the underlying editor — `Sobree.setTrackChanges`
+     * delegates to `editor.setTrackChanges`, so listeners on either
+     * surface see the same events.
+     */
+    "track-changes-change": TrackChangesState;
+    "docx:import": {
+        warnings: string[];
+    };
+    "docx:export": {
+        warnings: string[];
+    };
+}
+export type SobreeUnsubscribe = () => void;
+export interface SobreeOptions {
+    /** Initial document AST. */
+    initialDocument?: SobreeDocument;
+    /** Page setup. Falls back to `DEFAULT_PAGE_SETUP`. */
+    pageSetup?: PageSetup;
+    /** Forwarded to the underlying Editor. */
+    changeDebounceMs?: number;
+    /**
+     * Y.Doc backing the document. Forwarded to the Editor — see
+     * `EditorOptions.ydoc` for the contract. Use this when you want to
+     * attach a provider (`y-websocket`, `y-indexeddb`, `y-webrtc`) for
+     * persistence or collaboration. If absent, the editor creates one
+     * internally (still observable via `sobree.editor.ydoc`).
+     */
+    ydoc?: import('yjs').Doc;
+    /**
+     * Optional content-hashed `BlobStore` for binary parts. Forwarded
+     * to the Editor — see `EditorOptions.blobStore`.
+     */
+    blobStore?: import('./blob').BlobStore;
+    /**
+     * Initial track-changes mode. Forwarded to the editor — see
+     * `TrackChangesState`. When omitted, the editor starts in
+     * direct-edit mode and embedders flip it later with
+     * `sobree.setTrackChanges(...)`.
+     */
+    trackChanges?: TrackChangesState;
+}
+/**
+ * Top-level embeddable product surface. Composes a framework-free `Editor`
+ * with a paginated `PaperStack`, exposing a single wire-ready API for
+ * hosting webapps, headless Y peers (HeadlessSobree), and agents.
+ *
+ * Everything on this class is JSON-clean: plain data in, plain data out.
+ * No DOM nodes, Ranges, or function handles cross the public surface.
+ */
+export declare class Sobree {
+    readonly editor: Editor;
+    private readonly stack;
+    private setup;
+    private mode;
+    private readonly listeners;
+    private readonly detachPaginate;
+    private readonly detachChange;
+    private readonly detachTrackChanges;
+    /** Detachers for default + user-provided plugins, run in reverse on
+     *  `destroy` so attach order is mirrored on teardown. */
+    private readonly pluginDetachers;
+    constructor(container: HTMLElement, options?: SobreeOptions);
+    /** Internal stack element — useful for attaching context tools / viewport. */
+    get stackRoot(): HTMLElement;
+    /** First paper element — useful as a viewport fit target on first layout. */
+    get firstPaper(): HTMLElement;
+    /**
+     * First paper's outer ROW (paper card + per-page comments sidebar).
+     * Use as `fitWidthTarget` so the viewport's fit-to-width scales to
+     * include the sidebar — fitting just `.paper` would leave the
+     * sidebar clipped by the viewport's overflow.
+     */
+    get firstPaperRow(): HTMLElement;
+    /** Pass through for Viewport's renderTier callback. */
+    setRenderTier(tier: number): void;
+    /** Current page setup for section 0 (JSON-clean). */
+    getPageSetup(): PageSetup;
+    /** Number of sections in the current document. Always >= 1. */
+    getSectionCount(): number;
+    /**
+     * Read section `index` projected onto the demo's `PageSetup` shape so
+     * the same Page Setup modal can edit any section. Section 0 returns
+     * the live `setup`; other sections are projected from the AST.
+     *
+     * Lossy for properties the bridge doesn't carry (e.g. per-section
+     * pages-per-column will surface here as default), but enough for the
+     * fields the modal exposes today.
+     */
+    getSectionSetup(index: number): PageSetup;
+    /**
+     * Write back to section `index`. Section 0 funnels through
+     * `setPageSetup` (the canonical path); section 1+ goes through the
+     * editor's `setDocument` so it round-trips and triggers the change
+     * pipeline (repagination, listeners).
+     */
+    setSectionSetup(index: number, partial: Partial<PageSetup>): void;
+    /**
+     * Merge `partial` into the current page setup. Triggers repagination and
+     * fires `setup` event. Plain-data argument — safe over the wire.
+     */
+    setPageSetup(partial: Partial<PageSetup>): void;
+    /** Project the current `setup` into `doc.sections[0]` and commit. */
+    private writeSetupToSection0;
+    /** Current rendered page count. */
+    getPageCount(): number;
+    /**
+     * Force a repagination. Normally unnecessary — repagination runs after
+     * every `change` event. Useful for hosts that need to ensure pagination
+     * after initial mount (layout must be applied first — call from a
+     * `requestAnimationFrame` after the container is in the DOM).
+     */
+    repaginate(): void;
+    /** Delegate to `editor.getOutline()`. */
+    getOutline(): OutlineItem[];
+    /** Current mode. Default is `"edit"`. */
+    getMode(): SobreeMode;
+    /**
+     * Switch between edit and read mode. Read mode turns off
+     * `contenteditable`, tags the stack root with `is-read-mode` (so the
+     * embedder / block tools can hide indicators and toolbars via CSS or
+     * by listening to `mode-change`), and fires the `mode-change` event.
+     *
+     * Selection remains functional for copy / outline / accessibility;
+     * only editing is suspended.
+     */
+    setMode(mode: SobreeMode): void;
+    /**
+     * Current track-changes state. See `TrackChangesState`.
+     *
+     * Thin proxy to `editor.getTrackChanges()` — exposed on the façade
+     * so embedders driving the UI don't need to reach `sobree.editor`.
+     */
+    getTrackChanges(): TrackChangesState;
+    /**
+     * Switch authoring mode. Delegates to `editor.setTrackChanges`,
+     * which fires `track-changes-change`. Listeners attached to either
+     * `editor.on("track-changes-change", …)` or
+     * `sobree.on("track-changes-change", …)` receive the new state.
+     *
+     * The mode survives until flipped — it's not bound to selection or
+     * document. To run a one-off tracked edit, save the previous state,
+     * flip on, mutate, flip back.
+     */
+    setTrackChanges(state: TrackChangesState): void;
+    /**
+     * Read a .docx file and load it into the editor. Fully native: the
+     * parsed `SobreeDocument` is handed straight to the editor — no djot
+     * intermediate.
+     */
+    openDocx(src: File | Blob | ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Export the current document as a .docx Blob. Reads the editor's AST
+     * directly, overlays the current page setup's section/header/footer,
+     * and serialises to OOXML.
+     */
+    exportDocx(): Blob;
+    on<E extends SobreeEvent>(event: E, cb: (payload: SobreeEventPayload[E]) => void): SobreeUnsubscribe;
+    /**
+     * Compose the sections array the paper stack needs:
+     *
+     *   sections[0] is built from the live `setup` (the demo's UI model
+     *   represents section 0; setPageSetup updates flow through here).
+     *   sections[1..] come straight from the document AST — there's no UI
+     *   for editing them yet, so they're effectively read-only until a
+     *   future Page Setup section selector lands.
+     *
+     * Called whenever either source could have changed: constructor,
+     * `change` event, `setPageSetup`.
+     */
+    private syncStackSections;
+    /**
+     * Re-derive `setup` from `doc.sections[0]` when they diverge.
+     *
+     * Why: every page-setup edit goes setup → AST via
+     * `writeSetupToSection0`. But the inverse — AST → setup — only ran
+     * at construction time. That left the renderer's `setup` stuck on
+     * the post-edit state when the AST got reverted by undo / redo /
+     * external Y-provider edits, so `Cmd+Z` for a margin change reverted
+     * the AST silently while the paper kept the new margins.
+     *
+     * The `sameSetup` early-out is load-bearing — without it, the
+     * `change` event fired by `editor.setDocument` inside
+     * `writeSetupToSection0` would loop back into here, see the same
+     * setup, and waste a re-paginate.
+     */
+    private syncSetupFromDocument;
+    destroy(): void;
+}

package/dist/tokens.css

@@ -0,0 +1,144 @@
+/* Carlito — Google's open-source, metric-compatible clone of Calibri.
+ * MUST be the first rule in this file: CSS `@import` only fires when
+ * it precedes every other declaration. Most Sobree-rendered docs are
+ * authored in Word with Calibri as the body font; without Calibri or
+ * Carlito on the host, browsers fall back to Helvetica/Arial whose
+ * ellipsis (…) glyph is roughly 2× wider than Calibri's. A 60-char
+ * dot-leader bullet ("……………") that fits one line in Word then
+ * overflows or wraps in Sobree.
+ *
+ * We pull Carlito from Google Fonts so any embedder that imports
+ * `@sobree/core/tokens.css` gets Word-fidelity ellipsis (and accurate
+ * line metrics) without bundling the ~200 KB font in the package
+ * itself. Google Fonts serves subset WOFF2 files (~50 KB per weight)
+ * with permissive caching. `font-display: swap` means text reads
+ * immediately while Carlito loads — no flash of invisible text.
+ *
+ * If the host is offline / the CDN is blocked, the cascade falls
+ * through to Helvetica → Arial (wider ellipsis but still readable).
+ * For deployments that need fully-bundled fonts, override this @import
+ * with a local woff2 in the embedder's own CSS.
+ */
+@import url("https://fonts.googleapis.com/css2?family=Carlito:ital,wght@0,400;0,700;1,400;1,700&display=swap");
+
+/* @sobree/core — design tokens (the single source of truth for the brand).
+ *
+ * Consume from CSS:
+ *
+ *   @import "@sobree/core/tokens.css";
+ *
+ * Or from JS / TS:
+ *
+ *   import "@sobree/core/tokens.css";
+ *
+ * Add new tokens here, not in component CSS — keeps the brand coherent
+ * and makes theming a single edit.
+ */
+
+:root {
+  /* Primary — Sobree Amber. */
+  --sobree-50:  #fdf6ee;
+  --sobree-100: #f9e6d0;
+  --sobree-500: #c96f22;
+  --sobree-600: #b2591a;
+
+  /* Neutrals — warm ink, not gray. */
+  --ink-0:   #ffffff;
+  --ink-25:  #fbfaf7;
+  --ink-50:  #f6f4ef;
+  --ink-100: #eceae3;
+  --ink-200: #dedbd0;
+  --ink-300: #c4bfaf;
+  --ink-400: #a29c88;
+  --ink-500: #7c7764;
+  --ink-600: #5a5649;
+  --ink-700: #3d3a31;
+  --ink-800: #26241f;
+  --ink-900: #14130f;
+
+  /* Semantic tokens — what components reference. */
+  --bg:            var(--ink-25);
+  --bg-elevated:   var(--ink-0);
+  --bg-subtle:     var(--ink-50);
+  --bg-hover:      var(--ink-100);
+  --fg:            var(--ink-800);
+  --fg-strong:     var(--ink-900);
+  --fg-muted:      var(--ink-600);
+  --fg-subtle:     var(--ink-500);
+  --fg-on-primary: var(--ink-0);
+  --border:        var(--ink-200);
+  --border-strong: var(--ink-300);
+  --primary:       var(--sobree-500);
+  --primary-hover: var(--sobree-600);
+  --primary-soft:  var(--sobree-50);
+
+  /* Radii. */
+  --radius-xs: 2px;
+  --radius-sm: 2px;
+  --radius-md: 4px;
+  --radius-lg: 6px;
+
+  /* Shadows — warm-ink tinted, never gray. */
+  --shadow-xs: 0 1px 0 rgba(20, 19, 15, 0.04);
+  --shadow-sm: 0 1px 2px rgba(20, 19, 15, 0.06), 0 1px 1px rgba(20, 19, 15, 0.04);
+  --shadow-md: 0 4px 8px -2px rgba(20, 19, 15, 0.08), 0 2px 4px -2px rgba(20, 19, 15, 0.05);
+  --shadow-lg: 0 12px 24px -8px rgba(20, 19, 15, 0.12), 0 4px 8px -4px rgba(20, 19, 15, 0.06);
+
+  /* Focus ring — amber glow. */
+  --ring-focus: 0 0 0 3px rgba(201, 111, 34, 0.25);
+
+  /* Motion. */
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --dur-fast:   120ms;
+  --dur-base:   180ms;
+  --dur-slow:   280ms;
+
+  /* Spacing — 4px base. */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+
+  /* Back-compat aliases for older component CSS. */
+  --sobree-primary: var(--sobree-500);
+  --sobree-primary-soft: var(--primary-soft);
+  --sobree-border: var(--border);
+
+  /* === Tracked changes & comments ===
+   *
+   * The renderer emits semantic `<ins>` / `<del>` / comment markup in
+   * core (visibility is document fidelity, not an opt-in feature).
+   * These tokens make the *styling* themeable — override them in a
+   * consumer stylesheet instead of fighting component CSS specificity.
+   */
+
+  /* Per-author palette — 8 slots. `colorForAuthor()` hashes an author
+   * name to a slot index; the renderer references the matching token.
+   * Chosen for similar luminance (no author looks "louder") and to
+   * avoid pure red (clashes with deletion strikethrough) / pure yellow
+   * (clashes with the comment-range highlight). */
+  --sobree-author-0: #1f77b4; /* muted blue   */
+  --sobree-author-1: #2ca02c; /* green        */
+  --sobree-author-2: #9467bd; /* purple       */
+  --sobree-author-3: #8c564b; /* brown        */
+  --sobree-author-4: #e377c2; /* pink         */
+  --sobree-author-5: #17becf; /* teal         */
+  --sobree-author-6: #bcbd22; /* olive        */
+  --sobree-author-7: #ff7f0e; /* orange       */
+
+  /* Revision (tracked-change) styling. The author colour drives the
+   * text + decoration; `--sobree-revision-tint` is the background
+   * mix-strength applied via `color-mix`. */
+  --sobree-revision-ins-fallback: #0a7d2a; /* used when no author colour */
+  --sobree-revision-del-fallback: #b3261e;
+  --sobree-revision-tint: 8%;
+
+  /* Comment styling. */
+  --sobree-comment-range-bg:     rgba(255, 217, 0, 0.25);
+  --sobree-comment-range-border: rgba(180, 130, 0, 0.5);
+  --sobree-comment-accent:       #f59e0b; /* card rule when author colour absent */
+  --sobree-comment-resolved:     #16a34a; /* resolved-thread green */
+}
+

package/dist/util/selection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Save and restore the current document selection as a pair of (node, offset)
+ * pairs. Works across block re-parenting because text nodes are referenced
+ * directly — only breaks when the saved node is actually removed from the DOM.
+ */
+export interface SavedSelection {
+    startContainer: Node;
+    startOffset: number;
+    endContainer: Node;
+    endOffset: number;
+}
+export declare function saveSelection(): SavedSelection | null;
+export declare function restoreSelection(saved: SavedSelection | null): void;

package/dist/ydoc/apply.d.ts

@@ -0,0 +1,68 @@
+import { SobreeDocument } from '../doc/types';
+import * as Y from "yjs";
+/**
+ * Apply a new SobreeDocument to a Y.Doc, diffing against the current
+ * Y state by **block id**. The caller supplies the new id-per-block
+ * array (typically derived from the BlockRegistry — see
+ * `Editor.applyDocument`).
+ *
+ * # Granularity
+ *
+ *   - **Body blocks:** matched by id; updated in-place / inserted /
+ *     removed. Concurrent edits to *different* blocks always merge
+ *     cleanly via the Y.Array CRDT.
+ *
+ *   - **Paragraph block content:** the Y.Text is updated via
+ *     `diffApplyText` — minimal `insert` / `delete` / `format`
+ *     mutations matching what changed. Concurrent edits to *different
+ *     positions* in the same paragraph merge cleanly. Concurrent
+ *     edits to the *same* position still resolve via Yjs's standard
+ *     ordering (later op wins per Yjs's deterministic conflict rules).
+ *
+ *   - **Paragraph properties (alignment, indent, …):** stored as a
+ *     JSON blob on the Y.Map's `props` field. Concurrent property
+ *     edits clobber. Phase 1c may split into per-key Y.Map.
+ *
+ *   - **Non-paragraph blocks (section_break, table):** stored as
+ *     JSON-encoded `_ast`. Concurrent edits clobber.
+ *
+ *   - **Document meta (sections, styles, numbering, fonts,
+ *     headerFooterBodies):** JSON-encoded on a `meta` Y.Map.
+ *     Clobber on concurrent edits — these change rarely.
+ *
+ *   - **Binary parts (images, fonts):** stored as a Y.Map<Uint8Array>
+ *     with adds / removes detected by key. Phase 3 moves these to a
+ *     content-hashed blob store (out-of-band).
+ *
+ * The whole apply is wrapped in a single `Y.Doc.transact` with the
+ * supplied origin so subscribers (UndoManager, change listeners) see
+ * one batch.
+ */
+export interface ApplyDocumentOptions {
+    /**
+     * Part paths to **exclude** from the inline `parts` diff. Used when
+     * a `BlobStore` is configured — paths already managed via `partRefs`
+     * (or in-flight migration to it) must not also be written inline,
+     * or the Y.Doc would carry duplicate bytes.
+     *
+     * Empty / absent: today's path — every `rawParts` entry mirrors
+     * inline (no BlobStore).
+     */
+    skipPartPaths?: ReadonlySet<string>;
+}
+export declare function applyDocumentToYDoc(ydoc: Y.Doc, newDoc: SobreeDocument, newIds: readonly string[], origin?: unknown, opts?: ApplyDocumentOptions): void;
+/**
+ * Atomically write `partRefs` entries to a Y.Doc's `partRefs` Y.Map.
+ * Used by the Editor / HeadlessSobree when a `BlobStore` is configured —
+ * the editor hashes new bytes, uploads via the store, then calls this
+ * to publish the hash so other peers can fetch it.
+ *
+ * Wraps in `Y.Doc.transact` with the supplied origin so subscribers
+ * (UndoManager, observers) see one batch.
+ */
+export declare function applyPartRefsToYDoc(ydoc: Y.Doc, partRefs: Record<string, string>, origin?: unknown): void;
+/**
+ * Remove `partRefs` entries from a Y.Doc. Used when an embedder
+ * prunes unreferenced parts.
+ */
+export declare function removePartRefsFromYDoc(ydoc: Y.Doc, paths: readonly string[], origin?: unknown): void;

package/dist/ydoc/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Y.Doc backing for Sobree.
+ *
+ * The document is a Y.Doc; `SobreeDocument` is a *projection* computed
+ * by `projectYDoc` and cached by the Editor. All mutations go through
+ * `applyDocumentToYDoc` which diffs against the current Y state by
+ * block id and (for paragraphs) by Y.Text content.
+ *
+ * See `./schema.ts` for the Y.Doc layout, `./runs.ts` for the
+ * Run↔Delta mapping, and `./textDiff.ts` for the smart Y.Text diff
+ * that preserves CRDT semantics across applies.
+ */
+export { Y_BLOCK_AST_KEY, Y_BLOCK_ID_KEY, Y_BLOCK_KIND_KEY, Y_BLOCK_PROPS_KEY, Y_BLOCK_TEXT_KEY, Y_BODY_KEY, Y_META_FIELDS, Y_META_KEY, Y_PARTREFS_KEY, Y_PARTS_KEY, } from './schema';
+export { seedYDoc, buildBlockYMap, buildSkeletonBlockYMap, populateBlockContent, populateParagraphContent, populateParagraphYMap, } from './seed';
+export { projectYDoc, projectBlock } from './project';
+export { applyDocumentToYDoc, applyPartRefsToYDoc, removePartRefsFromYDoc, } from './apply';
+export { type DeltaOp, type EmbedContent, type LinkMark, attrsToRunProps, deepEqual, deltaToRuns, runPropsToAttrs, runsToDelta, } from './runs';
+export { diffApplyText } from './textDiff';

package/dist/ydoc/project.d.ts

@@ -0,0 +1,41 @@
+import { Block, SobreeDocument } from '../doc/types';
+import type * as Y from "yjs";
+/**
+ * Read the SobreeDocument projection out of a Y.Doc.
+ *
+ * Returns:
+ *
+ *   - **`doc`** — the projected SobreeDocument. Its `rawParts` is
+ *     populated from the Y.Doc's inline `parts` Y.Map only.
+ *   - **`ids`** — block-id order matching `doc.body`. The Editor
+ *     uses this to keep its BlockRegistry in sync.
+ *   - **`partRefs`** — partPath → hash mappings from the Y.Doc's
+ *     `partRefs` Y.Map (Phase 3.2+). Empty `{}` when no BlobStore-
+ *     using peer has touched the doc. **The caller (Editor /
+ *     HeadlessSobree) is responsible for resolving these through a
+ *     `BlobCache`** and merging the results into `doc.rawParts`.
+ *     We keep the resolution decoupled so projection has no async
+ *     work or external dependency.
+ *
+ * Two block shapes are supported:
+ *
+ *   - Phase 1b.5+: paragraphs as `{ kind: "paragraph", text: Y.Text, props }`.
+ *   - Phase 1a:    everything else as `{ _ast: JSON }`.
+ *
+ * Backwards compat: a Phase 1a-shaped paragraph (only `_ast`, no `kind`
+ * field) projects identically — the JSON is parsed straight to
+ * `Paragraph`.
+ *
+ * This is allocation-heavy; the Editor caches the result and invalidates
+ * on Y.Doc updates.
+ */
+export declare function projectYDoc(ydoc: Y.Doc): {
+    doc: SobreeDocument;
+    ids: string[];
+    partRefs: Record<string, string>;
+};
+/**
+ * Read a single block Y.Map into a Block. Returns `null` if the map
+ * is empty / unrecognizable (defensive — projectYDoc skips nulls).
+ */
+export declare function projectBlock(map: Y.Map<unknown>): Block | null;

package/dist/ydoc/runs.d.ts

@@ -0,0 +1,51 @@
+import { BreakRun, DrawingRun, InlineRun, RunProperties } from '../doc/types';
+export interface DeltaOp {
+    /** Text content (string) or embed (object literal). Y.Text differentiates by typeof. */
+    insert: string | EmbedContent;
+    /** Per-op marks — bold, italic, color, link, etc. Undefined when
+     *  no marks apply (Yjs preference: omit rather than set empty). */
+    attributes?: Record<string, unknown>;
+}
+/** All non-text run kinds become embed objects in the delta. */
+export type EmbedContent = {
+    __sobree: "break";
+    type: BreakRun["type"];
+} | {
+    __sobree: "tab";
+} | {
+    __sobree: "field";
+    instruction: string;
+    cached?: string;
+} | {
+    __sobree: "drawing";
+    partPath: string;
+    widthEmu: number;
+    heightEmu: number;
+    placement: DrawingRun["placement"];
+    altText?: string;
+};
+/** The `link` mark — stamped on every char inside a HyperlinkRun. */
+export interface LinkMark {
+    href: string;
+}
+export declare function runsToDelta(runs: readonly InlineRun[]): DeltaOp[];
+export declare function deltaToRuns(delta: readonly DeltaOp[]): InlineRun[];
+/**
+ * Convert RunProperties to a flat attributes object. Empty / undefined
+ * fields are omitted entirely (Yjs convention). Returns `undefined`
+ * when no marks apply.
+ */
+export declare function runPropsToAttrs(props: RunProperties | undefined): Record<string, unknown> | undefined;
+/**
+ * Inverse of `runPropsToAttrs`. Strips the `link` key (it's handled
+ * separately as a hyperlink wrapper). Strips any unknown attributes
+ * defensively (forward-compat: a future plugin may add marks Sobree
+ * doesn't model).
+ */
+export declare function attrsToRunProps(attrs: Record<string, unknown> | undefined): RunProperties;
+/**
+ * Deep equality for delta op contents — strings compared as `===`,
+ * embeds and attribute objects compared structurally. Used by the
+ * Y.Text diff to detect cells that haven't changed.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/ydoc/schema.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Y.Doc shape used by Sobree.
+ *
+ * The document is stored as a Y.Doc — that's the source of truth.
+ * `SobreeDocument` is a *projection* of this Y.Doc, computed by the
+ * helpers in `./project.ts` and cached by the Editor.
+ *
+ * # Top-level layout
+ *
+ * ```
+ * ydoc
+ * ├── getArray("body")  : Y.Array<Y.Map>     — block list, one Y.Map per block
+ * ├── getMap("meta")    : Y.Map              — sections, styles, numbering,
+ * │                                            headerFooterBodies, fonts.
+ * │                                            Stored as JSON-encoded values
+ * │                                            (rarely edited concurrently).
+ * │                                            Phase 1c may split fields into
+ * │                                            per-key Y types.
+ * ├── getMap("parts")    : Y.Map<Uint8Array>  — inline binary parts
+ * │                                              (legacy / no-BlobStore path).
+ * └── getMap("partRefs") : Y.Map<string>       — partPath → SHA-256 hex hash
+ *                                              (Phase 3.2+ / BlobStore path).
+ *                                              Bytes live in a side-channel
+ *                                              `BlobStore`; the editor's
+ *                                              `BlobCache` resolves hashes.
+ * ```
+ *
+ * Both `parts` and `partRefs` coexist — projection unions them so a
+ * Y.Doc with inline legacy bytes alongside hash-addressed refs reads
+ * correctly. The editor writes to whichever path matches its config
+ * (BlobStore → partRefs, otherwise parts).
+ *
+ * # Block Y.Map shape — paragraphs (Phase 1b.5+)
+ *
+ * Paragraph blocks (kind === `"paragraph"`, including headings) are
+ * structured for char-level CRDT:
+ *
+ * ```
+ * paragraphMap
+ * ├── get("id")    : string         — stable block id (matches BlockRegistry)
+ * ├── get("kind")  : "paragraph"    — discriminator
+ * ├── get("text")  : Y.Text         — runs flatten into here, marks for marks,
+ * │                                    embeds for breaks/tabs/fields/drawings,
+ * │                                    `link: { href }` mark for hyperlink chars
+ * └── get("props") : string (JSON)  — ParagraphProperties (alignment, indent,
+ *                                     numbering, …). JSON-encoded for v0.1;
+ *                                     concurrent property edits clobber.
+ * ```
+ *
+ * # Block Y.Map shape — non-paragraphs
+ *
+ * Section breaks and tables stay JSON-encoded — neither has inline
+ * text content with concurrent-edit demand. Tables get their own
+ * structural CRDT in a future Phase 1c (per-cell Y.Map<body Y.Array>).
+ *
+ * ```
+ * otherBlockMap
+ * ├── get("id")    : string             — stable block id
+ * └── get("_ast")  : string (JSON)      — JSON-encoded Block
+ * ```
+ *
+ * # Y.Text mark conventions
+ *
+ * The mapping between Sobree's `RunProperties` and Y.Text marks is
+ * 1:1 — `bold: true` becomes `{ bold: true }` on each char's
+ * attributes. Two special cases:
+ *
+ *   - `link: { href }` — chars inside a `HyperlinkRun` carry this mark.
+ *     The decoder reconstructs the HyperlinkRun by grouping consecutive
+ *     same-href chars.
+ *   - Embeds — non-text runs (break / tab / field / drawing) appear as
+ *     embed objects (`{ insert: { __sobree: "<kind>", … } }` in delta
+ *     form), occupying one position in the Y.Text.
+ *
+ * See `./runs.ts` for the conversion helpers and `./textDiff.ts` for
+ * the smart Y.Text diff that preserves CRDT semantics across applies.
+ */
+export declare const Y_BODY_KEY = "body";
+export declare const Y_META_KEY = "meta";
+/**
+ * Inline binary parts — `Y.Map<string, Uint8Array>` keyed by part
+ * path (e.g. `word/media/image1.png`). The legacy path: bytes ride
+ * along inside Y updates. Acceptable for small docs; expensive at
+ * scale (every peer replicates every byte).
+ *
+ * Used when no `BlobStore` is configured on the editor.
+ */
+export declare const Y_PARTS_KEY = "parts";
+/**
+ * Content-hashed part references — `Y.Map<string, string>` keyed by
+ * part path, valued by SHA-256 hex hash. The Phase 3.2+ path: bytes
+ * live in a side-channel `BlobStore`, the Y.Doc carries only small
+ * 64-char hashes. Y updates stay tiny regardless of image size.
+ *
+ * Used when a `BlobStore` is configured. The projection's `rawParts`
+ * resolves hashes against the editor's local `BlobCache` (which
+ * fetches from the store on miss).
+ *
+ * Both `parts` and `partRefs` coexist — a Y.Doc can carry inline
+ * legacy bytes alongside hash-addressed refs. Projection unions
+ * them; mixed-mode swarms work.
+ */
+export declare const Y_PARTREFS_KEY = "partRefs";
+export declare const Y_BLOCK_ID_KEY = "id";
+/** Discriminator: `"paragraph"` blocks have `text` + `props`; everything
+ *  else has `_ast`. Defaults to "_ast" path for forward-compat with
+ *  Phase 1a docs that didn't write a kind field. */
+export declare const Y_BLOCK_KIND_KEY = "kind";
+/** Phase 1b.5+: Y.Text on paragraph blocks. */
+export declare const Y_BLOCK_TEXT_KEY = "text";
+/** Phase 1b.5+: JSON-encoded ParagraphProperties on paragraph blocks. */
+export declare const Y_BLOCK_PROPS_KEY = "props";
+/** Phase 1a: JSON-encoded Block on non-paragraph blocks (and on
+ *  Phase 1a-shaped paragraph blocks for backwards compat). */
+export declare const Y_BLOCK_AST_KEY = "_ast";
+/** Keys stored on the `meta` Y.Map. */
+export declare const Y_META_FIELDS: {
+    readonly sections: "sections";
+    readonly headerFooterBodies: "headerFooterBodies";
+    readonly styles: "styles";
+    readonly numbering: "numbering";
+    readonly fonts: "fonts";
+};