superdoc 2.2.0 → 2.3.0

package/dist/word-layout/src/index.d.ts

@@ -0,0 +1,64 @@
+import { WordParagraphLayoutInput, WordParagraphLayoutOutput } from './types.js';
+export * from './types.js';
+export { TWIPS_PER_PIXEL, PIXELS_PER_TWIP, TWIPS_PER_POINT, POINTS_PER_TWIP, pixelsToTwips, twipsToPixels, pointsToTwips, twipsToPoints, halfPointsToPoints, pointsToHalfPoints, } from './unit-conversions.js';
+export { LIST_MARKER_GAP, DEFAULT_LIST_HANGING_PX } from './marker-utils.js';
+export type { NumberingFormat } from './marker-utils.js';
+export { createNumberingManager } from './numbering-manager.js';
+export type { NumberingManager, NumberingManagerSnapshot, NumberingCursor } from './numbering-manager.js';
+export { computeWordListMarker } from './list-marker.js';
+export type { ComputeWordListMarkerInput, ComputeWordListMarkerResult, WordListMarkerDefinition, } from './list-marker.js';
+/**
+ * Computes the complete layout properties for a Word paragraph, including indentation,
+ * tabs, and optional list marker positioning.
+ *
+ * This is the main entry point for Word paragraph layout calculation. It processes
+ * paragraph properties, document defaults, and optional numbering to produce a complete
+ * layout specification that can be used for rendering.
+ *
+ * @param input - The paragraph layout input containing paragraph properties, document defaults,
+ *   optional numbering information, and an optional measurement adapter for calculating text widths.
+ *
+ * @returns A complete layout specification including:
+ *   - `indentLeftPx`: Left indent in pixels
+ *   - `hangingPx`: Hanging indent in pixels (clamped to >= 0)
+ *   - `firstLinePx`: First line indent in pixels (if specified)
+ *   - `tabsPx`: Array of tab stop positions in pixels
+ *   - `textStartPx`: Horizontal position where paragraph text begins
+ *   - `marker`: Optional list marker layout (position, text, styling)
+ *   - `resolvedIndent`: Merged indent configuration
+ *   - `resolvedTabs`: Resolved tab stops
+ *   - `defaultTabIntervalPx`: Default tab interval in pixels
+ *   - `firstLineIndentMode`: Boolean flag indicating firstLine indent pattern detection.
+ *     When true, this indicates the paragraph uses OOXML's alternative list indent pattern
+ *     where the marker is positioned at `left + firstLine` instead of the standard
+ *     `left - hanging` pattern. This flag is set when `firstLine > 0` and `hanging` is
+ *     not defined. It affects marker positioning and tab spacing calculations in the renderer.
+ *
+ * @example
+ * ```typescript
+ * // Standard hanging indent pattern
+ * const layout1 = computeWordParagraphLayout({
+ *   paragraph: {
+ *     indent: { left: 720, hanging: 720 },
+ *     tabs: [],
+ *     numberingProperties: { numId: '1', ilvl: 0, format: 'decimal', lvlText: '%1.', path: [1] }
+ *   },
+ *   docDefaults: { run: { fontFamily: 'Calibri', fontSize: 12 } }
+ * });
+ * // layout1.firstLineIndentMode is undefined (standard pattern)
+ * // Marker positioned at: left (720) - hanging (720) = 0
+ *
+ * // FirstLine indent pattern (alternative OOXML style)
+ * const layout2 = computeWordParagraphLayout({
+ *   paragraph: {
+ *     indent: { left: 0, firstLine: 720 },
+ *     tabs: [],
+ *     numberingProperties: { numId: '1', ilvl: 0, format: 'decimal', lvlText: '%1.', path: [1] }
+ *   },
+ *   docDefaults: { run: { fontFamily: 'Calibri', fontSize: 12 } }
+ * });
+ * // layout2.firstLineIndentMode is true
+ * // Marker positioned at: left (0) + firstLine (720) = 720
+ * ```
+ */
+export declare function computeWordParagraphLayout(input: WordParagraphLayoutInput): WordParagraphLayoutOutput;

