@ai-ecoverse/slicc-shared-web 1.2.1 → 1.4.0

package/README.md

@@ -11,6 +11,7 @@ Configuration shared by SLICC's web repos ([slicc-bios](https://github.com/ai-ec
 | `lefthook.yml` | Pre-commit hooks: Biome, typecheck, no comments, no unit tests in git, AGENTS.md, diff coverage | `lefthook.yml`: `extends: [node_modules/@ai-ecoverse/slicc-shared-web/lefthook.yml]` |
 | `mcr.config.mjs` | Unit-test coverage for JS and TS sources in `src/` (TS types are stripped first), written to `coverage/unit/lcov.info` | `test:unit`: `mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'` |
 | `bin/` | `slicc-lint` runs every check below plus Biome and, if the repo has one, `typecheck`. `slicc-lint-comments` runs the [slicc no-comment checker](https://github.com/ai-ecoverse/slicc/tree/main/packages/dev-tools/no-comment) at a pinned commit, allowing AGENTS.md. `slicc-agents-md`, `slicc-no-unit-tests` and `slicc-diff-cover` complete the set | `lint`: `slicc-lint`, and the hooks above |
+| `harness/` | The CDP integration-test harness, described [below](#integration-test-harness) | `import { launch } from '@ai-ecoverse/slicc-shared-web/harness'`, and `--test-global-setup=node_modules/@ai-ecoverse/slicc-shared-web/harness/global.mjs` |
 
 Install it from npm, and pin the reusable workflow to the matching `vX.Y.Z` tag. Renovate keeps both current without the usual waiting period:
 
@@ -26,3 +27,51 @@ The hooks expect two scripts in each repo: `test:unit`, which writes `coverage/u
 - Agent guidance committed to a repo lives in AGENTS.md only, at most 1,000 characters per file. The repo has no CLAUDE.md, not even as a symlink, since Claude reads AGENTS.md. The check covers tracked and untracked files; gitignored local files are personal and stay out of it.
 - Unit tests stay out of git, in a gitignored `test/unit/`. The pre-commit hook requires them to execute every staged line in `src/`.
 - Integration tests are committed and run in CI.
+
+## Integration-test harness
+
+`harness/` drives playwright-core's Chromium over raw CDP, as its only client, from `node --test`. Every page, service worker, shared worker and dedicated worker, nested ones included, starts paused, gets coverage and the CPU profiler switched on in the same tick, and only then runs. Each test gets its own browser context and leaves `artifacts/<suite>/<test>/` behind: one CPU profile per target and snapshot, a screenshot per tab and a `console.log` of every target. The global teardown merges the raw coverage into `coverage/` (console table, lcov, V8 HTML) and writes `artifacts/hotspots.md`, the 15 frames with the most self time in the repo's own scripts.
+
+`playwright-core` and `monocart-coverage-reports` are peer dependencies; pin both in the repo's `devDependencies`. A repo describes what to serve and launches the browser once per test file:
+
+```js
+import { launch } from '@ai-ecoverse/slicc-shared-web/harness';
+
+const chrome = await launch({
+  roots: [['/dist/', 'dist/'], ['/', 'test/integration/page/']],
+  isolated: true,
+  coverage: ['/dist/'],
+});
+after(() => chrome.close());
+
+test('boots', async (t) => {
+  const page = await chrome.page(t);
+  await page.goto('/');
+  await page.until(() => document.title === 'ready');
+});
+```
+
+| `launch` option | Meaning | Default |
+|---|---|---|
+| `roots` | `[urlPrefix, directory]` pairs the local server serves, first match wins | `[['/', 'src/']]` |
+| `aliases` | Extra `[urlPrefix, directory]` pairs used only to map coverage and profiles back to files, for scripts that something else serves, such as a service worker | none |
+| `isolated` | Send COOP, COEP and CORP on every response, so pages are cross-origin isolated | `false` |
+| `coverage` | URL prefixes whose `.js`/`.mjs` scripts count for coverage. `node_modules/` never does. A `.map` next to a file is used | `['/']` |
+| `exits` | `{ urlPath: [regex, ...] }`: a breakpoint on the first line matching each pattern in that worker script, where the harness takes the worker's coverage and profile before it closes itself | none |
+| `intercept` | Remote URL prefixes answered from a disk cache in `node_modules/.cache/` | none |
+| `extensions` | Unpacked extension directories to load. Their scripts are covered and profiled like the repo's own, and tests then run in the default browser context, closing their tabs when they end, because Chrome does not run extensions in the per-test contexts | none |
+| `args` | Extra Chromium flags, such as `--host-resolver-rules` or `--ignore-certificate-errors` | none |
+| `timeout` | How long `page.until` polls, in ms | `30000` |
+
+`chrome.page(t)` opens a tab and returns the page API: `goto(path)`, `reload()`, `evaluate(fn, ...args)`, `until(fn, ...args)`, `press(key, ...modifiers)` (a key name like `Enter` or `F5`, or a single character typed with its US-layout key code), `type(text)`, `insert(text)`, `enter()`, `init(fn)` (runs in every new document), `expose(name, handler)` (a binding the page calls with a JSON string), `screenshot(file)`, `tab()` (another tab in the same context), `close()`, `errors`, `responses` and `dir` (the test's artifact directory). `chrome.requests` lists the paths the server saw in this test, `chrome.overrides` is a `Map` of paths to bodies served instead of files, and `chrome.cdn` takes `status` (answer every intercepted request with it), `corrupt` (flip the last byte) and lists the intercepted `requests`. All of them reset with each test. `serve(options)` starts the same server on its own, for an `npm start`.
+
+Why it works the way it does:
+
+- Playwright detaches from shared workers, which resumes them early, so their coverage started late about half the time. Raw CDP keeps every worker paused until the profiler runs.
+- `debugger;` pauses in `beforeunload` but not in `pagehide` or `pageswap`, so a `beforeunload` hook, installed after `Page.enable`, takes the coverage of a page before it navigates. The pause only answers CDP when the page itself starts the navigation, so `goto` and `reload` go through `location`, never `Page.navigate` or `Page.reload`.
+- `takePreciseCoverage` resets the counters, so every snapshot is a delta, and all of them are kept and summed.
+- monocart's `add()` from parallel test processes loses data, so each test writes raw JSON and the teardown merges it once.
+- Coverage of a script served from `chrome.overrides` would be mapped onto the file on disk, so a path overridden during a test is left out of that test's coverage.
+- `--disable-extensions --disable-component-extensions-with-background-pages` keeps a Hangouts service worker out of every run.
+- The attach event can arrive before `Target.createTarget` returns, so new tabs wait on a slot keyed by target id.
+- A worker blocked in `Atomics.wait`, or one that is already gone, may never answer; snapshots give up after 3 s, and closing a context or the browser after 10 s. A call to a target that detaches or crashes fails instead of waiting forever, and a new tab that never attaches fails after 10 s.

package/harness/cdn.mjs

@@ -0,0 +1,63 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { type } from './server.mjs';
+import { cache, ignore } from './util.mjs';
+
+const cors = [{ name: 'access-control-allow-origin', value: '*' }];
+const store = new URL('cdn/', cache);
+
+export async function download(url) {
+  const { host, pathname, search } = new URL(url);
+  const query = search ? encodeURIComponent(search) : '';
+  const file = new URL(`./${host}${pathname}${query}`, store);
+  const hit = await readFile(file).catch(ignore);
+  if (hit) return hit;
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${response.status} ${url}`);
+  const body = Buffer.from(await response.arrayBuffer());
+  await mkdir(dirname(fileURLToPath(file)), { recursive: true });
+  const partial = new URL(`${file.href}.${process.pid}`);
+  await writeFile(partial, body);
+  await rename(partial, file);
+  return body;
+}
+
+export async function cdn(cdp, remotes) {
+  const state = { status: 0, corrupt: false, requests: [] };
+  const reset = () => {
+    state.status = 0;
+    state.corrupt = false;
+    state.requests.length = 0;
+  };
+
+  async function fulfil({ requestId, request }) {
+    state.requests.push(request.url);
+    if (state.status) {
+      const failure = { requestId, responseCode: state.status, responseHeaders: cors };
+      return cdp.send('Fetch.fulfillRequest', failure);
+    }
+    const body = await download(request.url).catch(ignore);
+    if (!body) return cdp.send('Fetch.failRequest', { requestId, errorReason: 'Failed' });
+    const sent = Buffer.from(body);
+    if (state.corrupt) sent[sent.length - 1] ^= 0xff;
+    return cdp.send('Fetch.fulfillRequest', {
+      requestId,
+      responseCode: 200,
+      responseHeaders: [
+        ...cors,
+        { name: 'content-type', value: type(new URL(request.url).pathname) },
+      ],
+      body: sent.toString('base64'),
+    });
+  }
+
+  if (remotes.length > 0) {
+    cdp.on(async ({ method, params }) => {
+      if (method === 'Fetch.requestPaused') await fulfil(params).catch(ignore);
+    });
+    const patterns = remotes.map((remote) => ({ urlPattern: `${remote}*` }));
+    await cdp.send('Fetch.enable', { patterns });
+  }
+  return { state, reset };
+}

