dsh-motion-ui 0.5.6 → 0.7.0

package/lib/author-expression.js

@@ -1,7 +1,7 @@
 // A small authoring language compiled to the existing interpreter; never eval.
 import { IDENTIFIER_SOURCE, validIdentifier } from './identifiers.js';
 export function compileExpression(source) {
-  const fail = () => { throw new Error('DSH UI: invalid formula; use state.x, data.x, derived.x, item.x, numbers, strings, + - * /, comparisons, ?: and min/max/round/abs'); };
+  const fail = () => { throw new Error('DSH UI: invalid formula; use state.x, data.x, derived.x, item.x, numbers, strings, + - * /, comparisons, ?: and min/max/round/ceil/floor/abs'); };
   if (typeof source !== 'string' || !source.trim() || source.length > 2048) fail();
   const tokens = []; let offset = 0;
   const token = new RegExp(String.raw`\s*(?:(\d+(?:\.\d*)?|\.\d+)([eE][+-]?\d+)?|("(?:[^"\\]|\\.)*")|(${IDENTIFIER_SOURCE}(?:\.${IDENTIFIER_SOURCE})?)|(===|!==|<=|>=|==|!=|[+*/()?,:<>-]))`, 'uy');
@@ -23,7 +23,7 @@ export function compileExpression(source) {
     else if (t === '(') { out = parse(0, depth + 1); take(')'); }
     else if (t === '-' || t === '+') { const arg = parse(5, depth + 1); out = t === '-' ? { op: 'sub', args: [{ const: 0 }, arg] } : arg; }
     else if (typeof t === 'string' && t.split('.').length === 2 && ['state','data','derived','item'].includes(t.split('.')[0]) && validIdentifier(t.split('.')[1])) out = { ref: t };
-    else if (['min', 'max', 'round', 'abs'].includes(t)) {
+    else if (['min', 'max', 'round', 'ceil', 'floor', 'abs'].includes(t)) {
       take('('); const args = [parse(0, depth + 1)];
       while (tokens[pos] === ',') { pos++; args.push(parse(0, depth + 1)); if (args.length > 8) fail(); }
       take(')'); out = { op: t, args };
@@ -55,6 +55,7 @@ export function expandExpressions(doc) {
   const walk = nodes => { if (!Array.isArray(nodes)) return; for (const node of nodes) {
     if (!node || typeof node !== 'object') continue;
     for (const field of ['text', 'value', 'max', 'rows']) if (Object.hasOwn(node, field)) node[field] = expression(node[field]);
+    if (['table','chart'].includes(node.type)&&Array.isArray(node.rows)) for(const row of node.rows) if(row&&typeof row==='object'&&!Array.isArray(row)) for(const k of Object.keys(row)) row[k]=expression(row[k]);
     walk(node.children);
   } };
   walk(doc.nodes); return doc;

package/lib/authoring-guide.js

@@ -1,15 +1,16 @@
 // Keep this short and early in the injected contract, including free mode.
 export const AUTHORING_GUIDE = `Authoring fast path:
-- UI presentation waits for the whole assistant turn to end, including later reasoning/text. A successful render call saves the UI but does not mean it is already visible. Tool argument streaming does not preview UI. Text/reasoning stream normally; continue the user's task without waiting for the display or polling it.
+- Complete validated components may preview progressively as read-only UI during tool argument streaming. Controls and scripts activate only when the whole assistant turn ends, including later reasoning/text. A successful render call saves the document; continue the user's task without waiting for the display or polling it.
 - JSON object field order never matters. Every node, including each sandbox, must include a unique id. sandbox title/fallback default to the document's only when omitted; do not send null or empty values.
 - Declaring state does NOT create controls. For each parameter the user should edit, add a native slider/input/select/toggle bound to state.key, or actual canvas HTML controls wired to DSHUI.setState with that key in stateKeys. A canvas subscribe callback only updates display; it does not create an input. Read-only state and static UI are valid; do not invent controls where the task does not need them. Check intended controls exist before calling the tool.
 - Use render_ui/render_canvas directly for UI construction. This contract and ui_catalog are the protocol reference; installation source inspection is not a prerequisite. For unclear component/formula details consult ui_catalog, rather than grep/glob/shell searches of DSH checkouts or app.asar. File/search tools needed for the user's actual task or data remain appropriate.
-- Formula round(x) takes ONE argument and uses JavaScript Math.round: nearest integer, ties toward positive infinity (round(2.5)=3, round(-2.5)=-2). It is not ceil/floor, which are not registered native formula functions. For ceiling/floor use Math.ceil/Math.floor in a canvas subscribed to declared shared state. Display decimals formats numbers without changing calculation precision.
+- Formula round(x) takes ONE argument and uses JavaScript Math.round: nearest integer, ties toward positive infinity (round(2.5)=3, round(-2.5)=-2). Native ceil(x) rounds up and floor(x) rounds down, each with ONE argument. Use {expr:"ceil(state.people / 2)"} for room counts directly, without a canvas or lookup chain. Display decimals formats numbers without changing calculation precision.
 - Pass tool JSON fields as objects, not hand-escaped JSON strings. For custom HTML/SVG use render_canvas({title,fallback,html,css,script}) to avoid nesting source in document JSON.
 - Start with the smallest useful static UI. State/derived/actions are optional. A table can put its object rows directly in rows; reuse data/derived references only when useful. Example: {id:"t",type:"table",label:"方案比较",columns:[{key:"方案",label:"方案"}],rows:[{"方案":"A"}]}.
 - For a short ordered process, use steps with a DIRECT items array: {id:"flow",type:"steps",items:[{title:"整理文件",description:"保留源码和说明，排除密钥。"},{title:"提交代码",description:"检查变更后提交。"}]}. Do not wrap items in {item:[...]}. status is optional: omit it for explanatory guides; use pending/active/done/error only for known task states. Keep one sentence per requested step; avoid extra command disclosures unless asked.
+- A short dynamic chart/table can use inline formula cells: rows:[{label:"餐饮",value:{ref:"derived.food"}},{label:"住宿",value:{expr:"ceil(state.people / 2) * state.room"}}]. Chart labelKey:"label",valueKey:"value". No map/if chain is required for a few categories. Submit complete nodes/state/derived together on every render_ui retry; it creates a document, not a partial patch.
 - Numeric controls need complete typed state: state:{people:{type:"number",default:2,min:1,max:12,step:1},days:{type:"number",default:5,min:2,max:15,step:1}}. Use numbers without quotes or units. Prefer derived:{food:{expr:"state.people * state.days * 100"}} to a deep op/args tree. children, options, columns and expression args are direct arrays. The host normalizes plain numeric strings only in explicitly numeric fields and exact {item:[...]} wrappers only at declared array positions; ordinary text/data retain their types.
-- Host defaults use rounded surfaces and soft theme-aware gradients. For guided canvas designs prefer 18..24px surface radii and subtle gradient fills with legible text. Let content determine height: no empty spacer sections, min-height:100vh or large fixed min-heights. A canvas auto-fits its rendered content after commit, including shrinking after filtering; height is only the initial placeholder. Use SVG viewBox bounds close to actual graphics plus reasonable padding.
+- Host defaults use readable editorial typography, quiet backgrounds, light borders and restrained accents. For guided canvas designs prefer 12..18px radii and flat surfaces; gradients are optional and must not replace information hierarchy. Let content determine height: no empty spacer sections, min-height:100vh or large fixed min-heights. A canvas auto-fits its rendered content after commit, including shrinking after filtering; height is only the initial placeholder. Use SVG viewBox bounds close to actual graphics plus reasonable padding.
 - metric.value accepts a finite number or display string/boolean. Numbers use decimals and unit; strings display verbatim ("约 12 GiB", "待确认"). Calculations and chart series still require real numbers, never formatted strings.
 - IDs, data/state/derived keys, column keys and formula references support Chinese letters and underscores. Use 1..64 letters/numbers/underscores, start with a letter/underscore, no spaces/dots/hyphens; never constructor/prototype/__proto__. Labels/text can be natural language.
 - Persist a canvas checklist/list/object with state:{checklist:{type:"json",default:[]}} and DSHUI.setState({checklist:nextArray}). json state allows bounded arrays/objects, no options; native input/select cannot edit it. A native checklist uses separate boolean states and toggle nodes. Static lists belong in nodes/data, not state. String state with an array/object default and no options is canonicalized to json without losing its structure.

package/lib/build-info.js

@@ -1,2 +1,2 @@
 // Generated by npm run build.
-export const BUILD_INFO = Object.freeze({"version":"0.5.6","id":"0.5.6+1a92fbfce0c2","sourceHash":"1a92fbfce0c23812d59332a0de554fd7fd914d44fd715ab8e056ca0f19193bcf"});
+export const BUILD_INFO = Object.freeze({"version":"0.7.0","id":"0.7.0+6adc22f63978","sourceHash":"6adc22f639783dee4cfb7400828727748c020f09b8e912e4500dde67fc871562"});

package/lib/canvas-system.js

@@ -1,12 +1,12 @@
 // Optional primitives for model-authored surfaces. Host theme remains authoritative.
 export const CANVAS_SYSTEM_CSS = `
-:root{--canvas-radius:20px;--canvas-gap:16px;--canvas-positive:#167456;--canvas-negative:#b13b3b;--canvas-warning:#875b15}
+:root{--canvas-radius:16px;--canvas-gap:16px;--canvas-positive:#167456;--canvas-negative:#b13b3b;--canvas-warning:#875b15}
 :root[data-canvas-scheme=dark]{--canvas-positive:#78d9b4;--canvas-negative:#ffaaaa;--canvas-warning:#edc87e}
 #canvas{display:flow-root}html,body{margin:0;min-width:0;background:var(--canvas-bg,#fff);color:var(--canvas-ink,#182537);font:14px/1.6 system-ui,"Microsoft YaHei",sans-serif}*{box-sizing:border-box}svg{max-width:100%;height:auto}button,input,select,textarea{font:inherit;color:inherit}button,input,select,textarea{border:1px solid var(--canvas-line,#ced4df);border-radius:8px;background:var(--canvas-bg,#fff);padding:8px 12px;max-width:100%}button{cursor:pointer}button:disabled{cursor:default;opacity:.55}input[type=range]{padding:0;accent-color:var(--canvas-accent,#3e60d3)}input[type=checkbox],input[type=radio]{accent-color:var(--canvas-accent,#3e60d3)}button:focus-visible,input:focus-visible,select:focus-visible,textarea:focus-visible,[tabindex]:focus-visible{outline:2px solid var(--canvas-accent,#3e60d3);outline-offset:3px}
 .ui-stack{display:grid;gap:var(--canvas-gap)}.ui-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,240px),1fr));gap:var(--canvas-gap)}.ui-surface{padding:20px;border:1px solid var(--canvas-line,#ced4df);border-radius:var(--canvas-radius);background:var(--canvas-soft,#f3f5f8)}.ui-title{margin:0;font-size:clamp(20px,3vw,28px);line-height:1.3;letter-spacing:-.02em}.ui-caption{color:var(--canvas-muted,#526176);margin:8px 0;font-size:14px}.ui-value{font-size:clamp(24px,4vw,36px);font-variant-numeric:tabular-nums;line-height:1.2}.ui-controls{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.ui-field{display:grid;gap:6px;min-width:0}.ui-legend{display:flex;gap:16px;flex-wrap:wrap;font-size:13px}.ui-status{min-height:1.6em}.ui-error{color:var(--canvas-negative)}.ui-primary{background:var(--canvas-accent,#3e60d3);color:var(--canvas-accent-ink,#fff);border-color:transparent}
 svg .ui-node{fill:var(--canvas-soft,#f3f5f8);stroke:var(--canvas-line,#ced4df);stroke-width:1}svg .ui-edge{fill:none;stroke:var(--canvas-muted,#526176);stroke-width:1.5}svg .ui-label{fill:var(--canvas-ink,#182537);font:500 14px system-ui,sans-serif}svg .ui-note{fill:var(--canvas-muted,#526176);font:400 13px system-ui,sans-serif}svg .ui-leader{fill:none;stroke:var(--canvas-muted,#526176);stroke-dasharray:3 4}svg .ui-accent{fill:color-mix(in srgb,var(--canvas-accent,#3e60d3) 12%,var(--canvas-bg,#fff));stroke:var(--canvas-accent,#3e60d3)}
 .ui-flow{display:flex;align-items:center;justify-content:center;gap:16px;padding:24px 8px;flex-wrap:wrap}.ui-step{display:grid;gap:6px;min-width:130px;max-width:240px;padding:16px 20px;border:1px solid var(--canvas-line);border-radius:6px;background:var(--canvas-bg)}.ui-step strong{font-size:16px;font-weight:600}.ui-step span{font-size:14px;color:var(--canvas-muted)}.ui-arrow{color:var(--canvas-muted);font-size:22px}.ui-callout{border-inline-start:3px solid var(--canvas-accent);padding:8px 16px;color:var(--canvas-ink)}
-.ui-surface,.ui-step{border-radius:var(--canvas-radius);background:linear-gradient(135deg,color-mix(in srgb,var(--canvas-accent,#3e60d3) 9%,var(--canvas-bg,#fff)),var(--canvas-soft,#f3f5f8))}button,input:not([type=checkbox]):not([type=radio]):not([type=range]),select,textarea{border-radius:14px}.ui-primary{background:linear-gradient(120deg,var(--canvas-accent,#3e60d3),color-mix(in srgb,var(--canvas-accent,#3e60d3) 85%,#152647))}.ui-callout{border-radius:14px;background:linear-gradient(120deg,color-mix(in srgb,var(--canvas-accent,#3e60d3) 7%,var(--canvas-bg,#fff)),var(--canvas-bg,#fff))}
+.ui-surface,.ui-step{border-radius:var(--canvas-radius);background:var(--canvas-bg,#fff)}button,input:not([type=checkbox]):not([type=radio]):not([type=range]),select,textarea{border-radius:12px}button{border-radius:999px}.ui-primary{background:var(--canvas-ink,#182537);color:var(--canvas-bg,#fff)}.ui-callout{border-radius:0 12px 12px 0;background:color-mix(in srgb,var(--canvas-accent,#3e60d3) 5%,var(--canvas-bg,#fff))}
 @media(max-width:480px){.ui-flow{flex-direction:column;padding:16px 8px;gap:12px}.ui-step{width:100%;max-width:none}.ui-arrow{transform:rotate(90deg)}}
 @media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important}}`;
 
@@ -14,5 +14,5 @@ export const CANVAS_SYSTEM_GUIDE = `The canvas includes optional .ui-stack, .ui-
 For a small static diagram, .ui-flow arranges .ui-step nodes separated by .ui-arrow; each step uses strong + span. .ui-callout emphasizes one sentence. These work with no custom CSS or JavaScript and adapt to narrow screens.
 SVG construction: reserve label space first; center box labels with text-anchor=middle and dominant-baseline=central. Measure Chinese characters at roughly one font-size each, Latin letters about .6 font-size; mixed text needs combined width plus 24px padding on each side. These are estimates, not browser measurements. Give same-role nodes aligned dimensions. Route connectors around text and unrelated boxes, with explicit fill=none and visible arrowheads. Compute viewBox bounds from the furthest shape, label and arrow plus padding. A 680-unit diagram shown at 340px halves its fonts: reflow or move captions into HTML instead of shrinking important labels. Keep PC chat-column labels readable at actual rendered size. Use overview + focus detail for dense systems. Do not force this grammar on spatial/mechanical drawings.
 For calculators validate blanks, finite values, ranges and zero denominators; show an actionable error, never a stale result as valid. Use one state source for filtering/sorting/reset and one animation loop with cleanup. A reset restores inputs and outputs together. For explanation show relationships and one useful variable; for comparison expose criteria/units/assumptions; for a tool provide working inputs, calculation, outputs and reset.
-For fastest render_canvas preview emit title, fallback, state/data/derived if needed, height, css, html, script in that order. Keep CSS small; put a useful static initial view in html. Preview is non-interactive and scripts only run after successful commit and state restoration. Source order is a delivery optimization, not a thinking limit. Do not claim a preview is a working or saved result.
+Keep CSS small and put a useful initial view in html. Source field order is arbitrary. UI is shown only after the assistant turn ends and scripts activate after state restoration; there is no live tool-time preview. Do not claim a saved document has been visually checked without evidence.
 Small building example (adapt relationships and dimensions to the actual task, not a compulsory template): <svg viewBox="0 0 420 120" role="img" aria-label="输入转为输出"><path class="ui-edge" d="M160 60H260"/><path class="ui-edge" d="M250 54L260 60L250 66"/><rect class="ui-node" x="20" y="36" width="140" height="48" rx="8"/><text class="ui-label" x="90" y="60" text-anchor="middle" dominant-baseline="central">输入</text><rect class="ui-node ui-accent" x="260" y="36" width="140" height="48" rx="8"/><text class="ui-label" x="330" y="60" text-anchor="middle" dominant-baseline="central">输出</text></svg>. Use SVG label text only; explanatory paragraphs belong in responsive HTML. For a reset button connect addEventListener('click',()=>DSHUI.setState({yourDeclaredKey:yourDefault})); render results from DSHUI.subscribe(s=>...) rather than independently duplicating host-derived formulas.`;

package/lib/catalog.js

@@ -1,93 +1,95 @@
-import { UI_ICONS, UI_TONES } from './presentation.js';
-import { componentGuide } from './components.js';
-import { AUTHORING_GUIDE } from './authoring-guide.js';
-export { sceneExamples } from './scenes.js';
-export { bicycleExample, oscillatorExample } from './canvas-example.js';
-export const PROTOCOL_GUIDE = AUTHORING_GUIDE+`\n\nDSH UI v1. Call render_ui({document: ...}) directly when visualization helps. Do not call it inside run_code/PTC in this version.
-Formula shorthand: {expr:"state.V * state.V / state.R"} compiles to the same validated interpreter. Supports explicit state.x/data.x/derived.x/item.x references, + - * /, == != < <= > >=, parentheses, condition ? yes : no, min/max/round/abs, double-quoted strings and booleans. Use it in derived, node text/value/max/rows or map.fields. No arbitrary functions, property chains, statements or side effects; complex animation belongs in render_canvas. Example derived:{power:{expr:"state.V * state.V / state.R"}}, metric.value:{ref:"derived.power"}.
-Document: {version:1,title:string,fallback:string,presentation?:{layout,accent,density},state?:{},data?:{},derived?:{},nodes:[],actions?:{}}.
-Scene layouts: dashboard (metrics/trends), workbench (parameter controls/results), comparison (parallel choice cards), guide (ordered instructions), status (observed task snapshot), report (reading and evidence). Accent: blue/teal/violet/amber/rose; density: comfortable/compact. Omit to keep the standard design. Choose based on the task, not at random. Card surface: outline/soft/featured. Featured indicates discussion focus, not an automatic recommendation.
-Additional nodes: badge {id,type,text,icon?,tone?}; progress {id,type,label,value,max,unit?,icon?,tone?} where values may be bindings and 0 <= value <= positive max; steps {id,type,items:[{title,description?,status?:"pending"|"active"|"done"|"error"}]} (direct array of 1..12 items, not {item:[...]}; omit status for static guides); details {id,type,title,children,open?:boolean,icon?,tone?}. Progress and steps are declared snapshots, not a live host task subscription. Only claim real progress/completion from actual tool evidence; mark demo data visibly. Details keeps the content available in text fallback.
-Streaming: use ONE normal native render_ui call. Write version,title,fallback,presentation,state,data,derived,actions BEFORE nodes where possible. The client previews completed, validated top-level subtrees as arguments stream; incomplete nodes/strings/calculations wait. Preview controls are disabled and never save state or send actions. Only a successful Host result activates the durable UI. No separate ui.begin/patch calls are required. A cancelled/failed generation has no interactive document. Prefer several small meaningful top-level sections over one enormous wrapping card.
-All IDs and dictionary keys: Unicode letters (including Chinese) or underscore, followed by letters/marks/digits/underscore, max64; unique node IDs. Standard components reject HTML, JS, URLs, styles and callbacks. The sandbox component below is the explicit exception; unlisted fields are always rejected.
-Freeform canvas: {id,type:"sandbox",title,html,css?:string,script?:string,height?:160..1000,fallback,stateKeys?:string[],dataKeys?:string[],derivedKeys?:string[]}. Use it for custom SVG diagrams, animation, simulations and bespoke interfaces that fixed components cannot express. HTML is a body fragment. Put CSS in css and ALL JavaScript in script (not inline handlers, script tags or remote imports). Inline SVG is supported. Each source field allows up to 49152 characters; the total document remains 128KiB. The iframe has no same-origin privilege, remote resources/network APIs are blocked by CSP, and no host tools are exposed. Never put credentials or private unrelated data in a canvas. It is browser origin isolation, not a CPU/memory hard sandbox.
-Canvas API: window.DSHUI.snapshot -> {state,data,derived,disabled,theme,visible}; DSHUI.animate(fn) returns cleanup and calls fn({time,delta,reducedMotion,visible}), time/delta in seconds, delta capped at 0.05. It pauses offscreen/background and supplies a static delta=0 callback for reduced motion; integrate delta for pause/resume without jumps. DSHUI.subscribe(snapshot=>{...}) immediately supplies current selected values and returns unsubscribe; DSHUI.setState({key:value,...}) requests an atomic Host-validated update of declared stateKeys. Use bare dictionary keys in stateKeys/dataKeys/derivedKeys. Only declared keys are exposed; state types/ranges/options remain enforced. Subscribe to drive DOM/SVG from host state; do not send the same state back from subscribe (feedback loop). Native controls and canvas share the saved state. Local animation may use requestAnimationFrame without saving every frame. No Agent/tool action API in this release. theme exposes bg,soft,ink,muted,line,accent,scheme; CSS variables --canvas-bg/soft/ink/muted/line/accent update automatically. Honor reduced motion, provide accessible labels and responsive layout. Canvas scripts activate only after successful tool commit and state restoration; previews show a placeholder. Use a complete useful fallback per canvas. Code or reset changes restart the frame, state changes do not. All transient internal animation state is reset on reload; declare important parameters in document.state.
-state: key -> {type:"number",default,min,max,step} or {type:"string",default,options?:scalar[]} or {type:"boolean",default} or {type:"json",default:array/object} (canvas structured state, max16KiB per value). select requires scalar options. Numeric defaults follow step from min.
-derived: key -> expression: {const:scalar}, {ref:"state.key"|"data.key"|"derived.key"}, or {op,args:expression[]}. Allowed ops add,mul,min,max (1..8 args); sub,div,eq,neq,lt,lte,gt,gte (2); round,abs (1); if (3, boolean condition). No cycles. Arithmetic requires finite numbers: add does NOT concatenate strings. For formatted labels use a metric's label/unit/decimals, or format text inside a sandbox; omit unused derived fields. if can return strings: {op:"if",args:[{op:"gt",args:[{ref:"derived.weightGiB"},{const:20}]},{const:"超过理论预算"},{const:"在理论预算内"}]} -> bind a text node to this derived result. No separate conditional-rendering field is needed.
-Text/metric values are literal scalars or {ref:...}. Table/chart rows accept inline arrays of objects, {ref:"data.rows"}, {ref:"derived.rows"}, or the shorthand string "data.rows"/"derived.rows". Table label is an optional caption. Static table example: data:{rows:[{name:"A",note:"示例"}]}, node:{id:"t",type:"table",rows:{ref:"data.rows"},columns:[{key:"name",label:"方案"},{key:"note",label:"说明"}]}. Dynamic rows: a derived root may be {map:{source:"data.samples",fields:{contextK:{op:"mul",args:[{ref:"state.contextK"},{ref:"item.fraction"}]},value:{ref:"derived.total"}}}}. source must be the string "data.samples", not an inline array; declare those object rows in document.data.samples. Internal field keys support Chinese identifiers such as 功率 and ASCII identifiers such as powerW; spaces/dots/hyphens belong in display labels. item.key is available only inside map fields. Each field is a normal scalar expression. No nested maps/callbacks; 1..16 fields, max500 generated rows across all maps; normal expression and calculation budgets apply. Derived output max128KiB. DSHUI.formatNumber(value, decimals=2) formats finite numbers with 0..6 decimal places and comma grouping, exactly matching native metrics and fallback; use it for shared readouts instead of mixing toFixed rounding. Use this for live charts/tables, never model calls on slider changes.
-Registered component fields (some optional; required values and types follow the rules above/below): ${componentGuide()}. Controls bind "state.key"; slider numeric, toggle boolean, select requires state options. Metric decimals 0..6. Table columns: [{key,label,unit?}]. Chart kind bar/line, finite numeric values, rows as a data/derived binding; line xScale linear positions numeric labelKey samples by their actual coordinate, category uses equal spacing. Use ascending samples for a curve.
-actions: key -> {type:"agent.followup",intent:string,stateKeys:string[]}. Button submits current selected parameters as a new conversation request; it does not perform a host action itself. All host actions still use ordinary DSH permissions.
-Presentation: heading/text/card/metric accept optional tone (${UI_TONES.join(', ')}); heading/text/card/metric/button accept optional icon (${UI_ICONS.join(', ')}). Fixed tokens only, no SVG/HTML/CSS/color strings. Defaults already include icons and themed spacing. Use accent for primary information, warning for assumptions/caveats, success/danger only for explicitly established facts. Tones are static, not conditional; use derived string text to report changing verdicts. Use row for 2-3 related metrics, card for a meaningful section, avoid repeated headings and deep decorative nesting. Do not use color as the only explanation.
-Always include a useful fallback, units, assumptions and data provenance in visible text. No invented measurements. Use local derived values rather than requesting inference on slider changes.
-Limits: 128KiB document, 160 nodes, 12 node nesting levels, 64 state/derived/data/action keys, 128 expression nodes, 4096 calculation steps, 8192 characters/string. Charts include an accessible data table. Unknown fields/components are rejected.`;
-export const calculatorExample = {
-  version: 1, title: '理论权重体积计算器',
-  fallback: '27B 参数、4 bit 时纯权重理论体积约 12.57 GiB。这是理论估算，不是实测文件大小或运行显存；不含量化元数据、混合精度层、KV cache 和运行缓冲区。',
-  state: { parametersB: { type: 'number', default: 27, min: 1, max: 200, step: 1 }, bits: { type: 'number', default: 4, min: 2, max: 16, step: 1 } },
-  data: {},
-  derived: { weightGiB: { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.parametersB' }, { const: 1000000000 }, { ref: 'state.bits' }] }, { const: 8589934592 }] } },
-  nodes: [
-    { id: 'parameters', type: 'input', label: '参数量 B（十亿）', bind: 'state.parametersB' },
-    { id: 'bits', type: 'slider', label: '假设有效位宽 bit', bind: 'state.bits' },
-    { id: 'weight', type: 'metric', label: '纯权重理论体积', value: { ref: 'derived.weightGiB' }, unit: 'GiB', decimals: 2, icon: 'database', tone: 'accent' },
-    { id: 'note', type: 'text', text: '理论估算，不是实际 GGUF 大小或推理显存。', tone: 'warning' },
-    { id: 'followup', type: 'button', text: '按当前参数继续分析', action: 'analyze' }
-  ],
-  actions: { analyze: { type: 'agent.followup', intent: '分析当前参数下的量化选择，区分理论权重体积与真实运行开销；缺少信息时说明不确定性。', stateKeys: ['parametersB', 'bits'] } }
-};
-export const comparisonExample = {
-  version: 1, title: '示例数据比较', fallback: '仅用于演示：A 为 12，B 为 18，C 为 15；不是实测性能。',
-  data: { results: [{ name: 'A', value: 12 }, { name: 'B', value: 18 }, { name: 'C', value: 15 }] },
-  nodes: [
-    { id: 'note', type: 'text', text: '以下为演示数据，不是实测性能。', tone: 'warning' },
-    { id: 'chart', type: 'chart', kind: 'bar', rows: { ref: 'data.results' }, labelKey: 'name', valueKey: 'value', label: '示例分数', unit: '分' },
-    { id: 'table', type: 'table', rows: { ref: 'data.results' }, columns: [{ key: 'name', label: '方案' }, { key: 'value', label: '示例分数', unit: '分' }] }
-  ]
-};
-export const budgetExample = {
-  ...calculatorExample, title: '理论权重预算比较',
-  fallback: '这是纯权重理论预算比较，不包含实际推理运行开销。默认 27B、4 bit、20 GiB 理论预算，权重约 12.57 GiB。',
-  state: { ...calculatorExample.state, budgetGiB: { type: 'number', default: 20, min: 1, max: 96, step: 1 } },
-  derived: { ...calculatorExample.derived,
-    verdict: { op: 'if', args: [{ op: 'gt', args: [{ ref: 'derived.weightGiB' }, { ref: 'state.budgetGiB' }] }, { const: '超过纯权重理论预算；请降低位宽或提高预算。' }, { const: '在纯权重理论预算内；仍需另计运行开销。' }] }
-  },
-  nodes: [
-    { id: 'assumptions', type: 'text', tone: 'warning', text: '以下均为理论估算，不能直接据此判断模型能否在显卡上运行。' },
-    { id: 'settings', type: 'card', title: '调整参数', icon: 'sliders', children: [calculatorExample.nodes[0], calculatorExample.nodes[1], { id: 'budget', type: 'slider', label: '纯权重理论预算 GiB', bind: 'state.budgetGiB' }] },
-    { id: 'results', type: 'row', children: [calculatorExample.nodes[2], { id: 'budgetMetric', type: 'metric', label: '理论预算', icon: 'target', tone: 'neutral', value: { ref: 'state.budgetGiB' }, unit: 'GiB', decimals: 0 }] },
-    { id: 'verdictText', type: 'text', icon: 'info', text: { ref: 'derived.verdict' } }
-  ], actions: {}
-};
-export const curveExample = {
-  version: 1, title: '上下文与理论内存曲线',
-  fallback: '理论估算，只计算纯权重与 KV cache，不包含运行缓冲、量化元数据或多卡分配。默认 27B、4.25 bpw、32K 上下文、48 KiB/token KV，权重约 13.36 GiB，权重加 KV 约 14.86 GiB。',
-  state: {
-    parametersB: { type: 'number', default: 27, min: 1, max: 200, step: 1 },
-    bits: { type: 'number', default: 4.25, min: 2, max: 8, step: 0.25 },
-    contextK: { type: 'number', default: 32, min: 8, max: 128, step: 8 },
-    kvKib: { type: 'number', default: 48, min: 8, max: 192, step: 8 }
-  },
-  data: { samples: [{ fraction: 0.25 }, { fraction: 0.5 }, { fraction: 0.75 }, { fraction: 1 }] },
-  derived: {
-    weightGiB: calculatorExample.derived.weightGiB,
-    totalGiB: { op: 'add', args: [{ ref: 'derived.weightGiB' }, { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'state.kvKib' }] }, { const: 1024 }] }] },
-    curve: { map: { source: 'data.samples', fields: {
-      contextK: { op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'item.fraction' }] },
-      totalGiB: { op: 'add', args: [{ ref: 'derived.weightGiB' }, { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'item.fraction' }, { ref: 'state.kvKib' }] }, { const: 1024 }] }] }
-    } } }
-  },
-  nodes: [
-    { id: 'note', type: 'text', tone: 'warning', text: '理论值，不是实测推理显存。仅计纯权重 + KV cache，不含运行缓冲、量化元数据或多卡分配。' },
-    { id: 'controls', type: 'card', title: '参数调整', icon: 'sliders', children: [
-      calculatorExample.nodes[0], calculatorExample.nodes[1],
-      { id: 'context', type: 'slider', label: '最大上下文 K tokens', bind: 'state.contextK' },
-      { id: 'kv', type: 'slider', label: '每 token KV 开销 KiB', bind: 'state.kvKib' }
-    ] },
-    { id: 'metric', type: 'metric', label: '最大上下文下的理论权重 + KV', icon: 'database', value: { ref: 'derived.totalGiB' }, unit: 'GiB', decimals: 2 },
-    { id: 'curveChart', type: 'chart', kind: 'line', xScale: 'linear', label: '上下文 K tokens → 权重 + KV', unit: 'GiB', rows: { ref: 'derived.curve' }, labelKey: 'contextK', valueKey: 'totalGiB' },
-    { id: 'curveTable', type: 'table', rows: { ref: 'derived.curve' }, columns: [{ key: 'contextK', label: '上下文', unit: 'K tokens' }, { key: 'totalGiB', label: '理论内存', unit: 'GiB' }] },
-    { id: 'followup', type: 'button', text: '按当前曲线继续分析', action: 'analyze' }
-  ],
-  actions: { analyze: { type: 'agent.followup', intent: '依据当前参数与 derived.curve 理论曲线分析上下文和内存取舍，说明尚未计入的实际运行开销。', stateKeys: ['parametersB', 'bits', 'contextK', 'kvKib'] } }
-};
+import { UI_ICONS, UI_TONES } from './presentation.js';
+import { componentGuide } from './components.js';
+import { AUTHORING_GUIDE } from './authoring-guide.js';
+import {VISUAL_GUIDE} from './visual.js';
+export { sceneExamples } from './scenes.js';
+export { bicycleExample, oscillatorExample } from './canvas-example.js';
+export const PROTOCOL_GUIDE = VISUAL_GUIDE+'\n\n'+AUTHORING_GUIDE+`\n\nDSH UI v1. Call render_ui({document: ...}) directly when visualization helps. Do not call it inside run_code/PTC in this version.
+Formula shorthand: {expr:"state.V * state.V / state.R"} compiles to the same validated interpreter. Supports explicit state.x/data.x/derived.x/item.x references, + - * /, == != < <= > >=, parentheses, condition ? yes : no, min/max/round/ceil/floor/abs, double-quoted strings and booleans. Use it in derived, node text/value/max/rows or map.fields. No arbitrary functions, property chains, statements or side effects; complex animation belongs in render_canvas. Example derived:{power:{expr:"state.V * state.V / state.R"}}, metric.value:{ref:"derived.power"}.
+Document: {version:1,title:string,fallback:string,presentation?:{layout,accent,density,preset},state?:{},data?:{},derived?:{},nodes:[],actions?:{}}.
+Scene layouts: dashboard (metrics/trends), workbench (parameter controls/results), comparison (parallel choice cards), guide (ordered instructions), status (observed task snapshot), report (reading and evidence). Accent: blue/teal/violet/amber/rose; density: comfortable/compact. Omit to keep the standard design. Choose based on the task, not at random. Card surface: outline/soft/featured. Featured indicates discussion focus, not an automatic recommendation.
+Additional nodes: badge {id,type,text,icon?,tone?}; progress {id,type,label,value,max,unit?,icon?,tone?} where values may be bindings and 0 <= value <= positive max; steps {id,type,items:[{title,description?,status?:"pending"|"active"|"done"|"error"}]} (direct array of 1..12 items, not {item:[...]}; omit status for static guides); details {id,type,title,children,open?:boolean,icon?,tone?}. Progress and steps are declared snapshots, not a live host task subscription. Only claim real progress/completion from actual tool evidence; mark demo data visibly. Details keeps the content available in text fallback.
+Display lifecycle: submit native render_text/render_ui/render_canvas directly. Several independent UI documents may be created in one answer. Complete validated native blocks appear progressively as read-only previews. Keep previews visible through later reasoning and text; durable turn/end activates controls and scripts. Incomplete/failed tools never become interactive. Use small meaningful documents; no separate ui.begin/append calls.
+All IDs and dictionary keys: Unicode letters (including Chinese) or underscore, followed by letters/marks/digits/underscore, max64; unique node IDs. Standard components reject HTML, JS, arbitrary styles and callbacks. link/button href explicitly supports http/https URLs; path uses the host file opener on user click. The sandbox component below is the explicit exception; unlisted fields are always rejected.
+Freeform canvas: {id,type:"sandbox",title,html,css?:string,script?:string,height?:160..1000,fallback,stateKeys?:string[],dataKeys?:string[],derivedKeys?:string[],libraries?:["mechanism"]}. For internal assemblies and mechanical relations, ui_catalog topic=mechanism provides an opt-in local drawing/kinematics helper and three complete examples (assembly/gears/crank). Use it for custom SVG diagrams, animation, simulations and bespoke interfaces that fixed components cannot express. HTML is a body fragment. Put CSS in css and ALL JavaScript in script (not inline handlers, script tags or remote imports). Inline SVG is supported. Each source field allows up to 49152 characters; the total document remains 128KiB. The iframe has no same-origin privilege, remote resources/network APIs are blocked by CSP, and no host tools are exposed. Never put credentials or private unrelated data in a canvas. It is browser origin isolation, not a CPU/memory hard sandbox.
+Canvas API: window.DSHUI.snapshot -> {state,data,derived,disabled,theme,visible}; DSHUI.animate(fn) returns cleanup and calls fn({time,delta,reducedMotion,visible}), time/delta in seconds, delta capped at 0.05. It pauses offscreen/background and supplies a static delta=0 callback for reduced motion; integrate delta for pause/resume without jumps. DSHUI.subscribe(snapshot=>{...}) immediately supplies current selected values and returns unsubscribe; DSHUI.setState({key:value,...}) requests an atomic Host-validated update of declared stateKeys. Use bare dictionary keys in stateKeys/dataKeys/derivedKeys. Only declared keys are exposed; state types/ranges/options remain enforced. Subscribe to drive DOM/SVG from host state; do not send the same state back from subscribe (feedback loop). Native controls and canvas share the saved state. Local animation may use requestAnimationFrame without saving every frame. No Agent/tool action API in this release. theme exposes bg,soft,ink,muted,line,accent,scheme; CSS variables --canvas-bg/soft/ink/muted/line/accent update automatically. Honor reduced motion, provide accessible labels and responsive layout. Canvas scripts activate only after successful tool commit and state restoration; previews show inert completed HTML/CSS. Use a complete useful fallback per canvas. Code or reset changes restart the frame, state changes do not. All transient internal animation state is reset on reload; declare important parameters in document.state.
+state: key -> {type:"number",default,min,max,step} or {type:"string",default,options?:scalar[]} or {type:"boolean",default} or {type:"json",default:array/object} (canvas structured state, max16KiB per value). select requires scalar options. Numeric defaults follow step from min.
+derived: key -> expression: {const:scalar}, {ref:"state.key"|"data.key"|"derived.key"}, or {op,args:expression[]}. Allowed ops add,mul,min,max (1..8 args); sub,div,eq,neq,lt,lte,gt,gte (2); round,ceil,floor,abs (1); if (3, boolean condition). No cycles. Arithmetic requires finite numbers: add does NOT concatenate strings. For formatted labels use a metric's label/unit/decimals, or format text inside a sandbox; omit unused derived fields. if can return strings: {op:"if",args:[{op:"gt",args:[{ref:"derived.weightGiB"},{const:20}]},{const:"超过理论预算"},{const:"在理论预算内"}]} -> bind a text node to this derived result. No separate conditional-rendering field is needed.
+Text/metric values are literal scalars or {ref:...}. Table/chart rows accept inline arrays of objects, {ref:"data.rows"}, {ref:"derived.rows"}, or the shorthand string "data.rows"/"derived.rows". Table label is an optional caption. Static table example: data:{rows:[{name:"A",note:"示例"}]}, node:{id:"t",type:"table",rows:{ref:"data.rows"},columns:[{key:"name",label:"方案"},{key:"note",label:"说明"}]}. For a short live breakdown prefer inline formula cells: rows:[{label:"餐饮",value:{ref:"derived.mealTotal"}},{label:"住宿",value:{expr:"ceil(state.people / 2) * state.room"}}], labelKey:"label",valueKey:"value". These cells recalculate locally; data remains literal and never executes formulas. Dynamic rows for many samples: a derived root may be {map:{source:"data.samples",fields:{contextK:{op:"mul",args:[{ref:"state.contextK"},{ref:"item.fraction"}]},value:{ref:"derived.total"}}}}. source must be the string "data.samples", not an inline array; declare those object rows in document.data.samples. Internal field keys support Chinese identifiers such as 功率 and ASCII identifiers such as powerW; spaces/dots/hyphens belong in display labels. item.key is available only inside map fields. Each field is a normal scalar expression. No nested maps/callbacks; 1..16 fields, max500 generated rows across all maps; normal expression and calculation budgets apply. Derived output max128KiB. DSHUI.formatNumber(value, decimals=2) formats finite numbers with 0..6 decimal places and comma grouping, exactly matching native metrics and fallback; use it for shared readouts instead of mixing toFixed rounding. Use this for live charts/tables, never model calls on slider changes.
+Registered component fields (some optional; required values and types follow the rules above/below): ${componentGuide()}. Controls bind "state.key"; slider numeric, toggle boolean, select requires state options. Metric decimals 0..6. Table columns: [{key,label,unit?}]. Chart kind bar/line, finite numeric values, rows as a data/derived binding; line xScale linear positions numeric labelKey samples by their actual coordinate, category uses equal spacing. Use ascending samples for a curve.
+actions: key -> {type:"agent.followup",intent:string,stateKeys:string[]}. Button submits current selected parameters as a new conversation request; it does not perform a host action itself. All host actions still use ordinary DSH permissions.
+Presentation: heading/text/card/metric accept optional tone (${UI_TONES.join(', ')}); heading/text/card/metric/button accept optional icon (${UI_ICONS.join(', ')}). Fixed tokens only, no SVG/HTML/CSS/color strings. Defaults already include icons and themed spacing. Use accent for primary information, warning for assumptions/caveats, success/danger only for explicitly established facts. Tones are static, not conditional; use derived string text to report changing verdicts. Use row for 2-3 related metrics, card for a meaningful section, avoid repeated headings and deep decorative nesting. Do not use color as the only explanation.
+Always include a useful fallback, units, assumptions and data provenance in visible text. No invented measurements. Use local derived values rather than requesting inference on slider changes.
+Limits: 128KiB document, 160 nodes, 12 node nesting levels, 64 state/derived/data/action keys, 128 expression nodes, 4096 calculation steps, 8192 characters/string. Charts include an accessible data table. Unknown fields/components are rejected.`;
+export const calculatorExample = {
+  version: 1, title: '理论权重体积计算器',
+  fallback: '27B 参数、4 bit 时纯权重理论体积约 12.57 GiB。这是理论估算，不是实测文件大小或运行显存；不含量化元数据、混合精度层、KV cache 和运行缓冲区。',
+  state: { parametersB: { type: 'number', default: 27, min: 1, max: 200, step: 1 }, bits: { type: 'number', default: 4, min: 2, max: 16, step: 1 } },
+  data: {},
+  derived: { weightGiB: { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.parametersB' }, { const: 1000000000 }, { ref: 'state.bits' }] }, { const: 8589934592 }] } },
+  nodes: [
+    { id: 'parameters', type: 'input', label: '参数量 B（十亿）', bind: 'state.parametersB' },
+    { id: 'bits', type: 'slider', label: '假设有效位宽 bit', bind: 'state.bits' },
+    { id: 'weight', type: 'metric', label: '纯权重理论体积', value: { ref: 'derived.weightGiB' }, unit: 'GiB', decimals: 2, icon: 'database', tone: 'accent' },
+    { id: 'note', type: 'text', text: '理论估算，不是实际 GGUF 大小或推理显存。', tone: 'warning' },
+    { id: 'followup', type: 'button', text: '按当前参数继续分析', action: 'analyze' }
+  ],
+  actions: { analyze: { type: 'agent.followup', intent: '分析当前参数下的量化选择，区分理论权重体积与真实运行开销；缺少信息时说明不确定性。', stateKeys: ['parametersB', 'bits'] } }
+};
+export const comparisonExample = {
+  version: 1, title: '示例数据比较', fallback: '仅用于演示：A 为 12，B 为 18，C 为 15；不是实测性能。',
+  data: { results: [{ name: 'A', value: 12 }, { name: 'B', value: 18 }, { name: 'C', value: 15 }] },
+  nodes: [
+    { id: 'note', type: 'text', text: '以下为演示数据，不是实测性能。', tone: 'warning' },
+    { id: 'chart', type: 'chart', kind: 'bar', rows: { ref: 'data.results' }, labelKey: 'name', valueKey: 'value', label: '示例分数', unit: '分' },
+    { id: 'table', type: 'table', rows: { ref: 'data.results' }, columns: [{ key: 'name', label: '方案' }, { key: 'value', label: '示例分数', unit: '分' }] }
+  ]
+};
+export const budgetExample = {
+  ...calculatorExample, title: '理论权重预算比较',
+  fallback: '这是纯权重理论预算比较，不包含实际推理运行开销。默认 27B、4 bit、20 GiB 理论预算，权重约 12.57 GiB。',
+  state: { ...calculatorExample.state, budgetGiB: { type: 'number', default: 20, min: 1, max: 96, step: 1 } },
+  derived: { ...calculatorExample.derived,
+    verdict: { op: 'if', args: [{ op: 'gt', args: [{ ref: 'derived.weightGiB' }, { ref: 'state.budgetGiB' }] }, { const: '超过纯权重理论预算；请降低位宽或提高预算。' }, { const: '在纯权重理论预算内；仍需另计运行开销。' }] }
+  },
+  nodes: [
+    { id: 'assumptions', type: 'text', tone: 'warning', text: '以下均为理论估算，不能直接据此判断模型能否在显卡上运行。' },
+    { id: 'settings', type: 'card', title: '调整参数', icon: 'sliders', children: [calculatorExample.nodes[0], calculatorExample.nodes[1], { id: 'budget', type: 'slider', label: '纯权重理论预算 GiB', bind: 'state.budgetGiB' }] },
+    { id: 'results', type: 'row', children: [calculatorExample.nodes[2], { id: 'budgetMetric', type: 'metric', label: '理论预算', icon: 'target', tone: 'neutral', value: { ref: 'state.budgetGiB' }, unit: 'GiB', decimals: 0 }] },
+    { id: 'verdictText', type: 'text', icon: 'info', text: { ref: 'derived.verdict' } }
+  ], actions: {}
+};
+export const curveExample = {
+  version: 1, title: '上下文与理论内存曲线',
+  fallback: '理论估算，只计算纯权重与 KV cache，不包含运行缓冲、量化元数据或多卡分配。默认 27B、4.25 bpw、32K 上下文、48 KiB/token KV，权重约 13.36 GiB，权重加 KV 约 14.86 GiB。',
+  state: {
+    parametersB: { type: 'number', default: 27, min: 1, max: 200, step: 1 },
+    bits: { type: 'number', default: 4.25, min: 2, max: 8, step: 0.25 },
+    contextK: { type: 'number', default: 32, min: 8, max: 128, step: 8 },
+    kvKib: { type: 'number', default: 48, min: 8, max: 192, step: 8 }
+  },
+  data: { samples: [{ fraction: 0.25 }, { fraction: 0.5 }, { fraction: 0.75 }, { fraction: 1 }] },
+  derived: {
+    weightGiB: calculatorExample.derived.weightGiB,
+    totalGiB: { op: 'add', args: [{ ref: 'derived.weightGiB' }, { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'state.kvKib' }] }, { const: 1024 }] }] },
+    curve: { map: { source: 'data.samples', fields: {
+      contextK: { op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'item.fraction' }] },
+      totalGiB: { op: 'add', args: [{ ref: 'derived.weightGiB' }, { op: 'div', args: [{ op: 'mul', args: [{ ref: 'state.contextK' }, { ref: 'item.fraction' }, { ref: 'state.kvKib' }] }, { const: 1024 }] }] }
+    } } }
+  },
+  nodes: [
+    { id: 'note', type: 'text', tone: 'warning', text: '理论值，不是实测推理显存。仅计纯权重 + KV cache，不含运行缓冲、量化元数据或多卡分配。' },
+    { id: 'controls', type: 'card', title: '参数调整', icon: 'sliders', children: [
+      calculatorExample.nodes[0], calculatorExample.nodes[1],
+      { id: 'context', type: 'slider', label: '最大上下文 K tokens', bind: 'state.contextK' },
+      { id: 'kv', type: 'slider', label: '每 token KV 开销 KiB', bind: 'state.kvKib' }
+    ] },
+    { id: 'metric', type: 'metric', label: '最大上下文下的理论权重 + KV', icon: 'database', value: { ref: 'derived.totalGiB' }, unit: 'GiB', decimals: 2 },
+    { id: 'curveChart', type: 'chart', kind: 'line', xScale: 'linear', label: '上下文 K tokens → 权重 + KV', unit: 'GiB', rows: { ref: 'derived.curve' }, labelKey: 'contextK', valueKey: 'totalGiB' },
+    { id: 'curveTable', type: 'table', rows: { ref: 'derived.curve' }, columns: [{ key: 'contextK', label: '上下文', unit: 'K tokens' }, { key: 'totalGiB', label: '理论内存', unit: 'GiB' }] },
+    { id: 'followup', type: 'button', text: '按当前曲线继续分析', action: 'analyze' }
+  ],
+  actions: { analyze: { type: 'agent.followup', intent: '依据当前参数与 derived.curve 理论曲线分析上下文和内存取舍，说明尚未计入的实际运行开销。', stateKeys: ['parametersB', 'bits', 'contextK', 'kvKib'] } }
+};
+
 

package/lib/components.js

@@ -1,20 +1,25 @@
 // Shared attribute vocabulary for validation and model-facing capability discovery.
 const define = (fields, purpose, presentation = '') => Object.freeze({ fields: Object.freeze(fields), purpose, presentation });
 export const COMPONENTS = Object.freeze({
-  heading: define(['text'], 'Section heading', 'tone'), text: define(['text'], 'Readable explanation or bound text', 'tone'),
-  row: define(['children'], 'Wrapping parallel content'), column: define(['children'], 'Ordered vertical content'),
+  visual: define(['spec','stateKey','warnings'], 'Extended native charts, tables, plots, quiz, forms, diagrams, media and 3D'),
+  heading: define(['text','spans','size','weight','color','align','lineHeight'], 'Section heading', 'tone'), text: define(['text','spans','size','weight','color','align','lineHeight','copyable','title'], 'Readable explanation; copyable:true adds a reusable text panel', 'tone'),
+  code: define(['code','lang','title','wrap'], 'Literal copyable code; displayed only, never executed'),
+  callout: define(['text','spans','size','weight','color','align','lineHeight'], 'A short emphasized paragraph', 'tone'),
+  row: define(['children','columns','gap'], 'Wrapping parallel content'), column: define(['children','gap'], 'Ordered vertical content'),
   card: define(['title', 'children', 'surface'], 'Meaningful grouped section', 'tone'),
   details: define(['title', 'children', 'open'], 'Collapsible supporting content', 'tone'),
   badge: define(['text'], 'Short explicit status label', 'tone'),
   progress: define(['label', 'value', 'max', 'unit'], 'Declared numeric progress snapshot', 'tone'),
-  steps: define(['items'], 'Ordered declared steps'),
+  steps: define(['title','items'], 'Ordered declared steps with an optional heading'),
   metric: define(['label', 'value', 'unit', 'decimals'], 'Number with units, or a literal/bound status string', 'tone'),
   input: define(['label', 'bind'], 'String or numeric state input'), slider: define(['label', 'bind'], 'Numeric state control'),
-  select: define(['label', 'bind'], 'Selection from declared state options'), toggle: define(['label', 'bind'], 'Boolean state control'),
-  button: define(['text', 'action'], 'Declared Agent follow-up', 'icon'),
+  select: define(['label', 'bind','variant'], 'Selection from declared state options; variant:segmented for 2..8 short options, dropdown otherwise'), toggle: define(['label', 'bind'], 'Boolean state control'),
+  button: define(['text', 'action','href','path','variant'], 'Agent follow-up, web link or host file opener', 'icon'),
+  link: define(['text','href','path','variant'], 'User-clicked webpage or local file button', 'icon'),
+  divider: define(['label'], 'Quiet section divider'),
   table: define(['label', 'rows', 'columns'], 'Supplied or derived values; inline rows or data/derived reference'),
   chart: define(['kind', 'rows', 'labelKey', 'valueKey', 'label', 'unit', 'xScale'], 'Bar/line comparison with accessible data'),
-  sandbox: define(['title', 'html', 'css', 'script', 'fallback', 'height', 'stateKeys', 'dataKeys', 'derivedKeys'], 'Freeform isolated HTML/SVG/CSS/JavaScript visualization')
+  sandbox: define(['title', 'html', 'css', 'script', 'fallback', 'height', 'libraries', 'stateKeys', 'dataKeys', 'derivedKeys'], 'Freeform isolated HTML/SVG/CSS/JavaScript visualization')
 });
 export function componentFields(type) {
   const c = Object.hasOwn(COMPONENTS, type) ? COMPONENTS[type] : undefined;

package/lib/delivery.js

@@ -0,0 +1,18 @@
+import {validateDocument} from './protocol.js';
+import {repairFenceJson} from './visual-guard.js';
+export function deliveryDiagnostics(document){
+ const diagnostics=[];
+ const walk=nodes=>{for(const node of nodes){if(node.type==='visual')for(const message of node.warnings??[])diagnostics.push({severity:'warning',path:node.id,message});if(node.children)walk(node.children)}};walk(document.nodes);
+ return diagnostics;
+}
+export function diagnoseDelivery(input){
+ try{const document=validateDocument(input),diagnostics=deliveryDiagnostics(document);return {valid:true,complete:diagnostics.length===0,document,diagnostics}}catch(e){return {valid:false,complete:false,diagnostics:[{severity:'error',path:'document',message:e.message}]}}
+}
+export function resolveSourceFence(raw,{svg=false}={}){
+ if(typeof raw!=='string'||raw.length>131072)return {valid:false,complete:false,diagnostics:[{severity:'error',path:'source',message:'Source exceeds 128 KiB'}]};
+ if(/^[a-f\d]{8}-[a-f\d-]{27,}$/i.test(raw.trim()))return {marker:true};
+ if(svg)return diagnoseDelivery({items:[{type:'svg',title:'SVG',code:raw}]});
+ let value,repair;
+ try{value=JSON.parse(raw)}catch(e){repair=repairFenceJson(raw);if(!repair)return {valid:false,complete:false,diagnostics:[{severity:'error',path:'source',message:'Invalid JSON: '+e.message.slice(0,240)}]};value=JSON.parse(repair.text)}
+ const result=diagnoseDelivery(value);if(repair&&result.valid)result.repairs=repair.repairs;return result;
+}

package/lib/diagnostics-route.js

@@ -0,0 +1,6 @@
+import {stat} from 'node:fs/promises';
+import {BUILD_INFO} from './build-info.js';
+export function diagnosticsRoute(feedback){return async()=>{
+ const assets=await Promise.all(['visual.js','visual.css','mermaid.js','echarts-core.js','echarts-full.js','three.js','standalone-runtime.js','katex.css'].map(async name=>{try{const s=await stat(new URL('./assets/'+name,import.meta.url));return {name,available:s.isFile()&&s.size>0,bytes:s.size}}catch{return {name,available:false}}}));
+ return Response.json({build:BUILD_INFO,hostActive:true,feedbackHookRegistered:feedback.available,assets,assetRoute:'/api/plugins/dsh-generative-ui/assets/',permissions:'unchanged',checkedAt:new Date().toISOString()},{headers:{'Cache-Control':'no-store'}});
+}}

package/lib/document-update.js

@@ -0,0 +1,27 @@
+import {validateDocument} from './protocol.js';
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+function merge(a={},b={},label){const result={...a};for(const[k,v]of Object.entries(b)){if(Object.hasOwn(result,k)&&!same(result[k],v))throw Error('DSH UI: update cannot redefine '+label+'.'+k+'; preserve existing input/calculation definitions');result[k]=v}return result}
+export function updateDocument(current,{mode,targetId,document}){
+ if(!['append','replace'].includes(mode))throw Error('DSH UI: mode must be append or replace');
+ const incoming=validateDocument(document),next=structuredClone(current);
+ const find=(list,id)=>{for(const[n,node]of list.entries()){if(node.id===id)return {list,index:n,node};const child=node.children&&find(node.children,id);if(child)return child}};
+ const singleVisualAppend=!targetId&&mode==='append'&&next.nodes.length===1&&next.nodes[0].type==='visual'&&incoming.nodes.length===1&&incoming.nodes[0].type==='visual';
+ const target=targetId?find(next.nodes,targetId):singleVisualAppend?{list:next.nodes,index:0,node:next.nodes[0]}:null;if(targetId&&!target)throw Error('DSH UI: targetId must be an existing node ID');
+ // An extended fragment gets a generated state slot. A targeted update keeps
+ // the existing visual's slot rather than introducing an unrelated default.
+ if(target?.node.type==='visual'&&incoming.nodes.length===1&&incoming.nodes[0].type==='visual')delete incoming.state[incoming.nodes[0].stateKey];
+ next.state=merge(next.state,incoming.state,'state');next.derived=merge(next.derived,incoming.derived,'derived');next.data=merge(next.data,incoming.data,'data');next.actions=merge(next.actions,incoming.actions,'actions');
+ if(target?.node.type==='visual'){
+  if(incoming.nodes.length!==1||incoming.nodes[0].type!=='visual')throw Error('DSH UI: visual target requires one extended title/items document');
+  const input=incoming.nodes[0],spec=target.node.spec;
+  target.node.spec=mode==='append'?{...spec,items:[...spec.items,...input.spec.items]}:input.spec;
+  target.node.warnings=input.warnings??[];
+ }else if(target){
+  if(mode==='append'){if(!Array.isArray(target.node.children))throw Error('DSH UI: append target needs children or a visual spec');target.node.children.push(...incoming.nodes)}
+  else {if(incoming.nodes.length!==1)throw Error('DSH UI: targeted replace needs exactly one node');target.list[target.index]={...incoming.nodes[0],id:target.node.id}}
+ }else if(mode==='append')next.nodes.push(...incoming.nodes);
+ else {next.nodes=incoming.nodes;next.title=incoming.title;next.fallback=incoming.fallback;if(incoming.presentation!==undefined)next.presentation=incoming.presentation;else delete next.presentation}
+ // Existing state keys remain available even after replacing display nodes.
+ // New controls receive defaults; stored values are migrated by the store.
+ return validateDocument(next);
+}