From b0195e3d59f385512f87aba9b5e411900669c449 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Wed, 4 Nov 2026 20:18:40 +0900
Subject: [PATCH 1/5] =?UTF-8?q?ci(visual):=20=EB=B8=8C=EB=9D=BC=EC=9A=B0?=
=?UTF-8?q?=EC=A0=80=20=EC=84=A4=EC=B9=98=20=EB=8B=A8=EA=B3=84=EA=B0=80=20?=
=?UTF-8?q?=EC=8B=9C=EA=B0=81=20=ED=85=8C=EC=8A=A4=ED=8A=B8=20=EA=B8=80?=
=?UTF-8?q?=EA=BC=B4=20=ED=8C=A8=ED=82=A4=EC=A7=80=EB=A5=BC=20=EC=84=A4?=
=?UTF-8?q?=EC=B9=98=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제
tests/visual/fonts.conf는 Noto Sans·Noto Sans CJK·Liberation Mono가
있는 OS 글꼴 디렉터리만 읽는다. 생성 workflow의 브라우저 설치 단계는
`playwright install --with-deps` 한 줄이고, Playwright 의존 패키지에는
이 글꼴이 없다. 그래서 빈 러너에서는 FE-GATE-008이 코드와 무관하게
`visual-fonts` 단계에서 실패한다(1101/11-02의 남은 절반).
고른 방법
- 생성기(scripts/generate-ci-workflow.ts)의 browser-install 단계가
`--with-deps` 뒤에 글꼴 패키지 4개를 apt-get으로 설치한다.
`--with-deps`가 이미 패키지 목록을 갱신했으므로 update를 다시 하지
않는다. root가 아닌 러너에서만 sudo를 붙인다.
- 패키지 목록을 scripts/lib/visual-test-fonts.ts 한 곳에 두고 생성기와
tests/visual/fonts.setup.ts의 설치 안내가 같이 읽는다.
- 글꼴이 필요한 것은 FE-GATE-008뿐이지만 브라우저 단계 두 곳 모두에
넣었다. 게이트 ID로 갈라 쓰면 생성기가 게이트 목록에 묶인다.
- 버린 대안: job container 고정(러너의 컨테이너 지원 미확인),
ci:gate가 패키지 설치(개발자 PC에서도 sudo 요구).
위험·한계
- 실제 러너나 깨끗한 Ubuntu 24.04 컨테이너에서 이 단계를 돌리지
않았다. 패키지 이름과 디렉터리는 이 호스트(Ubuntu)와 fonts.conf로만
확인했다.
- CJK 패키지 때문에 브라우저 job 설치 시간이 수십 MB만큼 는다.
- gates.json은 바꾸지 않았다(단계 종류는 그대로 browser-install).
검증
- ci-workflow-generation 새 테스트: 생성기 수정 전 실패, 수정 뒤 통과.
파일 전체 424건 통과(스냅샷 1건 갱신).
- generate:ci-workflow로 workflow 재생성. check:ci PASS.
- lint, check:types:node, check:types:test, verify:documentation PASS.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-02
---
.gitea/workflows/quality-gates.yml | 8 ++++--
.../frontend-platform-testing-strategy.md | 5 +++-
scripts/generate-ci-workflow.ts | 8 +++++-
scripts/lib/visual-test-fonts.ts | 16 +++++++++++
.../ci-workflow-generation.test.ts.snap | 8 ++++--
tests/unit/ci-workflow-generation.test.ts | 27 +++++++++++++++++++
tests/visual/fonts.setup.ts | 4 ++-
7 files changed, 69 insertions(+), 7 deletions(-)
create mode 100644 scripts/lib/visual-test-fonts.ts
diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml
index 9542cd79..3841d543 100644
--- a/.gitea/workflows/quality-gates.yml
+++ b/.gitea/workflows/quality-gates.yml
@@ -67,7 +67,9 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Install Playwright browsers
if: ${{ matrix.browser }}
- run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ run: |
+ corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ $(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload merge gate evidence
@@ -104,7 +106,9 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Install Playwright browsers
if: ${{ matrix.browser }}
- run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ run: |
+ corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ $(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload release gate evidence
diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md
index f0ea21ab..e262a2ae 100644
--- a/docs/testing/frontend-platform-testing-strategy.md
+++ b/docs/testing/frontend-platform-testing-strategy.md
@@ -955,7 +955,10 @@ Playwright `toHaveScreenshot()`을 사용한다.
- browser 버전과 viewport·scale은 `playwright.visual.config.ts`로, 글꼴은
`tests/visual/fonts.conf`로 고정(Linux 전용). 러너에는
`fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`
- 패키지가 필요하고, 없으면 `visual-fonts` 검사가 설치 명령을 보여 주며 실패한다
+ 패키지가 필요하고, 없으면 `visual-fonts` 검사가 설치 명령을 보여 주며 실패한다.
+ CI의 브라우저 설치 단계가 같은 패키지를 설치한다. 목록은
+ `scripts/lib/visual-test-fonts.ts` 한 곳에 있고 생성기와 `visual-fonts` 검사가
+ 같이 읽는다(1103/11-02)
- animation/caret 비활성화
- clock/random/network fixture 고정
- 개인정보와 동적 ID mask
diff --git a/scripts/generate-ci-workflow.ts b/scripts/generate-ci-workflow.ts
index b37d8b58..66e68ddb 100644
--- a/scripts/generate-ci-workflow.ts
+++ b/scripts/generate-ci-workflow.ts
@@ -23,6 +23,7 @@ import {
assertSafePublishLeaf,
ensureSafePublishDirectory,
} from "./lib/ci-gate-log.ts";
+import { VISUAL_TEST_FONT_INSTALL_ARGUMENTS } from "./lib/visual-test-fonts.ts";
export type GenerateCiWorkflowOptions = Readonly<{
root: string;
@@ -196,7 +197,12 @@ function renderStep(
return [
" - name: Install Playwright browsers",
...(job.kind === "gate-matrix" ? [" if: ${{ matrix.browser }}"] : []),
- " run: corepack pnpm exec playwright install --with-deps chromium firefox webkit",
+ " run: |",
+ " corepack pnpm exec playwright install --with-deps chromium firefox webkit",
+ // 1103/11-02. The visual goldens' faces (tests/visual/fonts.conf) are
+ // not among Playwright's dependencies. `--with-deps` has refreshed the
+ // package lists; sudo only where the runner is not root.
+ ` $(command -v sudo || true) ${VISUAL_TEST_FONT_INSTALL_ARGUMENTS}`,
];
case "run-gate": {
if (job.kind === "gate-matrix") {
diff --git a/scripts/lib/visual-test-fonts.ts b/scripts/lib/visual-test-fonts.ts
new file mode 100644
index 00000000..f689f3fa
--- /dev/null
+++ b/scripts/lib/visual-test-fonts.ts
@@ -0,0 +1,16 @@
+/**
+ * 1103/11-02. The Debian/Ubuntu packages that hold the four faces the visual
+ * goldens were captured with. `tests/visual/fonts.conf` shows Chromium only
+ * their directories, Playwright's `--with-deps` does not install them, and
+ * `tests/visual/fonts.setup.ts` fails with this list when one is missing. The
+ * CI browser step (`scripts/generate-ci-workflow.ts`) installs the same list,
+ * so the hint and the runner cannot name different packages.
+ */
+export const VISUAL_TEST_FONT_PACKAGES = Object.freeze([
+ "fonts-noto-core",
+ "fonts-noto-cjk",
+ "fonts-noto-cjk-extra",
+ "fonts-liberation",
+] as const);
+
+export const VISUAL_TEST_FONT_INSTALL_ARGUMENTS = `apt-get install -y ${VISUAL_TEST_FONT_PACKAGES.join(" ")}`;
diff --git a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap
index 6ff0f0d1..a7f51531 100644
--- a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap
+++ b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap
@@ -70,7 +70,9 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Install Playwright browsers
if: \${{ matrix.browser }}
- run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ run: |
+ corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ $(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
- name: Run blocking gate
run: corepack pnpm ci:gate -- \${{ matrix.gate }}
- name: Upload merge gate evidence
@@ -107,7 +109,9 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Install Playwright browsers
if: \${{ matrix.browser }}
- run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ run: |
+ corepack pnpm exec playwright install --with-deps chromium firefox webkit
+ $(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
- name: Run blocking gate
run: corepack pnpm ci:gate -- \${{ matrix.gate }}
- name: Upload release gate evidence
diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts
index 1fa8fb94..b30c6de1 100644
--- a/tests/unit/ci-workflow-generation.test.ts
+++ b/tests/unit/ci-workflow-generation.test.ts
@@ -28,6 +28,7 @@ import {
validateInstallScriptPolicy,
validatePackageScriptGraph,
} from "../../scripts/lib/package-script-graph.ts";
+import { VISUAL_TEST_FONT_PACKAGES } from "../../scripts/lib/visual-test-fonts.ts";
const temporaryRoots: string[] = [];
const npmPostScriptForeignScopeCommands = [
@@ -1646,6 +1647,32 @@ describe("CI workflow generation", () => {
expect(actionUses.every((uses) => /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@[0-9a-f]{40}$/u.test(uses!))).toBe(true);
});
+ // 1103/11-02. tests/visual/fonts.conf reads the goldens' faces from OS
+ // packages that Playwright's own dependencies do not include, so a clean
+ // runner failed FE-GATE-008 at `visual-fonts`. Every browser step installs
+ // them, after `--with-deps` has refreshed the package lists.
+ it("installs the visual-test font packages in every browser step", async () => {
+ const workflow = renderCiWorkflow(await loadCiGateContract(process.cwd()));
+ const browserSteps = workflow
+ .split(" - name: ")
+ .filter((step) => step.startsWith("Install Playwright browsers"));
+ expect(browserSteps).toHaveLength(2);
+ for (const step of browserSteps) {
+ const playwright = step.indexOf("playwright install --with-deps");
+ const fonts = step.indexOf(
+ `apt-get install -y ${VISUAL_TEST_FONT_PACKAGES.join(" ")}`,
+ );
+ expect(playwright).toBeGreaterThan(0);
+ expect(fonts).toBeGreaterThan(playwright);
+ }
+ expect(VISUAL_TEST_FONT_PACKAGES).toEqual([
+ "fonts-noto-core",
+ "fonts-noto-cjk",
+ "fonts-noto-cjk-extra",
+ "fonts-liberation",
+ ]);
+ });
+
// 12-01: main is the integration branch; a push there must run the gates.
it("runs on pushes to main", async () => {
const workflow = renderCiWorkflow(await loadCiGateContract(process.cwd()));
diff --git a/tests/visual/fonts.setup.ts b/tests/visual/fonts.setup.ts
index 70775bff..db03d79f 100644
--- a/tests/visual/fonts.setup.ts
+++ b/tests/visual/fonts.setup.ts
@@ -3,6 +3,7 @@ import {
test,
type Page,
} from "../support/browser/strict-browser-test.ts";
+import { VISUAL_TEST_FONT_INSTALL_ARGUMENTS } from "../../scripts/lib/visual-test-fonts.ts";
// 11-02. The goldens were captured with these four faces. `fonts.conf` shows
// Chromium only the directories that hold them; this check runs before the
@@ -18,7 +19,8 @@ const expectedFaces = {
const installHint = [
"Visual tests must draw with the fonts the goldens were captured with.",
- "Debian/Ubuntu: sudo apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation",
+ // 1103/11-02. The CI browser step installs the same list.
+ `Debian/Ubuntu: sudo ${VISUAL_TEST_FONT_INSTALL_ARGUMENTS}`,
"tests/visual/fonts.conf reads them from the Debian/Ubuntu font directories; other OSes have no Linux goldens.",
].join("\n");
From d549ceb330b1c1281f57e041367b93e9dca40e17 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Wed, 4 Nov 2026 20:31:30 +0900
Subject: [PATCH 2/5] =?UTF-8?q?perf(examples):=20=ED=94=8C=EB=9E=AB?=
=?UTF-8?q?=ED=8F=BC=20=EA=B5=AC=EC=84=B1=20=ED=99=94=EB=A9=B4=EC=9D=B4=20?=
=?UTF-8?q?=EC=A0=9C=EB=AA=A9=EC=9D=84=20=EB=A8=BC=EC=A0=80=20=EA=B7=B8?=
=?UTF-8?q?=EB=A6=AC=EA=B3=A0=20=EC=8B=A4=ED=96=89=EB=B6=80=20=ED=91=9C?=
=?UTF-8?q?=EB=A7=8C=20=EA=B8=B0=EB=8B=A4=EB=A6=B0=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제
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
---
.../frontend-application-foundation.md | 3 +-
.../installed-feature-runtime-registries.ts | 6 +-
.../examples/platform-overview-page.tsx | 152 ++++++++++++------
src/presentation/routes/route-runtime.tsx | 7 +-
.../starter-platform-overview-page.test.tsx | 128 +++++++--------
.../starter-platform-overview-route.test.tsx | 54 +++++++
6 files changed, 233 insertions(+), 117 deletions(-)
create mode 100644 tests/component/starter-platform-overview-route.test.tsx
diff --git a/docs/architecture/frontend-application-foundation.md b/docs/architecture/frontend-application-foundation.md
index d9fe275e..d722cb20 100644
--- a/docs/architecture/frontend-application-foundation.md
+++ b/docs/architecture/frontend-application-foundation.md
@@ -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`)
diff --git a/src/features/installed-feature-runtime-registries.ts b/src/features/installed-feature-runtime-registries.ts
index 1404c147..7c02ea78 100644
--- a/src/features/installed-feature-runtime-registries.ts
+++ b/src/features/installed-feature-runtime-registries.ts
@@ -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(
diff --git a/src/presentation/examples/platform-overview-page.tsx b/src/presentation/examples/platform-overview-page.tsx
index 86d5250b..1cf80f90 100644
--- a/src/presentation/examples/platform-overview-page.tsx
+++ b/src/presentation/examples/platform-overview-page.tsx
@@ -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 }>) {
+ const composed = use(contracts);
+ const fixtureContributions = composed.contributions.filter(
+ (contribution) => contribution.source.kind === "TEMPLATE_FIXTURE",
+ ).length;
+ return (
+ <>
+
+
+ >
+ );
+}
+
+function ContractTables({
+ contracts,
+}: Readonly<{ contracts: Promise }>) {
+ const composed = use(contracts);
+ return (
+ <>
+ row.operationId}
+ empty={
+
+ }
+ />
+ {/* 1101/07-03. Drawn only when a contract skips validation by name. */}
+ `${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 }>) {
const runtime = useApplicationRuntime();
const [release, setRelease] = useState<
Awaited> | "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({
-
-
+
+
+
+ >
+ }
+ >
+
+
- row.operationId}
- empty={
-
- }
- />
- {/* 1101/07-03. Drawn only when a contract skips validation by name. */}
- `${row.contractId}.${row.validator}`}
- empty={null}
- />
+ }>
+
+
-> {
- const registries = await loadInstalledFeatureRuntimeRegistries();
- const contracts = registries.composedContractContributions;
- return Object.freeze({
- default: function InstalledPlatformOverviewPage() {
- return ;
- },
- });
+let installedContracts: Promise | 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 {
+ 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 ;
}
diff --git a/src/presentation/routes/route-runtime.tsx b/src/presentation/routes/route-runtime.tsx
index 69dfb550..8ae93a40 100644
--- a/src/presentation/routes/route-runtime.tsx
+++ b/src/presentation/routes/route-runtime.tsx
@@ -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",
diff --git a/tests/component/starter-platform-overview-page.test.tsx b/tests/component/starter-platform-overview-page.test.tsx
index 1c043b16..3484238c 100644
--- a/tests/component/starter-platform-overview-page.test.tsx
+++ b/tests/component/starter-platform-overview-page.test.tsx
@@ -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(
-
-
-
-
- ,
- );
+/**
+ * 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;
+ contracts?: ComposedContractContributions;
+ }> = {},
+) {
+ await act(async () => {
+ render(
+
+
+
+
+ ,
+ );
+ });
}
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(
-
-
-
-
- ,
- );
+ 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(
-
-
-
-
- ,
- );
+ 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(
- {
- throw new Error("manifest unavailable");
- },
- refresh: async () => {
- throw new Error("manifest unavailable");
- },
+ await renderPage({
+ application: createTestApplication({
+ releaseInfo: {
+ getCurrent: async () => {
+ throw new Error("manifest unavailable");
},
- })}
- >
-
-
-
- ,
- );
+ refresh: async () => {
+ throw new Error("manifest unavailable");
+ },
+ },
+ }),
+ });
await waitFor(() =>
expect(
screen.getByText("런타임 정보를 확인하지 못했습니다."),
diff --git a/tests/component/starter-platform-overview-route.test.tsx b/tests/component/starter-platform-overview-route.test.tsx
new file mode 100644
index 00000000..a6fad087
--- /dev/null
+++ b/tests/component/starter-platform-overview-route.test.tsx
@@ -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(
+
+
+ route chunk
}>
+
+
+
+ ,
+ );
+
+ 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();
+ });
+});
From 7f633106bbb745d653011b98ae392fc5416e0e57 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Wed, 4 Nov 2026 20:38:12 +0900
Subject: [PATCH 3/5] =?UTF-8?q?test(a11y):=20=EC=A0=91=EA=B7=BC=EC=84=B1?=
=?UTF-8?q?=20e2e=EA=B0=80=20=EA=B8=B0=EB=8A=A5=20API=EB=A5=BC=20descripto?=
=?UTF-8?q?r=20=EB=AA=A8=EC=96=91=EC=9D=98=20=EB=B9=88=20=EB=AA=A9?=
=?UTF-8?q?=EB=A1=9D=EC=9C=BC=EB=A1=9C=20=EB=8B=B5=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.
고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
접근성 spec 생성(파일·실행 시간 증가).
위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
"passed"로 적힌다.
검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
---
docs/accessibility/manual-checklist.md | 9 +-
docs/architecture/starter-experience.md | 2 +-
docs/manual/01-add-a-feature.md | 20 ++--
docs/manual/03-outside-feature-folder.md | 4 +-
docs/manual/reference/create-feature.md | 2 +-
tests/e2e/accessibility.spec.ts | 49 +++++++++-
tests/e2e/support/installed-api-answers.ts | 63 +++++++++++++
tests/mocks/handlers/http-scenarios.ts | 3 +-
tests/unit/a11y-api-answers.test.ts | 103 +++++++++++++++++++++
9 files changed, 228 insertions(+), 27 deletions(-)
create mode 100644 tests/e2e/support/installed-api-answers.ts
create mode 100644 tests/unit/a11y-api-answers.test.ts
diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md
index 8dad35c9..2e4158db 100644
--- a/docs/accessibility/manual-checklist.md
+++ b/docs/accessibility/manual-checklist.md
@@ -68,8 +68,13 @@ What the automated run scans:
never lands on the app shell's loading surface
(`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
catalog title.
-- Protected routes after the demo sign-in, never the sign-in prompt. Their API
- calls answer an empty list there.
+- Protected routes after the demo sign-in, never the sign-in prompt. A list
+ read answers an empty list in the frame its descriptor declares (inside the
+ Envelope for `responseEnvelope: "ENVELOPE_V1"`), and the scan runs only once
+ no alert box is on screen, so a list page is scanned in its empty state. A
+ read of one resource (a detail page) has no generic answer: that route is
+ scanned in its failure state and the run records an `a11y-data-state`
+ annotation.
- The reference sample's list in its success, empty and error states, its
detail, its form with submit errors and its status page, each after that
state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the
diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md
index 0a4512dc..bf356b57 100644
--- a/docs/architecture/starter-experience.md
+++ b/docs/architecture/starter-experience.md
@@ -185,7 +185,7 @@ Files outside the feature directory. Everything else a feature needs is in
| `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` |
| `src/contexts//context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` |
| `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release |
-| `tests/e2e/accessibility.spec.ts` | a route path has a parameter other than `:resourceId`, or a protected page cannot render while every API answers `[]` | `test:a11y` (FE-GATE-009): the spec fills in only `:resourceId` and answers every API with `[]` |
+| `tests/e2e/accessibility.spec.ts` | never per feature (1103/16-03): it fills every path parameter with one value and answers each API request from the installed descriptor, a list read with an empty list in its `responseEnvelope` frame. Edit it only for a protected page that sends something other than an installed GET before it renders | `test:a11y` (FE-GATE-009): a request no installed GET declares fails the route; so does an alert box (`role="alert"`) on a page that read only lists |
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from `composeProductSessionOwner` instead of installing it on the host global before boot | `check:types`; at runtime `feature needs , which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` |
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile, or a product runtime-config key and its FE-REG-ENV row (`PRODUCT_ENV_REGISTRY`) | auth profile: every gate that loads the operation, with `REST security profiles are incoherent for : unknown authProfileId …`. Config key: `check:types` where it is read. FE-REG-ENV row: `check:registries` checks its fields; nothing requires the row |
| `config/runtime/.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing |
diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md
index 8382286d..44b7bba7 100644
--- a/docs/manual/01-add-a-feature.md
+++ b/docs/manual/01-add-a-feature.md
@@ -389,20 +389,12 @@ projectRequest: (input) => Object.freeze({
- 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다.
- 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다.
- `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`).
-- 경로 파라미터 이름이 `:resourceId`가 아니면 `tests/e2e/accessibility.spec.ts`의 치환 줄에 `.replace`를 하나 잇는다.
-
- ```ts
- // 지금
- : definition.path.replace(":resourceId", "reference-1");
- // 예: 공지 기능의 /notice/items/:noticeId
- : definition.path.replace(":resourceId", "reference-1").replace(":noticeId", "notice-1");
- ```
-
- - 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 `:resourceId`만 실제 값으로 바꾼다.
- - 안 고치면 `:noticeId`라는 글자가 그대로 id로 들어간다. 파라미터 스키마가 그 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사한다.
- - 값은 아무 문자열이나 된다. 이 spec은 모든 API에 `[]`로 답해서 상세 페이지는 실패 상태로 그려진다.
+- `tests/e2e/accessibility.spec.ts`는 기능마다 고치지 않는다(1103/16-03).
+ - 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두 `a11y-1`로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다.
+ - API 요청은 설치된 descriptor에서 method와 `pathTemplate`으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope)으로 답한다. 그 뒤 경고 상자(`role="alert"`)가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다.
+ - 한 자원을 읽는 조회(경로 파라미터가 있고 빈 목록을 받지 않는 GET)에는 빈 목록 말고 답할 것이 없다. 그래서 상세 페이지는 실패 상태로 그려지고, 테스트 결과에 `a11y-data-state` annotation이 남는다.
+ - 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(`requests no installed list or single-resource read answers`).
- spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
- - 이 줄은 기능 ID를 담지 않는다. 그래서 제거 드릴(11단계)이 잡지 못한다. 기능을 지울 때 손으로 지운다([03 문서](03-outside-feature-folder.md#기능을-지울-때)).
- 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다.
③ **잡는 검사 / 못 잡는 것**
@@ -605,7 +597,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
- 남은 파일이 기능 ID나 폴더 이름을 담고 있으면 실패한다.
- 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: `
-- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `tests/e2e/accessibility.spec.ts`에 더한 파라미터 치환(6단계), `artifacts/tests/a11y-manual/.md`. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
+- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md
index 1c13012f..3dc4ecdd 100644
--- a/docs/manual/03-outside-feature-folder.md
+++ b/docs/manual/03-outside-feature-folder.md
@@ -101,7 +101,7 @@ release admission refused for staging:
언제와 실패 메시지는 정본 표에 있다. 여기에는 무엇을 위해 고치는지만 적는다.
- `src/contexts//context-layout.tsx`: context가 `AppShell` 대신 자기 틀을 쓸 때. 예제: `tests/helpers/fixture-layout-product.tsx`.
-- `tests/e2e/accessibility.spec.ts`: 경로 파라미터가 `:resourceId`가 아닐 때, 또는 모든 API가 `[]`를 답하면 그려지지 않는 보호 페이지일 때. 치환 줄 고치는 법은 [01 문서 6단계](01-add-a-feature.md#6단계-라우트).
+- `tests/e2e/accessibility.spec.ts`: 기능마다 고치지 않는다. 경로 파라미터와 API 응답을 설치된 라우트·descriptor에서 만든다. 보호 페이지가 설치된 GET이 아닌 요청을 그리기 전에 보낼 때만 손본다. 자세한 동작은 [01 문서 6단계](01-add-a-feature.md#6단계-라우트).
- `src/bootstrap/product-composition.ts`: `needs`에 템플릿이 만들지 않는 capability를 적었을 때. 제품 인증 프로필의 자격 증명도 여기서 준다.
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
@@ -141,8 +141,6 @@ release admission refused for staging:
- `artifacts/tests/a11y-manual/.md` (라우트마다)
- 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다.
- 기능 전용 `tests/e2e/` spec
-- `tests/e2e/accessibility.spec.ts`에 더한 `.replace(":<파라미터>", "<값>")`
- - 기능 ID를 담지 않아 제거 드릴이 잡지 못한다. 남아도 어떤 검사도 실패하지 않는다.
- `config/runtime/.json`의 `FEATURE_OVERRIDES` 키
- `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행
- 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성
diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md
index 5e26a4bb..a5586105 100644
--- a/docs/manual/reference/create-feature.md
+++ b/docs/manual/reference/create-feature.md
@@ -73,7 +73,7 @@ corepack pnpm create:feature [--context ] [--package @scope/nam
- GET 1개: `SAFE`, `EXTERNAL_BEARER`, 응답은 항목 배열.
- 쿼리 1개: `LIST_STANDARD` profile.
- 무효화 topic 1개, namespace 1개, edge 1개.
-- 빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`가 모든 API에 `[]`를 답하기 때문이다.
+- 빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`는 이 목록 조회에 빈 목록을 Envelope 모양으로 답하고, 경고 상자가 없는지 본 뒤 axe를 돌린다. 그래서 생성한 라우트는 빈 상태 화면으로 검사된다.
한도·마감 같은 숫자는 `scripts/create-feature.ts`의 템플릿이 정본이다.
diff --git a/tests/e2e/accessibility.spec.ts b/tests/e2e/accessibility.spec.ts
index 23c00bdc..189069fd 100644
--- a/tests/e2e/accessibility.spec.ts
+++ b/tests/e2e/accessibility.spec.ts
@@ -1,8 +1,13 @@
import AxeBuilder from "@axe-core/playwright";
import { expect, test, type Page } from "../support/browser/strict-browser-test.ts";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
+import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../../src/features/loaded-feature-runtimes.ts";
import type { RouteDefinition } from "../../src/contracts/routes.ts";
import { KO_MESSAGES } from "../../src/presentation/i18n/catalog.ts";
+import {
+ answerInstalledApiRequest,
+ type InstalledApiAnswer,
+} from "./support/installed-api-answers.ts";
const WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
const SIGN_IN_TITLE = KO_MESSAGES["route.auth.required.title"];
@@ -22,25 +27,59 @@ async function blockingViolations(page: Page) {
// Widened: without an installed feature every route is public, and the
// `session-required` branch must still typecheck (sample removal).
const ROUTES: readonly RouteDefinition[] = Object.values(ROUTE_REGISTRY);
+// 1103/16-03. Every path parameter gets one value: a feature with its own
+// parameter names needs no edit here.
+const PATH_PARAMETER_VALUE = "a11y-1";
+const API_ORIGIN = "http://localhost:8080";
for (const definition of ROUTES) {
const route =
definition.path === "*"
? "/not-found"
- : definition.path.replace(":resourceId", "reference-1");
+ : definition.path.replace(/:[A-Za-z][A-Za-z0-9_]*/gu, PATH_PARAMETER_VALUE);
test(`@a11y ${route} has no critical or serious axe violations`, async ({
page,
}) => {
const heading = page.getByRole("heading", { level: 1 });
if (definition.access === "session-required") {
- // Feature data is not this spec's subject: any API answers an empty list.
- await page.route("http://localhost:8080/api/**", (request) =>
- request.fulfill({ json: [] }),
- );
+ // 1103/11-01. Feature data is not this spec's subject: a list read gets
+ // an empty list in the frame its descriptor declares, so the page is
+ // scanned in its empty state, not on a response-shape error.
+ const answers: InstalledApiAnswer[] = [];
+ await page.route(`${API_ORIGIN}/**`, (request) => {
+ const answer = answerInstalledApiRequest(
+ COMPOSED_CONTRACT_CONTRIBUTIONS,
+ request.request().method(),
+ new URL(request.request().url()).pathname,
+ );
+ answers.push(answer);
+ return answer.kind === "unanswerable"
+ ? request.fulfill({ status: 501, body: answer.reason ?? answer.request })
+ : request.fulfill({ json: answer.body });
+ });
await page.goto(route);
await expect(heading).toHaveText(SIGN_IN_TITLE);
await page.getByRole("button", { name: "로그인 시작" }).click();
await expect(heading).toBeVisible();
await expect(heading).not.toHaveText(SIGN_IN_TITLE);
+ await expect(page.locator("[aria-busy='true']")).toHaveCount(0);
+ expect(
+ answers.filter((answer) => answer.kind === "unanswerable"),
+ "requests no installed list or single-resource read answers",
+ ).toEqual([]);
+ const singleResourceReads = answers.flatMap((answer) =>
+ answer.kind === "single-resource" ? [answer.operationId] : [],
+ );
+ if (singleResourceReads.length === 0) {
+ // A shape the page does not read fails here, before axe passes it.
+ await expect(page.getByRole("alert")).toHaveCount(0);
+ } else {
+ // No generic body answers a read of one resource: a detail page is
+ // scanned in its failure state, and the report says which.
+ test.info().annotations.push({
+ type: "a11y-data-state",
+ description: `failure state: ${singleResourceReads.join(", ")} reads one resource`,
+ });
+ }
} else {
await page.goto(route);
const title = CATALOG[`route.${definition.routeId}.title`];
diff --git a/tests/e2e/support/installed-api-answers.ts b/tests/e2e/support/installed-api-answers.ts
new file mode 100644
index 00000000..8895f10f
--- /dev/null
+++ b/tests/e2e/support/installed-api-answers.ts
@@ -0,0 +1,63 @@
+import type { ComposedContractContributions } from "../../../src/contracts/external-contract-runtime.ts";
+import { successEnvelope } from "../../mocks/handlers/http-scenarios.ts";
+
+/**
+ * 1103/11-01, 16-03. What `tests/e2e/accessibility.spec.ts` answers a
+ * protected page's API request with. Feature data is not that spec's subject,
+ * so a list read gets an empty list, framed the way the operation's own
+ * descriptor declares: inside the paired backend's Envelope for
+ * `responseEnvelope: "ENVELOPE_V1"`, bare otherwise. A global bare `[]` put
+ * every Envelope feature on the mismatch error screen and still passed.
+ *
+ * The request is matched to an installed GET by method and `pathTemplate`, so
+ * a new feature needs no edit here. A read with a path parameter whose payload
+ * is not a list (a detail page) cannot be answered with an empty list: the
+ * spec renders it in its failure state and says so. Any other request fails
+ * the spec instead of drawing an error screen that passes.
+ */
+export type InstalledApiAnswer =
+ | Readonly<{ kind: "empty-list"; operationId: string; body: unknown }>
+ | Readonly<{ kind: "single-resource"; operationId: string; body: unknown }>
+ | Readonly<{ kind: "unanswerable"; request: string; reason?: string }>;
+
+const EMPTY_LIST: readonly never[] = Object.freeze([]);
+
+function templatePattern(pathTemplate: string): RegExp {
+ const pattern = pathTemplate
+ .split(/\{[^}]+\}/u)
+ .map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+ .join("[^/]+");
+ return new RegExp(`^${pattern}$`, "u");
+}
+
+export function answerInstalledApiRequest(
+ contracts: ComposedContractContributions,
+ method: string,
+ pathname: string,
+): InstalledApiAnswer {
+ const request = `${method} ${pathname}`;
+ for (const { contract } of contracts.httpByOperationId.values()) {
+ if (contract.method !== method || contract.method !== "GET") continue;
+ if (!templatePattern(contract.pathTemplate).test(pathname)) continue;
+ const body =
+ contract.responseEnvelope === "ENVELOPE_V1"
+ ? successEnvelope([])
+ : EMPTY_LIST;
+ if (contract.outputValidator.safeParse(EMPTY_LIST).success) {
+ return Object.freeze({ kind: "empty-list", operationId: contract.operationId, body });
+ }
+ if (contract.pathTemplate.includes("{")) {
+ return Object.freeze({
+ kind: "single-resource",
+ operationId: contract.operationId,
+ body,
+ });
+ }
+ return Object.freeze({
+ kind: "unanswerable",
+ request,
+ reason: `${contract.operationId} reads no single resource and rejects an empty list`,
+ });
+ }
+ return Object.freeze({ kind: "unanswerable", request });
+}
diff --git a/tests/mocks/handlers/http-scenarios.ts b/tests/mocks/handlers/http-scenarios.ts
index 89b4b5a3..c88c57f1 100644
--- a/tests/mocks/handlers/http-scenarios.ts
+++ b/tests/mocks/handlers/http-scenarios.ts
@@ -169,7 +169,8 @@ const ENVELOPE_META = Object.freeze({
traceId: "0af7651916cd43dd8448eb211c80319c",
});
-function successEnvelope(data: JsonBodyType) {
+/** Also the accessibility e2e's answer (`tests/e2e/support/installed-api-answers.ts`). */
+export function successEnvelope(data: JsonBodyType) {
return Object.freeze({
success: true,
...(data === null ? {} : { data }),
diff --git a/tests/unit/a11y-api-answers.test.ts b/tests/unit/a11y-api-answers.test.ts
new file mode 100644
index 00000000..3b1f633b
--- /dev/null
+++ b/tests/unit/a11y-api-answers.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+
+import { readSuccessEnvelope } from "../../src/adapters/http/backend-envelope.ts";
+import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts";
+import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../../src/features/loaded-feature-runtimes.ts";
+import { answerInstalledApiRequest } from "../e2e/support/installed-api-answers.ts";
+import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts";
+
+/**
+ * 1103/11-01, 16-03. The accessibility e2e answers a protected page's API
+ * requests from the installed descriptors: an empty list in the frame the
+ * operation declares. A global bare `[]` put every Envelope feature on the
+ * mismatch error screen and still passed.
+ */
+const [LIST, GET, CREATE] = TEST_CONTRACT_CONTRIBUTION.http;
+
+function composed(responseEnvelope?: "ENVELOPE_V1") {
+ return composeContractContributions([
+ Object.freeze({
+ ...TEST_CONTRACT_CONTRIBUTION,
+ http: Object.freeze(
+ [LIST!, GET!, CREATE!].map((installed) =>
+ responseEnvelope === undefined
+ ? installed
+ : Object.freeze({
+ ...installed,
+ contract: Object.freeze({ ...installed.contract, responseEnvelope }),
+ }),
+ ),
+ ),
+ }),
+ ]);
+}
+
+describe("accessibility e2e API answers", () => {
+ it("answers a DTO list read with a bare empty list", () => {
+ expect(answerInstalledApiRequest(composed(), "GET", "/api/test-entities")).toEqual({
+ kind: "empty-list",
+ operationId: "TEST_LIST_ENTITIES",
+ body: [],
+ });
+ });
+
+ it("answers an Envelope list read with an empty list inside the Envelope", () => {
+ const answer = answerInstalledApiRequest(
+ composed("ENVELOPE_V1"),
+ "GET",
+ "/api/test-entities",
+ );
+ expect(answer.kind).toBe("empty-list");
+ if (answer.kind !== "empty-list") return;
+ // What the executor reads out of the frame is what the operation accepts.
+ expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] });
+ expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true);
+ });
+
+ it("names a single-resource read, which no empty list can answer", () => {
+ expect(
+ answerInstalledApiRequest(composed("ENVELOPE_V1"), "GET", "/api/test-entities/a11y-1"),
+ ).toMatchObject({ kind: "single-resource", operationId: "TEST_GET_ENTITY" });
+ });
+
+ it("refuses a request no installed read declares", () => {
+ expect(
+ answerInstalledApiRequest(composed(), "POST", "/api/test-entities"),
+ ).toEqual({ kind: "unanswerable", request: "POST /api/test-entities" });
+ expect(
+ answerInstalledApiRequest(composed(), "GET", "/api/elsewhere"),
+ ).toEqual({ kind: "unanswerable", request: "GET /api/elsewhere" });
+ });
+
+ it("refuses a parameterless read whose payload is not a list", () => {
+ const pagedOnly = composeContractContributions([
+ Object.freeze({
+ ...TEST_CONTRACT_CONTRIBUTION,
+ http: Object.freeze([
+ Object.freeze({
+ ...GET!,
+ contract: Object.freeze({
+ ...GET!.contract,
+ operationId: "TEST_PAGED_ENTITIES",
+ pathTemplate: "/api/paged-entities",
+ }),
+ }),
+ ]),
+ }),
+ ]);
+ expect(answerInstalledApiRequest(pagedOnly, "GET", "/api/paged-entities")).toEqual({
+ kind: "unanswerable",
+ request: "GET /api/paged-entities",
+ reason: "TEST_PAGED_ENTITIES reads no single resource and rejects an empty list",
+ });
+ });
+
+ it("can answer every parameterless read the installed features declare", () => {
+ for (const { contract } of COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.values()) {
+ if (contract.method !== "GET" || contract.pathTemplate.includes("{")) continue;
+ expect(
+ answerInstalledApiRequest(COMPOSED_CONTRACT_CONTRIBUTIONS, "GET", contract.pathTemplate),
+ ).toMatchObject({ kind: "empty-list", operationId: contract.operationId });
+ }
+ });
+});
From b96d61d8f773855257b66d219e1ea2c33059fcb9 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Wed, 4 Nov 2026 21:49:41 +0900
Subject: [PATCH 4/5] =?UTF-8?q?feat(examples)!:=20=EC=98=88=EC=A0=9C=20?=
=?UTF-8?q?=ED=99=94=EB=A9=B4=203=EA=B0=9C=EB=A5=BC=20=EB=81=8C=20?=
=?UTF-8?q?=EC=88=98=20=EC=9E=88=EB=8A=94=20=EA=B8=B0=EB=8A=A5=EC=9C=BC?=
=?UTF-8?q?=EB=A1=9C=20=EC=98=AE=EA=B8=B4=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
---
.../VD-06-intl-typed-message-catalog.md | 7 +-
docs/architecture/starter-experience.md | 34 +++++--
eslint.config.ts | 13 ++-
public/release-manifest.json | 6 +-
scripts/check-i18n.ts | 5 +-
.../context-module.ts | 12 +++
src/contracts/route-runtime-contract.ts | 18 ----
src/contracts/routes.ts | 39 --------
.../context-routes.ts | 17 ++++
.../contracts/platform-examples-contract.ts | 82 +++++++++++++++
.../platform-examples-message-catalog.ts | 23 +++++
.../feature-module.ts | 27 +++++
.../feature-runtime.ts | 13 +++
.../presentation}/auth-example-page.tsx | 4 +-
.../presentation/platform-examples-runtime.ts | 17 ++++
.../presentation}/state-gallery-page.tsx | 6 +-
.../presentation}/ui-gallery-page.tsx | 2 +-
src/presentation/i18n/catalog.ts | 24 +----
src/presentation/pages/home-page.tsx | 60 ++++++-----
src/presentation/routes/route-runtime.tsx | 12 ---
.../architecture/context-route-roots.test.ts | 8 +-
tests/component/starter-pages.test.tsx | 45 ++-------
tests/e2e/old-tab-chunk-recovery.spec.ts | 99 +++++++++++++++----
.../example-pages.test.tsx | 80 +++++++++++++++
.../ui-gallery-page.test.tsx} | 8 +-
tests/unit/runtime-adapters.test.ts | 21 +++-
26 files changed, 473 insertions(+), 209 deletions(-)
create mode 100644 src/contexts/platform-examples-context/context-module.ts
create mode 100644 src/features/platform-examples-feature/context-routes.ts
create mode 100644 src/features/platform-examples-feature/contracts/platform-examples-contract.ts
create mode 100644 src/features/platform-examples-feature/contracts/platform-examples-message-catalog.ts
create mode 100644 src/features/platform-examples-feature/feature-module.ts
create mode 100644 src/features/platform-examples-feature/feature-runtime.ts
rename src/{presentation/examples => features/platform-examples-feature/presentation}/auth-example-page.tsx (93%)
create mode 100644 src/features/platform-examples-feature/presentation/platform-examples-runtime.ts
rename src/{presentation/examples => features/platform-examples-feature/presentation}/state-gallery-page.tsx (94%)
rename src/{presentation/examples => features/platform-examples-feature/presentation}/ui-gallery-page.tsx (99%)
create mode 100644 tests/features/platform-examples-feature/example-pages.test.tsx
rename tests/{component/starter-ui-gallery-page.test.tsx => features/platform-examples-feature/ui-gallery-page.test.tsx} (96%)
diff --git a/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md b/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
index 66b0a112..9268cff4 100644
--- a/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
+++ b/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
@@ -70,9 +70,10 @@ route/form/failure 의미 값
- `check:i18n`은 catalog key와 placeholder parity, backend message JSX 렌더링을
검사한다. 검사 범위는 공통 UI 디렉터리, `src/presentation/pages`, 모든
- `src/features/*/presentation`이다. 컴포넌트 갤러리 `src/presentation/examples`는
- 일부러 뺐다(`scripts/check-i18n.ts`의 `commonDirectories`,
- `featurePresentationDirectories`).
+ `src/features/*/presentation`이다. 플랫폼 구성 화면
+ `src/presentation/examples`와 예제 화면
+ `src/features/platform-examples-feature/presentation`(1103/09-04)은 화면
+ 문구 ESLint 규칙에서 일부러 뺐다(`eslint.config.ts`).
- 화면 문구가 catalog에서 오는지는 ESLint `no-restricted-syntax`가 본다
(`eslint.config.ts`의 `screenTextSelectors`, 0929/08-02). 대상은 글자가 든
`JSXText`와 표시·접근성 속성(`aria-label`, `title`, `placeholder`, `alt`,
diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md
index bf356b57..d7775b40 100644
--- a/docs/architecture/starter-experience.md
+++ b/docs/architecture/starter-experience.md
@@ -85,14 +85,32 @@ rather than adding another independent route or data-loading convention.
### Replacing the starter screens
-`/` (`src/presentation/pages/home-page.tsx`) and `/examples/*`
-(`src/presentation/examples/`) are template content. Their own tests are the
-`tests/component/starter-*.test.tsx` files; delete them together with the
-screens. The platform's component tests (router, boundaries, shell, runtime
-tree) run on the pages of the test-only feature in
-`tests/helpers/fixture-feature.tsx` and keep passing when the starter screens
-change. Browser-level checks of the starter screens stay in `tests/e2e` and
-`tests/visual`.
+`/` (`src/presentation/pages/home-page.tsx`) is the platform's `APP_HOME`; a
+feature takes it over by declaring that route id (see "Product home and
+layouts"). Its starter links are the first three screens of the navigation.
+
+The example screens `/examples/ui`, `/examples/states` and `/examples/auth`
+are one feature, `src/features/platform-examples-feature/`, in its own context
+`src/contexts/platform-examples-context/` (1103/09-04). A product turns them
+off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or remove
+it with `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`
+as the drill. Their routes then leave the registry, the navigation, the
+bundle and the manual accessibility list (FE-GATE-028). Their component tests
+are in `tests/features/platform-examples-feature/` and go with them.
+
+The platform overview (`/examples/platform`,
+`src/presentation/examples/platform-overview-page.tsx`) stays a platform
+route. It describes the installed registries, and the lab gate (FE-GATE-026)
+times entering it: a feature route's first entry also loads its context's
+routes module before the page, a second request round the 200 ms budget does
+not fit. Its tests are the `tests/component/starter-*.test.tsx` files.
+
+The platform's component tests (router, boundaries, shell, runtime tree) run
+on the pages of the test-only feature in `tests/helpers/fixture-feature.tsx`
+and keep passing without the examples. The browser-level checks in
+`tests/e2e` and `tests/visual` use the example screens as their pages and run
+where the examples are installed: a product that leaves them out points those
+specs at its own screens or deletes them.
### Ownership declarations
diff --git a/eslint.config.ts b/eslint.config.ts
index 2e55d3c6..4d9f6f4c 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -458,8 +458,9 @@ const hookRules = {
// template literal, a ternary, an object prop such as `heading.title`) is not
// seen; review catches those. A product replaces these selectors in its own
// config, for example to allow a brand name or to drop the rule for a
-// one-locale product. The component gallery (src/presentation/examples) and
-// stories are workshop code and stay out; tests are outside these folders.
+// one-locale product. The platform overview (src/presentation/examples),
+// the example screens (src/features/platform-examples-feature/presentation)
+// and stories are workshop code and stay out; tests are outside these folders.
const screenTextDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
@@ -911,7 +912,13 @@ export default [
`${directory}/**/*.tsx`,
`tests/fixtures/i18n/*/${directory}/**/*.tsx`,
]),
- ignores: ["**/*.stories.tsx"],
+ // 1103/09-04. The example screens moved from src/presentation/examples
+ // into this feature and stay workshop code: their copy is Korean in every
+ // locale on purpose (08-07).
+ ignores: [
+ "**/*.stories.tsx",
+ "src/features/platform-examples-feature/presentation/**",
+ ],
rules: {
"no-restricted-syntax": [
...commonSecurityRules["no-restricted-syntax"],
diff --git a/public/release-manifest.json b/public/release-manifest.json
index 8c0005fa..471e2dd2 100644
--- a/public/release-manifest.json
+++ b/public/release-manifest.json
@@ -10,9 +10,9 @@
"routeChunks": {
"route-home": "src/presentation/pages/home-page.tsx",
"route-examples-platform": "src/presentation/examples/platform-overview-page.tsx",
- "route-examples-ui": "src/presentation/examples/ui-gallery-page.tsx",
- "route-examples-states": "src/presentation/examples/state-gallery-page.tsx",
- "route-examples-auth": "src/presentation/examples/auth-example-page.tsx",
+ "route-examples-ui": "src/features/platform-examples-feature/presentation/ui-gallery-page.tsx",
+ "route-examples-states": "src/features/platform-examples-feature/presentation/state-gallery-page.tsx",
+ "route-examples-auth": "src/features/platform-examples-feature/presentation/auth-example-page.tsx",
"route-reference-resources": "src/features/reference-feature/presentation/reference-resource-page.tsx",
"route-reference-resource-detail": "src/features/reference-feature/presentation/reference-resource-detail-page.tsx",
"route-reference-resource-form": "src/features/reference-feature/presentation/reference-resource-form-page.tsx",
diff --git a/scripts/check-i18n.ts b/scripts/check-i18n.ts
index 438b2680..0c2c04c7 100644
--- a/scripts/check-i18n.ts
+++ b/scripts/check-i18n.ts
@@ -59,8 +59,9 @@ if (!fixtureMode) {
// from an ordinary `.message` read. Fixture mode runs the ESLint rule on the
// fixture trees too, so this one gate shows the whole i18n contract rejecting
// every forbidden file and passing the allowed one.
-// `src/presentation/examples` is the component gallery and stays out of scope
-// on purpose.
+// `src/presentation/examples` (the platform overview) and the example
+// screens (`src/features/platform-examples-feature/presentation`, 1103/09-04)
+// are workshop code and stay out of the ESLint rule's scope on purpose.
const forbiddenFixtureRoot = "tests/fixtures/i18n/forbidden";
const allowedFixtureRoot = "tests/fixtures/i18n/allowed";
const sourceRoot = fixtureMode ? forbiddenFixtureRoot : ".";
diff --git a/src/contexts/platform-examples-context/context-module.ts b/src/contexts/platform-examples-context/context-module.ts
new file mode 100644
index 00000000..7e9b32a0
--- /dev/null
+++ b/src/contexts/platform-examples-context/context-module.ts
@@ -0,0 +1,12 @@
+/**
+ * 1103/09-04. The template's example screens (UI gallery, screen states,
+ * auth integration) as one removable bounded context. A product leaves
+ * `platform-examples-feature` out of `VITE_PRODUCT_FEATURES`, or deletes it,
+ * and the three routes leave the registry, the navigation, the bundle and the
+ * manual accessibility list together. The root is `examples/*`;
+ * `reference-context` keeps the more specific `examples/reference-resources/*`.
+ */
+export const CONTEXT_MODULE_ID = "platform-examples-context";
+export const CONTEXT_APP_ID = "template-app";
+export const CONTEXT_ROUTE_PATH = "examples/*";
+export const CONTEXT_MAX_FEATURES = 1;
diff --git a/src/contracts/route-runtime-contract.ts b/src/contracts/route-runtime-contract.ts
index ddbbdfa4..11c26d8a 100644
--- a/src/contracts/route-runtime-contract.ts
+++ b/src/contracts/route-runtime-contract.ts
@@ -23,24 +23,6 @@ export const PLATFORM_ROUTE_RUNTIME_CONTRACT = Object.freeze({
paramsCodec: "none",
searchCodec: "none",
}),
- EXAMPLES_UI: runtime({
- routeId: "EXAMPLES_UI",
- moduleId: "ui-gallery-page",
- paramsCodec: "none",
- searchCodec: "none",
- }),
- EXAMPLES_STATES: runtime({
- routeId: "EXAMPLES_STATES",
- moduleId: "state-gallery-page",
- paramsCodec: "none",
- searchCodec: "none",
- }),
- EXAMPLES_AUTH: runtime({
- routeId: "EXAMPLES_AUTH",
- moduleId: "auth-example-page",
- paramsCodec: "none",
- searchCodec: "none",
- }),
NOT_FOUND: runtime({
routeId: "NOT_FOUND",
moduleId: "not-found-page",
diff --git a/src/contracts/routes.ts b/src/contracts/routes.ts
index e4bcf431..53c79862 100644
--- a/src/contracts/routes.ts
+++ b/src/contracts/routes.ts
@@ -43,45 +43,6 @@ export const PLATFORM_ROUTE_REGISTRY = Object.freeze({
navigationLabel: "플랫폼 구성",
navigationOrder: 15,
}),
- EXAMPLES_UI: route({
- routeId: "EXAMPLES_UI",
- path: "/examples/ui",
- paramsSchema: null,
- searchSchema: null,
- access: "public",
- loadingSurface: "example-page",
- errorSurface: "route-boundary",
- chunkId: "route-examples-ui",
- title: "UI 구성요소",
- navigationLabel: "UI 구성요소",
- navigationOrder: 20,
- }),
- EXAMPLES_STATES: route({
- routeId: "EXAMPLES_STATES",
- path: "/examples/states",
- paramsSchema: null,
- searchSchema: null,
- access: "public",
- loadingSurface: "example-page",
- errorSurface: "route-boundary",
- chunkId: "route-examples-states",
- title: "화면 상태",
- navigationLabel: "화면 상태",
- navigationOrder: 30,
- }),
- EXAMPLES_AUTH: route({
- routeId: "EXAMPLES_AUTH",
- path: "/examples/auth",
- paramsSchema: null,
- searchSchema: null,
- access: "public",
- loadingSurface: "example-page",
- errorSurface: "route-boundary",
- chunkId: "route-examples-auth",
- title: "인증 연동",
- navigationLabel: "인증 연동",
- navigationOrder: 40,
- }),
NOT_FOUND: route({
routeId: "NOT_FOUND",
path: "*",
diff --git a/src/features/platform-examples-feature/context-routes.ts b/src/features/platform-examples-feature/context-routes.ts
new file mode 100644
index 00000000..1e332afe
--- /dev/null
+++ b/src/features/platform-examples-feature/context-routes.ts
@@ -0,0 +1,17 @@
+import type { RouteObject } from "react-router-dom";
+
+import { PLATFORM_EXAMPLES_CONTRACT } from "./contracts/platform-examples-contract.ts";
+import { PLATFORM_EXAMPLES_ROUTE_RUNTIME } from "./presentation/platform-examples-runtime.ts";
+
+export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(
+ Object.values(PLATFORM_EXAMPLES_CONTRACT.routes).map((definition) =>
+ Object.freeze({
+ id: definition.routeId,
+ path: definition.path,
+ handle: Object.freeze({
+ routeId: definition.routeId,
+ runtime: PLATFORM_EXAMPLES_ROUTE_RUNTIME[definition.routeId],
+ }),
+ }),
+ ),
+);
diff --git a/src/features/platform-examples-feature/contracts/platform-examples-contract.ts b/src/features/platform-examples-feature/contracts/platform-examples-contract.ts
new file mode 100644
index 00000000..e98498e4
--- /dev/null
+++ b/src/features/platform-examples-feature/contracts/platform-examples-contract.ts
@@ -0,0 +1,82 @@
+export const PLATFORM_EXAMPLES_FEATURE_ID = "platform-examples-feature";
+
+/**
+ * 1103/09-04. Three of the template's example screens, formerly fixed
+ * platform routes. The platform overview (`EXAMPLES_PLATFORM`) stays a
+ * platform route: the lab gate (FE-GATE-026) times entering it, and a feature
+ * route's first entry costs a second request round (its context's routes
+ * module, then the page). Paths, chunk ids and surfaces are unchanged: the
+ * visual and e2e tests and the manual accessibility records still name them.
+ * Declaration only, so it holds data; the pages load with `context-routes.ts`.
+ */
+export const PLATFORM_EXAMPLES_CONTRACT = Object.freeze({
+ featureId: PLATFORM_EXAMPLES_FEATURE_ID,
+ routes: Object.freeze({
+ EXAMPLES_UI: Object.freeze({
+ routeId: "EXAMPLES_UI",
+ path: "/examples/ui",
+ paramsSchema: null,
+ searchSchema: null,
+ access: "public",
+ loadingSurface: "example-page",
+ errorSurface: "route-boundary",
+ chunkId: "route-examples-ui",
+ title: "UI 구성요소",
+ navigationLabel: "UI 구성요소",
+ navigationOrder: 20,
+ }),
+ EXAMPLES_STATES: Object.freeze({
+ routeId: "EXAMPLES_STATES",
+ path: "/examples/states",
+ paramsSchema: null,
+ searchSchema: null,
+ access: "public",
+ loadingSurface: "example-page",
+ errorSurface: "route-boundary",
+ chunkId: "route-examples-states",
+ title: "화면 상태",
+ navigationLabel: "화면 상태",
+ navigationOrder: 30,
+ }),
+ EXAMPLES_AUTH: Object.freeze({
+ routeId: "EXAMPLES_AUTH",
+ path: "/examples/auth",
+ paramsSchema: null,
+ searchSchema: null,
+ access: "public",
+ loadingSurface: "example-page",
+ errorSurface: "route-boundary",
+ chunkId: "route-examples-auth",
+ title: "인증 연동",
+ navigationLabel: "인증 연동",
+ navigationOrder: 40,
+ }),
+ }),
+ routeRuntimeContracts: Object.freeze({
+ EXAMPLES_UI: Object.freeze({
+ routeId: "EXAMPLES_UI",
+ moduleId: "ui-gallery-page",
+ paramsCodec: "none",
+ searchCodec: "none",
+ }),
+ EXAMPLES_STATES: Object.freeze({
+ routeId: "EXAMPLES_STATES",
+ moduleId: "state-gallery-page",
+ paramsCodec: "none",
+ searchCodec: "none",
+ }),
+ EXAMPLES_AUTH: Object.freeze({
+ routeId: "EXAMPLES_AUTH",
+ moduleId: "auth-example-page",
+ paramsCodec: "none",
+ searchCodec: "none",
+ }),
+ }),
+ invalidation: Object.freeze({
+ topics: Object.freeze([]),
+ namespaces: Object.freeze([]),
+ edges: Object.freeze([]),
+ }),
+ topicVersions: Object.freeze([]),
+ contractPackages: Object.freeze([]),
+} as const);
diff --git a/src/features/platform-examples-feature/contracts/platform-examples-message-catalog.ts b/src/features/platform-examples-feature/contracts/platform-examples-message-catalog.ts
new file mode 100644
index 00000000..310c98d4
--- /dev/null
+++ b/src/features/platform-examples-feature/contracts/platform-examples-message-catalog.ts
@@ -0,0 +1,23 @@
+/**
+ * 1103/09-04. The route titles and navigation labels the shell reads; they
+ * moved here from the platform catalog with the routes. The pages' own copy
+ * stays Korean in every locale (08-07).
+ */
+export const PLATFORM_EXAMPLES_MESSAGE_CATALOGS = Object.freeze({
+ "ko-KR": Object.freeze({
+ "route.EXAMPLES_UI.navigation": "UI 구성요소",
+ "route.EXAMPLES_UI.title": "UI 구성요소",
+ "route.EXAMPLES_STATES.navigation": "화면 상태",
+ "route.EXAMPLES_STATES.title": "화면 상태",
+ "route.EXAMPLES_AUTH.navigation": "인증 연동",
+ "route.EXAMPLES_AUTH.title": "인증 연동",
+ }),
+ "en-US": Object.freeze({
+ "route.EXAMPLES_UI.navigation": "UI components",
+ "route.EXAMPLES_UI.title": "UI components",
+ "route.EXAMPLES_STATES.navigation": "Screen states",
+ "route.EXAMPLES_STATES.title": "Screen states",
+ "route.EXAMPLES_AUTH.navigation": "Authentication",
+ "route.EXAMPLES_AUTH.title": "Authentication",
+ }),
+} as const);
diff --git a/src/features/platform-examples-feature/feature-module.ts b/src/features/platform-examples-feature/feature-module.ts
new file mode 100644
index 00000000..7d7b3fc4
--- /dev/null
+++ b/src/features/platform-examples-feature/feature-module.ts
@@ -0,0 +1,27 @@
+import { defineFeatureModule } from "../feature-module.ts";
+import {
+ PLATFORM_EXAMPLES_CONTRACT,
+ PLATFORM_EXAMPLES_FEATURE_ID,
+} from "./contracts/platform-examples-contract.ts";
+import { PLATFORM_EXAMPLES_MESSAGE_CATALOGS } from "./contracts/platform-examples-message-catalog.ts";
+
+export const FEATURE_MODULE_ID =
+ "platform-examples-feature" satisfies typeof PLATFORM_EXAMPLES_FEATURE_ID;
+/** Owning bounded context (route root and budget live in its declaration). */
+export const FEATURE_CONTEXT_ID = "platform-examples-context";
+
+/**
+ * 1103/09-04. The template's example screens as a feature, so the product's
+ * feature selection, `FEATURE_OVERRIDES`, the removal drill and the manual
+ * accessibility list apply to them like to any feature. Declaration only:
+ * the pages load with the context routes, and the runtime half is empty.
+ */
+export const PLATFORM_EXAMPLES_FEATURE_MODULE = defineFeatureModule({
+ id: FEATURE_MODULE_ID,
+ contracts: PLATFORM_EXAMPLES_CONTRACT,
+ routes: PLATFORM_EXAMPLES_CONTRACT.routes,
+ messages: PLATFORM_EXAMPLES_MESSAGE_CATALOGS,
+ loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME,
+} as const);
+
+export const FEATURE_MODULE = PLATFORM_EXAMPLES_FEATURE_MODULE;
diff --git a/src/features/platform-examples-feature/feature-runtime.ts b/src/features/platform-examples-feature/feature-runtime.ts
new file mode 100644
index 00000000..7ab57e96
--- /dev/null
+++ b/src/features/platform-examples-feature/feature-runtime.ts
@@ -0,0 +1,13 @@
+import { defineFeatureRuntime } from "../feature-module.ts";
+import { PLATFORM_EXAMPLES_FEATURE_ID } from "./contracts/platform-examples-contract.ts";
+
+/**
+ * 1103/09-04. The example screens call no feature API: they show the
+ * design system and the shell's session. The runtime half is empty.
+ */
+export const FEATURE_RUNTIME = defineFeatureRuntime({
+ featureId: PLATFORM_EXAMPLES_FEATURE_ID,
+ schemas: Object.freeze({}),
+ adapters: [],
+ contractContributions: [],
+} as const);
diff --git a/src/presentation/examples/auth-example-page.tsx b/src/features/platform-examples-feature/presentation/auth-example-page.tsx
similarity index 93%
rename from src/presentation/examples/auth-example-page.tsx
rename to src/features/platform-examples-feature/presentation/auth-example-page.tsx
index f8419f2e..b7dcf908 100644
--- a/src/presentation/examples/auth-example-page.tsx
+++ b/src/features/platform-examples-feature/presentation/auth-example-page.tsx
@@ -1,8 +1,8 @@
-import { PageHeader } from "../design-system/index.ts";
+import { PageHeader } from "../../../presentation/design-system/index.ts";
import {
useSession,
useSessionAction,
-} from "../providers/session-provider.tsx";
+} from "../../../presentation/providers/session-provider.tsx";
export default function AuthExamplePage() {
const { sessionState } = useSession();
diff --git a/src/features/platform-examples-feature/presentation/platform-examples-runtime.ts b/src/features/platform-examples-feature/presentation/platform-examples-runtime.ts
new file mode 100644
index 00000000..36447dd8
--- /dev/null
+++ b/src/features/platform-examples-feature/presentation/platform-examples-runtime.ts
@@ -0,0 +1,17 @@
+import { lazy } from "react";
+
+/** One lazy chunk per example page, as when they were platform routes. */
+export const PLATFORM_EXAMPLES_ROUTE_RUNTIME = {
+ EXAMPLES_UI: Object.freeze({
+ moduleId: "ui-gallery-page",
+ Component: lazy(() => import("./ui-gallery-page.tsx")),
+ }),
+ EXAMPLES_STATES: Object.freeze({
+ moduleId: "state-gallery-page",
+ Component: lazy(() => import("./state-gallery-page.tsx")),
+ }),
+ EXAMPLES_AUTH: Object.freeze({
+ moduleId: "auth-example-page",
+ Component: lazy(() => import("./auth-example-page.tsx")),
+ }),
+} as const;
diff --git a/src/presentation/examples/state-gallery-page.tsx b/src/features/platform-examples-feature/presentation/state-gallery-page.tsx
similarity index 94%
rename from src/presentation/examples/state-gallery-page.tsx
rename to src/features/platform-examples-feature/presentation/state-gallery-page.tsx
index 24f77029..ceec9a9e 100644
--- a/src/presentation/examples/state-gallery-page.tsx
+++ b/src/features/platform-examples-feature/presentation/state-gallery-page.tsx
@@ -1,7 +1,7 @@
import { useState } from "react";
-import { deriveAsyncState } from "../../application/view-models/async-state.ts";
-import { createFailure } from "../../contracts/errors.ts";
+import { deriveAsyncState } from "../../../application/view-models/async-state.ts";
+import { createFailure } from "../../../contracts/errors.ts";
import {
AsyncSurface,
EmptySurface,
@@ -13,7 +13,7 @@ import {
Button,
Card,
PageHeader,
-} from "../design-system/index.ts";
+} from "../../../presentation/design-system/index.ts";
export default function StateGalleryPage() {
const [lastAction, setLastAction] = useState(
diff --git a/src/presentation/examples/ui-gallery-page.tsx b/src/features/platform-examples-feature/presentation/ui-gallery-page.tsx
similarity index 99%
rename from src/presentation/examples/ui-gallery-page.tsx
rename to src/features/platform-examples-feature/presentation/ui-gallery-page.tsx
index e5966beb..2a569382 100644
--- a/src/presentation/examples/ui-gallery-page.tsx
+++ b/src/features/platform-examples-feature/presentation/ui-gallery-page.tsx
@@ -19,7 +19,7 @@ import {
ToastProvider,
Tooltip,
useToast,
-} from "../design-system/index.ts";
+} from "../../../presentation/design-system/index.ts";
const COLOR_TOKENS = Object.freeze([
["Surface", "--color-surface"],
diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts
index 7f31d496..ccbf460e 100644
--- a/src/presentation/i18n/catalog.ts
+++ b/src/presentation/i18n/catalog.ts
@@ -45,12 +45,6 @@ const PLATFORM_KO_MESSAGES = {
"route.APP_HOME.title": "Clean Architecture Frontend",
"route.EXAMPLES_PLATFORM.navigation": "플랫폼 구성",
"route.EXAMPLES_PLATFORM.title": "플랫폼 구성",
- "route.EXAMPLES_UI.navigation": "UI 구성요소",
- "route.EXAMPLES_UI.title": "UI 구성요소",
- "route.EXAMPLES_STATES.navigation": "화면 상태",
- "route.EXAMPLES_STATES.title": "화면 상태",
- "route.EXAMPLES_AUTH.navigation": "인증 연동",
- "route.EXAMPLES_AUTH.title": "인증 연동",
"route.NOT_FOUND.navigation": "찾을 수 없음",
"route.NOT_FOUND.title": "페이지를 찾을 수 없습니다.",
"async.loading": "불러오는 중",
@@ -117,10 +111,8 @@ const PLATFORM_KO_MESSAGES = {
"home.runtime.summary": "빌드 {buildId} · 릴리스 {releaseId}",
"home.starter.title": "준비된 화면 살펴보기",
"home.starter.description":
- "설치된 라우트와 계약, 런타임 능력은 플랫폼 구성 화면에서, 공통 구성요소와 비동기 화면 상태는 예제 라우트에서 확인하세요.",
- "home.starter.platform": "플랫폼 구성 보기",
- "home.starter.ui": "UI 구성요소 보기",
- "home.starter.states": "화면 상태 보기",
+ "내비게이션의 첫 화면을 바로 엽니다. 템플릿에서는 설치된 라우트·계약·런타임 능력, 공통 구성요소, 비동기 화면 상태를 보여 주는 예제 화면입니다.",
+ "home.starter.open": "{title} 보기",
"page.notFound.title": "페이지를 찾을 수 없습니다.",
"page.notFound.description":
"주소를 확인하거나 준비된 시작 화면으로 돌아가세요.",
@@ -258,12 +250,6 @@ const PLATFORM_EN_MESSAGES = {
"route.APP_HOME.title": "Clean Architecture Frontend",
"route.EXAMPLES_PLATFORM.navigation": "Platform composition",
"route.EXAMPLES_PLATFORM.title": "Platform composition",
- "route.EXAMPLES_UI.navigation": "UI components",
- "route.EXAMPLES_UI.title": "UI components",
- "route.EXAMPLES_STATES.navigation": "Screen states",
- "route.EXAMPLES_STATES.title": "Screen states",
- "route.EXAMPLES_AUTH.navigation": "Authentication",
- "route.EXAMPLES_AUTH.title": "Authentication",
"route.NOT_FOUND.navigation": "Not found",
"route.NOT_FOUND.title": "Page not found",
"async.loading": "Loading",
@@ -329,10 +315,8 @@ const PLATFORM_EN_MESSAGES = {
"home.runtime.summary": "Build {buildId} · Release {releaseId}",
"home.starter.title": "Explore the prepared screens",
"home.starter.description":
- "See installed routes, contracts and runtime capabilities on the platform composition page, and common components and async screen states on the example routes.",
- "home.starter.platform": "View platform composition",
- "home.starter.ui": "View UI components",
- "home.starter.states": "View screen states",
+ "Open the first screens of the navigation. In the template these are the example screens for installed routes, contracts and runtime capabilities, common components and async screen states.",
+ "home.starter.open": "View {title}",
"page.notFound.title": "Page not found.",
"page.notFound.description": "Check the address or return to the start page.",
"template.breadcrumb": "Current location",
diff --git a/src/presentation/pages/home-page.tsx b/src/presentation/pages/home-page.tsx
index b773916e..0a72221a 100644
--- a/src/presentation/pages/home-page.tsx
+++ b/src/presentation/pages/home-page.tsx
@@ -1,7 +1,7 @@
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
-import { routePath } from "../../features/installed-feature-contracts.ts";
+import { NAVIGATION_ROUTES } from "../../features/installed-feature-contracts.ts";
import { PageHeader } from "../design-system/index.ts";
import { useLocale } from "../i18n/index.ts";
import { useApplicationRuntime } from "../providers/application-provider.tsx";
@@ -12,9 +12,19 @@ const READINESS_ITEMS = Object.freeze([
"accessibility",
] as const);
+/**
+ * 1103/09-04. The first screens of the navigation after this page. In the
+ * template those are its example screens, a removable feature; a
+ * product that leaves them out gets its own screens here, and the page names
+ * no feature's route.
+ */
+const STARTER_ROUTES = Object.freeze(
+ NAVIGATION_ROUTES.filter((route) => route.routeId !== "APP_HOME").slice(0, 3),
+);
+
export default function HomePage() {
const runtime = useApplicationRuntime();
- const { message } = useLocale();
+ const { message, resolve } = useLocale();
const [release, setRelease] = useState<
Awaited> | "failed" | null
>(null);
@@ -59,29 +69,29 @@ export default function HomePage() {
})
: message("home.runtime.checking")}
-
-
+
+ ) : null}
);
}
diff --git a/src/presentation/routes/route-runtime.tsx b/src/presentation/routes/route-runtime.tsx
index 8ae93a40..8d6941b5 100644
--- a/src/presentation/routes/route-runtime.tsx
+++ b/src/presentation/routes/route-runtime.tsx
@@ -28,18 +28,6 @@ export const PLATFORM_ROUTE_RUNTIME = {
"EXAMPLES_PLATFORM",
() => import("../examples/platform-overview-page.tsx"),
),
- EXAMPLES_UI: runtime(
- "EXAMPLES_UI",
- () => import("../examples/ui-gallery-page.tsx"),
- ),
- EXAMPLES_STATES: runtime(
- "EXAMPLES_STATES",
- () => import("../examples/state-gallery-page.tsx"),
- ),
- EXAMPLES_AUTH: runtime(
- "EXAMPLES_AUTH",
- () => import("../examples/auth-example-page.tsx"),
- ),
NOT_FOUND: runtime(
"NOT_FOUND",
() => import("../pages/not-found-page.tsx"),
diff --git a/tests/architecture/context-route-roots.test.ts b/tests/architecture/context-route-roots.test.ts
index 50b0c8b1..48d7b9a2 100644
--- a/tests/architecture/context-route-roots.test.ts
+++ b/tests/architecture/context-route-roots.test.ts
@@ -193,10 +193,10 @@ describe("feature routes and platform routes", () => {
expect(() =>
app(
context("examples", "examples/*", [
- feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }),
+ feature("examples-feature", { EXAMPLES_PLATFORM_COPY: "/examples/platform" }),
]),
),
- ).toThrow(/EXAMPLES_UI_COPY.*\/examples\/ui.*examples-feature.*examples.*EXAMPLES_UI/);
+ ).toThrow(/EXAMPLES_PLATFORM_COPY.*\/examples\/platform.*examples-feature.*examples.*EXAMPLES_PLATFORM/);
});
it("rejects the same path under a layout of its own", () => {
@@ -204,10 +204,10 @@ describe("feature routes and platform routes", () => {
expect(() =>
app(
context("examples", "examples/*", [
- feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }),
+ feature("examples-feature", { EXAMPLES_PLATFORM_COPY: "/examples/platform" }),
], layout),
),
- ).toThrow(/EXAMPLES_UI_COPY.*EXAMPLES_UI/);
+ ).toThrow(/EXAMPLES_PLATFORM_COPY.*EXAMPLES_PLATFORM/);
});
it("rejects two feature routes with the same path, naming both", () => {
diff --git a/tests/component/starter-pages.test.tsx b/tests/component/starter-pages.test.tsx
index 63090de8..d0e2734e 100644
--- a/tests/component/starter-pages.test.tsx
+++ b/tests/component/starter-pages.test.tsx
@@ -3,10 +3,8 @@
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { MemoryRouter } from "react-router-dom";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
-import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
-import StateGalleryPage from "../../src/presentation/examples/state-gallery-page.tsx";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
import HomePage from "../../src/presentation/pages/home-page.tsx";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
@@ -15,10 +13,11 @@ import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
/**
- * The starter screens (`/` and `/examples/*`) are the template's content, not
- * the platform (0929/10-02). A product that replaces them deletes the
- * `starter-*.test.tsx` files with them; the platform tests run on the
- * test-only feature's pages and keep passing.
+ * The starter screens (`/` and `/examples/platform`) are the template's
+ * content, not the platform (0929/10-02). A product that replaces them deletes
+ * the `starter-*.test.tsx` files with them; the platform tests run on the
+ * test-only feature's pages and keep passing. 1103/09-04: the other example
+ * screens are a removable feature, tested in its own test folder.
*/
function renderApp(
@@ -83,35 +82,3 @@ describe("starter home page", () => {
).not.toBeInTheDocument();
});
});
-
-describe("starter example pages", () => {
- it("returns to the current URL with its hash from the auth example page", async () => {
- const user = userEvent.setup();
- const beginSignIn = vi.fn(async () => {});
- renderApp(
- "/examples/auth#session",
- createTestApplication({
- session: { ...createAnonymousSessionAdapter(), beginSignIn },
- }),
- );
-
- await user.click(
- await screen.findByRole("button", { name: "로그인 시작" }),
- );
- expect(beginSignIn).toHaveBeenCalledWith("/examples/auth#session");
- });
-
- it("nests the state gallery's titles under the card and section around them (08-05)", () => {
- render();
-
- expect(
- screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
- ).toBeVisible();
- expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
- .toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
- // Access states sit directly under the section's h2.
- expect(
- screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
- ).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
- });
-});
diff --git a/tests/e2e/old-tab-chunk-recovery.spec.ts b/tests/e2e/old-tab-chunk-recovery.spec.ts
index 142eed2f..72635b16 100644
--- a/tests/e2e/old-tab-chunk-recovery.spec.ts
+++ b/tests/e2e/old-tab-chunk-recovery.spec.ts
@@ -1,7 +1,11 @@
import { appendFile, readFile } from "node:fs/promises";
import path from "node:path";
-import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
+import type { RouteDefinition } from "../../src/contracts/routes.ts";
+import {
+ ROUTE_REGISTRY,
+ ROUTE_RUNTIME_CONTRACT,
+} from "../../src/features/installed-feature-contracts.ts";
import { expect, test } from "../support/browser/strict-browser-test.ts";
import {
prepareFixtureBuilds,
@@ -19,11 +23,60 @@ import { startBuildServer } from "./support/service-worker-builds.ts";
* recovery failure instead.
*/
-const PLATFORM = ROUTE_REGISTRY.EXAMPLES_PLATFORM;
-const UI = ROUTE_REGISTRY.EXAMPLES_UI;
-const PLATFORM_PAGE = "src/presentation/examples/platform-overview-page.tsx";
-const UI_PAGE = "src/presentation/examples/ui-gallery-page.tsx";
-const PAGES = [PLATFORM_PAGE, UI_PAGE] as const;
+// 1103/09-04. The platform overview is a platform route; the UI gallery is
+// a feature route now, reached through its context gateway. Route ids only:
+// the page sources are read from build A's Vite manifest, so this spec names
+// no feature folder.
+const installedRoutes: Readonly> = ROUTE_REGISTRY;
+const runtimeContracts: Readonly> =
+ ROUTE_RUNTIME_CONTRACT;
+function installedRoute(routeId: string): RouteDefinition {
+ const definition = installedRoutes[routeId];
+ if (!definition) throw new Error(`${routeId} is not installed.`);
+ return definition;
+}
+const PLATFORM = installedRoute("EXAMPLES_PLATFORM");
+const UI = installedRoute("EXAMPLES_UI");
+
+type ViteManifest = Record<
+ string,
+ {
+ file: string;
+ name?: string;
+ isDynamicEntry?: boolean;
+ imports?: string[];
+ dynamicImports?: string[];
+ }
+>;
+
+async function viteManifest(dist: string): Promise {
+ return JSON.parse(
+ await readFile(path.join(dist, ".vite/manifest.json"), "utf8"),
+ ) as ViteManifest;
+}
+
+/** The source of a route's page: the dynamic entry named by its module id. */
+function pageSource(manifest: ViteManifest, route: RouteDefinition): string {
+ const moduleId = runtimeContracts[route.routeId]?.moduleId;
+ const sources = Object.entries(manifest)
+ .filter(([, entry]) => entry.isDynamicEntry && entry.name === moduleId)
+ .map(([source]) => source);
+ if (sources.length !== 1) {
+ throw new Error(`Expected one page chunk for ${route.routeId}: ${sources.join(", ")}`);
+ }
+ return sources[0]!;
+}
+
+/** The context routes module that lazy-loads `page`. */
+function routesSource(manifest: ViteManifest, page: string): string {
+ const sources = Object.entries(manifest)
+ .filter(([, entry]) => entry.isDynamicEntry && entry.dynamicImports?.includes(page))
+ .map(([source]) => source);
+ if (sources.length !== 1) {
+ throw new Error(`Expected one routes module for ${page}: ${sources.join(", ")}`);
+ }
+ return sources[0]!;
+}
let builds: FixtureBuilds<"a" | "b"> | undefined;
@@ -34,9 +87,10 @@ test.beforeAll(async () => {
{
name: "b",
edit: async (root) => {
- for (const page of PAGES) {
+ const manifest = await viteManifest(path.join(root, "dist-a"));
+ for (const route of [PLATFORM, UI]) {
await appendFile(
- path.join(root, page),
+ path.join(root, pageSource(manifest, route)),
'\n(globalThis as Record).__caFixtureBuild = "b";\n',
);
}
@@ -56,11 +110,13 @@ async function routeChunk(dist: string, chunkId: string): Promise {
return `/${manifest.routeChunks[chunkId]}`;
}
-// Each missing page chunk fails its request and the dynamic import. Chromium
-// may also log the 404 itself (without its URL), Firefox logs the error
-// object React caught, and WebKit logs its own import error without the URL.
-// Nothing else is allowed, but for the WebKit warning below.
-const MISSING_PAGE = String.raw`/assets/(?:platform-overview|ui-gallery)-page-[\w-]+\.js`;
+// Each missing chunk fails its request and the dynamic import. Chromium may
+// also log the 404 itself (without its URL), Firefox logs the error object
+// React caught, and WebKit logs its own import error without the URL. Nothing
+// else is allowed, but for the WebKit warning below. 1103/09-04: the B tab
+// misses the UI gallery's context routes module before its page: that module
+// names B's new page chunk, so its hash changed too.
+const MISSING_PAGE = String.raw`/assets/(?:platform-overview-page|ui-gallery-page|context-routes)-[\w-]+\.js`;
const MISSING_PAGE_FAILURES = [
String.raw`^requestfailed:GET:${MISSING_PAGE}:`,
String.raw`^console:error:TypeError: Failed to fetch dynamically imported module: http://127\.0\.0\.1:\d+${MISSING_PAGE}$`,
@@ -72,9 +128,7 @@ const MISSING_PAGE_FAILURES = [
/** The chunks Vite preloads with `page`: its static imports in `dist`. */
async function preloadedWith(dist: string, page: string): Promise {
- const manifest = JSON.parse(
- await readFile(path.join(dist, ".vite/manifest.json"), "utf8"),
- ) as Record;
+ const manifest = await viteManifest(dist);
if (!manifest[page]) throw new Error(`${page} is not in ${dist}'s manifest.`);
const files = new Set();
const pending = [...(manifest[page].imports ?? [])];
@@ -89,10 +143,10 @@ async function preloadedWith(dist: string, page: string): Promise {
// WebKit only. Three seconds after a document's load event, WebKit warns once
// for each link-preloaded resource the document has not used yet. Vite
-// preloads a page chunk together with the chunks it imports, so a missing page
+// preloads a chunk together with the chunks it imports, so a missing chunk
// leaves the chunks preloaded with it unused: in the A tab those of A's
// platform page (the tab is still on A while recovery reads the release
-// manifest), in the B tab those of B's UI page. Whether that check runs before
+// manifest), in the B tab those of B's context routes module for the UI page. Whether that check runs before
// the reload, or before the test ends, is timing, so the warnings come and go.
// They are the provoked failure's own effect; only those chunks are allowed.
test.use({
@@ -100,9 +154,14 @@ test.use({
const patterns = [...MISSING_PAGE_FAILURES];
if (browserName === "webkit") {
if (!builds) throw new Error("Fixture builds were not prepared.");
+ const aManifest = await viteManifest(builds.dist.a);
+ const bManifest = await viteManifest(builds.dist.b);
const files = [
- ...(await preloadedWith(builds.dist.a, PLATFORM_PAGE)),
- ...(await preloadedWith(builds.dist.b, UI_PAGE)),
+ ...(await preloadedWith(builds.dist.a, pageSource(aManifest, PLATFORM))),
+ ...(await preloadedWith(
+ builds.dist.b,
+ routesSource(bManifest, pageSource(bManifest, UI)),
+ )),
].map((file) => file.replaceAll(".", String.raw`\.`));
patterns.push(
String.raw`^console:warning:The resource http://127\.0\.0\.1:\d+/(?:${files.join("|")}) was preloaded using link preload but not used within a few seconds from the window's load event\. Please make sure it wasn't preloaded for nothing\.$`,
diff --git a/tests/features/platform-examples-feature/example-pages.test.tsx b/tests/features/platform-examples-feature/example-pages.test.tsx
new file mode 100644
index 00000000..017a1d66
--- /dev/null
+++ b/tests/features/platform-examples-feature/example-pages.test.tsx
@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { createAnonymousSessionAdapter } from "../../../src/adapters/auth/external-session-adapter.ts";
+import StateGalleryPage from "../../../src/features/platform-examples-feature/presentation/state-gallery-page.tsx";
+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";
+import { createTestApplication } from "../../helpers/create-test-application.ts";
+
+/**
+ * The example screens (`/examples/ui`, `/examples/states`, `/examples/auth`)
+ * are the template's content, not the platform (0929/10-02). 1103/09-04:
+ * they are `platform-examples-feature`, and this folder goes with it; the
+ * platform tests run on the test-only feature's pages and keep passing.
+ */
+
+function renderApp(
+ url: string,
+ application = createTestApplication(),
+) {
+ window.history.pushState({}, "", url);
+ return render(
+
+
+
+
+ ,
+ );
+}
+
+describe("example pages", () => {
+ it("reaches the UI gallery from the home page's starter actions", async () => {
+ const user = userEvent.setup();
+ renderApp("/");
+
+ await user.click(
+ await screen.findByRole("link", { name: "UI 구성요소 보기" }),
+ );
+
+ await waitFor(() =>
+ expect(
+ screen.getByRole("heading", { name: "UI 구성요소", level: 1 }),
+ ).toHaveFocus(),
+ );
+ });
+
+ it("returns to the current URL with its hash from the auth example page", async () => {
+ const user = userEvent.setup();
+ const beginSignIn = vi.fn(async () => {});
+ renderApp(
+ "/examples/auth#session",
+ createTestApplication({
+ session: { ...createAnonymousSessionAdapter(), beginSignIn },
+ }),
+ );
+
+ await user.click(
+ await screen.findByRole("button", { name: "로그인 시작" }),
+ );
+ expect(beginSignIn).toHaveBeenCalledWith("/examples/auth#session");
+ });
+
+ it("nests the state gallery's titles under the card and section around them (08-05)", () => {
+ render();
+
+ expect(
+ screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
+ ).toBeVisible();
+ expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
+ .toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
+ // Access states sit directly under the section's h2.
+ expect(
+ screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
+ ).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
+ });
+});
diff --git a/tests/component/starter-ui-gallery-page.test.tsx b/tests/features/platform-examples-feature/ui-gallery-page.test.tsx
similarity index 96%
rename from tests/component/starter-ui-gallery-page.test.tsx
rename to tests/features/platform-examples-feature/ui-gallery-page.test.tsx
index dfff44fa..52db2d3d 100644
--- a/tests/component/starter-ui-gallery-page.test.tsx
+++ b/tests/features/platform-examples-feature/ui-gallery-page.test.tsx
@@ -4,12 +4,12 @@ import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
-import UiGalleryPage from "../../src/presentation/examples/ui-gallery-page.tsx";
-import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
+import UiGalleryPage from "../../../src/features/platform-examples-feature/presentation/ui-gallery-page.tsx";
+import { LocaleProvider } from "../../../src/presentation/i18n/index.ts";
/**
- * A starter screen (0929/10-02): `/examples/ui` is template content, so a
- * product that replaces it deletes this file with it. The primitives have
+ * A starter screen (0929/10-02): `/examples/ui` is template content
+ * (`platform-examples-feature`, 1103/09-04), and this file goes with it. The primitives have
* their own suites; this one checks what the page wires them to — the
* validation rule, the shared notice line and the show/hide state.
*/
diff --git a/tests/unit/runtime-adapters.test.ts b/tests/unit/runtime-adapters.test.ts
index 77bbedb5..8b3155aa 100644
--- a/tests/unit/runtime-adapters.test.ts
+++ b/tests/unit/runtime-adapters.test.ts
@@ -4,7 +4,8 @@ import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts";
import { createBrowserMutationIntentFactory } from "../../src/adapters/platform/browser-mutation-intent-factory.ts";
import { createApplication } from "../../src/application/create-application.ts";
import type { ApplicationFeatureId } from "../../src/application/ports/in/application-api.ts";
-import { INSTALLED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts";
+import { loadFeatureRuntime } from "../../src/features/feature-module.ts";
+import { INSTALLED_PRODUCT_FEATURE_MODULES } from "../../src/features/installed-product-manifest.ts";
type Runtime = Parameters[0]["runtime"];
type Release = Parameters[0]["release"];
@@ -53,6 +54,20 @@ const release: Release = {
routeChunks: { "route-home": "assets/home.js" },
};
+
+/**
+ * 1103/09-04. The installed features that contribute an application API. The
+ * template's example screens call none: loading them
+ * installs no input.
+ */
+const API_FEATURE_IDS: readonly string[] = (
+ await Promise.all(
+ INSTALLED_PRODUCT_FEATURE_MODULES.map(async (module) =>
+ (await loadFeatureRuntime(module)).adapters.length > 0 ? [module.id] : [],
+ ),
+ )
+).flat();
+
describe("runtime adapter composition", () => {
it("creates validated intent and idempotency identities with independent UUID calls", () => {
const randomUUID = vi
@@ -361,7 +376,7 @@ describe("runtime adapter composition", () => {
});
it("gives a feature switched off by FEATURE_OVERRIDES no application API (Q-6.9-5)", async () => {
- const [disabledId, ...activeIds] = INSTALLED_PRODUCT_FEATURE_IDS;
+ const [disabledId, ...activeIds] = API_FEATURE_IDS;
const adapters = await createRuntimeAdapters({
runtime: {
...runtime,
@@ -401,7 +416,7 @@ describe("runtime adapter composition", () => {
adapters.featureLoaders,
);
- for (const featureId of INSTALLED_PRODUCT_FEATURE_IDS) {
+ for (const featureId of API_FEATURE_IDS) {
// 15-01. Not loaded until the router asks for the feature's routes.
expect(() =>
application.features.get(featureId as ApplicationFeatureId),
From 0a6ff6e5ed5af7a73ab29c1884a6137d02bacb25 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Wed, 4 Nov 2026 22:37:54 +0900
Subject: [PATCH 5/5] =?UTF-8?q?test(visual):=20=EC=8B=9C=EA=B0=81=20?=
=?UTF-8?q?=EA=B3=A8=EB=93=A0=EC=97=90=EC=84=9C=20=EC=84=A4=EC=B9=98?=
=?UTF-8?q?=EB=90=9C=20=EA=B8=B0=EB=8A=A5=EC=9D=98=20=EB=A7=81=ED=81=AC?=
=?UTF-8?q?=EC=99=80=20=EB=AA=A9=EB=A1=9D=EC=9D=84=20=EB=BA=80=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.
고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
실패를 낸다.
- 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
빠진다.
- 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
골든을 제품 소유로 선언(동기화마다 PNG 충돌).
위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
보기" 버튼만 남는다.
검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
가림 규칙에 걸리지 않음).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
---
...ct-pseudo-drawer-chromium-visual-linux.png | Bin 83363 -> 68770 bytes
...shell-wide-light-chromium-visual-linux.png | Bin 100913 -> 92040 bytes
...m-overview-light-chromium-visual-linux.png | Bin 456747 -> 187585 bytes
tests/visual/platform.visual.spec.ts | 54 ++++++++++++++++++
4 files changed, 54 insertions(+)
diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png
index 234b9d6ea4ad25ed9183f10576dd919f4821380f..03f375b5e3e04a70f4391d845467dd98b5cf52f5 100644
GIT binary patch
literal 68770
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