@sobree/core 0.1.0

package/dist/embed/viewport.d.ts

@@ -0,0 +1,133 @@
+export interface ViewportOptions {
+    minScale?: number;
+    maxScale?: number;
+    /** Scale change per unit of wheel deltaY for shift+wheel. Default 0.005. */
+    wheelZoomSensitivity?: number;
+    /** Scale change per unit of wheel deltaY for pinch (ctrlKey). Default 0.02. */
+    pinchZoomSensitivity?: number;
+    onScaleChange?: (scale: number) => void;
+    /**
+     * Fires when the render tier changes — an integer ≥1 chosen from the
+     * current scale. The stage is laid out at that tier via CSS `zoom` so
+     * text rasterises at the zoomed size rather than being blitted from a
+     * 1× bitmap. Callers that care about layout (e.g. a paginator) should
+     * re-run their measurement + layout pass when the tier changes.
+     */
+    onRenderTierChange?: (tier: number) => void;
+    /**
+     * Fires whenever the stage transform changes — zoom, pan, programmatic
+     * fit, or animated pan. Used by overlays (block toolbar, indicator)
+     * that live in viewport coordinates and must follow the page through
+     * any transform. Called frequently during gestures, so the handler
+     * should be cheap (read-rect-and-write-style cheap).
+     */
+    onTransformChange?: () => void;
+}
+/**
+ * A framework-free zoomable / pannable viewport.
+ *
+ * Layout:
+ *   container (overflow:hidden, the element passed in)
+ *     └ stage   (absolutely positioned, transform: translate(tx,ty) scale(s))
+ *         └ slot (where the embedded content lives — caller mounts here)
+ *
+ * Gestures:
+ *   - Zoom: wheel with shiftKey OR ctrlKey (macOS pinch emits ctrlKey).
+ *           The point under the cursor stays under the cursor (zoom-to-cursor).
+ *   - Pan:  wheel without modifiers — two-finger trackpad scroll deltas move
+ *           the stage. Also supports click-drag with middle mouse or space.
+ */
+export declare class Viewport {
+    readonly container: HTMLElement;
+    readonly slot: HTMLElement;
+    private readonly stage;
+    private scale;
+    private tx;
+    private ty;
+    private readonly minScale;
+    private readonly maxScale;
+    private readonly wheelZoomSensitivity;
+    private readonly pinchZoomSensitivity;
+    private readonly onScaleChange;
+    private readonly onRenderTierChange;
+    private readonly onTransformChange;
+    private readonly onWheel;
+    /** Current layout-side zoom factor (integer ≥ 1). See ViewportOptions. */
+    private renderTier;
+    /** Suppresses `onTransformChange` during the constructor's initial
+     *  `applyTransform` so consumers can capture `viewport` in their
+     *  callback without TDZ traps. Flipped true at the end of the ctor. */
+    private constructed;
+    /** Timestamp of the last wheel event, used to delimit gestures. */
+    private gestureLastTime;
+    /** Dominant axis for the current gesture. Null until detected, cleared at gesture end. */
+    private gesturePrimaryAxis;
+    /**
+     * Signed cumulative dx within the current gesture. Drives lock release:
+     * wobble (±3-5px back-and-forth) cancels out; sustained one-way motion
+     * accumulates past the threshold quickly. Reset at gesture end.
+     */
+    private gestureSignedDx;
+    /**
+     * Sticky horizontal-lock flag. Engaged by `fitTo` so alignment survives
+     * gentle diagonal trackpad gestures; broken when the gesture's signed
+     * cumulative dx crosses `X_RELEASE_THRESHOLD` — the user clearly intends
+     * sustained horizontal motion.
+     */
+    private horizontalLock;
+    constructor(container: HTMLElement, options?: ViewportOptions);
+    /** Reset pan to origin and scale to 1. */
+    reset(): void;
+    getScale(): number;
+    /** Integer layout-side zoom currently applied via CSS `zoom` on the stage. */
+    getRenderTier(): number;
+    /**
+     * Fit `target` to the viewport.
+     *   - `"width"`: scale so the target fills the viewport horizontally. The
+     *     vertical centre of the current view is preserved (no jump to the top
+     *     of the target).
+     *   - `"contain"`: scale so the entire target is visible, centred in both
+     *     axes.
+     * With `animate = true`, the transition runs with a CSS ease curve.
+     */
+    fitTo(target: HTMLElement, mode: "width" | "contain", animate?: boolean): void;
+    /**
+     * Pan the stage by `(dx, dy)` CSS pixels. Optional `animate` runs the
+     * same cubic-ease transition fit-to-page uses; unflagged pans apply
+     * instantly.
+     */
+    panBy(dx: number, dy: number, opts?: {
+        animate?: boolean;
+    }): void;
+    /** Zoom to `nextScale`, anchoring the point at (clientX, clientY) in container space. */
+    zoomTo(nextScale: number, clientX: number, clientY: number): void;
+    destroy(): void;
+    private handleWheel;
+    /**
+     * Axis-lock for pan gestures:
+     *   - Within a gesture (events ≤ GESTURE_GAP_MS apart), a clear dominant
+     *     axis zeros the other axis so a nearly-vertical swipe doesn't also
+     *     drift the paper sideways.
+     *   - An explicit `horizontalLock` set by `fitTo` survives across gestures,
+     *     keeping fit-page / fit-width alignment stable.
+     *   - Both locks release when the gesture's signed cumulative dx crosses
+     *     `X_RELEASE_THRESHOLD`. Signed sum cancels wobble (back-and-forth
+     *     averages to zero) while sustained one-way motion accumulates fast.
+     */
+    private applyScrollAxisLock;
+    private applyTransform;
+    /**
+     * Apply the current transform with a CSS transition. Used only for
+     * programmatic fits — wheel pan/zoom must stay instant or feel sluggish.
+     *
+     * If the target scale falls into a different render tier, we DON'T flip
+     * `stage.style.zoom` mid-flight: that property can't transition, so the
+     * layout would snap instantly while the `transform` keeps easing — the
+     * visible "weird reset" before the animation. Instead, we keep the
+     * current tier through the transition, write the transform expressed in
+     * THAT tier's coordinate space (visually identical to the same transform
+     * in any other tier — tier is just a layout-quality choice), and snap to
+     * the target tier on `transitionend`.
+     */
+    private applyTransformAnimated;
+}

