create-vitnode-app 0.0.1-canary.0

package/copy-of-vitnode-app/root/src/routes/_admin/admin.core.index.tsx

@@ -0,0 +1,70 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { AdminBreadcrumb } from "@vitnode/core/tanstack/admin";
+import {
+  AdminDashboardRouteContent,
+  loadAdminDashboardRoute,
+} from "@vitnode/core/tanstack/admin/dashboard";
+
+/**
+ * `/admin/core` - the AdminCP dashboard, and the one route file `_admin` keeps.
+ *
+ * Topology only. The layout query, the widget catalogue, the drag-and-drop
+ * board, the settings dialogs and the four mutations behind them are
+ * `@vitnode/core/tanstack/admin/dashboard`.
+ *
+ * ## Why this one file is still here
+ *
+ * Every other AdminCP screen is `@vitnode/core`'s, mounted by
+ * `withCoreAdminRoutes` as a code-based route - see `src/router.tsx`. This one
+ * stays because the file-based generator requires it to, and the requirement is
+ * sharp rather than stylistic:
+ *
+ * - A pathless layout with no file children is **dropped from the generated
+ *   tree**. `buildRouteTreeConfig` skips it outright, so `_admin` would not be
+ *   in `routeTree.gen.ts` at all and the route object `src/router.tsx` mounts
+ *   core's screens under would be an orphan.
+ * - It also collapses to a full path of `/`, which collides with `_main/index.tsx`
+ *   and fails the generator's uniqueness check by name.
+ *
+ * So `_admin` needs one file-based child with a real path in order to exist, and
+ * this is it - which is the same job it has always had. It was the shell's first
+ * child for exactly this reason, and now it is the only one.
+ *
+ * Deleting it does not remove a screen; it removes the AdminCP.
+ *
+ * ## No `head`, deliberately
+ *
+ * The Next.js page exports no `generateMetadata`, so the tab keeps the site's
+ * own name. Declaring `title: 'VitNode'` here would render "VitNode - VitNode"
+ * through `formatPageTitle`; saying nothing inherits the root's title and
+ * `_admin`'s `noindex`, which is the parity-preserving answer.
+ *
+ * ## `pluginWidgets` is not passed
+ *
+ * A plugin's dashboard widgets reach the Next.js board through
+ * `getVitNodeConfig()`, which is server-side config kept out of this app's
+ * browser bundle by `vitnode.shell.config.ts` - and this app registers its
+ * plugins by id and messages only (see `src/vitnode.config.ts`). So the board
+ * shows core's own widgets, which is the complete set for this install. It is
+ * the same seam `AdminShell` leaves open for nav `declarations`, and it changes
+ * here when plugin AdminCP registration moves over.
+ */
+export const Route = createFileRoute("/_admin/admin/core/")({
+  loader: async ({ context }) => await loadAdminDashboardRoute(context),
+  component: AdminDashboardRoute,
+  /**
+   * The whole of how an admin route contributes to the trail in the shell's
+   * header: the route declares its own crumb next to its own component, the
+   * shell renders whichever matched route declared the deepest one, and there is
+   * no map from pathname to breadcrumb anywhere. The label comes from the
+   * *visible* navigation, so this reads "Core" in whatever language the
+   * administrator is using without this file naming a string.
+   */
+  staticData: {
+    breadcrumb: <AdminBreadcrumb segments={["core"]} />,
+  },
+});
+
+function AdminDashboardRoute() {
+  return <AdminDashboardRouteContent {...Route.useLoaderData()} />;
+}

package/copy-of-vitnode-app/root/src/routes/_admin.tsx

