yoga-layout 3.2.1: Calculate flexbox layout with yoga-layout: calculateLayout mutates in-place returning undefined rather than a layout object, defaults to column flex-direction, and requires getComputedLayout to inspect geometry

# Notes: yoga-layout Flexbox Layout Calculation API

## What search_known_solution answered
`search_known_solution` returned `MATCH: COMPATIBLE` with low confidence pointing only to unrelated public samples (`drizzle-orm` SQL identifier escaping and SQLite driver setup, and ESM `require()`), indicating no existing sample verified `yoga-layout` layout calculation behavior.

## What a model would have written instead
A naive model would write `const layout = root.calculateLayout(500, 300); return layout.width;`, expect `root.getWidth()` to return `500` as a primitive number, and assume child nodes stack horizontally in `Row` direction by default like standard web CSS flexbox.

## How the wrong version fails
It fails loudly with `TypeError: Cannot read properties of undefined (reading 'width')` because `calculateLayout()` returns `undefined` (mutating the WASM node tree in-place, requiring `getComputedLayout()` or `getComputedWidth()`), and fails assertions because `getWidth()` returns a `Value` struct `{ value: 500, unit: 1 }` rather than a number and children default to `FlexDirection.Column` (`top: 50, left: 0`).

{"case":{"caseId":"case:sha256:1c067540532a4fd40d53f26e3b2143f48efe6e6a12aeb5878e882ddb490c7cfe","contract":["calculateLayout() returns undefined (mutates in-place, does not return layout object)","getComputedLayout() returns { left, right, top, bottom, width, height } object","getComputedWidth() and getComputedHeight() return resolved pixel numbers","getWidth() returns Value object with { value, unit } rather than raw number","default FlexDirection is Column (0) stacking children vertically unless Row is explicitly set","insertChild(child, index) places child at specified index","freeRecursive() frees WebAssembly memory for root and all descendants"],"goal":"Calculate flexbox layout with yoga-layout: calculateLayout mutates in-place returning undefined rather than a layout object, defaults to column flex-direction, and requires getComputedLayout to inspect geometry","kind":"HOW","packages":["pkg:npm/yoga-layout@3.2.1"],"schemaVersion":1,"symbols":["yoga-layout.Node.create","yoga-layout.Node.prototype.calculateLayout","yoga-layout.Node.prototype.getComputedLayout","yoga-layout.Node.prototype.getComputedWidth","yoga-layout.Node.prototype.getComputedHeight","yoga-layout.Node.prototype.getComputedLeft","yoga-layout.Node.prototype.getComputedTop","yoga-layout.Node.prototype.getWidth","yoga-layout.Node.prototype.setFlexDirection","yoga-layout.Node.prototype.insertChild","yoga-layout.Node.prototype.freeRecursive"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/yoga-layout@3.2.1"],"schemaVersion":1,"symbols":["yoga-layout.Node.create","yoga-layout.Node.prototype.calculateLayout","yoga-layout.Node.prototype.getComputedLayout","yoga-layout.Node.prototype.getComputedWidth","yoga-layout.Node.prototype.getComputedHeight","yoga-layout.Node.prototype.getComputedLeft","yoga-layout.Node.prototype.getComputedTop","yoga-layout.Node.prototype.getWidth","yoga-layout.Node.prototype.setFlexDirection","yoga-layout.Node.prototype.insertChild","yoga-layout.Node.prototype.freeRecursive"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-yoga-layout-api",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-yoga-layout-api",
      "version": "1.0.0",
      "license": "ISC",
      "dependencies": {
        "yoga-layout": "^3.2.1"
      }
    },
    "node_modules/yoga-layout": {
      "version": "3.2.1",
      "resolved": "https://registry.npmjs.org/yoga-layout/-/yoga-layout-3.2.1.tgz",
      "integrity": "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==",
      "license": "MIT"
    }
  }
}

{
  "name": "npm-yoga-layout-api",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "yoga-layout": "3.2.1"
  }
}

import assert from 'node:assert/strict';
import Yoga, { FlexDirection, Edge, Unit } from 'yoga-layout';

// 1. Root container creation and dimension setting
const root = Yoga.Node.create();
root.setWidth(500);
root.setHeight(300);

