@sobree/core 0.1.0

package/dist/paperStack/paperStack.d.ts

@@ -0,0 +1,245 @@
+import { PageSetup } from './pageSetup';
+import { AnchoredFrame, Block, NamedStyle, NumberingDefinition, SectionProperties } from '../doc/types';
+/**
+ * Sourced from `SobreeDocument`: the rich AST + the dependencies
+ * `renderBlocks` needs (numbering, named styles, embedded media bytes).
+ * When set, every page renders headers/footers from this AST and
+ * ignores the `PageSetup.header.default` / `footer.default` string
+ * templates. Cleared (set back to `null`) when the doc has no
+ * header/footer parts — falls back to the legacy text path.
+ */
+export interface RichZonesSource {
+    headerFooterBodies: Record<string, Block[]>;
+    numbering: readonly NumberingDefinition[];
+    styles: readonly NamedStyle[];
+    rawParts: Record<string, Uint8Array>;
+}
+/**
+ * Stack of Paper elements. The stack's root is the single contentEditable
+ * region; each paper's header/footer is contentEditable=false. Blocks of
+ * editor content are physically distributed across the papers'
+ * `.paper-content` elements. Editing naturally crosses page boundaries
+ * because the whole stack is one editable region.
+ *
+ * Call `repaginate()` after content changes or after page setup changes.
+ */
+export declare class PaperStack {
+    readonly root: HTMLElement;
+    private papers;
+    private setup;
+    /**
+     * Layout-side zoom tier currently applied to an ancestor (via the Viewport's
+     * CSS `zoom`). Measurements from offsetHeight/offsetTop come back in zoomed
+     * pixels, so the page budget must scale the same way.
+     */
+    private renderTier;
+    /** Optional observer fired after every successful repagination. */
+    private paginateListeners;
+    /**
+     * Per-section property overrides. When set, each Paper applies the
+     * section's settings (currently just `vAlign`) based on the
+     * `data-section-index` stamped on its first block. Sobree provides
+     * this from the live document; absent → all pages use `setup`.
+     */
+    private sections;
+    /**
+     * Optional rich-AST source for header/footer rendering. When present,
+     * each paper's header/footer is rendered from the matching part body
+     * (resolved through `sections[i].headerRefs` / `footerRefs`) instead
+     * of from the `PageSetup` string template. Set via `setRichZones`.
+     */
+    private richZones;
+    /**
+     * Document's floating-layer frames (the new architecture replacing
+     * the lifter + framePictures hacks). When set, each paper is painted
+     * with the subset of frames whose anchor resolves to that page;
+     * paper.setAnchoredFrames does the per-page filtering and DOM swap.
+     * `null` → no floating layer at all (skeleton state during Phase B).
+     */
+    private anchoredFrames;
+    /** Reused blob-URL cache across renders so the same image isn't re-uploaded. */
+    private readonly anchorPictureUrlCache;
+    constructor(container: HTMLElement, setup: PageSetup);
+    /**
+     * Provide the document's sections for per-page property application.
+     * Re-applied immediately so a setSections call without a content
+     * change still updates papers (e.g. user edits a section's vAlign in
+     * the future Page Setup section selector).
+     */
+    setSections(sections: readonly SectionProperties[]): void;
+    /**
+     * Install or clear the rich AST source for header/footer rendering.
+     * Re-renders zones immediately so the swap is visible without waiting
+     * for the next paginate. Pass `null` to revert to the legacy text-
+     * template path (no rich body available).
+     */
+    setRichZones(source: RichZonesSource | null): void;
+    /**
+     * Install or clear the document's floating-layer frames. Each frame's
+     * `anchor.paragraphIndex` (when set) decides which page receives it
+     * after the next repaginate; frames without a paragraph index land
+     * on the first page of their section. Pass `null` to clear.
+     *
+     * Call after `setRichZones`/`updateBodyBlocks` so the next render
+     * picks up the new floating content alongside body flow.
+     */
+    setAnchoredFrames(frames: readonly AnchoredFrame[] | null): void;
+    getSetup(): PageSetup;
+    getPageCount(): number;
+    onPaginate(cb: (pageCount: number) => void): () => void;
+    /** First paper's content — initial render target for a new editor. */
+    get primaryContent(): HTMLElement;
+    /** First paper card — for viewport fit-to-page calculations. */
+    get firstPaper(): HTMLElement;
+    /** First paper's row wrapper (paper + comments sidebar) — for fit-to-width. */
+    get firstPaperRow(): HTMLElement;
+    /** All content hosts in document order — for serialization. */
+    get contentHosts(): HTMLElement[];
+    updateSetup(setup: PageSetup): void;
+    /**
+     * Called by the Viewport when the layout-zoom tier changes. In Chromium,
+     * CSS `zoom` doesn't change `offsetHeight`/`offsetTop`, so measurements
+     * stay logical and the page budget is unaffected. We still re-paginate
+     * defensively — tier changes re-render text at a new resolution, which
+     * can nudge line wrapping at sub-pixel boundaries.
+     */
+    setRenderTier(tier: number): void;
+    /**
+     * Redistribute blocks across papers so no paper overflows. Creates or
+     * removes papers as needed.
+     *
+     * Delegates to the pure paginator in `src/pagination/` via the DOM
+     * adapter. Before paginating, blocks are **consolidated** into the first
+     * paper's content so their `offsetTop` values share one coordinate system,
+     * and consecutive `<p>` fragments sharing a `data-pag-pid` (previous-split
+     * siblings of the same logical paragraph) are **merged** back into a
+     * single paragraph — so each repagination starts from the clean logical
+     * flow instead of accumulating inter-fragment margins.
+     */
+    repaginate(): void;
+    /**
+     * Per-page footnote pinning. After body pagination completes, scan
+     * each paper for footnote references (`<sup class="sobree-footnote-ref">`)
+     * and populate that paper's `.paper-footnotes` zone with the cited
+     * bodies — matching Word's "footnote bodies render at the bottom of
+     * the page where they're referenced" behaviour.
+     *
+     * Footnote bodies are sourced from two places:
+     *   1. The doc-end `<aside class="sobree-footnotes">` the renderer
+     *      initially appends to paper[0].content. We harvest the `<li>`s
+     *      out of it before the aside itself gets re-paginated as a block.
+     *   2. Any footnote zones already populated from a previous repaginate
+     *      pass — those bodies stay in scope across iterations.
+     *
+     * Caveat: body budget is NOT reduced for footnote-zone height. On
+     * pages with many footnotes, the footnote zone may extend past the
+     * page bottom into the footer area. True budget-reservation is its
+     * own paginator feature.
+     */
+    private distributeFootnotes;
+    /**
+     * One round of consolidate → merge → paginate → distribute.
+     * Re-entrant: each call re-collects blocks from every paper, so the
+     * iterative loop in `repaginate` can call this multiple times with
+     * shrinking budgets to absorb post-split slippage.
+     */
+    private runPaginationOnce;
+    /**
+     * Build a `pageHeights[]` array from observed footnote-zone heights.
+     * Entry `i` = `baselineBudgetPx - footnoteZoneHeight(i)`. Pages
+     * without footnotes get the full baseline. Returned array trims
+     * trailing entries equal to the baseline, so consumers can detect
+     * "no per-page overrides needed" via `length === 0`.
+     */
+    private computePageHeights;
+    /**
+     * Largest content overflow across all papers, in CSS px. Zero means
+     * every paper fits within its content area. Used by the iterative
+     * `repaginate` to detect post-split slippage that needs another
+     * pagination pass with a tighter budget.
+     */
+    private maxPaperOverflowPx;
+    /**
+     * For every Paper, look at its first content block's `data-section-index`
+     * and apply that section's overrides. Falls back silently when no
+     * sections were provided or a paper is empty.
+     */
+    private applyPerSectionSettings;
+    private emitPaginate;
+    destroy(): void;
+    private pageContentHeightPx;
+    private collectAllBlocks;
+    private ensurePaperCount;
+    private renderAllZones;
+    /**
+     * Filter the document's `anchoredFrames` per paper and ask each Paper
+     * to swap its anchor-layer DOM accordingly. A frame's destination
+     * page is determined by its anchor:
+     *   - `paragraphIndex` set → page that ended up containing that
+     *     body block (looked up by `data-block-index` stamped on
+     *     rendered children).
+     *   - paragraphIndex absent → first paper of the frame's section.
+     *
+     * Cheap and idempotent; safe to call after any layout change.
+     */
+    private paintAnchorLayers;
+    /**
+     * Walk every paper's content children once and record, for each
+     * `data-block-index="N"` element, the paper index that holds it.
+     * The renderer stamps that attribute when emitting body paragraphs;
+     * this is the only piece of mutual knowledge between body flow and
+     * the floating layer needed for paragraph anchoring.
+     */
+    private buildParagraphPageIndex;
+    /**
+     * Section index a paper belongs to. Read off the first content
+     * block's `data-section-index` (stamped by `renderBlocks`). Empty
+     * papers and the no-sections case fall back to 0.
+     */
+    private sectionIndexForPage;
+    /**
+     * True when this paper is the first page of its section. Used to
+     * select the `first`-typed header/footer ref when the section has
+     * `titlePage = true`.
+     */
+    private isFirstPaperOfSection;
+    /**
+     * Resolve which header/footer Block[] applies to a paper. Walks the
+     * section's refs by type and looks up the corresponding part body in
+     * `richZones.headerFooterBodies`. Returns `null` when no rich body
+     * applies (no refs, or `richZones` not set).
+     */
+    private pickRichZone;
+}
+/**
+ * Walk the paginator's output back-to-front, collapsing trailing pages
+ * whose blocks are all visually empty into the previous page.
+ *
+ * "Visually empty" = an empty paragraph: a `<p>` (or list-item `<li>`)
+ * with no text content and no embedded image / table / break. We keep
+ * the empty blocks (round-trip fidelity demands every paragraph mark
+ * stays in the AST) — we just stop reserving a fresh page for them.
+ *
+ * Stops collapsing the moment a page contains any non-empty block, so
+ * a real "last page with just a signature line" still gets its own
+ * page. Idempotent; safe to call on a single-page result.
+ */
+/**
+ * Walk paginator output forward, absorbing pages whose total content
+ * height is ≤ 15% of `budgetPx` (the page-content budget) into the
+ * previous page. These tiny tail-pages are paginator widows — usually
+ * a 1-line overflow or an LRPB-induced sub-section that didn't have
+ * room. Both Word and LO tolerate a bit of bottom-margin spill in
+ * exchange for not spending an entire fresh page on the runt.
+ *
+ * Safety: only absorbs pages whose content height is smaller than the
+ * previous page's slack PLUS the widow tolerance (~20% of budget).
+ * If absorbing would visibly push content far past the page bottom,
+ * we leave the runt page alone — better an underfilled page than
+ * unreadable overflow.
+ *
+ * Run AFTER `collapseTrailingEmptyPages` so trailing whitespace is
+ * already merged and we're working on the real content layout.
+ */
+export declare function collapseUnderfilledPages(pages: readonly HTMLElement[][], budgetPx: number): HTMLElement[][];
+export declare function collapseTrailingEmptyPages(pages: readonly HTMLElement[][]): HTMLElement[][];

