@sobree/core 0.1.0 → 0.1.2

package/dist/editor/internal/mutations.d.ts

@@ -1,5 +1,5 @@
 import { Block, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument } from '../../doc/types';
-import { ParagraphPropertiesPatch, WrapTag } from '../index';
+import { ParagraphPropertiesPatch, WrapTag } from '../types';
 import { RunPropertiesPatch } from '../../doc/runs';
 /**
  * One registry-level operation produced by a mutation. The caller

package/dist/editor/ops/blocks.d.ts

@@ -0,0 +1,42 @@
+import { BlockRef, EditResult } from '../../doc/api';
+import { Block } from '../../doc/types';
+import { EditorContext } from '../context';
+import { ParagraphPropertiesPatch } from '../types';
+/**
+ * Block-level mutations: replace / insert / delete whole blocks and
+ * patch paragraph properties. All enforce optimistic locking via
+ * `ctx.checkRefs` and route through `ctx.commit`. Section-break removal
+ * merges the two sections it delimited. Track-changes mode stamps
+ * paragraph insert/delete markers instead of moving content outright.
+ */
+/** Replace the block at `target`'s index with `block`. */
+export declare function replaceBlock(ctx: EditorContext, target: BlockRef, block: Block): EditResult<BlockRef>;
+/**
+ * Insert `block` before the target block. Returns the new ref.
+ *
+ * In track-changes mode, if `block` is a paragraph it gets stamped with
+ * `revision: { type: "ins", author }` on its properties — the same
+ * paragraph-mark semantics as `splitBlock`. Non-paragraph blocks (table,
+ * section_break) don't carry the marker in v1 and insert plain.
+ */
+export declare function insertBlockBefore(ctx: EditorContext, target: BlockRef, block: Block): EditResult<BlockRef>;
+/**
+ * Insert `block` after the target block. Returns the new ref.
+ * Tracked-mode behaviour matches `insertBlockBefore`.
+ */
+export declare function insertBlockAfter(ctx: EditorContext, target: BlockRef, block: Block): EditResult<BlockRef>;
+/**
+ * Delete the target block.
+ *
+ * In track-changes mode, paragraph blocks aren't removed — their
+ * `properties.revision` is stamped `del` (the renderer shows the
+ * paragraph mark with a strikethrough ¶ glyph; the body text stays
+ * visible). If the paragraph carries the *current author's* pending
+ * `ins` marker (a paragraph the user themselves just created), the block
+ * is removed outright — cancelling an un-committed insert, matching the
+ * inline `deleteRange` semantics. Non-paragraph blocks (tables, section
+ * breaks) bypass tracking in v1 — they remove plainly.
+ */
+export declare function deleteBlock(ctx: EditorContext, target: BlockRef): EditResult<void>;
+/** Merge a patch into each target paragraph's properties. */
+export declare function applyBlockProperties(ctx: EditorContext, targets: BlockRef[], patch: ParagraphPropertiesPatch): EditResult<void>;

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

@@ -0,0 +1,12 @@
+import { EditResult } from '../../doc/api';
+import { EditorContext } from '../context';
+/**
+ * Comment resolve/reopen — flips `Comment.done` on the document's
+ * comment map. Comments live outside the body registry, so no block
+ * version bumps are needed; the change still commits (and mirrors) so
+ * collaborators and the change event see it.
+ */
+/** Mark comment `id` resolved (`Comment.done = true`). */
+export declare function resolveComment(ctx: EditorContext, id: number): EditResult<void>;
+/** Re-open a resolved comment `id` (`Comment.done = false`). */
+export declare function reopenComment(ctx: EditorContext, id: number): EditResult<void>;

package/dist/editor/ops/parts.d.ts

