From 18ef03510621d04a14942cd375d358f466652366 Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 15:36:16 +0900
Subject: [PATCH 1/8] docs(widgets): add the v0 textfield element page

---
 docs/widgets/drafts/v0/README.md             |   1 +
 docs/widgets/drafts/v0/elements/textfield.md | 276 +++++++++++++++++++
 2 files changed, 277 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/elements/textfield.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index dbbb2a4..59eb9bb 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -20,6 +20,7 @@ No later language generation inherits these names or contracts by default.
 |---|---|---|---|---|
 | [`<button>`](elements/button.md) | None | Built-in base catalogue during incubation | Control taxonomy and some state semantics unsettled | Checked action control and browser realization implemented; known composition and accessibility gaps documented |
 | [`<scroll>`](elements/scroll.md) | None | Built-in base catalogue during incubation | No accepted widget RFC | Element and Play behavior implemented; static preview pose proposed |
+| [`<textfield>`](elements/textfield.md) | None | Built-in base catalogue during incubation | Renamed from `<text-field>` in the v0 catalogue; no accepted widget RFC | Checked controlled promotion, browser realization, and Play draft/IME mechanics implemented; labelling and validation gaps documented |
 | [`<icon>`](elements/icon.md) | [Icon font](integrations/icon-font.md) | Built-in Lucide family and local families implemented | Font-only realization selected before v1; permanent resource model open | Checked token, strict WOFF2 pipeline, host resources, and browser realization implemented |
 | [`<img>`](elements/img.md) | None | Built-in base catalogue during incubation | Renamed from `<image>` in the v0 catalogue; no accepted widget RFC | Typed asset and accessibility contract plus browser Editor/Play realization implemented |
 | [`<view>`](elements/view.md) | None | Built-in base catalogue during incubation | Neutral container implemented; semantic role taxonomy unsettled | Checker/runtime/browser realization implemented; known ARIA defects documented |