@@ -0,0 +1,258 @@
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import {
+  ADMIN_ENTRY_PATH,
+  AdminNotFound,
+  adminReturnToFor,
+  canEnterAdmin,
+  ensureAdminAccess,
+  loadAdminMessages,
+  preloadAdminAccess,
+} from "@vitnode/core/tanstack/admin";
+import { ErrorActions } from "@vitnode/core/tanstack/layout";
+
+import { AdminShell } from "#/components/admin-shell";
+import { pageHead } from "#/lib/page-head";
+
+/**
+ * The boundary every AdminCP page sits under - the admin session guard, and the
+ * shell.
+ *
+ * Pathless: the leading underscore means it contributes no URL segment, so
+ * `routes/_admin/core/index.tsx` is `/admin/core`, guarded, and the guard is
+ * this file. A page joins the AdminCP by *where its file lives*, not by
+ * remembering to check a session.
+ *
+ * ## It is not under `_authenticated`, and must not be
+ *
+ * The AdminCP has its own session, under its own cookie (`vitnode_auth_admin`),
+ * with its own model and its own endpoint. Stacking the public guard above this
+ * one would bounce an administrator to `/login` for a session the AdminCP does
+ * not use - and `AuthState.isAdmin`, which lives on the *public* session, means
+ * "may be offered the AdminCP", not "is inside it". Two cookies, two questions.
+ *
+ * ## Exactly one splat may live under here, and nothing wider
+ *
+ * `admin.content.$.tsx` claims `/admin/content/*` - the Content Engine's own
+ * namespace, which Stage 13 moved into this router. That one is deliberate and
+ * narrow; a second is how the AdminCP breaks.
+ *
+ * `$.tsx`, `admin.$.tsx` or any other catch-all beside it would consume every
+ * *remaining* admin URL, including the ones no route declares. The AdminCP's own
+ * not-found would stop being reachable, a plugin's admin route would be shadowed
+ * by whichever splat sat above it, and nothing would report either - silently,
+ * and all at once. `src/tests/admin-routes.test.ts` pins both halves: that the
+ * content splat sits at exactly that path, and that it is the only one.
+ *
+ * ## Why the check is in `beforeLoad`
+ *
+ * It runs before the loader and long before React, so a visitor without admin
+ * access never receives a byte of an AdminCP page - not a flash, not a
+ * hydration, not a `useEffect` that redirects afterwards. A component-level
+ * check would render the page first and then take it away, which on the server
+ * means admin markup already written into the stream.
+ *
+ * ## A hover is not a navigation
+ *
+ * `defaultPreload: 'intent'` means the router runs this whole chain when a
+ * pointer rests on an admin link, and router-core has no staleness gate on
+ * `beforeLoad` the way it has on a loader - it re-runs it from the top of the
+ * branch every time. With `ADMIN_SESSION_STALE_TIME` at zero that made crossing
+ * the sidebar one server-function POST and one Hono call *per link the mouse
+ * passed over*, for a question nobody had asked yet.
+ *
+ * So the read is chosen by the `preload` flag the router already hands in.
+ * `preloadAdminAccess` is the same query, the same key and the same rejection
+ * behaviour, trusted for thirty seconds - the identical window the public
+ * session has always used for the identical reason. `ensureAdminAccess` and its
+ * `staleTime: 0` are untouched on the path that matters, and that is the whole
+ * of the revocation guarantee: entering a screen is a real navigation, this runs
+ * again with `preload: false`, and the API is asked. Router-core never lets a
+ * preloaded `beforeLoad` result stand in for a navigation's.
+ *
+ * The redirect below is deliberately *not* conditional on `preload`. It is not a
+ * navigation - `preloadClientRoute` catches it and preloads the sign-in page
+ * instead of moving anybody - and skipping it would leave a denied preload
+ * walking into the screen loaders underneath, which would then send admin
+ * requests the API is going to refuse.
+ *
+ * ## A failed read is not a denial
+ *
+ * `ensureAdminAccess` resolves only for an answer the API actually gave - `200`
+ * or `403`. A `429` from the rate limiter, a `500`, an API that is not listening:
+ * all three reject, and that rejection is deliberately left to propagate as an
+ * ordinary route error.
+ *
+ * Only `canEnterAdmin` answering `false` sends anybody to `/admin`. Catching the
+ * rejection and redirecting instead would sign every administrator out of the
+ * AdminCP during an outage and present them with a sign-in form for a session
+ * they already hold - which is precisely what the Next.js `getSessionAdminApi()`
+ * does today, and precisely what this shape exists to stop.
+ *
+ * ## What it is not
+ *
+ * A navigation guard, and only that. `api/config.ts` puts
+ * `globalAdminMiddleware()` in front of every request whose path contains
+ * `/admin/`, each handler re-checks the staff tables, and
+ * `SessionAdminModel.getUser()` re-runs `checkIfUserIsAdmin` against the
+ * database on every request - deleting the session the moment the answer turns
+ * false. So an administrator who edits this app's cached permission set in
+ * devtools gets a visible button and an API that still refuses them. Nothing
+ * here is, or may become, the security boundary.
+ */
+export const Route = createFileRoute("/_admin")({
+  beforeLoad: async ({ context, location, preload }) => {
+    const access = preload
+      ? await preloadAdminAccess(context.queryClient)
+      : await ensureAdminAccess(context.queryClient);
+
+    if (!canEnterAdmin(access)) {
+      // TanStack Router's own control-flow signal: `redirect()` returns a typed
+      // redirect object that the router catches and turns into a navigation
+      // (or, during SSR, a 302). Throwing it is what stops the guard.
+      //
+      // `/admin` is a sibling leaf, not a child of this route, so this cannot
+      // loop: the sign-in page's own guard only redirects *away* on a granted
+      // session, and `sanitizeAdminReturnTo` rejects `/admin` as a target.
+      //
+      // Cast because `/admin` is not in this router's type table: it is
+      // `@vitnode/core`'s code-based route now, mounted by `withCoreRootRoutes`,
+      // and code-based routes are outside the generated tree's types. The
+      // *runtime* is unaffected, and `ADMIN_ENTRY_PATH` is the package's own
+      // constant - so the path and the sign-in route that serves it are still one
+      // fact in one place.
+      // eslint-disable-next-line @typescript-eslint/only-throw-error
+      throw redirect({
+        search: { returnTo: adminReturnToFor(location) },
+        to: ADMIN_ENTRY_PATH,
+      } as unknown as Parameters<typeof redirect>[0]);
+    }
+
+    // Merged into the context of everything below, so a child route reads
+    // `context.adminAccess` already narrowed to the granted half of the union.
+    // It is the same object the guard decided on, from the same cache entry, so
+    // a page cannot disagree with the guard that let it render.
+    return { adminAccess: access };
+  },
+  /**
+   * The shell's strings, warmed before React renders.
+   *
+   * `adminNav.namespaces` is the same array `AdminShell` hands the shell, and it
+   * has to be: the provider reads back the identical `intlQueryOptions` entry
+   * this fills, so warming a different namespace set would fill an entry nobody
+   * looks at and cost a round trip on the first paint anyway. It is not a fixed
+   * list because it cannot be - a plugin group's headings live under that
+   * plugin's own id, and which plugins this installation configured is decided
+   * in `src/admin-nav.gen.ts`.
+   *
+   * ## Imported inside the loader, not above it
+   *
+   * A route file's `loader` body runs only for a navigation into this shell; the
+   * file itself is evaluated in the client entry, on every page of the site. The
+   * generated navigation is not small - it carries every configured plugin's
+   * sidebar icons and its content type definitions, and through those the whole
+   * Content Engine and `zod` - so a static import here put ~45 KB of AdminCP
+   * data, plus `zod`, in front of the front page's first paint. `AdminShell`
+   * imports the same module, and `AdminShell` is this route's `component`, which
+   * is code-split: the two land in the same chunk, so an administrator pays for
+   * it once and everybody else not at all.
+   */
+  loader: async ({ context }) => {
+    const { adminNav } = await import("#/lib/admin-nav");
+
+    await loadAdminMessages({ ...context, namespaces: adminNav.namespaces });
+  },
+  /**
+   * Stated once for the whole panel rather than on each screen.
+   *
+   * The AdminCP is behind a session and must never be indexed. Router merges the
+   * `head` of every matched route and dedupes `meta` by `name`, preferring the
+   * deepest, so an admin screen inherits this by saying nothing - which is
+   * exactly what `RouteHeadOptions` describes. A screen's own `pageHead` adds
+   * only its title and description.
+   */
+  head: () => pageHead({ robots: "noindex, nofollow" }),
+  /**
+   * The AdminCP's 404, rendered inside the shell.
+   *
+   * What reaches it is a screen whose loader called `requireAdminPermission`
+   * and was refused - the same answer `app/[locale]/admin/(auth)/not-found.tsx`
+   * gives in the Next.js AdminCP. Declared here rather than per screen so every
+   * one of them answers a missing permission identically.
+   *
+   * A content URL that resolves to no content type reaches it too, and by the
+   * same route: `loadContentAdminRoute` throws `notFound()` for a splat its
+   * registry cannot name, which is the answer the Next.js catch-all's
+   * `notFound()` gives one navigation later.
+   *
+   * A URL under `/admin` that matches no route at all does *not* reach this one.
+   * Outside `/admin/content`, `_admin` has only declared children - see above -
+   * so such a path matches nothing in this subtree and the router falls back to
+   * its own not-found at the root. That is the correct trade, and the cost is
+   * paid deliberately: rendering an unmigrated admin URL inside this shell would
+   * mean claiming it. (The root has no `notFoundComponent` of its own yet, so
+   * that fallback is currently the router's bare one - for every unmatched URL
+   * in this application, not only admin ones. Giving the root a real 404 page is
+   * its own piece of work.)
+   */
+  notFoundComponent: AdminNotFoundScreen,
+  component: AdminLayout,
+});
+
+/**
+ * The refusal, wearing the panel it was refused inside.
+ *
+ * ## It mounts the shell itself, and has to
+ *
+ * A `notFoundComponent` renders *instead of* the component of the route that
+ * handles the error, not inside it - so this replaces `AdminLayout`, sidebar
+ * and header and palette included. An administrator who opened a screen they
+ * lack the permission for would otherwise be dropped onto a bare 404 page with
+ * no way back into the AdminCP but the browser's back button, which is not what
+ * the Next.js AdminCP does: its `not-found.tsx` sits *under*
+ * `admin/(auth)/layout.tsx` and keeps the panel around the message.
+ *
+ * Mounting `AdminShell` here restores that, and it costs nothing: `beforeLoad`
+ * has already resolved the admin session and the loader above has already
+ * warmed the shell's messages, so the providers inside read the same two cache
+ * entries the working screens read and nothing suspends or fetches again.
+ *
+ * ## What is bound rather than defaulted
+ *
+ * `ErrorActions` is this app's binding rather than core's default: `/` is served
+ * by the Next.js application on some installs and by this one on others, and
+ * only the route tree knows which. It is passed as an element from module scope
+ * so the type is stable across renders.
+ */
+function AdminNotFoundScreen() {
+  return (
+    <AdminShell>
+      <AdminNotFound actions={<ErrorActions />} />
+    </AdminShell>
+  );
+}
+
+/**
+ * The AdminCP shell.
+ *
+ * `AdminShell` is this app's binding of `AdminShellContent` - the sidebar, the
+ * command palette, the breadcrumb area, the user menu and the one `<main>` every
+ * admin page renders inside. It mounts `AdminPermissionsProvider` itself, from
+ * the same admin session query the guard above has already filled, so
+ * `AdminStaffPermissionGate` and `useAdminStaffPermission` work identically here
+ * and in the Next.js AdminCP. It cannot suspend in practice and nothing below it
+ * can suspend at all; see the note on the provider.
+ *
+ * What `#/components/admin-shell` adds on top is only what a package cannot
+ * answer for a particular installation: where the user lookup runs, which
+ * plugins this app configured, and how the command palette moves without a link.
+ *
+ * The guard, the loader and the route options above are the parts that must not
+ * move.
+ */
+function AdminLayout() {
+  return (
+    <AdminShell>
+      <Outlet />
+    </AdminShell>
+  );
+}

