@podosoft/podokit 1.5.0 → 1.6.1

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -358,6 +358,23 @@ export function proxyTimeoutFor(
   return entry ? entry.timeoutMs : backendProxyTimeoutMs();
 }
 
+/**
+ * Bun's fetch fails a request whose connection sends nothing for its idle
+ * timeout, 300 seconds unless BUN_CONFIG_HTTP_IDLE_TIMEOUT sets another, even
+ * while the proxy still waits for response headers.
+ */
+const FETCH_IDLE_TIMEOUT_MS = 300_000;
+
+/**
+ * Bun's fetch options for a request that waits up to timeoutMs for response
+ * headers. A wait without a deadline, or one Bun's idle timeout would cut
+ * first, turns that timeout off, so only the deadline, the health checks, and
+ * the browser end it. Shorter waits keep Bun's default.
+ */
+export function upstreamFetchOptions(timeoutMs: number | null): { timeout?: false } {
+  return timeoutMs === null || timeoutMs >= FETCH_IDLE_TIMEOUT_MS ? { timeout: false } : {};
+}
+
 /** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
 const IDLE_TICK_SECONDS = 4;
 /** The longest idle timeout Bun accepts; 0 turns it off. */
@@ -509,6 +526,40 @@ export function normalizeClientIp(address: string | undefined): string | undefin
   return address;
 }
 
+let publicOriginsSource: string | undefined;
+let publicOrigins: ReadonlySet<string> = new Set();
+
+/**
+ * The public web origins listed in CORS_ORIGIN. Wildcard patterns name no single
+ * origin and are skipped, as are entries that are not absolute URLs.
+ */
+export function configuredPublicOrigins(value = process.env.CORS_ORIGIN): ReadonlySet<string> {
+  if (value !== publicOriginsSource) {
+    publicOriginsSource = value;
+    publicOrigins = new Set(
+      (value ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => !entry.includes("*") && URL.canParse(entry))
+        .map((entry) => new URL(entry).origin),
+    );
+  }
+  return publicOrigins;
+}
+
+/**
+ * Tell the API which public origin a request came in on. SvelteKit resolves the
+ * request URL from the Host header, or from the gateway's forwarded headers that
+ * HOST_HEADER and PROTOCOL_HEADER name, so the value is sent only when that origin
+ * is listed in CORS_ORIGIN. The API can then build links for the origin a browser
+ * used without trusting a header a caller wrote.
+ */
+export function setForwardedOrigin(headers: Headers, url: URL): void {
+  if (!configuredPublicOrigins().has(url.origin)) return;
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.slice(0, -1));
+}
+
 export function resolveClientIp(getClientAddress: () => string): string | undefined {
   try {
     return normalizeClientIp(getClientAddress());
@@ -531,8 +582,10 @@ export async function proxyRequest(
   // Forward the resolved client IP so the API (better-auth) can record it.
   const forwardedIp = normalizeClientIp(clientAddress);
   if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
+  const requestUrl = new URL(request.url);
+  setForwardedOrigin(headers, requestUrl);
 
-  const { pathname } = new URL(request.url);
+  const { pathname } = requestUrl;
   if (!backendReachable()) {
     request.body?.cancel().catch(() => undefined);
     return backendFailure(pathname, 503);
@@ -578,6 +631,7 @@ export async function proxyRequest(
       // closed EventSource or aborted request keeps its API socket open until Bun's
       // fetch pool is exhausted and the web process stops serving requests.
       signal: AbortSignal.any([request.signal, waiting.signal]),
+      ...upstreamFetchOptions(timeoutMs),
     });
   } catch (cause: unknown) {
     // Nobody waits for an answer to a request the browser abandoned.

package/dist/templates/fullstack/apps/web/src/lib/server/proxy-timeouts.ts

@@ -10,7 +10,8 @@
  * headers before it answers 504 BACKEND_TIMEOUT; null waits as long as the API
  * takes. Either way the proxy answers 503 BACKEND_UNAVAILABLE once the API's
  * GET /health stops answering, and the deadline ends when the response headers
- * arrive.
+ * arrive. For null or 300 seconds and more, the proxy also turns off Bun's fetch
+ * idle timeout, which would otherwise end a silent wait after 300 seconds.
  *
  * Bun closes a silent connection up to 4 seconds before its idle timeout, so a
  * longer wait also needs the API's API_IDLE_TIMEOUT and the web server's

package/dist/templates/fullstack/apps/web/tsconfig.json

@@ -6,5 +6,5 @@
     "esModuleInterop": true,
     "skipLibCheck": true
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts", "vite.extensions.ts"]
 }

package/dist/templates/fullstack/apps/web/vite.config.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { webSocketProxy } from "./vite.config.ts";
+
+describe("dev-server WebSocket proxy", () => {
+  it("sends each exact path in .podokit/dev.json to the API", () => {
+    const proxy = webSocketProxy(
+      JSON.stringify({ hostname: "app.localhost", webSocketPaths: ["/events/ws", "/agent.v1/ws"] }),
+      "http://api:5002",
+    );
+
+    expect(proxy).toEqual({
+      "^/events/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+      "^/agent\\.v1/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+    });
+    const [events] = Object.keys(proxy).map((key) => new RegExp(key));
+    expect(events?.test("/events/ws")).toBe(true);
+    expect(events?.test("/events/ws?token=1")).toBe(true);
+    expect(events?.test("/events/ws/other")).toBe(false);
+    expect(events?.test("/events/wsx")).toBe(false);
+  });
+
+  it("proxies nothing without the file or its paths", () => {
+    expect(webSocketProxy(null)).toEqual({});
+    expect(webSocketProxy(JSON.stringify({ hostname: "app.localhost" }))).toEqual({});
+  });
+
+  it("rejects a path the gateway would reject", () => {
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: ["events/ws"] }))).toThrow(
+      'invalid path: "events/ws"',
+    );
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: "/events/ws" }))).toThrow("must be an array");
+  });
+});