package/dist/word-layout/src/list-marker.d.ts

@@ -0,0 +1,68 @@
+import { NumberingManager } from './numbering-manager.js';
+import { ListRenderingAttrs } from './types.js';
+export interface WordListMarkerDefinition {
+    /** Concrete numId. */
+    numId: number | string;
+    /** Abstract numbering id for shared counter scoping. */
+    abstractId: number | string;
+    /** Level index. */
+    ilvl: number;
+    /** Resolved level start value (override-aware). */
+    start: number;
+    /** True if the start value came from `w:lvlOverride/w:startOverride`. */
+    startOverridden: boolean;
+    /** `w:lvlRestart` value when defined. */
+    restart?: number;
+    /** Level text template. May be empty when none defined. */
+    lvlText?: string;
+    /** Effective `w:numFmt/@w:val`. */
+    numFmt?: string;
+    /** Custom format string when `numFmt === 'custom'`. */
+    customFormat?: string;
+    /** `w:suff`. Defaults to `tab` when absent. */
+    suffix?: string;
+    /** `w:lvlJc`. Defaults to `left`. */
+    justification?: string;
+    /**
+     * Effective start settings for ancestor levels `0..ilvl-1`. Registered with
+     * `ensureStartSettings` (register-if-absent) before the marker path is
+     * computed so first-emitted nested markers fall back to OOXML-defined
+     * ancestor starts instead of `1`. Real ancestor counters still win.
+     */
+    ancestorStartSettings?: Array<{
+        ilvl: number;
+        start: number;
+        restart?: number;
+        startOverridden: boolean;
+    }>;
+}
+export interface ComputeWordListMarkerInput {
+    /** Resolved marker definition. */
+    definition: WordListMarkerDefinition;
+    /**
+     * Numbering manager instance carrying counter state for this projection.
+     * The caller must have already called `setStartSettings(...)` for the
+     * paragraph's level (this is typically done up-front per (numId, level)
+     * pair when paragraphs are first walked).
+     */
+    manager: NumberingManager;
+    /**
+     * Source-order key for this paragraph. Must be monotonically increasing
+     * for paragraphs within a projection so the counter manager can detect
+     * previous siblings.
+     */
+    paragraphOrdinal: number;
+}
+export interface ComputeWordListMarkerResult {
+    listRenderingAttrs: ListRenderingAttrs;
+    /** Computed numeric counter path. Useful for callers that want it directly. */
+    path: number[];
+    /** Effective counter value at the requested ilvl. */
+    counter: number;
+}
+/**
+ * Compute the marker text, list-rendering attributes, and counter path for
+ * one numbered paragraph. Advances the manager state by recording the new
+ * counter at the given paragraph ordinal.
+ */
+export declare function computeWordListMarker(input: ComputeWordListMarkerInput): ComputeWordListMarkerResult;

package/dist/word-layout/src/marker-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Union type representing all supported numbering format types.
+ * These formats determine how list markers are displayed.
+ */
+export type NumberingFormat = 'bullet' | 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman';
+/**
+ * Default hanging indent for list items in pixels.
+ * This value determines the horizontal offset between the marker and the text content.
+ */
+export declare const DEFAULT_LIST_HANGING_PX = 18;
+/**
+ * Gap between the list marker and the text content in pixels.
+ * This spacing ensures visual separation between the marker and the paragraph text.
+ */
+export declare const LIST_MARKER_GAP = 8;
+/**
+ * Default bullet character used when no specific bullet glyph is provided.
+ * The bullet point (•) is the standard Unicode character for unordered lists.
+ */
+export declare const DEFAULT_BULLET_GLYPH = "\u2022";

