@pieai/swimmer-ui-kit 2.13.0 → 3.0.0-rc.1

package/CHANGELOG.md

@@ -5,7 +5,72 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
 ## Unreleased
 
-### 2.13.0 candidate — WO-UI-1
+## 3.0.0-rc.1 — 预发布候选（2026-10-03）
+
+本候选只使用 npm next，latest 保持 2.14.0；不会自动升级消费产品。发布结果以单次 npm-publish 回执为准，失败不重复发布。它取代下方历史本地3.0.0候选，仍是干净断代，不提供兼容层。
+
+- S7：删除五个未公开的闲置组件，选择指南覆盖全部公开值，并有缺项反例门禁。
+- S8：移除351个旧图片素材/工具文件与资源初始化API；48个24px viewBox线条图标提供内联组件与可裁剪纯数据入口，保留实际35个旧名字并增加13个约定名字。需要彩色黏土插图的产品须在升级前自行复制所需图片。
+- S9：默认中文字体改为OFL1.1资源圆体，修改内部名称为Swimmer Rounded CN；四字重464个WOFF2块，共23,612,344字节，按字符按需请求；纯英文页面不请求中文块。
+- S10：四个表面层级和一个浮层阴影收敛，删除旧panel变量别名；十二组合色彩与对比度契约保持。
+- S11：GameButton/GameIconButton支持原生链接、路由注入和真实ref，新增32px小号；LiquidPopover提供受控状态、焦点、Escape/外部关闭及窄屏静态降级。
+- S12：展示组件使用静止水滴；Badge为24px/12px/600。进度条为10px轨道和潮汐弯月液面，数值变化后600ms休眠，零待机重绘、不占滤镜预算；删除GameProgress tone。
+- S13：组件入口及React共享分块保留client boundary，纯图标数据和声明/CSS不加。实际Next16.3.8消费者检查Server直接导入、Client交互、水合、Next Link和390px减少动态。
+- S14：根入口129个名字，生成迁移表覆盖179个名字变化与29个参数/样式变化。发布门禁新增真实Next消费者和11项标签保护测试；预发布确认next准确且latest未变，不把registry错误当作版本不存在。
+
+完整迁移及各产品接入范围见[3.0迁移表](docs/reference/migration-3.0.md)。
+
+## 3.0.0 — 历史本地候选，已由 rc.1 取代（2026-10-02）
+
+这是干净断代，不提供旧接口或旧主题兼容层。现有产品保持各自的精确版本；
+本轮只交付本地候选，需 Claude 在 University 验收并由 Owner 明确批准后才发布 npm。
+完整逐项说明见 [3.0 迁移表](docs/reference/migration-3.0.md)。
+
+### 外观与交互
+
+- 普通控件统一为路径绘制的二维水滴：无底唇、投影、渐变或液体阈值滤镜。
+  装饰背景按下横向摊开、回弹后休眠，文字和原生点击区域不缩放；缓波封顶 1.4px。
+- 六套风格 candy / pastel / mist / grey / outline / ink 全部保留，默认 pastel。
+  风格轴 data-game-ui-style 与 light / dark 明暗轴独立，十二套语义块自动检查完整性和对比度。
+- GameButton primary 是唯一的潮汐液体 CTA，一屏最多一个；涟、引导和 LiquidReveal 共用薄液体材质。
+  旧 surface / liquidFinish 轴、普通控件的液体外观与按钮铜牌皮肤移除；静态头像铜牌相框保留。
+- 按 Owner 委托 Claude 的评审决定：危险按钮保留风格普通底色、只用红字；outline / ink 同时用红边。
+  success 等含义色在灰阶与两套包边仍去色。开关轨道和圆点使用语义色，不另画黑色描边。
+- 换风格/明暗保留原生输入、选区、焦点与状态；减少动态、强制配色、禁用、取消事件和卸载都有回归覆盖。
+
+### 断代与组织
+
+- 深色值 night 改为 dark，包括选择器、dataset 和 closest 判断；包内 CLI 报告旧值，不提供渲染兼容。
+  已知迁移对象包括 University、Directing、FlowToFeel、SwimmerParty-Website、SwimmerAuthKit 的 auth-captcha。
+- 删除 OwnMySpace 专用建造、施工、资产库及放置工具，删除零使用金属按钮及其 WebGL 预算。
+  University 已在用的 GameMaterialSwatches 保留为通用配色控件，相关类型去掉地形命名。
+- 融化、弯曲与图像接触溶解移到 ./liquid-effects；展厅移到 ./preview。
+  默认入口和 ./liquid-presence 不含这两个可选实现，所有入口共用一份液体资源预算。
+- 根入口由 295 个名字收窄到 135 个，逐项迁移表覆盖删除、改名、子入口、参数与样式。
+  组件按职责归位，样式就近维护；styles.css 的公开引入路径与全部公开图标路径保持。
+- 当前说明收敛为七个入口；旧规格、业务报告、发布回执和原始视觉证据归档，原图不重新生成替代。
+  包检查针对实际 tarball 执行；本机候选、npm 发布与消费产品验收分开记录。
+
+## 2.14.0 — 2026-10-01
+
+- Fix the stair-stepped top edge on every glossy liquid body: the gloss pass
+  added its light's alpha to the body's, so a half-covered edge pixel turned
+  opaque wherever the highlight was bright. The light is now clipped to the
+  body eroded by a pixel and feathered; the highlight itself is unchanged.
+- Add `LiquidFill`: `LiquidGroup` and `LiquidSurface` take `fill={{ top,
+  bottom?, sheen? }}` for the coloured-liquid light (a narrow brighter band at
+  the top, a deeper foot). Colours may be tokens; bands are CSS `color-mix`.
+- `LiquidSurface` takes `gloss` and `outline={{ amplitude, lobes? }}` to
+  override its form's light and rest lobing.
+- 涟 (`LiquidPresence`, `LiquidReveal` material surface): the face carries its
+  light in the fill (top to foot) and casts a soft contact shadow along its
+  own outline through the new `--game-ui-liquid-presence-shadow` token; the
+  material panel drops its raised rim and stroke. The dark surface is unchanged.
+- Compatibility: additive API; visual change to glossy edges and to 涟's
+  material face. Owner approved publication on 2026-10-01 (University
+  session, "品牌UI包要发布成新版"), with the repository kept to one main line.
+
+## 2.13.0 — 2026-09-29
 
 - Add opt-in `surface="plaque"` to `GameButton`, `GameIconButton` and
   `GameAvatar`, with opaque light/night copper token pairs derived from
