feat(core): frame.origin = 'call' marker (async origin capture, step 1)

.github/workflows/ci.yml

@@ -155,10 +155,12 @@ jobs:
 
       # Playwright ships a downloader, not the browsers: `pnpm install` does not fetch them, so
       # `browser.e2e.ts` fails with "Executable doesn't exist at .../chrome-headless-shell".
-      # Scoped to chromium — it is the only engine the browser harness drives.
+      # Chromium drives the browser harness; Firefox and WebKit join it for the async-origin e2e (the engines differ in WHEN the media error
+      # event fires, in the stack format, and WebKit eliminates tail calls, which is exactly what that feature depends on). WebKit needs
+      # its system libraries, hence --with-deps.
       # On a fresh hosted VM this always downloads; it is a few seconds, not a failure.
-      - name: Install Playwright's Chromium
-        run: pnpm --filter @bugsee/instrumentation-tests exec playwright install chromium
+      - name: Install Playwright's browsers (Chromium, Firefox, WebKit)
+        run: pnpm --filter @bugsee/instrumentation-tests exec playwright install --with-deps chromium firefox webkit
 
       # The nuxt/sveltekit/astro harnesses each boot a real dev server on a FIXED port. A fresh hosted VM
       # starts clean, so this only guards a hung harness within one run (and a developer's machine, where

biome.json

@@ -12,7 +12,7 @@
       "!samples",
       "!.local-registry",
       "!packages/protocol/spec",
-      "!docs/design/async-origin-capture"
+      "!docs/design/async-origin-capture/**"
     ]
   },
   "formatter": {

docs/design/async-origin-capture/bench.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import http from 'node:http';
-const require = createRequire('/Volumes/External2TB/Projects/Bugsee/javascript/packages/instrumentation-tests/package.json');
+const require = createRequire(new URL('../../../packages/instrumentation-tests/package.json', import.meta.url));
 const pw = require('playwright');
 const srv = http.createServer((q,s)=>{s.setHeader('content-type','text/html');s.end('<!doctype html><body></body>');});
 await new Promise(r=>srv.listen(0,'127.0.0.1',r));

docs/design/async-origin-capture/probe.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import http from 'node:http';
-const require = createRequire('/Volumes/External2TB/Projects/Bugsee/javascript/packages/instrumentation-tests/package.json');
+const require = createRequire(new URL('../../../packages/instrumentation-tests/package.json', import.meta.url));
 const pw = require('playwright');
 const srv = http.createServer((q,s)=>{ if(q.url==='/'){s.setHeader('content-type','text/html');s.end('<!doctype html><body></body>');} else if(q.url==='/bad.js'){s.setHeader('content-type','text/javascript');s.end('syntax error here(');} else if(q.url==='/bad.json'){s.setHeader('content-type','application/json');s.end('{oops');} else {s.statusCode=404;s.end('nf');}});
 await new Promise(r=>srv.listen(0,'127.0.0.1',r));
@@ -68,7 +68,7 @@ const PAGE = () => {
     }
     await sleep(5000);
     const seen = new Set(out.map((o) => o.id));
-    for (const id of started) if (!seen.has(id)) out.push({ id, noUnhandledRejection: true });
+    for (const id of started) if (!seen.has(id)) out.push({ id, noEventWithin5s: true });
     resolve(out);
   });
 };

package.json

@@ -29,6 +29,7 @@
     "test:mutation": "node scripts/mutation.mjs",
     "ci:local": "bash scripts/ci-local.sh",
     "spec:refresh": "node scripts/spec-snapshot/refresh.mjs",