@@ -0,0 +1,71 @@
+import { SobreeDocument } from '../../doc/types';
+import { EmbedFontFaces, EmbedFontOptions } from '../../fonts';
+import { EditorContext } from '../context';
+/**
+ * Binary-part lifecycle: font embedding, orphan pruning, and the
+ * content-blob (`BlobStore`) migration path. When a `BlobStore` is
+ * configured, inline part bytes are mirrored to the store by content
+ * hash and referenced via `partRefs` instead of living inline in the
+ * Y.Doc; `resolveCachedPartRefsInto` / `onBlobResolved` patch bytes
+ * back into `doc.rawParts` as they arrive so the renderer stays
+ * synchronous. With no `BlobStore` (the default) the migration paths are
+ * no-ops and bytes are always inline.
+ */
+/** Patch any cached blob bytes for known partRefs into `doc.rawParts`. */
+export declare function resolveCachedPartRefsInto(ctx: EditorContext, doc: SobreeDocument): void;
+/**
+ * Callback fired by the BlobCache when a background fetch lands. Walks
+ * `lastPartRefs` to find which paths reference this hash, patches
+ * `doc.rawParts`, and re-renders so the user sees the part appear.
+ */
+export declare function onBlobResolved(ctx: EditorContext, hash: string): void;
+/**
+ * Wait for every currently-referenced binary part to be available in
+ * the local cache. Useful before `toDocx()` so the exported file
+ * contains all images / fonts. Resolves immediately when no `blobStore`
+ * is configured (bytes are always inline).
+ */
+export declare function ensurePartsLoaded(ctx: EditorContext): Promise<void>;
+/**
+ * Drop entries from `rawParts` that nothing in the AST references.
+ * Idempotent; reports the keys removed. Not auto-invoked — `exportDocx`
+ * filters at packaging time, so callers only need this when keeping the
+ * doc in-memory across many edits.
+ */
+export declare function pruneUnusedParts(ctx: EditorContext): {
+    kept: number;
+    pruned: string[];
+};
+/**
+ * Embed a TTF/OTF font into the document. Thin wrapper around
+ * `embedFontIntoDoc()` — handles the `setDocument` round so the renderer
+ * + `@font-face` registry pick up the new face, and migrates the added
+ * part bytes to the BlobStore when one is configured. Refuses (with a
+ * warning) restricted fonts unless `opts.allowRestricted`.
+ */
+export declare function embedFont(ctx: EditorContext, name: string, faces: EmbedFontFaces, opts?: EmbedFontOptions): {
+    warnings: string[];
+};
+/**
+ * Drop a font declaration by name. The associated font parts aren't
+ * removed immediately — call `pruneUnusedParts()` (or export) to GC them.
+ */
+export declare function removeEmbeddedFont(ctx: EditorContext, name: string): void;
+/**
+ * Part paths the Y.Doc mirror must NOT write inline — they're (or will
+ * soon be) tracked via `partRefs` instead. Returns `undefined` when
+ * there's nothing to skip (the common no-BlobStore case) so the mirror
+ * takes its fastest path.
+ */
+export declare function computePartPathSkipSet(ctx: EditorContext): ReadonlySet<string> | undefined;
+/**
+ * Background-migrate inline part bytes into the BlobStore. Called by
+ * mutators (`insertImage`, `embedFont`) when a `BlobStore` is configured.
+ * The local `doc.rawParts` keeps its inline copy so the renderer stays
+ * synchronous; the Y.Doc gets a `partRefs` entry referencing the
+ * content hash and any stale `parts` entry is deleted.
+ *
+ * Robust against errors: an upload failure logs and leaves the path in
+ * the pending set so a future call can retry.
+ */
+export declare function migratePartToBlobStore(ctx: EditorContext, partPath: string, bytes: Uint8Array): Promise<void>;

package/dist/editor/ops/review.d.ts

