@zephinel/dsh-intelligent-ui 0.2.2-26-10-21 → 0.4.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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Facebook, Inc. and its affiliates.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 ZumerLab
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/locale/en.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "meta": {
3
3
  "title": "Intelligent UI",
4
- "description": "Intelligent UI for DeepSeek Harness: render OpenUI Lang answers as interactive maps, photos, charts, forms, drawings and working tools inside the Web chat."
4
+ "description": "Interactive answers for DeepSeek Harness: maps, charts, forms and articles, with custom visual templates and chat-native on-demand generation. Use temporary results immediately, adjust or save them later; manage templates and export images or interactive pages."
5
5
  }
6
6
  }
package/locale/zh.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "meta": {
3
3
  "title": "智能 UI",
4
- "description": "DeepSeek Harness 的智能 UI 扩展:把 OpenUI Lang 答案渲染成可交互的地图、照片、图表、表单、手绘图与可操作页面。"
4
+ "description": "DeepSeek Harness 的交互式回答:地图、图表、表单与文章,支持自定义视觉模板和聊天内按需生成。临时结果可直接使用、调整或事后保存,并可管理模板、导出图片或交互页面。"
5
5
  }
6
6
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@zephinel/dsh-intelligent-ui",
3
- "version": "0.2.2-26-10-21",
4
- "description": "Intelligent UI for DeepSeek Harness: render OpenUI Lang answers as interactive maps, photos, charts, forms, drawings and working tools inside the Web chat. Off by default; enable it for one session or all sessions from the composer UI switch.",
3
+ "version": "0.4.0",
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",
7
7
  "exports": {
@@ -24,7 +24,9 @@
24
24
  "README.md",
25
25
  "README.en.md",
26
26
  "LICENSE",
27
- "NOTICE"
27
+ "NOTICE",
28
+ "lib/standalone.js",
29
+ "lib/standalone.css"
28
30
  ],
