dsh-plugin-background-image

Usage

1. Open DSH.
2. Go to Settings → Plugins → Plugin Settings.
3. Find Background Image Settings.
4. Enable the background, then choose a web image, a local image, or a preset gradient. For local images, clicking "Choose Local Image" opens the native system file dialog; the selected absolute path is recorded (the file stays where it is — never copied or moved).
5. Adjust the image opacity, display scope, frosted glass (blur strength and glass color saturation, applied to the sidebar and composer card), per-region opacity (sidebar, conversation area, composer), and chat content offset as needed. Lower opacity values are more transparent and more immersive; the sidebar shows frosted glass in immersive fullscreen, while the composer takes effect in both modes.

Configuration Storage

The background toggle, display scope, image opacity, frosted glass, per-region opacity, and chat content offset are persisted by the DSH settings system into the config directory (default ~/.dsh/settings.yaml), like this:

background-image:
  enabled: true
  mode: fullscreen
  opacity: 0.9
  image: https://example.com/background.webp
  blur: 12             # frosted-glass blur strength (px, sidebar & composer card, 0 = off)
  conversationBlur: 0 # independent conversation blur (0–48 px)
  conversationOpacity: 0 # conversation opacity (0–1, both display modes)
  saturation: 1.4      # glass color saturation (1 = as-is, >1 = more vivid)
  sidebarOpacity: 0.5  # sidebar opacity (fullscreen mode only, via the pseudo-element glass)
  composerOpacity: 0.72 # composer opacity
  contentOffset: 120   # chat content horizontal offset (px, positive = right, negative = left, 0 = centered)

• Everything is restored automatically after a page refresh or a DSH restart.
• Local images are recorded as absolute paths — never copied or moved; the file stays where it is:

background-image:
  enabled: true
  mode: fullscreen
  opacity: 0.9
  image: /Users/you/Pictures/background.png
  blur: 0
  conversationBlur: 0 # independent conversation blur (0–48 px)
  conversationOpacity: 0 # conversation opacity (0–1, both display modes)
  saturation: 1
  sidebarOpacity: 0.5
  composerOpacity: 0.72
  contentOffset: 0

Browsers cannot load file:// resources directly due to security policies, so the plugin registers a read-only file-serving route on the host (GET /plugins/background-image/file?path=) that serves the local image referenced by the configuration to the page over same-origin http. The route only accepts loopback origins and only serves the exact path currently referenced by the image field in settings.yaml ("reference-as-authorization", the same model as the official session.attachment). If the image file is moved or deleted, the background stops working and the path must be set again.