@sobree/core 0.1.28 → 0.1.29

package/dist/doc/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sobree's internal document model.
+ *
+ * Every node here maps 1-to-1 to an OOXML construct so serialisation to
+ * `.docx` is mechanical (no decisions, no lossy translation). The names
+ * are JS-friendly — `Paragraph`, `RunProperties`, etc. — rather than
+ * `<w:p>`, `<w:rPr>` directly, but the shapes line up.
+ *
+ * Conventions:
+ *   - All numeric measurements that originate in OOXML keep their native
+ *     unit, suffixed in the field name: `wTwips`, `sizeHalfPt`, `widthEmu`.
+ *   - All node objects are JSON-clean (no functions, classes, or
+ *     references) so they cross any wire (Yjs sync messages, MCP,
+ *     postMessage) untouched.
+ *   - Optional fields are `?:` — absence means "not set", not "default".
+ *     Defaults are applied at render time from the document's styles.
+ *
+ * The concept modules in this directory each own one slice of the model.
+ * This barrel re-exports every AST type so consumers keep importing from
+ * `doc/types` regardless of which concept file a type physically lives in.
+ */
+export type { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, } from '../formatting.types';
+export type { TableConditionalType, TableLook, TableStyleCellFormat, TableStyleDefinition, } from '../tableStyle.types';
+export type * from './block';
+export type * from './document';
+export type * from './drawing';
+export type * from './headersFooters';
+export type * from './numbering';
+export type * from './paragraph';
+export type * from './parts';
+export type * from './revisions';
+export type * from './runs';
+export type * from './sections';
+export type * from './styles';

package/dist/doc/types/numbering.d.ts

@@ -0,0 +1,25 @@
+import { ParagraphIndent } from './paragraph';
+import { RunProperties } from './runs';
+export interface NumberingDefinition {
+    /** `numId` referenced from `ParagraphProperties.numbering`. */
+    numId: number;
+    /** The abstract format definition. */
+    abstractFormat: AbstractNumberingFormat;
+}
+export interface AbstractNumberingFormat {
+    /** One per indent level (0..8 typically). */
+    levels: NumberingLevel[];
+}
+export interface NumberingLevel {
+    level: number;
+    /** Format: `bullet`, `decimal`, `lowerRoman`, `upperLetter`, … */
+    format: string;
+    /** Text template, e.g. `%1.` or a literal bullet character. */
+    text: string;
+    /** Restart numbering after this level. */
+    restart?: number;
+    /** Indentation of the numbered text. */
+    paragraphIndent?: ParagraphIndent;
+    /** Run properties for the bullet/number marker itself. */
+    runDefaults?: RunProperties;
+}

package/dist/doc/types/paragraph.d.ts

@@ -0,0 +1,82 @@
+import { BorderSpec, Shading } from '../formatting.types';
+import { RevisionMark } from './revisions';
+import { RunProperties } from './runs';
+export interface ParagraphProperties {
+    /** Reference to a `NamedStyle.id` of type "paragraph". */
+    styleId?: string;
+    alignment?: ParagraphAlignment;
+    /** Numbered/bulleted list reference. */
+    numbering?: {
+        numId: number;
+        level: number;
+    };
+    spacing?: ParagraphSpacing;
+    indent?: ParagraphIndent;
+    borders?: ParagraphBorders;
+    shading?: Shading;
+    /** Keep this paragraph on the same page as the next one. */
+    keepNext?: boolean;
+    /** Don't allow this paragraph to break across pages. */
+    keepLines?: boolean;
+    /** Insert a page break before this paragraph. */
+    pageBreakBefore?: boolean;
+    /** Custom tab stops from `<w:pPr><w:tabs>`, positions in twips. The
+     *  renderer uses the smallest stop's position to compute a CSS
+     *  `tab-size` on the paragraph so `\t` characters in the text honour
+     *  the document's tab geometry instead of the browser's 8-char
+     *  default. Mixed alignments (right / decimal / leader) collapse to
+     *  "left" for now — covering the common case (label-value columns
+     *  in headers + form fields). */
+    tabStops?: readonly {
+        positionTwips: number;
+        alignment: string;
+        leader?: string;
+    }[];
+    /** Default run properties applied to runs that don't override. */
+    runDefaults?: RunProperties;
+    /**
+     * Tracked-change marker on the paragraph mark itself. Semantically:
+     * the *paragraph break that precedes this paragraph* is a tracked
+     * change. Word stores this as `<w:rPr><w:ins/></w:rPr>` inside
+     * `<w:pPr>` — see ECMA-376 §17.13.5.7.
+     *
+     *   `ins` — pressing Enter created this paragraph (split the prior
+     *           paragraph). Accepting keeps the split; rejecting merges
+     *           the paragraph back into the previous one.
+     *   `del` — the user has marked this paragraph break for deletion
+     *           (e.g. Backspace at the start of this paragraph in
+     *           tracked mode). Accepting merges into the previous;
+     *           rejecting keeps the split.
+     *
+     * Accept/reject of this paragraph-level marker is tracked under
+     * follow-up task 26 (block-level revisions); v1 only adds the
+     * authoring path (via `Editor.splitBlock` in track-changes mode).
+     */
+    revision?: RevisionMark;
+}
+export type ParagraphAlignment = "left" | "center" | "right" | "both" | "distribute";
+export interface ParagraphSpacing {
+    /** Twips before the paragraph. */
+    beforeTwips?: number;
+    /** Twips after the paragraph. */
+    afterTwips?: number;
+    /** Twips between lines (when `lineRule === "exact" | "atLeast"`) or
+     *  240ths of a multiplier (when `lineRule === "auto"`). */
+    line?: number;
+    lineRule?: "auto" | "exact" | "atLeast";
+}
+export interface ParagraphIndent {
+    leftTwips?: number;
+    rightTwips?: number;
+    /** Indent of the first line of the paragraph (positive = indent in). */
+    firstLineTwips?: number;
+    /** Hanging indent (offsets first line OUT of the rest of the para). */
+    hangingTwips?: number;
+}
+export interface ParagraphBorders {
+    top?: BorderSpec;
+    right?: BorderSpec;
+    bottom?: BorderSpec;
+    left?: BorderSpec;
+    between?: BorderSpec;
+}

