@blankparticle/yoga-layout

@blankparticle/yoga-layout

A pure TypeScript implementation of the Yoga layout engine, optimized for JavaScript runtimes. It exposes the same ESM entry points as yoga-layout while avoiding the JavaScript-to-WebAssembly boundary.

The implementation is validated against the Yoga source snapshot pinned in reference/yoga. Differential tests build that snapshot with the repository's patches/yoga-f64.patch, making Yoga use the same binary64 number model as JavaScript instead of treating expected float32 rounding as port failures.

Using it as an override

Once published, a pnpm consumer can replace Yoga without changing application code:

{
  "pnpm": {
    "overrides": {
      "yoga-layout": "npm:@blankparticle/yoga-layout@<version>"
    }
  }
}

For local development, point the override at this directory instead:

{
  "pnpm": {
    "overrides": {
      "yoga-layout": "file:../yoga-layout-js"
    }
  }
}

The package ships compiled ESM and TypeScript declarations. Consumers do not need a TypeScript loader and do not compile the engine's source.

Development

vp install
git submodule update --init --recursive
vpr typecheck
vpr generate:enums
vpr check:generated
vpr test
vpr test:official
vpr test:local
vpr test:differential
vpr fuzz
vpr fuzz:differential
vpr fuzz:loop
vpr fuzz:smoke
vpr test:package
vpr test:ink
vpr test:ink:smoke
vpr test:all
vpr benchmark
vpr setup:ink
vpr benchmark:ink
vpr benchmark:ink:rerender

test:ink builds this package, injects it as Ink's yoga-layout import, and runs every AVA test in the Ink source snapshot pinned in reference/ink. The override is inherited by AVA workers and Ink's spawned terminal fixtures. test:ink:smoke remains available for a quick integration check.

benchmark:ink runs Ink's checked-in simple and static benchmark programs unchanged in isolated processes, once against this engine and once against the Yoga WASM version resolved by that Ink snapshot. It reports wall time, user and system CPU time, and peak RSS. The simple fixture performs 100,000 real Ink rerenders and can take several minutes. benchmark:ink:rerender is the smaller project-owned rerender comparison intended for quick iteration.

The setup command installs the Ink submodule's development dependencies without changing its lockfile or running unrelated dependency lifecycle scripts:

vpr setup:ink
vpr build
vpr benchmark:ink

The test layers are:

• Yoga's official JavaScript and generated conformance suites, consumed unchanged from reference/yoga/javascript/tests/;
• additional C++-API ports and project regressions in test/ for this implementation, including JS-only API behavior;
• focused layout and public-surface differential tests in test/differential/ and test/PublicApiTest.test.ts, run against the locally built reference WASM;
• a built-package API smoke test in test/package/;
• Ink's complete AVA suite with this engine substituted for yoga-layout.

src/generated/YGEnums.ts is generated from the enum definitions in the pinned Yoga source. generate:enums runs Yoga's canonical enums.py generator and syncs its TypeScript output with this project's license header; check:generated guards against a stale committed file.

Fuzzing

The structured fuzzers generate bounded trees across dimensions, intrinsic sizes, percentages, flex properties, alignment, wrapping, gaps, box edges, positioning, display, overflow, aspect ratios, measure functions, direction, and configuration modes.

# TypeScript crash, determinism, and layout-invariant campaign (10,000 cases)
vpr fuzz

# Compare generated layouts with the f64 WASM built from pinned Yoga (1,000 cases)
vpr fuzz:differential

# Replay one failure or run a larger bounded campaign
vpr fuzz:differential -- --seed 160575059 --runs 1
vpr fuzz:differential -- --runs 10000 --max-nodes 40

# Continuously exercise determinism and JS/f64-WASM parity until Ctrl+C
vpr fuzz:loop -- --max-nodes 40 --report-every 1000

With no --seed, each campaign chooses and prints a random base seed. Failures print a one-case replay command and write a self-contained report under the ignored .reference/fuzz-failures/ directory, including the generated case, exception stack, runtime details, and timestamp. fuzz:smoke is deterministic and is included in test:all.

fuzz:loop builds the f64 reference engine once, then continuously runs both TypeScript determinism/invariant checks and WASM differential checks. It keeps going after failures and stores deduplicated, self-contained records under .reference/fuzz-failures/loop/. Records include both engine outcomes, layout snapshots or exception stacks, campaign position, runtime details, occurrence counts, and recent seeds. SIGINT and SIGTERM flush the current record and print a final campaign summary.

To leave a campaign running from a shell and keep its console log:

vpr fuzz:loop -- --max-nodes 40 --report-every 10000 > .reference/fuzz-loop.log 2>&1 &

Local, aggregate, and benchmark commands build the reference WASM first. build:reference temporarily applies patches/yoga-f64.patch, builds Yoga, copies the matching f64 runtime wrapper into ignored .reference/yoga-f64/, and restores the submodule even when the build fails. It also recovers and restores the patch if an earlier build was interrupted. Generated WASM and wrapper files are ignored, so none are committed or published:

vpr build:reference
vpr test:local
vpr test:package
vpr test:ink
vpr test:all

Reference source

reference/yoga and reference/ink are clean Git submodules at rest. They pin the C++ implementation, test corpus, and Ink source used for development without mixing any of them or their generated artifacts into the published package. The maintained f64 delta lives outside the Yoga submodule in patches/yoga-f64.patch.

git submodule update --init --recursive

License

This project is distributed under the MIT license. Portions are derived from Yoga; its original copyright and MIT terms are preserved in THIRD_PARTY_NOTICES.md.