flexily 0.5.2 → 0.6.0

package/src/pretext-measurer.ts

@@ -1,86 +0,0 @@
-/**
- * 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

@@ -1,219 +0,0 @@
-/**
- * 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/testing.ts

@@ -1,215 +0,0 @@
-/**
- * Flexily Testing Utilities
- *
- * Diagnostic helpers for verifying layout correctness, especially
- * incremental re-layout consistency. Used by downstream consumers
- * (silvery, km-tui) and flexily's own test suite.
- *
- * @example
- * ```typescript
- * import { Node, DIRECTION_LTR } from 'flexily';
- * import { getLayout, diffLayouts, assertLayoutSanity } from 'flexily/testing';
- *
- * const root = Node.create();
- * root.setWidth(80);
- * root.calculateLayout(80, 24, DIRECTION_LTR);
- * assertLayoutSanity(root);
- * const layout = getLayout(root);
- * ```
- */
-
-import { DIRECTION_LTR, MEASURE_MODE_AT_MOST, MEASURE_MODE_EXACTLY } from "./constants.js"
-import type { MeasureFunc } from "./types.js"
-import { Node } from "./node-zero.js"
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface LayoutResult {
-  left: number
-  top: number
-  width: number
-  height: number
-  children: LayoutResult[]
-}
-
-export interface BuildTreeResult {
-  root: Node
-  dirtyTargets: Node[]
-  direction?: number // DIRECTION_LTR or DIRECTION_RTL, defaults to LTR
-}
-
-// ============================================================================
-// Layout Inspection
-// ============================================================================
-
-/** Recursively extract computed layout from a node tree. */
-export function getLayout(node: Node): LayoutResult {
-  return {
-    left: node.getComputedLeft(),
-    top: node.getComputedTop(),
-    width: node.getComputedWidth(),
-    height: node.getComputedHeight(),
-    children: Array.from({ length: node.getChildCount() }, (_, i) => getLayout(node.getChild(i)!)),
-  }
-}
-
-/** Format a layout tree as an indented string for debugging. */
-export function formatLayout(layout: LayoutResult, indent = 0): string {
-  const pad = "  ".repeat(indent)
-  let result = `${pad}{ left: ${layout.left}, top: ${layout.top}, width: ${layout.width}, height: ${layout.height} }`
-  if (layout.children.length > 0) {
-    result += ` [\n${layout.children.map((c) => formatLayout(c, indent + 1)).join(",\n")}\n${pad}]`
-  }
-  return result
-}
-
-/**
- * Collect node-by-node diffs between two layout trees.
- * Returns empty array if layouts match.
- */
-export function diffLayouts(a: LayoutResult, b: LayoutResult, path = "root"): string[] {
-  const diffs: string[] = []
-  // Use Object.is for NaN-safe comparison (NaN === NaN is false, Object.is(NaN, NaN) is true)
-  if (!Object.is(a.left, b.left)) diffs.push(`${path}: left ${a.left} vs ${b.left}`)
-  if (!Object.is(a.top, b.top)) diffs.push(`${path}: top ${a.top} vs ${b.top}`)
-  if (!Object.is(a.width, b.width)) diffs.push(`${path}: width ${a.width} vs ${b.width}`)
-  if (!Object.is(a.height, b.height)) diffs.push(`${path}: height ${a.height} vs ${b.height}`)
-  for (let i = 0; i < Math.max(a.children.length, b.children.length); i++) {
-    if (a.children[i] && b.children[i]) {
-      diffs.push(...diffLayouts(a.children[i]!, b.children[i]!, `${path}[${i}]`))
-    } else if (a.children[i]) {
-      diffs.push(`${path}[${i}]: missing in incremental`)
-    } else {
-      diffs.push(`${path}[${i}]: missing in reference`)
-    }
-  }
-  return diffs
-}
-
-// ============================================================================
-// Measure Functions
-// ============================================================================
-
-/**
- * Wrapping text measure function factory.
- * Simulates text of given width that wraps to multiple lines when constrained.
- */
-export function textMeasure(textWidth: number): MeasureFunc {
-  return (width: number, widthMode: number, _height: number, _heightMode: number) => {
-    if (widthMode === MEASURE_MODE_EXACTLY || widthMode === MEASURE_MODE_AT_MOST) {
-      if (width >= textWidth) return { width: textWidth, height: 1 }
-      const lines = Math.ceil(textWidth / width)
-      return { width: Math.min(textWidth, width), height: lines }
-    }
-    return { width: textWidth, height: 1 }
-  }
-}
-
-// ============================================================================
-// Assertions (throw on failure, no vitest dependency)
-// ============================================================================
-
-/**
- * Assert that all layout values are non-negative and width is finite.
- * Height may be NaN for auto-height trees with unconstrained height.
- * Throws a descriptive error on failure.
- */
-export function assertLayoutSanity(node: Node, path = "root"): void {
-  const w = node.getComputedWidth()
-  const h = node.getComputedHeight()
-  const l = node.getComputedLeft()
-  const t = node.getComputedTop()
-
-  // Width and height should be non-negative when finite.
-  // They can be NaN for auto-sized nodes in unconstrained containers (e.g., absolute children).
-  if (Number.isFinite(w) && w < 0) throw new Error(`${path}: width is negative (${w})`)
-  if (Number.isFinite(h) && h < 0) throw new Error(`${path}: height is negative (${h})`)
-  // Position values can be negative (absolute positioning) or non-finite (unconstrained containers).
-  // Only check that width is not Infinity (NaN is ok for auto-sized).
-  if (w === Infinity || w === -Infinity) throw new Error(`${path}: width is Infinity`)
-
-  for (let i = 0; i < node.getChildCount(); i++) {
-    assertLayoutSanity(node.getChild(i)!, `${path}[${i}]`)
-  }
-}
-
-/**
- * Differential oracle: re-layout of partially-dirty tree must match fresh layout.
- * Throws a descriptive error with node-by-node diff on failure.
- */
-export function expectRelayoutMatchesFresh(
-  buildTree: () => BuildTreeResult,
-  layoutWidth: number,
-  layoutHeight: number,
-): void {
-  // 1. Build, layout, mark dirty, re-layout
-  const { root, dirtyTargets, direction: dir } = buildTree()
-  const layoutDir = dir ?? DIRECTION_LTR
-  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
-  for (const t of dirtyTargets) t.markDirty()
-  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
-  const incremental = getLayout(root)
-
-  // 2. Build identical fresh tree, layout once
-  const fresh = buildTree()
-  fresh.root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
-  const reference = getLayout(fresh.root)
-
-  // 3. Must be identical — show detailed diff on failure
-  const diffs = diffLayouts(reference, incremental)
-  if (diffs.length > 0) {
-    const detail = diffs.map((d) => `  ${d}`).join("\n")
-    throw new Error(
-      `Incremental layout differs from fresh (${diffs.length} diffs):\n${detail}\n\nFresh:\n${formatLayout(reference)}\n\nIncremental:\n${formatLayout(incremental)}`,
-    )
-  }
-}
-
-/**
- * Assert that laying out twice with identical constraints produces identical results.
- * Catches non-determinism or state corruption from a single layout pass.
- */
-export function expectIdempotent(buildTree: () => BuildTreeResult, layoutWidth: number, layoutHeight: number): void {
-  const { root, direction: dir } = buildTree()
-  const layoutDir = dir ?? DIRECTION_LTR
-  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
-  const first = getLayout(root)
-  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
-  const second = getLayout(root)
-
-  const diffs = diffLayouts(first, second)
-  if (diffs.length > 0) {
-    const detail = diffs.map((d) => `  ${d}`).join("\n")
-    throw new Error(`Layout not idempotent (${diffs.length} diffs after 2nd pass):\n${detail}`)
-  }
-}
-
-/**
- * Assert that layout at width W, then different width W', then back to W
- * produces the same result as fresh layout at W.
- * Catches stale cache entries that don't update on constraint change.
- */
-export function expectResizeRoundTrip(buildTree: () => BuildTreeResult, widths: number[]): void {
-  const { root, direction: dir } = buildTree()
-  const layoutDir = dir ?? DIRECTION_LTR
-  for (const w of widths) {
-    root.setWidth(w)
-    root.calculateLayout(w, NaN, layoutDir)
-  }
-  const incremental = getLayout(root)
-
-  // Fresh reference at final width
-  const finalWidth = widths[widths.length - 1]!
-  const fresh = buildTree()
-  fresh.root.setWidth(finalWidth)
-  fresh.root.calculateLayout(finalWidth, NaN, layoutDir)
-  const reference = getLayout(fresh.root)
-
-  const diffs = diffLayouts(reference, incremental)
-  if (diffs.length > 0) {
-    const detail = diffs.map((d) => `  ${d}`).join("\n")
-    throw new Error(`Resize round-trip differs (widths: ${widths.join("→")}, ${diffs.length} diffs):\n${detail}`)
-  }
-}

package/src/text-layout.ts

@@ -1,75 +0,0 @@
-/**
- * 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
-}