@sobree/core 0.1.0

package/dist/markdown/parse.d.ts

@@ -0,0 +1,6 @@
+import { SobreeDocument } from '../doc/types';
+/**
+ * Parse a Markdown string into a `SobreeDocument`. Always returns a
+ * valid document; unsupported syntax falls through as plain text.
+ */
+export declare function parseMarkdown(md: string): SobreeDocument;

package/dist/pagination/cost.d.ts

@@ -0,0 +1,32 @@
+import { Box, Candidate, Item, ResolvedConfig } from './types';
+/**
+ * Score a candidate break. Lower is better.
+ *
+ *   totalCost = underfullWeight * leftover²
+ *             + own penalty cost
+ *             + widow/orphan penalty
+ *             + keep-with-next penalty
+ *             + keep-together penalty
+ *
+ * `start` is the index of the first item on the current page — needed so we
+ * only count paragraph lines that live on this page (not on earlier ones).
+ */
+export declare function scoreBreak(items: Item[], start: number, c: Candidate, cfg: ResolvedConfig): number;
+/** Penalty for breaking inside a paragraph and leaving a widow or orphan. */
+export declare function widowOrphanPenalty(items: Item[], start: number, c: Candidate, cfg: ResolvedConfig): number;
+/**
+ * +Infinity if the break is between a keepWithNext paragraph and whatever
+ * follows. The only case we *don't* forbid is when the break is between two
+ * lines of the same paragraph (widow/orphan's concern, not keep-with-next's).
+ */
+export declare function keepWithNextPenalty(items: Item[], c: Candidate): number;
+/** Penalty for breaking inside a keepTogether paragraph. */
+export declare function keepTogetherPenalty(items: Item[], c: Candidate, cfg: ResolvedConfig): number;
+export declare function nearestBoxBefore(items: Item[], idxExclusive: number): Box | null;
+export declare function nearestBoxAfter(items: Item[], idxInclusive: number): Box | null;
+export declare function countParagraphLinesOnPageBefore(items: Item[], start: number, pageEnd: number, pid: string): number;
+export declare function countParagraphLinesOnNextPage(items: Item[], nextStart: number, pid: string): number;
+/** Sum of box + inter-line glue heights for the paragraph beginning at startIdx. */
+export declare function sumParagraphHeight(items: Item[], startIdx: number): number;
+export declare function isGlueBetweenBoxes(items: Item[], idx: number): boolean;
+export declare function isGlueInsideKeepTogether(items: Item[], idx: number): boolean;

package/dist/pagination/index.d.ts

@@ -0,0 +1,2 @@
+export { paginate } from './paginate';
+export type { Box, Config, Glue, Item, Page, Penalty, ResolvedConfig, } from './types';

package/dist/pagination/paginate.d.ts

@@ -0,0 +1,10 @@
+import { Config, Item, Page } from './types';
+/**
+ * Greedy one-pass paginator. See README.md for the full cost model.
+ *
+ *   Walk the item stream, accumulating page height and a list of candidate
+ *   break positions. When the next item overflows — or a forced penalty
+ *   appears — pick the candidate that minimises totalCost (see scoreBreak),
+ *   emit the page, and continue from the chosen break.
+ */
+export declare function paginate(items: Item[], config: Config): Page[];

package/dist/pagination/postConditions.d.ts

@@ -0,0 +1,10 @@
+import { Candidate, Item, ResolvedConfig } from './types';
+/**
+ * If the chosen break still violates widow/orphan (despite the penalty in
+ * scoring), walk the candidate list backward and pick the nearest earlier
+ * candidate that doesn't violate — "back off the break by one line" in the
+ * spec — effectively one paragraph line moves to the next page.
+ *
+ * Returns the original `best` if no earlier candidate avoids the violation.
+ */
+export declare function backOffIfViolates(items: Item[], start: number, best: Candidate, candidates: Candidate[], cfg: ResolvedConfig): Candidate;

package/dist/pagination/types.d.ts

