Commit Graph
12 Commits
Author SHA1 Message Date
DongHyeonka ad73e56476 fix(presentation): 예제 화면이 자기 언어를 ko-KR로 밝힌다 (08-07)
문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제
화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다.
en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US"
아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2).

고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을
준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다.
버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다.
예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다.

위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는
문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서
영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어
본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다.
예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다.

검증:
- RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (Platform composition: lang Expected "ko-KR", Received "").
- GREEN: i18n·accessibility·ui-gallery·platform-overview e2e
  chromium·firefox·webkit 69/69 통과. tests/component 220/220,
  check-i18n PASS, tsc app 통과, eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07
2026-11-01 23:20:31 +09:00
DongHyeonka dda153b25e feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.

고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.

위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).

검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
  [ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
  통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
  eslint 통과. e2e accessibility·typography·reference-form·reference-save
  chromium 27/27.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
2026-11-01 23:20:31 +09:00
DongHyeonka 298201f3ee perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.

고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
  계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
  contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
  계약, adapter contribution, contract contribution)는 feature-runtime.ts로
  옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
  route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
  모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
  화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
  모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
  적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
  registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
  (installed-contract-contributions.ts). 선언하지 않은 contract package를
  적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
  installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
  registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
  둔다. src에서 후자를 import하면 새 아키텍처 규칙
  boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
  route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
  청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
  기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
  플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
  템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
  feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
  render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
  애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).

버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
  lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
  버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
  공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
  -60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
  i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
  초기로 세어 218,303 B가 됐다.

위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
  실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
  그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
  테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
  구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
  재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
  비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
  총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
  installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
  때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
  98.8%다.

수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B

검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
  equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
  tests/integration tests/contract tests/runtime-schema tests/architecture
  tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
  109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
  boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
  check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
  55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
  pnpm 경로의 check:bundle, test:system

BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
  loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
  (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
  만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
  codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
  16-structure-patterns.md 9절
2026-11-01 21:57:53 +09:00
DongHyeonka 9363fa84e3 refactor(examples): 예제 화면 머리글의 반복 "예제" 라벨을 지운다 (UI-06)
예제 화면 4곳이 제목 위에 같은 "예제" 라벨을 달았다. 이미 예제 메뉴
묶음 안에 있는 화면이라 정보가 없고, 예제를 복사하면 이 구성도 따라간다.

예제 화면의 eyebrow만 지웠다. PageHeader의 eyebrow 속성은 남겼다.
접근 상태 화면과 홈은 의미 있는 라벨을 쓴다. 검사는 넣지 않았다.
지울 수 있는 예제 화면의 문구라 검사 비용이 더 크다.

위험: 없음. 예제 화면은 i18n 검사 대상이 아니다.
검증: lint, check:types:app 통과. 시각 골든에 반영했다.
2026-11-01 18:34:28 +09:00
DongHyeonkaandClaude Opus 5.5 38db97a564 refactor(presentation): route status screens share one surface family (Q-6.8-10)
Route-level loading (Suspense fallback, context gateway, chunk check) now
renders LoadingSurface, which gains optional visible copy; route-level
auth-required, integration-required, invalid-address, disabled-feature,
failure and 404 screens render StatusPage, which gains an optional
`surface` marker and children slot. Visible copy, h1 headings, data-surface
markers and alerts are unchanged; the 404 home link is a router link.
The unlabelled context gateway loading now has an accessible name.

Session buttons in the shell, the auth-required screen and the auth example
share useSessionAction: one pending/failed state and sign-in returns to the
current URL including its hash (the auth example dropped the hash).
PageActionBar keys actions by position so a pending label does not remount
the pressed button.

The home and platform overview release loaders now handle a rejected
summary instead of showing "checking" forever.

Pinned first with tests/component/route-status-surfaces.test.tsx (RED: auth
example hash and both loaders; loading, auth-required, shell session and
404 link characterized before the change), plus the lane gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:44:38 +09:00
donghyeon-ka 5cc41467ae refactor: 프론트 템플릿 리펙토링 2026-09-18 15:16:58 +09:00
DongHyeonkaandClaude Opus 5 711d61e73f feat: make product features a declared selection with a runtime kill switch
Which features a build contains was not a decision anybody could express. The
reference feature was spread directly into the route, API, schema, codec and
adapter registries, so shipping without it meant editing five files by hand and
hoping nothing still referred to it — and there was no way at all to take it out
of service on a running deployment. The removability gate proved the editing
worked; nothing made it a choice.

There is now one manifest. `VITE_PRODUCT_FEATURES` narrows it at build time and
`FEATURE_OVERRIDES` in the runtime document takes an installed feature out of
service without a rebuild. Every registry composes from the manifest, and a test
fails if a new one forgets to.

Both inputs are subtractive, and the vocabulary is what enforces it rather than
a check somewhere downstream: the override enum has no `ENABLED`, and a
build-time selection naming something the source tree does not declare is
refused instead of ignored. A configuration document that could name a feature
into existence would be a configuration document choosing which code runs.

Disabling is not just hiding. Withdrawing a route from navigation would leave a
typed deep link that still mounts the feature, so the router refuses it too and
answers with a surface that says the deployment switched it off. The platform
overview now distinguishes the three states an operator actually needs: serving,
switched off, and not in this build.

What this is not: an env var does not shrink the bundle. A static import cannot
be undone by a value, and making the import graph itself depend on a
configuration string is the thing §3.5 exists to prevent — measured, `none`
changes the output by 58 bytes. Physical removal remains FE-GATE-020's job, and
the code comments say so rather than implying otherwise.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 20:45:19 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 13f28ef811 feat: add design system platform 2026-07-26 15:49:07 +09:00
donghyeon-ka 3581ead595 feat: provide reusable UI and state galleries 2026-07-25 23:59:12 +09:00
donghyeon-ka baeda39057 feat: assemble responsive app shell navigation 2026-07-25 23:52:34 +09:00