package/copy-of-vitnode-app/root/src/routes/_main/index.tsx

@@ -0,0 +1,60 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { pageHead } from "#/lib/page-head";
+
+/**
+ * The front page.
+ *
+ * One route file serving every public URL of the home page: `/` and `/pl` both
+ * match here, because the locale is stripped before matching and written back
+ * into every link the router builds. There is no `routes/pl/index.tsx` and there
+ * does not need to be one.
+ *
+ * **`head` must be written after `loader`** on routes that have one -
+ * `loaderData` is inferred from `loader` in the same object literal, and
+ * TypeScript reads a literal's members in order. This route has no loader: it
+ * fetches nothing, and the shell above it already warmed everything the header
+ * reads.
+ *
+ * `robots: 'index, follow'` is stated rather than assumed. `_main` says nothing
+ * about indexing, and a page that wants to be found should say so where somebody
+ * editing it will see it.
+ */
+export const Route = createFileRoute("/_main/")({
+  head: () =>
+    pageHead({
+      description: "A VitNode application.",
+      robots: "index, follow",
+      title: "Home",
+    }),
+  component: HomeRoute,
+});
+
+/**
+ * Replace this with your own home page.
+ *
+ * No `<main>`: the shell owns the document's one `main` landmark, and a page
+ * that renders a second gives a screen reader two to choose between. A page owns
+ * its container - width, padding, vertical rhythm - and nothing above it.
+ *
+ * The copy is hard-coded because a new app has no strings of its own yet. To
+ * translate it, add the keys to `src/locales/` and read them with
+ * `useTranslations` from `use-intl` - the same hook every VitNode component
+ * uses, on every host.
+ */
+function HomeRoute() {
+  return (
+    <div className="container mx-auto flex max-w-2xl flex-col gap-4 p-4">
+      <h1 className="text-3xl font-semibold tracking-tight text-balance">
+        Welcome to VitNode
+      </h1>
+
+      <p className="text-muted-foreground leading-relaxed text-pretty">
+        Edit <code>src/routes/_main/index.tsx</code> to change this page. The
+        header, the footer and the shell around it are{" "}
+        <code>@vitnode/core</code>&rsquo;s; everything under{" "}
+        <code>src/routes</code> is yours.
+      </p>
+    </div>
+  );
+}

