@mgamadeus/ddd-agents 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/files/widgets/MultiChoiceConversationWidget/MultiChoiceConversationWidget.md

@@ -0,0 +1,61 @@
+---
+name: MultiChoice
+emitter: none
+status: Not implemented — nothing emits it yet; analysis of whether implementing it is worthwhile pending, possibly useful
+summary: Generic multi-select picker with "Select all" and "Confirm N selections".
+description: Generic multi-select picker. Renders a labelled list of options with checkboxes plus a "Select all" toggle and a "Confirm N selections" button. Emits a follow-up chat message with the chosen labels.
+---
+
+# MultiChoiceConversationWidget
+
+## Description
+Generic, payload-driven multi-select directive. Used wherever the assistant needs the user to pick one or more items from a finite list and confirm — e.g. business attributes, opening-hour days, GBP service flags, social-channel picks.
+
+Visual: heading (optional title + subtitle), then a vertical stack of clickable rows each carrying a label, optional sublabel and a checkbox. A footer holds "Select all" / "Clear all" + a primary "Confirm {count} selections" button. Once confirmed the directive locks (no further toggling) and emits the configured chat message.
+
+## Data structure
+JSON payload:
+```ts
+{
+  title?: string,
+  subtitle?: string,
+  options: Array<{
+    label: string,           // visible label
+    sublabel?: string,       // small caption under the label
+    value: string,           // unique id, used in confirm action
+    selected?: boolean,      // pre-checked when true
+  }>,
+  selectAllLabel?: string,           // default: "Select all"
+  confirmLabelTemplate?: string,     // default: "Confirm {count} selection" (one key, plural via its MANY value:
+                                     // "Confirm 1 selection" / "Confirm 2 selections") — {count} is replaced; a custom
+                                     // template has no plural form, so word it count-neutral ("Selected: {count}")
+  confirmAction?: string,            // default: "Confirmed: {values}" — {values}/{count} replaced before send
+}
+```
+
+Markdown shape:
+```md
+::MultiChoice{payload='{"title":"…","options":[{"label":"…","value":"…"}]}'}
+```
+
+## When to use
+- User needs to pick one or more items from a known, finite set and explicitly confirm.
+- Skip for single-pick prompts (use a single-select directive) and for free-text answers.
+- Skip when each pick should fire its own action immediately — `MultiChoiceConversationWidget` defers until confirm.
+
+## ASCII layout (inline)
+```
+Title (optional)
+Subtitle (optional)
+
+┌────────────────────────────────────────────┐
+│ Label A                              [✓]   │
+│ Currently not added                        │
+└────────────────────────────────────────────┘
+┌────────────────────────────────────────────┐
+│ Label B                              [ ]   │
+└────────────────────────────────────────────┘
+…
+
+[ Select all ]   [ Confirm N selections ]
+```

package/dist/files/widgets/MultiChoiceConversationWidget/multi-choice-widget-contract.json

@@ -0,0 +1,43 @@
+{
+  "wireName": "MultiChoice",
+  "description": "The owner's answer on the multi-choice widget of an owner question. The confirm posts confirmAction as the owner's TEXT (sendMessageToChat): '{values}' becomes the picked options' labels in option order joined by ', ', '{count}' their number (default confirmAction 'Confirmed: {values}'; askOwner writes '{values}'), with the suffix the app declares appended when the widget belongs to another agent space than the active one (its agentSpaceId; the package default appends none, anotherAgentSpaceSuffixTemplate is empty). The backend reader is MultiChoiceConversationWidget (OwnerQuestionConversationWidget::readAnswer() / readPickFromFirstOwnerText()): the app's suffix is stripped when it names the widget's own agent space, the whole text is matched against one label first (a label may carry ', '), and only then split at ', ' with every part a label. Any owner text answers the widget; a text that matches no way is an answer without labels — so is a confirm under the default 'Confirmed: ' prefix today. The widget has no decline control. A stored contract: the confirm wording never changes without the readers accepting both.",
+  "anotherAgentSpaceSuffixTemplate": "",
+  "exampleBlocks": [
+    "```widget\n{\"type\":\"MultiChoice\",\"question\":\"Which channels should we post on?\",\"options\":[{\"label\":\"Instagram\",\"value\":\"Instagram\"},{\"label\":\"Facebook\",\"value\":\"Facebook\",\"sublabel\":\"Your page with 1,200 followers\"},{\"label\":\"TikTok\",\"value\":\"TikTok\"}],\"confirmAction\":\"{values}\",\"emittedBy\":\"tool:askOwner\"}\n```",
+    "```widget\n{\"type\":\"MultiChoice\",\"agentSpaceId\":412553,\"title\":\"What do you sell?\",\"options\":[{\"label\":\"Bread, rolls and cakes\",\"value\":\"bakery\"},{\"label\":\"Coffee\",\"value\":\"coffee\"}],\"confirmAction\":\"{values}\"}\n```"
+  ],
+  "exampleReactions": [
+    {
+      "exampleBlock": 0,
+      "messageType": "TEXT",
+      "confirmedValues": ["Instagram", "TikTok"],
+      "clickedOnWidgetOfAnotherAgentSpace": false,
+      "text": "Instagram, TikTok",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": ["Instagram", "TikTok"],
+      "expectedMeanings": []
+    },
+    {
+      "exampleBlock": 1,
+      "messageType": "TEXT",
+      "confirmedValues": ["bakery"],
+      "clickedOnWidgetOfAnotherAgentSpace": true,
+      "text": "Bread, rolls and cakes",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": ["Bread, rolls and cakes"],
+      "expectedMeanings": [],
+      "expectedAnotherAgentSpaceKey": 412553
+    },
+    {
+      "exampleBlock": 0,
+      "messageType": "TEXT",
+      "text": "Only Instagram for now, maybe TikTok later",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": [],
+      "expectedMeanings": []
+    }
+  ]
+}

