@gunkin/uiify 0.0.14-alpha → 0.0.16-alpha

package/README.md

@@ -7,7 +7,7 @@ Native-first, accessible React 19 components that work before hydration.
 ## Install
 
 ```bash
-npm install @gunkin/uiify@alpha react react-dom
+npm install @gunkin/uiify react react-dom
 ```
 
 ## Use
@@ -32,6 +32,51 @@ export function SaveButton() {
 Use focused `@gunkin/uiify/components/*`, `@gunkin/uiify/elements/*`, `@gunkin/uiify/core/*`, or `@gunkin/uiify/hooks` imports in
 Server Components so client boundaries remain explicit.
 
+## AI coding agents
+
+`@gunkin/uiify` ships rules, a component index and per-component references that match the
+installed version. Add one line to your project's `AGENTS.md`, or to `CLAUDE.md` for Claude Code
+(it does not read `AGENTS.md`):
+
+```text
+For @gunkin/uiify, read node_modules/@gunkin/uiify/agents/index.md
+```
+
+In a monorepo with hoisted dependencies, point to the nearest `node_modules/@gunkin/uiify`.
+
+### `/uiify` page-building skill
+
+The package also includes the `/uiify` AI skill. Use it when an agent is creating or improving a
+web page with UIify: it maps the brief to available components, plans the page in `DESIGN.md`,
+implements the page in `src/App.tsx` when that file exists, and reports the checks it could run.
+It uses the installed package's component references and follows UIify's public styling and
+accessibility contracts. Invoke it explicitly so it runs only for page-building work.
+
+Install the skill into the directory your agent reads:
+
+```bash
+# Cross-tool Agent Skills location (Codex, Copilot, Cursor, and compatible tools)
+mkdir -p .agents/skills/uiify
+cp -R node_modules/@gunkin/uiify/skills/uiify/. .agents/skills/uiify/
+
+# For Claude Code, use this location instead
+mkdir -p .claude/skills/uiify
+cp -R node_modules/@gunkin/uiify/skills/uiify/. .claude/skills/uiify/
+```
+
+Then invoke `/uiify <page brief>` in Claude Code, or use the explicit skill invocation supported by
+your agent. Add `--auto` to run all stages without confirmation gates. Interactive runs pause at
+each stage so you can stop before implementation. The skill writes its design state to `DESIGN.md`
+and page code under `src/`; it does not create a page when `src/App.tsx` is absent.
+
+### Keeping the skill current when developing UIify
+
+When changing a UIify component, update its public component reference and example when its API or
+usage changes, and update the harness catalog when its coverage or gap status changes. Then run
+`npm run checks:fix` from the repository root. This regenerates the consumer AI docs and `/uiify`
+skill, then checks their tests and freshness. Review and commit generated changes with the component
+change. `npm run check:ai-harness` runs the focused tests and freshness checks without rewriting files.
+
 Documentation: https://uiify.gunkin.dev/
 
 MIT © Anton Gunkin

package/agents/components.md

@@ -0,0 +1,80 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# @gunkin/uiify — component index
+
+Rules and anti-patterns: [index.md](./index.md). Each entry links to a generated reference with
+its exports, props and shapes; exact types are in the `.d.ts` file listed in the Types column.
+
+## Tiers
+
+| Tier | Meaning | Client JavaScript | Without JavaScript |
+| --- | --- | --- | --- |
+| 0 | RSC — zero client JavaScript | 0 kB | full |
+| 1 | RSC shell + thin client island | <= 1 kB | degraded-documented |
+| 2 | Client component — pre-hydration SSR | n/a | pre-hydration-only |
+
+## State sources
+
+| Source | Meaning |
+| --- | --- |
+| S1 | Native element state — browser owns it and updates the accessibility tree itself |
+| S2 | Hidden input + :has() propagation — CSS-readable, ARIA needs a client island |
+| none | Stateless markup |
+
+## Components
+
+| Component | Import | Tier | State | Native element | Types | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| [accordion](./reference/components/accordion.md) | `@gunkin/uiify/components/accordion` | 0 | S1 | `details[name]` | `dist/components/accordion.d.ts` | Native details/summary disclosure; name groups single-open items. Built on @gunkin/uiify/elements/details. |
+| [alert-modal](./reference/components/alert-modal.md) | `@gunkin/uiify/components/alert-modal` | 0 | S1 | `dialog[role=alertdialog] + command=show-modal` | `dist/components/alert-modal.d.ts` | Native modal alertdialog via show-modal; Cancel/Action are request-close invokers. Baseline Chrome 139 / Firefox 147 / Safari 26.2; below it UIEnhance's invoker fallback runs the command after hydration. |
+| [breadcrumb](./reference/components/breadcrumb.md) | `@gunkin/uiify/components/breadcrumb` | 0 | none | `nav>ol` | `dist/components/breadcrumb.d.ts` | Ellipsis expand/collapse is a native details/summary disclosure, built on @gunkin/uiify/elements/details. |
+| [button](./reference/components/button.md) | `@gunkin/uiify/components/button` | 0 | none | `button` | `dist/components/button.d.ts` |  |
+| [candle-chart](./reference/components/candle-chart.md) | `@gunkin/uiify/components/candle-chart` | 0 | none | `figure>ol>li` | `dist/components/candle-chart.d.ts` | Static OHLC geometry is computed during render and expressed as percentage CSS custom properties; the decorative candle glyphs have an accessible table fallback. |
+| [line-chart](./reference/components/line-chart.md) | `@gunkin/uiify/components/line-chart` | 0 | none | `figure>ol>li` | `dist/components/line-chart.d.ts` | Static line segments are computed during render and expressed as percentage CSS custom properties; the decorative CSS line has an accessible table fallback. |
+| [carousel](./reference/components/carousel.md) | `@gunkin/uiify/components/carousel` | 2 | none | `section > div[scroll-snap]` | `dist/components/carousel.d.ts` | The documented interactive carousel uses /client and requires hydration for synchronized controls. The base entry remains a native no-JS scroller with CSS Scroll Snap and fragment navigation; /fade adds client-driven CSS transitions. |
+| [checkbox](./reference/components/checkbox.md) | `@gunkin/uiify/components/checkbox` | 0 | S1 | `input[type=checkbox]` | `dist/components/checkbox.d.ts` | Native checkbox + label; default entry ships controlled callbacks with use client. |
+| [collapsible](./reference/components/collapsible.md) | `@gunkin/uiify/components/collapsible` | 0 | S1 | `details` | `dist/components/collapsible.d.ts` | Native details/summary disclosure. Built on @gunkin/uiify/elements/details. |
+| [modal](./reference/components/modal.md) | `@gunkin/uiify/components/modal` | 0 | S1 | `dialog + command=show-modal` | `dist/components/modal.d.ts` | True modal via show-modal/request-close; the browser owns inertness, Escape and focus return. Controlled/initially open state lives in @gunkin/uiify/components/modal/client. Trigger/Close built on @gunkin/uiify/elements/dialog. Backdrop tap and swipe-down are optional UIEnhance improvements; without them the modal still closes by icon, Escape and (Chrome/Firefox) backdrop tap. |
+| [drawer](./reference/components/drawer.md) | `@gunkin/uiify/components/drawer` | 0 | S1 | `dialog + command=show-modal` | `dist/components/drawer.d.ts` | DrawerPanel native shell + compound Drawer.* client API; snap-point drag on client entry. |
+| [field](./reference/components/field.md) | `@gunkin/uiify/components/field` | 0 | none | `div:has(input)` | `dist/components/field.d.ts` | :user-invalid + :has() reveals the error message |
+| [form](./reference/components/form.md) | `@gunkin/uiify/components/form` | 0 | none | `form` | `dist/components/form.d.ts` |  |
+| [input](./reference/components/input.md) | `@gunkin/uiify/components/input` | 0 | S1 | `input` | `dist/components/input.d.ts` |  |
+| [pagination](./reference/components/pagination.md) | `@gunkin/uiify/components/pagination` | 0 | none | `nav>ol>a` | `dist/components/pagination.d.ts` |  |
+| [popup](./reference/components/popup.md) | `@gunkin/uiify/components/popup` | 0 | S1 | `[popover]+popovertarget` | `dist/components/popup.d.ts` | Native parts anchor to their invoker (implicit anchor) and carry no aria-expanded; Chromium exposes expanded through the accessibility tree, other engines are unmeasured. The legacy Popup.Root compound keeps UIEnhance for its DOM attribute. Trigger/Content/Close built on @gunkin/uiify/elements/popover. |
+| [radio-group](./reference/components/radio-group.md) | `@gunkin/uiify/components/radio-group` | 0 | S1 | `input[type=radio]` | `dist/components/radio-group.d.ts` | Data-driven native radio group; browser owns selection. Built on @gunkin/uiify/elements/choice. |
+| [rating](./reference/components/rating.md) | `@gunkin/uiify/components/rating` | 0 | S1 | `input[type=radio]` | `dist/components/rating.d.ts` | Native radio group; hover preview and persisted selection are pure CSS (:checked/:hover sibling rules), no JS. Controlled value/onValueChange lives in the separate rating/client entry. Built on @gunkin/uiify/elements/choice. |
+| [segmented-control](./reference/components/segmented-control.md) | `@gunkin/uiify/components/segmented-control` | 0 | S1 | `input[type=radio]` | `dist/components/segmented-control.d.ts` | Built on @gunkin/uiify/elements/choice. |
+| [select](./reference/components/select.md) | `@gunkin/uiify/components/select` | 0 | S1 | `select` | `dist/components/select.d.ts` | Native text-only select; appearance:base-select is a Chrome+Safari cosmetic enhancement and Firefox keeps the OS picker. |
+| [skeleton](./reference/components/skeleton.md) | `@gunkin/uiify/components/skeleton` | 0 | none | `div` | `dist/components/skeleton.d.ts` |  |
+| [slider](./reference/components/slider.md) | `@gunkin/uiify/components/slider` | 0 | S1 | `input[type=range]` | `dist/components/slider.d.ts` |  |
+| [spinner](./reference/components/spinner.md) | `@gunkin/uiify/components/spinner` | 0 | none | `div` | `dist/components/spinner.d.ts` |  |
+| [switch](./reference/components/switch.md) | `@gunkin/uiify/components/switch` | 0 | S1 | `input[type=checkbox]` | `dist/components/switch.d.ts` |  |
+| [table](./reference/components/table.md) | `@gunkin/uiify/components/table` | 0 | none | `table` | `dist/components/table.d.ts` | Native semantic Table parts; selection, sorting and expansion use the explicit /client entry. |
+| [textarea](./reference/components/textarea.md) | `@gunkin/uiify/components/textarea` | 0 | S1 | `textarea` | `dist/components/textarea.d.ts` | field-sizing:content replaces the auto-grow JS. Baseline since Firefox 152. |
+| [toggle](./reference/components/toggle.md) | `@gunkin/uiify/components/toggle` | 0 | S1 | `input[type=checkbox]` | `dist/components/toggle.d.ts` | Native checkbox + label toggle; browser owns pressed state. |
+| [toggle-group](./reference/components/toggle-group.md) | `@gunkin/uiify/components/toggle-group` | 0 | S1 | `input[type=radio\|checkbox]` | `dist/components/toggle-group.d.ts` | Built on @gunkin/uiify/elements/choice. |
+| [tooltip](./reference/components/tooltip.md) | `@gunkin/uiify/components/tooltip` | 1 | S1 | `[popover]` | `dist/components/tooltip.d.ts` |  |
+| [hover-card](./reference/components/hover-card.md) | `@gunkin/uiify/components/hover-card` | 1 | S1 | `[popover]` | `dist/components/hover-card.d.ts` |  |
+| [toast](./reference/components/toast.md) | `@gunkin/uiify/components/toast` | 1 | S1 | `[popover] + aria-live` | `dist/components/toast.d.ts` |  |
+| [number-field](./reference/components/number-field.md) | `@gunkin/uiify/components/number-field` | 1 | S1 | `input[type=number]` | `dist/components/number-field.d.ts` |  |
+| [toolbar](./reference/components/toolbar.md) | `@gunkin/uiify/components/toolbar` | 1 | none | `div[role=toolbar]` | `dist/components/toolbar.d.ts` |  |
+| [file-upload](./reference/components/file-upload.md) | `@gunkin/uiify/components/file-upload` | 1 | S1 | `input[type=file]` | `dist/components/file-upload.d.ts` |  |
+| [header](./reference/components/header.md) | `@gunkin/uiify/components/header` | 0 | S1 | `header` | `dist/components/header.d.ts` | Semantic header root; compose native navigation with Modal. Full functionality without JavaScript; optional header/client adds scroll hide/reveal. |
+| [tabs](./reference/components/tabs.md) | `@gunkin/uiify/components/tabs` | 0 | S1 | `input[type=radio]` | `dist/components/tabs.d.ts` | Data-driven native radio switcher; CSS-only panels. Built on @gunkin/uiify/elements/choice. |
+| [dropdown-menu](./reference/components/dropdown-menu.md) | `@gunkin/uiify/components/dropdown-menu` | 2 | S2 | `[popover]+commandfor` | `dist/components/dropdown-menu.d.ts` |  |
+| [combobox](./reference/components/combobox.md) | `@gunkin/uiify/components/combobox` | 2 | S2 | `input+listbox` | `dist/components/combobox.d.ts` |  |
+| [context-menu](./reference/components/context-menu.md) | `@gunkin/uiify/components/context-menu` | 2 | S2 | `[popover]` | `dist/components/context-menu.d.ts` |  |
+| [tags-input](./reference/components/tags-input.md) | `@gunkin/uiify/components/tags-input` | 2 | none | `input` | `dist/components/tags-input.d.ts` |  |
+| [otp-input](./reference/components/otp-input.md) | `@gunkin/uiify/components/otp-input` | 2 | none | `input` | `dist/components/otp-input.d.ts` |  |
+| [color-picker](./reference/components/color-picker.md) | `@gunkin/uiify/components/color-picker` | 1 | S1 | `input[type=color]` | `dist/components/color-picker.d.ts` |  |
+| [virtual-scroll](./reference/components/virtual-scroll.md) | `@gunkin/uiify/components/virtual-scroll` | 2 | none | `div[overflow]` | `dist/components/virtual-scroll.d.ts` |  |
+| [table-of-contents](./reference/components/table-of-contents.md) | `@gunkin/uiify/components/table-of-contents` | 2 | S1 | `nav + button[popovertarget] + [popover] + a[href]` | `dist/components/table-of-contents.d.ts` | Base entry is a server-pure native navigation shell; /client adds enhancements. Native links and popover invocation/dismissal work without JavaScript. |
+
+## Elements
+
+| Element | Import | Native mechanism | Parts | Used by | Types |
+| --- | --- | --- | --- | --- | --- |
+| [invoker](./reference/elements/invoker.md) | `@gunkin/uiify/elements/invoker` | command/commandfor attributes | `Invoker` | dialog | `dist/elements/invoker.d.ts` |
+| [dialog](./reference/elements/dialog.md) | `@gunkin/uiify/elements/dialog` | dialog + command=show-modal | `Dialog.Trigger`, `Dialog.Content`, `Dialog.Close` | modal, alert-modal, drawer | `dist/elements/dialog.d.ts` |
+| [popover](./reference/elements/popover.md) | `@gunkin/uiify/elements/popover` | [popover] + popovertarget | `Popover.Trigger`, `Popover.Surface`, `Popover.Close` | popup | `dist/elements/popover.d.ts` |
+| [details](./reference/elements/details.md) | `@gunkin/uiify/elements/details` | details/summary | `Details.Root`, `Details.Summary`, `Details.Content` | accordion, collapsible, breadcrumb | `dist/elements/details.d.ts` |
+| [choice](./reference/elements/choice.md) | `@gunkin/uiify/elements/choice` | input[type=radio\|checkbox] + label | `Choice.Group`, `Choice.Item` | radio-group, tabs, toggle-group, segmented-control, rating | `dist/elements/choice.d.ts` |

package/agents/index.md

@@ -0,0 +1,179 @@
+# @gunkin/uiify — rules for AI coding agents
+
+This file ships inside the installed package, so it always matches the version in `node_modules`.
+Read it before writing code that imports `@gunkin/uiify`.
+
+- Component list, tiers and import paths: [components.md](./components.md)
+- Per-component exports, props and shapes: the reference file linked from `components.md`
+- Exact types: the `.d.ts` file listed for each entry in `components.md`
+- Docs site: https://uiify.gunkin.dev/
+
+## What you will probably get wrong
+
+Models trained on Radix, shadcn/ui and similar libraries reach for their idioms. These do not
+exist here.
+
+| You are about to write | Write this instead | Why |
+| --- | --- | --- |
+| `asChild` | `as="a"` or `render={...}` | There is no Slot. Polymorphism is `as` or `render`. |
+| `cva(...)` or another class-string builder | `variant` / `size` props, and CSS on `[data-variant]` / `[data-size]` | Props only write a `data-*` attribute; the rules live in CSS. |
+| `className={(state) => ...}` | A plain string `className`; select state with `[data-state]`, `[data-disabled]` and friends | `className` is never a function. |
+| `contentClassName`, `triggerClassName`, `itemClassName`, `contentStyle` | `className` / `style` on the part itself | Every public part takes its own `className`. |
+| `onChange={(value) => ...}` on a root or control | `onValueChange`, `onOpenChange`, `onCheckedChange`, `onPageChange` | `onChange` is the native DOM `change` event and receives the event. |
+| `isOpen`, `isDisabled`, `isChecked` | `open`, `disabled`, `checked` | No `is` prefix. |
+| `placement="bottom-start"` | `side="bottom" align="start"` | One vocabulary for popups. |
+| `data-open` | `data-state="open"` | Open state is `data-state`; there is no `data-open`. |
+| React context or child cloning to connect parts | The shared id you pass to each part: `fieldId`, `target` | Server-compatible parts are wired by ids, not context. |
+
+## Vocabulary
+
+| Concept | Props | Attribute |
+| --- | --- | --- |
+| Controlled value | `value`, `defaultValue`, `onValueChange(value)` | |
+| Open state | `open`, `defaultOpen`, `onOpenChange(open)` | `data-state="open"` or `"closed"` |
+| Checked state | `checked`, `defaultChecked`, `onCheckedChange` | `data-state="checked"`, `"unchecked"` or `"indeterminate"` on controlled checkboxes and switches; style uncontrolled inputs with `:checked` |
+| Current page | `page`, `defaultPage`, `onPageChange(page)` | |
+| Visual style | `variant` (omit for the default solid style) | `data-variant` |
+| Scale | `size` | `data-size` |
+| Direction | `orientation` | `data-orientation` |
+| Popup placement | `side`, `align` | `data-side`, `data-align` |
+| Form flags | `disabled`, `required`, `readOnly`, `invalid` | `data-disabled`, `data-required`, `data-readonly`, `data-invalid` |
+
+Other state attributes: `data-highlighted`, `data-selected`, `data-positioning`, and
+`data-active` on the active slot of the OTP input. Every public root and standalone part carries an
+identity marker, for example `data-uiify-button`; compound parts carry a kebab-case `data-part`. The values of `variant` and
+`size` differ per component: read the component's reference file.
+
+## Examples
+
+Variants and sizes are props that write attributes:
+
+```tsx
+import { Button } from "@gunkin/uiify/components/button";
+
+export function RemoveButton() {
+  return (
+    <Button variant="destructive" size="sm" type="button">
+      Remove
+    </Button>
+  );
+}
+```
+
+`as` swaps the rendered element and keeps the component's behavior:
+
+```tsx
+import { Button } from "@gunkin/uiify/components/button";
+
+export function BillingLink() {
+  return (
+    <Button as="a" href="/billing" variant="link">
+      Billing
+    </Button>
+  );
+}
+```
+
+Native server parts do not share React context. Each part names its root with an id you choose:
+
+```tsx
+import { Field } from "@gunkin/uiify/components/field";
+
+export function EmailField({ invalid }: { readonly invalid: boolean }) {
+  return (
+    <Field.Root id="email" invalid={invalid} required>
+      <Field.Label fieldId="email" required>
+        Email
+      </Field.Label>
+      <Field.Control as="input" fieldId="email" type="email" invalid={invalid} required />
+      <Field.Description fieldId="email">We only use it to send receipts.</Field.Description>
+      <Field.Error fieldId="email" invalid={invalid}>
+        Enter a valid email address
+      </Field.Error>
+    </Field.Root>
+  );
+}
+```
+
+A trigger and its close button reference the dialog by `id` and `target`:
+
+```tsx
+import { Modal, ModalClose } from "@gunkin/uiify/components/modal";
+
+export function DeleteProject() {
+  return (
+    <Modal
+      id="delete-project"
+      title="Delete project?"
+      description="This cannot be undone."
+      trigger="Delete project"
+      footer={<ModalClose target="delete-project">Cancel</ModalClose>}
+    >
+      <p>All files in the project will be removed.</p>
+    </Modal>
+  );
+}
+```
+
+This is the wrong version of the second example:
+
+```tsx wrong
+<Button asChild className={cva("px-4", { variants: {} })}>
+  <a href="/billing">Billing</a>
+</Button>
+```
+
+## Style with attributes
+
+Components ship behavior CSS only; the theme is optional. Load both from one stylesheet and
+declare the layer order on its first line:
+
+```css
+@layer reset, tokens, base, demo, components, utilities, theme, ui, app;
+@import "@gunkin/uiify/components/behavior.css";
+@import "@gunkin/uiify/styles/reset";
+@import "@gunkin/uiify/styles/tokens";
+@import "@gunkin/uiify/styles";
+```
+
+`behavior.css` declares `ui.reset, ui.behavior, ui.tokens, ui.theme, app` and the theme declares
+`reset, tokens, base, demo, components, utilities, theme`. Layers rank by first declaration, so
+the statement above only works if nothing loads `behavior.css` earlier: do not also import it from
+JavaScript. Unlayered rules beat every layer.
+
+With that order in place, rules in the `app` layer win over the library:
+
+```css
+@layer app {
+  [data-uiify-button][data-variant="destructive"] {
+    text-transform: uppercase;
+  }
+}
+```
+
+## Imports
+
+- `@gunkin/uiify/components/<name>`: components (names in `components.md`)
+- `@gunkin/uiify/elements/<name>`: native-element primitives for building your own anatomy
+- `@gunkin/uiify/hooks`: hooks
+- `@gunkin/uiify/core/<name>`: React-agnostic stores and render helpers
+- `@gunkin/uiify/components/behavior.css`: required behavior CSS, no visual styles
+- `@gunkin/uiify/styles`: optional theme; also `styles/tokens`, `styles/reset`, `styles/tailwind`
+
+## Server Components and hydration
+
+Check a component's tier in `components.md` before importing it into a Server Component.
+
+- Tier 0 renders with zero client JavaScript and works without JavaScript.
+- Tier 1 is a server shell with a small client island.
+- Tier 2 is a client component. It renders native-first markup before hydration, but keyboard
+  behavior and ARIA sync need hydration.
+
+Some components also have sub-entries such as `@gunkin/uiify/components/modal/client` for
+controlled state. They are listed under **Sub-entries** in the component's reference file.
+
+TableOfContents has a server-pure base entry for native popover buttons and fragment links.
+Import `@gunkin/uiify/components/table-of-contents/client` for scrollspy, hover opening,
+pinning and controlled `value`/`open`. Provide unique `Content.id` and matching `Trigger.target`,
+label the navigation and trigger, and match each `Indicator.value` to a target heading ID.
+The client Root owns context for its parts. A permanent list omits Trigger and Content.

package/agents/reference/components/accordion.md

@@ -0,0 +1,35 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# accordion
+
+- Import: `@gunkin/uiify/components/accordion`
+- Tier 0 (RSC — zero client JavaScript); state source S1; native element `details[name]`
+- Without JavaScript: full
+- Types file: `dist/components/accordion.d.ts`
+- Note: Native details/summary disclosure; name groups single-open items. Built on @gunkin/uiify/elements/details.
+
+## Exports
+
+- Runtime: `Accordion`
+- Types: `AccordionItem`, `AccordionProps`, `AccordionType`
+
+## Values
+
+- `AccordionType`: `"single" | "multiple"`
+
+## Props and shapes
+
+### AccordionItem
+
+Extends: `ChoicePanelItem`
+
+No own members.
+
+### AccordionProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes |  |
+| `items` | `readonly AccordionItem[]` | yes |  |
+| `type` | `AccordionType` | no |  |
+| `defaultValue` | `string \| readonly string[]` | no |  |
+| `className` | `string` | no |  |

package/agents/reference/components/alert-modal.md

@@ -0,0 +1,63 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# alert-modal
+
+- Import: `@gunkin/uiify/components/alert-modal`
+- Tier 0 (RSC — zero client JavaScript); state source S1; native element `dialog[role=alertdialog] + command=show-modal`
+- Without JavaScript: full
+- Types file: `dist/components/alert-modal.d.ts`
+- Note: Native modal alertdialog via show-modal; Cancel/Action are request-close invokers. Baseline Chrome 139 / Firefox 147 / Safari 26.2; below it UIEnhance's invoker fallback runs the command after hydration.
+
+## Exports
+
+- Runtime: `AlertModal`, `AlertModalAction`, `AlertModalCancel`, `AlertModalContent`, `AlertModalTrigger`
+- Types: `AlertModalActionOwnProps`, `AlertModalActionProps`, `AlertModalCancelOwnProps`, `AlertModalCancelProps`, `AlertModalContentOwnProps`, `AlertModalContentProps`, `AlertModalProps`, `AlertModalTriggerOwnProps`, `AlertModalTriggerProps`
+
+## Props and shapes
+
+### AlertModalProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes |  |
+| `trigger` | `ReactNode` | yes |  |
+| `title` | `ReactNode` | yes |  |
+| `description` | `ReactNode` | no |  |
+| `children` | `ReactNode` | no |  |
+| `actionLabel` | `ReactNode` | no |  |
+| `cancelLabel` | `ReactNode` | no |  |
+| `className` | `string` | no |  |
+
+### AlertModalTriggerOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `target` | `string` | yes | `id` of the `AlertModalContent` this button opens. |
+
+### AlertModalActionOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `target` | `string` | yes |  |
+
+### AlertModalCancelOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `target` | `string` | yes |  |
+
+### AlertModalContentOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `id` | `string` | yes |  |
+
+## Other types
+
+- `AlertModalTriggerProps<TAs>`: `NativeButtonProps<TAs, AlertModalTriggerOwnProps>`
+- `AlertModalActionProps<TAs>`: `NativeButtonProps<TAs, AlertModalActionOwnProps>`
+- `AlertModalCancelProps<TAs>`: `NativeButtonProps<TAs, AlertModalCancelOwnProps>`
+- `AlertModalContentProps`: `AlertModalContentOwnProps & Omit<ComponentPropsWithRef<"dialog">, keyof AlertModalContentOwnProps | "open" | "popover" | "role">` — `<dialog role="alertdialog">`; `role`, `open` and `popover` belong to the part.

package/agents/reference/components/breadcrumb.md

@@ -0,0 +1,72 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# breadcrumb
+
+- Import: `@gunkin/uiify/components/breadcrumb`
+- Tier 0 (RSC — zero client JavaScript); state source none; native element `nav>ol`
+- Without JavaScript: full
+- Types file: `dist/components/breadcrumb.d.ts`
+- Note: Ellipsis expand/collapse is a native details/summary disclosure, built on @gunkin/uiify/elements/details.
+
+## Exports
+
+- Runtime: `Breadcrumb`, `BreadcrumbEllipsis`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbList`, `BreadcrumbRoot`, `BreadcrumbSeparator`
+- Types: `BreadcrumbItemData`, `BreadcrumbItemProps`, `BreadcrumbLinkOwnProps`, `BreadcrumbLinkProps`, `BreadcrumbListOwnProps`, `BreadcrumbListProps`, `BreadcrumbRootOwnProps`, `BreadcrumbRootProps`, `BreadcrumbSeparatorOwnProps`, `BreadcrumbSeparatorProps`
+
+## Props and shapes
+
+### BreadcrumbRootOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `"aria-label"` | `string` | no |  |
+
+### BreadcrumbItemData
+
+One logical breadcrumb entry. Used by `BreadcrumbList`'s `items` prop — the data-driven alternative to `children` that `maxItems` collapsing requires (see BreadcrumbList's own doc comment for why).
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | `string` | yes |  |
+| `current` | `boolean` | no |  |
+| `href` | `string` | no |  |
+| `label` | `ReactNode` | yes |  |
+
+### BreadcrumbListOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `items` | `readonly BreadcrumbItemData[]` | no | Data-driven items, required to use `maxItems`. Filtering children by element type (`isValidElement` + a type check) can't see through a Fragment-free `.map()` over route data into a custom wrapper component — a real element only becomes visible to a parent's child introspection once React actually renders it, which hasn't happened yet when `BreadcrumbList` itself runs. An explicit array has no such blind spot. |
+| `itemsAfterCollapse` | `number` | no |  |
+| `itemsBeforeCollapse` | `number` | no |  |
+| `maxItems` | `number` | no |  |
+| `separator` | `ReactNode` | no |  |
+
+### BreadcrumbLinkOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `current` | `boolean` | no |  |
+| `href` | `string` | no |  |
+
+### BreadcrumbSeparatorOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+
+### BreadcrumbEllipsisProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `hiddenItems` | `readonly BreadcrumbItemData[]` | yes |  |
+| `separator` | `ReactNode` | no |  |
+
+## Other types
+
+- `BreadcrumbRootProps<TAs>`: `RenderableProps<TAs, BreadcrumbRootOwnProps, Record<string, never>, HTMLElement>`
+- `BreadcrumbListProps<TAs>`: `RenderableProps<TAs, BreadcrumbListOwnProps, Record<string, never>, HTMLOListElement>`
+- `BreadcrumbItemProps<TAs>`: `RenderableProps<TAs, { readonly children?: ReactNode }, Record<string, never>, HTMLLIElement>`
+- `BreadcrumbLinkProps<TAs>`: `RenderableProps<TAs, BreadcrumbLinkOwnProps, { current: boolean }, HTMLAnchorElement>`
+- `BreadcrumbSeparatorProps<TAs>`: `RenderableProps<TAs, BreadcrumbSeparatorOwnProps, Record<string, never>, HTMLElement>`

package/agents/reference/components/button.md

@@ -0,0 +1,40 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# button
+
+- Import: `@gunkin/uiify/components/button`
+- Tier 0 (RSC — zero client JavaScript); state source none; native element `button`
+- Without JavaScript: full
+- Types file: `dist/components/button.d.ts`
+
+## Exports
+
+- Runtime: `Button`
+- Types: `ButtonOwnProps`, `ButtonProps`, `ButtonSize`, `ButtonState`, `ButtonVariant`
+
+## Values
+
+- `ButtonVariant`: `"secondary" | "outline" | "ghost" | "destructive" | "link"`
+- `ButtonSize`: `"sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg"`
+
+## Props and shapes
+
+### ButtonOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | no |  |
+| `selected` | `boolean` | no | Marks the button as the chosen one of a set, or a toggle that is on. |
+| `type` | `"button" \| "submit" \| "reset"` | no |  |
+| `size` | `ButtonSize` | no |  |
+| `variant` | `ButtonVariant` | no |  |
+
+### ButtonState
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | yes |  |
+| `selected` | `boolean` | yes |  |
+
+## Other types
+
+- `ButtonProps<TAs>`: `RenderableProps<TAs, ButtonOwnProps, ButtonState, HTMLElement>`

package/agents/reference/components/candle-chart.md

@@ -0,0 +1,107 @@
+<!-- Generated from the package source. Do not edit by hand. -->
+# candle-chart
+
+- Import: `@gunkin/uiify/components/candle-chart`
+- Tier 0 (RSC — zero client JavaScript); state source none; native element `figure>ol>li`
+- Without JavaScript: full
+- Types file: `dist/components/candle-chart.d.ts`
+- Note: Static OHLC geometry is computed during render and expressed as percentage CSS custom properties; the decorative candle glyphs have an accessible table fallback.
+
+## Exports
+
+- Runtime: `CandleChart`
+- Types: `CandleChartAxisLabel`, `CandleChartData`, `CandleChartOwnProps`, `CandleChartPointerPosition`, `CandleChartProps`
+
+## Props and shapes
+
+### CandleChartData
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `time` | `string \| number` | yes |  |
+| `open` | `number` | yes |  |
+| `high` | `number` | yes |  |
+| `low` | `number` | yes |  |
+| `close` | `number` | yes |  |
+
+### CandleChartAxisLabel
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | yes |  |
+| `position` | `number` | yes | Position on the axis as a percentage from 0 to 100. |
+
+### CandleChartPointerPosition
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `index` | `number` | yes |  |
+| `offsetY` | `number` | yes | Pointer offset inside the candle hit area, in CSS pixels. |
+
+### CandleChartOwnProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `"aria-label"` | `string` | no |  |
+| `activeCandleIndex` | `number` | no |  |
+| `cursorY` | `number` | no |  |
+| `data` | `readonly CandleChartData[]` | yes |  |
+| `interactive` | `boolean` | no |  |
+| `onCandleClick` | `(index: number) => void` | no |  |
+| `onCandlePointerLeave` | `() => void` | no |  |
+| `onCandlePointerMove` | `(position: CandleChartPointerPosition) => void` | no |  |
+| `selectedCandleIndex` | `number` | no |  |
+| `xAxis` | `readonly CandleChartAxisLabel[]` | no |  |
+| `yAxis` | `readonly CandleChartAxisLabel[]` | no |  |
+
+### CandleChartClientOwnProps
+
+Extends: `CandleChartOwnProps`
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `visibleCount` | `number` | no | Live mode: sizes candles so `visibleCount` fill the viewport and virtualizes the full history with a horizontal VirtualScroll. The chart follows new candles while the reader is at the newest one; the price scale, axes, readout, and data table follow the visible candles. Zoom is disabled. |
+
+### CandleChartViewProps
+
+Internal props the client entry passes to `CandleChart`; not part of the public API.
+
+Extends: `CandleChartOwnProps`
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `candleLayer` | `ReactNode` | no | Replaces the static candle list (e.g. with a virtualized layer). |
+| `announceReadout` | `boolean` | no | Announce readout changes; off for streaming data. Defaults to `true`. |
+| `slotCount` | `number` | no | Slots the crosshair is positioned across. Defaults to `data.length`. |
+| `slotOffset` | `number` | no | Slot of `data[0]` within those slots, when `data` is a slice. Defaults to `0`. |
+
+### CandleChartCandleProps
+
+| Member | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `"div" \| "li"` | yes |  |
+| `candle` | `CandleChartData` | yes |  |
+| `index` | `number` | yes | Index reported to the pointer and click callbacks. |
+| `x` | `number` | yes | Candle position and width, as percentages of the candle layer. |
+| `slot` | `number` | yes |  |
+| `min` | `number` | yes |  |
+| `max` | `number` | yes |  |
+| `interactive` | `boolean` | yes |  |
+| `isActive` | `boolean` | yes |  |
+| `isSelected` | `boolean` | yes |  |
+| `cursorY` | `number \| undefined` | no |  |
+| `onCandleClick` | `((index: number) => void) \| undefined` | no |  |
+| `onCandlePointerLeave` | `(() => void) \| undefined` | no |  |
+| `onCandlePointerMove` | `((position: CandleChartPointerPosition) => void) \| undefined` | no |  |
+
+## Other types
+
+- `CandleChartProps<TAs>`: `RenderableProps<TAs, CandleChartOwnProps, Record<string, never>, HTMLElement>`
+- `CandleChartClientProps<TAs>`: `RenderableProps<TAs, CandleChartClientOwnProps, Record<string, never>, HTMLElement>`
+
+## Sub-entries
+
+### `@gunkin/uiify/components/candle-chart/client`
+
+- Runtime: `CandleChartClient`
+- Types: `CandleChartClientOwnProps`, `CandleChartClientProps`