package/dist/doc/types/parts.d.ts

@@ -0,0 +1,18 @@
+export type { FontDeclaration, FontEmbedRef } from '../../fonts/types';
+/**
+ * Mirror of the `_rels/document.xml.rels` table — Sobree tracks
+ * relationships as data so headers, footers, images, hyperlinks all share
+ * one allocation strategy at export time.
+ */
+export interface RelationshipManifest {
+    /** Map of `rId…` → relationship descriptor. */
+    byId: Record<string, Relationship>;
+}
+export interface Relationship {
+    id: string;
+    type: RelationshipType;
+    target: string;
+    /** External (true) means `target` is a URL; otherwise a part path. */
+    external?: boolean;
+}
+export type RelationshipType = "header" | "footer" | "image" | "hyperlink" | "styles" | "numbering" | "settings" | "fontTable" | "theme" | "comments" | "footnotes" | "endnotes";

package/dist/doc/types/revisions.d.ts

@@ -0,0 +1,8 @@
+export interface RevisionMark {
+    /** `ins` = insertion, `del` = deletion. */
+    type: "ins" | "del";
+    /** Author name as recorded in the docx (`<w:ins w:author="...">`). */
+    author?: string;
+    /** ISO-8601 timestamp string from the docx. */
+    date?: string;
+}

package/dist/doc/types/runs.d.ts

