@naeil/ui 0.8.0 → 0.10.0

package/docs/design/v2-migration.md

@@ -2,21 +2,21 @@
 
 이 안내는 `@naeil/ui`의 기본 모양과 재사용 규칙을 설명한다. 패키지 소비와 소비 사이트 배포는 별도 작업이다.
 
-**0.7.1 npm 게시·registry 검증 완료 — 2026-10-23.** 현재 게시된 기준 버전은 **0.7.1**이다. 이 유지보수 안내는 canonical `NaeilFooter`, `NaeilHeaderAccountControl`, `/release` 식별자와 기존 1600px 프레임을 함께 다룬다. 0.7.0은 미게시 후보이며, 처음 게시된 0.7.x 버전은 0.7.1이다. 독립된 새 React/Next registry 설치에서 동결 파일 139개와 타입·프로덕션 빌드·브라우저 검증이 통과했다. hosted Docs와 상시 배포 활성화는 별도 실행 기록으로 확인한다. UI v2는 디자인 세대 이름이며 npm 2.0을 뜻하지 않는다. 동결 패키지 소스·archive, 별도 검토한 Docs 소스와 실제 게시·배포 결과는 [릴리스 정책](../package-release.md#publication-and-deployment)에서 구분한다.
+**정확한 0.8.0 npm 게시·archive 일치 검증 완료 — 2026-10-29.** registry 태그는 `latest=0.7.2`, `next=0.8.0`이며 0.8.0 archive는 동결된 139파일과 일치한다. Home API는 0.8.0에 포함된다. 현재 소스의 **0.9.0은 미게시 후보**이며 root 예약 기본값을 추가한다. hosted Docs와 소비 서비스 배포는 별도 기록이다. [릴리스 정책](../package-release.md#publication-and-deployment)을 따른다.
 
 ## 시작하기
 
 React 19/ReactDOM 19와 Tailwind 4 앱에서 `/ui` 또는 선택적 `/naeil-header`·`/naeil-footer`를 사용한다. API 키와 Next.js는 필요 없다. 검증한 registry 버전을 고정해 설치한다.
 
 ```sh
-pnpm add --save-exact @naeil/ui@0.7.1
+pnpm add --save-exact @naeil/ui@0.8.0
 ```
 
-registry의 0.7.1 archive는 동결 릴리스 archive와 바이트가 일치한다. archive에 포함된 안내는 준비 시점의 기록이므로 현재 설치에는 이 유지보수 안내를 따른다. 로컬 개발에서는 저장소에서 `pnpm build:pkg`와 `npm pack --ignore-scripts --pack-destination /tmp`를 실행하고 `/tmp/naeil-ui-0.7.1.tgz`를 설치한다. 현재 소스의 개발용 pack은 동결 릴리스 archive와 다르므로 게시 파일을 대체하지 않는다. [독립 React 예제](https://github.com/naeil-dev/naeil-ui/tree/main/examples/react)와 [검증/릴리스 정책](../package-release.md)을 참고한다.
+registry의 0.8.0 archive는 동결 릴리스 archive와 바이트가 일치한다. archive에 포함된 안내는 준비 시점의 기록이므로 현재 설치에는 이 유지보수 안내를 따른다. 로컬 개발에서는 저장소에서 `pnpm build:pkg`와 `npm pack --ignore-scripts --pack-destination /tmp`를 실행하고 현재 미게시 후보인 `/tmp/naeil-ui-0.9.0.tgz`를 설치한다. 현재 소스의 개발용 pack은 동결 릴리스 archive와 다르므로 게시 파일을 대체하지 않는다. [독립 React 예제](https://github.com/naeil-dev/naeil-ui/tree/main/examples/react)와 [검증/릴리스 정책](../package-release.md)을 참고한다.
 
 공통 UI 소비에는 Supabase, 21st 또는 다른 API 키가 필요하지 않다. React/ReactDOM 19는 소비 앱의 peer이며, Next 15/16과 next-intl 4는 호환 경로에 필요한 선택적 peer다. next-themes 0.4와 tailwind-merge 3은 공통 런타임 의존성으로 설치된다. 사이트의 Supabase·MDX·Three 의존성과 코드는 공통 소비 경계에서 제외했다.
 
-버전을 생략한 설치는 registry의 latest 태그를 따른다. 2026-10-23에 latest는 0.7.1로 확인했다. 검증한 버전을 유지하려면 0.7.1을 명시한다. 업그레이드 전에 [변경 기록](../../CHANGELOG.md)을 확인한다.
+버전을 생략한 설치는 registry의 latest 태그를 따른다. 2026-10-29에 latest는 0.7.2, next는 0.8.0으로 확인했다. Home API를 사용하려면 검증한 0.8.0을 명시한다. 업그레이드 전에 [변경 기록](../../CHANGELOG.md)을 확인한다.
 
 Tailwind 4를 사용하는 앱의 전역 CSS에서 공통 스타일을 한 번 불러온다.
 
@@ -29,6 +29,10 @@ Tailwind 4를 사용하는 앱의 전역 CSS에서 공통 스타일을 한 번
 
 이미 Tailwind와 기본 스타일을 구성한 앱은 `@naeil/ui/theme.css`와 `@naeil/ui/components.css`를 함께 불러올 수 있다. 컴포넌트 CSS에는 크기·포커스·밀도·포털·reduced-motion 규칙이 있으므로 theme.css만으로 전체 v2 모양이 완성되지는 않는다.
 
+0.9.0 후보부터 두 CSS 경로의 `components.css`가 `html { scrollbar-gutter: stable }`과 Radix 이중 보상 제거를 제공한다. classic은 한쪽 공간을 예약하고 overlay는 0px이다. `<html data-naeil-scrollbar-gutter="auto">`를 첫 paint 전에 선언하면 root 예약과 lock 보정을 함께 끈다. theme-only/JS-only는 문서 정책을 바꾸지 않는다. 본문 바깥 여백/custom scroller/helper class는 별도 소비자 통합이나 opt-out이 필요하다. [채택된 계약](https://github.com/naeil-dev/naeil-ui/blob/434b7d07235316097ca3a55265ee02c1422b0cfd/docs/superpowers/specs/2026-10-29-page-root-scrollbar-gutter.md)과 [layout guide](../components/application-layout.md)의 비교·fallback·일본어 320px F3 wrap 규칙을 따른다.
+
+CSS import를 `layer(ui)` 같은 named layer로 감싸지 않는다. 그러면 dependency의 unlayered `--removed-body-scroll-bar-size`가 이겨 classic에서 15px로 남을 수 있다. opt-out 후 `@layer base { html { scrollbar-gutter: stable; } }`는 패키지 attribute selector보다 약하므로, layer 밖에 `html[data-naeil-scrollbar-gutter="auto"] { scrollbar-gutter: stable; }`를 쓰거나 패키지 import 뒤의 같은 base layer에서 이 attribute selector를 쓴다. 이때 lock 보상은 소비자가 책임진다. Classic modal scrim은 예약된 gutter 띠를 덮지 않으며, 0.9.0에서 scrim 스타일을 바꾸지 않는다. 자세한 예시와 적용 범위는 [layout guide](../components/application-layout.md#width-contract)를 따른다.
+
 ```tsx
 import { Button, Input, Select, SelectTrigger, SelectValue,
   SelectContent, SelectItem, Switch, Checkbox } from '@naeil/ui/ui';

package/docs/package-release.md

@@ -1,6 +1,6 @@
 # Package verification and release policy
 
-**Published baseline: 0.7.2** (`40a3928`, registry archive SHA-256 `b7919ed182307c5c3b48515f68567b0e4f51c611c86b7acf8861e769f596e2ec`, 139 files). **0.8.0 is an unpublished candidate** adding the canonical Home menu/brand/status/controlled-sheet API and package-owned chrome typography. Contract version stays `1` only while every existing invariant passes. The historical 0.7.1 publication and immutable archive below remain unchanged. UI v2 names a design generation, not an npm major. Hosted Docs and per-service activation retain separate receipts. Version-scoped installation is in the [README](../README.md#use-the-ui).
+**Published exact baseline: 0.8.0** (source/tag `3f708e27d05212af7f7a5be769f13f871e8d10c7`, archive SHA-256 `6feb5a8cd50265ace584a0855432683b4127119377e08235282eaebd27081084`, 139 files). Registry download matched that frozen archive on 2026-10-29; tags were `latest=0.7.2`, `next=0.8.0`. Its Home menu/brand/status/controlled-sheet APIs and package-owned chrome typography are published. **0.9.0 is an unpublished candidate** for the adopted page-root frame rule. Contract version remains `1` only if all invariants pass. Historical releases/archives remain immutable; hosted Docs and service activation require separate receipts.
 
 ## Architecture
 
@@ -31,6 +31,17 @@ pnpm exec playwright install chromium firefox webkit
 pnpm test:browser
 ```
 
+The chrome fixture server and standalone navigation sample use `NAEIL_UI_FIXTURE_PORT`, with the unchanged default defined in `scripts/chrome-fixture-config.ts` in the repository. The same module supplies every fixture URL. An explicit port also isolates generated fixtures, test results and HTML reports by port; leave it unset to retain the existing CI paths. Choose a free integer port from 1 to 65535.
+
+For two concurrent fixture-only runs in one worktree, use separate terminals:
+
+```sh
+NAEIL_UI_CHROME_ONLY=1 NAEIL_UI_FIXTURE_PORT=16081 pnpm test:browser e2e/page-frame.spec.ts --project=chromium
+NAEIL_UI_CHROME_ONLY=1 NAEIL_UI_FIXTURE_PORT=16082 pnpm test:browser e2e/page-frame.spec.ts --project=chromium
+```
+
+`NAEIL_UI_CHROME_ONLY=1` skips the unrelated Storybook server. Full suites still use `NAEIL_UI_STORYBOOK_PORT` for Storybook. Do not overlap an unset-port run (which cleans the default `test-results` directory) with custom-port runs in the same worktree. The standalone sample uses the same port setting: `NAEIL_UI_FIXTURE_PORT=16083 pnpm exec tsx scripts/serve-navigation-sample.ts`. Stop standalone previews after use; Playwright stops its own fixture server.
+
 `check:package:boundary` inspects an actual `npm pack --ignore-scripts` archive for every declared export, runtime dependencies, source aliases, relative imports, required CSS/tokens/documents/notices and forbidden website payload. `check:consumers` separately installs that tarball with npm into two temporary directories. It builds the reusable React example with Vite/Tailwind, type-checks with library checks enabled, imports shared deep modules, checks SSR and CSS, and asserts Next/Supabase/Three are absent. A separate Next production build exercises root exports and the deep paths observed in the reachable Next consumer, with consumer-owned messages and no auth backend. Neither fixture uses repository dependency symlinks. Network access is needed for uncached npm dependencies; temporary installs are removed on completion or failure.
 
 For a frozen release candidate, both archive-producing checks can enforce the reviewed SHA-256 before extraction or consumer installation:
@@ -104,7 +115,7 @@ The immutable npm archive's bundled guides are the release-preparation snapshot.
 
 ### Release procedure
 
-Maintained Storybook resolves relative Markdown guide links against the published `v0.7.2` source `40a3928e24cd2f0141be3e605eed0a75260938fd`. The unpublished 0.8.0 candidate keeps that published guide-link target until a separately reviewed Docs release. That tag is independent of the reviewed Docs deployment SHA. Hosted verification checks that the pinned links resolve; the unpublished `v0.7.0` tag is not a valid target. Historical foundation/source-authority links remain at their original revisions. Freeze subsequent documentation changes separately from immutable release archives.
+Maintained Storybook resolves relative Markdown guide links against the published `v0.7.2` source `40a3928e24cd2f0141be3e605eed0a75260938fd`. The published 0.8.0 archive and 0.9.0 candidate keep that published guide-link target until a separately reviewed Docs release. That tag is independent of the reviewed Docs deployment SHA. Hosted verification checks that the pinned links resolve; the unpublished `v0.7.0` tag is not a valid target. Historical foundation/source-authority links remain at their original revisions. Freeze subsequent documentation changes separately from immutable release archives.
 
 The authorized 0.3.0 release completed main merge, npm 0.3.0, a GitHub Release and hosted Docs as recorded above. The release maintainer performs external authentication and publication; documentation preparation does not itself execute those operations. The automatic verification workflow does not publish or deploy. Record native/manual observations with their actual scope and carry unrun checks as limitations; do not substitute automated WebKit/axe checks or publication authorization for human certification.
 
@@ -121,15 +132,17 @@ npm publication, GitHub Releases, main merge and hosted Docs are distinct operat
 `vercel.json` disables Git deployments only for `feat/public-ui-readiness`. Other branches retain Vercel's default behavior, so merging or pushing another branch requires a separate deployment decision. The automatic GitHub Actions checks are verification-only; enabling repository workflows is not evidence of a hosted site or approved release.
 
 
-### Manual exact-archive preparation for 0.8.0
+### Manual exact-archive preparation for 0.9.0 (following 0.8.0)
 
-The standing `scripts/rollout/prepare-release.mjs` accepts consecutive stable 0.7.x releases only. Do not change rollout policy, `release.json` or the chrome contract to admit 0.8.0. Use the manual release procedure above: complete P1–P7 from the `docs/superpowers/specs/2026-10-28-canonical-home-chrome.md` acceptance contract, freeze the exact source SHA/archive, then run boundary and clean React/Next checks with `NAEIL_UI_EXPECTED_ARCHIVE_SHA256`. The paired browser gate accepts `NAEIL_UI_CHROME_PACKAGE=/absolute/extracted/package` to exercise that exact archive, alongside SHA-512-pinned B1. It retains numeric differences and screenshots for human review; new renders never replace expectations automatically.
+The standing `scripts/rollout/prepare-release.mjs` accepts consecutive stable 0.7.x releases only. Do not change rollout policy, `release.json` or the chrome contract to admit 0.9.0. Use the manual release procedure above: complete G1–G7 from the [adopted root-frame contract](https://github.com/naeil-dev/naeil-ui/blob/434b7d07235316097ca3a55265ee02c1422b0cfd/docs/superpowers/specs/2026-10-29-page-root-scrollbar-gutter.md), including the retained 0.8.0 P1–P5 regressions, freeze the exact source SHA/archive, then run boundary and clean React/Next checks with `NAEIL_UI_EXPECTED_ARCHIVE_SHA256`. The paired browser gate accepts `NAEIL_UI_CHROME_PACKAGE=/absolute/extracted/package` to exercise that exact archive, alongside SHA-512-pinned 0.7.2 and SHA-256-pinned frozen 0.8.0. Reference-only root/lock CSS adjustments are separate hashed fixture files; immutable archives stay untouched. Both classic and overlay jobs require actual probes. Viewport captures have geometry guards; all acceptance measurement precedes any terminal fullPage capture. It retains numeric differences and screenshots for human review; new renders never replace expectations automatically.
 
-The candidate adds `appNavigation`, `brandSuffix`, `statusSlot` and controlled/observer sheet props; see [NaeilHeader](components/naeil-header.md) for supported host CSS and consumer-supplied fonts. Default catalog/blog/legacy overrides must remain equivalent to B1. Home uses the complete default toolbar and full footer. A source rollback must revert adapter, CSS and manifest/lock together; pin-only rollback cannot support the new API.
+Before npm publication, the separately approved source push must make the linked adopted contract at `434b7d07235316097ca3a55265ee02c1422b0cfd` public. Immediately after that push, verify an anonymous HTTP 200 for the exact guide URL and confirm its status says **rev 1, adopted 2026-10-29**. Local link/boundary checks do not establish public reachability. Source push may trigger Vercel deployment and retains its own approval boundary.
+
+Published 0.8.0 adds `appNavigation`, `brandSuffix`, `statusSlot` and controlled/observer sheet props; see [NaeilHeader](components/naeil-header.md) for supported host CSS and consumer-supplied fonts. Default catalog/blog/legacy overrides must remain equivalent to B1. Home Workspace uses the default account toolbar and full footer; LoginGate omits auth/separator and footer (F1/F2). A source rollback must revert adapter, CSS and manifest/lock together; pin-only rollback cannot support the new API.
 
 The shipped guide records the B1 empty-menu desktop limitation, controlled-mobile asynchronous account/focus handoff versus desktop/uncontrolled selection-time behavior, and Home's confirmation-owned desktop cancel fallback. Compatibility comparisons normalize only the contract markers/language/release identity and Radix-generated IDs; SVG/Logo and consumer IDs stay exact. Source or guide corrections require a new archive and exact-archive gates; earlier candidate digests are historical evidence.
 
-Package publication, tag, GitHub Release, main merge and Home deployment each require separate explicit approval. naeil.dev imports this repository's source, so a main merge upgrades its default header to 0.8.0 and is held until the owner approves that site impact and timing. Estimate/Jev stay on 0.7.2, and STOP remains. A prepared archive or local gate result grants no publication or rollout authority.
+Package publication, tag, GitHub Release, main merge and Home deployment each require separate explicit approval. naeil.dev imports this repository's source, so a main merge upgrades its default header to the 0.8.0 API/style plus the 0.9.0 root/lock rule (including Japanese 320px classic F3 wrap) and is held until the owner approves that site impact and timing. Estimate/Jev stay on 0.7.2, and STOP remains. A prepared archive or local gate result grants no publication or rollout authority.
 
 ## Storybook preview artifact
 
@@ -164,3 +177,11 @@ After the reviewed Docs deployment, verify the manager and iframe under `/naeil-
 Normal builds are network-independent after dependency installation. Vite collects notices for actual preview modules; checked-in manager notices conservatively cover named embedded packages and versions from Storybook 10.4.6's original source lock. `check-storybook` fails if a named embedded module lacks a full notice. Four vendored tiny modules have no embedded version in that lock/comments; their original npm notice source is explicitly marked, without an exact-version claim. The exact use-composed-ref@1.4.0 tarball/repository provides MIT metadata but no standalone notice; its metadata plus full declared terms are retained without inventing a year/holder. The client-only@0.0.1 React marker retains its exact metadata and the original React MIT notice. Other missing notices fail the build; no generic MIT fallback passes arbitrary packages.
 
 For a Storybook dependency upgrade, first build the new preview to obtain fresh manager scripts, then run `python3 scripts/refresh-storybook-notices.py` (read-only npm/source retrieval plus a local notice-file update), review its source/notice changes, and rebuild. The refresh is opt-in and needs network; the build never retrieves legal/reference material silently. Keep all generated `licenses/` JSON/text files with the preview. The standalone React consumer likewise emits exact installed code/font notices with its production output.
+
+### 0.9.0 frame preparation gates
+
+The owner adopted rev 1 on 2026-10-29 for local implementation and verification, including the root opt-out and F3 wrap. Both CSS graphs, theme/JS-only controls, opt-out and false-support branch, short/long route frames, body/content/fixed anchors under nested Radix locks, capture guards, frozen 0.8.0 comparisons and clean installed React/Next production CSS must pass before freezing. The false-support fixture tests a CSS branch, not a real unsupported engine. `build-chrome-fixtures.ts` alone is not clean-consumer proof; `check-consumers.ts` independently installs/builds/exercises both paths in each framework.
+
+Run the normal checks above serially, plus the two deterministic Chromium mode jobs using B0's process-local wrappers, `NAEIL_UI_SCROLLBAR_MODE=classic|overlay` and `NAEIL_UI_SCROLLBAR_WRAPPERS=/absolute/wrapper-directory`. Their 15/0px overflow probes and stable-root frame probes must pass; the diagnostic `--enable-automation` flag exposes actual argv through CDP without changing the mode probe. Preserve exact source/archive SHA-256/SRI/inventory and per-gate commands/exit codes outside the archive. Repeat archive-dependent checks using `NAEIL_UI_CHROME_PACKAGE=/absolute/extracted/package` and `NAEIL_UI_EXPECTED_ARCHIVE_SHA256`.
+
+This candidate is not published. npm/dist-tag, version tag, GitHub Release, push/main merge (= naeil.dev production), hosted Docs and Home bump/deploy remain separate approvals. Home keeps its local root rule until an approved exact-version upgrade removes it; rollback restores manifest/lock and local root rule together. Estimate/Jev remain on 0.7.2 and STOP remains in force.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naeil/ui",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "sideEffects": [
@@ -145,12 +145,36 @@
     "./release": {
       "types": "./dist/lib/ui-release.d.ts",
       "import": "./dist/lib/ui-release.js"
+    },
+    "./naeil-locale": {
+      "types": "./dist/naeil-locale/index.d.ts",
+      "import": "./dist/naeil-locale/index.js"
+    },
+    "./naeil-locale/client": {
+      "types": "./dist/naeil-locale/client.d.ts",
+      "import": "./dist/naeil-locale/client.js"
+    },
+    "./naeil-locale/server": {
+      "types": "./dist/naeil-locale/server.d.ts",
+      "import": "./dist/naeil-locale/server.js"
+    },
+    "./naeil-locale/messages": {
+      "types": "./dist/naeil-locale/messages.d.ts",
+      "import": "./dist/naeil-locale/messages.js"
+    },
+    "./naeil-locale/checker": {
+      "types": "./dist/naeil-locale/checker.d.ts",
+      "import": "./dist/naeil-locale/checker.js"
+    },
+    "./naeil-locale/chrome": {
+      "types": "./dist/naeil-locale/chrome.d.ts",
+      "import": "./dist/naeil-locale/chrome.js"
     }
   },
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "build:pkg": "pnpm build:release && pnpm check:brand && tsup && tsup --config tsup.deep.config.ts && tsx scripts/fix-deep-imports.ts && pnpm build:tokens && node scripts/build-release-entry.mjs",
+    "build:pkg": "pnpm check:messages && pnpm build:release && pnpm check:brand && tsup && tsup --config tsup.deep.config.ts && tsup --config tsup.locale.config.ts && tsx scripts/copy-locale-json.ts && tsx scripts/fix-deep-imports.ts && pnpm build:tokens && node scripts/build-release-entry.mjs && pnpm check:locale:package",
     "start": "next start",
     "lint": "eslint",
     "test": "vitest run",
@@ -168,11 +192,13 @@
     "check:brand": "tsx scripts/build-brand.ts --check",
     "build:release": "node scripts/build-ui-release.mjs",
     "rollout": "node scripts/rollout/rollout.mjs",
-    "test:rollout": "node --test scripts/rollout/*.test.mjs scripts/verify-ui-production.test.mjs"
+    "test:rollout": "node --test scripts/rollout/*.test.mjs scripts/verify-ui-production.test.mjs",
+    "check:messages": "tsx scripts/check-locale-messages.ts",
+    "check:locale:package": "tsx scripts/check-locale-package.ts"
   },
   "peerDependencies": {
     "next": "^15 || ^16",
-    "next-intl": "^4",
+    "next-intl": "4.14.8",
     "react": "^19",
     "react-dom": "^19"
   },
@@ -184,7 +210,9 @@
     "radix-ui": "^1.4.3",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "@formatjs/icu-messageformat-parser": "3.5.1",
+    "server-only": "0.0.1"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.13.0",
@@ -212,7 +240,7 @@
     "eslint-config-prettier": "^10.1.8",
     "gray-matter": "^4.0.3",
     "next": "16.1.7",
-    "next-intl": "^4.8.3",
+    "next-intl": "4.14.8",
     "pretendard": "^1.3.9",
     "prettier": "^3.8.1",
     "react": "19.2.3",

package/src/styles/components.css

@@ -1,3 +1,20 @@
+@layer base {
+  html:not([data-naeil-scrollbar-gutter="auto"]) {
+    scrollbar-gutter: stable;
+  }
+  html[data-naeil-scrollbar-gutter="auto"] {
+    scrollbar-gutter: auto;
+  }
+}
+
+/* The root already reserves the gap. Keep Radix's lock, without a second gap. */
+@supports (scrollbar-gutter: stable) {
+  html:not([data-naeil-scrollbar-gutter="auto"]) > body[data-scroll-locked] {
+    margin-right: 0 !important;
+    --removed-body-scroll-bar-size: 0px;
+  }
+}
+
 @layer components {
   .ui-navigation {
     position: relative;