// Trap 1: getWidth() returns a Value object ({ value, unit }), NOT a primitive number
const rawWidth = root.getWidth();
assert.equal(typeof rawWidth, 'object', 'getWidth() must return a Value object');
assert.equal(rawWidth.value, 500, 'Value object contains resolved number');
assert.equal(rawWidth.unit, Unit.Point, 'Unit is Unit.Point (1)');
assert.notEqual(rawWidth, 500, 'getWidth() must not equal primitive number 500');

// Trap 2: Default FlexDirection in Yoga is Column (0), unlike web CSS which defaults to Row
assert.equal(root.getFlexDirection(), FlexDirection.Column, 'Default flexDirection must be Column (0)');

// Create two child nodes
const child0 = Yoga.Node.create();
child0.setWidth(100);
child0.setHeight(50);

const child1 = Yoga.Node.create();
child1.setWidth(100);
child1.setHeight(50);

root.insertChild(child0, 0);
root.insertChild(child1, 1);

// Trap 3: calculateLayout() returns undefined (void); it mutates the tree in-place
const calcResult = root.calculateLayout(500, 300);
assert.equal(calcResult, undefined, 'calculateLayout() returns undefined, not a layout object');

// Trap 4: Computed geometry must be read via getComputedLayout() or getComputed*() methods
const computedRoot = root.getComputedLayout();
assert.deepEqual(computedRoot, {
  left: 0,
  right: 0,
  top: 0,
  bottom: 0,
  width: 500,
  height: 300
}, 'getComputedLayout() returns the computed layout rectangle');

assert.equal(root.getComputedWidth(), 500);
assert.equal(root.getComputedHeight(), 300);

// Under default Column direction, child1 is placed below child0 at top=50, left=0
assert.equal(child0.getComputedLeft(), 0);
assert.equal(child0.getComputedTop(), 0);
assert.equal(child0.getComputedWidth(), 100);
assert.equal(child0.getComputedHeight(), 50);

assert.equal(child1.getComputedLeft(), 0);
assert.equal(child1.getComputedTop(), 50);
assert.equal(child1.getComputedWidth(), 100);
assert.equal(child1.getComputedHeight(), 50);

// 2. Explicit FlexDirection.Row layout
const rowRoot = Yoga.Node.create();
rowRoot.setWidth(500);
rowRoot.setHeight(300);
rowRoot.setFlexDirection(FlexDirection.Row);

const rowChild0 = Yoga.Node.create();
rowChild0.setWidth(100);
rowChild0.setHeight(50);

const rowChild1 = Yoga.Node.create();
rowChild1.setWidth(100);
rowChild1.setHeight(50);

rowRoot.insertChild(rowChild0, 0);
rowRoot.insertChild(rowChild1, 1);
rowRoot.calculateLayout(500, 300);

// Under Row direction, rowChild1 is placed horizontally at left=100, top=0
assert.equal(rowChild0.getComputedLeft(), 0);
assert.equal(rowChild0.getComputedTop(), 0);
assert.equal(rowChild1.getComputedLeft(), 100);
assert.equal(rowChild1.getComputedTop(), 0);

// 3. Percentage sizing and padding/margin resolution
const padRoot = Yoga.Node.create();
padRoot.setWidth(500);
padRoot.setHeight(300);
padRoot.setPadding(Edge.All, 20);

const padChild = Yoga.Node.create();
padChild.setWidth('50%');
padChild.setHeight(100);
padChild.setMargin(Edge.Left, 15);
padChild.setMargin(Edge.Top, 10);

padRoot.insertChild(padChild, 0);
padRoot.calculateLayout(500, 300);

// 50% of inner width (500 - 20 - 20 = 460) is 230
assert.equal(padChild.getComputedWidth(), 230);
// Left position is parent padding left (20) + child margin left (15) = 35
assert.equal(padChild.getComputedLeft(), 35);
// Top position is parent padding top (20) + child margin top (10) = 30
assert.equal(padChild.getComputedTop(), 30);

// 4. Memory deallocation for WebAssembly nodes
root.freeRecursive();
rowRoot.freeRecursive();
padRoot.freeRecursive();