yoga-layout 3.0.4: Track layout invalidation via hasNewLayout/markLayoutSeen and load Yoga asynchronously without top-level await in yoga-layout patch releases

# Notes on yoga-layout patch release behavioural fix

### search_known_solution Result
`search_known_solution` returned no matches for `pkg:npm/yoga-layout` (only generic fallback samples unrelated to yoga-layout).

### What a model would have written instead
A model would call `node.hasNewLayout()` / `node.markLayoutSeen()` for layout cache invalidation or import from `yoga-layout/load` in non-top-level-await runtimes expecting them to exist in all Yoga 3.x releases.

### How the wrong version fails
Loudly with a fatal runtime error — in `yoga-layout <= 3.0.2`, `node.hasNewLayout` is `undefined` (throwing `TypeError: node.hasNewLayout is not a function`) and importing `yoga-layout/load` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` / `ERR_MODULE_NOT_FOUND`.

{"case":{"caseId":"case:sha256:f279c35e111e6ada9c3b2027910bc0aefca63a49867d7ded48b9090babb43ce2","contract":["yoga-layout/load exports loadYoga for explicit async initialization without top-level await","newly calculated nodes report hasNewLayout() as true","markLayoutSeen() resets hasNewLayout() to false on inspected nodes","recalculating layout after mutating node geometry flags hasNewLayout() as true again","selective markLayoutSeen preserves uninspected child node status across tree"],"goal":"Track layout invalidation via hasNewLayout/markLayoutSeen and load Yoga asynchronously without top-level await in yoga-layout patch releases","kind":"HOW","packages":["pkg:npm/yoga-layout@3.0.4"],"schemaVersion":1,"symbols":["yoga-layout/load","loadYoga","Node.hasNewLayout","Node.markLayoutSeen","Node.calculateLayout"]},"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.0.4"],"schemaVersion":1,"symbols":["yoga-layout/load","loadYoga","Node.hasNewLayout","Node.markLayoutSeen","Node.calculateLayout"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-yoga-layout-patch-fix",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-yoga-layout-patch-fix",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "yoga-layout": "3.0.4"
      }
    },
    "node_modules/yoga-layout": {
      "version": "3.0.4",
      "resolved": "https://registry.npmjs.org/yoga-layout/-/yoga-layout-3.0.4.tgz",
      "integrity": "sha512-mNmdkofwKGSXUYvo4sDTNI9BXTLAXw/LsBsftEmelPtS/PeePzs4yWe2Q0Y+p5NqadPSAMhAGuIiXs1QiZ+lBg==",
      "license": "MIT"
    }
  }
}

{
  "name": "csx-sample-yoga-layout-patch-fix",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "yoga-layout": "3.0.4"
  }
}

import { loadYoga } from 'yoga-layout/load';

/**
 * Initializes the Yoga WebAssembly module asynchronously without relying on top-level await.
 * This entrypoint was introduced in the yoga-layout 3.0.3/3.0.4 patch release.
 *
 * @returns {Promise<import('yoga-layout').Yoga>}
 */
export async function initYoga() {
  return await loadYoga();
}

/**
 * Traverses a node tree and marks all nodes in the subtree as seen.
 *
 * @param {import('yoga-layout').Node} node
 */
export function markTreeLayoutSeen(node) {
  node.markLayoutSeen();
  const childCount = node.getChildCount();
  for (let i = 0; i < childCount; i++) {
    markTreeLayoutSeen(node.getChild(i));
  }
}

/**
 * Collects an array of all nodes in the tree that report hasNewLayout() === true.
 *
 * @param {import('yoga-layout').Node} node
 * @returns {Array<import('yoga-layout').Node>}
 */
export function collectDirtyNodes(node) {
  const dirty = [];
  function traverse(current) {
    if (current.hasNewLayout()) {
      dirty.push(current);
    }
    const count = current.getChildCount();
    for (let i = 0; i < count; i++) {
      traverse(current.getChild(i));
    }
  }
  traverse(node);
  return dirty;
}

import { strict as assert } from 'node:assert';
import { initYoga, markTreeLayoutSeen, collectDirtyNodes } from '../src/index.mjs';

// -----------------------------------------------------------------------------
// Test 1: yoga-layout/load entrypoint allows explicit asynchronous initialization
// -----------------------------------------------------------------------------
const Yoga = await initYoga();
assert.ok(Yoga, 'Yoga instance must be resolved from loadYoga()');
assert.equal(typeof Yoga.Node.create, 'function', 'Yoga.Node.create must be a factory function');
assert.equal(typeof Yoga.Config.create, 'function', 'Yoga.Config.create must be a factory function');

// -----------------------------------------------------------------------------
// Test 2: Newly calculated nodes report hasNewLayout() === true
// -----------------------------------------------------------------------------
const root = Yoga.Node.create();
root.setWidth(300);
root.setHeight(200);

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

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

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

// Initial state before calculateLayout: node has new layout flag set
assert.equal(typeof root.hasNewLayout, 'function', 'Node must expose hasNewLayout()');
assert.equal(typeof root.markLayoutSeen, 'function', 'Node must expose markLayoutSeen()');
assert.equal(root.hasNewLayout(), true, 'Root node starts with hasNewLayout = true');
assert.equal(child1.hasNewLayout(), true, 'Child 1 starts with hasNewLayout = true');
assert.equal(child2.hasNewLayout(), true, 'Child 2 starts with hasNewLayout = true');

root.calculateLayout(300, 200);

// Verify computed layout metrics
assert.equal(root.getComputedWidth(), 300);
assert.equal(root.getComputedHeight(), 200);
assert.equal(child1.getComputedWidth(), 100);
assert.equal(child2.getComputedWidth(), 100);
assert.equal(root.hasNewLayout(), true, 'Root node reports hasNewLayout = true after calculateLayout()');
assert.equal(child1.hasNewLayout(), true, 'Child 1 reports hasNewLayout = true after calculateLayout()');
assert.equal(child2.hasNewLayout(), true, 'Child 2 reports hasNewLayout = true after calculateLayout()');

const dirtyBefore = collectDirtyNodes(root);
assert.equal(dirtyBefore.length, 3, 'All three nodes in the tree report hasNewLayout() === true');

// -----------------------------------------------------------------------------
// Test 3: markLayoutSeen() resets hasNewLayout() to false on inspected nodes
// -----------------------------------------------------------------------------
markTreeLayoutSeen(root);

assert.equal(root.hasNewLayout(), false, 'markLayoutSeen() resets root hasNewLayout to false');
assert.equal(child1.hasNewLayout(), false, 'markLayoutSeen() resets child1 hasNewLayout to false');
assert.equal(child2.hasNewLayout(), false, 'markLayoutSeen() resets child2 hasNewLayout to false');

const dirtyAfterSeen = collectDirtyNodes(root);
assert.equal(dirtyAfterSeen.length, 0, 'No dirty nodes remain after marking tree seen');

// -----------------------------------------------------------------------------
// Test 4: Recalculating layout after mutating node geometry flags hasNewLayout() as true
// -----------------------------------------------------------------------------
child2.setWidth(150);
root.calculateLayout(300, 200);

assert.equal(root.hasNewLayout(), true, 'Root node receives new layout flag on recalculation');
assert.equal(child2.hasNewLayout(), true, 'Mutated child2 receives new layout flag');
assert.equal(child2.getComputedWidth(), 150, 'Computed width reflects mutation');

// -----------------------------------------------------------------------------
// Test 5: Selective markLayoutSeen preserves uninspected node status
// -----------------------------------------------------------------------------
root.markLayoutSeen();
assert.equal(root.hasNewLayout(), false, 'Root node was marked seen');
assert.equal(child2.hasNewLayout(), true, 'Child 2 remains hasNewLayout = true until explicitly marked');

child2.markLayoutSeen();
assert.equal(child2.hasNewLayout(), false, 'Child 2 marked seen resets to false');

// Clean up WebAssembly memory
root.freeRecursive();

console.log('CONTRACT PASS: yoga-layout async loading and hasNewLayout/markLayoutSeen lifecycle verified');