From 0019c8e195f05e3e9c147a5759816be6d4d87e2a Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Wed, 2 Sep 2026 17:37:57 -0500
Subject: [PATCH 1/2] feat(ts): close component markup grammar

- Add segmented-control markup support with interpreter, compiled, contract, docs, preview, and conformance coverage.
- Convert stepper and timeline-item ejects to TypeScript-compatible Native markup templates with identity parity tests.
- Document and preserve explicit rulings for deferred data-grid, popover, image-lifecycle, and styling work.
---
 .../components/segmented-control-dark.webp    | Bin 0 -> 1900 bytes
 .../segmented-control-hero-dark.webp          | Bin 0 -> 1810 bytes
 .../segmented-control-hero-light.webp         | Bin 0 -> 1828 bytes
 .../components/segmented-control-light.webp   | Bin 0 -> 1870 bytes
 docs/src/app/docs/cli/page.mdx                |   2 +-
 docs/src/app/docs/components/button/page.mdx  |   2 +-
 .../components/segmented-control/layout.tsx   |   7 +
 .../components/segmented-control/page.mdx     |  47 +++++++
 docs/src/app/docs/components/stepper/page.mdx |   2 +-
 docs/src/app/docs/components/tabs/page.mdx    |   4 +-
 .../src/app/docs/components/timeline/page.mdx |   2 +-
 docs/src/app/docs/native-ui/page.mdx          |   7 +-
 docs/src/lib/component-vocab.json             |  20 ++-
 docs/src/lib/components-pages.ts              |   1 +
 skill-data/native-ui/SKILL.md                 |   5 +-
 src/primitives/canvas/ui_markup.zig           |  43 ++++--
 src/primitives/canvas/ui_markup_compiled.zig  |  25 +++-
 .../canvas/ui_markup_compiled_tests.zig       |  17 +++
 src/primitives/canvas/ui_markup_contract.zig  |   3 +
 .../canvas/ui_markup_contract_tests.zig       |  14 ++
 src/primitives/canvas/ui_markup_tests.zig     |  27 ++++
 src/primitives/canvas/ui_markup_view.zig      |  49 +++++--
 .../canvas/ui_markup_view_tests.zig           |  54 ++++++--
 src/primitives/canvas/ui_schema.zig           |   3 +
 src/primitives/canvas/ui_schema_tests.zig     |   6 +-
 src/tooling/components/identity_tests.zig     |  52 +++----
 src/tooling/components/stepper.native         |  22 +++
 src/tooling/components/stepper.zig            | 113 ---------------
 src/tooling/components/timeline-item.native   |  20 +++
 src/tooling/components/timeline_item.zig      | 131 ------------------
 src/tooling/eject_components.zig              |  32 +++--
 tools/docs_preview_scenes.zig                 |  25 +++-
 tools/native-sdk/main.zig                     |   7 +
 tools/native-sdk/markup_docs.zig              |   3 +-
 tools/native-sdk/markup_lsp.zig               |   2 +-
 35 files changed, 407 insertions(+), 340 deletions(-)
 create mode 100644 docs/public/components/segmented-control-dark.webp
 create mode 100644 docs/public/components/segmented-control-hero-dark.webp
 create mode 100644 docs/public/components/segmented-control-hero-light.webp
 create mode 100644 docs/public/components/segmented-control-light.webp
 create mode 100644 docs/src/app/docs/components/segmented-control/layout.tsx
 create mode 100644 docs/src/app/docs/components/segmented-control/page.mdx
 create mode 100644 src/tooling/components/stepper.native
 delete mode 100644 src/tooling/components/stepper.zig
 create mode 100644 src/tooling/components/timeline-item.native
 delete mode 100644 src/tooling/components/timeline_item.zig

diff --git a/docs/public/components/segmented-control-dark.webp b/docs/public/components/segmented-control-dark.webp
new file mode 100644
index 0000000000000000000000000000000000000000..ab912edc40b0de0c9d7569471db4e4988c73bb89
GIT binary patch
literal 1900
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

literal 0
HcmV?d00001

diff --git a/docs/public/components/segmented-control-hero-dark.webp b/docs/public/components/segmented-control-hero-dark.webp
new file mode 100644
index 0000000000000000000000000000000000000000..f830ff5005db397f2dd54e1f9a7e65e3341f4f8c
GIT binary patch
literal 1810
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
T(|zH4YIyYjIgl}t2zTN?Xr+^A

literal 0
HcmV?d00001

diff --git a/docs/public/components/segmented-control-hero-light.webp b/docs/public/components/segmented-control-hero-light.webp
new file mode 100644
index 0000000000000000000000000000000000000000..506de40f020fd897e5b13e5e4678ce6548ea069f
GIT binary patch
literal 1828
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

literal 0
HcmV?d00001

diff --git a/docs/public/components/segmented-control-light.webp b/docs/public/components/segmented-control-light.webp
new file mode 100644
index 0000000000000000000000000000000000000000..4ad10b4b255e2040d71f7ddd4190886c5aa7b5d6
GIT binary patch
literal 1870
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
SFQv*~@&B^Xe+?E*Wcv@HqPsHy

literal 0
HcmV?d00001

diff --git a/docs/src/app/docs/cli/page.mdx b/docs/src/app/docs/cli/page.mdx
index 20f57eb67..c4e612924 100644
--- a/docs/src/app/docs/cli/page.mdx
+++ b/docs/src/app/docs/cli/page.mdx
@@ -95,7 +95,7 @@ Write an owned `build.zig`/`build.zig.zon` into the app (once); the verbs then d
 native eject component <name> [dir]
 ```
 
-Write an owned copy of a library composite into `src/components/` (once, never overwriting — ejecting again errors with the file to delete first). Ejectable today: `stepper`, `timeline`, `timeline-item` — the library views that are honest compositions of primitives; engine controls are not on the menu (theme them through [tokens](/docs/theming) instead). `timeline` lands as a markup template (use it via `<use template="timeline" ...>`), the others as Zig view functions; each file opens with a header comment walking through the call-site migration, and each builds a widget tree identical to its library form at the moment of ejection. Unknown names get a did-you-mean plus the full ejectable list. See [Building Components](/docs/building-components#use-eject-or-build).
+Write an owned copy of a library composite into `src/components/` (once, never overwriting — ejecting again errors with the file to delete first). Ejectable today: `stepper`, `timeline`, `timeline-item` — the library views that are compositions of primitives; engine controls are not on the menu (theme them through [tokens](/docs/theming) instead). All three eject as Native markup templates, so they work in TypeScript apps without an app-side Zig file; use them through `<import>` and `<use>`. Each file opens with a header comment walking through the call-site migration, and each builds a widget tree identical to its library form at the moment of ejection. Unknown names get a did-you-mean plus the full ejectable list. See [Building Components](/docs/building-components#use-eject-or-build).
 
 ### `native doctor`
 
diff --git a/docs/src/app/docs/components/button/page.mdx b/docs/src/app/docs/components/button/page.mdx
index 846ded1b2..fa2f94878 100644
--- a/docs/src/app/docs/components/button/page.mdx
+++ b/docs/src/app/docs/components/button/page.mdx
@@ -36,7 +36,7 @@ Four sizes: `sm`, `default`, `lg`, and `icon` — the icon size renders a square
 
 ## Icons
 
-`icon` names a built-in vector icon (see the [icon registry](/docs/components/icon)) drawn inline before the label — one hit target, one enabled/disabled tint.
+`icon` names a built-in vector icon (see the [icon registry](/docs/components/icon)) drawn inline before the label — one hit target, one enabled/disabled tint. For an image-free icon button, use `size="icon"` with empty content and provide `label` for its accessible name. Registered-image button content remains a separate asset-lifecycle proposal.
 
 <ComponentPreview name="button-icons" alt="Buttons with inline icons rendered by the engine" />
 
diff --git a/docs/src/app/docs/components/segmented-control/layout.tsx b/docs/src/app/docs/components/segmented-control/layout.tsx
new file mode 100644
index 000000000..4bc7db339
--- /dev/null
+++ b/docs/src/app/docs/components/segmented-control/layout.tsx
@@ -0,0 +1,7 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("components/segmented-control");
+
+export default function SegmentedControlLayout({ children }: { children: React.ReactNode }) {
+  return children;
+}
diff --git a/docs/src/app/docs/components/segmented-control/page.mdx b/docs/src/app/docs/components/segmented-control/page.mdx
new file mode 100644
index 000000000..9a62e6238
--- /dev/null
+++ b/docs/src/app/docs/components/segmented-control/page.mdx
@@ -0,0 +1,47 @@
+import { ComponentPreview } from "@/components/component-preview";
+import { AttrTable } from "@/components/attr-table";
+
+# Segmented Control
+
+A standalone exclusive-choice segment. Each `segmented-control` is one named, pressable item: bind `selected` from the model, dispatch `on-press`, and add a vector `icon` when the label benefits from one. Put several in a row for a compact choice control; use [tabs](/docs/components/tabs) when you also need the tab-strip container and conditional panel.
+
+<ComponentPreview name="segmented-control" alt="Standalone segmented controls rendered by the engine" caption="Day, Week, and Month segments with Week selected" />
+
+## Markup
+
+```html
+<row gap="6">
+  <segmented-control selected="{range == day}" on-press="choose_day">Day</segmented-control>
+  <segmented-control selected="{range == week}" icon="settings" on-press="choose_week">Week</segmented-control>
+  <segmented-control selected="{range == month}" on-press="choose_month">Month</segmented-control>
+</row>
+```
+
+`selected` is model-owned. Pressing a segment sends its message; the next view rebuild reflects the new selection. The segment itself is a text-bearing control, so it needs visible content or a `label` accessible name.
+
+## Icons and sizes
+
+The `icon` attribute uses the same closed vector-icon vocabulary as [button](/docs/components/button). It is drawn as part of the segment's own hit target and follows the segment's state tint. `size` selects the shared control register; `label` supplies an accessible name when the visible content is absent.
+
+```html
+<row gap="6">
+  <segmented-control size="sm" selected="{view == list}" icon="file-text" label="List" on-press="show_list" />
+  <segmented-control size="sm" selected="{view == board}" icon="settings" label="Board" on-press="show_board" />
+</row>
+```
+
+## Programmatic construction (Zig)
+
+In a Zig view, use the same retained widget kind directly with `canvas.Ui`:
+
+```zig
+ui.row(.{ .gap = 6 }, .{
+    ui.el(.segmented_control, .{ .text = "Day", .selected = model.range == .day, .on_press = .choose_day }, .{}),
+    ui.el(.segmented_control, .{ .text = "Week", .icon = "settings", .selected = model.range == .week, .on_press = .choose_week }, .{}),
+    ui.el(.segmented_control, .{ .text = "Month", .selected = model.range == .month, .on_press = .choose_month }, .{}),
+})
+```
+
+## Attributes
+
+<AttrTable attrs={["text", "selected", "disabled", "size", "icon", "icon-placement", "label", "key", "global-key", "on-press", "on-hold"]} />
diff --git a/docs/src/app/docs/components/stepper/page.mdx b/docs/src/app/docs/components/stepper/page.mdx
index c7edf50b5..663896c65 100644
--- a/docs/src/app/docs/components/stepper/page.mdx
+++ b/docs/src/app/docs/components/stepper/page.mdx
@@ -10,7 +10,7 @@ A stage stepper: `step` children joined by hairline connectors, with `active` na
 
 ## Markup
 
-`active` is required — a number or one `{binding}`.
+`active` is required — a number or one `{binding}`. The component is also ejectable as a markup template when you need to own its shape.
 
 ```html
 <stepper active="{publish_step}">
diff --git a/docs/src/app/docs/components/tabs/page.mdx b/docs/src/app/docs/components/tabs/page.mdx
index a1de229ce..dce254584 100644
--- a/docs/src/app/docs/components/tabs/page.mdx
+++ b/docs/src/app/docs/components/tabs/page.mdx
@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";
 
 # Tabs
 
-A tab strip: ONE muted rounded container (the house tab-strip treatment) whose triggers sit inside it — the active trigger lifts to the surface with a hairline, inactive triggers stay muted on the container's wash. The children are [buttons](/docs/components/button) whose `selected` state marks the active tab — usually an equality against a model field — and whose `on-press` switches it. The segmented-control foundation is what the engine renders tab triggers with: both markup engines lower `<button>` children of `<tabs>` to `segmented_control` widgets (the builder uses `segmented_control` children directly), so the strip renders identically however it is authored. The panel itself is ordinary conditional content: an `if` per tab under the strip.
+A tab strip: ONE muted rounded container (the house tab-strip treatment) whose triggers sit inside it — the active trigger lifts to the surface with a hairline, inactive triggers stay muted on the container's wash. The children are [buttons](/docs/components/button) whose `selected` state marks the active tab — usually an equality against a model field — and whose `on-press` switches it. The segmented-control foundation is also available directly as `<segmented-control>` leaves: both markup engines lower `<button>` children of `<tabs>` to `segmented_control` widgets (the builder uses `segmented_control` children directly), so the strip renders identically however it is authored. The panel itself is ordinary conditional content: an `if` per tab under the strip.
 
 <ComponentPreview name="tabs" alt="A tab strip rendered by the engine" caption="Account selected in a three-tab strip" />
 
@@ -33,7 +33,7 @@ A tab strip: ONE muted rounded container (the house tab-strip treatment) whose t
 
 ## Programmatic construction (Zig)
 
