# @qipenglin/dsh-theme-spectrum

[中文](README.md) | English

Spectrum is an independently installable theme plugin for DeepSeek Harness Web. It provides ten color presets, each with Light and Dark palettes, while preserving the built-in Light, Dark, and System appearance setting.

## Install

```sh
dsh plugin --profile web add github:qipenglin/dsh-theme-spectrum
```

This installs the plugin directly from the GitHub repository's default branch. The repository includes verified `lib` artifacts, so installation does not execute build scripts. Restart the Web profile after installation. Spectrum appears under Settings → General → Theme style.

### Supply-chain age check

DSH asks pnpm to validate the entire Web profile when any plugin changes. The GitHub source itself does not depend on registry publication age, but installation can still fail on an already-installed dependency that is newer than the active `minimumReleaseAge`. Inspect the named package first. Either wait until it reaches the configured age or, for one audited retry only, disable the age threshold for that command:

```sh
env PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 \
  dsh plugin --profile web add github:qipenglin/dsh-theme-spectrum
```

The environment override is not persisted. A failed add may leave the Git source represented in `pnpm-lock.yaml` or `node_modules` after DSH rolls back the profile manifest; rerunning the same add successfully reconciles that partial state. A peer-dependency warning is informational when the command exits successfully.

## Presets

| Id | Name | Character |
|---|---|---|
| `graphite` | Graphite | Neutral and focused |
| `tide` | Tide | Cool blue and professional |
| `pine` | Pine | Quiet natural green |
| `dune` | Dune | Warm editorial neutrals |
| `vesper` | Vesper | Refined controlled purple |
| `signal` | Signal | Industrial gray and vermilion |
| `brass` | Brass | Cool instrument gray and antique gold |
| `cobalt` | Cobalt | Architectural periwinkle and true blue |
| `rosewood` | Rosewood | Dusty rose and wine red |
| `volt` | Volt | Experimental yellow-green and lime |

Graphite is the default. Preset selection is independent from `ui-theme.preference`, so the ten presets and Light, Dark, or System produce thirty valid combinations. Spectrum changes colors only; layout, typography, spacing, density, radii, and motion remain owned by DSH.

## Extension window theme variables

Ordinary DOM, portals mounted under `body`, and Shadow DOM content that consumes inherited custom properties follow Spectrum automatically, regardless of mount order. Extension authors can use these stable variables:

| Variable | Purpose |
|---|---|
| `--dsh-theme-spectrum-surface` | Window or panel background |
| `--dsh-theme-spectrum-surface-raised` | Card or toolbar background |
| `--dsh-theme-spectrum-surface-overlay` | Menu or floating surface |
| `--dsh-theme-spectrum-border` | Ordinary border |
| `--dsh-theme-spectrum-border-strong` | High-contrast divider |
| `--dsh-theme-spectrum-text` | Primary text |
| `--dsh-theme-spectrum-text-muted` | Secondary text |
| `--dsh-theme-spectrum-accent` | Primary action or accent |
| `--dsh-theme-spectrum-accent-contrast` | Content on the accent |
| `--dsh-theme-spectrum-focus-ring` | Keyboard focus indicator |
| `--dsh-theme-spectrum-hover` | Hover background |
| `--dsh-theme-spectrum-active` | Active background |
| `--dsh-theme-spectrum-code-surface` | File and code background |
| `--dsh-theme-spectrum-terminal-surface` | Terminal container background |
| `--dsh-theme-spectrum-selection` | Auxiliary selection background |
| `--dsh-theme-spectrum-success` | Success state |
| `--dsh-theme-spectrum-warning` | Warning state |
| `--dsh-theme-spectrum-error` | Error state |

Selection color must not be the only selected-state signal; add an outline, icon, check mark, or equivalent non-color indicator. The terminal variable covers the container only. xterm, Monaco, canvas, iframe, hard-coded colors, and closed Shadow DOM require cooperation from their owning plugin and cannot be safely recolored by a global theme.

Spectrum also supplies a small evidence-based compatibility alias catalog for current DSH feature styles, `dshmarket@1.11.3`, and `@deepseek-ai/dsh-profile-plugin-manager@0.1.0-rc.5`. It deliberately does not scan the DOM, observe mutations, target CSS-module hashes, or apply global `!important` rules.

## Configuration

```yaml
ui-theme:
  preference: system
ui-theme-presets:
  preset: graphite
```

The Host face registers the settings schema and injects both palette modes before the Client tree loads. The Client face contributes one reversible `ctx.theme.overrideTokens()` layer and one General settings row. Disposal removes the bootstrap style, theme override, locale dictionary, subscription, and settings row.

## Compatibility

DSH peer dependencies intentionally have no upper version restriction. This release's development lockfile is verified against official DSH `0.1.1-rc.2`; breaking DSH changes are handled in subsequent Spectrum releases. A successful installation-archive test records the exact DSH version in its test output rather than changing the already-tested archive.

## Development

```sh
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build
pnpm run pack:check
```

`pnpm run pack:check` replaces `dist/` with the single verified `dist/qipenglin-dsh-theme-spectrum-0.1.3.tgz` tarball.

`pnpm run test:installed` is an explicit, opt-in default-home test and is not part of ordinary checks. It never publishes or pushes code.

## Known limitations

- The preset catalog is fixed; there is no token editor or preset import format.
- Selection is global to the browser profile, not per workspace or session.
- Non-loopback browsers use the DSH SettingsScope memory policy.
- Unknown third-party hard-coded UI cannot be guaranteed to follow a theme.

## License

Released under the [MIT License](LICENSE).