@adia-ai/a2ui-corpus 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -7,10 +7,99 @@ compositions, exemplars, held-out eval fixtures, feedback registry,
 gap registry. Consumed by `@adia-ai/a2ui-retrieval` and
 `@adia-ai/a2ui-mcp`.
 
+> **Historical note (2026-05-05):** Entries dated before v0.3.0 reference
+> "all 8 published `@adia-ai/*` packages" — that was the package count at
+> the time. The lockstep policy expanded to 9 packages at v0.3.0 when
+> `@adia-ai/llm` joined; see the [0.3.0] entry below for the transition
+> details. References to "8 packages" in older entries are factually
+> correct as of the date they were written and are preserved per
+> Keep-A-Changelog convention (don't rewrite history).
+
 ## [Unreleased]
 
 _No pending changes._
 
+## [0.3.4] - 2026-05-07
+
+### Changed
+
+- **Component catalog regenerated** — 100 → 107 yamls (+7 from new admin-* CSS-only structural children added in `@adia-ai/web-modules`). `catalog-a2ui_0_9.json` + `catalog-a2ui_0_9_rules.txt` regenerated by `scripts/build/components.mjs`.
+
+- **New catalog entries** for the bespoke shell-tier family per ADR-0023:
+  - `AdminSidebar` (admin-sidebar) — JS-bearing
+  - `AdminCommand` (admin-command) — JS-bearing
+  - `AdminContent` / `AdminTopbar` / `AdminStatusbar` / `AdminScroll` / `AdminPage` / `AdminPageHeader` / `AdminPageBody` — CSS-only structural
+
+The catalog is consumed by `@adia-ai/a2ui-retrieval` for protocol-vocabulary composition. Composers (zettel, chunk-zettel) now have addressable entries for shell sub-regions instead of falling back to chunk-name retrieval.
+
+### No source changes
+
+Corpus chunks, fragments, compositions, and patterns are byte-identical to v0.3.3. The only change is the regenerated catalog manifest.
+
+## [0.3.3] - 2026-05-07
+
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
+
+### Added
+
+- **`fragments/layout/auth-card-header.json`** — first fragment
+  promoted from chunk corpus. Was 23 instances across user-flow auth
+  pages (sign-in, sign-up, recovery, account-deleted, email-verify,
+  forbidden) + error pages (404, 500, maintenance), all sharing the
+  same shape: `Header > Column[align=center,gap=1] >
+  [Link>Image, Text(h1), Text]`. 4 slots
+  (logo-href, logo-src, title, description). Promotion provides 23×
+  leverage over chunk-by-chunk emission. Zettel retrieval test:
+  score 88 vs 48 next alternative. (closes backlog #65)
+
+- **`A2UI_DISABLE_EMBEDDINGS` env-var override** in
+  `scripts/chunk-library.js`. When set, `searchChunksAsync()` falls
+  through to keyword-only search instead of attempting embeddings.
+  Used by the new top-level `npm run eval:keyword-only` script.
+  Latency drops from 100-400ms to 0-1ms with same scores; proves
+  keyword path is independently healthy. (closes backlog #11)
+
+- **Glossary section** in README.md — chunk vs pattern vs fragment
+  vs composition. Four overlapping concepts circulate through this
+  package; the glossary disambiguates. (closes backlog #94)
+
+- **Catalog manifest documentation** — README updated to clarify
+  that `retrieval/catalog.js` is **hand-written** (a CatalogManifest
+  module that dynamically reads per-component `<c>.a2ui.json`
+  sidecars at runtime), NOT a generated artifact. The actual
+  generated artifacts are `traits/_catalog.json` and per-component
+  `<name>.a2ui.json` sidecars. (companion to AGENTS.md hard-rule #7
+  correction; closes backlog #57)
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### Added
+
+- **Corpus re-harvest** — 173 unique chunks (from 160), 322 instances.
+  13 new block patterns (`command-palette-grouped`, `agent-activity-feed`,
+  `agent-reasoning-collapsed`, `user-profile-card`, `kanban-board-3col`,
+  `chat-streaming-surface`, `settings-notifications`, `marketing-hero-cta`,
+  `conversion-funnel-6step`, `users-table-badge`, `destructive-confirm-modal`,
+  `editor-code-pane`, `editor-preview-pane`) + 5 new page shells
+  (`settings-page-shell`, `form-page-shell`, `marketing-page-shell`,
+  `error-page-shell`, `editor-page-shell`).
+- **Harvester source expansion** — `apps/` added alongside `site/pages/`;
+  `apps/generic-shells/app/` contributes the 5 generic page shells.
+
+### Fixed
+
+- **`data-chunk-slot` preservation** — `stripChunkAttrs()` regex narrowed
+  to only strip `data-chunk` + `data-chunk-kind`; no longer strips
+  `data-chunk-slot` (composer runtime dependency for slot-finding).
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).

package/README.md

@@ -22,6 +22,30 @@ web-components ◀─reads──   a2ui-corpus (exemplars use AdiaUI tags)
 No back-writes. No circular reads. Web-components ships UI atoms only;
 corpus lives here; runtime lives in a2ui-compose.
 
+## Glossary
+
+Four overlapping concepts circulate through this package. Knowing which
+is which prevents reading bugs from creeping into authoring.
+
+| Term | Source of truth | Granularity | What it carries | Engine that consumes it |
+| --- | --- | --- | --- | --- |
+| **chunk** | `chunks/<id>.json` (one file per chunk) + `_index.json` | Smallest — a single labeled HTML region, harvested via `data-chunk` markers | `html`, `intent`, `domain`, `kind` (`block` / `data-chunk` / `field`), `keywords` | `chunk-zettel` (retrieve → synthesize) |
+| **pattern** | `patterns/<domain>/<name>.json` | Full-canvas A2UI template (≈whole-page) | A2UI message tree, retrieval keywords, exemplar provenance | `monolithic-instant` / `monolithic-pro` (retrieve → emit verbatim) |
+| **fragment** | `fragments/<domain>/<name>.json` | Atomic shape — re-usable across compositions | A2UI sub-tree, slot bindings, `metrics.leverage` | `zettel` (retrieve → compose into compositions) |
+| **composition** | `compositions/<domain>/<name>.json` | Pre-assembled set of fragments | Ordered fragment refs, slot wiring, keywords + tags, `links.used_by` | `zettel` (retrieve → emit verbatim or refine) |
+
+**One-line distinctions:**
+
+- **Chunk vs fragment** — chunks are *harvested*, fragments are *authored*. A chunk is whatever HTML region a `data-chunk` marker pointed at; a fragment is a deliberately-shaped A2UI sub-tree with named slots and leverage metrics.
+- **Fragment vs composition** — a fragment is *one shape*; a composition is *several fragments arranged together* into a coherent surface (e.g. `pricing-tiers` composition = header fragment + 3× tier-card fragments + footer fragment).
+- **Composition vs pattern** — both are full-surface, but compositions are *fragment-graph* native (zettel reuses the fragment library) while patterns are *flat A2UI templates* (monolithic emits them whole).
+
+**When in doubt, follow the engine:**
+
+- Looking at `monolithic-*` retrieval? You want a **pattern**.
+- Looking at `zettel` retrieval? You want a **composition** (or a fragment, if synthesis is composing one).
+- Looking at `chunk-zettel`? You want a **chunk**.
+
 ## Layout
 
 ```
@@ -107,6 +131,46 @@ Consumers who want embedding-based retrieval either:
    fall through to keyword scoring when the index file is absent
    (`chunk-embedding-retriever.js` returns `null` gracefully).
 
+### Embedding model pinning
+
+The `provider` and `model` recorded in each `*-embeddings.json` header
+are the **source of truth** at query time. The retrievers
+(`chunk-embedding-retriever.js`, `embedding-retriever.js`) re-resolve
+the same embedder from those header fields — they do **not** auto-pick
+a different provider when the recorded one's API key is unset, because
+cross-model cosine similarity is meaningless and same-provider/
+different-model emits different-dim vectors that `cosine()`
+short-circuits to 0 (silent retrieval failure).
+
+Currently pinned defaults:
+
+| Provider | Model | Dims | Env |
+|---|---|---:|---|
+| openai | `text-embedding-3-small` | 1536 | `OPENAI_API_KEY` |
+| voyage | `voyage-3-lite` | 1024 | `VOYAGE_API_KEY` |
+
+`detectProvider()` (in `packages/a2ui/retrieval/embedding/embedding-provider.js`)
+prefers Voyage when both keys are present (denser vectors, lower cost).
+The `build:embeddings*` scripts record the chosen provider/model into the
+`.json` header, so subsequent reads always re-bind to the same model.
+
+When upgrading to a new model (e.g. `text-embedding-3-small` →
+`text-embedding-3-large`):
+
+1. Update the default in `embedding-provider.js`.
+2. Rebuild **both** indexes (`npm run build:embeddings:all`).
+3. Verify with `npm run check:embeddings-fresh` that both index headers
+   record the new model.
+4. Re-run `npm run eval:diff -- --engine zettel` to confirm the new
+   model doesn't regress retrieval quality (different models score
+   queries differently — thresholds in `chunk-synthesizer.js` may
+   need a re-look, though the absolute keyword score floor remains
+   independent).
+
+Don't mix models. If one index records `voyage-3-lite` and the other
+records `text-embedding-3-small`, the retrievers will load both fine
+but the rankings will be incomparable across the two corpora.
+
 ## Scripts
 
 All run from repo root via npm: