flexily 0.2.0 → 0.3.0

package/src/node-zero.ts

@@ -19,6 +19,7 @@ import {
 } from "./types.js"
 import { setEdgeValue, setEdgeBorder, getEdgeValue, getEdgeBorderValue, traversalStack } from "./utils.js"
 import { log } from "./logger.js"
+import { getTrace } from "./trace.js"
 
 /**
  * A layout node in the flexbox tree.
@@ -103,6 +104,8 @@ export class Node {
     lastAvailH: NaN,
     lastOffsetX: NaN,
     lastOffsetY: NaN,
+    lastAbsX: NaN,
+    lastAbsY: NaN,
     layoutValid: false,
     lastDir: 0,
   }
@@ -184,6 +187,18 @@ export class Node {
    * ```
    */
   insertChild(child: Node, index: number): void {
+    // Cycle guard: prevent self-insertion or insertion of an ancestor (would create infinite loop)
+    if (child === this) {
+      throw new Error("Cannot insert a node as a child of itself")
+    }
+    let ancestor: Node | null = this._parent
+    while (ancestor !== null) {
+      if (ancestor === child) {
+        throw new Error("Cannot insert an ancestor as a child (would create a cycle)")
+      }
+      ancestor = ancestor._parent
+    }
+
     if (child._parent !== null) {
       child._parent.removeChild(child)
     }
@@ -240,6 +255,29 @@ export class Node {
     this._baselineFunc = null
   }
 
+  /**
+   * Free this node and all descendants recursively.
+   * Each node is detached from its parent and cleaned up.
+   * Uses iterative traversal to avoid stack overflow on deep trees.
+   */
+  freeRecursive(): void {
+    // Collect all descendants first (iterative to avoid stack overflow)
+    const nodes: Node[] = []
+    traversalStack.length = 0
+    traversalStack.push(this)
+    while (traversalStack.length > 0) {
+      const current = traversalStack.pop() as Node
+      nodes.push(current)
+      for (const child of current._children) {
+        traversalStack.push(child)
+      }
+    }
+    // Free in reverse order (leaves first) to avoid parent.removeChild on already-freed nodes
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      nodes[i]!.free()
+    }
+  }
+
   /**
    * Dispose the node (calls free)
    */
@@ -349,6 +387,7 @@ export class Node {
       Node.measureCacheHits++
       this._measureResult.width = m0.rw
       this._measureResult.height = m0.rh
+      getTrace()?.measureCacheHit(0, w, h, m0.rw, m0.rh)
       return this._measureResult
     }
     const m1 = this._m1
@@ -356,6 +395,7 @@ export class Node {
       Node.measureCacheHits++
       this._measureResult.width = m1.rw
       this._measureResult.height = m1.rh
+      getTrace()?.measureCacheHit(0, w, h, m1.rw, m1.rh)
       return this._measureResult
     }
     const m2 = this._m2
@@ -363,6 +403,7 @@ export class Node {
       Node.measureCacheHits++
       this._measureResult.width = m2.rw
       this._measureResult.height = m2.rh
+      getTrace()?.measureCacheHit(0, w, h, m2.rw, m2.rh)
       return this._measureResult
     }
     const m3 = this._m3
@@ -370,9 +411,13 @@ export class Node {
       Node.measureCacheHits++
       this._measureResult.width = m3.rw
       this._measureResult.height = m3.rh
+      getTrace()?.measureCacheHit(0, w, h, m3.rw, m3.rh)
       return this._measureResult
     }
 
+    // Cache miss
+    getTrace()?.measureCacheMiss(0, w, h)
+
     // Call actual measure function
     const result = this._measureFunc(w, wm, h, hm)
 
