create-vitnode-app 0.0.1-canary.0

package/copy-of-vitnode-app/root/src/lib/i18n/runtime.ts

@@ -0,0 +1,75 @@
+import { createServerFn } from "@tanstack/react-start";
+import { configureIntl, validateIntlInput } from "@vitnode/core/tanstack/i18n";
+import { IntlProvider } from "use-intl";
+
+import { i18n } from "#/i18n";
+import { loadIntlMessages } from "#/server/messages.server";
+
+/**
+ * One language's messages for one set of namespaces, fetched on the server.
+ *
+ * The one piece of the i18n runtime that cannot live in `@vitnode/core`, and the
+ * reason is the compiler rather than the code. A server function has to be
+ * transformed by the Start plugin in *both* bundles; the package is externalised
+ * from this app's SSR pass, so its modules reach the server un-compiled and a
+ * `createServerFn` declared there resolves to `undefined` during SSR with no
+ * error. See `packages/vitnode/src/tanstack/boundary.test.ts`.
+ *
+ * So the wrapper is here and the body is not: `validateIntlInput` is core's, and
+ * `loadIntlMessages` delegates to core's loading engine. Start strips the
+ * handler - and `#/server/messages.server` with it - out of the client build.
+ */
+export const getIntlMessages = createServerFn()
+  .validator(validateIntlInput)
+  .handler(async ({ data }) => await loadIntlMessages(data));
+
+/**
+ * This app's languages, handed to the package once.
+ *
+ * Everything in `@vitnode/core/tanstack/i18n` reads what this registers, so a
+ * route file imports `RouteMessages` and `intlQueryOptions` straight from the
+ * package. What must not happen is a route running before this module has been
+ * evaluated - so the two framework entry points, `src/router.tsx` and
+ * `src/start.ts`, both import from here, and `src/tests/intl-runtime.test.ts`
+ * fails if either stops doing so.
+ *
+ * The registration is at module scope but reads `getIntlMessages` above only by
+ * reference, so the order within this file does not matter: the validator and
+ * the fetcher are both called per request, long after it has finished
+ * evaluating.
+ */
+export const {
+  defaultLocale,
+  isLocale: isSupportedLocale,
+  localeRouting,
+} = configureIntl({
+  fetchMessages: async input => await getIntlMessages({ data: input }),
+  /**
+   * This app's own `use-intl`, handed over so `RouteMessages` can provide it.
+   *
+   * `@vitnode/core` is external to this app's SSR pass (`vite.config.ts`), so
+   * under `vite dev` Node loads the package and Vite loads this app, and the two
+   * resolve `use-intl` to two different files - two `createContext` calls, two
+   * React contexts. Everything the package renders reads its own; anything this
+   * app renders with its own `useTranslations` - `routes/_main/index.tsx` does -
+   * reads this one, and nothing inside the package can import it.
+   *
+   * So it is registered rather than imported, and `RouteMessages` mounts it
+   * outermost. A production build resolves `use-intl` once and the providers
+   * collapse into one, which is why leaving this out is a dev-only failure: the
+   * route's server render throws "No intl context found", React quietly falls
+   * back to client rendering, and the page still appears.
+   */
+  hostIntlProvider: IntlProvider,
+  i18n,
+});
+
+/**
+ * The router's half of locale routing, bound to this app's languages.
+ *
+ * Re-exported from here rather than imported straight from the package by
+ * `src/router.tsx`: it is the router entry's only i18n import, and routing it
+ * through this module is what makes `configureIntl` above run before the router
+ * - and therefore before any route, loader or component - exists.
+ */
+export { createLocaleRewrite } from "@vitnode/core/tanstack/i18n";

package/copy-of-vitnode-app/root/src/lib/i18n/shared.ts

