Skip to content

Runtime custom properties: typed lengths resolved where declared - #718

Merged
ide merged 1 commit into
mainfrom
safe-area/2a-runtime-properties
Nov 16, 2026
Merged

ide merged 1 commit into
mainfrom
safe-area/2a-runtime-properties

Conversation

@ide

@ide ide commented Nov 16, 2026

Copy link
Copy Markdown
Member

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*.

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
ide force-pushed the safe-area/2a-runtime-properties branch from fff8770 to d017e83 Compare November 16, 2026 01:06
@ide
ide merged commit c9d43cd into main Nov 16, 2026
0 of 2 checks passed
@ide
ide deleted the safe-area/2a-runtime-properties branch November 16, 2026 01:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants