flexily 0.2.0 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ```typescript
-import { Node, FLEX_DIRECTION_ROW, DIRECTION_LTR } from "@beorn/flexily"
+import { Node, FLEX_DIRECTION_ROW, DIRECTION_LTR } from "flexily"
 
 const root = Node.create()
 root.setWidth(100)
@@ -34,7 +34,7 @@ console.log(child.getComputedWidth()) // 100
 
 **No tree-shaking.** The WASM binary is monolithic. You get the entire engine even if you use a fraction of the features.
 
-Facebook's original pure-JS flexbox engine (`css-layout`) was abandoned when they moved to C++. [flexbox.js](https://github.com/Planning-nl/flexbox.js) exists but is unmaintained and missing features. Flexily fills the gap: full CSS flexbox spec, Yoga-compatible API, pure JS, zero WASM.
+Facebook's original pure-JS flexbox engine (`css-layout`) was abandoned when they moved to C++. [flexbox.js](https://github.com/Planning-nl/flexbox.js) exists but is unmaintained and missing features. Flexily fills the gap: comprehensive CSS flexbox support, Yoga-compatible API, pure JS, zero WASM.
 
 ## Who Should Use Flexily
 
@@ -45,11 +45,11 @@ Most developers should use a framework built on Flexily, not Flexily directly. F
 - **Specialized tools** where you need direct control over layout computation
 - **Anyone replacing Yoga** who wants a drop-in pure-JS alternative
 
-> **Building a terminal UI?** Use [silvery](https://github.com/beorn/silvery), which uses Flexily by default. You get React components, hooks, and layout feedback without touching the low-level API.
+> **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.
 
 ## Status
 
-1368 tests passing, including 41/41 Yoga compatibility tests and 1200+ incremental re-layout fuzz tests. Used by [silvery](https://github.com/beorn/silvery) as its default layout engine.
+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.
 
 | Feature                                       | Status   |
 | --------------------------------------------- | -------- |
@@ -68,11 +68,11 @@ Most developers should use a framework built on Flexily, not Flexily directly. F
 ## Installation
 
 ```bash
-bun add @beorn/flexily
-# or
-npm install @beorn/flexily
+npm install flexily
 ```
 
+**Runtimes:** Bun >= 1.0, Node.js >= 18. Pure JavaScript — no native or WASM dependencies.
+
 ## Performance
 
 Flexily and Yoga each win in different scenarios:
@@ -107,13 +107,13 @@ See [docs/performance.md](docs/performance.md) for detailed benchmarks including
 
 Flexily provides two layout implementations that produce identical output and pass identical tests:
 
-**Zero-allocation** (default, `@beorn/flexily`): Mutates `FlexInfo` structs on nodes instead of allocating temporary objects. Faster for flat/wide trees typical of TUI layouts. Not reentrant — a single layout pass must complete before another starts.
+**Zero-allocation** (default, `flexily`): Mutates `FlexInfo` structs on nodes instead of allocating temporary objects. Faster for flat/wide trees typical of TUI layouts. Re-entrant via save/restore of scratch arrays (supports nested `calculateLayout()` calls from measure/baseline functions).
 
-**Classic** (`@beorn/flexily/classic`): Allocates temporary objects during layout. Easier to read and debug. Use this when stepping through the algorithm or comparing behavior.
+**Classic** (`flexily/classic`): Allocates temporary objects during layout. Easier to read and debug. Use this when stepping through the algorithm or comparing behavior.
 
 ```typescript
