@zephinel/dsh-intelligent-ui 0.5.0 → 0.6.1

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.
Files changed (41) hide show
  1. package/NOTICE +7 -0
  2. package/README.en.md +107 -86
  3. package/README.md +103 -82
  4. package/assets/intelligent-ui-components-layout.webp +0 -0
  5. package/assets/intelligent-ui-dashboard-en.webp +0 -0
  6. package/assets/intelligent-ui-dashboard-zh.webp +0 -0
  7. package/assets/intelligent-ui-editing-en.webp +0 -0
  8. package/assets/intelligent-ui-editing-zh.webp +0 -0
  9. package/assets/intelligent-ui-itinerary-en.webp +0 -0
  10. package/assets/intelligent-ui-itinerary-zh.webp +0 -0
  11. package/assets/intelligent-ui-on-demand-hint.webp +0 -0
  12. package/assets/intelligent-ui-quiz-en.webp +0 -0
  13. package/assets/intelligent-ui-quiz-zh.webp +0 -0
  14. package/assets/intelligent-ui-readme-components.webp +0 -0
  15. package/assets/intelligent-ui-readme-controls.webp +0 -0
  16. package/assets/intelligent-ui-readme-generation-en.webp +0 -0
  17. package/assets/intelligent-ui-readme-generation-zh.webp +0 -0
  18. package/assets/intelligent-ui-readme-overview-en.webp +0 -0
  19. package/assets/intelligent-ui-readme-overview-zh.webp +0 -0
  20. package/assets/intelligent-ui-readme-temporary.webp +0 -0
  21. package/assets/intelligent-ui-real-dashboard-en.webp +0 -0
  22. package/assets/intelligent-ui-real-dashboard-zh.webp +0 -0
  23. package/assets/intelligent-ui-real-itinerary-en.webp +0 -0
  24. package/assets/intelligent-ui-real-itinerary-zh.webp +0 -0
  25. package/assets/intelligent-ui-real-quiz-en.webp +0 -0
  26. package/assets/intelligent-ui-real-quiz-zh.webp +0 -0
  27. package/assets/intelligent-ui-settings.webp +0 -0
  28. package/assets/intelligent-ui-style-panel.webp +0 -0
  29. package/assets/intelligent-ui-temporary-result-dark.webp +0 -0
  30. package/assets/intelligent-ui-temporary-result.webp +0 -0
  31. package/assets/intelligent-ui-toggle.png +0 -0
  32. package/lib/client.js +169 -146
  33. package/lib/index.js +101 -62
  34. package/lib/standalone.css +1 -1
  35. package/lib/standalone.js +139 -133
  36. package/licenses/remix-icon-LICENSE +186 -0
  37. package/package.json +12 -6
  38. package/skills/intelligent-ui/SKILL.md +46 -25
  39. package/skills/intelligent-ui/references/components.md +10 -10
  40. package/skills/intelligent-ui/references/integration.md +24 -22
  41. package/skills/intelligent-ui/references/troubleshooting.md +11 -2
