Real 404 pages and per-route document titles (#1272)

* Retry setup-status checks before showing auth

* Show real not found pages and route titles

Author: RhysSullivan

apps/host-selfhost/web/routes/__root.tsx

@@ -33,6 +33,7 @@ import { fetchNeedsSetup } from "../setup-status";
 // ---------------------------------------------------------------------------
 
 export const Route = createRootRoute({
+  notFoundComponent: NotFoundPage,
   component: RootComponent,
 });
 
@@ -50,6 +51,26 @@ const signOut = async () => {
   window.location.href = "/";
 };
 
+function NotFoundPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-background px-6 py-10">
+      <section className="w-full max-w-md text-center">
+        <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">404</p>
+        <h1 className="mt-2 text-xl font-semibold text-foreground">Page not found</h1>
+        <p className="mt-2 text-sm leading-6 text-muted-foreground">
+          There&apos;s nothing at this address.
+        </p>
+        <a
+          href="/"
+          className="mt-6 inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground shadow transition-colors hover:bg-primary/90"
+        >
+          Go home
+        </a>
+      </section>
+    </main>
+  );
+}
+
 const Loading = () => (
   <div className="flex min-h-screen items-center justify-center text-sm text-muted-foreground">
     Loading…

apps/host-selfhost/web/routes/app/admin.tsx

@@ -10,6 +10,7 @@ import { CopyButton } from "@executor-js/react/components/copy-button";
 import { Input } from "@executor-js/react/components/input";
 import { Label } from "@executor-js/react/components/label";
 import { NativeSelect, NativeSelectOption } from "@executor-js/react/components/native-select";
+import { useExecutorDocumentTitle } from "@executor-js/react/lib/document-title";
 import {
   orgMembersAtom,
   removeMember,
@@ -29,6 +30,7 @@ const ROLES = ["member", "admin"] as const;
 // are the self-host join mechanism. The API gates to owner/admin, so a
 // non-admin who opens this just sees load failures.
 function AdminPage() {
+  useExecutorDocumentTitle("Admin");
   return (
     <div className="min-h-0 flex-1 overflow-y-auto">
       <div className="mx-auto flex max-w-3xl flex-col gap-10 px-6 py-10 lg:px-8 lg:py-14">

packages/app/src/routes/__root.tsx

@@ -7,9 +7,30 @@ import { plugins as clientPlugins } from "virtual:executor/plugins-client";
 import { Shell } from "../web/shell";
 
 export const Route = createRootRoute({
+  notFoundComponent: NotFoundPage,
   component: RootComponent,
 });
 
+function NotFoundPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-background px-6 py-10">
+      <section className="w-full max-w-md text-center">
+        <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">404</p>
+        <h1 className="mt-2 text-xl font-semibold text-foreground">Page not found</h1>
+        <p className="mt-2 text-sm leading-6 text-muted-foreground">
+          There&apos;s nothing at this address.
+        </p>
+        <a
+          href="/"
+          className="mt-6 inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground shadow transition-colors hover:bg-primary/90"
+        >
+          Go home
+        </a>
+      </section>
+    </main>
+  );
+}
+
 function RootComponent() {
   return (
     <ExecutorProvider>

packages/react/package.json

@@ -17,6 +17,7 @@
     "./components/*": "./src/components/*.tsx",
     "./hooks/*": "./src/hooks/*.ts",
     "./lib/auth-placements": "./src/lib/auth-placements.tsx",
+    "./lib/document-title": "./src/lib/document-title.tsx",
     "./lib/integration-add": "./src/lib/integration-add.tsx",
     "./lib/*": "./src/lib/*.ts",
     "./globals.css": "./src/styles/globals.css",

packages/react/src/lib/document-title.tsx

@@ -0,0 +1,14 @@
+import { useEffect } from "react";
+
+const APP_NAME = "Executor";
+
+export function executorDocumentTitle(page: string): string {
+  return `${page} · ${APP_NAME}`;
+}
+
+export function useExecutorDocumentTitle(page: string | null | undefined): void {
+  useEffect(() => {
+    if (!page || typeof document === "undefined") return;
+    document.title = executorDocumentTitle(page);
+  }, [page]);
+}

packages/react/src/multiplayer/org-slug-gate.tsx

@@ -1,22 +1,31 @@
 import { useEffect, type ReactNode } from "react";
-import { useNavigate, useParams } from "@tanstack/react-router";
+import { useNavigate, useParams, useRouterState } from "@tanstack/react-router";
 
 // ---------------------------------------------------------------------------
 // Org-slug URL canonicalization for org-scoped hosts (cloud, self-host,
 // cloudflare). Console routes live under an optional `{-$orgSlug}` segment, so
 // the same tree serves `/policies` and `/acme/policies`; this gate, mounted
-// inside the authenticated shell, pins a BARE URL to the active org's slug:
+// inside the authenticated shell, pins the URL to the active org's slug:
 //
-//   - bare URL            → replace with `/<active-slug>/…` (canonicalize)
-//   - slug already in URL → render
+//   - bare URL                  → replace with `/<active-slug>/…` (canonicalize)
+//   - active slug already in URL → render
+//   - any other slug in URL     → replace with `/<active-slug>/…` (canonicalize)
 //
 // The URL slug is the request SCOPE, not just a label: every API call carries
 // it (the `x-executor-organization` header), and the server re-checks live
 // membership and resolves data for that org — same as the MCP URL-pinned org.
-// So a foreign slug never reaches this gate as "active": the server returns no
-// organization for an org the caller can't see, and the shell 404s upstream.
-// That makes two browser tabs on different orgs fully independent — no shared
-// "active org" to steal.
+// So a foreign slug never reaches this gate as "active" on a multi-org host:
+// the server returns no organization for an org the caller can't see, and the
+// shell 404s upstream. That makes two browser tabs on different orgs fully
+// independent — no shared "active org" to steal. On a single-org host (e.g.
+// self-host) every slug resolves to the same org server-side, so a bogus slug
+// (e.g. `/totally-bogus`) would otherwise fuzzy-match a route and render
+// under the wrong URL forever; canonicalizing it here fixes the URL instead.
+//
+// A genuinely unmatched path is neither of the above: it has no `orgSlug`
+// param (nothing below root matched) but isn't a bare URL either, so it must
+// NOT canonicalize — doing so would silently rewrite a bad URL into a valid
+// one instead of letting the not-found page render.
 // ---------------------------------------------------------------------------
 
 export interface OrgSlugGateProps {
@@ -31,9 +40,13 @@ export function OrgSlugGate(props: OrgSlugGateProps) {
   const urlSlug = params.orgSlug ?? null;
   const navigate = useNavigate();
 
-  // Only a BARE URL canonicalizes. A slug in the URL is the scope the whole
-  // request chain already ran with, so it always matches `activeSlug` here.
-  const needsCanonicalize = urlSlug === null;
+  // Skip canonicalization whenever the router is currently sitting on a
+  // not-found match — see the file header for why.
+  const isNotFound = useRouterState({
+    select: (state) => state.matches.some((match) => match.globalNotFound),
+  });
+
+  const needsCanonicalize = urlSlug !== activeSlug && !isNotFound;
 
   useEffect(() => {
     if (!needsCanonicalize) return;

packages/react/src/pages/api-keys.tsx

@@ -20,6 +20,7 @@ import {
 } from "../components/dialog";
 import { Input } from "../components/input";
 import { Label } from "../components/label";
+import { useExecutorDocumentTitle } from "../lib/document-title";
 
 // ---------------------------------------------------------------------------
 // Shared API-keys page. Reads/writes the provider-neutral `/account/api-keys`
@@ -58,6 +59,7 @@ const defaultApiKeyName = (): string =>
   }).format(new Date())}`;
 
 export function ApiKeysPage() {
+  useExecutorDocumentTitle("API keys");
   const result = useAtomValue(apiKeysAtom);
   const doCreate = useAtomSet(createApiKey, { mode: "promiseExit" });
   const doRevoke = useAtomSet(revokeApiKey, { mode: "promiseExit" });

packages/react/src/pages/integration-add.tsx

@@ -2,6 +2,7 @@ import { Suspense } from "react";
 import { Link, useNavigate } from "@tanstack/react-router";
 import { useIntegrationPlugins } from "@executor-js/sdk/client";
 import { trackEvent } from "../api/analytics";
+import { useExecutorDocumentTitle } from "../lib/document-title";
 
 // ---------------------------------------------------------------------------
 // Page
@@ -13,6 +14,7 @@ export function AddIntegrationPage(props: {
   preset?: string;
   namespace?: string;
 }) {
+  useExecutorDocumentTitle("Add integration");
   const { pluginKey, url, preset, namespace } = props;
   const navigate = useNavigate();
   const integrationPlugins = useIntegrationPlugins();

packages/react/src/pages/integration-detail.tsx

@@ -33,6 +33,7 @@ import { usePolicyActions } from "../hooks/use-policy-actions";
 import { useIntegrationPlugins, type IntegrationAccountHandoff } from "@executor-js/sdk/client";
 import { Button } from "../components/button";
 import { Skeleton } from "../components/skeleton";
+import { useExecutorDocumentTitle } from "../lib/document-title";
 
 // v2: the route's `namespace` param is the integration slug. Tools belong to
 // the integration's per-owner connections; a tool's policy id is
@@ -97,6 +98,7 @@ export function IntegrationDetailPage(props: { namespace: string }) {
   }, [namespace]);
 
   const integrationData = AsyncResult.isSuccess(integration) ? integration.value : null;
+  useExecutorDocumentTitle(integrationData?.name || namespace);
   const isBuiltInIntegration = namespace === "executor" || integrationData?.kind === "built-in";
   const currentTab = isBuiltInIntegration ? "tools" : activeTab;
   const canRefresh = integrationData?.canRefresh ?? false;

packages/react/src/pages/integrations.tsx

@@ -40,6 +40,7 @@ import {
 } from "../components/integration-favicon";
 import { IntegrationIconWithAccount } from "../components/integration-icon-with-account";
 import { Skeleton } from "../components/skeleton";
+import { useExecutorDocumentTitle } from "../lib/document-title";
 
 const KIND_TO_PLUGIN_KEY: Record<string, string> = {
   openapi: "openapi",
@@ -64,6 +65,7 @@ const bestDetection = (
 // ---------------------------------------------------------------------------
 
 export function IntegrationsPage() {
+  useExecutorDocumentTitle("Integrations");
   const integrations = useAtomValue(integrationsOptimisticAtom);
   const [connectOpen, setConnectOpen] = useState(false);