package/copy-of-vitnode-app/root/src/routes/_main.tsx

@@ -0,0 +1,64 @@
+import { createFileRoute, Outlet } from "@tanstack/react-router";
+import { MainBreadcrumb } from "@vitnode/core/tanstack/breadcrumb";
+import {
+  loadMainShell,
+  ThemeLayoutContent,
+} from "@vitnode/core/tanstack/layout";
+
+import { MainHeader } from "#/components/main-header";
+
+/**
+ * The main application shell - the header, the breadcrumb area and the one
+ * `<main>` landmark that every public page renders inside.
+ *
+ * Pathless, so it contributes no URL segment: `/discover` is `/discover`, not
+ * `/_main/discover`. A page joins the shell by *where its file lives*, which is
+ * the same rule `_authenticated` uses for the session guard - and the reason
+ * `_authenticated` lives underneath this one: a signed-in page is still a page
+ * on the public site, so it wants the shell *and* the guard rather than a second
+ * copy of the shell.
+ *
+ * ## What is deliberately outside it
+ *
+ * The four auth screens: `/login`, `/login/sso/$providerId`, `/register` and
+ * `/login/reset-password`. An auth screen is a full-height card on an otherwise
+ * empty document, and the header it would render is a header whose only
+ * interesting control is "sign in". Keeping them out is what makes this a shell
+ * that routes opt into rather than one every route is subject to.
+ * `routes/api/$` is outside for a different reason: it is a server route and
+ * renders no document at all. Note this is a visual difference from the Next.js
+ * app, where all four sit inside `(main)` and do render the header.
+ *
+ * `src/tests/main-shell.test.ts` asserts both halves - the settings paths
+ * inside, the four auth screens outside.
+ *
+ * ## The slots
+ *
+ * `ThemeLayoutContent`'s, and two of the same three the Next.js `ThemeLayout`
+ * fills: `header` and `breadcrumb`.
+ *
+ * `listeners` is deliberately left empty here. The Next.js app puts the
+ * notification toasts and the WebSocket's sign-in resync in it because its
+ * `/login` is inside the main shell; this app's is not, so a sync mounted here
+ * would not exist during the sign-in it has to notice. They are mounted by
+ * `__root` instead, next to the connection whose lifetime they share.
+ *
+ * ## What it is not
+ *
+ * A provider. Every technical provider this app has - the QueryClient, the two
+ * intl records, the theme, the WebSocket - is mounted once by `__root`, above
+ * every route, because a login screen needs them just as much as a page under
+ * this shell does. What lives here is structure: markup, and where the slots go.
+ */
+export const Route = createFileRoute("/_main")({
+  loader: async ({ context }) => await loadMainShell(context),
+  component: MainLayout,
+});
+
+function MainLayout() {
+  return (
+    <ThemeLayoutContent breadcrumb={<MainBreadcrumb />} header={<MainHeader />}>
+      <Outlet />
+    </ThemeLayoutContent>
+  );
+}

