a2ui-render-in-dsh 0.1.1 → 0.1.2

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. ALWAYS accompany the card with 1-3 sentences of normal prose in your reply (the takeaway, what to look at, or caveats) \u2014 a bare card with no text reads as unfinished; but never restate the card's 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 (a Column of fields) per step, built-in \u4E0A\u4E00\u6B65/\u4E0B\u4E00\u6B65/progress, the last step's submit sends ALL collected fields at once; use when a form has 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 text (headings, bold/italic, links, lists, quotes, fenced code, $...$ math); USE instead of stacking Text components for any multi-paragraph explanation inside a card
+- 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 any 2+ item attribute comparison beats prose. Interactive by default: click-to-sort headers, auto filter box and pagination on long data, copy/CSV export built in. 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 snippets
+- 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 (one Calc's out feeds another's inputs). digits rounds DISPLAY values only \u2014 omit on intermediate results (rates, ratios) to keep full 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 (screenshots, photos, receipts \u2014 use whenever seeing an image would help)
+- Calendar {bind, label?, min?, max?} \u2014 month-view date picker (friendlier than kind:"date" for choosing among nearby dates)
+- 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", "\u8FFD\u95EE2"\u2026]} \u2014 tappable follow-up questions below an answer; tapping sends that question as the user's message. ADD 2-4 to display-only cards when natural next questions exist
+Preselect by seeding dataModel at bind paths; disable via disabled on a control or an option.
+
+## 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. Learning -> MultipleChoice quizzes (options may be formulas), Math, Chart functions (+Slider), Anim, mindmap, Flashcard, CodeBlock. 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. After an interactive card, end your turn with one short line; a plain typed reply also counts as the answer. Uploaded images/signatures arrive attached to the submission message. Users can hit \u91CD\u65B0\u586B\u5199 on a locked card \u2014 the corrected submission is 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 (render a Progress card first, then update /percent as you work), corrections, and appending results \u2014 never render a duplicate card for the same content. Cards render progressively while you stream \u2014 no need to keep them small.
+
+## 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 semantically from user intent (they never say \u5361\u7247/\u56FE\u8868/\u52A8\u753B): (1) UTILITY \u2014 would a card serve any of UI's three purposes better than prose? ACT \u64CD\u4F5C: the user must answer/choose/fill/adjust/rate/confirm -> form. BROWSE \u6D4F\u89C8: the user wants to see/scan data or many items \u2014 statistics, rankings, distributions, trends, comparisons, or picking among several recommended items \u2014 movies/products/places/plans -> one Card per item in a Grid, or a Table (\u770B/\u67E5/\u5BF9\u6BD4/\u63A8\u8350\u51E0\u4E2A IS a card ask; dated or approximate data never cancels the card \u2014 chart the best you know, label the period, caveat in prose). UNDERSTAND \u7406\u89E3: structure, notation or MOTION aids comprehension \u2014 math, code, flows, schedules, stepwise processes, what-if exploration, and anything that unfolds over time (algorithms, simulations, physical processes) -> step animation. FEEDBACK \u53CD\u9988: before starting multi-step work (3+ tool steps), render a Progress/Steps card, a2ui_update it as steps complete, and put the final results in the card \u2014 never as a markdown table in prose. None of these (opinions, narration, short answers, translations, chat) -> prose. (2) FORM \u2014 fit each part and compose freely in one card: input->form, comparison->table, trend->chart, regional data->map, math->formula, code->code block, procedure->steps, relations->diagram, watchable process->animation, what-if->sliders+live chart. Cards PAIR with prose, never replace it: give your takeaway/analysis in 1-3 sentences of normal text and keep structured content in the card; don't duplicate data in both. Before your FIRST call in a conversation, call a2ui_catalog and follow it \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" } }
-          }
-        }
+        description: 'A2UI adjacency list incl. a node with id "root"; see a2ui_catalog.',
+        items: { type: "object", additionalProperties: true }
       },
-      dataModel: {
-        type: "object",
-        additionalProperties: true,
-        description: "Initial data model (optional)."
-      },
-      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,73 @@ 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 queue = ["root"];
+      while (queue.length > 0) {
+        const id = queue.pop();
+        if (reachable.has(id)) continue;
+        reachable.add(id);
+        const node = byId.get(id);
+        for (const child of Array.isArray(node?.children) ? node.children : []) queue.push(child);
+      }
+      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 card you previously rendered, IN PLACE: pass the surfaceId returned by a2ui_render, plus replacement/new components (matched by id) and/or dataModel value changes. Use for progress updates during long tasks, corrections, and appending content \u2014 instead of rendering 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.1.2",
   "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",