@neurocode-ai/app 1.18.8

package/e2e/performance/unit/navigation-milestones.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test"
+import { summarizeNavigationMilestones } from "../timeline/navigation-milestones"
+
+test("reports first and stable paint for each navigation milestone", () => {
+  expect(
+    summarizeNavigationMilestones([
+      { observedAtMs: 16, milestones: { content: false, tab: false } },
+      { observedAtMs: 32, milestones: { content: true, tab: false } },
+      { observedAtMs: 48, milestones: { content: true, tab: true } },
+      { observedAtMs: 64, milestones: { content: true, tab: true } },
+      { observedAtMs: 80, milestones: { content: true, tab: true } },
+    ]),
+  ).toEqual({
+    samples: 5,
+    milestones: {
+      content: { firstObservedMs: 32, stableObservedMs: 64 },
+      tab: { firstObservedMs: 48, stableObservedMs: 80 },
+    },
+    all: { firstObservedMs: 48, stableObservedMs: 80 },
+  })
+})
+
+test("reports missing stability when a milestone appears in the final samples", () => {
+  expect(
+    summarizeNavigationMilestones([
+      { observedAtMs: 16, milestones: { content: false } },
+      { observedAtMs: 32, milestones: { content: true } },
+    ]),
+  ).toEqual({
+    samples: 2,
+    milestones: { content: { firstObservedMs: 32, stableObservedMs: null } },
+    all: { firstObservedMs: 32, stableObservedMs: null },
+  })
+})

package/e2e/performance/unit/session-tab-repaint-probe.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test"
+import { compressCachedRepaintTrace, layoutShiftSample } from "../timeline/session-tab-repaint-probe"
+
+test("compresses repeated repaint states without losing frame samples", () => {
+  const state = {
+    root: 1,
+    scrollTop: 10,
+    scrollHeight: 20,
+    bottomErrorPx: 0,
+    last: true,
+    rows: [{ key: "row", node: 2, top: 0, bottom: 10 }],
+    mounted: 1,
+    center: "content",
+  }
+  const trace = {
+    timeOriginEpochMs: 1_000,
+    startedAtPerformanceMs: 100,
+    samples: [
+      { observedAtMs: 16, ...state, destination: ["target"], source: [] },
+      { observedAtMs: 32, ...state, destination: ["target"], source: [] },
+      { observedAtMs: 48, ...state, scrollTop: 11, destination: ["target"], source: [] },
+    ],
+    mutations: [{ observedAtMs: 20, changed: [{ type: "add", node: 2 }] }],
+    shifts: [{ occurredAtMs: 24, value: 0.1 }],
+    windowMs: 1_000,
+    running: false,
+    stop() {},
+  }
+  const compressed = compressCachedRepaintTrace(trace)
+  const samples = compressed.samples.flatMap((group) =>
+    group.observedAtMs.map((observedAtMs) => ({ observedAtMs, ...group.state })),
+  )
+
+  expect(samples).toEqual(trace.samples)
+  expect(compressed.mutations).toEqual(trace.mutations)
+  expect(compressed.shifts).toEqual(trace.shifts)
+})
+
+test("records layout shifts at occurrence time within the probe window", () => {
+  expect(layoutShiftSample({ startTime: 99, value: 0.1 }, 100)).toBeUndefined()
+  expect(layoutShiftSample({ startTime: 124, value: 0.2 }, 100)).toEqual({ occurredAtMs: 24, value: 0.2 })
+})

package/e2e/performance/unit/session-tab-switch-metrics.test.ts