package/harness/cdp.mjs

@@ -0,0 +1,43 @@
+export async function connect(url) {
+  const socket = new WebSocket(url);
+  await new Promise((resolve, reject) => {
+    socket.onopen = resolve;
+    socket.onerror = reject;
+  });
+  const pending = new Map();
+  const listeners = new Set();
+  let id = 0;
+  const drop = (sessionId, reason) => {
+    for (const [key, call] of pending) {
+      if (call.sessionId !== sessionId) continue;
+      pending.delete(key);
+      call.reject(new Error(`${call.method}: ${reason}`));
+    }
+  };
+  socket.onmessage = ({ data }) => {
+    const message = JSON.parse(data);
+    if (message.method === 'Target.detachedFromTarget')
+      drop(message.params.sessionId, 'target detached');
+    if (message.method === 'Inspector.targetCrashed') drop(message.sessionId, 'target crashed');
+    const call = pending.get(message.id);
+    pending.delete(message.id);
+    if (!call) for (const listener of listeners) listener(message);
+    else if (message.error) call.reject(new Error(`${call.method}: ${message.error.message}`));
+    else call.resolve(message.result);
+  };
+  socket.onclose = () => {
+    for (const call of pending.values()) call.reject(new Error(`${call.method}: socket closed`));
+  };
+  return {
+    send: (method, params = {}, sessionId) =>
+      new Promise((resolve, reject) => {
+        pending.set(++id, { method, sessionId, resolve, reject });
+        socket.send(JSON.stringify({ id, method, params, sessionId }));
+      }),
+    on: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close: () => socket.close(),
+  };
+}