@@ -0,0 +1,178 @@
+import { Shading } from '../formatting.types';
+import { RevisionMark } from './revisions';
+export type InlineRun = TextRun | BreakRun | TabRun | FieldRun | DrawingRun | HyperlinkRun | FootnoteRefRun | CommentRefRun;
+export interface TextRun {
+    kind: "text";
+    text: string;
+    properties: RunProperties;
+}
+export interface BreakRun {
+    kind: "break";
+    /**
+     * `line` — soft line break inside a paragraph (Shift-Enter).
+     * `page` — explicit page break.
+     * `column` — column break in a multi-column section.
+     */
+    type: "line" | "page" | "column";
+    properties?: RunProperties;
+}
+export interface TabRun {
+    kind: "tab";
+    properties?: RunProperties;
+}
+export interface FieldRun {
+    kind: "field";
+    /** Field instruction text — `PAGE`, `NUMPAGES`, `DATE`, `AUTHOR`, … */
+    instruction: string;
+    /**
+     * Cached value displayed if a viewer doesn't recalculate. Used as the
+     * preview text by Sobree's renderer.
+     */
+    cached?: string;
+    properties?: RunProperties;
+}
+/**
+ * Inline reference to a comment (`<w:commentReference w:id="N"/>`).
+ * Word renders a small balloon icon at the position; we mirror with
+ * a clickable inline span linking to the comment card in the aside.
+ */
+export interface CommentRefRun {
+    kind: "commentRef";
+    /** ID matching a key in `SobreeDocument.comments`. */
+    id: number;
+    properties?: RunProperties;
+}
+/**
+ * Inline reference to a footnote (`<w:footnoteReference w:id="N"/>`).
+ * Renders as a clickable superscript number; the referenced footnote's
+ * body lives in `SobreeDocument.footnotes[id]` and is rendered at the
+ * end of the document. (True per-page pinning is a paginator feature
+ * deferred for now.)
+ */
+export interface FootnoteRefRun {
+    kind: "footnoteRef";
+    /** ID matching a key in `SobreeDocument.footnotes`. */
+    id: number;
+    properties?: RunProperties;
+}
+export interface DrawingRun {
+    kind: "drawing";
+    /** Path of the embedded media part in `rawParts` (e.g. `word/media/image1.png`). */
+    partPath: string;
+    /** Rendered size. */
+    widthEmu: number;
+    heightEmu: number;
+    /** Accessibility text. */
+    altText?: string;
+    /**
+     * Where the image lays out:
+     *   - "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" | "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
+     * text baseline). `"middle"` centres the image on the text — used
+     * for a heading decoration (the flowed ► project arrow) that is
+     * taller than its label, so the label centres beside it as Word
+     * renders it. Omitted for ordinary inline images.
+     */
+    verticalAlign?: "baseline" | "middle";
+}
+export interface DrawingAnchor {
+    /** Horizontal offset in EMU (English Metric Units; 914400 EMU = 1 inch). */
+    offsetXEmu: number;
+    /** Vertical offset in EMU. */
+    offsetYEmu: number;
+    /** What `offsetXEmu` is measured from. */
+    relativeFromH: "page" | "margin" | "column" | "character";
+    /** What `offsetYEmu` is measured from. */
+    relativeFromV: "page" | "margin" | "paragraph" | "line";
+    /** True when the image renders *behind* text (z-index negative). */
+    behindDoc?: boolean;
+}
+export interface HyperlinkRun {
+    kind: "hyperlink";
+    /** Either an external URL or an internal anchor id. */
+    href: string;
+    /** Display text — itself a list of runs to allow nested formatting. */
+    children: InlineRun[];
+    properties?: RunProperties;
+}
+export interface RunProperties {
+    /** Reference to a `NamedStyle.id` of type "character". */
+    styleId?: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** Underline style — most callers want `"single"`. */
+    underline?: "single" | "double" | "dotted" | "dashed" | "wave" | "none";
+    strike?: boolean;
+    doubleStrike?: boolean;
+    /** `#rrggbb`. */
+    color?: string;
+    /** Word highlight name (`yellow`, `green`, …) or `#rrggbb`. */
+    highlight?: string;
+    /** Cell-style shading (`<w:shd w:fill="…">`). */
+    shading?: Shading;
+    /** Font family name (Calibri, Georgia, …). */
+    fontFamily?: string;
+    /** Size in points (Word stores half-points; we expose pt for ergonomics). */
+    fontSizePt?: number;
+    verticalAlign?: "subscript" | "superscript";
+    /** Whether the text is uppercase / small caps. */
+    caps?: boolean;
+    smallCaps?: boolean;
+    /** Hidden text (`<w:vanish/>`). */
+    hidden?: boolean;
+    /**
+     * Tracked-change marker — set when the run is inside a `<w:ins>`
+     * (insertion) or `<w:del>` (deletion) wrapper. The renderer
+     * applies a visual revision style; the underlying text is preserved
+     * either way so the document round-trips faithfully.
+     */
+    revision?: RevisionMark;
+    /**
+     * Comment ids whose `<w:commentRangeStart>` … `<w:commentRangeEnd>`
+     * span includes this run. The renderer highlights ranges with any
+     * active comment. Multiple ids let nested/overlapping comments
+     * coexist on the same run.
+     */
+    commentIds?: readonly number[];
+    /**
+     * Tracked **format change** — a snapshot of this run's properties
+     * *before* the most recent tracked formatting edit. Word stores this
+     * as `<w:rPrChange>` (ECMA-376 §17.13.5.32).
+     *
+     * Accepting the format revision drops `revisionFormat` (the current
+     * `properties` stays). Rejecting it restores `properties` *to* the
+     * `before` snapshot. Repeated tracked format edits don't overwrite
+     * the snapshot — the *original* properties stay captured, so a
+     * reject always returns the run to its pre-tracking state.
+     *
+     * `before` is itself a `RunProperties` but `revisionFormat` doesn't
+     * recurse (the snapshot is "what the run looked like before we
+     * started tracking format changes").
+     */
+    revisionFormat?: {
+        before: RunProperties;
+        author?: string;
+        date?: string;
+    };
+}