package/dist/plugin.d.ts

@@ -0,0 +1,24 @@
+import { Editor } from './editor';
+import { Viewport } from './embed/viewport';
+import { Sobree } from './sobree';
+export interface PluginContext {
+    /** The framework-free editor kernel. */
+    editor: Editor;
+    /** The Sobree façade — paper stack, page setup, mode, headers/footers. */
+    sobree: Sobree;
+    /** The viewport — pannable / zoomable stage. */
+    viewport: Viewport;
+    /** The element `createSobree()` was mounted into. */
+    host: HTMLElement;
+}
+export interface SobreePluginInstance {
+    /** Tear down everything `setup` allocated. Called on createSobree's
+     *  destroy, in reverse-of-setup order. */
+    destroy(): void;
+}
+export interface SobreePlugin {
+    /** Diagnostic name surfaced in setup-failure logs. Optional. */
+    name?: string;
+    /** Mount the plugin against the editor surface. Returns a destroyer. */
+    setup(ctx: PluginContext): SobreePluginInstance;
+}

package/dist/plugins/marks.d.ts

@@ -0,0 +1,49 @@
+import { Range as ApiRange } from '../doc/api';
+import { RunProperties } from '../doc/types';
+import { Editor, WrapTag } from '../editor';
+/**
+ * Mark toggle helpers — shared by the floating toolbar's mark buttons
+ * and the keyboard plugin (Ctrl+B / I / U / …).
+ *
+ * "Mark" = a boolean / enum run property that maps 1:1 to a `wrapRange`
+ * tag: `strong`, `em`, `u`, `s`, `sup`, `sub`. (`mark`/highlight is
+ * passthrough — not a toggle, since highlight is colour-valued.)
+ */
+/** Tag → run property key for toggle detection. */
+export declare const MARK_PROP: Record<string, keyof RunProperties>;
+/** Expected "on" value for each mark. */
+export declare const MARK_ON: Record<string, RunProperties[keyof RunProperties]>;
+export type ToggleableMark = "strong" | "em" | "u" | "s" | "sup" | "sub";
+/**
+ * Standard mark commands registered on every Editor's command bus.
+ * Owned by the marks module so a single source of truth backs the
+ * keyboard plugin (`@sobree/keyboard`), the floating toolbar
+ * (`@sobree/block-tools`), and any custom UI / agent dispatch.
+ */
+export interface MarkCommandDef {
+    name: string;
+    title: string;
+    tag: ToggleableMark;
+}
+export declare const MARK_COMMAND_DEFS: readonly MarkCommandDef[];
+/**
+ * Apply or clear a mark across `range` based on its current state. If
+ * every text run in the range already carries the mark's "on" value,
+ * the call clears it; otherwise the mark is applied.
+ *
+ * `mark` (highlight) is delegated straight to `wrapRange` — it's not a
+ * toggle since highlight is a colour, not a boolean.
+ */
+export declare function toggleMark(editor: Editor, range: ApiRange, tag: WrapTag): void;
+/**
+ * True when every non-empty text run inside `range` has the mark's "on"
+ * value. Walks hyperlink children. Multi-block ranges always read as
+ * inactive so a click sets the mark before clearing it.
+ */
+export declare function isMarkActive(editor: Editor, range: ApiRange, tag: string): boolean;
+/**
+ * Pick the right range to operate on: live DOM selection if any,
+ * otherwise the full extent of the block at the caret. Matches the
+ * "press Ctrl+B with caret only → bold the whole paragraph" UX.
+ */
+export declare function rangeAtSelection(editor: Editor): ApiRange | null;

