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
4 changes: 2 additions & 2 deletions .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/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).
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/b3b387132be1dda0e9d08d5044692236532c166d/src/tree/taffy_tree.rs), [Style](https://github.com/DioxusLabs/taffy/blob/b3b387132be1dda0e9d08d5044692236532c166d/src/style/mod.rs), [geometry](https://github.com/DioxusLabs/taffy/blob/b3b387132be1dda0e9d08d5044692236532c166d/src/geometry.rs), and [napi-rs conversions](https://napi.rs/docs/concepts/type-conversions).

## Scope and ownership

Expand Down Expand Up @@ -88,7 +88,7 @@ Non-Style scalar and fixed-object inputs use concrete napi-rs types where their

Borrowed Rust values never escape. Direct Style reads, Layout, child arrays, detailed Grid data, available space, and nested records are copied into complete detached JavaScript values. A measure callback's Style is first cloned into an owned Rust snapshot and is converted into a complete detached JavaScript value only when its `getStyle()` function is called.

Layout snapshots expose Taffy's `scrollable_overflow_rect` as `scrollableOverflowRect`; `right` and `bottom` are the reachable content extents formerly represented by `contentSize`, while negative `left` and `top` preserve start-side overflow that the old size could not express. Detailed Grid track snapshots expose per-track `positions` and resolved `lineNames`, replacing the old derived `sizes` and `gutters` arrays and preserving content-alignment offsets and logical RTL order.
Layout snapshots expose Taffy's `scrollable_overflow_rect` as `scrollableOverflowRect`; `right` and `bottom` are the reachable content extents formerly represented by `contentSize`, while negative `left` and `top` preserve start-side overflow that the old size could not express. Detailed Grid track snapshots expose per-track `positions`, the optional `emptyAxisLine` for a content-aligned axis with no tracks, and resolved `lineNames`, replacing the old derived `sizes` and `gutters` arrays and preserving content-alignment offsets and logical RTL order.

Binding-produced records and arrays are recursively readonly in TypeScript because mutation cannot update Taffy. Runtime objects remain ordinary mutable, unfrozen objects, and each read or callback `getStyle()` call returns an independent snapshot. There are no live native views, output caches, lazy properties, selectors, prepared queries, or batch snapshots; the callback function is an explicit on-demand operation rather than a property that hides an already materialized object.

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, [`77f38568`](https://github.com/DioxusLabs/taffy/commit/77f385683c1d698c91a23a259f87fdddf26925fb).
The values covered by this design are finite and non-recursive in the Taffy revision currently pinned by TaffyJS, [`b3b38713`](https://github.com/DioxusLabs/taffy/commit/b3b387132be1dda0e9d08d5044692236532c166d).

- [`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).
- [`Layout`](https://github.com/DioxusLabs/taffy/blob/b3b387132be1dda0e9d08d5044692236532c166d/src/tree/layout.rs#L263-L294) contains numbers and fixed Point, Size, and Rect records.
- [`DetailedLayoutInfo`](https://github.com/DioxusLabs/taffy/blob/b3b387132be1dda0e9d08d5044692236532c166d/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, numbers, and an optional empty-axis line 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/b3b387132be1dda0e9d08d5044692236532c166d/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/77f385683c1d698c91a23a259f87fdddf26925fb/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/b3b387132be1dda0e9d08d5044692236532c166d/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
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 [`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.
The binding depends on Taffy by exact Git revision, currently [`b3b38713`](https://github.com/DioxusLabs/taffy/commit/b3b387132be1dda0e9d08d5044692236532c166d), selected from upstream `main` on 2026-08-29. 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 exact revision while the pin is untagged and name the Taffy release when it 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
2 changes: 1 addition & 1 deletion 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 = "77f385683c1d698c91a23a259f87fdddf26925fb" }
taffy = { git = "https://github.com/DioxusLabs/taffy", rev = "b3b387132be1dda0e9d08d5044692236532c166d" }

[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 0.14.0. 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 at upstream main revision [`b3b38713`](https://github.com/DioxusLabs/taffy/commit/b3b387132be1dda0e9d08d5044692236532c166d). 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, 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.
`@taffyjs/wasm` runs the same TaffyJS API through WebAssembly, using Taffy at upstream main revision [`b3b38713`](https://github.com/DioxusLabs/taffy/commit/b3b387132be1dda0e9d08d5044692236532c166d). 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