Skip to content

Commit e56923b

Browse files
ashx-jclaude
andcommitted
feat(plugins): plugins add panels, commands, styles and agent tools without a fork
A plugin is a folder with a t3-plugin.json that a user drops onto Settings → Plugins. It installs turned off on one environment, and can ship themes and styles, a server half (RPC methods and channels, storage, settings with secrets in the secret store, and MCP tools for agents) and a web half that loads with T3's own React and UI kit (right panels, commands, a settings panel, assets, and redrawing the composer's control row, the sidebar and the Settings frame). @t3tools/plugin-sdk types both halves and builds a web half. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent bf469bb commit e56923b

202 files changed

Lines changed: 16077 additions & 303 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/desktop/src/electron/ElectronProtocol.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ describe("ElectronProtocol", () => {
9999
assert.equal(yield* Effect.promise(() => response.text()), "ok");
100100
assert.include(
101101
response.headers.get("content-security-policy") ?? "",
102-
"script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://clerk.t3.codes https://challenges.cloudflare.com",
102+
"script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' blob: https://clerk.t3.codes https://challenges.cloudflare.com",
103103
);
104104
assert.include(
105105
response.headers.get("content-security-policy") ?? "",
@@ -111,7 +111,7 @@ describe("ElectronProtocol", () => {
111111
);
112112
assert.include(
113113
response.headers.get("content-security-policy") ?? "",
114-
"font-src 'self' t3code-dev: data:",
114+
"font-src 'self' t3code-dev: blob: data:",
115115
);
116116
}),
117117
);

‎apps/desktop/src/electron/ElectronProtocol.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ function makeDesktopContentSecurityPolicy(input: DesktopProtocolRegistrationInpu
7474
"'self'",
7575
"'unsafe-inline'",
7676
"'wasm-unsafe-eval'",
77+
// Only the page holds each environment's credentials, so plugin bundles it fetches run from blob URLs.
78+
"blob:",
7779
...(clerkOrigin ? [clerkOrigin] : []),
7880
"https://challenges.cloudflare.com",
7981
];
@@ -89,7 +91,8 @@ function makeDesktopContentSecurityPolicy(input: DesktopProtocolRegistrationInpu
8991
`img-src 'self' ${input.scheme}: blob: data: http: https:`,
9092
`media-src 'self' ${input.scheme}: blob: http: https:`,
9193
"style-src 'self' 'unsafe-inline'",
92-
`font-src 'self' ${input.scheme}: data:`,
94+
// `blob:` for fonts a plugin ships, which reach the page through `api.assetUrl`.
95+
`font-src 'self' ${input.scheme}: blob: data:`,
9396
"worker-src 'self' blob:",
9497
"frame-src 'self' blob: http: https:",
9598
"object-src 'self' blob: http: https:",

‎apps/desktop/src/ipc/DesktopIpcHandlers.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ import {
5252
pickProjectFavicon,
5353
pickThemeFiles,
5454
setTheme,
55+
setWindowBackground,
5556
syncHtmlFullscreen,
5657
showContextMenu,
5758
} from "./methods/window.ts";
@@ -146,6 +147,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
146147
yield* ipc.handle(pickProjectFavicon);
147148
yield* ipc.handle(pickThemeFiles);
148149
yield* ipc.handle(setTheme);
150+
yield* ipc.handle(setWindowBackground);
149151
yield* ipc.handle(showContextMenu);
150152
yield* ipc.handle(openExternal);
151153
yield* ipc.handle(readMedia);

‎apps/desktop/src/ipc/channels.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ export const SET_NOTIFICATION_BADGE_CHANNEL = "desktop:set-notification-badge";
33
export const PICK_PROJECT_FAVICON_CHANNEL = "desktop:pick-project-favicon";
44
export const PICK_THEME_FILES_CHANNEL = "desktop:pick-theme-files";
55
export const SET_THEME_CHANNEL = "desktop:set-theme";
6+
export const SET_WINDOW_BACKGROUND_CHANNEL = "desktop:set-window-background";
67
export const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
78
export const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
89
export const READ_MEDIA_CHANNEL = "desktop:read-media";

‎apps/desktop/src/ipc/methods/window.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
DesktopEnvironmentBootstrapSchema,
55
DesktopMediaReadSchema,
66
DesktopThemeSchema,
7+
DesktopWindowBackgroundSchema,
78
EDITORS,
89
EditorId,
910
PickedThemeFileSchema,
@@ -40,6 +41,7 @@ import * as ElectronTheme from "../../electron/ElectronTheme.ts";
4041
import * as ElectronWindow from "../../electron/ElectronWindow.ts";
4142
import * as Electron from "electron";
4243
import * as MacPermissions from "../../permissions/MacPermissions.ts";
44+
import * as DesktopWindow from "../../window/DesktopWindow.ts";
4345
import { safariPermissionCheck } from "../../preview/BrowserImport/SafariPermission.ts";
4446
import * as IpcChannels from "../channels.ts";
4547
import * as DesktopIpc from "../DesktopIpc.ts";
@@ -290,6 +292,17 @@ export const setTheme = DesktopIpc.makeIpcMethod({
290292
}),
291293
});
292294

