Repository navigation
Runtime custom properties: typed lengths resolved where declared - #718
Merged
Merged
Conversation
Why
===
LLP 1123 D5 (expo/exact-llp#82, amended by expo/exact-llp#87) has an author declare a custom property on a node, `--gap="8px"`, and read it in a length below, `padding="var(--gap)"`, with CSS Variables 1's unregistered semantics: `var()` in a declaration is substituted at the declaring node and its subtree inherits the result. A capture, `--hero-top="var(--exact-safe-area-inset-top)"`, hands a box's own inset to its subtree, which is how a box inside a nested content owner reads an outer owner's inset (D5, D9). Only a length reads one, so the kernel holds each value as a calculation tree and resolves a reader by substituting trees, with no text parsed while it lays out.
How
===
The kernel holds a node's declarations as one rare row, `safe_area_properties` (bit 255), whose CSS is `--a: <length>; --b: <length>`: each value a length a calculation tree holds (`SafeAreaProperties::value`), with `em`, text styles, platform lengths and an `env()` with a fallback refused. A calculation tree has a `var()` leaf with its name and an optional fallback, which is one value wherever the call stands; the wire carries it as tag 10. `Env::properties` holds what one node's lengths read, made by `owner::properties_at`. Its resolver first walks every declaration a reader reaches, fallback references included, and marks each dependency cycle invalid (Tarjan); it then substitutes the rest where each is declared, a capture taking the declaring node's local inset. A value that reads an undefined `env()`, or exceeds the tree limits of 32 values and 32 levels once expanded (CSS Values 4 §10.8), is invalid; so is every value of a node whose reads reach more than 1,024 declarations. A reader's fallback applies to each.
A change rederives only what it reaches: a declaration change, the readers in the subtree of names whose values changed, below the nodes that declare them again and through the declarations that read them; an inset change, the readers that read an inset or whose properties reach one, in the owner's subtree; a move, the moved subtree's readers when any node declares a property (`NodeArena::declaring_slots`). Each goes through `txn::style_changed` with the rows that read, so a paragraph holding an inline image is measured again, and a reader whose engine style comes out the same lays nothing out. A root font size change rederives property readers, which a `rem` value reaches.
Lowering admits `--name` attributes (the lexer takes every CSS name character), merges a node's, its classes' included, into one row of `--name: value; ` fragments, empty where a class choice, a binding or an option leaves a value `none`, and checks each literal value as one length. Before that, a design token that is a length with one value in every mode is written as its value, read as a length row reads one: through `var()`, which the loader leaves as written in a declaration, or by its name where the text is literal whole, a template whose holes are literal once a component is expanded included. In a template with a hole computed at run time only a `var()` is a token, since the hole's text is unknown; a call in a comment, or of a host's `--exact-` name, is no token. A `var()` in a length row names a design token, a property some node declares, or, with a fallback, a name nothing declares (`lower-var-undeclared`, naming a close match). A fallback is checked as a value of its own: a `var()` in it of a token that has one value in every mode is written as that value, and one of a token that varies by mode, or of another kind than a length, is refused. Exact reserves dotted names for tokens. A property a design token names is refused, and so is a property in an inset override.
The wasm host writes each declaration and the readers' `var()`s for the browser to substitute, names escaped. The JS target writes a bound row one declaration at a time (`declarations.js`), past comments, strings and functions, and removes the ones a node no longer declares. The Apple host sends no row, since the kernel resolves its readers; its calculation bridge carries the root font size, which a `rem` value needs. The runner's agent rows show the declarations.
D5's limits hold: a substituted value clamps to its row's range in the kernel, where a browser makes a lone `var()` of such a literal invalid; a row that takes no percentage refuses one in a fallback too; a bound value's top-level `;` declares what follows it. Runtime custom properties are live once this lands: they add syntax main refused and change nothing an app writes today.
Test Plan
=========
`bun scripts/gate.mjs` passes. `bun scripts/known.mjs -- cargo test --tests --no-fail-fast`, `cargo clippy --all-targets --keep-going -- -D warnings`, `cargo check --workspace --all-targets --keep-going`, `bun scripts/caps.mjs`, `bun scripts/boot.mjs` and `bun scripts/wasm-check.mjs` pass on this commit. `cargo clippy --workspace --all-targets` fails only on two lints in `host/painted` (`src/paint/native.rs`, `src/text/shaping.rs`), which this branch does not touch and main has too.
The behavior is covered by `kernel/src/kernel/property_tests.rs` (declaration changes, removal and shadowing, cycles through used and unused fallbacks, the expansion and walk bounds in both row orders, undefined `env()` in both directions, `VAR(` in any case, moves with no local insets, percentages against each reader's basis, `rem` and the root font size, an inline image measured again), `kernel/src/style/safe_area_properties_tests.rs`, `contract/cli/tests/it/custom_properties.rs` (class choices and an option switched in one runner, tokens in declarations and fallbacks, every refusal), `host/web/src/element_tests.rs`, `host/web-js/custom-properties.test.mjs`, and `host/web/tests/local-insets.test.mjs`, where Chromium computes what the kernel does: a fallback 22px, a capture 47 where a nearer override is 30, a percentage the reader's own, and `declarations.js` writing a row with a comment and an escaped name. Each of these fails its test when the code behind it is removed: moves with no local insets, the paragraph measured again, the root font size, a defined property whatever its fallback reads, class and option fragments, nested fallback checks, the loader leaving a token's `var()` as written, literal templates folded, and comments, host names and escapes in token scanning. `bun host/apple/build.mjs --test --only BoxLayerMacTests` and the iOS class `BoxLayerIOSTests` on the iPhone Duo (iOS 27.1) pass with the bridge's new field.
`bun scripts/known.mjs -- bun test --isolate` over `host/web-js/{custom-properties,dom,tree,lower,modes,cleared-styles,build,lower-equal}.test.mjs` and `host/web/tests/local-insets.test.mjs`, with a Caltrain wasm build as `EXACT_WEB_DIST`, passes except the Firefox case of `cleared-styles.test.mjs`: Firefox does not launch on this Mac ("Could not find profile folder", also from `suiteBrowser('firefox')` alone).
`cargo test --release -p exact-kernel --test it property_cost -- --ignored --nocapture --test-threads=1`, 2,000 readers each eight boxes below the declaring root, on an M5 Pro Mac mini: build and first layout 24.4 ms with literal `8px`, 27.9 ms with `var(--pad)`, 27.6 ms with a capture, 25.5 ms with a plain local-inset reader; a steady relayout 0.25 µs in each; a change every reader sees 6.6 to 7.1 ms with its layout, of which 1.5 ms is the commit (2,001 nodes) and 5.6 ms the layout (18,000 frames). Changes no reader's value depends on lay out no frame: an unread declaration 0.38 ms of commit, an inset under readers of a literal property 0.45 ms, a change below nearer declarations 0.04 ms. A declaration chain doubling at each level costs 50 to 59 ms for 2,000 readers at 8 to 16 levels, the author limits ending it at the fifth.
Review records: expo/exact-llp's `reviews/code-2026-11-15-1123-stage-2a-r*`.
ide
force-pushed
the
safe-area/2a-runtime-properties
branch
from
November 16, 2026 01:06
fff8770 to
d017e83
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
LLP 1123 D5 (expo/exact-llp#82, amended by expo/exact-llp#87) has an author declare a custom property on a node,
--gap="8px", and read it in a length below,padding="var(--gap)", with CSS Variables 1's unregistered semantics:var()in a declaration is substituted at the declaring node and its subtree inherits the result. A capture,--hero-top="var(--exact-safe-area-inset-top)", hands a box's own inset to its subtree, which is how a box inside a nested content owner reads an outer owner's inset (D5, D9). Only a length reads one, so the kernel holds each value as a calculation tree and resolves a reader by substituting trees, with no text parsed while it lays out.How
The kernel holds a node's declarations as one rare row,
safe_area_properties(bit 255), whose CSS is--a: <length>; --b: <length>: each value a length a calculation tree holds (SafeAreaProperties::value), withem, text styles, platform lengths and anenv()with a fallback refused. A calculation tree has avar()leaf with its name and an optional fallback, which is one value wherever the call stands; the wire carries it as tag 10.Env::propertiesholds what one node's lengths read, made byowner::properties_at. Its resolver first walks every declaration a reader reaches, fallback references included, and marks each dependency cycle invalid (Tarjan); it then substitutes the rest where each is declared, a capture taking the declaring node's local inset. A value that reads an undefinedenv(), or exceeds the tree limits of 32 values and 32 levels once expanded (CSS Values 4 §10.8), is invalid; so is every value of a node whose reads reach more than 1,024 declarations. A reader's fallback applies to each.A change rederives only what it reaches: a declaration change, the readers in the subtree of names whose values changed, below the nodes that declare them again and through the declarations that read them; an inset change, the readers that read an inset or whose properties reach one, in the owner's subtree; a move, the moved subtree's readers when any node declares a property (
NodeArena::declaring_slots). Each goes throughtxn::style_changedwith the rows that read, so a paragraph holding an inline image is measured again, and a reader whose engine style comes out the same lays nothing out. A root font size change rederives property readers, which aremvalue reaches.Lowering admits
--nameattributes (the lexer takes every CSS name character), merges a node's, its classes' included, into one row of--name: value;fragments, empty where a class choice, a binding or an option leaves a valuenone, and checks each literal value as one length. Before that, a design token that is a length with one value in every mode is written as its value, read as a length row reads one: throughvar(), which the loader leaves as written in a declaration, or by its name where the text is literal whole, a template whose holes are literal once a component is expanded included. In a template with a hole computed at run time only avar()is a token, since the hole's text is unknown; a call in a comment, or of a host's--exact-name, is no token. Avar()in a length row names a design token, a property some node declares, or, with a fallback, a name nothing declares (lower-var-undeclared, naming a close match). A fallback is checked as a value of its own: avar()in it of a token that has one value in every mode is written as that value, and one of a token that varies by mode, or of another kind than a length, is refused. Exact reserves dotted names for tokens. A property a design token names is refused, and so is a property in an inset override.The wasm host writes each declaration and the readers'
var()s for the browser to substitute, names escaped. The JS target writes a bound row one declaration at a time (declarations.js), past comments, strings and functions, and removes the ones a node no longer declares. The Apple host sends no row, since the kernel resolves its readers; its calculation bridge carries the root font size, which aremvalue needs. The runner's agent rows show the declarations.D5's limits hold: a substituted value clamps to its row's range in the kernel, where a browser makes a lone
var()of such a literal invalid; a row that takes no percentage refuses one in a fallback too; a bound value's top-level;declares what follows it. Runtime custom properties are live once this lands: they add syntax main refused and change nothing an app writes today.Test Plan
bun scripts/gate.mjspasses.bun scripts/known.mjs -- cargo test --tests --no-fail-fast,cargo clippy --all-targets --keep-going -- -D warnings,cargo check --workspace --all-targets --keep-going,bun scripts/caps.mjs,bun scripts/boot.mjsandbun scripts/wasm-check.mjspass on this commit.cargo clippy --workspace --all-targetsfails only on two lints inhost/painted(src/paint/native.rs,src/text/shaping.rs), which this branch does not touch and main has too.The behavior is covered by
kernel/src/kernel/property_tests.rs(declaration changes, removal and shadowing, cycles through used and unused fallbacks, the expansion and walk bounds in both row orders, undefinedenv()in both directions,VAR(in any case, moves with no local insets, percentages against each reader's basis,remand the root font size, an inline image measured again),kernel/src/style/safe_area_properties_tests.rs,contract/cli/tests/it/custom_properties.rs(class choices and an option switched in one runner, tokens in declarations and fallbacks, every refusal),host/web/src/element_tests.rs,host/web-js/custom-properties.test.mjs, andhost/web/tests/local-insets.test.mjs, where Chromium computes what the kernel does: a fallback 22px, a capture 47 where a nearer override is 30, a percentage the reader's own, anddeclarations.jswriting a row with a comment and an escaped name. Each of these fails its test when the code behind it is removed: moves with no local insets, the paragraph measured again, the root font size, a defined property whatever its fallback reads, class and option fragments, nested fallback checks, the loader leaving a token'svar()as written, literal templates folded, and comments, host names and escapes in token scanning.bun host/apple/build.mjs --test --only BoxLayerMacTestsand the iOS classBoxLayerIOSTestson the iPhone Duo (iOS 27.1) pass with the bridge's new field.bun scripts/known.mjs -- bun test --isolateoverhost/web-js/{custom-properties,dom,tree,lower,modes,cleared-styles,build,lower-equal}.test.mjsandhost/web/tests/local-insets.test.mjs, with a Caltrain wasm build asEXACT_WEB_DIST, passes except the Firefox case ofcleared-styles.test.mjs: Firefox does not launch on this Mac ("Could not find profile folder", also fromsuiteBrowser('firefox')alone).cargo test --release -p exact-kernel --test it property_cost -- --ignored --nocapture --test-threads=1, 2,000 readers each eight boxes below the declaring root, on an M5 Pro Mac mini: build and first layout 24.4 ms with literal8px, 27.9 ms withvar(--pad), 27.6 ms with a capture, 25.5 ms with a plain local-inset reader; a steady relayout 0.25 µs in each; a change every reader sees 6.6 to 7.1 ms with its layout, of which 1.5 ms is the commit (2,001 nodes) and 5.6 ms the layout (18,000 frames). Changes no reader's value depends on lay out no frame: an unread declaration 0.38 ms of commit, an inset under readers of a literal property 0.45 ms, a change below nearer declarations 0.04 ms. A declaration chain doubling at each level costs 50 to 59 ms for 2,000 readers at 8 to 16 levels, the author limits ending it at the fifth.Review records: expo/exact-llp's
reviews/code-2026-11-15-1123-stage-2a-r*.