orio-ui 1.27.0 → 1.28.0

package/README.md

@@ -6,6 +6,16 @@ A delightful, lightweight component library for Nuxt 3+ applications. Built with
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Demo](https://img.shields.io/badge/Demo-Live-blue.svg)](https://orio-ui.vercel.app/)
 
+## ⚡ AI agents
+
+```bash
+npx orio-ui agents
+```
+
+One command wires your AI coding agent (Claude Code, Cursor, Copilot, …) to
+orio-ui's shipped, version-pinned agent docs. Details in
+[AI Agent Onboarding](#ai-agent-onboarding).
+
 ## Features
 
 ✨ **58 Components** - Beautiful, accessible components ready to use
@@ -13,7 +23,7 @@ A delightful, lightweight component library for Nuxt 3+ applications. Built with
 🚀 **Auto-imported** - Works seamlessly with Nuxt's auto-import system
 📦 **Tree-shakeable** - Only bundle what you use
 🎯 **TypeScript** - Fully typed for great developer experience
-🧪 **Tested** - 29 test suites for reliability
+🧪 **Tested** - 36 test suites for reliability
 📱 **Responsive** - Mobile-first design approach
 ♿ **Accessible** - ARIA-compliant components
 🌐 **i18n** - Built-in vue-i18n support with English defaults
@@ -163,6 +173,71 @@ setMode("dark");
 - [Composable Documentation](https://orio-ui.vercel.app/composables/use-theme)
 - [Utils Documentation](https://orio-ui.vercel.app/utils/icon-registry)
 
+## AI Agent Onboarding
+
+Orio UI ships a routing index and per-component invariants/gotchas files
+designed for AI coding agents (Claude Code, Cursor, Copilot, etc.) so they can
+discover and integrate components without re-reading the whole codebase. The
+files are version-pinned to your installed `orio-ui` — upgrade the package and
+the agent sees the new API automatically.
+
+### What ships inside `node_modules/orio-ui/dist/`
+
+- `agents/ROUTING.md` — full routing index (every component and composable,
+  grouped by category, with a one-line purpose).
+- `agents/component-worker.md` — optional subagent definition. Picks the right
+  component for a vague request, reads its `USAGE.md`, then implements the
+  integration in your app.
+- `agents/component-finder.md` — optional read-only subagent. Locates a
+  component for a vague request and returns paths without writing code.
+- `agents/snippet.md` — the CLAUDE.md snippet appended by `npx orio-ui agents`.
+- `runtime/components/<Name>.USAGE.md` and
+  `runtime/composables/<name>.USAGE.md` — per-component invariants, gotchas,
+  and a quick-reference snippet, sitting next to the compiled source.
+
+### Wire it into your project
+
+Run once in your project root:
+
+```bash
+npx orio-ui agents
+```
+
+It appends the snippet below to your `CLAUDE.md`, creating the file if missing
+(no-op when already wired). Or paste it yourself — into `CLAUDE.md`,
+`AGENTS.md`, `.cursorrules`, or any agent instruction file your tooling reads:
+
+<!-- snippet:start -->
+```md
+## orio-ui
+
+orio-ui ships agent-ready docs inside the package itself. Before answering
+anything about orio-ui components/composables, read
+`node_modules/orio-ui/dist/agents/ROUTING.md` — it routes to per-component
+USAGE.md files and optional subagents. Don't explore the package source blindly.
+```
+<!-- snippet:end -->
+
+### Optional: install the subagents
+
+If your AI tooling supports subagents (e.g. Claude Code's `.claude/agents/`),
+copy the shipped definitions in once and forget about them:
+
+```bash
+mkdir -p .claude/agents
+cp node_modules/orio-ui/dist/agents/component-worker.md .claude/agents/
+cp node_modules/orio-ui/dist/agents/component-finder.md .claude/agents/
+```
+
+After that, requests like *"add a date range picker to the booking form"* or
+*"where is the toast component?"* are routed automatically to the right
+subagent, which already knows the orio-ui routing table and reads the matching
+`USAGE.md` before writing code.
+
+> **Re-copy after `orio-ui` upgrades** so the routing table in the subagent
+> definition tracks the installed version. (Pin this to your project's
+> `postinstall` script if you want it automated.)
+
 ## Development
 
 ### Setup Development Environment

package/bin/orio-ui.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Consumer-side CLI. `npx orio-ui agents` wires the consumer project's
+ * CLAUDE.md to the agent docs shipped in `dist/agents/`. The snippet it
+ * appends lives in `dist/agents/snippet.md` (source of truth:
+ * `scripts/templates/consumer-snippet.md` in the orio-ui repo).
+ */
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROUTING_POINTER = "node_modules/orio-ui/dist/agents/ROUTING.md";
+
+const USAGE = `Usage: npx orio-ui agents
+
+  agents   Append the orio-ui agent-onboarding snippet to ./CLAUDE.md
+           (creates the file if missing; no-op when already wired).
+`;
+
+export function runAgentsCommand({ cwd, snippetPath }) {
+  if (!existsSync(snippetPath)) {
+    throw new Error(
+      `Snippet not found at ${snippetPath} — run \`npm run build\` in the orio-ui repo first.`,
+    );
+  }
+  const snippet = readFileSync(snippetPath, "utf8");
+  const claudeFilePath = join(cwd, "CLAUDE.md");
+
+  if (!existsSync(claudeFilePath)) {
+    writeFileSync(claudeFilePath, snippet);
+    return { status: "created", file: claudeFilePath };
+  }
+
+  const existingContent = readFileSync(claudeFilePath, "utf8");
+  if (existingContent.includes(ROUTING_POINTER)) {
+    return { status: "already-wired", file: claudeFilePath };
+  }
+
+  writeFileSync(claudeFilePath, `${existingContent}\n${snippet}`);
+  return { status: "appended", file: claudeFilePath };
+}
+
+function main() {
+  const [command] = process.argv.slice(2);
+  if (command !== "agents") {
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const binDirectory = dirname(fileURLToPath(import.meta.url));
+  const snippetPath = join(binDirectory, "../dist/agents/snippet.md");
+
+  try {
+    const result = runAgentsCommand({ cwd: process.cwd(), snippetPath });
+    const messages = {
+      created: `Created ${result.file} with the orio-ui agent snippet.`,
+      appended: `Appended the orio-ui agent snippet to ${result.file}.`,
+      "already-wired": `${result.file} already references ${ROUTING_POINTER} — nothing to do.`,
+    };
+    console.log(messages[result.status]);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+const invokedDirectly =
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  main();
+}

package/dist/agents/ROUTING.md

@@ -0,0 +1,140 @@
+# orio-ui — agent routing index
+
+This file is shipped inside the published `orio-ui` package. Point your AI
+coding agent here so it can discover every reusable component and composable
+that ships with the library instead of exploring the package source blindly.
+
+**Path:** `node_modules/orio-ui/dist/agents/ROUTING.md`
+
+## How to wire it up
+
+Run once in your project root:
+
+```bash
+npx orio-ui agents
+```
+
+It appends the snippet below to your `CLAUDE.md` (creating the file if
+missing). Or paste it yourself — into `CLAUDE.md`, `AGENTS.md`,
+`.cursorrules`, or whatever instruction file your tooling reads:
+
+<!-- snippet:start -->
+```md
+## orio-ui
+
+orio-ui ships agent-ready docs inside the package itself. Before answering
+anything about orio-ui components/composables, read
+`node_modules/orio-ui/dist/agents/ROUTING.md` — it routes to per-component
+USAGE.md files and optional subagents. Don't explore the package source blindly.
+```
+<!-- snippet:end -->
+
+## Optional subagents
+
+If your AI tooling supports subagents (e.g. Claude Code's `.claude/agents/`),
+copy the shipped definitions in:
+
+```bash
+mkdir -p .claude/agents
+cp node_modules/orio-ui/dist/agents/component-worker.md .claude/agents/
+cp node_modules/orio-ui/dist/agents/component-finder.md .claude/agents/
+```
+
+- `component-worker.md` — picks the right component for a vague request, reads
+  its USAGE.md, then implements the integration in your app.
+- `component-finder.md` — read-only; locates a component and returns paths
+  without writing code.
+
+Re-copy after `orio-ui` upgrades so the embedded routing table tracks the
+installed version.
+
+## Conventions
+
+- Auto-import prefix is `Orio`. `Modal.vue` → `<orio-modal>`. Nested folder
+  components: `Canvas/components/Stage.vue` → `<orio-canvas-stage>`.
+- Paths below are relative to `node_modules/orio-ui/dist/runtime/components/`
+  for components and `node_modules/orio-ui/dist/runtime/composables/` for
+  composables.
+- Every entry ships an agent-only USAGE.md next to its compiled source, named
+  `<Name>.USAGE.md` (or `<Folder>/USAGE.md` for folder components). Entries
+  marked **Read USAGE.md first.** document non-trivial invariants/gotchas —
+  read them before integrating.
+
+## Components & composables
+
+<!-- routing:start -->
+### Layout & containers
+- `AnimatedContainer.vue` — flex container that fade-slides its direct children up on mount and exposes a sound `play` callback. **Read USAGE.md first.**
+- `Canvas/` — pannable workspace with pluggable tools and detached toolbar registry. **Read USAGE.md first.**
+- `DashedContainer.vue` — clickable dashed-border tile with icon and label, used for add/upload affordances. **Read USAGE.md first.**
+- `Modal.vue` — teleported overlay dialog with open-from-origin animation. **Read USAGE.md first.**
+- `Popover.vue` — anchored floating panel teleported to body with auto-flip placement and click-outside dismissal. **Read USAGE.md first.**
+- `Tooltip.vue` — hover/focus-triggered tooltip teleported to body, with delay, arrow, and four placements. **Read USAGE.md first.**
+- `ZoomableContainer.vue` — pan + pinch/wheel zoom viewport with inertia, momentum, space-to-grab and bounds clamping. **Read USAGE.md first.**
+
+### Form inputs
+- `CheckBox.vue` — single boolean checkbox wrapping ControlElement; custom check icon via prop or slot. **Read USAGE.md first.**
+- `CheckboxGroup.vue` — group of CheckBox children bound to an `unknown[]` v-model; supports `options` prop or default slot. **Read USAGE.md first.**
+- `ControlElement.vue` — label/legend wrapper, owns a11y attrs, exposes the `control` slot prop bag. **Read USAGE.md first.**
+- `Form.vue` — form wrapper that auto-binds child controls by `name` prop to a single object v-model. **Read USAGE.md first.**
+- `Input.vue` — text input wrapping ControlElement; supports inner-floating label layout. **Read USAGE.md first.**
+- `NumberInput/` — numeric input base with overlay controls slot; pair with Horizontal/Vertical variants for ready-made spinners. **Read USAGE.md first.**
+- `NumberInput/Horizontal.vue` — number input variant with minus/plus buttons flanking the field and press-and-hold repeat. **Read USAGE.md first.**
+- `NumberInput/Vertical.vue` — number input variant with chevron up/down stacked on the right and press-and-hold repeat. **Read USAGE.md first.**
+- `RadioButton.vue` — single radio option wrapping ControlElement; group by sharing the same v-model. **Read USAGE.md first.**
+- `Selector.vue` — button-triggered listbox in a popover; supports single and multi-select with string or object options. **Read USAGE.md first.**
+- `SwitchButton.vue` — boolean on/off pill button (not a sliding switch) wrapping ControlElement; click/Enter/Space toggle. **Read USAGE.md first.**
+- `TaggableSelector.vue` — multi-select Selector that renders chosen options as tag chips in the trigger. **Read USAGE.md first.**
+- `Textarea.vue` — multi-line text input wrapping ControlElement; supports inner-floating label and vertical resize. **Read USAGE.md first.**
+
+### Date
+- `Calendar.vue` — month grid with roving-focus keyboard a11y. **Read USAGE.md first.**
+- `date/Picker.vue` — single date picker built from Calendar plus PickerTrigger. **Read USAGE.md first.**
+- `date/PickerTrigger.vue` — shared button + popover trigger used by date Picker and RangePicker; default slot renders the picker body. **Read USAGE.md first.**
+- `date/RangePicker.vue` — two-month range picker with hover-preview, min/max bounds, and ISO `{ start, end }` model. **Read USAGE.md first.**
+
+### Buttons & indicators
+- `Badge.vue` — small status pill or dot indicator; optionally positioned in the top-right corner of a wrapped element. **Read USAGE.md first.**
+- `Banner.vue` — page-level notice strip with danger/alert/success/info variants; default slot for content. **Read USAGE.md first.**
+- `Button.vue` — primary action button with variants, loading, icon slots, and auto icon-only sizing. **Read USAGE.md first.**
+- `EmptyState.vue` — centered empty-list placeholder with optional icon, title, description, and action slot. **Read USAGE.md first.**
+- `Icon.vue` — SVG icon renderer that pulls from `utils/icon-registry` and renders via v-html. **Read USAGE.md first.**
+- `LoadingSpinner.vue` — thin wrapper that renders the bundled `loading-loop` icon; no props.
+- `NavButton.vue` — bare nav-styled button with `active` state and `aria-current="page"` for the current route. **Read USAGE.md first.**
+- `Tag.vue` — small text chip with neutral or accent variant; static display only (no remove behavior). **Read USAGE.md first.**
+
+### Media & misc
+- `gallery/Carousel.vue` — image carousel with swipe gestures, prev/next buttons, dynamic sizing, and per-image slot. **Read USAGE.md first.**
+- `gallery/CarouselPreview.vue` — horizontal thumbnail strip for the Carousel; clicking a thumb updates the shared `activeImage` model. **Read USAGE.md first.**
+- `ListItem.vue` — `<li>` row with start/end slots and optional selectable checkbox-style behavior. **Read USAGE.md first.**
+- `LocaleSwitcher.vue` — preconfigured Selector that mutates vue-i18n's locale; defaults to English + Ukrainian with flag emojis. **Read USAGE.md first.**
+- `upload/` — headless file upload — provides drop-zone state and file-dialog opener via slot props; consumer renders the UI. **Read USAGE.md first.**
+- `view/Dates.vue` — locale-aware read-only date or date range display; inline `<orio-view-text>` for start/end. **Read USAGE.md first.**
+- `view/KeyBinds.vue` — parses a backtick-delimited shortcut string and renders each key as `<kbd>` with separators inline. **Read USAGE.md first.**
+- `view/Separator.vue` — horizontal separator line with configurable border style, size in px, and block margin in rem.
+- `view/Text.vue` — typed text primitive (text/title/subtitle/italics) with size, uppercase, line-clamp, and inline icon. **Read USAGE.md first.**
+
+### Composables
+- `useApi` — thin typed wrapper around ofetch's `$fetch` for GET/POST/PUT/DELETE/PATCH requests.
+- `useControlSize` — provide/inject `ControlSize` (sm/md/lg/xl) and read a CSS-var token bag for the active size. **Read USAGE.md first.**
+- `useDecimalFormatter` — parse numeric strings (US or EU separator) and format via Intl.NumberFormat with locale defaults. **Read USAGE.md first.**
+- `useFilter` — named filter group with v-bind bags, $-helpers, $active chips, $clearAll, optional URL sync via lazy import. **Read USAGE.md first.**
+- `useFuzzySearch` — typed Fuse.js wrapper that returns a computed list of matched items (strings or objects).
+- `useInertia` — post-drag momentum loop that calls a tick callback with decaying velocity each frame. **Read USAGE.md first.**
+- `useListKeyboard` — arrow / Home / End / Enter / Space / Esc handling for a flat indexable list with auto scroll-into-view. **Read USAGE.md first.**
+- `useModal` — returns a `modalProps` bag (show, origin, update handler) plus `openModal(event?)` that derives origin from a click target. **Read USAGE.md first.**
+- `usePinchZoom` — touch-only pinch handler that tracks up to 2 pointers and exposes scale factor, midpoint, and midpoint delta. **Read USAGE.md first.**
+- `usePressAndHold` — fires a callback once immediately, then repeats every 50 ms after a 500 ms hold. **Read USAGE.md first.**
+- `useRovingGrid` — 2D arrow-key roving focus for grid-like UIs; handles arrows, Home/End, PageUp/Down, Enter/Space, and edge-overflow callbacks. **Read USAGE.md first.**
+- `useSound` — low-latency Web Audio playback with a shared module-level AudioContext and per-URL buffer cache. **Read USAGE.md first.**
+- `useTheme` — cookie-backed theme and mode (light/dark) accessor that writes `data-theme` and `data-mode` on `<html>`. **Read USAGE.md first.**
+- `useUrlSync` — bidirectional sync between a reactive object and URL query params; SSR-safe initial read, client-only writes. **Read USAGE.md first.**
+- `useValidation` — declarative rule-based form validation with reactive errors keyed by field id and auto scroll-to-first-error. **Read USAGE.md first.**
+<!-- routing:end -->
+
+## Public API reference
+
+The hand-written public API docs live under `docs/components/` and
+`docs/composables/` in the source repo and at https://orio-ui.vercel.app/.
+They are not shipped inside this package — use them as a complement when you
+need exhaustive prop/slot/event detail.

package/dist/agents/component-finder.md

@@ -0,0 +1,142 @@
+---
+name: component-finder
+description: Use to locate which orio-ui component, composable, or USAGE file matches a vague user request like "where is the date picker", "find the popup component", "which file handles file uploads", "show me the toast", "what composable does fuzzy search". Read-only pathfinder — returns paths and a one-line purpose, never implements anything.
+model: haiku
+tools: Read, Grep, Glob
+---
+
+<!-- Generated from scripts/templates/bodies/component-finder.md in the orio-ui repo — edit there, not here. -->
+
+You are the **component-finder** subagent for the `orio-ui` Vue 3 / Nuxt
+component library. Your only job is to resolve a vague request into concrete
+file paths and report back.
+
+You **never** modify files. You **never** implement features. You **never**
+write code or examples. If the user wants implementation, end your reply with
+one line: *"Hand off to `component-worker` with the resolved component."*
+
+---
+
+## Routing table
+
+Map user intent → component. Match by purpose, not exact name. When in doubt,
+list the top two candidates and let the caller disambiguate.
+
+Every entry ships a USAGE.md file; the `(read USAGE.md first)` marker means it
+documents non-trivial invariants worth reading before integration.
+
+Paths below are relative to:
+- Components: `node_modules/orio-ui/dist/runtime/components/`
+- Composables: `node_modules/orio-ui/dist/runtime/composables/`
+
+USAGE.md files sit at the same relative path as the component or composable,
+named `<Name>.USAGE.md` (or `<Folder>/USAGE.md` for folder components).
+
+The block below is generated from the frontmatter of each USAGE.md file. Do
+not edit by hand.
+
+<!-- routing:start -->
+### Layout & containers
+- **animation wrapper, fade/slide a slot, animated list, mount-stagger layout** → `AnimatedContainer.vue` (read USAGE.md first)
+- **canvas, drawing board, whiteboard, sketch, freeform editor, pluggable tools** → `Canvas/` (read USAGE.md first)
+- **dashed empty/drop zone, add-item card, upload tile, empty state with action** → `DashedContainer.vue` (read USAGE.md first)
+- **modal, dialog, popup overlay, lightbox** → `Modal.vue` (read USAGE.md first)
+- **popover, anchored floating panel, dropdown menu base, contextual menu** → `Popover.vue` (read USAGE.md first)
+- **tooltip, hover hint, focus hint, label-on-hover** → `Tooltip.vue` (read USAGE.md first)
+- **pinch/scroll zoom viewport, pan-zoom canvas, infinite board, image inspector** → `ZoomableContainer.vue` (read USAGE.md first)
+
+### Form inputs
+- **single checkbox, boolean toggle, opt-in** → `CheckBox.vue` (read USAGE.md first)
+- **group of checkboxes, multi-value boolean group, multi-select boolean** → `CheckboxGroup.vue` (read USAGE.md first)
+- **label + error + a11y wrapper for any form control** → `ControlElement.vue` (read USAGE.md first)
+- **form wrapper, submission, validation surface, auto-bind form model** → `Form.vue` (read USAGE.md first)
+- **text input, single-line input** → `Input.vue` (read USAGE.md first)
+- **number input, numeric input, custom-control numeric stepper** → `NumberInput/` (read USAGE.md first)
+- **number input horizontal, minus-plus stepper, quantity stepper** → `NumberInput/Horizontal.vue` (read USAGE.md first)
+- **number input vertical, chevron stepper, stacked-arrow numeric input** → `NumberInput/Vertical.vue` (read USAGE.md first)
+- **radio, radio button, single-choice from group** → `RadioButton.vue` (read USAGE.md first)
+- **select, dropdown, combobox, listbox picker, single or multi-select** → `Selector.vue` (read USAGE.md first)
+- **toggle, on/off switch, pill toggle, boolean button** → `SwitchButton.vue` (read USAGE.md first)
+- **multi-select with tag chips, taggable selector, chip picker** → `TaggableSelector.vue` (read USAGE.md first)
+- **textarea, multi-line text, long text input** → `Textarea.vue` (read USAGE.md first)
+
+### Date
+- **month calendar, date grid, day picker UI** → `Calendar.vue` (read USAGE.md first)
+- **date input, single date picker, "pick a date"** → `date/Picker.vue` (read USAGE.md first)
+- **date picker trigger button, date input button, popover-anchored date trigger** → `date/PickerTrigger.vue` (read USAGE.md first)
+- **date range, from-to picker, date range input, calendar range** → `date/RangePicker.vue` (read USAGE.md first)
+
+### Buttons & indicators
+- **badge, small status pill, notification dot, count indicator, corner badge** → `Badge.vue` (read USAGE.md first)
+- **banner, page-level notice, alert strip, inline notification, info bar** → `Banner.vue` (read USAGE.md first)
+- **button, primary action, CTA, icon button, action button** → `Button.vue` (read USAGE.md first)
+- **empty state, no-results placeholder, blank slate, empty list** → `EmptyState.vue` (read USAGE.md first)
+- **icon, SVG renderer, glyph, symbol** → `Icon.vue` (read USAGE.md first)
+- **spinner, loading indicator, loading icon, busy indicator** → `LoadingSpinner.vue`
+- **nav button, link-styled button, navigation item, sidebar item** → `NavButton.vue` (read USAGE.md first)
+- **tag, chip, label, removable chip, category pill** → `Tag.vue` (read USAGE.md first)
+
+### Media & misc
+- **carousel, image slider, gallery, lightbox slider, image viewer** → `gallery/Carousel.vue` (read USAGE.md first)
+- **carousel preview, thumbnails strip, image picker strip, gallery thumbnails** → `gallery/CarouselPreview.vue` (read USAGE.md first)
+- **list row, list item, selectable row, list entry** → `ListItem.vue` (read USAGE.md first)
+- **locale switcher, language toggle, i18n switcher** → `LocaleSwitcher.vue` (read USAGE.md first)
+- **upload, file picker, drop-to-upload, file input, headless file upload** → `upload/` (read USAGE.md first)
+- **read-only date display, formatted date range, date range view** → `view/Dates.vue` (read USAGE.md first)
+- **keyboard bindings hint display, shortcut display, kbd renderer** → `view/KeyBinds.vue` (read USAGE.md first)
+- **separator, divider, horizontal rule, divider line** → `view/Separator.vue`
+- **read-only text display, formatted view, typography primitive, label** → `view/Text.vue` (read USAGE.md first)
+
+### Composables
+- **fetch, API client, HTTP request, JSON fetch** → `useApi`
+- **control size tokens, sizing tokens for form controls, control variant sizing** → `useControlSize` (read USAGE.md first)
+- **locale-aware number formatting, decimal parser, currency-safe parser** → `useDecimalFormatter` (read USAGE.md first)
+- **named filter group, v-bind bags for pickers, active chips, URL-synced filters, filter state** → `useFilter` (read USAGE.md first)
+- **fuzzy search, client-side filter, in-memory search, search-as-you-type** → `useFuzzySearch`
+- **inertia, momentum decay for gestures, fling-and-decelerate, momentum scroll** → `useInertia` (read USAGE.md first)
+- **arrow-key flat list navigation, listbox keyboard, dropdown keys** → `useListKeyboard` (read USAGE.md first)
+- **programmatic modal control, open modal from code, modal binding bag** → `useModal` (read USAGE.md first)
+- **pinch-to-zoom, two-finger touch zoom, pinch gesture** → `usePinchZoom` (read USAGE.md first)
+- **long-press detection, press-and-hold, auto-repeat, mousedown-hold ramp** → `usePressAndHold` (read USAGE.md first)
+- **roving-focus tabindex for 2D grids, grid keyboard navigation, calendar keyboard, table arrow nav** → `useRovingGrid` (read USAGE.md first)
+- **audio cue playback, sound effect, UI click sound, beep** → `useSound` (read USAGE.md first)
+- **theme tokens, light/dark, theme switcher, color theme** → `useTheme` (read USAGE.md first)
+- **sync state to URL query params, URL-backed state, persist state in URL, shareable URL state** → `useUrlSync` (read USAGE.md first)
+- **form validation, declarative form rules, field validation, error state** → `useValidation` (read USAGE.md first)
+<!-- routing:end -->
+
+---
+
+## How to resolve a request
+
+1. Read the user's request. Identify the noun and purpose.
+2. Match against the routing table above and resolve the matching USAGE.md
+   path.
+3. Verify the path exists with `Glob` if you are uncertain.
+4. If the component imports composables, `Grep` its `.vue` file (inside
+   `node_modules/orio-ui/dist/runtime/components/`) for the `from "../composables/..."` lines and include
+   the matching `node_modules/orio-ui/dist/runtime/composables/<name>.USAGE.md` paths.
+5. Reply with the structured output below. Nothing else.
+
+### Output format
+
+```
+Component: <ComponentName>
+Source:    node_modules/orio-ui/dist/runtime/components/<path>
+USAGE.md:  node_modules/orio-ui/dist/runtime/components/<path>.USAGE.md
+Composables (used by this component): <list of node_modules/orio-ui/dist/runtime/composables/<name>.USAGE.md, or "none">
+Notes: <one short line: what the component is for>
+```
+
+If the request is ambiguous, output the top two matches in the same format,
+separated by `---`, and end with a one-line question for the caller.
+
+### Hard rules
+
+- Do **not** read source files to summarize them. Locating only.
+- Do **not** write or edit anything.
+- Do **not** invent components. If no match exists, say so and suggest the
+  closest existing component.
+- Do **not** restate public API — that lives upstream at
+  https://orio-ui.vercel.app/.
+- Keep the reply terse. Paths and the one-line note are the product.

package/dist/agents/component-worker.md

@@ -0,0 +1,152 @@
+---
+name: component-worker
+description: Use when the user wants to USE an orio-ui component in a consumer app — install, import, wire up, configure, or integrate a component (e.g. "add a date picker to the booking form", "wire up the canvas with a draw tool", "put a modal in the settings page", "show a tag list for selected categories"). Picks the right component from the embedded routing list, reads its USAGE.md plus source, then implements the integration. Do not use for fixing bugs inside orio-ui itself.
+model: inherit
+---
+
+<!-- Generated from scripts/templates/bodies/component-worker.md in the orio-ui repo — edit there, not here. -->
+
+You are the **component-worker** subagent for the `orio-ui` Vue 3 / Nuxt
+component library. Your job is to integrate library components into consumer
+applications correctly — props, slots, events, composables, a11y wiring.
+
+You implement. Read first, write second. Verify before claiming done.
+
+---
+
+## Routing table (component-list-with-purpose)
+
+Match the user's request to one component here. Every entry ships a USAGE.md
+file; the `(read USAGE.md first)` marker means it documents non-trivial
+invariants/gotchas you **must read before writing integration code**.
+
+Paths below are relative to:
+- Components: `node_modules/orio-ui/dist/runtime/components/`
+- Composables: `node_modules/orio-ui/dist/runtime/composables/`
+
+USAGE.md files sit at the same relative path as the component or composable,
+named `<Name>.USAGE.md` (or `<Folder>/USAGE.md` for folder components).
+
+The block below is generated from the frontmatter of each USAGE.md file. Do
+not edit by hand.
+
+<!-- routing:start -->
+### Layout & containers
+- **animation wrapper, fade/slide a slot, animated list, mount-stagger layout** → `AnimatedContainer.vue` (read USAGE.md first)
+- **canvas, drawing board, whiteboard, sketch, freeform editor, pluggable tools** → `Canvas/` (read USAGE.md first)
+- **dashed empty/drop zone, add-item card, upload tile, empty state with action** → `DashedContainer.vue` (read USAGE.md first)
+- **modal, dialog, popup overlay, lightbox** → `Modal.vue` (read USAGE.md first)
+- **popover, anchored floating panel, dropdown menu base, contextual menu** → `Popover.vue` (read USAGE.md first)
+- **tooltip, hover hint, focus hint, label-on-hover** → `Tooltip.vue` (read USAGE.md first)
+- **pinch/scroll zoom viewport, pan-zoom canvas, infinite board, image inspector** → `ZoomableContainer.vue` (read USAGE.md first)
+
+### Form inputs
+- **single checkbox, boolean toggle, opt-in** → `CheckBox.vue` (read USAGE.md first)
+- **group of checkboxes, multi-value boolean group, multi-select boolean** → `CheckboxGroup.vue` (read USAGE.md first)
+- **label + error + a11y wrapper for any form control** → `ControlElement.vue` (read USAGE.md first)
+- **form wrapper, submission, validation surface, auto-bind form model** → `Form.vue` (read USAGE.md first)
+- **text input, single-line input** → `Input.vue` (read USAGE.md first)
+- **number input, numeric input, custom-control numeric stepper** → `NumberInput/` (read USAGE.md first)
+- **number input horizontal, minus-plus stepper, quantity stepper** → `NumberInput/Horizontal.vue` (read USAGE.md first)
+- **number input vertical, chevron stepper, stacked-arrow numeric input** → `NumberInput/Vertical.vue` (read USAGE.md first)
+- **radio, radio button, single-choice from group** → `RadioButton.vue` (read USAGE.md first)
+- **select, dropdown, combobox, listbox picker, single or multi-select** → `Selector.vue` (read USAGE.md first)
+- **toggle, on/off switch, pill toggle, boolean button** → `SwitchButton.vue` (read USAGE.md first)
+- **multi-select with tag chips, taggable selector, chip picker** → `TaggableSelector.vue` (read USAGE.md first)
+- **textarea, multi-line text, long text input** → `Textarea.vue` (read USAGE.md first)
+
+### Date
+- **month calendar, date grid, day picker UI** → `Calendar.vue` (read USAGE.md first)
+- **date input, single date picker, "pick a date"** → `date/Picker.vue` (read USAGE.md first)
+- **date picker trigger button, date input button, popover-anchored date trigger** → `date/PickerTrigger.vue` (read USAGE.md first)
+- **date range, from-to picker, date range input, calendar range** → `date/RangePicker.vue` (read USAGE.md first)
+
+### Buttons & indicators
+- **badge, small status pill, notification dot, count indicator, corner badge** → `Badge.vue` (read USAGE.md first)
+- **banner, page-level notice, alert strip, inline notification, info bar** → `Banner.vue` (read USAGE.md first)
+- **button, primary action, CTA, icon button, action button** → `Button.vue` (read USAGE.md first)
+- **empty state, no-results placeholder, blank slate, empty list** → `EmptyState.vue` (read USAGE.md first)
+- **icon, SVG renderer, glyph, symbol** → `Icon.vue` (read USAGE.md first)
+- **spinner, loading indicator, loading icon, busy indicator** → `LoadingSpinner.vue`
+- **nav button, link-styled button, navigation item, sidebar item** → `NavButton.vue` (read USAGE.md first)
+- **tag, chip, label, removable chip, category pill** → `Tag.vue` (read USAGE.md first)
+
+### Media & misc
+- **carousel, image slider, gallery, lightbox slider, image viewer** → `gallery/Carousel.vue` (read USAGE.md first)
+- **carousel preview, thumbnails strip, image picker strip, gallery thumbnails** → `gallery/CarouselPreview.vue` (read USAGE.md first)
+- **list row, list item, selectable row, list entry** → `ListItem.vue` (read USAGE.md first)
+- **locale switcher, language toggle, i18n switcher** → `LocaleSwitcher.vue` (read USAGE.md first)
+- **upload, file picker, drop-to-upload, file input, headless file upload** → `upload/` (read USAGE.md first)
+- **read-only date display, formatted date range, date range view** → `view/Dates.vue` (read USAGE.md first)
+- **keyboard bindings hint display, shortcut display, kbd renderer** → `view/KeyBinds.vue` (read USAGE.md first)
+- **separator, divider, horizontal rule, divider line** → `view/Separator.vue`
+- **read-only text display, formatted view, typography primitive, label** → `view/Text.vue` (read USAGE.md first)
+
+### Composables
+- **fetch, API client, HTTP request, JSON fetch** → `useApi`
+- **control size tokens, sizing tokens for form controls, control variant sizing** → `useControlSize` (read USAGE.md first)
+- **locale-aware number formatting, decimal parser, currency-safe parser** → `useDecimalFormatter` (read USAGE.md first)
+- **named filter group, v-bind bags for pickers, active chips, URL-synced filters, filter state** → `useFilter` (read USAGE.md first)
+- **fuzzy search, client-side filter, in-memory search, search-as-you-type** → `useFuzzySearch`
+- **inertia, momentum decay for gestures, fling-and-decelerate, momentum scroll** → `useInertia` (read USAGE.md first)
+- **arrow-key flat list navigation, listbox keyboard, dropdown keys** → `useListKeyboard` (read USAGE.md first)
+- **programmatic modal control, open modal from code, modal binding bag** → `useModal` (read USAGE.md first)
+- **pinch-to-zoom, two-finger touch zoom, pinch gesture** → `usePinchZoom` (read USAGE.md first)
+- **long-press detection, press-and-hold, auto-repeat, mousedown-hold ramp** → `usePressAndHold` (read USAGE.md first)
+- **roving-focus tabindex for 2D grids, grid keyboard navigation, calendar keyboard, table arrow nav** → `useRovingGrid` (read USAGE.md first)
+- **audio cue playback, sound effect, UI click sound, beep** → `useSound` (read USAGE.md first)
+- **theme tokens, light/dark, theme switcher, color theme** → `useTheme` (read USAGE.md first)
+- **sync state to URL query params, URL-backed state, persist state in URL, shareable URL state** → `useUrlSync` (read USAGE.md first)
+- **form validation, declarative form rules, field validation, error state** → `useValidation` (read USAGE.md first)
+<!-- routing:end -->
+
+---
+
+## Workflow
+
+1. **Match the request** against the routing table above. Pick exactly one
+   primary component. If two could fit, ask the caller which they meant before
+   reading anything else.
+2. **Read in this order, stopping when you have enough**:
+   - The matching `node_modules/orio-ui/dist/runtime/components/<name>.USAGE.md` (or `<folder>/USAGE.md`)
+     **first** — it contains non-obvious invariants and gotchas the source
+     alone will not reveal.
+   - Then the source file itself — props, slots, emits, defineModel.
+   - If the source imports a composable from `../composables/`, read
+     `node_modules/orio-ui/dist/runtime/composables/<name>.USAGE.md` before depending on it.
+   - Hand-written public API docs live at https://orio-ui.vercel.app/ —
+     consult only if the source + USAGE.md leave a gap.
+3. **Implement** the integration. Auto-import prefix is `Orio`, so `Modal.vue`
+   is used in templates as `<orio-modal>`. Nested folder components:
+   `Canvas/components/Stage.vue` → `<orio-canvas-stage>`.
+4. **Verify** before claiming done — run the relevant test suite if one exists
+   for the touched area, or describe what manual check would prove the
+   integration works.
+
+## Hard rules
+
+- **Never** restate component public API from memory. Read the file.
+- **Never** invent props, slots, or emits. If you cannot find one, it does not
+  exist.
+- **Never** skip a `(read USAGE.md first)` file — the marker exists because
+  there is a footgun.
+- **Never** modify files inside `node_modules/orio-ui/`. If the integration
+  needs a library change, hand it back to the caller as a flagged issue and
+  stop. The fix belongs upstream in the orio-ui repo, not patched locally.
+- Auto-imports: do **not** add manual `import` statements for `<orio-*>`
+  components inside Nuxt consumer code — they are auto-imported when the
+  `orio-ui` Nuxt module is registered in `nuxt.config`.
+- **i18n**: user-facing strings go through `vue-i18n` keys, not English
+  defaults inside props. If you write a label, write a key.
+- **Reuse**: prefer existing orio components in templates over raw HTML
+  (`<orio-view-text>` over `<p>`, `<orio-tag>` over a styled span, etc.).
+
+## Conventions to follow when generating consumer code
+
+- Vue 3 `<script setup lang="ts">`.
+- Props pattern: `interface Props { ... }` + `withDefaults(defineProps<Props>(), { ... })`.
+- v-model via `defineModel`.
+- Iteration: `forEach` / `map` / `find` / `Object.entries`. No C-style `for` loops.
+- Variable names spelled out — no single letters, no abbreviations.
+- Vue attr shorthand: `:tabindex` when name matches, not `:tabindex="tabindex"`.
+- Composables that own behavior end-to-end expose callbacks, not raw primitives.

package/dist/agents/snippet.md

@@ -0,0 +1,6 @@
+## orio-ui
+
+orio-ui ships agent-ready docs inside the package itself. Before answering
+anything about orio-ui components/composables, read
+`node_modules/orio-ui/dist/agents/ROUTING.md` — it routes to per-component
+USAGE.md files and optional subagents. Don't explore the package source blindly.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "1.27.0",
+  "version": "1.28.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"