superdoc 2.2.1 → 2.4.0-next.1

package/dist/layout-engine/contracts/src/direction-context.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Direction Context Types
+ *
+ * Typed direction information that propagates from section to paragraph to run
+ * during pm-adapter conversion. Each container has its own context type so the
+ * orthogonal axes do not collapse:
+ *
+ *   - section page direction (page numbers, columns) is independent of
+ *   - paragraph inline base direction (ind, jc, tab) which is independent of
+ *   - table visual direction (cell ordering) which is independent of
+ *   - writing mode (horizontal vs vertical text flow).
+ *
+ * Per ECMA-376:
+ *   - Section w:bidi affects section chrome only (§17.6.1).
+ *   - Paragraph w:bidi affects paragraph-level properties only (§17.3.1.6).
+ *   - Table w:bidiVisual affects cell ordering only (§17.4.1).
+ *   - Writing mode (w:textDirection) inherits across containers when absent
+ *     (§17.3.1.41) — the one exception that does propagate.
+ *
+ * The resolver chain in `pm-adapter/src/direction/` produces these contexts.
+ * Downstream consumers (DomPainter, layout-bridge, hit testing) read the
+ * resolved fields and never re-derive direction from raw attributes.
+ */
+/**
+ * Inline base direction of text within a container.
+ * Maps to OOXML w:bidi (paragraph) and w:rtl (run).
+ */
+export type BaseDirection = 'ltr' | 'rtl';
+/**
+ * Text flow direction ("writing mode").
+ * Maps to OOXML w:textDirection (ST_TextDirection §17.18.93).
+ *
+ * Limited to the values SuperDoc renders today; the full OOXML enum has
+ * twelve values for vertical-text variants (Wave 4 expands this).
+ */
+export type WritingMode = 'horizontal-tb' | 'vertical-rl' | 'vertical-lr';
+/**
+ * Direction context for a section.
+ * Used by section-level chrome only (page numbers, columns, gutters).
+ * MUST NOT be used to determine paragraph inline direction.
+ */
+export type SectionDirectionContext = {
+    /** Section page direction; from w:sectPr/w:bidi. */
+    pageDirection: BaseDirection;
+    /** Default writing mode for paragraphs and cells in the section. */
+    writingMode: WritingMode;
+    /** Whether the page gutter is on the right; from w:sectPr/w:rtlGutter. */
+    rtlGutter: boolean;
+};
+/**
+ * Direction context for a table.
+ * Carries visual cell ordering only. Cell paragraph direction is independent.
+ */
+export type TableDirectionContext = {
+    /**
+     * Visual direction of cell ordering; from w:tblPr/w:bidiVisual.
+     * Undefined when not specified.
+     *
+     * This is the single load-bearing field: `getTableVisualDirection` and all
+     * downstream consumers (layout-table, DomPainter) read only `visualDirection`.
+     */
+    visualDirection: BaseDirection | undefined;
+    /**
+     * Inherited from the parent section. Optional: producers that resolve only
+     * the table's own visual axis (e.g. the v2 layout adapter, which derives
+     * `visualDirection` from inline `w:bidiVisual` evidence) populate just
+     * `visualDirection`. Section inheritance is an orthogonal axis resolved
+     * elsewhere; no consumer reads `parentSection` today.
+     */
+    parentSection?: SectionDirectionContext;
+};
+/**
+ * Direction context for a table cell.
+ * Carries cell-level writing mode (vertical text). Cell paragraph inline
+ * direction is decided per-paragraph, not by the cell.
+ */
+export type CellDirectionContext = {
+    /**
+     * Cell text flow direction; from w:tcPr/w:textDirection.
+     * Falls back to the section writing mode when absent.
+     */
+    writingMode: WritingMode;
+    /** Inherited from the parent table. */
+    parentTable: TableDirectionContext;
+};
+/**
+ * Direction context for a paragraph.
+ * The single source of truth for paragraph direction-aware decisions.
+ *
+ * Consumers (logical-side resolution, alignment, indent, hit testing,
+ * DomPainter direction styling) read from here. They do NOT re-derive
+ * direction from raw attributes.
+ */
+export type ParagraphDirectionContext = {
+    /**
+     * Paragraph inline base direction; from w:pPr/w:bidi.
+     * Undefined when no explicit bidi is set; consumers should let the browser
+     * apply the Unicode Bidi Algorithm via missing or empty `dir` attribute.
+     *
+     * Section page direction MUST NOT propagate into this field. Per §17.6.1,
+     * section bidi only affects section chrome, not paragraph layout.
+     */
+    inlineDirection: BaseDirection | undefined;
+    /**
+     * Writing mode (text flow) for the paragraph; from w:pPr/w:textDirection.
+     * Inherits from the section when absent. This is the one OOXML direction
+     * field that propagates across containers per §17.3.1.41.
+     */
+    writingMode: WritingMode;
+};
+/**
+ * Run-level bidi signals: explicit overrides and embeddings.
+ * Direction signals only — script formatting lives in RunScriptContext.
+ *
+ * Maps to OOXML w:rPr/w:rtl (§17.3.2.30), w:dir (§17.3.2.8 embedding),
+ * w:bdo (§17.3.2.3 override).
+ */
+export type RunBidiContext = {
+    /**
+     * w:rPr/w:rtl. Preserves the source OOXML signal that the run carries
+     * the `w:rtl` flag. Per §17.3.2.30, `w:rtl` does two things at the model
+     * level:
+     *   1. Forces the complex-script formatting stack (bCs, iCs, szCs,
+     *      rFonts/@cs). See RunScriptContext for the formatting half.
+     *   2. Acts as a Character Directionality Override for weak/neutral
+     *      characters in the run (NOT a forced visual flip of strong-LTR text;
+     *      §17.3.2.30 explicitly says behavior on strong-LTR is unspecified).
+     *
+     * `rtl: true` is the source signal, NOT a directive that every consumer
+     * must project to `dir="rtl"` in the rendered DOM. The painter decides
+     * the DOM projection per its Word-parity rules (see
+     * `features/inline-direction/resolveRunDirectionAttribute`). Exporters
+     * must preserve `rtl: true` on round-trip regardless of paint decisions,
+     * since dropping it would lose the source `w:rPr/w:rtl` semantics.
+     */
+    rtl: boolean;
+    /** w:dir; bidi embedding direction (RLE/LRE). Wave 1c. */
+    embedding?: BaseDirection;
+    /** w:bdo; bidi override direction (RLO/LRO). Wave 1c. */
+    override?: BaseDirection;
+};
+/**
+ * Run-level script context: which formatting stack applies.
+ *
+ * Per ECMA Annex I, when w:rtl is set or w:cs is set, the run's formatting
+ * comes from the complex-script variants (bCs, iCs, szCs, rFonts/@cs).
+ * Otherwise it comes from the Latin variants (b, i, sz, rFonts/@ascii).
+ *
+ * This context is preservation-only in Wave 1a. Wave 1b implements the
+ * stack-selection logic (resolveRunScriptContext returns whether to render
+ * with the CS or Latin stack).
+ */
+export type RunScriptContext = {
+    /**
+     * w:rPr/w:cs (§17.3.2.7). Forces complex-script formatting regardless of Unicode.
+     * Per the spec, absence != false: when omitted, the value inherits from the style
+     * hierarchy and ultimately falls back to Unicode-based script detection. Only set
+     * this field when the source explicitly carries w:cs - leave undefined otherwise so
+     * downstream consumers can distinguish "not set" from "explicitly off".
+     */
+    complexScript?: boolean;
+    /**
+     * Per-script language metadata, kept on separate fields per ECMA §17.3.2.20
+     * because each maps to a different formatting stack (Latin / CS / East Asian).
+     * Wave 1b consumes these to gate spellcheck and font-stack selection.
+     */
+    language?: {
+        /** w:rPr/w:lang/@val. Default (Latin) language tag. */
+        default?: string;
+        /** w:rPr/w:lang/@bidi. Complex-script language tag. */
+        complexScript?: string;
+        /** w:rPr/w:lang/@eastAsia. East Asian language tag. */
+        eastAsian?: string;
+    };
+};
+/**
+ * Read a paragraph's inline base direction from its attributes.
+ *
+ * Prefers the resolved {@link ParagraphDirectionContext} (SD-2776) when
+ * present. Falls back to `paragraphProperties.rightToLeft` for PM-node /
+ * editor paths that store direction on the raw OOXML properties rather
+ * than the typed direction context.
+ *
+ * Consumers should call this instead of inspecting attrs ad hoc so the
+ * direction source check stays in one place.
+ */
+export declare function getParagraphInlineDirection(attrs: {
+    directionContext?: {
+        inlineDirection?: BaseDirection | null;
+    } | null;
+    paragraphProperties?: {
+        rightToLeft?: boolean | null;
+    } | null;
+} | null | undefined): BaseDirection | undefined;
+/**
+ * Read a table's visual direction (cell ordering axis) from its attributes.
+ *
+ * Prefers the resolved {@link TableDirectionContext} when present, falls
+ * back to the legacy `tableProperties.rightToLeft` (or `bidiVisual` alias)
+ * for compatibility. The AIDEV-NOTE on the fallback branch names the
+ * retirement signal.
+ *
+ * Per ECMA-376 §17.4.1, `w:bidiVisual` affects only cell ordering and
+ * table-visual properties. Cell paragraph inline direction is independent;
+ * use {@link getParagraphInlineDirection} for that axis.
+ *
+ * Consumers should call this instead of reading `tableProperties.rightToLeft`
+ * directly so the source check stays in one place and the resolver can take
+ * over once pm-adapter populates `tableDirectionContext` everywhere.
+ */
+export declare function getTableVisualDirection(attrs: {
+    tableDirectionContext?: {
+        visualDirection?: BaseDirection | null;
+    } | null;
+    tableProperties?: {
+        rightToLeft?: boolean | null;
+        bidiVisual?: boolean | null;
+    } | null;
+} | null | undefined): BaseDirection | undefined;