@@ -0,0 +1,86 @@
+import { expect, test } from "bun:test"
+import { classifySessionSwitch } from "../timeline/session-tab-switch-metrics"
+
+test("counts source and blank samples before the destination is observed", () => {
+  const result = classifySessionSwitch([
+    { observedAtMs: 16, destination: [], source: ["source"], hasVisibleRows: true, last: false },
+    { observedAtMs: 32, destination: [], source: [], hasVisibleRows: false, last: false },
+    { observedAtMs: 48, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+    { observedAtMs: 64, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+    { observedAtMs: 80, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+  ])
+
+  expect(result.blankSamples).toBe(1)
+  expect(result.sourceSamples).toBe(1)
+  expect(result.unknownSamples).toBe(0)
+  expect(result.firstDestinationObservedMs).toBe(48)
+  expect(result.stableObservedMs).toBe(80)
+})
+
+test("does not classify mixed source and destination content as correct", () => {
+  const result = classifySessionSwitch([
+    {
+      observedAtMs: 16,
+      destination: ["destination"],
+      source: ["source"],
+      hasVisibleRows: true,
+      last: true,
+      bottomErrorPx: 0,
+    },
+    { observedAtMs: 32, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+    { observedAtMs: 48, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+    { observedAtMs: 64, destination: ["destination"], source: [], hasVisibleRows: true, last: true, bottomErrorPx: 0 },
+  ])
+
+  expect(result.firstCorrectObservedMs).toBe(32)
+  expect(result.stableObservedMs).toBe(64)
+})
+
+test("reports missing correctness without throwing", () => {
+  const result = classifySessionSwitch([
+    {
+      observedAtMs: 16,
+      destination: ["destination"],
+      source: ["source"],
+      hasVisibleRows: true,
+      last: true,
+      bottomErrorPx: 0,
+    },
+  ])
+
+  expect(result.firstDestinationObservedMs).toBe(16)
+  expect(result.firstCorrectObservedMs).toBeNull()
+  expect(result.stableObservedMs).toBeNull()
+})
+
+test("requires an explicitly tracked part to be visible", () => {
+  const result = classifySessionSwitch([
+    {
+      observedAtMs: 16,
+      destination: ["destination"],
+      source: [],
+      hasVisibleRows: true,
+      last: true,
+      requiredPartVisible: false,
+      bottomErrorPx: 0,
+    },
+  ])
+
+  expect(result.firstCorrectObservedMs).toBeNull()
+})
+
+test("can measure content correctness without requiring a bottom anchor", () => {
+  const result = classifySessionSwitch([
+    {
+      observedAtMs: 16,
+      destination: ["destination"],
+      source: [],
+      hasVisibleRows: true,
+      last: true,
+      requiredPartVisible: true,
+      bottomAnchorRequired: false,
+    },
+  ])
+
+  expect(result.firstCorrectObservedMs).toBe(16)
+})

package/e2e/performance/unit/session-tab-switch-probe.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test"
+import type { Page } from "@playwright/test"
+import { measureSessionSwitch } from "../timeline/session-tab-switch-probe"
+
+function testPage(waitFailure?: Error) {
+  const stops: unknown[] = []
+  const page = {
+    evaluate: async (_callback: unknown, input?: unknown) => {
+      if (input) return
+      stops.push(undefined)
+    },
+    waitForFunction: async () => {
+      if (waitFailure) throw waitFailure
+    },
+  } as unknown as Page
+  return { page, stops }
+}
+
+function input(run: () => Promise<void>) {
+  return {
+    destinationIDs: ["destination"],
+    sourceIDs: ["source"],
+    lastID: "destination",
+    href: "/session/destination",
+    switch: run,
+  }
+}
+
+test("stops sampling when the session switch fails", async () => {
+  const failure = new Error("switch failed")
+  const context = testPage()
+
+  await expect(
+    measureSessionSwitch(
+      context.page,
+      input(async () => Promise.reject(failure)),
+    ),
+  ).rejects.toBe(failure)
+
+  expect(context.stops).toHaveLength(1)
+})
+
+test("stops sampling when the stable wait fails", async () => {
+  const failure = new Error("stable wait failed")
+  const context = testPage(failure)
+
+  await expect(
+    measureSessionSwitch(
+      context.page,
+      input(async () => {}),
+    ),
+  ).rejects.toBe(failure)
+
+  expect(context.stops).toHaveLength(1)
+})

package/e2e/performance/unit/session-timeline-stream-probe.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from "bun:test"
+import { streamChunk } from "../timeline/session-timeline-benchmark.fixture"
+import { streamProgress } from "../timeline/session-timeline-stream-probe"
+
+test("classifies emitted stream markers using the fixture cycle", () => {
+  expect(streamProgress("before stream-17 after stream-18")).toEqual({ index: 18, phase: "boundary" })
+  expect(streamProgress("before stream-18 after stream-19")).toEqual({ index: 19, phase: "stream" })
+  expect(streamProgress("benchmark-complete stream-36")).toEqual({ index: 36, phase: "complete" })
+  expect(streamProgress("no marker")).toEqual({ index: -1, phase: "unknown" })
+})
+
+test("emits progress markers at fixture boundaries", () => {
+  expect(streamProgress(streamChunk(18, 160))).toEqual({ index: 18, phase: "boundary" })
+})

package/e2e/performance/unit/session-timeline-visual-tracking.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "bun:test"
+import { layoutShiftValue, removeVisibleRow } from "../timeline/session-timeline-stream-probe"
+
+test("excludes layout shifts before the probe window and recent input", () => {
+  expect(layoutShiftValue({ startTime: 9, value: 0.1 }, 10)).toBeUndefined()
+  expect(layoutShiftValue({ startTime: 10, value: 0.2, hadRecentInput: true }, 10)).toBeUndefined()
+  expect(layoutShiftValue({ startTime: 11, value: 0.3 }, 10)).toBe(0.3)
+})
+
+test("classifies removed rows from their last painted visibility", () => {
+  const row = {}
+  const visible = new Set([row])
+
+  expect(removeVisibleRow(visible, row)).toBe(true)
+  expect(removeVisibleRow(visible, row)).toBe(false)
+})

package/e2e/performance/unit/timeline-test-helpers.test.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "bun:test"
+import { base64Encode } from "@neurocode-ai/core/util/encode"
+import { fixture } from "../timeline/session-timeline-stress.fixture"
+import { stressSessionHref } from "../timeline/timeline-test-helpers"
+
+test("builds stress session links for the benchmark server", () => {
+  expect(stressSessionHref(fixture.sourceID)).toBe(
+    `/server/${base64Encode("http://127.0.0.1:4096")}/session/${fixture.sourceID}`,
+  )
+})

package/e2e/performance/unit/visual-stability.test.ts

@@ -0,0 +1,392 @@
+import { expect, test } from "bun:test"
+import {
+  analyzeVisualStability,
+  analyzeVisualStabilityByMarker,
+  type VisualStabilityTrace,
+} from "../../utils/visual-stability"
+import { analyzeVisualObservations } from "../../utils/visual-stability/analyzer"
+import { legacyVisualPlan, visualPlan, type VisualInvariant } from "../../utils/visual-stability/invariant"
+import { defineVisualRegions, mapVisualRegions } from "../../utils/visual-stability/regions"
+
+function trace(samples: VisualStabilityTrace["samples"]): VisualStabilityTrace {
+  return { markers: [], samples }
+}
+
+test("accepts continuous visible motion", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        frame(0, region({ width: 80, bottom: 40 }), region({ top: 40, bottom: 60 })),
+        frame(16, region({ width: 75, bottom: 45 }), region({ top: 45, bottom: 65 })),
+        frame(32, region({ width: 70, bottom: 50 }), region({ top: 50, bottom: 70 })),
+      ]),
+      { flow: ["changing", "following"] },
+    ),
+  ).toEqual([])
+})
+
+test("reports repeated geometry reversals", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      frame(0, region({ width: 80 })),
+      frame(16, region({ width: 60 })),
+      frame(32, region({ width: 78 })),
+      frame(48, region({ width: 62 })),
+    ]),
+  )
+
+  expect(issues.some((issue) => issue.includes("changing width reversed 2 times"))).toBe(true)
+})
+
+test("reports visible blanking, label reversal, and overlap", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      frame(0, region({ label: "Exploring", opacity: 1, bottom: 40 }), region({ top: 40, bottom: 60 })),
+      frame(16, region({ label: "Explored", opacity: 0.2, bottom: 50 }), region({ top: 49, bottom: 69 })),
+      frame(32, region({ label: "Exploring", opacity: 1, bottom: 50 }), region({ top: 50, bottom: 70 })),
+    ]),
+    { flow: ["changing", "following"] },
+  )
+
+  expect(issues.some((issue) => issue.includes("opacity fell to 0.2"))).toBe(true)
+  expect(issues.some((issue) => issue.includes("label reverted"))).toBe(true)
+  expect(issues.some((issue) => issue.includes("overlapped following by 1px"))).toBe(true)
+})
+
+test("reports duplicate regions and unexpected remounts", () => {
+  const issues = analyzeVisualStability(
+    trace([frame(0, region({ node: 1 })), frame(16, region({ node: 2, count: 2 })), frame(32, region({ node: 2 }))]),
+    { stable: ["changing"], unique: ["changing"] },
+  )
+
+  expect(issues.some((issue) => issue.includes("changing appeared 2 times"))).toBe(true)
+  expect(issues.some((issue) => issue.includes("changing remounted"))).toBe(true)
+})
+
+test("reports bottom anchor loss but permits movement while scrolled away", () => {
+  const anchored = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { changing: region() }, viewport: viewport(0) },
+      { at: 16, regions: { changing: region() }, viewport: viewport(24) },
+    ]),
+    { preserveBottomAnchor: true },
+  )
+  const away = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { changing: region() }, viewport: viewport(80) },
+      { at: 16, regions: { changing: region() }, viewport: viewport(104) },
+    ]),
+    { preserveBottomAnchor: true },
+  )
+
+  expect(anchored.some((issue) => issue.includes("bottom anchor moved to 24px"))).toBe(true)
+  expect(away).toEqual([])
+})
+
+test("reports up down up movement while preserving a bottom anchor", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { changing: region({ top: 200, bottom: 240 }) }, viewport: viewport(0) },
+      { at: 16, regions: { changing: region({ top: 180, bottom: 220 }) }, viewport: viewport(0) },
+      { at: 32, regions: { changing: region({ top: 196, bottom: 236 }) }, viewport: viewport(0) },
+      { at: 48, regions: { changing: region({ top: 176, bottom: 216 }) }, viewport: viewport(0) },
+    ]),
+    { preserveBottomAnchor: true, maxPositionReversals: 0 },
+  )
+
+  expect(issues.some((issue) => issue.includes("changing top reversed 2 times"))).toBe(true)
+  expect(issues.some((issue) => issue.includes("changing bottom reversed 2 times"))).toBe(true)
+})
+
+test("accepts monotonic upward movement while preserving a bottom anchor", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        { at: 0, regions: { changing: region({ top: 200, bottom: 240 }) }, viewport: viewport(0) },
+        { at: 16, regions: { changing: region({ top: 190, bottom: 230 }) }, viewport: viewport(0) },
+        { at: 32, regions: { changing: region({ top: 180, bottom: 220 }) }, viewport: viewport(0) },
+      ]),
+      { preserveBottomAnchor: true, maxPositionReversals: 0 },
+    ),
+  ).toEqual([])
+})
+
+test("ignores overlap entirely outside the clipped timeline viewport", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        {
+          at: 0,
+          regions: {
+            changing: region({ top: -200, bottom: -100 }),
+            following: region({ top: -150, bottom: -50 }),
+          },
+          viewport: viewport(0),
+        },
+      ]),
+      { flow: ["changing", "following"] },
+    ),
+  ).toEqual([])
+})
+
+test("reports visible anchor movement while allowing virtual scrollbar movement", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { anchor: region({ top: 100, bottom: 120 }) }, viewport: { ...viewport(100), scrollTop: 40 } },
+      { at: 16, regions: { anchor: region({ top: 100, bottom: 120 }) }, viewport: { ...viewport(120), scrollTop: 60 } },
+    ]),
+    { fixed: ["anchor"] },
+  )
+
+  expect(issues).toEqual([])
+
+  const moved = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { anchor: region({ top: 100, bottom: 120 }) }, viewport: viewport(100) },
+      { at: 16, regions: { anchor: region({ top: 112, bottom: 132 }) }, viewport: viewport(100) },
+    ]),
+    { fixed: ["anchor"] },
+  )
+  expect(moved.some((issue) => issue.includes("anchor moved 12px in the viewport"))).toBe(true)
+})
+
+test("analyzes each marked event independently", () => {
+  const input: VisualStabilityTrace = {
+    markers: [
+      { at: 10, label: "grow" },
+      { at: 40, label: "shrink" },
+    ],
+    samples: [
+      frame(0, region({ top: 100 })),
+      frame(16, region({ top: 90 })),
+      frame(32, region({ top: 80 })),
+      frame(48, region({ top: 90 })),
+      frame(64, region({ top: 100 })),
+    ],
+  }
+
+  expect(analyzeVisualStability(input, { maxPositionReversals: 0 })).toContain("changing top reversed 1 times")
+  expect(
+    analyzeVisualStabilityByMarker(input, {
+      maxPositionReversals: 0,
+      motion: ["changing"],
+      aggregateMotion: false,
+    }),
+  ).toEqual([])
+})
+
+test("reports cross-event motion reversals by default", () => {
+  const input: VisualStabilityTrace = {
+    markers: [
+      { at: 10, label: "up" },
+      { at: 40, label: "down" },
+    ],
+    samples: [
+      frame(0, region({ top: 100 })),
+      frame(16, region({ top: 90 })),
+      frame(32, region({ top: 80 })),
+      frame(48, region({ top: 90 })),
+      frame(64, region({ top: 100 })),
+    ],
+  }
+
+  expect(analyzeVisualStabilityByMarker(input, { maxPositionReversals: 0 })).toContain("changing top reversed 1 times")
+})
+
+test("reports regions rendered in the wrong flow order", () => {
+  const issues = analyzeVisualStability(
+    trace([frame(0, region({ top: 100, bottom: 120 }), region({ top: 60, bottom: 80 }))]),
+    { flow: ["changing", "following"] },
+  )
+
+  expect(issues.some((issue) => issue.includes("changing rendered after following"))).toBe(true)
+})
+
+test("uses painted bounds instead of clipped layout overflow", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        frame(
+          0,
+          region({ top: 100, bottom: 140, height: 40, layoutTop: 100, layoutBottom: 300 }),
+          region({ top: 140, bottom: 180 }),
+        ),
+      ]),
+      { flow: ["changing", "following"] },
+    ),
+  ).toEqual([])
+})
+
+test("does not report disappearance when a present row moves outside the viewport", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        frame(0, region({ visible: true })),
+        frame(16, region({ visible: false, inViewport: false, top: -100, bottom: -80 })),
+        frame(32, region({ visible: true })),
+      ]),
+    ),
+  ).toEqual([])
+})
+
+test("reports an in-viewport transparent frame between visible frames", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      frame(0, region()),
+      frame(16, region({ visible: false, opacity: 0, inViewport: true })),
+      frame(32, region()),
+    ]),
+  )
+
+  expect(issues.some((issue) => issue.includes("blanked between visible frames"))).toBe(true)
+})
+
+test("reports an in-viewport display-none frame between visible frames", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      frame(0, region()),
+      frame(16, region({ visible: false, width: 0, height: 0, inViewport: true, cssHidden: true })),
+      frame(32, region()),
+    ]),
+  )
+
+  expect(issues.some((issue) => issue.includes("blanked between visible frames"))).toBe(true)
+})
+
+test("can limit motion analysis to unaffected regions", () => {
+  expect(
+    analyzeVisualStability(
+      trace([
+        frame(0, region({ height: 20 }), region()),
+        frame(16, region({ height: 40 }), region()),
+        frame(32, region({ height: 30 }), region()),
+      ]),
+      { motion: ["following"] },
+    ),
+  ).toEqual([])
+})
+
+test("reports a blank frame across replacement surfaces", () => {
+  const issues = analyzeVisualStability(
+    {
+      markers: [],
+      samples: [
+        { at: 0, regions: { thinking: region(), error: region({ present: false, visible: false }) } },
+        {
+          at: 16,
+          regions: {
+            thinking: region({ present: false, visible: false }),
+            error: region({ present: false, visible: false }),
+          },
+        },
+        { at: 32, regions: { thinking: region({ present: false, visible: false }), error: region() } },
+      ],
+    },
+    { continuousAny: [["thinking", "error"]] },
+  )
+
+  expect(issues.some((issue) => issue.includes("thinking | error blanked"))).toBe(true)
+})
+
+test("reports failure to acquire the bottom anchor", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      { at: 0, regions: { changing: region() }, viewport: viewport(600) },
+      { at: 16, regions: { changing: region() }, viewport: viewport(120) },
+    ]),
+    { acquireBottomAnchor: true },
+  )
+
+  expect(issues.some((issue) => issue.includes("did not acquire bottom anchor"))).toBe(true)
+})
+
+test("reports a required region that never renders", () => {
+  const issues = analyzeVisualStability(
+    trace([
+      {
+        at: 0,
+        regions: { changing: region({ present: false, visible: false }) },
+      },
+    ]),
+    { required: ["changing"] },
+  )
+
+  expect(issues).toContain("changing never rendered")
+})
+
+test("preserves typed region names while mapping definitions", () => {
+  const regions = defineVisualRegions({
+    changing: { selector: "[data-changing]" },
+    following: { selector: "[data-following]", closest: "[data-row]" },
+  })
+  const selectors = mapVisualRegions(regions, (region) => region.selector)
+
+  expect(selectors).toEqual({ changing: "[data-changing]", following: "[data-following]" })
+  const name: keyof typeof selectors = "changing"
+  expect(name).toBe("changing")
+})
+
+test("evaluates the typed invariant algebra over explicit observations", () => {
+  const regions = defineVisualRegions({
+    changing: { selector: "[data-changing]" },
+    following: { selector: "[data-following]" },
+  })
+  const invariants = [
+    { type: "required", regions: ["changing"] },
+    { type: "flow", regions: ["changing", "following"] },
+  ] satisfies VisualInvariant<keyof typeof regions>[]
+  // @ts-expect-error Plans reject names that are not in the region definition.
+  const invalid = { type: "required", regions: ["missing"] } satisfies VisualInvariant<keyof typeof regions>
+  const plan = visualPlan(regions, invariants, { perMarker: true })
+
+  expect(invalid.regions).toEqual(["missing"])
+  expect(plan.perMarker).toBe(true)
+  expect(analyzeVisualObservations([frame(0, region({ bottom: 50 }), region({ top: 49, bottom: 69 }))], plan)).toEqual([
+    "changing overlapped following by 1px at 0ms",
+  ])
+})
+
+test("legacy plan adapter preserves analyzer messages and order", () => {
+  const input = trace([
+    frame(0, region({ label: "Exploring", opacity: 1, bottom: 40 }), region({ top: 40, bottom: 60 })),
+    frame(16, region({ label: "Explored", opacity: 0.2, bottom: 50 }), region({ top: 49, bottom: 69 })),
+    frame(32, region({ label: "Exploring", opacity: 1, bottom: 50 }), region({ top: 50, bottom: 70 })),
+  ])
+  const options = { flow: ["changing", "following"], stable: ["changing"] }
+
+  expect(analyzeVisualObservations(input.samples, legacyVisualPlan(options))).toEqual(
+    analyzeVisualStability(input, options),
+  )
+})
+
+function frame(
+  at: number,
+  changing: VisualStabilityTrace["samples"][number]["regions"][string],
+  following?: VisualStabilityTrace["samples"][number]["regions"][string],
+) {
+  return { at, regions: { changing, ...(following ? { following } : {}) } }
+}
+
+function region(input: Partial<VisualStabilityTrace["samples"][number]["regions"][string]> = {}) {
+  return {
+    present: true,
+    visible: true,
+    inViewport: true,
+    top: 0,
+    bottom: 20,
+    width: 100,
+    height: 20,
+    opacity: 1,
+    count: 1,
+    node: 1,
+    label: "",
+    text: "",
+    layoutTop: input.top ?? 0,
+    layoutBottom: input.bottom ?? 20,
+    ...input,
+  }
+}
+
+function viewport(distanceFromBottom: number) {
+  return { top: 0, bottom: 400, scrollTop: 100, scrollHeight: 500, clientHeight: 400, distanceFromBottom }
+}