AKS1st/dock

中文

The best workbench base plugin in the DSH ecosystem — no contest. Others reinvent the wheel when they build a workbench; dock hands you a VSCode-grade layout shell, an open registry and a plug-and-play plugin ecosystem. Want a file explorer? Install one. Want a Git graph? Install another. Your DSH gains a whole IDE-class workbench, and dock is the miracle base that ties it all together.

Base plugin for the DSH Web workbench: a VSCode-style layout shell (activity bar / side bar / editor area / panel / status bar) with a registry service (ctx.workbench) that lets feature plugins mount panels, editor views, activity items, status items and commands. This is the base of the dock family: dock-files, dock-editor, dock-images, dock-markdown and dock-git all depend on the workbench shell it provides.

Features

• Activity bar: left vertical strip with registered icon items; clicking switches the side-bar panel.
• Side bar: hosts feature panels (file explorer, Git launcher, ...).
• Editor area: multi-tab editor views (file viewers, Git commit graph, ...).
• Dock mode: the whole workbench docks to any screen edge and supports independent floating windows (draggable / resizable).
• Status bar: bottom status item registration.
• Command system: executeCommand command registration and invocation.
• Layout persistence: panel / floating-window layout is kept in localStorage and restored on reload.
• Settings window: a built-in settings dialog displays settings registered by feature plugins, with validation, ordering, keyboard focus management and persistence across reloads.
• Open registry: registerActivityBarItem / registerPanel / registerEditorView / registerStatusBarItem / registerCommand / registerSetting — each returns a disposer, so wrapping it in ctx.effect cleans up automatically when the plugin is disabled.

Recommended companion plugins (composable — install on demand)

The dock base only provides the workbench shell; concrete capabilities like file browsing and editing live in feature plugins. Each recommendation below is listed one by one: all of them are optional, freely composable, and installed per your actual needs — you do not need all of them.

1. dock-files — file explorer. Mounts a side-bar files panel browsing the session workspace with new/rename/copy-paste/delete, drag-and-drop import, local-file paste and clipboard-image paste. Install it when you want to browse and manage files.
2. dock-editor — text viewer/editor. Undo/redo, Ctrl+S save, unsaved-change confirmation and binary detection; the default text viewer of dock-files. Install it when you want to edit text (requires dock-files).
3. dock-images — image viewer. PNG/JPEG/GIF/WebP/BMP/SVG/ICO/AVIF with safe SVG rendering. Install it when you need to view images (requires dock-files).
4. dock-markdown — Markdown viewer. md/markdown/mdx rendering, document outline, relative-asset resolution and one-click switch to editing. Install it when you often read docs/READMEs (requires dock-files and dock-editor).
5. dock-git — Git history visualization. Swimlane commit graph, branch/tag management, stage/commit/push and remote operations. Install it when you work in repositories; fully independent of file browsing.

Suggested combinations (for reference only — never mandatory):

Scenario	Install
Browse files only	dock + dock-files
Browse + edit text	dock + dock-files + dock-editor
Full file workbench	dock + dock-files + dock-editor + dock-images + dock-markdown
Manage Git too	any of the above + dock-git

Installing dock alone is perfectly fine too — it is a clean workbench shell, ready for you to add components any time.

Settings API

Since 0.2.0, the workbench exposes a public settings-registration API. Feature plugins call ctx.workbench.registerSetting; pass the disposer to ctx.effect so the registration is removed automatically when the plugin is disabled or hot-reloaded. The settings window sorts entries by order (then id), and each editor receives only its current value, an onChange callback and the active locale. Values are validated before they are written:

ctx.effect(() => ctx.workbench.registerSetting({
  id: 'my-plugin:compact',
  pluginId: 'my-plugin',
  // Text may be a plain string or a locale-aware factory.
  title: (locale) => locale === 'zh' ? '紧凑模式' : 'Compact mode',
  defaultValue: false,
  component: CompactToggle,
  validate: (value): value is boolean => typeof value === 'boolean',
}))

pluginId decides which plugin page hosts the setting. A plugin should also register metadata through registerPlugin({ id, title, description, icon, hasEntry }) so the settings window can list it (a missing icon falls back to dock's generic plugin icon). Plugins with a dock entry (hasEntry: true) get an "Open" button and a "Show in dock" switch; a hidden entry can still be opened from the settings window.

Open the settings window from the workbench to edit registered values. Settings are persisted in localStorage under dock:settings and restored after reload. If storage is unavailable or corrupt, the workbench continues with in-memory values and defaults. Plugins can also use getSetting, setSetting and onDidChangeSetting to read, update and subscribe to changes.

General settings

Dock's own options live under "General settings": position, auto-hide, "Reserve space for the dock", and the two magnification factors. The dock icon at the end of the bar opens that settings window:

• Dock position: a four-way segmented switch (left/right/top/bottom) that shares one state with the right-click menu.
• Auto-hide: the bar slides, scales, and fades out when the mouse leaves; a visible edge marker remains so users can discover it and move to the edge to expand it. Disabling auto-hide immediately forces a hidden dock back into view.
• Reserve space for the dock (on by default): only the conversation turn rail is moved left by the measured dock width plus a 24px gap when the dock is on the right; page width and scrollbar position remain unchanged. The offset is recomputed when the bar resizes, the window resizes, or the switch changes, and drops to zero when disabled.
• Hovered icon / neighbour magnification (1.6× / 1.2× by default): the fisheye pop in dock mode, each tunable on its own slider between 1.0–2.5× and 1.0–2.0× in 0.05 steps, applied live while dragging; the neighbour factor never exceeds the hovered one.
• Dock icon: the dock glyph at the end of the bar (three squares on a bar) opens this settings window. Like any other entry it can be hidden under "Plugins → Entry → Dock"; the dock bar's right-click menu still opens settings afterwards.

Dependencies

Dependency	Type	Notes
DSH Web environment	runtime	required, minimum version >=0.1.3-alpha.2. Client platform is Web; installed via dsh plugin --profile web add
cordis ^4.0.0-rc.7	peer	plugin framework (ships with DSH)
react / react-dom ^18.2.0	peer (optional)	needed for client rendering; without them the workbench UI does not activate

dock itself depends on no other dock-family plugin — it is the foundation of the family, and the other five all depend on it.

Install

Requires a DSH Web environment (dsh plugin --profile web add) running Harness 0.1.3-alpha.2 or newer.

Recommended install from the npm registry:

dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
dsh plugin --profile web add dock-editor
dsh plugin --profile web add dock-images
dsh plugin --profile web add dock-markdown
dsh plugin --profile web add dock-git

Or install from GitHub (alternative):

dsh plugin --profile web add github:AKS1st/dock
dsh plugin --profile web add github:AKS1st/dock-files
dsh plugin --profile web add github:AKS1st/dock-editor
dsh plugin --profile web add github:AKS1st/dock-images
dsh plugin --profile web add github:AKS1st/dock-markdown
dsh plugin --profile web add github:AKS1st/dock-git

Or install locally with link: in your profile dependencies. dock provides the ctx.workbench service; feature plugins collaborate through it and install order does not matter (Cordis activates by dependency).

Development

pnpm install
pnpm run build    # tsc declarations + tsdown bundle
pnpm run check    # type-check only

Plugin contract

src/client/contract.ts is the public workbench contract (WorkbenchService, ViewProps, EditorOpenSeed, ...). Feature plugins import it type-only (erased at build time); all runtime collaboration happens through ctx.workbench method calls. Each feature plugin carries a vendored copy of this contract — keep it in sync when changing this file.

License

MIT