dsh-vibrancy
Frosted-glass (acrylic) surfaces for the DeepSeek Harness Desktop application: the plugin reads the current desktop wallpaper, serves it over the profile's own Web server, and paints it behind the application blurred.
The plugin needs no change to DSH itself. A window backdrop material belongs to the Electron shell's BrowserWindow, which a plugin cannot reach, so this plugin supplies its own backdrop source instead: the wallpaper file Windows already keeps for the current display layout. It registers the layer only when the Host reports that a wallpaper is available, so a profile without the Host half, a solid-colour wallpaper, or a document another client owns renders exactly as before.
What it does
The Host half (index.mjs) registers two routes on the authenticated loopback Web server the page already shares, and re-reads the wallpaper on a timer so a slideshow rotation is picked up. The browser half (the served ./client bundle) asks for the descriptor, and only when it reports available: true does it mark the document, inject the stylesheet, and append the wallpaper layer.
The layer is one fixed, non-interactive div behind the application. A custom property on <html> points it at the image URL, and the stylesheet blurs and saturates it, clears the application's own opaque fills, tints the structural surfaces, and raises #root above the layer.
A poll re-fetches the descriptor. A new token swaps the layer URL, which is how a rotated wallpaper reaches the page without the browser serving a cached image. An available: false answer removes the layer and the markers again, returning the application to its own opaque paints.
Requirements
- Windows 11. The plugin reads the wallpaper file Windows writes for the current layout, under
%APPDATA%\Microsoft\Windows\Themes.
- DSH Desktop 0.1.7-rc.2 or later, with the
webServer service, whose register method mounts the two routes. The plugin needs no shell change at all: it never touches apps/desktop, uses no IPC channel, and calls no Electron API.
- The wallpaper must be an image file. A solid-colour background has no file to read, so
available is false and the plugin stays inert.
Install
lib/client.js is generated, and the package ships it, so a clone works as-is. Rebuild it only after editing src/glass-core.mjs:
node scripts/build-client.mjs
DSH Desktop owns its own profile at $DSH_HOME/profiles/desktop (%USERPROFILE%\.dsh\profiles\desktop on Windows), and the CLI cannot boot or mutate it. Installing means three writes into that directory:
- Copy this package to
<profile>/node_modules/dsh-vibrancy.
- Add
"dsh-vibrancy": "file:./node_modules/dsh-vibrancy" to dependencies and "dsh-vibrancy" to dsh.profile.bundles in <profile>/package.json.
- Append the Loader row to
<profile>/cordis.yml:
- id: window-glass
name: dsh-vibrancy
Then restart DSH Desktop. The Web GUI's plugin manager performs the same three writes itself once the package is reachable as a specifier it can resolve, which a local directory is not.
Disable
Set the dsh-vibrancy key in the Desktop document's local storage to off and reload the page:
localStorage.setItem('dsh-vibrancy', 'off')
With that value the page requests no descriptor and registers nothing; any other value, or no value, leaves the plugin enabled. There is no in-app command or setting for this key.
The Loader row also takes an enabled option, which stops the Host half serving the wallpaper and leaves every page untouched:
- id: window-glass
name: dsh-vibrancy
config:
enabled: false
How it works
The Host half injects webServer and registers a route through ctx.effect(() => ctx.webServer.register(...)), so disposal unregisters it with the plugin's fiber. GET /dsh-vibrancy/wallpaper returns the image bytes with the content-type taken from the file's magic bytes, a content-length, and cache-control: private, max-age=604800; it answers 404 no wallpaper when no image is usable or the file vanished between the check and the read. GET /dsh-vibrancy/wallpaper/meta returns { available, url, token, mimeType, refreshIntervalMs } with cache-control: no-store.
The image URL carries the token as a ?v= query, and the token is the truncated modification time and the file size, so a different wallpaper is a different URL and the browser cannot reuse its cached copy. A setInterval re-reads the wallpaper so a slideshow rotation is seen; the interval defaults to 30 000 ms and a smaller configured value is raised to 1000 ms.
src/wallpaper.mjs discovers the image. It reads %APPDATA%\Microsoft\Windows\Themes\CachedFiles and takes the newest image there, then falls back to TranscodedWallpaper beside it, which is the copy Windows composed for the current layout. The image type comes from the leading bytes, never from the filename: Windows names the cached file after the theme source extension, so a cached image can be named .jpg while its bytes are PNG, and a name-based guess would serve a type the browser refuses to paint. An unreadable, empty, or non-image candidate is skipped, and finding no candidate at all reports available: false.
The browser half runs on activation. installGlassSurfaces() reads the stored preference, checks that the document is standalone and carries no other client's marker, and fetches the descriptor with credentials: 'same-origin'. Only a descriptor with available: true and a non-empty url proceeds: the stylesheet is injected, data-ds-window-glass and data-ds-window-wallpaper are set on the root, and a <div id="dsh-vibrancy-wallpaper"> is appended to the body with the image supplied through the --dsh-vibrancy-wallpaper custom property on <html>, with quote characters escaped.
The layer is position: fixed with inset: -5%, z-index: 0, and pointer-events: none, painted with background-size: cover and filter: blur(48px) saturate(1.15). The negative inset pushes the element past the viewport so the transparent fringe a large blur() leaves at the edges stays outside the visible area, and #root is raised to position: relative; z-index: 1 so the application paints above it.
The stylesheet makes the application translucent by redefining the semantic background aliases — --dsw-alias-bg-base and the three bg-layer fills — as color-mix(in srgb, <theme token> <percentage>, transparent), with a separate percentage set under body[data-ds-dark-theme]. It deliberately does not strip element backgrounds: a broad background-color: transparent rule also erases cards, panels, and inputs, which leaves their text sitting unreadable on the blur. The base fill is the most translucent so the wallpaper reads through the main surface, while layer-1 and the input fills stay more opaque so card and composer text keep their contrast. Floating menus, dialogs, listboxes, and overlays keep a nearly opaque --dsw-specific-menu fill, because they cover content rather than the window. A visual probe that renders this stylesheet against a real wallpaper confirmed the percentages below are usable in both themes; it is a development tool and is not part of this package.
A timer re-fetches the descriptor at the interval the Host advertised, floored at 1000 ms. A changed token repoints the layer, and the same token leaves the DOM alone. An answer that is no longer available removes the layer, the custom property, and the root markers, so the application returns to its own paints.
Every failure path leaves the page untouched: no route because the Host half is absent, a 404, a non-JSON body, a transport error, a stored preference of off, a document that is not standalone, or a document already carrying [data-dsh-client]. Disposal clears the poll interval and removes the stylesheet, the layer, the custom property, and both attributes.
lib/client.js is a classic script, not a module: an application combo script carries each row's client.js entry and is concatenated verbatim, so the bundle has no loader of its own. scripts/build-client.mjs therefore inlines src/glass-core.mjs with its export keywords stripped and wraps it in the window.__ModuleLoader__.load({ id, factory }) registration that assigns exports.apply inside the factory. dsh.client.platform stays web because that is the value the Web module registry selects; the wallpaper check is the runtime descriptor fetch.
Verified behaviour
The tests in tests/glass.test.mjs (22), tests/wallpaper.test.mjs (11), tests/client-bundle.test.mjs (8), and tests/host-client.test.mjs (4) cover, against document stubs, a temporary wallpaper profile, a sandboxed execution of the generated bundle, and a real node:http server:
- A stored preference of
off disables the surfaces, and the default with no stored value is enabled.
- A document already claimed by another client, and a document without a top window, are not decorated.
- An unavailable wallpaper, a failing descriptor request, a missing route, a non-object descriptor, a document without
fetch, and a document without a body all leave the application's paints untouched.
- An available wallpaper registers the stylesheet, both root attributes, and the layer, and points the layer at the descriptor's URL.
- Disposal removes the styles, the layer, and the attributes, clears the poll interval, and a second disposal is a no-op.
- A rotated wallpaper replaces the layer URL on the next poll, and an unchanged one does not rewrite the layer.
- A wallpaper that disappears drops the glass surfaces again.
- A poll interval below the floor is raised, the image URL has its quotes escaped, clearing the layer is safe on a bare document, and the stylesheet is registered once per document.
- Image types are identified from magic bytes rather than the filename, a PNG named
.jpg is reported as a PNG, and a non-image, an empty file, a missing file, and a directory are all rejected.
- A described file carries a cache token built from its size and modification time, candidates need
APPDATA, a transcoded wallpaper is found without a cached directory, the newest cached image wins, non-image cache entries are skipped, and an absent profile yields no wallpaper.
- The generated bundle registers exactly one factory under the manifest package name, imports nothing, and tolerates a context without
ctx.effect.
- Over a real HTTP server: the Host serves the wallpaper with the type taken from its magic bytes, the client paints the wallpaper the Host actually serves, a rotated wallpaper changes the token, and an unknown route is not registered.
Design rendering, the blur itself, and the composited result are outside what a stub can observe, so they were checked separately with a visual probe that was not shipped with the package: it rendered the plugin's own stylesheet against the desktop's real wallpaper in Electron and captured the result. Both the light and dark token sets were inspected, and the probe recorded the resolved layer filter, geometry, viewport, and body paint alongside the capture.
Known limitations
The blur is of the wallpaper only. Other windows passing behind the application are not blurred, because blurring them needs a real operating-system composite, which a plugin cannot reach.
The layer is aligned to the screen rather than to the window, so it slides against the desktop while the window is dragged.
A wallpaper change is picked up on the next poll, up to about 30 seconds later, rather than instantly.
A solid-colour background has no image file, so available is false and the plugin stays inert; there is no colour to blur into a material.
The Host reads the user's wallpaper file. Only bytes the current user can already read are served, and only over the authenticated loopback Web server the page already shares, so nothing leaves the machine. The stored off preference and the row's enabled: false option turn the feature off.
License
MIT; see LICENSE.
