@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.21

package/evaluator/report.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/evaluator/report.schema.json",
+  "title": "Kerf UI browser evaluation report",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "tool",
+    "target",
+    "recordedAt",
+    "profileFiles",
+    "contexts",
+    "diagnostics",
+    "summary",
+    "artifacts",
+    "subjectiveReview"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": {
+      "type": "object",
+      "required": ["name", "reportVersion"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "const": "@kerfjs/ui/evaluator" },
+        "reportVersion": { "const": 1 }
+      }
+    },
+    "target": {
+      "type": "object",
+      "required": ["url"],
+      "additionalProperties": false,
+      "properties": { "url": { "type": "string", "minLength": 1 } }
+    },
+    "recordedAt": { "type": "string", "format": "date-time" },
+    "profileFiles": { "$ref": "#/$defs/stringList" },
+    "contexts": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/context" }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    },
+    "summary": { "$ref": "#/$defs/summary" },
+    "artifacts": {
+      "type": "object",
+      "required": ["retention", "files"],
+      "additionalProperties": false,
+      "properties": {
+        "retention": { "enum": ["always", "on-failure", "never"] },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "sha256"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+              }
+            }
+          }
+        }
+      }
+    },
+    "subjectiveReview": {
+      "type": "object",
+      "required": ["status", "rubric", "ratings", "note"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "const": "not-recorded" },
+        "rubric": {
+          "type": "array",
+          "minItems": 6,
+          "items": {
+            "type": "object",
+            "required": ["id", "prompt"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "prompt": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "ratings": { "type": "array", "maxItems": 0 },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "warnings", "passed"],
+      "additionalProperties": false,
+      "properties": {
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "boolean" }
+      }
+    },
+    "context": {
+      "type": "object",
+      "required": [
+        "id",
+        "browser",
+        "width",
+        "height",
+        "zoom",
+        "colorScheme",
+        "reducedMotion",
+        "evidence",
+        "summary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "browser": { "enum": ["chromium", "firefox", "webkit"] },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "zoom": { "type": "number", "minimum": 1 },
+        "colorScheme": { "enum": ["light", "dark"] },
+        "reducedMotion": { "enum": ["reduce", "no-preference"] },
+        "evidence": { "type": "object" },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["code", "severity", "context", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "string", "pattern": "^KUI-B[0-9]{3}$" },
+        "severity": { "enum": ["error", "warning"] },
+        "context": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "repair": { "type": "string", "minLength": 1 },
+        "selector": { "type": "string", "minLength": 1 },
+        "evidence": {}
+      }
+    }
+  }
+}

package/llms.txt

@@ -6,7 +6,7 @@
 > generate correct, good-looking kerf UI — it is not a catalog to browse.
 
 ```bash
-npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional peer
 ```
 
 Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
@@ -22,15 +22,51 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
    [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
    callback shapes, disposer return types).
 3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
-   relationships, side effects) load the
+   relationships, side effects, and geometry ownership) load the
    [Machine-readable component catalog](./ai/component-catalog.json) — the
