diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/architecture/routing-pages-and-patterns.md
index bb5cfe0c..fdc9a828 100644
--- a/docs/architecture/routing-pages-and-patterns.md
+++ b/docs/architecture/routing-pages-and-patterns.md
@@ -290,6 +290,10 @@ chunk recovery 순서:
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
`onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
+- context가 라우트나 레이아웃을 불러오지 못한 실패: `route_id`는 그 URL의 등록
+ 라우트 id다. 등록 라우트가 없는 URL이면 `UNREGISTERED_ROUTE`다. not-found
+ 화면이 실패한 것이 아니므로 `NOT_FOUND`를 쓰지 않는다(`app-router.tsx`의
+ `failedRouteIdAt`).
- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
(`async-surface.tsx`의 `TerminalErrorSurface`).
diff --git a/src/contracts/routes.ts b/src/contracts/routes.ts
index 8abbad36..e4bcf431 100644
--- a/src/contracts/routes.ts
+++ b/src/contracts/routes.ts
@@ -97,6 +97,14 @@ export const PLATFORM_ROUTE_REGISTRY = Object.freeze({
}),
});
+/**
+ * 1101/14.3. The `route_id` a render failure reports when no registered route
+ * names the URL: a context failed to load at an address none of its routes
+ * has. NOT_FOUND would say the not-found page failed, and a context id is not
+ * a route id, which telemetry drops.
+ */
+export const UNREGISTERED_ROUTE_ID = "UNREGISTERED_ROUTE";
+
/**
* 09-03. Platform routes an installed feature may take over by declaring the
* same route id: a product whose home is a feature screen. The feature's
diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx
index 1ecff079..d391d1a8 100644
--- a/src/presentation/routes/app-router.tsx
+++ b/src/presentation/routes/app-router.tsx
@@ -30,6 +30,7 @@ import {
import {
PLATFORM_ROUTE_REGISTRY,
type RouteDefinition,
+ UNREGISTERED_ROUTE_ID,
} from "../../contracts/routes.ts";
import { TEMPLATE_APP_MODULE } from "../../apps/template-app.ts";
import {
@@ -468,6 +469,18 @@ function registeredRouteIdAt(pathname: string): string | undefined {
return matchRoutes(routes, pathname)?.at(-1)?.route.id;
}
+/**
+ * 1101/14.3. The route a gateway or layout failure is reported under. The
+ * NOT_FOUND splat matches every URL, but there the context failed, not the
+ * not-found page.
+ */
+function failedRouteIdAt(pathname: string): string {
+ const routeId = registeredRouteIdAt(pathname);
+ return routeId === undefined || routeId === "NOT_FOUND"
+ ? UNREGISTERED_ROUTE_ID
+ : routeId;
+}
+
/** The chunk that route recovers, to key chunk recovery on it. */
function routeChunkId(pathname: string): string | undefined {
const routeId = registeredRouteIdAt(pathname);
@@ -567,7 +580,7 @@ function ContextRouteGateway({
buildId={buildId}
onUnrecovered={(incidentId) =>
diagnostics.reportRenderFailure({
- routeId: routeModule.id,
+ routeId: failedRouteIdAt(location.pathname),
buildId,
boundaryName: "route",
incidentId,
@@ -581,7 +594,7 @@ function ContextRouteGateway({
// evaluates, a feature runtime that does not load) escalates to the
// context boundary, which reports it.
withinContext(
- registeredRouteIdAt(location.pathname) ?? routeModule.id,
+ failedRouteIdAt(location.pathname),
,
)
);
@@ -639,7 +652,7 @@ function ContextLayout({
buildId={buildId}
onUnrecovered={(incidentId) =>
diagnostics.reportRenderFailure({
- routeId: registeredRouteIdAt(pathname) ?? "NOT_FOUND",
+ routeId: failedRouteIdAt(pathname),
buildId,
boundaryName: "route",
incidentId,
diff --git a/tests/component/context-boundary-diagnostics.test.tsx b/tests/component/context-boundary-diagnostics.test.tsx
index 23f92f00..b71c1afb 100644
--- a/tests/component/context-boundary-diagnostics.test.tsx
+++ b/tests/component/context-boundary-diagnostics.test.tsx
@@ -3,6 +3,7 @@
import { render, screen } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
+import { projectTelemetryEvent } from "../../src/contracts/telemetry.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
@@ -105,10 +106,11 @@ async function expectReportedFailure(
// React logs every caught render error; the assertions below are the point.
vi.spyOn(console, "error").mockImplementation(() => {});
const record = vi.fn();
+ const emit = vi.fn();
window.history.pushState({}, "", url);
render(
@@ -133,6 +135,9 @@ async function expectReportedFailure(
},
},
]);
+ // The same failure reaches telemetry, which takes route ids only.
+ const [telemetry] = emit.mock.calls.filter(([name]) => name === "ui.render.failed");
+ expect(projectTelemetryEvent(telemetry?.[0], telemetry?.[1])).toMatchObject({ success: true });
}
describe("context gateway failure diagnostics", () => {
@@ -158,9 +163,10 @@ describe("context gateway failure diagnostics", () => {
});
it("reports an unregistered handle refused while the routes load", async () => {
- // No feature route owns this URL; the registry's NOT_FOUND splat does.
+ // 1101/14.3. No registered route names this URL. The context failed, not
+ // the not-found page, so the report must not say NOT_FOUND.
await expectReportedFailure("/fixture/checked", {
- routeId: "NOT_FOUND",
+ routeId: "UNREGISTERED_ROUTE",
boundary: "route",
});
});
diff --git a/tests/component/context-route-gateway.test.tsx b/tests/component/context-route-gateway.test.tsx
index b4cba8d6..8295b0e1 100644
--- a/tests/component/context-route-gateway.test.tsx
+++ b/tests/component/context-route-gateway.test.tsx
@@ -3,6 +3,7 @@
import { act, render, screen, waitFor } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
+import { projectTelemetryEvent } from "../../src/contracts/telemetry.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
@@ -147,4 +148,38 @@ describe("context route gateway", () => {
await screen.findByText("새 버전으로 한 번만 전환합니다."),
).toBeVisible();
});
+
+ // 1101/14.3. Without a new deploy the download stays failed. The report
+ // names the route at the URL, or UNREGISTERED_ROUTE when no route does
+ // (not NOT_FOUND, whose page did not fail), and telemetry takes it: it
+ // accepts route ids only, so the context id was dropped there.
+ it.each([
+ ["/fixture/items/new", "FIXTURE_ITEM_FORM"],
+ ["/fixture/items/new/unknown", "UNREGISTERED_ROUTE"],
+ ])("reports an unrecovered routes-module download at %s as %s", async (url, routeId) => {
+ const record = vi.fn();
+ const emit = vi.fn();
+ window.history.pushState({}, "", url);
+ render(
+
+
+
+
+ ,
+ );
+
+ await screen.findByText(/^지원 참조: build-a:[0-9a-f]{8}$/);
+ expect(record).toHaveBeenCalledWith(
+ expect.objectContaining({
+ eventId: "ui.render.failed",
+ context: expect.objectContaining({ route_id: routeId }),
+ }),
+ );
+ const [telemetry] = emit.mock.calls.filter(([name]) => name === "ui.render.failed");
+ expect(projectTelemetryEvent(telemetry?.[0], telemetry?.[1])).toMatchObject({
+ success: true,
+ });
+ });
});