@remit/web-client 0.0.60 → 0.0.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.60",
+  "version": "0.0.61",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/ui/AppVersion.tsx

@@ -7,7 +7,10 @@ import {
 export interface AppVersionProps {
 	/** Override SHA for testing/Storybook. Defaults to the build-time constant. */
 	sha?: string;
-	/** Override commit URL. Defaults to the GitHub commit link. */
+	/**
+	 * Override commit URL. Defaults to the GitHub commit link, which is undefined
+	 * for a local "dev" build with no real SHA — the version renders unlinked then.
+	 */
 	commitUrl?: string;
 	/** Override build time ISO string. Defaults to the build-time constant. */
 	buildTime?: string;
@@ -35,14 +38,18 @@ export function AppVersion({
 	return (
 		<p className="text-xs text-fg-subtle">
 			Version{" "}
-			<a
-				href={commitUrl}
-				target="_blank"
-				rel="noopener noreferrer"
-				className="font-mono hover:text-fg-muted hover:underline"
-			>
-				{sha}
-			</a>
+			{commitUrl ? (
+				<a
+					href={commitUrl}
+					target="_blank"
+					rel="noopener noreferrer"
+					className="font-mono hover:text-fg-muted hover:underline"
+				>
+					{sha}
+				</a>
+			) : (
+				<span className="font-mono">{sha}</span>
+			)}
 			{" · "}
 			<span>Built {formatBuildTime(buildTime)}</span>
 		</p>

package/src/lib/app-info.ts

@@ -10,6 +10,18 @@ export const APP_BUILD_TIME: string = __APP_BUILD_TIME__;
 /** First 7 characters of the SHA, matching git's default short form. */
 export const APP_SHORT_SHA: string = APP_SHA.slice(0, 7);
 
-export const GITHUB_COMMIT_URL = `https://github.com/remit-mail/reader/commit/${APP_SHA}`;
+/**
+ * True when `APP_SHA` is a real git commit — a build that was given the commit
+ * (via `GITHUB_SHA` at build time). A local build with no git resolves to the
+ * literal "dev", which is not a commit and must not be linked (a
+ * `/commit/dev` URL is a dead link).
+ */
+export const APP_SHA_IS_COMMIT = /^[0-9a-f]{40}$/.test(APP_SHA);
+
+/** Commit URL for the build, or undefined when the build has no real SHA. */
+export const GITHUB_COMMIT_URL: string | undefined = APP_SHA_IS_COMMIT
+	? `https://github.com/remit-mail/reader/commit/${APP_SHA}`
+	: undefined;
+
 export const GITHUB_NEW_ISSUE_URL =
 	"https://github.com/remit-mail/reader/issues/new";

package/src/lib/bug-report.test.ts

@@ -9,10 +9,13 @@ import {
 } from "@remit/ui";
 import type { BugReportContext } from "./bug-report";
 import { buildBugReportDetails, buildGitHubIssueUrl } from "./bug-report";
+import type { RequestBreadcrumb } from "./request-breadcrumbs";
+import type { RouteBreadcrumb } from "./route-breadcrumbs";
 
 const baseCtx: BugReportContext = {
-	appSha: "abcdef1234567890abcdef1234567890abcdef12",
 	appShortSha: "abcdef1",
+	appCommitUrl:
+		"https://github.com/remit-mail/reader/commit/abcdef1234567890abcdef1234567890abcdef12",
 	appBuildTime: "2024-01-15T10:30:00.000Z",
 	userAgent: "Mozilla/5.0 (Test Browser)",
 	viewport: "1440×900",
@@ -20,6 +23,8 @@ const baseCtx: BugReportContext = {
 	timezone: "Europe/Amsterdam",
 	href: "https://app.example.com/mail/inbox?q=test",
 	recentErrors: [],
+	requests: [],
+	routes: [],
 };
 
 /**
@@ -145,6 +150,144 @@ describe("buildGitHubIssueUrl", () => {
 		const url = buildGitHubIssueUrl(ctx);
 		assert.doesNotThrow(() => new URL(url), "URL must be valid");
 	});
+
+	it("links the short SHA to the build commit", () => {
+		const decoded = decode(buildGitHubIssueUrl(baseCtx));
+		assert.ok(
+			decoded.includes(
+				"[`abcdef1`](https://github.com/remit-mail/reader/commit/abcdef1234567890abcdef1234567890abcdef12)",
+			),
+			"Expected the version to link the commit",
+		);
+	});
+
+	it("renders the version unlinked when the build has no real SHA", () => {
+		const decoded = decode(
+			buildGitHubIssueUrl({
+				...baseCtx,
+				appShortSha: "dev",
+				appCommitUrl: undefined,
+			}),
+		);
+		assert.ok(
+			decoded.includes("**Version**: `dev`"),
+			"Expected an unlinked dev version",
+		);
+		assert.ok(
+			!decoded.includes("/commit/dev"),
+			"A dev build must not produce a dead commit link",
+		);
+	});
+});
+
+describe("buildGitHubIssueUrl — request breadcrumbs", () => {
+	const requests: RequestBreadcrumb[] = [
+		{
+			method: "GET",
+			path: "/api/messages/abc-123",
+			status: 200,
+			durationMs: 42,
+			correlationId: "corr-ok",
+			timestamp: "2024-06-12T08:00:01.000Z",
+		},
+		{
+			method: "POST",
+			path: "/api/messages/abc-123/move",
+			status: 500,
+			durationMs: 130,
+			correlationId: "corr-fail",
+			timestamp: "2024-06-12T08:00:02.000Z",
+		},
+	];
+
+	it("renders a table of recent API requests", () => {
+		const decoded = decode(buildGitHubIssueUrl({ ...baseCtx, requests }));
+		assert.ok(decoded.includes("## Recent API requests"));
+		assert.ok(decoded.includes("/api/messages/abc-123/move"));
+		assert.ok(
+			decoded.includes("corr-fail"),
+			"Expected the correlation id in the table",
+		);
+		assert.ok(decoded.includes("| GET |"));
+	});
+
+	it("shows (none) when no requests were captured", () => {
+		const decoded = decode(buildGitHubIssueUrl({ ...baseCtx, requests: [] }));
+		assert.ok(decoded.includes("## Recent API requests"));
+	});
+
+	it("calls out the failing request in its own section", () => {
+		const failingRequest = requests[1];
+		const decoded = decode(
+			buildGitHubIssueUrl({ ...baseCtx, requests, failingRequest }),
+		);
+		assert.ok(decoded.includes("## Failing request"));
+		assert.ok(decoded.includes("**Endpoint**: `/api/messages/abc-123/move`"));
+		assert.ok(decoded.includes("**Method**: POST"));
+		assert.ok(decoded.includes("**Status**: 500"));
+		assert.ok(decoded.includes("**Correlation id**: corr-fail"));
+	});
+
+	it("describes a transport failure as no response", () => {
+		const failingRequest: RequestBreadcrumb = {
+			method: "GET",
+			path: "/api/messages",
+			status: 0,
+			durationMs: 5000,
+			timestamp: "2024-06-12T08:00:03.000Z",
+		};
+		const decoded = decode(buildGitHubIssueUrl({ ...baseCtx, failingRequest }));
+		assert.ok(decoded.includes("no response (transport failure)"));
+		assert.ok(decoded.includes("**Correlation id**: (none)"));
+	});
+
+	it("no breadcrumb ever carries a query string or a body", () => {
+		// A breadcrumb path is redacted at capture (request-breadcrumbs.ts), so
+		// even if the fetch layer saw a `?q=` search or a request body, the
+		// assembled requests table carries neither. Scope the check to that
+		// section — the `## URL` section legitimately keeps the full href.
+		const requestsWithQueryShaped: RequestBreadcrumb[] = [
+			{
+				method: "POST",
+				path: "/api/search",
+				status: 200,
+				durationMs: 5,
+				correlationId: "c1",
+				timestamp: "2024-06-12T08:00:01.000Z",
+			},
+		];
+		const decoded = decode(
+			buildGitHubIssueUrl({ ...baseCtx, requests: requestsWithQueryShaped }),
+		);
+		const section = decoded.slice(decoded.indexOf("## Recent API requests"));
+		assert.ok(
+			!section.includes("?"),
+			"A breadcrumb path must never carry a query string",
+		);
+		assert.ok(
+			!/"password"|"subject"|"body":/.test(section),
+			"A breadcrumb must never carry a request/response body",
+		);
+	});
+});
+
+describe("buildGitHubIssueUrl — navigation trail", () => {
+	const routes: RouteBreadcrumb[] = [
+		{ path: "/mail/inbox", timestamp: "2024-06-12T07:59:58.000Z" },
+		{ path: "/mail/message/abc-123", timestamp: "2024-06-12T08:00:00.000Z" },
+	];
+
+	it("renders the navigation trail so Steps to reproduce has context", () => {
+		const decoded = decode(buildGitHubIssueUrl({ ...baseCtx, routes }));
+		assert.ok(decoded.includes("## Navigation trail"));
+		assert.ok(decoded.includes("/mail/inbox"));
+		assert.ok(decoded.includes("/mail/message/abc-123"));
+	});
+
+	it("still emits the Steps to reproduce template", () => {
+		const decoded = decode(buildGitHubIssueUrl({ ...baseCtx, routes }));
+		assert.ok(decoded.includes("## Steps to reproduce"));
+	});
 });
 
 describe("buildGitHubIssueUrl — seeded from a caught error", () => {

package/src/lib/bug-report.ts

@@ -1,11 +1,17 @@
 import type { QuarantineReportSections } from "@remit/ui";
 import {
 	APP_BUILD_TIME,
-	APP_SHA,
 	APP_SHORT_SHA,
+	GITHUB_COMMIT_URL,
 	GITHUB_NEW_ISSUE_URL,
 } from "./app-info";
 import { getRecentErrors } from "./console-errors";
+import {
+	getFailingRequest,
+	getRecentRequests,
+	type RequestBreadcrumb,
+} from "./request-breadcrumbs";
+import { getRecentRoutes, type RouteBreadcrumb } from "./route-breadcrumbs";
 
 /**
  * A GitHub new-issue URL is capped (~8 KB). We budget below that so the stack
@@ -19,8 +25,9 @@ const TRUNCATION_MARKER =
 	"\n… (truncated — the copy action on this screen has the full report)";
 
 export interface BugReportContext {
-	appSha: string;
 	appShortSha: string;
+	/** Commit URL for the build, or undefined for a local "dev" build (no link). */
+	appCommitUrl?: string;
 	appBuildTime: string;
 	userAgent: string;
 	viewport: string;
@@ -28,6 +35,12 @@ export interface BugReportContext {
 	timezone: string;
 	href: string;
 	recentErrors: readonly string[];
+	/** Recent API calls, metadata only — method/path/status/duration/correlation. */
+	requests: readonly RequestBreadcrumb[];
+	/** Recent in-app navigations, oldest first. */
+	routes: readonly RouteBreadcrumb[];
+	/** The request that most likely triggered the report (transport or >= 400). */
+	failingRequest?: RequestBreadcrumb;
 	/** The message of the error that triggered the report, when seeded from one. */
 	errorMessage?: string;
 	/** The error's stacktrace, when available. */
@@ -56,8 +69,8 @@ export interface BugReportSeed {
 
 export function buildBugReportContext(seed?: BugReportSeed): BugReportContext {
 	return {
-		appSha: APP_SHA,
 		appShortSha: APP_SHORT_SHA,
+		appCommitUrl: GITHUB_COMMIT_URL,
 		appBuildTime: APP_BUILD_TIME,
 		userAgent: navigator.userAgent,
 		viewport: `${window.innerWidth}×${window.innerHeight}`,
@@ -65,6 +78,9 @@ export function buildBugReportContext(seed?: BugReportSeed): BugReportContext {
 		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
 		href: window.location.href,
 		recentErrors: getRecentErrors(),
+		requests: getRecentRequests(),
+		routes: getRecentRoutes(),
+		failingRequest: getFailingRequest(),
 		errorMessage: seed?.errorMessage,
 		stack: seed?.stack,
 		componentStack: seed?.componentStack,
@@ -77,6 +93,59 @@ function fencedBlock(content: string): string {
 	return ["```", content, "```"].join("\n");
 }
 
+/** `2024-06-12T08:00:01.234Z` → `08:00:01` — the wall-clock time, compact. */
+function clockTime(iso: string): string {
+	const match = /T(\d{2}:\d{2}:\d{2})/.exec(iso);
+	return match ? match[1] : iso;
+}
+
+function versionLine(ctx: BugReportContext): string {
+	const version = ctx.appCommitUrl
+		? `[\`${ctx.appShortSha}\`](${ctx.appCommitUrl})`
+		: `\`${ctx.appShortSha}\``;
+	return `- **Version**: ${version} built ${ctx.appBuildTime}`;
+}
+
+function failingRequestSection(request: RequestBreadcrumb): string[] {
+	const status =
+		request.status === 0
+			? "no response (transport failure)"
+			: `${request.status}`;
+	return [
+		"## Failing request",
+		`- **Endpoint**: \`${request.path}\``,
+		`- **Method**: ${request.method}`,
+		`- **Status**: ${status}`,
+		`- **Correlation id**: ${request.correlationId ?? "(none)"}`,
+		"",
+	];
+}
+
+function requestsSection(requests: readonly RequestBreadcrumb[]): string[] {
+	if (requests.length === 0) {
+		return ["## Recent API requests", "(none)", ""];
+	}
+	const rows = requests.map((r) => {
+		const status = r.status === 0 ? "ERR" : `${r.status}`;
+		return `| ${clockTime(r.timestamp)} | ${r.method} | \`${r.path}\` | ${status} | ${r.durationMs}ms | ${r.correlationId ?? ""} |`;
+	});
+	return [
+		"## Recent API requests",
+		"| Time | Method | Path | Status | Duration | Correlation |",
+		"| --- | --- | --- | --- | --- | --- |",
+		...rows,
+		"",
+	];
+}
+
+function navigationSection(routes: readonly RouteBreadcrumb[]): string[] {
+	if (routes.length === 0) {
+		return ["## Navigation trail", "(none)", ""];
+	}
+	const rows = routes.map((r) => `- ${clockTime(r.timestamp)} \`${r.path}\``);
+	return ["## Navigation trail", ...rows, ""];
+}
+
 interface BodyOverrides {
 	stack?: string;
 	/** Replaces the MIME-tree section only; it is fenced after this is applied. */
@@ -94,7 +163,7 @@ function buildIssueBody(
 
 	const lines: string[] = [
 		"## Environment",
-		`- **Version**: [\`${ctx.appShortSha}\`](https://github.com/remit-mail/reader/commit/${ctx.appSha}) built ${ctx.appBuildTime}`,
+		versionLine(ctx),
 		`- **Browser**: ${ctx.userAgent}`,
 		`- **Viewport**: ${ctx.viewport}`,
 		`- **Time**: ${ctx.timestamp} (${ctx.timezone})`,
@@ -108,6 +177,10 @@ function buildIssueBody(
 		lines.push("## Error", ctx.errorMessage, "");
 	}
 
+	if (ctx.failingRequest) {
+		lines.push(...failingRequestSection(ctx.failingRequest));
+	}
+
 	if (ctx.quarantine) {
 		const structure =
 			overrides?.quarantineStructure ?? ctx.quarantine.structure;
@@ -130,6 +203,9 @@ function buildIssueBody(
 		lines.push("## Component stack", fencedBlock(ctx.componentStack), "");
 	}
 
+	lines.push(...requestsSection(ctx.requests));
+	lines.push(...navigationSection(ctx.routes));
+
 	lines.push(
 		"## Recent console errors",
 		errorSection,

package/src/lib/network-error.ts

@@ -15,6 +15,8 @@
  * boundary makes the question decidable and the browser's wording irrelevant.
  */
 
+import { recordRequest } from "./request-breadcrumbs";
+
 /** A request that never reached a server. Always soft — never escalated. */
 export class NetworkError extends Error {
 	constructor(cause: unknown) {
@@ -47,12 +49,26 @@ const isDeliberateAbort = (error: unknown): boolean =>
  * `fetch`, with transport failures tagged. Every app-owned request goes through
  * this — the generated client is configured with it, and the hand-written
  * wrapper calls it — so a `NetworkError` downstream is a fact, not an inference.
+ *
+ * It is also the one place every request is seen, so it records a metadata-only
+ * breadcrumb (method, path, status, duration, correlation id) for bug reports.
+ * A deliberate abort is not a request outcome worth reporting, so it is
+ * re-thrown before any breadcrumb is written.
  */
 export const taggedFetch: typeof fetch = async (input, init) => {
+	const startedAt = performance.now();
 	try {
-		return await fetch(input, init);
+		const response = await fetch(input, init);
+		recordRequest({
+			input,
+			init,
+			response,
+			durationMs: performance.now() - startedAt,
+		});
+		return response;
 	} catch (error) {
 		if (isDeliberateAbort(error)) throw error;
+		recordRequest({ input, init, durationMs: performance.now() - startedAt });
 		throw new NetworkError(error);
 	}
 };

package/src/lib/request-breadcrumbs.test.ts

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import {
+	__resetRequestBreadcrumbs,
+	getFailingRequest,
+	getRecentRequests,
+	recordRequest,
+	requestPath,
+} from "./request-breadcrumbs";
+
+const response = (
+	status: number,
+	headers: Record<string, string> = {},
+): Response => new Response(null, { status, headers });
+
+beforeEach(() => {
+	__resetRequestBreadcrumbs();
+});
+
+describe("requestPath — redaction boundary", () => {
+	it("keeps the pathname and drops the query string", () => {
+		assert.equal(requestPath("/api/search?q=secret+query+text"), "/api/search");
+	});
+
+	it("drops the query on an absolute URL too", () => {
+		assert.equal(
+			requestPath("https://app.example.com/api/messages?q=private"),
+			"/api/messages",
+		);
+	});
+
+	it("drops a hash fragment", () => {
+		assert.equal(requestPath("/api/thing#section"), "/api/thing");
+	});
+
+	it("keeps opaque path ids (already public in the URL section)", () => {
+		assert.equal(
+			requestPath("/api/messages/abc-123-def"),
+			"/api/messages/abc-123-def",
+		);
+	});
+
+	it("accepts a URL instance", () => {
+		assert.equal(
+			requestPath(new URL("https://app.example.com/api/x?q=1")),
+			"/api/x",
+		);
+	});
+
+	it("accepts a Request instance", () => {
+		assert.equal(
+			requestPath(new Request("https://app.example.com/api/y?token=abc")),
+			"/api/y",
+		);
+	});
+});
+
+describe("recordRequest", () => {
+	it("captures metadata only — never the query or the body", () => {
+		recordRequest({
+			input: "/api/search?q=confidential",
+			init: { method: "POST", body: JSON.stringify({ subject: "secret" }) },
+			response: response(200),
+			durationMs: 12.6,
+		});
+		const [entry] = getRecentRequests();
+		assert.equal(entry.method, "POST");
+		assert.equal(entry.path, "/api/search");
+		assert.equal(entry.status, 200);
+		assert.equal(entry.durationMs, 13);
+		// The breadcrumb shape has no body/query field; assert nothing leaked in.
+		const serialized = JSON.stringify(entry);
+		assert.ok(
+			!serialized.includes("confidential"),
+			"query text must not be captured",
+		);
+		assert.ok(
+			!serialized.includes("secret"),
+			"request body must not be captured",
+		);
+	});
+
+	it("defaults the method to GET", () => {
+		recordRequest({
+			input: "/api/thing",
+			response: response(204),
+			durationMs: 1,
+		});
+		assert.equal(getRecentRequests()[0].method, "GET");
+	});
+
+	it("reads the method from a Request instance", () => {
+		recordRequest({
+			input: new Request("https://app.example.com/api/z", { method: "delete" }),
+			response: response(200),
+			durationMs: 1,
+		});
+		assert.equal(getRecentRequests()[0].method, "DELETE");
+	});
+
+	it("records status 0 and no correlation id for a transport failure", () => {
+		recordRequest({ input: "/api/thing", durationMs: 5000 });
+		const [entry] = getRecentRequests();
+		assert.equal(entry.status, 0);
+		assert.equal(entry.correlationId, undefined);
+	});
+
+	it("reads the correlation id from the first present header", () => {
+		recordRequest({
+			input: "/api/a",
+			response: response(200, { "x-request-id": "req-42" }),
+			durationMs: 1,
+		});
+		assert.equal(getRecentRequests()[0].correlationId, "req-42");
+	});
+
+	it("keeps only the last ten requests", () => {
+		for (let i = 0; i < 14; i++) {
+			recordRequest({
+				input: `/api/n/${i}`,
+				response: response(200),
+				durationMs: 1,
+			});
+		}
+		const entries = getRecentRequests();
+		assert.equal(entries.length, 10);
+		assert.equal(entries[0].path, "/api/n/4");
+		assert.equal(entries[9].path, "/api/n/13");
+	});
+});
+
+describe("getFailingRequest", () => {
+	it("returns the most recent HTTP error", () => {
+		recordRequest({ input: "/api/ok", response: response(200), durationMs: 1 });
+		recordRequest({
+			input: "/api/bad",
+			response: response(500),
+			durationMs: 1,
+		});
+		recordRequest({
+			input: "/api/ok2",
+			response: response(200),
+			durationMs: 1,
+		});
+		assert.equal(getFailingRequest()?.path, "/api/bad");
+	});
+
+	it("treats a transport failure as failing", () => {
+		recordRequest({ input: "/api/gone", durationMs: 100 });
+		assert.equal(getFailingRequest()?.status, 0);
+	});
+
+	it("returns undefined when every request succeeded", () => {
+		recordRequest({ input: "/api/ok", response: response(200), durationMs: 1 });
+		recordRequest({
+			input: "/api/ok2",
+			response: response(304),
+			durationMs: 1,
+		});
+		assert.equal(getFailingRequest(), undefined);
+	});
+});

package/src/lib/request-breadcrumbs.ts

@@ -0,0 +1,138 @@
+/**
+ * A constant-size ring of the last few API calls, captured at the one fetch
+ * choke point (`taggedFetch` in network-error.ts). It gives a bug report the
+ * request context that a minified stack cannot: which endpoints were hit, in
+ * what order, and what they returned — plus the correlation id that ties a
+ * failing request to its server-side log line.
+ *
+ * PRIVACY — the issue tracker is public, so a breadcrumb is METADATA ONLY.
+ * Capture records the request method, the URL PATHNAME, the HTTP status, the
+ * duration, and a correlation id. It never records a request or response body,
+ * and never the query string — a search's `?q=` carries the user's query text,
+ * a message fetch's params can carry a subject. `requestPath` strips the query
+ * and hash precisely so none of that can reach the report even when the fetch
+ * layer has the full URL in hand. Opaque path ids (a message id in the path)
+ * are acceptable: they already appear in the report's URL section.
+ *
+ * Capture is cheap by construction — a fixed-size array of small records, no
+ * serialization until a report is assembled.
+ */
+
+export interface RequestBreadcrumb {
+	method: string;
+	/** URL pathname only — never the query string or hash (see file header). */
+	path: string;
+	/** HTTP status, or 0 when the request never reached a server (transport failure). */
+	status: number;
+	durationMs: number;
+	/** Server correlation id from a response header, when the response carried one. */
+	correlationId?: string;
+	timestamp: string;
+}
+
+const MAX_ENTRIES = 10;
+
+const ring: RequestBreadcrumb[] = [];
+
+/**
+ * Response headers that carry a request/trace correlation id, in preference
+ * order. `Headers.get` is case-insensitive, so the lowercase form matches
+ * whatever casing the server sent.
+ */
+const CORRELATION_HEADERS = [
+	"x-correlation-id",
+	"x-request-id",
+	"x-amzn-requestid",
+	"x-amzn-trace-id",
+	"apigw-requestid",
+	"x-trace-id",
+] as const;
+
+/**
+ * The pathname of a request, with the query string and hash discarded. This is
+ * the redaction boundary: it is the only thing that reads the request URL, and
+ * it deliberately keeps nothing but the path so no query text can leak into a
+ * breadcrumb.
+ */
+export function requestPath(input: RequestInfo | URL): string {
+	const raw =
+		typeof input === "string"
+			? input
+			: input instanceof URL
+				? input.href
+				: input.url;
+	try {
+		return new URL(raw, window.location.origin).pathname;
+	} catch {
+		// A non-URL input (rare) still must not leak a query — cut at the first
+		// `?` or `#` and return what precedes it.
+		return raw.split(/[?#]/)[0];
+	}
+}
+
+function requestMethod(input: RequestInfo | URL, init?: RequestInit): string {
+	if (init?.method) return init.method.toUpperCase();
+	if (typeof input !== "string" && !(input instanceof URL) && input.method) {
+		return input.method.toUpperCase();
+	}
+	return "GET";
+}
+
+function correlationIdFrom(response: Response): string | undefined {
+	for (const header of CORRELATION_HEADERS) {
+		const value = response.headers.get(header);
+		if (value) return value;
+	}
+	return undefined;
+}
+
+function push(entry: RequestBreadcrumb): void {
+	ring.push(entry);
+	if (ring.length > MAX_ENTRIES) ring.shift();
+}
+
+/**
+ * Record the outcome of one fetch. Called from `taggedFetch` for both a
+ * completed response and a transport failure (no response, status 0). Only the
+ * metadata listed in `RequestBreadcrumb` is read — never `init.body` or the
+ * response body.
+ */
+export function recordRequest(args: {
+	input: RequestInfo | URL;
+	init?: RequestInit;
+	response?: Response;
+	durationMs: number;
+}): void {
+	const { input, init, response, durationMs } = args;
+	push({
+		method: requestMethod(input, init),
+		path: requestPath(input),
+		status: response?.status ?? 0,
+		durationMs: Math.round(durationMs),
+		correlationId: response ? correlationIdFrom(response) : undefined,
+		timestamp: new Date().toISOString(),
+	});
+}
+
+/** The captured breadcrumbs, oldest first. A copy — callers cannot mutate the ring. */
+export function getRecentRequests(): readonly RequestBreadcrumb[] {
+	return ring.slice();
+}
+
+/**
+ * The most recent request that failed — a transport failure (status 0) or an
+ * HTTP error (>= 400). This is the request a report should call out explicitly,
+ * so nobody has to decode a minified stack to learn what broke.
+ */
+export function getFailingRequest(): RequestBreadcrumb | undefined {
+	for (let i = ring.length - 1; i >= 0; i--) {
+		const entry = ring[i];
+		if (entry.status === 0 || entry.status >= 400) return entry;
+	}
+	return undefined;
+}
+
+/** Test-only: clear the ring. */
+export function __resetRequestBreadcrumbs(): void {
+	ring.length = 0;
+}

package/src/lib/route-breadcrumbs.test.ts

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import {
+	__resetRouteBreadcrumbs,
+	getRecentRoutes,
+	recordRoute,
+} from "./route-breadcrumbs";
+
+beforeEach(() => {
+	__resetRouteBreadcrumbs();
+});
+
+describe("recordRoute", () => {
+	it("captures the pathname with a timestamp", () => {
+		recordRoute("/mail/inbox");
+		const [entry] = getRecentRoutes();
+		assert.equal(entry.path, "/mail/inbox");
+		assert.ok(entry.timestamp);
+	});
+
+	it("strips a query string — never the user's search text", () => {
+		recordRoute("/mail/search?q=confidential");
+		const [entry] = getRecentRoutes();
+		assert.equal(entry.path, "/mail/search");
+		assert.ok(!JSON.stringify(entry).includes("confidential"));
+	});
+
+	it("collapses a repeated navigation to the same path", () => {
+		recordRoute("/mail/inbox");
+		recordRoute("/mail/inbox");
+		assert.equal(getRecentRoutes().length, 1);
+	});
+
+	it("keeps only the last eight navigations", () => {
+		for (let i = 0; i < 12; i++) recordRoute(`/mail/${i}`);
+		const entries = getRecentRoutes();
+		assert.equal(entries.length, 8);
+		assert.equal(entries[0].path, "/mail/4");
+		assert.equal(entries[7].path, "/mail/11");
+	});
+});

package/src/lib/route-breadcrumbs.ts

@@ -0,0 +1,45 @@
+/**
+ * A constant-size ring of the last few in-app navigations, captured from the
+ * router's `onResolved` event (see router.tsx). It gives a bug report a
+ * navigation trail, so "Steps to reproduce" has something concrete even when
+ * the reporter leaves the template blank.
+ *
+ * PRIVACY — like request breadcrumbs, this is METADATA ONLY and the tracker is
+ * public. A route entry is the resolved PATHNAME and a timestamp. The query
+ * string is dropped: a search route's `?q=` carries the user's query text.
+ * Opaque path ids (a message id in the path) are acceptable — they already
+ * appear in the report's URL section.
+ */
+
+export interface RouteBreadcrumb {
+	/** Resolved pathname only — never the query string (see file header). */
+	path: string;
+	timestamp: string;
+}
+
+const MAX_ENTRIES = 8;
+
+const ring: RouteBreadcrumb[] = [];
+
+/**
+ * Record a navigation. `path` is expected to be a pathname; any query or hash
+ * is stripped defensively so a caller passing a full location cannot leak query
+ * text into a breadcrumb.
+ */
+export function recordRoute(path: string): void {
+	const clean = path.split(/[?#]/)[0];
+	const last = ring[ring.length - 1];
+	if (last && last.path === clean) return;
+	ring.push({ path: clean, timestamp: new Date().toISOString() });
+	if (ring.length > MAX_ENTRIES) ring.shift();
+}
+
+/** The captured navigations, oldest first. A copy — callers cannot mutate the ring. */
+export function getRecentRoutes(): readonly RouteBreadcrumb[] {
+	return ring.slice();
+}
+
+/** Test-only: clear the ring. */
+export function __resetRouteBreadcrumbs(): void {
+	ring.length = 0;
+}

package/src/router.tsx

@@ -1,5 +1,6 @@
 import type { QueryClient } from "@tanstack/react-query";
 import { createRouter } from "@tanstack/react-router";
+import { recordRoute } from "./lib/route-breadcrumbs";
 import type { Telemetry } from "./lib/telemetry";
 import { routeTree } from "./routeTree.gen";
 
@@ -19,6 +20,9 @@ export const createAppRouter = (
 
 	router.subscribe("onResolved", (event) => {
 		telemetry.recordPageView(event.toLocation.pathname);
+		// A metadata-only navigation trail for bug reports; pathname only, never
+		// the query string (route-breadcrumbs.ts enforces the redaction).
+		recordRoute(event.toLocation.pathname);
 	});
 
 	return router;