package/dist/plugins/sections.d.ts

@@ -0,0 +1,15 @@
+import { Editor } from '../editor';
+/**
+ * Section commands plugin.
+ *
+ * Registers `section.insertBreakAfter` — inserts a `SectionBreak` block
+ * after the caret's current block. The new section inherits the
+ * previous section's properties (cloned so later edits don't bleed
+ * back) so visual continuity is preserved until the user edits the
+ * new section in Page Setup.
+ *
+ * The keyboard plugin's Ctrl+Shift+Enter dispatches this command, the
+ * change-type popover does too, and a future Insert menu would as well
+ * — same dispatch path for every trigger.
+ */
+export declare function attachSections(editor: Editor): () => void;

package/dist/presence/attach.d.ts

@@ -0,0 +1,48 @@
+import { Editor } from '../editor';
+import { AwarenessLike } from './awareness';
+import { PresenceState, PresenceUser } from './state';
+export interface AttachPresenceOptions {
+    /** This peer's identity. Published in the local state's `user` field. */
+    user: PresenceUser;
+    /**
+     * Called whenever any peer's presence (including this one) changes.
+     * The map is `clientID → PresenceState` for every peer currently
+     * publishing valid Sobree presence. The local peer's clientID
+     * (matches `awareness.clientID` / `editor.ydoc.clientID`) is
+     * included so callers can render their own caret too if they want.
+     */
+    onChange?: (peers: Map<number, PresenceState>) => void;
+    /**
+     * Default to `true` — publish the local user's selection on every
+     * `editor.on("selection")` event. Pass `false` if the caller wants
+     * to manage own-selection publishing manually.
+     */
+    publishOwnSelection?: boolean;
+}
+export interface PresenceHandle {
+    /** Snapshot of every peer's current state, keyed by clientID. */
+    getPeers(): Map<number, PresenceState>;
+    /**
+     * Push a manual state update. Useful when the local user changes
+     * name / color, or to explicitly clear the selection on focus loss.
+     */
+    setLocalState(state: Partial<PresenceState>): void;
+    /** Tear down: unsubscribe from awareness + editor events. Clears
+     *  the local published state so peers see the user leave. */
+    destroy(): void;
+}
+/**
+ * Wire an `Awareness` instance into the editor.
+ *
+ * - Publishes the local user's `user` + `selection` state on every
+ *   selection change.
+ * - Subscribes to remote peers' state via awareness `"change"`
+ *   events; surfaces them via `onChange(peers)` and `getPeers()`.
+ *
+ * Does NOT render an overlay — pass the peers to your own renderer,
+ * or wire `attachPresenceOverlay` from this package for the default
+ * caret + range-highlight rendering.
+ *
+ * Returns a `PresenceHandle` with manual-update and teardown.
+ */
+export declare function attachPresence(editor: Editor, awareness: AwarenessLike, opts: AttachPresenceOptions): PresenceHandle;

