uidex 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # uidex
 
-A React library for highlighting and annotating components. Perfect for building tutorials, onboarding experiences, or debugging tools.
+A framework-agnostic library for highlighting and annotating UI elements. Works with React, vanilla JS, or any framework. Includes a build-time scanner, inspect mode, Playwright integration, and Claude Code tooling.
 
 ## Installation
 
@@ -8,32 +8,61 @@ A React library for highlighting and annotating components. Perfect for building
 npm install uidex
 ```
 
-## Requirements
+## Quick Start
 
-- React 18 or higher
-- React DOM 18 or higher
+```bash
+# 1. Initialize config
+npx uidex init
 
-## Quick Start
+# 2. Add data-uidex attributes to your elements
+#    <button data-uidex="submit-btn">Submit</button>
+
+# 3. Run the scanner
+npx uidex scan
+```
+
+### React
 
 ```tsx
-// 1. Add data-uidex attributes to elements you want to track
-<button data-uidex="submit-btn">Submit</button>
+import './uidex.gen';
+import { UidexDevtools } from 'uidex';
+
+function App() {
+  return (
+    <>
+      <button data-uidex="submit-btn">Submit</button>
+      <UidexDevtools />
+    </>
+  );
+}
+```
 
-// 2. Run the scanner to generate the registry
-npx uidex-scan
+### Vanilla JS
 
-// 3. Import the generated file (auto-registers components)
+```js
 import './uidex.gen';
+import { createUidexUI } from 'uidex/core';
 
-// 4. Add UidexDevtools anywhere in your app
-import { UidexDevtools } from 'uidex';
+const ui = createUidexUI();
+ui.mount();
+
+// Cleanup
+ui.destroy();
+```
+
+### Script Tag
 
-<UidexDevtools />
+```html
+<script src="https://unpkg.com/uidex/dist/core/index.global.js"></script>
+<script>
+  const ui = UidexCore.createUidexUI({ components: { ... } });
+  ui.mount();
+</script>
 ```
 
 ## Configuration
 
-Create a `.uidex.json` file in your project root to customize default settings:
+`npx uidex init` creates a `.uidex.json` file:
 
 ```json
 {
@@ -61,221 +90,276 @@ Create a `.uidex.json` file in your project root to customize default settings:
 }
 ```
 
-## Components
+## Scanner
 
-### UidexDevtools
+The scanner finds `data-uidex` attributes in your source files and generates a typed registry.
 
-The main devtools component that displays a floating button with a list of all registered components:
+```bash
+npx uidex scan           # Generate registry
+npx uidex scan --check   # Validate UIDEX_PAGE.md coverage
+```
 
-```tsx
-import { UidexDevtools } from 'uidex';
+Add it to your build:
 