package/copy-of-vitnode-app/root/src/server/messages.server.ts

@@ -0,0 +1,29 @@
+import "@tanstack/react-start/server-only";
+import { createIntlMessagesLoader } from "@vitnode/core/tanstack/i18n/server";
+
+import { packageMessages } from "#/locales/packages";
+import { vitNodeConfig } from "#/vitnode.config";
+
+export type { IntlMessages } from "@vitnode/core/tanstack/i18n/server";
+
+/**
+ * The messages one page needs, in one language - this app's loader.
+ *
+ * Everything about *how* messages load is core's: the source order (core, then
+ * each plugin, then this app's overrides, later ones winning), the `web` scope
+ * stamped on each so the API's tree in this same process cannot be served in its
+ * place, the per-key fallback to the default locale, and the namespace pick that
+ * keeps every plugin's AdminCP copy out of a page that renders none of it.
+ *
+ * What is this app's, and can only be: the plugins it registered, the languages
+ * it declares, and `packageMessages` - the static loaders that stand in for each
+ * package's own locale barrel, because a barrel's
+ * `import("./en.json", { with: { type: "json" } })` is a specifier Rollup will
+ * not follow. See `src/locales/packages.ts` for the reproduction.
+ */
+export const loadIntlMessages = createIntlMessagesLoader({
+  appMessages: vitNodeConfig.i18n.messages,
+  defaultLocale: vitNodeConfig.i18n.defaultLocale,
+  packageMessages,
+  plugins: vitNodeConfig.plugins,
+});

