@qxuken/kui 0.1.0-alpha.38 → 0.1.0-alpha.39

package/CHANGELOG.md

@@ -21,6 +21,110 @@ 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.39 (2026-10-06)
+
+**What breaks.**
+
+- A `line`, `polygon` or `path` in its parent's box space paints in its
+  parent's layer at its place in the tree — over the siblings declared
+  before it, under those declared after — where it was a float layer of
+  its own, above every in-flow node and every float that had opened
+  before it (under Fixed). A stroke declared before a sibling it
+  overlaps is under that sibling now; declare it after to keep it on
+  top. One anchored `float="viewport"` is placed as it was.
+
+### Fixed
+
+- **A stroke is its parent's content, not a layer over the window**
+  (backlog F123, from kawoosh). The core floats every `line`, `polygon`
+  and `path` so it takes no room in a row or column, and since ADR 0023
+  every float is a layer stacked by when it opened — so a glyph drawn as
+  polylines into a pane's title bar, in a pane opened after the first
+  frame, painted over a toast the app had floated on every frame since
+  the window opened: kawoosh's "a new Kawoosh is installed: relaunch to
+  run it" with an `⌥` key cap through its border. A stroke in its
+  parent's box space now paints in the parent's layer, at its place in
+  the tree, as a child that takes no room does, and is held by the
+  parent's clip as before; a stroke anchored to the viewport keeps a
+  layer of its own. `Tree::opens_layer` is the one reading, for the live
+  pass and for a departing stroke's ghost.
+- **`modal-behind-content` reads the paint order, not the float bit**
+  (backlog RG120, from this release's pre-tag pass). With a stroke in its
+  parent's layer, the check for content over a modal the view did not
+  float still took any node under a `float` for a layer over it — and
+  every `line`, `polygon` and `path` is one for the room alone — so an
+  icon drawn with strokes before the modal's declaration raised the
+  warning on a modal nothing painted over. It reads `Tree::opens_layer`
+  now; a viewport-anchored stroke, a layer of its own, still warns.
+
+**What you can delete.** A toast or popover redeclared under a fresh key
+so it stacks over the icons an app draws with `line` or `polygon`, and
+a stroke moved out of its row into a float of its own so a card could
+cover it.
+
+- **`scripts/npm-approve.nu` asks npmjs whatever the npm it runs under
+  is configured with.** An npm with `@qxuken:registry` pointing at the
+  Forgejo copy asks that registry for a scoped package whatever
+  `--registry` says. alpha.38 was published by hand during a GitHub
+  Actions outage, Forgejo's npm copy first, and the script then read
+  Forgejo's dist-tags and said "live on npmjs already" and "latest is
+  0.1.0-alpha.38 already" while npmjs held the version staged. Every
+  call names npmjs for the scope as well now. A release script, so
+  nothing an app sees.
+
+**What you can delete.** Nothing.
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-06 — the
+two commits after the alpha.38 tag: a stroke painting in its parent's
+layer (F123) and the approval script naming npmjs for the scope — with a
+regression pass over them first: the diff read whole, each claim probed
+with a test before anything changed. Six probes were written; five
+passed and are kept in `tests/layers.rs` for what F123's own tests did
+not pin (a `polygon` and a `path` under the same rule, a departing
+stroke's ghost in its parent's layer, a declared float with `clip` still
+a layer, a viewport-anchored stroke still escaping its clip, a clickable
+stroke hit at its place), and the sixth found RG120, which is in this
+release. This round ran on the Mac alone; Windows and Linux did not run
+it for this tag.
+
+**macOS 27.0.1 on an M3 Pro MacBook Pro, rustc 1.99.0 (the toolchain
+CI runs), Node 25.6.0, nu 0.116.0**, on the release commit's tree, the
+workspace's own artifacts pruned and rebuilt. `cargo fmt --all --check`
+and `cargo clippy --workspace --all-targets --features
+kui-core/conformance -- -D warnings` are clean. `cargo test --workspace
+--features kui-core/conformance`: **1816 tests over 136 suites, 0
+failed** (4 ignored). The C round, `cbuild --run`, passes its five
+checks; the corpus passes its **57 scenes** in four adapters; the ABI
+is **25**. Node's `node --test test.mjs` under
+`KUI_CONFORMANCE_REQUIRED=1`: **210 of 210**. `npm run gen` leaves no
+diff, the examples typecheck and their lockfile installs, the headless
+round passes all **35 drives**, the book builds and
+`scripts/book-examples.nu --check` passes.
+
+**The windowed round**, `smoke -- --node`, twice over: **51 Rust
+examples and the eleven Node examples, each on both bases, 120 frames
+each, every one exiting 0** — 124 windows, eight at a time, in
+37.6 and 33.4 s — and `counter`, `host`, `c_panel` and `lua_panel` by
+hand under `KUI_SMOKE_FRAMES=120`, each exiting 0 with nothing on
+stderr: **128 windows over five hosts.** The AX audit: **106/106**, the
+audited window raised to the front by its pid first, and no warning on
+the fixture's stderr. F123 itself was seen in kawoosh's window before
+the merge, built against the branch by path; RG120's case is pinned in
+the core's tests alone.
+
+**The bench guard** against the alpha.38 tag, on the tree the release
+commit was cut from: **green**, none of the 8 guarded rows more than
+10% slower — every one between −5.3% and +1.4% (the worst guarded
+run-to-run spread 2.7%), and no row of the run more than 2.2% slower.
+Three rows got faster by more than the noise, and that is F123:
+`frame_10k_segments` 881 → 834 µs (−5.3%), `frame_1k_closed_lines`
+103 → 97.1 µs (−5.9%) and `frame_1k_polygons` 102 → 97.2 µs (−4.5%) —
+ten thousand strokes that were ten thousand layers for the float stack
+to sort are their parents' content now. `README.md`'s table is kept as
+it was.
+
 ## 0.1.0-alpha.38 (2026-10-05)
 
 **What breaks.**

package/docs/adr/0010-a-segment-primitive.md

@@ -136,6 +136,11 @@ test — is declined or deferred below, each with the reason.
    ignored. Because it is a float it paints in the float pass, on top of
    its parent's in-flow content and in tree order among the other floats:
    a connector meant to sit under two cards is declared before them.
+   *Amended 2026-10-06 (backlog F123):* it paints in its parent's layer
+   at its place in the tree — over the parent's box and the siblings
+   before it, under those after — and opens no layer of its own; the
+   connector under two cards is still declared before them. See the
+   amendment at the end.
    `slide`, `enter` and `exit` offsets move it as they move any float.
    *Amended 2026-09-22 (backlog F78):* it is clipped as a child of its
    parent is — by the parent's own box when the parent clips or
@@ -403,7 +408,17 @@ for a stroke that escapes its parent.
 Paint order does not change. A clipped float is still its own layer, drawn
 above its in-flow siblings in the float pass and hit in the same order
 ([ADR 0023](0023-layers-stack-in-the-order-they-open.md)). Only the clip
-comes from the parent. The corpus's `clip-float` scene pins it in every
+comes from the parent. *Amended 2026-10-06 (backlog F123):* that holds
+for a float a view declared with the bit. A `line`, `polygon` or `path`
+in its parent's box space, whose float the core made, is not a layer at
+all: it paints in its parent's layer at its place in the tree, as a child
+that takes no room — `Tree::opens_layer` is the one reading, for the live
+pass and the ghost pass. Under ADR 0023's stack, where a layer is above
+every layer that opened before it, a stroke's own layer put a key cap
+drawn into a title bar over a toast that had been open since the window's
+first frame; a stroke that is its parent's content stacks with the
+parent. One anchored `float="viewport"` escapes and keeps a layer of its
+own. The corpus's `clip-float` scene pins it in every
 binding: two nodes on a clipping canvas are panned half past its top edge,
 one clipped and one not. A press over the toolbar where the clipped node's
 cut half would be reaches the toolbar, and the same press on the other

package/docs/adr/0023-layers-stack-in-the-order-they-open.md

@@ -374,3 +374,22 @@ paints over the page's bar in a real window, checked by screenshot.
    "draws on top of in-flow content" becomes "a layer of its own, above
    the in-flow tree and every float that opened before it"; the `float`
    schema row (and so `docs/props.md`) gains the same sentence.
+
+## Amendment — a stroke is not a layer (2026-10-06, backlog F123)
+
+Decision 1 made every float root a layer, and the core makes a float of
+every `line`, `polygon` and `path` so it takes no room in a row or column
+([ADR 0010](0010-a-segment-primitive.md) decision 5). Together, under
+decision 3, a stroke drawn a frame after some float opened was above that
+float: kawoosh's update toast, a viewport float declared on every frame
+so it stays under every confirm, had the `⌥` key cap of a pane's title
+bar — polylines — painted over it, since the pane opened after the
+window's first frame. The stroke's float is the core's, for the room
+alone; the stroke is its parent's content, which F78 already said for its
+clip. So a stroke in its parent's box space now paints in its parent's
+layer at its place in the tree, as a child does — `Tree::opens_layer`
+decides what is a layer root, in `emit_frame` and in `PaintOrder::of`
+for a departing one — and only a float a view declared, or a stroke
+anchored to the viewport, opens a layer. `tests/layers.rs` pins the
+stroke under a toast opened before it, a stroke inside a float in that
+float's layer, and the viewport-anchored one above.

package/docs/adr/0025-the-image-is-the-canvas.md

@@ -170,7 +170,9 @@ date: 2026-09-11
    decision 5): always a float, sized to its bounding box inflated by one
    logical px for the antialiasing ramp, points in the parent's box space
    (`float="viewport"` for viewport space), no room taken in a row or
