From 0a82dd6696baba39ab22896a6e0b3600b96019dc Mon Sep 17 00:00:00 2001
From: Bobby Powers <bobbypowers@gmail.com>
Date: Wed, 1 Jul 2026 11:42:24 -0700
Subject: [PATCH 1/4] server: add unauthenticated /healthz route and exit on
 failed boot

GAE serves / as a static file, so production can be fully down (every
Express instance crash-looping) while / stays green. /healthz is an
Express-routed, unauthenticated uptime-check target that reflects the
WASM engine preload via isReady(). It mounts ahead of the request
logger and session middleware so constant polling stays cheap and out
of the logs. Because initializeServerDependencies() throws before the
route mounts, a preload failure surfaces as a non-responding instance,
not a 503; the 503 branch is defense-in-depth.

Also make a rejected main() log and exit(1) instead of falling into
the unhandledRejection logger, which left a zombie process that never
bound the port; on GAE that hung instances until the port-bind timeout
instead of recycling them with a clear error. This is the in-repo half
of issue 693 (the Cloud Monitoring channel/uptime-check/alert setup
remains ops-side).
---
 docs/dev/deploy.md                  |  3 +-
 src/server/CLAUDE.md                |  1 +
 src/server/app.ts                   | 13 ++++
 src/server/healthz.ts               | 41 +++++++++++++
 src/server/index.ts                 | 13 +++-
 src/server/tests/healthz.test.ts    | 93 +++++++++++++++++++++++++++++
 src/server/tests/index-boot.test.ts | 48 +++++++++++++++
 7 files changed, 210 insertions(+), 2 deletions(-)
 create mode 100644 src/server/healthz.ts
 create mode 100644 src/server/tests/healthz.test.ts
 create mode 100644 src/server/tests/index-boot.test.ts

diff --git a/docs/dev/deploy.md b/docs/dev/deploy.md
index 439ee399f..c034d970d 100644
--- a/docs/dev/deploy.md
+++ b/docs/dev/deploy.md
@@ -133,6 +133,7 @@ The server loads `config/default.json`, then `config/production.json` when `NODE
 Against the `--no-promote` version URL, then again on production:
 
 - `curl -sI https://<host>/` -> 200 HTML. View source: it links a hashed `/static/js/index.<hash>.js` (literal `<%= PUBLIC_URL %>` means the build was skipped) and `/static/css/index.<hash>.css`.
+- `curl -s https://<host>/healthz` -> 200 `ok`. This is the only check that exercises the Node server: `/` is a GAE static handler and stays green even when every Express instance is crash-looping (e.g. `ServerInitError`). A WASM preload failure aborts boot before the route mounts, so it shows up as a non-responding instance (connection failure / GAE 5xx), not a 503 -- treat any non-200 here as down. (The route's 503 branch is defense-in-depth, not the expected failure signal.)
 - `curl -sI https://<host>/static/js/sd-component.js` -> 200 -- the embeddable web component; external sites `<script src>` this exact path.
 - `curl -sI https://<host>/static/wasm/<hash>.module.wasm` -> 200, `content-type: application/wasm`.
 - `curl -sI` on `/robots.txt`, `/manifest.json`, `/favicon.ico`, `/legal/`, `/privacy/` -> 200; `curl -I http://<host>/` -> 301 to https.
@@ -162,4 +163,4 @@ Things to know that don't have a clean fix yet:
 
 - `pnpm deploy:web` deploys from the workspace root, so GAE's Node buildpack installs the *whole workspace's* dependency set on the instance -- `@rsbuild/*`, `jest`, `slate`, `radix`, rspress, vite, and every other package's deps (~590 MB / 1171 packages), none needed by the server at runtime. App Engine standard always reinstalls from the deployed `package.json` + lockfile and has no vendored-`node_modules` escape hatch, so the only lever is the deployed manifest. The smaller-deploy fix is implemented as **`pnpm deploy:web:staged`** (see below); it is locally proven but still pending a real `gcloud --no-promote` test, so `deploy:web` remains the default. Tracked in [docs/tech-debt.md](/docs/tech-debt.md) "Web deploy uploads the whole monorepo and GAE installs the full dep set".
 - Server-side PNG preview (`src/server/render.ts`) parses and rasterizes user-uploaded models in-process with no size cap beyond the 10 MB request body limit and no timeout.
-- There's no error reporting or alerting. Cloud Logging and the GAE metrics dashboard are it.
+- There's no error reporting or alerting. Cloud Logging and the GAE metrics dashboard are it. The Express `/healthz` route exists as an uptime-check target (see the smoke test above), but no Cloud Monitoring notification channel, uptime check, or alerting policy points at it yet -- that ops-side setup is tracked in [issue #693](https://github.com/bpowers/simlin/issues/693).
diff --git a/src/server/CLAUDE.md b/src/server/CLAUDE.md
index d7ab7c118..eba8cb6e0 100644
--- a/src/server/CLAUDE.md
+++ b/src/server/CLAUDE.md
@@ -16,6 +16,7 @@ For build/test/lint commands, see [docs/dev/commands.md](/docs/dev/commands.md).
 - `seshcookie/` -- Vendored copy of the seshcookie encrypted-cookie-session library (github.com/bpowers/seshcookie-js, relicensed to Apache-2.0 with its author's permission). simlin is its only consumer, so it lives in-tree instead of going through npm publishes; keep diffs against upstream minimal
 - `logger.ts` -- Minimal structured logger (one `{level, message, timestamp}` JSON line per entry on stdout)
 - `favicon.ts` -- In-memory favicon middleware
+- `healthz.ts` -- Unauthenticated healthz GET route for uptime checks (200 when the WASM engine is ready; never touches Firestore). A preload failure aborts boot before the route mounts, so a broken instance surfaces as a connection failure, not a 503 -- the 503 branch is defense-in-depth
 - `project-creation.ts` -- Project creation logic
 - `new-user.ts` -- New user handling
 - `server-init.ts` -- Server initialization
diff --git a/src/server/app.ts b/src/server/app.ts
index 2beb4307d..559006779 100644
--- a/src/server/app.ts
+++ b/src/server/app.ts
@@ -10,6 +10,7 @@ import * as admin from 'firebase-admin';
 import cors from 'cors';
 import express from 'express';
 import helmet from 'helmet';
+import { isReady } from '@simlin/engine';
 import { seshcookie } from './seshcookie/seshcookie';
 
 import { apiRouter } from './api';
@@ -18,6 +19,7 @@ import { Application } from './application';
 import { authn } from './authn';
 import authz from './authz';
 import { favicon } from './favicon';
+import { healthz } from './healthz';
 import { validateRuntimeConfig } from './config-validation';
 import * as logger from './logger';
 import { createDatabase } from './models/db';
@@ -126,6 +128,17 @@ class App {
       backend: 'firestore',
     });
 
+    // /healthz comes first: uptime checks poll it constantly, so keep it
+    // out of the request log and outside the session/auth middleware.
+    // (GAE's edge 301s plain-http before Express ever sees it, so sitting
+    // ahead of redirectToHttps only matters when running off-GAE.)
+    // Because initializeServerDependencies() above throws on preload
+    // failure -- aborting boot before this route mounts -- a broken WASM
+    // preload surfaces as an instance that never listens (connection
+    // failure / GAE 5xx), not as a 503 here; the isReady() probe is
+    // cheap defense-in-depth, not the expected failure signal.
+    this.app.get('/healthz', healthz(isReady));
+
     // put the redirect before the request logger to remove noise
     this.app.use(redirectToHttps);
     this.app.use(requestLogger);
diff --git a/src/server/healthz.ts b/src/server/healthz.ts
new file mode 100644
index 000000000..2b1f71e04
--- /dev/null
+++ b/src/server/healthz.ts
@@ -0,0 +1,41 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+import { RequestHandler } from 'express';
+
+export interface HealthResponse {
+  readonly status: number;
+  readonly body: string;
+}
+
+/**
+ * Decide the health-check response for the current engine state.
+ *
+ * The WASM engine preload is the only explicit boot-readiness step the
+ * server has (see server-init.ts). In practice a preload failure aborts
+ * boot before any route is mounted (initializeServerDependencies()
+ * throws and index.ts exits non-zero), so a broken instance surfaces as
+ * a connection failure rather than a 503; the 503 branch is cheap
+ * defense-in-depth in case that boot ordering ever changes.
+ */
+export function healthResponse(engineReady: boolean): HealthResponse {
+  return engineReady ? { status: 200, body: 'ok' } : { status: 503, body: 'engine not ready' };
+}
+
+/**
+ * Unauthenticated GET /healthz handler for Cloud Monitoring uptime checks.
+ *
+ * app.yaml serves '/' as a GAE static file, so '/' stays green even when
+ * every Express instance is crash-looping; this route is what proves the
+ * Node process itself is up. It must stay cheap (polled frequently) and
+ * must never touch Firestore, the session, or any other external service.
+ * The readiness probe is injected so the decision logic stays pure.
+ */
+export function healthz(isEngineReady: () => boolean): RequestHandler {
+  return (_req, res) => {
+    const { status, body } = healthResponse(isEngineReady());
+    // no-store: a cached "ok" from any intermediary would mask an outage
+    res.status(status).set('Cache-Control', 'no-store').type('text/plain').send(body);
+  };
+}
diff --git a/src/server/index.ts b/src/server/index.ts
index e25b43fba..ea476e853 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -17,4 +17,15 @@ async function main(): Promise<void> {
   app.listen();
 }
 
-setImmediate(main);
+// A failed boot (e.g. ServerInitError when the engine WASM is missing)
+// must take the process down: logging alone would leave a zombie that
+// never binds the port, and on GAE such an instance hangs until the
+// port-bind timeout instead of recycling immediately with a clear error
+// in the logs.
+setImmediate(() => {
+  main().catch((err: unknown) => {
+    const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    logger.error(`server startup failed, exiting: ${detail}`);
+    process.exit(1);
+  });
+});
diff --git a/src/server/tests/healthz.test.ts b/src/server/tests/healthz.test.ts
new file mode 100644
index 000000000..84e2a398c
--- /dev/null
+++ b/src/server/tests/healthz.test.ts
@@ -0,0 +1,93 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+import * as http from 'http';
+
+import express from 'express';
+
+import { healthResponse, healthz } from '../healthz';
+
+function request(
+  server: http.Server,
+  method: string,
+  reqPath: string,
+): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: string }> {
+  return new Promise((resolve, reject) => {
+    const addr = server.address();
+    if (!addr || typeof addr === 'string') {
+      return reject(new Error('server not listening'));
+    }
+    const req = http.request({ hostname: '127.0.0.1', port: addr.port, path: reqPath, method }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk: Buffer) => chunks.push(chunk));
+      res.on('end', () => {
+        resolve({ status: res.statusCode ?? 0, headers: res.headers, body: Buffer.concat(chunks).toString('utf-8') });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+describe('healthResponse', () => {
+  it('is 200 ok when the engine is ready', () => {
+    expect(healthResponse(true)).toEqual({ status: 200, body: 'ok' });
+  });
+
+  it('is 503 when the engine is not ready', () => {
+    expect(healthResponse(false)).toEqual({ status: 503, body: 'engine not ready' });
+  });
+});
+
+describe('healthz route', () => {
+  let server: http.Server;
+  let engineReady: boolean;
+
+  beforeAll(() => {
+    engineReady = true;
+
+    const app = express();
+    app.get(
+      '/healthz',
+      healthz(() => engineReady),
+    );
+    server = app.listen(0);
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  });
+
+  it('returns 200 ok when the readiness probe passes', async () => {
+    engineReady = true;
+    const res = await request(server, 'GET', '/healthz');
+    expect(res.status).toBe(200);
+    expect(res.body).toBe('ok');
+    expect(res.headers['content-type']).toContain('text/plain');
+    // uptime checks poll this endpoint; a cached response would mask an outage
+    expect(res.headers['cache-control']).toBe('no-store');
+  });
+
+  it('returns 503 when the readiness probe fails', async () => {
+    engineReady = false;
+    const res = await request(server, 'GET', '/healthz');
+    expect(res.status).toBe(503);
+    expect(res.body).toBe('engine not ready');
+    expect(res.headers['cache-control']).toBe('no-store');
+  });
+
+  it('answers HEAD requests with the same status and no body', async () => {
+    engineReady = true;
+    const res = await request(server, 'HEAD', '/healthz');
+    expect(res.status).toBe(200);
+    expect(res.body).toBe('');
+  });
+
+  it('is scoped to GET/HEAD: POST is not handled', async () => {
+    const res = await request(server, 'POST', '/healthz');
+    expect(res.status).toBe(404);
+  });
+});
diff --git a/src/server/tests/index-boot.test.ts b/src/server/tests/index-boot.test.ts
new file mode 100644
index 000000000..60ffd33d1
--- /dev/null
+++ b/src/server/tests/index-boot.test.ts
@@ -0,0 +1,48 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// index.ts is the server entrypoint: importing it schedules boot via
+// setImmediate. Mocking createApp and the logger lets us exercise just
+// the boot-failure contract -- log and exit non-zero -- without touching
+// Firebase or the real app. Exit-on-failure matters because a zombie
+// process that never binds the port hangs a GAE instance until the
+// port-bind timeout instead of recycling immediately.
+jest.mock('../app', () => ({
+  createApp: jest.fn(() => Promise.reject(new Error('boot failed: engine WASM missing'))),
+}));
+jest.mock('../logger', () => ({
+  error: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+}));
+
+import * as logger from '../logger';
+
+describe('server boot failure', () => {
+  it('logs the error and exits non-zero when createApp rejects', async () => {
+    const exit = jest.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    try {
+      await import('../index');
+
+      // boot runs on a later tick (setImmediate); poll until the catch fires
+      // rather than sleeping a fixed amount
+      await new Promise<void>((resolve) => {
+        const check = (): void => {
+          if (exit.mock.calls.length > 0) {
+            resolve();
+          } else {
+            setImmediate(check);
+          }
+        };
+        setImmediate(check);
+      });
+
+      expect(exit).toHaveBeenCalledWith(1);
+      expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('server startup failed'));
+      expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('engine WASM missing'));
+    } finally {
+      exit.mockRestore();
+    }
+  });
+});

From f6c0d6c40a0fe03a0d76fd707778fe59d73a360d Mon Sep 17 00:00:00 2001
From: Bobby Powers <bobbypowers@gmail.com>
Date: Wed, 1 Jul 2026 12:13:46 -0700
Subject: [PATCH 2/4] server: isolate preview rendering in a worker thread with
 a total deadline

Preview PNG rendering ran the whole protobuf->SVG->PNG pipeline
synchronously on the Express event loop through the process-wide WASM
DirectBackend, so one slow or pathological model stalled every
concurrently-multiplexed request on the instance (GAE allows 100) --
a regression from the 2022 per-request worker_threads design. Restore
that isolation: each render runs in its own worker thread with its own
WASM instance, behind a 2-slot FIFO limiter, under a 10s total
wall-clock budget that includes queue wait (a request whose deadline
lapses while queued rejects without spawning a doomed worker). A WASM
panic or OOM now kills a disposable thread, not the server. Failures
stay per-request: the preview route's existing 500 path is unchanged.

Cap automatic_scaling at 8 instances in app.yaml so a render storm or
crash loop cannot fan out cost without bound, and make
validate-app-prod-config.mjs refuse to deploy if the operator-local
.app.prod.yaml lacks max_instances. verify-deploy-build.sh and the
staged-deploy verify step now assert lib/render-worker.js ships,
because a build that dropped it would 500 every preview while looking
healthy. Addresses the isolation, timeout, and instance-cap facets of
issue 694; a model-complexity cap below the 10 MB body limit remains
open there.
---
 app.yaml                                      |   5 +
 docs/dev/deploy.md                            |   7 +-
 scripts/build-deploy-staging.mjs              |   6 +
 .../tests/validate-app-prod-config.test.mjs   |  58 ++++-
 scripts/validate-app-prod-config.mjs          |  12 +
 scripts/verify-deploy-build.sh                |  10 +
 src/server/CLAUDE.md                          |   4 +-
 src/server/preview-geometry.ts                |  53 ++++
 src/server/render-worker.ts                   |  66 +++++
 src/server/render.ts                          | 230 ++++++++++++++----
 .../tests/fixtures/worker-error-result.js     |  10 +
 src/server/tests/fixtures/worker-exit.js      |   8 +
 src/server/tests/fixtures/worker-hang.js      |   9 +
 src/server/tests/fixtures/worker-success.js   |  11 +
 src/server/tests/fixtures/worker-throw.js     |   8 +
 src/server/tests/render-model-preview.test.ts |  20 +-
 src/server/tests/render-to-png.test.ts        | 212 ++++++++++++++++
 17 files changed, 659 insertions(+), 70 deletions(-)
 create mode 100644 src/server/preview-geometry.ts
 create mode 100644 src/server/render-worker.ts
 create mode 100644 src/server/tests/fixtures/worker-error-result.js
 create mode 100644 src/server/tests/fixtures/worker-exit.js
 create mode 100644 src/server/tests/fixtures/worker-hang.js
 create mode 100644 src/server/tests/fixtures/worker-success.js
 create mode 100644 src/server/tests/fixtures/worker-throw.js
 create mode 100644 src/server/tests/render-to-png.test.ts

diff --git a/app.yaml b/app.yaml
index f7fad526d..424409f73 100644
--- a/app.yaml
+++ b/app.yaml
@@ -6,6 +6,11 @@ build_env_variables:
 instance_class: F4
 automatic_scaling:
   max_concurrent_requests: 100
+  # Cost cap: bounds worst-case fan-out if a render storm or crash loop drives
+  # autoscaling (issue #694). 8 F4 instances is far above routine load; raise
+  # deliberately if organic traffic ever needs it. Mirror this into
+  # .app.prod.yaml -- scripts/validate-app-prod-config.mjs enforces it there.
+  max_instances: 8
 
 handlers:
 - url: /static
diff --git a/docs/dev/deploy.md b/docs/dev/deploy.md
index c034d970d..f78b625ab 100644
--- a/docs/dev/deploy.md
+++ b/docs/dev/deploy.md
@@ -1,6 +1,6 @@
 # Deploying to production
 
-**Last reviewed:** 2026-05-08
+**Last reviewed:** 2026-07-01
 
 The web app at `app.simlin.com` runs on Google App Engine standard. GAE serves the static React SPA built from `src/app` and runs the Express backend in `src/server` (Firebase Auth, models persisted in Firestore as protobuf). `@simlin/mcp`, `@simlin/serve`, `pysimlin`, and `simlin-cli` are released separately to npm/PyPI -- they aren't part of this deploy.
 
@@ -103,6 +103,7 @@ On the instance GAE runs `pnpm install`, then the root `start` script: `node src
 
 - `runtime`: `nodejs24`. (`nodejs18` is EOL on GAE; `nodejs16`, the runtime of the last deploy before May 2026, is gone entirely -- which is why there's no "redeploy the old commit" rollback.)
 - `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS`: `''`. The local deploy script already runs the monorepo build and stages the exact artifact to upload; this prevents App Engine's Node buildpack from running the root `build` script again during staging.
+- `automatic_scaling.max_instances`: `8`. Cost cap so a render storm or crash loop can't fan out F4 instances without bound (issue #694). **Mirror this into `.app.prod.yaml`** -- both deploy scripts run `scripts/validate-app-prod-config.mjs`, which fails the deploy if it's missing or not a positive integer. Raise it deliberately if organic traffic ever needs more instances.
 - The handler list: `/static`, `/`, `/new`, `/legal*`, `/privacy`, `robots.txt`, `ads.txt`, favicon, `manifest.json`, then `/.*` -> `script: auto`. The `/` and `/new` static HTML handlers carry CSP/HSTS headers because they bypass Express Helmet. The SPA's dynamic routes like `/:username/:projectName` fall through to `/.*`, i.e. the Express server.
 - `env_variables`: the committed `app.yaml` has none; the server needs a couple (next section). They live in `.app.prod.yaml`.
 
@@ -125,7 +126,7 @@ The server loads `config/default.json`, then `config/production.json` when `NODE
 - [ ] `git status` is clean.
 - [ ] `gcloud config get-value project` is the production project.
 - [ ] `gcloud app versions list --service=default` shows a known-good current version -- note its ID, that's your rollback target. (If GAE has garbage-collected it, there is no rollback; see below.)
-- [ ] `.app.prod.yaml` reconciled against `app.yaml` (`runtime: nodejs24`, `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''`, handlers, `authentication__seshcookie__key` set to the value already in use).
+- [ ] `.app.prod.yaml` reconciled against `app.yaml` (`runtime: nodejs24`, `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''`, `automatic_scaling.max_instances: 8`, handlers, `authentication__seshcookie__key` set to the value already in use).
 - [ ] `wasm-opt --version` works; `rustup show` lists the `wasm32-unknown-unknown` target.
 
 ## Post-deploy smoke test
@@ -162,5 +163,5 @@ The `frontend` job in [`.github/workflows/ci.yaml`](/.github/workflows/ci.yaml)
 Things to know that don't have a clean fix yet:
 
 - `pnpm deploy:web` deploys from the workspace root, so GAE's Node buildpack installs the *whole workspace's* dependency set on the instance -- `@rsbuild/*`, `jest`, `slate`, `radix`, rspress, vite, and every other package's deps (~590 MB / 1171 packages), none needed by the server at runtime. App Engine standard always reinstalls from the deployed `package.json` + lockfile and has no vendored-`node_modules` escape hatch, so the only lever is the deployed manifest. The smaller-deploy fix is implemented as **`pnpm deploy:web:staged`** (see below); it is locally proven but still pending a real `gcloud --no-promote` test, so `deploy:web` remains the default. Tracked in [docs/tech-debt.md](/docs/tech-debt.md) "Web deploy uploads the whole monorepo and GAE installs the full dep set".
-- Server-side PNG preview (`src/server/render.ts`) parses and rasterizes user-uploaded models in-process with no size cap beyond the 10 MB request body limit and no timeout.
+- Server-side PNG preview (`src/server/render.ts`) renders user-uploaded models in per-request `worker_threads` workers (each with its own WASM instance) with a 10 s total wall-clock budget per request (queue wait included) and at most 2 concurrent renders -- restoring the isolation the 2022 deploy had (issue #694). What remains rough: there's no model-complexity cap below the 10 MB request body limit, so a pathological model still costs a bounded 10 s worker per attempt before failing with a 500.
 - There's no error reporting or alerting. Cloud Logging and the GAE metrics dashboard are it. The Express `/healthz` route exists as an uptime-check target (see the smoke test above), but no Cloud Monitoring notification channel, uptime check, or alerting policy points at it yet -- that ops-side setup is tracked in [issue #693](https://github.com/bpowers/simlin/issues/693).
diff --git a/scripts/build-deploy-staging.mjs b/scripts/build-deploy-staging.mjs
index e27d39f55..eb7dba434 100644
--- a/scripts/build-deploy-staging.mjs
+++ b/scripts/build-deploy-staging.mjs
@@ -240,6 +240,12 @@ function verify(stagingDir) {
   };
 
   check(fs.existsSync(path.join(stagingDir, 'lib/index.js')), 'lib/index.js missing');
+  // render.ts spawns this sibling via __dirname at runtime (issue #694); a
+  // deploy without it 500s every preview while everything else looks healthy.
+  check(
+    fs.existsSync(path.join(stagingDir, 'lib/render-worker.js')),
+    'lib/render-worker.js missing (preview renders would 500 at runtime)',
+  );
   check(fs.existsSync(path.join(stagingDir, 'config/production.json')), 'config/production.json missing');
   check(
     fs.existsSync(path.join(stagingDir, 'default_projects')) &&
diff --git a/scripts/tests/validate-app-prod-config.test.mjs b/scripts/tests/validate-app-prod-config.test.mjs
index f9c9d1959..a06ca26ed 100644
--- a/scripts/tests/validate-app-prod-config.test.mjs
+++ b/scripts/tests/validate-app-prod-config.test.mjs
@@ -3,6 +3,16 @@ import { describe, it } from 'node:test';
 
 import { validateAppProdConfig } from '../validate-app-prod-config.mjs';
 
+const MAX_INSTANCES_MESSAGE =
+  'automatic_scaling.max_instances must be set to a positive integer (cost cap; mirror the committed app.yaml)';
+
+// Every fixture that isn't specifically exercising the max_instances check
+// carries this block so its expected messages stay focused on one concern.
+const scalingBlock = `
+automatic_scaling:
+  max_instances: 8
+`;
+
 const validConfig = `
 runtime: nodejs24
 
@@ -12,7 +22,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: production-secret
-`;
+${scalingBlock}`;
 
 function messagesFor(source) {
   return validateAppProdConfig(source, '.app.prod.yaml').map((error) => error.message);
@@ -27,6 +37,7 @@ describe('validateAppProdConfig', () => {
     const messages = messagesFor(`
 # build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''
 # env_variables.authentication__seshcookie__key: production-secret
+# automatic_scaling.max_instances: 8
 runtime: nodejs24
 `);
 
@@ -34,6 +45,7 @@ runtime: nodejs24
       'build_env_variables.GOOGLE_NODE_RUN_SCRIPTS must be set to an empty string',
       'env_variables.NODE_ENV must be set to production',
       'env_variables.authentication__seshcookie__key must be set to the existing production session key',
+      MAX_INSTANCES_MESSAGE,
     ]);
   });
 
@@ -43,7 +55,7 @@ env_variables:
   NODE_ENV: production
   GOOGLE_NODE_RUN_SCRIPTS: ''
   authentication__seshcookie__key: production-secret
-`);
+${scalingBlock}`);
 
     assert.deepEqual(messages, ['build_env_variables.GOOGLE_NODE_RUN_SCRIPTS must be set to an empty string']);
   });
@@ -55,7 +67,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: production-secret
-`);
+${scalingBlock}`);
 
     assert.deepEqual(messages, ['build_env_variables.GOOGLE_NODE_RUN_SCRIPTS must be set to an empty string']);
   });
@@ -67,7 +79,7 @@ build_env_variables:
   authentication__seshcookie__key: production-secret
 env_variables:
   NODE_ENV: production
-`);
+${scalingBlock}`);
 
     assert.deepEqual(messages, [
       'env_variables.authentication__seshcookie__key must be set to the existing production session key',
@@ -83,7 +95,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: ${value}
-`),
+${scalingBlock}`),
         ['env_variables.authentication__seshcookie__key must be set to the existing production session key'],
       );
     }
@@ -95,7 +107,7 @@ build_env_variables:
   GOOGLE_NODE_RUN_SCRIPTS: ''
 env_variables:
   authentication__seshcookie__key: production-secret
-`);
+${scalingBlock}`);
 
     assert.deepEqual(messages, ['env_variables.NODE_ENV must be set to production']);
   });
@@ -108,19 +120,49 @@ build_env_variables:
   NODE_ENV: production
 env_variables:
   authentication__seshcookie__key: production-secret
-`,
+${scalingBlock}`,
       `
 build_env_variables:
   GOOGLE_NODE_RUN_SCRIPTS: ''
 env_variables:
   NODE_ENV: development
   authentication__seshcookie__key: production-secret