-function App() {
-  return (
-    <>
-      {/* Your app content */}
-      <UidexDevtools />
-    </>
-  );
+```json
+{
+  "scripts": {
+    "prebuild": "npx uidex scan",
+    "build": "next build"
+  }
 }
 ```
 
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `components` | `UidexMap` | - | Optional components map (uses registry if not provided) |
-| `config` | `UidexConfig` | - | Optional configuration for styling |
-| `buttonPosition` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Position of the floating button |
-| `trigger` | `ReactNode` | - | Custom trigger element |
-| `disabled` | `boolean` | `false` | Disable the devtools |
-| `onSelect` | `(id: string) => void` | - | Callback when a component is selected |
-
-### UidexOverlay
-
-For manual control over overlays:
+### Annotating Components
 
 ```tsx
-import { useState } from 'react';
-import { UidexOverlay } from 'uidex';
-
-function App() {
-  const [target, setTarget] = useState<HTMLElement | null>(null);
+<nav data-uidex="main-nav">
+  <a href="/">Home</a>
+</nav>
 
-  return (
-    <>
-      <button
-        ref={(el) => setTarget(el)}
-        onMouseEnter={(e) => setTarget(e.currentTarget)}
-        onMouseLeave={() => setTarget(null)}
-      >
-        Hover me
-      </button>
-      <UidexOverlay
-        target={target}
-        label="Button"
-        color="#3b82f6"
-      />
-    </>
-  );
-}
+/** @uidex cta-button - Primary call-to-action button */
+<button data-uidex="cta-button">Click Me</button>
 ```
 
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `target` | `HTMLElement \| null` | required | The element to highlight |
-| `label` | `string` | - | Label text shown on the overlay |
-| `color` | `string` | `#3b82f6` | Highlight color (hex or named color) |
-| `borderStyle` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | Border style |
-| `borderWidth` | `number` | `2` | Border width in pixels |
-| `showLabel` | `boolean` | `true` | Whether to show the label |
-| `labelPosition` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-left'` | Label position |
-| `colors` | `Record<string, string>` | - | Named colors map |
-
-## Build-Time Scanner
-
-The `uidex-scan` CLI tool scans your source files for `data-uidex` attributes and generates a TypeScript registry file.
-
-### Setup
+### Generated Output
 
-Add scanner configuration to your `.uidex.json`:
+The scanner generates `src/uidex.gen.ts` (gitignored) with:
 
-```json
-{
-  "$schema": "./node_modules/uidex/uidex.schema.json",
-  "scanner": {
-    "include": ["**/*.tsx"],
-    "exclude": ["**/*.test.*", "**/*.spec.*", "**/generated/**"],
-    "outputPath": "src/uidex.gen.ts",
-    "rootDir": "src"
-  }
-}
-```
+- `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)
+- Auto-registration calls
 
 ### Monorepo Support
 
-For monorepos with multiple packages, use the `sources` array:
+Use `sources` for multiple scan roots:
 
 ```json
 {
-  "$schema": "./node_modules/uidex/uidex.schema.json",
   "scanner": {
     "sources": [
-      {
-        "rootDir": "src",
-        "include": ["**/*.tsx"]
-      },
-      {
-        "rootDir": "../packages/ui/src",
-        "include": ["**/*.tsx"],
-        "prefix": "@myorg/ui"
-      }
+      { "rootDir": "src", "include": ["**/*.tsx"] },
+      { "rootDir": "../packages/ui/src", "include": ["**/*.tsx"], "prefix": "@myorg/ui" }
     ],
-    "exclude": ["**/*.test.*", "**/*.spec.*"],
+    "exclude": ["**/*.test.*"],
     "outputPath": "src/uidex.gen.ts"
   }
 }
 ```
 
-### Usage
+## Components
 
-Run the scanner as part of your build process:
+### UidexDevtools (React)
 
-```json
-{
-  "scripts": {
-    "prebuild": "npx uidex-scan",
-    "build": "next build"
-  }
-}
-```
+Floating devtools panel with component list, pages, features, and inspect mode.
 
-Or run it directly:
+```tsx
+import { UidexDevtools } from 'uidex';
 
-```bash
-npx uidex-scan
+<UidexDevtools
+  buttonPosition="bottom-right"
+  onSelect={(id) => console.log(id)}
+/>
 ```
 
-### Adding Components
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `components` | `UidexMap` | registry | Components map |
+| `config` | `UidexConfig` | - | Styling configuration |
+| `buttonPosition` | `ButtonPosition` | `'bottom-right'` | Initial button position |
+| `disabled` | `boolean` | `false` | Disable devtools |
+| `onSelect` | `(id: string) => void` | - | Selection callback |
+| `inspectShortcut` | `KeyboardShortcut \| false` | `Shift+Cmd+U` | Inspect mode shortcut |
 
-Add `data-uidex` attributes to your JSX elements:
+### UidexOverlay (React)
+
+Standalone overlay for highlighting a single element.
 
 ```tsx
-<nav data-uidex="main-nav">
-  <a href="/">Home</a>
-</nav>
+import { UidexOverlay } from 'uidex';
 
-<button data-uidex="cta-button">Click Me</button>
+<UidexOverlay
+  target={element}
+  label="Button"
+  color="#3b82f6"
+/>
+```
+
+| 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',
+  inspectShortcut: { key: 'u', shiftKey: true, metaKey: true },
+  onSelect: (id) => console.log(id),
+});
+
+ui.mount();
+ui.destroy();
 ```
 
-### JSDoc Documentation
+## Inspect Mode
+
+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.
 
-Add documentation to components using JSDoc comments:
+Disable or customize the shortcut:
 
 ```tsx