@@ -0,0 +1,20 @@
+import type { i18n } from "#/i18n";
+
+import { localeRouting } from "#/lib/i18n/runtime";
+
+/**
+ * A language this app serves, as a type. `"en" | "pl"`, derived from the config
+ * rather than written twice.
+ *
+ * The one i18n thing this app still owns, and it has to: `@vitnode/core` is
+ * installed by apps with different language lists, so it types a locale as
+ * `string` and takes this union as a type argument where the value originates
+ * (`useLocale<Locale>()`, `resolveLocale<Locale>()`).
+ */
+export type Locale = (typeof i18n.locales)[number]["code"];
+
+export { defaultLocale, localeRouting } from "#/lib/i18n/runtime";
+
+/** Narrows a string - a URL segment, a cookie, a `<select>` value - to a locale. */
+export const isLocale = (value: null | string | undefined): value is Locale =>
+  localeRouting.isSupportedLocale(value);

package/copy-of-vitnode-app/root/src/lib/navigation.ts

@@ -0,0 +1,24 @@
+import { createAuthNavigation } from "@vitnode/core/tanstack/auth";
+
+import { localeRouting } from "#/lib/i18n/shared";
+
+/**
+ * Going somewhere in this application from code, bound to this app's languages.
+ *
+ * One line of application, and everything else is
+ * `@vitnode/core/tanstack/auth`: the two questions a user-supplied target has to
+ * answer (may we send a browser there, and what does the router want to be
+ * handed), the reason a redirect carries `to` rather than `href`, and the fact
+ * that the same decision is made on a server and in a browser.
+ *
+ * What is left here is the only thing a package cannot answer - which languages
+ * this installation serves, which is what decides whether `/pl/discover` is a
+ * Polish page or a route called `pl`.
+ *
+ * `@vitnode/core/tanstack/routes` builds its own from the same factory, handed
+ * the same `localeRouting`, so core's auth screens and this app's AdminCP command
+ * palette navigate by one rule rather than two.
+ */
+export const { internalDestination, useAppNavigate } = createAuthNavigation({
+  localeRouting,
+});

package/copy-of-vitnode-app/root/src/lib/page-head.ts

@@ -0,0 +1,19 @@
+import { createRouteHead } from "@vitnode/core/tanstack/metadata";
+
+import { vitNodeShellConfig } from "#/vitnode.shell.config";
+
+/**
+ * A route's `head`, bound to this app's name.
+ *
+ * Two lines of application, and everything else is
+ * `@vitnode/core/tanstack/metadata`: the `"<page> - <site>"` title rule Next.js
+ * applies through `title.template`, the decision that a robots directive is
+ * stated rather than assumed, and the handling of a `loaderData` that is
+ * `undefined` on a route's first pass.
+ *
+ * What is left here is the only thing a package cannot answer - this site's own
+ * name, which is what every tab title ends with.
+ *
+ *     head: ({ loaderData }) => pageHead({ robots: 'index, follow', ...loaderData })
+ */
+export const pageHead = createRouteHead(vitNodeShellConfig.metadata);

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

@@ -0,0 +1,28 @@
+import type { AppMessagesMap } from "@vitnode/core/lib/i18n/types";
+
+/**
+ * Translations this app owns, on top of whatever the packages ship.
+ *
+ * Empty, and usually stays that way. Every VitNode package ships its own
+ * translations and `locales/packages.ts` is what registers them - carrying a
+ * second copy of a string a package already owns is how one product comes to
+ * spell the same settings tab two different ways.
+ *
+ * What belongs here is a string this app *changes*. Add a locale, then the key
+ * you are rewording:
+ *
+ *     export const appMessages: AppMessagesMap = {
+ *       en: {
+ *         '@vitnode/core': async () => await import('./en.json'),
+ *       },
+ *     }
+ *
+ * Deep-merged last, so a file here only needs the keys it actually changes:
+ * everything it leaves out falls back to the package's, and then to the default
+ * locale, key by key.
+ *
+ * Server-side only, and kept out of `src/i18n.ts` on purpose: these are
+ * functions, and `src/i18n.ts` is spread into the shell config, which crosses to
+ * the browser and has to stay serializable.
+ */
+export const appMessages: AppMessagesMap = {};

package/copy-of-vitnode-app/root/src/locales/packages.ts