package/dist/fonts/embedAPI.d.ts

@@ -0,0 +1,33 @@
+import { SobreeDocument } from '../doc/types';
+export interface EmbedFontFaces {
+    regular?: Uint8Array;
+    bold?: Uint8Array;
+    italic?: Uint8Array;
+    boldItalic?: Uint8Array;
+}
+export interface EmbedFontOptions {
+    /** Embed even when OS/2 fsType marks the face as restricted. Default false. */
+    allowRestricted?: boolean;
+}
+export interface EmbedFontResult {
+    /** Next document — same reference as input when nothing was embedded. */
+    next: SobreeDocument;
+    /** Per-face refusal warnings (e.g. restricted licence). */
+    warnings: string[];
+}
+/**
+ * Returns the next document with the given font embedded, plus any
+ * warnings (e.g. a face refused for licence reasons). When no face
+ * could be embedded, `next` is `===` the input doc — caller can
+ * skip a setDocument round.
+ */
+export declare function embedFontIntoDoc(doc: SobreeDocument, name: string, faces: EmbedFontFaces, opts?: EmbedFontOptions): EmbedFontResult;
+/**
+ * Drop a font declaration by name. Returns the same doc reference if
+ * the name wasn't present (caller can skip a setDocument round).
+ *
+ * Font part bytes are NOT removed from `rawParts` — call
+ * `pruneOrphanParts(doc)` (or just rely on export-side filtering) to
+ * GC them.
+ */
+export declare function removeFontFromDoc(doc: SobreeDocument, name: string): SobreeDocument;