@@ -0,0 +1,186 @@
1
+ Remix Icon License v1.0
2
+ Version 1.0 – January 2026
3
+ Copyright (c) 2017–2026 Remix Design
4
+
5
+ This License governs the use of the Remix Icon library, including all icons,
6
+ SVG files, font files, and related assets (collectively, the "Icons").
7
+
8
+ 1. Grant of License
9
+
10
+ Subject to the terms and conditions of this License, Remix Design grants you
11
+ a worldwide, royalty-free, non-exclusive license to use, copy, modify,
12
+ merge, and distribute the Icons, as permitted below.
13
+
14
+ 2. Permitted Uses
15
+
16
+ You are permitted to:
17
+
18
+ 2.1 Commercial and Non-Commercial Use
19
+ Use the Icons in personal, commercial, and client projects, including
20
+ but not limited to:
21
+ - Websites, web applications, and mobile applications
22
+ - Software products and SaaS platforms
23
+ - User interface designs, design systems, and UI kits
24
+ - Presentations, documentation, and marketing materials
25
+ - Physical or digital products where the Icons are decorative or
26
+ functional elements
27
+
28
+ 2.2 Modification and Derivative Works
29
+ - Modify, adapt, or customize the Icons
30
+ - Change colors, sizes, stroke styles, or other visual attributes
31
+ to fit your project needs
32
+
33
+ 2.3 Distribution as Part of a Larger Work
34
+ Include the Icons (modified or unmodified) as part of a larger product,
35
+ provided that:
36
+ - The Icons are functional or decorative components of the product, and
37
+ - The Icons are not marketed or sold as the primary value of the product
38
+
39
+ 2.4 Attribution (Optional)
40
+ Attribution to Remix Icon is appreciated but not required.
41
+ Suggested attribution:
42
+ "Icons by Remix Icon (https://remixicon.com)"
43
+
44
+ 3. Restrictions
45
+
46
+ 3.1 Prohibited: Standalone Icon Sales
47
+ You may NOT:
48
+ - Sell, sublicense, or distribute the Icons as a standalone product
49
+ - Package the Icons as an independent icon pack, icon library, or
50
+ icon font for sale
51
+ - Offer the Icons as a downloadable asset collection where the Icons
52
+ themselves constitute the primary product value
53
+
54
+ Clarification:
55
+ A product is considered a prohibited standalone icon sale if:
56
+ - The Icons are the primary advertised feature, or
57
+ - Removing the Icons would eliminate the core value of the product
58
+
59
+ Examples:
60
+ - Prohibited: "Premium Icon Pack – 2,000+ Icons for $29"
61
+ - Prohibited: "Extended Remix Icon Library (Paid)"
62
+ - Permitted: Website or app templates that include Icons as UI elements
63
+ - Permitted: Design systems or UI kits where Icons are a minor component
64
+
65
+ 3.2 Prohibited: Competing Icon Libraries
66
+ You may NOT use the Icons to create, distribute, or sell a competing
67
+ icon library or icon set, even if the Icons are modified with only
68
+ minor or superficial changes (such as color, size, stroke width,
69
+ corner radius, or layout).
70
+
71
+ 3.3 Prohibited: Logo, Trademark, and Brand Identity Use
72
+ You may NOT use the Icons, whether modified or unmodified, as:
73
+ - A logo, trademark, or brand identifier
74
+ - The primary visual identity of a company, product, or service
75
+
76
+ This includes, but is not limited to:
77
+ - Creating a logo by applying simple modifications such as color changes,
78
+ rotation, combination, or layout
79
+ - Using an Icon as a brand mark, app icon, or identity symbol where the
80
+ Icon itself represents the brand
81
+
82
+ Rationale:
83
+ Remix Icon is designed for functional and informational use. Using the
84
+ Icons as brand identifiers may impair their recognizability and neutrality
85
+ in other functional contexts.
86
+
87
+ 4. Brand Icons and Trademarks
88
+
89
+ Some Icons represent third-party brands or services.
90
+
91
+ 4.1 Permitted Use of Brand Icons
92
+ You may use brand icons solely to represent or link to the corresponding
93
+ brand, product, or service.
94
+ Examples:
95
+ - Using a GitHub icon to link to a GitHub repository
96
+ - Displaying social media icons in a website footer
97
+
98
+ 4.2 Prohibited Use of Brand Icons
99
+ You may NOT:
100
+ - Use brand icons as your own logo or trademark
101
+ - Modify brand icons to create a new brand identity
102
+ - Use brand icons in a way that implies endorsement or affiliation
103
+ by the brand owner
104
+ - Use brand icons for purposes unrelated to the represented brand
105
+
106
+ 4.3 Trademark Responsibility
107
+ All brand icons are subject to the trademark rights of their respective
108
+ owners. This License does not grant any trademark rights.
109
+ Users are responsible for ensuring that their use of brand icons complies
110
+ with applicable trademark laws.
111
+
112
+ 5. Copyright and License Notice
113
+
114
+ When distributing the complete Icon library or substantial portions thereof:
115
+
116
+ - You must retain existing copyright notices in source files
117
+ - You should include a copy of this License or a link to it
118
+
119
+ For individual use of Icons within projects (e.g., compiled apps, websites,
120
+ presentations), no copyright notice is required.
121
+
122
+ 6. No Trademark Rights
123
+
124
+ This License does not grant permission to use:
125
+
126
+ - The "Remix Icon" name, logo, or trademarks
127
+ - Any trademarks represented by brand icons
128
+
129
+ You may refer to Remix Icon by name solely for attribution purposes.
130
+
131
+ 7. Disclaimer of Warranty
132
+
133
+ THE ICONS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
134
+ IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
135
+ FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
136
+
137
+ 8. Limitation of Liability
138
+
139
+ IN NO EVENT SHALL REMIX DESIGN BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
140
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
141
+ FROM, OUT OF, OR IN CONNECTION WITH THE ICONS OR THEIR USE.
142
+
143
+ 9. License Compatibility
144
+
145
+ You may integrate the Icons into projects under permissive licenses
146
+ (such as MIT, BSD, or Apache 2.0), provided that:
147
+
148
+ - The Icons themselves remain governed by this License
149
+ - The restrictions in Section 3 continue to apply
150
+
151
+ This License may be incompatible with licenses that require unrestricted
152
+ redistribution of assets as standalone products or mandatory application
153
+ of strong copyleft or share-alike terms.
154
+
155
+ 10. Termination
156
+
157
+ Your rights under this License terminate automatically if you breach its
158
+ terms.
159
+
160
+ Upon termination:
161
+
162
+ - You must cease any distribution that violates this License
163
+ - You may continue to use the Icons in projects already distributed
164
+ prior to termination
165
+ - End users who received such projects are not affected
166
+
167
+ 11. License Versioning
168
+
169
+ Remix Design may publish revised versions of this License.
170
+
171
+ You may choose to use the Icons under:
172
+
173
+ - The version of this License under which you received them, or
174
+ - Any later version published by Remix Design
175
+
176
+ Once chosen, that version may be used indefinitely.
177
+
178
+ How to Apply This License
179
+
180
+ Include the following notice in your documentation when appropriate:
181
+
182
+ "This project uses icons from Remix Icon (https://remixicon.com),
183
+ licensed under the Remix Icon License v1.0."
184
+
185
+ When distributing the complete Icon library or substantial portions of it,
186
+ include a copy of this License.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zephinel/dsh-intelligent-ui",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
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,12 +44,18 @@
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 && 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",
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 && node test/renderer/nested-css-contract-check.mjs && node test/renderer/capture-token-contract-check.mjs",
48
+ "check": "npm run typecheck && npm run build && npm test && npm run test:renderer && npm run check:docs-facts && npm run check:docs-links && npm run check:pack-facts",
49
49
  "pack:check": "npm pack --dry-run --json",
