Layout engines for the Zinc UI: naive, Clay or Yoga

Date 2026-10-07. Scope: which flexbox engine zinc:ui uses per platform, given the owner’s wish to port a React Native app and the tiny targets (ESP32, PS1, PS2, Pi1). Inputs: lib/std/ui.ts measure/place/layout (read only, another developer’s uncommitted work), docs/reports/ui-rendering-architecture.md 4.8, docs/reports/ui-style-system.md 5.3, targets/capabilities.json, RULES.md section 4. Measurements were made on this Mac (Apple silicon, clang 17+, -O2) in a scratchpad clone; sources of the benchmark are not committed (reproduction notes in section 3).

1. Decision

1. Pluggable layout behind one interface (zn::ui::Layout, section 5). Two engines, chosen per project/profile: classic (the existing engine, fixed up, default everywhere) and rn (Yoga 3.2.1 vendored, opt-in, default for projects that declare "ui": {"preset": "react-native"}).
2. Yoga is the RN-fidelity engine. It is the engine of React Native itself, so “same semantics” is a property, not a goal; it has the exact RN defaults, a 548-case generated conformance suite taken from Chrome, a measure cache and dirty bits. It costs about 70 KB of code and 584 B per node (heap), so it is never the default on esp32, ps1, ps2.
3. Clay is rejected. It is not smaller (about 86 KB armv6 -Os against Yoga’s 73 KB), has no wrap, margin, shrink, basis, align-self or min-content text rules, is pre-1.0 (v0.14, API changed in the checkout: Clay_EndLayout(deltaTime)), is immediate-mode (the tree is redeclared each frame, which fights Zinc’s retained UiNode tree), and moves away from RN semantics rather than toward them.
4. This revises ui-rendering-architecture.md 4.8 (“do not adopt Taffy or Yoga”). That text rejected Yoga as the only engine because “every demo unchanged” (RULES 1) forbids changing pixels. Opt-in keeps that rule: the demos keep classic; Yoga is only used when asked. The SoA / measure-cache / relayout-boundary work (R5.1, ZN-189) stays, because classic must still be fast on tiny profiles. ST-05 (CSS flex completeness inside classic) shrinks to the cheap subset, see task LE-9: finishing it in full is rewriting Yoga.

2. Candidates

3. Measurements

Tree: header row of 6 items, sidebar of 10 rows (icon + text), a wrapping content area of N cards (title text, wrapped body text, a row of 2 buttons with text), percent widths, padding, gap, grow, measure callbacks (7 px per character, 16 px lines). N=16 gives 175 nodes (the hero page holds about 171). Fake text metrics, so only the layout engine is timed.

Reading: both are far under a frame (16.7 ms) on a desktop; Yoga’s incremental case (one text changed, 7 us) is the typical interaction, Clay re-pays 21-32 us every frame plus the declaration. On a Pi1 (about 30-50 times slower than this core by integer benchmarks, estimate) a full Yoga pass is 2-4 ms and an incremental one 0.3 ms: fine. On ESP32 (240 MHz LX6 with an FPU, estimate 60x slower) 4 ms full: fine for speed; the cost there is RAM: 175 nodes = 100 KB of a 160 KiB heap, and the UiNode tree already uses about 100 KiB (ui.ts comment), so Yoga cannot coexist with classic’s node store on ESP32. PS1 has no FPU: Yoga would run in software float (about 20-50x slower, estimate), not acceptable next to the fx12 profile.

The naive engine was not measured. It is Zinc code allocating arrays per container in measure (const kids: UiNode[] = [], abs) and running on the interpreter or AOT; there is no layout benchmark in bench. LE-2 adds one (section 7). Expect AOT to be within 2-5x of native Yoga for a full pass and always a full pass (no dirty bits), the interpreter far slower. This is the one number a decision should still check, but it does not change it: the engine is chosen for semantics and for the tiny profiles, not for desktop speed.

Reproduce: git clone --depth 1 --branch v3.2.1 https://github.com/facebook/yoga, compile yoga/**/*.cpp with clang++ -std=c++20 -O2 -fno-exceptions -fno-rtti -I., and size; Clay at e6cc369 with -std=c99 and CLAY_IMPLEMENTATION. Yoga’s own tests: tests/generated holds 548 tests in 25 files generated by gentest from HTML fixtures run in Chrome, plus about 35 unit test files (measure cache, rounding, dirty marking, aspect ratio).

4. What classic does differently from React Native (from reading measure/place)

