uidex 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uidex",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Convention-driven UI element registry and devtools surface for React apps.",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,27 +52,14 @@
     "uidex": "dist/cli/cli.cjs"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "tsup --watch",
-    "build": "pnpm run generate:api-routes && pnpm run build:css && tsup && pnpm run check:bundles",
-    "generate:api-routes": "tsx scripts/generate-api-routes.ts",
-    "build:css": "tailwindcss --input src/browser/styles/tailwind.css --output src/browser/styles/tailwind.built.css",
-    "check:bundles": "node scripts/check-bundles.mjs",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
-    "views-map": "tsx scripts/extract-views-map.ts",
-    "views-map:check": "tsx scripts/extract-views-map.ts --check"
-  },
   "dependencies": {
-    "@hey-api/client-fetch": "^0.10.0",
     "@clack/prompts": "^1.2.0",
+    "@hey-api/client-fetch": "^0.10.0",
     "@zag-js/core": "^1.40.0",
     "@zag-js/dialog": "^1.40.0",
     "@zag-js/menu": "^1.40.0",
@@ -88,6 +75,7 @@
     "lucide": "^1.8.0",
     "lucide-react": "^1.7.0",
     "modern-screenshot": "^4.7.0",
+    "oxc-parser": "^0.135.0",
     "tailwind-merge": "^3.5.0",
     "xstate": "^5.30.0",
     "zod": "^4.3.6",
@@ -102,9 +90,6 @@
     "@types/node": "^22.10.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@uidex/api-client": "workspace:*",
-    "@uidex/eslint-config": "workspace:*",
-    "@uidex/tsconfig": "workspace:*",
     "@vitejs/plugin-react": "^4.3.4",
     "eslint": "^9.18.0",
     "jsdom": "^26.0.0",
@@ -114,7 +99,10 @@
     "tsup": "^8.3.5",
     "tsx": "^4.7.0",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@uidex/api-client": "0.0.1",
+    "@uidex/eslint-config": "0.0.0",
+    "@uidex/tsconfig": "0.0.0"
   },
   "keywords": [
     "uidex",
@@ -129,5 +117,18 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/soel/uidex"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "pnpm run generate:api-routes && pnpm run build:css && pnpm run typecheck && tsup && pnpm run check:bundles",
+    "generate:api-routes": "tsx scripts/generate-api-routes.ts",
+    "build:css": "tailwindcss --input src/browser/styles/tailwind.css --output src/browser/styles/tailwind.built.css",
+    "check:bundles": "node scripts/check-bundles.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "views-map": "tsx scripts/extract-views-map.ts",
+    "views-map:check": "tsx scripts/extract-views-map.ts --check"
   }
-}
+}