@@ -0,0 +1,94 @@
+/** A single line or image-like unit. Contributes height. */
+export interface Box {
+    type: "box";
+    height: number;
+    /** Identifier shared by all lines of the same paragraph. */
+    paragraphId?: string;
+    isFirstLineOfParagraph?: boolean;
+    isLastLineOfParagraph?: boolean;
+    /** If true, the box is never split across a page break. */
+    monolithic?: boolean;
+    /** Paragraph-level: this paragraph must stay adjacent to the next. */
+    keepWithNext?: boolean;
+    /** Paragraph-level: all lines of this paragraph must fit on one page. */
+    keepTogether?: boolean;
+}
+/** Whitespace. Discarded at page edges when it ends up there. */
+export interface Glue {
+    type: "glue";
+    height: number;
+}
+/**
+ * A break point annotation with a finite cost, or a forced break
+ * (-Infinity), or a forbidden break (+Infinity).
+ */
+export interface Penalty {
+    type: "penalty";
+    cost: number;
+}
+export type Item = Box | Glue | Penalty;
+export interface Config {
+    /** Default page height in px. Used for any page index not covered
+     *  by `pageHeights`. */
+    pageHeight: number;
+    /**
+     * Per-page height overrides. Entry `i` is the budget for page index
+     * `i`; missing/undefined entries fall back to `pageHeight`. Lets
+     * callers shrink the body budget on specific pages (e.g. pages with
+     * footnote zones eating space at the bottom) without penalising
+     * pages that don't need it.
+     */
+    pageHeights?: readonly number[];
+    /** Minimum lines of a paragraph on the new page. Default 2. */
+    widows?: number;
+    /** Minimum lines of a paragraph on the current page. Default 2. */
+    orphans?: number;
+    /** Multiplier for underfull penalty (leftover²). Default 1.0. */
+    underfullWeight?: number;
+    /** Added when a candidate break would leave a widow or orphan. Default 10000. */
+    widowOrphanPenalty?: number;
+    /** Added to breaks inside keepTogether ranges; used for keep-with-next. Default 10000. */
+    keepPenalty?: number;
+}
+export interface ResolvedConfig {
+    pageHeight: number;
+    pageHeights?: readonly number[];
+    widows: number;
+    orphans: number;
+    underfullWeight: number;
+    widowOrphanPenalty: number;
+    keepPenalty: number;
+}
+export interface Page {
+    items: Item[];
+    /** Total box + glue height, excluding trailing glue. */
+    usedHeight: number;
+    /** Cost of the chosen break ending this page; 0 for forced / end-of-stream. */
+    cost: number;
+}
+/**
+ * Candidate break position.
+ *
+ * `pageEnd` is the exclusive upper bound of the current page's items — on a
+ * glue break the glue is INCLUDED (trailing glue stays on the current page
+ * for round-tripping), so pageEnd = glueIdx + 1. On a penalty break the
+ * penalty is EXCLUDED (consumed), so pageEnd = penaltyIdx.
+ *
+ * `nextStart` is the first item of the next page. On a penalty break it is
+ * penaltyIdx + 1 (the penalty is consumed). On a glue break it equals
+ * pageEnd.
+ *
+ * `heightAt` is the accumulated page height just *before* the candidate item
+ * — glue is not counted against the page's useful height.
+ */
+export interface Candidate {
+    pageEnd: number;
+    nextStart: number;
+    heightAt: number;
+    ownCost: number;
+}
+export declare const DEFAULTS: Omit<ResolvedConfig, "pageHeight">;
+export declare function resolveConfig(cfg: Config): ResolvedConfig;
+/** Effective page budget for `pageIdx` — per-page override if present,
+ *  global `pageHeight` otherwise. */
+export declare function pageHeightAt(cfg: ResolvedConfig, pageIdx: number): number;

package/dist/paperStack/pageSetup.d.ts

@@ -0,0 +1,42 @@
+export type PageSizeKey = "A3" | "A4" | "A5" | "B5" | "Letter" | "Legal" | "Tabloid";
+export interface PageSizeMM {
+    width: number;
+    height: number;
+}
+export declare const PAGE_SIZES: Record<PageSizeKey, PageSizeMM>;
+export type Orientation = "portrait" | "landscape";
+export interface Margins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface PageZoneText {
+    default: string;
+    first: string;
+    last: string;
+    differentFirst: boolean;
+    differentLast: boolean;
+}
+/** Vertical alignment of body content on every page — OOXML `<w:vAlign>`. */
+export type VerticalAlign = "top" | "center" | "bottom" | "both";
+export interface PageSetup {
+    size: PageSizeKey;
+    orientation: Orientation;
+    margins: Margins;
+    header: PageZoneText;
+    footer: PageZoneText;
+    /** Section-level vertical alignment. Default `"top"`. */
+    verticalAlign: VerticalAlign;
+}
+export declare const DEFAULT_PAGE_SETUP: PageSetup;
+export declare function resolvedDimensions(setup: PageSetup): {
+    widthMM: number;
+    heightMM: number;
+};
+export declare function substituteVariables(template: string, ctx: {
+    page: number;
+    pages: number;
+}): string;
+/** Pick the raw zone template for a given page, honouring first/last overrides. */
+export declare function zoneTemplateFor(zone: PageZoneText, page: number, pages: number): string;

