@devries-cameron20 / t3code-1 / commits / 7d32075e37
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

feat(web): themes can use full-size background images (#36680)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>

Theo Browne committed Nov 16, 2026 at 12:13 UTC 7d32075e3757ded707914e2450c3e392a9665765
16 files changed +271 -7
apps/server/src/assets/AssetAccess.test.ts
+24
@@ -215,6 +215,30 @@ describe("AssetAccess", () => {
215 }).pipe(Effect.provide(layerTest)),
216 );
217
218 + it.effect("serves the background image published beside an environment theme", () =>
219 + Effect.gen(function* () {
220 + const fs = yield* FileSystem.FileSystem;
221 + const { environmentThemesDir } = yield* ServerConfig.ServerConfig;
222 + yield* fs.makeDirectory(environmentThemesDir, { recursive: true });
223 + const imagePath = `${environmentThemesDir}/frieren.png`;
224 + yield* fs.writeFile(imagePath, screenshotPng);
225 + const result = yield* issueAssetUrl({
226 + resource: { _tag: "environment-theme-background", themeId: "frieren" },
227 + });
228 + const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
229 + const separator = suffix.indexOf("/");
230 + const token = suffix.slice(0, separator);
231 + const asset = yield* resolveAsset(token, suffix.slice(separator + 1));
232 + expect(asset).toMatchObject({ kind: "file", path: yield* fs.realPath(imagePath) });
233 + if (asset?.kind !== "file") return;
234 + const response = yield* assetFileResponse(asset);
235 + expect(response.headers["content-type"]).toBe("image/png");
236 +
237 + yield* fs.remove(imagePath);
238 + expect(yield* resolveAsset(token, suffix.slice(separator + 1))).toBeNull();
239 + }).pipe(Effect.scoped, Effect.provide(layerTest)),
240 + );
241 +
242 it.effect("issues exact URLs for media and browser documents outside the workspace", () =>
243 Effect.gen(function* () {
244 const fs = yield* FileSystem.FileSystem;
apps/server/src/assets/AssetAccess.ts
+37
@@ -17,6 +17,7 @@ import {
17 ThreadId,
18 NativeAppIconReference,
19 TurnItemId,
20 + EnvironmentThemeId,
21 } from "@t3tools/contracts";
22 import {
23 hostPreviewMimeTypeFromExtension,
@@ -52,6 +53,7 @@ import * as AssetSigner from "./AssetSigner.ts";
53 import { makeIsServerInternalPath } from "../auth/serverInternalPaths.ts";
54 import { parseAttachmentFileExtension, resolveAttachmentPathById } from "../attachmentStore.ts";
55 import * as ServerConfig from "../config.ts";
56 +import { findThemeBackground } from "../environmentTheme.ts";
57 import * as Orchestrator from "../orchestration-v2/Orchestrator.ts";
58 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
59 import * as ProjectFaviconResolver from "../project/ProjectFaviconResolver.ts";
@@ -168,6 +170,12 @@ const AssetClaimsSchema = Schema.Union([
170 app: NativeAppIconReference,
171 expiresAt: Schema.Number,
172 }),
173 + Schema.Struct({
174 + version: Schema.Literal(1),
175 + kind: Schema.Literal("environment-theme-background"),
176 + themeId: EnvironmentThemeId,
177 + expiresAt: Schema.Number,
178 + }),
179 Schema.Struct({
180 version: Schema.Literal(1),
181 kind: Schema.Literal("tool-output-image"),
@@ -834,6 +842,17 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
842 imageDimensions = readImageDimensions(image.bytes);
843 break;
844 }
845 + case "environment-theme-background": {
846 + // Published themes go to every client, so any client may read their backgrounds.
847 + claims = {
848 + version: 1,
849 + kind: "environment-theme-background",
850 + themeId: input.resource.themeId,
851 + expiresAt,
852 + };
853 + fileName = `${input.resource.themeId}-background`;
854 + break;
855 + }
856 case "native-app-icon": {
857 claims = {
858 version: 1,
@@ -982,6 +1001,24 @@ export const resolveAsset = Effect.fn("AssetAccess.resolveAsset")(function* (
1001 return image ? ({ kind: "bytes", ...image } satisfies ResolvedAsset) : null;
1002 }
1003
1004 + if (claims.kind === "environment-theme-background") {
1005 + const config = yield* ServerConfig.ServerConfig;
1006 + const fileSystem = yield* FileSystem.FileSystem;
1007 + // The themes directory may be a symlink; openMediaFile refuses any path that is not canonical.
1008 + const themesDir = yield* fileSystem
1009 + .realPath(config.environmentThemesDir)
1010 + .pipe(Effect.orElseSucceed(() => null));
1011 + const background = themesDir === null ? null : findThemeBackground(themesDir, claims.themeId);
1012 + if (background === null) return null;
1013 + const file = yield* openMediaFile(background.path).pipe(
1014 + Effect.tapError((cause) =>
1015 + Effect.logError("Failed to open theme background.", { path: background.path, cause }),
1016 + ),
1017 + Effect.orElseSucceed(() => null),
1018 + );
1019 + return file ? ({ kind: "file", path: background.path, file } satisfies ResolvedAsset) : null;
1020 + }
1021 +
1022 if (claims.kind === "native-app-icon") {
1023 const nativeAppIconResolver = yield* NativeAppIconResolver.NativeAppIconResolver;
1024 const iconPath = yield* nativeAppIconResolver.resolve(claims.app);
apps/server/src/environmentTheme.test.ts
+29
@@ -304,6 +304,35 @@ it.layer(NodeServices.layer)("environment theme", (it) => {
304 );
305 });
306
307 + it.effect(
308 + "reports the image beside a theme as its background, with a new revision per file",
309 + () =>
310 + withEnvironmentThemes(
311 + { "look.json": encodeThemeFile(NIGHTFALL_THEME), "look.png": "first" },
312 + Effect.gen(function* () {
313 + const { environmentThemesDir } = yield* ServerConfig.ServerConfig;
314 + const fs = yield* FileSystem.FileSystem;
315 + const path = yield* Path.Path;
316 + const background = Effect.map(currentThemes, (themes) => themes[0]?.background);
317 + const image = path.join(environmentThemesDir, "look.png");
318 +
319 + const first = yield* background;
320 + assert.isDefined(first);
321 + yield* fs.writeFileString(image, "a longer second image");
322 + assert.notStrictEqual(yield* background, first);
323 +
324 + yield* fs.remove(image);
325 + assert.isUndefined(yield* background);
326 + if (symlinksSupported) {
327 + const outside = path.join(environmentThemesDir, "..", "outside.png");
328 + yield* fs.writeFileString(outside, "outside");
329 + yield* fs.symlink(outside, image);
330 + assert.isUndefined(yield* background);
331 + }
332 + }),
333 + ),
334 + );
335 +
336 it.effect("keeps the served theme when an update does not fit the size limit", () => {
337 const large = (name: string): EnvironmentThemeFile => ({
338 ...NIGHTFALL_THEME,
apps/server/src/environmentTheme.ts
+42 -3
@@ -1,6 +1,7 @@
1 // @effect-diagnostics nodeBuiltinImport:off - the guarded file read needs open
2 // flags (O_NOFOLLOW, O_NONBLOCK) the FileSystem service does not expose.
3 import * as NodeFS from "node:fs";
4 +import * as NodePath from "node:path";
5
6 import {
7 type DefaultAppearancePreference,
@@ -52,6 +53,10 @@ const MAX_THEME_FILES = 32;
53 export const MAX_THEME_FILE_BYTES = 6 * THEME_CSS_MAX_LENGTH + 16 * 1024;
54 const MAX_THEME_TOTAL_BYTES = 6 * MAX_THEME_FILE_BYTES;
55
56 +/** A theme's background is `<id>.<extension>` beside `<id>.json`; earlier extensions win. */
57 +const THEME_BACKGROUND_EXTENSIONS = ["webp", "png", "jpg", "jpeg"] as const;
58 +const MAX_THEME_BACKGROUND_BYTES = 16 * 1024 * 1024;
59 +
60 interface PublishedThemes {
61 readonly seq: number;
62 readonly themes: ReadonlyArray<EnvironmentTheme>;
@@ -101,6 +106,8 @@ export class EnvironmentThemeService extends Context.Service<
106 readonly read: (themeId?: string) => Effect.Effect<
107 {
108 readonly current: string;
109 + /** Where theme files and their background images live. */
110 + readonly themesDir: string;
111 readonly themes: ReadonlyArray<EnvironmentTheme>;
112 readonly theme?: EnvironmentTheme;
113 },
@@ -173,6 +180,35 @@ export const readThemeFileGuarded = (filePath: string, maxBytes: number): string
180 }
181 };
182
183 +/**
184 + * The background image published beside `themeId`, if any. Symlinks and oversized files are
185 + * skipped. `entries` lets a directory scan skip lookups for names it did not list.
186 + */
187 +export function findThemeBackground(
188 + themesDir: string,
189 + themeId: string,
190 + entries?: ReadonlySet<string>,
191 +): { readonly path: string; readonly revision: string } | null {
192 + for (const extension of THEME_BACKGROUND_EXTENSIONS) {
193 + const name = `${themeId}.${extension}`;
194 + if (entries !== undefined && !entries.has(name)) continue;
195 + // Native separators: the asset route refuses a path that differs from its canonical form.
196 + const filePath = NodePath.join(themesDir, name);
197 + let info: NodeFS.BigIntStats;
198 + try {
199 + info = NodeFS.lstatSync(filePath, { bigint: true });
200 + } catch {
201 + continue;
202 + }
203 + if (!info.isFile() || info.size > MAX_THEME_BACKGROUND_BYTES) continue;
204 + return {
205 + path: filePath,
206 + revision: [info.ino, info.size, info.mtimeNs].map((part) => part.toString(36)).join("-"),
207 + };
208 + }
209 + return null;
210 +}
211 +
212 export const readPublishedThemes = Effect.fn(function* (themesDir: string) {
213 const fs = yield* FileSystem.FileSystem;
214 const entries = yield* fs
@@ -180,6 +216,7 @@ export const readPublishedThemes = Effect.fn(function* (themesDir: string) {
216 .pipe(Effect.orElseSucceed((): Array<string> => []));
217
218 const themes: Array<EnvironmentTheme> = [];
219 + const entryNames = new Set(entries);
220 let examined = 0;
221 let totalBytes = 0;
222 for (const entry of entries.toSorted()) {
@@ -232,7 +269,8 @@ export const readPublishedThemes = Effect.fn(function* (themesDir: string) {
269 break;
270 }
271
235 - themes.push({ id, ...file });
272 + const background = findThemeBackground(themesDir, id, entryNames);
273 + themes.push({ id, ...file, ...(background ? { background: background.revision } : {}) });
274 }
275 return themes;
276 });
@@ -406,7 +444,8 @@ const make = Effect.gen(function* () {
444 )(function* (themeId) {
445 const { themes } = yield* refresh;
446 const { defaultTheme } = yield* settings.getSettings;
409 - if (themeId === undefined) return { current: defaultTheme, themes };
447 + const themesDir = environmentThemesDir;
448 + if (themeId === undefined) return { current: defaultTheme, themesDir, themes };
449 const theme = themes.find((candidate) => candidate.id === themeId);
450 if (theme === undefined) {
451 return yield* new EnvironmentThemeRefusedError({
@@ -415,7 +454,7 @@ const make = Effect.gen(function* () {
454 known: themes.map(({ id }) => id),
455 });
456 }
418 - return { current: defaultTheme, themes, theme };
457 + return { current: defaultTheme, themesDir, themes, theme };
458 });
459
460 return {
apps/server/src/mcp/toolkits/theme/handlers.ts
+9 -2
@@ -16,6 +16,7 @@ export const layer = McpToolAccess.toLayer(ThemeToolkit, {
16 const themes = yield* EnvironmentTheme.EnvironmentThemeService;
17 const {
18 current,
19 + themesDir,
20 themes: published,
21 theme,
22 } = yield* themes.read(themeId).pipe(
@@ -30,8 +31,14 @@ export const layer = McpToolAccess.toLayer(ThemeToolkit, {
31 return {
32 current,
33 builtIn: BUILT_IN_THEME_IDS,
33 - published: published.map(({ id, name, css }) => ({ id, name, hasCss: Boolean(css) })),
34 - ...(theme === undefined ? {} : { theme: Struct.omit(theme, ["id"]) }),
34 + published: published.map(({ id, name, css, background }) => ({
35 + id,
36 + name,
37 + hasCss: Boolean(css),
38 + hasBackground: background !== undefined,
39 + })),
40 + ...(theme === undefined ? {} : { theme: Struct.omit(theme, ["id", "background"]) }),
41 + themesDir,
42 guide: THEME_GUIDE,
43 };
44 }),
apps/server/src/mcp/toolkits/theme/tools.ts
+2
@@ -41,9 +41,11 @@ const ThemeReadTool = Tool.make("t3_theme_read", {
41 id: EnvironmentThemeId,
42 name: Schema.String,
43 hasCss: Schema.Boolean,
44 + hasBackground: Schema.Boolean,
45 }),
46 ),
47 theme: Schema.optionalKey(EnvironmentThemeFile),
48 + themesDir: Schema.String,
49 guide: Schema.String,
50 }),
51 })
apps/server/src/ws.ts
+1
@@ -3031,6 +3031,7 @@ export const layerWsRpc = (
3031 if (
3032 input.resource._tag === "attachment" ||
3033 input.resource._tag === "native-app-icon" ||
3034 + input.resource._tag === "environment-theme-background" ||
3035 input.resource._tag === "tool-output-image" ||
3036 input.resource._tag === SOURCE_CONTROL_MEDIA_ASSET ||
3037 // A network path is served only from the thread's project, looked up below.
apps/web/src/appInit.tsx
+2
@@ -37,6 +37,7 @@ import {
37 } from "./composerDraftStore";
38 import { startDefaultThemeAdoption } from "./hooks/useDefaultTheme";
39 import { startEnvironmentThemeRepaint } from "./hooks/useEnvironmentTheme";
40 +import { startThemeBackground } from "./themeBackground";
41 import { readLocalStorageValue, subscribeLocalStorageKey } from "./hooks/useLocalStorage";
42 import { startHostEnvironmentLookup } from "./state/primaryEnvironment";
43 import {
@@ -264,6 +265,7 @@ export function startAppServices(): AppRouter {
265 startDocumentTitle(router);
266 startHostEnvironmentLookup();
267 startEnvironmentThemeRepaint();
268 + startThemeBackground();
269 startBrowserChromeThemeSync(router);
270 startDefaultThemeAdoption();
271 startModelPreferencesMigration();
apps/web/src/themeBackground.ts new
+96
@@ -0,0 +1,96 @@
1 +import { resolveAssetUrl } from "@t3tools/client-runtime/state/assets";
2 +import { executeAtomQuery } from "@t3tools/client-runtime/state/runtime";
3 +import type { EnvironmentId } from "@t3tools/contracts";
4 +
5 +import { appAtomRegistry, subscribeAtomChanges } from "./rpc/atomRegistry";
6 +import { assetEnvironment } from "./state/assets";
7 +import { themeEnvironmentIdAtom } from "./state/primaryEnvironment";
8 +import { themeServerEnvironmentThemesAtom } from "./state/server";
9 +import { environmentSession } from "./state/session";
10 +
11 +const THEME_BACKGROUND_VARIABLE = "--theme-background-image";
12 +
13 +let shownKey: string | null = null;
14 +let loading: AbortController | null = null;
15 +let objectUrl: string | null = null;
16 +
17 +function show(nextUrl: string | null): void {
18 + const root = document.documentElement;
19 + if (nextUrl === null) root.style.removeProperty(THEME_BACKGROUND_VARIABLE);
20 + else root.style.setProperty(THEME_BACKGROUND_VARIABLE, `url("${nextUrl}")`);
21 + if (objectUrl !== null) URL.revokeObjectURL(objectUrl);
22 + objectUrl = nextUrl;
23 +}
24 +
25 +async function loadBackground(
26 + environmentId: EnvironmentId,
27 + themeId: string,
28 + signal: AbortSignal,
29 +): Promise<string | null> {
30 + const minted = await executeAtomQuery(
31 + appAtomRegistry,
32 + assetEnvironment.createUrl({
33 + environmentId,
34 + input: { resource: { _tag: "environment-theme-background", themeId } },
35 + }),
36 + { label: "theme background", reportFailure: false, refresh: true, signal },
37 + );
38 + const connection = appAtomRegistry.get(
39 + environmentSession.preparedConnectionValueAtom(environmentId),
40 + );
41 + if (minted._tag !== "Success" || connection._tag === "None") return null;
42 + const url = resolveAssetUrl(connection.value.httpBaseUrl, minted.value.relativeUrl);
43 + if (url === null) return null;
44 + const response = await fetch(url, { signal });
45 + if (!response.ok) return null;
46 + const image = await response.blob();
47 + return image.type.startsWith("image/") ? URL.createObjectURL(image) : null;
48 +}
49 +
50 +/**
51 + * Sets `--theme-background-image` to the image published beside `themeId`, or clears it.
52 + * The image is copied into a blob URL once per revision, so the signed URL may expire.
53 + */
54 +export function applyThemeBackground(themeId: string | undefined): void {
55 + if (typeof document === "undefined") return;
56 + const environmentId = appAtomRegistry.get(themeEnvironmentIdAtom);
57 + const revision =
58 + themeId === undefined
59 + ? undefined
60 + : appAtomRegistry.get(themeServerEnvironmentThemesAtom)?.find((theme) => theme.id === themeId)
61 + ?.background;
62 + const key =
63 + environmentId === null || themeId === undefined || revision === undefined
64 + ? null
65 + : JSON.stringify([environmentId, themeId, revision]);
66 + if (key === shownKey) return;
67 + shownKey = key;
68 + loading?.abort();
69 + loading = null;
70 + // The previous image must not show under the next theme while it loads.
71 + show(null);
72 + if (environmentId === null || themeId === undefined || key === null) return;
73 + const controller = new AbortController();
74 + loading = controller;
75 + const failed = () => {
76 + if (controller.signal.aborted) return;
77 + // Lets the next repaint try again.
78 + shownKey = null;
79 + };
80 + loadBackground(environmentId, themeId, controller.signal).then((url) => {
81 + if (controller.signal.aborted) {
82 + if (url !== null) URL.revokeObjectURL(url);
83 + return;
84 + }
85 + loading = null;
86 + if (url === null) failed();
87 + else show(url);
88 + }, failed);
89 +}
90 +
91 +/** A new image revision does not change the palette, so it does not repaint the theme. */
92 +export function startThemeBackground(): () => void {
93 + return subscribeAtomChanges(themeServerEnvironmentThemesAtom, () =>
94 + applyThemeBackground(document.documentElement.dataset.themeId),
95 + );
96 +}
apps/web/src/themePalette.ts
+2
@@ -30,6 +30,7 @@ import {
30 } from "./lib/contextChipAccents";
31
32 import { appAtomRegistry, subscribeAtomChanges } from "./rpc/atomRegistry";
33 +import { applyThemeBackground } from "./themeBackground";
34 import { applyThemeCss } from "./themeCss";
35 import { themeServerEnvironmentThemesAtom } from "./state/server";
36
@@ -1681,6 +1682,7 @@ export function applyThemePalette(theme: ThemePreference, appearance?: ThemeAppe
1682 setThemePreviewAppearance(null);
1683 const palette = getThemeDefinition(theme);
1684 applyThemeCss(palette?.css);
1685 + applyThemeBackground(palette?.id);
1686
1687 if (palette) {
1688 root.dataset.themeId = palette.id;
docs/user/appearance.md
+16 -1
@@ -62,7 +62,7 @@ the theme, applies after T3 Code's own styles on web and desktop, and is include
62
63 Custom CSS cannot load files. `@import`, `image-set()`, and `url()` are ignored, except `url()`
64 with a `data:` address or an `#id`. This keeps an imported theme from sending what is on your screen
65 -to another site.
65 +to another site. For a full-size image, use a [background image](#background-image).
66
67 Class names in the app change between releases. For rules that keep working, target `data-slot`
68 and other `data-` attributes, such as `[data-chat-header]` or `[data-slot="button"]`.
@@ -132,3 +132,18 @@ view. An optional `css` string adds [custom CSS](#custom-css).
132
133 Write updates to a temporary file and rename it into place so clients never read a partial theme.
134 Invalid files are not published.
135 +
136 +### Background image
137 +
138 +A published theme can have a full-size background image. Ask an agent, for example "use
139 +~/Pictures/wallpaper.jpg as T3 Code's background", or save a JPEG, PNG, or WebP file of up to
140 +16 MB beside the theme file: `nightfall.jpg` beside `nightfall.json`. The theme's CSS decides
141 +where the image shows:
142 +
143 +```css
144 +[data-workspace-area="conversation"] {
145 + background: var(--theme-background-image) center / cover no-repeat;
146 +}
147 +```
148 +
149 +Delete the image file to remove it.
evals/mcp-tool-use/cases/themes.ndjson
+1
@@ -1,3 +1,4 @@
1 {"id": "restyle-t3-code-uses-theme-set", "area": "themes", "kind": "guard", "pattern": "restyle T3 Code itself", "experience": "Asked to change how T3 Code itself looks, an agent reads the theme guide, then publishes a theme with t3_theme_set. It does not write theme files by hand or edit the project.", "rule": "t3_theme_set: Restyle T3 Code itself, only when the user asks.", "privacy": "commit-safe", "source": {"pullRequest": "https://github.com/pingdotgg/t3code/pull/29293", "note": "A user needed a look the app had no setting for."}, "setup": {"role": "top", "mocks": {"t3_theme_read": {"current": "", "builtIn": ["t3-chat", "grove", "ocean", "ember", "iris"], "published": [], "guide": "Themes restyle T3 Code on web and desktop. `canvas` and `accent` (hex) derive a full palette. `css` applies after the app's styles."}, "t3_theme_set": {"themeId": "night-terminal", "published": true}}}, "prompt": "Make T3 Code itself look like a late-night terminal: near-black background with a green accent.", "expect": {"calls": [{"tool": "t3_theme_set", "args": {"theme.appearance": "dark"}}], "order": ["t3_theme_read", "t3_theme_set"]}, "maxSteps": 6}
2 {"id": "control-project-theme-edit-leaves-t3-code-alone", "area": "themes", "kind": "control", "pattern": "ordinary task: edit the project's own theme", "experience": "The user's project has a theme of its own. A request to change it is a file edit. T3 Code's look must not change.", "rule": "t3_theme_set: Restyle T3 Code itself, only when the user asks.", "privacy": "commit-safe", "setup": {"role": "top", "world": {"files": {"src/theme.css": ":root { --accent: #3b82f6; }\n.dark { --accent: #60a5fa; }\n"}}}, "prompt": "Change the dark theme accent to green.", "expect": {"notCalls": ["t3_theme_set", "t3_theme_read"], "textMust": ["theme\\.css"]}, "maxSteps": 6, "source": {"pullRequest": "https://github.com/pingdotgg/t3code/pull/35247", "note": "A real Haiku turn in the dev app during this work: asked to change a project's theme file, it edited the file and left T3 Code alone."}}
3 {"id": "dark-mode-request-sets-appearance", "area": "themes", "kind": "guard", "pattern": "switch T3 Code to dark mode", "experience": "Asked to switch T3 Code to dark mode, an agent sets the appearance with t3_theme_set. It does not tell the user to do it by hand, and it does not publish a new theme.", "rule": "t3_theme_set: `appearance` sets light, dark, or system mode.", "privacy": "commit-safe", "source": {"pullRequest": "https://github.com/pingdotgg/t3code/pull/35247", "note": "In the dev app, an agent asked to swap to dark mode said it could not and sent the user to Settings."}, "setup": {"role": "top", "mocks": {"t3_theme_read": {"current": "sumi", "builtIn": ["t3-chat", "grove", "ocean", "ember", "iris"], "published": [{"id": "sumi", "name": "Sumi", "hasCss": true}], "guide": "Themes restyle T3 Code on web and desktop."}, "t3_theme_set": {"appearance": "dark", "published": false}}}, "prompt": "swap me to dark mode", "expect": {"calls": [{"tool": "t3_theme_set", "args": {"appearance": "dark"}}]}, "maxSteps": 4}
4 +{"id": "theme-background-uses-image-file", "area": "themes", "kind": "bad", "pattern": "put a full-size image behind T3 Code", "experience": "Asked to use a 2.3 MB wallpaper as T3 Code's background, an agent could only embed it as data: text in theme CSS, hit the 20,000 character limit, and told the user T3 Code could not do it.", "rule": "THEME_GUIDE: For a background image, copy a JPEG, PNG, or WebP file to `<themesDir>/<themeId>.jpg`, beside the theme file. CSS shows it with `var(--theme-background-image)`.", "privacy": "commit-safe", "source": {"note": "A user on X shared an agent turn that shrank a wallpaper to fit theme CSS, then said a full-size image needed a T3 Code change."}, "setup": {"role": "top", "mocks": {"t3_theme_read": {"current": "sumi", "builtIn": ["t3-chat", "grove", "ocean", "ember", "iris"], "published": [{"id": "sumi", "name": "Sumi", "hasCss": true, "hasBackground": false}], "theme": {"name": "Sumi", "appearance": "dark", "canvas": "#16161d", "accent": "#c4746e", "css": "[data-chat-header] { border-bottom: 1px solid #2a2a37; }"}, "guide": "Themes restyle T3 Code on web and desktop. `canvas` and `accent` (hex) derive a full palette. `css` applies after the app's styles.", "themesDir": "/home/user/.t3/userdata/themes"}, "t3_theme_set": {"themeId": "sumi", "published": true}}}, "prompt": "Put /home/user/Downloads/frieren.jpeg behind T3 Code as the background of my Sumi theme. It's 2.3 MB and I want the full quality, not a shrunk copy.", "expect": {"shellMust": ["frieren\\.jpeg.*/home/user/\\.t3/userdata/themes/sumi\\.jpe?g"], "calls": [{"tool": "t3_theme_set", "args": {"themeId": "sumi", "theme.css": "~var(--theme-background-image)"}}]}, "maxSteps": 8}
evals/mcp-tool-use/run.ts
+3
@@ -48,6 +48,7 @@ import {
48 ThreadId,
49 } from "@t3tools/contracts";
50 import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences";
51 +import { THEME_GUIDE } from "@t3tools/shared/themeCss";
52 import { formatThreadLink } from "@t3tools/shared/threadLinks";
53 import { buildCodexAdditionalContext } from "../../apps/server/src/provider/CodexDeveloperInstructions.ts";
54 import { makeSideChatContext } from "../../apps/server/src/orchestration-v2/ContextHandoffService.ts";
@@ -1371,6 +1372,8 @@ const unsavedSecretNote = (Contracts as Record<string, unknown>).SECRET_REQUEST_
1372 /** Fields T3 adds to real thread and task results, applied to mocks and defaults alike. */
1373 const withProductFields = (name: string, value: unknown, child: boolean): unknown => {
1374 if (!isRecord(value)) return value;
1375 + // The guide is the checkout's text, so a case's mock cannot go stale.
1376 + if (name === "t3_theme_read") return { ...value, guide: THEME_GUIDE };
1377 const linked = (thread: unknown, idKey = "threadId") => {
1378 if (!isRecord(thread) || thread.link !== undefined) return thread;
1379 const id = thread[idKey] ?? thread.id;
packages/contracts/src/assets.ts
+4
@@ -8,6 +8,7 @@ import {
8 } from "./chatAttachment.ts";
9 import { ProjectFaviconPath } from "./project.ts";
10 import { ToolActivityNativeAppReference } from "./providerRuntime.ts";
11 +import { EnvironmentThemeId } from "./server.ts";
12
13 const ASSET_PATH_MAX_LENGTH = 1024;
14
@@ -66,6 +67,9 @@ export const AssetResource = Schema.Union([
67 // to a request that carries a credential, which the client has none of, so the server fetches
68 // them with the credential the host's driver holds for the repository at `cwd`. `repository`
69 // names the change request's repository, which can differ from the checkout at `cwd`.
70 + Schema.TaggedStruct("environment-theme-background", {
71 + themeId: EnvironmentThemeId,
72 + }),
73 Schema.TaggedStruct(SOURCE_CONTROL_MEDIA_ASSET, {
74 cwd: TrimmedNonEmptyString.check(Schema.isMaxLength(ASSET_PATH_MAX_LENGTH)),
75 url: TrimmedNonEmptyString.check(Schema.isMaxLength(2048)),
packages/contracts/src/server.ts
+2
@@ -653,6 +653,8 @@ export type EnvironmentThemeFile = typeof EnvironmentThemeFile.Type;
653 export const EnvironmentTheme = Schema.Struct({
654 id: EnvironmentThemeId,
655 ...environmentThemeFields,
656 + /** Revision of the image file published beside the theme; absent without one. */
657 + background: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(64))),
658 });
659 export type EnvironmentTheme = typeof EnvironmentTheme.Type;
660
packages/shared/src/themeCss.ts
+1 -1
@@ -79,7 +79,7 @@ export const THEME_GUIDE = [
79 "",
80 "CSS: `css` applies after the app's styles. Use `.dark` or `:root:not(.dark)` for one appearance.",
81 "It cannot load files: no @import, no image-set(), and url() only with data: or #id.",
82 - "A background image must be embedded as a data: address. `css` holds 50,000 characters, so keep the image near 30 KB.",
82 + 'For a background image, copy a JPEG, PNG, or WebP file of up to 16 MB to `<themesDir>/<themeId>.jpg` (or .png, .webp), beside the theme file. CSS shows it with `var(--theme-background-image)`, such as `[data-workspace-area="conversation"] { background: var(--theme-background-image) center / cover no-repeat; }`. Delete the file to remove it. Do not embed images in `css`: it holds 50,000 characters.',
83 "The app's own rules can be more specific. If a rule has no effect, add !important.",
84 "It cannot reach the terminal text, the file tree, or diff internals. Use color roles for those.",
85 "Native scrollbars take `::-webkit-scrollbar` and `::-webkit-scrollbar-thumb`.",