a2ui-render-in-dsh 0.1.0

package/lib/index.js

@@ -0,0 +1,154 @@
+// src/host/index.js
+import { defineTool } from "@deepseek-ai/dsh-tools";
+var name = "a2ui";
+var inject = ["tools"];
+var KNOWN_COMPONENTS = /* @__PURE__ */ new Set([
+  "Column",
+  "Row",
+  "Grid",
+  "Card",
+  "List",
+  "Divider",
+  "Text",
+  "Image",
+  "Tag",
+  "Math",
+  "Mermaid",
+  "Chart",
+  "Video",
+  "Anim",
+  "Button",
+  "MultipleChoice",
+  "Select",
+  "CheckBox",
+  "TextField"
+]);
+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.
+
+## Components ("components" is an A2UI v0.9 adjacency list; MUST include a node with 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):
+- 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.
+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.
+
+## 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 "/".
+
+## 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.
+
+## 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"}}}]
+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.";
+function apply(ctx) {
+  ctx.tools.register(defineTool({
+    name: "a2ui_catalog",
+    description: CATALOG_DESCRIPTION,
+    parameters: {},
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: { doc: { type: "string", required: true } }
+      },
+      render: (_args, value) => [{ type: "text", text: value.doc }]
+    },
+    isConcurrencySafe: () => true,
+    async execute() {
+      return { doc: CATALOG_DOC };
+    }
+  }));
+  ctx.tools.register(defineTool({
+    name: "a2ui_render",
+    description: RENDER_DESCRIPTION,
+    parameters: {
+      title: {
+        type: "string",
+        description: "Card title (optional)."
+      },
+      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)."
+      },
+      submitMode: {
+        type: "string",
+        description: '"once" (default, locks after submit) or "multi" \u2014 see a2ui_catalog.'
+      }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          status: { type: "string", required: true },
+          hint: { type: "string" }
+        }
+      },
+      render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }]
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      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 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 {
+        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."
+      };
+    }
+  }));
+}
+export {
+  apply,
+  inject,
+  name
+};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "a2ui-render-in-dsh",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baihui-ai/a2ui-render-in-dsh.git"
+  },
+  "homepage": "https://github.com/baihui-ai/a2ui-render-in-dsh#readme",
+  "bugs": {
+    "url": "https://github.com/baihui-ai/a2ui-render-in-dsh/issues"
+  },
+  "keywords": [
+    "dsh",
+    "a2ui",
+    "agent-ui",
+    "ant-design-x",
+    "interactive-cards",
+    "echarts",
+    "mermaid",
+    "katex"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-tool"
+      ]
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "watch": "node scripts/build.mjs --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@ant-design/x-card": "^2.9.0",
+    "echarts": "^6.1.0",
+    "esbuild": "^0.25.0",
+    "katex": "^0.18.4",
+    "mermaid": "^11.17.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}