package/templates/claude/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: uidex
+description: "uidex UI tracking conventions, audit diagnostics, and API client. Use when: adding/editing data-uidex* attributes, export const uidex blocks, uidex.page.ts / uidex.feature.ts files, Playwright @uidex:flow tests, .uidex.json config, running uidex scan / uidex scaffold, calling the uidex API, or fixing uidex scan --audit diagnostics."
+---
+
+# uidex
+
+uidex is a UI element tracking and feedback ingestion platform. This skill covers conventions for annotating UI entities, running the scanner, fixing audit diagnostics, and using the API client.
+
+## 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.
+
+## Reference guides
+
+Read on demand when the task touches these areas:
+
+- `./references/conventions.md` — Entity model, DOM annotations, `export const uidex` authoring, Playwright flows, scanner usage, configuration
+- `./references/audit.md` — All `uidex scan --audit` diagnostic codes with fix instructions
+- `./references/api.md` — uidex API client: authentication, making requests, common workflows, route tags
+
+## Quick reference
+
+### Scanner commands
+
+```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 --fix    # apply mechanical fixes (annotate unannotated elements), then rescan
+npx uidex scan --json   # emit diagnostics as JSON (fixable ones carry fixable: true)
+npx uidex scaffold <widget|page|feature> <id>  # emit Playwright stub from declared acceptance
+npx uidex rename <element|widget|region> <old-id> <new-id>  # rename an id everywhere
+```
+
+Run `uidex scan` after any `data-uidex*` attribute change, `export const uidex` edit, or new flow.
+
+### DOM annotations
+
+- `data-uidex="id"` — every interactive element (button, input, link, select, textarea)
+- `data-uidex-region="id"` — structural regions (only when HTML5 landmarks don't suffice)
+- `data-uidex-widget="id"` — composite behavioural units (video player, date picker, etc.)
+- `data-uidex-primitive="name"` — reusable components outside `src/components/ui/**`
+
+### Module-scoped metadata
+
+```tsx
+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
+```
+
+Kinds: `page`, `feature`, `widget`, `region`, `primitive`, `flow`, `notFlow` (opt-out).

package/templates/claude/references/audit.md

@@ -0,0 +1,43 @@
+# uidex audit diagnostics
+
+Run `npx uidex scan --fix` first. This applies every machine-generated fix — `missing-element-annotation` (inserts a deterministic `data-uidex` id derived from the element's accessible name / visible text / tag, deduped with a numeric suffix) and `uidex-export-empty-name` (drops empty `name` fields) — then rescans and rewrites the gen file. In `--json` output, fixable diagnostics carry `fixable: true`. Review the generated ids and rename any that read poorly (`npx uidex rename`).
+
+Then fix the remaining diagnostics, which need judgment:
+
+1. **`acceptance-uncovered`** — a declared acceptance criterion has no flow exercising it.
+   - Run `npx uidex scaffold <widget|page|feature> <id>` to generate a Playwright stub in `e2e/` with one `test()` per criterion; fill in the stubs.
+
+2. **`unknown-reference`** — a flow's `uidex('<id>')` call, or a `features:` / `widgets:` array in an `export const uidex`, references an id that isn't in the registry.
+   - If the id is a typo, fix the string literal.
+   - If the component was removed, remove the reference.
+   - If the component lost its `data-uidex`, restore it.
+
+3. **`duplicate-id`** — the same kind+id is annotated in more than one file. The registry keeps only one entry, so flows and the runtime overlay have an ambiguous target.
+   - Element/region duplicates (INFO) are fine when they are variants of the same logical element (desktop/mobile nav); otherwise rename one with `npx uidex rename <kind> <old-id> <new-id>` — it updates flow references too.
+   - Widget/primitive duplicates (WARNING) are definition collisions; rename one.
+
+4. **`dynamic-flow-reference`** — a `uidex(…)` call in a tagged flow uses a dynamic expression. The id is invisible to coverage and registry validation; use a string literal.
+
+5. **`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. Type-only imports are exempt.
+
+6. **`missing-element-annotation`** (INFO, machine-fixable) — an interactive `<button>`, `<a>`, `<input>`, `<select>`, or `<textarea>` has no `data-uidex`.
+   - `npx uidex scan --fix` inserts a generated id; review it and rename if it reads poorly. Skip (leave unannotated) only when the element is purely decorative (e.g., a skip link that never needs automated reference).
+
+7. **`uidex-export-satisfies-mismatch`** — the `satisfies Uidex.<Kind>` annotation contradicts the declared discriminator (e.g. `{ page: ... } satisfies Uidex.Widget`). Fix whichever side is wrong.
+
+8. **`widget-missing-dom` / `widget-id-mismatch`** — the widget id must appear identically on `data-uidex-widget="…"` at the DOM root and on `export const uidex = { widget: "…" }`. Align the two (prefer `npx uidex rename widget …` if the id itself is changing).
+
+Renaming an id by hand is error-prone (flow specs reference it); prefer `npx uidex rename <element|widget|region> <old-id> <new-id>`, which rewrites the DOM attribute, `uidex()` calls, widget exports, and `widgets:` arrays, then regenerates the gen file. Occurrences it cannot edit (const indirection, ternaries, patterns) are listed as `MANUAL` lines.
+
+After manual fixes, 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 → references/conventions.md}

@@ -1,22 +1,5 @@
 # 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.
@@ -44,7 +27,9 @@ Four attributes. All use kebab-case ids. DOM attributes are the sole surface for
 <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.
+`uidex scan --audit` flags unannotated `<button>`, `<a>`, `<input>`, `<select>`, `<textarea>` as INFO diagnostics (`missing-element-annotation`, or `spread-attr` when the element's only attribute is a `{...props}` spread). `missing-element-annotation` is machine-fixable: `npx uidex scan --fix` inserts a deterministic `data-uidex` id derived from the element's accessible name (aria-label), visible text, or tag, deduping collisions with a numeric suffix. Review the generated ids and rename any that read poorly via `npx uidex rename` — ids are referenced by flow tests, and the command rewrites those references too. (`spread-attr` is left alone: the annotation may be forwarded through props.)
+
+Dynamic attribute values resolve statically when possible: string literals in containers, unambiguous same-file `const` references, ternaries with literal branches (both ids register), and template literals with static text in any position (`` `tag-${x}-remove` `` registers the pattern `tag-*-remove`; `*` matches any run of characters at runtime, most-static-text pattern wins). Anything else is a `dynamic-attr` warning.
 
 ### `data-uidex-region` — structural regions (only when HTML5 doesn't suffice)
 
@@ -56,6 +41,20 @@ HTML5 landmarks (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `role="re
 </div>
 ```
 
+**Important:** The attribute value must be a string literal. `data-uidex-region={variable}` cannot be resolved statically and triggers a `region-dynamic-attr` warning. When a wrapper component forwards the region via a prop, declare it with `export const uidex` on the consuming file instead:
+
+```tsx
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  region: "members-page",
+} as const satisfies Uidex.Region
+
+export function MembersPage() {
+  return <EntityPageShell region="members-page" />
+}
+```
+
 ### `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.
@@ -124,11 +123,12 @@ Kinds (discriminator fields):
 | `page`      | `page: PageId \| false`           | `acceptance?`, `features?`, `widgets?`, `description?`                |
 | `feature`   | `feature: FeatureId \| false`     | `acceptance?`, `description?`                                         |
 | `widget`    | `widget: WidgetId`                | `acceptance?`, `description?`                                         |
+| `region`    | `region: RegionId \| false`       | `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.
+Setting `page: false` / `feature: false` / `primitive: false` / `region: false` explicitly opts a module out of auto-promotion.
 
 ### Typed cross-references
 
@@ -180,8 +180,10 @@ Rules:
 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
+npx uidex scan --fix    # apply mechanical fixes (annotate unannotated elements), then rescan and write
+npx uidex scan --json   # emit diagnostics as JSON (fixable ones carry fixable: true)
+npx uidex scaffold <widget|page|feature> <id>  # emit Playwright stub from declared acceptance
+npx uidex rename <element|widget|region> <old-id> <new-id>  # rename an id everywhere
 ```
 
 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.
@@ -202,12 +204,11 @@ Install the matching bundler plugin so `uidex.gen.ts` regenerates on file save:
 {
   "sources": [{ "rootDir": "src" }],
   "output": "src/uidex.gen.ts",
-  "flows": ["e2e/**/*.spec.ts"],
-  "typeMode": "strict"
+  "flows": ["e2e/**/*.spec.ts"]
 }
 ```
 
-`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.
+`uidex.gen.ts` always emits literal id unions, so `tsc` rejects unknown ids at the `satisfies Uidex.X` site.
 
 Multi-source (monorepo) example:
 
@@ -221,7 +222,3 @@ Multi-source (monorepo) example:
   "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/templates/claude/audit.md

@@ -1,43 +0,0 @@
-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.