ci(e2e): serve hub-client via vite preview instead of vite dev

Cuts wall time and removes flakes by replacing the dev-mode hub-client
server with a prebuilt bundle served through `vite preview`. The win is
mostly mechanical: a cold Playwright context downloads ~50 MB of assets
(WASM dominates at 32 MB). Through `vite dev` that goes uncompressed and
serializes through a single-threaded transform pipeline; through
`vite preview` with a gzip middleware it's ~5.6 MB on the wire and
served as static files. Under 2 Playwright workers on a 2-core CI
runner this was the source of the "preview iframe didn't render in 45s"
flakes.

Local smoke-all: 1.9 min / 1 flake → 1.1 min / 0 flakes (42% faster).
Full functional suite: 72 passed, 0 failed, 3 flaky (recovered), 2.6 min.

Major pieces
- hub-client/vite.config.ts: mirror `server.proxy` into `preview.proxy`
  (preview ignores `server.proxy`). Add a small `configurePreviewServer`
  plugin that runs `compression()` middleware; override its filter so
  `application/wasm` is included (mime-db marks it non-compressible by
  default — in practice it gzips ~6:1).
- hub-client/playwright.config.ts: `webServer.command` → `vite preview`;
  comment why it's not `vite dev` so the next agent doesn't "helpfully"
  revert it for HMR.
- hub-client/ast-renderer.html: moved from `public/` to project root.
  When it lived in `public/` the build emitted two copies — the
  transformed one at `dist/public/ast-renderer.html` and a raw copy at
  `dist/ast-renderer.html` (with a dev-only `<script src="/src/...tsx">`
  reference). The iframe `src="/ast-renderer.html"` hit the raw one in
  preview mode and the q2-debug E2E test broke. This was a latent prod
  bug — `vite dev` happened to mask it via source-path resolution.

Test-hook plumbing
- src/test-hooks.ts (new): registers
  `window.__quartoTest = { projectStorage, wasmRenderer }`. Tree-shaken
  out of any build without `VITE_E2E=1`.
- src/main.tsx: kicks off `import('./test-hooks')` and stores the
  promise on `window.__quartoTestReady`. Top-level `await` here doesn't
  help (the `load` event fires before module top-level awaits resolve),
  so tests `await window.__quartoTestReady` before reading the hooks.