package/harness/chrome.mjs

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { chromium } from 'playwright-core';
+import { cdn } from './cdn.mjs';
+import { connect } from './cdp.mjs';
+import { extensionSource, unpacked } from './extensions.mjs';
+import { page } from './page.mjs';
+import { breakpoints, recorder } from './recorder.mjs';
+import { serve } from './server.mjs';
+import { artifacts, bounded, ignore, slug, TIMED_OUT } from './util.mjs';
+
+export const flags = [
+  '--headless',
+  '--remote-debugging-port=0',
+  '--no-first-run',
+  '--no-default-browser-check',
+  '--no-sandbox',
+  '--disable-extensions',
+  '--disable-component-extensions-with-background-pages',
+  '--disable-background-timer-throttling',
+  '--disable-backgrounding-occluded-windows',
+  '--disable-renderer-backgrounding',
+  '--hide-scrollbars',
+  '--mute-audio',
+  '--window-size=1280,800',
+];
+
+export function commandLine(profile, extensions = [], extra = []) {
+  const loaded = extensions.length > 0;
+  const base = loaded ? flags.filter((flag) => flag !== '--disable-extensions') : flags;
+  const load = loaded
+    ? [`--disable-extensions-except=${extensions}`, `--load-extension=${extensions}`]
+    : [];
+  return [...base, ...load, ...extra, `--user-data-dir=${profile}`, 'about:blank'];
+}
+
+export async function start(
+  profile,
+  args = commandLine(profile),
+  executable = chromium.executablePath()
+) {
+  const child = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+  let log = '';
+  const url = await new Promise((resolve, reject) => {
+    child.stderr.on('data', (chunk) => {
+      log += chunk;
+      const match = log.match(/DevTools listening on (ws:\/\/\S+)/);
+      if (match) resolve(match[1]);
+    });
+    child.once('error', reject);
+    child.once('exit', (code) => reject(new Error(`Chromium exited with ${code}\n${log}`)));
+  });
+  return { child, url };
+}
+
+export async function stop(cdp, child) {
+  const exited = new Promise((resolve) => child.once('exit', resolve));
+  await bounded(cdp.send('Browser.close').catch(ignore), 'Browser.close');
+  cdp.close();
+  if (child.exitCode === null && (await bounded(exited, 'exit')) === TIMED_OUT) {
+    child.kill('SIGKILL');
+    await exited;
+  }
+}
+
+export async function launch({
+  roots,
+  aliases,
+  isolated,
+  coverage,
+  exits = {},
+  intercept = [],
+  extensions = [],
+  args = [],
+  timeout,
+} = {}) {
+  const server = await serve({ roots, aliases, isolated });
+  const found = await unpacked(extensions);
+  const fromExtension = extensionSource(found);
+  const files = { ...server, source: (href) => server.source(href) ?? fromExtension(href) };
+  const shared = extensions.length > 0;
+  const profile = await mkdtemp(join(tmpdir(), 'slicc-harness-'));
+  const loaded = [...found.values()].map((root) => root.slice(0, -1));
+  const { child, url } = await start(profile, commandLine(profile, loaded, args));
+  const cdp = await connect(url);
+  const record = recorder(cdp, files, { coverage, exits: await breakpoints(server, exits) });
+  const remote = await cdn(cdp, intercept);
+  await cdp.send('Target.setAutoAttach', {
+    autoAttach: true,
+    waitForDebuggerOnStart: true,
+    flatten: true,
+  });
+
+  async function tabs() {
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    return targetInfos.filter(({ type }) => type === 'page').map(({ targetId }) => targetId);
+  }
+
+  async function sweep(before) {
+    const added = (await tabs()).filter((targetId) => !before.has(targetId));
+    const closing = added.map((targetId) => cdp.send('Target.closeTarget', { targetId }));
+    await Promise.all(closing.map((sent) => sent.catch(ignore)));
+  }
+
+  async function finish(pages, browserContextId, dir, before) {
+    const shots = pages.map((opened, i) =>
+      opened.screenshot(new URL(`tab-${i + 1}.png`, dir)).catch(ignore)
+    );
+    await Promise.all(shots);
+    await record.end();
+    for (const opened of pages) opened.dispose();
+    remote.reset();
+    const closing = shared
+      ? sweep(before)
+      : cdp.send('Target.disposeBrowserContext', { browserContextId });
+    await bounded(closing, 'dispose');
+  }
+
+  return {
+    url: server.url,
+    cdn: remote.state,
+    requests: server.requests,
+    overrides: server.overrides,
+    async page(t) {
+      const suite = slug(basename(t.filePath ?? 'test', '.test.mjs'));
+      const dir = new URL(`${suite}/${slug(t.name)}/`, artifacts);
+      await mkdir(dir, { recursive: true });
+      const { browserContextId } = shared ? {} : await cdp.send('Target.createBrowserContext');
+      const before = new Set(shared ? await tabs() : []);
+      record.begin(browserContextId, dir, `${suite}-${slug(t.name)}`);
+      server.requests.length = 0;
+      server.overrides.clear();
+      server.overridden.clear();
+      const pages = [];
+      t.after(() => finish(pages, browserContextId, dir, before));
+      const tab = async () => {
+        const opened = page(cdp, await record.open(browserContextId), server, timeout);
+        pages.push(opened);
+        return Object.assign(opened, { tab, dir });
+      };
+      return tab();
+    },
+    async close() {
+      await stop(cdp, child);
+      await rm(profile, { recursive: true, force: true });
+      await server.close();
+    },
+  };
+}