50
+ "check:release": "node scripts/release-check.mjs",
50
51
  "prepare": "node scripts/build.mjs",
51
52
  "check:theme": "node test/renderer/theme-torture.mjs",
52
- "test:browser": "node test/browser/on-demand.e2e.mjs && node test/browser/style-panel.e2e.mjs && node test/browser/style-theme.e2e.mjs && node test/browser/export-image.e2e.mjs && node test/browser/standalone-page.e2e.mjs && node test/browser/article-layout.e2e.mjs && node test/browser/settings-picker.e2e.mjs"
53
+ "test:browser": "node test/browser/on-demand.e2e.mjs && node test/browser/style-panel.e2e.mjs && node test/browser/style-theme.e2e.mjs && node test/browser/export-image.e2e.mjs && node test/browser/standalone-page.e2e.mjs && node test/browser/article-layout.e2e.mjs && node test/browser/settings-picker.e2e.mjs && node test/browser/sidebar-update.e2e.mjs && node test/browser/artifact-edit.e2e.mjs && node test/browser/nested-edit-renderer.e2e.mjs",
54
+ "capture:readme": "node scripts/capture-screenshots.mjs && node scripts/capture-editor-screenshot.mjs && node scripts/capture-editor-screenshot.mjs --en && node scripts/build-readme-bento.mjs",
55
+ "check:docs-facts": "node scripts/check-doc-facts.mjs",
56
+ "check:docs-links": "node scripts/check-docs-links.mjs",
57
+ "check:pack-facts": "node scripts/check-pack-facts.mjs",
58
+ "check:release-notes": "node scripts/check-release-notes.mjs"
53
59
  },
