feat(web): "could not load" screen tells users how to debug it

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

@@ -100,9 +100,15 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
       const command = yield* commandIn({ home });
       const link = path.join(home, ".local", "bin", "t3");
 
-      expect(yield* command.state).toEqual({ supported: true, installedPath: null, onPath: false });
+      expect(yield* command.state).toEqual({
+        supported: true,
+        installedPath: null,
+        onPath: false,
+        launcherPath: null,
+      });
       const installed = yield* command.install;
       expect(installed.installedPath).toBe(link);
+      expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
       expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
       expect((yield* command.install).installedPath).toBe(link);
 

apps/desktop/src/app/DesktopCliCommand.ts

@@ -150,18 +150,26 @@ export const make = Effect.gen(function* () {
 
   const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
     if (!environment.isPackaged) {
-      return { supported: false, installedPath: null, onPath: false } as const;
+      return { supported: false, installedPath: null, onPath: false, launcherPath: null } as const;
     }
+    const launcherPath = (yield* exists(launcher)) ? launcher : null;
     const installed = yield* installedAt;
     const shadowedBy = yield* foreignFirstOnPath;
     const shadow = Option.isSome(shadowedBy) ? { shadowedBy: shadowedBy.value } : {};
     if (Option.isNone(installed)) {
-      return { supported: true, installedPath: null, onPath: false, ...shadow };
+      return { supported: true, installedPath: null, onPath: false, launcherPath, ...shadow };
     }
     const first = yield* firstOnPath;
     const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
-    return { supported: true, installedPath: installed.value, onPath, ...shadow };
-  }).pipe(Effect.orElseSucceed(() => ({ supported: false, installedPath: null, onPath: false })));
+    return { supported: true, installedPath: installed.value, onPath, launcherPath, ...shadow };
+  }).pipe(
+    Effect.orElseSucceed(() => ({
+      supported: false,
+      installedPath: null,
+      onPath: false,
+      launcherPath: null,
+    })),
+  );
 
   const ensureLauncher = DesktopCliShim.install.pipe(
     Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),

apps/web/index.html

@@ -440,27 +440,115 @@
       }
 
       #boot-error {
-        display: grid;
-        justify-items: center;
-        gap: 16px;
-        max-width: 600px;
-        padding: 24px;
-        text-align: center;
+        --boot-error-fg: #262626;
+        --boot-error-bg: #ffffff;
+        display: flex;
+        flex-direction: column;
+        align-items: flex-start;
+        width: min(400px, calc(100% - 48px));
+        font-size: 13px;
+        line-height: 20px;
       }
 
-      #boot-error p {
+      html.dark #boot-error {
+        --boot-error-fg: #f5f5f5;
+        --boot-error-bg: #0a0a0a;
+      }
+
+      html[data-theme-selected="true"] #boot-error {
+        --boot-error-fg: var(--boot-foreground);
+        --boot-error-bg: var(--boot-background);
+      }
+
+      #boot-error h1 {
         margin: 0;
+        font-size: 15px;
+        font-weight: 600;
+        line-height: 22px;
+      }
+
+      #boot-error p {
+        margin: 4px 0 0;
+        opacity: 0.6;
+        overflow-wrap: anywhere;
+        text-wrap: pretty;
+      }
+
+      #boot-error code {
+        font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+        font-size: 12px;
         overflow-wrap: anywhere;
       }
 
       #boot-error button {
-        padding: 8px 16px;
-        border: 1px solid currentColor;
+        border: 0;
+        font: inherit;
+        cursor: pointer;
+      }
+
+      #boot-error button:focus-visible {
+        outline: 2px solid var(--boot-error-fg);
+        outline-offset: 2px;
+      }
+
+      #boot-error-command {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        box-sizing: border-box;
+        width: 100%;
+        padding: 4px 4px 4px 10px;
+        border: 1px solid color-mix(in srgb, currentColor 10%, transparent);
+        border-radius: 6px;
+      }
+
+      #boot-error-command code {
+        flex: 1;
+        min-width: 0;
+        opacity: 0.8;
+        user-select: all;
+      }
+
+      #boot-error-copy {
+        display: grid;
+        flex: none;
+        place-items: center;
+        width: 24px;
+        height: 24px;
         border-radius: 4px;
         background: transparent;
         color: inherit;
