@sobree/core 0.1.1 → 0.1.3

package/dist/doc/styles.d.ts

@@ -17,3 +17,15 @@ export declare function resolveStyleCascade(styles: readonly NamedStyle[] | Sobr
     runDefaults: RunProperties;
     paragraphDefaults: ParagraphProperties;
 };
+/**
+ * Resolve a RUN character style (`<w:rStyle>`) to the run properties it
+ * contributes: its own rPr merged up its `basedOn` chain — but WITHOUT
+ * the Normal / DocDefaults anchor that `resolveStyleCascade` appends.
+ *
+ * A character style layers on top of the run's INHERITED paragraph
+ * formatting; folding the document defaults back in here would reset the
+ * run's font / size to the doc default (e.g. a colour-only "Blue" char
+ * style must not drag Times/12pt onto a Helvetica/10pt contact line). So
+ * we walk only the explicit `basedOn` chain and stop — no Normal anchor.
+ */
+export declare function resolveRunStyle(styles: readonly NamedStyle[], styleId: string): RunProperties;

package/dist/doc/types.d.ts

@@ -30,6 +30,15 @@ export interface SobreeDocument {
      * emits each body to its own OOXML part at export time.
      */
     headerFooterBodies: Record<string, Block[]>;
+    /**
+     * Floating objects that live inside a header/footer part, keyed by the
+     * SAME `HeaderFooterRef.partId` as `headerFooterBodies`. A header part
+     * is a self-contained sub-document: its flow blocks live in
+     * `headerFooterBodies[partId]`, its anchored frames here. The renderer
+     * paints these into a per-zone overlay exactly like body `anchoredFrames`.
+     * Empty/absent for the common header-without-floats case.
+     */
+    headerFooterFrames?: Record<string, AnchoredFrame[]>;
     /** Named styles (Heading1, Quote, Body Text, …) defined at the doc level. */
     styles: NamedStyle[];
     /** List/numbering definitions referenced by `Paragraph.properties.numbering`. */
@@ -129,6 +138,20 @@ export interface AnchoredFrame {
      *  floats over text and reserves nothing. Absent ⇒ unknown (treated
      *  as non-displacing). */
     wrap?: "square" | "topAndBottom" | "tight" | "through" | "none";
+    /** `wrapText` side from `<wp:wrapSquare|Tight|Through wrapText="…">` —
+     *  which sides of the frame body text flows on. Default `bothSides`.
+     *  Only meaningful for the displacing wrap modes; drives whether a
+     *  floated image goes `float: left` (text on the right) or `right`. */
+    wrapText?: "bothSides" | "left" | "right" | "largest";
+    /** Text-distance insets — `distT/B/L/R` on `<wp:anchor>`, in EMU. The
+     *  gap Word keeps between the frame and the text wrapping around it;
+     *  rendered as margins on the floated frame. */
+    textDistancesEmu?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
     /** What this frame contains. */
     content: AnchoredContent;
 }
@@ -271,6 +294,31 @@ export interface SectionBreak {
  * **Status**: type declared (Phase 1.0). Importer does not yet emit
  * this; renderer treats it as a no-op. Wiring lands in Phase 1.1-1.2.
  */
+/** One textbox shape inside an inline-frame group: its intra-group
+ *  position + size and recursive body, plus optional chrome (fill /
+ *  border / text insets) and vertical text anchor. */
+export interface InlineFrameTextbox {
+    offsetEmu: {
+        xEmu: number;
+        yEmu: number;
+    };
+    sizeEmu: {
+        wEmu: number;
+        hEmu: number;
+    };
+    body: Block[];
+    fill?: string;
+    border?: FrameBorder;
+    /** `<wps:bodyPr>` text insets (lIns/tIns/rIns/bIns) → CSS padding. */
+    padding?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
+    /** Vertical text anchor from `<wps:bodyPr anchor>`; defaults to "top". */
+    vAlign?: "top" | "center" | "bottom";
+}
 export interface InlineFrame {
     kind: "inline_frame";
     /** From the containing `<w:p>`'s `<w:pPr>`. The paginator emits a
@@ -304,36 +352,12 @@ export interface InlineFrame {
         wEmu: number;
         hEmu: number;
     };
-    /** The textbox SHAPE's intra-group position + size + body. The
-     *  renderer places `body` at the EXACT coordinates the author
-     *  intended. Optional because some drawings have only pictures /
-     *  shapes (no textbox content). */
-    textbox?: {
-        offsetEmu: {
-            xEmu: number;
-            yEmu: number;
-        };
-        sizeEmu: {
-            wEmu: number;
-            hEmu: number;
-        };
-        body: Block[];
-        fill?: string;
-        border?: FrameBorder;
-        /** `<wps:bodyPr>` text insets (lIns/tIns/rIns/bIns). The renderer
-         *  paints these as the region's CSS padding. */
-        padding?: {
-            topEmu: number;
-            rightEmu: number;
-            bottomEmu: number;
-            leftEmu: number;
-        };
-        /** Vertical text anchor from `<wps:bodyPr anchor>`. Word centers a
-         *  single heading line by sizing a short textbox and centering its
-         *  text; this carries that intent into the renderer's flex column.
-         *  Defaults to "top" when the attribute is absent. */
-        vAlign?: "top" | "center" | "bottom";
-    };
+    /** The group's textbox SHAPES, in document (child) order. Most groups
+     *  have one (a section "pill" heading: a centred line over a background
+     *  picture), but a "Project: X" entry has two — a title textbox and a
+     *  details textbox — and the renderer must show BOTH. Empty when the
+     *  group carries only pictures / shapes (no textbox content). */
+    textboxes: InlineFrameTextbox[];
     /** Decorative pictures inside the group. Each carries its own
      *  intra-group position. The renderer paints them as
      *  absolute-positioned `<img>` children of the frame wrapper,
@@ -443,10 +467,23 @@ export interface DrawingRun {
      *   - "inline"  — flows in the paragraph like a tall character.
      *   - "anchor"  — positioned absolutely (`<wp:anchor>`); `anchor`
      *                 carries the offset + frame-of-reference.
+     *   - "floatLeft" / "floatRight" — a `<wp:anchor>` image with a
+     *                 displacing wrap (square/tight/through), converted to a
+     *                 CSS float at the head of its anchor paragraph so body
+     *                 text flows around it. `floatMarginsEmu` carries the
+     *                 `distT/B/L/R` clearance.
      */
-    placement: "inline" | "anchor";
+    placement: "inline" | "anchor" | "floatLeft" | "floatRight";
     /** Set when `placement === "anchor"`. */
     anchor?: DrawingAnchor;
+    /** Set for `floatLeft` / `floatRight` — the text-clearance margins
+     *  (from the frame's `distT/B/L/R`), applied as CSS margins. */
+    floatMarginsEmu?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
     /**
      * Vertical alignment for an `inline` image relative to the text on
      * its line. Defaults to the browser baseline (image bottom on the

package/dist/docx/export/contentTypes.d.ts

@@ -4,6 +4,7 @@ declare const REL_TYPES: {
     readonly image: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
     readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
     readonly fontTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+    readonly numbering: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
     readonly font: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font";
 };
 type RelKind = keyof typeof REL_TYPES;

package/dist/docx/export/context.d.ts

@@ -13,7 +13,7 @@ export interface ExportContext {
     /** Rels to append to `word/_rels/document.xml.rels`. */
     relationships: Array<{
         id: string;
-        type: "header" | "footer" | "image" | "hyperlink" | "fontTable";
+        type: "header" | "footer" | "image" | "hyperlink" | "fontTable" | "numbering";
         target: string;
         /** External targets (URLs) need `TargetMode="External"`. */
         external?: boolean;

package/dist/docx/export/numbering.d.ts

@@ -0,0 +1,2 @@
+import { NumberingDefinition } from '../../doc/types';
+export declare function renderNumberingXml(numbering: readonly NumberingDefinition[]): string | null;

package/dist/docx/import/anchoredFrames.d.ts

@@ -1,4 +1,5 @@
 import { AnchoredFrame, Block } from '../../doc/types';
+import { ThemePalette } from '../shared/drawingColor';
 export interface AnchoredFramesContext {
     /** RelationshipId → part path lookup, e.g. `"rId4" → "media/image1.png"`. */
     rels: Map<string, string>;
@@ -20,6 +21,9 @@ export interface AnchoredFramesContext {
      * its true layout. When absent, falls back to flat text (tests).
      */
     parseBlockBody?: (txbxContent: Element) => Block[];
+    /** Theme colour palette (from `word/theme/theme1.xml`) so shape fills /
+     *  strokes declared as `<a:schemeClr>` resolve instead of vanishing. */
+    theme?: ThemePalette;
 }
 /**
  * Walk every `<w:drawing>/<wp:anchor>` in the document and return one

package/dist/docx/import/borders.d.ts

@@ -0,0 +1,12 @@
+import { ParagraphBorders } from '../../doc/types';
+/**
+ * Read a `<w:pBdr>` paragraph-border element into `ParagraphBorders`.
+ *
+ * Shared by the direct-paragraph parser AND the named-style parser: Word
+ * puts the divider rules of letterhead / résumé headers on a STYLE (e.g. a
+ * "Name" style's `<w:top>` rule), not on each paragraph. Reading it only
+ * for direct paragraphs dropped those rules entirely (the renderer's
+ * `effective.borders` cascade had nothing to apply). `none` / `nil` sides
+ * are skipped (Word's explicit "no border on this side").
+ */
+export declare function readParagraphBorders(pPr: Element): ParagraphBorders | undefined;

package/dist/docx/import/floatFrames.d.ts

@@ -0,0 +1,11 @@
+import { AnchoredFrame, Block, SectionProperties } from '../../doc/types';
+/**
+ * Prepend a float `DrawingRun` to each floatable frame's anchor paragraph
+ * and drop those frames from the overlay set. Pure — inputs untouched.
+ * Body indices are stable (we modify paragraphs in place, never insert),
+ * so it composes after `flowDisplacingTextboxes` without an index remap.
+ */
+export declare function floatWrappingImages(body: readonly Block[], frames: readonly AnchoredFrame[], sections: readonly SectionProperties[]): {
+    body: Block[];
+    frames: AnchoredFrame[];
+};

package/dist/docx/import/inlineFrames.d.ts

@@ -1,4 +1,5 @@
 import { Block, InlineFrame } from '../../doc/types';
+import { ThemePalette } from '../shared/drawingColor';
 export interface InlineFramesContext {
     /** RelationshipId → part path lookup. */
     rels: Map<string, string>;
@@ -26,6 +27,9 @@ export interface InlineFramesContext {
      * Without this flag, only explicit directives count.
      */
     honorLastRenderedPageBreaks?: boolean;
+    /** Theme colour palette (from `word/theme/theme1.xml`) so textbox /
+     *  shape fills declared as `<a:schemeClr>` resolve instead of vanishing. */
+    theme?: ThemePalette;
 }
 /**
  * One InlineFrame plus the source DOM nodes it came from.

package/dist/docx/import/paragraphs.d.ts

@@ -4,9 +4,14 @@ import { ParagraphFormat } from '../types';
 export type ImportedItem = {
     kind: "run";
     run: ImportedRun;
-} | {
+}
+/** `href` is set for HYPERLINK *fields* (the target lives in the field
+ *  instruction); `relId` for `<w:hyperlink r:id>` elements (resolved
+ *  against the rels table downstream). */
+ | {
     kind: "hyperlink";
     relId?: string;
+    href?: string;
     runs: ImportedRun[];
 };
 export interface ImportedParagraph {

package/dist/docx/import/styles.d.ts

@@ -1,3 +1,16 @@
 import { NamedStyle } from '../../doc/types';
 import { DocSettings } from './settings';
+/**
+ * Canonicalise a heading style id to `HeadingN`.
+ *
+ * Word and OpenOffice name the heading styles inconsistently across docs:
+ * `Heading2`, `Heading 2`, `heading 2`. The paragraph importer already
+ * maps a heading PARAGRAPH's styleId to the canonical `HeadingN` (so it
+ * renders as `<hN>` and joins the `HeadingN` convention used by builders /
+ * serialize / markdown). The STYLE definition must canonicalise the same
+ * way, or `resolveStyleCascade` looks up `HeadingN` and misses the
+ * actual style — dropping its colour, caps, etc. Non-heading ids pass
+ * through unchanged.
+ */
+export declare function canonicalStyleId(id: string): string;
 export declare function parseStylesXml(xml: string | undefined, settings?: DocSettings): NamedStyle[] | null;

package/dist/docx/shared/drawingColor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DrawingML colour resolution — literal AND theme colours.
+ *
+ * A DrawingML colour container (`<a:solidFill>`, the children of
+ * `<a:ln>`, …) holds either a literal `<a:srgbClr val="RRGGBB">` or a
+ * theme reference `<a:schemeClr val="accent1">`. Both can carry child
+ * TRANSFORM elements that adjust the base colour (`hueOff`, `satOff`,
+ * `lumOff`, `lumMod`, `shade`, `tint`, …). Word resolves the scheme slot
+ * against `word/theme/theme1.xml`'s `<a:clrScheme>` and applies the
+ * transforms in document order — reading only `srgbClr` renders every
+ * theme-coloured shape invisible (no fill, no stroke).
+ *
+ * Transform units (ECMA-376 §20.1.2.3):
+ *   - `hueOff`  — 60000ths of a degree, added to the hue.
+ *   - `satOff` / `lumOff` — 1000ths of a percent-POINT, added to S / L.
+ *   - `satMod` / `lumMod` — 100000ths, multiplied onto S / L.
+ *   - `shade` — scale toward black (val/100000).
+ *   - `tint`  — scale toward white (val/100000).
+ */
+/** Theme slot → `#RRGGBB`. Slots: dk1/lt1/dk2/lt2/accent1-6/hlink/folHlink. */
+export type ThemePalette = Record<string, string>;
+/** Parse `word/theme/theme1.xml` into the colour-scheme palette.
+ *  Returns undefined when the part is absent or malformed. */
+export declare function parseThemeXml(xml: string | undefined): ThemePalette | undefined;
+/**
+ * Resolve the colour child of `parent` (an `<a:solidFill>` or `<a:ln>`-
+ * style container): literal `srgbClr` or theme `schemeClr`, transforms
+ * applied. Returns `#RRGGBB` or undefined when no resolvable colour.
+ */
+export declare function readDrawingColor(parent: Element, theme?: ThemePalette): string | undefined;

package/dist/docx/shared/units.d.ts

@@ -28,8 +28,9 @@ export declare const twipsToPt: (t: number) => number;
 /** pt → twips. */
 export declare const ptToTwips: (pt: number) => number;
 /**
- * `w:line` for line spacing in "auto" mode: 240 twips = single-spacing.
- * So `line-height: 1.5` → `240 * 1.5 = 360`.
+ * `w:line` value (in "auto" line-rule mode) for single line spacing.
+ * Word treats 240 as 1.0×, so `line-height: 1.5` → `240 * 1.5 = 360`.
  */
+export declare const SINGLE_SPACING_LINE = 240;
 export declare const lineHeightToOoxml: (lineHeight: number) => number;
 export declare const ooxmlLineHeightToCss: (line: number) => number;

package/dist/docx/shared/xml.d.ts

@@ -17,6 +17,18 @@ export declare function wChildren(parent: Element, localName: string): Element[]
  * serialised documents differ.
  */
 export declare function wVal(el: Element | null): string | null;
+/**
+ * Read an OOXML on/off toggle property (`CT_OnOff`: `<w:pageBreakBefore>`,
+ * `<w:b>`, `<w:keepNext>`, …). Absent → false. Present with no `w:val` →
+ * true (a bare element means "on"). Present with `w:val` →
+ * "false"/"0"/"off" mean OFF; anything else ON.
+ *
+ * Reading these by mere presence is a classic OOXML bug: Word writes the
+ * explicit-off form (`<w:pageBreakBefore w:val="0"/>`) in DocDefaults and
+ * styles, so presence-only flips the property ON for every consumer — e.g.
+ * a page break before every paragraph.
+ */
+export declare function wOnOff(root: Document | Element, localName: string): boolean;
 /** Build an XML declaration header + root element. Used by the exporter. */
 export declare function xmlDocument(rootXml: string): string;
 /**

package/dist/docx/types.d.ts

@@ -18,6 +18,10 @@ export interface DocxExportResult {
 }
 /** A single inline run's formatting flags — what `<w:rPr>` tells us. */
 export interface RunFormat {
+    /** `<w:rStyle w:val="…">` — a character style applied to the run. Its
+     *  rPr (colour, underline, …) is resolved against the style cascade at
+     *  render time, under any direct run formatting. */
+    styleId?: string;
     bold?: boolean;
     italic?: boolean;
     underline?: boolean;

package/dist/editor/commands.d.ts

@@ -0,0 +1,14 @@
+import { CommandBus, CommandDefinition, CommandSnapshot } from './types';
+/**
+ * Default {@link CommandBus} implementation. Plain in-memory map; no
+ * editor coupling beyond the closure plugins use when registering.
+ * Replacing it would mean swapping a field on Editor — the rest of
+ * the surface stays the same.
+ */
+export declare class EditorCommands implements CommandBus {
+    private readonly commands;
+    register<Args = void>(def: CommandDefinition<Args>): () => void;
+    execute<Args = void>(name: string, args?: Args): void;
+    list(): CommandSnapshot[];
+    has(name: string): boolean;
+}

package/dist/editor/context.d.ts

@@ -0,0 +1,71 @@
+import { BlobCache, BlobStore } from '../blob';
+import { Range as ApiRange, BlockRef, EditResult } from '../doc/api';
+import { SobreeDocument } from '../doc/types';
+import { FontFaceRegistry } from '../fonts';
+import { History } from '../history';
+import { BlockRegistry } from './internal/blockRegistry';
+import { Mutation } from './internal/mutations';
+import { EditorSelection } from './selection';
+import { TrackChangesState } from './types';
+import type * as Y from "yjs";
+/**
+ * The kernel seam between the `Editor` (which owns mutable state, the
+ * `commit()` transaction pipeline, DOM-listener wiring, and Y.Doc
+ * mirroring) and the behaviour modules (`ops/*`, `query`) that implement
+ * each editing concern as free functions over this context.
+ *
+ * The `Editor` builds one `EditorContext` once in its constructor,
+ * closing over its own privates — so `commit` / `checkRefs` / `ensureCurrent`
+ * stay private to the class while the behaviour modules get exactly the
+ * surface they need and nothing more. This is the state/behaviour split
+ * that lets the central editor decompose without Host-seam slicing
+ * (which would have to expose nearly everything).
+ *
+ * Members are named to match the `Editor`'s own field/method names so a
+ * behaviour body reads identically whether it lives on the class or in a
+ * module: `this.commit(...)` becomes `ctx.commit(...)`.
+ */
+export interface EditorContext {
+    readonly host: HTMLElement;
+    readonly selection: EditorSelection;
+    readonly registry: BlockRegistry;
+    readonly history: History;
+    readonly ydoc: Y.Doc;
+    readonly blobStore: BlobStore | null;
+    readonly blobCache: BlobCache | null;
+    readonly fontFaces: FontFaceRegistry;
+    /** Live view of the editor's current document (re-read on every access). */
+    readonly doc: SobreeDocument;
+    /** Replace the cached document wholesale (rare — most paths use `commit`). */
+    setDoc(doc: SobreeDocument): void;
+    /** Full document replace: reset registry, re-render, mirror, emit change. */
+    setDocument(doc: SobreeDocument): void;
+    /** Re-render the current `doc` into the hosts (no selection restore, no emit). */
+    renderCurrent(): void;
+    /**
+     * Soft-revert the in-memory doc to `snapshot` and re-render (resets the
+     * serialised-block cache + dom-dirty flag; no registry reset, mirror, or
+     * emit). Used to roll back the browser's native IME mutations before a
+     * tracked re-insert.
+     */
+    restoreSnapshot(snapshot: SobreeDocument): void;
+    /** The content host(s) the renderer paints into (may differ from `host`). */
+    getContentHosts(): HTMLElement[];
+    /** The host(s) a DOM selection may live in. */
+    _hosts(): HTMLElement[];
+    readonly trackChanges: TrackChangesState;
+    /** Set tracked-changes state WITHOUT firing the change event (internal). */
+    setTrackChangesRaw(state: TrackChangesState): void;
+    readonly lastPartRefs: Record<string, string>;
+    setLastPartRefs(refs: Record<string, string>): void;
+    readonly pendingPartRefMigrations: Set<string>;
+    commit<T = void>(update: Partial<SobreeDocument>, mutations: readonly Mutation[], value?: T, reason?: string): EditResult<T>;
+    ensureCurrent(): SobreeDocument;
+    syncFromDom(): SobreeDocument;
+    checkRefs(refs: readonly BlockRef[]): EditResult<never> | null;
+    checkRange(range: ApiRange, expect: Record<string, number> | undefined): EditResult<never> | null;
+    emitChangeNow(): void;
+    mirrorToYDoc(): void;
+    scheduleChange(): void;
+    setDomDirty(value: boolean): void;
+}

package/dist/editor/dom.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DOM utilities for the editor — selection geometry, block-element
+ * lookup, drag/drop image detection, image sizing. Browser-only
+ * (no model state); kept apart from `editor/index.ts` so the editor
+ * module stays about editing, not DOM plumbing.
+ */
+/** Nearest ancestor (or self) that is a direct block child of a host. */
+export declare function closestBlockElement(node: Node, hosts: HTMLElement[]): HTMLElement | null;
+/** The live DOM selection range, but only if both ends are inside a host. */
+export declare function currentDomRangeInsideHosts(hosts: HTMLElement[]): Range | null;
+/** True when a drag/paste DataTransfer carries at least one image file. */
+export declare function hasImageInDataTransfer(dt: DataTransfer | null): boolean;
+/** Cross-browser caret range at viewport (x, y) — drop-point resolution. */
+export declare function caretRangeFromPoint(x: number, y: number): Range | null;
+/** Decode an image file's natural dimensions (falls back to 200×150). */
+export declare function readImageDimensions(file: File): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Replace an element with its children (lift contents up one level). */
+export declare function unwrap(el: HTMLElement): void;

package/dist/editor/events.d.ts

@@ -0,0 +1,29 @@
+import { Selection } from '../doc/api';
+import { ChangePayload, EditorEvent, EditorEventPayload, TrackChangesState, Unsubscribe } from './types';
+/**
+ * The editor's observable event surface — `change`, `selection`,
+ * `keydown`, `track-changes-change`. Owns the four listener sets and the
+ * dispatch loops; the Editor keeps the *triggers* (the DOM listeners and
+ * the commit pipeline) and forwards built payloads here. Each dispatch
+ * isolates listener exceptions so one bad subscriber can't break the
+ * others or the edit that fired the event.
+ */
+export declare class EditorEvents {
+    private readonly listeners;
+    on<E extends EditorEvent>(event: E, cb: (p: EditorEventPayload[E]) => void): Unsubscribe;
+    /** Whether any `change` subscriber exists — lets the caller skip
+     *  building the (cloned) payload when nobody's listening. */
+    hasChangeListeners(): boolean;
+    emitChange(payload: ChangePayload): void;
+    /** Compose a {@link SelectionPayload} from `sel` and dispatch. */
+    emitSelection(sel: Selection): void;
+    /**
+     * Normalise a DOM `KeyboardEvent` into a {@link KeyDownPayload} and
+     * dispatch in registration order. Subscribers can `preventDefault()`
+     * (browser default) and/or `stopPropagation()` (further subscribers).
+     */
+    emitKeyDown(e: KeyboardEvent): void;
+    emitTrackChanges(state: TrackChangesState): void;
+    /** Drop all subscribers on editor destroy. */
+    clear(): void;
+}