dsh-client-ui-details-host

English | 中文

Portable DSH/Cordis Client plugin that hosts one active details surface in the AppFrame details column. The package is platform:web UI infrastructure with no Electron, Node, or Desktop dependency. The npm scope @dsh-electron/ identifies the publisher, not a runtime requirement.

This repository is the canonical source. DeepSeek Harness Desktop mirrors it with git subtree and mounts Details Host as required built-in infrastructure. The same package runs unchanged in DeepSeek Harness Desktop and in a standard DSH Web host.

Installation

The package is in experimental development. A public npm release under @dsh-electron/dsh-client-ui-details-host is planned; until then, install from this repository.

DeepSeek Harness Desktop — Details Host is always enabled. No separate install step.

DSH Web — add the package to a profile after building lib/:

pnpm install
pnpm build
dsh plugin --profile web add .

Or install directly from GitHub:

dsh plugin --profile web add github:cherrchen/dsh-client-ui-details-host

dsh plugin add activates the bundled cordis.patch.yml layer, which inserts the plugin row into the composed configuration. No manual cordis.yml edit is required.

The Client half resolves through the package exports["./client"] entry. Peer dependencies (@deepseek-ai/dsh-client-runtime, @deepseek-ai/dsh-client-ui-layout, @deepseek-ai/dsh-client-ui-slots, and React) must already be present in the host composition.

User experience

Loading Details Host does not open the details column. The upstream DetailsPanel remains visible until a consumer calls ctx.shellDetails.open().

End users see the AppFrame third column only after a feature plugin opens a registered shell.details.surface. Details Host supplies the column chrome (resize handle, close control, header actions) and routes the active surface body. Closing the column returns control to the upstream DetailsPanel.

Public API

ctx.shellDetails

The Client plugin provides ctx.shellDetails, a ShellDetailsController with apiVersion 2 and the full P2 features set. Import types and constants from @dsh-electron/dsh-client-ui-details-host/client.

Method / property	Role
open(id)	Open a registered surface by id (compatibility overload).
open({ surfaceId, payload?, navigation? })	Preferred open form when the surface needs arguments or navigation mode.
close()	Close the column, clear session navigation, and restore the upstream occupant. Idempotent.
back() / canGoBack()	Restore the previous instance from the session back stack.
toggle(id)	Open when inactive; close when already active.
registerSurface(descriptor)	Optional lifecycle and dedupe metadata for a surface id.
getSnapshot() / subscribe()	Reactive state for useSyncExternalStore.

Key slot constants: DETAILS_SURFACE_SLOT (shell.details.surface) and DETAILS_HEADER_ACTIONS_SLOT (shell.details.header.actions).

Surface contributions

Other Client plugins register renderable surfaces with declaration-aware injection:

ctx.slots.inject('shell.details.surface', () =>
  ctx.slots.register({
    name: 'shell.details.surface',
    id: 'example.alpha',
    label: 'Example Alpha',
  }, ExampleSurface))

// ExampleSurface props include detailsInstance from PropsRuntime<'shell.details.surface'>

Optional payload typing uses declaration merging on the Client entry:

declare module '@dsh-electron/dsh-client-ui-details-host/client' {
  interface DetailsSurfacePayloadMap {
    'example.alpha': { tab?: string }
  }
}

Unknown external surfaces and payloads remain supported without augmentation.

Composition rules

The Host plugin is an empty Loader seat. The Client plugin requires slots, layout, and sessions.

open() validates the surface, creates a surface instance, registers DetailsHost into the single details slot at a lower shadowing priority than the upstream occupant, verifies DetailsHost won the cell, commits the instance, and then calls ctx.layout.openDetails(). Missing or duplicate surface ids, and takeover conflicts, throw typed errors and roll back. Switching to another registered id keeps DetailsHost mounted and does not close the column.

Each session keeps an in-memory active instance and bounded back stack (default push, optional replace, with back() and dedupe). Panel geometry stays with ctx.layout; this package only occupies details while a surface is open.

Unloading the active surface, switching the current session, a surface render crash, or unloading Details Host all close takeover and restore the upstream occupant.

npm publication

The package will publish to npm as @dsh-electron/dsh-client-ui-details-host. Publication is not available yet; treat API and versioning as pre-release.

Development

Use Node.js ^22.19 or >=24 with pnpm 11.

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

Model Experience

None, as this package contributes human-facing Client UI infrastructure without registering model tools or prompt content.

KV Cache effect

None. The package does not add, replace, or retain model-request tokens.

Known Limitations and Deferred Work

• Single active surface — only one shell.details.surface instance renders at a time; split, stacked, or pinned details columns are not implemented.
• Memory-only session state — navigation history is cleared on process restart; there is no localStorage, IndexedDB, or file persistence.
• Windows Desktop caption clearance — when the host document root carries data-dsh-desktop-platform="win32", the details header increases top padding so its close control clears the Window Controls Overlay. Other platforms keep the default header padding.