package/dist/presence/awareness.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal awareness interface — a structural subset of
+ * `y-protocols/awareness`'s `Awareness` class. We don't depend on
+ * `y-protocols` from `@sobree/core` (it's an optional concern); the
+ * interface here is structurally compatible so an `Awareness`
+ * instance passes typecheck without any glue.
+ *
+ * The shape:
+ *
+ *   - `clientID` — the local peer's id (matches `ydoc.clientID`)
+ *   - `setLocalState(state | null)` — publish your own state
+ *   - `setLocalStateField(field, value)` — patch one field
+ *   - `getStates()` — read every peer's state as `Map<clientID, state>`
+ *   - `on("change", cb) / off("change", cb)` — subscribe to changes
+ */
+export interface AwarenessLike {
+    readonly clientID: number;
+    setLocalState(state: Record<string, unknown> | null): void;
+    setLocalStateField(field: string, value: unknown): void;
+    getStates(): Map<number, Record<string, unknown>>;
+    on(event: "change" | "update", cb: (changes: AwarenessChanges, origin: unknown) => void): void;
+    off(event: "change" | "update", cb: (changes: AwarenessChanges, origin: unknown) => void): void;
+}
+export interface AwarenessChanges {
+    added: number[];
+    updated: number[];
+    removed: number[];
+}

package/dist/presence/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Presence — remote peer cursors and selection highlights.
+ *
+ * Builds on the Y.Doc backing in `@sobree/core`. Pass an `Awareness`
+ * instance (from `y-protocols/awareness`, surfaced via
+ * `@sobree/collab-providers` handles) and a user identity; pluck
+ * remote peers via `getPeers()` or render the default overlay.
+ *
+ * See `concepts/architecture` ("Y.Doc store") for the bigger picture
+ * and `api/create-sobree` ("Y.Doc + collaboration") for the
+ * multi-phase roadmap.
+ */
+export { attachPresence } from './attach';
+export type { AttachPresenceOptions, PresenceHandle, } from './attach';
+export { attachPresenceOverlay } from './overlay';
+export type { AttachPresenceOverlayOptions, PresenceOverlayHandle, } from './overlay';
+export { isPresenceState, presenceSelectionFromEditor, } from './state';
+export type { PresenceState, PresenceSelection, PresenceUser, } from './state';
+export type { AwarenessLike, AwarenessChanges } from './awareness';

package/dist/presence/overlay.d.ts

@@ -0,0 +1,28 @@
+import { Editor } from '../editor';
+import { AwarenessLike } from './awareness';
+import { PresenceHandle, AttachPresenceOptions } from './attach';
+export interface AttachPresenceOverlayOptions extends AttachPresenceOptions {
+    /**
+     * Element to render the overlay into. Should be an ancestor of the
+     * paper stack and `position: relative` (or `position: absolute`).
+     * The factory adds `position: relative` if `static`. Most embedders
+     * pass `createSobree(...).viewport.slot`.
+     */
+    container: HTMLElement;
+    /**
+     * Element whose `data-block-id` lookup resolves to block DOM
+     * elements. Default: `container`. Pass a different host if your
+     * paper stack is layered separately.
+     */
+    blockHost?: HTMLElement;
+}
+export interface PresenceOverlayHandle {
+    /** Underlying presence handle — read peers, push manual updates. */
+    readonly presence: PresenceHandle;
+    /** Force re-render (e.g. after a layout-affecting change the
+     *  overlay didn't observe directly). */
+    refresh(): void;
+    /** Tear down DOM + listeners. */
+    destroy(): void;
+}
+export declare function attachPresenceOverlay(editor: Editor, awareness: AwarenessLike, opts: AttachPresenceOverlayOptions): PresenceOverlayHandle;

package/dist/presence/state.d.ts

@@ -0,0 +1,36 @@
+import { Selection as EditorSelection } from '../doc/api';
+/** Per-peer state published to other peers via Yjs awareness. */
+export interface PresenceState {
+    user: PresenceUser;
+    /**
+     * Where this peer's cursor / range sits. `null` if focus left the
+     * editor. Position is identified by `blockId` (stable across the
+     * Y.Doc — see `BlockRegistry`) + character offsets, so it survives
+     * re-pagination and structural mutations.
+     */
+    selection: PresenceSelection | null;
+}
+export interface PresenceUser {
+    /** Stable peer id (a UUID, an auth user id, etc). Random per page-load
+     *  is fine if you don't have auth. */
+    id: string;
+    /** Display name for overlays / tooltips. */
+    name: string;
+    /** CSS color for the caret / range highlight (e.g. "#f59e0b"). */
+    color: string;
+}
+export interface PresenceSelection {
+    /** BlockRegistry id of the focused block. Both `anchor` and `focus`
+     *  point inside this block (cross-block selections are clipped to
+     *  the focus block for the overlay). */
+    blockId: string;
+    /** Caret position when anchor === focus; range start otherwise. */
+    anchor: number;
+    /** Caret position when anchor === focus; range end otherwise. */
+    focus: number;
+}
+/** Convenience view: the editor's live `Selection` collapsed to a
+ *  `PresenceSelection` referencing the focused block by id. */
+export declare function presenceSelectionFromEditor(sel: EditorSelection): PresenceSelection | null;
+/** Type guard — narrows an unknown awareness state value to PresenceState. */
+export declare function isPresenceState(value: unknown): value is PresenceState;