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

package/dist/files/styles/_conversation-widget-container.scss

@@ -0,0 +1,6 @@
+// Shared layout contract for widgets in the conversation and standalone captures.
+// Widgets use this name for container queries and this width for cqw units.
+@mixin conversation-widget-container {
+  container-type: inline-size;
+  container-name: chatPane;
+}

package/dist/files/styles/_media.scss

@@ -0,0 +1,50 @@
+// The chat's media conditions: a compile-time breakpoint table and the `media()` mixin the chat rules
+// call. Same table as the app's `src/styles/partials/_breakpoints.scss` and the same output as the `include-media`
+// library the app's `src/styles/_media-mixins.scss` pulls in for the forms the chat writes: `>=name`, `>name`, `<=name`,
+// `<name`, several conditions joined with `and`. `>` adds 1px, `<` subtracts 1px. The package's other rules use the
+// table in `_breakpoints.scss` (another set of values, kept apart by its own name here).
+@use "sass:list";
+@use "sass:map";
+@use "sass:string";
+
+$agents-chat-breakpoints: (
+  phone: 325px,
+  mobile: 767px,
+  tablet: 1025px,
+  desktop: 1200px,
+  wide: 1440px,
+) !default;
+
+@function agents-media-condition($expression) {
+  $operators: (">=", "<=", ">", "<");
+  @each $operator in $operators {
+    @if string.index($expression, $operator) == 1 {
+      $name: string.unquote(string.slice($expression, string.length($operator) + 1));
+      @if not map.has-key($agents-chat-breakpoints, $name) {
+        @error "agents media(): unknown breakpoint `#{$name}`.";
+      }
+      $width: map.get($agents-chat-breakpoints, $name);
+      @if $operator == ">=" {
+        @return "(min-width: #{$width})";
+      } @else if $operator == ">" {
+        @return "(min-width: #{$width + 1px})";
+      } @else if $operator == "<=" {
+        @return "(max-width: #{$width})";
+      } @else {
+        @return "(max-width: #{$width - 1px})";
+      }
+    }
+  }
+  @error "agents media(): `#{$expression}` is not one of >=name, >name, <=name, <name.";
+}
+
+@mixin media($conditions...) {
+  $query: "";
+  @each $condition in $conditions {
+    $part: agents-media-condition($condition);
+    $query: if($query == "", $part, "#{$query} and #{$part}");
+  }
+  @media #{string.unquote($query)} {
+    @content;
+  }
+}

package/dist/files/styles/_spacings.scss

@@ -0,0 +1,23 @@
+// Package spacing constants: compile-time values with arithmetic, not themable custom properties.
+// Same values as the app's `src/styles/_spacings.scss`, so the package compiles to the same CSS inside the app.
+$x0: 0;
+$x1: 0.5rem;
+$x0_125: 0.125 * $x1;
+$x0_25: 0.25 * $x1;
+$x0_5: 0.5 * $x1;
+$x1_5: 1.5 * $x1;
+$x1_75: 1.75 * $x1;
+$x2: 2 * $x1;
+$x2_5: 2.5 * $x1;
+$x3: 3 * $x1;
+$x4: 4 * $x1;
+$x5: 5 * $x1;
+$x6: 6 * $x1;
+$x7: 7 * $x1;
+$x8: 8 * $x1;
+$x9: 9 * $x1;
+
+// The older pixel names three package rules still read.
+$pico: 1px;
+$nano: 2px;
+$byte: 8px;

package/dist/files/styles/_surfaces.scss

