@ds-mo/ui 13.14.0 → 13.16.0

package/dist/.package-ready.json

@@ -1 +1 @@
-{"schemaVersion":1,"package":"@ds-mo/ui","version":"13.14.0","components":66,"digest":"09d9df9310c46e04ea473cb773aa9b27d777c2c11523c37fa3f5d7e7a3863cea","completedAt":"2026-08-12T04:49:31.606Z"}
+{"schemaVersion":1,"package":"@ds-mo/ui","version":"13.16.0","components":67,"digest":"55fed7e47f4c13794943756d36dadf566a3d4c505a7f1fde06e6595a0fd383da","completedAt":"2026-08-13T00:16:44.079Z"}

package/dist/agent-patterns.json

@@ -1,40 +1,55 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "13.14.0",
+  "packageVersion": "13.16.0",
   "kind": "patterns",
   "entries": [
     {
       "id": "pattern:agent-chat",
       "status": "experimental",
-      "summary": "Extend the generic conversation pattern with ordered agent response parts while keeping transport and product behavior outside the design system.",
+      "summary": "Compose provider-neutral agent turns from serializable or slotted response content, normalized tool lifecycle, pending human input, inline sources, and reader-respecting transcript movement.",
       "useWhen": [
-        "A chat presents rich agent output including Markdown, safe activity, display-only tool calls, attachments, or sources."
+        "A conversation presents rich agent output and may pause for structured participant input before the agent continues."
       ],
       "avoidWhen": [
-        "The channel is person-to-person or the component would be expected to execute models, tools, approvals, or persistence."
+        "The channel is person-to-person or the design-system layer would be expected to own models, provider schemas, transport, persistence, tool execution, approval consequences, or private reasoning."
       ],
       "components": [
         {
           "component": "component:ds-message-scroller",
-          "role": "Provides generic transcript movement and live-edge behavior.",
+          "role": "Positions new turn anchors, preserves reader-controlled live-edge behavior, and measures pending interaction with composer clearance.",
           "required": true
         },
         {
           "component": "component:ds-message",
-          "role": "Renders participant turns with channel-neutral semantics.",
+          "role": "Renders participant turns with channel-neutral semantics and marks application-owned outgoing turn anchors.",
           "required": true
         },
         {
           "component": "component:ds-message-bubble",
-          "role": "Renders user-sent prompts with the shared body-medium regular message baseline and secondary foreground.",
+          "role": "Renders user-sent prompts with the shared message baseline.",
           "required": true
         },
         {
           "component": "component:ds-agent-response",
-          "role": "Renders ordered normalized agent response parts.",
+          "role": "Renders ordered normalized parts or an application-composed ordered response body.",
           "required": true
         },
+        {
+          "component": "component:ds-agent-tool-call",
+          "role": "Presents a normalized provider-neutral tool lifecycle and optional custom result or diagnostic detail.",
+          "required": false
+        },
+        {
+          "component": "component:ds-agent-questionnaire",
+          "role": "Collects a temporary local answer draft above the composer and renders a quiet answered history record.",
+          "required": false
+        },
+        {
+          "component": "component:ds-agent-source-list",
+          "role": "Presents stable deduplicated sources inline after discovery is complete.",
+          "required": false
+        },
         {
           "component": "component:ds-message-actions",
           "role": "Provides completed-response Copy and controlled feedback without owning response data or consequences.",
@@ -42,31 +57,61 @@
         },
         {
           "component": "component:ds-message-composer",
-          "role": "Emits participant submission and stop intent.",
+          "role": "Emits participant submission and stop intent while keeping visible recoverable submission errors adjacent to the draft.",
           "required": true
         }
       ],
       "stateOwnership": [
-        "The application owns scripted or real transport, immutable response parts, retry, stop, generated titles, and persistence.",
-        "User-sent prompts use MessageBubble's user variant and body-medium regular default with secondary foreground; the application does not promote ordinary sent-message copy to body-large.",
-        "AgentResponse renders directly in Message without a MessageBubble surface, owns ordered display only, and never reveals private reasoning.",
-        "MessageActions may copy application-authored response text and emit controlled feedback intent; the application owns serialization, persistence, submission, permissions, analytics, and model consequences.",
-        "Markdown parsing and safe node creation belong to the renderer; the renderer-neutral @ds-mo/ui/prose.css surface owns only semantic-tree styling.",
-        "Tool-call components display execution state but do not request participant approval."
+        "The application normalizes every provider-specific tool and human-input state before rendering, and owns transport, immutable response parts, stop, retry, persistence, generated titles, permissions, and consequences.",
+        "Pending questionnaires render through the scroller interaction surface; the questionnaire owns only its current step and unsaved draft, while the application submits answers, resumes the agent, preserves failures, and replaces a successful interaction with an answered response record.",
+        "Tool calls display lifecycle only. Custom summary, result, and detail content must remain user-safe; execution, approval, retry, and authorization stay application-owned.",
+        "Choose response parts when ordered content must be serializable and registry-friendly. Choose composed mode when application-specific components must interleave with CompoMo primitives; the application owns that slotted content and its serialization.",
+        "Applications append stable deduplicated sources once retrieval settles. Active source discovery is an activity or tool state rather than a changing source list.",
+        "Applications mark only outgoing prompts that begin new turns as turn anchors. Saved transcript entry points may independently choose the last stored anchor.",
+        "Composer error actions are application-owned. The component presents failure above the editable box as one attached, measured support unit, and recovery never discards the participant draft.",
+        "Prompt suggestions and model selection are optional product composition. Suggestion selection normally fills and focuses the draft; model selection remains an application-owned tool-region control.",
+        "Markdown parsing and safe node creation belong to the renderer; the renderer-neutral public prose stylesheet owns semantic-tree styling and text measure without owning response ordering or streaming state.",
+        "TokoMo owns the semantic interface and code font-family tokens, CompoMo assigns text or diagnostic-code intent, and the application loads Inter and Fira Code assets once at its root; agent components never fetch font assets.",
+        "Agent activity is concise user-safe progress and never reveals private model reasoning or chain-of-thought."
       ],
       "accessibility": [
-        "Agent activity must be concise user-safe summaries, never hidden chain-of-thought.",
-        "Sources use descriptive external links and unsafe schemes remain non-interactive.",
-        "Streaming and tool states remain available as text without relying on animation."
+        "Tool lifecycle, questionnaire progress and validation, composer failure, and streaming state remain meaningful as text without relying on motion or color.",
+        "Applications move focus into a pending questionnaire only when context makes that shift appropriate; the component never steals focus on mount.",
+        "Source links use descriptive external-link names, derived hostnames, and noninteractive rendering for malformed or unsafe schemes.",
+        "Reader wheel, touch, keyboard, selection, and jump actions release live-edge following until Scroll to latest explicitly restores it."
       ],
       "responsiveBehavior": [
-        "Let AgentResponse use the available transcript width while retaining readable text measure and horizontal scrolling for code or tables."
+        "Let structured response content use the available lane while direct prose uses its readable measure, code and tables retain local overflow, questionnaire actions stack on narrow screens, and the combined interaction and composer stack remains fully measured."
       ],
       "implementations": {
         "customElements": {
-          "status": "planned",
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "pending-questionnaire",
+              "title": "Pending questionnaire above a conversation composer",
+              "summary": "Mark the outgoing turn, normalize the paused tool state, place temporary human input in the interaction surface, and keep submission transport in application code.",
+              "files": [
+                {
+                  "path": "agent-conversation.html",
+                  "language": "html",
+                  "content": "<ds-message-scroller messages-label=\"Agent conversation\" default-position=\"end\">\n  <ds-message message-id=\"turn-1\" direction=\"outgoing\" scroll-anchor>\n    <ds-message-bubble variant=\"user\">Prepare the maintenance follow-up.</ds-message-bubble>\n  </ds-message>\n  <ds-agent-response message-id=\"answer-1\" render-mode=\"composed\">\n    <ds-agent-tool-call name=\"work.prepare\" label=\"Choose the first follow-up\" state=\"waiting-for-user\"></ds-agent-tool-call>\n  </ds-agent-response>\n  <div slot=\"interaction\">\n    <ds-agent-questionnaire request-id=\"request-1\"></ds-agent-questionnaire>\n  </div>\n  <div slot=\"overlay\">\n    <ds-message-composer label=\"Message agent\"></ds-message-composer>\n  </div>\n</ds-message-scroller>"
+                },
+                {
+                  "path": "agent-conversation.ts",
+                  "language": "typescript",
+                  "content": "const questionnaire = document.querySelector('ds-agent-questionnaire')!;\nquestionnaire.questions = [{\n  id: 'priority',\n  type: 'single',\n  question: 'Which issue should be first?',\n  required: true,\n  choices: [\n    { value: 'battery', label: 'Repeated battery failures' },\n    { value: 'tires', label: 'Overdue tire inspections' },\n  ],\n}];\nquestionnaire.addEventListener('dsAnswer', async event => {\n  questionnaire.status = 'submitting';\n  try {\n    await submitAgentAnswers(event.detail);\n    questionnaire.status = 'answered';\n  } catch {\n    questionnaire.status = 'error';\n    questionnaire.errorMessage = 'Your answers could not be sent. Try again.';\n  }\n});\n\ndeclare function submitAgentAnswers(detail: { requestId: string; answers: unknown[] }): Promise<void>;"
+                }
+              ],
+              "notes": [
+                "On successful transport, remove the pending interaction and append an answered questionnaire response part to durable history rather than leaving the interactive surface in place."
+              ]
+            }
+          ],
           "references": [
-            "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+            "src/wc/components/MessageScroller/AgentChatReview.stories.ts",
+            "src/wc/components/MessageScroller/MessageScroller.stories.ts",
+            "src/docs/AgentConversations.mdx"
           ]
         },
         "react": {
@@ -84,6 +129,8 @@
       },
       "references": [
         "agent/patterns/conversation/pattern.agent.json",
+        "src/docs/AgentConversations.mdx",
+        "src/wc/components/MessageScroller/AgentChatReview.stories.ts",
         "src/wc/components/AgentResponse/AgentResponse.tsx"
       ]
     },
