@apteva/apteva-kit 0.1.125 → 0.1.127

package/dist/index.d.mts

@@ -225,36 +225,36 @@ interface SendMessageParams {
  */
 declare const WIDGET_DEFINITIONS: {
     readonly card: {
-        readonly schema: "title, description?, image?, footer?, actions?: [{type, label}]";
+        readonly schema: "title, description?, image?(url), footer?, actions?: [{type, label}]";
         readonly example: "@ui:card[{\"title\": \"Summary\", \"description\": \"Details here\"}]";
     };
     readonly list: {
-        readonly schema: "items: [{id, title, subtitle?, description?, image?, metadata?: {any extra data}}], actions?: [{type, label}] - metadata is sent as action payload when clicked";
+        readonly schema: "items: [{id, title, subtitle?, description?, image?(url), metadata?: {…}}], actions?: [{type, label}]";
         readonly example: "@ui:list[{\"items\": [{\"id\": \"1\", \"title\": \"Item\", \"subtitle\": \"Info\", \"metadata\": {\"key\": \"value\"}}]}]";
     };
     readonly button_group: {
-        readonly schema: "buttons: [{id, label, variant?}] - Use for standalone buttons only, NOT for form submits";
+        readonly schema: "buttons: [{id, label, variant?: \"default\"|\"primary\"|\"danger\"}]";
         readonly example: "@ui:button_group[{\"buttons\": [{\"id\": \"ok\", \"label\": \"OK\"}]}]";
     };
     readonly form: {
-        readonly schema: "title?, fields: [{name, type: text|password|number|select|checkbox|textarea|date, label, required?, placeholder?, options?}], actions: [{type, label}] - Button is built-in via actions, do NOT add separate button";
-        readonly example: "@ui:form[{\"title\": \"Settings\", \"fields\": [{\"name\": \"apiKey\", \"type\": \"password\", \"label\": \"API Key\", \"required\": true}], \"actions\": [{\"type\": \"save\", \"label\": \"Save\"}]}]";
+        readonly schema: "title?, fields: [{name, type: \"text\"|\"password\"|\"number\"|\"select\"|\"checkbox\"|\"textarea\"|\"date\", label, required?, placeholder?, options?: [{label, value}]}], actions: [{type, label}]";
+        readonly example: "@ui:form[{\"title\": \"Settings\", \"fields\": [{\"name\": \"key\", \"type\": \"password\", \"label\": \"API Key\", \"required\": true}], \"actions\": [{\"type\": \"save\", \"label\": \"Save\"}]}]";
     };
     readonly table: {
-        readonly schema: "columns: [{key, label}], rows: [...], striped?, compact?";
-        readonly example: "@ui:table[{\"columns\": [{\"key\": \"name\", \"label\": \"Name\"}], \"rows\": [{\"name\": \"A\"}]}]";
+        readonly schema: "columns: [{key, label}], rows: [{key: value, …}], striped?, compact?";
+        readonly example: "@ui:table[{\"columns\": [{\"key\": \"name\", \"label\": \"Name\"}], \"rows\": [{\"name\": \"Alice\"}]}]";
     };
     readonly image: {
-        readonly schema: "src, alt, caption?";
-        readonly example: "@ui:image[{\"src\": \"url\", \"alt\": \"desc\"}]";
+        readonly schema: "src(url), alt, caption?";
+        readonly example: "@ui:image[{\"src\": \"https://example.com/img.png\", \"alt\": \"Photo\"}]";
     };
     readonly chart: {
-        readonly schema: "chartType: line|bar|pie, data: {labels, datasets}";
-        readonly example: "@ui:chart[{\"chartType\": \"bar\", \"data\": {\"labels\": [\"A\"], \"datasets\": [{\"label\": \"X\", \"data\": [10]}]}}]";
+        readonly schema: "chartType: \"line\"|\"bar\"|\"pie\", data: {labels: [...], datasets: [{label, data: [numbers]}]}";
+        readonly example: "@ui:chart[{\"chartType\": \"bar\", \"data\": {\"labels\": [\"Q1\", \"Q2\"], \"datasets\": [{\"label\": \"Revenue\", \"data\": [100, 150]}]}}]";
     };
     readonly flow: {
-        readonly schema: "title, subtitle?, icon?: research|schedule|analyze|deploy|recurring|automation|data, steps: [{id, label, type?, color?: blue|purple|cyan|amber|emerald|rose|indigo|orange, status?: pending|active|completed|error|skipped}] - Horizontal pipeline. Use @label for agents. Types auto-detected from label.";
-        readonly example: "@ui:flow[{\"title\": \"Deploy Pipeline\", \"icon\": \"deploy\", \"steps\": [{\"id\": \"1\", \"label\": \"Test\", \"color\": \"cyan\"}, {\"id\": \"2\", \"label\": \"Build\", \"color\": \"amber\"}, {\"id\": \"3\", \"label\": \"Deploy\", \"color\": \"rose\"}]}]";
+        readonly schema: "title, subtitle?, icon?: \"research\"|\"schedule\"|\"analyze\"|\"deploy\"|\"recurring\"|\"automation\"|\"data\", steps: [{id, label, color?: \"blue\"|\"purple\"|\"cyan\"|\"amber\"|\"emerald\"|\"rose\"|\"indigo\"|\"orange\", status?: \"pending\"|\"active\"|\"completed\"|\"error\"|\"skipped\"}]";
+        readonly example: "@ui:flow[{\"title\": \"Pipeline\", \"steps\": [{\"id\": \"1\", \"label\": \"Test\", \"color\": \"cyan\"}, {\"id\": \"2\", \"label\": \"Deploy\", \"color\": \"rose\"}]}]";
     };
 };
 type WidgetType = keyof typeof WIDGET_DEFINITIONS;

package/dist/index.d.ts

@@ -225,36 +225,36 @@ interface SendMessageParams {
  */
 declare const WIDGET_DEFINITIONS: {
     readonly card: {
-        readonly schema: "title, description?, image?, footer?, actions?: [{type, label}]";
+        readonly schema: "title, description?, image?(url), footer?, actions?: [{type, label}]";
         readonly example: "@ui:card[{\"title\": \"Summary\", \"description\": \"Details here\"}]";
     };
     readonly list: {
-        readonly schema: "items: [{id, title, subtitle?, description?, image?, metadata?: {any extra data}}], actions?: [{type, label}] - metadata is sent as action payload when clicked";
+        readonly schema: "items: [{id, title, subtitle?, description?, image?(url), metadata?: {…}}], actions?: [{type, label}]";
         readonly example: "@ui:list[{\"items\": [{\"id\": \"1\", \"title\": \"Item\", \"subtitle\": \"Info\", \"metadata\": {\"key\": \"value\"}}]}]";
     };
     readonly button_group: {
-        readonly schema: "buttons: [{id, label, variant?}] - Use for standalone buttons only, NOT for form submits";
+        readonly schema: "buttons: [{id, label, variant?: \"default\"|\"primary\"|\"danger\"}]";
         readonly example: "@ui:button_group[{\"buttons\": [{\"id\": \"ok\", \"label\": \"OK\"}]}]";
     };
     readonly form: {
-        readonly schema: "title?, fields: [{name, type: text|password|number|select|checkbox|textarea|date, label, required?, placeholder?, options?}], actions: [{type, label}] - Button is built-in via actions, do NOT add separate button";
-        readonly example: "@ui:form[{\"title\": \"Settings\", \"fields\": [{\"name\": \"apiKey\", \"type\": \"password\", \"label\": \"API Key\", \"required\": true}], \"actions\": [{\"type\": \"save\", \"label\": \"Save\"}]}]";
+        readonly schema: "title?, fields: [{name, type: \"text\"|\"password\"|\"number\"|\"select\"|\"checkbox\"|\"textarea\"|\"date\", label, required?, placeholder?, options?: [{label, value}]}], actions: [{type, label}]";
+        readonly example: "@ui:form[{\"title\": \"Settings\", \"fields\": [{\"name\": \"key\", \"type\": \"password\", \"label\": \"API Key\", \"required\": true}], \"actions\": [{\"type\": \"save\", \"label\": \"Save\"}]}]";
     };
     readonly table: {
-        readonly schema: "columns: [{key, label}], rows: [...], striped?, compact?";
-        readonly example: "@ui:table[{\"columns\": [{\"key\": \"name\", \"label\": \"Name\"}], \"rows\": [{\"name\": \"A\"}]}]";
+        readonly schema: "columns: [{key, label}], rows: [{key: value, …}], striped?, compact?";
+        readonly example: "@ui:table[{\"columns\": [{\"key\": \"name\", \"label\": \"Name\"}], \"rows\": [{\"name\": \"Alice\"}]}]";
     };
     readonly image: {
-        readonly schema: "src, alt, caption?";
-        readonly example: "@ui:image[{\"src\": \"url\", \"alt\": \"desc\"}]";
+        readonly schema: "src(url), alt, caption?";
+        readonly example: "@ui:image[{\"src\": \"https://example.com/img.png\", \"alt\": \"Photo\"}]";
     };
     readonly chart: {
-        readonly schema: "chartType: line|bar|pie, data: {labels, datasets}";
-        readonly example: "@ui:chart[{\"chartType\": \"bar\", \"data\": {\"labels\": [\"A\"], \"datasets\": [{\"label\": \"X\", \"data\": [10]}]}}]";
+        readonly schema: "chartType: \"line\"|\"bar\"|\"pie\", data: {labels: [...], datasets: [{label, data: [numbers]}]}";
+        readonly example: "@ui:chart[{\"chartType\": \"bar\", \"data\": {\"labels\": [\"Q1\", \"Q2\"], \"datasets\": [{\"label\": \"Revenue\", \"data\": [100, 150]}]}}]";
     };
     readonly flow: {
-        readonly schema: "title, subtitle?, icon?: research|schedule|analyze|deploy|recurring|automation|data, steps: [{id, label, type?, color?: blue|purple|cyan|amber|emerald|rose|indigo|orange, status?: pending|active|completed|error|skipped}] - Horizontal pipeline. Use @label for agents. Types auto-detected from label.";
-        readonly example: "@ui:flow[{\"title\": \"Deploy Pipeline\", \"icon\": \"deploy\", \"steps\": [{\"id\": \"1\", \"label\": \"Test\", \"color\": \"cyan\"}, {\"id\": \"2\", \"label\": \"Build\", \"color\": \"amber\"}, {\"id\": \"3\", \"label\": \"Deploy\", \"color\": \"rose\"}]}]";
+        readonly schema: "title, subtitle?, icon?: \"research\"|\"schedule\"|\"analyze\"|\"deploy\"|\"recurring\"|\"automation\"|\"data\", steps: [{id, label, color?: \"blue\"|\"purple\"|\"cyan\"|\"amber\"|\"emerald\"|\"rose\"|\"indigo\"|\"orange\", status?: \"pending\"|\"active\"|\"completed\"|\"error\"|\"skipped\"}]";
+        readonly example: "@ui:flow[{\"title\": \"Pipeline\", \"steps\": [{\"id\": \"1\", \"label\": \"Test\", \"color\": \"cyan\"}, {\"id\": \"2\", \"label\": \"Deploy\", \"color\": \"rose\"}]}]";
     };
 };
 type WidgetType = keyof typeof WIDGET_DEFINITIONS;

package/dist/index.js

@@ -735,36 +735,36 @@ function parseWidgetsFromText(text) {
 // src/utils/widget-context.ts
 var WIDGET_DEFINITIONS = {
   card: {
-    schema: "title, description?, image?, footer?, actions?: [{type, label}]",
+    schema: "title, description?, image?(url), footer?, actions?: [{type, label}]",
     example: '@ui:card[{"title": "Summary", "description": "Details here"}]'
   },
   list: {
-    schema: "items: [{id, title, subtitle?, description?, image?, metadata?: {any extra data}}], actions?: [{type, label}] - metadata is sent as action payload when clicked",
+    schema: "items: [{id, title, subtitle?, description?, image?(url), metadata?: {\u2026}}], actions?: [{type, label}]",
     example: '@ui:list[{"items": [{"id": "1", "title": "Item", "subtitle": "Info", "metadata": {"key": "value"}}]}]'
   },
   button_group: {
-    schema: "buttons: [{id, label, variant?}] - Use for standalone buttons only, NOT for form submits",
+    schema: 'buttons: [{id, label, variant?: "default"|"primary"|"danger"}]',
     example: '@ui:button_group[{"buttons": [{"id": "ok", "label": "OK"}]}]'
   },
   form: {
-    schema: "title?, fields: [{name, type: text|password|number|select|checkbox|textarea|date, label, required?, placeholder?, options?}], actions: [{type, label}] - Button is built-in via actions, do NOT add separate button",
-    example: '@ui:form[{"title": "Settings", "fields": [{"name": "apiKey", "type": "password", "label": "API Key", "required": true}], "actions": [{"type": "save", "label": "Save"}]}]'
+    schema: 'title?, fields: [{name, type: "text"|"password"|"number"|"select"|"checkbox"|"textarea"|"date", label, required?, placeholder?, options?: [{label, value}]}], actions: [{type, label}]',
+    example: '@ui:form[{"title": "Settings", "fields": [{"name": "key", "type": "password", "label": "API Key", "required": true}], "actions": [{"type": "save", "label": "Save"}]}]'
   },
   table: {
-    schema: "columns: [{key, label}], rows: [...], striped?, compact?",
-    example: '@ui:table[{"columns": [{"key": "name", "label": "Name"}], "rows": [{"name": "A"}]}]'
+    schema: "columns: [{key, label}], rows: [{key: value, \u2026}], striped?, compact?",
+    example: '@ui:table[{"columns": [{"key": "name", "label": "Name"}], "rows": [{"name": "Alice"}]}]'
   },
   image: {
-    schema: "src, alt, caption?",
-    example: '@ui:image[{"src": "url", "alt": "desc"}]'
+    schema: "src(url), alt, caption?",
+    example: '@ui:image[{"src": "https://example.com/img.png", "alt": "Photo"}]'
   },
   chart: {
-    schema: "chartType: line|bar|pie, data: {labels, datasets}",
-    example: '@ui:chart[{"chartType": "bar", "data": {"labels": ["A"], "datasets": [{"label": "X", "data": [10]}]}}]'
+    schema: 'chartType: "line"|"bar"|"pie", data: {labels: [...], datasets: [{label, data: [numbers]}]}',
+    example: '@ui:chart[{"chartType": "bar", "data": {"labels": ["Q1", "Q2"], "datasets": [{"label": "Revenue", "data": [100, 150]}]}}]'
   },
   flow: {
-    schema: "title, subtitle?, icon?: research|schedule|analyze|deploy|recurring|automation|data, steps: [{id, label, type?, color?: blue|purple|cyan|amber|emerald|rose|indigo|orange, status?: pending|active|completed|error|skipped}] - Horizontal pipeline. Use @label for agents. Types auto-detected from label.",
-    example: '@ui:flow[{"title": "Deploy Pipeline", "icon": "deploy", "steps": [{"id": "1", "label": "Test", "color": "cyan"}, {"id": "2", "label": "Build", "color": "amber"}, {"id": "3", "label": "Deploy", "color": "rose"}]}]'
+    schema: 'title, subtitle?, icon?: "research"|"schedule"|"analyze"|"deploy"|"recurring"|"automation"|"data", steps: [{id, label, color?: "blue"|"purple"|"cyan"|"amber"|"emerald"|"rose"|"indigo"|"orange", status?: "pending"|"active"|"completed"|"error"|"skipped"}]',
+    example: '@ui:flow[{"title": "Pipeline", "steps": [{"id": "1", "label": "Test", "color": "cyan"}, {"id": "2", "label": "Deploy", "color": "rose"}]}]'
   }
 };
 var ALL_WIDGET_TYPES = Object.keys(WIDGET_DEFINITIONS);
@@ -774,27 +774,54 @@ function generateWidgetContext(enabledWidgets) {
   const widgets = enabledWidgets || DEFAULT_WIDGET_TYPES;
   let context = `
 ## UI Widgets
-SYNTAX: @ui:type[{json}] - MUST use SQUARE BRACKETS [] around the JSON object.
-CORRECT: @ui:list[{"items": [...]}]
-WRONG: @ui:list{"items": [...]} (missing square brackets)
+
+You can render interactive UI widgets inline in your responses. Use them when structured display is clearer than plain text (showing data, forms, actions, images). You may include normal text before or after a widget.
+
+**Syntax:** \`@ui:type[{json}]\` \u2014 the JSON object MUST be wrapped in square brackets \`[]\`.
+
+Example:
+@ui:list[{"items": [{"id": "1", "title": "First item"}]}]
+
+Do NOT wrap widgets in code blocks or backticks. Write them directly in your response text.
+
+### Available widgets
 
 `;
   for (const type of widgets) {
     const def = WIDGET_DEFINITIONS[type];
     if (!def) continue;
-    context += `${type}: ${def.schema} | ${def.example}
+    context += `**${type}** \u2014 ${def.schema}
+`;
+    context += `  ${def.example}
+
 `;
   }
-  context += `
-Per-item "metadata" is sent as payload on action click.
+  context += `### Notes
+- **actions**: the \`type\` field is a custom string you choose (e.g. "edit", "delete", "submit"). It is returned to the app when the user clicks the button.
+- **metadata** on list items: any extra data attached to an item. Returned as the action payload when the user clicks that item.
+- **form**: buttons are defined in \`actions\`, do NOT add a separate button_group for form submission.
+- **select fields**: \`options\` is an array of \`{label, value}\` objects.
 `;
   return context;
 }
 function generateCompactWidgetContext(enabledWidgets) {
   const widgets = enabledWidgets || DEFAULT_WIDGET_TYPES;
-  return `
-Widgets: @ui:type[{json}] - MUST use square brackets []. Example: @ui:list[{"items": [...]}]. Types: ${widgets.join(", ")}. Per-item "metadata" is sent as action payload.
+  let context = `
+## UI Widgets
+Render widgets inline: \`@ui:type[{json}]\` (square brackets required, no code blocks).
+Use when structured display is clearer than plain text. Normal text can surround widgets.
+
+`;
+  for (const type of widgets) {
+    const def = WIDGET_DEFINITIONS[type];
+    if (!def) continue;
+    context += `**${type}**: ${def.schema}
 `;
+  }
+  context += `
+actions.type = custom string returned on click. list metadata = payload on item click. form buttons go in actions, not button_group.
+`;
+  return context;
 }
 
 // src/utils/interface-parser.ts