@@ -0,0 +1,28 @@
+// Package surface constants: the card paddings, radii and shadows, same values as the app's
+// `src/styles/_surfaces.scss`. The colours inside the shadows stay custom properties (`--agents-shadow-rgb`).
+@import "spacings";
+
+// The radius of media flush inside a card (the button radius of the app's theme, 4px).
+$button-radius: $x0_5;
+
+// One card padding and one compact padding (small nested tiles, rows).
+$card-padding: $x2;
+$card-padding-compact: $x1;
+
+// Card 16px, compact tile 12px.
+$card-radius: $x2;
+$card-radius-compact: $x1_5;
+
+// A card whose corner hugs a rounded inset (a thumbnail tile at the compact padding) = inset radius + padding = 20px.
+$card-radius-around-thumbnail: $card-radius-compact + $card-padding-compact;
+
+// The card shadow: top-level chat cards sit elevated; nested tiles and canvas-internal cards stay flat.
+$card-shadow:
+  0 $x0_25 $x0_25 rgba(var(--agents-shadow-rgb), 0.08),
+  0 $x0_5 $x1 rgba(var(--agents-shadow-rgb), 0.05),
+  0 $x1 $x3 rgba(var(--agents-shadow-rgb), 0.03);
+
+// Muted icon buttons floating over a photo or card edge: a soft halo that keeps them legible on light and dark media.
+$floating-button-shadow:
+  0 0 $x0_5 0 rgba(var(--agents-shadow-rgb), 0.08),
+  0 0 $x2 $x0_5 rgba(var(--agents-shadow-rgb), 0.05);

package/dist/files/widgets/ClockConversationWidget/ClockConversationWidget.md

@@ -0,0 +1,53 @@
+---
+name: Clock
+emitter: agent
+summary: Live clock of one place, or a world clock of several, from the IANA time zones the agent passes. Digital and analog time, city label, date, UTC offset, a day/night hint and the difference to the owner's time; ticks in the browser, no network.
+description: Shows the current time of one place, or a world clock of up to eight places, from the IANA time zone ids the agent passes (with a city label each). Every clock shows the time as a large digital value and an analog dial with a second hand, the place with its zone abbreviation, whether it is today, yesterday or tomorrow there together with the hour difference to the owner's own time zone (the location's zone, else the browser's), the date, the UTC offset and a sun or moon for day or night. The time ticks client-side from the browser's time-zone data — nothing is fetched. A zone id the browser does not know is dropped and reported. In a report e-mail the clocks show the time of the capture with an "As of" line. Inline only, read-only.
+---
+
+# ClockConversationWidget
+
+## Description
+The current time somewhere else, the way a world clock app shows it: per place a large digital time, an analog dial,
+the place with its zone abbreviation, "Today / Yesterday / Tomorrow" with the hour difference to the owner's time, the
+date, the UTC offset and a sun or moon for day or night. One place renders one clock; several places render one widget
+with one row per place (a world clock). The time ticks every second in the browser from its own time-zone data
+(`Intl`), so the widget needs no tool and fetches nothing; daylight-saving changes come with the browser's data.
+
+The owner's own time zone is the location's time zone (derived from the address), else the browser's. A zone id the
+browser does not know is dropped and reported to the model (render report `failed`, code `INVALID_PROP`, naming the
+dropped ids); the other clocks still render. No valid zone at all renders one muted line and reports `failed` too; an
+empty `clocks` list reports `empty`. In a report e-mail the clocks are frozen at the capture time and an "As of …" line
+says when that was.
+
+## Data structure — DATA-COMPLETE (zone ids and labels only)
+```ts
+interface ClockPayload {
+  title?: string;                  // optional headline in the owner's language — "Your team's time zones"
+  timeFormat?: "24h" | "12h";      // OMIT → the location's preference
+  clocks: {
+    timeZone: string;              // an IANA time zone id: "Europe/Berlin", "America/New_York", "Asia/Tokyo"
+    label?: string;                // the place in the owner's language — "Münster, Germany"; OMIT → the city of the id
+    abbreviation?: string;         // OMIT → the browser's short zone name ("CET", "EDT")
+  }[];                             // 1 to 8 clocks, in the order to show
+}
+```
+Accepted aliases (weak models rename fields): `zones` / `timeZones` for `clocks`; `tz`, `tz_name`, `zone`, `timezone`
+for `timeZone`; `city`, `location`, `name` for `label`; `tz_alias` for `abbreviation`; `time_format` for `timeFormat`;
+a clock written as a plain zone id string; one clock written at the top level (`{"timeZone": …, "label": …}`).
+
+Single clock:
+```widget
+{ "type": "Clock", "clocks": [ { "timeZone": "Europe/Berlin", "label": "Münster, Deutschland" } ] }
+```
+World clock:
+```widget
+{ "type": "Clock", "title": "Berlin, New York, Tokio", "clocks": [ { "timeZone": "Europe/Berlin", "label": "Berlin, Deutschland" }, { "timeZone": "America/New_York", "label": "New York, NY, USA" }, { "timeZone": "Asia/Tokyo", "label": "Tokio, Japan" } ] }
+```
+
+## When to use
+- When the owner asks what time it is somewhere ("Wie spät ist es in Tokio?"), or how far ahead or behind a place is: one clock with the place's IANA time zone and its name as `label`.
+- When the answer compares the time of several places (a team, customers or suppliers abroad, a call across time zones): ONE Clock widget with one entry per place, never one widget per place.
+- Write a SHORT one-line prose intro FIRST that already states the time or the difference ("In Tokio ist es jetzt 10:58, acht Stunden später als bei dir:"), then the widget on its own line — a widget-only turn renders blank.
+- Pass real IANA ids only (`Asia/Tokyo`, not `JST` or `GMT+9`); never invent a time — the widget computes it.
+- Not for a historical time, a date calculation, a countdown or finding a meeting slot in a calendar — answer those in prose.