29
31
  "dsh": {
30
32
  "bundle": {
@@ -46,7 +48,8 @@
46
48
  "check": "npm run build && npm test && npm run test:renderer",
47
49
  "pack:check": "npm pack --dry-run --json",
48
50
  "prepare": "node scripts/build.mjs",
49
- "check:theme": "node test/renderer/theme-torture.mjs"
51
+ "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"
50
53
  },
51
54
  "keywords": [
52
55
  "deepseek-harness",
@@ -77,6 +80,7 @@
77
80
  "@openuidev/react-lang": "^1.0.1",
78
81
  "@types/react": "^18.3.0",
79
82
  "@types/react-dom": "^18.3.0",
83
+ "@zumer/snapdom": "^3.3.6",
80
84
  "esbuild": "^0.25.0",
81
85
  "katex": "^0.16.47",
82
86
  "lucide-react": "^0.562.0",
@@ -10,13 +10,13 @@ whenToUse: "A visual, interactive or computed answer would serve better than pro
10
10
 
11
11
  ## Before you start: is the session enabled?
12
12
 
13
- The extension is opt-in; the host switch has three scopes — **Off**, **This session only**, **All sessions**. 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**, **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:
14
14
 
15
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.
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** (仅本会话) or **All sessions** (全部会话) in the **UI** chip on the right side of the composer, or run `/iui session` / `/iui global`. Do not call `render_ui`, do not fake a card, and do not repeat the ask on later turns.
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
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.
18
18
 
19
- A deployment may also enable **Free composition** on the extension's Plugin detail page (Plugins → Intelligent UI). When the injected prompt says "Free composition is on for this deployment", the design playbook below is advisory rather than a template.
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
 
@@ -34,11 +34,40 @@ Two consequences matter in practice:
34
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
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.
36
36
 
37
+ ## Answer styles
38
+
39
+ The injected prompt owns the effective style decision and appends it to the session prompt; this section only explains how to build each shape. Apply the style you were given:
40
+
41
+ - **Card** — compact, scannable interactive page. Keep cards tight; do not turn a broad request into a long article.
42
+ - **Article** — article-first reading page inside the card: a short coverage summary, a `Toc`, and one `Section` per major part whose body is substantial `Markdown` prose. All core content must be readable without clicking; interactions are optional supplements. The Host rejects an article-style call that has no reachable `Toc` and `Section`, so include both. Keep Section anchors unique within one card. `Section(title, children, anchor?)` lets `anchor` be the stable id while `title` stays display text; `Toc(items, anchors?)` takes the matching parallel anchors. Without anchors the title is the target.
43
+ - **Auto** — choose per request: Card for interactive, structured, visual or computational answers; Article for 详尽/深入/全面/长文/报告/综述 requests.
44
+
45
+ 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.
46
+
47
+ ## On-demand generation and custom templates
48
+
49
+ An `ON-DEMAND UI` request note comes from a Host-armed operation; it is already present in the prompt for the first turn (DSH assembles the system prompt before the user message) and stays while the turn clarifies. Once bound, a plain `render_ui` without `temporaryStyle` is rejected. In that turn, call `render_ui` with a complete `temporaryStyle` and matching `style`, omitting `styleId`. A user's prose request or your tool arguments cannot authorize temporaryStyle: the Host must already allow this operation and the current tool call. If authorization is absent, ask the user to choose **On-demand UI** in the composer; do not arm it yourself.
50
+
51
+ - **Ground the content before styling.** Missing content is material ambiguity. If the request refers to "this analysis", "these contents", "the above data" but none is in the conversation, or its numbers/dates/sources are absent, do not invent placeholder datasets, statistics, dates, quotes or sources. Use `ask_user_question` to ask which content to use (conversation content, pasted/linked data, or explicitly labelled illustrative data); render only after it is available or illustrative data is authorized. Style clarity never excuses missing data.
52
+ - Clear request/grounded context → 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).
53
+ - `temporaryStyle` is a schemaVersion 1 result snapshot: `baseLayout` (`card` or `article`, equal to `style`), nonempty reusable `directives` (up to 2,000 characters), `theme`, optional `suggestedName`. 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.
54
+ - Write transferable design preferences about hierarchy, density, tone and component behavior. Keep this answer's content/private data in the program; directives cannot override system/tool/safety instructions.
55
+ - No preview, naming, saving or settings changes are required. Render once and stop. The extension provides **Adjust style** and **Save as template**; do not save templates yourself or put management buttons in the generated program.
56
+ - For a Host-authorized adjustment, reuse the referenced result's temporary snapshot from the conversation, keep the content and change the requested style only. A new call creates a new result; saving is an optional user action on a specific result.
57
+ - Outside an on-demand turn, a selected custom template requires the exact `styleId` and matching base layout specified by the injected prompt. `styleId` and `temporaryStyle` are mutually exclusive. A temporary result never becomes the selected session style automatically.
58
+
59
+ 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).
60
+
37
61
  ## Workflow
38
62
 
63
+ ### 0. Outline the content first
64
+
65
+ For an Article answer, write the outline before choosing components: every major part, the 2–5 points each must teach, and one concrete example, cause or debate that makes it specific. Completion: you can name every section and its substance without writing code. For a Card answer, this step can be a short list of the blocks and the fact each carries.
66
+
67
+
39
68
  ### 1. Choose the medium
40
69
 
41
- Pick **one to three hero blocks** that carry the idea, then supporting blocks. Name them before writing: "map + timeline + checklist", "KPI row + trend + region donut + top-orders table". Completion: you can say what the page is for and which block answers the question, without writing any code yet.
70
+ For a **Card** page, pick **one to three hero blocks** that carry the idea, then supporting blocks. For an **Article** page, the main body is one readable column: a summary, a `Toc`, and `Section`s with prose; visual blocks are supplements. Name the shape before writing: "map + timeline + checklist" or "summary + toc + sections + one chart". Completion: you can say what the page is for and which block carries the answer, without writing any code yet.
42
71
 
43
72
  Choosing rules of thumb:
44
73
 
@@ -69,14 +98,14 @@ Completion: the program satisfies the hard rules below, and the pre-flight check
69
98
 
70
99
  ### 4. Call the tool
71
100
 
72
- Call `render_ui({ program: <the complete program>, title: "Short noun phrase" })`. 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.
101
+ Call `render_ui({ program: <the complete program>, style: <"card"|"article">, title: "Short noun phrase" })`. Pass `card` for a compact interactive page, `article` for the reading layout; when the session is Auto, pass the style you chose. For a selected custom template add its exact `styleId`; for a Host-authorized on-demand turn instead 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.
73
102
 
