create-vitnode-app 0.0.1-canary.0

package/copy-of-vitnode-app/monorepo/turbo.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://turborepo.dev/schema.json",
+  "ui": "tui",
+  "tasks": {
+    "db:prepare": {
+      "cache": false,
+      "inputs": ["$TURBO_DEFAULT$", ".env*"],
+      "env": ["POSTGRES_URL"]
+    },
+    "db:migrate": {
+      "dependsOn": ["^db:migrate"],
+      "cache": false,
+      "inputs": ["$TURBO_DEFAULT$", ".env*"],
+      "env": ["POSTGRES_URL"]
+    },
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", ".env*"],
+      "outputs": [".output/**", "dist/**"],
+      "env": ["POSTGRES_URL", "NEXT_PUBLIC_API_URL", "NEXT_PUBLIC_WEB_URL"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", ".env*"],
+      "env": ["POSTGRES_URL", "NEXT_PUBLIC_API_URL", "NEXT_PUBLIC_WEB_URL"]
+    },
+    "start": {
+      "dependsOn": ["^start"]
+    },
+    "lint": {
+      "dependsOn": ["^lint"]
+    },
+    "lint:fix": {
+      "dependsOn": ["^lint:fix"]
+    },
+    "i18n:create": {
+      "dependsOn": ["^i18n:create"]
+    },
+    "i18n:check": {
+      "dependsOn": ["^i18n:check"]
+    },
+    "i18n:delete": {
+      "dependsOn": ["^i18n:delete"]
+    },
+    "i18n:update": {
+      "dependsOn": ["^i18n:update"]
+    },
+    "i18n:update:ai": {
+      "dependsOn": ["^i18n:update:ai"]
+    }
+  }
+}

package/copy-of-vitnode-app/root/.env.example

@@ -0,0 +1,22 @@
+POSTGRES_URL=postgresql://root:root@localhost:5432/vitnode
+REDIS_URL=redis://localhost:6379
+
+# Both name this app's own origin, and it has to be the port `dev` actually
+# serves. Neither is strictly required: on the server the API origin is taken
+# off the request being rendered, and in the browser it falls back to the origin
+# the page was served from - so a preview deployment on a generated hostname
+# needs no config at all. Set `NEXT_PUBLIC_API_URL` only to point at a separate
+# API server; `NEXT_PUBLIC_WEB_URL` is what the API stamps cookies with.
+NEXT_PUBLIC_WEB_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:3000
+
+# === CRON Secret for Internal API Calls ===
+CRON_SECRET=your-secure-cron-secret-key
+
+# === Docker Database Postgres ===
+POSTGRES_USER=root
+POSTGRES_PASSWORD=root
+POSTGRES_NAME=vitnode
+
+# === Docker Redis ===
+REDIS_PASSWORD=root

package/copy-of-vitnode-app/root/.gitignore_template

@@ -0,0 +1,41 @@
+# Dependencies
+node_modules
+
+# Turbo
+.turbo
+
+# Test & Build
+/coverage
+/.output/
+/.nitro/
+/.vite/
+/.tanstack/
+/out/
+/build
+*.tsbuildinfo
+
+# Generated by the VitNode Vite plugin and the TanStack route generator
+src/*.gen.ts
+
+# Misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Others
+.vercel
+.env*.local
+
+# Local storage adapter uploads
+/public/uploads

package/copy-of-vitnode-app/root/global.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="use-intl" />
+
+import core from '@vitnode/core/locales/en.json' with { type: 'json' }
+
+/**
+ * What `useTranslations` is allowed to be asked for.
+ *
+ * Augmenting **`use-intl`** rather than `next-intl`. `AppConfig` is declared by
+ * `use-intl`, which is what VitNode renders every string through on every host;
+ * `next-intl` only ever re-exported it. This is a type-level dependency and so
+ * it survives a grep for imports - which is exactly why it is worth naming.
+ *
+ * `use-intl` has to be a *direct* dependency of this app for the reference above
+ * to resolve. Under pnpm's strict `node_modules` layout, reaching it through
+ * `@vitnode/core` is not enough.
+ *
+ * Typed against core's English tree, which is the default locale: every other
+ * language falls back to it key by key, so it is the one that defines which keys
+ * exist. Add a plugin's tree to the intersection to get its keys checked too:
+ *
+ *     import blog from '@acme/blog/locales/en.json' with { type: 'json' }
+ *     Messages: typeof core & typeof blog
+ */
+declare module 'use-intl' {
+  interface AppConfig {
+    Messages: typeof core
+  }
+}

package/copy-of-vitnode-app/root/src/components/admin-shell.tsx

@@ -0,0 +1,72 @@
+import type { AdminUserSearch } from "@vitnode/core/tanstack/admin";
+
+import { AdminShellContent } from "@vitnode/core/tanstack/admin";
+import { LanguageSwitcher } from "@vitnode/core/tanstack/layout";
+
+import { adminNav } from "#/lib/admin-nav";
+import { adminUserSearchFn } from "#/lib/admin-search";
+import { useAppNavigate } from "#/lib/navigation";
+
+/**
+ * The AdminCP shell, as this app mounts it.
+ *
+ * Everything the panel *is* - the sidebar, the header, the palette, the user
+ * menu, the breadcrumb area and the one `<main>` - is `AdminShellContent`'s.
+ * What is bound here is only what a package cannot answer for an application:
+ *
+ *     onNavigate        useAppNavigate       the palette's Enter key
+ *     searchUsers       adminUserSearchFn    this app's own server function
+ *     languageSwitcher  <LanguageSwitcher/>  the router's
+ *     nav               adminNav             the plugins *this* app configured
+ *
+ * No `LinkComponent`: every sidebar destination is a route in this application's
+ * own tree, so the shell's own default - `RouterLink` - is the right one. The
+ * exception is handled a layer down rather than here: a plugin's `admin.nav`
+ * entry may point at a docs site or a status page, and `adminLinkFor` renders
+ * those as plain anchors, so an absolute URL is never handed to a router that
+ * would try to match it. The sidebar and the command palette both go through it,
+ * so an entry cannot behave one way when clicked and another when searched.
+ *
+ * `onNavigate` is still passed, because the palette moves the router *without a
+ * link*: Enter on a highlighted entry is a navigation nobody clicked, and it has
+ * to be handed the same de-localized destination a `<Link>` would build. See
+ * `#/lib/navigation`.
+ *
+ * ## `nav` is a projection, not the plugin registry
+ *
+ * `src/vitnode.config.ts` is server-side and carries message loaders, which a
+ * browser bundle has no business holding. So the sidebar is built from
+ * `#/lib/admin-nav`, which reads the generated browser-safe projection: ids,
+ * hrefs, permissions, icons and content type definitions, and nothing that
+ * renders a screen. The screens have a projection of their own - see
+ * `#/lib/content-registry`, which the content route imports so that a plugin's
+ * editor fields and form layouts land in that route's chunk rather than in the
+ * shell's.
+ *
+ * It carries the message namespaces with it, because a plugin group's headings
+ * live under that plugin's own id and the shell would otherwise render them as
+ * dotted identifiers. `_admin`'s loader warms the same list.
+ *
+ * No navigation is derived from a plugin's route tree, in either direction: the
+ * navigation model is complete regardless of which screen a click lands on, and
+ * a nav entry is a product decision rather than a consequence of the route tree.
+ */
+const searchUsers: AdminUserSearch = async search =>
+  await adminUserSearchFn({ data: { search } });
+
+export const AdminShell = ({ children }: { children: React.ReactNode }) => {
+  const navigate = useAppNavigate();
+
+  return (
+    <AdminShellContent
+      languageSwitcher={<LanguageSwitcher />}
+      nav={adminNav}
+      onNavigate={href => {
+        void navigate(href);
+      }}
+      searchUsers={searchUsers}
+    >
+      {children}
+    </AdminShellContent>
+  );
+};

