@mark1russell7/typeset 0.1.0 → 0.1.2

package/src/measurer/advance.ts

@@ -0,0 +1,307 @@
+/**
+ * The advance function of the font model: the width of a text in a CSS font, as the measurer of
+ * `@mark1russell7/layout-contract/text` asks for it. The host gives the font files as faces. The function finds the face
+ * of each run of the text with the matching rules of CSS. It finds the script of the run, and measures the run with the
+ * rules of one text engine.
+ */
+import { engines, isEngineName, type EngineName, type EngineRules } from "../fonts/engines.ts";
+import { measureWidth, readFont, type Font } from "../fonts/font.ts";
+import type { Decompress } from "../fonts/sfnt.ts";
+
+/** One font file of the host, with the family, the weight and the style that CSS matches. */
+export interface FontFace {
+  /** The family name, as the CSS font names it. The match ignores the case. */
+  readonly family: string;
+  /** The bytes of a TrueType, OpenType or WOFF2 file. */
+  readonly data: Uint8Array;
+  /**
+   * The weight of the face: one value, or the range of a variable font. The default is the range of the `wght` axis of the
+   * font, or 400 for a font with no `wght` axis.
+   */
+  readonly weight?: number | readonly [number, number];
+  /** The style of the face. The default is `normal`. */
+  readonly style?: "normal" | "italic" | "oblique";
+  /** The Brotli decompressor of a WOFF2 file. */
+  readonly decompress?: Decompress;
+}
+
+/** The options of `fontAdvance`. */
+export interface FontAdvanceOptions {
+  /** The font files of the host. The order sets the choice between two faces with the same match. */
+  readonly faces: readonly FontFace[];
+  /** The text engine: a row name of `engines`, or the rules of a row. The default is `freetype`, as Chromium on Linux. */
+  readonly engine?: EngineName | EngineRules;
+  /**
+   * The shaping of `measureWidth`. The default is `canvas`, as `canvasAdvance` of layout-contract measures each segment
+   * with `measureText`. Use `dom` for the widths of a text in a page.
+   */
+  readonly shaping?: "dom" | "canvas";
+}
+
+/** The parts of a CSS font shorthand that change a width. */
+export interface FontSpec {
+  readonly style: "normal" | "italic" | "oblique";
+  /** The angle of an oblique style in degrees. CSS gives 14 when the font names no angle. */
+  readonly angle: number;
+  /** The weight from 1 to 1000. */
+  readonly weight: number;
+  /** The width of the font as a percent of the normal width, from the keyword of `font-stretch`. */
+  readonly stretch: number;
+  /** The size in px. */
+  readonly size: number;
+  /** The family names in the order of the font, with no quotes. */
+  readonly families: readonly string[];
+}
+
+const stretches: Readonly<Record<string, number>> = {
+  "ultra-condensed": 50,
+  "extra-condensed": 62.5,
+  condensed: 75,
+  "semi-condensed": 87.5,
+  "semi-expanded": 112.5,
+  expanded: 125,
+  "extra-expanded": 150,
+  "ultra-expanded": 200,
+};
+
+// Each number pattern matches a text in one way only. Thus a long run of digits does not make the match slow.
+const sizePattern = /^((?:\d+(?:\.\d+)?|\.\d+)(?:e[+-]?\d+)?)(px|pt)(\/.*)?$/i;
+const anglePattern = /^(-?(?:\d+(?:\.\d+)?|\.\d+))deg$/i;
+const weightPattern = /^(?:\d+(?:\.\d+)?|\.\d+)$/;
+
+/**
+ * This function reads a CSS font shorthand, for example `italic 700 16px/1.2 "Noto Sans", sans-serif`. The size must be in
+ * `px` or `pt`. The function refuses `small-caps`, the system font keywords and the relative sizes with a `RangeError`.
+ */
+export function parseFont(font: string): FontSpec {
+  const tokens = font.trim().split(/\s+/);
+  let style: FontSpec["style"] = "normal";
+  let angle = 14;
+  let weight = 400;
+  let stretch = 100;
+  let index = 0;
+  for (; index < tokens.length; index++) {
+    const token = tokens[index]!;
+    const lower = token.toLowerCase();
+    const size = sizePattern.exec(token);
+    if (size !== null) break;
+    if (lower === "normal") continue;
+    if (lower === "italic") style = "italic";
+    else if (lower === "oblique") {
+      style = "oblique";
+      const next = anglePattern.exec(tokens[index + 1] ?? "");
+      if (next !== null) {
+        angle = Number(next[1]);
+        index++;
+      }
+    } else if (lower === "bold" || lower === "bolder") weight = 700;
+    else if (lower === "lighter") weight = 100;
+    else if (weightPattern.test(token) && Number(token) >= 1 && Number(token) <= 1000) weight = Number(token);
+    else if (Object.hasOwn(stretches, lower)) stretch = stretches[lower]!;
+    else throw new RangeError(`the font "${font}" has the part "${token}", which the measurer does not know`);
+  }
+  const size = sizePattern.exec(tokens[index] ?? "");
+  if (size === null) throw new RangeError(`the font "${font}" has no size in px or pt`);
+  let rest = tokens.slice(index + 1).join(" ");
+  // A line height after a space: "16px / 1.2" or "16px /1.2"
+  if (size[3] === undefined && rest.startsWith("/")) rest = rest.slice(1).trim().replace(/^\S+\s*/, "");
+  const families = rest
+    .split(",")
+    .map((family) => family.trim().replace(/^(["'])(.*)\1$/, "$2").trim())
+    .filter((family) => family.length > 0);
+  if (families.length === 0) throw new RangeError(`the font "${font}" has no family`);
+  const value = Number(size[1]);
+  return { style, angle, weight, stretch, size: size[2]!.toLowerCase() === "pt" ? (value * 4) / 3 : value, families };
+}
+
+/** The Unicode scripts and their OpenType tags. A script that is not in the list gets `DFLT`. */
+const scriptPatterns: readonly (readonly [RegExp, string])[] = [
+  [/\p{sc=Latin}/u, "latn"],
+  [/\p{sc=Greek}/u, "grek"],
+  [/\p{sc=Cyrillic}/u, "cyrl"],
+  [/\p{sc=Armenian}/u, "armn"],
+  [/\p{sc=Hebrew}/u, "hebr"],
+  [/\p{sc=Arabic}/u, "arab"],
+  [/\p{sc=Syriac}/u, "syrc"],
+  [/\p{sc=Thaana}/u, "thaa"],
+  [/\p{sc=Devanagari}/u, "deva"],
+  [/\p{sc=Bengali}/u, "beng"],
+  [/\p{sc=Gurmukhi}/u, "guru"],
+  [/\p{sc=Gujarati}/u, "gujr"],
+  [/\p{sc=Oriya}/u, "orya"],
+  [/\p{sc=Tamil}/u, "taml"],
+  [/\p{sc=Telugu}/u, "telu"],
+  [/\p{sc=Kannada}/u, "knda"],
+  [/\p{sc=Malayalam}/u, "mlym"],
+  [/\p{sc=Sinhala}/u, "sinh"],
+  [/\p{sc=Thai}/u, "thai"],
+  [/\p{sc=Lao}/u, "lao "],
+  [/\p{sc=Tibetan}/u, "tibt"],
+  [/\p{sc=Myanmar}/u, "mymr"],
+  [/\p{sc=Georgian}/u, "geor"],
+  [/\p{sc=Hangul}/u, "hang"],
+  [/\p{sc=Ethiopic}/u, "ethi"],
+  [/\p{sc=Khmer}/u, "khmr"],
+  [/\p{sc=Mongolian}/u, "mong"],
+  [/[\p{sc=Hiragana}\p{sc=Katakana}]/u, "kana"],
+  [/\p{sc=Bopomofo}/u, "bopo"],
+  [/\p{sc=Han}/u, "hani"],
+];
+
+const neutral = /[\p{sc=Common}\p{sc=Inherited}\p{sc=Unknown}]/u;
+
+/**
+ * This function gives the OpenType script tag of a text, as HarfBuzz guesses it. The tag is the script of the first
+ * character that is not of the scripts Common, Inherited or Unknown. A text of only those characters, for example emoji, gets `DFLT`.
+ */
+export function scriptTag(text: string): string {
+  for (const character of text) {
+    if (neutral.test(character)) continue;
+    for (const [pattern, tag] of scriptPatterns) if (pattern.test(character)) return tag;
+    return "DFLT";
+  }
+  return "DFLT";
+}
+
+/** A character that stays in the run of the character before it: a mark, a joiner, a variation selector, a tag or a skin tone. */
+const attached = /^[\p{M}‌‍︀-️\u{e0020}-\u{e007f}\u{e0100}-\u{e01ef}\u{1f3fb}-\u{1f3ff}]$/u;
+
+const styleOrder: Readonly<Record<FontSpec["style"], readonly FontSpec["style"][]>> = {
+  normal: ["normal", "oblique", "italic"],
+  italic: ["italic", "oblique", "normal"],
+  oblique: ["oblique", "italic", "normal"],
+};
+
+/** A face with its font, read at the first use. */
+interface Loaded {
+  readonly face: FontFace;
+  readonly index: number;
+  readonly font: Font;
+  readonly range: readonly [number, number];
+}
+
+/**
+ * This function gives the rank of a face for the weight `weight`, with the rules of CSS Fonts 4. A lower rank is a
+ * better match. A face whose range holds the weight has the rank 0.
+ */
+function weightRank(range: readonly [number, number], weight: number): number {
+  const [min, max] = range;
+  if (min <= weight && weight <= max) return 0;
+  const above = min > weight;
+  // The groups of CSS: 1 is the first choice after an exact match, 3 is the last
+  if (weight >= 400 && weight <= 500) {
+    if (above && min <= 500) return 1000 + min;
+    if (!above) return 3000 - max;
+    return 5000 + min;
+  }
+  if (weight < 400) return above ? 3000 + min : 1000 - max;
+  return above ? 1000 + min : 3000 - max;
+}
+
+/**
+ * This function gives the advance function of the faces of the host: the width in px of a text in a CSS font. Each run
+ * of the text gets the first family of the font with a glyph for its first character. When no family has a glyph, the
+ * run gets the first family that has a face. The width of a run is `measureWidth` with the size of the font, the script
+ * of `scriptTag` and the rules of the engine. The instance of a variable face takes the weight and the stretch as `wdth`.
+ * It takes the style as `ital` or `slnt`, and the size as `opsz`, as `font-optical-sizing: auto` does.
+ */
+export function fontAdvance(options: FontAdvanceOptions): (text: string, font: string) => number {
+  const engine = options.engine ?? "freetype";
+  if (typeof engine === "string" && !isEngineName(engine)) throw new RangeError(`the engine "${engine}" is not a row of engines`);
+  const rules: EngineRules = typeof engine === "string" ? engines[engine] : engine;
+  const shaping = options.shaping ?? "canvas";
+  const faces = options.faces;
+  const loaded = new Map<number, Loaded>();
+  const specs = new Map<string, FontSpec>();
+  const instances = new Map<string, Font>();
+  const families = new Map<string, readonly Font[] | undefined>();
+
+  const load = (index: number): Loaded => {
+    let entry = loaded.get(index);
+    if (entry === undefined) {
+      const face = faces[index]!;
+      const font = readFont(face.data, { deltas: rules.deltas, metrics: rules.metrics, ...(face.decompress === undefined ? {} : { decompress: face.decompress }) });
+      const axis = font.axes.find((value) => value.tag === "wght");
+      const declared = face.weight;
+      const range: readonly [number, number] = typeof declared === "number" ? [declared, declared] : (declared ?? (axis === undefined ? [400, 400] : [axis.min, axis.max]));
+      entry = { face, index, font, range };
+      loaded.set(index, entry);
+    }
+    return entry;
+  };
+
+  /** This function gives the font of the best face of a family for the spec, or `undefined` when the family has no face. */
+  const fontOf = (family: string, spec: FontSpec): Font | undefined => {
+    const name = family.toLowerCase();
+    const candidates: Loaded[] = [];
+    for (let i = 0; i < faces.length; i++) if (faces[i]!.family.toLowerCase() === name) candidates.push(load(i));
+    if (candidates.length === 0) return undefined;
+    const style = styleOrder[spec.style].find((value) => candidates.some((entry) => (entry.face.style ?? "normal") === value))!;
+    let best: Loaded | undefined;
+    let bestRank = Infinity;
+    for (const entry of candidates) {
+      if ((entry.face.style ?? "normal") !== style) continue;
+      const rank = weightRank(entry.range, spec.weight);
+      if (rank < bestRank) {
+        best = entry;
+        bestRank = rank;
+      }
+    }
+    const chosen = best!;
+    const tags = new Set(chosen.font.axes.map((axis) => axis.tag));
+    const instance: Record<string, number> = {};
+    if (tags.has("wght")) instance["wght"] = Math.min(chosen.range[1], Math.max(chosen.range[0], spec.weight));
+    if (tags.has("wdth")) instance["wdth"] = spec.stretch;
+    if (tags.has("opsz")) instance["opsz"] = spec.size;
+    if (tags.has("ital")) instance["ital"] = spec.style === "italic" ? 1 : 0;
+    if (tags.has("slnt")) instance["slnt"] = spec.style === "oblique" ? -spec.angle : 0;
+    const key = `${chosen.index}|${JSON.stringify(instance)}`;
+    let font = instances.get(key);
+    if (font === undefined) {
+      font = Object.keys(instance).length === 0 ? chosen.font : chosen.font.at(instance);
+      instances.set(key, font);
+    }
+    return font;
+  };
+
+  const fontsOf = (font: string): { readonly spec: FontSpec; readonly fonts: readonly Font[] } => {
+    let spec = specs.get(font);
+    if (spec === undefined) {
+      spec = parseFont(font);
+      if (specs.size >= 256) specs.clear();
+      specs.set(font, spec);
+    }
+    let fonts = families.get(font);
+    if (fonts === undefined) {
+      fonts = spec.families.map((family) => fontOf(family, spec)).filter((value) => value !== undefined);
+      if (fonts.length === 0) throw new RangeError(`no face of the host has a family of the font "${font}"`);
+      if (families.size >= 256) families.clear();
+      families.set(font, fonts);
+    }
+    return { spec, fonts };
+  };
+
+  return (text: string, font: string): number => {
+    const { spec, fonts } = fontsOf(font);
+    const measure = (run: string, face: Font): number => measureWidth(face, run, spec.size, { script: scriptTag(run), shaping, rounding: rules.rounding, sum: rules.sum });
+    if (fonts.length === 1) return measure(text, fonts[0]!);
+    let width = 0;
+    let run = "";
+    let current: Font | undefined;
+    let joined = false;
+    for (const character of text) {
+      const code = character.codePointAt(0)!;
+      const stays = current !== undefined && (joined || attached.test(character));
+      const face = stays ? current! : (fonts.find((value) => value.glyph(code) !== 0) ?? fonts[0]!);
+      if (face !== current && run.length > 0) {
+        width += measure(run, current!);
+        run = "";
+      }
+      current = face;
+      run += character;
+      joined = code === 0x200d;
+    }
+    if (run.length > 0) width += measure(run, current!);
+    return width;
+  };
+}

package/src/measurer.ts

@@ -0,0 +1,5 @@
+/**
+ * The subpath `./measurer`: the advance function of a layout engine, from the font model of typeset. The measurer of
+ * `@mark1russell7/layout-contract/text` takes it as its `AdvanceFn`.
+ */
+export { fontAdvance, parseFont, scriptTag, type FontAdvanceOptions, type FontFace, type FontSpec } from "./measurer/advance.ts";

package/src/text/rope.ts

@@ -0,0 +1,291 @@
+/**
+ * The `Text` rope: a persistent balanced tree of strings with the width and the length of each subtree. An edit makes a
+ * new rope. The new rope shares the subtrees that do not change. A width function gives the width of a run of text. The
+ * rope uses it only for the leaves and for the windows at the seams. Thus an edit uses it of the order of `log n` times.
+ *
+ * The seams are exact when the width function obeys the separator law. For each text `p + s + q` with a separator `s`:
+ * `width(p + s + q) = width(p + s) + width(s + q) - width(s)`. The model of `@mark1russell7/typeset/fonts` obeys it for a space and a
+ * tab. It shapes each word alone, and its kerning goes only between two adjacent glyphs.
+ */
+import type { WidthOf } from "../breaking/paragraph.ts";
+
+/** The options of a rope. */
+export interface TextOptions {
+  /**
+   * The separators of the separator law: each character is one UTF-16 code unit. The default is a space and a tab. An
+   * empty string makes each seam measure the full text of the two sides.
+   */
+  readonly separators?: string;
+  /** The largest count of UTF-16 code units in a leaf. The default is 256. */
+  readonly chunk?: number;
+}
+
+/** The summary of a subtree: its length, its width, and the two ends that a seam measures again. */
+interface Summary {
+  /** The count of UTF-16 code units. */
+  readonly length: number;
+  readonly width: number;
+  /** This value is `true` when the text has a separator. */
+  readonly separated: boolean;
+  /** The text through the first separator, or all the text when the text has no separator. */
+  readonly head: string;
+  readonly headWidth: number;
+  /** The text from the last separator, or all the text when the text has no separator. */
+  readonly tail: string;
+  readonly tailWidth: number;
+}
+
+interface Leaf extends Summary {
+  readonly kind: "leaf";
+  readonly text: string;
+  readonly height: 0;
+}
+
+interface Branch extends Summary {
+  readonly kind: "branch";
+  readonly left: Node;
+  readonly right: Node;
+  readonly height: number;
+}
+
+type Node = Leaf | Branch;
+
+/** The shared state of the ropes of one width function and one set of options. */
+interface Context {
+  readonly width: WidthOf;
+  readonly separators: string;
+  readonly chunk: number;
+}
+
+function isSeparator(context: Context, code: number): boolean {
+  for (let i = 0; i < context.separators.length; i++) if (context.separators.charCodeAt(i) === code) return true;
+  return false;
+}
+
+function leafOf(context: Context, text: string): Leaf {
+  const width = context.width(text);
+  let first = -1;
+  let last = -1;
+  for (let i = 0; i < text.length; i++) {
+    if (!isSeparator(context, text.charCodeAt(i))) continue;
+    if (first < 0) first = i;
+    last = i;
+  }
+  if (first < 0) return { kind: "leaf", text, height: 0, length: text.length, width, separated: false, head: text, headWidth: width, tail: text, tailWidth: width };
+  const head = text.slice(0, first + 1);
+  const tail = text.slice(last);
+  return { kind: "leaf", text, height: 0, length: text.length, width, separated: true, head, headWidth: context.width(head), tail, tailWidth: context.width(tail) };
+}
+
+/**
+ * This function makes the branch of two subtrees. It measures one window: the tail of the left side and the head of the right
+ * side. The separator law then gives the width of all the text from the widths of the two sides.
+ */
+function branchOf(context: Context, left: Node, right: Node): Branch {
+  const seam = left.tail + right.head;
+  const seamWidth = context.width(seam);
+  let width: number;
+  if (!left.separated && !right.separated) width = seamWidth;
+  else if (!left.separated) width = right.width - right.headWidth + seamWidth;
+  else if (!right.separated) width = left.width - left.tailWidth + seamWidth;
+  else width = left.width + right.width - left.tailWidth - right.headWidth + seamWidth;
+  return {
+    kind: "branch",
+    left,
+    right,
+    height: Math.max(left.height, right.height) + 1,
+    length: left.length + right.length,
+    width,
+    separated: left.separated || right.separated,
+    head: left.separated ? left.head : seam,
+    headWidth: left.separated ? left.headWidth : seamWidth,
+    tail: right.separated ? right.tail : seam,
+    tailWidth: right.separated ? right.tailWidth : seamWidth,
+  };
+}
+
+/** This function joins two trees in the order of the text and keeps the heights of the two children within 1. */
+function join(context: Context, left: Node | undefined, right: Node | undefined): Node | undefined {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  if (left.kind === "leaf" && right.kind === "leaf" && left.length + right.length <= context.chunk) return leafOf(context, left.text + right.text);
+  if (left.height > right.height + 1) {
+    const branch = left as Branch;
+    const joined = join(context, branch.right, right)!;
+    if (joined.height <= branch.left.height + 1) return branchOf(context, branch.left, joined);
+    return rotateLeft(context, branch.left, joined as Branch);
+  }
+  if (right.height > left.height + 1) {
+    const branch = right as Branch;
+    const joined = join(context, left, branch.left)!;
+    if (joined.height <= branch.right.height + 1) return branchOf(context, joined, branch.right);
+    return rotateRight(context, joined as Branch, branch.right);
+  }
+  return branchOf(context, left, right);
+}
+
+/** This function balances the branch of `left` and `heavy`, when `heavy` is 2 levels higher than `left`. */
+function rotateLeft(context: Context, left: Node, heavy: Branch): Branch {
+  if (heavy.left.height <= heavy.right.height) return branchOf(context, branchOf(context, left, heavy.left), heavy.right);
+  const middle = heavy.left as Branch;
+  return branchOf(context, branchOf(context, left, middle.left), branchOf(context, middle.right, heavy.right));
+}
+
+/** This function balances the branch of `heavy` and `right`, when `heavy` is 2 levels higher than `right`. */
+function rotateRight(context: Context, heavy: Branch, right: Node): Branch {
+  if (heavy.right.height <= heavy.left.height) return branchOf(context, heavy.left, branchOf(context, heavy.right, right));
+  const middle = heavy.right as Branch;
+  return branchOf(context, branchOf(context, heavy.left, middle.left), branchOf(context, middle.right, right));
+}
+
+/** This function divides a tree at the UTF-16 offset `at` into the text before and the text after. */
+function split(context: Context, node: Node | undefined, at: number): [Node | undefined, Node | undefined] {
+  if (node === undefined) return [undefined, undefined];
+  if (at <= 0) return [undefined, node];
+  if (at >= node.length) return [node, undefined];
+  if (node.kind === "leaf") return [leafOf(context, node.text.slice(0, at)), leafOf(context, node.text.slice(at))];
+  if (at === node.left.length) return [node.left, node.right];
+  if (at < node.left.length) {
+    const [before, after] = split(context, node.left, at);
+    return [before, join(context, after, node.right)];
+  }
+  const [before, after] = split(context, node.right, at - node.left.length);
+  return [join(context, node.left, before), after];
+}
+
+/** This function gives the end of the next leaf of `text` from `start`: after a separator when it can, and not in a surrogate pair. */
+function chunkEnd(context: Context, text: string, start: number): number {
+  const limit = start + context.chunk;
+  if (limit >= text.length) return text.length;
+  for (let i = limit - 1; i >= start + context.chunk / 2; i--) if (isSeparator(context, text.charCodeAt(i))) return i + 1;
+  const code = text.charCodeAt(limit - 1);
+  return code >= 0xd800 && code <= 0xdbff ? limit - 1 : limit;
+}
+
+/** This function makes a balanced tree of a text: leaves of at most `chunk` code units, and then a level of branches at a time. */
+function build(context: Context, text: string): Node | undefined {
+  let level: Node[] = [];
+  for (let start = 0; start < text.length; ) {
+    const end = chunkEnd(context, text, start);
+    level.push(leafOf(context, text.slice(start, end)));
+    start = end;
+  }
+  if (level.length === 0) return undefined;
+  while (level.length > 1) {
+    const next: Node[] = [];
+    for (let i = 0; i + 1 < level.length; i += 2) next.push(branchOf(context, level[i]!, level[i + 1]!));
+    if (level.length % 2 === 1) next.push(level[level.length - 1]!);
+    level = next;
+  }
+  return level[0];
+}
+
+function leaves(node: Node | undefined, out: string[]): string[] {
+  if (node === undefined) return out;
+  const stack: Node[] = [node];
+  while (stack.length > 0) {
+    const top = stack.pop()!;
+    if (top.kind === "leaf") out.push(top.text);
+    else stack.push(top.right, top.left);
+  }
+  return out;
+}
+
+/**
+ * A text with its width: a persistent balanced rope. Each edit gives a new `Text` and does not change this one. The offsets
+ * are in UTF-16 code units, as the offsets of a JavaScript string.
+ */
+export class Text {
+  readonly #context: Context;
+  readonly #root: Node | undefined;
+
+  private constructor(context: Context, root: Node | undefined) {
+    this.#context = context;
+    this.#root = root;
+  }
+
+  /** This function makes the rope of `text` with the width function `width`. */
+  static from(text: string, width: WidthOf, options: TextOptions = {}): Text {
+    const separators = options.separators ?? " \t";
+    const chunk = options.chunk ?? 256;
+    if (!Number.isInteger(chunk) || chunk < 2) throw new RangeError(`the chunk is ${chunk}, not an integer of 2 or more`);
+    for (let i = 0; i < separators.length; i++) {
+      const code = separators.charCodeAt(i);
+      if (code >= 0xd800 && code <= 0xdfff) throw new RangeError("a separator is one UTF-16 code unit, not a half of a surrogate pair");
+    }
+    const context: Context = { width, separators, chunk };
+    return new Text(context, build(context, text));
+  }
+
+  /** The count of UTF-16 code units of the text. */
+  get length(): number {
+    return this.#root?.length ?? 0;
+  }
+
+  /** The width of the text. It is equal to the width of the flat string when the width function obeys the separator law. */
+  get width(): number {
+    return this.#root?.width ?? 0;
+  }
+
+  /** The height of the tree: 0 for a text of one leaf. The tests use it to examine the balance. */
+  get height(): number {
+    return this.#root?.height ?? 0;
+  }
+
+  /** This function gives the flat string. */
+  toString(): string {
+    return leaves(this.#root, []).join("");
+  }
+
+  /** This function gives the strings of the leaves in the order of the text. */
+  chunks(): string[] {
+    return leaves(this.#root, []);
+  }
+
+  /** This function gives the text from `start` to `end`, as a new rope. */
+  slice(start: number, end: number = this.length): Text {
+    this.#check(start, end);
+    const [, after] = split(this.#context, this.#root, start);
+    const [middle] = split(this.#context, after, end - start);
+    return new Text(this.#context, middle);
+  }
+
+  /** This function gives the width of the text from `start` to `end`. */
+  widthOf(start: number, end: number = this.length): number {
+    return this.slice(start, end).width;
+  }
+
+  /** This function gives this text and then `other`. The two ropes must have the same width function and options. */
+  concat(other: Text): Text {
+    const context = other.#context;
+    if (context.width !== this.#context.width || context.separators !== this.#context.separators || context.chunk !== this.#context.chunk) {
+      throw new TypeError("the two ropes have different width functions or options");
+    }
+    return new Text(this.#context, join(this.#context, this.#root, other.#root));
+  }
+
+  /** This function puts `text` at the offset `at`. */
+  insert(at: number, text: string): Text {
+    return this.replace(at, at, text);
+  }
+
+  /** This function removes the text from `start` to `end`. */
+  remove(start: number, end: number): Text {
+    return this.replace(start, end, "");
+  }
+
+  /** This function puts `text` in place of the text from `start` to `end`. */
+  replace(start: number, end: number, text: string): Text {
+    this.#check(start, end);
+    const [before, rest] = split(this.#context, this.#root, start);
+    const [, after] = split(this.#context, rest, end - start);
+    const middle = build(this.#context, text);
+    return new Text(this.#context, join(this.#context, join(this.#context, before, middle), after));
+  }
+
+  #check(start: number, end: number): void {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > this.length) {
+      throw new RangeError(`the range ${start} to ${end} is not in the text of length ${this.length}`);
+    }
+  }
+}

package/src/text.ts

@@ -0,0 +1 @@
+export { Text, type TextOptions } from "./text/rope.ts";