package/dist/word-layout/src/numbering-manager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Editor-neutral list counter manager. Keeps word-layout marker text stable for
+ * abstract-id shared counters and `w:lvlOverride/@w:startOverride` scoping.
+ *
+ * Behavior:
+ * - counters are tracked per abstractId so multiple concrete `numId`s sharing
+ *   the same abstract definition continue numbering across the document
+ * - a per-`(numId, level)` `startOverridden` flag scopes counters back to the
+ *   single concrete `numId` when an `lvlOverride/startOverride` is in play
+ * - cache mode keeps the fast `lastSeen*` lookup path used by runtime adapters
+ */
+type NumId = string | number;
+type Level = number;
+type Position = number;
+type CounterValue = number;
+type CounterLevelMap = Record<Position, CounterValue>;
+type CounterMap = Record<string, Record<Level, CounterLevelMap>>;
+type StartSettings = {
+    start: number;
+    restart?: number;
+    startOverridden?: boolean;
+};
+type StartsMap = Record<string, Record<Level, StartSettings>>;
+type LastSeenMap = Record<string, Record<Level, {
+    pos: number;
+    count: number;
+}>>;
+/**
+ * Opaque, same-realm numbering cursor. Its payload is one immutable persistent
+ * state root, so capture and restore are O(1); unchanged numbering scopes are
+ * structurally shared across every retained cursor. Restore is valid only
+ * within the JS realm that captured it and only in compact mode.
+ */
+export interface NumberingCursor {
+    readonly __wordLayoutNumberingCursor: true;
+}
+export interface NumberingManager {
+    setStartSettings(numId: NumId, level: number, startValue: number, restartValue?: number, startOverridden?: boolean): void;
+    ensureStartSettings(numId: NumId, level: number, startValue: number, restartValue?: number, startOverridden?: boolean): void;
+    setCounter(numId: NumId, level: number, pos: number, value: number, abstractId?: string | number): void;
+    getCounter(numId: NumId, level: number, pos: number): number | null;
+    calculateCounter(numId: NumId, level: number, pos: number, abstractId?: string | number): number;
+    getAncestorsPath(numId: NumId, level: number, pos: number): number[];
+    calculatePath(numId: NumId, level: number, pos: number): number[];
+    getCountersMap(): CounterMap;
+    exportSnapshot(): NumberingManagerSnapshot;
+    restoreSnapshot(snapshot: NumberingManagerSnapshot | null): void;
+    /**
+     * Capture a compact, same-realm cursor of current numbering state in O(1).
+     * The returned token is opaque and non-serializable by contract: passing it
+     * through `structuredClone` or a worker boundary strips its brand and
+     * `restoreCursor` rejects it. Throws unless compact mode is enabled.
+     */
+    captureCursor(): NumberingCursor;
+    /**
+     * Restore state in O(1) from a cursor produced in the same realm. Throws on a
+     * foreign/serialized cursor or when compact mode is not enabled; `null`
+     * resets to the empty state.
+     */
+    restoreCursor(cursor: NumberingCursor | null): void;
+    _clearCache(): void;
+    enableCache(): void;
+    disableCache(): void;
+    /**
+     * Enable compact (cursor-timeline) mode: the cache-fast lookup path PLUS
+     * suppression of the historical per-position counter maps and the
+     * position-keyed path cache. Sequential queries are served from last-seen
+     * facts. Current state is linear in active scopes, while retained cursors add
+     * only fixed-depth structurally shared transitions. Arbitrary past-position
+     * `getCounter` queries are not answerable in this mode; callers needing them
+     * must use the default (non-compact) mode.
+     */
+    enableCompactMode(): void;
+    clearAllState(): void;
+}
+export interface NumberingManagerSnapshot {
+    startsMap: StartsMap;
+    countersMap: CounterMap;
+    abstractCountersMap: CounterMap;
+    abstractIdMap: Record<string, string | undefined>;
+    lastSeenByAbstractIdMap: LastSeenMap;
+    lastSeenByNumIdMap: LastSeenMap;
+}
+export declare function createNumberingManager(): NumberingManager;
+export {};

package/dist/word-layout/src/tab-layout.d.ts