package/copy-of-vitnode-app/root/src/components/main-header.tsx

@@ -0,0 +1,33 @@
+import { MainHeader as MainHeaderContent } from "@vitnode/core/tanstack/layout";
+
+/**
+ * The site header, as the main shell's slot for it.
+ *
+ * One line of application. The bar, the nav, the language and theme switchers,
+ * the user area and both cache entries they read are
+ * `@vitnode/core/tanstack/layout`'s `MainHeader`.
+ *
+ * **Your mark goes here.** Left alone the header renders VitNode's own, which is
+ * the right default and the wrong answer for a real site. Pass your own:
+ *
+ *     <MainHeaderContent logo={<YourLogo />} />
+ *
+ * This file exists so that choosing a mark is a sentence a site says out loud
+ * rather than something it inherits without noticing.
+ *
+ * No `LinkComponent`. Every header destination is a route in this application's
+ * own tree, so the header's own default - `RouterLink`, the router's `Link` in
+ * the shape the shared views ask for - is the right one, and the prop stays
+ * available for a host that needs to answer differently.
+ *
+ * ## What the shell owes it
+ *
+ * Two warm cache entries, both ensured by `_main`'s loader:
+ *
+ *     headerIntlQueryOptions  ->  a `useSuspenseQuery`, so this is required
+ *     prefetchSession         ->  the first paint shows the visitor, not a gap
+ *
+ * See the loader in `routes/_main.tsx`, which states why one is `ensure` and the
+ * other `prefetch`.
+ */
+export const MainHeader = () => <MainHeaderContent />;

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

@@ -0,0 +1,36 @@
+import type { VitNodeI18nConfig } from "@vitnode/core/lib/i18n/types";
+
+/**
+ * The languages this app serves.
+ *
+ * Its own module so the web config and the API config can point at the same
+ * object instead of drifting apart - the site and the emails it sends have to
+ * agree on which languages exist.
+ *
+ * Add a language by adding an entry. Packages ship their own translations, so a
+ * new locale needs no `messages` here: anything a package has not translated
+ * falls back to `defaultLocale` key by key. Register the package's own file for
+ * that language in `src/locales/packages.ts`, and put your own rewording in
+ * `src/locales/app.ts`.
+ */
+export const i18n = {
+  defaultLocale: "en" as const,
+  /**
+   * Explicit, because the app renders on a server: without one, `use-intl`
+   * formats dates in whatever zone the server happens to run in and warns that
+   * the client will disagree. Stage 3, which owns the locale runtime, is where a
+   * per-visitor zone would come from.
+   */
+  timeZone: "UTC",
+  /**
+   * `as const` on each code, and nothing else: it keeps `"en" | "pl"` out of
+   * the widening `satisfies` would otherwise do, which is what makes `Locale`
+   * in `lib/i18n/shared.ts` a real union rather than an alias for `string`.
+   */
+  locales: [
+    {
+      code: "en" as const,
+      name: "English",
+    },
+  ],
+} satisfies VitNodeI18nConfig;

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

@@ -0,0 +1,11 @@
+import { createServerFn } from "@tanstack/react-start";
+import { setAdminTransport } from "@vitnode/core/tanstack/admin";
+import { readAdminSessionOnApi } from "@vitnode/core/tanstack/admin/server";
+
+export const readAdminSessionFn = createServerFn().handler(
+  async () => await readAdminSessionOnApi(),
+);
+
+setAdminTransport({
+  readAdminSession: async () => await readAdminSessionFn(),
+});

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

