@nano-ui-kit/a2ui-corpus

Corpus and operational-learning artifacts for the gen-UI pipeline — patterns, fragments, compositions, exemplars, feedback, gaps, eval fixtures. Pure data plus the scripts that maintain it. No runtime.

The pipeline reads this package; this package never reads the pipeline. See @nano-ui-kit/a2ui-compose for engine code, @nano-ui-kit/web-components for UI atoms, @nano-ui-kit/a2ui-mcp for the MCP server.

Dependency direction

gen-ui           ──reads──▶  a2ui-corpus
a2ui-mcp       ──reads──▶  gen-ui, a2ui-corpus
web-components   ◀─reads──   a2ui-corpus (exemplars use NanoUI tags)

No back-writes. No circular reads. Web-components ships UI atoms only; corpus lives here; runtime lives in gen-ui.

Layout

a2ui-corpus/
├── patterns/                ~97 full-canvas A2UI templates (retrieval corpus)
│   ├── <domain>/<name>.json   agent · data · forms · layout · navigation · settings
│   ├── _components.json       canonical name + aliases map (Carousel → Swiper)
│   └── _taxonomy.json         concept synonyms (auth → [login, signup, otp])
│
├── fragments/               atomic shapes — building blocks for Zettel
│   ├── action/                  button rows, toolbars, inline CTAs
│   ├── content/                 stat cards, list items, media blocks
│   ├── form/                    field, field-row, field-group recipes
│   └── layout/                  section, grid, card scaffolding
│
├── compositions/            named multi-fragment recipes
│   ├── agent/ data/ form/ layout/ navigation/ settings/
│                              each = pre-assembled fragment set with keywords + tags
│
├── exemplars/               hand-authored HTML sources
│   ├── ui/                      component-level exemplars
│   └── prose/                   prose + mixed-content exemplars
│                              extract.js compiles these → chunks/ + catalog
│
├── evals/                   held-out.jsonl + eval fixtures
├── chunks/                  extracted A2UI fragments  (build output)
├── pages/                   extracted full-page A2UI   (build output)
├── feedback/                daily JSONL — user feedback events
├── gaps/                    gap registry — prompts with missing coverage
├── scripts/                 maintenance tooling (extract, ingest, feedback, ticket)
│
├── catalog-a2ui_0_9.json       aggregated artifact — what gen-ui + MCP read
├── catalog-a2ui_0_9_rules.txt  natural-language composition rules (per component)
├── common_types.json           shared A2UI type shapes
├── pattern-embeddings.json     pre-computed embeddings for semantic search
├── functions.json              declarative wiring-engine function catalog
├── manifest.json               extraction metadata (what / when / counts)
├── pattern-specs.md            written specs for each pattern category
└── data-flow.md                how the 4 signal sources feed the pipeline

What's committed vs generated

| Kind | Committed | Source of truth | |----------------------------|-----------|----------------------------------------| | Patterns (patterns/) | ✓ | Hand-authored JSON | | Fragments/compositions | ✓ | Hand-authored JSON | | Exemplars (exemplars/) | ✓ | Hand-authored HTML | | Extracted chunks/pages | ✓ | scripts/extract.js (from exemplars) | | catalog-a2ui_0_9.json | ✓ | scripts/build-catalog.js (aggregated)| | Feedback JSONL | ✓ | Written by gen-ui/retrieval/ at runtime | | Gap registry | ✓ | Written by gen-ui/retrieval/ at runtime |

Extracted artifacts are committed for convenience (avoids a build step to read the pipeline), but the scripts are authoritative — regenerate via npm run pipeline if anything drifts.

Scripts

All run from repo root via npm:

npm run pipeline             # extract + ingest (full refresh of chunks/ + catalog)
npm run pipeline:stats       # report counts without writing
npm run build:catalog        # aggregate patterns/fragments/compositions → catalog
npm run build:catalog -- --verify   # fail if catalog is stale vs source

npm run feedback:report      # human-readable feedback digest
npm run feedback:promote     # promote high-confidence feedback → new patterns

npm run ticket               # open ticket tracker
npm run ticket:list          # list open tickets
npm run ticket:create        # create a ticket against corpus/pipeline

Script inventory (scripts/):

| Script | Purpose | |---------------------------|------------------------------------------------------| | extract.js | Exemplar HTML → A2UI chunks & pages | | ingest.js | Index extracted chunks into the retrieval corpus | | run-pipeline.mjs | Orchestrates extract + ingest | | build-pattern-index.mjs | Computes pattern-embeddings.json for semantic search | | feedback-report.js | Aggregates feedback JSONL into a readable digest | | feedback-promote.js | Moves high-confidence feedback into the pattern lib | | ticket.mjs | Corpus/pipeline issue tracker |

Exports

// Catalog — the aggregated read-target for engines
import catalog from '@nano-ui-kit/a2ui-corpus';

// Alias map + taxonomy
import aliases from '@nano-ui-kit/a2ui-corpus/patterns';

// Held-out eval fixture
import fixture from '@nano-ui-kit/a2ui-corpus/evals/held-out.jsonl?raw';

// Exemplar source (for scripts + docs)
import html from '@nano-ui-kit/a2ui-corpus/exemplars/ui/pricing-tiers.html?raw';

Authoring order — demo page → exemplar → training

When adding coverage for a new intent:

1. Site demo page — author the HTML in site/pages/examples/** using pure primitive composition (no <style> block, no inline styles, only real components). See repo-root AGENTS.md.
2. Exemplar — copy the working markup into a2ui-corpus/exemplars/ui/<name>.html. Strip non-essential chrome; keep attributes that encode intent.
3. Extract + ingest — npm run pipeline. The scripts write chunks/, pages/, and refresh the catalog.
4. Verify — npm run eval:diff -- --engine zettel should still hold coverage 100%, avgScore ≥ 88. Regression thresholds in AGENTS.md.

See data-flow.md for the full 4-signal pipeline (exemplars → fragments → compositions → feedback).

Regression floors

The pipeline must hold these thresholds — tracked in the held-out benchmark:

• Fragment reuse ratio ≥ 29.9% — 167 refs / 559 composition nodes
• Zettel: coverage 100%, avgScore ≥ 88, MRR ≥ 0.94
• Monolithic: coverage 100%, avgScore ≥ 95
• Dogfood: 20/20 intents at avg ≥ 95

What this package does NOT contain

• Pipeline runtime — gen-ui/
• UI custom elements — web-components/
• MCP transport — a2ui-mcp/
• Site / playground UI — /site/

If a file here is .js / .mjs, it's a maintenance script, not runtime. Runtime readers go through gen-ui/retrieval/*.

License

MIT