@specific.dev/spectest 0.103.0 → 0.105.0

package/README.md

@@ -66,6 +66,26 @@ The handshake returns a rejection `Response` or callbacks (`open`, `message`,
 in order per connection. WS and trusted WSS support text/binary messages;
 observe traffic through the fake's helpers.
 
+## Chat reactions (0.105.0)
+
+A `chat` annotation's message can carry the tapbacks a messaging app puts on
+a bubble. Each reaction is `{ emoji, from?, new? }`: `from` is `self` (the end
+user) or `other` (the default), and `new` marks one that arrived in this step,
+exactly like a message's `new`. A removed reaction simply stops being listed.
+
+```ts
+return annotate(turns, "chat", {
+  messages: turns.map((t) => ({
+    side: t.fromCustomer ? "self" : "other",
+    text: t.body,
+    reactions: t.acked ? [{ emoji: "✅", new: t.ackedNow }] : [],
+  })),
+});
+```
+
+The dashboard draws the chips on the bubble's lower corner, opposite the
+sender, and slides a new one in after the bubbles that arrived with it.
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/annotate.d.ts

@@ -113,6 +113,30 @@ export interface ChatMessageAnnotation {
      * the fake that marks them.
      */
     new?: boolean;
+    /**
+     * Reactions on this message — the tapbacks a messaging app lets either
+     * party put on a bubble (👀, ✅). Drawn as small chips on the bubble's
+     * corner. A reaction that was removed simply stops being listed.
+     */
+    reactions?: readonly ChatReactionAnnotation[];
+}
+/** One reaction on a {@link ChatMessageAnnotation}. */
+export interface ChatReactionAnnotation {
+    /** The reaction itself — one emoji, usually. */
+    emoji: string;
+    /**
+     * Who reacted: `self` is the end user, `other` whoever they are talking
+     * to. Defaults to `other`, which is also what any other value draws as —
+     * a reaction on the wrong side can be seen and fixed, a dropped one
+     * cannot.
+     */
+    from?: "self" | "other";
+    /**
+     * This reaction arrived in *this* call — a message's `new`, and the
+     * fake's to set for the same reason: only it knows what the app had
+     * already seen. It slides in after the messages that arrived with it.
+     */
+    new?: boolean;
 }
 /**
  * Say what a fake helper's return value *is*, so the timeline can draw it

package/dist/annotate.js

@@ -173,8 +173,33 @@ function chatMessageOf(src) {
         msg.text = truncateUtf8(body).value;
     if (src.new === true)
         msg.new = true;
+    const reactions = reactionsOf(src.reactions);
+    if (reactions.length > 0)
+        msg.reactions = reactions;
     return msg;
 }
+/** Reactions get the tolerance `side` gets: an entry that isn't quite right
+ *  is drawn rather than dropped — a `from` that is missing or misspelled is
+ *  the other party's — and only one with nothing to draw (no string
+ *  `emoji`, or an empty one) is skipped. */
+function reactionsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const entry of v) {
+        const src = fields(entry);
+        if (typeof src.emoji !== "string" || src.emoji === "")
+            continue;
+        const reaction = {
+            emoji: truncateUtf8(src.emoji).value,
+            from: text(src.from) === "self" ? "self" : "other",
+        };
+        if (src.new === true)
+            reaction.new = true;
+        out.push(reaction);
+    }
+    return out;
+}
 function messageOf(src) {
     const msg = {};
     const from = text(src.from);

package/dist/browser.d.ts

@@ -22,6 +22,13 @@ export interface BrowserOptions {
     frame?: "browser" | "mobile";
     /** Initial URL to navigate to before the constructor returns. */
     url?: string;
+    /** IANA timezone, e.g. "Europe/Stockholm". Defaults to the host timezone.
+     * Set on first creation; inherited sessions keep their original timezone. */
+    timezone?: string;
+    /** Locale, e.g. "sv-SE", for navigator.language, Accept-Language and
+     * date/number formatting. Omit to use the browser's default locale.
+     * Set on first creation; inherited sessions keep their original locale. */
+    locale?: string;
     /** Feed a WAV fixture through Chromium's native microphone capture.
      * Set on the session's first creation; inherited sessions keep their source.
      * Fixture sessions use a dedicated Chromium process for audio isolation. */
@@ -296,7 +303,7 @@ export interface SafeAreaInsets {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export declare function prewarmViewPool(n?: number): Promise<void>;
 /**

package/dist/browser.js

@@ -160,20 +160,24 @@ function deviceContextOptions(d) {
 }
 /** Create the context one view lives in — device emulation when the view is
  *  phone-emulated, a plain viewport otherwise. */
-async function newViewContext(width, height, device, microphone) {
-    const fixture = microphone === undefined ? undefined : await prepareMicrophoneFixture(microphone);
+async function newViewContext(width, height, device, opts = {}) {
+    const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
     let browser;
     try {
         browser = fixture ? await chromium.launch({
             executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
         }) : await ensurePlaywrightBrowser();
-        const context = await browser.newContext(device
-            ? deviceContextOptions(device)
-            : {
-                viewport: { width, height },
-                // Reduced-motion for replay fidelity — see deviceContextOptions.
-                reducedMotion: "reduce",
-            });
+        const context = await browser.newContext({
+            ...(device
+                ? deviceContextOptions(device)
+                : {
+                    viewport: { width, height },
+                    // Reduced-motion for replay fidelity — see deviceContextOptions.
+                    reducedMotion: "reduce",
+                }),
+            timezoneId: opts.timezone,
+            locale: opts.locale,
+        });
         context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
         context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
         if (fixture) {
@@ -879,7 +883,7 @@ async function createView(width, height) {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export async function prewarmViewPool(n = 1) {
     for (let i = 0; i < n; i++) {
@@ -910,10 +914,11 @@ export async function openMobileBackend(opts = {}) {
     const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
     const wantW = device ? device.viewport.width : opts.width ?? 1280;
     const wantH = device ? device.viewport.height : opts.height ?? 720;
-    // Mobile views are never pooled — the pool holds only default-desktop
-    // views (in the shared desktop context), and a mobile view needs its own
-    // emulated context anyway.
-    const pooled = !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    // The pool holds only default-desktop contexts. Context creation options
+    // such as timezone and locale require a fresh context.
+    const pooled = !device && opts.microphone === undefined && opts.timezone === undefined &&
+        opts.locale === undefined && wantW === 1280 && wantH === 720
+        ? VIEW_POOL.pop() : undefined;
     let holder;
     if (pooled) {
         holder = {
@@ -930,7 +935,7 @@ export async function openMobileBackend(opts = {}) {
         };
     }
     else {
-        holder = await newHolder(wantW, wantH, device, opts.microphone);
+        holder = await newHolder(wantW, wantH, device, opts);
     }
     const { backend } = buildBackend(holder, opts.recorder ?? null, {
         persistent: false,
@@ -992,8 +997,8 @@ function checkSessionCap(kind, live, name) {
         `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
         `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
 }
-async function newHolder(width, height, device, microphone) {
-    const context = await newViewContext(width, height, device, microphone);
+async function newHolder(width, height, device, opts = {}) {
+    const context = await newViewContext(width, height, device, opts);
     let spawned;
     try {
         spawned = await spawnPage(context);
@@ -1073,7 +1078,7 @@ export async function acquirePersistentBrowser(name = "", opts = {}) {
     }
     else {
         checkSessionCap("browser", SHARED_BROWSERS.size, name);
-        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts.microphone);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts);
         SHARED_BROWSERS.set(name, holder);
     }
     const view = holder;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, Wra
 import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 export { field } from "./inspect.js";
 export { annotate } from "./annotate.js";
-export type { Annotated, AnnotationKind, AnnotationOptions, ChatAnnotation, ChatMessageAnnotation, EmailAnnotation, } from "./annotate.js";
+export type { Annotated, AnnotationKind, AnnotationOptions, ChatAnnotation, ChatMessageAnnotation, ChatReactionAnnotation, EmailAnnotation, } from "./annotate.js";
 import type { Annotated } from "./annotate.js";
 export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";

package/dist/locator-errors.js

@@ -15,7 +15,7 @@
 // only ever replaced when we have something better to say.
 //
 // `classifyLocatorFailure` also says WHICH failure it was, because only one of
-// them — a locator that matched nothing — can be explained further by asking
+// them — a locator that did not resolve — can be explained further by asking
 // the page what it holds (see locator-hints.ts).
 //
 // The call log is read from the error's own `log` array (playwright attaches
@@ -55,8 +55,8 @@ function logFromMessage(message) {
 function cleanLogLine(line) {
     return line.trim().replace(/^-\s*/, "").replace(/^\d+\s*×\s*/, "");
 }
-/** Did the locator ever match anything? Playwright logs "locator resolved to
- *  <html>" the moment it does, and nothing of the sort when it never did. */
+/** Did Playwright report resolution? A missing entry can also mean its
+ *  renderer or transport stalled before it could resolve the locator. */
 function resolved(log) {
     return log.some((l) => l.startsWith("locator resolved to"));
 }
@@ -125,8 +125,11 @@ export function classifyLocatorFailure(label, err) {
     if (!detail)
         return undefined;
     const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
+    // A renderer or transport stall can time out before resolution even when
+    // the element exists (confirmed by a Specific failure replay). Absence of
+    // a resolved log entry is not proof that the DOM contains no match.
     if (!resolved(detail.log)) {
-        return { kind: "no-match", message: `No element matches ${label} ${waited}` };
+        return { kind: "no-match", message: `Timed out resolving ${label} ${waited}` };
     }
     // It matched, so the failure is about the element's state.
     const state = (message) => ({ kind: "state", message });
@@ -198,5 +201,11 @@ export async function rewriteLocatorErrorWithHints(err, label, hints) {
             /* A diagnostic must never replace the failure it explains. */
         }
     }
-    return setErrorMessage(err, message);
+    // Preserve the original diagnostic when a friendly rewrite is misleading.
+    // Error.cause is non-enumerable, so it does not expand recorder payloads.
+    const e = err;
+    if (e.cause === undefined) {
+        Object.defineProperty(e, "cause", { value: new Error(e.message), configurable: true });
+    }
+    return setErrorMessage(e, message);
 }

package/dist/recorder.d.ts

@@ -646,6 +646,23 @@ export interface ChatBlockMessage {
     /** Arrived in *this* step: drawn with an entrance animation. Only the
      *  producer knows this, so only the producer sets it. */
     new?: boolean;
+    /** Reactions on this message — the tapbacks a messaging app lets either
+     *  party put on a bubble (👀, ✅). Drawn as chips on the bubble's lower
+     *  corner, on the side opposite the sender. Absent and empty read the
+     *  same: nothing to draw. */
+    reactions?: ChatBlockReaction[];
+}
+/** One reaction on a {@link ChatBlockMessage}. */
+export interface ChatBlockReaction {
+    /** The reaction itself — an emoji, or any short string. */
+    emoji: string;
+    /** Who reacted. `self` is the end user, `other` the party they are
+     *  talking to; absent reads as `other`. */
+    from?: "self" | "other";
+    /** Arrived in *this* step, like a message's `new`: drawn with the same
+     *  entrance animation, after the bubbles that arrived with it. Only the
+     *  producer knows this, so only the producer sets it. */
+    new?: boolean;
 }
 /**
  * A step that describes itself in presentation terms — a title plus an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.103.0",
+  "version": "0.105.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/annotate.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+
+import { annotate, readAnnotation } from "./annotate.js";
+
+/** Open a chat annotation: the messages its one block lowered to, and the
+ *  value the test would receive. */
+function chat(boxed: unknown) {
+  const opened = readAnnotation(boxed);
+  if (!opened || opened.annotation.kind !== "chat") throw new Error("not a chat annotation");
+  const block = opened.annotation.blocks[0];
+  if (!block || block.type !== "chat") throw new Error("not a chat block");
+  return { messages: block.messages, value: opened.value };
+}
+
+describe("annotate chat", () => {
+  test("copies a message's reactions through and leaves the value alone", () => {
+    const turns = [
+      {
+        side: "self",
+        text: "where is my order?",
+        reactions: [{ emoji: "👀" }, { emoji: "✅", from: "self", new: true }],
+      },
+      { side: "other", text: "It ships today.", new: true },
+    ];
+    const { messages, value } = chat(annotate(turns, "chat"));
+    expect(value).toBe(turns);
+    expect(messages[0]!.reactions).toEqual([
+      // No `from` is the other party's, exactly as no `side` is.
+      { emoji: "👀", from: "other" },
+      { emoji: "✅", from: "self", new: true },
+    ]);
+    // A message without reactions carries no empty list.
+    expect(messages[1]!.reactions).toBeUndefined();
+    expect(messages[1]).toEqual({ side: "other", text: "It ships today.", new: true });
+  });
+
+  // The tolerance `side` has: a reaction that isn't quite right is drawn —
+  // on the other party's side — rather than dropped. Only one with nothing
+  // to draw is skipped.
+  test("draws a reaction it does not quite understand and skips one it cannot", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          {
+            side: "self",
+            text: "hi",
+            reactions: [
+              { emoji: "❤️", from: "them", new: "yes" },
+              { emoji: 42 },
+              { emoji: "" },
+              "👍",
+              { emoji: "🎉", from: "self" },
+            ],
+          },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]!.reactions).toEqual([
+      { emoji: "❤️", from: "other" },
+      { emoji: "🎉", from: "self" },
+    ]);
+  });
+
+  test("a reactions field that is not a list is no reactions", () => {
+    const { messages } = chat(annotate([{ side: "self", text: "hi", reactions: "👍" }], "chat"));
+    expect(messages[0]!.reactions).toBeUndefined();
+  });
+
+  test("reactions ride along when the messages are passed as options", () => {
+    const { messages } = chat(
+      annotate({ id: 7 }, "chat", {
+        title: "+46 70 123 45 67",
+        messages: [{ side: "other", text: "Done?", reactions: [{ emoji: "✅", from: "self", new: true }] }],
+      }),
+    );
+    expect(messages[0]!.reactions).toEqual([{ emoji: "✅", from: "self", new: true }]);
+  });
+});

package/src/annotate.ts

@@ -34,6 +34,7 @@ import { deepUnwrap } from "./inspect.js";
 import {
   truncateUtf8,
   type ChatBlockMessage,
+  type ChatBlockReaction,
   type EmailEventMessage,
   type EmailEventSummary,
   type StepBlock,
@@ -171,6 +172,31 @@ export interface ChatMessageAnnotation {
    * the fake that marks them.
    */
   new?: boolean;
+  /**
+   * Reactions on this message — the tapbacks a messaging app lets either
+   * party put on a bubble (👀, ✅). Drawn as small chips on the bubble's
+   * corner. A reaction that was removed simply stops being listed.
+   */
+  reactions?: readonly ChatReactionAnnotation[];
+}
+
+/** One reaction on a {@link ChatMessageAnnotation}. */
+export interface ChatReactionAnnotation {
+  /** The reaction itself — one emoji, usually. */
+  emoji: string;
+  /**
+   * Who reacted: `self` is the end user, `other` whoever they are talking
+   * to. Defaults to `other`, which is also what any other value draws as —
+   * a reaction on the wrong side can be seen and fixed, a dropped one
+   * cannot.
+   */
+  from?: "self" | "other";
+  /**
+   * This reaction arrived in *this* call — a message's `new`, and the
+   * fake's to set for the same reason: only it knows what the app had
+   * already seen. It slides in after the messages that arrived with it.
+   */
+  new?: boolean;
 }
 
 /** Listing rows carried on the event. The returned value is never capped. */
@@ -330,9 +356,31 @@ function chatMessageOf(src: Record<string, unknown>): ChatBlockMessage {
   const body = text(src.text);
   if (body) msg.text = truncateUtf8(body).value;
   if (src.new === true) msg.new = true;
+  const reactions = reactionsOf(src.reactions);
+  if (reactions.length > 0) msg.reactions = reactions;
   return msg;
 }
 
+/** Reactions get the tolerance `side` gets: an entry that isn't quite right
+ *  is drawn rather than dropped — a `from` that is missing or misspelled is
+ *  the other party's — and only one with nothing to draw (no string
+ *  `emoji`, or an empty one) is skipped. */
+function reactionsOf(v: unknown): ChatBlockReaction[] {
+  if (!Array.isArray(v)) return [];
+  const out: ChatBlockReaction[] = [];
+  for (const entry of v) {
+    const src = fields(entry);
+    if (typeof src.emoji !== "string" || src.emoji === "") continue;
+    const reaction: ChatBlockReaction = {
+      emoji: truncateUtf8(src.emoji).value,
+      from: text(src.from) === "self" ? "self" : "other",
+    };
+    if (src.new === true) reaction.new = true;
+    out.push(reaction);
+  }
+  return out;
+}
+
 function messageOf(src: Record<string, unknown>): EmailEventMessage {
   const msg: EmailEventMessage = {};
   const from = text(src.from);

package/src/browser-timezone.test.ts

@@ -0,0 +1,105 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { readRaw } from "./inspect.js";
+import {
+  acquirePersistentBrowser,
+  openBrowser,
+  prewarmViewPool,
+  type Browser,
+} from "./browser.js";
+
+interface Settings {
+  timezone: string;
+  locale: string;
+  language: string;
+  acceptLanguage: string;
+  winterOffset: number;
+  summerOffset: number;
+  number: string;
+}
+
+async function settings(browser: Browser): Promise<Settings> {
+  return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
+}
+
+describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("browser timezone and locale", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  beforeAll(() => {
+    server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: request => new Response(`<script>
+        window.settings = {
+          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+          locale: Intl.DateTimeFormat().resolvedOptions().locale,
+          language: navigator.language,
+          acceptLanguage: ${JSON.stringify(request.headers.get("accept-language"))},
+          winterOffset: new Date("2026-01-15T12:00:00Z").getTimezoneOffset(),
+          summerOffset: new Date("2026-07-15T12:00:00Z").getTimezoneOffset(),
+          number: new Intl.NumberFormat().format(1234.5),
+        };
+      </script>`, { headers: { "content-type": "text/html" } }),
+    });
+  });
+  afterAll(() => server.stop(true));
+
+  test("applies both options before initial navigation and retains them after reload", async () => {
+    const browser = await openBrowser({ timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const initial = await settings(browser);
+      expect(initial).toMatchObject({
+        timezone: "Europe/Stockholm", locale: "sv-SE", language: "sv-SE",
+        winterOffset: -60, summerOffset: -120, number: "1\u00a0234,5",
+      });
+      expect(initial.acceptLanguage.split(",")[0]).toBe("sv-SE");
+      await browser.reload();
+      expect(await settings(browser)).toEqual(initial);
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test.each([
+    { timezone: "Europe/Stockholm" },
+    { locale: "sv-SE" },
+  ])("bypasses the default view pool for %j without changing defaults", async options => {
+    const baseline = await openBrowser({ url: server.url.href });
+    let defaults: Settings;
+    try { defaults = await settings(baseline); } finally { await baseline.close(); }
+    await prewarmViewPool();
+    const browser = await openBrowser({ ...options, url: server.url.href });
+    try {
+      const actual = await settings(browser);
+      expect(actual.timezone).toBe(options.timezone ?? defaults.timezone);
+      expect(actual.language).toBe(options.locale ?? defaults.language);
+    } finally { await browser.close(); }
+    const pooled = await openBrowser({ url: server.url.href });
+    try { expect(await settings(pooled)).toEqual(defaults); } finally { await pooled.close(); }
+  }, 20000);
+
+  test("named sessions are isolated and reattachment keeps first-call settings", async () => {
+    const a = await acquirePersistentBrowser("regional-a", { timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const b = await acquirePersistentBrowser("regional-b", { timezone: "America/New_York", locale: "en-US", url: server.url.href });
+      try {
+        expect(await settings(b.browser)).toMatchObject({ timezone: "America/New_York", language: "en-US", winterOffset: 300, summerOffset: 240 });
+        const original = await settings(a.browser);
+        expect(original).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE" });
+        await a.detach();
+        const attached = await acquirePersistentBrowser("regional-a", { timezone: "UTC", locale: "en-US" });
+        expect(attached.attached).toBe(true);
+        await attached.browser.reload();
+        expect(await settings(attached.browser)).toEqual(original);
+        await attached.detach();
+      } finally { await b.browser.close(); }
+    } finally { await a.browser.close(); }
+  }, 20000);
+
+  test("mobile framing retains regional settings", async () => {
+    const browser = await openBrowser({ frame: "mobile", timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      expect(await settings(browser)).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE", winterOffset: -60 });
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test("rejects an invalid timezone", async () => {
+    await expect(openBrowser({ timezone: "Invalid/Timezone" })).rejects.toThrow(/timezone/i);
+  }, 20000);
+});

package/src/browser.ts

@@ -93,6 +93,13 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
+  /** IANA timezone, e.g. "Europe/Stockholm". Defaults to the host timezone.
+   * Set on first creation; inherited sessions keep their original timezone. */
+  timezone?: string;
+  /** Locale, e.g. "sv-SE", for navigator.language, Accept-Language and
+   * date/number formatting. Omit to use the browser's default locale.
+   * Set on first creation; inherited sessions keep their original locale. */
+  locale?: string;
   /** Feed a WAV fixture through Chromium's native microphone capture.
    * Set on the session's first creation; inherited sessions keep their source.
    * Fixture sessions use a dedicated Chromium process for audio isolation. */
@@ -510,23 +517,25 @@ async function newViewContext(
   width: number,
   height: number,
   device: DevicePreset | null,
-  microphone?: MicrophoneFixture,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<BrowserContext> {
-  const fixture = microphone === undefined ? undefined : await prepareMicrophoneFixture(microphone);
+  const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
   let browser: PlaywrightBrowser | undefined;
   try {
     browser = fixture ? await chromium.launch({
       executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
-    const context = await browser.newContext(
-      device
+    const context = await browser.newContext({
+      ...(device
         ? deviceContextOptions(device)
         : {
             viewport: { width, height },
             // Reduced-motion for replay fidelity — see deviceContextOptions.
             reducedMotion: "reduce",
-          },
-    );
+          }),
+      timezoneId: opts.timezone,
+      locale: opts.locale,
+    });
     context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
     context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
     if (fixture) {
@@ -1310,7 +1319,7 @@ async function createView(width: number, height: number): Promise<PooledView> {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export async function prewarmViewPool(n = 1): Promise<void> {
   for (let i = 0; i < n; i++) {
@@ -1345,11 +1354,12 @@ export async function openMobileBackend(
   const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
   const wantW = device ? device.viewport.width : opts.width ?? 1280;
   const wantH = device ? device.viewport.height : opts.height ?? 720;
-  // Mobile views are never pooled — the pool holds only default-desktop
-  // views (in the shared desktop context), and a mobile view needs its own
-  // emulated context anyway.
+  // The pool holds only default-desktop contexts. Context creation options
+  // such as timezone and locale require a fresh context.
   const pooled =
-    !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    !device && opts.microphone === undefined && opts.timezone === undefined &&
+    opts.locale === undefined && wantW === 1280 && wantH === 720
+      ? VIEW_POOL.pop() : undefined;
   let holder: ViewHolder;
   if (pooled) {
     holder = {
@@ -1365,7 +1375,7 @@ export async function openMobileBackend(
       initScripts: [],
     };
   } else {
-    holder = await newHolder(wantW, wantH, device, opts.microphone);
+    holder = await newHolder(wantW, wantH, device, opts);
   }
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
@@ -1437,9 +1447,9 @@ async function newHolder(
   width: number,
   height: number,
   device: DevicePreset | null,
-  microphone?: MicrophoneFixture,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<ViewHolder> {
-  const context = await newViewContext(width, height, device, microphone);
+  const context = await newViewContext(width, height, device, opts);
   let spawned: SpawnedPage;
   try { spawned = await spawnPage(context); } catch (err) {
     await closeViewContext(context);
@@ -1539,7 +1549,7 @@ export async function acquirePersistentBrowser(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
-      opts.microphone,
+      opts,
     );
     SHARED_BROWSERS.set(name, holder);
   }

package/src/index.ts

@@ -63,6 +63,7 @@ export type {
   AnnotationOptions,
   ChatAnnotation,
   ChatMessageAnnotation,
+  ChatReactionAnnotation,
   EmailAnnotation,
 } from "./annotate.js";
 import type { Annotated } from "./annotate.js";

package/src/locator-errors.test.ts

@@ -21,12 +21,12 @@ function timeoutError(message: string, log: string[]): Error {
 }
 
 describe("locatorFailureMessage", () => {
-  test("names the element that was never found", () => {
+  test("names the locator that did not resolve", () => {
     const err = timeoutError("click: Timeout 5000ms exceeded.", [
       "  - waiting for getByTestId('add')",
     ]);
     expect(locatorFailureMessage('testid "add"', err)).toBe(
-      'No element matches testid "add" (waited 5s)',
+      'Timed out resolving testid "add" (waited 5s)',
     );
   });
 
@@ -84,7 +84,7 @@ describe("locatorFailureMessage", () => {
     ]);
     delete (err as { log?: unknown }).log;
     expect(locatorFailureMessage('testid "add"', err)).toBe(
-      'No element matches testid "add" (waited 5s)',
+      'Timed out resolving testid "add" (waited 5s)',
     );
   });
 
@@ -145,7 +145,7 @@ describe("rewriteLocatorErrorWithHints", () => {
       "\nClose matches on the page:\n  - testid \"add-todo\"",
     )) as Error;
     expect(err.message).toBe(
-      'No element matches testid "add" (waited 5s)\n' +
+      'Timed out resolving testid "add" (waited 5s)\n' +
         'Close matches on the page:\n  - testid "add-todo"',
     );
     // The stack's copy of the message is rewritten too, or the CLI would
@@ -173,7 +173,7 @@ describe("rewriteLocatorErrorWithHints", () => {
     const err = (await rewriteLocatorErrorWithHints(missing(), 'testid "add"', async () => {
       throw new Error("page closed");
     })) as Error;
-    expect(err.message).toBe('No element matches testid "add" (waited 5s)');
+    expect(err.message).toBe('Timed out resolving testid "add" (waited 5s)');
   });
 });
 
@@ -189,8 +189,8 @@ describe("rewriteLocatorErrorWithHints (stack)", () => {
     )) as Error;
 
     expect(out).toBe(err); // same error: the author's own frames survive
-    expect(out.message).toBe('No element matches testid "add" (waited 5s)');
-    expect(out.stack).toStartWith('No element matches testid "add" (waited 5s)');
+    expect(out.message).toBe('Timed out resolving testid "add" (waited 5s)');
+    expect(out.stack).toStartWith('Timed out resolving testid "add" (waited 5s)');
     expect(out.stack).not.toContain("Timeout 5000ms exceeded");
     expect(out.stack).toContain("todo.ts:12:34");
   });
@@ -211,3 +211,11 @@ describe("formatWaited", () => {
     expect(formatWaited(30_000)).toBe("30s");
   });
 });
+
+test("retains the original Playwright diagnostic for a stalled renderer", async () => {
+  const err = timeoutError("click: Timeout 10000ms exceeded.", ["  - waiting for locator('#confirm')"]);
+  const original = err.message;
+  await rewriteLocatorErrorWithHints(err, 'css "#confirm"', async () => "");
+  expect(err.message).toBe('Timed out resolving css "#confirm" (waited 10s)');
+  expect((err.cause as Error).message).toBe(original);
+});

package/src/locator-errors.ts

@@ -15,7 +15,7 @@
 // only ever replaced when we have something better to say.
 //
 // `classifyLocatorFailure` also says WHICH failure it was, because only one of
-// them — a locator that matched nothing — can be explained further by asking
+// them — a locator that did not resolve — can be explained further by asking
 // the page what it holds (see locator-hints.ts).
 //
 // The call log is read from the error's own `log` array (playwright attaches
@@ -67,8 +67,8 @@ function cleanLogLine(line: string): string {
   return line.trim().replace(/^-\s*/, "").replace(/^\d+\s*×\s*/, "");
 }
 
-/** Did the locator ever match anything? Playwright logs "locator resolved to
- *  <html>" the moment it does, and nothing of the sort when it never did. */
+/** Did Playwright report resolution? A missing entry can also mean its
+ *  renderer or transport stalled before it could resolve the locator. */
 function resolved(log: string[]): boolean {
   return log.some((l) => l.startsWith("locator resolved to"));
 }
@@ -147,8 +147,11 @@ export function classifyLocatorFailure(
   const detail = parseTimeout(err);
   if (!detail) return undefined;
   const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
+  // A renderer or transport stall can time out before resolution even when
+  // the element exists (confirmed by a Specific failure replay). Absence of
+  // a resolved log entry is not proof that the DOM contains no match.
   if (!resolved(detail.log)) {
-    return { kind: "no-match", message: `No element matches ${label} ${waited}` };
+    return { kind: "no-match", message: `Timed out resolving ${label} ${waited}` };
   }
 
   // It matched, so the failure is about the element's state.
@@ -228,5 +231,11 @@ export async function rewriteLocatorErrorWithHints(
       /* A diagnostic must never replace the failure it explains. */
     }
   }
-  return setErrorMessage(err as Error, message);
+  // Preserve the original diagnostic when a friendly rewrite is misleading.
+  // Error.cause is non-enumerable, so it does not expand recorder payloads.
+  const e = err as Error;
+  if (e.cause === undefined) {
+    Object.defineProperty(e, "cause", { value: new Error(e.message), configurable: true });
+  }
+  return setErrorMessage(e, message);
 }

package/src/recorder.ts

@@ -897,6 +897,24 @@ export interface ChatBlockMessage {
   /** Arrived in *this* step: drawn with an entrance animation. Only the
    *  producer knows this, so only the producer sets it. */
   new?: boolean;
+  /** Reactions on this message — the tapbacks a messaging app lets either
+   *  party put on a bubble (👀, ✅). Drawn as chips on the bubble's lower
+   *  corner, on the side opposite the sender. Absent and empty read the
+   *  same: nothing to draw. */
+  reactions?: ChatBlockReaction[];
+}
+
+/** One reaction on a {@link ChatBlockMessage}. */
+export interface ChatBlockReaction {
+  /** The reaction itself — an emoji, or any short string. */
+  emoji: string;
+  /** Who reacted. `self` is the end user, `other` the party they are
+   *  talking to; absent reads as `other`. */
+  from?: "self" | "other";
+  /** Arrived in *this* step, like a message's `new`: drawn with the same
+   *  entrance animation, after the bubbles that arrived with it. Only the
+   *  producer knows this, so only the producer sets it. */
+  new?: boolean;
 }
 
 /**