@@ -0,0 +1,43 @@
+import { adminNavBundle } from "@vitnode/core/tanstack/admin";
+
+import { pluginAdminNav } from "#/admin-nav.gen";
+
+/**
+ * This installation's AdminCP navigation - core's own, plus whatever the plugins
+ * it configured contribute.
+ *
+ * Two lines, and both of them are host-only work by necessity. Which plugins are
+ * installed is a property of this application, and `src/admin-nav.gen.ts` is
+ * where the build writes the answer: one literal import per configured plugin
+ * that exports an `admin/nav` module. Every *rule* about what a sidebar contains
+ * - which entries a content type earns, how a hand-declared entry is titled,
+ * which permission hides one, which message namespaces the result needs - is
+ * `@vitnode/core`'s, in `adminNavBundle`. Nothing about navigation is decided
+ * here.
+ *
+ * ## Why it is not read from `vitnode.config.ts`
+ *
+ * That config is server-side on purpose (`vitnode.shell.config.ts` explains the
+ * split): it carries message loaders and API wiring, which a browser bundle has
+ * no business holding. A sidebar needs the ids, the hrefs, the permissions, the
+ * icons and the content type definitions, all of which are plain data. The
+ * generated projection is exactly that half, so the browser gets the navigation
+ * without the Content Engine's UI - which arrives, when a content screen
+ * actually renders, through `src/lib/content-registry.ts` instead.
+ *
+ * ## Module scope, and why that matters twice
+ *
+ * Evaluated once per bundle rather than per render. `AdminShellContent` memoises
+ * its namespace list on this object's identity, and `_admin`'s loader warms the
+ * messages from the same `namespaces` array the shell then reads - so a stable
+ * value here is what makes those one cache entry rather than two.
+ *
+ * ## Content entries were never rewritten, and that is the point
+ *
+ * A content type's entry is `/admin/content/…`, and it said exactly that
+ * through every change in which framework rendered those screens. Only *how a
+ * click travels* ever changed, and nothing here was edited for it. Routes and
+ * navigation stay separate concepts: nothing derives a nav entry from a route
+ * file, and nothing makes one conditional on a route existing.
+ */
+export const adminNav = adminNavBundle({ plugins: pluginAdminNav });

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

@@ -0,0 +1,37 @@
+import { createServerFn } from "@tanstack/react-start";
+import { readAdminUserSearchOnApi } from "@vitnode/core/tanstack/admin/server";
+import { z } from "zod";
+
+/**
+ * The AdminCP command palette's user lookup, as this app's server function.
+ *
+ * One handler, one line, exactly like `lib/auth.ts` - and here for the same
+ * reason. `createServerFn` needs the module it sits in to be transformed by the
+ * Start compiler on both sides of the render, and `@vitnode/core` reaches the
+ * server un-compiled (see the note in `lib/auth.ts`), so the declaration lives
+ * in the host and the behaviour lives in the package.
+ *
+ * ## Why it has a validator
+ *
+ * A server function is a public same-origin endpoint: its input is whatever a
+ * caller posts, not whatever the dialog typed. This value reaches an API query
+ * string, so it is parsed rather than trusted - trimmed, length-bounded, and a
+ * string at all.
+ *
+ * The bound is not a security control; the API authorizes the read from the
+ * admin cookie and pages it itself. It is a cheap refusal of the requests that
+ * could only ever be abuse - a megabyte of "search term" that the API would
+ * otherwise have to hand to Postgres.
+ *
+ * `POST` puts it behind `createCsrfMiddleware` in `src/start.ts`, which matters
+ * more here than it looks: this reads other people's names and email addresses,
+ * and a `GET` would be reachable from another origin's page with the
+ * administrator's cookies attached.
+ */
+const adminUserSearchInput = z.object({
+  search: z.string().trim().min(1).max(128),
+});
+
+export const adminUserSearchFn = createServerFn({ method: "POST" })
+  .validator(adminUserSearchInput)
+  .handler(async ({ data }) => await readAdminUserSearchOnApi(data.search));

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

