dsh-background-web

Readme

# dsh-background-web

Self-contained whole-window background plugin for the DeepSeek Harness **web**
surface. It is a dual-face bundle: the node half registers a same-origin
upload/read/delete route plus the durable settings section, and the browser half
projects the stored image into the window and registers a General-settings
preference row. The image is picked with a **browser-native file input** — no
Electron dialog, so it works on any `dsh web` installation.

## Install

```sh
dsh plugin --profile web add dsh-background-web
dsh web
```

Then open **设置 → 通用 → 背景** (General settings), choose an image, and adjust
enable / visibility / dark overlay / blur.

## Distribution (publishing this plugin)

- **Self-contained**: `dependencies`/`peerDependencies` are empty — the
  `@deepseek-ai` surface lives in devDependencies for typechecking only, and
  the built `lib/` artifacts are committed — so the package installs from a
  plain npm registry or directly from GitHub with **no peer resolution**:

  ```sh
  dsh plugin --profile web add github:gubai-future/dsh-background-web
  # or a registry/tarball spec
  ```

- **Discovery**: add the `dsh-plugin` topic to the GitHub repository so it
  shows up on https://github.com/topics/dsh-plugin.
- **Target requirements**: a standard `dsh web` composition — the official
  web-app bundle provides the `settings`/`webServer` host services and the
  runtime/ui-settings/locale/ui-slots browser rows this plugin builds on.
- Runtime data: each user keeps their image in `$DSH_HOME/background-web/`
  (single slot, 20 MB, four raster formats).

## Local development

This package is developed locally: the source lives in this workspace and the
built artifact is exercised inside the DeepSeek Harness checkout's **plugin
system** (the monorepo composition). The published package is
self-contained, so end users install without registry peer resolution — the
checkout loop here is for developing the feature itself.

- Build here, test there: from the harness checkout
  (`E:\project\works\dsh\deepseek-harness`) run the web surface on a **changed
  port** (`3090`; `3080` is the primary instance):

  ```sh
  pnpm run dsh -- web --port 3090 --no-open
  ```

- The official `@deepseek-ai/dsh-client-ui-background` package covers the same
  feature with a different design: it stores the image as a data URL inside its
  settings namespace and owns a full Settings **section**; this plugin keeps
  the image in a host-side single-slot file, serves it through a same-origin
  route, and registers an inline row under General settings. Namespaces, route
  paths, and slot ids differ, so both can be composed without hard conflicts —
  expect two background entries in that case.

## How it works

- **Node half** (`src/index.ts`): registers the `background-web` settings
  section and the `/dsh-background-web/background` route (`PUT` upload, `GET`
  serve, `DELETE` clear). Image bytes live in a single-slot directory under
  `$DSH_HOME/background-web/current.<ext>`; the format is probed from magic
  bytes (png / jpeg / gif / webp).
- **Browser half** (`src/client/index.ts`): binds the `background-web` settings
  scope, drives a self-contained projector (a `<style>` element + body
  attributes — no dependency on `ui-theme`'s stylesheet), and registers the
  `settings.general.item` row. While the background is visible
  (`data-dsh-bg-web-visible`), the projector re-themes the stock surfaces:
  base fills go transparent, and markdown/tool-dropdown code surfaces become
  frosted glass (`backdrop-filter` + translucent `color-mix` fills). The
  re-theme targets the app's official surface hooks — `data-*` attributes on
  cards/blocks, the stable `md-code-block` class, and the `data-io-card`
  attribute on the tool row IN/OUT card — never hashed CSS Module classes;
  switching the background off retracts it all.

## Build (author only)

Users install the **built** artifact; the package must ship `lib/index.js`,
`lib/client.js`, and `lib/types/**`.

Local builds resolve the `@deepseek-ai/*` peers through `node_modules`
links (junctions) pointing into the harness checkout
(`E:\project\works\dsh\deepseek-harness`), and run that checkout's toolchain —
no registry install is needed. The link table (`node_modules` → checkout):

| link | target in the checkout |
|---|---|
| `@deepseek-ai/cordis` | `vendor/cordis` |
| `@deepseek-ai/schemastery` | `vendor/schemastery` |
| `@deepseek-ai/dsh-settings` | `packages/settings/settings` |
| `@deepseek-ai/dsh-host-webserver` | `packages/host/webserver` |
| `@deepseek-ai/dsh-client-runtime` | `packages/client/runtime` |
| `@deepseek-ai/dsh-client-ui-settings` | `packages/client/ui-settings` |
| `@deepseek-ai/dsh-client-ui-slots` | `packages/client/ui-slots` |
| `@deepseek-ai/dsh-client-locale` | `packages/client/locale` |
| `react`, `@types/react` | `packages/client/ui-background/node_modules/...` |
| `@types/node`, `lightningcss` | root `node_modules/...` |

```powershell
& 'E:\project\works\dsh\deepseek-harness\node_modules\.bin\tsc.cmd' -p tsconfig.json
& 'E:\project\works\dsh\deepseek-harness\node_modules\.bin\tsdown.cmd'
```

The two steps are what `pnpm run build` (tsc then tsdown) runs under a real
install.

## Known limitations

- **Remote browsers** persist the preference process-locally: the settings RPC is
  loopback-only, so a non-loopback browser does not write `settings.yaml`. The
  image bytes are served same-origin and still project for that session.
- Uploads are capped at **20 MB** and admitted only for the four probed raster
  formats; no downscaling, compression, or OCR is performed.
- Single-slot storage: a new pick overwrites the previous image.
- The frosted-glass re-theme targets the app's official surface hooks
  (`data-*` block attributes, `md-code-block`, and the tool-row IN/OUT card,
  matched by both its `data-io-card` hook and a `[class*='_ioCard']`
  class-substring fallback so stock app builds keep the glass). If a future
  app revision renames those hooks, the affected surfaces silently fall back
  to stock styling — the background image itself keeps working.
- `tsdown.config.ts` mirrors the repository's `packages/client/tsdown.client.ts`
  preset; the few deliberate differences for a standalone build are documented
  in that file's header. Keep it in sync when the preset changes.