package/harness/extensions.mjs

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { join, normalize, sep } from 'node:path';
+
+export function extensionId(input) {
+  const hex = createHash('sha256').update(input).digest('hex').slice(0, 32);
+  return [...hex].map((digit) => String.fromCharCode(97 + Number.parseInt(digit, 16))).join('');
+}
+
+export async function unpacked(dirs) {
+  const found = new Map();
+  for (const dir of dirs) {
+    const root = await realpath(dir);
+    const manifest = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'));
+    const id = extensionId(manifest.key ? Buffer.from(manifest.key, 'base64') : root);
+    found.set(id, `${root}${sep}`);
+  }
+  return found;
+}
+
+export function extensionSource(found) {
+  return (href) => {
+    if (!href.startsWith('chrome-extension://')) return null;
+    const { host, pathname } = new URL(href);
+    const root = found.get(host);
+    return root ? join(root, normalize(decodeURIComponent(pathname))) : null;
+  };
+}

package/harness/global.mjs

@@ -0,0 +1,72 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { cwd } from 'node:process';
+import { CoverageReport } from 'monocart-coverage-reports';
+import { artifacts, raw, samples } from './util.mjs';
+
+async function name() {
+  const manifest = await readFile('package.json', 'utf8').catch(() => '{}');
+  return JSON.parse(manifest).name ?? basename(cwd());
+}
+
+async function load(dir) {
+  const files = await readdir(dir).catch(() => []);
+  const parsed = files
+    .sort()
+    .map(async (file) => JSON.parse(await readFile(new URL(file, dir), 'utf8')));
+  return Promise.all(parsed);
+}
+
+export async function report() {
+  const merged = new CoverageReport({
+    name: await name(),
+    outputDir: 'coverage',
+    reports: ['console-details', 'lcovonly', 'v8'],
+    logging: 'error',
+    all: { dir: 'src', filter: '**/*.js' },
+    sourceFilter: (path) => path.startsWith('src/'),
+  });
+  for (const entries of await load(raw)) {
+    if (entries.length > 0) await merged.add(entries);
+  }
+  await merged.generate();
+}
+
+export function table(runs) {
+  const self = new Map();
+  let profiles = 0;
+  for (const run of runs) {
+    profiles += run.profiles;
+    for (const [frame, micros] of Object.entries(run.self)) {
+      self.set(frame, (self.get(frame) ?? 0) + micros);
+    }
+  }
+  const top = [...self].sort((a, b) => b[1] - a[1]).slice(0, 15);
+  const rows = top.map(([frame, micros]) => `| ${(micros / 1000).toFixed(2)} ms | \`${frame}\` |`);
+  return [
+    `### Hotspots: self time in our scripts across ${profiles} CPU profiles`,
+    '',
+    '| self | frame |',
+    '| ---: | :--- |',
+    ...rows,
+    '',
+  ].join('\n');
+}
+
+export async function hotspots() {
+  const markdown = table(await load(samples));
+  await mkdir(artifacts, { recursive: true });
+  await writeFile(new URL('hotspots.md', artifacts), markdown);
+  console.log(markdown);
+}
+
+export async function globalSetup() {
+  await rm(artifacts, { recursive: true, force: true });
+  await rm(raw, { recursive: true, force: true });
+  await rm(samples, { recursive: true, force: true });
+}
+
+export async function globalTeardown() {
+  await report();
+  await hotspots();
+}

package/harness/index.mjs

@@ -0,0 +1,4 @@
+export { connect } from './cdp.mjs';
+export { launch } from './chrome.mjs';
+export { isolation, serve } from './server.mjs';
+export { slug } from './util.mjs';

package/harness/page.mjs

