uidex 0.2.4 → 0.4.0

package/README.md

@@ -1,465 +1,365 @@
 # uidex
 
-A framework-agnostic library for highlighting and annotating UI elements. Works with React, vanilla JS, or any framework. Includes a build-time scanner, annotation linting, inspect mode, Playwright integration, and Claude Code tooling.
+uidex surfaces structured context about a running UI — pages, features, widgets, regions, elements, primitives, flows — to humans (devtools overlay, command palette, detail panels), agents (typed `uidex.gen.ts` registry), and test runners (Playwright fixture + reporter).
 
-## Installation
+This is **uidex 0.1** — a greenfield rewrite. The published surface is a single npm package with framework-neutral core, an optional React adapter, and a built-in cloud client, each reachable through its own subpath export.
+
+## Install
 
 ```bash
-npm install uidex
+pnpm add uidex
 ```
 
-## Quick Start
+## Quick start (React)
 
 ```bash
-# 1. Initialize config
-npx uidex init
-
-# 2. Add data-uidex attributes to your elements
-#    <button data-uidex="submit-btn">Submit</button>
-
-# 3. Run the scanner
-npx uidex scan
+npx uidex init            # write .uidex.json and .gitignore entry
+npx uidex scan            # generate src/uidex.gen.ts
 ```
 
-### React
-
 ```tsx
-import './uidex.gen';
-import { UidexDevtools } from 'uidex';
+// any React root
+import { UidexProvider, UidexMount } from "uidex/react"
 
-function App() {
+export default function Root({ children }: { children: React.ReactNode }) {
   return (
-    <>
-      <button data-uidex="submit-btn">Submit</button>
-      <UidexDevtools />
-    </>
-  );
+    <UidexProvider projectKey="pk_your_project">
+      {children}
+      {process.env.NODE_ENV !== "production" && <UidexMount />}
+    </UidexProvider>
+  )
 }
 ```
 
-### Vanilla JS
-
-```js
-import './uidex.gen';
-import { createUidexUI } from 'uidex/core';
-
-const ui = createUidexUI();
-ui.mount();
-
-// Cleanup
-ui.destroy();
-```
-
-### Script Tag
-
-```html
-<script src="https://unpkg.com/uidex/dist/core/index.global.js"></script>
-<script>
-  const ui = UidexCore.createUidexUI({ components: { ... } });
-  ui.mount();
-</script>
-```
+That is the full integration. Shadow DOM mounts under the `<UidexMount>` node, the Inspector is always on while the surface is mounted (hover highlights any uidex-annotated element; plain click opens the element menu anchored to its bounds), and Cmd+K opens the palette. Passing `projectKey` auto-wires the built-in cloud client; pass `cloud={null}` to opt out, or `cloud={customAdapter}` to supply your own.
 
-## Configuration
+### Dev-only mount
 
-`npx uidex init` creates a `.uidex.json` file:
+Because the Inspector intercepts clicks on every uidex-annotated element while mounted, uidex is a **dev-only surface**. Consumers MUST gate the mount on an environment check — the SDK does not enforce this itself.
 
