Feature request: wallpaper (background image) support in the new theme system

[Williawar]

The new theming system in the nightlies (.1025+) is excellent — I moved my
whole custom palette into it the day it appeared. This is a request for the
one visual layer it can't express yet: a background image behind the canvas.

What I built (works today, via CSS patching)

A desktop wallpaper that sits under the whole app, with the existing glass
surfaces doing all the work of keeping content readable. The composer is the
star: its translucent glass lets the image ghost through the prompt box, and
the native glass-opacity slider already gives users the control they need.

Mechanically it's small — which is why I think it would make a clean native
feature:

1. One image layer on the root (I use html::before, position: fixed,
   cover, with a theme-colored gradient over it to set the ghosting level —
   the equivalent of a wallpaper opacity setting).
2. Four stacked bg-background/80 layers currently bury it (the inner flex
   container, the scroll container, main, and body). They need to be
   transparent when a wallpaper is active — everything above them (cards,
   bubbles, composer, popovers, sidebar) keeps its own paint and stays
   readable with zero further changes.

That's the entire mechanism. No component changes needed — the app's existing
glass design language already composes beautifully with an image behind it.

Proposed shape

An optional field on the theme file (or a standalone appearance setting):

{
  "version": 1,
  "name": "Deep Veil",
  "appearance": "light",
  "colors": { /* ... */ },
  "wallpaper": {
    "image": "<data URI or file path>",
    "opacity": 0.15,        // how much image shows through the canvas color
    "fit": "cover",
    "position": "center"
  }
}

• opacity as "image strength" (canvas color over image) matches how people
  reason about wallpapers, and keeps every theme readable by default.
• The glass-opacity setting already covers the surface-translucency half.
• Import/export keeps working — a theme with its wallpaper travels as one
  file (data URI), which is a lovely property for sharing themes.

Happy to share the working CSS, screenshots, or test nightlies. Thanks for
the theme system — funny how being able to theme it the way I want made me use
t3code a lot more.

[Williawar]

I'd like to put up a PR for this. The minimal slice I have in mind:

• An optional wallpaper field on ThemeFile (image data URI, opacity, fit, position). Optional, so version-1 files, import/export, and every existing theme keep working unchanged.
• useTheme sets --theme-wallpaper-* variables and a root class when the active theme carries one.
• index.css adds a fixed root image layer (a theme-colored gradient over the image implements the opacity control), and under that root class the covering bg-background/80 / body layers go transparent. Everything above them — cards, bubbles, composer glass, popovers, sidebar — keeps its own paint and stays readable as-is.
• No theme-editor UI in the first slice: wallpapers arrive via theme import; editor UI as a follow-up.

One question before I build it: as a data URI the image would live inside the t3code:themes:v1 localStorage entry, which has a real size budget. Is a documented cap (say ~2 MB, with a friendly import error) acceptable for a first version, or would you prefer different storage for the image? Happy to go either way.

[Williawar]

Draft PR up at #5911 — the minimal slice described above (wallpaper field on ThemeFile, root hook + body chrome paint, no editor UI). On the storage question: the image cap (192 KB base64) keeps any wallpapered theme file inside the existing 256 KB MAX_THEME_FILE_BYTES import budget, so no limits change.

[GhouI]

Following up on @Williawar's voluntarily closed #5911: I've implemented a focused replacement locally against main (9a47c7bd4).

The slice stays on web/desktop: imported/exported theme JSON supports embedded PNG/JPEG/WebP/AVIF/GIF, a 192 KB complete data-URI cap, and opacity 0–1 (default 0.15), with fixed cover/center rendering. It preserves the existing grain layer and theme colors, drops malformed stored wallpapers, preserves wallpaper through color edits/duplicates/merges, and clears it when switching to a normal theme or cancelling its preview. The editor now includes a small image picker to choose, replace, or remove a wallpaper, with live preview and cancellation. Explicit picker edits take precedence when merging. No shared/mobile/server changes.

Validation: all 4,170 web unit tests pass; web typecheck and lint pass (lint retains existing warnings). Browser checks covered import/export, color edits, preview cancellation, duplication, and merge precedence. Five files changed, including a short user-guide addition. No replacement PR opened yet; keeping the follow-up here in the existing discussion.

Same palette, route, 1440 × 1000 viewport, and glass settings. The after image uses an embedded PNG at 0.15 opacity.

Before	After

[olafura]

This gist is a demonstration of how this feature could be built or customized with the Qt/QML branch. It is an example to try and adapt, not a complete implementation of the discussion request or a feature shipped in upstream T3 Code.

I put together a Qt-shell wallpaper example with a local SVG included, adjustable image strength, and a tinted timeline card. The opt-in webView.transparentCanvas setting clears the page's backing layers so the wallpaper shows through the conversation, without fading text, messages or menus. The wallpaper has no animation loop.

It also accepts local image URLs and data URIs. This doesn't change the web theme-file format, so web theme export alone won't carry the wallpaper. Share the gist files together.

Demonstration gist and setup.

Corrected wallpaper example on workspace 5. The image now shows through the conversation timeline; text and message backgrounds retain their normal opacity. The conversation uses demo data.

Code and checks assisted by Codex.

[olafura]

Sorry for the lack of context this is showing how using this technique in the linked discussion would help with your issue #10708