Merge master into fix/conversation-column-one-axis-scroll

.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+2026-08-03-pi-ai-declared-provider-catalog.md: d75b6bdb91d60026636bf320f8c6625590849a41
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: f8dba9900b1a7a3abcb16c70a35cc18f0c44219f

.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md

@@ -0,0 +1,67 @@
+# Agent Note: pi-ai routes are declared providers, not catalog lookups
+
+Status: implemented
+
+English | [中文](2026-08-03-pi-ai-declared-provider-catalog.zh.md)
+
+## Problem
+
+`dsh-llm-pi-ai` treated the pi-ai package's generated catalog as the boundary of what could be configured. A route key had to name an installed provider (`resolveProfiles` rejected anything else), model listing returned `getBuiltinModels(provider)` verbatim, and request-time model resolution looked the id up in that same catalog and overrode only `baseURL`. Three consequences followed, and all three were dead ends rather than gaps: an OpenAI-compatible gateway, a self-hosted server, or a provider newer than the installed catalog could not be configured at all; a model the catalog had not caught up with failed with `UNKNOWN_MODEL` even against a correct endpoint; and a model's context window and output cap were whatever the pinned pi-ai release said, so a deployment could neither correct a stale value nor supply one for a model pi-ai had never described. Upgrading the package was the only way to move any of it.
+
+The adapter also streamed through `streamSimple` from `@earendil-works/pi-ai/compat`, an entry point whose own module documentation declares it a temporary compatibility surface — its catalog reads are `@deprecated`, and it is deleted when pi-ai finishes its `ModelManager` migration. The three configuration limits and the deprecated dependency have the same fix, because pi-ai's supported runtime (`createModels()` / `createProvider()`) is built around a provider being *declared* rather than looked up.
+
+## Decision
+
+A provider route is a **declaration**, and the installed catalog is its default. `resolveProfiles` no longer checks route keys against `getBuiltinProviders()`. Instead each route resolves to a materialized model list plus the pi-ai `Provider` that serves it:
+
+- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — `id`, `name`, `contextWindow`, `maxTokens`. Pricing and input modalities are absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Reasoning is absent for a different reason: a bare capability flag would make pi-ai advertise effort levels with no `thinkingLevelMap` to spell them, so it rides the installed entry or is absent. Materialization spreads the installed entry and overrides those four fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
+- `provider.ts` builds the route's `Provider`. A catalog route that keeps its catalog protocol **reuses** the installed provider with `getModels()` replaced; every other route is built by `createProvider()` over a protocol table whose entries are the same `@earendil-works/pi-ai/api/*.lazy` factories pi-ai's own provider factories use. That table is narrower than pi-ai's full API set on purpose — it holds only protocols a profile can completely describe with a key, an endpoint, and headers, so Bedrock (SigV4 plus a region), Vertex (project, location, ADC), Azure (provider environment plus an api-version), and Codex (OAuth) are absent rather than offered as routes that cannot authenticate. Catalog routes still reach them through their own provider; only an explicit override is refused.
+- `adapter.ts` turns each resolution into an **immutable snapshot** — the profiles plus a `createModels()` collection holding those providers — and every operation captures a whole snapshot before its first `await`.
+- A model's **explicitly configured** `maxTokens` becomes the seam's `defaultMaxTokens`. The value inherited from the installed catalog does not: pi-ai requires `Model.maxTokens` as the model's output *capability*, while `defaultMaxTokens` is a cap the deployment chose to send on requests that name none, and materializing the former as the latter would start capping every request at a number nobody picked.
+
+### Snapshots, not a shared collection
+
+`Models.streamSimple()` resolves its provider lazily, when the returned stream is first consumed — which is after the adapter has awaited the route's credential. A single collection mutated in place would therefore let a request that started under one configuration finish under another, or fail on a provider that no longer exists, even though `llm.prepareCall()` already froze that step's config and captured its adapter registration. A configuration change builds a *new* collection and leaves the one in use alone, so the seam's per-step freeze holds all the way down: switching models mid-reply takes effect on the next step, never inside the one in flight.
+
+### The directory replaces atomically
+
+The configurable-provider directory follows the profiles, so it changes whenever a declared route appears or leaves. Withdrawing the old registration and making a new one cannot express that: a candidate set the registry refuses — a profile keyed `deepseek-official`, which `llm-deepseek` already declares — would leave this plugin's whole directory withdrawn and the Models page empty, silently, because the settings-change callback contains the failure. `registerConfigurableProviders` therefore returns a handle carrying `replace(entries)` with the same validate-the-candidate-set-first atomicity `registerAdapter` has, and the plugin uses it. A refused swap costs a diagnostic; the previous entries keep serving.
+
+Resolution fails loud and names the route and model at fault: a model the catalog does not describe falls back to the route's own `defaultContextWindow`/`defaultMaxTokens`, so a listing that discloses nothing but ids still yields a serviceable route; a route the catalog does not ship needs `api`, `baseURL`, and a non-empty `models` list. Because the built `Provider` is part of the resolution result, a protocol or model error keeps the last good route set serving, exactly as a bad settings snapshot already did.
+
+The configurable-provider directory is now the installed catalog **joined with** every route the current profiles declare, re-registered when that set changes. Without the join a hand-declared route would have no settings address and no configuration surface could show or edit it.
+
+### A capability whose only level does nothing is reported unavailable
+
+pi-ai reports a model with no reasoning metadata as supporting the single level `off`, and the adapter used to pass that straight through. It reaches the seam as a one-item effort list, which every surface renders as a picker holding one selectable control — and that control is a lie: `off` becomes an *omitted* reasoning option at dispatch, byte-for-byte the request that naming no effort already produces. A provider whose own default is to think keeps thinking while the surface shows `off` selected.
+
+`reasoningInfo` therefore omits the seam's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
+
+### Credentials stay outside pi-ai
+
+pi-ai's `Models` carries its own credential concept — a `CredentialStore` keyed by provider id, with `envApiKeyAuth` resolving `credential.key ?? env(VAR)`. Adopting it would have created a second credential source of truth beside `ctx.credentials` and, worse, reintroduced the ambient fallback the harness deliberately forbids: a named-but-missing `apiKeyEnv` must fail with `MISSING_CREDENTIAL` rather than authenticate with whatever unrelated key the environment holds.
+
+`ModelsImpl.applyAuth` honours `options.apiKey` as the request's key, but only through a provider that declares an api-key method: `resolveProviderAuth` short-circuits to that method when the override is present, and otherwise falls through to the credential store and then to ambient discovery, returning nothing — and so failing the request with `Provider is not configured` — when the provider has no api-key method at all. The harness therefore resolves the route's key through its own seam, as before, and passes the result as the request's `apiKey`; the collection is constructed with no credential store.
+
+A route's auth follows from that. A catalog route keeps the installed provider's own `auth`, which preserves provider-native ambient discovery for a profile naming no credential, and keeps it through an `api` override too: which environment a provider reads is a property of the provider, not of the wire format its models speak. The exception is a catalog provider with no api-key method — `openai-codex` authenticates through OAuth alone — where a profile that names a credential also gets the harness method beside the provider's own, because otherwise its configured key would be refused before any request went out. A keyless profile on such a route adds nothing and keeps the honest refusal: this adapter holds no OAuth store to resolve through. A hand-declared route gets a harness-owned `ApiKeyAuth` that reports configured-but-keyless rather than unconfigured, leaving the requirement to the protocol — which is where it lives: pi-ai's OpenAI-compatible implementation still demands a key or an `Authorization` header, and says so itself.
+
+## Alternatives considered
+
+- **Keep `createProvider()` but skip the `Models` collection**, streaming through `provider.streamSimple(model, ctx, {apiKey})`. Smallest diff and the credential path is untouched, but `createProvider`'s `auth` is a required field that this path never invokes — a required-by-signature implementation with no caller. It also leaves `refreshModels` needing a hand-built `RefreshModelsContext`, and keeps the adapter off the runtime pi-ai actually supports.
+- **Reuse the installed provider for catalog routes and `createProvider()` only for declared ones**, with no shared resolution. Zero risk to catalog behavior, but catalog materialization, endpoint override, and per-model configuration would each exist twice, and a catalog route that repoints its protocol would have to jump paths mid-resolution. The chosen split confines the asymmetry to provider construction, where it is forced by pi-ai not exposing a built provider's API implementations.
+- **Rebuild every route through `createProvider()`**, including catalog ones. Fully symmetric, but a built `Provider` does not expose its `api`, so the protocol table would become the ceiling on which providers work — Bedrock loads its Smithy module through a separate entry point and would silently stop working.
+- **Expose pi-ai's whole `Model` shape** (cost, input modalities, `thinkingLevelMap`, `compat`). Maximum configurability, but no current consumer reads those fields, so a configured price or modality would change nothing while reading as supported.
+
+- **Keep one mutable `Models` collection and re-sync it.** Fewer allocations, and correct for every operation that resolves synchronously. It is exactly wrong for the one that does not: `stream()` awaits a credential between capturing its model and dispatching it.
+- **Simulate an atomic directory swap with dispose-then-register.** No seam change, and it works whenever the new set is valid — which is the case that never needed atomicity.
+- **A runtime dynamic catalog** — `fetchModels` plus `ModelsStore`, refreshed in the background. Rejected for this change: it makes the model list external mutable state needing cache, invalidation, and an offline path, and the product need is a one-shot discovery action whose result the user adopts into `settings.yaml`. That action belongs to the configuration surface and is deferred with it; `settings.yaml` stays the single source of truth for what a route serves.
+
+## Consequences
+
+Configuring a provider no longer depends on a pi-ai release. A gateway, a self-hosted server, or a model newer than the pinned catalog is a `settings.yaml` edit, and a stale context window can be corrected in place. The deprecated `/compat` import is gone, so pi-ai deleting it is no longer a breaking event. `defaultMaxTokens` now flows from configuration when a deployment states one, without inventing a cap from catalog metadata.
+
+What it costs: `settings.yaml` grows for a declared route, because it must state its endpoint, protocol, and model ids. `api` applies to a whole route, so a mixed-protocol catalog route cannot host a model of the other protocol — splitting it across two route keys is the workaround. Nothing queries a provider's `/models`, so a model list is only as current as its last edit. Reported error shape shifts in one case: a route whose auth resolves to nothing now surfaces pi-ai's own diagnostic as an error `finish` chunk before any network call, where the previous adapter sent a keyless request and surfaced the provider's 401.
+
+## Testing
+
+`tests/catalog.spec.ts` covers the contract end to end against local mock servers: a hand-declared route streaming to its own endpoint with its own credential, its appearance in the configurable-provider directory, per-model overrides defaulting from the installed catalog, a model added to a catalog route, protocol repointing with and without an endpoint override, catalog-only metadata surviving an override, the keyless posture and its `Authorization`-header workaround, an OAuth-only catalog route authenticating with the key its profile names while a keyless one stays unconfigured, a repointed route keeping its catalog auth, and every resolution failure that names a route or model. `tests/catalog.spec.ts` also pins the snapshot and directory contracts: an in-flight request whose route set changes during its credential await still reaches the endpoint it resolved against, the next request picks up the new one, a colliding declared route leaves the directory whole, and a declared route's entry appears and leaves with its profile. `packages/llm/llm/tests/topology.spec.ts` covers `replace` — refusing a candidate another registration owns while keeping the current set, accepting a swap over its own entries, allowing an empty set, and failing after disposal. `tests/sdk-options.spec.ts` re-targets the SDK boundary from the removed `/compat` import to the protocol table's lazy api module, which also pins that a setup failure arrives as a terminal error chunk rather than a throw. The twin's [design-verification role](2026-06-13-twin-llm-adapters.md) is unchanged.

.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md

@@ -0,0 +1,67 @@
+# Agent Note: pi-ai 路由是被声明的提供方，而不是 catalog 查表
+
+Status: implemented
+
+[English](2026-08-03-pi-ai-declared-provider-catalog.md) | 中文
+
+## Problem
+
+`dsh-llm-pi-ai` 把 pi-ai 包生成的 catalog 当成了可配置范围的边界。路由键必须点名一个已安装提供方（`resolveProfiles` 拒绝其余一切），模型列举原样返回 `getBuiltinModels(provider)`，请求期的模型解析又在同一份 catalog 里查这个 id、且只覆盖 `baseURL`。由此产生三个后果，而且三个都是死路而非缺口：OpenAI 兼容网关、自建服务，或比已安装 catalog 更新的提供方，根本无法配置；catalog 尚未跟上的模型即便端点正确也会以 `UNKNOWN_MODEL` 失败；模型的上下文窗口与输出上限完全由锁定的 pi-ai 版本决定，部署既无法更正过期值，也无法为 pi-ai 从未描述过的模型补上。要动其中任何一条，只能升级依赖。
+
+适配器还经 `@earendil-works/pi-ai/compat` 的 `streamSimple` 发起流式请求，而该入口自己的模块文档声明它是临时兼容面——其 catalog 读取标了 `@deprecated`，并会在 pi-ai 完成 `ModelManager` 迁移时被删除。这三条配置限制与这个废弃依赖的解法是同一个，因为 pi-ai 受支持的运行时（`createModels()` / `createProvider()`）正是围绕「提供方是被*声明*出来的，而非查出来的」建立的。
+
+## Decision
+
+提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
+
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——`id`、`name`、`contextWindow`、`maxTokens`。定价与输入模态不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。推理缺席则是另一个理由：一个孤立的能力布尔量会让 pi-ai 公布出没有 `thinkingLevelMap` 可供拼写的档位，因此它沿用已安装条目或直接缺席。物化时以已安装条目铺底、再覆盖那四个字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
+- `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
+- 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出**能力**，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
+
+### 快照，而不是共享集合
+
+`Models.streamSimple()` 惰性解析 provider——在返回的流首次被消费时，而那已在适配器 await 路由凭据之后。因此就地改动的单一集合，会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider，尽管 `llm.prepareCall()` 早已冻结了该步的 config 并捕获了其适配器注册。配置变化改为构造**新**集合，正在被使用的那个原封不动，于是 seam 的每步冻结得以贯通到底：回复途中切换模型在下一步生效，绝不影响在途的那一步。
+
+### 目录原子替换
+
+可配置提供方目录跟随 profiles，因此每当一条声明路由出现或离开它都会变化。「撤销旧注册再新建一个」表达不了这件事：注册表拒绝的候选集合——比如一份键为 `deepseek-official` 的 profile，而 `llm-deepseek` 已声明了它——会让本插件的整个目录被撤走、Models 页变空，而且是静默的，因为 settings 变更回调把失败容住了。因此 `registerConfigurableProviders` 改为返回带 `replace(entries)` 的句柄，其「候选集先整体校验」的原子性与 `registerAdapter` 相同，插件改用它。被拒的替换只付出一条诊断；先前的条目继续服务。
+
+解析失败得响亮，并点名出问题的路由与模型：catalog 未描述的模型会回落到该路由自己的 `defaultContextWindow`／`defaultMaxTokens`，因此只公布 id 的列表也能得到可服务的路由；catalog 未提供的路由需要 `api`、`baseURL` 和非空的 `models` 列表。由于构造出的 `Provider` 是解析结果的一部分，协议或模型出错时最后可用的路由集合会继续服务——与此前坏的 settings 快照的行为完全一致。
+
+可配置提供方目录现在是已安装 catalog **与**当前 profile 声明的每条路由的并集，并在该集合变化时重新登记。没有这个并集，手工声明的路由就没有 settings 地址，任何配置界面都无法展示或编辑它。
+
+### 唯一档位什么也做不到的能力，报告为不可用
+
+pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适配器此前原样透传。它抵达 seam 时是一个单元素的 effort 列表，任何界面都会把它渲染成一个只有一项可选控件的选择器——而这个控件在撒谎：`off` 在派发时变成被*省略*的 reasoning 选项，与「不点名任何档位」产出的请求逐字节相同。自身默认就在思考的提供方会继续思考，界面却显示 `off` 已选中。
+
+因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 seam 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖每一个手工声明的模型**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
+
+### 凭据留在 pi-ai 之外
+
+pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `CredentialStore`，配合 `envApiKeyAuth` 解析 `credential.key ?? env(VAR)`。采用它会在 `ctx.credentials` 之外制造第二个凭据事实源，更糟的是会把 harness 明确禁止的环境回落重新引进来：点名了却取不到的 `apiKeyEnv` 必须以 `MISSING_CREDENTIAL` 失败，而不是用环境里恰好持有的某个无关密钥完成认证。
+
+`ModelsImpl.applyAuth` 会把 `options.apiKey` 当作该请求的密钥，但这条路必须经由一个声明了 api-key 方法的提供方：`resolveProviderAuth` 在覆盖存在时短路到该方法，否则依次落到凭据存储与环境发现；若提供方压根没有 api-key 方法，它返回空，请求随即以 `Provider is not configured` 失败。因此 harness 一如既往经自身 seam 解析路由密钥，并把结果作为请求的 `apiKey` 传入；该集合构造时不带任何凭据存储。
+
+路由的 auth 由此推出。catalog 路由保留已安装提供方自己的 `auth`，从而为不点名凭据的 profile 保住其提供方原生环境发现，且在 `api` 覆盖之下同样保留：提供方读哪个环境是提供方自身的属性，而非其模型所讲协议格式的属性。例外是没有 api-key 方法的 catalog 提供方——`openai-codex` 只走 OAuth——此时点名了凭据的 profile 会在提供方原有 auth 之外再获得 harness 的方法，否则它配置的密钥会在任何请求发出之前被拒。这类路由上不点名凭据的 profile 什么也不加、并保留那句诚实的拒绝：本适配器没有可供解析的 OAuth 存储。手工声明的路由则获得一个 harness 自有的 `ApiKeyAuth`，它报告「已配置但无密钥」而非「未配置」，把该要求留给协议——那才是它真正所在的位置：pi-ai 的 OpenAI 兼容实现仍要求密钥或 `Authorization` 标头，并且会自己说出来。
+
+## Alternatives considered
+
+- **保留 `createProvider()` 但不建 `Models` 集合**，改由 `provider.streamSimple(model, ctx, {apiKey})` 发起。改动最小且凭据路径原封不动，但 `createProvider` 的 `auth` 是必填字段，这条路上它永远不会被调用——一份因签名而必填、却没有调用方的实现。它还让 `refreshModels` 需要手工构造 `RefreshModelsContext`，并使适配器始终不在 pi-ai 真正支持的运行时上。
+- **catalog 路由复用已安装提供方，只有声明式路由走 `createProvider()`**，且两者不共享解析。对 catalog 行为零风险，但 catalog 物化、端点覆盖与每模型配置这三件事都要各写两遍，而改指协议的 catalog 路由还得在解析中途跳到另一条路径。已采纳的拆法把不对称收敛在提供方构造这一处——那里的不对称是 pi-ai 不暴露已构造提供方的 API 实现所强加的。
+- **让每条路由都经 `createProvider()` 重建**，包括 catalog 路由。完全对称，但已构造的 `Provider` 不暴露自己的 `api`，于是协议表会成为「哪些提供方能用」的天花板——Bedrock 经独立入口加载其 Smithy 模块，会因此静默失效。
+- **完整暴露 pi-ai 的 `Model` 形状**（成本、输入模态、`thinkingLevelMap`、`compat`）。可配置性最大，但这些字段当前没有任何读取方，因此配了价格或模态什么也不会改变，却看起来像是受支持的。
+
+- **保留单个可变 `Models` 集合并重新同步。** 分配更少，且对每个同步完成解析的操作都是正确的；唯独对那个不同步的操作恰恰是错的：`stream()` 会在捕获模型与派发模型之间 await 一次凭据。
+- **用「先 dispose 再注册」模拟目录原子替换。** 无需改 seam，且在新集合有效时确实可用——而那正是从不需要原子性的那种情形。
+- **运行时动态 catalog**——`fetchModels` 加 `ModelsStore`，后台刷新。本次变更拒绝：它把模型列表变成需要缓存、失效与离线路径的外部可变状态，而产品需求是一次性的发现动作、其结果由用户采纳进 `settings.yaml`。该动作属于配置界面，与之一并暂缓；`settings.yaml` 始终是「路由服务什么」的唯一事实源。
+
+## Consequences
+
+配置一个提供方不再取决于 pi-ai 的发布节奏。网关、自建服务，或比锁定 catalog 更新的模型，都是一次 `settings.yaml` 编辑，过期的上下文窗口也能就地更正。废弃的 `/compat` 导入已经消失，因此 pi-ai 删除它不再是破坏性事件。`defaultMaxTokens` 现在只在部署明确给出时才自配置流出，不会从 catalog 元数据里发明一个上限。
+
+代价是：声明式路由会让 `settings.yaml` 变长，因为它必须自报端点、协议与模型 id。`api` 作用于整条路由，因此混合协议的 catalog 路由无法承载另一种协议的模型——把它拆成两个路由键是变通办法。没有任何环节查询提供方的 `/models`，因此模型列表的新鲜度只到最近一次编辑为止。有一种情形下报错形状发生变化：auth 解析不出任何值的路由，现在会在任何网络调用之前把 pi-ai 自己的诊断作为错误 `finish` 分片呈现，而此前的适配器会发出无密钥请求并呈现提供方的 401。
+
+## Testing
+
+`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该契约：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项契约：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。

.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+2026-08-04-declaring-a-provider-from-the-models-page.md: 53996e488c467e00754837b83b7a33994d4813ee
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: fa61c48492eabf51f3d325078ceffa84ac52d12c

.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md

@@ -0,0 +1,43 @@
+# Agent Note: Declaring a provider from the Models page
+
+Status: implemented
+
+English | [中文](2026-08-04-declaring-a-provider-from-the-models-page.zh.md)
+
+## Problem
+
+The two layers below made a pi-ai route [a declaration](2026-08-03-pi-ai-declared-provider-catalog.md) and gave the host a way to [interrogate a draft endpoint](2026-08-04-draft-provider-endpoint-interrogation.md). Neither reached a person who does not edit YAML: the Models page still offered one API-key field per provider and a fold with a base URL, so adding a gateway meant opening `$DSH_HOME/settings.yaml` and knowing the profile shape, and correcting a stale context window meant the same. The capability existed and the surface did not expose it.
+
+Two things were missing, and they are not the same shape. Editing an existing route's models is a *field* on a card that already exists. Declaring a route is a *create*: the route id is being chosen, so until it is chosen there is no settings address to edit.
+
+## Decision
+
+The model list is a component shared by both flows; the create is its own card.
+
+`ModelListEditor` edits a profile's `models` array — one row per model with id, display name, context window, and output cap — and owns the fetch action. An empty list means "serve this route's built-in catalog", so a row is only ever added deliberately; clearing an optional field drops it rather than storing a value the schema would reject, and a capacity that is not a positive integer is not stored at all.
+
+Fetching asks about the endpoint **the form currently shows** — a base URL edited but unsaved, a key typed but unstored — so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end; the adapter's own message appears beside rows that stay editable by hand.
+
+`CustomProviderCard` declares a route pi-ai does not ship. It is a separate card because the route id is chosen here: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. The three facts a hand-declared route cannot default — endpoint, protocol, and at least one model — gate the create button, so a failure names the field while the user is still looking at it.
+
+The protocol choices come from the namespace's **own schema**, read through the settings descriptor the page already fetches (`providers.*.api` is a union of the adapter's `supportedProtocols()`). No new wire field, no constant in the client, and no way for the offered choices to drift from the accepted ones.
+
+## Alternatives considered
+
+**Declare a provider through `ProviderEditor` with extra fields.** One card instead of two, but the editor is addressed by `settingsPath`, and a route being named has no path yet. Recomputing the path per keystroke would remount the card and discard the draft; deferring it would mean the editor's whole write path no longer described what it was editing.
+
+**Add a wire field for the protocol list.** Explicit, and the obvious first instinct. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
+
+**Fetch against the stored profile instead of the live form.** No key would leave the form for an unsaved provider. But the flow that needs fetching most is the one where nothing is stored yet, and a form whose endpoint was edited would quietly interrogate the old one.
+
+**Write adopted candidates straight into the list.** Fewer clicks, but a fetch would then overwrite capacities the user had corrected, and a listing that discloses only ids would replace real numbers with nothing.
+
+## Consequences
+
+A gateway, a self-hosted server, or a model newer than the installed catalog is now configurable without leaving the browser, and the endpoint itself supplies the model ids where it can. The page grew two components and one shared list editor; the editor card's pi-ai fold grew from two fields to a list.
+
+What it costs: only pi-ai routes can be hand-declared, because `llm-pi-ai` is the one namespace whose profiles describe a whole provider — a `llm-deepseek` route stays a composition fact. Interrogation reaches only OpenAI-compatible endpoints, so a gateway speaking another protocol reports that it cannot be asked and its models are typed in. And the page now holds a key in component state for the duration of a fetch, which is the same exposure `credentials.set` already has and no longer than the card lives.
+
+## Testing
+
+`packages/client/ui-models/tests/provider-form.spec.tsx` drives the rendered page over a scripted wire face: adding, editing, and removing rows; a cleared optional field leaving the profile and a non-integer capacity never entering it; the interrogation carrying the edited endpoint, the unsaved key, and the profile's protocol; the picker's default selection, toggling, cancel, and adopt-keeps-tuned-rows; the empty, refused, and rejected-transport paths; the create writing one profile plus its credential; every gate on the create button; and the read-only posture. `protocolChoices` is covered against a schema that declares the union and one that does not.

.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md

@@ -0,0 +1,43 @@
+# Agent Note: 在 Models 页上声明一个提供方
+
+Status: implemented
+
+[English](2026-08-04-declaring-a-provider-from-the-models-page.md) | 中文
+
+## Problem
+
+下面两层已经让 pi-ai 路由变成[一份声明](2026-08-03-pi-ai-declared-provider-catalog.md)，并给了 host [询问草稿端点](2026-08-04-draft-provider-endpoint-interrogation.md)的能力。但两者都没有抵达不编辑 YAML 的人：Models 页仍然只为每个提供方提供一个 API 密钥输入框和一个装着 API 地址的折叠区，因此接入一个网关意味着打开 `$DSH_HOME/settings.yaml` 并知道 profile 的形状，更正一个过期的上下文窗口也是如此。能力已经存在，界面却没有暴露它。
+
+缺的是两件事，而它们的形状并不相同。编辑既有路由的模型，是一张已经存在的卡片上的一个*字段*；声明一条路由则是一次*创建*：路由 id 正在此处被选定，而在选定之前根本没有可编辑的 settings 地址。
+
+## Decision
+
+模型列表是两条流程共用的组件；创建则是它自己的卡片。
+
+`ModelListEditor` 编辑 profile 的 `models` 数组——一行一个模型，含 id、显示名称、上下文窗口与输出上限——并持有获取动作。空列表意味着「使用该路由的内置 catalog」，因此每一行都只会被刻意添加；清空某个可选字段会丢弃它，而不是存入一个 schema 会拒绝的值，不是正整数的容量则根本不会被存下。
+
+获取会询问表单**当前显示**的端点——已修改但未保存的 API 地址、已键入但未存储的密钥——因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路；适配器自己的消息会出现在各行旁边，而这些行仍可手工编辑。
+
+`CustomProviderCard` 声明 pi-ai 未提供的路由。它之所以是独立卡片，正因为路由 id 是在这里选定的：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的三件事——端点、协议、至少一个模型——会门控创建按钮，因此失败会在用户仍看着该字段时点名它。
+
+协议选项来自该 namespace **自己的 schema**，经页面本就会获取的 settings 描述符读出（`providers.*.api` 是适配器 `supportedProtocols()` 的一个 union）。没有新增协议字段，客户端里没有常量，提供的选项也无从与被接受的集合发生漂移。
+
+## Alternatives considered
+
+**在 `ProviderEditor` 上加字段来声明提供方。** 两张卡片变一张，但编辑器由 `settingsPath` 寻址，而正在被命名的路由还没有路径。逐次按键重算路径会让卡片重新挂载并丢掉草稿；推迟计算则意味着编辑器的整条写入路径不再描述它正在编辑的东西。
+
+**为协议列表新增一个协议字段。** 显式，也是最直觉的第一反应。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
+
+**针对已存 profile 而非实时表单发起获取。** 对尚未保存的提供方来说，密钥就不会离开表单。但最需要获取的恰恰是「什么都还没存」的那条流程，而端点已修改的表单会悄悄去询问旧地址。
+
+**把采纳的候选直接写进列表。** 点击更少，但一次获取就会覆盖用户已更正的容量，而只公布 id 的列表会把真实数字替换成空。
+
+## Consequences
+
+网关、自建服务，或比已安装 catalog 更新的模型，如今无需离开浏览器就能配置，而模型 id 在端点能提供时由端点自己给出。页面多了两个组件和一个共用的列表编辑器；编辑卡片的 pi-ai 折叠区从两个字段长成了一个列表。
+
+代价是：只有 pi-ai 路由可以手工声明，因为 `llm-pi-ai` 是唯一一个其 profile 描述整个提供方的 namespace——`llm-deepseek` 路由仍是组合面的事实。询问只覆盖 OpenAI 兼容端点，因此讲其他协议的网关会报告自己无法被询问，其模型需手工键入。另外，页面在一次获取期间会把密钥保存在组件状态里，这与 `credentials.set` 已有的暴露面相同，且不长于卡片的存活时间。
+
+## Testing
+
+`packages/client/ui-models/tests/provider-form.spec.tsx` 在脚本化的协议面之上驱动渲染后的页面：添加、编辑与移除行；被清空的可选字段离开 profile、非整数容量从不进入；询问携带已修改的端点、未保存的密钥，以及 profile 自身的协议；选择框的默认选中、勾选切换、取消，以及「采纳保留已调优的行」；空列表、被拒、传输被拒三条路径；创建写入一份 profile 加其凭据；创建按钮上的每一道门控；以及只读姿态。`protocolChoices` 针对「声明了该 union」与「没有声明」两种 schema 都有覆盖。

.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
+2026-08-04-draft-provider-endpoint-interrogation.md: 65545098cd1063c40081481c1ac8f0afdb4fb390
+2026-08-04-draft-provider-endpoint-interrogation.zh.md: cb09042904f4ab1558c0c214d275a934234955ac

.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md