@@ -0,0 +1,154 @@
+import { writeFile } from 'node:fs/promises';
+import { sleep } from './util.mjs';
+
+const masks = { alt: 1, ctrl: 2, meta: 4, shift: 8 };
+const keys = new Map([
+  ['Enter', { code: 'Enter', keyCode: 13, text: '\r' }],
+  ['Tab', { code: 'Tab', keyCode: 9, text: '\t' }],
+  ['Backspace', { code: 'Backspace', keyCode: 8 }],
+  ['Escape', { code: 'Escape', keyCode: 27 }],
+  ['Delete', { code: 'Delete', keyCode: 46 }],
+  ['Insert', { code: 'Insert', keyCode: 45 }],
+  ['Home', { code: 'Home', keyCode: 36 }],
+  ['End', { code: 'End', keyCode: 35 }],
+  ['PageUp', { code: 'PageUp', keyCode: 33 }],
+  ['PageDown', { code: 'PageDown', keyCode: 34 }],
+  ['ArrowUp', { code: 'ArrowUp', keyCode: 38 }],
+  ['ArrowDown', { code: 'ArrowDown', keyCode: 40 }],
+  ['ArrowLeft', { code: 'ArrowLeft', keyCode: 37 }],
+  ['ArrowRight', { code: 'ArrowRight', keyCode: 39 }],
+]);
+const punctuation = new Map([
+  [' ', ['Space', 32]],
+  [';', ['Semicolon', 186]],
+  ['=', ['Equal', 187]],
+  [',', ['Comma', 188]],
+  ['-', ['Minus', 189]],
+  ['.', ['Period', 190]],
+  ['/', ['Slash', 191]],
+  ['`', ['Backquote', 192]],
+  ['[', ['BracketLeft', 219]],
+  ['\\', ['Backslash', 220]],
+  [']', ['BracketRight', 221]],
+  ["'", ['Quote', 222]],
+]);
+const shifted = new Map(
+  [...'~!@#$%^&*()_+{}|:"<>?'].map((char, i) => [char, "`1234567890-=[]\\;',./"[i]])
+);
+
+function named(key) {
+  const known = keys.get(key);
+  if (known) return known;
+  const fn = /^F(\d{1,2})$/.exec(key);
+  return { code: key, keyCode: fn ? 111 + Number(fn[1]) : 0 };
+}
+
+export function character(char) {
+  const base = shifted.get(char) ?? char.toLowerCase();
+  const upper = base.toUpperCase();
+  if (/^[a-z]$/.test(base))
+    return { code: `Key${upper}`, keyCode: upper.charCodeAt(0), text: char };
+  if (/^\d$/.test(base)) return { code: `Digit${base}`, keyCode: base.charCodeAt(0), text: char };
+  const [code, keyCode] = punctuation.get(base) ?? ['', 0];
+  return { code, keyCode, text: char };
+}
+
+export function keystroke(key, modifiers) {
+  const bits = modifiers.reduce((sum, name) => sum | masks[name], 0);
+  const { code, keyCode, text } = [...key].length === 1 ? character(key) : named(key);
+  const typed = bits & ~masks.shift ? undefined : text;
+  return { key, code, windowsVirtualKeyCode: keyCode, modifiers: bits, text: typed };
+}
+
+export function settle(ms = 1000) {
+  const finite = document
+    .getAnimations()
+    .filter((animation) => animation.effect?.getComputedTiming().endTime < Infinity);
+  const done = Promise.all(finite.map((animation) => animation.finished.catch(() => null)));
+  return Promise.race([done, new Promise((resolve) => setTimeout(resolve, ms))]);
+}
+
+export function mark() {
+  window.stale = true;
+}
+
+export function fresh() {
+  return !window.stale;
+}
+
+export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
+  const send = (method, params) => cdp.send(method, params, sessionId);
+  const errors = [];
+  const responses = [];
+  const bindings = new Map();
+  const dispose = cdp.on(({ method, params, sessionId: from }) => {
+    if (from !== sessionId) return;
+    if (method === 'Runtime.exceptionThrown') {
+      const { exception, text } = params.exceptionDetails;
+      errors.push(exception?.description ?? text);
+    }
+    if (method === 'Runtime.bindingCalled') bindings.get(params.name)?.(JSON.parse(params.payload));
+    if (method === 'Network.responseReceived') responses.push(params.response);
+  });
+
+  async function evaluate(fn, ...args) {
+    const expression = `(${fn})(...${JSON.stringify(args)})`;
+    const { result, exceptionDetails } = await send('Runtime.evaluate', {
+      expression,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (exceptionDetails) throw new Error(exceptionDetails.exception?.description);
+    return result.value;
+  }
+
+  async function until(fn, ...args) {
+    const deadline = Date.now() + timeout;
+    let last;
+    while (Date.now() < deadline) {
+      last = await evaluate(fn, ...args).catch((error) => error.message);
+      if (last === true) return;
+      await sleep(25);
+    }
+    throw new Error(`Timed out waiting for ${fn}\nlast result: ${JSON.stringify(last)}`);
+  }
+
+  async function press(key, ...modifiers) {
+    const event = keystroke(key, modifiers);
+    await send('Input.dispatchKeyEvent', { ...event, type: event.text ? 'keyDown' : 'rawKeyDown' });
+    await send('Input.dispatchKeyEvent', { ...event, type: 'keyUp', text: undefined });
+  }
+
+  async function navigate(expression) {
+    await evaluate(mark);
+    await send('Runtime.evaluate', { expression });
+    await until(fresh);
+  }
+
+  return {
+    errors,
+    responses,
+    dispose,
+    evaluate,
+    until,
+    press,
+    goto: (path) => navigate(`location.assign(${JSON.stringify(new URL(path, server.url).href)})`),
+    reload: () => navigate('location.reload()'),
+    insert: (text) => send('Input.insertText', { text }),
+    close: () => cdp.send('Target.closeTarget', { targetId }),
+    enter: () => press('Enter'),
+    async type(text) {
+      for (const key of text) await press(key);
+    },
+    init: (fn) => send('Page.addScriptToEvaluateOnNewDocument', { source: `(${fn})()` }),
+    async expose(name, handler) {
+      bindings.set(name, handler);
+      await send('Runtime.addBinding', { name });
+    },
+    async screenshot(file) {
+      await evaluate(settle);
+      const { data } = await send('Page.captureScreenshot', { format: 'png' });
+      await writeFile(file, Buffer.from(data, 'base64'));
+    },
+  };
+}

package/harness/recorder.mjs

@@ -0,0 +1,210 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, relative } from 'node:path';
+import { cwd } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { bounded, ignore, raw, samples, sleep, TIMED_OUT } from './util.mjs';
+
+const profiled = new Set(['page', 'worker', 'service_worker', 'shared_worker']);
+const nested = { autoAttach: true, waitForDebuggerOnStart: true, flatten: true };
+const unload = "addEventListener('beforeunload', () => { debugger; })";
+
+function pathOf(url) {
+  return URL.canParse(url) ? new URL(url).pathname : '';
+}
+
+export function label(target) {
+  return target.type === 'page' ? 'page' : basename(pathOf(target.url), '.js') || target.type;
+}
+
+export async function breakpoints(server, exits) {
+  const found = new Map();
+  for (const [path, patterns] of Object.entries(exits)) {
+    const file = server.locate(path);
+    const text = file ? await readFile(file, 'utf8').catch(() => '') : '';
+    const lines = text.split('\n');
+    const numbers = patterns
+      .map((pattern) => lines.findIndex((line) => pattern.test(line)))
+      .filter((n) => n >= 0);
+    found.set(path, numbers);
+  }
+  return found;
+}
+
+export function covered(server, prefixes) {
+  return ({ url }) => {
+    if (!server.source(url)) return false;
+    const { pathname, protocol } = new URL(url);
+    const ours = protocol === 'chrome-extension:' || prefixes.some((p) => pathname.startsWith(p));
+    return ours && /\.m?js$/.test(pathname) && !pathname.includes('/node_modules/');
+  };
+}
+
+export function selfTimes(profile, server, into) {
+  const frames = new Map(profile.nodes.map((node) => [node.id, node.callFrame]));
+  profile.samples.forEach((id, i) => {
+    const { url, functionName, lineNumber, columnNumber } = frames.get(id);
+    const file = url.includes('/node_modules/') ? null : server.source(url);
+    if (!file) return;
+    const top = lineNumber === 0 && columnNumber === 0 ? '(top level)' : '(anonymous)';
+    const key = `${relative(cwd(), file)}:${lineNumber + 1} ${functionName || top}`;
+    into[key] = (into[key] ?? 0) + (profile.timeDeltas[i + 1] ?? 0);
+  });
+  return into;
+}
+
+async function entry(server, script) {
+  const file = server.source(script.url);
+  const source = await readFile(file, 'utf8').catch(ignore);
+  if (source === null || server.overridden.has(new URL(script.url).pathname)) return null;
+  const map = await readFile(`${file}.map`, 'utf8').catch(ignore);
+  return {
+    ...script,
+    url: pathToFileURL(file).href,
+    source,
+    ...(map ? { sourceMap: JSON.parse(map) } : {}),
+  };
+}
+
+export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } = {}) {
+  const sessions = new Map();
+  const tabs = new Map();
+  const ours = covered(server, coverage);
+  let run = null;
+
+  async function dump(sessionId, target, restart) {
+    const current = run;
+    const send = (method) => cdp.send(method, {}, sessionId);
+    const taken = Promise.all([send('Profiler.takePreciseCoverage'), send('Profiler.stop')]);
+    const [{ result }, { profile }] = await Promise.race([taken, sleep(3000)]).then(
+      (answer) => answer ?? [{}, {}],
+      () => [{}, {}]
+    );
+    if (!(result && current)) return;
+    if (restart) send('Profiler.start').catch(ignore);
+    current.scripts.push(...result.filter(ours));
+    current.profiles += 1;
+    selfTimes(profile, server, current.self);
+    const name = `${String(current.profiles).padStart(3, '0')}-${label(target)}.cpuprofile`;
+    await writeFile(new URL(name, current.dir), JSON.stringify(profile));
+  }
+
+  async function checkpoint() {
+    const current = [...sessions].filter(([, target]) => target.browserContextId === run?.context);
+    await Promise.all(current.map(([sessionId, target]) => dump(sessionId, target, true)));
+  }
+
+  function tab(targetId) {
+    if (!tabs.has(targetId)) {
+      const slot = {};
+      slot.session = new Promise((resolve) => {
+        slot.resolve = resolve;
+      });
+      tabs.set(targetId, slot);
+    }
+    return tabs.get(targetId);
+  }
+
+  function commands({ type, url }) {
+    const list = [];
+    if (profiled.has(type)) {
+      list.push(
+        ['Runtime.enable'],
+        ['Profiler.enable'],
+        ['Profiler.setSamplingInterval', { interval: 100 }],
+        ['Profiler.startPreciseCoverage', { callCount: true, detailed: true }],
+        ['Profiler.start'],
+        ['Target.setAutoAttach', nested]
+      );
+    }
+    const lines = type === 'worker' ? exits.get(pathOf(url)) : undefined;
+    if (lines) {
+      list.push(
+        ['Debugger.enable'],
+        ...lines.map((lineNumber) => ['Debugger.setBreakpointByUrl', { url, lineNumber }])
+      );
+    }
+    if (type === 'page') {
+      list.push(
+        ['Network.enable'],
+        ['Debugger.enable'],
+        ['Page.enable'],
+        ['Page.addScriptToEvaluateOnNewDocument', { source: unload }]
+      );
+    }
+    return list;
+  }
+
+  function attach({ sessionId, targetInfo, waitingForDebugger }) {
+    if (profiled.has(targetInfo.type)) sessions.set(sessionId, targetInfo);
+    const list = commands(targetInfo);
+    if (waitingForDebugger) list.push(['Runtime.runIfWaitingForDebugger']);
+    const ready = Promise.all(
+      list.map(([method, params]) => cdp.send(method, params, sessionId).catch(ignore))
+    );
+    if (targetInfo.type === 'page') tab(targetInfo.targetId).resolve(ready.then(() => sessionId));
+    return ready;
+  }
+
+  function log(sessionId, line) {
+    const target = sessions.get(sessionId);
+    if (!run || target?.browserContextId !== run.context) return;
+    run.console.push(`${label(target)}: ${line}`);
+  }
+
+  async function paused(sessionId) {
+    const target = sessions.get(sessionId);
+    if (target?.type === 'worker') await dump(sessionId, target, false);
+    else await checkpoint();
+    await cdp.send('Debugger.resume', {}, sessionId).catch(ignore);
+  }
+
+  cdp.on(async ({ method, params, sessionId }) => {
+    if (method === 'Target.attachedToTarget') await attach(params);
+    if (method === 'Target.detachedFromTarget') sessions.delete(params.sessionId);
+    if (method === 'Runtime.consoleAPICalled') {
+      const text = params.args.map((arg) => arg.value ?? arg.description).join(' ');
+      log(sessionId, `${params.type} ${text}`);
+    }
+    if (method === 'Runtime.exceptionThrown') {
+      const { exception, text } = params.exceptionDetails;
+      log(sessionId, `uncaught ${exception?.description ?? text}`);
+    }
+    if (method === 'Debugger.paused') await paused(sessionId);
+  });
+
+  async function open(browserContextId) {
+    const { targetId } = await cdp.send('Target.createTarget', {
+      url: 'about:blank',
+      browserContextId,
+    });
+    const sessionId = await bounded(tab(targetId).session, 'attach');
+    tabs.delete(targetId);
+    if (sessionId === TIMED_OUT) throw new Error(`Target.createTarget: ${targetId} never attached`);
+    if (run && !run.context) run.context = sessions.get(sessionId)?.browserContextId;
+    return { sessionId, targetId };
+  }
+
+  function begin(context, dir, name) {
+    run = { context, dir, name, scripts: [], console: [], profiles: 0, self: {} };
+  }
+
+  async function end() {
+    await checkpoint();
+    const current = run;
+    run = null;
+    const entries = await Promise.all(current.scripts.map((script) => entry(server, script)));
+    const found = { profiles: current.profiles, self: current.self };
+    await mkdir(raw, { recursive: true });
+    await mkdir(samples, { recursive: true });
+    await Promise.all([
+      writeFile(new URL(`${current.name}.json`, raw), JSON.stringify(entries.filter(Boolean))),
+      writeFile(new URL(`${current.name}.json`, samples), JSON.stringify(found)),
+      writeFile(
+        new URL('console.log', current.dir),
+        current.console.map((line) => `${line}\n`).join('')
+      ),
+    ]);
+  }
+
+  return { open, begin, end };
+}

