From b80e22ec2dfdb9789c69ce9b30a29b18cb38d5a8 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Mon, 7 Sep 2026 10:55:54 -0700
Subject: [PATCH] docs(visualizer): require self-contained widget sources

---
 docs/tool-catalog.i18n.yaml                                   | 4 ++--
 docs/tool-catalog.md                                          | 2 +-
 docs/tool-catalog.zh.md                                       | 2 +-
 packages/visualizer/tool-visualizer/src/tools.ts              | 2 +-
 .../tests/__snapshots__/model-surface.spec.ts.snap            | 2 +-
 .../visualizer/tool-visualizer/tests/model-surface.spec.ts    | 4 +++-
 snapshots/web/visualizer-host/tool-schemas.expected.json      | 2 +-
 7 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index c7488b81a1..ccac9eac35 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-catalog.md
-tool-catalog.md: ac1b84c279247990f22728995684f8d4ca6e5254
-tool-catalog.zh.md: 42071bbbf65fb0fb1ace66e8b1858a834a4b5e12
+tool-catalog.md: 731d7b0c45d2e2834848fbb2e27440e5ac8a7401
+tool-catalog.zh.md: b976a15113cb2272f2e51c8a688abcb34131be68
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index ac1b84c279..731d7b0c45 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -2097,7 +2097,7 @@ Render one temporary inline graphic or interactive widget from conversation cont
     },
     "widget_code": {
       "type": "string",
-      "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. External resources are blocked; inline everything."
+      "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. Keep the widget self-contained: include all required styles, scripts, data, and assets in the source."
     }
   },
   "required": [
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 42071bbbf6..b976a15113 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -2104,7 +2104,7 @@ todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为
     },
     "widget_code": {
       "type": "string",
-      "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. External resources are blocked; inline everything."
+      "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. Keep the widget self-contained: include all required styles, scripts, data, and assets in the source."
     }
   },
   "required": [
diff --git a/packages/visualizer/tool-visualizer/src/tools.ts b/packages/visualizer/tool-visualizer/src/tools.ts
index a2aab21c03..2b217f4c44 100644
--- a/packages/visualizer/tool-visualizer/src/tools.ts
+++ b/packages/visualizer/tool-visualizer/src/tools.ts
@@ -49,7 +49,7 @@ export function registerVisualizerTools(
   ctx: Context,
   limits: { readonly maxTitleBytes: number; readonly maxWidgetBytes: number },
 ): void {
-  const sourceDescription = 'For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. External resources are blocked; inline everything.'
+  const sourceDescription = 'For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. Keep the widget self-contained: include all required styles, scripts, data, and assets in the source.'
 
   ctx.tools.register(defineTool({
     name: 'widget_guidelines',
diff --git a/packages/visualizer/tool-visualizer/tests/__snapshots__/model-surface.spec.ts.snap b/packages/visualizer/tool-visualizer/tests/__snapshots__/model-surface.spec.ts.snap
index cfdef26bea..fdff907c88 100644
--- a/packages/visualizer/tool-visualizer/tests/__snapshots__/model-surface.spec.ts.snap
+++ b/packages/visualizer/tool-visualizer/tests/__snapshots__/model-surface.spec.ts.snap
@@ -87,7 +87,7 @@ exports[`Visualizer model surface > ships one neutral SVG and HTML model surface
             "type": "string",
           },
           "widget_code": {
-            "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. External resources are blocked; inline everything.",
+            "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. Keep the widget self-contained: include all required styles, scripts, data, and assets in the source.",
             "type": "string",
           },
         },
diff --git a/packages/visualizer/tool-visualizer/tests/model-surface.spec.ts b/packages/visualizer/tool-visualizer/tests/model-surface.spec.ts
index 6404398bb7..4810fdbf9a 100644
--- a/packages/visualizer/tool-visualizer/tests/model-surface.spec.ts
+++ b/packages/visualizer/tool-visualizer/tests/model-surface.spec.ts
@@ -171,7 +171,9 @@ describe('Visualizer model surface', () => {
     expect(sourceDescription).toContain('<canvas> using 2D or WebGL')
     expect(sourceDescription).toContain('inline <script>')
     expect(sourceDescription).toContain('For SVG: raw SVG')
-    expect(sourceDescription).toContain('External resources are blocked; inline everything')
+    expect(sourceDescription).toContain(
+      'Keep the widget self-contained: include all required styles, scripts, data, and assets in the source',
+    )
     expect(sourceDescription).not.toContain('load and follow the interactive widget_guidelines module')
     expect(sourceDescription).not.toContain('window.dshWidget')
   })
diff --git a/snapshots/web/visualizer-host/tool-schemas.expected.json b/snapshots/web/visualizer-host/tool-schemas.expected.json
index 8f3fb74893..08f5cb26e9 100644
--- a/snapshots/web/visualizer-host/tool-schemas.expected.json
+++ b/snapshots/web/visualizer-host/tool-schemas.expected.json
@@ -416,7 +416,7 @@
           },
           "widget_code": {
             "type": "string",
-            "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. External resources are blocked; inline everything."
+            "description": "For HTML: one fragment. Put any inline <style> first, content next (semantic HTML, inline <svg>, <canvas> using 2D or WebGL, or native controls), and any inline <script> last. For SVG: raw SVG beginning with <svg>, with a viewBox that declares its aspect ratio. Keep the widget self-contained: include all required styles, scripts, data, and assets in the source."
           }
         },
         "required": [