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

[saphid]

Proposal: a static, opt-in background scene for built-in themes (narrowed from #12897)

The need in this thread still stands: people spend whole days in T3 Code, and some want the workspace to feel less flat. On current main (a1d9d72aef), Settings → Appearance has Contrast and Glass opacity, but nothing can sit behind the canvas, so the glass surfaces have nothing to show through.

Main today: workspace	Main today: Appearance

My larger version (#12897: 15 scenes plus a new transparency slider) was closed for missing direction approval. This is the smallest version I think is still useful.

Scope

• One switch: Settings → Appearance → Background scene. It's off by default, so nothing changes for anyone who doesn't turn it on.
• Each built-in theme (T3 Chat, Grove, Ocean, Ember, Iris) gets one static, pre-softened scene: 5 webp files, about 325 KB in total, and only the active one is fetched. Custom themes and the default look have no scene.
• The canvas, sidebar and toolbar use the theme's own colors at the existing Glass opacity, so there's no new slider.
• No blur, no animation, and no backdrop-filter on large surfaces. The image paints once on body::before. With the switch off, none of the new CSS applies.
• Web and desktop only. Mobile reads the setting and ignores it.

Performance budget (proposed acceptance criteria)

• Off: no added paint or GPU work.
• On and idle: zero repaints.
• On while streaming: no dropped frames at 60 Hz, and no more than 0.2 ms of added paint per frame.

Measured on the ready branch with headless Chrome (Metal GPU compositing) at 1440×900. Each figure is the median of three 5-second runs. "Streaming" appends text to the timeline on every frame. Machine load differed between the two sessions, so compare rows within a session.

Session	Build	Idle paints	Streaming paint (5 s)	p95 frame	GPU-process CPU (5 s)
1	main	0	82 ms	16.7 ms	803 ms
1	branch, switch off	0	92 ms	16.8 ms	855 ms
1	branch, Ocean light on	0	129 ms	16.8 ms	869 ms
2 (final head)	branch, switch off	0	55 ms	16.7 ms	547 ms
2 (final head)	branch, Ocean light on	0	56 ms	16.7 ms	560 ms
2 (final head)	branch, Grove dark on	0	67 ms	16.7 ms	643 ms

With the switch off, the code path matches main: none of the new CSS applies, so the gap between those two rows is run-to-run noise. With the scene on, paint rises by at most about 0.12 ms per frame, with no dropped frames and no idle repaints. I haven't measured this in the Electron shell or on a low-end GPU. Raw numbers

Ocean, light	Grove, dark	Ember, light

Turning it on, switching theme, changing glass opacity, and turning it off: recording

How this relates to #10412: that PR lets you import your own chat wallpaper, with blur and custom CSS. This proposal is the narrower built-in option: no image import, no storage budget, and no blur. If you'd rather go the import route, I'll drop this one.

Verification plan for a PR: focused contract and settings tests, before/after screenshots plus a short recording, this perf table re-run on the PR head, and one pass in the Electron shell.

The decision I need: do you want a built-in, off-by-default background scene in this shape? If yes, I'll open one PR from the ready branch (saphid/t3code:feat/theme-background-scene). If not, I'll leave #12897 closed.

[abhiabrol19]

Adding a use case for the theme-CSS half of #10412.

I'm building a custom dark theme (Starry Night) as a theme file. Colors get me most of the way, but the built-in themes also get per-theme styling a custom theme can't reach: the composer outline and highlight and the surface grain (T3 Chat), and the sidebar stage-art palette (all five built-ins). Those are hard-coded html[data-theme-id=…] rules in index.css.

The optional css field in #10412 would close that gap without new vocabulary. An imported or published theme could carry its own overlay styling, for example a subtle starfield and a glow behind the composer, the way the built-ins do today. Shipped alone, without the wallpaper half, it would already cover this.

Would maintainers approve the css field as a direction?

[abhaymettu]

A background image variant to weigh next to #10412, not a competing PR. It has no theme CSS, and the image covers the whole window instead of the chat column. The #10412 column comes from reading its diff. Corrections welcome.

	#10412	This branch
Where the image shows	The chat column	The whole window, including the sidebar and Settings
Image storage	A data URL (up to 1.5M characters) or an http(s) URL, kept in client settings	The image bytes in IndexedDB on each device, scaled to at most 3840 px on the long edge. Settings keep only its SHA-256. Local files only.
Readability	Optional image blur, glass cards with backdrop blur, and an adjustable text shadow	One veil in the theme's background color over the unblurred photo, a little heavier at the top in dark mode. While an image shows, glass is solid, so the composer, menus, and code blocks are opaque, and the Glass opacity row is disabled and says so. Grouped settings cards are 92% opaque. Secondary and status text colors shift for contrast only on the surfaces over the photo (sidebar, thread, Settings), so menus and dialogs keep the theme's colors. No blur and no text shadow.
Controls	Image, Opacity, Blur, Text shadow, Shadow blur	On or off, the image, and one Fade slider from 70 to 100%
Theme CSS	Yes	No

At a Fade of 70%, secondary, link, and status text keep 4.5:1 contrast with the default theme, even over a solid black photo in light mode or a solid white one in dark mode. Custom themes are not tested.

It is off by default. While it is off, nothing reads from IndexedDB, and every new CSS rule is scoped to an attribute that is not set. The image also stays hidden under prefers-reduced-transparency, prefers-contrast: more, and forced-colors. Restore device defaults resets it and deletes the stored image. The change is web and desktop only, with no server or mobile changes. The branch is 16 files, about 700 added lines without tests: main...abhaymettu:t3code:up/background-image-v3

My question for the maintainers is which of these you want:

1. A separate PR, off by default.
2. Parts of it (the IndexedDB store, the whole-window veil) folded into feat(web): customize themes with CSS and chat wallpaper #10412, if @maria-rcks wants them.
3. Neither, because feat(web): customize themes with CSS and chat wallpaper #10412 already covers it.

I won't open a PR without a yes in this thread.

Written with Claude Opus 5.5 via Claude Code in T3 Code.