@wenathlan/devthink 2.0.13 → 2.0.15

package/tests/datagrid.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import {
+  datagridcolumnsof,
+  datagridof,
+  exportdatagrid,
+  exportmenudescriptors,
+  exportrowsof,
+  filterdatagridrows,
+  infercolumntype,
+  maskedvalueof,
+  selectrowrange,
+  sortdatagridrows,
+} from "../views.js";
+
+const now = 1_800_000_000_000;
+
+describe("datagrid and exportmenu", () => {
+  it("infers the column types from the observed values", () => {
+    expect(infercolumntype(["1", "2.5", "-3"])).toBe("number");
+    expect(infercolumntype(["true", "false"])).toBe("boolean");
+    expect(infercolumntype(["2024-05-01", "2024-06-15"])).toBe("date");
+    expect(infercolumntype(["alpha", "beta"])).toBe("text");
+    expect(infercolumntype(["", ""])).toBe("empty");
+    const columns = datagridcolumnsof([{ name: "alpha", price: "10", live: "true" }]);
+    expect(columns.find((column) => column.field === "name")?.type).toBe("text");
+    expect(columns.find((column) => column.field === "price")?.type).toBe("number");
+    expect(columns.find((column) => column.field === "live")?.type).toBe("boolean");
+    expect(columns.every((column) => column.inferred)).toBe(true);
+  });
+
+  it("builds the datagrid view of an extraction result and refuses empty shapes", () => {
+    const view = datagridof({
+      title: "  Pricing table  ",
+      origin: "https://example.com",
+      runid: "run-1",
+      rows: [
+        { item: "screwdriver", price: "12" },
+        { item: "hammer", price: "20" },
+      ],
+      at: now,
+    });
+    expect(view.title).toBe("Pricing table");
+    expect(view.rows).toHaveLength(2);
+    expect(view.rows[0]?.index).toBe(0);
+    expect(view.columns.map((column) => column.field)).toEqual(["item", "price"]);
+    expect(() =>
+      datagridof({ title: "", origin: "https://example.com", runid: "run-1", rows: [{ a: "b" }], at: now }),
+    ).toThrow(/title/);
+    expect(() => datagridof({ title: "grid", origin: " ", runid: "run-1", rows: [{ a: "b" }], at: now })).toThrow(
+      /origin/,
+    );
+    expect(() =>
+      datagridof({ title: "grid", origin: "https://example.com", runid: "run-1", rows: [], at: now }),
+    ).toThrow(/row/);
+  });
+
+  it("sorts and filters rows locally inside the surface", () => {
+    const view = datagridof({
+      title: "grid",
+      origin: "https://example.com",
+      runid: "run-1",
+      rows: [
+        { item: "hammer", price: "20" },
+        { item: "screwdriver", price: "12" },
+        { item: "wrench", price: "15" },
+      ],
+      at: now,
+    });
+    const sorted = sortdatagridrows(view, { field: "price", direction: "ascending" });
+    expect(sorted.rows.map((row) => row.values.item)).toEqual(["screwdriver", "wrench", "hammer"]);
+    const descending = sortdatagridrows(view, { field: "price", direction: "descending" });
+    expect(descending.rows.map((row) => row.values.item)).toEqual(["hammer", "wrench", "screwdriver"]);
+    expect(() => sortdatagridrows(view, { field: "unknown", direction: "ascending" })).toThrow(/column/);
+    const filtered = filterdatagridrows(view, "HAMMER");
+    expect(filtered.rows.map((row) => row.values.item)).toEqual(["hammer"]);
+    expect(filterdatagridrows(view, "").rows).toHaveLength(3);
+  });
+
+  it("selects a row range for a partial export and refuses a range outside the grid", () => {
+    const view = datagridof({
+      title: "grid",
+      origin: "https://example.com",
+      runid: "run-1",
+      rows: [{ a: "1" }, { a: "2" }, { a: "3" }],
+      at: now,
+    });
+    const selected = selectrowrange(view, 1, 2);
+    expect(selected.rows.map((row) => row.selected)).toEqual([false, true, true]);
+    expect(exportrowsof(selected, "selection")).toHaveLength(2);
+    expect(exportrowsof(selected, "run")).toHaveLength(3);
+    expect(() => selectrowrange(view, 2, 1)).toThrow(/range/);
+    expect(() => exportrowsof(view, "selection")).toThrow(/selected row range/);
+  });
+
+  it("offers csv, json and clipboard formats scoped to the selection, the step and the run", () => {
+    const menu = exportmenudescriptors();
+    expect(menu.filter((descriptor) => descriptor.format === "csv")).toHaveLength(3);
+    expect(menu.map((descriptor) => descriptor.scope)).toContain("selection");
+    expect(menu.map((descriptor) => descriptor.scope)).toContain("step");
+    expect(menu.map((descriptor) => descriptor.scope)).toContain("run");
+    expect(
+      menu
+        .filter((descriptor) => descriptor.format === "clipboard")
+        .every((descriptor) => descriptor.destination === "clipboard"),
+    ).toBe(true);
+  });
+
+  it("writes masked values only, honoring the maskinputs verdicts", () => {
+    const view = datagridof({
+      title: "grid",
+      origin: "https://example.com",
+      runid: "run-1",
+      rows: [{ user: "ada", token: "s3cr3tlongvalue" }],
+      at: now,
+    });
+    const maskverdicts = { token: "The token value stays masked and never renders in the clear." };
+    const masked = maskedvalueof("s3cr3tlongvalue", "token", maskverdicts);
+    expect(masked.masked).toBe(true);
+    expect(masked.value).not.toContain("s3cr3t");
+    expect(maskedvalueof("ada", "user", maskverdicts).masked).toBe(false);
+    const csv = exportdatagrid(view, { format: "csv", scope: "run", destination: "download" }, maskverdicts);
+    expect(csv.maskedfields).toEqual(["token"]);
+    expect(csv.text).not.toContain("s3cr3tlongvalue");
+    expect(csv.text).toContain("ada");
+    expect(csv.rows).toBe(1);
+    const json = exportdatagrid(view, { format: "json", scope: "run", destination: "memory" }, maskverdicts);
+    const parsed = JSON.parse(json.text) as {
+      rows: Array<Record<string, unknown>>;
+      columns: Array<{ field: string; type: string }>;
+    };
+    expect(parsed.columns.find((column) => column.field === "user")?.type).toBe("text");
+    expect(String(parsed.rows[0]?.token)).not.toContain("s3cr3t");
+    const clipboard = exportdatagrid(view, { format: "clipboard", scope: "run", destination: "clipboard" }, {});
+    expect(clipboard.text).toContain("s3cr3tlongvalue");
+    expect(clipboard.maskedfields).toEqual([]);
+  });
+});