-`,
+${scalingBlock}`,
     ]) {
       assert.deepEqual(messagesFor(source), ['env_variables.NODE_ENV must be set to production']);
     }
   });
 
+  it('rejects a missing automatic_scaling block', () => {
+    const messages = messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+`);
+
+    assert.deepEqual(messages, [MAX_INSTANCES_MESSAGE]);
+  });
+
+  it('rejects max_instances values that are not positive integers', () => {
+    for (const value of ['0', '-2', '2.5', 'unlimited', "''"]) {
+      assert.deepEqual(
+        messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+automatic_scaling:
+  max_instances: ${value}
+`),
+        [MAX_INSTANCES_MESSAGE],
+        `max_instances: ${value} should be rejected`,
+      );
+    }
+  });
+
   it('rejects malformed YAML', () => {
     const messages = messagesFor(`
 build_env_variables:
diff --git a/scripts/validate-app-prod-config.mjs b/scripts/validate-app-prod-config.mjs
index f017949e3..42a74f870 100644
--- a/scripts/validate-app-prod-config.mjs
+++ b/scripts/validate-app-prod-config.mjs
@@ -60,6 +60,18 @@ export function validateAppProdConfig(source, filename = '.app.prod.yaml') {
     });
   }
 
+  // Cost cap: without max_instances a render storm or crash loop can fan out
+  // F4 instances without bound (issue #694). The committed app.yaml carries
+  // the reference value; the operator must mirror it here.
+  const scaling = config.automatic_scaling;
+  const maxInstances = isRecord(scaling) ? scaling.max_instances : undefined;
+  if (!Number.isInteger(maxInstances) || maxInstances <= 0) {
+    errors.push({
+      message:
+        'automatic_scaling.max_instances must be set to a positive integer (cost cap; mirror the committed app.yaml)',
+    });
+  }
+
   return errors;
 }
 
diff --git a/scripts/verify-deploy-build.sh b/scripts/verify-deploy-build.sh
index 186145225..50fc48b2c 100755
--- a/scripts/verify-deploy-build.sh
+++ b/scripts/verify-deploy-build.sh
@@ -182,6 +182,16 @@ else
     pass "src/server/lib/index.js exists"
 fi
 
+# 9. The preview render worker entry ships next to the compiled server.
+#    render.ts spawns lib/render-worker.js via __dirname at runtime
+#    (issue #694); if it's missing, every preview request 500s while the
+#    rest of the server looks healthy.
+if [ ! -f src/server/lib/render-worker.js ]; then
+    fail "src/server/lib/render-worker.js missing (preview renders would 500 at runtime)"
+else
+    pass "src/server/lib/render-worker.js exists"
+fi
+
 echo ""
 if [ "$errors" -gt 0 ]; then
     echo "verify-deploy-build: FAILED ($errors error(s))" >&2
diff --git a/src/server/CLAUDE.md b/src/server/CLAUDE.md
index eba8cb6e0..53b2201c4 100644
--- a/src/server/CLAUDE.md
+++ b/src/server/CLAUDE.md
@@ -21,6 +21,8 @@ For build/test/lint commands, see [docs/dev/commands.md](/docs/dev/commands.md).
 - `new-user.ts` -- New user handling
 - `server-init.ts` -- Server initialization
 - `route-handlers.ts` -- Route handler utilities
-- `render.ts` -- Server-side PNG rendering (delegates to the engine WASM)
+- `render.ts` -- Server-side PNG preview orchestration: spawns a per-request `worker_threads` worker under a total wall-clock budget (`RENDER_TIMEOUT_MS`, queue wait included) and a small FIFO concurrency cap, so a slow/pathological model can't pin the Express event loop (issue #694)
+- `render-worker.ts` -- Worker entry that runs the actual render pipeline (protobuf -> SVG -> PNG) on its own engine WASM instance; `renderProjectToPng` is exported for in-process tests
+- `preview-geometry.ts` -- Pure preview sizing/viewBox helpers shared by render.ts (re-exported) and the worker
 - `models/` -- Database interfaces (Firestore, etc.)
 - `schemas/` -- Data validation schemas
diff --git a/src/server/preview-geometry.ts b/src/server/preview-geometry.ts
new file mode 100644
index 000000000..b952bcd0c
--- /dev/null
+++ b/src/server/preview-geometry.ts
@@ -0,0 +1,53 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Pure geometry helpers for preview rendering. This lives apart from
+// render.ts so the render worker (render-worker.ts) can import it without
+// pulling in the main thread's worker-spawning code or the protobuf schemas.
+
+const MAX_PREVIEW_PX = 400;
+const RETINA_SCALE = 2;
+export const MAX_PREVIEW_SIZE = MAX_PREVIEW_PX * RETINA_SCALE; // 800
+
+/**
+ * Compute the single constraining dimension to pass to renderPng.
+ *
+ * Returns only the constraining dimension set to `maxSize`, with
+ * the other set to 0 so the engine derives it from the aspect ratio.
+ * This avoids the width-precedence bug where passing both non-zero
+ * causes the engine to ignore the height constraint.
+ */
+export function previewDimensions(
+  svgWidth: number,
+  svgHeight: number,
+  maxSize: number,
+): { width: number; height: number } {
+  if (svgWidth <= 0 || svgHeight <= 0 || maxSize <= 0) {
+    return { width: 0, height: 0 };
+  }
+  if (svgWidth >= svgHeight) {
+    // Landscape or square: constrain width, let the engine derive height
+    return { width: maxSize, height: 0 };
+  }
+  // Portrait: constrain height, let the engine derive width
+  return { width: 0, height: maxSize };
+}
+
+/**
+ * Parse the viewBox dimensions from an SVG string.
+ *
+ * Returns `{width, height}` from the third and fourth viewBox values.
+ * Falls back to `{0, 0}` when the viewBox is absent or unparseable.
+ */
+export function parseSvgDimensions(svg: string): { width: number; height: number } {
+  const match = svg.match(/viewBox="([^"]*)"/);
+  if (!match) {
+    return { width: 0, height: 0 };
+  }
+  const parts = match[1].trim().split(/\s+/).map(Number);
+  if (parts.length < 4 || parts.some(isNaN)) {
+    return { width: 0, height: 0 };
+  }
+  return { width: parts[2], height: parts[3] };
+}
diff --git a/src/server/render-worker.ts b/src/server/render-worker.ts
new file mode 100644
index 000000000..c42784117
--- /dev/null
+++ b/src/server/render-worker.ts
@@ -0,0 +1,66 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Worker-thread entry point for server-side preview rendering.
+//
+// The whole pipeline (protobuf parse -> SVG -> PNG rasterize) is CPU-bound
+// WASM work; running it here keeps the Express event loop responsive and
+// contains a WASM OOM or panic to a disposable thread that render.ts can
+// terminate on timeout (issue #694). Worker threads have their own module
+// registry, so this thread instantiates its own engine WASM instance instead
+// of sharing the server's process-wide DirectBackend; the engine resolves
+// core/libsimlin.wasm relative to its own compiled lib/, which is identical
+// on the main thread and in a worker.
+
+import { isMainThread, parentPort, workerData } from 'worker_threads';
+
+import { Project as EngineProject } from '@simlin/engine';
+
+import { MAX_PREVIEW_SIZE, parseSvgDimensions, previewDimensions } from './preview-geometry';
+
+/** Payload render.ts passes to the worker via workerData. */
+export interface RenderWorkerData {
+  projectContents: Uint8Array;
+}
+
+/** The single message this worker posts back: a PNG or an error string. */
+export type RenderWorkerResult = { ok: true; png: Uint8Array } | { ok: false; error: string };
+
+/**
+ * Render a serialized project's `main` model to a preview-sized PNG.
+ *
+ * This is the functional core of the worker, exported so tests can exercise
+ * the real pipeline in-process (via ts-jest) without spawning a thread.
+ */
+export async function renderProjectToPng(projectContents: Uint8Array): Promise<Uint8Array> {
+  const engineProject = await EngineProject.openProtobuf(projectContents);
+  try {
+    const svg = await engineProject.renderSvgString('main');
+    const intrinsic = parseSvgDimensions(svg);
+    const dims = previewDimensions(intrinsic.width, intrinsic.height, MAX_PREVIEW_SIZE);
+    return await engineProject.renderPng('main', dims.width, dims.height);
+  } finally {
+    await engineProject.dispose();
+  }
+}
+
+// Imperative shell: runs only when this module is loaded as a Worker entry.
+// Importing it on the main thread (tests) leaves isMainThread true, so the
+// import stays side-effect free there.
+if (!isMainThread && parentPort) {
+  const port = parentPort;
+  const { projectContents } = workerData as RenderWorkerData;
+  renderProjectToPng(projectContents)
+    .then((png) => {
+      const result: RenderWorkerResult = { ok: true, png };
+      port.postMessage(result);
+    })
+    .catch((err: unknown) => {
+      const result: RenderWorkerResult = {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+      port.postMessage(result);
+    });
+}
diff --git a/src/server/render.ts b/src/server/render.ts
index 3d3618800..844581423 100644
--- a/src/server/render.ts
+++ b/src/server/render.ts
@@ -2,63 +2,203 @@
 // Use of this source code is governed by the Apache License,
 // Version 2.0, that can be found in the LICENSE file.
 
-import { Project as EngineProject } from '@simlin/engine';
+import * as fs from 'fs';
+import * as path from 'path';
+import { Worker } from 'worker_threads';
+
 import { File } from './schemas/file_pb';
+import type { RenderWorkerData, RenderWorkerResult } from './render-worker';
 
-const MAX_PREVIEW_PX = 400;
-const RETINA_SCALE = 2;
-const MAX_PREVIEW_SIZE = MAX_PREVIEW_PX * RETINA_SCALE; // 800
+// Re-exported so existing consumers (and their tests) keep a single import
+// surface; the implementations live in preview-geometry.ts so the render
+// worker can use them without loading this module.
+export { previewDimensions, parseSvgDimensions } from './preview-geometry';
 
 /**
- * Compute the single constraining dimension to pass to renderPng.
- *
- * Returns only the constraining dimension set to `maxSize`, with
- * the other set to 0 so the engine derives it from the aspect ratio.
- * This avoids the width-precedence bug where passing both non-zero
- * causes the engine to ignore the height constraint.
+ * TOTAL wall-clock budget for one preview request, measured from the
+ * renderToPNG call -- it covers time queued for a render slot plus the render
+ * itself, enforced by terminating the worker. Generous -- a routine preview,
+ * including the worker compiling its own WASM instance, finishes well under a
+ * second -- but bounded, so a pathological or adversarial model costs one
+ * failed request instead of pinning a render slot (and, before issue #694,
+ * the whole event loop).
+ */
+export const RENDER_TIMEOUT_MS = 10_000;
+
+/**
+ * At most this many render workers at once. The cap bounds worker fan-out
+ * and CPU contention with the Express event loop while still letting renders
+ * overlap. It does NOT make worst-case memory survivable: each worker's WASM
+ * memory can grow to the 1 GiB module cap, and two maxed-out workers exceed
+ * an F4's RAM -- that exposure predates the worker split; it's now contained
+ * to an instance restart (with app.yaml max_instances capping the cost)
+ * instead of undefined in-process behavior. Excess renders queue FIFO; queue
+ * depth is implicitly bounded because every waiting render is an in-flight
+ * HTTP request and GAE caps those at max_concurrent_requests (100).
  */
-export function previewDimensions(
-  svgWidth: number,
-  svgHeight: number,
-  maxSize: number,
-): { width: number; height: number } {
-  if (svgWidth <= 0 || svgHeight <= 0 || maxSize <= 0) {
-    return { width: 0, height: 0 };
+const MAX_CONCURRENT_RENDERS = 2;
+
+export interface RenderLimiter {
+  run<T>(task: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Minimal FIFO concurrency limiter. A slot is released when the task settles
+ * (resolve or reject), so a failed or timed-out render can never leak a slot.
+ * Exported for direct unit testing.
+ */
+export function createRenderLimiter(maxConcurrent: number): RenderLimiter {
+  if (!Number.isInteger(maxConcurrent) || maxConcurrent <= 0) {
+    throw new Error(`maxConcurrent must be a positive integer, got ${maxConcurrent}`);
   }
-  if (svgWidth >= svgHeight) {
-    // Landscape or square: constrain width, let the engine derive height
-    return { width: maxSize, height: 0 };
+
+  let active = 0;
+  const waiters: Array<() => void> = [];
+
+  const acquire = (): Promise<void> => {
+    if (active < maxConcurrent) {
+      active++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      waiters.push(() => {
+        active++;
+        resolve();
+      });
+    });
+  };
+
+  const release = (): void => {
+    active--;
+    const next = waiters.shift();
+    if (next) {
+      next();
+    }
+  };
+
+  return {
+    async run<T>(task: () => Promise<T>): Promise<T> {
+      await acquire();
+      try {
+        return await task();
+      } finally {
+        release();
+      }
+    },
+  };
+}
+
+const renderLimiter = createRenderLimiter(MAX_CONCURRENT_RENDERS);
+
+/** Test-only overrides; production callers pass no options. */
+export interface RenderOptions {
+  /** Override RENDER_TIMEOUT_MS (e.g. to exercise the timeout path fast). */
+  timeoutMs?: number;
+  /** Override the worker entry (e.g. a hanging or failing fixture). */
+  workerScript?: string;
+}
+
+/**
+ * Locate the compiled worker entry. In production this module runs from the
+ * compiled lib/, so render-worker.js is a sibling. Under ts-jest __dirname is
+ * the source directory, where only render-worker.ts exists; fall back to the
+ * compiled copy under lib/ (produced by `pnpm build` -- tests that need it
+ * skip when it's absent).
+ */
+function resolveWorkerScript(): string {
+  const candidates = [path.join(__dirname, 'render-worker.js'), path.join(__dirname, 'lib', 'render-worker.js')];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
   }
-  // Portrait: constrain height, let the engine derive width
-  return { width: 0, height: maxSize };
+  throw new Error(
+    `render-worker.js not found (looked at ${candidates.join(', ')}); ` +
+      'run `pnpm --filter @simlin/server run build`',
+  );
 }
 
 /**
- * Parse the viewBox dimensions from an SVG string.
+ * Spawn a worker for one render and settle exactly once: on the worker's
+ * result message, its 'error'/'messageerror'/'exit' events, or the deadline.
+ * The worker is terminated on every settle path -- terminate() is idempotent
+ * and a no-op on an already-exited thread, so unconditional termination is
+ * the simplest way to guarantee no thread outlives its request.
  *
- * Returns `{width, height}` from the third and fourth viewBox values.
- * Falls back to `{0, 0}` when the viewBox is absent or unparseable.
+ * `deadline` is an epoch-ms timestamp captured before the render queued for a
+ * slot; the worker only gets whatever budget remains. `timeoutMs` is the
+ * original total budget, used for the error message.
  */
-export function parseSvgDimensions(svg: string): { width: number; height: number } {
-  const match = svg.match(/viewBox="([^"]*)"/);
-  if (!match) {
-    return { width: 0, height: 0 };
-  }
-  const parts = match[1].trim().split(/\s+/).map(Number);
-  if (parts.length < 4 || parts.some(isNaN)) {
-    return { width: 0, height: 0 };
-  }
-  return { width: parts[2], height: parts[3] };
+function runRenderWorker(
+  projectContents: Uint8Array,
+  deadline: number,
+  timeoutMs: number,
+  workerScript: string,
+): Promise<Uint8Array> {
+  return new Promise<Uint8Array>((resolve, reject) => {
+    const data: RenderWorkerData = { projectContents };
+    const worker = new Worker(workerScript, { workerData: data });
+    let settled = false;
+
+    const settle = (outcome: () => void): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      outcome();
+    };
+
+    const timer = setTimeout(
+      () => {
+        settle(() => reject(new Error(`preview render timed out after ${timeoutMs}ms`)));
+      },
+      Math.max(0, deadline - Date.now()),
+    );
+
+    worker.on('message', (result: RenderWorkerResult) => {
+      if (result.ok) {
+        settle(() => resolve(result.png));
+      } else {
+        settle(() => reject(new Error(result.error)));
+      }
+    });
+    worker.on('error', (err) => {
+      settle(() => reject(err));
+    });
+    worker.on('messageerror', (err) => {
+      // A result that fails to deserialize would otherwise leave us waiting
+      // out the deadline and reporting a misleading "timed out".
+      settle(() => reject(new Error(`render worker result could not be deserialized: ${err.message}`)));
+    });
+    worker.on('exit', (code) => {
+      // Reached only if the worker exits before posting a result (pending
+      // messages are delivered ahead of 'exit'; settle() dedupes regardless).
+      settle(() => reject(new Error(`render worker exited with code ${code} before producing a result`)));
+    });
+  });
 }
 
-export async function renderToPNG(fileDoc: File): Promise<Uint8Array> {
-  const engineProject = await EngineProject.openProtobuf(fileDoc.getProjectContents_asU8());
-  try {
-    const svg = await engineProject.renderSvgString('main');
-    const intrinsic = parseSvgDimensions(svg);
-    const dims = previewDimensions(intrinsic.width, intrinsic.height, MAX_PREVIEW_SIZE);
-    return await engineProject.renderPng('main', dims.width, dims.height);
-  } finally {
-    await engineProject.dispose();
-  }
+/**
+ * Render a project file's `main` model to a preview PNG in an isolated,
+ * per-request worker thread. The timeout is a TOTAL wall-clock budget from
+ * this call, covering both queueing for a render slot and the render itself.
+ * Failures (bad model, worker crash, timeout) reject; callers translate that
+ * into a 500 for the one affected request.
+ */
+export async function renderToPNG(fileDoc: File, options?: RenderOptions): Promise<Uint8Array> {
+  const projectContents = fileDoc.getProjectContents_asU8();
+  const timeoutMs = options?.timeoutMs ?? RENDER_TIMEOUT_MS;
+  const workerScript = options?.workerScript ?? resolveWorkerScript();
+  // Capture the deadline before enqueueing so queue wait counts against the
+  // budget: the client has been waiting the whole time, and a request whose
+  // deadline lapsed in the queue must not burn a slot on a doomed render.
+  const deadline = Date.now() + timeoutMs;
+  return renderLimiter.run(() => {
+    if (Date.now() >= deadline) {
+      return Promise.reject(new Error(`preview render timed out after ${timeoutMs}ms waiting for a render slot`));
+    }
+    return runRenderWorker(projectContents, deadline, timeoutMs, workerScript);
+  });
 }
diff --git a/src/server/tests/fixtures/worker-error-result.js b/src/server/tests/fixtures/worker-error-result.js
new file mode 100644
index 000000000..5389f4240
--- /dev/null
+++ b/src/server/tests/fixtures/worker-error-result.js
@@ -0,0 +1,10 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Test fixture standing in for render-worker.js: reports a render failure the
+// way the real worker does when the engine rejects a model.
+'use strict';
+const { parentPort } = require('worker_threads');
+
+parentPort.postMessage({ ok: false, error: 'boom: intentional render failure' });
diff --git a/src/server/tests/fixtures/worker-exit.js b/src/server/tests/fixtures/worker-exit.js
new file mode 100644
index 000000000..6e2befb3b
--- /dev/null
+++ b/src/server/tests/fixtures/worker-exit.js
@@ -0,0 +1,8 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Test fixture standing in for render-worker.js: exits without ever posting a
+// result, which surfaces on the main thread as the Worker 'exit' event.
+'use strict';
+process.exit(7);
diff --git a/src/server/tests/fixtures/worker-hang.js b/src/server/tests/fixtures/worker-hang.js
new file mode 100644
index 000000000..7284ec8aa
--- /dev/null
+++ b/src/server/tests/fixtures/worker-hang.js
@@ -0,0 +1,9 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Test fixture standing in for render-worker.js: never responds. The interval
+// keeps the thread alive indefinitely so only worker.terminate() -- the
+// timeout path under test -- can end it.
+'use strict';
+setInterval(() => {}, 1000);
diff --git a/src/server/tests/fixtures/worker-success.js b/src/server/tests/fixtures/worker-success.js
new file mode 100644
index 000000000..8bd7f30eb
--- /dev/null
+++ b/src/server/tests/fixtures/worker-success.js
@@ -0,0 +1,11 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Test fixture standing in for render-worker.js: echoes the projectContents
+// bytes back as the "png" so tests can verify the payload round-trips through
+// workerData and the result message without needing the WASM engine.
+'use strict';
+const { parentPort, workerData } = require('worker_threads');
+
+parentPort.postMessage({ ok: true, png: workerData.projectContents });
diff --git a/src/server/tests/fixtures/worker-throw.js b/src/server/tests/fixtures/worker-throw.js
new file mode 100644
index 000000000..f8c0b5ad8
--- /dev/null
+++ b/src/server/tests/fixtures/worker-throw.js
@@ -0,0 +1,8 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+// Test fixture standing in for render-worker.js: dies with an uncaught
+// exception, which surfaces on the main thread as the Worker 'error' event.
+'use strict';
+throw new Error('worker exploded');
diff --git a/src/server/tests/render-model-preview.test.ts b/src/server/tests/render-model-preview.test.ts
index a0eb364aa..52131f061 100644
--- a/src/server/tests/render-model-preview.test.ts
+++ b/src/server/tests/render-model-preview.test.ts
@@ -6,7 +6,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { Project as EngineProject } from '@simlin/engine';
-import { previewDimensions, parseSvgDimensions } from '../render';
+import { renderProjectToPng } from '../render-worker';
 
 const MAX_PREVIEW_SIZE = 800;
 
@@ -29,8 +29,10 @@ function readPngDimensions(png: Uint8Array): { width: number; height: number } {
   };
 }
 
-// Simulate the server's preview generation pipeline:
-// XMILE -> engine -> protobuf -> engine -> SVG (for dims) -> PNG
+// Drive the server's preview generation pipeline:
+// XMILE -> engine -> protobuf, then the worker's real pipeline function
+// (renderProjectToPng) run in-process so ts-jest tests the current source
+// rather than a compiled copy or an inline duplicate of the pipeline.
 async function generatePreview(modelName: string): Promise<Uint8Array> {
   const xmile = loadDefaultProject(modelName);
 
@@ -39,16 +41,8 @@ async function generatePreview(modelName: string): Promise<Uint8Array> {
   const protobuf = await importProject.serializeProtobuf();
   await importProject.dispose();
 
-  // Step 2: Load from protobuf, get SVG dimensions, render PNG (same as render.ts)
-  const engineProject = await EngineProject.openProtobuf(protobuf);
-  try {
-    const svg = await engineProject.renderSvgString('main');
-    const intrinsic = parseSvgDimensions(svg);
-    const dims = previewDimensions(intrinsic.width, intrinsic.height, MAX_PREVIEW_SIZE);
-    return await engineProject.renderPng('main', dims.width, dims.height);
-  } finally {
-    await engineProject.dispose();
-  }
+  // Step 2: the exact code the render worker executes
+  return renderProjectToPng(protobuf);
 }
 
 describe('model preview rendering', () => {
diff --git a/src/server/tests/render-to-png.test.ts b/src/server/tests/render-to-png.test.ts
new file mode 100644
index 000000000..f49953a03
--- /dev/null
+++ b/src/server/tests/render-to-png.test.ts
@@ -0,0 +1,212 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { Project as EngineProject } from '@simlin/engine';
+
+import { createRenderLimiter, renderToPNG } from '../render';
+import { File } from '../schemas/file_pb';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+function fixture(name: string): string {
+  return path.join(FIXTURES_DIR, name);
+}
+
+function makeFile(contents: Uint8Array): File {
+  const file = new File();
+  file.setProjectContents(contents);
+  return file;
+}
+
+// Assert a settled promise rejected and return its stringified reason
+// (e.g. "Error: preview render timed out after 300ms").
+function rejectionMessage(result: PromiseSettledResult<unknown>): string {
+  expect(result.status).toBe('rejected');
+  return String((result as PromiseRejectedResult).reason);
+}
+
+// Resolve one macrotask so already-runnable limiter tasks get a chance to
+// start before we assert on which of them ran.
+function flush(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+interface Deferred {
+  promise: Promise<void>;
+  resolve: () => void;
+  reject: (err: Error) => void;
+}
+
+function deferred(): Deferred {
+  let resolve!: () => void;
+  let reject!: (err: Error) => void;
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe('createRenderLimiter', () => {
+  it('rejects a non-positive concurrency cap', () => {
+    expect(() => createRenderLimiter(0)).toThrow(/positive/);
+    expect(() => createRenderLimiter(-1)).toThrow(/positive/);
+  });
+
+  it('runs tasks up to the cap and queues the rest in FIFO order', async () => {
+    const limiter = createRenderLimiter(2);
+    const started: string[] = [];
+    const gates = { a: deferred(), b: deferred(), c: deferred(), d: deferred() };
+
+    const task = (name: keyof typeof gates) => () => {
+      started.push(name);
+      return gates[name].promise;
+    };
+
+    const runs = [limiter.run(task('a')), limiter.run(task('b')), limiter.run(task('c')), limiter.run(task('d'))];
+    await flush();
+    expect(started).toEqual(['a', 'b']);
+
+    gates.b.resolve();
+    await runs[1];
+    await flush();
+    expect(started).toEqual(['a', 'b', 'c']);
+
+    gates.a.resolve();
+    await runs[0];
+    await flush();
+    expect(started).toEqual(['a', 'b', 'c', 'd']);
+
+    gates.c.resolve();
+    gates.d.resolve();
+    await Promise.all(runs);
+  });
+
+  it('releases the slot when a task rejects', async () => {
+    const limiter = createRenderLimiter(1);
+    await expect(limiter.run(() => Promise.reject(new Error('first fails')))).rejects.toThrow('first fails');
+    await expect(limiter.run(() => Promise.resolve('second runs'))).resolves.toBe('second runs');
+  });
+
+  it('propagates task results', async () => {
+    const limiter = createRenderLimiter(1);
+    await expect(limiter.run(() => Promise.resolve(42))).resolves.toBe(42);
+  });
+});
+
+describe('renderToPNG worker orchestration', () => {
+  it('resolves with the bytes the worker posts back', async () => {
+    const contents = new Uint8Array([1, 2, 3, 4, 5]);
+    const png = await renderToPNG(makeFile(contents), { workerScript: fixture('worker-success.js') });
+    expect(Array.from(png)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it('rejects when the worker reports a render failure', async () => {
+    await expect(
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-error-result.js') }),
+    ).rejects.toThrow('boom: intentional render failure');
+  });
+
+  it('rejects when the worker dies with an uncaught exception', async () => {
+    await expect(
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-throw.js') }),
+    ).rejects.toThrow('worker exploded');
+  });
+
+  it('rejects when the worker exits without producing a result', async () => {
+    await expect(
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-exit.js') }),
+    ).rejects.toThrow(/exited with code 7/);
+  });
+
+  it('rejects when the worker script does not exist', async () => {
+    await expect(
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('does-not-exist.js') }),
+    ).rejects.toThrow();
+  });
+
+  it('times out a hung worker', async () => {
+    await expect(
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-hang.js'), timeoutMs: 200 }),
+    ).rejects.toThrow(/timed out after 200ms/);
+  });
+
+  it('releases both render slots after timed-out renders (no slot leak)', async () => {
+    // Saturate the concurrency cap (2) with hung workers; if a timeout leaked
+    // its slot, the follow-up success render below would never start.
+    // allSettled (not sequential awaits) so every rejection has a handler
+    // attached from the start -- both timers fire together, and a rejection
+    // that lands before its `await` would otherwise be flagged by jest as an
+    // unhandled rejection.
+    const hung = await Promise.allSettled([
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-hang.js'), timeoutMs: 150 }),
+      renderToPNG(makeFile(new Uint8Array([2])), { workerScript: fixture('worker-hang.js'), timeoutMs: 150 }),
+    ]);
+    expect(rejectionMessage(hung[0])).toMatch(/timed out/);
+    expect(rejectionMessage(hung[1])).toMatch(/timed out/);
+
+    const contents = new Uint8Array([9, 9, 9]);
+    const png = await renderToPNG(makeFile(contents), { workerScript: fixture('worker-success.js') });
+    expect(Array.from(png)).toEqual([9, 9, 9]);
+  });
+
+  it('rejects a render whose total deadline lapsed while queued, without spawning a worker', async () => {
+    // Occupy both slots with hung workers for ~300ms. The third render's
+    // 50ms budget expires while it waits in the queue, so when a slot frees
+    // it must fail fast with the distinct waiting-for-slot message -- even
+    // though its worker script would succeed instantly if spawned.
+    // allSettled for the same unhandled-rejection reason as above.
+    const results = await Promise.allSettled([
+      renderToPNG(makeFile(new Uint8Array([1])), { workerScript: fixture('worker-hang.js'), timeoutMs: 300 }),
+      renderToPNG(makeFile(new Uint8Array([2])), { workerScript: fixture('worker-hang.js'), timeoutMs: 300 }),
+      renderToPNG(makeFile(new Uint8Array([3])), { workerScript: fixture('worker-success.js'), timeoutMs: 50 }),
+    ]);
+    expect(rejectionMessage(results[0])).toMatch(/timed out after 300ms/);
+    expect(rejectionMessage(results[1])).toMatch(/timed out after 300ms/);
+    expect(rejectionMessage(results[2])).toMatch(/timed out after 50ms waiting for a render slot/);
+  });
+});
+
+// End-to-end: spawn the REAL compiled worker (lib/render-worker.js), which
+// instantiates its own engine WASM inside the thread -- proving the WASM path
+// resolution works from a worker the same way it does on the main thread.
+// `pnpm build` produces lib/; skip (not fail) when it's absent so the suite
+// stays runnable on a source-only checkout. CI and pre-commit build first, so
+// this always runs there. Note the compiled worker can be stale relative to
+// render-worker.ts; the pipeline logic itself is tested from source in
+// render-model-preview.test.ts.
+const builtWorker = path.join(__dirname, '..', 'lib', 'render-worker.js');
+const describeIfBuilt = fs.existsSync(builtWorker) ? describe : describe.skip;
+if (!fs.existsSync(builtWorker)) {
+  console.warn(
+    `[render-to-png] skipping real-worker e2e: ${builtWorker} not found; run \`pnpm --filter @simlin/server run build\`.`,
+  );
+}
+
+describeIfBuilt('renderToPNG end to end (real worker, real WASM)', () => {
+  it('renders the population default project to a bounded PNG', async () => {
+    const modelPath = path.join(__dirname, '..', '..', '..', 'default_projects', 'population', 'model.xmile');
+    const xmile = fs.readFileSync(modelPath, 'utf8');
+    const importProject = await EngineProject.open(xmile);
+    const protobuf = await importProject.serializeProtobuf();
+    await importProject.dispose();
+
+    // No options: exercises the default worker-script resolution and timeout.
+    const png = await renderToPNG(makeFile(protobuf));
+
+    // PNG signature
+    expect(png[0]).toBe(137);
+    expect(png[1]).toBe(80); // P
+    expect(png[2]).toBe(78); // N
+    expect(png[3]).toBe(71); // G
+
+    // IHDR width/height are big-endian at offsets 16/20
+    const buffer = Buffer.from(png);
+    expect(buffer.readUInt32BE(16)).toBeLessThanOrEqual(800);
+    expect(buffer.readUInt32BE(20)).toBeLessThanOrEqual(800);
+  }, 20_000); // the worker compiles its own WASM instance; allow headroom on slow machines
+});

From b9fe44171a2883c851f60c49c1986072fe41bca2 Mon Sep 17 00:00:00 2001
From: Bobby Powers <bobbypowers@gmail.com>
Date: Wed, 1 Jul 2026 13:01:25 -0700
Subject: [PATCH 3/4] engine/deploy: fix cross-origin embeds via a blob worker
 trampoline and /static CORS

The embeddable web component was broken on third-party pages: the
engine runs in a Web Worker whose chunk URL resolves (via the
component build's assetPrefix 'auto') to an absolute app.simlin.com
URL, and the Worker constructor enforces same-origin regardless of
CORS, so embeds loaded project data but never initialized the engine.

Boot the worker through a same-origin blob: trampoline when the
resolved chunk URL is cross-origin: worker-trampoline.ts holds the
pure origin-decision and trampoline-source logic plus an injectable
spawn shell that briefly intercepts the global Worker constructor to
observe the URL the bundler resolved (the new Worker(new URL(...))
expression must stay inline or rspack stops bundling the worker
chunk). The imported chunk keeps its https URL identity, so its
internal WASM fetch resolves against app.simlin.com; engine-worker.ts
overrides the runtime publicPath in the trampolined (classic,
blob-origin) context where self.location would otherwise poison it.
The same-origin path -- the main app -- constructs through the native
Worker with identical arguments, verified against a rebuilt bundle.

Serve Access-Control-Allow-Origin: * on the /static GAE handler so
the trampoline's cross-origin import and the worker's WASM fetch pass
CORS; everything under /static is public build output.
validate-app-prod-config.mjs now requires the header in the
operator-local .app.prod.yaml, and the deploy smoke list gains a
header curl plus a real two-origin embed check (the remaining
browser-only semantics are uncoverable by unit tests; issue 825
tracks an automated Playwright harness).
---
 app.yaml                                      |   9 +
 docs/dev/deploy.md                            |   5 +-
 .../tests/validate-app-prod-config.test.mjs   | 104 +++++-
 scripts/validate-app-prod-config.mjs          |  16 +
 src/engine/CLAUDE.md                          |   2 +
 src/engine/src/backend-factory.browser.ts     |  60 +++-
 src/engine/src/engine-worker.ts               |  21 ++
 src/engine/src/worker-trampoline.ts           | 253 ++++++++++++++
 src/engine/tests/worker-trampoline.test.ts    | 324 ++++++++++++++++++
 9 files changed, 781 insertions(+), 13 deletions(-)
 create mode 100644 src/engine/src/worker-trampoline.ts
 create mode 100644 src/engine/tests/worker-trampoline.test.ts

diff --git a/app.yaml b/app.yaml
index 424409f73..023fb1f15 100644
--- a/app.yaml
+++ b/app.yaml
@@ -16,6 +16,15 @@ handlers:
 - url: /static
   static_dir: public/static
   secure: always
+  http_headers:
+    # The embeddable web component (sd-component.js) is hotlinked from
+    # third-party origins (issue #688); its engine worker's WASM fetch (and
+    # any @font-face/CSS asset loads) are cross-origin CORS requests against
+    # these assets. They are public, immutable, content-hashed files served
+    # without credentials, so a wildcard origin is appropriate and adds no
+    # risk. Mirror this into .app.prod.yaml --
+    # scripts/validate-app-prod-config.mjs enforces it there.
+    Access-Control-Allow-Origin: "*"
 
 - url: /$
   static_files: public/index.html
diff --git a/docs/dev/deploy.md b/docs/dev/deploy.md
index f78b625ab..5f2950f57 100644
--- a/docs/dev/deploy.md
+++ b/docs/dev/deploy.md
@@ -104,6 +104,7 @@ On the instance GAE runs `pnpm install`, then the root `start` script: `node src
 - `runtime`: `nodejs24`. (`nodejs18` is EOL on GAE; `nodejs16`, the runtime of the last deploy before May 2026, is gone entirely -- which is why there's no "redeploy the old commit" rollback.)
 - `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS`: `''`. The local deploy script already runs the monorepo build and stages the exact artifact to upload; this prevents App Engine's Node buildpack from running the root `build` script again during staging.
 - `automatic_scaling.max_instances`: `8`. Cost cap so a render storm or crash loop can't fan out F4 instances without bound (issue #694). **Mirror this into `.app.prod.yaml`** -- both deploy scripts run `scripts/validate-app-prod-config.mjs`, which fails the deploy if it's missing or not a positive integer. Raise it deliberately if organic traffic ever needs more instances.
+- The `/static` handler's `http_headers` with `Access-Control-Allow-Origin: "*"`. Third-party pages hotlink `sd-component.js`, and its engine worker's WASM fetch (plus fonts/CSS assets) are cross-origin CORS requests against `/static` (issue #688); without this header embeds load their data but the engine never initializes. The assets are public, immutable, and served without credentials, so the wildcard adds no risk. **Mirror this into `.app.prod.yaml`** -- `scripts/validate-app-prod-config.mjs` fails the deploy if the header is missing.
 - The handler list: `/static`, `/`, `/new`, `/legal*`, `/privacy`, `robots.txt`, `ads.txt`, favicon, `manifest.json`, then `/.*` -> `script: auto`. The `/` and `/new` static HTML handlers carry CSP/HSTS headers because they bypass Express Helmet. The SPA's dynamic routes like `/:username/:projectName` fall through to `/.*`, i.e. the Express server.
 - `env_variables`: the committed `app.yaml` has none; the server needs a couple (next section). They live in `.app.prod.yaml`.
 
@@ -126,7 +127,7 @@ The server loads `config/default.json`, then `config/production.json` when `NODE
 - [ ] `git status` is clean.
 - [ ] `gcloud config get-value project` is the production project.
 - [ ] `gcloud app versions list --service=default` shows a known-good current version -- note its ID, that's your rollback target. (If GAE has garbage-collected it, there is no rollback; see below.)
-- [ ] `.app.prod.yaml` reconciled against `app.yaml` (`runtime: nodejs24`, `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''`, `automatic_scaling.max_instances: 8`, handlers, `authentication__seshcookie__key` set to the value already in use).
+- [ ] `.app.prod.yaml` reconciled against `app.yaml` (`runtime: nodejs24`, `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''`, `automatic_scaling.max_instances: 8`, handlers including the `/static` `Access-Control-Allow-Origin: "*"` header, `authentication__seshcookie__key` set to the value already in use).
 - [ ] `wasm-opt --version` works; `rustup show` lists the `wasm32-unknown-unknown` target.
 
 ## Post-deploy smoke test
@@ -136,7 +137,9 @@ Against the `--no-promote` version URL, then again on production:
 - `curl -sI https://<host>/` -> 200 HTML. View source: it links a hashed `/static/js/index.<hash>.js` (literal `<%= PUBLIC_URL %>` means the build was skipped) and `/static/css/index.<hash>.css`.
 - `curl -s https://<host>/healthz` -> 200 `ok`. This is the only check that exercises the Node server: `/` is a GAE static handler and stays green even when every Express instance is crash-looping (e.g. `ServerInitError`). A WASM preload failure aborts boot before the route mounts, so it shows up as a non-responding instance (connection failure / GAE 5xx), not a 503 -- treat any non-200 here as down. (The route's 503 branch is defense-in-depth, not the expected failure signal.)
 - `curl -sI https://<host>/static/js/sd-component.js` -> 200 -- the embeddable web component; external sites `<script src>` this exact path.
+- `curl -H "Origin: https://example.com" -sI https://<host>/static/js/sd-component.js` -> response includes `access-control-allow-origin: *`. Cross-origin embeds need this on everything under `/static` (worker chunk, WASM -- issue #688). GAE emits `http_headers` unconditionally (the request `Origin` header doesn't matter), so any curl shows it; the earlier smoke checks missed its absence only because they never asserted on response headers. Without it, embeds load data but never initialize the engine.
 - `curl -sI https://<host>/static/wasm/<hash>.module.wasm` -> 200, `content-type: application/wasm`.
+- Full embed check (the header curl only proves CORS, not the blob-trampoline worker boot): serve `<script src="https://<host>/static/js/sd-component.js"></script><sd-model username="..." projectName="..."></sd-model>` from a different origin (e.g. `python3 -m http.server` on localhost) and confirm the diagram renders and simulates with no console errors.
 - `curl -sI` on `/robots.txt`, `/manifest.json`, `/favicon.ico`, `/legal/`, `/privacy/` -> 200; `curl -I http://<host>/` -> 301 to https.
 - Browser: log in with Google, land on Home, no console errors.
 - New-user flow: sign in with a fresh account, claim a username, confirm the example projects appear and one opens and simulates.
diff --git a/scripts/tests/validate-app-prod-config.test.mjs b/scripts/tests/validate-app-prod-config.test.mjs
index a06ca26ed..d86375c6d 100644
--- a/scripts/tests/validate-app-prod-config.test.mjs
+++ b/scripts/tests/validate-app-prod-config.test.mjs
@@ -6,6 +6,9 @@ import { validateAppProdConfig } from '../validate-app-prod-config.mjs';
 const MAX_INSTANCES_MESSAGE =
   'automatic_scaling.max_instances must be set to a positive integer (cost cap; mirror the committed app.yaml)';
 
+const STATIC_CORS_MESSAGE =
+  'handlers must include a /static handler with http_headers.Access-Control-Allow-Origin set to "*" (cross-origin embeds, issue #688; mirror the committed app.yaml)';
+
 // Every fixture that isn't specifically exercising the max_instances check
 // carries this block so its expected messages stay focused on one concern.
 const scalingBlock = `
@@ -13,6 +16,16 @@ automatic_scaling:
   max_instances: 8
 `;
 
+// Likewise for fixtures not exercising the /static CORS check.
+const staticHandlerBlock = `
+handlers:
+- url: /static
+  static_dir: public/static
+  secure: always
+  http_headers:
+    Access-Control-Allow-Origin: "*"
+`;
+
 const validConfig = `
 runtime: nodejs24
 
@@ -22,7 +35,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: production-secret
-${scalingBlock}`;
+${scalingBlock}${staticHandlerBlock}`;
 
 function messagesFor(source) {
   return validateAppProdConfig(source, '.app.prod.yaml').map((error) => error.message);
@@ -46,6 +59,7 @@ runtime: nodejs24
       'env_variables.NODE_ENV must be set to production',
       'env_variables.authentication__seshcookie__key must be set to the existing production session key',
       MAX_INSTANCES_MESSAGE,
+      STATIC_CORS_MESSAGE,
     ]);
   });
 
@@ -55,7 +69,7 @@ env_variables:
   NODE_ENV: production
   GOOGLE_NODE_RUN_SCRIPTS: ''
   authentication__seshcookie__key: production-secret
-${scalingBlock}`);
+${scalingBlock}${staticHandlerBlock}`);
 
     assert.deepEqual(messages, ['build_env_variables.GOOGLE_NODE_RUN_SCRIPTS must be set to an empty string']);
   });
@@ -67,7 +81,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: production-secret
-${scalingBlock}`);
+${scalingBlock}${staticHandlerBlock}`);
 
     assert.deepEqual(messages, ['build_env_variables.GOOGLE_NODE_RUN_SCRIPTS must be set to an empty string']);
   });
@@ -79,7 +93,7 @@ build_env_variables:
   authentication__seshcookie__key: production-secret
 env_variables:
   NODE_ENV: production
-${scalingBlock}`);
+${scalingBlock}${staticHandlerBlock}`);
 
     assert.deepEqual(messages, [
       'env_variables.authentication__seshcookie__key must be set to the existing production session key',
@@ -95,7 +109,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: ${value}
-${scalingBlock}`),
+${scalingBlock}${staticHandlerBlock}`),
         ['env_variables.authentication__seshcookie__key must be set to the existing production session key'],
       );
     }
@@ -107,7 +121,7 @@ build_env_variables:
   GOOGLE_NODE_RUN_SCRIPTS: ''
 env_variables:
   authentication__seshcookie__key: production-secret
-${scalingBlock}`);
+${scalingBlock}${staticHandlerBlock}`);
 
     assert.deepEqual(messages, ['env_variables.NODE_ENV must be set to production']);
   });
@@ -120,14 +134,14 @@ build_env_variables:
   NODE_ENV: production
 env_variables:
   authentication__seshcookie__key: production-secret
-${scalingBlock}`,
+${scalingBlock}${staticHandlerBlock}`,
       `
 build_env_variables:
   GOOGLE_NODE_RUN_SCRIPTS: ''
 env_variables:
   NODE_ENV: development
   authentication__seshcookie__key: production-secret