@@ -0,0 +1,66 @@
+import { createServerFn } from "@tanstack/react-start";
+import {
+  changePasswordInputSchema,
+  passwordResetRequestInputSchema,
+  setAuthTransport,
+  signInInputSchema,
+  signOutInputSchema,
+  signUpInputSchema,
+  ssoCallbackInputSchema,
+  ssoStartInputSchema,
+} from "@vitnode/core/tanstack/auth";
+import {
+  changePasswordFromResetOnApi,
+  completeSsoOnApi,
+  readSessionOnApi,
+  requestPasswordResetOnApi,
+  signInOnApi,
+  signOutOnApi,
+  signUpOnApi,
+  startSsoOnApi,
+} from "@vitnode/core/tanstack/auth/server";
+
+export const readSessionFn = createServerFn().handler(
+  async () => await readSessionOnApi(),
+);
+
+export const signInFn = createServerFn({ method: "POST" })
+  .validator(signInInputSchema)
+  .handler(async ({ data }) => await signInOnApi(data));
+
+export const signOutFn = createServerFn({ method: "POST" })
+  .validator(signOutInputSchema)
+  .handler(async ({ data }) => await signOutOnApi(data));
+
+export const startSsoFn = createServerFn({ method: "POST" })
+  .validator(ssoStartInputSchema)
+  .handler(async ({ data }) => await startSsoOnApi(data));
+
+export const completeSsoFn = createServerFn({ method: "POST" })
+  .validator(ssoCallbackInputSchema)
+  .handler(async ({ data }) => await completeSsoOnApi(data));
+
+export const signUpFn = createServerFn({ method: "POST" })
+  .validator(signUpInputSchema)
+  .handler(async ({ data }) => await signUpOnApi(data));
+
+export const requestPasswordResetFn = createServerFn({ method: "POST" })
+  .validator(passwordResetRequestInputSchema)
+  .handler(async ({ data }) => await requestPasswordResetOnApi(data));
+
+export const changePasswordFromResetFn = createServerFn({ method: "POST" })
+  .validator(changePasswordInputSchema)
+  .handler(async ({ data }) => await changePasswordFromResetOnApi(data));
+
+setAuthTransport({
+  changePasswordFromReset: async input =>
+    await changePasswordFromResetFn({ data: input }),
+  completeSso: async input => await completeSsoFn({ data: input }),
+  readSession: async () => await readSessionFn(),
+  requestPasswordReset: async input =>
+    await requestPasswordResetFn({ data: input }),
+  signIn: async input => await signInFn({ data: input }),
+  signOut: async input => await signOutFn({ data: input }),
+  signUp: async input => await signUpFn({ data: input }),
+  startSso: async input => await startSsoFn({ data: input }),
+});

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