package/dist/files/widgets/MultiChoiceConversationWidget/multi-choice.preview-fixtures.json

@@ -0,0 +1,103 @@
+{
+  "wireName": "MultiChoice",
+  "fixtures": [
+    {
+      "name": "default",
+      "description": "Choice pills with a confirm — the reservation time pills of the ChatGPT reference.",
+      "payload": {
+        "question": "Which channels should we post on?",
+        "options": [
+          {
+            "label": "Instagram",
+            "value": "Instagram"
+          },
+          {
+            "label": "Facebook",
+            "value": "Facebook",
+            "sublabel": "Your page with 1,200 followers"
+          },
+          {
+            "label": "TikTok",
+            "value": "TikTok"
+          }
+        ],
+        "confirmAction": "{values}"
+      },
+      "expectedState": "data",
+      "width": 528,
+      "interactions": [
+        {
+          "name": "pick Instagram",
+          "click": {
+            "text": "Instagram"
+          }
+        },
+        {
+          "name": "pick Facebook",
+          "click": {
+            "text": "Facebook"
+          }
+        }
+      ]
+    },
+    {
+      "name": "render-report-error",
+      "description": "A payload without an options list reports failed INVALID_PROP.",
+      "payload": {
+        "question": "Which channels?"
+      },
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "kassel-dental-services",
+      "description": "Which services the November posts of the practice should feature — several may be picked, the confirm sends them.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "question": "Welche Leistungen sollen die November-Posts zeigen?",
+        "options": [
+          {
+            "label": "Prophylaxe / professionelle Zahnreinigung",
+            "value": "Prophylaxe",
+            "sublabel": "Passt zu den Prophylaxe-Wochen"
+          },
+          {
+            "label": "Implantologie",
+            "value": "Implantologie"
+          },
+          {
+            "label": "Bleaching",
+            "value": "Bleaching"
+          },
+          {
+            "label": "Kinderzahnheilkunde",
+            "value": "Kinderzahnheilkunde"
+          },
+          {
+            "label": "Angstpatienten-Behandlung",
+            "value": "Angstpatienten-Behandlung"
+          }
+        ],
+        "confirmAction": "{values}"
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528,
+      "interactions": [
+        {
+          "name": "pick Prophylaxe",
+          "click": {
+            "text": "Prophylaxe / professionelle Zahnreinigung"
+          }
+        },
+        {
+          "name": "pick Bleaching",
+          "click": {
+            "text": "Bleaching"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/files/widgets/QuickRepliesConversationWidget/QuickRepliesConversationWidget.md

@@ -0,0 +1,65 @@
+---
+name: QuickReplies
+emitter: agent
+summary: Short answer pills under a closed question — one click sends that option's text as the owner's message.
+description: The pill answers to a closed question (a backend hard rule) — two to five SHORT options in the owner's language, each a complete answer the owner could also type. A click posts the option's text as the owner's own message; the card locks once the send is confirmed, and goes inert once a newer owner message exists (the conversation moved past the question).
+---
+
+# QuickRepliesConversationWidget
+
+## Description
+The agent asks a CLOSED question in prose, then offers the answers as pills instead of leaving the owner to type one. Renders a row of short buttons under the question; a click sends that button's exact text as the owner's chat message — a shortcut for typing the same words, never a separate action channel.
+
+Single pick only (compare `MultiChoiceConversationWidget`, which defers to an explicit multi-select confirm). Locks after the click is confirmed sent; a rejected send (closed conversation, an in-flight start) leaves the pills clickable again. Once a NEWER owner message exists in the conversation — the owner typed past it, or answered a later question — the card goes inert (rendered disabled) so a stale pick can never answer the wrong question.
+
+Every option MUST be a complete answer the owner could send verbatim — never a template with a blank (e.g. "Yes, we deliver to these areas: …"). The widget enforces this as a backstop: an option containing an ellipsis (`…`/`...`), a bracketed or underscore blank (`[...]`, `[…]`, `___`), or ending in a colon is a "placeholder option" — clicking it never sends; instead the stripped text is placed in the composer (with a trailing space) and focused, so the owner types the missing part themselves.
+
+## Data structure
+JSON payload:
+```ts
+{
+  options: string[], // 2 to 5 entries, each trimmed, non-empty, unique case-insensitively
+}
+```
+
+Validation (an invalid payload renders nothing):
+- `options` must be an array.
+- 2 to 5 entries.
+- Each entry a non-empty string after trimming.
+- No two entries equal case-insensitively (not silently deduplicated — a payload that violates this is dropped).
+- An entry longer than 60 characters is shown truncated with an ellipsis; the click still sends the FULL text.
+
+Markdown shape (the fence form):
+```widget
+{ "type": "QuickReplies", "options": ["Ja, veröffentlichen", "Jetzt nicht"] }
+```
+
+## When to use
+- Right under a closed (yes/no/either-or) question, so the owner can answer with one click instead of typing.
+- Each option must be a short, complete answer the owner could also type verbatim — not a label for a longer action.
+- Skip for an open-ended question (free text is the only sensible answer) and for multi-select (`MultiChoiceConversationWidget`).
+
+## ASCII layout (inline)
+```
+Möchtest du die Änderungen jetzt veröffentlichen?
+
+   [ Ja, veröffentlichen ]   [ Jetzt nicht ]
+```
+
+After a confirmed click, every pill disables and the chosen one stays highlighted:
+```
+Möchtest du die Änderungen jetzt veröffentlichen?
+
+   [ Ja, veröffentlichen ]■  [ Jetzt nicht ]   (■ = chosen, both disabled)
+```
+
+
+## Platform-written widgets (`askOwner`)
+
+The backend's `askOwner` meta-tool renders the model's own closed question as a QuickReplies tool widget under the
+final text. Its fence carries extra flat fields the widget ignores and the platform reads back: `question` (the
+model's question text), `questionKey` (a catalogue key such as `serveModel`, `draftApproval`), `optionMeanings`
+(one catalogue meaning per option, same order) and `descriptions` (one optional explanation per option, `null`
+where none). The click still posts the option label as the owner's message — that label is the platform's read-back
+key. A multi-select question renders as `MultiChoice` with `confirmAction: "{values}"` (the picked labels joined by
+", ").

package/dist/files/widgets/QuickRepliesConversationWidget/quick-replies-widget-contract.json

@@ -0,0 +1,43 @@
+{
+  "wireName": "QuickReplies",
+  "description": "The owner's answer on the single-choice pills of an owner question. A click posts the option's label as the owner's TEXT (sendMessageToChat), with the suffix the app declares appended when the widget belongs to another agent space than the active one (its agentSpaceId; the package default appends none, anotherAgentSpaceSuffixTemplate is empty). A placeholder option (an ellipsis, a bracketed or underscore blank, a trailing colon) never posts: it fills the composer instead. The backend reader is QuickRepliesConversationWidget (OwnerQuestionConversationWidget::readAnswer() / readPickFromFirstOwnerText()): the app's suffix is stripped when it names the widget's own agent space, then the whole text is matched against the labels (case-insensitive, trailing ' .!' ignored). Any owner text answers the widget; a text that matches no label is an answer without labels. The pills have no decline control. A stored contract: the click wording never changes without the readers accepting both.",
+  "anotherAgentSpaceSuffixTemplate": "",
+  "exampleBlocks": [
+    "```widget\n{\"type\":\"QuickReplies\",\"question\":\"Wie erreichen dich deine Kunden?\",\"options\":[\"Kunden kommen zu uns\",\"Wir fahren zu den Kunden\",\"Beides\"],\"questionKey\":\"serveModel\",\"optionMeanings\":[\"walkIn\",\"mobile\",\"hybrid\"],\"emittedBy\":\"tool:askOwner\"}\n```",
+    "```widget\n{\"type\":\"QuickReplies\",\"agentSpaceId\":412553,\"options\":[\"Yes, publish it\",\"Not yet\"]}\n```"
+  ],
+  "exampleReactions": [
+    {
+      "exampleBlock": 0,
+      "messageType": "TEXT",
+      "clickedOption": "Wir fahren zu den Kunden",
+      "clickedOnWidgetOfAnotherAgentSpace": false,
+      "text": "Wir fahren zu den Kunden",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": ["Wir fahren zu den Kunden"],
+      "expectedMeanings": ["mobile"]
+    },
+    {
+      "exampleBlock": 0,
+      "messageType": "TEXT",
+      "text": "Beides, aber hauptsächlich fahren wir raus",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": [],
+      "expectedMeanings": []
+    },
+    {
+      "exampleBlock": 1,
+      "messageType": "TEXT",
+      "clickedOption": "Yes, publish it",
+      "clickedOnWidgetOfAnotherAgentSpace": true,
+      "text": "Yes, publish it",
+      "expectsAnswer": true,
+      "expectsDecline": false,
+      "expectedLabels": ["Yes, publish it"],
+      "expectedMeanings": [],
+      "expectedAnotherAgentSpaceKey": 412553
+    }
+  ]
+}

package/dist/files/widgets/QuickRepliesConversationWidget/quick-replies.preview-fixtures.json

@@ -0,0 +1,45 @@
+{
+  "wireName": "QuickReplies",
+  "fixtures": [
+    {
+      "name": "default",
+      "description": "An owner question with three answer pills — the follow-up suggestions of the ChatGPT reference as one tap each.",
+      "payload": {
+        "question": "What should we look at next?",
+        "options": ["Compare with last month", "Show the top keywords", "Which competitor grew most?"]
+      },
+      "expectedState": "data",
+      "width": 528,
+      "interactions": [{ "name": "pick the second answer", "click": { "text": "Show the top keywords" } }]
+    },
+    {
+      "name": "render-report-error",
+      "description": "Two options that differ only by case drop the card, reported failed INVALID_PROP.",
+      "payload": {
+        "options": [
+          "Yes",
+          "yes"
+        ]
+      },
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "kassel-dental-next-step",
+      "description": "After the review summary the assistant asks the practice owner what to look at next — three answer pills the model wrote.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "question": "Womit sollen wir weitermachen?",
+        "options": [
+          "Auf die 2-Sterne-Bewertung antworten",
+          "Bewertungen mit Dentalzentrum Kassel-West vergleichen",
+          "Bewertungsanfragen an Prophylaxe-Patienten senden"
+        ]
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/SuggestedActions/SuggestedActions.md

@@ -0,0 +1,60 @@
+---
+name: SuggestedActions
+emitter: frontend
+summary: Quick-reply pill buttons under an AI message; click sends a predefined prompt.
+description: Inline row of muted pill buttons rendered under an AI message. Each pill is a quick-reply — clicking it sends the predefined `userAction` text back into the chat as if the user typed it. Lightweight quick-reply pattern; no icons, no descriptions, no flags.
+---
+
+# SuggestedActions
+
+## Description
+Quick-reply pills shown under an assistant turn. Parses `options` (JSON array of `{displayText, userAction}`), renders muted component-library `Button`s in a single horizontal flex row. Click → `sendMessageToChat(userAction)` → the chat behaves as if the user typed `userAction`. Returns `null` on parse / shape failure (warns to console).
+
+Visual contract:
+- Single horizontal row, compact muted buttons.
+- `displayText` is the **short** label the user sees on the pill (verb-led, ~1–4 words).
+- `userAction` is the **full** message that gets injected into the chat on click — phrase it as something a real user would naturally type, can be a complete sentence.
+- No icons, no subtitles, no recommended / destructive variants.
+
+## Data structure
+Single prop `options` — a non-empty array of `{displayText, userAction}` objects.
+```ts
+interface SuggestedActionsProps {
+  options: {
+    displayText: string;  // required, short pill label (~1–4 words, verb-led)
+    userAction: string;   // required, full user message sent to chat on click
+  }[];                    // required, non-empty
+}
+```
+The renderer JSON-stringifies prop objects automatically, so mock / backend authors supply a plain array — no double-encoding needed.
+
+Concrete `options` value:
+```json
+[
+  { "displayText": "Reply now",   "userAction": "Help me reply to my recent reviews" },
+  { "displayText": "Draft it",    "userAction": "Draft a weekend promo post for Google" },
+  { "displayText": "Skip for now","userAction": "Skip these for now" }
+]
+```
+
+Markdown shape:
+```md
+::SuggestedActions{options='[{"displayText":"Reply now","userAction":"Help me reply to my recent reviews"}]'}
+```
+
+## When to use
+- AI ends a turn with 2–6 obvious conversational follow-ups the user is likely to tap instead of typing.
+- Each option must be **a message the user would say**, not an action that opens a UI / mounts a widget / triggers a side effect.
+- `displayText` reads like a chat-reply chip ("Show me how", "Draft it for me", "Not now").
+- `userAction` reads like a complete user turn — specific enough that the assistant can act on it without follow-up clarification.
+- Options that would need descriptions, titles, icons or a recommended flag are written as prose — there is no card-stack widget.
+- Skip when an option must open a canvas, mount a widget, or run a side effect → pick the matching dedicated widget.
+- Skip when there is exactly one obvious next step — just ask the user directly.
+
+## ASCII layout (inline)
+```
+... AI message text above ...
+
+[ Reply now ]  [ Draft it ]  [ Add photos ]  [ Sync hours ]  [ Skip for now ]
+   muted          muted          muted           muted            muted
+```

package/dist/files/widgets/SuggestedActions/suggested-actions.preview-fixtures.json

@@ -0,0 +1,19 @@
+{
+  "wireName": "SuggestedActions",
+  "fixtures": [
+    {
+      "name": "render-report-error",
+      "description": "A fence carries no options attribute, so the widget reports failed INVALID_PROP and renders nothing.",
+      "payload": {
+        "options": [
+          {
+            "displayText": "Yes",
+            "userAction": "Yes"
+          }
+        ]
+      },
+      "expectedState": "error",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/ToolTraceConversationWidget/ToolTraceConversationWidget.md

@@ -0,0 +1,48 @@
+---
+name: ToolTrace
+emitter: frontend
+summary: Collapsible trace of the tool calls behind an answer (debug/transparency).
+description: Muted, italic single-line trace of a `tool_use` assistant part (e.g. `→ Opened Example Tasks`). Payload-only, renders on both live delivery and history replay, and never executes the tool.
+---
+
+# ToolTraceConversationWidget
+
+## Description
+
+Renders a muted single-line label for a `tool_use` part so the user can see which tool
+the agent invoked, without re-running it. Renders identically on live delivery and on
+history replay — it is purely presentational.
+
+## Payload
+
+```json
+{
+  "name": "Navigate",
+  "input": { "destination": "APP.NAV.EXAMPLE.TASKS" }
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | no | Tool name. Falls back to `"Tool"` when missing/non-string. |
+| `input` | object | no | Tool input. Only read when `name === "Navigate"`. |
+
+## Label resolution
+
+- `name === "Navigate"` **and** `input.destination` is a non-empty string → the last
+  dot-segment of the destination is humanized: `APP.NAV.EXAMPLE.TASKS` → `Example Tasks`.
+- Otherwise → the raw `name` (or `"Tool"`).
+
+Output is `→ Opened <label>`.
+
+## States
+
+- Non-JSON / non-object payload, or unresolvable label → renders nothing (`null`).
+
+## Layout
+
+```
+→ Opened Example Tasks
+```
+
+Single inline `<span>`, 12px, italic, subtle text color.

package/dist/files/widgets/ToolTraceConversationWidget/tool-trace.preview-fixtures.json

@@ -0,0 +1,32 @@
+{
+  "wireName": "ToolTrace",
+  "fixtures": [
+    {
+      "name": "render-report-mounted",
+      "description": "A readable trace mounts (a fence always carries an object, so the unreadable path is spec-only).",
+      "payload": {
+        "name": "Navigate",
+        "input": {
+          "destination": "APP.NAV.EXAMPLE.TASKS"
+        }
+      },
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "default",
+      "description": "The muted trace line of a navigation the assistant made for the practice owner: it opened the reviews page of the app.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "name": "Navigate",
+        "input": {
+          "destination": "APP.NAV.EXAMPLE.REVIEWS"
+        }
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/WebSearchResultsConversationWidget/WebSearchResultsConversationWidget.md

@@ -0,0 +1,49 @@
+---
+name: WebSearchResults
+emitter: agent
+canvas: webSearchResults
+summary: References of the agent's own web research answer — the pages it used as link chips with site icons, placed under its prose answer. DATA-COMPLETE.
+description: Renders the references of a web research answer the agent wrote itself — one link chip per page it used (the site's favicon and name, the page title on hover). The agent writes the answer as prose ABOVE the widget; the widget carries only `query` and `sources`. Legacy messages with an `answer` field render the former answer card.
+---
+
+# WebSearchResultsConversationWidget
+
+## Description
+The references of a web research answer. The agent writes its answer as prose in the message and puts this
+widget on its own line UNDER it, carrying the pages it actually used. Each page renders as a link chip: the site's
+favicon, the site name, the full page title on hover; a click opens the page in a new tab.
+
+## Data structure — DATA-COMPLETE (no re-fetch)
+**This widget does NOT fetch anything.** It renders entirely from the payload. The `sources` are copied character for
+character from the `searchTheWeb` / `extractInformationFromWebPagesWithFastLLM` tool results.
+```ts
+interface WebSearchResultsPayload {
+  query: string;                       // what was researched
+  provider?: string;                   // PERPLEXITY
+  sources: { url: string; title?: string }[];  // the pages the answer used, in order
+  // legacy (older stored messages): title, display, answer — a payload with `answer` renders the answer card
+}
+```
+Concrete payload example:
+```json
+{
+  "query": "BMW iX M60 vs iX M70 chassis and acceleration",
+  "provider": "PERPLEXITY",
+  "sources": [
+    { "url": "https://www.press.bmwgroup.com/deutschland/article/detail/T0447680DE/der-neue-bmw-ix", "title": "Der neue BMW iX" },
+    { "url": "https://fastestlaps.com/models/bmw-ix-m60", "title": "BMW iX M60 specs, 0-60, quarter mile" }
+  ]
+}
+```
+
+## When to use
+- After a web research answer on a screen: the answer as prose first, then this widget on its own line with the pages
+  the answer used. Never the answer inside the widget, never a page the tools did not return.
+
+## ASCII layout
+```
+<the agent's answer, prose, tables>
+
+Sources
+ (🌐 press.bmwgroup.com) (🌐 fastestlaps.com) (🌐 autobild.de)
+```

package/dist/files/widgets/WebSearchResultsConversationWidget/web-search-results.preview-fixtures.json

@@ -0,0 +1,57 @@
+{
+  "wireName": "WebSearchResults",
+  "fixtures": [
+    {
+      "name": "default",
+      "description": "The sources of a web research answer — the source cards of the ChatGPT news feed reference.",
+      "payload": {
+        "query": "Münster bakery opening hours on public holidays",
+        "provider": "PERPLEXITY",
+        "sources": [
+          { "url": "https://www.muenster.de/feiertage.html", "title": "Feiertage in Münster" },
+          { "url": "https://www.ihk.de/nordwestfalen/ladenoeffnung", "title": "Ladenöffnung an Feiertagen" },
+          { "url": "https://www.bäckerhandwerk.de/oeffnungszeiten", "title": "Öffnungszeiten im Bäckerhandwerk" }
+        ]
+      },
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "render-report-empty",
+      "description": "No answer and no source with a url reports empty NO_DATA.",
+      "payload": {
+        "query": "opening hours",
+        "sources": []
+      },
+      "expectedState": "empty",
+      "width": 528
+    },
+    {
+      "name": "kassel-dental-emergency-service",
+      "description": "The owner asked how the dental emergency service in Kassel is organised at weekends (for the practice's Notfallsprechstunde page); the widget carries the three pages the answer used.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "query": "zahnärztlicher Notdienst Kassel Wochenende",
+        "provider": "PERPLEXITY",
+        "sources": [
+          {
+            "url": "https://www.lzkh.de/patienten/zahnaerztlicher-notdienst",
+            "title": "Zahnärztlicher Notdienst in Hessen – Landeszahnärztekammer Hessen"
+          },
+          {
+            "url": "https://www.kzvh.de/patienten/notdienst",
+            "title": "Notdienstsuche – Kassenzahnärztliche Vereinigung Hessen"
+          },
+          {
+            "url": "https://www.kassel.de/buerger/gesundheit/notdienste.php",
+            "title": "Notdienste und Bereitschaftsdienste – Stadt Kassel"
+          }
+        ]
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    }
+  ]
+}