package/dist/layout-engine/contracts/src/drawing-taxonomy.d.ts

@@ -0,0 +1,126 @@
+import { DrawingKind } from './index.js';
+/**
+ * How a visual-object family is treated by drawing rendering.
+ *
+ * - `supported`: projected into a real layout contract and rendered.
+ * - `fail-closed`: preserved for save/reopen, never silently dropped, and
+ *   surfaced with a named diagnostic + placeholder instead of guessed output.
+ * - `deferred`: explicitly out of current scope; no support claim is made and
+ *   no rendering path is added unless a later plan pulls it in.
+ */
+export type DrawingSupportLevel = 'supported' | 'fail-closed' | 'deferred';
+/**
+ * Existing layout-contract target a supported family projects into. `none`
+ * marks families that are policies (e.g. `mc:AlternateContent` traversal) or
+ * have no layout target (fail-closed / deferred families).
+ *
+ * The string values intentionally match the public layout contract names in
+ * `index.ts` so the taxonomy is greppable against the real contracts.
+ */
+export type DrawingContractTarget = 'ImageRun' | 'ImageBlock' | 'ImageDrawing' | 'DrawingBlock' | 'selected-choice' | 'none';
+/**
+ * The `DrawingBlock` discriminant a supported drawing family maps to, when its
+ * contract target is `DrawingBlock`. Reuses the layout contract `DrawingKind`
+ * union so the taxonomy cannot drift from the painter's accepted kinds.
+ */
+export type DrawingTaxonomyDrawingKind = Extract<DrawingKind, 'vectorShape' | 'shapeGroup' | 'image' | 'chart'>;
+/**
+ * Frozen canonical diagnostic codes for drawing rendering.
+ *
+ * New extractor/adapter diagnostics MUST use these exact strings. Family-
+ * specific codes are required — do not collapse everything to
+ * `render.unsupported-inline-ooxml` (plan §4).
+ */
+export declare const DRAWING_DIAGNOSTIC_CODES: {
+    /** External image relationship (`r:link` / `TargetMode="External"`). Not fetched. */
+    readonly externalImageDeferred: "render.media.external-image-deferred";
+    /** Drawing references a relationship id that does not exist on the owner part. */
+    readonly missingRelationship: "render.drawing.missing-relationship";
+    /** Relationship resolves but the target media part bytes are missing/empty. */
+    readonly missingMediaPart: "render.media.missing-part";
+    /** Relationship exists but is not an image relationship type. */
+    readonly unsupportedRelationshipType: "render.drawing.unsupported-relationship-type";
+    /** Media MIME is not in the supported allowlist. */
+    readonly unsupportedMime: "render.media.unsupported-mime";
+    /** Media part exceeds the host byte-size policy before bytes are materialized. */
+    readonly imageTooLarge: "render.media.image-too-large";
+    /** SVG content rejected by the SVG safety policy. */
+    readonly unsafeSvg: "render.media.unsafe-svg";
+    /** Metafile / TIFF (EMF, WMF, TIFF) with no approved conversion path. */
+    readonly unsupportedFormat: "render.media.unsupported-format";
+    /** OLE / ActiveX / embedded package object. */
+    readonly embeddedObjectNotSupported: "render.embedded-object-not-supported";
+    /** SmartArt / diagram / unknown external graphic-data object. */
+    readonly unsupportedObject: "render.drawing.unsupported-object";
+    /** VML structure outside any supported image-like subset. */
+    readonly vmlUnsupported: "render.drawing.vml-unsupported";
+    /** VML image-like content that could not be promoted to a supported image. */
+    readonly vmlImageUnsupported: "render.drawing.vml-image-unsupported";
+    /** Custom geometry command the extractor does not implement (e.g. `arcTo`). */
+    readonly unsupportedGeometryCommand: "render.drawing.unsupported-geometry-command";
+    /** Anchor fields required for honest placement are unsupported. */
+    readonly anchorUnsupported: "render.drawing.anchor-unsupported";
+    /** Wrap fields required for honest placement are unsupported. */
+    readonly wrapUnsupported: "render.drawing.wrap-unsupported";
+    /** `mc:AlternateContent` had no supported choice and no usable fallback. */
+    readonly altContentNoSupportedChoice: "render.drawing.altcontent-no-supported-choice";
+    /** A child of an otherwise-supported group is unsupported. */
+    readonly groupChildUnsupported: "render.drawing.group-child-unsupported";
+};
+export type DrawingDiagnosticCode = (typeof DRAWING_DIAGNOSTIC_CODES)[keyof typeof DRAWING_DIAGNOSTIC_CODES];
+/**
+ * Existing pre-Phase-15 diagnostic codes that remain valid compatibility
+ * aliases (plan §4: "Existing resolver codes can remain compatibility aliases
+ * when they already exist"). Each maps to the canonical code it aliases so
+ * consumers and the Labs oracles can normalize without renaming live emitters.
+ *
+ * These remain emitted by the host resolver / adapter for now; the taxonomy does
+ * not rename live emitters in this plan. Later plans may converge emitters onto
+ * the canonical codes, but the aliases must keep resolving here until then.
+ */
+export declare const DRAWING_DIAGNOSTIC_CODE_ALIASES: Readonly<Record<string, DrawingDiagnosticCode>>;
+/**
+ * Every visual-object family the taxonomy classifies. Names are stable identifiers
+ * used by the extractor, adapter diagnostics, Labs summaries, and the closeout
+ * support matrix.
+ */
+export type DrawingFamily = 'inlineBitmap' | 'anchoredBitmap' | 'imageChildInGroup' | 'vectorShape' | 'shapeGroup' | 'chart' | 'alternateContent' | 'externalImage' | 'missingRelationship' | 'missingMediaPart' | 'wrongRelationshipType' | 'unsupportedMime' | 'oversizedMediaPart' | 'unsafeSvg' | 'metafileOrTiff' | 'embeddedObject' | 'smartArtOrDiagram' | 'vml' | 'vmlImageLike' | 'unsupportedGeometryCommand' | 'unsupportedAnchorFields' | 'unsupportedWrapFields' | 'alternateContentNoSupportedChoice' | 'groupChildUnsupported' | 'objectEditing' | 'customWrapPolygon' | 'chartFidelity' | 'vmlFidelity' | 'decorativeAccessibilityUi';
+/** Frozen classification record for a single visual-object family. */
+export interface DrawingFamilySpec {
+    readonly family: DrawingFamily;
+    readonly support: DrawingSupportLevel;
+    /** Human-facing one-line description for matrices and diagnostics. */
+    readonly description: string;
+    /** Layout-contract target for supported families; `none` otherwise. */
+    readonly contract: DrawingContractTarget;
+    /** `DrawingBlock` discriminant when `contract === 'DrawingBlock'`. */
+    readonly drawingKind?: DrawingTaxonomyDrawingKind;
+    /** Canonical diagnostic code for fail-closed families. */
+    readonly diagnostic?: DrawingDiagnosticCode;
+}
+/**
+ * The frozen drawing support taxonomy.
+ *
+ * Invariants (enforced by `drawing-taxonomy.test.ts`):
+ * - every `supported` family has a real contract target (`!== 'none'`);
+ * - every `DrawingBlock`-targeted family declares a `drawingKind`;
+ * - every `fail-closed` family declares a canonical `diagnostic`;
+ * - every canonical diagnostic code is referenced by at least one fail-closed
+ *   family;
+ * - `deferred` families make no support claim (`contract: 'none'`, no
+ *   diagnostic).
+ */
+export declare const DRAWING_SUPPORT_TAXONOMY: Readonly<Record<DrawingFamily, DrawingFamilySpec>>;
+/** Every classified family, in declaration order. */
+export declare const DRAWING_FAMILIES: readonly DrawingFamily[];
+/** Resolve a family's frozen classification spec. */
+export declare function getDrawingFamilySpec(family: DrawingFamily): DrawingFamilySpec;
+/** True when the family renders into a real layout contract. */
+export declare function isSupportedDrawingFamily(family: DrawingFamily): boolean;
+/**
+ * Normalize a possibly-aliased diagnostic code to its canonical code.
+ * Returns the canonical code when `code` is itself canonical, the aliased
+ * canonical code when `code` is a known compatibility alias, or `null` when the
+ * code is outside the drawing diagnostic vocabulary.
+ */
+export declare function canonicalDrawingDiagnosticCode(code: string): DrawingDiagnosticCode | null;