-```json
+```tsx
+// React — gate <UidexMount> on NODE_ENV
 {
-  "$schema": "./node_modules/uidex/uidex.schema.json",
-  "defaults": {
-    "color": "#3b82f6",
-    "borderStyle": "solid",
-    "borderWidth": 2,
-    "showLabel": true,
-    "labelPosition": "top-left"
-  },
-  "colors": {
-    "primary": "#3b82f6",
-    "success": "#10b981",
-    "warning": "#f59e0b",
-    "error": "#ef4444",
-    "info": "#6366f1"
-  },
-  "scanner": {
-    "rootDir": "src",
-    "include": ["**/*.tsx", "**/*.jsx"],
-    "exclude": ["**/*.test.*", "**/*.spec.*"],
-    "outputPath": "src/uidex.gen.ts"
-  }
+  process.env.NODE_ENV !== "production" && <UidexMount />
 }
 ```
 
-## Scanner
-
-The scanner finds `data-uidex` attributes in your source files and generates a typed registry.
-
-```bash
-npx uidex scan           # Generate registry
-npx uidex scan --audit   # Validate coverage and annotations
-```
-
-Add it to your build:
-
-```json
-{
-  "scripts": {
-    "prebuild": "npx uidex scan",
-    "build": "next build"
-  }
+```ts
+// Vanilla — gate createUidex().mount() on NODE_ENV
+if (process.env.NODE_ENV !== "production") {
+  createUidex({ cloud: cloud({ projectKey: "pk_..." }) }).mount()
 }
 ```
 
-### Annotating Components
+## Quick start (vanilla)
 
-```tsx
-<nav data-uidex="main-nav">
-  <a href="/">Home</a>
-</nav>
+```ts
+import { createUidex } from "uidex"
+import { cloud } from "uidex/cloud"
 
-{/* Optional: add a JSDoc description for richer documentation */}
-/** @uidex cta-button - Primary call-to-action button */
-<button data-uidex="cta-button">Click Me</button>
+const uidex = createUidex({
+  cloud: cloud({ projectKey: "pk_your_project" }),
+})
+uidex.mount() // defaults to document.body
 ```
 
-### Generated Output
+## Package layout
 
-The scanner generates `src/uidex.gen.ts` (gitignored) with:
+| Subpath                     | Purpose                                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `uidex`                     | Vanilla core. `createUidex`, session store (XState v5 surface + highlight + form machines), entity registry, injected surface, panel registry, Zag machines. No React, no network. |
+| `uidex/react`               | React boot wrapper. `UidexProvider`, `useUidex`, `UidexMount`, `createReactPanel`. No network.                                                                                     |
+| `uidex/cloud`               | Fetch client for the cloud ingest API. `cloud({ projectKey, endpoint })`, `FeedbackPayload`, etc. No React.                                                                        |
+| `uidex/headless`            | Narrower vanilla entry — Registry + Session + Shadow DOM + Overlay + Inspector + MenuBar. No panels.                                                                               |
+| `uidex/scan`                | Scanner pipeline (`discover → walk → extract → resolve → audit → emit`) and CLI.                                                                                                   |
+| `uidex/playwright`          | Test fixture (`uidex(id)`). Optional peer: `@playwright/test`.                                                                                                                     |
+| `uidex/playwright/reporter` | Coverage reporter.                                                                                                                                                                 |
 
-- `components` — map of id to file locations
-- `componentIds` — array of all ids
-- `ComponentId` — union type of all ids
-- `pages` — from `UIDEX_PAGE.md` files (directory-based component association)
-- `features` — from `UIDEX_FEATURE.md` files (explicit component association)
-- `uiComponents` — presentational primitives detected under `ui/` directories (see [UI Primitives](#ui-primitives))
-- Auto-registration calls
+The build enforces subpath isolation: `uidex` contains no React or network code, `uidex/react` contains no network code, `uidex/cloud` contains no React.
 
-### Monorepo Support
+## Entity model
 
-The scanner auto-discovers multiple `.uidex.json` files in monorepo setups. Use `sources` for multiple scan roots within a single config:
+Eight kinds, one registry, one ref shape:
 
-```json
-{
-  "scanner": {
-    "sources": [
-      { "rootDir": "src", "include": ["**/*.tsx"] },
-      { "rootDir": "../packages/ui/src", "include": ["**/*.tsx"], "prefix": "@myorg/ui" }
-    ],
-    "exclude": ["**/*.test.*"],
-    "outputPath": "src/uidex.gen.ts"
-  }
+```ts
+type EntityKind =
+  | "route"
+  | "page"
+  | "feature"
+  | "widget"
+  | "region"
+  | "element"
+  | "primitive"
+  | "flow"
+
+interface EntityRef {
+  kind: EntityKind
+  id: string
 }
 ```
 
-## UI Primitives
-
-The scanner treats any `.tsx` file whose path contains a literal `ui/` segment as a presentational primitive (e.g. `components/ui/button.tsx`, `features/auth/ui/Form.tsx`). Primitives don't need `data-uidex` annotations — the scanner detects them by convention and emits a separate `uiComponents` array in `uidex.gen.ts` alongside the usual component map.
+- **route** — a URL pattern. Auto-detected from the framework router.
+- **page** — the module that renders a route. `export const uidex = { page: "id", ... } as const satisfies Uidex.Page` overrides the derived id and declares acceptance.
+- **feature** — cross-cutting behaviour under `src/features/*`. `export const uidex = { feature: "id", ... }` overrides.
+- **widget** — composite interactive unit (video player, date picker). Declared with `data-uidex-widget="id"` on the DOM root AND `export const uidex = { widget: "id", acceptance: [...] }` on the component module. The scanner cross-validates the two.
+- **region** — HTML5 landmark or `role="region"`. `data-uidex-region` overrides id.
+- **element** — explicit interactive element. Always annotated via `data-uidex`.
+- **primitive** — reusable presentational component (button, input) under `src/ui/**`.
+- **flow** — top-level `test.describe` in `e2e/**`; `@uidex:flow` tag adds richer metadata. Opt out with `export const uidex = { notFlow: true }`.
 
-Each primitive gets a **scope** resolved by walking up from its file:
+## Runtime API
 
-| Marker found first | Scope |
-|---|---|
-| `UIDEX_FEATURE.md` | `feature:<dir-name>` |
-| `UIDEX_PAGE.md` | `page:<dir-name>` |
-| neither | `global` |
-
-`npx uidex scan --audit` flags imports of feature- or page-scoped primitives from outside their scope tree. Global primitives are exempt.
+```ts
+import { createUidex } from "uidex"
 
-### Shape
+const uidex = createUidex({
+  cloud: null, // or a CloudAdapter from uidex/cloud
+  theme: "auto", // "light" | "dark" | "auto"
+  defaultPanels: true, // register bundled detail + palette panels
+  panels: [myCustomPanel], // additional panels (last registered wins on conflict)
+})
 
-```ts
-import type { PrimitiveEntry } from 'uidex';
-
-// interface PrimitiveEntry {
-//   name: string;        // exported component name, e.g. "Button"
-//   filePath: string;    // source-root-relative path, e.g. "ui/button.tsx"
-//   scope: string;       // "global" | "feature:<name>" | "page:<name>"
-//   composes: string[];  // names of other primitives this one imports
-//   usedBy: string[];    // file paths of consumers (non-primitive sources)
-//   kind: 'ui';
-// }
+uidex.mount() // defaults to document.body
+uidex.unmount()
 ```
 
-`composes` and `usedBy` are filled in by a cross-source provenance pass, so you get the full dependency graph without maintaining it by hand. Barrel (`index.ts`) re-exports are **not** followed — import primitives directly from their source file for accurate tracking.
+`createUidex` returns:
 
-### Building a custom catalog from `uiComponents`
+| Field        | Shape                                                                                                                                                                            |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registry`   | `Registry` — `.add`, `.get(kind, id)`, `.list(kind)`, `.query(fn)`.                                                                                                              |
+| `session`    | Zustand store projecting the XState surface machine. `hover`, `selection`, `stack`, `inspectorActive`, `theme`, `ingestActive`. `session.send(event)` for direct machine events. |
+| `panels`     | `{ register, unregister, list }` — panel registrar.                                                                                                                              |
+| `cloud`      | The configured `CloudAdapter` or `null`.                                                                                                                                         |
+| `ingest`     | Console + network capture (auto-enabled when `cloud` is configured).                                                                                                             |
+| `shadowRoot` | The Shadow DOM root after `mount()`, else `null`.                                                                                                                                |
 
-`uiComponents` is the public contract for building your own design-system docs page or component explorer. Import it from the generated file and render however you like:
+### React wiring
 
 ```tsx
-// app/gallery/page.tsx
-import { uiComponents } from '@/uidex.gen';
-import { Button } from '@/components/ui/button';
+import { UidexProvider, UidexMount, useUidex } from "uidex/react"
+```
 
-// The only thing you maintain by hand: a map from primitive name to a live preview.
-const previews: Record<string, React.ReactNode> = {
-  Button: <Button>Click me</Button>,
-};
+- `<UidexProvider>` accepts `projectKey`, `cloud`, and `config` props. It creates the core instance on mount and disposes on unmount. If `projectKey` is provided and `cloud` is not explicitly set, it auto-wires `cloud({ projectKey })` from `uidex/cloud`.
+- `useUidex()` returns the core instance and throws `UidexContextError` outside a provider.
+- `<UidexMount>` renders the host DOM node the surface attaches to; the surface detaches on unmount.
 
-export default function Gallery() {
-  return (
-    <ul>
-      {uiComponents.map((entry) => (
-        <li key={entry.filePath + entry.name}>
-          <h3>{entry.name} <small>({entry.scope})</small></h3>
-          <div>{previews[entry.name] ?? <em>no preview</em>}</div>
-          <p>Used by {entry.usedBy.length} file(s)</p>
-        </li>
-      ))}
-    </ul>
-  );
-}
+### Headless
+
+```ts
+import { createHeadless } from "uidex/headless"
+
+const h = createHeadless({ theme: "auto" })
+h.mount()
+h.overlay.show(el, { label: "target" })
+h.inspector.start()
 ```
 
-That's the whole pattern: **uidex ships the data, you ship the renderer.** Group by `scope` for sectioned layouts, filter on `composes`/`usedBy` to surface dependency graphs, or skip live previews entirely and render it as a plain data table.
+No panels, no `ViewStack`. Same Shadow DOM, Overlay, MenuBar, CursorTooltip, CommandPalette (empty). Intended for agents, screencasts, and non-panel consumers.
 
-> **Note:** the `uiComponents` export is only present when the scanner finds at least one primitive. If your project has none yet, create a file under a `ui/` directory and re-run `npx uidex scan`.
+## Panel system
 
-See [`examples/next-app/app/gallery/page.tsx`](./examples/next-app/app/gallery/page.tsx) for a worked example that groups primitives by scope and renders each with a live preview + `composes`/`usedBy` metadata.
+Panels are the pluggable UI surface. Both detail views and palette commands are `Panel`s. Panels are framework-agnostic — `render` is imperative:
 
-## Components
+```ts
+interface Panel {
+  id: string
+  matches?: (ref: EntityRef) => boolean // detail panel
+  command?: { label: string; group?: string; shortcut?: string } // palette entry
+  render: (ctx: PanelContext, root: HTMLElement) => () => void
+}
+```
 
-### UidexDevtools (React)
+- `render` receives a mount root and returns a cleanup function.
+- Last registered wins on `matches()` overlap. `id` collision replaces the prior registration.
+- `ctx.navigate(ref)` pushes the matching panel for `ref` onto the view stack; the current view stays mounted underneath and is revealed on pop.
+- `ctx.push({ id, ref? })` and `ctx.pop()` drive the stack directly; `ctx.close()` clears every entry at once.
+- `ctx.cloud` is the configured `CloudAdapter` or `null`; cloud-backed affordances MUST degrade gracefully when it is null.
 
-Floating devtools panel with component list, pages, features, and inspect mode.
+Authoring a panel with React:
 
 ```tsx
-import { UidexDevtools } from 'uidex';
+import { createReactPanel } from "uidex/react"
 
-<UidexDevtools
-  buttonPosition="bottom-right"
-  theme="auto"
-  onSelect={(id) => console.log(id)}
-/>
+export const myPanel = createReactPanel({
+  id: "my-panel",
+  matches: (ref) => ref.kind === "widget",
+  component: ({ ctx }) => <div>Widget: {ctx.ref?.id}</div>,
+})
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `components` | `UidexMap` | registry | Components map |
-| `config` | `UidexConfig` | - | Styling configuration |
-| `buttonPosition` | `ButtonPosition` | `'bottom-right'` | Initial button position |
-| `theme` | `UidexTheme` | `'auto'` | Theme: `'dark'`, `'light'`, or `'auto'` |
-| `disabled` | `boolean` | `false` | Disable devtools |
-| `onSelect` | `(id: string) => void` | - | Selection callback |
-| `inspectShortcut` | `KeyboardShortcut \| false` | `Shift+Cmd+U` | Inspect mode shortcut |
-| `ingest` | `IngestConfig` | - | Server feedback submission config |
-| `onSubmit` | `(report, result) => void` | - | Callback after feedback submission |
+`createReactPanel` wraps `createRoot` / `unmount` and produces a conforming `Panel`.
 
-### UidexOverlay (React)
+### Element menu
 
-Standalone overlay for highlighting a single element.
+Clicking any uidex-annotated element opens a popover menu anchored to the element's bounds. The menu is chrome owned by the Surface (not a `Panel`), composed from the shared `menu` + `popover` Zag machines. All rows close the menu on activation; Escape and outside-click dismiss and return focus to the prior focus holder.
 
-```tsx
-import { UidexOverlay } from 'uidex';
+| Row                          | When shown                                         | Action                                                                                                                              |
+| ---------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Copy path**                | Always                                             | `navigator.clipboard.writeText("<kind>:<id>")`.                                                                                     |
+| **Open details**             | A registered panel matches the entity              | `session.actions.select(ref)` + `session.actions.openPanel(panel.id, ref)` where `panel = panels.findMatch(ref)`.                   |
+| **Submit feedback**          | A registered panel matches the entity              | Routes to the matched detail panel (feedback currently lives as a sub-view). Suppressed if there is no detail panel for the entity. |
+| **View acceptance criteria** | `ref.kind === "widget"` and a detail panel matches | Opens the widget detail panel.                                                                                                      |
+| **Find usages**              | `ref.kind === "primitive"`                         | Queries the registry for entities composing the primitive and opens the primitive detail panel.                                     |
 
-<UidexOverlay
-  target={element}
-  label="Button"
-  color="#3b82f6"
-/>
-```
+The ⌘K palette provides the keyboard-driven counterpart: its "On this page" section enumerates every uidex entity present in the current DOM, and selecting a row calls `ctx.navigate(ref)`.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `target` | `HTMLElement \| null` | required | Element to highlight |
-| `label` | `string` | - | Label text |
-| `color` | `string` | - | Border color (hex or named) |
-| `borderStyle` | `BorderStyle` | `'solid'` | `solid`, `dashed`, or `dotted` |
-| `borderWidth` | `number` | `2` | Border width in px |
-| `showLabel` | `boolean` | `true` | Show label |
-| `labelPosition` | `LabelPosition` | `'top-left'` | Label position |
-| `colors` | `Record<string, string>` | - | Named colors map |
-
-### createUidexUI (Vanilla JS)
-
-```js
-import { createUidexUI } from 'uidex/core';
-
-const ui = createUidexUI({
-  components: { ... },
-  pages: [ ... ],
-  features: [ ... ],
-  config: { defaults: { color: '#3b82f6' } },
-  buttonPosition: 'bottom-right',
-  theme: 'auto',
-  inspectShortcut: { key: 'u', shiftKey: true, metaKey: true },
-  onSelect: (id) => console.log(id),
-});
-
-ui.mount();
-ui.destroy();
-```
+### Bundled panels
 
-## Theming
+`createUidex({ defaultPanels: true })` (the default) registers:
 
-The devtools widget supports automatic theme detection. Set `theme="auto"` (the default) to match the host page's theme — it checks for `.dark` / `.light` classes on `<html>` and falls back to the OS `prefers-color-scheme` media query. Changes are tracked live via `MutationObserver` and `matchMedia` listeners.
+`commandPalettePanel`, `componentDetailPanel` (element), `pageDetailPanel`, `featureDetailPanel`, `widgetDetailPanel`, `flowDetailPanel`, `primitiveDetailPanel`, `regionDetailPanel`.
 
-```tsx
-// Auto-detect (default) — matches host page or OS preference
-<UidexDevtools theme="auto" />
+All eight are vanilla TypeScript built on Zag machines and Tailwind classes.
 
-// Force dark or light
-<UidexDevtools theme="dark" />
-<UidexDevtools theme="light" />
-```
+### Report uidex issue
 
-All UI renders inside a Shadow DOM with CSS custom properties. The default theme is dark. Override tokens for a light theme:
-
-```css
-:root {
-  --background: #ffffff;
-  --foreground: #262626;
-  --card: #ffffff;
-  --card-foreground: #262626;
-  --popover: #ffffff;
-  --popover-foreground: #262626;
-  --primary: #262626;
-  --primary-foreground: #fafafa;
-  --muted: rgba(0, 0, 0, 0.04);
-  --muted-foreground: #6b6b6b;
-  --border: rgba(0, 0, 0, 0.08);
-}
-```
+Every view's footer Actions popup (⌘K from depth 1, or the footer affordance) includes a **Report uidex issue** entry. It opens the SDK's built-in feedback form and submits to a uidex-maintained project — separate from your host `cloud` adapter, so SDK bugs surface to the uidex team without contaminating your own ticketing. The report is stamped with the SDK version and the originating view id (e.g. `uidex-sdk:command-palette`); when the SDK cannot reach its endpoint the form falls back to copying a Markdown report to the clipboard.
 
-## Inspect Mode
+## Scanner
 
-Press **Shift+Cmd+U** (Shift+Ctrl+U on Windows/Linux) to enter inspect mode. Hover over elements to highlight them, click to select. Press **Escape** to exit.
+One pipeline, six stages, each stage in its own file and independently callable:
 
-Disable or customize the shortcut:
+```
+discover(cwd)        // locate .uidex.json files across the monorepo
+  -> walk(sources)   // enumerate files per include/exclude
+  -> extract(files)  // data-uidex* attrs + export const uidex AST literals
+  -> resolve(ann)    // apply conventions, compute scopes, back-references
+  -> audit(registry) // diagnostics: missing, scope-leak, acceptance coverage
+  -> emit(registry)  // deterministic uidex.gen.ts
+```
 
-```tsx
-// Disable
-<UidexDevtools inspectShortcut={false} />
+CLI:
 
-// Custom shortcut
-<UidexDevtools inspectShortcut={{ key: 'i', ctrlKey: true }} />
+```bash
+npx uidex init                      # scaffold .uidex.json
+npx uidex scan                      # run full pipeline
+npx uidex scan --check              # fail on registry drift (CI gate)
+npx uidex scan --lint               # annotation lint diagnostics (includes legacy-jsdoc)
+npx uidex scan --audit              # --check + --lint + coverage
+npx uidex scan --json               # machine-readable output
+npx uidex scaffold widget <id>      # emit Playwright spec from declared acceptance
+npx uidex claude install            # Claude Code rules + skill + hooks
 ```
 
-## Playwright Integration
+See the [docs site](https://github.com/soel/uidex#docs) for the convention table, annotation surfaces, and the acceptance workflow.
 
-Test your annotated components with type-safe locators and coverage reporting.
+### Bundler plugins
 
-### Test Fixture
+Optional opt-in watch integrations regenerate `uidex.gen.ts` on file save:
 
-```ts
-import { test, expect } from 'uidex/playwright';
+- `@uidex/vite-plugin` — `plugins: [uidex()]` in `vite.config.ts`.
+- `@uidex/webpack-plugin` — `new UidexPlugin()` in `webpack.config.js`.
+- `@uidex/next-plugin` — `withUidex(config)` wrapper for `next.config.*`. Webpack transport today; Turbopack support tracked as a follow-up.
 
-test('submit button works', async ({ uidex }) => {
-  await uidex('submit-btn').click();
-  await uidex('success-message').waitFor();
-});
-```
+All three wrap `@uidex/plugin-core` so behaviour and diagnostic shapes are identical across bundlers.
 
-### Coverage Reporter
+## Config (`.uidex.json`)
 
-Track which `data-uidex` components are covered by tests:
+Flat schema. Legacy nested `scanner.*`, `defaults`, `colors` are rejected with descriptive errors.
 
-```ts
-// playwright.config.ts
-import UidexCoverageReporter from 'uidex/playwright/reporter';
-import { componentIds } from './src/uidex.gen.test';
-
-export default defineConfig({
-  reporter: [
-    ['html'],
-    [UidexCoverageReporter, { componentIds }],
+```json
+{
+  "$schema": "./node_modules/uidex/uidex.schema.json",
+  "sources": [
+    {
+      "rootDir": "src",
+      "include": ["**/*.{ts,tsx}"],
+      "exclude": ["**/*.test.*"]
+    }
   ],
-});
+  "output": "src/uidex.gen.ts",
+  "flows": ["e2e/**/*.spec.ts"],
+  "typeMode": "strict",
+  "audit": { "scopeLeak": true, "coverage": true, "acceptance": true },
+  "conventions": {
+    "primitives": ["src/ui/**", "src/components/ui/**"],
+    "features": "src/features/*",
+    "pages": "auto",
+    "flows": ["e2e/**/*.spec.ts"],
+    "regions": "landmarks"
+  }
+}
 ```
 
-Outputs `uidex-coverage.json` with covered/uncovered components and percentage.
+Set any `conventions.*` entry to `false` to disable that auto-discovery stage.
 
-### Scaffold Tests
+`typeMode` controls whether emitted id types are literal unions (`"strict"`, default) or `string` (`"loose"`, a temporary migration knob).
 
-Generate test stubs from your pages and features:
+## Acceptance workflow
 
-```bash
-npx uidex scaffold [dir]
+Declare criteria in the module-scoped `export const uidex`:
+
+```ts
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  widget: "video-player",
+  acceptance: [
+    "Plays on space",
+    "Mutes with m",
+    "Scrubs with arrow keys",
+  ],
+} as const satisfies Uidex.Widget
+
+export function VideoPlayer() {
+  return <div data-uidex-widget="video-player">...</div>
+}
 ```
 
-## Claude Code Integration
+1. Scanner extracts `acceptance` → `entity.meta.acceptance` (in source order).
+2. Flows touching the widget (directly or via descendants) are collected into `meta.flows`.
+3. `scan --audit` flags any criterion not covered by a flow; the hint suggests `uidex scaffold widget <id>`.
+4. `uidex scaffold widget video-player` emits a Playwright spec with one `test()` per criterion, tagged `@uidex:flow`. Re-running is idempotent unless `--force` is passed.
 
-Set up Claude Code with uidex-aware rules, a `/uidex:audit` skill, and a post-edit hook that validates coverage:
+## Cloud + ingest
 
-```bash
-npx uidex claude install    # Add rules + skill + hooks
-npx uidex claude uninstall  # Remove everything
-```
+Configure cloud by passing a `CloudAdapter` into `createUidex({ cloud })` or, from React, by passing `projectKey` / `cloud` to `<UidexProvider>`. The built-in client lives at `uidex/cloud`:
 
-Manage individually:
+```ts
+import { cloud } from "uidex/cloud"
 
-```bash
-npx uidex claude rules add|remove    # .claude/rules/uidex.md
-npx uidex claude skill add|remove    # .claude/commands/uidex/audit.md
-npx uidex claude hooks add|remove    # PostToolUse hook in .claude/settings.json
+const adapter = cloud({ projectKey: "pk_..." })
+await adapter.feedback.submit(payload)
+await adapter.integrations.getConfig()
 ```
 
-## Package Exports
+`cloud()` takes `{ projectKey, endpoint?, fetch? }`. `endpoint` defaults to the production cloud URL; `fetch` allows tests or self-hosted deployments to inject a custom transport. Errors surface as `CloudError` with `status`, `retryAfter`, and `details`.
 
-| Import | Description |
-|--------|-------------|
-| `uidex` | React components (re-exports `uidex/react`) |
-| `uidex/core` | Vanilla JS classes (`createUidexUI`, `Overlay`, `Inspector`) |
-| `uidex/react` | React wrappers (`UidexDevtools`, `UidexOverlay`) |
-| `uidex/playwright` | Test fixture and helpers |
-| `uidex/playwright/reporter` | Coverage reporter |
-| `uidex/api` | API client (Node.js) |
-| `uidex/styles.css` | Standalone CSS (optional, auto-injected via Shadow DOM) |
+When `cloud` is configured, `uidex/ingest` auto-enables:
 
-## CLI Reference
+- Console capture: `warn`/`error`, ring buffer ≤ 50. Originals always invoked.
+- Network capture: failed fetches only, ring buffer ≤ 20. Native `fetch` reference is captured at module load, so `cloud.feedback.submit` always uses an un-intercepted fetch.
 
-```
-npx uidex                    Show help / list commands
-npx uidex init               Create .uidex.json and update .gitignore
-npx uidex scan               Run component scanner
-npx uidex scan --audit       Validate coverage and annotations
-npx uidex scaffold [dir]     Generate Playwright test stubs
-npx uidex claude install     Set up Claude Code integration
-npx uidex claude uninstall   Remove Claude Code integration
-npx uidex login              Authenticate with uidex server
-npx uidex logout             Remove stored credentials
-npx uidex link               Link current directory to org/project
-npx uidex status             Show auth and link state
-npx uidex feedback           Manage feedback (list, show, update, delete)
-npx uidex triage             Manage triage (run, list, show, approve, dismiss, submit)
-npx uidex integrations       Manage integrations (list, add, remove, test, targets)
-```
+Override per-channel via `createUidex({ ingest: { console: {...}, network: null } })`, or pass `ingest: null` to disable entirely.
 
-## TypeScript
-
-Full type definitions included:
+## Playwright
 
 ```ts
-import type {
-  UidexConfig,
-  UidexDefaults,
-  UidexMap,
-  UidexLocation,
-  UidexPage,
-  UidexFeature,
-  UidexTheme,
-  UidexUIOptions,
-  PrimitiveEntry,
-  BorderStyle,
-  LabelPosition,
-  ButtonPosition,
-  KeyboardShortcut,
-  OverlayOptions,
-  IngestConfig,
-  FeedbackReport,
-  FeedbackResult,
-  FeedbackType,
-  FeedbackSeverity,
-} from 'uidex';
+import { test, expect } from "uidex/playwright"
+
+test.describe("Add and complete a todo", { tag: "@uidex:flow" }, () => {
+  test("adds a todo", async ({ uidex }) => {
+    await uidex("todo-text-field").fill("Buy milk")
+    await uidex("todo-add-button").click()
+    await expect(uidex("todo-item")).toHaveCount(1)
+  })
+})
 ```
 
-## Examples
-
-See `examples/` for working demos:
+Resolves any `data-uidex`, `data-uidex-region`, `data-uidex-widget`, or `data-uidex-primitive`. Register the coverage reporter to emit flow → entity coverage data — it is additive, compatible with any other reporter.
 
-- `examples/next-app/` — Next.js App Router
-- `examples/vite-app/` — Vite + React
+```ts
+// playwright.config.ts
+reporter: [["list"], ["uidex/playwright/reporter"]]
+```
 
-## License
+## Scripts
 
-MIT
+```bash
+pnpm build           # build:css + tsup + check:bundles
+pnpm test            # vitest (watch)
+pnpm test:run        # vitest (run)
+pnpm typecheck       # tsc --noEmit
+pnpm lint            # eslint src/
+```