@podosoft/podokit 1.2.0 → 1.4.0

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

@@ -0,0 +1,60 @@
+// Bundled entry for scripts/bootstrap-admin.mjs. The build bundles only its
+// top-level targets, so the script cannot import auth modules from dist directly.
+// 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/maintenance-command";
+import { verifyPassword } from "better-auth/crypto";
+import { auth } from "./auth/auth";
+import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";
+
+export interface BootstrapUser {
+  id: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  passwordHash: string | null;
+}
+
+interface BootstrapUserRow extends Omit<BootstrapUser, "emailVerified" | "signupApproved"> {
+  // SQLite stores booleans as 0 or 1.
+  emailVerified: boolean | number | null;
+  signupApproved: boolean | number | null;
+}
+
+function userQuery(placeholder: string): string {
+  return `SELECT u.id,
+                 u.email,
+                 u.role,
+                 u."emailVerified" AS "emailVerified",
+                 u."signupApproved" AS "signupApproved",
+                 a.password AS "passwordHash"
+            FROM "user" AS u
+       LEFT JOIN "account" AS a
+              ON a."userId" = u.id
+             AND a."providerId" = 'credential'
+           WHERE lower(u.email) = lower(${placeholder})
+           LIMIT 1`;
+}
+
+function flag(value: boolean | number | null): boolean {
+  return value === true || value === 1;
+}
+
+export async function findBootstrapUser(email: string): Promise<BootstrapUser | null> {
+  let row: BootstrapUserRow | undefined;
+  if (postgresPool) {
+    row = (await postgresPool.query<BootstrapUserRow>(userQuery("$1"), [email])).rows[0];
+  } else if (sqliteDatabase) {
+    row = sqliteDatabase.query<BootstrapUserRow, [string]>(userQuery("?1")).get(email) ?? undefined;
+  }
+  if (!row) return null;
+  return {
+    ...row,
+    emailVerified: flag(row.emailVerified),
+    signupApproved: flag(row.signupApproved),
+  };
+}
+
+export { auth, closeAuthDatabase, verifyPassword };

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