54
60
  "keywords": [
55
61
  "deepseek-harness",
@@ -76,8 +82,8 @@
76
82
  "access": "public"
77
83
  },
78
84
  "devDependencies": {
79
- "@openuidev/lang-core": "^1.0.1",
80
- "@openuidev/react-lang": "^1.0.1",
85
+ "@openuidev/lang-core": "^1.1.1",
86
+ "@openuidev/react-lang": "^1.1.1",
81
87
  "@types/node": "^22.20.5",
82
88
  "@types/react": "^18.3.0",
83
89
  "@types/react-dom": "^18.3.0",
@@ -1,50 +1,50 @@
1
1
  ---
2
2
  name: intelligent-ui
3
- description: "Render an interactive answer as UI in DSH: one complete OpenUI Lang program (maps, photos, charts, tables, forms, SVG drawings, games) shown as a turn-tail card. Use it for structured answers — itineraries, comparisons, dashboards, timelines, explainers, guides — when the session has Intelligent UI enabled; it is then the default format and prose is the bounded exception. If render_ui is missing, answer in prose."
4
- whenToUse: "A visual, interactive or computed answer would serve better than prose — day plans, dashboards, comparisons, budgets, how-to drawings, forms, games, timelines, explainers — or the user asks to render, show, visualize or build a page, or invokes /intelligent-ui. Not for a single fact, a one-line reply, or a plain text/code answer."
3
+ description: "Render an interactive answer as UI in DSH: one complete OpenUI Lang program (maps, photos, charts, tables, forms, SVG drawings, games) shown as a turn-tail card. Use it for structured answers — itineraries, comparisons, dashboards, timelines, explainers, guides — when the session has Intelligent UI enabled and a page serves the answer better than text; the model decides the format per answer and loads this skill only when it renders. If render_ui is missing, answer in prose."
4
+ whenToUse: "A visual, interactive or computed answer would serve better than prose — day plans, dashboards, comparisons, budgets, how-to drawings, forms, games, timelines, explainers — or the user asks to render, show, visualize or build a page, or invokes /intelligent-ui. Not for a bare fact, a term restatement, a one-line factual reply, or a plain text/code answer."
5
5
  ---
6
6
 
7
7
  # Intelligent UI
8
8
 
9
- `render_ui` turns one OpenUI Lang program into an interactive card at the end of the turn. The program is not prose and not HTML: it declares named values and components, and the card evaluates them in the browser. In a session with Intelligent UI enabled, the plugin injects the complete language prompt (components, functions, syntax); this skill adds the decision boundary, the workflow, the design playbook and the deep reference that the prompt cannot fit.
9
+ `render_ui` turns one OpenUI Lang program into an interactive card at the end of the turn. The program is not prose and not HTML: it declares named values and components, and the card evaluates them in the browser. In a session with Intelligent UI enabled, the plugin injects the complete language prompt (components, functions, syntax); this skill adds the workflow, the design playbook and the deep reference that the prompt cannot fit.
10
10
 
11
11
  ## Before you start: is the session enabled?
12
12
 
13
- The extension is opt-in. The deployment-wide switch and default answer style live on the Plugin detail page; the composer can override enablement and style for one session — **Off**, **This session only**, **All sessions** (inherits the global switch), and **Auto** / **Card** / **Article** or a saved custom template. You cannot see the composer, so infer the state from the request:
13
+ The extension is opt-in. The deployment-wide switch and default answer style live on the Plugin detail page; the composer can override enablement and style for one session — **Off**, **This session only**, **Follow global** (inherits the global switch; its chip states whether the global switch is on or off), and **Auto** / **Card** / **Article** or a saved custom template. You cannot see the composer, so infer the state from the request:
14
14
 
15
- - **`render_ui` is in your tools and the `tool:intelligent-ui` prompt section is present** → enabled. Continue; a page is the default answer format.
15
+ - **`render_ui` is in your tools and the `tool:intelligent-ui` prompt section is present** → enabled. Continue; decide per answer whether a page serves it better than text.
16
16
  - **`render_ui` is absent** → off for this session, or the plugin/host services did not load. Answer in prose. If a page would genuinely serve better, say once that the user can pick **This session only** (仅本会话) in the **UI** chip on the right side of the composer, run `/iui on`, or enable the extension for all sessions on the Plugin detail page. Do not call `render_ui`, do not fake a card, and do not repeat the ask on later turns.
17
- - **Explicit invocation is a directive:** the user invoked `/intelligent-ui`, or asked you to build the page with this skill → render; prose only when the user also asked for text or the tool is unavailable.
17
+ - **Explicit invocation is a directive:** the user invoked `/intelligent-ui`, or explicitly asked for a page, dashboard, card or UI → render; prose only when the user also asked for text or the tool is unavailable.
18
18
 
19
19
  A deployment may also enable **Free-form layout** on the extension's Plugin detail page (Plugins → Intelligent UI). When the injected prompt says "Free-form layout is on for this deployment", the design playbook below is advisory rather than a template.
20
20
 
21
21
  ## Decide the format
22
22
 
23
- The decision policy is owned by the injected `tool:intelligent-ui` prompt; this skill applies it. In an enabled session `render_ui` is the **default answer format** for any answer with structure: several facts, a timeline, stages, steps, options, numbers, a comparison, or something to explore — including introductions, explainers, overviews and guides about a topic.
23
+ The decision policy is owned by the injected `tool:intelligent-ui` prompt; this skill applies it rather than restating it. If that policy decides the answer is better as Markdown, answer in Markdown without calling `render_ui` and stop here; otherwise continue with the workflow below.
24
24
 
25
- Answer in Markdown only when the whole answer is:
26
-
27
- - a single fact or one or two sentences;
28
- - an explicit request for text, a document, Markdown, code or a plain answer;
29
- - content that cannot be shown as a page (a safety warning, material that must be quoted verbatim);
30
- - a fallback after two failed render attempts in the turn.
31
-
32
- Two consequences matter in practice:
33
-
34
- - **A knowledge or explainer topic is not a prose signal.** If the answer would have parts (eras, stages, factors, examples, dynasties, events), make the page — timeline, cards or an explorer — instead of a long text answer.
35
- - **A page is never faked.** If the switch is off or the tool is missing, say so once and answer in prose; never simulate a card with HTML or a fenced block.
25
+ The session style is a layout preference for when you render, not a requirement to render: Card and Article name the layout, Auto lets you choose Card, Article or a free layout. Explicit invocation is a directive (see above). A page is never faked: if the switch is off or the tool is missing, say so once and answer in prose; never simulate a card with HTML or a fenced block.
36
26
 
37
27
  ## Answer styles
38
28
 
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:
29
+ The injected prompt owns the effective style decision and appends it to the session prompt; this section only explains how to build each shape. When you render an ordinary answer, use the session style below; an authorized on-demand operation uses the free-layout contract in the next section:
40
30
 
41
31
  - **Card** — compact, scannable interactive page. Keep cards tight; do not turn a broad request into a long article.
42
32
  - **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
33
  - **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.
44
- - **Auto** — choose per request: Card for interactive, structured, visual or computational answers; Article for 详尽/深入/全面/长文/报告/综述 requests.
34
+ - **Auto** — choose the layout that fits when you render: Card for interactive, structured, visual or computational pages; Article for 详尽/深入/全面/长文/报告/综述 answers; free when neither shell fits — compose the page shape yourself, with `Toc` and `Section` optional. If the answer is better as text, answer in Markdown without calling `render_ui`.
35
+ - **Document (experimental)** — the deployment may enable document mode; the injected prompt then says so. An ordinary rendered answer is the reply itself: pass `style: "free"`, put all prose and blocks inside one program, and write no Markdown outside the call. The page has no card header or collapse control and reads as chat message text.
45
36
 
46
37
  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.
47
38
 
39
+ ## Document mode (experimental)
40
+
41
+ A deployment may enable **document mode** (Plugin detail page → Experimental). The injected `tool:intelligent-ui` prompt then opens with the document contract; follow it:
42
+
43
+ - For an ordinary answer that benefits from a page, write the **whole answer** as one complete program: prose, headings, tables and code as ordinary blocks (`Markdown`, `Title`, `Text`, `Table`, `Code`, ...), with visual or interactive components placed between the parts they explain.
44
+ - Pass `style: "free"`, omit `styleId` and `temporaryStyle`, call `render_ui` once, and then **stop**: do not write an introduction or a closing Markdown reply. If no page serves the answer, answer in Markdown as usual.
45
+ - The client presents the recorded result without card chrome, so the page reads as the turn's message text rather than a deliverable card. It is still a turn-tail result: copying the message, search and transcript Markdown export do not include the page body, and the document page has no editing entry or revision history.
46
+ - Do not use document mode for on-demand results, saved templates or Artifact edit requests; those keep their own card contract and the Host enforces their layouts.
47
+
48
48
  ## On-demand generation and custom templates
49
49
 
50
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.
@@ -54,12 +54,31 @@ An `ON-DEMAND UI` request note comes from a Host-armed operation; it is already
54
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
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.
56
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.
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.
57
+ - No preview, naming, saving or settings changes are required. Render once and stop. Users can change the style in the Artifact editor's **Style** section; older Hosts or non-editable cards keep the legacy **Adjust style** fallback (a redirected read-only fallback card keeps neither Save nor Adjust). **Save as template** appears only on a result carrying a theme-bearing temporary style and creates a new template; do not save templates yourself or put management buttons in the generated program. The editor's deterministic style switch is a user UI action and needs no model call.
58
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.
59
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.
60
60
 
61
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).
62
62
 