package/copy-of-vitnode-app/root/src/start.ts

@@ -0,0 +1,88 @@
+import {
+  createCsrfMiddleware,
+  createMiddleware,
+  createStart,
+} from "@tanstack/react-start";
+import { handleLocaleRequest } from "@vitnode/core/tanstack/i18n/server";
+
+import {
+  applyDocumentCacheControl,
+  applyRedirectCacheControl,
+} from "#/lib/document-headers";
+import { localeRouting } from "#/lib/i18n/runtime";
+
+/**
+ * Locale routing, as the first thing that happens to a request.
+ *
+ * A global request middleware rather than a wrapper around the server entry:
+ * Start runs these before route matching and before SSR, which is exactly where
+ * a canonical redirect belongs - the alternative is rendering a page and then
+ * throwing it away.
+ *
+ * `handlerType` narrows it to page requests. Server function calls arrive on
+ * `/_serverFn/*` with `handlerType: "serverFn"`, and redirecting an RPC to a
+ * canonical URL would break it rather than tidy it.
+ *
+ * `/api/*` reaches here too and is deliberately ignored by
+ * `handleLocaleRequest`, so the Stage 1 Hono bridge sees the request exactly as
+ * the client sent it.
+ *
+ * `localeRouting` is handed in rather than read from the package's registered
+ * runtime: Start runs request middleware before route matching, so this is the
+ * one caller that cannot assume the router entry has been evaluated. Importing
+ * it from `#/lib/i18n/runtime` is also what guarantees this app's i18n is
+ * configured before the first request touches it.
+ *
+ * ## And what a document is allowed to say about itself
+ *
+ * The cache directive rides along here for one reason: this is already the only
+ * place in the application that holds every page response, before and after
+ * rendering, and a second middleware would be a second thing to remember. Every
+ * document this app produces carries a dehydrated Query cache containing the
+ * visitor's own session - and, under `/admin`, an administrator's whole
+ * permission set - so none of them may be stored by a shared cache. See
+ * `#/lib/document-headers`, which owns the rule and says why; this file only
+ * applies it.
+ */
+const localeMiddleware = createMiddleware().server(
+  async ({ handlerType, next, request }) => {
+    if (handlerType !== "router") return await next();
+
+    const { redirect, setCookie } = handleLocaleRequest(request, localeRouting);
+    if (redirect) {
+      applyRedirectCacheControl(redirect);
+
+      return redirect;
+    }
+
+    const result = await next();
+
+    // `append`, not `set`: the API mounted at `/api/*` and the auth flow both
+    // mint their own cookies, and overwriting the header would sign people out.
+    if (setCookie) result.response.headers.append("set-cookie", setCookie);
+
+    // After the cookie, so a document that just wrote one is covered by the
+    // same directive as one that did not. Only an HTML response is touched -
+    // `/api/*` reaches here too, and the API's own caching is not this
+    // middleware's to decide.
+    applyDocumentCacheControl(result.response);
+
+    return result;
+  },
+);
+
+/**
+ * This app's Start instance.
+ *
+ * `createCsrfMiddleware` is not optional here. Start installs it *only* while an
+ * app declares no `requestMiddleware` of its own - the moment this file exists,
+ * the default is replaced by whatever it lists, and leaving CSRF out would
+ * expose every server function as an unauthenticated cross-site endpoint. It is
+ * declared first so it runs before anything else.
+ */
+export const startInstance = createStart(() => ({
+  requestMiddleware: [
+    createCsrfMiddleware({ filter: ctx => ctx.handlerType === "serverFn" }),
+    localeMiddleware,
+  ],
+}));