flexily 0.5.0 → 0.5.2

package/README.md

@@ -16,7 +16,7 @@ root.setWidth(80)
 root.setFlexDirection(FLEX_DIRECTION_ROW)
 
 const label = flex.createNode()
-label.setTextContent("Hello")  // auto-measured: 5 wide
+label.setTextContent("Hello") // auto-measured: 5 wide
 
 const content = flex.createNode()
 content.setFlexGrow(1)
@@ -106,6 +106,7 @@ 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)
@@ -136,7 +137,7 @@ Text measurement backends:
 npm install flexily
 ```
 
-**Runtimes:** Bun >= 1.0, Node.js >= 18. Pure JavaScript — no native or WASM dependencies.
+**Runtimes:** Bun >= 1.0, Node.js >= 23.6. Pure JavaScript — no native or WASM dependencies.
 
 ## Performance
 
@@ -149,7 +150,7 @@ Flexily and Yoga each win in different scenarios:
 | **Single dirty leaf**   | Yoga        | 2.8-3.4x   | 406-969 nodes    |
 | **Deep nesting (15+)**  | Yoga        | increasing | 1 node per level |
 
-Benchmarks use TUI-realistic trees: columns × bordered cards with measure functions (e.g., 5 columns × 20 cards = ~406 nodes, 8×30 = ~969 nodes). Typical depth is 3-5 levels (column → card → content → text). See [docs/performance.md](docs/performance.md) for full methodology.
+Benchmarks use TUI-realistic trees: columns × bordered cards with measure functions (e.g., 5 columns × 20 cards = ~406 nodes, 8×30 = ~969 nodes). Typical depth is 3-5 levels (column → card → content → text). See [docs/guide/performance.md](docs/guide/performance.md) for full methodology.
 
 **Where Yoga wins — and why it matters less in practice.** Yoga is 2.8-3.4x faster in the single-dirty-leaf scenario: one node changes in a ~400-1000 node tree. WASM's per-node layout computation is genuinely faster than JS. But in interactive TUIs, most renders are no-change frames (cursor moved, selection changed) where Flexily is 5.5x faster. Initial layout (new screen, tab switch) also favors Flexily at 1.5-2.5x. The single-dirty-leaf case is a minority of frames in practice.
 
@@ -166,7 +167,7 @@ Flexily's fingerprint cache makes no-change re-layout essentially free (27ns reg
 
 **Use Yoga instead when** your primary workload is frequent incremental re-layout of large pre-existing trees, you have deep nesting (15+ levels), or you're in the React Native ecosystem.
 
-See [docs/performance.md](docs/performance.md) for detailed benchmarks including TUI-realistic trees with measure functions.
+See [docs/guide/performance.md](docs/guide/performance.md) for detailed benchmarks including TUI-realistic trees with measure functions.
 
 ## Algorithm
 
@@ -195,7 +196,7 @@ Incremental re-layout (caching unchanged subtrees) is essential for performance
 
 The fuzz tests use a **differential oracle**: build a random tree, layout, mark nodes dirty, re-layout, then compare against a fresh layout of the identical tree. This has caught 3 distinct caching bugs that all 524 single-pass tests missed.
 
-See [docs/testing.md](docs/testing.md) for methodology and [docs/incremental-layout-bugs.md](docs/incremental-layout-bugs.md) for the bug taxonomy.
+See [docs/guide/testing.md](docs/guide/testing.md) for methodology and [docs/guide/incremental-layout-bugs.md](docs/guide/incremental-layout-bugs.md) for the bug taxonomy.
 
 ## Bundle Size
 
@@ -225,15 +226,15 @@ Same constants, same method names, same behavior.
 
 ## Documentation
 
-| Document                                                   | Description                         |
-| ---------------------------------------------------------- | ----------------------------------- |
-| [Getting Started](docs/getting-started.md)                 | Quick guide to building layouts     |
-| [API Reference](docs/api.md)                               | Complete API documentation          |
-| [Algorithm](docs/algorithm.md)                             | How the layout algorithm works      |
-| [Performance](docs/performance.md)                         | Benchmarks and methodology          |
-| [Yoga Comparison](docs/yoga-comparison.md)                 | Feature comparison with Yoga        |
-| [Testing](docs/testing.md)                                 | Test infrastructure and methodology |
-| [Incremental Layout Bugs](docs/incremental-layout-bugs.md) | Bug taxonomy and debugging guide    |
+| Document                                                         | Description                         |
+| ---------------------------------------------------------------- | ----------------------------------- |
+| [Getting Started](docs/guide/getting-started.md)                 | Quick guide to building layouts     |
+| [API Reference](docs/api/reference.md)                           | Complete API documentation          |
+| [Algorithm](docs/guide/algorithm.md)                             | How the layout algorithm works      |
+| [Performance](docs/guide/performance.md)                         | Benchmarks and methodology          |
+| [Yoga Comparison](docs/guide/yoga-comparison.md)                 | Feature comparison with Yoga        |
+| [Testing](docs/guide/testing.md)                                 | Test infrastructure and methodology |
+| [Incremental Layout Bugs](docs/guide/incremental-layout-bugs.md) | Bug taxonomy and debugging guide    |
 
 ## Related Projects
 
@@ -249,14 +250,17 @@ Same constants, same method names, same behavior.
 
 ```
 src/