@@ -0,0 +1,51 @@
+import {
+  buildContentFrontendRegistry,
+  setContentFrontendRegistry,
+} from "@vitnode/core/content";
+
+import { pluginContentTypes } from "#/content-registry.gen";
+
+/**
+ * This installation's Content Engine registry - every content type its
+ * configured plugins register, with their editing screens attached.
+ *
+ * Two lines, and both of them are host-only work by necessity. Which plugins are
+ * installed is a property of this application, and `src/content-registry.gen.ts`
+ * is where the build writes the answer: one literal import per configured plugin
+ * that exports an `admin/content` module. Every *rule* about what a registration
+ * is - which paths are legal, which two of them collide, how they are ordered,
+ * how one is found by id or by `admin.path` - is `@vitnode/core`'s, in
+ * `buildContentFrontendRegistry`. Nothing about the Content Engine is decided
+ * here.
+ *
+ * ## Why it is not read from `vitnode.config.ts`
+ *
+ * That config is server-side on purpose (`vitnode.shell.config.ts` explains the
+ * split): it carries message loaders and API wiring, which a browser bundle has
+ * no business holding. The generated projection is the browser-safe half - the
+ * definitions, the icons and the override components - so the AdminCP gets the
+ * content screens without the server config. The same arrangement
+ * `src/lib/admin-nav.ts` uses for the sidebar, one layer deeper.
+ *
+ * ## Registration, and where it belongs in the import graph
+ *
+ * `setContentFrontendRegistry` fills a module-scope slot in `@vitnode/core`, so
+ * the package's own content code finds the registry without being handed it as
+ * a prop - the same shape as `setAdminTransport`. Module scope means *per
+ * bundle*: the browser has one instance and the server has one, and each
+ * registers its own.
+ *
+ * This module is reached through a `() => import(...)` that `/admin/content`'s
+ * loader awaits, never through a static import, and that is deliberate.
+ * Registration only has to happen before a content screen runs, and deferring it
+ * to the route is what lets Rollup put this whole graph - every plugin's field
+ * components, table cells and form layouts, plus `zod` and the Content Engine
+ * itself - in that route's chunk instead of in the bundle every page of the site
+ * loads first. `router.tsx` holds the thunk because that is where the route tree
+ * is composed; what it does *not* hold is the value. A plugin's own heavier
+ * parts stay lazier still: `@vitnode/blog` draws a `React.lazy` boundary around
+ * its Tiptap editor, so even opening the article list does not fetch it.
+ */
+export const contentRegistry = buildContentFrontendRegistry(pluginContentTypes);
+
+setContentFrontendRegistry(contentRegistry);

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

