@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/patterns-agent.md

@@ -0,0 +1,223 @@
+# Agent & Chat Patterns
+
+## Chat Shell (canonical substrate composition)
+
+The canonical chat surface composes substrate primitives directly — `<chat-shell>` orchestrates LLM streaming + proxy-url wiring, with bespoke children for header / thread / composer / sidebar:
+
+```html
+<chat-shell
+    proxy-url="/api/chat"
+    provider="anthropic"
+    model="claude-sonnet-4-7"
+    system="You are a helpful assistant."
+    thinking>
+  <chat-header>
+    <span slot="name">Assistant</span>
+    <chat-status slot="status">Connected</chat-status>
+  </chat-header>
+
+  <chat-thread>
+    <chat-empty>
+      <empty-state-ui icon="chat-circle" heading="How can I help?" description="Ask anything."></empty-state-ui>
+    </chat-empty>
+  </chat-thread>
+
+  <chat-composer>
+    <chat-input-ui placeholder="Message…" submit-on-enter></chat-input-ui>
+  </chat-composer>
+</chat-shell>
+```
+
+| Element | Purpose |
+|-----------|---------|
+| `chat-shell` | Behavior-only LLM-streaming orchestrator. Wires markdown rendering, code-block upgrades, proxy-url integration |
+| `chat-header` | Top chrome bar — name, status, settings |
+| `chat-thread` | Message-list scroll surface; reflects `[streaming]`, `[empty]` on itself |
+| `chat-empty` | Empty-state slot inside `<chat-thread>` |
+| `chat-composer` | Wraps the input primitive; flex footer alignment |
+| `chat-input-ui` | Primitive textarea with submit-on-enter, slash-commands, attachments |
+| `chat-sidebar` | Optional `slot="leading"` — conversation list, persistence |
+| `chat-status` | Reflected connection indicator inside `<chat-header>` |
+
+**State as attribute (cross-cut via `:has()`):**
+
+```css
+chat-shell:has(chat-thread[streaming]) chat-header { /* show streaming indicator */ }
+chat-shell:has(chat-thread[empty]) chat-composer { /* center the empty-state */ }
+```
+
+For the full canonical shape including sidebar persistence and styling, see `flows-shells.md` `## Chat Shell` and the substrate demo at `packages/web-modules/chat/chat-shell/chat-shell.examples.html`. Per ADR-0023, all children are bespoke cluster-namespaced elements; legacy data-attribute shapes (`[data-chat-messages]`, `[data-chat-input]`) were retired in v0.4.0 per ADR-0024.
+
+## Manual Chat Layout (vanilla composition, no chat-shell)
+
+Build a chat surface from raw layout primitives — useful when you need full control over message-bubble rendering or aren't wiring an LLM stream:
+
+```html
+<card-ui size="lg" style="height:600px;display:flex;flex-direction:column">
+  <header divider>
+    <span slot="icon"><avatar-ui text="Assistant" size="sm"></avatar-ui></span>
+    <span slot="heading" variant="section">Assistant</span>
+    <badge-ui slot="action" text="Online" variant="success" size="xs"></badge-ui>
+  </header>
+  <section style="flex:1;overflow-y:auto">
+    <col-ui gap="4" id="messages"></col-ui>
+  </section>
+  <footer divider>
+    <row-ui gap="2" style="width:100%">
+      <input-ui raw placeholder="Type a message..." style="flex:1"></input-ui>
+      <button-ui text="Send" variant="primary" icon="paper-plane-right" size="sm"></button-ui>
+    </row-ui>
+  </footer>
+</card-ui>
+```
+
+## Message Bubbles
+
+```html
+<!-- User (right-aligned) -->
+<row-ui justify="end">
+  <card-ui size="sm" variant="filled" style="max-width:70%;background:var(--a-accent-subtle)">
+    <section><p>Can you help me build a dashboard?</p></section>
+  </card-ui>
+</row-ui>
+
+<!-- Assistant (left-aligned with avatar) -->
+<row-ui gap="2" align="start">
+  <avatar-ui text="AI" size="sm"></avatar-ui>
+  <card-ui size="sm" style="max-width:70%">
+    <section><p>I'd be happy to help!</p></section>
+  </card-ui>
+</row-ui>
+```
+
+## Suggestion Chips
+
+```html
+<row-ui gap="1" style="flex-wrap:wrap">
+  <button-ui text="Stat cards dashboard" variant="outline" size="sm"></button-ui>
+  <button-ui text="Login form" variant="outline" size="sm"></button-ui>
+  <button-ui text="User profile card" variant="outline" size="sm"></button-ui>
+</row-ui>
+```
+
+## A2UI Rendering
+
+### Static
+```html
+<a2ui-root id="surface"></a2ui-root>
+```
+```js
+root.processAll([{
+  type: 'updateComponents',
+  surfaceId: 'default',
+  components: [
+    { id: 'root', component: 'Card', children: ['hdr', 'sec'] },
+    { id: 'hdr', component: 'Header', children: ['title'] },
+    { id: 'title', component: 'Text', variant: 'h3', textContent: 'Hello' },
+    { id: 'sec', component: 'Section', children: ['col'] },
+    { id: 'col', component: 'Column', children: ['msg'] },
+    { id: 'msg', component: 'Text', variant: 'body', textContent: 'Generated content.' },
+  ],
+}]);
+```
+
+### Streaming
+```html
+<a2ui-root src="/api/agent" transport="sse"></a2ui-root>
+```
+Transports: `sse`, `ws`, `jsonl`, `mcp`.
+
+### A2UI Playground (debugging)
+
+For interactive A2UI debugging — schema explorer, surface state inspection, code view — open the playground app at `apps/genui/` (multi-route a2ui workbench) or `playgrounds/composed-flow/` (single-page demo). There is no dedicated `<a2ui-playground>` primitive; the playground experience is composed via `<a2ui-root>` + `<chat-shell>` + dev panels in those apps.
+
+## Gen UI Pipeline
+
+```js
+import { generateUI, generateUIStream } from '@adia-ai/a2ui-compose';
+
+// Instant mode (pattern matching, no LLM)
+const result = await generateUI({ intent: 'login form', mode: 'instant' });
+
+// Streaming mode (LLM-powered)
+for await (const event of generateUIStream({ intent: 'dashboard with metrics', llmAdapter })) {
+  switch (event.type) {
+    case 'status':    // pipeline stage transition
+    case 'clarify':   // vague intent — questions for user
+    case 'research':  // brand/reference research results
+    case 'decompose': // complex intent split into subtasks
+    case 'text_delta': // raw LLM text chunk
+    case 'partial':   // parseable partial A2UI — render immediately
+    case 'complete':  // final result with validation, suggestions, executionId
+    case 'error':     // generation error
+  }
+}
+```
+
+Multi-turn: pass `executionId` from a previous `complete` event to iterate.
+
+## Evolution Engine
+
+```js
+import { savePattern, importPattern, FeedbackCollector, evaluatePromotion } from '@adia-ai/a2ui-compose';
+
+// Save a generation as a reusable pattern
+savePattern('login-form', { messages: result.messages, validation: result.validation, intent: 'login form', canvasHTML: canvas.getHTML() });
+
+// Import at runtime
+importPattern(patternJSON);
+
+// Collect user feedback
+const feedback = new FeedbackCollector();
+feedback.initFromGeneration(execId, { intent, domain, messages, validation });
+feedback.collectFeedback(execId, { rating: 5, intentAlignment: 5, visualQuality: 4, componentChoice: 5 });
+
+// Check if this should become a named pattern
+const promo = evaluatePromotion({ score: 98, feedback: { rating: 5 }, alignment: { score: 0.9 } });
+// -> { shouldPromote: true, confidence: 0.97, suggestedName: 'login-form' }
+```
+
+## Activity Feed
+
+```html
+<card-ui>
+  <header><span slot="heading" variant="section">Activity</span></header>
+  <section>
+    <col-ui gap="2">
+      <row-ui gap="2" align="start">
+        <avatar-ui text="Jane" size="sm"></avatar-ui>
+        <col-ui gap="1">
+          <small><strong>Jane</strong> created a new project</small>
+          <small style="color:var(--a-canvas-text-subtle)">2 minutes ago</small>
+        </col-ui>
+      </row-ui>
+      <divider-ui></divider-ui>
+      <row-ui gap="2" align="start">
+        <avatar-ui text="Alex" size="sm"></avatar-ui>
+        <col-ui gap="1">
+          <small><strong>Alex</strong> deployed to production</small>
+          <small style="color:var(--a-canvas-text-subtle)">15 minutes ago</small>
+        </col-ui>
+      </row-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+
+## MCP Tools (13)
+
+| Tool | Purpose |
+|------|---------|
+| `generate_ui` | Natural language -> A2UI |
+| `validate_schema` | 15 structural + 5 wiring checks |
+| `lookup_component` | Component API by type name |
+| `get_component_map` | Full 80-type catalog |
+| `search_patterns` | Keyword + semantic + remix search |
+| `classify_intent` | Domain classification |
+| `assemble_context` | Token-budgeted context assembly |
+| `check_anti_patterns` | HTML anti-pattern detection |
+| `get_traits` | Trait catalog |
+| `convert_html` | HTML -> A2UI transpilation |
+| `get_wiring_catalog` | Controller/handler/resolver catalog |
+| `import_pattern` | Import pattern JSON at runtime |
+| `submit_feedback` | Structured quality feedback |