package/tests/doccheck.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+const execute = promisify(execFile);
+
+/* ── The documentation consistency check coverage. ── */
+
+describe("the documentation consistency artifact", () => {
+  it("declares every check family the gate runs over the documentation", async () => {
+    const source = await readFile("tests/doccheck.mjs", "utf8");
+    for (const family of [
+      "kindcoverage",
+      "kindfields",
+      "kindexamples",
+      "doclinks",
+      "codefences",
+      "referencetables",
+      "flowdiagrams",
+      "changelogcoverage",
+      "roadmapcoverage",
+      "readmeclaims",
+    ])
+      expect(source).toContain(`record("${family}"`);
+    /* the gate reads the compiled catalogs and joins the validate chain after the build */
+    expect(source).toContain("dist/policy.js");
+    expect(source).toContain("dist/index.js");
+    expect(source).toContain("dist/protocol.js");
+    expect(source).toContain("process.exitCode = 1");
+  });
+
+  it("covers every check family with a passing outcome once the gate has run", async () => {
+    const artifactpath = "tests/artifacts/doccheck.json";
+    const built = existsSync("dist/policy.js");
+    const packagejson = JSON.parse(await readFile("package.json", "utf8")) as { version: string };
+    /* a built tree runs the gate itself when no fresh artifact of this release exists, so every lane that builds before the suite verifies the documentation artifact without depending on gate ordering */
+    if (built && !existsSync(artifactpath)) await execute("node", ["tests/doccheck.mjs"]);
+    if (built && existsSync(artifactpath)) {
+      const stored = JSON.parse(await readFile(artifactpath, "utf8")) as { release: string };
+      if (stored.release !== packagejson.version) await execute("node", ["tests/doccheck.mjs"]);
+    }
+    const stored = existsSync(artifactpath);
+    if (built) expect(stored).toBe(true);
+    if (!stored) return;
+    const report = JSON.parse(await readFile(artifactpath, "utf8")) as {
+      release: string;
+      kindcount: number;
+      checks: Array<{ name: string; ok: boolean }>;
+      summary: { total: number; passed: number; failed: number };
+    };
+    expect(report.release).toBe(packagejson.version);
+    expect(report.summary.failed).toBe(0);
+    expect(report.summary.passed).toBe(report.summary.total);
+    expect(report.kindcount).toBeGreaterThan(300);
+    expect(report.checks.map((check) => check.name)).toEqual([
+      "kindcoverage",
+      "kindfields",
+      "kindexamples",
+      "doclinks",
+      "codefences",
+      "referencetables",
+      "flowdiagrams",
+      "changelogcoverage",
+      "roadmapcoverage",
+      "readmeclaims",
+    ]);
+  });
+
+  it("keeps the kind documentation generated from the module surface and the flows mermaid", async () => {
+    const kinddocs = await readFile("docs/kinddocs.md", "utf8");
+    const headings = (kinddocs.match(/^### `([a-z0-9]+)`$/gm) ?? []).length;
+    expect(headings).toBeGreaterThan(300);
+    for (const family of [
+      "## Interaction kinds",
+      "## Observation kinds",
+      "## Navigation kinds",
+      "## Tab and window kinds",
+      "## Form and data kinds",
+      "## Capture kinds",
+      "## Network kinds",
+      "## Debugging kinds",
+      "## Memory kinds",
+      "## Workflow kinds",
+      "## Protocol kinds",
+      "## Coordination kinds",
+    ])
+      expect(kinddocs).toContain(family);
+    const flowdocs = await readFile("docs/flowdocs.md", "utf8");
+    expect((flowdocs.match(/```mermaid/g) ?? []).length).toBeGreaterThanOrEqual(12);
+    const refdocs = await readFile("docs/refdocs.md", "utf8");
+    for (const table of [
+      "## cli command reference",
+      "## protocol message reference",
+      "## error code reference",
+      "## audit event reference",
+      "## configuration key reference",
+      "## storage schema reference",
+      "## capability manifest reference",
+      "## mcp tool reference",
+      "## trigger and scheduler reference",
+      "## permission and consent reference",
+    ])
+      expect(refdocs).toContain(table);
+  });
+});

package/tests/dombatch.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import {
+  batchqueryplanof,
+  batchquerysavings,
+  batchquerytaskof,
+  coalescedombursts,
+  debounceprofilesof,
+  mutationbatchof,
+  runbatchquery,
+} from "../perf.js";
+import { batchqueryplangate, debouncewindowvalid } from "../policy.js";
+
+const now = 1_800_000_000_000;
+
+describe("debouncedom coalescing across event storms", () => {
+  it("builds the debounce profiles of the user configured windows only", () => {
+    const profiles = debounceprofilesof({ scroll: 100, input: 50 });
+    expect(profiles).toEqual([
+      { kind: "scroll", window: 100 },
+      { kind: "input", window: 50 },
+    ]);
+    expect(debounceprofilesof({})).toEqual([]);
+  });
+
+  it("coalesces scroll, input and resize storms per window and closes the batch when the window elapses", () => {
+    const profiles = [
+      { kind: "scroll" as const, window: 100 },
+      { kind: "input" as const, window: 200 },
+    ];
+    const events = [
+      { kind: "scroll" as const, at: now },
+      { kind: "scroll" as const, at: now + 40 },
+      { kind: "scroll" as const, at: now + 80 },
+      { kind: "input" as const, at: now },
+      { kind: "input" as const, at: now + 250 },
+    ];
+    const batches = coalescedombursts({ events, profiles, now: now + 90 });
+    const scroll = batches.find((batch) => batch.kind === "scroll");
+    expect(scroll?.count).toBe(3);
+    expect(scroll?.closed).toBe(false);
+    const inputbatches = batches.filter((batch) => batch.kind === "input");
+    expect(inputbatches).toHaveLength(2);
+    expect(inputbatches[0]?.count).toBe(1);
+    expect(inputbatches[0]?.closed).toBe(true);
+    const closed = coalescedombursts({ events, profiles, now: now + 500 }).filter((batch) => batch.kind === "scroll");
+    expect(closed[0]?.closed).toBe(true);
+  });
+
+  it("debounces one rapid mutation burst of the dom observer into a single batch", () => {
+    const burst = mutationbatchof({
+      mutations: [{ at: now }, { at: now + 5 }, { at: now + 9 }],
+      window: 100,
+      now: now + 10,
+    });
+    expect(burst.kind).toBe("mutation");
+    expect(burst.count).toBe(3);
+    expect(burst.closed).toBe(false);
+    const spread = mutationbatchof({ mutations: [{ at: now }, { at: now + 500 }], window: 100, now: now + 600 });
+    expect(spread.closed).toBe(true);
+    const unbounded = mutationbatchof({ mutations: [{ at: now }, { at: now + 9999 }], now: now + 10000 });
+    expect(unbounded.closed).toBe(true);
+    expect(unbounded.count).toBe(2);
+  });
+
+  it("validates the windows as user choices with no engine default", () => {
+    expect(debouncewindowvalid({ kind: "scroll", window: 100 }).allowed).toBe(true);
+    expect(debouncewindowvalid({ kind: "scroll" }).allowed).toBe(true);
+    expect(debouncewindowvalid({ kind: "scroll" }).reason).toMatch(/pass through uncoalesced/i);
+    expect(debouncewindowvalid({ kind: "input", window: 0 }).allowed).toBe(false);
+    expect(debouncewindowvalid({ kind: "input", window: -5 }).allowed).toBe(false);
+  });
+});
+
+describe("batchquery folding of repeated selectors", () => {
+  it("folds repeated selectors into one pass of distinct selectors", () => {
+    const plan = batchqueryplanof(["#a", "#b", "#a", "#c", "#b", "#a"]);
+    expect(plan.selectors).toEqual(["#a", "#b", "#c"]);
+    expect(plan.folded).toBe(3);
+    expect(plan.onepass).toBe(true);
+    expect(batchqueryplangate(plan).allowed).toBe(true);
+    expect(batchqueryplangate({ selectors: ["#a", "#a"], folded: 0, onepass: true }).allowed).toBe(false);
+    expect(batchqueryplangate({ selectors: ["#a"], folded: 0, onepass: false }).allowed).toBe(false);
+    expect(batchqueryplangate({ selectors: [], folded: 0, onepass: true }).allowed).toBe(false);
+  });
+
+  it("executes the grouped selectors in one pass with one resolver call per distinct selector", () => {
+    const calls: string[] = [];
+    const pass = runbatchquery({
+      plan: batchqueryplanof(["#a", "#b", "#a"]),
+      resolver: (selector) => {
+        calls.push(selector);
+        return `resolved:${selector}`;
+      },
+    });
+    expect(calls).toEqual(["#a", "#b"]);
+    expect(pass.queries).toBe(2);
+    expect(pass.resolutions).toEqual({ "#a": "resolved:#a", "#b": "resolved:#b" });
+    const savings = batchquerysavings(batchqueryplanof(["#a", "#a", "#a"]));
+    expect(savings).toEqual({ distinct: 1, folded: 2, saved: 2 });
+  });
+
+  it("shapes the plan into one offscreen worker task payload", () => {
+    const task = batchquerytaskof({ plan: batchqueryplanof(["#a", "#b", "#a"]), runid: "run1", stepid: "s1" });
+    expect(task.task).toBe("batchquery");
+    expect(task.selectors).toEqual(["#a", "#b"]);
+    expect(task.folded).toBe(1);
+    expect(task.runid).toBe("run1");
+  });
+});

package/tests/emulation.test.ts

@@ -0,0 +1,282 @@
+import { describe, expect, it } from "vitest";
+import {
+  agentgrammarvalid,
+  agentpresetof,
+  applylayer,
+  blackboxmatches,
+  blackboxruleof,
+  blackboxedurls,
+  browserpermissions,
+  devicepresetof,
+  emulationkinds,
+  emulationstateof,
+  expirelayers,
+  exportpresetlibrary,
+  familyofkind,
+  hideblackboxedframes,
+  importpresetlibrary,
+  locationconsentcovers,
+  locationpresetof,
+  locationrangevalid,
+  layernames,
+  networkpresetof,
+  newlayer,
+  permissiongrade,
+  permissiongrantof,
+  permissionstates,
+  revertalllayers,
+  revertlayer,
+  revertplanof,
+  stackedcount,
+} from "../environments.js";
+import type { emulationlayer, stackframe } from "../types.js";
+
+const now = 1_800_000_000_000;
+
+const device = { name: "phone", width: 390, height: 844, pixelratio: 3, mobile: true };
+const network = { name: "slow3g", latency: 400, download: 400, upload: 400, offline: false };
+const location = { name: "lisbon", latitude: 38.7223, longitude: -9.1393, accuracy: 100 };
+const agent = {
+  name: "desktopmask",
+  useragent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+  platform: "Linux x86_64",
+  brands: ["Chromium", "Not A;Brand"],
+};
+
+function layer(id: string, family: emulationlayer["family"], name: string, at: number): emulationlayer {
+  return newlayer({
+    id,
+    runid: "run",
+    stepid: `step-${id}`,
+    family,
+    name,
+    originscope: "https://example.com",
+    revertplan: ["revert the layer", "restore the prior page state"],
+    at,
+  });
+}
+
+describe("emulation presets", () => {
+  it("normalizes the device, network, location and agent presets of the user curated libraries", () => {
+    expect(devicepresetof(device)).toEqual(device);
+    expect(devicepresetof({ name: "", width: 390, height: 844, pixelratio: 3 })).toBeUndefined();
+    expect(devicepresetof({ name: "x", width: 0, height: 844, pixelratio: 3 })).toBeUndefined();
+    expect(devicepresetof({ name: "x", width: 390, height: 844, pixelratio: -1 })).toBeUndefined();
+    expect(devicepresetof({ name: "x", width: 1.5, height: 844, pixelratio: 3 })).toBeUndefined();
+    expect(networkpresetof(network)).toEqual(network);
+    expect(networkpresetof({ name: "x", latency: -1, download: 1, upload: 1 })).toBeUndefined();
+    expect(networkpresetof({ name: "x", latency: 0, download: 0, upload: 0, offline: true })?.offline).toBe(true);
+    expect(locationpresetof(location)).toEqual(location);
+    expect(locationpresetof({ name: "x", latitude: 91, longitude: 0, accuracy: 5 })).toBeUndefined();
+    expect(agentpresetof(agent)).toEqual(agent);
+    expect(agentpresetof({ ...agent, brands: [] })).toBeUndefined();
+    expect(agentpresetof({ ...agent, platform: " " })).toBeUndefined();
+  });
+
+  it("maps every emulation kind onto its layer family", () => {
+    expect(familyofkind("emulatedevice")).toBe("device");
+    expect(familyofkind("emulatenetwork")).toBe("network");
+    expect(familyofkind("emulatelocate")).toBe("location");
+    expect(familyofkind("setuseragent")).toBe("agent");
+    expect(familyofkind("overridepermission")).toBe("permission");
+    expect(familyofkind("blackboxscripts")).toBe("blackbox");
+    expect(familyofkind("click")).toBeUndefined();
+    expect(emulationkinds).toHaveLength(6);
+  });
+});
+
+describe("emulation grammars", () => {
+  it("validates the latitude and longitude ranges of the location layer", () => {
+    expect(locationrangevalid(0, 0)).toBe(true);
+    expect(locationrangevalid(90, 180)).toBe(true);
+    expect(locationrangevalid(-90, -180)).toBe(true);
+    expect(locationrangevalid(90.1, 0)).toBe(false);
+    expect(locationrangevalid(0, -180.1)).toBe(false);
+    expect(locationrangevalid(Number.NaN, 0)).toBe(false);
+  });
+
+  it("validates the user agent string against the reviewed grammar", () => {
+    expect(agentgrammarvalid(agent.useragent)).toBe(true);
+    expect(agentgrammarvalid("curl/8.5.0")).toBe(true);
+    expect(agentgrammarvalid("no version token")).toBe(false);
+    expect(agentgrammarvalid("Mozilla/5.0\r\nX-Injected: 1")).toBe(false);
+    expect(agentgrammarvalid("bad<script>")).toBe(false);
+    expect(agentgrammarvalid("x".repeat(513))).toBe(false);
+  });
+
+  it("validates the permission overrides against the reviewed browser permission set and grades them by name", () => {
+    expect(permissiongrantof({ name: "geolocation", state: "granted", runscope: true })).toEqual({
+      name: "geolocation",
+      state: "granted",
+      runscope: true,
+    });
+    expect(permissiongrantof({ name: "camera", state: "denied" })).toEqual({
+      name: "camera",
+      state: "denied",
+      runscope: true,
+    });
+    expect(permissiongrantof({ name: "screen-capture", state: "granted" })).toBeUndefined();
+    expect(permissiongrantof({ name: "geolocation", state: "maybe" })).toBeUndefined();
+    expect(permissionstates).toEqual(["granted", "denied", "prompt"]);
+    expect(permissiongrade("geolocation")).toBe("powerful");
+    expect(permissiongrade("camera")).toBe("powerful");
+    expect(permissiongrade("microphone")).toBe("powerful");
+    expect(permissiongrade("notifications")).toBe("powerful");
+    expect(permissiongrade("clipboard-write")).toBe("standard");
+    expect(browserpermissions).toContain("geolocation");
+  });
+
+  it("normalizes the blackbox rules and matches third party urls with stars and subtrees", () => {
+    const rule = { urlpatterns: ["https://cdn.example/vendor/**"], tracescope: "both" as const };
+    expect(blackboxruleof(rule)).toEqual(rule);
+    expect(blackboxruleof({ urlpatterns: [], tracescope: "both" })).toBeUndefined();
+    expect(blackboxruleof({ urlpatterns: ["https://cdn.example/**"], tracescope: "everywhere" })).toBeUndefined();
+    expect(blackboxruleof({ urlpatterns: ["https://cdn.example/**"] })).toBeUndefined();
+    expect(blackboxmatches("https://cdn.example/vendor/**", "https://cdn.example/vendor/app.js")).toBe(true);
+    expect(blackboxmatches("https://cdn.example/vendor/**", "https://cdn.example/other.js")).toBe(false);
+    expect(blackboxmatches("https://cdn.example/*", "https://cdn.example/app.js")).toBe(true);
+    expect(blackboxmatches("https://cdn.example/*", "https://cdn.example/nested/app.js")).toBe(false);
+    expect(blackboxmatches("https://cdn.example/**", "https://elsewhere.example/app.js")).toBe(false);
+  });
+
+  it("hides blackboxed frames from stack traces and lists the blackboxed urls of a trace", () => {
+    const frames: stackframe[] = [
+      { url: "https://example.com/app.js", line: 1 },
+      { url: "https://cdn.example/vendor/lib.js", line: 2 },
+      { url: "https://example.com/main.js", line: 3 },
+    ];
+    const traces = [{ urlpatterns: ["https://cdn.example/**"], tracescope: "traces" as const }];
+    expect(hideblackboxedframes(traces, frames)).toEqual([frames[0], frames[2]]);
+    const profiles = [{ urlpatterns: ["https://cdn.example/**"], tracescope: "profiles" as const }];
+    expect(hideblackboxedframes(profiles, frames)).toHaveLength(3);
+    expect(
+      blackboxedurls(
+        [...traces, ...profiles],
+        frames.map((frame) => frame.url),
+      ),
+    ).toEqual(["https://cdn.example/vendor/lib.js"]);
+    expect(hideblackboxedframes([], frames)).toHaveLength(3);
+  });
+
+  it("requires a non-empty reviewed revert plan beside every layer", () => {
+    expect(revertplanof(["detach", "restore the prior state"])).toEqual(["detach", "restore the prior state"]);
+    expect(revertplanof([])).toBeUndefined();
+    expect(revertplanof(["", "  "])).toBeUndefined();
+    expect(revertplanof("detach")).toBeUndefined();
+  });
+});
+
+describe("emulation layers", () => {
+  it("applies and reverts device metric layers with the prior state captured for the exact revert", () => {
+    const state = emulationstateof({ runid: "run", tabid: 4, origin: "https://example.com", now });
+    const withprior = newlayer({
+      id: "l1",
+      runid: "run",
+      stepid: "s1",
+      family: "device",
+      name: "phone",
+      originscope: "https://example.com",
+      revertplan: ["restore the pixel ratio"],
+      prior: { pixelratio: 2, viewportwidth: 1200, viewportheight: 800 },
+      at: now,
+    });
+    const applied = applylayer(state, withprior, now + 10);
+    expect(applied.layers).toHaveLength(1);
+    expect(applied.layers[0]?.prior?.pixelratio).toBe(2);
+    const reverted = revertlayer(applied, "l1", now + 20);
+    expect(reverted.layers[0]?.revertedat).toBe(now + 20);
+    expect(layernames(reverted)).toEqual([]);
+  });
+
+  it("stacks layers with the last applied winning conflicts and reverts them in reverse order", () => {
+    const base = emulationstateof({ runid: "run", tabid: 4, origin: "https://example.com", now });
+    let current = applylayer(base, layer("l1", "device", "phone", now), now + 1);
+    current = applylayer(current, layer("l2", "network", "slow3g", now), now + 2);
+    current = applylayer(current, layer("l3", "agent", "desktopmask", now), now + 3);
+    expect(stackedcount(current)).toBe(3);
+    expect(layernames(current)).toEqual(["phone", "slow3g", "desktopmask"]);
+    const second = applylayer(current, layer("l4", "device", "tablet", now + 5), now + 5);
+    expect(layernames(second)).toEqual(["phone", "slow3g", "desktopmask", "tablet"]);
+    const outcome = revertalllayers(second, now + 30);
+    expect(outcome.reverted.map((entry) => entry.name)).toEqual(["tablet", "desktopmask", "slow3g", "phone"]);
+    expect(layernames(outcome.state)).toEqual([]);
+    expect(stackedcount(outcome.state)).toBe(0);
+  });
+
+  it("keeps the layer history of reverted layers for review", () => {
+    const state = applylayer(
+      emulationstateof({ runid: "run", tabid: 4, origin: "https://example.com", now }),
+      layer("l1", "location", "lisbon", now),
+      now,
+    );
+    const reverted = revertalllayers(state, now + 10);
+    expect(reverted.state.layers).toHaveLength(1);
+    expect(reverted.state.layers[0]?.revertedat).toBe(now + 10);
+  });
+});
+
+describe("emulation retention and presets", () => {
+  it("expires the prior states of reverted layers after the retention window while the history survives", () => {
+    const state = revertalllayers(
+      applylayer(
+        emulationstateof({ runid: "run", tabid: 4, origin: "https://example.com", now }),
+        newlayer({
+          id: "l1",
+          runid: "run",
+          stepid: "s1",
+          family: "agent",
+          name: "desktopmask",
+          originscope: "https://example.com",
+          revertplan: ["restore the agent"],
+          prior: { useragent: "UA" },
+          at: now,
+        }),
+        now,
+      ),
+      now + 10,
+    ).state;
+    expect(expirelayers(state, 1000, now + 100).layers[0]?.prior).toEqual({ useragent: "UA" });
+    const expired = expirelayers(state, 1000, now + 2000);
+    expect(expired.layers[0]?.prior).toBeUndefined();
+    expect(expired.layers[0]?.priorexpired).toBe(true);
+    expect(expired.layers[0]?.name).toBe("desktopmask");
+    expect(expirelayers(state, undefined, now + 100_000).layers[0]?.prior).toEqual({ useragent: "UA" });
+  });
+
+  it("exports and imports the versioned preset library through review", () => {
+    const file = exportpresetlibrary({
+      devices: [device],
+      networks: [network],
+      locations: [location],
+      agents: [agent],
+      now,
+    });
+    expect(file.version).toBe(1);
+    expect(file.devices[0]?.name).toBe("phone");
+    const parsed = importpresetlibrary(JSON.parse(JSON.stringify(file)));
+    expect(parsed?.networks[0]?.name).toBe("slow3g");
+    expect(parsed?.locations[0]?.latitude).toBe(38.7223);
+    expect(importpresetlibrary({ devices: [{ name: "bad", width: 0, height: 0, pixelratio: 1 }] })).toBeUndefined();
+    expect(importpresetlibrary("nope")).toBeUndefined();
+  });
+
+  it("covers the location consent by origin and reviewed coordinates", () => {
+    const consents = [
+      {
+        id: "c1",
+        prompt: "Where?",
+        origin: "https://example.com",
+        latitude: 38.7223,
+        longitude: -9.1393,
+        approved: true,
+        consentedat: now,
+      },
+    ];
+    expect(locationconsentcovers("https://example.com", 38.7223, -9.1393, consents)).toBe(true);
+    expect(locationconsentcovers("https://example.com", 41.3851, 2.1734, consents)).toBe(false);
+    expect(locationconsentcovers("https://elsewhere.example", 38.7223, -9.1393, consents)).toBe(false);
+    expect(locationconsentcovers("https://example.com", 38.7223, -9.1393, [{ ...consents[0]!, approved: false }])).toBe(
+      false,
+    );
+  });
+});