@@ -0,0 +1,128 @@
+/**
+ * What a VitNode document response may say about being stored.
+ *
+ * `private, no-store`, and it is not a precaution - it is a description of what
+ * is in the body. Every page this application renders streams a dehydrated Query
+ * cache into its HTML, and that cache always holds `["vitnode","session"]`: the
+ * visitor's own name, avatar and `isAdmin` flag. Inside `/admin` it also holds
+ * `["vitnode","admin-session"]`, which is that administrator's entire permission
+ * set. `tanstack/auth/session-query` and `tanstack/admin/session-query` both say
+ * so in their own words - "that document is personalised and must not be served
+ * from a shared cache" - and until now nothing on the response said it back.
+ *
+ * Nothing caches these documents today. That is a property of the current
+ * deployment, not of the application: the moment a CDN, a reverse proxy or a
+ * `Cache-Control`-respecting edge sits in front of the Node server, an absent
+ * directive is an invitation to store one visitor's HTML and serve it to the
+ * next. Stage 15 is when that becomes likely, so the header belongs here now.
+ *
+ * ## It is an invariant, not a default
+ *
+ * This started as a fallback for documents that said nothing, and that was
+ * wrong. A default is something a route may override, and at this architecture
+ * level there is no override a route could correctly choose: the dehydrated
+ * cache is written into the stream by `setupRouterSsrQueryIntegration` for
+ * *every* document, so a route opting into `public, max-age=60` would be
+ * publishing whichever visitor rendered first to everyone who asked next. The
+ * route cannot know that, because the private payload is not something the route
+ * put there.
+ *
+ * So the directive is forced rather than filled in, and a route that sets its
+ * own is overwritten rather than obeyed. That is the whole difference between
+ * this being a hardening measure and it being a security invariant.
+ *
+ * Public document caching is not forbidden forever - it is forbidden *while the
+ * session is dehydrated into the document*. Introducing it later is a separate,
+ * explicit piece of architecture in which the private state is kept out of the
+ * shared body (a public shell fetching its session client-side, say), and the
+ * invariant here would move with it rather than being quietly relaxed by a route
+ * that wanted a faster page.
+ *
+ * `private` bars a shared cache. `no-store` bars every cache, including the
+ * browser's own disk cache - which is the half that matters on a shared machine,
+ * where the previous person's permission set should not be recoverable from
+ * `chrome://cache` after they sign out. The pair is the standard spelling for
+ * "this body belongs to exactly one person, once".
+ *
+ * The known cost is the back/forward cache. `no-store` used to make a page
+ * outright ineligible for bfcache in Chromium; current versions keep such pages
+ * eligible but evict them when cookies change - which for this app means a
+ * sign-in or sign-out invalidates a back-navigation that would otherwise have
+ * restored a page rendered for the previous session. That is the correct trade
+ * and the outcome anybody would want, but it is a real difference and it is
+ * worth a look during a manual pass rather than a surprise later.
+ */
+export const DOCUMENT_CACHE_CONTROL = "private, no-store";
+
+/**
+ * Whether this response is one of the documents the rule above describes.
+ *
+ * One question, and it is what keeps the API out of it. `/api/*` is served by
+ * the Hono bridge through this same middleware, and a bare `GET` from it carries
+ * no `Cache-Control` of its own - so a rule that applied to every response would
+ * quietly forbid clients from caching the API. An HTML content-type is the
+ * honest way to ask "is this a page", it needs no path list to be kept in step
+ * with the router, and it cannot be wrong about a response that has already been
+ * produced.
+ *
+ * It deliberately does *not* ask whether a directive is already present. That
+ * used to be the second half of this predicate, and it is exactly the exemption
+ * the invariant above cannot afford - see {@link applyDocumentCacheControl}.
+ *
+ * A redirect is deliberately not matched here - it has no content type - and is
+ * handled by {@link applyRedirectCacheControl} instead, which wants a narrower
+ * rule.
+ */
+const isRenderedDocument = (headers: Headers): boolean =>
+  (headers.get("content-type") ?? "").toLowerCase().startsWith("text/html");
+
+/**
+ * Says what a rendered document is, on the response about to be sent.
+ *
+ * `set` rather than a conditional fill, and that is the fix: whatever the
+ * response was carrying is replaced. A route cannot opt out, because a route is
+ * not in a position to know what is in the body it is opting out for.
+ *
+ * Only `text/html` is touched. Everything else the middleware sees - the API,
+ * assets, client chunks, a `204` with no content type at all - keeps whatever it
+ * had, including nothing.
+ *
+ * Mutates rather than returning a new `Response`, because the middleware already
+ * holds the one Start produced and rebuilding it would mean copying a stream.
+ * The same reason `set-cookie` is appended in place a few lines away.
+ */
+export const applyDocumentCacheControl = (response: Response): void => {
+  if (!isRenderedDocument(response.headers)) return;
+
+  response.headers.set("cache-control", DOCUMENT_CACHE_CONTROL);
+};
+
+/**
+ * The same for a locale redirect, but only when it is carrying a cookie.
+ *
+ * A `308` from `/en/discover` to `/discover` is a fact about URLs, identical for
+ * every visitor, and permanently cacheable - which is most of the point of
+ * answering with one. So it keeps that property by default.
+ *
+ * The exception is the redirect that also writes the locale cookie, which is
+ * what `/pl/admin` produces: a stored copy of that would hand the next visitor
+ * through the same shared cache a `Set-Cookie` chosen by somebody else, and
+ * quietly switch their language. Shared caches are generally expected to refuse
+ * a `Set-Cookie` response, but "generally expected" is not a property this
+ * application can assert about somebody else's proxy, and one visitor's cookie
+ * reaching another's browser is not the kind of thing to leave to convention.
+ *
+ * So the cookie-carrying case is forced, for the same reason the document is: a
+ * `public` directive already on such a redirect is overwritten rather than
+ * respected, because the thing that makes it unsafe to share is the `Set-Cookie`
+ * beside it and not whatever the directive claims.
+ *
+ * The cookie-less case keeps its existing semantics untouched, directive and
+ * all. It carries no private state, so there is nothing here to protect and
+ * nothing to override.
+ */
+export const applyRedirectCacheControl = (response: Response): void => {
+  if (!response.headers.has("set-cookie")) return;
+
+  response.headers.set("cache-control", DOCUMENT_CACHE_CONTROL);
+};