-In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically. In the builder the strip's children are `segmented_control` elements — the widget kind the engine's tab strips are built on (segmented controls are a documented markup exclusion, so markup composes the strip from buttons instead).
+In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically. In the builder the strip's children are `segmented_control` elements, the same widget kind available as a standalone markup leaf.
 
 ```zig
 ui.el(.tabs, .{}, .{
diff --git a/docs/src/app/docs/components/timeline/page.mdx b/docs/src/app/docs/components/timeline/page.mdx
index 180634540..39762f268 100644
--- a/docs/src/app/docs/components/timeline/page.mdx
+++ b/docs/src/app/docs/components/timeline/page.mdx
@@ -4,7 +4,7 @@ import { EjectSection } from "@/components/eject-section";
 
 # Timeline
 
-A timeline/ledger list container: a vertical column of `timeline-item` children (`for` and `if` work inside it). Each item pairs a leading indicator badge — `indicator` text or a small dot, colored by `variant` — with a title/description/meta content column, joined by a connector rail; set `connector="false"` on the last item to end the rail. Binding `on-press` makes the whole item pressable with a trailing chevron. For a horizontal stage indicator, see [stepper](/docs/components/stepper).
+A timeline/ledger list container: a vertical column of `timeline-item` children (`for` and `if` work inside it). Each item pairs a leading indicator badge — `indicator` text or a small dot, colored by `variant` — with a title/description/meta content column, joined by a connector rail; set `connector="false"` on the last item to end the rail. Binding `on-press` makes the whole item pressable with a trailing chevron. Both the container and item can be ejected as markup templates when you need to own their shape. For a horizontal stage indicator, see [stepper](/docs/components/stepper).
 
 <ComponentPreview name="timeline" alt="A timeline rendered by the engine" caption="indicator badges, titles with descriptions and meta lines, and the connector rail" />
 
diff --git a/docs/src/app/docs/native-ui/page.mdx b/docs/src/app/docs/native-ui/page.mdx
index 5d927a515..2d853f38a 100644
--- a/docs/src/app/docs/native-ui/page.mdx
+++ b/docs/src/app/docs/native-ui/page.mdx
@@ -54,7 +54,7 @@ The runtime owns the rest: install, presentation, resize, typed event dispatch,
 | `tree` | disclosure tree | vertical container whose descendant rows with `role="treeitem"` form one roving keyboard focus set: Up/Down walk visible rows (selection follows focus via `on-change` when bound, otherwise `on-press`), Left collapses or moves to the parent row, Right expands or moves to the first child row, Home/End jump to the edges, Enter/Space activate; nested rows derive hierarchy structurally, while flat `<for>` rows declare their one-based `tree-level`; expandable rows bind `expanded` and `on-toggle`, and the model owns both states |
 | `text`, `badge`, `tooltip` | text leaves | `{}` interpolation allowed in content; `text` takes a line policy via `wrap` (`"true"` word-wraps; `"false"`/unset paint one honest line) and an overflow policy via `overflow` (`ellipsis` — the default trailing elision — or `clip`) and the typography rungs via `size="heading"`/`size="display"` (themable token steps above title — section headings, hero stats). `tooltip` with `anchor="above\|below"` floats against its parent — the `stack` wrapping trigger + tooltip, the same shape as the anchored `dropdown-menu` — and the runtime owns its visibility through hover intent: it shows after the pointer rests on the trigger for `tooltip-delay` milliseconds (default 600; `"0"` shows instantly), skips the delay during the shared 400ms warm window after a pointer-hovered tooltip hides on leave, and shows immediately when the trigger gains keyboard focus; it hides on pointer leave (the only hide that warms), focus departure, Escape, or a press — the model never hears hover. Without `anchor` it stays a static leaf that paints whenever the view renders it — see [Tooltip](/docs/components/tooltip) |
 | `text` > `span` | inline styled runs | mixed-style text in one wrapped paragraph: span children style runs with `weight="regular\|medium\|bold"`, `mono`, `italic`, `scale` (a positive multiplier on the paragraph's base size — inline headings, hero stats), `underline`, `foreground` (a token name); `{bindings}` interpolate inside spans; whitespace between runs collapses to a single space (none = the runs abut); spans do not nest, take no events, and the paragraph announces as one text run — see [Rich text](#rich-text-inline-spans-and-markdown) |
-| `button`, `toggle-button`, `list-item`, `menu-item`, `toggle`, `switch`, `select`, `avatar` | text-bearing controls | the label is the element content; `button`, `toggle-button`, `list-item`, and `menu-item` also take `icon="..."` — a vector icon drawn inline (buttons and toggle-buttons before the label, icon-only when the content is empty; list and menu items as a leading slot), one hit target that follows the element's enabled/disabled tint; tab strips are `toggle-button` children, so tabs get icons this way; `select` shows its `placeholder` while empty and dispatches `on-press`; `avatar` renders initials, or a runtime image via `image="{binding}"`. `list-item` alone also accepts element children IN PLACE of the text run (the list-row composite): the children flow horizontally inside the row's flat chrome — transparent at rest, full-width hover/selected washes, one hit target — so composite rows (title + snippet, leading icon + trailing badge) stay honest list rows instead of bordered boxes; name the row with `label` and never mix a text run with children. Rows that really are cards (a kanban board's draggable cards) opt into the card treatment explicitly with `background`/`radius` |
+| `button`, `toggle-button`, `list-item`, `menu-item`, `toggle`, `switch`, `select`, `avatar` | text-bearing controls | the label is the element content; `button`, `toggle-button`, `list-item`, and `menu-item` also take `icon="..."` — a vector icon drawn inline (buttons and toggle-buttons before the label, icon-only when the content is empty; list and menu items as a leading slot), one hit target that follows the element's enabled/disabled tint; tab strips are `toggle-button` children, so tabs get icons this way; `select` shows its `placeholder` while empty and dispatches `on-press`; `avatar` renders initials, or a runtime image via `image="{binding}"`. `list-item` alone also accepts element children IN PLACE of the text run (the list-row composite): the children flow horizontally inside the row's flat chrome — transparent at rest, full-width hover/selected washes, one hit target — so composite rows (title + snippet, leading icon + trailing badge) remain list rows instead of bordered boxes; name the row with `label` and never mix a text run with children. Rows that really are cards (a kanban board's draggable cards) opt into the card treatment explicitly with `background`/`radius` |
 | `checkbox`, `radio`, `slider`, `progress` | value controls | `checked`, `value` |
 | `text-field`, `input`, `search-field`, `combobox`, `textarea` | text entry | `placeholder`; edits arrive via `on-input` |
 | `status-bar` | status bar | content only, no children |
@@ -66,6 +66,7 @@ The runtime owns the rest: install, presentation, resize, typed event dispatch,
 | `video` | video playback | leaf; `src` declares the app's single platform-decoded playback (an assets path or `http(s)` URL, local-first like audio), `autoplay`/`loop`/`muted` shape it, and `controls` composes the house transport chrome — without it the element is the surface alone and your update code drives the video command vocabulary; no intrinsic size, `label` it; goldens and replay see the placeholder, transport is journaled truth — see [Video](/docs/components/video) |
 | `stepper` > `step` | stage stepper | `active="{index}"` derives each step's completed/active/pending state; steps are text leaves joined by connectors — see [Pipeline components](#pipeline-components-stepper-timeline-and-nav) |
 | `timeline` > `timeline-item` | ledger/timeline list | items are leaves whose `title`/`description`/`meta`/`indicator` attributes carry the content; `on-press` makes the whole item pressable |
+| `segmented-control` | exclusive-choice control | standalone text-bearing segment; bind `selected`, dispatch `on-press`, and optionally add a vector `icon`; compose several in a row, or use [tabs](/docs/components/tabs) for the strip-and-panel pattern |
 | `chart` > `series` | data chart | each series binds a model `[]const f32` iterable via `values="{binding}"` (`kind` is `line`/`area`/`bar`, `color` a token name); `y-min`/`y-max`/`grid-lines`/`baseline` shape the plot, `x-labels`/`y-labels` add muted axis ticks, `hover-details` adds the pointer detail card — see [Charts](#charts) |
 | `input-group` > `textarea` + `input-group-actions` | grouped input | the composer shape: ONE bordered field wrapping exactly one `textarea` (first) plus an optional `input-group-actions` row of controls inside the same border — the group wears the focus ring for its focused descendant and the textarea's own chrome dissolves; put a `<spacer grow="1"/>` between leading and trailing controls — see [Input Group](/docs/components/input-group) |
 
@@ -88,7 +89,7 @@ A tab strip, a select trigger, and a table read the way you would guess:
 </table>
 ```
 
