@devries-cameron20 / t3code-1 / commits / 6f3f0d46ea
Fork 0

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

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