-   column; `slide`, `enter`, `exit` move it as a float. Like a line it
+   column; `slide`, `enter`, `exit` move it as a float — and, since
+   backlog F123, painted in the parent's layer at its place in the tree
+   as a line is, not in a layer of its own. Like a line it
    takes **no input** and has **no access row** (`polygon-ignores-input`
    for the same six keys, a `role` and `label` honoured if declared) —
    *superseded the same day by [ADR 0026](0026-hit-testing-by-shape.md):

package/docs/adr/0040-a-path-is-a-mask-in-the-atlas.md

@@ -105,7 +105,9 @@ date: 2026-10-04
    parent's box space, `float="viewport"` for viewport space, sized to its
    own bounding box inflated by one logical px, no room taken in a row or
    column; `slide`, `enter` and `exit` move and fade it as a float; a
-   declared `clip` holds it as it holds a polygon.
+   declared `clip` holds it as it holds a polygon; and, since backlog
+   F123, it paints in the parent's layer at its place in the tree as a
+   line and a polygon do, not in a layer of its own.
 2. **One wire form, and SVG's `d` parsed in the core.** On the wire a
    path is a flat `f32` list, an op code followed by its operands, every
    coordinate absolute and in the parent's box space: `M x y`, `L x y`,

package/howto.md

