chore: release v5.2.6

feat(mcp): add cover-letter PDF downloads (#3304 )
* feat(mcp): add cover-letter PDF downloads * fix(mcp): bind signed PDF targets * test(mcp): cover unavailable cover letters * fix(api): accept legacy PDF download targets * fix(server): limit legacy PDF tokens to resumes --------- Co-authored-by: Amruth Pillai <im.amruth@gmail.com>
2026-09-30 16:54:26 +10:00 · 2026-08-14 05:24:08 +02:00 · 2026-08-13 23:09:56 +02:00 · 2026-08-13 23:07:55 +02:00 · 2026-08-13 23:07:49 +02:00 · 2026-08-13 23:01:06 +02:00
779 changed files with 169839 additions and 18745 deletions
@@ -56,6 +56,9 @@ jobs:
      - name: Install Dependencies
        run: pnpm install --frozen-lockfile

+      - name: Run Server and Tooling Tests
+        run: pnpm exec turbo run test:ci --filter=server --filter=@reactive-resume/tooling
+
      - name: Install Playwright Browser
        run: pnpm exec playwright install --with-deps chromium

@@ -73,8 +76,8 @@ jobs:
      - name: Build
        run: pnpm build

-      - name: Run E2E Tests
-        run: pnpm test:e2e:ci
+      - name: Run Baseline E2E Tests
+        run: pnpm exec playwright test --grep-invert "@semantic-css"

      - name: Upload Playwright Report
        if: always()
@@ -51,6 +51,7 @@ temp
 .cursor
 .codegraph
 .superpowers
+.worktrees
 .migration

 # Local Storage Data
@@ -67,3 +68,4 @@ ds-bundle/
 packages/ui/.ds-compiled.css
 packages/ui/.ds-tw-raw.css
 packages/ui/dist/
+i18n.cache
@@ -0,0 +1,31 @@
+config:
+  default: true
+  MD007: false
+  MD009: false
+  MD010: false
+  MD012: false
+  MD013: false
+  MD001: false
+  MD022: false
+  MD024: false
+  MD025: false
+  MD028: false
+  MD031: false
+  MD032: false
+  MD033: false
+  MD034: false
+  MD036: false
+  MD040: false
+  MD041: false
+  MD046: false
+  MD060: false
+
+frontMatter: "^---[\\s\\S]*?---"
+gitignore: true
+globs:
+  - "**/*.{md,mdx}"
+ignores:
+  - ".design-sync/**"
+  - "node_modules/**"
+  - ".turbo/**"
+  - "dist/**"
@@ -0,0 +1,23 @@
+# Task 1: Harden public PDF response contract
+
+## Implemented
+
+- Pinned successful public PDF responses to `Content-Type: application/pdf` at the HTTP boundary.
+- Kept `Cache-Control: private, no-store` hardcoded at that boundary for successful, validation-error, and service-error responses.
+- Removed the unused `cacheControl` member from `createPublicResumePdf` and all affected tests/mocks.
+- Updated the route regression to return a `text/plain` file from the service mock while asserting the HTTP response remains `application/pdf`.
+
+## Verification
+
+- `pnpm --filter server test -- src/http/public-resume-pdf.test.ts` — 13 files / 71 tests passed.
+- `dotenvx run -f .env.local -- pnpm exec vitest run packages/api/src/features/resume/public-pdf.test.ts` — 1 file / 7 tests passed.
+- `pnpm exec biome check apps/server/src/http/public-resume-pdf.ts apps/server/src/http/public-resume-pdf.test.ts packages/api/src/features/resume/public-pdf.ts packages/api/src/features/resume/public-pdf.test.ts` — passed.
+- `pnpm --filter server typecheck` and `pnpm --filter @reactive-resume/api typecheck` — passed.
+
+## Note
+
+The API package test script did not scope to the supplied test path and initially ran the package suite, which has two unrelated baseline failures: `src/features/ai/url-policy.test.ts` and `src/features/resume/export.test.ts` (missing required env). The target test was then run directly with `.env.local` and passed.
+
+## Self-review
+
+`git diff --check` passed. The diff is restricted to the public PDF service contract, HTTP response header, and their focused tests.
@@ -12,7 +12,7 @@ Internal packages are source-consumed through `package.json` export maps that po

 - **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`). Use `nvm install 24 && nvm use 24` if needed.
 - **Docker** is required to run PostgreSQL. Start it with `sudo dockerd &` if the daemon isn't running.
- **pnpm 11.1.2** is managed via corepack (`corepack enable`).
+- **pnpm 11.21.0**. Install pnpm directly using the [official installation guide](https://pnpm.io/installation).

 ### Codebase map

@@ -107,7 +107,7 @@ The production server runs migrations during startup before serving traffic. Man

 ### Environment

-Copy `.env.example` to `.env`. The three required variables are:
+Copy `.env.example` to `.env.local`. The three required variables are:

 - `APP_URL` (default `http://localhost:3000`)
 - `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
@@ -115,6 +115,8 @@ Copy `.env.example` to `.env`. The three required variables are:

 S3/SeaweedFS is optional. If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. The checked-in `.env.example` sets SeaweedFS defaults, so either start the `seaweedfs` compose service too or comment out those S3 vars to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.

+`REDIS_URL` and `ENCRYPTION_SECRET` are optional for core resume flows, but both are required for saved AI providers and the authenticated `/agent` workspace. Start the `redis` compose service and set both vars in `.env.local` when working on those features. For host-run development, use `REDIS_URL=redis://localhost:6379`; the container-run app uses `REDIS_URL=redis://redis:6379`.
+
 When running dev servers or migration commands, prefix the command with `dotenvx run -f .env.local --`. For example: `dotenvx run -f .env.local -- pnpm dev`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not need this prefix by default. If one of those commands fails because a specific environment variable is required, rerun it with the `dotenvx run -f .env.local --` prefix.

 ### Common commands
@@ -124,6 +126,7 @@ When running dev servers or migration commands, prefix the command with `dotenvx
 | Install deps | `pnpm install` |
 | Start Postgres only | `sudo docker compose -f compose.dev.yml up -d postgres` |
 | Start Postgres + SeaweedFS | `sudo docker compose -f compose.dev.yml up -d postgres seaweedfs seaweedfs_create_bucket` |
+| Start full dev infrastructure | `sudo docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket` |
 | Generate migrations | `dotenvx run -f .env.local -- pnpm db:generate` |
 | Run migrations | `dotenvx run -f .env.local -- pnpm db:migrate` |
 | Dev server | `dotenvx run -f .env.local -- pnpm dev` (starts on port 3000) |
@@ -1,17 +1,17 @@
 # syntax=docker/dockerfile:1.7

+ARG PNPM_VERSION=11.21.0
 ARG NODE_VERSION=24

-FROM node:${NODE_VERSION}-slim AS base
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS base
+
+ARG NODE_VERSION
+
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store

 WORKDIR /app

-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
-    PNPM_HOME="/pnpm" \
-    PATH="/pnpm:$PATH" \
-    TURBO_TELEMETRY_DISABLED=1
-
-RUN corepack enable
+ENV TURBO_TELEMETRY_DISABLED=1

 FROM base AS pruner
 COPY . .
@@ -1,19 +1,19 @@
 # syntax=docker/dockerfile:1.7

+ARG PNPM_VERSION=11.21.0
 ARG NODE_VERSION=24

-FROM node:${NODE_VERSION}-slim AS dev
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS dev
+
+ARG NODE_VERSION
+
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store

 WORKDIR /app

-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
-	PNPM_HOME="/pnpm" \
-	PATH="/pnpm:$PATH" \
-	NODE_ENV=development \
+ENV NODE_ENV=development \
 	TURBO_TELEMETRY_DISABLED=1

-RUN corepack enable
-
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
 COPY patches ./patches
 COPY apps/server/package.json ./apps/server/package.json
@@ -60,7 +60,7 @@ If your company would like to sponsor Reactive Resume, email [hello@amruthpillai
 - Professionally designed templates
 - A4 and Letter size support
 - Customizable colors, fonts, and spacing
- Custom CSS for advanced styling
+- Structured Style Rules for section and text styling

 **Privacy & Control**

@@ -240,11 +240,11 @@ Other ways to support:

 ## Star History

-<a href="https://www.star-history.com/#amruthpillai/reactive-resume&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=amruthpillai%2Freactive-resume&type=date&legend=top-left">
 <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left&sealed_token=BF8sVMes0z5BhdkMhtFklhxeikeGUrSyW-CcY9E_RCQI5zqUHEbMRwcB075fUewbAtlNoCnDlWhDWjrDGhTcXMojsS2I0RCqcL-Y9p3Ez3H1A2QpRMthjFilP0YOCJEE9AZqRrqzlvj1uU2y5ixarXOuUXuuSw5DkLMViSMD8Ldl0H3BEgclnjWw4fI4" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&legend=top-left&sealed_token=BF8sVMes0z5BhdkMhtFklhxeikeGUrSyW-CcY9E_RCQI5zqUHEbMRwcB075fUewbAtlNoCnDlWhDWjrDGhTcXMojsS2I0RCqcL-Y9p3Ez3H1A2QpRMthjFilP0YOCJEE9AZqRrqzlvj1uU2y5ixarXOuUXuuSw5DkLMViSMD8Ldl0H3BEgclnjWw4fI4" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&legend=top-left&sealed_token=BF8sVMes0z5BhdkMhtFklhxeikeGUrSyW-CcY9E_RCQI5zqUHEbMRwcB075fUewbAtlNoCnDlWhDWjrDGhTcXMojsS2I0RCqcL-Y9p3Ez3H1A2QpRMthjFilP0YOCJEE9AZqRrqzlvj1uU2y5ixarXOuUXuuSw5DkLMViSMD8Ldl0H3BEgclnjWw4fI4" />
 </picture>
 </a>

@@ -7,6 +7,7 @@
 		"dev": "tsx watch src/index.ts",
 		"build": "tsdown",
 		"start": "node dist/index.mjs",
+		"docs:gen": "tsx src/openapi/generate-spec.ts",
 		"typecheck": "tsgo --noEmit",
 		"test": "vitest run --passWithNoTests",
 		"test:coverage": "vitest run --coverage --passWithNoTests",
@@ -17,53 +18,67 @@
 		"#react-pdf-renderer": "@react-pdf/renderer"
 	},
 	"dependencies": {
-		"@ai-sdk/anthropic": "^4.0.8",
-		"@ai-sdk/google": "^4.0.8",
-		"@ai-sdk/openai": "^4.0.7",
-		"@ai-sdk/openai-compatible": "^3.0.5",
-		"@aws-sdk/client-s3": "^3.1079.0",
-		"@better-auth/api-key": "^1.6.23",
-		"@better-auth/drizzle-adapter": "^1.6.23",
-		"@better-auth/infra": "^0.3.4",
-		"@better-auth/oauth-provider": "^1.6.23",
-		"@better-auth/passkey": "^1.6.23",
-		"@hono/node-server": "^2.0.8",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@orpc/client": "^1.14.6",
-		"@orpc/experimental-ratelimit": "^1.14.6",
-		"@orpc/json-schema": "^1.14.6",
-		"@orpc/openapi": "^1.14.6",
-		"@orpc/server": "^1.14.6",
-		"@orpc/zod": "^1.14.6",
-		"@react-pdf/renderer": "^4.5.1",
+		"@ai-sdk/anthropic": "^4.0.36",
+		"@ai-sdk/cerebras": "^3.0.28",
+		"@ai-sdk/cohere": "^4.0.25",
+		"@ai-sdk/deepseek": "^3.0.26",
+		"@ai-sdk/fireworks": "^3.0.30",
+		"@ai-sdk/google": "^4.0.39",
+		"@ai-sdk/groq": "^4.0.26",
+		"@ai-sdk/mistral": "^4.0.27",
+		"@ai-sdk/openai": "^4.0.36",
+		"@ai-sdk/openai-compatible": "^3.0.28",
+		"@ai-sdk/perplexity": "^4.0.27",
+		"@ai-sdk/togetherai": "^3.0.29",
+		"@ai-sdk/xai": "^4.0.33",
+		"@aws-sdk/client-s3": "^3.1106.0",
+		"@better-auth/api-key": "^1.6.26",
+		"@better-auth/drizzle-adapter": "^1.6.26",
+		"@better-auth/infra": "^0.3.7",
+		"@better-auth/oauth-provider": "^1.6.26",
+		"@better-auth/passkey": "^1.6.26",
+		"@bramus/specificity": "^2.4.2",
+		"@hono/node-server": "^2.1.0",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@orpc/client": "^1.15.0",
+		"@orpc/experimental-ratelimit": "^1.15.0",
+		"@orpc/json-schema": "^1.15.0",
+		"@orpc/openapi": "^1.15.0",
+		"@orpc/server": "^1.15.0",
+		"@orpc/zod": "^1.15.0",
+		"@react-pdf/renderer": "^4.6.0",
 		"@reactive-resume/api": "workspace:*",
 		"@reactive-resume/auth": "workspace:*",
 		"@reactive-resume/db": "workspace:*",
 		"@reactive-resume/env": "workspace:*",
 		"@reactive-resume/mcp": "workspace:*",
+		"@reactive-resume/pdf": "workspace:*",
 		"@reactive-resume/schema": "workspace:*",
 		"@reactive-resume/utils": "workspace:*",
 		"@sindresorhus/slugify": "^3.0.0",
 		"@t3-oss/env-core": "^0.13.11",
 		"@uiw/color-convert": "^2.10.3",
-		"ai": "^7.0.15",
+		"ai": "^7.0.58",
 		"bcrypt": "^6.0.0",
-		"better-auth": "1.6.23",
+		"better-auth": "1.6.26",
+		"canonicalize": "^3.0.0",
 		"cjk-regex": "^3.4.0",
+		"css-tree": "^3.2.1",
 		"deepmerge-ts": "^7.1.5",
 		"drizzle-orm": "1.0.0-rc.4",
 		"drizzle-zod": "1.0.0-beta.14-a36c63d",
-		"es-toolkit": "^1.49.0",
+		"es-toolkit": "^1.50.0",
 		"fast-json-patch": "^3.1.1",
-		"hono": "^4.12.27",
+		"hono": "^4.13.1",
 		"jsonrepair": "^3.15.0",
-		"node-html-parser": "^8.0.4",
-		"nodemailer": "^9.0.3",
-		"ollama-ai-provider-v2": "^3.6.0",
-		"pg": "^8.22.0",
+		"node-html-parser": "^9.0.1",
+		"nodemailer": "^9.0.5",
+		"ollama-ai-provider-v2": "^4.0.1",
+		"pdfjs-dist": "^6.2.108",
+		"pg": "^8.23.0",
 		"phosphor-icons-react-pdf": "^0.1.3",
-		"react": "^19.2.7",
-		"react-email": "^6.6.6",
+		"react": "^19.2.8",
+		"react-email": "^6.9.2",
 		"react-pdf-html": "^2.1.5",
 		"resumable-stream": "^2.2.12",
 		"sharp": "^0.35.3",
@@ -74,13 +89,13 @@
 	},
 	"devDependencies": {
 		"@reactive-resume/config": "workspace:*",
-		"@types/node": "^26.1.0",
-		"@types/pg": "^8.20.0",
-		"@types/react": "^19.2.17",
-		"@typescript/native-preview": "7.0.0-dev.20260704.1",
-		"tsdown": "^0.22.3",
-		"tsx": "^4.23.0",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.9"
+		"@types/node": "^26.2.0",
+		"@types/pg": "^8.21.0",
+		"@types/react": "^19.2.18",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"tsdown": "^0.22.14",
+		"tsx": "^4.23.12",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
 	}
 }
@@ -9,6 +9,7 @@ const mocks = vi.hoisted(() => ({
 	handleUpload: vi.fn(),
 	handleMcp: vi.fn(),
 	handleResumePdfDownload: vi.fn(),
+	handlePublicResumePdf: vi.fn(),
 	handleMcpServerCard: vi.fn(),
 	handleOAuthAuthorizationServer: vi.fn(),
 	handleOAuthProtectedResource: vi.fn(),
@@ -69,6 +70,15 @@ vi.mock("./resume-pdf", () => ({
 	handleResumePdfDownload: mocks.handleResumePdfDownload,
 }));

+vi.mock("./public-resume-pdf", () => ({
+	handlePublicResumePdf: mocks.handlePublicResumePdf,
+}));
+
+const transportEnv = (remoteAddress: string) =>
+	({
+		incoming: { socket: { remoteAddress } },
+	}) as never;
+
 beforeEach(() => {
 	vi.clearAllMocks();
 	mocks.handleAuth.mockResolvedValue(new Response("auth"));
@@ -79,6 +89,7 @@ beforeEach(() => {
 	mocks.handleUpload.mockResolvedValue(new Response("upload"));
 	mocks.handleMcp.mockResolvedValue(new Response("mcp"));
 	mocks.handleResumePdfDownload.mockResolvedValue(new Response("pdf"));
+	mocks.handlePublicResumePdf.mockResolvedValue(new Response("public-pdf"));
 	mocks.handleMcpServerCard.mockReturnValue(new Response("server-card"));
 	mocks.handleOAuthAuthorizationServer.mockReturnValue(new Response("oauth-authorization-server"));
 	mocks.handleOAuthProtectedResource.mockReturnValue(new Response("oauth-protected-resource"));
@@ -117,6 +128,51 @@ describe("createApp", () => {
 		expect(mocks.handleWebApp).not.toHaveBeenCalled();
 	});

+	it("uses the transport address for public PDF fallback despite rotated forwarding headers", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const first = new Request("http://localhost:3001/api/resumes/jane/resume/pdf?reason=render-data-hash", {
+			headers: { "x-forwarded-for": "198.51.100.1" },
+		});
+		const rotated = new Request("http://localhost:3001/api/resumes/jane/resume/pdf?reason=render-data-hash", {
+			headers: { "x-forwarded-for": "198.51.100.2" },
+		});
+		const env = transportEnv("203.0.113.9");
+
+		const response = await app.fetch(first, env);
+		await app.fetch(rotated, env);
+
+		await expect(response.text()).resolves.toBe("public-pdf");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(1, first, "jane", "resume", "203.0.113.9");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(2, rotated, "jane", "resume", "203.0.113.9");
+		expect(mocks.handleResumePdfDownload).not.toHaveBeenCalled();
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("passes the transport address to RPC and OpenAPI and fails closed when it is unavailable", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const trustedRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.1" },
+		});
+		const unknownRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.2" },
+		});
+		const trustedOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume/style-projection");
+		const unknownOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume/style-projection");
+
+		await app.fetch(trustedRpcRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownRpcRequest);
+		await app.fetch(trustedOpenApiRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownOpenApiRequest);
+
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(1, trustedRpcRequest, "203.0.113.9");
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(2, unknownRpcRequest, "unknown");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(1, trustedOpenApiRequest, "203.0.113.9");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
+	});
+
 	it.each([
 		["GET", "/robots.txt", "robots", mocks.handleRobots],
 		["HEAD", "/robots.txt", "", mocks.handleRobots],
@@ -1,3 +1,7 @@
+import type { Http2Bindings, HttpBindings } from "@hono/node-server";
+import type { Context } from "hono";
+import { isIP } from "node:net";
+import { getConnInfo } from "@hono/node-server/conninfo";
 import { Hono } from "hono";
 import { handleMcp } from "../mcp/handler";
 import { handleOpenApi } from "../openapi/handler";
@@ -15,18 +19,33 @@ import { handleUpload } from "../static/uploads";
 import { handleWebApp, serveWebDistStatic } from "../static/web";
 import { handleAuth, handleOAuth } from "./auth";
 import { handleHealth } from "./health";
+import { handlePublicResumePdf } from "./public-resume-pdf";
 import { handleResumePdfDownload } from "./resume-pdf";

-export function createApp() {
-	const app = new Hono();
+type ServerEnvironment = { Bindings: HttpBindings | Http2Bindings };

-	app.all("/api/rpc", (c) => handleRpc(c.req.raw));
-	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw));
-	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw));
-	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw));
+const getTrustedClient = (context: Context<ServerEnvironment>): string => {
+	try {
+		const address = getConnInfo(context).remote.address?.trim();
+		return address && isIP(address) ? address : "unknown";
+	} catch {
+		return "unknown";
+	}
+};
+
+export function createApp() {
+	const app = new Hono<ServerEnvironment>();
+
+	app.all("/api/rpc", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
 	app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
 	app.all("/api/auth/*", (c) => handleAuth(c.req.raw));
 	app.get("/api/health", () => handleHealth());
+	app.get("/api/resumes/:username/:slug/pdf", (c) =>
+		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), getTrustedClient(c)),
+	);
 	app.get("/api/resumes/:id/pdf", (c) => handleResumePdfDownload(c.req.raw, c.req.param("id")));
 	app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
 	app.get("/uploads/*", (c) => handleUpload(c.req.raw));
@@ -37,9 +37,7 @@ async function checkDatabase() {
 	return { status: "healthy" };
 }

-async function checkStorage() {
-	return getStorageService().healthcheck();
-}
+const checkStorage = () => getStorageService().healthcheck();

 export async function handleHealth() {
 	const [database, storage] = await Promise.all([runCheck(checkDatabase), runCheck(checkStorage)]);
@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	createPublicResumePdf: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/public-pdf", () => ({
+	createPublicResumePdf: mocks.createPublicResumePdf,
+	PUBLIC_RESUME_PDF_MISMATCH_REASONS: [
+		"missing-projection",
+		"format-version",
+		"language-version",
+		"semantic-tree-version",
+		"registry-fingerprint",
+		"adapter-fingerprint",
+		"render-data-hash",
+		"invalid-projection",
+	],
+}));
+
+const { handlePublicResumePdf } = await import("./public-resume-pdf");
+const trustedClient = "203.0.113.9";
+
+describe("handlePublicResumePdf", () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it("returns the authorized fallback PDF with strict mismatch metadata and cache policy", async () => {
+		const body = new File(["%PDF"], "Ada_Lovelace.pdf", { type: "text/plain" });
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body,
+			filename: "Ada_Lovelace.pdf",
+		});
+		const registry = "0".repeat(64);
+		const adapter = "1".repeat(64);
+		const request = new Request(
+			`https://example.com/api/resumes/jane/resume/pdf?reason=render-data-hash&registryFingerprint=${registry}&adapterFingerprint=${adapter}`,
+			{ headers: { "x-forwarded-for": "203.0.113.7" } },
+		);
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/pdf");
+		expect(response.headers.get("Content-Disposition")).toBe('inline; filename="Ada_Lovelace.pdf"');
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(await response.text()).toBe("%PDF");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+			mismatchReason: "render-data-hash",
+			clientRegistryFingerprint: registry,
+			clientAdapterFingerprint: adapter,
+		});
+	});
+
+	it("defaults a missing mismatch reason and keeps password/private responses uncacheable", async () => {
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body: new File(["%PDF"], "resume.pdf", { type: "application/pdf" }),
+			filename: "resume.pdf",
+		});
+		const request = new Request("https://example.com/api/resumes/jane/resume/pdf");
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith(
+			expect.objectContaining({ mismatchReason: "missing-projection" }),
+		);
+	});
+
+	it.each([
+		[{ code: "BAD_REQUEST" }, 400],
+		[{ code: "NEED_PASSWORD" }, 401],
+		[{ code: "NOT_FOUND" }, 404],
+		[{ code: "RATE_LIMIT_EXCEEDED" }, 429],
+		[{ code: "INTERNAL_SERVER_ERROR" }, 500],
+	])("maps controlled API errors without caching the response", async (error, status) => {
+		mocks.createPublicResumePdf.mockRejectedValueOnce(error);
+
+		const response = await handlePublicResumePdf(
+			new Request("https://example.com/api/resumes/jane/resume/pdf"),
+			"jane",
+			"resume",
+			trustedClient,
+		);
+
+		expect(response.status).toBe(status);
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+	});
+
+	it.each(["?reason=private-source", "?registryFingerprint=unsafe", "?adapterFingerprint=unsafe"])(
+		"rejects invalid fallback metadata before the API service",
+		async (search) => {
+			const response = await handlePublicResumePdf(
+				new Request(`https://example.com/api/resumes/jane/resume/pdf${search}`),
+				"jane",
+				"resume",
+				trustedClient,
+			);
+
+			expect(response.status).toBe(400);
+			expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+			expect(mocks.createPublicResumePdf).not.toHaveBeenCalled();
+		},
+	);
+});
@@ -0,0 +1,72 @@
+import type { PublicResumePdfMismatchReason } from "@reactive-resume/api/features/resume/public-pdf";
+import {
+	createPublicResumePdf,
+	PUBLIC_RESUME_PDF_MISMATCH_REASONS,
+} from "@reactive-resume/api/features/resume/public-pdf";
+
+const noStoreResponse = (body: string, status: number) =>
+	new Response(body, { status, headers: { "Cache-Control": "private, no-store" } });
+
+const errorStatus = (error: unknown): number => {
+	const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+	if (code === "BAD_REQUEST") return 400;
+	if (code === "NEED_PASSWORD") return 401;
+	if (code === "NOT_FOUND") return 404;
+	if (code === "RATE_LIMIT_EXCEEDED") return 429;
+	return 500;
+};
+
+const fingerprint = (value: string | null): string | undefined => {
+	if (value === null) return;
+	return /^[a-f0-9]{64}$/.test(value) ? value : undefined;
+};
+
+export async function handlePublicResumePdf(
+	request: Request,
+	username: string,
+	slug: string,
+	trustedClient = "unknown",
+): Promise<Response> {
+	const searchParams = new URL(request.url).searchParams;
+	const rawReason = searchParams.get("reason") ?? "missing-projection";
+	if (!PUBLIC_RESUME_PDF_MISMATCH_REASONS.includes(rawReason as PublicResumePdfMismatchReason)) {
+		return noStoreResponse("Invalid fallback metadata", 400);
+	}
+	const rawRegistryFingerprint = searchParams.get("registryFingerprint");
+	const rawAdapterFingerprint = searchParams.get("adapterFingerprint");
+	const clientRegistryFingerprint = fingerprint(rawRegistryFingerprint);
+	const clientAdapterFingerprint = fingerprint(rawAdapterFingerprint);
+	if (
+		(rawRegistryFingerprint !== null && clientRegistryFingerprint === undefined) ||
+		(rawAdapterFingerprint !== null && clientAdapterFingerprint === undefined)
+	) {
+		return noStoreResponse("Invalid fallback metadata", 400);
+	}
+
+	try {
+		const result = await createPublicResumePdf({
+			username,
+			slug,
+			requestHeaders: request.headers,
+			trustedClient,
+			mismatchReason: rawReason as PublicResumePdfMismatchReason,
+			...(clientRegistryFingerprint ? { clientRegistryFingerprint } : {}),
+			...(clientAdapterFingerprint ? { clientAdapterFingerprint } : {}),
+		});
+
+		return new Response(result.body, {
+			headers: {
+				"Content-Type": "application/pdf",
+				"Content-Disposition": `inline; filename="${result.filename.replaceAll('"', "")}"`,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		const status = errorStatus(error);
+		return noStoreResponse(
+			status === 500 ? "Failed to generate public resume PDF" : "Public resume PDF unavailable",
+			status,
+		);
+	}
+}
@@ -23,6 +23,7 @@ describe("handleResumePdfDownload", () => {
 			ok: true,
 			resumeId: "resume-1",
 			userId: "user-1",
+			target: "resume",
 			expiresAt: "2026-06-01T10:10:00.000Z",
 		});
 		mocks.createResumePdfDownload.mockResolvedValueOnce({
@@ -49,6 +50,7 @@ describe("handleResumePdfDownload", () => {
 			ok: true,
 			resumeId: "resume-1",
 			userId: "user-1",
+			target: "cover-letter",
 			expiresAt: "2026-06-01T10:10:00.000Z",
 		});
 		mocks.createResumePdfDownload.mockResolvedValueOnce({
@@ -68,6 +70,62 @@ describe("handleResumePdfDownload", () => {
 		});
 	});

+	it("defaults a legacy token without a target to resume", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Cover Letter.pdf"' },
+			body: new File([], "Cover Letter.pdf", { type: "application/pdf" }),
+		});
+
+		await handleResumePdfDownload(new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy"), "resume-1");
+
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({
+			id: "resume-1",
+			userId: "user-1",
+			target: "resume",
+		});
+	});
+
+	it("rejects a cover-letter target for a legacy token without one", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+
+	it("rejects a target that differs from the signed token", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "resume",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+
 	it("rejects missing, invalid, and expired tokens before rendering", async () => {
 		let response = await handleResumePdfDownload(
 			new Request("https://example.com/api/resumes/resume-1/pdf"),
@@ -30,9 +30,16 @@ export async function handleResumePdfDownload(request: Request, id: string) {

 	const verification = verifyResumePdfDownloadToken({ resumeId: id, token });
 	if (!verification.ok) return verification.reason === "expired" ? expiredResponse() : unauthorizedResponse();
+	const queryTarget = searchParams.get("target");
+	if (
+		verification.target
+			? queryTarget !== null && queryTarget !== verification.target
+			: queryTarget && queryTarget !== "resume"
+	)
+		return unauthorizedResponse();

 	try {
-		const target = searchParams.get("target") === "cover-letter" ? "cover-letter" : "resume";
+		const target = verification.target ?? "resume";
 		const download = await createResumePdfDownload({ id, userId: verification.userId, target });

 		return new Response(download.body, {
@@ -2,6 +2,7 @@ import { pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { env } from "@reactive-resume/env/server";
 import { createApp } from "./http/app";
+import { stylesheetPreflightRunner } from "./services/stylesheet-preflight";
 import { runStartupChecks } from "./startup/checks";

 export { createApp } from "./http/app";
@@ -9,6 +10,14 @@ export { createApp } from "./http/app";
 async function main() {
 	await runStartupChecks();

+	// Safety net: Node 24 crashes the whole process on an unhandled rejection. One request's
+	// stray promise must not take the server down for everyone, so log and keep serving.
+	// Registered after startup checks so a broken startup still fails loudly. (Left uncaught
+	// exceptions on Node's default crash-and-restart, since process state is unsafe after one.)
+	process.on("unhandledRejection", (reason) => {
+		console.error("[unhandledRejection]", reason);
+	});
+
 	const port =
 		process.env.NODE_ENV === "production" ? Number.parseInt(process.env.PORT ?? "3000", 10) : env.SERVER_PORT;

@@ -23,6 +32,10 @@ async function main() {
 			console.info(`🚀 Up and running on http://localhost:${info.port}`);
 		},
 	);
+
+	// Load the heavy PDF preflight runtime once, now, so the first semantic-CSS edit
+	// does not pay (and time out on) the cold worker start.
+	stylesheetPreflightRunner.warmup();
 }

 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
@@ -1,5 +1,21 @@
 import { auth, verifyOAuthToken } from "@reactive-resume/auth/config";

+const OAUTH_WARN_THROTTLE_MS = 60_000;
+let lastOAuthWarnAt = 0;
+
+function warnOAuthThrottled(message: string, detail?: unknown): void {
+	const now = Date.now();
+	if (now - lastOAuthWarnAt < OAUTH_WARN_THROTTLE_MS) return;
+	lastOAuthWarnAt = now;
+
+	if (detail !== undefined) {
+		console.warn(message, detail);
+		return;
+	}
+
+	console.warn(message);
+}
+
 export class AuthError extends Error {
 	constructor() {
 		super("Unauthorized");
@@ -13,8 +29,9 @@ export async function authenticateRequest(request: Request): Promise<void> {
 		try {
 			const payload = await verifyOAuthToken(authHeader.slice(7));
 			if (payload?.sub) return;
-		} catch {
-			// Invalid or expired token; fall through to API key auth.
+			warnOAuthThrottled("[MCP] OAuth token verified but missing `sub` claim");
+		} catch (error) {
+			warnOAuthThrottled("[MCP] OAuth token verification failed:", error);
 		}
 	}

@@ -7,7 +7,7 @@ export async function handleMcp(request: Request) {
 	try {
 		await authenticateRequest(request);

-		const server = await createMcpServer(request);
+		const server = createMcpServer(request);
 		const transport = new WebStandardStreamableHTTPServerTransport({
 			enableJsonResponse: true,
 		});
@@ -22,7 +22,7 @@ function createRequestClient(request: Request): RouterClient<typeof router> {
 	});
 }

-export async function createMcpServer(request: Request) {
+export function createMcpServer(request: Request) {
 	const server = new McpServer(
 		{
 			name: "reactive-resume",
@@ -53,7 +53,7 @@ export async function createMcpServer(request: Request) {
 				`Read schema at \`resume://_meta/schema\`; read resume JSON via \`resume://{id}\` or \`${MCP_TOOL_NAME.getResume}\`.`,
 				`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
 				`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
-				`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`.`,
+				`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`; set target to \`cover-letter\` to export a visible cover letter separately.`,
 				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
 			].join(" "),
 		},
@@ -0,0 +1,20 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export async function generateOpenApiDocumentation(
+	target = fileURLToPath(new URL("../../../../docs/spec.json", import.meta.url)),
+) {
+	const packageJson = JSON.parse(await readFile(new URL("../../../../package.json", import.meta.url), "utf8")) as {
+		version: string;
+	};
+	process.env.APP_URL ??= "https://rxresu.me";
+	process.env.DATABASE_URL ??= "postgresql://localhost/reactive_resume_docs";
+	process.env.AUTH_SECRET ??= "documentation-generation-isolated-process-only";
+	const { generateOpenApiSpec } = await import("./generator");
+	const spec = await generateOpenApiSpec({ appUrl: "https://rxresu.me", version: packageJson.version });
+	await writeFile(target, `${JSON.stringify(spec, null, "\t")}\n`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+	await generateOpenApiDocumentation(process.argv[2]);
+}
@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+type GeneratedSpecView = {
+	components?: { schemas?: Record<string, unknown> };
+	paths?: Record<
+		string,
+		Record<
+			string,
+			{
+				requestBody?: {
+					content?: Record<string, { schema?: unknown }>;
+				};
+			}
+		>
+	>;
+};
+
+async function generateSpec() {
+	process.env.APP_URL ??= "https://rxresu.me";
+	process.env.DATABASE_URL ??= "postgresql://localhost/reactive_resume_test";
+	process.env.AUTH_SECRET ??= "openapi-generator-test-process-only";
+	const { generateOpenApiSpec } = await import("./generator");
+	return generateOpenApiSpec({
+		appUrl: "https://rxresu.me",
+		version: "9.8.7",
+	});
+}
+
+function getRequestSchema(spec: GeneratedSpecView, path: string, method: string) {
+	return spec.paths?.[path]?.[method]?.requestBody?.content?.["application/json"]?.schema;
+}
+
+function containsImpossibleSchema(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsImpossibleSchema);
+	if (typeof value !== "object" || value === null) return false;
+	const object = value as Record<string, unknown>;
+	const negated = object.not;
+	if (typeof negated === "object" && negated !== null && Object.keys(negated).length === 0) {
+		return true;
+	}
+	return Object.values(object).some(containsImpossibleSchema);
+}
+
+function findImpossibleRequestSchemas(spec: GeneratedSpecView) {
+	const impossibleRequests: string[] = [];
+	for (const [path, operations] of Object.entries(spec.paths ?? {})) {
+		for (const [method, operation] of Object.entries(operations)) {
+			for (const [mediaType, content] of Object.entries(operation.requestBody?.content ?? {})) {
+				if (containsImpossibleSchema(content.schema)) {
+					impossibleRequests.push(`${method.toUpperCase()} ${path} (${mediaType})`);
+				}
+			}
+		}
+	}
+	return impossibleRequests;
+}
+
+describe("generateOpenApiSpec", () => {
+	it("uses caller-provided application URL and version", async () => {
+		const spec = await generateSpec();
+
+		expect(spec.info).toMatchObject({
+			title: "Reactive Resume",
+			version: "9.8.7",
+		});
+		expect(spec.servers).toEqual([{ url: "https://rxresu.me/api/openapi" }]);
+		expect(spec.externalDocs).toEqual({
+			url: "https://docs.rxresu.me",
+			description: "Reactive Resume Documentation",
+		});
+	}, 15_000);
+
+	it("uses the canonical input-side ResumeData schema in update requests", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const { $schema: _dialect, ...canonicalInputSchema } = createResumeDataJsonSchema();
+
+		expect(spec.components?.schemas?.ResumeData).toEqual(canonicalInputSchema);
+		expect(getRequestSchema(spec, "/resumes/{id}", "put")).toMatchObject({
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+		});
+	});
+
+	it("publishes the custom-section type and item correlation", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const schema = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+
+	it("does not publish impossible request schemas", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual([]);
+	});
+
+	it("checks every request body media type for impossible schemas", () => {
+		const spec: GeneratedSpecView = {
+			paths: {
+				"/documents": {
+					post: {
+						requestBody: {
+							content: {
+								"application/json": { schema: { type: "object" } },
+								"multipart/form-data": { schema: { not: {} } },
+							},
+						},
+					},
+				},
+			},
+		};
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual(["POST /documents (multipart/form-data)"]);
+	});
+
+	it("documents imported data as an accepted ResumeData input", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(getRequestSchema(spec, "/resumes/import", "post")).toEqual({
+			type: "object",
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+			required: ["data"],
+		});
+	});
+});
@@ -0,0 +1,80 @@
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { JSON_SCHEMA_INPUT_REGISTRY, ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
+import router from "@reactive-resume/api/routers";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+export const openAPIRouter = {
+	...router,
+	resume: {
+		...router.resume,
+		downloadPdf: downloadResumePdfProcedure,
+	},
+};
+
+const { $schema: _dialect, ...resumeDataInputSchema } = createResumeDataJsonSchema();
+type ResumeDataInputJsonSchema = Parameters<typeof JSON_SCHEMA_INPUT_REGISTRY.add<typeof resumeDataSchema>>[1];
+JSON_SCHEMA_INPUT_REGISTRY.add(resumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
+const importResumeInputSchema = openAPIRouter.resume.import["~orpc"].inputSchema;
+if (importResumeInputSchema) {
+	JSON_SCHEMA_INPUT_REGISTRY.add(importResumeInputSchema, {
+		type: "object",
+		properties: {
+			data: { $ref: "#/components/schemas/ResumeData" },
+		},
+		required: ["data"],
+	});
+}
+
+const openAPIGenerator = new OpenAPIGenerator({
+	schemaConverters: [
+		new ZodToJsonSchemaConverter({
+			interceptors: [
+				({ options, next }) => {
+					const [required, schema] = next();
+					const impossible =
+						Object.keys(schema).length === 1 &&
+						typeof schema.not === "object" &&
+						schema.not !== null &&
+						Object.keys(schema.not).length === 0;
+					return options.strategy === "input" && impossible ? [required, {}] : [required, schema];
+				},
+			],
+		}),
+	],
+});
+
+type GenerateOpenApiSpecOptions = {
+	appUrl: string;
+	version: string;
+};
+
+export async function generateOpenApiSpec({ appUrl, version }: GenerateOpenApiSpecOptions) {
+	return await openAPIGenerator.generate(openAPIRouter, {
+		info: {
+			title: "Reactive Resume",
+			version,
+			description: "Reactive Resume API",
+			license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
+			contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
+		},
+		servers: [{ url: `${appUrl}/api/openapi` }],
+		externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
+		commonSchemas: {
+			ResumeData: { schema: resumeDataSchema, strategy: "input" },
+		},
+		components: {
+			securitySchemes: {
+				apiKey: {
+					type: "apiKey",
+					name: "x-api-key",
+					in: "header",
+					description: "The API key to authenticate requests.",
+				},
+			},
+		},
+		security: [{ apiKey: [] }],
+		filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
+	});
+}
@@ -1,24 +1,13 @@
 import { SmartCoercionPlugin } from "@orpc/json-schema";
-import { OpenAPIGenerator } from "@orpc/openapi";
 import { OpenAPIHandler } from "@orpc/openapi/fetch";
 import { onError } from "@orpc/server";
 import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
 import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
-import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
-import router from "@reactive-resume/api/routers";
 import { env } from "@reactive-resume/env/server";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
 import { appVersion } from "../app-version";
 import { mergeResponseHeaders } from "../http/headers";
 import { getRequestLocale } from "../rpc/locale";
-
-const openAPIRouter = {
-	...router,
-	resume: {
-		...router.resume,
-		downloadPdf: downloadResumePdfProcedure,
-	},
-};
+import { generateOpenApiSpec, openAPIRouter } from "./generator";

 const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
 	plugins: [
@@ -36,46 +25,15 @@ const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
 	],
 });

-const openAPIGenerator = new OpenAPIGenerator({
-	schemaConverters: [new ZodToJsonSchemaConverter()],
-});
-
-export async function handleOpenApi(request: Request) {
+export async function handleOpenApi(request: Request, trustedClient = "unknown") {
 	if (request.method === "GET" && (request.url.endsWith("/spec.json") || request.url.endsWith("/spec"))) {
-		const spec = await openAPIGenerator.generate(openAPIRouter, {
-			info: {
-				title: "Reactive Resume",
-				version: appVersion,
-				description: "Reactive Resume API",
-				license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
-				contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
-			},
-			servers: [{ url: `${env.APP_URL}/api/openapi` }],
-			externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
-			commonSchemas: {
-				ResumeData: { schema: resumeDataSchema },
-			},
-			components: {
-				securitySchemes: {
-					apiKey: {
-						type: "apiKey",
-						name: "x-api-key",
-						in: "header",
-						description: "The API key to authenticate requests.",
-					},
-				},
-			},
-			security: [{ apiKey: [] }],
-			filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
-		});
-
-		return Response.json(spec);
+		return Response.json(await generateOpenApiSpec({ appUrl: env.APP_URL, version: appVersion }));
 	}

 	const resHeaders = new Headers();
 	const { response } = await openAPIHandler.handle(request, {
 		prefix: "/api/openapi",
-		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders, trustedClient },
 	});

 	if (!response) return new Response("NOT_FOUND", { status: 404 });
@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	auth: {},
+	env: {
+		APP_URL: "https://rxresu.me",
+	},
+}));
+
+vi.mock("@better-auth/oauth-provider", () => ({
+	oauthProviderAuthServerMetadata: vi.fn(() => vi.fn(() => Response.json({}))),
+	oauthProviderOpenIdConfigMetadata: vi.fn(() => vi.fn(() => Response.json({}))),
+}));
+
+vi.mock("@reactive-resume/auth/config", () => ({
+	auth: mocks.auth,
+}));
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+vi.mock("@reactive-resume/mcp/server-card", () => ({
+	buildMcpServerCard: vi.fn(() => ({})),
+}));
+
+vi.mock("../app-version", () => ({
+	appVersion: "test",
+}));
+
+describe("handleOAuthProtectedResource", () => {
+	it("advertises the mounted auth issuer as the authorization server", async () => {
+		const { handleOAuthProtectedResource } = await import("./metadata");
+
+		const response = await handleOAuthProtectedResource();
+
+		await expect(response.json()).resolves.toMatchObject({
+			resource: "https://rxresu.me",
+			authorization_servers: ["https://rxresu.me/api/auth"],
+		});
+	});
+});
@@ -4,8 +4,8 @@ import { env } from "@reactive-resume/env/server";
 import { buildMcpServerCard } from "@reactive-resume/mcp/server-card";
 import { appVersion } from "../app-version";

-const oauthAuthorizationServerHandler = oauthProviderAuthServerMetadata(auth);
-const openIdConfigurationHandler = oauthProviderOpenIdConfigMetadata(auth);
+export const handleOAuthAuthorizationServer = oauthProviderAuthServerMetadata(auth);
+export const handleOpenIdConfiguration = oauthProviderOpenIdConfigMetadata(auth);

 export function handleWellKnownFallback() {
 	return new Response("OK", { status: 200 });
@@ -20,19 +20,11 @@ export function handleMcpServerCard() {
 	});
 }

-export function handleOAuthAuthorizationServer(request: Request) {
-	return oauthAuthorizationServerHandler(request);
-}
-
-export function handleOpenIdConfiguration(request: Request) {
-	return openIdConfigurationHandler(request);
-}
-
-export async function handleOAuthProtectedResource() {
+export function handleOAuthProtectedResource() {
 	const metadata = {
 		resource: env.APP_URL,
 		bearer_methods_supported: ["header"],
-		authorization_servers: [env.APP_URL, `${env.APP_URL}/api/auth`],
+		authorization_servers: [`${env.APP_URL}/api/auth`],
 	};

 	return Response.json(metadata, {
@@ -3,6 +3,7 @@ import { RPCHandler } from "@orpc/server/fetch";
 import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
 import router from "@reactive-resume/api/routers";
 import { mergeResponseHeaders } from "../http/headers";
+import { stylesheetPreflightRunner } from "../services/stylesheet-preflight";
 import { getRequestLocale } from "./locale";

 const rpcHandler = new RPCHandler(router, {
@@ -14,11 +15,17 @@ const rpcHandler = new RPCHandler(router, {
 	],
 });

-export async function handleRpc(request: Request) {
+export async function handleRpc(request: Request, trustedClient = "unknown") {
 	const resHeaders = new Headers();
 	const { response } = await rpcHandler.handle(request, {
 		prefix: "/api/rpc",
-		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+		context: {
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders,
+			trustedClient,
+			stylesheetPreflightRunner,
+		},
 	});

 	if (!response) return new Response("NOT_FOUND", { status: 404 });
@@ -0,0 +1,332 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { createStylesheetPreflightRunner, STYLESHEET_PREFLIGHT_LIMITS } from "./stylesheet-preflight";
+
+const validStylesheet = {
+	languageVersion: 1,
+	text: "@version 1;",
+} as const;
+
+const input = {
+	data: defaultResumeData,
+	template: defaultResumeData.metadata.template,
+	stylesheet: validStylesheet,
+} as const;
+
+// Runners now own a long-lived, reused worker; destroy them so no worker thread
+// outlives its test.
+const runners: Array<{ destroy(): Promise<void> }> = [];
+const track = <T extends { destroy(): Promise<void> }>(runner: T): T => {
+	runners.push(runner);
+	return runner;
+};
+afterEach(async () => {
+	await Promise.all(runners.splice(0).map((runner) => runner.destroy()));
+});
+
+const memoryExhaustionWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		const retained = [];
+		while (true) {
+			const batch = Array.from({ length: 100_000 }, (_, index) => ({ batch: retained.length, index }));
+			retained.push(batch);
+		}
+	`)}`,
+);
+
+const failedWorker = new URL(
+	`data:text/javascript,${encodeURIComponent('throw new Error("sensitive worker details");')}`,
+);
+
+// Counts how many preflights this single worker instance served so a reuse test
+// can prove the worker is not respawned per request.
+const reuseCountingWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort } from "node:worker_threads";
+		let served = 0;
+		parentPort.postMessage({ type: "ready" });
+		parentPort.on("message", (message) => {
+			if (message?.type !== "preflight") return;
+			served += 1;
+			parentPort.postMessage({
+				type: "result",
+				requestId: message.requestId,
+				result: { ok: true, pageCount: 1, byteCount: served, diagnostics: [] },
+			});
+		});
+	`)}`,
+);
+
+const delayedSuccessfulWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort } from "node:worker_threads";
+		parentPort.postMessage({ type: "ready" });
+		parentPort.on("message", (message) => {
+			if (message?.type !== "preflight") return;
+			setTimeout(() => {
+				parentPort.postMessage({
+					type: "result",
+					requestId: message.requestId,
+					result: {
+						ok: true,
+						pageCount: 1,
+						byteCount: Number(message.input.data.basics.name),
+						diagnostics: [],
+					},
+				});
+			}, 300);
+		});
+	`)}`,
+);
+
+const delayedReadyWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort } from "node:worker_threads";
+		parentPort.on("message", (message) => {
+			if (message?.type !== "preflight") return;
+			setTimeout(() => {
+				parentPort.postMessage({
+					type: "result",
+					requestId: message.requestId,
+					result: { ok: true, pageCount: 1, byteCount: 1, diagnostics: [] },
+				});
+			}, 10);
+		});
+		setTimeout(() => parentPort.postMessage({ type: "ready" }), 50);
+	`)}`,
+);
+
+const neverCompletesWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort } from "node:worker_threads";
+		parentPort.postMessage({ type: "ready" });
+		setInterval(() => {}, 1_000);
+	`)}`,
+);
+
+const synchronousFailureWorker = new URL("https://example.com/stylesheet-preflight.mjs");
+
+const numberedInput = (number: number) => ({
+	...input,
+	data: {
+		...input.data,
+		basics: {
+			...input.data.basics,
+			name: String(number),
+		},
+	},
+});
+
+const invalidInput = () => {
+	const data = structuredClone(defaultResumeData);
+	data.customSections = [
+		{
+			id: "custom-experience",
+			type: "experience",
+			title: "Experience",
+			icon: "",
+			columns: 1,
+			hidden: false,
+			keepTogether: false,
+			startOnNewPage: false,
+			items: [{ id: "summary-shaped-item", hidden: false, content: "<p>Missing company</p>" }],
+		} as never,
+	];
+	return { ...input, data };
+};
+
+describe("stylesheet PDF preflight worker", () => {
+	it("keeps the production resource policy fixed and immutable", () => {
+		expect(STYLESHEET_PREFLIGHT_LIMITS).toEqual({
+			timeoutMs: 30_000,
+			maxPages: 20,
+			maxBytes: 10_000_000,
+			maxPageWidthPt: 2_000,
+			maxPageHeightPt: 20_000,
+			maxPageAreaPt2: 20_000_000,
+			maxOldGenerationMb: 256,
+			maxConcurrentWorkers: 1,
+			maxQueuedRequests: 32,
+		});
+		expect(Object.isFrozen(STYLESHEET_PREFLIGHT_LIMITS)).toBe(true);
+	});
+
+	it("accepts a bounded candidate render in an isolated worker", async () => {
+		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 15_000 }));
+
+		const result = await runner.run(input);
+
+		expect(result).toEqual(
+			expect.objectContaining({
+				ok: true,
+				pageCount: 1,
+				byteCount: expect.any(Number),
+			}),
+		);
+		if (!result.ok) throw new Error(`Expected successful preflight, received ${result.code}.`);
+		expect(result.byteCount).toBeGreaterThan(0);
+		expect(runner.activeWorkerCount).toBe(0);
+	}, 45_000);
+
+	it("reuses one warm worker across sequential requests instead of cold-starting each one", async () => {
+		const runner = track(createStylesheetPreflightRunner({}, reuseCountingWorker));
+
+		const first = await runner.run(input);
+		const second = await runner.run(input);
+		const third = await runner.run(input);
+
+		// A single reused worker increments its per-instance counter; a per-request
+		// worker would report byteCount 1 every time.
+		expect([first, second, third].map((result) => (result.ok ? result.byteCount : -1))).toEqual([1, 2, 3]);
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	});
+
+	it("preserves structured resume-data failures across the worker boundary", async () => {
+		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 15_000 }));
+
+		const result = runner.run(invalidInput());
+
+		await expect(result).rejects.toMatchObject({
+			name: "ZodError",
+			issues: expect.arrayContaining([expect.objectContaining({ path: ["customSections", 0, "items", 0, "company"] })]),
+		});
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	}, 20_000);
+
+	it("terminates a worker when the render exceeds its deadline", async () => {
+		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 1 }, neverCompletesWorker));
+
+		const result = await runner.run(input);
+
+		expect(result).toEqual(expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_TIMEOUT" }));
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	});
+
+	it("starts the authored render deadline after the worker runtime is ready", async () => {
+		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 20 }, delayedReadyWorker));
+
+		await expect(runner.run(input)).resolves.toEqual(expect.objectContaining({ ok: true, pageCount: 1 }));
+		expect(runner.activeWorkerCount).toBe(0);
+	});
+
+	it("returns deterministic output byte and page limit codes", async () => {
+		const byteRunner = track(createStylesheetPreflightRunner({ maxBytes: 16 }));
+		const pageRunner = track(createStylesheetPreflightRunner({ maxPages: 0 }));
+
+		await expect(byteRunner.run(input)).resolves.toEqual(
+			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_BYTE_LIMIT" }),
+		);
+		await expect(pageRunner.run(input)).resolves.toEqual(
+			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_PAGE_LIMIT" }),
+		);
+		expect(byteRunner.activeWorkerCount).toBe(0);
+		expect(pageRunner.activeWorkerCount).toBe(0);
+	}, 30_000);
+
+	it("maps worker heap exhaustion to a controlled memory-limit result", async () => {
+		const runner = track(
+			createStylesheetPreflightRunner({ maxOldGenerationMb: 8, timeoutMs: 10_000 }, memoryExhaustionWorker),
+		);
+
+		const result = await runner.run(input);
+
+		expect(result).toEqual(expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_MEMORY_LIMIT" }));
+		expect(runner.activeWorkerCount).toBe(0);
+	}, 15_000);
+
+	it("does not expose internal errors from a failed worker bootstrap", async () => {
+		const runner = track(createStylesheetPreflightRunner({}, failedWorker));
+
+		const result = await runner.run(input);
+
+		expect(result).toEqual({
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
+			message: "The PDF preflight worker failed.",
+			diagnostics: [],
+		});
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	});
+
+	it("surfaces sanitized render failures from inside the worker catch path", async () => {
+		const throwingWorker = new URL(
+			`data:text/javascript,${encodeURIComponent(`
+				import { parentPort } from "node:worker_threads";
+				parentPort.postMessage({ type: "ready" });
+				parentPort.on("message", (message) => {
+					if (message?.type !== "preflight") return;
+					parentPort.postMessage({
+						type: "result",
+						requestId: message.requestId,
+						result: {
+							ok: false,
+							code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
+							message: "The PDF preflight worker failed. (Error: Canvas is already closed)",
+							diagnostics: [],
+						},
+					});
+				});
+			`)}`,
+		);
+		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 5_000 }, throwingWorker));
+
+		const result = await runner.run(input);
+
+		expect(result).toEqual({
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
+			message: "The PDF preflight worker failed. (Error: Canvas is already closed)",
+			diagnostics: [],
+		});
+	});
+
+	it("bounds concurrent workers and queued requests without charging queue time to the worker deadline", async () => {
+		const runner = track(
+			createStylesheetPreflightRunner(
+				{
+					timeoutMs: 500,
+					maxConcurrentWorkers: 1,
+					maxQueuedRequests: 2,
+				},
+				delayedSuccessfulWorker,
+			),
+		);
+		const completionOrder: number[] = [];
+		const accepted = [1, 2, 3].map((number) =>
+			runner.run(numberedInput(number)).then((result) => {
+				if (result.ok) completionOrder.push(result.byteCount);
+				return result;
+			}),
+		);
+		const rejected = runner.run(numberedInput(4));
+
+		expect(runner.activeWorkerCount).toBe(1);
+		expect(runner.queuedPreflightCount).toBe(2);
+		await expect(rejected).resolves.toEqual(
+			expect.objectContaining({
+				code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
+				message: "The PDF preflight queue is full.",
+			}),
+		);
+		const results = await Promise.all(accepted);
+
+		expect(results.every((result) => result.ok)).toBe(true);
+		expect(completionOrder).toEqual([1, 2, 3]);
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	}, 5_000);
+
+	it("does not leak a slot when the worker constructor throws synchronously", async () => {
+		const runner = track(createStylesheetPreflightRunner({}, synchronousFailureWorker));
+
+		await expect(runner.run(input)).resolves.toEqual(
+			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_WORKER_FAILED" }),
+		);
+		expect(runner.activeWorkerCount).toBe(0);
+		expect(runner.queuedPreflightCount).toBe(0);
+	});
+});
@@ -0,0 +1,362 @@
+import type {
+	PdfPreflightFailure,
+	PdfPreflightResult,
+	StylesheetPreflightInput,
+	StylesheetPreflightRunner,
+} from "@reactive-resume/pdf/server";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { STYLESHEET_PREFLIGHT_LIMITS } from "@reactive-resume/pdf/preflight-reference";
+
+export { STYLESHEET_PREFLIGHT_LIMITS } from "@reactive-resume/pdf/preflight-reference";
+
+type StylesheetPreflightLimits = {
+	timeoutMs: number;
+	maxPages: number;
+	maxBytes: number;
+	maxPageWidthPt: number;
+	maxPageHeightPt: number;
+	maxPageAreaPt2: number;
+	maxOldGenerationMb: number;
+	maxConcurrentWorkers: number;
+	maxQueuedRequests: number;
+};
+
+const SOURCE_WORKER_LOADER_HEAP_MB = 256;
+// The worker is warmed once and reused, so the one-time cold load (which is
+// super-linear in available CPU — measured ~9s at 0.5 vCPU, ~53s at 0.35, ~93s at
+// 0.25) is paid at startup, not per request. This ceiling must exceed that cold
+// load or warmup is killed mid-bootstrap and never completes on a throttled box;
+// it only bounds a genuinely stuck bootstrap and is off the per-edit path.
+const WORKER_READINESS_TIMEOUT_MS = 120_000;
+
+type SerializedPreflightCause = {
+	name: string;
+	message: string;
+	issues: readonly unknown[];
+};
+
+type StylesheetPreflightWorkerMessage =
+	| { type: "ready" }
+	| { type: "load_error"; message: string }
+	| { type: "result"; requestId: number; result: PdfPreflightResult }
+	| { type: "preflight_error"; requestId: number; cause: SerializedPreflightCause };
+
+export type NodeStylesheetPreflightRunner = StylesheetPreflightRunner & {
+	readonly activeWorkerCount: number;
+	readonly queuedPreflightCount: number;
+	warmup(): void;
+	destroy(): Promise<void>;
+};
+
+const failure = (code: PdfPreflightFailure["code"], message: string): PdfPreflightFailure => ({
+	ok: false,
+	code,
+	message,
+	diagnostics: [],
+});
+
+const workerFailure = (error: Error): PdfPreflightFailure => {
+	const code = (error as NodeJS.ErrnoException).code;
+	return code === "ERR_WORKER_OUT_OF_MEMORY" || /heap out of memory/i.test(error.message)
+		? failure("STYLESHEET_PREFLIGHT_MEMORY_LIMIT", "The PDF preflight worker exceeded its memory limit.")
+		: failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed.");
+};
+
+const sourceWorkerExecArgv = () => {
+	const importIndex = process.execArgv.findIndex(
+		(argument, index, arguments_) =>
+			(argument === "--import" && arguments_[index + 1]?.includes("tsx")) ||
+			(argument.startsWith("--import=") && argument.includes("tsx")),
+	);
+	const inherited = process.execArgv[importIndex];
+	if (inherited?.startsWith("--import=")) return [inherited];
+	if (inherited === "--import") return [inherited, process.execArgv[importIndex + 1] as string];
+	return ["--import", import.meta.resolve("tsx")];
+};
+
+const workerLocation = () => {
+	const source = import.meta.url.endsWith(".ts");
+	return {
+		source,
+		url: source
+			? new URL("../workers/stylesheet-preflight.ts", import.meta.url)
+			: new URL("./stylesheet-preflight-worker.mjs", import.meta.url),
+		// Production must not inherit parent execArgv (e.g. --import/--input-type); source workers need tsx.
+		execArgv: source ? sourceWorkerExecArgv() : [],
+		...(source
+			? {
+					env: {
+						...process.env,
+						TSX_TSCONFIG_PATH: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
+					},
+				}
+			: {}),
+	};
+};
+
+type PendingRequest = {
+	resolve: (result: PdfPreflightResult) => void;
+	reject: (cause: unknown) => void;
+	renderTimer?: ReturnType<typeof setTimeout>;
+};
+
+type Readiness = {
+	promise: Promise<Worker>;
+	resolve: (worker: Worker) => void;
+	reject: (error: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+};
+
+export function createStylesheetPreflightRunner(
+	overrides: Partial<StylesheetPreflightLimits> = {},
+	testWorkerUrl?: URL,
+): NodeStylesheetPreflightRunner {
+	const limits = Object.freeze({ ...STYLESHEET_PREFLIGHT_LIMITS, ...overrides });
+
+	let worker: Worker | undefined;
+	let ready = false;
+	let readiness: Readiness | undefined;
+	let destroyed = false;
+	let requestSeq = 0;
+
+	const pending = new Map<number, PendingRequest>();
+	// ponytail: process-local, bounded admission; upgrade to a pooled/distributed queue only for multi-process coordination.
+	const queue: Array<{
+		input: StylesheetPreflightInput;
+		resolve: PendingRequest["resolve"];
+		reject: PendingRequest["reject"];
+	}> = [];
+
+	const teardownWorker = () => {
+		const dead = worker;
+		worker = undefined;
+		ready = false;
+		if (readiness) {
+			clearTimeout(readiness.timer);
+			readiness.reject(new Error("Stylesheet preflight worker did not become ready."));
+			readiness = undefined;
+		}
+		if (!dead) return;
+		dead.off("message", onMessage);
+		dead.off("error", onError);
+		dead.off("exit", onExit);
+		void dead.terminate().catch(() => undefined);
+	};
+
+	const clearPending = (requestId: number): PendingRequest | undefined => {
+		const entry = pending.get(requestId);
+		if (!entry) return undefined;
+		if (entry.renderTimer) clearTimeout(entry.renderTimer);
+		pending.delete(requestId);
+		return entry;
+	};
+
+	const drainQueue = () => {
+		while (!destroyed && pending.size < limits.maxConcurrentWorkers && queue.length > 0) {
+			const next = queue.shift();
+			if (!next) return;
+			dispatch(next.input, next.resolve, next.reject);
+		}
+	};
+
+	const resolveRequest = (requestId: number, result: PdfPreflightResult) => {
+		const entry = clearPending(requestId);
+		if (!entry) return;
+		entry.resolve(result);
+		drainQueue();
+	};
+
+	const rejectRequest = (requestId: number, cause: unknown) => {
+		const entry = clearPending(requestId);
+		if (!entry) return;
+		entry.reject(cause);
+		drainQueue();
+	};
+
+	// A crashed/exited/timed-out worker is torn down and its in-flight requests are
+	// failed; the next dispatch (including any queued requests) spawns a fresh one,
+	// so a poisoned render never lingers across requests.
+	const failWorker = (result: PdfPreflightFailure) => {
+		teardownWorker();
+		const stale = [...pending.keys()];
+		for (const requestId of stale) resolveRequest(requestId, result);
+		drainQueue();
+	};
+
+	function onMessage(message: StylesheetPreflightWorkerMessage) {
+		if (message.type === "ready") {
+			if (readiness) {
+				clearTimeout(readiness.timer);
+				ready = true;
+				const resolveReady = readiness.resolve;
+				const readyWorker = worker;
+				readiness = undefined;
+				if (readyWorker) resolveReady(readyWorker);
+			}
+			return;
+		}
+		if (message.type === "load_error") {
+			failWorker(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", message.message));
+			return;
+		}
+		if (message.type === "result") {
+			resolveRequest(message.requestId, message.result);
+			return;
+		}
+		if (message.type === "preflight_error") {
+			rejectRequest(
+				message.requestId,
+				Object.assign(new Error(message.cause.message), { name: message.cause.name, issues: message.cause.issues }),
+			);
+		}
+	}
+
+	function onError(error: Error) {
+		console.warn("[stylesheet-preflight] worker error:", error.message);
+		failWorker(workerFailure(error));
+	}
+
+	function onExit(code: number) {
+		if (destroyed || (!worker && pending.size === 0)) return;
+		console.warn(`[stylesheet-preflight] worker exited unexpectedly (code ${code})`);
+		failWorker(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed."));
+	}
+
+	const startWorker = (): Promise<Worker> => {
+		const location = testWorkerUrl ? { source: false, url: testWorkerUrl, execArgv: [] as string[] } : workerLocation();
+		let spawned: Worker;
+		try {
+			spawned = new Worker(location.url, {
+				name: "stylesheet-preflight",
+				resourceLimits: {
+					// The source-only tsx compiler heap is outside the production render budget.
+					maxOldGenerationSizeMb: limits.maxOldGenerationMb + (location.source ? SOURCE_WORKER_LOADER_HEAP_MB : 0),
+				},
+				execArgv: location.execArgv,
+				...("env" in location ? { env: location.env } : {}),
+			});
+		} catch (error) {
+			return Promise.reject(error instanceof Error ? error : new Error("Failed to start PDF preflight worker."));
+		}
+
+		worker = spawned;
+		ready = false;
+		// The idle reused worker must not keep the process (or a test run) alive; active
+		// requests stay alive through their ref'd readiness/render timers.
+		spawned.unref();
+		spawned.on("message", onMessage);
+		spawned.once("error", onError);
+		spawned.once("exit", onExit);
+
+		let resolve!: (value: Worker) => void;
+		let reject!: (error: Error) => void;
+		const promise = new Promise<Worker>((resolvePromise, rejectPromise) => {
+			resolve = resolvePromise;
+			reject = rejectPromise;
+		});
+		const timer = setTimeout(() => {
+			console.warn(`[stylesheet-preflight] worker did not become ready within ${WORKER_READINESS_TIMEOUT_MS}ms`);
+			teardownWorker();
+		}, WORKER_READINESS_TIMEOUT_MS);
+		readiness = { promise, resolve, reject, timer };
+		return promise;
+	};
+
+	const getReadyWorker = (): Promise<Worker> => {
+		if (destroyed) return Promise.reject(new Error("Stylesheet preflight worker was terminated."));
+		if (worker && ready) return Promise.resolve(worker);
+		if (readiness) return readiness.promise;
+		return startWorker();
+	};
+
+	// One retry: a worker that failed to become ready is torn down; a second
+	// attempt spawns a fresh worker before the request gives up.
+	const waitUntilReady = async (): Promise<Worker> => {
+		try {
+			return await getReadyWorker();
+		} catch {
+			return await getReadyWorker();
+		}
+	};
+
+	function dispatch(
+		input: StylesheetPreflightInput,
+		resolve: PendingRequest["resolve"],
+		reject: PendingRequest["reject"],
+	) {
+		const requestId = ++requestSeq;
+		pending.set(requestId, { resolve, reject });
+		void waitUntilReady()
+			.then((readyWorker) => {
+				const entry = pending.get(requestId);
+				if (!entry) return;
+				entry.renderTimer = setTimeout(() => {
+					// A stuck render poisons the reused worker: tear it down and respawn — but
+					// only the worker this request actually ran on, so a stale timer can never
+					// kill a newer worker already serving other requests.
+					clearPending(requestId);
+					if (worker === readyWorker) teardownWorker();
+					resolve(failure("STYLESHEET_PREFLIGHT_TIMEOUT", "The PDF preflight exceeded its deadline."));
+					drainQueue();
+				}, limits.timeoutMs);
+				readyWorker.postMessage({ type: "preflight", requestId, input, limits });
+			})
+			.catch((error: unknown) => {
+				resolveRequest(
+					requestId,
+					workerFailure(error instanceof Error ? error : new Error("Failed to start PDF preflight worker.")),
+				);
+			});
+	}
+
+	return {
+		get activeWorkerCount() {
+			return pending.size;
+		},
+		get queuedPreflightCount() {
+			return queue.length;
+		},
+
+		warmup() {
+			void waitUntilReady().catch(() => undefined);
+		},
+
+		run(input: StylesheetPreflightInput): Promise<PdfPreflightResult> {
+			return new Promise<PdfPreflightResult>((resolve, reject) => {
+				if (destroyed) {
+					resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."));
+					return;
+				}
+				if (pending.size < limits.maxConcurrentWorkers) {
+					dispatch(input, resolve, reject);
+					return;
+				}
+				if (queue.length >= limits.maxQueuedRequests) {
+					resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight queue is full."));
+					return;
+				}
+				queue.push({ input, resolve, reject });
+			});
+		},
+
+		async destroy() {
+			destroyed = true;
+			const dead = worker;
+			teardownWorker();
+			await dead?.terminate().catch(() => undefined);
+			for (const requestId of [...pending.keys()]) {
+				resolveRequest(
+					requestId,
+					failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."),
+				);
+			}
+			while (queue.length > 0) {
+				const next = queue.shift();
+				next?.resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."));
+			}
+		},
+	};
+}
+
+export const stylesheetPreflightRunner = createStylesheetPreflightRunner();
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { handleSchemaJson } from "./schema";
+
+describe("handleSchemaJson", () => {
+	it("publishes the custom-section type and item correlation", async () => {
+		const response = handleSchemaJson();
+		const schema = z.fromJSONSchema((await response.json()) as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+});
@@ -1,11 +1,8 @@
-import z from "zod";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
 import { appVersion } from "../app-version";

 export function handleSchemaJson() {
-	const resumeDataJSONSchema = z.toJSONSchema(resumeDataSchema);
-
-	return Response.json(resumeDataJSONSchema, {
+	return Response.json(createResumeDataJsonSchema(), {
 		status: 200,
 		headers: {
 			"Content-Type": "application/schema+json; charset=utf-8",
@@ -33,6 +33,8 @@ describe("handleUpload", () => {
 		expect(response.status).toBe(200);
 		expect(readMock).toHaveBeenCalledWith("uploads/user-1/pictures/photo.jpeg");
 		expect(response.headers.get("Content-Type")).toBe("image/jpeg");
+		expect(response.headers.get("Cross-Origin-Resource-Policy")).toBe("same-site");
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBeNull();
 	});

 	it("does not serve private agent attachment keys through the public uploads route", async () => {
@@ -1,7 +1,6 @@
 import { createHash } from "node:crypto";
 import { basename, extname, normalize } from "node:path";
 import { getStorageService, inferContentType } from "@reactive-resume/api/features/storage";
-import { env } from "@reactive-resume/env/server";

 export async function handleUpload(request: Request) {
 	const { userId, filePath } = parseRouteParams(request.url);
@@ -41,7 +40,6 @@ export async function handleUpload(request: Request) {
 	headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
 	headers.set("X-Frame-Options", "DENY");
 	headers.set("X-Download-Options", "noopen");
-	headers.set("Access-Control-Allow-Origin", env.APP_URL);

 	return new Response(toArrayBuffer(storedFile.data), { headers });
 }
@@ -1,6 +1,11 @@
 import fs from "node:fs/promises";
 import { beforeEach, describe, expect, it, vi } from "vitest";

+const mocks = vi.hoisted(() => ({
+	env: { APP_URL: "https://rxresu.me" },
+	serveStatic: vi.fn((_options?: unknown) => vi.fn()),
+}));
+
 vi.mock("node:fs", () => ({
 	existsSync: vi.fn(() => true),
 }));
@@ -12,10 +17,25 @@ vi.mock("node:fs/promises", () => ({
 }));

 vi.mock("@hono/node-server/serve-static", () => ({
-	serveStatic: vi.fn(() => vi.fn()),
+	serveStatic: mocks.serveStatic,
 }));

+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+type StaticOptions = {
+	onFound?: (
+		path: string,
+		context: {
+			req: { path: string };
+			header: (name: string, value: string) => void;
+		},
+	) => void | Promise<void>;
+};
+
 const { handleWebApp } = await import("./web");
+const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | undefined;

 describe("web app fallback classification", () => {
 	beforeEach(() => {
@@ -32,22 +52,77 @@ describe("web app fallback classification", () => {
 		expect(await response.text()).toBe("<html>app</html>");
 	});

-	it.each([
-		"/auth/login",
-		"/dashboard",
-		"/builder/resume-1",
-		"/agent",
-		"/templates",
-		"/templates/azurill.pdf",
-	])("serves noindex shell for known app prefix %s", async (pathname) => {
+	it("injects canonical metadata and structured data into tracking-parameter root requests only", async () => {
+		vi.mocked(fs.readFile).mockResolvedValue(`
+			<!doctype html>
+			<html>
+				<head>
+					<title>Reactive Resume — A free and open-source resume builder</title>
+					<meta
+						name="description"
+						content="Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume."
+					>
+				</head>
+				<body><div id="app"></div></body>
+			</html>
+		`);
+
+		const response = await handleWebApp(new Request("http://server.internal/?utm_source=search"));
+		const html = await response.text();
+
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/">');
+		expect(html).toContain('<link rel="preload" href="/videos/timelapse-v1.webp" as="image" fetchpriority="high">');
+		expect(html).toContain('<meta property="og:url" content="https://rxresu.me/">');
+		expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
+		expect(html).toContain('id="reactive-resume-structured-data"');
+		expect(html).toContain('"@type":["SoftwareApplication","WebApplication"]');
+		expect(html).toContain('"url":"https://rxresu.me/"');
+		expect(html).not.toContain("utm_source");
+
+		const dashboardResponse = await handleWebApp(new Request("https://example.com/dashboard"));
+		expect(await dashboardResponse.text()).not.toContain('rel="canonical"');
+	});
+
+	it("caches versioned homepage media immutably", async () => {
+		const headers = new Headers();
+
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse-v1.mp4" },
+			header: (name, value) => headers.set(name, value),
+		});
+
+		expect(headers.get("Cache-Control")).toBe("public, max-age=31536000, immutable");
+
+		const unversionedHeaders = new Headers();
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse.mp4" },
+			header: (name, value) => unversionedHeaders.set(name, value),
+		});
+
+		expect(unversionedHeaders.get("Cache-Control")).toBeNull();
+	});
+
+	it.each(["/", "/alice/resume"])("sets framing and report-only CSP security headers on %s", async (pathname) => {
 		const response = await handleWebApp(new Request(`https://example.com${pathname}`));

 		expect(response.status).toBe(200);
-		expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
-		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
-		expect(await response.text()).toBe("<html>app</html>");
+		expect(response.headers.get("X-Frame-Options")).toBe("DENY");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(response.headers.get("Content-Security-Policy-Report-Only")).toContain("frame-ancestors 'none'");
 	});

+	it.each(["/auth/login", "/dashboard", "/builder/resume-1", "/agent", "/templates", "/templates/azurill.pdf"])(
+		"serves noindex shell for known app prefix %s",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+			expect(await response.text()).toBe("<html>app</html>");
+		},
+	);
+
 	it("serves noindex shell for public resume shaped routes", async () => {
 		const response = await handleWebApp(new Request("https://example.com/alice/resume"));

@@ -66,19 +141,18 @@ describe("web app fallback classification", () => {
 		expect(fs.readFile).not.toHaveBeenCalled();
 	});

-	it.each([
-		"/api/foo",
-		"/mcp/foo",
-		"/uploads/foo",
-	])("does not treat reserved two-segment path %s as a public resume", async (pathname) => {
-		const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+	it.each(["/api/foo", "/mcp/foo", "/uploads/foo"])(
+		"does not treat reserved two-segment path %s as a public resume",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));

-		expect(response.status).toBe(404);
-		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
-		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
-		expect(await response.text()).toBe("Not Found");
-		expect(fs.readFile).not.toHaveBeenCalled();
-	});
+			expect(response.status).toBe(404);
+			expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+			expect(await response.text()).toBe("Not Found");
+			expect(fs.readFile).not.toHaveBeenCalled();
+		},
+	);

 	it("returns plain 404 for missing asset-looking paths", async () => {
 		const response = await handleWebApp(new Request("https://example.com/assets/missing.css"));
@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { env } from "@reactive-resume/env/server";

 function resolveWebDistPath() {
 	const candidates = [
@@ -31,8 +32,6 @@ const reservedPublicResumeSegments = new Set([
 	"templates",
 ]);

-export const serveWebDistStatic = serveStatic({ root: staticRoot });
-
 function isAssetPath(pathname: string): boolean {
 	return pathname.split("/").pop()?.includes(".") ?? false;
 }
@@ -52,12 +51,130 @@ function isPublicResumePath(pathname: string): boolean {
 	return segments.length === 2 && firstSegment !== undefined && !reservedPublicResumeSegments.has(firstSegment);
 }

+const BASE_SECURITY_HEADERS = {
+	"X-Frame-Options": "DENY",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Content-Security-Policy-Report-Only":
+		"default-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+};
+
+const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder";
+const ROOT_DESCRIPTION =
+	"Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.";
+const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp";
+const ROOT_FAQ_ITEMS = [
+	{
+		question: "Is Reactive Resume really free?",
+		answer:
+			"Yes! Reactive Resume is completely free to use, with no hidden costs, premium tiers, or subscription fees. It's open-source and will always remain free.",
+	},
+	{
+		question: "How is my data protected?",
+		answer:
+			"Your data is stored securely and is never shared with third parties. You can also self-host Reactive Resume on your own servers for complete control over your data.",
+	},
+	{
+		question: "Can I export my resume to PDF?",
+		answer:
+			"Absolutely! You can export your resume to PDF with a single click. The exported PDF maintains all your formatting and styling perfectly.",
+	},
+	{
+		question: "Is Reactive Resume available in multiple languages?",
+		answer:
+			"Yes, Reactive Resume is available in multiple languages. You can choose your preferred language in the settings page, or using the language switcher in the top right corner. If you don't see your language, or you would like to improve the existing translations, you can contribute to the translations on Crowdin.",
+	},
+	{
+		question: "What makes Reactive Resume different from other resume builders?",
+		answer:
+			"Reactive Resume is open-source, privacy-focused, and completely free. Unlike other resume builders, it doesn't show ads, track your data, or limit your features behind a paywall.",
+	},
+	{
+		question: "How do I share my resume?",
+		answer:
+			"You can share your resume via a unique public URL, protect it with a password, or download it as a PDF to share directly. The choice is yours!",
+	},
+] as const;
+
+function createRootSeoMarkup(canonicalUrl: string) {
+	const origin = new URL(canonicalUrl).origin;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@graph": [
+			{
+				"@type": "WebSite",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+			},
+			{
+				"@type": ["SoftwareApplication", "WebApplication"],
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				description: ROOT_DESCRIPTION,
+				applicationCategory: "BusinessApplication",
+				operatingSystem: "Web",
+				isAccessibleForFree: true,
+				offers: {
+					"@type": "Offer",
+					price: "0",
+					priceCurrency: "USD",
+				},
+				codeRepository: "https://github.com/amruthpillai/reactive-resume",
+			},
+			{
+				"@type": "Project",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				sameAs: ["https://github.com/amruthpillai/reactive-resume"],
+			},
+			{
+				"@type": "FAQPage",
+				mainEntity: ROOT_FAQ_ITEMS.map((item) => ({
+					"@type": "Question",
+					name: item.question,
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: item.answer,
+					},
+				})),
+			},
+		],
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<link rel="preload" href="${ROOT_POSTER_PATH}" as="image" fetchpriority="high">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ROOT_TITLE}">
+		<meta property="og:description" content="${ROOT_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ROOT_TITLE}">
+		<meta name="twitter:description" content="${ROOT_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="reactive-resume-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+export const serveWebDistStatic = serveStatic({
+	root: staticRoot,
+	onFound: (_path, context) => {
+		if (/^\/videos\/.*-v\d+\.(?:mp4|webp)$/.test(context.req.path)) {
+			context.header("Cache-Control", "public, max-age=31536000, immutable");
+		}
+	},
+});
+
 function getFallbackResponseHeaders(pathname: string) {
-	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8" };
+	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
 	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
 		return {
 			"Content-Type": "text/html; charset=UTF-8",
 			"X-Robots-Tag": "noindex, follow",
+			...BASE_SECURITY_HEADERS,
 		};
 	}

@@ -89,5 +206,8 @@ export async function handleWebApp(request: Request) {
 	if (isHead) return new Response(null, { status: 200, headers });

 	const html = await fs.readFile(indexHtmlPath, "utf-8");
-	return new Response(html, { headers });
+	const canonicalUrl = new URL("/", env.APP_URL).toString();
+	const responseHtml = pathname === "/" ? html.replace("</head>", `${createRootSeoMarkup(canonicalUrl)}</head>`) : html;
+
+	return new Response(responseHtml, { headers });
 }
@@ -0,0 +1,78 @@
+import type {
+	PdfPreflightPageLimits,
+	PdfPreflightResult,
+	RenderPreflightPdfResult,
+} from "@reactive-resume/pdf/preflight";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+
+type StylesheetPreflightInspectionLimits = PdfPreflightPageLimits & {
+	maxPages: number;
+	maxBytes: number;
+};
+
+type PdfLoadingTask = {
+	promise: PromiseLike<{ numPages: number }>;
+	destroy(): Promise<void>;
+};
+
+type LoadPdf = (options: { data: Uint8Array }) => PdfLoadingTask;
+
+export async function inspectPreflightPdf(
+	rendered: Extract<RenderPreflightPdfResult, { ok: true }>,
+	limits: StylesheetPreflightInspectionLimits,
+	loadPdf: LoadPdf = getDocument,
+): Promise<PdfPreflightResult> {
+	if (rendered.bytes.byteLength > limits.maxBytes) {
+		return {
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_BYTE_LIMIT",
+			message: "The rendered PDF exceeds the preflight byte limit.",
+			diagnostics: rendered.diagnostics,
+		};
+	}
+
+	const byteCount = rendered.bytes.byteLength;
+	let loadingTask: PdfLoadingTask;
+	try {
+		loadingTask = loadPdf({ data: rendered.bytes });
+	} catch {
+		return {
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_PARSE_FAILED",
+			message: "PDF inspection failed.",
+			diagnostics: rendered.diagnostics,
+		};
+	}
+
+	try {
+		let document: { numPages: number };
+		try {
+			document = await loadingTask.promise;
+		} catch {
+			return {
+				ok: false,
+				code: "STYLESHEET_PREFLIGHT_PARSE_FAILED",
+				message: "PDF inspection failed.",
+				diagnostics: rendered.diagnostics,
+			};
+		}
+
+		if (document.numPages > limits.maxPages) {
+			return {
+				ok: false,
+				code: "STYLESHEET_PREFLIGHT_PAGE_LIMIT",
+				message: "The rendered PDF exceeds the preflight page limit.",
+				diagnostics: rendered.diagnostics,
+			};
+		}
+
+		return {
+			ok: true,
+			pageCount: document.numPages,
+			byteCount,
+			diagnostics: rendered.diagnostics,
+		};
+	} finally {
+		await loadingTask.destroy().catch(() => undefined);
+	}
+}
@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from "vitest";
+import { inspectPreflightPdf } from "./stylesheet-preflight-inspection";
+
+const warning = {
+	code: "EXTREME_VALUE",
+	severity: "warning",
+	message: "The authored value is unusually large.",
+	range: {
+		start: { line: 1, column: 1, offset: 0 },
+		end: { line: 1, column: 10, offset: 9 },
+	},
+} as const;
+
+const rendered = {
+	ok: true as const,
+	bytes: new TextEncoder().encode("%PDF-1.7"),
+	diagnostics: [warning],
+};
+
+const limits = {
+	maxPages: 20,
+	maxBytes: 10_000_000,
+	maxPageWidthPt: 2_000,
+	maxPageHeightPt: 20_000,
+	maxPageAreaPt2: 20_000_000,
+};
+
+describe("stylesheet preflight PDF inspection", () => {
+	it("preserves compiler warnings and hides parser exceptions", async () => {
+		const destroy = vi.fn(async () => undefined);
+
+		const result = await inspectPreflightPdf(rendered, limits, () => ({
+			promise: Promise.reject(new Error("sensitive parser details")),
+			destroy,
+		}));
+
+		expect(result).toEqual({
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_PARSE_FAILED",
+			message: "PDF inspection failed.",
+			diagnostics: [warning],
+		});
+		expect(destroy).toHaveBeenCalledOnce();
+	});
+
+	it("preserves compiler warnings when PDF.js fails before returning a loading task", async () => {
+		const result = await inspectPreflightPdf(rendered, limits, () => {
+			throw new Error("sensitive parser setup details");
+		});
+
+		expect(result).toEqual({
+			ok: false,
+			code: "STYLESHEET_PREFLIGHT_PARSE_FAILED",
+			message: "PDF inspection failed.",
+			diagnostics: [warning],
+		});
+	});
+});
@@ -0,0 +1,90 @@
+import type {
+	PdfPreflightPageLimits,
+	PdfPreflightResult,
+	StylesheetPreflightInput,
+} from "@reactive-resume/pdf/preflight";
+import { parentPort } from "node:worker_threads";
+import * as React from "react";
+import { inspectPreflightPdf } from "./stylesheet-preflight-inspection";
+
+(globalThis as typeof globalThis & { React: typeof React }).React = React;
+
+type StylesheetPreflightWorkerLimits = PdfPreflightPageLimits & {
+	maxPages: number;
+	maxBytes: number;
+};
+
+// The worker is long-lived and reused across requests: the heavy PDF runtime is
+// loaded once at startup and each preflight arrives as a message (input can no
+// longer come from `workerData`, which is fixed at construction time).
+type StylesheetPreflightWorkerRequest = {
+	type: "preflight";
+	requestId: number;
+	input: StylesheetPreflightInput;
+	limits: StylesheetPreflightWorkerLimits;
+};
+
+type SerializedPreflightCause = {
+	name: string;
+	message: string;
+	issues: readonly unknown[];
+};
+
+const sanitizeWorkerCause = (cause: unknown): string => {
+	if (!(cause instanceof Error)) return "The PDF preflight worker failed.";
+	const detail = cause.message.replace(/\s+/g, " ").trim().slice(0, 200);
+	if (!detail) return "The PDF preflight worker failed.";
+	return `The PDF preflight worker failed. (${cause.name}: ${detail})`;
+};
+
+const serializeZodCause = (cause: unknown): SerializedPreflightCause | undefined => {
+	if (!(cause instanceof Error) || cause.name !== "ZodError" || !("issues" in cause) || !Array.isArray(cause.issues)) {
+		return;
+	}
+	return { name: cause.name, message: cause.message, issues: cause.issues };
+};
+
+// Load the heavy PDF runtime once. A rejection here (missing/broken dependency in
+// a pruned production install) is reported explicitly instead of becoming an
+// unhandled rejection that silently kills the worker and surfaces as an opaque
+// runner-side failure.
+const initialization = import("@reactive-resume/pdf/preflight");
+
+void initialization.then(
+	() => parentPort?.postMessage({ type: "ready" }),
+	(cause: unknown) => {
+		console.error("[stylesheet-preflight] worker runtime failed to load", cause);
+		parentPort?.postMessage({ type: "load_error", message: sanitizeWorkerCause(cause) });
+	},
+);
+
+const handle = async (request: StylesheetPreflightWorkerRequest): Promise<void> => {
+	try {
+		const { renderPreflightPdf } = await initialization;
+		const rendered = await renderPreflightPdf(request.input, request.limits);
+		const result: PdfPreflightResult = rendered.ok ? await inspectPreflightPdf(rendered, request.limits) : rendered;
+		parentPort?.postMessage({ type: "result", requestId: request.requestId, result });
+	} catch (cause) {
+		const serializedCause = serializeZodCause(cause);
+		if (serializedCause) {
+			parentPort?.postMessage({ type: "preflight_error", requestId: request.requestId, cause: serializedCause });
+			return;
+		}
+		console.error("[stylesheet-preflight]", cause);
+		parentPort?.postMessage({
+			type: "result",
+			requestId: request.requestId,
+			result: {
+				ok: false,
+				code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
+				message: sanitizeWorkerCause(cause),
+				diagnostics: [],
+			},
+		});
+	}
+};
+
+parentPort?.on("message", (message: StylesheetPreflightWorkerRequest) => {
+	if (message.type !== "preflight") return;
+	void handle(message);
+});
@@ -33,7 +33,10 @@ const promptAssetsPlugin: TsdownPlugin = {
 };

 export default defineConfig({
-	entry: { index: "src/index.ts" },
+	entry: {
+		index: "src/index.ts",
+		"stylesheet-preflight-worker": "src/workers/stylesheet-preflight.ts",
+	},
 	format: "esm",
 	platform: "node",
 	target: "node24",
@@ -42,6 +45,9 @@ export default defineConfig({
 	shims: true,
 	dts: false,
 	define: { __APP_VERSION__: JSON.stringify(rootPackageJson.version ?? "0.0.0") },
+	// The flagged dynamic imports are deliberate: they defer evaluation of env-dependent
+	// modules so tests can run without env vars, not to split chunks.
+	suppressWarnings: [/dynamic import will not move module into another chunk/],
 	outExtensions: () => ({ js: ".mjs" }),
 	deps: {
 		alwaysBundle: [/^@reactive-resume\//],
@@ -1,4 +1,9 @@
 {
 	"extends": ["//"],
-	"tags": ["app:server", "runtime:server", "role:adapter"]
+	"tags": ["app:server", "runtime:server", "role:adapter"],
+	"tasks": {
+		"test:ci": {
+			"cache": false
+		}
+	}
 }
@@ -16,7 +16,7 @@
 		<link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png" type="image/png" sizes="180x180 any" />
 		<link rel="manifest" href="/manifest.webmanifest" crossorigin="use-credentials" />

-		<title>Reactive Resume</title>
+		<title>Reactive Resume — A free and open-source resume builder</title>
 	</head>
 	<body>
 		<!-- Keep #app empty: main.tsx only mounts React when rootElement has no children. -->
@@ -56,6 +56,6 @@
 				clip: rect(0 0 0 0);
 			}
 		</style>
-		<script type="module" src="/src/main.tsx"></script>
+		<script type="module" data-cfasync="false" src="/src/main.tsx"></script>
 	</body>
 </html>
@@ -16,22 +16,30 @@
 		"lingui:extract": "lingui extract --clean --overwrite"
 	},
 	"dependencies": {
-		"@ai-sdk/react": "^4.0.16",
-		"@base-ui/react": "^1.6.0",
-		"@better-auth/api-key": "^1.6.23",
-		"@better-auth/infra": "^0.3.4",
-		"@better-auth/oauth-provider": "^1.6.23",
-		"@better-auth/passkey": "^1.6.23",
+		"@ai-sdk/react": "^4.0.61",
+		"@base-ui/react": "^1.7.0",
+		"@better-auth/api-key": "^1.6.26",
+		"@better-auth/infra": "^0.3.7",
+		"@better-auth/oauth-provider": "^1.6.26",
+		"@better-auth/passkey": "^1.6.26",
+		"@codemirror/autocomplete": "^6.20.3",
+		"@codemirror/commands": "^6.10.4",
+		"@codemirror/lang-css": "^6.3.1",
+		"@codemirror/language": "^6.12.4",
+		"@codemirror/lint": "^6.9.7",
+		"@codemirror/search": "^6.7.1",
+		"@codemirror/state": "^6.7.1",
+		"@codemirror/view": "^6.43.8",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",
 		"@dnd-kit/utilities": "^3.2.2",
-		"@lingui/core": "^6.4.0",
-		"@lingui/react": "^6.4.0",
-		"@orpc/client": "^1.14.6",
-		"@orpc/server": "^1.14.6",
-		"@orpc/tanstack-query": "^1.14.6",
+		"@lingui/core": "^6.6.0",
+		"@lingui/react": "^6.6.0",
+		"@orpc/client": "^1.15.0",
+		"@orpc/server": "^1.15.0",
+		"@orpc/tanstack-query": "^1.15.0",
 		"@phosphor-icons/react": "^2.1.10",
-		"@react-pdf/renderer": "^4.5.1",
+		"@react-pdf/renderer": "^4.6.0",
 		"@reactive-resume/ai": "workspace:*",
 		"@reactive-resume/api": "workspace:*",
 		"@reactive-resume/auth": "workspace:*",
@@ -43,42 +51,44 @@
 		"@reactive-resume/schema": "workspace:*",
 		"@reactive-resume/ui": "workspace:*",
 		"@reactive-resume/utils": "workspace:*",
-		"@tailwindcss/vite": "^4.3.2",
-		"@tanstack/react-form": "^1.33.0",
+		"@tailwindcss/vite": "^4.3.3",
+		"@tanstack/react-form": "^1.33.4",
 		"@tanstack/react-hotkeys": "^0.10.0",
-		"@tanstack/react-query": "^5.101.2",
-		"@tanstack/react-router": "^1.170.17",
-		"@tiptap/extension-color": "^3.27.1",
-		"@tiptap/extension-highlight": "^3.27.1",
-		"@tiptap/extension-text-align": "^3.27.1",
-		"@tiptap/extension-text-style": "^3.27.1",
-		"@tiptap/pm": "^3.27.1",
-		"@tiptap/react": "^3.27.1",
-		"@tiptap/starter-kit": "^3.27.1",
+		"@tanstack/react-query": "^5.101.4",
+		"@tanstack/react-router": "^1.170.25",
+		"@tiptap/extension-color": "^3.29.2",
+		"@tiptap/extension-highlight": "^3.29.2",
+		"@tiptap/extension-text-align": "^3.29.2",
+		"@tiptap/extension-text-style": "^3.29.2",
+		"@tiptap/pm": "^3.29.2",
+		"@tiptap/react": "^3.29.2",
+		"@tiptap/starter-kit": "^3.29.2",
 		"@types/js-cookie": "^3.0.6",
 		"@uiw/color-convert": "^2.10.3",
 		"@uiw/react-color-colorful": "^2.10.3",
-		"ai": "^7.0.15",
-		"better-auth": "1.6.23",
+		"ai": "^7.0.58",
+		"better-auth": "1.6.26",
+		"buffer": "^6.0.3",
 		"cmdk": "^1.1.1",
 		"drizzle-orm": "1.0.0-rc.4",
-		"es-toolkit": "^1.49.0",
-		"fuse.js": "^7.4.2",
-		"immer": "^11.1.11",
+		"es-toolkit": "^1.50.0",
+		"fuse.js": "^7.5.0",
+		"immer": "^11.1.16",
 		"js-cookie": "^3.0.8",
-		"motion": "^12.42.2",
-		"pdfjs-dist": "6.1.200",
-		"pg": "^8.22.0",
+		"motion": "^13.0.0",
+		"pdfjs-dist": "6.2.108",
+		"pg": "^8.23.0",
+		"prettier": "^3.9.6",
 		"qrcode.react": "^4.2.0",
-		"react": "^19.2.7",
-		"react-dom": "^19.2.7",
-		"react-easy-crop": "^6.1.0",
+		"react": "^19.2.8",
+		"react-dom": "^19.2.8",
+		"react-easy-crop": "^6.2.3",
 		"react-markdown": "^10.1.0",
-		"react-resizable-panels": "^4.12.1",
-		"react-window": "^2.2.7",
-		"react-zoom-pan-pinch": "^4.0.3",
+		"react-resizable-panels": "^4.12.2",
+		"react-window": "^2.3.0",
+		"react-zoom-pan-pinch": "^4.0.4",
 		"remark-gfm": "^4.0.1",
-		"sonner": "^2.0.7",
+		"sonner": "^2.0.8",
 		"ts-pattern": "^5.9.0",
 		"usehooks-ts": "^3.1.1",
 		"zod": "^4.4.3",
@@ -86,23 +96,27 @@
 	},
 	"devDependencies": {
 		"@babel/core": "^8.0.1",
-		"@lingui/babel-plugin-lingui-macro": "^6.4.0",
-		"@lingui/cli": "^6.4.0",
-		"@lingui/format-po": "^6.4.0",
-		"@lingui/vite-plugin": "^6.4.0",
+		"@lingui/babel-plugin-lingui-macro": "^6.6.0",
+		"@lingui/cli": "^6.6.0",
+		"@lingui/format-po": "^6.6.0",
+		"@lingui/vite-plugin": "^6.6.0",
 		"@reactive-resume/config": "workspace:*",
 		"@rolldown/plugin-babel": "^0.2.3",
-		"@tanstack/router-plugin": "^1.168.19",
+		"@tanstack/devtools-vite": "^0.8.3",
+		"@tanstack/react-devtools": "^0.10.9",
+		"@tanstack/react-query-devtools": "^5.101.4",
+		"@tanstack/react-router-devtools": "^1.167.1",
+		"@tanstack/router-plugin": "^1.168.29",
 		"@types/babel__core": "^7.20.5",
-		"@types/pg": "^8.20.0",
-		"@types/react": "^19.2.17",
-		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "7.0.0-dev.20260704.1",
-		"@vitejs/plugin-react": "^6.0.3",
+		"@types/pg": "^8.21.0",
+		"@types/react": "^19.2.18",
+		"@types/react-dom": "^19.2.4",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"@vitejs/plugin-react": "^6.0.5",
 		"babel-plugin-macros": "^3.1.0",
 		"babel-plugin-react-compiler": "^1.0.0",
 		"rimraf": "^6.1.3",
-		"typescript": "^6.0.3",
-		"vite": "^8.1.3"
+		"typescript": "^7.0.2",
+		"vite": "^8.2.1"
 	}
 }
@@ -11,6 +11,15 @@ type CountUpProps = {
 	"aria-atomic"?: boolean | "true" | "false";
 };

+const getDecimalPlaces = (num: number): number => {
+	const str = num.toString();
+	if (str.includes(".")) {
+		const decimals = str.split(".")[1];
+		if (Number.parseInt(decimals, 10) !== 0) return decimals.length;
+	}
+	return 0;
+};
+
 // ponytail: from/direction/delay/startWhen/onStart/onEnd removed — no production caller passes them
 export function CountUp({
 	to,
@@ -31,15 +40,6 @@ export function CountUp({

 	const isInView = useInView(ref, { once: true, margin: "0px" });

-	const getDecimalPlaces = (num: number): number => {
-		const str = num.toString();
-		if (str.includes(".")) {
-			const decimals = str.split(".")[1];
-			if (Number.parseInt(decimals, 10) !== 0) return decimals.length;
-		}
-		return 0;
-	};
-
 	const maxDecimals = getDecimalPlaces(to);

 	const formatValue = useCallback(
--- a/Show More
+++ b/Show More