uidex 0.2.4 → 0.4.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uidex",
-  "version": "0.2.4",
-  "description": "A framework-agnostic library for highlighting and annotating UI elements",
+  "version": "0.4.0",
+  "description": "Convention-driven UI element registry and devtools surface for React apps.",
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,17 +12,26 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
-    },
-    "./core/style.css": "./dist/core/style.css",
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
       "require": "./dist/react/index.cjs"
     },
+    "./cloud": {
+      "types": "./dist/cloud/index.d.ts",
+      "import": "./dist/cloud/index.js",
+      "require": "./dist/cloud/index.cjs"
+    },
+    "./headless": {
+      "types": "./dist/headless/index.d.ts",
+      "import": "./dist/headless/index.js",
+      "require": "./dist/headless/index.cjs"
+    },
+    "./scan": {
+      "types": "./dist/scan/index.d.ts",
+      "import": "./dist/scan/index.js",
+      "require": "./dist/scan/index.cjs"
+    },
     "./playwright": {
       "types": "./dist/playwright/index.d.ts",
       "import": "./dist/playwright/index.js",
@@ -32,40 +41,33 @@
       "types": "./dist/playwright/reporter.d.ts",
       "import": "./dist/playwright/reporter.js",
       "require": "./dist/playwright/reporter.cjs"
-    },
-    "./api": {
-      "types": "./dist/api/index.d.ts",
-      "import": "./dist/api/index.js",
-      "require": "./dist/api/index.cjs"
-    },
-    "./styles.css": "./dist/core/style.css"
+    }
   },
-  "sideEffects": [
-    "*.css"
-  ],
+  "sideEffects": false,
   "files": [
     "dist",
-    "claude",
-    "uidex.schema.json"
+    "templates"
   ],
   "bin": {
-    "uidex": "dist/scripts/cli.cjs"
+    "uidex": "dist/cli/cli.cjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "dev": "tsup --watch",
-    "build": "npm run build:tailwind && npm run generate:css && tsup && npm run build:css",
-    "build:tailwind": "tailwindcss --input src/ui/tailwind.css --output src/ui/tailwind.out.css",
-    "build:css": "cp src/core/style.css dist/core/style.css",
-    "generate:css": "tsx scripts/generate-css-text.ts",
-    "scan": "tsx scripts/cli.ts scan",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "build": "pnpm run build:css && tsup && pnpm run check:bundles",
+    "build:css": "tailwindcss --input src/styles/tailwind.css --output src/styles/tailwind.built.css",
+    "check:bundles": "node scripts/check-bundles.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "eslint src/",
-    "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx,css}\"",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm run test:run && npm run typecheck"
+    "views-map": "tsx scripts/extract-views-map.ts",
+    "views-map:check": "tsx scripts/extract-views-map.ts --check"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40",
@@ -77,56 +79,61 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@zag-js/combobox": "^1.40.0",
+    "@zag-js/core": "^1.40.0",
+    "@zag-js/dialog": "^1.40.0",
+    "@zag-js/menu": "^1.40.0",
+    "@zag-js/popover": "^1.40.0",
+    "@zag-js/react": "^1.40.0",
+    "@zag-js/scroll-area": "^1.40.0",
+    "@zag-js/tabs": "^1.40.0",
+    "@zag-js/tooltip": "^1.40.0",
+    "@zag-js/types": "^1.40.0",
+    "@zag-js/utils": "^1.40.0",
+    "clsx": "^2.1.1",
+    "lucide": "^1.8.0",
+    "lucide-react": "^1.7.0",
+    "modern-screenshot": "^4.7.0",
+    "tailwind-merge": "^3.5.0",
+    "xstate": "^5.30.0",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.2"
+  },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@phosphor-icons/react": "^2.1.10",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.2.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.10.5",
-    "@types/react": "^18.3.18",
-    "@types/react-dom": "^18.3.5",
-    "@typescript-eslint/eslint-plugin": "^8.21.0",
-    "@typescript-eslint/parser": "^8.21.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@uidex/eslint-config": "workspace:*",
+    "@uidex/tsconfig": "workspace:*",
     "@vitejs/plugin-react": "^4.3.4",
-    "@vitest/coverage-v8": "^2.1.8",
     "eslint": "^9.18.0",
-    "eslint-plugin-react": "^7.37.4",
-    "eslint-plugin-react-hooks": "^5.1.0",
     "jsdom": "^26.0.0",
