perf(examples): 플랫폼 구성 화면이 제목을 먼저 그리고 실행부 표만 기다린다

문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).

고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
  제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
  snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
  표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
  청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
  실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
  이유), hover 프리페치(키보드·직접 진입에 효과 작음).

위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
  직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
  페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
  약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.

검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
  보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
  eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
  test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
  부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
  LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
  홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
  잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
  feature-runtime·reference-schemas는 제목 뒤에 받는다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
This commit is contained in:
DongHyeonka
2026-11-04 22:59:03 +09:00
parent b0195e3d59
commit d549ceb330
6 changed files with 233 additions and 117 deletions
@@ -119,7 +119,8 @@ Central installed catalogs are aggregation points only:
registry the HTTP executor resolves against, filled as features load
- `installed-feature-runtime-registries.ts`: loads every runtime half and
composes the V2 API registries and contract contributions; the platform
overview route calls it before it renders, the boot never does
overview page calls it after it draws its title (1103/15-01), the boot
never does
- `loaded-feature-runtimes.ts`: the same registries as module constants (top-
level await) for Node scripts, tests and registry governance; nothing under
`src` may import it (`boot-does-not-load-every-feature-runtime`)
@@ -22,8 +22,10 @@ import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest.
*
* The app boot never calls this: at runtime the composition root loads one
* feature at a time when its routes are entered (`installed-feature-adapters.ts`).
* The platform overview route calls it before it renders, and Node scripts and
* tests read the same result through `loaded-feature-runtimes.ts`.
* The platform overview page calls it after it draws its title (1103/15-01:
* awaiting it in the route module added a request round to entering the
* route), and Node scripts and tests read the same result through
* `loaded-feature-runtimes.ts`.
*/
export async function loadInstalledFeatureRuntimeRegistries() {
const runtimes = Object.freeze(
@@ -1,4 +1,4 @@
import { type ComponentType, useEffect, useState } from "react";
import { Suspense, use, useEffect, useState } from "react";
import {
HTTP_EXECUTION_CEILINGS,
@@ -11,7 +11,6 @@ import {
import { SERVER_STATE_PROFILES } from "../../contracts/server-state.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../../features/installed-contract-contributions.ts";
import { ROUTE_REGISTRY } from "../../features/installed-feature-contracts.ts";
import { loadInstalledFeatureRuntimeRegistries } from "../../features/installed-feature-runtime-registries.ts";
import type {
RuntimeCapabilityId,
RuntimeCapabilityStatus,
@@ -21,6 +20,7 @@ import {
Card,
DataTable,
EmptySurface,
LoadingSurface,
PageHeader,
type DataTableColumn,
} from "../design-system/index.ts";
@@ -309,14 +309,71 @@ function buildOperationRows(
);
}
const CONTRACTS_LOADING = "기능 실행부를 불러오고 있습니다.";
/** The summary counts that only the features' runtime halves know. */
function ContractMetrics({
contracts,
}: Readonly<{ contracts: Promise<ComposedContractContributions> }>) {
const composed = use(contracts);
const fixtureContributions = composed.contributions.filter(
(contribution) => contribution.source.kind === "TEMPLATE_FIXTURE",
).length;
return (
<>
<Metric
label="HTTP 오퍼레이션"
value={`${buildOperationRows(composed).length}개`}
/>
<Metric
label="외부 계약 패키지"
value={`${EXPECTED_CONTRACT_SET_PACKAGES.length}개`}
hint={`템플릿 픽스처 ${fixtureContributions}개`}
/>
</>
);
}
function ContractTables({
contracts,
}: Readonly<{ contracts: Promise<ComposedContractContributions> }>) {
const composed = use(contracts);
return (
<>
<DataTable
caption="설치된 HTTP 오퍼레이션"
columns={OPERATION_COLUMNS}
rows={buildOperationRows(composed)}
rowKey={(row) => row.operationId}
empty={
<EmptySurface
title="설치된 HTTP 오퍼레이션이 없습니다."
description="계약 기여물을 추가하면 이 표에 나타납니다."
/>
}
/>
{/* 1101/07-03. Drawn only when a contract skips validation by name. */}
<DataTable
caption="런타임 검증을 생략한 계약"
columns={UNVALIDATED_COLUMNS}
rows={listUnvalidatedPayloads(composed)}
rowKey={(row) => `${row.contractId}.${row.validator}`}
empty={null}
/>
</>
);
}
/**
* 15-01. The page lists every installed HTTP operation, which lives in the
* features' runtime halves. Its route loads them all before it renders
* (`loadPlatformOverviewPage`); the boot never does.
* features' runtime halves; the boot never loads them. 1103/15-01: only the
* parts that read them wait (`contracts`). The title and everything the
* declarations know draw at once, so entering the route costs the page chunk
* alone, not a second request round for every feature's runtime.
*/
export function PlatformOverviewPage({
contracts,
}: Readonly<{ contracts: ComposedContractContributions }>) {
}: Readonly<{ contracts: Promise<ComposedContractContributions> }>) {
const runtime = useApplicationRuntime();
const [release, setRelease] = useState<
Awaited<ReturnType<typeof runtime.getReleaseSummary>> | "failed" | null
@@ -338,16 +395,11 @@ export function PlatformOverviewPage({
}, [runtime]);
const routes = Object.values(ROUTE_REGISTRY);
const operations = buildOperationRows(contracts);
const capabilities = runtime.getCapabilitySnapshot();
const features = runtime.getFeatureSnapshot();
const activeCapabilityCount = capabilities.filter(
(status) => status.active > 0,
).length;
const fixtureContributions =
contracts.contributions.filter(
(contribution) => contribution.source.kind === "TEMPLATE_FIXTURE",
).length;
return (
// 08-07. Example copy is Korean in every locale (outside the catalog).
@@ -413,12 +465,19 @@ export function PlatformOverviewPage({
</header>
<dl className="platform-metric-grid">
<Metric label="라우트" value={`${routes.length}개`} />
<Metric label="HTTP 오퍼레이션" value={`${operations.length}개`} />
<Metric
label="외부 계약 패키지"
value={`${EXPECTED_CONTRACT_SET_PACKAGES.length}개`}
hint={`템플릿 픽스처 ${fixtureContributions}개`}
/>
<Suspense
fallback={
<>
<Metric label="HTTP 오퍼레이션" value="확인 중" />
<Metric
label="외부 계약 패키지"
value={`${EXPECTED_CONTRACT_SET_PACKAGES.length}개`}
/>
</>
}
>
<ContractMetrics contracts={contracts} />
</Suspense>
<Metric
label="선택적 런타임 능력"
value={`${activeCapabilityCount} / ${capabilities.length}`}
@@ -464,26 +523,9 @@ export function PlatformOverviewPage({
포함되지 않습니다. 제품은 픽스처를 지우고 자기 패키지를 고정합니다.
</p>
</header>
<DataTable
caption="설치된 HTTP 오퍼레이션"
columns={OPERATION_COLUMNS}
rows={operations}
rowKey={(row) => row.operationId}
empty={
<EmptySurface
title="설치된 HTTP 오퍼레이션이 없습니다."
description="계약 기여물을 추가하면 이 표에 나타납니다."
/>
}
/>
{/* 1101/07-03. Drawn only when a contract skips validation by name. */}
<DataTable
caption="런타임 검증을 생략한 계약"
columns={UNVALIDATED_COLUMNS}
rows={listUnvalidatedPayloads(contracts)}
rowKey={(row) => `${row.contractId}.${row.validator}`}
empty={null}
/>
<Suspense fallback={<LoadingSurface description={CONTRACTS_LOADING} />}>
<ContractTables contracts={contracts} />
</Suspense>
</section>
<section
@@ -592,15 +634,31 @@ export function PlatformOverviewPage({
);
}
/** The route module: the page bound to the registries it reads. */
export async function loadPlatformOverviewPage(): Promise<
Readonly<{ default: ComponentType }>
> {
const registries = await loadInstalledFeatureRuntimeRegistries();
const contracts = registries.composedContractContributions;
return Object.freeze({
default: function InstalledPlatformOverviewPage() {
return <PlatformOverviewPage contracts={contracts} />;
},
});
let installedContracts: Promise<ComposedContractContributions> | undefined;
/**
* One load shared by both waiting parts and by later visits. The composer is
* imported here too, so its code is not in the page chunk the title waits
* for. A duplicate across features rejects here and reaches the route
* boundary, as it did when the route awaited it; a failed load is dropped so
* the next visit retries.
*/
function loadInstalledContracts(): Promise<ComposedContractContributions> {
if (installedContracts === undefined) {
const loading = import(
"../../features/installed-feature-runtime-registries.ts"
)
.then((module) => module.loadInstalledFeatureRuntimeRegistries())
.then((registries) => registries.composedContractContributions);
loading.catch(() => {
if (installedContracts === loading) installedContracts = undefined;
});
installedContracts = loading;
}
return installedContracts;
}
/** The route module: the page bound to the installed registries. */
export default function InstalledPlatformOverviewPage() {
return <PlatformOverviewPage contracts={loadInstalledContracts()} />;
}
+3 -4
View File
@@ -24,10 +24,9 @@ function runtime(
export const PLATFORM_ROUTE_RUNTIME = {
APP_HOME: runtime("APP_HOME", () => import("../pages/home-page.tsx")),
EXAMPLES_PLATFORM: runtime("EXAMPLES_PLATFORM", () =>
import("../examples/platform-overview-page.tsx").then((module) =>
module.loadPlatformOverviewPage(),
),
EXAMPLES_PLATFORM: runtime(
"EXAMPLES_PLATFORM",
() => import("../examples/platform-overview-page.tsx"),
),
EXAMPLES_UI: runtime(
"EXAMPLES_UI",
@@ -1,9 +1,12 @@
// @vitest-environment jsdom
import { render, screen, waitFor, within } from "@testing-library/react";
import { act, render, screen, waitFor, within } from "@testing-library/react";
import { describe, expect, it } from "vitest";
import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts";
import {
composeContractContributions,
type ComposedContractContributions,
} from "../../src/contracts/external-contract-runtime.ts";
import { unvalidatedPayload } from "../../src/contracts/unvalidated-payload.ts";
import { SERVER_STATE_PROFILES } from "../../src/contracts/server-state.ts";
import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../../src/features/loaded-feature-runtimes.ts";
@@ -24,14 +27,31 @@ import { createRuntimeCapabilitiesStub } from "../helpers/runtime-capabilities-s
* template that removes its sample feature still satisfies this suite.
*/
function renderPage() {
return render(
<ApplicationProvider application={createTestApplication()}>
<LocaleProvider>
<PlatformOverviewPage contracts={COMPOSED_CONTRACT_CONTRIBUTIONS} />
</LocaleProvider>
</ApplicationProvider>,
);
/**
* 1103/15-01. The contract tables wait for the features' runtime halves
* behind their own Suspense boundary; `act` lets the given promise settle.
*/
async function renderPage(
options: Readonly<{
application?: ReturnType<typeof createTestApplication>;
contracts?: ComposedContractContributions;
}> = {},
) {
await act(async () => {
render(
<ApplicationProvider
application={options.application ?? createTestApplication()}
>
<LocaleProvider>
<PlatformOverviewPage
contracts={Promise.resolve(
options.contracts ?? COMPOSED_CONTRACT_CONTRIBUTIONS,
)}
/>
</LocaleProvider>
</ApplicationProvider>,
);
});
}
function tableByCaption(caption: string): HTMLElement {
@@ -48,8 +68,8 @@ function metricByLabel(scope: HTMLElement, label: string): HTMLElement {
}
describe("platform overview page", () => {
it("renders one route row per installed route registry entry", () => {
renderPage();
it("renders one route row per installed route registry entry", async () => {
await renderPage();
const table = tableByCaption("설치된 라우트 목록");
const dataRows = within(table).getAllByRole("row").slice(1);
@@ -62,11 +82,11 @@ describe("platform overview page", () => {
}
});
it("renders one operation row per installed HTTP contract", () => {
it("renders one operation row per installed HTTP contract", async () => {
const operationIds = [
...COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.keys(),
];
renderPage();
await renderPage();
if (operationIds.length === 0) {
expect(
@@ -87,7 +107,7 @@ describe("platform overview page", () => {
});
// 1101/07-03. A skipped validation is shown, not just composed.
it("lists the operations that skip runtime validation, with the reason", () => {
it("lists the operations that skip runtime validation, with the reason", async () => {
const [listRow, ...rest] = TEST_CONTRACT_CONTRIBUTION.http;
const contracts = composeContractContributions([
Object.freeze({
@@ -107,13 +127,7 @@ describe("platform overview page", () => {
]),
}),
]);
render(
<ApplicationProvider application={createTestApplication()}>
<LocaleProvider>
<PlatformOverviewPage contracts={contracts} />
</LocaleProvider>
</ApplicationProvider>,
);
await renderPage({ contracts });
const table = tableByCaption("런타임 검증을 생략한 계약");
const [row, ...others] = within(table).getAllByRole("row").slice(1);
@@ -122,16 +136,16 @@ describe("platform overview page", () => {
expect(within(row!).getByText("typed by the package")).toBeVisible();
});
it("shows no skipped-validation list when every operation validates", () => {
renderPage();
it("shows no skipped-validation list when every operation validates", async () => {
await renderPage();
expect(
screen.queryByRole("table", { name: "런타임 검증을 생략한 계약" }),
).toBeNull();
});
it("renders every fixed server-state profile with its own budget", () => {
renderPage();
it("renders every fixed server-state profile with its own budget", async () => {
await renderPage();
const table = tableByCaption("서버 상태 프로파일");
for (const profile of Object.values(SERVER_STATE_PROFILES)) {
@@ -142,8 +156,8 @@ describe("platform overview page", () => {
);
});
it("labels a capability that was never selected as unselected", () => {
renderPage();
it("labels a capability that was never selected as unselected", async () => {
await renderPage();
const region = screen.getByRole("region", { name: "선택적 런타임 능력" });
@@ -151,21 +165,15 @@ describe("platform overview page", () => {
expect(within(region).queryByText("운영자가 비활성화함")).toBeNull();
});
it("separates an operator disable from a capability that was never selected", () => {
render(
<ApplicationProvider
application={createTestApplication({
runtimeCapabilities: createRuntimeCapabilitiesStub({
SERVICE_WORKER: { selected: 1, active: 0, override: "DISABLED" },
OFFLINE_COMMANDS: { selected: 1, active: 1 },
}),
})}
>
<LocaleProvider>
<PlatformOverviewPage contracts={COMPOSED_CONTRACT_CONTRIBUTIONS} />
</LocaleProvider>
</ApplicationProvider>,
);
it("separates an operator disable from a capability that was never selected", async () => {
await renderPage({
application: createTestApplication({
runtimeCapabilities: createRuntimeCapabilitiesStub({
SERVICE_WORKER: { selected: 1, active: 0, override: "DISABLED" },
OFFLINE_COMMANDS: { selected: 1, active: 1 },
}),
}),
});
const region = screen.getByRole("region", { name: "선택적 런타임 능력" });
@@ -174,11 +182,11 @@ describe("platform overview page", () => {
expect(within(region).getAllByText("미선택")).toHaveLength(2);
});
it("counts installed contract packages separately from template fixtures", () => {
it("counts installed contract packages separately from template fixtures", async () => {
const fixtures = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.filter(
(contribution) => contribution.source.kind === "TEMPLATE_FIXTURE",
).length;
renderPage();
await renderPage();
const summary = screen.getByRole("region", { name: "설치 요약" });
const packages = metricByLabel(summary, "외부 계약 패키지");
@@ -199,7 +207,7 @@ describe("platform overview page", () => {
});
it("renders the verified release identity once the runtime resolves it", async () => {
renderPage();
await renderPage();
const region = screen.getByRole("region", { name: "릴리스 신원" });
await waitFor(() =>
@@ -213,24 +221,18 @@ describe("platform overview page", () => {
});
it("stops the release metrics from loading forever", async () => {
render(
<ApplicationProvider
application={createTestApplication({
releaseInfo: {
getCurrent: async () => {
throw new Error("manifest unavailable");
},
refresh: async () => {
throw new Error("manifest unavailable");
},
await renderPage({
application: createTestApplication({
releaseInfo: {
getCurrent: async () => {
throw new Error("manifest unavailable");
},
})}
>
<LocaleProvider>
<PlatformOverviewPage contracts={COMPOSED_CONTRACT_CONTRIBUTIONS} />
</LocaleProvider>
</ApplicationProvider>,
);
refresh: async () => {
throw new Error("manifest unavailable");
},
},
}),
});
await waitFor(() =>
expect(
screen.getByText("런타임 정보를 확인하지 못했습니다."),
@@ -0,0 +1,54 @@
// @vitest-environment jsdom
import { render, screen, within } from "@testing-library/react";
import { Suspense } from "react";
import { describe, expect, it, vi } from "vitest";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PLATFORM_ROUTE_RUNTIME } from "../../src/presentation/routes/route-runtime.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
// The feature runtimes never arrive: the route must not wait for them.
vi.mock("../../src/features/installed-feature-runtime-registries.ts", () => ({
loadInstalledFeatureRuntimeRegistries: () => new Promise(() => {}),
}));
/**
* 1103/15-01. The lab gate (FE-GATE-026) times this route from the click to
* its heading. Its route module used to await every installed feature's
* runtime half first, which added a second request round to the click.
*/
describe("platform overview route module", () => {
it("draws the title and the declared routes before the feature runtimes load", async () => {
const Page = PLATFORM_ROUTE_RUNTIME.EXAMPLES_PLATFORM.Component;
render(
<ApplicationProvider application={createTestApplication()}>
<LocaleProvider>
<Suspense fallback={<p>route chunk</p>}>
<Page />
</Suspense>
</LocaleProvider>
</ApplicationProvider>,
);
expect(
await screen.findByRole("heading", { level: 1, name: "플랫폼 구성" }),
).toBeVisible();
const routes = screen.getByRole("table", { name: "설치된 라우트 목록" });
expect(within(routes).getAllByRole("row").slice(1)).toHaveLength(
Object.keys(ROUTE_REGISTRY).length,
);
// Only the part read from the runtime halves waits.
const contracts = screen.getByRole("region", {
name: "계약과 HTTP 오퍼레이션",
});
expect(
within(contracts).getByLabelText("기능 실행부를 불러오고 있습니다."),
).toBeVisible();
expect(
screen.queryByRole("table", { name: "설치된 HTTP 오퍼레이션" }),
).toBeNull();
});
});