diff --git a/docs/widgets/drafts/v0/elements/textfield.md b/docs/widgets/drafts/v0/elements/textfield.md
new file mode 100644
index 0000000..593f165
--- /dev/null
+++ b/docs/widgets/drafts/v0/elements/textfield.md
@@ -0,0 +1,276 @@
+# `<textfield>`
+
+- **Status:** Implemented controlled text input; visible labelling and richer input semantics unsettled
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Element
+- **Facets:** None
+- **Availability:** Built-in base catalog; currently project-pinned during incubation
+- **Decision:** Renamed from `<text-field>` in base catalog 0.2.0; no accepted widget RFC
+- **Specification:** Pre-specification; controlled draft semantics implemented
+- **Implementation:** Checker, Core semantic view, browser Editor, and Play implemented
+- **Owners:** Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+`<textfield>` declares a single-line text input whose draft value is
+application state. It is a catalog element, not a user-authored component, and
+source cannot invent its properties or events. It takes no children.
+
+The current base catalog is stored with the Instagram project while Uhura is
+incubating. Calling the element built-in describes its authoring and checking
+role; it does not yet mean that a globally packaged catalog exists.
+
+The spelling is deliberate and unhyphenated. Base catalog 0.1.0 shipped
+`<text-field>`; catalog 0.2.0 renamed it to `<textfield>` in the same change
+that renamed `<image>` to `<img>`. The old spelling is not a compatibility
+alias: the checker rejects `<text-field>` as an unknown element and attaches a
+migration note naming the new spelling. A golden rejection pins that exact
+diagnostic.
+
+## Why Uhura needs an explicit textfield element
+
+HTML's [`input`](https://html.spec.whatwg.org/multipage/input.html#the-input-element)
+is uncontrolled by default: the DOM owns the draft, and application state only
+learns about it through events the author chose to wire. Frameworks then layer
+conventions on top. React's
+[controlled input](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)
+convention — bind `value`, handle `onChange` — is enforced only at runtime: a
+`value` without a change handler produces a console warning and a field that
+silently ignores typing. Nothing in the type system or build distinguishes a
+controlled input from a forgotten handler.
+
+Uhura promotes that convention into a checked catalog contract. The catalog
+declares the element controlled — binding `value` obligates handling
+`on:change` — and the checker rejects the violation statically as
+`UH5008 markup/controlled-promotion`. The obligation is data in the catalog,
+not a rule hard-coded for one element, so future controlled elements inherit
+the same mechanism. This buys:
+
+- **No controlled/uncontrolled ambiguity.** A `value` binding is a promise
+  that the machine owns the draft; the compiler holds the author to it before
+  anything renders.
+- **Deterministic replay.** Every keystroke the application sees is a `change`
+  event carrying `value: text` through the ordinary event pipeline. The draft
+  lives in Uhura state, so traces and replays reproduce typing exactly; there
+  is no shadow DOM-owned draft that a replay cannot observe.
+- **Portable semantics.** A non-web renderer receives a label, placeholder,
+  disabled flag, and two events — not a DOM idiom. Flutter's
+  [`TextField`](https://api.flutter.dev/flutter/material/TextField-class.html)
+  with an explicit controller reflects the same judgment that draft ownership
+  must be explicit rather than ambient.
+
+CSS keeps owning size, spacing, borders, and typography. `<textfield>` exists
+because draft ownership, change delivery, and submit gestures are semantic
+capabilities rather than aesthetics.
+
+## Current semantic contract
+
+Real usage from the Instagram comments composer:
+
+```uhura
+<textfield value={draft} label="Add a comment" placeholder="Add a comment…"
+           disabled={comment-pending}
+           on:change={emit composer-changed()}
+           on:submit={emit submit-requested()} />
+```
+
+| Contract | Current behavior |
+|---|---|
+| Class | `interactive` |
+| Children | None |
+| `value` | Optional `text`; binding it promotes the field to controlled and obligates `on:change` |
+| `placeholder` | Optional `text` |
+| `label` | Required `text`; the accessible name |
+| `disabled` | Optional `bool` |
+| `class` | Universal, CSS-owned class list |
+| `change` | Input event carrying `value: text`; fires per committed edit, one per IME composition |
+| `submit` | Input event with no carried payload; fired by the Enter gesture when bound |
+| Nesting | Interactive class forbids interactive descendants; moot here because children are closed |
+
+The carried `value` reaches the machine through signature coverage rather than
+authored arguments: `on:change={emit composer-changed()}` is legal when the
+machine declares `on composer-changed(value: text)`, because authored emit
+arguments and renderer-carried fields must jointly cover the handler
+signature. The corpus uses exactly this shape in all four current occurrences
+(search query, caption, alternative text, and comment composer).
+
+Uhura's `change` is HTML's `input`, not HTML's blur-time `change`: it fires on
+each committed edit. During IME composition the renderer buffers locally and
+emits a single `change` at `compositionend`.
+
+`submit` is a gesture, not a form model. Enter emits the bound descriptor and
+suppresses the platform default; when `on:submit` is absent, Enter does
+nothing semantic. An Enter that commits an IME conversion is never a submit
+gesture; the browser Play policy checks both `isComposing` and the WebKit
+keyCode 229 tell.
+
+## Draft ownership
+
+Core owns the draft; the renderer owns caret and IME. The bound `value`
+expression is the single source of truth: the typical handler stores the
+carried text (`set query = value`), and Core echoes it back through the
+semantic view. A handler that discards the carried value produces a field that
+visibly reverts — that is the contract working, not a renderer bug.
+
+The browser Play policy keeps typing and asynchronous state changes from
+corrupting each other. Per field, it counts in-flight `change` emissions that
+have not yet been stepped; while the count is nonzero, an externally computed
+value never applies directly — it is stashed, and the last stashed value wins
+only once typing settles and Core did not echo the draft back meanwhile. A
+tick-scheduled outcome landing mid-typing therefore cannot eat keystrokes.
+Field state is keyed by the input element in a `WeakMap`, so teardown is
+automatic and a remounted field starts fresh.
+
+Editor previews are inert by construction: the read-only renderer facade is
+built without a textfield controller, and the realized input is additionally
+marked read-only. Nothing typed into a preview can exist, and no `change` or
+`submit` can be emitted from a board.
+
+## Accessibility and validation
+
+The checker enforces, with golden or corpus coverage:
+
+- catalog closure — unknown properties and events on `<textfield>` are
+  rejected, and `on:` bindings are only legal where the catalog declares them;
+- `label` is required (`UH5004 markup/missing-required-prop`);
+- the children model is `none`;
+- controlled promotion — `value` without `on:change` is
+  `UH5008 markup/controlled-promotion`; and
+- legacy `<text-field>` is rejected with a rename note, not aliased.
+
+The browser realization maps `label` to `aria-label` on the inner native
+input and `placeholder` to the native attribute. Known accessibility gaps,
+stated honestly:
+
+- There is no visible label. `aria-label` names the field for assistive
+  technology only, while the placeholder disappears as soon as the user
+  types. The WAI guidance treats visible
+  [labels](https://www.w3.org/WAI/tutorials/forms/labels/) as the default and
+  hidden naming as the exception; the current contract inverts that and has
+  no `<label>`-style association, heading fallback, or described-by channel.
+- There is no error, validity, or description semantic: no invalid state, no
+  `aria-describedby` equivalent, no required-field marker.
+- `disabled` maps to the native disabled state, which removes the field from
+  the focus order; a read-only-but-focusable pose does not exist.
+- The checker validates that `label` is bound, not that its text is
+  non-empty or useful.
+
+The inner input is mechanic DOM, marked `data-uh-mechanic="input"` — it is
+created by the property applier, is not a semantic child, never appears as a
+realization path segment, and reconciliation deliberately leaves it in place
+when semantic children are swept. Renderer policy tests pin this.
+
+## Rendering and platform behavior
+
+Browser Editor and Play realize the element as a `div` with class
+`uh-textfield` (plus authored classes) wrapping one native
+`input[type=text]`:
+
+```html
+<div class="uh-textfield authored-classes">
+  <input type="text" data-uh-mechanic="input" aria-label="…" placeholder="…">
+</div>
+```
+
+Play wires the input to the textfield controller and applies Core's draft
+through it; Editor sets the input read-only and applies the value directly.
+The base stylesheet gives the input a minimal bordered treatment; everything
+visual beyond that is authored CSS on the wrapper and input.
+
+A native renderer may realize the contract with its platform text-input
+primitive. It must reproduce the observable semantics — accessible name,
+per-edit `change` with a single emission per composed sequence, the Enter
+submit gesture, and external-value application that never destroys
+uncommitted typing — or reject the capability honestly. Caret ownership,
+selection, autocorrect, keyboard type, and IME presentation remain renderer
+and platform concerns unless separately promoted into portable contracts.
+
+## Motion
+
+`<textfield>` defines no semantic motion, transition, or completion event.
+Caret blinking, focus rings, and platform keyboard animations are renderer
+and platform presentation.
+
+## Conformance
+
+Existing executable coverage proves:
+
+- the base catalog exposes `textfield` as a childless interactive element
+  with `value`, `placeholder`, required `label`, `disabled`, `change`
+  carrying one `text` field, and `submit`;
+- the catalog's controlled declaration is `value` → `change`, loaded and
+  asserted by the contract corpus;
+- binding `value` without `on:change` produces the pinned `UH5008` golden;
+- `<text-field>` produces the pinned `UH5001` golden with the rename note;
+- the complete Instagram corpus checks and lowers with `textfield` semantic
+  nodes;
+- Editor and Play realize the same `uh-textfield` structure, the inner input
+  is mechanic DOM excluded from semantic realization, and the Editor
+  realization stays inert.
+
+A durable support claim additionally requires conformance coverage for:
+
+- the in-flight counter and stash race: external values landing mid-typing,
+  Core echoing versus replacing the draft, and settlement ordering;
+- IME composition in a real browser, including the WebKit
+  Enter-after-compositionend behavior the code special-cases;
+- `submit` with and without a bound descriptor, and Enter during
+  composition;
+- `disabled` interaction and focus-order behavior;
+- an unbound-`value` field's behavior, once its semantics are decided;
+- accessibility-tree assertions rather than attribute assertions alone; and
+- equivalent semantics or an honest unsupported-capability diagnostic in
+  non-browser renderers.
+
+The Play textfield mechanics currently have no dedicated unit test; the
+in-flight, stash, and composition invariants are documented and exercised
+only indirectly.
+
+## Decisions and open questions
+
+This page is part of the v0 element documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC or
+versioned specification. The `§10` cited by the catalog and the checker
+diagnostic is the spike design's semantic-element-catalog section, not a
+section of a versioned language specification.
+
+Known gaps and open questions:
+
+1. The catalog does not require `value`, but the runtime has no uncontrolled
+   draft semantics: an unbound field's typed text survives only until the
+   next reconciliation applies the evaluated (empty) value. Whether `value`
+   becomes required, or an uncontrolled mode becomes real, is undecided.
+2. Whether the contract needs a visible-label mechanism instead of
+   `aria-label`-only naming, and how that composes with authored layout.
+3. Whether input purposes (password, email, number, search), autocomplete
+   semantics, and keyboard hints become checked semantic properties or stay
+   renderer policy.
+4. Multiline input is not covered; a text area is a distinct children/sizing
+   contract, not a `textfield` flag.
+5. Validation, error presentation, described-by, and required-field semantics
+   have no owner.
+6. Whether `submit` should relate to a future form or field-group concept or
+   remain a per-field Enter gesture.
+7. Selection, caret position, and programmatic focus are renderer-owned
+   today; a portable focus or selection intent is a separate capability.
+8. The per-edit `change` cadence versus a settled/blur cadence is
+   implementation-proven but not adjudicated for non-browser renderers.
+
+Current implementation references:
+
+- [Base catalog declaration](../../../../../examples/instagram/client/catalog/base.toml)
+- [Catalog and markup checking](../../../../../crates/uhura-check/src/markup.rs)
+- [Catalog controlled-promotion schema](../../../../../crates/uhura-check/src/catalog.rs)
+- [Play textfield mechanics](../../../../../web/src/play/textfield.ts)
+- [Browser property mapping](../../../../../web/src/renderer/appliers.ts)
+- [Shared browser reconciliation](../../../../../web/src/renderer/reconciler.ts)
+- [Read-only Editor renderer](../../../../../web/src/renderer/editor.ts)
+- [Renderer policy tests](../../../../../web/src/renderer/tests/policies.test.ts)
+- [Contract corpus tests](../../../../../crates/uhura-check/tests/contracts_corpus.rs)
+- [Golden rejections](../../../../../crates/uhura-tests/goldens/m2/)
+- [Current Instagram composer usage](../../../../../examples/instagram/client/surfaces/comments-sheet.uhura)
+- [Specification router](../../../../spec/README.md)

From 44887f2256a5d1dcb321c89aa0851ab4490fb29e Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 15:58:07 +0900
Subject: [PATCH 2/8] docs(widgets): add the v0 region element page

---
 docs/widgets/drafts/v0/README.md          |   1 +
 docs/widgets/drafts/v0/elements/region.md | 240 ++++++++++++++++++++++
 2 files changed, 241 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/elements/region.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index 59eb9bb..bdf1c71 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -24,6 +24,7 @@ No later language generation inherits these names or contracts by default.
 | [`<icon>`](elements/icon.md) | [Icon font](integrations/icon-font.md) | Built-in Lucide family and local families implemented | Font-only realization selected before v1; permanent resource model open | Checked token, strict WOFF2 pipeline, host resources, and browser realization implemented |
 | [`<img>`](elements/img.md) | None | Built-in base catalogue during incubation | Renamed from `<image>` in the v0 catalogue; no accepted widget RFC | Typed asset and accessibility contract plus browser Editor/Play realization implemented |
 | [`<view>`](elements/view.md) | None | Built-in base catalogue during incubation | Neutral container implemented; semantic role taxonomy unsettled | Checker/runtime/browser realization implemented; known ARIA defects documented |
+| [`<region>`](elements/region.md) | None | Built-in base catalogue during incubation | Activation semantics implemented; role taxonomy and keyboard equivalence unsettled | Checked one-child activation area, supplementary reachability, and browser realization implemented; focus-order and role gaps documented |
 
 ## Integrations
 
diff --git a/docs/widgets/drafts/v0/elements/region.md b/docs/widgets/drafts/v0/elements/region.md
new file mode 100644
index 0000000..4e3dace
--- /dev/null
+++ b/docs/widgets/drafts/v0/elements/region.md
@@ -0,0 +1,240 @@
+# `<region>`
+
+- **Status:** Implemented semantic activation area; role taxonomy and keyboard equivalence unsettled
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Element
+- **Facets:** None
+- **Availability:** Built-in base catalog; currently project-pinned during incubation
+- **Decision:** Current spike design; no accepted widget RFC
+- **Specification:** Pre-specification; activation semantics implemented
+- **Implementation:** Checker, Core semantic view, browser Editor, and Play implemented
+- **Owners:** Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+`<region>` declares a semantic activation area: a labelled, focusable wrapper
+that makes exactly one child element activatable. It is a catalog element, not
+a user-authored component, and source cannot invent its properties or events.
+
+The current base catalog is stored with the Instagram project while Uhura is
+incubating. Calling the element built-in describes its authoring and checking
+role; it does not yet mean that a globally packaged catalog exists.
+
+## Why Uhura needs an explicit region element
+
+The web's ambient answer to "make this area clickable" is `onclick` on a
+`div`. That idiom is an accessibility failure by default: the div has no role,
+no accessible name, no focusability, and no keyboard activation. The ARIA
+Authoring Practices [button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
+exists precisely because retrofitting those four properties onto a generic
+container is easy to forget and hard to audit.
+
+Uhura removes the retrofit entirely by making the failure inexpressible:
+
+- **Layout elements can never take handlers.** Binding `on:` to a `<view>` is
+  rejected as `UH5002 markup/event-not-declared`, and the diagnostic
+  explicitly steers the author: *"`on:` never attaches to layout elements —
+  wrap the content in `<region>`"*. The golden rejection
+  `reject-event-on-layout` pins that diagnostic. There is no div-onclick to
+  misuse.
+- **Activation implies a name.** `label` is required, so an activatable area
+  without an accessible name fails checking (`UH5004
+  markup/missing-required-prop`) before anything renders.
+- **Activation implies keyboard access.** The Play renderer gives every
+  region `role="button"`, `tabindex="0"`, and Enter/Space activation — the
+  author cannot opt out of focusability by omission.
+- **Redundant gestures must have a first-class path.** A gesture-only
+  affordance (Instagram's double-tap-to-like) is marked `supplementary`, and
+  the checker requires the same machine event to also be emitted from a
+  focusable element in the same definition (`UH5020
+  markup/supplementary-unreachable`). WCAG's
+  [pointer gesture guidance](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html)
+  asks for exactly this single-pointer/keyboard alternative; Uhura makes the
+  omission a compile error rather than an audit finding.
+
+`<button>` remains the element for a self-contained action control with
+content children. `<region>` exists for the wrapper case: an area of existing
+markup — an author row, a media block, a metadata line — whose activation is a
+navigation or gesture semantic layered over content. CSS keeps owning all of
+its appearance.
+
+## Current semantic contract
+
+Real usage from the Instagram post card (rendered by the feed page):
+
+```uhura
+<region label="View profile" on:activate={emit author-tapped(user: post.author.id)}>
+  <view class="author-row">
+    <img class="avatar" src={post.author.avatar.src} alt={post.author.avatar.alt} />
+    <text class="username">{post.author.username}</text>
+  </view>
+</region>
+```
+
+And the supplementary double-activation form, from the same component:
+
+```uhura
+<region label="Like this post" supplementary
+        on:activate-double={emit like-toggled(post: post.id, now-liked: true)}>
+  <img class="media" src={m.image.src} alt={m.image.alt} />
+</region>
+```
+
+| Contract | Current behavior |
+|---|---|
+| Class | `interactive` |
+| Children | Exactly one element (`UH5006 markup/bad-children` otherwise) |
+| `label` | Required `text`; the accessible name |
+| `supplementary` | Optional `bool` presence marker; declares the region a redundant gesture path |
+| `class` | Universal, CSS-owned class list |
+| `activate` | Input event with no carried payload |
+| `activate-double` | Input event with no carried payload |
+| Nesting | Interactive class: a region cannot nest inside another interactive element, and nothing interactive may appear beneath it (`UH5007 markup/nested-interactive`) |
+
+The nested-interactive rule also sees through components: expanding a
+component whose markup contains an interactive element inside a region is
+rejected using the checker's interactive memo. The golden rejection
+`reject-nested-interactive` pins the diagnostic.
+
+The supplementary reachability check is name-level: for every emit bound on a
+supplementary region, some non-supplementary use in the same definition must
+emit the same machine event. The Instagram corpus satisfies it because
+`like-toggled` is also emitted by the Like `<button>` in the action row.
+
+## Ownership
+
+Core owns nothing region-specific: a region contributes an ordinary semantic
+node whose bound descriptors flow through the standard event pipeline. The
+renderer owns gesture recognition (click, double-click, key presses) and
+focus presentation. Whether a double activation should have platform-specific
+timing or touch semantics is entirely renderer policy.
+
+## Accessibility and validation
+
+The checker enforces, with golden or corpus coverage:
+
+- catalog closure — unknown properties and events on `<region>` are rejected;
+- `label` is required (`UH5004`);
+- the children model is exactly one element (`UH5006`);
+- no interactive nesting in either direction (`UH5007`, pinned by
+  `reject-nested-interactive`); and
+- supplementary reachability (`UH5020`) — though no golden rejection
+  currently pins this diagnostic; it is enforced in code with corpus
+  evidence only.
+
+The browser realization maps `label` to `aria-label`, sets `role="button"`,
+and in Play sets `tabindex="0"`; Editor previews omit the tabindex, so a
+board region is never focusable. Play wires three gestures: click emits the
+`activate` descriptor, double-click emits `activate-double` (suppressing the
+platform default), and — for regions specifically — Enter and Space emit the
+first bound descriptor in `activate`, `press`, `activate-double` order.
+
+Known accessibility gaps, stated honestly:
+
+- **Everything is a button.** `role="button"` is applied to every region,
+  including supplementary ones and pure navigation targets. An author-row
+  region that navigates announces as a button, not a link; ARIA link
+  semantics do not exist in the contract.
+- **`aria-label` flattens content.** A region names itself with `aria-label`
+  over composite children; assistive technology reads the label and may not
+  expose the wrapped username, caption, or image content as the region's
+  name computation.
+- **Supplementary regions are still focusable.** A `supplementary` region
+  receives `tabindex="0"` like any other, adding a tab stop that duplicates
+  the focusable element the checker required elsewhere — the reverse of what
+  the marker suggests.
+- **Keyboard double activation is a collapse, not an equivalent.** Enter on
+  a region whose only binding is `activate-double` fires that descriptor on
+  a single key press. That satisfies reachability but blurs the gesture
+  semantics.
+
+## Rendering and platform behavior
+
+Browser Editor and Play realize the element as a `div` with class
+`uh-region` (plus authored classes):
+
+```html
+<div class="uh-region authored-classes" role="button" tabindex="0" aria-label="…">
+  <!-- the single semantic child -->
+</div>
+```
+
+Editor previews are inert: no tabindex, and the read-only renderer facade
+never wires gesture listeners, so a board region cannot emit. Play attaches
+the click, double-click, and region-specific keydown listeners once per
+element and dispatches whatever descriptors the current node carries.
+
+A native renderer may realize the contract with its platform gesture system
+(for example a tap and double-tap recognizer over a labelled accessibility
+element). It must reproduce the observable semantics — accessible name,
+focusability, keyboard activation, and single/double activation dispatch —
+or reject the capability honestly.
+
+## Motion
+
+`<region>` defines no semantic motion. Focus rings, press feedback, and
+ripple-style effects are renderer and platform presentation.
+
+## Conformance
+
+Existing executable coverage proves:
+
+- the base catalog exposes `region` as an interactive element with one-child
+  children, required `label`, `supplementary`, `activate`, and
+  `activate-double` (contract corpus);
+- `on:` bindings on layout elements are rejected with the wrap-in-region
+  note (`reject-event-on-layout` golden);
+- interactive nesting is rejected (`reject-nested-interactive` golden); and
+- the complete Instagram corpus checks and lowers with region semantic nodes
+  in the post card, reel card, connection row, stories tray, and the feed,
+  search, profile, and story pages.
+
+A durable support claim additionally requires conformance coverage for:
+
+- a golden rejection pinning `UH5020 markup/supplementary-unreachable`;
+- keyboard activation order (Enter/Space descriptor selection) as a pinned
+  renderer policy test;
+- double-click default suppression and its interaction with text selection;
+- accessibility-tree assertions for the label-over-content name computation;
+  and
+- equivalent semantics or an honest unsupported-capability diagnostic in
+  non-browser renderers.
+
+## Decisions and open questions
+
+This page is part of the v0 element documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC. The
+`§10` and `§4.8` cited by the checker diagnostics are spike-design sections,
+not a versioned language specification.
+
+Known gaps and open questions:
+
+1. Whether regions need a role taxonomy (button, link, none) instead of the
+   unconditional `role="button"`, and how a navigation region should
+   announce.
+2. Whether `supplementary` should remove the region from the focus order,
+   given that its purpose is to declare the redundant path.
+3. Whether keyboard activation of `activate-double`-only regions should
+   exist, be remapped, or be rejected statically.
+4. The children model is exactly one element; whether a region should ever
+   wrap conditional (`{#if}` / `{#match}`) content directly is undecided —
+   today the author must wrap those in a `<view>` first.
+5. Long-press, context-menu, and other activation gestures are not part of
+   the contract; whether they become new events or renderer policy is open.
+6. The checker validates that `label` is bound, not that its text is
+   non-empty or useful.
+
+Current implementation references:
+
+- [Base catalog declaration](../../../../../examples/instagram/client/catalog/base.toml)
+- [Catalog and markup checking](../../../../../crates/uhura-check/src/markup.rs)
+- [Browser property mapping](../../../../../web/src/renderer/appliers.ts)
+- [Gesture and keyboard wiring](../../../../../web/src/renderer/reconciler.ts)
+- [Contract corpus tests](../../../../../crates/uhura-check/tests/contracts_corpus.rs)
+- [Golden rejections](../../../../../crates/uhura-tests/goldens/m2/)
+- [Current Instagram post-card usage](../../../../../examples/instagram/client/components/post-card.uhura)
+- [Specification router](../../../../spec/README.md)

From 2c8547d7df0c9f3b53112d7c926c468e9d2fbf7f Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:00:51 +0900
Subject: [PATCH 3/8] docs(widgets): add the v0 text element page

---
 docs/widgets/drafts/v0/README.md        |   1 +
 docs/widgets/drafts/v0/elements/text.md | 169 ++++++++++++++++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/elements/text.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index bdf1c71..dedf3fe 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -25,6 +25,7 @@ No later language generation inherits these names or contracts by default.
 | [`<img>`](elements/img.md) | None | Built-in base catalogue during incubation | Renamed from `<image>` in the v0 catalogue; no accepted widget RFC | Typed asset and accessibility contract plus browser Editor/Play realization implemented |
 | [`<view>`](elements/view.md) | None | Built-in base catalogue during incubation | Neutral container implemented; semantic role taxonomy unsettled | Checker/runtime/browser realization implemented; known ARIA defects documented |
 | [`<region>`](elements/region.md) | None | Built-in base catalogue during incubation | Activation semantics implemented; role taxonomy and keyboard equivalence unsettled | Checked one-child activation area, supplementary reachability, and browser realization implemented; focus-order and role gaps documented |
+| [`<text>`](elements/text.md) | None | Built-in base catalogue during incubation | Text-only children rule implemented; semantic tag and inline-content model unsettled | Checked text-run children, typed interpolation, run joining, and browser realization implemented; no inline markup documented |
 
 ## Integrations
 
diff --git a/docs/widgets/drafts/v0/elements/text.md b/docs/widgets/drafts/v0/elements/text.md
new file mode 100644
index 0000000..6f3a232
--- /dev/null
+++ b/docs/widgets/drafts/v0/elements/text.md
@@ -0,0 +1,169 @@
+# `<text>`
+
+- **Status:** Implemented text container; semantic tag and inline-content model unsettled
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Element
+- **Facets:** None
+- **Availability:** Built-in base catalog; currently project-pinned during incubation
+- **Decision:** Current spike design; no accepted widget RFC
+- **Specification:** Pre-specification; text-only children rule implemented
+- **Implementation:** Checker, Core lowering, browser Editor, and Play implemented
+- **Owners:** Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+`<text>` is the only place text can appear. It declares no semantic
+properties of its own and no events; its entire contract is its children
+model: literal text runs and `{expr}` interpolation, nothing else. It is the
+smallest element in the base catalog.
+
+The current base catalog is stored with the Instagram project while Uhura is
+incubating. Calling the element built-in describes its authoring and checking
+role; it does not yet mean that a globally packaged catalog exists.
+
+## Why Uhura needs an explicit text element
+
+HTML permits bare text nodes anywhere flow content is allowed, so any
+container may quietly become a text owner. That ambient permission is what
+Uhura removes. Text outside `<text>` is a compile error
+(`UH5012 markup/interpolation-outside-text`, with the message *"text content
+(and `{expr}` interpolation) lives inside `<text>` only"*), which buys:
+
+- **One typed interpolation site.** `{expr}` is only legal inside `<text>`,
+  and every interpolated expression is checked against `text`. The corpus
+  converts numbers explicitly (`to-text(post.comment-count)`); there is no
+  implicit stringification a renderer could disagree about.
+- **Deterministic realization.** Because text owns its runs, lowering keeps
+  them as an ordered run list, Core evaluation joins literals and evaluated
+  interpolations into a single inert content value, and the renderer applies
+  it as one `textContent` write. There is no mixed children reconciliation
+  for text nodes at all — the reconciler skips child handling for `text`
+  entirely.
+- **A portable text primitive.** Non-web renderers receive "a labelled-run
+  text node" rather than the DOM's anything-may-contain-text model. This is
+  the same judgment as Flutter's explicit
+  [`Text`](https://api.flutter.dev/flutter/widgets/Text-class.html) widget:
+  text is a widget, not an ambient capability of containers.
+
+CSS keeps owning typography, color, wrapping, and truncation via the
+universal `class` attribute.
+
+## Current semantic contract
+
+Real usage from the Instagram post card:
+
+```uhura
+<text class="username">{post.author.username}</text>
+<text class="meta">{to-text(post.comment-count) ++ (if post.comment-count == 1 then " comment · " else " comments · ") ++ post.posted-label}</text>
+```
+
+| Contract | Current behavior |
+|---|---|
+| Class | `content` |
+| Children | Text runs only: literals and `{expr}` interpolation (`UH5006 markup/bad-children` for anything else) |
+| Interpolation | Each `{expr}` checks against `text` |
+| Props | None declared; `class` is universal |
+| Events | None; content-class elements cannot take `on:` bindings |
+
+Core evaluation joins the runs: literals concatenate with evaluated
+interpolation results into one plain string, delivered to the renderer as a
+single synthesized `content` value. The `content` name is pipeline
+machinery, not an authorable property — the catalog declares no props for `text`, and
+writing `content=…` in source is rejected as an unknown prop.
+
+## Ownership
+
+Core owns evaluation of interpolated expressions and produces the joined
+string. The renderer owns nothing but painting it; there is no state, no
+lifecycle, and no failure mode beyond expression evaluation itself.
+
+## Accessibility and validation
+
+The checker enforces, with golden or corpus coverage:
+
+- text and interpolation outside `<text>` are rejected (`UH5012`);
+- non-text children inside `<text>` are rejected (`UH5006`); and
+- interpolated expressions must type as `text`.
+
+The realization adds no ARIA: a text node is plain content, named by its own
+text. Accessibility concerns live where text is consumed — for example a
+`<region>` label naming over wrapped text content, documented on the
+[region page](region.md).
+
+## Rendering and platform behavior
+
+Browser Editor and Play realize the element as a `p` with class `uh-text`
+(plus authored classes), and apply the joined content with a single
+`textContent` assignment:
+
+```html
+<p class="uh-text authored-classes">joined literal and interpolated runs</p>
+```
+
+The `p` tag is renderer policy, not contract. It applies equally to
+paragraph-like captions and to inline-like fragments such as usernames; CSS
+in the corpus restyles it per class. A native renderer may realize the
+contract with its platform text primitive; it must reproduce the joined-runs
+content exactly.
+
+## Motion
+
+`<text>` defines no semantic motion. Text change is an ordinary content
+update with no transition contract.
+
+## Conformance
+
+Existing executable coverage proves:
+
+- the base catalog exposes `text` as a content element with the text
+  children model (contract corpus asserts the catalog's element set and
+  meta-schema);
+- the complete Instagram corpus checks, lowers, and renders with text nodes
+  in every page and component; and
+- renderer policy tests exercise text realization alongside the other
+  elements.
+
+A durable support claim additionally requires conformance coverage for:
+
+- a golden rejection pinning `UH5012` (text outside `<text>`);
+- a golden rejection pinning element children inside `<text>`; and
+- bidi, whitespace, and empty-content behavior across renderers.
+
+## Decisions and open questions
+
+This page is part of the v0 element documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC. The
+`§4.4` cited by the checker diagnostic is the spike design's markup section,
+not a versioned language specification.
+
+Known gaps and open questions:
+
+1. There is no inline markup: emphasis, links, or mixed-style runs inside
+   one text node are inexpressible. Instagram-style "username then caption"
+   lines are built from sibling `<text>` nodes styled by CSS.
+2. The `p` realization is unconditional. Whether the contract needs a
+   semantic role or level (paragraph, span-like, heading) or the tag stays
+   renderer policy is undecided.
+3. Whitespace normalization between runs is unspecified beyond the current
+   implementation's literal joining.
+4. Truncation, line clamping, and "see more" expansion are CSS or future
+   capabilities; nothing semantic exists.
+5. Localization concerns — plural rules, directionality isolation around
+   interpolated values — have no owner. The corpus hand-rolls English
+   pluralization with `if` expressions.
+
+Current implementation references:
+
+- [Base catalog declaration](../../../../../examples/instagram/client/catalog/base.toml)
+- [Catalog and markup checking](../../../../../crates/uhura-check/src/markup.rs)
+- [Text-run lowering](../../../../../crates/uhura-check/src/lower.rs)
+- [Run joining at evaluation](../../../../../crates/uhura-core/src/eval.rs)
+- [Browser property mapping](../../../../../web/src/renderer/appliers.ts)
+- [Shared browser reconciliation](../../../../../web/src/renderer/reconciler.ts)
+- [Contract corpus tests](../../../../../crates/uhura-check/tests/contracts_corpus.rs)
+- [Current Instagram post-card usage](../../../../../examples/instagram/client/components/post-card.uhura)
+- [Specification router](../../../../spec/README.md)

From 4a4554608b09e69db376985d4dc97a192b74683f Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:03:01 +0900
Subject: [PATCH 4/8] docs(widgets): add the v0 pager element page

---
 docs/widgets/drafts/v0/README.md         |   1 +
 docs/widgets/drafts/v0/elements/pager.md | 220 +++++++++++++++++++++++
 2 files changed, 221 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/elements/pager.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index dedf3fe..8f7042d 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -26,6 +26,7 @@ No later language generation inherits these names or contracts by default.
 | [`<view>`](elements/view.md) | None | Built-in base catalogue during incubation | Neutral container implemented; semantic role taxonomy unsettled | Checker/runtime/browser realization implemented; known ARIA defects documented |
 | [`<region>`](elements/region.md) | None | Built-in base catalogue during incubation | Activation semantics implemented; role taxonomy and keyboard equivalence unsettled | Checked one-child activation area, supplementary reachability, and browser realization implemented; focus-order and role gaps documented |
 | [`<text>`](elements/text.md) | None | Built-in base catalogue during incubation | Text-only children rule implemented; semantic tag and inline-content model unsettled | Checked text-run children, typed interpolation, run joining, and browser realization implemented; no inline markup documented |
+| [`<pager>`](elements/pager.md) | None | Built-in base catalogue during incubation | Uncontrolled paging implemented; `page-change` and indicator semantics unsettled | Checked keyed-each viewport and browser scroll-snap realization implemented; `page-change` declared but wired in no renderer |
 
 ## Integrations
 
diff --git a/docs/widgets/drafts/v0/elements/pager.md b/docs/widgets/drafts/v0/elements/pager.md
new file mode 100644
index 0000000..d169d7c
--- /dev/null
+++ b/docs/widgets/drafts/v0/elements/pager.md
@@ -0,0 +1,220 @@
+# `<pager>`
+
+- **Status:** Implemented paged viewport; `page-change` declared but never wired, indicator semantics unsettled
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Element
+- **Facets:** None
+- **Availability:** Built-in base catalog; currently project-pinned during incubation
+- **Decision:** Current spike design; no accepted widget RFC
+- **Specification:** Pre-specification; uncontrolled paging implemented, observation unrealized
+- **Implementation:** Checker, Core semantic view, browser Editor, and Play implemented; `page-change` unimplemented in every renderer
+- **Owners:** Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+`<pager>` declares a paged viewport: one slide visible at a time, slides
+supplied by exactly one keyed `{#each}`. It is a catalog element, not a
+user-authored component, and source cannot invent its properties or events.
+
+The current base catalog is stored with the Instagram project while Uhura is
+incubating. Calling the element built-in describes its authoring and checking
+role; it does not yet mean that a globally packaged catalog exists.
+
+## Why Uhura needs an explicit pager element
+
+The web builds carousels out of scroll containers, scroll-snap CSS, and
+JavaScript that reverse-engineers the current page from scroll offsets. The
+result is a mechanism, not a semantic: nothing identifies "this is a paged
+collection of N slides, currently on slide k" to a compiler, a static design
+tool, or a non-web renderer. The ARIA Authoring Practices
+[carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) exists
+because that identity must otherwise be reconstructed by hand every time.
+
+An explicit `<pager>` gives Uhura one stable owner for:
+
+- **the paged-collection identity** — a viewport whose children are exactly
+  one keyed `{#each}`, checked statically (`UH5006 markup/bad-children`
+  names the rule: *"children come from exactly one keyed `{#each}`"*);
+- **the accessible name** — `label` is required, so an unnamed carousel is a
+  compile error rather than an audit finding;
+- **the page indicator** — declared as data (`indicator="dots"`), realized
+  by the renderer, instead of a hand-built sibling widget that can drift
+  from the real page count; and
+- **future page observations** — the catalog reserves `page-change` as an
+  observation event so the machine can one day react to paging the same way
+  `near-end` works on `<scroll>`.
+
+This follows established practice in declarative UI systems: Flutter's
+[`PageView`](https://api.flutter.dev/flutter/widgets/PageView-class.html) is
+an explicit paged viewport distinct from its general scroll views, with the
+page as a first-class concept rather than a derived offset.
+
+CSS keeps owning slide sizing, snap physics presentation, and indicator
+appearance. `<pager>` exists because paged-collection identity is a semantic
+capability rather than aesthetics.
+
+## Current semantic contract
+
+Real usage from the Instagram post card's photo carousel:
+
+```uhura
+<pager class="media" indicator="dots" label="Photo carousel">
+  {#each c.slides as s (s.id)}
+    <img class="slide" src={s.src} alt={s.alt} />
+  {/each}
+</pager>
+```
+
+| Contract | Current behavior |
+|---|---|
+| Class | `layout` |
+| Viewport | Yes; the catalog meta-schema permits observation events only on viewports |
+| Children | Exactly one keyed `{#each}` (`UH5006` otherwise) |
+| `indicator` | Optional enum `none` or `dots` |
+| `label` | Required `text`; the accessible name |
+| `class` | Universal, CSS-owned class list |
+| `page-change` | Declared observation event (`kind = "observe"`); see below — no renderer emits it |
+| Current page | Renderer-owned physical state; absent from Uhura state and the semantic view |
+
+### `page-change` is declared, never realized
+
+This must be stated honestly. The catalog declares `page-change` — its own
+comment says *"Declared for controlled use; the spike never binds it"* — and
+the checker would accept an `on:page-change={emit …}` binding. But no
+occurrence in the corpus binds it, and no renderer code references the event
+at all: the browser pager's scroll listener only repaints the dots. A bound
+`page-change` today would check, lower, and then never fire. The event is a
+reserved name plus checker eligibility, not a working capability, and this
+page labels it **unimplemented** accordingly.
+
+## Ownership
+
+Core owns the slide list (through the keyed `{#each}`) and nothing else. The
+renderer owns the current page, snap physics, and indicator state. Like
+`<scroll>`'s physical offset, the current page is deliberately not
+application state in the uncontrolled model; whether a controlled variant
+(machine-owned page index) should exist is an open question below.
+
+## Accessibility and validation
+
+The checker enforces, with golden or corpus coverage:
+
+- catalog closure — unknown properties and events on `<pager>` are rejected;
+- `label` is required (`UH5004 markup/missing-required-prop`);
+- the children model is exactly one keyed `{#each}` (`UH5006`), asserted
+  directly by the contract corpus; and
+- `indicator` values are checked against the enum.
+
+The browser realization maps `label` to `aria-label` and sets
+`role="group"`. The dots are mechanic DOM marked `aria-hidden="true"`.
+
+Known accessibility gaps, stated honestly:
+
+- **No current-page semantics.** Nothing announces "slide 2 of 5". The dots
+  are hidden from assistive technology and there is no live region, no
+  `aria-roledescription="carousel"`, and no per-slide group labelling from
+  the APG carousel pattern.
+- **No keyboard paging.** No previous/next controls exist and none are
+  synthesized; paging is native horizontal scrolling of the track only.
+- **Reduced-motion behavior is undefined** for snap animation.
+- The checker validates that `label` is bound, not that its text is
+  non-empty or useful.
+
+## Rendering and platform behavior
+
+Browser Editor and Play realize the element as a `div` with class
+`uh-pager` (plus authored classes) owning two pieces of mechanic DOM: a
+scroll-snap track that hosts the semantic slides, and, when
+`indicator="dots"`, an indicator layer:
+
+```html
+<div class="uh-pager authored-classes" role="group" aria-label="…">
+  <div class="uh-track" data-uh-mechanic="track"><!-- semantic slides --></div>
+  <div class="uh-dots" data-uh-mechanic="dots" aria-hidden="true"><span class="uh-dot">…</span></div>
+</div>
+```
+
+The track is `display: flex; overflow-x: auto; scroll-snap-type: x
+mandatory` with each slide `flex: 0 0 100%`, so paging is native CSS
+scroll-snap in both Editor and Play. Semantic children are reconciled into
+the track, not the pager element itself; the mechanic track and dots are
+never counted as semantic children, and reconciliation leaves them in place
+when semantic children are swept — the same mechanic-DOM policy as the
+textfield's inner input. A track scroll listener keeps the active dot in
+sync with the scroll position; the dot count follows the semantic child
+count on every apply.
+
+A native renderer may realize the contract with its platform paged-view
+primitive. It must reproduce the observable semantics — accessible name,
+one-slide-at-a-time paging over the keyed children, and the declared
+indicator — or reject the capability honestly.
+
+## Motion
+
+`<pager>` defines no semantic motion. Snap animation, momentum, and
+indicator transitions are renderer and platform presentation; no completion
+event exists (and `page-change`, which could anchor one, is unrealized).
+
+## Conformance
+
+Existing executable coverage proves:
+
+- the base catalog exposes `pager` as a layout viewport whose children model
+  is keyed-each, with `indicator`, required `label`, and a declared
+  `page-change` observation (contract corpus asserts the children model and
+  the catalog meta-schema);
+- the complete Instagram corpus checks and lowers with pager semantic nodes
+  in the post card and reel card; and
+- renderer policy tests pin that mechanic pager DOM is excluded from
+  semantic realization.
+
+A durable support claim additionally requires conformance coverage for:
+
+- `page-change` end-to-end, once it is designed: cadence, payload (page
+  index? key?), and settling semantics — or its removal from the catalog;
+- dot-count and active-dot behavior under slide insertion, removal, and
+  reorder through the keyed `{#each}`;
+- accessibility-tree assertions for the group name and a decided
+  current-page announcement model; and
+- equivalent semantics or an honest unsupported-capability diagnostic in
+  non-browser renderers.
+
+## Decisions and open questions
+
+This page is part of the v0 element documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC. The
+`§10` cited by the catalog and diagnostics is the spike design's
+semantic-element-catalog section, not a versioned language specification.
+
+Known gaps and open questions:
+
+1. `page-change` has no design: no payload shape, no cadence (per snap
+   settle? per crossing?), no renderer wiring, and no corpus usage. Whether
+   it ships, changes shape, or is dropped from the catalog is undecided.
+2. Whether a controlled pager (machine-owned page index, programmatic
+   paging) should exist, mirroring the controlled-promotion mechanism the
+   textfield uses.
+3. The indicator enum is `none | dots`; numbered, fraction ("2/5"), and
+   thumbnail indicators have no owner, and whether indicators stay catalog
+   data or become authored markup is open.
+4. Current-page announcement and the APG carousel roles are undecided;
+   `role="group"` plus a hidden indicator is known to be insufficient.
+5. Keyboard and assistive paging controls (previous/next) have no owner —
+   authored buttons cannot target the pager because no paging intent exists.
+6. Autoplaying or looping pagers are not part of the contract.
+
+Current implementation references:
+
+- [Base catalog declaration](../../../../../examples/instagram/client/catalog/base.toml)
+- [Catalog and markup checking](../../../../../crates/uhura-check/src/markup.rs)
+- [Browser property mapping and mechanic track/dots](../../../../../web/src/renderer/appliers.ts)
+- [Track child-hosting in reconciliation](../../../../../web/src/renderer/reconciler.ts)
+- [Mechanic-DOM realization contract](../../../../../web/src/renderer/contracts.ts)
+- [Play pager styles](../../../../../web/src/play/shell.css)
+- [Contract corpus tests](../../../../../crates/uhura-check/tests/contracts_corpus.rs)
+- [Current Instagram post-card usage](../../../../../examples/instagram/client/components/post-card.uhura)
+- [Specification router](../../../../spec/README.md)

From 6ac1db0ba0a4bbce34cb450505774b2e420dc63f Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:05:46 +0900
Subject: [PATCH 5/8] docs(widgets): add the v0 video element page

---
 docs/widgets/drafts/v0/README.md         |   1 +
 docs/widgets/drafts/v0/elements/video.md | 231 +++++++++++++++++++++++
 2 files changed, 232 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/elements/video.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index 8f7042d..c90fb59 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -27,6 +27,7 @@ No later language generation inherits these names or contracts by default.
 | [`<region>`](elements/region.md) | None | Built-in base catalogue during incubation | Activation semantics implemented; role taxonomy and keyboard equivalence unsettled | Checked one-child activation area, supplementary reachability, and browser realization implemented; focus-order and role gaps documented |
 | [`<text>`](elements/text.md) | None | Built-in base catalogue during incubation | Text-only children rule implemented; semantic tag and inline-content model unsettled | Checked text-run children, typed interpolation, run joining, and browser realization implemented; no inline markup documented |
 | [`<pager>`](elements/pager.md) | None | Built-in base catalogue during incubation | Uncontrolled paging implemented; `page-change` and indicator semantics unsettled | Checked keyed-each viewport and browser scroll-snap realization implemented; `page-change` declared but wired in no renderer |
+| [`<video>`](elements/video.md) | None | Built-in base catalogue during incubation | In the catalogue; a stale checker note still calls it deferred — adjudication pending | Checked eight-prop playback contract, Play playback, and pinned Editor poster-only pose implemented; no playback events or captions |
 
 ## Integrations
 
diff --git a/docs/widgets/drafts/v0/elements/video.md b/docs/widgets/drafts/v0/elements/video.md
new file mode 100644
index 0000000..a160bdb
--- /dev/null
+++ b/docs/widgets/drafts/v0/elements/video.md
@@ -0,0 +1,231 @@
+# `<video>`
+
+- **Status:** Implemented playback element; a stale checker note still calls it deferred, and playback observation is absent
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Element
+- **Facets:** None
+- **Availability:** Built-in base catalog; currently project-pinned during incubation
+- **Decision:** Added to the base catalog (present in 0.3.0); a contradictory deferral note survives in the checker; no accepted widget RFC
+- **Specification:** Pre-specification; declarative playback policy implemented
+- **Implementation:** Checker, Core semantic view, browser Editor (poster pose), and Play (playing video) implemented
+- **Owners:** Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+`<video>` declares first-class time-based media with a deliberately small
+semantic surface: provider-resolved source and poster assets, a required
+accessible name, and five explicit playback-policy booleans. It is a catalog
+element, not a user-authored component, and source cannot invent its
+properties or events. It takes no children.
+
+The current base catalog is stored with the Instagram project while Uhura is
+incubating. Calling the element built-in describes its authoring and checking
+role; it does not yet mean that a globally packaged catalog exists.
+
+## The stale deferral note
+
+The catalog and the checker currently disagree in text, though not in
+behavior, and this page records the contradiction precisely.
+
+The checker's unknown-element note table still contains:
+
+> `video` — "video is deferred: poster `<img>` + `video-off` badge pattern"
+
+That table is consulted in exactly one place: the
+`ElementResolution::Unknown` arm of element resolution. Element resolution
+classifies any name the catalog owns as `CatalogElement` before the unknown
+arm can be reached — and `video` **is** a catalog element in base 0.3.0, with
+the contract corpus asserting its presence in the element list. The note is
+therefore unreachable dead data: no input can produce it, because `<video>`
+in source resolves to the catalog element and checks normally.
+
+Reading: the catalog is the current truth — video was promoted from the
+earlier poster-plus-badge deferral into a real element — and the note is a
+leftover from the deferral era. It is retained here as a documented defect
+pending maintainer confirmation in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22); the fix is
+deleting the entry (or, if the deferral is somehow still intended, deleting
+the catalog element — the corpus makes that reading untenable, since two
+components use `<video>` today).
+
+## Why Uhura needs an explicit video element
+
+HTML's [`video`](https://html.spec.whatwg.org/multipage/media.html#the-video-element)
+couples a huge imperative surface (media controllers, ready states, track
+lists) with permissive markup: no accessible name is required, autoplay
+policy is a moving browser target, and sources are raw URLs. Uhura's element
+keeps the portable part and makes the policy explicit:
+
+- **Playback policy is authored data, not renderer magic.** The catalog
+  comment states the intent: *"playback policy remains explicit instead of
+  renderer magic."* `autoplay`, `muted`, `loop`, `controls`, and
+  `playsinline` are declared booleans; a renderer applies exactly what the
+  author declared, and a design tool can read the policy statically without
+  executing anything.
+- **A name is mandatory.** `label` is required (`UH5004
+  markup/missing-required-prop`), so unnamed media fails checking. The
+  corpus names videos from their poster's alternative text.
+- **Assets are provider-resolved.** `src` and `poster` are typed `asset`
+  values resolved through the asset pipeline, not free-form URLs; the
+  browser realization resolves them to concrete mp4/jpg URLs.
+- **Previews are safe by construction.** The Editor realization is a poster
+  pose: playback booleans are forced off and no source is attached, so a
+  static board can never start playing or downloading media. This
+  deterministic preview pose is pinned by a renderer policy test — the
+  legitimate heir of the old "poster plus badge" deferral pattern.
+
+CSS keeps owning size, aspect, cropping, and placement. `<video>` exists
+because media identity, naming, and playback policy are semantic
+capabilities rather than aesthetics.
+
+## Current semantic contract
+
+Real usage from the Instagram corpus — the post card:
+
+```uhura
+<video class="media" src={v.src} poster={v.poster.src} label={v.poster.alt} controls playsinline />
+```
+
+and the reel card:
+
+```uhura
+<video class="reel-media" src={v.src} poster={v.poster.src} label={v.poster.alt} muted loop controls playsinline />
+```
+
+| Contract | Current behavior |
+|---|---|
+| Class | `content` |
+| Children | None |
+| `src` | Required `asset`; the media source |
+| `poster` | Optional `asset`; the pre-playback image |
+| `label` | Required `text`; the accessible name |
+| `autoplay` | Optional `bool` |
+| `muted` | Optional `bool` |
+| `loop` | Optional `bool` |
+| `controls` | Optional `bool` |
+| `playsinline` | Optional `bool` |
+| Events | None declared; playback state is invisible to the machine |
+| Playback position | Renderer-owned; absent from Uhura state and the semantic view |
+
+## Ownership
+
+Core owns nothing playback-related: the element contributes a semantic node
+with evaluated props, and no event ever flows back. The renderer owns the
+media pipeline, playback state, controls chrome, and the platform's autoplay
+gating. The asset provider owns resolving `src` and `poster` references to
+URLs. This means play/pause state, progress, buffering, and errors are all
+currently outside the semantic model — an honest limitation listed below.
+
+## Accessibility and validation
+
+The checker enforces, with golden or corpus coverage:
+
+- catalog closure — unknown properties and events on `<video>` are rejected;
+- `src` and `label` are required (`UH5004`);
+- the children model is `none` (`UH5006 markup/bad-children`); and
+- boolean props are presence markers written bare, per the corpus style.
+
+The browser realization maps `label` to `aria-label` on the native element.
+
+Known accessibility gaps, stated honestly:
+
+- **No captions or subtitles.** There is no track/caption concept at all —
+  no semantic property, no asset kind, no renderer surface. For real media
+  content this is the largest gap in the contract.
+- **No text alternative model beyond the name.** Unlike `<img>`'s checked
+  `alt`/`decorative` choice, video has only `label`; audio description and
+  transcript association have no owner.
+- **Autoplay against user preference.** `autoplay` is applied as declared;
+  no reduced-motion or user-preference gate exists in the contract, and
+  browsers' own autoplay blocking becomes silent divergence between what the
+  author declared and what plays.
+- The checker validates that `label` is bound, not that its text is
+  non-empty or useful.
+
+## Rendering and platform behavior
+
+Browser Editor and Play realize the element as a native `video` tag with
+class `uh-video` (plus authored classes) — one of the few catalog elements
+with a non-`div` realization:
+
+```html
+<video class="uh-video authored-classes" aria-label="…" poster="…resolved…" src="…resolved…">
+```
+
+Play applies all five policy booleans as both content attributes and IDL
+properties, and resolves `src` (mp4) and `poster` (jpg) through the asset
+applier, which detaches and reloads the media element when a source is
+removed. Editor forces every boolean off, never attaches `src`, applies only
+the poster, and stamps `data-video-preview="poster"` — the pinned poster-only
+preview pose. The renderer policy test asserts a board video has a resolved
+poster, no source, and no autoplay/controls.
+
+A native renderer may realize the contract with its platform media player.
+It must reproduce the observable semantics — accessible name, poster-first
+presentation, and literal application of the declared playback policy — or
+reject the capability honestly.
+
+## Motion
+
+`<video>` is itself motion, but defines no semantic motion contract: no
+transition, no completion event, no reduced-motion behavior. Whether
+`autoplay` should be subordinated to a reduced-motion preference is an open
+question below.
+
+## Conformance
+
+Existing executable coverage proves:
+
+- the base catalog exposes `video` as a childless content element with the
+  eight properties above and no events (the contract corpus asserts the
+  catalog element list and meta-schema);
+- the complete Instagram corpus checks and lowers with video semantic nodes
+  in the post card and reel card; and
+- the Editor poster-only pose is pinned by a renderer policy test.
+
+A durable support claim additionally requires conformance coverage for:
+
+- deleting (or justifying) the unreachable deferral note, with a test that
+  `<video>` resolves as a catalog element;
+- asset-resolution failure behavior for `src` and `poster`;
+- autoplay policy divergence: declared `autoplay` versus browser gating,
+  and the `muted`-autoplay interaction;
+- accessibility-tree assertions for the media name; and
+- equivalent semantics or an honest unsupported-capability diagnostic in
+  non-browser renderers.
+
+## Decisions and open questions
+
+This page is part of the v0 element documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC.
+
+Known gaps and open questions:
+
+1. The stale checker note (above) needs maintainer adjudication in #22:
+   delete the unreachable `video` entry from the unknown-element note table.
+2. Playback observation has no design: no `play`/`pause`/`ended` events, no
+   position, no buffering state. Whether any of it becomes observable to
+   the machine (the pager's `page-change` faces the same question) is open.
+3. Captions, subtitles, audio description, and transcripts have no owner.
+4. Whether `autoplay` should be gated on reduced-motion or become a
+   renderer-mediated request rather than a literal command.
+5. The asset pipeline currently assumes mp4 and jpg; multiple sources,
+   adaptive streaming, and format negotiation have no owner.
+6. Whether the machine can ever command playback (a play intent) or the
+   contract stays declarative-policy-only.
+
+Current implementation references:
+
+- [Base catalog declaration](../../../../../examples/instagram/client/catalog/base.toml)
+- [Catalog and markup checking, including the stale note](../../../../../crates/uhura-check/src/markup.rs)
+- [Browser tag selection and property mapping](../../../../../web/src/renderer/appliers.ts)
+- [Asset resolution for source and poster](../../../../../web/src/renderer/assets.ts)
+- [Renderer policy tests (Editor poster-only pose)](../../../../../web/src/renderer/tests/policies.test.ts)
+- [Contract corpus tests](../../../../../crates/uhura-check/tests/contracts_corpus.rs)
+- [Current Instagram post-card usage](../../../../../examples/instagram/client/components/post-card.uhura)
+- [Current Instagram reel-card usage](../../../../../examples/instagram/client/components/reel-card.uhura)
+- [Specification router](../../../../spec/README.md)

From edd58d11b607894adaa11a1689fb8f1861d58645 Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:07:31 +0900
Subject: [PATCH 6/8] docs(widgets): add the v0 sheet surface page

---
 docs/widgets/drafts/v0/README.md         |   6 +
 docs/widgets/drafts/v0/surfaces/sheet.md | 234 +++++++++++++++++++++++
 2 files changed, 240 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/surfaces/sheet.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index c90fb59..2b2bd5c 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -29,6 +29,12 @@ No later language generation inherits these names or contracts by default.
 | [`<pager>`](elements/pager.md) | None | Built-in base catalogue during incubation | Uncontrolled paging implemented; `page-change` and indicator semantics unsettled | Checked keyed-each viewport and browser scroll-snap realization implemented; `page-change` declared but wired in no renderer |
 | [`<video>`](elements/video.md) | None | Built-in base catalogue during incubation | In the catalogue; a stale checker note still calls it deferred — adjudication pending | Checked eight-prop playback contract, Play playback, and pinned Editor poster-only pose implemented; no playback events or captions |
 
+## Surfaces
+
+| Entry | Facets | Availability | Decision | Implementation |
+|---|---|---|---|---|
+| [Sheet](surfaces/sheet.md) | None | Built-in surface machinery; the default modality | Structural lifecycle per the spike design; modality validation and motion unsettled | Parser, checker steering, Core surface stack, and browser scrim/Escape/focus realization implemented |
+
 ## Integrations
 
 | Entry | Applies to | Decision | Implementation |
diff --git a/docs/widgets/drafts/v0/surfaces/sheet.md b/docs/widgets/drafts/v0/surfaces/sheet.md
new file mode 100644
index 0000000..a029360
--- /dev/null
+++ b/docs/widgets/drafts/v0/surfaces/sheet.md
@@ -0,0 +1,234 @@
+# Sheet surface
+
+- **Status:** Implemented default surface modality; modality validation, motion, and drag dismissal unsettled
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Surface
+- **Facets:** None
+- **Availability:** Built-in surface machinery; `sheet` is the default modality
+- **Decision:** Current spike design (§8.1); no accepted widget RFC
+- **Specification:** Pre-specification; structural lifecycle implemented
+- **Implementation:** Parser, checker, Core surface stack, browser Editor, and Play implemented
+- **Owners:** Syntax, Checker, Core, Renderer
+- **Supported renderers:** Browser Editor and Play
+
+A sheet is a surface — a machine-managed presentation layer stacked above
+the page — whose modality is `sheet`. Surfaces are not elements: the checker
+steers markup away explicitly (writing `<sheet>` produces the unknown-element
+note *"sheets are surfaces — `surface <name> modality sheet`"*, and mounting
+a declared surface by name in markup adds *"surfaces mount via
+`open-surface`, not markup"*). A surface is declared as its own definition
+kind and entered only through the machine.
+
+This is the first Surface entry in the v0 draft; the stable
+[surfaces hub](../../../surfaces/README.md) records that no surface is
+documented outside this disposable draft yet.
+
+## Why Uhura needs machine-owned sheets
+
+The web's bottom sheet is a positioned `div` plus hand-written scrim,
+Escape handling, focus management, and open/close state scattered through
+application code. Every one of those concerns is a correctness or
+accessibility bug when forgotten, which is why the ARIA APG
+[dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+is a checklist at all. Uhura moves the whole lifecycle into the machine:
+
+- **Opening is a machine operation.** `open-surface <name>(args)` is a
+  statement in a handler, staged and applied structurally — not a markup
+  conditional. The surface instance gets a serial, its own state, a
+  recorded opener scope, and a captured focus-restore key-path from the
+  triggering node.
+- **Dismissal is structural, not authored.** Every surface view carries a
+  first-class dismiss descriptor whose event is the reserved machine event
+  `dismiss`. Escape and the scrim emit that published descriptor; Core
+  handles it structurally with no authored handler involved, pops the
+  instance, force-closes surfaces it opened, and issues a focus-restore
+  intent when the dismissed surface was topmost. A `dismiss` arriving from
+  a non-surface scope is an evaluation error.
+- **Occlusion is enforced in acceptance.** While any surface is stacked,
+  UI events targeting the page are dropped as occluded, and only the top
+  surface's scope is accepted — interaction with covered layers is
+  impossible by construction, not by pointer-events CSS.
+- **Focus is a machine intent.** The dismiss pops emit a `focus-restore`
+  intent carrying the stored key-path; the renderer's focus controller
+  performs it. Entering a mounted sheet focuses its first focusable
+  element.
+
+The result: an author writes one declaration line and one `open-surface`
+statement, and scrim, Escape, stacking, inertness, and focus restoration
+exist with replayable, trace-visible semantics.
+
+## Current semantic contract
+
+The corpus' only surface, the Instagram comments sheet:
+
+```uhura
+surface comments-sheet modality sheet
+
+props {
+  post: id
+}
+```
+
+opened from the feed, post, and reels pages:
+
+```uhura
+on comments-requested(post: id) {
+  open-surface comments-sheet(post: post)
+}
+```
+
+| Contract | Current behavior |
+|---|---|
+| Declaration | `surface <name>` with optional `modality <ident>`; the parser hint names `sheet` |
+| Default | Omitted modality lowers to `"sheet"`; the IR models modality as surface-only data |
+| Instance identity | `definition:serial` key; serials minted per open |
+| Props | Declared props bound by name from the `open-surface` argument list |
+| State | Each instance gets fresh initial state; no state survives dismissal |
+| Dismiss | Reserved structural `dismiss`; Escape and scrim emit the published descriptor |
+| Occlusion | Any stacked surface occludes the page; only the top surface accepts UI events |
+| Focus | First focusable focused on mount; focus-restore intent to the opener's key-path on topmost dismissal |
+| Sweep | Surfaces opened by a dismissed or swept scope force-close with it |
+
+The modality value flows verbatim from parse through lowering
+(`DefKind::Surface` only — pages and components never carry one) into the
+IR and out through evaluation into each `SurfaceView`, which also carries
+the dismiss descriptor and the focus-restore key-path.
+
+## Ownership
+
+Core owns the surface stack: instances, serials, props, per-instance state,
+opener bookkeeping, structural dismiss, occlusion acceptance, the orphan
+sweep, and focus-restore intents. The renderer owns presentation: scrim,
+panel, stacking order, inertness, Escape listening, and actually moving
+focus. The renderer never invents a dismiss event — it presses the
+descriptor Core published, IME-guarded so an Escape that cancels a
+composition is not a dismiss gesture.
+
+## Accessibility and validation
+
+Implemented behavior:
+
+- The Play panel is `role="dialog"` with `aria-modal="true"` and
+  `tabindex="-1"`, receives focus (or its first focusable child) on mount.
+- The page host and every below-top overlay are `inert` while surfaces are
+  stacked, so focus and assistive-technology traversal cannot reach
+  occluded content — containment by inertness rather than a roving trap.
+- Escape and scrim dismissal are wired unconditionally.
+- Focus restoration targets the recorded key-path, falling back to a
+  focusable descendant of the recorded node.
+
+Known gaps, stated honestly:
+
+- **No accessible name for the sheet itself.** Nothing labels the dialog;
+  no title property or labelled-by association exists in the declaration.
+- **`role="dialog"` regardless of modality.** A sheet announces as a
+  dialog; no sheet-specific role or `aria-roledescription` exists.
+- **The modality value is unvalidated.** The parser accepts any identifier
+  after `modality`; no checker rule constrains it to a known set. A typo
+  (`modality shete`) lowers, runs, and silently renders with the default
+  sheet presentation.
+- There is no non-dismissable sheet: Escape and scrim always dismiss.
+
+## Rendering and platform behavior
+
+The Play shell mounts each stacked surface as an overlay in host order:
+
+```html
+<div class="uh-surface-overlay" data-surface-key="comments-sheet:2">
+  <div class="uh-scrim"></div>
+  <div class="uh-surface uh-modality-sheet" role="dialog" aria-modal="true" tabindex="-1">
+    <!-- the surface's semantic root -->
+  </div>
+</div>
+```
+
+The base stylesheet presents the panel as a bottom sheet: the overlay is a
+bottom-justified column, the panel is 72% block-size with top-rounded
+corners over a 40% black scrim. The `uh-modality-<modality>` class is
+stamped from the surface view, though today only the base `.uh-surface`
+bottom-sheet treatment exists — sheet presentation is effectively the
+universal surface presentation. Editor boards realize the same overlay
+structure read-only and label surface nodes with their modality in the
+surface hierarchy and workflow views.
+
+A native renderer may realize the contract with its platform sheet
+primitive. It must reproduce the observable semantics — stacked modal
+presentation, scrim/Escape-equivalent dismissal through the published
+descriptor, occlusion, and focus restoration — or reject the capability
+honestly.
+
+## Motion
+
+Sheets define no semantic motion: no enter/exit transition, no completion
+event, no reduced-motion contract. The current realization mounts and
+removes overlays instantly; slide-up presentation and drag-to-dismiss are
+future renderer or contract work, listed below.
+
+## Conformance
+
+Existing executable coverage proves:
+
+- surface declarations parse with and without `modality`, and lowering
+  defaults the modality to `sheet` for surface definitions only;
+- the evaluated snapshot carries per-surface modality, dismiss descriptor,
+  and restore-focus key-path with an exact-field protocol check;
+- the M4 gate tests drive `comments-sheet` end-to-end over the Instagram
+  IR: opening, surface views in snapshots, dismissal, and the FocusRestore
+  intent asserted on topmost dismissal.
+
+A durable support claim additionally requires conformance coverage for:
+
+- direct tests pinning the non-surface-scope dismiss error, occlusion drop
+  dispositions, and the opened-surface sweep (implemented and documented in
+  the step machinery, but not individually pinned);
+- checker-level modality validation once the legal set is decided;
+- an accessible-name mechanism for the panel;
+- Escape-during-IME and scrim-versus-panel-click edge cases as pinned
+  renderer tests;
+- stacked-sheet (surface-over-surface) presentation and focus behavior; and
+- equivalent semantics or an honest unsupported-capability diagnostic in
+  non-browser renderers.
+
+## Decisions and open questions
+
+This page is part of the v0 documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). The current
+implementation and
+[Instagram spike design](../../../../studies/instagram-spike-design.md)
+establish useful evidence but do not replace an accepted widget RFC. The
+`§8.1` cited by the code is the spike design's surface-stack section, not a
+versioned language specification.
+
+Known gaps and open questions:
+
+1. The legal modality set is undefined — see the
+   [dialog page](dialog.md) for the second declared value and its
+   unrealized presentation. Whether modality becomes a checked enum, and
+   where its meaning (presentation? occlusion? dismissal policy?) is
+   specified, is open.
+2. Sheet naming: a title/label for the dialog role has no owner.
+3. Non-dismissable and confirm-before-dismiss sheets are inexpressible;
+   whether dismissability becomes declarable is open.
+4. Detents, partial-height sheets, and drag-to-dismiss are not part of the
+   contract.
+5. Enter/exit motion and its completion semantics have no owner.
+6. Whether `open-surface` idempotency per (definition, context) — described
+   in the spike design — is fully honored by the current staging is not
+   pinned by a dedicated test.
+
+Current implementation references:
+
+- [Surface declaration parsing](../../../../../crates/uhura-syntax/src/parser/mod.rs)
+- [Modality lowering and default](../../../../../crates/uhura-check/src/lower.rs)
+- [Surface IR](../../../../../crates/uhura-core/src/ir.rs)
+- [Surface view and dismiss descriptor](../../../../../crates/uhura-core/src/eval.rs)
+- [Semantic view types](../../../../../crates/uhura-core/src/view.rs)
+- [Structural dismiss, occlusion, and the sweep](../../../../../crates/uhura-core/src/step.rs)
+- [Checker steering notes](../../../../../crates/uhura-check/src/markup.rs)
+- [Play surface stack](../../../../../web/src/play/surfaces.ts)
+- [Play focus mechanics](../../../../../web/src/play/focus.ts)
+- [Play sheet styles](../../../../../web/src/play/shell.css)
+- [Current Instagram comments sheet](../../../../../examples/instagram/client/surfaces/comments-sheet.uhura)
+- [Specification router](../../../../spec/README.md)

From c2c08d0a9e63846811e46f9c752d9bf1a86fa004 Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:08:58 +0900
Subject: [PATCH 7/8] docs(widgets): add the v0 dialog surface page

---
 docs/widgets/drafts/v0/README.md          |   1 +
 docs/widgets/drafts/v0/surfaces/dialog.md | 183 ++++++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 docs/widgets/drafts/v0/surfaces/dialog.md

diff --git a/docs/widgets/drafts/v0/README.md b/docs/widgets/drafts/v0/README.md
index 2b2bd5c..2ff226e 100644
--- a/docs/widgets/drafts/v0/README.md
+++ b/docs/widgets/drafts/v0/README.md
@@ -34,6 +34,7 @@ No later language generation inherits these names or contracts by default.
 | Entry | Facets | Availability | Decision | Implementation |
 |---|---|---|---|---|
 | [Sheet](surfaces/sheet.md) | None | Built-in surface machinery; the default modality | Structural lifecycle per the spike design; modality validation and motion unsettled | Parser, checker steering, Core surface stack, and browser scrim/Escape/focus realization implemented |
+| [Dialog](surfaces/dialog.md) | None | Proposed; named by a checker steering note only | No design: legal modality set, presentation, and dismissal policy all open | Generic surface machinery would accept `modality dialog`; no dialog presentation, validation, or corpus usage exists |
 
 ## Integrations
 
diff --git a/docs/widgets/drafts/v0/surfaces/dialog.md b/docs/widgets/drafts/v0/surfaces/dialog.md
new file mode 100644
index 0000000..2125a11
--- /dev/null
+++ b/docs/widgets/drafts/v0/surfaces/dialog.md
@@ -0,0 +1,183 @@
+# Dialog surface
+
+- **Status:** Named but unrealized modality: the machinery is modality-generic, no dialog presentation exists, and no corpus usage exists
+- **Version scope:** v0 incubation draft
+- **Lifetime:** Disposable with the v0 widget draft
+- **Document type:** Capability
+- **Primary form:** Surface
+- **Facets:** None
+- **Availability:** Proposed; the surface machinery would accept `modality dialog` today, but nothing distinguishes it from a sheet
+- **Decision:** Named by a checker steering note only; no accepted widget RFC
+- **Specification:** Pre-specification; no dialog-specific semantics exist anywhere
+- **Implementation:** Generic surface machinery implemented; dialog presentation unimplemented; zero corpus usage
+- **Owners:** Syntax, Checker, Core, Renderer
+- **Supported renderers:** None with dialog-specific behavior
+
+A dialog is the second surface modality the v0 line names: a machine-managed
+modal layer that should present as a centered interruption rather than a
+bottom sheet. This page documents an honest peculiarity of the current
+state: **dialog exists as a name, not as a capability.** Every claim below
+is labelled accordingly.
+
+The one place the codebase commits to dialogs at all is the checker's
+steering note: writing `<dialog>` as markup is rejected as an unknown
+element with the note *"dialogs are surfaces (core surface stack)"* —
+matching the sibling note that steers `<sheet>` to
+`surface <name> modality sheet`. The steering is implemented; the
+destination is not.
+
+## What exists today (implemented)
+
+The surface machinery is modality-generic, so `modality dialog` would flow
+through it end to end:
+
+- **Parse.** The parser accepts any identifier after `modality` (its
+  error hint names only `sheet`), so `surface confirm-delete modality
+  dialog` parses.
+- **Lower and IR.** The modality string lowers verbatim for surface
+  definitions and rides the IR; nothing inspects the value.
+- **Core.** Evaluation copies it into the surface view. Opening, stacking,
+  occlusion, structural dismiss via the reserved `dismiss` event, the
+  orphan sweep, and focus-restore intents are all shared with sheets and
+  are documented on the [sheet page](sheet.md) — none of them branch on
+  modality. The step machinery's acceptance comment mentions "top-surface
+  modality", but the implemented rule is modality-independent: any stacked
+  surface occludes the page and only the top surface is interactive.
+- **Play.** The panel would be stamped `uh-modality-dialog` and, as for
+  every surface, `role="dialog"` with `aria-modal="true"`, scrim and
+  Escape dismissal, inert layers below, and first-focusable entry.
+
+## What does not exist (the gap)
+
+- **No presentation.** No `.uh-modality-dialog` rule exists in any
+  stylesheet. The base `.uh-surface` treatment is a bottom sheet — 72%
+  block-size, top-rounded corners, bottom-justified overlay — so a
+  `modality dialog` surface would render as a sheet with a different class
+  name. A centered, width-constrained dialog pose exists nowhere.
+- **No validation.** No checker rule constrains the modality value; the
+  legal set is undefined. `dialog` is exactly as (un)checked as `shete`.
+- **No semantics.** Nothing dialog-specific is specified: no
+  alert/confirmation taxonomy, no required-choice (non-dismissable) mode,
+  no default-action or destructive-action concept, no dialog title.
+- **No usage.** The corpus contains exactly one surface, `comments-sheet
+  modality sheet`; `modality dialog` appears nowhere in any example, test,
+  or golden. There is no real usage example to cite, and this page
+  deliberately does not invent one as if it were supported.
+
+## Why Uhura needs dialogs as surfaces (proposed)
+
+The argument is the sheet argument with a different pose. A confirmation
+dialog hand-built from positioned divs re-implements scrim, Escape, focus
+capture, and restoration — the ARIA APG
+[modal dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+checklist — per occurrence. Uhura's surface stack already owns that
+lifecycle structurally: machine-opened instances, published dismiss
+descriptors, occlusion in event acceptance, and focus-restore intents.
+Making dialogs a modality of the same stack, rather than a new primitive,
+means:
+
+- one lifecycle, one trace shape, and one replay story for every modal
+  layer;
+- the modality axis carries only what actually differs — presentation
+  geometry and, plausibly, dismissal policy (dialogs conventionally resist
+  scrim-dismissal for destructive confirmations); and
+- the checker's element-steering keeps authors from rebuilding modality
+  out of `<view>`s, exactly as it does for sheets.
+
+The native web is converging on the same split: HTML's
+[`dialog` element](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element)
+distinguishes modal presentation from content, and Uhura's machine-owned
+variant adds the statically checkable lifecycle HTML leaves to script.
+
+## Proposed contract sketch (not implemented)
+
+A minimal dialog declaration would be spelled exactly like a sheet:
+
+```uhura
+surface confirm-delete modality dialog
+
+props {
+  post: id
+}
+```
+
+opened with the same machine statement (`open-surface
+confirm-delete(post: post)`) and dismissed through the same reserved
+`dismiss`. Everything on the sheet page's contract table would apply
+unchanged except presentation. This sketch is authorable today and would
+run — but it would look like a sheet, which is why this page labels the
+capability unrealized rather than partially supported.
+
+## Accessibility and validation
+
+Nothing dialog-specific is implemented. The generic surface behavior
+(`role="dialog"`, `aria-modal`, inert lower layers, focus entry and
+restoration) and its gaps — no accessible name for the panel, no
+non-dismissable mode — are documented on the [sheet page](sheet.md) and
+apply verbatim. A real dialog capability would additionally need:
+
+- a title/accessible-name mechanism (dialogs are conventionally named by
+  a visible heading);
+- a decided dismissal policy (Escape yes, scrim configurable, or
+  required-choice); and
+- initial-focus rules for confirmation patterns (focus the safe action,
+  not the first focusable, per APG guidance).
+
+## Rendering and platform behavior
+
+Unimplemented. The required renderer work is a `.uh-modality-dialog`
+presentation (centered overlay, constrained inline-size, full scrim) in
+Play and Editor, and a native mapping to platform dialog/alert primitives.
+Until a renderer distinguishes the modality, claiming dialog support would
+be false; renderers currently realize every surface as a sheet.
+
+## Motion
+
+Not part of any contract; sheets define none either. Dialog conventions
+(fade/scale-in) would need the same motion-contract decision the sheet
+page defers.
+
+## Conformance
+
+Nothing dialog-specific is provable today, and no conformance case exists.
+Before support can be claimed, at minimum:
+
+- the legal modality set is decided and checker-validated;
+- a dialog presentation exists in the browser renderers, pinned by policy
+  tests;
+- occlusion, dismissal, and focus behavior are adjudicated per modality
+  (identical to sheets, or deliberately different) and pinned; and
+- at least one corpus surface uses `modality dialog` end to end.
+
+## Decisions and open questions
+
+This page is part of the v0 documentation effort signalled in
+[gridaco/uhura#22](https://github.com/gridaco/uhura/issues/22). It exists
+to keep the modality axis honest: the name is reserved by a steering note,
+the machinery is ready, and the capability is not designed.
+
+Open questions:
+
+1. Is `dialog` actually the second modality v0 wants, or should the axis
+   wait for a real product need? (The corpus has never needed one.)
+2. Whether modality means presentation only, or also dismissal policy and
+   occlusion behavior — the step machinery's comment gestures at
+   modality-aware acceptance that does not exist.
+3. Alert versus confirmation versus free-form dialog taxonomy, default and
+   destructive actions, and required-choice semantics.
+4. Dialog naming (visible title versus label prop) and initial focus.
+5. Whether the unvalidated-modality hole is fixed by an enum in the
+   parser, the checker, or a future surface catalog analogous to the
+   element catalog.
+
+Current implementation references (all modality-generic):
+
+- [Checker steering note for `<dialog>`](../../../../../crates/uhura-check/src/markup.rs)
+- [Surface declaration parsing](../../../../../crates/uhura-syntax/src/parser/mod.rs)
+- [Modality lowering and default](../../../../../crates/uhura-check/src/lower.rs)
+- [Surface view and dismiss descriptor](../../../../../crates/uhura-core/src/eval.rs)
+- [Structural dismiss and occlusion](../../../../../crates/uhura-core/src/step.rs)
+- [Play surface stack and modality class](../../../../../web/src/play/surfaces.ts)
+- [Sheet-only surface styles](../../../../../web/src/play/shell.css)
+- [Sheet surface page](sheet.md)
+- [Specification router](../../../../spec/README.md)

From ad1b9f311c9ab2ad6aad0398416dcfb6ae8c16bd Mon Sep 17 00:00:00 2001
From: yongrean <78528865+k08200@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:22:45 +0900
Subject: [PATCH 8/8] docs(widgets): route the surface hub to v0 pages and
 document the avatar and card patterns

---
 docs/widgets/patterns/README.md | 29 ++++++++++++++++++++++++++++-
 docs/widgets/surfaces/README.md |  7 ++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/docs/widgets/patterns/README.md b/docs/widgets/patterns/README.md
index 3396ba7..f0d3a83 100644
--- a/docs/widgets/patterns/README.md
+++ b/docs/widgets/patterns/README.md
@@ -12,4 +12,31 @@ and renderers.
 Patterns are guidance and reusable material, not catalog elements by naming
 convention alone.
 
-No patterns are documented here yet.
+## Named patterns
+
+The checker's unknown-element notes direct authors here for two names that are
+deliberately not catalog elements. Both are compositions of existing
+capabilities; exact element contracts belong to the versioned catalog docs.
+
+### Avatar
+
+An avatar is `<img>` with authored sizing and shape, not an element:
+
+```uhura
+<img class="viewer-avatar" src={viewer.avatar.src} alt={viewer.avatar.alt} />
+```
+
+with CSS owning the circular crop (`border-radius`, fixed inline/block size,
+`object-fit: cover`). The accessibility contract is `<img>`'s own
+`exactly-one-of [alt, decorative]`; an avatar that duplicates an adjacent
+visible name is usually `decorative`. See the current
+[v0 `<img>` page](../drafts/v0/elements/img.md).
+
+### Card
+
+A card is `<view>` with authored surface styling (border, radius, padding,
+background), not an element. Grouping, list membership, and activation stay
+with the existing contracts: `<view role="list">` + keyed `{#each}` for
+collections, and a wrapping [`<region>`](../drafts/v0/elements/region.md) when
+the whole card is one activation target. See the current
+[v0 `<view>` page](../drafts/v0/elements/view.md).
diff --git a/docs/widgets/surfaces/README.md b/docs/widgets/surfaces/README.md
index 37eed7e..ad66345 100644
--- a/docs/widgets/surfaces/README.md
+++ b/docs/widgets/surfaces/README.md
@@ -9,4 +9,9 @@ orchestration primitives that sit outside the ordinary element tree.
 Version-scoped surface entries must separate semantic lifecycle from
 renderer-owned presentation, focus mechanics, and motion.
 
-No surfaces are documented here yet.
+Version-scoped surface pages live with the current draft:
+
+- [v0 `sheet`](../drafts/v0/surfaces/sheet.md) — the implemented default
+  modality and its structural dismiss lifecycle.
+- [v0 `dialog`](../drafts/v0/surfaces/dialog.md) — a named modality with no
+  accepted design or realization yet.