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

package/dist/files/widgets/CustomVisualizationConversationWidget/CustomVisualizationConversationWidget.md

@@ -0,0 +1,83 @@
+---
+name: CustomVisualization
+emitter: agent
+summary: A visualization the model programs itself — its own HTML, CSS and JavaScript with the data in the block, run in a sandboxed frame. ONLY for what no ComposedView node can express (a canvas animation, a custom projection, a simulation).
+description: Runs the block's `html`, `css` and `script` in an iframe with `sandbox="allow-scripts"` (an opaque origin — no cookies, no storage, no access to the chat) under the policy `default-src 'none'` (no network: no fetch, no external image, script or font). The data travels in the block (`data`, read by the script as `window.AGENTS_VISUALIZATION.data`); libraries come only from the allow-list (`d3`). The frame tells the chat its height (clamped 80–1200 px) and beats every second; a frame that stops beating (an endless loop) or never gets ready is removed. In the e-mail it renders as a static preview without the frame.
+---
+
+# CustomVisualizationConversationWidget
+
+## Description
+ChatGPT's custom visualization (`AppBlock`) in our design: one elevated
+card with the model's title and caption, and under it the model's own visualization in a sandboxed frame — a canvas
+animation with sliders, a drag-to-rotate projection, a small simulation. The chat's colours are handed to the frame as
+CSS custom properties (`--agents-fg`, `--agents-fg-light`, `--agents-bg`, `--agents-bg-var`, `--agents-accent`, `--agents-divider`,
+`--agents-font-family`) and `window.AGENTS_VISUALIZATION.colorScheme` (`light` | `dark`), so a visualization can follow the
+theme.
+An app whose stored scripts read other names declares them once (`AgentsEnvironment.sandboxLegacyAliases`:
+`visualizationGlobalNames`, `themeVariablePrefixes`); the frame then defines the same frozen global under each declared
+name and sets every theme variable under each declared prefix as well. Without a declaration only the names above exist.
+
+What the sandbox allows and forbids:
+- the iframe carries `sandbox="allow-scripts"` only — never `allow-same-origin`, `allow-top-navigation`,
+  `allow-popups` or `allow-forms`;
+- the frame page's policy: `default-src 'none'; script-src <the frame's own bootstrap by hash> blob:;
+  style-src 'unsafe-inline'; img-src data: blob:; font-src data:; form-action 'none'; base-uri 'none'` — the block's
+  script and the allow-listed libraries run as `blob:` scripts the bootstrap creates; nothing loads from a URL;
+- inline event attributes (`onclick="…"`) do not run — use `addEventListener` in the script;
+- an image is a `data:` URL or drawn by the script; a `fetch`, an external image or font is blocked and reported;
+- honest limit: a script can still navigate its own frame (and so put data into a URL). The frame holds only the
+  block's own data, which the customer already sees, and no credentials.
+
+## Data structure — DATA-COMPLETE
+```ts
+interface CustomVisualizationPayload {
+  title?: string;        // the card title (the owner's language); not repeated inside the html
+  description?: string;  // one caption line under the title
+  html: string;          // the markup inside the frame's root (no <script> — it would not run)
+  css?: string;          // the styles; the frame's body is transparent, the visualization paints its own background
+  script?: string;       // the JavaScript; reads window.AGENTS_VISUALIZATION.data; html or script is required
+  libraries?: string[];  // from the allow-list only: "d3" (v7.6.1, global `d3`)
+  data?: unknown;        // any JSON the script draws — every value with its source in the prose
+  height?: number;       // the frame's height until it reports its own (80–1200, default 360)
+}
+```
+At most 65,536 bytes of `html` + `css` + `script` + the JSON of `data` (UTF-8); a larger block is not run. A block
+with neither `html` nor `script`, or with a library outside the allow-list, is not run either.
+
+Concrete payload example:
+```widget
+{"type": "CustomVisualization", "title": "Solar System Explorer", "description": "Interactive 3D projection · illustrative scales", "html": "<canvas id=\"orbits\"></canvas><input id=\"speed\" type=\"range\" min=\"0\" max=\"3\" step=\"0.1\" value=\"1\">", "css": "canvas{display:block;width:100%;aspect-ratio:16/10;background:#0b1020}", "script": "var bodies = window.AGENTS_VISUALIZATION.data.bodies; /* draw the orbits on the canvas, animate with requestAnimationFrame */", "data": {"bodies": [{"name": "Earth", "orbitRadius": 94, "size": 6.5, "color": "#4c9dff", "speed": 1}]}, "height": 420}
+```
+
+## When to use
+- Only when no ComposedView node can express the picture: an animation on a canvas, a custom projection or a small simulation the owner explores with sliders or the mouse. A table, a chart, KPI tiles, a map, a list or a form are ComposedView nodes, never this widget. One short line first, then the widget; the prose carries the key statement, because a visualization that fails to load shows nothing. Never for live data the script would fetch (it cannot), never for demo numbers in a customer answer.
+
+## States
+- loading: a skeleton in the frame's shape until the script ran, reported `pending`;
+- ready: the frame at the height it reports, reported `mounted`;
+- a block that is not run (no content, too large, a library outside the allow-list): one muted line, reported `failed`
+  (`INVALID_PROP` / `BUDGET_EXCEEDED`);
+- a script error: what rendered stays, one muted line under it, reported `failed` (`RENDER_FAILED` with the error line);
+- a frame that stops beating for 5 s (an endless loop) or is not ready after 15 s: the frame is removed, one muted line,
+  reported `failed` (`RENDER_FAILED`);
+- e-mail: a static preview (title, caption, a tile saying the visualization is interactive) — no frame, no script.
+
+## Where the frame page is served
+`sandbox-frame/custom-visualization-frame.html` is a self-contained static page our build emits
+(`app-build/assets/custom-visualization-frame-<hash>.html`). `shared/custom-visualization-sandbox-config.ts`
+(`frameUrl`) points the widget at a copy of the same file on a host of another registrable domain — then every browser
+with site isolation runs the frame in a process of its own, and an endless loop cannot freeze the chat before the
+watchdog removes the frame.
+
+## ASCII layout
+```
+┌──────────────────────────────────────────────┐
+│ Solar System Explorer                        │
+│ Interactive 3D projection · illustrative …   │
+│ ┌──────────────────────────────────────────┐ │
+│ │      (the model's own canvas, sliders,   │ │
+│ │       buttons — inside the sandbox)      │ │
+│ └──────────────────────────────────────────┘ │
+└──────────────────────────────────────────────┘
+```

package/dist/files/widgets/CustomVisualizationConversationWidget/custom-visualization.preview-fixtures.json

@@ -0,0 +1,227 @@
+{
+  "wireName": "CustomVisualization",
+  "fixtures": [
+    {
+      "name": "solar-system",
+      "description": "The ChatGPT custom visualization (53): the Solar System Explorer — a canvas 3D projection of six planets with speed, tilt and zoom sliders, a pause button and drag-to-rotate, all in the model's own HTML/CSS/JS inside the sandbox frame.",
+      "payload": {
+        "title": "Solar System Explorer",
+        "description": "Interaktive 3D-Projektion · Illustrative Maßstäbe",
+        "html": "<div class=\"explorer\">\n  <span class=\"count-badge\" id=\"count-badge\"></span>\n  <canvas id=\"orbits\" aria-label=\"Planet orbits\"></canvas>\n  <div class=\"controls\">\n    <label>Geschwindigkeit<input id=\"speed\" type=\"range\" min=\"0\" max=\"3\" step=\"0.1\" value=\"1\"></label>\n    <label>Neigung<input id=\"tilt\" type=\"range\" min=\"0\" max=\"80\" step=\"1\" value=\"53\"></label>\n    <label>Zoom<input id=\"zoom\" type=\"range\" min=\"0.5\" max=\"1.6\" step=\"0.05\" value=\"1\"></label>\n    <button id=\"pause\" type=\"button\">Pause</button>\n  </div>\n  <p class=\"hint\">Mit der Maus ziehen: Perspektive drehen · Regler verändern die Animation</p>\n</div>",
+        "css": ".explorer{position:relative;background:#0b1020;border-radius:12px;overflow:hidden;color:#cbd8f2}\n.count-badge{position:absolute;top:12px;right:12px;padding:4px 12px;border-radius:999px;background:rgba(203,216,242,.12);font-size:12px}\ncanvas{display:block;width:100%;aspect-ratio:16/10;cursor:grab}\ncanvas.dragging{cursor:grabbing}\n.controls{display:grid;grid-template-columns:repeat(3,minmax(0,1fr)) auto;gap:12px;align-items:end;padding:12px 16px;background:#121a30}\n.controls label{display:flex;flex-direction:column;gap:6px;font-size:12px;color:#9fb0d0}\n.controls input{width:100%;accent-color:#7ea6ff}\n.controls button{padding:8px 16px;border-radius:8px;border:0;background:#2a3d6b;color:#fff;font:inherit;cursor:pointer}\n.hint{margin:0;padding:8px 16px 12px;font-size:12px;color:#7d8bab;text-align:center;background:#121a30}\n@media (max-width:420px){.controls{grid-template-columns:1fr 1fr}.controls button{grid-column:span 2}}",
+        "script": "var bodies = window.AGENTS_VISUALIZATION.data.bodies;\nvar canvas = document.getElementById(\"orbits\");\nvar context = canvas.getContext(\"2d\");\nvar stars = [];\nfor (var starIndex = 0; starIndex < 140; starIndex++) stars.push({ x: Math.random(), y: Math.random(), size: Math.random() * 1.2 + 0.2 });\ndocument.getElementById(\"count-badge\").textContent = bodies.length + \" Planeten\";\nvar state = { time: 0, yaw: 0.35, tilt: 53 * Math.PI / 180, zoom: 1, speed: 1, running: true, last: 0 };\nvar resize = function () {\n  var ratio = window.devicePixelRatio || 1;\n  canvas.width = canvas.clientWidth * ratio;\n  canvas.height = canvas.clientHeight * ratio;\n  context.setTransform(ratio, 0, 0, ratio, 0, 0);\n};\nvar project = function (x, z) {\n  var width = canvas.clientWidth, height = canvas.clientHeight;\n  var scale = Math.min(width / 520, height / 470) * state.zoom;\n  var xr = x * Math.cos(state.yaw) - z * Math.sin(state.yaw);\n  var zr = x * Math.sin(state.yaw) + z * Math.cos(state.yaw);\n  var yr = -zr * Math.sin(state.tilt);\n  var depth = zr * Math.cos(state.tilt);\n  var perspective = 900 / (900 + depth * 0.45);\n  return { x: width / 2 + xr * scale * perspective, y: height / 2 + yr * scale * perspective, depth: depth, k: perspective * scale };\n};\nvar drawOrbit = function (radius) {\n  context.beginPath();\n  for (var step = 0; step <= 160; step++) {\n    var angle = step / 160 * Math.PI * 2;\n    var point = project(radius * Math.cos(angle), radius * Math.sin(angle));\n    if (step === 0) context.moveTo(point.x, point.y); else context.lineTo(point.x, point.y);\n  }\n  context.strokeStyle = \"rgba(124,152,203,.29)\";\n  context.lineWidth = 1;\n  context.stroke();\n};\nvar drawBody = function (body) {\n  var radius = Math.max(2, body.size * body.point.k);\n  var shade = context.createRadialGradient(body.point.x - radius * 0.4, body.point.y - radius * 0.4, 0.5, body.point.x, body.point.y, radius * 1.3);\n  shade.addColorStop(0, \"#ffffff\");\n  shade.addColorStop(0.23, body.color);\n  shade.addColorStop(1, \"#172239\");\n  context.fillStyle = shade;\n  context.beginPath();\n  context.arc(body.point.x, body.point.y, radius, 0, Math.PI * 2);\n  context.fill();\n  if (body.rings) {\n    context.beginPath();\n    context.ellipse(body.point.x, body.point.y, radius * 1.8, radius * 0.52, -0.28, 0, Math.PI * 2);\n    context.strokeStyle = \"rgba(235,210,160,.75)\";\n    context.lineWidth = 2;\n    context.stroke();\n  }\n  context.font = \"12px system-ui, sans-serif\";\n  context.textAlign = \"center\";\n  context.fillStyle = \"#cbd8f2\";\n  context.fillText(body.name, body.point.x, body.point.y + radius + 15);\n};\nvar draw = function (now) {\n  if (!state.last) state.last = now;\n  if (state.running) state.time += (now - state.last) / 1000 * state.speed;\n  state.last = now;\n  var width = canvas.clientWidth, height = canvas.clientHeight;\n  context.clearRect(0, 0, width, height);\n  stars.forEach(function (star) { context.fillStyle = \"rgba(203,216,242,.5)\"; context.fillRect(star.x * width, star.y * height, star.size, star.size); });\n  bodies.forEach(function (body) { drawOrbit(body.orbitRadius); });\n  var sun = project(0, 0);\n  var glow = context.createRadialGradient(sun.x, sun.y, 2, sun.x, sun.y, 34 * state.zoom);\n  glow.addColorStop(0, \"rgba(255,220,140,1)\");\n  glow.addColorStop(0.35, \"rgba(255,180,80,.55)\");\n  glow.addColorStop(1, \"rgba(255,150,50,0)\");\n  context.fillStyle = glow;\n  context.beginPath();\n  context.arc(sun.x, sun.y, 34 * state.zoom, 0, Math.PI * 2);\n  context.fill();\n  var placed = bodies.map(function (body) {\n    var angle = state.time * body.speed * 0.6 + body.phase;\n    return { name: body.name, size: body.size, color: body.color, rings: body.rings, point: project(body.orbitRadius * Math.cos(angle), body.orbitRadius * Math.sin(angle)) };\n  });\n  placed.sort(function (first, second) { return second.point.depth - first.point.depth; }).forEach(drawBody);\n  window.requestAnimationFrame(draw);\n};\ndocument.getElementById(\"speed\").addEventListener(\"input\", function (event) { state.speed = Number(event.target.value); });\ndocument.getElementById(\"tilt\").addEventListener(\"input\", function (event) { state.tilt = Number(event.target.value) * Math.PI / 180; });\ndocument.getElementById(\"zoom\").addEventListener(\"input\", function (event) { state.zoom = Number(event.target.value); });\nvar pauseButton = document.getElementById(\"pause\");\npauseButton.addEventListener(\"click\", function () { state.running = !state.running; pauseButton.textContent = state.running ? \"Pause\" : \"Weiter\"; });\nvar dragStartX = null;\ncanvas.addEventListener(\"pointerdown\", function (event) { dragStartX = event.clientX; canvas.classList.add(\"dragging\"); canvas.setPointerCapture(event.pointerId); });\ncanvas.addEventListener(\"pointermove\", function (event) { if (dragStartX === null) return; state.yaw += (event.clientX - dragStartX) * 0.01; dragStartX = event.clientX; });\ncanvas.addEventListener(\"pointerup\", function () { dragStartX = null; canvas.classList.remove(\"dragging\"); });\nwindow.addEventListener(\"resize\", resize);\nresize();\nwindow.requestAnimationFrame(draw);",
+        "data": {
+          "bodies": [
+            {
+              "name": "Merkur",
+              "orbitRadius": 42,
+              "size": 3.5,
+              "color": "#aba7a4",
+              "speed": 4.1,
+              "phase": 0.4
+            },
+            {
+              "name": "Venus",
+              "orbitRadius": 66,
+              "size": 5.5,
+              "color": "#e3bc85",
+              "speed": 1.7,
+              "phase": 2.6
+            },
+            {
+              "name": "Erde",
+              "orbitRadius": 94,
+              "size": 6.5,
+              "color": "#4c9dff",
+              "speed": 1,
+              "phase": 2.2
+            },
+            {
+              "name": "Mars",
+              "orbitRadius": 126,
+              "size": 4.5,
+              "color": "#ef7955",
+              "speed": 0.65,
+              "phase": 0.9
+            },
+            {
+              "name": "Jupiter",
+              "orbitRadius": 175,
+              "size": 11,
+              "color": "#d5a87a",
+              "speed": 0.3,
+              "phase": 5.9
+            },
+            {
+              "name": "Saturn",
+              "orbitRadius": 225,
+              "size": 9,
+              "color": "#d5c18e",
+              "speed": 0.17,
+              "phase": 4.4,
+              "rings": true
+            }
+          ]
+        },
+        "height": 420
+      },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528,
+      "interactions": []
+    },
+    {
+      "name": "d3-bars",
+      "description": "An allow-listed library in use: a d3 bar chart drawn by the model's script with the chat's colours (--agents-accent, --agents-fg-light).",
+      "payload": {
+        "title": "Bewertungen pro Monat",
+        "description": "Neue Google-Bewertungen, Mai bis Oktober 2026",
+        "html": "<div id=\"chart\"></div>",
+        "css": "#chart{padding:8px 4px}#chart text{fill:var(--agents-fg-light);font-size:11px}#chart .domain,#chart .tick line{stroke:var(--agents-divider)}",
+        "script": "var rows = window.AGENTS_VISUALIZATION.data.rows;\nvar width = document.getElementById(\"chart\").clientWidth, height = 220, margin = { top: 12, right: 12, bottom: 28, left: 36 };\nvar svg = d3.select(\"#chart\").append(\"svg\").attr(\"width\", width).attr(\"height\", height);\nvar x = d3.scaleBand().domain(rows.map(function (row) { return row.month; })).range([margin.left, width - margin.right]).padding(0.25);\nvar y = d3.scaleLinear().domain([0, d3.max(rows, function (row) { return row.reviews; })]).nice().range([height - margin.bottom, margin.top]);\nsvg.append(\"g\").attr(\"transform\", \"translate(0,\" + (height - margin.bottom) + \")\").call(d3.axisBottom(x));\nsvg.append(\"g\").attr(\"transform\", \"translate(\" + margin.left + \",0)\").call(d3.axisLeft(y).ticks(4));\nsvg.selectAll(\"rect\").data(rows).join(\"rect\").attr(\"x\", function (row) { return x(row.month); }).attr(\"width\", x.bandwidth()).attr(\"y\", function (row) { return y(row.reviews); }).attr(\"height\", function (row) { return y(0) - y(row.reviews); }).attr(\"rx\", 4).style(\"fill\", \"var(--agents-accent)\");\n",
+        "libraries": [
+          "d3"
+        ],
+        "data": {
+          "rows": [
+            {
+              "month": "Mai",
+              "reviews": 12
+            },
+            {
+              "month": "Jun",
+              "reviews": 18
+            },
+            {
+              "month": "Jul",
+              "reviews": 9
+            },
+            {
+              "month": "Aug",
+              "reviews": 22
+            },
+            {
+              "month": "Sep",
+              "reviews": 15
+            },
+            {
+              "month": "Okt",
+              "reviews": 27
+            }
+          ]
+        },
+        "height": 240
+      },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    },
+    {
+      "name": "narrow",
+      "description": "The Solar System Explorer at a narrow chat width: the controls wrap into two columns inside the frame.",
+      "payload": {
+        "title": "Solar System Explorer",
+        "description": "Interaktive 3D-Projektion · Illustrative Maßstäbe",
+        "html": "<div class=\"explorer\">\n  <span class=\"count-badge\" id=\"count-badge\"></span>\n  <canvas id=\"orbits\" aria-label=\"Planet orbits\"></canvas>\n  <div class=\"controls\">\n    <label>Geschwindigkeit<input id=\"speed\" type=\"range\" min=\"0\" max=\"3\" step=\"0.1\" value=\"1\"></label>\n    <label>Neigung<input id=\"tilt\" type=\"range\" min=\"0\" max=\"80\" step=\"1\" value=\"53\"></label>\n    <label>Zoom<input id=\"zoom\" type=\"range\" min=\"0.5\" max=\"1.6\" step=\"0.05\" value=\"1\"></label>\n    <button id=\"pause\" type=\"button\">Pause</button>\n  </div>\n  <p class=\"hint\">Mit der Maus ziehen: Perspektive drehen · Regler verändern die Animation</p>\n</div>",
+        "css": ".explorer{position:relative;background:#0b1020;border-radius:12px;overflow:hidden;color:#cbd8f2}\n.count-badge{position:absolute;top:12px;right:12px;padding:4px 12px;border-radius:999px;background:rgba(203,216,242,.12);font-size:12px}\ncanvas{display:block;width:100%;aspect-ratio:16/10;cursor:grab}\ncanvas.dragging{cursor:grabbing}\n.controls{display:grid;grid-template-columns:repeat(3,minmax(0,1fr)) auto;gap:12px;align-items:end;padding:12px 16px;background:#121a30}\n.controls label{display:flex;flex-direction:column;gap:6px;font-size:12px;color:#9fb0d0}\n.controls input{width:100%;accent-color:#7ea6ff}\n.controls button{padding:8px 16px;border-radius:8px;border:0;background:#2a3d6b;color:#fff;font:inherit;cursor:pointer}\n.hint{margin:0;padding:8px 16px 12px;font-size:12px;color:#7d8bab;text-align:center;background:#121a30}\n@media (max-width:420px){.controls{grid-template-columns:1fr 1fr}.controls button{grid-column:span 2}}",
+        "script": "var bodies = window.AGENTS_VISUALIZATION.data.bodies;\nvar canvas = document.getElementById(\"orbits\");\nvar context = canvas.getContext(\"2d\");\nvar stars = [];\nfor (var starIndex = 0; starIndex < 140; starIndex++) stars.push({ x: Math.random(), y: Math.random(), size: Math.random() * 1.2 + 0.2 });\ndocument.getElementById(\"count-badge\").textContent = bodies.length + \" Planeten\";\nvar state = { time: 0, yaw: 0.35, tilt: 53 * Math.PI / 180, zoom: 1, speed: 1, running: true, last: 0 };\nvar resize = function () {\n  var ratio = window.devicePixelRatio || 1;\n  canvas.width = canvas.clientWidth * ratio;\n  canvas.height = canvas.clientHeight * ratio;\n  context.setTransform(ratio, 0, 0, ratio, 0, 0);\n};\nvar project = function (x, z) {\n  var width = canvas.clientWidth, height = canvas.clientHeight;\n  var scale = Math.min(width / 520, height / 470) * state.zoom;\n  var xr = x * Math.cos(state.yaw) - z * Math.sin(state.yaw);\n  var zr = x * Math.sin(state.yaw) + z * Math.cos(state.yaw);\n  var yr = -zr * Math.sin(state.tilt);\n  var depth = zr * Math.cos(state.tilt);\n  var perspective = 900 / (900 + depth * 0.45);\n  return { x: width / 2 + xr * scale * perspective, y: height / 2 + yr * scale * perspective, depth: depth, k: perspective * scale };\n};\nvar drawOrbit = function (radius) {\n  context.beginPath();\n  for (var step = 0; step <= 160; step++) {\n    var angle = step / 160 * Math.PI * 2;\n    var point = project(radius * Math.cos(angle), radius * Math.sin(angle));\n    if (step === 0) context.moveTo(point.x, point.y); else context.lineTo(point.x, point.y);\n  }\n  context.strokeStyle = \"rgba(124,152,203,.29)\";\n  context.lineWidth = 1;\n  context.stroke();\n};\nvar drawBody = function (body) {\n  var radius = Math.max(2, body.size * body.point.k);\n  var shade = context.createRadialGradient(body.point.x - radius * 0.4, body.point.y - radius * 0.4, 0.5, body.point.x, body.point.y, radius * 1.3);\n  shade.addColorStop(0, \"#ffffff\");\n  shade.addColorStop(0.23, body.color);\n  shade.addColorStop(1, \"#172239\");\n  context.fillStyle = shade;\n  context.beginPath();\n  context.arc(body.point.x, body.point.y, radius, 0, Math.PI * 2);\n  context.fill();\n  if (body.rings) {\n    context.beginPath();\n    context.ellipse(body.point.x, body.point.y, radius * 1.8, radius * 0.52, -0.28, 0, Math.PI * 2);\n    context.strokeStyle = \"rgba(235,210,160,.75)\";\n    context.lineWidth = 2;\n    context.stroke();\n  }\n  context.font = \"12px system-ui, sans-serif\";\n  context.textAlign = \"center\";\n  context.fillStyle = \"#cbd8f2\";\n  context.fillText(body.name, body.point.x, body.point.y + radius + 15);\n};\nvar draw = function (now) {\n  if (!state.last) state.last = now;\n  if (state.running) state.time += (now - state.last) / 1000 * state.speed;\n  state.last = now;\n  var width = canvas.clientWidth, height = canvas.clientHeight;\n  context.clearRect(0, 0, width, height);\n  stars.forEach(function (star) { context.fillStyle = \"rgba(203,216,242,.5)\"; context.fillRect(star.x * width, star.y * height, star.size, star.size); });\n  bodies.forEach(function (body) { drawOrbit(body.orbitRadius); });\n  var sun = project(0, 0);\n  var glow = context.createRadialGradient(sun.x, sun.y, 2, sun.x, sun.y, 34 * state.zoom);\n  glow.addColorStop(0, \"rgba(255,220,140,1)\");\n  glow.addColorStop(0.35, \"rgba(255,180,80,.55)\");\n  glow.addColorStop(1, \"rgba(255,150,50,0)\");\n  context.fillStyle = glow;\n  context.beginPath();\n  context.arc(sun.x, sun.y, 34 * state.zoom, 0, Math.PI * 2);\n  context.fill();\n  var placed = bodies.map(function (body) {\n    var angle = state.time * body.speed * 0.6 + body.phase;\n    return { name: body.name, size: body.size, color: body.color, rings: body.rings, point: project(body.orbitRadius * Math.cos(angle), body.orbitRadius * Math.sin(angle)) };\n  });\n  placed.sort(function (first, second) { return second.point.depth - first.point.depth; }).forEach(drawBody);\n  window.requestAnimationFrame(draw);\n};\ndocument.getElementById(\"speed\").addEventListener(\"input\", function (event) { state.speed = Number(event.target.value); });\ndocument.getElementById(\"tilt\").addEventListener(\"input\", function (event) { state.tilt = Number(event.target.value) * Math.PI / 180; });\ndocument.getElementById(\"zoom\").addEventListener(\"input\", function (event) { state.zoom = Number(event.target.value); });\nvar pauseButton = document.getElementById(\"pause\");\npauseButton.addEventListener(\"click\", function () { state.running = !state.running; pauseButton.textContent = state.running ? \"Pause\" : \"Weiter\"; });\nvar dragStartX = null;\ncanvas.addEventListener(\"pointerdown\", function (event) { dragStartX = event.clientX; canvas.classList.add(\"dragging\"); canvas.setPointerCapture(event.pointerId); });\ncanvas.addEventListener(\"pointermove\", function (event) { if (dragStartX === null) return; state.yaw += (event.clientX - dragStartX) * 0.01; dragStartX = event.clientX; });\ncanvas.addEventListener(\"pointerup\", function () { dragStartX = null; canvas.classList.remove(\"dragging\"); });\nwindow.addEventListener(\"resize\", resize);\nresize();\nwindow.requestAnimationFrame(draw);",
+        "data": {
+          "bodies": [
+            {
+              "name": "Merkur",
+              "orbitRadius": 42,
+              "size": 3.5,
+              "color": "#aba7a4",
+              "speed": 4.1,
+              "phase": 0.4
+            },
+            {
+              "name": "Venus",
+              "orbitRadius": 66,
+              "size": 5.5,
+              "color": "#e3bc85",
+              "speed": 1.7,
+              "phase": 2.6
+            },
+            {
+              "name": "Erde",
+              "orbitRadius": 94,
+              "size": 6.5,
+              "color": "#4c9dff",
+              "speed": 1,
+              "phase": 2.2
+            },
+            {
+              "name": "Mars",
+              "orbitRadius": 126,
+              "size": 4.5,
+              "color": "#ef7955",
+              "speed": 0.65,
+              "phase": 0.9
+            },
+            {
+              "name": "Jupiter",
+              "orbitRadius": 175,
+              "size": 11,
+              "color": "#d5a87a",
+              "speed": 0.3,
+              "phase": 5.9
+            },
+            {
+              "name": "Saturn",
+              "orbitRadius": 225,
+              "size": 9,
+              "color": "#d5c18e",
+              "speed": 0.17,
+              "phase": 4.4,
+              "rings": true
+            }
+          ]
+        },
+        "height": 420
+      },
+      "locale": "de",
+      "expectedState": "data",
+      "width": 340
+    },
+    {
+      "name": "script-error",
+      "description": "The model's script throws: what rendered stays, one muted line under it, the block reports failed RENDER_FAILED with the error line.",
+      "payload": {
+        "title": "Kaputte Visualisierung",
+        "html": "<p>Vor dem Fehler</p>",
+        "css": "p{margin:16px}",
+        "script": "undefinedFunctionCall();"
+      },
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "endless-loop",
+      "description": "The model's script never returns: the heartbeat stops, the watchdog removes the frame after 5 s and the block reports failed.",
+      "payload": {
+        "title": "Endlosschleife",
+        "html": "<p>Rechnet …</p>",
+        "css": "",
+        "script": "while (true) {}"
+      },
+      "expectedState": "error",
+      "width": 528
+    },
+    {
+      "name": "unknown-library",
+      "description": "A library outside the allow-list: the block is not run, one muted line, reported failed INVALID_PROP.",
+      "payload": {
+        "title": "Mit Chart.js",
+        "html": "<canvas id=\"c\"></canvas>",
+        "css": "",
+        "script": "new Chart(document.getElementById('c'), {});",
+        "libraries": [
+          "chart.js"
+        ]
+      },
+      "expectedState": "error",
+      "width": 528
+    }
+  ]
+}

package/dist/files/widgets/CustomVisualizationConversationWidget/sandbox-frame/custom-visualization-frame.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-lM0XGmhGiZMIHljQlTSKPwhJjlniS3+ZlLVcChonUbA=' blob:; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; form-action 'none'; base-uri 'none'">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>Custom visualization</title>
+<style>html,body{margin:0;padding:0;background:transparent;color:var(--agents-fg,#1d1d1f);font-family:var(--agents-font-family,system-ui,sans-serif);font-size:14px;line-height:1.4;overflow-x:hidden}*,*::before,*::after{box-sizing:border-box}#visualization{display:flow-root}</style>
+<script>
+(function () {
+  "use strict";
+  // The sandbox host of the CustomVisualization widget. It runs in an iframe with
+  // sandbox="allow-scripts" (an opaque origin: no cookies, no storage, no parent DOM) under the policy above. It waits
+  // for ONE render message from its parent window, then shows the block's HTML and CSS, loads the allow-listed
+  // libraries and the block's script as blob: scripts (the only scripts the policy admits besides this one), and tells
+  // the parent its height, that it is alive (the heartbeat), when the script ran (ready) and when a script failed. It
+  // acts on nothing but that one message. The script reads window.AGENTS_VISUALIZATION and the theme variables
+  // --agents-*; the render message may name further global names and variable prefixes the app declared (the names its
+  // stored scripts read), and the frame then defines the same global and sets the same variables under those as well.
+  var CHANNEL = "agents-custom-visualization";
+  var GLOBAL_NAME = "AGENTS_VISUALIZATION";
+  var THEME_VARIABLE_PREFIX = "--agents-";
+  var GLOBAL_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  var THEME_VARIABLE_PREFIX_PATTERN = /^--[a-z][a-z0-9-]*-$/;
+  var HEARTBEAT_INTERVAL_MS = 1000;
+  var MAX_ERROR_MESSAGE_LENGTH = 300;
+  var parentWindow = window.parent;
+  var postToParent = parentWindow.postMessage.bind(parentWindow);
+  var instanceToken = null;
+  var lastPostedHeight = -1;
+  var heightMeasureRequested = false;
+
+  var post = function (message) {
+    message.channel = CHANNEL;
+    message.token = instanceToken;
+    postToParent(message, "*");
+  };
+
+  var reportError = function (errorText) {
+    post({ type: "error", message: String(errorText || "Unknown script error").slice(0, MAX_ERROR_MESSAGE_LENGTH) });
+  };
+
+  // The content's own height: the root is a flow root (margins stay inside), and the document's scroll height is no
+  // measure — inside a frame it never drops below the frame's current height.
+  var measureHeight = function () {
+    heightMeasureRequested = false;
+    var visualizationRoot = document.getElementById("visualization");
+    if (!visualizationRoot) return;
+    var contentHeight = Math.ceil(visualizationRoot.getBoundingClientRect().height);
+    if (contentHeight !== lastPostedHeight) {
+      lastPostedHeight = contentHeight;
+      post({ type: "height", height: contentHeight });
+    }
+  };
+
+  var requestHeightMeasure = function () {
+    if (heightMeasureRequested) return;
+    heightMeasureRequested = true;
+    window.requestAnimationFrame(measureHeight);
+  };
+
+  var loadScriptText = function (scriptText) {
+    return new Promise(function (resolve, reject) {
+      var scriptUrl = URL.createObjectURL(new Blob([scriptText], { type: "text/javascript" }));
+      var scriptElement = document.createElement("script");
+      scriptElement.src = scriptUrl;
+      scriptElement.onload = function () {
+        URL.revokeObjectURL(scriptUrl);
+        resolve();
+      };
+      scriptElement.onerror = function () {
+        URL.revokeObjectURL(scriptUrl);
+        reject(new Error("A script could not be loaded in the sandbox."));
+      };
+      document.head.appendChild(scriptElement);
+    });
+  };
+
+  // The variable's name without its prefix (fg-light), or null when it carries none of the accepted prefixes.
+  var readThemeVariableSuffix = function (variableName, themeVariablePrefixes) {
+    var acceptedPrefixes = [THEME_VARIABLE_PREFIX].concat(themeVariablePrefixes);
+    for (var prefixIndex = 0; prefixIndex < acceptedPrefixes.length; prefixIndex++) {
+      var acceptedPrefix = acceptedPrefixes[prefixIndex];
+      var variableSuffix = variableName.slice(acceptedPrefix.length);
+      if (variableName.indexOf(acceptedPrefix) === 0 && /^[a-z-]+$/.test(variableSuffix)) return variableSuffix;
+    }
+    return null;
+  };
+
+  // Every accepted variable is set under the package's prefix and under each declared prefix.
+  var applyThemeVariables = function (themeVariables, themeVariablePrefixes) {
+    if (!themeVariables || typeof themeVariables !== "object") return;
+    Object.keys(themeVariables).forEach(function (variableName) {
+      var variableValue = themeVariables[variableName];
+      var variableSuffix = readThemeVariableSuffix(variableName, themeVariablePrefixes);
+      if (variableSuffix === null || typeof variableValue !== "string") return;
+      [THEME_VARIABLE_PREFIX].concat(themeVariablePrefixes).forEach(function (themeVariablePrefix) {
+        document.documentElement.style.setProperty(themeVariablePrefix + variableSuffix, variableValue);
+      });
+    });
+  };
+
+  var readDeclaredNames = function (declaredNames, namePattern) {
+    if (!Array.isArray(declaredNames)) return [];
+    return declaredNames.filter(function (declaredName) {
+      return typeof declaredName === "string" && namePattern.test(declaredName);
+    });
+  };
+
+  var loadLibrariesThenScript = function (librarySources, visualizationScript, libraryIndex) {
+    if (libraryIndex < librarySources.length) {
+      return loadScriptText(librarySources[libraryIndex]).then(function () {
+        return loadLibrariesThenScript(librarySources, visualizationScript, libraryIndex + 1);
+      });
+    }
+    return visualizationScript ? loadScriptText(visualizationScript) : Promise.resolve();
+  };
+
+  var render = function (renderMessage) {
+    window.addEventListener("error", function (errorEvent) {
+      reportError(errorEvent && errorEvent.message ? errorEvent.message : "Unknown script error");
+    });
+    window.addEventListener("unhandledrejection", function (rejectionEvent) {
+      var rejectionReason = rejectionEvent ? rejectionEvent.reason : null;
+      reportError(rejectionReason && rejectionReason.message ? rejectionReason.message : String(rejectionReason));
+    });
+    document.addEventListener("securitypolicyviolation", function (violationEvent) {
+      reportError("Blocked by the sandbox policy: " + violationEvent.effectiveDirective + " "
+        + String(violationEvent.blockedURI || "").slice(0, 80));
+    });
+    window.setInterval(function () {
+      post({ type: "heartbeat" });
+    }, HEARTBEAT_INTERVAL_MS);
+    post({ type: "heartbeat" });
+
+    var themeVariablePrefixes = readDeclaredNames(renderMessage.themeVariablePrefixes, THEME_VARIABLE_PREFIX_PATTERN);
+    applyThemeVariables(renderMessage.theme, themeVariablePrefixes);
+    document.documentElement.setAttribute("data-color-scheme", renderMessage.colorScheme === "dark" ? "dark" : "light");
+    var styleElement = document.createElement("style");
+    styleElement.textContent = renderMessage.css;
+    document.head.appendChild(styleElement);
+    var visualizationRoot = document.createElement("div");
+    visualizationRoot.id = "visualization";
+    visualizationRoot.innerHTML = renderMessage.html;
+    document.body.appendChild(visualizationRoot);
+
+    var visualization = Object.freeze({
+      data: renderMessage.data,
+      colorScheme: renderMessage.colorScheme === "dark" ? "dark" : "light"
+    });
+    [GLOBAL_NAME].concat(readDeclaredNames(renderMessage.visualizationGlobalNames, GLOBAL_NAME_PATTERN))
+      .forEach(function (globalName) {
+        // A declared name never replaces a property the window already has (location, parent, …).
+        if (!(globalName in window)) window[globalName] = visualization;
+      });
+    if (typeof ResizeObserver === "function") {
+      new ResizeObserver(requestHeightMeasure).observe(visualizationRoot);
+    }
+    requestHeightMeasure();
+
+    loadLibrariesThenScript(renderMessage.librarySources, renderMessage.script, 0).then(function () {
+      requestHeightMeasure();
+      post({ type: "ready" });
+    }, function (loadError) {
+      reportError(loadError.message);
+    });
+  };
+
+  var isRenderMessage = function (message) {
+    return message !== null && typeof message === "object" && message.channel === CHANNEL && message.type === "render"
+      && typeof message.token === "string" && typeof message.html === "string" && typeof message.css === "string"
+      && typeof message.script === "string" && Array.isArray(message.librarySources)
+      && message.librarySources.every(function (librarySource) { return typeof librarySource === "string"; })
+      && (message.visualizationGlobalNames === undefined || Array.isArray(message.visualizationGlobalNames))
+      && (message.themeVariablePrefixes === undefined || Array.isArray(message.themeVariablePrefixes));
+  };
+
+  window.addEventListener("message", function (messageEvent) {
+    if (messageEvent.source !== parentWindow || instanceToken !== null || !isRenderMessage(messageEvent.data)) return;
+    instanceToken = messageEvent.data.token;
+    render(messageEvent.data);
+  });
+})();
+</script>
+</head>
+<body></body>
+</html>

package/dist/files/widgets/EntityMentionConversationWidget/EntityMentionConversationWidget.md

@@ -0,0 +1,55 @@
+---
+name: EntityMention
+emitter: customer
+summary: Composer widget: the entity (a competitor, a review, a keyword) the OWNER asked about from a detail panel's "Ask about this", sent inside their own message and echoed read-only above their prose. Never emitted by the agent. Declares `composerComponent` (`EntityMentionComposerWidget`).
+description: Read-only echo of the entity the owner picked with "Ask about this" in an entity detail panel, rendered above their OWN message prose. The owner's composer writes this fence — the agent never emits it; the backend reads which entity the question is about from it.
+---
+
+# EntityMentionConversationWidget
+
+## Description
+This widget is written by the OWNER's composer, never by the agent (ChatGPT's "Anschlussfrage stellen").
+The `entityDetail` canvas shows one entity (opened by an `EntityLink`, a `Map` point or a button of a `ComposedView`
+tree); its **"Ask about this"** button (`EntityMentionAskButton/`, hook `shared/use-entity-mention-composer.ts`) puts
+the entity into the chat input as an `EntityMention` **composer widget** (`ConversationWidgetContext.composerWidgets`,
+rendered by `EntityMentionComposerWidget` as a chip with a ✕). It sends nothing: the owner writes the question. On send,
+`buildMessageTextWithComposerWidgets` appends one fence per mentioned entity to the message text;
+`ConversationMessageUser` extracts it again (`splitComposerWidgetFencesFromMessageText`) and renders THIS component —
+a read-only card (the entity type's icon, "Asking about", the name) — above the prose, right-aligned.
+
+The backend reads the fence off the owner's own message as `EntityMentionConversationWidget`
+(`app/src/Domain/AI/Entities/Conversations/Widgets/`): `entityType` + `entityId` name the entity
+(`buildEntityReferenceRow()` gives the row the entity type's `EntityReferenceResolver` checks the read rights of);
+`label` is only what the panel showed and identifies nothing. One widget per entity, at most 5 per message (a sixth
+"Ask about this" takes the place of the oldest mention); the same entity twice is one mention.
+
+A payload that names no entity (no valid `entityType` / `entityId`) renders nothing and reports `failed INVALID_PROP`.
+
+## Data structure
+```ts
+interface EntityMentionPayload {
+  entityType: string; // the resolver's ENTITY_TYPE: "competitor" | "review" | "keyword" | …
+  entityId: string; // the id the backend resolved the reference to (a row id or an external id)
+  label?: string; // the entity's name as the panel showed it, at most 120 characters
+  // the key of the entity's agent space, under the block field the app declares
+  // (`AgentsEnvironment.widgetSelfHydrationKeyFieldName`); omitted = the chat's agent space
+}
+```
+
+## Fence example
+```widget
+{"type": "EntityMention", "entityType": "competitor", "entityId": "8812", "label": "Altes Gasthaus Leve"}
+```
+
+## When to use
+Never emitted by the agent — the owner's composer writes it with the detail panel's "Ask about this" button; this doc exists for the registry and the backend reader, not as an authoring instruction.
+
+## ASCII layout
+Right-aligned, above the owner's own message:
+```
+              ┌──────────────────────────┐
+              │ [▤]  Asking about         │
+              │      Altes Gasthaus Leve  │
+              └──────────────────────────┘
+                 Why is their rating better than mine?
+```

package/dist/files/widgets/EntityMentionConversationWidget/entity-mention.preview-fixtures.json

@@ -0,0 +1,55 @@
+{
+  "wireName": "EntityMention",
+  "fixtures": [
+    {
+      "name": "entity-mention-competitor",
+      "description": "The read-only echo above the owner's own message: the competitor the owner put into the composer with the detail panel's \"Ask about this\" (ChatGPT's \"Anschlussfrage stellen\", 21b–21d).",
+      "payload": {
+        "entityType": "competitor",
+        "entityId": "8812",
+        "label": "Dentalzentrum Kassel-West",
+        "agentSpaceId": 1
+      },
+      "expectedState": "data",
+      "width": 528,
+      "dataSet": "kassel-dental-practice"
+    },
+    {
+      "name": "entity-mention-without-label",
+      "description": "A mention whose opener knew no name: the chip says \"About this entry\".",
+      "payload": {
+        "entityType": "review",
+        "entityId": "4711"
+      },
+      "expectedState": "data",
+      "width": 528,
+      "dataSet": "kassel-dental-practice"
+    },
+    {
+      "name": "entity-mention-invalid",
+      "description": "The error state: a fence that names no entity (no entityId) renders nothing and reports failed INVALID_PROP.",
+      "payload": {
+        "entityType": "competitor",
+        "label": "Dentalzentrum Kassel-West"
+      },
+      "expectedState": "error",
+      "width": 528,
+      "dataSet": "kassel-dental-practice"
+    },
+    {
+      "name": "default",
+      "description": "The owner opened the chat from the competitor list and asks about Dentalzentrum Kassel-West (Friedrich-Ebert-Straße 140, 4.7 ★ from 154 reviews): the chip above their message names it.",
+      "dataSet": "kassel-dental-practice",
+      "payload": {
+        "entityType": "competitor",
+        "entityId": "5124",
+        "label": "Dentalzentrum Kassel-West",
+        "agentSpaceId": 7
+      },
+      "agentSpaceId": 7,
+      "locale": "de",
+      "expectedState": "data",
+      "width": 528
+    }
+  ]
+}