@@ -599,8 +644,9 @@ export class Node {
     this._lastCalcH = availableHeight
     this._lastCalcDir = direction
 
-    const start = Date.now()
-    const nodeCount = countNodes(this)
+    // Only compute debug stats when debug logging is enabled (avoid O(n) traversal in production)
+    const start = log.debug ? Date.now() : 0
+    const nodeCount = log.debug ? countNodes(this) : 0
 
     // Reset measure statistics for this layout pass
     Node.resetMeasureStats()
@@ -664,6 +710,56 @@ export class Node {
     return this._layout.height
   }
 
+  /**
+   * Get the computed right edge position after layout (left + width).
+   *
+   * @returns The right edge position in points
+   */
+  getComputedRight(): number {
+    return this._layout.left + this._layout.width
+  }
+
+  /**
+   * Get the computed bottom edge position after layout (top + height).
+   *
+   * @returns The bottom edge position in points
+   */
+  getComputedBottom(): number {
+    return this._layout.top + this._layout.height
+  }
+
+  /**
+   * Get the computed padding for a specific edge after layout.
+   * Returns the resolved padding value (percentage and logical edges resolved).
+   *
+   * @param edge - EDGE_LEFT, EDGE_TOP, EDGE_RIGHT, or EDGE_BOTTOM
+   * @returns Padding value in points
+   */
+  getComputedPadding(edge: number): number {
+    return getEdgeValue(this._style.padding, edge).value
+  }
+
+  /**
+   * Get the computed margin for a specific edge after layout.
+   * Returns the resolved margin value (percentage and logical edges resolved).
+   *
+   * @param edge - EDGE_LEFT, EDGE_TOP, EDGE_RIGHT, or EDGE_BOTTOM
+   * @returns Margin value in points
+   */
+  getComputedMargin(edge: number): number {
+    return getEdgeValue(this._style.margin, edge).value
+  }
+
+  /**
+   * Get the computed border width for a specific edge after layout.
+   *
+   * @param edge - EDGE_LEFT, EDGE_TOP, EDGE_RIGHT, or EDGE_BOTTOM
+   * @returns Border width in points
+   */
+  getComputedBorder(edge: number): number {
+    return getEdgeBorderValue(this._style.border, edge)
+  }
+
   // ============================================================================
   // Internal Accessors (for layout algorithm)
   // ============================================================================

package/src/testing.ts

@@ -37,6 +37,7 @@ export interface LayoutResult {
 export interface BuildTreeResult {
   root: Node
   dirtyTargets: Node[]
+  direction?: number // DIRECTION_LTR or DIRECTION_RTL, defaults to LTR
 }
 
 // ============================================================================
@@ -121,11 +122,13 @@ export function assertLayoutSanity(node: Node, path = "root"): void {
   const l = node.getComputedLeft()
   const t = node.getComputedTop()
 
-  if (w < 0) throw new Error(`${path}: width is negative (${w})`)
-  if (!Number.isFinite(w)) throw new Error(`${path}: width is not finite (${w})`)
-  if (!Number.isFinite(l)) throw new Error(`${path}: left is not finite (${l})`)
+  // 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})`)
-  if (Number.isFinite(t) && t < 0) throw new Error(`${path}: top is negative (${t})`)
+  // 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}]`)
@@ -142,15 +145,16 @@ export function expectRelayoutMatchesFresh(
   layoutHeight: number,
 ): void {
   // 1. Build, layout, mark dirty, re-layout
-  const { root, dirtyTargets } = buildTree()
-  root.calculateLayout(layoutWidth, layoutHeight, DIRECTION_LTR)
+  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, DIRECTION_LTR)
+  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
   const incremental = getLayout(root)
 
   // 2. Build identical fresh tree, layout once
   const fresh = buildTree()
-  fresh.root.calculateLayout(layoutWidth, layoutHeight, DIRECTION_LTR)
+  fresh.root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
   const reference = getLayout(fresh.root)
 
   // 3. Must be identical — show detailed diff on failure
@@ -168,10 +172,11 @@ export function expectRelayoutMatchesFresh(
  * Catches non-determinism or state corruption from a single layout pass.
  */
 export function expectIdempotent(buildTree: () => BuildTreeResult, layoutWidth: number, layoutHeight: number): void {
-  const { root } = buildTree()
-  root.calculateLayout(layoutWidth, layoutHeight, DIRECTION_LTR)
+  const { root, direction: dir } = buildTree()
+  const layoutDir = dir ?? DIRECTION_LTR
+  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
   const first = getLayout(root)
-  root.calculateLayout(layoutWidth, layoutHeight, DIRECTION_LTR)
+  root.calculateLayout(layoutWidth, layoutHeight, layoutDir)
   const second = getLayout(root)
 
   const diffs = diffLayouts(first, second)
@@ -187,10 +192,11 @@ export function expectIdempotent(buildTree: () => BuildTreeResult, layoutWidth:
  * Catches stale cache entries that don't update on constraint change.
  */
 export function expectResizeRoundTrip(buildTree: () => BuildTreeResult, widths: number[]): void {
-  const { root } = buildTree()
+  const { root, direction: dir } = buildTree()
+  const layoutDir = dir ?? DIRECTION_LTR
   for (const w of widths) {
     root.setWidth(w)
-    root.calculateLayout(w, NaN, DIRECTION_LTR)
+    root.calculateLayout(w, NaN, layoutDir)
   }
   const incremental = getLayout(root)
 
@@ -198,7 +204,7 @@ export function expectResizeRoundTrip(buildTree: () => BuildTreeResult, widths:
   const finalWidth = widths[widths.length - 1]!
   const fresh = buildTree()
   fresh.root.setWidth(finalWidth)
-  fresh.root.calculateLayout(finalWidth, NaN, DIRECTION_LTR)
+  fresh.root.calculateLayout(finalWidth, NaN, layoutDir)
   const reference = getLayout(fresh.root)
 
   const diffs = diffLayouts(reference, incremental)

package/src/types.ts

@@ -126,6 +126,10 @@ export interface FlexInfo {
   lastOffsetX: number
   /** Last offsetY passed to layoutNode */
   lastOffsetY: number
+  /** Last absX passed to layoutNode (affects edge-based rounding) */
+  lastAbsX: number
+  /** Last absY passed to layoutNode (affects edge-based rounding) */
+  lastAbsY: number
   /** Whether cached layout is valid (fingerprint matched, not dirty) */
   layoutValid: boolean
   /** Last direction passed to layoutNode */
@@ -198,32 +202,35 @@ export function createValue(value = 0, unit = 0): Value {
 
 /**
  * Create default style.
+ *
+ * Comments indicate where Yoga and CSS defaults differ.
+ * Flexily follows Yoga defaults for API compatibility.
  */
 export function createDefaultStyle(): Style {
   return {
-    display: 0, // DISPLAY_FLEX
-    positionType: 1, // POSITION_TYPE_RELATIVE
+    display: 0, // DISPLAY_FLEX (same in CSS and Yoga)
+    positionType: 1, // POSITION_TYPE_RELATIVE (same in CSS and Yoga)
     position: [createValue(), createValue(), createValue(), createValue(), createValue(), createValue()],
-    flexDirection: 0, // FLEX_DIRECTION_COLUMN (Yoga default, not CSS!)
-    flexWrap: 0, // WRAP_NO_WRAP
-    flexGrow: 0,
-    flexShrink: 0, // Yoga native default (CSS uses 1)
-    flexBasis: createValue(0, 3), // AUTO
-    alignItems: 4, // ALIGN_STRETCH
-    alignSelf: 0, // ALIGN_AUTO
-    alignContent: 1, // ALIGN_FLEX_START
-    justifyContent: 0, // JUSTIFY_FLEX_START
-    width: createValue(0, 3), // AUTO
-    height: createValue(0, 3), // AUTO
+    flexDirection: 2, // FLEX_DIRECTION_ROW — CSS default; Yoga defaults to COLUMN
+    flexWrap: 0, // WRAP_NO_WRAP (same in CSS and Yoga)
+    flexGrow: 0, // (same in CSS and Yoga)
+    flexShrink: 0, // Yoga default; CSS defaults to 1
+    flexBasis: createValue(0, 3), // AUTO (same in CSS and Yoga)
+    alignItems: 4, // ALIGN_STRETCH (same in CSS and Yoga)
+    alignSelf: 0, // ALIGN_AUTO (same in CSS and Yoga)
+    alignContent: 1, // ALIGN_FLEX_START — Yoga default; CSS defaults to STRETCH
+    justifyContent: 0, // JUSTIFY_FLEX_START (same in CSS and Yoga)
+    width: createValue(0, 3), // AUTO (same in CSS and Yoga)
+    height: createValue(0, 3), // AUTO (same in CSS and Yoga)
     minWidth: createValue(),
     minHeight: createValue(),
     maxWidth: createValue(),
     maxHeight: createValue(),
-    aspectRatio: NaN, // undefined by default
+    aspectRatio: NaN, // undefined by default (same in CSS and Yoga)
     margin: [createValue(), createValue(), createValue(), createValue(), createValue(), createValue()],
     padding: [createValue(), createValue(), createValue(), createValue(), createValue(), createValue()],
     border: [0, 0, 0, 0, NaN, NaN],
     gap: [0, 0],
-    overflow: 0, // OVERFLOW_VISIBLE
+    overflow: 0, // OVERFLOW_VISIBLE (same in CSS and Yoga)
   }
 }

package/src/utils.ts

@@ -180,35 +180,61 @@ export function resolveValue(value: Value, availableSize: number): number {
 /**
  * Apply min/max constraints to a size.
  *
- * When size is NaN (auto-sized), min constraints establish a floor.
- * This handles the case where a parent has minWidth/maxWidth but no explicit width -
- * children need to resolve percentages against the constrained size.
+ * CSS behavior:
+ * - min: Floor constraint. Does NOT affect children's layout — the container expands
+ *   after shrink-wrap. When size is NaN (auto-sized), min is NOT applied here;
+ *   the post-shrink-wrap applyMinMax call (Phase 9) handles it.
+ * - max: Ceiling constraint. DOES affect children's layout — content wraps/clips
+ *   within the max. When size is NaN (auto-sized), max constrains the container
+ *   so children are laid out within the max bound.
+ *
+ * Percent constraints that can't resolve (available is NaN) are skipped entirely,
+ * since resolveValue returns 0 for percent-against-NaN, which would incorrectly
+ * clamp sizes to 0.
  */
 export function applyMinMax(size: number, min: Value, max: Value, available: number): number {
   let result = size
 
-  if (min.unit !== C.UNIT_UNDEFINED) {
-    const minValue = resolveValue(min, available)
-    // Only apply if minValue is valid (not NaN from percent with NaN available)
-    if (!Number.isNaN(minValue)) {
-      // When size is NaN (auto-sized), min establishes the floor
-      if (Number.isNaN(result)) {
-        result = minValue
-      } else {
-        result = Math.max(result, minValue)
+  // Apply max first, then min. CSS spec: when min > max, min wins.
+  // By applying max before min, Math.max(result, minValue) ensures min dominates.
+
+  if (max.unit !== C.UNIT_UNDEFINED) {
+    // Skip percent max when available is NaN — can't resolve meaningfully
+    if (max.unit === C.UNIT_PERCENT && Number.isNaN(available)) {
+      // Skip: percent against NaN resolves to 0, which would be wrong
+    } else {
+      const maxValue = resolveValue(max, available)
+      if (!Number.isNaN(maxValue)) {
+        // Apply max as ceiling even when size is NaN (auto-sized).
+        // This constrains children's layout to the max bound.
+        // Phase 9 shrink-wrap may reduce it further; the post-shrink-wrap
+        // applyMinMax call ensures max is still respected.
+        if (Number.isNaN(result)) {
+          // For auto-sized nodes, only apply finite max constraints.
+          // Infinity means "no real constraint" (e.g., silvery sets
+          // maxWidth=Infinity as default) and should not replace NaN.
+          if (maxValue !== Infinity) {
+            result = maxValue
+          }
+        } else {
+          result = Math.min(result, maxValue)
+        }
       }
     }
   }
 
-  if (max.unit !== C.UNIT_UNDEFINED) {
-    const maxValue = resolveValue(max, available)
-    // Only apply if maxValue is valid (not NaN from percent with NaN available)
-    if (!Number.isNaN(maxValue)) {
-      // When size is NaN (auto-sized), max alone doesn't set the size
-      // (the element should shrink-wrap to content, then be capped by max)
-      // Only apply max if we have a concrete size to constrain
-      if (!Number.isNaN(result)) {
-        result = Math.min(result, maxValue)
+  if (min.unit !== C.UNIT_UNDEFINED) {
+    // Skip percent min when available is NaN — can't resolve meaningfully
+    if (min.unit === C.UNIT_PERCENT && Number.isNaN(available)) {
+      // Skip: percent against NaN resolves to 0, which would be wrong
+    } else {
+      const minValue = resolveValue(min, available)
+      if (!Number.isNaN(minValue)) {
+        // Only apply min to definite sizes. When size is NaN (auto-sized),
+        // skip — the post-shrink-wrap applyMinMax call will floor it.
+        if (!Number.isNaN(result)) {
+          result = Math.max(result, minValue)
+        }
       }
     }
   }