-   canonical checked-in source; its schema is alongside it.
-4. **Apply the rules below and in** [skill.md](./ai/skill.md).
+   canonical checked-in source; its schema is alongside it. Also load the
+   consuming application's catalog extension when present; generate one from the
+   [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
+   when app-owned components must participate in selection or alignment.
+   Load the [Composition catalog v2](./ai/component-catalog-v2.json) to
+   mechanically evaluate parents, contexts, zones/cardinality, children, state,
+   wiring, responsive/layout/accessibility rules, and public boundaries. V1
+   remains compatible; v2 joins catalogs by `package:id`. Consumer v2 catalogs
+   use [the v2 extension schema](./ai/component-catalog-extension-v2.schema.json).
+   Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
+   `KUI-T###` ids, exact declaration symbols, and the boundary between rejected
+   source states and relationships that still require runtime/catalog checks.
+   Before generating application UI, discover `.kerf-ui-profile.json` with the
+   shipped [application profile API](./ai/application-ui-profile.mjs). Merge
+   package defaults, workspace policy, then parent-to-child directory policy;
+   honor its package-qualified preferences, approved theme/density, semantic
+   tokens, layout conventions, and narrow source-located exceptions. Validation
+   is catalog-aware per layer, including parent values later overridden by a
+   child; synchronous hosts use [application-ui-profile-sync.cjs](./ai/application-ui-profile-sync.cjs).
+   See the
+   [workspace profile example](./docs/examples/application-ui-profile.json).
+4. **When authoring a component gallery**, load
+   [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
+   authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
+5. **Apply the rules below and in** [skill.md](./ai/skill.md).
+6. **Before calling an integration complete**, run
+   [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
+   profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
+   repair source-located errors until exit 0. Use full mode for release gates.
+   [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
+   layout diagnostics are wanted; its review findings are a bounded human/AI
+   review queue rather than an objective aesthetic score.
+7. **Evaluate the running application** by explicitly enabling the doctor's
+   browser stage or directly invoking
+   [`kerf-ui-evaluate`](./docs/ui-evaluator.md). Preserve its `KUI-B###`
+   browser evidence and screenshots; record hierarchy/rhythm/density/aesthetic
+   ratings separately with a named reviewer rather than presenting them as
+   objective assertions.
 
 ## Core rules (do the right thing)
 
 - **Reach for the primitive, not for CSS.** The package is built to look right
-  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
+  _unstyled_. Before adding `padding`, `margin`, `width`, `height`, `border`,
   `background`, a wrapper card, or a decoration, check whether the component, the
   pane, or the content-item already owns it — it almost always does. Prefer a
   component prop or a `--kui-*` token; write CSS only for genuinely new structure,
@@ -69,7 +105,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
   `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
   `data-morph-skip-children`).
-- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
+- **`PanelHeader` is _the_ panel/dialog/page heading.** A plain toolbar with an
   optional bordered icon group, an extra-large `ToolbarText` title, the trailing
   controls you pass, and an optional subtitle below — do not hand-build a heading
   row or restyle a toolbar into one.
@@ -90,7 +126,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
   navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
   disclosure flags in the app — they are data or persisted layout, and the app reads
-  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
+  them to render. The `wire…` helpers own the _ephemeral_ parts: `wireNavStack` the
   push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
   `wireResizableRegions` the live drag preview; they report committed changes via
   callbacks. The one richer case is `wireTokenSearchFields`, which manages the
@@ -128,13 +164,19 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 `NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
-+ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
-`@kerfjs/ui/catalog` is another opt-in shell — a
-`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
-(collapsible category sidebar + preview stage + resources footer) from your own
-entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
-type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
-declared side effects.
+
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+  `@kerfjs/ui/catalog` is another opt-in shell — a
+  `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+  (collapsible category sidebar + preview stage + resources footer, with an opt-in
+  transparent-bound and margin geometry overlay plus focus-preserving active-row
+  reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. For any Catalog demo, follow
+  the [authoritative authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+  rather than inferring structure from the shell or private CSS.
+  `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
 ## Reference
 
@@ -146,5 +188,6 @@ declared side effects.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
-- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
+- [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
 - [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.17",
+  "version": "5.0.0-beta.21",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "kerf-ui-analyze": "./analyzer/cli.mjs",
+    "kerf-ui-doctor": "./doctor/cli.mjs",
+    "kerf-ui-evaluate": "./evaluator/cli.mjs"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": [
@@ -116,6 +121,26 @@
       "types": "./dist/catalog.d.ts",
       "import": "./dist/catalog.js"
     },
+    "./catalog-resources": {
+      "types": "./dist/catalog-resources.d.ts",
+      "import": "./dist/catalog-resources.js"
+    },
+    "./analyzer": {
+      "types": "./analyzer/index.d.mts",
+      "import": "./analyzer/index.mjs"
+    },
+    "./analyzer/report.schema.json": "./analyzer/report.schema.json",
+    "./doctor": {
+      "types": "./doctor/index.d.mts",
+      "import": "./doctor/index.mjs"
+    },
+    "./doctor/config.schema.json": "./doctor/config.schema.json",
+    "./doctor/report.schema.json": "./doctor/report.schema.json",
+    "./evaluator": {
+      "types": "./evaluator/index.d.mts",
+      "import": "./evaluator/index.mjs"
+    },
+    "./evaluator/report.schema.json": "./evaluator/report.schema.json",
     "./wire-catalog": {
       "types": "./dist/wire-catalog.d.ts",
       "import": "./dist/wire-catalog.js"
@@ -141,6 +166,11 @@
       "types": "./dist/split-view.d.ts",
       "import": "./dist/split-view.js"
     },
+    "./pane": {
+      "types": "./dist/pane.d.ts",
+      "browser": "./dist/browser/pane.js",
+      "import": "./dist/pane.js"
+    },
     "./workbench": {
       "types": "./dist/workbench.d.ts",
       "import": "./dist/workbench.js"
@@ -176,6 +206,11 @@
       "browser": "./dist/browser/skeleton.js",
       "import": "./dist/skeleton.js"
     },
+    "./sunken-panel": {
+      "types": "./dist/sunken-panel.d.ts",
+      "browser": "./dist/browser/sunken-panel.js",
+      "import": "./dist/sunken-panel.js"
+    },
     "./segmented-control": {
       "types": "./dist/segmented-control.d.ts",
       "browser": "./dist/browser/segmented-control.js",
@@ -243,12 +278,14 @@
     "./tab-bar.css": "./dist/styles/tab-bar.css",
     "./nav-stack.css": "./dist/styles/nav-stack.css",
     "./split-view.css": "./dist/styles/split-view.css",
+    "./pane.css": "./dist/styles/pane.css",
     "./workbench.css": "./dist/styles/workbench.css",
     "./collapsible-panel.css": "./dist/styles/collapsible-panel.css",
     "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
     "./loading-spinner.css": "./dist/styles/loading-spinner.css",
     "./select.css": "./dist/styles/select.css",
     "./skeleton.css": "./dist/styles/skeleton.css",
+    "./sunken-panel.css": "./dist/styles/sunken-panel.css",
     "./segmented-control.css": "./dist/styles/segmented-control.css",
     "./token-search-field.css": "./dist/styles/token-search-field.css",
     "./state-banner.css": "./dist/styles/state-banner.css",
@@ -261,6 +298,9 @@
   "files": [
     "dist",
     "ai",
+    "analyzer",
+    "doctor",
+    "evaluator",
     "docs",
     "ux-demo/recipes",
     "llms.txt",
@@ -272,27 +312,39 @@
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
+    "format": "prettier --write . --ignore-unknown",
     "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
-    "check:format": "prettier --check \"src/**/*.css\" \"ux-demo/**/*.css\"",
-    "catalog:sync": "node scripts/sync-component-catalog.mjs",
-    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/check-component-catalog.mjs",
+    "check:format": "prettier --check . --ignore-unknown",
+    "catalog:sync": "node scripts/sync-component-catalog.mjs && node scripts/sync-component-catalog-v2.mjs",
+    "catalog:v2:sync": "node scripts/sync-component-catalog-v2.mjs",
+    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/sync-component-catalog-v2.mjs --check && node scripts/check-component-catalog.mjs",
+    "check:profile": "node scripts/check-application-ui-profile.mjs",
+    "check:demo-conformance": "node scripts/check-catalog-demo-conformance.mjs",
     "check:recipes": "node scripts/check-recipes.mjs",
-    "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs",
+    "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs && node scripts/audit-ai-regression-results-v3.mjs",
     "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
     "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
     "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
     "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
     "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
+    "ai:regressions:record-v3": "node scripts/record-ai-regression-run-v3.mjs",
+    "ai:regressions:replay-v3": "node scripts/replay-ai-regression-run-v3.mjs",
     "ai:regressions:score": "node scripts/score-ai-regression.mjs",
     "check:guidance": "node scripts/check-decision-guidance.mjs",
-    "lint": "eslint src tests ux-demo docs/examples --max-warnings 0",
+    "lint:eslint": "eslint src tests ux-demo docs/examples --max-warnings 0",
+    "lint": "npm run lint:eslint && npm run check:format",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
-    "test": "npm run test:unit && npm run test:bundle",
+    "test": "npm run test:unit && npm run test:bundle && npm run test:analyzer && npm run test:doctor && npm run test:evaluator",
     "test:unit": "vitest run tests/unit --coverage",
     "test:bundle": "npm run build && vitest run tests/bundle",
-    "test:consumer-types": "npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json",
+    "test:analyzer": "vitest run tests/integration/ui-analyzer-downstream.test.ts",
+    "test:doctor": "vitest run tests/unit/ui-doctor.test.ts tests/integration/ui-doctor-downstream.test.ts",
+    "test:evaluator": "vitest run tests/unit/ui-evaluator.test.ts tests/integration/ui-evaluator-downstream.test.ts",
+    "test:contract-types:source": "node node_modules/typescript7/bin/tsc -p tests/consumer-types/contracts/tsconfig.source.json",
+    "test:contract-types:packed": "node scripts/check-packed-type-contracts.mjs",
+    "test:consumer-types": "npm run test:contract-types:source && npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json && npm run test:contract-types:packed",
     "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run check:format && npm run check:catalog && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
+    "check": "npm run check:catalog && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
     "prepublishOnly": "npm run check",
     "check:design-templates": "node scripts/check-design-templates.mjs",
     "check:design-templates:drift": "node scripts/check-design-templates-drift.mjs",
@@ -301,13 +353,21 @@
   "peerDependencies": {
     "@awesome.me/webawesome": "^3.12.0",
     "kerfjs": "^5.0.0-0",
-    "lucide": "^1.43.0"
+    "lucide": "^1.43.0",
+    "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {
     "@awesome.me/webawesome": {
       "optional": true
+    },
+    "playwright": {
+      "optional": true
     }
   },
+  "dependencies": {
+    "postcss": "^8.5.28",
+    "typescript": "^6.0.3"
+  },
   "devDependencies": {
     "@awesome.me/webawesome": "3.12.0",
     "@eslint/js": "^10.0.1",