feat(client): inject slot declaration lifetimes

2026-08-05 23:38:29 +08:00
parent bb53e25ed0
commit 86965b053c
100 changed files with 1065 additions and 837 deletions
@@ -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/host/directory-picker-native/README.md
-README.md: 0ff5524791094095550542de9bb525a4a633f5b5
-README.zh.md: 19915340c14249ae07d56001911165841dd550d2
+README.md: 4dd0c79d080fe097d063cfd2200e30aafc2d2d42
+README.zh.md: 8ebf2a6e978ad042e522e7e2831a508501d3eca5
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 The **native-OS-chooser backend** of the [directory-picker seam](../directory-picker/README.md): `NativeDirectoryPicker` registers `ctx.directoryPicker` with the `native` capability, whose `pick(signal)` opens one native chooser per call and resolves the chosen absolute path (`null` on cancel). Platform tools run without a shell: `osascript` on macOS and Zenity with a KDialog fallback on Linux; the caller's abort terminates the native process. Windows opens the modern `IFileOpenDialog` in a spawned child process — a koffi-driven COM conversation on the child's main thread with the best thread DPI awareness the host accepts (per-monitor-v2 first), aborted by posting `WM_CLOSE` to the dialog thread. Only viable when the operator sits at the host's display — remote deployments compose [`-browse`](../directory-picker-browse/README.md) instead. The command boundary (`DirectoryPickerRunner`) and platform facts are injectable. The shared no-shell subprocess runner lives in [`dsh-native-command`](../../util/native-command/README.md).

-**Dual-face package**: the browser half (`./client`) registers a renderless flow occupant into [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes — each `open` request drives `host.pickDirectory` and reports the one outcome (picked path / cancel / failure) through the hole's owner conversation. One cordis.yml row therefore composes both sides of the native interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).
+**Dual-face package**: the browser half (`./client`) registers a renderless flow occupant into [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes — each `open` request drives `host.pickDirectory` and reports the one outcome (picked path / cancel / failure) through the hole's owner conversation. Both directory-flow declarations must be live before either contribution installs. One cordis.yml row therefore composes both sides of the native interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).

 ## Model Experience

@@ -4,7 +4,7 @@

 [目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。

-**双面包**：browser half（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并经洞的 owner 会话上报唯一结果（所选路径／取消／失败）。因此一行 cordis.yml 同时组合原生交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+**双面包**：browser half（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并经洞的 owner 会话上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于 live 状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。

 ## 模型体验

@@ -7,7 +7,6 @@
 * both sides of the native interaction with one cordis.yml row; no client
 * code branches on a capability kind.
 */
-import { deferGroupRegistration } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 // Type-only: pulls the SlotMap merge declaring the directory-flow holes.
 import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
@@ -20,22 +19,22 @@ export const inject = ['slots', 'workspaces']

 /**
 * Client plugin body: register the renderless native flow into both
- * directory-flow holes (declaration-aware deferral — the declaring
- * ui-workspace entries may activate later, and an HMR collapse re-declares).
+ * directory-flow holes through `slots.inject()` because the ui-workspace
+ * entries may activate later or replace their declarations.
 * @param ctx - client root context.
 */
 export function apply(ctx: ClientContext): void {
  const injected = (): NativeFlowInjected => ({ pick: () => ctx.workspaces.pickDirectory() })
-  ctx.effect(() => {
-    // One occupant, both holes, as a unit: construction or late conflicts
-    // (holes declared after rival providers activated) roll the whole pair
-    // back and fail loud — semantics owned by deferGroupRegistration.
-    const group = deferGroupRegistration(
-      ctx.slots,
-      ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const,
-      NativeDirectoryFlow,
-      name => ctx.slots.register({ name, inject: injected }, NativeDirectoryFlow),
-    )
-    return () => { group.dispose() }
-  }, 'directory-picker-native: flow registrations')
+  // Both declaration lifetimes must be live before the pair installs; the
+  // generator makes the two registrations one transactional effect. The
+  // outer/inner nesting order is arbitrary; neither hole has precedence.
+  ctx.slots.inject('conversation.hero.workspace.directoryFlow', () =>
+    ctx.slots.inject('sidebar.workspaces.directoryFlow', function* () {
+      yield ctx.slots.register({
+        name: 'conversation.hero.workspace.directoryFlow', inject: injected,
+      }, NativeDirectoryFlow)
+      yield ctx.slots.register({
+        name: 'sidebar.workspaces.directoryFlow', inject: injected,
+      }, NativeDirectoryFlow)
+    }))
 }
@@ -56,7 +56,16 @@ describe('directory-picker-native client half', () => {
    for (const hole of HOLES) expect(after.slots.entries(hole)).toHaveLength(1)
  })

-  it('rolls back wholesale and reports loudly when a rival provider wins after deferred activation', async () => {
+  it('fails loudly instead of deduplicating a duplicate package row', async () => {
+    const b = await bench()
+    b.declare()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const duplicate = b.ctx.plugin({ inject: [...inject], apply })
+    await expect(duplicate.await()).rejects.toThrow(/already has a registration/)
+    for (const hole of HOLES) expect(b.slots.entries(hole)).toHaveLength(1)
+  })
+
+  it('rolls back wholesale and reports loudly when a rival injection wins declaration activation', async () => {
    const b = await bench()
    const rejections: unknown[] = []
    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
@@ -64,15 +73,14 @@ describe('directory-picker-native client half', () => {
    process.on('unhandledRejection', onUnhandled)
    process.on('uncaughtException', onUnhandled)
    try {
-      // This provider activates BEFORE any hole exists: both deferrals wait.
-      // (Duplicate rows of the SAME package converge silently — the deferral
-      // skips a hole its own component already occupies; the conflict needs
-      // a rival provider.)
+      // The rival subscribes first, so synchronous declaration notifications
+      // let it occupy the pair before this provider's waiting injection runs.
+      b.slots.inject(HOLES[0], () => b.slots.inject(HOLES[1], function* () {
+        yield b.slots.register({ name: HOLES[0] } as never, () => null)
+        yield b.slots.register({ name: HOLES[1] } as never, () => null)
+      }))
      await b.ctx.plugin({ inject: [...inject], apply }).await()
      b.declare()
-      // A rival occupies both holes ahead of the pending microtask flush.
-      b.slots.register({ name: HOLES[0] } as never, () => null)
-      b.slots.register({ name: HOLES[1] } as never, () => null)
      await new Promise(resolve => setTimeout(resolve, 20))
      // The rival keeps both holes; this provider rolled back wholesale and
      // surfaced the conflict on the fail-loud channel — no partial mix.
@@ -97,11 +105,11 @@ describe('directory-picker-native client half', () => {
    }
  })

-  it('rolls back the first deferral when the second hole is already occupied', async () => {
+  it('rolls back the outer injection when the second hole is already occupied', async () => {
    const b = await bench()
    b.declare()
    // Foreign occupant in the SECOND registered hole: the pair construction
-    // throws after the first deferral installed its subscription.
+    // throws after the outer injection installed its subscription.
    b.slots.register({ name: HOLES[1] } as never, () => null)
    const rejections: unknown[] = []
    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }