@sobree/core 0.1.25 → 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;
     /**
@@ -135,30 +131,6 @@ export declare class Editor {
      * `editor.history.undo() / redo() / clear() / depth() / on(...)`.
      */
     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.
-     */
-    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
@@ -166,13 +138,19 @@ export declare class Editor {
      */
     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`).
+     * 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 pendingPreEdit;
-    private hasPendingPreEdit;
+    private frames;
+    /**
+     * 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 pipeline;
     /**
      * Kernel seam handed to the behaviour modules (`ops/*`, `query`). Built
      * once in the constructor; closes over this instance's privates so the
@@ -181,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
@@ -197,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
@@ -234,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
@@ -472,136 +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.
-     *
-     * `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.
+     * (`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

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/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;
+}