VOZEB-UI-FOUNDATION-01 — Foundation v1 候选收口证据

这是一份候选交接记录，不是 Gate 1 批准、正式 Design Freeze 或发布说明。

1. 结论与边界

项目	当前值
Task ID	`VOZEB-UI-FOUNDATION-01`
当前状态	`DESIGN_CANDIDATE / REVIEW_REQUIRED / NOT_FROZEN`
视觉候选仓库	`/Users/wangzihao/Projects/oceanway-vozeb`
Retail 主线	未集成；本次收口没有修改 `/Users/wangzihao/Projects/retail-platform`
Gate 1	未通过，等待用户对视觉方向、组件 API 和性能边界作出确认
下一任务	用户确认后另建 `VOZEB-UI-MIGRATION-02`，不自动开始全项目迁移

Foundation v1 的交付物是可审查的 OceanWay 视觉候选：Ocean Air/Abyss token、左侧 workspace shell、单一页面背景 renderer、Agent Composer、Liquid Glass surface、基础状态/数据/overlay kit、React Bits/Ocean 动效适配器和 /components 实验室。业务页面的数据、身份、模型、计费、权限、持久化和路由事实仍由 VOZEB/平台 adapter 负责；候选 kit 不读取 store、不请求 API、不创建 Operation/Billing Entry，也不持久化业务状态。

2. Source / tree provenance

2.1 Git 锚点

候选包从下列固定基线拆分，并由包含本文件的 Git commit承载。提交 SHA 不在提交内容中自引用；交接时以 git rev-parse HEAD 和 git show --format=%T --no-patch HEAD 解析该候选包的 commit/tree：

git rev-parse HEAD
git show --format=%T --no-patch HEAD
git diff --name-only d0037e99bbbec29f59e320d5ee6ba3fc8daeb6fe..HEAD
git status --short

证据	值
分支	`codex/oceanway-bootstrap`
Foundation 包基线	`d0037e99bbbec29f59e320d5ee6ba3fc8daeb6fe`
Foundation 基线树	`0bed27ce6481777206d1f538a5e31f0f1f0a281c`
候选 commit / tree	本文件所在 commit；交接报告记录最终 SHA/tree
上游远端	`https://github.com/csyqlz/VOZEB-PRO.git`
VOZEB 原始基线	`4de8360f46b3b8e9a76649ec68b6ae3d028345ac`（`v0.0.6` / `upstream/main`）
工作树边界	仅白名单 Foundation 文件进入候选 commit；其余并行 dirty 文件保持未提交

该仓库工作树由多个并行任务共享；本候选通过显式 pathspec 从 dirty tree 拆出一个独立 commit，不使用 git add .、reset、clean 或全仓格式化。web/test-results/、Retail adapter、后台/商业路由和 Create/Spaces 业务候选都不属于本提交。候选 commit 只提高可复现性，不提升设计状态，也不授权 Gate 1 或项目级迁移。

2.2 候选变更清单（Foundation Owner 范围）

以下是本 Foundation 候选的最终路径边界。目录内的 .tsx、.ts、.css、测试和 README 均属于同一 kit，后续迁移应通过 web/src/components/ocean/index.ts 的窄 API 接入。

A. Shell、主题与材质基础

web/src/components/layout/app-workspace-shell.tsx
web/src/components/layout/app-workspace-shell.module.css
web/src/components/layout/app-workspace-shell.test.ts
web/src/components/layout/app-sidebar.tsx
web/src/components/layout/app-sidebar.module.css
web/src/components/layout/mobile-nav-drawer.tsx
web/src/components/layout/user-status-actions.tsx
web/src/components/layout/ocean-particle-background.tsx       # 旧名兼容导出
web/src/components/layout/ocean-liquid-glass-material.ts
web/src/components/layout/ocean-liquid-glass-material.test.ts
web/src/app/styles/global-foundation.css
web/src/app/styles/global-liquid-glass.css
web/src/app/styles/global-ocean-air-theme.css
web/src/lib/app-theme.ts
web/src/lib/app-theme.test.ts
web/src/lib/ocean-air-theme.ts
web/src/lib/ocean-air-theme.test.ts
web/src/lib/ocean-theme-mode.test.ts
web/src/lib/canvas-theme.test.ts

职责：保留左侧菜单和移动 Drawer；提供 Ocean Air（浅色）/Abyss（深色）语义变量、连续圆角、单条 hairline、焦点和 reduced-motion/transparency/forced-colors 回退。页面级 OceanAmbientBackground 是唯一背景 renderer；旧 OceanParticleBackground 仅保留兼容入口，不再拥有第二套粒子实现。

B. 首页与 Agent 焦点表面

