@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/runOfflineFullTests.ts

@@ -0,0 +1,1634 @@
+#!/usr/bin/env node
+/**
+ * runOfflineFullTests — full-stack offline orchestrator.
+ *
+ * Boots the entire offline stack in ONE Node process:
+ *
+ *   - Postgres (per-run UUID DB, migrated)
+ *   - 4 mock servers in-process: admin shell, Admin GraphQL,
+ *     Storefront GraphQL, mock storefront (Liquid) — all reading
+ *     ONE shared ShopState (in-memory, owned by this process)
+ *   - Remix backend (Vite) as a child process, with NODE_OPTIONS
+ *     preloading MSW so its outbound `fetch()` to *.myshopify.com
+ *     reaches our Admin GraphQL mock
+ *   - Playwright as a child process, with mock URLs in env
+ *
+ * The Playwright fixture (`offlineFullTest`, orchestrated mode)
+ * reads the mock URLs from env and routes browser requests via
+ * `page.route()`. Tests mutate ShopState via control-plane HTTP
+ * endpoints exposed by the storefront mock (mounted under
+ * `/__test__/state/*`).
+ *
+ * This is the offline counterpart to runTests.ts (online mode).
+ * Online tests still go via runTests.ts; offline-full tests via this.
+ *
+ * Env it sets in the spawned Remix backend:
+ *   SHOPIFY_API_SECRET  = mock JWT secret (so JWTs validate)
+ *   NODE_OPTIONS        = --import @essential-apps/shopify-test-shopify-api/msw-loader
+ *   TEST_OFFLINE_MOCK_ADMIN_API_URL = mock GraphQL baseUrl (used by MSW loader)
+ *   TEST_OFFLINE         = true (app-side opt-in flag for any code that
+ *                              wants to no-op real Shopify side-effects)
+ *
+ * Env it sets in the Playwright run:
+ *   TEST_OFFLINE_ORCHESTRATED   = true
+ *   TEST_OFFLINE_MOCK_ADMIN_SHELL_URL   = http://127.0.0.1:N
+ *   TEST_OFFLINE_MOCK_ADMIN_API_URL     = http://127.0.0.1:N
+ *   TEST_OFFLINE_MOCK_STOREFRONT_API_URL = http://127.0.0.1:N
+ *   TEST_OFFLINE_MOCK_STOREFRONT_URL    = http://127.0.0.1:N
+ *   TEST_OFFLINE_MOCK_BACKEND_URL       = the Remix backend's URL
+ *   TEST_OFFLINE_MOCK_SHOP_DOMAIN       = test-shop.myshopify.com
+ */
+import { spawn, execSync, type ChildProcess } from 'node:child_process';
+import { assertInVm, computeBuildHash } from '@essential-apps/shopify-test-core';
+import { startEdgeProxy } from '../edge/edgeProxy.js';
+import { startNeonWsProxy } from '../lib/neonWsProxy.js';
+import { TEST_CA_CERT_PEM } from '../edge/cert.js';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Agent } from 'undici';
+import {
+  ShopState,
+  createStorefrontApp,
+  startStorefront,
+  type StartedStorefront,
+  type ExtensionConfig,
+} from '@essential-apps/shopify-test-storefront';
+import { dawn } from '@essential-apps/shopify-test-themes';
+import {
+  createAdminApi,
+  startAdminApi,
+  createStorefrontApi,
+  startStorefrontApi,
+  createPartnerApi,
+  startPartnerApi,
+  type StartedAdminApi,
+  type StartedStorefrontApi,
+  type StartedPartnerApi,
+} from '@essential-apps/shopify-test-shopify-api';
+import {
+  createMockAdminApp,
+  startMockAdmin,
+  DEFAULT_MOCK_JWT_SECRET,
+  mintIdToken,
+  type StartedMockAdmin,
+} from '@essential-apps/shopify-test-mock-admin';
+
+const insecureFetchDispatcher = new Agent({ connect: { rejectUnauthorized: false } });
+const PG_HOST = 'localhost';
+const PG_PORT = '5432';
+const READY_TIMEOUT_MS = 120_000;
+
+const DEFAULT_SHOP_DOMAIN = 'test-shop.myshopify.com';
+const DEFAULT_APP_HANDLE = process.env['SHOPIFY_APP_HANDLE'] ?? 'essential-app';
+// Mock client id — must match what the Remix backend reads as
+// SHOPIFY_API_KEY for App Bridge validation paths to align. We use a
+// fixed value so seeded sessions and JWT audience claims line up.
+// Matches the default clientId in the offline mock-admin / shopState
+// fixtures. If those defaults change, change this too.
+const MOCK_CLIENT_ID = 'mock-api-key';
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(process.cwd(), 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(`No package.json at ${pkgPath}.`);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) throw new Error(`package.json has no name field.`);
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+function dbUrl(name: string): string {
+  const user = process.env['PGUSER'] || process.env['USER'] || 'root';
+  return `postgresql://${user}@${PG_HOST}:${PG_PORT}/${name}`;
+}
+
+/**
+ * Drop any DBs left over from previous crashed orchestrator runs.
+ * We match on the per-app naming pattern `${app}_offline_*`. A
+ * graceful exit drops the DB in the `finally` block; a SIGKILL
+ * (or test runner timeout) leaks it. Cleanup at the START of the
+ * next run keeps the dev's Postgres from accumulating dozens of
+ * dead databases over months.
+ *
+ * Safe: only deletes DBs matching our prefix; never touches anything
+ * the user might have manually named.
+ */
+function dropOrphanDatabases(prefix: string): void {
+  try {
+    const output = execSync(
+      `psql -h ${PG_HOST} -p ${PG_PORT} -d postgres -At -c "SELECT datname FROM pg_database WHERE datname LIKE '${prefix}_%'"`,
+      { encoding: 'utf8' },
+    );
+    const orphans = output
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    if (orphans.length === 0) return;
+    console.log(`[runOfflineFull] cleanup: dropping ${orphans.length} orphan DB(s)…`);
+    for (const name of orphans) {
+      try {
+        // `--force` (psql 13+) terminates any leftover connections
+        // before drop. Falls back to plain dropdb if --force isn't
+        // supported in the local psql.
+        execSync(`dropdb --force -h ${PG_HOST} -p ${PG_PORT} ${name} 2>/dev/null || dropdb -h ${PG_HOST} -p ${PG_PORT} ${name}`, {
+          stdio: 'ignore',
+        });
+      } catch {
+        // Couldn't drop (active connection from another orchestrator
+        // run, perhaps). Skip silently — we'll get it next time.
+      }
+    }
+  } catch (err) {
+    // If psql isn't available at all we just skip cleanup; the
+    // primary createdb below will fail loudly anyway.
+    console.warn(`[runOfflineFull] orphan-DB cleanup failed: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Build a `resetDb` hook the storefront control plane can call
+ * between tests. Runs:
+ *   1. TRUNCATE every user-defined table in `public` (CASCADE,
+ *      RESTART IDENTITY) — discovered dynamically from pg_tables
+ *      so adding a model doesn't break the hook.
+ *   2. Re-seed the consuming app's Session row.
+ *
+ * Why TRUNCATE-then-reseed vs. literal per-test database:
+ *   - Per-test DB would require restarting the backend (a single
+ *     long-running process with a fixed DATABASE_URL) on every
+ *     test, ~5s overhead per test → multiple minutes for the
+ *     current suite. TRUNCATE runs in ~5ms and is observationally
+ *     identical for the consuming code.
+ *   - This hook is ORCHESTRATOR-owned, so the consuming app no
+ *     longer needs a `/test-internal/reset-db` route. The backend
+ *     stays test-unaware.
+ */
+function makeResetDbHook(dbName: string, shopDomain: string, scopes: string): () => Promise<void> {
+  return async () => {
+    // Build the SQL as a single transaction: one round-trip, atomic.
+    // The DO block iterates pg_tables for `public` schema, skipping
+    // Prisma's migration metadata. RESTART IDENTITY resets serial
+    // sequences so per-test IDs start from 1 (predictable in
+    // snapshots / assertions).
+    const seedSql =
+      // Insert the seeded session row. We pass scopes as a literal
+      // here (escaped) because the `psql -c` interface doesn't have
+      // proper parameterized queries.
+      `INSERT INTO "Session" (id, shop, state, "isOnline", "accessToken", scope) ` +
+      `VALUES ('offline_${shopDomain}', '${shopDomain}', 'offline-mock', false, 'mock-access-token', '${scopes.replace(/'/g, "''")}') ` +
+      `ON CONFLICT (id) DO UPDATE SET ` +
+      `shop = EXCLUDED.shop, state = EXCLUDED.state, "accessToken" = EXCLUDED."accessToken", scope = EXCLUDED.scope;`;
+    const sql = `
+      BEGIN;
+      DO $$
+      DECLARE
+        t text;
+      BEGIN
+        FOR t IN
+          SELECT tablename FROM pg_tables
+          WHERE schemaname = 'public' AND tablename <> '_prisma_migrations'
+        LOOP
+          EXECUTE 'TRUNCATE TABLE "' || t || '" RESTART IDENTITY CASCADE';
+        END LOOP;
+      END $$;
+      ${seedSql}
+      COMMIT;
+    `;
+    // Use a tempfile + `psql -f` rather than `-c "..."`. The
+    // inline form fights shell quoting on multi-line SQL that
+    // contains dollar-quoted DO blocks ($$ ... $$). A file is
+    // also easier to inspect when debugging.
+    const tmpFile = resolve(
+      tmpdir(),
+      `offline-reset-db-${randomUUID()}.sql`,
+    );
+    writeFileSync(tmpFile, sql, 'utf8');
+    try {
+      execSync(
+        `psql -h ${PG_HOST} -p ${PG_PORT} -d ${dbName} -v ON_ERROR_STOP=1 -f ${tmpFile}`,
+        { stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+    } catch (err) {
+      const stderr = (err as { stderr?: Buffer }).stderr?.toString() ?? '';
+      const stdout = (err as { stdout?: Buffer }).stdout?.toString() ?? '';
+      throw new Error(
+        `[resetDb] psql failed: ${(err as Error).message}\n` +
+          `stdout: ${stdout}\nstderr: ${stderr}\nSQL file (preserved for inspection): ${tmpFile}`,
+      );
+    }
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* best-effort */
+    }
+  };
+}
+
+/** Probe a URL until it responds (any status). Used for backend readiness. */
+async function waitForReady(url: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr = '';
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, {
+        redirect: 'manual',
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        dispatcher: insecureFetchDispatcher as any,
+      } as RequestInit);
+      if (res.status > 0) return;
+    } catch (e) {
+      lastErr = (e as Error).message;
+    }
+    await sleep(1_000);
+  }
+  throw new Error(`Backend never became ready at ${url}. Last error: ${lastErr}`);
+}
+
+/**
+ * Configure the container for offline mode: write Shopify hostname
+ * entries into /etc/hosts and install the edge proxy's self-signed
+ * cert as a system CA. The container entrypoint
+ * (tests/test-offline/docker/entrypoint.sh) does the same thing when
+ * node_modules is warm at container start; on a cold cache, the
+ * entrypoint can't (cert file doesn't exist yet) and this is the
+ * post-install backstop.
+ *
+ * Idempotent — safe to call multiple times. The `grep -q` guards
+ * make /etc/hosts edits skip if entries are already present;
+ * `update-ca-certificates` is a no-op if the cert is already
+ * trusted.
+ */
+function ensureOfflineSetup(): void {
+  // Source of truth for the CA cert: imported from edge/cert.js
+  // (statically imported at the top of this file). `certutil -A -i`
+  // requires an on-disk path so we write the CA to a temp file
+  // before importing into NSS; the system CA store install (which
+  // uses /usr/local/share/ca-certificates/) writes the PEM string
+  // directly.
+
+  // /etc/hosts entries — IPv4 ONLY. The edge proxy binds on 0.0.0.0
+  // (IPv4); listen() on `::` (IPv6 dual-stack) hangs forever on the
+  // VM kernel, see commit 603594e. If we also add `::1`
+  // entries, Chrome resolves AAAA → ::1, connects to nothing, and
+  // returns "Failed to fetch" inside page.evaluate(). IPv4-only
+  // mapping forces Chrome down the IPv4 path that actually reaches
+  // the edge proxy.
+  const hostsPath = '/etc/hosts';
+  let hostsContent = '';
+  try {
+    hostsContent = readFileSync(hostsPath, 'utf8');
+  } catch {
+    console.warn(`[runOfflineFull] could not read ${hostsPath}; skipping /etc/hosts setup`);
+    return;
+  }
+  const hostsToAdd: string[] = [];
+  for (const host of [
+    'test-shop.myshopify.com',
+    'admin.shopify.com',
+    'cdn.shopify.com',
+    // Real Shopify font CDN — routed by the edge proxy to the
+    // storefront mock's /__shopify-fonts/* handler so the live
+    // `font_face` filter output (which contains real
+    // fonts.shopifycdn.com URLs) just works in-browser.
+    'fonts.shopifycdn.com',
+  ]) {
+    if (!new RegExp(`^127\\.0\\.0\\.1\\s+${host.replace(/\./g, '\\.')}\\s*$`, 'm').test(hostsContent)) {
+      hostsToAdd.push(`127.0.0.1 ${host}`);
+    }
+    // NOTE: deliberately NOT adding `::1 <host>` entries — see the
+    // comment block above for why.
+  }
+  if (hostsToAdd.length > 0) {
+    try {
+      writeFileSync(hostsPath, hostsContent + '\n' + hostsToAdd.join('\n') + '\n');
+      console.log(`[runOfflineFull] wrote ${hostsToAdd.length} /etc/hosts entries`);
+    } catch (err) {
+      console.warn(
+        `[runOfflineFull] could not write ${hostsPath}: ${(err as Error).message}. ` +
+          `Browser may resolve Shopify hostnames to real Shopify on the internet.`,
+      );
+    }
+  }
+
+  // System CA trust (Node). `/usr/local/share/ca-certificates/*.crt`
+  // is the canonical apt-style location; update-ca-certificates
+  // appends to /etc/ssl/certs/ca-certificates.crt which Node +
+  // glibc OpenSSL read. NODE_EXTRA_CA_CERTS belt-and-suspenders.
+  const systemCertDest = '/usr/local/share/ca-certificates/edge-ca.crt';
+  try {
+    let existing = '';
+    try {
+      existing = readFileSync(systemCertDest, 'utf8');
+    } catch {
+      /* not installed yet */
+    }
+    if (existing !== TEST_CA_CERT_PEM) {
+      writeFileSync(systemCertDest, TEST_CA_CERT_PEM);
+      execSync('update-ca-certificates >/dev/null 2>&1 || true', { stdio: 'ignore' });
+      console.log('[runOfflineFull] installed edge CA into system trust store');
+    }
+    process.env['NODE_EXTRA_CA_CERTS'] = systemCertDest;
+  } catch (err) {
+    console.warn(
+      `[runOfflineFull] could not install edge CA: ${(err as Error).message}. ` +
+        `TLS connections to the edge may fail.`,
+    );
+  }
+
+  // Chrome / Chromium on Linux verifies certs against NSS DB
+  // (`~/.pki/nssdb`), NOT the system CA store. We import the CA
+  // cert (NOT the server cert) — Chrome's chain validation walks
+  // server cert → CA in NSS → trust anchor. `certutil` (from
+  // libnss3-tools) is the canonical tool. NSS DB is per-user; we
+  // run as root so it lives at /root/.pki/nssdb and is shared
+  // across every Chromium instance (test runs + explore mode +
+  // any future headed-Chrome workflow).
+  //
+  // Trust attribute "C,,":
+  //   First slot  C = trusted CA for SSL/TLS server cert validation
+  //   Second slot empty = not trusted for email
+  //   Third slot  empty = not trusted for code/object signing
+  // Minimum-privilege scope for what we need.
+  try {
+    const nssDir = `${process.env['HOME'] ?? '/root'}/.pki/nssdb`;
+    if (!existsSync(nssDir)) {
+      mkdirSync(nssDir, { recursive: true });
+      execSync(`certutil -N --empty-password -d sql:${nssDir}`, {
+        stdio: 'ignore',
+      });
+    }
+    // Write CA cert to a temp file so certutil -i can read it.
+    const tmpCaPath = '/tmp/edge-ca.crt';
+    writeFileSync(tmpCaPath, TEST_CA_CERT_PEM);
+    // Delete-then-add for idempotency (avoids "already exists").
+    execSync(
+      `certutil -d sql:${nssDir} -D -n edge-ca >/dev/null 2>&1 || true`,
+      { stdio: 'ignore' },
+    );
+    execSync(
+      `certutil -d sql:${nssDir} -A -t "C,," -n edge-ca -i ${tmpCaPath}`,
+      { stdio: 'ignore' },
+    );
+    unlinkSync(tmpCaPath);
+    console.log('[runOfflineFull] installed edge CA into NSS DB (Chrome)');
+  } catch (err) {
+    console.warn(
+      `[runOfflineFull] could not install edge CA into NSS DB: ${(err as Error).message}. ` +
+        `Chrome will reject the edge's cert. Verify libnss3-tools is installed in the image.`,
+    );
+  }
+}
+
+/**
+ * Build the absolute path to the MSW loader inside the consuming
+ * app's node_modules. NODE_OPTIONS=--import requires either an absolute
+ * path or a Node-resolvable specifier; an absolute path is the
+ * safest bet across Node versions.
+ */
+function resolveMswLoaderPath(): string {
+  const candidate = resolve(
+    process.cwd(),
+    'node_modules/@essential-apps/shopify-test-shopify-api/dist/admin/mswLoader.js',
+  );
+  if (!existsSync(candidate)) {
+    throw new Error(
+      `MSW loader not found at ${candidate}. Did you install ` +
+        `@essential-apps/shopify-test-shopify-api as a dependency of the ` +
+        `consuming app?`,
+    );
+  }
+  return candidate;
+}
+
+/**
+ * Absolute path to the Neon-local preload shim (ships in
+ * shopify-test-shopify-api, beside the MSW loader). Preloaded into the
+ * backend so an app whose prisma client uses @neondatabase/serverless
+ * reaches THIS run's local Postgres via the WS proxy — no app change.
+ */
+function resolveNeonShimPath(): string {
+  const candidate = resolve(
+    process.cwd(),
+    'node_modules/@essential-apps/shopify-test-shopify-api/dist/admin/neonLocalShim.js',
+  );
+  if (!existsSync(candidate)) {
+    throw new Error(
+      `Neon-local shim not found at ${candidate}. Did you install ` +
+        `@essential-apps/shopify-test-shopify-api as a dependency of the ` +
+        `consuming app?`,
+    );
+  }
+  return candidate;
+}
+
+/**
+ * Seed a Session row directly via prisma so authenticate.admin()
+ * finds the merchant. We invoke a tiny inline TS script via the app's
+ * own node_modules so we get the same Prisma client + schema.
+ */
+function seedSession(env: Record<string, string>, shopDomain: string): void {
+  // Write the seed to a temp file rather than --eval to avoid having
+  // to escape `$` in the inline script (which gets eaten by various
+  // levels of shell/template-literal interpretation).
+  const tmpFile = resolve(
+    process.cwd(),
+    `.offline-seed-${randomUUID()}.mjs`,
+  );
+  const script = [
+    `import { PrismaClient } from '@prisma/client';`,
+    `const prisma = new PrismaClient();`,
+    `await prisma.session.upsert({`,
+    `  where: { id: 'offline_${shopDomain}' },`,
+    `  update: {},`,
+    `  create: {`,
+    `    id: 'offline_${shopDomain}',`,
+    `    shop: '${shopDomain}',`,
+    `    state: 'offline-mock',`,
+    `    isOnline: false,`,
+    `    accessToken: 'mock-access-token',`,
+    `    scope: process.env.SCOPES || '',`,
+    `  },`,
+    `});`,
+    `await prisma.$disconnect();`,
+    `console.log('[seedSession] OK');`,
+  ].join('\n');
+  try {
+    writeFileSync(tmpFile, script);
+    execSync(`node ${tmpFile}`, { stdio: 'inherit', env });
+  } finally {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Multi-worker via the shard-supervisor pattern.
+ *
+ * Setting `TEST_OFFLINE_WORKERS=N` runs N parallel processes, each
+ * isolated end-to-end:
+ *   - own Postgres DB (random UUID, no collision)
+ *   - own Remix backend on `BASE_PORT + shardIndex`
+ *   - own 5 mock servers on OS-assigned ports
+ *   - own Playwright invocation with `--shard k/N` to partition tests
+ *
+ * Architecture:
+ *   - Supervisor (no `TEST_OFFLINE_SHARD_INDEX` set, N>1):
+ *       1. Build cache check + build once (so shards don't race)
+ *       2. Orphan-DB cleanup once
+ *       3. Spawn N child processes (`node ... runOfflineFullTests.ts`)
+ *          each with `TEST_OFFLINE_SHARD_INDEX=k`, `TEST_OFFLINE_SKIP_BUILD=true`
+ *       4. Stream child stdout/stderr prefixed with [shard k]
+ *       5. Wait for all, exit with worst exit code
+ *   - Child (`TEST_OFFLINE_SHARD_INDEX` set):
+ *       1. Skip build (supervisor did it)
+ *       2. Skip orphan cleanup (supervisor did it)
+ *       3. Use BASE_PORT + (shardIndex-1) for backend
+ *       4. Per-shard Playwright HTML report dir
+ *       5. Append `--shard k/N` to playwright args
+ *
+ * Why a process-per-shard vs. multi-slot-in-one-process:
+ *   - Avoids ~500-line refactor of main() to manage N parallel
+ *     boots / closes / signal handlers
+ *   - Keeps Playwright's "one worker per process" model intact
+ *   - Each shard is a clean unit; crashes don't cross-contaminate
+ *   - Cost: ~5s extra per shard for backend boot (parallelized)
+ */
+async function main(): Promise<void> {
+  // Hard gate: this orchestrator only runs inside the offline container.
+  // The whole offline architecture (edge proxy on :443, /etc/hosts
+  // for *.myshopify.com, system-CA-trusted self-signed cert, port
+  // 443 bind) depends on running in a Linux microVM where:
+  //   - /etc/hosts modifications stick for the test session
+  //   - port 443 is bindable (we're root in the container)
+  //   - the system CA store can be updated without sudo theater
+  //   - a fresh DB + Postgres come with the image
+  //
+  // Running host-native would either need a different cert/port/DNS
+  // strategy or invasive Chromium/Node bypasses. We tried that path
+  // (page.route() + host-resolver-rules + a Node socket-layer shim);
+  // it worked but maintained ~400 lines of bypass code in parallel.
+  // Use `npm run test:offline-full` from the consuming app — it
+  // routes through `runDockerOffline.ts` which spawns the
+  // `essential-upsell-test:latest` image where TEST_IN_CONTAINER=true
+  // is set by docker/entrypoint.sh.
+  if (process.env['TEST_IN_CONTAINER'] !== 'true') {
+    console.error(
+      '[runOfflineFull] FATAL: must run inside the offline container.\n' +
+        '  Run: `npm run test:offline-full` (which invokes runDockerOffline.ts)\n' +
+        '  If you are seeing this from inside what should be a container, the\n' +
+        "  entrypoint script (tests/test-offline/docker/entrypoint.sh) didn't run or\n" +
+        "  didn't export TEST_IN_CONTAINER=true.",
+    );
+    process.exit(2);
+  }
+
+  // ── Offline-mode setup (idempotent, survives cold cache) ──
+  // The container entrypoint (tests/test-offline/docker/entrypoint.sh) does
+  // this when node_modules is already populated at container start.
+  // But on a FRESH Linux node_modules cache, the entrypoint runs
+  // BEFORE `npm install`, so the cert isn't on disk yet and the
+  // entrypoint's offline-setup block is skipped. Re-apply it here
+  // now that we know node_modules exists.
+  ensureOfflineSetup();
+
+  // ── Supervisor branch ─────────────────────────────────────
+  // Default to 1 (serial). The supervisor model spawns N child
+  // processes inside ONE libkrun container; each child boots its
+  // OWN edge proxy on :443 for the *.myshopify.com → 127.0.0.1
+  // hosts-file redirect. Inside a single network namespace only one
+  // bind to :443 wins — N>1 here fails with EADDRINUSE.
+  //
+  // For real parallelism, use `runIsolatedDockerOffline.ts` (one
+  // libkrun microVM per test) — each VM has its own network ns so
+  // :443 is per-VM. That's what `npm run test:offline-full:isolated`
+  // invokes; set `TEST_PARALLEL_VMS=N` to scale.
+  //
+  // Set `TEST_OFFLINE_WORKERS=N` (≥2) here only when the supervisor's
+  // edge-proxy-per-shard collision is fixed; today it's a footgun.
+  const requestedWorkers = Math.max(
+    1,
+    Number(process.env['TEST_OFFLINE_WORKERS'] ?? '1'),
+  );
+  const shardIndex = process.env['TEST_OFFLINE_SHARD_INDEX']
+    ? Number(process.env['TEST_OFFLINE_SHARD_INDEX'])
+    : null;
+  if (requestedWorkers > 1 && shardIndex === null) {
+    process.exit(await runSupervisor(requestedWorkers));
+  }
+
+  // From here on we're either a single-worker run (shardIndex
+  // null, requestedWorkers === 1) OR a child shard. Same code
+  // path; child uses shardIndex to compute its port.
+
+  // Minimal env probe: we don't need the full online-mode `.env.test`
+  // schema, but we DO want SCOPES to match what the app expects.
+  const scopes = process.env['SCOPES'] ?? 'write_products,read_products,write_discounts,read_discounts';
+  const playwrightConfig =
+    process.env['TEST_PLAYWRIGHT_CONFIG'] ??
+    'tests/test-offline/playwright.offline-full.config.ts';
+  const isChildShard = shardIndex !== null;
+  // Backend port: shard k uses BASE + (k-1); single-worker uses BASE.
+  const baseBackendPort = Number(process.env['TEST_OFFLINE_BACKEND_PORT'] ?? '8181');
+  const backendPort = String(
+    isChildShard ? baseBackendPort + (shardIndex - 1) : baseBackendPort,
+  );
+  // Production Remix serves via plain HTTP (remix-serve has no TLS).
+  // Vite dev had self-signed HTTPS; offline-full uses HTTP. The mock
+  // admin shell serves the iframe pointing here; mixed-content
+  // warnings are silenced via Chrome flags in the offlineFullStack
+  // fixture.
+  const backendUrl = `http://localhost:${backendPort}`;
+  // Skip the build if TEST_OFFLINE_SKIP_BUILD=true and a recent build
+  // exists — saves ~30s on iterative runs. Default: always build for
+  // a fresh, deterministic result.
+  const skipBuild = process.env['TEST_OFFLINE_SKIP_BUILD'] === 'true';
+
+  // ── Postgres ──────────────────────────────────────────────
+  const appName = readAppName();
+  const dbPrefix = `${appName}_offline`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  const dbName = `${dbPrefix}_${randomUUID().replace(/-/g, '_')}`;
+  const dbConn = dbUrl(dbName);
+  const preserveDb = process.env['TEST_PRESERVE_DB'] === 'true';
+
+  console.log(`[runOfflineFull] Test DB: ${dbConn}`);
+  console.log(`[runOfflineFull] Backend: ${backendUrl}`);
+
+  // Drop orphan DBs from previous crashed runs. The supervisor
+  // already did this once — children skip.
+  if (!isChildShard) {
+    dropOrphanDatabases(dbPrefix);
+  }
+
+  console.log('[runOfflineFull] createdb…');
+  execSync(`createdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`, { stdio: 'inherit' });
+
+  // ── Mock servers (in-process, sharing one ShopState) ─────
+  const state = new ShopState({
+    shop: { domain: DEFAULT_SHOP_DOMAIN, permanent_domain: DEFAULT_SHOP_DOMAIN },
+  });
+  const shopOrigin = `https://${DEFAULT_SHOP_DOMAIN}`;
+
+  // Populate `state.settings` from the active theme's
+  // `config/settings_data.json` so Dawn's CSS-variable scaffolding
+  // (`{{ settings.color_schemes }}`, `{{ settings.type_body_font }}`,
+  // etc.) renders proper CSS. Without this every storefront page
+  // ships with empty CSS variables and looks unstyled.
+  state.loadThemeSettingsFrom(dawn);
+
+  // Explore mode shows the storefront to a human, so populate it
+  // with a small set of products + a `frontpage` collection so
+  // Dawn's featured-collection section renders something other
+  // than its onboarding placeholders. Tests don't get this seed —
+  // they seed exactly what they need to assert on, which is the
+  // entire point of fresh state per test.
+  if (process.env['TEST_OFFLINE_EXPLORE'] === 'true') {
+    seedExploreProducts(state);
+  }
+
+  console.log('[runOfflineFull] booting mock servers…');
+  // 127.0.0.1 binding is the safe default — orchestrator and child
+  // both reach the mocks on loopback. Used to be subtly broken
+  // because we ran Playwright via execSync (sync, blocks the event
+  // loop), so the mocks couldn't accept connections during the
+  // test run. Now we use spawn() which keeps the loop spinning.
+  const HOSTNAME = '127.0.0.1';
+  const startOpts = { port: 0, hostname: HOSTNAME };
+
+  // Optional theme-app-extensions to inject into the storefront. Tests
+  // that exercise the storefront-rendering side of the app
+  // (e.g. funnel published in admin → visible on PDP) set this so
+  // the extension's blocks/app-embed.liquid actually runs.
+  //
+  // The env var `TEST_OFFLINE_EXTENSIONS_JSON` is a JSON array of
+  // `{ name, rootDir, enabled }` entries. Paths may be absolute or
+  // relative to the consuming app's cwd. Empty/unset → no extensions
+  // (legacy behavior: smoke tests don't need this).
+  const extensions = loadExtensions();
+
+  // Optional path to the built post-purchase extension JS. When
+  // set, the storefront mock serves a synthetic post-purchase
+  // host at `/checkouts/:token/post_purchase` that loads the JS
+  // and drives its ShouldRender callback. Env-driven so the
+  // shopify-test framework stays app-agnostic.
+  const postPurchaseExtensionPath = process.env['TEST_OFFLINE_POST_PURCHASE_EXT']
+    ? resolve(process.cwd(), process.env['TEST_OFFLINE_POST_PURCHASE_EXT']!)
+    : undefined;
+  if (postPurchaseExtensionPath && !existsSync(postPurchaseExtensionPath)) {
+    throw new Error(
+      `[runOfflineFull] TEST_OFFLINE_POST_PURCHASE_EXT points at ${postPurchaseExtensionPath} but the file doesn't exist. ` +
+        `Build the extension first — the bundled .js must exist on disk before the test run.`,
+    );
+  }
+
+  // The orchestrator owns the DB lifecycle: we build the
+  // reset-DB hook here (it captures the per-run dbName) and pass
+  // it into the storefront mock. The control plane exposes it at
+  // `POST /__test__/reset-db`. This keeps the consuming app
+  // test-agnostic — no special routes shipped in the backend.
+  // `scopes` is computed at the top of main(); reuse it here.
+  const resetDbHook = makeResetDbHook(dbName, DEFAULT_SHOP_DOMAIN, scopes);
+
+  const storefrontMock: StartedStorefront = await startStorefront(
+    createStorefrontApp({
+      state,
+      theme: dawn,
+      originForRender: shopOrigin,
+      enableControlPlane: true,
+      extensions,
+      hooks: { resetDb: resetDbHook },
+      ...(postPurchaseExtensionPath
+        ? { postPurchaseExtensionPath }
+        : {}),
+    }),
+    startOpts,
+  );
+  const adminApi: StartedAdminApi = await startAdminApi(createAdminApi({ state }), startOpts);
+  const storefrontApi: StartedStorefrontApi = await startStorefrontApi(
+    createStorefrontApi({ state }),
+    startOpts,
+  );
+  const partnerApi: StartedPartnerApi = await startPartnerApi(
+    createPartnerApi({ state }),
+    startOpts,
+  );
+  const adminShell: StartedMockAdmin = await startMockAdmin(
+    createMockAdminApp({
+      state,
+      appUrl: backendUrl,
+      clientId: MOCK_CLIENT_ID,
+      jwtSecret: DEFAULT_MOCK_JWT_SECRET,
+    }),
+    startOpts,
+  );
+  console.log(
+    `[runOfflineFull] mocks ready:\n` +
+      `   shell:        ${adminShell.baseUrl}\n` +
+      `   admin GQL:    ${adminApi.baseUrl}\n` +
+      `   storefront GQL: ${storefrontApi.baseUrl}\n` +
+      `   storefront:   ${storefrontMock.baseUrl}\n` +
+      `   partner GQL:  ${partnerApi.baseUrl}`,
+  );
+  // Self-probe: confirm each mock is reachable from this process.
+  const probes: Array<{ name: string; url: string; init: RequestInit }> = [
+    { name: 'shell', url: `${adminShell.baseUrl}/store/test/apps/x`, init: { method: 'GET' } },
+    { name: 'admin GQL', url: `${adminApi.baseUrl}/admin/api/2025-07/graphql.json`, init: { method: 'POST', body: '{"query":"{ __typename }"}', headers: { 'content-type': 'application/json' } } },
+    { name: 'storefront GQL', url: `${storefrontApi.baseUrl}/api/2025-07/graphql.json`, init: { method: 'POST', body: '{"query":"{ __typename }"}', headers: { 'content-type': 'application/json' } } },
+    { name: 'storefront', url: `${storefrontMock.baseUrl}/`, init: { method: 'GET' } },
+    { name: 'storefront control', url: `${storefrontMock.baseUrl}/__test__/state/snapshot`, init: { method: 'GET' } },
+  ];
+  for (const p of probes) {
+    try {
+      const r = await fetch(p.url, p.init);
+      console.log(`[runOfflineFull] probe ${p.name}: ${r.status}`);
+    } catch (e) {
+      console.log(`[runOfflineFull] probe ${p.name}: FAILED ${(e as Error).message}`);
+    }
+  }
+
+  // ── Edge proxy (HTTPS) ──────────────────────────────────────
+  // Single HTTPS endpoint that takes browser requests for Shopify
+  // hostnames (test-shop.myshopify.com, admin.shopify.com,
+  // cdn.shopify.com) and dispatches to the right internal mock by
+  // Host + path.
+  //
+  // The browser and Node both reach this proxy at port 443 because
+  // the container's `/etc/hosts` maps Shopify hostnames to 127.0.0.1
+  // (kernel-layer DNS rewrite — see tests/test-offline/docker/entrypoint.sh),
+  // and the edge's self-signed cert is installed as a system CA so
+  // TLS validates natively. No Chromium flags or Node monkey-patches
+  // required — DNS + TLS work the same way they would against real
+  // Shopify in production.
+  //
+  // Why an edge proxy at all (vs. running each mock on a unique port):
+  // because real Shopify serves storefront, admin shell, admin API,
+  // storefront API, and CDN all from a small set of well-known
+  // hostnames — different paths, same hosts. The edge replicates that
+  // dispatch, so tests use real-shaped URLs throughout.
+  //
+  // We bind dual-stack `::` so /etc/hosts entries for both 127.0.0.1
+  // and ::1 reach the same listener — Chrome inside the container
+  // sometimes prefers IPv6 when AAAA records exist for the hostname.
+  const edge = await startEdgeProxy({
+    backends: {
+      storefront: storefrontMock.baseUrl,
+      adminApi: adminApi.baseUrl,
+      storefrontApi: storefrontApi.baseUrl,
+      adminShell: adminShell.baseUrl,
+    },
+    shopDomain: DEFAULT_SHOP_DOMAIN,
+    // Previously bound dual-stack `::` so /etc/hosts entries for
+    // both 127.0.0.1 and ::1 hit the same listener — but on the
+    // VM kernel, listen() on `::` blocks forever
+    // (no 'error' event, no callback). 0.0.0.0 binds IPv4 only and
+    // works reliably. /etc/hosts uses 127.0.0.1 entries anyway, so
+    // IPv6 isn't needed in practice.
+    hostname: '0.0.0.0',
+    port: 443,
+  });
+  console.log(`[runOfflineFull] edge proxy: ${edge.baseUrl}`);
+
+  // ── Neon-local WS proxy (zero-app-touch) ──────────────────
+  // Bridge the app's @neondatabase/serverless driver to THIS run's local
+  // Postgres without the app changing its prisma client. The shim
+  // (preloaded into the backend below) points neonConfig.wsProxy here;
+  // the proxy reads the driver's `?address=` and forwards to Postgres.
+  const neonProxy = await startNeonWsProxy({ targetHost: PG_HOST, targetPort: Number(PG_PORT) });
+  console.log(
+    `[runOfflineFull] neon ws-proxy: 127.0.0.1:${neonProxy.port} → Postgres ${PG_HOST}:${PG_PORT}`,
+  );
+
+  // ── Backend env ───────────────────────────────────────────
+  const mswLoader = resolveMswLoaderPath();
+  const neonShim = resolveNeonShimPath();
+  const backendEnv: NodeJS.ProcessEnv = {
+    // Forward the consuming app's declared test env. The orchestrator is
+    // launched with `node --env-file=.env.test`, so .env.test's values
+    // are already in `process.env`; spreading it lets the Remix backend
+    // see app-specific vars that modules read at IMPORT time — e.g. SDK
+    // clients constructed at module scope. Remix's server bundle eagerly
+    // evaluates every route module on boot, so an app whose
+    // `anthropic.server.ts` does `new Anthropic({ apiKey: process.env… })`
+    // at top level throws "Could not resolve authentication method" and
+    // the backend never boots. Every wiring-/security-critical key below
+    // is assigned AFTER the spread, so the mock wiring always wins (local
+    // Postgres DATABASE_URL, mock-JWT SHOPIFY_API_SECRET, MSW/neon
+    // NODE_OPTIONS, mock API URLs, TEST_OFFLINE). Also carries through
+    // PRISMA_QUERY_ENGINE_LIBRARY (the linux-arm64 engine pin) the
+    // backend's prisma client needs in-VM.
+    ...process.env,
+    PATH: process.env['PATH'] ?? '',
+    // Empty-string fallback would tell child processes "HOME is set but
+    // empty" — npm in particular then writes its cache to literal `~/.npm`
+    // relative to cwd. Inside the VM cwd is /workspace
+    // (host-mounted), so that materializes as a stray `~/` directory in
+    // the consuming project on the host. Use a real path instead.
+    HOME: process.env['HOME'] || '/root',
+    USER: process.env['USER'] ?? '',
+    NODE_ENV: 'test',
+    DATABASE_URL: dbConn,
+    DIRECT_URL: dbConn,
+    // Apps that keep a SECOND database (e.g. an analytics event store the
+    // app reaches with a different client — drizzle + @neondatabase/serverless
+    // at ANALYTICS_DATABASE_URL) point it at the same offline Postgres, like
+    // DATABASE_URL. Assigned AFTER the ...process.env spread so it overrides
+    // any real value carried in from .env.test — both so the offline client
+    // connects locally (via the same neon ws-proxy) and so a real analytics
+    // DB is never reachable from an offline run. Harmless for apps without it.
+    // The non-prisma tables this client expects are created by the optional
+    // extra-schema hook below (tests/test-offline/offline-extra-schema.sql).
+    ANALYTICS_DATABASE_URL: dbConn,
+    // Auth wired to the mock JWT secret — shopify-app-remix uses this
+    // to verify session JWTs minted by the mock App Bridge.
+    SHOPIFY_API_KEY: MOCK_CLIENT_ID,
+    SHOPIFY_API_SECRET: DEFAULT_MOCK_JWT_SECRET,
+    SCOPES: scopes,
+    SHOPIFY_APP_URL: backendUrl,
+    PORT: backendPort,
+    // MSW preload: the Remix process intercepts its outbound
+    // *.myshopify.com fetches and forwards to our Admin GraphQL mock.
+    // --trace-warnings turns the otherwise-stackless UNDICI-WS
+    // warning into something diagnosable. --unhandled-rejections=strict
+    // surfaces unhandled rejections as proper exits with stack.
+    NODE_OPTIONS:
+      `--import ${JSON.stringify(`file://${mswLoader}`)} ` +
+      `--import ${JSON.stringify(`file://${neonShim}`)} ` +
+      `--trace-warnings --unhandled-rejections=strict`,
+    // Tells neonLocalShim where the in-VM Neon WS proxy listens. The
+    // shim no-ops if the app doesn't use @neondatabase/serverless, so
+    // this is harmless for apps that bypass Neon in test.
+    TEST_OFFLINE_NEON_WSPROXY_PORT: String(neonProxy.port),
+    // Surface every MSW-intercepted request in stderr so we can see
+    // whether admin.graphql calls actually reach the mock. Default
+    // off in normal runs (chatty); on for debugging.
+    ...(process.env['TEST_OFFLINE_MOCK_ADMIN_API_DEBUG']
+      ? { TEST_OFFLINE_MOCK_ADMIN_API_DEBUG: process.env['TEST_OFFLINE_MOCK_ADMIN_API_DEBUG'] }
+      : {}),
+    TEST_OFFLINE_MOCK_ADMIN_API_URL: adminApi.baseUrl,
+    // Partner API mock URL — when set, the MSW loader installs a
+    // second handler intercepting partners.shopify.com fetches.
+    // The consuming app reads `SHOPIFY_PARTNER_*` env vars at
+    // runtime to build the Partner API URL; we synthesize plausible
+    // values pointing at the mock instead of real Shopify.
+    TEST_OFFLINE_MOCK_PARTNER_API_URL: partnerApi.baseUrl,
+    SHOPIFY_APP_ID: process.env['SHOPIFY_APP_ID'] ?? '999000000',
+    SHOPIFY_PARTNER_ORGANIZATION_ID:
+      process.env['SHOPIFY_PARTNER_ORGANIZATION_ID'] ?? '11111111',
+    SHOPIFY_PARTNER_ACCESS_TOKEN:
+      process.env['SHOPIFY_PARTNER_ACCESS_TOKEN'] ?? 'mock-partner-token',
+    BILLING_IS_TEST: process.env['BILLING_IS_TEST'] ?? 'true',
+    TEST_OFFLINE: 'true',
+    // Theme app extension UUID (harmless if absent).
+    ...(process.env['SHOPIFY_UPSELLS_ID']
+      ? { SHOPIFY_UPSELLS_ID: process.env['SHOPIFY_UPSELLS_ID'] }
+      : {}),
+  };
+
+  console.log('[runOfflineFull] prisma migrate deploy…');
+  // Strip the MSW loader from NODE_OPTIONS for prisma's invocation.
+  // MSW shouldn't intercept Postgres connections (it's HTTP-only),
+  // but loading it from inside `npx prisma` triggers a silent
+  // failure inside the container (the loader's undici interception
+  // setup conflicts with prisma's CLI lifecycle in ways that don't
+  // reproduce on the host's Node 24.0). prisma's job is `migrate
+  // deploy` — pure DB work, no Shopify API calls — so dropping the
+  // MSW loader here is safe and not even semantically different.
+  const prismaEnv = { ...backendEnv };
+  delete prismaEnv['NODE_OPTIONS'];
+  execSync('npx prisma migrate deploy', { stdio: 'inherit', env: prismaEnv });
+
+  // Optional app-provided extra schema. prisma migrate only creates the
+  // prisma-managed tables; an app may also read a second database with a
+  // different ORM (e.g. drizzle for analytics) whose tables prisma doesn't
+  // know about. If the consuming app ships
+  // tests/test-offline/offline-extra-schema.sql, apply it to the SAME offline
+  // Postgres (idempotent CREATE TABLE IF NOT EXISTS), via psql with the
+  // MSW-loader-stripped env, exactly like migrate. Skipped if absent, so it's
+  // a no-op for apps that don't need it.
+  const extraSchema = resolve(process.cwd(), 'tests/test-offline/offline-extra-schema.sql');
+  if (existsSync(extraSchema)) {
+    console.log('[runOfflineFull] applying extra schema (tests/test-offline/offline-extra-schema.sql)…');
+    execSync(
+      `psql -h ${PG_HOST} -p ${PG_PORT} -d ${dbName} -v ON_ERROR_STOP=1 -f ${JSON.stringify(extraSchema)}`,
+      { stdio: 'inherit', env: prismaEnv },
+    );
+  }
+
+  console.log('[runOfflineFull] seeding session row…');
+  try {
+    seedSession(prismaEnv as Record<string, string>, DEFAULT_SHOP_DOMAIN);
+  } catch (err) {
+    console.warn(
+      `[runOfflineFull] session seed failed (continuing): ${(err as Error).message}`,
+    );
+  }
+
+  // ── Backend (Vite) ────────────────────────────────────────
+  let dev: ChildProcess | null = null;
+
+  /**
+   * Kill the backend child + drop the per-run DB. Used by:
+   *   - the normal `finally` block at end of `main()`
+   *   - the SIGINT/SIGTERM handlers below (Ctrl+C, parent kill)
+   *
+   * Idempotent: safe to call from both paths during teardown.
+   * Synchronous so it works inside signal handlers (Node only
+   * allows sync work there before the process exits).
+   *
+   * `preserveDb` (TEST_PRESERVE_DB=true) keeps the DB for
+   * post-mortem inspection — useful when chasing test-only data
+   * drift after a failure.
+   */
+  const cleanup = (): void => {
+    if (dev && !dev.killed) {
+      try {
+        dev.kill('SIGTERM');
+      } catch {
+        // ignore — child may have already exited
+      }
+    }
+    // Stop the Neon WS proxy. Fire-and-forget: cleanup runs in sync
+    // signal-handler context, and the process is exiting anyway.
+    try {
+      void neonProxy.close();
+    } catch {
+      // ignore
+    }
+    if (!preserveDb) {
+      try {
+        // `--force` terminates straggler connections (the backend
+        // process may not have closed Prisma's pool yet). Falls
+        // back to plain dropdb on older psql installs.
+        execSync(
+          `dropdb --force -h ${PG_HOST} -p ${PG_PORT} ${dbName} 2>/dev/null || dropdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`,
+          { stdio: 'ignore' },
+        );
+      } catch {
+        // Best-effort. Orphan cleanup at next run's start will get
+        // anything we leak here.
+      }
+    }
+  };
+
+  /**
+   * Signal handler: ensure the DB drops before we exit. Node would
+   * otherwise skip the `finally` block in `main()` for SIGINT/
+   * SIGTERM, leaking the DB. We run cleanup, then re-raise with
+   * the conventional exit code (`128 + signal`).
+   */
+  const onSignal = (sig: 'SIGINT' | 'SIGTERM'): void => {
+    console.log(`\n[runOfflineFull] received ${sig}, tearing down…`);
+    cleanup();
+    // 128 + signal number is the POSIX convention.
+    process.exit(sig === 'SIGINT' ? 130 : 143);
+  };
+  process.on('SIGINT', () => onSignal('SIGINT'));
+  process.on('SIGTERM', () => onSignal('SIGTERM'));
+
+  let exitCode = 1;
+  try {
+    // Production build → remix-serve (no Vite dev, no HMR). Vite dev
+    // mode injects HMR <link>/<script> tags client-side that aren't
+    // in the SSR HTML, breaking React 18's hydration check. The
+    // production build is a static SSR + client bundle pair with no
+    // such tag injection.
+    //
+    // Build-cache strategy: we hash the consuming app's source tree
+    // + package files + relevant configs. If that hash matches what
+    // we cached after the last successful build, skip the build.
+    // This makes CI-safe what `TEST_OFFLINE_SKIP_BUILD=true` does
+    // unsafely: the cache invalidates on ANY source change.
+    //
+    // Cache file lives in `build/.test-build-cache` (gitignored by
+    // virtue of being under the build/ output dir). Force a fresh
+    // build with `TEST_OFFLINE_FORCE_BUILD=true` (handy when
+    // suspecting the cache is stale, e.g. after a dependency
+    // update that didn't touch package.json hashes).
+    const buildCachePath = resolve(process.cwd(), 'build/.test-build-cache');
+    const currentBuildHash = await computeBuildHash(process.cwd());
+    const forceBuild = process.env['TEST_OFFLINE_FORCE_BUILD'] === 'true';
+    const cachedHash =
+      !forceBuild && existsSync(buildCachePath) && existsSync('build/server/index.js')
+        ? readFileSync(buildCachePath, 'utf8').trim()
+        : null;
+    const skipBuildBecauseExplicit = skipBuild;
+    const skipBuildBecauseCache = cachedHash === currentBuildHash;
+
+    if (skipBuildBecauseExplicit) {
+      console.log('[runOfflineFull] skipping build (TEST_OFFLINE_SKIP_BUILD=true)');
+    } else if (skipBuildBecauseCache) {
+      console.log(
+        `[runOfflineFull] build cache HIT (${currentBuildHash.slice(0, 12)}) — skipping npm run build. ` +
+          `Force with TEST_OFFLINE_FORCE_BUILD=true.`,
+      );
+    } else {
+      console.log(
+        `[runOfflineFull] build cache MISS — running npm run build. ` +
+          `(${cachedHash ? `was ${cachedHash.slice(0, 12)}, now ` : 'no cache, '}${currentBuildHash.slice(0, 12)})`,
+      );
+      execSync('npm run build', {
+        stdio: 'inherit',
+        env: { ...backendEnv, NODE_ENV: 'production' },
+      });
+      // Only write the cache file AFTER the build succeeds — a
+      // crashed build leaves stale `build/` we shouldn't endorse.
+      writeFileSync(buildCachePath, currentBuildHash);
+    }
+    console.log('[runOfflineFull] booting Remix prod server (remix-serve)…');
+    // Resolve remix-serve's CLI path directly — `npx remix-serve`
+    // on some systems alters NODE_OPTIONS (it spawns a child via
+    // npm-cli with PATH manipulation), which silently drops our
+    // --import preload. `node ./node_modules/.bin/remix-serve` is
+    // a hard pointer.
+    const remixServeBin = resolve(process.cwd(), 'node_modules/.bin/remix-serve');
+    const backendRuntimeEnv: NodeJS.ProcessEnv = {
+      ...backendEnv,
+      PORT: backendPort,
+      // NODE_ENV stays 'test' at RUNTIME (we set 'production' only
+      // for the build step above). app/lib/prisma.server.ts swaps
+      // in the Neon serverless WebSocket adapter on
+      // NODE_ENV=production — that's incompatible with our local
+      // Postgres setup.
+      NODE_ENV: 'test',
+    };
+    // remix-serve binds to process.env.HOST as its LISTEN address
+    // (`app.listen(port, HOST)`). Apps commonly set HOST to their public
+    // URL in .env (harmless on Vercel/prod, which never runs remix-serve)
+    // — but a URL value makes app.listen throw `getaddrinfo ENOTFOUND
+    // https://…` so the backend never boots. Drop it here so the server
+    // binds all interfaces (loopback-reachable, like apps that don't set
+    // HOST at all). Zero-app-touch: the runner owns the remix-serve
+    // process, so it owns the bind address. (prismaEnv + the build step
+    // keep HOST — only the server-listen step is sensitive to it.)
+    delete backendRuntimeEnv.HOST;
+    dev = spawn(
+      remixServeBin,
+      ['./build/server/index.js'],
+      {
+        // Route the backend's stderr to OUR stdout (fd 1). The VM runner
+        // only captures stdout, so plain 'inherit' loses backend stderr —
+        // including unhandled action throws and the MSW preload logs,
+        // which makes offline failures undebuggable.
+        stdio: ['inherit', 'inherit', 1],
+        env: backendRuntimeEnv,
+      },
+    );
+    console.log(`[runOfflineFull] waiting for backend at ${backendUrl}…`);
+    await waitForReady(backendUrl, READY_TIMEOUT_MS);
+    console.log('[runOfflineFull] backend ready.');
+
+    // ── Pre-warm Remix routes ──────────────────────────────────
+    // remix-serve lazy-compiles each route's loader/action module on
+    // first authenticated request. The first /app navigation in a
+    // test can take 5-15s on a cold backend (JIT for the route module,
+    // Prisma client init, GraphQL schema parse, mock MSW interception
+    // setup). For tests whose entire scope is "publish funnel +
+    // customer checkout", that one-time hit dominates the per-test
+    // budget — they spend 60-80s of a 90s timeout waiting for pages
+    // to render the first time.
+    //
+    // The warm-up REQUEST must pass shopify-app-remix's authenticate
+    // gate, otherwise we get a fast 302 to /auth/login and the route
+    // module never loads (we saw a 14ms total warm-up that touched
+    // nothing). Mint a real mock id_token signed with the same secret
+    // the backend is configured with.
+    //
+    // Failures are non-fatal — the next real test request will
+    // surface a clearer error than "warm-up failed".
+    console.log('[runOfflineFull] pre-warming hot Remix routes…');
+    const warmupToken = await mintIdToken({
+      shop: DEFAULT_SHOP_DOMAIN,
+      clientId: MOCK_CLIENT_ID,
+      secret: DEFAULT_MOCK_JWT_SECRET,
+    });
+    const warmupHost = Buffer.from(`${DEFAULT_SHOP_DOMAIN}/admin`).toString(
+      'base64',
+    );
+    const warmupQuery =
+      `host=${encodeURIComponent(warmupHost)}` +
+      `&shop=${DEFAULT_SHOP_DOMAIN}` +
+      `&embedded=1` +
+      `&id_token=${warmupToken}`;
+    const warmupRoutes = [
+      // The embedded-app entry — every test's first iframe goto hits
+      // this. Loads `routes/app` (auth + layout) + `routes/app._index`
+      // (dashboard loader + Polaris components). Two big modules.
+      `/app?${warmupQuery}`,
+      `/app?${warmupQuery}&_data=routes%2Fapp`,
+      `/app?${warmupQuery}&_data=routes%2Fapp._index`,
+      // Funnel-creation form — every "publish via admin UI" flow.
+      `/app/funnels/new?${warmupQuery}`,
+      `/app/funnels/new?${warmupQuery}&_data=routes%2Fapp.funnels.new`,
+    ];
+    const t0 = Date.now();
+    const warmupResults = await Promise.all(
+      warmupRoutes.map(async (path) => {
+        const tStart = Date.now();
+        try {
+          const resp = await fetch(`${backendUrl}${path}`, {
+            headers: {
+              authorization: `Bearer ${warmupToken}`,
+              // shopify-app-remix's `isbot` check returns 410 for
+              // Node's default User-Agent. Match the same UA the
+              // browser context uses in tests (see offlineFullStack
+              // fixture) so the request reaches the loader.
+              'user-agent':
+                'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+                '(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            },
+            redirect: 'manual',
+          });
+          await resp.text().catch(() => '');
+          return {
+            path,
+            status: resp.status,
+            ms: Date.now() - tStart,
+            location: resp.headers.get('location') ?? null,
+          };
+        } catch (err) {
+          return { path, error: (err as Error).message, ms: Date.now() - tStart };
+        }
+      }),
+    );
+    console.log(
+      `[runOfflineFull] route pre-warm done (${Date.now() - t0}ms):`,
+    );
+    for (const r of warmupResults) {
+      const status =
+        'error' in r ? `ERR ${r.error}` : `${r.status}${r.location ? ` → ${r.location}` : ''}`;
+      console.log(`  ${r.ms}ms ${status} ${r.path.split('?')[0]}`);
+    }
+
+    // ── Explore mode (no Playwright; manual click-around) ──
+    // When `TEST_OFFLINE_EXPLORE=true` is set, skip Playwright
+    // entirely. Instead, launch a single non-headless Chrome on the
+    // container's Xvfb display, pointed at the admin app's entry
+    // URL. The container is started with `--publish 5900:5900` +
+    // `TEST_ONLINE_VNC=1`, so the developer can connect from macOS via
+    //   open vnc://localhost:5900   (password: `test`)
+    // and click through the admin and storefront against the online
+    // mock stack. The process holds open until SIGINT/SIGTERM.
+    //
+    // This is the "interactive Shopify dev store" mode — useful
+    // for visually inspecting funnel rendering, debugging admin
+    // UI flows, mutating state via Prisma Studio in another tab,
+    // etc.
+    if (process.env['TEST_OFFLINE_EXPLORE'] === 'true') {
+      const adminUrl =
+        process.env['TEST_OFFLINE_EXPLORE_URL'] ??
+        `https://admin.shopify.com/store/test/apps/${DEFAULT_APP_HANDLE}/app`;
+      console.log('[runOfflineFull] explore mode — launching Chrome at:');
+      console.log(`   ${adminUrl}`);
+      console.log('');
+      console.log('   Useful URLs you can navigate to (all routed via the edge proxy):');
+      console.log(`     Admin app:   ${adminUrl}`);
+      console.log(`     Storefront:  https://${DEFAULT_SHOP_DOMAIN}/`);
+      console.log(`     PDP example: https://${DEFAULT_SHOP_DOMAIN}/products/placeholder`);
+      console.log(`     Cart:        https://${DEFAULT_SHOP_DOMAIN}/cart`);
+      console.log('');
+      console.log('   Connect: open vnc://localhost:5900 (password: test)');
+      console.log('   Stop: Ctrl-C');
+
+      // Drive Playwright's bundled chromium directly via its own
+      // CLI, instead of the system google-chrome.
+      //
+      // Why: real google-chrome (v148 as of writing) crashes under
+      // Apple `container`'s Rosetta amd64-on-arm64 translation with
+      //   `assertion failed [arm::is_brk_instruction(instruction)]:
+      //    SIGTRAP from kernel was not from a BRK`
+      // after a few renderer signals. The same image runs Playwright
+      // chromium (~v131) for tests with zero crashes, so the bug is
+      // Chrome v148-specific, not a container/image bug. By using
+      // Playwright's chromium for explore mode too, we get:
+      //   1. No Rosetta crash (tests prove the binary is stable)
+      //   2. Same browser tests use → identical behavior (a click
+      //      that works in a test works here)
+      //   3. No need for system google-chrome in the image at all
+      //      (could be removed in a future image trim)
+      //
+      // Profile is wiped on every launch — persistent profiles
+      // accumulate stale state (cookies pointing at old session
+      // tokens, HSTS upgrades, cached error pages) that produced
+      // mysterious "first page loads but click does nothing" bugs
+      // across cert/proxy iterations. Fresh profile = same starting
+      // point as a test.
+      try {
+        rmSync('/tmp/explore-profile', { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+
+      // Drive Playwright via its programmatic API directly — same
+      // entrypoint the test fixture uses (`chromium.launchPersistentContext`).
+      // The `playwright open` CLI is close but doesn't accept arbitrary
+      // chromium flags (we need `--allow-running-insecure-content` and
+      // the local-network-access disable-feature gang).
+      // @playwright/test re-exports `chromium` (and friends) from
+      // the underlying `playwright` package; using it avoids adding
+      // a second top-level dep.
+      const playwrightModule = await import('@playwright/test');
+      const chromiumPkg = playwrightModule.chromium;
+      assertInVm('launch a browser');
+      const exploreCtx = await chromiumPkg.launchPersistentContext(
+        '/tmp/explore-profile',
+        {
+          headless: false,
+          ignoreHTTPSErrors: true,
+          // Slightly smaller than the Xvfb screen (1600x1000) so the
+          // browser window plus its DevTools panel both fit without
+          // clipping off the right edge of the virtual display.
+          viewport: { width: 1560, height: 960 },
+          // Match the test fixture's UA so isbot heuristics + any
+          // UA-keyed app logic behave identically.
+          userAgent:
+            'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+            '(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+          args: [
+            '--no-sandbox',
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--ip-address-space-overrides=127.0.0.1:0=public,[::1]:0=public',
+            '--disable-features=LocalNetworkAccessChecks,LocalNetworkAccessChecksWebSockets,LocalNetworkAccessChecksWebTransport,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessRespectPreflightResults,PrivateNetworkAccessSendPreflights',
+            '--local-network-access-permissions-policy-default-enabled',
+            '--allow-running-insecure-content',
+            '--disable-features=BlockInsecurePrivateNetworkRequestsFromPrivate,BlockInsecurePrivateNetworkRequestsFromUnknown',
+            // Don't use --start-maximized — under Xvfb it can ask
+            // for more pixels than the virtual display has and the
+            // right edge gets clipped. Playwright's viewport setting
+            // sizes the inner window precisely instead.
+            '--window-position=0,0',
+            // Auto-open DevTools so the developer can inspect
+            // Network/Console while clicking through. The mock
+            // stack has many moving parts (edge cert, /etc/hosts,
+            // App Bridge mock, JWT bounce); when something silently
+            // fails, having Network + Console one click away cuts
+            // diagnosis from hours to seconds. Pass
+            // TEST_OFFLINE_EXPLORE_NO_DEVTOOLS=1 to disable.
+            ...(process.env['TEST_OFFLINE_EXPLORE_NO_DEVTOOLS'] === '1'
+              ? []
+              : ['--auto-open-devtools-for-tabs']),
+          ],
+        },
+      );
+      const explorePage =
+        exploreCtx.pages()[0] ?? (await exploreCtx.newPage());
+      await explorePage.goto(adminUrl, { waitUntil: 'domcontentloaded' });
+
+      // Wait indefinitely. Exit triggers:
+      //   - Developer closes the browser window → context emits `close`.
+      //   - Container receives SIGINT/SIGTERM → we close the context
+      //     and resolve so the outer `finally` can tear down mocks.
+      await new Promise<void>((resolveExit) => {
+        const onSignal = () => {
+          exploreCtx.close().catch(() => {});
+          resolveExit();
+        };
+        exploreCtx.on('close', () => resolveExit());
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+      });
+      exitCode = 0;
+      return;
+    }
+
+    // ── Playwright ─────────────────────────────────────────
+    console.log('[runOfflineFull] running Playwright…');
+    const playwrightEnv: NodeJS.ProcessEnv = {
+      ...process.env,
+      // Expose the per-run test DB to specs so they can seed/inspect the
+      // app's OWN Postgres directly (e.g. seed Article rows for
+      // list/detail flows). The mock ShopState covers Shopify resources,
+      // but the app DB has no control plane — and apps whose create flow
+      // is gated behind external services (AI, queues) can't be seeded
+      // via their action routes offline. The Playwright process runs in
+      // the same VM as Postgres, so a plain `pg` client on this URL
+      // reaches it directly (no Neon proxy needed).
+      DATABASE_URL: dbConn,
+      DIRECT_URL: dbConn,
+      TEST_OFFLINE_ORCHESTRATED: 'true',
+      TEST_OFFLINE_MOCK_ADMIN_SHELL_URL: adminShell.baseUrl,
+      TEST_OFFLINE_MOCK_ADMIN_API_URL: adminApi.baseUrl,
+      TEST_OFFLINE_MOCK_STOREFRONT_API_URL: storefrontApi.baseUrl,
+      TEST_OFFLINE_MOCK_STOREFRONT_URL: storefrontMock.baseUrl,
+      TEST_OFFLINE_MOCK_BACKEND_URL: backendUrl,
+      TEST_OFFLINE_MOCK_PARTNER_API_URL: partnerApi.baseUrl,
+      TEST_OFFLINE_MOCK_SHOP_DOMAIN: DEFAULT_SHOP_DOMAIN,
+      TEST_OFFLINE_MOCK_APP_HANDLE: DEFAULT_APP_HANDLE,
+      TEST_OFFLINE_MOCK_CLIENT_ID: MOCK_CLIENT_ID,
+      TEST_OFFLINE_MOCK_EDGE_URL: edge.baseUrl,
+      TEST_OFFLINE_MOCK_EDGE_PORT: String(edge.port),
+    };
+    // Use async spawn (NOT execSync) — execSync blocks the
+    // orchestrator's event loop, so the in-process mock servers
+    // can't accept connections from the Playwright child while
+    // tests run. Subtle and ruins everything.
+    // Build Playwright arg list. When this orchestrator is a child
+    // shard, `--shard k/N` partitions the test files across all
+    // shards (Playwright auto-distributes based on file count).
+    // Per-shard HTML reports go to distinct dirs so they don't
+    // collide on a shared workspace.
+    const playwrightArgs: string[] = [
+      'playwright',
+      'test',
+      '--config',
+      playwrightConfig,
+    ];
+    if (isChildShard && requestedWorkers > 1) {
+      playwrightArgs.push('--shard', `${shardIndex}/${requestedWorkers}`);
+      // Per-shard output dirs (defaults would clobber each other).
+      playwrightArgs.push('--output', `test-results-shard-${shardIndex}`);
+      playwrightEnv['PLAYWRIGHT_HTML_REPORT'] = `playwright-report-shard-${shardIndex}`;
+    }
+    // Forward user-supplied argv to Playwright — `--grep "name"`,
+    // a file path, `--repeat-each`, etc. The docker runner already
+    // forwards user args verbatim into this script's argv; we just
+    // pass them through to playwright so single-test iteration is
+    // possible (`npm run test:offline-full -- --grep "PDP form"`).
+    // Skip our own known flags (currently none after the launcher
+    // strips them — process.argv[0] is `node`, argv[1] is this
+    // script).
+    const userArgs = process.argv.slice(2).filter((a) => a.length > 0);
+    if (userArgs.length > 0) {
+      playwrightArgs.push(...userArgs);
+    }
+    const playwrightExitCode = await new Promise<number>((resolveCode, rejectCode) => {
+      const proc = spawn('npx', playwrightArgs, { stdio: 'inherit', env: playwrightEnv });
+      proc.on('exit', (code) => resolveCode(code ?? 1));
+      proc.on('error', rejectCode);
+    });
+    if (playwrightExitCode !== 0) {
+      throw new Error(`Playwright exited with code ${playwrightExitCode}`);
+    }
+    exitCode = 0;
+  } catch (err) {
+    console.error(`[runOfflineFull] failed: ${(err as Error).message}`);
+  } finally {
+    console.log('[runOfflineFull] tearing down…');
+    // `cleanup()` kills the backend AND drops the DB (with
+    // preserveDb honored). It's the same function the signal
+    // handlers call, so the teardown path is identical whether
+    // we exit gracefully or via Ctrl+C.
+    cleanup();
+    await sleep(1_000);
+
+    // Close mocks. Errors here shouldn't mask test exit code.
+    await Promise.allSettled([
+      edge.close(),
+      adminShell.close(),
+      adminApi.close(),
+      storefrontApi.close(),
+      storefrontMock.close(),
+      partnerApi.close(),
+    ]);
+
+    if (preserveDb) {
+      console.log(`[runOfflineFull] DB preserved: ${dbName}`);
+    }
+  }
+
+  process.exit(exitCode);
+}
+
+// computeBuildHash now lives in @essential-apps/shopify-test-core
+// (shared with runOffline's host build, so the host + in-VM build caches
+// agree). Imported at the top of this file.
+
+/**
+ * Parse `TEST_OFFLINE_EXTENSIONS_JSON` into an array of ExtensionConfig.
+ * Schema (JSON array):
+ *   [{ name: string, rootDir: string, enabled?: boolean }, ...]
+ *
+ * `rootDir` may be absolute or relative to `process.cwd()` (the
+ * consuming app's checkout). Validates that each rootDir exists and
+ * fails fast otherwise — silently dropping mis-spelled paths leads
+ * to "extension didn't render" mysteries.
+ */
+function loadExtensions(): ExtensionConfig[] {
+  const raw = process.env['TEST_OFFLINE_EXTENSIONS_JSON'];
+  if (!raw) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `[runOfflineFull] TEST_OFFLINE_EXTENSIONS_JSON is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(
+      `[runOfflineFull] TEST_OFFLINE_EXTENSIONS_JSON must be a JSON array; got ${typeof parsed}`,
+    );
+  }
+  const out: ExtensionConfig[] = [];
+  for (const entry of parsed) {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new Error(`[runOfflineFull] extension entry must be an object: ${JSON.stringify(entry)}`);
+    }
+    const e = entry as { name?: unknown; rootDir?: unknown; enabled?: unknown };
+    if (typeof e.name !== 'string' || typeof e.rootDir !== 'string') {
+      throw new Error(
+        `[runOfflineFull] each extension needs { name: string, rootDir: string }; got ${JSON.stringify(entry)}`,
+      );
+    }
+    const rootDir = resolve(process.cwd(), e.rootDir);
+    if (!existsSync(rootDir)) {
+      throw new Error(`[runOfflineFull] extension rootDir does not exist: ${rootDir}`);
+    }
+    out.push({
+      name: e.name,
+      rootDir,
+      enabled: e.enabled !== false,
+    });
+  }
+  if (out.length > 0) {
+    console.log(
+      `[runOfflineFull] loaded ${out.length} extension(s): ${out.map((e) => `${e.name}=${e.rootDir}`).join(', ')}`,
+    );
+  }
+  return out;
+}
+
+/**
+ * Supervisor mode — fans out N child orchestrator processes.
+ * Each child runs the same script with `TEST_OFFLINE_SHARD_INDEX=k`
+ * + `TEST_OFFLINE_WORKERS=N` so it picks its slot via the
+ * conditional at the top of `main()`.
+ *
+ * We do the build ONCE (before fanning out) and pass
+ * `TEST_OFFLINE_SKIP_BUILD=true` to children to avoid N parallel
+ * builds racing on the same `build/` directory. Orphan DB cleanup
+ * also runs once here.
+ *
+ * Output streams are inherited (children print directly to our
+ * stdout/stderr). Lines aren't prefixed by shard — Playwright's
+ * own output already includes test paths which disambiguate.
+ *
+ * Returns the worst child exit code so the supervisor's exit
+ * accurately reflects failure.
+ */
+
+/**
+ * Seed a small product catalog + featured collection for explore
+ * mode. Just enough variety so Dawn's homepage sections render
+ * something realistic — different price points, a "compare at"
+ * (for on-sale styling), a fake image URL each so card layout
+ * exercises both with-image and without-image paths.
+ *
+ * Not used by tests (they seed what they assert on).
+ */
+function seedExploreProducts(state: ShopState): void {
+  // Image URLs point at the bundled Shopify-asset mirror — these are
+  // the actual product photos from theme-dawn-demo.myshopify.com,
+  // captured by the `mirror` probe. Browser requests are routed by
+  // the edge proxy + `/__shopify-mirror/*` handler so they 200 with
+  // real byte content (no broken-image placeholders during explore).
+  //
+  // Real Shopify normalizes uploaded image URLs to its CDN; we
+  // emit `https://test-shop.myshopify.com/cdn/shop/products/<file>`
+  // (per-shop CDN proxy shape) which our mirror handler resolves
+  // host-agnostically by matching the `/cdn/shop/products/<file>`
+  // suffix.
+  const cdn = (file: string) =>
+    `https://test-shop.myshopify.com/cdn/shop/products/${file}`;
+  // Seed product titles match the actual photos mirrored from the
+  // Dawn-demo store (it's a handbag store; the images are bags).
+  // Mismatching titles + handbag photos looked broken — the user
+  // saw "Snowboard" text with a purse photo. Aligning them keeps
+  // explore mode visually coherent. Image filenames reproduce the
+  // exact mirrored basenames (Shopify hashes are preserved).
+  const fixtures: Array<{
+    title: string;
+    handle: string;
+    price: number;
+    compareAt?: number;
+    description: string;
+    image: string;
+  }> = [
+    { title: 'Art Deco Bag',     handle: 'art-deco-bag',     price: 39900,                  description: 'Statement crossbody in cyclamen pink.',  image: 'mlouye-art-deco-cyclamen-1_ec8e69b6-92ea-4c48-b8b6-34601cf3c070.jpg' },
+    { title: 'Bo Ivy Bag',       handle: 'bo-ivy-bag',       price: 28900, compareAt: 34900,  description: 'Sculpted shoulder bag in emerald green.', image: 'mlouye-bo-ivy-emerald-1_73c3987e-5ec7-4e72-879a-2ba2e560648f.jpg' },
+    { title: 'Soft Strap Bag',   handle: 'soft-strap-bag',   price: 35900,                  description: 'Soft brown leather, structured strap.',  image: 'mlouye-bo-soft-strap-brown-1.jpg' },
+    { title: 'Brick Mini Bag',   handle: 'brick-mini-bag',   price: 22900,                  description: 'Oil-yellow rectangular mini.',           image: 'mlouye-brick-oil-yellow-1.jpg' },
+    { title: 'Business Bag',     handle: 'business-bag',     price: 49900,                  description: 'Black-and-grey carry-all.',              image: 'mlouye-business-bag-black_grey-1.jpg' },
+    { title: 'Helix Multi Bag',  handle: 'helix-multi-bag',  price: 41900,                  description: 'Statement multicolor helix shape.',      image: 'mlouye-helix-multicolor-2_1800x1800_10c62242-6743-4d46-a251-defa246dd195.jpg' },
+  ];
+  for (const f of fixtures) {
+    const src = cdn(f.image);
+    const img = { src, alt: f.title, width: 800, height: 800 };
+    state.addProduct({
+      title: f.title,
+      handle: f.handle,
+      description: f.description,
+      description_text: f.description,
+      price: f.price,
+      compare_at_price: f.compareAt ?? null,
+      vendor: 'Snowboard Vendor',
+      type: 'Snowboards',
+      tags: ['Featured', 'New'],
+      // Collection membership is wired by addCollection below.
+      featured_image: img,
+      // Dawn reads `card_product.featured_media`, NOT `featured_image`,
+      // for product-card rendering — it's a Shopify "Media" object
+      // with extra `.aspect_ratio` / `.preview_image` props. Without
+      // this Dawn skips the image block on every product card.
+      featured_media: {
+        ...img,
+        aspect_ratio: 1,
+        media_type: 'image',
+        preview_image: img,
+      },
+      // Dawn's PDP main-product section reads `product.media` (an
+      // ARRAY of Media objects) to build the gallery. Without this
+      // the product page shows no image. `position` is the 1-indexed
+      // slot in the gallery; we only have one.
+      media: [
+        {
+          id: img.width * 100 + 1,
+          position: 1,
+          media_type: 'image',
+          aspect_ratio: 1,
+          preview_image: img,
+          ...img,
+        },
+      ],
+      images: [img],
+    });
+  }
+  // Seed BOTH collections Dawn's default templates reference:
+  //   - `all`       — referenced by `templates/index.json`'s
+  //                   featured-collection section by default
+  //   - `frontpage` — referenced by various sections that look
+  //                   for the merchant's main landing collection
+  // Add the products to both so each section renders its own
+  // grid even before the merchant edits the template.
+  const handles = fixtures.map((f) => f.handle);
+  state.addCollection({ handle: 'all',       title: 'All products',     productHandles: handles });
+  state.addCollection({ handle: 'frontpage', title: 'Home page',        productHandles: handles });
+}
+
+async function runSupervisor(workers: number): Promise<number> {
+  console.log(`[runOfflineFull] supervisor: spawning ${workers} shard(s)…`);
+
+  // Pre-build: each child would otherwise duplicate the build (or
+  // race on the cache). Build here once, then pass SKIP_BUILD=true
+  // to children. The build cache check still runs (cheap), so this
+  // is a no-op on warm caches.
+  const appRoot = process.cwd();
+  const buildCachePath = resolve(appRoot, 'build/.test-build-cache');
+  const currentBuildHash = await computeBuildHash(appRoot);
+  const cachedHash =
+    existsSync(buildCachePath) && existsSync('build/server/index.js')
+      ? readFileSync(buildCachePath, 'utf8').trim()
+      : null;
+  if (cachedHash === currentBuildHash) {
+    console.log(`[runOfflineFull] supervisor: build cache HIT (${currentBuildHash.slice(0, 12)})`);
+  } else {
+    console.log(`[runOfflineFull] supervisor: build cache MISS — running npm run build…`);
+    execSync('npm run build', {
+      stdio: 'inherit',
+      // `TEST_OFFLINE=true` switches the consuming app's
+      // vite.config.ts off of any production deployment preset
+      // (e.g. Vercel's `vercelPreset()`) and back to the plain
+      // Remix build that produces `build/server/index.js`. Without
+      // this, presets that shard the output by runtime (e.g.
+      // `build/server/nodejs-…/`) leave the expected `index.js`
+      // path empty and the child shard's `remix-serve` errors with
+      // ENOENT. The non-supervisor path (line ~911) already passes
+      // this through `backendEnv`; we mirror it here so both build
+      // paths produce the same artifact layout.
+      env: { ...process.env, NODE_ENV: 'production', TEST_OFFLINE: 'true' },
+    });
+    writeFileSync(buildCachePath, currentBuildHash);
+  }
+
+  // Orphan-DB cleanup once for the whole supervisor run.
+  const appName = readAppName();
+  const dbPrefix = `${appName}_offline`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  dropOrphanDatabases(dbPrefix);
+
+  // Spawn N children in parallel.
+  const childScript = process.argv[1] ?? '';
+  const children: Array<Promise<number>> = [];
+  for (let k = 1; k <= workers; k++) {
+    const childEnv: NodeJS.ProcessEnv = {
+      ...process.env,
+      TEST_OFFLINE_SHARD_INDEX: String(k),
+      TEST_OFFLINE_WORKERS: String(workers),
+      TEST_OFFLINE_SKIP_BUILD: 'true',
+    };
+    children.push(
+      new Promise<number>((resolveChild, rejectChild) => {
+        // Re-exec ourselves through `node --import tsx` so TS still
+        // parses. argv[1] points at the user's `runOfflineFullTests.ts`
+        // by the time we're invoked from the consuming app's
+        // npm script.
+        const proc = spawn(
+          process.execPath,
+          ['--import', 'tsx', childScript],
+          { stdio: 'inherit', env: childEnv },
+        );
+        proc.on('exit', (code) => resolveChild(code ?? 1));
+        proc.on('error', rejectChild);
+      }),
+    );
+  }
+  const exitCodes = await Promise.all(children);
+  const worst = exitCodes.reduce((a, b) => Math.max(a, b), 0);
+  console.log(
+    `[runOfflineFull] supervisor: shard exit codes [${exitCodes.join(', ')}]; overall=${worst}`,
+  );
+  return worst;
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});