fix(tests): stagger iframe worker launch + richer import error

Reported: on production tko.io under Safari, one spec
occasionally fails with the opaque WebKit message
`Importing a module script failed.` — most often a spec that
imports a large chunk graph (e.g. `builds/reference/spec/
bindingGlobalsBehavior.js`, which imports the full reference
build). Chromium handles the same graph fine. The failure mode
is known across Astro, SvelteKit, Nuxt, Immich, and tracks
against upstream WebKit bug 242740.

Two changes:

1. **Stagger worker launch** in tests.astro. With pool=4 every
   worker used to spawn its first iframe simultaneously, hitting
   the same shared module-graph chunks concurrently — that's
   what triggers the WebKit race. A 120ms per-worker offset
   spaces the first-round fetches (360ms total head-start for
   pool=4) and removes the contention without materially
   slowing the run (still ~5.2s end-to-end; was ~5.4s).
2. **Richer error on failure** in tests-frame.html. Keep the
   original dynamic `import()` (no retry) but in the catch,
   re-fetch the spec URL with `cache: 'no-store'` and report
   HTTP status, content-length, and content-type alongside the
   original WebKit message in both the in-frame err div and
   the `import-error` postMessage. Gives something actionable
   when the failure does surface.

Author: Brian M Hunt

tko.io/package.json

@@ -7,10 +7,10 @@
     "postinstall": "patch-package",
     "prebuild": "bun ./scripts/generate-verified-behaviors.mjs && mkdir -p public/lib && cd ../builds/knockout && bun run build && cp dist/browser.min.js ../../tko.io/public/lib/ko.js && cd ../reference && bun run build && cp dist/browser.min.js ../../tko.io/public/lib/tko.js && cd ../../tko.io && bun ./scripts/bundle-tests.mjs",
     "predev": "bun run prebuild",
-    "dev": "ASTRO_TELEMETRY_DISABLED=1 astro dev",
-    "build": "ASTRO_TELEMETRY_DISABLED=1 astro build --force",
-    "preview": "ASTRO_TELEMETRY_DISABLED=1 astro preview",
-    "check": "ASTRO_TELEMETRY_DISABLED=1 astro check"
+    "dev": "ASTRO_TELEMETRY_DISABLED=1 bun --bun astro dev",
+    "build": "ASTRO_TELEMETRY_DISABLED=1 bun --bun astro build --force",
+    "preview": "ASTRO_TELEMETRY_DISABLED=1 bun --bun astro preview",
+    "check": "ASTRO_TELEMETRY_DISABLED=1 bun --bun astro check"
   },
   "keywords": ["tko", "knockout", "documentation"],
   "author": "",

tko.io/public/tests-frame.html

@@ -64,11 +64,43 @@
     <script type="module">
       const qs = new URLSearchParams(location.search)
       const slug = qs.get('spec')