package/harness/server.mjs

@@ -0,0 +1,83 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+
+export const isolation = {
+  'cross-origin-opener-policy': 'same-origin',
+  'cross-origin-embedder-policy': 'require-corp',
+  'cross-origin-resource-policy': 'same-origin',
+};
+
+const types = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.wasm': 'application/wasm',
+};
+
+export function type(path) {
+  return types[extname(path)] ?? 'application/octet-stream';
+}
+
+export function locator(roots) {
+  const mounted = roots.map(([prefix, dir]) => [prefix, `${resolve(dir)}${sep}`]);
+  return (pathname) => {
+    const found = mounted.find(([prefix]) => pathname.startsWith(prefix));
+    if (!found) return null;
+    const [prefix, root] = found;
+    const rel = pathname.slice(prefix.length);
+    const file = join(root, normalize(rel === '' || rel.endsWith('/') ? `${rel}index.html` : rel));
+    return file.startsWith(root) ? file : null;
+  };
+}
+
+export async function serve({
+  roots = [['/', 'src/']],
+  aliases = [],
+  isolated = false,
+  port = 0,
+} = {}) {
+  const headers = isolated ? isolation : {};
+  const locate = locator(roots);
+  const lookup = locator([...aliases, ...roots]);
+  const requests = [];
+  const overrides = new Map();
+  const overridden = new Set();
+  const server = createServer(async (request, response) => {
+    const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname);
+    requests.push(pathname);
+    if (overrides.has(pathname)) {
+      overridden.add(pathname);
+      return response
+        .writeHead(200, { ...headers, 'content-type': type(pathname), 'cache-control': 'no-cache' })
+        .end(overrides.get(pathname));
+    }
+    const file = locate(pathname);
+    const found = file && (await stat(file).catch(() => null))?.isFile();
+    if (!found) return response.writeHead(404, headers).end();
+    response.writeHead(200, {
+      ...headers,
+      'content-type': type(file),
+      'cache-control': 'no-cache',
+    });
+    createReadStream(file).pipe(response);
+  });
+  await new Promise((done) => server.listen(port, '127.0.0.1', done));
+  const url = `http://127.0.0.1:${server.address().port}/`;
+  return {
+    url,
+    requests,
+    overrides,
+    overridden,
+    locate,
+    source: (href) =>
+      href.startsWith(url) ? lookup(decodeURIComponent(new URL(href).pathname)) : null,
+    close: () => new Promise((done) => server.close(done)),
+  };
+}