@@ -0,0 +1,193 @@
+import { ParagraphIndent, ResolvedTabStop } from './types.js';
+/**
+ * Tab alignment type supporting all Word-compatible alignment modes.
+ * Used throughout tab stop processing to ensure type safety.
+ */
+export type TabAlignment = 'start' | 'center' | 'end' | 'decimal' | 'bar' | 'num';
+/**
+ * Raw tab stop data as received from various document parsers.
+ *
+ * Different parsers may use different property names for the same concepts:
+ * - `val`, `align`, `alignment`, or `type` for alignment mode
+ * - `originalPos` for positions already in twips (no conversion needed)
+ * - `pos`, `position`, or `offset` for positions in pixels (require conversion to twips)
+ * - `leader` for the optional leader character style
+ *
+ * This flexible structure allows the normalization functions to handle
+ * tab stop data from multiple sources without requiring parser-specific code.
+ */
+export type RawTabStop = {
+    val?: string;
+    align?: string;
+    alignment?: string;
+    type?: string;
+    originalPos?: number;
+    pos?: number;
+    position?: number;
+    offset?: number;
+    leader?: 'none' | 'dot' | 'heavy' | 'hyphen' | 'middleDot' | 'underscore';
+};
+/**
+ * Normalized tab stop with positions standardized to twips.
+ *
+ * This is the intermediate format used during tab stop processing.
+ * All position values are guaranteed to be in twips (1/1440 inch),
+ * allowing consistent calculations regardless of the original source format.
+ * The alignment is validated and normalized to standard values.
+ */
+export type NormalizedTabStopTwips = {
+    alignment: TabAlignment;
+    positionTwips: number;
+    leader?: RawTabStop['leader'];
+};
+/**
+ * Options for computing the final set of tab stops.
+ *
+ * Controls whether to use explicit tab stops or generate default stops,
+ * and how to position default stops when generated.
+ */
+export type ComputeTabStopsOptions = {
+    /** Pre-normalized explicit tab stops to use instead of generating defaults */
+    explicitStops?: NormalizedTabStopTwips[];
+    /** Interval between default tab stops in twips (typically 720 = 0.5 inch) */
+    defaultTabIntervalTwips?: number;
+    /** Starting offset for default tab stop calculation (e.g., left indent) */
+    startTwips?: number;
+};
+/**
+ * Options for building the complete effective tab stop set.
+ *
+ * Integrates tab stops from multiple sources: paragraph-level explicit stops,
+ * paragraph-level defaults, and document-level defaults. Also handles
+ * decimal separator configuration for decimal-aligned tabs.
+ */
+export type BuildEffectiveTabStopsOptions = {
+    /** Raw tab stops defined explicitly on the paragraph */
+    explicitStops?: RawTabStop[];
+    /** Paragraph indentation affecting tab stop positioning */
+    paragraphIndent?: ParagraphIndent;
+    /** Paragraph-level default tab interval (overrides document default) */
+    paragraphTabIntervalTwips?: number;
+    /** Document-level default tab interval */
+    defaultTabIntervalTwips?: number;
+    /** Character to use for decimal alignment (e.g., '.' or ',') */
+    decimalSeparator?: string;
+};
+/**
+ * Normalizes alignment values from various formats to standard alignment types.
+ *
+ * Handles case-insensitive alignment names, legacy alignment values (left/right),
+ * and unknown values by mapping them to standard alignment types. This ensures
+ * consistent alignment handling across different document formats.
+ *
+ * @param value - Alignment value from document source (may be undefined, empty, or unknown)
+ * @returns Normalized TabAlignment, null if no valid alignment provided, or 'start' for unknown values
+ *
+ * @example
+ * ```typescript
+ * normalizeAlignment('LEFT')    // returns 'start'
+ * normalizeAlignment('Right')   // returns 'end'
+ * normalizeAlignment('decimal') // returns 'decimal'
+ * normalizeAlignment('')        // returns null
+ * normalizeAlignment('unknown') // returns 'start' (fallback)
+ * normalizeAlignment(undefined) // returns null
+ * ```
+ */
+export declare const normalizeAlignment: (value?: string) => TabAlignment | null;
+/**
+ * Normalizes raw tab stop data into a consistent format with positions in twips.
+ *
+ * This function processes various tab stop representations (which may use different
+ * property names and units) into a standardized format suitable for layout calculations.
+ * It handles alignment normalization, position unit conversion, and sorting.
+ *
+ * @param candidateStops - Array of raw tab stop objects from document parsing.
+ *   May be null, undefined, or contain malformed entries.
+ * @returns Array of normalized tab stops sorted by position, with positions in twips
+ *
+ * @example
+ * ```typescript
+ * const stops = normalizeExplicitTabStops([
+ *   { val: 'left', pos: 48 },           // Position in pixels
+ *   { val: 'right', originalPos: 1440 }, // Position in twips
+ *   { val: 'decimal', pos: 96, leader: 'dot' }
+ * ]);
+ *
+ * console.log(stops);
+ * // [
+ * //   { alignment: 'start', positionTwips: 720, leader: undefined },
+ * //   { alignment: 'end', positionTwips: 1440, leader: undefined },
+ * //   { alignment: 'decimal', positionTwips: 1440, leader: 'dot' }
+ * // ]
+ * ```
+ */
+export declare const normalizeExplicitTabStops: (candidateStops?: RawTabStop[] | null) => NormalizedTabStopTwips[];
+/**
+ * Computes the final list of tab stops, using either explicit stops or generating
+ * default stops at regular intervals.
+ *
+ * When explicit tab stops are provided, they are used directly. Otherwise, this function
+ * generates a default set of equally-spaced tab stops based on the default interval.
+ *
+ * @param options - Configuration for tab stop computation
+ * @param options.explicitStops - Pre-normalized explicit tab stops to use
+ * @param options.defaultTabIntervalTwips - Interval between default tab stops in twips
+ * @param options.startTwips - Starting offset for default tab stop calculation
+ * @returns Array of tab stops sorted by position
+ *
+ * @example
+ * ```typescript
+ * // Using explicit stops
+ * const explicit = computeTabStops({
+ *   explicitStops: [
+ *     { alignment: 'start', positionTwips: 720 },
+ *     { alignment: 'end', positionTwips: 1440 }
+ *   ]
+ * });
+ *
+ * // Generating default stops
+ * const defaults = computeTabStops({
+ *   defaultTabIntervalTwips: 720,
+ *   startTwips: 0
+ * });
+ * // Returns 12 stops at 720, 1440, 2160, ... twips
+ * ```
+ */
+export declare const computeTabStops: (options: ComputeTabStopsOptions) => NormalizedTabStopTwips[];
+/**
+ * Builds the complete set of effective tab stops in pixels, accounting for paragraph
+ * indentation and document defaults.
+ *
+ * This is the primary tab stop resolution function that integrates all sources of tab
+ * configuration: explicit paragraph tab stops, paragraph-level defaults, and document-level
+ * defaults. It also handles decimal separator characters for decimal-aligned tabs.
+ *
+ * @param options - Options for building effective tab stops
+ * @param options.explicitStops - Raw tab stops defined on the paragraph
+ * @param options.paragraphIndent - Paragraph indentation that affects tab stop positioning
+ * @param options.paragraphTabIntervalTwips - Paragraph-level default tab interval
+ * @param options.defaultTabIntervalTwips - Document-level default tab interval
+ * @param options.decimalSeparator - Character to use for decimal alignment (e.g., '.' or ',')
+ * @returns Array of resolved tab stops with positions in pixels
+ *
+ * @example
+ * ```typescript
+ * const stops = buildEffectiveTabStopsPx({
+ *   explicitStops: [
+ *     { val: 'decimal', pos: 96, leader: 'dot' }
+ *   ],
+ *   paragraphIndent: { left: 24 },
+ *   defaultTabIntervalTwips: 720,
+ *   decimalSeparator: ','
+ * });
+ *
+ * console.log(stops[0]);
+ * // {
+ * //   alignment: 'decimal',
+ * //   position: 96,
+ * //   leader: 'dot',
+ * //   decimalChar: ','
+ * // }
+ * ```
+ */
+export declare const buildEffectiveTabStopsPx: (options: BuildEffectiveTabStopsOptions) => ResolvedTabStop[];