@@ -0,0 +1,43 @@
+import type { LocaleMessagesMap } from "@vitnode/core/lib/i18n/types";
+
+import { CONFIG_PLUGIN as CORE } from "@vitnode/core/config";
+
+/**
+ * Where this app reads each installed package's translations from.
+ *
+ * Every VitNode package ships a locale barrel - `@vitnode/core/locales/index` -
+ * that loads its own files with a runtime
+ * `import("./en.json", { with: { type: "json" } })`. Under Node that is exactly
+ * right, and it is how an API app reads them.
+ *
+ * It cannot work here, and the reason is the import attribute rather than
+ * anything about VitNode. Vite and Nitro inline `@vitnode/core`'s build output
+ * into this app's server chunks - `ssr.external` applies to the SSR pass, not to
+ * Nitro's own bundling - but Rollup will not follow a dynamic import that
+ * carries `with: { type: "json" }`, so it neither emits the JSON nor rewrites
+ * the specifier. What ships is a relative import pointing next to a chunk that
+ * the JSON was never copied to, and every string on the page renders as its own
+ * key.
+ *
+ * So the loaders are declared here instead, with static specifiers a bundler can
+ * follow. Each resolves through the package's `./locales/*.json` export to the
+ * real file and lands in the build as a chunk fetched on demand, which is the
+ * same laziness the barrels wanted.
+ *
+ * **Add a line here for every plugin you install.** A plugin registered in
+ * `vitnode.config.ts` with no entry in this map renders its own strings as keys:
+ *
+ *     import { CONFIG_PLUGIN as BLOG } from '@acme/blog/const'
+ *
+ *     [BLOG.pluginId]: {
+ *       en: async () => await import('@acme/blog/locales/en.json'),
+ *     },
+ *
+ * This is the app's *only* copy of that list - `vitnode.config.ts` and
+ * `server/messages.server.ts` both read it from here.
+ */
+export const packageMessages: Record<string, LocaleMessagesMap> = {
+  [CORE.pluginId]: {
+    en: async () => await import("@vitnode/core/locales/en.json"),
+  },
+};

package/copy-of-vitnode-app/root/src/router.tsx