package/dist/fonts/emit.d.ts

@@ -0,0 +1,24 @@
+import { ExportContext } from '../docx/export/context';
+import { SobreeDocument } from '../doc/types';
+interface FontTableEmission {
+    /** Inner XML of `word/fontTable.xml`. */
+    fontTableXml: string;
+    /** Inner XML of `word/_rels/fontTable.xml.rels`. */
+    fontTableRelsXml: string;
+}
+/**
+ * Stage every font-related artifact into the export context: the
+ * fontTable XML + companion rels, the document-level relationship,
+ * the content-type override, and the `.odttf` extension flag. Caller
+ * (docx/export/index.ts) just calls this once and forgets — no
+ * font-aware code needs to live in the export entry point any more.
+ *
+ * No-op when `doc.fonts` is empty.
+ */
+export declare function mountFontTableArtifacts(doc: SobreeDocument, ctx: ExportContext): void;
+/**
+ * Render the font table and its companion .rels. Returns null if the
+ * document declares no fonts (caller skips emitting the parts).
+ */
+export declare function emitFontTable(doc: SobreeDocument): FontTableEmission | null;
+export {};

package/dist/fonts/fontFaceRegistry.d.ts

@@ -0,0 +1,20 @@
+import { FontDeclaration } from './types';
+export declare class FontFaceRegistry {
+    private readonly styleEl;
+    /** Mostly for cleanup — every blob URL we minted needs revoking. */
+    private blobUrls;
+    /** Last-applied snapshot — skip re-registration when nothing changed. */
+    private lastSerialised;
+    constructor();
+    /**
+     * Sync the registry to the current document's fonts. Idempotent —
+     * if the font list hasn't changed since the last call, no work
+     * happens (no blob revocation, no DOM churn).
+     *
+     * Bails out (no-op) when the runtime doesn't expose
+     * `URL.createObjectURL` — typically jsdom in tests, where the
+     * registry isn't observable anyway.
+     */
+    sync(fonts: readonly FontDeclaration[], rawParts: Record<string, Uint8Array>): void;
+    destroy(): void;
+}

package/dist/fonts/fsType.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Read the OS/2 table's `fsType` field from a TrueType / OpenType font.
+ * The field encodes the font foundry's embedding licence — applications
+ * that embed must check it. See OpenType spec, OS/2 table § "fsType":
+ *   https://learn.microsoft.com/en-us/typography/opentype/spec/os2#fst
+ *
+ * Bits (mask with 0x000F for the licence triplet — they're mutually
+ * exclusive in practice):
+ *   0x0000  Installable embedding allowed. ← happy path.
+ *   0x0002  Restricted licence — must NOT be embedded.
+ *   0x0004  Preview & Print — embed for view/print only, no editing.
+ *   0x0008  Editable — embed and allow modifications.
+ *   0x0100  No subsetting — must embed the full face.
+ *   0x0200  Bitmap embedding only.
+ *
+ * `readFsType` returns `null` on parse failure (corrupt header, missing
+ * OS/2 table, truncated input). Callers treat `null` as "unknown
+ * licence — don't embed unless explicitly forced."
+ */
+export type EmbedMode = "installable" | "preview" | "editable" | "restricted";
+export interface FsTypeReport {
+    allowed: boolean;
+    mode: EmbedMode;
+    noSubset: boolean;
+    bitmapOnly: boolean;
+    /** Raw fsType field, for callers that want the bits. */
+    raw: number;
+}
+/** Walk the table directory and return `OS/2.fsType`, or null on failure. */
+export declare function readFsType(font: Uint8Array): number | null;
+/**
+ * Interpret an `fsType` value into a structured embedding decision.
+ * Defensive on `null` input (corrupt font) — reports as restricted so
+ * callers fail closed.
+ */
+export declare function canEmbed(fsType: number | null): FsTypeReport;

