# dsh-themes

English | [中文](README.md)

A **look & theme** plugin for DSH (DeepSeek Harness): built-in palettes, light / dark / follow-system appearance modes, Open VSX search & install, VS Code theme import, persisted theme library.

## Install

```bash
dsh plugin --profile web add dsh-themes
```

Restart dsh web, then use it under **Settings → Themes**. For local development, `bash scripts/install.sh` builds, assembles and installs in one go.

## Compatibility

- Requires DSH `^0.1.5-rc.1 || ^0.2.0-rc.1` (declared through `peerDependencies`, which DSH's plugin compatibility gate evaluates)
- Verified on **0.2.0-rc.2** (current latest), 0.1.7-rc.2, and 0.1.5-rc.2
- Full coverage of the **86 semantic tokens** DSH 0.2.0's UI actually consumes (including `--dsw-alias-state-idle-primary`), so no native DSH colors leak through
- Client toasts use the DSH platform seed-word module `@deepseek-ai/dsh-client-ui-primitives` (nothing extra to install)
- The Host half registers the exact Fetch route `/api/dsh-themes` through `connection.fetch.register`, so DSH's own `/api` prefix route forwards it with the trusted-host fence and browser-session authentication attached
- The old `inject: [webRuntime, webServer]` addition on the `connection` row in a profile's `cordis.patch.yml` is **no longer needed** and can be removed since 0.1.9
- The build-time guard `scripts/check-dsh-compat.mjs` (wired into `pnpm check`) validates the core token set, semantic-token coverage and the `peerDependencies` range so this can't silently drift again

## Development

Source: https://github.com/MangMax/dsh-themes

```bash
bash scripts/install.sh    # build + assemble + install
```

## Features

- **Theme card model**: each theme has light/dark variant slots aggregating all variants of that side; imported extensions become one theme card
- **Default theme fallback**: the DSH native appearance is itself a selectable theme; deleting the in-use imported theme or clicking "Restore default theme" falls back to it
- **Variant selector**: blended color-ball list (like t3code's ThemePreviewCircle); selected ball enlarges in a fixed slot, overflow arrows navigate, active variants show a selection outline
- **Appearance modes**: system / light / dark; light and dark sides can belong to different themes independently
- **Color editor (second-level page)**: rename, light/dark tabs, grouped token color pickers + hex inputs with instant effect, and "Reset edits"
- **Open VSX search & install**: one-request search (60 s TTL cache, 10 s timeout) with icon/author/license/rating, description inline on cards and details batched into one call; debounced input, inline spinner and fade-in results; one-click import downloads, **unzips on demand**, parses (JSONC + `include` merge) and aggregates, with a versioned cache for instant repeats
- **VS Code import**: local extension scan, URL fetch, paste JSON — all four paths accept **JSONC** (comments / trailing commas / BOM); the manifest `uiTheme` overrides a file's `type` so light variants are no longer misclassified; OKLCH-aware engine derives surfaces, workbench-specified values are contrast-gated
- **Toast feedback**: success / failure reports use DSH's native `Toast` (top-center, animated, above every panel) instead of inline text at the bottom of the page
- **Full token coverage**: all 95 color tokens of the DSH design platform (surface layers bg-layer-1~3 / overlays / masks, label layers primary~caption, interactive feedback, buttons, Markdown, status extras, scrollbars, toast/tooltip, sidebar & menu specifics) follow the theme; the "Edit" editor groups them semantically
- **Settings nav icon**: the "Themes" entry in the settings panel gets a palette icon from the reicon icon set (https://github.com/dqev/reicon)
- **Bilingual UI**: settings copy follows the DSH language preference (**Settings → General → Language**), switching live; persisted theme-library data stays language-neutral and is localized at render time
- **Persistence**: theme library saved to `~/.dsh/dsh-themes.json` and restored on restart
- **Cross-platform (Windows / macOS / Linux)**: networking and local files run entirely inside the host process (global `fetch` + node builtins + `fflate` in-memory unzip) — no dependence on shell commands like curl/mkdir/unzip, so it works under Windows (pwsh) too