flexily 0.3.3 → 0.5.0

package/README.md

@@ -5,6 +5,31 @@
 [![npm version](https://img.shields.io/npm/v/flexily.svg)](https://www.npmjs.com/package/flexily)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
+**Composable API** (recommended):
+
+```typescript
+import { createFlexily, FLEX_DIRECTION_ROW } from "flexily"
+
+const flex = createFlexily()
+const root = flex.createNode()
+root.setWidth(80)
+root.setFlexDirection(FLEX_DIRECTION_ROW)
+
+const label = flex.createNode()
+label.setTextContent("Hello")  // auto-measured: 5 wide
+
+const content = flex.createNode()
+content.setFlexGrow(1)
+content.setTextContent("World")
+
+root.insertChild(label, 0)
+root.insertChild(content, 1)
+flex.calculateLayout(root, 80, 1)
+// label: 5 wide, content: 75 wide
+```
+
+**Low-level Yoga-compatible API:**
+
 ```typescript
 import { Node, FLEX_DIRECTION_ROW, DIRECTION_LTR } from "flexily"
 
@@ -47,9 +72,47 @@ Most developers should use a framework built on Flexily, not Flexily directly. F
 
 > **Building a terminal UI?** Use [silvery](https://silvery.dev), which uses Flexily by default. You get React components, hooks, and layout feedback without touching the low-level API.
 
+## Composable API
+
+Flexily v0.5+ includes a composable engine with built-in text measurement:
+
+```typescript
+import { createFlexily } from "flexily"
+
+const flex = createFlexily()
+const root = flex.createNode()
+root.setWidth(80)
+root.setFlexDirection(FLEX_DIRECTION_ROW)
+
+const label = flex.createNode()
+label.setTextContent("Hello")
+
+const content = flex.createNode()
+content.setFlexGrow(1)
+content.setTextContent("World")
+
+root.insertChild(label, 0)
+root.insertChild(content, 1)
+flex.calculateLayout(root, 80, 1)
+// label: 5 wide, content: 75 wide
+```
+
+For custom text measurement, compose plugins with `pipe()`:
+
+```typescript
+import { createBareFlexily, pipe, withTestMeasurer } from "flexily"
+
+const flex = pipe(createBareFlexily(), withTestMeasurer())
+```
+
+Text measurement backends:
+- **`withMonospace()`** — terminal grids (1 char = 1 cell), default
+- **`withTestMeasurer()`** — deterministic widths for CI (Latin 0.8, CJK 1.0, emoji 1.8)
+- **`withPretext(pretext)`** — proportional fonts via [Pretext](https://github.com/chenglou/pretext)
+
 ## Status
 
-1495 tests, including 44 Yoga compatibility tests and 1200+ incremental re-layout fuzz tests. Used by [silvery](https://silvery.dev) as its default layout engine.
+1561 tests, including 44 Yoga compatibility tests and 1200+ incremental re-layout fuzz tests. Used by [silvery](https://silvery.dev) as its default layout engine.
 
 | Feature                                       | Status   |
 | --------------------------------------------- | -------- |
@@ -64,6 +127,8 @@ Most developers should use a framework built on Flexily, not Flexily directly. F
 | Logical edges (EDGE_START/END)                | Complete |
 | RTL support                                   | Complete |
 | Baseline alignment                            | Complete |
+| Composable engine (createFlexily, pipe)       | Complete |
+| Text measurement (monospace, proportional)    | Complete |
 
 ## Installation
 
@@ -184,15 +249,18 @@ Same constants, same method names, same behavior.
 
 ```
 src/
-├── index.ts        # Main export
-├── node-zero.ts    # Node class with FlexInfo
-├── layout-zero.ts  # Layout algorithm (~2000 lines)
-├── constants.ts    # Flexbox constants (Yoga-compatible)
-├── types.ts        # TypeScript interfaces
-├── utils.ts        # Shared utilities
-└── classic/        # Allocating algorithm (for debugging)
-    ├── node.ts
-    └── layout.ts
+├── index.ts              # Main export (everything)
+├── create-flexily.ts     # createFlexily, createBareFlexily, pipe, FlexilyNode
+├── text-layout.ts        # TextLayoutService, PreparedText interfaces
+├── monospace-measurer.ts # Terminal text measurement (1 char = 1 cell)
+├── test-measurer.ts      # Deterministic test measurer
+├── pretext-measurer.ts   # Proportional font measurement (peer dep)
+├── node-zero.ts          # Node class with FlexInfo
+├── layout-zero.ts        # Layout algorithm (~2000 lines)
+├── constants.ts          # Flexbox constants (Yoga-compatible)
+├── types.ts              # TypeScript interfaces
+├── utils.ts              # Shared utilities
+└── classic/              # Allocating algorithm (for debugging)
 ```
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flexily",
-  "version": "0.3.3",
-  "description": "Pure JavaScript flexbox layout engine — Yoga-compatible API, faster initial layout, smaller bundle, no WASM",
+  "version": "0.5.0",
+  "description": "Pure JavaScript flexbox layout engine — composable plugins, text measurement, Yoga-compatible API, no WASM",
   "keywords": [
     "canvas-ui",
     "css",

package/src/create-flexily.ts

@@ -0,0 +1,153 @@
+/**
+ * Composable Flexily engine — createFlexily, createBareFlexily, pipe.
+ *
+ * FlexilyNode = Node + { setTextContent, getTextContent }.
+ * No wrapper — text methods are mixed directly onto the Node instance.
+ */
+
+import { Node } from "./node-zero.js"
+import { DIRECTION_LTR, MEASURE_MODE_UNDEFINED, MEASURE_MODE_AT_MOST } from "./constants.js"
+import type { TextLayoutService, ResolvedTextStyle, PreparedText } from "./text-layout.js"
+import { createMonospaceMeasurer } from "./monospace-measurer.js"
+
+// ============================================================================
+// FlexilyNode — Node + text content mixin
+// ============================================================================
+
+/** A Node with text content methods. */
+export interface FlexilyNode extends Node {
+  setTextContent(text: string, style?: Partial<ResolvedTextStyle>): void
+  getTextContent(): string | null
+}
+
+const DEFAULT_TEXT_STYLE: ResolvedTextStyle = {
+  fontShorthand: "1ch monospace",
+  fontFamily: "monospace",
+  fontSize: 1,
+  fontWeight: 400,
+  fontStyle: "normal",
+  lineHeight: 1,
+}
+
+/** Mix text content methods onto a Node. Returns the same node typed as FlexilyNode. */
+function mixTextContent(node: Node, engine: FlexilyEngine): FlexilyNode {
+  let textContent: string | null = null
+  let prepared: PreparedText | null = null
+
+  // Save originals before overriding — setTextContent needs to call the
+  // original setMeasureFunc without triggering text state clearing.
+  const origSetMeasure = node.setMeasureFunc.bind(node)
+  const origUnsetMeasure = node.unsetMeasureFunc.bind(node)
+
+  const flexNode = node as FlexilyNode
+
+  flexNode.setTextContent = function (text: string, style?: Partial<ResolvedTextStyle>): void {
+    if (!engine.textLayout) {
+      throw new Error("No TextLayoutService. Add a text plugin (withMonospace, withPretext, withTestMeasurer).")
+    }
+
+    textContent = text
+    const resolved: ResolvedTextStyle = { ...DEFAULT_TEXT_STYLE, ...style }
+    prepared = engine.textLayout.prepare({ text, style: resolved })
+
+    // Install a MeasureFunc via original (bypasses text-clearing override)
+    const p = prepared
+    origSetMeasure((width, widthMode) => {
+      if (widthMode === MEASURE_MODE_UNDEFINED) {
+        const sizes = p.intrinsicSizes()
+        const result = p.layout({ maxWidth: sizes.maxContentWidth })
+        return { width: result.width, height: result.height }
+      }
+      const result = p.layout({ maxWidth: width })
+      const usedWidth = widthMode === MEASURE_MODE_AT_MOST ? Math.min(width, result.width) : width
+      return { width: usedWidth, height: result.height }
+    })
+  }
+
+  flexNode.getTextContent = function (): string | null {
+    return textContent
+  }
+
+  // Override setMeasureFunc/unsetMeasureFunc to clear text state when
+  // the user explicitly sets a custom measure function.
+  flexNode.setMeasureFunc = function (fn) {
+    textContent = null
+    prepared = null
+    origSetMeasure(fn)
+  }
+
+  flexNode.unsetMeasureFunc = function () {
+    textContent = null
+    prepared = null
+    origUnsetMeasure()
+  }
+
+  return flexNode
+}
+
+// ============================================================================
+// Engine
+// ============================================================================
+
+/** The composable Flexily engine. */
+export interface FlexilyEngine {
+  createNode(): FlexilyNode
+  calculateLayout(root: FlexilyNode, width?: number, height?: number, direction?: number): void
+  textLayout?: TextLayoutService
+}
+
+/** A plugin that extends or configures the engine. */
+export type FlexilyPlugin = (engine: FlexilyEngine) => FlexilyEngine
+
+/**
+ * Create a bare Flexily engine — no plugins, just nodes and layout.
+ * Add plugins via pipe() for text measurement.
+ */
+export function createBareFlexily(): FlexilyEngine {
+  const engine: FlexilyEngine = {
+    createNode(): FlexilyNode {
+      return mixTextContent(Node.create(), engine)
+    },
+    calculateLayout(root: FlexilyNode, width?: number, height?: number, direction?: number): void {
+      root.calculateLayout(width, height, direction ?? DIRECTION_LTR)
+    },
+  }
+  return engine
+}
+
+/**
+ * Apply plugins to an engine, left to right.
+ *
+ * @example
+ * ```typescript
+ * const flex = pipe(createBareFlexily(), withMonospace(), withTestMeasurer())
+ * ```
+ */
+export function pipe(engine: FlexilyEngine, ...plugins: FlexilyPlugin[]): FlexilyEngine {
+  let result = engine
+  for (const plugin of plugins) {
+    result = plugin(result)
+  }
+  return result
+}
+
+/**
+ * Create a batteries-included Flexily engine.
+ *
+ * Includes monospace text measurement (1 char = charWidth units).
+ * For terminal UIs, the default charWidth/charHeight of 1 maps to terminal cells.
+ *
+ * @example
+ * ```typescript
+ * import { createFlexily } from "flexily"
+ * const flex = createFlexily()
+ * const node = flex.createNode()
+ * node.setTextContent("Hello world")
+ * flex.calculateLayout(node, 80, 24)
+ * ```
+ */
+export function createFlexily(options?: { charWidth?: number; charHeight?: number }): FlexilyEngine {
+  const engine = createBareFlexily()
+  engine.textLayout = createMonospaceMeasurer(options?.charWidth ?? 1, options?.charHeight ?? 1)
+  return engine
+}

package/src/index.ts

@@ -4,26 +4,49 @@
  * A Yoga-compatible layout engine for terminal UIs and other environments
  * where WebAssembly is not available or desirable.
  *
- * @example
- * ```typescript
- * import { Node, FLEX_DIRECTION_ROW, DIRECTION_LTR } from 'flexily';
- *
- * const root = Node.create();
- * root.setWidth(80);
- * root.setHeight(24);
- * root.setFlexDirection(FLEX_DIRECTION_ROW);
- *
- * const child = Node.create();
- * child.setFlexGrow(1);
- * root.insertChild(child, 0);
+ * Two API levels:
  *
- * root.calculateLayout(80, 24, DIRECTION_LTR);
+ * 1. Composable (recommended):
+ * ```typescript
+ * import { createFlexily } from "flexily"
+ * const flex = createFlexily()
+ * const node = flex.createNode()
+ * node.setTextContent("Hello world")
+ * flex.calculateLayout(node, 80, 24)
+ * ```
  *
- * console.log(child.getComputedWidth()); // 80
+ * 2. Low-level (Yoga-compatible):
+ * ```typescript
+ * import { Node, DIRECTION_LTR } from "flexily"
+ * const root = Node.create()
+ * root.setWidth(80)
+ * root.calculateLayout(80, 24, DIRECTION_LTR)
  * ```
  */
 
-// Node class (zero-alloc version)
+// Composable API
+export { createFlexily, createBareFlexily, pipe } from "./create-flexily.js"
+export type { FlexilyEngine, FlexilyNode, FlexilyPlugin } from "./create-flexily.js"
+
+// Text measurement plugins
+export { createMonospaceMeasurer, withMonospace } from "./monospace-measurer.js"
+export { createTestMeasurer, withTestMeasurer } from "./test-measurer.js"
+export { createPretextMeasurer, withPretext } from "./pretext-measurer.js"
+export type { PretextAPI, PretextPrepared, PretextLayout } from "./pretext-measurer.js"
+
+// Text layout service types
+export type {
+  TextLayoutService,
+  PreparedText,
+  TextLayout,
+  TextLine,
+  TextConstraints,
+  IntrinsicSizes,
+  ResolvedTextStyle,
+  TextPrepareInput,
+} from "./text-layout.js"
+
+// Node class (zero-alloc version) — low-level Yoga-compatible API
 export { Node } from "./node-zero.js"
 
 // All constants (Yoga-compatible)

package/src/monospace-measurer.ts

@@ -0,0 +1,68 @@
+/**
+ * Monospace text measurement.
+ *
+ * Terminal text: graphemeCount * charWidth, always 1 line (no wrapping).
+ * This is the default for terminal UIs where 1 char = 1 cell.
+ */
+
+import type { FlexilyPlugin } from "./create-flexily.js"
+import type { TextLayoutService, PreparedText, TextLayout, IntrinsicSizes } from "./text-layout.js"
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+
+/**
+ * Create a monospace text measurement service.
+ *
+ * @param charWidth - Width of each character cell (default: 1 for terminal grids)
+ * @param charHeight - Height of each character cell (default: 1 for terminal grids)
+ */
+export function createMonospaceMeasurer(charWidth = 1, charHeight = 1): TextLayoutService {
+  return {
+    prepare(input) {
+      const { text } = input
+
+      // Count grapheme clusters for proper emoji/CJK support
+      let graphemeCount = 0
+      for (const _ of segmenter.segment(text)) graphemeCount++
+
+      const totalWidth = graphemeCount * charWidth
+
+      const prepared: PreparedText = {
+        intrinsicSizes(): IntrinsicSizes {
+          return {
+            minContentWidth: totalWidth, // monospace: entire text is one unbreakable segment
+            maxContentWidth: totalWidth,
+          }
+        },
+
+        layout(constraints): TextLayout {
+          const width = constraints.maxWidth !== undefined ? Math.min(totalWidth, constraints.maxWidth) : totalWidth
+
+          return {
+            width,
+            height: charHeight,
+            lineCount: 1,
+            firstBaseline: charHeight,
+            lastBaseline: charHeight,
+            truncated: width < totalWidth,
+          }
+        },
+      }
+
+      return prepared
+    },
+  }
+}
+
+/**
+ * Plugin: add monospace text measurement to the engine.
+ *
+ * @param charWidth - Width per character cell (default: 1)
+ * @param charHeight - Height per character cell (default: 1)
+ */
+export function withMonospace(charWidth = 1, charHeight = 1): FlexilyPlugin {
+  return (engine) => {
+    engine.textLayout = createMonospaceMeasurer(charWidth, charHeight)
+    return engine
+  }
+}

package/src/pretext-measurer.ts

@@ -0,0 +1,86 @@
+/**
+ * Pretext text measurement plugin.
+ *
+ * Integrates with @chenglou/pretext for proportional font measurement.
+ * Pretext is a peer dependency — users must install it separately.
+ *
+ * See silvery-internal/design/v05-layout/pretext-integration.md
+ */
+
+import type { FlexilyPlugin } from "./create-flexily.js"
+import type { TextLayoutService, PreparedText, TextLayout, IntrinsicSizes } from "./text-layout.js"
+
+/** Pretext API shape (from @chenglou/pretext). Defined here to avoid a hard dependency. */
+export interface PretextAPI {
+  prepare(text: string, font: string): PretextPrepared
+}
+
+export interface PretextPrepared {
+  layout(maxWidth: number, lineHeight?: number): PretextLayout
+}
+
+export interface PretextLayout {
+  width: number
+  height: number
+  lines?: Array<{ text: string; width: number }>
+}
+
+/**
+ * Create a Pretext-based text measurement service.
+ *
+ * @param pretext - The pretext module (import from "@chenglou/pretext")
+ */
+export function createPretextMeasurer(pretext: PretextAPI): TextLayoutService {
+  return {
+    prepare(input) {
+      const { text, style } = input
+      const pretextPrepared = pretext.prepare(text, style.fontShorthand)
+      const lineHeight = style.lineHeight || style.fontSize
+
+      let cachedIntrinsic: IntrinsicSizes | null = null
+
+      const prepared: PreparedText = {
+        intrinsicSizes(): IntrinsicSizes {
+          if (cachedIntrinsic) return cachedIntrinsic
+          const unconstrained = pretextPrepared.layout(Infinity, lineHeight)
+          const minLayout = pretextPrepared.layout(0, lineHeight)
+          cachedIntrinsic = {
+            minContentWidth: minLayout.width,
+            maxContentWidth: unconstrained.width,
+          }
+          return cachedIntrinsic
+        },
+
+        layout(constraints): TextLayout {
+          const maxWidth = constraints.maxWidth ?? Infinity
+          const result = pretextPrepared.layout(maxWidth, lineHeight)
+          const lineCount = result.lines?.length ?? 1
+          const width = constraints.shrinkWrap ? result.width : Math.min(maxWidth, result.width)
+
+          return {
+            width,
+            height: result.height,
+            lineCount,
+            firstBaseline: lineHeight,
+            lastBaseline: lineCount > 0 ? (lineCount - 1) * lineHeight + lineHeight : lineHeight,
+            truncated: false,
+          }
+        },
+      }
+
+      return prepared
+    },
+  }
+}
+
+/**
+ * Plugin: add Pretext-based proportional text measurement.
+ *
+ * @param pretext - The pretext module (import from "@chenglou/pretext")
+ */
+export function withPretext(pretext: PretextAPI): FlexilyPlugin {
+  return (engine) => {
+    engine.textLayout = createPretextMeasurer(pretext)
+    return engine
+  }
+}

package/src/test-measurer.ts

@@ -0,0 +1,219 @@
+/**
+ * Deterministic test text measurer.
+ *
+ * Fixed grapheme width table: Latin 0.8, CJK 1.0, emoji 1.8 (relative to fontSize).
+ * Deterministic across platforms — use in tests and CI.
+ * Supports word wrapping for realistic text layout testing.
+ */
+
+import type { FlexilyPlugin } from "./create-flexily.js"
+import type { TextLayoutService, PreparedText, TextLayout, TextLine, IntrinsicSizes } from "./text-layout.js"
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+
+/** Measure a single grapheme cluster with the deterministic width table. */
+function graphemeWidth(grapheme: string, fontSize: number): number {
+  const cp = grapheme.codePointAt(0) ?? 0
+
+  // Emoji: ZWJ sequences, variation selectors, regional indicators
+  if (
+    (cp >= 0x1f300 && cp <= 0x1faff) ||
+    (cp >= 0x2600 && cp <= 0x27bf) ||
+    (cp >= 0xfe00 && cp <= 0xfe0f) ||
+    cp === 0x200d ||
+    (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+    grapheme.length > 2
+  ) {
+    return fontSize * 1.8
+  }
+
+  // CJK: Chinese, Japanese, Korean ideographs + fullwidth
+  if (
+    (cp >= 0x4e00 && cp <= 0x9fff) ||
+    (cp >= 0x3000 && cp <= 0x303f) ||
+    (cp >= 0x3040 && cp <= 0x309f) ||
+    (cp >= 0x30a0 && cp <= 0x30ff) ||
+    (cp >= 0xac00 && cp <= 0xd7af) ||
+    (cp >= 0xff00 && cp <= 0xffef)
+  ) {
+    return fontSize * 1.0
+  }
+
+  // Latin and everything else
+  return fontSize * 0.8
+}
+
+/** A word or whitespace segment for line breaking. */
+interface TextSegment {
+  text: string
+  width: number
+  isWhitespace: boolean
+}
+
+function segmentText(text: string, fontSize: number): TextSegment[] {
+  const segments: TextSegment[] = []
+  let current = ""
+  let currentWidth = 0
+  let isWhitespace = false
+
+  for (const { segment } of segmenter.segment(text)) {
+    const isSpace = segment === " " || segment === "\t"
+
+    if (segments.length === 0 && current === "") {
+      isWhitespace = isSpace
+      current = segment
+      currentWidth = isSpace ? fontSize * 0.8 : graphemeWidth(segment, fontSize)
+      continue
+    }
+
+    if (isSpace !== isWhitespace) {
+      if (current) segments.push({ text: current, width: currentWidth, isWhitespace })
+      current = segment
+      currentWidth = isSpace ? fontSize * 0.8 : graphemeWidth(segment, fontSize)
+      isWhitespace = isSpace
+    } else {
+      current += segment
+      currentWidth += isSpace ? fontSize * 0.8 : graphemeWidth(segment, fontSize)
+    }
+  }
+
+  if (current) segments.push({ text: current, width: currentWidth, isWhitespace })
+  return segments
+}
+
+function measureString(text: string, fontSize: number): number {
+  let width = 0
+  for (const { segment } of segmenter.segment(text)) {
+    width += graphemeWidth(segment, fontSize)
+  }
+  return width
+}
+
+/**
+ * Create a deterministic text measurement service for testing.
+ *
+ * Uses fixed grapheme widths: Latin 0.8, CJK 1.0, emoji 1.8 (relative to fontSize).
+ */
+export function createTestMeasurer(): TextLayoutService {
+  return {
+    prepare(input) {
+      const { text, style } = input
+      const fontSize = style.fontSize
+      const lineHeight = style.lineHeight || fontSize
+
+      const segments = segmentText(text, fontSize)
+
+      let maxContentWidth = 0
+      let minContentWidth = 0
+      for (const seg of segments) {
+        maxContentWidth += seg.width
+        if (!seg.isWhitespace && seg.width > minContentWidth) {
+          minContentWidth = seg.width
+        }
+      }
+
+      const prepared: PreparedText = {
+        intrinsicSizes(): IntrinsicSizes {
+          return { minContentWidth, maxContentWidth }
+        },
+
+        layout(constraints, options?): TextLayout {
+          const maxWidth = constraints.maxWidth ?? Infinity
+          const maxLines = constraints.maxLines ?? Infinity
+          const wrap = constraints.wrap ?? "normal"
+          const includeLines = options?.includeLines ?? false
+
+          if (wrap === "none" || maxWidth >= maxContentWidth) {
+            const truncated = maxLines < 1
+            const width = constraints.shrinkWrap ? maxContentWidth : Math.min(maxWidth, maxContentWidth)
+            return {
+              width,
+              height: truncated ? 0 : lineHeight,
+              lineCount: truncated ? 0 : 1,
+              firstBaseline: lineHeight,
+              lastBaseline: lineHeight,
+              truncated: maxWidth < maxContentWidth,
+              lines: includeLines
+                ? [{ text, width: maxContentWidth, startIndex: 0, endIndex: text.length }]
+                : undefined,
+            }
+          }
+
+          // Word wrapping
+          const lines: TextLine[] = []
+          let lineWidth = 0
+          let lineText = ""
+          let lineStart = 0
+          let charIndex = 0
+
+          for (const seg of segments) {
+            if (seg.isWhitespace) {
+              if (lineText) {
+                lineWidth += seg.width
+                lineText += seg.text
+              }
+              charIndex += seg.text.length
+              continue
+            }
+
+            if (lineWidth + seg.width > maxWidth && lineText) {
+              const trimmed = lineText.trimEnd()
+              lines.push({
+                text: trimmed,
+                width: measureString(trimmed, fontSize),
+                startIndex: lineStart,
+                endIndex: charIndex,
+              })
+              if (lines.length >= maxLines) break
+
+              lineText = seg.text
+              lineWidth = seg.width
+              lineStart = charIndex
+            } else {
+              lineText += seg.text
+              lineWidth += seg.width
+            }
+            charIndex += seg.text.length
+          }
+
+          if (lineText && lines.length < maxLines) {
+            const trimmed = lineText.trimEnd()
+            lines.push({
+              text: trimmed,
+              width: measureString(trimmed, fontSize),
+              startIndex: lineStart,
+              endIndex: charIndex,
+            })
+          }
+
+          const lineCount = lines.length
+          const height = lineCount * lineHeight
+          const widestLine = lines.reduce((max, l) => Math.max(max, l.width), 0)
+          const width = constraints.shrinkWrap ? widestLine : Math.min(maxWidth, widestLine)
+
+          return {
+            width,
+            height,
+            lineCount,
+            firstBaseline: lineHeight,
+            lastBaseline: lineCount > 0 ? (lineCount - 1) * lineHeight + lineHeight : lineHeight,
+            truncated: lines.length >= maxLines && charIndex < text.length,
+            lines: includeLines ? lines : undefined,
+          }
+        },
+      }
+
+      return prepared
+    },
+  }
+}
+
+/**
+ * Plugin: add deterministic test text measurement to the engine.
+ */
+export function withTestMeasurer(): FlexilyPlugin {
+  return (engine) => {
+    engine.textLayout = createTestMeasurer()
+    return engine
+  }
+}

package/src/text-layout.ts

@@ -0,0 +1,75 @@
+/**
+ * Text Layout Service — pluggable text measurement for Flexily.
+ *
+ * The TextLayoutService interface decouples text measurement from the layout engine.
+ * Different backends handle different environments:
+ * - MonospaceMeasurer: terminal (1 char = 1 cell)
+ * - DeterministicTestMeasurer: tests/CI (fixed grapheme widths)
+ * - PretextMeasurer: proportional fonts (Canvas measureText)
+ *
+ * See silvery-internal/design/v05-layout/pretext-integration.md for design rationale.
+ */
+
+/** Resolved text style — consumed by both measurement and painting. */
+export interface ResolvedTextStyle {
+  fontShorthand: string // e.g. "14px 'Inter', sans-serif"
+  fontFamily: string
+  fontSize: number
+  fontWeight: number
+  fontStyle: string
+  lineHeight: number
+}
+
+/** Input for text preparation. */
+export interface TextPrepareInput {
+  text: string
+  style: ResolvedTextStyle
+  direction?: "auto" | "ltr" | "rtl"
+  locale?: string
+}
+
+/** Intrinsic text sizes for flexbox min/max-content. */
+export interface IntrinsicSizes {
+  minContentWidth: number // longest unbreakable segment
+  maxContentWidth: number // unwrapped total width
+}
+
+/** Constraints for text layout. */
+export interface TextConstraints {
+  maxWidth?: number
+  maxHeight?: number
+  maxLines?: number
+  wrap?: "normal" | "anywhere" | "none"
+  overflow?: "clip" | "ellipsis"
+  shrinkWrap?: boolean
+}
+
+/** A single laid-out line of text. */
+export interface TextLine {
+  text: string
+  width: number
+  startIndex: number
+  endIndex: number
+}
+
+/** Result of laying out prepared text at a specific width. */
+export interface TextLayout {
+  width: number
+  height: number
+  lineCount: number
+  firstBaseline: number
+  lastBaseline: number
+  truncated: boolean
+  lines?: readonly TextLine[]
+}
+
+/** Prepared text — measured and segmented, ready for layout at any width. */
+export interface PreparedText {
+  intrinsicSizes(): IntrinsicSizes
+  layout(constraints: TextConstraints, options?: { includeLines?: boolean }): TextLayout
+}
+
+/** Pluggable text measurement backend. */
+export interface TextLayoutService {
+  prepare(input: TextPrepareInput): PreparedText
+}