@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.
@@ -2,48 +2,48 @@
2
2
 
3
3
  dsh-intelligent-ui is a DSH bundle with two halves:
4
4
 
5
- - **Host** (`lib/index.js`, Node): registers the `render_ui` tool, validates programs with `@openuidev/lang-core` against the generated component spec compiled into the bundle, owns the three-scope switch (persistence file + slash command + session projection + per-agent tool visibility), contributes the OpenUI Lang generation prompt as a conditional system-prompt section (`tool:intelligent-ui`, order 3100), serves one volatile settings field (`freeComposition`) read live by the prompt, and registers the shipped Agent Skill when the deployment composes a skill service. `@deepseek-ai/schemastery` is the one runtime dependency, used only for the Config schema the Host settings service reads.
6
- - **Client** (`lib/client.js`, browser): registers a `conversation.chat.turnTail` card that renders every `render_ui` program recorded by the closing turn, a compact `render_ui` process row that keeps the raw program out of the tool list, the composer UI switch in `conversation.input.activity`, and the deployment-wide configuration on the bundle's Plugins detail page in `plugins.bundle.config`. It also registers the extension's zh/en UI dictionaries with the client locale service (`ctx.locale.register('intelligent-ui', { zh, en })`) and declares `locale` on those four slot registrations, so an in-app language switch re-renders all of its chrome.
5
+ - **Host** (`lib/index.js`, Node): registers the `render_ui` tool, validates programs with `@openuidev/lang-core` against the generated component spec compiled into the bundle, owns the per-session switch and answer-style overrides (persistence file + slash command + session projection + per-agent tool visibility), contributes the OpenUI Lang generation prompt as a conditional system-prompt section (`tool:intelligent-ui`, order 3100), serves the global `globalEnabled` / `answerStyle` / `freeComposition` / `exportBackground` / `exportScale` / `removeFollowUps` settings (the prompt reads the enable/style/composition values live; the browser also reads the image-export and page follow-up defaults), validates the model-provided `style` against the effective session style, registers the shipped Agent Skill when the deployment composes a skill service, and (when the deployment composes `webServer`) serves `lib/standalone.js` / `lib/standalone.css` on same-origin routes for interactive-page export. `@deepseek-ai/schemastery` is the one runtime dependency, used only for the Config schema the Host settings service reads.
6
+ - **Client** (`lib/client.js`, browser): registers a `conversation.chat.turnTail` card that renders every `render_ui` program recorded by the closing turn, a compact `render_ui` process row that keeps the raw program out of the tool list, the composer UI switch in `conversation.input.activity`, an export entry in `conversation.chat.assistant-actions` (only for messages whose closing Turn recorded `render_ui`; it saves the Turn's rendered cards as one PNG or one single-file interactive HTML page), and the deployment-wide configuration on the bundle's Plugins detail page in `plugins.bundle.config`. It also registers the extension's zh/en UI dictionaries with the client locale service (`ctx.locale.register('intelligent-ui', { zh, en })`) and declares `locale` on those slot registrations, so an in-app language switch re-renders all of its chrome. The composer control opens built-in Auto/Card/Article preview cards, Custom styles with management, and a bottom On-demand UI entry. `conversation.input.overlay` shows an armed hint/examples/cancel; temporary result cards add a badge and adjust/save actions; the Plugin detail page adds global enablement, the global default style, and the export defaults (background color, 1x/2x, and whether images/pages remove the whole `@ToAssistant` follow-up block (on by default)).
7
7
 
8
8
  The same package ships the Agent Skill in `skills/intelligent-ui/`. A deployment can use the tool without the skill; the skill is what makes an agent good at it.
9
9
 
10
10
  ## Current status
11
11
 
12
- **Published.** `@zephinel/dsh-intelligent-ui@0.2.2-26-10-21` is on npm and the repository is public at `Zephinel/dsh-intelligent-ui`. Prefer the npm or GitHub bundle install below; the local-checkout flow remains available for development.
12
+ **Published.** `@zephinel/dsh-intelligent-ui@0.4.0` is on npm and the repository is public at `Zephinel/dsh-intelligent-ui`. Prefer the npm or GitHub bundle install below; the local-checkout flow remains available for development.
13
13
 
14
14
  ## Requirements
15
15
 
16
16
  - DSH **0.2.1** (validated on `0.2.1-rc.2`), Node **24**.
17
17
  - The **web** profile (or any profile whose app has a browser chat surface); the client half declares `"dsh": { "client": { "platform": "web" } }`.
18
+ - Interactive-page export additionally needs a `webServer` service so the Host can serve the standalone renderer assets; without it image export still works and page export reports a build failure.
19
+ - Style catalog and management require Host `webServer` plus `connection.requestRejection` authentication. On-demand uses the deployment's normal default conversation model services and session events; there is no extension-owned draft model endpoint, `llm` injection or `agentDefaultModel` injection. The structured clarification path additionally needs the built-in `ask_user_question` tool; a text fallback keeps the operation pending for the next message instead of requiring an immediate re-arm.
18
20
  - The app composes the client locale service (`@deepseek-ai/dsh-client-locale`; DSH Web includes it by default). The browser half requires the `locale` service: without it the switch and the card do not mount, while the Host tool and prompt keep working. UI dictionaries live in `src/shared/locales.ts` (`zh` as the key-set source of truth, `en` checked complete); the renderer falls back to English outside DSH.
19
21
  - Network access for the nice-to-haves: Wikipedia/Wikimedia (photo search), OpenFreeMap tiles and OSRM demo routing (Map). Offline, the page still renders with the fallbacks described below.
20
22
  - Runtime dependency **`@deepseek-ai/schemastery`** (~3.18.5), installed with the package; the Host uses it only for the Plugin detail page Config schema.
21
23
  - The package declares **no `engines.dsh` yet**; it was verified against `0.2.1-rc.2`. A later DSH may refuse it until a compatible release lands or an exact-version exemption is granted (below).
22
24
 
23
- ## Three-scope switch (off by default)
25
+ ## Session switch and answer style
24
26
 
25
- The extension costs ~8.5k prompt tokens, so access is opt-in. The host owns one switch with three mutually exclusive scopes; the client only mirrors it. A fresh install starts **off**, and the state survives refresh and DSH restarts.
27
+ The extension costs ~9.5k prompt tokens, so access is opt-in. The deployment-wide defaults live on the Plugin detail page; the composer can override them for one session. A fresh install starts **off** globally, and session state survives refresh and DSH restarts.
26
28
 
27
- - **Off**: every session is disabled.
28
- - **This session**: only the session that selected it is enabled; every other session (including new ones) stays off.
29
- - **All sessions**: every current and future session is enabled.
30
- - **Controls:** the **UI** chip in the composer opens the shell's native menu with **Off**, **This session only** and **All sessions**, or use `/iui off`, `/iui session`, `/iui global`. The chip and menu follow the app's UI language (in a Chinese UI: `UI:关闭 / UI:本会话 / UI:全部` and 「关闭 / 仅本会话 / 全部会话」). A bare `/iui` prints the current scope, `on` and `all` are aliases for `global`.
31
- - **Persistence:** `<DSH_HOME>/dsh-intelligent-ui.json` (default `~/.dsh/dsh-intelligent-ui.json`), written atomically on every flip: `{ "global": false, "sessions": ["<session-id>"] }`. A legacy `{ "enabled": true }` file is read as global. Selecting **off** or **all sessions** clears the session list.
32
- - **What off means for a session:** the `render_ui` schema is denied per agent through `agent.ctx.tools.restrict()`, so it is absent from the request tool catalog; the `tool:intelligent-ui` prompt section resolves to an empty string; a stray call (for example from a request assembled before the switch changed) throws `render_ui is disabled for this session`.
33
- - **What on means for a session:** the `tool:intelligent-ui` prompt section is injected and makes a `render_ui` page the default answer format for structured answers, including introductions, explainers and timelines. Markdown is the bounded exception: a single fact or one or two sentences, an explicit request for text, content that cannot be shown as a page, or two failed calls. The policy lives only in the prompt section; the Agent Skill points at it instead of restating it.
34
- - **Explicit invocation:** a user-invocable `/intelligent-ui` token in direct user input injects the skill as a user-role instructions context; the skill treats that as a direct instruction to answer with `render_ui`. Use it to force a card when the model's own judgement would otherwise answer in prose.
35
- - **Plugin detail page:** the extension contributes a bundle configuration (`plugins.bundle.config`, key `@zephinel/dsh-intelligent-ui`) whose **Free composition** switch writes the volatile `freeComposition` field. Off (default) keeps the design playbook; on appends an advisory note to the injected prompt and marks the skill's Design playbook as guidance. The preference is deployment-wide and read live, so no restart is needed. The page states that this is a prompt-level preference, not enforcement; `/intelligent-ui` remains the way to force a card.
36
- - **Projection and tabs:** the `intelligent-ui` session projection folds the `command/run` + `command/done` pair of the session that flipped it (for the `pending` state) and projects the effective scope for that session. Tabs share **control** flips over a `BroadcastChannel` (`dsh-intelligent-ui-mode`); a typed `/iui` in another tab shows up on that tab's next projection frame or refresh.
37
- - **Deployments without `sessionProjections` + `commands`:** there is no composer control and no persistence, so the extension keeps its legacy **always-on** behavior. DSH Web composes both services, so this only affects minimal custom profiles.
29
+ - **Global defaults (Plugin detail page):** **Enable in all sessions**, the global **Auto / Card / Article** or saved-template style, and the existing **Free-form layout** switch.
30
+ - **Session overrides (composer UI chip):** **Off / This session only / All sessions** for enablement (All sessions means this session inherits the global switch, without changing that switch); `/iui on|off|inherit`. The **This session only** entry opens a style panel: built-in preview cards, saved templates, On-demand UI, and **Follow global**; `/iui style auto|card|article|inherit|<cs_id>`.
31
+ - **Effective values:** session override first, then the global value; `inherit` follows the global value.
32
+ - **Answer style:** `Card` is a compact interactive page; `Article` is a reading layout inside the `render_ui` card (`Toc` + collapsible `Section` + long Markdown prose); `Auto` lets the model choose. The Host appends the effective style to the generation prompt and rejects a `render_ui` style that conflicts with a forced Card/Article setting.
33
+ - **Persistence:** `<DSH_HOME>/dsh-intelligent-ui.json`, written atomically on every session change: `{ "sessions": [...], "offSessions": [...], "styles": { "<session-id>": "article" } }`. A legacy `{ "enabled": true }` or `{ "global": true, "sessions": [...] }` file is still read as migration state. Global values live in the Host settings document.
34
+ - **What off means for a session:** the `render_ui` schema is denied per agent through `agent.ctx.tools.restrict()`, the `tool:intelligent-ui` prompt section resolves to an empty string, and a stray call throws `render_ui is disabled for this session`.
35
+ - **What on means for a session:** the prompt section is injected with the effective style note; structured answers use `render_ui`, and the bounded prose exception still applies (single fact, explicit text request, non-visual content, two failed calls).
36
+ - **Projection:** the `intelligent-ui` session projection folds the `command/run` + `command/done` pair (pending state) and projects `sessionEnable`, `sessionStyle`, `globalEnabled`, `globalStyle`, `enabled`, `style` `pending` and nullable `onDemand` (projection stateVersion 6). The composer control mirrors this projection and sends commands. It also publishes an optimistic view to other tabs over BroadcastChannel; when the host projection catches up, the projection becomes authoritative again.
37
+ - **Deployments without `sessionProjections` + `commands`:** no session controls and no persistence, so the extension keeps its legacy **always-on** behavior. DSH Web composes both services.
38
38
 
39
- The switch is not per-session-only: choosing **all sessions** covers every session opened later, while **this session** deliberately leaves the rest off. Use `/iui off` when you want to stop paying the prompt cost everywhere.
39
+ Use `/iui off` (session override) to stop paying the prompt cost for that session; use the Plugin detail page to change the deployment-wide default.
40
40
 
41
41
  ## UI language
42
42
 
43
43
  The browser half follows DSH's UI language and needs no configuration:
44
44
 
45
45
  - `src/shared/locales.ts` holds one flat dictionary per built-in locale (`zh` is the key-set source of truth, `en` is type-checked against it, `{name}` placeholders are interpolated at lookup). `src/client/index.tsx` registers both with `ctx.locale.register('intelligent-ui', { zh, en })`.
46
- - All four slot registrations declare `locale: 'intelligent-ui'`, so the slot system hands each component the `t` seat; switching the language in Settings re-renders the composer chip, its menu, the card chrome, the Plugin detail page and the renderer's component chrome (map controls, copy button, timer, fallbacks) without a reload.
46
+ - All six slot registrations (turn tail, assistant actions, `tool.call.toolview`, composer activity, composer overlay and the Plugins detail config form) declare `locale: 'intelligent-ui'`, so the slot system hands each component the `t` seat; switching the language in Settings re-renders the composer chip, its menu, the card chrome, the Plugin detail page and the renderer's component chrome (map controls, copy button, timer, fallbacks) without a reload.
47
47
  - The renderer library is also mounted outside DSH by the self-checks and standalone embeds, so `src/lib/render.tsx` accepts the seat as a prop, publishes it through React context, and falls back to English when none is given.
48
48
  - Model-facing text is out of scope: the tool description, the generation prompt and the Agent Skill stay in English, and so do the `/iui` Host replies (DSH's locale service covers browser UI only). The plugin's display title and description come from `locale/en.json` / `locale/zh.json`, a separate `PluginLocalizedMeta` mechanism.
49
49
 
@@ -52,9 +52,9 @@ The browser half follows DSH's UI language and needs no configuration:
52
52
  The package declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, and that patch inserts the host row `id: intelligent-ui` with `name: '@zephinel/dsh-intelligent-ui'`. Installing the repository as a bundle installs the package into the profile and selects it in the profile's ordered layer list:
53
53
 
54
54
  ```sh
55
- # npm (current latest: 0.2.2-26-10-21)
55
+ # npm (current latest: 0.4.0)
56
56
  dsh plugin --profile web add @zephinel/dsh-intelligent-ui
57
- dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.2.2-26-10-21 # pin a version
57
+ dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.4.0 # pin a version
58
58
  # or GitHub
59
59
  dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
60
60
  ```
@@ -65,7 +65,7 @@ DSH Desktop installs the same bundle from the app instead of the CLI: **Plugins*
65
65
 
66
66
  Packaging behavior that matters when publishing:
67
67
 
68
- - The registry tarball ships the prebuilt `lib/` (host and client bundles), `cordis.patch.yml`, `skills/`, `locale/`, `licenses/`, `assets/`, the two READMEs (`README.md` / `README.en.md`), `LICENSE`, `NOTICE` and `icon.svg` (34 files). The generated component spec and generation prompt are build inputs compiled into `lib/index.js`; `vendor/` and `src/` are not shipped.
68
+ - The registry tarball ships the prebuilt `lib/` (host and client bundles), `cordis.patch.yml`, `skills/`, `locale/`, `licenses/`, `assets/`, the two READMEs (`README.md` / `README.en.md`), `LICENSE`, `NOTICE` and `icon.svg` (43 files). The generated component spec and generation prompt are build inputs compiled into `lib/index.js`; `vendor/` and `src/` are not shipped.
69
69
  - A Git checkout installs from source: pnpm runs the package's `prepare` build, so the install may ask for **build-script approval** and needs the toolchain. A registry tarball has nothing to build.
70
70
  - Without `dsh.bundle`, the manager would install the package as a plain dependency with the warning `declares no dsh.bundle — installed as a plain dependency, not a profile layer`, and nothing would load. This package declares it, so that warning means the wrong spec or an old tarball.
71
71
 
@@ -73,7 +73,7 @@ If DSH refuses the package for version incompatibility, either install a compati
73
73
 
74
74
  ```sh
75
75
  dsh plugin --profile web version-exemptions
76
- dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.2.2-26-10-21 --dsh-version 0.2.1-rc.2 --accept-risk
76
+ dsh plugin --profile web allow-version @zephinel/dsh-intelligent-ui@0.4.0 --dsh-version 0.2.1-rc.2 --accept-risk
77
77
  ```
78
78
 
79
79
  Remove it with the mirror command:
@@ -120,9 +120,9 @@ dsh --profile web --dump-config | grep -n intelligent-ui # the entry must be c
120
120
 
121
121
  Verification checklist (remember the switch is off by default):
122
122
 
123
- 0. **Switch present.** The composer shows the **UI** chip in `conversation.input.activity`; its menu offers **Off**, **This session only**, and **All sessions** (localized: 「关闭 / 仅本会话 / 全部会话」 in a Chinese UI). Pick a scope (or run `/iui session` / `/iui global`) before checking the tool and prompt; with the switch off, steps 1–2 are expected to *fail* by design.
124
- 1. **Tool present while on.** With the switch admitting the session, it exposes `render_ui` with the argument schema `{ program: string, title?: string }`. The model-facing description starts "Render an interactive answer as UI in the chat". With the switch off (or scoped to another session), the request tool list must **not** contain `render_ui`.
125
- 2. **Prompt present while on.** With the switch on, the composed system prompt contains the OpenUI Lang section (order 3100) with the 55-component catalog; with the switch off the section resolves to an empty string.
123
+ 0. **Switch present.** The composer shows the **UI** chip in `conversation.input.activity`; its menu offers **Off**, **This session only**, and **All sessions** (localized: 「关闭 / 仅本会话 / 全部会话」 in a Chinese UI). Pick **This session only** (or run `/iui on`) before checking the tool and prompt; with the switch off, steps 1–2 are expected to *fail* by design. The Plugin detail page exposes the global enablement switch, the default Answer style and Free-form layout.
124
+ 1. **Tool present while on.** With the switch admitting the session, it exposes `render_ui` with the argument schema `{ program: string, style: "card"|"article", title?: string, styleId?: string, temporaryStyle?: StyleSnapshot }`. The effective style is built-in or a visible saved template; Auto requires the model to pass the concrete card/article style it chose. The model-facing description starts "Render an interactive answer as UI in the chat". With the switch off (or scoped to another session), the request tool list must **not** contain `render_ui`.
125
+ 2. **Prompt present while on.** With the switch on, the composed system prompt contains the OpenUI Lang section (order 3100) with the 57-component catalog and the effective style note; with the switch off the section resolves to an empty string.
126
126
  3. **Card works.** Ask the model to render a trivial page, or let the skill lead it. The turn ends with a card titled by `title` (or the localized default "Interactive answer" / 「交互式回答」) containing the rendered UI; the process area shows one such row, not the raw program.
127
127
  4. **Skill present.** When the profile composes the skill registry, the session catalog lists `intelligent-ui`; loading it returns the body of `skills/intelligent-ui/SKILL.md`. Without a skill service the tool still works and only the catalog entry is missing.
128
128
 
@@ -152,23 +152,42 @@ Filesystem discovery is only a **manual fallback** for an environment where the
152
152
  | Aspect | Contract |
153
153
  | --- | --- |
154
154
  | Name | `render_ui` |
155
- | Arguments | `{ "program": string, "title"?: string }`, `additionalProperties: false` |
155
+ | Arguments | `{ "program": string, "style": "card"|"article", "title"?: string, "styleId"?: string, "temporaryStyle"?: StyleSnapshot }`, `required: ["program", "style"]`, `additionalProperties: false` |
156
156
  | `program` | One complete OpenUI Lang program, statement per line, `root` first. Passed verbatim by the model; persisted as the tool call's arguments and replayed from history. |
157
157
  | `title` | Optional short card label, e.g. "Day in San Francisco". When omitted the client uses the localized default ("Interactive answer" / 「交互式回答」). |
158
- | Success value | `{ "statements": number, "warnings"?: string[] }` — the parsed statement count and any non-fatal findings (`Unresolved reference: …`, `Unreferenced statement (will not render): …`). |
159
- | Model-visible result | `Interactive UI rendered for the user (<n> statements).` plus ` Parser notes: <warnings joined by "; ">` when warnings exist. |
158
+ | `style` | `"card"` or `"article"`; required. Pass the effective base layout from the prompt; a Host-authorized temporary snapshot overrides the selected style only for that result. In Auto pass the style you chose. |
159
+ | `styleId` | Exact selected custom template id; omit for built-in or temporary styles. Mutually exclusive with temporaryStyle. |
160
+ | `temporaryStyle` | Host-authorized schemaVersion 1 snapshot: baseLayout equals style, reusable directives, controlled theme, optional suggestedName. Model arguments cannot authorize an operation. |
161
+ | Success value | `{ "statements": number, "style": "card"|"article", "styleSource"?: "builtin"|"template"|"temporary", "styleId"?: string, "warnings"?: string[] }` — the parsed statement count, the resolved style recorded with the page, and any non-fatal findings (`Unresolved reference: …`, `Unreferenced statement (will not render): …`). |
162
+ | Model-visible result | `Interactive UI rendered for the user (<n> statements, <style> style).` plus ` Notes: <warnings joined by "; ">` when warnings exist. |
160
163
  | Empty/failed validation | Throws `Error: render_ui: …`; the model sees the message as a tool error and is expected to fix and retry in the same turn. |
161
164
  | Validation | `createParser(componentSpecSchema, "Col")` from `@openuidev/lang-core`; the spec is generated from `vendor/spec.json` at build time and compiled into `lib/index.js`. Fatal findings are parser errors, `incomplete: true`, and an unresolved root. Warnings never block rendering. |
162
165
  | Rendering | Client-side only. The card is appended at the end of the turn that called the tool; multiple calls in one turn render multiple cards, but the tool guidance asks for one. |
163
166
  | Interaction | All `$` state, `@functions`, `@Set`/`@Reset`, charts, maps and SVG run in the browser with no model round trip. `@ToAssistant` seeds the composer draft with the message and submits it, starting a new turn. |
164
- | Persistence | The program string is stored in the session event log as tool arguments; the rendered result is not. A resumed session re-renders from the program. |
167
+ | Persistence | The program and any inline temporaryStyle are recorded in tool arguments; DOM is not persisted. Replay reads those arguments when available in the loaded history window. Temporary replay needs no catalog; saved-template colors resolve from the current catalog and may fall back if missing. |
165
168
  | Trust boundary | `HtmlView` runs in a sandboxed iframe with an opaque origin. Its CSP allows inline code, a few script/style/font CDNs and https images; no other network. Programs cannot reach the chat DOM, cookies or storage. |
166
169
 
170
+ ## Style and operation contracts
171
+
172
+ | Surface | Current contract |
173
+ | --- | --- |
174
+ | Catalog | `GET /api/intelligent-ui/styles?sessionId=<id>` → `{ templates }` visible globally or in that session. Requires webServer + connection authentication. |
175
+ | Save from result | `POST /api/intelligent-ui/styles`, `{ op: "saveFromResult", resultId, name, description?, scope: "global"|"session", sessionId? }` → 201 `{ template }`. Host copies its validated snapshot; no theme/directives/revisionId accepted. Session scope requires the owning sessionId. No automatic selection/default write or model call. Duplicate names fail; no server idempotency key. |
176
+ | Save | Same POST with `{ op: "save", template: { name, description?, baseLayout, directives, theme }, scope, sessionId? }`. Validated persistence API, not a model creation workflow. |
177
+ | Update | Same POST with `{ op: "update", id, patch: { name?, description?, directives? } }`; only these fields may change; returns `{ template }`. |
178
+ | Delete | Same POST with `{ op: "delete", id }` → `{ deleted: id }`; missing template returns 404. |
179
+ | Route limits | Auth checked first; GET/POST only, application/json, 64 KiB maximum body, 15-second read timeout, no-store. No draft/LLM interview routes. |
180
+ | Stores | `<DSH_HOME>/dsh-intelligent-ui-styles.json`: 40 global/20 per-session templates. `dsh-intelligent-ui-results.json`: latest 200 immutable temporary result snapshots with resultId (= callId), sessionId, optional parentResultId and createdAt. Evicted results return `result_missing` when saved. |
181
+ | Operation | `/iui on-demand [off|<client-instance-token> [adjust <resultId>]]`; one active operation per session, armed TTL 10 minutes, up to two clarification rounds. While armed, re-arm replaces; once bound (running/clarifying), re-arm is rejected and needs an explicit cancel. A completed turn that produced no render returns to armed with `resume: true`; the hint stays and the next human message continues the same operation. In-memory states: armed/running/clarifying/completed/failed/cancelled/interrupted. Restart clears operation views; re-arm to continue. |
182
+ | Event binding | Live session/event binds the next human message; ignores injected context, deduplicates seq and constrains tool events by turn. The prompt note is injected while armed because DSH appends the system prompt before the first user/message; it requires content grounding (never fabricate missing data) and, for missing text/link content, a free-form question with no options. A bound on-demand turn rejects a plain render without temporaryStyle. Observed callId + bound operation authorize temporaryStyle. Structured ask_user_question answers resume the operation; pending questions block render. A text-only completed turn re-arms with `resume` and keeps the composer hint until a result renders or the user cancels. Failed/interrupted operations keep a retry/dismiss hint instead of vanishing. Client token limits hint visibility, not the source of the next session message. |
183
+ | Theme boundary | Controlled theme variables apply to the renderer host; portaled popovers and sandboxed iframes retain default theme. Export freezes the resolved per-card theme/scheme, temporary snapshots first, current templates second. |
184
+ | Prompt boundary | Saved-template directives are JSON-quoted bounded display preferences subordinate to system/tool/safety rules. Temporary directives stay result data. Models may render authorized snapshots; saving/management belongs to explicit user actions. |
185
+
167
186
  ## Troubleshooting a missing `render_ui`
168
187
 
169
188
  Work top-down; each step rules out one layer:
170
189
 
171
- 1. **Switch state (start here).** The extension is off by default. Check the composer **UI** control (off / session / global; Chinese UI: 「关闭 / 仅本会话 / 全部会话」) or run `/iui` to print the current scope; if the control is missing, the profile lacks `sessionProjections`/`commands` or the browser half did not load. A tool error reading `render_ui is disabled for this session` means the switch does not admit this session (wrong scope, or a command that has not settled) — pick “this session” or “all sessions” and retry.
190
+ 1. **Switch state (start here).** The extension is off by default. Check the composer **UI** control (Off / This session only / All sessions; Chinese UI: 「关闭 / 仅本会话 / 全部会话」) or run `/iui` to print the current state; if the control is missing, the profile lacks `sessionProjections`/`commands` or the browser half did not load. A tool error reading `render_ui is disabled for this session` means the switch does not admit this session (wrong scope, or a command that has not settled) — pick “this session only” and retry.
172
191
  2. **Right profile.** Installed into `web` but the session runs under another profile (`headless`, `sdk`, custom) → install there too.
173
192
  3. **Composed tree.** `dsh --profile web --dump-config` does not mention `intelligent-ui` → the bundle is not selected or the checkout is not linked. Re-add it (`dsh plugin --profile web add link:$(pwd)` from the checkout, or `node scripts/install.mjs`), then restart.
174
193
  4. **Built artifacts.** For a checkout: `lib/index.js` and `lib/client.js` exist and are newer than `src/`. If not, `npm run build`.
@@ -184,10 +203,11 @@ Work top-down; each step rules out one layer:
184
203
 
185
204
  - The card appears at the **end of the turn** (turn-tail), never inline mid-answer; during generation the process row reads the localized "Interactive answer" (「交互式回答」 in a Chinese UI).
186
205
  - Model-authored programs occasionally fail validation; the host returns exact errors and the model is expected to self-repair in the same turn. Repeated failures are a prompt/model issue, not a host issue.
187
- - The generation prompt is about 8.5K tokens and is sent **only for a session the switch admits**; otherwise the prompt section is empty and the tool schema is hidden. Prompt caching absorbs most of the cost while on.
206
+ - The generation prompt is about 9.5K tokens and is sent **only for a session the switch admits**; otherwise the prompt section is empty and the tool schema is hidden. Prompt caching absorbs most of the cost while on.
188
207
  - Photos, map tiles and routing are third-party services with offline fallbacks (see [troubleshooting.md](troubleshooting.md#runtime-fallbacks-valid-program-degraded-media)).
189
208
  - `Math` relies on the host's global KaTeX styles; if a future DSH shell drops them, formulas degrade to text.
190
209
  - This extension is web-only: profiles without a browser surface register the tool but have no card to render into.
191
210
  - The browser half requires the client locale service (`dsh-client-locale`); a minimal custom profile without it will not mount the switch or the card, while the Host tool and prompt keep working.
211
+ - Interactive pages are self-contained but large (about 3.4–4.9 MB) and keep only the exporting theme; their photos, maps and routing still use the same third-party services as inside DSH.
192
212
  - The `/iui` Host replies and the command palette's command description stay English even in a Chinese UI; both are DSH platform behavior, and the command palette localizes only first-party commands by identity.
193
- - The package is published on npm as `@zephinel/dsh-intelligent-ui@0.2.2-26-10-21`; pin a version for reproducibility. Publishing a new version needs a version bump plus the packaging checks in `test/packaging/`.
213
+ - The package is published on npm as `@zephinel/dsh-intelligent-ui@0.4.0`; pin a version for reproducibility. Publishing a new version needs a version bump plus the packaging checks in `test/packaging/`.
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## The retry loop
6
6
 
7
- 1. **Read the error text.** The host prefixes every rejection with `render_ui: the program is not valid openui-lang and was not shown. Fix it and call render_ui again. ` and then lists one or more findings separated by `; `. Fix **all** findings, not just the first.
7
+ 1. **Read the error text.** Fatal program-validation errors use `render_ui: the program is not valid openui-lang and was not shown. Fix it and call render_ui again. ` and then list one or more findings separated by `; `. Fix **all** findings, not just the first.
8
8
  2. **Locate the statement.** The finding names a field path (`/text`, `/children`, `/size`), a component (`Unknown component "Baz"`), a function (`Unknown function "@Magic"`) or a signature. Match it to the offending statement.
9
9
  3. **Fix the smallest thing.** A rejected program is never partially rendered, so there is no advantage in rewriting the whole page. Change the argument, the name or the missing reference.
10
10
  4. **Call `render_ui` again in the same turn.** Two or three attempts are normal; the validator errors are precise. If the same finding comes back twice, the fix did not apply — re-read the program rather than rephrasing the message.
@@ -13,7 +13,7 @@
13
13
 
14
14
  ## Preflight: call the tool, do not build a harness
15
15
 
16
- `render_ui` is the supported preflight, and retrying is cheap: a rejected program is never partially rendered, and a successful result that carries `Parser notes:` tells you exactly what was dropped. Do not validate a program by adding scratch scripts, tests, fixtures or build output to the extension's own checkout — not even inside a gitignored directory such as `test/renderer/.build/`. The user sees those writes as changes in a repository you were not asked to touch.
16
+ `render_ui` is the supported preflight, and retrying is cheap: a rejected program is never partially rendered, and a successful result that carries `Notes:` tells you exactly what was dropped. Do not validate a program by adding scratch scripts, tests, fixtures or build output to the extension's own checkout — not even inside a gitignored directory such as `test/renderer/.build/`. The user sees those writes as changes in a repository you were not asked to touch.
17
17
 
18
18
  - Write any draft program to a temporary file (for example under `$TMPDIR` or `/tmp`) if it must exist on disk.
19
19
  - Treat the extension source tree as read-only while answering; the only exception is a request that explicitly asks you to change the extension itself.
@@ -22,21 +22,71 @@
22
22
  ## The switch does not admit this session
23
23
 
24
24
  ```text
25
- render_ui is disabled for this session. Turn on Intelligent UI with the composer switch or /iui on|session|global.
25
+ render_ui is disabled for this session. Turn on Intelligent UI with the composer switch or /iui on|inherit.
26
26
  ```
27
27
 
28
- **Cause.** This is a tool-admission error, not a validator error: the program never reached the parser. The host switch is **Off**, or scoped to **This session only** for a different session, or the `/iui` command that flips it has not settled.
28
+ **Cause.** This is a tool-admission error, not a validator error: the program never reached the parser. The session override is **Off**, the session follows a globally disabled switch, or the `/iui` command that flips it has not settled.
29
29
 
30
- **Fix.** Open the **UI** chip in the composer and pick **This session only** or **All sessions** (「仅本会话」/「全部会话」 in a Chinese UI; or run `/iui session` / `/iui global`), then retry in the same turn. If the chip already shows a scope that includes this session, the host half may be stale — restart the DSH host (next section). Never emulate the card with HTML or a fenced block.
30
+ **Fix.** Open the **UI** chip in the composer and pick **This session only** (「仅本会话」 in a Chinese UI; or run `/iui on`), or enable the extension globally on the Plugin detail page, then retry in the same turn. If the chip already shows a scope that includes this session, the host half may be stale — restart the DSH host (next section). Never emulate the card with HTML or a fenced block.
31
31
 
32
32
  ## Red `/iui` rows or a missing UI control
33
33
 
34
- - A red command row reading `Usage: /iui [on|off]` while the **UI** menu offers **This session only** / **All sessions**(「仅本会话」/「全部会话」)means the browser half is newer than the host half: the new menu sends `session`/`global`, the old host only accepts `on|off`. Restart the process serving the DSH Web UI, then refresh the page. This is version skew, not a program error.
34
+ - A red command row reading `Usage: /iui [on|off|inherit]` while the **UI** menu offers a **Follow global** entry means the browser half is newer than the host half: restart the process serving the DSH Web UI, then refresh the page. This is version skew, not a program error.
35
35
  - If the **UI** chip is absent, the profile lacks the `sessionProjections` + `commands` services or the browser half did not load. In that deployment the extension is always-on, so a missing `render_ui` points at the plugin itself — see [integration.md](integration.md#troubleshooting-a-missing-render_ui).
36
36
  - A `Switch failed`(「切换失败」)inline label means the command request failed before it reached the switch; retry once, then report the exact failure line.
37
37
 
38
38
  ## Host error strings (verbatim) and fixes
39
39
 
40
+ ### Temporary style and operation errors
41
+
42
+ These messages are copied from the current Host. Authorization and schema failures happen before program parsing.
43
+
44
+ ```text
45
+ render_ui: styleId and temporaryStyle are mutually exclusive.
46
+ render_ui: temporaryStyle requires a bound, running on-demand operation and its current tool call. The model cannot authorize one.
47
+ render_ui: invalid temporaryStyle snapshot; use schemaVersion 1, a baseLayout, reusable directives and controlled theme tokens.
48
+ render_ui: temporaryStyle.baseLayout must match style.
49
+ render_ui: on-demand operation was cancelled or replaced before completion.
50
+ render_ui: this turn is an on-demand UI request; pass a complete temporaryStyle with a matching style (omit styleId), or ask the user a clarifying question first.
51
+ ```
52
+
53
+ Use only one style source. A temporary snapshot needs a Host-armed operation bound to the human message and current observed `render_ui` call; the model cannot self-authorize. Ask the user to re-arm in the composer after expiry, cancellation or restart. A text-only fallback turn keeps the operation pending (resume) so the next message can continue without re-arming; retry is offered for failed/interrupted turns. A structured question still awaiting an answer blocks rendering; wait for the built-in `ask_user_question` answer first. Match `baseLayout` and `style`, use only schemaVersion 1/controlled theme tokens and bounded reusable directives; omit styleId.
54
+
55
+ For the light ink pair, the exact contrast error is below; the same format uses `dark` and/or `accent` for the other pairs:
56
+
57
+ ```text
58
+ render_ui: temporaryStyle light ink/canvas contrast must be at least 3:1.
59
+ ```
60
+
61
+ Raise the named pair's contrast in the named palette, targeting 4.5:1. Ratios from 3:1 to below 4.5:1 succeed with a `Temporary style … contrast is …:1; 4.5:1 is recommended.` warning.
62
+
63
+ Selected-template errors identify the required template/base layout; for example:
64
+
65
+ ```text
66
+ render_ui: this session uses custom style "Ocean notes"; pass styleId: "cs_ocean01" and style: "card".
67
+ ```
68
+
69
+ Follow that exact id/layout outside an authorized on-demand call. If the template is gone, let the user select another style; do not fabricate it.
70
+
71
+ Command and result-save failures include:
72
+
73
+ ```text
74
+ Enable Intelligent UI for this session before arming on-demand UI (/iui on).
75
+ Usage: /iui on-demand [off|<client-instance-token> [adjust <resultId>]]
76
+ Invalid session or client instance token.
77
+ Invalid on-demand adjustment parent result id.
78
+ An on-demand UI operation is already running in this session; wait for it to finish or cancel it first.
79
+ Too many active on-demand operations. Cancel one and retry.
80
+ This result snapshot is no longer available.
81
+ A style with this name already exists.
82
+ The style library has reached its scope limit.
83
+ The session must match the result.
84
+ This template no longer exists.
85
+ Could not save the style. Check its name, scope and theme, then retry.
86
+ ```
87
+
88
+ The result registry retains only 200 records; eviction can prevent saving while recorded arguments still replay. Save from the result's extension action rather than asking the model to write templates. Re-arming replaces the previous active operation. Keep other tabs from sending in that session while armed: the hint is tab-specific, but the Host binds the next human session message.
89
+
40
90
  ### The program is empty
41
91
 
42
92
  ```text
@@ -161,7 +211,7 @@ The program is incomplete.
161
211
 
162
212
  ### Warnings that are not fatal
163
213
 
164
- These do **not** throw; they come back in the success value and, in the UI, as the `Parser notes:` suffix in the tool result:
214
+ These do **not** throw; they come back in the success value and, in the UI, as the `Notes:` suffix in the tool result:
165
215
 
166
216
  ```text
167
217
  Unresolved reference: missing
@@ -174,8 +224,8 @@ Unreferenced statement (will not render): extra
174
224
  The tool result on success is:
175
225
 
176
226
  ```text
177
- Interactive UI rendered for the user (23 statements).
178
- Interactive UI rendered for the user (23 statements). Parser notes: Unreferenced statement (will not render): extra
227
+ Interactive UI rendered for the user (23 statements, card style).
228
+ Interactive UI rendered for the user (23 statements, card style). Notes: Unreferenced statement (will not render): extra
179
229
  ```
180
230
 
181
231
  ### The tool is missing entirely
@@ -211,7 +261,7 @@ These are not errors to fix in the program; they are how the card behaves when t
211
261
 
212
262
  No error appears, yet the page is not what you intended. Check these in order:
213
263
 
214
- 1. **Warnings** — did the success result include `Parser notes:`? Unresolved references silently null out content.
264
+ 1. **Warnings** — did the success result include `Notes:`? Unresolved references silently null out content.
215
265
  2. **Bindings not bound** — a `$` variable that no component references never changes anything visible; a control that writes an unused variable is a dead input.
216
266
  3. **Chart keys** — `Chart` needs `x` to name a key that exists in every row and `series` to name number keys. Mismatched keys render an empty plot. `@GroupBy`/`@Bucket` rows use `key` and `value`.
217
267
  4. **Map coordinates** — `MapMarker(label, lat, lng)`, in that order; swapped values put the pin in the ocean.