dsh-image-skin

dsh-image-skin

English | 中文

A DeepSeek Harness web plugin: set a background image and adapt the UI's text, background, brand and border colors to the image palette automatically.

Built with DeepSeek Harness.

Screenshots

Features

• Background image — pick any image (auto-downscaled to a 1600px JPEG for storage).
• Palette adaptation — extracts the image's average + dominant colors and derives a full set of --dsw-alias-* / --dsw-specific-* theme tokens (background surfaces, primary/secondary/tertiary labels, brand, borders, buttons, code blocks, the sidebar) in both light and dark modes, respecting your existing light/dark preference.
• Contrast guarantee — derived text colors are checked against their surface with WCAG relative luminance (primary/secondary ≥ 4.5:1, tertiary/caption ≥ 3:1) and nudged darker/lighter when short.
• Opacity slider — controls the main surface opacity; layered surfaces (menus/popovers/sidebar) only ease slightly and stay ≥ 80% opaque.
• Image fit — cover / contain / stretch.
• Scrim — a hue-tinted white/black veil over the image for readability on busy pictures.
• Auto light/dark — optional "follow image" switch: bright images get the light scheme, dark images the dark scheme; disabling it or removing the skin restores your previous light/dark/system preference (via a registered empty-token scheme-carrier theme, so your durable preference is never overwritten).
• Persistence — image + options live in localStorage and restore on refresh.
• Settings section — registers a "Skin" page (settings.section) with zh/en copy that follows the DSH language setting.

How it works

Everything goes through two official seams — no DOM-structure surgery and no hard-coded product selectors:

1. ctx.theme.overrideTokens(source, tokens) stacks a token layer over the active theme ({ '--dsw-alias-xxx': { light, dark } }). The theme presenter writes those tokens as inline CSS variables on <body>, so the whole app recolors. Removing the skin calls the returned disposer to restore the theme.
2. One injected static CSS rule — body { background-image: … }. The image URL, fit and scrim ride custom tokens (--dsh-skin-bg-*), so the theme layer owns them and tears them down with the layer.
3. ctx.theme.register + ctx.theme.setTheme (auto light/dark) — with "follow image" on, a scheme-carrier theme (colorScheme: light|dark, empty tokens) is registered and made active; the real colors still come from the override layer. Only the built-in light/dark/system preferences are persisted, so the in-process auto id never overwrites your durable preference, and leaving auto restores the prior one.

Layout

src/index.ts                # host half: no-op mount point
src/context-types.ts        # structural ctx mirror + @deepseek-ai/cordis augmentation
src/client/index.tsx        # client half: overrideTokens + CSS + settings section
src/client/SkinSettings.tsx # settings UI (upload / preview / opacity / remove)
src/client/theme.ts         # palette → token overrides
src/client/extract.ts       # image downscale + palette extraction (canvas)
src/client/color.ts         # pure color math (RGB/HSL/luminance)
src/client/store.ts         # localStorage persistence
cordis.patch.yml            # bundle patch (mounts the plugin into a profile)
scripts/build.mjs           # esbuild build (host ESM + wrapped client bundle)
scripts/smoke.mjs           # smoke test (host exports + client bundle contract)

Development

Requires Node.js ≥ 22.13 (pnpm 11's requirement) and pnpm 11.

pnpm install
pnpm build        # emits lib/index.js and lib/client.js (esbuild + tsc declarations)
pnpm typecheck    # tsc --noEmit
pnpm smoke        # smoke test: host exports + client bundle contract (no browser)

Compatible DSH versions

DSH checks a bundle's declared @deepseek-ai/dsh-* peerDependencies against its own runtime version before loading it, so check out the tag that matches the DSH you run:

git checkout v1.1.0    # for dsh 0.2.x
git checkout v1.0.0    # for dsh 0.1.x

Switching tags needs no rebuild: they differ only in the manifest (peerDependencies, dsh.client.inject, version) and in type-erased sources, so the emitted lib/ bundle is the same. For development, run pnpm install after switching — pnpm-lock.yaml is kept per tag.

These git checkout steps apply to a local clone mounted with link:. There is no in-place "switch version" in dsh plugin: it forwards its arguments to pnpm, so changing the installed version means changing the dependency spec (pnpm add <spec> inside the profile, or remove + add). The profile then restarts on the new copy; a git spec is compatibility-checked only after pnpm runs, and an incompatible tag is rejected and rolled back (see below).

A github: install builds itself: package.json declares prepare: pnpm build, and pnpm runs prepare on a fetched git dependency. pnpm 11 blocks that script until the package is allowlisted, so the first attempt fails on purpose and prints the exact key to add (see "Install from GitHub" below). Use the link: flow for development.

If the DSH log says skipping profile bundle "dsh-image-skin", the checked-out tag does not match the running runtime: switch tags rather than granting the dsh plugin allow-version exemption.

Install into your web profile

Local development (link, recommended)

cd <this repo>
pnpm install && pnpm build

# one step: install AND auto-mount (no manual file edits)
dsh plugin --profile web add link:<absolute path to this repo>

Then restart DSH and hard-refresh the browser (Ctrl/Cmd+Shift+R). dsh plugin detects dsh.bundle.patch and appends the package to dsh.profile.bundles automatically.

GitHub tag (no local clone)

# 1. first attempt fails and prints the exact allowBuilds key it needs
dsh plugin --profile web add github:YouHui1/dsh-image-skin#v1.1.0

# 2. paste that key into ~/.dsh/profiles/web/pnpm-workspace.yaml, then retry
#    allowBuilds:
#      'dsh-image-skin@github:YouHui1/dsh-image-skin#<sha>': true
dsh plugin --profile web add github:YouHui1/dsh-image-skin#v1.1.0

The key must match what pnpm printed, including the commit SHA: pnpm resolves the tag to a commit, and a repo-level key such as github:YouHui1/dsh-image-skin does not match. A different tag, or a moved tag, means a different SHA, pnpm prints a new key, and step 1 is repeated. prepare itself runs pnpm build, so the machine doing the install needs Node ≥ 22.13 and registry access for the devDependencies.

This repo is not published to npm (package.json has "private": true) — local use just needs the link flow above. See AGENTS.md if you ever want to publish.

Never mount through both channels at once (that loads two copies). Remove any leftover hand-written insert line from cordis.patch.yml before switching to the bundle channel.

Uninstall

Bundle channel (dsh plugin add)

dsh plugin --profile web remove dsh-image-skin

This removes the dependency, uninstalls the package, and drops it from dsh.profile.bundles. Restart DSH + hard-refresh.

Manual link install: delete the dsh-image-skin dependency from ~/.dsh/profiles/web/package.json, delete the image-skin insert block from cordis.patch.yml, then pnpm install and restart.

Skin data: the image lives under the dsh-image-skin.v1 localStorage key — tap "Remove skin" before uninstalling, or delete the key in DevTools → Application → Local Storage.

Notes

• Client-half changes only need a hard refresh; host-half changes (this plugin's host is empty) need a DSH restart.
• Images are stored as data:image/jpeg (a few hundred KB), well under the localStorage quota.

Known limitations

• Very high-saturation images could tint surfaces strongly; background saturation is capped (sat ≤ 45), and layered surfaces (menus/popovers) stay ≥ 80% opaque to preserve readability.

License

MIT

Third-party community plugin — not affiliated with DeepSeek or DeepSeek Harness. Names and logos belong to their respective owners.