package/dist/files/widgets/ClockConversationWidget/clock.preview-fixtures.json

@@ -0,0 +1,76 @@
+{
+  "wireName": "Clock",
+  "fixtures": [
+    {
+      "name": "default",
+      "description": "One clock — the time in Münster for an owner in Berlin (ChatGPT ClockWidget, ref 36): digital and analog time, place with zone abbreviation, today with +0 h.",
+      "payload": { "clocks": [{ "timeZone": "Europe/Berlin", "label": "Münster, Deutschland" }] },
+      "settings": { "location": { "location": { "timezone": "Europe/Berlin" } } },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "world-clock",
+      "description": "The world clock of ref 37 — Berlin, New York, Tokio for an owner in Berlin: one row per place, yesterday / today with the hour difference.",
+      "payload": {
+        "title": "Berlin, New York, Tokio",
+        "clocks": [
+          { "timeZone": "Europe/Berlin", "label": "Berlin, Deutschland" },
+          { "timeZone": "America/New_York", "label": "New York, NY, USA" },
+          { "timeZone": "Asia/Tokyo", "label": "Tokio, Japan" }
+        ]
+      },
+      "settings": { "location": { "location": { "timezone": "Europe/Berlin" } } },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "world-clock-12h",
+      "description": "The same world clock in 12-hour format for an English-speaking owner in New York, ChatGPT's own field names (tz_name, location) as a weak model would copy them.",
+      "payload": {
+        "time_format": "12h",
+        "zones": [
+          { "tz_name": "America/New_York", "location": "New York, NY, USA", "tz_alias": "EDT" },
+          { "tz_name": "Asia/Kolkata", "location": "Bengaluru, India" },
+          { "tz_name": "Australia/Sydney", "location": "Sydney, Australia" }
+        ]
+      },
+      "settings": { "location": { "location": { "timezone": "America/New_York" } } },
+      "locale": "en",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "unknown-zone",
+      "description": "One valid and one unknown zone id: the unknown one is dropped and reported (failed INVALID_PROP), the valid clock still renders.",
+      "payload": {
+        "clocks": [
+          { "timeZone": "Asia/Tokyo", "label": "Tokio, Japan" },
+          { "timeZone": "JST", "label": "Osaka" }
+        ]
+      },
+      "settings": { "location": { "location": { "timezone": "Europe/Berlin" } } },
+      "locale": "de",
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "all-unknown",
+      "description": "Only unknown zone ids: one muted line, reported failed.",
+      "payload": { "clocks": [{ "timeZone": "Mars/Olympus_Mons", "label": "Olympus Mons" }] },
+      "locale": "de",
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "empty",
+      "description": "A block without any clock: one muted line, reported empty.",
+      "payload": { "clocks": [] },
+      "locale": "de",
+      "expectedState": "empty",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/ConceptExplainerConversationWidget/ConceptExplainerConversationWidget.md

@@ -0,0 +1,86 @@
+---
+name: ConceptExplainer
+emitter: agent
+summary: Interactive explainer of how something works for the business — a slider over states, a picture and a caption per state. Types — rankingFactors (Seo), reviewImpact (Reputation). DATA-COMPLETE (the type id plus a few figures).
+description: Explains a mechanism instead of showing data, the way ChatGPT's LearningViz explains moon phases — one card with a picture of the current state, the state's name and one or two sentences under it, a slider over the states with labelled step buttons, variant pills where the type has them, and a footer naming the source and whether the picture carries the business's own figures or is an illustration. Each explainer TYPE lives in the domain that owns its content and registers itself by file. rankingFactors (Seo) shows how relevance, distance and prominence move a business in Google's local results, without any number. reviewImpact (Reputation) shows how new reviews of a chosen rating move the average star rating — exact arithmetic from the average and review count the block carries, or an illustration without figures. Inline, read-only (the controls change only the picture).
+---
+
+# ConceptExplainerConversationWidget
+
+## Description
+An interactive explanation (ChatGPT's LearningViz is the interaction model — not the
+content). One elevated card: the title and a sub-line, the type's picture of the current state on a flat tile, the
+state's name and what changes in it, the variant pills (where the type has variants), the slider over the states with
+the current state's label and one button per state, and a footer with the source and a line that says whether the
+figures are computed from the block or the picture is an illustration.
+
+The widget is a frame; each explainer TYPE is one file in its domain, found by folder glob:
+
+| Type (`explainer`) | Domain | Shows | Values |
+|---|---|---|---|
+| `rankingFactors` | Seo (`widgets/seo/RankingFactorsConceptExplainer/`) | Google's three local ranking factors — relevance, distance, prominence — as signal meters, and a small illustrated list of local results in which the business's row moves as its profile, reviews and website get stronger, and drops when the searcher is further away. No number, no position, no weight: Google publishes none. | `businessName` (optional, labels the business's own row) |
+| `reviewImpact` | Reputation (`widgets/reputation/ReviewImpactConceptExplainer/`) | The average star rating today and after 1, 3, 5, 10 or 25 new reviews of 5, 4, 3 or 1 star, on a 1–5 scale; with the business's figures also how many more reviews of the picked rating lift the shown average to the next tenth. | `currentAverage` (1–5) and `reviewCount` (whole number) — both or neither |
+
+The slider and the pills change only the picture (local state), so they stay usable on a replay. In a report e-mail the
+card shows one representative state (`rankingFactors`: the website step, `reviewImpact`: five new reviews) without
+controls. Every figure `reviewImpact` shows is arithmetic: the mean of all ratings, rounded to one decimal as the
+platforms show it; the footer says that the exact value behind a shown average can differ by up to 0.05.
+
+Render report: no `explainer` → `empty` (`NO_DATA`), one muted line; an unknown type → `failed`
+(`INVALID_PROP`, the detail names the known types), one muted line; a value outside its range (an average of 7) or one
+figure without the other → `failed` (`INVALID_PROP`, the detail names the dropped values) while the illustration still
+renders.
+
+## Data structure — DATA-COMPLETE
+```ts
+interface ConceptExplainerPayload {
+  explainer: "rankingFactors" | "reviewImpact"; // the type id; case, "_" and "-" are ignored
+  title?: string;        // the headline in the owner's language (at most 160 characters); OMIT → the type's own title
+  values?: {             // only the figures the type reads — copied from a read of THIS conversation, never estimated
+    businessName?: string;    // rankingFactors
+    currentAverage?: number;  // reviewImpact: the average rating, 1–5
+    reviewCount?: number;     // reviewImpact: the number of reviews behind it
+  };
+  step?: string | number; // the state to start at (a step id such as "reviews", or its index); OMIT → the first
+}
+```
+Accepted aliases (weak models rename fields): `type_id`, `typeId`, `explainerType`, `concept` for `explainer` (also
+inside `values`, as ChatGPT writes `{"parameters": {"type_id": …}}`); `parameters`, `params`, `data` for `values`;
+`averageRating`, `average`, `rating` for `currentAverage`; `reviewsCount`, `numberOfReviews`, `totalReviews`, `count` for
+`reviewCount`; `initialStep` for `step`.
+
+How Google's local ranking works:
+```widget
+{"type": "ConceptExplainer", "explainer": "rankingFactors", "values": {"businessName": "Bäckerei Krume"}}
+```
+How new reviews move this business's rating (the figures from the reputation read):
+```widget
+{"type": "ConceptExplainer", "explainer": "reviewImpact", "values": {"currentAverage": 4.2, "reviewCount": 37}}
+```
+
+## When to use
+- When the owner asks how or why something works rather than what their numbers are — what moves their position in Google's local results, why a competitor ranks above them, how much new reviews change their star average: write a SHORT one-line answer FIRST, then this widget with the matching `explainer` on its own line (a widget-only turn renders blank).
+- `rankingFactors` for how Google's local ranking works (relevance, distance, prominence); pass only `values.businessName`, the widget shows no number.
+- `reviewImpact` for how new reviews move the average rating; pass `values.currentAverage` and `values.reviewCount` exactly as a reputation read of this conversation returned them, otherwise omit `values` and the widget shows an illustration — never estimate the figures.
+- Not for the business's current figures or lists (use the domain's widget), not as a forecast of a position or a rating, and not when the owner only wants advice — answer that in prose.
+
+## ASCII layout
+```
+How new reviews move your rating
+Your average rating is the mean of all reviews: each new review moves it a little
+┌────────────────────────────────────────────────────────┐
+│ ┌ Today ─────────┐   ┌ After 5 new reviews ─┐          │
+│ │ 4.2  ★★★★☆     │   │ 4.3  ★★★★☆           │ (ringed) │
+│ └────────────────┘   └──────────────────────┘          │
+│ ├────┼────┼────┼──●─●┤   1★ 2★ 3★ 4★ 5★                │
+│ 3 more 5-star reviews lift the shown average to 4.3    │
+└────────────────────────────────────────────────────────┘
+               After 5 new reviews: 4.3
+ With 5 more 5-star reviews your average moves from 4.2 to 4.3.
+Rating of the new reviews   (5 stars) (4 stars) (3 stars) (1 star)
+New reviews                                              +5
+●━━━━━━━━━━━━━━━━━○─────────────────────────────────────
+(Today) (+1) (+3) (+5) (+10) (+25)
+As Google and most review platforms show it: the mean of all ratings, rounded to one decimal
+Computed from the average and the number of reviews in this answer; …
+```

package/dist/files/widgets/ConceptExplainerConversationWidget/concept-explainer.preview-fixtures.json

@@ -0,0 +1,23 @@
+{
+  "wireName": "ConceptExplainer",
+  "fixtures": [
+    {
+      "name": "unknown-type",
+      "description": "A type id no explainer type registers (ChatGPT's MOON_PHASES): one muted line, reported failed INVALID_PROP with the known types.",
+      "payload": {
+        "explainer": "MOON_PHASES"
+      },
+      "locale": "en",
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "empty",
+      "description": "A block that names no explainer: one muted line, reported empty.",
+      "payload": {},
+      "locale": "en",
+      "expectedState": "empty",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/ConversationSearchResultsConversationWidget/ConversationSearchResultsConversationWidget.md

@@ -0,0 +1,59 @@
+---
+name: ConversationSearchResults
+emitter: agent
+canvas: conversationSearchResults
+summary: Grouped cross-conversation recall results from `searchConversations`. DATA-COMPLETE; ≤5 groups inline, more → canvas.
+description: Renders the result of searchConversations (cross-chat semantic recall) — matches grouped by conversation (title · date · matched message excerpts with the query bolded), each with an arrow to jump to that chat. Few groups inline, many in the canvas side panel.
+---
+
+# ConversationSearchResultsConversationWidget
+
+## Description
+Shows the matches from `searchConversations` grouped by conversation — reuses the same `AgentSearchResults` view the chat's own search panel uses. Each group is a card: conversation title (or "Untitled chat") · relative date, then its matched message rows (You / the agent + excerpt, query terms highlighted), with an arrow to open that conversation. Few groups render inline; many open in the canvas side panel.
+
+## Data structure — DATA-COMPLETE (no re-fetch)
+**Unlike a self-hydrating widget, this widget does NOT fetch anything.** It renders entirely from the payload. The agent copies the `query` and the grouped results from the `searchConversations` tool output straight into the payload — the search is never re-run.
+```ts
+interface ConversationSearchResultsPayload {
+  query: string;                       // the search query, used to highlight matched terms
+  title?: string;                      // short LLM headline (user's language) shown on the collapsed canvas card; falls back to the query
+  display?: "inline" | "canvas";       // OPTIONAL — normally OMIT; the widget auto-picks inline (few) vs canvas (many)
+  groups: {
+    conversationId?: number;           // the source chat (the open-arrow target)
+    title?: string;                    // the chat's title
+    summary?: string;                  // the chat's summary recap (shown under the title)
+    dateTime?: string;                 // "Y-m-d H:i:s" of the most-recent matched message
+    hits: { role?: string; excerpt?: string; dateTime?: string; indexInConversation?: number; messageId?: number }[];
+  }[];                                 // dateTime per hit = that message's timestamp (shown on the row)
+}
+```
+Just copy the `groups` from the `searchConversations` result verbatim (title · summary · dateTime · hits with their per-message dateTime are all in it). Concrete payload example:
+```json
+{
+  "query": "facebook",
+  "groups": [
+    { "conversationId": 1841, "title": "Create Facebook Post", "summary": "Drafted a first Facebook post for the shop.", "dateTime": "2026-06-20 14:03:11",
+      "hits": [ { "role": "user", "excerpt": "connect fb", "dateTime": "2026-06-20 14:01:00" }, { "role": "user", "excerpt": "ok, create a post for fb", "dateTime": "2026-06-20 14:03:11" } ] },
+    { "conversationId": 1799, "title": "Open Connections", "dateTime": "2026-06-18 09:21:00",
+      "hits": [ { "role": "user", "excerpt": "in connections is facebook connected?", "dateTime": "2026-06-18 09:21:00" } ] }
+  ]
+}
+```
+
+## When to use
+- After calling `searchConversations` — render the matches as this widget instead of re-listing them in prose.
+- Few matches → they render inline; many → they open in the canvas side panel automatically (or set `display`).
+- Skip for a single in-conversation recall (`recallConversation`) — that's the current chat, answer inline in prose.
+
+## ASCII layout (inline / canvas)
+```
+┌──────────────────────────────────────────────┐
+│ Create Facebook Post                       →  │   ← group: title · date · open arrow
+│   You   connect ⟦fb⟧                          │
+│   You   ok, create a post for ⟦fb⟧            │
+├──────────────────────────────────────────────┤
+│ Open Connections                           →  │
+│   You   in connections is ⟦facebook⟧ connected?│
+└──────────────────────────────────────────────┘
+   (⟦…⟧ = query terms highlighted; → jumps to that chat)
+```

package/dist/files/widgets/ConversationSearchResultsConversationWidget/conversation-search-results.preview-fixtures.json

@@ -0,0 +1,85 @@
+{
+  "wireName": "ConversationSearchResults",
+  "fixtures": [
+    {
+      "name": "render-report-empty",
+      "description": "No group with a readable hit reports empty NO_DATA.",
+      "payload": {
+        "query": "opening hours",
+        "groups": []
+      },
+      "expectedState": "empty",
+      "width": 528
+    },
+    {
+      "name": "default",
+      "description": "The owner asked \"Was hatten wir zu den Prophylaxe-Wochen besprochen?\": three earlier chats of the practice match and render inline.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "query": "Prophylaxe-Wochen",
+        "title": "Frühere Chats zur Prophylaxe",
+        "groups": [
+          {
+            "conversationId": 84102,
+            "title": "Prophylaxe-Wochen im November planen",
+            "summary": "Ablauf und Posts für die Prophylaxe-Aktion im November abgestimmt.",
+            "created": "2026-10-24 16:05:00",
+            "updated": "2026-10-24 16:05:00",
+            "hits": [
+              {
+                "role": "USER",
+                "excerpt": "Wir wollen im November Prophylaxe-Wochen machen mit einem Aktionsangebot für die professionelle Zahnreinigung. Kannst du dazu Posts für Instagram und Facebook planen?",
+                "messageId": 912301,
+                "indexInConversation": 0,
+                "created": "2026-10-24 15:48:00"
+              },
+              {
+                "role": "ASSISTANT",
+                "excerpt": "Gern: drei Posts – Ankündigung am 29. Oktober, eine Erinnerung zur Monatsmitte und ein Team-Post mit ZFA Miriam zur professionellen Zahnreinigung.",
+                "messageId": 912305,
+                "indexInConversation": 2,
+                "created": "2026-10-24 15:52:00"
+              }
+            ]
+          },
+          {
+            "conversationId": 83560,
+            "title": "Antwort auf die 2-Sterne-Bewertung",
+            "summary": "Antwort auf die Bewertung zur Wartezeit nach der Prophylaxe-Sitzung formuliert.",
+            "created": "2026-10-12 10:31:00",
+            "updated": "2026-10-12 10:31:00",
+            "hits": [
+              {
+                "role": "USER",
+                "excerpt": "Die neue 2-Sterne-Bewertung beschwert sich über 40 Minuten Wartezeit bei der Prophylaxe. Wie antworten wir am besten?",
+                "messageId": 905118,
+                "indexInConversation": 0,
+                "created": "2026-10-12 10:20:00"
+              }
+            ]
+          },
+          {
+            "conversationId": 82944,
+            "title": "Leistungsseite Prophylaxe überarbeiten",
+            "summary": "Texte der Website-Seite Prophylaxe und die Keyword-Auswahl besprochen.",
+            "created": "2026-09-30 14:02:00",
+            "updated": "2026-09-30 14:02:00",
+            "hits": [
+              {
+                "role": "ASSISTANT",
+                "excerpt": "Für \"professionelle zahnreinigung kassel\" steht die Praxis seit Wochen auf Position 9 – ein eigener Abschnitt zu Ablauf und Kosten der Prophylaxe auf der Seite kann helfen.",
+                "messageId": 899407,
+                "indexInConversation": 4,
+                "created": "2026-09-30 13:55:00"
+              }
+            ]
+          }
+        ]
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/CurrencyConverterConversationWidget/CurrencyConverterConversationWidget.md

@@ -0,0 +1,51 @@
+---
+name: CurrencyConverter
+emitter: agent
+summary: Currency converter — an amount in one currency, its value in another, the exchange rate and the date the rate is of; the owner edits the amount and swaps the currencies, recomputed from the delivered rate. DATA-COMPLETE.
+description: Renders a currency conversion from the rate `getCurrencyExchangeRate` returned — the amount in the first currency (an editable field), its value in the second, "1 EUR = 1.12023 USD" and a chip "Rate of <day>". The owner may type another amount and swap the two currencies; both are recomputed in the browser from the delivered rate, nothing is fetched or written. Our rates are dated (one per day, cached up to a month), so the widget never says "live".
+---
+
+# CurrencyConverterConversationWidget
+
+## Description
+A currency conversion (after ChatGPT's `CurrencyConverterWidgetWithSource`). The title "Currency converter" sits above one elevated card with two rows: the first currency
+(round flag badge, ISO code, the currency's name in the UI language) with the amount in an editable soft field and its
+symbol on the right, a round swap button on the hairline between the rows, the second currency with the converted value
+big and bold on the right. A footer line carries "1 EUR = 1.12023 USD" and "Rate of <day>". The two currencies are the
+delivered pair only — there is no currency picker; swap turns the pair round and inverts the rate. The amount is
+typed and shown grouped in the owner's language (`1,250,000` / `1.250.000`). In the e-mail capture the amount is plain
+text and the swap button is gone.
+
+## Data structure — DATA-COMPLETE (no re-fetch)
+The tool `getCurrencyExchangeRate` (`CurrencyConversionMCPPackage`) dictates the filled block in its result; the model
+copies it. The parser accepts the aliases `from`/`from_currency`/`baseCurrency`, `to`/`to_currency`/`targetCurrency`,
+`exchangeRate`, `rate_date`/`date`; a block without both codes and a positive rate renders nothing and reports `failed`.
+```ts
+interface CurrencyConverterPayload {
+  fromCurrency: string; // ISO 4217 (EUR)
+  toCurrency: string;   // ISO 4217 (USD)
+  amount?: number;      // in fromCurrency, default 1
+  rate: number;         // 1 fromCurrency = rate toCurrency
+  rateDate?: string;    // Y-m-d, the day the rate is of
+}
+```
+Concrete payload example:
+```json
+{ "fromCurrency": "EUR", "toCurrency": "USD", "amount": 100, "rate": 1.12023, "rateDate": "2026-10-25" }
+```
+
+## When to use
+- After `getCurrencyExchangeRate` on a screen, whenever the answer is a conversion between two currencies (a price, an invoice, a budget in another currency). Copy the block the tool result dictates — the rate and its date exactly as returned, never a rate from memory. Write a SHORT one-line intro with the converted amount FIRST, then the widget on its own line. Not for a rate history over time, not on a phone call.
+
+## ASCII layout
+```
+Currency converter
+┌──────────────────────────────────────────────────────────┐
+│ (🇪🇺) EUR                              [ 100 ] €         │
+│      Euro                                                │
+│ ───────────────────── (⇅) ─────────────────────────────  │
+│ (🇺🇸) USD                                  112,02 $       │
+│      US-Dollar                                           │
+│ 1 EUR = 1,12023 USD  ·  Rate of 25.10.2026               │
+└──────────────────────────────────────────────────────────┘
+```

package/dist/files/widgets/CurrencyConverterConversationWidget/currency-converter.preview-fixtures.json

@@ -0,0 +1,73 @@
+{
+  "wireName": "CurrencyConverter",
+  "fixtures": [
+    {
+      "name": "default",
+      "description": "100 GBP to USD at the rate of 25 October 2026 — the approved design's reference conversion; the amount is edited and the currencies swapped.",
+      "payload": {
+        "fromCurrency": "GBP",
+        "toCurrency": "USD",
+        "amount": 100,
+        "rate": 1.31842,
+        "rateDate": "2026-10-25"
+      },
+      "locale": "en",
+      "expectedState": "data",
+      "width": 528,
+      "interactions": [
+        {
+          "name": "edit-amount",
+          "fill": {
+            "selector": "[data-testid='currency-converter-amount'] input",
+            "value": "250"
+          }
+        },
+        {
+          "name": "swap",
+          "click": {
+            "selector": "[data-testid='currency-converter-swap']"
+          }
+        }
+      ]
+    },
+    {
+      "name": "english-large-amount",
+      "description": "A large GBP amount in JPY (a currency without decimals), in English formatting, to check grouping and the fit of a long hero number.",
+      "payload": {
+        "fromCurrency": "GBP",
+        "toCurrency": "JPY",
+        "amount": 1250000,
+        "rate": 201.3846,
+        "rateDate": "2026-09-30"
+      },
+      "locale": "en",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "german",
+      "description": "The reference conversion in German: currency names, grouping and decimal marks and the date follow the UI language.",
+      "payload": {
+        "fromCurrency": "GBP",
+        "toCurrency": "USD",
+        "amount": 100,
+        "rate": 1.31842,
+        "rateDate": "2026-10-25"
+      },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "invalid",
+      "description": "A block without a rate: the widget renders nothing and reports failed (INVALID_PROP).",
+      "payload": {
+        "fromCurrency": "GBP",
+        "toCurrency": "USD",
+        "amount": 100
+      },
+      "expectedState": "error",
+      "width": 528
+    }
+  ]
+}