- e2e/helpers/testHooks.ts (new): typed global augmentation.
- e2e/helpers/previewExtraction.ts, projectFactory.ts,
  share-link-project-set.spec.ts: 5 `await import('/src/services/...ts')`
  call sites replaced with `await window.__quartoTestReady` +
  `window.__quartoTest.{projectStorage,wasmRenderer}`. The dev-only
  source-path imports stopped working under `vite preview` (prod
  bundles don't expose source paths).
- package.json: `test:e2e[:ui]` scripts now set `VITE_E2E=1` and build
  before running playwright (since preview serves from `dist/`).
- .github/workflows/hub-client-e2e.yml: `VITE_E2E: '1'` on the Build
  TypeScript packages step.

Side effects worth knowing
- Running `npx playwright test` directly (bypassing `npm run test:e2e`)
  serves whatever was last built into `dist/` — possibly stale. The
  npm-script path always rebuilds.
- New devDeps `compression` + `@types/compression` (83 transitive
  packages, dev-only, no shipped code). No production runtime change.
- `vite dev`, `vite build` defaults, and the production user bundle are
  untouched: the compression plugin only fires under `vite preview`,
  and test-hooks is dead-code-eliminated without `VITE_E2E=1`.

Author: gordonwoodhull

.github/workflows/hub-client-e2e.yml

@@ -105,7 +105,16 @@ jobs:
       # q2-demos/* currently fail their vite build (they import an
       # absolute path "/src/wasm-js-bridge/cache.js" that only exists
       # in hub-client/), and trace-viewer is not under test here.
+      #
+      # VITE_E2E=1 on the hub-client build pulls in src/test-hooks.ts so
+      # the Playwright suite can reach internal services via
+      # `window.__quartoTest` (production bundles don't expose source
+      # paths the way `vite dev` did). The flag is consumed only by the
+      # `if (import.meta.env.VITE_E2E === '1')` branch in src/main.tsx;
+      # production-user builds leave it unset and tree-shake the hooks out.
       - name: Build TypeScript packages (ts-packages + hub-client)
+        env:
+          VITE_E2E: '1'
         run: |
           for pkg in ts-packages/*/; do
             if [ -f "$pkg/package.json" ]; then

hub-client/public/ast-renderer.html hub-client/ast-renderer.htmlhub-client/public/ast-renderer.html renamed to hub-client/ast-renderer.html

@@ -6,6 +6,7 @@
  */
 
 import type { Page } from '@playwright/test';
+import type {} from './testHooks';
 
 /**
  * Wait for the preview iframe to render content.
@@ -101,8 +102,10 @@ export async function getPreviewHtml(
   documentPath: string,
 ): Promise<string> {
   return page.evaluate(async (docPath) => {
-    const renderer = await import('/src/services/wasmRenderer.ts');
-    const result = await renderer.renderToHtml({ documentPath: docPath });
+    await window.__quartoTestReady;
+    const hooks = window.__quartoTest;
+    if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+    const result = await hooks.wasmRenderer.renderToHtml({ documentPath: docPath });
     return result.html ?? '';
   }, documentPath);
 }
@@ -121,7 +124,10 @@ export async function getPreviewCss(page: Page): Promise<string> {
       throw new Error('No active preview iframe found');
     }
 
-    const renderer = await import('/src/services/wasmRenderer.ts');
+    await window.__quartoTestReady;
+    const hooks = window.__quartoTest;
+    if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+    const renderer = hooks.wasmRenderer;
     const links = iframe.contentDocument.querySelectorAll('link[rel="stylesheet"]');
     let combinedCss = '';
 
@@ -187,8 +193,10 @@ export async function getRenderDiagnostics(
   warnings: RenderDiagnostic[];
 }> {
   return page.evaluate(async (docPath) => {
-    const renderer = await import('/src/services/wasmRenderer.ts');
-    const result = await renderer.renderToHtml({ documentPath: docPath });
+    await window.__quartoTestReady;
+    const hooks = window.__quartoTest;
+    if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+    const result = await hooks.wasmRenderer.renderToHtml({ documentPath: docPath });
     return {
       success: result.success,
       error: result.error,

hub-client/e2e/helpers/previewExtraction.ts

@@ -19,6 +19,7 @@ import {
 import { SERVER_INFO_PATH } from './globalSetup';
 import type { ServerInfo } from './globalSetup';
 import { expect, type Page } from '@playwright/test';
+import type {} from './testHooks';
 
 export interface ProjectFile {
   path: string;
@@ -160,8 +161,10 @@ export async function seedProjectInBrowser(
 ): Promise<string> {
   return page.evaluate(
     async ({ indexDocId, syncServer, name }) => {
-      const ps = await import('/src/services/projectStorage.ts');
-      const entry = await ps.addProject(indexDocId, syncServer, name);
+      await window.__quartoTestReady;
+      const hooks = window.__quartoTest;
+      if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+      const entry = await hooks.projectStorage.addProject(indexDocId, syncServer, name);
       return entry.id;
     },
     { indexDocId, syncServer, name },

hub-client/e2e/helpers/projectFactory.ts

@@ -0,0 +1,39 @@
+/**
+ * Type declarations for the in-browser test hooks installed by
+ * `src/test-hooks.ts`. The hooks are registered on `window.__quartoTest`
+ * only when the bundle is built with `VITE_E2E=1` (see playwright.config.ts).
+ *
+ * This file is for types only — the runtime accessor lives inside the
+ * `page.evaluate(...)` callbacks because page.evaluate ships callback
+ * source to the browser, where Node-side helpers aren't reachable.
+ *
+ * Always `await window.__quartoTestReady` before reading `window.__quartoTest`
+ * — the hooks module loads asynchronously and the page's `load` event fires
+ * before module top-level awaits resolve.
+ *
+ * Usage from a test/helper:
+ *
+ * ```ts
+ * import type {} from './testHooks';  // ambient global augmentation
+ *
+ * await page.evaluate(async () => {
+ *   await window.__quartoTestReady;
+ *   const hooks = window.__quartoTest!;
+ *   return hooks.projectStorage.addProject(...);
+ * });
+ * ```
+ */
+import type * as projectStorage from '../../src/services/projectStorage';
+import type * as wasmRenderer from '../../src/services/wasmRenderer';
+
+export interface QuartoTestHooks {
+  projectStorage: typeof projectStorage;
+  wasmRenderer: typeof wasmRenderer;
+}
+
+declare global {
+  interface Window {
+    __quartoTest?: QuartoTestHooks;
+    __quartoTestReady?: Promise<unknown>;
+  }
+}

hub-client/e2e/helpers/testHooks.ts

@@ -21,6 +21,7 @@ import {
   createProjectOnServer,
   getServerUrl,
 } from './helpers/projectFactory';
+import type {} from './helpers/testHooks';
 
 /**
  * Bootstrap the receiver browser with an existing synced project set.
@@ -201,8 +202,10 @@ test.describe('Share link → synced project set', () => {
           .poll(
             () =>
               sharePage.evaluate(async (docId) => {
-                const ps = await import('/src/services/projectStorage.ts');
-                const entry = await ps.getProjectByIndexDocId(`automerge:${docId}`);
+                await window.__quartoTestReady;
+                const hooks = window.__quartoTest;
+                if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+                const entry = await hooks.projectStorage.getProjectByIndexDocId(`automerge:${docId}`);
                 return !!entry;
               }, sharedIndexDocId),
             { timeout: 15000 },
@@ -268,8 +271,10 @@ test.describe('Share link → synced project set', () => {
         // nothing about — this is exactly the state Bug A produces.
         await bootstrapPage.evaluate(
           async ({ indexDocId, server }) => {
-            const ps = await import('/src/services/projectStorage.ts');
-            await ps.addProject(`automerge:${indexDocId}`, server, 'Orphan Demo');
+            await window.__quartoTestReady;
+            const hooks = window.__quartoTest;
+            if (!hooks) throw new Error('__quartoTest missing — rebuild with VITE_E2E=1');
+            await hooks.projectStorage.addProject(`automerge:${indexDocId}`, server, 'Orphan Demo');
           },
           { indexDocId: orphanIndexDocId, server: syncServer },
         );

hub-client/e2e/share-link-project-set.spec.ts

@@ -20,8 +20,8 @@
     "test:integration:watch": "vitest --config vitest.integration.config.ts",
     "test:wasm": "vitest run --config vitest.wasm.config.ts",
     "test:wasm:watch": "vitest --config vitest.wasm.config.ts",
-    "test:e2e": "npm run build:wasm && playwright test",
-    "test:e2e:ui": "npm run build:wasm && playwright test --ui",
+    "test:e2e": "npm run build:wasm && VITE_E2E=1 npm run build && playwright test",
+    "test:e2e:ui": "npm run build:wasm && VITE_E2E=1 npm run build && playwright test --ui",
     "test:visual": "playwright test --config playwright.visual.config.ts",
     "test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots=missing",
     "test:ci": "npm run test && npm run test:integration && npm run test:wasm",
@@ -56,13 +56,15 @@
     "@playwright/test": "^1.50.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
+    "@types/compression": "^1.8.1",
     "@types/ejs": "^3.1.5",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/coverage-v8": "^4.0.17",
+    "compression": "^1.8.1",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",

hub-client/package.json

@@ -60,17 +60,32 @@ export default defineConfig({
     // },
   ],
 
-  // Run local dev server before tests
+  // Serve the prebuilt hub-client bundle via `vite preview` rather than
+  // `vite dev`. Why this matters for E2E throughput:
+  //   - A cold Playwright browser context fetches ~50 MB of assets
+  //     (the ~32 MB WASM dominates). Through `vite dev` that goes
+  //     uncompressed and serialized through the transform pipeline;
+  //     through `vite preview` (with our gzip middleware in vite.config.ts)
+  //     it's ~5.6 MB on the wire and served as static files.
+  //   - `vite dev` also re-transforms ~500 TS/JSX modules per page load;
+  //     the production bundle is ~10 chunks.
+  //   - Under 2 Playwright workers contending for one dev server on a
+  //     2-core CI runner this was the source of the "preview iframe
+  //     didn't render in 45s" flakes. Do NOT revert this to `npm run dev`
+  //     to get HMR back — HMR isn't used by tests and dev mode reintroduces
+  //     the contention.
   webServer: {
-    command: 'npm run dev',
+    command: 'npm run preview -- --port 5173',
     url: 'http://localhost:5173',
     // Reuse existing server in dev mode for faster iteration
     reuseExistingServer: !process.env.CI,
-    // Timeout for server to start
+    // Timeout for server to start (preview is near-instant; the bundle
+    // must already be built, which the CI workflow does explicitly).
     timeout: 120000,
-    // Vite proxies /auth/* and the websocket to VITE_HUB_SERVER
-    // (default http://localhost:3000). globalSetup starts the e2e hub
-    // on port 3030, so point Vite at that port.
+    // Vite preview reads VITE_HUB_SERVER at config-eval time to wire
+    // preview.proxy at the target. globalSetup starts the e2e hub on
+    // port 3030, so point preview at that port. The env is server-side
+    // only — it isn't baked into the built client bundle.
     env: {
       VITE_HUB_SERVER: 'http://localhost:3030',
     },

hub-client/playwright.config.ts

@@ -12,6 +12,17 @@ import { savePreAuthHash, restorePreAuthHash } from './utils/routing'
 // Order matters: restore first (consumes saved value), then save current.
 restorePreAuthHash() || savePreAuthHash();
 
+// E2E test hooks. Tree-shaken out unless VITE_E2E=1 was set at build time.
+// We expose the dynamic-import promise on `window.__quartoTestReady` so
+// `page.evaluate` callbacks can `await` it. Top-level await here would
+// not help: it blocks React mount but the browser's `load` event (which
+// playwright `goto` waits for) fires before module top-level awaits
+// resolve, so a naive `window.__quartoTest` access can still race.
+if (import.meta.env.VITE_E2E === '1') {
+  (window as Window & { __quartoTestReady?: Promise<unknown> }).__quartoTestReady =
+    import('./test-hooks');
+}
+
 const GOOGLE_CLIENT_ID = import.meta.env.VITE_GOOGLE_CLIENT_ID;
 
 const root = (

hub-client/src/main.tsx

@@ -0,0 +1,27 @@
+/**
+ * E2E test hooks: expose a couple of internal services on `window` so the
+ * Playwright suite can bypass UI to seed projects (`projectStorage`) and
+ * render qmd directly (`wasmRenderer`).
+ *
+ * Why this exists: the E2E suite used to reach into the source tree via
+ * `await import('/src/services/...ts')`, which only works under `vite dev`.
+ * The CI run uses `vite preview` (production bundle) for throughput; this
+ * module is the bridge so the same tests work against the prod bundle.
+ *
+ * Inclusion is gated on `import.meta.env.VITE_E2E === '1'` at build time
+ * (see `src/main.tsx`). Without that flag, vite tree-shakes this module
+ * out of the production bundle entirely.
+ */
+import * as projectStorage from './services/projectStorage';
+import * as wasmRenderer from './services/wasmRenderer';
+
+declare global {
+  interface Window {
+    __quartoTest?: {
+      projectStorage: typeof projectStorage;
+      wasmRenderer: typeof wasmRenderer;
+    };
+  }
+}
+
+window.__quartoTest = { projectStorage, wasmRenderer };