package/dist/templates/fullstack/apps/web/vite.config.ts

@@ -1,8 +1,10 @@
+import { readFileSync } from "node:fs";
 import adapter from "@sveltejs/adapter-bun";
 import { sveltekit } from "@sveltejs/kit/vite";
 import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
 import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
+import { defineConfig, mergeConfig, type ProxyOptions } from "vite";
+import { appSvelteKitConfig, appViteConfig } from "./vite.extensions.ts";
 
 // Inside the dev container, bind to all interfaces and accept local gateway or
 // HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
@@ -10,16 +12,56 @@ import { defineConfig } from "vite";
 const inDocker = process.env.VITE_DOCKER === "1";
 const publicOrigin = process.env.PODOKIT_BUILD_ORIGIN;
 
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    sveltekit({
-      adapter: adapter(),
-      preprocess: vitePreprocess(),
-      ...(publicOrigin ? { paths: { origin: publicOrigin } } : {}),
+/**
+ * Dev-server proxies for the exact WebSocket paths in `.podokit/dev.json`. A
+ * SvelteKit route cannot answer an upgrade, so `bun run dev` sends these paths to
+ * the API the way the `podo dev` gateway and a deployment's edge do. The API must
+ * authenticate each upgrade itself.
+ */
+export function webSocketProxy(
+  devConfig: string | null,
+  target = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002",
+): Record<string, ProxyOptions> {
+  if (devConfig === null) return {};
+  const { webSocketPaths = [] } = JSON.parse(devConfig) as { webSocketPaths?: unknown };
+  if (!Array.isArray(webSocketPaths)) throw new Error(".podokit/dev.json webSocketPaths must be an array of paths");
+  return Object.fromEntries(
+    webSocketPaths.map((path: unknown) => {
+      if (typeof path !== "string" || !/^\/[A-Za-z0-9._~!$&'()+,;=:@/-]+$/.test(path)) {
+        throw new Error(`.podokit/dev.json webSocketPaths has an invalid path: ${JSON.stringify(path)}`);
+      }
+      const exact = `^${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\?.*)?$`;
+      return [exact, { target, ws: true, xfwd: true }];
     }),
-  ],
-  server: {
-    ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
-  },
-});
+  );
+}
+
+function readDevConfig(): string | null {
+  try {
+    return readFileSync(new URL("../../.podokit/dev.json", import.meta.url), "utf8");
+  } catch (cause) {
+    if ((cause as { code?: unknown }).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+export default defineConfig((env) =>
+  mergeConfig(
+    {
+      plugins: [
+        tailwindcss(),
+        sveltekit({
+          adapter: adapter(),
+          preprocess: vitePreprocess(),
+          ...appSvelteKitConfig,
+          ...(publicOrigin ? { paths: { ...appSvelteKitConfig.paths, origin: publicOrigin } } : {}),
+        }),
+      ],
+      server: {
+        ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
+        ...(env.command === "serve" ? { proxy: webSocketProxy(readDevConfig()) } : {}),
+      },
+    },
+    typeof appViteConfig === "function" ? appViteConfig(env) : appViteConfig,
+  ),
+);

package/dist/templates/fullstack/apps/web/vite.extensions.ts

@@ -0,0 +1,23 @@
+import type { Config as SvelteKitConfig } from "@sveltejs/kit/vite";
+import type { UserConfig, UserConfigFnObject } from "vite";
+
+/**
+ * Application-owned additions to the managed vite.config.ts, combined with Vite's
+ * `mergeConfig`: lists such as `plugins` are appended and objects are merged key
+ * by key. Use it for dev-server warmup, dependency optimization, `define`
+ * constants, extra plugins, or extra allowed hosts instead of editing
+ * vite.config.ts. A function receives Vite's `{ command, mode }`. WebSocket paths
+ * listed in `.podokit/dev.json` already reach the API through the dev server.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const appViteConfig: UserConfig | UserConfigFnObject = {
+  // Transform the pages most sessions open first as soon as the dev server starts:
+  // server: { warmup: { clientFiles: ["./src/routes/+layout.svelte", "./src/routes/+page.svelte"] } },
+};
+
+/**
+ * Application-owned SvelteKit options, such as `alias`, `csrf`, or `prerender`.
+ * PodoKit sets `adapter` and `preprocess`, and `paths.origin` from
+ * PODOKIT_BUILD_ORIGIN at build time.
+ */
+export const appSvelteKitConfig: SvelteKitConfig = {};

package/dist/templates/fullstack/compose.dev.yaml

@@ -48,6 +48,7 @@ services:
         - { action: sync, path: ./apps/web/src, target: /app/apps/web/src }
         - { action: sync, path: ./apps/web/static, target: /app/apps/web/static }
         - { action: sync+restart, path: ./apps/web/vite.config.ts, target: /app/apps/web/vite.config.ts }
+        - { action: sync+restart, path: ./apps/web/vite.extensions.ts, target: /app/apps/web/vite.extensions.ts }
         - { action: rebuild, path: ./apps/web/package.json }
 
   api:
@@ -121,7 +122,7 @@ services:
     mem_limit: ${MINIO_MEM_LIMIT:-512m}
     memswap_limit: ${MINIO_MEM_LIMIT:-512m}
     profiles: [storage]
-    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z@sha256:635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46
     command: server /data --console-address ":9001"
     environment:
       MINIO_ROOT_USER: podokit
@@ -134,15 +135,17 @@ services:
     mem_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     memswap_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     profiles: [storage]
-    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z@sha256:cfc83108c3abb371f8fb84d99c1fdc88f8c237e022409b0081fb7c0a3be634dd
     depends_on:
       minio: { condition: service_started }
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint:
       - sh
-      - -c
+      - -ec
       - |
         until mc alias set loc http://minio:9000 podokit podokitsecret; do sleep 1; done
-        mc mb -p loc/podokit || true
+        mc mb --ignore-existing loc/podokit
     networks: [podokit]
 
 networks:

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

@@ -16,9 +16,9 @@ Read the profile's `driver` first and say which one you are operating.
 1. Run `{{packageExecutor}} @podosoft/podokit status`, `{{packageExecutor}} @podosoft/podokit diff`, and `{{packageExecutor}} @podosoft/podokit doctor`. Stop if managed-file conflicts or unsupported framework versions could make the image unreliable.
 2. Read [references/profile.md](references/profile.md) before creating or changing a deployment profile.
 3. Make sure the images exist for that tag. Read [references/release.md](references/release.md): tagging `vX.Y.Z` runs the release workflow, which builds and pushes both images and stops there. Never apply a release whose images were not published.
-4. Run `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing secret values.
+4. Run `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every `FAIL` line and show the user every `warn` line, without printing secret values.
 5. Run `{{packageExecutor}} @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
-6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, the migration warning, and the plan hash.
+6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, every plan warning, and the plan hash.
 7. Do not apply until the user explicitly approves that exact plan.
 8. Apply with `{{packageExecutor}} @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
 9. Run `{{packageExecutor}} @podosoft/podokit deploy status --profile <name> --json` and `{{packageExecutor}} @podosoft/podokit deploy verify --profile <name> --json`.

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

@@ -24,9 +24,17 @@ Review these fields before planning:
   `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.
+  `/api/files/uploads/`); keep them. `edgeProxies` counts the reverse proxies in
+  front of the Ingress controller or NodePort (default 0); the web server then
+  trusts that many plus the controller in `X-Forwarded-For`. Never set
+  `XFF_DEPTH`, `ADDRESS_HEADER`, `TRUSTED_PROXY_HOPS`, or `TRUSTED_PROXY_HEADER`
+  in `runtimeConfig`; the profile refuses them.
 - `workloads`: API/web replicas and resources plus an optional worker
-- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
+- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage.
+  PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
+  application opens itself, each sized by a `runtimeConfig` key (`sizeKey`) or a
+  fixed `size` when the code sets it; the doctor and the plan check the connection budget
+  against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
 - `runtimeConfig`: non-sensitive environment values only
 - `verification`: HTTPS origin and checks with exact statuses and optional JSON fields
@@ -72,7 +80,9 @@ The fields that differ from the Kubernetes driver:
   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
+  external proxy. `edgeProxies` counts the reverse proxies in front of the published
+  port (default 1); with the gateway it must match `trustedProxyCidrs`, which the
+  doctor checks. 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
   before TLS exists.
 - `workloads`: replicas plus Compose `cpus` and `memory` limits

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

@@ -1,6 +1,6 @@
 ---
 name: podokit-update
-description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject.
+description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject/restore.
 ---
 
 # Keep a PodoKit project up to date
@@ -11,15 +11,18 @@ its own files while keeping the user's changes.
 ```bash
 podo status          # version, modules, file tiers, and how many managed files were edited
 podo diff            # list the PodoKit-managed files you've edited (owned files ignored)
+podo diff <path>     # line diff of one file against the template (owned files too)
 podo doctor          # check framework versions vs. the supported ranges
 podo update          # dry-run: preview what a newer version would change (writes nothing)
 podo update --apply  # apply it — clean updates are written; your edits are 3-way merged
 podo eject <path>    # take ownership of a managed file so update skips it
+podo restore <path>  # rewrite a managed file from the template; re-manages an ejected file
 ```
 
 Rules to respect:
 - **owned** files (routes, your components, `AGENTS.md`, shadcn `ui/**`) are never
-  touched by `update`.
+  touched by `update`. When their template changes, the plan lists them as
+  `review`; compare with `podo diff <path>` and copy what the app needs.
 - **assembled** files are recomputed from the module set — keep edits **outside**
   the `// podokit:begin…end` fences.
 - Run `podo update` (dry-run) first and read the plan before `--apply`. Commit or

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

@@ -18,11 +18,14 @@ TRUSTED_PROXY_HOPS=1
 # response headers.
 # BACKEND_TIMEOUT_MS=2000
 # BACKEND_PROXY_TIMEOUT_MS=30000
-CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
+# podo dev sets CORS_ORIGIN and BETTER_AUTH_URL for web and api from
+# .podokit/dev.json. These two serve compose.dev.yaml run without podo dev,
+# such as from the devcontainer.
+CORS_ORIGIN={{devCorsOrigin}}
 REDIS_HOST=redis
 REDIS_PORT=6379
 BETTER_AUTH_SECRET=
-BETTER_AUTH_URL=http://{{projectName}}.localhost
+BETTER_AUTH_URL={{devAuthUrl}}
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true
 RATE_LIMIT_TTL=60

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

@@ -3,9 +3,13 @@
 # ── Required (runtime) ───────────────────────────────────────────────
 NODE_ENV=development
 PORT=5002
+# Address the API listens on (default 0.0.0.0); 127.0.0.1 keeps it off the network.
+# HOST=0.0.0.0
 
 # Canonical database connection. Set this for PostgreSQL or SQLite; POSTGRES_* remains a fallback.
 # DATABASE_URL=postgres://podokit:podokit@localhost:5432/podokit
+# With SQLite and no DATABASE_URL, the database file, relative to apps/api.
+# SQLITE_PATH=./data/podokit.sqlite
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=podokit

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

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

package/dist/templates/fullstack/infra/k3s/configmap.yaml

@@ -16,3 +16,4 @@ data:
   HOST_HEADER: "x-forwarded-host"
   ADDRESS_HEADER: "x-forwarded-for"
   XFF_DEPTH: "1"
+  # podokit:end:runtime-config

package/dist/templates/fullstack/tests/README.md

@@ -13,9 +13,58 @@ The suite runs against a live stack (web on `E2E_BASE_URL`, proxying `/api/*` to
 the API). With the recommended containerized loop, start `podo dev watch` and run:
 
 ```bash
-E2E_BASE_URL=http://{{projectName}}.localhost {{rootRun}} test:e2e
+E2E_BASE_URL=http://{{devHostname}} {{rootRun}} test:e2e
 ```
 
 The default `http://localhost:5001` is for the alternative `{{rootRun}} dev`
 host-process loop. Files ending in `*.api.spec.ts` run in the request-only `api`
 project; `*.ui.spec.ts` run in the chromium `ui` project.
+
+## Workers and exclusive tests
+
+The suite runs on one worker unless `E2E_WORKERS` says otherwise. For the whole
+suite, more workers finish sooner:
+
+```bash
+E2E_WORKERS=2 {{rootRun}} test:e2e
+```
+
+Set the count with `E2E_WORKERS`, not `--workers`: the global setup refuses more
+than one worker when `E2E_WORKERS` is unset.
+
+Every test shares one API, database, mail catcher, and SMS sink. A test that
+changes state other tests rely on takes the `@exclusive` tag:
+
+```ts
+test("maintenance mode holds visitors back", { tag: "@exclusive" }, async ({ page }) => {
+  // ...
+});
+```
+
+Tag a test when it changes a server-wide setting (a feature flag, the
+authentication configuration such as SMTP, social providers, or sign-up
+approval, the site settings, or a module's settings) or the profile of a seeded
+account. Each project has an `<name>-exclusive` twin, such as `ui-exclusive`,
+that runs only the tagged tests, one at a time. Never empty the shared mail
+catcher or SMS sink in a test: send to an address or number of the test's own
+instead.
+
+The `test:e2e` scripts run `run-e2e.ts`, which hands its arguments (a file,
+`--grep`, `--project`) to Playwright. With more than one worker it runs
+Playwright twice: first every test not tagged `@exclusive` on those workers,
+then the tagged tests on one worker, even when a test failed in the first run.
+The suite fails when either run fails. The second run reports to
+`playwright-report/exclusive` and `test-results/exclusive`:
+
+```bash
+bunx playwright show-report playwright-report/exclusive
+```
+
+A plain `bunx playwright test` with `E2E_WORKERS` above 1 makes one run in which
+the twins depend on every other test: a failing test there leaves the exclusive
+tests not run, and selecting an exclusive test runs every other test first. Use
+`{{rootRun}} test:e2e` on more workers, and do not combine `--no-deps` with
+`E2E_WORKERS` above 1.
+
+Application-owned projects in `playwright.projects.cjs` get twins too. A project
+that another project depends on is a setup project and keeps a single copy.

package/dist/templates/fullstack/tests/helpers/app-paths.ts

@@ -0,0 +1,18 @@
+import type { AppPaths } from "./paths";
+
+/**
+ * Where this application's screens differ from the generated ones, for the
+ * managed e2e specs. PodoKit creates this file once and never overwrites it.
+ * Set only what differs; `paths.ts` documents each entry and its default. For
+ * example, an app whose first screen is a signed-in workspace without a
+ * heading, and which shows no public footer:
+ *
+ * ```ts
+ * export const appPaths: Partial<AppPaths> = {
+ *   homeReady: (page) => page.getByTestId("workspace"),
+ *   indexable: [],
+ *   footer: null,
+ * };
+ * ```
+ */
+export const appPaths: Partial<AppPaths> = {};

package/dist/templates/fullstack/tests/helpers/paths.ts

@@ -0,0 +1,33 @@
+import type { Locator, Page } from "@playwright/test";
+import { appPaths } from "./app-paths";
+
+/**
+ * The application screens managed specs visit. The defaults describe the
+ * generated pages; `app-paths.ts`, which the application owns, overrides any
+ * of them, so a managed spec never needs editing for an app's own screens.
+ */
+export interface AppPaths {
+  /** The first screen a visitor opens. */
+  home: string;
+  /** Visible once the first screen has rendered. */
+  homeReady: (page: Page) => Locator;
+  /** Public pages search engines may index: they carry no `X-Robots-Tag`. */
+  indexable: string[];
+  /** A public page that renders the managed `SiteFooter`, or null when none does. */
+  footer: string | null;
+  /**
+   * A page that renders the managed `LanguageSwitch`, `ThemeToggle`, and
+   * `AccountMenu` for a signed-in user, or null when none does.
+   */
+  accountMenu: string | null;
+}
+
+const defaults: AppPaths = {
+  home: "/",
+  homeReady: (page) => page.getByRole("heading", { level: 1 }),
+  indexable: ["/"],
+  footer: "/login",
+  accountMenu: "/",
+};
+
+export const paths: AppPaths = { ...defaults, ...appPaths };

package/dist/templates/fullstack/tests/helpers/seeded-admin.ts

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The administrator the admin-dashboard Playwright setup seeds, with the address
+ * and password `accounts.ts` reads from `E2E_*` variables and the application's
+ * `app-accounts.ts`, or null in an app without that module. Specs of modules
+ * that do not require admin-dashboard sign in with this instead of importing
+ * `accounts.ts`, which only admin-dashboard installs.
+ */
+export async function seededAdmin(): Promise<{ email: string; password: string } | null> {
+  if (!existsSync(join(__dirname, "accounts.ts"))) return null;
+  const { ADMIN } = await import("./accounts");
+  return { email: ADMIN.email, password: ADMIN.password };
+}

package/dist/templates/fullstack/tests/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "test:e2e": "bunx playwright test",
-    "test:e2e:ui": "bunx playwright test --project=ui",
-    "test:e2e:api": "bunx playwright test --project=api",
+    "test:e2e": "bun run-e2e.ts",
+    "test:e2e:ui": "bun run-e2e.ts --project=ui --project=ui-exclusive",
+    "test:e2e:api": "bun run-e2e.ts --project=api --project=api-exclusive",
     "test:e2e:report": "bunx playwright show-report"
   },
   "devDependencies": {

package/dist/templates/fullstack/tests/playwright.config.ts

@@ -1,11 +1,15 @@
 import { defineConfig, devices } from "@playwright/test";
-import { loadPlaywrightProjects } from "./playwright.extensions";
+import { e2eRunSettings, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
+// E2E_WORKERS sets the worker count (default 1); tests tagged @exclusive run in
+// `<project>-exclusive` twins after the others, in a second run when run-e2e.ts
+// starts the suite on more workers (see playwright.extensions.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const run = e2eRunSettings();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/ },
   { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
@@ -16,12 +20,14 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: [["list"], ["html", { open: "never" }]],
+  workers: run.workers,
+  outputDir: run.outputDir,
+  globalSetup: "./playwright.extensions.ts",
+  reporter: [["list"], ["html", { open: "never", outputFolder: run.reportFolder }]],
   use: {
     baseURL,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [...coreProjects, ...loadPlaywrightProjects(coreProjects)],
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], run.workers, run.phase),
 });