@@ -0,0 +1,50 @@
+# Agent Note: Interrogating a draft provider endpoint
+
+Status: implemented
+
+English | [中文](2026-08-04-draft-provider-endpoint-interrogation.zh.md)
+
+## Problem
+
+Once a pi-ai route became [a declaration rather than a catalog lookup](2026-08-03-pi-ai-declared-provider-catalog.md), a person adding an OpenAI-compatible gateway had to know its model ids before they could configure it. The adapter no longer constrains them to an installed catalog, which is the point, but it also means nothing tells the user what the endpoint actually serves — and most of these endpoints do publish that list at `GET /models`.
+
+The obvious answer, a dynamic runtime catalog refreshed in the background, was rejected with the layer below it: it makes a route's model list external mutable state needing a cache, an invalidation story, and an offline path, while the product need is narrower. What is needed is a *question asked once*, whose answer the user adopts into `settings.yaml` — so `settings.yaml` remains the only thing deciding what a route serves.
+
+The awkward part is that the question is about something that does not exist yet. The provider being added has no route, no stored profile, and no stored credential; the endpoint and key are values in a form the user is still typing. Every existing seam operation is keyed by a registered provider route, so none of them can carry this.
+
+## Decision
+
+Interrogation is keyed by **settings namespace**, not by provider route:
+
+- `ctx.llm.registerModelDiscovery(settingsNs, discover)` lets an adapter plugin offer to interrogate endpoints for the namespace it owns, and `ctx.llm.discoverModels(settingsNs, request)` asks. There is no way to enumerate which namespaces registered: a surface that cannot interrogate learns it from the refusal, and a list nothing consumed would be a required wire field doing nothing. The namespace is the right key because a configuration surface already holds it from the configurable-provider directory, and because a provider being added has no route to name.
+- `LlmModelDiscoveryRequest` carries the draft — an optional `provider`, an optional `baseURL`, an optional `api`, an optional `apiKey`, and a signal — and needs at least one of `provider` or `baseURL` to have anything to answer about. `provider` exists because a route the adapter already describes is answered from its own registry with no network call at all; only a route it does not describe reaches an endpoint. Nothing in this path writes settings or credentials. The one read is the credential of a route the request names: a configuration surface holds a redacted descriptor rather than the stored secret, so the draft's `apiKey` is present only while the user is typing one, and without that read an already-configured route would be interrogated unauthenticated and answer 401. The typed key wins, being the one under test.
+- `LlmDiscoveredModel` makes every field but `id` optional, because most listings disclose an id and nothing else. The reply is candidates, not a catalog: a surface adopting one still owes the capacities the adapter requires.
+- `llm.discoverModels` carries the same draft over the wire. Its `apiKey` is the third and last payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`, and it is never stored or echoed back. It does ride the client's outgoing envelope like every other secret-bearing payload, where a `subscribeEnvelopes()` observer can see it; redacting that tap is a configuration-plane-wide change, not this method's to make alone. The method is loopback-only for a second reason besides the key: it makes the host issue a GET to a caller-chosen URL and reports the outcome, which is a probe an anonymous LAN caller must not have. Every refusal folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered.
+
+`dsh-llm-pi-ai` implements the wire path as a plain `GET {baseURL}/models`, reading `openai-completions` and `openai-responses`: their `GET /models` shape with bearer auth is the one a gateway, a self-hosted server, and the official endpoints all agree on. Azure is excluded despite its OpenAI lineage — it authenticates with an `api-key` header and requires an `api-version` query — and Codex uses OAuth; both would have reported an authentication failure as a provider with no models. Every other protocol answers `DISCOVERY_UNSUPPORTED`, so the surface falls back to hand-entry rather than reporting a guessed response shape as an empty provider. `baseURL` is treated as a prefix rather than a URL to resolve against, so a deployment path such as `https://gateway.example/openai/v1` keeps its segments. The reply is read under a four-megabyte ceiling enforced on the bytes actually received — the endpoint is a URL the user typed, so a declared `content-length` is checked first as a courtesy but never trusted as the bound, matching `dsh-web-fetch`'s two-stage shape for its own caller-supplied URLs.
+
+### Why not pi-ai's own refresh machinery
+
+pi-ai supplies `createProvider({ fetchModels })` plus `Models.refresh()` and a `ModelsStore`, and the layer below already builds pi-ai `Provider` objects. Routing interrogation through them would have meant constructing a throwaway provider and collection per question, with a store whose entire purpose — persisting a catalog across runs — contradicts the decision that `settings.yaml` owns the catalog. It would also have bought nothing: **no built-in pi-ai provider implements `fetchModels`**, so the HTTP call and its response parsing are this package's code either way. A direct fetch says what is actually happening. The route's stored credential is resolved by the plugin's own per-request resolver, and only on the branch that reaches the network, so a catalog route answers without touching credentials and never fails over one the question did not need.
+
+## Alternatives considered
+
+**Key interrogation by provider route.** Symmetric with every other seam operation, and it would let the request omit the endpoint. But the case that motivates the feature — adding a provider — has no route, so the operation would only work for providers already configured, which are the ones that need it least.
+
+**Put the capability on `LlmAdapter`.** Adapters are reached through a route registration, so this has the same problem, plus it would make an adapter instance answer questions about endpoints it does not serve.
+
+**Have the host read the stored profile instead of accepting a draft.** No secret would cross the wire for an already-configured provider. But adding a provider would then require saving an unusable configuration first, and a form whose endpoint was edited but not yet saved would silently interrogate the old one. Accepting the draft keeps what the user sees and what is asked identical — with the credential as the one exception, because it is the one field a surface is never shown and so can never put in the draft.
+
+**Interrogate every pi-ai protocol.** Anthropic's listing happens to share OpenAI's envelope, and Google's does not. Supporting the ones that are easy would make coverage arbitrary and, worse, make a wrong guess at a response shape indistinguishable from a provider with no models. A protocol that says it cannot be interrogated sends the user to hand-entry, which is the documented fallback.
+
+**Buffer the reply with `response.text()` and check its length.** Simpler, but the bound would arrive after the bytes did, and the endpoint is whatever URL the user typed.
+
+## Consequences
+
+A person adding a gateway can ask it what it serves instead of hunting through its documentation, and the answer arrives as candidates they choose from rather than as configuration written behind their back. The seam gained a registry that is deliberately small: one offer per namespace, no storage, no lifecycle beyond the fiber.
+
+What it costs: the wire gained a third secret-carrying payload, so the configuration plane's write-only surface is now three methods rather than two. Discovery coverage is protocol-shaped rather than provider-shaped — an Anthropic-compatible gateway must be filled in by hand even though its listing would parse. And because nothing re-runs the question, a model list is still only as current as its last edit; that is the same trade the layer below made deliberately.
+
+## Testing
+
+`packages/llm/llm/tests/topology.spec.ts` covers the registry: one offer per namespace, disposal with the fiber, normalization that drops duplicate and unusable ids without inventing capacities, and the `NO_DISCOVERY`/`INVALID_DISCOVERY` refusals. `packages/llm/llm-pi-ai/tests/discovery.spec.ts` drives the probe against local HTTP servers — a listing with and without disclosed capacities, a preserved deployment path, an absent credential, a configured route supplying its own where the draft has none and a typed key winning over it, a catalog route answering without resolving one at all, dropped rows, 401/403 versus a server fault, a non-listing and a non-JSON body, an unreachable endpoint, caller cancellation, an unsupported protocol, and the size ceiling in both its declared-length and streamed forms. `packages/host/apiproxy/tests/api-proxy-config.spec.ts` covers the RPC over a real proxy: the draft reaching its namespace whole, absent fields staying absent, no namespace or credential being written, and a failure surfacing as `model-discovery-failed` with the credential absent from the serialized error.

.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md

@@ -0,0 +1,50 @@
+# Agent Note: 询问草稿中的提供方端点
+
+Status: implemented
+
+[English](2026-08-04-draft-provider-endpoint-interrogation.md) | 中文
+
+## Problem
+
+当 pi-ai 路由变成[一份声明而非 catalog 查表](2026-08-03-pi-ai-declared-provider-catalog.md)之后，要接入一个 OpenAI 兼容网关的人，必须先知道它的模型 id 才能完成配置。适配器不再把人限制在已安装 catalog 里——这正是那次改动的目的——但也意味着没有任何东西告诉用户该端点究竟服务什么，而这类端点大多在 `GET /models` 上公布了这份列表。
+
+显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是**只问一次**，其答案由用户采纳进 `settings.yaml`——从而让 `settings.yaml` 始终是唯一决定路由服务什么的东西。
+
+麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 seam 操作都以已注册的提供方路由为键，因此没有一个能承载它。
+
+## Decision
+
+询问以 **settings namespace** 为键，而不是提供方路由：
+
+- `ctx.llm.registerModelDiscovery(settingsNs, discover)` 让适配器插件为自己拥有的 namespace 提供「询问端点」的能力，`ctx.llm.discoverModels(settingsNs, request)` 发起询问。没有任何办法枚举哪些 namespace 注册过：询问不了的界面会从那句拒绝里知道，而一份无人消费的列表只会变成一个什么都不做的必填协议字段。以 namespace 为键是对的，因为配置界面已经从可配置提供方目录里拿到了它，也因为正在新增的提供方没有路由可点名。
+- `LlmModelDiscoveryRequest` 携带草稿——可选的 `provider`、可选的 `baseURL`、可选的 `api`、可选的 `apiKey`，以及一个 signal——且 `provider` 与 `baseURL` 至少要有一个，才有东西可答。`provider` 之所以存在，是因为适配器已经描述过的路由直接由它自己的注册表作答、完全不联网；只有它未描述的路由才会抵达某个端点。这条路径不写 settings 与 credentials。唯一的读取是请求所点名路由的凭据：配置界面拿到的是脱敏描述符而非已存的机密，因此草稿里的 `apiKey` 只在用户正键入时才存在；没有这次读取，已配置好的路由就会被不带认证地询问，只换回一个 401。键入的密钥优先，因为那正是被测试的那一把。
+- `LlmDiscoveredModel` 除 `id` 外每个字段都可选，因为大多数列表只公布 id。回复是候选而非 catalog：采纳其中一条的界面仍要补上适配器所需的容量。
+- `llm.discoverModels` 把同一份草稿送过协议层。它的 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。它确实会像其他承载机密的载荷一样随客户端外发信封同行，`subscribeEnvelopes()` 观察者看得到；把那个抽头脱敏是整个配置面的改动，不该由这一个方法独自决定。除密钥之外它被钉在回环还有第二个理由：它让宿主向调用方选定的 URL 发起 GET 并回报结果，这是匿名 LAN 调用者不该拥有的探测能力。每一种拒绝都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。
+
+`dsh-llm-pi-ai` 的实现只是一次朴素的 `GET {baseURL}/models`，且仅限 OpenAI 兼容协议。它们的列表形状是网关、自建服务与官方端点三方一致认可的那一种，而这正是该动作存在的场景。其余协议一律以 `DISCOVERY_UNSUPPORTED` 回答，让界面回退到手工填写，而不是把猜错的响应形状报成一个空提供方。`baseURL` 按前缀而非待解析 URL 处理，因此 `https://gateway.example/openai/v1` 这类部署路径会保留其路径段。回复在四兆字节上限下读取，且上限落在实际收到的字节上——端点是用户自己填的 URL，因此会先看声明的 `content-length` 作为善意提示，但绝不把它当作边界；这与 `dsh-web-fetch` 面对自己的调用方提供 URL 时所用的两段式形状一致。
+
+### 为什么不用 pi-ai 自己的 refresh 机制
+
+pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与 `ModelsStore`，而下层本来就在构造 pi-ai `Provider` 对象。把询问接到它们上面，意味着每问一次就要构造一个用完即弃的 provider 与集合，而那个 store 的全部目的——跨运行持久化 catalog——恰恰与「`settings.yaml` 拥有 catalog」的决定相抵触。而且它什么也换不来：**没有任何一个 pi-ai 内置 provider 实现了 `fetchModels`**，因此 HTTP 调用及其响应解析无论如何都是本包的代码。直接 fetch 才如实说出正在发生的事。路由已存的凭据由本插件自己那套逐请求解析器取出，且只在真正要联网的那条分支上进行，因此 catalog 路由作答时既不触碰凭据，也不会因为一把这次询问根本用不上的密钥而失败。
+
+## Alternatives considered
+
+**以提供方路由为键。** 与其他每个 seam 操作对称，也能让请求省去端点。但催生该功能的场景——新增提供方——没有路由，于是这个操作只对已配置好的提供方可用，而它们恰恰最不需要它。
+
+**把能力挂在 `LlmAdapter` 上。** 适配器要经由路由注册才能抵达，因此问题相同；而且这会让一个适配器实例去回答它并不服务的端点的问题。
+
+**让 host 读已存 profile，而不是接受草稿。** 对已配置好的提供方来说，不会有 secret 跨越协议层。但这样一来新增提供方就必须先保存一份不可用的配置，而端点已改却尚未保存的表单会静默地去询问旧地址。接受草稿让用户看见的与被询问的保持一致——凭据是唯一的例外，因为它是界面从不被展示、因而永远无法放进草稿的那个字段。
+
+**询问 pi-ai 的每一种协议。** Anthropic 的列表恰好与 OpenAI 共用同一层信封，而 Google 的不是。只支持容易的那几种会让覆盖范围变得任意；更糟的是，猜错的响应形状会与「该提供方没有模型」无法区分。一个明说自己无法被询问的协议，会把用户送去手工填写——那正是既定的回退路径。
+
+**用 `response.text()` 缓冲整个回复再判断长度。** 更简单，但上限会在字节已经到达之后才生效，而端点是用户随手填的任意 URL。
+
+## Consequences
+
+接入网关的人可以直接问它服务什么，而不必去翻它的文档；答案以候选形式抵达，由用户自己挑选，而不是被背着写进配置。seam 因此多了一个刻意保持很小的注册表：每个 namespace 一份、不存储、除 fiber 外没有生命周期。
+
+代价是：协议层多了第三个承载 secret 的载荷，配置面的只写接口从两个方法变成三个。发现能力按协议而非按提供方划分——一个 Anthropic 兼容网关即便其列表能被解析，也仍须手工填写。而且由于没有任何环节会重跑该询问，模型列表的新鲜度依旧只到最近一次编辑为止；这与下层刻意做出的取舍是同一个。
+
+## Testing
+
+`packages/llm/llm/tests/topology.spec.ts` 覆盖注册表：每个 namespace 一份、随 fiber dispose、丢弃重复与不可用 id 且不凭空补容量的归一化，以及 `NO_DISCOVERY`/`INVALID_DISCOVERY` 两种拒绝。`packages/llm/llm-pi-ai/tests/discovery.spec.ts` 针对本地 HTTP 服务器驱动探测——含与不含公布容量的列表、被保留的部署路径、无凭据、草稿没带密钥时已配置路由自行取用凭据且键入的密钥压过它、catalog 路由完全不解析凭据即作答、被丢弃的行、401/403 与服务器故障之别、非列表与非 JSON 响应、不可达端点、调用方取消、不支持的协议，以及尺寸上限的「声明长度」与「流式」两种形态。`packages/host/apiproxy/tests/api-proxy-config.spec.ts` 在真实 proxy 上覆盖该 RPC：草稿完整抵达其 namespace、缺席字段保持缺席、没有 namespace 或凭据被写入，以及失败以 `model-discovery-failed` 呈现且序列化后的错误里不含凭据。

.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md
+2026-08-06-web-markdown-incremental-ast-renderer.md: 3599bfcc78dc4eefe5e82f461a469bdba15f3aae
+2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 2e00977da58ef29a77c45abcecf0f3bb62737929

.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md

@@ -0,0 +1,33 @@
+# Agent Note: Incremental streaming markdown through a direct mdast renderer
+
+Status: implemented
+
+English | [中文](2026-08-06-web-markdown-incremental-ast-renderer.zh.md)
+
+## Problem
+
+`MarkdownText` re-parsed the whole accumulated reply on every streaming publish: react-markdown's string-only API builds a fresh unified processor per render and runs micromark → mdast → hast → React over the full text, so per-chunk main-thread work grew linearly with the reply and the stream's cumulative cost grew quadratically. The existing mitigations (frame batching, the isolated streaming tail, the plain fence arm) bounded how often and how widely that work ran, never how much text each run re-parsed. Fixing it needs AST-level input — freezing settled blocks and re-parsing only the source tail — which the string-only wrapper structurally cannot express.
+
+## Decision
+
+`MarkdownText` renders mdast directly and parses incrementally while streaming:
+
+- **Grammars** ([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)): `parseGfm` (streaming arm and `extractMarkdownPlainText`) and `parseGfmWithMath` (settled arm) call `mdast-util-from-markdown` with the same micromark extensions the replaced remark plugins wrapped, so block boundaries are identical everywhere. `mathCompatibility` (ex `remarkMathCompatibility`) now exports its micromark extension directly.
+- **Incremental parsing** ([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)): CommonMark block parsing is line-based, so appended text reshapes only the parse frontier. `IncrementalMarkdownParser` keeps the trailing two blocks unstable (the last block is the frontier; the second-to-last is safety margin), freezes everything before them, and re-parses only the source tail from the last frozen block's `position.end.offset` — the parser's own offsets, no bespoke source scanning. Each source region parses O(1) times per stream instead of once per chunk; a single giant block (an unclosed fence) degrades to the old full-reparse cost and no worse. Non-append input resets the state under a bumped generation.
+- **Rendering** ([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx), [katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)): one switch over mdast node types replaces remark-rehype + react-markdown, reproducing the replaced pipeline's DOM byte-for-byte — table alignment as `text-align` styles, tight-list paragraph unwrapping, task-list classes and checkbox spacing, the footnote section (whose in-page anchors the protocol allowlist already reduced to plain text), literal raw HTML, the separator newlines that surface next to literal HTML text, and rehype-katex's three-arm error chain with KaTeX HTML mapped to React through the browser's own `DOMParser` (no wrapper element, so first/last-child margin rules still reach `.katex-display`; React 18 puts the `.katex-mathml` subtree in the HTML namespace exactly as the replaced pipeline did — a pre-existing limitation outside this parity contract, invisible to the visual `.katex-html` arm). Frozen blocks cache their React elements and keep source-offset keys, so crossing the freeze boundary reconciles instead of remounting; `MarkdownText` is memoized.
+
+The DOM is pinned by `tests/fixtures/markdown-dom`: fixtures recorded from the react-markdown implementation before the swap, which the new renderer must reproduce under a whitespace-normalizing serializer. A fixture diff is a user-visible markdown style change to review, never to re-record for a refactor. `tests/markdown-incremental.spec.tsx` holds the equivalence property — at every appended prefix, chunked at 1/3/7/16 bytes, the live component's DOM equals a fresh mount's — plus freeze-boundary DOM-node identity and reset behavior.
+
+This reverses the [assistant-markdown note](../feature/2026-07-23-web-assistant-markdown.md)'s rejected alternative ("maintain a custom React walker"): the incremental requirement is new evidence, the walker's security-sensitive branches (URL allowlist, image policy, inert HTML) were already product-owned functions, and the dependency no longer deleted owned code — it blocked the architecture. That note's untrusted-output policy and renderer selection are unchanged.
+
+## Alternatives considered
+
+**Keep react-markdown and split the source into per-segment `<ReactMarkdown>` instances.** Zero renderer ownership, but each frame parses the tail twice (boundary detection + render), settled math still re-parses everything, hast construction and the per-render processor remain, and blocks remount when crossing the freeze boundary because element trees cannot be cached across instances.
+
+**Render cached mdast through `mdast-util-to-hast` + `hast-util-to-jsx-runtime`.** Keeps upstream's node mappings for free, but retains the hast intermediate per frame and two new direct dependencies for a pipeline whose mapping surface is small, closed, and now pinned by fixtures.
+
+**Parse KaTeX output with `hast-util-from-html-isomorphic` (as rehype-katex does).** Pulls a parse5-based HTML parser into the bundle to parse trusted, vocabulary-constrained KaTeX output the browser's `DOMParser` (with the spec's SVG/MathML attribute adjustments) already parses identically.
+
+## Consequences
+
+Streaming per-chunk work now tracks the unstable tail instead of the whole reply, and react-markdown, remark-gfm, remark-math, rehype-katex, unified, and the hast chain left the browser bundle (`mdast-util-math` and `micromark-util-sanitize-uri` became direct dependencies; both were already transitive). The package owns ~25 node mappings, their tests, and the KaTeX DOM conversion — priced against the fixture contract that freezes their output. Two behavioral deviations, both healed by the settled full parse at finalize: a reference-style link or footnote whose definition lands on the other side of a freeze boundary renders literally while streaming, and a footnote reference can flash back to literal text when its definition freezes while the referencing block is still unstable. This module and KaTeX conversion assume a browser DOM (`DOMParser`), which the client-only package already did.

.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md

@@ -0,0 +1,33 @@
+# Agent Note: 经由直接 mdast 渲染器的增量流式 Markdown
+
+Status: implemented
+
+[English](2026-08-06-web-markdown-incremental-ast-renderer.md) | 中文
+
+## Problem
+
+`MarkdownText` 在每次流式发布时都重新解析整个已累积的回复:react-markdown 的纯字符串 API 每次渲染都新建 unified processor,并对全文跑完 micromark → mdast → hast → React,因此每个 chunk 的主线程工作量随回复长度线性增长,整个流的累计成本随之二次增长。既有缓解手段(帧级合并、隔离的流式尾部、围栏 plain 臂)约束的是这份工作跑多频繁、波及多广,从未约束每次重新解析多少文本。修复它需要 AST 级输入——冻结已定型的块、只重新解析源文本尾部——这是纯字符串封装在结构上无法表达的。
+
+## Decision
+
+`MarkdownText` 直接渲染 mdast,并在流式期间增量解析:
+
+- **语法**([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)):`parseGfm`(流式臂与 `extractMarkdownPlainText`)和 `parseGfmWithMath`(定稿臂)以被替换的 remark 插件所包装的同一组 micromark 扩展调用 `mdast-util-from-markdown`,因此各处块边界完全一致。`mathCompatibility`(原 `remarkMathCompatibility`)现在直接导出其 micromark 扩展。
+- **增量解析**([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)):CommonMark 块解析按行推进,追加文本只会重塑解析前沿。`IncrementalMarkdownParser` 保留末尾两个块不稳定(最后一块是前沿;倒数第二块是安全裕量),冻结其前的所有块,只从最后一个冻结块的 `position.end.offset` 起重新解析源尾部——用的是解析器自己的偏移量,没有任何自制源扫描。每个源区间在整个流中解析 O(1) 次而非每 chunk 一次;单个巨型块(未闭合围栏)退化为旧的全量重解析成本,不会更差。非追加输入在递增的 generation 下重置状态。
+- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性契约范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
+
+DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
+
+这推翻了[助手 Markdown Note](../feature/2026-07-23-web-assistant-markdown.md) 中被否决的备选("维护一个自定义 React walker"):增量需求是当时不存在的新证据,walker 的安全敏感分支(URL 白名单、图片策略、惰性 HTML)本就是产品自有函数,而该依赖不再删减自有代码——它阻塞了架构。该 Note 的不可信输出策略与渲染器选型不变。
+
+## Alternatives considered
+
+**保留 react-markdown,把源文本切成逐段 `<ReactMarkdown>` 实例。** 渲染器零自有成本,但每帧对尾部解析两次(边界检测 + 渲染),定稿数学仍要全量重解析,hast 构建与逐渲染 processor 依旧存在,且块跨过冻结边界时会重挂载——元素树无法跨实例缓存。
+
+**用 `mdast-util-to-hast` + `hast-util-to-jsx-runtime` 渲染缓存的 mdast。** 白拿上游节点映射,但每帧保留 hast 中间层,并为一个映射面小、封闭、且已被 fixture 钉死的管线引入两个新直接依赖。
+
+**用 `hast-util-from-html-isomorphic` 解析 KaTeX 输出(rehype-katex 的做法)。** 为解析可信、词汇受限的 KaTeX 输出把基于 parse5 的 HTML 解析器拉进 bundle,而浏览器自带的 `DOMParser`(带规范的 SVG/MathML 属性调整)解析结果完全相同。
+
+## Consequences
+
+流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 契约对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。

.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
-2026-07-23-web-assistant-markdown.md: 8a8778351911bcb3448366c718aa124c4a89de58
-2026-07-23-web-assistant-markdown.zh.md: 2ac024e24ff95b4eb296112562c93f343b832187
+2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
+2026-07-23-web-assistant-markdown.zh.md: b47375db843ea1c81b913e3f7ac8cd1bbc278830

.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md

@@ -12,9 +12,9 @@ The Web conversation preserves assistant Markdown source through session events,
 
 `@deepseek-ai/dsh-client-ui-primitives` exports `MarkdownText` as the untrusted assistant-text renderer, and `ui-conversation` selects it only for assistant `text` blocks. Finalized history, the streaming tail, and interrupted partials already share `AssistantMarkdown`, so they receive the same renderer without changing events or snapshots. User and steering messages keep `MessageText` and remain literal.
 
-`MarkdownText` uses `react-markdown` with `remark-gfm` to build React elements from an AST. It covers CommonMark blocks plus GFM tables, task lists, strikethrough, and autolinks without raw-HTML parsing. Fenced code routes through the shared `CodeBlock`, which highlights registered grammars with the client's shiki singleton (`--shiki-*` tokens) and falls back to plain monospace otherwise. While a turn streams, fences stay on the plain arm so growing fences are not retokenized every chunk.
+`MarkdownText` parses with `mdast-util-from-markdown` plus the GFM micromark extensions and renders the mdast tree through the package's own renderer, parsing incrementally while a turn streams (the [incremental AST renderer note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) owns that mechanism and its DOM-parity contract). It covers CommonMark blocks plus GFM tables, task lists, strikethrough, and autolinks without raw-HTML parsing. A micromark attention extension reuses the CommonMark resolver while letting runs of at least two asterisks close after Unicode punctuation when followed immediately by CJK text. This exception covers punctuation-terminated strong emphasis in whitespace-free CJK prose during streaming and after settlement; single-asterisk emphasis, non-CJK adjacency, escaped source, code, and math retain upstream parsing. Fenced code routes through the shared `CodeBlock`, which highlights registered grammars with the client's shiki singleton (`--shiki-*` tokens) and falls back to plain monospace otherwise. While a turn streams, fences stay on the plain arm so growing fences are not retokenized every chunk.
 
