dsh-photo-skins

Readme

# 🪄 dsh-photo-skins

[中文](README.zh.md) | English

Import once. Auto-accent once. Turn any photo into a skin for the DSH Web GUI.

![Photo skins demo](screenshots/Interface_1.png)
Photo skins for the DSH Web GUI: import your own photos and turn them into
the interface skin. The photo paints the backdrop behind the GUI, and the
accent colors are extracted from the photo automatically (dominant color as
the accent, photo-tinted light/dark readability veils). Rendering controls:
fit (cover/contain), blur (0-100px, global or split empty/content), dim
(0-100%) and the auto-accent toggle.

0831Updates - A cordis plugin: enhance Web-Reach, page, reading and RSS.

## ✨ Core Feature

### 📥 Import photos three ways
![Photo skins demo](screenshots/Plugin_Path.png)
- File picker, drag-and-drop, or paste — pick whichever you like
- Supports PNG / JPG / WebP / GIF, up to 25MB each

### 👗 Try on / apply / remove
- Manage everything from the first-level "Photo skins" settings section
- "Try on" previews temporarily without touching the applied photo
- "Apply" writes the skin in one click; "Remove" clears the local copy

### 🎨 Automatic accent extraction
- The photo's dominant color becomes the interface accent
- Derives light/dark scrim tints so the readability veils pick up the photo's own tone
- Exposes CSS variables `--dsw-photo-accent` / `--dsw-photo-accent-soft` / `--dsw-photo-accent-contrast`

### 🖼️ Rendering controls
![Photo skins demo](screenshots/Interface_chat.png)
- Fit: cover / contain
- Blur: 0–100px, global or split
- Dim: 0–100%, keeping foreground content readable
- Accent-from-photo: toggle on/off anytime

### 💾 Local persistence
- The applied photo persists through the `photo-skins` settings namespace and survives reloads
  
## 🚀 Install

From npm:

```sh
dsh plugin --profile web add dsh-photo-skins
```

From this repository (development):

```sh
pnpm install && pnpm build
dsh plugin --profile web add link:.
```

Then refresh the running Web GUI (restart `dsh web` if the new section does
not appear).

## Storage

Photos are stored under `<DSH_HOME>/photo-skins/<id>/` (`original.<ext>` plus
a `manifest.json` with the display name, type, size and import time). Nothing
is uploaded or shared; removal deletes the local copy.

## Web-Reach

Web-Reach is in the same plugin and free to use. It wires "web search" into DSH's web capability
seam (`ctx.web`) and additionally registers two native tools that the Agent
calls automatically during a conversation when it needs current information:

- `web_search`: contributed as one of three `ctx.web` search providers —
  DuckDuckGo (no key; scraping-based, needs a reachable network path to
  duckduckgo.com), Exa free (hosted MCP; the default backend, marked
  "recommended" in the card), or Exa API key (requires a saved key).
- `web_fetch`: Jina Reader turns any public page into Markdown (no key).
- `rss_fetch`: parses an RSS 2.0 / Atom feed into its entries (no key).

Web search is a master switch: the "Web search" toggle above the composer shows
the active backend and turns it on/off, sharing the same `web-reach` namespace
as the card so the two stay in sync. When enabled (the default), the plugin
points `ctx.web`'s `searchProviderId` at the chosen backend. when disabled, the official DeepSeek-native search is restored.

The key entry only appears for the "Exa API key" mode. The key is stored in the
`web-reach` settings namespace as a secret, redacted on the wire and never read
back by the browser (write-only). Search queries and page URLs are sent to
third-party services (DuckDuckGo / Exa / Jina Reader) — the data leaves this
machine. See Security model below.

## 🔒 Security model

- All routes (`/api/photo-skins/*`) sit behind a same-origin fence
  (Sec-Fetch-Site / Origin): cross-site webpages cannot read, import or
  delete your photos.
- Uploads are validated by file magic bytes, not by name or declared
  content-type — a renamed SVG or executable is rejected (415). SVG is
  deliberately unsupported (script risk).
- Uploads are capped at 25MB (413) and written atomically (tmp + rename).
- Stored ids are generated and validated against a whitelist regex, so no
  path can escape the store directory.
- Web-Reach search providers and tools run in the host process (there is no
  browser-exposed route), and every outbound fetch is SSRF-gated: only public
  http(s) URLs are fetched, and loopback / link-local / private / reserved IP
  ranges, plus cloud-metadata hostnames and IP-obfuscation forms, are refused.
  Redirects are re-validated and capped; responses are timeout-bounded (15-20s)
  and size-capped (2 MiB); provider/tool execution honours the turn's
  cancellation signal. The Exa hosted-MCP endpoint
  (https://mcp.exa.ai/mcp) passes the same SSRF gate.
- The DuckDuckGo search path sends only a text query term (never a URL) and
  reports the decoded result URLs back without fetching them.
- The Exa API key is an optional `role('secret')` settings field: stripped at
  the wire boundary, the browser never receives the plaintext; the provider
  reads it only host-side at execution time. Choosing "Exa API key" without a
  saved key leaves that provider unavailable and search fails loudly rather
  than silently downgrading.
- Exa free (MCP) uses Exa's official hosted MCP endpoint, currently advertised
  as keyless; its keyless status is not verified by this plugin and may change.


## 🛠️ Development
Requirements: Node.js ^22.19 || >=24, pnpm

```sh
pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run
pnpm build       # tsdown -> lib/ (host) + lib/client.js (browser bundle)
```

## License

BSD-3-Clause. See THIRD_PARTY_NOTICES.md for attribution of incorporated
portions.