a2ui-render-in-dsh 0.1.1 → 0.2.0

package/lib/index.js

@@ -5878,66 +5878,121 @@ var KNOWN_COMPONENTS = /* @__PURE__ */ new Set([
   "Card",
   "List",
   "Divider",
+  "Tabs",
+  "When",
+  "Wizard",
   "Text",
+  "Markdown",
   "Image",
+  "Icon",
   "Tag",
   "Math",
   "Mermaid",
   "Chart",
+  "Map",
   "Video",
+  "Audio",
   "Anim",
+  "Table",
+  "Stat",
+  "Steps",
+  "Progress",
+  "Timeline",
+  "CodeBlock",
+  "Flashcard",
+  "Countdown",
+  "ImageCompare",
   "Button",
   "MultipleChoice",
   "Select",
+  "Rate",
+  "Slider",
   "CheckBox",
-  "TextField"
+  "TextField",
+  "Calc",
+  "Upload",
+  "Suggestions",
+  "Calendar",
+  "RankList",
+  "Signature",
+  "EditableTable"
 ]);
 var CATALOG_DOC = `# a2ui_render authoring guide
 
-Adaptive use: render a card ONLY when it clearly beats prose \u2014 (a) interaction: quiz/multiple-choice, short forms, option or confirm pickers, product cards; (b) visualization: charts, math function plots, flowcharts, mind maps, diagrams, LaTeX formulas. Otherwise answer in plain text. One call = one card; display-only cards (no Button) are fine. To show several items or a chart dashboard, make ONE call with a Grid \u2014 never several calls.
+Forms: each question = one field; options -> MultipleChoice/Select; free answers -> TextField (multiline for long); offering suggestions? ALSO add a TextField for a custom answer; several questions = ONE card, ONE submit Button labeled with the action ("\u63D0\u4EA4", "\u786E\u8BA4\u5EFA\u6863"). Multiple items or several charts = ONE call with a Grid. Display-only cards (no Button) are fine. Pair every card with 1-3 sentences of prose (takeaway/caveats) \u2014 never restate its data in text.
 
-## Components ("components" is an A2UI v0.9 adjacency list; MUST include a node with id "root"; only these names render)
+## Components (adjacency list; MUST include id "root"; only these names render)
 Layout:
 - Column / Row {children, gap?}
-- Grid {children, columns?, gap?, minWidth?} \u2014 side-by-side cards & 2x2 dashboards; columns 2\u20134, or omit for auto-fit at minWidth px (default 180)
-- Card {children, title?}
-- List {children, direction?: "vertical"|"horizontal"}
-- Divider {}
-Content (Chart/Mermaid/Image have built-in fullscreen zoom \u2014 do not oversize them):
+- Grid {children, columns?, gap?, minWidth?} \u2014 side-by-side cards, 2x2 dashboards (columns 2-4, omit for auto-fit)
+- Card {children, title?} \xB7 List {children, direction?} \xB7 Divider {}
+- Tabs {tabs: ["\u540D"\u2026], children, bind?} \u2014 one child per tab; dataset switching / grouping
+- When {value: {"path": "/x"}, equals?, includes?, notEmpty?, children} \u2014 children render only when the bound value matches; use for follow-up fields (e.g. reason box when choice includes "\u5176\u4ED6")
+- Wizard {steps: ["\u6B65\u9AA4\u540D"\u2026], children, submitLabel?} \u2014 multi-step form: one child (Column of fields) per step, built-in prev/next/progress, last step submits ALL fields; use for 5+ questions
+Content (Chart/Mermaid/Image auto-get fullscreen zoom; don't oversize):
 - Text {text, variant?: "h1"|"h2"|"h3"|"body"|"caption"|"strong"}
-- Image {url, alt?, width?, height?} \u2014 GIF ok
-- Tag {text, color?: "blue"|"green"|"red"|"orange"|"gray"}
-- Math {tex, block?} \u2014 KaTeX LaTeX, e.g. {"tex": "\\\\int_0^1 x^2\\\\,dx = \\\\frac{1}{3}", "block": true}. ALWAYS use Math for mathematical notation \u2014 matrices and vectors included: NEVER write raw nested arrays like [[2,1],[0,3]] inside Text; render them as a formula instead, e.g. {"tex": "\\\\begin{pmatrix}2&1\\\\\\\\0&3\\\\end{pmatrix}\\\\times\\\\begin{pmatrix}1&4\\\\\\\\5&2\\\\end{pmatrix}=\\\\begin{pmatrix}7&10\\\\\\\\15&6\\\\end{pmatrix}", "block": true} (row separator is \\\\\\\\). When animating matrix math with Anim, put the overall equation in a Math block above it.
-- Mermaid {code, caption?} \u2014 flowchart ("graph TD; A[\u5F00\u59CB]-->B{\u5224\u65AD}"), mindmap ("mindmap\\n  root((\u4E3B\u9898))\\n    \u5206\u652F"), sequenceDiagram, gantt, pie, stateDiagram
-- Chart {option, height?, functions?, xMin?, xMax?, samples?, yClip?} \u2014 ECharts. Data mode: standard ECharts option verbatim (line/bar/pie/scatter/radar/heatmap\u2026). Function mode: functions=[{"expr":"tan(x)","name"?:"y=tan(x)"}] with xMin/xMax (default -10..10) and yClip (default 10) \u2014 ~400 points sampled, asymptotes break automatically; NEVER hand-enumerate data points for a math curve. Expressions: + - * / ^ %, sin cos tan cot sec csc asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log2 log10 floor ceil round sign min max pow atan2, constants pi/e, variable x.
-- Video {url, poster?, loop?, muted?, autoplay?} \u2014 mp4/webm
-- Anim {frames, interval?, height?, autoplay?, labels?} \u2014 step-by-step ALGORITHM animation; auto-plays through ONCE, then the user replays/steps via the built-in controls (do not loop). The form is auto-detected from the frame shape. Simulate the algorithm yourself, one frame per step, each with a clear "note" caption. Two forms:
-  (1) Array/bars (sorting, searching, heaps; 8\u201312 small numbers): frames=[{"data":[5,3,8,1],"highlight":[0,1],"sorted":[3],"note":"\u6BD4\u8F83 5 \u548C 3"},\u2026] \u2014 data is the FULL array state, highlight = indices being operated on (orange), sorted = finalized (green).
-  (2) Grid/matrix (matrix ops, DP tables, 2D grids): frames=[{"grids":[{"title":"A","data":[[1,2],[3,4]],"highlight":[[0,0],[0,1]]},{"title":"B","data":[[5,7],[6,8]],"highlight":[[0,0],[1,0]]},{"title":"C=A\xD7B","data":[[17,null],[null,null]],"accent":[[0,0]]}],"note":"C[0][0]=1\xD75+2\xD76=17"},\u2026] \u2014 grids render side by side; highlight = cells being read (orange), accent = cells being written (green), null cells render empty. A single grid may use {"grid": [[...]], "highlight": [[r,c]], "accent": [[r,c]]} directly.
+- Markdown {text} \u2014 rich long-form (headings, bold/italic, links, lists, quotes, fenced code, $...$ math); use for any multi-paragraph text instead of stacked Texts
+- Image {url, alt?, width?, height?} \xB7 Tag {text, color?: "blue"|"green"|"red"|"orange"|"gray"}
+- Icon {name, size?, color?} \u2014 check x plus minus warning info star heart calendar clock location user search settings mail phone home file link download upload play music image cart tag gift trophy fire bolt sun moon cloud thumbs-up
+- Math {tex, block?} \u2014 KaTeX. ALL math notation goes here, matrices included: never raw arrays like [[2,1],[0,3]] in Text \u2014 write {"tex": "\\\\begin{pmatrix}2&1\\\\\\\\0&3\\\\end{pmatrix}", "block": true} (row sep \\\\\\\\). Equation above its Anim when animating.
+- Mermaid {code, caption?} \u2014 flowchart ("graph TD; A[\u5F00\u59CB]-->B{\u5224\u65AD}"), mindmap, sequenceDiagram, gantt, pie, stateDiagram
+- Chart {option, height?, functions?, params?, xMin?, xMax?, yClip?} \u2014 ECharts (viewers get a PNG-download button). Data mode: standard option verbatim. Function mode: functions=[{"expr":"tan(x)","name"?}], xMin/xMax (\xB110), yClip (10); sampled automatically, asymptotes break \u2014 NEVER hand-enumerate curve points. Ops: + - * / ^ %, sin cos tan cot sec csc asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log2 log10 floor ceil round sign min max pow atan2, pi/e, x. params: {"mu":{"path":"/mu"}} injects bound values as constants \u2014 pair with Slider for live curves.
+- Table {columns, rows, caption?, sortable?, filter?, pageSize?} \u2014 for any 2+ item comparison; sort/filter/pagination/copy/CSV are automatic. Dict binding: rows={"source":{"k1":[[\u2026]],\u2026},"pick":{"path":"/k"}} + a Select/Tabs on that path switches datasets live.
+- Stat {label, value, unit?, trend?, hint?} \u2014 KPI tile ("+12%" green / "-3%" red); several in a Grid
+- Steps {items: [{title, description?, status?: "done"|"current"|"pending"}]} \u2014 linear procedures; Mermaid flowchart only when it BRANCHES
+- Progress {value, max?, label?} \xB7 Timeline {items: [{time?, title, description?}]} (past events; Steps = to-dos)
+- CodeBlock {code, language?, title?} \u2014 ALWAYS for code, including quiz/form stems: compose Text(\u9898\u5E72) + CodeBlock(\u4EE3\u7801) + inputs; NEVER inline code in a Text prop
+- Video {url, poster?\u2026} \xB7 Audio {url, title?} \xB7 Flashcard {front, back} \xB7 Countdown {to?: "2026-09-01 10:00", seconds?, label?}
+- Map {data: [{name: "\u5E7F\u4E1C", value: 100}\u2026], title?, unit?, height?} \u2014 China province choropleth (regional sales/distribution); province names in Chinese
+- ImageCompare {before, after} \u2014 drag-divider image comparison (before/after, A/B)
+- Anim {frames, interval?, height?, autoplay?} \u2014 algorithm animation; plays ONCE, user replays via controls. Form auto-detected from frame shape; simulate the algorithm yourself, one frame per step with a "note" caption, FULL state each frame:
+  bars (sorting/searching, 8-12 numbers): {"data":[5,3,8,1],"highlight":[0,1],"sorted":[3],"note":"\u2026"} \u2014 highlight=orange, sorted=green
+  grid (matrix/DP): {"grids":[{"title":"A","data":[[1,2],[3,4]],"highlight":[[0,0]]},{"title":"C","data":[[17,null]],"accent":[[0,0]]}],"note":"\u2026"} \u2014 highlight=read(orange), accent=write(green), null=empty; single grid: {"grid":[[\u2026]],\u2026}
+  graph (BFS/DFS/trees): {"graph":{"nodes":[{"id":"A","label"?,"x"?,"y"?,"state"?:"active"|"seen"|"done"}],"edges":[["A","B","active"|"done"?]]},"note":"\u2026"} \u2014 no x/y (0-100) = auto circle; active=orange, seen=blue, done=green
 Interaction:
 - Button {label, variant?: "primary"|"default"|"danger", submit?, action: {event: {name, context?}}}
-- MultipleChoice {options: [{label, value, description?, disabled?}], bind, maxAllowedSelections?, disabled?} \u2014 flat option list; stores an array of chosen values at bind; maxAllowedSelections 1 = single-select
-- Select {options: [{label, value, description?, disabled?}], bind, label?, placeholder?, multiple?, maxAllowedSelections?, disabled?} \u2014 dropdown select, better for long option lists or compact forms; single-select stores the chosen value at bind, multiple: true stores an array (maxAllowedSelections caps it)
-- CheckBox {label, bind, disabled?} \u2014 boolean at bind
-- TextField {label?, placeholder?, multiline?, bind, disabled?} \u2014 string at bind
-Input states: preselect by seeding dataModel at the bind path (e.g. dataModel={"city":"beijing"} or {"skills":["go","sql"]}); disable a whole control with disabled: true, or one option via disabled on that option.
+- MultipleChoice {options: [{label, value, description?, disabled?}], bind, maxAllowedSelections?, disabled?} \u2014 array at bind; max 1 = single-select
+- Select {options, bind, label?, placeholder?, multiple?, maxAllowedSelections?, disabled?} \u2014 dropdown; single stores value, multiple stores array
+- Rate {bind, label?, max?, disabled?} \u2014 stars 1..max (5)
+- Slider {bind, label?, min?, max?, step?, unit?, disabled?} \u2014 numbers in a range; parameter exploration with Chart params
+- Calc {expr, inputs: {name: {"path": "/x"}\u2026}, out, digits?} \u2014 invisible derived number written at out; chainable. digits rounds display only \u2014 omit on intermediates to keep precision
+- CheckBox {label, bind, disabled?} \xB7 TextField {label?, placeholder?, multiline?, kind?: "text"|"number"|"date"|"time", bind, disabled?}
+- Upload {bind?, label?, max?} \u2014 image picker; chosen images are SENT TO YOU with the submission (use whenever seeing an image helps)
+- Calendar {bind, label?, min?, max?, range?} \u2014 month-view date picker; range: true picks start+end (value ["\u8D77","\u6B62"])
+- RankList {items: ["\u9009\u9879"\u2026], bind, label?} \u2014 user reorders by priority; submits the ordered list
+- Signature {label?} \u2014 handwritten signature pad; the drawing is sent to you as an image
+- EditableTable {columns, rows, bind, label?} \u2014 user edits cells, the whole grid submits at bind
+- Suggestions {items: ["\u8FFD\u95EE1"\u2026]} \u2014 tappable follow-ups; a tap sends that question as the user's message. ADD 2-4 to display-only cards
+Preselect by seeding dataModel at bind paths; disable via disabled on a control or option. Any input takes required: true \u2014 submit is blocked (field highlighted) until filled; give required fields labels.
+
+## Reactivity
+Bindings are live: inputs write bind paths, every {"path"} display binding updates instantly.
+- Follow-ups: MultipleChoice bind:"a" + When includes:"\u5176\u4ED6" wrapping a TextField
+- Exploration: Slider bind:"mu" + Chart params:{"mu":{"path":"/mu"}}
+- Calculators: Sliders -> Calc {expr, inputs, out:"monthly"} -> Stat value:{"path":"/monthly"}
+- Dataset switch: Tabs panes, or Table dict binding
+Seed every bound path in dataModel.
+
+## Scenario map
+Input collection -> form (TextField/kind date|time|number, MultipleChoice 2-7 options, Select for long lists, CheckBox, Rate). Decisions -> Grid Cards + Table; lone confirm Button gets submit:true. Data -> Chart (trend/rank/share) + Stat tiles + Table; regional -> Map. Learning -> MultipleChoice quizzes (options may be formulas), Math, Chart functions (+Slider), Anim, mindmap, Flashcard; \u8BFB\u4EE3\u7801\u9898 = Text(\u9898\u5E72) + CodeBlock(\u4EE3\u7801) + TextField. Procedures -> Steps (Timeline for history, Progress for completion, gantt/Table for schedules). Entertainment -> Grid recommendation cards, Rate, polls via MultipleChoice.
+
+## Inline math
+Any text prop (Text, option labels/descriptions, Table cells, Steps, Flashcard, Anim notes) embeds formulas with $...$, e.g. option {"label": "$\\\\frac{x^2}{2}+C$"}. Math component = display equations; $...$ = math inside sentences/choices. In math quizzes, option labels with fractions/roots/integrals/exponents SHOULD be $...$ formulas (e.g. {"label": "$3x^2$"}), not Unicode approximations.
 
 ## Data binding
-- "bind" is a dataModel key path WITHOUT a leading slash ("answer", "form/name").
-- Display props may read live values with {"path": "/answer"} (WITH leading slash).
-- "dataModel" seeds initial values. Avoid literal string props that start with "/".
+"bind" = write path WITHOUT leading slash ("answer", "form/name"). Display reads use {"path": "/answer"} (WITH slash). Avoid literal string props starting with "/".
 
 ## Submission
-- A Button click sends a plain-language user message: button label + chosen values ("\u63D0\u4EA4\u7B54\u6848\uFF1AB\u3001C"; multi-line for forms). MultipleChoice values arrive as their option LABELS \u2014 map back to values yourself if they differ.
-- action.event.context is optional (touched fields are included automatically); entries may be literals or {"path": "/x", "label": "\u5B57\u6BB5\u540D"}.
-- Locking: under submitMode "once" (default), a click locks the card ONLY when the card has input components (MultipleChoice/CheckBox/TextField) \u2014 a form/quiz submits once and stays recorded. Buttons on cards WITHOUT inputs (product \u67E5\u770B\u8BE6\u60C5, menus) are query buttons and stay clickable. Override per Button with submit: true (always lock \u2014 e.g. a lone confirm button) or submit: false (never lock). submitMode "multi" disables locking entirely.
-- After rendering an interactive card, end your turn with one short line telling the user to use the card. If the user types a plain reply instead, accept it as the answer.
+Button click sends a plain-language user message: button label + chosen values ("\u63D0\u4EA4\u7B54\u6848\uFF1AB\u3001C"; multi-line for forms); MultipleChoice arrives as option LABELS. action.event.context optional (touched fields auto-included); entries may be literals or {"path": "/x", "label": "\u540D"}. Locking (submitMode "once", default): cards WITH inputs lock after submit and stay recorded; input-less cards' buttons are query buttons, always clickable; per-Button submit: true|false overrides; "multi" never locks. A plain typed reply also counts as the answer. Uploads/signatures arrive attached to the submission. \u91CD\u65B0\u586B\u5199 unlocks a locked card; corrections arrive prefixed \uFF08\u4FEE\u6B63\uFF09.
 
-## Example (single-select quiz)
-components=[{"id":"root","component":"Column","children":["q","opts","submit"]},{"id":"q","component":"Text","variant":"h3","text":"TCP \u4E09\u6B21\u63E1\u624B\u7684\u7B2C\u4E8C\u6B65\u662F\u4EC0\u4E48\uFF1F"},{"id":"opts","component":"MultipleChoice","bind":"answer","maxAllowedSelections":1,"options":[{"label":"SYN","value":"SYN"},{"label":"SYN-ACK","value":"SYN-ACK"}]},{"id":"submit","component":"Button","label":"\u63D0\u4EA4\u7B54\u6848","variant":"primary","action":{"event":{"name":"submit"}}}]
+## Updating a rendered card
+a2ui_render returns a surfaceId. Call a2ui_update {surfaceId, components?, dataModel?} to change that card IN PLACE \u2014 replace/add components by id, overwrite dataModel keys. Use for long-task progress, corrections, appended results \u2014 never render a duplicate card. Cards stream progressively; don't shrink them.
+
+## Example (quiz)
+components=[{"id":"root","component":"Column","children":["q","opts","btn"]},{"id":"q","component":"Text","variant":"h3","text":"\u2026\u9898\u76EE\u2026"},{"id":"opts","component":"MultipleChoice","bind":"answer","maxAllowedSelections":1,"options":[{"label":"A\u2026","value":"A"},{"label":"B\u2026","value":"B"}]},{"id":"btn","component":"Button","label":"\u63D0\u4EA4\u7B54\u6848","variant":"primary","action":{"event":{"name":"submit"}}}]
 dataModel={"answer":[]}`;