+      const specUrl = `/tests/source/${slug}.js`
+
+      // On failure the opaque WebKit "Importing a module script
+      // failed." message carries no URL or status. Refetch the
+      // spec URL in the catch and surface HTTP status + size so
+      // the parent can show something useful. The parent prefetches
+      // every shared chunk into the browser HTTP cache before
+      // spawning iframes to avoid the race that produces the opaque
+      // error in the first place; see source-mode chunk prefetch in
+      // tests.astro.
+      //
+      // Refs:
+      //   https://github.com/withastro/astro/issues/14775
+      //   https://github.com/sveltejs/kit/issues/5208
+      //   https://github.com/nuxt/nuxt/issues/33478
+      //   https://bugs.webkit.org/show_bug.cgi?id=242740
+      async function diagnose(err) {
+        try {
+          const res = await fetch(specUrl, { cache: 'no-store' })
+          const status = res.statusText ? `${res.status} ${res.statusText}` : `${res.status}`
+          const size = res.headers.get('content-length') ?? '?'
+          const type = res.headers.get('content-type') || 'unknown'
+          // `res` only covers the top-level spec URL. If this HTTP
+          // probe reports 2xx, the failure was most likely in a
+          // transitive chunk of the module graph, not this file.
+          const note = res.ok ? ' (top-level OK — failure likely in a transitive chunk)' : ''
+          return `import failed at ${specUrl} [HTTP ${status}, ${size}B, ${type}]${note}: ${err?.message || err}`
+        } catch (fetchErr) {
+          return `import failed at ${specUrl} (fetch also failed: ${fetchErr?.message || fetchErr}): ${err?.message || err}`
+        }
+      }
+
       if (!slug) {
         document.getElementById('err').textContent = 'missing ?spec= query param'
       } else {
         try {
-          await import(`/tests/source/${slug}.js`)
+          await import(specUrl)
           const runner = mocha.run()
           runner.on('pass', t => parent.postMessage({ type: 'pass', slug, title: t.fullTitle(), duration: t.duration }, '*'))
           runner.on('fail', (t, err) => parent.postMessage({
@@ -80,8 +112,9 @@
           runner.on('end', () => parent.postMessage({ type: 'end', slug, stats: runner.stats }, '*'))
           parent.postMessage({ type: 'start', slug, total: runner.total }, '*')
         } catch (err) {
-          document.getElementById('err').textContent = 'import failed: ' + (err?.message || err)
-          parent.postMessage({ type: 'import-error', slug, err: err?.message || String(err) }, '*')
+          const detail = await diagnose(err)
+          document.getElementById('err').textContent = detail
+          parent.postMessage({ type: 'import-error', slug, err: detail }, '*')
         }
       }
     </script>

tko.io/scripts/bundle-tests.mjs

@@ -275,9 +275,21 @@ async function buildSourceBundles({ buildVersion, tsconfig, alias }) {
     logLevel: 'warning'
   })
 
+  // Enumerate the shared chunk files esbuild emitted alongside
+  // the per-spec bundles. The parent page prefetches these once
+  // before spawning iframes so the browser HTTP cache is warm —
+  // otherwise multiple iframes race to fetch the same chunks and
+  // WebKit occasionally reports the opaque "Importing a module
+  // script failed." error. See tko.io/src/pages/tests.astro.
+  const chunks = []
+  for await (const name of new Bun.Glob('chunk-*.js').scan({ cwd: sourceOutputDir })) {
+    chunks.push(name)
+  }
+  chunks.sort()
+
   await fs.writeFile(
     path.join(sourceOutputDir, 'manifest.json'),
-    JSON.stringify({ specs: manifest }, null, 2),
+    JSON.stringify({ specs: manifest, chunks }, null, 2),
     'utf8'
   )
 

tko.io/src/pages/tests.astro

@@ -1,4 +1,27 @@
 ---
+import { fileURLToPath } from 'node:url'
+
+// Read the source-mode chunk list at SSR time so the HTML ships
+// with <link rel="modulepreload"> for every shared chunk already
+// in <head>. The browser starts warming the HTTP cache during
+// initial parse — well before any JS runs — which side-steps the
+// concurrent-fetch race that makes WebKit occasionally fail spec
+// iframes with the opaque "Importing a module script failed."
+// error. `prebuild` always runs bundle-tests.mjs before Astro
+// builds the site, so manifest.json is guaranteed to exist; the
+// catch is only for the very first `bun run dev` invocation.
+// Scripts (and Astro under `bun --bun`) run on Bun, so use
+// Bun.file rather than node:fs.
+let sourceChunks: string[] = []
+try {
+  const manifestPath = fileURLToPath(new URL('../../public/tests/source/manifest.json', import.meta.url))
+  const manifest = await Bun.file(manifestPath).json()
+  sourceChunks = manifest.chunks ?? []
+} catch {
+  // bundle hasn't run yet — runSourceMode's runtime fallback
+  // still injects missing <link> tags client-side.
+}
+
 // TKO Browser Test Runner — written in TKO itself.
 //
 // Two modes:
@@ -32,6 +55,8 @@
     <title>TKO · Browser Tests</title>
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Lobster&display=swap" />
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mocha@10/mocha.css" />
+    {sourceChunks.map(name => <link rel="modulepreload" href={`/tests/source/${name}`} />)}
+    <link rel="preload" as="script" href="/tests/source/setup.js" />
     <style>
       :root {
         --bg: #0b0d11;
@@ -520,6 +545,28 @@
         const res = await fetch('/tests/source/manifest.json')
         const manifest = await res.json()
         let specs = manifest.specs
+
+        // Chunks are normally preloaded via <link rel="modulepreload">
+        // rendered in the page's <head> at SSR time (see frontmatter).
+        // If the rendered page predates the current bundle (e.g.
+        // Astro SSR'd before bundle-tests.mjs ran, or manifest has
+        // new chunks), inject any missing <link>s now so the browser
+        // warms the HTTP cache before iframes race on it.
+        const head = document.head
+        const existing = new Set(
+          [...head.querySelectorAll('link[rel=modulepreload]')].map(l => l.getAttribute('href'))
+        )
+        const missing = (manifest.chunks || [])
+          .map(name => `/tests/source/${name}`)
+          .filter(href => !existing.has(href))
+        await Promise.all(missing.map(href => new Promise(resolve => {
+          const link = document.createElement('link')
+          link.rel = 'modulepreload'
+          link.href = href
+          link.addEventListener('load', resolve, { once: true })
+          link.addEventListener('error', resolve, { once: true })
+          head.appendChild(link)
+        })))
         const grep = page.grep().trim()
         if (grep) {
           // Invalid regex patterns (e.g. bare `(`) throw from the
@@ -632,7 +679,10 @@
           })
         }
 
-        // Phase 1: parallel hidden specs.
+        // Phase 1: parallel hidden specs. The chunk prefetch
+        // above warmed the HTTP cache, so iframes can safely race
+        // on dynamic import() without tripping WebKit's
+        // dependency-tree fetcher.
         async function hiddenWorker() {
           while (hiddenQueue.length) {
             const spec = hiddenQueue.shift()