@adia-ai/a2ui 0.8.38 → 0.8.39

package/catalog/tiers/README.md

@@ -15,6 +15,18 @@ the ladder's one law: **every tier-N entry is a declared composition of
 tier-(N−1) entries.** An entry that composes nothing, or that names something
 absent from the rung below, fails the build.
 
+Where an entry carries a `template`, the law is enforced one level deeper:
+`composes` must be **exactly** the set of rung-below entries the template
+actually uses — no undeclared uses, no unused declarations. Templates spell
+components with A2UI standard TYPE names (`Column`, `CheckBox`,
+`ChoicePicker`) while L0 is keyed by catalog COMPONENT names (`Col`, `Check`,
+`Select`); the derivation joins them through `registry.js` (type → tag) and
+the catalog's `x-adiaui.tag` (tag → name), so authors write whichever
+vocabulary the template uses and declare `composes` in catalog names. A type
+that resolves to neither — a native element (`FormContainer`,
+`DescriptionTerm`), a sub-descriptor (`ColDef`), or an upper-rung unit
+(`AdminShell`) — has no L0 entry and fails the build.
+
 ## File shape
 
 ```jsonc
@@ -27,7 +39,7 @@ absent from the rung below, fails the build.
       "template": [ /* A2UI nodes referencing L0 types only */ ],
       "wiring": { /* controller/handler contract, wiring-registry vocabulary */ },
       "keywords": ["stats", "kpi", "dashboard"],
-      "preview": "previews/stat-summary-row.html"   // derived artifact, never hand-written
+      // "preview": "previews/stat-summary-row.html"  // RESERVED, unbuilt — see below
     }
   }
 }
@@ -37,9 +49,46 @@ Only `composes` is interpreted by the derivation; every other key is carried
 into the index untouched, so this directory stays the single authoring
 surface and the index stays a pure aggregation.
 
+`preview` is **reserved and unbuilt** — no entry carries one, and no generator
+exists. Rendering an AdiaUI widget needs a browser (built bundles, icon
+registry, custom-element upgrade), and every rendering path in this repo is
+ephemeral review tooling against a running dev server. The scope-out rationale
+and the re-entry checklist are in `.claude/docs/specs/tiered-catalogs.md`
+## Previews (gh#1291 phase 2). Until then, `source.page` is the pointer at a
+live demo page where the widget renders in situ.
+
 ## Status
 
-Empty by design as of phase 1 (the L0 home-move). L1 curation — promoting the
-best of the zettel compositions and patterns into named, versioned widget
-entries — is its own sized phase; see `.claude/docs/specs/tiered-catalogs.md`
-## Follow-up phases.
+| Rung | State |
+|---|---|
+| `l1-widgets.json` | **populated** — 44 curated widgets across 17 domains (gh#1291 phase 1) |
+| `l2-*.json` | reserved — unblocked now that L1 exists |
+| `l3-*.json` · `l4-*.json` | reserved |
+
+## The L1 curation record
+
+`curation/l1-widgets.curation.json` is the **authored judgment**: the criteria
+(five mechanical gates + three selection rules) and the allow-list of admitted
+chunk names, with the rationale for each. `l1-widgets.json` is its
+transcription, materialized by
+
+    node scripts/build/curate-l1-widgets.mjs --apply     # write
+    node scripts/build/curate-l1-widgets.mjs --verify    # report divergence
+
+That script is a **one-shot curation tool, not a build step** — deliberately
+absent from `npm run check` and from every freshness gate. ADR-0050 Decision
+§1 rules that the corpus derives from catalogs and never the reverse; wiring
+the transcription into the build would make the chunk corpus a standing input
+to the catalog and close a derivation cycle. `curation/` is not matched by the
+`l1-*.json` glob, so the tier derivation never reads it.
+
+An entry's `template` is a **snapshot frozen at curation time**, not a live
+view of its source chunk — a widget entry is a versioned contract that holds
+still while demo HTML evolves. `--verify` reporting divergence is information,
+not breakage; re-syncing means bumping the affected entries' `version` and
+re-running `--apply`.
+
+Entry names are their source chunk's name unchanged, which keeps the
+provenance join an identity and keeps naming out of the judgment budget.
+Each entry carries `source: { chunk, page }`; the reverse linkage (a chunk
+naming its catalog entry) is gh#1291 phase 5.

package/catalog/tiers/curation/l1-widgets.curation.json

@@ -0,0 +1,153 @@
+{
+  "$comment": "AUTHORED curation record for the L1 widget rung (ADR-0050, gh#1291 phase 1). This file is the CURATION — the judgment act. `../l1-widgets.json` is its transcription, materialized by `node scripts/build/curate-l1-widgets.mjs --apply` (a one-shot curation tool, deliberately NOT a gate and NOT in `npm run check`: the corpus must never become a standing input to the catalog build — ADR-0050 Decision §1, 'the corpus derives from catalogs, never the reverse'). Not matched by the tier glob (`l1-*.json` in the parent dir), so the derivation never reads it.",
+  "curationId": "l1-widgets@1",
+  "date": "2026-08-15",
+  "issue": "https://github.com/adiahealth/gen-ui-kit/issues/1291",
+  "rationale": {
+    "proposalAsWritten": "The design note's open question 1 proposed ranking by zettel-engine usage frequency from eval traces. That signal is not available to this curation: eval runs land in `evals/mcp/runs/` which is not committed, and the corpus chunk index reports `instances: 1` for every one of the 431 ladder-clean block chunks, so there is no in-repo frequency to rank by. The criteria below substitute repo-resident, deterministic signals for the same intent — 'what recurs on shipped surfaces', not 'what exists'.",
+    "intent": "L1 is the CURATED-COMMON tier: the chat-scale functional units an agent enumerates and asks for by name. Breadth over depth — one canonical entry per composition shape, capped per domain — so the first slice is a usable vocabulary rather than a census of the 516 templates.",
+    "namingRule": "An entry's name is its source chunk's name, unchanged. Renaming would buy prettier names at the cost of traceability and would make every name an arbitrary judgment call; chunk names are already kebab-case, unique, and descriptive. This also makes the phase-5 chunk<->entry linkage an identity join.",
+    "frozenSnapshot": "An entry's `template` is a snapshot taken at curation time, not a live view of the chunk. That is the point of curation: a widget entry is a versioned contract that holds still while demo HTML evolves. Re-syncing is an authored act (bump `version`, re-run the tool), never an automatic build step."
+  },
+  "criteria": {
+    "gates": [
+      {
+        "id": "G1",
+        "name": "tier fit",
+        "rule": "chunk.kind === 'block'",
+        "why": "L1's entry unit is a chat-scale functional unit. `page` chunks are whole routes and `panel` chunks are shell regions — both are L2/L3 material, and admitting them would let L1 absorb the rungs above it."
+      },
+      {
+        "id": "G2",
+        "name": "ladder-clean",
+        "rule": "every template node's `component` canonicalizes to an L0 catalog entry",
+        "why": "The composability law. Canonicalization goes A2UI type -> tag (packages/gen-ui/a2ui/registry.js) -> catalog component name, because templates emit A2UI standard type names (Column, CheckBox, ChoicePicker) while L0 is keyed by catalog names (Col, Check, Select). Excludes templates using FormContainer / DescriptionTerm / DescriptionDetail / ColDef (native elements and sub-descriptors with no L0 entry) and AdminShell (an L3 unit — correctly not composable at L1)."
+      },
+      {
+        "id": "G3",
+        "name": "chat-scale",
+        "rule": "6 <= template.length <= 30 nodes",
+        "why": "Below 6 nodes an entry is a decorated primitive, not a widget — it adds a name without adding composition. Above 30 it is a section or a page, which is L2's unit."
+      },
+      {
+        "id": "G4",
+        "name": "self-contained",
+        "rule": "chunk.nested.length === 0",
+        "why": "A chunk that contains another chunk is a composition of compositions — L2 by the ladder's own definition."
+      },
+      {
+        "id": "G5",
+        "name": "retrieval-ready",
+        "rule": "metadata.domain && metadata.description && metadata.keywords.length >= 6",
+        "why": "An entry a chat agent cannot find is not a served entry. Domain, description, and keywords are what the protocol MCP will enumerate on (phase 3)."
+      }
+    ],
+    "selection": [
+      {
+        "id": "S1",
+        "name": "one entry per composition shape",
+        "rule": "Within a group of gated candidates sharing an identical canonical `composes` set, admit at most one — the most generically-named, most complete representative.",
+        "why": "Curated, not census. `banner-announcement-beta` and `banner-announcement-promo` are the same widget with different copy; shipping both spends the vocabulary budget on duplicates."
+      },
+      {
+        "id": "S2",
+        "name": "domain cap",
+        "rule": "At most 3 entries per metadata.domain.",
+        "why": "Breadth is the first slice's job. Uncapped, `data` / `forms` / `settings` alone would take half the tier and leave billing, overlay, and content unrepresented."
+      },
+      {
+        "id": "S3",
+        "name": "the named-thing test",
+        "rule": "Judgment: would an agent ask for this by name? Prefer canonical shapes over page-specific instances.",
+        "why": "The one criterion that cannot be mechanized, and the reason this file is authored rather than derived."
+      }
+    ]
+  },
+  "census": {
+    "corpusTemplates": 516,
+    "afterG1G2": 431,
+    "afterAllGates": 273,
+    "curated": 44,
+    "note": "44 of 273 gated (16%), 8.5% of the 516 templates. The remaining 229 gated candidates are the backlog for the next curation pass, not rejects."
+  },
+  "entries": {
+    "agent": [
+      "agent-tool-call-accordion",
+      "agent-reasoning-collapsed",
+      "agent-memory-list"
+    ],
+    "auth": [
+      "access-denied-with-request",
+      "auth-signin-card-otp",
+      "verification-stepper"
+    ],
+    "billing": [
+      "checkout-order-summary-card",
+      "usage-quota-meter-card"
+    ],
+    "content": [
+      "faq-accordion",
+      "comments-composer",
+      "code-snippet"
+    ],
+    "dashboard": [
+      "analytics-chart",
+      "chart-in-card-full-chart",
+      "retention-cohort-with-legend"
+    ],
+    "data": [
+      "stat-cards-kpi-dashboard",
+      "search-results-list",
+      "order-tracking-timeline"
+    ],
+    "data-management": [
+      "data-export-history",
+      "export-flow-delivery"
+    ],
+    "display": [
+      "user-profile-card",
+      "bell-menu-empty",
+      "image-caption-tile"
+    ],
+    "error": [
+      "banner-system-maintenance"
+    ],
+    "forms": [
+      "login-form-card",
+      "signup-form-card",
+      "contact-form-card"
+    ],
+    "input": [
+      "filter-popover-form"
+    ],
+    "layout": [
+      "admin-page-header-with-actions",
+      "tabs-with-panels",
+      "avatar-group-overflow"
+    ],
+    "marketing": [
+      "hero-cta-simple",
+      "feature-grid-three-cards",
+      "testimonial-pull-quote"
+    ],
+    "navigation": [
+      "admin-topbar-breadcrumb-actions",
+      "app-nav-groups",
+      "toolbar-icons"
+    ],
+    "onboarding": [
+      "onb-persona-picker",
+      "product-tour"
+    ],
+    "overlay": [
+      "alert-dialog-unsaved",
+      "destructive-confirm-modal",
+      "inline-dialog-rename"
+    ],
+    "settings": [
+      "webhooks-list",
+      "api-keys-list",
+      "permissions-role-picker-radio"
+    ]
+  }
+}