dsh-motion-ui 0.5.3 → 0.5.5

package/lib/protocol.js

@@ -3,11 +3,11 @@ import { SANDBOX_LIMITS } from './sandbox.js';
 import { COMPONENTS, componentFields } from './components.js';
 import { formatNumber } from './format-number.js';
 import { expandExpressions } from './author-expression.js';
+import { validIdentifier as key } from './identifiers.js';
 export const LIMITS = Object.freeze({ bytes: 131072, nodes: 160, depth: 12, rows: 500, expressions: 128, steps: 4096 });
 const own = (o, k) => Object.hasOwn(o, k);
 const fail = message => { throw new Error(`DSH UI: ${message}`); };
 const object = x => x !== null && typeof x === 'object' && !Array.isArray(x);
-const key = x => typeof x === 'string' && /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(x) && !['constructor', 'prototype', '__proto__'].includes(x);
 const finite = x => typeof x === 'number' && Number.isFinite(x);
 const scalar = x => typeof x === 'string' || typeof x === 'boolean' || finite(x);
 const text = (x, at) => { if (typeof x !== 'string' || x.length > 8192) fail(`${at} must be a string of at most 8192 characters`); };
@@ -41,6 +41,10 @@ export function validateState(doc, state) {
       if (!finite(v) || v < s.min || v > s.max) fail(`state.${k} is outside its numeric range`);
       const offset = (v - s.min) / s.step;
       if (Math.abs(offset - Math.round(offset)) > 1e-6) fail(`state.${k} does not match its step`);
+    } else if (s.type === 'json') {
+      if (!object(v) && !Array.isArray(v)) fail(`state.${k} must be an array or object for type json`);
+      safeJson(v);
+      if (new TextEncoder().encode(JSON.stringify(v)).length > 16384) fail(`state.${k} JSON exceeds 16 KiB`);
     } else if (s.type === 'string') text(v, `state.${k}`);
     else if (typeof v !== 'boolean') fail(`state.${k} must be boolean`);
     if (s.options && !s.options.includes(v)) fail(`invalid option for state.${k}`);