-${scalingBlock}`,
+${scalingBlock}${staticHandlerBlock}`,
     ]) {
       assert.deepEqual(messagesFor(source), ['env_variables.NODE_ENV must be set to production']);
     }
@@ -140,7 +154,7 @@ build_env_variables:
 env_variables:
   NODE_ENV: production
   authentication__seshcookie__key: production-secret
-`);
+${staticHandlerBlock}`);
 
     assert.deepEqual(messages, [MAX_INSTANCES_MESSAGE]);
   });
@@ -156,13 +170,83 @@ env_variables:
   authentication__seshcookie__key: production-secret
 automatic_scaling:
   max_instances: ${value}
-`),
+${staticHandlerBlock}`),
         [MAX_INSTANCES_MESSAGE],
         `max_instances: ${value} should be rejected`,
       );
     }
   });
 
+  it('rejects a config with no handlers list', () => {
+    const messages = messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+${scalingBlock}`);
+
+    assert.deepEqual(messages, [STATIC_CORS_MESSAGE]);
+  });
+
+  it('rejects a /static handler without the CORS header', () => {
+    const messages = messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+${scalingBlock}
+handlers:
+- url: /static
+  static_dir: public/static
+  secure: always
+`);
+
+    assert.deepEqual(messages, [STATIC_CORS_MESSAGE]);
+  });
+
+  it('rejects a /static handler whose CORS header is not the wildcard', () => {
+    const messages = messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+${scalingBlock}
+handlers:
+- url: /static
+  static_dir: public/static
+  secure: always
+  http_headers:
+    Access-Control-Allow-Origin: https://app.simlin.com
+`);
+
+    assert.deepEqual(messages, [STATIC_CORS_MESSAGE]);
+  });
+
+  it('finds the /static handler anywhere in the handlers list', () => {
+    const messages = messagesFor(`
+build_env_variables:
+  GOOGLE_NODE_RUN_SCRIPTS: ''
+env_variables:
+  NODE_ENV: production
+  authentication__seshcookie__key: production-secret
+${scalingBlock}
+handlers:
+- url: /$
+  static_files: public/index.html
+  upload: public/index.html
+- url: /static
+  static_dir: public/static
+  secure: always
+  http_headers:
+    Access-Control-Allow-Origin: '*'
+`);
+
+    assert.deepEqual(messages, []);
+  });
+
   it('rejects malformed YAML', () => {
     const messages = messagesFor(`
 build_env_variables:
diff --git a/scripts/validate-app-prod-config.mjs b/scripts/validate-app-prod-config.mjs
index 42a74f870..da056e90e 100644
--- a/scripts/validate-app-prod-config.mjs
+++ b/scripts/validate-app-prod-config.mjs
@@ -72,6 +72,22 @@ export function validateAppProdConfig(source, filename = '.app.prod.yaml') {
     });
   }
 