package/harness/util.mjs

@@ -0,0 +1,32 @@
+import { cwd } from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+export const TIMED_OUT = Symbol('timed out');
+
+const project = pathToFileURL(`${cwd()}/`);
+
+export const artifacts = new URL('artifacts/', project);
+export const cache = new URL('node_modules/.cache/slicc-harness/', project);
+export const raw = new URL('coverage/', cache);
+export const samples = new URL('hotspots/', cache);
+
+export function ignore() {
+  return null;
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function bounded(promise, label, ms = 10000) {
+  const result = await Promise.race([promise, sleep(ms).then(() => TIMED_OUT)]);
+  if (result === TIMED_OUT) console.warn(`chrome: ${label} took over ${ms} ms, moving on`);
+  return result;
+}
+
+export function slug(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-ecoverse/slicc-shared-web",
-  "version": "1.2.1",
-  "description": "Shared Renovate, Biome, TypeScript, lefthook and GitHub Actions configuration for SLICC's web repos",
+  "version": "1.4.0",
+  "description": "Shared Renovate, Biome, TypeScript, lefthook and GitHub Actions configuration, plus the CDP integration-test harness, for SLICC's web repos",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,9 @@
     "./tsconfig.json": "./tsconfig.json",
     "./lefthook.yml": "./lefthook.yml",
     "./package.json": "./package.json",
-    "./mcr.config.mjs": "./mcr.config.mjs"
+    "./mcr.config.mjs": "./mcr.config.mjs",
+    "./harness": "./harness/index.mjs",
+    "./harness/global": "./harness/global.mjs"
   },
   "bin": {
     "slicc-agents-md": "bin/slicc-agents-md.sh",
@@ -38,6 +40,7 @@
   "files": [
     "bin",
     "biome.json",
+    "harness",
     "default.json",
     "lefthook.yml",
     "mcr.config.mjs",
@@ -45,12 +48,21 @@
   ],
   "scripts": {
     "lint": "bin/slicc-lint.sh && shellcheck bin/*.sh",
+    "pretest": "playwright-core install --no-shell chromium",
+    "test": "node --test --test-global-setup=harness/global.mjs test/integration/*.test.mjs && node test/integration/verify.mjs",
+    "test:unit": "mcr -c test/unit/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'",
     "trust": "npx fledgling sync -y --skip-publish",
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
+    "monocart-coverage-reports": "2.13.0",
+    "playwright-core": "1.63.0",
     "semantic-release": "25.0.9"
+  },
+  "peerDependencies": {
+    "monocart-coverage-reports": ">=2.13.0",
+    "playwright-core": ">=1.50.0"
   }
 }