295+
export const setWindowBackground = DesktopIpc.makeIpcMethod({
296+
channel: IpcChannels.SET_WINDOW_BACKGROUND_CHANNEL,
297+
payload: DesktopWindowBackgroundSchema,
298+
result: Schema.Void,
299+
handler: Effect.fn("desktop.ipc.window.setWindowBackground")(function* (background) {
300+
const appSettings = yield* DesktopAppSettings.DesktopAppSettings;
301+
const change = yield* appSettings.setWindowBackground(background);
302+
if (change.changed) yield* (yield* DesktopWindow.DesktopWindow).syncAppearance;
303+
}),
304+
});
305+
293306
export const showContextMenu = DesktopIpc.makeIpcMethod({
294307
channel: IpcChannels.CONTEXT_MENU_CHANNEL,
295308
payload: ContextMenuInput,

‎apps/desktop/src/preload.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
212212
ipcRenderer.invoke(IpcChannels.PICK_PROJECT_FAVICON_CHANNEL, initialPath),
213213
pickThemeFiles: () => ipcRenderer.invoke(IpcChannels.PICK_THEME_FILES_CHANNEL, undefined),
214214
setTheme: (theme) => ipcRenderer.invoke(IpcChannels.SET_THEME_CHANNEL, theme),
215+
setWindowBackground: (background) =>
216+
ipcRenderer.invoke(IpcChannels.SET_WINDOW_BACKGROUND_CHANNEL, background),
215217
showContextMenu: (items, position) =>
216218
ipcRenderer.invoke(IpcChannels.CONTEXT_MENU_CHANNEL, {
217219
items,

‎apps/desktop/src/settings/DesktopAppSettings.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
22
import * as NodeServices from "@effect/platform-node/NodeServices";
3+
import { DesktopWindowBackgroundSchema } from "@t3tools/contracts";
34
import { assert, describe, it } from "@effect/vitest";
45
import * as Effect from "effect/Effect";
56
import * as FileSystem from "effect/FileSystem";
@@ -35,6 +36,7 @@ const DesktopSettingsPatch = Schema.Struct({
3536
wslMode: Schema.optionalKey(Schema.Literals(["local", "wsl"])),
3637
wslDistro: Schema.optionalKey(Schema.NullOr(Schema.String)),
3738
wslOnly: Schema.optionalKey(Schema.Boolean),
39+
windowCanvases: Schema.optionalKey(DesktopWindowBackgroundSchema),
3840
});
3941

4042
const decodeDesktopSettingsPatch = Schema.decodeEffect(Schema.fromJsonString(DesktopSettingsPatch));
@@ -191,6 +193,7 @@ describe("DesktopSettings", () => {
191193
wslBackendEnabled: false,
192194
wslOnly: false,
193195
wslDistro: null,
196+
windowBackground: null,
194197
} satisfies DesktopAppSettings.DesktopSettings);
195198
}),
196199
),
@@ -229,6 +232,11 @@ describe("DesktopSettings", () => {
229232

230233
yield* settings.setMainWindowBounds({ x: -1200, y: 40, width: 400, height: 360 }, true);
231234
yield* settings.setServerExposureMode("network-accessible");
235+
const windowBackground = {
236+
light: { appearance: "light", color: "#f4f4f4" },
237+
dark: { appearance: "dark", color: "#151515" },
238+
} as const;
239+
yield* settings.setWindowBackground(windowBackground);
232240

233241
const persisted = yield* decodeDesktopSettingsPatch(
234242
yield* fileSystem.readFileString(environment.desktopSettingsPath),
@@ -237,6 +245,7 @@ describe("DesktopSettings", () => {
237245
mainWindowBounds: { x: -1200, y: 40, width: 400, height: 360 },
238246
mainWindowMaximized: true,
239247
serverExposureMode: "network-accessible",
248+
windowCanvases: windowBackground,
240249
} satisfies typeof DesktopSettingsPatch.Type);
241250

242251
const restored = yield* Effect.gen(function* () {
@@ -245,6 +254,7 @@ describe("DesktopSettings", () => {
245254
}).pipe(Effect.provide(DesktopAppSettings.layer));
246255
assert.deepEqual(restored.mainWindowBounds, persisted.mainWindowBounds);
247256
assert.isTrue(restored.mainWindowMaximized);
257+
assert.deepEqual(restored.windowBackground, windowBackground);
248258
}),
249259
),
250260
);
@@ -322,6 +332,7 @@ describe("DesktopSettings", () => {
322332
wslBackendEnabled: false,
323333
wslOnly: false,
324334
wslDistro: null,
335+
windowBackground: null,
325336
} satisfies DesktopAppSettings.DesktopSettings);
326337
}),
327338
{ appVersion: "0.0.17-nightly.20260415.1" },
@@ -351,6 +362,7 @@ describe("DesktopSettings", () => {
351362
wslBackendEnabled: false,
352363
wslOnly: false,
353364
wslDistro: null,
365+
windowBackground: null,
354366
} satisfies DesktopAppSettings.DesktopSettings);
355367
}),
356368
{ appVersion: "0.0.17-nightly.20260415.1" },