63
+ ## Artifact block edits
64
+
65
+ A user message can carry one or more targeted edit requests for pages already on screen: the composer sends one `<artifact-edit-request>` header per chip (artifact identity, stable `requestId`, base revision, style, per-block instructions, the complete target order and an optional reorder hint) followed by that artifact's original program inside `<artifact-program>`. The Host parses the envelopes to validate and record each update, so apply them as the envelope's rules say:
66
+
67
+ - **Content edits use `edit_ui_blocks`:** call `edit_ui_blocks` exactly once per request with a mini openui-lang program `root = Col([...])` whose direct children are exactly the edited target blocks' top-level expressions, in the request's order. Do not return the whole page and do not call `render_ui` for this request. You may add new helper statements, but never redefine an existing statement or `$state` name, keep every existing helper/state declaration unchanged, and never add, remove, merge or duplicate a block. The page inside `<artifact-program>` is read-only reference context (Phase 1 still sends it).
68
+ - **Nested block requests:** when an edit carries `nodeId`/`sourceDigest` (a block inside a `Col`/`Row`/`Card`/`Box`/`Grid`/`Section`/`Carousel`), the request is nested: still call `edit_ui_blocks` exactly once, and the mini-program's root children must correspond to the request edits in `selectionOrder` — one child expression per edited nested block, in that order. Never mix nested and top-level edits in one request (the Host rejects that). Nested reordering is a separate `orderByParent` request handled with `render_ui` (see below); duplicate, delete, cross-container move and Divider/Spacer property changes are deterministic Host operations performed from the editor UI, so they never appear in an edit envelope and need no model call.
69
+ - **Editable scope:** every direct child of the root `Col` and of the seven allowlisted containers (`Col`, `Row`, `Box`, `Grid`, `Card`, `Section`, `Carousel`) is editable, including a root `Title` and `Caption`/`Divider`/`Spacer`/`Toc`. Blocks inside `@Each`, opaque expressions, shared named expressions, page chrome and pages over the depth/node budget are not editable; do not invent edits for them. The editor UI may also add, duplicate, delete or move blocks; only content edits, nested additions and `orderByParent` reorders are sent to the model.
70
+ - **Strict mode (`strict: true`):** when the envelope header says strict, the user has turned on strict protection: do not change any block that is not one of the requested targets (nested or top-level). If the Host rejects the edit for an unselected-block change, the pending request stays armed — fix the program and retry the **same** request; do not ask for a new edit request or reopen editing.
71
+ - **Nested additions (`additions`):** when the envelope header has `additions`, the user wants new block(s) inserted into an existing container. Still call `edit_ui_blocks` exactly once. The mini-program root `Col` children must be exactly: the content edits first (ordered by ascending `selectionOrder`), then one child expression per addition (in request order) — the total child count equals edits + additions. Each addition names `parentNodeId` (the destination container) and `index` (position among that parent's editable children); insert the generated expression accordingly and keep every other block unchanged. Do not return `orderByParent` in the same request as `additions` (they are separate sends), do not add more than the requested additions, and keep the recorded style. If the fragment order/count does not match, the Host rejects the request and keeps it armed for a retry.
72
+ - **Nested order-only requests:** when the request carries `orderByParent` (parent node ids -> complete child node-id permutations) but no content edits, call `render_ui` once with the complete updated program (same as any order-only request) and keep the recorded style; the Host deterministically rebuilds the hierarchy from the header, so return the page with the requested child order rather than restructuring it yourself. Do not mix nested content edits with a reorder of the same parent subtree, and keep the root `targetOrder` order in the returned program.
73
+ - **Order-only or global-only requests use `render_ui`:** call it exactly once per request with the complete updated program.
74
+ - **Natural-language style edits (`kind: "style"`) use `render_ui` once, explicitly:** the envelope carries no block targets, only a `styleInstruction` plus the recorded style and (for a result-owned style) its `temporaryStyle` snapshot. Call `render_ui` exactly once with the complete program, the recorded `style`, and a complete `temporaryStyle` whose `baseLayout` equals that style; omit `styleId`. Pass the envelope's `requestId` as `editRequestId` — a style edit is **never** applied automatically, so a missing `editRequestId` is an error. Keep every block and the layout; change only the presentation the instruction asks for, and never call `edit_ui_blocks` for it. The Host records one revision that keeps the approved snapshot and reports `Interactive UI style updated for the user (revision N of the artifact, <layout> layout).`
75
+ - **One message may contain several requests (one per Artifact):** apply each request with its own tool call. With several pending requests, pass `requestId` (and `artifactId`) to `edit_ui_blocks` or `editRequestId` to `render_ui` so the Host applies exactly that request; a missing or unknown selector is an error that lists the pending choices — fix the selector instead of guessing. Never merge several Artifacts into one fragment program, and never use one call to satisfy two requests. Each request is recorded and committed independently: a failed request does not roll back the other revisions, so retry only the failed one.
76
+ - Change only the target blocks plus the minimum directly related parts; keep every unselected block and the rest of the page's content, structure and interactive behavior unchanged.
77
+ - Reorder the root `Col`'s top-level blocks to exactly the target order (`targetOrder`) when one is present. Reordering never adds, removes, merges, duplicates or regenerates a block: keep the same set of top-level blocks, keep reordered-only blocks' content/identity/interactions, and keep each block identifiable by its statement name or title so the Host can map it.
78
+ - Keep the recorded style: for `render_ui` pass the `style` named in the envelope and its exact `styleId` when recorded; `edit_ui_blocks` takes only the mini program and the Host reuses the recorded style. When the envelope header carries a `temporaryStyle` snapshot (a result-owned temporary style), the request is content-only: apply it with `edit_ui_blocks` and never pass style or styleId. Order-only/global-only edits on a temporary style are not sent; if asked, tell the user to re-render the page with a saved or built-in style first.
79
+ - Apply all block instructions plus the optional global instruction. If they are materially ambiguous or contradict each other, ask one focused question with `ask_user_question` instead of guessing.
80
+ - A successful edit result reads `Interactive UI updated for the user (revision N of the artifact, K blocks edited).`; an order-only update reads `... block order adjusted).` and the card shows the new revision. The Host rejects a program based on a stale revision, an unmappable arrangement or a fragment that does not fit; do not retry blindly, and never call `render_ui` and `edit_ui_blocks` for the same request.
81
+
63
82
  ## Workflow
64
83
 
65
84
  ### 0. Outline the content first
@@ -78,7 +97,7 @@ Choosing rules of thumb:
78
97
  | numbers across time or categories | `Chart` (`line`/`area` for time, `bar` for categories, `pie`/`donut` for shares) |
79
98
  | an exact comparison or detail list | `Table`, or label/value `Row`s in a `Card` |
80
99
  | places and a route | `Map` + `MapMarker` (labels are the fallback list) |
81
- | how something looks | `SearchImage` (exact 2–4 word subject), or `Image` for a URL you have |
100
+ | how something looks | `SearchImage` (exact 2–4 word subject), or `Image` for an image file you have (workspace path) or a URL you were given |
82
101
  | how something works or goes together | `Svg` drawings, one per step, with `SvgText` labels |
83
102
  | a choice the user must make | `SegmentedControl` / `RadioGroup` / `Pressable` tiles / `Slider` |
84
103
  | learning or a game | `Flashcard`, quiz with scoring, `Celebration`, `HtmlView` for a real animation loop |
@@ -100,7 +119,7 @@ Completion: the program satisfies the hard rules below, and the pre-flight check
100
119
 
101
120
  ### 4. Call the tool
102
121
 
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.
122
+ 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 layout you chose (`card`, `article` or `free`). If the answer is better as Markdown text, do not call the tool. 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.
104
123
 
105
124
  **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.
106
125
 
@@ -132,16 +151,18 @@ Exact signatures, argument order, enums and function list: [references/component
132
151
 
133
152
  **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.
134
153
 
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.
154
+ 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 an Auto-chosen free layout, authorized free results and selected free templates, page shape and typography guidance is advisory; follow the composition the content needs while retaining language, theme and safety rules.
136
155
 
137
156
  - **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.
138
157
  - **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.
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.
158
+ - **Layout and spacing contract.** The renderer owns the vertical rhythm; Card/Article pages use one readable column. For a free layout (Auto-chosen, on-demand result or free template), follow the composition the content needs. 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
159
  - **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
160
  - **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
161
  - **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
162
  - **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.
163
+ - **Use the file path for an image you already have.** When you or a tool created a PNG/JPEG/WebP/GIF in the workspace (chart export, screenshot, generated figure), pass it to `Image` directly — workspace-relative (`Image("figures/chart.png", "Quarterly revenue")`) or absolute. The app reads it through the session's file permissions; never start a static file server or paste an `http://` URL for a local file, and never say a local image cannot be shown. A missing, oversized or unsupported file renders a clear placeholder; SVG and `HtmlView` local images are not supported.
144
164
  - **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.
165
+ - **Draw the mechanism, don't describe its shape.** When the answer explains a process, loop or request path — how a runtime turns a prompt into tool calls, how a request flows, how a state machine moves — lead with one labeled diagram (stages, arrows, and the state or data passing between them), then add a few sentences of prose. Make the steps explorable when interaction teaches the order (a stepper, tabs or a slider); never make the reader assemble the flow from paragraphs.
145
166
  - **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").
146
167
  - **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`.
147
168
  - **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.
@@ -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
 
@@ -101,20 +101,20 @@ Shows content in a small panel when the trigger is clicked: a definition, a sour
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. No arguments.
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
 
@@ -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 tables.
227
+ Prose with headings, lists, quotes, code, tables and inline images (`![alt](src)`; http(s), a small `data:image` base64 URI, or a workspace image path).
228
228
 
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.
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 (`![alt](<figures/a b.png>)`). 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
 
@@ -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 a URL the user or a tool gave; if it fails, a photo is found for alt.
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.** 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.
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