# `@deepseek-ai/dsh-client-web-component`

[English](README.md) | 中文

DSH Web Component adapter 的可安装 profile 组合包。它提供浏览器侧 `webComponent` service，把已注册的 slot tree 挂载为原生 Custom Elements；slot 所有权、typed descriptor、属性/事件绑定、DOM outlet 和 incarnation 生命周期都由 adapter 边界负责。

## 仓库结构

```text
package.json              # 插件包以及 dsh.bundle/dshClient 清单
cordis.patch.yml          # 浏览器 opt-in profile 层
src/index.ts              # host loader entry
src/client/               # 浏览器实现
src/invariant.ts          # package invariant companion
lib/                      # 生成的 host/client 产物
legacy/                   # 旧 DSH 快照的宿主接线补丁，仅作迁移资料
docs/                     # 详细协议文档
tests/                    # 单元、组合和无浏览器进程测试
```

组合包安装后加入一个默认禁用的 `web-component` 行。Web profile 在 slot host 和 browser runtime 都存在时显式启用：

```yaml
- id: web-component
  disabled: false
  name: '@deepseek-ai/dsh-client-web-component'
```

新的 bundle 层只负责组合插件行。Slot host API、descriptor 类型、browser runtime 和 React renderer seam 必须由 profile 所用的 DSH 版本提供；旧宿主源码补丁保留在 `legacy/`，不属于 bundle 契约。

客户端不会向 feature plugin 暴露 live React tree 或原始 DOM context。它使用 plain descriptor，在 incarnation context 中解析声明值，通过 JavaScript property 而不是序列化 attribute 写入元素，并通过声明的 handler 返回 CustomEvent detail。

## 开发

完整 typecheck 需要 sibling DSH checkout：

```text
~/git/deepseek-harness
~/git/web-components
```

```sh
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
```

`prepare` 直接从 `src/` 构建 host 和 browser entry，因此 Git 安装不需要 sibling project references。pnpm 10 可能要求 profile 允许 prepare 脚本；只应批准固定且可信的 checkout。

## 已知限制

- `CustomElementRegistry` 定义是页面生命周期资源，无法注销；adapter 会拒绝替换 constructor。
- 组合包不提供 DOM 或 React renderer，profile 必须先挂载 DSH slot host 和 browser runtime。
- 旧 DSH 快照需要使用 `legacy/` 中的兼容补丁，因为 bundle 不能新增缺失的宿主源码 API；当前 `master` 也还没有 Slots election/incarnation API，完整 typecheck 需要兼容的 Slots 改动（例如 `d97d6a1e`）。