dsh-ui-container

dsh-ui-container

Reusable visual and service container for DeepSeek Harness browser plugins. It
owns named UI surfaces, document providers, recursive React hosts, and the small
remote protocol needed to connect another frontend without transmitting a DOM
or component tree.

Install the plugin into a DeepSeek Harness profile:

dsh plugin --profile web add github:CH4ACKO3/dsh-ui-container

This command is profile-scoped and can be run from any directory.

Git dependencies run this package's prepare build. With pnpm 10 or newer,
approve the exact package key reported by the first install in the profile's
pnpm-workspace.yaml, then repeat the command. Registry releases and packed
artifacts do not require that approval.

Other browser plugins import its public API from
@ch4acko3/dsh-ui-container/client and inject the uiContainer Cordis service.

Remote transport

@ch4acko3/dsh-ui-container can project a container across a process or
network boundary. The remote contract transfers document snapshots and change
notifications; it never transfers React elements, DOM nodes or a Cordis service
object.

Capabilities

Protocol version 1 negotiates these capabilities during the mandatory
handshake:

• documents resolves URI-based document projections.
• subscriptions subscribes to a URI and sends a small invalidation when its
  projection may have changed.
• surface_commands routes open, reveal and close commands to a mounted surface
  session. A server must opt in to this capability; it is disabled by default.

Document resolution includes an optional known_revision. When it matches the
current server revision, the response is not_modified and contains no document
payload. A change notification contains only the subscription id and URI. The
client then resolves the document again, so network usage follows actual data
changes rather than the size or nesting of the rendered component tree.

All remote document content and metadata must be JSON-compatible. Renderers stay
inside the receiving frontend and render the projection locally.

Cross-process connection

Use MessagePort for a Worker, iframe bridge or host IPC adapter:

const hostChannel = createMessagePortUiRemoteChannel(hostPort)
const clientChannel = createMessagePortUiRemoteChannel(clientPort)

const stopServing = exposeUiContainerRemote(ctx.uiContainer, hostChannel, {
  server: {
    name: 'patchouli-host',
    version: '0.1.0',
    instance_id: crypto.randomUUID(),
  },
})

const remote = await UiContainerRemoteClient.connect(clientChannel, {
  client: {
    name: 'patchouli-window',
    version: '0.1.0',
    instance_id: crypto.randomUUID(),
  },
  protocol_versions: [UI_REMOTE_PROTOCOL_VERSION],
  capabilities: ['documents', 'subscriptions'],
})

const unregister = ctx.uiContainer.documents.registerProvider(
  remote.createDocumentProvider('memory'),
)

Dispose unregister, remote, and stopServing with the lifecycle that owns
the ports.

Network connection

The network owner accepts and authenticates the WebSocket first, then exposes
the container over that socket:

webSocketServer.on('connection', (socket, request) => {
  const principal = authenticate(request)
  if (!principal) return socket.close(1008, 'Unauthorized')

  const channel = createWebSocketUiRemoteChannel(socket)
  exposeUiContainerRemote(ctx.uiContainer, channel, {
    server: {
      name: 'patchouli-host',
      version: '0.1.0',
      instance_id: processInstanceId,
    },
    capabilities: ['documents', 'subscriptions'],
  })
})

A browser client can connect directly:

const remote = await connectUiContainerWebSocket('wss://host.example/ui', {
  client: {
    name: 'patchouli-web',
    version: '0.1.0',
    instance_id: crypto.randomUUID(),
  },
  protocol_versions: [UI_REMOTE_PROTOCOL_VERSION],
  capabilities: ['documents', 'subscriptions'],
})

The transport intentionally does not define authentication. The application
that owns the WebSocket endpoint must enforce authentication, authorization,
TLS and origin policy before calling exposeUiContainerRemote. A server should
enable surface_commands only for principals allowed to control the addressed
frontend session.

Wire contract

Messages are JSON-RPC 2.0. Method names carry their major version:

ui.container.handshake@1
ui.container.document.resolve@1
ui.container.document.subscribe@1
ui.container.document.unsubscribe@1
ui.container.document.changed@1       # server notification
ui.container.surface.open@1
ui.container.surface.reveal@1
ui.container.surface.close@1

The TypeScript definitions in src/client/remote-protocol.ts are the normative
wire schema. A connection permits exactly one handshake, and every later method
must belong to a negotiated capability.