@zephinel/dsh-intelligent-ui 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +63 -45
- package/README.md +62 -44
- package/assets/intelligent-ui-on-demand-hint.webp +0 -0
- package/assets/intelligent-ui-settings.webp +0 -0
- package/assets/intelligent-ui-style-panel.webp +0 -0
- package/assets/intelligent-ui-temporary-result-dark.webp +0 -0
- package/assets/intelligent-ui-temporary-result.webp +0 -0
- package/assets/intelligent-ui-toggle.png +0 -0
- package/lib/client.js +125 -125
- package/lib/index.js +59 -56
- package/lib/standalone.css +1 -1
- package/lib/standalone.js +77 -77
- package/package.json +4 -3
- package/skills/intelligent-ui/SKILL.md +19 -11
- package/skills/intelligent-ui/references/components.md +26 -26
- package/skills/intelligent-ui/references/integration.md +16 -15
- package/skills/intelligent-ui/references/troubleshooting.md +20 -3
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zephinel/dsh-intelligent-ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Intelligent UI for DeepSeek Harness: render OpenUI Lang answers as interactive maps, photos, charts, forms, drawings, working tools or a reading article inside the Web chat. Global defaults live on the Plugins detail page; the composer overrides enablement and answer style per session.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -44,8 +44,8 @@
|
|
|
44
44
|
"build:prompt": "node scripts/generate-prompt.mjs",
|
|
45
45
|
"typecheck": "tsc --noEmit",
|
|
46
46
|
"test": "node --test test/host/*.test.mjs test/client/*.test.mjs test/packaging/*.test.mjs",
|
|
47
|
-
"test:renderer": "node test/renderer/check.mjs && node test/renderer/render-check.mjs && node test/renderer/contrast-check.mjs && node test/renderer/i18n-check.mjs && node test/renderer/typography-check.mjs",
|
|
48
|
-
"check": "npm run build && npm test && npm run test:renderer",
|
|
47
|
+
"test:renderer": "node test/renderer/check.mjs && node test/renderer/render-check.mjs && node test/renderer/contrast-check.mjs && node test/renderer/i18n-check.mjs && node test/renderer/typography-check.mjs && node test/renderer/media-row-check.mjs && node test/renderer/pressable-select-check.mjs && node test/renderer/css-contract-check.mjs && node test/renderer/prop-contract-check.mjs",
|
|
48
|
+
"check": "npm run typecheck && npm run build && npm test && npm run test:renderer",
|
|
49
49
|
"pack:check": "npm pack --dry-run --json",
|
|
50
50
|
"prepare": "node scripts/build.mjs",
|
|
51
51
|
"check:theme": "node test/renderer/theme-torture.mjs",
|
|
@@ -78,6 +78,7 @@
|
|
|
78
78
|
"devDependencies": {
|
|
79
79
|
"@openuidev/lang-core": "^1.0.1",
|
|
80
80
|
"@openuidev/react-lang": "^1.0.1",
|
|
81
|
+
"@types/node": "^22.20.5",
|
|
81
82
|
"@types/react": "^18.3.0",
|
|
82
83
|
"@types/react-dom": "^18.3.0",
|
|
83
84
|
"@zumer/snapdom": "^3.3.6",
|
|
@@ -36,10 +36,11 @@ Two consequences matter in practice:
|
|
|
36
36
|
|
|
37
37
|
## Answer styles
|
|
38
38
|
|
|
39
|
-
The injected prompt owns the effective style decision and appends it to the session prompt; this section only explains how to build each shape. Apply the style
|
|
39
|
+
The injected prompt owns the effective style decision and appends it to the session prompt; this section only explains how to build each shape. Apply the session style below for ordinary answers; an authorized on-demand operation uses the free-layout contract in the next section:
|
|
40
40
|
|
|
41
41
|
- **Card** — compact, scannable interactive page. Keep cards tight; do not turn a broad request into a long article.
|
|
42
42
|
- **Article** — article-first reading page inside the card: a short coverage summary, a `Toc`, and one `Section` per major part whose body is substantial `Markdown` prose. All core content must be readable without clicking; interactions are optional supplements. The Host rejects an article-style call that has no reachable `Toc` and `Section`, so include both. Keep Section anchors unique within one card. `Section(title, children, anchor?)` lets `anchor` be the stable id while `title` stays display text; `Toc(items, anchors?)` takes the matching parallel anchors. Without anchors the title is the target.
|
|
43
|
+
- **Free template** — when the session selects a template with `baseLayout: "free"`, compose the user-requested layout without a Card/Article shell. `Toc` and `Section` are optional; pass `style: "free"` plus the exact selected `styleId`, without `temporaryStyle`. The renderer applies the template theme and retains the DSH card header.
|
|
43
44
|
- **Auto** — choose per request: Card for interactive, structured, visual or computational answers; Article for 详尽/深入/全面/长文/报告/综述 requests.
|
|
44
45
|
|
|
45
46
|
For an Article answer, a skeleton is a failure. Each major part needs specific facts, causes, examples or debates, and the page must not end by asking which part to expand instead of covering it. The compactness rules below apply to Card pages and to side cards inside an Article — they are not a reason to delete Article content.
|
|
@@ -49,11 +50,12 @@ For an Article answer, a skeleton is a failure. Each major part needs specific f
|
|
|
49
50
|
An `ON-DEMAND UI` request note comes from a Host-armed operation; it is already present in the prompt for the first turn (DSH assembles the system prompt before the user message) and stays while the turn clarifies. Once bound, a plain `render_ui` without `temporaryStyle` is rejected. In that turn, call `render_ui` with a complete `temporaryStyle` and matching `style`, omitting `styleId`. A user's prose request or your tool arguments cannot authorize temporaryStyle: the Host must already allow this operation and the current tool call. If authorization is absent, ask the user to choose **On-demand UI** in the composer; do not arm it yourself.
|
|
50
51
|
|
|
51
52
|
- **Ground the content before styling.** Missing content is material ambiguity. If the request refers to "this analysis", "these contents", "the above data" but none is in the conversation, or its numbers/dates/sources are absent, do not invent placeholder datasets, statistics, dates, quotes or sources. Use `ask_user_question` to ask which content to use (conversation content, pasted/linked data, or explicitly labelled illustrative data); render only after it is available or illustrative data is authorized. Style clarity never excuses missing data.
|
|
52
|
-
-
|
|
53
|
-
-
|
|
53
|
+
- **Presentation format is user-determined.** Compose the requested dashboard, poster, timeline, comparison, reading page or other layout directly. If the layout is materially unclear, ask one focused layout question before rendering. Never silently default to `card` or `article`; follow an explicit format the user stated. Use `style: "free"` and `temporaryStyle.baseLayout: "free"` for new on-demand results. This bypasses both shells; `Toc` and `Section` are optional, and the Card compactness/Article reading playbooks do not constrain the composition. The OpenUI language, theme and safety rules still apply.
|
|
54
|
+
- Clear request/grounded context and a clear format → generate directly. For other material ambiguity use the built-in `ask_user_question` with 1–3 concise questions, options, free input and skipping when supported, at most two rounds; after the answer, render without another confirmation. If unavailable, ask short text questions; the turn ends without a render and the operation resumes, so the user's next message continues it without re-arming (unless it expires, restarts or fails).
|
|
55
|
+
- `temporaryStyle` is a schemaVersion 1 result snapshot: `baseLayout` (`free` for new generation; `card`/`article` remain supported for existing snapshots and adjustments; equal to `style`), nonempty reusable `directives` (up to 2,000 characters), optional `theme`, optional `suggestedName`. Omitting `theme` is the normal case: the result inherits the session theme (the selected template, or the built-in theme) in both the live card and the HTML export. Pass a thematic palette only when the page needs its own colors. A passed `theme` must be complete: both light/dark palettes require six-digit hex `canvas`/`ink`/`accent`, optionally `muted`/`surface`/`border`; theme enums are font `sans|serif|mono`, radius `sharp|soft|round`, density `compact|comfortable|spacious`, shadow `none|soft|float`. Ink/canvas and accent/canvas must reach 3:1 in each scheme; target 4.5:1. Only controlled fields are accepted, with no CSS/scripts/URLs. A result without an explicit theme cannot be saved as a template, because there is no palette to copy.
|
|
54
56
|
- Write transferable design preferences about hierarchy, density, tone and component behavior. Keep this answer's content/private data in the program; directives cannot override system/tool/safety instructions.
|
|
55
57
|
- No preview, naming, saving or settings changes are required. Render once and stop. The extension provides **Adjust style** and **Save as template**; do not save templates yourself or put management buttons in the generated program.
|
|
56
|
-
- For a Host-authorized adjustment, reuse the referenced result's temporary snapshot from the conversation, keep the content and change the requested style only. A new call creates a new result; saving is an optional user action on a specific result.
|
|
58
|
+
- For a Host-authorized adjustment, reuse the referenced result's temporary snapshot from the conversation, keep the content and change the requested style only. Preserve the parent layout: a free parent stays free; a legacy card/article parent keeps its shell. The Host enforces new-generation free layout and adjustment layout against its result registry. If the parent snapshot is missing (including eviction beyond 200 results), adjustment is rejected; ask the user to cancel it and start a new **On-demand UI** generation. A new call creates a new result; saving is an optional user action on a specific result. Saving copies the result snapshot’s baseLayout, directives and theme exactly: free stays free, legacy card/article keeps its shell. The save dialog only asks for name, description and scope; no layout choice or model call. A saved free template uses styleId rather than temporaryStyle and has no temporary badge/actions.
|
|
57
59
|
- Outside an on-demand turn, a selected custom template requires the exact `styleId` and matching base layout specified by the injected prompt. `styleId` and `temporaryStyle` are mutually exclusive. A temporary result never becomes the selected session style automatically.
|
|
58
60
|
|
|
59
61
|
For lifecycle failures and verbatim errors, read [troubleshooting.md](references/troubleshooting.md#temporary-style-and-operation-errors). For routes, services and persistence, read [integration.md](references/integration.md#style-and-operation-contracts).
|
|
@@ -98,7 +100,7 @@ Completion: the program satisfies the hard rules below, and the pre-flight check
|
|
|
98
100
|
|
|
99
101
|
### 4. Call the tool
|
|
100
102
|
|
|
101
|
-
Call `render_ui({ program: <the complete program>, style: <"card"|"article">, title: "Short noun phrase" })`. Pass `card` for a compact interactive page, `article` for the reading layout; when the session is Auto, pass the style you chose. For a selected custom template
|
|
103
|
+
Call `render_ui({ program: <the complete program>, style: <"card"|"article"|"free">, title: "Short noun phrase" })`. Pass `card` for a compact interactive page, `article` for the reading layout; when the session is Auto, pass the style you chose. For a selected custom template pass its baseLayout (including `free`) and exact `styleId`, without `temporaryStyle`; for new Host-authorized on-demand generation use `free` and add `temporaryStyle` as described above. The title is card chrome: 2–6 words, no trailing period ("Lisbon in three days", "Sales, last 90 days"). Before the call, at most one short Markdown sentence; after a successful call, stop or add one short sentence. Never paste the program into the reply, and never repeat the page's content in prose.
|
|
102
104
|
|
|
103
105
|
**The call is the preflight.** The tool validates the program, reports warnings, and never partially renders a rejected call; retry in the same turn instead of building a local harness. Keep the extension checkout read-only while answering — no scratch programs, tests, fixtures or build output anywhere under the plugin's source tree, including `test/renderer/.build/`; put drafts in a temporary directory outside the repository. Hard rule 11 carries the full version.
|
|
104
106
|
|
|
@@ -106,6 +108,7 @@ Call `render_ui({ program: <the complete program>, style: <"card"|"article">, ti
|
|
|
106
108
|
|
|
107
109
|
- **Success, no warnings** — done. The page is on screen; do not re-call.
|
|
108
110
|
- **Success, with warnings** — inspect the named parser finding or contrast warning. Ordinary calls may be repaired once; an on-demand success completes its operation even with warnings, so further changes need the user to arm Adjust style again.
|
|
111
|
+
- **Success but a missing or broken block** — a render-time crash inside one component is contained: the failing subtree disappears (or keeps stale content) while `render_ui` still reports success, so you get no finding and cannot detect it. Recovery is user-initiated: when the user reports a blank or broken area, rebuild that block more simply in the next turn.
|
|
109
112
|
- **Fatal error** — read every finding after the `render_ui:` prefix, fix all of them, and retry in the same turn. Two or three attempts are normal. If the same finding returns, re-read the program instead of rewording the message. If retries keep failing, drop the most complex block (Map, HtmlView, nested `@Each`), send a simpler page, and say so in one sentence.
|
|
110
113
|
- **Tool missing** — follow [Before you start](#before-you-start-is-the-session-enabled): answer in prose, and point at [integration.md](references/integration.md#troubleshooting-a-missing-render_ui) if the user is setting it up.
|
|
111
114
|
|
|
@@ -129,18 +132,19 @@ Exact signatures, argument order, enums and function list: [references/component
|
|
|
129
132
|
|
|
130
133
|
**Free-form layout.** When the injected prompt says "Free-form layout is on for this deployment", this playbook is advisory, not a template: choose the page shape and blocks the content needs, and vary them between answers. The hard rules above and the theme/readability guidance below still apply.
|
|
131
134
|
|
|
132
|
-
The compactness bullets below describe **Card** pages and side cards inside an Article. An Article page follows the Article layout bullet instead: prose is the main content, and a wall of text is not a defect when the user asked for depth.
|
|
135
|
+
The compactness bullets below describe **Card** pages and side cards inside an Article. An Article page follows the Article layout bullet instead: prose is the main content, and a wall of text is not a defect when the user asked for depth. For authorized free results and selected free templates, page shape and typography guidance is advisory; follow the requested composition while retaining language, theme and safety rules.
|
|
133
136
|
|
|
134
137
|
- **Article layout.** One column, readable measure. `Title` (xl/2xl), a short `Text` summary, a `Toc`, then `Section` blocks. Put `Markdown` prose inside each Section; use a chart, map or table as a supplement between sections, not as a substitute for the prose. A Section body is a flow: prose first, then at most a couple of supplemental blocks; no blank spacer or divider blocks. All sections always start open; the reader can collapse them. Do not use a `Carousel` as the only way to read core content.
|
|
135
138
|
- **Compose a page, not a form letter.** A `Title` (`xl`/`2xl`), one short `Text`, then 2–4 mixed blocks. Group related blocks in `Card`s; do not wrap the whole page in one card.
|
|
136
|
-
- **Layout and spacing contract.** The renderer owns the vertical rhythm;
|
|
137
|
-
- **Cards stay compact.** Card title `md`/`sm`; inside a `Card` the display sizes are capped (`lg` 18 → `xl` 22 → `2xl` 26 → `3xl` 30px), so `xl` is for one KPI number, never for the card heading. Body `sm`, at most one short paragraph, then facts as `Badge`s or label/value rows. Cards side by side in a `Grid` carry the same blocks in the same order so they line up.
|
|
138
|
-
- **Media rows beat walls of text.** A photo beside copy: `Row([Box([SearchImage("Sonoma Plaza", 1.33)], null, null, null, null, "lg", null, 120), Col([Title("Sonoma", "md"), Row([Badge("1 h drive", null, "car"), Badge("Wine country", "purple")], 1, null, null, true), Text("A slow plaza and quiet back roads.", "sm")], 2)], 4, "start")`. Give the image box an explicit width so the row is stable; top-align the text.
|
|
139
|
-
- **
|
|
139
|
+
- **Layout and spacing contract.** The renderer owns the vertical rhythm; Card/Article pages use one readable column. For authorized free results, follow the user-requested page shape. Leave `gap` unset on the page root `Col`, on `Section` children and on `Card` contents — the app already spaces them (section 24 / group 12 / inner 8). Set `gap` only on `Row`, `Grid`, `Carousel` and small compact control stacks: 1–2 for inner pairs, 3–4 for grouped blocks. Never create vertical space with `Spacer()`, an empty `Box`/`Col`/`Card`, empty `Text`/`Markdown`, or a `Divider` used as a blank; group related blocks in a `Card` or let the flow space them. Do not wrap a whole Section body in a `Col` with a manual gap, and do not put a whole page side by side. The Host warns about root gaps, vertical Spacers, empty Sections/Text and `gap: 0` block stacks.
|
|
140
|
+
- **Cards stay compact.** Card title `md`/`sm`; anywhere inside a `Card`, a `Grid` cell or a `Carousel` item — including inside a `Row` — the display sizes are capped (`lg` 18 → `xl` 22 → `2xl` 26 → `3xl` 30px), and a body `Text` is 15px, so `xl` is for one KPI number, never for the card heading. Body `sm`, at most one short paragraph, then facts as `Badge`s or label/value rows. Cards side by side in a `Grid` carry the same blocks in the same order so they line up.
|
|
141
|
+
- **Media rows beat walls of text.** A photo beside copy: `Row([Box([SearchImage("Sonoma Plaza", 1.33)], null, null, null, null, "lg", null, 120), Col([Title("Sonoma", "md"), Row([Badge("1 h drive", null, "car"), Badge("Wine country", "purple")], 1, null, null, true), Text("A slow plaza and quiet back roads.", "sm")], 2)], 4, "start")`. Give the image box an explicit width so the row is stable; top-align the text. A media `Box` with only a `height` still takes the renderer's 120–200px default width, so pass `width` too when the size must be exact. A media row is a feature element — roughly one to three per page — and each `SearchImage` is a network lookup that can come back empty for an obscure subject. A repeated list or ranking is a `Table` or `List`, not a stack of photo rows; if a row genuinely needs a thumbnail, size it explicitly: `Box([SearchImage("subject", 0.7)], null, null, null, null, null, null, 44)` — the renderer now honors that explicit width and aspect ratio.
|
|
142
|
+
- **A hand-built thumbnail list is page rhythm too.** When repeated `Row`s are genuinely clearer than `Table`/`List`, make one `Col` of rows with no gap (the 12px flow), a fixed-width rank slot, a fixed-width thumbnail and a centered row — copy and adapt: `rows = Col(@Each(films, "m", Row([Box([Text(m.r + "", "sm", "muted", "semibold", null, null, true)], null, null, null, null, null, null, 26), Box([SearchImage(m.t + " still", 0.7, "sm")], null, null, null, null, null, null, 44), Box([Col([Text(m.t, "sm", null, "semibold"), Text(m.d, "xs", "muted")], 1)], "col", 1, null, null, null, null, null, null, 1), Text(@Format(m.s, "number", 1), "md", null, "semibold")], 2, "center")))`. The 26px rank `Box` stops a two-digit "10" from widening column 1 and shifting that row's thumbnail, and the centered row keeps short copy from top-aligning against a taller photo; a repeated list or ranking is still clearest as a `Table` or `List`.
|
|
143
|
+
- **SearchImage for things with a look** — place, dish, product, animal, building: give it one feature photo in a hero, card or media row, never one photo per item in a list. Name the exact subject (`"Belém Tower Lisbon"`, not `"Europe trip"`). A photo shows what a thing looks like; `Svg` shows how it works, so how-to answers often need drawings even when photos are present.
|
|
140
144
|
- **Draw with `Svg` whenever the user would otherwise picture it.** One drawing per step, viewBox around 240 wide, a dozen shapes in tokens, `SvgText` labels, a `Line` + small `Polygon` for arrows. Drive it from `$step` and offer a thumbnail strip.
|
|
141
145
|
- **Make it work on its own.** Every control changes what is rendered; every list, budget or total is computed from state or inline data with `@functions`; nothing waits for another message. `@ToAssistant` is only for what the page cannot compute (form submit, "plan another day").
|
|
142
146
|
- **Guard arithmetic.** Number inputs are empty or zero: read them as `@Clamp(@Default($people, 1), 1, 50)` and guard divisions with a `$n > 0 ? … : 1` ternary. `@Avg` of an empty list is `0`.
|
|
143
|
-
- **Format for humans.** `@Format(value, "currency", 0, "USD")`, `@Format(value, "percent", 1)`, `@Plural(n, "guest")`, `@FormatDate(date, "long")`. Units belong in the label or unit argument, not in the number.
|
|
147
|
+
- **Format for humans.** `@Format(value, "currency", 0, "USD")`, `@Format(value, "percent", 1)`, `@Plural(n, "guest")`, `@FormatDate(date, "long")`. Units belong in the label or unit argument, not in the number. `@FormatDate` on an empty or invalid date returns `""`, so an empty date input never breaks the card.
|
|
144
148
|
- **Data stays inline and modest for Card pages.** A few dozen rows in a literal array is fine; summarize with `@GroupBy`/`@Bucket` and show the top rows in a `Table`. Typical Card page: 20–80 statements; past ~120, cut blocks rather than shrink everything. An Article page is content-driven: it may be much longer, and content must not be deleted to satisfy a statement budget. Use one `Markdown` block per section when that keeps the program manageable.
|
|
145
149
|
- **Theme with tokens.** `Color` tokens and CSS colors adapt to DSH dark/light automatically. Use raw hexes only for illustration (`Svg` fills, heatmap scales via `@MixColor`), and make sure text stays readable in both themes.
|
|
146
150
|
|
|
@@ -169,6 +173,8 @@ The compactness bullets below describe **Card** pages and side cards inside an A
|
|
|
169
173
|
13. **Preflighting by editing the plugin** — a scratch harness written into the extension checkout shows the user a spurious file diff in a repository you were not asked to change. Call `render_ui` and use its findings; keep drafts outside the tree.
|
|
170
174
|
14. **Manual vertical spacing** — `Spacer()`, an empty `Box`/`Col`/`Card`, empty `Text`/`Markdown`, or a `Divider` used as a blank. The renderer already owns the rhythm; these produce odd blank bands (and Host warnings).
|
|
171
175
|
15. **Gap on a block stack** — explicit `gap` on the page root, Section contents or Card body overrides the app rhythm and can double the blank space. Keep gaps on `Row`/`Grid`/`Carousel` and compact control groups only.
|
|
176
|
+
16. **A photo inside every repeated row** — an `@Each` template whose repeated row contains a `SearchImage` turns the list into tall media rows, and the extra searches often fail to an empty placeholder. Use `Table`/`List` for repeated rows, or a compact thumbnail sized explicitly (a `Box` with a `width` and a small `SearchImage` ratio).
|
|
177
|
+
17. **Two-digit rank shifts the thumbnail** — a bare `Text(m.r + "")` widens the first column once the rank reaches 10, pushing that row's thumbnail right, and a list `Col` with `gap: 1` crams photo rows 4px apart. Give the rank a fixed-width `Box` (e.g. 26px), let the list `Col` keep the 12px flow (no gap, or 2–3), and center rows whose photo is taller than the copy.
|
|
172
178
|
|
|
173
179
|
## Pre-flight checklist
|
|
174
180
|
|
|
@@ -184,6 +190,8 @@ Before the call, verify:
|
|
|
184
190
|
8. No file was created or edited outside the requested deliverable — in particular, nothing in the extension checkout was touched to test the program.
|
|
185
191
|
9. The reply around the call is one intro sentence and, after success, at most one closing sentence.
|
|
186
192
|
10. The layout follows the spacing contract: no root/Section/Card gap, no manual vertical spacer or empty blank block, and every stack is left to the renderer's flow rhythm.
|
|
193
|
+
11. Photos are few feature images — roughly one to three per page — and every repeated row is a `Table`/`List` row or an explicitly sized compact thumbnail, not a `SearchImage` per row.
|
|
194
|
+
12. A hand-built row list leaves the list `Col` gap unset (or 2–3), centers rows whose photo is taller, and gives the rank a fixed-width slot so 9 and 10 align.
|
|
187
195
|
|
|
188
196
|
## Reference index
|
|
189
197
|
|
|
@@ -14,9 +14,9 @@ Complete reference for the OpenUI Lang vocabulary this extension ships: **57 com
|
|
|
14
14
|
|
|
15
15
|
**Token types**
|
|
16
16
|
|
|
17
|
-
- **Color**: `"ink"`, `"muted"`, `"faint"`, `"canvas"`, `"on-ink"`, `"info"`, `"success"`, `"warning"`, `"danger"`, `"purple"`, `"pink"`, `"chart1"`…`"chart6"`, or any CSS color. As a background, status colors are soft tints; as text/stroke they are strong. `"surface"`, `"surface-strong"` and `"
|
|
17
|
+
- **Color**: `"ink"`, `"muted"`, `"faint"`, `"canvas"`, `"on-ink"`, `"info"`, `"success"`, `"warning"`, `"danger"`, `"purple"`, `"pink"`, `"chart1"`…`"chart6"`, or any CSS color. As a background, status colors are soft tints; as text/stroke they are strong. `"surface"`, `"surface-strong"`, `"border"`, `"canvas"` and `"on-ink"` are background/paint tokens — use them as backgrounds or SVG fills; as text/icon colors they are ignored and the theme ink is used instead (they are washes and would vanish as text). A background of `"ink"` is an inverted fill and a background of `"chart1"`…`"chart6"` is a solid brand fill: in both cases their content switches to a readable color automatically, so leave child text colors unset (or use `"on-ink"`).
|
|
18
18
|
- **Radius**: `"sm"`, `"md"`, `"lg"`, `"xl"`, `"full"`, or a pixel number.
|
|
19
|
-
- **Length**: a pixel number or a CSS length string
|
|
19
|
+
- **Length**: a pixel number, or a CSS length string — `px`, `%`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax` (and `dvh`/`svh`/`lvh`), `ch`, `ex`, `lh`, `pt`, `pc`, `cm`, `mm`, `in`, `fr` — or a safe `calc()`/`min()`/`max()`/`clamp()` built from them, e.g. `"calc(100% - 32px)"`. `var()`, `url()`, `attr()` and `env()` are rejected, and an unsupported string is ignored (the default size applies).
|
|
20
20
|
- **Spacing**: every `gap` and `padding` argument counts **4px steps** (`gap: 3` = 12px). Inner gap 1–2, group gap 3–4, section gap 5–6. Do not use one gap everywhere.
|
|
21
21
|
|
|
22
22
|
**Rules that apply to every component**
|
|
@@ -66,7 +66,7 @@ Grid(children: Node[], columns?: number, minChildWidth?: number, gap?: number)
|
|
|
66
66
|
|
|
67
67
|
Equal columns (default 2). With minChildWidth (px), columns drop on narrow screens.
|
|
68
68
|
|
|
69
|
-
**Notes.** Equal columns, default 2. `minChildWidth` (px) lets columns drop on the narrow chat card — prefer it over a fixed column count for anything wide.
|
|
69
|
+
**Notes.** Equal columns, default 2. `minChildWidth` (px) lets columns drop on the narrow chat card — prefer it over a fixed column count for anything wide. `columns` is rounded and clamped to 1–12: values above 12 silently become 12.
|
|
70
70
|
|
|
71
71
|
### `Card`
|
|
72
72
|
|
|
@@ -86,7 +86,7 @@ Carousel(children: Node[], itemWidth?: number, gap?: number)
|
|
|
86
86
|
|
|
87
87
|
Horizontal row that scrolls and snaps, each child an item itemWidth px wide (default 240): photos, cards, options, days.
|
|
88
88
|
|
|
89
|
-
**Notes.** Horizontal snap-scrolling row: photos, choices, days. Each child becomes one item `itemWidth` px wide (default 240).
|
|
89
|
+
**Notes.** Horizontal snap-scrolling row: photos, choices, days. Each child becomes one item `itemWidth` px wide (default 240; values below 80 are raised to 80). An explicit `itemWidth` is honored and is not capped to the 85% peek that applies to unsized items.
|
|
90
90
|
|
|
91
91
|
### `Popover`
|
|
92
92
|
|
|
@@ -96,7 +96,7 @@ Popover(trigger: string | Node[], content: string | Node[])
|
|
|
96
96
|
|
|
97
97
|
Shows content in a small panel when the trigger is clicked: a definition, a source, details behind an Icon("info", "sm").
|
|
98
98
|
|
|
99
|
-
**Notes.** Keep the trigger short (an icon or a word); put the aside in the content. Good for sources, definitions and caveats.
|
|
99
|
+
**Notes.** Keep the trigger short (an icon or a word); put the aside in the content. Good for sources, definitions and caveats. The panel is at most 280px wide (narrower on small viewports).
|
|
100
100
|
|
|
101
101
|
### `Divider`
|
|
102
102
|
|
|
@@ -146,7 +146,7 @@ Title(text: string, size?: "sm" | "md" | "lg" | "xl" | "2xl" | "3xl", color?: Co
|
|
|
146
146
|
|
|
147
147
|
Heading; md for a card title, lg for a section, 2xl for a big number.
|
|
148
148
|
|
|
149
|
-
**Notes.** Page title `xl`/`2xl`; card or block title `md`/`sm`. Inside a Card, display sizes use a capped scale — `lg` 18px, `xl` 22px, `2xl` 26px, `3xl` 30px — so `xl` reads as a big number (a KPI) without turning the panel into a page; use it for one number, not for the card heading.
|
|
149
|
+
**Notes.** Page title `xl`/`2xl`; card or block title `md`/`sm`. Inside a `Card`, a `Grid` cell or a `Carousel` item — at any nesting depth, e.g. inside a `Row` — display sizes use a capped scale — `lg` 18px, `xl` 22px, `2xl` 26px, `3xl` 30px — so `xl` reads as a big number (a KPI) without turning the panel into a page; use it for one number, not for the card heading. A nested Card does not apply the scale twice, and a body `Text` inside those containers is 15px.
|
|
150
150
|
|
|
151
151
|
### `Text`
|
|
152
152
|
|
|
@@ -226,7 +226,7 @@ Markdown(text: string)
|
|
|
226
226
|
|
|
227
227
|
Prose with headings, lists, quotes, code and tables.
|
|
228
228
|
|
|
229
|
-
**Notes.** Prose with headings, lists, quotes, tables and code fences. Use for long-form notes; build UI with components, not Markdown.
|
|
229
|
+
**Notes.** Prose with headings, lists, quotes, tables and code fences. Lists nest by indentation, keeping ordered and unordered levels; only h1–h4 have display styles, so h5 and h6 render at the h4 size. Use for long-form notes; build UI with components, not Markdown.
|
|
230
230
|
|
|
231
231
|
### `Quote`
|
|
232
232
|
|
|
@@ -298,7 +298,7 @@ Input(value: $binding<string | number>, label?: string, type?: "text" | "number"
|
|
|
298
298
|
|
|
299
299
|
Text or number field; a number field stores numbers.
|
|
300
300
|
|
|
301
|
-
**Notes.** Text or number field bound to `$var`; a number field stores numbers. Guard counts with `@Default`/`@Clamp` before dividing.
|
|
301
|
+
**Notes.** Text or number field bound to `$var`; a number field stores numbers. A number field accepts a decimal comma — "1,5" is 1.5 — while other commas group digits ("1,000" is 1000); unparseable text keeps the old value. Guard counts with `@Default`/`@Clamp` before dividing.
|
|
302
302
|
|
|
303
303
|
### `TextArea`
|
|
304
304
|
|
|
@@ -306,7 +306,7 @@ Text or number field; a number field stores numbers.
|
|
|
306
306
|
TextArea(value: $binding<string>, label?: string, placeholder?: string, rows?: number)
|
|
307
307
|
```
|
|
308
308
|
|
|
309
|
-
**Notes.** Multi-line text bound to `$var`.
|
|
309
|
+
**Notes.** Multi-line text bound to `$var`. `rows` defaults to 3 and is clamped to 2–20.
|
|
310
310
|
|
|
311
311
|
### `Select`
|
|
312
312
|
|
|
@@ -336,7 +336,7 @@ Slider(value: $binding<number>, min: number, max: number, step?: number, label?:
|
|
|
336
336
|
|
|
337
337
|
Shows label and value; unit like "%" or "$" formats the value.
|
|
338
338
|
|
|
339
|
-
**Notes.** Numeric range bound to `$var`. `unit` formats the value ("%", "$", " kg"); `marks` labels positions.
|
|
339
|
+
**Notes.** Numeric range bound to `$var`. `unit` formats the value ("%", "$", " kg"); `marks` labels positions. The readout shows the bound number as-is (no locale rounding), and an out-of-range bound value is clamped and written back once, so the readout and the state agree.
|
|
340
340
|
|
|
341
341
|
### `Checkbox`
|
|
342
342
|
|
|
@@ -384,9 +384,9 @@ Countdown with start, pause and reset. It counts the bound seconds down to 0, so
|
|
|
384
384
|
Form(children: Node[])
|
|
385
385
|
```
|
|
386
386
|
|
|
387
|
-
Groups fields;
|
|
387
|
+
Groups fields; only a Button's @ToAssistant message text is forwarded, so write the values it needs into that message.
|
|
388
388
|
|
|
389
|
-
**Notes.** Groups fields for a submit Button. See the deployment note in [troubleshooting.md](troubleshooting.md) for
|
|
389
|
+
**Notes.** Groups fields for a submit Button. See the deployment note in [troubleshooting.md](troubleshooting.md) for what @ToAssistant forwards here. In an export with follow-up removal on, the submit Button is removed together with the Form's fields, while prose in the same Card stays.
|
|
390
390
|
|
|
391
391
|
## Media and data (8 components)
|
|
392
392
|
|
|
@@ -396,9 +396,9 @@ Groups fields; their values go with any @ToAssistant inside.
|
|
|
396
396
|
SearchImage(query: string, aspectRatio?: number, radius?: Radius, fit?: "cover" | "contain")
|
|
397
397
|
```
|
|
398
398
|
|
|
399
|
-
A real photo the app finds for query; it needs no URL and no tool. Name the exact thing in 2 to 4 words: "Belém Tower Lisbon", "iPhone 17", "pastel de nata". Use one for
|
|
399
|
+
A real photo the app finds for query; it needs no URL and no tool. Name the exact thing in 2 to 4 words: "Belém Tower Lisbon", "iPhone 17", "pastel de nata". Use one for a place, dish, product or thing with a look; treat it as feature media, not one photo per list row.
|
|
400
400
|
|
|
401
|
-
**Notes.** A real photo found by the app. Name the exact subject in 2–4 words; there is no URL and no tool call. Offline it degrades to an icon placeholder.
|
|
401
|
+
**Notes.** A real photo found by the app. Name the exact subject in 2–4 words; there is no URL and no tool call. Offline it degrades to an icon placeholder. `aspectRatio` is clamped to 0.05–20.
|
|
402
402
|
|
|
403
403
|
### `Image`
|
|
404
404
|
|
|
@@ -408,7 +408,7 @@ Image(src: string, alt: string, aspectRatio?: number, radius?: Radius, fit?: "co
|
|
|
408
408
|
|
|
409
409
|
Photo from a URL the user or a tool gave; if it fails, a photo is found for alt.
|
|
410
410
|
|
|
411
|
-
**Notes.** Photo from a URL the user or a tool gave; if it fails, the app searches by `alt`.
|
|
411
|
+
**Notes.** Photo from a URL the user or a tool gave; if it fails, the app searches by `alt`. `aspectRatio` is clamped to 0.05–20.
|
|
412
412
|
|
|
413
413
|
### `Icon`
|
|
414
414
|
|
|
@@ -428,7 +428,7 @@ Table(columns: string[], rows: any[][])
|
|
|
428
428
|
|
|
429
429
|
Each row lists its cells in column order; a cell may be a component. Number columns align right.
|
|
430
430
|
|
|
431
|
-
**Notes.** Rows are cell arrays in column order; a cell may be a component (Badge, Text). Number columns right-align.
|
|
431
|
+
**Notes.** Rows are cell arrays in column order; a cell may be a component (Badge, Text). Number columns right-align. A number cell renders raw — no grouping or rounding — so format values with `@Format` yourself. Right-alignment is a heuristic: a column goes numeric only when every non-empty cell is a number or a numeric-looking string, so IDs, years and ranks ("007", "2024") align right too, with no per-column override — one non-numeric cell (a name, "TBD") turns the column left.
|
|
432
432
|
|
|
433
433
|
### `Chart`
|
|
434
434
|
|
|
@@ -436,9 +436,9 @@ Each row lists its cells in column order; a cell may be a component. Number colu
|
|
|
436
436
|
Chart(type: "bar" | "line" | "area" | "pie" | "donut" | "scatter", data: Record<string, string | number>[], x?: string, series?: string[], format?: "number" | "currency" | "percent", currency?: string, stacked?: boolean, height?: number)
|
|
437
437
|
```
|
|
438
438
|
|
|
439
|
-
Rows of data; x is the category key (a number key for scatter), series the value keys (default: every
|
|
439
|
+
Rows of data; x is the category key (a number key for scatter), series the value keys (default: every numeric key across rows, in first-seen order). percent values are like 45; currency is a code like "EUR".
|
|
440
440
|
|
|
441
|
-
**Notes.** Rows of `{xKey: category, seriesKey: number}`. `x` names the category key, `series` the value keys (default: every
|
|
441
|
+
**Notes.** Rows of `{xKey: category, seriesKey: number}`. `x` names the category key, `series` the value keys (default: every numeric key across rows), `format` "number"|"currency"|"percent", `stacked` for bars/areas, `height` in px (default 240, clamped 140–480; pie/donut ignore it). Stacked bars/areas accumulate positive and negative values separately, so negatives stay visible below zero. Category labels are sampled (every n-th band) so they never overlap: a skipped label is not drawn, has no tooltip, and cannot be forced on. Pie/donut use only `series[0]` — extra numeric keys are ignored, so give a pie one explicit value key.
|
|
442
442
|
|
|
443
443
|
### `Map`
|
|
444
444
|
|
|
@@ -448,7 +448,7 @@ Map(markers: MapMarker[], route?: boolean, selected?: $binding<string>, height?:
|
|
|
448
448
|
|
|
449
449
|
Street map fitted to its markers. route draws the road path in marker order; selected holds the clicked marker's label.
|
|
450
450
|
|
|
451
|
-
**Notes.** Needs MapMarker children. `route` draws a street route in marker order; `selected` is a `$` binding holding the clicked label. Tiles or routing failing degrades to a place list/direct lines.
|
|
451
|
+
**Notes.** Needs MapMarker children. `route` draws a street route in marker order; `selected` is a `$` binding holding the clicked label. Tiles or routing failing degrades to a place list/direct lines. `height` in px (default 400, clamped 200–720 and capped at `max(280px, 82vw)`).
|
|
452
452
|
|
|
453
453
|
### `MapMarker`
|
|
454
454
|
|
|
@@ -458,7 +458,7 @@ MapMarker(label: string, lat: number, lng: number, category?: string, icon?: str
|
|
|
458
458
|
|
|
459
459
|
A place on a Map; icon is one emoji, else the pin shows its number.
|
|
460
460
|
|
|
461
|
-
**Notes.** A pin: label, lat, lng, optional category, optional emoji icon. Numbered pins are drawn with a digit.
|
|
461
|
+
**Notes.** A pin: label, lat, lng, optional category, optional emoji icon. Numbered pins are drawn with a digit. Long labels are ellipsized on one line (max 160px, 120px on viewports ≤520px), so keep labels short and recognizable.
|
|
462
462
|
|
|
463
463
|
### `YouTube`
|
|
464
464
|
|
|
@@ -468,7 +468,7 @@ YouTube(video: string, title?: string)
|
|
|
468
468
|
|
|
469
469
|
Embedded YouTube video by id or URL. Only a video you know exists.
|
|
470
470
|
|
|
471
|
-
**Notes.** Embed by video id or URL. Only videos that are known to exist.
|
|
471
|
+
**Notes.** Embed by video id, or a `watch`, `youtu.be`, `/embed/`, `/shorts/` or `/live/` URL. Only videos that are known to exist.
|
|
472
472
|
|
|
473
473
|
## Play (2 components)
|
|
474
474
|
|
|
@@ -480,7 +480,7 @@ Flashcard(front: string | Node[], back: string | Node[], hint?: string)
|
|
|
480
480
|
|
|
481
481
|
Card that flips between front and back when tapped. Put several in a Carousel or Grid.
|
|
482
482
|
|
|
483
|
-
**Notes.** Tap to flip. Put several in a Carousel or Grid for a deck. `hint` shows before the flip.
|
|
483
|
+
**Notes.** Tap, or press Enter/Space, to flip. The outer control is a `div role="button"`, so a card may contain its own interactive controls (`Button`, `Pressable`, `Input`) without invalid nesting. Put several in a Carousel or Grid for a deck. `hint` shows before the flip.
|
|
484
484
|
|
|
485
485
|
### `Celebration`
|
|
486
486
|
|
|
@@ -502,7 +502,7 @@ Svg(children: Node[], viewBox: string, width?: Length, height?: Length)
|
|
|
502
502
|
|
|
503
503
|
A drawing for steps, parts, mechanisms, diagrams and layouts. Scales to its width; its shapes take expressions, so state can move them.
|
|
504
504
|
|
|
505
|
-
**Notes.** Scaled drawing canvas. `viewBox` like "0 0 240 160"; shapes take expressions, so state can move them.
|
|
505
|
+
**Notes.** Scaled drawing canvas. `viewBox` like "0 0 240 160"; shapes take expressions, so state can move them. An explicit `width` larger than the available column renders at the column width — a responsive cap, not a bug — so split the drawing or use a `Grid` when the canvas must be larger; without a `width` it fills the column up to about 1.5× its viewBox (at least 280px), and an unsupported width string is ignored (the default sizing applies).
|
|
506
506
|
|
|
507
507
|
### `G`
|
|
508
508
|
|
|
@@ -584,7 +584,7 @@ SvgText(text: string, x: number, y: number, size?: number, fill?: Color, anchor?
|
|
|
584
584
|
HtmlView(html: string, height?: number, title?: string)
|
|
585
585
|
```
|
|
586
586
|
|
|
587
|
-
Sandboxed HTML page with inline JS, for games and canvas.
|
|
587
|
+
Sandboxed HTML page with inline JS, for games and canvas. The sandbox loads CDN scripts and styles, Google Fonts and any https image; no other network. Fits its content unless height is set.
|
|
588
588
|
|
|
589
589
|
**Notes.** The iframe has an opaque origin (no access to the chat or its storage), its CSP allows inline code, a few script/style/font CDNs and https images, but no other network. Its height is clamped to 80–2400 px, and it mounts once the program has finished arriving.
|
|
590
590
|
|
|
@@ -611,7 +611,7 @@ Provided by the language runtime; available everywhere. Data functions compose:
|
|
|
611
611
|
|
|
612
612
|
## Library `@functions` (59)
|
|
613
613
|
|
|
614
|
-
Shipped with this component library (generated from `vendor/spec.json`). These are the ONLY functions available beyond the core set — you cannot define your own.
|
|
614
|
+
Shipped with this component library (generated from `vendor/spec.json`). These are the ONLY functions available beyond the core set — you cannot define your own. A call with invalid or out-of-domain arguments evaluates to `null` instead of failing the page — guard the value with `@Default` when a blank is not acceptable.
|
|
615
615
|
|
|
616
616
|
| Function | Signature | Use |
|
|
617
617
|
| --- | --- | --- |
|
|
@@ -658,7 +658,7 @@ Shipped with this component library (generated from `vendor/spec.json`). These a
|
|
|
658
658
|
| `@MixColor` | `MixColor(from: string, to: string, t: number) → string` | The hex color a fraction t of the way from one hex color to another, e.g. @MixColor("#ffffff", "#0285ff", 0.5) for a heatmap or a tint |
|
|
659
659
|
| `@Now` | `Now() → string` | The current date and time as an ISO string |
|
|
660
660
|
| `@Today` | `Today() → string` | Today's date in the viewer's time zone, as "YYYY-MM-DD" |
|
|
661
|
-
| `@FormatDate` | `FormatDate(date: string \| number, style?: "date" \| "short" \| "long" \| "weekday" \| "month" \| "time" \| "datetime" \| "iso") → string` | A date as text: "date" Oct 9, 2026 (default), "short" Oct 9, "long" Friday, October 9, 2026, "weekday" Fri, "month" Oct 2026, "time" 9:30 PM, "datetime", "iso" 2026-10-09. Dates are "YYYY-MM-DD", ISO or a timestamp |
|
|
661
|
+
| `@FormatDate` | `FormatDate(date: string \| number, style?: "date" \| "short" \| "long" \| "weekday" \| "month" \| "time" \| "datetime" \| "iso") → string` | A date as text: "date" Oct 9, 2026 (default), "short" Oct 9, "long" Friday, October 9, 2026, "weekday" Fri, "month" Oct 2026, "time" 9:30 PM, "datetime", "iso" 2026-10-09. Dates are "YYYY-MM-DD", ISO or a timestamp. An empty or invalid value returns "" instead of failing the card |
|
|
662
662
|
| `@AddDays` | `AddDays(date: string \| number, days: number) → string` | The date days later (negative: earlier), as "YYYY-MM-DD" |
|
|
663
663
|
| `@AddMonths` | `AddMonths(date: string \| number, months: number) → string` | The date months later (negative: earlier), kept within the month (Jan 31 + 1 is Feb 28), as "YYYY-MM-DD"; 12 months is a year |
|
|
664
664
|
| `@DaysBetween` | `DaysBetween(from: string \| number, to: string \| number) → number` | Calendar days from one date to another (negative if to is earlier) |
|
|
@@ -9,7 +9,7 @@ The same package ships the Agent Skill in `skills/intelligent-ui/`. A deployment
|
|
|
9
9
|
|
|
10
10
|
## Current status
|
|
11
11
|
|
|
12
|
-
**Published.** `@zephinel/dsh-intelligent-ui@0.
|
|
12
|
+
**Published.** `@zephinel/dsh-intelligent-ui@0.5.0` is on npm and the repository is public at `Zephinel/dsh-intelligent-ui`. Prefer the npm or GitHub bundle install below; the local-checkout flow remains available for development.
|
|
13
13
|
|
|
14
14
|
## Requirements
|
|
15
15
|
|
|
@@ -52,9 +52,9 @@ The browser half follows DSH's UI language and needs no configuration:
|
|
|
52
52
|
The package declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, and that patch inserts the host row `id: intelligent-ui` with `name: '@zephinel/dsh-intelligent-ui'`. Installing the repository as a bundle installs the package into the profile and selects it in the profile's ordered layer list:
|
|
53
53
|
|
|
54
54
|
```sh
|
|
55
|
-
# npm (current latest: 0.
|
|
55
|
+
# npm (current latest: 0.5.0)
|
|
56
56
|
dsh plugin --profile web add @zephinel/dsh-intelligent-ui
|
|
57
|
-
dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.
|
|
57
|
+
dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.5.0 # pin a version
|
|
58
58
|
# or GitHub
|
|
59
59
|
dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
|
|
60
60
|
```
|
|
@@ -73,7 +73,7 @@ If DSH refuses the package for version incompatibility, either install a compati
|
|
|
73
73
|
|
|
74
74
|
```sh
|
|
75
75
|
dsh plugin --profile web version-exemptions
|
|
76
|
-
dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.
|
|
76
|
+
dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.5.0 --dsh-version 0.2.1-rc.2 --accept-risk
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
Remove it with the mirror command:
|
|
@@ -121,7 +121,7 @@ dsh --profile web --dump-config | grep -n intelligent-ui # the entry must be c
|
|
|
121
121
|
Verification checklist (remember the switch is off by default):
|
|
122
122
|
|
|
123
123
|
0. **Switch present.** The composer shows the **UI** chip in `conversation.input.activity`; its menu offers **Off**, **This session only**, and **All sessions** (localized: 「关闭 / 仅本会话 / 全部会话」 in a Chinese UI). Pick **This session only** (or run `/iui on`) before checking the tool and prompt; with the switch off, steps 1–2 are expected to *fail* by design. The Plugin detail page exposes the global enablement switch, the default Answer style and Free-form layout.
|
|
124
|
-
1. **Tool present while on.** With the switch admitting the session, it exposes `render_ui` with the argument schema `{ program: string, style: "card"|"article", title?: string, styleId?: string, temporaryStyle?: StyleSnapshot }`.
|
|
124
|
+
1. **Tool present while on.** With the switch admitting the session, it exposes `render_ui` with the argument schema `{ program: string, style: "card"|"article"|"free", title?: string, styleId?: string, temporaryStyle?: StyleSnapshot }`. Authorized new on-demand generation requires free layout; adjustments preserve the registered parent layout. Both override session style guidance; otherwise the effective style is built-in or a visible saved template; Auto requires the model to pass the concrete card/article style it chose. The model-facing description starts "Render an interactive answer as UI in the chat". With the switch off (or scoped to another session), the request tool list must **not** contain `render_ui`.
|
|
125
125
|
2. **Prompt present while on.** With the switch on, the composed system prompt contains the OpenUI Lang section (order 3100) with the 57-component catalog and the effective style note; with the switch off the section resolves to an empty string.
|
|
126
126
|
3. **Card works.** Ask the model to render a trivial page, or let the skill lead it. The turn ends with a card titled by `title` (or the localized default "Interactive answer" / 「交互式回答」) containing the rendered UI; the process area shows one such row, not the raw program.
|
|
127
127
|
4. **Skill present.** When the profile composes the skill registry, the session catalog lists `intelligent-ui`; loading it returns the body of `skills/intelligent-ui/SKILL.md`. Without a skill service the tool still works and only the catalog entry is missing.
|
|
@@ -152,13 +152,13 @@ Filesystem discovery is only a **manual fallback** for an environment where the
|
|
|
152
152
|
| Aspect | Contract |
|
|
153
153
|
| --- | --- |
|
|
154
154
|
| Name | `render_ui` |
|
|
155
|
-
| Arguments | `{ "program": string, "style": "card"|"article", "title"?: string, "styleId"?: string, "temporaryStyle"?: StyleSnapshot }`, `required: ["program", "style"]`, `additionalProperties: false` |
|
|
155
|
+
| Arguments | `{ "program": string, "style": "card"|"article"|"free", "title"?: string, "styleId"?: string, "temporaryStyle"?: StyleSnapshot }`, `required: ["program", "style"]`, `additionalProperties: false` |
|
|
156
156
|
| `program` | One complete OpenUI Lang program, statement per line, `root` first. Passed verbatim by the model; persisted as the tool call's arguments and replayed from history. |
|
|
157
157
|
| `title` | Optional short card label, e.g. "Day in San Francisco". When omitted the client uses the localized default ("Interactive answer" / 「交互式回答」). |
|
|
158
|
-
| `style` | `"card"` or `"
|
|
158
|
+
| `style` | `"card"`, `"article"` or `"free"`; required. Free is accepted with an authorized temporary snapshot or the exact styleId of the selected free template (without temporaryStyle), without Card compactness or mandatory Toc/Section. Pass the effective base layout from the prompt; a Host-authorized temporary snapshot overrides the selected style only for that result. In Auto pass the style you chose. |
|
|
159
159
|
| `styleId` | Exact selected custom template id; omit for built-in or temporary styles. Mutually exclusive with temporaryStyle. |
|
|
160
|
-
| `temporaryStyle` | Host-authorized schemaVersion 1 snapshot: baseLayout equals style, reusable directives,
|
|
161
|
-
| Success value | `{ "statements": number, "style": "card"|"article", "styleSource"?: "builtin"|"template"|"temporary", "styleId"?: string, "warnings"?: string[] }` — the parsed statement count, the resolved style recorded with the page, and any non-fatal findings (`Unresolved reference: …`, `Unreferenced statement (will not render): …`). |
|
|
160
|
+
| `temporaryStyle` | Host-authorized schemaVersion 1 snapshot: baseLayout equals style (Host-enforced `free` for new generation; adjustments must match the registered parent snapshot layout, including legacy card/article), reusable directives, optional theme (omitted = inherit the session theme; when passed it must be complete and contrast-checked), optional suggestedName. A snapshot without a theme cannot become a style template. Missing or evicted parents reject adjustment with an error asking the user to cancel and start a new on-demand generation. Model arguments cannot authorize an operation. |
|
|
161
|
+
| Success value | `{ "statements": number, "style": "card"|"article"|"free", "styleSource"?: "builtin"|"template"|"temporary", "styleId"?: string, "warnings"?: string[] }` — the parsed statement count, the resolved style recorded with the page, and any non-fatal findings (`Unresolved reference: …`, `Unreferenced statement (will not render): …`). |
|
|
162
162
|
| Model-visible result | `Interactive UI rendered for the user (<n> statements, <style> style).` plus ` Notes: <warnings joined by "; ">` when warnings exist. |
|
|
163
163
|
| Empty/failed validation | Throws `Error: render_ui: …`; the model sees the message as a tool error and is expected to fix and retry in the same turn. |
|
|
164
164
|
| Validation | `createParser(componentSpecSchema, "Col")` from `@openuidev/lang-core`; the spec is generated from `vendor/spec.json` at build time and compiled into `lib/index.js`. Fatal findings are parser errors, `incomplete: true`, and an unresolved root. Warnings never block rendering. |
|
|
@@ -172,15 +172,15 @@ Filesystem discovery is only a **manual fallback** for an environment where the
|
|
|
172
172
|
| Surface | Current contract |
|
|
173
173
|
| --- | --- |
|
|
174
174
|
| Catalog | `GET /api/intelligent-ui/styles?sessionId=<id>` → `{ templates }` visible globally or in that session. Requires webServer + connection authentication. |
|
|
175
|
-
| Save from result | `POST /api/intelligent-ui/styles`, `{ op: "saveFromResult", resultId, name, description?, scope: "global"|"session", sessionId? }` → 201 `{ template }`. Host copies
|
|
175
|
+
| Save from result | `POST /api/intelligent-ui/styles`, `{ op: "saveFromResult", resultId, name, description?, scope: "global"|"session", sessionId? }` → 201 `{ template }`. Host copies baseLayout/directives/theme exactly from the validated snapshot, including free. A snapshot without a theme answers 400 `no_theme`: a template needs its own palette, so the UI hides Save for those results. All results reject a client `baseLayout` field; the dialog only asks for name/description/scope. Free templates keep the DSH card header with no Card/Article shell or required Toc/Section, and use styleId without temporaryStyle or temporary actions. The result snapshot stays unchanged; no theme/directives/revisionId accepted. Session scope requires the owning sessionId. No automatic selection/default write or model call. Duplicate names fail; no server idempotency key. |
|
|
176
176
|
| Save | Same POST with `{ op: "save", template: { name, description?, baseLayout, directives, theme }, scope, sessionId? }`. Validated persistence API, not a model creation workflow. |
|
|
177
177
|
| Update | Same POST with `{ op: "update", id, patch: { name?, description?, directives? } }`; only these fields may change; returns `{ template }`. |
|
|
178
178
|
| Delete | Same POST with `{ op: "delete", id }` → `{ deleted: id }`; missing template returns 404. |
|
|
179
179
|
| Route limits | Auth checked first; GET/POST only, application/json, 64 KiB maximum body, 15-second read timeout, no-store. No draft/LLM interview routes. |
|
|
180
|
-
| Stores | `<DSH_HOME>/dsh-intelligent-ui-styles.json`: 40 global/20 per-session templates. `dsh-intelligent-ui-results.json`: latest 200 immutable temporary result snapshots with resultId (= callId), sessionId, optional parentResultId and createdAt. Evicted results return `result_missing` when saved. |
|
|
180
|
+
| Stores | `<DSH_HOME>/dsh-intelligent-ui-styles.json`: version 1 with card/article/free baseLayout (no migration); 40 global/20 per-session templates. `dsh-intelligent-ui-results.json`: latest 200 immutable temporary result snapshots with resultId (= callId), sessionId, optional parentResultId and createdAt. Evicted results return `result_missing` when saved and reject adjustment; historical tool arguments still replay. |
|
|
181
181
|
| Operation | `/iui on-demand [off|<client-instance-token> [adjust <resultId>]]`; one active operation per session, armed TTL 10 minutes, up to two clarification rounds. While armed, re-arm replaces; once bound (running/clarifying), re-arm is rejected and needs an explicit cancel. A completed turn that produced no render returns to armed with `resume: true`; the hint stays and the next human message continues the same operation. In-memory states: armed/running/clarifying/completed/failed/cancelled/interrupted. Restart clears operation views; re-arm to continue. |
|
|
182
|
-
| Event binding | Live session/event binds the next human message; ignores injected context, deduplicates seq and constrains tool events by turn. The prompt note is injected while armed because DSH appends the system prompt before the first user/message; it requires content grounding (never fabricate missing data) and, for missing text/link content, a free-form question with no options. A bound on-demand turn rejects a plain render without temporaryStyle. Observed callId + bound operation authorize temporaryStyle. Structured ask_user_question answers resume the operation; pending questions block render. A text-only completed turn re-arms with `resume` and keeps the composer hint until a result renders or the user cancels. Failed/interrupted operations keep a retry/dismiss hint instead of vanishing. Client token limits hint visibility, not the source of the next session message. |
|
|
183
|
-
| Theme boundary | Controlled theme variables apply to the renderer host; portaled popovers and sandboxed iframes retain default theme. Export freezes the resolved per-card theme/scheme, temporary snapshots
|
|
182
|
+
| Event binding | Live session/event binds the next human message; ignores injected context, deduplicates seq and constrains tool events by turn. The prompt note is injected while armed because DSH appends the system prompt before the first user/message; it requires content grounding (never fabricate missing data) and, for missing text/link content, a free-form question with no options. Presentation follows the user request; if materially unclear, ask a focused layout question rather than silently defaulting. New generation passes style/baseLayout free. A bound on-demand turn rejects a plain render without temporaryStyle. Observed callId + bound operation authorize temporaryStyle. Structured ask_user_question answers resume the operation; pending questions block render. A text-only completed turn re-arms with `resume` and keeps the composer hint until a result renders or the user cancels. Failed/interrupted operations keep a retry/dismiss hint instead of vanishing. Client token limits hint visibility, not the source of the next session message. |
|
|
183
|
+
| Theme boundary | Controlled theme variables apply to the renderer host; portaled popovers and sandboxed iframes retain default theme. Export freezes the resolved per-card theme/scheme: snapshot theme first, then the saved or session-selected template theme (theme-less temporary snapshots included), then the built-in theme. |
|
|
184
184
|
| Prompt boundary | Saved-template directives are JSON-quoted bounded display preferences subordinate to system/tool/safety rules. Temporary directives stay result data. Models may render authorized snapshots; saving/management belongs to explicit user actions. |
|
|
185
185
|
|
|
186
186
|
## Troubleshooting a missing `render_ui`
|
|
@@ -208,6 +208,7 @@ Work top-down; each step rules out one layer:
|
|
|
208
208
|
- `Math` relies on the host's global KaTeX styles; if a future DSH shell drops them, formulas degrade to text.
|
|
209
209
|
- This extension is web-only: profiles without a browser surface register the tool but have no card to render into.
|
|
210
210
|
- The browser half requires the client locale service (`dsh-client-locale`); a minimal custom profile without it will not mount the switch or the card, while the Host tool and prompt keep working.
|
|
211
|
-
- Interactive pages are self-contained but large (about 3.4–4.9 MB) and keep only the exporting theme; their photos, maps and routing still use the same third-party services as inside DSH.
|
|
211
|
+
- Interactive pages are self-contained but large (about 3.4–4.9 MB) and keep only the exporting theme; non-free cards keep the 760px measure and the live 12px card gap, free results use the full page width, and their photos, maps and routing still use the same third-party services as inside DSH.
|
|
212
|
+
- **Image export follows the live cards, not the whole page.** Portaled overlays — an open `Popover` panel and `Celebration` confetti live on `<body>` — are visible on screen but absent from the saved PNG; everything inside the card, including an expanded `Map` dialog, is captured.
|
|
212
213
|
- The `/iui` Host replies and the command palette's command description stay English even in a Chinese UI; both are DSH platform behavior, and the command palette localizes only first-party commands by identity.
|
|
213
|
-
- The package is published on npm as `@zephinel/dsh-intelligent-ui@0.
|
|
214
|
+
- The package is published on npm as `@zephinel/dsh-intelligent-ui@0.5.0`; pin a version for reproducibility. Publishing a new version needs a version bump plus the packaging checks in `test/packaging/`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Troubleshooting
|
|
2
2
|
|
|
3
|
-
`render_ui` either returns a success value or throws. A thrown error is the host's own message, verbatim: read the quoted fragment, fix the named problem, and call again in the same turn. A success can still carry parser warnings; treat those as bugs too.
|
|
3
|
+
`render_ui` either returns a success value or throws. A thrown error is the host's own message, verbatim: read the quoted fragment, fix the named problem, and call again in the same turn, or request the user action named by an operation error below. A success can still carry parser warnings; treat those as bugs too.
|
|
4
4
|
|
|
5
5
|
## The retry loop
|
|
6
6
|
|
|
@@ -44,14 +44,24 @@ These messages are copied from the current Host. Authorization and schema failur
|
|
|
44
44
|
```text
|
|
45
45
|
render_ui: styleId and temporaryStyle are mutually exclusive.
|
|
46
46
|
render_ui: temporaryStyle requires a bound, running on-demand operation and its current tool call. The model cannot authorize one.
|
|
47
|
-
render_ui: invalid temporaryStyle
|
|
47
|
+
render_ui: invalid temporaryStyle: <field-specific reason>. Pass schemaVersion 1, baseLayout, and non-empty directives; add a theme (light and dark palettes plus font, radius, density and shadow) only when the page should not inherit the session theme.
|
|
48
48
|
render_ui: temporaryStyle.baseLayout must match style.
|
|
49
|
+
render_ui: on-demand generation requires style: "free" and temporaryStyle.baseLayout: "free"; card/article layouts are only supported when adjusting an existing result.
|
|
49
50
|
render_ui: on-demand operation was cancelled or replaced before completion.
|
|
50
51
|
render_ui: this turn is an on-demand UI request; pass a complete temporaryStyle with a matching style (omit styleId), or ask the user a clarifying question first.
|
|
51
52
|
```
|
|
52
53
|
|
|
53
54
|
Use only one style source. A temporary snapshot needs a Host-armed operation bound to the human message and current observed `render_ui` call; the model cannot self-authorize. Ask the user to re-arm in the composer after expiry, cancellation or restart. A text-only fallback turn keeps the operation pending (resume) so the next message can continue without re-arming; retry is offered for failed/interrupted turns. A structured question still awaiting an answer blocks rendering; wait for the built-in `ask_user_question` answer first. Match `baseLayout` and `style`, use only schemaVersion 1/controlled theme tokens and bounded reusable directives; omit styleId.
|
|
54
55
|
|
|
56
|
+
Adjustment errors identify the stored parent layout or an unavailable parent; for a legacy Card parent and a missing result named `old-result`:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
render_ui: on-demand adjustment must preserve the parent result layout; pass style: "card" and temporaryStyle.baseLayout: "card".
|
|
60
|
+
render_ui: cannot adjust result "old-result": its parent snapshot is unavailable in the result registry. Ask the user to cancel this adjustment and start a new on-demand generation.
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Retry layout mismatches using both required fields. Adjustments must retain the parent snapshot's free/card/article layout. Missing or evicted snapshots cannot be recovered from model arguments or conversation content: ask the user to cancel and start a new **On-demand UI** generation. Rejection does not record a result or complete the operation; historical replay remains available.
|
|
64
|
+
|
|
55
65
|
For the light ink pair, the exact contrast error is below; the same format uses `dark` and/or `accent` for the other pairs:
|
|
56
66
|
|
|
57
67
|
```text
|
|
@@ -78,6 +88,7 @@ Invalid on-demand adjustment parent result id.
|
|
|
78
88
|
An on-demand UI operation is already running in this session; wait for it to finish or cancel it first.
|
|
79
89
|
Too many active on-demand operations. Cancel one and retry.
|
|
80
90
|
This result snapshot is no longer available.
|
|
91
|
+
This result has no explicit theme, so it cannot become a style template. Adjust it with a theme first, then save.
|
|
81
92
|
A style with this name already exists.
|
|
82
93
|
The style library has reached its scope limit.
|
|
83
94
|
The session must match the result.
|
|
@@ -254,7 +265,7 @@ These are not errors to fix in the program; they are how the card behaves when t
|
|
|
254
265
|
| HtmlView shows `Preparing the interactive view…`(「正在准备交互视图…」) | Normal: the iframe mounts once the program has finished arriving. | Nothing. |
|
|
255
266
|
| Math renders as plain text | KaTeX inherits the host's global styles; if they are absent the formula degrades. | Prefer plain text for casual math; use `Math` for real formulas. |
|
|
256
267
|
| Clipboard write fails | `@CopyToClipboard` falls back to `document.execCommand("copy")`. | Nothing; it is best-effort. |
|
|
257
|
-
| A `render_ui` program crashes while rendering | The
|
|
268
|
+
| A `render_ui` program crashes while rendering | The failing subtree disappears or keeps its last valid render; a renderer-level crash additionally shows `This generated UI could not be rendered.`(「生成的 UI 无法渲染。」)with the message and a collapsible `Show the UI program`(「显示 UI 程序」). | The success result carries no finding — you cannot detect this crash yourself. Recovery is user-initiated: when the user reports it, simplify the offending component (usually a Chart with malformed data or an Svg with invalid path text) in the next turn. |
|
|
258
269
|
| `@ToAssistant` follow-up misses the form values | Only the message string is forwarded in this deployment; the optional `context` object is not delivered. | Build the message from the bindings: `@ToAssistant("Plan for " + $people + " people")`. |
|
|
259
270
|
|
|
260
271
|
## Rendered but wrong
|
|
@@ -269,5 +280,11 @@ No error appears, yet the page is not what you intended. Check these in order:
|
|
|
269
280
|
6. **Conditional nulls** — a ternary in a children array is fine, but a top-level statement that evaluates to `null` and is then referenced as a component breaks the page. Keep ternaries inside children arrays.
|
|
270
281
|
7. **Empty state** — `@Sum`, `@Avg` and `@Count` over an empty array return `0`; division by a count needs a guard (`$people > 0 ? ... : 1`). `@Pick([])` returns `null`, and `@First([])` returns `null`; provide a fallback with `@Default` or a ternary.
|
|
271
282
|
8. **Dates** — comparisons are numeric; order dates with `@DaysBetween(a, b) > 0`, and format them with `@FormatDate`.
|
|
283
|
+
9. **Silent `null` from a function** — a `@function` call with a wrong-typed or out-of-domain argument (for example `@Sum($items.score)` when `score` holds strings, or `@Range(0, 5, 0)`) evaluates to `null` with no warning, so the surrounding `Text` or KPI renders blank while the tool reports success. Check that the fields are numbers before aggregating and fall back with `@Default(expr, neutral)` where a blank is not acceptable.
|
|
272
284
|
|
|
273
285
|
If the page is merely visually weak, do not re-call for cosmetic fixes: choose better blocks next turn ([SKILL.md](../SKILL.md#design-playbook) has the composition rules).
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
### Free saved templates
|
|
289
|
+
|
|
290
|
+
A selected free template requires `style: "free"` and its exact `styleId`, without `temporaryStyle`. A Card/Article selection still rejects free; a built-in selection cannot authorize free by adding an arbitrary styleId. Free templates require no Toc/Section or Article wrapper. Saving a result copies the registered layout, directives and theme; a theme-less result has no palette to copy, so the client hides Save and the API answers `no_theme`. A legacy client sending `baseLayout` receives `invalid_input` and must reload the updated client. Missing/deleted templates retain the existing default-theme fallback.
|