@qxuken/kui 0.1.0-alpha.44 → 0.1.0-alpha.46

package/CHANGELOG.md

@@ -21,6 +21,281 @@ listed under both (backlog F61, from the alpha.12 field reports: the list
 is what the release knows it broke, and a fix it did not think of as one
 was the first bare bump to break an app in five releases).
 
+## 0.1.0-alpha.46 (2026-10-09)
+
+**What breaks.**
+
+- C ABI 27 (under Added, F131): `KuiClip` grows from eight words to
+  twenty — `transform`, `inner` and `inner_radius` — so a host that
+  strides `KuiDrawData.clips` reads the new stride and the conformance
+  digest hashes the whole entry; `KuiSpec` appends `rotate`, `scale`,
+  `pivot_set`, `pivot_x`, `pivot_y` and `iterations` (F133; 64-bit size
+  744), `KuiKeyframe` and `KuiEnter` append `rotate` and `scale`, and
+  `KuiKeyframe` `dx` and `dy` with `KUI_KF_OFFSET` (strides 52 and 48;
+  F132). `KuiSpec` holds `KuiEnter` twice by value, as `enter` and
+  `exit`, so its fields after `enter` move by 8 bytes and those after
+  `exit` by 16: recompile, and re-derive the offsets of a hand-written
+  mirror (ctypes, Zig, an Odin of its own) rather than append to it. A
+  zeroed field is what every spec, stop and entrance had before. Node's
+  `clips()` buffer has the same stride, and `decodeClips` reads
+  `transform`, `inner` and `innerRadii`. A renderer of its own that
+  ignores the new words draws a turned subtree upright.
+- Rust struct literals: none of these is `#[non_exhaustive]`, so a
+  literal that names every field gains the new ones or a `..` base —
+  `Clip` (`transform`, `inner`, `inner_radius`; it has no `Default`,
+  so `..Clip::NONE`), `Keyframe` (`dx`, `dy`), `Slots` and `Enter`
+  (`rotate`, `scale`), `AnimSpec::iterations`,
+  `InteractSpec::transform`, `NodeInfo` (`rotate`, `scale`),
+  `HitRegion::turn`, `ScrollRegion::turn` and `EnvFacts::now`.
+- Node's `WarningCode` union gains `'ambiguous-name'` (F137): a
+  `switch` over it that TypeScript checks for exhaustiveness names it.
+
+### Added
+
+- **A node turns about its pivot** (backlog F131, from berainder's
+  review; [ADR 0043](docs/adr/0043-a-node-turns-about-its-pivot.md)).
+  `rotate` (turns, clockwise), `scale` (a uniform factor) and
+  `pivotX` / `pivotY` (fractions of the box, the centre by default) on
+  any node — `NodeSpec::rotate` / `scale` / `pivot` in Rust, the rows in
+  JSX and Lua, `KuiSpec.rotate` / `scale` / `pivot_set` with
+  `KUI_PIVOT_X` / `KUI_PIVOT_Y` in C (ABI 27), the generated `Spec`
+  fields in Odin. Paint-only: the node takes the room its upright self
+  takes and `onLayout` reports the layout rect; everything the subtree
+  draws turns with it — backgrounds, borders, shadows, text, images,
+  strokes, fragments — and so does what it clips, so a photo stays
+  inside a tilted card's rounded corners. Hit where drawn: a tilted
+  card is grabbed on its tilted edge, a press in its box past its edge
+  falls through, a scroller inside a turn takes the wheel where it is
+  drawn; the access rect is the bounding box. Turns nest by
+  composition; a float anchored to its parent turns with it, a viewport
+  float does not. A turn and a scale are one slot that tweens with
+  `transition` — a card follows the pointer while a drag holds the
+  transition off and springs back when it is on — and an entrance, an
+  exit and a keyframe stop name `rotate` and `scale` (`enter: { scale:
+  0.8 }`, `keyframes: [{ rotate: 0 }, { rotate: 1 }]` spins a box); a
+  departing subtree keeps its turn. On the wire the clip entry carries
+  the space (`Clip::transform`, `inner`, `inner_radius`); the quad does
+  not change. A `path`'s own `rotate` keeps ADR 0041's meaning and
+  composes under the node's. The `transform` example.
+- `Transform`, the similarity a clip entry carries, with `about`,
+  `apply`, `unapply`, `then`, `bounds`; `Clip::turned`, `turned_by`,
+  `visible`, `shown`; `HitTurn` on a hit region and a scroll region;
+  `NodeInfo::rotate` / `scale` in the devtools' facts (F131).
+- **A keyframe stop names a position** (backlog F132, from berainder's
+  review). `dx` / `dy` on a stop — `Keyframe::dx` / `dy` / `offset` in
+  Rust, the stop's fields in JSX and Lua, `KuiKeyframe.dx` / `dy` with
+  `KUI_KF_OFFSET` in C (ABI 27), `Keyframe.dx` / `dy` with `.Offset` in
+  Odin — are logical px from where layout put the node, as an entrance's
+  are: the node and its subtree are drawn, hit and read by assistive
+  technology that far away at the stop, a lane a stop leaves out is 0,
+  and the offset adds to a `slide`'s. `[{ dy: 0 }, { dy: -6 }]` with
+  `repeat: 'alternate'` bobs a box; three stops drift a sparkle up as it
+  fades. Paint, hit and access only: the room the node takes is its
+  place's, and an `onLayout` node reports its layout rect, not a cycle
+  that would post an event every frame it ran. The `transition` example
+  has a bob and a sparkle.
+- **A keyframe cycle plays so many times** (backlog F133, from
+  berainder's review). `iterations` — CSS's `animation-iteration-count`:
+  `NodeSpec::iterations` in Rust, the row in JSX and Lua, `KuiSpec.iterations`
+  in C (0 is for ever; ABI 27), the generated `Spec.iterations` in Odin.
+  Left out, a cycle runs for ever and reads the clock as it always did,
+  so siblings stay in phase. A finite one plays from the first frame its
+  node is declared with it, holds its first stop through its `delay`,
+  and rests where its last iteration ended (CSS's fill `both`); then it
+  owes no frame, so `animating()`, `owed()` and the frame trace go quiet
+  as a settled transition's do. `1` plays a burst or a shake once, `2`
+  alternating goes out and back, `0.5` stops halfway; `delay` plus
+  `iterations: 1` staggers one-shots. A node that leaves and comes back
+  plays again, and so does one whose stops the view drops for a frame
+  and declares again: that is how a view replays it.
+- **The view reads the frame clock** (backlog F134). `Ui::now` /
+  `Core::now` in Rust, `env.now` in Lua, `kui_now` in C, `now` in Odin,
+  `ctx.now()` in Node: the driver's seconds that `transition` and
+  `keyframes` read this frame, 0 before a driver sets one. A deadline
+  read off it — a toast's expiry, a sequence's beats — agrees with the
+  core's easing, and a test's `advance` moves both.
+- **A frame asked for at a time** (backlog F135). `Ui::request_frame_at`
+  / `Core::request_frame_at` and `Core::next_frame_at` in Rust,
+  `env.request_frame_at` in Lua, `kui_request_frame_at` /
+  `kui_next_frame_at` in C (`INFINITY` for none), the same doors in Odin,
+  `ctx.requestFrameAt` / `nextFrameAt` in Node; `Waker::wake_at(Instant)`
+  for a thread. On the frame clock: the runner sleeps to the earliest
+  time asked for and runs the view, with nothing owed until then, so
+  `animating()` stays false. A time already past is a frame now; the
+  time is kept until a frame reaches it.
+- **The exit named at the removal** (backlog F136). `Ui::exit_with` /
+  `Core::set_exit` in Rust, `env.exit_with` in Lua, `kui_exit_with` in
+  C, `exit_with` in Odin, `ctx.exitWith` in Node: the exit a node leaves
+  by if it leaves in the frame that finishes next, over the one its
+  last frame declared, so the handler that removes a card says which way
+  it goes. It lapses when that frame finishes; it aims a node that
+  declares an `exit`, with that node's `transition`.
+- **A lookup by accessible name** (backlog F137). `Core::key_named` /
+  `Drive::key_named` in Rust, `kui_key_named` in C, `key_named` in Odin,
+  `ctx.keyNamed` in Node: the first node in the last frame whose
+  accessible name — its `label`, else a control's text — is the one
+  asked for, so a test presses "the button named Like" as a reader would.
+  Two with one name raise the new `ambiguous-name` warning. The docs now
+  say "key label" for what `key_of` and `texts_under` read, the name the
+  view opened a node under, and "accessible name" for the `label` row.
+- **The runner decodes images, GIFs included** (backlog F138).
+  `kui_native::decode_image(bytes)` turns PNG, JPEG, WebP or GIF bytes
+  into straight RGBA and a size, the shape `add_image` takes;
+  `decode_animation` keeps every frame of an animated GIF, APNG or WebP,
+  composited to the whole canvas, with its delay and the loop count, and
+  `Animation::at(elapsed)` says which frame shows and when the next is
+  due, so a GIF plays on the frame clock through `update_image_with` and
+  `request_frame_at` with nothing owed between steps.
+  `Launcher::icon_bytes` takes an icon from a PNG
+  (`Launcher::try_icon_bytes` for bytes from outside the program). C: `kui_decode_image`,
+  `kui_decode_animation`, `kui_animation_at` and `kui_pixels_free`, with
+  `runner`; Odin: `decode_image`, `decode_animation`, `animation_at`,
+  copied into the context allocator; Node: `decodeImage`,
+  `decodeAnimation` and `animationAt` on the package. The runner's
+  `image` gains its `gif` feature. The `decode` example plays a shipped
+  spinner.
+
+**What you can delete.**
+
+- A width and a height tweened against each other to fake a card's
+  tilt, and a `path` drawn in a box's place so that it could turn
+  (F131).
+- A float declared where a drifting thing ends, entering from where it
+  starts over a transition as long as its life, to move it along a path
+  (F132): its stops say the path.
+- A clock of the app's own and `request_frame` on every frame to time a
+  sequence that plays once — a burst, a pop, a row of stars — and the
+  frame owed for good by a cycle the app meant to stop (F133).
+- A clock of the app's own, beside the core's, that a test had to push
+  forward by hand (F134): read `now()`.
+- A thread per deadline that sleeps and then calls `Waker::wake` (F135):
+  `request_frame_at`, or `Waker::wake_at` from off the view.
+- A frame drawn with the exit aimed before the frame that removes the
+  card, and the model field and `request_frame` that schedule it
+  (F136): `exit_with` in the handler.
+- The `image` dependency an app added to decode its photos, its version
+  pin and the `[profile.dev.package."*"]` line that made it fast, and a
+  GIF crate beside it (F138): `decode_image` and `decode_animation`.
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-09, over
+F131–F138 from the berainder review, with alpha.46's pre-tag pass over
+it on the Mac: the mechanical round as CI runs it, the windowed round,
+the accessibility audit and the bench guard, then three read-only
+reviewers of the diff since alpha.45 — the core and the renderer, the
+bindings, the docs — each claim probed. What they found was corrected
+before the tag (the backlog's alpha.46 pre-tag section lists it), and
+one entry, RG155 — the caret inside a turned node — is open.
+
+**macOS**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu`: **1997 tests over 149 suites**, 0 failed. The C round
+passes (5 checks), and so do the **58 scenes** through Rust, Lua, C and
+Node; Node's tests under `KUI_CONFORMANCE_REQUIRED=1`, **224 of 224**;
+`npm run gen` with no diff, the examples' typecheck, the headless round,
+the book, and `cargo audit` over the lockfile the decoder grew. The
+windowed round with Node's: **55 examples on both bases**, clean on a
+first run, twice. The accessibility audit: **106 of 106**. The bench
+guard against the alpha.45 tag: **green**, the eight guarded rows −0.9%
+to +0.9%; the unguarded exit rows read +2% to +4%, the 16 bytes an
+entrance and an exit grew by. The Odin steps did not run: this
+machine's Odin links an LLVM that is gone, so the hand-written Odin
+layer this round needed is checked by CI's `odin.nu` steps on the tag,
+and its layout was compared by script against the C side's asserts. No
+Windows or Linux machine ran this round.
+
+## 0.1.0-alpha.45 (2026-10-08)
+
+**What breaks.**
+
+- A menu row whose accelerator would leave its label under 48 px — a
+  window narrower than the accelerator with its gaps — draws the
+  accelerator cut short with "…" and the label's first glyphs, where it
+  drew the whole accelerator past the panel's edge and no label (under
+  Fixed, RG154).
+- A `menu_panel` floating in the viewport whose caller declared its
+  ceiling as a size expression (`max_width(Bound::Calc(..))`, `"50%"`)
+  bounds its labels by that ceiling read against the window, where it
+  bounded them by the window alone (under Fixed, RG154). A panel
+  anchored elsewhere keeps the window as its labels' bound.
+- A menu bar the app leaves out of a frame while a submenu switch waits
+  its 0.3 s starts the wait again when the bar is back, where the switch
+  went through at once on the next build (under Fixed, RG154).
+- Windows and Plasma: a `Blur` or `Tinted` window on a desktop with no
+  wallpaper kui can read is `Opaque` from its first frame again, as it
+  was in alpha.43; alpha.44's `Tinted`-then-`Opaque` is GNOME's alone
+  now (under Fixed, RG154).
+
+### Fixed
+
+- **The accelerator is bounded too** (backlog RG154, from the alpha.44
+  pre-tag pass). A row's label was what the panel's width bounded, and
+  its accelerator was drawn whole: in a window narrower than the
+  accelerator the label shrank to nothing and the accelerator ran past
+  the panel, which is what RG150 set out to stop. The label keeps a
+  floor of 48 px (`widgets::MENU_LABEL_MIN`) and the accelerator takes
+  what that leaves, ending in "…". And a ceiling declared as a size
+  expression on a panel floating in the viewport now caps the labels as
+  a px one does, read against the window; a panel anchored to a node
+  keeps the window's ceiling for its labels, since the room layout will
+  read the expression against is not placed when the rows are built.
+- **A menu bar the app stops drawing owes no frames** (backlog RG154).
+  A submenu switch waiting its 0.3 s was cleared by the next build of the
+  bar's menu; an app that stopped drawing the bar inside the wait (or
+  handed it to the platform) kept the switch, and the frames it owed,
+  for good. A frame that builds no menu on a surface drops the switch
+  waiting there.
+- **Windows and Plasma: no wallpaper, opaque from the first frame**
+  (backlog RG154). RG150 moved finding the wallpaper's path to the
+  loader's thread for GNOME's sake, where it is up to three `gsettings`
+  processes; on Windows it is one call and on Plasma one file read, so
+  the loop asks there and a window with none to draw never reads
+  `Tinted` first. GNOME keeps the thread. Windows run on screen;
+  Plasma compiled and read.
+
+**What you can delete.**
+
+- A shorter accelerator chosen for a menu that has to fit a narrow
+  window (RG154).
+- A frame an app requested itself after stopping its menu bar, to let
+  the core settle (RG154).
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-08, over
+RG154 — what alpha.44's pre-tag pass left — with alpha.45's pre-tag pass
+over it on the Windows machine and under WSLg: the mechanical round on
+both, then a read-only review of the diff since alpha.44, each claim
+probed. It filed nothing; its one finding, a `Calc` ceiling read against
+the window for a panel anchored elsewhere, was corrected inside RG154
+before the tag.
+
+**Windows**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu --node`: **2148 tests over 143 suites**, 0 failed. The
+C round passes (6 checks), and so do the **57 scenes** through Rust,
+Lua, C, Node and Odin; the Odin binding's four steps with CI's pinned
+`dev-2026-09`; Node's tests under `KUI_CONFORMANCE_REQUIRED=1` (**218 of
+219**, the one skip Windows'), `npm run gen` with no diff, the
+examples' typecheck and the headless round. The windowed round with
+Node's: **53 examples on both bases**, clean on a first run; `counter`
+and `host` opened by hand after `cbuild`, and the backdrop examples
+opened with and without `KUI_BACKDROP_EMULATE`. The bench guard against
+the alpha.44 tag, on a quiet machine: **green**, the eight guarded rows
+−0.7% to +2.1% (`frame_10k_rects_with_access_tree` the high one), the
+worst run-to-run spread 3.5%. A first run beside the WSL round read two
+rows unreadable at 13 and 21% spread, which is why it was run again.
+
+**Linux**, under WSLg (llvmpipe), the same commit: fmt and clippy
+clean; `cargo test --workspace`: **1926 tests over 142 suites**, 0
+failed; the C round (5 checks) and the 57 scenes through every adapter,
+Node **219 of 219** with the corpus required, gen clean, the typecheck,
+the headless round. The windowed round under X11 with Node's: **53
+examples on both bases**, clean on a first run, two at a time. The
+backdrop examples under X11 read no wallpaper (WSLg has none to name)
+and went `Opaque`, as they should; Plasma's on-the-loop read is
+compiled and read, not run. No Mac ran this round: the AX audit is CI's
+and the next Mac round's.
+
 ## 0.1.0-alpha.44 (2026-10-08)
 
 **What breaks.**

package/docs/adr/0041-a-mask-turns-about-its-centre.md

@@ -143,7 +143,9 @@ date: 2026-10-05
   framebuffer space, a scroller inside a turned box scrolls along a
   tilted axis, hit-testing inverts a matrix per ancestor, and the access
   tree's rects become bounding boxes. Not built here, and this does not
-  rule it out: a path's own `rotate` would compose under it.
+  rule it out: a path's own `rotate` would compose under it. *Built as
+  [ADR 0043](0043-a-node-turns-about-its-pivot.md) on 2026-10-08, with
+  the path's turn composing under the node's as said.*
 - **A stock arc fragment** (an SDF sector, angles in its params, as
   `polygon` is a stock fragment). A turn is then two floats a frame and
   no raster, exact at any angle. ADR 0040 declined a `sector` element

package/docs/adr/0043-a-node-turns-about-its-pivot.md

@@ -0,0 +1,370 @@
+---
+status: accepted
+date: 2026-10-08
+---
+
+# A node turns about its pivot: `rotate` and `scale` on any node, paint-only, carried by the clip entry
+
+> **Accepted and built 2026-10-08**, the day it was proposed; the
+> *Amendment* at the end records what the building changed. Asked by
+> berainder (backlog F131): a card that tilts a few degrees towards the
+> side it is being dragged to is the swipe's whole look, and the app
+> tweened `width` and `height` instead and called it depth. [ADR
+> 0041](0041-a-mask-turns-about-its-centre.md) gave `rotate` to a
+> `path` alone and listed "a transform on any node" under *Considered
+> options* as "the general thing, and a different document" — every
+> quad kind turns, glyphs leave the pixel grid, the clip stops being a
+> rect in framebuffer space, a scroller inside a turned box scrolls
+> along a tilted axis, hit-testing inverts a matrix per ancestor, the
+> access tree's rects become bounding boxes. This is that document. It
+> takes each of those costs, decides which to pay and which to decline,
+> and lands on a turn and a uniform scale about a pivot, **paint-only**:
+> layout is what it was, and everything after layout — the quads, the
+> clip, the hits, the access rect — is drawn, cut, hit and read through
+> the transform. [ADR 0005](0005-the-paint-vocabulary.md)'s paint
+> vocabulary gains two slots and no quad kind; ADR 0041's path turn
+> composes under this one and is otherwise untouched.
+
+## Context
+
+- **What a turning box costs today: everything.** No node has a
+  transform. `slide`, `enter` and `exit` move and fade; ADR 0025 gave
+  layout a scale factor (the DPI), not a rotation; backlog V7 declined
+  a layout `zoom` — a subtree laid out in its own logical space — until
+  a second app asks for it, and berainder did not: it asked for the
+  *look* of a tilt, with the card taking the room its upright self
+  takes. A view that wants one today fakes it (width and height eased
+  against each other), or draws the card as a `path` (which cannot
+  hold a photo or text), or goes to a framework with CSS transforms.
+- **The vertex stage already turns.** ADR 0041 put a path's turn in the
+  quad: the `blur` slot carries radians for kinds 1 and 3, and
+  `vs_main` turns the four corners about the quad's centre
+  (`shader.wgsl`). `local` and `uv` stay the quad's own, so the fragment
+  stage's SDF, border, radii and image sampling come out right on a
+  turned quad without knowing it turned. The one thing that does not
+  turn is the clip, tested against the framebuffer position.
+- **The clip is already a table.** Since ABI 11 a quad names a
+  [`Clip`] entry in `DisplayList::clips` rather than carrying its rect
+  (`display.rs`): one entry per *distinct* clip a frame reaches, a
+  handful, interned by run length as emission walks paint order. Every
+  quad under one card names the same entry. An entry is the space a
+  quad is painted in; today that space is "framebuffer, cut to this
+  rounded rect".
+- **Hits are by shape.** ADR 0026 made a region's hit test the rect and
+  then a shape inside it — rounded corners, a stroke's pieces, a
+  polygon, a path's outline — in the region's own coordinates
+  (`input.rs`, `contains`). A region's test is local already; what it
+  lacks is the step from the pointer to local.
+- **The slots are a list.** `anim::Slot` names nine things a transition
+  tweens; an entrance and a keyframe stop name five of them through
+  `Slots` (`slots.rs`), parsed in one place for every binding. A tenth
+  slot is a row in that enum, a lane in that struct and a branch in
+  `ease_transitioning`.
+- **What a turn is for, in the apps this repo has seen.** A card that
+  tilts with a drag and springs back; a pulse (`scale` 1 → 1.05 → 1 on
+  a cycle); a wobble (`rotate` ±0.01 on a cycle); a spinner that is a
+  box and not an arc; a chip that enters at `scale: 0.8` and settles;
+  an icon that flips. Every one is a turn or a uniform scale about a
+  point in the box, and every one wants to **tween**. None is a skew,
+  a matrix or a 3D flip.
+
+## Decisions
+
+1. **`rotate`, `scale`, `pivotX`, `pivotY` on any node.** `rotate` in
+   turns, clockwise with y down, 0 for none — the unit a `path`'s
+   `rotate` and a gradient's `angle` already take. `scale` a uniform
+   factor, 1 for none. `pivotX`/`pivotY` fractions of the node's box,
+   `0.5, 0.5` — the centre — by default, the point the turn and the
+   scale are about. In Rust `NodeSpec::rotate(turns)`, `scale(f)`,
+   `pivot(fx, fy)`; JSX `rotate`, `scale`, `pivotX`, `pivotY`; Lua
+   their snake case; C `rotate`, `scale` (0 is 1), `pivot_set`,
+   `pivot_x`, `pivot_y` on `KuiSpec`; Odin the generated `Spec` fields.
+   Container rows — a box, an image, an edit, a `line`, a `polygon`;
+   on a `text` they are dropped with the `unknown-prop` warning every
+   container row on a text raises (put them on the box around it). On
+   a `path`, `rotate` and `pivot` keep ADR 0041's meaning — the path's
+   own turn about a point in `d`'s coordinates, which does not tween —
+   and `scale` is the node's; a path that wants a tweened turn is put
+   in a box. The two should become one; see *Open questions*.
+2. **Paint-only.** Layout does not see the transform: the node takes
+   the room its upright self takes, its siblings do not move, a scroller
+   around it scrolls the untransformed content size, `onLayout` reports
+   the layout rect, `rect_of` and `layout_of` answer it. A transform is
+   `opacity`'s kind of row — something applied after layout to
+   everything the subtree draws — and not `width`'s. V7's layout zoom
+   stays declined on its own terms; nothing here is it.
+3. **A node's whole subtree turns with it, about the node's pivot.**
+   Every quad the subtree emits — backgrounds, borders, shadows,
+   glyphs, images, fragments, segments, masks — is drawn through the
+   same similarity: `pixel = R(angle) · scale · p + t`, with `t` chosen
+   so the pivot stays put. Transforms **nest** by composition: a node
+   turned inside a turned node turns about its own pivot in its
+   parent's turned space. A float anchored to its parent turns with the
+   parent as its content does; a viewport float does not; a float
+   anchored to a node by key (the devtools' tabs) does not.
+4. **The clip entry carries the space.** [`Clip`] gains three fields:
+   `transform` — angle in radians, scale, `tx`, `ty`, the similarity
+   every quad naming the entry is drawn through — and `inner` with
+   `inner_radius`, a second clip in the quad's own space, before the
+   transform. The entry's `rect` and `radius` stay what they were: the
+   clip in framebuffer space. A clipping node *outside* any turn
+   narrows `rect`; one *inside* a turn narrows `inner`, since its box is
+   in the turned space. Between two nested turns a clip is approximated
+   by its bounding box in the inner space (its corners drop to square);
+   a tilted card inside a tilted card inside a scroller is the one
+   shape that pays, by a sliver at a corner. A frame with no transform
+   interns exactly the entries it interned before, with the identity
+   transform and no inner clip, so the run-length intern and every
+   backend that ignores the new fields are unchanged.
+5. **The shader turns the corners and tests two clips.** `vs_main`
+   applies the entry's transform after a path's own turn (decision 1 of
+   ADR 0041 composes under it, as that document said it would), and
+   passes the pre-transform position down as a varying. The fragment
+   stage tests the framebuffer clip against the framebuffer position,
+   as before, and the inner clip against the pre-transform position —
+   an affine function of position, so the interpolated varying is
+   exact, and no inverse is computed per pixel. A segment's capsule SDF
+   reads the pre-transform position too, so a turned stroke is a
+   stroke. The instance grows by three `vec4`s (48 bytes); the quad on
+   the wire does not change. A fragment pipeline's epilogue
+   (`fragment::EPILOGUE`) tests the inner clip the same way, so a
+   `fragment` inside a turned card is cut by the card.
+6. **Hit where drawn.** A region under a transform carries it and the
+   inner clip; `contains` unprojects the pointer into the node's space
+   and tests the rect, the shape and the inner clip there, and the
+   framebuffer clip with the pointer as it is. A tilted card is grabbed
+   on its tilted edge; its rounded corners still miss; a press in its
+   box off its outline falls through. Drag payloads stay in viewport
+   px — what a drag means to the app that moves the card is where the
+   pointer is on screen. A scroll region inside a turned node is hit
+   the same way, so the wheel over a tilted list scrolls it; what moves
+   is the content along the node's own axes, since the offset is
+   applied in layout and the turn after.
+7. **The access rect is the bounding box.** Assistive technology gets
+   an axis-aligned rect, so a turned node's is the bounding box of its
+   turned layout rect, cut to the framebuffer clip as every rect is.
+   Reading order and actions are untouched.
+8. **A turn and a scale are one slot, and it tweens.** `Slot::Transform`
+   carries `[rotate, scale, 0, 0]`: with a `transition` a card follows
+   the pointer while a drag holds the transition off and springs back
+   when it is on, as `slide` does for position. An entrance names
+   `rotate` and `scale` (`enter: { scale: 0.8 }` settles a chip in), an
+   exit names them (`exit: { rotate: 0.1, scale: 0 }` spins a card
+   away), a keyframe stop names them (`keyframes: [{ scale: 1.05, at:
+   0.5 }]` pulses; `[{ rotate: 0 }, { rotate: 1 }]` spins a box) —
+   through `Slots`, so every binding gets them from the one parser. A
+   lane a stop or an entrance leaves out is the node's own value,
+   which for `scale` is 1 and not 0: a stop that names only `rotate`
+   does not shrink the box.
+9. **A ghost keeps its turn.** A departing subtree is replayed with the
+   transform its nodes declared, the root's eased toward the exit's;
+   the turns of ancestors outside the picture — which may be gone — are
+   not replayed, as their clips are not.
+10. **What is declined.** A matrix, skew, 3D, a per-axis scale, a
+    transform origin outside the box (`pivot` past 0..1 is allowed and
+    means what it says; it is not clamped). CSS's `transform` is the
+    general thing; a turn and a uniform scale are what every app has
+    asked for, and each is one float that tweens. A `backdropBlur`
+    under a turn blurs its upright box (the blur reads the framebuffer
+    region); `pixelSnap` snaps the layout rect before the turn, so a
+    turned snapped box is a turned box. Both are said in `props.md`.
+
+## Considered options
+
+- **The transform on the quad.** Four floats on every quad of every
+  frame, for a feature almost no quad uses; and the inner clip has no
+  room there at all. The clip table exists for exactly this reason
+  (ABI 11), and a quad under a turned card already names the entry its
+  siblings do. Not taken.
+- **Rasterize the subtree offscreen and draw the texture turned.** One
+  quad, exact clipping, and the way a browser composites a transformed
+  layer. It costs a render target per turned subtree per frame, a copy
+  of every pixel under it, and text rendered to a texture and
+  resampled — blurry at any angle, which is the one thing a glyph
+  turned by its own quad is not. The backdrop pass (F129) does this
+  for a blur because a blur needs the pixels; a turn does not.
+- **A transform on the clip only, hits and access left upright.** Half
+  the build and a lie: a tilted card hit on its upright rect is grabbed
+  in the air beside its corner. ADR 0026's shapes make the honest
+  version cheap.
+- **Unify the path's `rotate` with this one now.** The path's turn
+  would become a node transform, its `pivot` a point in the box, the
+  square box ADR 0041 sweeps unnecessary, and its turn would tween for
+  free. It is the right end state and the wrong day: `path` is
+  released, its `pivot` is in `d`'s coordinates by a decision this
+  repo argued, and `path_coverage.rs` pins the sweep. Left open below.
+- **A per-axis scale (`scaleX`/`scaleY`).** A flip (`scaleX: -1`) is
+  the one use, and a flip of a box with text in it mirrors the text.
+  The slot's lanes have room for it if an app asks.
+
+## Consequences
+
+- **A tilt is one row and it tweens.** berainder's card is
+  `rotate(lean * 0.03)` with its transition held off while dragging,
+  and the spring back is the transition it already has.
+- **The instance grows.** Three `vec4`s per quad in `kui-wgpu`: half a
+  megabyte more upload on a 10,000-quad frame, a few microseconds.
+  Nothing on the core's side of the wire grows per quad; the clip
+  table's entries grow from 32 to 80 bytes, and a frame has a handful.
+- **The C ABI bumps to 27.** `KuiClip` grows (a `[lib]` struct a host
+  strides with its own `sizeof`), `KuiSpec`, `KuiEnter` and
+  `KuiKeyframe` gain fields, and the conformance digest hashes the
+  whole clip entry. The Node `clips()` buffer's stride grows with it;
+  `decodeClips` reads the new fields.
+- **Every binding gets the four rows and the two slot lanes** from the
+  schema and the one slot parser; the Odin layer regenerates its
+  `Spec`, `Enter`, `Keyframe` and `Clip`.
+- **Glyphs leave the pixel grid under a turn**, as a turned path's
+  mask does: a turned text is resampled at its angle and reads
+  softer. A text that must stay crisp is not turned. Under a scale, the
+  SDF ramps scale with the box, so a box scaled up has an edge
+  `scale` times as soft; a UI scale stays near 1.
+- **The devtools' facts show `rotate` and `scale`** beside `opacity`.
+
+## Open questions
+
+- **The path's own turn.** When a release can break `path`, its
+  `rotate` should be this one — tweened, composed, about a pivot in
+  the box — and `pivot` should take the box's fractions as every other
+  node's does; ADR 0041's square sweep goes with it. Condition: the
+  first app that wants a path's turn to tween.
+- **Text sharpness under a turn.** A glyph mask is bilinear-sampled at
+  its angle. If a turned paragraph is ever asked for — not a card with
+  a word on it — the answer is a supersampled mask or a rasterization
+  at the angle, both of which the atlas's turn-bin rejection in ADR
+  0041 already priced.
+
+## Measurements to take
+
+- `frame_10k_rects` and the guarded `frame` rows: the transform walk is
+  behind `Tree::any_transform`, so a frame with none should read as it
+  did (the guard allows the noise floor).
+- A frame of 1,000 turned boxes, each its own clip entry, against the
+  same frame upright: the cost of the per-node compose and the
+  bounding-box cull. Not yet taken (RG155).
+
+## Amendment: what the building changed (2026-10-08)
+
+- **`KuiSpec` is 744 bytes, not 728.** The five appended fields land
+  after the 8-byte-aligned tail, and the parity test said so.
+- **`pivot_set` is two bits.** A C host setting one axis — the parity
+  test's one-row-at-a-time check was the first — needs to say which, so
+  `KUI_PIVOT_X` and `KUI_PIVOT_Y` are bits as `KUI_VALUE_*` are, and the
+  Odin lowering ORs them in. `scale` stays "0 is 1".
+- **The slot bits are `KUI_KF_ROTATE` 64, `KUI_KF_SCALE` 128,
+  `KUI_ENTER_ROTATE` 64, `KUI_ENTER_SCALE` 128.**
+- **A glyph cull reads the clip in the quad's space.** The text, cell
+  and editor painters compared glyph positions against the entry's
+  framebuffer rect; under a turn that is the wrong space. They read
+  `Clip::visible` — the inner clip narrowed by the outer one pulled
+  back through the transform — which is the rect itself when nothing
+  turns.
+- **The pre-transform position is a varying, not an inverse.** `pre` at
+  location 10 of `VsOut`; the fragment epilogue takes it at the same
+  location, with `inner` and `inner_radii` at 11 and 12. A fragment
+  entry point lists a subset of the vertex outputs, so an app's
+  fragment compiled against the old prelude still links.
+- **A scrollbar's thumb under a turn is hit upright.** The bar is drawn
+  turned (its quads name the scroller's entry) but its track is tested
+  as an upright rect. A turned scroller is a demonstration shape, and
+  the wheel over it is right; the thumb waits for an app that drags one.
+- **A caret placed inside a turn reads the pointer upright.** A press
+  finds an editor in a tilted card, but where its caret lands, the drag
+  that extends it, a static text's selection drag and `text_hit` take
+  the pointer less the content origin without pulling it back through
+  the turn, so under a turn or a scale the caret lands on the wrong
+  character. Found by alpha.46's pre-tag pass; open as RG155, with the
+  inner clip's unsmoothed edge and the second measurement below.
+- **The Odin layer was regenerated by hand.** No Odin ran on the
+  building machine (its binary wants an LLVM the machine does not have),
+  so `kui_c.odin`, `layout.odin`, `generated.odin`, `types.odin` and the
+  generator's policy were written as the generator writes them, and
+  CI's `odin.nu gen --check` is what says whether they match.
+  It did not, at first: `KuiSpec` embeds `KuiEnter` twice (`enter`,
+  `exit`), whose eight new bytes moved every field after them by 16,
+  and the hand-written `layout.odin` moved only the tail. Found while
+  building F133 (2026-10-09) and rewritten from the C mirror's own
+  asserts (`target/kui-abi-assert.c`), all 77 offsets, with every field
+  of every mirrored struct checked to have one.
+- **Lua's `path` strips the row.** Lua reads every key of a table as a
+  schema row before an element reads its own, so `path { rotate = }`
+  turned the node as well as the mask and the `path` scene's digest
+  moved; the arm now drops the node transform the generic walk read.
+  Node's encoder had the same fault and the same fix (its `path` case
+  writes the rows without `rotate`): the full run that cleared this ADR
+  loaded a stale addon and passed, and the next one, building F133,
+  caught it. C and Odin take a path's turn as an argument.
+- **The conformance digest hashes twenty words a clip** in all five
+  adapters, and the `transform` scene is the first whose digest moves
+  if a turn, a scale or an inner clip does.
+- **Measured, and given back (2026-10-09).** The first build passed
+  the bench guard against `v0.1.0-alpha.44` with every frame that turns
+  nothing 4% to 9% slower. Investigated before merging, against the
+  build's own parent (`acbbbb4d`, RG154 — which reads as alpha.44 does,
+  so all of it was this ADR's), by alternating the two bench binaries
+  and profiling with `sample`. Six costs, each found by an experiment
+  before it was fixed:
+
+  1. **The paint path carried the whole clip.** `Paint` held the
+     80-byte `Clip` by value into `emit_node` and `paint_box`, which
+     rescaled all twenty floats for every node. It holds the clip's rect
+     and id now; a leaf that culls — a text, a grid, an editor — reads
+     the scaled entry from the display list, and the table rules look
+     the logical clip up by node.
+  2. **The walk carried it too.** `emit_frame` built an 80-byte value
+     per node and read its rect. It carries the rect, the cull rect and
+     the id; the clip stays in `self.clips`, which is pushed in tree
+     order instead of filled and overwritten, and children of one
+     clipper share one intersect and one intern through a two-index
+     cache (a list's rows were interning the same 80 bytes each).
+  3. **A tenth tween slot on every transitioning node.** 96 bytes a
+     node whether it turned or not. The turn's tween lives in
+     `AnimStore::turns`, for the nodes that turn.
+  4. **The test for a turn inside `ease_transitioning`.** It is eased
+     after the other slots, in `ease_transform`, out of line, behind a
+     two-box check in `ease_spec`; `ease_transitioning` is alpha.44's.
+  5. **An inlining cliff.** The drive body shared by the array slots and
+     the turn was force-inlined into both callers, so `Tween::eased_at`
+     and `spring_step` gained a second caller and stopped being inlined —
+     4% on the transitioning row by itself. The shared body is the
+     out-of-line function now, as `NodeAnim::drive` was, and the
+     helpers inline into it again.
+  6. **A test that stopped `prepare_spec` inlining.** The check for a
+     turn in `ease_spec` scanned the keyframe stops inline, which made
+     `prepare_spec` too big to inline into `open_content`, and every node
+     paid a call (+2% on 10,000 gradient cells). The scan is out of line.
+
+  Smaller: the hit region's turn is boxed (36 bytes inline was 1% on a
+  thousand buttons), the transform inside the interact group is boxed
+  (so a gradient or a hover allocates the group in the class it did),
+  the leaves that do not cull by the clip never copy it, and the
+  turned-space cull is asked only on a frame that turns. Medians against
+  RG154, on mains power:
+
+  | row | first build | now (median) | now (fastest) |
+  | --- | --- | --- | --- |
+  | `frame_10k_rects` | +5.9% | +0.5% | +0.5% |
+  | `frame_1k_typical` | +4.7% | −0.3% | −0.1% |
+  | `frame_10k_rects_with_text_and_hits` | +4.5% | −0.3% | −0.6% |
+  | `frame_10k_segments` | +5.2% | +0.2% | +0.6% |
+  | `frame_10k_rects_with_access_tree` | +4.1% | −0.1% | −0.5% |
+  | `list_10k_rows_virtual` | +8.1% | +0.4% | +2.1% |
+  | `frame_1k_curves` | +1.1% | +0.1% | +0.3% |
+  | `frame_10k_rects_all_transitioning` | +11.0% | −2.7% | −3.9% |
+  | `deep_nesting_64_levels` | +5.7% | +3.0% | +0.5% |
+  | `frame_10k_rects_with_gradient` | +6.2% | +1.2% | +1.6% |
+  | `frame_10k_rects_all_declaring_exit` | +13.6% | +4.6% | +0.6% |
+  | `frame_10k_rects_rounded_clip` | +17.4% | −6.1% | −6.0% |
+
+  `deep_nesting_64_levels` never clips or turns, and what moved in it is
+  layout, whose code is unchanged and the same size: placement, not
+  cost. The exit row's medians span 15% on this machine, and its fastest
+  samples are level; what it keeps is its entrance and exit, 16 bytes
+  bigger each for `rotate` and `scale`, which every node declaring one
+  allocates. The rounded clip is faster than before ADR 0043 because a
+  clipper's children now share one intersect. Two
+  traps for the next one: the Mac on battery, and another session's
+  builds, made the transitioning row unreadable (medians spanning 2×)
+  until the race waited out `rustc` and read the fastest sample beside
+  the median; and the guard's base was alpha.44, which hid that RG154
+  sat between it and this build.