@sobree/core 0.1.24 → 0.1.26

package/dist/editor/index.d.ts

@@ -103,8 +103,6 @@ export declare class Editor {
     private readonly registry;
     private readonly debounceMs;
     private readonly getContentHosts;
-    private debounceHandle;
-    private revision;
     /** The editor's observable event surface (change / selection / keydown
      *  / track-changes-change). See `./events.ts`. */
     private readonly events;
@@ -123,8 +121,6 @@ export declare class Editor {
      * `ops/trackedInput`.
      */
     private trackedInput;
-    /** Cached last-seen per-block JSON strings, for diff-based version bumps. */
-    private lastSerialisedBlocks;
     /** Tracks `@font-face` registrations for the document's embedded fonts. */
     private readonly fontFaces;
     /**
@@ -136,29 +132,25 @@ export declare class Editor {
      */
     readonly history: History;
     /**
-     * True when DOM mutations since the last sync were user-driven (typing,
-     * paste, drag-drop image). False right after we render from AST — the
-     * DOM is then a projection of `this.doc`, and reading it back can't
-     * tell us anything the AST doesn't already know, while losing any
-     * fidelity the serializer drops (column widths, vAlign, …). `getDocument`
-     * and `emitChangeNow` sync only when this flag is set.
+     * The editing context the caret was last in — a frame id, or `"body"`.
+     * When it changes, the undo-capture group is closed so each box's edit
+     * is a distinct undo step. `null` until the first selection.
      */
-    private domDirty;
+    private lastEditContext;
     /**
-     * Ids of editable textbox frames whose DOM the user has edited since
-     * the last sync. Frames live in the floating overlay (outside the
-     * body content hosts), so they need their own read-back path —
-     * `syncFromDom` re-serialises each dirty frame into
-     * `anchoredFrames[id].content.body`.
+     * Editable-textbox-frame controller — owns the dirty-frame set, the
+     * frame DOM read-back, and the pre-/post-edit selection capture/restore
+     * that drives gold-standard frame undo. Built in the constructor. See
+     * `./internal/frames.ts`.
      */
-    private readonly dirtyFrameIds;
+    private frames;
     /**
-     * Set by `syncFromDom` when the pending change was a pure live frame
-     * keystroke; read (and reset) by `emitChangeNow` into the change
-     * payload's `liveFrameEdit`. Lets the host skip the overlay repaint
-     * that would clobber the caret, while still repainting on undo/remote.
+     * The change / sync pipeline — owns `revision`, the debounce handle, the
+     * per-block JSON cache + `domDirty`, and the render → mirror → emit
+     * cycle (`commit`, `syncFromDom`, `adoptYDocState`, …). Built in the
+     * constructor. See `./internal/changePipeline.ts`.
      */
-    private pendingLiveFrameEdit;
+    private pipeline;
     /**
      * Kernel seam handed to the behaviour modules (`ops/*`, `query`). Built
      * once in the constructor; closes over this instance's privates so the
@@ -167,6 +159,32 @@ export declare class Editor {
      */
     private readonly ctx;
     constructor(host: HTMLElement, options?: EditorOptions);
+    /**
+     * Optional content-hashed blob layer. The cache's `onResolved` callback
+     * patches `doc.rawParts` and fires `change` so the renderer picks up a
+     * freshly-arrived blob without an explicit refresh from the embedder.
+     */
+    private createBlobCache;
+    /**
+     * History orchestrator — Phase 1b.6: backed by Y.UndoManager, which
+     * observes the body / meta / parts top-level Y types and tracks
+     * operations whose origin matches `localOrigin`. Local edits (mirrored
+     * with origin "local") create stack items; remote-provider edits don't —
+     * so `Cmd+Z` reverses only this peer's own edits. Selection capture /
+     * restore is delegated to the {@link FrameController} (referenced lazily;
+     * it's built right after this).
+     */
+    private createHistory;
+    /** Editor-attribute setup + the initial render of the seeded document. */
+    private mountHost;
+    /** The hooks `wireEditorDom` calls — each forwards to the owning module. */
+    private buildDomHooks;
+    /**
+     * Route an `input` event. A caret inside an editable textbox frame reads
+     * back into that frame's body (not the document body); everything else is
+     * an ordinary body edit. Either way, schedule a debounced change.
+     */
+    private handleInput;
     /**
      * Initialise `this.doc` + registry from the Y.Doc. Two paths, run
      * after the context exists so the adopt path can resolve cached part
@@ -183,12 +201,6 @@ export declare class Editor {
      * stay private to the class while modules get a curated surface.
      */
     private buildContext;
-    /**
-     * Re-project the Y.Doc into `this.doc`, sync the BlockRegistry to
-     * the projected ids, re-render the DOM, and fire `change`. Called
-     * when a remote provider applies an update we didn't initiate.
-     */
-    private adoptYDocState;
     /**
      * Resolve any `partRefs` hashes that are currently cached into the
      * provided document's `rawParts`. In-place mutation — the document
@@ -220,26 +232,6 @@ export declare class Editor {
     setShowHiddenText(show: boolean): void;
     /** Replace the document. Fires `change` synchronously. */
     setDocument(doc: SobreeDocument): void;
-    /**
-     * Internal apply path shared by `setDocument` and any other
-     * full-replace caller. The Y.Doc mirror produces tracked Y
-     * operations that Y.UndoManager turns into a single stack item.
-     */
-    private applyDocument;
-    /**
-     * Re-render the current `doc` into the content hosts. Syncs
-     * `@font-face` registrations BEFORE rendering so newly-embedded fonts
-     * are available to the render pass. No selection restore, no change
-     * emit — callers sequence those.
-     */
-    private renderCurrent;
-    /**
-     * Soft-revert to a doc `snapshot` and re-render. Resets the
-     * serialised-block cache + dom-dirty flag; no registry reset, mirror, or
-     * change emit. Used to undo native IME mutations before a tracked
-     * re-insert (see `ops/trackedInput`).
-     */
-    private restoreSnapshot;
     /**
      * Drop entries from `rawParts` that nothing in the AST references.
      * Useful after deleting images (or font embeds — Phase 3) to keep the
@@ -458,87 +450,18 @@ export declare class Editor {
     _registry(): BlockRegistry;
     /** @internal */
     _blockElementAt(index: number): HTMLElement | null;
-    /**
-     * Parallel array of live block ids (same length as `doc.body`), used
-     * by the renderer to stamp `data-block-id` onto every block element.
-     * Lets external tools (block tools, embedders) locate a block's DOM
-     * element after the body is re-rendered from scratch.
-     */
-    private blockIdsArray;
     private checkRefs;
     private checkRange;
-    /**
-     * Apply a mutation to `this.doc`, update the registry, re-render, fire
-     * change. Returns the affected refs (post-bump).
-     */
-    private commit;
-    /**
-     * Ensure `this.doc` reflects the latest edits. If the DOM has been
-     * dirtied by user typing / paste / drop, pull the latest content out
-     * of it and bump affected block versions. If the last mutation came
-     * from the API, the AST is already current — skip the (lossy)
-     * DOM-to-AST round-trip.
-     */
-    private ensureCurrent;
-    private syncFromDom;
-    /**
-     * Re-read the DOM of each dirty editable textbox frame into the AST.
-     * The frame element IS the serialization host (the block renderer paints
-     * its body directly into it), so `serializeHostsToDocument([el])` yields
-     * the same `Block[]` shape as a body host. Matched to the AST frame by
-     * its stable `data-anchor-id`. Pure body swap — geometry/anchor untouched.
-     */
-    private syncFramesFromDom;
-    /**
-     * The id of the editable textbox frame the caret currently sits in, or
-     * null when the selection is in ordinary body flow. Used to route an
-     * `input` event to the frame read-back instead of the body read-back.
-     */
-    private editedFrameId;
     /**
      * Toggle a mark on the caret inside an editable textbox frame, natively
-     * (`document.execCommand`), so the body-selection mark path doesn't have
-     * to understand frame coordinates. The resulting `<b>`/`<i>`/`<u>` tags
-     * round-trip through the frame read-back (the inline serializer maps them
-     * to run properties). Returns false when the caret isn't in a frame, so
-     * the mark command falls back to the body path.
+     * (`document.execCommand`). Returns false when the caret isn't in a
+     * frame, so the mark command falls back to the body path. See
+     * {@link FrameController.applyFrameMark}.
      */
     applyFrameMark(tag: string): boolean;
     /** Active state of `tag` at a frame caret (toolbar highlight), or null
      *  when the caret isn't in a frame. */
     frameMarkActive(tag: string): boolean | null;
-    /**
-     * Schedule a DOM-driven change emit. Called from the `input` listener
-     * when the user types — the DOM is the source of truth and we sync the
-     * AST from it before notifying listeners.
-     */
-    private scheduleChange;
-    /**
-     * Emit a `change` event using the current in-memory AST verbatim. Do
-     * NOT sync from DOM — callers that need a DOM sync should call it
-     * explicitly (user-typing path does). API mutations have already
-     * rendered their AST into the DOM and must not let the lossy DOM-read
-     * overwrite properties the renderer doesn't surface
-     * (column widths, verticalAlign, table properties, …).
-     */
-    private emitChangeNow;
-    /**
-     * Snapshot of the live block ids in body order — used both as the
-     * input to `applyDocumentToYDoc` (so each Y.Map carries its stable
-     * id) and as the `blockIdsArray()` the renderer uses to set the
-     * `data-block-id` attribute.
-     */
-    private allBlockIds;
-    /**
-     * Mirror the current `this.doc` into the Y.Doc as a single
-     * transaction. The diff is performed by `applyDocumentToYDoc`,
-     * which matches blocks by id so concurrent edits to *different*
-     * blocks merge cleanly via the Y.Array CRDT.
-     *
-     * Origin is `"local"` so a future Y observer can distinguish locally-
-     * driven mutations (already rendered) from remote ones (need re-render).
-     */
-    private mirrorToYDoc;
     /**
      * Compose the current selection into a {@link SelectionPayload} and
      * dispatch to subscribers. Called from the document-level
@@ -546,6 +469,14 @@ export declare class Editor {
      * even when no subscribers exist (the early-return keeps it cheap).
      */
     private fireSelection;
+    /**
+     * When the caret moves to a different editing context — another textbox
+     * frame, or between a frame and the body — close the undo-capture group
+     * so the next edit there is its own undo step. Without this, two edits
+     * to different boxes within `captureTimeout` coalesce and a single undo
+     * reverts both, unlike Word (where each box is a distinct action).
+     */
+    private breakUndoOnContextChange;
     private fireKeyDown;
 }
 export { countBlocks };

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

@@ -0,0 +1,123 @@
+import { EditResult } from '../../doc/api';
+import { SobreeDocument } from '../../doc/types';
+import { EditorContext } from '../context';
+import { EditorEvents } from '../events';
+import { FrameController } from './frames';
+import { Mutation } from './mutations';
+export declare class ChangePipeline {
+    private readonly ctx;
+    private readonly events;
+    private readonly frames;
+    private readonly debounceMs;
+    private revision;
+    private debounceHandle;
+    /** Cached last-seen per-block JSON strings, for diff-based version bumps. */
+    private lastSerialisedBlocks;
+    /**
+     * True when DOM mutations since the last sync were user-driven (typing,
+     * paste, drag-drop image). False right after we render from AST — the
+     * DOM is then a projection of the doc, and reading it back can't tell us
+     * anything the AST doesn't already know, while losing any fidelity the
+     * serializer drops (column widths, vAlign, …). `getDocument` and
+     * `emitChangeNow` sync only when this flag is set.
+     */
+    private domDirty;
+    /**
+     * Set by `syncFromDom` when the pending change was a pure live frame
+     * keystroke; read (and reset) by `emitChangeNow` into the change
+     * payload's `liveFrameEdit`. Lets the host skip the overlay repaint
+     * that would clobber the caret, while still repainting on undo/remote.
+     */
+    private pendingLiveFrameEdit;
+    constructor(ctx: EditorContext, events: EditorEvents, frames: FrameController, debounceMs: number);
+    /** Monotonic counter bumped on each `change` event. */
+    getRevision(): number;
+    /** Mark the body DOM dirty (user typed in body flow). */
+    markBodyDirty(): void;
+    setDomDirty(value: boolean): void;
+    /**
+     * Seed `lastSerialisedBlocks` from `doc` (no dirty flip). Called from the
+     * Editor's document-init path, which owns `doc`/registry setup directly.
+     */
+    captureBaseline(doc: SobreeDocument): void;
+    /** Cancel any pending debounced change (teardown). */
+    cancelPending(): void;
+    /**
+     * Apply a mutation to the doc, update the registry, re-render, fire
+     * change. Returns the affected refs (post-bump).
+     */
+    commit<T = void>(update: Partial<SobreeDocument>, mutations: readonly Mutation[], value?: T, _reason?: string): EditResult<T>;
+    /**
+     * Ensure the doc reflects the latest edits. If the DOM has been dirtied
+     * by user typing / paste / drop, pull the latest content out of it and
+     * bump affected block versions. If the last mutation came from the API,
+     * the AST is already current — skip the (lossy) DOM-to-AST round-trip.
+     */
+    ensureCurrent(): SobreeDocument;
+    syncFromDom(): SobreeDocument;
+    /**
+     * Schedule a DOM-driven change emit. Called from the `input` listener
+     * when the user types — the DOM is the source of truth and we sync the
+     * AST from it before notifying listeners.
+     */
+    scheduleChange(): void;
+    /**
+     * Emit a `change` event using the current in-memory AST verbatim. Do
+     * NOT sync from DOM — callers that need a DOM sync should call it
+     * explicitly (user-typing path does). API mutations have already
+     * rendered their AST into the DOM and must not let the lossy DOM-read
+     * overwrite properties the renderer doesn't surface
+     * (column widths, verticalAlign, table properties, …).
+     */
+    emitChangeNow(): void;
+    /**
+     * Re-render the current `doc` into the content hosts. Syncs
+     * `@font-face` registrations BEFORE rendering so newly-embedded fonts
+     * are available to the render pass. No selection restore, no change
+     * emit — callers sequence those.
+     */
+    renderCurrent(): void;
+    /**
+     * Soft-revert to a doc `snapshot` and re-render. Resets the
+     * serialised-block cache + dom-dirty flag; no registry reset, mirror, or
+     * change emit. Used to undo native IME mutations before a tracked
+     * re-insert (see `ops/trackedInput`).
+     */
+    restoreSnapshot(snapshot: SobreeDocument): void;
+    /**
+     * Internal apply path shared by `setDocument` and any other
+     * full-replace caller. The Y.Doc mirror produces tracked Y
+     * operations that Y.UndoManager turns into a single stack item.
+     */
+    applyDocument(doc: SobreeDocument): void;
+    /**
+     * Parallel array of live block ids (same length as `doc.body`), used by
+     * the renderer to stamp `data-block-id` onto every block element. Lets
+     * external tools (block tools, embedders) locate a block's DOM element
+     * after the body is re-rendered from scratch.
+     */
+    blockIdsArray(): string[];
+    /**
+     * Snapshot of the live block ids in body order — used both as the input
+     * to `applyDocumentToYDoc` (so each Y.Map carries its stable id) and as
+     * the `blockIdsArray()` the renderer uses to set the `data-block-id`
+     * attribute.
+     */
+    allBlockIds(): string[];
+    /**
+     * Mirror the current `doc` into the Y.Doc as a single transaction. The
+     * diff is performed by `applyDocumentToYDoc`, which matches blocks by id
+     * so concurrent edits to *different* blocks merge cleanly via the
+     * Y.Array CRDT.
+     *
+     * Origin is `"local"` so a future Y observer can distinguish locally-
+     * driven mutations (already rendered) from remote ones (need re-render).
+     */
+    mirrorToYDoc(): void;
+    /**
+     * Re-project the Y.Doc into `doc`, sync the BlockRegistry to the
+     * projected ids, re-render the DOM, and fire `change`. Called when a
+     * remote provider applies an update we didn't initiate.
+     */
+    adoptYDocState(): void;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Selection <-> character-offset helpers for editable textbox frames.
+ *
+ * A frame's body is a contentEditable island whose text isn't addressable
+ * by the body's block-registry `Selection` model. Undo/redo still needs to
+ * capture the caret (or selection) on a frame edit and put it back, so we
+ * model a frame selection as a `{ start, end }` character span across the
+ * frame's text nodes — stable enough to survive the AST round-trip and
+ * clamp cleanly to the (possibly shorter) post-undo text. A collapsed
+ * caret is `start === end`.
+ */
+export interface FrameOffsets {
+    /** Character offset of the selection start within the frame. */
+    start: number;
+    /** Character offset of the selection end (=== start for a caret). */
+    end: number;
+}
+/**
+ * The current selection's `{ start, end }` character offsets within `root`,
+ * or `null` when the selection isn't anchored inside `root`. Normalised so
+ * `start <= end` regardless of selection direction.
+ */
+export declare function frameSelectionOffsets(root: HTMLElement, doc: Document): FrameOffsets | null;
+/**
+ * Character offset of the collapsed caret within `root` (selection start),
+ * or `null` when the selection isn't inside `root`. Thin wrapper over
+ * {@link frameSelectionOffsets} for caret-only callers.
+ */
+export declare function caretCharOffset(root: HTMLElement, doc: Document): number | null;
+/**
+ * Select `start..end` characters within `root` (a collapsed caret when
+ * equal), clamping each end to the available text — an undo can revert to
+ * shorter text. No-op-safe when `root` has no text nodes.
+ */
+export declare function applyFrameSelection(root: HTMLElement, offsets: FrameOffsets, doc: Document): void;
+/** Place a collapsed caret `offset` chars into `root` (clamped). */
+export declare function placeCaretAtOffset(root: HTMLElement, offset: number, doc: Document): void;

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

@@ -0,0 +1,105 @@
+import { CapturedSelection } from '../../history/types';
+import { EditorContext } from '../context';
+export declare class FrameController {
+    private readonly ctx;
+    /**
+     * Ids of editable textbox frames whose DOM the user has edited since
+     * the last sync. Frames live in the floating overlay (outside the
+     * body content hosts), so they need their own read-back path —
+     * `syncFramesFromDom` re-serialises each dirty frame into
+     * `anchoredFrames[id].content.body`.
+     */
+    private readonly dirtyFrameIds;
+    /**
+     * Selection captured at `beforeinput` (pre-DOM-mutation) for the open
+     * undo group — restored on undo so the caret lands where the edit began.
+     * `hasPendingPreEdit` distinguishes "nothing stashed" from a stashed
+     * `null` (a body `Selection` can legitimately be `null`).
+     */
+    private pendingPreEdit;
+    private hasPendingPreEdit;
+    constructor(ctx: EditorContext);
+    /** True when a frame edit is pending a read-back. */
+    hasDirtyFrames(): boolean;
+    /**
+     * Route an `input` event: if the caret sits in an editable textbox
+     * frame, mark that frame dirty and return `true` (the body must NOT be
+     * read back). Returns `false` for an ordinary body edit.
+     */
+    routeInput(): boolean;
+    /**
+     * Re-read the DOM of each dirty editable textbox frame into the AST.
+     * The frame element IS the serialization host (the block renderer paints
+     * its body directly into it), so `serializeHostsToDocument([el])` yields
+     * the same `Block[]` shape as a body host. Matched to the AST frame by
+     * its stable `data-anchor-id`. Pure body swap — geometry/anchor untouched.
+     *
+     * `captureRunDefaults` promotes each paragraph's rendered base font to
+     * `runDefaults`, so a frame's text keeps its size/family even when a
+     * keystroke (or a select-all-retype) strips every run's inline styling —
+     * the heading no longer collapses to the default font on the next repaint.
+     */
+    syncFramesFromDom(): void;
+    /**
+     * The id of the editable textbox frame the caret currently sits in, or
+     * null when the selection is in ordinary body flow. Used to route an
+     * `input` event to the frame read-back instead of the body read-back.
+     */
+    editedFrameId(): string | null;
+    /** The editable textbox frame element the caret is inside, or null. */
+    private focusedFrameEl;
+    /** The (freshly-painted) frame element with this `data-anchor-id`, or null. */
+    private frameElById;
+    /**
+     * Capture the live selection for an undo step. A selection inside an
+     * editable textbox frame becomes a `FrameSelection` — the body
+     * `Selection` model is keyed on registry blocks and can't address frame
+     * content — so undo can restore it the same way it restores a body
+     * selection. Everything else is an ordinary body selection.
+     */
+    captureSelectionForHistory(): CapturedSelection;
+    /**
+     * The selection BEFORE the edit that opened the current undo group,
+     * stashed by `onBeforeInput` (which fires before the DOM mutates). Falls
+     * back to the live selection for edits that bypass `beforeinput`
+     * (programmatic mutations, `setDocument`).
+     */
+    capturePreEditSelection(): CapturedSelection;
+    /**
+     * Stash the pre-edit selection on the first input of a new undo group,
+     * so undo can land the caret where the edit began. `beforeinput` fires
+     * before the browser mutates the DOM, so the live selection here is the
+     * pre-edit position. Only the FIRST input of a group stashes; coalesced
+     * inputs leave the group's `before` intact (`History.onGroupSettled`
+     * clears the stash once a step has captured).
+     *
+     * Scoped to textbox frames. The body already restores its caret through
+     * the proven `applySelectionToDom` path on `stack-item-popped`; we leave
+     * its behaviour byte-for-byte unchanged (no pre-edit stash → `before`
+     * falls back to the post-edit selection, same as `after`). Frames had no
+     * working restore at all, so they get the full pre-/post-edit treatment.
+     */
+    onBeforeInput(): void;
+    /** Drop the pending pre-edit stash — a step has captured (or extended) it. */
+    clearPendingPreEditSelection(): void;
+    /**
+     * Restore an undo step's selection. Fires on `stack-item-popped`, which
+     * runs AFTER the change handler has already repainted the frame overlay
+     * (`adoptYDocState` calls `emitChangeNow` synchronously), so a captured
+     * frame selection lands on the fresh frame element and sticks — the same
+     * lifecycle the body selection restore relies on.
+     */
+    restoreCapturedSelection(sel: CapturedSelection): void;
+    /**
+     * Toggle a mark on the caret inside an editable textbox frame, natively
+     * (`document.execCommand`), so the body-selection mark path doesn't have
+     * to understand frame coordinates. The resulting `<b>`/`<i>`/`<u>` tags
+     * round-trip through the frame read-back (the inline serializer maps them
+     * to run properties). Returns false when the caret isn't in a frame, so
+     * the mark command falls back to the body path.
+     */
+    applyFrameMark(tag: string): boolean;
+    /** Active state of `tag` at a frame caret (toolbar highlight), or null
+     *  when the caret isn't in a frame. */
+    frameMarkActive(tag: string): boolean | null;
+}

package/dist/editor/view/docSerialize/block.d.ts

@@ -10,5 +10,20 @@ export interface BlockSerializeContext {
         numId: number;
         ordered: boolean;
     } | null;
+    /**
+     * Capture each paragraph's effective base run style (from the rendered
+     * `<p>`'s inline font) into `ParagraphProperties.runDefaults`.
+     *
+     * Used for textbox-frame read-back only. A frame's text carries its font
+     * on the runs, with no named style to fall back on; so when a keystroke
+     * lands in a bare text node — or a select-all-retype replaces every
+     * styled span with one unstyled node — the runs lose their font and a
+     * repaint renders the whole line at the default tiny size. The `<p>`
+     * element keeps its inline font through these DOM edits, so promoting it
+     * to a paragraph-level default makes the font survive run-level loss.
+     * Body flow leaves this off: its runs legitimately inherit from named
+     * styles, which must stay style-linked across edits.
+     */
+    captureRunDefaults?: boolean;
 }
 export declare function blocksFromNodes(nodes: readonly Node[], ctx: BlockSerializeContext): Block[];

package/dist/editor/view/docSerialize/index.d.ts

@@ -5,4 +5,13 @@ import { SobreeDocument } from '../../../doc/types';
  * produced here — the Sobree façade injects those from its current page
  * setup state before handing the document off to the exporter.
  */
-export declare function serializeHostsToDocument(hosts: readonly HTMLElement[]): SobreeDocument;
+export interface SerializeHostsOptions {
+    /**
+     * Capture each paragraph's effective base run style into
+     * `ParagraphProperties.runDefaults`. Set for textbox-frame read-back so a
+     * frame's font survives run-level styling loss; left off for body flow,
+     * which stays style-linked. See `BlockSerializeContext.captureRunDefaults`.
+     */
+    captureRunDefaults?: boolean;
+}
+export declare function serializeHostsToDocument(hosts: readonly HTMLElement[], options?: SerializeHostsOptions): SobreeDocument;

package/dist/editor/view/docSerialize/inline.d.ts

@@ -1,4 +1,4 @@
-import { InlineRun } from '../../../doc/types';
+import { InlineRun, RunProperties } from '../../../doc/types';
 /**
  * Serialise DOM children of `el` into a flat `InlineRun[]`. Nested
  * formatting wrappers (`<strong><em>...`) are flattened — each leaf text
@@ -9,3 +9,4 @@ import { InlineRun } from '../../../doc/types';
  * children (their own flat run list).
  */
 export declare function serializeInlineChildren(el: HTMLElement): InlineRun[];
+export declare function mergeStyleAttribute(base: RunProperties, styleAttr: string | null): RunProperties;

package/dist/editor/wiring.d.ts

@@ -24,6 +24,9 @@ export interface EditorDomHooks {
     trackedInput: TrackedInput;
     /** Tracked-changes authoring mode is on right now. */
     isTrackedEnabled: () => boolean;
+    /** A real edit is about to mutate the DOM (`beforeinput`, before the
+     *  mutation). Lets the editor stash the pre-edit selection for undo. */
+    onBeforeInput: () => void;
     /** Mark the DOM dirty + schedule a debounced change. */
     onInput: () => void;
     /** Fire the editor's `selection` event. */

package/dist/history/history.d.ts

@@ -1,5 +1,5 @@
-import { Selection, Selection as PublicSelection } from '../doc/api';
-import { HistoryConfig, HistoryDepth } from './types';
+import { CapturedSelection, HistoryConfig, HistoryDepth } from './types';
+import { Selection as PublicSelection } from '../doc/api';
 /**
  * Undo / redo for the Sobree editor — backed by `Y.UndoManager`.
  *
@@ -51,22 +51,43 @@ export interface HistoryOptions extends Partial<HistoryConfig> {
      *  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;
+    /** Capture the *current* (post-edit) live selection — called as a
+     *  stack item is added/updated, stashed as the step's `after`. Returns
+     *  a body `Selection` or a frame selection; `History` keeps it opaque. */
+    captureSelection: () => CapturedSelection;
+    /** Capture the selection as it was BEFORE the edit that opened the
+     *  current undo step — stashed as the step's `before` and restored on
+     *  undo. Defaults to {@link captureSelection} when not provided (callers
+     *  without a pre-edit hook, e.g. headless, get post-edit on both). */
+    capturePreEditSelection?: () => CapturedSelection;
     /** 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;
+    restoreSelection: (sel: CapturedSelection) => void;
+    /** Notify the caller that the current undo group has captured (or
+     *  extended) its selection, so it can drop any pending pre-edit stash.
+     *  Fires on every `stack-item-added` / `stack-item-updated`. */
+    onGroupSettled?: () => void;
 }
 export declare class History {
     private readonly mgr;
     private readonly listeners;
     private readonly captureSelection;
+    private readonly capturePreEditSelection;
     private readonly restoreSelection;
+    private readonly onGroupSettled;
     constructor(opts: HistoryOptions);
     undo(): boolean;
     redo(): boolean;
+    /**
+     * Close the current undo-capture group so the NEXT local edit starts a
+     * fresh undo step instead of coalescing into the previous one (within
+     * `captureTimeout`). The editor calls this when the editing context
+     * changes — e.g. the caret moves to a different textbox frame, or
+     * between a frame and the body — so two distinct edits don't collapse
+     * into a single undo. No-op when there's nothing pending to capture.
+     */
+    stopCapturing(): void;
     canUndo(): boolean;
     canRedo(): boolean;
     clear(): void;