@@ -150,6 +197,7 @@
         "ShellApp owns responsive mode, PanelNav presentation, tool open state, active tool, mobile Inbox grouping, Menu state, fullscreen presentation, focus restoration, and breakpoint state preservation.",
         "Tool products and routed content are instantiated once by the application in named tool-view and default slots; ShellApp changes presentation without recreating those owners.",
         "The application owns account menus, tool product data, page actions, and the consequences of every emitted intent event.",
+        "The application owns viewport and theme-color metadata, the dynamic-viewport framework root, and containing document overscroll so body never becomes a second application scroller; ShellApp fills that owner and keeps its existing internal scrollers.",
         "The application resolves competing global messages to one Banner and owns its actions, controlled open state, orientation for the available shell capacity, dismissal persistence, and removal after exit motion.",
         "Use composition=\"slotted\" only when a team intentionally needs to assemble the public lower-level chrome components itself."
       ],
@@ -164,6 +212,8 @@
         "ShellApp automatically resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
         "Desktop and tablet use PanelNav, BarNav, PanelTools through ShellTools, and ShellPage chrome.",
         "Mobile uses MobileSheetNav, MobileBarNav, MobileHeader, ShellTools mobile presentation, and the same routed content owner. MobileBarNav paints its primary surface through the bottom safe-area inset so light browser chrome and application chrome meet without a secondary-surface seam.",
