@sobree/core 0.1.9 → 0.1.11

package/dist/paperStack/footnoteFlow.d.ts

@@ -0,0 +1,26 @@
+import { Paper } from './paper';
+/**
+ * For each paper, find the footnote refs that landed on it after
+ * pagination and populate that paper's `.paper-footnotes` zone with the
+ * cited bodies — 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 here for footnote-zone height; that
+ * reservation is `footnotePageHeights`'s job, fed back into the next
+ * pagination pass.
+ */
+export declare function distributeFootnotes(papers: readonly Paper[]): void;
+/**
+ * Per-page body budget after subtracting each page's footnote-zone
+ * height — entry `i` is page `i`'s budget. Trailing entries equal to the
+ * baseline are trimmed so two arrays differing only by an unrelated tail
+ * compare equal (keeps the repaginate loop's `arraysEqual` honest).
+ */
+export declare function footnotePageHeights(papers: readonly Paper[], baselineBudgetPx: number): number[];

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

@@ -0,0 +1,41 @@
+/**
+ * Unequal multi-column flow.
+ *
+ * CSS multi-column only produces equal columns, so a Word section with
+ * explicit per-column widths (`<w:cols w:equalWidth="0">`) can't be laid
+ * out by CSS. The renderer (`openColumnContainerIfNeeded`) emits a flat
+ * `.sobree-cols-unequal` wrapper stamped with the column geometry; this
+ * pass — run after layout, when heights are measurable — restructures it
+ * into explicit-width column tracks and flows the section's blocks across
+ * them.
+ *
+ * Fill model: BALANCE, not fill-to-page. Word balances a multi-column
+ * section that has no explicit column break and fits one page — it
+ * equalises the column heights rather than packing the first column to
+ * the page bottom and spilling the remainder. (CSS `column-count` does
+ * the same for the equal-width path; this is the unequal-width analogue.)
+ * A naive "fill column 1 to the page height, then spill" instead packs
+ * the wide column nearly full before the narrow one starts, and — worse —
+ * the page-height threshold sits far above the actual content, so a few
+ * pixels of font-metric drift between renders (web fonts loaded vs not)
+ * flip blocks across the boundary. Balancing both matches Word and is
+ * stable: the split lands at the block boundary that minimises the
+ * tallest column, which block granularity pins in place.
+ *
+ * Scope: single-page column sections (a section whose content fits one
+ * page), which matches the equal-column path's current capability — that
+ * wraps a section's content in one monolithic block the paginator places
+ * on a single page. Blocks are moved whole (a paragraph is not split
+ * across a column boundary); that's faithful for the templates this
+ * targets, where columns break at block boundaries. `colHeightPx` is the
+ * page content height — a hard ceiling no column may exceed (content
+ * taller than that genuinely overflows the page, out of this scope).
+ * Idempotent: re-running re-flattens and re-fills, so the iterative
+ * paginate loop can call it each pass.
+ */
+/**
+ * Flow every unequal-column section under `root` into its width tracks.
+ * `colHeightPx` is the page content-height budget (the height each
+ * column may fill before spilling to the next).
+ */
+export declare function flowUnequalColumnSections(root: HTMLElement, colHeightPx: number): void;

package/dist/paperStack/paper.d.ts

@@ -1,7 +1,7 @@
-import { PageSetup } from './pageSetup';
+import { AnchoredFrame, SectionProperties } from '../doc/types';
 import { AnchorLayerContext } from '../editor/view/docRenderer/anchorLayer';
+import { PageSetup } from './pageSetup';
 import { ZoneRenderContext } from './paperZone';
-import { AnchoredFrame, SectionProperties } from '../doc/types';
 export type { ZoneRenderContext } from './paperZone';
 /**
  * A single paper — exactly one page. Fixed width and height from the page

package/dist/paperStack/paperStack.d.ts

@@ -1,5 +1,5 @@
-import { PageSetup } from './pageSetup';
 import { AnchoredFrame, Block, NamedStyle, NumberingDefinition, SectionProperties } from '../doc/types';
+import { PageSetup } from './pageSetup';
 /**
  * Sourced from `SobreeDocument`: the rich AST + the dependencies
  * `renderBlocks` needs (numbering, named styles, embedded media bytes).
@@ -120,26 +120,6 @@ export declare class PaperStack {
      * 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
@@ -154,7 +134,6 @@ export declare class PaperStack {
      * 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
@@ -223,6 +202,7 @@ export declare class PaperStack {
      */
     private pickRichZone;
 }
