@deepseek-ai/dsh-client-ui-action-cards 0.0.0-stage → 0.2.2-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,40 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/client-ui-action-cards/README.md
+/:
+  en: eec43de9002f4ab1
+  zh: 0d2fddca5a1f993a
+/deepseek-ai-dsh-client-ui-action-cards:
+  en: c36a554629f96f79
+  zh: 0ea837da87938e52
+/deepseek-ai-dsh-client-ui-action-cards/summary:
+  en: 89ea57734c42a481
+  zh: c7a4f5f0b59b78ad
+/deepseek-ai-dsh-client-ui-action-cards/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: b00dddf4c88f0a45
+/deepseek-ai-dsh-client-ui-action-cards/use-this-package:
+  en: 717a53d2170d253b
+  zh: 4e52852690601371
+/deepseek-ai-dsh-client-ui-action-cards/use-this-package/register-a-card-body:
+  en: 9ec9f9f8f3165d3e
+  zh: 2d8154ec2fe0c9ab
+/deepseek-ai-dsh-client-ui-action-cards/understand-the-implementation:
+  en: 168ae39a83d6f4eb
+  zh: 312cc12876bca834
+/deepseek-ai-dsh-client-ui-action-cards/further-exploration:
+  en: 55e4d74a33cdeeb3
+  zh: f601d5a4dcf63ec5
+/deepseek-ai-dsh-client-ui-action-cards/model-experience:
+  en: f80a4b656c108f22
+  zh: a3e30f46fa7136ac
+/deepseek-ai-dsh-client-ui-action-cards/model-experience/kv-cache-effect:
+  en: 9cb7131bde146341
+  zh: 1c7d1af00f58004d
+/deepseek-ai-dsh-client-ui-action-cards/known-limitations-and-deferred-work:
+  en: df94821940e4e2b8
+  zh: 490441ab06b153c9
+/deepseek-ai-dsh-client-ui-action-cards/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: bd8a8936229e035e

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+---
+description: "Browser half of optional action cards: the card frame below completed answers, the body registry that experiment packages fill, and the one-line process row of propose_action calls."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-client-ui-action-cards
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Users see an optional action card below a completed answer: its title, a brief that folds when long, and the controls of the experiment that proposed it. In the process area, the proposal shows as one row with the card title and whether the call was accepted; a refused call expands to its reason. A card whose experiment provides no controls in this browser offers only Not now. Showing, expanding and folding cards make no model request.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Enable the [Personalized recommendations](../personalized-recommendations/README.md) bundle, which inserts this package beside its [Host service](../action-cards/README.md). This browser contribution has no configuration fields.
+
+### Register a card body
+
+A kind's browser plugin injects `actionCards` and registers its body inside its own `ctx.effect`: `ctx.actionCards.register({ action, locale, Body })` returns the disposer. The frame renders `Body` for cards of that action with the card, its recorded or derived decision, the Session id, the frame's title and folded brief as `summary`, the frame's fold component as `Folded`, an `act(verb, payload?)` bound to the card, and a translator `t` for the body's own locale namespace. The body places `summary` in its own layout and owns its header, controls, status and footer. A second body for the same action is a registration error.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+One `conversation.chat.turnTail` entry reads the `actionCards` Session projection and shows the card admitted in its Turn after that Turn has ended with a final answer; a Turn that ends without answer text shows no card, and should several cards share a Turn, the lowest call id is shown. The frame sets `data-action-card` to the call id and names its region by the card title. Folding counts a wide grapheme, such as a Chinese character, as two Latin-letter widths and folds after about 260; it never measures layout or alters the full text.
+
+A `tool.call.toolview` entry keyed `propose_action` renders the process row from the recorded call arguments and result. The plugin provides the body registry at its top level, then mounts the generated `actionCards` Remote and registers its dictionaries and slot entries for the same lifetime.
+
+| Source | Contents |
+|---|---|
+| [`src/client/mount.ts`](src/client/mount.ts) | Registry, Remote, dictionaries and slot entries |
+| [`src/client/Card.tsx`](src/client/Card.tsx) | Turn tail, frame, fold and fallback body |
+| [`src/client/ProposeRow.tsx`](src/client/ProposeRow.tsx) | Process row |
+| [`src/client/registry.ts`](src/client/registry.ts) | Body registry and body props |
+| [`tests/`](tests/) | Placement, frame, fallback, row and registration tests |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Action cards](../action-cards/README.md) — the tool, card state and user actions behind the frame.
+- [Personalized page cards](../client-ui-creation-recommendations/README.md) and [recommendation cards](../client-ui-plugin-recommendations/README.md) — the shipped card bodies.
+- [Slots](../../client/ui-slots/README.md) — Turn tail and tool row registration.
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the Host card service: card actions reach it as Remote calls, and it owns the logged tool, decisions and status notice.
+
+#### KV Cache effect
+
+Rendering cards and process rows does not change any model request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- A card whose action has no registered body offers only Not now, so its experiment's other actions need that experiment's browser plugin. Not now still works after the experiment's Host plugin is turned off.
+- The Turn tail shows one card per Turn, matching the Host rule of one card per turn.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,89 @@
+---
+description: "可选操作卡片的浏览器端：已完成回答下方的卡片框架、供各实验包填入的正文注册表，以及 propose_action 调用的单行过程行。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-action-cards
+
+[English](README.md) | 中文
+
+## 概述
+
+用户在已完成的回答下方看到一张可选操作卡片：标题、过长时会折叠的说明，以及提议该卡片的实验所提供的控件。在过程区中，提议显示为一行，带卡片标题和调用是否被接受；被拒绝的调用可以展开查看原因。如果实验在当前浏览器中没有提供控件，卡片只提供“暂不需要”。展示、展开和折叠卡片都不会发起模型请求。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [实现原理](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+启用[个性化推荐](../personalized-recommendations/README.zh.md) Bundle，它会在本包旁插入对应的 [Host 服务](../action-cards/README.zh.md)。本浏览器组件没有配置字段。
+
+### 注册卡片正文
+
+种类的浏览器插件注入 `actionCards`，并在自己的 `ctx.effect` 中注册正文：`ctx.actionCards.register({ action, locale, Body })` 返回注销函数。框架为该动作的卡片渲染 `Body`，并传入：卡片、已记录或推导出的决定、会话 id、框架渲染的标题与折叠说明 `summary`、框架的折叠组件 `Folded`、绑定到该卡片的 `act(verb, payload?)`，以及正文自己语言命名空间的翻译函数 `t`。正文把 `summary` 放进自己的布局，并负责自己的标题栏、控件、状态和底部操作。为同一动作注册第二个正文属于注册错误。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 实现原理
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+一个 `conversation.chat.turnTail` 条目读取 `actionCards` 会话投影，在某一轮以最终回答结束后展示该轮接受的卡片；没有回答文本就结束的轮次不显示卡片，若同一轮有多张卡片，显示调用 id 最小的一张。框架把 `data-action-card` 设为调用 id，并以卡片标题命名所在区域。折叠时，宽字素（如汉字）按两个拉丁字母宽度计算，约 260 个单位后折叠；折叠不测量布局，也不改动完整文本。
+
+一个以 `propose_action` 为键的 `tool.call.toolview` 条目，根据记录的调用参数和结果渲染过程行。插件在顶层提供正文注册表，然后挂载生成的 `actionCards` Remote，并在同一生命周期内注册词典和插槽条目。
+
+| 源码 | 内容 |
+|---|---|
+| [`src/client/mount.ts`](src/client/mount.ts) | 注册表、Remote、词典与插槽条目 |
+| [`src/client/Card.tsx`](src/client/Card.tsx) | 轮次尾部、框架、折叠与兜底正文 |
+| [`src/client/ProposeRow.tsx`](src/client/ProposeRow.tsx) | 过程行 |
+| [`src/client/registry.ts`](src/client/registry.ts) | 正文注册表与正文属性 |
+| [`tests/`](tests/) | 位置、框架、兜底、过程行与注册测试 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [操作卡片](../action-cards/README.zh.md) — 框架背后的工具、卡片状态与用户操作。
+- [个性化页面卡片](../client-ui-creation-recommendations/README.zh.md)和[推荐卡片](../client-ui-plugin-recommendations/README.zh.md) — 随产品提供的卡片正文。
+- [插槽](../../client/ui-slots/README.zh.md) — 轮次尾部与工具行的注册。
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接影响来自 Host 卡片服务：卡片操作以 Remote 调用到达该服务，由它负责记录在日志中的工具、决定和状态通知。
+
+#### KV Cache 影响
+
+渲染卡片和过程行不会改变任何模型请求。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 动作没有注册正文的卡片只提供“暂不需要”，该实验的其他操作需要它的浏览器插件。即使该实验的 Host 插件已关闭，“暂不需要”仍然可用。
+- 轮次尾部每轮只显示一张卡片，与 Host 每轮一张卡片的规则一致。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作背景——点击展开</summary>
+
+无。
+
+</details>