-/** @uidex cta-button - Primary call-to-action button */
-<button data-uidex="cta-button">Click Me</button>
+// Disable
+<UidexDevtools inspectShortcut={false} />
+
+// Custom shortcut
+<UidexDevtools inspectShortcut={{ key: 'i', ctrlKey: true }} />
 ```
 
-### Generated Output
+## Playwright Integration
+
+Test your annotated components with type-safe locators and coverage reporting.
 
-The scanner generates a TypeScript file with all discovered components:
+### Test Fixture
 
-```typescript
-// Auto-generated by uidex scanner
-// Do not edit this file manually
+```ts
+import { test, expect } from 'uidex/playwright';
 
-import { registerComponents } from 'uidex';
+test('submit button works', async ({ uidex }) => {
+  await uidex('submit-btn').click();
+  await uidex('success-message').waitFor();
+});
+```
 
-export const components = {
-  "cta-button": [{ filePath: "src/pages/Home.tsx", line: 12 }],
-  "main-nav": [{ filePath: "src/components/Header.tsx", line: 5 }]
-};
+### Coverage Reporter
 
-export const componentIds = ["cta-button", "main-nav"] as const;
+Track which `data-uidex` components are covered by tests:
 
-export type ComponentId = typeof componentIds[number];
+```ts
+// playwright.config.ts
+import UidexCoverageReporter from 'uidex/playwright/reporter';
+import { componentIds } from './src/uidex.gen.test';
 
-// Auto-register components
-registerComponents(components);
+export default defineConfig({
+  reporter: [
+    ['html'],
+    [UidexCoverageReporter, { componentIds }],
+  ],
+});
 ```
 
-### Using Generated Types
+Outputs `uidex-coverage.json` with covered/uncovered components and percentage.
 
-Import the generated types for type-safe component access:
+### Scaffold Tests
 
-```tsx
-import { components, ComponentId } from './uidex.gen';
+Generate test stubs from your pages and features:
+
+```bash
+npx uidex scaffold [dir]
+```
+
+## Claude Code Integration
+
+Set up Claude Code with uidex-aware rules, a `/uidex-audit` skill, and a post-edit hook that validates coverage:
+
+```bash
+npx uidex claude init       # Add rules + skill + hooks
+npx uidex claude teardown   # Remove everything
+```
 
-function highlightElement(id: ComponentId) {
-  const locations = components[id];
-  console.log(`Found at: ${locations[0].filePath}:${locations[0].line}`);
+Manage individually:
+
+```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
+```
+
+## Theming
+
+All UI renders inside a Shadow DOM with CSS custom properties. Override any token at `:root`:
+
+```css
+:root {
+  --uidex-color-primary: #2e2e2e;
+  --uidex-color-bg: #ffffff;
+  --uidex-color-bg-elevated: #f5f5f5;
+  --uidex-color-text: #1f2937;
+  --uidex-color-text-strong: #111827;
+  --uidex-color-text-muted: #6b7280;
+  --uidex-color-surface-hover: #f3f4f6;
+  --uidex-color-surface-active: #e5e7eb;
+  --uidex-color-border: #d1d5db;
+  --uidex-color-border-light: #e5e7eb;
 }
+```
+
+33 tokens available across colors, shadows, border-radius, z-index, typography, and transitions. The default theme is dark monochromatic with zero border-radius and monospace typography.
+
+## Package Exports
+
+| 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/styles.css` | Standalone CSS (optional, auto-injected via Shadow DOM) |
 
-// Type error: "invalid-id" is not a valid ComponentId
-highlightElement("invalid-id");
+## CLI Reference
+
+```
+npx uidex                    Initialize project (alias for init)
+npx uidex init               Create .uidex.json and update .gitignore
+npx uidex scan               Run component scanner
+npx uidex scan --check       Validate UIDEX_PAGE.md coverage
+npx uidex scaffold [dir]     Generate Playwright test stubs
+npx uidex claude init        Set up Claude Code integration
+npx uidex claude teardown    Remove Claude Code integration
 ```
 
 ## TypeScript
 
-This package is written in TypeScript and includes full type definitions:
+Full type definitions included:
 
-```tsx
+```ts
 import type {
   UidexConfig,
   UidexDefaults,
-  UidexDevtoolsProps,
-  UidexOverlayProps,
-  UidexLocation,
   UidexMap,
+  UidexLocation,
+  UidexPage,
+  UidexFeature,
   BorderStyle,
   LabelPosition,
   ButtonPosition,
+  KeyboardShortcut,
 } from 'uidex';
 ```
 
+## Examples
+
+See `examples/` for working demos:
+
+- `examples/next-app/` — Next.js App Router
+- `examples/vite-app/` — Vite + React
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uidex",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A framework-agnostic library for highlighting and annotating UI elements",
   "type": "module",
   "main": "./dist/index.cjs",