Items 1, 4, 6, 7-9, 11, 12 change pixels when fixed, which is why they cannot be fixed inside classic without violating “all demos unchanged”. Item 4 is the exception: it is a bug; fixing it (re-wrap in place when the final width differs) belongs in classic (LE-8) and is checked against the demo goldens.

5. Integration design

Interface (src/host/layout.h, one header, owned by us, dependency direction as host):

create(node) / destroy(node)
set_style(node, key, value)      // key ids = the PROP table of ui-style-system 5.2 (layout class only)
insert(parent, child, index) / remove(parent, child)
set_measure(node, kind, text_id, font_id, size_x64, tracking)   // native text metrics, no VM re-entry
mark_dirty(node)
calculate(root, w, h)
box(node) -> {x, y, w, h}        // relative to parent, already rounded

classic is the existing Zinc code behind the same calls (no behaviour change; it reads nodes directly). rn is src/host/layout_yoga.cpp (about 400 lines) over third_party/yoga.

Vendoring. third_party/yoga/: yoga/ sources of tag v3.2.1 (commit 042f501), LICENSE, archive sha256 recorded in third_party/README.md, built by our CMake as the static library zn_yoga with -fno-exceptions -fno-rtti, no Java/JS/Gradle, no capture/fuzz. Builds with clang and zig c++ (verified with both targets above). Only the unit tests of the layout core are kept for the conformance job.

Mapping UiNode to YGNode. Created lazily in rn mode at node creation, kept in a handle-indexed table (SoA friendly; UiNode gets no new field).

Implemented in src/host/layout_yoga.cpp (ZN-283): setStyle takes the PROP numbers of lib/std/ui.ts for the layout class and numbers from 1000 for the side-record fields that have none yet (zn::host::LayoutProp documents the value encodings); tests/t0/layout_yoga.sh checks one case per row, the rounding, and the heap after 1000 create/destroy cycles. The measure callbacks are ZN-284.

Text. The measure callback is C++: it reads (text_id, font_id, size, tracking) from the wrapper’s node record and calls the runtime’s text_advance/textWidth and the existing wrap routine (the same code as wrapText; later the HarfBuzz tier of ZN-114 through TextLayout). It returns {width, lines * lineHeight}. No callback into the VM, so it works in the interpreter, the AOT and QuickJS modes. After calculate, ui.ts re-runs wrapText for each text node with its final width (pure, cached by (text, font, width)) to fill lines[]/lineW[] for the painter; this also makes rn and classic agree on the lines of a given box.

Images and fields. Image measure = intrinsic size and aspectRatio from the image; text fields use the 200 px default of classic unless the style gives a width.

Scroll views, layers, anchors. Unchanged: layoutLayers() and applyAnchors() run after calculate and only consume x, y, lw, lh; box() is converted to absolute coordinates by summing parents once (a pass over the tree, no allocation). Virtual lists keep contentH = count*itemH and give Yoga the viewport as a fixed-size scroll node whose realised rows are children.

Dirty flags. A layout-class property write (PROP table class layout) or a text change calls mark_dirty(node) (Yoga propagates to ancestors and stops at a node whose result is cached); layoutDirty stays the global request to run calculate. Paint-only writes (colour, opacity, transform) never touch the engine. A node with fixed width and height is a relayout boundary in Yoga for free.

AOT / ZBC path. Layout lives in the host (zn::host, like Gfx), reached through the runtime-call table, so ZBC needs a handful of new runtime calls (layout_create/set/insert/remove/dirty/calculate/box), not new opcodes; the AOT output links zn_yoga only when the project selects rn. The compiler resolves the option at build time and drops the module otherwise (the zinc:ui/fx pattern of ui-style-system 5.2: an ESP32 app ships none of it). Where the wrapper cannot be linked (a firmware without C++ exceptions-free libstdc++ support, PS1) the build refuses rn with a clear diagnostic.

Selection. zinc.json: "ui": {"layout": "classic" | "rn" | "auto"} and "preset": "react-native" (sets layout: rn, RN style defaults, useWebDefaults off, Errata none). auto reads targets/capabilities.json key ui.layout:

Implemented in ZN-285: "ui": {"layout", "preset"} in zinc.json, the ui group of targets/capabilities.json (layout for auto, rn allowed or not, why), resolved at compile time for the profile or the --target; programs read the result as UI_LAYOUT of zinc:platform. tests/t0/ui_layout_option.sh.

An RN app on a tiny target uses classic: the RN-only styles it relies on (flex 1 equal shares, shrink, aspectRatio, alignContent) must then be handled by LE-9, or the app is not a candidate for that target. This is stated in the docs, not hidden.