@@ -0,0 +1,35 @@
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+// The admin session list pages active sessions newest first with a keyset on
+// ("createdAt", "id"). Better Auth's schema indexes only "userId" and "token",
+// so without this index every page sorts the whole session table.
+const INDEX = "IDX_session_createdAt_id";
+
+export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
+  name = "IndexSessionCreatedAt1792060000000";
+  // CONCURRENTLY cannot run inside a transaction block. The runner therefore
+  // uses the "each" transaction mode. SQLite migrations always use one.
+  transaction = false;
+
+  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")`);
+      return;
+    }
+    // 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(
+      `SELECT 1 AS "invalid" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid`,
+      [`"${INDEX}"`],
+    ) as unknown[];
+    if (invalid.length > 0) await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${INDEX}"`);
+    await queryRunner.query(
+      `CREATE INDEX CONCURRENTLY IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`,
+    );
+  }
+
+  // A revert runs inside a transaction, so it uses a plain statement.
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS "${INDEX}"`);
+  }
+}

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/admin/users.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { keepLatestFilter, listUsersQuery, type UserListState } from "./users";
+import {
+  adminUsersQuery,
+  keepLatestFilter,
+  listAdminUsers,
+  listUsersQuery,
+  type UserListState,
+} from "./users";
 
 const base: UserListState = {
   page: 1,
@@ -11,9 +17,9 @@ const base: UserListState = {
   status: "",
 };
 
-describe("listUsersQuery", () => {
+describe("adminUsersQuery", () => {
   it("pages newest first by default", () => {
-    expect(listUsersQuery({ ...base, page: 3 })).toEqual({
+    expect(adminUsersQuery({ ...base, page: 3 })).toEqual({
       limit: 15,
       offset: 30,
       sortBy: "createdAt",
@@ -22,54 +28,75 @@ describe("listUsersQuery", () => {
   });
 
   it("sorts by a table column on the server", () => {
-    expect(listUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
+    expect(adminUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
       sortBy: "name",
       sortDirection: "asc",
     });
-    expect(listUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
+    expect(adminUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
       sortBy: "createdAt",
       sortDirection: "desc",
     });
   });
 
-  it("searches email case-insensitively and names as typed", () => {
-    expect(listUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
-      searchValue: "ada@example.com",
+  it("searches the chosen field with the text trimmed", () => {
+    expect(adminUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
+      search: "Ada@Example.COM",
       searchField: "email",
-      searchOperator: "contains",
     });
-    expect(listUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
-      searchValue: "Ada",
+    expect(adminUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
+      search: "Ada",
       searchField: "name",
     });
-    expect(listUsersQuery({ ...base, search: "   " })).not.toHaveProperty("searchValue");
+    expect(adminUsersQuery({ ...base, search: "   " })).not.toHaveProperty("search");
   });
 
-  it("maps the role and status filters to the single server filter", () => {
-    expect(listUsersQuery({ ...base, role: "admin" })).toMatchObject({
-      filterField: "role",
-      filterValue: "admin",
-      filterOperator: "eq",
+  it("sends the role and status filters together", () => {
+    expect(adminUsersQuery({ ...base, role: "admin", status: "active" })).toMatchObject({
+      role: "admin",
+      status: "active",
     });
-    expect(listUsersQuery({ ...base, status: "pending" })).toMatchObject({
-      filterField: "signupApproved",
-      filterValue: false,
-    });
-    expect(listUsersQuery({ ...base, status: "banned" })).toMatchObject({
-      filterField: "banned",
-      filterValue: true,
-    });
-    expect(listUsersQuery(base)).not.toHaveProperty("filterField");
+    expect(adminUsersQuery({ ...base, status: "pending" })).toMatchObject({ status: "pending" });
+    expect(adminUsersQuery({ ...base, status: "deleted" })).not.toHaveProperty("status");
+    expect(adminUsersQuery(base)).not.toHaveProperty("role");
+  });
+});
+
+describe("listAdminUsers", () => {
+  it("asks GET /admin/users for one page", async () => {
+    const paths: string[] = [];
+    const client = {
+      get: <T>(path: string): Promise<T> => {
+        paths.push(path);
+        return Promise.resolve({ items: [], total: 0 } as unknown as T);
+      },
+    };
+
+    await listAdminUsers(client, adminUsersQuery({ ...base, page: 2, search: "ada", role: "admin", status: "banned" }));
+    await listAdminUsers(client, adminUsersQuery(base));
+
+    expect(paths).toEqual([
+      "/admin/users?limit=15&offset=15&sortBy=createdAt&sortDirection=desc&search=ada&searchField=email&role=admin&status=banned",
+      "/admin/users?limit=15&offset=0&sortBy=createdAt&sortDirection=desc",
+    ]);
   });
 });
 
-describe("keepLatestFilter", () => {
-  it("keeps whichever filter changed last", () => {
+// Application-owned users pages from 1.2 still import these.
+describe("deprecated listUsers helpers", () => {
+  it("still builds the single-filter Better Auth query", () => {
+    expect(listUsersQuery({ ...base, page: 2, search: " Ada@Example.COM ", status: "banned" })).toEqual({
+      limit: 15,
+      offset: 15,
+      sortBy: "createdAt",
+      sortDirection: "desc",
+      searchValue: "ada@example.com",
+      searchField: "email",
+      searchOperator: "contains",
+      filterField: "banned",
+      filterValue: true,
+      filterOperator: "eq",
+    });
     expect(keepLatestFilter({ role: "admin", status: "" }, { role: "admin", status: "banned" }))
       .toEqual({ role: "", status: "banned" });
-    expect(keepLatestFilter({ role: "", status: "banned" }, { role: "user", status: "banned" }))
-      .toEqual({ role: "user", status: "" });
-    expect(keepLatestFilter({ role: "", status: "" }, { role: "user", status: "" }))
-      .toEqual({ role: "user", status: "" });
   });
 });

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/users.ts

@@ -1,4 +1,6 @@
-// Builds the Better Auth `admin.listUsers` query for the server-paged users table.
+import type { ApiClient } from "@podosoft/podokit-api-client";
+
+// Builds the `GET /admin/users` query for the server-paged users table.
 
 export type UserListSort = { key: string; dir: "asc" | "desc" };
 
@@ -12,6 +14,82 @@ export type UserListState = {
   status: string;
 };
 
+export type AdminUserStatus = "active" | "pending" | "banned";
+
+/** A user from `GET /admin/users`. */
+export type AdminUser = {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  banned: boolean;
+  banReason: string | null;
+  banExpires: string | null;
+  createdAt: string;
+};
+
+export type AdminUserPage = { items: AdminUser[]; total: number };
+
+export type AdminUserQuery = {
+  limit: number;
+  offset: number;
+  sortBy: string;
+  sortDirection: "asc" | "desc";
+  search?: string;
+  searchField?: "email" | "name";
+  role?: string;
+  status?: AdminUserStatus;
+};
+
+export const DEFAULT_USER_SORT: UserListSort = { key: "createdAt", dir: "desc" };
+
+const SORTABLE_FIELDS = new Set(["name", "email", "role", "createdAt"]);
+const STATUSES = new Set<string>(["active", "pending", "banned"]);
+
+function isStatus(value: string): value is AdminUserStatus {
+  return STATUSES.has(value);
+}
+
+export function adminUsersQuery(state: UserListState): AdminUserQuery {
+  const sort = state.sort && SORTABLE_FIELDS.has(state.sort.key) ? state.sort : DEFAULT_USER_SORT;
+  const search = state.search.trim();
+  return {
+    limit: state.perPage,
+    offset: (Math.max(state.page, 1) - 1) * state.perPage,
+    sortBy: sort.key,
+    sortDirection: sort.dir,
+    // The server matches case-insensitively, so the text is sent as typed.
+    ...(search ? { search, searchField: state.searchField === "name" ? "name" as const : "email" as const } : {}),
+    ...(state.role ? { role: state.role } : {}),
+    ...(isStatus(state.status) ? { status: state.status } : {}),
+  };
+}
+
+/** Reads one page; the role and status filters combine on the server. */
+export function listAdminUsers(client: Pick<ApiClient, "get">, query: AdminUserQuery): Promise<AdminUserPage> {
+  const params = new URLSearchParams({
+    limit: String(query.limit),
+    offset: String(query.offset),
+    sortBy: query.sortBy,
+    sortDirection: query.sortDirection,
+  });
+  if (query.search) {
+    params.set("search", query.search);
+    params.set("searchField", query.searchField ?? "email");
+  }
+  if (query.role) params.set("role", query.role);
+  if (query.status) params.set("status", query.status);
+  return client.get<AdminUserPage>(`/admin/users?${params.toString()}`);
+}
+
+// The 1.2 users page is application-owned and still imports the helpers below,
+// which build a Better Auth `admin.listUsers` query. Keep them until the next
+// major release so `podo update` does not break that page; new pages use
+// `adminUsersQuery` and `listAdminUsers`.
+
+/** @deprecated Use `AdminUserQuery` with `listAdminUsers`. */
 export type ListUsersQuery = {
   limit: number;
   offset: number;
@@ -25,10 +103,6 @@ export type ListUsersQuery = {
   filterOperator?: "eq";
 };
 
-export const DEFAULT_USER_SORT: UserListSort = { key: "createdAt", dir: "desc" };
-
-const SORTABLE_FIELDS = new Set(["name", "email", "role", "createdAt"]);
-
 function filterFor(role: string, status: string): Pick<ListUsersQuery, "filterField" | "filterValue" | "filterOperator"> {
   if (status === "pending") return { filterField: "signupApproved", filterValue: false, filterOperator: "eq" };
   if (status === "banned") return { filterField: "banned", filterValue: true, filterOperator: "eq" };
@@ -36,6 +110,7 @@ function filterFor(role: string, status: string): Pick<ListUsersQuery, "filterFi
   return {};
 }
 
+/** @deprecated Use `adminUsersQuery`; `listUsers` accepts only one filter. */
 export function listUsersQuery(state: UserListState): ListUsersQuery {
   const sort = state.sort && SORTABLE_FIELDS.has(state.sort.key) ? state.sort : DEFAULT_USER_SORT;
   const searchField = state.searchField === "name" ? "name" : "email";
@@ -47,8 +122,6 @@ export function listUsersQuery(state: UserListState): ListUsersQuery {
     sortDirection: sort.dir,
     ...(search
       ? {
-          // Better Auth matches with a case-sensitive LIKE on PostgreSQL and stores
-          // emails in lower case, so lower-casing makes email search case-insensitive.
           searchValue: searchField === "email" ? search.toLowerCase() : search,
           searchField,
           searchOperator: "contains" as const,
@@ -58,10 +131,7 @@ export function listUsersQuery(state: UserListState): ListUsersQuery {
   };
 }
 
-/**
- * `listUsers` accepts one filter, so the role and status selects are mutually
- * exclusive: when both hold a value, the one that just changed wins.
- */
+/** @deprecated `GET /admin/users` combines the role and status filters. */
 export function keepLatestFilter(
   previous: { role: string; status: string },
   next: { role: string; status: string },

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/guards.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Stands in for the application's own list in the app-owned public-paths.ts.
+vi.mock("./public-paths", () => ({ APP_PUBLIC_PATHS: ["/pricing", "/robots.txt"] }));
+
+const { isPublicPath } = await import("./guards");
+
+describe("isPublicPath", () => {
+  it("keeps the sign-in flow and the landing page public", () => {
+    expect(isPublicPath("/")).toBe(true);
+    expect(isPublicPath("/login")).toBe(true);
+    expect(isPublicPath("/reset-password/token")).toBe(true);
+    expect(isPublicPath("/admin")).toBe(false);
+    expect(isPublicPath("/account")).toBe(false);
+  });
+
+  it("adds the application's public prefixes and their subpaths", () => {
+    expect(isPublicPath("/pricing")).toBe(true);
+    expect(isPublicPath("/pricing/teams")).toBe(true);
+    expect(isPublicPath("/robots.txt")).toBe(true);
+    expect(isPublicPath("/pricingx")).toBe(false);
+  });
+});

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

@@ -1,4 +1,5 @@
 import { error } from "@sveltejs/kit";
+import { APP_PUBLIC_PATHS } from "./public-paths";
 
 /** Roles that may reach the admin console. Kept as a set so custom roles can be
  *  added here (and, later, replaced by a permission check) without touching every
@@ -13,6 +14,7 @@ const PUBLIC_PATHS = [
   "/verify-email",
   "/pending-approval",
   "/maintenance",
+  ...APP_PUBLIC_PATHS,
   // Modules add their public (no-session) page prefixes here.
   // podokit:begin:public-paths
   // podokit:end:public-paths

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

@@ -0,0 +1,9 @@
+/**
+ * Application-owned public page prefixes. A listed path also covers its
+ * subpaths ("/pricing" covers "/pricing/teams"). These pages render for
+ * anonymous visitors and keep rendering when the API or site settings are
+ * unavailable; every other page requires a session and fails closed with 503
+ * during an outage. Modules add their own prefixes in guards.ts, so do not
+ * repeat them here. PodoKit creates this file once and never overwrites it.
+ */
+export const APP_PUBLIC_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);
+  });
+});