-├── index.ts              # Main export (everything)
-├── create-flexily.ts     # createFlexily, createBareFlexily, pipe, FlexilyNode
+├── index.ts              # Main export (everything: createFlexily, Node, constants, plugins)
+├── create-flexily.ts     # createFlexily, createBareFlexily, pipe, FlexilyNode mixin
 ├── 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)
+├── monospace-measurer.ts # Monospace text measurement (terminal: 1 char = 1 cell)
+├── test-measurer.ts      # Deterministic test measurer (Latin 0.8, CJK 1.0, emoji 1.8)
+├── pretext-measurer.ts   # Pretext proportional text plugin (peer dep)
+├── node-zero.ts          # Node class with FlexInfo (hot path)
+├── layout-zero.ts        # Core layout: computeLayout + layoutNode (hot path)
+├── layout-helpers.ts     # Edge resolution: margins, padding, borders (hot path)
+├── layout-flex-lines.ts  # Pre-alloc arrays, line breaking, flex distribution (hot path)
+├── layout-measure.ts     # measureNode — intrinsic sizing (hot path)
 ├── constants.ts          # Flexbox constants (Yoga-compatible)
 ├── types.ts              # TypeScript interfaces
 ├── utils.ts              # Shared utilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexily",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Pure JavaScript flexbox layout engine — composable plugins, text measurement, Yoga-compatible API, no WASM",
   "keywords": [
     "canvas-ui",
@@ -17,7 +17,7 @@
     "yoga-wasm",
     "zero-dependency"
   ],
-  "homepage": "https://beorn.github.io/flexily/",
+  "homepage": "https://beorn.codes/flexily/",
   "bugs": {
     "url": "https://github.com/beorn/flexily/issues"
   },
@@ -41,6 +41,10 @@
     "./classic": {
       "types": "./src/classic/index.ts",
       "import": "./src/classic/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing.ts",
+      "import": "./src/testing.ts"
     }
   },
   "publishConfig": {
@@ -58,12 +62,17 @@
     "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
+    "@types/node": "^25.5.0",
+    "loggily": "^0.4.2",
     "typescript": "^5.9.3",
     "vitepress": "^1.6.3",
+    "vitepress-enrich": "^0.4.0",
+    "vitepress-plugin-llms": "^1.0.0",
     "vitest": "^3.1.0",
     "yoga-wasm-web": "^0.3.3"
   },
   "engines": {
+    "bun": ">=1.0",
     "node": ">=23.6.0"
   }
 }

package/src/logger.ts

@@ -14,11 +14,12 @@ interface ConditionalLogger {
 
 let _logger: ConditionalLogger | null = null
 
-function createFallbackLogger(namespace: string): ConditionalLogger {
-  // Dynamic require to avoid bundling debug if not needed
+async function createFallbackLogger(namespace: string): Promise<ConditionalLogger> {
+  // Dynamic import to avoid bundling debug if not needed
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const createDebug = require("debug") as (ns: string) => DebugFn & { enabled: boolean }
+    const { default: createDebug } = (await import("debug")) as {
+      default: (ns: string) => DebugFn & { enabled: boolean }
+    }
     const debug = createDebug(namespace)
     return { debug: debug.enabled ? debug : undefined }
   } catch {