-Visual spacing, tables, links, blockquotes, inline code, and code-block chrome follow deepsuite `@deepseek/md` (`markdown.css` / `code-block.css`) and the same `--dsw-alias-markdown-*`, `--dsw-font-markdown-*`, `--dsw-alias-border-l*`, and `--dsw-alias-label-*` tokens. Links use `--dsw-alias-state-business-primary` (deepsuite's sheet uses `--dsw-alias-brand-text`, which is blue only under newDesign; design-platform keeps brand-text near-black and is not retuned here). `CodeBlock` ships a language banner and a copy control (`复制` / `复制成功`). Finalized text renders KaTeX through `remark-math` and `rehype-katex`; `remarkMathCompatibility` maps `\(...\)`, `\[...\]`, and block-level same-line `$$...$$` to the same standard math AST nodes. This is a narrow parser compatibility layer, not a regex rewrite or malformed-model-output repair. Streaming stays literal until finalization so incomplete formulae do not flash errors. Citation pills, heading anchors, the thinking-small markdown variant, and custom □/☑ task markers remain out of scope; GFM task lists keep native checkboxes.
+Visual spacing, tables, links, blockquotes, inline code, and code-block chrome follow deepsuite `@deepseek/md` (`markdown.css` / `code-block.css`) and the same `--dsw-alias-markdown-*`, `--dsw-font-markdown-*`, `--dsw-alias-border-l*`, and `--dsw-alias-label-*` tokens. Links use `--dsw-alias-state-business-primary` (deepsuite's sheet uses `--dsw-alias-brand-text`, which is blue only under newDesign; design-platform keeps brand-text near-black and is not retuned here). When one inline-code token consists entirely of an absolute HTTP(S) URL, its code chrome contains the same keyboard-focusable safe external anchor as an ordinary link; port, path, and query text remain unchanged, while commands, partial URLs, other schemes, and fenced code stay inert. `CodeBlock` ships a language banner and a copy control (`复制` / `复制成功`). Finalized text renders KaTeX through the settled grammar's math extensions; `mathCompatibility` maps `\(...\)`, `\[...\]`, and block-level same-line `$$...$$` to the same standard math AST nodes. This is a narrow parser compatibility layer, not a regex rewrite or malformed-model-output repair. Streaming stays literal until finalization so incomplete formulae do not flash errors. Citation pills, heading anchors, the thinking-small markdown variant, and custom □/☑ task markers remain out of scope; GFM task lists keep native checkboxes.
 
 The dependency is explicit in `ui-primitives`; because that pure library is seeded by the Web shell, the parser and highlighter are part of the initial browser bundle.
 
@@ -26,7 +26,7 @@ Fenced code and GFM tables own horizontal overflow so long content cannot widen
 
 ## Alternatives considered
 
-**Promote the existing mdast and micromark development dependencies and maintain a custom React walker.** This avoids a new parser family but makes the product own every node mapping, GFM extension, and security-sensitive rendering branch. The dedicated React renderer keeps that traversal upstream while preserving an AST-to-React path.
+**Promote the existing mdast and micromark development dependencies and maintain a custom React walker.** This avoids a new parser family but makes the product own every node mapping, GFM extension, and security-sensitive rendering branch. The dedicated React renderer keeps that traversal upstream while preserving an AST-to-React path. *Later reversed on new evidence — incremental streaming parsing needs AST-level input the string-only wrapper cannot provide; the [incremental AST renderer note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) owns that decision.*
 
 **Replace `MessageText` with Markdown rendering.** This formats user prompts and steering as a side effect. Those authored surfaces remain literal until the product chooses that behavior explicitly.
 
@@ -36,6 +36,10 @@ Fenced code and GFM tables own horizontal overflow so long content cannot widen
 
 **Port deepsuite Prism `highlight.css` and the mdast pipeline.** Appearance parity is owned by CSS Modules and shared `--dsw-*` tokens; highlighting stays on the existing shiki allowlist so the client does not take a second highlighter or Prism class contract.
 
+**Preprocess Markdown source or repair text nodes after parsing for CJK punctuation boundaries.** A source rewrite must reproduce escape, code, math, and delimiter rules before the parser owns those distinctions, while a text-node repair has already lost some source intent and cannot compose with parsed inline nodes. Extending attention at the tokenizer boundary preserves the upstream resolver and limits the divergence to delimiter eligibility.
+
+**Require the model to emit standard links and leave URL-shaped inline code inert.** Output guidance cannot make persisted or third-party model replies uniform, and inline code is a common way to distinguish a literal endpoint. Recognizing only a complete absolute HTTP(S) value at the rendered inline-code boundary preserves code semantics while applying the existing untrusted-link policy.
+
 ## Consequences
 
-Assistant replies render semantic Markdown consistently during streaming and replay, while tool cards, reasoning rows, interactions, user bubbles, and the host protocol remain unchanged. Streaming reparses the current text after each accumulated update; incomplete Markdown can temporarily change structure, but the isolated tail bounds React invalidation and the final event does not switch renderers. Code fences share one chrome and copy path with tool and details surfaces. The initial Web shell includes the Markdown parser, GFM runtime, KaTeX, and shiki allowlist; citation, anchor, and thinking-small surfaces remain deferred.
+Assistant replies render semantic Markdown consistently during streaming and replay, while tool cards, reasoning rows, interactions, user bubbles, and the host protocol remain unchanged. Streaming reparses only the unstable tail after each accumulated update; incomplete Markdown can temporarily change the tail's structure, but the isolated tail bounds React invalidation and the final event does not switch renderers. URL-shaped inline code becomes navigable without changing its visible literal, while unsafe schemes and mixed code remain non-interactive. Code fences share one chrome and copy path with tool and details surfaces. The initial Web shell includes the Markdown parser, GFM runtime, KaTeX, and shiki allowlist; citation, anchor, and thinking-small surfaces remain deferred.

.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md

@@ -12,9 +12,9 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
 
 `@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
 
-`MarkdownText` 使用 `react-markdown` 与 `remark-gfm`，从 AST 构建 React 元素。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
+`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性契约）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
 
-视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过 `remark-math` 和 `rehype-katex` 渲染 KaTeX；`remarkMathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
+视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。当单个行内代码 token 完全由绝对 HTTP(S) URL 构成时，其代码外框会包含一个与普通链接相同、可通过键盘聚焦的安全外链锚点；端口、路径与查询文本保持不变，而命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过定稿语法的数学扩展渲染 KaTeX；`mathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
 
 该依赖在 `ui-primitives` 中显式声明；由于这一纯库由 Web shell 预置，解析器与高亮器会成为初始浏览器 bundle 的一部分。
 
@@ -26,7 +26,7 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 ## 考虑过的替代方案
 
-**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。
+**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要纯字符串封装无法提供的 AST 级输入；该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有。*
 
 **将 `MessageText` 替换为 Markdown 渲染。**这会产生格式化用户提示词与 steering 的副作用。在产品明确选择此行为之前，这两类输入内容仍按字面渲染。
 
@@ -36,6 +36,10 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 **移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。
 
+**为处理 CJK 标点边界而预处理 Markdown 源文本，或在解析后修复文本节点。**源文本重写必须在解析器掌握这些区别之前复现转义、代码、数学公式与定界符规则；文本节点修复则已经丢失部分源文本意图，也无法与已解析的行内节点组合。在分词器边界扩展 attention 可保留上游 resolver，并将差异限制在定界符的适用条件上。
+
+**要求模型输出标准链接，并让 URL 形态的行内代码保持不可交互。**输出指引无法统一已持久化回复与第三方模型回复，而行内代码是将端点标记为字面值的常见方式。仅在行内代码的渲染边界识别完整的绝对 HTTP(S) 值，可在应用现有不受信任链接策略的同时保留代码语义。
+
 ## 后果
 
-assistant 回复在流式输出与回放期间都会一致地渲染为语义化 Markdown，而工具卡片、推理行、交互、用户气泡和宿主协议保持不变。每次累积更新后，流式输出都会重新解析当前文本；未完成的 Markdown 可能暂时改变结构，但独立的尾部会限定 React 失效范围，最终事件也不会切换渲染器。代码围栏与工具及详情表层共用同一外框与复制路径。初始 Web shell 包含 Markdown 解析器、GFM 运行时、KaTeX 与 shiki 允许列表；citation、anchor 和 thinking-small 表层仍暂缓。
+assistant 回复在流式输出与回放期间都会一致地渲染为语义化 Markdown，而工具卡片、推理行、交互、用户气泡和宿主协议保持不变。每次累积更新后，流式输出只重新解析不稳定的尾部；未完成的 Markdown 可能暂时改变尾部结构，但独立的尾部会限定 React 失效范围，最终事件也不会切换渲染器。URL 形态的行内代码会在不改变其可见字面文本的情况下变得可导航，而采用不安全 scheme 或混有其他内容的代码仍不可交互。代码围栏与工具及详情表层共用同一外框与复制路径。初始 Web shell 包含 Markdown 解析器、GFM 运行时、KaTeX 与 shiki 允许列表；citation、anchor 和 thinking-small 表层仍暂缓。

.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.md
+2026-08-05-web-preview-product-badge.md: c20dedf8caa497d17a577cf46261c6a24c09a1ce
+2026-08-05-web-preview-product-badge.zh.md: c428dabf2a9a2ece2f90b0c3a527835a494c7cb7

.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.md

@@ -0,0 +1,33 @@
+# Agent Note: Web preview product badge
+
+Status: implemented
+
+English | [中文](2026-08-05-web-preview-product-badge.zh.md)
+
+## Problem
+
+The Web empty state does not identify the product as a preview. Users can enter the main session surface without seeing that the product is pre-release, while a deployment setting would misrepresent a product-wide lifecycle decision as an operator choice.
+
+## Decision
+
+The empty hero always renders a localized `Preview` / `预览版` badge beneath the headline. It has no configuration switch: preview status is one product identity shared by every deployment, not a deployment-varying tunable.
+
+The badge keeps the business-tertiary background so both themes retain the product-blue context, and uses the theme's primary label token for text. That pairing gives ordinary 12px text sufficient contrast in both light and dark themes; the business-primary foreground is reserved for larger or non-text accents because it does not reach the required contrast on this background.
+
+The badge leaves the product when the first tagged release removes the repository's pre-release stance, or when the owning product decision declares the preview phase complete. That change removes the badge and its locale key together rather than adding a runtime toggle.
+
+## Alternatives considered
+
+**Make preview status configurable.** Rejected because two deployments of the same pre-release product must not present different lifecycle identities, and a configuration field would turn product release state into an unsupported operator choice.
+
+**Use business-primary text on the business-tertiary background.** Rejected because the resulting light- and dark-theme contrast is below the 4.5:1 requirement for the badge's 12px text.
+
+**Hide the badge from the accessibility tree.** Rejected because preview status is product information rather than decoration; the accessible headline therefore includes the badge text.
+
+## Consequences
+
+Every new session exposes the same localized preview identity in visual and accessibility output. Removing preview status is an explicit product-release edit, and the badge favors readable neutral text over an all-blue treatment while retaining the business-tinted background.
+
+## Testing
+
+The conversation component test covers both localized badge values, and the Web lifecycle snapshots pin the English badge in the assembled empty hero.

.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md

@@ -0,0 +1,33 @@
+# Agent Note：Web 预览版产品徽标
+
+状态：已实现
+
+[English](2026-08-05-web-preview-product-badge.md) | 中文
+
+## 问题
+
+Web 空状态没有标明产品处于预览版阶段。用户可以在未看到产品尚未正式发布的情况下进入主会话界面；若改用部署设置，则会把面向整个产品的生命周期决策误表述为操作者的选择。
+
+## 决策
+
+空状态主视觉区始终在标题下方渲染本地化的 `Preview` / `预览版` 徽标。它没有配置开关：预览状态是所有部署共同的一项产品身份，而不是随部署变化的可调参数。
+
+徽标沿用 business-tertiary 背景，使两套主题都保留产品蓝的视觉语境；文字则使用主题的 primary label token。这一组合让普通 12px 文字在浅色与暗色主题下都有足够的对比度。business-primary 前景色仅留给较大字号文本或非文本强调元素，因为它在该背景上达不到要求的对比度。
+
+首个 tagged release 取消仓库的预发布立场时，或归属产品方明确决定预览阶段结束时，产品会移除该徽标。这一改动会同时移除徽标及其 locale key，而不是增加运行时开关。
+
+## 曾考虑的替代方案
+
+**让预览状态可配置。** 不予采纳：同一个预发布产品的两套部署不得展示不同的生命周期身份，配置字段还会把产品发布状态变成一项不受支持的操作者选择。
+
+**在 business-tertiary 背景上使用 business-primary 文字。** 不予采纳：由此产生的浅色与暗色主题对比度低于徽标 12px 文字所要求的 4.5:1。
+
+**在无障碍树中隐藏徽标。** 不予采纳：预览状态是产品信息而非装饰，因此无障碍标题会包含徽标文字。
+
+## 后果
+
+每个新会话都会在视觉与无障碍输出中呈现相同的本地化预览版身份。移除预览状态是一项显式的产品发布改动；徽标保留业务蓝色调背景，同时采用可读的中性色文字，而不是全蓝色处理方案。
+
+## 测试
+
+会话组件测试覆盖两个本地化徽标值，Web 生命周期快照则固定组装后空状态主视觉区中的英文徽标。

THIRD_PARTY_NOTICES.md

@@ -47,6 +47,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`@shikijs/langs`](https://github.com/shikijs/shiki) | MIT |
 | [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) | MIT |
 | [`@tanstack/react-virtual`](https://github.com/TanStack/virtual) | MIT |
+| [`@types/mdast`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@vscode/ripgrep`](https://github.com/microsoft/vscode-ripgrep) | MIT |
 | [`anser`](https://github.com/IonicaBizau/anser) | MIT |
 | [`chokidar`](https://github.com/paulmillr/chokidar) | MIT |
@@ -63,10 +64,14 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`koffi`](https://github.com/Koromix/koffi) | MIT |
 | [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) | MIT |
 | [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm) | MIT |
+| [`mdast-util-math`](https://github.com/syntax-tree/mdast-util-math) | MIT |
+| [`micromark-core-commonmark`](https://github.com/micromark/micromark/tree/main/packages/micromark-core-commonmark) | MIT |
 | [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm) | MIT |
 | [`micromark-extension-math`](https://github.com/micromark/micromark-extension-math) | MIT |
 | [`micromark-factory-space`](https://github.com/micromark/micromark/tree/main/packages/micromark-factory-space) | MIT |
 | [`micromark-util-character`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-character) | MIT |
+| [`micromark-util-classify-character`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-classify-character) | MIT |
+| [`micromark-util-sanitize-uri`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri) | MIT |
 | [`micromark-util-symbol`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-symbol) | MIT |
 | [`micromark-util-types`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-types) | MIT |
 | [`node-addon-require-builtin`](https://www.npmjs.com/package/node-addon-require-builtin) | MIT |
@@ -75,10 +80,6 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`pnpm`](https://github.com/pnpm/pnpm) | MIT |
 | [`react`](https://github.com/facebook/react) | MIT |
 | [`react-dom`](https://github.com/facebook/react) | MIT |
-| [`react-markdown`](https://github.com/remarkjs/react-markdown) | MIT |
-| [`rehype-katex`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex) | MIT |
-| [`remark-gfm`](https://github.com/remarkjs/remark-gfm) | MIT |
-| [`remark-math`](https://github.com/remarkjs/remark-math/tree/main/packages/remark-math) | MIT |
 | [`shiki`](https://github.com/shikijs/shiki) | MIT |
 | [`supports-color`](https://github.com/chalk/supports-color) | MIT |
 | [`tsx`](https://github.com/privatenumber/tsx) | MIT |
@@ -109,7 +110,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/babel__code-frame`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/js-yaml`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/jsdom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
-| [`@types/mdast`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |

apps/web/tests/markdown-cjk-strong.e2e.ts

@@ -0,0 +1,132 @@
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
+import {
+  assertFixtureInventory,
+  captureStableAria,
+  compareOrRefreshGolden,
+  launchWebScaffold,
+  seedSession,
+  watchConsole,
+  webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/markdown-cjk-strong', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/markdown-cjk-strong/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'markdown-cjk-strong-web-e2e'
+const DONE = 'CJK_STRONG_DONE'
+const CASES = [
+  ['**注意：**内容', '注意：', '注意：内容'],
+  ['**Notice:**内容', 'Notice:', 'Notice:内容'],
+  ['**事件中间件（waterfall）**实现', '事件中间件（waterfall）', '事件中间件（waterfall）实现'],
+  ['**事件中间件(waterfall)**实现', '事件中间件(waterfall)', '事件中间件(waterfall)实现'],
+  ['**句号。**后续', '句号。', '句号。后续'],
+  ['**Period.**后续', 'Period.', 'Period.后续'],
+  ['**提醒！**继续', '提醒！', '提醒！继续'],
+  ['**Warning!**继续', 'Warning!', 'Warning!继续'],
+] as const
+
+/** Build one settled assistant reply covering CJK-adjacent strong punctuation boundaries. */
+function markdownFixture(): string {
+  const session = Session.create(SessionId('markdown-cjk-strong-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
+  session.append('turn/start', { turn: 1 })
+  const user = session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text: 'Render adjacent CJK strong emphasis.' }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+  session.append('session/title', {
+    title: 'CJK strong emphasis',
+    messageSeqs: [user.seq],
+    source: { kind: 'fallback' },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
+  session.append('assistant/message', {
+    turn: 1,
+    step: 1,
+    message: createMessage({
+      role: 'assistant',
+      content: [{
+        type: 'text',
+        text: [
+          '## CJK strong emphasis',
+          '',
+          ...CASES.flatMap(([markdown]) => [markdown, '']),
+          DONE,
+        ].join('\n'),
+      }],
+      source: { kind: 'model', provider: 'fixture', model: 'fixture' },
+    }),
+  }, { surfaceOp: 'append' })
+  session.append('step/end', { turn: 1, step: 1 })
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+  return [
+    JSON.stringify({
+      type: 'session',
+      version: SESSION_FORMAT_VERSION,
+      id: '{{sessionId}}',
+      createdAt: 0,
+      cwd: '{{cwd}}',
+    }),
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
+    '',
+  ].join('\n')
+}
+
+describe('web e2e: CJK-adjacent Markdown strong emphasis', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, markdownFixture(), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('renders punctuation-terminated strong spans before adjacent CJK text', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-cjk-strong'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+
+    const strong = page.locator('[class*="markdown"] strong')
+    await expect.poll(() => strong.count(), { timeout: 10_000 }).toBe(CASES.length)
+    expect(await strong.allTextContents()).toEqual(CASES.map(([, expected]) => expected))
+    for (const [, , paragraph] of CASES) {
+      expect(await page.getByText(paragraph, { exact: true }).count()).toBe(1)
+    }
+
+    const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
+      .split(SEED_ID).join('{{seededId}}')
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  }, 60_000)
+})

apps/web/tests/markdown-images.e2e.ts

@@ -83,6 +83,7 @@ async function stopServer(server: Server): Promise<void> {
 /** Build one closed, invariant-checked session fixture with remote and local image Markdown. */
 function markdownImageFixture(remoteUrl: string): string {
   const session = Session.create(SessionId('markdown-image-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
   session.append('turn/start', { turn: 1 })
   const user = session.append('user/message', createUserMessage({
     content: [{ type: 'text', text: 'Show the Markdown image policy.' }],
@@ -126,7 +127,14 @@ function markdownImageFixture(remoteUrl: string): string {
   }
   return [
     JSON.stringify(header),
-    ...session.events.map(event => JSON.stringify(event)),
+    // Spaced event times, exactly as the sibling markdown fixtures pin them:
+    // the stats line renders its LLM segment only while the step's measured
+    // milliseconds exceed zero, so a fixture that leaves the times unset lets
+    // the replay's own speed decide whether the golden matches.
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
     '',
   ].join('\n')
 }

apps/web/tests/markdown-inline-code-links.e2e.ts

@@ -0,0 +1,142 @@
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
+import {
+  assertFixtureInventory,
+  captureStableAria,
+  compareOrRefreshGolden,
+  launchWebScaffold,
+  seedSession,
+  watchConsole,
+  webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/markdown-inline-code-links', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/markdown-inline-code-links/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'markdown-inline-code-links-web-e2e'
+const DONE = 'INLINE_CODE_LINK_DONE'
+
+/** Build a settled assistant reply with linkable URL code and inert code controls. */
+function markdownFixture(linkUrl: string): string {
+  const session = Session.create(SessionId('markdown-inline-code-links-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
+  session.append('turn/start', { turn: 1 })
+  const user = session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text: 'Show the local preview URL.' }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+  session.append('session/title', {
+    title: 'Inline code links',
+    messageSeqs: [user.seq],
+    source: { kind: 'fallback' },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
+  session.append('assistant/message', {
+    turn: 1,
+    step: 1,
+    message: createMessage({
+      role: 'assistant',
+      content: [{
+        type: 'text',
+        text: [
+          '## Inline code links',
+          '',
+          `Preview: \`${linkUrl}\``,
+          '',
+          `Standard: [Open preview](${linkUrl})`,
+          '',
+          `Command: \`curl ${linkUrl}\``,
+          '',
+          'Unsafe: `javascript:alert(1)`',
+          '',
+          DONE,
+        ].join('\n'),
+      }],
+      source: { kind: 'model', provider: 'fixture', model: 'fixture' },
+    }),
+  }, { surfaceOp: 'append' })
+  session.append('step/end', { turn: 1, step: 1 })
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+  return [
+    JSON.stringify({
+      type: 'session',
+      version: SESSION_FORMAT_VERSION,
+      id: '{{sessionId}}',
+      createdAt: 0,
+      cwd: '{{cwd}}',
+    }),
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
+    '',
+  ].join('\n')
+}
+
+describe('web e2e: Markdown inline-code links', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let linkUrl: string
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    linkUrl = new URL('/?demo=1', scaffold.baseUrl).toString()
+    await seedSession(scaffold, markdownFixture(linkUrl), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('opens a complete HTTP URL from inline code and leaves other code inert', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-inline-code-links'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+
+    const inlineCodeLink = page.locator('[class*="markdown"] code a')
+    await expect.poll(() => inlineCodeLink.count(), { timeout: 10_000 }).toBe(1)
+    expect(await inlineCodeLink.getAttribute('href')).toBe(linkUrl)
+    expect(await inlineCodeLink.getAttribute('target')).toBe('_blank')
+    expect(await inlineCodeLink.getAttribute('rel')).toBe('noopener noreferrer')
+    await inlineCodeLink.focus()
+    expect(await inlineCodeLink.evaluate(element => document.activeElement === element)).toBe(true)
+
+    const popupPromise = page.waitForEvent('popup')
+    await inlineCodeLink.click()
+    const popup = await popupPromise
+    await popup.waitForURL(linkUrl, { timeout: 15_000 })
+    expect(popup.url()).toBe(linkUrl)
+    await popup.close()
+
+    expect(await page.getByText(`curl ${linkUrl}`, { exact: true }).locator('a').count()).toBe(0)
+    expect(await page.getByText('javascript:alert(1)', { exact: true }).locator('a').count()).toBe(0)
+    const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
+      .split(SEED_ID).join('{{seededId}}')
+      .split(linkUrl).join('{{linkUrl}}')
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  }, 60_000)
+})

apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md

@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Let's start building
+- text: Let's start building Preview
 - button "Choose workspace":
   - img
   - text: workspace

apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md

@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Let's start building
+- text: Let's start building Preview
 - button "Choose workspace":
   - img
   - text: workspace

apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md

@@ -0,0 +1,52 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "CJK strong emphasis" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Render adjacent CJK strong emphasis. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation" [disabled]:
+  - img
+- text: Available only on the last message of a completed turn
+- heading "CJK strong emphasis" [level=2]
+- paragraph:
+  - strong: 注意：
+  - text: 内容
+- paragraph:
+  - strong: "Notice:"
+  - text: 内容
+- paragraph:
+  - strong: 事件中间件（waterfall）
+  - text: 实现
+- paragraph:
+  - strong: 事件中间件(waterfall)
+  - text: 实现
+- paragraph:
+  - strong: 句号。
+  - text: 后续
+- paragraph:
+  - strong: Period.
+  - text: 后续
+- paragraph:
+  - strong: 提醒！
+  - text: 继续
+- paragraph:
+  - strong: Warning!
+  - text: 继续
+- paragraph: CJK_STRONG_DONE
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{clock}} Ran for {{duration}}
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model":
+  - text: Select model
+  - img
+- button "Send message" [disabled]
+- text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok

apps/web/tests/snapshots/markdown-images/ui.expected.md

@@ -28,4 +28,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps Input 0 tok · Output 0 tok
+- text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok

apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md

@@ -0,0 +1,43 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "Inline code links" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Show the local preview URL. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation" [disabled]:
+  - img
+- text: Available only on the last message of a completed turn
+- heading "Inline code links" [level=2]
+- paragraph:
+  - text: "Preview:"
+  - code:
+    - link "{{linkUrl}}":
+      - /url: {{linkUrl}}
+- paragraph:
+  - text: "Standard:"
+  - link "Open preview":
+    - /url: {{linkUrl}}
+- paragraph:
+  - text: "Command:"
+  - code: curl {{linkUrl}}
+- paragraph:
+  - text: "Unsafe:"
+  - code: javascript:alert(1)
+- paragraph: INLINE_CODE_LINK_DONE
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{clock}} Ran for {{duration}}
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model":
+  - text: Select model
+  - img
+- button "Send message" [disabled]
+- text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok

apps/web/tests/snapshots/models-settings/configured.expected.md

@@ -21,3 +21,6 @@
   - button "添加提供方":
     - img
     - text: 添加提供方
+  - button "添加自定义提供方":
+    - img
+    - text: 添加自定义提供方

apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md

@@ -69,3 +69,6 @@
   - button "添加提供方":
     - img
     - text: 添加提供方
+  - button "添加自定义提供方":
+    - img
+    - text: 添加自定义提供方

apps/web/tsconfig.json

@@ -52,6 +52,8 @@
     "tests/message-actions.e2e.ts",
     "tests/markdown-images.e2e.ts",
     "tests/math-rendering.e2e.ts",
+    "tests/markdown-cjk-strong.e2e.ts",
+    "tests/markdown-inline-code-links.e2e.ts",
     "tests/queue-actions.e2e.ts",
     "tests/skill-invocation-policy.e2e.ts",
     "tests/permission-policy-context.e2e.ts",

docs/config-catalog.md

@@ -704,8 +704,34 @@ export interface PiAiProviderProfile {
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
   apiKeyEnv?: string
-  /** Override the selected catalog model's endpoint without changing its protocol metadata. */
+  /** Name shown by configuration surfaces; defaults to the route key. */
+  displayName?: string
+  /**
+   * Wire protocol every model on this route speaks. Omission keeps each
+   * installed catalog model's own protocol, which is why a catalog route needs
+   * no protocol at all; a route the catalog does not ship must name one.
+   */
+  api?: string
+  /** Endpoint for this route's models; defaults to the installed catalog's endpoint. */
   baseURL?: string
+  /**
+   * This route's model catalog. Omission serves the installed catalog for the
+   * route unchanged; an explicit list replaces it, each entry defaulting its
+   * unset fields from the installed model of the same id.
+   */
+  models?: PiAiModelProfile[]
+  /**
+   * Context capacity for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 262,144). A guess by construction, so
+   * a deployment whose gateway serves smaller models corrects it here.
+   */
+  defaultContextWindow?: number
+  /**
+   * Output capability for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 32,768). This sizes the model; it
+   * never becomes a per-request cap on its own.
+   */
+  defaultMaxTokens?: number
   /** Provider request headers; Harness attribution wins reserved names. */
   headers?: Record<string, string>
   /** Provider-neutral pi-ai reasoning level. */
@@ -725,11 +751,28 @@ export interface PiAiProviderProfile {
   /** Provider-owned model-request retry policy; omission uses normal defaults. */
   retryPolicy?: RetryPolicyConfig
 }
+
+/** One configured model entry: an id plus the catalog fields it overrides. */
+export interface PiAiModelProfile {
+  /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
+  id: string
+  /** Display name for selectors; defaults to the catalog name, then the id. */
+  name?: string
+  /** Maximum combined request and response context in tokens. */
+  contextWindow?: number
+  /**
+   * Maximum output tokens. Configuring one also makes it this model's
+   * per-request default; a value inherited from the installed catalog, or the
+   * route's fallback, is the model's capability and never becomes a request
+   * default on its own.
+   */
+  maxTokens?: number
+}
 ```
 
 Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)
 
-Source: [`packages/llm/llm-pi-ai/src/config.ts:62`](../packages/llm/llm-pi-ai/src/config.ts)
+Source: [`packages/llm/llm-pi-ai/src/config.ts:122`](../packages/llm/llm-pi-ai/src/config.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 

docs/cordis-catalog/events.md

@@ -486,7 +486,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:69`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
 
 ### `llm/stream` — waterfall
 
@@ -510,7 +510,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:58`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
 
 ## `session/*`
 
@@ -624,7 +624,7 @@ One registered namespace's RAW user section changed, whether or not the resolved
 
 Types: [SettingsNamespace](../core-data-structures/settings.md)
 
-Source: [`packages/settings/settings/src/index.ts:150`](../../packages/settings/settings/src/index.ts)
+Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
 
 ### `settings/updated` — emit
 
@@ -651,7 +651,7 @@ Committed change to one registered namespace's resolved value. Emitted after the
 
 Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md)
 
-Source: [`packages/settings/settings/src/index.ts:137`](../../packages/settings/settings/src/index.ts)
+Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
 
 ## `skills/*`
 

docs/cordis-catalog/services.md

@@ -844,9 +844,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns the disposer that withdraws all of them.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -854,6 +854,29 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () =
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -916,9 +939,9 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<Prepared
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:255`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 
@@ -1839,7 +1862,7 @@ async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevi
 
 Types: [SettingsDescribeOptions](../core-data-structures/settings.md) · [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsPathOp](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md)
 
-Source: [`packages/settings/settings/src/index.ts:365`](../../packages/settings/settings/src/index.ts)
+Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
 
 ## `ctx.skills` — `SkillService`
 

docs/core-data-structures/core.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/core.md
-core.md: 495651e1f3105afff15f68822568ff71c531da4f
-core.zh.md: c895601f39d350811ab1169533287d8f59dba703
+core.md: 6c9b778f2ec6a0b4e3ffdf7d69e5e4d34df0b4a9
+core.zh.md: 4912060cad1f3b9fce910ec8c24b8b50dafd6ed1

docs/core-data-structures/core.md

@@ -330,6 +330,55 @@ interface LlmModelInfo {
 }
 ```
 
+A provider a surface is still drafting has no route and no catalog, so interrogation is described separately: the request carries the draft the user is editing, and the reply is candidates a surface may adopt rather than a catalog it must serve.
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 Correctness-sensitive metadata is resolved separately from the advisory catalog and is owned by the adapter serving the exact route. Context capacity, adapter call defaults, and reasoning choices share one exact-model result so consumers do not repeat authoritative model resolution.
 
 ```ts type-equiv

docs/core-data-structures/core.zh.md

@@ -336,6 +336,55 @@ interface LlmModelInfo {
 }
 ```
 
+界面正在起草的提供方既没有路由也没有 catalog，因此询问被单独描述：请求携带用户正在编辑的草稿，回复是界面可以采纳的候选，而不是它必须服务的 catalog。
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 对正确性敏感的元数据与参考目录分开解析，并归服务该确切路由的适配器所有。上下文容量、适配器调用默认值和推理选项共用同一个确切模型结果，消费方因而无需重复执行权威模型解析。
 
 ```ts type-equiv

docs/core-data-structures/settings.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/settings.md
-settings.md: 1cabfae5d8dc72a9cd79341d250ee79820693872
-settings.zh.md: d63a1384646fa38199e7d65e9f0504f0440597be
+settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd
+settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53

docs/core-data-structures/settings.md

@@ -17,7 +17,7 @@ type SettingsNamespace = Branded<'SettingsNamespace'>
 
 ## Registration
 
-Registration binds a schemastery schema to a namespace on the calling plugin's fiber — disposing that fiber removes the namespace and its observers. The options carry the composition layer and the owner's effect timing.
+Registration binds a schemastery schema to a namespace on the calling plugin's fiber — disposing that fiber removes the namespace and its observers. The options carry the composition layer, the owner's effect timing, and an optional check for what the schema cannot express.
 
 ```ts type-equiv
 /** Registration options beyond the namespace schema. */
@@ -26,9 +26,31 @@ interface SettingsRegisterOptions<T> {
   base?: Partial<T>
   /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
   applies?: SettingsApplies
+  /**
+   * Reject a resolved section the owner could not act on, for constraints its
+   * schema cannot express — a cross-field requirement, or one field's validity
+   * depending on another's. Throwing here refuses the *write* that produced the
+   * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
+   * something that would silently disable the owner.
+   *
+   * Kept separate from the schema because the schema is also what a
+   * configuration surface renders and what an absent section resolves through;
+   * folding a cross-field check into it would change both.
+   *
+   * Once the owner is registered, a stored section that fails this keeps the
+   * namespace's last good value and warns, exactly as a schema failure does,
+   * so an externally edited document cannot strand a running owner. At
+   * registration there is no last good value yet, so a stored section that
+   * already fails rejects the registration itself — again exactly as a schema
+   * failure does.
+   * @param value - the resolved section, schema-valid by construction.
+   */
+  validate?: (value: T) => void
 }
 ```
 
+`validate` runs after the schema admits a value, so it sees defaults and the composition base exactly as the owner will. `dsh-llm-pi-ai` uses it to refuse a provider profile it could not serve at the write that produced it, rather than storing one that would disable every route in its namespace.
+
 `applies` is a UI hint, not a mechanism: a `restart` owner simply never watches, so its value is read once at construction and configuration surfaces can badge the pending change.
 
 ```ts type-equiv

docs/core-data-structures/settings.zh.md

@@ -17,7 +17,7 @@ type SettingsNamespace = Branded<'SettingsNamespace'>
 
 ## 注册
 
-注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose 该 fiber 即移除 namespace 及其观察者。options 携带组合层与 owner 的生效时机。
+注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose 该 fiber 即移除 namespace 及其观察者。options 携带组合层、owner 的生效时机，以及一个可选的、用于校验 schema 表达不了的约束的钩子。
 
 ```ts type-equiv
 /** Registration options beyond the namespace schema. */
@@ -26,9 +26,31 @@ interface SettingsRegisterOptions<T> {
   base?: Partial<T>
   /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
   applies?: SettingsApplies
+  /**
+   * Reject a resolved section the owner could not act on, for constraints its
+   * schema cannot express — a cross-field requirement, or one field's validity
+   * depending on another's. Throwing here refuses the *write* that produced the
+   * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
+   * something that would silently disable the owner.
+   *
+   * Kept separate from the schema because the schema is also what a
+   * configuration surface renders and what an absent section resolves through;
+   * folding a cross-field check into it would change both.
+   *
+   * Once the owner is registered, a stored section that fails this keeps the
+   * namespace's last good value and warns, exactly as a schema failure does,
+   * so an externally edited document cannot strand a running owner. At
+   * registration there is no last good value yet, so a stored section that
+   * already fails rejects the registration itself — again exactly as a schema
+   * failure does.
+   * @param value - the resolved section, schema-valid by construction.
+   */
+  validate?: (value: T) => void
 }
 ```
 
+`validate` 在 schema 接纳该值之后运行，因此它看到的默认值与组合 base 与 owner 将看到的完全一致。`dsh-llm-pi-ai` 用它在写入处拒绝自己无法服务的提供方 profile，而不是先存下来、再让该 namespace 下每条路由失效。
+
 `applies` 是 UI 提示而非机制：`restart` 的 owner 只是从不 watch，其值在构造期读取一次，配置界面可为待生效变更加标。
 
 ```ts type-equiv

docs/event-producer-consumer.md

@@ -28,14 +28,14 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:141`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:69`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:58`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
+| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:60`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:73`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:95`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:104`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
-| `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:150`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
-| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:137`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
+| `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
+| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |

packages/client/connection/src/client/api.ts

@@ -15,7 +15,7 @@ export type {
   ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
   GoalsApi, GoalRef,
   SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
-  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
+  CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,
   SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'

packages/client/connection/src/client/fixture.ts

@@ -2502,6 +2502,12 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         ],
       }),
       models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
+      // The fixture endpoint is imaginary, so the interrogation answers the
+      // catalog it already serves — enough for a surface to exercise adopting
+      // candidates without a reachable provider.
+      discoverModels: request => ok(request, {
+        models: fixtureModelGroups().flatMap(group => group.models.map(model => ({ id: model.id, name: model.name }))),
+      }),
     },
     respond(message: ClientResponse): Promise<RpcReceipt> {
       // Same routing discipline as the host: rpcId first, then the payload's
@@ -2619,6 +2625,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'credentials.unset': return this.api.credentials.unset(request)
       case 'llm.providers': return this.api.llm.providers(request)
       case 'llm.models': return this.api.llm.models(request)
+      case 'llm.discoverModels': return this.api.llm.discoverModels(request, signal)
     }
   }
 

packages/client/connection/src/client/index.ts

