@essential-apps/shopify-test-runner 1.0.0

package/dist/scripts/runOfflineFullTests.js

@@ -0,0 +1,1456 @@
+#!/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 } 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, } from '@essential-apps/shopify-test-storefront';
+import { dawn } from '@essential-apps/shopify-test-themes';
+import { createAdminApi, startAdminApi, createStorefrontApi, startStorefrontApi, createPartnerApi, startPartnerApi, } from '@essential-apps/shopify-test-shopify-api';
+import { createMockAdminApp, startMockAdmin, DEFAULT_MOCK_JWT_SECRET, mintIdToken, } 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';
+function readAppName() {
+    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'));
+    if (!pkg.name)
+        throw new Error(`package.json has no name field.`);
+    return pkg.name.replace(/^@[^/]+\//, '');
+}
+function dbUrl(name) {
+    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) {
+    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.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, shopDomain, scopes) {
+    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.stderr?.toString() ?? '';
+            const stdout = err.stdout?.toString() ?? '';
+            throw new Error(`[resetDb] psql failed: ${err.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, timeoutMs) {
+    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,
+            });
+            if (res.status > 0)
+                return;
+        }
+        catch (e) {
+            lastErr = e.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() {
+    // 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 = [];
+    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.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.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.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() {
+    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() {
+    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, shopDomain) {
+    // 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() {
+    // 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 = await startStorefront(createStorefrontApp({
+        state,
+        theme: dawn,
+        originForRender: shopOrigin,
+        enableControlPlane: true,
+        extensions,
+        hooks: { resetDb: resetDbHook },
+        ...(postPurchaseExtensionPath
+            ? { postPurchaseExtensionPath }
+            : {}),
+    }), startOpts);
+    const adminApi = await startAdminApi(createAdminApi({ state }), startOpts);
+    const storefrontApi = await startStorefrontApi(createStorefrontApi({ state }), startOpts);
+    const partnerApi = await startPartnerApi(createPartnerApi({ state }), startOpts);
+    const adminShell = 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 = [
+        { 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.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 = {
+        // 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, DEFAULT_SHOP_DOMAIN);
+    }
+    catch (err) {
+        console.warn(`[runOfflineFull] session seed failed (continuing): ${err.message}`);
+    }
+    // ── Backend (Vite) ────────────────────────────────────────
+    let dev = 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 = () => {
+        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) => {
+        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 = {
+            ...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.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((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 = {
+            ...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 = [
+            '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((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.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() {
+    const raw = process.env['TEST_OFFLINE_EXTENSIONS_JSON'];
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`[runOfflineFull] TEST_OFFLINE_EXTENSIONS_JSON is not valid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`[runOfflineFull] TEST_OFFLINE_EXTENSIONS_JSON must be a JSON array; got ${typeof parsed}`);
+    }
+    const out = [];
+    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;
+        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) {
+    // 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) => `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 = [
+        { 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) {
+    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 = [];
+    for (let k = 1; k <= workers; k++) {
+        const childEnv = {
+            ...process.env,
+            TEST_OFFLINE_SHARD_INDEX: String(k),
+            TEST_OFFLINE_WORKERS: String(workers),
+            TEST_OFFLINE_SKIP_BUILD: 'true',
+        };
+        children.push(new Promise((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);
+});
+//# sourceMappingURL=runOfflineFullTests.js.map