package/dist/paperStack/paginationAdapter/buildItems.d.ts

@@ -0,0 +1,19 @@
+import { DomItem } from './types';
+/**
+ * Convert a flat list of top-level block elements into an Item stream for
+ * the pagination engine.
+ *
+ * Per-block handling:
+ *   - `.page-break` / `[data-page-break]` → Penalty(-Infinity) + zero-height Box
+ *     (element still lands at the top of the next page for round-tripping).
+ *   - `<figure>` / `.keep-together` / `[data-keep-together]` → monolithic Box
+ *     (whole block moves together; doesn't split).
+ *   - `<table>`, `<pre>` → monolithic Box.
+ *   - h1–h6 → Box with `keepWithNext: true`.
+ *   - `<p>` with ≥2 line boxes → one Box per line (shared paragraphId,
+ *     first/last flags set) so widow/orphan can act per line.
+ *   - Otherwise → one Box with the element's measured height.
+ *
+ * Inter-block glue(0) makes every inter-block position a candidate break.
+ */
+export declare function buildItems(blocks: HTMLElement[]): DomItem[];

package/dist/paperStack/paginationAdapter/distribute.d.ts

@@ -0,0 +1,23 @@
+import { Page } from '../../pagination/types';
+/**
+ * Turn the paginator's `Page[]` into a per-page array of DOM elements.
+ *
+ * Two flavours of split:
+ *
+ *   - **Multi-line `<p>` straddling a page boundary**: split the `<p>`
+ *     at the character offset of the first line on the later page.
+ *     Original keeps the head fragment; a clone (same tag, attributes
+ *     preserved, data-pag-continuation stamped) holds the tail.
+ *   - **Multi-line `<li>` straddling a page boundary**: same machinery
+ *     — `<li>` is treated like `<p>` by `buildItems`, so the per-line
+ *     boxes route through `splitParagraphAcrossPages` too. Continuation
+ *     `<li>` fragments are tagged so CSS can hide their list marker.
+ *
+ * On top of per-element splits, `<li>` elements need re-wrapping into
+ * per-page `<ol>` / `<ul>` clones (you can't have a bare `<li>` at
+ * paper-content level — its marker won't render). The third pass
+ * groups consecutive same-source LIs into per-page list-container
+ * clones with the right `start` attribute so numbering continues
+ * across page breaks.
+ */
+export declare function distributePages(pages: Page[]): HTMLElement[][];

package/dist/paperStack/paginationAdapter/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DOM → pagination-engine adapter for PaperStack.
+ *
+ *   1. `buildItems` walks the blocks and emits the Item stream — one Box
+ *      per block (or one per paragraph line), plus penalties for page-break
+ *      markers and monolithic flags for figures / keep-together groups.
+ *   2. `paginate` (the pure engine in `src/pagination`) produces Pages.
+ *   3. `distributePages` turns Pages into a per-page list of DOM elements,
+ *      physically splitting paragraphs that straddle page boundaries.
+ *
+ * Features honoured:
+ *   - Widow/orphan at the line level for `<p>` elements.
+ *   - Keep-with-next for headings (h1–h6).
+ *   - Keep-together for `<figure>`, `.keep-together`, `[data-keep-together]`.
+ *   - Forced page breaks for `.page-break` / `[data-page-break]` markers.
+ *   - Tables and code blocks remain monolithic.
+ */
+export declare function paginateBlocks(blocks: HTMLElement[], pageContentHeightPx: number, pageHeightsPx?: readonly number[]): HTMLElement[][];

package/dist/paperStack/paginationAdapter/paragraphLines.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Measure the individual line boxes of a paragraph-like element using
+ * `Range.getClientRects()`. The returned metrics let the paginator treat
+ * each line as its own `Box` so widow/orphan rules can act per line.
+ *
+ * Fast path uses binary search — O(L · log N) per paragraph for L lines
+ * and N characters (versus O(N) for a per-character linear walk).
+ */
+export interface LineMetric {
+    lineIndex: number;
+    /** Natural height of the line box in CSS px. */
+    height: number;
+    /** Character offset within the element where the line starts. */
+    startCharOffset: number;
+    /** Character offset (exclusive) where the line ends. */
+    endCharOffset: number;
+}
+export declare function measureParagraphLines(el: HTMLElement): LineMetric[];
+/** Resolve a character offset (0-based, counting only text chars) to (textNode, nodeOffset). */
+export declare function nodeAtCharOffset(el: HTMLElement, charOffset: number): {
+    node: Text;
+    offset: number;
+} | null;

