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`.",