+  // Cross-origin embed contract (issue #688): third-party pages hotlink
+  // sd-component.js, and its engine worker/WASM loads are cross-origin
+  // requests against /static. Without the wildcard ACAO header the embed
+  // silently fails to initialize the engine -- a regression no same-origin
+  // smoke check can catch, so enforce the committed app.yaml's header here.
+  const handlers = Array.isArray(config.handlers) ? config.handlers : [];
+  const staticHandler = handlers.find((handler) => isRecord(handler) && handler.url === '/static');
+  const headers = isRecord(staticHandler) ? staticHandler.http_headers : undefined;
+  const allowOrigin = isRecord(headers) ? headers['Access-Control-Allow-Origin'] : undefined;
+  if (allowOrigin !== '*') {
+    errors.push({
+      message:
+        'handlers must include a /static handler with http_headers.Access-Control-Allow-Origin set to "*" (cross-origin embeds, issue #688; mirror the committed app.yaml)',
+    });
+  }
+
   return errors;
 }
 
diff --git a/src/engine/CLAUDE.md b/src/engine/CLAUDE.md
index 8fac063fc..20e9ba4c0 100644
--- a/src/engine/CLAUDE.md
+++ b/src/engine/CLAUDE.md
@@ -29,6 +29,7 @@ For build/test/lint commands, see [docs/dev/commands.md](/docs/dev/commands.md).
 - `src/patch.ts` -- Model patching logic
 - `src/worker-protocol.ts` -- Worker message protocol
 - `src/backend-factory.ts` / `.browser.ts` / `.node.ts` -- Platform-specific backend factories
