@zephinel/dsh-intelligent-ui 0.4.2 → 0.6.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/NOTICE +7 -0
- package/README.en.md +141 -102
- package/README.md +136 -97
- package/assets/intelligent-ui-components-layout.webp +0 -0
- package/assets/intelligent-ui-dashboard-en.webp +0 -0
- package/assets/intelligent-ui-dashboard-zh.webp +0 -0
- package/assets/intelligent-ui-editing-en.webp +0 -0
- package/assets/intelligent-ui-editing-zh.webp +0 -0
- package/assets/intelligent-ui-itinerary-en.webp +0 -0
- package/assets/intelligent-ui-itinerary-zh.webp +0 -0
- package/assets/intelligent-ui-on-demand-hint.webp +0 -0
- package/assets/intelligent-ui-quiz-en.webp +0 -0
- package/assets/intelligent-ui-quiz-zh.webp +0 -0
- package/assets/intelligent-ui-readme-components.webp +0 -0
- package/assets/intelligent-ui-readme-controls.webp +0 -0
- package/assets/intelligent-ui-readme-generation-en.webp +0 -0
- package/assets/intelligent-ui-readme-generation-zh.webp +0 -0
- package/assets/intelligent-ui-readme-overview-en.webp +0 -0
- package/assets/intelligent-ui-readme-overview-zh.webp +0 -0
- package/assets/intelligent-ui-readme-temporary.webp +0 -0
- package/assets/intelligent-ui-real-dashboard-en.webp +0 -0
- package/assets/intelligent-ui-real-dashboard-zh.webp +0 -0
- package/assets/intelligent-ui-real-itinerary-en.webp +0 -0
- package/assets/intelligent-ui-real-itinerary-zh.webp +0 -0
- package/assets/intelligent-ui-real-quiz-en.webp +0 -0
- package/assets/intelligent-ui-real-quiz-zh.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 +151 -134
- package/lib/index.js +108 -70
- package/lib/standalone.css +1 -1
- package/lib/standalone.js +133 -133
- package/licenses/remix-icon-LICENSE +186 -0
- package/package.json +11 -4
- package/skills/intelligent-ui/SKILL.md +61 -32
- package/skills/intelligent-ui/references/components.md +34 -34
- package/skills/intelligent-ui/references/integration.md +33 -30
- package/skills/intelligent-ui/references/troubleshooting.md +30 -4
|
@@ -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**
|
|
@@ -46,7 +46,7 @@ Row(children: Node[], gap?: number, align?: "start" | "center" | "end" | "stretc
|
|
|
46
46
|
|
|
47
47
|
Horizontal layout; items are vertically centered.
|
|
48
48
|
|
|
49
|
-
**Notes.** Horizontal flex row; set `wrap` for badge rows that may not fit. Use `Spacer()` to push items apart.
|
|
49
|
+
**Notes.** Horizontal flex row; set `wrap` for badge rows that may not fit. Use `Spacer(width?: Length, height?: Length)` to push items apart.
|
|
50
50
|
|
|
51
51
|
### `Box`
|
|
52
52
|
|
|
@@ -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,25 +96,25 @@ 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
|
|
|
103
103
|
```
|
|
104
|
-
Divider()
|
|
104
|
+
Divider(color?: Color, width?: Length, thickness?: number)
|
|
105
105
|
```
|
|
106
106
|
|
|
107
|
-
**Notes.** A horizontal rule.
|
|
107
|
+
**Notes.** A horizontal rule. `color` takes a theme token or CSS colour, `width` a px number or a percentage (centred when narrowed) and `thickness` 0.5–12 px; omit an argument for the theme default. For `width`, omit it for no explicit length (the rule keeps the layout default), use px for a fixed size, or a percentage for a share of the container.
|
|
108
108
|
|
|
109
109
|
### `Spacer`
|
|
110
110
|
|
|
111
111
|
```
|
|
112
|
-
Spacer()
|
|
112
|
+
Spacer(width?: Length, height?: Length)
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
Fills the free space in a Row.
|
|
115
|
+
Fills the free space in a Row. Set `width`/`height` to a px number or a percentage to turn it into a fixed gap instead of a flexible one; omit them to keep the flexible default.
|
|
116
116
|
|
|
117
|
-
**Notes.** Fills the free space in a Row; put it between items you want pushed apart.
|
|
117
|
+
**Notes.** Fills the free space in a Row; put it between items you want pushed apart. Length forms: Default (omit) means no explicit length; px is a fixed size that neither grows nor shrinks; a percentage is a share of the container, and a percentage height needs a definite container height or it becomes 0.
|
|
118
118
|
|
|
119
119
|
### `Section`
|
|
120
120
|
|
|
@@ -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
|
|
|
@@ -224,9 +224,9 @@ marker replaces the bullet or number, e.g. a time or an emoji.
|
|
|
224
224
|
Markdown(text: string)
|
|
225
225
|
```
|
|
226
226
|
|
|
227
|
-
Prose with headings, lists, quotes, code and
|
|
227
|
+
Prose with headings, lists, quotes, code, tables and inline images (``; http(s), a small `data:image` base64 URI, or a workspace image path).
|
|
228
228
|
|
|
229
|
-
**Notes.** Prose with headings, lists, quotes, tables and
|
|
229
|
+
**Notes.** Prose with headings, lists, quotes, tables, code fences and inline images. The image resolver is the same one `Image` uses, so a source may be http(s), a small `data:image` base64 URI, or a workspace path (relative or absolute); a destination containing spaces or parentheses goes in angle brackets (``). 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
|
|
|
@@ -406,9 +406,9 @@ A real photo the app finds for query; it needs no URL and no tool. Name the exac
|
|
|
406
406
|
Image(src: string, alt: string, aspectRatio?: number, radius?: Radius, fit?: "cover" | "contain")
|
|
407
407
|
```
|
|
408
408
|
|
|
409
|
-
Photo from
|
|
409
|
+
Photo from an http(s) URL, a small `data:image` base64 URI, or an image path the user or a tool named (workspace-relative like `figures/chart.png`, or absolute). Local paths are read by the app: never start a web server or invent an http URL for a local file; a missing or unsupported image shows a clear placeholder, not a substitute photo.
|
|
410
410
|
|
|
411
|
-
**Notes.**
|
|
411
|
+
**Notes.** Accepted sources are `http(s):` URLs, `data:image/png|jpeg|webp|gif;base64,...` URIs (about 512 KiB decoded at most), and filesystem paths (workspace-relative or absolute; `..`/NUL/URL-scheme paths are rejected). Local files are read by the Host process through its workspace-files read authority (which is not confined to the workspace and can read absolute paths outside it) and shown from a same-origin blob URL; missing, oversized (>10 MiB) or non-whitelisted content (including SVG) renders a localized error placeholder. An explicit source never falls back to a searched photo; that behavior belongs to `SearchImage`. `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) |
|
|
@@ -2,38 +2,39 @@
|
|
|
2
2
|
|
|
3
3
|
dsh-intelligent-ui is a DSH bundle with two halves:
|
|
4
4
|
|
|
5
|
-
- **Host** (`lib/index.js`, Node): registers the `render_ui` tool, validates programs with `@openuidev/lang-core` against the generated component spec compiled into the bundle, owns the per-session switch and answer-style overrides (persistence file + slash command + session projection + per-agent tool visibility), contributes the OpenUI Lang generation prompt as a conditional system-prompt section (`tool:intelligent-ui`, order 3100), serves the global `globalEnabled` / `answerStyle` / `freeComposition` / `exportBackground` / `exportScale` / `removeFollowUps` settings (the prompt reads the enable/style/composition values live; the browser also reads the image-export and page follow-up defaults), validates the model-provided `style` against the effective session style, registers the shipped Agent Skill when the deployment composes a skill service, and (when the deployment composes `webServer`) serves `lib/standalone.js` / `lib/standalone.css` on same-origin routes for interactive-page export. `@deepseek-ai/schemastery` is the one runtime dependency, used only for the Config schema the Host settings service reads.
|
|
6
|
-
- **Client** (`lib/client.js`, browser): registers a `conversation.chat.turnTail` card that renders every `render_ui` program recorded by the closing turn, a compact `render_ui` process row that keeps the raw program out of the tool list, the composer UI switch in `conversation.input.activity`, an export entry in `conversation.chat.assistant-actions` (only for messages whose closing Turn recorded `render_ui`; it saves the Turn's rendered cards as one PNG or one single-file interactive HTML page), and the deployment-wide configuration on the bundle's Plugins detail page in `plugins.bundle.config`. It also registers the extension's zh/en UI dictionaries with the client locale
|
|
5
|
+
- **Host** (`lib/index.js`, Node): registers the `render_ui` tool, validates programs with `@openuidev/lang-core` against the generated component spec compiled into the bundle, owns the per-session switch and answer-style overrides (persistence file + slash command + session projection + per-agent tool visibility), contributes the OpenUI Lang generation prompt as a conditional system-prompt section (`tool:intelligent-ui`, order 3100), serves the global `globalEnabled` / `answerStyle` / `freeComposition` / `documentMode` / `exportBackground` / `exportScale` / `removeFollowUps` settings (the prompt reads the enable/style/composition values live; the browser also reads the image-export and page follow-up defaults), validates the model-provided `style` against the effective session style, registers the shipped Agent Skill when the deployment composes a skill service, and (when the deployment composes `webServer`) serves `lib/standalone.js` / `lib/standalone.css` on same-origin routes for interactive-page export. `@deepseek-ai/schemastery` is the one runtime dependency, used only for the Config schema the Host settings service reads.
|
|
6
|
+
- **Client** (`lib/client.js`, browser): registers a `conversation.chat.turnTail` card that renders every `render_ui` program recorded by the closing turn, a compact `render_ui` process row that keeps the raw program out of the tool list, the composer UI switch in `conversation.input.activity`, an export entry in `conversation.chat.assistant-actions` (only for messages whose closing Turn recorded `render_ui`; it saves the Turn's rendered cards as one PNG or one single-file interactive HTML page), and the deployment-wide configuration on the bundle's Plugins detail page in `plugins.bundle.config`. It also registers the extension's zh/en UI dictionaries with the client locale serviceAn ordinary render recorded while the experimental document mode is on carries `document: true`; the client renders that result as a chrome-less document section instead of a card (no header, collapse control, editing entry or revision history). (`ctx.locale.register('intelligent-ui', { zh, en })`) and declares `locale` on those slot registrations, so an in-app language switch re-renders all of its chrome. The composer control opens built-in Auto/Card/Article preview cards, Custom styles with management, and a bottom On-demand UI entry. `conversation.input.overlay` shows an armed hint/examples/cancel; temporary result cards add a badge and adjust/save actions; the Plugin detail page adds global enablement, the global default style, and the export defaults (background color, 1x/2x, and whether images/pages remove the whole `@ToAssistant` follow-up block (on by default)).
|
|
7
7
|
|
|
8
8
|
The same package ships the Agent Skill in `skills/intelligent-ui/`. A deployment can use the tool without the skill; the skill is what makes an agent good at it.
|
|
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`. The published 0.5.0 does not include the B1/B2 style editing and revision-history deletion currently in the local main branch (not yet pushed). Prefer the npm or GitHub bundle install below; the local-checkout flow remains available for development.
|
|
13
13
|
|
|
14
14
|
## Requirements
|
|
15
15
|
|
|
16
|
-
- DSH **0.2.
|
|
16
|
+
- DSH **0.2.2** (validated on `0.2.2-rc.1`, current latest), Node **24**.
|
|
17
17
|
- The **web** profile (or any profile whose app has a browser chat surface); the client half declares `"dsh": { "client": { "platform": "web" } }`.
|
|
18
18
|
- Interactive-page export additionally needs a `webServer` service so the Host can serve the standalone renderer assets; without it image export still works and page export reports a build failure.
|
|
19
19
|
- Style catalog and management require Host `webServer` plus `connection.requestRejection` authentication. On-demand uses the deployment's normal default conversation model services and session events; there is no extension-owned draft model endpoint, `llm` injection or `agentDefaultModel` injection. The structured clarification path additionally needs the built-in `ask_user_question` tool; a text fallback keeps the operation pending for the next message instead of requiring an immediate re-arm.
|
|
20
20
|
- The app composes the client locale service (`@deepseek-ai/dsh-client-locale`; DSH Web includes it by default). The browser half requires the `locale` service: without it the switch and the card do not mount, while the Host tool and prompt keep working. UI dictionaries live in `src/shared/locales.ts` (`zh` as the key-set source of truth, `en` checked complete); the renderer falls back to English outside DSH.
|
|
21
21
|
- Network access for the nice-to-haves: Wikipedia/Wikimedia (photo search), OpenFreeMap tiles and OSRM demo routing (Map). Offline, the page still renders with the fallbacks described below.
|
|
22
22
|
- Runtime dependency **`@deepseek-ai/schemastery`** (~3.18.5), installed with the package; the Host uses it only for the Plugin detail page Config schema.
|
|
23
|
-
- The package declares **no `engines.dsh` yet**; it was verified against `0.2.
|
|
23
|
+
- The package declares **no `engines.dsh` yet**; it was verified against `0.2.2-rc.1`. A later DSH may refuse it until a compatible release lands or an exact-version exemption is granted (below).
|
|
24
24
|
|
|
25
25
|
## Session switch and answer style
|
|
26
26
|
|
|
27
|
-
The extension costs ~
|
|
27
|
+
The extension costs ~10k prompt tokens, so access is opt-in. The deployment-wide defaults live on the Plugin detail page; the composer can override them for one session. A fresh install starts **off** globally, and session state survives refresh and DSH restarts.
|
|
28
28
|
|
|
29
|
-
- **Global defaults (Plugin detail page):** **Enable in all sessions**, the global **Auto / Card / Article** or saved-template style,
|
|
30
|
-
- **Session overrides (composer UI chip):** **Off / This session only /
|
|
29
|
+
- **Global defaults (Plugin detail page):** **Enable in all sessions**, the global **Auto / Card / Article** or saved-template style, the existing **Free-form layout** switch, and the experimental **Answer as a document (experimental)** switch (`documentMode`).
|
|
30
|
+
- **Session overrides (composer UI chip):** **Off / This session only / Follow global** for enablement (Follow global inherits the global switch without changing it; the chip states whether the global switch is on or off); `/iui on|off|inherit`. The **This session only** entry opens a style panel: built-in preview cards, saved templates, On-demand UI, and **Follow global**; `/iui style auto|card|article|inherit|<cs_id>`.
|
|
31
31
|
- **Effective values:** session override first, then the global value; `inherit` follows the global value.
|
|
32
|
-
- **Answer style:** `Card` is a compact interactive page; `Article` is a reading layout inside the `render_ui` card (`Toc` + collapsible `Section` + long Markdown prose); `Auto` lets the model choose. The Host appends the effective style to the generation prompt and rejects a `render_ui` style that conflicts with a forced Card/Article setting.
|
|
32
|
+
- **Answer style:** `Card` is a compact interactive page; `Article` is a reading layout inside the `render_ui` card (`Toc` + collapsible `Section` + long Markdown prose); `Auto` lets the model choose Card, Article or a free layout. The Host appends the effective style note to the generation prompt and rejects a `render_ui` style that conflicts with a forced Card/Article setting; in Auto it accepts `card`, `article` or `free`. The session style is a layout preference: the model decides per answer whether to render at all and may answer in Markdown when a page would add nothing (except an explicit render request or an authorized on-demand operation).
|
|
33
33
|
- **Persistence:** `<DSH_HOME>/dsh-intelligent-ui.json`, written atomically on every session change: `{ "sessions": [...], "offSessions": [...], "styles": { "<session-id>": "article" } }`. A legacy `{ "enabled": true }` or `{ "global": true, "sessions": [...] }` file is still read as migration state. Global values live in the Host settings document.
|
|
34
34
|
- **What off means for a session:** the `render_ui` schema is denied per agent through `agent.ctx.tools.restrict()`, the `tool:intelligent-ui` prompt section resolves to an empty string, and a stray call throws `render_ui is disabled for this session`.
|
|
35
|
-
- **
|
|
36
|
-
- **
|
|
35
|
+
- **Experimental document mode:** when `documentMode` is on, an ordinary answer (not an on-demand result, Artifact edit or saved template) must be rendered with `style: "free"` and the whole answer inside the program; the prompt omits the session style note, the Host ignores the selected template, and the success value/meta records `document: true`. The client then renders the result as a chrome-less document that reads as the turn's message text. It is a stopgap for in-message UI: the content still lives in the turn-tail result, so message copy/search/transcript export omit it, and the document page has no editing entry or revision history. The switch only affects new answers; recorded results replay with their recorded presentation.
|
|
36
|
+
- **What on means for a session:** the prompt section is injected with the effective style note; the model decides page vs text per answer, and a session style only names the layout when it renders.
|
|
37
|
+
- **Projection:** the `intelligent-ui` session projection folds the `command/run` + `command/done` pair (pending state) and projects `sessionEnable`, `sessionStyle`, `globalEnabled`, `globalStyle`, `enabled`, `style`, `pending`, nullable `onDemand`, and the optional capability bits `styleEdit`/`styleSwitch` (projection stateVersion 6). The composer control mirrors this projection and sends commands. It also publishes an optimistic view to other tabs over BroadcastChannel; when the host projection catches up, the projection becomes authoritative again.
|
|
37
38
|
- **Deployments without `sessionProjections` + `commands`:** no session controls and no persistence, so the extension keeps its legacy **always-on** behavior. DSH Web composes both services.
|
|
38
39
|
|
|
39
40
|
Use `/iui off` (session override) to stop paying the prompt cost for that session; use the Plugin detail page to change the deployment-wide default.
|
|
@@ -52,9 +53,9 @@ The browser half follows DSH's UI language and needs no configuration:
|
|
|
52
53
|
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
54
|
|
|
54
55
|
```sh
|
|
55
|
-
# npm (current latest: 0.
|
|
56
|
+
# npm (current latest: 0.5.0)
|
|
56
57
|
dsh plugin --profile web add @zephinel/dsh-intelligent-ui
|
|
57
|
-
dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.
|
|
58
|
+
dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.5.0 # pin a version
|
|
58
59
|
# or GitHub
|
|
59
60
|
dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
|
|
60
61
|
```
|
|
@@ -65,7 +66,7 @@ DSH Desktop installs the same bundle from the app instead of the CLI: **Plugins*
|
|
|
65
66
|
|
|
66
67
|
Packaging behavior that matters when publishing:
|
|
67
68
|
|
|
68
|
-
- The registry tarball ships the prebuilt `lib/` (host and client bundles), `cordis.patch.yml`, `skills/`, `locale/`, `licenses/`, `assets/`, the two READMEs (`README.md` / `README.en.md`), `LICENSE`, `NOTICE` and `icon.svg` (
|
|
69
|
+
- The registry tarball ships the prebuilt `lib/` (host and client bundles), `cordis.patch.yml`, `skills/`, `locale/`, `licenses/`, `assets/`, the two READMEs (`README.md` / `README.en.md`), `LICENSE`, `NOTICE` and `icon.svg` (65 files). The generated component spec and generation prompt are build inputs compiled into `lib/index.js`; `vendor/` and `src/` are not shipped.
|
|
69
70
|
- A Git checkout installs from source: pnpm runs the package's `prepare` build, so the install may ask for **build-script approval** and needs the toolchain. A registry tarball has nothing to build.
|
|
70
71
|
- Without `dsh.bundle`, the manager would install the package as a plain dependency with the warning `declares no dsh.bundle — installed as a plain dependency, not a profile layer`, and nothing would load. This package declares it, so that warning means the wrong spec or an old tarball.
|
|
71
72
|
|
|
@@ -73,7 +74,7 @@ If DSH refuses the package for version incompatibility, either install a compati
|
|
|
73
74
|
|
|
74
75
|
```sh
|
|
75
76
|
dsh plugin --profile web version-exemptions
|
|
76
|
-
dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.
|
|
77
|
+
dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.5.0 --dsh-version 0.2.2-rc.1 --accept-risk
|
|
77
78
|
```
|
|
78
79
|
|
|
79
80
|
Remove it with the mirror command:
|
|
@@ -120,8 +121,8 @@ dsh --profile web --dump-config | grep -n intelligent-ui # the entry must be c
|
|
|
120
121
|
|
|
121
122
|
Verification checklist (remember the switch is off by default):
|
|
122
123
|
|
|
123
|
-
0. **Switch present.** The composer shows the **UI** chip in `conversation.input.activity`; its menu offers **Off**, **This session only**, and **
|
|
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
|
+
0. **Switch present.** The composer shows the **UI** chip in `conversation.input.activity`; its menu offers **Off**, **This session only**, and **Follow global** (localized: 「关闭 / 仅本会话 / 跟随全局」 in a Chinese UI); Follow global shows the current global state under the row. 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.
|
|
125
|
+
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 style it chose (`card`, `article` or `free`), and any ordinary style may answer in Markdown when a page would add nothing. 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
126
|
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
127
|
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
128
|
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,17 +153,18 @@ Filesystem discovery is only a **manual fallback** for an environment where the
|
|
|
152
153
|
| Aspect | Contract |
|
|
153
154
|
| --- | --- |
|
|
154
155
|
| Name | `render_ui` |
|
|
155
|
-
| Arguments | `{ "program": string, "style": "card"|"article", "title"?: string, "styleId"?: string, "temporaryStyle"?: StyleSnapshot }`, `required: ["program", "style"]`, `additionalProperties: false` |
|
|
156
|
+
| Arguments | `{ "program": string, "style": "card"|"article"|"free", "title"?: string, "styleId"?: string, "temporaryStyle"?: StyleSnapshot, "editRequestId"?: string }`, `required: ["program", "style"]`, `additionalProperties: false` |
|
|
156
157
|
| `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
158
|
| `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 `"
|
|
159
|
+
| `style` | `"card"`, `"article"` or `"free"`; required. Free is accepted with an authorized temporary snapshot, the exact styleId of the selected free template (without temporaryStyle), an Auto session that chose free (no styleId/temporaryStyle), or an ordinary answer rendered while the deployment enables document mode (then free is required and styleId/temporaryStyle are rejected); 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
160
|
| `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
|
-
|
|
|
161
|
+
| `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. A pending natural-language style edit also exercises this snapshot path, but only with `editRequestId` and without `styleId`. |
|
|
162
|
+
| `editRequestId` | The pending Artifact edit request this call applies: required for a natural-language style edit (`kind: "style"` envelope) and used for order-only/global-only block requests. A style request is explicit-only and never auto-applies; a called style edit records `styleEdit: true`, the approved `temporaryStyle` and the recorded `title`, and the revision keeps the layout with no `styleId`/`editedBlockIds`. |
|
|
163
|
+
| Success value | `{ "statements": number, "style": "card"|"article"|"free", "styleSource"?: "builtin"|"template"|"temporary", "styleId"?: string, "document"?: boolean, "warnings"?: string[] }` — the parsed statement count, the resolved style recorded with the page, `document: true` for an ordinary answer recorded in document mode, and any non-fatal findings (`Unresolved reference: …`, `Unreferenced statement (will not render): …`). The result meta also records `style`/`styleSource` so a settled free layout replays without a style identity. |
|
|
162
164
|
| Model-visible result | `Interactive UI rendered for the user (<n> statements, <style> style).` plus ` Notes: <warnings joined by "; ">` when warnings exist. |
|
|
163
165
|
| 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
166
|
| 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. |
|
|
165
|
-
| Rendering | Client-side only. The card is appended at the end of the turn that called the tool; multiple calls in one turn render multiple cards, but the tool guidance asks for one. |
|
|
167
|
+
| Rendering | Client-side only. The card is appended at the end of the turn that called the tool; multiple calls in one turn render multiple cards, but the tool guidance asks for one. A result recorded with `document: true` is rendered as a chrome-less document section (the message-body presentation of the experimental document mode) instead of a card. |
|
|
166
168
|
| Interaction | All `$` state, `@functions`, `@Set`/`@Reset`, charts, maps and SVG run in the browser with no model round trip. `@ToAssistant` seeds the composer draft with the message and submits it, starting a new turn. |
|
|
167
169
|
| Persistence | The program and any inline temporaryStyle are recorded in tool arguments; DOM is not persisted. Replay reads those arguments when available in the loaded history window. Temporary replay needs no catalog; saved-template colors resolve from the current catalog and may fall back if missing. |
|
|
168
170
|
| Trust boundary | `HtmlView` runs in a sandboxed iframe with an opaque origin. Its CSP allows inline code, a few script/style/font CDNs and https images; no other network. Programs cannot reach the chat DOM, cookies or storage. |
|
|
@@ -172,22 +174,22 @@ Filesystem discovery is only a **manual fallback** for an environment where the
|
|
|
172
174
|
| Surface | Current contract |
|
|
173
175
|
| --- | --- |
|
|
174
176
|
| 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
|
|
177
|
+
| 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
178
|
| Save | Same POST with `{ op: "save", template: { name, description?, baseLayout, directives, theme }, scope, sessionId? }`. Validated persistence API, not a model creation workflow. |
|
|
177
179
|
| Update | Same POST with `{ op: "update", id, patch: { name?, description?, directives? } }`; only these fields may change; returns `{ template }`. |
|
|
178
180
|
| Delete | Same POST with `{ op: "delete", id }` → `{ deleted: id }`; missing template returns 404. |
|
|
179
181
|
| 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. |
|
|
182
|
+
| 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
183
|
| 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
|
|
184
|
+
| 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. |
|
|
185
|
+
| 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
186
|
| 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
187
|
|
|
186
188
|
## Troubleshooting a missing `render_ui`
|
|
187
189
|
|
|
188
190
|
Work top-down; each step rules out one layer:
|
|
189
191
|
|
|
190
|
-
1. **Switch state (start here).** The extension is off by default. Check the composer **UI** control (Off / This session only /
|
|
192
|
+
1. **Switch state (start here).** The extension is off by default. Check the composer **UI** control (Off / This session only / Follow global; Chinese UI: 「关闭 / 仅本会话 / 跟随全局」) or run `/iui` to print the current state; if the control is missing, the profile lacks `sessionProjections`/`commands` or the browser half did not load. A tool error reading `render_ui is disabled for this session` means the switch does not admit this session (wrong scope, or a command that has not settled) — pick “this session only” and retry.
|
|
191
193
|
2. **Right profile.** Installed into `web` but the session runs under another profile (`headless`, `sdk`, custom) → install there too.
|
|
192
194
|
3. **Composed tree.** `dsh --profile web --dump-config` does not mention `intelligent-ui` → the bundle is not selected or the checkout is not linked. Re-add it (`dsh plugin --profile web add link:$(pwd)` from the checkout, or `node scripts/install.mjs`), then restart.
|
|
193
195
|
4. **Built artifacts.** For a checkout: `lib/index.js` and `lib/client.js` exist and are newer than `src/`. If not, `npm run build`.
|
|
@@ -203,11 +205,12 @@ Work top-down; each step rules out one layer:
|
|
|
203
205
|
|
|
204
206
|
- The card appears at the **end of the turn** (turn-tail), never inline mid-answer; during generation the process row reads the localized "Interactive answer" (「交互式回答」 in a Chinese UI).
|
|
205
207
|
- Model-authored programs occasionally fail validation; the host returns exact errors and the model is expected to self-repair in the same turn. Repeated failures are a prompt/model issue, not a host issue.
|
|
206
|
-
- The generation prompt is about
|
|
208
|
+
- The generation prompt is about 10K tokens and is sent **only for a session the switch admits**; otherwise the prompt section is empty and the tool schema is hidden. Prompt caching absorbs most of the cost while on.
|
|
207
209
|
- Photos, map tiles and routing are third-party services with offline fallbacks (see [troubleshooting.md](troubleshooting.md#runtime-fallbacks-valid-program-degraded-media)).
|
|
208
210
|
- `Math` relies on the host's global KaTeX styles; if a future DSH shell drops them, formulas degrade to text.
|
|
209
211
|
- This extension is web-only: profiles without a browser surface register the tool but have no card to render into.
|
|
210
212
|
- 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.
|
|
213
|
+
- 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.
|
|
214
|
+
- **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
215
|
- 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.
|
|
216
|
+
- 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
|
|
@@ -68,6 +78,15 @@ render_ui: this session uses custom style "Ocean notes"; pass styleId: "cs_ocean
|
|
|
68
78
|
|
|
69
79
|
Follow that exact id/layout outside an authorized on-demand call. If the template is gone, let the user select another style; do not fabricate it.
|
|
70
80
|
|
|
81
|
+
Document-mode errors reject a layout the deployment does not use for ordinary answers:
|
|
82
|
+
|
|
83
|
+
```text
|
|
84
|
+
render_ui: document mode renders the answer as one free-layout document; pass style: "free" without styleId or temporaryStyle.
|
|
85
|
+
render_ui: document mode does not use saved templates; omit styleId and pass style: "free".
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
This deployment records ordinary answers as documents: pass `style: "free"`, put the whole answer (prose plus interactive blocks) in the program, and write no Markdown outside the call. Card/Article and saved-template layouts are rejected for these answers; apply on-demand results, saved templates and Artifact edit requests with their own recorded layout instead.
|
|
89
|
+
|
|
71
90
|
Command and result-save failures include:
|
|
72
91
|
|
|
73
92
|
```text
|
|
@@ -78,6 +97,7 @@ Invalid on-demand adjustment parent result id.
|
|
|
78
97
|
An on-demand UI operation is already running in this session; wait for it to finish or cancel it first.
|
|
79
98
|
Too many active on-demand operations. Cancel one and retry.
|
|
80
99
|
This result snapshot is no longer available.
|
|
100
|
+
This result has no explicit theme, so it cannot become a style template. Adjust it with a theme first, then save.
|
|
81
101
|
A style with this name already exists.
|
|
82
102
|
The style library has reached its scope limit.
|
|
83
103
|
The session must match the result.
|
|
@@ -246,7 +266,7 @@ These are not errors to fix in the program; they are how the card behaves when t
|
|
|
246
266
|
|
|
247
267
|
| Situation | What the user sees | What to do |
|
|
248
268
|
| --- | --- | --- |
|
|
249
|
-
| Photo search offline or rate-limited | `SearchImage`
|
|
269
|
+
| Photo search offline or rate-limited | `SearchImage` shows a neutral placeholder. An explicit `Image` whose source is missing, too large, unsupported (e.g. SVG) or fails to load shows a short localized error placeholder and never searches for a substitute. Search timeouts are 8 s per request, 12 s total. | Nothing. Do not add prose about images failing; for a local file, pass the workspace path instead of a URL. |
|
|
250
270
|
| Map tiles unavailable | `Map tiles are temporarily unavailable. The places are still shown.`(「地图瓦片暂时不可用,地点仍会显示。」)The pins stay interactive. | Nothing; keep the place list near the map. |
|
|
251
271
|
| Map renderer cannot start (old browser, no WebGL) | `Map preview unavailable`(「地图预览不可用」)plus `The places are listed below.`(「地点列表见下方。」)with a numbered list of labels and coordinates. | Keep marker labels short and recognizable; the fallback is a list. |
|
|
252
272
|
| Routing service down | `Street routing unavailable. Showing direct connections.`(「街道路线不可用,改为直线连接。」)Straight lines still join the pins in order. | Nothing; route is an enhancement. |
|
|
@@ -254,7 +274,7 @@ These are not errors to fix in the program; they are how the card behaves when t
|
|
|
254
274
|
| HtmlView shows `Preparing the interactive view…`(「正在准备交互视图…」) | Normal: the iframe mounts once the program has finished arriving. | Nothing. |
|
|
255
275
|
| 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
276
|
| Clipboard write fails | `@CopyToClipboard` falls back to `document.execCommand("copy")`. | Nothing; it is best-effort. |
|
|
257
|
-
| A `render_ui` program crashes while rendering | The
|
|
277
|
+
| 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
278
|
| `@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
279
|
|
|
260
280
|
## Rendered but wrong
|
|
@@ -269,5 +289,11 @@ No error appears, yet the page is not what you intended. Check these in order:
|
|
|
269
289
|
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
290
|
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
291
|
8. **Dates** — comparisons are numeric; order dates with `@DaysBetween(a, b) > 0`, and format them with `@FormatDate`.
|
|
292
|
+
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
293
|
|
|
273
294
|
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).
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
### Free saved templates
|
|
298
|
+
|
|
299
|
+
A selected free template requires `style: "free"` and its exact `styleId`, without `temporaryStyle`. An Auto session may also pass `style: "free"` directly (no `styleId`/`temporaryStyle`); the Host records it as a built-in free layout. A forced Card/Article selection still rejects free, and adding an arbitrary styleId cannot authorize free. Free layouts 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.
|