-import { Node } from "@beorn/flexily" // zero-allocation (default)
-import { Node } from "@beorn/flexily/classic" // allocating (debugging)
+import { Node } from "flexily" // zero-allocation (default)
+import { Node } from "flexily/classic" // allocating (debugging)
 ```
 
 Both implement CSS Flexbox spec Section 9.7 with iterative freeze for min/max constraints, Yoga-compatible edge-based rounding, weighted flex-shrink, auto margin absorption, and full RTL support.
@@ -124,7 +124,7 @@ Incremental re-layout (caching unchanged subtrees) is essential for performance
 
 | Layer              | Tests     | What it verifies                                               |
 | ------------------ | --------- | -------------------------------------------------------------- |
-| Yoga compatibility | 41        | Identical output to Yoga for every feature                     |
+| Yoga compatibility | 44        | Identical output to Yoga for every feature                     |
 | Feature tests      | ~110      | Each flexbox feature in isolation                              |
 | **Re-layout fuzz** | **1200+** | Incremental re-layout matches fresh layout across random trees |
 
@@ -143,7 +143,7 @@ See [docs/testing.md](docs/testing.md) for methodology and [docs/incremental-lay
 
 ## API Compatibility
 
-100% Yoga API compatibility (41/41 comparison tests passing). Drop-in replacement:
+Yoga-compatible API (44 comparison tests passing). Near drop-in replacement for common use cases:
 
 ```typescript
 // Yoga
@@ -152,7 +152,7 @@ const yoga = await Yoga.init() // Async!
 const root = yoga.Node.create()
 
 // Flexily
