@podosoft/podokit 1.3.0 → 1.4.1

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -19,6 +19,12 @@ Review these fields before planning:
 - `exposure`: Ingress or NodePort. Ingress routes `/` to web and routes only the
   exact paths in `webSocketPaths` directly to API. The list is empty by default;
   root, prefixes, patterns, queries, encoded separators, and traversal are invalid.
+  `apiPaths` lists static prefixes under `/api/` (such as `/api/files/uploads/`)
+  for bodies above the web `BODY_SIZE_LIMIT`; a second Ingress with a Traefik
+  `stripPrefix` Middleware sends them to API without `/api`. It needs a
+  Traefik-served IngressClass, and `/api/auth` is rejected. `podo deploy init`
+  and `podo add` fill in the paths installed modules declare (file-upload:
+  `/api/files/uploads/`); keep them.
 - `workloads`: API/web replicas and resources plus an optional worker
 - `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
@@ -61,9 +67,10 @@ The fields that differ from the Kubernetes driver:
 
 - `target`: Docker context, endpoint fingerprint, Compose project name
 - `exposure`: `bindAddress` and `port`, plus an exact `webSocketPaths` allowlist,
-  `trustedProxyCidrs`, and `gatewayImage`. With an empty allowlist, web owns the
-  published port. With paths, an internal gateway owns it, sends only exact listed
-  paths to API, and sends every other request to web. Forwarding headers are trusted
+  an `apiPaths` prefix list, `trustedProxyCidrs`, and `gatewayImage`. With both
+  lists empty, web owns the published port. With paths, an internal gateway owns
+  it, sends exact WebSocket paths to API, sends `apiPaths` prefixes to API with
+  `/api` removed, and sends every other request to web. Forwarding headers are trusted
   only from the direct proxy CIDRs in `trustedProxyCidrs`; leave it empty without an
   external proxy. The bind address defaults to `127.0.0.1`, because the expected
   front door is a trusted reverse proxy — binding every interface publishes the app

package/dist/templates/fullstack/dot-claude/skills/podokit-elysia-endpoint/SKILL.md

@@ -19,8 +19,13 @@ description: Use when adding or changing an Elysia REST endpoint in apps/api. Co
    `{ success: false, error: { code, message, statusCode, path, timestamp } }`.
 4. APIs are authenticated by default when auth is installed. Register an
    explicit `public`, `session`, `admin`, or `api-key` policy for every route.
+   A `GET` policy also covers `HEAD`, which Elysia answers with the GET handler.
 5. Add route detail and response schemas so the endpoint is present in the
    merged OpenAPI document at `/api-docs-json`.
+   Browsers reach the endpoint through the web `/api` proxy, which drops
+   headers it does not know. When the endpoint reads a custom request header or
+   returns one the browser needs, add its name to the app-owned
+   `apps/web/src/lib/server/proxy-headers.ts`.
 6. Add a `bun:test` unit or integration test beside the feature. Verify with
    `bun run lint`, `bun test`, `bun run build`, and
    `bun run --cwd apps/api contract` without starting a dev server. The contract

package/dist/templates/fullstack/dot-claude/skills/podokit-sveltekit-route/SKILL.md

@@ -26,5 +26,11 @@ description: Use when adding or changing a SvelteKit page/route in apps/web —
    app-owned `apps/web/src/lib/server/public-paths.ts`. A prefix covers its
    subpaths. Give such a page's loader a fallback for when the API is down
    instead of throwing. Never edit `PUBLIC_PATHS` in the managed `guards.ts`.
-7. **Verify**: `{{webRun}} build` (includes `svelte-check`)
+7. **File endpoints** (with the admin-dashboard module): `hooks.server.ts` loads
+   the session and site settings before every page and endpoint. For a
+   `+server.ts` that serves files or feeds and never reads `locals.user`, add
+   its prefix to `APP_ASSET_PATHS` in the app-owned
+   `apps/web/src/lib/server/asset-paths.ts` to skip both API calls. Pages under
+   that prefix still get the full context.
+8. **Verify**: `{{webRun}} build` (includes `svelte-check`)
    and add/adjust a Playwright test in `tests/`.

package/dist/templates/fullstack/dot-devcontainer/devcontainer.json

@@ -1,6 +1,7 @@
 {
   "name": "{{projectName}} (containerized dev)",
   "dockerComposeFile": ["../compose.dev.yaml"],
+  "initializeCommand": "{{packageExecutor}} @podosoft/podokit dev env",
   "service": "api",
   "workspaceFolder": "/app",
   "runServices": ["traefik", "web", "api", "worker", "postgres", "redis", "minio", "minio-init"],

package/dist/templates/fullstack/{dot-env.docker → dot-env.docker.example}

@@ -1,6 +1,9 @@
-# Container environment for compose.dev.yaml. Compose does not interpolate
-# from this file: set container memory limits such as API_MEM_LIMIT=3g in the
-# shell or the project's .env file instead.
+# Container environment for compose.dev.yaml. Commit this example with
+# development defaults only. podo dev copies it to the untracked .env.docker
+# when that file is missing and fills every empty *_SECRET value with a random
+# one. Put real credentials, such as OAuth or SMTP secrets, in .env.docker.
+# Compose does not interpolate from these files: set container memory limits
+# such as API_MEM_LIMIT=3g in the shell or the project's .env file instead.
 NODE_ENV=development
 PORT=5002
 POSTGRES_HOST=postgres
@@ -12,7 +15,7 @@ BACKEND_INTERNAL_URL=http://api:5002
 CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
 REDIS_HOST=redis
 REDIS_PORT=6379
-BETTER_AUTH_SECRET=change-me-in-container-min-32-characters
+BETTER_AUTH_SECRET=
 BETTER_AUTH_URL=http://{{projectName}}.localhost
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true

package/dist/templates/fullstack/dot-env.example

@@ -16,11 +16,18 @@ POSTGRES_DB=podokit
 # queries, plus DB_AUTH_POOL_MAX for the auth module when it is installed. Keep
 # replicas x (DB_POOL_MAX + DB_AUTH_POOL_MAX), plus a few for migrations, below
 # the server's max_connections (100 by default). The timeouts are milliseconds.
+# DB_QUERY_TIMEOUT_MS bounds how long a query waits for a server that stopped
+# answering; migrations and maintenance commands are not bounded.
 # DB_POOL_MAX=20
 # DB_CONNECT_TIMEOUT_MS=10000
 # DB_IDLE_TIMEOUT_MS=30000
+# DB_QUERY_TIMEOUT_MS=10000
 # DB_AUTH_POOL_MAX=10
 
+# Largest API request body in bytes (Bun's default is 128 MiB). Requests through
+# the web app's /api proxy are also bounded by BODY_SIZE_LIMIT below.
+# API_MAX_REQUEST_BODY_SIZE=134217728
+
 # Readiness (GET /health/ready): the longest one dependency check may run, and how
 # long a result is reused across probes (0 checks on every request).
 # READINESS_CHECK_TIMEOUT_MS=800
@@ -44,3 +51,6 @@ REDIS_DB=0
 # REDIS_USERNAME=
 # REDIS_PASSWORD=
 REDIS_TLS=false
+# Longest wait in milliseconds for Redis to answer one command. A command that
+# gets no reply in time fails, and its connection is closed and reopened.
+# REDIS_COMMAND_TIMEOUT_MS=1000

package/dist/templates/fullstack/dot-gitignore

@@ -5,6 +5,7 @@ build/
 .env
 .env.*
 !.env.example
+!.env.docker.example
 .DS_Store
 *.log
 

package/dist/templates/fullstack/dot-podokit/dev.json

@@ -1,5 +1,6 @@
 {
   "schemaVersion": 1,
   "hostname": "{{projectName}}.localhost",
-  "webSocketPaths": []
+  "webSocketPaths": [],
+  "apiPaths": []
 }

package/dist/templates/fullstack/infra/k3s/README.md

@@ -20,4 +20,6 @@ branch tags, and empty tags, and so should you.
 For a hand-managed API WebSocket endpoint, add a `pathType: Exact` Ingress path to
 the API service before the existing `/` web path. Do not route a prefix or the root
 to API. Deployment profiles express the same rule with
-`exposure.webSocketPaths` and validate it before rendering.
+`exposure.webSocketPaths` and validate it before rendering. A large-upload route
+under `/api/` needs `/api` removed on the way to the API; `exposure.apiPaths`
+renders a separate Ingress with a Traefik `stripPrefix` Middleware for that.

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-sessions/admin-sessions.migration.spec.ts

@@ -4,11 +4,16 @@ import type { QueryRunner } from "typeorm";
 import { revertLatestSqliteMigration, runSqliteMigrations } from "../database/sqlite-migrator";
 import { IndexSessionCreatedAt1792060000000 } from "../migrations/1792060000000-IndexSessionCreatedAt";
 
-function runner(type: "postgres" | "better-sqlite3", queries: string[], invalid = false): QueryRunner {
+function runner(
+  type: "postgres" | "better-sqlite3",
+  queries: string[],
+  { invalid = false, session = true }: { invalid?: boolean; session?: boolean } = {},
+): QueryRunner {
   return {
     connection: { options: { type } },
     query: (sql: string): Promise<unknown[]> => {
       queries.push(sql);
+      if (sql.includes("IS NOT NULL")) return Promise.resolve([{ exists: session }]);
       return Promise.resolve(invalid && sql.includes("indisvalid") ? [{ invalid: 1 }] : []);
     },
   } as unknown as QueryRunner;
@@ -25,6 +30,7 @@ function rows<Row>(database: Database, sql: string): Row[] {
 }
 
 const CREATE = 'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_session_createdAt_id" ON "session" ("createdAt", "id")';
+const SESSION_EXISTS = 'SELECT to_regclass($1) IS NOT NULL AS "exists"';
 
 describe("admin session list index migration", () => {
   it("builds the PostgreSQL index concurrently outside a transaction", async () => {
@@ -33,6 +39,7 @@ describe("admin session list index migration", () => {
     const up: string[] = [];
     await migration.up(runner("postgres", up));
     expect(up).toEqual([
+      SESSION_EXISTS,
       "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid",
       CREATE,
     ]);
@@ -44,8 +51,30 @@ describe("admin session list index migration", () => {
 
   it("rebuilds an invalid index left by an interrupted build", async () => {
     const up: string[] = [];
-    await new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, true));
-    expect(up.slice(1)).toEqual(['DROP INDEX CONCURRENTLY IF EXISTS "IDX_session_createdAt_id"', CREATE]);
+    await new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, { invalid: true }));
+    expect(up.slice(2)).toEqual(['DROP INDEX CONCURRENTLY IF EXISTS "IDX_session_createdAt_id"', CREATE]);
+  });
+
+  // `migration:run` runs only the application migrations, so on a new database
+  // Better Auth has not created its tables yet.
+  it("fails with the command that creates the Better Auth tables on PostgreSQL", async () => {
+    const up: string[] = [];
+    await expect(new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, { session: false })))
+      .rejects.toThrow('Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all"');
+    expect(up).toEqual([SESSION_EXISTS]);
+  });
+
+  it("fails with the command that creates the Better Auth tables on SQLite and records nothing", async () => {
+    const database = new Database(":memory:");
+    try {
+      const migrations = [{ timestamp: 1792060000000, migration: new IndexSessionCreatedAt1792060000000() }];
+      await expect(runSqliteMigrations(database, migrations)).rejects.toThrow(
+        'Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all"',
+      );
+      expect(rows(database, 'SELECT "name" FROM "migrations"')).toEqual([]);
+    } finally {
+      database.close();
+    }
   });
 
   it("serves the newest-first session page on SQLite and reverts", async () => {

package/dist/templates/modules/admin-dashboard/files/apps/api/src/bootstrap-admin-runtime.ts

@@ -3,7 +3,7 @@
 // The command runs against a migrated schema and reports a missing table from its
 // own query. Better Auth's asynchronous startup check would only race the
 // connection the command closes when it finishes.
-import "./auth/skip-schema-validation";
+import "./auth/maintenance-command";
 import { verifyPassword } from "better-auth/crypto";
 import { auth } from "./auth/auth";
 import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";

package/dist/templates/modules/admin-dashboard/files/apps/api/src/migrations/1792060000000-IndexSessionCreatedAt.ts

@@ -5,6 +5,12 @@ import type { MigrationInterface, QueryRunner } from "typeorm";
 // so without this index every page sorts the whole session table.
 const INDEX = "IDX_session_createdAt_id";
 
+// Better Auth creates "session" in its own schema step. `migrate:all` runs that
+// step before the application migrations; `migration:run` does not.
+const MISSING_SESSION_TABLE =
+  'Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all", ' +
+  "which applies the Better Auth schema before the application migrations.";
+
 export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
   name = "IndexSessionCreatedAt1792060000000";
   // CONCURRENTLY cannot run inside a transaction block. The runner therefore
@@ -13,9 +19,21 @@ export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
 
   async up(queryRunner: QueryRunner): Promise<void> {
     if (queryRunner.connection.options.type !== "postgres") {
-      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`);
+      try {
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`);
+      } catch (error) {
+        if (error instanceof Error && /no such table: (?:main\.)?session$/.test(error.message)) {
+          throw new Error(MISSING_SESSION_TABLE, { cause: error });
+        }
+        throw error;
+      }
       return;
     }
+    const [session] = await queryRunner.query(
+      `SELECT to_regclass($1) IS NOT NULL AS "exists"`,
+      [`"session"`],
+    ) as Array<{ exists: boolean } | undefined>;
+    if (!session?.exists) throw new Error(MISSING_SESSION_TABLE);
     // Sign-ins keep writing sessions while the index builds. An interrupted
     // build leaves an invalid index that IF NOT EXISTS would keep.
     const invalid = await queryRunner.query(

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -1,9 +1,12 @@
-import { error } from "@sveltejs/kit";
+import { error, type RequestEvent } from "@sveltejs/kit";
 import type { Handle } from "@sveltejs/kit/hooks";
+import { building } from "$app/env";
+import { routes } from "$app/manifest";
 import { serverApiClient } from "#lib/server/api.js";
 import { resolveLocale } from "#lib/i18n/messages.js";
 import { applySearchIndexingHeaders } from "#lib/server/search-indexing.js";
 import { isPublicPath } from "#lib/server/guards.js";
+import { needsRuntimeContext } from "#lib/server/runtime-context.js";
 import type { SiteSettings } from "#lib/site.svelte.js";
 import { ApiError } from "@podosoft/podokit-api-client";
 
@@ -12,15 +15,18 @@ function isTemporaryServiceFailure(cause: unknown): boolean {
   return cause.statusCode === 408 || cause.statusCode === 429 || cause.statusCode >= 500;
 }
 
-export const handle: Handle = async ({ event, resolve }) => {
-  // Static assets and API proxy requests do not render application layouts.
-  // Avoid multiplying settings/session API calls for every asset and proxied
-  // request; page and data routes still receive the complete runtime context.
-  if (event.route.id === null || event.url.pathname.startsWith("/api/")) {
-    const response = await resolve(event);
-    return applySearchIndexingHeaders(response, event.url.pathname);
-  }
+// An anonymous visitor with no site settings, for responses that render no
+// layout. The locale still follows the visitor's cookie.
+function setEmptyRuntimeContext(event: RequestEvent): void {
+  event.locals.site = null;
+  event.locals.siteUnavailable = false;
+  event.locals.user = null;
+  event.locals.session = null;
+  event.locals.authUnavailable = false;
+  event.locals.locale = resolveLocale(event.cookies.get("locale"));
+}
 
+async function loadRuntimeContext(event: RequestEvent): Promise<void> {
   // Public site settings (branding, locale/timezone defaults, maintenance, …)
   // and the session are independent, so both requests run at once. The
   // settings are loaded once here and reused by the layout load. The async
@@ -73,6 +79,18 @@ export const handle: Handle = async ({ event, resolve }) => {
   ) {
     error(503, "Service temporarily unavailable");
   }
+}
+
+export const handle: Handle = async ({ event, resolve }) => {
+  // Listed asset endpoints, missing subresources, the API proxy, and
+  // prerendering skip the two API lookups. Pages, their data, form actions,
+  // remote functions, and the 404 page get the complete runtime context.
+  const route = routes.find(({ id }) => id === event.route.id);
+  if (needsRuntimeContext(event, { building, route })) {
+    await loadRuntimeContext(event);
+  } else {
+    setEmptyRuntimeContext(event);
+  }
   const response = await resolve(event, {
     transformPageChunk: ({ html }) =>
       html.replace(

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/asset-paths.ts

@@ -0,0 +1,11 @@
+/**
+ * Application-owned prefixes for `+server.ts` endpoints that serve files, feeds,
+ * or other responses needing neither the session nor the site settings (for
+ * example "/docs" when an endpoint serves documentation files). A listed path
+ * also covers its subpaths. When an endpoint under a listed prefix answers a
+ * request, hooks.server.ts skips its two API lookups and the endpoint sees an
+ * anonymous `locals.user`. A `+page` under a listed prefix still gets the
+ * session and site settings, so it keeps its sign-in and maintenance checks.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_ASSET_PATHS: readonly string[] = [];

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/runtime-context.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Stands in for the application's own list in the app-owned asset-paths.ts.
+vi.mock("./asset-paths", () => ({ APP_ASSET_PATHS: ["/docs", "/feed.xml"] }));
+
+const { needsRuntimeContext, prefersHtml } = await import("./runtime-context");
+
+const NAVIGATION = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+const IMAGE = "image/avif,image/webp,image/apng,*/*;q=0.8";
+
+interface RequestOptions {
+  routeId?: string | null;
+  method?: string;
+  headers?: Record<string, string>;
+  isDataRequest?: boolean;
+  isRemoteRequest?: boolean;
+}
+
+function request(path: string, options: RequestOptions = {}) {
+  const url = new URL(path, "http://app.localhost");
+  return {
+    url,
+    route: { id: options.routeId === undefined ? url.pathname : options.routeId },
+    request: new Request(url, { method: options.method ?? "GET", headers: options.headers }),
+    isDataRequest: options.isDataRequest ?? false,
+    isRemoteRequest: options.isRemoteRequest ?? false,
+  };
+}
+
+describe("needsRuntimeContext", () => {
+  it("loads the session and site settings for pages and their data", () => {
+    expect(needsRuntimeContext(request("/account", { headers: { accept: NAVIGATION } }))).toBe(true);
+    expect(needsRuntimeContext(request("/account", { headers: { accept: "*/*" } }))).toBe(true);
+    expect(needsRuntimeContext(request("/account", { isDataRequest: true }))).toBe(true);
+  });
+
+  it("loads them for an unmatched route because the 404 page renders the root layout", () => {
+    // Without the session a signed-in visitor was sent to /login, which sent
+    // them straight back: a redirect loop on every missing page.
+    expect(
+      needsRuntimeContext(
+        request("/missing", { routeId: null, headers: { accept: NAVIGATION, "sec-fetch-dest": "document" } }),
+      ),
+    ).toBe(true);
+    expect(needsRuntimeContext(request("/missing", { routeId: null, headers: { accept: "*/*" } }))).toBe(true);
+    expect(needsRuntimeContext(request("/missing", { routeId: null, isDataRequest: true }))).toBe(true);
+  });
+
+  it("skips them for a missing subresource that SvelteKit answers without a layout", () => {
+    for (const destination of ["image", "script", "style", "font"]) {
+      expect(
+        needsRuntimeContext(request("/missing.png", { routeId: null, headers: { "sec-fetch-dest": destination } })),
+      ).toBe(false);
+    }
+  });
+
+  it("skips them for the backend proxy", () => {
+    expect(needsRuntimeContext(request("/api", { routeId: "/api/[...path]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/api/site/settings", { routeId: "/api/[...path]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/api/auth/get-session", { routeId: "/api/auth/[...all]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/apiary", { headers: { accept: NAVIGATION } }))).toBe(true);
+  });
+
+  it("skips them while prerendering", () => {
+    expect(needsRuntimeContext(request("/pricing", { headers: { accept: NAVIGATION } }), { building: true })).toBe(false);
+  });
+
+  it("loads them for remote functions, which may read the session without a route", () => {
+    expect(needsRuntimeContext(request("/_app/remote/abc/list", { routeId: null, isRemoteRequest: true }))).toBe(true);
+  });
+
+  it("skips them when an endpoint under an application asset path answers", () => {
+    const files = { page: false, endpoint: true };
+    expect(
+      needsRuntimeContext(
+        request("/docs/guide/diagram.png", { routeId: "/docs/[...path]", headers: { accept: IMAGE, "sec-fetch-dest": "image" } }),
+        { route: files },
+      ),
+    ).toBe(false);
+    // Opening a file in a tab is a navigation, but no page renders.
+    expect(
+      needsRuntimeContext(
+        request("/docs/manual.pdf", { routeId: "/docs/[...path]", headers: { accept: NAVIGATION, "sec-fetch-dest": "document" } }),
+        { route: files },
+      ),
+    ).toBe(false);
+    expect(needsRuntimeContext(request("/feed.xml", { headers: { accept: "application/rss+xml" } }), { route: files })).toBe(false);
+    expect(needsRuntimeContext(request("/documents", { headers: { accept: "*/*" } }), { route: files })).toBe(true);
+  });
+
+  it("keeps them when a page under an application asset path answers", () => {
+    const page = { page: true, endpoint: false };
+    expect(needsRuntimeContext(request("/docs", { headers: { accept: "*/*" } }), { route: page })).toBe(true);
+    expect(needsRuntimeContext(request("/docs", { headers: { accept: NAVIGATION } }), { route: page })).toBe(true);
+  });
+
+  it("follows SvelteKit's page or endpoint choice when an asset route has both", () => {
+    const both = { page: true, endpoint: true };
+    const docs = (options: RequestOptions) =>
+      needsRuntimeContext(request("/docs/intro", { routeId: "/docs/[slug]", ...options }), { route: both });
+    expect(docs({ headers: { accept: NAVIGATION } })).toBe(true);
+    expect(docs({ isDataRequest: true })).toBe(true);
+    expect(docs({ method: "POST", headers: { accept: "application/json", "x-sveltekit-action": "true" } })).toBe(true);
+    expect(docs({ headers: { accept: IMAGE } })).toBe(false);
+    expect(docs({ headers: { accept: "*/*" } })).toBe(false);
+    expect(docs({ method: "PUT", headers: { accept: NAVIGATION } })).toBe(false);
+    // Without route information the same negotiation applies.
+    expect(needsRuntimeContext(request("/docs/intro", { headers: { accept: IMAGE } }))).toBe(false);
+    expect(needsRuntimeContext(request("/docs/intro", { headers: { accept: NAVIGATION } }))).toBe(true);
+  });
+});
+
+describe("prefersHtml", () => {
+  it("follows SvelteKit's page and endpoint negotiation", () => {
+    expect(prefersHtml(NAVIGATION)).toBe(true);
+    expect(prefersHtml("text/*")).toBe(true);
+    expect(prefersHtml("*/*")).toBe(false);
+    expect(prefersHtml(null)).toBe(false);
+    expect(prefersHtml(IMAGE)).toBe(false);
+    expect(prefersHtml("application/json, text/html;q=0.5")).toBe(true);
+    expect(prefersHtml("application/json, */*;q=0.9, text/html;q=0.5")).toBe(false);
+    expect(prefersHtml("*/*;q=0.9, text/html")).toBe(true);
+    expect(prefersHtml("text/html;q=0, */*")).toBe(false);
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/runtime-context.ts

@@ -0,0 +1,107 @@
+import { APP_ASSET_PATHS } from "./asset-paths";
+
+/** The request fields that decide whether a response can use the session and site settings. */
+export interface RuntimeContextRequest {
+  url: URL;
+  route: { id: string | null };
+  request: Request;
+  isDataRequest: boolean;
+  isRemoteRequest: boolean;
+}
+
+// Fetch destinations that SvelteKit answers with a plain-text 404, without the
+// root layout, when no route matches.
+const SUBRESOURCE_DESTINATIONS = new Set([
+  "audio",
+  "audioworklet",
+  "font",
+  "image",
+  "json",
+  "manifest",
+  "paintworklet",
+  "report",
+  "script",
+  "serviceworker",
+  "sharedworker",
+  "style",
+  "track",
+  "video",
+  "webidentity",
+  "worker",
+  "xslt",
+]);
+
+function underPrefix(pathname: string, prefix: string): boolean {
+  return pathname === prefix || (prefix !== "/" && pathname.startsWith(`${prefix}/`));
+}
+
+/**
+ * True when an Accept header ranks HTML ahead of the wildcard. This mirrors how
+ * SvelteKit chooses between a page and an endpoint on the same route.
+ */
+export function prefersHtml(accept: string | null): boolean {
+  const ranges = (accept ?? "*/*")
+    .split(",")
+    .map((part, index) => {
+      const [range = "", ...params] = part.trim().toLowerCase().split(";");
+      const quality = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+      return { range: range.trim(), q: quality ? Number(quality.slice(2)) : 1, index };
+    })
+    .filter(({ range, q }) => range.includes("/") && q > 0)
+    .sort((a, b) => b.q - a.q || specificity(b.range) - specificity(a.range) || a.index - b.index);
+  const html = ranges.findIndex(({ range }) => range === "text/html" || range === "text/*");
+  const wildcard = ranges.findIndex(({ range }) => range === "*/*");
+  return html !== -1 && (wildcard === -1 || html < wildcard);
+}
+
+function specificity(range: string): number {
+  if (range === "*/*") return 0;
+  return range.endsWith("/*") ? 1 : 2;
+}
+
+/** Which files the matched route has, from `routes` in `$app/manifest`. */
+export interface RouteFiles {
+  page: boolean;
+  endpoint: boolean;
+}
+
+/** True when SvelteKit answers the request with the route's `+page` rather than its `+server`. */
+function answeredByPage(event: RuntimeContextRequest, route: RouteFiles | undefined): boolean {
+  if (route && !route.page) return false;
+  if (route && !route.endpoint) return true;
+  if (event.isDataRequest) return true;
+  const { headers, method } = event.request;
+  if (method !== "GET" && method !== "HEAD" && method !== "POST") return false;
+  if (method === "POST" && headers.get("x-sveltekit-action") === "true") return true;
+  return prefersHtml(headers.get("accept"));
+}
+
+/**
+ * Decide whether hooks.server.ts must load the session and the site settings
+ * before SvelteKit answers the request. It skips them only when the response
+ * cannot render a layout, or when the application listed the path in
+ * APP_ASSET_PATHS and a `+server` endpoint, not a `+page`, answers it.
+ */
+export function needsRuntimeContext(
+  event: RuntimeContextRequest,
+  options: { building?: boolean; route?: RouteFiles } = {},
+): boolean {
+  // Prerendering runs at build time without the API, and the stored HTML must
+  // not depend on one visitor's session or on runtime site settings.
+  if (options.building) return false;
+  const { pathname } = event.url;
+  // The backend proxy forwards the cookies; the API resolves the session itself.
+  if (underPrefix(pathname, "/api")) return false;
+  // Remote functions run application code that may read the session.
+  if (event.isRemoteRequest) return true;
+  if (event.route.id === null) {
+    // SvelteKit renders its 404 page with the root layout, which redirects or
+    // greets the visitor, unless the browser fetched a subresource.
+    const destination = event.request.headers.get("sec-fetch-dest") ?? "";
+    return !SUBRESOURCE_DESTINATIONS.has(destination);
+  }
+  if (APP_ASSET_PATHS.some((prefix) => underPrefix(pathname, prefix))) {
+    return answeredByPage(event, options.route);
+  }
+  return true;
+}

package/dist/templates/modules/admin-dashboard/files/tests/api/profile-image.api.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "@playwright/test";
 import { ADMIN } from "../helpers/accounts";
+import { expectObjectLength } from "../helpers/object-response";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -48,7 +49,7 @@ test("profile image upload, replacement, public read, and removal", async ({ pla
   expect(firstImage.ok()).toBeTruthy();
   expect(firstImage.headers()["content-type"]).toContain("image/png");
   expect(firstImage.headers()["cache-control"]).toBe("public, max-age=31536000, immutable");
-  expect(firstImage.headers()["content-length"]).toBe(String(PNG.byteLength));
+  expectObjectLength(firstImage.headers(), PNG.byteLength);
   expect((await firstImage.body()).equals(PNG)).toBe(true);
   const etag = firstImage.headers()["etag"];
   expect(etag).toMatch(/^"[^"]+"$/);

package/dist/templates/modules/admin-dashboard/files/tests/api/site-settings.api.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "@playwright/test";
 import { ADMIN } from "../helpers/accounts";
+import { expectObjectLength } from "../helpers/object-response";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -101,7 +102,7 @@ test("site favicon: the versioned URL is cached for good and other URLs revalida
     expect(current.status()).toBe(200);
     expect(current.headers()["cache-control"]).toBe(IMMUTABLE);
     expect(current.headers()["content-type"]).toContain("image/png");
-    expect(current.headers()["content-length"]).toBe(String(ICON.byteLength));
+    expectObjectLength(current.headers(), ICON.byteLength);
     expect((await current.body()).equals(ICON)).toBe(true);
     const etag = current.headers()["etag"] ?? "";
     expect(etag).toMatch(/^"[^"]+"$/);

package/dist/templates/modules/admin-dashboard/files/tests/helpers/disposable-users.ts

@@ -35,16 +35,16 @@ async function readCreatedUserId(response: CreatedUserResponse): Promise<string>
 export const test = base.extend<{ disposableUsers: DisposableUsers }>({
   disposableUsers: async ({ context, playwright }, use, testInfo) => {
     // API projects do not inherit the UI project's admin storageState, while a
-    // second admin sign-in can invalidate the shared UI session. Authenticate an
-    // isolated request context only for API tests and reuse browser cookies for UI.
-    let request = context.request;
-    let ownsRequest = false;
+    // second admin sign-in can invalidate the shared UI session. API tests sign in
+    // an isolated request context. UI tests copy the browser's admin cookies into
+    // their own context once, so a test that later signs its page in as another
+    // user does not turn cleanup into that user's (forbidden) requests.
+    const request = await playwright.request.newContext({
+      baseURL,
+      extraHTTPHeaders: origin,
+      ...(testInfo.project.name === "api" ? {} : { storageState: await context.storageState() }),
+    });
     if (testInfo.project.name === "api") {
-      request = await playwright.request.newContext({
-        baseURL,
-        extraHTTPHeaders: origin,
-      });
-      ownsRequest = true;
       const signIn = await request.post("/api/auth/sign-in/email", {
         data: { email: ADMIN.email, password: ADMIN.password },
       });
@@ -94,7 +94,7 @@ export const test = base.extend<{ disposableUsers: DisposableUsers }>({
           }
         }
       } finally {
-        if (ownsRequest) await request.dispose();
+        await request.dispose();
       }
     }
   },

package/dist/templates/modules/admin-dashboard/files/tests/helpers/object-response.ts

@@ -0,0 +1,12 @@
+import { expect } from "@playwright/test";
+
+// IN_MEMORY_READ_BYTES of @podosoft/podokit-runtime. Both object storage
+// providers and the web proxy keep the Content-Length of objects up to this
+// size; Bun may send larger ones chunked.
+const IN_MEMORY_READ_BYTES = 2 * 1024 * 1024;
+
+export function expectObjectLength(headers: Record<string, string>, size: number): void {
+  const length = headers["content-length"];
+  if (length === undefined && size > IN_MEMORY_READ_BYTES) return;
+  expect(length).toBe(String(size));
+}