dsh-theme-lab

Readme

# DSH Theme Lab

> **Unofficial community project — not affiliated with or endorsed by DeepSeek.**

A modular theme collection and starter kit for the preview release of [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). Theme Lab adds a native Settings selector, persistent choices, semantic light/dark palettes, and responsive artwork that appears only before the first message.

| Event Horizon | Cyber Sakura |
| --- | --- |
| ![A violet black hole on a dark background](assets/event-horizon.webp) | ![A neon night garden with pink blossoms](assets/cyber-sakura.webp) |
| Obsidian Gold | Digital Rain |
| ![A black architectural space with a gold portal](assets/obsidian-gold.webp) | ![Abstract green digital rain on black](assets/digital-rain.webp) |

## Interface preview

### Cyber Sakura chat

![Cyber Sakura applied to the DeepSeek Harness chat](docs/images/cyber-sakura-chat.jpg)

### Theme selector

![Cyber Sakura selected in DeepSeek Harness settings](docs/images/cyber-sakura-settings.jpg)

Cyber Sakura in the native Harness theme selector, with its matching chat palette active behind Settings.

## Features

- Four custom themes plus the untouched DeepSeek Harness default.
- One data-driven registry for cards, palettes, artwork, and asset routes.
- Exactly 16 inspected semantic tokens per custom theme, with light and dark values.
- Native Settings persistence through the Harness connection service—no `localStorage` fallback.
- Responsive WebP hero artwork scoped to `[data-phase='hero']` only.
- Reversible token overrides and complete cleanup when selecting the default or unloading.
- A small Creator fallback for trying the Event Horizon palette without artwork or Settings.

## Compatibility and prerequisites

Theme Lab 1.0.0 targets **DeepSeek Harness `0.1.1-rc.2`** and Node.js 22. Harness is currently preview software: its plugin APIs can change without notice, so review the compatibility note before upgrading either project.

You need:

- an existing local DeepSeek Harness installation;
- Node.js 22 and pnpm through Corepack;
- access to the active Harness profile directory and its `cordis.patch.yml`.

## Install from source

```sh
git clone https://github.com/Slymaster/dsh-theme-lab.git
cd dsh-theme-lab
corepack enable
pnpm install --frozen-lockfile
pnpm bundle
pnpm link --global
```

Link the package from the active DeepSeek Harness profile directory:

```sh
pnpm link --global dsh-theme-lab
```

Merge the single row from [`cordis.patch.yml`](cordis.patch.yml) into the profile patch:

```yaml
- insert:
    - id: dsh-theme-lab-live
      name: dsh-theme-lab
```

Keep exactly one Theme Lab row. The package manifest exposes the Web client automatically.

### Updating a running profile

Harness may discover disabled client modules, so do not leave an old Theme Lab alias beside the new one. For a safe hot update:

1. Remove the existing Theme Lab row completely and wait until the Harness boot graph contains no Theme Lab module.
2. Rebuild/link the new package, insert the single row above, and wait for HMR.

This two-phase procedure avoids stale Host ESM cache and duplicate client registrations. A browser that loaded the old boot graph may need one refresh. If your Harness build does not apply Host changes through HMR, follow its current restart guidance instead of assuming hot replacement is supported.

## Choose a theme

Open **Settings → General → Interface theme**, then choose DeepSeek original, Event Horizon, Cyber Sakura, Obsidian Gold, or Digital Rain. The selection is stored in the native `dsh-theme-lab` Settings namespace and should survive a page reload.

## Create your own

Follow [Creating a theme](docs/creating-a-theme.md). A new theme is one registry entry, one optimized WebP, and a complete 16-token palette. No controller branch is required.

## Creator fallback

[`client.js`](client.js) is intentionally limited: it applies only the Event Horizon token palette. It has no hero artwork, theme selector, or persistence. Use the installable package for the complete experience.

## Uninstall

1. Select **DeepSeek original** in Settings.
2. Remove the `dsh-theme-lab-live` row from the profile patch.
3. Unlink the package from the profile with `pnpm unlink dsh-theme-lab`.
4. Optionally remove the global link from the cloned project with `pnpm unlink --global`.

Unloading calls the token, hero, slot, and subscription disposers. The saved `dsh-theme-lab` preference can remain harmlessly in the Harness Settings document.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| No theme cards | Confirm the profile has one `dsh-theme-lab` dependency and one Host row, then inspect the boot graph. |
| Choice changes but resets on reload | Ensure both `connection` injections in `package.json` and `src/client/index.ts` are still present. |
| Artwork returns 404 | Rebuild and check `/plugins/dsh-theme-lab/<theme-id>.webp`; routes are exact and case-sensitive. |
| Duplicate cards or stale styles | Remove all old aliases, use the two-phase update above, then refresh once. |
| Theme covers an active conversation | Confirm custom CSS still targets only `[data-phase='hero']`. |

When reporting a problem, include the Harness version, Node version, browser console error, and a redacted boot-graph excerpt. Never post secrets or private profile data.

## Development

```sh
pnpm bundle
pnpm test
npm pack --dry-run --json
```

The validator exercises the registry, settings namespace, persistence wiring, cleanup, contrast, exact routes, package contents, and deterministic bundles.

## Project links

- [DeepSeek Harness upstream](https://github.com/deepseek-ai/deepseek-harness)
- [Theme Lab issues](https://github.com/Slymaster/dsh-theme-lab/issues)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Artwork provenance](ASSETS.md)
- [Third-party notices](THIRD_PARTY_NOTICES.md)

## Roadmap

- Compatibility checks for future Harness preview releases.
- Community theme gallery and reusable palette validation.
- Import/export format for theme definitions.
- Automated browser-level smoke testing when upstream exposes a stable test harness.

## License

MIT © Slymaster. See [LICENSE](LICENSE). DeepSeek Harness remains governed by its own license; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).