-    "prettier": "^3.4.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "shadcn": "^4.1.2",
     "tailwindcss": "^4.2.2",
     "tsup": "^8.3.5",
     "tsx": "^4.7.0",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.54.0",
+    "typescript": "^5.9.3",
     "vitest": "^2.1.8"
   },
   "keywords": [
-    "annotation",
-    "highlight",
-    "overlay",
-    "component",
+    "uidex",
+    "devtools",
     "react",
-    "vanilla-js",
-    "framework-agnostic"
+    "playwright",
+    "feedback",
+    "scanner"
   ],
   "author": "soel",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/soel/uidex"
-  },
-  "dependencies": {
-    "@base-ui/react": "^1.3.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.7.0",
-    "tailwind-merge": "^3.5.0"
   }
 }

package/templates/claude/audit.md

@@ -0,0 +1,43 @@
+Run `npx uidex scan --audit` and fix all reported diagnostics.
+
+1. **`marker-md-ignored`** — legacy `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` files from v1. Migrate their content:
+   - Create a `uidex.page.ts` (in the route directory) or `uidex.feature.ts` (in the feature directory) and add an `export const uidex` block carrying the `page`/`feature` id, the description, and the acceptance list.
+   - Each `- [ ]` checkbox becomes one entry in the `acceptance` array.
+   - Delete the `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` file.
+
+2. **`acceptance-uncovered`** — a declared `@acceptance` criterion has no flow exercising it.
+   - For widgets: run `npx uidex scaffold widget <id>` to generate a Playwright stub in `e2e/` with one `test()` per criterion; fill in the stubs.
+   - For features/pages: write a Playwright spec under `e2e/**` tagged `{ tag: "@uidex:flow" }` that exercises the criterion by calling `uidex('<element-id>').*()` on the relevant elements.
+
+3. **`unknown-reference`** — a flow's `uidex('<id>')` call references an id that isn't in the registry.
+   - If the id is a typo, fix the string literal in the spec.
+   - If the component was removed, remove the call.
+   - If the component lost its `data-uidex`, restore it.
+   - Dynamic ids (variables, template literals) are invisible to the scanner. If a literal is flagged, it is actually a literal in the source.
+
+4. **`scope-leak`** — a primitive scoped to `feature:<name>` or `page:<name>` is being imported from outside that scope.
+   - Either move the primitive to `src/components/ui/**` so it becomes global, or route the consumer through an appropriate boundary.
+
+5. **`missing-element-annotation`** (INFO) — an interactive `<button>`, `<a>`, `<input>`, `<select>`, or `<textarea>` has no `data-uidex`.
+   - Add `data-uidex="<kebab-id>"`. Skip this diagnostic only when the element is purely decorative (e.g., a skip link that never needs automated reference).
+
+6. **`acceptance-orphan`** — an `@acceptance` tag appears on a JSDoc that doesn't declare `@uidex page|feature|widget`.
+   - Move the acceptance tags into the correct JSDoc block, or remove them.
+
+7. **`prefer-well-known-file`** (INFO) — a page or feature's `export const uidex` lives on an arbitrary file instead of the well-known file (`uidex.page.ts` for pages, `uidex.feature.ts` for features). Migrate:
+   - Create `uidex.page.ts` (in the route directory) or `uidex.feature.ts` (in the feature directory).
+   - Move the `export const uidex` block from the current file into the new well-known file.
+   - Remove the export (and any now-unused `Uidex` type import) from the original file.
+   - Run `npx uidex scan` to regenerate the gen file — `loc.file` updates but the entity itself is unchanged.
+
+After fixing, run `npx uidex scan` to regenerate the gen file before re-running the audit.
+
+## Decision rules for primitives
+
+Add `data-uidex-primitive="kebab-name"` ONLY when the component lives outside `src/components/ui/**` and meets all of:
+
+- Exports a reusable presentational component (not a page, layout, or feature orchestrator).
+- Wraps native elements or other primitives — no business logic or data fetching (`useQuery`, `useMutation`, etc.).
+- Imported by multiple consumers.
+
+If it's in `src/components/ui/**`, the scanner auto-promotes it — no attribute needed.

package/templates/claude/rules.md