package/dist/word-layout/src/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared type definitions for Word paragraph + list layout contracts.
+ */
+export type WordListSuffix = 'tab' | 'space' | 'nothing' | undefined;
+export type WordListJustification = 'left' | 'center' | 'right';
+export type ParagraphIndent = {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+};
+export type ParagraphSpacing = {
+    before?: number;
+    after?: number;
+    line?: number;
+    lineRule?: 'auto' | 'exact' | 'atLeast';
+};
+export type ResolvedTabStop = {
+    position: number;
+    alignment: 'start' | 'center' | 'end' | 'decimal' | 'bar' | 'num';
+    leader?: 'none' | 'dot' | 'heavy' | 'hyphen' | 'middleDot' | 'underscore';
+    decimalChar?: string;
+};
+type TabStop = {
+    val: 'start' | 'end' | 'center' | 'decimal' | 'bar' | 'clear';
+    pos: number;
+    leader?: 'none' | 'dot' | 'hyphen' | 'heavy' | 'underscore' | 'middleDot';
+};
+export type ResolvedRunProperties = {
+    fontFamily: string;
+    fontSize: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: {
+        style?: 'single' | 'double' | 'dotted' | 'dashed' | 'wavy';
+        color?: string;
+    } | null;
+    strike?: boolean;
+    color?: string;
+    highlight?: string;
+    smallCaps?: boolean;
+    allCaps?: boolean;
+    baselineShift?: number;
+    vertAlign?: 'superscript' | 'subscript' | 'baseline';
+    letterSpacing?: number;
+    scale?: number;
+    lang?: string;
+    vanish?: boolean;
+};
+export type NumberingProperties = {
+    numId?: number;
+    ilvl?: number;
+};
+export type ResolvedParagraphProperties = {
+    styleId?: string;
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    indent?: ParagraphIndent;
+    spacing?: ParagraphSpacing;
+    tabs?: TabStop[];
+    tabIntervalTwips?: number;
+    decimalSeparator?: string;
+    numberingProperties?: NumberingProperties | null;
+};
+export type WordLayoutMeasurementAdapter = {
+    measureText?: (text: string, fontCss: string, options?: {
+        letterSpacing?: number;
+    }) => number;
+};
+export type ListRenderingAttrs = {
+    markerText: string;
+    justification: WordListJustification;
+    path: number[];
+    numberingType: string;
+    suffix: 'tab' | 'space' | 'nothing';
+};
+export type WordParagraphLayoutInput = {
+    paragraph: ResolvedParagraphProperties;
+    listRenderingAttrs: ListRenderingAttrs;
+    markerRun: ResolvedRunProperties;
+};
+export type WordListMarkerLayout = {
+    markerText: string;
+    markerBoxWidthPx?: number;
+    glyphWidthPx?: number;
+    gutterWidthPx?: number;
+    justification: WordListJustification;
+    markerX?: number;
+    suffix: WordListSuffix;
+    textStartX?: number;
+    run: ResolvedRunProperties;
+};
+export type WordParagraphLayoutOutput = {
+    indentLeftPx: number;
+    hangingPx: number;
+    firstLinePx?: number;
+    tabsPx: number[];
+    textStartPx: number;
+    marker?: WordListMarkerLayout;
+    defaultTabIntervalPx?: number;
+    /**
+     * True when list uses firstLine indent pattern (marker at left+firstLine)
+     * instead of standard hanging pattern (marker at left-hanging).
+     */
+    firstLineIndentMode?: boolean;
+};
+export {};