@@ -20,8 +85,8 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
   modal-test screenshots to `.devspace-visual/`, preserving retained scratch
   evidence and all existing assertions.
 - Compatibility: additive only; no new dependency or React peer change.
-  This candidate is not published: Owner's private-publication instruction
-  needs clarification before using this repository's public npm workflow.
+  Published through the existing npm Trusted Publishing workflow after
+  Owner clarified public publication (AuthKit remains private).
 
 ## 2.12.0 — 2026-09-29
 
@@ -276,7 +341,7 @@ registration, routing and `LiquidCtaTransition`. Its old uniform `scale=0.95`
 / `bouncy` motion deliberately changes to the kit's existing `press` behavior
 only when that custom wrapper is migrated. Preserve transition source geometry,
 callback ordering and tests; do not discard the 823-line transition as if the
-kit had absorbed it. See the [upgrade playbook](docs/reference/usage-and-upgrade-playbook.md)
+kit had absorbed it. See the [archived 2.x upgrade playbook](docs/archive/reference-2.x/usage-and-upgrade-playbook.md)
 for exact commands, CSS ownership, acceptance cases and rollback.
 
 This is a **minor**: additive opt-in layout and discovery, not a public-export

package/LICENSE

@@ -14,28 +14,25 @@ non-exclusive, non-transferable, revocable license to:
 
 You may not:
 
-1. modify or create derivative works from the source code or visual assets;
-2. redistribute, sublicense, publish, sell, or provide this package or its
-   visual assets as a standalone library, asset pack, template, or competing
-   product;
-3. extract or redistribute the visual assets separately from an application
-   that uses this package;
-4. remove or alter copyright, license, attribution, or proprietary notices;
-   or
-5. use PieAI names, logos, or trademarks to imply endorsement.
+1. modify or create derivative works from PieAI's source code;
+2. redistribute, sublicense, publish, sell, or provide this package as a
+   standalone library, template, or competing product;
+3. remove or alter copyright, license, attribution, or proprietary notices;
+4. use PieAI names, logos, or trademarks to imply endorsement.
 
 Distribution of bundled or minified application output is permitted only when
 this package is an inseparable dependency of that application and is not
