oasis-editor 0.0.1 → 0.0.2

package/dist/plugins/internal/createEssentialsPlugin.d.ts

@@ -36,6 +36,7 @@ export interface EssentialsFormattingCapability {
     rejectRevisions: () => boolean;
     toggleShowMargins: () => boolean;
     toggleShowParagraphMarks: () => boolean;
+    togglePreciseFonts: () => boolean;
     pageBreak: () => boolean;
     lineBreak: () => boolean;
     splitBlock: () => boolean;
@@ -43,6 +44,7 @@ export interface EssentialsFormattingCapability {
     setFontSize: (value: number | null) => boolean;
     setColor: (value: string | null) => boolean;
     setHighlight: (value: string | null) => boolean;
+    setTextShading: (value: string | null) => boolean;
     setStyleId: (value: string) => boolean;
     setUnderlineStyle: (value: string | null) => void;
 }
@@ -56,7 +58,7 @@ export interface EssentialsDocumentCapability {
     documentStyles: () => EssentialsDocumentStyleDescriptor[];
     exportDocx: () => void;
     exportPdf: () => void;
-    importDocx: () => void;
+    importDocument: () => void;
     insertImage: () => void;
 }
 export interface EssentialsLinkCapability {
@@ -78,6 +80,7 @@ export interface EssentialsParagraphCapability {
     setSpacingAfter: (value: number | null) => void;
     setSpacingBefore: (value: number | null) => void;
     setIndentLeft: (value: number | null) => void;
+    setIndentRight: (value: number | null) => void;
     setIndentFirstLine: (value: number | null) => void;
     setIndentHanging: (value: number | null) => void;
     setShading: (value: string | null) => void;
@@ -93,6 +96,10 @@ export interface EssentialsSectionCapability {
     toggleOrientation: () => void;
     breakNextPage: () => void;
     breakContinuous: () => void;
+    setPageMargins: (margins: {
+        left?: number;
+        right?: number;
+    }) => void;
 }
 export interface EssentialsTableCapability {
     insideTable: () => boolean;

package/dist/react.d.ts

@@ -0,0 +1,12 @@
+import type React from "react";
+import type { OasisEditorAppProps, OasisEditorClient } from "oasis-editor";
+
+export type ReactOasisEditorProps = OasisEditorAppProps & {
+  /**
+   * Receives the mounted Oasis client. Props are mount-only for this adapter;
+   * remount the component to apply a new editor configuration.
+   */
+  onClient?: (client: OasisEditorClient) => void;
+};
+
+export declare const OasisEditor: React.FC<ReactOasisEditorProps>;

package/dist/react.js

@@ -0,0 +1,24 @@
+import React, { useEffect, useRef } from "react";
+import { mount } from "oasis-editor";
+
+export function OasisEditor(props) {
+  const containerRef = useRef(null);
+  const instanceRef = useRef(null);
+
+  useEffect(() => {
+    if (containerRef.current) {
+      instanceRef.current = mount(containerRef.current, props);
+      props.onClient?.(instanceRef.current);
+    }
+    return () => {
+      instanceRef.current?.unmount();
+      instanceRef.current = null;
+    };
+  }, []);
+
+  return React.createElement("div", {
+    ref: containerRef,
+    className: props.ui?.class,
+    style: props.ui?.style,
+  });
+}

package/dist/testing/wordLayoutParity.d.ts

@@ -4,8 +4,6 @@ export interface WordLayoutSupportStatus {
     supported: boolean;
     reason?: string;
     wordPath?: string;
-    pythonCommand?: string;
-    pythonArgs?: string[];
 }
 interface WordPdfLine {
     text: string;
@@ -54,7 +52,6 @@ export interface WordLayoutParityResult {
 export interface WordLayoutParityOptions {
     geometryTolerancePoints?: number;
     strictTextAndGeometry?: boolean;
-    layoutMode?: "fast" | "wordParity";
 }
 export declare function detectWordLayoutParitySupport(): WordLayoutSupportStatus;
 export declare function verifyWordLayoutParity(document: EditorDocument, options?: WordLayoutParityOptions): Promise<WordLayoutParityResult>;

package/dist/text/fonts/FontMetricsProvider.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Synchronous source of glyph advance widths for the layout engine, backed by
+ * the bundled metric-compatible fonts (Carlito≈Calibri, Arimo≈Arial,
+ * Tinos≈Times New Roman, Roboto as the universal fallback).
+ *
+ * Because these fonts are metric-compatible with the Office fonts they stand in
+ * for, advance widths match Microsoft Word — and, being parsed from the same
+ * bytes everywhere, they are identical in Node and the browser, which makes
+ * text layout deterministic across environments.
+ */
+export interface FontMetricsProvider {
+    /**
+     * Advance width in CSS pixels for a code point in the resolved face, or
+     * `null` when no metric face can supply it (font bytes not yet available, or
+     * the resolved face has no glyph for the code point — e.g. CJK/emoji). The
+     * caller then falls back to a heuristic.
+     */
+    getAdvanceWidthPx(family: string | null | undefined, bold: boolean, italic: boolean, codePoint: number, fontSizePx: number): number | null;
+    /**
+     * The face's natural single-spacing line height in CSS pixels (`ascender −
+     * descender + lineGap`), or `null` when no metric face is available. Used to
+     * locate the top of rendered text within a spaced line box.
+     */
+    getNaturalLineHeightPx(family: string | null | undefined, bold: boolean, italic: boolean, fontSizePx: number): number | null;
+    /**
+     * Word/PDF text-top offset in CSS pixels for the resolved face, or `null`
+     * when no metric face is available.
+     */
+    getWordTextTopOffsetPx(family: string | null | undefined, bold: boolean, italic: boolean, fontSizePx: number): number | null;
+}
+export declare function getFontMetricsProvider(): FontMetricsProvider;
+/**
+ * Loads (and parses) the bundled faces for the given families so that
+ * {@link FontMetricsProvider.getAdvanceWidthPx} resolves synchronously in the
+ * browser. Call this before the first layout/mount. In Node it is unnecessary
+ * (synchronous `fs` loading covers it) but harmless.
+ */
+export declare function preloadLayoutFonts(families?: Iterable<string | null | undefined>): Promise<void>;

package/dist/text/fonts/FontProgramFactory.d.ts

@@ -0,0 +1,6 @@
+import { PdfEmbeddableFont } from '../../core/types.js';
+import { SfntFontProgram } from '../../sfnt/SfntFontProgram.js';
+
+export declare function parseEmbeddedFont(sourceBytes: Uint8Array): Promise<SfntFontProgram>;
+export declare function parseEmbeddedFontSync(sourceBytes: Uint8Array): SfntFontProgram;
+export declare function createPdfEmbeddableFont(program: SfntFontProgram): PdfEmbeddableFont;

package/dist/text/fonts/core/types.d.ts

@@ -0,0 +1,69 @@
+import { Os2VerticalMetrics, VerticalMetrics } from '../../../../../truetype/tableParsers.js';
+
+export type FontFormat = "ttf" | "woff2";
+export interface FontDecoder {
+    readonly format: FontFormat;
+    canDecode(bytes: Uint8Array): boolean;
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+    decodeSync?(bytes: Uint8Array): Uint8Array;
+}
+export interface GlyphInfo {
+    readonly id: number;
+    readonly codePoints: number[];
+    readonly advanceWidth: number;
+}
+export interface GlyphPosition {
+    readonly xAdvance: number;
+}
+export interface GlyphRun {
+    readonly glyphs: GlyphInfo[];
+    readonly positions: GlyphPosition[];
+    readonly advanceWidth: number;
+}
+export interface FontMetadata {
+    readonly postscriptName: string;
+    readonly bbox: {
+        readonly minX: number;
+        readonly minY: number;
+        readonly maxX: number;
+        readonly maxY: number;
+    };
+    readonly ascent: number;
+    readonly descent: number;
+    readonly capHeight: number;
+    readonly xHeight: number;
+    readonly italicAngle: number;
+    readonly isFixedPitch: boolean;
+    readonly macStyleBold: boolean;
+    readonly macStyleItalic: boolean;
+    readonly familyClass: number;
+}
+export interface ParsedFontProgram {
+    readonly sfntBytes: Uint8Array;
+    readonly unitsPerEm: number;
+    readonly verticalMetrics: VerticalMetrics;
+    readonly os2VerticalMetrics: Os2VerticalMetrics | null;
+    readonly metadata: FontMetadata;
+    readonly glyphCount: number;
+    glyphForCodePoint(codePoint: number): number;
+    hasGlyphForCodePoint(codePoint: number): boolean;
+    advanceWidthForGlyph(glyphId: number): number;
+    getRawTableData(tag: string): Uint8Array | null;
+}
+export interface TextLayouter {
+    layout(text: string): GlyphRun;
+}
+export interface FontSubset {
+    readonly fontFile: Uint8Array;
+    readonly widths: number[];
+    readonly unicode: number[][];
+    encodeGlyph(glyphId: number): number;
+}
+export interface FontSubsetter {
+    createSubset(font: ParsedFontProgram, glyphs: Iterable<GlyphInfo>): FontSubset;
+}
+export interface PdfEmbeddableFont {
+    readonly program: ParsedFontProgram;
+    readonly layouter: TextLayouter;
+    readonly subsetter: FontSubsetter;
+}

package/dist/text/fonts/decoders/Brotli.d.ts

@@ -0,0 +1,4 @@
+export type BrotliDecompress = (bytes: Uint8Array) => Promise<Uint8Array>;
+export type BrotliDecompressSync = (bytes: Uint8Array) => Uint8Array;
+export declare const decompressBrotliSync: BrotliDecompressSync;
+export declare const decompressBrotli: BrotliDecompress;

package/dist/text/fonts/decoders/FontDecoderRegistry.d.ts

@@ -0,0 +1,10 @@
+import { FontDecoder } from '../../../../core/types.js';
+
+export declare class FontDecoderRegistry {
+    private readonly decoders;
+    constructor(decoders: FontDecoder[]);
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+    decodeSync(bytes: Uint8Array): Uint8Array;
+    private resolve;
+}
+export declare const defaultFontDecoderRegistry: FontDecoderRegistry;

package/dist/text/fonts/decoders/TtfDecoder.d.ts

@@ -0,0 +1,8 @@
+import { FontDecoder } from '../../../../core/types.js';
+
+export declare class TtfDecoder implements FontDecoder {
+    readonly format: "ttf";
+    canDecode(bytes: Uint8Array): boolean;
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+    decodeSync(bytes: Uint8Array): Uint8Array;
+}

package/dist/text/fonts/decoders/Woff2Decoder.d.ts

@@ -0,0 +1,45 @@
+import { FontDecoder } from '../../../../core/types.js';
+import { BrotliDecompress, BrotliDecompressSync } from '../../../Brotli.js';
+import { GlyfReconstruction } from '../../../../vendor/woff2/glyf-reconstructor.js';
+
+export interface Woff2Dependencies {
+    decompress?: BrotliDecompress;
+    decompressSync?: BrotliDecompressSync;
+    transformers?: Map<number, Woff2Transform>;
+}
+interface Woff2Table {
+    tag: number;
+    flags: number;
+    srcOffset: number;
+    srcLength: number;
+    transformLength: number;
+    dstLength: number;
+}
+interface Woff2Header {
+    flavor: number;
+    numTables: number;
+    compressedOffset: number;
+    compressedLength: number;
+    uncompressedSize: number;
+    tables: Woff2Table[];
+}
+interface TransformState {
+    glyfInfo: GlyfReconstruction | null;
+    numHMetrics: number;
+}
+interface TransformContext {
+    header: Woff2Header;
+    tableMap: Map<number, Uint8Array>;
+    tablesByTag: Map<number, Woff2Table>;
+    state: TransformState;
+}
+type Woff2Transform = (table: Woff2Table, srcData: Uint8Array, context: TransformContext) => void;
+export declare function decodeWoff2(fontData: Uint8Array, deps?: Partial<Woff2Dependencies>): Promise<Uint8Array>;
+export declare function decodeWoff2Sync(fontData: Uint8Array, deps?: Partial<Woff2Dependencies>): Uint8Array;
+export declare class Woff2Decoder implements FontDecoder {
+    readonly format: "woff2";
+    canDecode(bytes: Uint8Array): boolean;
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+    decodeSync(bytes: Uint8Array): Uint8Array;
+}
+export {};

package/dist/text/fonts/layout/SimpleTextLayouter.d.ts

@@ -0,0 +1,7 @@
+import { GlyphRun, ParsedFontProgram, TextLayouter } from '../../../../core/types.js';
+
+export declare class SimpleTextLayouter implements TextLayouter {
+    private readonly font;
+    constructor(font: ParsedFontProgram);
+    layout(text: string): GlyphRun;
+}

package/dist/text/fonts/preciseFontMetrics.d.ts

@@ -0,0 +1,16 @@
+import { SfntFontProgram } from '../../sfnt/SfntFontProgram.js';
+
+export declare function registerPreciseFont(family: string, bold: boolean, italic: boolean, program: SfntFontProgram): void;
+export declare function clearPreciseFonts(): void;
+/** Whether any real face is loaded for the family (ignores the mode flag). */
+export declare function hasPreciseFont(family: string | null | undefined): boolean;
+/** Whether a specific face has already been registered (used to skip reloads). */
+export declare function hasPreciseFontFace(family: string, bold: boolean, italic: boolean): boolean;
+/**
+ * The real font program for the requested face when precise mode is active and it
+ * was loaded, else `null`. Falls back to the regular face of the same family when
+ * the exact bold/italic face is not installed, so a paragraph never mixes real
+ * and substitute metrics within one family. Returns `null` when precise mode is
+ * off so callers transparently revert to the bundled substitute.
+ */
+export declare function getPreciseFontProgram(family: string | null | undefined, bold: boolean, italic: boolean): SfntFontProgram | null;

package/dist/text/fonts/preciseFontMode.d.ts

@@ -0,0 +1,7 @@
+/** Reactive accessor that bumps whenever precise-mode state changes. */
+export declare const preciseFontModeVersion: import('../../solid-js').Accessor<number>;
+export declare function isPreciseFontModeEnabled(): boolean;
+export declare function setPreciseFontModeEnabled(value: boolean): void;
+export declare function setAvailableLocalFontFamilies(families: Iterable<string>): void;
+/** True when the given (document-requested) family is installed locally. */
+export declare function isLocalFontFamilyAvailable(fontFamily: string | null | undefined): boolean;

package/dist/text/fonts/sfnt/SfntFontProgram.d.ts

@@ -0,0 +1,29 @@
+import { FontMetadata, ParsedFontProgram } from '../../../../core/types.js';
+
+export declare class SfntFontProgram implements ParsedFontProgram {
+    readonly sfntBytes: Uint8Array;
+    private readonly directory;
+    readonly unitsPerEm: number;
+    readonly verticalMetrics: import('../../../../../truetype/tableParsers.js').VerticalMetrics;
+    readonly os2VerticalMetrics: import('../../../../../truetype/tableParsers.js').Os2VerticalMetrics | null;
+    readonly metadata: FontMetadata;
+    readonly glyphCount: number;
+    private readonly cmap;
+    private readonly advanceForGlyph;
+    private constructor();
+    static parse(sfntBytes: Uint8Array): SfntFontProgram;
+    /**
+     * Every face in the bytes: one program for a plain sfnt, or one per sub-font
+     * for a TrueType Collection (`ttcf`). Lets the caller select the exact
+     * bold/italic face by its name/macStyle instead of taking the first font.
+     */
+    static parseCollection(sfntBytes: Uint8Array): SfntFontProgram[];
+    glyphForCodePoint(codePoint: number): number;
+    hasGlyphForCodePoint(codePoint: number): boolean;
+    advanceWidthForGlyph(glyphId: number): number;
+    advanceWidthForCodePoint(codePoint: number): number;
+    getRawTableData(tag: string): Uint8Array | null;
+    naturalLineHeightPx(fontSizePx: number): number;
+    wordTextTopOffsetPx(fontSizePx: number): number;
+    private parseMetadata;
+}

package/dist/text/fonts/vendor/woff2/buffer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lightweight byte reader with bounds checks used by the WOFF2 decoder.
+ */
+export declare class Buf {
+    private readonly data;
+    offset: number;
+    constructor(data: Uint8Array, offset?: number);
+    get length(): number;
+    peekRemaining(): Uint8Array;
+    readU8(): number;
+    readU16(): number;
+    readS16(): number;
+    readU32(): number;
+    readBytes(n: number): Uint8Array;
+    skip(n: number): void;
+}
+/**
+ * Read a Base128 variable-length integer.
+ */
+export declare function readBase128(buf: Buf): number;
+/**
+ * Read a 255UInt16 as defined in the WOFF2 spec.
+ */
+export declare function read255UShort(buf: Buf): number;

package/dist/text/fonts/vendor/woff2/glyf-reconstructor.d.ts

@@ -0,0 +1,55 @@
+import { Buf } from '../../../../buffer.js';
+
+export declare const GLYF_FLAGS: {
+    ON_CURVE: number;
+    X_SHORT: number;
+    Y_SHORT: number;
+    REPEAT: number;
+    X_SAME: number;
+    Y_SAME: number;
+    OVERLAP_SIMPLE: number;
+};
+export declare const COMPOSITE_FLAGS: {
+    ARG_WORDS: number;
+    WE_HAVE_A_SCALE: number;
+    MORE_COMPONENTS: number;
+    WE_HAVE_AN_XY_SCALE: number;
+    WE_HAVE_A_TWO_BY_TWO: number;
+    WE_HAVE_INSTRUCTIONS: number;
+};
+export interface GlyfReconstruction {
+    glyfData: Uint8Array;
+    locaData: Uint8Array;
+    glyfChecksum: number;
+    locaChecksum: number;
+    numGlyphs: number;
+    indexFormat: number;
+    xMins: Int16Array;
+}
+export declare function withSign(flag: number, base: number): number;
+export declare function tripletDecode(flagsIn: Uint8Array, data: Uint8Array, nPoints: number): {
+    points: {
+        x: number;
+        y: number;
+        onCurve: boolean;
+    }[];
+    consumed: number;
+};
+export declare function storePoints(points: {
+    x: number;
+    y: number;
+    onCurve: boolean;
+}[], nContours: number, instructionLength: number, hasOverlap: boolean): Uint8Array;
+export declare function computeBBox(points: {
+    x: number;
+    y: number;
+}[]): [number, number, number, number];
+export declare function sizeOfComposite(stream: Buf): {
+    size: number;
+    haveInstructions: boolean;
+};
+export declare function storeLoca(locaValues: number[], indexFormat: number): {
+    data: Uint8Array;
+    checksum: number;
+};
+export declare function reconstructGlyfTable(transformed: Uint8Array, locaDstLength: number): GlyfReconstruction;

package/dist/text/fonts/vendor/woff2/hmtx-reconstructor.d.ts

@@ -0,0 +1,5 @@
+export declare function readNumHMetrics(hheaTable: Uint8Array): number;
+export declare function reconstructTransformedHmtx(transformed: Uint8Array, numGlyphs: number, numHMetrics: number, xMins: Int16Array): {
+    data: Uint8Array;
+    checksum: number;
+};

package/dist/text/fonts/vendor/woff2/sfnt-builder.d.ts

@@ -0,0 +1,7 @@
+export declare const SFNT_HEADER_SIZE = 12;
+export declare const SFNT_ENTRY_SIZE = 16;
+export declare const CHECKSUM_ADJUSTMENT_OFFSET = 8;
+export declare function buildSfnt(flavor: number, tableData: Map<number, Uint8Array>): {
+    ttf: Uint8Array;
+    tables: Record<string, Uint8Array>;
+};

package/dist/text/fonts/vendor/woff2/utils.d.ts

@@ -0,0 +1,12 @@
+export declare const TAG: (text: string) => number;
+export declare const TAG_GLYF: number;
+export declare const TAG_LOCA: number;
+export declare const TAG_HMTX: number;
+export declare const TAG_HHEA: number;
+export declare const TAG_HEAD: number;
+export declare const KNOWN_TAGS: number[];
+export declare function tagToString(tag: number): string;
+export declare const round4: (v: number) => number;
+export declare function computeULongSum(data: Uint8Array): number;
+export declare function store16(value: number, out: Uint8Array, offset: number): number;
+export declare function store32(value: number, out: Uint8Array, offset: number): number;

package/dist/text/truetype/AdvanceWidthSource.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Contract for a source of horizontal glyph advance widths.
+ *
+ * Implementations expose just enough of a font's metrics to drive text layout:
+ * the design grid (`unitsPerEm`) and the advance width of any Unicode code
+ * point. Consumers depend on this interface rather than a concrete parser, so
+ * the layout engine stays decoupled from the TrueType binary format.
+ */
+export interface AdvanceWidthSource {
+    /** Font design units per em (from the `head` table), e.g. 2048 or 1000. */
+    readonly unitsPerEm: number;
+    /**
+     * Advance width, in font design units, for a Unicode code point. Returns the
+     * `.notdef` (glyph 0) advance when the code point is not mapped by the font.
+     */
+    advanceWidthForCodePoint(codePoint: number): number;
+    /** True when the font's `cmap` maps this code point to a non-zero glyph id. */
+    hasGlyphForCodePoint(codePoint: number): boolean;
+}

package/dist/text/truetype/BinaryReader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A forward/seekable cursor over a byte buffer that reads big-endian integers.
+ *
+ * The sfnt container (TrueType/OpenType) is always big-endian, so every
+ * multi-byte read goes through `DataView`, whose getters are big-endian by
+ * default. Reading multi-byte values via typed-array views over the raw buffer
+ * would adopt the host's endianness — the single most common font-parsing bug —
+ * so this reader never does that.
+ */
+export declare class BinaryReader {
+    private readonly bytes;
+    private readonly view;
+    private cursor;
+    constructor(bytes: Uint8Array);
+    get length(): number;
+    tell(): number;
+    seek(offset: number): void;
+    skip(byteCount: number): void;
+    private ensure;
+    u8(): number;
+    u16(): number;
+    i16(): number;
+    u32(): number;
+    /** Reads a 4-byte sfnt tag as an ASCII string (e.g. "cmap", "head"). */
+    tag(): string;
+    /** Absolute (non-advancing) big-endian uint16 read. */
+    u16At(offset: number): number;
+}

package/dist/text/truetype/CmapParser.d.ts

@@ -0,0 +1,15 @@
+import { BinaryReader } from '../../BinaryReader.js';
+
+/** Maps Unicode code points to glyph ids. Returns 0 (.notdef) when unmapped. */
+export interface CmapSubtable {
+    glyphForCodePoint(codePoint: number): number;
+}
+/**
+ * Parses the `cmap` table and selects the best Unicode subtable.
+ *
+ * Preference order favours the Windows platform with the widest coverage:
+ *   (3,10) format 12 full Unicode → (3,1) format 4 BMP → (0,*) Unicode → first.
+ * Only formats 4 and 12 are supported; they cover essentially all modern
+ * TrueType/OpenType text fonts.
+ */
+export declare function parseCmap(reader: BinaryReader, cmapOffset: number): CmapSubtable;

package/dist/text/truetype/SfntTableDirectory.d.ts

@@ -0,0 +1,26 @@
+import { BinaryReader } from '../../BinaryReader.js';
+
+export interface SfntTableRecord {
+    offset: number;
+    length: number;
+}
+/**
+ * The sfnt table directory: the 12-byte offset table plus the 16-byte table
+ * records that locate every table (`head`, `hhea`, `cmap`, ...) within the
+ * font. TrueType Collections (`ttcf`) are unwrapped to their first font.
+ */
+export declare class SfntTableDirectory {
+    private readonly tables;
+    private constructor();
+    static parse(reader: BinaryReader): SfntTableDirectory;
+    /**
+     * Sub-font sfnt offsets when the bytes are a TrueType Collection (`ttcf`), or
+     * `null` for a plain single-face sfnt. Lets callers pick a specific face
+     * (regular/bold/italic) rather than always unwrapping to the first font.
+     */
+    static collectionOffsets(reader: BinaryReader): number[] | null;
+    /** Parses the table directory whose offset table begins at `sfntOffset`. */
+    static parseAt(reader: BinaryReader, sfntOffset: number): SfntTableDirectory;
+    getTable(tag: string): SfntTableRecord | undefined;
+    requireTable(tag: string): SfntTableRecord;
+}

package/dist/text/truetype/TrueTypeFont.d.ts

@@ -0,0 +1,36 @@
+import { AdvanceWidthSource } from '../../AdvanceWidthSource.js';
+import { VerticalMetrics } from '../../tableParsers.js';
+
+/**
+ * A minimal TrueType/OpenType font parser that exposes horizontal advance
+ * widths. It reads only the tables needed for text measurement
+ * (`head`, `hhea`, `maxp`, `hmtx`, `cmap`) — no glyph outlines, no kerning.
+ *
+ * Construct via {@link TrueTypeFont.parse}; it throws {@link TrueTypeParseError}
+ * on malformed or unsupported fonts so callers can fall back gracefully.
+ */
+export declare class TrueTypeFont implements AdvanceWidthSource {
+    readonly unitsPerEm: number;
+    readonly verticalMetrics: VerticalMetrics;
+    private readonly os2VerticalMetrics;
+    private readonly cmap;
+    private readonly advanceForGlyph;
+    private constructor();
+    static parse(bytes: Uint8Array): TrueTypeFont;
+    /**
+     * The font's natural (single-spacing) line height in px — `ascender −
+     * descender + lineGap` scaled to the font size. This is the em box Word lays
+     * a line of text into before any line-spacing multiple is applied.
+     */
+    naturalLineHeightPx(fontSizePx: number): number;
+    /**
+     * Distance from the line-box top to the top of the rendered text in Word's
+     * PDF output. Word places the baseline at `usWinAscent`; the parity PDF
+     * extractor reports the typographic text top from the font descriptor
+     * ascender, so the delta is stable regardless of paragraph line spacing or
+     * docGrid snapping.
+     */
+    wordTextTopOffsetPx(fontSizePx: number): number;
+    advanceWidthForCodePoint(codePoint: number): number;
+    hasGlyphForCodePoint(codePoint: number): boolean;
+}

package/dist/text/truetype/TrueTypeParseError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raised when a font buffer cannot be parsed as a usable sfnt/TrueType font
+ * (missing required tables, truncated data, or an unsupported `cmap` layout).
+ *
+ * Callers that load fonts opportunistically (e.g. a metrics registry falling
+ * back to a heuristic) can catch this to degrade gracefully instead of failing
+ * the whole layout pass.
+ */
+export declare class TrueTypeParseError extends Error {
+    constructor(message: string);
+}

package/dist/text/truetype/tableParsers.d.ts

@@ -0,0 +1,45 @@
+import { BinaryReader } from '../../BinaryReader.js';
+
+/** Reads `unitsPerEm` from the `head` table (located at byte offset 18). */
+export declare function parseHeadUnitsPerEm(reader: BinaryReader, offset: number): number;
+/**
+ * Reads `numberOfHMetrics` (the count of long horizontal metrics) from the
+ * `hhea` table (located at byte offset 34).
+ */
+export declare function parseHheaNumberOfHMetrics(reader: BinaryReader, offset: number): number;
+/** The font's vertical metrics, in font design units. */
+export interface VerticalMetrics {
+    /** Distance from the baseline to the top of the em box (`hhea.ascender`). */
+    ascent: number;
+    /** Distance from the baseline to the bottom (`hhea.descender`, negative). */
+    descent: number;
+    /** Recommended extra spacing between lines (`hhea.lineGap`). */
+    lineGap: number;
+}
+/** OS/2 metrics Word uses to position text within a line box. */
+export interface Os2VerticalMetrics {
+    /** Typographic ascender (`OS/2.sTypoAscender`). */
+    typoAscender: number;
+    /** Windows ascender (`OS/2.usWinAscent`). */
+    winAscent: number;
+}
+/**
+ * Reads the vertical metrics from the `hhea` table: `ascender` (offset 4),
+ * `descender` (offset 6) and `lineGap` (offset 8), all signed font units.
+ */
+export declare function parseHheaVerticalMetrics(reader: BinaryReader, offset: number): VerticalMetrics;
+/**
+ * Reads the OS/2 vertical metrics needed to locate the rendered text top.
+ * Returns `null` for very old/incomplete fonts that do not expose these fields.
+ */
+export declare function parseOs2VerticalMetrics(reader: BinaryReader, offset: number, length: number): Os2VerticalMetrics | null;
+/** Reads `numGlyphs` from the `maxp` table (located at byte offset 4). */
+export declare function parseMaxpNumGlyphs(reader: BinaryReader, offset: number): number;
+/**
+ * Builds a glyph-id → advance-width lookup from the `hmtx` table.
+ *
+ * `hmtx` stores `numberOfHMetrics` `longHorMetric` records (advanceWidth:u16,
+ * lsb:i16). Glyph ids at or beyond that count reuse the *last* record's advance
+ * — the trailing-run convention used by fonts with a monospaced glyph tail.
+ */
+export declare function parseHmtxAdvances(reader: BinaryReader, offset: number, numberOfHMetrics: number): (glyphId: number) => number;