The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 15:45 UTC
feat(web): "could not load" screen tells users how to debug it (#25317)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 25, 2026 at 22:27 UTC
6f3f0d46ea9838385e30f0f3cb3ad9e1ccf6aa53
6 files changed
+252
-21
apps/desktop/src/app/DesktopCliCommand.test.ts
+7
-1
@@ -100,9 +100,15 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
100
const command = yield* commandIn({ home });
101
const link = path.join(home, ".local", "bin", "t3");
102
103
- expect(yield* command.state).toEqual({ supported: true, installedPath: null, onPath: false });
103
+ expect(yield* command.state).toEqual({
104
+ supported: true,
105
+ installedPath: null,
106
+ onPath: false,
107
+ launcherPath: null,
108
+ });
109
const installed = yield* command.install;
110
expect(installed.installedPath).toBe(link);
111
+ expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
112
expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
113
expect((yield* command.install).installedPath).toBe(link);
114
apps/desktop/src/app/DesktopCliCommand.ts
+12
-4
@@ -150,18 +150,26 @@ export const make = Effect.gen(function* () {
150
151
const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
152
if (!environment.isPackaged) {
153
- return { supported: false, installedPath: null, onPath: false } as const;
153
+ return { supported: false, installedPath: null, onPath: false, launcherPath: null } as const;
154
}
155
+ const launcherPath = (yield* exists(launcher)) ? launcher : null;
156
const installed = yield* installedAt;
157
const shadowedBy = yield* foreignFirstOnPath;
158
const shadow = Option.isSome(shadowedBy) ? { shadowedBy: shadowedBy.value } : {};
159
if (Option.isNone(installed)) {
159
- return { supported: true, installedPath: null, onPath: false, ...shadow };
160
+ return { supported: true, installedPath: null, onPath: false, launcherPath, ...shadow };
161
}
162
const first = yield* firstOnPath;
163
const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
163
- return { supported: true, installedPath: installed.value, onPath, ...shadow };
164
- }).pipe(Effect.orElseSucceed(() => ({ supported: false, installedPath: null, onPath: false })));
164
+ return { supported: true, installedPath: installed.value, onPath, launcherPath, ...shadow };
165
+ }).pipe(
166
+ Effect.orElseSucceed(() => ({
167
+ supported: false,
168
+ installedPath: null,
169
+ onPath: false,
170
+ launcherPath: null,
171
+ })),
172
+ );
173
174
const ensureLauncher = DesktopCliShim.install.pipe(
175
Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
apps/web/index.html
+99
-11
@@ -440,27 +440,115 @@
440
}
441
442
#boot-error {
443
- display: grid;
444
- justify-items: center;
445
- gap: 16px;
446
- max-width: 600px;
447
- padding: 24px;
448
- text-align: center;
443
+ --boot-error-fg: #262626;
444
+ --boot-error-bg: #ffffff;
445
+ display: flex;
446
+ flex-direction: column;
447
+ align-items: flex-start;
448
+ width: min(400px, calc(100% - 48px));
449
+ font-size: 13px;
450
+ line-height: 20px;
451
}
452
451
- #boot-error p {
453
+ html.dark #boot-error {
454
+ --boot-error-fg: #f5f5f5;
455
+ --boot-error-bg: #0a0a0a;
456
+ }
457
+
458
+ html[data-theme-selected="true"] #boot-error {
459
+ --boot-error-fg: var(--boot-foreground);
460
+ --boot-error-bg: var(--boot-background);
461
+ }
462
+
463
+ #boot-error h1 {
464
margin: 0;
465
+ font-size: 15px;
466
+ font-weight: 600;
467
+ line-height: 22px;
468
+ }
469
+
470
+ #boot-error p {
471
+ margin: 4px 0 0;
472
+ opacity: 0.6;
473
+ overflow-wrap: anywhere;
474
+ text-wrap: pretty;
475
+ }
476
+
477
+ #boot-error code {
478
+ font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
479
+ font-size: 12px;
480
overflow-wrap: anywhere;
481
}
482
483
#boot-error button {
457
- padding: 8px 16px;
458
- border: 1px solid currentColor;
484
+ border: 0;
485
+ font: inherit;
486
+ cursor: pointer;
487
+ }
488
+
489
+ #boot-error button:focus-visible {
490
+ outline: 2px solid var(--boot-error-fg);
491
+ outline-offset: 2px;
492
+ }
493
+
494
+ #boot-error-command {
495
+ display: flex;
496
+ align-items: center;
497
+ gap: 8px;
498
+ box-sizing: border-box;
499
+ width: 100%;
500
+ padding: 4px 4px 4px 10px;
501
+ border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
502
+ border-radius: 6px;
503
+ }
504
+
505
+ #boot-error-command code {
506
+ flex: 1;
507
+ min-width: 0;
508
+ opacity: 0.8;
509
+ user-select: all;
510
+ }
511
+
512
+ #boot-error-copy {
513
+ display: grid;
514
+ flex: none;
515
+ place-items: center;
516
+ width: 24px;
517
+ height: 24px;
518
border-radius: 4px;
519
background: transparent;
520
color: inherit;
462
- font: inherit;
463
- cursor: pointer;
521
+ opacity: 0.6;
522
+ }
523
+
524
+ #boot-error-copy:hover {
525
+ opacity: 1;
526
+ background: color-mix(in srgb, currentColor 8%, transparent);
527
+ }
528
+
529
+ #boot-error-triage {
530
+ width: 100%;
531
+ margin-top: 40px;
532
+ }
533
+
534
+ #boot-error-triage p {
535
+ margin: 0 0 8px;
536
+ font-size: 12px;
537
+ line-height: 18px;
538
+ }
539
+
540
+ #boot-error-reload {
541
+ height: 32px;
542
+ margin-top: 16px;
543
+ padding: 0 14px;
544
+ border-radius: 6px;
545
+ background: var(--boot-error-fg);
546
+ color: var(--boot-error-bg);
547
+ font-weight: 500;
548
+ }
549
+
550
+ #boot-error-reload:hover {
551
+ opacity: 0.9;
552
}
553
</style>
554
<title>T3 Code (Beta)</title>
apps/web/src/lib/bootError.test.ts
new
+54
@@ -0,0 +1,54 @@
1
+import type { DesktopBridge, DesktopCliCommandState } from "@t3tools/contracts";
2
+import { describe, expect, it, vi } from "vite-plus/test";
3
+
4
+import { resolveTriageCommand } from "./bootError";
5
+
6
+const desktopWith = (getState: () => Promise<DesktopCliCommandState>) =>
7
+ ({ cliCommand: { getState } }) as unknown as DesktopBridge;
8
+
9
+const notOnPath = (launcherPath: string | null): DesktopCliCommandState => ({
10
+ supported: launcherPath !== null,
11
+ installedPath: null,
12
+ onPath: false,
13
+ launcherPath,
14
+});
15
+
16
+describe("resolveTriageCommand", () => {
17
+ it("prefers t3 on PATH, then the desktop launcher", async () => {
18
+ const onPath = { ...notOnPath("/home/me/.t3/bin/t3"), onPath: true };
19
+ await expect(resolveTriageCommand(desktopWith(async () => onPath))).resolves.toBe("t3 triage");
20
+ await expect(
21
+ resolveTriageCommand(desktopWith(async () => notOnPath("/home/me/.t3/bin/t3"))),
22
+ ).resolves.toBe("/home/me/.t3/bin/t3 triage");
23
+ });
24
+
25
+ it("quotes launcher paths for the shell that runs them", async () => {
26
+ await expect(
27
+ resolveTriageCommand(desktopWith(async () => notOnPath("/Users/O'Neil/.t3/bin/t3"))),
28
+ ).resolves.toBe(`'/Users/O'"'"'Neil/.t3/bin/t3' triage`);
29
+ await expect(
30
+ resolveTriageCommand(desktopWith(async () => notOnPath("C:\\Users\\Me\\.t3\\bin\\t3.cmd"))),
31
+ ).resolves.toBe("C:\\Users\\Me\\.t3\\bin\\t3.cmd triage");
32
+ await expect(
33
+ resolveTriageCommand(
34
+ desktopWith(async () => notOnPath("C:\\Users\\Jo O'Neil\\.t3\\bin\\t3.cmd")),
35
+ ),
36
+ ).resolves.toBe("& 'C:\\Users\\Jo O''Neil\\.t3\\bin\\t3.cmd' triage");
37
+ });
38
+
39
+ it("falls back to npx without a usable desktop launcher", async () => {
40
+ using _warn = vi.spyOn(console, "warn").mockImplementation(() => {});
41
+ await expect(resolveTriageCommand(undefined)).resolves.toBe("npx t3 triage");
42
+ await expect(resolveTriageCommand({} as DesktopBridge)).resolves.toBe("npx t3 triage");
43
+ await expect(resolveTriageCommand(desktopWith(async () => notOnPath(null)))).resolves.toBe(
44
+ "npx t3 triage",
45
+ );
46
+ const staleWindowsPathEntry = { ...notOnPath(null), supported: true, onPath: true };
47
+ await expect(
48
+ resolveTriageCommand(desktopWith(async () => staleWindowsPathEntry)),
49
+ ).resolves.toBe("npx t3 triage");
50
+ await expect(
51
+ resolveTriageCommand(desktopWith(() => Promise.reject(new Error("ipc closed")))),
52
+ ).resolves.toBe("npx t3 triage");
53
+ });
54
+});
apps/web/src/lib/bootError.ts
+78
-5
@@ -1,3 +1,40 @@
1
+import type { DesktopBridge } from "@t3tools/contracts";
2
+
3
+const FALLBACK_TRIAGE_COMMAND = "npx t3 triage";
4
+
5
+/** The Windows launcher is a `.cmd` run from PowerShell, which needs `&` to run a quoted path. */
6
+function launcherCommand(launcherPath: string) {
7
+ if (launcherPath.endsWith(".cmd")) {
8
+ return /^[\w:\\.-]+$/.test(launcherPath)
9
+ ? launcherPath
10
+ : `& '${launcherPath.replace(/['\u2018\u2019\u201A\u201B]/g, "$&$&")}'`;
11
+ }
12
+ return /^[\w@%+=:,./-]+$/.test(launcherPath)
13
+ ? launcherPath
14
+ : `'${launcherPath.replaceAll("'", `'"'"'`)}'`;
15
+}
16
+
17
+/** Desktop can run its bundled launcher without Node; everything else falls back to npx. */
18
+export async function resolveTriageCommand(bridge: DesktopBridge | undefined) {
19
+ try {
20
+ const state = await bridge?.cliCommand?.getState();
21
+ // Windows reports onPath from its PATH entry alone; only an existing launcher proves it runs.
22
+ if (state?.launcherPath) {
23
+ return state.onPath ? "t3 triage" : `${launcherCommand(state.launcherPath)} triage`;
24
+ }
25
+ } catch (error) {
26
+ console.warn("Could not read the desktop CLI state.", error);
27
+ }
28
+ return FALLBACK_TRIAGE_COMMAND;
29
+}
30
+
31
+const icon = (paths: string) =>
32
+ `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`;
33
+const COPY_ICON = icon(
34
+ '<rect width="14" height="14" x="8" y="8" rx="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
35
+);
36
+const CHECK_ICON = icon('<path d="M20 6 9 17l-5-5"/>');
37
+
38
export function showBootError(error: unknown) {
39
console.error("T3 Code failed to start.", error);
40
const bootShell = document.getElementById("boot-shell");
@@ -7,20 +44,56 @@ export function showBootError(error: unknown) {
44
content.id = "boot-error";
45
content.setAttribute("role", "alert");
46
10
- const message = document.createElement("p");
11
- message.textContent = "T3 Code could not load.";
12
- content.append(message);
47
+ const title = document.createElement("h1");
48
+ title.textContent = "T3 Code could not load";
49
+ content.append(title);
50
51
if (import.meta.env.DEV && error instanceof Error) {
52
const detail = document.createElement("p");
16
- detail.textContent = error.message;
53
+ detail.append(Object.assign(document.createElement("code"), { textContent: error.message }));
54
content.append(detail);
55
}
56
57
const reload = document.createElement("button");
58
+ reload.id = "boot-error-reload";
59
reload.type = "button";
60
reload.textContent = "Reload";
61
reload.addEventListener("click", () => window.location.reload());
24
- content.append(reload);
62
+
63
+ const hint = document.createElement("p");
64
+ hint.textContent = "If reloading does not help, run this in a terminal to find the cause:";
65
+
66
+ const command = document.createElement("code");
67
+ command.textContent = FALLBACK_TRIAGE_COMMAND;
68
+ const commandRow = document.createElement("div");
69
+ commandRow.id = "boot-error-command";
70
+ commandRow.append(command);
71
+ // The clipboard API exists only in secure contexts, such as HTTPS and the desktop app.
72
+ if (window.isSecureContext) {
73
+ const copy = document.createElement("button");
74
+ copy.id = "boot-error-copy";
75
+ copy.type = "button";
76
+ copy.title = "Copy command";
77
+ copy.setAttribute("aria-label", "Copy command");
78
+ copy.innerHTML = COPY_ICON;
79
+ copy.addEventListener("click", () => {
80
+ navigator.clipboard.writeText(command.textContent ?? "").then(
81
+ () => {
82
+ copy.innerHTML = CHECK_ICON;
83
+ copy.setAttribute("aria-label", "Copied");
84
+ },
85
+ (copyError) => console.warn("Could not copy the triage command.", copyError),
86
+ );
87
+ });
88
+ commandRow.append(copy);
89
+ }
90
+
91
+ const triage = document.createElement("div");
92
+ triage.id = "boot-error-triage";
93
+ triage.append(hint, commandRow);
94
+
95
+ content.append(reload, triage);
96
bootShell.replaceChildren(content);
97
+
98
+ void resolveTriageCommand(window.desktopBridge).then((value) => (command.textContent = value));
99
}
packages/contracts/src/ipc.ts
+2
@@ -321,6 +321,8 @@ export const DesktopCliCommandStateSchema = Schema.Struct({
321
installedPath: Schema.NullOr(Schema.String),
322
onPath: Schema.Boolean,
323
shadowedBy: Schema.optionalKey(Schema.String),
324
+ /** The app's bundled `t3` launcher, which runs without Node or a PATH entry. */
325
+ launcherPath: Schema.NullOr(Schema.String),
326
});
327
export type DesktopCliCommandState = typeof DesktopCliCommandStateSchema.Type;
328