package/dist/layout-engine/contracts/src/engines/image-wrap.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @superdoc/engines-image-wrap contract
+ *
+ * Computes text wrapping exclusions for anchored images.
+ * Handles both rectangular (Square/TopAndBottom) and polygon-based (Tight/Through) wrapping.
+ */
+export interface WrapStyle {
+    type: 'None' | 'Square' | 'Tight' | 'Through' | 'TopAndBottom';
+    wrapText?: 'bothSides' | 'left' | 'right' | 'largest';
+    distTop?: number;
+    distBottom?: number;
+    distLeft?: number;
+    distRight?: number;
+    polygon?: number[][];
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Scale an OOXML wrap polygon to absolute page coordinates.
+ *
+ * OOXML polygons are expressed in EMUs relative to the image's native size.
+ * This function scales them to match the rendered image dimensions and position.
+ *
+ * @param ooxml - Array of [x, y] coordinate pairs from OOXML (in EMUs, 0-based)
+ * @param imageRect - Rendered image rectangle in pt
+ * @returns Scaled polygon in absolute page coordinates (pt)
+ */
+export declare function scaleWrapPolygon(ooxml: number[][], imageRect: Rect): number[][];
+/**
+ * Compute horizontal exclusion range for a line intersecting a wrapped image.
+ *
+ * For rectangular wrapping (Square/TopAndBottom):
+ * - Returns the image bounds + padding distances
+ *
+ * For polygon wrapping (Tight/Through):
+ * - Samples the polygon at the given Y coordinate
+ * - Returns the horizontal range occupied by the polygon at that height
+ *
+ * @param image - Image rectangle and wrap style
+ * @param lineY - Top Y coordinate of the text line (pt)
+ * @param lineHeight - Height of the text line (pt)
+ * @returns Exclusion range (left/right in pt), or null if no intersection
+ */
+export declare function computeWrapExclusion(image: {
+    rect: Rect;
+    wrap: WrapStyle;
+}, lineY: number, lineHeight: number): {
+    left: number;
+    right: number;
+} | null;

package/dist/layout-engine/contracts/src/engines/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Engine contracts for Word-specific layout logic.
+ *
+ * These pure functions implement Word's layout mathematics and are consumed
+ * by both PM plugins and the standalone layout pipeline to ensure consistent results.
+ *
+ * Design principles:
+ * - Pure functions only (no DOM/PM dependencies)
+ * - Inputs/outputs in pt (points, 1/72 inch)
+ * - Deterministic (same input → same output)
+ * - Triple-tested (unit, PM-vs-layout parity, Word golden corpus)
+ */
+export * from './paragraph.js';
+export * from './tabs.js';
+export * from './lists.js';
+export * from './image-wrap.js';
+export * from './tables.js';

package/dist/layout-engine/contracts/src/engines/lists.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @superdoc/engines-lists contract
+ *
+ * Formats list labels and computes hanging indents for multi-level numbering.
+ * Extracted from PM list helpers and DOCX numbering utilities to ensure consistent
+ * marker generation across PM and layout.
+ */
+export interface NumberingLevel {
+    format: 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman' | 'bullet' | 'custom';
+    text: string;
+    start: number;
+    indent: {
+        left: number;
+        hanging: number;
+    };
+    alignment?: 'left' | 'center' | 'right';
+}
+/**
+ * Format a list label from a numbering level definition.
+ *
+ * Handles template substitution (e.g., "%1." → "1."), numbering formats
+ * (Arabic, Roman, alphabetic), and custom bullet characters.
+ *
+ * @param level - Numbering level definition
+ * @param indices - Array of indices for each level (e.g., [1, 2] for "1.b")
+ * @returns Formatted label text and estimated width in pt
+ *
+ * @example
+ * formatListLabel(
+ *   { format: 'decimal', text: '%1.', start: 1, ... },
+ *   [3]
+ * ) // → { text: '3.', width: 12 }
+ *
+ * @example
+ * formatListLabel(
+ *   { format: 'lowerLetter', text: '%1)', start: 1, ... },
+ *   [2]
+ * ) // → { text: 'b)', width: 10 }
+ */
+export declare function formatListLabel(level: NumberingLevel, indices: number[]): {
+    text: string;
+    width: number;
+};
+/**
+ * Compute hanging indent values for a list level.
+ *
+ * Returns the marker width, hanging indent (marker gutter), and first-line indent
+ * based on the level's DOCX-derived indent metadata.
+ *
+ * @param level - Numbering level definition
+ * @returns Indent values in pt
+ */
+export declare function computeListIndent(level: NumberingLevel): {
+    labelWidth: number;
+    hangingIndent: number;
+    firstLineIndent: number;
+};

package/dist/layout-engine/contracts/src/engines/paragraph.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @superdoc/engines-paragraph contract
+ *
+ * Resolves paragraph spacing and indentation from computed styles and numbering overrides.
+ * Consumed by both PM adapter and layout measurer to ensure consistent geometry.
+ */
+export interface ParagraphSpacing {
+    before: number;
+    after: number;
+    line: number;
+    lineUnit?: 'px' | 'multiplier';
+    lineRule: 'auto' | 'exact' | 'atLeast';
+}
+export interface ParagraphIndent {
+    left: number;
+    right: number;
+    firstLine: number;
+    hanging: number;
+}
+/**
+ * Minimal subset of ComputedStyle required for spacing/indent resolution.
+ * The full ComputedStyle lives in @superdoc/style-engine.
+ */
+export interface ParagraphStyleInput {
+    spacing?: {
+        before?: number;
+        after?: number;
+        line?: number;
+        lineRule?: 'auto' | 'exact' | 'atLeast';
+    };
+    indent?: {
+        left?: number;
+        right?: number;
+        firstLine?: number;
+        hanging?: number;
+    };
+}
+export interface NumberingStyleInput {
+    indent?: {
+        left?: number;
+        hanging?: number;
+    };
+}
+/**
+ * Resolve final spacing and indentation values from styles + numbering overrides.
+ *
+ * Word resolution rules:
+ * 1. Start with base paragraph style spacing/indent
+ * 2. Apply numbering definition overrides (if list item)
+ * 3. Apply direct formatting overrides
+ *
+ * @param style - Computed paragraph style slice
+ * @param numbering - Optional numbering overrides (for list items)
+ * @returns Resolved spacing and indent in pt
+ */
+export declare function resolveSpacingIndent(style: ParagraphStyleInput, numbering?: NumberingStyleInput): {
+    spacing: ParagraphSpacing;
+    indent: ParagraphIndent;
+};

package/dist/layout-engine/contracts/src/engines/tables.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @superdoc/engines-tables contract (placeholder)
+ *
+ * Column width resolution and row measurement for tables.
+ * This is a placeholder for future Phase 2 work (tables pod).
+ */
+/**
+ * OOXML percentage divisor constant.
+ * OOXML stores percentages as 1/50ths of a percent:
+ * - 5000 = 100%
+ * - 2500 = 50%
+ * - 1000 = 20%
+ */
+export declare const OOXML_PCT_DIVISOR = 5000;
+/**
+ * Table width attribute from OOXML format.
+ * Represents table width specification with different types.
+ *
+ * @property width - Width value (alternative to value property)
+ * @property value - Width value (alternative to width property)
+ * @property type - Width type: 'pct' for percentage, 'px' or 'pixel' for pixels
+ *
+ * @example
+ * // Percentage width (50%)
+ * { value: 2500, type: 'pct' }
+ *
+ * @example
+ * // Pixel width
+ * { width: 600, type: 'px' }
+ */
+export interface TableWidthAttr {
+    width?: number;
+    value?: number;
+    type?: 'pct' | 'px' | 'pixel' | string;
+}
+/**
+ * Extract a validated numeric width from a table width attribute object.
+ *
+ * Supports either `width` or `value` fields and rejects non-finite or non-positive
+ * values so callers can safely use the result in layout calculations.
+ */
+export declare function resolveTableWidthAttr(value: unknown): {
+    width: number;
+    type?: TableWidthAttr['type'];
+} | null;
+export interface TableColumnSpec {
+    type: 'auto' | 'fixed' | 'pct';
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+}
+/**
+ * Resolve final column widths for a table.
+ *
+ * Implements Word's table width algorithm:
+ * - Fixed columns use their specified width
+ * - Percentage columns share proportionally
+ * - Auto columns distribute remaining space based on content
+ *
+ * @param columns - Column specifications from table grid
+ * @param availableWidth - Content area width in pt
+ * @returns Array of final column widths in pt
+ *
+ * @example
+ * resolveColumnWidths(
+ *   [
+ *     { type: 'fixed', width: 100 },
+ *     { type: 'auto' },
+ *     { type: 'pct', width: 50 }
+ *   ],
+ *   400
+ * ) // → [100, 150, 200] (fixed + auto + 50% of remaining)
+ */
+export declare function resolveColumnWidths(columns: TableColumnSpec[], availableWidth: number): number[];
+/**
+ * Measure row heights for a table given column widths.
+ *
+ * Future implementation will:
+ * - Measure cell content at the specified column width
+ * - Handle vertical alignment (top/middle/bottom)
+ * - Account for cell padding and borders
+ * - Support min/max row heights
+ *
+ * @param cells - 2D array of cell content (by row, then column)
+ * @param columnWidths - Resolved column widths in pt
+ * @returns Array of row heights in pt
+ */
+export declare function measureRowHeights(cells: unknown[][], // Placeholder - will be CellContent[][] in real implementation
+_columnWidths: number[]): number[];