Skip to content

Commit 6f3f0d4

Browse files
t3dotggclaude
andauthored
feat(web): "could not load" screen tells users how to debug it (pingdotgg#25317)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 1549046 commit 6f3f0d4

6 files changed

Lines changed: 252 additions & 21 deletions

File tree

‎apps/desktop/src/app/DesktopCliCommand.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,15 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
100100
const command = yield* commandIn({ home });
101101
const link = path.join(home, ".local", "bin", "t3");
102102

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+
});
104109
const installed = yield* command.install;
105110
expect(installed.installedPath).toBe(link);
111+
expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
106112
expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
107113
expect((yield* command.install).installedPath).toBe(link);
108114

‎apps/desktop/src/app/DesktopCliCommand.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -150,18 +150,26 @@ export const make = Effect.gen(function* () {
150150

151151
const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
152152
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;
154154
}
155+
const launcherPath = (yield* exists(launcher)) ? launcher : null;
155156
const installed = yield* installedAt;
156157
const shadowedBy = yield* foreignFirstOnPath;
157158
const shadow = Option.isSome(shadowedBy) ? { shadowedBy: shadowedBy.value } : {};
158159
if (Option.isNone(installed)) {
159-
return { supported: true, installedPath: null, onPath: false, ...shadow };
160+
return { supported: true, installedPath: null, onPath: false, launcherPath, ...shadow };
160161
}
161162
const first = yield* firstOnPath;
162163
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+
);
165173

166174
const ensureLauncher = DesktopCliShim.install.pipe(
167175
Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),

‎apps/web/index.html‎

Lines changed: 99 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -440,27 +440,115 @@
440440
}
441441

442442
#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;
449451
}
450452

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 {
452464
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;
453480
overflow-wrap: anywhere;
454481
}
455482

456483
#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;
459518
border-radius: 4px;
460519
background: transparent;
461520
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;
464552
}
465553
</style>
466554
<title>T3 Code (Beta)</title>

‎apps/web/src/lib/bootError.test.ts‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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‎

Lines changed: 78 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
138
export function showBootError(error: unknown) {
239
console.error("T3 Code failed to start.", error);
340
const bootShell = document.getElementById("boot-shell");
@@ -7,20 +44,56 @@ export function showBootError(error: unknown) {
744
content.id = "boot-error";
845
content.setAttribute("role", "alert");
946

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);
1350

1451
if (import.meta.env.DEV && error instanceof Error) {
1552
const detail = document.createElement("p");
16-
detail.textContent = error.message;
53+
detail.append(Object.assign(document.createElement("code"), { textContent: error.message }));
1754
content.append(detail);
1855
}
1956

2057
const reload = document.createElement("button");
58+
reload.id = "boot-error-reload";
2159
reload.type = "button";
2260
reload.textContent = "Reload";
2361
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);
2596
bootShell.replaceChildren(content);
97+
98+
void resolveTriageCommand(window.desktopBridge).then((value) => (command.textContent = value));
2699
}

‎packages/contracts/src/ipc.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,8 @@ export const DesktopCliCommandStateSchema = Schema.Struct({
321321
installedPath: Schema.NullOr(Schema.String),
322322
onPath: Schema.Boolean,
323323
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),
324326
});
325327
export type DesktopCliCommandState = typeof DesktopCliCommandStateSchema.Type;
326328

0 commit comments

Comments
 (0)