+        "Below 768px the application root owns a 100dvh fixed stage with a 100vh fallback while ShellApp continues to fill its owner with height 100%; JavaScript viewport measurement synchronizes only the chrome wash and does not own layout height.",
+        "With viewport-fit=cover, ShellApp consumes the shared top safe-area inset once and MobileBarNav consumes the persistent bottom inset; nested routed, tool, sheet, and consumer headers do not duplicate either inset.",
         "An optional Banner spans the complete application above desktop navigation, workspace, tools, and mobile global surfaces while remaining below the operating-system top safe area.",
         "Switching breakpoints changes presentation and inert state without recreating route or tool elements.",
         "Messages uses its own mobile destination; Stacks and Activity use explicit mobile Inbox grouping metadata."
@@ -551,7 +601,7 @@
         }
       ],
       "stateOwnership": [
-        "The router owns heading copy, selected section, depth, available actions, content inset, content surface, route data, and product outcomes.",
+        "The router owns heading copy, selected section, depth, available actions, content inset, divider visibility, scroll-compaction policy, content surface, route data, and product outcomes.",
         "The application replaces pageChrome from completed route state and handles ShellApp page intent events.",
         "ShellApp owns ShellPage, BarTitle, MobileHeader, the content scroller, sticky presentation, and responsive switching.",
         "The default slot contains application-owned routed content and is not recreated for header compaction or breakpoint changes.",
@@ -567,6 +617,7 @@
         "ShellApp derives the desktop BarTitle and mobile MobileHeader from the same pageChrome object.",
         "Route-level sections remain pageChrome tabs; subordinate local views use subsections.",
         "Use contentInset none only for deliberately full-bleed products such as maps and canvases.",
+        "Table pages can retain responsive inline and bottom gutters while tuning their roomy and compact block-start seams; set scrollCompaction false when their roomy title must stay pinned, and let shell capacity continue to compact it for tools or tablet layouts.",
         "Choose contentSurface independently: primary and secondary canvases both support default responsive gutters or full-bleed content.",
         "Desktop and tablet BarTitle presentations match a secondary page canvas across expanded, compact, and constrained variants; the separate mobile header remains primary.",
         "ShellPage keeps its scroll-compaction spacer on the selected content surface so the routed canvas remains continuous.",