@sobree/core 0.1.23 → 0.1.25

package/dist/editor/index.d.ts

@@ -20,22 +20,6 @@ export type { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinit
 export type { CellRef, InsertAt, InsertColumnOpts, InsertRowOpts, MergeCellsOpts, } from './types';
 export { runsLength } from '../doc/runs';
 export type { RunPropertiesPatch };
-/**
- * Public editor surface.
- *
- * Two entry points for every operation:
- *   - Core methods take `BlockRef` / `InlinePosition` / `Range` and
- *     return `EditResult`. These are the wire-callable API — same
- *     contract for in-process toolbars, headless Y peers (HeadlessSobree),
- *     and future MCP wrappers.
- *   - "AtSelection" sugar reads the live DOM selection, builds the
- *     position/range for you, and delegates to the core. Use these in
- *     in-process UI code.
- *
- * Mutations enforce optimistic locking via block `version` numbers.
- * Conflicts return `{ ok: false, error: { code: "optimistic-lock", … } }`
- * rather than throwing.
- */
 export declare class Editor {
     readonly host: HTMLElement;
     readonly selection: EditorSelection;
@@ -160,6 +144,35 @@ export declare class Editor {
      * and `emitChangeNow` sync only when this flag is set.
      */
     private domDirty;
+    /**
+     * 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`.
+     */
+    private readonly dirtyFrameIds;
+    /**
+     * 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;
+    /**
+     * 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 lastEditContext;
+    /**
+     * 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;
     /**
      * Kernel seam handed to the behaviour modules (`ops/*`, `query`). Built
      * once in the constructor; closes over this instance's privates so the
@@ -482,6 +495,81 @@ export declare class Editor {
      */
     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.
+     *
+     * `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.
+     */
+    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;
+    /** 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.
+     */
+    private captureSelectionForHistory;
+    /**
+     * 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`).
+     */
+    private capturePreEditSelection;
+    /**
+     * 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.
+     */
+    private onBeforeInput;
+    /** Drop the pending pre-edit stash — a step has captured (or extended) it. */
+    private clearPendingPreEditSelection;
+    /**
+     * 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.
+     */
+    private restoreCapturedSelection;
+    /**
+     * 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;
     /**
      * 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
@@ -521,6 +609,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/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/types.d.ts

@@ -94,6 +94,15 @@ export interface ChangePayload {
     document: SobreeDocument;
     revision: number;
     documentVersion: number;
+    /**
+     * True when this change came from a live keystroke inside an editable
+     * textbox frame — the frame's DOM already holds the edit, so the host
+     * can skip repainting the floating overlay (which would clobber the
+     * caret). Absent / false for body edits, API mutations, undo/redo, and
+     * remote (Y.Doc-driven) changes — those re-render from the AST, so the
+     * overlay IS stale and must repaint.
+     */
+    liveFrameEdit?: boolean;
 }
 /** Summary of a top-level block, for `getBlocks()` and list-style UIs. */
 export interface BlockInfo {
@@ -171,6 +180,18 @@ export interface EditorLike {
         expect?: Record<string, number>;
     }): EditResult<void>;
     readonly selection: EditorSelectionLike;
+    /**
+     * When the caret sits in an editable textbox frame, toggle a mark
+     * (`"strong"`/`"em"`/`"u"`/`"s"`/`"sup"`/`"sub"`) natively on that
+     * frame's selection — the frame read-back captures the result. Returns
+     * `true` when handled (caret was in a frame), `false` otherwise so the
+     * caller falls back to the body mark path. Optional: implemented by the
+     * DOM Editor, absent on headless peers (which have no frame DOM).
+     */
+    applyFrameMark?(tag: string): boolean;
+    /** Active state of `tag` at the frame caret, or `null` when the caret
+     *  isn't in a frame (caller uses the body `isMarkActive`). */
+    frameMarkActive?(tag: string): boolean | null;
 }
 export type EditorEvent = "change" | "selection" | "keydown" | "track-changes-change";
 export type EditorEventPayload = {

package/dist/editor/view/docRenderer/anchorLayer.d.ts

@@ -16,6 +16,16 @@ export interface AnchorLayerContext {
      * stacked text (test/headless fallback).
      */
     renderBody?: (blocks: Block[], host: HTMLElement) => void;
+    /**
+     * When true, textbox frames become editable islands: the frame turns
+     * into its own `contentEditable` host (`pointer-events:auto`) so the
+     * user can click in and type. The editor wires the read-back that
+     * serialises the frame's DOM into `anchoredFrames[id].content.body`.
+     * False / absent → display-only overlay (read-only mode, decorations,
+     * headless). Pictures, shapes, and groups stay non-interactive
+     * regardless — only textbox prose is editable.
+     */
+    editable?: boolean;
 }
 /**
  * Build the per-page anchor layer. Returns a single `<div>` whose

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;

package/dist/history/types.d.ts

@@ -1,8 +1,37 @@
+import { Selection } from '../doc/api';
 /**
- * History config + depth shape. Phase 1b.6+ — backed by Y.UndoManager;
- * the snapshot-specific types (HistoryEntry, SnapshotPosition,
- * SnapshotSelection) that lived here in Phase 1a are no longer needed.
+ * Selection inside an editable textbox frame. Frame bodies aren't body
+ * registry blocks, so the public `Selection` model can't address them —
+ * but undo/redo still needs to put the caret (or range) back. The editor
+ * captures this on a frame edit and restores it on undo, exactly as it
+ * does the body `Selection`; `History` treats the stashed value as opaque.
+ * A collapsed caret has `start === end`.
  */
+export interface FrameSelection {
+    kind: "frame-selection";
+    /** `data-anchor-id` of the frame the selection was in. */
+    frameId: string;
+    /** Character offset of the selection start across the frame's text. */
+    start: number;
+    /** Character offset of the selection end (=== start for a caret). */
+    end: number;
+}
+/**
+ * What the editor stashes for an undo step: a body `Selection` (incl.
+ * `null` when focus is outside) or a {@link FrameSelection}. Restored
+ * verbatim on undo/redo so the cursor lands where the body's would.
+ */
+export type CapturedSelection = Selection | FrameSelection;
+/**
+ * Both ends of an undo step's cursor: where it sat BEFORE the edit and
+ * AFTER it. Undo restores `before` (you land where you started the edit);
+ * redo restores `after` (you land where the edit left you) — Word/Docs
+ * behaviour. Stashed on each `Y.UndoManager` stack item's meta.
+ */
+export interface UndoSelections {
+    before: CapturedSelection;
+    after: CapturedSelection;
+}
 export interface HistoryConfig {
     /** Hard cap on entry count (per stack). UndoManager doesn't expose
      *  a max-depth knob directly — kept here for forward-compat in case