Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions .agents/docs/binding-cases.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The feedback loop is: apply the current rules to concrete upstream behavior; dis

Direct reads still materialize complete snapshots. The measured callback path now preserves the same complete Style capability through on-demand `getStyle()` delivery as recorded in the [read boundary](architecture.md#read-boundary); selective reads remain separate work under the [performance TODO](api-alignment-todos.md#performance).

The evidence baseline for this case is Taffy at revision [`8d13fdc8`](https://github.com/DioxusLabs/taffy/commit/8d13fdc88468c83f01b13b36fadc0349950c6f51), napi 3.12.0, napi-derive 3.6.2, and @napi-rs/cli 3.8.2.
The evidence baseline for this case is Taffy at revision [`77f38568`](https://github.com/DioxusLabs/taffy/commit/77f385683c1d698c91a23a259f87fdddf26925fb), napi 3.12.0, napi-derive 3.6.2, and @napi-rs/cli 3.8.2.

## Case 1: TaffyTree layout state and node identities

Expand Down Expand Up @@ -91,9 +91,9 @@ This case is closed as an API mapping exercise. It fixes the outer state owner,

### Evidence

- [TaffyTree and NodeData implementation](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/taffy_tree.rs)
- [NodeId implementation](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/node.rs)
- [Layout implementation](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/layout.rs)
- [TaffyTree and NodeData implementation](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/taffy_tree.rs)
- [NodeId implementation](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/node.rs)
- [Layout implementation](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/layout.rs)
- [ECMAScript Map objects](https://tc39.es/ecma262/multipage/keyed-collections.html#sec-map-objects)
- [ECMAScript SameValueZero comparison](https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero)

Expand Down Expand Up @@ -614,15 +614,15 @@ The shared definition and stable codes that this case originally left open are n

### Evidence

- [Taffy Style definition and defaults](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/mod.rs)
- [Taffy semantic length types](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/dimension.rs)
- [Taffy alignment types](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/alignment.rs)
- [Taffy Style definition and defaults](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/mod.rs)
- [Taffy semantic length types](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/dimension.rs)
- [Taffy alignment types](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/alignment.rs)
- [CSS Box Alignment overflow-position values](https://www.w3.org/TR/css-align-3/#overflow-values)
- [Taffy geometry types](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/geometry.rs)
- [Taffy grid Style types](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/grid.rs)
- [Taffy geometry types](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/geometry.rs)
- [Taffy grid Style types](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/grid.rs)
- [Yoga 3.2.1 JavaScript wrapper](https://github.com/facebook/yoga/blob/v3.2.1/javascript/src/wrapAssembly.ts)
- [Yoga 3.2.1 native Style normalization](https://github.com/facebook/yoga/blob/v3.2.1/yoga/style/Style.h)
- [TaffyTree Style operations and measurement](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/taffy_tree.rs)
- [TaffyTree Style operations and measurement](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/taffy_tree.rs)
- [napi-rs object conversion](https://napi.rs/docs/concepts/type-conversions)
- [napi-rs enum conversion](https://napi.rs/docs/concepts/enum)
- [TypeScript enum objects and const-enum publication pitfalls](https://www.typescriptlang.org/docs/handbook/enums)
Expand Down Expand Up @@ -718,10 +718,10 @@ Retaining a callback's owned `getStyle` provider remains supported and does not

### Evidence

- [TaffyTree context, dirty-state, and compute operations](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/taffy_tree.rs)
- [Taffy root and cached layout computation](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/compute/mod.rs)
- [Taffy leaf measurement](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/compute/leaf.rs)
- [Taffy per-node cache behavior](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/cache.rs)
- [TaffyTree context, dirty-state, and compute operations](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/taffy_tree.rs)
- [Taffy root and cached layout computation](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/compute/mod.rs)
- [Taffy leaf measurement](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/compute/leaf.rs)
- [Taffy per-node cache behavior](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/cache.rs)
- [napi-rs scoped function calls and pending-exception capture](https://github.com/napi-rs/napi-rs/blob/napi-v3.12.0/crates/napi/src/bindgen_runtime/js_values/function.rs)
- [napi-rs JavaScript exception retention](https://github.com/napi-rs/napi-rs/blob/napi-v3.12.0/crates/napi/src/error.rs)
- [Yoga 3.2.1 JavaScript measure wrapper](https://github.com/facebook/yoga/blob/v3.2.1/javascript/src/wrapAssembly.ts)
Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/binding-mapping.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This is the current reference for Rust/JavaScript conversion and safety in `@taffyjs/node`. It describes the implemented Taffy boundary. Product choices that should constrain future work are recorded in [@taffyjs/node decisions](taffyjs-node-decisions.md).

Recheck version-sensitive behavior whenever Taffy, napi-rs, Node.js, or TypeScript changes. The primary upstream references are [TaffyTree](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/taffy_tree.rs), [Style](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/mod.rs), [geometry](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/geometry.rs), and [napi-rs conversions](https://napi.rs/docs/concepts/type-conversions).
Recheck version-sensitive behavior whenever Taffy, napi-rs, Node.js, or TypeScript changes. The primary upstream references are [TaffyTree](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/taffy_tree.rs), [Style](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/mod.rs), [geometry](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/geometry.rs), and [napi-rs conversions](https://napi.rs/docs/concepts/type-conversions).

## Scope and ownership

Expand Down
10 changes: 5 additions & 5 deletions .agents/docs/query-api-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,13 @@ This design is deliberately smaller than a general query language.

## Why this boundary remains valid

The values covered by this design are finite and non-recursive in the Taffy revision currently pinned by TaffyJS, [`8d13fdc8`](https://github.com/DioxusLabs/taffy/commit/8d13fdc88468c83f01b13b36fadc0349950c6f51).
The values covered by this design are finite and non-recursive in the Taffy revision currently pinned by TaffyJS, [`77f38568`](https://github.com/DioxusLabs/taffy/commit/77f385683c1d698c91a23a259f87fdddf26925fb).

- [`Layout`](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/layout.rs#L263-L294) contains numbers and fixed Point, Size, and Rect records.
- [`DetailedLayoutInfo`](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/layout.rs#L402-L410) currently contains either no details or a Grid value. The Grid details contain fixed records plus arrays of fixed line-position records, line-name strings, and numbers rather than another DetailedLayoutInfo value.
- Style contains fixed records, tagged variants, and collections, but those collections have bounded element shapes. For example, [`GridTemplateComponent::Repeat`](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/grid.rs#L1639-L1648) contains a list of TrackSizingFunction values rather than another list of GridTemplateComponent values. CSS Grid also specifies that [`repeat()` cannot be nested](https://www.w3.org/TR/css-grid/#repeat-notation).
- [`Layout`](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/layout.rs#L263-L294) contains numbers and fixed Point, Size, and Rect records.
- [`DetailedLayoutInfo`](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/layout.rs#L402-L410) currently contains either no details or a Grid value. The Grid details contain fixed records plus arrays of fixed line-position records, line-name strings, and numbers rather than another DetailedLayoutInfo value.
- Style contains fixed records, tagged variants, and collections, but those collections have bounded element shapes. For example, [`GridTemplateComponent::Repeat`](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/grid.rs#L1639-L1648) contains a list of TrackSizingFunction values rather than another list of GridTemplateComponent values. CSS Grid also specifies that [`repeat()` cannot be nested](https://www.w3.org/TR/css-grid/#repeat-notation).

Two related structures are recursive, but neither is embedded in these per-node values. The Taffy node tree refers to children through NodeId and belongs to the tree API. CSS math functions such as `calc()`, `min()`, `max()`, and `clamp()` have a recursive [calculation-tree model](https://www.w3.org/TR/css-values-4/#calc-internal), but [Taffy stores a calc value as an opaque pointer-like handle resolved by the surrounding tree implementation](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/compact_length.rs#L210-L270), not as an expression tree inside Style.
Two related structures are recursive, but neither is embedded in these per-node values. The Taffy node tree refers to children through NodeId and belongs to the tree API. CSS math functions such as `calc()`, `min()`, `max()`, and `clamp()` have a recursive [calculation-tree model](https://www.w3.org/TR/css-values-4/#calc-internal), but [Taffy stores a calc value as an opaque pointer-like handle resolved by the surrounding tree implementation](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/compact_length.rs#L210-L270), not as an expression tree inside Style.

New layout features may add fields, variants, collections, or relationships between nodes without making a per-node Style or Layout recursively contain itself. Those changes can extend the generated selectors without changing this model. If TaffyJS later exposes a genuinely recursive value such as a raw CSS expression tree or layout-fragment tree, the existing query can return the whole value or a reference to it without descending recursively, or that new value can receive a separately designed API.

Expand Down
4 changes: 2 additions & 2 deletions .agents/docs/taffyjs-yoga-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ Primary sources:
- [Yoga pixel-grid processing](https://github.com/facebook/yoga/blob/v3.2.1/yoga/algorithm/PixelGrid.cpp)
- [Yoga flex-basis experiment branch](https://github.com/facebook/yoga/blob/v3.2.1/yoga/algorithm/CalculateLayout.cpp)
- [Yoga WebFlexBasis relayout regression](https://github.com/facebook/yoga/blob/v3.2.1/tests/YGRelayoutTest.cpp)
- [Taffy Style](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/style/mod.rs)
- [Taffy tree and layout storage](https://github.com/DioxusLabs/taffy/blob/8d13fdc88468c83f01b13b36fadc0349950c6f51/src/tree/taffy_tree.rs)
- [Taffy Style](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/style/mod.rs)
- [Taffy tree and layout storage](https://github.com/DioxusLabs/taffy/blob/77f385683c1d698c91a23a259f87fdddf26925fb/src/tree/taffy_tree.rs)
- [Current @taffyjs/node tree wrapper](../../packages/taffyjs-node/src/tree.ts)

The inventory includes package exports, intentional named runtime and type exports, members on the default Yoga object, declared factories and methods, and deliberate behavior added by the JavaScript wrapper. It excludes undocumented Emscripten or Embind implementation artifacts such as the runtime Z property found on factory objects.
Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/technology-stack.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Native bindings and distribution

The binding depends on Taffy by exact Git revision, currently [`8d13fdc8`](https://github.com/DioxusLabs/taffy/commit/8d13fdc88468c83f01b13b36fadc0349950c6f51). The repository publishes npm packages and no Rust crate, so a revision requirement carries no crates.io restriction, and the pinned revision contains upstream fixes that no Taffy release contains. The Git-pin strategy was originally supported by a 500-node nested-flexbox measurement on one macOS arm64 host: on 2026-08-22, Taffy 0.13.0 took 26.15 ms while the then-current post-release revision `55cda62a` took 3.24 ms and the `yoga-layout` baseline remained 9.7 ms. That comparison explains why the project does not fall back to the release tag; it is not a performance claim for the current pin. The retained public dataset is measured on the fixed benchmark host and is normally refreshed after a dependency change. A refresh for `8d13fdc8` remains pending: three complete attempts on 2026-08-23 were rejected by the existing stability gates in different scenarios, so `benchmarks/results/published.json` deliberately remains the dataset from source commit `ccb0c0c108e390bcc88a6832d930a2498bd0630f` and must not be treated as evidence for the current pin. Each published package names the exact revision in its README.
The binding depends on Taffy by exact Git revision, currently [`77f38568`](https://github.com/DioxusLabs/taffy/commit/77f385683c1d698c91a23a259f87fdddf26925fb), which is also the Taffy 0.14.0 release commit. The repository publishes npm packages and no Rust crate, so a Git requirement carries no crates.io restriction. `Cargo.toml` and `Cargo.lock` retain the exact source identity; public package docs name the Taffy release instead of repeating its commit hash when the revision is tagged. The Git-pin strategy was originally supported by a 500-node nested-flexbox measurement on one macOS arm64 host: on 2026-08-22, Taffy 0.13.0 took 26.15 ms while the then-current post-release revision `55cda62a` took 3.24 ms and the `yoga-layout` baseline remained 9.7 ms. That historical comparison is not a performance claim for the current pin. The retained public dataset is measured on the fixed benchmark host, identifies its TaffyJS source commit, and is normally refreshed after a dependency change.

napi-rs owns the Rust-to-Node boundary, private native declarations, native loader, and target-specific package metadata. It generates an ESM loader, which Vite+ bundles into the ESM public entry without maintaining a custom loader. The pinned napi-rs template deliberately emits bare Node builtin specifiers to retain Node 12 compatibility; TaffyJS targets Node 22.20 or newer, so the repository mechanically normalizes those generated specifiers to the explicit `node:` protocol before formatting and bundling the loader.

Expand Down
4 changes: 2 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ rust-version = "1.88"
napi = { version = "=3.12.0", features = ["napi8"] }
napi-build = "=2.4.0"
napi-derive = "=3.6.2"
taffy = { git = "https://github.com/DioxusLabs/taffy", rev = "8d13fdc88468c83f01b13b36fadc0349950c6f51" }
taffy = { git = "https://github.com/DioxusLabs/taffy", rev = "77f385683c1d698c91a23a259f87fdddf26925fb" }

[profile.release]
lto = true
Expand Down
2 changes: 1 addition & 1 deletion apps/website/node/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `@taffyjs/node`

`@taffyjs/node` is the native Node-API binding for Taffy at revision [`8d13fdc8`](https://github.com/DioxusLabs/taffy/commit/8d13fdc88468c83f01b13b36fadc0349950c6f51), an upstream commit after the 0.13.0 release. It provides an explicit in-memory layout tree for Block, Flexbox, and Grid through readable JavaScript inputs and outputs.
`@taffyjs/node` is the native Node-API binding for Taffy 0.14.0. It provides an explicit in-memory layout tree for Block, Flexbox, and Grid through readable JavaScript inputs and outputs.

Follow [Getting Started](../guide/getting-started.md) to install the package and compute a first layout.

Expand Down
2 changes: 1 addition & 1 deletion apps/website/wasm/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `@taffyjs/wasm`

`@taffyjs/wasm` runs the same TaffyJS API through WebAssembly, over Taffy at revision [`8d13fdc8`](https://github.com/DioxusLabs/taffy/commit/8d13fdc88468c83f01b13b36fadc0349950c6f51). Choose it for a bundled browser application, or when you want to use WebAssembly explicitly in Node.js instead of loading a native addon.
`@taffyjs/wasm` runs the same TaffyJS API through WebAssembly, using Taffy 0.14.0. Choose it for a bundled browser application, or when you want to use WebAssembly explicitly in Node.js instead of loading a native addon.

Read the [Design](./design.md) to understand how the package keeps one direct API across native and WebAssembly runtimes.

Expand Down
Loading