-        font: inherit;
-        cursor: pointer;
+        opacity: 0.6;
+      }
+
+      #boot-error-copy:hover {
+        opacity: 1;
+        background: color-mix(in srgb, currentColor 8%, transparent);
+      }
+
+      #boot-error-triage {
+        width: 100%;
+        margin-top: 40px;
+      }
+
+      #boot-error-triage p {
+        margin: 0 0 8px;
+        font-size: 12px;
+        line-height: 18px;
+      }
+
+      #boot-error-reload {
+        height: 32px;
+        margin-top: 16px;
+        padding: 0 14px;
+        border-radius: 6px;
+        background: var(--boot-error-fg);
+        color: var(--boot-error-bg);
+        font-weight: 500;
+      }
+
+      #boot-error-reload:hover {
+        opacity: 0.9;
       }
     </style>
     <title>T3 Code (Beta)</title>

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

@@ -0,0 +1,54 @@
+import type { DesktopBridge, DesktopCliCommandState } from "@t3tools/contracts";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { resolveTriageCommand } from "./bootError";
+
+const desktopWith = (getState: () => Promise<DesktopCliCommandState>) =>
+  ({ cliCommand: { getState } }) as unknown as DesktopBridge;
+
+const notOnPath = (launcherPath: string | null): DesktopCliCommandState => ({
+  supported: launcherPath !== null,
+  installedPath: null,
+  onPath: false,
+  launcherPath,
+});
+
+describe("resolveTriageCommand", () => {
+  it("prefers t3 on PATH, then the desktop launcher", async () => {
+    const onPath = { ...notOnPath("/home/me/.t3/bin/t3"), onPath: true };
+    await expect(resolveTriageCommand(desktopWith(async () => onPath))).resolves.toBe("t3 triage");
+    await expect(
+      resolveTriageCommand(desktopWith(async () => notOnPath("/home/me/.t3/bin/t3"))),
+    ).resolves.toBe("/home/me/.t3/bin/t3 triage");
+  });
+
+  it("quotes launcher paths for the shell that runs them", async () => {
+    await expect(
+      resolveTriageCommand(desktopWith(async () => notOnPath("/Users/O'Neil/.t3/bin/t3"))),
+    ).resolves.toBe(`'/Users/O'"'"'Neil/.t3/bin/t3' triage`);
+    await expect(
+      resolveTriageCommand(desktopWith(async () => notOnPath("C:\\Users\\Me\\.t3\\bin\\t3.cmd"))),
+    ).resolves.toBe("C:\\Users\\Me\\.t3\\bin\\t3.cmd triage");
+    await expect(
+      resolveTriageCommand(
+        desktopWith(async () => notOnPath("C:\\Users\\Jo O'Neil\\.t3\\bin\\t3.cmd")),
+      ),
+    ).resolves.toBe("& 'C:\\Users\\Jo O''Neil\\.t3\\bin\\t3.cmd' triage");
+  });
+
+  it("falls back to npx without a usable desktop launcher", async () => {
+    using _warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await expect(resolveTriageCommand(undefined)).resolves.toBe("npx t3 triage");
+    await expect(resolveTriageCommand({} as DesktopBridge)).resolves.toBe("npx t3 triage");
+    await expect(resolveTriageCommand(desktopWith(async () => notOnPath(null)))).resolves.toBe(
+      "npx t3 triage",
+    );
+    const staleWindowsPathEntry = { ...notOnPath(null), supported: true, onPath: true };
+    await expect(
+      resolveTriageCommand(desktopWith(async () => staleWindowsPathEntry)),
+    ).resolves.toBe("npx t3 triage");
+    await expect(
+      resolveTriageCommand(desktopWith(() => Promise.reject(new Error("ipc closed")))),
+    ).resolves.toBe("npx t3 triage");
+  });
+});

apps/web/src/lib/bootError.ts