@@ -0,0 +1,227 @@
+import type { AnyRouter } from "@tanstack/react-router";
+
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { createVitNodeQueryClient } from "@vitnode/core/lib/query-client";
+import { RoutePendingSpinner } from "@vitnode/core/tanstack/pending";
+import {
+  pluginRouteSpecs,
+  withPluginRoutes,
+} from "@vitnode/core/tanstack/plugin-routes";
+import {
+  withCoreAdminRoutes,
+  withCoreMainRoutes,
+  withCoreRootRoutes,
+} from "@vitnode/core/tanstack/routes";
+
+/**
+ * The auth transport, registered by importing the module that declares it.
+ *
+ * `@vitnode/core/tanstack/auth` owns every auth decision this app makes but may
+ * not declare a `createServerFn` - uncompiled on the server, one silently
+ * resolves to `undefined` - so `lib/auth.ts` declares the eight wrappers and
+ * hands them over at module scope. A bare import because there is nothing to
+ * name: the registration *is* the module's effect.
+ *
+ * Here because a router is the one module both entry points load, so the
+ * registration has happened before any route, loader or component can reach for
+ * it, in the browser bundle and on the server alike.
+ */
+import "./lib/auth";
+/**
+ * The admin transport, registered the same way and for the same reason.
+ *
+ * One server function rather than eight, reading the AdminCP's own session under
+ * its own cookie. It is a separate registration from the auth one on purpose:
+ * they are two sessions, two cookies and two cache entries, and nothing in
+ * VitNode may let the public session answer an admin question.
+ */
+import "./lib/admin-auth";
+import { createLocaleRewrite, localeRouting } from "./lib/i18n/runtime";
+import { pageHead } from "./lib/page-head";
+import { pluginRouteSources } from "./plugin-routes.gen";
+import { Route as adminShellRoute } from "./routes/_admin";
+import { Route as mainShellRoute } from "./routes/_main";
+import { routeTree as fileRouteTree } from "./routeTree.gen";
+
+/**
+ * The Content Engine registry, behind a literal dynamic import.
+ *
+ * Awaited by the one loader that needs it - `/admin/content/*` - rather than
+ * imported here. Building the registry reaches `@vitnode/core/content` and
+ * every configured plugin's admin form components, and this module is the one
+ * the client entry evaluates on every page: as a static import it put `zod`,
+ * every plugin's content registrations, the content form primitives and
+ * `react-hook-form` in front of the front page's first paint. See
+ * `CoreAdminRouteContext.loadContentRegistry`.
+ */
+const loadContentRegistry = async () =>
+  (await import("./lib/content-registry")).contentRegistry;
+
+/**
+ * One route tree: this app's route files, plus the AdminCP screens `@vitnode/core`
+ * owns, plus the pages its plugins declare.
+ *
+ * At module scope rather than inside `getRouter`, because `getRouter` runs once
+ * per server request and mounting the plugin routes mutates the route tree - the
+ * generated tree is a module singleton. `withPluginRoutes` is idempotent anyway;
+ * doing it once is simply where it belongs.
+ *
+ * The plugin half comes from one generated file: a static import of each
+ * configured plugin's own route tree. No plugin page is copied into
+ * `src/routes`, no route path is written by hand, and nothing here knows which
+ * plugins are installed - see `@vitnode/core/tanstack/plugin-routes`.
+ *
+ * A page is reached only through the literal `lazy(() => import(...))` its route
+ * declared, so every one of them is a chunk of its own. The one part of a plugin
+ * route that is not lazy is a `search` schema: a router's `validateSearch` runs
+ * during path matching, before any chunk is fetched, so it lives in the tree
+ * rather than in the page.
+ *
+ * `mountUnder` names one route per shell, which is the whole of what "a plugin
+ * route renders in the application shell" amounts to here. A plugin declares
+ * `area: "main"` or `area: "admin"`; `_main` is the route that renders the
+ * public shell and `_admin` the one that renders the AdminCP, and being a child
+ * of one of them is what gives `/example` the header and the one `<main>` that
+ * `/discover` has, or gives `/admin/reports` the sidebar, the breadcrumb area
+ * and the admin session guard that `/admin/core` has. No new field, no per-route
+ * layout metadata and no second copy of either shell - route composition, which
+ * the area declaration already described.
+ *
+ * Neither shell changes a path: both are pathless, so `/example` stays
+ * `/example` and an admin plugin route's `/admin/…` is the path its own route
+ * spells out in full. An area VitNode knows and this app has not named here
+ * fails the composition rather than being mounted under the other one.
+ *
+ * `_main` and `_admin` are imported for their route objects, and they are the
+ * same objects the generated tree holds: `createFileRoute` produces one instance
+ * per module and `routeTree.gen.ts` mutates it in place.
+ *
+ * `withCoreMainRoutes`, `withCoreAdminRoutes` and `withCoreRootRoutes` mount
+ * core's own screens the same way, one per mount point: the public pages under
+ * the main shell, the AdminCP's under its own, and the shell-less ones - the auth
+ * cards and the AdminCP sign-in - straight under the root.
+ *
+ * They were twenty-nine route files in this application until
+ * `@vitnode/core/tanstack/routes` existed, every one of them pure wiring around
+ * something imported from the package - so an app carried a copy of VitNode's own
+ * routing table and core adding a screen meant an edit here. They are code-based
+ * rather than declared as plugin routes because they need the router's full
+ * option set: a real `validateSearch` that clamps `?page=999` before anything
+ * renders, a `beforeLoad` guard that runs before any chunk is fetched, and a
+ * splat path a plugin route path does not represent.
+ *
+ * `localeRouting` goes to the last of the three because a sign-in navigates to a
+ * path a *visitor* supplied: the route tree carries no locale, so the prefix has
+ * to be stripped before the router sees it, and which prefixes exist is this
+ * app's answer. It is the same object the `rewrite` below uses.
+ *
+ * `pageHead` is this app's own `createRouteHead(metadata)` binding, handed over
+ * because a package cannot know the site's name: a plugin page's `<title>` goes
+ * through the same `"<page> - <site>"` rule every other VitNode page's does,
+ * rather than through a second one the plugin invented.
+ */
+const routeTree = withCoreRootRoutes(
+  withCoreAdminRoutes(
+    withCoreMainRoutes(
+      withPluginRoutes(
+        fileRouteTree,
+        pluginRouteSpecs(pluginRouteSources),
+        {
+          mountUnder: { admin: adminShellRoute, main: mainShellRoute },
+          pageHead,
+        },
+      ),
+      { mountUnder: mainShellRoute, pageHead },
+    ),
+    { loadContentRegistry, mountUnder: adminShellRoute, pageHead },
+  ),
+  { localeRouting, mountUnder: fileRouteTree, pageHead },
+);
+
+/**
+ * The app's router, and the QueryClient it owns.
+ *
+ * Start calls this once per server request and once in the browser, which is
+ * exactly the lifetime a QueryClient should have: created here, it is per
+ * request on the server - never a module-level client shared by every visitor
+ * being rendered at once - and a single long-lived one on the client.
+ *
+ * It goes into the router context, so a route loader reaches it as
+ * `context.queryClient` and can `ensureQueryData` before its component renders.
+ * That is the whole point of putting it here rather than in a provider: a
+ * loader runs before React does, so a client mounted by a component would be
+ * out of reach of the code that most wants it.
+ *
+ * `setupRouterSsrQueryIntegration` wires the two together: it dehydrates the
+ * cache into the SSR stream (including queries that resolve mid-render),
+ * hydrates it on the client before the first render, routes `redirect()` thrown
+ * inside a query or mutation through the router, and wraps the app in the one
+ * `QueryClientProvider` for this client. Nothing else in this app may create a
+ * `QueryClient` or a provider for one - two clients in a page means a query a
+ * loader cached is invisible to the component that reads it.
+ *
+ * `defaultPreloadStaleTime: 0` leaves caching to Query rather than having the
+ * router keep a second copy of the same data with its own expiry.
+ *
+ * `defaultStaleReloadMode: 'blocking'` is what makes a route's pending shape
+ * reachable at all once preloading is on. Router core's default is
+ * `'background'`, and a background reload never opens a pending window - but it
+ * still waits for the route's component chunk before it commits. So the common
+ * desktop path, hover a link and click it, took the one branch that renders
+ * nothing: the hover filled the loader, the click was therefore a background
+ * reload, and the chunk downloaded with the previous page still on screen and
+ * no skeleton in sight.
+ *
+ * It costs nothing here because a VitNode loader does not block on a warm cache:
+ * `ensureQueryData` with `revalidateIfStale` hands back the cached entry and
+ * refreshes behind it, so "blocking" describes a promise that resolves in a
+ * microtask. What changes is only that the router now marks the match pending
+ * while that happens, which is what `defaultPendingMs` is for.
+ *
+ * `defaultPendingMs: 150` is that threshold, and it is not zero for the same
+ * reason. At zero, every navigation opens a pending window, so
+ * `defaultPendingMinMs` holds a *fully cached* navigation behind a skeleton for
+ * 300ms - a page that could have been instant, made slow to look busy. At 150ms
+ * a cached navigation goes straight through with nothing shown and a slow one
+ * still gets its shape, in the content area and the breadcrumb together.
+ *
+ * `rewrite` is what makes one route tree serve two public URL shapes: `/pl/...`
+ * arrives, `/...` is matched, and every link the router builds gets the prefix
+ * back. No route file mentions a locale, so nothing here has to be duplicated
+ * per language - see `@vitnode/core/tanstack/i18n`.
+ */
+export function getRouter() {
+  const queryClient = createVitNodeQueryClient();
+
+  // The rewrite reads the locale off the router's own current location, and the
+  // router needs the rewrite to parse that location - so it is handed a getter
+  // rather than the router itself. `output` only ever runs once a link is built,
+  // which is long after the assignment below.
+  const holder: { current?: AnyRouter } = {};
+
+  const router = createTanStackRouter({
+    context: { queryClient },
+    defaultPendingComponent: RoutePendingSpinner,
+    defaultPendingMs: 150,
+    defaultPendingMinMs: 300,
+    defaultPreload: "intent",
+    defaultPreloadStaleTime: 0,
+    defaultStaleReloadMode: "blocking",
+    rewrite: createLocaleRewrite(() => holder.current),
+    routeTree,
+    scrollRestoration: true,
+  });
+
+  holder.current = router;
+
+  setupRouterSsrQueryIntegration({ queryClient, router });
+
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}

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