-A few widget kinds are deliberately **not** markup elements because their shape does not fit the closed grammar — write these as Zig view functions with `canvas.Ui`: `image` (it references image pixels by `ImageId` — registered at runtime, see [Images](#images) below — which attribute values cannot carry), `icon_button` (`<button icon="...">` with empty content covers the declarative case), `data_grid` (needs per-column cell templates — arbitrary render callbacks), `popover` and `menu_surface` (Zig-side floating surfaces; the ANCHORED `dropdown-menu` covers the declarative case), and `segmented_control` (a shell-chrome kind; `tabs` and `toggle-group` cover its use cases). (`icon` used to sit on this list; the built-in vector icon set made it expressible — the name vocabulary is closed and compile-checked.) The one image binding markup does carry is the avatar's: `image="{binding}"` names a `u64` `ImageId` model field or function — the id is just model data, never a markup literal, and `0` keeps the initials fallback.
+A few widget capabilities remain proposals rather than markup admissions. `data_grid` still needs a per-column cell-template contract (row type, column value, keys, accessibility, and virtualization behavior); `popover` and `menu_surface` need an anchoring ruling (nearest positioned ancestor versus an explicit anchor relationship, including the HTML-markup surface); and image-backed `icon_button`/`image` usage needs the TypeScript asset-lifecycle ruling. Per-state styling beyond design tokens belongs to the HTML-markup lane's stage 4. Existing vector icon buttons are fully declarative as `<button size="icon" icon="..." label="..." on-press="..." />`; `segmented-control` is a first-class markup leaf, and runtime image bindings remain available on `avatar` and `image` as documented below.
 
 Apps with their own iconography can parse any stroke-dialect/Feather/Tabler-dialect SVG at comptime (`canvas.svg_icon.parseComptime(@embedFile("icons/logo.svg"))`) and register it at boot with `canvas.icons.registerAppIcons(&table)`: the draw paths (icon leaves via `ui.appIcon`, `ElementOptions.icon` on buttons, toggle buttons, icon buttons, and list/menu items) resolve registered names exactly like built-ins. Markup reaches them through the `app:` NAMESPACE (`<icon name="app:waveform"/>`, `icon="app:waveform"`): bare names keep the closed built-in vocabulary (the compiled engine proves them at comptime, where a runtime registration cannot exist), while `app:` names are structurally accepted by both engines and verified by `native check` against the model contract - declare the table as `pub const app_icons` on the app root so the contract emit reflects the same names `main` registers. Bound icon names (`icon="{binding}"`) make the choice model data - a per-row status icon, a play/pause toggle - and any name that fails to resolve at draw time renders the missing-icon fallback (a slashed circle) with a Debug warning naming the value, never a silent gap.
 
@@ -538,7 +539,7 @@ macOS-first, like `resizable = false`: GTK and Win32 hosts keep standard chrome
 
 ## Images
 
-Image pixels are runtime-registered resources: the app registers decoded straight-alpha RGBA8 under a caller-chosen `ImageId` (a `u64` kept in the model, effect-key style; 0 is the "no image" sentinel), and `image`, `icon_button`, and `avatar` widgets reference the id. Native SDK bundles no image codecs — encoded bytes (PNG, JPEG, whatever the OS decodes) go through the platform decoder: CGImageSource on macOS and the iOS toolkit host, gdk-pixbuf on GTK, WIC on Windows, BitmapFactory on the Android toolkit host (both mobile hosts register the codec over the embed image service; an embed host without one reports `error.UnsupportedService`).
+Image pixels are runtime-registered resources: the app registers decoded straight-alpha RGBA8 under a caller-chosen `ImageId` (a `u64` kept in the model, effect-key style; 0 is the "no image" sentinel), and `image` and `avatar` widgets reference the id in markup. The builder also exposes the id to the lower-level `icon_button` kind; image-backed icon buttons remain a Stage 2 asset-lifecycle proposal. Native SDK bundles no image codecs — encoded bytes (PNG, JPEG, whatever the OS decodes) go through the platform decoder: CGImageSource on macOS and the iOS toolkit host, gdk-pixbuf on GTK, WIC on Windows, BitmapFactory on the Android toolkit host (both mobile hosts register the codec over the embed image service; an embed host without one reports `error.UnsupportedService`).
 
 The first-class load path is `fx.loadImage` (`Cmd.imageLoad` on the TS tier): one effect resolving a local-then-URL source cascade with a content-addressed cache, decoding, registering, and delivering exactly one result Msg — see [Dynamic Images](/docs/dynamic-images) for the whole story, including the byte-identical offline replay guarantee. The registration seam underneath is also callable directly — the hand-rolled fetch-avatar path is one update arm: fetch bytes, decode + register in one call, and write the id into the model only on success — so the avatar renders its initials while the image is loading and keeps them when the fetch or decode failed:
 
diff --git a/docs/src/lib/component-vocab.json b/docs/src/lib/component-vocab.json
index 87e1fca92..8b0758902 100644
--- a/docs/src/lib/component-vocab.json
+++ b/docs/src/lib/component-vocab.json
@@ -52,6 +52,10 @@
       "name": "button",
       "doc": "Text-bearing control; the label is the text content. Dispatch with on-press. icon draws a vector icon inline before the label (icon-only when the content is empty; give it a label) — one hit target, one enabled/disabled tint."
     },
+    {
+      "name": "segmented-control",
+      "doc": "Standalone exclusive-choice trigger; the label is the text content, selected marks the active item, and icon may add a vector icon. Compose items with ordinary markup, for, or a template."
+    },
     {
       "name": "checkbox",
       "doc": "Text-bearing value control; the visible label is text content (or text=), bind checked, dispatch with on-toggle."
@@ -1068,6 +1072,10 @@
       "width": 1120,
       "height": 320
     },
+    "segmented-control": {
+      "width": 1120,
+      "height": 320
+    },
     "toggle": {
       "width": 1120,
       "height": 320
@@ -1396,6 +1404,10 @@
       "width": 704,
       "height": 396
     },
+    "segmented-control-hero": {
+      "width": 704,
+      "height": 396
+    },
     "separator-hero": {
       "width": 704,
       "height": 396
@@ -1578,8 +1590,8 @@
   "ejectable": [
     {
       "name": "stepper",
-      "form": "Zig view function",
-      "path": "src/components/stepper.zig"
+      "form": "markup template",
+      "path": "src/components/stepper.native"
     },
     {
       "name": "timeline",
@@ -1588,8 +1600,8 @@
     },
     {
       "name": "timeline-item",
-      "form": "Zig view function",
-      "path": "src/components/timeline_item.zig"
+      "form": "markup template",
+      "path": "src/components/timeline-item.native"
     }
   ]
 }
diff --git a/docs/src/lib/components-pages.ts b/docs/src/lib/components-pages.ts
index 892cb008d..47dd2c8e8 100644
--- a/docs/src/lib/components-pages.ts
+++ b/docs/src/lib/components-pages.ts
@@ -45,6 +45,7 @@ export const componentPages: ComponentPage[] = [
   { slug: "resizable", name: "Resizable", preview: "resizable-hero", blurb: "Panel with an engine-managed drag handle." },
   { slug: "scroll", name: "Scroll", preview: "scroll-hero", blurb: "Scroll regions with model-observable offsets." },
   { slug: "select", name: "Select", preview: "select-hero", blurb: "Trigger plus the anchored dropdown options pattern." },
+  { slug: "segmented-control", name: "Segmented Control", preview: "segmented-control-hero", blurb: "Standalone selected segments with typed press events." },
   { slug: "separator", name: "Separator", preview: "separator-hero", blurb: "Hairline rules, horizontal and vertical." },
   { slug: "sheet", name: "Sheet", preview: "sheet-hero", blurb: "Bottom-anchored modal surface." },
   { slug: "skeleton", name: "Skeleton", preview: "skeleton-hero", blurb: "Loading placeholders that sketch the content." },
diff --git a/skill-data/native-ui/SKILL.md b/skill-data/native-ui/SKILL.md
index 6cdf7f7c9..a9749fe34 100644
--- a/skill-data/native-ui/SKILL.md
+++ b/skill-data/native-ui/SKILL.md
@@ -208,12 +208,13 @@ Automation drives the native path honestly: snapshots list every widget's declar
 | `text`, `badge`, `tooltip` | text leaves | text content, `{}` interpolation allowed; `text` line policy via `wrap` (`"true"` word-wraps; `"false"`/unset paint one honest line, overflow eliding by default — `overflow="clip"` opts out), and `text` alone takes the typography rungs `size="heading"`/`size="display"` (themable token steps above title — section headings, hero stats, timer numerals). `tooltip` with `anchor="above\|below"` floats against its parent (the stack wrapping trigger + tooltip, the dropdown pattern) and the RUNTIME owns its visibility — hover intent on the trigger: shows after `tooltip-delay` ms (default 600; `"0"` = instant) and immediately on keyboard focus; hides on leave, focus departure, Escape, or a press of the trigger (a press also closes the warm window), and a shared 400ms warm window after a pointer-hovered tooltip hides on leave (the only hide that warms) shows the next trigger's tooltip instantly; the model never hears hover. These are shadcn/ui's defaults (Base UI). Without `anchor` it stays a static leaf that paints whenever the view renders it |
 | `text` > `span` | inline styled runs | mixed-style text in ONE wrapped paragraph: span children style runs with `weight="regular\|medium\|bold"`, `mono`, `italic`, `scale` (a positive multiplier on the paragraph's base size — inline headings, hero stats), `underline`, `foreground` (token name); `{bindings}` interpolate inside spans; whitespace between runs collapses to a single space (none = the runs abut); spans do not nest, take no events, and the paragraph announces as one text run — see "Rich text" |
 | `button`, `toggle-button`, `list-item`, `menu-item`, `toggle`, `switch`, `select`, `avatar` | text-bearing controls | label is the text content; `button`, `toggle-button`, `list-item`, and `menu-item` also take `icon="save"` — a vector icon drawn inline (buttons/toggle-buttons before the label, icon-only when the content is empty: add a `label`; list/menu items as a leading slot), ONE hit target whose icon follows the element's enabled/disabled tint (no overlay stacking, no duplicated `on-press`); tab strips are `toggle-button` children, so tabs get icons this way; `select` shows `placeholder` while empty and dispatches `on-press`; `avatar` renders initials, or a runtime image via `image="{binding}"` (see the Images section) |
+| `segmented-control` | exclusive-choice control | standalone text-bearing segment; bind `selected`, dispatch `on-press`, and optionally add a vector `icon`; compose several in a row, or use `tabs` for the strip-and-panel pattern |
 | `checkbox`, `radio`, `slider`, `progress` | value controls | `checked`, `value` (a 0..1 fraction on slider and progress; progress clamps out-of-range values at render, never an error); checkbox/radio visible labels are text content (`<checkbox>Done</checkbox>`), with `text="..."` as the equivalent binding-friendly form and `label=` alone naming one for accessibility without drawing a label; a radio selection TRANSITION (pointer, Space/Enter, grouped navigation, or accessibility selection) dispatches `on-change` when bound, then `on-toggle`, then `on-press` for compatibility — reactivating the already-checked radio has no new `on-change` edge, though a legacy fallback still receives the activation; a slider's `value` follows the source when it MOVES (model-driven progress renders every rebuild) and keeps the user's drag while the source replays the same value — use `slider` for seek bars, `progress` for display-only; a markup slider's `on-change` dispatches a PLAIN Msg with no value payload — mirror the applied value into the model with `Options.sync` (the Zig builder's `on_value = Ui.valueMsg(.tag)` does deliver the applied f32) |
 | `text-field`, `input`, `search-field`, `combobox`, `textarea` | text entry | `placeholder`; edits via `on-input`, enter via `on-submit` on single-line kinds; in a default `textarea`, Enter (and Shift+Enter) inserts a newline and `on-submit` dispatches on primary+Enter (cmd on macOS, ctrl elsewhere). A chat composer opts into `submit-on-enter="true"`: plain Enter submits, Shift+Enter remains a newline, and the primary chord still submits. `search-field` carries a built-in trailing clear affordance whenever it holds text (press the x, or Escape while focused — both clear through the text-edit path, so `on-input` hears it; no attribute, no external Clear button needed) |
 | `status-bar` | status bar | text leaf: content only, no children |
 | `separator`, `spacer` | separator, flexible space | `separator` is axis-aware: a horizontal rule in a `column`, a thin vertical divider in a `row`; give `spacer` a `grow` |
 | `skeleton`, `spinner` | loading leaves | size `skeleton` with `width`/`height` |
-| `icon` | vector icon leaf | `name` picks the icon: a bare literal is a curated built-in stroke icon (compile-checked; 49 names: search, plus, x, x-circle, check, check-circle, chevron-up/down/left/right, arrow-up/down/right, menu, panel-left, panel-right, settings, terminal, wrench, trash, edit, copy, external-link, play, pause, skip-back/forward, shuffle, repeat, music, volume, info, alert, download, save, folder, folder-open, file-text, sun, moon, eye, clock, git-pull-request, git-merge, git-branch, circle-dot, archive, refresh-cw, send); `app:<name>` reaches an icon the app registered at boot with `canvas.icons.registerAppIcons` (declare the table as `pub const app_icons` on the app root so `native check` verifies the name against the model contract), and one `{binding}` defers the choice to model data - an unknown resolved name draws the missing-icon fallback (a slashed circle) with a Debug warning naming the value, never a silent gap; tint with `foreground`, size with `width`/`height` |
+| `icon` | vector icon leaf | `name` picks the icon: a bare literal is a curated built-in stroke icon (compile-checked; 49 names: search, plus, x, x-circle, check, check-circle, chevron-up/down/left/right, arrow-up/down/right, menu, panel-left, panel-right, settings, terminal, wrench, trash, edit, copy, external-link, play, pause, skip-back/forward, shuffle, repeat, music, volume, info, alert, download, save, folder, folder-open, file-text, sun, moon, eye, clock, git-pull-request, git-merge, git-branch, circle-dot, archive, refresh-cw, send); `app:<name>` reaches an icon the app registered at boot with `canvas.icons.registerAppIcons` (declare the table as `pub const app_icons` on the app root so `native check` verifies the name against the model contract), and one `{binding}` defers the choice to model data - an unknown resolved name draws the missing-icon fallback (a slashed circle) with a Debug warning naming the value; tint with `foreground`, size with `width`/`height` |
 | `media-surface` | media surface leaf | composites a texture produced OUTSIDE the widget tree (video decoder, camera, an external renderer like mpv) into the layout like any widget — clipped, z-ordered, rounded. `surface="{binding}"` (required) binds the model-owned u64 surface id a Zig-tier producer targets (`runtime.acquireMediaSurfaceProducer` pushes RGBA8 frames, latest-wins, paced by the presented-frame clock; 0 = unbound, draws nothing; usable ids are nonzero values below the reserved bit 63). No intrinsic size — give it `width`/`height` or `grow`; display-only (presses fall through); `label` it (pictorial content). Texture contents are presentation chrome: goldens, reference screenshots, and session replay show the deterministic id-derived placeholder, never producer frames |
 | `image` | runtime image leaf | draws a RUNTIME-REGISTERED image by its model-owned u64 ImageId — the id `Cmd.imageLoad` (TS) or `fx.loadImage`/`fx.registerImageBytes` (Zig) registered pixels under. `image="{binding}"` (required) binds a model field/fn; ids are model data, never markup literals, and 0 draws nothing (store the id only when the load reports loaded — see the Images section). `source-x`/`source-y`/`source-width`/`source-height` select one atlas region in decoded-image pixel coordinates (declare all four). No intrinsic size — give it `width`/`height` or `grow`; display-only (presses fall through); `label` it (pictorial content) |
 | `code` | bare highlighted source/editor | `source="{binding}"` (required) provides source text and `language="tsx"` selects a literal lexer name; the component supplies no background, border, radius, shadow, or padding, so wrap it in a panel/card when chrome is wanted. It is read-only by default; `editable on-input="edit"` opts into multiline editing while retaining highlighting. It wraps by default, `line-numbers` opts into logical line numbers, `added-lines="5"` / `removed-lines="2-4"` add Geist-style diff rows without changing copied source, and `wrap="false"` preserves lines inside one horizontal scroll region. HTML-family highlighting distinguishes HTML/XML/SVG and JSX/TSX tags, attributes, strings, comments, and embedded expressions. Zig builder: `ui.code(CodeOptions, source)` |
@@ -224,7 +225,7 @@ Automation drives the native path honestly: snapshots list every widget's declar
 | `context-menu` | consumed by its parent | right-click menu on its DIRECT parent (a hit-target kind or an element with `on-press`/`on-double-press`/`on-toggle`/`on-hold`/`on-drag`); metadata, never a flow child. Children: `menu-item`s (`on-press` required, `disabled` optional, no `icon`) and bare `separator`s, with `if`/`else`/`for` around them. Attribute-less; presents natively where the host has a menu presenter, as an anchored surface elsewhere — see "Context menus" |
 | `input-group` > `textarea` + `input-group-actions` | composite grouped input | the composer shape: ONE bordered field wrapping exactly one `textarea` (first — document order is focus order) plus an optional `input-group-actions` row of controls inside the same border. The group wears the focus ring for its focused descendant and the textarea's own chrome dissolves automatically, so the whole group reads as one field; the textarea keeps its full behavior (`text`, `placeholder`, `on-input`, `on-submit`, `autofocus`, and optional `submit-on-enter`). Group takes `label`, `width`, `height`, `min-width`, `grow`, `key`, `global-key`; the actions row takes `gap` and holds ordinary elements (`if`/`else`/`for` work — swap send for stop while streaming) — put a `<spacer grow="1"/>` between leading and trailing controls (`Ui.inputGroup`/`Ui.inputGroupActions` are the Zig-view equivalents) |
 
-Not markup-expressible (deliberately — write these as Zig view functions with `canvas.Ui`): `icon_button` (`<button icon="...">` with empty content is the declarative icon button), `data_grid` (per-column cell templates), `popover`/`menu_surface` (anchored to runtime geometry), `segmented_control` (use `tabs`/`toggle-group`: `<button>` children of `<tabs>` lower to segmented triggers automatically, so the active tab lifts per the house treatment). Charts ARE expressible: `<chart>` with `<series values="{binding}">` children binding model f32 iterables — see the Charts section (`.band` series and dynamic series composition stay with `ui.chart`). Built-in vector icons ARE expressible: `<icon name="search"/>` (closed, compile-checked name set; `Ui.icon` is the Zig-view equivalent). App-authored icons: `canvas.svg_icon.parseComptime(@embedFile("icons/logo.svg"))` parses any SVG in the common 24x24 stroke-icon dialect at comptime; register the parsed table once at boot with `canvas.icons.registerAppIcons(&table)` and draw by name via `ui.appIcon(.{...}, "logo")` or `ElementOptions.icon` — registered names render exactly like built-ins on every draw path. Markup `<icon>`/`<button icon>` stay built-in-only (the compiled engine validates names at comptime, where runtime registrations cannot exist — engine parity). Runtime images ARE expressible: `<image image="{cover}" width="120" height="80" label="Cover art"/>` and `<avatar image="{user_image}">CT</avatar>` bind a `u64` ImageId model field/fn (the id is just model data; 0 draws nothing / keeps the initials fallback) — see the Images section; the `image` binding is required on the leaf (an unbound `<image>` is dead markup) and stays avatar+image scoped. Add all four `source-x`/`source-y`/`source-width`/`source-height` attributes to draw one decoded-pixel sub-rectangle from a shared atlas.
+Capabilities still awaiting a separate admission or ruling are image-backed `icon_button` content, `data_grid` per-column cell templates, and `popover`/`menu_surface` anchoring. `segmented-control` is a first-class markup leaf, and vector icon buttons use `<button size="icon" icon="..." label="..." on-press="..." />`. Charts ARE expressible: `<chart>` with `<series values="{binding}">` children binding model f32 iterables — see the Charts section (`.band` series and dynamic series composition stay with `ui.chart`). Built-in vector icons ARE expressible: `<icon name="search"/>` (closed, compile-checked name set; `Ui.icon` is the Zig-view equivalent). App-authored icons: `canvas.svg_icon.parseComptime(@embedFile("icons/logo.svg"))` parses any SVG in the common 24x24 stroke-icon dialect at comptime; register the parsed table once at boot with `canvas.icons.registerAppIcons(&table)` and draw by name via `ui.appIcon(.{...}, "logo")` or `ElementOptions.icon` — registered names render exactly like built-ins on every draw path. Markup `<icon>`/`<button icon>` stay built-in-only (the compiled engine validates names at comptime, where runtime registrations cannot exist — engine parity). Runtime images ARE expressible: `<image image="{cover}" width="120" height="80" label="Cover art"/>` and `<avatar image="{user_image}">CT</avatar>` bind a `u64` ImageId model field/fn (the id is just model data; 0 draws nothing / keeps the initials fallback) — see the Images section; the `image` binding is required on the leaf (an unbound `<image>` is dead markup) and stays avatar+image scoped. Add all four `source-x`/`source-y`/`source-width`/`source-height` attributes to draw one decoded-pixel sub-rectangle from a shared atlas.
 
 ## Attributes
 
diff --git a/src/primitives/canvas/ui_markup.zig b/src/primitives/canvas/ui_markup.zig
index 8eea90ee0..19a04c4f4 100644
--- a/src/primitives/canvas/ui_markup.zig
+++ b/src/primitives/canvas/ui_markup.zig
@@ -1089,10 +1089,7 @@ fn typedTextSegmentsComptime(comptime text: []const u8) []const TypedTextSegment
 /// Element names the interpreter accepts, derived from the registry
 /// (ui_schema.zig; the registry↔engine conformance tests live in
 /// ui_markup_view_tests.zig). Covers every built-in component whose shape
-/// fits the closed grammar; the deliberate exclusions (image,
-/// icon-button, data-grid, popover, menu-surface, segmented-control) are
-/// documented next to the widget-kind coverage test in
-/// ui_markup_view_tests.zig — write those as Zig view functions.
+/// fits the closed grammar, including standalone segmented-control leaves.
 pub const known_element_names = schema.element_names;
 
 /// Elements whose content is a single run of text (with `{}`
@@ -1268,7 +1265,7 @@ pub const tooltip_delay_element_message = "tooltip-delay is only supported on to
 pub const tooltip_delay_dependent_attr_message = "tooltip-delay needs anchor on the same tooltip - only an anchored tooltip is hover-shown by the runtime (a static tooltip paints whenever the view renders it), so without anchor the delay is silently inert";
 
 pub const image_binding_message = "image takes one {binding} to a u64 ImageId the app registered at runtime (Cmd.imageLoad, fx.loadImage, fx.registerImageBytes) - runtime image ids are model data, not markup literals; 0 renders nothing (an avatar falls back to its initials)";
-pub const image_binding_element_message = "image is only supported on avatar and image - the remaining image-bearing widget (icon-button) stays a Zig view (ElementOptions.image)";
+pub const image_binding_element_message = "image is only supported on avatar and image - the remaining image-bearing widget (icon-button) stays deferred until the TypeScript asset lifecycle is decided";
 pub const image_source_element_message = "source-x, source-y, source-width, and source-height are only supported on avatar and image - they crop a runtime-registered image in decoded-image pixel coordinates";
 pub const image_source_binding_message = "source-x, source-y, source-width, and source-height require the element's image binding - without a registered image the source rectangle is inert";
 pub const image_source_complete_message = "source-x, source-y, source-width, and source-height must be declared together - they form one source rectangle in decoded-image pixel coordinates";
@@ -1311,7 +1308,7 @@ pub const icon_missing_name_message = "icon requires a name attribute selecting
 pub const icon_children_message = "icon is a leaf - it takes no children";
 
 pub const button_icon_message = "icon takes a built-in icon name drawn inside the element (see canvas.icons.known_icon_names, e.g. save, plus, refresh-cw), an app-registered app:<name> (canvas.icons.registerAppIcons), or one {binding} resolving to such a name";
-pub const button_icon_element_message = "icon is only supported on button, toggle-button, list-item, menu-item, and badge - it draws a vector icon inside the element as one hit target; for a bare icon use <icon name=\"...\"/>";
+pub const button_icon_element_message = "icon is only supported on button, toggle-button, list-item, menu-item, badge, and segmented-control - it draws a vector icon inside the element as one hit target; for a bare icon use <icon name=\"...\"/>";
 
 /// The `app:` icon namespace: the markup channel into the app's OWN
 /// registered vector icons (`canvas.icons.registerAppIcons`). Bare names
@@ -1394,8 +1391,8 @@ fn wellShapedIconName(name: []const u8) bool {
 /// enabled/disabled state). Registry-derived from the `icon_attr` element
 /// predicate; mirrors the engine kinds that consume `Widget.icon`:
 /// buttons and toggle-buttons draw it before the label (tab strips are
-/// toggle-button children, so tabs get icons through this), list items
-/// and menu items draw it as a leading slot.
+/// toggle-button children, so tabs get icons through this), list items,
+/// menu items, and segmented controls draw it as an inline slot.
 pub const known_icon_attr_element_names = schema.icon_attr_element_names;
 
 pub fn iconAttrElement(name: []const u8) bool {
@@ -2371,7 +2368,7 @@ fn validateCode(node: MarkupNode) ?MarkupErrorInfo {
 /// `<stepper active="{index}">` takes only `<step>` text-leaf children:
 /// each step's state (completed/active/pending) derives from its position
 /// against the active index, so steps carry no attributes of their own.
-fn validateStepper(node: MarkupNode) ?MarkupErrorInfo {
+fn validateStepper(node: MarkupNode, slot_rule: SlotRule) ?MarkupErrorInfo {
     var has_active = false;
     for (node.attrs) |attribute| {
         if (std.mem.eql(u8, attribute.name, "active")) {
@@ -2391,6 +2388,16 @@ fn validateStepper(node: MarkupNode) ?MarkupErrorInfo {
     }
     if (!has_active) return errorAt(node, stepper_active_message);
     for (node.children) |child| {
+        if (child.kind == .slot_block) {
+            // Ejected steppers use a single slot to pass their step items
+            // through the built-in composite. The use-site children are
+            // checked by validateUseChildren; a slot is only legal in a
+            // template body.
+            if (slot_rule != .template_body) return errorAt(child, slot_outside_template_message);
+            if (child.attrs.len > 0) return attrError(child, child.attrs[0], slot_attrs_message);
+            if (child.children.len > 0) return errorAt(child.children[0], slot_children_message);
+            continue;
+        }
         if (child.kind != .element or !std.mem.eql(u8, child.name, "step")) {
             return errorAt(child, stepper_children_message);
         }
@@ -2980,10 +2987,24 @@ comptime {
 fn validateRuleHook(hook: []const u8, document: MarkupDocument, node: MarkupNode, parent_element: ?[]const u8, template_limit: usize, slot_rule: SlotRule) ?MarkupErrorInfo {
     if (std.mem.eql(u8, hook, "markdown")) return validateMarkdown(node);
     if (std.mem.eql(u8, hook, "code")) return validateCode(node);
-    if (std.mem.eql(u8, hook, "stepper")) return validateStepper(node);
+    if (std.mem.eql(u8, hook, "stepper")) return validateStepper(node, slot_rule);
     if (std.mem.eql(u8, hook, "step")) {
         // Steps inside a stepper are consumed by validateStepper; one
-        // reaching the generic pass sits outside a stepper.
+        // reaching the generic pass sits outside a stepper. A use site's
+        // slot children are validated before expansion, with the same
+        // step shape and a template parent that is not yet known.
+        if (slot_rule == .use_children) {
+            for (node.attrs) |attribute| return attrError(node, attribute, step_attr_message);
+            var text_runs: usize = 0;
+            for (node.children) |child| {
+                if (child.kind != .text) return errorAt(child, text_leaf_children_message);
+                text_runs += 1;
+                if (text_runs > 1) return errorAt(child, text_leaf_single_run_message);
+                if (textInterpolationError(child)) |info| return info;
+                if (textNodeCoverageError(child)) |info| return info;
+            }
+            return null;
+        }
         return errorAt(node, step_parent_message);
     }
     if (std.mem.eql(u8, hook, "timeline")) return validateTimeline(document, node, template_limit, slot_rule);
diff --git a/src/primitives/canvas/ui_markup_compiled.zig b/src/primitives/canvas/ui_markup_compiled.zig
index 410bd28f3..d758ab2c2 100644
--- a/src/primitives/canvas/ui_markup_compiled.zig
+++ b/src/primitives/canvas/ui_markup_compiled.zig
@@ -1005,6 +1005,10 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
                 }
                 if (node.attr("active") == null) fail(node, markup.stepper_active_message);
                 for (node.children) |child| {
+                    if (child.kind == .slot_block) {
+                        if (node.children.len != 1) fail(child, markup.stepper_children_message);
+                        continue;
+                    }
                     if (child.kind != .element or !std.mem.eql(u8, child.name, "step")) {
                         fail(child, markup.stepper_children_message);
                     }
@@ -1029,12 +1033,27 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
             if (comptime (node.attr("label") != null)) {
                 options.semantics.label = stringAttr(node, entries, comptime node.attr("label").?, ui, model, scope, "label expects text");
             }
-            const steps = ui.arena.alloc(Ui.StepperStep, node.children.len) catch {
+            const slot_index: ?usize = comptime if (node.children.len == 1 and node.children[0].kind == .slot_block) innermostSlotIndex(entries) else null;
+            if (comptime (node.children.len == 1 and node.children[0].kind == .slot_block and slot_index == null)) {
+                comptime fail(node.children[0], markup.slot_outside_template_message);
+            }
+            const step_nodes = comptime if (slot_index) |index| entries[index].slot_nodes else node.children;
+            const steps = ui.arena.alloc(Ui.StepperStep, step_nodes.len) catch {
                 ui.failed = true;
                 return ui.el(.row, .{}, .{});
             };
-            inline for (0..node.children.len) |index| {
-                steps[index] = .{ .label = interpolatedText(comptime node.children[index], entries, ui, model, scope) };
+            if (comptime (slot_index != null)) {
+                const index = comptime slot_index.?;
+                const site_scope = scopePayload(entries, index, scope);
+                inline for (0..step_nodes.len) |step_index| {
+                    const child = comptime step_nodes[step_index];
+                    if (comptime (child.kind != .element or !std.mem.eql(u8, child.name, "step"))) fail(child, markup.stepper_children_message);
+                    steps[step_index] = .{ .label = interpolatedText(child, comptime entries[index].slot_entries, ui, model, site_scope) };
+                }
+            } else {
+                inline for (0..step_nodes.len) |index| {
+                    steps[index] = .{ .label = interpolatedText(comptime step_nodes[index], entries, ui, model, scope) };
+                }
             }
             return ui.stepper(options, steps);
         }
diff --git a/src/primitives/canvas/ui_markup_compiled_tests.zig b/src/primitives/canvas/ui_markup_compiled_tests.zig
index 8666c91f2..4c3698d4b 100644
--- a/src/primitives/canvas/ui_markup_compiled_tests.zig
+++ b/src/primitives/canvas/ui_markup_compiled_tests.zig
@@ -92,6 +92,23 @@ const InboxUi = canvas.Ui(fixture.Msg);
 const InboxInterpreter = markup_view.MarkupView(fixture.Model, fixture.Msg);
 const InboxCompiled = canvas.CompiledMarkupView(fixture.Model, fixture.Msg, fixture.inbox_markup_source);
 
+const SegmentedCompiled = canvas.CompiledMarkupView(fixture.SegmentedModel, fixture.SegmentedMsg, fixture.segmented_markup_source);
+
+test "compiled segmented-control and vector icon button match the interpreter" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const model = fixture.SegmentedModel{};
+    var interpreter_view = try markup_view.MarkupView(fixture.SegmentedModel, fixture.SegmentedMsg).init(arena, fixture.segmented_markup_source);
+    var interpreter_ui = fixture.SegmentedUi.init(arena);
+    const interpreted = try interpreter_ui.finalize(try interpreter_view.build(&interpreter_ui, &model));
+    var compiled_ui = fixture.SegmentedUi.init(arena);
+    const compiled = try compiled_ui.finalize(SegmentedCompiled.build(&compiled_ui, &model));
+    try expectSameTree(fixture.SegmentedMsg, interpreted, compiled);
+    try testing.expectEqual(canvas.WidgetKind.segmented_control, compiled.root.children[0].kind);
+    try testing.expectEqualStrings("settings", compiled.root.children[2].icon);
+}
+
 const zero_card_padding_markup =
     \\<card padding="0">
     \\  <text>Flush</text>
diff --git a/src/primitives/canvas/ui_markup_contract.zig b/src/primitives/canvas/ui_markup_contract.zig
index 708e28aaa..743180ec7 100644
--- a/src/primitives/canvas/ui_markup_contract.zig
+++ b/src/primitives/canvas/ui_markup_contract.zig
@@ -1242,6 +1242,9 @@ const Checker = struct {
             }
             if (std.mem.eql(u8, attribute.name, "image")) {
                 // Runtime image ids are model integers (engine parity).
+                if (!std.mem.eql(u8, node.name, "avatar") and !std.mem.eql(u8, node.name, "image")) {
+                    return self.failAttr(node, attribute, markup.image_binding_element_message);
+                }
                 const expression = markup.parseAttrExpression(attribute.value) orelse continue;
                 if (expression != .binding) continue;
                 const resolved = try self.resolveBinding(node, expression.binding, true);
diff --git a/src/primitives/canvas/ui_markup_contract_tests.zig b/src/primitives/canvas/ui_markup_contract_tests.zig
index c25d4566c..428478522 100644
--- a/src/primitives/canvas/ui_markup_contract_tests.zig
+++ b/src/primitives/canvas/ui_markup_contract_tests.zig
@@ -865,6 +865,20 @@ test "app: icon references check against the contract's registered icon list" {
     try testing.expectEqualStrings(markup.app_icon_prefix, contract.app_icon_prefix);
 }
 
+test "segmented-control bindings and messages check through the model contract" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    const document = try parseFixture(arena,
+        \\<row>
+        \\  <segmented-control selected="{active}" icon="settings" on-press="add">Settings</segmented-control>
+        \\</row>
+    );
+    var usage = try contract.Usage.init(arena, &model_contract);
+    try testing.expectEqual(null, try contract.checkDocument(arena, document, &model_contract, &usage));
+}
+
 // ------------------------------------------------------------ dead state
 
 test "dead state warns on unbound model state and undispatched Msg tags" {
diff --git a/src/primitives/canvas/ui_markup_tests.zig b/src/primitives/canvas/ui_markup_tests.zig
index 94bdf478d..44aead9ef 100644
--- a/src/primitives/canvas/ui_markup_tests.zig
+++ b/src/primitives/canvas/ui_markup_tests.zig
@@ -712,9 +712,11 @@ test "the image attribute validates as one binding on avatar and image" {
         // attribute would be silently inert.
         .{ .source = "<row>\n  <badge image=\"{user_image}\">3</badge>\n</row>", .message = markup.image_binding_element_message },
         .{ .source = "<column>\n  <panel image=\"{user_image}\" />\n</column>", .message = markup.image_binding_element_message },
+        .{ .source = "<row>\n  <button image=\"{user_image}\" label=\"Preview\" />\n</row>", .message = markup.image_binding_element_message },
         // Source rectangles are image/avatar-only, require an image, and
         // are atomic so a missing coordinate never defaults silently.
         .{ .source = "<row>\n  <badge source-x=\"0\" source-y=\"0\" source-width=\"16\" source-height=\"16\">3</badge>\n</row>", .message = markup.image_source_element_message },
+        .{ .source = "<row>\n  <button source-x=\"0\" source-y=\"0\" source-width=\"16\" source-height=\"16\" label=\"Preview\" />\n</row>", .message = markup.image_source_element_message },
         .{ .source = "<row>\n  <avatar source-x=\"0\" source-y=\"0\" source-width=\"16\" source-height=\"16\">CT</avatar>\n</row>", .message = markup.image_source_binding_message },
         .{ .source = "<row>\n  <image image=\"{atlas}\" source-x=\"0\" source-y=\"0\" source-width=\"16\" label=\"Tile\" />\n</row>", .message = markup.image_source_complete_message },
         // ...and required on the leaf: an unbound image is statically
@@ -1254,6 +1256,31 @@ test "stepper and timeline validate structure with teaching messages" {
     }
 }
 
+test "segmented-control validates as a named text control" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    const valid_sources = [_][]const u8{
+        "<row>\n  <segmented-control selected=\"true\" icon=\"settings\" on-press=\"choose\">Settings</segmented-control>\n</row>",
+        "<row>\n  <segmented-control selected=\"{active}\" label=\"View\" on-press=\"choose\" />\n</row>",
+    };
+    for (valid_sources) |source| {
+        var parser = markup.Parser.init(arena, source);
+        try testing.expectEqual(@as(?markup.MarkupErrorInfo, null), markup.validate(try parser.parse()));
+    }
+
+    const cases = [_]struct { source: []const u8, message: []const u8 }{
+        .{ .source = "<row>\n  <segmented-control icon=\"not-an-icon\">Settings</segmented-control>\n</row>", .message = markup.button_icon_message },
+        .{ .source = "<row>\n  <segmented-control>\n    <text>Settings</text>\n  </segmented-control>\n</row>", .message = markup.text_leaf_children_message },
+    };
+    for (cases) |case| {
+        var parser = markup.Parser.init(arena, case.source);
+        const info = markup.validate(try parser.parse()) orelse return error.TestUnexpectedResult;
+        try testing.expectEqualStrings(case.message, info.message);
+    }
+}
+
 test "chart and series validate structure with teaching messages" {
     var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
     defer arena_state.deinit();
diff --git a/src/primitives/canvas/ui_markup_view.zig b/src/primitives/canvas/ui_markup_view.zig
index e0fde0c15..2266dbacd 100644
--- a/src/primitives/canvas/ui_markup_view.zig
+++ b/src/primitives/canvas/ui_markup_view.zig
@@ -970,17 +970,46 @@ pub fn MarkupView(comptime ModelT: type, comptime MsgT: type) type {
             }
             if (!has_active) return self.failNode(node, markup.stepper_active_message);
 
-            const steps = try ui.arena.alloc(Ui.StepperStep, node.children.len);
-            for (node.children, 0..) |child, index| {
-                if (child.kind != .element or !std.mem.eql(u8, child.name, "step")) {
-                    return self.failNode(child, markup.stepper_children_message);
+            const is_slotted = node.children.len == 1 and node.children[0].kind == .slot_block;
+            const capture = if (is_slotted) scope.slotCapture() else null;
+            if (is_slotted and capture == null) return self.failNode(node.children[0], markup.slot_outside_template_message);
+            const step_nodes = if (capture) |captured| captured.nodes else node.children;
+            const steps = try ui.arena.alloc(Ui.StepperStep, step_nodes.len);
+            if (capture) |captured| {
+                // Slot content is authored at the use site. Temporarily
+                // restore that consumer scope so interpolated step labels
+                // see the same loop variables as a direct stepper.
+                var saved_entries: [max_scope_depth]ScopeEntry = undefined;
+                const saved_len = scope.len;
+                const saved_floor = scope.floor;
+                const saved_ctx = scope.template_ctx;
+                for (scope.entries[captured.len..saved_len], 0..) |entry, offset| saved_entries[offset] = entry;
+                scope.len = captured.len;
+                scope.floor = captured.floor;
+                scope.template_ctx = captured.template_ctx;
+                defer {
+                    for (saved_entries[0 .. saved_len - captured.len], 0..) |entry, offset| scope.entries[captured.len + offset] = entry;
+                    scope.len = saved_len;
+                    scope.floor = saved_floor;
+                    scope.template_ctx = saved_ctx;
+                }
+                for (step_nodes, 0..) |child, index| {
+                    if (child.kind != .element or !std.mem.eql(u8, child.name, "step")) return self.failNode(child, markup.stepper_children_message);
+                    for (child.attrs) |attribute| if (!std.mem.eql(u8, attribute.name, "kind")) return self.failNode(child, markup.step_attr_message);
+                    steps[index] = .{ .label = try self.interpolatedText(ui, scope, child) };
                 }
-                for (child.attrs) |attribute| {
-                    if (!std.mem.eql(u8, attribute.name, "kind")) {
-                        return self.failNode(child, markup.step_attr_message);
+            } else {
+                for (step_nodes, 0..) |child, index| {
+                    if (child.kind != .element or !std.mem.eql(u8, child.name, "step")) {
+                        return self.failNode(child, markup.stepper_children_message);
+                    }
+                    for (child.attrs) |attribute| {
+                        if (!std.mem.eql(u8, attribute.name, "kind")) {
+                            return self.failNode(child, markup.step_attr_message);
+                        }
                     }
+                    steps[index] = .{ .label = try self.interpolatedText(ui, scope, child) };
                 }
-                steps[index] = .{ .label = try self.interpolatedText(ui, scope, child) };
             }
             return ui.stepper(options, steps);
         }
@@ -1849,8 +1878,8 @@ pub fn MarkupView(comptime ModelT: type, comptime MsgT: type) type {
         /// runtime (`Cmd.imageLoad`, `fx.loadImage`,
         /// `fx.registerImageBytes`) — the id is model data, never a
         /// markup literal, and 0 draws nothing (an avatar keeps its
-        /// initials fallback). The remaining image-bearing widget
-        /// (icon-button) stays a Zig view.
+        /// initials fallback). Image-backed buttons remain a separate
+        /// asset-lifecycle proposal.
         fn applyImageAttr(self: *Self, scope: *Scope, node: markup.MarkupNode, options: *Ui.ElementOptions, attribute: markup.MarkupAttr) BuildError!void {
             if (!std.mem.eql(u8, node.name, "avatar") and !std.mem.eql(u8, node.name, "image")) {
                 return self.failVoid(node, markup.image_binding_element_message);
diff --git a/src/primitives/canvas/ui_markup_view_tests.zig b/src/primitives/canvas/ui_markup_view_tests.zig
index cbf224367..2dbb4daa9 100644
--- a/src/primitives/canvas/ui_markup_view_tests.zig
+++ b/src/primitives/canvas/ui_markup_view_tests.zig
@@ -1597,20 +1597,13 @@ test "the registry's takes-children predicate matches the interpreter's takes-ch
     }
 }
 
-/// Widget kinds deliberately NOT expressible in markup v1 — each needs
-/// something the closed grammar cannot carry, so these are written as Zig
-/// view functions instead of forcing a bad markup shape:
-/// - image, icon_button: reference image assets by runtime ImageId,
-///   which markup's literal/binding attribute values cannot express.
-///   (icon IS expressible: the built-in vector set is a closed literal
-///   vocabulary, comptime-validated.)
+/// Widget kinds deliberately NOT expressible as direct markup leaves —
+/// each is either a composite form or awaits a separate admission:
 /// - data_grid: a virtualized data grid needs per-column cell templates
 ///   (arbitrary render callbacks).
 /// - popover, menu_surface: floating surfaces anchored to runtime geometry
 ///   the static tree cannot express (dropdown-menu covers the declarative
 ///   menu case).
-/// - segmented_control: engine kind for shell chrome segments; tabs and
-///   toggle-group cover the component catalog's use cases.
 /// - chart: expressible as the `<chart>` COMPOSITE (series children whose
 ///   values bind model f32 iterables, lowered through `Ui.chart`), so no
 ///   plain element maps to the kind here — like the other composites, the
@@ -1623,9 +1616,24 @@ test "the registry's takes-children predicate matches the interpreter's takes-ch
 ///   lowered through `Ui.inputGroup`), so no plain element maps to the
 ///   kind here — like chart, the bespoke builder is the channel.
 const markup_excluded_widget_kinds = [_]canvas.WidgetKind{
-    .icon_button, .data_grid, .popover, .menu_surface, .segmented_control, .chart, .split_divider, .input_group,
+    .icon_button, .data_grid, .popover, .menu_surface, .chart, .split_divider, .input_group,
 };
 
+pub const SegmentedModel = struct {
+    mode: u8 = 1,
+};
+pub const SegmentedMsg = union(enum) { choose };
+pub const SegmentedUi = canvas.Ui(SegmentedMsg);
+const SegmentedMarkup = markup_view.MarkupView(SegmentedModel, SegmentedMsg);
+
+pub const segmented_markup_source =
+    \\<column gap="8">
+    \\  <segmented-control selected="{mode == 0}" on-press="choose">List</segmented-control>
+    \\  <segmented-control selected="{mode == 1}" icon="settings" on-press="choose">Grid</segmented-control>
+    \\  <button size="icon" icon="settings" label="Preview" on-press="choose" />
+    \\</column>
+;
+
 fn kindExpressible(kind: canvas.WidgetKind) bool {
     for (canvas.ui_markup.known_element_names) |name| {
         if (markup_view.elementKind(name) == kind) return true;
@@ -1642,6 +1650,32 @@ test "known_element_names covers every markup-expressible widget kind" {
     }
 }
 
+test "segmented-control and vector icon button build and dispatch" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    var parser = canvas.ui_markup.Parser.init(arena, segmented_markup_source);
+    try testing.expectEqual(@as(?canvas.ui_markup.MarkupErrorInfo, null), canvas.ui_markup.validate(try parser.parse()));
+
+    const model = SegmentedModel{};
+    var view = try SegmentedMarkup.init(arena, segmented_markup_source);
+    var ui = SegmentedUi.init(arena);
+    const tree = try ui.finalize(try view.build(&ui, &model));
+    const list = tree.root.children[0];
+    const grid = tree.root.children[1];
+    const preview = tree.root.children[2];
+    try testing.expectEqual(canvas.WidgetKind.segmented_control, list.kind);
+    try testing.expectEqual(canvas.WidgetKind.segmented_control, grid.kind);
+    try testing.expect(!list.state.selected);
+    try testing.expect(grid.state.selected);
+    try testing.expectEqualStrings("settings", grid.icon);
+    try testing.expectEqual(SegmentedMsg.choose, tree.msgForPointer(list.id, .up).?);
+    try testing.expectEqual(SegmentedMsg.choose, tree.msgForPointer(grid.id, .up).?);
+    try testing.expectEqual(canvas.WidgetKind.button, preview.kind);
+    try testing.expectEqualStrings("settings", preview.icon);
+    try testing.expectEqual(SegmentedMsg.choose, tree.msgForPointer(preview.id, .up).?);
+}
+
 test "every built-in component is expressible in markup" {
     for (canvas.builtin_component_kinds) |component| {
         const descriptor = canvas.builtinComponentDescriptor(component);
diff --git a/src/primitives/canvas/ui_schema.zig b/src/primitives/canvas/ui_schema.zig
index 412737feb..e3a0090b0 100644
--- a/src/primitives/canvas/ui_schema.zig
+++ b/src/primitives/canvas/ui_schema.zig
@@ -362,6 +362,9 @@ pub const elements = [_]ElementInfo{
     // line numbers or one horizontal scroll region for unwrapped lines.
     // Markdown fences use the same builder component.
     .{ .code = 70, .name = "code", .rule_hook = "code", .hit_target = false },
+    // Standalone exclusive-choice trigger. Its item collection is ordinary
+    // markup structure around these text-bearing leaves.
+    .{ .code = 71, .name = "segmented-control", .widget_kind = "segmented_control", .takes_text = true, .icon_attr = true, .a11y_name = .control },
 };
 
 // ------------------------------------------------------------- attributes
diff --git a/src/primitives/canvas/ui_schema_tests.zig b/src/primitives/canvas/ui_schema_tests.zig
index bc70e7af0..7e0dcb12d 100644
--- a/src/primitives/canvas/ui_schema_tests.zig
+++ b/src/primitives/canvas/ui_schema_tests.zig
@@ -21,7 +21,7 @@ test "registry codes are stable: assigned at birth, never renumbered or renamed"
     // (append or slot them anywhere — order carries no meaning) and pin
     // the new fingerprint ONLY for additions; renames/renumbers are
     // schema-version-bump events, not silent edits.
-    try testing.expectEqual(@as(usize, 70), schema.elements.len);
+    try testing.expectEqual(@as(usize, 71), schema.elements.len);
     try testing.expectEqual(@as(usize, 102), schema.attrs.len);
     try testing.expectEqual(@as(usize, 15), schema.events.len);
     // The element table runs through the span composite (64), the
@@ -29,7 +29,7 @@ test "registry codes are stable: assigned at birth, never renumbered or renamed"
     // runtime-image leaf (67), the video playback composite (68), and
     // the terminal leaf (69), and the reusable code composite (70).
     try testing.expectEqual(
-        @as(u64, 0x180108eb2382ba60),
+        @as(u64, 0xbb9008f3d35ecc25),
         tableFingerprint(schema.ElementInfo, &schema.elements),
     );
     // The attr table runs through the split layout-tween attributes
@@ -107,7 +107,7 @@ test "registry event scoping names registry elements" {
 test "derived name lists mirror the registry" {
     // The derivations are the vocabulary every consumer reads; hold them
     // to the registry's own predicates.
-    try testing.expectEqual(@as(usize, 56), schema.element_names.len);
+    try testing.expectEqual(@as(usize, 57), schema.element_names.len);
     for (schema.element_names) |name| {
         try testing.expect(schema.elementByName(name).?.rule_hook == null);
     }
diff --git a/src/tooling/components/identity_tests.zig b/src/tooling/components/identity_tests.zig
index 40ec36362..5a290a991 100644
--- a/src/tooling/components/identity_tests.zig
+++ b/src/tooling/components/identity_tests.zig
@@ -2,7 +2,7 @@
 //!
 //! `native eject component <name>` copies the canonical sources next to
 //! this file into an app. These tests are what keeps those copies
-//! honest: each builds the ejected form and the library form against
+//! precisely: each builds the ejected form and the library form against
 //! the same inputs and requires the two widget trees to be IDENTICAL —
 //! every id, every field, every handler — so ejecting is never a visual
 //! or behavioral change, only an ownership change. A library refactor
@@ -19,8 +19,8 @@ const testing = std.testing;
 const native_sdk = @import("native_sdk");
 const canvas = native_sdk.canvas;
 
-const stepper_component = @import("stepper.zig");
-const timeline_item_component = @import("timeline_item.zig");
+const stepper_template = @embedFile("stepper.native");
+const timeline_item_template = @embedFile("timeline-item.native");
 const timeline_template = @embedFile("timeline.native");
 
 /// A stand-in app model/message pair: the composites under test bind no
@@ -30,7 +30,7 @@ const Model = struct {};
 const Msg = union(enum) { open: u32 };
 const Ui = canvas.Ui(Msg);
 
-test "ejected stepper builds the library stepper's exact tree" {
+test "ejected stepper markup builds the library stepper's exact tree" {
     var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
     defer arena_state.deinit();
     const arena = arena_state.allocator();
@@ -46,56 +46,43 @@ test "ejected stepper builds the library stepper's exact tree" {
         };
         const library_tree = try library_ui.finalize(library_ui.stepper(.{ .active = active }, &library_steps));
 
+        const active_text = if (active == 0) "0" else if (active == 1) "1" else "3";
+        const source = "<import src=\"components/stepper.native\"/>\n<use template=\"stepper\" active=\"" ++ active_text ++ "\">" ++
+            "<step>Plan</step><step>Work</step><step>Ship</step></use>";
+        const files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/stepper.native", .source = stepper_template }};
         var ejected_ui = Ui.init(arena);
-        const ejected_steps = [_]stepper_component.Step{
-            .{ .label = labels[0] }, .{ .label = labels[1] }, .{ .label = labels[2] },
-        };
-        const ejected_tree = try ejected_ui.finalize(stepper_component.build(&ejected_ui, .{ .active = active }, &ejected_steps));
+        const ejected_tree = try buildMarkupTree(arena, &ejected_ui, source, &files);
 
         try testing.expectEqualDeep(library_tree.root, ejected_tree.root);
         try testing.expectEqualDeep(library_tree.handlers, ejected_tree.handlers);
     }
 }
 
-test "ejected timeline item builds the library item's exact tree, press handler included" {
+test "ejected timeline-item markup builds the library item's exact tree" {
     var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
     defer arena_state.deinit();
     const arena = arena_state.allocator();
 
-    const TimelineItem = timeline_item_component.TimelineItem(Msg);
-
-    // The full shape: indicator variant, description, meta, connector,
-    // selection, and a whole-item press (which grows the chevron and
-    // binds the handler on the item root).
+    // The full visual shape: indicator variant, description, meta,
+    // connector, and selection. The built-in element remains the typed
+    // event boundary; template values do not invent callback values.
     var library_ui = Ui.init(arena);
     const library_tree = try library_ui.finalize(library_ui.timelineItem(.{
-        .key = .{ .int = 7 },
         .icon = "check",
         .variant = .primary,
         .title = "Build the release",
         .description = "Compile, test, and package the app",
         .meta = "2m 14s",
         .selected = true,
-        .on_press = .{ .open = 7 },
     }));
 
+    const source = "<import src=\"components/timeline-item.native\"/>\n<use template=\"timeline-item\" title=\"Build the release\" description=\"Compile, test, and package the app\" meta=\"2m 14s\" icon=\"check\" variant=\"primary\" selected=\"true\" />";
+    const files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/timeline-item.native", .source = timeline_item_template }};
     var ejected_ui = Ui.init(arena);
-    const ejected_tree = try ejected_ui.finalize(TimelineItem.build(&ejected_ui, .{
-        .key = .{ .int = 7 },
-        .icon = "check",
-        .variant = .primary,
-        .title = "Build the release",
-        .description = "Compile, test, and package the app",
-        .meta = "2m 14s",
-        .selected = true,
-        .on_press = .{ .open = 7 },
-    }));
+    const ejected_tree = try buildMarkupTree(arena, &ejected_ui, source, &files);
 
     try testing.expectEqualDeep(library_tree.root, ejected_tree.root);
     try testing.expectEqualDeep(library_tree.handlers, ejected_tree.handlers);
-    // The press is real in both forms, not just structurally equal.
-    try testing.expectEqual(Msg{ .open = 7 }, ejected_tree.msgForPointer(ejected_tree.root.id, .up).?);
-
     // The minimal shape: dot indicator (no badge content), title only,
     // no connector, no press — the other half of every conditional.
     var minimal_library_ui = Ui.init(arena);
@@ -103,11 +90,10 @@ test "ejected timeline item builds the library item's exact tree, press handler
         .title = "Queued",
         .connector = false,
     }));
+    const minimal_source = "<import src=\"components/timeline-item.native\"/>\n<use template=\"timeline-item\" title=\"Queued\" connector=\"false\" />";
+    const minimal_files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/timeline-item.native", .source = timeline_item_template }};
     var minimal_ejected_ui = Ui.init(arena);
-    const minimal_ejected = try minimal_ejected_ui.finalize(TimelineItem.build(&minimal_ejected_ui, .{
-        .title = "Queued",
-        .connector = false,
-    }));
+    const minimal_ejected = try buildMarkupTree(arena, &minimal_ejected_ui, minimal_source, &minimal_files);
     try testing.expectEqualDeep(minimal_library.root, minimal_ejected.root);
     try testing.expectEqualDeep(minimal_library.handlers, minimal_ejected.handlers);
 }
diff --git a/src/tooling/components/stepper.native b/src/tooling/components/stepper.native
new file mode 100644
index 000000000..1bfcac81f
--- /dev/null
+++ b/src/tooling/components/stepper.native
@@ -0,0 +1,22 @@
+<!-- Your app's stepper.
+     Ejected from the Native SDK component library.
+
+     This file now belongs to your app: edit it freely, and SDK updates
+     never touch it. The template keeps the SDK stepper's typed rendering
+     and inserts the caller's step children at the same structural point:
+
+         before: <stepper active="{stage}">...</stepper>
+         after:  <import src="components/stepper.native"/>
+                 <use template="stepper" active="{stage}">...</use>
+
+     `step` remains an SDK-owned markup element. Its completed/active/
+     pending state still derives from the active index, and the slot is
+     built in the consumer's scope so loop bindings keep working.
+
+     Deleting this file costs nothing; `native eject component stepper`
+     writes it again. -->
+<template name="stepper" args="active">
+  <stepper active="{active}">
+    <slot/>
+  </stepper>
+</template>
diff --git a/src/tooling/components/stepper.zig b/src/tooling/components/stepper.zig
deleted file mode 100644
index 640669aaf..000000000
--- a/src/tooling/components/stepper.zig
+++ /dev/null
@@ -1,113 +0,0 @@
-//! Your app's stepper.
-//! Ejected from the Native SDK component library.
-//!
-//! This file now belongs to your app: edit it freely, and SDK updates
-//! never touch it. It builds the same widget tree `ui.stepper` produced
-//! at the moment it was ejected, so migrating a call site is a rename:
-//!
-//!     const stepper = @import("components/stepper.zig");
-//!
-//!     // before: ui.stepper(.{ .active = model.stage }, &steps)
-//!     // after:  stepper.build(&ui, .{ .active = model.stage }, &steps)
-//!
-//! The library form stays available — call sites you have not migrated
-//! keep rendering the stock stepper, and deleting this file costs
-//! nothing (`native eject component stepper` writes it again).
-//!
-//! The composition, in one glance: a horizontal row of steps whose
-//! completed/active/pending states derive from `Options.active`.
-//! Indicators are badges — a vector check icon for completed steps, the
-//! step number otherwise — and hairline separators connect the steps.
-//! Display-only: driving `active` belongs to the app model.
-
-const std = @import("std");
-const native_sdk = @import("native_sdk");
-const canvas = native_sdk.canvas;
-
-/// Visual state of a step, derived from its index against
-/// `Options.active`.
-pub const StepState = enum { completed, active, pending };
-
-pub const Step = struct {
-    /// Step label ("Work", "Review · round 2").
-    label: []const u8,
-};
-
-pub const Options = struct {
-    /// Index of the active step: earlier steps render completed (check
-    /// indicator), later ones pending. An index past the last step
-    /// renders every step completed.
-    active: usize = 0,
-    key: ?canvas.UiKey = null,
-    global_key: ?canvas.UiKey = null,
-    grow: f32 = 0,
-    /// Row semantics; role defaults to `list` (each step is a `listitem`
-    /// carrying its label, state, and position).
-    semantics: canvas.WidgetSemantics = .{},
-};
-
-pub fn stepState(active: usize, index: usize) StepState {
-    if (index < active) return .completed;
-    if (index == active) return .active;
-    return .pending;
-}
-
-/// Build the stepper into the app's view. `ui` is the app's typed view
-/// builder (`*canvas.Ui(Msg)`); taking it generically keeps this file
-/// independent of your app's message type.
-pub fn build(ui: anytype, options: Options, steps: []const Step) @TypeOf(ui.*).Node {
-    var semantics = options.semantics;
-    if (semantics.role == .none) semantics.role = .list;
-    const node_count = if (steps.len == 0) 0 else steps.len * 2 - 1;
-    const nodes = ui.arena.alloc(@TypeOf(ui.*).Node, node_count) catch {
-        ui.failed = true;
-        return ui.el(.row, .{ .semantics = semantics }, .{});
-    };
-    for (steps, 0..) |step, index| {
-        nodes[index * 2] = stepNode(ui, options.active, index, steps.len, step);
-        if (index + 1 < steps.len) {
-            // The connector between steps: a bare separator inside a row
-            // renders as a hairline across the space it grows into.
-            nodes[index * 2 + 1] = ui.el(.separator, .{ .grow = 1 }, .{});
-        }
-    }
-    return ui.el(.row, .{
-        .key = options.key,
-        .global_key = options.global_key,
-        .gap = 8,
-        .cross = .center,
-        .grow = options.grow,
-        .semantics = semantics,
-    }, .{nodes});
-}
-
-fn stepNode(ui: anytype, active: usize, index: usize, count: usize, step: Step) @TypeOf(ui.*).Node {
-    const state = stepState(active, index);
-    // Completed steps wear the vector `check` icon — a check text glyph
-    // is outside the bundled font's coverage and would render as a tofu
-    // box on the reference/screenshot paths.
-    const indicator = ui.el(.badge, .{
-        .variant = if (state == .pending) canvas.WidgetVariant.outline else .primary,
-        .icon = if (state == .completed) "check" else "",
-        .text = if (state == .completed) "" else ui.fmt("{d}", .{index + 1}),
-    }, .{});
-    const label = switch (state) {
-        // The active step reads bold; a single bold span is the wrapped
-        // text machinery, so the emphasis costs no second text pipeline.
-        .active => ui.paragraph(.{}, &.{.{ .text = step.label, .weight = .bold }}),
-        .completed => ui.text(.{}, step.label),
-        .pending => ui.text(.{ .style_tokens = .{ .foreground = .text_muted } }, step.label),
-    };
-    return ui.el(.row, .{
-        .key = .{ .int = @intCast(index) },
-        .gap = 6,
-        .cross = .center,
-        .selected = state == .active,
-        .semantics = .{
-            .role = .listitem,
-            .label = ui.fmt("{s} ({s})", .{ step.label, @tagName(state) }),
-            .list_item_index = @intCast(index),
-            .list_item_count = @intCast(count),
-        },
-    }, .{ indicator, label });
-}
diff --git a/src/tooling/components/timeline-item.native b/src/tooling/components/timeline-item.native
new file mode 100644
index 000000000..679778cbc
--- /dev/null
+++ b/src/tooling/components/timeline-item.native
@@ -0,0 +1,20 @@
+<!-- Your app's timeline item.
+     Ejected from the Native SDK component library.
+
+     This file now belongs to your app: edit it freely, and SDK updates
+     never touch it. The template exposes the item's markup-owned shape and
+     keeps its content and state arguments at the same element boundary:
+
+         before: <timeline-item title="Build" variant="primary" />
+         after:  <import src="components/timeline-item.native"/>
+                 <use template="timeline-item" title="Build" variant="primary" />
+
+     A call site that needs a typed `on-press` can keep using the built-in
+     `<timeline-item>` element directly; message bindings stay on elements,
+     never in a string-valued component callback.
+
+     Deleting this file costs nothing; `native eject component timeline-item`
+     writes it again. -->
+<template name="timeline-item" args="title description= meta= indicator= icon= variant=outline connector=true selected=false">
+  <timeline-item title="{title}" description="{description}" meta="{meta}" indicator="{indicator}" icon="{icon}" variant="{variant}" connector="{connector}" selected="{selected}" />
+</template>
diff --git a/src/tooling/components/timeline_item.zig b/src/tooling/components/timeline_item.zig
deleted file mode 100644
index 5e3e8815a..000000000
--- a/src/tooling/components/timeline_item.zig
+++ /dev/null
@@ -1,131 +0,0 @@
-//! Your app's timeline item.
-//! Ejected from the Native SDK component library.
-//!
-//! This file now belongs to your app: edit it freely, and SDK updates
-//! never touch it. It builds the same widget tree `ui.timelineItem`
-//! produced at the moment it was ejected, so migrating a call site is a
-//! rename (the type takes your app's message union once, because a
-//! pressable item carries a typed `on_press`):
-//!
-//!     const timeline_item = @import("components/timeline_item.zig");
-//!     const TimelineItem = timeline_item.TimelineItem(Msg);
-//!
-//!     // before: ui.timelineItem(.{ .title = run.title, .on_press = .{ .open = run.id } })
-//!     // after:  TimelineItem.build(&ui, .{ .title = run.title, .on_press = .{ .open = run.id } })
-//!
-//! The library form stays available — call sites you have not migrated
-//! keep rendering the stock item, and deleting this file costs nothing
-//! (`native eject component timeline-item` writes it again).
-//!
-//! The composition, in one glance: a leading status indicator (badge or
-//! dot, plus a hairline connector toward the next item), a
-//! title/description/meta content column, and — when pressable — a
-//! trailing chevron with `on_press` bound to the item's root, so presses
-//! on the plain text fall through to the item.
-
-const std = @import("std");
-const native_sdk = @import("native_sdk");
-const canvas = native_sdk.canvas;
-
-pub fn TimelineItem(comptime Msg: type) type {
-    return struct {
-        const Ui = canvas.Ui(Msg);
-
-        pub const Options = struct {
-            key: ?canvas.UiKey = null,
-            global_key: ?canvas.UiKey = null,
-            /// Indicator badge text ("3"); empty (with no `icon`)
-            /// renders a small dot. Prefer `icon` for symbols — text
-            /// glyphs outside the bundled font render as tofu boxes on
-            /// the reference/screenshot paths.
-            indicator: []const u8 = "",
-            /// Vector icon indicator (registry name, e.g. "check"):
-            /// drawn inside the badge with the variant's tint. Wins the
-            /// badge's content slot alongside `indicator` text.
-            icon: []const u8 = "",
-            /// Indicator color variant — map item outcomes here (primary
-            /// for done, destructive for errors, outline for stopped, ...).
-            variant: canvas.WidgetVariant = .outline,
-            title: []const u8,
-            /// Wrapped muted preview under the title.
-            description: []const u8 = "",
-            /// Muted trailing meta line ("claude · sonnet · 1m 12s").
-            meta: []const u8 = "",
-            /// Hairline connector from the indicator toward the next
-            /// item; clear it on the last item.
-            connector: bool = true,
-            /// Whole-item press: adds a trailing chevron and binds the
-            /// press to the item's root, focusable with role `listitem`.
-            /// A click anywhere on the item dispatches — presses on the
-            /// title/description/meta text fall through to the root
-            /// (dragging still selects the text).
-            on_press: ?Msg = null,
-            selected: bool = false,
-        };
-
-        pub fn build(ui: *Ui, options: Options) Ui.Node {
-            const dot = options.indicator.len == 0 and options.icon.len == 0;
-            const indicator = ui.el(.badge, .{
-                .variant = options.variant,
-                .text = options.indicator,
-                .icon = options.icon,
-                .width = if (dot) 10 else 0,
-                .height = if (dot) 10 else 0,
-            }, .{});
-            const lead = if (options.connector)
-                ui.el(.column, .{ .cross = .center, .gap = 4 }, .{
-                    indicator,
-                    ui.el(.separator, .{ .grow = 1, .width = 1 }, .{}),
-                })
-            else
-                ui.el(.column, .{ .cross = .center }, .{indicator});
-
-            const content_nodes = ui.arena.alloc(Ui.Node, 3) catch {
-                ui.failed = true;
-                return ui.el(.stack, .{}, .{});
-            };
-            content_nodes[0] = ui.paragraph(.{}, &.{.{ .text = options.title, .weight = .bold }});
-            var content_len: usize = 1;
-            if (options.description.len > 0) {
-                content_nodes[content_len] = ui.text(.{ .wrap = true, .style_tokens = .{ .foreground = .text_muted } }, options.description);
-                content_len += 1;
-            }
-            if (options.meta.len > 0) {
-                content_nodes[content_len] = ui.paragraph(.{}, &.{.{ .text = options.meta, .color = .text_muted, .scale = 0.9 }});
-                content_len += 1;
-            }
-            const content = ui.el(.column, .{ .grow = 1, .gap = 2 }, .{content_nodes[0..content_len]});
-
-            const item_semantics = canvas.WidgetSemantics{
-                .role = .listitem,
-                .label = options.title,
-                .focusable = options.on_press != null,
-            };
-            const row_children = ui.arena.alloc(Ui.Node, 3) catch {
-                ui.failed = true;
-                return ui.el(.stack, .{}, .{});
-            };
-            row_children[0] = lead;
-            row_children[1] = content;
-            var row_len: usize = 2;
-            if (options.on_press != null) {
-                row_children[row_len] = ui.text(.{ .style_tokens = .{ .foreground = .text_muted } }, "›");
-                row_len += 1;
-            }
-            const row_node = ui.el(.row, .{ .gap = 10, .padding = 8 }, .{row_children[0..row_len]});
-
-            // The press binds to the item's root: a bound handler makes
-            // the stack a hit target, and presses on the plain
-            // title/description/meta text fall through to it (dragging
-            // still selects the text). No overlay, no duplicated
-            // handlers.
-            return ui.el(.stack, .{
-                .key = options.key,
-                .global_key = options.global_key,
-                .selected = options.selected,
-                .semantics = item_semantics,
-                .on_press = options.on_press,
-            }, .{row_node});
-        }
-    };
-}
diff --git a/src/tooling/eject_components.zig b/src/tooling/eject_components.zig
index 3e10091f8..8dce90f4f 100644
--- a/src/tooling/eject_components.zig
+++ b/src/tooling/eject_components.zig
@@ -4,7 +4,7 @@
 //! The ownership model, stated once: the default is to USE the library
 //! composites and theme them through design tokens; ejecting writes the
 //! composite's canonical source into the app (`src/components/`) for the
-//! moment you need to own its shape. Only honest compositions are on the
+//! moment you need to own its shape. Only library compositions are on the
 //! menu — views the library itself builds from public primitives (rows,
 //! columns, badges, separators, text). Engine control classes (buttons,
 //! text fields, tabs, ...) are never ejectable: their behavior lives in
@@ -12,7 +12,7 @@
 //! fork.
 //!
 //! Each canonical source lives as a real file next to this one
-//! (`components/`), embedded verbatim at compile time, and held honest
+//! (`components/`), embedded verbatim at compile time, and held in parity
 //! by identity tests (`src/tooling/components/identity_tests.zig`) that
 //! build the ejected form and the library form against the same inputs
 //! and require identical widget trees. Whether a component ejects as a
@@ -25,6 +25,8 @@
 const std = @import("std");
 const buildgraph = @import("buildgraph.zig");
 
+pub const ComponentForm = enum { markup, zig };
+
 pub const Component = struct {
     /// The name `native eject component <name>` accepts (the registry
     /// element / builder-sugar name, so users name the thing they see).
@@ -36,6 +38,10 @@ pub const Component = struct {
     /// The canonical source, embedded verbatim — the identity tests keep
     /// it building the exact tree the library builds.
     source: []const u8,
+    /// The source form written into an app. This is explicit so the CLI can
+    /// refuse a future Zig-form component in a TypeScript tree rather than
+    /// violating the app-authoring rule.
+    form_kind: ComponentForm = .markup,
     /// One-line form summary for listings and the success message.
     form: []const u8,
 };
@@ -45,9 +51,10 @@ pub const Component = struct {
 pub const components = [_]Component{
     .{
         .name = "stepper",
-        .path = "src/components/stepper.zig",
-        .source = @embedFile("components/stepper.zig"),
-        .form = "Zig view function",
+        .path = "src/components/stepper.native",
+        .source = @embedFile("components/stepper.native"),
+        .form = "markup template",
+        .form_kind = .markup,
     },
     .{
         .name = "timeline",
@@ -57,9 +64,10 @@ pub const components = [_]Component{
     },
     .{
         .name = "timeline-item",
-        .path = "src/components/timeline_item.zig",
-        .source = @embedFile("components/timeline_item.zig"),
-        .form = "Zig view function",
+        .path = "src/components/timeline-item.native",
+        .source = @embedFile("components/timeline-item.native"),
+        .form = "markup template",
+        .form_kind = .markup,
     },
 };
 
@@ -168,3 +176,11 @@ test "unknown names suggest their nearest ejectable component" {
 test "the component list names every ejectable component" {
     try std.testing.expectEqualStrings("stepper, timeline, timeline-item", component_list);
 }
+
+test "current ejectable components all use the markup form" {
+    for (components) |component| {
+        try std.testing.expectEqual(ComponentForm.markup, component.form_kind);
+        try std.testing.expect(std.mem.endsWith(u8, component.path, ".native"));
+        try std.testing.expectEqualStrings("markup template", component.form);
+    }
+}
diff --git a/tools/docs_preview_scenes.zig b/tools/docs_preview_scenes.zig
index 5136c7584..f2be5392a 100644
--- a/tools/docs_preview_scenes.zig
+++ b/tools/docs_preview_scenes.zig
@@ -12,7 +12,7 @@
 //! Scenes are retained widget trees. Most are stateless: the runtime
 //! owns hover, focus, toggle, text-edit, slider, and scroll state, which
 //! is exactly the interactivity those previews expose. Scenes whose
-//! honest demo needs MODEL-owned state (accordion expansion, tab panel
+//! interactive demo needs MODEL-owned state (accordion expansion, tab panel
 //! switching, dialog dismiss/reopen, the select's anchored dropdown)
 //! declare a tiny shared mini-model (`SceneModel`) and build from it;
 //! the wasm host routes the REAL widget event dispatch (press, toggle,
@@ -152,6 +152,7 @@ pub const scenes = [_]Scene{
     .{ .name = "alert", .height = 220, .build = stateless(buildAlert) },
     .{ .name = "accordion", .height = 240, .build = buildAccordion, .model = .{ .flags = .{ true, false, false, false } } },
     .{ .name = "tabs", .height = 230, .build = buildTabs },
+    .{ .name = "segmented-control", .height = 160, .build = buildSegmentedControl },
     .{ .name = "menu", .height = 280, .build = stateless(buildMenu) },
     .{ .name = "tooltip", .height = 160, .build = stateless(buildTooltip), .hover = .{ .kind = .button } },
     .{ .name = "bubble", .height = 300, .build = stateless(buildBubble) },
@@ -218,6 +219,7 @@ pub const scenes = [_]Scene{
     heroScene("resizable-hero", buildResizableHero),
     heroScene("scroll-hero", buildScrollHero),
     .{ .name = "select-hero", .width = hero_tile_width, .height = hero_tile_height, .build = buildSelectHero, .model = .{ .open = true } },
+    heroScene("segmented-control-hero", buildSegmentedControlHero),
     heroScene("separator-hero", buildSeparatorHero),
     heroScene("sheet-hero", buildSheetHero),
     heroScene("skeleton-hero", buildSkeletonHero),
@@ -745,6 +747,17 @@ fn buildTabs(ui: *Ui, model: *const SceneModel) Node {
     });
 }
 
+fn buildSegmentedControl(ui: *Ui, model: *const SceneModel) Node {
+    const active = @min(model.index, 2);
+    return tile(ui, .{
+        ui.row(.{ .gap = 8, .cross = .center }, .{
+            ui.el(.segmented_control, .{ .text = "Day", .selected = active == 0, .on_press = .{ .select_index = 0 } }, .{}),
+            ui.el(.segmented_control, .{ .text = "Week", .selected = active == 1, .icon = "settings", .on_press = .{ .select_index = 1 } }, .{}),
+            ui.el(.segmented_control, .{ .text = "Month", .selected = active == 2, .on_press = .{ .select_index = 2 } }, .{}),
+        }),
+    });
+}
+
 fn tabTrigger(ui: *Ui, model: *const SceneModel, comptime index: u8) Node {
     return ui.el(.segmented_control, .{
         .text = tab_labels[index],
@@ -1695,6 +1708,16 @@ fn buildTabsHero(ui: *Ui) Node {
     });
 }
 
+fn buildSegmentedControlHero(ui: *Ui) Node {
+    return heroTile(ui, .{
+        ui.row(.{ .gap = 6, .cross = .center }, .{
+            ui.el(.segmented_control, .{ .text = "Day", .selected = true }, .{}),
+            ui.el(.segmented_control, .{ .text = "Week", .icon = "settings" }, .{}),
+            ui.el(.segmented_control, .{ .text = "Month" }, .{}),
+        }),
+    });
+}
+
 fn buildTextareaHero(ui: *Ui) Node {
     return heroTile(ui, .{
         ui.el(.textarea, .{ .width = 280, .height = 90, .placeholder = "Write a release note…" }, .{}),
diff --git a/tools/native-sdk/main.zig b/tools/native-sdk/main.zig
index ff397570c..1504043a5 100644
--- a/tools/native-sdk/main.zig
+++ b/tools/native-sdk/main.zig
@@ -822,6 +822,13 @@ fn runEjectComponent(io: std.Io, name: []const u8) !void {
         }
         std.process.exit(1);
     };
+    if (tooling.ts_core.detect(io) == .ts and component.form_kind == .zig) {
+        std.debug.print(
+            "cannot eject {s} into a TypeScript app as a Zig view - use the markup form ({s}) instead; app authors do not write Zig\n",
+            .{ component.name, component.form },
+        );
+        std.process.exit(1);
+    }
     tooling.eject_components.eject(io, ".", component) catch |err| switch (err) {
         error.AlreadyEjected => {
             std.debug.print("already ejected at {s} - delete it to re-eject\n", .{component.path});
diff --git a/tools/native-sdk/markup_docs.zig b/tools/native-sdk/markup_docs.zig
index a1c3ebcfb..d3a832e82 100644
--- a/tools/native-sdk/markup_docs.zig
+++ b/tools/native-sdk/markup_docs.zig
@@ -31,6 +31,7 @@ pub const element_docs = [_]Doc{
     .{ .name = "text", .doc = "Text leaf; content supports {} interpolation. Line policy via wrap: wrap=\"true\" word-wraps, wrap=\"false\" clips to one honest line. size takes the typography rungs heading|display for section headings and hero stats." },
     .{ .name = "badge", .doc = "Text leaf badge; content supports {} interpolation." },
     .{ .name = "button", .doc = "Text-bearing control; the label is the text content. Dispatch with on-press. icon draws a vector icon inline before the label (icon-only when the content is empty; give it a label) — one hit target, one enabled/disabled tint." },
+    .{ .name = "segmented-control", .doc = "Standalone exclusive-choice trigger; the label is the text content, selected marks the active item, and icon may add a vector icon. Compose items with ordinary markup, for, or a template." },
     .{ .name = "checkbox", .doc = "Text-bearing value control; the visible label is text content (or text=), bind checked, dispatch with on-toggle." },
     .{ .name = "radio", .doc = "Text-bearing single-choice value control; the visible label is text content (or text=), bind checked or selected. Selection dispatches on-change when bound, then on-toggle, then on-press for compatibility." },
     .{ .name = "toggle", .doc = "Text-bearing toggle control; the label is the text content." },
@@ -132,7 +133,7 @@ pub const attribute_docs = [_]Doc{
     .{ .name = "label", .doc = "Accessible name; when set it REPLACES the element's text as the announced name - screen readers and automation snapshots see the label, never the text it shadows." },
     .{ .name = "autofocus", .doc = "Focusable controls only: moves keyboard focus to the element when it mounts or when the value turns on (edge-triggered - holding it true never re-steals focus), revealing it through ancestor scroll regions first. For editable text, an absent selection becomes a caret collapsed at the end of the text and the editor scrolls to reveal it; an existing selection is preserved. The TEA way to focus an editor on create." },
     .{ .name = "submit-on-enter", .doc = "textarea only: true makes plain Enter dispatch on-submit while Shift+Enter inserts a newline; Cmd/Ctrl+Enter still submits. False or absent keeps the multiline default where Enter inserts and submission uses the primary chord." },
-    .{ .name = "icon", .doc = "button, toggle-button, list-item, menu-item: vector icon drawn inline (buttons/toggle-buttons before the label, list/menu items as a leading slot): a built-in name (comptime-validated against canvas.icons.known_icon_names, e.g. save, plus, refresh-cw), an app-registered app:<name>, or one {binding} resolving to such a name. Icon-only buttons when the content is empty — add a label. One hit target, one enabled/disabled tint." },
+    .{ .name = "icon", .doc = "button, toggle-button, list-item, menu-item, segmented-control: vector icon drawn inline (buttons/toggle-buttons before the label, list/menu items as a leading slot): a built-in name (comptime-validated against canvas.icons.known_icon_names, e.g. save, plus, refresh-cw), an app-registered app:<name>, or one {binding} resolving to such a name. Icon-only buttons when the content is empty — add a label. One hit target, one enabled/disabled tint." },
     .{ .name = "icon-placement", .doc = "Icon slot side on label-bearing buttons/toggle-buttons: leading (default) draws the icon before the label, trailing after it — the next-page chevron. Icon-only buttons center the glyph regardless." },
     .{ .name = "window-drag", .doc = "Marks the element as a window-drag surface (the hidden-titlebar pattern): pressing its background - or plain text/icons inside - moves the window; double-click zooms per the OS convention. Buttons and other press-claiming children inside stay clickable. macOS-only; elsewhere the press is dead space." },
     .{ .name = "overscroll", .doc = "scroll only: edge behavior of the region. none pins scrolling at the content edges (the shipped default via the ScrollPhysics.overscroll token), rubber_band lets this region bounce past them, default follows the token. Honored by the engine's scroll physics and the native OS scroller alike." },
diff --git a/tools/native-sdk/markup_lsp.zig b/tools/native-sdk/markup_lsp.zig
index 1a1a099dc..a89730562 100644
--- a/tools/native-sdk/markup_lsp.zig
+++ b/tools/native-sdk/markup_lsp.zig
@@ -947,7 +947,7 @@ test "doc tables cover every known element, attribute, and event" {
     for (ui_markup.known_element_names) |name| {
         try testing.expect(elementDoc(name) != null);
     }
-    for ([_][]const u8{ "for", "if", "else", "template", "use", "import", "slot", "markdown", "stepper", "step", "timeline", "timeline-item", "chart", "series", "context-menu", "input-group", "input-group-actions", "span", "reactions", "video" }) |name| {
+    for ([_][]const u8{ "for", "if", "else", "template", "use", "import", "slot", "markdown", "stepper", "step", "timeline", "timeline-item", "chart", "series", "context-menu", "input-group", "input-group-actions", "span", "reactions", "video", "segmented-control" }) |name| {
         try testing.expect(elementDoc(name) != null);
     }
     for (ui_markup.schema.attrs) |entry| {

From 7dc5c1ee3bd61cf3b72f3312871766f1d7281bf7 Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Wed, 2 Sep 2026 18:36:20 -0500
Subject: [PATCH 2/2] fix(markup): preserve ejected component contracts

---
 .../components/segmented-control/page.mdx     | 10 ++---
 src/primitives/canvas/ui_markup_compiled.zig  | 41 +++++++++++++++----
 .../canvas/ui_markup_compiled_tests.zig       | 24 +++++++++++
 src/primitives/canvas/ui_markup_contract.zig  |  6 +++
 .../canvas/ui_markup_contract_tests.zig       | 21 ++++++++++
 src/primitives/canvas/ui_markup_view.zig      | 21 ++++++++--
 src/tooling/components/identity_tests.zig     | 32 ++++++++++++---
 src/tooling/components/stepper.native         |  8 ++--
 src/tooling/components/timeline-item.native   |  8 ++--
 src/tooling/components/timeline.native        |  8 ++--
 10 files changed, 149 insertions(+), 30 deletions(-)

diff --git a/docs/src/app/docs/components/segmented-control/page.mdx b/docs/src/app/docs/components/segmented-control/page.mdx
index 9a62e6238..e0343730a 100644
--- a/docs/src/app/docs/components/segmented-control/page.mdx
+++ b/docs/src/app/docs/components/segmented-control/page.mdx
@@ -11,9 +11,9 @@ A standalone exclusive-choice segment. Each `segmented-control` is one named, pr
 
 ```html
 <row gap="6">
-  <segmented-control selected="{range == day}" on-press="choose_day">Day</segmented-control>
-  <segmented-control selected="{range == week}" icon="settings" on-press="choose_week">Week</segmented-control>
-  <segmented-control selected="{range == month}" on-press="choose_month">Month</segmented-control>
+  <segmented-control selected="{range == 'day'}" on-press="choose_day">Day</segmented-control>
+  <segmented-control selected="{range == 'week'}" icon="settings" on-press="choose_week">Week</segmented-control>
+  <segmented-control selected="{range == 'month'}" on-press="choose_month">Month</segmented-control>
 </row>
 ```
 
@@ -25,8 +25,8 @@ The `icon` attribute uses the same closed vector-icon vocabulary as [button](/do
 
 ```html
 <row gap="6">
-  <segmented-control size="sm" selected="{view == list}" icon="file-text" label="List" on-press="show_list" />
-  <segmented-control size="sm" selected="{view == board}" icon="settings" label="Board" on-press="show_board" />
+  <segmented-control size="sm" selected="{view == 'list'}" icon="file-text" label="List" on-press="show_list" />
+  <segmented-control size="sm" selected="{view == 'board'}" icon="settings" label="Board" on-press="show_board" />
 </row>
 ```
 
diff --git a/src/primitives/canvas/ui_markup_compiled.zig b/src/primitives/canvas/ui_markup_compiled.zig
index d758ab2c2..3a3a1e475 100644
--- a/src/primitives/canvas/ui_markup_compiled.zig
+++ b/src/primitives/canvas/ui_markup_compiled.zig
@@ -142,7 +142,9 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
             slot_nodes: []const markup.MarkupNode = &.{},
             slot_entries: []const ScopeEntry = &.{},
             SiteScope: type = void,
-
+            /// True when a value arg came from a declaration default rather
+            /// than an explicit use-site argument.
+            defaulted: bool = false,
             const Kind = enum { item, value_arg, slice_arg, slot };
         };
 
@@ -1048,6 +1050,11 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
                 inline for (0..step_nodes.len) |step_index| {
                     const child = comptime step_nodes[step_index];
                     if (comptime (child.kind != .element or !std.mem.eql(u8, child.name, "step"))) fail(child, markup.stepper_children_message);
+                    comptime {
+                        for (child.attrs) |attribute| {
+                            if (!std.mem.eql(u8, attribute.name, "kind")) fail(child, markup.step_attr_message);
+                        }
+                    }
                     steps[step_index] = .{ .label = interpolatedText(child, comptime entries[index].slot_entries, ui, model, site_scope) };
                 }
             } else {
@@ -1726,7 +1733,7 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
                 var entries: []const ScopeEntry = &.{};
                 for (specs) |spec| {
                     entries = entries ++ &[_]ScopeEntry{switch (spec.kind) {
-                        .value => .{ .name = spec.name, .kind = .value_arg, .variant = spec.variant },
+                        .value => .{ .name = spec.name, .kind = .value_arg, .variant = spec.variant, .defaulted = spec.defaulted },
                         .slice => .{ .name = spec.name, .kind = .slice_arg, .Item = spec.Item },
                     }};
                 }
@@ -1833,7 +1840,7 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
             const Leaf = comptime (OnType(Item, field_path, false) orelse fail(node, "key does not name a field on the item"));
             comptime requireVariant(bindingVariant(Leaf), &.{ .integer, .string }, node, "key fields must be integers or strings");
             const value = interpreter.valueOf(Leaf, valueOn(Item, field_path, item, ui.arena)) orelse unreachable;
-            return uiKeyFromValue(value, ui);
+            return uiKeyFromValue(value);
         }
 
         // ---------------------------------------------------- attributes
@@ -2149,21 +2156,39 @@ fn CompiledMarkupEngine(comptime ModelT: type, comptime MsgT: type, comptime res
             }
         }
 
-        fn attrKey(comptime node: markup.MarkupNode, comptime entries: []const ScopeEntry, comptime raw: []const u8, ui: *Ui, model: *const ModelT, scope: anytype, comptime message: []const u8) canvas.UiKey {
+        fn attrKey(comptime node: markup.MarkupNode, comptime entries: []const ScopeEntry, comptime raw: []const u8, ui: *Ui, model: *const ModelT, scope: anytype, comptime message: []const u8) ?canvas.UiKey {
             comptime requireVariant(exprVariant(node, entries, raw), &.{ .integer, .string }, node, message);
-            return uiKeyFromValue(evalExpr(node, entries, raw, ui, model, scope), ui);
+            const omitted_default = comptime blk: {
+                const expression = markup.parseAttrExpression(raw) orelse break :blk false;
+                if (expression != .binding) break :blk false;
+                const path = expression.binding;
+                if (interpreter.pathTail(path) != null) break :blk false;
+                const index = scopeIndex(entries, interpreter.pathHead(path)) orelse break :blk false;
+                break :blk entries[index].defaulted;
+            };
+            return optionalUiKeyFromValue(evalExpr(node, entries, raw, ui, model, scope), ui, omitted_default);
         }
 
-        fn uiKeyFromValue(value: Value, ui: *Ui) canvas.UiKey {
+        fn uiKeyFromValue(value: Value) canvas.UiKey {
+            return switch (value) {
+                .integer => |int| canvas.uiKey(@as(u64, @bitCast(int))),
+                .string => |text| canvas.uiKey(text),
+                else => unreachable,
+            };
+        }
+
+        fn optionalUiKeyFromValue(value: Value, ui: *Ui, omitted_default: bool) ?canvas.UiKey {
             return switch (value) {
                 // Keys are identity, not quantities: a negative integer
                 // id maps bijectively into the u64 key space (the
                 // interpreter's itemKey/attrKey rule), never a trap.
                 .integer => |int| canvas.uiKey(@as(u64, @bitCast(int))),
-                .string => |text| canvas.uiKey(text),
+                // Empty defaults are the template-language spelling for an
+                // omitted optional key; preserve unkeyed structural identity.
+                .string => |text| if (text.len == 0 and omitted_default) null else canvas.uiKey(text),
                 else => blk: {
                     ui.failed = true;
-                    break :blk canvas.uiKey(@as(u64, 0));
+                    break :blk null;
                 },
             };
         }
diff --git a/src/primitives/canvas/ui_markup_compiled_tests.zig b/src/primitives/canvas/ui_markup_compiled_tests.zig
index 4c3698d4b..0da5ffa0e 100644
--- a/src/primitives/canvas/ui_markup_compiled_tests.zig
+++ b/src/primitives/canvas/ui_markup_compiled_tests.zig
@@ -94,6 +94,16 @@ const InboxCompiled = canvas.CompiledMarkupView(fixture.Model, fixture.Msg, fixt
 
 const SegmentedCompiled = canvas.CompiledMarkupView(fixture.SegmentedModel, fixture.SegmentedMsg, fixture.segmented_markup_source);
 
+const EjectedStepperDefaultMarkup =
+    \\<template name="stepper" args="active key= global_key= label=">
+    \\  <stepper active="{active}" key="{key}" global-key="{global_key}" label="{label}">
+    \\    <slot/>
+    \\  </stepper>
+    \\</template>
+    \\<use template="stepper" active="1"><step>Plan</step><step>Ship</step></use>
+;
+const EjectedStepperDefaultCompiled = canvas.CompiledMarkupView(fixture.TemplateModel, fixture.TemplateMsg, EjectedStepperDefaultMarkup);
+
 test "compiled segmented-control and vector icon button match the interpreter" {
     var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
     defer arena_state.deinit();
@@ -109,6 +119,20 @@ test "compiled segmented-control and vector icon button match the interpreter" {
     try testing.expectEqualStrings("settings", compiled.root.children[2].icon);
 }
 
+test "compiled ejected stepper defaults preserve unkeyed identity" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const model = fixture.TemplateModel{};
+    const labels = [_]TemplateUi.StepperStep{ .{ .label = "Plan" }, .{ .label = "Ship" } };
+
+    var library_ui = TemplateUi.init(arena);
+    const library = try library_ui.finalize(library_ui.stepper(.{ .active = 1 }, &labels));
+    var compiled_ui = TemplateUi.init(arena);
+    const compiled = try compiled_ui.finalize(EjectedStepperDefaultCompiled.build(&compiled_ui, &model));
+    try testing.expectEqualDeep(library.root, compiled.root);
+}
+
 const zero_card_padding_markup =
     \\<card padding="0">
     \\  <text>Flush</text>
diff --git a/src/primitives/canvas/ui_markup_contract.zig b/src/primitives/canvas/ui_markup_contract.zig
index 743180ec7..1ab254b6d 100644
--- a/src/primitives/canvas/ui_markup_contract.zig
+++ b/src/primitives/canvas/ui_markup_contract.zig
@@ -1439,6 +1439,12 @@ const Checker = struct {
             }
         }
         for (node.children) |child| {
+            if (child.kind == .slot_block) {
+                // Ejected steppers pass their actual children through the
+                // slot. Check those children in the consumer's scope.
+                try self.checkSlot(child);
+                continue;
+            }
             for (child.children) |run| {
                 if (run.kind == .text) try self.checkTextRun(run);
             }
diff --git a/src/primitives/canvas/ui_markup_contract_tests.zig b/src/primitives/canvas/ui_markup_contract_tests.zig
index 428478522..5a377702d 100644
--- a/src/primitives/canvas/ui_markup_contract_tests.zig
+++ b/src/primitives/canvas/ui_markup_contract_tests.zig
@@ -879,6 +879,27 @@ test "segmented-control bindings and messages check through the model contract"
     try testing.expectEqual(null, try contract.checkDocument(arena, document, &model_contract, &usage));
 }
 
+test "the contract checker validates stepper slot content in the consumer scope" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    const document = try parseFixture(arena,
+        \\<template name="stepper" args="active">
+        \\  <stepper active="{active}">
+        \\    <slot/>
+        \\  </stepper>
+        \\</template>
+        \\<row>
+        \\  <use template="stepper" active="{count}">
+        \\    <step>{missing}</step>
+        \\  </use>
+        \\</row>
+    );
+    const message = (try contractMessage(arena, document, null)).?;
+    try testing.expect(std.mem.startsWith(u8, message, contract.binding_model_message));
+}
+
 // ------------------------------------------------------------ dead state
 
 test "dead state warns on unbound model state and undispatched Msg tags" {
diff --git a/src/primitives/canvas/ui_markup_view.zig b/src/primitives/canvas/ui_markup_view.zig
index 2266dbacd..1c42c2911 100644
--- a/src/primitives/canvas/ui_markup_view.zig
+++ b/src/primitives/canvas/ui_markup_view.zig
@@ -96,6 +96,7 @@ pub fn MarkupView(comptime ModelT: type, comptime MsgT: type) type {
         const ScopeEntry = struct {
             name: []const u8,
             payload: Payload,
+            defaulted: bool = false,
 
             const Payload = union(enum) {
                 item: struct { type_index: usize, ptr: *const anyopaque },
@@ -1630,7 +1631,11 @@ pub fn MarkupView(comptime ModelT: type, comptime MsgT: type) type {
                     }
                     break :blk .{ .value = literalValue(default) };
                 } else return self.failNode(node, markup.use_missing_arg_message);
-                scope.entries[saved_len + arg_count] = .{ .name = arg.name, .payload = payload };
+                scope.entries[saved_len + arg_count] = .{
+                    .name = arg.name,
+                    .payload = payload,
+                    .defaulted = node.attrEntry(arg.name) == null and arg.default != null,
+                };
                 arg_count += 1;
             }
             // The slot capture: the use-site children plus the scope state
@@ -2100,13 +2105,23 @@ pub fn MarkupView(comptime ModelT: type, comptime MsgT: type) type {
             }
         }
 
-        fn attrKey(self: *Self, scope: *Scope, node: markup.MarkupNode, attribute: markup.MarkupAttr) BuildError!canvas.UiKey {
+        fn attrKey(self: *Self, scope: *Scope, node: markup.MarkupNode, attribute: markup.MarkupAttr) BuildError!?canvas.UiKey {
+            const omitted_default = switch (markup.attrTyped(attribute)) {
+                .binding => |path| if (scope.lookup(pathHead(path))) |entry|
+                    entry.defaulted and pathTail(path) == null
+                else
+                    false,
+                else => false,
+            };
             const value = try self.evalAttrExpression(scope, node, attribute);
             return switch (value) {
                 // Bijective like itemKey: a negative integer key is a
                 // distinct identity, never a trap.
                 .integer => |int| canvas.uiKey(@as(u64, @bitCast(int))),
-                .string => |text| canvas.uiKey(text),
+                // Empty defaults are the template-language spelling for an
+                // omitted optional key. This lets ejected templates forward
+                // key/global-key without changing unkeyed identity.
+                .string => |text| if (text.len == 0 and omitted_default) null else canvas.uiKey(text),
                 else => self.failKey(node, "keys must be integers or strings"),
             };
         }
diff --git a/src/tooling/components/identity_tests.zig b/src/tooling/components/identity_tests.zig
index 5a290a991..b1196c070 100644
--- a/src/tooling/components/identity_tests.zig
+++ b/src/tooling/components/identity_tests.zig
@@ -44,10 +44,15 @@ test "ejected stepper markup builds the library stepper's exact tree" {
         const library_steps = [_]Ui.StepperStep{
             .{ .label = labels[0] }, .{ .label = labels[1] }, .{ .label = labels[2] },
         };
-        const library_tree = try library_ui.finalize(library_ui.stepper(.{ .active = active }, &library_steps));
+        const library_tree = try library_ui.finalize(library_ui.stepper(.{
+            .active = active,
+            .key = canvas.uiKey("pipeline"),
+            .global_key = canvas.uiKey("pipeline-global"),
+            .semantics = .{ .label = "Pipeline" },
+        }, &library_steps));
 
         const active_text = if (active == 0) "0" else if (active == 1) "1" else "3";
-        const source = "<import src=\"components/stepper.native\"/>\n<use template=\"stepper\" active=\"" ++ active_text ++ "\">" ++
+        const source = "<import src=\"components/stepper.native\"/>\n<use template=\"stepper\" active=\"" ++ active_text ++ "\" key=\"pipeline\" global_key=\"pipeline-global\" label=\"Pipeline\">" ++
             "<step>Plan</step><step>Work</step><step>Ship</step></use>";
         const files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/stepper.native", .source = stepper_template }};
         var ejected_ui = Ui.init(arena);
@@ -58,6 +63,21 @@ test "ejected stepper markup builds the library stepper's exact tree" {
     }
 }
 
+test "ejected stepper defaults preserve the library's unkeyed identity" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    const source = "<import src=\"components/stepper.native\"/>\n<use template=\"stepper\" active=\"1\"><step>Plan</step><step>Ship</step></use>";
+    const files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/stepper.native", .source = stepper_template }};
+    var library_ui = Ui.init(arena);
+    const labels = [_]Ui.StepperStep{ .{ .label = "Plan" }, .{ .label = "Ship" } };
+    const library_tree = try library_ui.finalize(library_ui.stepper(.{ .active = 1 }, &labels));
+    var ejected_ui = Ui.init(arena);
+    const ejected_tree = try buildMarkupTree(arena, &ejected_ui, source, &files);
+    try testing.expectEqualDeep(library_tree.root, ejected_tree.root);
+}
+
 test "ejected timeline-item markup builds the library item's exact tree" {
     var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
     defer arena_state.deinit();
@@ -68,6 +88,8 @@ test "ejected timeline-item markup builds the library item's exact tree" {
     // event boundary; template values do not invent callback values.
     var library_ui = Ui.init(arena);
     const library_tree = try library_ui.finalize(library_ui.timelineItem(.{
+        .key = canvas.uiKey("item"),
+        .global_key = canvas.uiKey("item-global"),
         .icon = "check",
         .variant = .primary,
         .title = "Build the release",
@@ -76,7 +98,7 @@ test "ejected timeline-item markup builds the library item's exact tree" {
         .selected = true,
     }));
 
-    const source = "<import src=\"components/timeline-item.native\"/>\n<use template=\"timeline-item\" title=\"Build the release\" description=\"Compile, test, and package the app\" meta=\"2m 14s\" icon=\"check\" variant=\"primary\" selected=\"true\" />";
+    const source = "<import src=\"components/timeline-item.native\"/>\n<use template=\"timeline-item\" title=\"Build the release\" description=\"Compile, test, and package the app\" meta=\"2m 14s\" icon=\"check\" variant=\"primary\" selected=\"true\" key=\"item\" global_key=\"item-global\" />";
     const files = [_]canvas.ui_markup.SourceFile{.{ .path = "components/timeline-item.native", .source = timeline_item_template }};
     var ejected_ui = Ui.init(arena);
     const ejected_tree = try buildMarkupTree(arena, &ejected_ui, source, &files);
@@ -126,9 +148,9 @@ test "the ejected timeline template builds the library <timeline> element's exac
         \\  <timeline-item title="Building" meta="just now" connector="false" />
         \\
     ;
-    const element_source = "<timeline gap=\"4\" label=\"Activity\">\n" ++ items ++ "</timeline>\n";
+    const element_source = "<timeline gap=\"4\" label=\"Activity\" key=\"ledger\" global-key=\"ledger-global\">\n" ++ items ++ "</timeline>\n";
     const template_source = "<import src=\"components/timeline.native\"/>\n" ++
-        "<use template=\"timeline\" gap=\"4\" label=\"Activity\">\n" ++ items ++ "</use>\n";
+        "<use template=\"timeline\" gap=\"4\" label=\"Activity\" key=\"ledger\" global_key=\"ledger-global\">\n" ++ items ++ "</use>\n";
     const files = [_]canvas.ui_markup.SourceFile{
         .{ .path = "components/timeline.native", .source = timeline_template },
     };
diff --git a/src/tooling/components/stepper.native b/src/tooling/components/stepper.native
index 1bfcac81f..7b2862638 100644
--- a/src/tooling/components/stepper.native
+++ b/src/tooling/components/stepper.native
@@ -11,12 +11,14 @@
 
      `step` remains an SDK-owned markup element. Its completed/active/
      pending state still derives from the active index, and the slot is
-     built in the consumer's scope so loop bindings keep working.
+     built in the consumer's scope so loop bindings keep working. The
+     `global_key` template arg uses an underscore because template args are
+     binding names; it forwards to the element's `global-key` attribute.
 
      Deleting this file costs nothing; `native eject component stepper`
      writes it again. -->
-<template name="stepper" args="active">
-  <stepper active="{active}">
+<template name="stepper" args="active key= global_key= label=">
+  <stepper active="{active}" key="{key}" global-key="{global_key}" label="{label}">
     <slot/>
   </stepper>
 </template>
diff --git a/src/tooling/components/timeline-item.native b/src/tooling/components/timeline-item.native
index 679778cbc..45c214c04 100644
--- a/src/tooling/components/timeline-item.native
+++ b/src/tooling/components/timeline-item.native
@@ -11,10 +11,12 @@
 
      A call site that needs a typed `on-press` can keep using the built-in
      `<timeline-item>` element directly; message bindings stay on elements,
-     never in a string-valued component callback.
+     never in a string-valued component callback. The `global_key` template
+     arg uses an underscore because template args are binding names; it
+     forwards to the element's `global-key` attribute.
 
      Deleting this file costs nothing; `native eject component timeline-item`
      writes it again. -->
-<template name="timeline-item" args="title description= meta= indicator= icon= variant=outline connector=true selected=false">
-  <timeline-item title="{title}" description="{description}" meta="{meta}" indicator="{indicator}" icon="{icon}" variant="{variant}" connector="{connector}" selected="{selected}" />
+<template name="timeline-item" args="title description= meta= indicator= icon= variant=outline connector=true selected=false key= global_key=">
+  <timeline-item title="{title}" description="{description}" meta="{meta}" indicator="{indicator}" icon="{icon}" variant="{variant}" connector="{connector}" selected="{selected}" key="{key}" global-key="{global_key}" />
 </template>
diff --git a/src/tooling/components/timeline.native b/src/tooling/components/timeline.native
index d84ea105e..f57264995 100644
--- a/src/tooling/components/timeline.native
+++ b/src/tooling/components/timeline.native
@@ -16,12 +16,14 @@
      are only reachable through <use>, so the built-in <timeline> element
      keeps meaning what it always did at call sites you have not
      migrated. <timeline-item> children work unchanged inside the <use> -
-     they land at the <slot/> below.
+     they land at the <slot/> below. The `global_key` template arg uses an
+     underscore because template args are binding names; it forwards to the
+     element's `global-key` attribute.
 
      Deleting this file costs nothing; `native eject component timeline`
      writes it again. -->
-<template name="timeline" args="gap=0 grow=0 label=">
-  <column role="list" gap="{gap}" grow="{grow}" label="{label}">
+<template name="timeline" args="gap=0 grow=0 label= key= global_key=">
+  <column role="list" gap="{gap}" grow="{grow}" label="{label}" key="{key}" global-key="{global_key}">
     <slot/>
   </column>
 </template>