+- `src/worker-trampoline.ts` -- Cross-origin embed support (issue #688): pure decision/construction functions plus an injectable spawn shell that boots the engine worker through a same-origin blob: trampoline when the resolved chunk URL is cross-origin (third-party pages hotlinking sd-component.js). The bundler-facing constraints (inline `new Worker(new URL(...))` pattern, classic-worker downgrade under UMD, `publicPath: 'auto'` deriving from `self.location` in classic worker chunks) are documented in the module header; `backend-factory.browser.ts` and `engine-worker.ts` are the two consumers
 - `src/internal/` -- Internal modules (project, model, memory, error, import-export)
 - `src/internal/wasmgen.ts` -- `simlin_model_compile_to_wasm` FFI wrapper + the pure `parseWasmLayout` / `readStridedSeries` decoders for the per-model wasm blob (re-exported via `@simlin/engine/internal`)
 - `src/internal/canonicalize.ts` -- pure `canonicalizeIdent`, a faithful port of the Rust canonicalizer (used to resolve caller names to wasm-layout slots); not re-exported from the `internal` barrel
@@ -54,6 +55,7 @@ For build/test/lint commands, see [docs/dev/commands.md](/docs/dev/commands.md).
 - `tests/race.test.ts` -- Concurrency tests
 - `tests/cleanup.test.ts` -- Resource cleanup tests
 - `tests/wasmgen.test.ts`, `tests/canonicalize.test.ts` -- Unit tests for the pure layout decoders and `canonicalizeIdent`
+- `tests/worker-trampoline.test.ts` -- Unit tests for the cross-origin worker trampoline (origin decision, trampoline source, spawn interception with fake Worker/URL)
 - `tests/wasm-backend.test.ts`, `tests/wasm-model.test.ts`, `tests/worker-wasm.test.ts` -- wasm-vs-VM parity through `DirectBackend`, the `Model`/`Sim` facade, and the Web Worker
 - `tests/wasm-ltm.test.ts` -- LTM-on-wasm parity through the TypeScript surface: drives `Model.simulate({ engine: 'wasm', enableLtm: true })` end-to-end and asserts the resulting `Run.links` match the VM (link set, polarities, per-step scores). Includes a `WorkerBackend` twin and an Unsupported-LTM case that surfaces as a rejection without falling back to the VM
 - `tests/ltm-test-helpers.ts` -- shared helpers for the LTM tests (`linksByKey`, `expectScoresClose`); kept separate from the test files so the wasm and worker LTM suites compare links the same way
diff --git a/src/engine/src/backend-factory.browser.ts b/src/engine/src/backend-factory.browser.ts
index 2cae9716e..453aa2a35 100644
--- a/src/engine/src/backend-factory.browser.ts
+++ b/src/engine/src/backend-factory.browser.ts
@@ -9,21 +9,71 @@
  * keeping the main thread free for UI interaction. The Worker is created
  * lazily on first access and reused for all subsequent operations.
  *
+ * When the resolved worker chunk URL is cross-origin -- the embeddable web
+ * component hotlinked from a third-party page (issue #688) -- the worker is
+ * created through a same-origin blob trampoline instead, because the Worker
+ * constructor enforces the same-origin policy regardless of CORS. See
+ * worker-trampoline.ts for the mechanism.
+ *
  * This is selected at build time via tsconfig path mapping for browser builds.
  */
 
 import { EngineBackend } from './backend';
 import { WorkerBackend } from './worker-backend';
+import { spawnWithTrampoline } from './worker-trampoline';
 import type { WorkerRequest, WorkerResponse } from './worker-protocol';
 
+// Bundlers that implement webpack's module variables (rspack, webpack)
+// rewrite this free identifier to their runtime publicPath; with
+// assetPrefix 'auto' that value is derived from the embedding <script src>,
+// i.e. it carries the origin our assets actually live on. Under bundlers
+// that don't implement it (vite), the typeof guard below safely yields
+// 'undefined'.
+declare let __webpack_public_path__: string;
+
 let sharedBackend: EngineBackend | null = null;
 let sharedWorker: Worker | null = null;
+// blob: URL backing a trampolined worker; revoked once the worker proves it
+// loaded (first message) or failed (error event) so it doesn't leak.
+let sharedWorkerBlobUrl: string | null = null;
 
-function createWorkerBackend(): WorkerBackend {
-  const worker = new Worker(new URL('./engine-worker.js', import.meta.url), {
+function releaseWorkerBlobUrl(): void {
+  if (sharedWorkerBlobUrl !== null) {
+    URL.revokeObjectURL(sharedWorkerBlobUrl);
+    sharedWorkerBlobUrl = null;
+  }
+}
+
+function spawnBundledWorker(): Worker {
+  // IMPORTANT: this expression must stay literally in the form
+  // `new Worker(new URL('...', import.meta.url), ...)`. rspack, webpack and
+  // vite detect the worker (and bundle ./engine-worker.js into a worker
+  // chunk) only when the `new URL(...)` is inline inside the
+  // `new Worker(...)` call; hoisting the URL into a variable silently
+  // degrades the reference to a raw, unbundled asset (verified against
+  // rspack 1.7). Cross-origin handling happens in spawnWithTrampoline, which
+  // intercepts this construction to observe the resolved chunk URL.
+  return new Worker(new URL('./engine-worker.js', import.meta.url), {
     type: 'module',
   });
+}
+
+function bundlerPublicPath(): string | undefined {
+  return typeof __webpack_public_path__ === 'string' ? __webpack_public_path__ : undefined;
+}
+
+function pageOrigin(): string | undefined {
+  return typeof self !== 'undefined' && self.location ? self.location.origin : undefined;
+}
+
+function createWorkerBackend(): WorkerBackend {
+  const spawned = spawnWithTrampoline(globalThis as { Worker?: unknown }, spawnBundledWorker, {
+    pageOrigin: pageOrigin(),
+    publicPath: bundlerPublicPath(),
+  });
+  const worker = spawned.worker;
   sharedWorker = worker;
+  sharedWorkerBlobUrl = spawned.blobUrl;
 
   const backend = new WorkerBackend(
     (msg: WorkerRequest, transfer?: Transferable[]) => {
@@ -35,6 +85,10 @@ function createWorkerBackend(): WorkerBackend {
     },
     (callback: (msg: WorkerResponse) => void) => {
       worker.onmessage = (event: MessageEvent<WorkerResponse>) => {
+        // The first message proves the (possibly trampolined) worker script
+        // finished loading, so the backing blob URL is no longer needed.
+        // No-op on every later message and on the direct path.
+        releaseWorkerBlobUrl();
         callback(event.data);
       };
     },
@@ -42,6 +96,7 @@ function createWorkerBackend(): WorkerBackend {
 
   worker.onerror = (event: ErrorEvent) => {
     event.preventDefault();
+    releaseWorkerBlobUrl();
     const error = new Error(`Worker error: ${event.message}`);
     backend.handleWorkerError(error);
     sharedBackend = null;
@@ -70,4 +125,5 @@ export function resetBackend(): void {
     sharedWorker.terminate();
     sharedWorker = null;
   }
+  releaseWorkerBlobUrl();
 }
diff --git a/src/engine/src/engine-worker.ts b/src/engine/src/engine-worker.ts
index a6f0fcbc1..657ebaa28 100644
--- a/src/engine/src/engine-worker.ts
+++ b/src/engine/src/engine-worker.ts
@@ -22,6 +22,13 @@
  */
 
 import type { WorkerResponse } from './worker-protocol';
+import { ENGINE_PUBLIC_PATH_GLOBAL } from './worker-trampoline';
+
+// Rewritten by rspack/webpack to the runtime publicPath slot. Under bundlers
+// without webpack module variables (vite) the identifier stays undeclared,
+// which is still safe: `typeof` never throws on unresolvable references, it
+// yields 'undefined' and the guarded assignment below is skipped.
+declare let __webpack_public_path__: string;
 
 // Worker global scope interface for postMessage with Transferable support.
 // We define this locally rather than adding the webworker lib (which conflicts
@@ -34,6 +41,20 @@ interface WorkerGlobalScope {
 
 const workerSelf = self as unknown as WorkerGlobalScope;
 
+// Cross-origin embed support (issue #688): when the blob trampoline in
+// backend-factory.browser.ts boots this worker, the bundler's
+// `publicPath: 'auto'` runtime derives the asset base from `self.location`
+// -- the blob URL, i.e. the *embedding* page's origin -- so the WASM fetch
+// below would target the wrong host. The trampoline records the correct
+// asset root under a well-known global before loading this chunk; apply it
+// here, which runs after the bundler runtime computed its (wrong) value and
+// before the dynamic import below triggers the WASM load. Directly-loaded
+// workers never see the global, so their behavior is unchanged.
+const publicPathOverride = (self as unknown as Record<string, unknown>)[ENGINE_PUBLIC_PATH_GLOBAL];
+if (typeof publicPathOverride === 'string' && typeof __webpack_public_path__ === 'string') {
+  __webpack_public_path__ = publicPathOverride;
+}
+
 // Buffer for messages that arrive before the dynamic import resolves.
 let pendingMessages: unknown[] | null = [];
 
diff --git a/src/engine/src/worker-trampoline.ts b/src/engine/src/worker-trampoline.ts
new file mode 100644
index 000000000..75578494f
--- /dev/null
+++ b/src/engine/src/worker-trampoline.ts
@@ -0,0 +1,253 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+/**
+ * Cross-origin worker trampoline (issue #688).
+ *
+ * The embeddable web component is hotlinked from third-party pages as
+ * `<script src="https://app.simlin.com/static/js/sd-component.js">`, and its
+ * engine worker chunk resolves to an absolute app.simlin.com URL. The Worker
+ * constructor enforces the same-origin policy regardless of CORS, so on an
+ * embedding page `new Worker(<app.simlin.com url>)` throws a synchronous
+ * SecurityError and the engine can never initialize.
+ *
+ * The workaround is the standard blob trampoline: create the worker from a
+ * same-origin `blob:` URL whose only job is to load the real cross-origin
+ * chunk. Two wrinkles, both verified against the emitted rspack 1.7 output:
+ *
+ * 1. rspack downgrades `{ type: 'module' }` to a classic worker for
+ *    non-module (UMD) builds, so the trampoline body must be
+ *    `importScripts(...)` there, while module-worker bundlers (vite) need a
+ *    static `import` instead. `importScripts` of a cross-origin classic
+ *    script is permitted without CORS; the module `import` is a CORS fetch
+ *    and relies on the ACAO header app.yaml serves for /static.
+ *
+ * 2. Inside a classic worker chunk, rspack's `publicPath: 'auto'` runtime
+ *    derives the asset base from `self.location`, which for a trampolined
+ *    worker is the blob URL -- i.e. the *embedding* page's origin -- so the
+ *    engine's WASM fetch would target the wrong host. The trampoline
+ *    therefore smuggles the correct asset root through a well-known global
+ *    (ENGINE_PUBLIC_PATH_GLOBAL) that engine-worker.ts applies to
+ *    `__webpack_public_path__` before anything triggers the WASM load.
+ *    Module-format chunks resolve assets via `import.meta.url` (which a
+ *    static import preserves as the real chunk URL) and need no override.
+ *
+ * This module is the functional core: pure decision/construction functions
+ * plus an injectable spawn shell, all unit-testable without a real Worker.
+ */
+
+export type WorkerType = 'module' | 'classic';
+
+export interface DirectPlan {
+  readonly kind: 'direct';
+}
+
+export interface TrampolinePlan {
+  readonly kind: 'trampoline';
+  readonly source: string;
+}
+
+export type WorkerCreationPlan = DirectPlan | TrampolinePlan;
+
+/**
+ * Global property name the classic-worker trampoline uses to hand the
+ * bundler's asset root to engine-worker.ts. Shared as a constant so both
+ * sides of the handoff cannot drift apart.
+ */
+export const ENGINE_PUBLIC_PATH_GLOBAL = '__simlin_engine_public_path__';
+
+/**
+ * Whether creating a Worker for `workerUrl` from a page at `pageOrigin`
+ * would violate the Worker constructor's same-origin requirement.
+ *
+ * Conservative by design: whenever the answer cannot be determined the
+ * result is false, preserving the direct (status quo) construction path.
+ */
+export function isCrossOrigin(workerUrl: string, pageOrigin: string | null | undefined): boolean {
+  // 'null' is the serialization of an opaque origin (sandboxed iframe,
+  // file:, ...). A blob: trampoline would inherit the same opaque origin
+  // and cannot help, so keep the direct path there too.
+  if (!pageOrigin || pageOrigin === 'null') {
+    return false;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(workerUrl);
+  } catch {
+    // Relative URLs resolve against the page itself, i.e. same-origin.
+    return false;
+  }
+  // blob:/data: worker URLs are not subject to the cross-origin restriction
+  // the trampoline works around; only http(s) chunk URLs are candidates.
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return false;
+  }
+  return parsed.origin !== pageOrigin;
+}
+
+/**
+ * Normalize the bundler-reported publicPath into an absolute URL string the
+ * worker can prepend to asset paths. rspack's 'auto' runtime builds the
+ * value by string concatenation (e.g. "https://host/static/js/" + "../../"),
+ * so normalization through the URL parser keeps the handoff clean; a
+ * relative publicPath resolves against the worker chunk's own origin, which
+ * is where the assets actually live.
+ */
+export function resolvePublicPathOverride(publicPath: string | undefined, workerUrl: string): string | undefined {
+  if (publicPath === undefined || publicPath === '') {
+    return undefined;
+  }
+  try {
+    return new URL(publicPath, workerUrl).href;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the source of the same-origin trampoline script.
+ *
+ * For module workers a single static `import` suffices: the imported chunk
+ * keeps its own absolute URL as `import.meta.url`, so every relative
+ * resolution inside it (further chunks, WASM) still targets the origin that
+ * served it. For classic workers the equivalent is `importScripts`, plus the
+ * publicPath handoff described in the module docs above.
+ */
+export function workerTrampolineSource(absUrl: string, workerType: WorkerType, publicPathOverride?: string): string {
+  // JSON.stringify guarantees the URL cannot break out of the string
+  // literal, whatever characters it contains.
+  const urlLiteral = JSON.stringify(absUrl);
+  if (workerType === 'module') {
+    return `import ${urlLiteral};\n`;
+  }
+  const lines: string[] = [];
+  if (publicPathOverride !== undefined) {
+    lines.push(`self[${JSON.stringify(ENGINE_PUBLIC_PATH_GLOBAL)}] = ${JSON.stringify(publicPathOverride)};`);
+  }
+  lines.push(`importScripts(${urlLiteral});`);
+  return `${lines.join('\n')}\n`;
+}
+
+export interface PlanWorkerCreationArgs {
+  readonly workerUrl: string;
+  readonly pageOrigin: string | null | undefined;
+  readonly workerType: WorkerType;
+  readonly publicPath?: string;
+}
+
+/**
+ * Decide how to construct the engine worker: directly (same-origin or
+ * undeterminable, the status quo path) or via a blob trampoline
+ * (cross-origin embed).
+ */
+export function planWorkerCreation(args: PlanWorkerCreationArgs): WorkerCreationPlan {
+  const { workerUrl, pageOrigin, workerType, publicPath } = args;
+  if (!isCrossOrigin(workerUrl, pageOrigin)) {
+    return { kind: 'direct' };
+  }
+  const override = workerType === 'classic' ? resolvePublicPathOverride(publicPath, workerUrl) : undefined;
+  return { kind: 'trampoline', source: workerTrampolineSource(workerUrl, workerType, override) };
+}
+
+type WorkerCtor = new (url: string | URL, options?: WorkerOptions) => Worker;
+
+export interface WorkerUrlFactory {
+  createObjectURL(blob: Blob): string;
+  revokeObjectURL(url: string): void;
+}
+
+export interface SpawnedWorker {
+  readonly worker: Worker;
+  /**
+   * The blob: URL backing a trampolined worker, or null for the direct
+   * path. The caller owns revocation: revoke once the worker has provably
+   * loaded (first message) or failed (error event), not before -- the
+   * browser fetches the blob asynchronously after construction.
+   */
+  readonly blobUrl: string | null;
+}
+
+export interface SpawnEnvironment {
+  readonly pageOrigin: string | null | undefined;
+  readonly publicPath?: string;
+}
+
+/**
+ * Run `spawn` -- the bundler-emitted `new Worker(new URL(...), ...)`
+ * expression -- with the global Worker constructor transiently swapped for
+ * an interceptor that applies planWorkerCreation to the resolved chunk URL.
+ *
+ * Why interception instead of computing the URL up front: bundlers (rspack,
+ * webpack, vite) only detect and bundle a worker when the `new URL(...)`
+ * sits literally inside the `new Worker(...)` call, and they rewrite that
+ * whole expression to runtime-internal publicPath/chunk-filename lookups.
+ * The resolved URL is therefore only observable at the constructor call
+ * itself. The swap is synchronous and restored in `finally`; JS is
+ * single-threaded, so nothing else can observe it.
+ *
+ * On the direct path the interceptor forwards the exact URL object and
+ * options it received, so same-origin behavior is unchanged.
+ */
+export function spawnWithTrampoline(
+  globalScope: { Worker?: unknown },
+  spawn: () => Worker,
+  env: SpawnEnvironment,
+  urlFactory: WorkerUrlFactory = URL,
+): SpawnedWorker {
+  const NativeWorker = globalScope.Worker as WorkerCtor | undefined;
+  if (typeof NativeWorker !== 'function') {
+    // No Worker constructor here (SSR, exotic runtimes): let the bundled
+    // expression behave exactly as it would have without this shim.
+    return { worker: spawn(), blobUrl: null };
+  }
+
+  // Holder object rather than a bare local: assignments happen inside the
+  // interceptor closure, and TypeScript's control-flow analysis would
+  // otherwise narrow a bare local to its initial null at the read below.
+  const captured: { spawned: SpawnedWorker | null } = { spawned: null };
+  // A function expression (not an arrow) so the emitted `new Worker(...)`
+  // call can construct it; returning an object from a constructor makes
+  // that object the result of `new`.
+  const InterceptingWorker = function (url: string | URL, options?: WorkerOptions): Worker {
+    const plan = planWorkerCreation({
+      workerUrl: String(url),
+      pageOrigin: env.pageOrigin,
+      workerType: options?.type === 'module' ? 'module' : 'classic',
+      publicPath: env.publicPath,
+    });
+    if (plan.kind === 'direct') {
+      const worker = new NativeWorker(url, options);
+      captured.spawned = { worker, blobUrl: null };
+      return worker;
+    }
+    const blobUrl = urlFactory.createObjectURL(new Blob([plan.source], { type: 'text/javascript' }));
+    try {
+      const worker = new NativeWorker(blobUrl, options);
+      captured.spawned = { worker, blobUrl };
+      return worker;
+    } catch (err) {
+      urlFactory.revokeObjectURL(blobUrl);
+      throw err;
+    }
+  } as unknown as WorkerCtor;
+
+  globalScope.Worker = InterceptingWorker;
+  let worker: Worker;
+  try {
+    worker = spawn();
+  } finally {
+    globalScope.Worker = NativeWorker;
+  }
+  // If the bundled code somehow constructed the worker without going through
+  // the global constructor (or wrapped the one it got back), fall back to
+  // reporting the caller-visible handle -- but still surface any blob URL we
+  // created, so the caller's revoke-on-first-message/error logic reclaims it
+  // instead of leaking a blob nobody can revoke. Revoking eagerly here would
+  // be wrong: the underlying worker may still be fetching the blob.
+  const intercepted = captured.spawned;
+  if (intercepted !== null && intercepted.worker === worker) {
+    return intercepted;
+  }
+  return { worker, blobUrl: intercepted !== null ? intercepted.blobUrl : null };
+}
diff --git a/src/engine/tests/worker-trampoline.test.ts b/src/engine/tests/worker-trampoline.test.ts
new file mode 100644
index 000000000..70d174c1b
--- /dev/null
+++ b/src/engine/tests/worker-trampoline.test.ts
@@ -0,0 +1,324 @@
+// Copyright 2026 The Simlin Authors. All rights reserved.
+// Use of this source code is governed by the Apache License,
+// Version 2.0, that can be found in the LICENSE file.
+
+/**
+ * Unit tests for the cross-origin worker trampoline (functional core of the
+ * embed fix for issue #688).
+ *
+ * The browser backend factory spawns the engine's Web Worker from a chunk URL
+ * that, in the embeddable web component, is an absolute app.simlin.com URL.
+ * On a third-party page `new Worker(<cross-origin url>)` throws a synchronous
+ * SecurityError, so the factory routes cross-origin URLs through a
+ * same-origin blob: trampoline instead. These tests cover the pure
+ * decision/construction functions and the injectable spawn shell; no real
+ * Worker is required.
+ */
+
+import {
+  ENGINE_PUBLIC_PATH_GLOBAL,
+  isCrossOrigin,
+  planWorkerCreation,
+  resolvePublicPathOverride,
+  spawnWithTrampoline,
+  workerTrampolineSource,
+} from '../src/worker-trampoline';
+
+const CHUNK_URL = 'https://app.simlin.com/static/js/async/325.js';
+const APP_ORIGIN = 'https://app.simlin.com';
+const EMBED_ORIGIN = 'https://example.com';
+
+describe('isCrossOrigin', () => {
+  it('is false when the worker URL matches the page origin', () => {
+    expect(isCrossOrigin(CHUNK_URL, APP_ORIGIN)).toBe(false);
+  });
+
+  it('is true for a different host', () => {
+    expect(isCrossOrigin(CHUNK_URL, EMBED_ORIGIN)).toBe(true);
+  });
+
+  it('is true for a different scheme on the same host', () => {
+    expect(isCrossOrigin(CHUNK_URL, 'http://app.simlin.com')).toBe(true);
+  });
+
+  it('is true for a different port on the same host', () => {
+    expect(isCrossOrigin(CHUNK_URL, 'https://app.simlin.com:8443')).toBe(true);
+  });
+
+  it('is false when the page origin cannot be determined', () => {
+    expect(isCrossOrigin(CHUNK_URL, undefined)).toBe(false);
+    expect(isCrossOrigin(CHUNK_URL, null)).toBe(false);
+    expect(isCrossOrigin(CHUNK_URL, '')).toBe(false);
+  });
+
+  it('is false for an opaque ("null") page origin', () => {
+    // A blob: trampoline would inherit the same opaque origin, so it cannot
+    // help; keep the direct path.
+    expect(isCrossOrigin(CHUNK_URL, 'null')).toBe(false);
+  });
+
+  it('is false for a relative worker URL (resolves against the page)', () => {
+    expect(isCrossOrigin('/static/js/async/325.js', EMBED_ORIGIN)).toBe(false);
+    expect(isCrossOrigin('./engine-worker.js', EMBED_ORIGIN)).toBe(false);
+  });
+
+  it('is false for non-http(s) worker URLs', () => {
+    expect(isCrossOrigin('blob:https://example.com/uuid', EMBED_ORIGIN)).toBe(false);
+    expect(isCrossOrigin('data:text/javascript,1', EMBED_ORIGIN)).toBe(false);
+  });
+});
+
+describe('resolvePublicPathOverride', () => {
+  it('passes through undefined and empty publicPath', () => {
+    expect(resolvePublicPathOverride(undefined, CHUNK_URL)).toBeUndefined();
+    expect(resolvePublicPathOverride('', CHUNK_URL)).toBeUndefined();
+  });
+
+  it('normalizes the dot-dot form rspack computes for assetPrefix auto', () => {
+    // rspack's runtime computes publicPath by string concatenation, e.g.
+    // dirname(script src) + "../../"; normalize so the worker gets a clean
+    // absolute base.
+    expect(resolvePublicPathOverride('https://app.simlin.com/static/js/../../', CHUNK_URL)).toBe(
+      'https://app.simlin.com/',
+    );
+  });
+
+  it('resolves a relative publicPath against the worker URL origin', () => {
+    expect(resolvePublicPathOverride('/', CHUNK_URL)).toBe('https://app.simlin.com/');
+  });
+});
+
+describe('workerTrampolineSource', () => {
+  it('emits a single static import for module workers', () => {
+    expect(workerTrampolineSource(CHUNK_URL, 'module')).toBe(`import ${JSON.stringify(CHUNK_URL)};\n`);
+  });
+
+  it('emits importScripts for classic workers', () => {
+    expect(workerTrampolineSource(CHUNK_URL, 'classic')).toBe(`importScripts(${JSON.stringify(CHUNK_URL)});\n`);
+  });
+
+  it('sets the publicPath global before importScripts for classic workers', () => {
+    const source = workerTrampolineSource(CHUNK_URL, 'classic', 'https://app.simlin.com/');
+    const lines = source.trimEnd().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toBe(`self[${JSON.stringify(ENGINE_PUBLIC_PATH_GLOBAL)}] = "https://app.simlin.com/";`);
+    expect(lines[1]).toBe(`importScripts(${JSON.stringify(CHUNK_URL)});`);
+  });
+
+  it('escapes URLs so they cannot break out of the string literal', () => {
+    const hostile = 'https://app.simlin.com/x");importScripts("https://evil.example/y';
+    const source = workerTrampolineSource(hostile, 'classic');
+    expect(source).toBe(`importScripts(${JSON.stringify(hostile)});\n`);
+    expect(source).toContain('\\"');
+  });
+});
+
+describe('planWorkerCreation', () => {
+  it('keeps the direct path for same-origin URLs', () => {
+    expect(
+      planWorkerCreation({
+        workerUrl: CHUNK_URL,
+        pageOrigin: APP_ORIGIN,
+        workerType: 'classic',
+        publicPath: 'https://app.simlin.com/static/js/../../',
+      }),
+    ).toEqual({ kind: 'direct' });
+  });
+
+  it('keeps the direct path when the origin is unknown', () => {
+    expect(planWorkerCreation({ workerUrl: CHUNK_URL, pageOrigin: undefined, workerType: 'module' })).toEqual({
+      kind: 'direct',
+    });
+  });
+
+  it('builds an import trampoline for cross-origin module workers', () => {
+    const plan = planWorkerCreation({
+      workerUrl: CHUNK_URL,
+      pageOrigin: EMBED_ORIGIN,
+      workerType: 'module',
+      publicPath: 'https://app.simlin.com/static/js/../../',
+    });
+    expect(plan).toEqual({ kind: 'trampoline', source: `import ${JSON.stringify(CHUNK_URL)};\n` });
+  });
+
+  it('builds an importScripts trampoline with publicPath override for cross-origin classic workers', () => {
+    const plan = planWorkerCreation({
+      workerUrl: CHUNK_URL,
+      pageOrigin: EMBED_ORIGIN,
+      workerType: 'classic',
+      publicPath: 'https://app.simlin.com/static/js/../../',
+    });
+    expect(plan.kind).toBe('trampoline');
+    if (plan.kind !== 'trampoline') {
+      throw new Error('unreachable');
+    }
+    expect(plan.source).toContain(`self[${JSON.stringify(ENGINE_PUBLIC_PATH_GLOBAL)}] = "https://app.simlin.com/";`);
+    expect(plan.source).toContain(`importScripts(${JSON.stringify(CHUNK_URL)});`);
+  });
+
+  it('omits the publicPath override when none is available', () => {
+    const plan = planWorkerCreation({
+      workerUrl: CHUNK_URL,
+      pageOrigin: EMBED_ORIGIN,
+      workerType: 'classic',
+    });
+    expect(plan).toEqual({
+      kind: 'trampoline',
+      source: `importScripts(${JSON.stringify(CHUNK_URL)});\n`,
+    });
+  });
+});
+
+describe('spawnWithTrampoline', () => {
+  // Mimics the DOM Worker constructor closely enough for the shell: records
+  // its arguments so tests can assert exactly what was constructed.
+  class FakeWorker {
+    readonly url: string | URL;
+    readonly options: WorkerOptions | undefined;
+    constructor(url: string | URL, options?: WorkerOptions) {
+      this.url = url;
+      this.options = options;
+    }
+  }
+
+  interface FakeUrlFactory {
+    createObjectURL: jest.Mock<string, [Blob]>;
+    revokeObjectURL: jest.Mock<void, [string]>;
+    lastBlob: () => Blob;
+  }
+
+  function makeUrlFactory(): FakeUrlFactory {
+    let blob: Blob | null = null;
+    const createObjectURL = jest.fn((b: Blob) => {
+      blob = b;
+      return 'blob:https://example.com/fake-uuid';
+    });
+    const revokeObjectURL = jest.fn();
+    return {
+      createObjectURL,
+      revokeObjectURL,
+      lastBlob: () => {
+        if (blob === null) {
+          throw new Error('no blob was created');
+        }
+        return blob;
+      },
+    };
+  }
+
+  function makeScope(): { Worker?: unknown } {
+    return { Worker: FakeWorker };
+  }
+
+  // Emulates the bundler-emitted expression: it constructs whatever the
+  // (possibly swapped) global `Worker` currently refers to.
+  function bundlerSpawn(scope: { Worker?: unknown }, url: string, type: string | undefined): () => Worker {
+    return () => {
+      const ctor = scope.Worker as new (url: URL, options?: WorkerOptions) => Worker;
+      return new ctor(new URL(url), { type: type as WorkerType | undefined });
+    };
+  }
+  type WorkerType = 'classic' | 'module';
+
+  it('passes same-origin workers through to the native constructor untouched', () => {
+    const scope = makeScope();
+    const urlFactory = makeUrlFactory();
+    const spawned = spawnWithTrampoline(
+      scope,
+      bundlerSpawn(scope, CHUNK_URL, undefined),
+      { pageOrigin: APP_ORIGIN, publicPath: 'https://app.simlin.com/static/js/../../' },
+      urlFactory,
+    );
+    expect(spawned.blobUrl).toBeNull();
+    const worker = spawned.worker as unknown as FakeWorker;
+    expect(worker).toBeInstanceOf(FakeWorker);
+    expect(String(worker.url)).toBe(CHUNK_URL);
+    expect(urlFactory.createObjectURL).not.toHaveBeenCalled();
+    expect(scope.Worker).toBe(FakeWorker);
+  });
+
+  it('routes cross-origin classic workers through a blob trampoline', async () => {
+    const scope = makeScope();
+    const urlFactory = makeUrlFactory();
+    const spawned = spawnWithTrampoline(
+      scope,
+      bundlerSpawn(scope, CHUNK_URL, undefined),
+      { pageOrigin: EMBED_ORIGIN, publicPath: 'https://app.simlin.com/static/js/../../' },
+      urlFactory,
+    );
+    expect(spawned.blobUrl).toBe('blob:https://example.com/fake-uuid');
+    const worker = spawned.worker as unknown as FakeWorker;
+    expect(worker).toBeInstanceOf(FakeWorker);
+    expect(String(worker.url)).toBe('blob:https://example.com/fake-uuid');
+    const source = await urlFactory.lastBlob().text();
+    expect(source).toContain(`self[${JSON.stringify(ENGINE_PUBLIC_PATH_GLOBAL)}] = "https://app.simlin.com/";`);
+    expect(source).toContain(`importScripts(${JSON.stringify(CHUNK_URL)});`);
+    expect(scope.Worker).toBe(FakeWorker);
+  });
+
+  it('routes cross-origin module workers through an import trampoline', async () => {
+    const scope = makeScope();
+    const urlFactory = makeUrlFactory();
+    const spawned = spawnWithTrampoline(
+      scope,
+      bundlerSpawn(scope, CHUNK_URL, 'module'),
+      { pageOrigin: EMBED_ORIGIN, publicPath: undefined },
+      urlFactory,
+    );
+    expect(spawned.blobUrl).toBe('blob:https://example.com/fake-uuid');
+    const source = await urlFactory.lastBlob().text();
+    expect(source).toBe(`import ${JSON.stringify(CHUNK_URL)};\n`);
+    expect(scope.Worker).toBe(FakeWorker);
+  });
+
+  it('restores the global and revokes the blob URL when construction fails', () => {
+    class ThrowingWorker {
+      constructor() {
+        throw new Error('worker construction failed');
+      }
+    }
+    const scope: { Worker?: unknown } = { Worker: ThrowingWorker };
+    const urlFactory = makeUrlFactory();
+    expect(() =>
+      spawnWithTrampoline(
+        scope,
+        bundlerSpawn(scope, CHUNK_URL, undefined),
+        { pageOrigin: EMBED_ORIGIN, publicPath: undefined },
+        urlFactory,
+      ),
+    ).toThrow('worker construction failed');
+    expect(urlFactory.revokeObjectURL).toHaveBeenCalledWith('blob:https://example.com/fake-uuid');
+    expect(scope.Worker).toBe(ThrowingWorker);
+  });
+
+  it('restores the global when spawn itself throws', () => {
+    const scope = makeScope();
+    const urlFactory = makeUrlFactory();
+    expect(() =>
+      spawnWithTrampoline(
+        scope,
+        () => {
+          throw new Error('bundler pattern not transformed');
+        },
+        { pageOrigin: APP_ORIGIN, publicPath: undefined },
+        urlFactory,
+      ),
+    ).toThrow('bundler pattern not transformed');
+    expect(scope.Worker).toBe(FakeWorker);
+  });
+
+  it('falls back to plain spawn when the environment has no Worker', () => {
+    const scope: { Worker?: unknown } = {};
+    const sentinel = {} as Worker;
+    const spawned = spawnWithTrampoline(scope, () => sentinel, { pageOrigin: EMBED_ORIGIN }, makeUrlFactory());
+    expect(spawned).toEqual({ worker: sentinel, blobUrl: null });
+  });
+
+  it('returns the spawned worker as-is when spawn bypasses the global constructor', () => {
+    const scope = makeScope();
+    const sentinel = {} as Worker;
+    const spawned = spawnWithTrampoline(scope, () => sentinel, { pageOrigin: EMBED_ORIGIN }, makeUrlFactory());
+    expect(spawned).toEqual({ worker: sentinel, blobUrl: null });
+    expect(scope.Worker).toBe(FakeWorker);
+  });
+});

From b9586a71ce19d902eacc7562b8412c37b6b4dc71 Mon Sep 17 00:00:00 2001
From: Bobby Powers <bobbypowers@gmail.com>
Date: Wed, 1 Jul 2026 13:06:58 -0700
Subject: [PATCH 4/4] deploy: gate gcloud uploads on the GAE 10k-file cap
 before deploying

gcloud app deploy uploads whatever .gcloudignore leaves in, entirely
independent of git tracking status, so a git-status-clean tree can
still trip App Engine Standard's hard 10,000-file cap on gitignored
artifacts (cargo target dirs, venvs, scratch checkouts) -- and the
failure only surfaced inside gcloud, after the expensive clean+build.
check-upload-file-count.sh enumerates the real upload set once via
gcloud meta list-files-for-upload immediately before each deploy and
aborts with a per-top-level-directory breakdown when the cap would be
hit. Both deploy paths run it: the root-path deploy because that is
where the unbounded exposure lives, the staged path as a cheap guard
against staging-assembly regressions. The cap parameter is
overridable only so the failure path can be exercised by hand against
a tiny fixture. With the .gcloudignore hardening that landed earlier,
this completes issue 695.
---
 docs/dev/deploy.md                 |  3 +-
 scripts/check-upload-file-count.sh | 57 ++++++++++++++++++++++++++++++
 scripts/deploy-web-staged.sh       |  7 ++++
 scripts/deploy-web.sh              |  8 +++++
 4 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100755 scripts/check-upload-file-count.sh

diff --git a/docs/dev/deploy.md b/docs/dev/deploy.md
index 5f2950f57..87e56ffdf 100644
--- a/docs/dev/deploy.md
+++ b/docs/dev/deploy.md
@@ -27,6 +27,7 @@ export NODE_ENV=production
 pnpm clean                                       # cargo clean + each package's clean script
 pnpm build                                       # pnpm -r run build: Rust+WASM, then every TS package
 pnpm --filter @simlin/app run deploy:assemble    # copy build/ and build-component/ into public/; drop symlinks
+scripts/check-upload-file-count.sh .             # abort if the upload set would trip GAE's 10,000-file cap
 gcloud app deploy ./.app.prod.yaml               # upload the repo minus .gcloudignore, switch traffic
 # A bash trap runs the cleanup below on EXIT/INT/TERM, even if any step above fails:
 pnpm --filter @simlin/app run deploy:clean       # git checkout the symlinks and index.html; rm build artifacts
@@ -124,7 +125,7 @@ The server loads `config/default.json`, then `config/production.json` when `NODE
 ## Pre-deploy checklist
 
 - [ ] CI is green on the commit you're deploying.
-- [ ] `git status` is clean.
+- [ ] `git status` is clean. Note this only makes the tracked-`public/` mutation and cleanup reliable -- it does NOT bound what gets uploaded. The upload set is whatever `.gcloudignore` leaves in, so gitignored/untracked junk (venvs, nested cargo `target/` dirs, scratch checkouts) still counts toward GAE Standard's hard 10,000-file cap (issue #695). Both deploy scripts run [`scripts/check-upload-file-count.sh`](/scripts/check-upload-file-count.sh) immediately before `gcloud app deploy` and abort with a per-top-level-directory breakdown if the cap would be hit; fix by deleting the offending dirs or adding them to `.gcloudignore`.
 - [ ] `gcloud config get-value project` is the production project.
 - [ ] `gcloud app versions list --service=default` shows a known-good current version -- note its ID, that's your rollback target. (If GAE has garbage-collected it, there is no rollback; see below.)
 - [ ] `.app.prod.yaml` reconciled against `app.yaml` (`runtime: nodejs24`, `build_env_variables.GOOGLE_NODE_RUN_SCRIPTS: ''`, `automatic_scaling.max_instances: 8`, handlers including the `/static` `Access-Control-Allow-Origin: "*"` header, `authentication__seshcookie__key` set to the value already in use).
diff --git a/scripts/check-upload-file-count.sh b/scripts/check-upload-file-count.sh
new file mode 100755
index 000000000..c86f278d2
--- /dev/null
+++ b/scripts/check-upload-file-count.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# Pre-flight gate: fail if the gcloud upload set for DIR meets or exceeds
+# App Engine Standard's hard per-deploy file cap (10,000 files).
+#
+# Why this exists (issue #695): `gcloud app deploy` uploads everything that
+# .gcloudignore does not exclude, which is INDEPENDENT of git tracking
+# status. A `git status`-clean tree can still hold gitignored artifacts
+# (cargo target dirs, Python venvs, third_party checkouts) or brand-new
+# untracked scratch dirs that blow the cap -- and without this gate the
+# failure only surfaces inside `gcloud app deploy`, after the expensive
+# clean+build. `gcloud meta list-files-for-upload` is the only check that
+# reflects the real upload set, so we run it once here, immediately before
+# the deploy, and turn a late upload failure into a fast, actionable error.
+#
+# Usage: check-upload-file-count.sh DIR [MAX_FILES]
+#   MAX_FILES defaults to 10000 (the GAE Standard cap). It is overridable
+#   so the failure path can be exercised by hand against a small directory
+#   without building a 10k-file fixture.
+
+set -euo pipefail
+
+if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
+    echo "usage: $0 DIR [MAX_FILES]" >&2
+    exit 2
+fi
+
+DIR="$1"
+MAX_FILES="${2:-10000}"
+
+UPLOAD_LIST="$(mktemp)"
+trap 'rm -f "$UPLOAD_LIST"' EXIT
+
+# Enumerate exactly once: on a polluted tree this walk covers 100k+ files
+# and is the slow part, so both the count and the per-directory breakdown
+# below are derived from this single capture. Running from inside DIR makes
+# gcloud emit paths relative to DIR, which the breakdown's `cut` relies on.
+(cd "$DIR" && gcloud meta list-files-for-upload .) > "$UPLOAD_LIST"
+
+UPLOAD_COUNT="$(wc -l < "$UPLOAD_LIST" | tr -d '[:space:]')"
+
+if [ "$UPLOAD_COUNT" -ge "$MAX_FILES" ]; then
+    {
+        echo "ERROR: gcloud would upload $UPLOAD_COUNT files from $DIR, but App Engine"
+        echo "       Standard rejects deploys of $MAX_FILES files or more."
+        echo ""
+        echo "The upload set is whatever .gcloudignore leaves in -- a clean 'git status'"
+        echo "does NOT bound it (gitignored and untracked files still upload). Largest"
+        echo "top-level directories in the upload set; delete the junk ones or add them"
+        echo "to .gcloudignore:"
+        echo ""
+        cut -d/ -f1 "$UPLOAD_LIST" | sort | uniq -c | sort -rn | head -10
+    } >&2
+    exit 1
+fi
+
+echo "    upload set: $UPLOAD_COUNT files (cap: $MAX_FILES)"
diff --git a/scripts/deploy-web-staged.sh b/scripts/deploy-web-staged.sh
index cab12c233..4ca44d089 100755
--- a/scripts/deploy-web-staged.sh
+++ b/scripts/deploy-web-staged.sh
@@ -77,6 +77,13 @@ bash "$REPO_ROOT/scripts/verify-deploy-build.sh"
 echo "==> Assembling self-contained server staging dir (scripts/build-deploy-staging.mjs)"
 node "$REPO_ROOT/scripts/build-deploy-staging.mjs" "$STAGING_DIR" "$REPO_ROOT/.app.prod.yaml"
 
+# The staging dir is bounded by construction (build-deploy-staging.mjs copies
+# an explicit file list), so this gate is cheap here -- it exists to catch a
+# regression in the staging assembly (e.g. accidentally vendoring a
+# node_modules tree) before the upload starts. See issue #695.
+echo "==> Checking upload file count against the GAE 10k cap (scripts/check-upload-file-count.sh)"
+bash "$REPO_ROOT/scripts/check-upload-file-count.sh" "$STAGING_DIR"
+
 echo "==> gcloud app deploy $STAGING_DIR/app.yaml"
 gcloud app deploy "$STAGING_DIR/app.yaml" "$@"
 
diff --git a/scripts/deploy-web.sh b/scripts/deploy-web.sh
index 722f99992..97a926301 100755
--- a/scripts/deploy-web.sh
+++ b/scripts/deploy-web.sh
@@ -70,6 +70,14 @@ pnpm build
 echo "==> Staging app build into public/ (pnpm --filter @simlin/app run deploy:assemble)"
 pnpm --filter @simlin/app run deploy:assemble
 
+# Gate on the real upload set right before the deploy: this deploy uploads
+# from the repo root, where the upload set is whatever .gcloudignore leaves
+# in -- independent of git status, and including files the build steps above
+# just created. Failing here (instead of inside gcloud app deploy) names the
+# offending directories and still runs the cleanup trap. See issue #695.
+echo "==> Checking upload file count against the GAE 10k cap (scripts/check-upload-file-count.sh)"
+bash "$REPO_ROOT/scripts/check-upload-file-count.sh" "$REPO_ROOT"
+
 echo "==> gcloud app deploy ./.app.prod.yaml"
 gcloud app deploy "$REPO_ROOT/.app.prod.yaml" "$@"