Implemented in ZN-288 (LE-9): "preset": "react-native" on a target without Yoga resolves to classic instead of failing (an explicit "layout": "rn" still fails), and in either engine the preset gives React Native’s style semantics: flex: n lowers to grow n, shrink 1, basis 0 (equal shares) and text is black by default (UI_PRESET of zinc:platform). flexShrink, flexBasis, minWidth/maxWidth, alignSelf, aspectRatio and alignContent were already honoured by classic (ST tasks, ZN-358/359); ZN-288 adds CSS’s freeze loop for a growing item with a main-axis min or max, run only when such an item is in the line, so every other line keeps the legacy share. tests/t1/layout_compat.sh runs the cases in both engines: equal boxes except a grow item with a minWidth, where classic follows CSS (250 / 50) and Yoga gives 275 / 25. Size: +1,086 bytes of ZBC on the esp32 profile (467,771 -> 468,857 for the test program).

Implemented in ZN-289 (LE-10): tools/layout-fixtures extracts the 548 cases of Yoga v3.2.1 into tests/golden/layout-conformance/cases.json, tests/t1/layout_conformance.sh runs them through zinc:ui in both engines: rn passes all 227 cases zinc:ui can express, classic 190 (baseline classic.pass, the 37 others in classic.known-fail). The matrix: docs/reports/layout-conformance.md. The run found two bugs of the rn mode, fixed: flexBasis: '0%' was read as auto, and a recycled node handle looked already inserted in its parent’s Yoga children (layout NaN after a removal).

6. Scores (RULES section 4: fit x3, performance x3, size x2, maintainability x2, licence x2, portability x1, effort x1; maximum 70)

Fit: A 2 (does not meet RN semantics, and extending it fully is a Yoga rewrite), B 1, C 4 (loses “demos unchanged” and the tiny targets), D 5. Perf: naive has no dirty bits and allocates (2); Yoga and Clay are microseconds. Size: D counts Yoga as optional, so tiny builds pay 0. Effort: D has the interface plus the wrapper plus the conformance work.

D wins by 3 over C and 14 over A; C would win if the tiny targets were out of scope, which they are not (RULES 1, product vision).

What would make us revisit: the naive engine measuring within 2x of Yoga and growing real RN fidelity cheaply (LE-9 turns out small: drop rn); Yoga’s 7 us incremental advantage mattering on Pi1 (it will not); a Yoga release that drops the C++20 / no-RTTI build; Taffy-in-C++ getting a licence (grid).

7. Conformance plan

1. Fixture corpus (JSON). A script (tools/layout-fixtures, Node, run offline, outputs committed) extracts every case of Yoga’s tests/generated/*.cpp (548) into {name, tree: {style..., children, text}, viewport, expected: [{x, y, w, h}]}. Expectations come from Chrome (that is how Yoga’s tests are generated), so they are CSS-correct, which is what rn with web defaults must match; the RN-default variants are produced by running Yoga itself with RN defaults (golden of the engine, reviewed once).
2. Zinc layout runner (tests/t0/layout_conformance): feeds each fixture to an engine through the section 5 interface and compares boxes with tolerance 0 (rn) or reports (classic). Output is a matrix feature x engine (pass count), committed as docs/reports/layout-conformance.md.
3. rn must pass 100% of the generated cases (they are Yoga’s own tests: a failure means a wrapper bug in mapping or text measure); a handful of RN-specific cases (flex 1 equal shares, percent, w-full, rounding, nested text wrap) are added by hand.
4. classic is tracked, not required: the known-fail list (section 4) must only shrink; LE-8 and LE-9 each move named cases from fail to pass. A random-tree differential (10k trees, the harness of ZN-189 / S10) compares classic before/after any change to prove “zero diffs on the 63 example entries”.
5. Pixel goldens for the examples. Every example entry renders twice: classic (the existing goldens, unchanged) and, for the ones that make sense (hero, maps, bouncing-ball HUD, remarkable), rn, recorded as separate goldens with a reviewed diff image where they differ. The diff list is the migration guide for RN users.
6. Perf gate. tools/bench-m4-style benchmark layout-175 (the tree of section 3, built through the interface): full, one-leaf, clean; --check-regressions at 15% per RULES 7; a size job prints size of the zn_yoga object per target (armv6, aarch64, wasm32) and fails above 90 KB.

8. Proposed backlog tasks

Sizes S (under half a session), M (one session), L (two). None created; this is the proposal. Ids are placeholders.

Order: LE-1 and LE-2 and LE-3 (parallel), LE-8 early (a bug fix users hit today), then LE-4, LE-5, LE-6, LE-7, LE-10, LE-11, LE-9 and LE-12 last.

Edit this page on GitHub ↗