‎apps/desktop/src/settings/DesktopAppSettings.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
import {
22
DesktopServerExposureModeSchema,
33
DesktopUpdateChannelSchema,
4+
DesktopWindowBackgroundSchema,
45
type DesktopServerExposureMode,
56
type DesktopUpdateChannel,
7+
type DesktopWindowBackground,
8+
type DesktopWindowCanvas,
69
} from "@t3tools/contracts";
710
import { fromLenientJson } from "@t3tools/shared/schemaJson";
811
import { resolveSymlinkTarget } from "@t3tools/shared/symlink";
@@ -39,6 +42,8 @@ export interface DesktopSettings {
3942
readonly wslDistro: string | null;
4043
// Requires restart because the pool chooses its primary spec at layer initialization.
4144
readonly wslOnly: boolean;
45+
/** The renderer's theme canvases, painted before the page loads. */
46+
readonly windowBackground: DesktopWindowBackground | null;
4247
}
4348

4449
export interface DesktopSettingsChange {
@@ -79,6 +84,7 @@ export const DEFAULT_DESKTOP_SETTINGS: DesktopSettings = {
7984
wslBackendEnabled: false,
8085
wslDistro: null,
8186
wslOnly: false,
87+
windowBackground: null,
8288
};
8389

8490
const DesktopWindowBoundsDocument = Schema.Struct({
@@ -102,6 +108,7 @@ const DesktopSettingsDocument = Schema.Struct({
102108
wslMode: Schema.optionalKey(Schema.Literals(["local", "wsl"])),
103109
wslDistro: Schema.optionalKey(Schema.NullOr(Schema.String)),
104110
wslOnly: Schema.optionalKey(Schema.Boolean),
111+
windowCanvases: Schema.optionalKey(Schema.Unknown),
105112
});
106113

107114
type DesktopSettingsDocument = typeof DesktopSettingsDocument.Type;
@@ -112,6 +119,8 @@ const decodeDesktopSettingsJson = Schema.decodeEffect(DesktopSettingsJson);
112119
const encodeDesktopSettingsJson = Schema.encodeEffect(DesktopSettingsJson);
113120
const decodeDesktopWindowBounds = Schema.decodeUnknownOption(DesktopWindowBoundsSchema);
114121
const desktopWindowBoundsEquivalence = Schema.toEquivalence(DesktopWindowBoundsSchema);
122+
const decodeDesktopWindowBackground = Schema.decodeUnknownOption(DesktopWindowBackgroundSchema);
123+
const desktopWindowBackgroundEquivalence = Schema.toEquivalence(DesktopWindowBackgroundSchema);
115124

116125
const settingsChange = (settings: DesktopSettings, changed: boolean): DesktopSettingsChange => ({
117126
settings,
@@ -172,6 +181,9 @@ export class DesktopAppSettings extends Context.Service<
172181
readonly setWslOnly: (
173182
enabled: boolean,
174183
) => Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError>;
184+
readonly setWindowBackground: (
185+
background: DesktopWindowBackground,
186+
) => Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError>;
175187
readonly applyWslWindowsFallback: Effect.Effect<
176188
DesktopSettingsChange,
177189
DesktopSettingsWriteError
@@ -197,6 +209,21 @@ function normalizeWslDistro(value: unknown): string | null {
197209
return typeof value === "string" && isValidDistroName(value) ? value : null;
198210
}
199211

212+
function normalizeWindowColor(value: unknown): string | null {
213+
return typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value) ? value.toLowerCase() : null;
214+
}
215+
216+
function normalizeWindowBackground(value: unknown): DesktopWindowBackground | null {
217+
const canvas = ({ appearance, color }: DesktopWindowCanvas): DesktopWindowCanvas => ({
218+
appearance,
219+
color: normalizeWindowColor(color),
220+
});
221+
return Option.match(decodeDesktopWindowBackground(value), {
222+
onNone: () => null,
223+
onSome: (background) => ({ light: canvas(background.light), dark: canvas(background.dark) }),
224+
});
225+
}
226+
200227
export function normalizeMainWindowBounds(value: unknown): DesktopWindowBounds | null {
201228
return Option.getOrNull(decodeDesktopWindowBounds(value));
202229
}
@@ -233,6 +260,7 @@ function normalizeDesktopSettingsDocument(
233260
wslBackendEnabled,
234261
wslDistro: normalizeWslDistro(parsed.wslDistro),
235262
wslOnly: parsed.wslOnly === true,
263+
windowBackground: normalizeWindowBackground(parsed.windowCanvases),
236264
};
237265
}
238266

@@ -279,6 +307,9 @@ function toDesktopSettingsDocument(
279307
if (settings.wslOnly !== defaults.wslOnly) {
280308
document.wslOnly = settings.wslOnly;
281309
}
310+
if (settings.windowBackground !== null) {
311+
document.windowCanvases = settings.windowBackground;
312+
}
282313

283314
return document;
284315
}
@@ -369,6 +400,18 @@ function setWslOnly(settings: DesktopSettings, enabled: boolean): DesktopSetting
369400
};
370401
}
371402

403+
function setWindowBackground(
404+
settings: DesktopSettings,
405+
background: DesktopWindowBackground,
406+
): DesktopSettings {
407+
const normalized = normalizeWindowBackground(background);
408+
return settings.windowBackground !== null &&
409+
normalized !== null &&
410+
desktopWindowBackgroundEquivalence(settings.windowBackground, normalized)
411+
? settings
412+
: { ...settings, windowBackground: normalized };
413+
}
414+
372415
function setLocalEnvironmentEnabled(settings: DesktopSettings, enabled: boolean): DesktopSettings {
373416
return settings.localEnvironmentEnabled === enabled
374417
? settings
@@ -561,6 +604,14 @@ export const make = Effect.gen(function* () {
561604

562605
return yield* persist((settings) => setWslOnly(settings, enabled));
563606
}),
607+
setWindowBackground: Effect.fn("desktop.settings.setWindowBackground")(function* (background) {
608+
yield* Effect.annotateCurrentSpan({
609+
light: background.light.color,
610+
dark: background.dark.color,
611+
});
612+
613+
return yield* persist((settings) => setWindowBackground(settings, background));
614+
}),
564615
setLocalEnvironmentEnabled: Effect.fn("desktop.settings.setLocalEnvironmentEnabled")(
565616
function* (enabled) {
566617
yield* Effect.annotateCurrentSpan({ enabled });
@@ -626,6 +677,11 @@ export const layerTest = (initialSettings: DesktopSettings = DEFAULT_DESKTOP_SET
626677
setWslOnly: Effect.fn("DesktopAppSettings.setWslOnly")(function (enabled) {
627678
return update((settings) => setWslOnly(settings, enabled));
628679
}),
680+
setWindowBackground: Effect.fn("DesktopAppSettings.setWindowBackground")(
681+
function (background) {
682+
return update((settings) => setWindowBackground(settings, background));
683+
},
684+
),
629685
setLocalEnvironmentEnabled: Effect.fn("DesktopAppSettings.setLocalEnvironmentEnabled")(
630686
function (enabled) {
631687
return update((settings) => setLocalEnvironmentEnabled(settings, enabled));

‎apps/desktop/src/updates/updatesTestHarness.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,7 @@ export function makeHarness(options: UpdatesHarnessOptions = {}) {
231231
setWslDistro: () => Effect.die("unexpected WSL distro change"),
232232
setLocalEnvironmentEnabled: () => Effect.die("unexpected local environment toggle"),
233233
setWslOnly: () => Effect.die("unexpected WSL-only toggle"),
234+
setWindowBackground: () => Effect.die("unexpected window background update"),
234235
applyWslWindowsFallback: Effect.die("unexpected WSL Windows fallback"),
235236
applyWslWindowsFallbackInMemory: Effect.die("unexpected WSL Windows fallback"),
236237
} satisfies DesktopAppSettings.DesktopAppSettings["Service"])

‎apps/desktop/src/window/DesktopWindow.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,7 @@ function layerTest(input: {
269269
setWslBackendEnabled: () => Effect.die("unexpected WSL backend toggle"),
270270
setWslDistro: () => Effect.die("unexpected WSL distro change"),
271271
setWslOnly: () => Effect.die("unexpected WSL-only toggle"),
272+
setWindowBackground: () => Effect.die("unexpected window background update"),
272273
setLocalEnvironmentEnabled: () => Effect.die("unexpected local environment toggle"),
273274
applyWslWindowsFallback: Effect.die("unexpected WSL Windows fallback"),
274275
applyWslWindowsFallbackInMemory: Effect.die("unexpected WSL Windows fallback"),
@@ -505,6 +506,33 @@ describe("DesktopWindow", () => {
505506
}
506507
});
507508

509+
it("starts windows in the canvas the page paints in the current appearance", () => {
510+
const surface = {
511+
light: { appearance: "light", color: "#f4f4f4" },
512+
dark: { appearance: "dark", color: "#151515" },
513+
} as const;
514+
const pinnedDark = {
515+
light: { appearance: "dark", color: "#151515" },
516+
dark: { appearance: "dark", color: "#151515" },
517+
} as const;
518+
const plain = {
519+
light: { appearance: "light", color: null },
520+
dark: { appearance: "dark", color: null },
521+
} as const;
522+
for (const [shouldUseDarkColors, background, expected] of [
523+
[false, surface, { color: "#f4f4f4", dark: false }],
524+
[true, surface, { color: "#151515", dark: true }],
525+
[false, pinnedDark, { color: "#151515", dark: true }],
526+
[true, plain, { color: "#000000", dark: true }],
527+
[false, null, { color: "#ffffff", dark: false }],
528+
] as const) {
529+
assert.deepEqual(
530+
DesktopWindow.resolveWindowCanvas(shouldUseDarkColors, background),
531+
expected,
532+
);
533+
}
534+
});
535+
508536
it("rejects renderer navigations whose origin only serializes as null", () => {
509537
for (const applicationUrl of ["t3code://app/", "t3code-dev://app/"]) {
510538
assert.isTrue(

0 commit comments

Comments
 (0)