web/src/app/home/home-workspace.tsx
web/src/app/home/home-workspace.module.css
web/src/app/home/home-workspace.test.ts
web/src/app/home/liquid-glass-lens.tsx       # 兼容别名，委托 OceanGlassSurface

职责：首页欢迎区、宽度受控的 Agent 指令台、最近画布/辅助区域和现有 VOZEB 数据回调。不改变提交、登录门禁、模型选择、计费或 Canvas 持久化语义。页面 CSS 中仍有少量候选专用 rgba/white 阴影与媒体遮罩，列为冻结前 token-cleanup gap，不在本次收口自动改写。

C. Ocean 可复用 kit（唯一共享视觉入口）

web/src/components/ocean/**

包括：

layout/：OceanWorkspaceShell、OceanSidebar、OceanMobileDrawer；
surfaces/：OceanGlassSurface、OceanGlassCard；
composer/：OceanAgentComposer；
backgrounds/：OceanAmbientBackground、组件实验室专用 MoltenMetal；
foundation/：OceanUtilityControl、OceanContentCard、OceanContextRail、 OceanStatusCluster、OceanLoadingShell、OceanCanvasStage；
data/ 与 overlays/：Filter、DataTable、Dialog、Drawer、Popover；
motion/：Spotlight、Tilt、Magnetic、Reveal、ShinyText、BlurText、ClickSpark、 GlareHover、AnimatedList、CountUp、GradientText、GradualBlur、LogoLoop、PixelSwap、 RotatingText、ScrollExpand；
patterns/：Foundation lab、Asset/Prompt/Work、Admin、Canvas、Drama、Auth、Install 等 view-model-only 组合 kit；
README.md、组件测试和 index.ts：复用边界、性能契约和窄导出入口。

D. UI 原子层与来源清单

web/src/components/ui/avatar.tsx
web/src/components/ui/badge.tsx
web/src/components/ui/button.tsx
web/src/components/ui/component-foundation.test.tsx
web/src/components/ui/component-manifest.ts
web/src/components/ui/component-manifest.test.ts
web/src/components/ui/empty-state.tsx
web/src/components/ui/field.tsx
web/src/components/ui/icon-button.tsx
web/src/components/ui/index.ts
web/src/components/ui/input.tsx
web/src/components/ui/loading-state.tsx
web/src/components/ui/media-frame.tsx
web/src/components/ui/progress.tsx
web/src/components/ui/react-bits-glass-surface.module.css
web/src/components/ui/react-bits-glass-surface.tsx
web/src/components/ui/section.tsx
web/src/components/ui/skeleton.tsx
web/src/components/ui/status.tsx
web/src/components/ui/surface.tsx
web/src/components/ui/tabs.tsx
web/src/components/ui/textarea.tsx
web/src/components/ui/dia-text-reveal.tsx

DiaTextReveal 是 VOZEB 原始基线已有的 Motion 原子（在 4de8360 可追溯），本轮只做 Ocean token 默认色、SSR/reduced-motion 和实验室重播适配；它不计入 React Bits 第三方源码清单。ReactBitsGlassSurface 是固定快照的应用内副本，外层 OceanGlassSurface 负责材质参数、单边界和浏览器回退。

E. Canvas loading 过渡（仅视觉候选）

web/src/app/(user)/canvas/[id]/canvas-client-page.tsx
web/src/app/(user)/canvas/[id]/canvas-page-elements.tsx
web/src/app/(user)/canvas/[id]/canvas-loading-shell.module.css
web/src/app/(user)/canvas/[id]/canvas-page-elements.test.tsx

职责：水合/加载时直接使用最终几何的 OceanLoadingShell，避免旧三块填充闪现；不改变 Canvas 节点、连线、保存、权限或任务事实。Canvas 列表、Create、Spaces 和完整业务页迁移不属于 Foundation v1。

F. 组件实验室与候选证据

web/src/app/components/page.tsx
web/src/app/components/component-showcase.tsx
web/src/app/components/component-showcase.module.css
web/src/app/components/component-showcase.test.ts
web/src/app/components/component-catalog.tsx
web/src/app/components/component-catalog.module.css
web/e2e/foundation-v1.spec.ts
web/e2e/home.spec.ts
web/playwright.config.ts

/components 是本阶段唯一的视觉候选审查入口。清单当前登记 231 项：built 85、 candidate 41、domain 94、controller 9、legacy 2、planned 0；React Bits 登记 27 项（extract 15、reference 12、direct 0）。清单中的 domain/controller/legacy 条目展示的是契约骨架或来源记录，不等于业务组件已迁移。

G. 文档与第三方来源

docs/oceanway/VOZEB-UI-FOUNDATION-01.md
docs/oceanway/VOZEB-UI-FOUNDATION-01-CLOSEOUT.md
docs/oceanway/VOZEB-UI-FOUNDATION-01.tokens.json
docs/oceanway/VOZEB-COMPONENT-INVENTORY-01.md
web/src/components/ocean/README.md
web/THIRD_PARTY_NOTICES.md
web/package.json
web/pnpm-lock.yaml

DESIGN.md、CHANGELOG.md 当前工作树也含有 Foundation 条目，但同时包含其他并行任务内容，不能作为本候选的独立提交边界，本次明确排除。依赖清单只记录引入 ogl@1.0.11 并移除先前的 simple-liquid-glass 运行时；React Bits 固定源码快照与许可正文记录在 web/THIRD_PARTY_NOTICES.md。根目录 THIRD_PARTY_LICENSES.md 含本机/Docs 依赖漂移，不进入本候选。

2.3 明确排除的共享 dirty 路径

以下路径在快照中可能 dirty，但不是本 Foundation closeout 的交付物；本次没有修改或整合它们：

web/src/integrations/retail/**
web/src/lib/server/retail-*.ts
web/src/app/admin/catalog/**
web/src/app/admin/operations/**
web/src/app/admin/orders/**
web/src/app/admin/settings/**
web/src/app/admin/users/**
web/src/app/(user)/create/**
web/src/app/(user)/spaces/**
web/e2e/all-pages.spec.ts
web/e2e/core.spec.ts
web/src/app/(user)/legacy-workbench-routes.test.ts
web/src/components/admin/admin-panel.tsx
web/src/components/compact-empty-state.tsx
web/next-env.d.ts
CHANGELOG.md
DESIGN.md
THIRD_PARTY_LICENSES.md
docs/content/docs/progress/pending-test.mdx
docs/oceanway/VOZEB-RETAIL-*.md
docs/oceanway/VOZEB-ADMIN-*.md
web/test-results/**

这些路径的领域契约、适配器、后台路由和测试由平台主线 Owner 管理；不得因为本候选的组件清单而将其视为已完成的 Retail 集成。

3. License / attribution ledger

来源	固定版本/文件	条款与交付边界
VOZEB-PRO 应用	根目录 `LICENSE`；基线 `4de8360`	文件文本为 GNU Affero General Public License v3（AGPL v3）；应用源码继续随原项目许可证交付。
React Bits	commit `1ba7ecd4e570d20392fb62c923efb00f5b440642`	MIT + Commons Clause License Condition v1.0；Copyright © 2026 David Haz；完整记录和许可证文本见 `web/THIRD_PARTY_NOTICES.md`。
React Bits 来源	GlassSurface、SoftAurora、MoltenMetal、Spotlight、Tilt、Magnetic、Reveal/AnimatedContent、ShinyText、BlurText、ClickSpark、GlareHover、AnimatedList、GradualBlur、PixelSwap、LogoLoop、ScrollExpand、CountUp、RotatingText、GradientText	以源码快照为参考/应用内适配；OceanWay 适配器增加生命周期、可见性、偏好降级、边界和可访问性，不作为独立 React Bits 组件包再分发。
OGL runtime	`ogl@1.0.11`	Unlicense；用于页面背景和组件实验室的 OGL 适配，版本与来源记录在第三方 notice。
VOZEB `DiaTextReveal`	原始基线 `4de8360` 的 `web/src/components/ui/dia-text-reveal.tsx`	VOZEB 原有组件，本轮为 Ocean token/SSR 偏好适配；不冒充 React Bits 来源。

本项目没有引入 liquid-glass-react 作为运行时依赖；Blur Amount、Saturation、 Chromatic Aberration、Elasticity 的参数语义由 Ocean 适配层收敛到固定 React Bits GlassSurface API 和 CSS fallback。第三方条款与根目录 AGPL 是分开的；本记录不对许可证作额外法律解释，也不把上游组件重新许可为独立组件库。

4. Objective evidence

以下证据来自候选工作树，不能替代用户视觉验收、独立 Testing 或 Gate 1 批准：

检查	结果
Vitest 全量	`513 files passed / 4 skipped`；`2324 tests passed / 9 skipped`（共 2333；干净候选 commit）
TypeScript	`tsc --noEmit --pretty false` 通过（干净候选 commit）
ESLint	`eslint . --quiet` 通过（干净候选 commit）
Prettier	`prettier --check .` 通过（干净候选 commit）
生产构建	`node scripts/production-build.mjs` 通过；Next 静态页面 `63/63`（干净候选 commit）
发布门禁	`node scripts/release-check.mjs` 通过；依赖审计无已知漏洞，Compose/Render/Standalone 检查通过
Foundation 定向 Vitest	15 个 Foundation/UI/Home/Canvas 测试文件、55 项通过
Foundation smoke E2E	未执行：本机缺少 Playwright bundled Chromium，setup 在启动浏览器前失败；未将 dirty worktree 的系统浏览器结果计入本提交证据
Home E2E	未执行，原因同上；需安装 CI/browser bundle 后复跑
Signed-out route subset	未执行，原因同上；`all-pages.spec.ts` 本身属于排除的跨页面 dirty 测试，不在候选 commit
`/components` motion	候选实现登记并挂载 17 个非静态 motion marker；DiaTextReveal 重播会 remount；另有 231 个静态 catalog preview（需浏览器复核）
偏好降级	单元契约覆盖 Reduced Motion / Reduced Transparency、WebGL fallback 与 context-loss 单 renderer 约束；浏览器几何需补做 bundled-browser 验收

测试环境限制和未通过项：

当前机器没有 Playwright bundled Chromium；foundation-v1.spec.ts/home.spec.ts 在 setup 启动阶段被浏览器缺失阻断。安装固定 browser bundle 后，必须在桌面和 390/430 视口复跑；本次没有把临时系统 Chrome 或其他 dirty worktree 的结果冒充候选 commit 证据。
完整 authenticated all-pages 属跨页面历史测试，且当前工作树版本仍可能在旧 Canvas loading-shell 断言处失败；它不在候选 commit，不能被表述为 Foundation 全量 E2E 绿灯。
开发服务器曾有既有 maintenance heartbeat 的 Manifest file is empty/notifications 409 日志噪声；/ 与 /components 返回 200，浏览器没有组件运行时错误。

5. 已知 Gap（不在本次自动补齐）

web/src/app/home/home-workspace.module.css 的候选局部 raw rgba/white 阴影、遮罩和透明度尚未统一到 semantic token；需要用户确认后做独立 token-cleanup。
SlicedWaves 只有实验室 candidate metadata，没有真实业务挂载；不得与首页 OceanAmbientBackground 叠加第二个 WebGL renderer。
OceanAmbientBackground 是页面级背景，不在 /components 再复制挂载；若要单独展示，需要互斥背景切换和新的性能证据。
CatalogEntry 的 231 个 inventory preview 是静态契约骨架，不是 231 个真实业务组件。
完整页面迁移、Admin route 视觉接入、Canvas/Drama/Assets 的真实 adapter 接线尚未完成。
尚无独立 Testing/Operations 对 Foundation 做正式 VERIFIED / OPERATIONALIZED 结论。
本文件所在 commit 是可复现的视觉候选包；它仍需用户评审，不能因提交存在而提升为 FROZEN、Gate 1 通过或正式页面迁移。

6. Gate 1 尚缺的用户确认项

Gate 1 只在以下事项由用户确认后才能建立后继任务；本记录不代替确认：

视觉方向：Ocean Air/Abyss 的背景明度、字体/字重、圆角层级、hairline、阴影和 “无多边框、无固定左上高光、正文不用蓝色”是否作为 Foundation v1 基准。
Liquid Glass 强度：Agent 与少量焦点表面的透明度、blur/saturation、是否开启 SVG channel split，以及边框/阴影在不同显示器上的可接受范围。
信息架构：左侧菜单项、OceanWay Logo、移动 Drawer 行为和账户/健康状态位置是否固定；不恢复顶部产品导航。
Agent Composer：桌面宽度边界、辅助区域关系、四种模态、示例提示词、发送/附件交互和文案是否固定为可复用 API。
动效白名单：哪些 React Bits/Ocean motion 进入产品页，哪些保持 /components 实验室候选；尤其是 MoltenMetal/SlicedWaves 的互斥 WebGL 策略。
性能预算：页面背景 renderer 数量、帧率/像素密度上限、移动端降级、隐藏标签页暂停、 reduced-motion/transparency、WebGL 不可用 fallback 是否达到预期。
组件版本与授权：确认当前组件 API/Token v0.2 可以作为 Foundation v1 候选版本，并明确授权另建 VOZEB-UI-MIGRATION-02；在此之前保持 REVIEW_REQUIRED / NOT_FROZEN。

7. 停点

Foundation v1 现在停在候选评审点。平台主线可以继续自己的领域契约、适配器和测试，但不得覆盖本候选的共享视觉文件；视觉线程也不得自行把平台 dirty 文件整合进来。收到用户明确确认后，再按独立 Task Packet 建立 Gate 1 集成切片；在此之前不宣称 Gate 1 通过、不宣称全项目 UI 已改造，也不执行部署、发布或生产写入。

VOZEB-UI-FOUNDATION-01 — Foundation v1 候选收口证据

On this page