@adia-ai/a2ui-compose 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -12,6 +12,22 @@ generator graph.
 
 _No pending changes._
 
+## [0.4.5] - 2026-05-12
+
+### Changed — GenUI overhaul prompt-engineering (§56, v0.4.5)
+
+- **`strategies/monolithic/_shared.js` — CORPUS CONTEXT block added to `buildSystemPrompt`** (~30 new lines between role/output-format and CARD-N content model). Surgical insertion explaining the §36-§51 retrieval-augmented pipeline:
+  - Pipeline searches PATTERNS / COMPOSITIONS first (full-canvas A2UI templates: login-form, pricing-tiers, dashboard-admin-page)
+  - Pipeline also searches ANNOTATED CHUNKS (real production HTML with `metadata.{domain, keywords, description}`)
+  - When matched, `MATCHED PATTERN` / `STRUCTURAL REFERENCE` blocks carry the actual reference
+  - Only AVAILABLE COMPONENTS are usable — anything else is a hallucination
+
+  Cost: ~150 tokens per request. Benefit: LLM understands what the pipeline around it IS instead of treating the matched-pattern block as anonymous instructions. Existing rules unchanged; no removed lines.
+
+- **`strategies/monolithic/generate-pro.js` — STRUCTURAL REFERENCE prose enriched.** Prior copy: "a real production block from the codebase matched this intent." New copy: "this chunk was retrieved from the AdiaUI training corpus (annotated production HTML, harvested from real app pages). It matched your intent on keyword/domain ranking." Threads chunk `metadata.domain`, `metadata.description`, `metadata.keywords` into the prompt when present. Reframes "do not copy the HTML" as "the chunk represents the SHAPE the user wants; instantiate it with their content" — more actionable framing.
+
+See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the v0.4.5 overhaul arc + apps/genui/CHANGELOG.md `[Unreleased]` for the per-§ rollup.
+
 ## [0.4.4] - 2026-05-12
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {

package/strategies/monolithic/_shared.js

@@ -51,6 +51,32 @@ Output format: [{ "type": "updateComponents", "surfaceId": "default", "component
 Each component: { "id": "<unique>", "component": "<Type>", "children": ["<childId>", ...], ...props }
 The root must have id "root". Use short, descriptive IDs (e.g., "hdr", "email-field", "submit-btn").`);
 
+  // ── Corpus context (§56, v0.4.5) ──
+  // Tells the LLM how the system surrounding it is wired so it doesn't
+  // hallucinate component names and so it understands what MATCHED PATTERN /
+  // STRUCTURAL REFERENCE blocks actually ARE. Keep this section tight — every
+  // token costs latency + money.
+  parts.push(`CORPUS CONTEXT (the system around you):
+
+You are part of a retrieval-augmented pipeline. Before this prompt was built,
+the pipeline searched two corpora for matches to the user's intent:
+
+1. PATTERNS / COMPOSITIONS — full-canvas A2UI templates curated for the
+   AdiaUI design system. Examples: login-form, pricing-tiers,
+   dashboard-admin-page. When a strong match exists, you'll see a
+   "MATCHED PATTERN" block below with the canonical template.
+
+2. ANNOTATED CHUNKS — real production HTML blocks harvested from the AdiaUI
+   apps (auth flows, dashboards, error pages, etc.) with metadata
+   (domain, keywords, description). When a strong chunk match exists,
+   you'll see a "STRUCTURAL REFERENCE" block with the production HTML.
+   Match its component palette + information density, but translate to
+   A2UI components — do not copy raw HTML.
+
+Both corpora use ONLY components from the AVAILABLE COMPONENTS list further
+down. If you would invent a component name not in that list, you're
+hallucinating — use the closest canonical name instead.`);
+
   // ── Card-N content model (critical for quality) ──
   parts.push(`CARD-N CONTENT MODEL (mandatory for any card surface):
 - Card > Header: for title/description. Use Text children with heading variants (h3, h4).

package/strategies/monolithic/generate-pro.js

@@ -221,10 +221,18 @@ export async function generatePro({ intent, executionId, storeId, llmAdapter, an
   //    structural "look like this" hint that lets the LLM materialize the
   //    real chunk shape (e.g. auth-signin-card-email) instead of
   //    hallucinating a passable-but-wrong shape from the brief alone.
+  //
+  //    §56 (v0.4.5): prompt language enriched with provenance + metadata so
+  //    the LLM understands the chunk's domain/keywords context. Tested via
+  //    factory-chat + gen-ui live submit; LLMs produce closer structural
+  //    matches when told what the chunk is + where it came from.
   const chunkReferenceBlock = chunkRefHtml
-    ? `\nSTRUCTURAL REFERENCE — a real production block from the codebase matched this intent. Match its component palette, information density, and Card / Header / Section / Footer anatomy. Do NOT copy the HTML verbatim into A2UI; translate its semantic structure into the equivalent A2UI components:
+    ? `\nSTRUCTURAL REFERENCE — this chunk was retrieved from the AdiaUI training corpus (annotated production HTML, harvested from real app pages). It matched your intent on keyword/domain ranking:
+
+CHUNK: ${chunkMatch.name}
+  kind=${chunkMatch.kind}, primary=${chunkMatch.primary}, score=${chunkMatch.score}${chunkMatch.metadata?.domain ? `, domain=${chunkMatch.metadata.domain}` : ''}${chunkMatch.metadata?.description ? `\n  description: ${chunkMatch.metadata.description}` : ''}${chunkMatch.metadata?.keywords ? `\n  keywords: ${chunkMatch.metadata.keywords.join(', ')}` : ''}
 
-CHUNK: ${chunkMatch.name} (${chunkMatch.kind}, primary=${chunkMatch.primary}, score=${chunkMatch.score})
+Match this chunk's component palette, information density, and Card/Header/Section/Footer anatomy. Do NOT copy the HTML verbatim into A2UI — translate its semantic structure into the equivalent A2UI components. The chunk represents the SHAPE the user wants; your job is to instantiate that shape with their content:
 ---
 ${chunkRefHtml}
 ---