@@ -50,7 +54,7 @@ export function validateState(doc, state) {
 }
 const ARITY = { add: [1, 8], sub: [2, 2], mul: [1, 8], div: [2, 2], min: [1, 8], max: [1, 8], round: [1, 1], abs: [1, 1], eq: [2, 2], neq: [2, 2], lt: [2, 2], lte: [2, 2], gt: [2, 2], gte: [2, 2], if: [3, 3] };
 function reference(doc, ref) {
-  if (typeof ref !== 'string' || !/^(state|data|derived)\.[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(ref)) fail('invalid reference');
+  if (typeof ref !== 'string' || !['state','data','derived'].includes(ref.split('.')[0]) || ref.split('.').length !== 2 || !key(ref.split('.')[1])) fail(`invalid reference ${JSON.stringify(ref)}; use state.key, data.key or derived.key with a letter/underscore identifier`);
   const [group, k] = ref.split('.');
   if (!own(doc[group], k)) fail(`unknown reference ${ref}`);
   return [group, k];
@@ -118,7 +122,7 @@ function checkViewValues(doc, evaluated) {
       if (n.type === 'chart' && rows.some(r => !own(r, n.labelKey) || !scalar(r[n.labelKey]) || !own(r, n.valueKey) || !finite(r[n.valueKey]))) fail('chart requires labels and finite numeric values');
       if (n.type === 'chart' && n.xScale === 'linear' && rows.some(r => !finite(r[n.labelKey]))) fail('linear chart requires numeric x values');
     }
-    if (n.type === 'metric' && !finite(evaluated.resolveValue(n.value))) fail('metric requires a numeric value');
+    if (n.type === 'metric' && !scalar(evaluated.resolveValue(n.value))) fail(`node.${n.id}.value must resolve to a number, string or boolean; use table for rows or a canvas for structured data`);
     if (n.type === 'progress') {
       const v = evaluated.resolveValue(n.value), max = evaluated.resolveValue(n.max);
       if (!finite(v) || !finite(max) || max <= 0 || v < 0 || v > max) fail('progress requires 0 <= value <= positive max');
@@ -144,11 +148,14 @@ export function validateDocument(input) {
   for (const group of ['state', 'data', 'derived', 'actions']) {
     doc[group] ??= {};
     if (!object(doc[group]) || Object.keys(doc[group]).length > 64) fail(`invalid ${group}`);
-    for (const k of Object.keys(doc[group])) if (!key(k)) fail(`invalid key in ${group}`);
+    for (const k of Object.keys(doc[group])) if (!key(k)) fail(`invalid key in ${group}: ${JSON.stringify(k)}; use 1..64 letters, numbers or underscores, starting with a letter/underscore (Chinese letters supported); no spaces, dots or hyphens. Put display labels in label/text`);
   }
   for (const [k, s] of Object.entries(doc.state)) {
     fields(s, ['type', 'default', 'min', 'max', 'step', 'options'], `state.${k}`);
-    if (!['number', 'string', 'boolean'].includes(s.type)) fail(`unsupported state type ${k}`);
+    // Preserve structured checklist data instead of coercing it to a string.
+    if (s.type === 'string' && (Array.isArray(s.default) || object(s.default)) && !own(s,'options')) s.type = 'json';
+    if (!['number', 'string', 'boolean', 'json'].includes(s.type)) fail(`unsupported state type ${k}; use number, string, boolean or json (arrays/objects)`);
+    if (s.type === 'json' && own(s,'options')) fail(`state.${k}: json state does not support select options; use scalar options or a canvas`);
     if (s.type === 'number') {
       if (![s.min, s.max, s.step].every(finite) || s.min >= s.max || s.step <= 0) fail(`invalid numeric limits for ${k}`);
       if ((s.max - s.min) / s.step > 1e9) fail(`numeric step too small for ${k}`);
@@ -168,7 +175,7 @@ export function validateDocument(input) {
       const [, k] = reference(doc, e.map.source), rows = doc.data[k];
       if (!Array.isArray(rows) || rows.length > LIMITS.rows || !rows.every(object)) fail('map source must be object rows');
       if (!object(e.map.fields) || !Object.keys(e.map.fields).length || Object.keys(e.map.fields).length > 16) fail('map requires 1..16 fields');
-      for (const [k, value] of Object.entries(e.map.fields)) { if (!key(k)) fail(`invalid map field ${JSON.stringify(k).slice(0,100)}; use an ASCII identifier matching [a-zA-Z][a-zA-Z0-9_]{0,63}, such as powerW. Put Chinese display text in column/chart labels, not internal field keys`); validateExpression(value, depth + 1, rows); }
+      for (const [k, value] of Object.entries(e.map.fields)) { if (!key(k)) fail(`invalid map field ${JSON.stringify(k).slice(0,100)}; use a letter/underscore identifier such as powerW or 功率, without spaces, dots or hyphens`); validateExpression(value, depth + 1, rows); }
       return;
     }
     if (own(e, 'const')) { fields(e, ['const'], 'expression'); if (!scalar(e.const)) fail('constant must be scalar'); return; }
@@ -208,6 +215,7 @@ export function validateDocument(input) {
       if (++count > LIMITS.nodes) fail('too many nodes');
       if (!object(n) || !key(n.id) || ids.has(n.id)) fail('node ids must be unique identifiers'); ids.add(n.id);
       if (!Object.hasOwn(COMPONENTS, n.type)) fail('unsupported component ' + n.type);
+      if (['table','chart'].includes(n.type) && typeof n.rows === 'string' && /^(data|derived)\./.test(n.rows)) n.rows={ref:n.rows};
       switch (n.type) {
         case 'sandbox': {
           
@@ -220,16 +228,25 @@ export function validateDocument(input) {
         }
         case 'row': case 'column': break;
         case 'card': if (n.title !== undefined) text(n.title, 'card title'); if (n.surface !== undefined && !UI_SURFACES.includes(n.surface)) fail('unknown card surface'); break;
-        case 'details': text(n.title, 'details title'); if (n.open !== undefined && typeof n.open !== 'boolean') fail('details open must be boolean'); break;
+        case 'details':
+          text(n.title, 'details title');
+          if (n.open === 'true' || n.open === 'false') n.open = n.open === 'true';
+          if (n.open !== undefined && typeof n.open !== 'boolean') fail(`node.${n.id}.open must be boolean true or false`);
+          break;
         case 'badge': value(n.text, 'badge text'); break;
         case 'progress': text(n.label, 'progress label'); value(n.value, 'progress value'); value(n.max, 'progress max'); if (n.unit !== undefined) text(n.unit, 'progress unit'); break;
         case 'steps': {
-          
-          if (!Array.isArray(n.items) || !n.items.length || n.items.length > 12) fail('steps require 1..12 items');
-          for (const item of n.items) {
-            fields(item, ['title', 'description', 'status'], 'step'); text(item.title, 'step title');
-            if (item.description !== undefined) text(item.description, 'step description');
-            if (!['pending', 'active', 'done', 'error'].includes(item.status)) fail('unknown step status');
+          // Some function-call adapters emit an XML-style singular item wrapper.
+          // Unwrap only this exact, lossless shape; never drop sibling fields.
+          if (object(n.items) && Object.keys(n.items).length === 1 && Array.isArray(n.items.item)) n.items = n.items.item;
+          const at = `node.${n.id}.items`;
+          if (!Array.isArray(n.items)) fail(`${at} must be an array of 1..12 step objects, received ${n.items === null ? 'null' : typeof n.items}. Use items:[{"title":"First step","description":"One sentence"}], not items:{item:[...]}. status is optional for a static guide`);
+          if (!n.items.length || n.items.length > 12) fail(`${at} requires 1..12 items; received ${n.items.length}. Split a longer guide into separate steps nodes`);
+          for (const [i, item] of n.items.entries()) {
+            const stepAt = `${at}[${i}]`;
+            fields(item, ['title', 'description', 'status'], stepAt); text(item.title, `${stepAt}.title`);
+            if (item.description !== undefined) text(item.description, `${stepAt}.description`);
+            if (item.status !== undefined && !['pending', 'active', 'done', 'error'].includes(item.status)) fail(`${stepAt}.status must be pending, active, done or error; omit status for a static guide`);
           } break;
         }
         case 'heading': case 'text': value(n.text, 'text'); break;
@@ -240,18 +257,19 @@ export function validateDocument(input) {
           const [, k] = reference(doc, n.bind), spec = doc.state[k];
           if (n.type === 'slider' && spec.type !== 'number') fail('slider requires numeric state');
           if (n.type === 'toggle' && spec.type !== 'boolean') fail('toggle requires boolean state');
+          if (['input','select'].includes(n.type) && spec.type === 'json') fail(`node.${n.id}: structured state requires a sandbox with DSHUI.setState; use separate boolean states and toggle nodes for a native checklist`);
           if (n.type === 'input' && spec.type === 'boolean') fail('use toggle for boolean state');
           if (n.type === 'select' && !spec.options) fail('select requires options'); break;
         }
         case 'button': text(n.text, 'button text'); if (!own(doc.actions, n.action)) fail('unknown action'); break;
         case 'table': {
-          if(Array.isArray(n.rows))fail('table.rows must use {ref:"data.rows"}; move the array into document.data.rows, not inline in the table');
-          value(n.rows, 'table rows');
+          if (n.label !== undefined) text(n.label, 'table label');
+          if (!Array.isArray(n.rows)) value(n.rows, 'table rows');
           if (!Array.isArray(n.columns) || !n.columns.length || n.columns.length > 16) fail('invalid table columns');
           const cols = new Set();
           for (const c of n.columns) { fields(c, ['key', 'label', 'unit'], 'column'); if (!key(c.key) || cols.has(c.key)) fail('invalid or duplicate column key'); cols.add(c.key); text(c.label, 'column label'); if (c.unit !== undefined) text(c.unit, 'column unit'); } break;
         }
-        case 'chart': value(n.rows, 'chart rows'); if (!['bar', 'line'].includes(n.kind) || !key(n.labelKey) || !key(n.valueKey)) fail('invalid chart'); text(n.label, 'chart label'); if (n.unit !== undefined) text(n.unit, 'chart unit'); if (n.xScale !== undefined && (!['category', 'linear'].includes(n.xScale) || n.xScale === 'linear' && n.kind !== 'line')) fail('invalid xScale'); break;
+        case 'chart': if (!Array.isArray(n.rows)) value(n.rows, 'chart rows'); if (!['bar', 'line'].includes(n.kind) || !key(n.labelKey) || !key(n.valueKey)) fail('invalid chart'); text(n.label, 'chart label'); if (n.unit !== undefined) text(n.unit, 'chart unit'); if (n.xScale !== undefined && (!['category', 'linear'].includes(n.xScale) || n.xScale === 'linear' && n.kind !== 'line')) fail('invalid xScale'); break;
         default: fail(`unsupported component ${n.type}`);
       }
       if (['heading', 'text', 'card', 'metric', 'button', 'badge', 'progress', 'details'].includes(n.type)) {
@@ -283,9 +301,9 @@ export function fallbackText(doc) {
     if (n.type === 'sandbox') lines.push(n.title, n.fallback);
     if ((n.type === 'card' || n.type === 'details') && n.title) lines.push(n.title);
     if (n.type === 'progress') lines.push(`${n.label}: ${resolveValue(n.value)} / ${resolveValue(n.max)} ${n.unit ?? ''}`);
-    if (n.type === 'steps') for (const item of n.items) lines.push(`[${item.status}] ${item.title}${item.description ? ': ' + item.description : ''}`);
-    if (n.type === 'metric') lines.push(`${n.label}: ${formatNumber(resolveValue(n.value),n.decimals ?? 2)} ${n.unit ?? ''}`);
-    if (n.type === 'table') { lines.push(n.columns.map(c => c.label + (c.unit ? ` (${c.unit})` : '')).join(' | ')); for (const row of resolveValue(n.rows)) lines.push(n.columns.map(c => Object.hasOwn(row, c.key) ? String(row[c.key]) : '—').join(' | ')); }
+    if (n.type === 'steps') for (const [i,item] of n.items.entries()) lines.push(`${item.status ? `[${item.status}]` : `${i+1}.`} ${item.title}${item.description ? ': ' + item.description : ''}`);
+    if (n.type === 'metric') { const v=resolveValue(n.value); lines.push(`${n.label}: ${typeof v === 'number' ? formatNumber(v,n.decimals ?? 2) : String(v)} ${n.unit ?? ''}`); }
+    if (n.type === 'table') { if(n.label)lines.push(n.label); lines.push(n.columns.map(c => c.label + (c.unit ? ` (${c.unit})` : '')).join(' | ')); for (const row of resolveValue(n.rows)) lines.push(n.columns.map(c => Object.hasOwn(row, c.key) ? String(row[c.key]) : '—').join(' | ')); }
     if (n.type === 'chart') { lines.push(n.label + (n.unit ? ` (${n.unit})` : '')); for (const r of resolveValue(n.rows)) lines.push(`${r[n.labelKey]}: ${r[n.valueKey]}`); }
     if (n.children) walk(n.children);
   } }

package/lib/stream.js

@@ -1,4 +1,5 @@
 import { LIMITS, validateDocument } from './protocol.js';
+import { toolJson } from './tool-json.js';
 
 // Parse complete JSON tokens only. Never finish a string, number or model expression.
 // Partial containers retain completed members, but only the document wrapper and
@@ -62,7 +63,7 @@ export function previewDocument(raw) {
   try {
     const root=parseToolArguments(raw);if(!root)return null;
     const document = root.members?.get('document');
-    if(document?.complete&&typeof document.value==='string'&&root.members.size===1)return validateDocument(JSON.parse(document.value));
+    if(document?.complete&&typeof document.value==='string'&&root.members.size===1)return validateDocument(toolJson(document.value,'document'));
     if (!document?.members) return null;
     if ([...root.members.keys()].some(k => k !== 'document')) return null;
     const doc = { ...document.value }, nodes = document.members.get('nodes');

package/lib/tool-json.js

@@ -1,7 +1,26 @@
 // DSH adapters may represent `type: json` fields as JSON strings.
 // Decode only the tool field, once; strict protocol validation still applies.
+function clean(source) {
+  let input=source.trim().replace(/^\uFEFF/, '');
+  const fence=input.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i);
+  if(fence)input=fence[1];
+  let output='',quoted=false,escaped=false;
+  for(let i=0;i<input.length;i++){
+    const c=input[i];
+    if(quoted){output+=c;if(escaped)escaped=false;else if(c==='\\')escaped=true;else if(c==='"')quoted=false;continue;}
+    if(c==='"')quoted=true;
+    if(c===',' && /^\s*[}\]]/.test(input.slice(i+1)))continue;
+    output+=c;
+  }
+  return output;
+}
 export function toolJson(value, field, maxBytes=131072){
   if(typeof value!=='string')return value;
-  if(Buffer.byteLength(value,'utf8')>maxBytes)throw new Error(`DSH UI: ${field} JSON exceeds size limit`);
-  try{return JSON.parse(value)}catch{throw new Error(`DSH UI: ${field} must contain valid JSON. Fix quoting/escaping. For a standalone HTML/SVG canvas, render_canvas accepts separate html/css/script fields.`)}
+  if(new TextEncoder().encode(value).length>maxBytes)throw new Error(`DSH UI: ${field} JSON exceeds size limit`);
+  const source=clean(value);
+  try{return JSON.parse(source)}catch(error){
+    const position=error.message.match(/position (\d+)/)?.[1];
+    const location=position===undefined?'':` at line ${source.slice(0,Number(position)).split('\n').length}, column ${Number(position)-source.lastIndexOf('\n',Number(position)-1)}`;
+    throw new Error(`DSH UI: ${field} must contain valid JSON${location}. Pass an object directly, not a manually escaped JSON string. Do not use single-quoted keys or raw newlines inside strings. For HTML/SVG use render_canvas with separate html/css/script fields. No partial document was saved.`);
+  }
 }

package/lib/tool-schema.js

@@ -0,0 +1,39 @@
+import {COMPONENTS} from './components.js';
+// Expose the document skeleton to native function calling, not just prose.
+// Per-component and expression checks remain in the shared runtime validator.
+const dictionary=description=>({type:'object',additionalProperties:true,description});
+export const DOCUMENT_PARAMETER={
+  required:true,
+  description:'Pass the document as an OBJECT. Do not manually escape/serialize it. For HTML/SVG source prefer render_canvas.',
+  type:'object',additionalProperties:false,
+    properties:{
+      version:{type:'number',const:1,required:true},
+      title:{type:'string',required:true},
+      fallback:{type:'string',required:true,description:'Useful plain-text explanation if the UI is unavailable.'},
+      nodes:{type:'array',required:true,items:{type:'object',additionalProperties:true,properties:{
+        id:{type:'string',required:true,description:'Unique letter/underscore identifier; Chinese supported, max64.'},
+        type:{type:'string',required:true,enum:Object.keys(COMPONENTS)},
+        label:{type:'string'},title:{type:'string'},
+        items:{type:'array',description:'steps only: direct array, not {item:[...]}. 1..12 step objects. Omit status for a static process guide.',items:{type:'object',additionalProperties:false,properties:{
+          title:{type:'string',required:true},description:{type:'string'},status:{type:'string',enum:['pending','active','done','error']}
+        }}},
+        open:{type:'boolean',description:'details only; defaults to closed.'},
+        icon:{type:'string'},tone:{type:'string'},surface:{type:'string'},
+        max:{type:'json',description:'progress only: positive numeric value or binding.'},unit:{type:'string'},decimals:{type:'number'},
+        action:{type:'string',description:'button only: a key declared in document.actions.'},
+        kind:{type:'string',enum:['bar','line']},labelKey:{type:'string'},valueKey:{type:'string'},xScale:{type:'string'},
+        html:{type:'string'},css:{type:'string'},script:{type:'string'},fallback:{type:'string'},height:{type:'number'},
+        stateKeys:{type:'array',items:{type:'string'}},dataKeys:{type:'array',items:{type:'string'}},derivedKeys:{type:'array',items:{type:'string'}},
+        text:{type:'json',description:'Literal scalar or {ref}/{expr}.'},
+        value:{type:'json',description:'metric: number or display string/boolean, or {ref}/{expr}. progress: numeric.'},
+        rows:{type:'json',description:'table/chart: inline array of objects, {ref:"data.rows"}/{ref:"derived.rows"}, or scoped reference string.'},
+        columns:{type:'array',items:{type:'object',additionalProperties:false,properties:{key:{type:'string',required:true},label:{type:'string',required:true},unit:{type:'string'}}}},
+        bind:{type:'string',description:'Controls bind state.key.'},children:{type:'array',description:'row/column/card/details: array of registered nodes using the same fields and type-specific rules. steps uses items instead of children.',items:{type:'json'}}
+      }}},
+      state:dictionary('key -> {type:number/string/boolean/json,default,...}. Numeric state needs min,max,step. json is bounded array/object state for canvas controls.'),
+      data:dictionary('Static data; Chinese identifier keys supported. Omit if rows are inline.'),
+      derived:dictionary('Local expressions or maps. Omit when unused.'),
+      actions:dictionary('Declared agent.followup actions. Omit when unused.'),
+      presentation:dictionary('Optional layout/accent/density from registered tokens.')
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-motion-ui",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Interactive UI, HTML/SVG animation and local calculations for DeepSeek Harness Web, with injected design guidance.",
   "type": "module",
   "main": "index.js",