@@ -1,3 +1,40 @@
+import type { DesktopBridge } from "@t3tools/contracts";
+
+const FALLBACK_TRIAGE_COMMAND = "npx t3 triage";
+
+/** The Windows launcher is a `.cmd` run from PowerShell, which needs `&` to run a quoted path. */
+function launcherCommand(launcherPath: string) {
+  if (launcherPath.endsWith(".cmd")) {
+    return /^[\w:\\.-]+$/.test(launcherPath)
+      ? launcherPath
+      : `& '${launcherPath.replace(/['\u2018\u2019\u201A\u201B]/g, "$&$&")}'`;
+  }
+  return /^[\w@%+=:,./-]+$/.test(launcherPath)
+    ? launcherPath
+    : `'${launcherPath.replaceAll("'", `'"'"'`)}'`;
+}
+
+/** Desktop can run its bundled launcher without Node; everything else falls back to npx. */
+export async function resolveTriageCommand(bridge: DesktopBridge | undefined) {
+  try {
+    const state = await bridge?.cliCommand?.getState();
+    // Windows reports onPath from its PATH entry alone; only an existing launcher proves it runs.
+    if (state?.launcherPath) {
+      return state.onPath ? "t3 triage" : `${launcherCommand(state.launcherPath)} triage`;
+    }
+  } catch (error) {
+    console.warn("Could not read the desktop CLI state.", error);
+  }
+  return FALLBACK_TRIAGE_COMMAND;
+}
+
+const icon = (paths: string) =>
+  `<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>`;
+const COPY_ICON = icon(
+  '<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"/>',
+);
+const CHECK_ICON = icon('<path d="M20 6 9 17l-5-5"/>');
+
 export function showBootError(error: unknown) {
   console.error("T3 Code failed to start.", error);
   const bootShell = document.getElementById("boot-shell");
@@ -7,20 +44,56 @@ export function showBootError(error: unknown) {
   content.id = "boot-error";
   content.setAttribute("role", "alert");
 
-  const message = document.createElement("p");
-  message.textContent = "T3 Code could not load.";
-  content.append(message);
+  const title = document.createElement("h1");
+  title.textContent = "T3 Code could not load";
+  content.append(title);
 
   if (import.meta.env.DEV && error instanceof Error) {
     const detail = document.createElement("p");
-    detail.textContent = error.message;
+    detail.append(Object.assign(document.createElement("code"), { textContent: error.message }));
     content.append(detail);
   }
 
   const reload = document.createElement("button");
+  reload.id = "boot-error-reload";
   reload.type = "button";
   reload.textContent = "Reload";
   reload.addEventListener("click", () => window.location.reload());
-  content.append(reload);
+
+  const hint = document.createElement("p");
+  hint.textContent = "If reloading does not help, run this in a terminal to find the cause:";
+
+  const command = document.createElement("code");
+  command.textContent = FALLBACK_TRIAGE_COMMAND;
+  const commandRow = document.createElement("div");
+  commandRow.id = "boot-error-command";
+  commandRow.append(command);
+  // The clipboard API exists only in secure contexts, such as HTTPS and the desktop app.
+  if (window.isSecureContext) {
+    const copy = document.createElement("button");
+    copy.id = "boot-error-copy";
+    copy.type = "button";
+    copy.title = "Copy command";
+    copy.setAttribute("aria-label", "Copy command");
+    copy.innerHTML = COPY_ICON;
+    copy.addEventListener("click", () => {
+      navigator.clipboard.writeText(command.textContent ?? "").then(
+        () => {
+          copy.innerHTML = CHECK_ICON;
+          copy.setAttribute("aria-label", "Copied");
+        },
+        (copyError) => console.warn("Could not copy the triage command.", copyError),
+      );
+    });
+    commandRow.append(copy);
+  }
+
+  const triage = document.createElement("div");
+  triage.id = "boot-error-triage";
+  triage.append(hint, commandRow);
+
+  content.append(reload, triage);
   bootShell.replaceChildren(content);
+
+  void resolveTriageCommand(window.desktopBridge).then((value) => (command.textContent = value));
 }

packages/contracts/src/ipc.ts

@@ -321,6 +321,8 @@ export const DesktopCliCommandStateSchema = Schema.Struct({
   installedPath: Schema.NullOr(Schema.String),
   onPath: Schema.Boolean,
   shadowedBy: Schema.optionalKey(Schema.String),
+  /** The app's bundled `t3` launcher, which runs without Node or a PATH entry. */
+  launcherPath: Schema.NullOr(Schema.String),
 });
 export type DesktopCliCommandState = typeof DesktopCliCommandStateSchema.Type;