package/dist/word-layout/src/unit-conversions.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared unit conversion helpers (twips, pixels, points).
+ *
+ * Word stores most layout values in twips (1/20th of a point). We convert
+ * to/from CSS pixels to keep the pipeline consistent across DOM, canvas,
+ * and PDF renderers.
+ */
+export declare const TWIPS_PER_INCH = 1440;
+export declare const POINTS_PER_INCH = 72;
+export declare const PIXELS_PER_INCH = 96;
+export declare const TWIPS_PER_POINT = 20;
+export declare const POINTS_PER_TWIP: number;
+export declare const TWIPS_PER_PIXEL: number;
+export declare const PIXELS_PER_TWIP: number;
+/**
+ * Converts CSS pixels to twips (twentieths of a point).
+ *
+ * Word documents store most measurements in twips, while web rendering uses pixels.
+ * This function performs the conversion with proper rounding to maintain precision.
+ * Invalid inputs (null, undefined, NaN, Infinity) return 0.
+ *
+ * @param px - The value in CSS pixels to convert. May be null or undefined.
+ * @returns The equivalent value in twips, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * pixelsToTwips(96);  // 1440 (1 inch = 96px = 1440 twips)
+ * pixelsToTwips(24);  // 360
+ * pixelsToTwips(null); // 0
+ * pixelsToTwips(NaN);  // 0
+ * ```
+ */
+export declare const pixelsToTwips: (px?: number | null) => number;
+/**
+ * Converts twips (twentieths of a point) to CSS pixels.
+ *
+ * This is the inverse of pixelsToTwips. Invalid inputs return 0.
+ *
+ * @param twips - The value in twips to convert. May be null or undefined.
+ * @returns The equivalent value in CSS pixels, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * twipsToPixels(1440); // 96 (1 inch)
+ * twipsToPixels(720);  // 48 (half inch)
+ * twipsToPixels(null); // 0
+ * ```
+ */
+export declare const twipsToPixels: (twips?: number | null) => number;
+/**
+ * Converts points to twips (twentieths of a point).
+ *
+ * Points are a standard typographic unit (72 points = 1 inch).
+ * This function converts them to twips for Word document storage.
+ * Invalid inputs (null, undefined, NaN, Infinity) return 0.
+ *
+ * @param points - The value in points to convert. May be null or undefined.
+ * @returns The equivalent value in twips, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * pointsToTwips(72);   // 1440 (1 inch = 72 points = 1440 twips)
+ * pointsToTwips(12);   // 240
+ * pointsToTwips(null); // 0
+ * ```
+ */
+export declare const pointsToTwips: (points?: number | null) => number;
+/**
+ * Converts twips (twentieths of a point) to points.
+ *
+ * This is the inverse of pointsToTwips. Points are a standard typographic
+ * unit where 72 points equals 1 inch. Invalid inputs return 0.
+ *
+ * @param twips - The value in twips to convert. May be null or undefined.
+ * @returns The equivalent value in points, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * twipsToPoints(1440); // 72 (1 inch)
+ * twipsToPoints(240);  // 12
+ * twipsToPoints(null); // 0
+ * ```
+ */
+export declare const twipsToPoints: (twips?: number | null) => number;
+/**
+ * Converts half-points to points.
+ *
+ * Word documents sometimes store measurements in half-points for finer
+ * granularity. This function converts them to standard points by dividing by 2.
+ * Invalid inputs (null, undefined, NaN, Infinity) return 0.
+ *
+ * @param halfPoints - The value in half-points to convert. May be null or undefined.
+ * @returns The equivalent value in points, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * halfPointsToPoints(24); // 12
+ * halfPointsToPoints(5);  // 2.5
+ * halfPointsToPoints(null); // 0
+ * ```
+ */
+export declare const halfPointsToPoints: (halfPoints?: number | null) => number;
+/**
+ * Converts points to half-points.
+ *
+ * This is the inverse of halfPointsToPoints. Half-points provide finer
+ * granularity for measurements in Word documents (2 half-points = 1 point).
+ * Invalid inputs (null, undefined, NaN, Infinity) return 0.
+ *
+ * @param points - The value in points to convert. May be null or undefined.
+ * @returns The equivalent value in half-points, or 0 if input is invalid
+ *
+ * @example
+ * ```typescript
+ * pointsToHalfPoints(12);   // 24
+ * pointsToHalfPoints(2.5);  // 5
+ * pointsToHalfPoints(null); // 0
+ * ```
+ */
+export declare const pointsToHalfPoints: (points?: number | null) => number;