-offered as a reusable library or asset collection.
-
-This license does not grant ownership of any source code, visual asset,
-trademark, or other intellectual property. Third-party materials, if any,
-remain subject to their respective rights and terms.
-
-THE SOFTWARE AND ASSETS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
-PIEAI WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
-FROM THE SOFTWARE, ASSETS, OR THEIR USE.
+offered as a reusable library.
+
+This license does not grant ownership of any source code, trademark, or other
+intellectual property. Third-party materials listed in NOTICE, including fonts
+and icon path data, remain under their respective licenses. None of the
+restrictions above limits rights granted by those third-party licenses.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. PIEAI WILL NOT BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE SOFTWARE
+OR ITS USE.
 
 Any use outside these terms requires prior written permission from PieAI.

package/NOTICE

@@ -1,40 +1,9 @@
 Third-party notices
 ===================
 
-Liquid-metal dispersion shader
-------------------------------
-Portions of the WebGL2 renderer in `src/liquidMetalWebGL.ts` are adapted
-from ThreeUI (https://github.com/MengTo/threeui), Copyright (c) 2026
-Meng To, licensed under the MIT License.
-
-The upstream ships the shader inside a standalone HTML page and embeds
-that page in an iframe. This package inlines the shader so colours can
-follow `--game-ui-*` tokens, adds a CSS renderer as the default, and
-caps simultaneous WebGL contexts.
-
-The MIT License text for that material:
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 Liquid-gooey Morph/Bend adaptations
 -----------------------------------
-The liquid primitive in `src/LiquidGroup.tsx` and its supporting filter,
+The liquid primitive in `src/liquid/LiquidGroup/LiquidGroup.tsx` and its supporting filter,
 geometry, shadow, spring, evolve, and Move modules includes direct local
 adaptations from the `liquid-gooey` package in the Libraries repository
 (https://github.com/Jakubantalik/Libraries/tree/main/packages/liquid-gooey),
@@ -51,7 +20,7 @@ envelope for `morph.shape`, its 7px-default content cross-blur for
 `morph.contentBlur`, and its Bend velocity-bowed path, horizontal cap
 deformation, surface-glued tracking, and `--lg-bend-x` / `--lg-bend-y` /
 `--lg-bend-xn` / `--lg-bend-yn` CSS variable outlet. The local implementations
-are in `src/liquidGooeyEvolve.ts` and `src/liquidGooeyMove.ts`; their file
+are in `src/liquid/evolve.ts` and `src/liquid/move.ts`; their file
 headers repeat this source URL, pinned commit, copyright, MIT license, and
 NOTICE pointer. We also adapted the donor's Move center spring, velocity-axis
 stretch, and lagging tail/mid-droplet physics for the selected segmented
@@ -64,7 +33,7 @@ element, so they are not in the SVG filter region or its pad. Inset and
 spread layers remain SVG-resident.
 
 The local implementation also adapts the donor's pairwise image-melt engine in
-`src/liquidGooeyImageMelt.tsx`, including the two-item pairing, measured image
+`src/liquid-effects/melt/ImageMelt.tsx`, including the two-item pairing, measured image
 rects, crisp-face seam masks, two-palette colour mixing, and marbling pass. Its
 contact dissolve masks only `<img>` pixels; text remains in the unfiltered DOM
 content layer. The dissolve math is a scoped adaptation of the donor's contact
@@ -107,7 +76,7 @@ SOFTWARE.
 Liquid-gooey image Melt and contact dissolve
 --------------------------------------------
 Portions of the pairwise image-melt and contact-image dissolve implementation
-in `src/liquidGooeyImageMelt.tsx` are adapted from liquid-gooey by Jakub
+in `src/liquid-effects/melt/ImageMelt.tsx` are adapted from liquid-gooey by Jakub
 Antalik (https://github.com/Jakubantalik/Libraries/tree/main/packages/liquid-gooey),
 Copyright (c) 2026 Jakub, licensed under the MIT License.
 
@@ -152,4 +121,68 @@ SOFTWARE.
 Fonts
 -----
 Baloo 2 and Geist Variable are licensed under the SIL Open Font License.
-See `src/fonts/OFL-Baloo2.txt` and `src/fonts/OFL-Geist.txt`.
+See `src/tokens/fonts/OFL-Baloo2.txt` and `src/tokens/fonts/OFL-Geist.txt`.
+
+Inline SVG icon paths
+---------------------
+48 semantic names are mapped to reviewed Lucide 1.51.0 shapes. The original
+SVG geometry is converted to path-only data by scripts/generate-game-icons.py.
+The source archive SHA-256 and per-icon hashes are in scripts/game-icons-source.json.
+Source: https://github.com/lucide-icons/lucide/tree/1.51.0/icons
+No Lucide runtime library, SVG images, or remote image URLs are distributed.
+The generated geometry retains the following upstream ISC and Feather MIT terms:
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Chinese font subsets: Swimmer Rounded CN
+---------------------------------------
+Derived from Resource Han Rounded CN v0.990 by Cyano Hao, based on Adobe Source Han.
+Copyright 2018-2019 Cyano Hao; Copyright 2014, 2015, 2018 Adobe Systems Incorporated,
+with Reserved Font Name Source. Licensed under SIL Open Font License 1.1.
+These Unicode-range WOFF2 subsets have renamed internal family/full/PostScript
+names and retain original copyright/license metadata. They are not a font-family
+compatibility alias. Exact input hashes and deterministic tools are recorded in
+scripts/zh-font-source.json. The full original OFL text is shipped at
+dist/fonts/zh/OFL.txt (source: src/tokens/fonts/zh/OFL.txt).

package/README.md

@@ -1,175 +1,64 @@
 # @pieai/swimmer-ui-kit
 
-Self-contained clay game UI kit for PieAI web, game, and wrapped
-(mobile/desktop WebView) surfaces. React 19 + TypeScript strict.
-**100% standard CSS** — consumers need no Tailwind, no PostCSS, no CSS
-processor of any kind. The optional `GameHelpTip` uses the existing Floating UI
-dependency; ordinary controls remain native.
-
-Source is publicly readable. Use is governed by the
-[PieAI Limited Use License](./LICENSE), not an open-source license. The visual
-assets may not be extracted, modified, or redistributed as a standalone pack.
-
-- **Start here / 我该用哪个组件？**
-  [Primary button, liquid CTA, forms, panels and other tasks](docs/reference/component-selection-guide.md)
-- Design system truth (tokens, theming, motion, a11y):
-  [Design system guide](docs/reference/design-system-guide.md)
-- Consumer onboarding / upgrade SOP / release checklist:
-  [Usage and upgrade playbook](docs/reference/usage-and-upgrade-playbook.md)
-- Exhaustive reference (not the starting point):
-  [Generated public API inventory](docs/reference/public-api-inventory.md)
-- [Interactive catalog](https://swimmer-ui-kit.pieaistudio.com/): real controls,
-  matte/glossy comparison, theme/state selectors and copyable React examples.
-- [Full reference](https://swimmer-ui-kit.pieaistudio.com/?view=reference) and
-  [liquid form laboratory](https://swimmer-ui-kit.pieaistudio.com/liquid.html).
-  Local: `pnpm dev` and `pnpm storybook`.
-
-## Install
-
-```json
-{
-  "dependencies": {
-    "@pieai/swimmer-ui-kit": "2.6.1"
-  }
-}
-```
+Swimmer 的共享 React UI：普通控件是平面水滴，主线 CTA 是潮汐液体。支持六套风格与独立明暗，表单、焦点、键盘和编辑内容仍由原生 DOM 承接。它不拥有产品数据、模型调用、账号验证或支付。
 
-Peer dependencies: `react >=19` and `react-dom >=19` — nothing else.
-Pin the exact version (no `^`) — upgrades are explicit, reviewed actions.
-The package is ESM-only and published publicly on npmjs. It uses the default
-npm registry, so consumers need no scope-specific `.npmrc` and no package-read
-token.
+**3.0.0-rc.1 是预发布候选，发布通道为 next；稳定 latest 保持 2.14.0。** 是否已发布成功以 npm 标签和发布回执为准，不以 main 的版本号为准。现有产品继续锁定精确版本；主动升级先读[迁移表](docs/reference/migration-3.0.md)，本仓库不自动升级任何产品。
 
-Import the stylesheet once in the app shell:
+## 安装与最小使用
 
-```ts
-import '@pieai/swimmer-ui-kit/styles.css';
+React / React DOM 需要 19 或以上。候选评审时安装交付回执里的本地 tarball，先核对 SHA-256；发布后再改用 Owner 批准的精确 npm 版本。不要把相邻仓库源码当生产依赖。
+
+```sh
+# 发布回执成功后，显式选择候选版本；不要用 latest 自动升级
+pnpm add --save-exact @pieai/swimmer-ui-kit@3.0.0-rc.1
+# 发布前或离线验收，安装回执中经过 SHA-256 核对的同版本 tarball
+pnpm add --save-exact /path/to/swimmer-ui-kit-3.0.0-rc.1.tgz
 ```
 
-**Optional** — only if the host app uses Tailwind v4 and wants Tailwind
-theme names (`bg-primary`, `text-foreground`, `rounded-md`…) to resolve to
-kit tokens, additionally import the bridge (requires the host's Tailwind
-build; never import it without Tailwind):
+```tsx
+import { GameButton } from '@pieai/swimmer-ui-kit';
+import '@pieai/swimmer-ui-kit/styles.css';
 
-```ts
-import '@pieai/swimmer-ui-kit/tailwind.css';
+export function Actions() {
+  return (
+    <section data-game-ui-theme="light" data-game-ui-style="pastel">
+      <GameButton>看看详情</GameButton>
+      <GameButton variant="primary">继续下一步</GameButton>
+    </section>
+  );
+}
 ```
 
-## What's inside
-
-- **Account primitives (2.13.0 local candidate, not published)**:
-  opt-in copper `surface="plaque"`, `GameOtpInput`, vertical `GameTabs`,
-  and `GameListRow` with independent actions. See the
-  [account-controls contract](docs/reference/design-system-guide.md#账号界面原件)
-  and Storybook `Clay / Account / AccountControls`. Account requests and
-  business state stay in the host.
-
-- **Ready-to-use components** across: core controls (`GameButton`,
-  `LiquidMetalButton`, `GameTabs`,
-  `GameSlider`, `GameToggle`, `GameForms` inputs…), panels and windows
-  (`GamePanel`, `GameCollapsiblePanel`, `GameWindowPanel`, `GameModal` on
-  native `<dialog>`), HUD/shell surfaces (`GameShell`, `GameHud`,
-  `GameSceneHudLayout`, `GameMovementPad`…), the OwnMySpace surface pack,
-  terrain/build tooling (`GameTerrainBuildToolbox`…), and the AI
-  contractor queue (`GameContractorPanel`…). `src/index.ts` is the
-  authoritative export list; Storybook is the visual catalog.
-- **Design tokens** as CSS variables (`--game-ui-*`) with TypeScript
-  mirrors (`CLAY_*_TOKENS`, `GAME_UI_TOKENS`). The CSS variables are the
-  cross-stack contract and work outside React:
-
-  ```css
-  .my-game-panel {
-    background: var(--game-ui-panel);
-    color: var(--game-ui-text);
-    border-radius: var(--game-ui-radius-panel);
-  }
-  ```
-
-  Product-owned overflow containers can opt into the kit's cross-browser clay
-  scrollbar treatment with `class="game-ui-scroll-surface"`; tune its size,
-  track, thumb, and hover colors through the `--game-ui-scrollbar-*` tokens.
-
-- **Type**: a HUD scale (`--game-ui-font-xs` … `-xxl`) plus the three things a
-  HUD scale does not cover — `--game-ui-font-mono` for code, and
-  `--game-ui-font-reading` / `--game-ui-line-reading` /
-  `--game-ui-measure-reading` for a screen someone reads for minutes rather
-  than glances at. Reach for the reading trio whenever the text is prose, not
-  a label.
-- **Official themes**: light (default) and `night`
-  (`<html data-game-ui-theme="night">`). Downstream theming = overriding
-  semantic tokens; see the design system guide.
-- **`swimmer-ui-check`**: lints your CSS for raw colour literals in component
-  rules *and* for token pairs that cannot be read. Two tokens are not
-  automatically safe together — `--game-ui-accent-ink` is accent-COLOURED ink
-  for a surface, `--game-ui-accent-contrast` is the ink meant to sit **on**
-  `--game-ui-accent`. Pairing the first with the accent measures 1.48:1.
-
-  ```bash
-  npx swimmer-ui-check src
-  ```
-
-- **Clay assets**: two lines of setup, and **skipping them is not a no-op**.
-  Out of the box the kit draws *placeholders* — one rounded square per icon
-  with a letter in it — not the icon set. They exist so a fresh install
-  renders something instead of a broken image, and they are not shippable.
-  The real sculpted PNGs travel inside the package and need serving:
-
-  ```bash
-  npx swimmer-ui-assets public      # copies dist/assets into your static root
-  ```
-  ```ts
-  import { setClayAssetMode } from '@pieai/swimmer-ui-kit';
-  setClayAssetMode('source');       // once, at your entry
-  ```
-
-  Serving them somewhere else — a CDN, a sub-path deploy — is
-  `setClayAssetBasePath('/my/path')`, and `swimmer-ui-assets public --base=/my/path`
-  mirrors the layout to match. If you *want* placeholders, say so with
-  `acknowledgeClayPlaceholders()` and the console notice goes quiet.
-
-  Note on sizing: the sculpted family is 96px art. Below roughly 24px it turns
-  to mud, and being PNG it cannot take a `currentColor` tint, so it is the
-  wrong family for a dense navigation rail or toolbar. Use the `line` style
-  there, or your own glyphs.
-- **Audio helper**: `playGameInteractionSound` (SSR-safe, opt-in via the
-  `sound` prop on `GameButton`).
-
-## Wrapped-app (Capacitor/Tauri) readiness
-
-The kit treats WebView shells as first-class: interactive controls ship
-`touch-action: manipulation` and transparent tap highlights, hover-only
-affordances sit behind `@media (hover: hover)`, and every safe-area read
-flows through the `--game-ui-safe-*` tokens so hosts (e.g. Capacitor
-Android edge-to-edge, where raw `env(safe-area-inset-*)` can read 0) can
-override the source values in one place.
-
-## Compatibility contract (1.0)
-
-- Exported components and props, `.game-ui-*` class names, and
-  `--game-ui-*` token names are public API: additive-only within a major.
-- `dist/styles.css` stays 100% standard CSS (guard-tested; the CSS build
-  fails on any lightningcss warning).
-- Packaging is machine-checked: `publint` and `arethetypeswrong` run clean
-  (ESM-only by design — CJS consumers on Node ≥22 can `require(esm)` or
-  dynamic-import).
-
-See `CHANGELOG.md` for release history and migration notes.
-
-## Development
-
-```bash
-pnpm install
-pnpm dev              # preview page (token ledger + all surfaces)
-pnpm storybook        # component catalog
-pnpm verify && pnpm docs:check
-pnpm api:inventory    # regenerate the public API index after a reviewed API change
+一屏最多一个 primary。危险操作用 danger：红字、普通底色；不会变成另一个液体 CTA。安装包是 ESM-only；主样式是标准 CSS，不要求 Tailwind 或产品的 CSS 预处理器。
+
+图标直接用 `<GameIcon icon="check" />`，没有图片请求或初始化；尺寸为16 / 20 / 24px。默认英文与中文字体声明已随 styles.css 加载；中文按字符块请求，fonts.css 也可单独使用。
+
+App Router 可以从 Server Component 直接挂载 UIKit 组件；事件、ref 与受控状态放在宿主 Client Component，CSS 在 layout 导入。组件入口和 React 共享分块已有 client boundary，不需要产品重复包装导出；纯图标数据从 icon-paths 子入口读取。具体边界见[主题与液体](docs/reference/theme-and-liquid.md)。
+
+## 去哪里看
+
+| 需要 | 入口 |
+| --- | --- |
+| 选组件、正确使用 | [组件选择指南](docs/reference/component-selection-guide.md) |
+| 主题、液体、可选特效 | [主题与液体](docs/reference/theme-and-liquid.md) |
+| 改配色、字体和样式 | [设计 token](docs/reference/design-tokens.md) |
+| 全部公开名字 | [生成的 API 清单](docs/reference/public-api-inventory.md) |
+| 迁移与候选验收 | [3.0 迁移表](docs/reference/migration-3.0.md) |
+| 工作状态与证据 | [当前工作](docs/reference/execution/current-work.md) |
+
+本机 `pnpm dev` 打开组件目录，`pnpm storybook` 打开故事；端口被占就换空闲端口，别停止其他项目的服务。已部署网站不是本机 3.0 候选的证明。
+
+## 开发与交付
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+pnpm docs:check
+pnpm build-storybook
 ```
 
-Releases use GitHub Actions Trusted Publishing: bump `package.json`, commit and
-push `main`, then run `gh workflow run npm-publish.yml --ref main`. The manual
-workflow is the release safety switch; it publishes to npmjs with short-lived
-OIDC credentials and provenance, without a local login or stored npm token.
+公共 API 变更后运行 pnpm api:inventory。提交/推送只保存代码，不发 npm，也不部署网站。发布需完整本机门禁和明确授权；S14 已获 Owner 的单次工作流授权，预发布只更新 next，失败停止、不重试。包级门禁与下游产品真实接入验收分别记录。
+
+维护者检查真实包体使用 `pnpm check:packed .scratch/<candidate>.tgz`：五个 JS 入口（含独立图标路径）、React 共享分块边界、严格类型消费、资源原字节和迁移检查器都从 tarball 验证。该命令只创建仓库内隔离夹具，不安装到产品、不发布。 另用 `pnpm check:next-consumer .scratch/<candidate>.tgz` 安装真实候选到临时 Next 项目，检查构建、启动、水合、链接、液体交互与窄屏；发布工作流也执行此门禁。
 
-The former `doc/` tutorials and one-off root reports are catalogued in the
-[documentation and evidence relocation record](docs/archive/relocations-2.5.0.json). Historical
-material is retained, but installation and component selection follow the guides above.
+源码公开可读，使用受 [PieAI Limited Use License](LICENSE) 约束，并非开源许可。字体和图标路径遵循各自第三方许可证；来源看 [NOTICE](NOTICE) 与 [donor 索引](donors-individual.md)。

package/bin/lib/retired-theme.d.mts

@@ -0,0 +1,2 @@
+export function stripSourceComments(text: string): string;
+export function findRetiredThemeValues(text: string): Array<{ line: number; message: string }>;

package/bin/lib/retired-theme.mjs

@@ -0,0 +1,58 @@
+/** Migration diagnostic only. This module never applies a theme or supplies a fallback. */
+export function stripSourceComments(text) {
+  let result = '',
+    quote = '',
+    mode = '';
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i],
+      next = text[i + 1];
+    if (mode === 'line') {
+      result += ch === '\n' ? '\n' : ' ';
+      if (ch === '\n') mode = '';
+    } else if (mode === 'block') {
+      if (ch === '*' && next === '/') {
+        result += '  ';
+        i++;
+        mode = '';
+      } else result += ch === '\n' ? '\n' : ' ';
+    } else if (quote) {
+      result += ch;
+      if (ch === '\\' && next !== undefined) {
+        result += next;
+        i++;
+      } else if (ch === quote) quote = '';
+    } else if (ch === '"' || ch === "'" || ch === '`') {
+      quote = ch;
+      result += ch;
+    } else if (ch === '/' && (next === '/' || next === '*')) {
+      mode = next === '/' ? 'line' : 'block';
+      result += '  ';
+      i++;
+    } else result += ch;
+  }
+  return result;
+}
+
+export function findRetiredThemeValues(text) {
+  // Preserve character offsets while making quoted CSS selectors inside JS
+  // strings readable. Quotes need not share a delimiter with their JS host.
+  const code = stripSourceComments(text).replace(/\\(?=['"`])/g, ' ');
+  const patterns = [
+    /data-game-ui-theme\s*=\s*['"`]?\s*night\s*['"`]?/g,
+    /data-game-ui-theme\s*=\s*\{[^}]*?['"`]night['"`][^}]*\}/g,
+    /['"`]data-game-ui-theme['"`]\s*:\s*['"`]night['"`]/g,
+    /\bsetAttribute\s*\(\s*['"`]data-game-ui-theme['"`]\s*,\s*['"`]night['"`]/g,
+    /\b(?:dataset\s*\.\s*gameUiTheme|dataset\s*\[\s*['"`]gameUiTheme['"`]\s*\])\s*=\s*['"`]night['"`]/g,
+    /\bgameUiTheme\s*:\s*['"`]night['"`]/g,
+  ];
+  const matches = new Map();
+  for (const pattern of patterns)
+    for (const match of code.matchAll(pattern)) {
+      const line = code.slice(0, match.index).split('\n').length;
+      matches.set(line, {
+        line,
+        message: 'data-game-ui-theme="night" 已在 3.0 删除；请改成 data-game-ui-theme="dark"。',
+      });
+    }
+  return [...matches.values()].sort((a, b) => a.line - b.line);
+}