uidex 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uidex",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Convention-driven UI element registry and devtools surface for React apps.",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,6 +57,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "dev": "tsup --watch",
+    "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/",
+    "typecheck": "tsc --noEmit",
+    "views-map": "tsx scripts/extract-views-map.ts",
+    "views-map:check": "tsx scripts/extract-views-map.ts --check"
+  },
   "peerDependencies": {
     "@playwright/test": ">=1.40",
     "react": ">=18",
@@ -83,6 +95,7 @@
     "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",
@@ -96,6 +109,8 @@
     "@types/node": "^22.10.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@uidex/eslint-config": "workspace:*",
+    "@uidex/tsconfig": "workspace:*",
     "@vitejs/plugin-react": "^4.3.4",
     "eslint": "^9.18.0",
     "jsdom": "^26.0.0",
@@ -105,9 +120,7 @@
     "tsup": "^8.3.5",
     "tsx": "^4.7.0",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.8",
-    "@uidex/eslint-config": "0.0.0",
-    "@uidex/tsconfig": "0.0.0"
+    "vitest": "^2.1.8"
   },
   "keywords": [
     "uidex",
@@ -122,17 +135,5 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/soel/uidex"
-  },
-  "scripts": {
-    "dev": "tsup --watch",
-    "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/",
-    "typecheck": "tsc --noEmit",
-    "views-map": "tsx scripts/extract-views-map.ts",
-    "views-map:check": "tsx scripts/extract-views-map.ts --check"
   }
-}
+}

package/templates/claude/audit.md

@@ -1,8 +1,8 @@
 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:
-   - Copy the description and acceptance list into a `@uidex page <id>` or `@uidex feature <id>` JSDoc block on the corresponding module (`page.tsx` for pages; the feature's main index/component for features).
-   - Each `- [ ]` checkbox becomes one `@acceptance <text>` tag.
+   - 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.
@@ -24,6 +24,12 @@ Run `npx uidex scan --audit` and fix all reported diagnostics.
 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

package/templates/claude/rules.md

@@ -2,6 +2,21 @@
 
 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.

package/dist/cloud/index.d.cts

@@ -1,108 +0,0 @@
-interface ConsoleLogEntry {
-    level: "log" | "warn" | "error" | "info";
-    message: string;
-    timestamp: string;
-}
-interface NetworkErrorEntry {
-    url: string;
-    method: string;
-    status: number | null;
-    statusText: string | null;
-    timestamp: string;
-}
-interface Viewport {
-    width: number;
-    height: number;
-}
-interface SourceRef {
-    filePath: string;
-    line: number;
-}
-interface FeedbackSuggestedTarget {
-    integrationId: string;
-    targetConfig: Record<string, unknown>;
-}
-interface FeedbackPayload {
-    type: "bug" | "feature" | "improvement" | "question";
-    severity: "low" | "medium" | "high" | "critical";
-    title?: string;
-    description: string;
-    componentId: string;
-    element?: string | null;
-    sources?: SourceRef[];
-    url: string;
-    path: string;
-    route?: string | null;
-    pageTitle?: string;
-    sessionId?: string;
-    reporterEmail?: string;
-    reporterName?: string;
-    timestamp: string;
-    viewport: Viewport;
-    screen: Viewport;
-    userAgent: string;
-    locale?: string;
-    environment?: string;
-    appVersion?: string;
-    consoleLogs?: ConsoleLogEntry[];
-    networkErrors?: NetworkErrorEntry[];
-    metadata?: Record<string, string>;
-    screenshot?: string;
-    suggestedTarget?: FeedbackSuggestedTarget;
-}
-interface FeedbackExternalLink {
-    ok: boolean;
-    url?: string;
-    key?: string;
-    error?: string;
-}
-interface FeedbackResult {
-    id: string;
-    sequenceNumber: number;
-    externalLink?: FeedbackExternalLink;
-}
-interface IngestConfigEpic {
-    key: string;
-    summary: string;
-    status: string;
-}
-interface IngestConfig {
-    hasJira: boolean;
-    integrationId?: string;
-    epics?: IngestConfigEpic[];
-}
-/**
- * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
- * payload/result/integration shapes. SDK-bundled `cloud()` returns the
- * defaulted form. `ViewContext.cloud` uses the fully-open variant; consumers
- * that need the SDK shape narrow with `as CloudAdapter`.
- */
-interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
-    getConfig(): Promise<IngestConfig>;
-}> {
-    readonly feedback: {
-        submit(payload: TPayload): Promise<TResult>;
-    };
-    readonly integrations: TIntegrations;
-}
-
-declare const DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
-interface CloudOptions {
-    projectKey: string;
-    endpoint?: string;
-    fetch?: typeof fetch;
-}
-declare class CloudError extends Error {
-    readonly status: number;
-    readonly retryAfter?: number;
-    readonly details?: unknown;
-    constructor(message: string, options: {
-        status: number;
-        retryAfter?: number;
-        details?: unknown;
-    });
-}
-
-declare function cloud(options: CloudOptions): CloudAdapter;
-
-export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type IngestConfig, type IngestConfigEpic, type SourceRef, cloud };