-import { Node } from "@beorn/flexily"
+import { Node } from "flexily"
 const root = Node.create() // Sync!
 ```
 
@@ -178,7 +178,7 @@ Same constants, same method names, same behavior.
 | [Taffy](https://github.com/DioxusLabs/taffy)            | Rust       | High-performance layout library supporting Flexbox and CSS Grid. Used by Dioxus and Bevy.          |
 | [flexbox.js](https://github.com/Planning-nl/flexbox.js) | JavaScript | Pure JS flexbox engine by Planning-nl. Reference implementation that inspired Flexily's algorithm. |
 | [css-layout](https://www.npmjs.com/package/css-layout)  | JavaScript | Facebook's original pure-JS flexbox, predecessor to Yoga. Deprecated.                              |
-| [silvery](https://github.com/beorn/silvery)             | TypeScript | React for CLIs with layout feedback. Uses Flexily by default.                                      |
+| [silvery](https://silvery.dev)                          | TypeScript | React for CLIs with layout feedback. Uses Flexily by default.                                      |
 
 ## Code Structure
 
@@ -186,7 +186,7 @@ Same constants, same method names, same behavior.
 src/
 ├── index.ts        # Main export
 ├── node-zero.ts    # Node class with FlexInfo
-├── layout-zero.ts  # Layout algorithm (~2300 lines)
+├── layout-zero.ts  # Layout algorithm (~2000 lines)
 ├── constants.ts    # Flexbox constants (Yoga-compatible)
 ├── types.ts        # TypeScript interfaces
 ├── utils.ts        # Shared utilities

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "flexily",
-  "version": "0.2.0",
-  "description": "Pure JavaScript flexbox layout engine with Yoga-compatible API",
+  "version": "0.3.1",
+  "description": "Pure JavaScript flexbox layout engine \u2014 Yoga-compatible API, faster initial layout, smaller bundle, no WASM",
   "keywords": [
+    "canvas-ui",
     "css",
     "flexbox",
     "layout",
+    "measure",
     "pure-javascript",
     "terminal",
     "tui",
+    "ui-layout",
     "yoga",
+    "yoga-alternative",
+    "yoga-wasm",
     "zero-dependency"
   ],
   "homepage": "https://beorn.github.io/flexily/",
@@ -23,46 +28,41 @@
     "url": "https://github.com/beorn/flexily.git"
   },
   "files": [
-    "dist",
     "src"
   ],
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
     },
     "./classic": {
-      "types": "./dist/index-classic.d.ts",
-      "import": "./dist/index-classic.js"
+      "types": "./src/classic/index.ts",
+      "import": "./src/classic/index.ts"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "bench": "bunx --bun vitest bench",
-    "bench:standalone": "bun bench/run.ts",
-    "bench:compare": "bun bench/compare.ts",
     "typecheck": "tsc --noEmit",
-    "build:docs": "cd docs/site && bun run docs:build",
-    "ci": "bun run typecheck && bun test",
-    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
-  },
-  "dependencies": {
-    "debug": "^4.4.3"
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.0",
-    "@types/debug": "^4.1.12",
-    "loggily": "github:beorn/loggily",
-    "typescript": "^5.7.3",
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.1.0",
     "yoga-wasm-web": "^0.3.3"
   },
   "engines": {
-    "bun": ">=1.0",
-    "node": ">=18"
+    "node": ">=23.6.0"
   }
-}
+}

package/src/CLAUDE.md

@@ -16,16 +16,16 @@ Flexily is a pure-JavaScript flexbox layout engine with a Yoga-compatible API. T
                 │                               │
          ┌──────┴──────┐                 ┌──────┴───────┐
          │ node-zero.ts│                 │layout-zero.ts │
-         │  (1412 LOC) │                 │  (1781 LOC)   │
+         │  (1412 LOC) │                 │  (2029 LOC)   │
          │  Node class │                 │  layoutNode   │
          └──────┬──────┘                 └──────┬────────┘
                 │                               │
          ┌──────┴──────┐     ┌──────────────────┼──────────────────┐
          │  types.ts   │     │                  │                  │
          │  Interfaces │  layout-helpers.ts  layout-flex-lines.ts  │
-         └─────────────┘  (140 LOC)         (346 LOC)             │
+         └─────────────┘  (160 LOC)         (349 LOC)             │
                           Edge resolution   Pre-alloc arrays   layout-measure.ts
-                                            Line breaking      (257 LOC)
+                                            Line breaking      (259 LOC)
                                             Flex distribution  measureNode
 
          layout-traversal.ts (70 LOC) - Tree traversal (markSubtreeLayoutSeen, countNodes)
@@ -42,22 +42,22 @@ Flexily is a pure-JavaScript flexbox layout engine with a Yoga-compatible API. T
 - Factory function API: `Node.create()` (no `new` in user code, though `Node` is a class internally)
 - Yoga-compatible API surface: same method names, same constants, drop-in replacement
 - Pure JavaScript: no WASM, no native dependencies, synchronous initialization
-- Single-threaded: layout uses module-level pre-allocated arrays (not reentrant)
+- Module-level pre-allocated arrays with save/restore for re-entrancy (measureFunc/baselineFunc may call calculateLayout on other trees)
 
 ## Source Files
 
 | File                   | LOC   | Role                                                                 | Hot path?                      |
 | ---------------------- | ----- | -------------------------------------------------------------------- | ------------------------------ |
-| `layout-zero.ts`       | 1781  | Core layout: `computeLayout()`, `layoutNode()` (11 phases)           | **Yes** - most critical        |
-| `layout-helpers.ts`    | 140   | Edge resolution: margins, padding, borders                           | **Yes** - called per edge      |
-| `layout-flex-lines.ts` | 346   | Pre-alloc arrays, `breakIntoLines()`, `distributeFlexSpaceForLine()` | **Yes** - flex distribution    |
-| `layout-measure.ts`    | 257   | `measureNode()` — intrinsic sizing                                   | **Yes** - sizing pass          |
+| `layout-zero.ts`       | 2029  | Core layout: `computeLayout()`, `layoutNode()` (11 phases)           | **Yes** - most critical        |
+| `layout-helpers.ts`    | 160   | Edge resolution: margins, padding, borders                           | **Yes** - called per edge      |
+| `layout-flex-lines.ts` | 349   | Pre-alloc arrays, `breakIntoLines()`, `distributeFlexSpaceForLine()` | **Yes** - flex distribution    |
+| `layout-measure.ts`    | 259   | `measureNode()` — intrinsic sizing                                   | **Yes** - sizing pass          |
 | `layout-traversal.ts`  | 70    | Tree traversal: `markSubtreeLayoutSeen()`, `countNodes()`            | Moderate                       |
-| `layout-stats.ts`      | 43    | Debug/benchmark counters                                             | No (counters only)             |
+| `layout-stats.ts`      | 41    | Debug/benchmark counters                                             | No (counters only)             |
 | `node-zero.ts`         | 1412  | Node class, tree ops, caching                                        | **Yes** - second most critical |
-| `types.ts`             | 229   | `FlexInfo`, `Style`, `Layout`, `Value` interfaces                    | No (types only)                |
-| `utils.ts`             | 217   | `resolveValue`, `applyMinMax`, edge helpers, shared traversal stack  | Yes (called frequently)        |
-| `constants.ts`         | 81    | Yoga-compatible numeric constants                                    | No                             |
+| `types.ts`             | 232   | `FlexInfo`, `Style`, `Layout`, `Value` interfaces                    | No (types only)                |
+| `utils.ts`             | 240   | `resolveValue`, `applyMinMax`, edge helpers, shared traversal stack  | Yes (called frequently)        |
+| `constants.ts`         | 82    | Yoga-compatible numeric constants                                    | No                             |
 | `logger.ts`            | 67    | Conditional debug logger (`log.debug?.()`)                           | No (conditional)               |
 | `testing.ts`           | 209   | `getLayout`, `diffLayouts`, `expectRelayoutMatchesFresh`             | No (test only)                 |
 | `classic/`             | ~2900 | Allocating reference algorithm                                       | No (debugging only)            |
@@ -125,6 +125,7 @@ Single pass over children:
 ### Phase 7a: Estimate Line Cross Sizes
 
 - Tentative cross-axis sizes from definite child dimensions
+- For measureFunc children: uses `child.flex.mainSize` (from flex distribution), not parent `mainAxisSize`. This ensures text wrapping is measured at the child's actual constrained width.
 - Auto-sized children use 0 (actual size computed in Phase 8)
 
 ### Phase 7b: Apply alignContent
@@ -146,6 +147,14 @@ The most complex phase. For each relative child:
 8. Apply cross-axis alignment offset (flex-end, center, baseline)
 9. Advance `mainPos` for next child
 
+### Phase 9b: Re-stretch Auto-Sized Cross Axis
+
+- When cross axis was auto (NaN) during Phase 8, `ALIGN_STRETCH` children need re-stretching to the now-known cross size
+
+### Phase 9c: Re-align Auto-Sized Cross Axis
+
+- When `crossAxisSize` was NaN during Phase 8, alignment offsets for `ALIGN_CENTER`, `ALIGN_FLEX_END`, and cross-axis auto margins computed NaN. Phase 9c recomputes these using the final shrink-wrapped cross size.
+
 ### Phase 9: Shrink-Wrap Auto-Sized Containers
 
 - For containers without explicit size, compute actual used space from children
@@ -184,7 +193,7 @@ let _lineItemSpacings = new Float64Array(32) // Per-line item spacing
 
 These grow dynamically if >32 lines (rare). Total memory: ~1,344 bytes (4 Float64Arrays × 256 bytes + 1 Uint16Array × 64 bytes + Array overhead).
 
-**Consequence: Not reentrant.** Layout is single-threaded; concurrent `calculateLayout()` calls corrupt shared state. This is safe because layout is synchronous.
+**Re-entrancy**: A `measureFunc` or `baselineFunc` may synchronously call `calculateLayout()` on a separate tree. `enterLayout()`/`exitLayout()` in `layout-flex-lines.ts` bracket nested calls to save and restore the module-level scratch arrays, preventing corruption of the outer pass's state. Only allocates on re-entrant calls (depth > 0).
 
 ### Per-Node FlexInfo (`node.flex`)
 
@@ -218,6 +227,8 @@ interface FlexInfo {
   lastAvailH
   lastOffsetX
   lastOffsetY
+  lastAbsX
+  lastAbsY
   lastDir
   layoutValid
 }
@@ -275,12 +286,16 @@ flex.lastAvailW = availableWidth
 flex.lastAvailH = availableHeight
 flex.lastOffsetX = offsetX
 flex.lastOffsetY = offsetY
+flex.lastAbsX = absX
+flex.lastAbsY = absY
 flex.lastDir = direction
 flex.layoutValid = true
 ```
 
 On next call, if `layoutValid && !isDirty && same constraints`, the entire subtree is skipped. Only position delta is propagated (if offset changed).
 