package/dist/doc/types/sections.d.ts

@@ -0,0 +1,67 @@
+import { HeaderFooterRef } from './headersFooters';
+export interface SectionProperties {
+    pageSize: PageSize;
+    pageMargins: PageMargins;
+    /** Header references. Most docs have one or two. */
+    headerRefs: HeaderFooterRef[];
+    footerRefs: HeaderFooterRef[];
+    /** Show the first-page header/footer slot if true. */
+    titlePage?: boolean;
+    /** Continuous, nextPage, etc. */
+    type?: "continuous" | "nextPage" | "evenPage" | "oddPage";
+    /**
+     * Vertical alignment of the body content on each page in this section.
+     * OOXML `<w:vAlign>` (ECMA-376 §17.6.21). Only visible on partial pages
+     * — full pages have no slack to redistribute. Default is `"top"` (the
+     * field is omitted in that case).
+     *
+     *   - `top`    — content anchored to top margin (default).
+     *   - `center` — content centred between top and bottom margin.
+     *   - `bottom` — content anchored to bottom margin.
+     *   - `both`   — paragraph spacing stretched to fill the page.
+     */
+    vAlign?: "top" | "center" | "bottom" | "both";
+    /**
+     * Multi-column layout for the section's content (`<w:cols>`).
+     * Absent or `count <= 1` → single column (the default; the renderer
+     * does not wrap in a column container in that case).
+     */
+    columns?: SectionColumns;
+}
+export interface SectionColumns {
+    /** Number of columns. */
+    count: number;
+    /** Default inter-column gap in twips (Word's `<w:cols w:space>`). Used
+     *  for equal columns and as the fallback gap when a per-column space
+     *  is absent. */
+    spaceTwips?: number;
+    /** `false` when the section declares explicit per-column widths
+     *  (Word's `<w:cols w:equalWidth="0">`). Absent/`true` → equal columns,
+     *  which the renderer flows with CSS multi-column. */
+    equalWidth?: boolean;
+    /** Per-column geometry from `<w:col w:w w:space>`, present only for the
+     *  unequal case. `length === count`. Each entry's `spaceTwips` is the
+     *  gap AFTER that column (the last column's is usually absent). The
+     *  renderer flows blocks across these tracks at their true widths. */
+    columns?: SectionColumn[];
+}
+export interface SectionColumn {
+    /** Column width in twips (`<w:col w:w>`). */
+    widthTwips: number;
+    /** Trailing gap after this column in twips (`<w:col w:space>`). */
+    spaceTwips?: number;
+}
+export interface PageSize {
+    wTwips: number;
+    hTwips: number;
+    orientation: "portrait" | "landscape";
+}
+export interface PageMargins {
+    topTwips: number;
+    rightTwips: number;
+    bottomTwips: number;
+    leftTwips: number;
+    headerTwips: number;
+    footerTwips: number;
+    gutterTwips: number;
+}

package/dist/doc/types/styles.d.ts

@@ -0,0 +1,32 @@
+import { TableStyleDefinition } from '../tableStyle.types';
+import { TableProperties } from './block';
+import { ParagraphProperties } from './paragraph';
+import { RunProperties } from './runs';
+export interface NamedStyle {
+    id: string;
+    type: "paragraph" | "character" | "table" | "numbering";
+    /** Display name shown in Word's style picker. */
+    displayName: string;
+    /** Inherits from another style id. */
+    basedOn?: string;
+    /** The style applied to the next paragraph after this one (for headings). */
+    nextStyleId?: string;
+    /** Default run properties. */
+    runDefaults?: RunProperties;
+    /** Default paragraph properties. */
+    paragraphDefaults?: ParagraphProperties;
+    /** Numbering linked via the style's `<w:numPr>` — the source of heading
+     *  outline numbers ("1", "1.1", "1.2"). `numId` references a
+     *  `NumberingDefinition`; `level` is the outline level this style sits at.
+     *  Distinct from `ParagraphProperties.numbering` (a paragraph's OWN list
+     *  membership); a style's numbering applies to every paragraph using it. */
+    numbering?: {
+        numId: number;
+        level: number;
+    };
+    /** Default table properties (only for table styles). */
+    tableDefaults?: TableProperties;
+    /** Table-style borders + conditional formatting (only for table
+     *  styles). Resolved per cell at render time. */
+    tableStyle?: TableStyleDefinition;
+}