package/dist/fonts/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@sobree/core/fonts` — internal module aggregating everything
+ * font-related: AST shape, OOXML import + export, ODTTF codec,
+ * licensing check, in-memory `@font-face` registration.
+ *
+ * Consumers import from this `index.ts`, never reach into individual
+ * files. The module is internal to `@sobree/core`; the public surface
+ * is re-exported through `packages/core/src/index.ts`.
+ */
+export type { FontDeclaration, FontEmbedRef } from './types';
+export { deobfuscate, generateFontKey, isUnobfuscated, obfuscate, } from './odttf';
+export { canEmbed, readFsType } from './fsType';
+export type { EmbedMode, FsTypeReport } from './fsType';
+export { mountFontTableFromZip, parseFontTable } from './parse';
+export { emitFontTable, mountFontTableArtifacts } from './emit';
+export { embedFontIntoDoc, removeFontFromDoc, } from './embedAPI';
+export type { EmbedFontFaces, EmbedFontOptions, EmbedFontResult, } from './embedAPI';
+export { fontLivenessPaths } from './liveness';
+export { FontFaceRegistry } from './fontFaceRegistry';

package/dist/fonts/liveness.d.ts

@@ -0,0 +1,2 @@
+import { SobreeDocument } from '../doc/types';
+export declare function fontLivenessPaths(doc: SobreeDocument): Set<string>;

package/dist/fonts/odttf.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ODTTF (Obfuscated TrueType Font) codec for OOXML font embedding.
+ *
+ * Per ECMA-376 Part 4 §2.8.1: Word obfuscates embedded font binaries
+ * by XORing the first 32 bytes with a 16-byte key derived from a GUID
+ * (the `w:fontKey` attribute on `<w:embedRegular/>` / etc.). The key
+ * is the GUID's 16 bytes in **reverse** order. The first 16 bytes of
+ * the font are XOR'd with the key, then the next 16 bytes are XOR'd
+ * with the same key. Bytes 32..end pass through unchanged.
+ *
+ * Symmetry — the operation is its own inverse (XOR is involutive), so
+ * `obfuscate(deobfuscate(x, k), k) === x`.
+ *
+ * A `fontKey` of all-zeros means "no obfuscation" and the bytes are
+ * already a raw TTF/OTF.
+ */
+/**
+ * XOR-deobfuscate or -obfuscate the first 32 bytes of `bytes` with the
+ * key derived from `fontKey`. Returns a fresh `Uint8Array` — the input
+ * is not mutated.
+ */
+export declare function deobfuscate(bytes: Uint8Array, fontKey: string): Uint8Array;
+/** Symmetric inverse — same operation as `deobfuscate`, named for clarity at call sites. */
+export declare function obfuscate(bytes: Uint8Array, fontKey: string): Uint8Array;
+/**
+ * Generate a fresh GUID in the canonical `{XX-...}` form Word uses for
+ * `w:fontKey`. Random bytes via `crypto.getRandomValues`; falls back to
+ * `Math.random()` if `crypto` isn't present (jsdom often is, Node 19+
+ * is too — fallback only matters for ancient runtimes).
+ */
+export declare function generateFontKey(): string;
+/** True when `fontKey` is the sentinel "no obfuscation" GUID. */
+export declare function isUnobfuscated(fontKey: string | undefined): boolean;

package/dist/fonts/parse.d.ts

@@ -0,0 +1,29 @@
+import { FontDeclaration } from './types';
+interface Loaded {
+    declarations: FontDeclaration[];
+    /** ZIP paths of embedded font parts that should be kept in rawParts. */
+    embeddedPartPaths: Set<string>;
+}
+/**
+ * Convenience for the import pipeline: pull `word/fontTable.xml` +
+ * `word/_rels/fontTable.xml.rels` out of the unzipped text-parts map
+ * and return the parsed declarations. Falls back to an empty array
+ * when the document carries no font table — most don't.
+ *
+ * `parseRels` is the same `parseRels` helper the document uses; passed
+ * in to avoid a cycle through `docx/import`.
+ */
+export declare function mountFontTableFromZip(textParts: Record<string, string>, parseRels: (xml: string) => Map<string, string>): FontDeclaration[];
+/**
+ * Returns parsed declarations + the set of font-part ZIP paths the
+ * unzipped binary map should retain. `fontTableRels` resolves `r:id`
+ * references inside `<w:embed*>` elements to their target paths.
+ */
+export declare function parseFontTable(fontTableXml: string, fontTableRels: Map<string, string>): Loaded;
+/**
+ * Convenience: parse direct-child `<w:font>` elements, in case some
+ * producers use children rather than descendants. Reserved for future
+ * "strict mode" callers.
+ */
+export declare function readChildFonts(parent: Element): Element[];
+export {};

package/dist/fonts/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Font-table type definitions, lifted out of `doc/types.ts` so the
+ * fonts module owns its own AST shapes. Re-exported from
+ * `doc/types.ts` for backwards compat — existing consumers keep
+ * working unchanged.
+ */
+/**
+ * One entry in the document's font table — mirrors `<w:font>` in
+ * OOXML. Most fields are substitution hints used when the named font
+ * isn't installed on the reader's machine; `embed` carries pointers
+ * to actual font bytes stored under `rawParts`.
+ */
+export interface FontDeclaration {
+    /** `<w:font w:name="...">` — the font family this entry describes. */
+    name: string;
+    altName?: string;
+    /** 10-byte PANOSE classification, hex-encoded. */
+    panose?: string;
+    /** Character set, hex (default "00"). */
+    charset?: string;
+    family?: "auto" | "decorative" | "modern" | "roman" | "script" | "swiss";
+    pitch?: "default" | "fixed" | "variable";
+    /** Unicode/codepage subset bitmasks — mirrors `<w:sig>`. */
+    sig?: {
+        usb0: string;
+        usb1: string;
+        usb2: string;
+        usb3: string;
+        csb0: string;
+        csb1: string;
+    };
+    notTrueType?: boolean;
+    /** Embedded faces. Optional — most declarations are just name + panose. */
+    embed?: {
+        regular?: FontEmbedRef;
+        bold?: FontEmbedRef;
+        italic?: FontEmbedRef;
+        boldItalic?: FontEmbedRef;
+    };
+}
+export interface FontEmbedRef {
+    /** ZIP path of the font bytes (key into `SobreeDocument.rawParts`). */
+    partPath: string;
+    /**
+     * GUID used for ODTTF XOR-obfuscation of the first 32 bytes. Absent
+     * means the part is a raw TTF/OTF (no obfuscation). When writing
+     * `.docx`, a fresh GUID is generated per embed.
+     */
+    fontKey?: string;
+    /** Round-trip flag — true if the on-disk file is already a subset. */
+    subsetted?: boolean;
+}

package/dist/headless.d.ts

@@ -0,0 +1,168 @@
+import { BlobCache, BlobStore } from './blob';
+import { BlockRef, EditError, EditResult, Selection } from './doc/api';
+import { ParagraphPropertiesPatch, BlockInfo, CommandBus, OutlineItem } from './editor';
+import { Block, ParagraphAlignment, ParagraphProperties, SobreeDocument } from './doc/types';
+import { History } from './history';
+/**
+ * HeadlessSobree — a no-DOM Sobree peer for LLM agents, automation,
+ * back-end pipelines, MCP servers, anywhere code needs to read or
+ * write a Sobree document without rendering it.
+ *
+ * # The shape
+ *
+ * Same mental model as the browser editor: hold a `Y.Doc`, read it
+ * as a `SobreeDocument` projection, write through typed mutation
+ * methods, get a `change` event on every update (local or remote).
+ * The difference: no DOM, no rendering, no selection-from-DOM logic.
+ * Selection is just a value field you can read / write.
+ *
+ * # Use cases
+ *
+ *   1. **LLM agents.** Connect a Y-websocket provider to a Sobree
+ *      room; the LLM sees the same doc the user sees. It can read
+ *      structure (paragraphs, headings, runs) and apply edits that
+ *      propagate back through Y.
+ *
+ *   2. **Server-side rendering / export.** Run `editor.toDocx()` in
+ *      a Node worker against a snapshot loaded from `@sobree/collab-server`'s
+ *      persistence backend.
+ *
+ *   3. **Automation pipelines.** Cron job that processes inbound
+ *      content and writes formatted reports to a Sobree doc.
+ *
+ *   4. **Tests.** Build a fixture document programmatically without
+ *      a DOM environment.
+ *
+ * # What it's NOT
+ *
+ *   - A *relay*. That's `@sobree/collab-server` — a Node server that
+ *     fans out Y messages between many peers. HeadlessSobree is a
+ *     single peer with its own Y.Doc.
+ *   - A *full editor*. The browser `Editor` adds DOM rendering,
+ *     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.
+ *
+ * # Origin tagging
+ *
+ * Every mutation writes to the Y.Doc with a configurable origin
+ * (default `"headless"`). The local `Y.UndoManager` tracks only that
+ * origin — so the peer's `Cmd+Z`-equivalent (`peer.history.undo()`)
+ * reverses only its own edits, not the human peers'. Pick a stable
+ * per-peer origin string (e.g. `"agent:gpt-4-2024-05"`) if you want
+ * post-hoc telemetry to identify the author.
+ */
+import * as Y from "yjs";
+export interface HeadlessSobreeOptions {
+    /**
+     * Origin string used for this peer's Y.Doc mutations. Identifies
+     * the source in `afterTransaction` events and scopes the
+     * Y.UndoManager. Default `"headless"`.
+     */
+    origin?: string;
+    /**
+     * Initial document. Used only if the Y.Doc is empty at construction
+     * time — same semantics as `Editor.initialDocument`. If the Y.Doc
+     * is non-empty (a peer joining an active room), this is ignored
+     * and the existing state is adopted.
+     */
+    initialDocument?: SobreeDocument;
+    /**
+     * Override the BlockRegistry's id prefix. Default is
+     * `${ydoc.clientID.toString(36)}_` — same convention the browser
+     * `Editor` uses, so newly-minted block ids never collide across
+     * peers.
+     */
+    idPrefix?: string;
+    /**
+     * Optional content-hashed `BlobStore` (Phase 3.2+). Without one,
+     * binary parts ride inline in the Y.Doc; with one, the headless
+     * peer resolves `partRefs` hashes via a local `BlobCache` and
+     * fetches missing bytes from the store on demand. See
+     * `EditorOptions.blobStore` for the full contract.
+     */
+    blobStore?: BlobStore;
+}
+export type HeadlessEvent = "change";
+export interface HeadlessChangePayload {
+    doc: SobreeDocument;
+    /** Whether the change originated from THIS peer's mutations
+     *  (true) or arrived via a Y provider from a remote peer (false). */
+    local: boolean;
+}
+export type HeadlessUnsubscribe = () => void;
+/**
+ * Headless Sobree peer. Construct with a `Y.Doc` — typically one
+ * you've already attached a provider to. Reads project through the
+ * Y.Doc; writes mirror back inside `Y.Doc.transact` with the
+ * configured origin.
+ */
+export declare class HeadlessSobree {
+    readonly ydoc: Y.Doc;
+    readonly commands: CommandBus;
+    readonly history: History;
+    readonly origin: string;
+    /** Optional content-hashed blob layer. Mirrors the browser `Editor`'s
+     *  `blobStore` field — null when no store is configured. */
+    readonly blobStore: BlobStore | null;
+    /** Local cache for blob bytes. Null when no `blobStore` is set. */
+    readonly blobCache: BlobCache | null;
+    private doc;
+    private readonly registry;
+    private currentSelection;
+    private readonly listeners;
+    private lastPartRefs;
+    private ydocUpdateListener;
+    constructor(ydoc: Y.Doc, opts?: HeadlessSobreeOptions);
+    /** Current document — a fresh projection of the Y.Doc state. */
+    getDocument(): SobreeDocument;
+    /** Summary of every top-level block. */
+    getBlocks(): BlockInfo[];
+    getBlock(index: number): BlockInfo;
+    getBlockById(id: string): BlockInfo | null;
+    /** Heading outline — one entry per `paragraph` block whose
+     *  resolved style identifies it as a heading. */
+    getOutline(): OutlineItem[];
+    /** This peer's stored selection — same shape `editor.selection.get()`
+     *  returns. `null` when no selection is set. */
+    getSelection(): Selection;
+    /**
+     * Set this peer's selection. Stored as a value (no DOM update);
+     * the value is what `history` captures on each mutation and
+     * restores on undo.
+     */
+    setSelection(selection: Selection): void;
+    /** Replace the document. */
+    setDocument(doc: SobreeDocument): void;
+    /** Replace the block at `target`'s index with `block`. */
+    replaceBlock(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /** Insert `block` before the target block. */
+    insertBlockBefore(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /** Insert `block` after the target block. */
+    insertBlockAfter(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /** Delete the target block. */
+    deleteBlock(target: BlockRef): EditResult<void>;
+    /** Merge a patch into each target paragraph's properties. */
+    applyBlockProperties(targets: BlockRef[], patch: ParagraphPropertiesPatch): EditResult<void>;
+    on<E extends HeadlessEvent>(event: E, cb: (payload: HeadlessChangePayload) => void): HeadlessUnsubscribe;
+    destroy(): void;
+    private allBlockIds;
+    private mirror;
+    private adoptYDocState;
+    private resolveCachedPartRefsInto;
+    private onBlobResolved;
+    /**
+     * Wait for every currently-referenced binary part to be available
+     * in the local cache. No-op when no `blobStore` is configured.
+     */
+    ensurePartsLoaded(): Promise<void>;
+    private checkRefs;
+    private commit;
+    private fireChange;
+    private summariseBlock;
+}
+export type { Block, BlockInfo, BlockRef, EditError, EditResult, ParagraphAlignment, ParagraphProperties, Selection, SobreeDocument, };

package/dist/history/history.d.ts

@@ -0,0 +1,100 @@
+import { Selection, Selection as PublicSelection } from '../doc/api';
+import { HistoryConfig, HistoryDepth } from './types';
+/**
+ * Undo / redo for the Sobree editor — backed by `Y.UndoManager`.
+ *
+ * # Why Y.UndoManager
+ *
+ * Phase 1b.6 swaps the snapshot-stack History for `Y.UndoManager` so:
+ *
+ *   1. **Per-peer undo.** UndoManager tracks operations by *origin*.
+ *      When a peer types, those Y operations are tagged `"local"`. A
+ *      remote peer's edits arrive with a different origin (the
+ *      provider name), so the local UndoManager doesn't see them as
+ *      its own. `Cmd+Z` reverses only the local user's edits — exactly
+ *      what users expect in collab.
+ *
+ *   2. **CRDT-native.** Undoing produces *inverse Y operations*, which
+ *      flow through the same broadcast pipeline as forward edits. No
+ *      separate "undo over the wire" protocol needed.
+ *
+ *   3. **No snapshot stack.** Memory is bounded by Yjs's internal item
+ *      list; no separate snapshot bookkeeping.
+ *
+ * # API compatibility
+ *
+ * The public surface (`undo`, `redo`, `canUndo`, `canRedo`, `clear`,
+ * `depth`, `on`) matches the old History so the Editor's command-bus
+ * registrations and the keyboard plugin's `Cmd+Z` mapping work
+ * unchanged. The legacy `recordCommit` / `recordTyping` / `flush`
+ * methods are kept as no-ops — UndoManager auto-tracks ops by origin
+ * and `captureTimeout` handles coalescing without explicit "begin a
+ * typing session" calls.
+ *
+ * # Selection restore
+ *
+ * Each undo/redo step needs to restore the cursor to its pre-edit
+ * position. We capture the live selection in `stack-item-added`'s
+ * `meta` and restore it on `stack-item-popped`. The restore happens
+ * AFTER the editor has re-projected and re-rendered (the Y observer
+ * fires before the popped event — see `Editor.adoptYDocState`).
+ */
+import * as Y from "yjs";
+export type HistoryEvent = "change";
+export type HistoryListener = (depth: HistoryDepth) => void;
+export interface HistoryOptions extends Partial<HistoryConfig> {
+    /** Y.Doc to track. The UndoManager observes the body, meta, and
+     *  parts top-level types — every Sobree mutation funnels through
+     *  one of these, so any local edit produces a stack entry. */
+    ydoc: Y.Doc;
+    /** Origin string used by the Editor's `mirrorToYDoc()` and other
+     *  local writes. UndoManager only tracks operations whose origin
+     *  is in this set. Defaults to `"local"`. */
+    localOrigin?: unknown;
+    /** Capture the *current* live selection — called as a stack item
+     *  is being added so we can stash it for restore on undo. */
+    captureSelection: () => Selection;
+    /** Restore a previously-captured selection to the live DOM /
+     *  EditorSelection. Called on undo / redo after the Y.Doc has been
+     *  re-projected and re-rendered. */
+    restoreSelection: (sel: Selection) => void;
+}
+export declare class History {
+    private readonly mgr;
+    private readonly listeners;
+    private readonly captureSelection;
+    private readonly restoreSelection;
+    constructor(opts: HistoryOptions);
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    clear(): void;
+    depth(): HistoryDepth;
+    on(_event: HistoryEvent, cb: HistoryListener): () => void;
+    destroy(): void;
+    /** @deprecated UndoManager auto-tracks ops by origin; no need to
+     *  call this. Kept as a no-op so the Editor's existing call sites
+     *  don't break. */
+    recordCommit(): void;
+    /** @deprecated UndoManager's `captureTimeout` coalesces consecutive
+     *  ops into one stack item. No explicit recording needed. */
+    recordTyping(): void;
+    /** @deprecated UndoManager flushes implicitly on `captureTimeout`
+     *  expiry or on the next non-tracked operation. */
+    flush(): void;
+    private fire;
+}
+/** @deprecated Selection survives undo/redo via stable block ids now;
+ *  no snapshot-conversion is needed. Kept as a pass-through stub. */
+export declare function makeEntry(doc: unknown, selection: PublicSelection, reason: string, _indexOfBlock: (id: string) => number): {
+    doc: unknown;
+    selection: PublicSelection;
+    reason: string;
+    timestamp: number;
+};
+/** @deprecated Pass-through; selection structure is no longer
+ *  index-keyed in the new history. */
+export declare function selectionToSnapshot(selection: PublicSelection, _indexOfBlock: (id: string) => number): PublicSelection;
+/** @deprecated Pass-through; selection survives via stable ids. */
+export declare function snapshotToSelection(snap: PublicSelection, _refAt: (idx: number) => unknown): PublicSelection;

package/dist/history/index.d.ts

@@ -0,0 +1,4 @@
+export { History, makeEntry, selectionToSnapshot, snapshotToSelection, } from './history';
+export type { HistoryEvent, HistoryListener, HistoryOptions, } from './history';
+export type { HistoryConfig, HistoryDepth, HistoryEntry, SnapshotPosition, SnapshotSelection, } from './types';
+export { DEFAULT_HISTORY_CONFIG } from './types';