@qxuken/kui 0.1.0-alpha.45 → 0.1.0-alpha.47

package/howto.md

@@ -37,6 +37,101 @@ because the removal is judged whole rather than half-animated, and the
 [ADR 0012](docs/adr/0012-the-exit-budget.md) ·
 [alpha.8](CHANGELOG.md#010-alpha8-2026-09-07)
 
+### How do I throw a card left or right from a button?
+
+Aim the exit in the handler that removes the card:
+`ui.exit_with(key, Enter::from(400.0, 0.0).opacity(0.0))` in Rust
+(`env.exit_with` in Lua, `kui_exit_with` in C, `ctx.exitWith(key, { dx:
+400, opacity: 0 })` in Node), then stop declaring the card. The exit a
+node leaves by is otherwise the one its last frame declared, so a Like
+button pressed with the card at rest would send it the default way; the
+named exit wins for the frame the card goes in, and lapses when that
+frame finishes if the card stayed. It aims a node that declares an
+`exit` and a `transition`, and plays with that transition — so give the
+card a default `exit`, and a drag that already aims it by the lean on
+every frame needs nothing more.
+
+[`exit` row](props.md#container-props) ·
+[`Ui::exit_with` door](props.md#doors)
+
+### How do I tilt a card as it is dragged?
+
+`rotate` on the card, in turns clockwise (`0.03` is a tilt, `0.25` a
+quarter turn), read from the drag's `dx` in `on_event`; `scale` and
+`pivotX` / `pivotY` (fractions of the box, the centre by default) sit
+beside it. The turn is paint-only — the card keeps the room its upright
+self takes — and everything under it turns with it: the photo it clips
+inside its rounded corners, a badge floating on its corner, its text,
+and its hit region, so it is grabbed on its tilted edge. Leave the
+`transition` off while the pointer holds the card, so the tilt follows
+at once, and put it back on release: the turn is a slot like `bg` or
+`width`, so the spring brings it home. `enter: { scale: 0.8 }` settles
+a chip in, `exit: { rotate: 0.1, scale: 0 }` spins one away, and a
+spinner is a box with `keyframes: [{ rotate: 0 }, { rotate: 1 }]`. A
+`path`'s own `rotate` is ADR 0041's and does not tween; put the path in
+a box for one that does.
+
+[`rotate` row](props.md#container-props) ·
+[ADR 0043](docs/adr/0043-a-node-turns-about-its-pivot.md) ·
+[`transform` example](../examples/rust/features/transform.rs)
+
+### How do I make a node bob, drift or shake by itself?
+
+Give it `keyframes` whose stops name `dx` / `dy`: logical px from where
+layout put it, sampled off the cycle like any other slot, so the view
+declares the stops once and never redraws for them. `[{ dy: 0 }, { dy:
+-6 }]` with `repeat: 'alternate'` bobs it; stops that rise and fade drift
+a sparkle up; a few small alternating `dx` stops on a short cycle shake
+it. The node and everything under it are drawn and hit where the stop
+puts them, and the offset adds to a `slide`, but the room it takes is its
+place's: siblings do not move, and `onLayout` reports the layout rect
+rather than a cycle that would post an event every frame. A cycle runs
+for as long as the node is declared and asks for a frame every vsync,
+unless `iterations` says how many times.
+
+[`keyframes` row](props.md#container-props) ·
+[`transition` example](../examples/rust/features/transition.rs)
+
+### How do I play a keyframe animation once?
+
+`iterations: 1` on the node with the `keyframes` (CSS's
+`animation-iteration-count`). The cycle plays from the first frame the
+node is declared with it, rests where it ended — the last stop, or the
+first for `reverse`, or the start again for `2` alternating — and then
+asks for nothing, so `animating()` goes quiet and a test's `advance` runs
+it out. Before its `delay` it holds its first stop, so a row of stars
+given `delay: i * 150` and `iterations: 1` pops in one after another
+without showing their own values first. To play it again, drop the
+stops for a frame and declare them again, or give the node a new key: a
+finite cycle restarts whenever a frame went without it. A blinking caret
+is still not keyframes (see the caret how-to): it is a cycle with no end.
+
+[`iterations` row](props.md#container-props) ·
+[`keyframes` row](props.md#container-props) ·
+[`transition` example](../examples/rust/features/transition.rs)
+
+### How do I show a photo or a GIF my app ships?
+
+Decode it with the runner, which links the decoder it draws its
+wallpaper with: `kui_native::decode_image(bytes)` turns PNG, JPEG, WebP
+or GIF bytes into straight RGBA and a size, which `add_image` takes as it
+is (`decodeImage` in Node, `kui_decode_image` in C, freed with
+`kui_pixels_free`). No `image` dependency of the app's own. For an
+animated GIF, APNG or WebP, `decode_animation` keeps every frame — the
+whole canvas each, as a browser composites it — with the seconds each
+shows. Play it on the frame clock: keep when it started, ask
+`anim.at(ui.now() - started)` which frame shows and when the next
+is due, `update_image_with` the pixels when the index moved, and
+`request_frame_at(started + next)`. Nothing is owed between steps, so a
+spinner at 80 ms a step costs twelve frames a second and an idle window
+otherwise, and a paused one asks for nothing. A GIF frame that says 10 ms
+or less shows for 100, the way browsers show it; a finite loop count
+rests on the last frame. Lua is a guest and gets the handle from its
+host.
+
+[`decode` example](../examples/rust/features/decode.rs) ·
+[`image` element](props.md#elements)
+
 ### How do I draw a connector between two boxes?
 
 `<line from={[x, y]} to={[x, y]} width color/>` is one round-capped stroke,
@@ -1207,7 +1302,8 @@ blinks in the background. Headless the phase stays true;
 `setCaretVisible(false)` / `kui_set_caret_visible` is how a test sees
 the off phase drawn, and how a C host with its own window drives it
 (`kui_has_caret`, `kui_caret_stamp` are the clock's inputs). Never use
-`keyframes` for this: they ask for a frame every vsync and never stop.
+`keyframes` for this: a blink has no end, and an endless cycle asks for a
+frame every vsync.
 
 A caret that does not blink — the block of a modal editor's normal mode —
 declares `caretSolid` (Lua `caret_solid = true`, C `KUI_VALUE_CARET_SOLID`
@@ -1700,7 +1796,48 @@ re-renders. `ctx.setTime` under a loop throws and names `advance` — the loop
 owns the clock — and `startTime` in the options pins where that clock starts
 so assertions on `tick.msg(now)` are exact.
 
-[alpha.8 `**What breaks.**`](CHANGELOG.md#010-alpha8-2026-09-07)
+Keep the app's own deadlines on that clock too. `now()` — `ui.now()` in
+Rust, `env.now` in Lua, `kui_now` in C, `ctx.now()` in Node — is the
+frame clock in seconds, the one `transition` and `keyframes` read (0
+before a driver sets it), so a toast due at `shownAt + 3` and the fade
+that takes it away agree, and `advance` or `Drive::advance` moves both.
+A view that reads `Instant::now()` or `Date.now()` keeps
+a second clock no test can move.
+
+[alpha.8 `**What breaks.**`](CHANGELOG.md#010-alpha8-2026-09-07) ·
+[`now` in the env](props.md#env)
+
+### How do I hide a toast after three seconds without a timer thread?
+
+Keep the time it is due on the frame clock, and ask for a frame then:
+`ui.request_frame_at(shown_at + 3.0)` in Rust (`env.request_frame_at` in
+Lua, `kui_request_frame_at` in C, `ctx.requestFrameAt` in Node), read
+`now()` in the view, and stop drawing the toast once it is past. The
+runner sleeps to that time and runs the view, and nothing is owed in
+between, so `animating()` stays false and an idle app stays idle. The
+earliest time asked for wins and is kept until a frame reaches it, so a
+view may ask every frame or once. From a thread that is not the view's —
+a download finishing on its own schedule — `Waker::wake_at(instant)`
+says the same thing to every window. A test moves the clock past the
+time and draws; a host driving its own window reads
+`kui_next_frame_at` and sleeps to it.
+
+[`now` in the env](props.md#env)
+
+### How do I press "the button named Like" in a test?
+
+Look it up by the name a reader hears: `Drive::key_named("Like")` in
+Rust (`Core::key_named` under it, `ctx.keyNamed` in Node, `kui_key_named`
+in C), then `click_key` it. The name is the node's `label` row, else the
+text inside a control, so a test that finds a button this way also checks
+that a screen reader can. `key_of` asks a different question: the *key
+label*, the name the view opened the node under (`with_keyed("like",
+..)`, a `key` prop), which a reader never hears and `texts_under` reads
+too. Two nodes with one name resolve to the first in tree order and raise
+`ambiguous-name` — the same two a reader cannot tell apart.
+
+[`label` row](props.md#container-props) ·
+[`ambiguous-name`](props.md#warnings)
 
 ### How do I test the real window, not a headless core?
 
@@ -1938,7 +2075,8 @@ it again after an upgrade; it is generated, never edited.
 Tell the launcher, once, and every window it creates carries it:
 `kui_native::app("t").icon(rgba, w, h)` with straight RGBA pixels, row by row
 — something a taskbar shrinks cleanly, 64 to 256 px, rendered from your
-drawing at build time or decoded from a PNG you ship — and, for a
+drawing at build time — or `.icon_bytes(include_bytes!("icon.png"))` for
+a PNG you ship, decoded by the runner — and, for a
 Windows program, `.icon_resource(1)` too. A Windows program's icon is a
 resource linked into its executable (a `1 ICON "app.ico"` line in its
 `.rc`, compiled by `embed-resource` or the like in `build.rs`), which is

package/index.d.ts

@@ -1,6 +1,7 @@
 import type {
   AppMsg,
   BoxProps,
+  EnterProp,
   GeneratedSpecProps,
   KuiNode,
   MenuItemInput,
@@ -805,6 +806,12 @@ export type WarningCode =
    *  declares, or pass the hex key an event carried. Two nodes with the *same*
    *  key are `duplicate-key`. */
   | 'ambiguous-key'
+  /** A lookup by accessible name (`Core::key_named`, `ctx.keyNamed`,
+   *  `kui_key_named`) found more than one node with that name in the last frame
+   *  — two buttons both read as "Delete" — and used the first in tree order. A
+   *  reader hears the same name twice too: give each a `label` that says which,
+   *  or look the one meant up by its key label. */
+  | 'ambiguous-name'
   /** A `focusRegion(name)` (`Core::focus_region`, `env.focus_region`,
    *  `kui_focus_region`) named a node the frame after it did not declare as a
    *  `focusRegion` — no node under the label, or a node without the row — so
@@ -1381,6 +1388,10 @@ export interface NodeInfo {
   opacity: number;
   /** Its `backdropBlur` radius in px, 0 for none (backlog F129). */
   backdropBlur: number;
+  /** Its turn in turns and its scale as drawn this frame, eased (ADR
+   *  0043): 0 and 1 for a node that declares none. */
+  rotate: number;
+  scale: number;
   /** A scroller's offset; `null` for a node that does not scroll. */
   scroll: { x: number; y: number } | null;
   /** Every handler it declared with the payload it would post: `click`,
@@ -3047,6 +3058,37 @@ export declare class Ctx {
    * while the window has no keyboard. Always `true` headless.
    */
   caretVisible(): boolean
+  /**
+   * The frame clock in seconds (backlog F134): the one the
+   * tweens and cycles read, `setTime` or the loop's own, 0
+   * before either. Read a deadline off it rather than off
+   * `Date.now()`, so `advance` moves both.
+   */
+  now(): number
+  /**
+   * Asks for a frame at `at` on the frame clock (backlog F135),
+   * in seconds: a toast's expiry, a sequence's next beat. Nothing
+   * is owed until then, so `animating()` stays false; a window
+   * sleeps to it and draws, and the earliest time asked for wins.
+   * A headless loop's `advance` past it draws the frame it ends
+   * on, as it does for a `tick`.
+   */
+  requestFrameAt(at: number): void
+  /**
+   * The exit the node `key` leaves by if it leaves in the frame
+   * that finishes next (backlog F136), over the `exit` it
+   * declared: `{dx: 400, opacity: 0}`, the same fields as
+   * `exit`. A card a button throws aside is removed in the same
+   * handler, with no frame drawn first to aim it. It aims a node
+   * that declares an `exit`, with that node's transition, and is
+   * forgotten when that frame finishes.
+   */
+  exitWith(key: string, exit: EnterProp): void
+  /**
+   * The frame-clock time the next asked-for frame is due at, in
+   * seconds; `null` when none was asked for.
+   */
+  nextFrameAt(): number | null
   /**
    * Whether there is a caret to blink: a focused `<edit>`'s, or
    * the `caret` a `line` under the focused sink declares — unless
@@ -3078,8 +3120,9 @@ export declare class Ctx {
    */
   focus(key: string): void
   /**
-   * The hex key of the node a label names — the label a `key`
-   * prop declared, resolved through the frame being built so
+   * The hex key of the node a key label names — the label a `key`
+   * prop declared, not the accessible name a reader hears
+   * (`keyNamed`), resolved through the frame being built so
    * far and then the last finished one — or null when no node
    * declared it. The door for holding a key across frames;
    * every call that takes a key takes the label too, so this
@@ -3090,6 +3133,16 @@ export declare class Ctx {
    * plugin filling a slot is answered from its own nodes only.
    */
   keyOf(label: string): string | null
+  /**
+   * The hex key of the first node in the last finished frame
+   * whose accessible name is `name` (backlog F137) — its
+   * `label` prop, else its own text, else a control's derived
+   * name — so a test clicks "the button named Like" as a reader
+   * would: `ctx.click(ctx.keyNamed('Like'))`. Not `keyOf`'s key
+   * label, which a reader never hears. Null when no node has the
+   * name; two raise `ambiguous-name`.
+   */
+  keyNamed(name: string): string | null
   blur(): void
   /**
    * What Tab does, as a call — for an `onKey` sink that binds Tab
@@ -3509,6 +3562,66 @@ export declare class Ctx {
   setEditText(key: string, text: string): void
 }
 
+/**
+ * Decoded pixels (`decodeImage`): `width` by `height`, four bytes each
+ * (RGBA), row by row from the top left, alpha not premultiplied — what
+ * `addImage`, `updateImage` and a window's `icon` take.
+ */
+export interface DecodedImage {
+  width: number
+  height: number
+  rgba: Buffer
+}
+
+/**
+ * Every frame of an animated image (`decodeAnimation`), each the whole
+ * canvas, with the seconds each shows and how many times the sequence
+ * plays (absent: for ever).
+ */
+export interface DecodedAnimation {
+  width: number
+  height: number
+  frames: Array<Buffer>
+  delays: Array<number>
+  loops?: number
+}
+
+/**
+ * Which frame shows at a moment (`animationAt`), and the seconds after
+ * the start the next is due — `Infinity` once a finite animation has
+ * played out.
+ */
+export interface AnimationShowing {
+  index: number
+  next: number
+}
+
+/**
+ * Decodes PNG, JPEG, WebP or GIF bytes (an animated file's first frame)
+ * with the runner's decoder (backlog F138), so an app that ships a photo
+ * needs no image package: `ctx.addImage(d.width, d.height, d.rgba)`.
+ * Throws, naming why, for bytes that are not an image or do not decode.
+ */
+export declare function decodeImage(bytes: Buffer): DecodedImage
+
+/**
+ * Decodes every frame of an animated GIF, PNG (APNG) or WebP, each the
+ * whole canvas, and the seconds each shows; a GIF frame asking for 10 ms
+ * or less shows for 100, as browsers show it. A still image is one frame
+ * shown for ever. Play it on the frame clock with `animationAt`,
+ * `updateImage` and `requestFrameAt`.
+ */
+export declare function decodeAnimation(bytes: Buffer): DecodedAnimation
+
+/**
+ * Which of the frames with these `delays` shows `elapsed` seconds after
+ * the animation started, playing `loops` times (null or 0 for ever), and when
+ * the next is due: `animationAt(gif.delays, gif.loops, ctx.now() -
+ * started)`, then `updateImage` when the index moved and
+ * `requestFrameAt(started + next)`.
+ */
+export declare function animationAt(delays: Array<number>, loops: number | undefined | null, elapsed: number): AnimationShowing
+
 /** Byte stride of one quad in the `quads()` buffer. */
 export declare function quadStride(): number
 
@@ -4244,6 +4357,37 @@ export declare class KuiWindow {
    * while the window has no keyboard. Always `true` headless.
    */
   caretVisible(): boolean
+  /**
+   * The frame clock in seconds (backlog F134): the one the
+   * tweens and cycles read, `setTime` or the loop's own, 0
+   * before either. Read a deadline off it rather than off
+   * `Date.now()`, so `advance` moves both.
+   */
+  now(): number
+  /**
+   * Asks for a frame at `at` on the frame clock (backlog F135),
+   * in seconds: a toast's expiry, a sequence's next beat. Nothing
+   * is owed until then, so `animating()` stays false; a window
+   * sleeps to it and draws, and the earliest time asked for wins.
+   * A headless loop's `advance` past it draws the frame it ends
+   * on, as it does for a `tick`.
+   */
+  requestFrameAt(at: number): void
+  /**
+   * The exit the node `key` leaves by if it leaves in the frame
+   * that finishes next (backlog F136), over the `exit` it
+   * declared: `{dx: 400, opacity: 0}`, the same fields as
+   * `exit`. A card a button throws aside is removed in the same
+   * handler, with no frame drawn first to aim it. It aims a node
+   * that declares an `exit`, with that node's transition, and is
+   * forgotten when that frame finishes.
+   */
+  exitWith(key: string, exit: EnterProp): void
+  /**
+   * The frame-clock time the next asked-for frame is due at, in
+   * seconds; `null` when none was asked for.
+   */
+  nextFrameAt(): number | null
   /**
    * Whether there is a caret to blink: a focused `<edit>`'s, or
    * the `caret` a `line` under the focused sink declares — unless
@@ -4275,8 +4419,9 @@ export declare class KuiWindow {
    */
   focus(key: string): void
   /**
-   * The hex key of the node a label names — the label a `key`
-   * prop declared, resolved through the frame being built so
+   * The hex key of the node a key label names — the label a `key`
+   * prop declared, not the accessible name a reader hears
+   * (`keyNamed`), resolved through the frame being built so
    * far and then the last finished one — or null when no node
    * declared it. The door for holding a key across frames;
    * every call that takes a key takes the label too, so this
@@ -4287,6 +4432,16 @@ export declare class KuiWindow {
    * plugin filling a slot is answered from its own nodes only.
    */
   keyOf(label: string): string | null
+  /**
+   * The hex key of the first node in the last finished frame
+   * whose accessible name is `name` (backlog F137) — its
+   * `label` prop, else its own text, else a control's derived
+   * name — so a test clicks "the button named Like" as a reader
+   * would: `ctx.click(ctx.keyNamed('Like'))`. Not `keyOf`'s key
+   * label, which a reader never hears. Null when no node has the
+   * name; two raise `ambiguous-name`.
+   */
+  keyNamed(name: string): string | null
   blur(): void
   /**
    * What Tab does, as a call — for an `onKey` sink that binds Tab

package/index.js

@@ -3,7 +3,10 @@
 import native from './native.cjs';
 import { createEncoder } from './encoder.js';
 
-export const { Ctx, KuiWindow, RowHeights, quadStride, clipStride, protocol } = native;
+export const {
+  Ctx, KuiWindow, RowHeights, quadStride, clipStride, protocol,
+  decodeImage, decodeAnimation, animationAt,
+} = native;
 export { createEncoder };
 
 // The brand on what `update` (or a function `init`) returns to hand the loop
@@ -1412,6 +1415,14 @@ export function decodeClips(buffer) {
       // Corner radii clockwise from the top-left: a clipping node with a
       // radius rounds what it clips. All zero = a plain rect clip.
       radii: [f[4], f[5], f[6], f[7]],
+      // The turn every quad naming this entry is drawn through (ADR
+      // 0043): angle in radians, scale, tx, ty — `[0, 1, 0, 0]`, the
+      // identity, on a frame that turns nothing.
+      transform: [f[8], f[9], f[10], f[11]],
+      // A second clip in the quad's own space, before the turn, and its
+      // radii: from clipping nodes inside a turned subtree.
+      inner: [f[12], f[13], f[14], f[15]],
+      innerRadii: [f[16], f[17], f[18], f[19]],
     });
   }
   return clips;

package/jsx-runtime.d.ts

@@ -119,12 +119,20 @@ export type AlignProp = 'start' | 'center' | 'end';
  *  animate their amount only, in the form the prop itself declares. */
 export interface KeyframeProp {
   at?: number;
+  /** Logical px across from where layout put the node, at this stop (backlog F132): the node and its subtree are drawn and hit there. Left out, 0. */
+  dx?: number;
+  /** Logical px down from where layout put the node, at this stop: `[{ dy: 0 }, { dy: -6 }]` with `repeat: 'alternate'` bobs it. Left out, 0. */
+  dy?: number;
   width?: SizingProp;
   height?: SizingProp;
   bg?: ColorProp;
   radius?: number;
   /** Group opacity, 0..1. */
   opacity?: number;
+  /** A turn in turns clockwise (ADR 0043). */
+  rotate?: number;
+  /** A uniform scale about the node's pivot. */
+  scale?: number;
 }
 
 /** Where a node starts the first frame it is seen, for `enter`: the slots
@@ -141,6 +149,10 @@ export interface EnterProp {
   radius?: number;
   /** Group opacity, 0..1: `{ opacity: 0 }` fades the whole subtree in. */
   opacity?: number;
+  /** A turn in turns clockwise (ADR 0043): `{ rotate: -0.02 }` swings in. */
+  rotate?: number;
+  /** A uniform scale about the node's pivot: `{ scale: 0.8 }` settles in. */
+  scale?: number;
 }
 
 /** A gradient painted over a box's `bg`, under its border and children
@@ -296,9 +308,9 @@ export interface GeneratedSpecProps {
   dropBg?: ColorProp;
   /** Easing for `transition` (default easeOut). The springs — `smooth` (no overshoot), `snappy`, `spring` and `bouncy` (the most), each a `bounce` of its own — integrate with momentum, so a value retargeted mid-flight keeps moving the way it was; `transition` is then about how long one takes to get there. */
   easing?: 'easeOut' | 'linear' | 'easeIn' | 'easeInOut' | 'spring' | 'bouncy' | 'smooth' | 'snappy';
-  /** Where the node starts the first frame it is seen `{ dx?, dy?, width?, height?, bg?, radius?, opacity? }`: those slots ease in from there over `transition` ms instead of snapping (`dx`/`dy` slide it in from that far away, `opacity: 0` fades the whole subtree in). */
+  /** Where the node starts the first frame it is seen `{ dx?, dy?, width?, height?, bg?, radius?, opacity?, rotate?, scale? }`: those slots ease in from there over `transition` ms instead of snapping (`dx`/`dy` slide it in from that far away, `opacity: 0` fades the whole subtree in, `scale: 0.8` settles it in). */
   enter?: EnterProp;
-  /** Where the node ends the frame after the view stops declaring it `{ dx?, dy?, width?, height?, bg?, radius?, opacity? }` — an `enter` read the other way. It plays when the node itself is removed, its parent still declared; a node that goes because an ancestor went — a tab switched away, a panel closed around it — goes at once with it, unless that ancestor has an `exit` of its own, whose picture carries it (backlog DX19; React's `AnimatePresence` rule). With a `transition`, the departing subtree is copied out of the last frame that had it and replayed frozen, in its place (the pass it painted in, just under the node that painted after it — a panel under a HUD leaves under it) and inert (no clicks, no Tab stop, no access row) while those slots ease from where they were, then dropped; without one it vanishes at once as it always did. `width`/`height` resize the departing node's own box only — the subtree inside it is a picture and is not laid out again. Needs a stable key across frames. */
+  /** Where the node ends the frame after the view stops declaring it `{ dx?, dy?, width?, height?, bg?, radius?, opacity?, rotate?, scale? }` — an `enter` read the other way. It plays when the node itself is removed, its parent still declared; a node that goes because an ancestor went — a tab switched away, a panel closed around it — goes at once with it, unless that ancestor has an `exit` of its own, whose picture carries it (backlog DX19; React's `AnimatePresence` rule). With a `transition`, the departing subtree is copied out of the last frame that had it and replayed frozen, in its place (the pass it painted in, just under the node that painted after it — a panel under a HUD leaves under it) and inert (no clicks, no Tab stop, no access row) while those slots ease from where they were, then dropped; without one it vanishes at once as it always did. `width`/`height` resize the departing node's own box only — the subtree inside it is a picture and is not laid out again. The exit read is the one the last frame that had the node declared, unless `exit_with` named another for the frame it went in: a card a button throws left or right is aimed by the handler that removes it, with no frame drawn first to point it. Needs a stable key across frames. */
   exit?: EnterProp;
   /** A disclosure's state: what a node that shows and hides something (a twisty, an accordion header, a menu button) reads as. Unset, the node does not expand at all — which is why this names its state instead of being a flag. */
   expanded?: 'collapsed' | 'expanded';
@@ -324,13 +336,15 @@ export interface GeneratedSpecProps {
   hoverable?: boolean;
   /** Where focus lands when the enclosing `modal` scope is entered: the first node in the modal's Tab ring declaring it, so a destructive confirm opens on its Cancel rather than on whichever control is declared first. Read on entry only — a Tab press afterwards stands, and the scope re-entered (a nested confirm closing) leaves focus where it was. Declared on nothing, or only on nodes the ring skips (disabled, `role="none"`, not focusable), entry stays the ring's first node. */
   initialFocus?: boolean;
+  /** How many times the `keyframes` cycle runs (CSS `animation-iteration-count`, backlog F133); left out, for ever. A finite cycle plays from the first frame the node is declared with it — a node that leaves and comes back plays again — holds its first stop through its `delay`, and rests where its last iteration ended (CSS's fill `both`): `1` plays a burst or a shake once, `2` with `repeat: "alternate"` goes out and back and ends where it began, `0.5` stops halfway. Once it is over the node owes no frame, so `animating()` and `owed()` go quiet as a settled transition's do; `delay` plus `iterations: 1` staggers one-shots. A count that is not a positive number is for ever. C: 0 is for ever. */
+  iterations?: LengthProp;
   /** A press on this node, or anywhere inside it, leaves keyboard focus where it was: a toolbar button, a tab or a divider that acts without taking the keyboard from the editor or key sink that had it. Without it a press on an `onClick` node focuses the node, and the app's keys stop reaching the sink until it takes focus back. The press also leaves a text or cell selection and the Tab ring where they were, so a Copy button copies what was selected. An `<edit>` inside still takes its caret and focus, as the keyboard's own owner. The click, drag and hover are unchanged, and Tab and assistive technology still reach the node. */
   keepFocus?: boolean;
   /** With `onKey`: releases arrive too, as the same payload with phase:"up" (`text` null, `repeat` false) — for a held-key interaction (WASD, press-and-hold, a key that arms a mode while it is down). A key only comes up where it went down: a release whose press the sink never got is dropped, and focus leaving while a key is held delivers the `up` first, so nothing is left stuck down. Without it a sink hears presses only, which is what a keymap wants — one that heard both halves would run every binding twice. */
   keyUp?: boolean;
-  /** CSS-style stops `[{ at?, width?, height?, bg?, radius?, opacity? }, …]`: the slots they name cycle through them over `transition` ms, forever, without the view redrawing; `at` is 0..1 and spreads evenly when omitted. */
+  /** CSS-style stops `[{ at?, dx?, dy?, width?, height?, bg?, radius?, opacity?, rotate?, scale? }, …]`: the slots they name cycle through them over `transition` ms, for ever unless `iterations` says how many times, without the view redrawing; `at` is 0..1 and spreads evenly when omitted. `dx` / `dy` are logical px from where layout put the node (backlog F132), as an entrance's are: the node and its subtree are drawn and hit that far away at the stop, a lane a stop leaves out is 0, and the offset adds to a `slide`'s, so `[{ dy: 0 }, { dy: -6 }]` with `repeat: 'alternate'` bobs a box and a sparkle drifts up its stops. Paint, hit and access only: layout and the room the node takes are its own place's, and an `onLayout` node reports its layout rect, not the cycle, which would post an event every frame it runs. */
   keyframes?: KeyframeProp[];
-  /** The accessible name. Without one a button, link, tab or heading is named by the text inside it; an image, an icon-only button and a `modal` dialog have none, and the core warns (`image-without-label`, `control-without-name`, `modal-without-name`). */
+  /** The accessible name. Without one a button, link, tab or heading is named by the text inside it; an image, an icon-only button and a `modal` dialog have none, and the core warns (`image-without-label`, `control-without-name`, `modal-without-name`). Not the key label a `key` prop or `with_keyed` declares, which `key_of` looks up and a reader never hears; `key_named` looks a node up by this name. */
   label?: string;
   /** Marks this node a live region: when the text inside it changes, a screen reader reads the change without being asked — `polite` at the next pause, `assertive` interrupting. Put it on the smallest node that holds the message, since everything inside a live node is live. For a one-off with no node behind it ("Saved") the binding's `announce` verb is the other half. */
   live?: 'off' | 'polite' | 'assertive';
@@ -378,6 +392,10 @@ export interface GeneratedSpecProps {
   opacity?: LengthProp;
   /** What a scroll gesture that starts over this scroller does when it is already at its limit that way (backlog F107, CSS's `overscroll-behavior`): `auto` (the default) passes the gesture on to the scroller around it, `contain` keeps it here, moving nothing until it turns back. A gesture picks its target once, when it starts — the innermost scroller under the pointer that can still move the way it goes — and keeps it until it ends, wherever the pointer or the content has gone; one that reaches a limit midway stops there, whatever this says. Only on the axes the node scrolls: a `scrollY` list that contains still passes a sideways swipe to the strip around it. For a panel or a popup's list whose scrolling must never move what is behind it. */
   overscroll?: 'auto' | 'contain';
+  /** Where across the box `rotate` and `scale` are about, as a fraction of its width: 0 the left edge, 0.5 (the default) the middle, 1 the right edge; outside 0..1 is a point past the box. C: `pivot_x` with `pivot_set`. */
+  pivotX?: LengthProp;
+  /** Where down the box `rotate` and `scale` are about, as a fraction of its height: 0 the top, 0.5 (the default) the middle, 1 the bottom. C: `pivot_y` with `pivot_set`. */
+  pivotY?: LengthProp;
   /** Paint this node's background, border, shadow and fragment with each edge on a whole physical pixel: `x` and `x + width` rounded on their own, from where layout put them, as a text's span backgrounds are. Off by default, and a box is drawn where layout put it, so a 1 px `gap` between boxes is there at any scale. On, boxes that share an edge in layout meet on one pixel line, where a join inside a pixel was drawn by halves and left a seam — rows of a band stacked at a pitch that is not whole pixels, or a box that continues a text's selection. Layout, hit-testing, the clip and the children are untouched. A snapped box can draw up to half a pixel from its layout edge and its size can differ by a pixel, so a snapped hairline is 1 or 2 px thick by where it sits. */
   pixelSnap?: boolean;
   /** Background while pressed (or while its hoverGroup is); implies hover tracking. */
@@ -396,10 +414,14 @@ export interface GeneratedSpecProps {
   repeat?: 'normal' | 'reverse' | 'alternate' | 'alternateReverse';
   /** What the node is to assistive technology. Unset, the core derives one (an `onClick` node is a button, an editor a text input, a scrolling box a scroll view, a plain box nothing); `none` hides the node and its subtree from the access tree. A `radio` belongs inside a `radioGroup` and a `tab` inside a `tabList`, labelled with what the choice is: the pair is a composite (`docs/adr/0007-composite-keyboard-patterns.md`) — one Tab stop for the set, the arrows, Home and End moving the choice inside it (each step is the item's click, so the choice follows focus), and a screen reader reading "2 of 3". A `radio` or `tab` with no container above it is a Tab stop of its own that no arrow moves, and the core warns (`item-outside-container`). `menu` holds `menuItem`s and `list` holds `listItem`s the same way. */
   role?: 'none' | 'button' | 'checkbox' | 'radio' | 'switch' | 'slider' | 'tab' | 'tabList' | 'link' | 'heading' | 'list' | 'listItem' | 'image' | 'dialog' | 'group' | 'textInput' | 'multilineTextInput' | 'line' | 'radioGroup' | 'menu' | 'menuItem' | 'terminal';
+  /** Turns this node and everything under it, in turns clockwise (0.25 is a quarter turn right), about its pivot — the centre unless `pivotX` / `pivotY` say — after layout (`docs/adr/0043-a-node-turns-about-its-pivot.md`). Paint-only: the node takes the room its upright self takes, nothing around it moves, `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: a child cut by a turned card's rounded corners stays inside them. Hit where drawn: a tilted card is grabbed on its tilted edge and a press in its box past its edge falls through; drag payloads stay in viewport px. The access rect is the bounding box. Nests by composition. Tweens with `transition` as one slot with `scale`, and an entrance, an exit or a keyframe stop may name it (`enter: { rotate: -0.02 }`, `keyframes: [{ rotate: 0 }, { rotate: 1 }]` spins a box). A float anchored to the parent turns with it; a viewport float does not. On a `path` this is the path's own turn (ADR 0041), which does not tween — wrap it in a box for one that does. Text under a turn leaves the pixel grid, as a turned mask does. `backdropBlur` under a turn blurs the upright box. */
+  rotate?: LengthProp;
   /** The width of a table's `rules` in logical px; 1 when unset. */
   ruleWidth?: LengthProp;
   /** On a table (`dir="table"`, ADR 0033): grid lines of this colour between its columns and between its rows (backlog DX21) — down the middle of each gap between the columns of its widest row, from the first row's top to the last row's bottom, and across the middle of each gap between rows, the content box wide. Drawn with the table's box, under its cells and on whole pixels, so give the table and its rows a `gap` at least `ruleWidth` for the lines to show between cells; the outer edge is the table's `border`. Ignored on anything but a table. */
   rules?: ColorProp;
+  /** Scales this node and everything under it by this factor, uniformly, about its pivot, after layout (`docs/adr/0043-a-node-turns-about-its-pivot.md`); 1 is none. 0 draws nothing in Rust, Node and Lua; in C and Odin, where a zeroed field is unset, 0 is 1. Paint-only, as `rotate` is: layout, the room taken and `onLayout` are the upright node's; what it draws, clips and hits scales. Tweens with `transition` as one slot with `rotate`; `enter: { scale: 0.8 }` settles a chip in, `keyframes: [{ scale: 1.05, at: 0.5 }]` pulses. The edge ramps scale with the box, so a box scaled far up reads soft. */
+  scale?: LengthProp;
   /** Which axes `onScroll` takes (backlog F107): `both` (the default), `x` or `y`. A scroll gesture on an axis the node does not take passes it by, to the scroller around it, and hears nothing here: a terminal that scrolls its history says `y`, and a sideways swipe that starts over it moves the strip it sits in. (A swipe that started elsewhere is not the node's either way: a gesture keeps the target it started with.) Meaningless without `onScroll`. */
   scrollAxes?: 'both' | 'x' | 'y';
   /** The modifiers `onScroll` is for (backlog F122): `"shift"`, `"ctrl"`, `"alt"` and `"super"` (⌘, the Windows key), separated by spaces or commas — `"ctrl super"`. With any named, the node hears only a scroll gesture that began with one of them held, and hears it first: ahead of every scroll container and every `onScroll` that names none, wherever under the pointer the gesture began, the innermost such node winning — so a Ctrl-wheel zoom declared on the window's root is heard over a list, and the list does not scroll. A wheel with none of them held passes the node by, as if it had no `onScroll`: a node that scrolls as well (`overflow`) scrolls for it as any container does. Its `scroll` events carry `mods`, the modifiers held when the gesture began; the gesture stays the node's to the end of its glide, whatever is let go meanwhile, and one begun without them never becomes its. A word that is none of the four is skipped. Unset, a handler like any other. Meaningless without `onScroll`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qxuken/kui",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.47",
   "description": "kui for Node: JSX views lowered into the kui IR, Elm-style messages as data",
   "license": "MIT",
   "repository": {