@@ -0,0 +1,212 @@
+import type { QueryClient } from "@tanstack/react-query";
+
+import { TanStackDevtools } from "@tanstack/react-devtools";
+import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools";
+import { ThemeScript } from "@vitnode/core/components/theme-script";
+import {
+  intlQueryOptions,
+  publicPathnameOf,
+  resolveLocale,
+  useLocale,
+} from "@vitnode/core/tanstack/i18n";
+import {
+  ErrorActions,
+  NotFound,
+  VitNodeRootProviders,
+} from "@vitnode/core/tanstack/layout";
+
+import type { Locale } from "#/lib/i18n/shared";
+
+import { vitNodeShellConfig } from "#/vitnode.shell.config";
+
+import appCss from "../styles.css?url";
+
+const { debug, i18n, metadata, theme } = vitNodeShellConfig;
+
+/**
+ * What the router itself provides, before any route has run.
+ *
+ * The QueryClient, and nothing else. `beforeLoad` below adds `locale` on top, so
+ * what a loader actually receives is `{ queryClient, locale }` - the language
+ * included, because a loader that fetches anything user-facing needs to know
+ * which one it is fetching.
+ */
+export interface RootRouterContext {
+  queryClient: QueryClient;
+}
+
+export const Route = createRootRouteWithContext<RootRouterContext>()({
+  /**
+   * The request's language, resolved once and handed to every loader below.
+   *
+   * The same function the rewrite and the components use, so there is one answer
+   * per request rather than one per consumer. Note that a language switch does
+   * not change the *internal* URL - only the public one - so the switcher
+   * invalidates the router to bring this back in step.
+   */
+  beforeLoad: ({ location }) => ({
+    locale: resolveLocale<Locale>(publicPathnameOf(location)),
+  }),
+  component: RootComponent,
+  head: () => ({
+    links: [
+      { href: appCss, rel: "stylesheet" },
+      /*
+       * The tab icon, from `public/favicon.ico`.
+       *
+       * Stated rather than left to the browser's automatic `/favicon.ico`
+       * request, because that request is a 404 until the file exists and a
+       * silently missing icon is easy to never notice. Drop your own 32px `.ico`
+       * at `public/favicon.ico`; it lives there rather than being imported so
+       * that the URL is stable and the file is still reachable at the well-known
+       * path browsers ask for unprompted.
+       */
+      {
+        href: "/favicon.ico",
+        rel: "icon",
+        sizes: "32x32",
+        type: "image/x-icon",
+      },
+    ],
+    meta: [
+      { charSet: "utf-8" },
+      { content: "width=device-width, initial-scale=1", name: "viewport" },
+      // The default title, from the app's config. A route that names itself
+      // renders `"<page> - <shortTitle>"` instead, through `formatPageTitle` -
+      // the same rule Next.js applies through `title.template`.
+      { title: metadata.title },
+    ],
+  }),
+  /**
+   * Warm this language's shell strings before anything renders.
+   *
+   * `context.locale` rather than a default: `/pl` has to arrive with Polish
+   * already in the cache, or the first paint is English and the page flips after
+   * hydration.
+   */
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(
+      intlQueryOptions({ locale: context.locale }),
+    );
+  },
+  /**
+   * Every URL this application does not serve.
+   *
+   * The last resort, and until now there was none: a path that matched no route
+   * at all fell through to TanStack Router's own `<p>Not Found</p>` - no shell,
+   * no strings, no way back - and the router warned about the missing option on
+   * every such navigation. `/admin/contents` and a hand-typed `/blog/post-30`
+   * both landed there.
+   *
+   * ## What reaches it, and what does not
+   *
+   * Only a path **no route matched**. A route that matched and then answered
+   * `notFound()` from its own loader is caught by the nearest
+   * `notFoundComponent` above it, which is why `/admin/content/nope` and
+   * `/admin/content/blog/articles/999999/edit` render the AdminCP's 404 inside
+   * the panel rather than this - see `_admin`'s, which mounts the shell around
+   * the same message.
+   *
+   * ## It is a 404, and not a redirect anywhere
+   *
+   * The route tree is the whole application, so a URL that reaches here is one
+   * somebody typed or a stale bookmark, and saying so is the honest answer.
+   * Bouncing an unmatched path at some other origin would hide a genuinely
+   * missing page behind a hop to a server that 404s it anyway. Where a URL is
+   * served from is a deployment question, and a proxy in front of the app
+   * answers it better than this route can.
+   */
+  notFoundComponent: RootNotFound,
+  shellComponent: RootDocument,
+});
+
+/**
+ * Rendered inside `RootComponent`, which is what makes the strings work: the
+ * providers it mounts include `RouteMessages` with `core.global`, and that is
+ * the namespace `NotFound` reads its two lines from. The root's loader has
+ * already warmed that entry, so nothing suspends.
+ */
+function RootNotFound() {
+  return <NotFound actions={<ErrorActions />} />;
+}
+
+/**
+ * The VitNode provider tree, mounted once above every route.
+ *
+ * Every provider in it is shared with the Next.js app - the theme, the toaster,
+ * the tooltip provider, the WebSocket - plus the pair of `use-intl` records that
+ * only a package can name. `VitNodeRootProviders` owns all of it, including the
+ * argument for why the realtime listeners are inside it rather than in the main
+ * shell.
+ *
+ * What this route contributes is the two things an application owns: which
+ * languages it serves, and its theme defaults.
+ *
+ * Because the locale comes from router state, changing language re-renders this:
+ * new locale, new query key, new messages, no page reload.
+ */
+function RootComponent() {
+  return (
+    <VitNodeRootProviders config={{ debug, locales: i18n.locales, theme }}>
+      <Outlet />
+    </VitNodeRootProviders>
+  );
+}
+
+/**
+ * The document itself.
+ *
+ * `lang` is the language this request actually resolved to - `en` for `/`, `pl`
+ * for `/pl`, and on a route outside the localized URL space (`/admin`) whatever
+ * the visitor's cookie says. It comes from the same router state the provider
+ * reads, so the two cannot disagree and hydration has nothing to complain about.
+ *
+ * `ThemeScript` has to be in the head, and it has to be inline: it applies the
+ * stored theme to `<html>` before the browser paints, so the first frame is the
+ * theme the visitor chose rather than a flash of the default one.
+ * `suppressHydrationWarning` covers the attributes it writes, which by design
+ * differ from what the server rendered.
+ */
+function RootDocument({ children }: { children: React.ReactNode }) {
+  const locale = useLocale();
+
+  return (
+    <html lang={locale} suppressHydrationWarning>
+      <head>
+        <HeadContent />
+        <ThemeScript {...theme} />
+      </head>
+
+      <body suppressHydrationWarning>
+        {children}
+
+        {import.meta.env.DEV ? (
+          <TanStackDevtools
+            config={{
+              position: "bottom-right",
+            }}
+            plugins={[
+              {
+                name: "TanStack Router",
+                render: <TanStackRouterDevtoolsPanel />,
+              },
+              {
+                name: "TanStack Query",
+                render: <ReactQueryDevtoolsPanel />,
+              },
+            ]}
+          />
+        ) : null}
+
+        <Scripts />
+      </body>
+    </html>
+  );
+}