+/** Parse "sobree-footnote-7" → 7; returns null for anything else. */
 /**
  * Walk the paginator's output back-to-front, collapsing trailing pages
  * whose blocks are all visually empty into the previous page.

package/dist/paperStack/paperZone.d.ts

@@ -1,5 +1,5 @@
-import { AnchorLayerContext } from '../editor/view/docRenderer/anchorLayer';
 import { AnchoredFrame, Block, NamedStyle, NumberingDefinition } from '../doc/types';
+import { AnchorLayerContext } from '../editor/view/docRenderer/anchorLayer';
 /**
  * Everything a header/footer zone needs to render its FLOW content. The
  * floating layer (anchored frames) is painted separately via

package/dist/presence/overlay.d.ts

@@ -1,6 +1,6 @@
 import { Editor } from '../editor';
+import { AttachPresenceOptions, PresenceHandle } from './attach';
 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

package/dist/sobree.d.ts

@@ -1,6 +1,6 @@
-import { PageSetup } from './paperStack/pageSetup';
-import { Editor, OutlineItem, TrackChangesState } from './editor';
 import { SobreeDocument } from './doc/types';
+import { Editor, OutlineItem, TrackChangesState } from './editor';
+import { PageSetup } from './paperStack/pageSetup';
 export type SobreeMode = "edit" | "read";
 export type SobreeEvent = "change" | "paginate" | "setup" | "mode-change" | "track-changes-change" | "docx:import" | "docx:export";
 export interface SobreeEventPayload {
@@ -61,6 +61,13 @@ export interface SobreeOptions {
      * `sobree.setTrackChanges(...)`.
      */
     trackChanges?: TrackChangesState;
+    /**
+     * Show a small, non-interactive `@sobree/core` version badge at the
+     * bottom-centre of the screen. Off by default. A debug aid for
+     * confirming which renderer build is live (e.g. past a stale cache
+     * after a deploy) — it has no other behaviour.
+     */
+    versionBadge?: boolean;
 }
 /**
  * Top-level embeddable product surface. Composes a framework-free `Editor`
@@ -75,6 +82,11 @@ export declare class Sobree {
     private readonly stack;
     private setup;
     private mode;
+    /** Guards a single in-flight `document.fonts.ready` repagination so
+     *  repeated triggers while fonts load coalesce into one re-run. */
+    private fontSettleScheduled;
+    /** Removes the version badge (when `versionBadge` is on). `null` otherwise. */
+    private versionBadgeTeardown;
     private readonly listeners;
     private readonly detachPaginate;
     private readonly detachChange;
@@ -136,6 +148,24 @@ export declare class Sobree {
      * `requestAnimationFrame` after the container is in the DOM).
      */
     repaginate(): void;
+    /**
+     * Repaginate, unless a header/footer zone is being edited in place
+     * (live zone edits manage their own reflow). Also schedules a re-run
+     * once any still-loading document fonts settle.
+     */
+    private paginateUnlessZoneEditing;
+    /**
+     * Pagination and column balancing measure laid-out text, so they depend
+     * on the actual font glyph metrics. A document's embedded fonts load
+     * asynchronously — a pass that runs before they arrive (notably on a
+     * cold reload, or right after `loadDocx` registers new faces) measures
+     * with FALLBACK metrics, which can mis-balance columns or mis-place page
+     * breaks. When fonts are still loading, re-run once they settle so the
+     * final layout reflects real glyphs. No-op when nothing is pending
+     * (the common warm-cache / steady-editing case), and a single in-flight
+     * re-run is coalesced so rapid changes during a load don't pile up.
+     */
+    private repaginateWhenFontsSettle;
     /** Delegate to `editor.getOutline()`. */
     getOutline(): OutlineItem[];
     /** Current mode. Default is `"edit"`. */

package/dist/tokens.css

