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

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

@@ -1,223 +0,0 @@
-# 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 |