74
103
  **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.
75
104
 
76
105
  ### 5. Handle the result
77
106
 
78
107
  - **Success, no warnings** — done. The page is on screen; do not re-call.
79
- - **Success, with warnings** — a name was unresolved or a statement was unreachable. Fix the program and call once more; the warnings name the exact statement.
108
+ - **Success, with warnings** — inspect the named parser finding or contrast warning. Ordinary calls may be repaired once; an on-demand success completes its operation even with warnings, so further changes need the user to arm Adjust style again.
80
109
  - **Fatal error** — read every finding after the `render_ui:` prefix, fix all of them, and retry in the same turn. Two or three attempts are normal. If the same finding returns, re-read the program instead of rewording the message. If retries keep failing, drop the most complex block (Map, HtmlView, nested `@Each`), send a simpler page, and say so in one sentence.
81
110
  - **Tool missing** — follow [Before you start](#before-you-start-is-the-session-enabled): answer in prose, and point at [integration.md](references/integration.md#troubleshooting-a-missing-render_ui) if the user is setting it up.
82
111
 
@@ -85,7 +114,7 @@ Call `render_ui({ program: <the complete program>, title: "Short noun phrase" })
85
114
  1. One program, one statement per line: `name = expression`. It starts with `root`; `root` must evaluate to a component, conventionally `Col`.
86
115
  2. Arguments are **positional**. Omit optional arguments from the end; skip a middle one with `null`. Named syntax (`children: [...]`) is rejected.
87
116
  3. Every referenced name is declared, and every non-root statement is reachable from `root`. Violations are warnings that silently drop content.
88
- 4. Use only the shipped vocabulary: 55 components, 14 core + 59 library `@functions`, 5 action steps — exact names, case-sensitive. Do not invent `@If`, `@Map`, `@Length` or components.
117
+ 4. Use only the shipped vocabulary: 57 components, 14 core + 59 library `@functions`, 5 action steps — exact names, case-sensitive. Do not invent `@If`, `@Map`, `@Length` or components.
89
118
  5. `$` state is declared with literal defaults. Inputs bind their first argument to a `$` variable; only actions mutate state (`@Set`, `@Reset`).
90
119
  6. No control flow: `cond ? a : b` picks values or components, `null` hides a block, `@Each` repeats. No user-defined functions, no string interpolation — concatenate with `+`.
91
120
  7. `@Each(array, "x", template)`: the loop variable exists only inside the template. Inline the template.
@@ -98,10 +127,13 @@ Exact signatures, argument order, enums and function list: [references/component
98
127
 
99
128
  ## Design playbook
100
129
 
101
- **Free composition.** When the injected prompt says "Free composition 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.
130
+ **Free-form layout.** When the injected prompt says "Free-form layout is on for this deployment", this playbook is advisory, not a template: choose the page shape and blocks the content needs, and vary them between answers. The hard rules above and the theme/readability guidance below still apply.
131
+
132
+ The compactness bullets below describe **Card** pages and side cards inside an Article. An Article page follows the Article layout bullet instead: prose is the main content, and a wall of text is not a defect when the user asked for depth.
102
133
 
134
+ - **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.
103
135
  - **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.
104
- - **Spacing is a system.** `gap`/`padding` count 4px steps: inner 1–2, group 3–4, section 5–6. Leave `gap` unset on the page root and on card contents (the app applies the article rhythm); set a gap on `Row`/`Grid` only.
136
+ - **Layout and spacing contract.** The renderer owns the vertical rhythm; a page is one readable column. 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.
105
137
  - **Cards stay compact.** Card title `md`/`sm`; inside a `Card` the display sizes are capped (`lg` 18 → `xl` 22 → `2xl` 26 → `3xl` 30px), so `xl` is for one KPI number, never for the card heading. Body `sm`, at most one short paragraph, then facts as `Badge`s or label/value rows. Cards side by side in a `Grid` carry the same blocks in the same order so they line up.
106
138
  - **Media rows beat walls of text.** A photo beside copy: `Row([Box([SearchImage("Sonoma Plaza", 1.33)], null, null, null, null, "lg", null, 120), Col([Title("Sonoma", "md"), Row([Badge("1 h drive", null, "car"), Badge("Wine country", "purple")], 1, null, null, true), Text("A slow plaza and quiet back roads.", "sm")], 2)], 4, "start")`. Give the image box an explicit width so the row is stable; top-align the text.
107
139
  - **SearchImage for every thing with a look** — place, dish, product, animal, building. 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.
@@ -109,14 +141,14 @@ Exact signatures, argument order, enums and function list: [references/component
109
141
  - **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").
110
142
  - **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`.
111
143
  - **Format for humans.** `@Format(value, "currency", 0, "USD")`, `@Format(value, "percent", 1)`, `@Plural(n, "guest")`, `@FormatDate(date, "long")`. Units belong in the label or unit argument, not in the number.
112
- - **Data stays inline and modest.** A few dozen rows in a literal array is fine; summarize with `@GroupBy`/`@Bucket` and show the top rows in a `Table`. Typical page: 20–80 statements; past ~120, cut blocks rather than shrink everything.
144
+ - **Data stays inline and modest for Card pages.** A few dozen rows in a literal array is fine; summarize with `@GroupBy`/`@Bucket` and show the top rows in a `Table`. Typical Card page: 20–80 statements; past ~120, cut blocks rather than shrink everything. An Article page is content-driven: it may be much longer, and content must not be deleted to satisfy a statement budget. Use one `Markdown` block per section when that keeps the program manageable.
113
145
  - **Theme with tokens.** `Color` tokens and CSS colors adapt to DSH dark/light automatically. Use raw hexes only for illustration (`Svg` fills, heatmap scales via `@MixColor`), and make sure text stays readable in both themes.
114
146
 
115
147
  ## DSH specifics
116
148
 
117
149
  - **The card is turn-tail.** It appears after the turn ends; during generation the process area shows one `Interactive answer` row (「交互式回答」 in a Chinese UI). Do not describe the card as if it were streaming; write the intro sentence as if the page appears at the end.
118
150
  - **Title and collapse are chrome.** The card header shows `title`; when it is omitted the localized default is used ("Interactive answer" in English, 「交互式回答」 in Chinese). The card can be collapsed by the user; the program cannot control that. The rendered card is full-width in the chat column and narrow on mobile — use `Grid` with `minChildWidth`, `Row` with `wrap`, and avoid fixed widths over ~600px.
119
- - **Dark/light is automatic.** Tokens, components and the `HtmlView` document's `color-scheme` follow the host theme. Do not hardcode white backgrounds or black text.
151
+ - **Dark/light is automatic.** Tokens and components follow the host theme; controlled custom themes apply only to the renderer host. Portaled popovers and sandboxed `HtmlView` keep the default host theme. Exported pages freeze the scheme at export time. Do not hardcode white backgrounds or black text.
120
152
  - **`HtmlView` is the only escape hatch** for arbitrary HTML/CSS/JS: canvas games, physics toys, custom animations. It runs in a sandboxed iframe with an opaque origin, no access to the page or its storage, and network limited to script/style/font CDNs and https images. Use it only when components plus `Svg` cannot express the idea, and keep the whole game in one string; it cannot share state with the page.
121
153
  - **`@ToAssistant` starts a new turn.** In this deployment only the message string is forwarded — the optional `context` object is not delivered — so compose needed values into the message: `@ToAssistant("Plan for " + $people + " people on " + $date)`. Keep it short and first-person, and never use it for something the page can already compute.
122
154
 
@@ -132,7 +164,11 @@ Exact signatures, argument order, enums and function list: [references/component
132
164
  8. **Numbers where strings are required** — `Title($n)` fails; write `$n + ""` or `@Format`.
133
165
  9. **Too much page** — more than four block types, lg+ titles inside cards, or a wall of prose in a card. Choose fewer, bigger ideas.
134
166
  10. **Program pasted into prose** — the tool carries the program; the reply stays a sentence.
135
- 11. **Preflighting by editing the plugin** — a scratch harness written into the extension checkout shows the user a spurious file diff in a repository you were not asked to change. Call `render_ui` and use its findings; keep drafts outside the tree.
167
+ 11. **Article page that is only a skeleton** — sections of one-line bullets, cards in place of paragraphs, or a closing "tell me which part to expand". Article needs substantive prose, a `Toc`, and `Section`s; follow up only after a complete answer.
168
+ 12. **Interaction instead of information** — a carousel showing one item at a time, or a quiz, cannot substitute for content the user asked to read. Lead with readable content; add controls only when they add depth, sources or comparison.
169
+ 13. **Preflighting by editing the plugin** — a scratch harness written into the extension checkout shows the user a spurious file diff in a repository you were not asked to change. Call `render_ui` and use its findings; keep drafts outside the tree.
170
+ 14. **Manual vertical spacing** — `Spacer()`, an empty `Box`/`Col`/`Card`, empty `Text`/`Markdown`, or a `Divider` used as a blank. The renderer already owns the rhythm; these produce odd blank bands (and Host warnings).
171
+ 15. **Gap on a block stack** — explicit `gap` on the page root, Section contents or Card body overrides the app rhythm and can double the blank space. Keep gaps on `Row`/`Grid`/`Carousel` and compact control groups only.
136
172
 
137
173
  ## Pre-flight checklist
138
174
 
@@ -144,8 +180,10 @@ Before the call, verify:
144
180
  4. Component names, argument order, optional-argument `null`s and enum values match the reference.
145
181
  5. Values are derived with `@functions`, formatted for display, and safe against empty/zero input.
146
182
  6. The program is complete and self-running: no placeholders, no dependence on a follow-up message.
147
- 7. No file was created or edited outside the requested deliverable — in particular, nothing in the extension checkout was touched to test the program.
148
- 8. The reply around the call is one intro sentence and, after success, at most one closing sentence.
183
+ 7. For an Article answer: every major part is present, each has substantive prose (not only bullets), the core content is readable without interaction, and the page does not claim to be a skeleton.
184
+ 8. No file was created or edited outside the requested deliverable — in particular, nothing in the extension checkout was touched to test the program.
185
+ 9. The reply around the call is one intro sentence and, after success, at most one closing sentence.
186
+ 10. The layout follows the spacing contract: no root/Section/Card gap, no manual vertical spacer or empty blank block, and every stack is left to the renderer's flow rhythm.
149
187
 
150
188
  ## Reference index
151
189
 
@@ -153,9 +191,9 @@ Read these when the task needs more than the injected prompt:
153
191
 
154
192
  | File | Read it when |
155
193
  | --- | --- |
156
- | [references/components.md](references/components.md) | You need an exact signature, default, enum, optional argument position, or the full list of 55 components, 73 functions and 5 action steps. |
194
+ | [references/components.md](references/components.md) | You need an exact signature, default, enum, optional argument position, or the full list of 57 components, 73 functions and 5 action steps. |
157
195
  | [references/language.md](references/language.md) | You are unsure about syntax, hoisting, `$` state, actions, `@Each`, comments, coercion, or want wrong-vs-right snippets. |
158
- | [references/examples.md](references/examples.md) | You want a complete validated program to adapt: itinerary, calculator, SVG tutorial, dashboard, form, quiz + HtmlView game. |
196
+ | [references/examples.md](references/examples.md) | You want a complete validated program to adapt: itinerary, calculator, SVG tutorial, dashboard, form, quiz + HtmlView game, detailed article. |
159
197
  | [references/troubleshooting.md](references/troubleshooting.md) | A call failed, the result carried warnings, the card rendered wrong, or media/map/HtmlView degraded. Contains the verbatim host error strings and the retry loop. |
160
198
  | [references/integration.md](references/integration.md) | The user is installing or adopting the extension, `render_ui` is missing, the skill is missing from the catalog, or you need the tool contract and limits. |
161
199
 
@@ -1,6 +1,6 @@
1
1
  # Components, functions and actions
2
2
 
3
- Complete reference for the OpenUI Lang vocabulary this extension ships: **55 components**, **59 library `@functions`**, **14 core `@functions`** (73 callable in total) and **5 action steps**. Signatures and descriptions are generated from `vendor/spec.json`, the build-time source of the component spec that the host validator enforces (the spec is compiled into `lib/index.js`; `vendor/` is not shipped). A component or argument not listed here does not exist at runtime.
3
+ Complete reference for the OpenUI Lang vocabulary this extension ships: **57 components**, **59 library `@functions`**, **14 core `@functions`** (73 callable in total) and **5 action steps**. Signatures and descriptions are generated from `vendor/spec.json`, the build-time source of the component spec that the host validator enforces (the spec is compiled into `lib/index.js`; `vendor/` is not shipped). A component or argument not listed here does not exist at runtime.
4
4
 
5
5
  > The plugin already injects these signatures into the system prompt. Read this file when you need the grouped notes, an optional argument you have not used, or the full function table in one place.
6
6
 
@@ -26,7 +26,7 @@ Complete reference for the OpenUI Lang vocabulary this extension ships: **55 com
26
26
  - Never add an argument that is not in the signature: extra arguments are a fatal error (`Text takes 8 arg(s), got 9`).
27
27
  - A component used at the root must be a component call, and the convention is `root = Col([...])`.
28
28
 
29
- ## Layout (9 components)
29
+ ## Layout (11 components)
30
30
 
31
31
  ### `Col`
32
32
 
@@ -116,6 +116,26 @@ Fills the free space in a Row.
116
116
 
117
117
  **Notes.** Fills the free space in a Row; put it between items you want pushed apart.
118
118
 
119
+ ### `Section`
120
+
121
+ ```
122
+ Section(title: string, children: Node[], anchor?: string)
123
+ ```
124
+
125
+ Collapsible article section; starts open. The optional `anchor` is the Toc target; when omitted the title is the target.
126
+
127
+ **Notes.** Use for article-first pages: one Section per major part, with `Markdown` prose inside. The header is a full-row toggle; `title` is display text and `anchor` is the stable id, so two Sections may share a display title if they use distinct anchors. Section anchors must be unique within one card.
128
+
129
+ ### `Toc`
130
+
131
+ ```
132
+ Toc(items: string[], anchors?: string[])
133
+ ```
134
+
135
+ Compact table of contents linking to Section anchors. `items` are labels; optional parallel `anchors` decouple labels from targets.
136
+
137
+ **Notes.** Put it near the top of an article page. Each target (the parallel anchor, or the label when anchors are omitted) must exactly match a Section anchor/title. When two labels repeat, pass distinct anchors and the same anchors on both the Toc and the Sections.
138
+
119
139
  ## Text (12 components)
120
140
 
121
141
  ### `Title`
@@ -20,7 +20,7 @@ How to use them:
20
20
 
21
21
 
22
22
  ```openui
23
- root = Col([head, photos, facts, Grid([mapCard, timelineCard], 2, 300, 4), checklistCard, budgetCard, prefs], 5)
23
+ root = Col([head, photos, facts, Grid([mapCard, timelineCard], 2, 300, 4), checklistCard, budgetCard, prefs])
24
24
  $done = []
25
25
  $selected = "外滩晨走"
26
26
  $pace = "轻松"
@@ -57,7 +57,7 @@ prefs = Card([Title("按你的节奏再排一次", "sm"), Form([SegmentedControl
57
57
 
58
58
 
59
59
  ```openui
60
- root = Col([title, intro, controls, figures, poursCard, timerCard, stepsCard, footer, party], 5)
60
+ root = Col([title, intro, controls, figures, poursCard, timerCard, stepsCard, footer, party])
61
61
  $cups = 2
62
62
  $strength = "平衡"
63
63
  $left = 30
@@ -94,7 +94,7 @@ party = Celebration($left == 0)
94
94
 
95
95
 
96
96
  ```openui
97
- root = Col([head, materials, viewer, strip, tip, footer, party], 5)
97
+ root = Col([head, materials, viewer, strip, tip, footer, party])
98
98
  $step = 0
99
99
  materials = Row([Badge("A4 纸 1 张", "info"), Badge("不用剪刀"), Badge("约 3 分钟", "success")], 2, null, null, true)
100
100
  head = Col([Title("十分钟折一架飞得远的纸飞机", "2xl"), Text("换一种画风:这一页全是 Svg 手绘步骤图,没有照片和地图。点缩略图或按钮切步骤,看完最后一步会撒花。", "md", "muted")], 2)
@@ -104,7 +104,7 @@ s1 = Svg([Rect(76, 20, 88, 156, "surface", "ink", 2), Polygon("76,20 120,20 120,
104
104
  s2 = Svg([Polygon("120,20 164,20 120,84", "#e7f0fc", "ink", 1.5), Polygon("120,20 76,20 120,84", "surface", "ink", 1.5), Line(120, 84, 120, 168, "ink", 1.5), SvgText("再折一次", 120, 190, 11, "muted", "middle")], "0 0 240 204")
105
105
  s3 = Svg([Polygon("120,26 62,96 120,154", "surface", "ink", 2), Polygon("120,26 178,96 120,154", "#e7f0fc", "ink", 2), Line(120, 26, 120, 154, "muted", 1), Line(62, 96, 178, 96, "muted", 1), Line(16, 56, 44, 70, "info", 2), Line(10, 88, 38, 94, "info", 2), SvgText("完成 · 试飞", 120, 176, 11, "info", "middle")], "0 0 240 192")
106
106
  drawings = [s0, s1, s2, s3]
107
- viewer = Card([Row([Badge("步骤 " + ($step + 1) + " / 4", "info"), Spacer(), Caption(@Percent($step + 1, 4) + "% 完成")], 2), Box([drawings[$step]], null, null, 3, "surface", "lg"), Title(steps[$step].title, "md"), Text(steps[$step].text, "sm"), Row([Button("上一步", @Set($step, @Clamp($step - 1, 0, 3)), "outline", null, null, "arrow-left", $step == 0), Spacer(), Button("下一步", @Set($step, @Clamp($step + 1, 0, 3)), "solid", null, null, "arrow-right", $step == 3)], 2)], null, 4, 3)
107
+ viewer = Card([Row([Badge("步骤 " + ($step + 1) + " / 4", "info"), Spacer(), Caption(@Percent($step + 1, 4) + "% 完成")], 2), Box([drawings[$step]], null, null, 3, "surface", "lg"), Title(steps[$step].title, "md"), Text(steps[$step].text, "sm"), Row([Button("上一步", @Set($step, @Clamp($step - 1, 0, 3)), "outline", null, null, "arrow-left", $step == 0), Spacer(), Button("下一步", @Set($step, @Clamp($step + 1, 0, 3)), "solid", null, null, "arrow-right", $step == 3)], 2)], null, 4)
108
108
  strip = Grid(@Each(@Range(0, 4), "i", Pressable([drawings[i], Caption((i + 1) + ". " + steps[i].title)], @Set($step, i), i == $step, 2)), 4, 96, 2)
109
109
  tip = Card([Row([Icon("lightbulb", "sm"), Text("机翼后缘向上折 3 mm,飞机就会爬升;重心太靠后会打转,把机头捏紧一点。", "sm")], 2)], "soft")
110
110
  footer = Row([Button("复制折法", @CopyToClipboard("纸飞机:对折出中线 → 两顶角折向中线 → 再折一次 → 对折机身 → 折出机翼(后缘上折 3 mm)"), "outline", null, "sm", "copy"), Button("再教我折一架", @ToAssistant("再教我折一架飞得更远的纸飞机,每一步配 Svg 图。"), "soft", null, "sm", "sparkles")], 2)
@@ -123,7 +123,7 @@ party = Celebration($step == 3)
123
123
 
124
124
 
125
125
  ```openui
126
- root = Col([head, kpis, Grid([trendCard, regionCard], 2, 300, 4), tableCard, note], 5)
126
+ root = Col([head, kpis, Grid([trendCard, regionCard], 2, 300, 4), tableCard, note])
127
127
  $region = "全部"
128
128
  orders = [{date: "2026-07-03", region: "North", product: "Espresso machine", amount: 1290}, {date: "2026-07-06", region: "South", product: "Grinder", amount: 420}, {date: "2026-07-11", region: "East", product: "Espresso machine", amount: 1180}, {date: "2026-07-15", region: "North", product: "Milk pitcher", amount: 85}, {date: "2026-07-19", region: "South", product: "Filter brewer", amount: 560}, {date: "2026-07-24", region: "East", product: "Grinder", amount: 460}, {date: "2026-07-28", region: "North", product: "Espresso machine", amount: 1420}, {date: "2026-08-02", region: "South", product: "Espresso machine", amount: 1330}, {date: "2026-08-06", region: "East", product: "Scale", amount: 130}, {date: "2026-08-10", region: "North", product: "Grinder", amount: 480}, {date: "2026-08-13", region: "South", product: "Filter brewer", amount: 620}, {date: "2026-08-18", region: "East", product: "Espresso machine", amount: 1490}, {date: "2026-08-21", region: "North", product: "Milk pitcher", amount: 95}, {date: "2026-08-25", region: "South", product: "Scale", amount: 140}, {date: "2026-08-28", region: "East", product: "Grinder", amount: 520}, {date: "2026-08-31", region: "North", product: "Espresso machine", amount: 1610}]
129
129
  filtered = $region == "全部" ? orders : @Filter(orders, "region", "==", $region)
@@ -160,7 +160,7 @@ note = Text("数据是演示用的静态数组;筛选、分组和汇总全部
160
160
 
161
161
 
162
162
  ```openui
163
- root = Col([head, formCard, previewCard, note], 5)
163
+ root = Col([head, formCard, previewCard, note])
164
164
  $name = ""
165
165
  $people = 4
166
166
  $date = "2026-11-08"
@@ -191,7 +191,7 @@ note = Text("提交按钮只把这一句请求发回助手;页面上的预览
191
191
 
192
192
 
193
193
  ```openui
194
- root = Col([head, cards, quizCard, resultCard, gameCard, footer, party], 5)
194
+ root = Col([head, cards, quizCard, resultCard, gameCard, footer, party])
195
195
  $a1 = ""
196
196
  $a2 = ""
197
197
  head = Col([Title("咖啡冲煮小测", "2xl"), Text("先点开三张翻面卡复习,再答两道题。答对两题会撒花;页面底部还有一个 15 秒的接豆子小游戏。", "md", "muted")], 2)
@@ -211,3 +211,19 @@ party = Celebration(score == 2)
211
211
  ```
212
212
 
213
213
  ---
214
+
215
+ ## 7. Detailed article: article-first page with Sections and a Toc (7 statements)
216
+
217
+ Used when the effective style is Article. The main body is prose in `Markdown`;
218
+ `Section` supplies the collapsible heading and the anchor target, and `Toc` links
219
+ to the same titles. The chart is a supplement, not a replacement for the prose. If two Sections share a display title, give them distinct anchors and pass the same anchors to `Toc`, e.g. `Toc(["Notes", "Notes"], ["notes-1", "notes-2"])` with `Section("Notes", [...], "notes-1")` and `Section("Notes", [...], "notes-2")`.
220
+
221
+ ```text
222
+ root = Col([title, intro, toc, s1, s2, chart])
223
+ title = Title("Why cities grew along rivers", "2xl")
224
+ intro = Text("A short guide to the geography behind the first urban civilizations.", "md", "muted")
225
+ toc = Toc(["一、Water, silt and surplus", "二、The cost of coordination"])
226
+ s1 = Section("一、Water, silt and surplus", [Markdown("River floodplains offered three things at once: fresh water, fertile silt renewed every year, and a cheap transport surface. In Mesopotamia the Tigris and Euphrates supported irrigation canals by the fourth millennium BCE; in Egypt the Nile's annual flood made basin farming predictable. Surplus grain could feed specialists — potters, priests, scribes — who did not farm.\n\nSurplus alone did not create a city. Storage, records and a way to move grain across a season were equally necessary, which is why early writing and accounting appear together.")])
227
+ s2 = Section("二、The cost of coordination", [Markdown("Large irrigation works required labor beyond a single village. Canal maintenance, flood control and grain storage created a coordination problem that kinship alone could not solve. Temple and palace institutions emerged as the organizations that collected, stored and redistributed the surplus.\n\nThat solution had costs: labor obligations, surveillance and unequal access to stored grain. The first cities were therefore both a technological achievement and a new political order. The debate over whether irrigation caused the state or the state captured irrigation is still open.")])
228
+ chart = Chart("bar", [{name: "Uruk", people: 40000}, {name: "Mohenjo-daro", people: 35000}, {name: "Memphis", people: 30000}], "name", ["people"])
229
+ ```