-var RENDER_DESCRIPTION = "Render a UI card (A2UI) inline in the chat: quiz/multiple-choice questions, short forms, option/confirm pickers, product cards, ECharts charts and math function plots, Mermaid flowcharts/mind maps, LaTeX formulas, images, video, step-by-step algorithm animations (sorting etc.). Use ONLY when a card clearly beats prose; otherwise answer in plain text. IMPORTANT: before your FIRST call in a conversation, call a2ui_catalog and follow its authoring guide \u2014 do not guess component names or props. After rendering an interactive card, end your turn; the user's submission arrives as a plain-language user message.";
-var CATALOG_DESCRIPTION = "Returns the A2UI authoring guide for a2ui_render: the full component catalog with props, data-binding rules, submission format, and an example. Call it ONCE before your first a2ui_render in a conversation; the result stays in context \u2014 call again only if the guide is no longer visible.";
+var RENDER_DESCRIPTION = "Render a UI card (A2UI) inline in the chat. Judge EVERY reply from user intent (they never say \u5361\u7247/\u56FE\u8868): would a card serve any of UI's FOUR purposes better than prose? ACT \u64CD\u4F5C: user must answer/choose/fill/adjust/confirm -> form card. BROWSE \u6D4F\u89C8: user wants to see/scan data or items \u2014 statistics, rankings, distributions, trends, comparisons, multi-item recommendations -> chart/table/map/Grid of item cards; \u770B/\u67E5/\u5BF9\u6BD4/\u63A8\u8350\u51E0\u4E2A IS a card ask, and dated or approximate data never cancels the card \u2014 chart the best known, label the period, caveat in prose. UNDERSTAND \u7406\u89E3: structure, notation or motion aids comprehension \u2014 math, code, flows, what-if exploration, and time-unfolding processes (algorithms, simulations) -> step animation. FEEDBACK \u53CD\u9988: before multi-step work (3+ tool steps), render a Progress/Steps card, a2ui_update it as steps complete, final results into the card (not markdown tables in prose). None of the four (opinions, narration, short answers, translations, chat) -> prose. Compose freely \u2014 one card can mix form/chart/table/formula parts. Cards PAIR with prose: 1-3 sentences of takeaway as normal text, structured content in the card, no duplication. Call a2ui_catalog BEFORE your first render in a conversation \u2014 never guess component names. After an interactive card, end your turn; the submission arrives as a plain-language user message.";
+var CATALOG_DESCRIPTION = "Returns the full component catalog and authoring rules for a2ui_render. Call ONCE before your first render in a conversation; the result stays in context \u2014 call again only if it is no longer visible.";
 function apply(ctx) {
   ctx.tools.register(defineTool({
     name: "a2ui_catalog",
@@ -5960,33 +6015,15 @@ function apply(ctx) {
     name: "a2ui_render",
     description: RENDER_DESCRIPTION,
     parameters: {
-      title: {
-        type: "string",
-        description: "Card title (optional)."
-      },
+      title: { type: "string", description: "Card title." },
       components: {
         type: "array",
         required: true,
-        description: 'A2UI v0.9 adjacency list; must include a node with id "root". Component names and props: see a2ui_catalog.',
-        items: {
-          type: "object",
-          additionalProperties: true,
-          properties: {
-            id: { type: "string", required: true },
-            component: { type: "string", required: true },
-            children: { type: "array", items: { type: "string" } }
-          }
-        }
-      },
-      dataModel: {
-        type: "object",
-        additionalProperties: true,
-        description: "Initial data model (optional)."
+        description: 'A2UI adjacency list incl. a node with id "root"; see a2ui_catalog.',
+        items: { type: "object", additionalProperties: true }
       },
-      submitMode: {
-        type: "string",
-        description: '"once" (default, locks after submit) or "multi" \u2014 see a2ui_catalog.'
-      }
+      dataModel: { type: "object", additionalProperties: true, description: "Initial values." },
+      submitMode: { type: "string", description: '"once" (default) | "multi".' }
     },
     output: {
       schema: {
@@ -5994,27 +6031,81 @@ function apply(ctx) {
         additionalProperties: false,
         properties: {
           status: { type: "string", required: true },
+          surfaceId: { type: "string" },
           hint: { type: "string" }
         }
       },
       render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }]
     },
     isConcurrencySafe: () => true,
-    async execute(args) {
+    async execute(args, exec) {
       const components = Array.isArray(args.components) ? args.components : [];
       if (!components.some((node) => node !== null && typeof node === "object" && node.id === "root")) {
         throw new Error('a2ui_render: components must include a node with id "root". Call a2ui_catalog for the authoring guide.');
       }
+      const byId = new Map(components.filter((n) => n !== null && typeof n === "object" && n.id !== void 0).map((n) => [n.id, n]));
+      const reachable = /* @__PURE__ */ new Set();
+      const missing = /* @__PURE__ */ new Set();
+      const queue = ["root"];
+      while (queue.length > 0) {
+        const id = queue.pop();
+        if (reachable.has(id)) continue;
+        reachable.add(id);
+        const node = byId.get(id);
+        if (node === void 0) {
+          missing.add(id);
+          continue;
+        }
+        for (const child of Array.isArray(node.children) ? node.children : []) queue.push(child);
+      }
+      if (missing.size > 0) {
+        throw new Error(`a2ui_render: children reference undefined component id(s) ${[...missing].map((id) => `"${id}"`).join(", ")} \u2014 define them or fix the reference.`);
+      }
+      const orphans = [...byId.keys()].filter((id) => !reachable.has(id));
+      if (orphans.length > 0) {
+        throw new Error(`a2ui_render: component(s) ${orphans.map((id) => `"${id}"`).join(", ")} are defined but not reachable from "root" \u2014 add them to a parent's children or remove them.`);
+      }
       const unknown = [...new Set(components.map((node) => node?.component).filter((component) => typeof component === "string" && !KNOWN_COMPONENTS.has(component)))];
       if (unknown.length > 0) {
         throw new Error(`a2ui_render: unknown component(s) ${unknown.map((component) => `"${component}"`).join(", ")} \u2014 nothing would render. Call a2ui_catalog for the list of valid components.`);
       }
       return {
+        surfaceId: String(exec.callId),
         status: "presented",
-        hint: "Card rendered in the chat. The user's interaction arrives as the next user message (button label + chosen values in plain language). End your turn now if you are waiting for it."
+        hint: "Card rendered. The user's action arrives as the next user message; end your turn if waiting."
       };
     }
   }));
+  ctx.tools.register(defineTool({
+    name: "a2ui_update",
+    description: "Update a rendered card IN PLACE by its surfaceId (from a2ui_render): components replace/add by id, dataModel overwrites keys. For progress, corrections, appended results \u2014 never render a duplicate card.",
+    parameters: {
+      surfaceId: { type: "string", required: true, description: "The surfaceId returned by the a2ui_render call to update." },
+      components: {
+        type: "array",
+        description: "Components to add or replace (matched by id); same schema as a2ui_render.",
+        items: { type: "object", additionalProperties: true }
+      },
+      dataModel: { type: "object", additionalProperties: true, description: "Data model values to overwrite, keyed by top-level path." }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: { status: { type: "string", required: true } }
+      },
+      render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }]
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      if ((!Array.isArray(args.components) || args.components.length === 0) && (args.dataModel === null || typeof args.dataModel !== "object" || Object.keys(args.dataModel ?? {}).length === 0)) {
+        throw new Error("a2ui_update: provide components and/or dataModel to change.");
+      }
+      const unknown = [...new Set((Array.isArray(args.components) ? args.components : []).map((node) => node?.component).filter((component) => typeof component === "string" && !KNOWN_COMPONENTS.has(component)))];
+      if (unknown.length > 0) throw new Error(`a2ui_update: unknown component(s) ${unknown.join(", ")} \u2014 call a2ui_catalog.`);
+      return { status: "updated" };
+    }
+  }));
 }
 export {
   apply,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2ui-render-in-dsh",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A2UI interactive cards for the dsh web UI: the agent renders clickable interfaces (quizzes, forms, product cards) via @ant-design/x-card, and user interactions flow back to the agent as answers.",
   "author": "sondge <fengshangjie@lilybearing.com>",
   "license": "MIT",
@@ -52,15 +52,18 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "watch": "node scripts/build.mjs --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "node test/run.mjs"
   },
   "devDependencies": {
     "@ant-design/x-card": "^2.9.0",
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
     "echarts": "^6.1.0",
     "esbuild": "^0.25.0",
+    "jsdom": "^30.0.1",
     "katex": "^0.18.4",
     "mermaid": "^11.17.0",
+    "playwright": "^1.62.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
@@ -75,6 +78,5 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
-  },
-  "dependencies": {}
+  }
 }