@@ -0,0 +1,227 @@
+# uidex conventions
+
+This project uses [uidex](https://github.com/soel/uidex) for UI element tracking and feedback ingestion.
+
+## AI behavior
+
+Before editing any file inside a feature directory (`src/features/<name>/`) or a Next.js route directory, read the entity's well-known metadata file first:
+
+- Feature directories: `uidex.feature.ts` — the feature's `export const uidex` block lives here.
+- Route directories: `uidex.page.ts` — the page's `export const uidex` block lives here.
+
+These files declare `acceptance` criteria and a `description`. Treat them as **context steering**, not test assertions:
+
+- Acceptance criteria capture what matters about the page or feature so changes preserve the right behaviors. They are NOT the testing source of truth — Playwright flows under `e2e/**` are.
+- Before making a change, check whether it would violate a declared acceptance criterion. If it would, flag the conflict to the user before proceeding.
+- If a change adds or removes user-visible behavior, update the acceptance list in the well-known file alongside the code change.
+
+If a feature or page directory has no `uidex.feature.ts` / `uidex.page.ts`, the metadata may live on an arbitrary file in the directory (legacy convention) — `uidex scan --audit` will surface a `prefer-well-known-file` diagnostic with the current location.
+
+## Entity model
+
+Eight entity kinds make up the registry. Most are discovered by convention; annotations only override.
+
+| Kind        | Source                                                               | How discovered                                                                                                                                              |
+| ----------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `element`   | Interactive DOM element                                              | `data-uidex="id"` (always manual)                                                                                                                           |
+| `region`    | Structural area                                                      | `data-uidex-region="id"` OR HTML5 landmark (`<header>`/`<nav>`/`<main>`/`<aside>`/`<footer>`/`role="region"`)                                               |
+| `widget`    | Composite behavioural unit (video player, date picker, autocomplete) | `data-uidex-widget="id"` on the DOM root **AND** `export const uidex = { widget: "id", ... }` on the component module                                       |
+| `primitive` | Reusable presentational component definition                         | Any file under `src/components/ui/**` (auto-promoted); `data-uidex-primitive="name"` opts in a non-conventional location                                    |
+| `page`      | Route-rendered top-level                                             | Auto-derived from your framework's route detection (Next.js / Vite / TanStack Router); `export const uidex = { page: "id", ... }` overrides                 |
+| `feature`   | Cross-cutting capability                                             | Any directory under `src/features/*`; `export const uidex = { feature: "id", ... }` overrides                                                               |
+| `flow`      | End-to-end user journey                                              | Top-level `test.describe` in `e2e/**` (auto-promoted); `{ tag: "@uidex:flow" }` adds richer metadata; opt out with `export const uidex = { notFlow: true }` |
+| `route`     | URL → page mapping                                                   | Auto-derived from your framework's router                                                                                                                   |
+
+## DOM annotations
+
+Four attributes. All use kebab-case ids. DOM attributes are the sole surface for multi-per-file kinds (elements, regions, widget roots).
+
+### `data-uidex` — every interactive element
+
+```tsx
+<button data-uidex="save-btn">Save</button>
+<input data-uidex="email-field" />
+<a data-uidex="nav-home" href="/">Home</a>
+```
+
+`uidex scan --audit` flags unannotated `<button>`, `<a>`, `<input>`, `<select>`, `<textarea>` as INFO diagnostics. Rename carefully — ids are referenced by flow tests.
+
+### `data-uidex-region` — structural regions (only when HTML5 doesn't suffice)
+
+HTML5 landmarks (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `role="region"`) auto-register as regions. Only add `data-uidex-region` on non-semantic `<div>` wrappers you want in the registry:
+
+```tsx
+<div data-uidex-region="settings-form">
+  <button data-uidex="save-btn">Save</button>
+</div>
+```
+
+### `data-uidex-widget` — composite behavioural units
+
+Place on the root of a self-contained UI unit with internal state (video player, date picker, rich text editor). The DOM attribute is the runtime boundary; acceptance criteria live on the `export const uidex` at the component definition.
+
+```tsx
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  widget: "video-player",
+  acceptance: [
+    "Plays/pauses on Space",
+    "Scrubber updates as video plays",
+    "M toggles mute",
+  ],
+} as const satisfies Uidex.Widget
+
+export function VideoPlayer() {
+  return (
+    <div data-uidex-widget="video-player">
+      <button data-uidex="play">Play</button>
+      <input data-uidex="scrubber" type="range" />
+    </div>
+  )
+}
+```
+
+**Widget id duplication rule.** The id must appear in **both** places — on `data-uidex-widget="..."` at the DOM root (runtime boundary) **and** on `export const uidex = { widget: "..." }` (scan-time metadata). The scanner cross-validates: a mismatch or one-sided presence is an error.
+
+Child `data-uidex` elements are automatically composed onto the widget (via DOM nesting at scan time).
+
+### `data-uidex-primitive` — reusable component definitions
+
+Any `.tsx` under `src/components/ui/**` is auto-promoted to a primitive (name = kebab of filename). Add `data-uidex-primitive="name"` only to opt-in a reusable component that lives outside the convention directory.
+
+```tsx
+// src/components/ui/button.tsx — auto-promoted as 'button', no attribute needed
+export function Button({ children, ...props }) {
+  return <button {...props}>{children}</button>
+}
+```
+
+## `export const uidex` — module-scoped authoring surface
+
+One named export per module, on the file that **defines** the entity. The RHS must be a plain AST literal — object / array / string / number / boolean literals, optional `as const`, optional `satisfies Uidex.<Kind>`. Identifier references in value position, calls, spreads, conditionals, and template literals with expressions are rejected with an error diagnostic.
+
+```tsx
+// Page
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  page: "org-settings",
+  acceptance: [
+    "User can update the organization name",
+    "Error message is shown if the update fails",
+  ],
+  features: ["billing"],
+} as const satisfies Uidex.Page
+
+export default function SettingsPage() { ... }
+```
+
+Kinds (discriminator fields):
+
+| Kind        | Discriminator                     | Other fields                                                          |
+| ----------- | --------------------------------- | --------------------------------------------------------------------- |
+| `page`      | `page: PageId \| false`           | `acceptance?`, `features?`, `widgets?`, `description?`                |
+| `feature`   | `feature: FeatureId \| false`     | `acceptance?`, `description?`                                         |
+| `widget`    | `widget: WidgetId`                | `acceptance?`, `description?`                                         |
+| `primitive` | `primitive: PrimitiveId \| false` | `description?`                                                        |
+| `flow`      | `flow: FlowId`                    | `description?`                                                        |
+| opt-out     | `notFlow: true`                   | (no other fields — opts a Playwright spec out of flow auto-promotion) |
+
+Setting `page: false` / `feature: false` / `primitive: false` explicitly opts a module out of auto-promotion.
+
+### Typed cross-references
+
+`uidex.gen.ts` exports per-kind id unions (`PageId`, `FeatureId`, `WidgetId`, etc.) and a `Uidex` namespace of shape types. `satisfies Uidex.Page` makes `tsc` flag unknown ids at the literal — no `uidex scan --audit` round-trip required:
+
+```tsx
+export const uidex = {
+  page: "checkout",
+  features: ["billng"], // tsc error: "billng" is not assignable to FeatureId
+} as const satisfies Uidex.Page
+```
+
+### Precedence
+
+```
+configuration override  >  export const uidex  >  DOM attribute  >  convention
+```
+
+## Playwright flows
+
+End-to-end user journeys are Playwright tests in `e2e/**`. Any top-level `test.describe` auto-promotes to a flow; the `@uidex:flow` tag adds richer metadata. Opt out by adding `export const uidex = { notFlow: true } as const satisfies Uidex.NotFlow` at the top of the spec file.
+
+```ts
+import { expect, test } from "uidex/playwright"
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  flow: "add-and-complete-todo",
+  description: "User adds a todo and marks it complete.",
+} as const satisfies Uidex.Flow
+
+test.describe("Add and complete a todo", { tag: "@uidex:flow" }, () => {
+  test("adds a todo", async ({ uidex }) => {
+    await uidex("todo-field").fill("Buy milk")
+    await uidex("todo-add").click()
+  })
+})
+```
+
+Rules:
+
+- One tagged describe per `flow-*.spec.ts`.
+- Component ids inside `uidex(...)` MUST be string literals (static-analysable).
+- `page-*.spec.ts` and `feature-*.spec.ts` scoped tests remain untagged.
+
+## Scanner
+
+```bash
+npx uidex scan          # regenerate src/uidex.gen.ts
+npx uidex scan --check  # fail non-zero if the committed gen file is stale
+npx uidex scan --audit  # validate (--check + --lint; exits non-zero on errors)
+npx uidex scan --json   # emit diagnostics as JSON
+npx uidex scaffold widget <id>  # emit Playwright stub from declared acceptance
+```
+
+Run `uidex scan` after any `data-uidex*` attribute change, `export const uidex` edit, or new flow. The gen file (`src/uidex.gen.ts` by default) is auto-generated and **committed** — consumers import types from it directly.
+
+### Bundler plugins (optional)
+
+Install the matching bundler plugin so `uidex.gen.ts` regenerates on file save:
+
+- `@uidex/vite-plugin` — for Vite
+- `@uidex/webpack-plugin` — for raw Webpack
+- `@uidex/next-plugin` — `withUidex(config)` wrapper for Next.js (Webpack transport)
+
+## Configuration
+
+`.uidex.json` is flat. Example:
+
+```json
+{
+  "sources": [{ "rootDir": "src" }],
+  "output": "src/uidex.gen.ts",
+  "flows": ["e2e/**/*.spec.ts"],
+  "typeMode": "strict"
+}
+```
+
+`typeMode: "strict"` (default) emits literal id unions — `tsc` rejects unknown ids at the `satisfies Uidex.X` site. `typeMode: "loose"` emits `string` — a **temporary migration knob** for repos mid-migration from legacy JSDoc.
+
+Multi-source (monorepo) example:
+
+```json
+{
+  "sources": [
+    { "rootDir": "apps/web/src" },
+    { "rootDir": "packages/ui/src", "prefix": "@org/ui" }
+  ],
+  "output": "apps/web/src/uidex.gen.ts",
+  "flows": ["apps/web/e2e/**/*.spec.ts"]
+}
+```
+
+## Migration from legacy JSDoc
+
+JSDoc tags (`@uidex page|feature|widget`, `@acceptance`, `@uidex:not-flow`) are **no longer recognised** — the scanner registers nothing from them. `uidex scan --lint` ships a `legacy-jsdoc` rule that warns on every legacy tag and points at the replacement `export const uidex` form. Set `typeMode: "loose"` in `.uidex.json` during migration to keep `tsc` quiet; flip to `strict` once every JSDoc tag is gone.

package/claude/audit-command.md

@@ -1,46 +0,0 @@
-Run `npx uidex scan --audit` and fix all reported issues:
-
-1. **Uncovered components** (components missing doc coverage):
-   - Create a `UIDEX_PAGE.md` in the component's directory for page-specific components
-   - For cross-cutting components (auth, billing, search, etc.), create or update a `UIDEX_FEATURE.md` in `features/<name>/` and list the component ID in the `components:` frontmatter
-   - Include a `# Title`, `> description` blockquote, and `## Acceptance` with `- [ ]` checkboxes
-
-2. **Route directories missing UIDEX_PAGE.md** (route with `page.tsx` but no doc):
-   - Create a `UIDEX_PAGE.md` in the route directory
-   - Without its own doc, the route's components get absorbed by a parent page doc
-
-3. **Orphaned UIDEX_PAGE.md files** (docs with no components underneath):
-   - If the components were removed, delete the UIDEX_PAGE.md
-   - If components are missing annotations, add them
-
-4. **Orphaned UIDEX_FEATURE.md files** (features referencing no known components):
-   - Update the `components:` frontmatter to reference valid component IDs
-   - If the feature is no longer relevant, delete it
-
-5. **Missing descriptions** (pages/features without a `>` blockquote description):
-   - Add a `> description` blockquote immediately after the `# Title` heading
-
-6. **Missing block annotations** (structural regions):
-   - Add `data-uidex-block="kebab-id"` to page root wrappers and section containers
-   - Blocks do NOT need JSDoc comments
-
-7. **Missing interactive annotations**:
-   - Add `data-uidex="kebab-id"` to buttons, inputs, links, and other interactive elements
-   - Optionally add `/** @uidex id - description */` JSDoc above interactive elements
-
-8. **Primitive annotations** — use `data-uidex-primitive="kebab-name"` when a component is a **reusable presentational building block**, not a consumer/page component. Apply when ALL of these are true:
-   - The file **exports** a component (not a page or layout)
-   - The component **wraps native HTML elements or other primitives** (buttons, inputs, cards, badges) rather than composing app-level features
-   - The component is **imported by multiple consumers** or is designed to be reusable
-   - The component does **not fetch data or contain business logic** — it receives everything via props
-
-   Do NOT add `data-uidex-primitive` to:
-   - Page components, layouts, or route-level files
-   - Feature orchestrators (dialogs that compose multiple primitives with business logic)
-   - Components that call hooks for data fetching (`useQuery`, `useMutation`, etc.)
-   - One-off components only used in a single place (use `data-uidex` or `data-uidex-block` instead)
-
-   Files with `data-uidex-primitive` are exempt from missing-annotation lint checks.
-   The scanner detects primitives by the attribute alone — directory structure does not matter.
-
-After fixing all issues, run `npx uidex scan` to regenerate the component registry.