package/dist/cloud/index.d.ts

@@ -1,108 +0,0 @@
-interface ConsoleLogEntry {
-    level: "log" | "warn" | "error" | "info";
-    message: string;
-    timestamp: string;
-}
-interface NetworkErrorEntry {
-    url: string;
-    method: string;
-    status: number | null;
-    statusText: string | null;
-    timestamp: string;
-}
-interface Viewport {
-    width: number;
-    height: number;
-}
-interface SourceRef {
-    filePath: string;
-    line: number;
-}
-interface FeedbackSuggestedTarget {
-    integrationId: string;
-    targetConfig: Record<string, unknown>;
-}
-interface FeedbackPayload {
-    type: "bug" | "feature" | "improvement" | "question";
-    severity: "low" | "medium" | "high" | "critical";
-    title?: string;
-    description: string;
-    componentId: string;
-    element?: string | null;
-    sources?: SourceRef[];
-    url: string;
-    path: string;
-    route?: string | null;
-    pageTitle?: string;
-    sessionId?: string;
-    reporterEmail?: string;
-    reporterName?: string;
-    timestamp: string;
-    viewport: Viewport;
-    screen: Viewport;
-    userAgent: string;
-    locale?: string;
-    environment?: string;
-    appVersion?: string;
-    consoleLogs?: ConsoleLogEntry[];
-    networkErrors?: NetworkErrorEntry[];
-    metadata?: Record<string, string>;
-    screenshot?: string;
-    suggestedTarget?: FeedbackSuggestedTarget;
-}
-interface FeedbackExternalLink {
-    ok: boolean;
-    url?: string;
-    key?: string;
-    error?: string;
-}
-interface FeedbackResult {
-    id: string;
-    sequenceNumber: number;
-    externalLink?: FeedbackExternalLink;
-}
-interface IngestConfigEpic {
-    key: string;
-    summary: string;
-    status: string;
-}
-interface IngestConfig {
-    hasJira: boolean;
-    integrationId?: string;
-    epics?: IngestConfigEpic[];
-}
-/**
- * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
- * payload/result/integration shapes. SDK-bundled `cloud()` returns the
- * defaulted form. `ViewContext.cloud` uses the fully-open variant; consumers
- * that need the SDK shape narrow with `as CloudAdapter`.
- */
-interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
-    getConfig(): Promise<IngestConfig>;
-}> {
-    readonly feedback: {
-        submit(payload: TPayload): Promise<TResult>;
-    };
-    readonly integrations: TIntegrations;
-}
-
-declare const DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
-interface CloudOptions {
-    projectKey: string;
-    endpoint?: string;
-    fetch?: typeof fetch;
-}
-declare class CloudError extends Error {
-    readonly status: number;
-    readonly retryAfter?: number;
-    readonly details?: unknown;
-    constructor(message: string, options: {
-        status: number;
-        retryAfter?: number;
-        details?: unknown;
-    });
-}
-
-declare function cloud(options: CloudOptions): CloudAdapter;
-
-export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type IngestConfig, type IngestConfigEpic, type SourceRef, cloud };