+**`absX`/`absY` must be fingerprinted** because edge-based rounding depends on absolute position: `width = round(absX + nodeWidth) - round(absX)`. A fractional shift in absX (e.g., from a sibling's width change) changes the rounded result even when availW/availH/direction are unchanged.
+
 **`Object.is()` is required** for NaN-safe comparison. `NaN === NaN` is `false`; `Object.is(NaN, NaN)` is `true`. NaN represents "unconstrained" -- a legitimate and common constraint value.
 
 ### Invalidation Triggers
@@ -316,11 +331,11 @@ This is Yoga's algorithm. Layout positions stored in `layout.left`/`layout.top`
 
 ## measureNode vs layoutNode
 
-`measureNode()` (~240 lines) is a lightweight alternative to `layoutNode()` (~1650 lines). It computes `width` and `height` but NOT `left`/`top`. Used during Phase 5 for intrinsic sizing of auto-sized container children. Save/restore of `layout.width`/`layout.height` is required around `measureNode` calls because it overwrites those fields.
+`measureNode()` (~260 lines) is a lightweight alternative to `layoutNode()` (~1900 lines). It computes `width` and `height` but NOT `left`/`top`. Used during Phase 5 for intrinsic sizing of auto-sized container children. Save/restore of `layout.width`/`layout.height` is required around `measureNode` calls because it overwrites those fields.
 
-## Integration: How silvery Uses Flexily
+## Integration: How Silvery Uses Flexily
 
-silvery uses flexily through an adapter layer:
+Silvery uses Flexily through an adapter layer:
 
 1. `silvery/src/layout-engine.ts` defines the `LayoutEngine` / `LayoutNode` interfaces
 2. `silvery/src/adapters/flexily-zero-adapter.ts` wraps `Node` in `FlexilyZeroNodeAdapter`
@@ -335,7 +350,7 @@ silvery calls `calculateLayout()` on every render. The no-change case (cursor mo
 | ----------------------------------------- | ---------------------------------------- | ------------------------------------- | ---------------------------------------------- |
 | `overflow:hidden/scroll` + `flexShrink:0` | Item expands to content (ignores parent) | Item shrinks to fit parent            | 4.5: auto min-size = 0 for overflow containers |
 | Default `flexShrink`                      | 0 (Yoga native default)                  | 0 (matches Yoga)                      | CSS default is 1                               |
-| Default `flexDirection`                   | Column                                   | Column                                | CSS default is Row                             |
+| Default `flexDirection`                   | Column                                   | Row (CSS default)                     | Row                                            |
 | Baseline alignment                        | Full spec (recursive first-child)        | Simplified (no recursive propagation) | Recursive first-child                          |
 
 The `flexShrink` override for overflow containers (line ~1244 in layout-zero.ts) is the most significant divergence. Without it, `overflow:hidden` children inside constrained parents balloon to content size, defeating the purpose of clipping.
@@ -362,10 +377,10 @@ Edge-based properties use 6-element arrays: `[left, top, right, bottom, start, e
 
 Border widths are plain numbers (always points). Logical border slots use `NaN` as "not set" sentinel.
 
-### Default Style (Yoga-compatible, not CSS)
+### Default Style
 
 ```typescript
-flexDirection: COLUMN      // CSS default is ROW
+flexDirection: ROW         // CSS default (diverges from Yoga's COLUMN)
 flexShrink: 0              // CSS default is 1
 alignItems: STRETCH        // Same as CSS
 flexBasis: AUTO            // Same as CSS
@@ -451,11 +466,11 @@ cd vendor/flexily && bun run build
 
 | Layer              | Tests     | Command                                                                      | What it verifies                  |
 | ------------------ | --------- | ---------------------------------------------------------------------------- | --------------------------------- |
-| Yoga compat        | 38        | `bun test tests/yoga-comparison.test.ts tests/yoga-overflow-compare.test.ts` | Identical output to Yoga          |
+| Yoga compat        | 44        | `bun test tests/yoga-comparison.test.ts tests/yoga-overflow-compare.test.ts` | Identical output to Yoga          |
 | Feature tests      | ~110      | `bun test tests/layout.test.ts`                                              | Each flexbox feature in isolation |
 | **Re-layout fuzz** | **1200+** | `bun test tests/relayout-consistency.test.ts`                                | Incremental matches fresh         |
 | Mutation testing   | 4+        | `bun scripts/mutation-test.ts`                                               | Fuzz catches cache mutations      |
-| All tests          | 1368      | `bun test`                                                                   | Everything                        |
+| All tests          | 1495      | `bun test`                                                                   | Everything                        |
 
 The fuzz tests are the most important layer. They've caught 3 distinct caching bugs that all single-pass tests missed.
 

package/src/classic/layout.ts

@@ -123,9 +123,9 @@ export function resolveEdgeBorderValue(
 
   // Logical takes precedence if set (NaN = not set)
   if (logicalSlot !== undefined && !Number.isNaN(arr[logicalSlot])) {
-    return arr[logicalSlot]
+    return arr[logicalSlot]!
   }
-  return arr[physicalIndex]
+  return arr[physicalIndex]!
 }
 
 export function markSubtreeLayoutSeen(node: Node): void {
@@ -205,7 +205,10 @@ function breakIntoLines(children: ChildLayout[], mainAxisSize: number, mainGap:
   let lineMainSize = 0
 
   for (const child of children) {
-    const childMainSize = child.baseSize + child.mainMargin
+    // CSS spec 9.3.4: line breaking uses the "hypothetical main size" which is
+    // the flex base size clamped to min/max, not the unclamped base size.
+    const hypotheticalMainSize = Math.max(child.minMain, Math.min(child.maxMain, child.baseSize))
+    const childMainSize = hypotheticalMainSize + child.mainMargin
     const gapIfNotFirst = currentLine.length > 0 ? mainGap : 0
 
     // Check if child fits on current line
@@ -528,7 +531,9 @@ function layoutNode(
   // This ensures children's absolute positions include parent's position offset
   let parentPosOffsetX = 0
   let parentPosOffsetY = 0
-  if (style.positionType === C.POSITION_TYPE_STATIC || style.positionType === C.POSITION_TYPE_RELATIVE) {
+  // CSS spec: position:static ignores insets (top/left/right/bottom).
+  // Only position:relative applies insets as offsets from normal flow position.
+  if (style.positionType === C.POSITION_TYPE_RELATIVE) {
     const leftPos = style.position[0]
     const topPos = style.position[1]
     const rightPos = style.position[2]
@@ -935,6 +940,11 @@ function layoutNode(
           childCross = crossDim.value
         } else if (crossDim.unit === C.UNIT_PERCENT && !Number.isNaN(crossAxisSize)) {
           childCross = crossAxisSize * (crossDim.value / 100)
+        } else if (childLayout.node.children.length > 0) {
+          // Auto-sized container children: Phase 5 already laid them out with
+          // layoutNode to compute baseSize. The cross-axis size is available
+          // on the child's layout (height for row, width for column).
+          childCross = isRow ? childLayout.node.layout.height : childLayout.node.layout.width
         } else {
           // Auto - use a default or measure. For now, use 0 and let stretch handle it.
           childCross = 0
@@ -990,6 +1000,16 @@ function layoutNode(
             }
             break
 
+          case C.ALIGN_SPACE_EVENLY:
+            // Equal spacing between lines and at edges
+            if (numLines > 0) {
+              const spaceEvenlyGap = freeSpace / (numLines + 1)
+              for (let i = 0; i < numLines; i++) {
+                lineCrossOffsets[i]! += spaceEvenlyGap * (i + 1)
+              }
+            }
+            break
+
           case C.ALIGN_STRETCH:
             // Distribute extra space evenly among lines
             if (freeSpace > 0 && numLines > 0) {
@@ -1251,11 +1271,12 @@ function layoutNode(
       const fractionalLeft = innerLeft + childX
       const fractionalTop = innerTop + childY
 
-      // Compute position offsets for RELATIVE/STATIC positioned children
+      // Compute position offsets for RELATIVE positioned children
+      // CSS spec: position:static ignores insets; only position:relative applies them.
       // These must be included in the absolute position BEFORE rounding (Yoga-compatible)
       let posOffsetX = 0
       let posOffsetY = 0
-      if (childStyle.positionType === C.POSITION_TYPE_RELATIVE || childStyle.positionType === C.POSITION_TYPE_STATIC) {
+      if (childStyle.positionType === C.POSITION_TYPE_RELATIVE) {
         const relLeftPos = childStyle.position[0]
         const relTopPos = childStyle.position[1]
         const relRightPos = childStyle.position[2]
@@ -1469,7 +1490,7 @@ function layoutNode(
         }
       }
 
-      if (crossOffset > 0) {
+      if (crossOffset !== 0) {
         if (isRow) {
           child.layout.top += Math.round(crossOffset)
         } else {
@@ -1605,6 +1626,7 @@ function layoutNode(
   // Content box dimensions for percentage resolution of absolute children
   const absContentBoxW = absPaddingBoxW - paddingLeft - paddingRight
   const absContentBoxH = absPaddingBoxH - paddingTop - paddingBottom
+  const isRow = isRowDirection(style.flexDirection)
 
   for (const child of absoluteChildren) {
     const childStyle = child.style
@@ -1626,10 +1648,11 @@ function layoutNode(
     const hasTop = topPos.unit !== C.UNIT_UNDEFINED
     const hasBottom = bottomPos.unit !== C.UNIT_UNDEFINED
 
-    const leftOffset = resolveValue(leftPos, nodeWidth)
-    const topOffset = resolveValue(topPos, nodeHeight)
-    const rightOffset = resolveValue(rightPos, nodeWidth)
-    const bottomOffset = resolveValue(bottomPos, nodeHeight)
+    // Yoga resolves percentage position offsets against the content box dimensions
+    const leftOffset = resolveValue(leftPos, absContentBoxW)
+    const topOffset = resolveValue(topPos, absContentBoxH)
+    const rightOffset = resolveValue(rightPos, absContentBoxW)
+    const bottomOffset = resolveValue(bottomPos, absContentBoxH)
 
     // Calculate available size for absolute child using padding box
     const contentW = absPaddingBoxW
@@ -1702,28 +1725,45 @@ function layoutNode(
     const childHeight = child.layout.height
 
     // Apply alignment when no explicit position set
-    // For absolute children, align-items/justify-content apply when no position offsets
+    // For absolute children, align-items applies on cross axis, justify-content on main axis
+    // Row: X = main axis (justifyContent), Y = cross axis (alignItems)
+    // Column: X = cross axis (alignItems), Y = main axis (justifyContent)
     if (!hasLeft && !hasRight) {
-      // No horizontal position - use align-items (for row) or justify-content (for column)
-      // Default column direction: cross-axis is horizontal, use alignItems
-      let alignment = style.alignItems
-      if (childStyle.alignSelf !== C.ALIGN_AUTO) {
-        alignment = childStyle.alignSelf
-      }
-      const freeSpaceX = contentW - childWidth - childMarginLeft - childMarginRight
-      switch (alignment) {
-        case C.ALIGN_CENTER:
-          childX = childMarginLeft + freeSpaceX / 2
-          break
-        case C.ALIGN_FLEX_END:
-          childX = childMarginLeft + freeSpaceX
-          break
-        case C.ALIGN_STRETCH:
-          // Stretch: already handled by setting width to fill
-          break
-        default: // FLEX_START
-          childX = childMarginLeft
-          break
+      if (isRow) {
+        // Row: X is main axis, use justifyContent
+        const freeSpaceX = contentW - childWidth - childMarginLeft - childMarginRight
+        switch (style.justifyContent) {
+          case C.JUSTIFY_CENTER:
+            childX = childMarginLeft + freeSpaceX / 2
+            break
+          case C.JUSTIFY_FLEX_END:
+            childX = childMarginLeft + freeSpaceX
+            break
+          default: // FLEX_START
+            childX = childMarginLeft
+            break
+        }
+      } else {
+        // Column: X is cross axis, use alignItems/alignSelf
+        let alignment = style.alignItems
+        if (childStyle.alignSelf !== C.ALIGN_AUTO) {
+          alignment = childStyle.alignSelf
+        }
+        const freeSpaceX = contentW - childWidth - childMarginLeft - childMarginRight
+        switch (alignment) {
+          case C.ALIGN_CENTER:
+            childX = childMarginLeft + freeSpaceX / 2
+            break
+          case C.ALIGN_FLEX_END:
+            childX = childMarginLeft + freeSpaceX
+            break
+          case C.ALIGN_STRETCH:
+            // Stretch: already handled by setting width to fill
+            break
+          default: // FLEX_START
+            childX = childMarginLeft
+            break
+        }
       }
     } else if (!hasLeft && hasRight) {
       // Position from right edge
@@ -1734,19 +1774,41 @@ function layoutNode(
     }
 
     if (!hasTop && !hasBottom) {
-      // No vertical position - use justify-content (for row) or align-items (for column)
-      // Default column direction: main-axis is vertical, use justifyContent
-      const freeSpaceY = contentH - childHeight - childMarginTop - childMarginBottom
-      switch (style.justifyContent) {
-        case C.JUSTIFY_CENTER:
-          childY = childMarginTop + freeSpaceY / 2
-          break
-        case C.JUSTIFY_FLEX_END:
-          childY = childMarginTop + freeSpaceY
-          break
-        default: // FLEX_START
-          childY = childMarginTop
-          break
+      if (isRow) {
+        // Row: Y is cross axis, use alignItems/alignSelf
+        let alignment = style.alignItems
+        if (childStyle.alignSelf !== C.ALIGN_AUTO) {
+          alignment = childStyle.alignSelf
+        }
+        const freeSpaceY = contentH - childHeight - childMarginTop - childMarginBottom
+        switch (alignment) {
+          case C.ALIGN_CENTER:
+            childY = childMarginTop + freeSpaceY / 2
+            break
+          case C.ALIGN_FLEX_END:
+            childY = childMarginTop + freeSpaceY
+            break
+          case C.ALIGN_STRETCH:
+            // Stretch: already handled by setting height to fill
+            break
+          default: // FLEX_START
+            childY = childMarginTop
+            break
+        }
+      } else {
+        // Column: Y is main axis, use justifyContent
+        const freeSpaceY = contentH - childHeight - childMarginTop - childMarginBottom
+        switch (style.justifyContent) {
+          case C.JUSTIFY_CENTER:
+            childY = childMarginTop + freeSpaceY / 2
+            break
+          case C.JUSTIFY_FLEX_END:
+            childY = childMarginTop + freeSpaceY
+            break
+          default: // FLEX_START
+            childY = childMarginTop
+            break
+        }
       }
     } else if (!hasTop && hasBottom) {
       // Position from bottom edge
@@ -1769,14 +1831,12 @@ function layoutNode(
 // so the public API remains consistent between versions.
 
 export let layoutNodeCalls = 0
-export let resolveEdgeCalls = 0
 export let layoutSizingCalls = 0
 export let layoutPositioningCalls = 0
 export let layoutCacheHits = 0
 
 export function resetLayoutStats(): void {
   layoutNodeCalls = 0
-  resolveEdgeCalls = 0
   layoutSizingCalls = 0
   layoutPositioningCalls = 0
   layoutCacheHits = 0