@@ -42,7 +42,10 @@ because the removal is judged whole rather than half-animated, and the
 `<line from={[x, y]} to={[x, y]} width color/>` is one round-capped stroke,
 `<line points={[[x, y], …]} curve/>` a polyline or a smooth curve through
 the points; a line is always a float in its parent's box space, sized to its
-own bounding box, so it takes no room in a row or column. With `onClick`,
+own bounding box, so it takes no room in a row or column — and it paints
+where a child declared there would, in its parent's layer, over the siblings
+before it and under those after (a connector meant to sit under two cards is
+declared before them; one meant to sit over them, after). With `onClick`,
 `onDrag` or `hoverable` it is hit by its stroke, at least 4 px wide
 ([ADR 0026](docs/adr/0026-hit-testing-by-shape.md)). Budget its quads: one per segment, and a curve is flattened
 in the core at one piece per 6 logical px of chord, at most 32 per span — so

package/jsx-runtime.d.ts

@@ -900,7 +900,9 @@ export declare namespace JSX {
      *  Placed as a `line` is: always a float in its parent's box space
      *  (`float="viewport"` for viewport space), sized to its own bounding
      *  box two pixels out on each side, so it takes no room in a row or
-     *  column. `transition` eases the fill and, with `slide`, its position.
+     *  column, and painted in the parent's layer at its place in the tree
+     *  (backlog F123). `transition` eases the fill and, with `slide`, its
+     *  position.
      *  Hit by its outline under the fill rule
      *  (docs/adr/0026-hit-testing-by-shape.md): with `onClick`, `onDrag`,
      *  `onHover` or `hoverable`, a press inside hits it and one in its box

package/package.json

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

package/props.md

@@ -164,11 +164,11 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 | `<switch checked onClick key label description tooltip disabled>text</switch>` | `switch { label=, checked=, on_click=, key=, text=, description=, tooltip=, disabled= }` | `kui_switch` | The stock switch (`widgets::toggle_with`, ADR 0034): a track and a knob drawn from `checked`, the knob sliding across when it changes, and its label; read as a switch, on or off. The state is the app's, as a checkbox's is; the rows are the checkbox's, `mixed` aside. |
 | `<slider label valueNow valueMin valueMax valueStep valueText onChange width description tooltip disabled/>` | `slider { label=, value_now=, value_min=, value_max=, value_step=, value_text=, on_change=, width=, … }` | `kui_slider` | The stock slider (`widgets::slider_with`, ADR 0034): a track, a fill to `valueNow` and a thumb, as wide as a menu (`width` sizes it), keyed by its `label`, which is also its accessible name. With `onChange` the core does the arithmetic: a press proposes the value under the pointer, a drag each new step, the arrows one `valueStep`, PageUp / PageDown ten, Home / End the ends, all clamped to `valueMin`..`valueMax` (0..100 unset) and snapped to the step, as `{kind:"change", value, phase:"move"\|"end", tag}`. The value is proposed, never applied: the view stores it and declares it as `valueNow`. Its look is its spec, so the rows it reads are the value rows, the access rows and its width. |
 | `<image src={id} sampling fit>` | `image { id=, sampling=, fit= }` | `kui_image`, `kui_image_with` | A registered RGBA image. Sizing: `width="fit"` takes the pixel size, a fit height against a resolved width keeps the aspect, `radius` rounds it. Two rows say how the pixels meet the box (`docs/adr/0025-the-image-is-the-canvas.md`): `sampling` is `linear` (the default) or `nearest` — pixel art, an emulator, a data grid that must stay square under zoom; `fit` is `fill` (the default: the pixels stretch to the box), `contain` (the largest rect of the image's aspect that fits, centred, the rest of the box showing what is behind) or `cover` (the box filled and the pixels that do not fit cropped, centred). The box — its layout, its hit region, its access rect — is the same in every mode. The pixels come from the atlas, or from a texture of the image's own once `updateImage` has replaced them or when no atlas page could hold them; the node cannot tell and need not. |
-| `<polygon points={[[x,y],…]} bg/>` | `polygon { points={{x,y},…}, bg= }` | `kui_polygon` | A filled polygon through up to eight `points`, the fill in `bg` (`docs/adr/0025-the-image-is-the-canvas.md`, decision 6): an arrowhead, a pie slice, the area under a curve. Placed as a `line` is — always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box a pixel out on each side, so it takes no room in a row or column. A polygon in its parent's box space is held by the parent's clip as a child is, its hit region with it, so it is cut at a scroller's edge with the row it is drawn in; a declared float is held that way only when it declares `clip` with a parent anchor, and a `float="viewport"` polygon escapes (backlog F78, `docs/adr/0010-a-segment-primitive.md` decision 5). `transition` eases the fill and, with `slide`, its position. The outline may be concave; a self-intersecting one fills even-odd, its overlaps unfilled. Hit by its outline (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press inside the outline hits it and one in its box past the outline falls through, so a pie's wedges need no hit boxes; with none it takes no input and has no access row, and with input it derives one as a box would (a clickable wedge is a button), so name it. A ninth point and later are dropped with `polygon-points-truncated`; fewer than three draw nothing; no `bg`, no fill. On the wire it is one `fragment` quad painted by a WGSL function the core registers itself, so a host that draws the list gets its source from `kui_fragment_source` like any other; what it costs is that quad and one pipeline switch per run of polygons. A stroked outline is a closed `line` over it. |
-| `<path d="M … Z" bg width color fillRule rotate pivot dash dashOffset/>` | `path { d = "M … Z", bg=, width=, color=, fill_rule=, rotate=, pivot=, dash=, dash_offset= }` | `kui_path` | Any outline — SVG's `d`, a pie wedge with a round arc, a map's region, an icon — filled with `bg` by `fillRule` (`nonzero`, the default, or `evenodd`) and stroked `width` wide in `color` when `width` is given, the stroke over the fill (`docs/adr/0040-a-path-is-a-mask-in-the-atlas.md`). `d` is SVG path data (`M L H V C S Q T A Z`, absolute or relative), parsed by one parser in the core, so every binding draws the same shape; one that does not parse raises `path-malformed` and draws nothing. JSX also takes `d` as a flat number array of op codes and operands, Lua the same as `ops`, and C only that form (`kui_path_parse` turns a string into it). Placed as a `line` is — always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box two pixels out on each side (half the stroke's width further), so it takes no room in a row or column, held by the parent's clip as a child is. `transition` eases the fill and, with `slide`, its position; the stroke's colour does not tween, as a box's border does not. Hit by its outline under the fill rule (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press inside hits it and one in its box past the outline falls through, so a pie's wedges need no hit boxes; a stroke with no fill is hit by its stroke as a line is; with input it derives an access row as a box would (a clickable wedge is a button), so name it. On the wire it is one glyph-mask quad per paint, fill and stroke: the outline is rasterized once per shape, scale and quarter-pixel position into the glyph atlas and tinted like a glyph, so a host that draws text draws paths, and nothing is re-rasterized for a colour tween, a hover or a slide. The fill bleeds half a pixel, so two paths sharing an edge meet without the background showing through; a chart that wants separators gaps its own geometry. A mask a quarter of the biggest atlas page or more, or a path whose ops change twice within a few frames, draws from a texture of its own instead (a `texture` quad), and one past 8192 px on a side draws nothing, with `path-too-large`. `rotate` turns the path, in turns clockwise, about `pivot` — a point in the path's own coordinates, the centre of its box without one (`docs/adr/0041-a-mask-turns-about-its-centre.md`): the turn is the quad's and not the mask's, so a path that only turns — a spinner's arc about its circle's centre — is rasterized once and stays in the atlas at every angle. A path with `rotate` or `pivot` is boxed by the square the turn sweeps, its mask centred on the pivot on a whole pixel, and it is hit where it is drawn; `rotate` does not tween. `dash` and `dashOffset` cut the stroke into marks and gaps as a `line`'s do (backlog V2) — lengths as seen, round-capped marks — restarting at every subpath as SVG's do; the pattern is part of the stroke's mask, so a dashed stroke costs what a solid one does, a stroke with no fill is still hit along its gaps, and a `dashOffset` that changes every frame is a shape that changes every frame: the path leaves the atlas for a texture of its own while it marches. |
+| `<polygon points={[[x,y],…]} bg/>` | `polygon { points={{x,y},…}, bg= }` | `kui_polygon` | A filled polygon through up to eight `points`, the fill in `bg` (`docs/adr/0025-the-image-is-the-canvas.md`, decision 6): an arrowhead, a pie slice, the area under a curve. Placed as a `line` is — always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box a pixel out on each side, so it takes no room in a row or column, and painted in the parent's layer at its place in the tree, over the siblings before it and under those after (backlog F123). A polygon in its parent's box space is held by the parent's clip as a child is, its hit region with it, so it is cut at a scroller's edge with the row it is drawn in; a declared float is held that way only when it declares `clip` with a parent anchor, and a `float="viewport"` polygon escapes (backlog F78, `docs/adr/0010-a-segment-primitive.md` decision 5). `transition` eases the fill and, with `slide`, its position. The outline may be concave; a self-intersecting one fills even-odd, its overlaps unfilled. Hit by its outline (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press inside the outline hits it and one in its box past the outline falls through, so a pie's wedges need no hit boxes; with none it takes no input and has no access row, and with input it derives one as a box would (a clickable wedge is a button), so name it. A ninth point and later are dropped with `polygon-points-truncated`; fewer than three draw nothing; no `bg`, no fill. On the wire it is one `fragment` quad painted by a WGSL function the core registers itself, so a host that draws the list gets its source from `kui_fragment_source` like any other; what it costs is that quad and one pipeline switch per run of polygons. A stroked outline is a closed `line` over it. |
+| `<path d="M … Z" bg width color fillRule rotate pivot dash dashOffset/>` | `path { d = "M … Z", bg=, width=, color=, fill_rule=, rotate=, pivot=, dash=, dash_offset= }` | `kui_path` | Any outline — SVG's `d`, a pie wedge with a round arc, a map's region, an icon — filled with `bg` by `fillRule` (`nonzero`, the default, or `evenodd`) and stroked `width` wide in `color` when `width` is given, the stroke over the fill (`docs/adr/0040-a-path-is-a-mask-in-the-atlas.md`). `d` is SVG path data (`M L H V C S Q T A Z`, absolute or relative), parsed by one parser in the core, so every binding draws the same shape; one that does not parse raises `path-malformed` and draws nothing. JSX also takes `d` as a flat number array of op codes and operands, Lua the same as `ops`, and C only that form (`kui_path_parse` turns a string into it). Placed as a `line` is — always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box two pixels out on each side (half the stroke's width further), so it takes no room in a row or column, held by the parent's clip as a child is and painted in the parent's layer at its place in the tree (backlog F123). `transition` eases the fill and, with `slide`, its position; the stroke's colour does not tween, as a box's border does not. Hit by its outline under the fill rule (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press inside hits it and one in its box past the outline falls through, so a pie's wedges need no hit boxes; a stroke with no fill is hit by its stroke as a line is; with input it derives an access row as a box would (a clickable wedge is a button), so name it. On the wire it is one glyph-mask quad per paint, fill and stroke: the outline is rasterized once per shape, scale and quarter-pixel position into the glyph atlas and tinted like a glyph, so a host that draws text draws paths, and nothing is re-rasterized for a colour tween, a hover or a slide. The fill bleeds half a pixel, so two paths sharing an edge meet without the background showing through; a chart that wants separators gaps its own geometry. A mask a quarter of the biggest atlas page or more, or a path whose ops change twice within a few frames, draws from a texture of its own instead (a `texture` quad), and one past 8192 px on a side draws nothing, with `path-too-large`. `rotate` turns the path, in turns clockwise, about `pivot` — a point in the path's own coordinates, the centre of its box without one (`docs/adr/0041-a-mask-turns-about-its-centre.md`): the turn is the quad's and not the mask's, so a path that only turns — a spinner's arc about its circle's centre — is rasterized once and stays in the atlas at every angle. A path with `rotate` or `pivot` is boxed by the square the turn sweeps, its mask centred on the pivot on a whole pixel, and it is hit where it is drawn; `rotate` does not tween. `dash` and `dashOffset` cut the stroke into marks and gaps as a `line`'s do (backlog V2) — lengths as seen, round-capped marks — restarting at every subpath as SVG's do; the pattern is part of the stroke's mask, so a dashed stroke costs what a solid one does, a stroke with no fill is still hit along its gaps, and a `dashOffset` that changes every frame is a shape that changes every frame: the path leaves the atlas for a texture of its own while it marches. |
 | `<fragment src={id} image={id} params={[…]} animate>` | `fragment { id=, image=, params={…}, animate= }` | `kui_fragment`, `kui_fragment_with` | A box a registered WGSL function paints (`docs/adr/0015-a-fragment-element-and-the-painter-it-is-not.md`): a conic or a moving gradient, rings, noise, shimmer — anything the paint vocabulary has no prop for. An ordinary node otherwise — it lays out, rounds, clips, fades, takes input and holds children, which paint over it — but with **no intrinsic size**, so give it a `width`/`height` or `fill` or it is zero by zero. `src` is a handle from `add_fragment`, which validates the source and warns rather than minting one that cannot compile. `params` is up to sixteen numbers the shader reads as four `vec4<f32>`; more are dropped with a warning. `image` is a registered image the function reads — `kui_sample(uv)` (bilinear) and `kui_sample_nearest(uv)` return its texels at `uv` in `[0,1]²`, and `in.image` is its texel rect, `zw` the size — which is what makes a replaced image a waveform, a heatmap, a 50k-point line or an image effect from one quad (`docs/adr/0025-the-image-is-the-canvas.md`, decision 7); the core binds the atlas or the image's own texture, whichever holds it, and a fragment whose image is not live draws nothing, as one whose `src` is not does. `animate` asks for a frame every frame, which is what a fragment that reads `time` needs and what a still one must not declare. |
 | `<cells rows cols cells={Uint32Array} cursorAt={[row, col]} cursorShape cursorColor size family lineHeight/>` | `cells { rows=, cols=, lines={"row text", …}, runs={{row, col, len, fg, bg, flags}, …}, cursor_at={row, col}, cursor_shape=, cursor_color=, size=, family= }` | `kui_cells` | A terminal's screen as one node (backlog C20): `rows × cols` cells, each a character, a foreground and background as `0xRRGGBBAA` (0 = no background), and attribute bits — 1 bold, 2 italic, 4 underline, 8 strikethrough, 16 wide (the glyph spans this cell and the next, which the app leaves blank), 32 the underline is a wave (a terminal's undercurl, SGR 4:3) and 64 dotted (SGR 4:4), either implying it — plus, optionally, the underline's own colour (SGR 58), 0 for the foreground (backlog K4). A glyph is shaped once per character and style variant and thereafter placed at `col × cell_w` without shaping, so a screen whose every cell is new each frame costs what a still one costs (~60 µs for 200 × 50). The cell width is `M`'s advance in the style's font snapped to whole pixels, the height its `lineHeight`; a cell is a cell, so ligatures never form. A character the family has no glyph for is asked of a monospaced face before the platform's fallback list, shaped smaller where it is still wider than its cells (two under wide), and drawn in their middle (backlog F120); the private use area's icons are left as they fall. Box drawing and block elements (U+2500–U+259F) and the Powerline separators (U+E0B0–U+E0BF: the arrows, and the Powerline Extra half circles and wedges) are not shaped at all but drawn from the cell box — a font's are its own line box tall, a cell is `lineHeight` tall, and through the font every `│` was a dash with a gap under it (backlog F66) and a rounded cap a fallback font's squiggle (F112) — so a TUI's frames and rounded rows are seamless in any font, and bold does not thicken a light line (the set has its heavy variants). JSX passes the cells as a `Uint32Array` (or number array) of four entries per cell — codepoint, fg, bg, flags — or five, with the underline colour, in row-major order; Lua a string per row in `lines` plus `runs` of `{row, col, len, fg, bg, flags, ul}` over them (a run's fg, bg or ul of 0 keeps the default: the style's colour, no background, the foreground); C a `KuiCell` array with `ul`. `cursorAt` (`cursor_at`) names a cell to paint under its glyph in `cursorColor` as a `block` (default), `bar` or `underline` — its own name, since `cursor` is the pointer shape. `originLine` (`origin_line`) is the absolute line number of row 0: a grid is one screenful of the app's own history, so a row number means a different line after every scroll, and stamping where the screen sits is what lets a selection keep its ends across one (`docs/adr/0017-selection-as-a-scope.md`). Saying nothing is 0, and a selection then holds only while the screen does not move. The node's own rows apply — an `onKey` makes it the terminal's sink, an `onClick` or `onDrag` carries `cell: {row, col}` on its events — and its access row is `terminal`, the rows joined as its value. |
-| `<line from={[x,y]} to={[x,y]} width color/>`, `<line points={[[x,y],…]} curve dash={[6, 4]} dashOffset/>` | `line { from={x,y}, to={x,y}, width=, color= }`, `line { points={{x,y},…}, curve=true, dash={6, 4}, dash_offset= }` | `kui_line`, `kui_polyline` | A round-capped stroke: one segment, a polyline through `points`, or a smooth curve through them with `curve`. Always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box, so it takes no room in a row or column. A stroke in its parent's box space is held by the parent's clip as a child is, its hit region with it, so it is cut at a scroller's edge with the row it is drawn in; a declared float is held that way only when it declares `clip` with a parent anchor, and a `float="viewport"` stroke escapes (backlog F78, `docs/adr/0010-a-segment-primitive.md` decision 5). `width` is the stroke width (default 1) and `color` the stroke colour; `transition` eases the colour, and with `slide` beside it the stroke's position too — the points ride its box, so a stroke whose ends all move together slides with them, while one whose ends move apart resizes at once (a canvas of floats eases everything or nothing, connectors included). Hit by its shape (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press within half the width of any piece hits it — at least 4 px of grab, so a hairline is a target — and a press elsewhere in its bounding box falls through to what is under; with none it takes no input and has no access row, and with input it derives one as a box would (a clickable connector is a button), so name it. What it costs: one quad per segment, and a curve is flattened in the core at one piece per 6 logical px of chord (at most 32 per span) — fixed rather than tolerance-driven so every binding gets the same pieces and the corpus can pin them — so a nine-point curve over ~50 px spans is ~60 quads, and a `quadCount` budget should expect it. `dash` cuts the stroke into marks and gaps (backlog V2): one length (marks and gaps alike), a mark and a gap, or four lengths for a dash-dot, in px **as seen** — every mark is a short stroke with the stroke's round caps, so `dash` 6, 4 is 6 px of ink and 4 px of nothing at any width, and a mark no longer than the stroke is wide is a dot (SVG's `stroke-dasharray` measures the centre line instead, so with round caps its `4 4` at a width of 4 is solid; this pattern is SVG's `mark − width, gap + width`). The pattern runs along the stroke's whole length, so it keeps its phase round the corners of a polyline and the pieces of a curve, and `dashOffset` starts that far into it — growing it moves the marks towards the first point, a marquee's marching ants; neither tweens. A pattern with no gap, a mark and gap under a physical pixel together, or more than 16384 marks draws solid. A dashed stroke is hit along its whole length, gaps included, and costs a quad per mark per piece the mark lies on. |
+| `<line from={[x,y]} to={[x,y]} width color/>`, `<line points={[[x,y],…]} curve dash={[6, 4]} dashOffset/>` | `line { from={x,y}, to={x,y}, width=, color= }`, `line { points={{x,y},…}, curve=true, dash={6, 4}, dash_offset= }` | `kui_line`, `kui_polyline` | A round-capped stroke: one segment, a polyline through `points`, or a smooth curve through them with `curve`. Always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box, so it takes no room in a row or column — but a float for the room alone: in its parent's box space it paints in the parent's layer at its place in the tree, over the siblings declared before it and under those after, as a child does, and opens no layer of its own (backlog F123; a connector meant to sit under two cards is declared before them). A stroke in its parent's box space is held by the parent's clip as a child is, its hit region with it, so it is cut at a scroller's edge with the row it is drawn in; a declared float is held that way only when it declares `clip` with a parent anchor, and a `float="viewport"` stroke escapes, and is a layer of its own (backlog F78, `docs/adr/0010-a-segment-primitive.md` decision 5). `width` is the stroke width (default 1) and `color` the stroke colour; `transition` eases the colour, and with `slide` beside it the stroke's position too — the points ride its box, so a stroke whose ends all move together slides with them, while one whose ends move apart resizes at once (a canvas of floats eases everything or nothing, connectors included). Hit by its shape (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press within half the width of any piece hits it — at least 4 px of grab, so a hairline is a target — and a press elsewhere in its bounding box falls through to what is under; with none it takes no input and has no access row, and with input it derives one as a box would (a clickable connector is a button), so name it. What it costs: one quad per segment, and a curve is flattened in the core at one piece per 6 logical px of chord (at most 32 per span) — fixed rather than tolerance-driven so every binding gets the same pieces and the corpus can pin them — so a nine-point curve over ~50 px spans is ~60 quads, and a `quadCount` budget should expect it. `dash` cuts the stroke into marks and gaps (backlog V2): one length (marks and gaps alike), a mark and a gap, or four lengths for a dash-dot, in px **as seen** — every mark is a short stroke with the stroke's round caps, so `dash` 6, 4 is 6 px of ink and 4 px of nothing at any width, and a mark no longer than the stroke is wide is a dot (SVG's `stroke-dasharray` measures the centre line instead, so with round caps its `4 4` at a width of 4 is solid; this pattern is SVG's `mark − width, gap + width`). The pattern runs along the stroke's whole length, so it keeps its phase round the corners of a polyline and the pieces of a curve, and `dashOffset` starts that far into it — growing it moves the marks towards the first point, a marquee's marching ants; neither tweens. A pattern with no gap, a mark and gap under a physical pixel together, or more than 16384 marks draws solid. A dashed stroke is hit along its whole length, gaps included, and costs a quad per mark per piece the mark lies on. |
 | `<titlebar title>` or `<titlebar>…</titlebar>` | `titlebar { title= }` / `titlebar { … }` | `kui_titlebar`, `kui_titlebar_with` | Adaptive titlebar for custom chrome: drag strip, native-control inset, window buttons. |
 | `<menuBar menu={[{ label, items: [{ label, id?, role?, accel?, enabled?, checked? }] }]}/>` | `menu_bar { menu = { { label=, items= { { label=, id=, role=, accel=, enabled=, checked= } } } } }` | `kui_menu_bar` | The application menu (`docs/adr/0018-a-menu-bar-the-app-declares.md`): `menu` is what it *is*, and where this element sits is where its titles go when they have to be drawn in the window. One call and not two, because declaring the menu and placing the strip are one decision. It draws **nothing** where the platform owns the bar — macOS, where the driver hands the same declaration to the OS — so the frame has still said what the app's menu is and the strip simply is not there; that is the contract `windowButtons` has under native decorations, and it is what makes one view portable. Its rows are the rows a context menu has: the same `role`s the core performs itself (`copy`, `paste`, `selectAll`, `cut`, `lookUp`), the same `id` payload, the same `accel` text, plus `checked` for a setting — and choosing one posts the same `{kind:"menu", role, item}` event, so an app handles one thing whichever menu it came from. Declared every frame and diffed: an unchanged menu costs a comparison, and an empty list takes it away. An accelerator kui can parse is rewritten into the platform's spelling, so `"mod+s"` reads as `⌘S` on macOS and `Ctrl+S` elsewhere and binds that key in the platform's own bar. On macOS the first menu is the application menu, which the OS titles with the app's own name whatever the label says. While a menu is open the bar is the frame's modal scope, so hovering across the titles moves the open menu, a press on the open title closes it, and Escape or a press in the app below closes it and reaches nothing else. |
 | `<windowButtons/>` | `window_buttons()` | `kui_window_buttons` | Just the min/max/close buttons, for fully custom titlebars. |