DSH plugin right sidebar: tab identity and previews
The right sidebar's hardest part is identity, not components: a tab is a (kind, address) pair, not an id. DSH plugin treats the address as content identity and type registration as a ranked claim. Understand both and "the same file opened as two tabs" stops being mysterious.
One dock surface per session
The layout is history computed by a pure planner, and a docked pane is never empty.(source)
Each session has exactly one dock surface, kept in a session-scoped slot store and drawn by rightbar.session. The root-scoped rightbar controller keeps separate seats for the selected Session and for background Sessions owning initialized keepMounted bodies; only the foreground Conversation is visible. Refreshing restores the saved layout.
Every surface change is one history record computed by the kit's pure planner; a docked pane is never empty, and an empty root pane gains the default page chosen from registered guide entries.
A tab type is two registrations sharing a definition id: a static definition in ctx.sidebarRightTabs saying which addresses its kind opens, plus one keyed slot registration supplying its body. The framework injects useTabInfo() for live Sidebar, panel, and tab information; each type keeps its state in the slot store, and packages reference each other's declarations only as types.
The address is a tab's content identity
Resource addresses and page addresses are two families, and callers never compose page addresses.(source)
Every tab opens from one address string, and that address is the tab's content identity.
Resource addresses are URLs of the form dsh-resource://<type>/…: the host names the resource protocol and the rest is that protocol's own path; all protocols share one scheme, so a new protocol adds only a host. A file path starts with its scope: session/<sessionId> followed by a path relative to that session's workspace root, or absolute followed by an absolute path with its leading / removed. The id and every path segment are component-encoded, while a drive letter's : stays literal.
fileAddressFor(sessionId, cwd, path) builds addresses — relative paths or absolute paths inside the workspace become session-relative, other absolute paths become absolute addresses — and parseFileAddress(address) reads the parts back or returns undefined.
Page addresses are what the Sidebar records for tabs opened by kind rather than by resource: sidebar://<kind>, written by the Sidebar itself when openTab(kind) runs. Callers never compose them — guide pages and the file tree call openTab('guide') and openTab('files').
Tab identity is the (kind, address) pair: registry claiming uses the raw address as the record's contentId. So the same address under the same type finds the existing tab, while the same address under two types gives two tabs.
Tab type registration is a ranked claim
No type claiming throws, and that is a wiring error rather than a user error.(source)
ctx.sidebarRightTabs.register(definition) registers one implementation of a type for the caller's lifetime and returns an unregister function; callers place it in their own ctx.effect, so the implementation lives as long as its plugin, and a second registration of the same id throws.
Definitions are static: no runtime hooks, nothing per tab or per session. Key fields:
id— this implementation's identity, unique across registrations; body and title slots register under it;kind— the type's discriminant and the objectopenTabnames; may repeat, and an extension can take over a builtin;patterns— optional resource address globs; a pattern containing:matches the whole address, one without matches the URL path at any depth;priority—extension(default and highest),builtin,fallback;canOpen(address)— optional synchronous veto applied to glob hits;title(address)— chip text captured into the layout record when the tab opens and never rewritten;keepMounted— optional lazy keep-alive so a visited body survives hiding, Session switches, and dock switches.
Routing is a ranked claim. candidates(address) sorts types that match a pattern and are not vetoed: first by tier, then by longest matched pattern, then by registration order. claim(address, kind?) takes the first candidate, or the named kind directly — skipping globs while canOpen still applies — returning { kind, contentId: address, title }. An address no type claims throws.
One kind may carry both a builtin and an extension registration. The extension applies to claiming, get(kind), openTab(kind), and guide pages; the seat finds body and title by the effective definition's id without slot priority involvement; and the builtin returns once the extension unregisters.
Slots and owner props
useTabInfo() fields are all the live information a body receives.(source)
The Sidebar declares four extension slots, plus one keyed document body slot:
| Slot | Cardinality and purpose |
|---|---|
sidebar.right.pane.tab | Keyed by definition id, session scope; supplies a tab body, and a kind without one renders "cannot view this content" |
sidebar.right.pane.tab.title | Keyed by definition id; chip title, optional, falling back to the captured title(address) |
sidebar.right.tab.guide | Chain, session scope; replaces guide tab content rather than the tab |
sidebar.right.tab.menu.item | List, session scope; appended after kit layout actions, and acting items must call the owner's dismiss() |
sidebar.right.tab.document | Keyed by document implementation id; the renderer chosen inside a document tab |
Bodies, titles, and guide replacements receive useTabInfo(), returning { sidebar, panel, tab }: sidebar holds expanded and fullscreen; panel.id identifies the owning pane and the required panel.isFloating distinguishes floating from docked; both update through the hook as tabs move while tab.id stays fixed; tab also holds visible, navigation, signal, and actions.
Lifetime rules to remember: all tabs require the Session to be foreground; docked bodies additionally require expanded and selected; docked titles require expanded; foreground floating windows do not collapse with the whole bar. signal aborts when the record disappears or the plugin unloads, never on hiding or Session switching.
navigation.revision increments on every navigation to that tab, even with unchanged params, so a body can act purely on "navigated again"; address-opened tabs start at 1, and records nobody opened by address (seeded guides, refresh or undo restores) start at 0.
The tab domain holds one occurrence per open record: a record appearing pins its address in the resource model, so switching tabs and unmounting bodies loses nothing; a record disappearing aborts and drops it; an undo-restored record is a new occurrence.
Document previews: selection apart from ownership
Switching renderers changes neither the tab nor the resource address.(source)
The text tab owns the shared Document Preview. Its root registration declares sidebar.right.tab.document and provides ctx.documentPreviews. Renderers register DocumentPreviewDefinition metadata in their own effect, then wait for the slot through ctx.slots.inject('sidebar.right.tab.document', ...) and register components with key: definition.id and their own locale namespace.
The registry records a unique id, extensions, a localized title(), loading, and optional priority and wrap. Suffix matching is case-insensitive, ordering extensions first (the default) then builtins, then comparing suffix length (longer wins) and registration order. Unlike tab kind replacement, the registry keeps every implementation; the toolbar lists matching candidates and remembers the choice per tab. Unknown extensions use plain text.
DocumentPreviewProps derives from PropsRuntime<'sidebar.right.tab.document'>. The owner provides the raw resourceAddress, content, the current wrap, and the declared addResource and setResources callbacks: text content is { kind: 'text', text, pages, eof } and full bytes are { kind: 'bytes', data }. These transient buffers are borrowed read-only and must never enter persistent layout or Session JSON; PDF copies bytes before transferring to a Worker.
Self-loading renderers instead receive { kind: 'renderer', revision, loaded, failed, reload } rather than file bytes. A body calls its own inject face, cancels requests on revision changes and unmounts, and reports the source version it displayed through loaded(version); on load failure it calls failed() so later file changes can trigger a retry. Parents ignore stale reports and keep shared reload and source-change controls.
Workspace Files and built-in types
A file resource pushes metadata only; read content yourself through the remote namespace.(source)
The host's ctx.workspaceFiles and the generated workspaceFiles remote namespace read files the Session filesystem backend allows: stat(path) returns { absolutePath, version, bytes? }; read(path, { offset?, limit? }) returns one page of lines; readBytes(path, { range?, baseFile? }) returns the full file or a byte window within maxFileBytes; list(path) returns direct children inside the workspace root; search(...) searches through the bundled rg; changes(path) watches one target.
dsh-api-workspace-files registers the file provider, with ResourceProtocolMap.file being WorkspaceFileStat directly. Session addresses carry the authorizing Session plus a relative or absolute path, which the host accepts and resolves as-is; a bare absolute address has no authorizing Session and fails with workspace-file/unknown-workspace instead of borrowing the current or tab Session.
Five built-in types exist: guide (builtin, openTab('guide')), text (fallback, dsh-resource://file/**, claiming Session addresses only), files (builtin, openTab('files')), browser (a multi-instance builtin), and subagentchat (builtin, pointing at an addressed subagent Conversation).
Verification: register a document-style tab
Cover claim order, body dispatch, and renderer switching.(source)
- Register an image type with
priority: 'extension', open a*.png, and assert it beatstext's fallback. - Open another address with
openTab('image')and assertcanOpenstill applies. - Open the same address as
textthen asimageand assert two tabs result. - Read
useTabInfo()in the body and assertpanel.isFloatingandtab.navigation.revisionmatch expectations. - Register a type without a body and assert it renders "cannot view this content" rather than crashing.
- Switch the document renderer and assert the tab and resource address are unchanged while only the rendered component swapped.
If step 1 does not beat the builtin, check whether patterns matches the whole address — a pattern without : matches only the path portion.
For full slot and inject rules, see slot hooks and injection; for the client resource model, see client resource lifecycle.
One line to close: a tab is kind plus address, page addresses are written only by the Sidebar, claiming ranks by tier and pattern length, extensions can take over builtins, renderer switches leave tabs alone, and file resources push metadata only.
FAQ
Yes. A DSH plugin tab identity is the pair of kind and address. DSH plugin finds an existing tab for the same address and type, while the same address under two types gives two tabs.
No. DSH plugin captures it once when the tab opens and writes it into the layout record. DSH plugin requires a live title to come from a title slot reading its own store.
Yes. DSH plugin lets an extension take over a builtin kind. DSH plugin applies the extension for claiming, get, openTab, and guide pages, and the builtin returns after unregistering.
No. DSH plugin states that switching renderers changes neither the tab nor the resource address. DSH plugin keeps preview policy separate from resource ownership.
Related Terms
- sidebar.right.pane.tab
- sidebar.right.pane.tab is a session-scoped slot keyed by definition id that supplies one tab's body.— DeepSeek Harness reference - Right sidebar
- useTabInfo
- useTabInfo is a framework-injected hook returning live sidebar, panel, and tab information.— DeepSeek Harness reference - Right sidebar
- DocumentPreviewDefinition
- DocumentPreviewDefinition is renderer metadata: id, extensions, title, loading, and optional priority and wrap.— DeepSeek Harness reference - Right sidebar
- WorkspaceFileStat
- WorkspaceFileStat is the file resource value with absolutePath, version, and optional bytes; it pushes metadata, never content.— packages/client/resources/src/index.ts
Sources
- DeepSeek Harness reference - Right sidebar· deepseek-ai
- packages/client/resources/src/index.ts· deepseek-ai