@@ -37,15 +37,15 @@
 
 :root {
   /* Primary — Sobree Amber. */
-  --sobree-50:  #fdf6ee;
+  --sobree-50: #fdf6ee;
   --sobree-100: #f9e6d0;
   --sobree-500: #c96f22;
   --sobree-600: #b2591a;
 
   /* Neutrals — warm ink, not gray. */
-  --ink-0:   #ffffff;
-  --ink-25:  #fbfaf7;
-  --ink-50:  #f6f4ef;
+  --ink-0: #ffffff;
+  --ink-25: #fbfaf7;
+  --ink-50: #f6f4ef;
   --ink-100: #eceae3;
   --ink-200: #dedbd0;
   --ink-300: #c4bfaf;
@@ -57,20 +57,20 @@
   --ink-900: #14130f;
 
   /* Semantic tokens — what components reference. */
-  --bg:            var(--ink-25);
-  --bg-elevated:   var(--ink-0);
-  --bg-subtle:     var(--ink-50);
-  --bg-hover:      var(--ink-100);
-  --fg:            var(--ink-800);
-  --fg-strong:     var(--ink-900);
-  --fg-muted:      var(--ink-600);
-  --fg-subtle:     var(--ink-500);
+  --bg: var(--ink-25);
+  --bg-elevated: var(--ink-0);
+  --bg-subtle: var(--ink-50);
+  --bg-hover: var(--ink-100);
+  --fg: var(--ink-800);
+  --fg-strong: var(--ink-900);
+  --fg-muted: var(--ink-600);
+  --fg-subtle: var(--ink-500);
   --fg-on-primary: var(--ink-0);
-  --border:        var(--ink-200);
+  --border: var(--ink-200);
   --border-strong: var(--ink-300);
-  --primary:       var(--sobree-500);
+  --primary: var(--sobree-500);
   --primary-hover: var(--sobree-600);
-  --primary-soft:  var(--sobree-50);
+  --primary-soft: var(--sobree-50);
 
   /* Radii. */
   --radius-xs: 2px;
@@ -89,9 +89,9 @@
 
   /* Motion. */
   --ease-standard: cubic-bezier(0.2, 0, 0, 1);
-  --dur-fast:   120ms;
-  --dur-base:   180ms;
-  --dur-slow:   280ms;
+  --dur-fast: 120ms;
+  --dur-base: 180ms;
+  --dur-slow: 280ms;
 
   /* Spacing — 4px base. */
   --space-1: 4px;
@@ -136,9 +136,8 @@
   --sobree-revision-tint: 8%;
 
   /* Comment styling. */
-  --sobree-comment-range-bg:     rgba(255, 217, 0, 0.25);
+  --sobree-comment-range-bg: rgba(255, 217, 0, 0.25);
   --sobree-comment-range-border: rgba(180, 130, 0, 0.5);
-  --sobree-comment-accent:       #f59e0b; /* card rule when author colour absent */
-  --sobree-comment-resolved:     #16a34a; /* resolved-thread green */
+  --sobree-comment-accent: #f59e0b; /* card rule when author colour absent */
+  --sobree-comment-resolved: #16a34a; /* resolved-thread green */
 }
-

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The published `@sobree/core` version, baked in from `package.json` at
+ * build time. Useful for confirming which renderer build is actually
+ * running — e.g. past a stale CDN / browser cache after a deploy.
+ */
+export declare const VERSION: string;

package/dist/versionBadge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A fixed, non-interactive badge showing the `@sobree/core` version.
+ *
+ * Debug aid only — off by default (`SobreeOptions.versionBadge`). It lets
+ * you confirm which renderer build is actually live, e.g. after a deploy
+ * past a stale CDN / browser cache. No interactivity, no layout impact.
+ *
+ * Mounted on `document.body`, NOT the editor container: the viewport
+ * applies a zoom `transform` to its slot, which would both scale the
+ * badge and become its containing block (breaking `position: fixed`).
+ * Body-mounting keeps it screen-bottom-centre, unscaled, always visible.
+ */
+/** Mount the version badge and return a teardown that removes it. */
+export declare function mountVersionBadge(doc?: Document): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sobree/core",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "publishConfig": {
     "access": "public"
   },