@sobree/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 sobree.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @sobree/core
+
+Embeddable, print-view-first WYSIWYG editor for `.docx`. Framework-free
+core, plugin architecture, native OOXML round-trip.
+
+→ Docs: **[docs.sobree.dev](https://docs.sobree.dev)**
+→ Live editor: **[sobree.dev/try](https://sobree.dev/try)**
+
+## Install
+
+`@sobree/core` is the **minimal editor kernel** — AST + paginator + DOCX
+I/O + history + fonts. It ships with **zero plugin packages**. Install
+the plugins you want and pass them to `createSobree()`.
+
+For an interactive editor with toolbar, keyboard shortcuts, and zoom dock:
+
+```sh
+pnpm add @sobree/core @sobree/keyboard @sobree/block-tools @sobree/zoom-controls
+```
+
+For a headless / API-driven peer (LLM agent, automation):
+
+```sh
+pnpm add @sobree/core yjs
+```
+
+Use `HeadlessSobree` — the no-DOM counterpart of the browser editor.
+For multi-user collab, add `@sobree/collab-providers` (client glue)
+and run `@sobree/collab-server` somewhere.
+
+## Hello world
+
+```ts
+import { createSobree } from "@sobree/core";
+import { keyboard } from "@sobree/keyboard";
+import { blockTools } from "@sobree/block-tools";
+import { zoomControls } from "@sobree/zoom-controls";
+import "@sobree/core/tokens.css";
+
+const editor = createSobree("#editor", {
+  content: "# Hello\n\nStart typing.",
+  plugins: [
+    keyboard(),       // Cmd+B / Cmd+Z / …
+    blockTools(),     // floating toolbar + gutter indicator
+    zoomControls(),   // bottom-right zoom dock
+  ],
+});
+
+editor.on("change", ({ doc }) => {
+  console.log("body has", doc.body.length, "blocks");
+});
+```
+
+`createSobree()` mounts the viewport, the paginated paper stack, runs each
+plugin's `setup()` against a shared context, and returns a single handle.
+Plugins are torn down in reverse-of-mount order on `editor.destroy()`.
+
+## What's in the box
+
+- **Native OOXML AST.** Every node maps 1:1 to a `<w:…>` element.
+- **Y.Doc backed.** Every editor is backed by a Yjs `Y.Doc`; mutations mirror in via `Y.Doc.transact`. Embedders attach `y-websocket` / `y-indexeddb` / `y-webrtc` providers for persistence + collaboration. `editor.ydoc` is the escape hatch.
+- **Pure paginator.** TeX-style break selection, widow / orphan, keep-with-next, multi-section. No DOM, no I/O.
+- **Per-peer undo / redo.** Thin wrapper around `Y.UndoManager` — each peer's `Cmd+Z` reverses only its own edits via tracked Y origins; remote edits flow through but stay off the local stack. Selection restored from `stackItem.meta`.
+- **OOXML font embedding.** `word/fontTable.xml` round-trip + ODTTF obfuscation + OS/2 fsType licence check + runtime `@font-face` registration. Note: `fsType` is an advisory gate — the embedder is responsible for ensuring they have rights to ship any font they pass to `editor.embedFont(...)`. Pass `{ allowRestricted: true }` only when you do.
+- **Minimal core, opt-in plugins.** Toolbar (`@sobree/block-tools`), keyboard (`@sobree/keyboard`), zoom dock (`@sobree/zoom-controls`) ship as siblings. For multi-user collab: `@sobree/collab-providers` (client) + `@sobree/collab-server` (Node relay). `@sobree/core` has no plugin dependencies — only `fflate` for ZIP and `yjs` for the CRDT.
+- **Y-protocol IS the wire.** No separate RPC plugin. Headless callers (LLMs, automation) participate via `HeadlessSobree` — same commands, same Y.Doc.
+- **Wire-ready surface.** `editor.commands.execute(name, args)` is the single dispatch path used by keyboard, toolbar, and external transports.
+- **JSON-clean projection.** `editor.getDocument()` returns a JSON-clean `SobreeDocument` snapshot of the underlying Y.Doc — survives `structuredClone` and any wire.
+
+## Polymorphic content
+
+```ts
+createSobree("#editor", { content: "# Markdown" });          // seed string
+createSobree("#editor", { content: docxBlob });              // .docx bytes
+createSobree("#editor", { content: astLiteral });            // built with the doc builders
+createSobree("#editor");                                      // empty
+```
+
+For the `.docx` path, `await editor.ready` resolves once the import lands.
+
+## Save back to `.docx`
+
+```ts
+const { blob } = editor.toDocx();
+```
+
+Or load a different file at runtime:
+
+```ts
+const { warnings } = await editor.loadDocx(file);
+```
+
+## Documentation
+
+- [Quick start](https://docs.sobree.dev/quick-start/)
+- [`createSobree()` API](https://docs.sobree.dev/api/create-sobree/)
+- [History (undo / redo)](https://docs.sobree.dev/api/history/)
+- [Fonts (embedding + fontTable)](https://docs.sobree.dev/api/fonts/)
+- [Architecture](https://docs.sobree.dev/concepts/architecture/)
+- [Document model](https://docs.sobree.dev/concepts/document/)
+- [Plugin model](https://docs.sobree.dev/concepts/plugins/)
+- [Building your own plugin](https://docs.sobree.dev/plugins/build-your-own/)
+
+## License
+
+MIT.

package/dist/__vite-browser-external-DYxpcVy9.js

@@ -0,0 +1,5 @@
+const e = {};
+export {
+  e as default
+};
+//# sourceMappingURL=__vite-browser-external-DYxpcVy9.js.map

package/dist/__vite-browser-external-DYxpcVy9.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__vite-browser-external-DYxpcVy9.js","sources":["../__vite-browser-external"],"sourcesContent":["export default {}"],"names":["__viteBrowserExternal"],"mappings":"AAAA,MAAAA,IAAe,CAAA;"}

package/dist/blob/cache.d.ts

@@ -0,0 +1,69 @@
+import { BlobHash, BlobStore } from './types';
+export interface BlobCacheOptions {
+    /** Underlying store. */
+    store: BlobStore;
+    /**
+     * Optional listener fired when a previously-missing hash arrives in
+     * the cache (background fetch landed). Editors use this to know
+     * when to re-render — a `<img>` whose bytes were pending now has
+     * something to show.
+     */
+    onResolved?: (hash: BlobHash) => void;
+    /**
+     * Optional listener fired when a fetch fails. The cache leaves the
+     * hash in "missing" state and lets a future `ensureLoaded` retry.
+     * Default: warn to console.
+     */
+    onError?: (hash: BlobHash, err: unknown) => void;
+}
+export declare class BlobCache {
+    private readonly store;
+    private readonly onResolved;
+    private readonly onError;
+    private readonly cache;
+    /** In-flight fetches, keyed by hash. Promise resolves to the bytes
+     *  (cached) or `null` (not found / error). */
+    private readonly inflight;
+    constructor(opts: BlobCacheOptions);
+    /**
+     * Synchronously read bytes for a hash. Returns `null` if not yet
+     * cached. Doesn't trigger a fetch — call `ensureLoaded` first if
+     * you need to wait.
+     */
+    get(hash: BlobHash): Uint8Array | null;
+    /** Whether the hash is currently in the cache. */
+    has(hash: BlobHash): boolean;
+    /**
+     * Insert bytes into the cache directly. Used when the embedder
+     * already has the bytes in hand (paste image, font embed, DOCX
+     * import) and wants the local renderer to find them immediately.
+     *
+     * Returns the bytes' hash. Caller is responsible for uploading
+     * to the BlobStore separately (typically `await store.put(bytes)`
+     * with the same input).
+     */
+    put(hash: BlobHash, bytes: Uint8Array): void;
+    /**
+     * Ensure the given hashes are in the cache. Returns a Promise that
+     * resolves once every hash is either in the cache or has failed to
+     * fetch (failures don't reject the Promise — they're reported via
+     * `onError` and skipped, consistent with the "best-effort
+     * availability" model).
+     *
+     * Already-cached hashes resolve immediately. Already-in-flight
+     * fetches are deduplicated (multiple concurrent callers wait on
+     * the same Promise).
+     */
+    ensureLoaded(hashes: readonly BlobHash[]): Promise<void>;
+    /**
+     * Number of cached blobs. Diagnostic / test helper; production
+     * code shouldn't depend on this for correctness.
+     */
+    size(): number;
+    /**
+     * Clear all cached blobs. Used by the Editor on `destroy` to free
+     * memory; future refinements may auto-evict.
+     */
+    clear(): void;
+    private fetchOne;
+}

package/dist/blob/fetch.d.ts

@@ -0,0 +1,18 @@
+import { BlobStore } from './types';
+export interface FetchBlobStoreOptions {
+    /** Base URL — bytes are addressed at `<baseUrl>/<hash>`. No trailing slash. */
+    baseUrl: string;
+    /**
+     * Optional headers factory. Called per request — embed auth tokens,
+     * trace IDs, custom content types, etc. Defaults to no extra headers.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Pass through to the underlying `fetch` (CORS mode, signal, etc.). */
+    fetchInit?: RequestInit;
+    /**
+     * Override the global `fetch`. Useful for testing or running inside
+     * a runtime with a custom fetch impl. Default: `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+}
+export declare function fetchBlobStore(opts: FetchBlobStoreOptions): BlobStore;

package/dist/blob/hash.d.ts

@@ -0,0 +1,13 @@
+import { BlobHash } from './types';
+/**
+ * Compute the SHA-256 hex digest of `bytes`. Lowercase hex, 64 chars.
+ *
+ * Always returns a Promise — the WebCrypto API is async, and we
+ * shape the Node path the same way for API consistency.
+ */
+export declare function sha256Hex(bytes: Uint8Array): Promise<BlobHash>;
+/**
+ * Validate that a string looks like a SHA-256 hex digest. Used as a
+ * defensive guard when bytes come from the wire.
+ */
+export declare function isBlobHash(s: string): boolean;

package/dist/blob/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @sobree/core blob module — content-hashed binary parts.
+ *
+ * Without configuring a `BlobStore`, Sobree behaves as it always has:
+ * binary parts (images, fonts) live inline in `SobreeDocument.rawParts`
+ * and inside the Y.Doc's `parts: Y.Map<Uint8Array>`.
+ *
+ * With a `BlobStore` configured on `createSobree({ blobStore })`,
+ * Sobree shifts to *content-hashed* mode: bytes go to the BlobStore
+ * (the side channel) and the Y.Doc stores only SHA-256 hashes
+ * (`partRefs: Y.Map<string, string>`). Y updates stay small — a
+ * 5 MB image paste no longer means 5 MB on every peer's Y.Doc.
+ *
+ * Two reference implementations ship out of the box:
+ *
+ *   - `inMemoryBlobStore()` — tests, local-only deployments
+ *   - `fetchBlobStore({ baseUrl, headers })` — HTTP backend
+ *
+ * For production at scale, write a custom `BlobStore` against S3 /
+ * R2 / Postgres / Redis. The interface is three methods.
+ *
+ * The `BlobCache` class bridges the async `BlobStore` and the
+ * synchronous editor renderer — pre-fetch with `ensureLoaded`, read
+ * synchronously after.
+ */
+export type { BlobHash, BlobStore } from './types';
+export { BlobStoreError } from './types';
+export { sha256Hex, isBlobHash } from './hash';
+export { inMemoryBlobStore } from './memory';
+export { fetchBlobStore } from './fetch';
+export type { FetchBlobStoreOptions } from './fetch';
+export { BlobCache } from './cache';
+export type { BlobCacheOptions } from './cache';

package/dist/blob/memory.d.ts

@@ -0,0 +1,2 @@
+import { BlobStore } from './types';
+export declare function inMemoryBlobStore(): BlobStore;

package/dist/blob/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * BlobStore — the side-channel where binary parts live when an
+ * embedder configures Sobree for content-hashed assets (Phase 3.2+).
+ *
+ * # The contract
+ *
+ * Tiny, intentionally minimal. Three operations: `put` (returns the
+ * content hash under which bytes are stored), `get` (fetches by
+ * hash), and optional `has` (cheap existence check). Every reasonable
+ * backend — in-memory, IndexedDB, HTTP, S3, R2, Cloudflare Workers,
+ * Postgres LO, Redis — implements this.
+ *
+ * # Why content addressing
+ *
+ * Two reasons:
+ *
+ *   1. **Deduplication.** A 5 MB logo pasted into 100 docs lives once
+ *      in the blob store, not 100 times. Hashes collide on identity,
+ *      so identical bytes produce identical keys.
+ *   2. **Tamper resistance.** A peer can verify any fetched blob by
+ *      re-hashing — no trust in the storage layer required for
+ *      integrity. (Confidentiality is a separate concern; encrypt at
+ *      the transport / storage layer if you need it.)
+ *
+ * # Hash algorithm
+ *
+ * Sobree uses SHA-256 hex (lowercase, no separators) for blob
+ * addressing. 64 chars per hash. Sized for the next decade or two of
+ * web content; not so long that hashes are awkward to log or shove
+ * into a URL path.
+ *
+ * # Concurrency
+ *
+ * Implementations should be safe for concurrent `put` of the same
+ * content (multiple callers, same bytes → same hash, idempotent).
+ * `get(hash)` must return the same bytes that were `put`.
+ */
+/** A SHA-256 hex digest. 64 lowercase hex chars. */
+export type BlobHash = string;
+export interface BlobStore {
+    /**
+     * Upload bytes and return their content hash. Idempotent — calling
+     * `put` with the same bytes returns the same hash and is a no-op
+     * after the first call.
+     */
+    put(bytes: Uint8Array): Promise<BlobHash>;
+    /**
+     * Fetch bytes by hash. Returns `null` when the blob isn't present
+     * (e.g. another peer wrote the partRef but the bytes haven't
+     * propagated yet). Implementations should NOT throw on "not
+     * found" — return null.
+     */
+    get(hash: BlobHash): Promise<Uint8Array | null>;
+    /**
+     * Optional cheap existence check — returns `true` if a blob with
+     * the given hash exists, without transferring its content. Used by
+     * `BlobCache` to decide whether to schedule a fetch. Falls back to
+     * `(await get(hash)) !== null` if not provided.
+     */
+    has?(hash: BlobHash): Promise<boolean>;
+    /**
+     * Optional removal. Most production deployments don't expose this
+     * over the wire (blob deletion needs care: ref counting, garbage
+     * collection, distributed coordination). Provided for tests and
+     * local-only deployments where the embedder owns lifecycle.
+     */
+    delete?(hash: BlobHash): Promise<void>;
+}
+/**
+ * BlobStoreError is thrown for low-level failures (transport,
+ * authorization, integrity check). "Not found" is *not* an error —
+ * `get` returns `null` for that case so callers can distinguish.
+ */
+export declare class BlobStoreError extends Error {
+    /** Originating exception, network response, etc. */
+    readonly cause?: unknown | undefined;
+    constructor(message: string, 
+    /** Originating exception, network response, etc. */
+    cause?: unknown | undefined);
+}

package/dist/createSobree.d.ts

@@ -0,0 +1,132 @@
+import { Sobree, SobreeEvent, SobreeEventPayload, SobreeUnsubscribe } from './sobree';
+import { Editor, CommandBus } from './editor';
+import { Viewport } from './embed/viewport';
+import { SobreePlugin } from './plugin';
+import { PageSetup } from './paperStack/pageSetup';
+import { SobreeDocument } from './doc/types';
+/**
+ * Initial content. Type detection is automatic:
+ *   - `string`            → seed-quality Markdown (see `parseMarkdown`)
+ *   - `Blob` / `File`     → `.docx` bytes (loaded asynchronously)
+ *   - `ArrayBuffer`       → `.docx` bytes
+ *   - `Uint8Array`        → `.docx` bytes
+ *   - `SobreeDocument`    → AST literal (use the builders to construct)
+ *
+ * For a `.docx` source, the constructor returns synchronously with an
+ * empty editor and `.ready` resolves once the import lands. For all
+ * other source types, `.ready` is already resolved when the factory
+ * returns.
+ */
+export type SobreeContent = string | Blob | ArrayBuffer | Uint8Array | SobreeDocument;
+/**
+ * How the viewport is fitted on initial mount.
+ *   - `"width"` (default) — first paper fills the host width; you see
+ *     the document the way you'd read it.
+ *   - `"page"` — first paper is fully contained (whole page visible).
+ *   - `"none"` — leave the viewport at 1:1, no auto-fit.
+ */
+export type FitOnMount = "width" | "page" | "none";
+export interface CreateSobreeOptions {
+    /** Initial content. See `SobreeContent`. Default: empty document. */
+    content?: SobreeContent;
+    /** Page setup. Falls back to A4 portrait with 1in margins. */
+    pageSetup?: PageSetup;
+    /**
+     * Plugins to mount. Each receives a `PluginContext` (editor +
+     * viewport + sobree + host) on `setup()` and returns a destroyer.
+     * Mounted in array order; destroyed in reverse on
+     * `editor.destroy()`. See `@sobree/keyboard`, `@sobree/block-tools`,
+     * `@sobree/zoom-controls` for stock factories. (`@sobree/collab-providers`
+     * lands in Phase 2 for Yjs persistence / collaboration.)
+     */
+    plugins?: SobreePlugin[];
+    /** Forwarded to the underlying Editor. */
+    changeDebounceMs?: number;
+    /**
+     * Y.Doc backing the document. The editor mirrors every mutation into
+     * this Y.Doc; embedders attach providers (`y-websocket`,
+     * `y-indexeddb`, `y-webrtc`, …) for persistence / collaboration.
+     * If absent, the editor creates one internally — still observable
+     * via `editor.editor.ydoc`.
+     */
+    ydoc?: import('yjs').Doc;
+    /**
+     * Optional content-hashed `BlobStore` for binary parts (Phase 3.2+).
+     * Without one, binary parts (images, fonts) ride inline in the
+     * Y.Doc; with one, they go through the BlobStore and the Y.Doc
+     * carries only hashes. See `EditorOptions.blobStore` for the full
+     * contract.
+     */
+    blobStore?: import('./blob').BlobStore;
+    /**
+     * Auto-fit the viewport to the first paper after mount. Default
+     * `"width"` — what most embedders want for a "looks right out of the
+     * box" first impression. Pass `"none"` if you're driving the
+     * viewport yourself.
+     */
+    fitOnMount?: FitOnMount;
+}
+/**
+ * The editor handle returned by `createSobree()`. Proxies the most-used
+ * methods of the underlying `Sobree` + `Editor` so embedders rarely
+ * need to reach through. Power users can use `.sobree` / `.editor` /
+ * `.viewport` directly.
+ *
+ * Plugin instances are NOT exposed on the handle — plugins self-manage
+ * after handoff. Reach through `.editor` for command bus / events.
+ */
+export interface SobreeHandle {
+    readonly sobree: Sobree;
+    readonly editor: Editor;
+    readonly viewport: Viewport;
+    /**
+     * The Y.Doc backing the document. Provided so embedders can attach
+     * Yjs providers (`y-websocket`, `y-indexeddb`, `y-webrtc`) for
+     * persistence / collaboration without reaching through `editor.editor`.
+     * Same reference as `editor.editor.ydoc`.
+     */
+    readonly ydoc: import('yjs').Doc;
+    /**
+     * Resolves when the constructor's `content` has finished loading. For
+     * docx content this awaits the import; for everything else this is an
+     * already-resolved promise.
+     */
+    readonly ready: Promise<{
+        warnings: string[];
+    }>;
+    getDocument(): SobreeDocument;
+    setDocument(doc: SobreeDocument): void;
+    /** Replace the document with one parsed from a Markdown string (seed-quality). */
+    loadMarkdown(md: string): void;
+    /** Load a `.docx` file. Resolves with any import warnings. */
+    loadDocx(src: File | Blob | ArrayBuffer | Uint8Array): Promise<{
+        warnings: string[];
+    }>;
+    /**
+     * Serialise the current document to a `.docx` Blob. Uses bytes
+     * currently cached locally — if a `blobStore` is configured and
+     * some referenced parts aren't yet cached, call
+     * `await handle.ensurePartsLoaded()` first to pre-fetch them.
+     * Missing parts appear in `warnings`.
+     */
+    toDocx(): {
+        blob: Blob;
+        warnings: string[];
+    };
+    /**
+     * Wait for every currently-referenced binary part to be available
+     * in the local cache. No-op when no `blobStore` is configured.
+     */
+    ensurePartsLoaded(): Promise<void>;
+    getPageSetup(): PageSetup;
+    setPageSetup(partial: Partial<PageSetup>): void;
+    readonly commands: CommandBus;
+    on<E extends SobreeEvent>(event: E, cb: (payload: SobreeEventPayload[E]) => void): SobreeUnsubscribe;
+    destroy(): void;
+}
+/**
+ * Mount a fully-wired Sobree editor (Viewport + Sobree + user plugins)
+ * into `target` (CSS selector or HTMLElement). See `CreateSobreeOptions`
+ * and `SobreeHandle` for the full surface.
+ */
+export declare function createSobree(target: string | HTMLElement, options?: CreateSobreeOptions): SobreeHandle;

package/dist/doc/api.d.ts

@@ -0,0 +1,132 @@
+/**
+ * API-level types for talking to the Editor.
+ *
+ * These describe HOW you address content (positions, ranges, selections)
+ * and what guarantees you get back (block versions, edit results). They
+ * are JSON-clean so the same shapes work for in-process callers, the
+ * forthcoming WebSocket / MCP adapter, and tests.
+ *
+ * Kept separate from `src/doc/types.ts` (the AST itself) because these
+ * are runtime concerns — none of them are persisted to .docx.
+ *
+ * Design note on why there's no polymorphic `Position` type:
+ *   - For block-scoped operations (insert / replace / delete) the input
+ *     is a `BlockRef` paired with a method name that spells out the
+ *     intent (`insertBlockBefore`, `insertBlockAfter`).
+ *   - For inline-scoped operations (insert a run, move caret, apply
+ *     attributes across a span) the input is an `InlinePosition` — a
+ *     block ref plus a character offset inside that block.
+ *   This keeps method signatures self-describing for LLM / MCP callers,
+ *   no discriminated unions to construct.
+ */
+/**
+ * Stable handle to a block, valid for the lifetime of an Editor instance.
+ * `id` is allocated by the Editor on first sight (sequential strings like
+ * `"b1"`, `"b2"`); `version` bumps on every modification. Versions reset
+ * to 0 when the document is reloaded (`setDocument`, `openDocx`).
+ *
+ * Pass this to mutating operations to opt in to optimistic locking. The
+ * operation fails with `"optimistic-lock"` if the live version no longer
+ * matches.
+ */
+export interface BlockRef {
+    id: string;
+    version: number;
+}
+/** Version map for blocks an operation should also lock-check. */
+export type BlockExpectations = Record<string, number>;
+/**
+ * Address a point inside a block's content.
+ *
+ * `offset = 0` is the start of the block's content; `offset = blockLength`
+ * is the end. Non-text inlines (drawings, fields, hyperlinks) count as
+ * 1 each. A caret always lives inside a block — "before block N" is
+ * expressed as `{ block: blockN, offset: 0 }`; "after block N" is
+ * `{ block: blockN, offset: blockLength }`. For inserting NEW blocks
+ * adjacent to an existing one, use the `insertBlockBefore` /
+ * `insertBlockAfter` methods directly — they take a `BlockRef`, not a
+ * position.
+ */
+export interface InlinePosition {
+    block: BlockRef;
+    offset: number;
+}
+/**
+ * Inclusive range from `from` to `to` — both inline positions. Single-
+ * block ranges have `from.block.id === to.block.id`.
+ *
+ * For operations that span blocks, pass `opts.expect` with the middle
+ * blocks' expected versions — the Range itself only pins the endpoints.
+ */
+export interface Range {
+    from: InlinePosition;
+    to: InlinePosition;
+}
+/**
+ * The current cursor / selection state of the editor in model terms.
+ * `null` when nothing is selected (e.g. focus is outside the editor).
+ */
+export type Selection = null | {
+    kind: "caret";
+    at: InlinePosition;
+} | {
+    kind: "range";
+    range: Range;
+};
+/** Result envelope returned by every mutating operation. */
+export type EditResult<T = void> = {
+    ok: true;
+    value: T;
+    affected: BlockRef[];
+} | {
+    ok: false;
+    error: EditError;
+};
+/** Why an edit didn't apply. Discriminated union — agents switch on `code`. */
+export type EditError = OptimisticLockError | {
+    code: "invalid-position";
+    details: string;
+} | {
+    code: "unknown-block";
+    blockId: string;
+} | {
+    code: "range-empty";
+    details: string;
+} | {
+    code: "range-out-of-order";
+    details: string;
+} | {
+    code: "invalid-state";
+    details: string;
+};
+export interface OptimisticLockError {
+    code: "optimistic-lock";
+    /**
+     * Per-block conflict info. `actual` is `null` when the block has been
+     * deleted between read and write — distinguishable from a stale
+     * version on the same block.
+     */
+    conflicts: Array<{
+        blockId: string;
+        expected: number;
+        actual: number | null;
+    }>;
+}
+/** Build an inline position inside `block` at the given character offset. */
+export declare function inlineAt(block: BlockRef, offset: number): InlinePosition;
+/** Construct a range from two positions. */
+export declare function makeRange(from: InlinePosition, to: InlinePosition): Range;
+/** Caret at a single position. */
+export declare function caretAt(at: InlinePosition): Selection;
+/** True if two inline positions are inside the same block (by id). */
+export declare function sameBlock(a: InlinePosition, b: InlinePosition): boolean;
+/** Zero-width range — `from` and `to` collapsed onto the same offset. */
+export declare function isCollapsedRange(range: Range): boolean;
+/** Caret selection OR collapsed range. */
+export declare function isCaret(sel: Selection): boolean;
+/** Build an `EditResult` for a successful operation. */
+export declare function ok<T>(value: T, affected?: BlockRef[]): EditResult<T>;
+/** Build an `EditResult` for a failed operation. */
+export declare function fail(error: EditError): EditResult<never>;
+/** Specialised builder for the common optimistic-lock failure case. */
+export declare function lockConflict(conflicts: OptimisticLockError["conflicts"]): EditResult<never>;

package/dist/doc/builders.d.ts

@@ -0,0 +1,42 @@
+import { Block, HeaderFooterRef, InlineRun, NamedStyle, PageMargins, PageSize, Paragraph, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument, Table, TextRun } from './types';
+/** A new, blank document with an A4 portrait section and the standard styles. */
+export declare function emptyDocument(): SobreeDocument;
+export declare function defaultSection(): SectionProperties;
+export declare function defaultPageSize(): PageSize;
+export declare function defaultMargins(): PageMargins;
+/** A paragraph with no runs and no properties beyond the defaults. */
+export declare function paragraph(runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
+/** Heading paragraph (`Heading{level}` style, level clamped to 1..6). */
+export declare function heading(level: number, runs?: InlineRun[], extra?: ParagraphProperties): Paragraph;
+/** Plain text run with optional formatting. */
+export declare function text(value: string, properties?: RunProperties): TextRun;
+/** Convenience: emphasised (bold + italic) text run. */
+export declare function emphasis(value: string, properties?: RunProperties): TextRun;
+export declare function strong(value: string, properties?: RunProperties): TextRun;
+export declare function softBreak(): InlineRun;
+export declare function pageBreak(): InlineRun;
+/** Default Word styles every doc declares so headings render correctly.
+ *
+ *  Carries WORD-HARDCODED-DEFAULT typography — i.e. what Word uses
+ *  when a docx has bare/empty styles.xml entries. That means single
+ *  line spacing (1.0×) and zero space-before / space-after on Normal.
+ *  Headings keep their bold + size on `runDefaults` but DON'T add
+ *  spacing-before/after either — the original docx tells the renderer
+ *  via per-paragraph `spacing` properties when something needs to
+ *  breathe.
+ *
+ *  This is the load-bearing constraint: a docx round-trip must not
+ *  silently add (or remove) vertical rhythm the original didn't ask
+ *  for. Embedders that want a different baseline (e.g. markdown output
+ *  with 8pt-after for visible paragraph separation) override the
+ *  Normal style on the document they construct — see `parseMarkdown`.
+ *
+ *  Heading scale steps down from a prominent H1 at 24pt to body-sized
+ *  H6 at 11pt. */
+export declare function defaultStyles(): NamedStyle[];
+/** Push a block onto the document body. Mutates `doc` and returns it. */
+export declare function appendBlock(doc: SobreeDocument, block: Block): SobreeDocument;
+/** Allocate a new header/footer reference id. Pure helper. */
+export declare function makeHeaderFooterRef(type: "default" | "first" | "even", partId: string): HeaderFooterRef;
+export declare function isParagraph(block: Block): block is Paragraph;
+export declare function isTable(block: Block): block is Table;