@@ -25,7 +25,7 @@ export type {
   IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,
   GoalsApi, GoalRef,
   SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
-  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
+  CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,
 } from './api.ts'
 export {
   RpcId,

packages/client/connection/src/index.ts

@@ -44,10 +44,15 @@ export const Config: z<ConnectionConfig> = z.object({
  * reconnaissance no anonymous caller should have. `trustedHosts` is a
  * DNS-rebinding fence, explicitly not authentication, so the whole
  * configuration plane stays loopback-same-origin until a real authentication
- * layer exists. The model catalog (`llm.providers`, `llm.models`) is
- * deliberately NOT here: it carries provider ids, display names, and model
- * lists — no endpoints, keys, or key state — and a LAN client's model picker
- * legitimately needs it.
+ * layer exists. `llm.discoverModels` belongs to that plane on both counts: it
+ * carries a draft credential, and it makes the HOST issue a GET to a URL the
+ * caller chose and reports back the status or the parsed body — an anonymous
+ * LAN caller would have a probe for whatever the host can reach and the
+ * browser cannot.
+ *
+ * The model catalog (`llm.providers`, `llm.models`) is deliberately NOT here:
+ * it carries provider ids, display names, and model lists — no endpoints,
+ * keys, or key state — and a LAN client's model picker legitimately needs it.
  */
 const PRIVILEGED_METHODS = new Set([
   'host.pickDirectory',
@@ -60,6 +65,7 @@ const PRIVILEGED_METHODS = new Set([
   'credentials.describe',
   'credentials.set',
   'credentials.unset',
+  'llm.discoverModels',
 ])
 
 /**

packages/client/connection/tests/fake-api.ts

@@ -197,6 +197,7 @@ export class FakeApiClient implements IApiClient {
   readonly llm: IApiClient['llm'] = {
     providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
     models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+    discoverModels: payload => this.record('llm.discoverModels', payload, Promise.resolve(ok({ models: [] }))),
   }
 
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */

packages/client/connection/tests/node-half.spec.ts

@@ -129,13 +129,15 @@ describe('connection node half', () => {
   it('pins privileged methods to loopback even for a declared trusted authority', async () => {
     const { routes, dispose } = await mounted({ trustedHosts: ['harness.example'] })
     // The privileged set: native dialogs plus the whole settings/credential
-    // configuration plane, reads included. The same declared authority reaches
+    // configuration plane, reads included, plus the one method that makes the
+    // host fetch a caller-chosen URL. The same declared authority reaches
     // ordinary reads (carrier-level 404 from the empty proxy proves the fence
     // passed), but each privileged method stays loopback-only and 403s.
     for (const method of [
       'host.pickDirectory', 'host.openPath',
       'settings.describe', 'settings.openDocument', 'settings.update', 'settings.replace', 'settings.mutate',
       'credentials.describe', 'credentials.set', 'credentials.unset',
+      'llm.discoverModels',
     ]) {
       const denied = fakeResponse()
       await routes[0]!.handler(
@@ -221,6 +223,9 @@ describe('connection node half over a real HTTP server', () => {
         'settings.describe', 'settings.openDocument', 'settings.update', 'settings.replace', 'settings.mutate',
         'credentials.describe', 'credentials.set', 'credentials.unset',
         'host.pickDirectory', 'host.openPath',
+        // Carries a draft credential and turns the host into a fetcher for a
+        // URL the caller picked: an anonymous LAN caller must not reach it.
+        'llm.discoverModels',
       ]) {
         expect([method, await call(port, method, 'harness.example')]).toEqual([method, 403])
       }

packages/client/runtime/tests/fake-api.ts

@@ -232,6 +232,7 @@ export class FakeApiClient implements IApiClient {
   readonly llm: IApiClient['llm'] = {
     providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
     models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+    discoverModels: payload => this.record('llm.discoverModels', payload, Promise.resolve(ok({ models: [] }))),
   }
 
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */

packages/client/ui-conversation/src/client/locales.ts

@@ -45,6 +45,7 @@ export const zh = {
   'access.confirm.cancel': '取消',
   'access.confirm.enable': '启用 Full access',
   'hero.headline': '开始构建吧',
+  'hero.preview': '预览版',
   'hero.chooseWorkspace': '选择工作区',
   'session.hierarchy': '会话层级',
   'details.title': '详情',
@@ -184,6 +185,7 @@ export const en = {
   'access.confirm.cancel': 'Cancel',
   'access.confirm.enable': 'Enable Full access',
   'hero.headline': 'Let\'s start building',
+  'hero.preview': 'Preview',
   'hero.chooseWorkspace': 'Choose workspace',
   'session.hierarchy': 'Session hierarchy',
   'details.title': 'Details',

packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx

@@ -119,7 +119,8 @@ export function HeroShell({ t, children }: HeroShellProps) {
         <div className={css.headline}>
           {/* figma 34:10412: fish 34×25 leading the headline, gap 10. */}
           <FishLogo size={34} className={css.fish} />
-          {t('hero.headline')}
+          <span className={css.headlineText}>{t('hero.headline')}</span>
+          <span className={css.previewBadge}>{t('hero.preview')}</span>
         </div>
         <div className={css.body}>
           {/* The resident composer (ConversationRoot wrapActiveBody seat; the

packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css

@@ -23,21 +23,44 @@
   overflow: visible;
 }
 
-/* figma 34:10411: fish + title, gap 10, centered; 26/32 wt500. */
+/* figma 34:10411: fish + title, gap 10, centered; 26/32 wt500. The preview
+   badge is a product addition outside that source and aligns to the title. */
 .headline {
-  display: flex;
+  display: grid;
+  grid-template-columns: 34px auto;
+  column-gap: 10px;
+  row-gap: 4px;
   align-items: center;
   justify-content: center;
-  gap: 10px;
   font-size: 26px;
   line-height: 32px;
   font-weight: 500;
   color: var(--dsw-alias-label-primary);
 }
 
+.headlineText {
+  grid-row: 1;
+  grid-column: 2;
+}
+
+.previewBadge {
+  grid-row: 2;
+  grid-column: 2;
+  justify-self: start;
+  padding: 0 4px;
+  border-radius: 4px;
+  background: var(--dsw-alias-state-business-tertiary);
+  color: var(--dsw-alias-label-primary);
+  font-size: 12px;
+  line-height: 18px;
+  font-weight: 500;
+  white-space: nowrap;
+}
+
 /* figma fish fill rides business blue. */
 .fish {
-  flex: none;
+  grid-row: 1;
+  grid-column: 1;
   color: var(--dsw-alias-state-business-primary);
 }
 

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -12,12 +12,14 @@ import type {
 import type { ConversationRootProps } from '../src/client/skeleton/ConversationRoot.tsx'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
 import { SessionInputShell } from '../src/client/input/facade.ts'
-import { zh } from '../src/client/locales.ts'
+import { en, zh } from '../src/client/locales.ts'
 import { ConversationRoot } from '../src/client/skeleton/ConversationRoot.tsx'
 import { ConversationSession } from '../src/client/skeleton/ConversationSession.tsx'
+import { HeroShell } from '../src/client/skeleton/EmptyHero.tsx'
 import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
 import type {
@@ -213,6 +215,14 @@ function mount(
   }
 }
 
+describe('Hero chrome', () => {
+  it('renders the English preview badge through the hero locale seat', () => {
+    const view = render(<HeroShell t={makeTranslate(en, commonEn)} />)
+    expect(view.getByText('Let\'s start building')).toBeTruthy()
+    expect(view.getByText('Preview')).toBeTruthy()
+  })
+})
+
 describe('ConversationRoot resident composer', () => {
   it('keeps composer text in the machine, mirrors to the chat store, and submits through the sink', () => {
     const b = mount(conversationSnapshot())
@@ -273,6 +283,7 @@ describe('ConversationRoot resident composer', () => {
     expect(host).not.toBeNull()
     expect(header?.getAttribute('aria-hidden')).toBe('true')
     expect(b.view.getByText('开始构建吧')).toBeTruthy()
+    expect(b.view.getByText('预览版')).toBeTruthy()
     expect(b.view.queryByTestId('view-chat')).toBeNull()
     // The same machine-backed textarea is live in the hero, and the
     // persistence mirror stays bound (ConversationSession mounts chrome-hidden

packages/client/ui-models/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
-README.md: c578ecfc9163245e8666cb6d2d327efdaccccf89
-README.zh.md: 40da5b52f681071cb5b833866270db7b37fb0957
+README.md: b55914197e472edec8a8b6d4d3e02036d1697728
+README.zh.md: ca93c3d5a2a85fffb22707f8389f1e979468e2ec

packages/client/ui-models/README.md

@@ -4,12 +4,20 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and the direct DeepSeek adapter's advisory model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and a localized confirmation dialog must complete before the page submits that destructive unset.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and the direct DeepSeek adapter's advisory model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and a localized confirmation dialog must complete before the page submits that destructive unset.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
 Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
+## Model list and endpoint interrogation
+
+A pi-ai profile's `models` list is edited on the card: one row per model showing its id and display name, with the context window and output cap behind a per-row disclosure and two label-free actions — expand and delete — on the right. An empty list means "serve this route's built-in catalog", so a row is only ever added deliberately; clearing a capacity drops it rather than storing a value the schema would reject, and the adapter's route-level fallbacks size whatever configuration leaves out — an empty capacity shows those fallbacks' magnitude as its placeholder, a hint rather than a mirror, since the field counts `K` as 1000 and a deployment may override them. A capacity that is not a positive integer is simply not stored.
+
+**Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
+
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts.
+
 ## Model Experience
 
 None, as the section renders a browser configuration UI; nothing here reaches a model request.
@@ -22,4 +30,6 @@ None; this package neither assembles nor sends a provider request.
 
 - **Only the API key and curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)). DeepSeek exposes `baseURL`, `reasoningEffort`, and model `id`/`name`/`contextWindow`/`maxTokens`; pi-ai exposes `baseURL` and `reasoning`. Retry policy, timeouts, DeepSeek model descriptions, and other advanced fields remain in `settings.yaml`; existing model fields the editor does not show are preserved. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name.
 - **Deleting a row leaves its stored key in `.env`** — removal unsets the settings profile but deliberately does not unset the derived credential; re-adding the provider finds the key already configured. An explicit key-removal control is deferred.
+- **Only pi-ai routes can be hand-declared** — the custom-provider card writes into `llm-pi-ai`, the one namespace whose profiles describe a whole provider. A `llm-deepseek` route is a composition fact, not something this page can create.
+- **Interrogation covers OpenAI-compatible endpoints** — the adapter reads only that listing shape, so a gateway speaking another protocol reports that it cannot be asked and its models are entered by hand.
 - **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows.

packages/client/ui-models/README.zh.md

@@ -4,12 +4,20 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），而且必须先在本地化对话框中确认，页面才会提交这次破坏性的 unset。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），而且必须先在本地化对话框中确认，页面才会提交这次破坏性的 unset。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
 每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
+## 模型列表与端点询问
+
+pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，行上显示 id 与显示名称，上下文窗口与输出上限收在该行的展开区内，右侧是两个无文字的操作——展开与删除。空列表意味着「使用该路由的内置 catalog」，因此每一行都只会被刻意添加；清空容量会丢弃它，而不是存入一个 schema 会拒绝的值，配置留空的部分由适配器的路由级回退值定尺寸——留空的容量以这些回退值的量级作为占位符，那只是提示而非镜像：该字段按 1000 计 `K`，且部署可以覆盖这些回退值。不是正整数的容量根本不会被存下。
+
+**获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
+
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。
+
 ## 模型体验
 
 无。该分区渲染浏览器配置 UI；这里没有任何内容进入模型请求。
@@ -22,4 +30,6 @@
 
 - **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）。DeepSeek 公开 `baseURL`、`reasoningEffort` 与模型的 `id`/`name`/`contextWindow`/`maxTokens`；pi-ai 公开 `baseURL` 与 `reasoning`。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 `settings.yaml` 中；编辑器未展示的现有模型字段会予以保留。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。
 - **删除一行会把它已存储的密钥留在 `.env` 里**：删除取消设置的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。
+- **只有 pi-ai 路由可以手工声明**：自定义提供方卡片写入 `llm-pi-ai`——唯一一个其 profile 描述整个提供方的 namespace。`llm-deepseek` 路由是组合面的事实，不是本页能创建的东西。
+- **询问只覆盖 OpenAI 兼容端点**：适配器只读这一种列表形状，因此讲其他协议的网关会报告自己无法被询问，其模型需手工填写。
 - **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。

packages/client/ui-models/src/client/CustomProviderCard.tsx

@@ -0,0 +1,240 @@
+/**
+ * The card that declares a provider pi-ai does not ship — an OpenAI-compatible
+ * gateway, a self-hosted server, or a provider newer than the installed
+ * catalog.
+ *
+ * This is a create, not an edit, which is why it is its own card rather than
+ * the provider editor with extra fields: the route id is being *chosen* here,
+ * and the settings address does not exist until it is. One `settings.mutate`
+ * sets the whole profile at `providers.<route>`; the key travels separately
+ * through `credentials.set` under the reference the profile records, exactly as
+ * an existing provider's key does.
+ *
+ * The three fields a hand-declared route cannot default — endpoint, protocol,
+ * and at least one model — are required here rather than at load, so the
+ * failure names the field while the user is still looking at it.
+ */
+
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import { EditorFooter } from './EditorFooter.tsx'
+import { validateDeepSeekModels } from './DeepSeekModelsEditor.tsx'
+import { ModelListEditor } from './ModelListEditor.tsx'
+import type { ModelDraft } from './ModelListEditor.tsx'
+import { deriveKeyRef, messageOf } from './store.ts'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/** The settings namespace a hand-declared provider is written into. */
+const NS = 'llm-pi-ai'
+
+/** A route id usable as a settings key and as the stem of a credential name. */
+const ROUTE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** Props of {@link CustomProviderCard}. */
+export interface CustomProviderCardProps {
+  /** Route ids already declared, so the card refuses to shadow one. */
+  taken: readonly string[]
+  /** Wire protocols the adapter can serve, in the order it reports them. */
+  protocols: readonly string[]
+  /**
+   * Revision of the `llm-pi-ai` user section this card opened at, sent with
+   * the create so a route another tab declared meanwhile is a refusal rather
+   * than a silent overwrite of its whole profile.
+   */
+  revision: number
+  /** Wire faces for the write and for interrogating the endpoint. */
+  api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>
+  /** Section copy. */
+  t: (key: keyof typeof en) => string
+  /** Disable writes (read-only settings provider). */
+  readOnly: boolean
+  /** Close the card; `changed` reports whether a provider was created. */
+  onClose: (changed: boolean) => void
+}
+
+/**
+ * Render the custom-provider creation card.
+ * @param props - existing routes, protocol choices, wire faces, and copy.
+ * @returns the creation card.
+ */
+export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
+  const { taken, protocols, api, t } = props
+  // Captured at mount, like the editor's: the write must be judged against the
+  // section this card was drafted over, not whatever it grew into meanwhile.
+  const [openedAt] = useState(() => props.revision)
+  const [route, setRoute] = useState('')
+  const [displayName, setDisplayName] = useState('')
+  const [baseURL, setBaseURL] = useState('')
+  const [protocol, setProtocol] = useState(protocols[0] ?? '')
+  const [keyDraft, setKeyDraft] = useState('')
+  const [models, setModels] = useState<readonly ModelDraft[]>([])
+  const [busy, setBusy] = useState(false)
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+  const disabled = props.readOnly || busy
+
+  const routeInvalid = route.length > 0 && !ROUTE_PATTERN.test(route)
+  const routeTaken = taken.includes(route)
+  // Rows are checked by the same per-row validator the editor cards use, so a
+  // bad row is named by its position here too. Capacities have route-level
+  // fallbacks; what a route cannot default is at least one model.
+  const modelFailure = validateDeepSeekModels(models)
+  const ready = route.length > 0 && !routeInvalid && !routeTaken
+    && baseURL.length > 0 && models.length > 0 && modelFailure === undefined
+  // The one blocked gate worth a line under the form. The route id is omitted
+  // because its own field already explains itself, and a satisfied card says
+  // nothing at all rather than printing an empty paragraph.
+  const hint = failure !== undefined || ready
+    ? undefined
+    : baseURL.length === 0
+      ? t('customNeedsBaseUrl')
+      : modelFailure !== undefined
+        ? `${t('model')} ${String(modelFailure.index + 1)}: ${t(modelFailure.key)}`
+        : t('customNeedsModels')
+
+  /** Perform the create, returning a failure message or undefined. */
+  const createOnce = async (): Promise<string | undefined> => {
+    const keyRef = deriveKeyRef(route)
+    const profile = {
+      ...displayName.length === 0 ? {} : { displayName },
+      apiKeyEnv: keyRef,
+      api: protocol,
+      baseURL,
+      models: models.map(model => ({ ...model })),
+    }
+    const response = await api.settings.mutate({
+      ns: NS,
+      ops: [{ op: 'set', path: ['providers', route], value: profile }],
+      // `taken` is a snapshot too, so the id check alone cannot see a route
+      // declared after this card opened; the revision makes that race a
+      // `settings-conflict` instead of a write over the other profile.
+      expectedRevision: openedAt,
+    })
+    if (!response.result.ok) return response.result.error.message
+    if (keyDraft.length > 0) {
+      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
+      // The profile landed; saying the key did not is the only honest report,
+      // and the row is now editable so the key can be entered again there.
+      if (!stored.result.ok) return stored.result.error.message
+    }
+    return undefined
+  }
+
+  const create = async (): Promise<void> => {
+    setBusy(true)
+    setFailure(undefined)
+    try {
+      const outcome = await createOnce()
+      if (outcome !== undefined) {
+        setFailure(outcome)
+        return
+      }
+      props.onClose(true)
+    } catch (error) {
+      // A transport failure rejects rather than answering; without this the
+      // card would stay busy with nothing shown.
+      setFailure(messageOf(error))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className={styles['editor']}>
+      <div className={styles['editorHeader']}>
+        <span className={styles['editorTitle']}>{t('customTitle')}</span>
+      </div>
+      <div className={styles['field']}>
+        <span className={styles['fieldLabel']}>{t('customRoute')}</span>
+        <input
+          className={styles['input']}
+          type="text"
+          value={route}
+          placeholder="acme-gateway"
+          aria-label={t('customRoute')}
+          disabled={disabled}
+          onChange={(event) => { setRoute(event.target.value) }}
+        />
+      </div>
+      <p className={styles['advancedHint']}>
+        {routeInvalid ? t('customRouteInvalid') : routeTaken ? t('customRouteTaken') : t('customRouteHint')}
+      </p>
+      <div className={styles['field']}>
+        <span className={styles['fieldLabel']}>{t('customDisplayName')}</span>
+        <input
+          className={styles['input']}
+          type="text"
+          value={displayName}
+          placeholder={route.length === 0 ? t('customDisplayName') : route}
+          aria-label={t('customDisplayName')}
+          disabled={disabled}
+          onChange={(event) => { setDisplayName(event.target.value) }}
+        />
+      </div>
+      <div className={styles['field']}>
+        <span className={styles['fieldLabel']}>{t('baseUrl')}</span>
+        <input
+          className={styles['input']}
+          type="text"
+          value={baseURL}
+          placeholder="https://gateway.example/v1"
+          aria-label={t('baseUrl')}
+          disabled={disabled}
+          onChange={(event) => { setBaseURL(event.target.value) }}
+        />
+      </div>
+      <div className={styles['field']}>
+        <span className={styles['fieldLabel']}>{t('customApi')}</span>
+        <select
+          className={styles['input']}
+          value={protocol}
+          aria-label={t('customApi')}
+          disabled={disabled}
+          onChange={(event) => { setProtocol(event.target.value) }}
+        >
+          {protocols.map(choice => <option key={choice} value={choice}>{choice}</option>)}
+        </select>
+      </div>
+      <div className={styles['field']}>
+        <span className={styles['fieldLabel']}>{t('keyInput')}</span>
+        <input
+          className={styles['input']}
+          type="password"
+          autoComplete="off"
+          value={keyDraft}
+          placeholder={t('keyPlaceholder')}
+          aria-label={t('keyInput')}
+          disabled={disabled}
+          onChange={(event) => { setKeyDraft(event.target.value) }}
+        />
+      </div>
+      <ModelListEditor
+        models={models}
+        onChange={setModels}
+        probe={{
+          settingsNs: NS,
+          baseURL,
+          api: protocol,
+          ...keyDraft.length === 0 ? {} : { apiKey: keyDraft },
+        }}
+        api={api}
+        t={t}
+        disabled={disabled}
+      />
+      {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
+      {/* Only the gates with something to say render; the route-id gate has its
+          own field-level hint, so its blocked state would print an empty line. */}
+      {hint === undefined ? null : <p className={styles['advancedHint']}>{hint}</p>}
+      <EditorFooter
+        t={t}
+        busy={busy}
+        submitDisabled={disabled || !ready}
+        submitLabel="create"
+        submitBusyLabel="creating"
+        onCancel={() => { props.onClose(false) }}
+        onSubmit={() => { void create() }}
+      />
+    </div>
+  )
+}

packages/client/ui-models/src/client/EditorFooter.tsx

@@ -0,0 +1,65 @@
+/**
+ * The action row every provider card ends with: dismiss on the left, commit on
+ * the right.
+ *
+ * The two cards commit different things — one creates a route, one edits an
+ * existing profile — but the row itself carries no such knowledge. It renders
+ * what it is handed, so the cards keep sole ownership of when a commit is
+ * allowed and what the in-flight wording is.
+ *
+ * Cancel refuses input only while a commit is in flight, never because the card
+ * is disabled: a card the deployment cannot write to must still be dismissable.
+ *
+ * @module dsh-client-ui-models/client/EditorFooter
+ */
+
+import type { ReactNode } from 'react'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/** Props of {@link EditorFooter}. */
+export interface EditorFooterProps {
+  /** Localizer for the row's own labels. */
+  t: (key: keyof typeof en) => string
+  /** Whether a commit is in flight; holds Cancel and swaps the commit label. */
+  busy: boolean
+  /** Whether the commit is refused, as judged by the owning card. */
+  submitDisabled: boolean
+  /** Commit label while idle. */
+  submitLabel: keyof typeof en
+  /** Commit label while a commit is in flight. */
+  submitBusyLabel: keyof typeof en
+  /** Dismiss the card without committing. */
+  onCancel: () => void
+  /** Run the card's commit. */
+  onSubmit: () => void
+}
+
+/**
+ * Render one provider card's action row.
+ * @param props - the labels, commit gating, and handlers the owning card supplies.
+ * @returns the cancel/commit row.
+ */
+export function EditorFooter(props: EditorFooterProps): ReactNode {
+  const { t } = props
+  return (
+    <div className={styles['editorActions']}>
+      <button
+        type="button"
+        className={styles['secondaryButton']}
+        disabled={props.busy}
+        onClick={props.onCancel}
+      >
+        {t('cancel')}
+      </button>
+      <button
+        type="button"
+        className={styles['primaryButton']}
+        disabled={props.submitDisabled}
+        onClick={props.onSubmit}
+      >
+        {props.busy ? t(props.submitBusyLabel) : t(props.submitLabel)}
+      </button>
+    </div>
+  )
+}

packages/client/ui-models/src/client/ModelListEditor.tsx

@@ -0,0 +1,459 @@
+/**
+ * The model list of one pi-ai provider profile, plus the action that asks the
+ * provider what it serves.
+ *
+ * The list is the profile's `models` array as the card holds it: an empty list
+ * means "serve this route's built-in catalog", and any entry replaces that
+ * catalog, so a row is only ever added deliberately. Fetching asks the endpoint
+ * **the form currently shows** — including a key typed but not yet saved — so
+ * adding a provider is one pass instead of save-then-return; the reply is
+ * candidates the user picks from, never configuration written behind them.
+ *
+ * A provider that cannot be interrogated (an unreachable endpoint, a protocol
+ * with no readable listing) is not a dead end: the failure is shown next to the
+ * rows the user can still fill in by hand.
+ */
+
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import type { DiscoveredModelView, IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import { formatCapacity, parseCapacity } from './DeepSeekModelsEditor.tsx'
+import type { DeepSeekModelDraft } from './DeepSeekModelsEditor.tsx'
+import { messageOf } from './store.ts'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/**
+ * One configured model row. Structurally open, exactly like the DeepSeek
+ * catalog editor's rows: a profile field this card does not edit — one a future
+ * schema adds, or one hand-written in `settings.yaml` — has to survive being
+ * edited here rather than being dropped by a rebuild.
+ */
+export type ModelDraft = DeepSeekModelDraft
+
+/** A row's text field, or the empty string when unset or not a string. */
+function textOf(model: ModelDraft, key: string): string {
+  const value = model[key]
+  return typeof value === 'string' ? value : ''
+}
+
+/** A row's numeric field, or `undefined` when unset or not a number. */
+function numberOf(model: ModelDraft, key: string): number | undefined {
+  const value = model[key]
+  return typeof value === 'number' ? value : undefined
+}
+
+/** What an interrogation needs, taken from the live form. */
+export interface ProbeTarget {
+  /** Settings namespace whose adapter family answers. */
+  settingsNs: string
+  /**
+   * Route being edited, when the card edits one. An adapter that already
+   * describes it answers from its own registry, so such a card can ask without
+   * an endpoint at all.
+   */
+  provider?: string
+  /** Endpoint as the form currently shows it. */
+  baseURL?: string
+  /** Wire protocol the form names, when it names one. */
+  api?: string
+  /** Key typed into the form and not yet stored, when there is one. */
+  apiKey?: string
+}
+
+/** Props of {@link ModelListEditor}. */
+export interface ModelListEditorProps {
+  /** The rows as currently drafted. */
+  models: readonly ModelDraft[]
+  /** Whether the user layer currently owns the whole array; absent on a create. */
+  overridden?: boolean
+  /** Replace the drafted rows. */
+  onChange: (models: ModelDraft[]) => void
+  /** Remove the user-owned array and return to inheritance; absent on a create. */
+  onReset?: () => void
+  /** Endpoint facts for the fetch action. */
+  probe: ProbeTarget
+  /** Wire face the fetch action calls. */
+  api: Pick<IApiClient, 'llm'>
+  /** Section copy. */
+  t: (key: keyof typeof en) => string
+  /** Disable every control (read-only deployment or a pending write). */
+  disabled: boolean
+}
+
+/** Disclosure chevron; rotates to point down while its row is open. */
+function IconChevron({ open }: { open: boolean }): ReactNode {
+  return (
+    <svg
+      width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden
+      style={{ transform: open ? 'rotate(90deg)' : undefined, transition: 'transform 120ms ease' }}
+    >
+      <path d="M6 3.5L10.5 8L6 12.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+/** Removal glyph for one model row. */
+function IconTrash(): ReactNode {
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path
+        d="M2.5 4h11M6.5 4V2.5h3V4M4 4l.7 9a1 1 0 001 .9h4.6a1 1 0 001-.9L12 4M6.5 6.8v4.4M9.5 6.8v4.4"
+        stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** The two token counts edited as K/M-suffixed text behind a row's disclosure. */
+type CapacityField = 'contextWindow' | 'maxTokens'
+
+/**
+ * What an empty capacity field is worth, shown as its placeholder so a row left
+ * blank does not read as a model with no capacity at all.
+ *
+ * The magnitudes are the adapter's own route-level fallbacks (`llm-pi-ai`'s
+ * `defaultContextWindow` and `defaultMaxTokens`), spelled the way a person
+ * would say them. They are a hint, not a mirror: this page counts `K` as 1000,
+ * so typing `256K` stores 256000 while leaving the field blank keeps the
+ * adapter's 262144. A deployment that overrides those defaults is not
+ * reflected here — nothing on this page can read them.
+ */
+const CAPACITY_HINT: Readonly<Record<CapacityField, string>> = {
+  contextWindow: '256K',
+  maxTokens: '32K',
+}
+
+/**
+ * Spell a stored count for a field that may be unset. The spelling itself is
+ * {@link formatCapacity}, shared with the DeepSeek catalog editor so both
+ * surfaces read and write one K/M vocabulary.
+ * @param value - stored capacity, or `undefined` for an unset field.
+ * @returns the field text, empty when unset.
+ */
+function capacitySpelling(value: number | undefined): string {
+  return value === undefined ? '' : formatCapacity(value)
+}
+
+/** Adopt a candidate, keeping whatever capacities the provider disclosed. */
+function adopt(candidate: DiscoveredModelView): ModelDraft {
+  return {
+    id: candidate.id,
+    ...candidate.name === undefined ? {} : { name: candidate.name },
+    ...candidate.contextWindow === undefined ? {} : { contextWindow: candidate.contextWindow },
+    ...candidate.maxTokens === undefined ? {} : { maxTokens: candidate.maxTokens },
+  }
+}
+
+/**
+ * Render the model list with its fetch action.
+ * @param props - the drafted rows, probe target, wire face, and copy.
+ * @returns the model-list editor.
+ */
+export function ModelListEditor(props: ModelListEditorProps): ReactNode {
+  const { models, onChange, probe, api, t, disabled } = props
+  const [busy, setBusy] = useState(false)
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+  const [candidates, setCandidates] = useState<readonly DiscoveredModelView[] | undefined>(undefined)
+  const [picked, setPicked] = useState<ReadonlySet<string>>(new Set())
+  // Rows carry an id and a name; capacities are the exception, so they stay
+  // folded until asked for rather than crowding every row with four inputs.
+  const [expanded, setExpanded] = useState<ReadonlySet<number>>(new Set())
+  // Capacities are edited as text, so a field's keystrokes are held here rather
+  // than re-derived from the parsed count on every change — that would rewrite
+  // `1000` to `1K` mid-word. Unreadable text is kept past blur so the refusal
+  // names a row the user can still see, which is why this is one entry PER
+  // FIELD: a single buffer would be displaced by editing any other field, and
+  // the abandoned one would render its stored NaN as the literal `NaN`.
+  const [editing, setEditing] = useState<ReadonlyMap<string, string>>(new Map())
+
+  /** Buffer key for one capacity field; the row half moves when rows do. */
+  const bufferKey = (index: number, field: CapacityField): string => `${String(index)}:${field}`
+
+  const editCapacity = (index: number, field: CapacityField, text: string): void => {
+    setEditing(current => new Map(current).set(bufferKey(index, field), text))
+    patch(index, { [field]: parseCapacity(text) })
+  }
+
+  /** What a capacity field shows: the buffer while typing, else the stored count. */
+  const capacityText = (model: ModelDraft, index: number, field: CapacityField): string =>
+    editing.get(bufferKey(index, field)) ?? capacitySpelling(numberOf(model, field))
+
+  /** Drop one row's entries and shift the rows after it down, in one pass. */
+  const reindexOnRemove = (
+    current: ReadonlyMap<string, string>,
+    index: number,
+  ): Map<string, string> => {
+    const next = new Map<string, string>()
+    for (const [key, value] of current) {
+      const at = Number(key.slice(0, key.indexOf(':')))
+      if (at === index) continue
+      // Only the row number moves; the field half of the key is untouched.
+      next.set(at > index ? key.replace(/^\d+/, String(at - 1)) : key, value)
+    }
+    return next
+  }
+
+  const toggleExpanded = (index: number): void => {
+    setExpanded((current) => {
+      const next = new Set(current)
+      if (!next.delete(index)) next.add(index)
+      return next
+    })
+  }
+
+  const patch = (index: number, next: Record<string, string | number | undefined>): void => {
+    onChange(models.map((model, at) => {
+      if (at !== index) return model
+      // Rebuilt rather than spread over: an emptied optional field has to leave
+      // the profile, not be stored as a value its schema would reject.
+      // Spread first so a field this card does not edit survives; an emptied
+      // optional field is then dropped rather than stored as a value its
+      // schema would reject.
+      const cleared = new Set(
+        Object.entries(next).filter(([, value]) => value === undefined || value === '').map(([key]) => key),
+      )
+      return Object.fromEntries(
+        Object.entries({ ...model, ...next }).filter(([key]) => !cleared.has(key)),
+      )
+    }))
+  }
+
+  const fetchModels = async (): Promise<void> => {
+    setBusy(true)
+    setFailure(undefined)
+    try {
+      const response = await api.llm.discoverModels({
+        settingsNs: probe.settingsNs,
+        ...probe.provider === undefined ? {} : { provider: probe.provider },
+        ...probe.baseURL === undefined || probe.baseURL.length === 0 ? {} : { baseURL: probe.baseURL },
+        ...probe.api === undefined ? {} : { api: probe.api },
+        ...probe.apiKey === undefined ? {} : { apiKey: probe.apiKey },
+      })
+      if (!response.result.ok) {
+        setFailure(response.result.error.message)
+        return
+      }
+      const found = response.result.value.models
+      if (found.length === 0) {
+        setFailure(t('fetchEmpty'))
+        return
+      }
+      // Everything already configured starts unchecked, so adopting a
+      // selection never silently rewrites a capacity the user corrected.
+      const known = new Set(models.map(model => textOf(model, 'id')))
+      setCandidates(found)
+      setPicked(new Set(found.filter(model => !known.has(model.id)).map(model => model.id)))
+    } catch (error) {
+      // The transport rejected rather than answering; without this the button
+      // would stay busy with nothing shown.
+      setFailure(messageOf(error))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const closePicker = (): void => {
+    setCandidates(undefined)
+    setPicked(new Set())
+  }
+
+  const adoptPicked = (): void => {
+    /* v8 ignore next -- the dialog only renders with candidates loaded */
+    if (candidates === undefined) return
+    const byId = new Map(models.map(model => [textOf(model, 'id'), model]))
+    for (const candidate of candidates) {
+      if (!picked.has(candidate.id)) continue
+      // A row the user already tuned wins over the provider's own numbers.
+      // Keyed by id, so a half-typed row whose id is still empty is not a
+      // match and the candidate joins as its own row — correct, since a row
+      // without an id is not yet a model and the create/apply gates refuse it.
+      byId.set(candidate.id, byId.get(candidate.id) ?? adopt(candidate))
+    }
+    onChange([...byId.values()])
+    closePicker()
+  }
+
+  const toggle = (id: string): void => {
+    setPicked((current) => {
+      const next = new Set(current)
+      if (!next.delete(id)) next.add(id)
+      return next
+    })
+  }
+
+  // A route the adapter already describes answers without an endpoint; only a
+  // draft with neither has nothing to ask about.
+  const askable = probe.provider !== undefined || (probe.baseURL !== undefined && probe.baseURL.length > 0)
+  return (
+    <section className={styles['modelCatalog']} aria-label={t('models')}>
+      <div className={styles['modelListHead']}>
+        <div className={styles['modelCatalogHeading']}>
+          <span className={styles['modelCatalogTitle']}>{t('models')}</span>
+          {props.overridden === undefined
+            ? null
+            : (
+              <span className={styles['modelCatalogMeta']}>
+                {props.overridden ? t('modelsCustomized') : t('modelsInherited')}
+              </span>
+            )}
+        </div>
+        {props.overridden === true && props.onReset !== undefined
+          ? (
+            <button
+              type="button"
+              className={styles['linkButton']}
+              disabled={disabled}
+              onClick={props.onReset}
+            >
+              {t('resetModels')}
+            </button>
+          )
+          : null}
+        <button
+          type="button"
+          className={styles['linkButton']}
+          disabled={disabled || busy || !askable}
+          title={askable ? undefined : t('fetchNeedsBaseUrl')}
+          onClick={() => { void fetchModels() }}
+        >
+          {busy ? t('fetching') : t('fetchModels')}
+        </button>
+      </div>
+      {models.length === 0 ? <p className={styles['modelEmpty']}>{t('modelsEmpty')}</p> : null}
+      {models.map((model, index) => (
+        <div key={index} className={styles['modelEntry']}>
+          <div className={styles['modelRow']}>
+            <input
+              className={styles['input']}
+              type="text"
+              value={textOf(model, 'id')}
+              placeholder={t('modelId')}
+              aria-label={`${t('modelId')} ${index + 1}`}
+              disabled={disabled}
+              onChange={(event) => { patch(index, { id: event.target.value }) }}
+            />
+            <input
+              className={styles['input']}
+              type="text"
+              value={textOf(model, 'name')}
+              placeholder={t('modelName')}
+              aria-label={`${t('modelName')} ${index + 1}`}
+              disabled={disabled}
+              onChange={(event) => { patch(index, { name: event.target.value === '' ? undefined : event.target.value }) }}
+            />
+            <button
+              type="button"
+              className={styles['iconButton']}
+              aria-label={`${t('modelAdvanced')} ${index + 1}`}
+              aria-expanded={expanded.has(index)}
+              title={t('modelAdvanced')}
+              onClick={() => { toggleExpanded(index) }}
+            >
+              <IconChevron open={expanded.has(index)} />
+            </button>
+            <button
+              type="button"
+              className={`${styles['iconButton']} ${styles['iconButtonDanger']}`}
+              aria-label={`${t('removeModel')} ${index + 1}`}
+              title={t('removeModel')}
+              disabled={disabled}
+              onClick={() => {
+                onChange(models.filter((_model, at) => at !== index))
+                // Both stores are keyed by position, so every row after this
+                // one shifts down and would otherwise inherit its neighbour's
+                // state — a different row's capacities popping open, or its
+                // half-typed text appearing in another row's field.
+                setExpanded((current) => {
+                  const next = new Set<number>()
+                  for (const at of current) {
+                    if (at < index) next.add(at)
+                    else if (at > index) next.add(at - 1)
+                  }
+                  return next
+                })
+                setEditing(current => reindexOnRemove(current, index))
+              }}
+            >
+              <IconTrash />
+            </button>
+          </div>
+          {expanded.has(index)
+            ? (
+              <div className={styles['modelAdvanced']}>
+                <label className={styles['modelField']}>
+                  <span className={styles['modelFieldLabel']}>{t('modelContextWindow')}</span>
+                  <input
+                    className={styles['input']}
+                    type="text"
+                    inputMode="numeric"
+                    value={capacityText(model, index, 'contextWindow')}
+                    placeholder={CAPACITY_HINT.contextWindow}
+                    aria-label={`${t('modelContextWindow')} ${index + 1}`}
+                    disabled={disabled}
+                    onChange={(event) => { editCapacity(index, 'contextWindow', event.target.value) }}
+                  />
+                </label>
+                <label className={styles['modelField']}>
+                  <span className={styles['modelFieldLabel']}>{t('modelMaxTokens')}</span>
+                  <input
+                    className={styles['input']}
+                    type="text"
+                    inputMode="numeric"
+                    value={capacityText(model, index, 'maxTokens')}
+                    placeholder={CAPACITY_HINT.maxTokens}
+                    aria-label={`${t('modelMaxTokens')} ${index + 1}`}
+                    disabled={disabled}
+                    onChange={(event) => { editCapacity(index, 'maxTokens', event.target.value) }}
+                  />
+                </label>
+              </div>
+            )
+            : null}
+        </div>
+      ))}
+      <button
+        type="button"
+        className={styles['addModelButton']}
+        disabled={disabled}
+        onClick={() => { onChange([...models, { id: '' }]) }}
+      >
+        {t('addModel')}
+      </button>
+      {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
+      <Modal
+        open={candidates !== undefined}
+        onClose={closePicker}
+        title={t('fetchTitle')}
+        closeLabel={t('close')}
+        description={t('fetchDescription')}
+        className={styles['fetchDialog'] as string}
+        footer={(
+          <>
+            <Button variant="outline" onClick={closePicker}>{t('cancel')}</Button>
+            <Button variant="outline" onClick={adoptPicked}>{t('fetchAdopt')}</Button>
+          </>
+        )}
+      >
+        <ul className={styles['candidateList']}>
+          {(candidates ?? []).map(candidate => (
+            <li key={candidate.id} className={styles['candidate']}>
+              <label className={styles['candidateLabel']}>
+                <input
+                  type="checkbox"
+                  checked={picked.has(candidate.id)}
+                  onChange={() => { toggle(candidate.id) }}
+                />
+                {/* The id alone: it is the string adoption writes, and the
+                    capacities the endpoint reported are adopted with it and
+                    editable in the row that appears. */}
+                <span className={styles['candidateId']}>{candidate.id}</span>
+              </label>
+            </li>
+          ))}
+        </ul>
+      </Modal>
+    </section>
+  )
+}

packages/client/ui-models/src/client/ModelsSection.module.css

@@ -264,11 +264,26 @@
   gap: 12px;
 }
 
+/* The two ways to gain a provider, as equal siblings spanning the same width
+   as the rows above. Wraps rather than shrinking below a legible label. */
+.addActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
 .addButton {
-  display: inline-flex;
-  align-items: center;
+  /* Overrides the shared button base above: these two are not pills sitting in
+     a footer but the last slot of the provider list, so they split the row
+     evenly and repeat the row cards' corner. Dashed, like every other "nothing
+     here yet" affordance on this page, to read as a place rather than a
+     command. */
+  flex: 1 1 0;
+  min-width: 180px;
   gap: 6px;
-  align-self: flex-start;
+  height: 44px;
+  border: 1px dashed var(--dsw-alias-border-l3);
+  border-radius: 12px;
 }
 
 .addCard,
@@ -572,3 +587,44 @@ select.input {
     transition: none;
   }
 }
+
+.fetchDialog {
+  max-width: 520px;
+
+  /* The candidate list scrolls inside this dialog, an elevated surface, so the
+     scrollbar indirection is rebound here rather than on the scrolling child:
+     the elevation choice belongs with the surface and inherits down (see
+     ui-theme styles/scrollbar.css for the contract). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+.candidateList {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  max-height: 320px;
+  margin: 0;
+  overflow-y: auto;
+  padding: 0;
+  list-style: none;
+}
+
+.candidate {
+  border-radius: 6px;
+}
+
+.candidateLabel {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  cursor: pointer;
+}
+
+.candidateId {
+  flex: 1 1 auto;
+  font-family: var(--ds-font-family-code);
+  font-size: 13px;
+  overflow-wrap: anywhere;
+}

packages/client/ui-models/src/client/ModelsSection.tsx

@@ -14,7 +14,8 @@ import type { ReactNode } from 'react'
 import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
 import { Button, IconPlusOutline16, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
-import { messageOf } from './store.ts'
+import { CustomProviderCard } from './CustomProviderCard.tsx'
+import { messageOf, protocolChoices } from './store.ts'
 import type { ModelsSettingsState, ModelsSettingsStore, ProviderRow } from './store.ts'
 import { ProviderEditor } from './ProviderEditor.tsx'
 import type { en } from './locales.ts'
@@ -27,7 +28,7 @@ export interface ModelsSectionInjected {
   /** uSES subscription hook bound to the store. */
   useSnapshot: SnapshotSelectorHook<ModelsSettingsState>
   /** Wire faces the editor writes through. */
-  api: Pick<IApiClient, 'settings' | 'credentials'>
+  api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>
   /** Section copy. */
   t: (key: keyof typeof en) => string
 }
@@ -118,10 +119,12 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
   const [adding, setAdding] = useState(false)
   const [deleteTarget, setDeleteTarget] = useState<EditorTarget | undefined>(undefined)
   const [deleting, setDeleting] = useState(false)
+  const [declaring, setDeclaring] = useState(false)
 
   const closeEditor = (changed: boolean): void => {
     setEditing(undefined)
     setAdding(false)
+    setDeclaring(false)
     if (changed) void controller.load()
   }
 
@@ -163,6 +166,10 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
   const addable = state.rows.filter(row => !row.configured && row.entry.settingsNs !== '')
   const addTarget = adding ? editing : undefined
   const addNamespace = addTarget === undefined ? undefined : state.namespaces.get(addTarget.settingsNs)
+  // Hand-declared routes live in the pi-ai namespace, which is also the only
+  // one whose schema names the protocols one may speak; without it mounted
+  // there is nothing to declare and the entry point stays disabled.
+  const protocols = protocolChoices(state.namespaces.get('llm-pi-ai'))
 
   return (
     <div className={styles['section']}>
@@ -202,7 +209,14 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
                   <button
                     type="button"
                     className={styles['secondaryButton']}
-                    onClick={() => { setAdding(false); setEditing(open ? undefined : target) }}
+                    onClick={() => {
+                      // One card at a time: leaving `declaring` set would show
+                      // the create card beside this editor, and closing either
+                      // one discards the other's draft.
+                      setDeclaring(false)
+                      setAdding(false)
+                      setEditing(open ? undefined : target)
+                    }}
                   >
                     {t('edit')}
                   </button>
@@ -274,24 +288,55 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
               />
             </div>
           )
-          : (
-            <button
-              type="button"
-              className={styles['addButton']}
-              disabled={addable.length === 0 || !state.writable}
-              onClick={() => {
-                const first = addable[0]
-                /* v8 ignore next -- the button is disabled while nothing is addable */
-                if (first === undefined) return
-                setAdding(true)
-                setEditing(targetOf(first))
-              }}
-            >
-              {/* Same glyph as the composer's attach button. */}
-              <IconPlusOutline16 size={14} />
-              {t('add')}
-            </button>
-          )}
+          : declaring
+            ? (
+              <div className={styles['addCard']}>
+                <CustomProviderCard
+                  taken={state.rows.map(row => row.entry.provider)}
+                  protocols={protocols}
+                  /* v8 ignore next -- the card only opens from a button disabled without this namespace */
+                  revision={state.namespaces.get('llm-pi-ai')?.revision ?? 0}
+                  api={api}
+                  t={t}
+                  readOnly={!state.writable}
+                  onClose={closeEditor}
+                />
+              </div>
+            )
+            : (
+              // One row for the two ways to gain a provider: adopt one the
+              // adapter already knows, or declare one it does not. Side by side
+              // and equal-width so they read as siblings and line up with the
+              // rows above, rather than two pills of different lengths.
+              <div className={styles['addActions']}>
+                <button
+                  type="button"
+                  className={styles['addButton']}
+                  disabled={addable.length === 0 || !state.writable}
+                  onClick={() => {
+                    const first = addable[0]
+                    /* v8 ignore next -- the button is disabled while nothing is addable */
+                    if (first === undefined) return
+                    setDeclaring(false)
+                    setAdding(true)
+                    setEditing(targetOf(first))
+                  }}
+                >
+                  {/* Same glyph as the composer's attach button. */}
+                  <IconPlusOutline16 size={14} />
+                  {t('add')}
+                </button>
+                <button
+                  type="button"
+                  className={styles['addButton']}
+                  disabled={protocols.length === 0 || !state.writable}
+                  onClick={() => { setAdding(false); setEditing(undefined); setDeclaring(true) }}
+                >
+                  <IconPlusOutline16 size={14} />
+                  {t('customAdd')}
+                </button>
+              </div>
+            )}
       </div>
       <Modal
         open={deleteTarget !== undefined}

packages/client/ui-models/src/client/ProviderEditor.tsx

@@ -22,6 +22,8 @@ import {
 import {
   DeepSeekModelsEditor, modelDrafts, validateDeepSeekModels,
 } from './DeepSeekModelsEditor.tsx'
+import { EditorFooter } from './EditorFooter.tsx'
+import { ModelListEditor } from './ModelListEditor.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
@@ -56,8 +58,8 @@ export interface ProviderEditorProps {
   namespace: SettingsNamespaceView
   /** Path from the section root to this provider's profile. */
   settingsPath: readonly string[]
-  /** Wire faces for writes. */
-  api: Pick<IApiClient, 'settings' | 'credentials'>
+  /** Wire faces for writes and for interrogating a provider endpoint. */
+  api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>
   /** Section copy. */
   t: (key: keyof typeof en) => string
   /** Disable writes (read-only settings provider). */
@@ -167,6 +169,22 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
     setDraft(current => next === undefined ? deletePath(current, [key]) : setPath(current, [key], next))
   }
 
+  // The model list is validated by the same per-row checker for both families,
+  // so a bad row is named by its position rather than by a blanket message.
+  const modelFailure = validateDeepSeekModels(getPath(draft, ['models']))
+  // What the form currently shows, which is what an interrogation must ask:
+  // an edited-but-unsaved endpoint, and a key typed but not yet stored.
+  const probeApi = stringAt(draft, 'api') ?? stringAt(fallback, 'api')
+  const probeBaseURL = stringAt(draft, 'baseURL') ?? stringAt(fallback, 'baseURL')
+  const probe = {
+    settingsNs: namespace.ns,
+    // Naming the route lets an adapter that already describes it answer from
+    // its own registry — better metadata, no network call, no endpoint needed.
+    provider: props.provider,
+    ...probeBaseURL === undefined ? {} : { baseURL: probeBaseURL },
+    ...probeApi === undefined ? {} : { api: probeApi },
+    ...keyDraft.length === 0 ? {} : { apiKey: keyDraft },
+  }
   /**
    * The write for this card, or a failure message. Every edit travels as
    * path ops against the STORED section: the draft comes from the redacted
@@ -183,10 +201,15 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
       && stringAt(fallback, 'apiKeyEnv') === undefined
       ? setPath(draft, ['apiKeyEnv'], keyRef)
       : draft
-    if (layout === 'deepseek') {
-      const modelFailure = validateDeepSeekModels(getPath(next, ['models']))
-      if (modelFailure !== undefined) {
-        return `${t('model')} ${String(modelFailure.index + 1)}: ${t(modelFailure.key)}`
+    {
+      // The same checker gates the submit button, so a card cannot reach this
+      // with a bad row; it stays because the schema check below would refuse
+      // the write with a message naming a path instead of the row, and because
+      // nothing but this function decides what is written.
+      const failure = validateDeepSeekModels(getPath(next, ['models']))
+      /* v8 ignore next 3 -- unreachable from the card: the same failure disables submit */
+      if (failure !== undefined) {
+        return `${t('model')} ${String(failure.index + 1)}: ${t(failure.key)}`
       }
     }
     /* v8 ignore next -- apply is only reachable from the rendered card, which required a resolved node */
@@ -263,6 +286,17 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
     const models = modelDrafts(modelsOverridden ? customModels : inheritedModels())
     const defaultContextWindow = getPath(fallback, ['defaultContextWindow'])
     const defaultMaxTokens = getPath(fallback, ['maxTokens'])
+    /** What both family editors take: the rows, whose layer owns them, and the two writes. */
+    const catalogProps = {
+      models,
+      overridden: modelsOverridden,
+      t,
+      disabled,
+      onChange: (next: Record<string, unknown>[]) => {
+        setDraft(current => setPath(current, ['models'], next))
+      },
+      onReset: () => { setDraft(current => deletePath(current, ['models'])) },
+    }
     return (
       <>
         <div className={styles['field']}>
@@ -316,22 +350,20 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 ))}
               </select>
             </div>
+            {/* Both families edit the same rows through the same contract; only
+                the extras differ — DeepSeek's inherited capacities, pi-ai's
+                endpoint interrogation. */}
             {family === 'deepseek'
               ? (
                 <DeepSeekModelsEditor
-                  models={models}
-                  overridden={modelsOverridden}
+                  {...catalogProps}
                   defaultContextWindow={typeof defaultContextWindow === 'number'
                     ? defaultContextWindow
                     : undefined}
                   defaultMaxTokens={typeof defaultMaxTokens === 'number' ? defaultMaxTokens : undefined}
-                  t={t}
-                  disabled={disabled}
-                  onChange={(next) => { setDraft(current => setPath(current, ['models'], next)) }}
-                  onReset={() => { setDraft(current => deletePath(current, ['models'])) }}
                 />
               )
-              : null}
+              : <ModelListEditor {...catalogProps} probe={probe} api={api} />}
           </div>
         </details>
       </>
@@ -354,24 +386,22 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
         ? <p className={styles['advancedHint']}>{`${t('advancedHint')} (${namespace.ns})`}</p>
         : curatedFields(layout)}
       {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
-      <div className={styles['editorActions']}>
-        <button
-          type="button"
-          className={styles['secondaryButton']}
-          disabled={busy}
-          onClick={() => { props.onClose(false) }}
-        >
-          {t('cancel')}
-        </button>
-        <button
-          type="button"
-          className={styles['primaryButton']}
-          disabled={disabled || layout === 'unknown'}
-          onClick={() => { void apply() }}
-        >
-          {busy ? t('applying') : t('apply')}
-        </button>
-      </div>
+      {modelFailure === undefined
+        ? null
+        : (
+          <p className={styles['advancedHint']}>
+            {`${t('model')} ${String(modelFailure.index + 1)}: ${t(modelFailure.key)}`}
+          </p>
+        )}
+      <EditorFooter
+        t={t}
+        busy={busy}
+        submitDisabled={disabled || layout === 'unknown' || modelFailure !== undefined}
+        submitLabel="apply"
+        submitBusyLabel="applying"
+        onCancel={() => { props.onClose(false) }}
+        onSubmit={() => { void apply() }}
+      />
     </div>
   )
 }

packages/client/ui-models/src/client/locales.ts

@@ -52,6 +52,29 @@ export const en = {
   modelContextInvalid: 'Context window must be a positive count, like 131072, 256K, or 1M.',
   modelMaxTokensInvalid: 'Max output tokens must be a positive count, like 8192, 64K, or 1M.',
   advancedHint: 'Other fields live in settings.yaml; edit that section directly.',
+  modelCapacityInvalid: 'A capacity must be a number, optionally suffixed K or M.',
+  modelDuplicate: 'Each model ID may appear once.',
+  modelContextWindow: 'Context window',
+  modelMaxTokens: 'Max output tokens',
+  fetchModels: 'Fetch available models',
+  fetching: 'Asking the provider\u2026',
+  fetchNeedsBaseUrl: 'Enter the base URL first, then fetch.',
+  fetchEmpty: 'The provider listed no models. Add them by hand.',
+  fetchTitle: 'Choose models to add',
+  fetchDescription: 'These are the models this provider has available. Choose the ones to add.',
+  fetchAdopt: 'Add selected',
+  customAdd: 'Add a custom provider',
+  customTitle: 'Custom provider',
+  customRoute: 'Provider ID',
+  customRouteHint: 'Lowercase identifier that uniquely names this provider in requests and as its credential name.',
+  customRouteInvalid: 'Use lowercase letters, digits, and dashes.',
+  customRouteTaken: 'A provider already uses this ID.',
+  customDisplayName: 'Display name',
+  customApi: 'API protocol',
+  customNeedsBaseUrl: 'A custom provider needs a base URL.',
+  customNeedsModels: 'A custom provider needs at least one model.',
+  create: 'Create provider',
+  creating: 'Creating\u2026',
   onboardingTitle: 'Add an API key to get started',
   onboardingDescription: 'Configure the official DeepSeek provider to start building.',
   onboardingGoToSettings: 'Go to settings',
@@ -113,6 +136,29 @@ export const zh: typeof en = {
   modelContextInvalid: '上下文窗口必须是正数，例如 131072、256K 或 1M。',
   modelMaxTokensInvalid: '最大输出 token 数必须是正数，例如 8192、64K 或 1M。',
   advancedHint: '其余字段在 settings.yaml 中，请直接编辑对应段。',
+  modelCapacityInvalid: '容量需为数字，可加 K 或 M 后缀。',
+  modelDuplicate: '每个模型 ID 只能出现一次。',
+  modelContextWindow: '上下文窗口',
+  modelMaxTokens: '最大输出 token',
+  fetchModels: '获取可用模型',
+  fetching: '正在询问提供方\u2026',
+  fetchNeedsBaseUrl: '请先填写 API 地址，再获取。',
+  fetchEmpty: '该提供方没有列出任何模型，请手动添加。',
+  fetchTitle: '选择要添加的模型',
+  fetchDescription: '以下是模型提供方的可用模型，勾选要添加的模型。',
+  fetchAdopt: '添加所选',
+  customAdd: '添加自定义提供方',
+  customTitle: '自定义提供方',
+  customRoute: 'Provider ID',
+  customRouteHint: '小写标识，在请求中唯一标识该提供方，并用于派生凭据名。',
+  customRouteInvalid: '只能使用小写字母、数字和短横线。',
+  customRouteTaken: '已有提供方使用了这个 ID。',
+  customDisplayName: '显示名称',
+  customApi: 'API 协议',
+  customNeedsBaseUrl: '自定义提供方需要填写 API 地址。',
+  customNeedsModels: '自定义提供方至少需要一个模型。',
+  create: '创建提供方',
+  creating: '创建中\u2026',
   onboardingTitle: '添加一个 API Key 开始使用',
   onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。',
   onboardingGoToSettings: '前往配置',

packages/client/ui-models/src/client/store.ts

@@ -11,7 +11,13 @@ import type {
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { getPath, hasPath } from '@deepseek-ai/dsh-client-schema-form'
+import { getPath, hasPath, nodeAtPath, rehydrateSchema } from '@deepseek-ai/dsh-client-schema-form'
+
+/**
+ * Any route key walks a dict schema to the same profile node, so the lookup
+ * names one that cannot collide with a configured route.
+ */
+const PROBE_ROUTE = '\u0000probe'
 
 /** One provider row the page renders. */
 export interface ProviderRow {
@@ -66,6 +72,22 @@ export function deriveKeyRef(provider: string): string {
   return `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`
 }
 
+/**
+ * The wire protocols a hand-declared route may name, read out of the owning
+ * namespace's own schema. This stays a schema read rather than a wire field so
+ * the choices the page offers cannot drift from the ones the adapter accepts:
+ * both come from the same `Config`.
+ * @param namespace - the namespace view whose schema declares the profile shape.
+ * @returns the protocol identifiers, or an empty list when the schema has none.
+ */
+export function protocolChoices(namespace: SettingsNamespaceView | undefined): string[] {
+  if (namespace === undefined) return []
+  const node = nodeAtPath(rehydrateSchema(namespace.schema), ['providers', PROBE_ROUTE, 'api'])
+  const list = (node as { type?: string; list?: readonly { value?: unknown }[] } | undefined)
+  if (list?.type !== 'union' || list.list === undefined) return []
+  return list.list.map(entry => entry.value).filter((value): value is string => typeof value === 'string')
+}
+
 /** The credential reference a resolved profile names (its `apiKeyEnv` field). */
 function apiKeyEnvOf(namespace: SettingsNamespaceView | undefined, path: readonly string[]): string | undefined {
   if (namespace === undefined) return undefined

packages/client/ui-models/tests/provider-form.spec.tsx

@@ -0,0 +1,865 @@
+// @vitest-environment jsdom
+/** Model-list editing, endpoint interrogation, and hand-declared provider creation. */
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import Schema from 'schemastery'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
+import { ModelsSection } from '../src/client/ModelsSection.tsx'
+import type { ModelsSectionInjected } from '../src/client/ModelsSection.tsx'
+import { CustomProviderCard } from '../src/client/CustomProviderCard.tsx'
+import { formatCapacity, parseCapacity } from '../src/client/DeepSeekModelsEditor.tsx'
+import { ModelsSettingsStore, protocolChoices } from '../src/client/store.ts'
+import { en } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+const t: ModelsSectionInjected['t'] = key => en[key]
+
+const PROTOCOLS = ['openai-completions', 'openai-responses', 'anthropic-messages']
+
+/** The pi-ai profile shape as the host serializes it, including the layer-1 fields. */
+const PiAiConfig = Schema.object({
+  providers: Schema.dict(Schema.object({
+    apiKey: Schema.string().role('secret'),
+    apiKeyEnv: Schema.string().role('credential-ref'),
+    displayName: Schema.string(),
+    api: Schema.union(PROTOCOLS),
+    baseURL: Schema.string(),
+    models: Schema.array(Schema.object({
+      id: Schema.string().required(),
+      name: Schema.string(),
+      contextWindow: Schema.number(),
+      maxTokens: Schema.number(),
+    })),
+    reasoning: Schema.union(['off', 'high']),
+  })),
+})
+
+let nextRpc = 0
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `r-${nextRpc++}` as never, result: { ok: true, value } }
+}
+function fail<T>(message: string, code: string): RpcResponse<T> {
+  return { rpcId: `r-${nextRpc++}` as never, result: { ok: false, error: { code, message, details: {} } as never } }
+}
+
+function piAiNamespace(
+  providers: Record<string, unknown>,
+  userProviders: Record<string, unknown> = providers,
+): SettingsNamespaceView {
+  return {
+    ns: 'llm-pi-ai',
+    schema: JSON.parse(JSON.stringify(PiAiConfig.toJSON())) as unknown,
+    // `value` is the effective section; `user` is only the layer this page
+    // writes. They differ whenever a composition `base` supplies something.
+    value: { providers },
+    base: {},
+    user: { providers: userProviders },
+    applies: 'live',
+    secrets: [],
+    revision: 3,
+  }
+}
+
+function scriptedFace(options: {
+  providers?: Record<string, unknown>
+  /** User layer, when it differs from the effective section. */
+  userProviders?: Record<string, unknown>
+  discover?: ReturnType<typeof vi.fn>
+  mutate?: ReturnType<typeof vi.fn>
+  set?: ReturnType<typeof vi.fn>
+} = {}) {
+  const providers = options.providers ?? {
+    openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy.example/v1' },
+  }
+  const namespace = piAiNamespace(providers, options.userProviders ?? providers)
+  const discover = options.discover ?? vi.fn(() => Promise.resolve(ok({ models: [] })))
+  const mutate = options.mutate ?? vi.fn(() => Promise.resolve(ok(namespace)))
+  const set = options.set ?? vi.fn(() => Promise.resolve(ok({})))
+  const face = {
+    llm: {
+      providers: vi.fn(() => Promise.resolve(ok({
+        providers: Object.keys(providers).map(provider => ({
+          provider,
+          displayName: provider,
+          settingsNs: 'llm-pi-ai',
+          settingsPath: ['providers', provider],
+          active: true,
+        })),
+      }))),
+      models: vi.fn(() => Promise.resolve(ok({ groups: [], failures: [] }))),
+      discoverModels: discover,
+    },
+    settings: {
+      describe: vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: [namespace] }))),
+      update: vi.fn(),
+      replace: vi.fn(),
+      mutate,
+    },
+    credentials: {
+      describe: vi.fn((payload: { refs: string[] }) => Promise.resolve(ok({
+        credentials: Object.fromEntries(payload.refs.map(ref => [ref, { configured: false, writable: true }])),
+      }))),
+      set,
+      unset: vi.fn(),
+    },
+  }
+  return { face, discover, mutate, set, namespace }
+}
+
+type WireFace = ConstructorParameters<typeof ModelsSettingsStore>[0]
+
+/** The settings write one card produced, as the scripted face recorded it. */
+interface MutateCall {
+  ns: string
+  expectedRevision?: number
+  ops: { op: string; path: string[]; value?: unknown }[]
+}
+
+/** The first interrogation payload; fails the case when nothing was asked. */
+function firstProbe(discover: ReturnType<typeof vi.fn>): unknown {
+  const call = (discover.mock.calls as unknown as [unknown][])[0]?.[0]
+  if (call === undefined) throw new Error('no interrogation was recorded')
+  return call
+}
+
+/** The first recorded settings write; fails the case when nothing was written. */
+function firstMutate(mutate: ReturnType<typeof vi.fn>): MutateCall {
+  const call = mutate.mock.calls[0]?.[0] as MutateCall | undefined
+  if (call === undefined) throw new Error('no settings write was recorded')
+  return call
+}
+
+async function mountSection(options: Parameters<typeof scriptedFace>[0] = {}) {
+  const scripted = scriptedFace(options)
+  const controller = new ModelsSettingsStore(scripted.face as unknown as WireFace)
+  await controller.load()
+  const injected: ModelsSectionInjected = {
+    controller,
+    useSnapshot: bindSnapshotSelector(controller.store),
+    api: scripted.face as never,
+    t,
+  }
+  render(<ModelsSection {...injected} />)
+  return scripted
+}
+
+/** Open the editor of one configured row and expand its customized fold. */
+function openEditor(provider: string): void {
+  const row = screen.getByText(provider).closest('li')
+  if (row === null) throw new Error(`no row for ${provider}`)
+  fireEvent.click(within_(row, en.edit))
+  const summary = document.querySelector('summary')
+  if (summary === null) throw new Error('no customized fold')
+  fireEvent.click(summary)
+}
+
+/** Open one model row's advanced fold, where the capacities live. */
+function expandModel(index: number): void {
+  fireEvent.click(screen.getByLabelText(`${en.modelAdvanced} ${index}`))
+}
+
+/** The button carrying `label`, typed so its disabled/title state is readable. */
+function buttonNamed(label: string): HTMLButtonElement {
+  const found = screen.getByText(label)
+  if (!(found instanceof HTMLButtonElement)) throw new Error(`"${label}" is not a button`)
+  return found
+}
+
+/** Click the button with `label` inside `scope`. */
+function within_(scope: HTMLElement, label: string): HTMLElement {
+  const found = [...scope.querySelectorAll('button')].find(button => button.textContent === label)
+  if (found === undefined) throw new Error(`no "${label}" button`)
+  return found
+}
+
+describe('protocolChoices', () => {
+  it('reads the protocols out of the namespace schema and nothing else', async () => {
+    const { namespace } = scriptedFace()
+    expect(protocolChoices(namespace)).toEqual(PROTOCOLS)
+    expect(protocolChoices(undefined)).toEqual([])
+    const plain = { ...namespace, schema: JSON.parse(JSON.stringify(Schema.object({}).toJSON())) as unknown }
+    expect(protocolChoices(plain)).toEqual([])
+    await Promise.resolve()
+  })
+})
+
+describe('model list editing', () => {
+  it('adds, edits, and removes rows without storing emptied optional fields', async () => {
+    const { mutate } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    expandModel(1)
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 1`), { target: { value: '65536' } })
+    fireEvent.change(screen.getByLabelText(`${en.modelName} 1`), { target: { value: 'Acme' } })
+    // Clearing an optional field must drop it rather than store an empty value.
+    fireEvent.change(screen.getByLabelText(`${en.modelName} 1`), { target: { value: '' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    expect(firstMutate(mutate)).toMatchObject({
+      ns: 'llm-pi-ai',
+      expectedRevision: 3,
+      ops: [{ op: 'set', path: ['providers', 'openai', 'models'], value: [{ id: 'acme-large', contextWindow: 65_536 }] }],
+    })
+  })
+
+  it('names a duplicate model id in the edit flow too', async () => {
+    const { mutate } = await mountSection({
+      providers: { openai: { baseURL: 'https://proxy.example/v1', models: [{ id: 'dup' }] } },
+    })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 2`), { target: { value: 'dup' } })
+
+    // The create card refuses this in place; an edited route must not have to
+    // learn it from the host's refusal instead.
+    expect(screen.getByText(`${en.model} 2: ${en.modelIdDuplicate}`)).toBeTruthy()
+    expect(buttonNamed(en.apply).disabled).toBe(true)
+    expect(mutate).not.toHaveBeenCalled()
+  })
+
+  it('reads K and M suffixes and keeps the text the user typed', async () => {
+    const { mutate } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    expandModel(1)
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 1`), { target: { value: '1M' } })
+    fireEvent.change(screen.getByLabelText(`${en.modelMaxTokens} 1`), { target: { value: '32K' } })
+
+    // The field keeps the spelling rather than snapping to the expansion, and
+    // a plain count is not rewritten into a suffix mid-word either.
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelContextWindow} 1`).value).toBe('1M')
+    fireEvent.change(screen.getByLabelText(`${en.modelMaxTokens} 1`), { target: { value: '1000' } })
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelMaxTokens} 1`).value).toBe('1000')
+
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    // What lands in settings is always a plain token count.
+    expect(firstMutate(mutate).ops[0]?.value)
+      .toEqual([{ id: 'm', contextWindow: 1_000_000, maxTokens: 1000 }])
+  })
+
+  it('refuses to apply while a capacity is unreadable', async () => {
+    const { mutate } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    expandModel(1)
+    fireEvent.change(screen.getByLabelText(`${en.modelMaxTokens} 1`), { target: { value: 'abc' } })
+
+    // Silently dropping it would store a route sized differently from what the
+    // field shows, so the text stays put and the write is refused instead.
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelMaxTokens} 1`).value).toBe('abc')
+    expect(screen.getByText(`${en.model} 1: ${en.modelMaxTokensInvalid}`)).toBeTruthy()
+    expect(buttonNamed(en.apply).disabled).toBe(true)
+    expect(mutate).not.toHaveBeenCalled()
+  })
+
+  it('spells a stored capacity back the way it is typed', async () => {
+    await mountSection({
+      providers: {
+        openai: {
+          baseURL: 'https://proxy.example/v1',
+          models: [{ id: 'kept', contextWindow: 1_000_000, maxTokens: 256_000 }],
+        },
+      },
+    })
+    openEditor('openai')
+    expandModel(1)
+
+    // Opening a row reads the stored counts, which are plain integers; showing
+    // them as such would make an already-configured route look unlike one the
+    // user just typed, and re-applying would rewrite the field it read.
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelContextWindow} 1`).value).toBe('1M')
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelMaxTokens} 1`).value).toBe('256K')
+  })
+
+  it('edits one row of several and lets a cleared capacity leave the profile', async () => {
+    const { mutate } = await mountSection({
+      providers: { openai: { baseURL: 'https://proxy.example/v1', models: [{ id: 'first' }, { id: 'second' }] } },
+    })
+    openEditor('openai')
+
+    expandModel(2)
+    fireEvent.change(screen.getByLabelText(`${en.modelMaxTokens} 2`), { target: { value: '2048' } })
+    fireEvent.change(screen.getByLabelText(`${en.modelName} 2`), { target: { value: 'Second' } })
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 2`), { target: { value: '4096' } })
+    // Clearing it back to empty must drop the field, not store a zero.
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 2`), { target: { value: '' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    expect(firstMutate(mutate).ops[0]?.value).toEqual([
+      { id: 'first' },
+      { id: 'second', name: 'Second', maxTokens: 2048 },
+    ])
+  })
+
+  it('shows the adapter defaults as inherited until an edit takes them over', async () => {
+    await mountSection({ providers: { openai: { baseURL: 'https://proxy.example/v1' } } })
+    openEditor('openai')
+
+    // The user layer names no models, so the list belongs to the adapter and
+    // says so; taking it over is an explicit act, not a side effect of opening.
+    expect(screen.getByText(en.modelsInherited)).toBeTruthy()
+    expect(screen.queryByText(en.resetModels)).toBeNull()
+  })
+
+
+  it('keeps expansion on the row it belongs to after an earlier one is removed', async () => {
+    await mountSection({
+      providers: {
+        openai: {
+          baseURL: 'https://proxy.example/v1',
+          models: [{ id: 'first' }, { id: 'second' }, { id: 'third' }],
+        },
+      },
+    })
+    openEditor('openai')
+
+    // Expansion is keyed by position, so removing an earlier row shifts the
+    // rest down; without reindexing, row 3 would inherit row 2's open state.
+    expandModel(2)
+    fireEvent.click(screen.getByLabelText(`${en.removeModel} 1`))
+
+    // 'second' now sits at position 1 and keeps its capacities open; 'third'
+    // moved to position 2 and stays folded.
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelId} 1`).value).toBe('second')
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 1`)).not.toBeNull()
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 2`)).toBeNull()
+  })
+
+  it('leaves an earlier row expanded and forgets the removed row\u2019s own state', async () => {
+    await mountSection({
+      providers: {
+        openai: {
+          baseURL: 'https://proxy.example/v1',
+          models: [{ id: 'first' }, { id: 'second' }, { id: 'third' }],
+        },
+      },
+    })
+    openEditor('openai')
+
+    // A row before the removal keeps its own position and stays open.
+    expandModel(1)
+    fireEvent.click(screen.getByLabelText(`${en.removeModel} 2`))
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelId} 1`).value).toBe('first')
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 1`)).not.toBeNull()
+
+    // Removing the expanded row itself drops that state rather than handing it
+    // to whichever row slides into the position.
+    fireEvent.click(screen.getByLabelText(`${en.removeModel} 1`))
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelId} 1`).value).toBe('third')
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 1`)).toBeNull()
+  })
+
+  it('separates emptying the list from restoring the adapter defaults', async () => {
+    const { mutate } = await mountSection({
+      providers: { openai: { baseURL: 'https://proxy.example/v1', models: [{ id: 'kept' }] } },
+    })
+    openEditor('openai')
+
+    // An empty override is a route that serves no models — a different intent
+    // from handing the catalog back, which is what the reset affordance does.
+    expect(screen.getByText(en.modelsCustomized)).toBeTruthy()
+    fireEvent.click(screen.getByText(en.resetModels))
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    expect(firstMutate(mutate).ops)
+      .toContainEqual({ op: 'unset', path: ['providers', 'openai', 'models'] })
+  })
+
+})
+
+describe('capacity spellings', () => {
+  it.each([
+    ['', undefined],
+    ['65536', 65_536],
+    ['256K', 256_000],
+    ['1m', 1_000_000],
+    // A decimal multiple is exact in intent but not in binary floating point,
+    // so an integral result snaps back instead of landing a few ULPs high.
+    ['2.3M', 2_300_000],
+    // Not an integral count: kept as written rather than silently rounded.
+    ['1.0005K', 1000.5],
+  ])('reads %j as %j', (text, expected) => {
+    expect(parseCapacity(text)).toBe(expected)
+  })
+
+  it.each(['abc', '12x', '1 000', '-5', ''])('refuses %j rather than guessing', (text) => {
+    const parsed = parseCapacity(text)
+    expect(parsed === undefined || Number.isNaN(parsed)).toBe(true)
+  })
+
+  it.each([
+    [1_000_000, '1M'],
+    [256_000, '256K'],
+    [65_536, '65536'],
+    // Never a spelling that would not survive being read back.
+    [0, '0'],
+    [1.5, '1.5'],
+  ])('spells %j as %j', (value, expected) => {
+    expect(formatCapacity(value)).toBe(expected)
+  })
+
+  it('round-trips every spelling it produces', () => {
+    for (const value of [1_000_000, 256_000, 65_536, 4096, 1000]) {
+      expect(parseCapacity(formatCapacity(value))).toBe(value)
+    }
+  })
+})
+
+describe('endpoint interrogation', () => {
+  it('asks the endpoint the form shows, with a key that is not yet stored', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({ models: [{ id: 'acme-large', contextWindow: 65_536 }] })))
+    await mountSection({ discover })
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'typed-not-saved' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://edited.example/v1' } })
+    fireEvent.click(screen.getByText(en.fetchModels))
+
+    await waitFor(() => { expect(discover).toHaveBeenCalled() })
+    expect(firstProbe(discover)).toEqual({
+      settingsNs: 'llm-pi-ai',
+      // The route is named, so an adapter that already describes it answers
+      // from its own registry rather than the endpoint.
+      provider: 'openai',
+      baseURL: 'https://edited.example/v1',
+      apiKey: 'typed-not-saved',
+    })
+  })
+
+  it('carries the protocol the profile already names', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({ models: [] })))
+    await mountSection({
+      discover,
+      providers: { openai: { baseURL: 'https://proxy.example/v1', api: 'openai-responses' } },
+    })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByText(en.fetchModels))
+
+    await waitFor(() => { expect(discover).toHaveBeenCalled() })
+    expect(firstProbe(discover)).toEqual({
+      settingsNs: 'llm-pi-ai',
+      provider: 'openai',
+      baseURL: 'https://proxy.example/v1',
+      api: 'openai-responses',
+    })
+  })
+
+  it('adopts only the picked candidates, keeping a row the user already tuned', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({
+      models: [{ id: 'kept', contextWindow: 999 }, { id: 'fresh', contextWindow: 4096, name: 'Fresh' }],
+    })))
+    const { mutate } = await mountSection({
+      discover,
+      providers: { openai: { baseURL: 'https://proxy.example/v1', models: [{ id: 'kept', contextWindow: 111 }] } },
+    })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByText(en.fetchModels))
+    await screen.findByText(en.fetchTitle)
+    // The already-configured row starts unchecked; the new one starts checked.
+    const boxes = [...document.querySelectorAll<HTMLInputElement>('input[type="checkbox"]')]
+    expect(boxes.map(box => box.checked)).toEqual([false, true])
+    fireEvent.click(screen.getByText(en.fetchAdopt))
+
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    expect(firstMutate(mutate).ops[0]?.value).toEqual([
+      { id: 'kept', contextWindow: 111 },
+      { id: 'fresh', contextWindow: 4096, name: 'Fresh' },
+    ])
+  })
+
+  it('keeps the rows editable when the provider cannot be interrogated', async () => {
+    const discover = vi.fn(() => Promise.resolve(
+      fail('https://proxy.example/v1/models answered 401; check the API key', 'model-discovery-failed'),
+    ))
+    await mountSection({ discover })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByText(en.fetchModels))
+
+    await screen.findByText(/answered 401; check the API key/)
+    // The failure is a detour, not a dead end: hand-entry is still offered.
+    expect(screen.getByRole('button', { name: en.addModel })).toBeTruthy()
+  })
+
+  it('reports an empty listing and a rejected transport', async () => {
+    const empty = vi.fn(() => Promise.resolve(ok({ models: [] })))
+    await mountSection({ discover: empty })
+    openEditor('openai')
+    fireEvent.click(screen.getByText(en.fetchModels))
+    await screen.findByText(en.fetchEmpty)
+    cleanup()
+
+    const rejected = vi.fn(() => Promise.reject(new Error('carrier down')))
+    await mountSection({ discover: rejected })
+    openEditor('openai')
+    fireEvent.click(screen.getByText(en.fetchModels))
+    await screen.findByText('carrier down')
+  })
+
+  it('can be asked for a configured route even with no endpoint', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({ models: [{ id: 'from-registry' }] })))
+    await mountSection({ discover, providers: { openai: {} } })
+    openEditor('openai')
+
+    // A route the adapter already describes needs no endpoint at all.
+    expect(buttonNamed(en.fetchModels).disabled).toBe(false)
+    fireEvent.click(screen.getByText(en.fetchModels))
+
+    await waitFor(() => { expect(discover).toHaveBeenCalled() })
+    expect(firstProbe(discover)).toEqual({ settingsNs: 'llm-pi-ai', provider: 'openai' })
+  })
+
+  it('keeps the create card asking only once it has an endpoint', () => {
+    // A provider being declared has no route yet, so the endpoint is the only
+    // thing an interrogation could go on.
+    const scripted = scriptedFace()
+    render(
+      <CustomProviderCard
+        taken={[]} protocols={PROTOCOLS} revision={7} api={scripted.face as never}
+        t={t} readOnly={false} onClose={vi.fn()}
+      />,
+    )
+    expect(buttonNamed(en.fetchModels).disabled).toBe(true)
+    expect(buttonNamed(en.fetchModels).title).toBe(en.fetchNeedsBaseUrl)
+
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    expect(buttonNamed(en.fetchModels).disabled).toBe(false)
+    fireEvent.click(screen.getByText(en.fetchModels))
+
+    // A provider being declared names no route, so only the endpoint travels.
+    expect(firstProbe(scripted.discover)).toEqual({
+      settingsNs: 'llm-pi-ai',
+      baseURL: 'https://acme.test/v1',
+      api: 'openai-completions',
+    })
+  })
+
+  it('folds a row\u2019s capacities away until they are asked for', async () => {
+    await mountSection({
+      providers: { openai: { baseURL: 'https://proxy.example/v1', models: [{ id: 'only' }] } },
+    })
+    openEditor('openai')
+
+    // The row shows what identifies a model; capacities are the exception.
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 1`)).toBeNull()
+    expandModel(1)
+    expect(screen.getByLabelText(`${en.modelContextWindow} 1`)).toBeTruthy()
+    expandModel(1)
+    expect(screen.queryByLabelText(`${en.modelContextWindow} 1`)).toBeNull()
+  })
+
+  it('closes the picker without adopting anything on cancel', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({ models: [{ id: 'fresh' }] })))
+    const { mutate } = await mountSection({ discover })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByText(en.fetchModels))
+    const dialog = await screen.findByRole('dialog')
+    // The editor card carries a Cancel of its own; this one is the dialog's.
+    fireEvent.click(within_(dialog, en.cancel))
+
+    await waitFor(() => { expect(screen.queryByText(en.fetchTitle)).toBeNull() })
+    expect(mutate).not.toHaveBeenCalled()
+  })
+
+  it('toggles a candidate off and back on before adopting', async () => {
+    const discover = vi.fn(() => Promise.resolve(ok({
+      models: [{ id: 'a' }, { id: 'b', maxTokens: 2048 }],
+    })))
+    const { mutate } = await mountSection({ discover })
+    openEditor('openai')
+
+    fireEvent.click(screen.getByText(en.fetchModels))
+    await screen.findByText(en.fetchTitle)
+    const boxes = [...document.querySelectorAll<HTMLInputElement>('input[type="checkbox"]')]
+    const first = boxes[0] as HTMLInputElement
+    fireEvent.click(first)
+    fireEvent.click(first)
+    fireEvent.click(screen.getByText(en.fetchAdopt))
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    // A disclosed output cap rides along with the candidate that has one.
+    expect(firstMutate(mutate).ops[0]?.value).toEqual([{ id: 'a' }, { id: 'b', maxTokens: 2048 }])
+  })
+})
+
+describe('hand-declared providers', () => {
+  function mountCard(overrides: Partial<Parameters<typeof CustomProviderCard>[0]> = {}) {
+    const scripted = scriptedFace()
+    const onClose = vi.fn()
+    render(
+      <CustomProviderCard
+        taken={['openai']}
+        protocols={PROTOCOLS}
+        revision={7}
+        api={scripted.face as never}
+        t={t}
+        readOnly={false}
+        onClose={onClose}
+        {...overrides}
+      />,
+    )
+    return { ...scripted, onClose }
+  }
+
+  it('writes the whole profile and the key under the derived reference', async () => {
+    const { mutate, set, onClose } = mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme-gateway' } })
+    fireEvent.change(screen.getByLabelText(en.customDisplayName), { target: { value: 'Acme Gateway' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://gateway.acme.example/v1' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'gw-key' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    expandModel(1)
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 1`), { target: { value: '65536' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    expect(firstMutate(mutate)).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{
+        op: 'set',
+        path: ['providers', 'acme-gateway'],
+        value: {
+          displayName: 'Acme Gateway',
+          apiKeyEnv: 'ACME_GATEWAY_API_KEY',
+          api: 'openai-completions',
+          baseURL: 'https://gateway.acme.example/v1',
+          models: [{ id: 'acme-large', contextWindow: 65_536 }],
+        },
+      }],
+      // The section this card was drafted over: a route another tab declared
+      // meanwhile makes this a conflict rather than an overwrite.
+      expectedRevision: 7,
+    })
+    expect(set).toHaveBeenCalledWith({ ref: 'ACME_GATEWAY_API_KEY', value: 'gw-key' })
+  })
+
+  it('names the blocked gate under the form, and nothing once it is satisfied', () => {
+    mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+
+    // Endpoint first: the gate names the one thing standing in the way.
+    expect(screen.getByText(en.customNeedsBaseUrl)).toBeTruthy()
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    expect(screen.getByText(en.customNeedsModels)).toBeTruthy()
+
+    // Satisfied: the shared line disappears rather than rendering empty.
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    expect(screen.queryByText(en.customNeedsBaseUrl)).toBeNull()
+    expect(screen.queryByText(en.customNeedsModels)).toBeNull()
+    expect(buttonNamed(en.create).disabled).toBe(false)
+  })
+
+  it('refuses to create while a capacity is unreadable', () => {
+    mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    expandModel(1)
+    fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} 1`), { target: { value: '64 KiB' } })
+
+    expect(screen.getByText(`${en.model} 1: ${en.modelContextInvalid}`)).toBeTruthy()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+  })
+
+  it('keeps each half-typed capacity with its own row across a removal', () => {
+    mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    for (const [at, id] of [[1, 'first'], [2, 'second'], [3, 'third']] as const) {
+      fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+      fireEvent.change(screen.getByLabelText(`${en.modelId} ${String(at)}`), { target: { value: id } })
+      expandModel(at)
+      // Deliberately mid-word: the buffer exists so text like this survives.
+      fireEvent.change(screen.getByLabelText(`${en.modelContextWindow} ${String(at)}`),
+        { target: { value: `${String(at)}.` } })
+    }
+
+    // Removing the middle row: the one before keeps its position and text, the
+    // one after moves down carrying its own, and the removed row's text goes.
+    fireEvent.click(screen.getByLabelText(`${en.removeModel} 2`))
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelId} 1`).value).toBe('first')
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelContextWindow} 1`).value).toBe('1.')
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelId} 2`).value).toBe('third')
+    expect(screen.getByLabelText<HTMLInputElement>(`${en.modelContextWindow} 2`).value).toBe('3.')
+  })
+
+  it('refuses two models sharing one id', () => {
+    mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'same' } })
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 2`), { target: { value: 'same' } })
+
+    // The adapter refuses a duplicate outright, so the form must not offer to
+    // write one.
+    expect(screen.getByText(`${en.model} 2: ${en.modelIdDuplicate}`)).toBeTruthy()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 2`), { target: { value: 'other' } })
+    expect(buttonNamed(en.create).disabled).toBe(false)
+  })
+
+  it('creates a model with no capacities, which the route\u2019s fallbacks size', async () => {
+    const { mutate, onClose } = mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'bare' } })
+
+    // A listing that discloses nothing but ids is enough to create a working
+    // provider; the adapter sizes what configuration leaves out.
+    expect(buttonNamed(en.create).disabled).toBe(false)
+    fireEvent.click(screen.getByText(en.create))
+
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    expect(firstMutate(mutate).ops[0]?.value).toMatchObject({ models: [{ id: 'bare' }] })
+  })
+
+  it('refuses to create until the route, endpoint, and a model are usable', () => {
+    mountCard()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'Acme Gateway' } })
+    expect(screen.getByText(en.customRouteInvalid)).toBeTruthy()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'openai' } })
+    expect(screen.getByText(en.customRouteTaken)).toBeTruthy()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    expect(screen.getByText(en.customNeedsBaseUrl)).toBeTruthy()
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    expect(screen.getByText(en.customNeedsModels)).toBeTruthy()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+
+    // A model row with no id is not a model.
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    expect(buttonNamed(en.create).disabled).toBe(true)
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    expect(buttonNamed(en.create).disabled).toBe(false)
+  })
+
+  it('surfaces a refused write and a rejected transport without closing', async () => {
+    const refused = vi.fn(() => Promise.resolve(fail('read-only settings', 'settings-rejected')))
+    const { onClose } = mountCard({ api: { ...scriptedFace({ mutate: refused }).face } as never })
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await screen.findByText('read-only settings')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('surfaces a rejected transport during create', async () => {
+    const rejecting = vi.fn(() => Promise.reject(new Error('carrier down')))
+    const { onClose } = mountCard({ api: { ...scriptedFace({ mutate: rejecting }).face } as never })
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await screen.findByText('carrier down')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('reports a stored profile whose key write was refused', async () => {
+    const set = vi.fn(() => Promise.resolve(fail('credential is read-only', 'credential-rejected')))
+    const { onClose } = mountCard({ api: { ...scriptedFace({ set }).face } as never })
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'k' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await screen.findByText('credential is read-only')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('creates with the chosen protocol and no display name', async () => {
+    const { mutate, onClose } = mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.change(screen.getByLabelText(en.customApi), { target: { value: 'anthropic-messages' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    // No display name configured means none stored; the route id is the name.
+    expect(firstMutate(mutate).ops[0]?.value).toEqual({
+      apiKeyEnv: 'ACME_API_KEY',
+      api: 'anthropic-messages',
+      baseURL: 'https://acme.test/v1',
+      models: [{ id: 'm' }],
+    })
+  })
+
+  it('offers no protocol when the namespace declares none', () => {
+    mountCard({ protocols: [] })
+    expect(screen.getByLabelText<HTMLSelectElement>(en.customApi).value).toBe('')
+  })
+
+  it('closes without writing on cancel, and honors a read-only deployment', () => {
+    const { onClose, mutate } = mountCard()
+    fireEvent.click(screen.getByText(en.cancel))
+    expect(onClose).toHaveBeenCalledWith(false)
+    expect(mutate).not.toHaveBeenCalled()
+    cleanup()
+
+    mountCard({ readOnly: true })
+    expect(screen.getByLabelText<HTMLInputElement>(en.customRoute).disabled).toBe(true)
+    expect(buttonNamed(en.create).disabled).toBe(true)
+  })
+
+  it('closes the create card when an existing row is opened for editing', async () => {
+    await mountSection({ providers: { openai: { baseURL: 'https://proxy.example/v1' } } })
+
+    fireEvent.click(screen.getByRole('button', { name: en.customAdd }))
+    expect(screen.getByText(en.customTitle)).toBeTruthy()
+
+    // Two cards at once would each be closable by the other: whichever one is
+    // dismissed clears the shared state and discards the other's draft.
+    openEditor('openai')
+    expect(screen.queryByText(en.customTitle)).toBeNull()
+  })
+
+  it('reaches the card from the section and returns to the button on cancel', async () => {
+    await mountSection()
+
+    fireEvent.click(screen.getByRole('button', { name: en.customAdd }))
+    expect(screen.getByText(en.customTitle)).toBeTruthy()
+
+    fireEvent.click(screen.getByText(en.cancel))
+    await waitFor(() => { expect(screen.queryByText(en.customTitle)).toBeNull() })
+    expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy()
+  })
+})

packages/client/ui-models/tests/styles.spec.ts

@@ -1,12 +1,25 @@
-import { readFileSync } from 'node:fs'
+/**
+ * Models section stylesheet contract, asserted against the CSS text on disk.
+ *
+ * The section paints in both themes, and a `--dsw-*` name the theme does not
+ * declare fails silently: the browser takes the `var()` fallback, so the sheet
+ * still renders and only the dark theme looks wrong. Checking the names against
+ * the sheet that declares them is what turns that into a test failure.
+ */
+import { readdirSync, readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 
 const css = readFileSync(fileURLToPath(new URL('../src/client/ModelsSection.module.css', import.meta.url)), 'utf8')
-const tokens = readFileSync(
-  fileURLToPath(new URL('../../ui-theme/src/styles/design-platform.css', import.meta.url)),
-  'utf8',
-)
+// The theme package maps `./styles/*` to `./src/styles/*`, so the declarations
+// stay on the source plane rather than needing a build.
+// Every theme sheet, not just the platform tokens: font and scrollbar
+// variables are declared in siblings, and a gate reading one file would call
+// their names undeclared.
+const tokens = readdirSync(fileURLToPath(new URL('../../ui-theme/src/styles/', import.meta.url)))
+  .filter(name => name.endsWith('.css'))
+  .map(name => readFileSync(fileURLToPath(new URL(`../../ui-theme/src/styles/${name}`, import.meta.url)), 'utf8'))
+  .join('\n')
 
 /** The declarations of one top-level rule, by selector. */
 function block(selector: string): string {
@@ -21,12 +34,24 @@ describe('ModelsSection theme styles', () => {
     // resolves to whatever literal sits in its fallback slot, which is how this
     // section stayed light under the dark theme before. Undeclared names have
     // no fallback at all and inherit, so both spellings must fail here.
-    const named = [...css.matchAll(/var\((--dsw-[a-z0-9-]+)/g)].map(match => match[1])
+    // Every theme-variable prefix the sheets actually use, not just `--dsw-`:
+    // a `--dsh-` name reads as a plausible sibling and would otherwise slip
+    // past this gate into a fallback literal.
+    const named = [...css.matchAll(/var\((--(?:dsw|dsh|ds)-[a-z0-9-]+)/g)].map(match => match[1])
     const undeclared = [...new Set(named)].filter(name => !tokens.includes(`  ${String(name)}:`))
     expect(undeclared).toEqual([])
     expect(css).not.toMatch(/var\(--(?:surface|text-|border|accent-strong)/)
   })
 
+  it('closes every block, so no rule is swallowed by the one above it', () => {
+    // A missing `}` on an `@media` block is not a parse error: every rule after
+    // it silently becomes conditional, and the whole fetch dialog once painted
+    // unstyled for anyone whose system does not ask for reduced motion. Nothing
+    // downstream reports this — the sheet loads and the classes still attach.
+    const bare = css.replace(/\/\*[\s\S]*?\*\//g, '')
+    expect((bare.match(/\}/g) ?? []).length).toBe((bare.match(/\{/g) ?? []).length)
+  })
+
   it('separates the row card from the editor it expands into', () => {
     // `bg-layer-3` and `bg-module-platform` both resolve to neutral-bluish-800
     // under the dark theme, so filling the row with either erases the nested
@@ -35,4 +60,10 @@ describe('ModelsSection theme styles', () => {
     expect(block('.rowCard')).toContain('border: 1px solid var(--dsw-alias-border-l2)')
     expect(block('.rowCard')).not.toMatch(/\bbackground\s*:/)
   })
+
+  it('never falls back to a literal colour', () => {
+    // A token that resolves is never the problem; an undeclared one takes this
+    // branch, and a literal here is a single colour for both themes.
+    expect(css).not.toMatch(/var\(--dsw-[a-z0-9-]+\s*,\s*(?:#|rgb|rgba|hsl|hsla)/)
+  })
 })

packages/client/ui-primitives/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
-README.md: 03e7e3649fd0913fb48579aa87634153f67f5baf
-README.zh.md: 090ecc34e8d514e38853de8ed52e82d3bf019b43
+README.md: 385730c94831d2fd4af83f9eca0f55941551c796
+README.zh.md: b8a75dbffc6549f6294dfda5988c67d6569386c9

packages/client/ui-primitives/README.md

@@ -10,7 +10,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 ## Markdown rendering
 
-`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
+`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
 
 ## Terminal output
 
@@ -42,6 +42,7 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
+- **Streaming defers cross-boundary reference resolution** — a reference-style link or footnote whose definition sits on the other side of the incremental freeze boundary renders as literal text while the reply streams; the settled full parse at finalize resolves it. Inline links and references resolved within one parse are unaffected.
 - **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
 - **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
 - **No `Active` StateDot variant** — the supported states are done, warning, ongoing, and error.

packages/client/ui-primitives/README.zh.md

@@ -10,7 +10,7 @@
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
@@ -42,6 +42,7 @@
 
 ## 已知限制与暂缓事项
 
+- **流式期间跨边界引用解析被推迟**：定义落在增量冻结边界另一侧的引用式链接或脚注，在回复流式输出期间渲染为字面文本；定稿时的全量解析会将其解析。内联链接以及在同一次解析内完成解析的引用不受影响。
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 没有 `Active` 变体**：支持的状态为 done、warning、ongoing 和 error。

packages/client/ui-primitives/package.json

@@ -21,23 +21,24 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@shikijs/langs": "^4.3.1",
+    "@types/mdast": "^4.0.4",
     "anser": "^2.3.5",
     "clsx": "^2.0.0",
     "katex": "^0.16.47",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "micromark-core-commonmark": "^2.0.3",
     "micromark-extension-gfm": "^3.0.0",
     "micromark-extension-math": "^3.1.0",
     "micromark-factory-space": "^2.0.1",
     "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-sanitize-uri": "^2.0.1",
     "micromark-util-symbol": "^2.0.1",
     "micromark-util-types": "^2.0.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "react-markdown": "^10.1.0",
-    "rehype-katex": "^7.0.1",
-    "remark-gfm": "^4.0.1",
-    "remark-math": "^6.0.0",
     "shiki": "^4.3.1"
   },
   "devDependencies": {

packages/client/ui-primitives/src/markdown/MarkdownText.tsx

@@ -1,155 +1,164 @@
-import { isValidElement, useMemo } from 'react'
-import ReactMarkdown from 'react-markdown'
-import type { Components, UrlTransform } from 'react-markdown'
-import rehypeKatex from 'rehype-katex'
-import remarkGfm from 'remark-gfm'
-import remarkMath from 'remark-math'
-import { CodeBlock } from './CodeBlock.tsx'
-import { remarkMathCompatibility } from './remarkMathCompatibility.ts'
+/**
+ * Untrusted assistant-Markdown renderer over the direct mdast pipeline:
+ * `parse.ts` grammars, the incremental streaming parser, and `render.tsx`.
+ * While a message streams, all but the trailing two blocks freeze as cached
+ * React elements and only the source tail behind them re-parses per chunk,
+ * so per-chunk work tracks the tail size instead of the whole reply. Frozen
+ * blocks keep their source-offset keys when they cross the freeze boundary,
+ * so React reconciles instead of remounting. Known deviation while
+ * streaming: a reference-style link or footnote whose definition sits on the
+ * other side of the freeze boundary renders literally until the settled
+ * full parse self-heals it.
+ */
+
+import { memo, useMemo, useRef } from 'react'
+import type { ReactNode } from 'react'
+import { IncrementalMarkdownParser } from './incremental.ts'
+import { parseGfm, parseGfmWithMath } from './parse.ts'
+import {
+  collectReferenceTargets, createReferenceTargets, renderBlocks, renderFootnoteSection,
+  wrapBlockChildren,
+} from './render.tsx'
+import type { MarkdownCodeLabels, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
 import 'katex/dist/katex.min.css'
 import css from './MarkdownText.module.css'
 
-const streamingRemarkPlugins = [remarkGfm]
-const settledRemarkPlugins = [
-  remarkGfm,
-  remarkMathCompatibility,
-  remarkMath,
-]
-const settledRehypePlugins = [rehypeKatex]
+export type { MarkdownCodeLabels } from './render.tsx'
 
-function sanitizeUrl(url: string): string {
-  try {
-    switch (new URL(url).protocol) {
-      case 'http:':
-      case 'https:':
-      case 'mailto:':
-        return url
-      default:
-        return ''
+/** One settled full render: parse with math, resolve references, append the footnote section. */
+function renderSettled(text: string, codeLabels: MarkdownCodeLabels | undefined): ReactNode[] {
+  const root = parseGfmWithMath(text)
+  const targets = createReferenceTargets()
+  collectReferenceTargets(root.children, targets)
+  const context: MarkdownRenderContext = {
+    streaming: false,
+    codeLabels,
+    targets,
+    footnoteOrder: [],
+    footnoteCounts: new Map(),
+  }
+  const blocks = wrapBlockChildren(
+    renderBlocks(root.children.map((node, index) => ({ node, key: index })), context),
+    false,
+  )
+  const section = renderFootnoteSection(context)
+  return section === null ? blocks : [...blocks, '\n', section]
+}
+
+/**
+ * Streaming render state for one growing message: the incremental parser,
+ * the frozen blocks' cached elements, and the reference/footnote state their
+ * rendering consumed (footnote numbering assigned to frozen references is
+ * final, so the tail continues from a copy of it each frame).
+ */
+class StreamingRenderer {
+  private readonly parser = new IncrementalMarkdownParser(parseGfm)
+  private generation = -1
+  private frozenCount = 0
+  private frozenElements: ReactNode[] = []
+  private frozenTargets: ReferenceTargets = createReferenceTargets()
+  private frozenFootnoteOrder: string[] = []
+  private frozenFootnoteCounts = new Map<string, number>()
+  private lastText: string | null = null
+  private lastRendered: ReactNode[] = []
+
+  /** @param codeLabels - Fence copy labels baked into cached elements; the owner replaces the renderer when they change. */
+  constructor(private readonly codeLabels: MarkdownCodeLabels | undefined) {}
+
+  /**
+   * Render the current accumulated text. Idempotent per text value, so React
+   * may re-execute the calling render freely.
+   * @param text - The full accumulated markdown source.
+   * @returns Frozen elements, re-rendered tail, and the footnote section.
+   */
+  render(text: string): ReactNode[] {
+    if (text === this.lastText) return this.lastRendered
+    const { frozen, tail, generation } = this.parser.update(text)
+    if (generation !== this.generation) {
+      this.generation = generation
+      this.frozenCount = 0
+      this.frozenElements = []
+      this.frozenTargets = createReferenceTargets()
+      this.frozenFootnoteOrder = []
+      this.frozenFootnoteCounts = new Map()
     }
-  } catch {
-    return ''
+    const newlyFrozen = frozen.slice(this.frozenCount)
+    collectReferenceTargets(newlyFrozen.map(block => block.node), this.frozenTargets)
+    // Targets visible this frame: everything frozen so far plus the current
+    // tail parse — a newly frozen block's references resolved against the
+    // same parse tree its definitions came from.
+    const frameTargets: ReferenceTargets = {
+      definitions: new Map(this.frozenTargets.definitions),
+      footnotes: new Map(this.frozenTargets.footnotes),
+    }
+    collectReferenceTargets(tail.map(block => block.node), frameTargets)
+    if (newlyFrozen.length > 0) {
+      const frozenContext: MarkdownRenderContext = {
+        streaming: true,
+        codeLabels: this.codeLabels,
+        targets: frameTargets,
+        footnoteOrder: this.frozenFootnoteOrder,
+        footnoteCounts: this.frozenFootnoteCounts,
+      }
+      // Separator newlines are cached alongside the elements so the
+      // assembled children match the settled pipeline's block wrapping.
+      const batch = [...this.frozenElements]
+      for (const element of renderBlocks(newlyFrozen, frozenContext)) {
+        if (batch.length > 0) batch.push('\n')
+        batch.push(element)
+      }
+      this.frozenElements = batch
+      this.frozenCount = frozen.length
+    }
+    const tailContext: MarkdownRenderContext = {
+      streaming: true,
+      codeLabels: this.codeLabels,
+      targets: frameTargets,
+      footnoteOrder: [...this.frozenFootnoteOrder],
+      footnoteCounts: new Map(this.frozenFootnoteCounts),
+    }
+    const children = [...this.frozenElements]
+    for (const element of renderBlocks(tail, tailContext)) {
+      if (children.length > 0) children.push('\n')
+      children.push(element)
+    }
+    const section = renderFootnoteSection(tailContext)
+    if (section !== null) children.push('\n', section)
+    this.lastText = text
+    this.lastRendered = children
+    return this.lastRendered
   }
 }
 
-const safeUrl: UrlTransform = url => sanitizeUrl(url)
-
-/** Copy-button labels forwarded to fence CodeBlocks (this package is cordis-free, so copy arrives via props). */
-export interface MarkdownCodeLabels {
-  /** Copy-button idle label. */
-  copyLabel?: string | undefined
-  /** Copy-button label during the post-copy confirmation window. */
-  copiedLabel?: string | undefined
-}
-
-function remoteImageUrl(url: string): string | undefined {
-  try {
-    const protocol = new URL(url).protocol
-    return protocol === 'http:' || protocol === 'https:' ? url : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/** Build the component table; while `streaming`, fences render the plain arm (see CodeBlock). */
-function buildComponents(streaming: boolean, codeLabels?: MarkdownCodeLabels): Components {
-  return {
-    a: ({ href = '', children }) => {
-      const safeHref = sanitizeUrl(href)
-      if (safeHref === '') return <>{children}</>
-      const external = ['http:', 'https:'].includes(new URL(safeHref).protocol)
-      return (
-        <a
-          href={safeHref}
-          {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
-        >
-          {children}
-        </a>
-      )
-    },
-    img: ({ alt = '', src = '' }) => {
-      const imageSrc = remoteImageUrl(src)
-      if (imageSrc === undefined) return <span className={css.imageAlt}>{alt}</span>
-      return (
-        <img
-          className={css.image}
-          src={imageSrc}
-          alt={alt}
-          loading="lazy"
-          decoding="async"
-          referrerPolicy="no-referrer"
-        />
-      )
-    },
-    table: ({ children }) => (
-      <div className={css.tableScroll}>
-        <table>{children}</table>
-      </div>
-    ),
-    // Fenced blocks route through the shared CodeBlock (shiki for registered
-    // grammars, identical-geometry plain fallback for unknown/absent
-    // languages); inline code keeps the default <code> path (the :not(pre)
-    // rule styles it). While the message streams, the fence renders the
-    // plain arm — retokenizing a growing fence on every chunk is quadratic
-    // main-thread work; the finalize swap highlights it once.
-    pre: ({ children }) => {
-      // The markdown pipeline always hands `pre` its single `code` element;
-      // the undefined arm guards a react-markdown representation change.
-      /* v8 ignore next 2 */
-      const child = isValidElement<{ className?: string; children?: unknown }>(children) ? children : undefined
-      const raw = child?.props.children
-      // A fence whose content isn't one plain string (e.g. an empty fence)
-      // keeps the stock <pre> rather than guessing.
-      if (typeof raw !== 'string') return <pre>{children}</pre>
-      const lang = /language-([\w-]+)/.exec(child?.props.className ?? '')?.[1]
-      return (
-        <CodeBlock
-          code={raw}
-          lang={streaming ? undefined : lang}
-          copyLabel={codeLabels?.copyLabel}
-          copiedLabel={codeLabels?.copiedLabel}
-        />
-      )
-    },
-  }
-}
-
-const staticComponents = buildComponents(false)
-const streamingComponents = buildComponents(true)
-
 /**
  * Render untrusted assistant-authored Markdown as semantic React elements.
  * @param props - Markdown source text preserved by the session projection;
- * `streaming` renders fences and TeX plain (highlighting and KaTeX land on the finalize swap);
- * `codeLabels` forwards localized copy-button labels to fence CodeBlocks —
- * pass a reference-stable object (memoized per locale revision), because the
- * component table memoizes on its identity and a fresh literal per render
- * would rebuild it every streaming chunk.
+ * `streaming` renders fences and TeX plain (highlighting and KaTeX land on
+ * the finalize swap) and parses incrementally across chunks; `codeLabels`
+ * forwards localized copy-button labels to fence CodeBlocks — pass a
+ * reference-stable object (memoized per locale revision), because a new
+ * identity discards the streaming render cache mid-message.
  * @returns A GFM document with TeX math rendered through KaTeX; raw HTML,
  * relative links, and unsafe protocols are disabled, while absolute HTTP(S)
  * images render directly.
  */
-export function MarkdownText({ text, streaming = false, codeLabels }: {
+export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels }: {
   text: string
   streaming?: boolean
   codeLabels?: MarkdownCodeLabels | undefined
 }) {
-  // The label-free tables stay module-level singletons so the common case
-  // keeps referential stability across renders without a hook.
-  const components = useMemo(() => {
-    if (codeLabels === undefined) return streaming ? streamingComponents : staticComponents
-    return buildComponents(streaming, codeLabels)
-  }, [streaming, codeLabels])
-  return (
-    <div className={css.markdown}>
-      <ReactMarkdown
-        remarkPlugins={streaming ? streamingRemarkPlugins : settledRemarkPlugins}
-        rehypePlugins={streaming ? undefined : settledRehypePlugins}
-        components={components}
-        urlTransform={safeUrl}
-      >
-        {text}
-      </ReactMarkdown>
-    </div>
-  )
-}
+  const streamRef = useRef<StreamingRenderer | null>(null)
+  const streamLabelsRef = useRef<MarkdownCodeLabels | undefined>(codeLabels)
+  const children = useMemo(() => {
+    if (!streaming) {
+      streamRef.current = null
+      return renderSettled(text, codeLabels)
+    }
+    if (streamRef.current === null || streamLabelsRef.current !== codeLabels) {
+      streamRef.current = new StreamingRenderer(codeLabels)
+      streamLabelsRef.current = codeLabels
+    }
+    return streamRef.current.render(text)
+  }, [text, streaming, codeLabels])
+  return <div className={css.markdown}>{children}</div>
+})

packages/client/ui-primitives/src/markdown/cjkFriendlyStrong.ts

@@ -0,0 +1,83 @@
+/** Let asterisk strong emphasis close after punctuation when CJK prose continues without whitespace. */
+
+import { attention } from 'micromark-core-commonmark'
+import { unicodePunctuation } from 'micromark-util-character'
+import { classifyCharacter } from 'micromark-util-classify-character'
+import { codes, constants } from 'micromark-util-symbol'
+import type { Construct, Extension, State, Tokenizer } from 'micromark-util-types'
+
+const cjkCharacter = new RegExp([
+  '\\p{Script_Extensions=Han}',
+  '\\p{Script_Extensions=Hiragana}',
+  '\\p{Script_Extensions=Katakana}',
+  '\\p{Script_Extensions=Hangul}',
+  '\\p{Script_Extensions=Bopomofo}',
+].join('|'), 'u')
+
+function isCjkCharacter(code: number | null): boolean {
+  return code !== null && code >= 0 && cjkCharacter.test(String.fromCodePoint(code))
+}
+
+const tokenizeCjkFriendlyAttention: Tokenizer = function (effects, ok, nok) {
+  const configuredAttentionMarkers = this.parser.constructs.attentionMarkers.null
+  if (configuredAttentionMarkers === undefined) {
+    throw new Error('micromark CommonMark attention markers are unavailable')
+  }
+  const attentionMarkers = configuredAttentionMarkers
+  const previous = this.previous
+  const before = classifyCharacter(previous)
+  let marker: number | null = codes.eof
+
+  return start
+
+  function start(code: number | null): State | undefined {
+    /* v8 ignore next -- this text construct is dispatched only for an asterisk. */
+    if (code !== codes.asterisk) return nok(code)
+    marker = code
+    effects.enter('attentionSequence')
+    return inside(code)
+  }
+
+  function inside(code: number | null): State | undefined {
+    if (code === marker) {
+      effects.consume(code)
+      return inside
+    }
+
+    const token = effects.exit('attentionSequence')
+    const after = classifyCharacter(code)
+    const open = !after || (after === constants.characterGroupPunctuation && Boolean(before))
+      || attentionMarkers.includes(code)
+    const commonMarkClose = !before
+      || (before === constants.characterGroupPunctuation && Boolean(after))
+      || attentionMarkers.includes(previous)
+    const markerCount = token.end.offset - token.start.offset
+    const cjkStrongClose = markerCount >= 2
+      && unicodePunctuation(previous)
+      && isCjkCharacter(code)
+    const close = commonMarkClose || cjkStrongClose
+
+    token._open = open
+    token._close = close
+    return ok(code)
+  }
+}
+
+const cjkFriendlyAttention: Construct = {
+  name: 'cjkFriendlyAttention',
+  resolveAll: attention.resolveAll,
+  tokenize: tokenizeCjkFriendlyAttention,
+}
+
+const cjkFriendlyStrongExtension: Extension = {
+  text: { [codes.asterisk]: cjkFriendlyAttention },
+}
+
+/**
+ * Extend CommonMark asterisk strong emphasis for punctuation-delimited CJK
+ * prose, as a micromark syntax extension for `fromMarkdown`.
+ * @returns The micromark syntax extension.
+ */
+export function cjkFriendlyStrong(): Extension {
+  return cjkFriendlyStrongExtension
+}

packages/client/ui-primitives/src/markdown/incremental.ts

@@ -0,0 +1,130 @@
+/**
+ * Incremental block-level markdown parsing for an append-only text stream.
+ *
+ * Re-parsing the whole accumulated document on every streaming chunk is
+ * quadratic in the final reply length. CommonMark block parsing is line-based
+ * and appended text can only reshape the parse frontier — the last top-level
+ * block (a paragraph becoming a setext heading or a table, a list continuing
+ * after a blank line, an unclosed fence swallowing lines) — so earlier blocks
+ * are final. This parser therefore freezes all but the trailing
+ * {@link UNSTABLE_TAIL_BLOCKS} blocks and re-parses only the source tail
+ * behind them: each source region is parsed O(1) times over the stream
+ * instead of once per chunk.
+ *
+ * The freeze boundary comes from the parser's own `position` offsets, never
+ * from custom source scanning. The cut sits at the *end offset* of the last
+ * frozen block (not the next block's start): a following block's start offset
+ * excludes up to three spaces of insignificant leading indentation, which is
+ * harmless to drop, but cutting at the previous end also keeps the
+ * inter-block blank lines in the tail so the sliced source stays verbatim.
+ *
+ * Known deviation, shared with any prefix-freeze scheme: micromark resolves
+ * reference-style links and footnotes document-wide at parse time, so a
+ * reference whose definition lands on the other side of the freeze boundary
+ * renders literally until the settled full parse self-heals it.
+ */
+
+import type { Root, RootContent } from 'mdast'
+
+/**
+ * Trailing blocks kept unstable. Appended text reshapes at most the last
+ * block; the second-to-last is retained as safety margin so a freeze decision
+ * never has to reason about the parse frontier.
+ */
+const UNSTABLE_TAIL_BLOCKS = 2
+
+/** A top-level mdast block plus a render key that is stable across chunks. */
+export interface PositionedBlock {
+  /** The parsed block. Positions inside it are relative to its parse slice. */
+  readonly node: RootContent
+  /**
+   * The block's start offset in the full source text. Stable from the frame
+   * a block first appears through freezing, so React reconciles rather than
+   * remounts when a block crosses the freeze boundary.
+   */
+  readonly key: number
+}
+
+/** One {@link IncrementalMarkdownParser.update} result. */
+export interface IncrementalBlocks {
+  /** Blocks that can no longer change; grows monotonically per generation. */
+  readonly frozen: readonly PositionedBlock[]
+  /** The re-parsed unstable tail (at most {@link UNSTABLE_TAIL_BLOCKS} blocks plus growth). */
+  readonly tail: readonly PositionedBlock[]
+  /** Bumped whenever non-append input discards the frozen prefix; callers drop caches keyed on it. */
+  readonly generation: number
+}
+
+/**
+ * A block's render key: its absolute source start offset. A position-less
+ * node (a grammar is free to omit positions) falls back to a negative
+ * list-index key — unique within one update's tail, which is the only place
+ * the fallback can occur: freezing requires the cut block's position, so a
+ * position-less parse keeps every block in the tail (real grammars always
+ * stamp positions and never take this path).
+ */
+function blockKey(node: RootContent, base: number, index: number): number {
+  const offset = node.position?.start.offset
+  return offset === undefined ? -(index + 1) : base + offset
+}
+
+/**
+ * Append-only incremental parser over a caller-supplied grammar. One instance
+ * accumulates one streaming document; non-append input resets it.
+ */
+export class IncrementalMarkdownParser {
+  private prevText = ''
+  private tailStart = 0
+  private frozen: PositionedBlock[] = []
+  private generation = 0
+  private cached: IncrementalBlocks | null = null
+
+  /** @param parse - Grammar shared with whatever renders the blocks, so boundaries agree. */
+  constructor(private readonly parse: (text: string) => Root) {}
+
+  /**
+   * Fold the current accumulated text and return the frozen/tail split.
+   * Idempotent for identical input (the previous result is returned as-is),
+   * so callers may invoke it from render paths that re-execute.
+   * @param text - The full accumulated markdown source.
+   * @returns Frozen and tail blocks with stream-stable render keys.
+   */
+  update(text: string): IncrementalBlocks {
+    if (this.cached !== null && text === this.prevText) return this.cached
+    // Deliberate O(prefix) memcmp per update: sound divergence detection has
+    // to verify the whole retained prefix, and startsWith compares bytes two
+    // orders of magnitude faster than parsing them — the cost this class
+    // exists to remove. Passing append/reset deltas instead would push
+    // append bookkeeping across the session-projection seam for a check
+    // that stays sub-millisecond at realistic reply sizes.
+    if (!text.startsWith(this.prevText)) {
+      this.prevText = ''
+      this.tailStart = 0
+      this.frozen = []
+      this.generation += 1
+    }
+    this.prevText = text
+    const base = this.tailStart
+    const blocks = this.parse(text.slice(base)).children
+    let firstUnstable = Math.max(0, blocks.length - UNSTABLE_TAIL_BLOCKS)
+    if (firstUnstable > 0) {
+      const cutEnd = blocks[firstUnstable - 1]?.position?.end.offset
+      if (cutEnd === undefined) {
+        // A grammar that omits positions leaves nothing to cut at; keep the
+        // whole parse in the tail rather than guessing a boundary.
+        firstUnstable = 0
+      } else {
+        for (const node of blocks.slice(0, firstUnstable)) {
+          this.frozen.push({ node, key: blockKey(node, base, this.frozen.length) })
+        }
+        this.tailStart = base + cutEnd
+      }
+    }
+    const tail = blocks.slice(firstUnstable).map((node, index) => ({
+      node,
+      key: blockKey(node, base, index),
+    }))
+    this.cached = { frozen: [...this.frozen], tail, generation: this.generation }
+    return this.cached
+  }
+}

packages/client/ui-primitives/src/markdown/katex.tsx

@@ -0,0 +1,90 @@
+/**
+ * TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer
+ * replaced: the same three-arm error chain (strict render, `strict: 'ignore'`
+ * retry, error span) and a DOM-identical element tree, so settled math keeps
+ * its exact markup. KaTeX emits an HTML string; the browser's own HTML parser
+ * (`DOMParser`, applying the spec's SVG/MathML foreign-content attribute
+ * adjustments KaTeX output relies on) turns it into a tree this module maps
+ * onto React elements — KaTeX output is a static span/MathML/SVG vocabulary
+ * with no raw user HTML, the same trust shiki's tree gets in CodeBlock.
+ *
+ * React 18 has no MathML support, so the `.katex-mathml` subtree's elements
+ * land in the HTML namespace — exactly as they did under the replaced
+ * hast-util-to-jsx-runtime pipeline. The visual arm is the `.katex-html`
+ * span tree; the MathML arm serves assistive technology, which reads it by
+ * tag name regardless of namespace.
+ */
+
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import katex from 'katex'
+
+/**
+ * Convert one inline `style` attribute string into React's style object.
+ * KaTeX emits only plain kebab-case declarations (no custom properties and no
+ * nameless declarations), so camel-casing the property is the whole mapping.
+ */
+function styleObject(css: string): CSSProperties {
+  const style: Record<string, string> = {}
+  for (const declaration of css.split(';')) {
+    const colon = declaration.indexOf(':')
+    if (colon === -1) continue
+    const name = declaration.slice(0, colon).trim()
+    const key = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+    style[key] = declaration.slice(colon + 1).trim()
+  }
+  return style
+}
+
+/** Map one parsed DOM node onto a React element (text nodes pass through). */
+function domToReact(node: ChildNode, key: number): ReactNode {
+  if (node.nodeType === Node.TEXT_NODE) return node.textContent
+  /* v8 ignore next 2 -- KaTeX output holds only elements and text; other
+     node kinds cannot appear in its serialized vocabulary. */
+  if (node.nodeType !== Node.ELEMENT_NODE) return null
+  const element = node as Element
+  const props: Record<string, unknown> = { key }
+  for (const attribute of element.attributes) {
+    if (attribute.name === 'class') props['className'] = attribute.value
+    else if (attribute.name === 'style') props['style'] = styleObject(attribute.value)
+    else props[attribute.name] = attribute.value
+  }
+  const children = [...element.childNodes].map(domToReact)
+  return children.length === 0
+    ? createElement(element.localName, props)
+    : createElement(element.localName, props, ...children)
+}
+
+/**
+ * Render TeX source to React elements through KaTeX.
+ * @param value - The TeX source (math node value; fenced `math` blocks append
+ * their trailing newline to match the replaced pipeline's text extraction).
+ * @param displayMode - Display (block) versus inline rendering.
+ * @returns KaTeX's element tree, or the error span when the source does not
+ * parse (colored with KaTeX's stock `errorColor`, matching rehype-katex).
+ */
+export function renderTexToReact(value: string, displayMode: boolean): ReactNode {
+  let html: string
+  try {
+    html = katex.renderToString(value, { displayMode, throwOnError: true })
+  } catch (error) {
+    try {
+      html = katex.renderToString(value, { displayMode, strict: 'ignore', throwOnError: false })
+    } catch {
+      // KaTeX renders ParseErrors itself under throwOnError: false; only its
+      // internal errors reach here, so mirror rehype-katex's manual span.
+      /* v8 ignore next 8 */
+      return (
+        <span
+          className="katex-error"
+          style={{ color: '#cc0000' }}
+          title={String(error)}
+        >
+          {value}
+        </span>
+      )
+    }
+  }
+  const parsed = new DOMParser().parseFromString(html, 'text/html')
+  return [...parsed.body.childNodes].map(domToReact)
+}

packages/client/ui-primitives/src/markdown/mathCompatibility.ts

@@ -8,10 +8,6 @@ import type { Construct, Extension, Previous, State, Tokenizer } from 'micromark
 
 // oxlint-disable typescript/no-this-alias -- micromark binds tokenizer context only on the outer callback.
 
-interface RemarkProcessor {
-  data(): { micromarkExtensions?: Extension[] }
-}
-
 const previousBackslash: Previous = function (code) {
   if (code !== codes.backslash) return true
   const tail = this.events.at(-1)
@@ -342,12 +338,12 @@ const backslashMath: Extension = {
 }
 
 /**
- * Add TeX backslash delimiters and same-line display-dollar blocks for remark-math.
- * The same processor must register remark-math to compile the emitted math tokens.
- * @returns Nothing.
+ * TeX backslash delimiters and same-line display-dollar blocks as a micromark
+ * syntax extension reusing `micromark-extension-math`'s token vocabulary; the
+ * caller must also register `math()` on the same parse so the emitted tokens
+ * compile to standard math nodes.
+ * @returns The micromark syntax extension.
  */
-export function remarkMathCompatibility(this: RemarkProcessor): undefined {
-  const data = this.data()
-  const extensions = data.micromarkExtensions ?? (data.micromarkExtensions = [])
-  extensions.push(backslashMath)
+export function mathCompatibility(): Extension {
+  return backslashMath
 }

packages/client/ui-primitives/src/markdown/parse.ts

@@ -0,0 +1,44 @@
+/**
+ * The markdown renderer's two mdast grammars, one per rendering arm. Each
+ * arm is internally consistent — the incremental tail parses, the one-shot
+ * parses, and the plain-text projection of a given grammar always agree on
+ * where blocks start and end — and the settled grammar is the streaming one
+ * plus the math extensions, so the arms differ only where TeX delimiters
+ * begin a math construct (a `$$` block is a paragraph while streaming and a
+ * math block once settled, by design).
+ */
+
+import type { Root } from 'mdast'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { gfmFromMarkdown } from 'mdast-util-gfm'
+import { mathFromMarkdown } from 'mdast-util-math'
+import { gfm } from 'micromark-extension-gfm'
+import { math } from 'micromark-extension-math'
+import { cjkFriendlyStrong } from './cjkFriendlyStrong.ts'
+import { mathCompatibility } from './mathCompatibility.ts'
+
+/**
+ * Parse GFM markdown (the streaming arm's grammar: no math, so incomplete
+ * TeX never flashes KaTeX errors mid-stream).
+ * @param text - Markdown source.
+ * @returns The mdast root.
+ */
+export function parseGfm(text: string): Root {
+  return fromMarkdown(text, {
+    extensions: [gfm(), cjkFriendlyStrong()],
+    mdastExtensions: [gfmFromMarkdown()],
+  })
+}
+
+/**
+ * Parse GFM markdown plus TeX math with the compatibility delimiters
+ * (the settled arm's grammar).
+ * @param text - Markdown source.
+ * @returns The mdast root.
+ */
+export function parseGfmWithMath(text: string): Root {
+  return fromMarkdown(text, {
+    extensions: [gfm(), cjkFriendlyStrong(), mathCompatibility(), math()],
+    mdastExtensions: [gfmFromMarkdown(), mathFromMarkdown()],
+  })
+}

packages/client/ui-primitives/src/markdown/plain-text.ts

@@ -1,12 +1,12 @@
 /**
  * Markdown-to-plain-text projection for compact summaries and labels.
- * Parsing shares the renderer's GFM grammar; raw HTML stays literal, links
- * keep their labels, images keep alt text, and code keeps its source text.
+ * Parsing shares the renderer's streaming GFM grammar ({@link parseGfm}), so
+ * the projection strips exactly the markup the renderer would draw; raw HTML
+ * stays literal, links keep their labels, images keep alt text, and code
+ * keeps its source text.
  */
 
-import { fromMarkdown } from 'mdast-util-from-markdown'
-import { gfmFromMarkdown } from 'mdast-util-gfm'
-import { gfm } from 'micromark-extension-gfm'
+import { parseGfm } from './parse.ts'
 
 /** Amount of parsed Markdown content returned by the extractor. */
 export type MarkdownPlainTextMode = 'all' | 'first-line' | 'first-paragraph'
@@ -108,10 +108,7 @@ export function extractMarkdownPlainText(
   options: MarkdownPlainTextOptions = {},
 ): string {
   const { mode = 'all' } = options
-  const root = fromMarkdown(markdown, {
-    extensions: [gfm()],
-    mdastExtensions: [gfmFromMarkdown()],
-  }) as MarkdownNode
+  const root = parseGfm(markdown) as MarkdownNode
   const all = fullText(root)
   switch (mode) {
     case 'all':

packages/client/ui-primitives/src/markdown/render.tsx

@@ -0,0 +1,544 @@
+/**
+ * Direct mdast→React markdown renderer. Replaces the react-markdown /
+ * remark-rehype pipeline with one switch over parsed nodes so streaming can
+ * cache frozen blocks as React elements; the rendered DOM is pinned
+ * byte-for-byte by `tests/fixtures/markdown-dom` and must not drift.
+ *
+ * Untrusted-output policy (unchanged from the replaced pipeline): link and
+ * image destinations pass a protocol allowlist, images additionally require
+ * absolute HTTP(S), raw HTML renders as literal text (no HTML enters the
+ * DOM), and KaTeX runs without trusted commands. Fragment-anchor URLs fail
+ * the allowlist, so footnote references and back-references render as plain
+ * text rather than in-page links.
+ *
+ * Merge-extensible node unions fall through the documented default (render
+ * nothing) rather than ending in assertNever: grammars registered elsewhere
+ * may add node types this renderer has no mapping for.
+ */
+
+import { Fragment, createElement } from 'react'
+import type { Key, ReactNode } from 'react'
+import type * as Md from 'mdast'
+import type {} from 'mdast-util-math'
+import { normalizeUri } from 'micromark-util-sanitize-uri'
+import { CodeBlock } from './CodeBlock.tsx'
+import { renderTexToReact } from './katex.tsx'
+import type { PositionedBlock } from './incremental.ts'
+import css from './MarkdownText.module.css'
+
+/** Copy-button labels forwarded to fence CodeBlocks (this package is cordis-free, so copy arrives via props). */
+export interface MarkdownCodeLabels {
+  /** Copy-button idle label. */
+  copyLabel?: string | undefined
+  /** Copy-button label during the post-copy confirmation window. */
+  copiedLabel?: string | undefined
+}
+
+function sanitizeUrl(url: string): string {
+  try {
+    switch (new URL(url).protocol) {
+      case 'http:':
+      case 'https:':
+      case 'mailto:':
+        return url
+      default:
+        return ''
+    }
+  } catch {
+    // Relative and otherwise unparsable destinations are disallowed alongside
+    // disallowed protocols; new URL() has no other failure mode for strings.
+    return ''
+  }
+}
+
+function remoteImageUrl(url: string): string | undefined {
+  try {
+    const protocol = new URL(url).protocol
+    return protocol === 'http:' || protocol === 'https:' ? url : undefined
+  } catch {
+    // Same single failure mode as above: not an absolute URL.
+    return undefined
+  }
+}
+
+/** Link/image reference targets collected from a document (first definition per identifier wins, as in CommonMark). */
+export interface ReferenceTargets {
+  /** Link/image definitions keyed by upper-cased identifier. */
+  definitions: Map<string, Md.Definition>
+  /** Footnote definitions keyed by upper-cased identifier. */
+  footnotes: Map<string, Md.FootnoteDefinition>
+}
+
+/**
+ * Create an empty {@link ReferenceTargets}.
+ * @returns Fresh empty maps.
+ */
+export function createReferenceTargets(): ReferenceTargets {
+  return { definitions: new Map(), footnotes: new Map() }
+}
+
+/**
+ * Record every definition and footnote definition under `nodes` into
+ * `targets`, depth-first, keeping the first definition per identifier.
+ * @param nodes - Subtrees to walk (top-level blocks or any nested children).
+ * @param targets - Accumulator, typically shared across incremental segments.
+ */
+export function collectReferenceTargets(
+  nodes: readonly Md.RootContent[],
+  targets: ReferenceTargets,
+): void {
+  for (const node of nodes) {
+    if (node.type === 'definition') {
+      const id = node.identifier.toUpperCase()
+      if (!targets.definitions.has(id)) targets.definitions.set(id, node)
+    } else if (node.type === 'footnoteDefinition') {
+      const id = node.identifier.toUpperCase()
+      if (!targets.footnotes.has(id)) targets.footnotes.set(id, node)
+    }
+    if ('children' in node) collectReferenceTargets(node.children, targets)
+  }
+}
+
+/**
+ * One render pass's state: immutable options and targets plus the footnote
+ * numbering accumulated in document order while references render.
+ */
+export interface MarkdownRenderContext {
+  /** Streaming arm: fences render plain and TeX stays literal. */
+  readonly streaming: boolean
+  /** Localized fence copy-button labels. */
+  readonly codeLabels: MarkdownCodeLabels | undefined
+  /** Reference targets visible to this pass. */
+  readonly targets: ReferenceTargets
+  /** Footnote identifiers in first-reference order; a footnote's number is its 1-based index here. */
+  readonly footnoteOrder: string[]
+  /** References rendered per identifier; drives the section's back-reference count. */
+  readonly footnoteCounts: Map<string, number>
+}
+
+/**
+ * Render top-level blocks. Nodes that render nothing (definitions, unmapped
+ * types) are dropped rather than kept as null placeholders, matching the
+ * replaced pipeline's child lists so separator newlines land identically.
+ * @param blocks - Blocks with their stream-stable render keys.
+ * @param context - The pass state; footnote numbering mutates in document order.
+ * @returns One React node per rendered block.
+ */
+export function renderBlocks(
+  blocks: readonly PositionedBlock[],
+  context: MarkdownRenderContext,
+): ReactNode[] {
+  return blocks
+    .map(block => renderNode(block.node, block.key, context))
+    .filter(element => element !== null)
+}
+
+/**
+ * Interleave the newline text nodes the replaced pipeline emitted between
+ * block-level children. They are invisible between elements but coalesce
+ * into adjacent literal raw-HTML text, where the DOM parity fixtures pin
+ * them.
+ * @param elements - Rendered block children with empty renders already dropped.
+ * @param edges - Also emit the leading and trailing newline (hast's loose wrap).
+ * @returns The interleaved children.
+ */
+export function wrapBlockChildren(elements: readonly ReactNode[], edges: boolean): ReactNode[] {
+  const wrapped: ReactNode[] = []
+  for (const element of elements) {
+    if (edges || wrapped.length > 0) wrapped.push('\n')
+    wrapped.push(element)
+  }
+  if (edges && elements.length > 0) wrapped.push('\n')
+  return wrapped
+}
+
+/**
+ * A block child rendered for a parent that must tell paragraphs apart from
+ * other blocks (list items unwrap them when tight; footnote bodies receive
+ * their back-references inside the trailing paragraph).
+ */
+type BlockEntry = { paragraph: ReactNode[] } | { element: ReactNode }
+
+/** Render container children into {@link BlockEntry} values, dropping empty renders. */
+function renderBlockEntries(
+  blocks: readonly Md.RootContent[],
+  context: MarkdownRenderContext,
+): BlockEntry[] {
+  const entries: BlockEntry[] = []
+  for (const [index, block] of blocks.entries()) {
+    if (block.type === 'paragraph') {
+      entries.push({ paragraph: renderChildren(block.children, context) })
+    } else {
+      const element = renderNode(block, index, context)
+      if (element !== null) entries.push({ element })
+    }
+  }
+  return entries
+}
+
+function renderChildren(
+  nodes: readonly Md.RootContent[],
+  context: MarkdownRenderContext,
+): ReactNode[] {
+  return nodes.map((node, index) => renderNode(node, index, context))
+}
+
+function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderContext): ReactNode {
+  switch (node.type) {
+    case 'text':
+      return node.value
+    case 'paragraph':
+      return <p key={key}>{renderChildren(node.children, context)}</p>
+    case 'heading':
+      return createElement(`h${node.depth}`, { key }, ...renderChildren(node.children, context))
+    case 'blockquote':
+      return (
+        <blockquote key={key}>
+          {wrapBlockChildren(renderChildren(node.children, context).filter(child => child !== null), true)}
+        </blockquote>
+      )
+    case 'thematicBreak':
+      return <hr key={key} />
+    case 'break':
+      // The replaced pipeline emitted a newline text node after each <br>.
+      return <Fragment key={key}><br />{'\n'}</Fragment>
+    case 'strong':
+      return <strong key={key}>{renderChildren(node.children, context)}</strong>
+    case 'emphasis':
+      return <em key={key}>{renderChildren(node.children, context)}</em>
+    case 'delete':
+      return <del key={key}>{renderChildren(node.children, context)}</del>
+    case 'inlineCode': {
+      // Parity with mdast-util-to-hast: inline code renders line endings as spaces.
+      const value = node.value.replace(/\r?\n|\r/g, ' ')
+      // An inline-code token that is entirely an absolute HTTP(S) URL keeps
+      // its code chrome and gains the same safe external anchor as a link;
+      // commands, partial URLs, and other schemes stay inert. The value is
+      // authored text, not a parsed destination, so no normalizeUri: port,
+      // path, and query render unchanged.
+      const href = inlineCodeHttpUrl(value)
+      return <code key={key}>{href === undefined ? value : renderSafeLink(href, [value], 'link')}</code>
+    }
+    case 'html':
+      // No HTML parser enters the pipeline: raw HTML stays literal text.
+      return node.value
+    case 'code':
+      return renderCode(node, key, context)
+    case 'math':
+      return <Fragment key={key}>{renderTexToReact(node.value, true)}</Fragment>
+    case 'inlineMath':
+      return <Fragment key={key}>{renderTexToReact(node.value, false)}</Fragment>
+    case 'list':
+      return renderList(node, key, context)
+    case 'listItem':
+      // Reachable only in hand-built trees: the grammar emits items inside lists.
+      return renderListItem(node, listItemLoose(node), key, context)
+    case 'table':
+      return renderTable(node, key, context)
+    case 'link':
+      return renderAnchor(node.url, renderChildren(node.children, context), key)
+    case 'linkReference':
+      return renderLinkReference(node, key, context)
+    case 'image':
+      return renderImage(node.url, node.alt ?? '', key)
+    case 'imageReference':
+      return renderImageReference(node, key, context)
+    case 'footnoteReference':
+      return renderFootnoteReference(node, key, context)
+    case 'definition':
+    case 'footnoteDefinition':
+      // Targets render elsewhere: definitions resolve references in place;
+      // footnote bodies render in the trailing section.
+      return null
+    default:
+      // Documented default for the merge-extensible union: node types without
+      // a mapping (tableRow/tableCell outside a table, frontmatter, future
+      // grammar contributions) render nothing.
+      return null
+  }
+}
+
+function renderCode(node: Md.Code, key: Key, context: MarkdownRenderContext): ReactNode {
+  const language = node.lang ?? undefined
+  if (node.value === '') {
+    // Parity: the replaced pipeline kept the stock <pre> for an empty fence.
+    return (
+      <pre key={key}>
+        <code className={language === undefined ? undefined : `language-${language}`} />
+      </pre>
+    )
+  }
+  // The replaced pipeline recovered the grammar id from the hast class with
+  // /language-([\w-]+)/, which truncates at the first non-word character.
+  const lang = language === undefined ? undefined : /^[\w-]+/.exec(language)?.[0]
+  if (!context.streaming && lang === 'math') {
+    // ```math fences render as display TeX once settled (rehype-katex parity);
+    // its text extraction saw the code block's trailing newline.
+    return <Fragment key={key}>{renderTexToReact(`${node.value}\n`, true)}</Fragment>
+  }
+  return (
+    <CodeBlock
+      key={key}
+      // The replaced hast pipeline appended one synthetic newline that
+      // CodeBlock's display trim removes; feeding the bare value would make
+      // that trim eat a REAL trailing blank line inside the fence instead.
+      code={`${node.value}\n`}
+      lang={context.streaming ? undefined : lang}
+      copyLabel={context.codeLabels?.copyLabel}
+      copiedLabel={context.codeLabels?.copiedLabel}
+    />
+  )
+}
+
+/** A list is loose when it or any of its items is spread; every item then keeps its paragraphs. */
+function listLoose(list: Md.List): boolean {
+  return (list.spread ?? false) || list.children.some(listItemLoose)
+}
+
+function listItemLoose(item: Md.ListItem): boolean {
+  return item.spread ?? item.children.length > 1
+}
+
+function renderList(node: Md.List, key: Key, context: MarkdownRenderContext): ReactNode {
+  const loose = listLoose(node)
+  const properties: { start?: number; className?: string } = {}
+  if (typeof node.start === 'number' && node.start !== 1) properties.start = node.start
+  if (node.children.some(item => typeof item.checked === 'boolean')) {
+    properties.className = 'contains-task-list'
+  }
+  return createElement(
+    node.ordered === true ? 'ol' : 'ul',
+    { key, ...properties },
+    ...node.children.map((item, index) => renderListItem(item, loose, index, context)),
+  )
+}
+
+function renderListItem(
+  item: Md.ListItem,
+  loose: boolean,
+  key: Key,
+  context: MarkdownRenderContext,
+): ReactNode {
+  const entries = renderBlockEntries(item.children, context)
+  const task = typeof item.checked === 'boolean'
+  if (task) {
+    const checkbox = <input key="task-checkbox" type="checkbox" checked={item.checked === true} disabled />
+    const head = entries[0]
+    if (head !== undefined && 'paragraph' in head) {
+      head.paragraph = head.paragraph.length > 0 ? [checkbox, ' ', ...head.paragraph] : [checkbox]
+    } else {
+      entries.unshift({ paragraph: [checkbox] })
+    }
+  }
+  // Newline placement and tight-paragraph unwrapping mirror
+  // mdast-util-to-hast's list-item handler: a newline before every child
+  // except a tight leading paragraph, and after a trailing non-paragraph
+  // (or any trailing child when loose).
+  const parts: ReactNode[] = []
+  for (const [index, entry] of entries.entries()) {
+    const isParagraph = 'paragraph' in entry
+    if (loose || index !== 0 || !isParagraph) parts.push('\n')
+    if (!isParagraph) parts.push(entry.element)
+    else if (loose) parts.push(<p key={`p-${index}`}>{entry.paragraph}</p>)
+    else parts.push(<Fragment key={`p-${index}`}>{entry.paragraph}</Fragment>)
+  }
+  const tail = entries[entries.length - 1]
+  if (tail !== undefined && (loose || !('paragraph' in tail))) parts.push('\n')
+  return (
+    <li key={key} className={task ? 'task-list-item' : undefined}>
+      {parts}
+    </li>
+  )
+}
+
+function renderTable(node: Md.Table, key: Key, context: MarkdownRenderContext): ReactNode {
+  const align = node.align ?? null
+  const [headRow, ...bodyRows] = node.children
+  return (
+    <div key={key} className={css.tableScroll}>
+      <table>
+        {headRow !== undefined && <thead>{renderTableRow(headRow, 'th', align, 0, context)}</thead>}
+        {bodyRows.length > 0 && (
+          <tbody>
+            {bodyRows.map((row, index) => renderTableRow(row, 'td', align, index + 1, context))}
+          </tbody>
+        )}
+      </table>
+    </div>
+  )
+}
+
+function renderTableRow(
+  row: Md.TableRow,
+  cellTag: 'th' | 'td',
+  align: readonly Md.AlignType[] | null,
+  key: Key,
+  context: MarkdownRenderContext,
+): ReactNode {
+  // With column alignment present, every row renders exactly one cell per
+  // column, padding or truncating the row (mdast-util-to-hast parity).
+  const length = align === null ? row.children.length : align.length
+  const cells: ReactNode[] = []
+  for (let index = 0; index < length; index++) {
+    const cell = row.children[index]
+    const alignValue = align?.[index]
+    cells.push(createElement(
+      cellTag,
+      // hast-util-to-jsx-runtime's default tableCellAlignToStyle turned the
+      // deprecated align attribute into an inline style; keep that DOM.
+      { key: index, style: alignValue == null ? undefined : { textAlign: alignValue } },
+      ...(cell === undefined ? [] : renderChildren(cell.children, context)),
+    ))
+  }
+  return <tr key={key}>{cells}</tr>
+}
+
+/** Anchor over an already-authored href: allowlisted or unwrapped, external links get the safe attributes. */
+function renderSafeLink(href: string, children: ReactNode[], key: Key): ReactNode {
+  const safeHref = sanitizeUrl(href)
+  if (safeHref === '') return <Fragment key={key}>{children}</Fragment>
+  const external = ['http:', 'https:'].includes(new URL(safeHref).protocol)
+  return (
+    <a
+      key={key}
+      href={safeHref}
+      {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+    >
+      {children}
+    </a>
+  )
+}
+
+/** Anchor over a parsed markdown destination, which hast normalized before the allowlist saw it. */
+function renderAnchor(url: string, children: ReactNode[], key: Key): ReactNode {
+  return renderSafeLink(normalizeUri(url), children, key)
+}
+
+/**
+ * The complete inline-code value when it is exactly an absolute HTTP(S) URL
+ * (no surrounding whitespace); anything else stays inert code.
+ */
+function inlineCodeHttpUrl(value: string): string | undefined {
+  if (value.trim() !== value) return undefined
+  try {
+    const protocol = new URL(value).protocol
+    return protocol === 'http:' || protocol === 'https:' ? value : undefined
+  } catch {
+    // Not an absolute URL at all — the only way new URL() rejects a string.
+    return undefined
+  }
+}
+
+function renderImage(url: string, alt: string, key: Key): ReactNode {
+  const imageSrc = remoteImageUrl(sanitizeUrl(normalizeUri(url)))
+  if (imageSrc === undefined) {
+    return <span key={key} className={css.imageAlt}>{alt}</span>
+  }
+  return (
+    <img
+      key={key}
+      className={css.image}
+      src={imageSrc}
+      alt={alt}
+      loading="lazy"
+      decoding="async"
+      referrerPolicy="no-referrer"
+    />
+  )
+}
+
+/** The bracketed source text a reference reverts to when its definition is missing. */
+function referenceSuffix(node: Md.LinkReference | Md.ImageReference): string {
+  if (node.referenceType === 'collapsed') return '][]'
+  if (node.referenceType === 'full') return `][${node.label ?? node.identifier}]`
+  return ']'
+}
+
+function renderLinkReference(
+  node: Md.LinkReference,
+  key: Key,
+  context: MarkdownRenderContext,
+): ReactNode {
+  const definition = context.targets.definitions.get(node.identifier.toUpperCase())
+  const children = renderChildren(node.children, context)
+  if (definition === undefined) {
+    // The grammar only emits references whose definitions exist somewhere in
+    // the same parse, but incremental segments and hand-built trees may still
+    // present unresolved ones: revert to the bracketed source text.
+    return <Fragment key={key}>{'['}{children}{referenceSuffix(node)}</Fragment>
+  }
+  return renderAnchor(definition.url, children, key)
+}
+
+function renderImageReference(
+  node: Md.ImageReference,
+  key: Key,
+  context: MarkdownRenderContext,
+): ReactNode {
+  const definition = context.targets.definitions.get(node.identifier.toUpperCase())
+  if (definition === undefined) return `![${node.alt ?? ''}${referenceSuffix(node)}`
+  return renderImage(definition.url, node.alt ?? '', key)
+}
+
+function renderFootnoteReference(
+  node: Md.FootnoteReference,
+  key: Key,
+  context: MarkdownRenderContext,
+): ReactNode {
+  const id = node.identifier.toUpperCase()
+  const seen = context.footnoteCounts.get(id)
+  if (seen === undefined) context.footnoteOrder.push(id)
+  context.footnoteCounts.set(id, (seen ?? 0) + 1)
+  // The in-page anchor fails the protocol allowlist, so only the numbered
+  // superscript renders (matching the replaced pipeline's unwrapped link).
+  return <sup key={key}>{String(context.footnoteOrder.indexOf(id) + 1)}</sup>
+}
+
+/**
+ * Render the trailing footnote section for every footnote referenced during
+ * the pass, in first-reference order, with one plain-text back-reference
+ * marker per rendered reference.
+ * @param context - The pass state after all blocks rendered.
+ * @returns The section, or null when no referenced footnote has a definition.
+ */
+export function renderFootnoteSection(context: MarkdownRenderContext): ReactNode | null {
+  const items: ReactNode[] = []
+  for (const id of context.footnoteOrder) {
+    const definition = context.targets.footnotes.get(id)
+    if (definition === undefined) continue
+    const count = context.footnoteCounts.get(id) ?? 0
+    const backrefs: ReactNode[] = []
+    for (let reference = 1; reference <= count; reference++) {
+      if (backrefs.length > 0) backrefs.push(' ')
+      backrefs.push('↩')
+      if (reference > 1) backrefs.push(<sup key={`re-${reference}`}>{String(reference)}</sup>)
+    }
+    const entries = renderBlockEntries(definition.children, context)
+    const tail = entries[entries.length - 1]
+    const body: ReactNode[] = entries.map((entry, index) => (
+      'paragraph' in entry
+        ? (
+          <p key={`p-${index}`}>
+            {entry.paragraph}
+            {entry === tail && <>{' '}{backrefs}</>}
+          </p>
+        )
+        : entry.element
+    ))
+    // Without a trailing paragraph the back-references join the block list
+    // itself (and pick up the wrap newlines), as in the replaced pipeline.
+    if (tail === undefined || !('paragraph' in tail)) body.push(...backrefs)
+    items.push(
+      <li key={id} id={`user-content-fn-${normalizeUri(id.toLowerCase())}`}>
+        {wrapBlockChildren(body, true)}
+      </li>,
+    )
+  }
+  if (items.length === 0) return null
+  return (
+    <section key="footnotes" data-footnotes className="footnotes">
+      <h2 id="footnote-label" className="sr-only">Footnotes</h2>
+      <ol>{items}</ol>
+    </section>
+  )
+}

packages/client/ui-primitives/tests/fixtures/markdown-dom/blockquote-nested.settled.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <blockquote>
+    <p>
+      #text "level one\nstill one"
+    <blockquote>
+      <p>
+        #text "nested"
+    <ul>
+      <li>
+        #text "quoted list"
+  <p>
+    #text "after"

packages/client/ui-primitives/tests/fixtures/markdown-dom/blockquote-nested.streaming.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <blockquote>
+    <p>
+      #text "level one\nstill one"
+    <blockquote>
+      <p>
+        #text "nested"
+    <ul>
+      <li>
+        #text "quoted list"
+  <p>
+    #text "after"

packages/client/ui-primitives/tests/fixtures/markdown-dom/cjk-strong-and-inline-code-url.settled.txt

@@ -0,0 +1,20 @@
+<div class="_markdown_404681">
+  <p>
+    <strong>
+      #text "注意："
+    #text "内容在标点后直接闭合。"
+  <p>
+    #text "**Notice:**text keeps upstream parsing."
+  <p>
+    #text "*提醒！*单星号也保持上游行为。"
+  <p>
+    <code>
+      <a href="https://example.com/preview?q=one%20two#result" rel="noopener noreferrer" target="_blank">
+        #text "https://example.com/preview?q=one%20two#result"
+    #text " 与 "
+    <code>
+      #text "curl http://127.0.0.1:3199/"
+    #text " 以及 "
+    <code>
+      #text "javascript:alert(1)"
+    #text "。"

packages/client/ui-primitives/tests/fixtures/markdown-dom/cjk-strong-and-inline-code-url.streaming.txt

@@ -0,0 +1,20 @@
+<div class="_markdown_404681">
+  <p>
+    <strong>
+      #text "注意："
+    #text "内容在标点后直接闭合。"
+  <p>
+    #text "**Notice:**text keeps upstream parsing."
+  <p>
+    #text "*提醒！*单星号也保持上游行为。"
+  <p>
+    <code>
+      <a href="https://example.com/preview?q=one%20two#result" rel="noopener noreferrer" target="_blank">
+        #text "https://example.com/preview?q=one%20two#result"
+    #text " 与 "
+    <code>
+      #text "curl http://127.0.0.1:3199/"
+    #text " 以及 "
+    <code>
+      #text "javascript:alert(1)"
+    #text "。"

packages/client/ui-primitives/tests/fixtures/markdown-dom/code-fences.settled.txt

@@ -0,0 +1,78 @@
+<div class="_markdown_404681">
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+          #text "ts"
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <div>
+      <pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0">
+        <code>
+          <span class="line">
+            <span style="color:var(--shiki-token-keyword)">
+              #text "const"
+            <span style="color:var(--shiki-token-constant)">
+              #text " answer"
+            <span style="color:var(--shiki-token-keyword)">
+              #text ":"
+            <span style="color:var(--shiki-token-constant)">
+              #text " number"
+            <span style="color:var(--shiki-token-keyword)">
+              #text " ="
+            <span style="color:var(--shiki-token-constant)">
+              #text " 42"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "no language"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+          #text "unknown-lang"
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "plain fallback"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+          #text "ts"
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <div>
+      <pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0">
+        <code>
+          <span class="line">
+            <span style="color:var(--shiki-token-keyword)">
+              #text "const"
+            <span style="color:var(--shiki-token-constant)">
+              #text " withMeta"
+            <span style="color:var(--shiki-token-keyword)">
+              #text " ="
+            <span style="color:var(--shiki-token-constant)">
+              #text " true"
+  <pre>
+    <code>
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "indented code block\nsecond line"

packages/client/ui-primitives/tests/fixtures/markdown-dom/code-fences.streaming.txt

@@ -0,0 +1,53 @@
+<div class="_markdown_404681">
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "const answer: number = 42"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "no language"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "plain fallback"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "const withMeta = true"
+  <pre>
+    <code>
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "indented code block\nsecond line"

packages/client/ui-primitives/tests/fixtures/markdown-dom/definition-only.settled.txt

@@ -0,0 +1 @@
+<div class="_markdown_404681">

packages/client/ui-primitives/tests/fixtures/markdown-dom/definition-only.streaming.txt

@@ -0,0 +1 @@
+<div class="_markdown_404681">

packages/client/ui-primitives/tests/fixtures/markdown-dom/entities-and-escapes.settled.txt

@@ -0,0 +1,3 @@
+<div class="_markdown_404681">
+  <p>
+    #text "AT&T, 3 < 4, *not em*, backslash \\ literal, © entity."

packages/client/ui-primitives/tests/fixtures/markdown-dom/entities-and-escapes.streaming.txt

@@ -0,0 +1,3 @@
+<div class="_markdown_404681">
+  <p>
+    #text "AT&T, 3 < 4, *not em*, backslash \\ literal, © entity."

packages/client/ui-primitives/tests/fixtures/markdown-dom/fence-trailing-blank-lines.settled.txt

@@ -0,0 +1,37 @@
+<div class="_markdown_404681">
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "kept blank line follows\n"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+          #text "ts"
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <div>
+      <pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0">
+        <code>
+          <span class="line">
+            <span style="color:var(--shiki-token-keyword)">
+              #text "const"
+            <span style="color:var(--shiki-token-constant)">
+              #text " doubled"
+            <span style="color:var(--shiki-token-keyword)">
+              #text " ="
+            <span style="color:var(--shiki-token-constant)">
+              #text " true"
+          #text "\n"
+          <span class="line">
+          #text "\n"
+          <span class="line">
+  <p>
+    #text "after"

packages/client/ui-primitives/tests/fixtures/markdown-dom/fence-trailing-blank-lines.streaming.txt

@@ -0,0 +1,23 @@
+<div class="_markdown_404681">
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "kept blank line follows\n"
+  <div class="_block_9aea57 md-code-block">
+    <div class="_bannerWrap_9aea57">
+      <div class="_banner_9aea57">
+        <div class="_infostring_9aea57">
+        <div class="_action_9aea57">
+          <button class="_copyButton_9aea57" type="button">
+            #text "复制"
+    <pre class="_plain_9aea57">
+      <code>
+        #text "const doubled = true\n\n"
+  <p>
+    #text "after"

packages/client/ui-primitives/tests/fixtures/markdown-dom/footnotes.settled.txt

@@ -0,0 +1,29 @@
+<div class="_markdown_404681">
+  <p>
+    #text "First use"
+    <sup>
+      #text "1"
+    #text " and reuse"
+    <sup>
+      #text "1"
+    #text " and another"
+    <sup>
+      #text "2"
+    #text "."
+  <section class="footnotes" data-footnotes="true">
+    <h2 class="sr-only" id="footnote-label">
+      #text "Footnotes"
+    <ol>
+      <li id="user-content-fn-a">
+        <p>
+          #text "Footnote a body with "
+          <a href="https://example.com" rel="noopener noreferrer" target="_blank">
+            #text "link"
+          #text ". ↩ ↩"
+          <sup>
+            #text "2"
+      <li id="user-content-fn-b">
+        <p>
+          #text "Footnote b first paragraph."
+        <p>
+          #text "Second paragraph of b. ↩"

packages/client/ui-primitives/tests/fixtures/markdown-dom/footnotes.streaming.txt

@@ -0,0 +1,29 @@
+<div class="_markdown_404681">
+  <p>
+    #text "First use"
+    <sup>
+      #text "1"
+    #text " and reuse"
+    <sup>
+      #text "1"
+    #text " and another"
+    <sup>
+      #text "2"
+    #text "."
+  <section class="footnotes" data-footnotes="true">
+    <h2 class="sr-only" id="footnote-label">
+      #text "Footnotes"
+    <ol>
+      <li id="user-content-fn-a">
+        <p>
+          #text "Footnote a body with "
+          <a href="https://example.com" rel="noopener noreferrer" target="_blank">
+            #text "link"
+          #text ". ↩ ↩"
+          <sup>
+            #text "2"
+      <li id="user-content-fn-b">
+        <p>
+          #text "Footnote b first paragraph."
+        <p>
+          #text "Second paragraph of b. ↩"

packages/client/ui-primitives/tests/fixtures/markdown-dom/gfm-strikethrough-and-literals.settled.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <p>
+    #text "Mixed "
+    <del>
+      #text "gone"
+    #text " text with "
+    <a href="http://www.example.com" rel="noopener noreferrer" target="_blank">
+      #text "www.example.com"
+    #text " literal and "
+    <a href="mailto:user@example.com">
+      #text "user@example.com"
+    #text " email."

packages/client/ui-primitives/tests/fixtures/markdown-dom/gfm-strikethrough-and-literals.streaming.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <p>
+    #text "Mixed "
+    <del>
+      #text "gone"
+    #text " text with "
+    <a href="http://www.example.com" rel="noopener noreferrer" target="_blank">
+      #text "www.example.com"
+    #text " literal and "
+    <a href="mailto:user@example.com">
+      #text "user@example.com"
+    #text " email."

packages/client/ui-primitives/tests/fixtures/markdown-dom/hard-breaks-and-hr.settled.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <p>
+    #text "two-space break"
+    <br>
+    #text "\nafter break"
+  <p>
+    #text "backslash break"
+    <br>
+    #text "\nafter backslash"
+  <hr>
+  <p>
+    #text "tail"

packages/client/ui-primitives/tests/fixtures/markdown-dom/hard-breaks-and-hr.streaming.txt

@@ -0,0 +1,12 @@
+<div class="_markdown_404681">
+  <p>
+    #text "two-space break"
+    <br>
+    #text "\nafter break"
+  <p>
+    #text "backslash break"
+    <br>
+    #text "\nafter backslash"
+  <hr>
+  <p>
+    #text "tail"

packages/client/ui-primitives/tests/fixtures/markdown-dom/heading-tight-against-list.settled.txt

@@ -0,0 +1,15 @@
+<div class="_markdown_404681">
+  <h4>
+    #text "Small heading"
+  <ul>
+    <li>
+      #text "one"
+    <li>
+      #text "two"
+  <h5>
+    #text "Next"
+  <ol>
+    <li>
+      #text "a"
+    <li>
+      #text "b"

packages/client/ui-primitives/tests/fixtures/markdown-dom/heading-tight-against-list.streaming.txt

@@ -0,0 +1,15 @@
+<div class="_markdown_404681">
+  <h4>
+    #text "Small heading"
+  <ul>
+    <li>
+      #text "one"
+    <li>
+      #text "two"
+  <h5>
+    #text "Next"
+  <ol>
+    <li>
+      #text "a"
+    <li>
+      #text "b"

packages/client/ui-primitives/tests/fixtures/markdown-dom/headings-and-paragraphs.settled.txt

@@ -0,0 +1,33 @@
+<div class="_markdown_404681">
+  <h1>
+    #text "H1 with "
+    <code>
+      #text "code"
+  <h2>
+    #text "H2"
+  <h3>
+    #text "H3"
+  <h4>
+    #text "H4"
+  <h5>
+    #text "H5"
+  <h6>
+    #text "H6"
+  <p>
+    #text "Paragraph one with "
+    <strong>
+      #text "strong"
+    #text ", "
+    <em>
+      #text "emphasis"
+    #text ", "
+    <del>
+      #text "strike"
+    #text ", and "
+    <code>
+      #text "inline"
+    #text "."
+  <h1>
+    #text "Setext title"
+  <h2>
+    #text "Second setext"

packages/client/ui-primitives/tests/fixtures/markdown-dom/headings-and-paragraphs.streaming.txt

@@ -0,0 +1,33 @@
+<div class="_markdown_404681">
+  <h1>
+    #text "H1 with "
+    <code>
+      #text "code"
+  <h2>
+    #text "H2"
+  <h3>
+    #text "H3"
+  <h4>
+    #text "H4"
+  <h5>
+    #text "H5"
+  <h6>
+    #text "H6"
+  <p>
+    #text "Paragraph one with "
+    <strong>
+      #text "strong"
+    #text ", "
+    <em>
+      #text "emphasis"
+    #text ", "
+    <del>
+      #text "strike"
+    #text ", and "
+    <code>
+      #text "inline"
+    #text "."
+  <h1>
+    #text "Setext title"
+  <h2>
+    #text "Second setext"

packages/client/ui-primitives/tests/fixtures/markdown-dom/images.settled.txt

@@ -0,0 +1,14 @@
+<div class="_markdown_404681">
+  <p>
+    <img alt="https image" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="https://example.com/secure.png">
+  <p>
+    <img alt="http image" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="http://example.com/plain.png">
+  <p>
+    <span class="_imageAlt_404681">
+      #text "relative dropped"
+    #text " and inline "
+    <span class="_imageAlt_404681">
+      #text "bad scheme"
+    #text " end."
+  <p>
+    <img alt="" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="https://example.com/empty-alt.png">

packages/client/ui-primitives/tests/fixtures/markdown-dom/images.streaming.txt

@@ -0,0 +1,14 @@
+<div class="_markdown_404681">
+  <p>
+    <img alt="https image" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="https://example.com/secure.png">
+  <p>
+    <img alt="http image" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="http://example.com/plain.png">
+  <p>
+    <span class="_imageAlt_404681">
+      #text "relative dropped"
+    #text " and inline "
+    <span class="_imageAlt_404681">
+      #text "bad scheme"
+    #text " end."
+  <p>
+    <img alt="" class="_image_404681" decoding="async" loading="lazy" referrerpolicy="no-referrer" src="https://example.com/empty-alt.png">