@yunmin311/dsh-universal-palette

Readme

# dsh-universal-palette

[![npm version](https://img.shields.io/npm/v/@yunmin311/dsh-universal-palette.svg)](https://www.npmjs.com/package/@yunmin311/dsh-universal-palette)
[![GitHub release](https://img.shields.io/github/v/release/yunmin311/dsh-universal-palette.svg)](https://github.com/yunmin311/dsh-universal-palette/releases)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![DSH](https://img.shields.io/badge/DSH-0.1.2--rc.1-2962ff.svg)](docs/COMPATIBILITY.md)
[![node](https://img.shields.io/node/v/%40yunmin311/dsh-universal-palette.svg)](package.json)
[![CI](https://github.com/yunmin311/dsh-universal-palette/actions/workflows/ci.yml/badge.svg)](https://github.com/yunmin311/dsh-universal-palette/actions/workflows/ci.yml)

Language: English | [简体中文](README.zh-CN.md)

A command, session, model, and history surface for DeepSeek Harness Web — one keystroke, everything running in the current workspace.

![The full Global Floating Palette in an active DSH conversation](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/active-global-floating.png)

## Why Universal Palette

DSH grows capabilities through plugins: each release and each community plugin can add Host commands, client command UIs, models, and reference sources. The native surfaces for these live in different places — the slash menu, the model selector, the sidebar, the composer's `@` menu — and none of them answer the one question a keyboard-first user actually has: *what can I do right now, in this workspace, and how do I get there?*

Universal Palette gives that shared search controller two presentations: contextual Composer Search and a global Floating Palette. It owns no second catalog: every command, session, model, and history hit it shows comes from DSH's public Client APIs at query time, so the Palette is automatically correct as DSH and its ecosystem change.

It is built to stay out of the way: DSH's own design tokens, glass over the native surface, locale-following copy, and zero behavior change for anything it does not have a verified public contract with.

## Features

- **Commands** — the complete live Host command catalog, searched and executed through official APIs; new Host commands from DSH or any plugin appear automatically with zero adaptation.
- **Models** — the session's real model directory with the current selection, submitted through the public selection contract.
- **Sessions** — current-first session navigation with stable identity dedupe, no title-based merging.
- **Conversation Hits** — full-text history search via DSH's own session search, with snippet and metadata.
- **Deterministic relevance** — exact-prefix-first scoring with a minimum relevance gate; recency and context only order genuinely relevant rows.
- **Native look and locale** — DSH design tokens, official menu typography and elevation, glass surface, zh/en copy following DSH's locale.
- **Public-contract interoperability** — capability-detected cooperation with community plugins; no private registry reads, no hard dependencies.

## Quick Start

```powershell
dsh plugin --profile web add @yunmin311/dsh-universal-palette@0.2.0
dsh --profile web
```

**Composer search**

- Type `/find` from the native DSH slash menu, or use the Search button. Bare `/` remains owned by DSH.
- The Composer remains the only query input. `/find query` stays in the Composer, while the Search button opens the same search directly from the current draft without inserting `/find`.
- In an active conversation, results appear as a compact DSH-native surface above the Composer.
- In a zero-turn Hero session, Composer Search falls back to Compact Floating because the locked Host does not mount the active Composer overlay surface yet.

**Global search**

- Press `Alt+Q` on Windows/Linux or `Cmd+Shift+K` on macOS.
- This opens the Floating Palette: zero-turn uses the compact variant, while active conversations use the full 600px variant.

Existing custom shortcuts are preserved. `Esc` closes the Palette; outside clicks close a Floating Palette and pass through to DSH.

## Usage

| Gesture | Result |
|---|---|
| `/` | Use the native DSH slash menu |
| Search button or `/find` | Open Composer Search from the Composer: compact DSH-native results above it when active, Compact Floating in a zero-turn Hero session |
| `Alt+Q` (Windows/Linux) or `Cmd+Shift+K` (macOS) | Toggle the Global Floating Palette |
| Type | Fuzzy search across commands, models, sessions, and history |
| `↑↓` | Move selection |
| `Enter` | Open / run the selected row |
| `Tab` | Action panel (infrastructure; current built-in providers expose primary actions only) |
| `Esc` | Close |

## Two search modes

### Composer Search — contextual / embedded

In an active conversation, the Composer stays the only query input and results appear in a compact DSH-native surface directly above it. In a zero-turn Hero session, the same Search button or `/find` entry opens the Compact Floating presentation through Host capability fallback.

![Compact Floating presentation in a zero-turn Hero session](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/zero-turn-compact.png)

![Upward Composer Morph in an active conversation](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/active-composer-morph.png)

### Global Floating Palette — global / navigational

The global shortcut always opens the Floating Palette. Zero-turn uses the compact 540px presentation; active conversations use the full 600px presentation shown at the top of this page.

![Searching the goal command](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/command-search.png)

![A conversation hit with snippet and metadata](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/conversation-hit.png)

## Search surfaces

| Surface | Source contract | Action | Needs active session |
|---|---|---|---|
| Commands | `ctx.remote.commands.list / execute` (official Host catalog) | Execute | Yes |
| Models | `ctx.modelDirectories` (official model directory) | Select | Yes |
| Sessions | `ctx.sessions` (official session controller) | Open | No |
| Conversation Hits | `ctx.sessions.search` (official FTS boundary) | Open | No |

## Community interoperability

Interoperability is verified against real installed plugins — see the [interoperability matrix](docs/INTEROPERABILITY_MATRIX.md).

- **Host command federation: automatic.** Host commands from community plugins (e.g. dsh-tui-command-ext's `/clear` `/rename` `/unarchive` `/compact-fast`, or a `/code-review` plugin) appear and execute with zero adaptation — the Palette reads the live official catalog.

  ![A third-party Host command discovered by exact query](https://raw.githubusercontent.com/yunmin311/dsh-universal-palette/main/docs/assets/readme/interop-command.png)

- **dsh-keys-palette: optional public bridge.** Registers one `universal-palette.open` action on its public `keys.actions` registry so you can bind a shortcut to open the Palette. Absent plugin, zero effect.
- **Tested coexistence:** dsh-tui-command-ext, dsh-session-workbench, dsh-reference-anything, dsh-keys-palette, dsh-market — all verified installed together on real DSH boots.
- **No private coupling.** Session Workbench and Reference Anything publish no public handoff API; the Palette integrates nothing beyond coexistence and documents upstream gaps instead of hacking around them.

This is not "supports all plugins" — only the contracts above are consumed, capability-detected, with zero behavior change when absent.

## For plugin authors

Universal Palette federates DSH's public contracts — you do not integrate with the Palette to become visible in it.

- **Host commands**: register through DSH's official Host command contract (`ctx.commands.register`) and the Palette discovers you automatically from the live catalog on every query. No Palette dependency, no adapter, no release coordination.
- **Deeper interoperability**: an optional, capability-detected adapter is considered only when your plugin exposes a stable public Cordis service. It must be zero-impact when your plugin is absent and lifecycle-safe when it unloads. The working example is dsh-keys-palette's public `keys.actions` registry, which the Palette uses to contribute one bindable "open" action.
- **Client-only `commandUi` commands, private registries, DOM state, and internal routes are off the table** — the Palette keeps plain coexistence there and waits for a public API ([upstream gaps](docs/UPSTREAM_INTEROP_GAPS.md)).
- **Session / reference / workspace plugins**: the same rule applies. A public handoff service or official contract is the only path into Palette secondary integrations; no public seam means `WAIT_PUBLIC_API`.

Universal Palette currently has no Provider SDK, and none is planned. The preferred ecosystem path is: **register with DSH, and the Palette federates public contracts.** Details and verified cases: [interoperability matrix](docs/INTEROPERABILITY_MATRIX.md).

## Compatibility

Verified and locked against `@deepseek-ai/dsh@0.1.2-rc.1` (`deepseek-ai/deepseek-harness@76fda729799fe9b3848dbe2c211d4b231032b81e`). Other DSH revisions are unverified. Details: [COMPATIBILITY.md](docs/COMPATIBILITY.md), [COMMAND_COMPATIBILITY.md](docs/COMMAND_COMPATIBILITY.md).

On the locked DSH `0.1.2-rc.1` Hero surface, session-scoped Composer Morph outlets are not mounted. Universal Palette therefore uses its compact Floating presentation until the first conversation turn, then switches Composer Search to the native upward Morph. This is the approved **Host capability fallback**.

## Privacy & Security

- No telemetry and no analytics.
- No network requests of its own: everything goes through DSH's in-process public Client APIs.
- No credentials read or stored; the demo/acceptance profiles run credential-free by design.
- User preferences (shortcut, frecency) live in browser `localStorage` under the Palette's own namespace.
- History search delegates to DSH's session FTS; its database belongs to the DSH profile, not to this plugin.

## Testing

- `pnpm run check` — typecheck + unit tests (including the Keys Palette bridge lifecycle).
- `pnpm run build` — host ESM face + browser CJS bundle with a purity gate.
- Real DSH acceptance on Windows: official command compatibility gate ([`scripts/command-compat.mjs`](scripts/command-compat.mjs)), multi-plugin coexistence probes ([`scripts/interop-probe.mjs`](scripts/interop-probe.mjs)), and recorded evidence under [`evidence/`](evidence/).

## Known limitations

- Locked to DSH `0.1.2-rc.1`; other revisions are unverified.
- Client-only `commandUi` commands (e.g. popup pickers) are not discoverable — DSH exposes no public enumeration yet ([upstream gaps](docs/UPSTREAM_INTEROP_GAPS.md)).

## Development

```powershell
pnpm install
pnpm run check
pnpm run build
```

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Compatibility](docs/COMPATIBILITY.md)
- [Command compatibility](docs/COMMAND_COMPATIBILITY.md)
- [Design contract](docs/DESIGN_CONTRACT.md)
- [Interoperability matrix](docs/INTEROPERABILITY_MATRIX.md)
- [Upstream interop gaps](docs/UPSTREAM_INTEROP_GAPS.md)
- [Changelog](CHANGELOG.md)

## License

[MIT](LICENSE)