@smileid/usesmileid 12.0.0 → 12.0.2

package/src/presentation/theme/__tests__/use_use_smile_id_fonts.test.tsx

@@ -0,0 +1,166 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterEach,
+} from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+import Module from "node:module";
+import { DM_SANS_FONT_NAMES } from "../theme";
+
+/**
+ * The hook `require()`s the bundled `.ttf` assets — Metro resolves those to
+ * numeric asset ids, Node does not. Register a CommonJS handler that mimics
+ * Metro's numeric id so the font map can be asserted without a bundler.
+ */
+const nodeExtensions = (
+  Module as unknown as {
+    _extensions: Record<
+      string,
+      (mod: { exports: unknown }, filename: string) => void
+    >;
+  }
+)._extensions;
+
+let nextAssetId = 0;
+
+beforeAll(() => {
+  nodeExtensions[".ttf"] = (mod) => {
+    nextAssetId += 1;
+    mod.exports = nextAssetId;
+  };
+});
+
+type FontsModule = typeof import("../use_use_smile_id_fonts");
+type ExpoFontModule = { loadAsync: ReturnType<typeof vi.fn> };
+
+/** Fresh copy of the module so its one-shot `loadPromise` latch is reset. */
+async function freshModules(): Promise<{
+  fonts: FontsModule;
+  expoFont: ExpoFontModule;
+}> {
+  vi.resetModules();
+  const expoFont = (await import("expo-font")) as unknown as ExpoFontModule;
+  // The shared setup's `expo-font` mock survives `resetModules`, so its spy
+  // carries calls across tests unless cleared here.
+  expoFont.loadAsync.mockClear();
+  const fonts = (await import("../use_use_smile_id_fonts")) as FontsModule;
+  return { fonts, expoFont };
+}
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  warn.mockRestore();
+});
+
+describe("loadUseSmileIDFonts", () => {
+  it("registers every bundled DM Sans weight under its typography face name", async () => {
+    const { fonts, expoFont } = await freshModules();
+
+    await fonts.loadUseSmileIDFonts();
+
+    expect(expoFont.loadAsync).toHaveBeenCalledTimes(1);
+    const [map] = expoFont.loadAsync.mock.calls[0] as [Record<string, number>];
+    expect(Object.keys(map).sort()).toEqual(
+      Object.values(DM_SANS_FONT_NAMES).sort(),
+    );
+    for (const face of Object.values(DM_SANS_FONT_NAMES)) {
+      expect(typeof map[face]).toBe("number");
+    }
+  });
+
+  it("shares one in-flight load across concurrent flows", async () => {
+    const { fonts, expoFont } = await freshModules();
+
+    const [first, second] = [
+      fonts.loadUseSmileIDFonts(),
+      fonts.loadUseSmileIDFonts(),
+    ];
+    await Promise.all([first, second]);
+    await fonts.loadUseSmileIDFonts();
+
+    expect(first).toBe(second);
+    expect(expoFont.loadAsync).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("useUseSmileIDFonts", () => {
+  function renderHook(useHook: () => boolean) {
+    const seen: boolean[] = [];
+    function Probe() {
+      seen.push(useHook());
+      return null;
+    }
+    let renderer!: ReturnType<typeof createRenderer>;
+    act(() => {
+      renderer = createRenderer(<Probe />);
+    });
+    return { seen, renderer };
+  }
+
+  async function settle() {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  }
+
+  it("renders before the faces are registered, then flips to loaded", async () => {
+    const { fonts } = await freshModules();
+
+    const { seen } = renderHook(fonts.useUseSmileIDFonts);
+    expect(seen[0]).toBe(false);
+
+    await settle();
+
+    expect(seen.at(-1)).toBe(true);
+  });
+
+  it("never blocks the flow when font registration fails — warns and falls back", async () => {
+    const { fonts, expoFont } = await freshModules();
+    expoFont.loadAsync.mockRejectedValueOnce(new Error("asset registry down"));
+
+    const { seen } = renderHook(fonts.useUseSmileIDFonts);
+    await settle();
+
+    expect(seen.at(-1)).toBe(false);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("asset registry down"),
+    );
+  });
+
+  it("reports a non-Error rejection without crashing on `.message`", async () => {
+    const { fonts, expoFont } = await freshModules();
+    expoFont.loadAsync.mockRejectedValueOnce("native module missing");
+
+    renderHook(fonts.useUseSmileIDFonts);
+    await settle();
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("native module missing"),
+    );
+  });
+
+  it("stops tracking the load after unmount", async () => {
+    const { fonts } = await freshModules();
+
+    const { renderer, seen } = renderHook(fonts.useUseSmileIDFonts);
+    expect(seen).toEqual([false]);
+    act(() => {
+      renderer.unmount();
+    });
+    await settle();
+
+    // The load resolves after the screen is gone; the cleanup latch keeps it
+    // from re-rendering the unmounted tree.
+    expect(seen).toEqual([false]);
+  });
+});

package/src/presentation/utils/__tests__/locale_utils.test.ts

@@ -1,37 +1,78 @@
 import { describe, expect, it } from "vitest";
 
+import {
+  GlobalPrivacyControl,
+  globalPrivacyControlFromWire,
+  GLOBAL_PRIVACY_CONTROL_WIRE_KEY,
+} from "../../../core/models/global_privacy_control";
 import { getDefaultConsentState, isDeviceLocaleInEU } from "../locale_utils";
 
 describe("locale_utils", () => {
   it("EU locale (de-DE) is recognised as EU and default consent is false", () => {
     expect(isDeviceLocaleInEU("de-DE")).toBe(true);
-    expect(getDefaultConsentState("de-DE")).toBe(false);
+    expect(getDefaultConsentState(GlobalPrivacyControl.OptIn, "de-DE")).toBe(
+      false,
+    );
   });
 
   it("non-EU locale (en-US) is not EU and default consent is true", () => {
     expect(isDeviceLocaleInEU("en-US")).toBe(false);
-    expect(getDefaultConsentState("en-US")).toBe(true);
+    expect(getDefaultConsentState(GlobalPrivacyControl.OptIn, "en-US")).toBe(
+      true,
+    );
   });
 
   it("EU locale (fr-FR) is recognised as EU and default consent is false", () => {
     expect(isDeviceLocaleInEU("fr-FR")).toBe(true);
-    expect(getDefaultConsentState("fr-FR")).toBe(false);
+    expect(getDefaultConsentState(GlobalPrivacyControl.OptIn, "fr-FR")).toBe(
+      false,
+    );
   });
 
   it("non-EU locale (en-NG) is not EU and default consent is true", () => {
     expect(isDeviceLocaleInEU("en-NG")).toBe(false);
-    expect(getDefaultConsentState("en-NG")).toBe(true);
+    expect(getDefaultConsentState(GlobalPrivacyControl.OptIn, "en-NG")).toBe(
+      true,
+    );
   });
 
   it("bare language tag with no region falls back to non-EU", () => {
     // `"fr"` has no region segment — the BCP-47 split returns
     // undefined for the country, which never matches the EU set.
     expect(isDeviceLocaleInEU("fr")).toBe(false);
-    expect(getDefaultConsentState("fr")).toBe(true);
+    expect(getDefaultConsentState(GlobalPrivacyControl.OptIn, "fr")).toBe(true);
   });
 
   it("empty locale string falls back to non-EU", () => {
     expect(isDeviceLocaleInEU("")).toBe(false);
     expect(getDefaultConsentState("")).toBe(true);
   });
+
+  describe("global privacy control", () => {
+    it("default posture forces opt-out even for EU locales", () => {
+      expect(getDefaultConsentState()).toBe(true);
+      expect(getDefaultConsentState(GlobalPrivacyControl.OptOut, "de-DE")).toBe(
+        true,
+      );
+      expect(getDefaultConsentState(GlobalPrivacyControl.OptOut, "en-NG")).toBe(
+        true,
+      );
+    });
+
+    it("parses wire values and defaults unknowns to opt-out", () => {
+      expect(globalPrivacyControlFromWire("opt-out")).toBe(
+        GlobalPrivacyControl.OptOut,
+      );
+      expect(globalPrivacyControlFromWire("opt-in")).toBe(
+        GlobalPrivacyControl.OptIn,
+      );
+      expect(globalPrivacyControlFromWire(null)).toBe(
+        GlobalPrivacyControl.OptOut,
+      );
+      expect(globalPrivacyControlFromWire("user_settings")).toBe(
+        GlobalPrivacyControl.OptOut,
+      );
+      expect(GLOBAL_PRIVACY_CONTROL_WIRE_KEY).toBe("global_privacy_control");
+    });
+  });
 });

package/src/presentation/utils/locale_utils.ts

@@ -1,3 +1,4 @@
+import { GlobalPrivacyControl } from "../../core/models/global_privacy_control";
 const EU_COUNTRY_CODES: ReadonlySet<string> = new Set([
   "AT",
   "BE",
@@ -59,13 +60,21 @@ export function isDeviceLocaleInEU(
 }
 
 /**
- * Returns the default consent checkbox state based on the device locale.
+ * Returns the default consent checkbox state for the partner-declared
+ * `GlobalPrivacyControl` posture.
  *
- * - EU locales: unticked (`false`) to comply with GDPR opt-in.
- * - Non-EU locales: ticked (`true`).
+ * - `GlobalPrivacyControl.OptOut` (default): ticked (`true`) universally —
+ *   the opt-out layout is enforced for every session and the device region
+ *   is never consulted.
+ * - `GlobalPrivacyControl.OptIn`: legacy regional mechanics — EU locales
+ *   start unticked (`false`, explicit opt-in per GDPR), everywhere else
+ *   starts ticked (`true`).
  */
 export function getDefaultConsentState(
+  globalPrivacyControl: GlobalPrivacyControl = GlobalPrivacyControl.OptOut,
   locale: string = getDeviceLocale(),
 ): boolean {
-  return !isDeviceLocaleInEU(locale);
+  return globalPrivacyControl === GlobalPrivacyControl.OptOut
+    ? true
+    : !isDeviceLocaleInEU(locale);
 }

package/src/testing/__tests__/fake_face_analyzer.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { makeFakeFaceAnalyzer } from "../fake_face_analyzer";
+
+const scenario = {
+  name: "selfie-happy-path",
+  captureType: "selfie",
+  steps: [
+    { emit: "noFace", holdFrames: 2 },
+    { emit: "faceCentered", holdFrames: 3 },
+    { emit: "satisfied" },
+  ],
+} as const;
+
+describe("FakeFaceAnalyzer", () => {
+  it("replays holdFrames per step and repeats the final step indefinitely", () => {
+    const fake = makeFakeFaceAnalyzer(scenario);
+    const emits = Array.from({ length: 9 }, () => fake.nextEmit());
+    expect(emits).toEqual([
+      "noFace",
+      "noFace",
+      "faceCentered",
+      "faceCentered",
+      "faceCentered",
+      "satisfied",
+      "satisfied",
+      "satisfied",
+      "satisfied",
+    ]);
+  });
+
+  it("records the JS lifecycle calls", async () => {
+    const fake = makeFakeFaceAnalyzer(scenario);
+    await fake.configure();
+    await fake.reset();
+    await fake.flush();
+    await fake.close();
+    expect(fake.configureCallCount).toBe(1);
+    expect(fake.resetCallCount).toBe(1);
+    expect(fake.flushCallCount).toBe(1);
+    expect(fake.closeCallCount).toBe(1);
+  });
+});

package/src/testing/__tests__/scenario_expectations.test.ts

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  expectSubsetInOrder,
+  parseScenarioExpectations,
+} from "../scenario_expectations";
+
+// Read the canonical shared scenario at run time (see the capture-screen test
+// for the same rationale) so a drift in the shared `expected` block is caught
+// here per-PR rather than silently diverging.
+const scenarioDir = dirname(fileURLToPath(import.meta.url));
+const selfieScenario = JSON.parse(
+  readFileSync(
+    join(scenarioDir, "../../../../e2e/scenarios/selfie-happy-path.json"),
+    "utf8",
+  ),
+) as unknown;
+
+const agentModeScenario = JSON.parse(
+  readFileSync(
+    join(scenarioDir, "../../../../e2e/scenarios/selfie-agent-mode.json"),
+    "utf8",
+  ),
+) as unknown;
+
+describe("parseScenarioExpectations", () => {
+  // Nothing is relaxed for the agent, so the shared script must carry the same
+  // terminal contract as the front-camera happy path.
+  it("gives the shared agent-mode scenario the same terminal contract as the happy path", () => {
+    const agentMode = parseScenarioExpectations(agentModeScenario);
+    const happyPath = parseScenarioExpectations(selfieScenario);
+    expect(agentMode.screens).toEqual(happyPath.screens);
+    expect(agentMode.events).toEqual(happyPath.events);
+    expect(agentMode.terminal).toBe("submitted");
+  });
+
+  it("surfaces the shared selfie scenario's expected screens/events/terminal", () => {
+    const expected = parseScenarioExpectations(selfieScenario);
+    expect(expected.screens).toEqual([
+      "consent",
+      "instructions",
+      "capture",
+      "preview",
+      "processing",
+    ]);
+    expect(expected.events).toEqual([
+      "flow_started",
+      "consent_captured",
+      "selfie_captured",
+      "job_submitted",
+      "flow_completed",
+    ]);
+    expect(expected.terminal).toBe("submitted");
+  });
+
+  it("defaults to empty arrays when the block is absent", () => {
+    const expected = parseScenarioExpectations({ name: "x" });
+    expect(expected.screens).toEqual([]);
+    expect(expected.events).toEqual([]);
+  });
+
+  it("rejects a malformed expected block", () => {
+    expect(() =>
+      parseScenarioExpectations({ expected: { screens: [1, 2] } }),
+    ).toThrow(/must be an array of strings/);
+    expect(() =>
+      parseScenarioExpectations({ expected: { terminal: "exploded" } }),
+    ).toThrow(/terminal must be one of/);
+  });
+});
+
+describe("expectSubsetInOrder", () => {
+  it("passes when every expected item appears in order (interleaving allowed)", () => {
+    const { screens, events } = parseScenarioExpectations(selfieScenario);
+    // Recorded stream may carry extra, unlisted events between the required
+    // ones — the contract is subset-in-order, not exact match.
+    const recordedEvents = [
+      "flow_started",
+      "screen_viewed",
+      "consent_captured",
+      "screen_viewed",
+      "selfie_captured",
+      "image_quality_ok",
+      "job_submitted",
+      "flow_completed",
+    ];
+    expect(() => expectSubsetInOrder(recordedEvents, events)).not.toThrow();
+    expect(() => expectSubsetInOrder([...screens], screens)).not.toThrow();
+  });
+
+  it("throws when an expected item is missing", () => {
+    expect(() =>
+      expectSubsetInOrder(
+        ["flow_started", "flow_completed"],
+        ["flow_started", "job_submitted", "flow_completed"],
+      ),
+    ).toThrow(/job_submitted/);
+  });
+
+  it("throws when expected items appear out of order", () => {
+    expect(() =>
+      expectSubsetInOrder(
+        ["flow_completed", "flow_started"],
+        ["flow_started", "flow_completed"],
+      ),
+    ).toThrow(/to appear in order/);
+  });
+});

package/src/testing/__tests__/scenario_loader.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { parseScriptedScenario } from "../scenario_loader";
+
+describe("parseScriptedScenario", () => {
+  const valid = {
+    name: "selfie-happy-path",
+    captureType: "selfie",
+    steps: [
+      { emit: "noFace", holdFrames: 10 },
+      { emit: "faceCentered", holdFrames: 20 },
+      { emit: "satisfied" },
+    ],
+    // An `expected` block may ride alongside; the loader ignores extra keys.
+    expected: { screens: [], events: [], terminal: "submitted" },
+  };
+
+  it("returns the typed scenario for a valid shape", () => {
+    const scenario = parseScriptedScenario(valid);
+    expect(scenario.name).toBe("selfie-happy-path");
+    expect(scenario.captureType).toBe("selfie");
+    expect(scenario.steps).toHaveLength(3);
+    expect(scenario.steps[2]).toEqual({ emit: "satisfied" });
+  });
+
+  it("rejects an unknown emit (vocabulary drift)", () => {
+    expect(() =>
+      parseScriptedScenario({
+        name: "x",
+        captureType: "selfie",
+        steps: [{ emit: "wink" }],
+      }),
+    ).toThrow(/not a known emission/);
+  });
+
+  it("rejects an unknown captureType", () => {
+    expect(() =>
+      parseScriptedScenario({
+        name: "x",
+        captureType: "iris",
+        steps: [{ emit: "noFace" }],
+      }),
+    ).toThrow(/captureType/);
+  });
+
+  it("rejects empty steps", () => {
+    expect(() =>
+      parseScriptedScenario({ name: "x", captureType: "selfie", steps: [] }),
+    ).toThrow(/non-empty/);
+  });
+
+  it("rejects a non-integer holdFrames", () => {
+    expect(() =>
+      parseScriptedScenario({
+        name: "x",
+        captureType: "selfie",
+        steps: [{ emit: "noFace", holdFrames: 1.5 }],
+      }),
+    ).toThrow(/holdFrames/);
+  });
+
+  it("rejects a non-object input", () => {
+    expect(() => parseScriptedScenario("nope")).toThrow(/JSON object/);
+  });
+});

package/src/testing/fake_face_analyzer.ts

@@ -0,0 +1,82 @@
+import type { FaceAnalyzer } from "@smileid/usesmileid_platform_interface";
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+
+/**
+ * Deterministic fake face analyzer for scripted-scenario E2E runs. Exported
+ * only behind the `@smileid/usesmileid/testing` subpath so it cannot leak into
+ * partner production bundles.
+ *
+ * Per-frame detection runs in the provider's native frame-processor plugin
+ * (pixels never cross into JS), so `frameProcessorPluginName` points at a
+ * plugin that does not exist — the capture screen surfaces that as its
+ * camera-unavailable state. This fake covers the DSL registration seam and the
+ * capture-free flows; capture progression is driven via `onResult` instead.
+ */
+export interface ScriptedScenarioStep {
+  readonly emit: string;
+  readonly holdFrames?: number;
+}
+
+export interface ScriptedScenario {
+  readonly name: string;
+  readonly captureType: string;
+  readonly steps: readonly ScriptedScenarioStep[];
+}
+
+export class FakeFaceAnalyzer implements FaceAnalyzer {
+  readonly kind = "face" as const;
+  readonly key: AnalyzerFactoryKey = AnalyzerFactoryKey.MLKitFace;
+  readonly frameProcessorPluginName = "e2e-fake-face";
+
+  configureCallCount = 0;
+  resetCallCount = 0;
+  flushCallCount = 0;
+  closeCallCount = 0;
+
+  private stepIndex = 0;
+  private framesLeftInStep: number;
+
+  constructor(private readonly scenario: ScriptedScenario) {
+    this.framesLeftInStep = scenario.steps[0]?.holdFrames ?? 1;
+  }
+
+  /** Frame-by-frame cursor; the final step repeats indefinitely. */
+  nextEmit(): string {
+    const steps = this.scenario.steps;
+    const step = steps[this.stepIndex];
+    if (step === undefined) return "noFace";
+    if (this.stepIndex === steps.length - 1) return step.emit;
+    this.framesLeftInStep -= 1;
+    if (this.framesLeftInStep <= 0) {
+      this.stepIndex += 1;
+      this.framesLeftInStep = steps[this.stepIndex]?.holdFrames ?? 1;
+    }
+    return step.emit;
+  }
+
+  configure(): Promise<void> {
+    this.configureCallCount += 1;
+    return Promise.resolve();
+  }
+
+  reset(): Promise<void> {
+    this.resetCallCount += 1;
+    return Promise.resolve();
+  }
+
+  flush(): Promise<void> {
+    this.flushCallCount += 1;
+    return Promise.resolve();
+  }
+
+  close(): Promise<void> {
+    this.closeCallCount += 1;
+    return Promise.resolve();
+  }
+}
+
+export function makeFakeFaceAnalyzer(
+  scenario: ScriptedScenario,
+): FakeFaceAnalyzer {
+  return new FakeFaceAnalyzer(scenario);
+}

package/src/testing/index.ts

@@ -0,0 +1,15 @@
+// Test-support entry — exported behind the `@smileid/usesmileid/testing`
+// subpath only. Nothing here may be re-exported from the main index.
+export {
+  FakeFaceAnalyzer,
+  makeFakeFaceAnalyzer,
+  type ScriptedScenario,
+  type ScriptedScenarioStep,
+} from "./fake_face_analyzer";
+export { scriptedFaceScanResults } from "./scripted_scan_results";
+export { parseScriptedScenario } from "./scenario_loader";
+export {
+  type ScenarioExpectations,
+  parseScenarioExpectations,
+  expectSubsetInOrder,
+} from "./scenario_expectations";

package/src/testing/scenario_expectations.ts

@@ -0,0 +1,87 @@
+/**
+ * Capture-scoped expectations from the shared `e2e-scenarios` schema's `expected`
+ * block (screen + analytics-event names, terminal state). Framework-agnostic (no
+ * vitest/jest import) so a partner app's own e2e runner can reuse it.
+ */
+export interface ScenarioExpectations {
+  /** Ordered `screen_viewed` sequence for the canonical consent-first flow. */
+  readonly screens: readonly string[];
+  /** Ordered analytics event types that must fire (subset-in-order). */
+  readonly events: readonly string[];
+  /** How the capture session ends. */
+  readonly terminal?: "submitted" | "timeout" | "unsatisfied";
+}
+
+const TERMINALS: ReadonlySet<string> = new Set([
+  "submitted",
+  "timeout",
+  "unsatisfied",
+]);
+
+/**
+ * Extracts and validates the `expected` block from an already-parsed shared
+ * scenario JSON object. Returns empty screen/event arrays when the block is
+ * absent (older scenarios), and throws on a malformed block so drift fails
+ * loudly rather than silently weakening the contract.
+ */
+export function parseScenarioExpectations(raw: unknown): ScenarioExpectations {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("scenario must be a JSON object");
+  }
+  const expected = (raw as Record<string, unknown>).expected;
+  if (expected === undefined) {
+    return { screens: [], events: [] };
+  }
+  if (typeof expected !== "object" || expected === null) {
+    throw new Error("scenario.expected must be an object when present");
+  }
+  const record = expected as Record<string, unknown>;
+  const screens = readStringArray(record.screens, "scenario.expected.screens");
+  const events = readStringArray(record.events, "scenario.expected.events");
+  const terminal = record.terminal;
+  if (terminal === undefined) {
+    return { screens, events };
+  }
+  if (typeof terminal !== "string" || !TERMINALS.has(terminal)) {
+    throw new Error(
+      `scenario.expected.terminal must be one of ${[...TERMINALS].join(", ")}, got ${String(terminal)}`,
+    );
+  }
+  return {
+    screens,
+    events,
+    terminal: terminal as "submitted" | "timeout" | "unsatisfied",
+  };
+}
+
+function readStringArray(value: unknown, label: string): readonly string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value as string[];
+}
+
+/**
+ * Asserts that every element of [expected] appears in [recorded] in the same
+ * relative order (a minimal ordered-subset match — unlisted items may
+ * interleave, exact-match is deliberately NOT required). Throws a descriptive
+ * Error on failure so it works under any test runner.
+ */
+export function expectSubsetInOrder(
+  recorded: readonly string[],
+  expected: readonly string[],
+  label = "sequence",
+): void {
+  let cursor = 0;
+  for (const item of recorded) {
+    if (cursor < expected.length && item === expected[cursor]) cursor += 1;
+  }
+  if (cursor !== expected.length) {
+    throw new Error(
+      `${label}: expected [${expected
+        .slice(cursor)
+        .join(", ")}] to appear in order within [${recorded.join(", ")}]`,
+    );
+  }
+}