package/dist/paperStack/paginationAdapter/splitList.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Split an `<ol>` / `<ul>` into two sibling list elements at the given
+ * child index. The original keeps `<li>`s `[0, liIndex)`; a new sibling
+ * (same tag + cloned attributes) is inserted immediately after and
+ * receives `<li>`s `[liIndex, end)`. Returns the new (tail) element.
+ *
+ * Why this exists: paragraphs can split mid-character via
+ * `splitElementAtCharOffset`, but lists need to split at `<li>`
+ * boundaries — both because the LI is the smallest paginable unit AND
+ * because mid-LI splits would require duplicating the marker (number /
+ * bullet) which is browser-rendered.
+ *
+ * For ordered lists, the tail clone gets a `start` attribute so the
+ * second fragment continues numbering from where the first left off.
+ * `start` is computed from the head's surviving `<li>` count plus the
+ * head's own `start` attribute (defaults to 1) — handles already-split
+ * fragments correctly.
+ */
+export declare function splitListAtChild(el: HTMLElement, liIndex: number): HTMLElement;

package/dist/paperStack/paginationAdapter/splitParagraph.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Split `el` into two sibling elements at the given character offset. The
+ * original keeps [0, charOffset); a new element (same tag + attributes) is
+ * inserted immediately after and receives [charOffset, end). Returns the
+ * new (bottom) element.
+ *
+ * Uses `Range.extractContents()` to move the tail into a fragment; preserves
+ * element boundaries within the `<p>` (e.g. `<strong>`, `<code>` are cloned
+ * if the split falls mid-element).
+ */
+export declare function splitElementAtCharOffset(el: HTMLElement, charOffset: number): HTMLElement;
+/**
+ * Move a split offset backward to the nearest word boundary (whitespace) so
+ * words are never cut in half. We don't have a proper line-breaking engine,
+ * so keeping words intact is the rule.
+ *
+ * Returns 0 if no whitespace is found before `offset` (rare — long single
+ * word); callers should skip splitting in that case and let the paragraph
+ * overflow rather than break mid-word.
+ */
+export declare function snapToWordBoundary(el: HTMLElement, offset: number): number;

package/dist/paperStack/paginationAdapter/types.d.ts

@@ -0,0 +1,30 @@
+import { Box, Glue, Penalty } from '../../pagination/types';
+/**
+ * Box that carries the DOM element it came from. For multi-line paragraphs,
+ * a single `<p>` contributes multiple DomBoxes — each with the same `el` and
+ * a distinct `lineIndex`. For lists, a single `<ol>` / `<ul>` contributes
+ * one DomBox per `<li>` child, each with the same `el` and a distinct
+ * `liIndex` — the distribution step uses these to clone the parent list
+ * and move tail `<li>`s into per-page fragments, mirroring how multi-line
+ * paragraphs are split.
+ */
+export interface DomBox extends Box {
+    el: HTMLElement;
+    /** 0-based line within the paragraph, when `el` is a split paragraph. */
+    lineIndex?: number;
+    /** Total lines of the paragraph. */
+    totalLines?: number;
+    /** 0-based li index within an `<ol>` / `<ul>` parent, when `el` is the list. */
+    liIndex?: number;
+    /** Total `<li>` children in the parent list. */
+    totalLis?: number;
+    /** Source `<tr>` when this box represents a paragraph emitted by
+     *  per-paragraph row-content splitting (tall rows). `el` points at the
+     *  cell-level paragraph; `cellTr` lets `distributePages` clone the TR
+     *  per page and route the paragraph into the matching cell clone. */
+    cellTr?: HTMLElement;
+    /** Marks the FIRST box of a tall row's per-paragraph stream so distribute
+     *  can move non-dominant-cell content (labels, …) onto that fragment. */
+    isFirstParaOfRow?: boolean;
+}
+export type DomItem = DomBox | Glue | Penalty;

package/dist/paperStack/paper.d.ts