@@ -0,0 +1,67 @@
+import { Range as ApiRange, BlockRef, EditResult } from '../../doc/api';
+import { EditorContext } from '../context';
+import { RevisionSpan } from '../types';
+/**
+ * Tracked-change review: accept/reject of inline, format, and
+ * paragraph-mark revisions (single-range, paragraph-level, or
+ * whole-document), plus `getRevisions` which enumerates every logical
+ * change as coalesced `RevisionSpan`s. The run-level decisions reuse the
+ * pure transforms in `revisionRuns`; the engine is `mutateRunsInRange`
+ * (shared with the authoring path in `ops/runs`).
+ */
+/**
+ * Accept the tracked changes inside `range`: insertions become permanent
+ * (marker stripped, text kept), deletions are applied (text dropped).
+ * Runs with no revision pass through, so a slightly-wider range is safe.
+ */
+export declare function acceptRevision(ctx: EditorContext, range: ApiRange, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/** Reject the tracked changes inside `range`. Inverse of `acceptRevision`. */
+export declare function rejectRevision(ctx: EditorContext, range: ApiRange, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/** Accept tracked format changes inside `range` (drop the snapshot). */
+export declare function acceptFormatRevision(ctx: EditorContext, range: ApiRange, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/** Reject tracked format changes inside `range` (revert to `before`). */
+export declare function rejectFormatRevision(ctx: EditorContext, range: ApiRange, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/**
+ * Accept the paragraph-mark revision on `target`:
+ *   - `ins` → strip the marker; the paragraph break stays permanent.
+ *   - `del` → merge this paragraph's content into the *previous* one.
+ */
+export declare function acceptParagraphRevision(ctx: EditorContext, target: BlockRef): EditResult<void>;
+/**
+ * Reject the paragraph-mark revision on `target`:
+ *   - `ins` → merge this paragraph into the *previous* (undo the split).
+ *   - `del` → strip the marker; the paragraph break stays.
+ */
+export declare function rejectParagraphRevision(ctx: EditorContext, target: BlockRef): EditResult<void>;
+/**
+ * Flag `body[index]`'s paragraph break as a tracked deletion. Used by
+ * the Backspace-at-start-of-paragraph keystroke. Cancels the author's
+ * own pending `ins` by merging instead; leaves peer revisions alone.
+ */
+export declare function markParagraphBreakForDelete(ctx: EditorContext, index: number): EditResult<void>;
+/**
+ * Enumerate every logical tracked change. Consecutive revision-bearing
+ * runs by the same author coalesce into one `RevisionSpan`; each span
+ * carries fresh versioned refs ready for accept/reject. Re-query after
+ * each `change` — the ranges are positional.
+ */
+export declare function getRevisions(ctx: EditorContext): RevisionSpan[];
+/**
+ * Accept every tracked change (optionally filtered by author). One
+ * commit for the whole sweep.
+ */
+export declare function acceptAllRevisions(ctx: EditorContext, opts?: {
+    author?: string;
+}): EditResult<void>;
+/** Reject every tracked change (optionally filtered by author). */
+export declare function rejectAllRevisions(ctx: EditorContext, opts?: {
+    author?: string;
+}): EditResult<void>;

package/dist/editor/ops/runs.d.ts

@@ -0,0 +1,83 @@
+import { Range as ApiRange, BlockRef, EditResult, InlinePosition } from '../../doc/api';
+import { RunPropertiesPatch } from '../../doc/runs';
+import { InlineRun } from '../../doc/types';
+import { EditorContext } from '../context';
+import { WrapTag } from '../types';
+/**
+ * Inline (run-level) mutations — run properties, wrapping, run/image
+ * insertion, paragraph split, and range deletion — plus the image
+ * clipboard/drag handlers. `mutateRunsInRange` is the shared engine that
+ * applies a run transform to the slice a range covers (single- or
+ * multi-block); it's exported because the review module reuses it for
+ * accept/reject. Track-changes mode stamps `ins`/`del`/`revisionFormat`
+ * markers instead of mutating text outright.
+ */
+/** Apply run-level properties across `range`. */
+export declare function applyRunProperties(ctx: EditorContext, range: ApiRange, patch: RunPropertiesPatch, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/** Wrap the runs in `range` with semantic formatting. */
+export declare function wrapRange(ctx: EditorContext, range: ApiRange, tag: WrapTag, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/**
+ * Insert a run at `at`. Splits the run list at the offset. In
+ * track-changes mode the run is stamped `revision: ins` (unless it
+ * already carries one — caller-provided revisions win).
+ */
+export declare function insertRun(ctx: EditorContext, at: InlinePosition, run: InlineRun): EditResult<BlockRef>;
+/**
+ * Split a paragraph at `at`. Runs before the offset stay; runs after
+ * move into a fresh paragraph inserted immediately after, inheriting the
+ * original's properties. In track-changes mode the new paragraph's
+ * `properties.revision` is stamped `ins` (the "this break is a tracked
+ * insert" marker). Returns the ref of the *new* (second) block.
+ */
+export declare function splitBlock(ctx: EditorContext, at: InlinePosition): EditResult<BlockRef>;
+/**
+ * Insert an image at `at`. Bytes go into `doc.rawParts` under a fresh
+ * `word/media/imageN.{ext}` path; a `DrawingRun` referencing it is
+ * inserted. When a `blobStore` is configured the bytes migrate in the
+ * background (hashed + uploaded + `partRefs` entry); the local renderer
+ * keeps reading the inline bytes throughout.
+ */
+export declare function insertImage(ctx: EditorContext, at: InlinePosition, bytes: Uint8Array, opts: {
+    mime: string;
+    widthPx?: number;
+    heightPx?: number;
+    altText?: string;
+}): EditResult<BlockRef>;
+/**
+ * Delete the content inside `range` (single- or cross-block). In
+ * track-changes mode the deletion is *recorded*: plain runs are stamped
+ * `del`, a run already marked as the same author's pending `ins` is
+ * dropped (cancelling an un-committed insert), peer revisions are left
+ * for accept/reject. Cross-paragraph tracked deletes also stamp each
+ * later paragraph-mark `del` so `acceptAllRevisions` collapses the range.
+ */
+export declare function deleteRange(ctx: EditorContext, range: ApiRange, opts?: {
+    expect?: Record<string, number>;
+}): EditResult<void>;
+/**
+ * Apply a runs transform to the runs covered by `range`. Handles single-
+ * and multi-block ranges. Assumes locks have already been checked.
+ * Exported for reuse by the review (accept/reject) module.
+ */
+export declare function mutateRunsInRange(ctx: EditorContext, range: ApiRange, transform: (runs: InlineRun[]) => InlineRun[]): EditResult<void>;
+/**
+ * Unwrap span ancestors intersecting the selection, up to the block.
+ * Best-effort DOM-level cleanup — preserves the in-place UX without a
+ * re-render.
+ */
+export declare function clearInlineFormattingAtSelection(ctx: EditorContext): void;
+/** Insert an image at the current caret. */
+export declare function insertImageAtSelection(ctx: EditorContext, bytes: Uint8Array, opts: {
+    mime: string;
+    widthPx?: number;
+    heightPx?: number;
+    altText?: string;
+}): EditResult<BlockRef>;
+/** Read a File's bytes + intrinsic dimensions and insert it at the caret. */
+export declare function insertImageFromFile(ctx: EditorContext, file: File): Promise<void>;
+export declare function onDragOver(_ctx: EditorContext, e: DragEvent): void;
+export declare function onDrop(ctx: EditorContext, e: DragEvent): Promise<void>;

package/dist/editor/ops/trackedInput.d.ts

@@ -0,0 +1,44 @@
+import { EditorContext } from '../context';
+/**
+ * Track-changes *authoring* input — the DOM event handlers that route
+ * tracked-mode keystrokes, IME composition, and paste through the typed
+ * API so the resulting runs carry revision markers. Stateful (it holds
+ * the IME composition snapshot + a warn-once set), so it's built once per
+ * editor via {@link createTrackedInput} rather than exposed as free
+ * functions like the other `ops/*` modules.
+ *
+ * Collaborators: `ops/runs` (insertRun / splitBlock / deleteRange /
+ * insertImageFromFile), `ops/review` (markParagraphBreakForDelete for the
+ * Backspace-at-start-of-paragraph merge), `query` (caret placement +
+ * position refresh), and the kernel `restoreSnapshot` for the IME
+ * rollback. The mode *config* (`getTrackChanges` / `setTrackChanges`)
+ * stays on the Editor — it only touches the listener registry.
+ */
+export interface TrackedInput {
+    /**
+     * Route a tracked-mode `beforeinput` through the typed API. Returns
+     * `true` if consumed (caller should `preventDefault`), `false` to let
+     * the browser handle it natively (untracked).
+     */
+    handleBeforeInput(ie: InputEvent): boolean;
+    /**
+     * True when the caret sits in a block containing any revision wrapper
+     * (`<ins>` / `<del>` / `.sobree-revision-format`). `beforeinput` uses
+     * this in mode-OFF to take over the insert path so the browser doesn't
+     * stamp the new character with the wrapper's marker.
+     */
+    caretInsideRevisionWrapper(): boolean;
+    handleCompositionStart(e: CompositionEvent): void;
+    handleCompositionEnd(e: CompositionEvent): void;
+    onPaste(e: ClipboardEvent): Promise<void>;
+    /**
+     * Insert `text` at the current selection as a tracked paste — each
+     * `\n` becomes a `splitBlock`, CRLF/CR normalised to LF. The plain-text
+     * core of `onPaste`, exposed directly because jsdom provides no
+     * `DataTransfer` to drive `onPaste` end-to-end in tests.
+     */
+    pasteTrackedText(text: string): void;
+    /** Clear any in-flight composition state (called on editor destroy). */
+    reset(): void;
+}
+export declare function createTrackedInput(ctx: EditorContext): TrackedInput;

package/dist/editor/query.d.ts

@@ -0,0 +1,22 @@
+import { InlinePosition } from '../doc/api';
+import { Block } from '../doc/types';
+import { EditorContext } from './context';
+import { BlockInfo, OutlineItem } from './types';
+/**
+ * Read-only projections of the document — block summaries, the heading
+ * outline, an HTML snapshot — plus the two position helpers
+ * (`placeCaret` / `refreshedPosition`) that resolve a block id to a live
+ * ref. All pull through `ctx.ensureCurrent()` so a pending DOM edit is
+ * folded in before the read. No mutation, no commit.
+ */
+export declare function toHtml(ctx: EditorContext): string;
+export declare function getBlocks(ctx: EditorContext): BlockInfo[];
+export declare function getBlock(ctx: EditorContext, index: number): BlockInfo;
+/** Same summary, looked up by stable id. Returns `null` if unknown. */
+export declare function getBlockById(ctx: EditorContext, id: string): BlockInfo | null;
+export declare function getOutline(ctx: EditorContext): OutlineItem[];
+export declare function summariseBlock(ctx: EditorContext, block: Block, index: number): BlockInfo;
+/** Refresh a position's block ref to the live version (id stays stable). */
+export declare function refreshedPosition(ctx: EditorContext, at: InlinePosition): InlinePosition | null;
+/** Place the caret at `(blockId, offset)` using a fresh block ref. */
+export declare function placeCaret(ctx: EditorContext, blockId: string, offset: number): void;

package/dist/editor/revisionRuns.d.ts

@@ -0,0 +1,56 @@
+import { InlineRun } from '../doc/types';
+/**
+ * Resolve one run against an accept/reject decision on its tracked
+ * change. Returns the replacement run list — `[run]` unchanged,
+ * `[stripped]` to keep the text minus the revision marker, or `[]` to
+ * drop the run entirely.
+ *
+ *   accept + ins → keep text, strip marker     (insertion confirmed)
+ *   accept + del → drop run                    (deletion applied)
+ *   reject + ins → drop run                    (insertion undone)
+ *   reject + del → keep text, strip marker     (deletion undone)
+ *
+ * Non-text runs and runs with no `revision` pass through untouched.
+ */
+export declare function decideRevisionRun(run: InlineRun, decision: "accept" | "reject"): InlineRun[];
+/**
+ * Authoring helper for `insertRun` in track-changes mode. Stamps an
+ * `ins` revision on the run if it doesn't already carry one — a caller
+ * providing a pre-stamped run (e.g. an import code path replaying a
+ * revision) wins. Mirrors `decideRevisionRun`'s text-only contract:
+ * non-text runs (drawings, breaks, tabs, …) pass through unchanged in
+ * v1 — Word does track drawing inserts as revisions, but layering that
+ * on the non-uniform `properties` shape of non-text runs is a follow-up.
+ */
+export declare function stampInsertRevision(run: InlineRun, author: string | undefined): InlineRun;
+/**
+ * Consumption helper for `acceptFormatRevision` / `rejectFormatRevision`.
+ *
+ *   accept → drop `revisionFormat`; current `properties` stay.
+ *   reject → restore `properties` to `revisionFormat.before`; the
+ *            snapshot is then dropped too (the run is back to its
+ *            pre-tracking state and there's nothing to undo).
+ *
+ * Runs without a `revisionFormat` snapshot pass through unchanged.
+ */
+export declare function decideFormatRun(run: InlineRun, decision: "accept" | "reject"): InlineRun;
+/**
+ * Authoring helper for `applyRunProperties` in track-changes mode.
+ * Captures the run's current `properties` (excluding any existing
+ * `revisionFormat` so the snapshot stays self-contained) as
+ * `revisionFormat.before` if no snapshot is already in place.
+ * Subsequent tracked format edits skip re-snapshotting — the *original*
+ * pre-tracking state always wins on reject.
+ */
+export declare function snapshotFormatRevision(run: InlineRun, author: string | undefined): InlineRun;
+/**
+ * Authoring helper for `deleteRange` in track-changes mode. Per the
+ * `TrackChangesState` semantics, applied per text run in range:
+ *   - plain run (no revision)               → stamp `del`
+ *   - already-pending `ins` by same author  → drop the run (cancel)
+ *   - everything else (peer revision, peer
+ *     `del`, anything pre-marked)           → leave untouched
+ * Non-text runs pass through unchanged (same text-only contract as
+ * `stampInsertRevision`).
+ */
+export declare function stampDeleteRevision(run: InlineRun, author: string | undefined): InlineRun[];

package/dist/editor/selection.d.ts

@@ -0,0 +1,34 @@
+import { Range as ApiRange, BlockRef, InlinePosition, Selection } from '../doc/api';
+import { BlockRegistry } from './internal/blockRegistry';
+/**
+ * The slice of Editor internals `EditorSelection` reads — its
+ * decoupling seam, so this module doesn't import the concrete `Editor`
+ * class (which would re-introduce an import cycle). The `Editor`
+ * structurally satisfies it via its `_hosts()` / `_registry()`
+ * accessors.
+ */
+export interface SelectionHost {
+    _hosts(): HTMLElement[];
+    _registry(): BlockRegistry;
+}
+/**
+ * Model-level view of the editor's live DOM selection. `editor.selection`
+ * is an instance of this; it translates between the browser selection
+ * and Sobree's `Selection` / `Range` / `InlinePosition` shapes.
+ */
+export declare class EditorSelection {
+    private readonly editor;
+    constructor(editor: SelectionHost);
+    /** Current selection as a model `Selection`. Returns `null` when focus is outside. */
+    get(): Selection;
+    /** Apply a model selection to the DOM. */
+    set(sel: Selection): boolean;
+    /** Shortcut: current selection as a `Range`, or `null` when collapsed/absent. */
+    currentRange(): ApiRange | null;
+    /** Shortcut: the caret position (collapses a range to its `from`). */
+    currentCaret(): InlinePosition | null;
+    /** Shortcut: ref of the block containing the caret. */
+    currentBlock(): BlockRef | null;
+    /** Legacy: current block index (for code still using indices). */
+    currentBlockIndex(): number | null;
+}