+    "async-origin:refresh": "node scripts/async-origin/refresh.mjs",
     "spec:check": "node scripts/spec-snapshot/refresh.mjs --check"
   },
   "devDependencies": {

packages/astro/README.md

@@ -53,6 +53,10 @@ bugsee({
 });
 ```
 
+## Island hydration errors
+
+Astro catches an island's hydration failure itself and re-dispatches it as a cancelable `astro:hydration-error` event (plus a `console.error`); nothing is rethrown, so the page's error handlers never see it. The browser launch listens for that event and reports the error, without cancelling the event, so Astro's own console output is unchanged. For component errors during rendering, also add the matching island adapter (`@bugsee/react`, `@bugsee/vue`, ...).
+
 ## Links
 
 - Repository: https://github.com/bugsee/bugsee-javascript/tree/main/packages/astro

packages/astro/package.json

@@ -103,10 +103,11 @@
   },
   "dependencies": {
     "@bugsee/adapter-kit": "workspace:*",
+    "@bugsee/bugsee": "workspace:*",
     "@bugsee/core": "workspace:*",
     "@bugsee/protocol": "workspace:*",
     "@bugsee/vercel-edge": "workspace:*",
-    "@bugsee/bugsee": "workspace:*"
+    "@bugsee/web-adapter": "workspace:*"
   },
   "devDependencies": {
     "@bugsee/node": "workspace:*",

packages/astro/src/client.test.ts

@@ -1,12 +1,35 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const { launch } = vi.hoisted(() => ({ launch: vi.fn() }));
-vi.mock('@bugsee/bugsee', () => ({ launch }));
+const { launch, relaunchUmbrella, listen, flush, order } = vi.hoisted(() => ({
+  launch: vi.fn(),
+  relaunchUmbrella: vi.fn(),
+  listen: vi.fn(),
+  flush: vi.fn(),
+  order: [] as string[],
+}));
+vi.mock('@bugsee/bugsee', () => ({ launch, relaunch: relaunchUmbrella }));
+vi.mock('./hydration', () => ({
+  listenForAstroHydrationErrors: listen,
+  flushQueuedAstroHydrationErrors: flush,
+}));
 
-import { registerClient } from './client';
+// The client module remembers the last registration's hydration options (like core's relaunch keeps them), so each test gets a fresh one.
+let registerClient: typeof import('./client').registerClient;
+let relaunch: typeof import('./client').relaunch;
 
 describe('registerClient', () => {
-  afterEach(() => launch.mockReset());
+  beforeEach(async () => {
+    vi.resetModules();
+    ({ registerClient, relaunch } = await import('./client'));
+  });
+
+  afterEach(() => {
+    launch.mockReset();
+    relaunchUmbrella.mockReset();
+    listen.mockReset();
+    flush.mockReset();
+    order.length = 0;
+  });
 
   it('launches the browser SDK with the appToken + options, returns the client', async () => {
     const client = { id: 'browser' };
@@ -19,4 +42,98 @@ describe('registerClient', () => {
     await registerClient('tok');
     expect(launch).toHaveBeenCalledWith('tok', {});
   });
+
+  it('listens BEFORE the launch (an island error during launch is queued) and flushes the queue once the client exists', async () => {
+    listen.mockImplementation(() => order.push('listen'));
+    launch.mockImplementation(async () => {
+      order.push('launch');
+      return {};
+    });
+    flush.mockImplementation(() => order.push('flush'));
+    await registerClient('tok');
+    expect(order).toEqual(['listen', 'launch', 'flush']);
+  });
+
+  it('relaunch() is wrapped in the same window: listen first, flush in a finally (the carrier client is cleared during the restart)', async () => {
+    listen.mockImplementation(() => order.push('listen'));
+    relaunchUmbrella.mockImplementation(async () => {
+      order.push('relaunch');
+      return {};
+    });
+    flush.mockImplementation(() => order.push('flush'));
+    await relaunch({ replay: false });
+    expect(order).toEqual(['listen', 'relaunch', 'flush']);
+    expect(relaunchUmbrella).toHaveBeenCalledWith({ replay: false });
+    relaunchUmbrella.mockRejectedValue(new Error('relaunch failed'));
+    order.length = 0;
+    await expect(relaunch()).rejects.toThrow('relaunch failed');
+    expect(order).toEqual(['listen', 'flush']);
+  });
+
+  it("hands the page document the launch uses (an explicit one, else the bound window's) to the hydration listener as its target", async () => {
+    launch.mockResolvedValue({});
+    const doc = {} as Document;
+    await registerClient('tok', { document: doc } as never);
+    expect(listen).toHaveBeenLastCalledWith({ target: doc });
+    const windowDoc = {} as Document;
+    await registerClient('tok', { window: { document: windowDoc } } as never);
+    expect(listen).toHaveBeenLastCalledWith({ target: windowDoc });
+    const hostile = {
+      get document(): never {
+        throw new Error('sandboxed');
+      },
+    };
+    await registerClient('tok', { window: hostile } as never);
+    // nothing selectable this time: the earlier registration's document is KEPT (core's relaunch keeps `document` and `window` too)
+    expect(listen).toHaveBeenLastCalledWith({ target: windowDoc });
+  });
+
+  it('a plain relaunch() keeps the earlier document, carrier and onError (core keeps them), and an explicit one wins', async () => {
+    const doc = {} as Document;
+    const carrier = {};
+    const onError = vi.fn();
+    launch.mockResolvedValue({});
+    relaunchUmbrella.mockResolvedValue({});
+    await registerClient('tok', { document: doc, carrier, onError } as never);
+    await relaunch();
+    expect(listen).toHaveBeenLastCalledWith({ target: doc, carrier, onError });
+    expect(flush).toHaveBeenLastCalledWith({ target: doc, carrier, onError });
+    const other = {} as Document;
+    await relaunch({ document: other } as never);
+    expect(listen).toHaveBeenLastCalledWith({ target: other, carrier, onError });
+  });
+
+  it("a plain relaunch() after a bound WINDOW listens and flushes on that window's document (the same EventTarget as registerClient)", async () => {
+    const windowDoc = {} as Document;
+    launch.mockResolvedValue({});
+    relaunchUmbrella.mockResolvedValue({});
+    await registerClient('tok', { window: { document: windowDoc } } as never);
+    await relaunch({ replay: false });
+    expect(listen).toHaveBeenLastCalledWith({ target: windowDoc });
+    expect(flush).toHaveBeenLastCalledWith({ target: windowDoc });
+  });
+
+  it('hands a custom carrier to the hydration listener, so it looks where the client lives', async () => {
+    const carrier = {};
+    launch.mockResolvedValue({});
+    await registerClient('tok', { carrier } as never);
+    expect(listen).toHaveBeenCalledWith({ carrier });
+    expect(flush).toHaveBeenCalledWith({ carrier });
+  });
+
+  it('ends the queueing window even when the launch fails, and still rejects with the launch error', async () => {
+    const failure = new Error('launch failed');
+    launch.mockRejectedValue(failure);
+    await expect(registerClient('tok')).rejects.toBe(failure);
+    expect(flush).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the onError sink to the hydration listener, and keeps it for a later call that gives none (core keeps onError)', async () => {
+    const onError = vi.fn();
+    await registerClient('tok', { onError });
+    expect(listen).toHaveBeenCalledTimes(1);
+    expect(listen).toHaveBeenCalledWith({ onError });
+    await registerClient('tok');
+    expect(listen).toHaveBeenLastCalledWith({ onError });
+  });
 });

packages/astro/src/client.ts

@@ -4,11 +4,77 @@
 // a UI renderer). The Integration injects `injectScript('page', "import { registerClient } … registerClient(…)")`.
 //
 // Browser-only → behind the `@bugsee/astro/client` subpath, never the portable `.`/`./middleware` entries.
-import { type Bugsee, type BugseeLaunchOptionsWithPerformance, launch } from '@bugsee/bugsee';
+import {
+  type Bugsee,
+  type BugseeLaunchOptionsWithPerformance,
+  launch,
+  relaunch as umbrellaRelaunch,
+} from '@bugsee/bugsee';
+import { flushQueuedAstroHydrationErrors, listenForAstroHydrationErrors } from './hydration';
 
 /** Options for the Astro client (browser) composition — the batteries-included browser umbrella options. */
 export interface AstroClientOptions extends BugseeLaunchOptionsWithPerformance {}
 
+// The hydration listener's options: where to report a failing sink, and which carrier the client lives on (a custom one is not on `globalThis`).
+const hydrationOptions = (
+  options:
+    | {
+        onError?: (error: unknown) => void;
+        carrier?: object;
+        document?: Document;
+        window?: unknown;
+      }
+    | undefined,
+) => {
+  // The page document the launch itself uses: an explicit `document`, else the bound window's. Omitted when neither yields one, which
+  // keeps the listener's default (`globalThis.document`). A hostile `window.document` getter (a sandboxed frame) counts as none.
+  let target: Document | undefined = options?.document;
+  if (target === undefined) {
+    try {
+      target = (options?.window as { document?: Document } | undefined)?.document;
+    } catch {
+      target = undefined;
+    }
+  }
+  return {
+    ...(options?.onError !== undefined ? { onError: options.onError } : {}),
+    ...(options?.carrier !== undefined ? { carrier: options.carrier } : {}),
+    ...(target !== undefined ? { target } : {}),
+  };
+};
+
+// The hydration options of the last registration (see `withHydrationWindow`).
+let lastHydration: ReturnType<typeof hydrationOptions> = {};
+
+/**
+ * Open the hydration listener's launch window, run `start`, and close the window in a `finally`: an error dispatched while the client is
+ * (re)starting is queued, and the flush runs whether the start succeeded or failed.
+ */
+async function withHydrationWindow<T>(
+  options:
+    | {
+        onError?: (error: unknown) => void;
+        carrier?: object;
+        document?: Document;
+        window?: unknown;
+      }
+    | undefined,
+  start: () => Promise<T>,
+): Promise<T> {
+  // Like core's `relaunchWith`, which keeps `document`, `window`, `carrier` and `onError` from the previous launch and lets an explicit one
+  // win: a plain `relaunch()` must watch the same document, on the same carrier, with the same sink.
+  const hydration = { ...lastHydration, ...hydrationOptions(options) };
+  lastHydration = hydration;
+  // Astro swallows an island's hydration failure into an `astro:hydration-error` event; nothing else would see it. Listen BEFORE the
+  // launch resolves (an error dispatched meanwhile is queued) and flush once the client exists.
+  listenForAstroHydrationErrors(hydration);
+  try {
+    return await start();
+  } finally {
+    flushQueuedAstroHydrationErrors(hydration); // success: report what queued; failure: end the window, nothing to report to
+  }
+}
+
 /**
  * Start Bugsee for the Astro client (browser). Returns the started client (a per-isolate singleton — a
  * repeat call returns the existing client).
@@ -17,7 +83,15 @@ export async function registerClient(
   appToken: string,
   options: AstroClientOptions = {},
 ): Promise<Bugsee> {
-  return await launch(appToken, options);
+  return await withHydrationWindow(options, () => launch(appToken, options));
+}
+
+/**
+ * `relaunch` from the umbrella, inside the same window: it `stop()`s the running client (clearing the carrier slot) and waits out the
+ * drain before the new one is set, and an island that fails to hydrate meanwhile must not be lost.
+ */
+export async function relaunch(options?: Parameters<typeof umbrellaRelaunch>[0]): Promise<Bugsee> {
+  return await withHydrationWindow(options, () => umbrellaRelaunch(options));
 }
 
 // API parity with the umbrella entries: the same VALUE surface, thin re-exports of the same functions.
@@ -30,5 +104,4 @@ export {
   type LifecycleEventsListener,
   type LifecycleEventType,
   type ReportAttachmentInput,
-  relaunch,
 } from '@bugsee/bugsee';