@@ -0,0 +1,107 @@
+import { PageSetup } from './pageSetup';
+import { AnchorLayerContext } from '../editor/view/docRenderer/anchorLayer';
+import { AnchoredFrame, Block, NamedStyle, NumberingDefinition, SectionProperties } from '../doc/types';
+export interface ZoneRenderContext {
+    blocks: readonly Block[];
+    numbering: readonly NumberingDefinition[];
+    styles: readonly NamedStyle[];
+    rawParts: Record<string, Uint8Array>;
+    pageNumber: number;
+    totalPages: number;
+}
+/**
+ * A single paper — exactly one page. Fixed width and height from the page
+ * setup. Has a header zone, a content area, and a footer zone. The content
+ * area is where editable blocks live (the PaperStack assigns them here).
+ *
+ * Header/footer elements are contentEditable=false; the content area inherits
+ * editability from the PaperStack root.
+ */
+export declare class Paper {
+    /**
+     * Outer row container — holds the paper card + the right-side
+     * comments sidebar. `PaperStack` appends this to its root; CSS uses
+     * flex layout so comments sit beside (not inside) the paper.
+     */
+    readonly outer: HTMLElement;
+    /** The paper card itself — sized to the page dimensions. */
+    readonly root: HTMLElement;
+    readonly content: HTMLElement;
+    /**
+     * Per-page footnote zone. Sits between body content and the footer
+     * INSIDE the paper card. Populated by `PaperStack` after pagination
+     * distributes footnote bodies to the page where their referencing
+     * `<sup>` landed. Empty zones get `is-empty` for CSS hiding.
+     */
+    readonly footnotes: HTMLElement;
+    /**
+     * Per-page floating-object overlay. Absolute-positioned children
+     * (anchored textboxes, decorative shapes, anchored pictures) live
+     * here, painted on top of `content` by the renderer's anchor-layer
+     * module. The paginator never sees these — flow content and
+     * floating content are fully decoupled.
+     */
+    readonly anchors: HTMLElement;
+    /**
+     * Per-page side gutter — sits to the RIGHT of the paper card
+     * (sibling of `root`, child of `outer`). Core leaves it empty (and
+     * `is-empty`, so it collapses); the `@sobree/review` plugin fills it
+     * with comment cards. Kept in core as a stable mount point so the
+     * `.paper-row` flex layout — which the viewport's fit-to-width
+     * depends on — doesn't shift when a plugin attaches or detaches.
+     */
+    readonly comments: HTMLElement;
+    private readonly header;
+    private readonly footer;
+    constructor(container: HTMLElement, setup: PageSetup);
+    applySetup(setup: PageSetup): void;
+    /**
+     * Apply per-section settings on top of the base PageSetup. Currently
+     * just `vAlign` — extends naturally to per-section page size, margins,
+     * column counts, etc. when those land. Idempotent; called by
+     * PaperStack after pagination distributes content.
+     */
+    applySectionOverride(section: SectionProperties): void;
+    /**
+     * Render the header zone from the rich AST. Uses the same `renderBlocks`
+     * walker as body content so drawings, formatting, hyperlinks and
+     * tables all carry through. `PAGE` / `NUMPAGES` field nodes are
+     * substituted with this paper's page number / the total count.
+     */
+    setHeaderBlocks(ctx: ZoneRenderContext): void;
+    setFooterBlocks(ctx: ZoneRenderContext): void;
+    /**
+     * When a rich header (or footer) renders taller than the page's
+     * reserved margin, push body content out of the overlap.
+     *
+     * Word's behaviour: if header content exceeds `pgMar.top`, the body
+     * yields downward. Same for footer + `pgMar.bottom`. Our paper
+     * normally sets `padding-top: var(--margin-top)`; we override here to
+     * `max(--margin-top, headerOffsetHeight)` (resp. for footer) so the
+     * body's first paragraph never sits underneath the rendered header.
+     *
+     * The override is purely visual — the paginator still uses
+     * `setup.margins.top/bottom` for its budget, so pages with very tall
+     * headers may end up packing fewer body lines than expected. That's
+     * a follow-up: feed the observed zone heights back into
+     * `pageContentHeightPx` so pagination matches Word's effective body
+     * area.
+     */
+    private applyZoneOverflowPadding;
+    /**
+     * Plain-text fallback for callers that don't have rich blocks (legacy
+     * page-setup modal templates that render to a single line of text).
+     * Mirrors what `setHeaderBlocks` would do for an "x of y"-style
+     * paragraph; kept as a separate method to keep the call sites obvious.
+     */
+    setHeaderText(text: string): void;
+    setFooterText(text: string): void;
+    /**
+     * Replace the anchor layer with frames whose anchor resolves to this
+     * page. Idempotent — the old layer is wiped before painting the new
+     * one. Pass `frames=[]` to clear the layer (sets `is-empty` so the
+     * pointer-events-blocking overlay collapses out of the way).
+     */
+    setAnchoredFrames(frames: readonly AnchoredFrame[], ctx: AnchorLayerContext): void;
+    destroy(): void;
+}