@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/text/ITextFrame.d.ts

@@ -4,13 +4,14 @@ import { TextVisitor } from './TextVisitor';
 import { ITextLine } from './TextLine';
 import { ITextParagraph } from './TextParagraph';
 import { ITextBoxAlignment as _IAlignment } from './TextBoxAlignment';
+import { IText } from './IText';
 /**
  * Represents a rectangular container for text and its formatting within a document.
  *
  * A TextFrame allows precise control over the positioning, size (width and height),
  * layout, and appearance of text content.
  */
-export interface ITextFrame {
+export interface ITextFrame extends ITextFrame.IText {
     readonly wrapped: boolean;
     readonly insets: Rectangle;
     readonly orientation: ITextFrame.Orientation;
@@ -57,6 +58,8 @@ export interface ITextFrame {
      * @param allowWrap If `true` then will try to wrap on natural breaks. Defaults the the current settings.
      */
     createTextFrame(text: string, allowWrap?: boolean): ITextFrame;
+    /** For runtime type checking. */
+    readonly isITextFrame: true;
 }
 /**
  * {@inheritDoc ITextFrame}
@@ -66,6 +69,28 @@ export interface ITextFrame {
  * {@link ITextFrame}
  */
 export declare namespace ITextFrame {
+    /**
+     * The text of a frame, without its layout.
+     *
+     * @remarks
+     * What a frame can always answer, including one whose layout is not modeled — text on an
+     * imported shape is read this way.
+     */
+    interface IText {
+        /**
+         * Returns the frame's text with its formatting stripped.
+         *
+         * @remarks
+         * - Paragraphs are separated by `
+    `, and a line break inside a paragraph is also `
+    `.
+         * - Runs and fields are concatenated in document order.
+         * - Blank paragraphs at the start and end are dropped; blank paragraphs between text are kept.
+         * - An equation reads as its linear text form.
+         * - A frame with nothing written in it answers `''`.
+         */
+        getText(): string;
+    }
     namespace IAlignment {
         type Properties = _IAlignment.Properties;
         type JSON = _IAlignment.JSON;
@@ -299,8 +324,92 @@ export declare namespace ITextFrame {
          * Centers text at the tab stop.
          */
         readonly Center: "center";
+        /**
+         * Aligns numbers at the tab stop on their decimal point.
+         */
+        readonly Decimal: "decimal";
     };
     type TabStopAlignment = typeof TabStopAlignment[keyof typeof TabStopAlignment];
+    /**
+     * The direction drawing text runs in its body.
+     */
+    const WritingMode: {
+        readonly Horizontal: "horizontal";
+        /** Each line turned 90° clockwise, read top to bottom; lines advance leftwards. */
+        readonly Vertical: "vertical";
+        /** Each line turned 270° clockwise, read bottom to top; lines advance rightwards. */
+        readonly Vertical270: "vertical270";
+        /** WordArt vertical: upright letters stacked top to bottom. */
+        readonly WordArtVertical: "wordArtVertical";
+        /** East Asian vertical: upright ideographs, Latin text turned. */
+        readonly EastAsianVertical: "eastAsianVertical";
+        /** Mongolian vertical: top to bottom, lines advancing rightwards. */
+        readonly MongolianVertical: "mongolianVertical";
+        /** WordArt vertical read right to left. */
+        readonly WordArtVerticalRtl: "wordArtVerticalRtl";
+    };
+    type WritingMode = typeof WritingMode[keyof typeof WritingMode];
+    /** Text insets from the text rectangle, in pixels. */
+    interface InsetsJSON {
+        left?: number;
+        top?: number;
+        right?: number;
+        bottom?: number;
+    }
+    /** How a text body sits in the frame that holds it. */
+    interface BodyJSON {
+        /** Vertical anchor of the text in the frame. */
+        anchor?: VerticalAlignment;
+        /** Center the text box horizontally within the frame. */
+        anchorCenter?: boolean;
+        wrap?: 'none' | 'square';
+        insets?: InsetsJSON;
+        /** `shape` grows the frame to fit the text; `normal` shrinks the text to fit the frame. */
+        autoFit?: Autofit;
+        /** With `normal` autofit: the font scale applied, as a percentage. */
+        fontScale?: number;
+        /** With `normal` autofit: the line spacing reduction applied, as a percentage. */
+        lineSpacingReduction?: number;
+        vertical?: WritingMode;
+        /** What happens to text past the bottom: `visible`, `ellipsis` or `clip`. */
+        verticalOverflow?: Overflow;
+        /** What happens to text past the sides: `visible` or `clip`. */
+        horizontalOverflow?: Overflow;
+        upright?: boolean;
+        rightToLeftColumns?: boolean;
+        columns?: number;
+        /** Space between columns, in pixels. */
+        columnSpacing?: number;
+        fromWordArt?: boolean;
+        forceAntiAlias?: boolean;
+        compatibleLineSpacing?: boolean;
+        spaceFirstLastParagraph?: boolean;
+        /** A preset text warp (`prstTxWarp`) and its adjust values, in the preset grammar's units. */
+        warp?: {
+            preset: string;
+            adjustments?: Record<string, number>;
+        };
+        /** `bodyPr/extLst` as the file states it: an opaque DrawingML fragment, written back as it was. */
+        extLst?: string;
+    }
+    /** The paragraph formatting a text body's levels inherit (`lstStyle`). */
+    interface ListStyleJSON {
+        default?: IText.ParagraphPropertiesJSON;
+        /** Levels 1 to 9, by index; a level the file does not state is absent. */
+        levels?: (IText.ParagraphPropertiesJSON | undefined)[];
+    }
+    /**
+     * The text written in a frame — a shape's text body — as JSON: its paragraphs, how the body
+     * sits in the frame, and the list style the paragraphs inherit from.
+     */
+    interface JSON {
+        paragraphs: IText.ParagraphJSON[];
+        /** Text rotation in degrees, when the body states one. */
+        rotation?: number;
+        /** How the body sits in the frame; absent for the defaults. */
+        body?: BodyJSON;
+        listStyle?: ListStyleJSON;
+    }
     interface CloneableTextFrame extends ITextFrame {
         clone(visitor?: TextVisitor): ITextFrame;
         equals(other: ITextFrame): boolean;

package/types/src/text/TextBoxAlignment.d.ts

@@ -1,5 +1,5 @@
 import { ITextFrame } from './ITextFrame';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 /**
  * Provided options for aligned text within a bounding box.
  */
@@ -13,7 +13,7 @@ export interface ITextBoxAlignment {
      *
      * @param horizontal The horizontal alignment
      */
-    setHorizontal(horizontal: ITextFrame.HorizontalAlignment | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setHorizontal(horizontal: ITextFrame.HorizontalAlignment | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * Types of horizontal alignment.
      */
@@ -23,7 +23,7 @@ export interface ITextBoxAlignment {
      *
      * @param vertical The vertical alignment
      */
-    setVertical(vertical: ITextFrame.VerticalAlignment | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setVertical(vertical: ITextFrame.VerticalAlignment | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * An integer value, where an increment of 1 represents 3 spaces.
      * Indicates the number of spaces (of the normal style font) of indentation for text in a cell.
@@ -37,7 +37,7 @@ export interface ITextBoxAlignment {
      *
      * @param indent The indentation
      */
-    setIndent(indent: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setIndent(indent: number | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * Indicates additional number of spaces of indentation to adjust for text in a cell.
      */
@@ -47,7 +47,7 @@ export interface ITextBoxAlignment {
      *
      * @param relativeIndent The relative indentation
      */
-    setRelativeIndent(relativeIndent: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setRelativeIndent(relativeIndent: number | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * The behavior for text that does not fit with the cell bounds.
      * @see
@@ -59,28 +59,37 @@ export interface ITextBoxAlignment {
      *
      * @param overflow The overflow behavior
      */
-    setOverflow(overflow: ITextFrame.Overflow | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setOverflow(overflow: ITextFrame.Overflow | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
-     * Rotation of the text.
+     * Rotation of the text, in degrees `0…360` (counter-clockwise, as OOXML stores it).
      * @defaultValue 0
      */
     getRotation(): number;
     /**
-     * Sets the rotation
+     * Sets the rotation.
      *
-     * @param rotation The rotation
+     * @param rotation The rotation in degrees; negative values are normalized (`-45` is `315`).
+     *
+     * @remarks
+     * Rotation and {@link setStacked stacked} are one orientation setting: setting a rotation turns
+     * stacking off.
      */
-    setRotation(rotation: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setRotation(rotation: number | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
-     * If the text should stack vertically instead of horizontally.
+     * If the text is stacked — every glyph upright, one below the other (Excel's "Vertical Text").
+     * @defaultValue false
      */
     getStacked(): boolean;
     /**
-     * Sets the stacked
+     * Sets whether the text is stacked.
      *
-     * @param stacked The stacked
+     * @param stacked `true` to stack the glyphs vertically.
+     *
+     * @remarks
+     * Stacked and {@link setRotation rotation} are one orientation setting: stacking clears any
+     * rotation.
      */
-    setStacked(stacked: boolean | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setStacked(stacked: boolean | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * If the cells justified or distributed alignment should be used on the last line of text.
      * (This is typical for East Asian alignments but not typical in other contexts.)
@@ -91,7 +100,7 @@ export interface ITextBoxAlignment {
      *
      * @param justifyLastLine The justified last line
      */
-    setJustifyLastLine(justifyLastLine: boolean | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setJustifyLastLine(justifyLastLine: boolean | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     /**
      * The direction the cell is being read.
      */
@@ -101,7 +110,7 @@ export interface ITextBoxAlignment {
      *
      * @param readingDirection The reading direction
      */
-    setReadingDirection(readingDirection: ITextFrame.ReadingDirection | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
+    setReadingDirection(readingDirection: ITextFrame.ReadingDirection | null, options?: ICellStyle.UpdateOptions): ITextBoxAlignment;
     toJSON(): ITextBoxAlignment.JSON;
     /**
      * For runtime type checking.

package/types/src/text/TextEngine.d.ts

@@ -0,0 +1,34 @@
+import { SdkWasmExports } from '../wasm';
+import { TextWrapperFallback } from './_TextWrapperFallback';
+/** The lazily loaded TypeScript wrapper and its `linebreak` package. */
+export type TextFallbackModule = {
+    TextWrapperFallback: typeof TextWrapperFallback;
+};
+/**
+ * What wraps text: the Rust wrapper in the sdk's wasm, or, only where that cannot load (a
+ * Content Security Policy without `'wasm-unsafe-eval'`, Lockdown Mode), the TypeScript wrapper
+ * with its `linebreak` package as a chunk of its own. One or the other is loaded before any text
+ * is wrapped, never both; a wrap before either is an error naming `whenReady()`. The font
+ * collection starts the load when it starts and counts it among the loads its `whenReady()`
+ * waits for, so a workbook's `whenReady()` covers it.
+ *
+ * @remarks
+ * Internal to the sdk. In Node the wasm is instantiated as the sdk loads, so there is no window
+ * in which nothing is loaded.
+ */
+export declare const TextEngine: {
+    /**
+     * Loads the engine: the wasm, and the TypeScript fallback only if that fails. Rejects only
+     * when neither loads.
+     */
+    load: () => Promise<void>;
+    /** Loads the TypeScript wrapper whether or not the wasm is there: for comparing the two. */
+    loadFallback: () => Promise<TextFallbackModule>;
+    /** Whether a wrap can run now. */
+    isLoaded: () => boolean;
+    /** The wasm, if it has loaded. */
+    peekWasm: () => SdkWasmExports | undefined;
+    /** The TypeScript wrapper, if it has loaded. */
+    peekFallback: () => TextFallbackModule | undefined;
+};
+//# sourceMappingURL=TextEngine.d.ts.map

package/types/src/text/TextFrame.d.ts

@@ -1,10 +1,10 @@
 import { Size, Bounds, Rectangle } from '@sheetxl/utils';
+import { IFontStyle } from '../font';
 import { TextVisitor } from './TextVisitor';
 import { ITextLine } from './TextLine';
 import { ITextParagraph } from './TextParagraph';
 import { ITextFrame } from './ITextFrame';
 import { ITextBoxAlignment } from './TextBoxAlignment';
-import { IStyledFont } from './richtext';
 export declare class TextFrame {
     private _private;
     private _bounds;
@@ -12,14 +12,18 @@ export declare class TextFrame {
     private _lines;
     private _lastLayoutSize;
     private _lastLayout;
+    /** The fonts the last layout measured with: a font that arrived since makes it stale. */
+    private _lastLayoutFonts;
     private _defaultFont;
     private _alignment;
-    constructor(overrides: Partial<ITextFrame>, defaultFont: IStyledFont, alignment: ITextBoxAlignment, lines?: ITextLine[] | null, bounds?: Bounds | null, textBounds?: Bounds | null);
+    constructor(overrides: Partial<ITextFrame>, defaultFont: IFontStyle, alignment: ITextBoxAlignment, lines?: ITextLine[] | null, bounds?: Bounds | null, textBounds?: Bounds | null);
     visitParas(visitor: TextVisitor): void;
     visitLines(visitor: TextVisitor): void;
     layout(size?: Partial<Size> | null): ITextFrame;
     clone(visitor?: TextVisitor): ITextFrame;
     equals(other: ITextParagraph): boolean;
+    /** {@inheritDoc ITextFrame.IText.getText} */
+    getText(): string;
     /** {@inheritDoc ITextFrame.createTextFrame} */
     createTextFrame(text: string, allowWrap?: boolean): ITextFrame;
     get bounds(): Bounds;
@@ -39,5 +43,7 @@ export declare class TextFrame {
     get isSpaceFirstLastPara(): boolean;
     get presetTextWarp(): string | null;
     get paragraphs(): ITextParagraph[];
+    /** {@inheritDoc ITextFrame.isITextFrame} */
+    get isITextFrame(): true;
 }
 //# sourceMappingURL=TextFrame.d.ts.map

package/types/src/text/TextLine.d.ts

@@ -9,6 +9,8 @@ export interface ITextLine {
     readonly runs: ITextRun[];
     readonly bounds: Bounds;
     readonly baseline: number;
+    /** For runtime type checking. */
+    readonly isITextLine: true;
 }
 /**
  * A default text line.
@@ -20,5 +22,7 @@ export declare class DefaultTextLine implements ITextLine {
     get baseline(): any;
     get runs(): any;
     get bullet(): null;
+    /** {@inheritDoc ITextLine.isITextLine} */
+    get isITextLine(): true;
 }
 //# sourceMappingURL=TextLine.d.ts.map

package/types/src/text/TextParagraph.d.ts

@@ -24,6 +24,8 @@ export interface ITextParagraph {
     readonly rightMargin: number;
     readonly bullet: IBullet | null;
     readonly runs: ITextRun[];
+    /** For runtime type checking. */
+    readonly isITextParagraph: true;
 }
 export interface PlacedTextParagraph extends ITextParagraph {
     /**
@@ -57,5 +59,7 @@ export declare class DefaultTextParagraph implements ITextParagraph, PlacedTextP
     get rightMargin(): number;
     get bullet(): IBullet | null;
     get runs(): ITextRun[];
+    /** {@inheritDoc ITextParagraph.isITextParagraph} */
+    get isITextParagraph(): true;
 }
 //# sourceMappingURL=TextParagraph.d.ts.map

package/types/src/text/TextRotation.d.ts

@@ -26,7 +26,7 @@ import { ITextFrame } from './ITextFrame';
 export interface Line {
     /**
      * Where the strip's un-rotated top-left sits (content-box coordinate space). The strip is the
-     * line's box (`size`) rotated by the layout {@link Layout.angle angle} **about this point**.
+     * line's box (`size`) rotated by the layout {@link RotatedLayout.angle angle} **about this point**.
      */
     origin: Point;
     /** The un-rotated strip box: the line's text width × line height. */
@@ -37,7 +37,7 @@ export interface Line {
 /**
  * The placed geometry for all lines — see {@link layoutLines}.
  */
-export interface Layout {
+export interface RotatedLayout {
     /** The rotation, CSS degrees clockwise, normalized to [0, 360). Never 0 or 180 (callers skip). */
     angle: number;
     /**
@@ -102,5 +102,5 @@ export declare function getAdvance(lineHeight: number, deg: number): number;
  * The footprint may exceed the content box in either axis — rotated text overflows; clipping is a
  * consumer decision.
  */
-export declare function layoutLines(lineSizes: readonly Size[], deg: number, content: Bounds, horizontal: ITextFrame.HorizontalAlignment, vertical: ITextFrame.VerticalAlignment): Layout;
+export declare function layoutLines(lineSizes: readonly Size[], deg: number, content: Bounds, horizontal: ITextFrame.HorizontalAlignment, vertical: ITextFrame.VerticalAlignment): RotatedLayout;
 //# sourceMappingURL=TextRotation.d.ts.map

package/types/src/text/TextRun.d.ts

@@ -1,4 +1,5 @@
 import { Bounds } from '@sheetxl/utils';
+import { IFont } from '../font';
 import { IText } from './IText';
 import { TextVisitor } from './TextVisitor';
 /**
@@ -51,7 +52,14 @@ export interface ITextRun {
     /**
      * Specifies the strikethrough style applied to the text.
      */
-    readonly strikeStyle: IText.StrikeStyle;
+    readonly strikeStyle: IFont.StrikeStyle;
+    /**
+       * Specifies the baseline for both the superscript and subscript fonts.
+       * The size is specified using a percentage where 1000 is equal to 1 percent
+       * of the font size and 100000 is equal to 100 percent font of the font size.
+       */
+    /** For runtime type checking. */
+    readonly isITextRun: true;
 }
 export interface PlacedTextRun extends ITextRun {
     /**
@@ -80,6 +88,8 @@ export declare class DefaultTextRun implements ITextRun, PlacedTextRun, Cloneabl
     get kerningMin(): number;
     get smallCaps(): IText.SmallCaps;
     get offset(): number;
-    get strikeStyle(): IText.StrikeStyle;
+    get strikeStyle(): IFont.StrikeStyle;
+    /** {@inheritDoc ITextRun.isITextRun} */
+    get isITextRun(): true;
 }
 //# sourceMappingURL=TextRun.d.ts.map

package/types/src/text/TextStacked.d.ts

@@ -0,0 +1,83 @@
+import { Bounds } from '@sheetxl/utils';
+import { ITextFrame } from './ITextFrame';
+/**
+ * Stacked cell-text layout — Excel's "Vertical Text" (`textRotation="255"`).
+ *
+ * Stacked text is not rotated. Every glyph stays upright and occupies one SLOT of the font's line
+ * pitch, glyphs advancing downward in a column. Measured against Excel (hidden-COM probes, see
+ * `VERTICAL-TEXT-PLAN.md`):
+ *
+ * 1. Columns come from explicit line breaks — one column per line, left → right in reading order —
+ *    and, when the cell wraps, from breaking a column that would exceed the content height: greedy
+ *    at spaces (the space at a break is consumed), per glyph inside a word longer than the capacity.
+ *    It is the horizontal wrap rule transposed. An unwrapped cell keeps one column; a line break
+ *    there is a blank slot.
+ * 2. Leading and trailing spaces of a column are measured but never painted (see
+ *    {@link layoutColumns}); inner spaces are blank slots.
+ * 3. Each column is aligned on its own by the vertical alignment (Top / Center / Bottom; Justify
+ *    and Distributed behave as Top and Center — nothing is spread). The horizontal alignment places
+ *    the group of columns; the caller resolves General (Excel centers it). Columns are one pitch
+ *    wide and glyphs center in them.
+ * 4. Nothing overflows: the footprint clips to the cell on both axes.
+ *
+ * All output is pure geometry, renderer-agnostic: a DOM renderer maps each column to a box of
+ * `pitch` line-height with one glyph per line; a canvas renderer paints each glyph centered in
+ * its slot.
+ */
+/**
+ * One stacked column.
+ */
+export interface Column {
+    /** The slot texts, top to bottom — one glyph each; a blank slot is `' '`. */
+    glyphs: readonly string[];
+    /** The column box (content-box coordinate space): one pitch wide, `glyphs.length · pitch` tall. */
+    bounds: Bounds;
+}
+/**
+ * The placed geometry for all columns — see {@link layoutColumns}.
+ */
+export interface StackedLayout {
+    /** The slot pitch: the font's line height. Also the column width. */
+    pitch: number;
+    /** One entry per column, in reading order (left → right). */
+    columns: readonly Column[];
+    /** The axis-aligned union of all columns. */
+    bounds: Bounds;
+}
+/**
+ * Splits text into the units that take a slot each. Code points, so a surrogate pair is one slot.
+ */
+export declare function splitGlyphs(text: string): string[];
+/**
+ * Splits text into columns of slots.
+ *
+ * @param text The text to stack (line breaks are `\n`).
+ * @param wrapped `true` when the cell wraps: line breaks start new columns and a column longer than
+ *  `capacity` breaks (see the module notes). `false` keeps one column with a line break as a blank
+ *  slot.
+ * @param capacity The slots per column before a wrapped column breaks. Pass
+ *  `Number.MAX_SAFE_INTEGER` to split on line breaks only (the measure Excel's autofit uses).
+ *
+ * @remarks
+ * Columns keep their leading/trailing spaces — those count for measurement. {@link layoutColumns}
+ * trims them for painting.
+ */
+export declare function toColumns(text: string, wrapped: boolean, capacity: number): string[][];
+/**
+ * The slot count a measure uses: the longest column, spaces included.
+ */
+export declare function slotCount(columns: readonly (readonly string[])[]): number;
+/**
+ * Lays out stacked columns within a content box.
+ *
+ * @param columns The columns' slot glyphs, in reading order (see {@link toColumns}). Leading and
+ *  trailing spaces are trimmed here — Excel measures them but does not paint them.
+ * @param pitch The slot pitch (the font's line height); also the column width.
+ * @param content The content box (cell box minus insets), in the caller's coordinate space.
+ * @param horizontal The resolved horizontal alignment (`General` already resolved). Places the
+ *  group of columns: Left/Justify at the left edge, Right at the right edge, otherwise centered.
+ * @param vertical The vertical alignment, applied to EACH column: Top/Justify hug the top edge,
+ *  Center/Distributed center, Bottom (the default) hugs the bottom.
+ */
+export declare function layoutColumns(columns: readonly (readonly string[])[], pitch: number, content: Bounds, horizontal: ITextFrame.HorizontalAlignment, vertical: ITextFrame.VerticalAlignment): StackedLayout;
+//# sourceMappingURL=TextStacked.d.ts.map

package/types/src/text/TextWrapper.d.ts

@@ -1,4 +1,4 @@
-import { IFont } from '../font';
+import { IFontCollection } from '../font';
 /**
  * Simple Text Line Wrapper. Is not useful for Rich Text (yet). see TextLayout.
  */
@@ -43,36 +43,42 @@ export interface Line {
 export interface onLine {
     (line: Line): boolean | void;
 }
+export interface TextWrapperConfig {
+    /**
+     * Wrap in the Rust wrapper when the wasm is there (the default). `false` keeps every wrap on
+     * the TypeScript one, for comparing the two; that one must have been loaded
+     * (`TextEngine.loadFallback()`).
+     */
+    native?: boolean;
+}
 export declare function linesToText(lines: Line[], trimTrailingSpace?: boolean): string;
 /**
- * A simple text wrapper that uses a line breaker to break lines.
+ * Wraps text into lines against a width, measuring from the font collection.
  *
- * *PERFORMANCE OPTIMIZATIONS*
- * - Binary search for wordBreak
- * - Reuse all of the objects. (this should support a reuse flag and it lines are not needed then they can also be internally reused)
- * - Have text measure for collapsed text just calc the difference between the two (just trailing whitespace, is there kerning?)
+ * @remarks
+ * Two wrappers behind one call, one of them loaded before any text is wrapped
+ * ({@link TextEngine}): the Rust one in the sdk's wasm (`sheetxl-text`), or, only where the wasm
+ * cannot load, the TypeScript one with its `linebreak` package. Both measure from the same
+ * {@link IFont.AdvanceTable}, the Rust one through the table's wasm twin, and break the same way,
+ * so which one answers changes no size (`wrap.differential.node.test.ts`: zero
+ * disagreements over the corpus). A wrap before either has loaded is an error: wait for
+ * `IWorkbook.whenReady()` first.
  */
 export declare class TextWrapper {
-    private _textMeasurer;
-    private _breaker;
-    private _lastBreak;
-    private _charactersRead;
-    private _linesRead;
-    private _maxXRead;
-    private _maxXWhitespaceRead;
-    private _maxYRead;
-    private _fontName;
-    private _fontSize;
-    private _metricOptions;
-    private _indent;
-    private _isSuperSub;
-    private _ellipsis;
-    private _maxWidth;
-    private _maxHeight;
-    constructor(textMeasurer: IFont.Measurer);
-    private _measureText;
-    private _breakWord;
-    private _breakWhiteSpace;
+    private readonly _fonts;
+    private readonly _useNative;
+    /**
+     * @param fonts Where the font named by each wrap's options is measured from.
+     */
+    constructor(fonts?: IFontCollection, config?: TextWrapperConfig);
+    /** Whether the next wrap runs in the Rust wrapper. */
+    get isNative(): boolean;
     wrap(text: string, options?: TextWrapperOptions | null): TextWrapperResults;
+    /**
+     * The wrap through the Rust wrapper: the text crosses the boundary once and the lines come
+     * back as one flat array, {@link NATIVE_LINE_STRIDE} numbers each (DESIGN-FONTS §6.2:
+     * one call per wrap). Its offsets are UTF-8 bytes, turned into UTF-16 positions here.
+     */
+    private _wrapNative;
 }
 //# sourceMappingURL=TextWrapper.d.ts.map

package/types/src/text/_TextUtils.d.ts

@@ -1,17 +1,17 @@
 import { Size } from '@sheetxl/utils';
-import { IFont } from '../font';
+import { IFontCollection } from '../font';
 import { ITextFrame } from './ITextFrame';
 import { ITextBoxAlignment } from './TextBoxAlignment';
-import { IStyledFont } from './richtext/IStyledFont';
+import { IFontStyle } from '../font/IFontStyle';
 /**
  * This 'places' text which means that using all of the formatting rules it assign's locations and bounds to
  * all of the characters. It does not however actually render them. See @renderTextFrame for rendering.
  *
  * @param textFrame
  * @param dimensions
- * @param textMeasurer This defaults to a canvas context
+ * @param fonts Where fonts are measured from; the shared collection by default.
  */
-export declare function layoutTextFrame(textFrame: ITextFrame, defaultFont: IStyledFont, alignment: ITextBoxAlignment, dimensions?: Partial<Size> | null, textMeasurer?: IFont.Measurer): ITextFrame;
+export declare function layoutTextFrame(textFrame: ITextFrame, defaultFont: IFontStyle, alignment: ITextBoxAlignment, dimensions?: Partial<Size> | null, fonts?: IFontCollection): ITextFrame;
 /**
  * Checks whether a string is entirely uppercase, lowercase, or mixed case.
  *
@@ -86,5 +86,5 @@ export declare function convertCase(str: string, caseArray: readonly number[]):
  * TODO - abstract CellStyle
  * @internal
  */
-export declare function createTextFrameFromText(text: string, defaultFont: IStyledFont, alignment: ITextBoxAlignment, allowWrap: boolean, disableCustomFormatting?: boolean): ITextFrame;
+export declare function createTextFrameFromText(text: string, defaultFont: IFontStyle, alignment: ITextBoxAlignment, allowWrap: boolean, disableCustomFormatting?: boolean): ITextFrame;
 //# sourceMappingURL=_TextUtils.d.ts.map

package/types/src/text/_TextWrapperFallback.d.ts

@@ -0,0 +1,49 @@
+import { IFontCollection } from '../font';
+import { TextWrapperOptions, TextWrapperResults } from './TextWrapper';
+/**
+ * A simple text wrapper that uses a line breaker to break lines.
+ *
+ * @remarks
+ * Widths are advance sums with no kerning, so a line is measured as it grows, a character at a
+ * time ({@link Tally}): no character is measured twice, however long the line.
+ */
+export declare class TextWrapperFallback {
+    private _fonts;
+    private _table;
+    private _letterSpacing;
+    private _breaker;
+    private _lastBreak;
+    private _charactersRead;
+    private _linesRead;
+    private _maxXRead;
+    private _maxXWhitespaceRead;
+    private _maxYRead;
+    private _fontSize;
+    private _indent;
+    private _isSuperSub;
+    private _maxWidth;
+    private _maxHeight;
+    /** One character's advance in px, by character, for the current wrap. */
+    private _advances;
+    private _metrics;
+    /** The current line from its start to {@link _charactersRead}. */
+    private _lineTally;
+    /**
+     * @param fonts Where the font named by each wrap's options is measured from.
+     */
+    constructor(fonts: IFontCollection);
+    private _finish;
+    /** `[trailing white space trimmed, as is]`. */
+    private _widths;
+    private _advance;
+    /** Grows `tally` by `text`, the characters that follow the phrase it measures. */
+    private _extend;
+    /**
+     * Breaks a word that does not fit into full lines of characters, at least one per line; the
+     * remainder becomes `currentLine`, its tally the line's.
+     */
+    private _breakWord;
+    private _breakWhiteSpace;
+    wrap(text: string, options?: TextWrapperOptions | null): TextWrapperResults;
+}
+//# sourceMappingURL=_TextWrapperFallback.d.ts.map