diff --git a/.github/actions/setup-workspace/action.yml b/.github/actions/setup-workspace/action.yml
index 3f56e2765..8cca687c6 100644
--- a/.github/actions/setup-workspace/action.yml
+++ b/.github/actions/setup-workspace/action.yml
@@ -4,6 +4,10 @@ description: Setup Node.js and pnpm, restoring an exact platform-specific worksp
 runs:
   using: composite
   steps:
+    - name: Checkout Avatar SDK submodule
+      shell: bash
+      run: git submodule update --init --depth 1 -- assets/avatar
+
     - name: Restore workspace dependencies
       id: workspace-cache
       uses: actions/cache@v4
@@ -11,6 +15,7 @@ runs:
         path: |
           node_modules
           assets/avatar/node_modules
+          assets/avatar/packages/*/node_modules
           apps/*/node_modules
           packages/*/node_modules
           packages/adapters/*/node_modules
@@ -20,7 +25,8 @@ runs:
           workspace-v1-pnpm-11.7.0-${{ runner.os }}-${{ runner.arch }}-${{
           hashFiles('.github/actions/setup-workspace/action.yml', '.node-version', '.npmrc',
           'package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml', 'patches/**/*.patch',
-          'assets/avatar/package.json', 'apps/*/package.json',
+          'assets/avatar/package.json', 'assets/avatar/packages/*/package.json',
+          'apps/*/package.json',
           'packages/*/package.json', 'packages/adapters/*/package.json',
           'packages/channels/*/package.json', 'packages/plugins/*/package.json') }}
 
diff --git a/.github/assets/avatar-3d-sdk-client-dark.jpg b/.github/assets/avatar-3d-sdk-client-dark.jpg
new file mode 100644
index 000000000..5b1c73cc1
Binary files /dev/null and b/.github/assets/avatar-3d-sdk-client-dark.jpg differ
diff --git a/.github/workflows/chrome-extension-ci.yml b/.github/workflows/chrome-extension-ci.yml
index 59fcdd838..d88cbd834 100644
--- a/.github/workflows/chrome-extension-ci.yml
+++ b/.github/workflows/chrome-extension-ci.yml
@@ -50,6 +50,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/chrome-extension-release.yml b/.github/workflows/chrome-extension-release.yml
index b28c822b6..8c6f1c701 100644
--- a/.github/workflows/chrome-extension-release.yml
+++ b/.github/workflows/chrome-extension-release.yml
@@ -40,6 +40,8 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -154,6 +156,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/deploy-avatar.yml b/.github/workflows/deploy-avatar.yml
index 169c20dd9..d27a108ea 100644
--- a/.github/workflows/deploy-avatar.yml
+++ b/.github/workflows/deploy-avatar.yml
@@ -7,7 +7,6 @@ on:
     paths:
       - assets/avatar
       - assets/avatar/**
-      - packages/avatar/**
       - .github/workflows/deploy-avatar.yml
   workflow_dispatch:
 
diff --git a/.github/workflows/deploy-pwa.yml b/.github/workflows/deploy-pwa.yml
index 662af3fa1..09f876959 100644
--- a/.github/workflows/deploy-pwa.yml
+++ b/.github/workflows/deploy-pwa.yml
@@ -5,9 +5,10 @@ on:
     branches:
       - main
     paths:
+      - assets/avatar
+      - assets/avatar/**
       - apps/client/**
       - packages/adapters/**
-      - packages/avatar/**
       - packages/channels/lark/**
       - packages/cli-helper/**
       - packages/components/**
diff --git a/.github/workflows/deploy-relay-admin.yml b/.github/workflows/deploy-relay-admin.yml
index f6cec5ca5..bd1c1c046 100644
--- a/.github/workflows/deploy-relay-admin.yml
+++ b/.github/workflows/deploy-relay-admin.yml
@@ -38,6 +38,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/deploy-relay-dev.yml b/.github/workflows/deploy-relay-dev.yml
index 251c3bc7d..1cdfbb685 100644
--- a/.github/workflows/deploy-relay-dev.yml
+++ b/.github/workflows/deploy-relay-dev.yml
@@ -70,6 +70,9 @@ jobs:
       - name: Checkout repository
         if: steps.credentials.outputs.available == 'true'
         uses: actions/checkout@v4
+      - name: Checkout Avatar SDK submodule
+        if: steps.credentials.outputs.available == 'true'
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         if: steps.credentials.outputs.available == 'true'
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/deploy-relay-server.yml b/.github/workflows/deploy-relay-server.yml
index 7c01edf4e..aa9ea47dc 100644
--- a/.github/workflows/deploy-relay-server.yml
+++ b/.github/workflows/deploy-relay-server.yml
@@ -76,6 +76,8 @@ jobs:
           fi
       - name: Checkout repository
         uses: actions/checkout@v4
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -143,6 +145,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/desktop-package.yml b/.github/workflows/desktop-package.yml
index 7bc740879..8a141b3ac 100644
--- a/.github/workflows/desktop-package.yml
+++ b/.github/workflows/desktop-package.yml
@@ -632,7 +632,9 @@ jobs:
 
       - name: Install dependencies
         working-directory: ${{ steps.desktop_workspace.outputs.workspace_dir }}
-        run: pnpm install --frozen-lockfile
+        run: |
+          git submodule update --init --depth 1 -- assets/avatar
+          pnpm install --frozen-lockfile
 
       - name: Run desktop package preflight
         working-directory: ${{ steps.desktop_workspace.outputs.workspace_dir }}
diff --git a/.github/workflows/npm-publish-alpha.yml b/.github/workflows/npm-publish-alpha.yml
index d7b4db719..58bf8ee08 100644
--- a/.github/workflows/npm-publish-alpha.yml
+++ b/.github/workflows/npm-publish-alpha.yml
@@ -49,8 +49,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Checkout demo video submodule
-        run: git submodule update --init --depth 1 -- assets/demo-video
+      - name: Checkout required workspace submodules
+        run: git submodule update --init --depth 1 -- assets/avatar assets/demo-video
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/relay-ci.yml b/.github/workflows/relay-ci.yml
index f459103db..da8827987 100644
--- a/.github/workflows/relay-ci.yml
+++ b/.github/workflows/relay-ci.yml
@@ -87,8 +87,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Checkout demo video submodule
-        run: git submodule update --init --depth 1 -- assets/demo-video
+      - name: Checkout required workspace submodules
+        run: git submodule update --init --depth 1 -- assets/avatar assets/demo-video
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/stable-windows-msi-release.yml b/.github/workflows/stable-windows-msi-release.yml
index d8bc31eca..019c25ac8 100644
--- a/.github/workflows/stable-windows-msi-release.yml
+++ b/.github/workflows/stable-windows-msi-release.yml
@@ -53,6 +53,8 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.sha }}
 
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
diff --git a/.github/workflows/vscode-extension-ci.yml b/.github/workflows/vscode-extension-ci.yml
index 4ad05e417..97878d45c 100644
--- a/.github/workflows/vscode-extension-ci.yml
+++ b/.github/workflows/vscode-extension-ci.yml
@@ -44,6 +44,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.github/workflows/vscode-extension-release.yml b/.github/workflows/vscode-extension-release.yml
index 5384e6a68..c28acc2e4 100644
--- a/.github/workflows/vscode-extension-release.yml
+++ b/.github/workflows/vscode-extension-release.yml
@@ -37,6 +37,8 @@ jobs:
         with:
           fetch-depth: 0
           ref: refs/tags/${{ inputs.release_tag }}
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -127,6 +129,9 @@ jobs:
           fetch-depth: 0
           ref: refs/tags/${{ needs.build.outputs.release_tag }}
 
+      - name: Checkout Avatar SDK submodule
+        run: git submodule update --init --depth 1 -- assets/avatar
+
       - name: Validate immutable release source
         env:
           EXPECTED_SOURCE_SHA: ${{ needs.build.outputs.source_sha }}
diff --git a/.github/workflows/workspace-cache-warm.yml b/.github/workflows/workspace-cache-warm.yml
index e7d2c14d0..b76188fec 100644
--- a/.github/workflows/workspace-cache-warm.yml
+++ b/.github/workflows/workspace-cache-warm.yml
@@ -14,6 +14,7 @@ on:
       - pnpm-workspace.yaml
       - patches/**/*.patch
       - assets/avatar/package.json
+      - assets/avatar/packages/*/package.json
       - apps/*/package.json
       - packages/*/package.json
       - packages/adapters/*/package.json
diff --git a/.oo/docs/en/usage/avatar-runtime.md b/.oo/docs/en/usage/avatar-runtime.md
index 4605d315b..d8e3d9360 100644
--- a/.oo/docs/en/usage/avatar-runtime.md
+++ b/.oo/docs/en/usage/avatar-runtime.md
@@ -11,17 +11,54 @@ import {
   createDefaultAvatarDefinition,
   parseAvatarDefinition,
   serializeAvatarDefinition
-} from '@oneworks/avatar-core'
+} from '@oneworks/avatar'
 
 const definition = createDefaultAvatarDefinition()
 const json = serializeAvatarDefinition(definition)
 const restored = parseAvatarDefinition(json)
 ```
 
+The face can enable a configurable highlight inside each eye. `scene.decals` adds vector color shapes that are projected onto a body or entity-part surface, so blush, mouth marks, badges, and similar details follow the same 3D pose and export path instead of becoming separate floating geometry.
+
+```ts
+const decorated = {
+  ...definition,
+  scene: {
+    ...definition.scene,
+    face: {
+      ...definition.scene.face,
+      eyeHighlight: {
+        color: '#ffffff',
+        enabled: true,
+        offsetX: -18,
+        offsetY: -20,
+        opacity: 96,
+        size: 30
+      }
+    },
+    decals: [
+      {
+        color: '#f29a93',
+        height: 18,
+        id: 'blush-left',
+        label: 'Left blush',
+        opacity: 88,
+        rotation: -6,
+        shape: 'ellipse',
+        targetPartId: null,
+        width: 30,
+        x: -50,
+        y: 31
+      }
+    ]
+  }
+}
+```
+
 Applications can supply multiple animation libraries. A library contains groups and clips, and a clip may also be passed directly to playback. A `relative` clip anchors each pose dimension at that dimension's first explicitly authored value; an `absolute` clip uses the recorded values directly.
 
 ```ts
-import type { AvatarAnimationLibrary } from '@oneworks/avatar-core'
+import type { AvatarAnimationLibrary } from '@oneworks/avatar'
 
 export const supportAnimations = {
   id: 'support',
@@ -62,7 +99,7 @@ Version 1 animation patches support `colorGrade`, `face`, and the `pitch`, `yaw`
 `Avatar` and `AvatarEditor` consume the same definition and animation libraries. The editor is the complete editor used by the hosted product, not a reduced settings form.
 
 ```tsx
-import { createDefaultAvatarDefinition } from '@oneworks/avatar-core'
+import { createDefaultAvatarDefinition } from '@oneworks/avatar'
 import { Avatar, AvatarEditor } from '@oneworks/avatar-react'
 import type { AvatarHandle } from '@oneworks/avatar-react'
 import { useRef, useState } from 'react'
@@ -110,7 +147,7 @@ The renderer ref provides `play`, `pause`, `resume`, `seek`, `stop`, `capture`,
 
 ```vue
 <script setup lang="ts">
-import { createDefaultAvatarDefinition } from '@oneworks/avatar-core'
+import { createDefaultAvatarDefinition } from '@oneworks/avatar'
 import { OneWorksAvatar, OneWorksAvatarEditor } from '@oneworks/avatar-vue'
 import { ref } from 'vue'
 import '@oneworks/avatar-vue/style.css'
diff --git a/.oo/docs/en/usage/avatar.md b/.oo/docs/en/usage/avatar.md
index 59057ec35..e3435a7d5 100644
--- a/.oo/docs/en/usage/avatar.md
+++ b/.oo/docs/en/usage/avatar.md
@@ -23,17 +23,21 @@ Export sizes are 128, 256, and 512 pixels. The camera background can be a color
 
 ## Developer integration
 
-The new 3D Runtime is currently versioned `0.1.0-alpha.0`. Its source and clean packed-consumer verification are public in [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar). The four new packages have not completed their first npm registry publication, so do not run same-name install commands yet. The imports below are implemented and verified public alpha contracts, not an unimplemented proposal.
+The 3D Runtime and framework adapters share version `1.0.0-rc.6`. `@oneworks/avatar` is now the framework-neutral 3D core package; the old 2D pixel renderer is no longer retained.
+
+```bash
+pnpm add @oneworks/avatar@rc
+# Add one or more adapters for your application.
+pnpm add @oneworks/avatar-react@rc @oneworks/avatar-vue@rc @oneworks/avatar-web@rc
+```
 
 | Package                  | Purpose                                                                  |
 | ------------------------ | ------------------------------------------------------------------------ |
-| `@oneworks/avatar-core`  | Versioned definitions, validation, serialization, and animation runtime. |
+| `@oneworks/avatar`       | Versioned definitions, validation, serialization, and animation runtime. |
 | `@oneworks/avatar-react` | React `Avatar` renderer and full `AvatarEditor`.                         |
 | `@oneworks/avatar-vue`   | Vue `OneWorksAvatar` and `OneWorksAvatarEditor`.                         |
 | `@oneworks/avatar-web`   | Vanilla JavaScript mounts and explicitly registered Web Components.      |
 
-The existing `@oneworks/avatar` package is intentionally separate: it remains the legacy 2D pixel-emoticon SVG renderer and does not consume 3D definitions.
-
 Continue with the guide for your integration target:
 
 - [Definitions, custom animations, React, and Vue](./avatar-runtime.md)
@@ -69,9 +73,9 @@ The Skill uses the real editor and its 3D scene model instead of redrawing resul
 
 ## Source, local development, and deployment
 
-The legacy pixel renderer lives in [`oneworks-ai/app`](https://github.com/oneworks-ai/app) under `packages/avatar`. The 3D editor, Runtime, framework adapters, and export pipeline live in [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar).
+The 3D editor, `@oneworks/avatar` Runtime, framework adapters, and export pipeline all live in [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar).
 
-The Avatar repository is mounted into the app repository as the `assets/avatar` submodule. It builds independently from the app root workspace while using an `app-source` checkout or symlink for shared package source.
+The Avatar repository is mounted into the app repository as the `assets/avatar` submodule, and its four public packages are also members of the app root workspace. The Avatar repository can still be checked out independently and use an `app-source` checkout or symlink for shared package source.
 
 ```bash
 pnpm install --no-frozen-lockfile
@@ -82,4 +86,4 @@ ONEWORKS_APP_SOURCE_DIR=app-source pnpm typecheck:sdk
 ONEWORKS_APP_SOURCE_DIR=app-source pnpm smoke:sdk
 ```
 
-The Avatar page is published by the Avatar repository's `deploy-avatar.yml` workflow. The app repository triggers it when `assets/avatar`, `assets/avatar/**`, `packages/avatar/**`, or `.github/workflows/deploy-avatar.yml` changes. The main docs workflow publishes this page from `.oo/docs`.
+The Avatar page is published by the Avatar repository's `deploy-avatar.yml` workflow. The app repository triggers it when `assets/avatar`, `assets/avatar/**`, or `.github/workflows/deploy-avatar.yml` changes. The main docs workflow publishes this page from `.oo/docs`.
diff --git a/.oo/docs/usage/avatar-runtime.md b/.oo/docs/usage/avatar-runtime.md
index f29594978..41b4e832a 100644
--- a/.oo/docs/usage/avatar-runtime.md
+++ b/.oo/docs/usage/avatar-runtime.md
@@ -11,17 +11,54 @@ import {
   createDefaultAvatarDefinition,
   parseAvatarDefinition,
   serializeAvatarDefinition
-} from '@oneworks/avatar-core'
+} from '@oneworks/avatar'
 
 const definition = createDefaultAvatarDefinition()
 const json = serializeAvatarDefinition(definition)
 const restored = parseAvatarDefinition(json)
 ```
 
+面部可以开启可配置的眼睛内高光。`scene.decals` 用于把矢量颜色形状投影到主体或指定实体部件表面；红晕、嘴部色块、徽标等细节会跟随同一套 3D 姿态与导出链路，而不是变成悬浮的独立几何体。
+
+```ts
+const decorated = {
+  ...definition,
+  scene: {
+    ...definition.scene,
+    face: {
+      ...definition.scene.face,
+      eyeHighlight: {
+        color: '#ffffff',
+        enabled: true,
+        offsetX: -18,
+        offsetY: -20,
+        opacity: 96,
+        size: 30
+      }
+    },
+    decals: [
+      {
+        color: '#f29a93',
+        height: 18,
+        id: 'blush-left',
+        label: '左侧红晕',
+        opacity: 88,
+        rotation: -6,
+        shape: 'ellipse',
+        targetPartId: null,
+        width: 30,
+        x: -50,
+        y: 31
+      }
+    ]
+  }
+}
+```
+
 应用可以传入多个动画库。库由 group 和 clip 组成，播放时也可以直接传 clip。`relative` 会把每个姿态维度各自第一次显式出现的值锚定到当前场景；`absolute` 使用动画中记录的绝对值。
 
 ```ts
-import type { AvatarAnimationLibrary } from '@oneworks/avatar-core'
+import type { AvatarAnimationLibrary } from '@oneworks/avatar'
 
 export const supportAnimations = {
   id: 'support',
@@ -62,7 +99,7 @@ v1 动画 patch 支持 `colorGrade`、`face`，以及 `view` 的 `pitch`、`yaw`
 `Avatar` 和 `AvatarEditor` 接收同一个 definition 和动画库。编辑器是在线产品使用的完整编辑器，不是简化表单。
 
 ```tsx
-import { createDefaultAvatarDefinition } from '@oneworks/avatar-core'
+import { createDefaultAvatarDefinition } from '@oneworks/avatar'
 import { Avatar, AvatarEditor } from '@oneworks/avatar-react'
 import type { AvatarHandle } from '@oneworks/avatar-react'
 import { useRef, useState } from 'react'
@@ -110,7 +147,7 @@ export function AvatarWorkspace() {
 
 ```vue
 <script setup lang="ts">
-import { createDefaultAvatarDefinition } from '@oneworks/avatar-core'
+import { createDefaultAvatarDefinition } from '@oneworks/avatar'
 import { OneWorksAvatar, OneWorksAvatarEditor } from '@oneworks/avatar-vue'
 import { ref } from 'vue'
 import '@oneworks/avatar-vue/style.css'
diff --git a/.oo/docs/usage/avatar.md b/.oo/docs/usage/avatar.md
index 738aee570..f2fbbe05a 100644
--- a/.oo/docs/usage/avatar.md
+++ b/.oo/docs/usage/avatar.md
@@ -23,17 +23,21 @@ OneWorks Avatar 是浏览器端 3D 几何头像编辑器，也提供与在线编
 
 ## 开发者接入
 
-新的 3D Runtime 当前版本为 `0.1.0-alpha.0`，源码与 pack 后的干净 consumer 验证已公开在 [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar)。四个新包尚未完成首次 npm registry 发布，因此现在不要执行同名包安装命令；以下 import 是已经实现并验证的公开 alpha 接口，而不是尚未落地的设计稿。
+3D Runtime 与框架适配器统一使用 `1.0.0-rc.6`。`@oneworks/avatar` 已直接升级为框架无关的 3D 核心包，旧的 2D 像素 renderer 不再保留。
+
+```bash
+pnpm add @oneworks/avatar@rc
+# 按项目选择一个或多个适配器
+pnpm add @oneworks/avatar-react@rc @oneworks/avatar-vue@rc @oneworks/avatar-web@rc
+```
 
 | 包                       | 用途                                                 |
 | ------------------------ | ---------------------------------------------------- |
-| `@oneworks/avatar-core`  | 版本化 definition、校验、序列化和动画运行时。        |
+| `@oneworks/avatar`       | 版本化 definition、校验、序列化和动画运行时。        |
 | `@oneworks/avatar-react` | React `Avatar` 渲染组件和完整 `AvatarEditor`。       |
 | `@oneworks/avatar-vue`   | Vue `OneWorksAvatar` 和 `OneWorksAvatarEditor`。     |
 | `@oneworks/avatar-web`   | 原生 JavaScript mount API 和显式注册 Web Component。 |
 
-现有的 `@oneworks/avatar` 不在这张表里：它仍是独立的 legacy 2D 像素表情 SVG renderer，不能读取 3D definition。
-
 按接入目标继续阅读：
 
 - [Definition、自定义动画、React 与 Vue](./avatar-runtime.md)
@@ -69,9 +73,9 @@ npx skills@latest add oneworks-ai/avatar
 
 ## 源码、本地开发与部署
 
-Legacy 像素 renderer 位于 [`oneworks-ai/app`](https://github.com/oneworks-ai/app) 的 `packages/avatar`。3D 编辑器、Runtime、框架适配器和导出链路位于 [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar)。
+3D 编辑器、`@oneworks/avatar` Runtime、框架适配器和导出链路统一位于 [`oneworks-ai/avatar`](https://github.com/oneworks-ai/avatar)。
 
-Avatar 仓库作为 `assets/avatar` submodule 挂载回 app 仓库。它独立于 app 根 workspace 构建，并通过 `app-source` checkout 或软链接使用共享包源码。
+Avatar 仓库作为 `assets/avatar` submodule 挂载回 app 仓库；四个公开包同时是 app 根 workspace 的成员。Avatar 仓库也可以单独检出，并通过 `app-source` checkout 或软链接使用共享包源码。
 
 ```bash
 pnpm install --no-frozen-lockfile
@@ -82,4 +86,4 @@ ONEWORKS_APP_SOURCE_DIR=app-source pnpm typecheck:sdk
 ONEWORKS_APP_SOURCE_DIR=app-source pnpm smoke:sdk
 ```
 
-Avatar 页面由 Avatar 仓库的 `deploy-avatar.yml` workflow 发布。app 仓库在 `assets/avatar`、`assets/avatar/**`、`packages/avatar/**` 或 `.github/workflows/deploy-avatar.yml` 变化时触发它。文档页由主站 docs workflow 从 `.oo/docs` 发布。
+Avatar 页面由 Avatar 仓库的 `deploy-avatar.yml` workflow 发布。app 仓库在 `assets/avatar`、`assets/avatar/**` 或 `.github/workflows/deploy-avatar.yml` 变化时触发它。文档页由主站 docs workflow 从 `.oo/docs` 发布。
diff --git a/.oo/rules/maintenance/README.md b/.oo/rules/maintenance/README.md
index e5b47f13a..b2274c5db 100644
--- a/.oo/rules/maintenance/README.md
+++ b/.oo/rules/maintenance/README.md
@@ -123,17 +123,17 @@ target、状态查询、操作租约和 handoff 见 [开发服务跨会话协作
 - PWA 静态站点由 `oneworks-ai/pwa` 仓库维护，发布分支是该仓库的 `gh-pages`。
 - 本仓库的 `.github/workflows/deploy-pwa.yml` 负责在 `main` 的 client 相关输入变化时触发 `oneworks-ai/pwa` 的 `deploy-pwa.yml` workflow，并等待下游 workflow 成功；不再直接写本仓库的 `gh-pages`。
 - 本仓库需要配置 Actions secret `PWA_DEPLOY_TOKEN`，用于跨仓库触发 `oneworks-ai/pwa` workflow。推荐使用只授予 `oneworks-ai/pwa` Actions 写权限的 fine-grained token。
-- PWA 仓库部署时会 checkout 本仓库 `main` 的指定 commit，使用 `__ONEWORKS_PROJECT_CLIENT_MODE__=standalone` 和 `__ONEWORKS_PROJECT_CLIENT_BASE__=/pwa/` 构建 `apps/client`，然后把 `apps/client/dist/` 发布到 `oneworks-ai/pwa` 的 `gh-pages`。
+- PWA 仓库部署时会 checkout 本仓库 `main` 的指定 commit，先初始化 client 必需的 `assets/avatar` SDK submodule，再使用 `__ONEWORKS_PROJECT_CLIENT_MODE__=standalone` 和 `__ONEWORKS_PROJECT_CLIENT_BASE__=/pwa/` 构建 `apps/client`，然后把 `apps/client/dist/` 发布到 `oneworks-ai/pwa` 的 `gh-pages`。合入前跨仓验证使用 exact `source_sha` 与 `dry_run=true`，只跑 checkout、submodule、install 和 production build，不更新 `gh-pages`。
 - `__ONEWORKS_PROJECT_CLIENT_BASE__=/pwa/` 的官方独立构建会在编译期启用官网首页预览运行时；普通独立部署默认不包含这部分模拟数据和 hook 代码。自定义构建可以用 `__ONEWORKS_PROJECT_CLIENT_HOMEPAGE_PREVIEW__=1` 强制启用，或用 `__ONEWORKS_PROJECT_CLIENT_HOMEPAGE_PREVIEW__=0` 强制关闭。
 - 本仓库自己的 `gh-pages` 不再承载 PWA，后续主要用于项目文档站；维护文档站构建或部署时，不要把 PWA 发布逻辑重新写回本仓库。
 
 ### 7. Avatar 独立部署维护
 
 - Avatar 预览站点由 `oneworks-ai/avatar` 仓库维护，并作为本仓库 `assets/avatar` submodule 挂载。
-- Avatar 的运行时来源是本仓库 `packages/avatar`，client 通过 `@oneworks/avatar` 使用同一套 SVG rect 渲染器。
-- 本仓库的 `.github/workflows/deploy-avatar.yml` 只在 `assets/avatar/**`、`packages/avatar/**` 或 workflow 自身变化时触发，避免其它 package / client 改动误触发 avatar Pages 更新。
+- Avatar 仓库拥有编辑器以及 `@oneworks/avatar`、React、Vue、Vanilla / Web Component 四个 public 3D runtime package；本仓通过 submodule workspace 消费同一份源码，不再维护独立的 legacy 2D renderer。
+- 本仓库的 `.github/workflows/deploy-avatar.yml` 只在 exact `assets/avatar` gitlink、`assets/avatar/**` 或 workflow 自身变化时触发，避免其它 package / client 改动误触发 Avatar Pages 更新。
 - 本仓库需要配置 Actions secret `AVATAR_DEPLOY_TOKEN`，用于跨仓库触发 `oneworks-ai/avatar` 的 `deploy-avatar.yml` workflow。推荐使用只授予 `oneworks-ai/avatar` Actions 写权限的 fine-grained token。
-- Avatar 仓库部署时会 checkout 本仓库 `main` 的指定 commit，并初始化 submodules；构建命令是 `ONEWORKS_AVATAR_BASE=/avatar/ pnpm -C assets/avatar build`，最终发布 `assets/avatar/dist/` 到 GitHub Pages。
+- Avatar 仓库部署时 checkout 自身源码构建编辑器，仅 checkout 本仓指定 commit 读取共享 Node / package metadata；Pages 产物由 Avatar 仓自己的 `pnpm build` 生成并发布。四个 public runtime package 的 npm version、tag、provenance 与 postflight 也由该独立仓库的受保护发布流程负责。
 
 ### 8. Homepage 文档站部署维护
 
diff --git a/.oo/rules/release/npm-trusted-publishing.md b/.oo/rules/release/npm-trusted-publishing.md
index 580ecc896..3870a2275 100644
--- a/.oo/rules/release/npm-trusted-publishing.md
+++ b/.oo/rules/release/npm-trusted-publishing.md
@@ -11,7 +11,7 @@
 
 ## npm 发布前：身份与登录态
 
-在 dispatch 前，先收敛本次的**完整 npm public identity set**：所有实际会发布的 public workspace package，以及 `apps/bootstrap/package.json` 的 `oneworks.publishAliases` 展开的 publish alias。不要只看 workspace 名称、也不要手工猜 alias；用发布计划和该 manifest 的当前值逐项列出。
+在 dispatch 前，先收敛本次的**完整 npm public identity set**：本仓发布计划中所有实际会发布的 public workspace package，以及 `apps/bootstrap/package.json` 的 `oneworks.publishAliases` 展开的 publish alias。`skippedIndependent` 中由获准独立仓库发布的包不属于本仓 identity set，必须由其源码仓库单独完成相同级别的 trust、provenance 与 postflight。不要只看 workspace 名称、也不要手工猜 alias；用发布计划和该 manifest 的当前值逐项列出。
 
 对每一个 identity 都审计其 Trusted Publisher 配置。浏览器已登录 npm 不表示 CLI 已认证；用 `npm whoami`（必要时完成 CLI login）确认操作者 CLI 身份。它只说明本地 CLI 登录态，**不**说明 GitHub OIDC 是否能发布，也不应被用作 OIDC 状态证明。
 
diff --git a/.oo/rules/release/process.md b/.oo/rules/release/process.md
index 5806e2dc6..7d877621e 100644
--- a/.oo/rules/release/process.md
+++ b/.oo/rules/release/process.md
@@ -60,7 +60,7 @@ Relay device transport contract is runtime code shared by `@oneworks/types`, `@o
 - `packages` 不能为空，除非明确勾选 `publish_all=true`。发布整组 public workspace 包时必须显式打开 `publish_all`，避免误触发把所有 public 包发布到 npm。
 - `publish_tag=latest` 的首次 stable 发布会强制 `publish_all=true`、`packages` 为空，并且 workflow 必须从精确的 `pkg/oneworks/v<version>` tag 运行。发生 mixed-result 后，先由 postflight 完整列出缺失 identity；目标版本要求 provenance 时必须修复 trust 并用 `auth_mode=oidc` 定向恢复，不能以 token mode 绕过 provenance。
 - workflow 先用 publish-plan 生成 alias-closed order，再由 npm publish guard 冻结该顺序中每个本地 `.tgz` 的 digest，并仅发布这些精确 tarball；发布前每项重新检查目标 version 不存在，绝不以 `--skip-existing` 接受未知 registry bytes；`publish_tag` 默认 `alpha`。
-- 新增 public workspace 包不需要改 workflow；只要被 `pnpm-workspace.yaml` 收录、`package.json` 带 `name` / `version` 且没有 `private: true`，在 `publish_all=true` 时会自动进入全量发布计划。只想发新包时优先填写 `packages=<new-package>`，让发布计划自动补内部依赖顺序。
+- 新增 public workspace 包默认不需要改 workflow；只要被 `pnpm-workspace.yaml` 收录、`package.json` 带 `name` / `version` 且没有 `private: true`，在 `publish_all=true` 时会自动进入本仓全量发布计划。唯一例外是由获准独立源码仓库拥有并发布的 workspace 包：其 `repository.url` 必须命中 `publish-plan` 的显式 allowlist，计划必须把它列入 `skippedIndependent`，无论全量还是按包点名都不得从本仓发布；未知独立仓库或显式点名必须 fail closed。版本、tag、provenance 与 npm postflight 由该独立仓库自己的受保护发布流程负责。
 - `onework`、`oneork`、`oneorks` 是 `oneworks` bootstrap 的 typo publish alias，必须从 `apps/bootstrap/package.json` 的 `oneworks.publishAliases` 自动展开，同源改名发布；不要为它们创建独立 workspace 包，不要让它们依赖 `oneworks`，也不要写额外 redirect 逻辑。发布这组包且要保证裸 `npx onework` 和 `npx oneworks` 行为一致时，必须在首次发布该版本时使用 `publish_tag=latest`，或在发布后立刻用有 2FA 权限的 npm 登录态执行 `npm dist-tag add <pkg>@<version> latest` 补齐 `oneworks` 和三个 publish alias 包。
 - 发布 guard 在目标 version 已存在时失败而非跳过；mixed-result 必须由 postflight 完整对账并按恢复规则处理。
 - npm Trusted Publishing 要求 package 已存在。新增包第一次发布必须依赖 `NPM_TOKEN` 完成 bootstrap；首发成功后，必须在 npm 为该包配置 Trusted Publisher：GitHub Actions、`oneworks-ai/app`、workflow filename `npm-publish-alpha.yml`、允许 `npm publish`。后续同包版本再通过 Trusted Publishing 发布。
diff --git a/apps/client/__tests__/account-quota.spec.tsx b/apps/client/__tests__/account-quota.spec.tsx
index 2d37693ba..647b1c281 100644
--- a/apps/client/__tests__/account-quota.spec.tsx
+++ b/apps/client/__tests__/account-quota.spec.tsx
@@ -398,7 +398,7 @@ describe('account quota indicators', () => {
     expect(getAdapterResetCreditOutcomeTone(getAdapterResetCreditOutcome('noCredit'))).toBe('warning')
   })
 
-  it('keeps a deterministic pixel fallback behind a remote account avatar', () => {
+  it('keeps a deterministic 3D fallback behind a remote account avatar', () => {
     const html = renderToStaticMarkup(
       <AccountAvatar
         option={{
@@ -410,7 +410,7 @@ describe('account quota indicators', () => {
       />
     )
 
-    expect(html).toContain('account-avatar__pixel')
+    expect(html).toContain('account-avatar__fallback')
     expect(html).toContain('account-avatar__image')
     expect(html).toContain('referrerPolicy="no-referrer"')
   })
diff --git a/apps/client/__tests__/agent-room-rendering.spec.tsx b/apps/client/__tests__/agent-room-rendering.spec.tsx
index 480cca5ab..c17ca662b 100644
--- a/apps/client/__tests__/agent-room-rendering.spec.tsx
+++ b/apps/client/__tests__/agent-room-rendering.spec.tsx
@@ -645,7 +645,7 @@ describe('agent room transcript rendering', () => {
     ])
   })
 
-  it('uses pixel avatars for room participants without configured avatar labels', async () => {
+  it('uses 3D avatars for room participants without configured avatar labels', async () => {
     const html = await renderRoom({
       room: {
         ...fixtureRoom,
@@ -656,16 +656,16 @@ describe('agent room transcript rendering', () => {
     const reviewerMessage = getMessageMarkup(html, 'msg-reviewer-failed')
 
     expectContains(assignmentMessage, [
-      'agent-room-bubble__avatar--pixel',
-      'class="room-pixel-avatar agent-room-bubble__avatar-pixel"',
-      'class="room-pixel-avatar__image"',
-      'src="data:image/svg+xml'
+      'agent-room-bubble__avatar--generated',
+      'class="room-avatar agent-room-bubble__avatar-generated"',
+      'room-avatar__model',
+      'interactive-avatar__canvas'
     ])
     expectContains(reviewerMessage, [
-      'agent-room-bubble__avatar--pixel',
-      'class="room-pixel-avatar agent-room-bubble__avatar-pixel"',
-      'class="room-pixel-avatar__image"',
-      'src="data:image/svg+xml'
+      'agent-room-bubble__avatar--generated',
+      'class="room-avatar agent-room-bubble__avatar-generated"',
+      'room-avatar__model',
+      'interactive-avatar__canvas'
     ])
   })
 
@@ -1980,7 +1980,7 @@ describe('agent room transcript rendering', () => {
       '.agent-room-bubble__content--targeted {',
       'flex-direction: column;',
       '.agent-room-bubble__content-text--markdown {',
-      '--room-pixel-avatar-radius: 6px;',
+      '--room-avatar-radius: 6px;',
       '.agent-room-bubble__expand {',
       'align-self: flex-start;',
       'justify-content: center;',
diff --git a/apps/client/__tests__/agent-room-sidebar-card.spec.tsx b/apps/client/__tests__/agent-room-sidebar-card.spec.tsx
index 343d41deb..352ccca23 100644
--- a/apps/client/__tests__/agent-room-sidebar-card.spec.tsx
+++ b/apps/client/__tests__/agent-room-sidebar-card.spec.tsx
@@ -86,9 +86,10 @@ describe('agent room sidebar card', () => {
     expect(html).not.toContain('room-item__stats')
     expect(html).not.toContain(room.lastMessage)
     expect(html).not.toContain('room-item__last-message')
-    expect(html).toContain('room-pixel-avatar')
-    expect(html).toContain('room-pixel-avatar__image')
-    expect(html).toContain('data:image/svg+xml')
+    expect(html).toContain('room-avatar')
+    expect(html).toContain('room-avatar__model')
+    expect(html).toContain('interactive-avatar__canvas')
+    expect(html).not.toContain('data:image/svg+xml')
     expect(html).not.toContain('>groups</span>')
   })
 
@@ -119,12 +120,12 @@ describe('agent room sidebar card', () => {
 
     expect(styles).toContain('line-height: 1;')
     expect(styles).toContain('min-width: var(--room-actions-reserved-width);')
-    expect(styles).toContain('.room-pixel-avatar')
+    expect(styles).toContain('.room-avatar')
     expect(styles).toContain('align-items: center;')
     expect(styles).toContain('align-self: center;')
     expect(styles).toContain('--room-item-avatar-size: var(--session-leading-size, 16px);')
-    expect(styles).toContain('&.room-pixel-avatar')
-    expect(styles).toContain('--room-pixel-avatar-radius: var(--room-item-avatar-radius);')
+    expect(styles).toContain('&.room-avatar')
+    expect(styles).toContain('--room-avatar-radius: var(--room-item-avatar-radius);')
     expect(styles).toContain('& &__actions &__action-btn')
     expect(styles).toContain('box-shadow: none;')
     expect(styles).not.toContain('align-items: stretch;')
diff --git a/apps/client/__tests__/chat-header-session-title.spec.tsx b/apps/client/__tests__/chat-header-session-title.spec.tsx
index 9e1730cf9..4dbc223a7 100644
--- a/apps/client/__tests__/chat-header-session-title.spec.tsx
+++ b/apps/client/__tests__/chat-header-session-title.spec.tsx
@@ -171,7 +171,7 @@ describe('chat header session title', () => {
     expect(html).toContain('chat_bubble')
     expect(html).toContain('chat-header-room-icon')
     expect(html).toContain('chat-header-room-icon--completed')
-    expect(html).toContain('room-pixel-avatar')
+    expect(html).toContain('room-avatar')
   })
 
   it('renders the room title icon without requiring an explicit icon seed', async () => {
@@ -185,7 +185,7 @@ describe('chat header session title', () => {
     })
 
     expect(html).toContain('chat-header-room-icon')
-    expect(html).toContain('room-pixel-avatar')
+    expect(html).toContain('room-avatar')
     expect(html).toContain('Agent Room')
   })
 
diff --git a/apps/client/package.json b/apps/client/package.json
index 7fe93fd92..30c8d3cc6 100644
--- a/apps/client/package.json
+++ b/apps/client/package.json
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@oneworks/avatar": "workspace:*",
+    "@oneworks/avatar-react": "workspace:*",
     "@oneworks/components": "workspace:*",
     "@oneworks/cursor": "workspace:*",
     "@oneworks/diagnostics": "workspace:*",
diff --git a/apps/client/src/components/agent-room/@components/AgentRoomAvatarContent.tsx b/apps/client/src/components/agent-room/@components/AgentRoomAvatarContent.tsx
index 61f27eb0d..62d5e6cfd 100644
--- a/apps/client/src/components/agent-room/@components/AgentRoomAvatarContent.tsx
+++ b/apps/client/src/components/agent-room/@components/AgentRoomAvatarContent.tsx
@@ -1,7 +1,7 @@
 import { useState } from 'react'
 
 import { getWorkspaceResourceUrl } from '#~/api'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 
 import type { AgentRoomMemberView } from '../@types/agent-room-view'
 
@@ -16,11 +16,11 @@ export const resolveAgentRoomAvatar = (value: string | undefined) => {
 export function AgentRoomAvatarContent({
   imageClassName,
   member,
-  pixelClassName
+  generatedClassName
 }: {
   imageClassName?: string
   member: Pick<AgentRoomMemberView, 'avatar' | 'avatarLabel' | 'memberKey'>
-  pixelClassName: string
+  generatedClassName: string
 }) {
   const avatar = resolveAgentRoomAvatar(member.avatar)
   const [failedAvatar, setFailedAvatar] = useState<string>()
@@ -31,5 +31,5 @@ export function AgentRoomAvatarContent({
   const avatarLabel = member.avatarLabel?.trim()
   if (avatarLabel != null && avatarLabel !== '') return avatarLabel
 
-  return <RoomPixelAvatar className={pixelClassName} seed={`entity:${member.memberKey}`} />
+  return <RoomAvatar className={generatedClassName} seed={`entity:${member.memberKey}`} />
 }
diff --git a/apps/client/src/components/agent-room/@components/AgentRoomBubble.tsx b/apps/client/src/components/agent-room/@components/AgentRoomBubble.tsx
index 06565b4c9..f04942804 100644
--- a/apps/client/src/components/agent-room/@components/AgentRoomBubble.tsx
+++ b/apps/client/src/components/agent-room/@components/AgentRoomBubble.tsx
@@ -192,7 +192,7 @@ const renderSystemMessageContent = (message: AgentRoomMessageView, t: TFunction)
             <AgentRoomAvatarContent
               imageClassName='agent-room-bubble__joined-avatar-image'
               member={member}
-              pixelClassName='agent-room-bubble__joined-avatar-pixel'
+              generatedClassName='agent-room-bubble__joined-avatar-generated'
             />
           </span>
         ))}
@@ -417,7 +417,7 @@ export function AgentRoomBubble({
                 type='button'
                 className={[
                   'agent-room-bubble__avatar',
-                  avatarMember.avatar == null && avatarLabel == null ? 'agent-room-bubble__avatar--pixel' : '',
+                  avatarMember.avatar == null && avatarLabel == null ? 'agent-room-bubble__avatar--generated' : '',
                   'agent-room-bubble__avatar-button'
                 ].filter(Boolean).join(' ')}
                 aria-expanded={senderPopover.isPinned}
@@ -430,7 +430,7 @@ export function AgentRoomBubble({
                 <AgentRoomAvatarContent
                   imageClassName='agent-room-bubble__avatar-image'
                   member={avatarMember}
-                  pixelClassName='agent-room-bubble__avatar-pixel'
+                  generatedClassName='agent-room-bubble__avatar-generated'
                 />
               </button>
               <PinnedPopoverPortal
@@ -448,7 +448,7 @@ export function AgentRoomBubble({
                     <AgentRoomAvatarContent
                       imageClassName='agent-room-bubble__avatar-image'
                       member={avatarMember}
-                      pixelClassName='agent-room-bubble__avatar-pixel'
+                      generatedClassName='agent-room-bubble__avatar-generated'
                     />
                   </span>
                   <span className='agent-room-bubble__sender-popover-copy'>
@@ -482,14 +482,14 @@ export function AgentRoomBubble({
             <div
               className={[
                 'agent-room-bubble__avatar',
-                avatarMember.avatar == null && avatarLabel == null ? 'agent-room-bubble__avatar--pixel' : ''
+                avatarMember.avatar == null && avatarLabel == null ? 'agent-room-bubble__avatar--generated' : ''
               ].filter(Boolean).join(' ')}
               aria-hidden='true'
             >
               <AgentRoomAvatarContent
                 imageClassName='agent-room-bubble__avatar-image'
                 member={avatarMember}
-                pixelClassName='agent-room-bubble__avatar-pixel'
+                generatedClassName='agent-room-bubble__avatar-generated'
               />
             </div>
           )
diff --git a/apps/client/src/components/agent-room/@components/AgentRoomRoster.tsx b/apps/client/src/components/agent-room/@components/AgentRoomRoster.tsx
index e44d39567..5a70b8442 100644
--- a/apps/client/src/components/agent-room/@components/AgentRoomRoster.tsx
+++ b/apps/client/src/components/agent-room/@components/AgentRoomRoster.tsx
@@ -63,14 +63,14 @@ export function AgentRoomRoster({
               <div
                 className={[
                   'agent-room-roster__avatar',
-                  member.avatar == null && avatarLabel == null ? 'agent-room-roster__avatar--pixel' : ''
+                  member.avatar == null && avatarLabel == null ? 'agent-room-roster__avatar--generated' : ''
                 ].filter(Boolean).join(' ')}
                 aria-hidden='true'
               >
                 <AgentRoomAvatarContent
                   imageClassName='agent-room-roster__avatar-image'
                   member={member}
-                  pixelClassName='agent-room-roster__avatar-pixel'
+                  generatedClassName='agent-room-roster__avatar-generated'
                 />
               </div>
               <div className='agent-room-roster__member-copy'>
diff --git a/apps/client/src/components/agent-room/AgentRoomView.scss b/apps/client/src/components/agent-room/AgentRoomView.scss
index 5766695ed..e961d2880 100644
--- a/apps/client/src/components/agent-room/AgentRoomView.scss
+++ b/apps/client/src/components/agent-room/AgentRoomView.scss
@@ -256,9 +256,9 @@
   object-fit: cover;
 }
 
-.agent-room-bubble__joined-avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: 20px;
-  --room-pixel-avatar-radius: 4px;
+.agent-room-bubble__joined-avatar-generated.room-avatar {
+  --room-avatar-size: 20px;
+  --room-avatar-radius: 4px;
 }
 
 .agent-room-bubble:focus-visible .agent-room-bubble__surface,
@@ -294,32 +294,32 @@
   font: inherit;
 }
 
-.agent-room-bubble__avatar--pixel,
-.agent-room-roster__avatar--pixel {
+.agent-room-bubble__avatar--generated,
+.agent-room-roster__avatar--generated {
   padding: 0;
   border: 0;
   background: transparent;
 }
 
-.agent-room-bubble__avatar-pixel.room-pixel-avatar,
-.agent-room-roster__avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: var(--agent-room-bubble-avatar-size, 34px);
-  --room-pixel-avatar-bg: color-mix(
+.agent-room-bubble__avatar-generated.room-avatar,
+.agent-room-roster__avatar-generated.room-avatar {
+  --room-avatar-size: var(--agent-room-bubble-avatar-size, 34px);
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--tag-bg) 86%,
     var(--sub-bg-color)
   );
-  --room-pixel-avatar-border: color-mix(
+  --room-avatar-border: color-mix(
     in srgb,
-    var(--room-pixel-avatar-accent) 54%,
+    var(--room-avatar-accent) 54%,
     var(--border-color)
   );
-  --room-pixel-avatar-overlay: color-mix(
+  --room-avatar-overlay: color-mix(
     in srgb,
-    var(--room-pixel-avatar-accent) 20%,
+    var(--room-avatar-accent) 20%,
     transparent
   );
-  --room-pixel-avatar-radius: 6px;
+  --room-avatar-radius: 6px;
 }
 
 .agent-room-bubble__avatar-spacer {
@@ -404,9 +404,9 @@
   background: var(--tag-bg);
 }
 
-.agent-room-bubble__sender-popover-avatar .room-pixel-avatar {
-  --room-pixel-avatar-size: 36px;
-  --room-pixel-avatar-radius: 6px;
+.agent-room-bubble__sender-popover-avatar .room-avatar {
+  --room-avatar-size: 36px;
+  --room-avatar-radius: 6px;
 }
 
 .agent-room-bubble__sender-popover-copy,
@@ -760,13 +760,13 @@
   box-shadow: none;
 }
 
-.agent-room-bubble--leader .agent-room-bubble__avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-bg: color-mix(
+.agent-room-bubble--leader .agent-room-bubble__avatar-generated.room-avatar {
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--primary-color) 10%,
     var(--tag-bg)
   );
-  --room-pixel-avatar-border: color-mix(
+  --room-avatar-border: color-mix(
     in srgb,
     var(--primary-color) 46%,
     var(--border-color)
diff --git a/apps/client/src/components/chat/AGENTS.md b/apps/client/src/components/chat/AGENTS.md
index 01683f1cd..e0181ef8b 100644
--- a/apps/client/src/components/chat/AGENTS.md
+++ b/apps/client/src/components/chat/AGENTS.md
@@ -114,7 +114,7 @@
 
 - 聊天状态栏和账号下拉的额度数据统一走 `src/hooks/use-adapter-accounts-with-quota.ts`，只读取 adapter 已持久化 / 缓存的账号与额度快照；聊天挂载或启动会话时不得自动发起 `refresh: true` live quota probe，因为 Codex probe 是独立 app-server，可能与会话 app-server 同时进入 OAuth refresh。设置页、额度详情或用户显式刷新继续走对应 detail / action 链路，不要在各个 chat surface 内重复请求。
 - 五小时 / 七天窗口统一由 `src/utils/account-quota.ts` 解析，并复用 `src/components/account-quota/QuotaUsageRing.tsx`；配置详情、状态栏和下拉选项不要各自猜测 metric id、label 或百分比语义。
-- `AccountAvatar` 只消费 adapter 返回的 `avatarUrl`，缺失或图片加载失败时使用本地确定性像素头像；浏览器端不得读取 Codex auth 或自行调用 ChatGPT profile 接口。
+- `AccountAvatar` 只消费 adapter 返回的 `avatarUrl`，缺失或图片加载失败时使用本地确定性 3D 头像；浏览器端不得读取 Codex auth 或自行调用 ChatGPT profile 接口。
 - 状态栏额度环必须放在 `.sender-select-shell--account` 外部，与 select 作为 `.chat-status-bar__account-group` 的 sibling；整个 group 是 popup 宽度锚点。不要把额度环塞进 select shell，否则 trigger 内容会被挤压，popup 也只会继承账号文本宽度。
 - 账号选项内也要展示对应账号的额度，避免 trigger 与 popup 信息密度不一致。
 - 改这条链路时至少覆盖共享额度解析、账号详情、状态栏和下拉列表，并用真实账号刷新验证头像 URL、5h / 7d 两个窗口及图片加载结果。
diff --git a/apps/client/src/components/chat/ChatHeader.scss b/apps/client/src/components/chat/ChatHeader.scss
index 0a4e8e582..ac6b822db 100644
--- a/apps/client/src/components/chat/ChatHeader.scss
+++ b/apps/client/src/components/chat/ChatHeader.scss
@@ -55,14 +55,14 @@
   color: var(--sub-text-color);
 }
 
-.chat-header-room-icon.room-pixel-avatar {
-  --room-pixel-avatar-bg: color-mix(
+.chat-header-room-icon.room-avatar {
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--sidebar-active-text) 12%,
     var(--sidebar-active-bg)
   );
-  --room-pixel-avatar-border: var(--sidebar-active-text);
-  --room-pixel-avatar-radius: 6px;
+  --room-avatar-border: var(--sidebar-active-text);
+  --room-avatar-radius: 6px;
 
   width: var(
     --route-container-header-icon-size,
@@ -75,24 +75,24 @@
   padding: 2px;
 }
 
-.chat-header-room-icon--completed.room-pixel-avatar {
-  --room-pixel-avatar-bg: color-mix(
+.chat-header-room-icon--completed.room-avatar {
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--success-color) 18%,
     var(--tag-bg)
   );
 }
 
-.chat-header-room-icon--failed.room-pixel-avatar {
-  --room-pixel-avatar-bg: color-mix(
+.chat-header-room-icon--failed.room-avatar {
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--danger-color) 18%,
     var(--tag-bg)
   );
 }
 
-.chat-header-room-icon--idle.room-pixel-avatar {
-  --room-pixel-avatar-bg: color-mix(
+.chat-header-room-icon--idle.room-avatar {
+  --room-avatar-bg: color-mix(
     in srgb,
     var(--sub-text-color) 14%,
     var(--tag-bg)
diff --git a/apps/client/src/components/chat/ChatHeader.tsx b/apps/client/src/components/chat/ChatHeader.tsx
index 5f0b881c9..efb73758d 100644
--- a/apps/client/src/components/chat/ChatHeader.tsx
+++ b/apps/client/src/components/chat/ChatHeader.tsx
@@ -33,7 +33,7 @@ import { ConfigSectionPanel } from '../config'
 import type { FieldSpec } from '../config/configSchema'
 import { MaterialSymbol } from '../icons/MaterialSymbol'
 import { RouteContainerHeader } from '../layout/RouteContainerHeader'
-import { RoomPixelAvatar } from '../room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '../room-avatar/RoomAvatar'
 import { InteractionPanelWorkspaceActions } from './interaction-panel/InteractionPanelWorkspaceActions'
 import type {
   InteractionPanelRunCommand,
@@ -259,7 +259,7 @@ export function ChatHeader({
   const roomTitleIconSeed = normalizeTitle(roomIconSeed) ?? displayTitle
   const roomTitleIcon = !hideTitleIcon && modeSwitch?.mode === 'room'
     ? (
-      <RoomPixelAvatar
+      <RoomAvatar
         className={[
           'chat-header-room-icon',
           roomIconStatus != null ? `chat-header-room-icon--${roomIconStatus}` : ''
diff --git a/apps/client/src/components/chat/messages/MessageItem.scss b/apps/client/src/components/chat/messages/MessageItem.scss
index 131cea892..84b54991c 100644
--- a/apps/client/src/components/chat/messages/MessageItem.scss
+++ b/apps/client/src/components/chat/messages/MessageItem.scss
@@ -381,13 +381,13 @@
 }
 
 .message-source-line__avatar {
-  --room-pixel-avatar-size: 14px;
-  --room-pixel-avatar-radius: 3px;
-  --room-pixel-avatar-bg: rgba(17, 24, 39, .38);
-  --room-pixel-avatar-border: transparent;
-  --room-pixel-avatar-overlay: color-mix(
+  --room-avatar-size: 14px;
+  --room-avatar-radius: 3px;
+  --room-avatar-bg: rgba(17, 24, 39, .38);
+  --room-avatar-border: transparent;
+  --room-avatar-overlay: color-mix(
     in srgb,
-    var(--room-pixel-avatar-accent) 22%,
+    var(--room-avatar-accent) 22%,
     rgba(255, 255, 255, .08)
   );
 
diff --git a/apps/client/src/components/chat/messages/MessageItem.tsx b/apps/client/src/components/chat/messages/MessageItem.tsx
index e90cca175..2a7e5c4ba 100644
--- a/apps/client/src/components/chat/messages/MessageItem.tsx
+++ b/apps/client/src/components/chat/messages/MessageItem.tsx
@@ -12,7 +12,7 @@ import { MarkdownContent } from '#~/components/MarkdownContent'
 import type { MarkdownImageRenderProps, MarkdownMediaRenderProps } from '#~/components/MarkdownContent'
 import type { AgentRoomMemberView } from '#~/components/agent-room'
 import { getAppBrowserLinkUrl, openExternalLink } from '#~/components/markdown-link-context-menu-utils'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 import { parseWorkspaceFileLinkForWorkspaceRoot } from '#~/utils/link-targets'
 import type { WorkspaceFileLinkTarget } from '#~/utils/link-targets'
 import { resolveMarkdownLinkIntentTarget } from '#~/utils/markdown-link-intent'
@@ -619,8 +619,8 @@ function MessageItemComponent({
                               </span>
                             )
                             : (
-                              <RoomPixelAvatar
-                                className='message-source-line__avatar message-source-line__avatar--pixel'
+                              <RoomAvatar
+                                className='message-source-line__avatar message-source-line__avatar--generated'
                                 seed={agentRoomMessageSource.avatarSeed}
                               />
                             )}
diff --git a/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.scss b/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.scss
index b6c82316f..151f718fa 100644
--- a/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.scss
+++ b/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.scss
@@ -28,10 +28,10 @@
   object-fit: cover;
 }
 
-.account-avatar__pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: var(--account-avatar-size);
-  --room-pixel-avatar-radius: 50%;
-  --room-pixel-avatar-border: transparent;
+.account-avatar__fallback.room-avatar {
+  --room-avatar-size: var(--account-avatar-size);
+  --room-avatar-radius: 50%;
+  --room-avatar-border: transparent;
 
   width: var(--account-avatar-size);
   height: var(--account-avatar-size);
diff --git a/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.tsx b/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.tsx
index 8fab284da..207d7e5c0 100644
--- a/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.tsx
+++ b/apps/client/src/components/chat/sender/@components/account-select/AccountAvatar.tsx
@@ -1,6 +1,6 @@
 import './AccountAvatar.scss'
 
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 import type { ChatAdapterAccountOption } from '#~/hooks/chat/use-chat-adapter-account-selection'
 
 const normalizeOptionalText = (value: string | undefined) => {
@@ -25,8 +25,8 @@ export function AccountAvatar({
 
   return (
     <span className={`account-avatar account-avatar--${size}`} aria-hidden='true'>
-      <RoomPixelAvatar
-        className='account-avatar__pixel'
+      <RoomAvatar
+        className='account-avatar__fallback'
         seed={`adapter-account:${getAccountAvatarSeed(option)}`}
       />
       {avatarUrl != null && (
diff --git a/apps/client/src/components/config/AdapterAccountPreview.scss b/apps/client/src/components/config/AdapterAccountPreview.scss
index b7c0f9108..4ba66c382 100644
--- a/apps/client/src/components/config/AdapterAccountPreview.scss
+++ b/apps/client/src/components/config/AdapterAccountPreview.scss
@@ -152,10 +152,10 @@
   background: transparent;
 }
 
-.adapter-account-preview__avatar-fallback.room-pixel-avatar {
-  --room-pixel-avatar-size: 28px;
-  --room-pixel-avatar-radius: 50%;
-  --room-pixel-avatar-border: transparent;
+.adapter-account-preview__avatar-fallback.room-avatar {
+  --room-avatar-size: 28px;
+  --room-avatar-radius: 50%;
+  --room-avatar-border: transparent;
 
   width: 28px;
   height: 28px;
diff --git a/apps/client/src/components/config/AdapterAccountPreview.tsx b/apps/client/src/components/config/AdapterAccountPreview.tsx
index 5cd8d7099..20edd3386 100644
--- a/apps/client/src/components/config/AdapterAccountPreview.tsx
+++ b/apps/client/src/components/config/AdapterAccountPreview.tsx
@@ -5,7 +5,7 @@ import { useMemo } from 'react'
 import type { AdapterAccountInfo } from '@oneworks/types'
 
 import { QuotaUsageRing } from '#~/components/account-quota/QuotaUsageRing'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 import { getAccountQuotaWindows } from '#~/utils/account-quota'
 
 import { useAdapterAccountPreviewData } from './@hooks/use-adapter-account-preview-data'
@@ -162,7 +162,7 @@ function AccountPreviewRow({
       onClick={onOpen}
     >
       <span className='adapter-account-preview__avatar' aria-hidden='true'>
-        <RoomPixelAvatar
+        <RoomAvatar
           className='adapter-account-preview__avatar-fallback'
           seed={`adapter-account:${getAccountAvatarSeed(account, identity.name)}`}
         />
diff --git a/apps/client/src/components/config/AdapterAccountsManager.scss b/apps/client/src/components/config/AdapterAccountsManager.scss
index 3de5f23ce..b8b50702e 100644
--- a/apps/client/src/components/config/AdapterAccountsManager.scss
+++ b/apps/client/src/components/config/AdapterAccountsManager.scss
@@ -387,10 +387,10 @@
   border-radius: 50%;
 }
 
-.adapter-account-manager__item-avatar-fallback.room-pixel-avatar {
-  --room-pixel-avatar-size: 34px;
-  --room-pixel-avatar-radius: 50%;
-  --room-pixel-avatar-border: transparent;
+.adapter-account-manager__item-avatar-fallback.room-avatar {
+  --room-avatar-size: 34px;
+  --room-avatar-radius: 50%;
+  --room-avatar-border: transparent;
 
   width: 34px;
   height: 34px;
diff --git a/apps/client/src/components/config/AdapterAccountsManager.tsx b/apps/client/src/components/config/AdapterAccountsManager.tsx
index 59b904697..691074bad 100644
--- a/apps/client/src/components/config/AdapterAccountsManager.tsx
+++ b/apps/client/src/components/config/AdapterAccountsManager.tsx
@@ -18,7 +18,7 @@ import { AccountQuotaPanel } from '#~/components/account-quota/AccountQuotaPanel
 import { QuotaUsageRing } from '#~/components/account-quota/QuotaUsageRing'
 import { ActionSearchToolbar } from '#~/components/action-search-toolbar/ActionSearchToolbar'
 import { NativeTabs } from '#~/components/native-tabs'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 import { UsagePanel } from '#~/components/usage/UsagePanel'
 import { focusDesktopWindowIfAvailable } from '#~/desktop/manager-runtime'
 import { useAdapterAccountQuotaDetail } from '#~/hooks/use-adapter-account-quota-detail'
@@ -823,7 +823,7 @@ const AccountsListView = ({
                   onClick={() => onOpenAccount(account.key)}
                 >
                   <span className='adapter-account-manager__item-avatar' aria-hidden='true'>
-                    <RoomPixelAvatar
+                    <RoomAvatar
                       className='adapter-account-manager__item-avatar-fallback'
                       seed={`adapter-account:${getAccountAvatarSeed(account)}`}
                     />
diff --git a/apps/client/src/components/entity-card/EntityCard.scss b/apps/client/src/components/entity-card/EntityCard.scss
index d8e5ad655..6a26161b8 100644
--- a/apps/client/src/components/entity-card/EntityCard.scss
+++ b/apps/client/src/components/entity-card/EntityCard.scss
@@ -73,9 +73,9 @@
   object-fit: cover;
 }
 
-.entity-card__avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: 36px;
-  --room-pixel-avatar-radius: 6px;
+.entity-card__avatar-generated.room-avatar {
+  --room-avatar-size: 36px;
+  --room-avatar-radius: 6px;
 }
 
 .entity-card__copy {
diff --git a/apps/client/src/components/entity-card/EntityCard.tsx b/apps/client/src/components/entity-card/EntityCard.tsx
index 321a37241..5848d98f8 100644
--- a/apps/client/src/components/entity-card/EntityCard.tsx
+++ b/apps/client/src/components/entity-card/EntityCard.tsx
@@ -5,7 +5,7 @@ import type { KeyboardEvent } from 'react'
 import { getWorkspaceResourceUrl } from '#~/api'
 import { GroupAvatar } from '#~/components/group-avatar/GroupAvatar'
 import type { GroupAvatarMember } from '#~/components/group-avatar/GroupAvatar'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 
 const resolveAvatarUrl = (avatar: string | undefined) => {
   const value = avatar?.trim()
@@ -71,7 +71,7 @@ export function EntityCard({
       />
       <span className='entity-card__avatar' aria-hidden='true'>
         {avatarUrl == null
-          ? <RoomPixelAvatar className='entity-card__avatar-pixel' seed={`entity:${entityId}`} />
+          ? <RoomAvatar className='entity-card__avatar-generated' seed={`entity:${entityId}`} />
           : <img alt='' className='entity-card__avatar-image' src={avatarUrl} />}
       </span>
       <span className='entity-card__copy'>
diff --git a/apps/client/src/components/entity-summary/EntitySummary.scss b/apps/client/src/components/entity-summary/EntitySummary.scss
index 6bdf0f5eb..fa015dff3 100644
--- a/apps/client/src/components/entity-summary/EntitySummary.scss
+++ b/apps/client/src/components/entity-summary/EntitySummary.scss
@@ -84,8 +84,8 @@
   height: 56px;
 }
 
-.entity-summary--detail .entity-summary__avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: 56px;
+.entity-summary--detail .entity-summary__avatar-generated.room-avatar {
+  --room-avatar-size: 56px;
 }
 
 .entity-summary--detail .entity-summary__copy > strong {
@@ -109,9 +109,9 @@
   object-fit: cover;
 }
 
-.entity-summary__avatar-pixel.room-pixel-avatar {
-  --room-pixel-avatar-size: 44px;
-  --room-pixel-avatar-radius: 6px;
+.entity-summary__avatar-generated.room-avatar {
+  --room-avatar-size: 44px;
+  --room-avatar-radius: 6px;
 }
 
 .entity-summary__copy,
diff --git a/apps/client/src/components/entity-summary/EntitySummary.tsx b/apps/client/src/components/entity-summary/EntitySummary.tsx
index edc298019..3386e852e 100644
--- a/apps/client/src/components/entity-summary/EntitySummary.tsx
+++ b/apps/client/src/components/entity-summary/EntitySummary.tsx
@@ -1,7 +1,7 @@
 import './EntitySummary.scss'
 
 import { getWorkspaceResourceUrl } from '#~/api'
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 
 const resolveAvatarUrl = (avatar: string | undefined) => {
   const value = avatar?.trim()
@@ -45,7 +45,7 @@ export function EntitySummary({
     <>
       <span className='entity-summary__avatar' aria-hidden='true'>
         {avatarUrl == null
-          ? <RoomPixelAvatar className='entity-summary__avatar-pixel' seed={`entity:${entityId}`} />
+          ? <RoomAvatar className='entity-summary__avatar-generated' seed={`entity:${entityId}`} />
           : <img alt='' className='entity-summary__avatar-image' src={avatarUrl} />}
       </span>
       <span className='entity-summary__copy'>
diff --git a/apps/client/src/components/group-avatar/GroupAvatar.scss b/apps/client/src/components/group-avatar/GroupAvatar.scss
index d2f7e1446..401a1888a 100644
--- a/apps/client/src/components/group-avatar/GroupAvatar.scss
+++ b/apps/client/src/components/group-avatar/GroupAvatar.scss
@@ -24,7 +24,8 @@
   padding: 0;
 }
 
-.group-avatar__cell > img {
+.group-avatar__cell > img,
+.group-avatar__cell > .oneworks-avatar {
   display: block;
   width: 100%;
   height: 100%;
diff --git a/apps/client/src/components/group-avatar/GroupAvatar.tsx b/apps/client/src/components/group-avatar/GroupAvatar.tsx
index 93b4cf97f..73c93f434 100644
--- a/apps/client/src/components/group-avatar/GroupAvatar.tsx
+++ b/apps/client/src/components/group-avatar/GroupAvatar.tsx
@@ -1,8 +1,9 @@
 import './GroupAvatar.scss'
 
-import { createSeededAvatarDataUri } from '@oneworks/avatar'
+import { createSeededAvatarDefinition } from '@oneworks/avatar'
+import { Avatar } from '@oneworks/avatar-react'
 import type { CSSProperties } from 'react'
-import { useState } from 'react'
+import { useMemo, useState } from 'react'
 
 import { getWorkspaceResourceUrl } from '#~/api'
 
@@ -14,34 +15,31 @@ export interface GroupAvatarMember {
 
 const resolveAvatarUrl = (member: GroupAvatarMember) => {
   const avatar = member.avatar?.trim()
-  if (avatar != null && avatar !== '') {
-    return /^(?:blob:|data:|https?:\/\/)/u.test(avatar)
-      ? avatar
-      : getWorkspaceResourceUrl(avatar)
-  }
-  return createSeededAvatarDataUri({
-    seed: `entity:${member.key}`,
-    size: 72,
-    title: member.label ?? member.key
-  })
+  if (avatar == null || avatar === '') return undefined
+  return /^(?:blob:|data:|https?:\/\/)/u.test(avatar)
+    ? avatar
+    : getWorkspaceResourceUrl(avatar)
 }
 
-const resolveFallbackAvatarUrl = (member: GroupAvatarMember) =>
-  createSeededAvatarDataUri({
-    seed: `entity:${member.key}`,
-    size: 72,
-    title: member.label ?? member.key
-  })
-
 function GroupAvatarImage({ member }: { member: GroupAvatarMember }) {
   const [failedAvatar, setFailedAvatar] = useState<string>()
   const avatar = resolveAvatarUrl(member)
+  const definition = useMemo(() =>
+    createSeededAvatarDefinition({
+      name: member.label ?? member.key,
+      seed: `entity:${member.key}`
+    }), [member.key, member.label])
+
+  if (avatar == null || failedAvatar === avatar) {
+    return <Avatar aria-hidden='true' definition={definition} />
+  }
+
   return (
     <img
       alt=''
       draggable={false}
       onError={() => setFailedAvatar(avatar)}
-      src={failedAvatar === avatar ? resolveFallbackAvatarUrl(member) : avatar}
+      src={avatar}
     />
   )
 }
diff --git a/apps/client/src/components/room-avatar/RoomAvatar.scss b/apps/client/src/components/room-avatar/RoomAvatar.scss
new file mode 100644
index 000000000..05596e555
--- /dev/null
+++ b/apps/client/src/components/room-avatar/RoomAvatar.scss
@@ -0,0 +1,35 @@
+.room-avatar {
+  --room-avatar-accent: var(--primary-color);
+  --room-avatar-accent-soft: var(--primary-soft-bg);
+  --room-avatar-bg: var(--tag-bg);
+  --room-avatar-border: var(--border-color);
+  --room-avatar-overlay: color-mix(
+    in srgb,
+    var(--room-avatar-accent) 18%,
+    transparent
+  );
+  --room-avatar-radius: 6px;
+  --room-avatar-size: 28px;
+
+  display: inline-flex;
+  align-items: stretch;
+  justify-content: stretch;
+  width: var(--room-avatar-size);
+  height: var(--room-avatar-size);
+  max-width: 100%;
+  max-height: 100%;
+  flex: 0 0 auto;
+  box-sizing: border-box;
+  padding: 0;
+  border: 1px solid var(--room-avatar-border);
+  border-radius: var(--room-avatar-radius);
+  background: var(--room-avatar-bg);
+  overflow: hidden;
+}
+
+.room-avatar__model {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: calc(var(--room-avatar-radius) - 1px);
+}
diff --git a/apps/client/src/components/room-avatar/RoomAvatar.tsx b/apps/client/src/components/room-avatar/RoomAvatar.tsx
new file mode 100644
index 000000000..f0b5aae9f
--- /dev/null
+++ b/apps/client/src/components/room-avatar/RoomAvatar.tsx
@@ -0,0 +1,35 @@
+import './RoomAvatar.scss'
+
+import { createSeededAvatarDefinition } from '@oneworks/avatar'
+import { Avatar } from '@oneworks/avatar-react'
+import { useMemo } from 'react'
+
+export function RoomAvatar({
+  className,
+  label,
+  seed
+}: {
+  className?: string
+  label?: string
+  seed: string
+}) {
+  const definition = useMemo(() =>
+    createSeededAvatarDefinition({
+      name: label,
+      seed
+    }), [label, seed])
+
+  return (
+    <span
+      className={['room-avatar', className].filter(Boolean).join(' ')}
+      aria-label={label}
+      aria-hidden={label == null ? true : undefined}
+    >
+      <Avatar
+        aria-hidden='true'
+        className='room-avatar__model'
+        definition={definition}
+      />
+    </span>
+  )
+}
diff --git a/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.scss b/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.scss
deleted file mode 100644
index 6d6ab8a77..000000000
--- a/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.scss
+++ /dev/null
@@ -1,36 +0,0 @@
-.room-pixel-avatar {
-  --room-pixel-avatar-accent: var(--primary-color);
-  --room-pixel-avatar-accent-soft: var(--primary-soft-bg);
-  --room-pixel-avatar-bg: var(--tag-bg);
-  --room-pixel-avatar-border: var(--border-color);
-  --room-pixel-avatar-overlay: color-mix(
-    in srgb,
-    var(--room-pixel-avatar-accent) 18%,
-    transparent
-  );
-  --room-pixel-avatar-radius: 6px;
-  --room-pixel-avatar-size: 28px;
-
-  display: inline-flex;
-  align-items: stretch;
-  justify-content: stretch;
-  width: var(--room-pixel-avatar-size);
-  height: var(--room-pixel-avatar-size);
-  max-width: 100%;
-  max-height: 100%;
-  flex: 0 0 auto;
-  box-sizing: border-box;
-  padding: 0;
-  border: 1px solid var(--room-pixel-avatar-border);
-  border-radius: var(--room-pixel-avatar-radius);
-  background: var(--room-pixel-avatar-bg);
-  overflow: hidden;
-}
-
-.room-pixel-avatar__image {
-  display: block;
-  width: 100%;
-  height: 100%;
-  border-radius: calc(var(--room-pixel-avatar-radius) - 1px);
-  object-fit: cover;
-}
diff --git a/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.tsx b/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.tsx
deleted file mode 100644
index eabe79395..000000000
--- a/apps/client/src/components/room-pixel-avatar/RoomPixelAvatar.tsx
+++ /dev/null
@@ -1,36 +0,0 @@
-import './RoomPixelAvatar.scss'
-
-import { createSeededAvatarDataUri, resolveSeededAvatar } from '@oneworks/avatar'
-import { useMemo } from 'react'
-
-export function RoomPixelAvatar({
-  className,
-  label,
-  seed
-}: {
-  className?: string
-  label?: string
-  seed: string
-}) {
-  const avatar = useMemo(() => {
-    const config = resolveSeededAvatar({ seed })
-    return {
-      emoticon: config.emoticon,
-      uri: createSeededAvatarDataUri({
-        seed,
-        size: 128,
-        title: label ?? `OneWorks ${config.emoticon} avatar`
-      })
-    }
-  }, [label, seed])
-
-  return (
-    <span
-      className={['room-pixel-avatar', className].filter(Boolean).join(' ')}
-      aria-label={label}
-      aria-hidden={label == null ? true : undefined}
-    >
-      <img className='room-pixel-avatar__image' src={avatar.uri} alt='' aria-hidden='true' />
-    </span>
-  )
-}
diff --git a/apps/client/src/components/sidebar/RoomItem.scss b/apps/client/src/components/sidebar/RoomItem.scss
index 7f724fb21..bf8c4a501 100644
--- a/apps/client/src/components/sidebar/RoomItem.scss
+++ b/apps/client/src/components/sidebar/RoomItem.scss
@@ -8,10 +8,10 @@
   );
   --room-item-avatar-radius: 2px;
   --room-item-card-border: var(--border-color);
-  --room-pixel-avatar-border: var(--room-item-card-border);
-  --room-pixel-avatar-overlay: color-mix(
+  --room-avatar-border: var(--room-item-card-border);
+  --room-avatar-overlay: color-mix(
     in srgb,
-    var(--room-pixel-avatar-accent) 10%,
+    var(--room-avatar-accent) 10%,
     transparent
   );
 
@@ -72,8 +72,8 @@
     background: transparent;
 
     &--completed {
-      .room-pixel-avatar {
-        --room-pixel-avatar-bg: color-mix(
+      .room-avatar {
+        --room-avatar-bg: color-mix(
           in srgb,
           var(--success-color) 18%,
           var(--tag-bg)
@@ -82,8 +82,8 @@
     }
 
     &--failed {
-      .room-pixel-avatar {
-        --room-pixel-avatar-bg: color-mix(
+      .room-avatar {
+        --room-avatar-bg: color-mix(
           in srgb,
           var(--danger-color) 18%,
           var(--tag-bg)
@@ -92,8 +92,8 @@
     }
 
     &--idle {
-      .room-pixel-avatar {
-        --room-pixel-avatar-bg: color-mix(
+      .room-avatar {
+        --room-avatar-bg: color-mix(
           in srgb,
           var(--sub-text-color) 14%,
           var(--tag-bg)
@@ -103,12 +103,12 @@
   }
 
   &__avatar {
-    --room-pixel-avatar-size: var(--room-item-avatar-size);
+    --room-avatar-size: var(--room-item-avatar-size);
 
-    &.room-pixel-avatar {
-      // The element has both room-pixel-avatar and room-item__avatar classes.
-      // Keep this selector stronger than RoomPixelAvatar's own default radius.
-      --room-pixel-avatar-radius: var(--room-item-avatar-radius);
+    &.room-avatar {
+      // The element has both room-avatar and room-item__avatar classes.
+      // Keep this selector stronger than RoomAvatar's own default radius.
+      --room-avatar-radius: var(--room-item-avatar-radius);
 
       border-radius: var(--room-item-avatar-radius);
     }
diff --git a/apps/client/src/components/sidebar/RoomItem.tsx b/apps/client/src/components/sidebar/RoomItem.tsx
index 140cbb28a..9cf7703d2 100644
--- a/apps/client/src/components/sidebar/RoomItem.tsx
+++ b/apps/client/src/components/sidebar/RoomItem.tsx
@@ -4,7 +4,7 @@ import { List, Tooltip } from 'antd'
 import { useMemo } from 'react'
 import { useTranslation } from 'react-i18next'
 
-import { RoomPixelAvatar } from '#~/components/room-pixel-avatar/RoomPixelAvatar'
+import { RoomAvatar } from '#~/components/room-avatar/RoomAvatar'
 
 import { RoomContextMenu, isRoomFavorited } from './RoomContextMenu'
 import { RoomItemActions } from './RoomItemActions'
@@ -70,7 +70,7 @@ export function RoomItem({
     >
       <div className='room-item__content'>
         <div className={`room-item__leading room-item__leading--${room.status}`}>
-          <RoomPixelAvatar className='room-item__avatar' seed={room.id} />
+          <RoomAvatar className='room-item__avatar' seed={room.id} />
         </div>
         <div className='room-item__info'>
           <div className='room-item__header'>
diff --git a/assets/AGENTS.md b/assets/AGENTS.md
index 02244e3d3..190eb43f5 100644
--- a/assets/AGENTS.md
+++ b/assets/AGENTS.md
@@ -2,8 +2,8 @@
 
 `assets/` hosts standalone design asset projects that are useful to develop and preview independently from the main apps.
 
-- `avatar/`: preview/export page for the shared pixel-rect SVG avatar system in `packages/avatar`.
+- `avatar/`: editor, public 3D runtime packages, framework adapters, and export surface for OneWorks Avatar.
 
-Asset projects that also publish standalone sites should live in their own repository and be mounted here as submodules. Keep reusable runtime APIs in `packages/*`; asset repositories should own preview/export UX and GitHub Pages deployment only.
+Asset projects that also publish standalone sites should live in their own repository and be mounted here as submodules. Keep reusable runtime APIs in the owning repository's `packages/*`; asset repositories normally own preview/export UX and GitHub Pages deployment only, unless their public package ownership is explicitly approved and protected like `assets/avatar`.
 
-Do not add submodule asset sites such as `assets/avatar` to the root `pnpm-workspace.yaml`. They may have their own app dependencies and lockfile; including them in the root workspace makes unrelated Vercel / CI installs fail when the submodule package changes.
+`assets/avatar` and its public `packages/*` are intentional root workspace members because the main client consumes the same 3D runtime. Do not add other submodule asset sites to the root workspace without equivalent install, build, and clean-consumer coverage.
diff --git a/assets/avatar b/assets/avatar
index 684fa2ac4..0998f9d62 160000
--- a/assets/avatar
+++ b/assets/avatar
@@ -1 +1 @@
-Subproject commit 684fa2ac45d9e71c1b4556eb811ebc226668fb3a
+Subproject commit 0998f9d6266d71c757ab8956b8fba0b92c3226e2
diff --git a/changelog/1.0.0-rc.6/avatar.md b/changelog/1.0.0-rc.6/avatar.md
index a56791787..a4d288bf2 100644
--- a/changelog/1.0.0-rc.6/avatar.md
+++ b/changelog/1.0.0-rc.6/avatar.md
@@ -7,5 +7,7 @@
 - Added SVG and PNG downloads for the current 3D camera view, plus animated GIF export for selected animations.
 - Added transparent camera backgrounds with frame-aware SVG, PNG, and GIF output.
 - Added a 3D-aware Agent Skill and bilingual developer guidance for sharing editable sources and exported assets.
-- Added reusable 3D Avatar SDK surfaces for React, Vue, Vanilla JavaScript, and opt-in Web Components, including the complete editor and custom animation libraries.
+- Replaced the legacy 2D `@oneworks/avatar` package with the versioned 3D definition and animation runtime, including deterministic seeded definitions.
+- Added matching `1.0.0-rc.6` SDK surfaces for React, Vue, Vanilla JavaScript, and opt-in Web Components, including the complete editor and custom animation libraries.
+- Added configurable eye highlights and vector surface decals for blush, mouth marks, badges, and other pose-aware model details.
 - Avatar deployment now triggers when the app repository updates the Avatar submodule pointer.
diff --git a/dprint.json b/dprint.json
index 433785c81..047a783d6 100644
--- a/dprint.json
+++ b/dprint.json
@@ -40,6 +40,7 @@
     "assets/homepage/**",
     "assets/icon/**",
     "assets/pwa/**",
+    "assets/avatar/**",
     "assets/brand/**/*.svg",
     "packages/plugins/external-browser-driver/assets/*.svg"
   ],
diff --git a/packages/avatar/AGENTS.md b/packages/avatar/AGENTS.md
deleted file mode 100644
index bc35dcdcd..000000000
--- a/packages/avatar/AGENTS.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Avatar Package Guide
-
-`packages/avatar` owns the reusable OneWorks avatar renderer.
-
-- `src/avatar.ts`: pure SVG generator, pixel glyph definitions, palettes, presets, and low-level data URI helpers.
-- `src/seed.ts`: deterministic seed-to-avatar helpers for client UI.
-- `__tests__/`: renderer and seed behavior coverage.
-
-Avatar glyphs must remain SVG `rect` geometry. Do not replace the face characters with web fonts, canvas text, or raster images. Keep reusable runtime APIs here; the `assets/avatar` project is only the preview/export surface.
-
-Deployment:
-
-- `assets/avatar` is a submodule of `oneworks-ai/avatar`.
-- The Pages site is rebuilt when this package or the avatar asset app changes.
-- If glyphs, palettes, seed mapping, or exported renderer APIs change, run the package tests and the asset app build before updating the submodule pointer.
-
-Validation:
-
-- `pnpm -C packages/avatar build`
-- `pnpm -C packages/avatar test`
diff --git a/packages/avatar/README.md b/packages/avatar/README.md
deleted file mode 100644
index 97d6d054a..000000000
--- a/packages/avatar/README.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# @oneworks/avatar
-
-[English](README.md) | [简体中文](README.zh-Hans.md)
-
-`@oneworks/avatar` is the legacy OneWorks 2D pixel-emoticon SVG renderer. It provides deterministic, DOM-free SVG and data-URI helpers for application placeholders.
-
-It is not the OneWorks 3D Avatar runtime. For the 3D editor, editable share URLs, SVG/PNG/GIF export, and current integration boundaries, see [OneWorks Avatar](https://github.com/oneworks-ai/avatar#readme).
-
-## Install
-
-```bash
-pnpm add @oneworks/avatar
-```
-
-## React usage
-
-```tsx
-import { createSeededAvatarDataUri } from '@oneworks/avatar'
-import { useMemo } from 'react'
-
-export function AgentAvatar({ id, name }: { id: string; name: string }) {
-  const src = useMemo(() =>
-    createSeededAvatarDataUri({
-      seed: `agent:${id}`,
-      size: 128,
-      title: `${name} avatar`
-    }), [id, name])
-
-  return <img src={src} width={64} height={64} alt={`${name} avatar`} />
-}
-```
-
-## Node or server-side SVG
-
-The SVG helpers do not require a DOM:
-
-```ts
-import {
-  createAvatarSvg,
-  getAvatarPalette,
-  isSupportedAvatarEmoticon
-} from '@oneworks/avatar'
-import { writeFile } from 'node:fs/promises'
-
-const emoticon = '0w0'
-if (!isSupportedAvatarEmoticon(emoticon)) throw new Error('Unsupported avatar')
-
-await writeFile(
-  'avatar.svg',
-  createAvatarSvg({
-    emoticon,
-    palette: getAvatarPalette('signal'),
-    backgroundStyle: 'gradient',
-    showShadow: true,
-    size: 256,
-    title: 'Codex avatar'
-  }),
-  'utf8'
-)
-```
-
-## Exports
-
-- `@oneworks/avatar`: renderer, palettes, glyph parts, presets, and seed helpers.
-- `@oneworks/avatar/avatar`: low-level SVG renderer and pixel glyph data.
-- `@oneworks/avatar/seed`: deterministic seed-to-avatar helpers.
-
-Prefer the root import unless a narrow subpath is necessary. Do not deep-import `dist` files.
-
-## Stability notes
-
-- Seeded output is deterministic within a package version. If the preset set or ordering changes, the same seed may resolve differently in a later version. Pin the package version for long-lived identity, or persist the resolved emoticon and palette ID.
-- The package renders the legacy pixel avatar with a background. It does not provide transparent 3D output, PNG/GIF export, camera framing, entity parts, or animation.
-- Validate custom emoticons with `isSupportedAvatarEmoticon` before calling the renderer.
-
-## Maintenance
-
-- Edit glyph geometry, palettes, presets, and SVG output in `packages/avatar/src/avatar.ts`.
-- Edit deterministic seed mapping in `packages/avatar/src/seed.ts`.
-- Edit the 3D editor and browser export UI in the `assets/avatar` submodule.
diff --git a/packages/avatar/README.zh-Hans.md b/packages/avatar/README.zh-Hans.md
deleted file mode 100644
index 664569f6d..000000000
--- a/packages/avatar/README.zh-Hans.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# @oneworks/avatar
-
-[English](README.md) | [简体中文](README.zh-Hans.md)
-
-`@oneworks/avatar` 是 OneWorks 的 legacy 2D 像素表情 SVG renderer，为应用占位头像提供确定性的、无 DOM 依赖的 SVG 与 data URI helper。
-
-它不是 OneWorks 3D Avatar runtime。3D 编辑器、可编辑分享链接、SVG/PNG/GIF 导出和当前接入边界请参阅 [OneWorks Avatar](https://github.com/oneworks-ai/avatar/blob/main/README.zh-Hans.md)。
-
-## 安装
-
-```bash
-pnpm add @oneworks/avatar
-```
-
-## React 用法
-
-```tsx
-import { createSeededAvatarDataUri } from '@oneworks/avatar'
-import { useMemo } from 'react'
-
-export function AgentAvatar({ id, name }: { id: string; name: string }) {
-  const src = useMemo(() =>
-    createSeededAvatarDataUri({
-      seed: `agent:${id}`,
-      size: 128,
-      title: `${name} avatar`
-    }), [id, name])
-
-  return <img src={src} width={64} height={64} alt={`${name} avatar`} />
-}
-```
-
-## Node 或服务端 SVG
-
-SVG helper 不依赖 DOM：
-
-```ts
-import {
-  createAvatarSvg,
-  getAvatarPalette,
-  isSupportedAvatarEmoticon
-} from '@oneworks/avatar'
-import { writeFile } from 'node:fs/promises'
-
-const emoticon = '0w0'
-if (!isSupportedAvatarEmoticon(emoticon)) throw new Error('Unsupported avatar')
-
-await writeFile(
-  'avatar.svg',
-  createAvatarSvg({
-    emoticon,
-    palette: getAvatarPalette('signal'),
-    backgroundStyle: 'gradient',
-    showShadow: true,
-    size: 256,
-    title: 'Codex avatar'
-  }),
-  'utf8'
-)
-```
-
-## 导出入口
-
-- `@oneworks/avatar`：renderer、palette、glyph part、preset 和 seed helper。
-- `@oneworks/avatar/avatar`：底层 SVG renderer 和像素 glyph 数据。
-- `@oneworks/avatar/seed`：确定性的 seed-to-avatar helper。
-
-除非确实需要窄子路径，否则优先从包根导入；不要 deep import `dist` 文件。
-
-## 稳定性说明
-
-- Seed 输出在同一包版本内保持确定性。如果 preset 集合或顺序发生变化，同一 seed 在后续版本可能得到不同结果。长期身份应固定包版本，或持久化已经解析出的 emoticon 和 palette ID。
-- 本包渲染带背景的 legacy 像素头像，不提供透明 3D 输出、PNG/GIF 导出、相机相框、entity part 或动画。
-- 调用 renderer 前，使用 `isSupportedAvatarEmoticon` 校验自定义表情。
-
-## 维护入口
-
-- `packages/avatar/src/avatar.ts`：glyph geometry、palette、preset 和 SVG 输出。
-- `packages/avatar/src/seed.ts`：确定性 seed mapping。
-- `assets/avatar` submodule：3D 编辑器和浏览器导出 UI。
diff --git a/packages/avatar/__tests__/avatar.spec.ts b/packages/avatar/__tests__/avatar.spec.ts
deleted file mode 100644
index dd20d2024..000000000
--- a/packages/avatar/__tests__/avatar.spec.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import {
-  AVATAR_EYES,
-  createAvatarSvg,
-  createSeededAvatarDataUri,
-  getAvatarPalette,
-  resolveSeededAvatar
-} from '../src/index.js'
-
-const getGlyphBlockYValues = (svg: string, minX: number, maxX: number) => {
-  return [
-    ...new Set(
-      [...svg.matchAll(/<rect x="([0-9.]+)" y="([0-9.]+)" width="6" height="6" fill="#[0-9a-fA-F]{6}"\/>/g)]
-        .map(match => ({ x: Number(match[1]), y: Number(match[2]) }))
-        .filter(rect => rect.x >= minX && rect.x <= maxX)
-        .map(rect => rect.y)
-    )
-  ].sort((a, b) => a - b)
-}
-
-describe('@oneworks/avatar', () => {
-  it('exports the symbolic eye glyphs used by the picker', () => {
-    const eyeGlyphs = AVATAR_EYES.map(eye => eye.glyph)
-
-    expect(eyeGlyphs).toContain('P')
-    expect(eyeGlyphs).toContain('p')
-    expect(eyeGlyphs).toContain('=')
-    expect(eyeGlyphs).toContain('~')
-    expect(eyeGlyphs).toContain('*')
-  })
-
-  it('lowers only lower-case p and q descenders', () => {
-    const svg = createAvatarSvg({
-      emoticon: 'pwp',
-      palette: getAvatarPalette('black')
-    })
-
-    expect(getGlyphBlockYValues(svg, 5, 33)).toEqual([68, 75, 82, 89, 96])
-    expect(getGlyphBlockYValues(svg, 47, 75)).toEqual([54, 61, 68, 75, 82])
-    expect(getGlyphBlockYValues(svg, 89, 117)).toEqual([68, 75, 82, 89, 96])
-  })
-
-  it('resolves seeded avatars deterministically', () => {
-    const first = resolveSeededAvatar({ seed: 'agent-room:codex' })
-    const second = resolveSeededAvatar({ seed: 'agent-room:codex' })
-    const dataUri = createSeededAvatarDataUri({ seed: 'agent-room:codex', size: 128 })
-
-    expect(first).toEqual(second)
-    expect(dataUri).toContain('data:image/svg+xml;charset=utf-8,')
-  })
-})
diff --git a/packages/avatar/package.json b/packages/avatar/package.json
deleted file mode 100644
index 8e3b3d5ab..000000000
--- a/packages/avatar/package.json
+++ /dev/null
@@ -1,48 +0,0 @@
-{
-  "name": "@oneworks/avatar",
-  "type": "module",
-  "version": "1.0.0-rc.5",
-  "description": "OneWorks avatar pixel emoticon SVG renderer",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/oneworks-ai/app.git",
-    "directory": "packages/avatar"
-  },
-  "imports": {
-    "#~/*.js": {
-      "__oneworks__": {
-        "default": "./src/*.ts"
-      },
-      "default": "./dist/*.js"
-    }
-  },
-  "exports": {
-    ".": {
-      "__oneworks__": {
-        "default": "./src/index.ts"
-      },
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./avatar": {
-      "__oneworks__": {
-        "default": "./src/avatar.ts"
-      },
-      "types": "./dist/avatar.d.ts",
-      "default": "./dist/avatar.js"
-    },
-    "./seed": {
-      "__oneworks__": {
-        "default": "./src/seed.ts"
-      },
-      "types": "./dist/seed.d.ts",
-      "default": "./dist/seed.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "pnpm -C ../.. exec vitest run --workspace vitest.workspace.ts --project bundler packages/avatar/__tests__"
-  }
-}
diff --git a/packages/avatar/src/avatar.ts b/packages/avatar/src/avatar.ts
deleted file mode 100644
index e9da73a10..000000000
--- a/packages/avatar/src/avatar.ts
+++ /dev/null
@@ -1,963 +0,0 @@
-/* eslint-disable max-lines -- Avatar glyph geometry, palettes, presets, and SVG output share one renderer contract. */
-
-export interface AvatarPalette {
-  readonly id: string
-  readonly name: string
-  readonly background: string
-  readonly gradient: readonly [string, string]
-  readonly foreground: string
-  readonly shadow: string
-}
-
-export type AvatarBackgroundStyle = 'solid' | 'gradient'
-export type AvatarSlot = 'left' | 'mouth' | 'right'
-
-export interface AvatarPreset {
-  readonly id: string
-  readonly label: string
-  readonly emoticon: string
-  readonly paletteId: string
-}
-
-export interface AvatarPart {
-  readonly id: string
-  readonly label: string
-  readonly glyph: string
-}
-
-export interface AvatarGlyphMark {
-  readonly x: number
-  readonly y: number
-}
-
-export interface AvatarGlyphView {
-  readonly width: number
-  readonly height: number
-  readonly markSize: number
-  readonly marks: readonly AvatarGlyphMark[]
-}
-
-export interface CreateAvatarSvgOptions {
-  readonly emoticon: string
-  readonly palette: AvatarPalette
-  readonly backgroundStyle?: AvatarBackgroundStyle
-  readonly dimInactiveGlyphs?: boolean
-  readonly highlightSlot?: AvatarSlot | readonly AvatarSlot[]
-  readonly showShadow?: boolean
-  readonly size?: number
-  readonly title?: string
-}
-
-interface PixelGlyph {
-  readonly width: number
-  readonly rows: readonly string[]
-}
-
-interface AvatarGlyphRect {
-  readonly slot: AvatarSlot
-  readonly x: number
-  readonly y: number
-}
-
-const VIEW_SIZE = 128
-const GLYPH_HEIGHT = 7
-const CELL_SIZE = 7
-const MARK_SIZE = 6
-const CHAR_GAP = 1
-const LOWERCASE_DESCENDER_Y_OFFSET = CELL_SIZE * 2
-
-const GLYPHS: Record<string, PixelGlyph> = {
-  '0': {
-    width: 5,
-    rows: [
-      '01110',
-      '10001',
-      '10011',
-      '10101',
-      '11001',
-      '10001',
-      '01110'
-    ]
-  },
-  O: {
-    width: 5,
-    rows: [
-      '01110',
-      '10001',
-      '10001',
-      '10001',
-      '10001',
-      '10001',
-      '01110'
-    ]
-  },
-  o: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '01110',
-      '10001',
-      '10001',
-      '10001',
-      '01110'
-    ]
-  },
-  Q: {
-    width: 5,
-    rows: [
-      '01110',
-      '10001',
-      '10001',
-      '10001',
-      '10101',
-      '10010',
-      '01101'
-    ]
-  },
-  q: {
-    width: 5,
-    rows: [
-      '00000',
-      '01110',
-      '10001',
-      '10001',
-      '10011',
-      '01101',
-      '00001'
-    ]
-  },
-  P: {
-    width: 5,
-    rows: [
-      '11110',
-      '10001',
-      '10001',
-      '11110',
-      '10000',
-      '10000',
-      '10000'
-    ]
-  },
-  p: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '11110',
-      '10001',
-      '11110',
-      '10000',
-      '10000'
-    ]
-  },
-  U: {
-    width: 5,
-    rows: [
-      '10001',
-      '10001',
-      '10001',
-      '10001',
-      '10001',
-      '10001',
-      '01110'
-    ]
-  },
-  u: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '10001',
-      '10001',
-      '10001',
-      '10011',
-      '01101'
-    ]
-  },
-  V: {
-    width: 5,
-    rows: [
-      '10001',
-      '10001',
-      '10001',
-      '01010',
-      '01010',
-      '00100',
-      '00100'
-    ]
-  },
-  v: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '10001',
-      '10001',
-      '01010',
-      '01010',
-      '00100'
-    ]
-  },
-  W: {
-    width: 5,
-    rows: [
-      '10001',
-      '10001',
-      '10001',
-      '10101',
-      '10101',
-      '11111',
-      '01010'
-    ]
-  },
-  w: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '10001',
-      '10001',
-      '10101',
-      '11111',
-      '01010'
-    ]
-  },
-  X: {
-    width: 5,
-    rows: [
-      '10001',
-      '01010',
-      '00100',
-      '00100',
-      '00100',
-      '01010',
-      '10001'
-    ]
-  },
-  x: {
-    width: 5,
-    rows: [
-      '00000',
-      '10001',
-      '01010',
-      '00100',
-      '00100',
-      '01010',
-      '10001'
-    ]
-  },
-  A: {
-    width: 5,
-    rows: [
-      '01110',
-      '10001',
-      '10001',
-      '11111',
-      '10001',
-      '10001',
-      '10001'
-    ]
-  },
-  a: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '01110',
-      '00001',
-      '01111',
-      '10001',
-      '01111'
-    ]
-  },
-  M: {
-    width: 5,
-    rows: [
-      '10001',
-      '11011',
-      '10101',
-      '10101',
-      '10001',
-      '10001',
-      '10001'
-    ]
-  },
-  m: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '11011',
-      '10101',
-      '10101',
-      '10101',
-      '10101'
-    ]
-  },
-  N: {
-    width: 5,
-    rows: [
-      '10001',
-      '11001',
-      '10101',
-      '10011',
-      '10001',
-      '10001',
-      '10001'
-    ]
-  },
-  n: {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '11110',
-      '10001',
-      '10001',
-      '10001',
-      '10001'
-    ]
-  },
-  '.': {
-    width: 3,
-    rows: [
-      '000',
-      '000',
-      '000',
-      '000',
-      '000',
-      '010',
-      '010'
-    ]
-  },
-  '-': {
-    width: 3,
-    rows: [
-      '000',
-      '000',
-      '000',
-      '111',
-      '000',
-      '000',
-      '000'
-    ]
-  },
-  _: {
-    width: 3,
-    rows: [
-      '000',
-      '000',
-      '000',
-      '000',
-      '000',
-      '000',
-      '111'
-    ]
-  },
-  '^': {
-    width: 5,
-    rows: [
-      '00100',
-      '01010',
-      '10001',
-      '00000',
-      '00000',
-      '00000',
-      '00000'
-    ]
-  },
-  '~': {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '01001',
-      '10110',
-      '00000',
-      '00000',
-      '00000'
-    ]
-  },
-  '=': {
-    width: 5,
-    rows: [
-      '00000',
-      '00000',
-      '11111',
-      '00000',
-      '11111',
-      '00000',
-      '00000'
-    ]
-  },
-  '+': {
-    width: 5,
-    rows: [
-      '00000',
-      '00100',
-      '00100',
-      '11111',
-      '00100',
-      '00100',
-      '00000'
-    ]
-  },
-  '*': {
-    width: 5,
-    rows: [
-      '10101',
-      '01110',
-      '11111',
-      '01110',
-      '10101',
-      '00000',
-      '00000'
-    ]
-  },
-  '@': {
-    width: 5,
-    rows: [
-      '01110',
-      '10001',
-      '10111',
-      '10101',
-      '10111',
-      '10000',
-      '01110'
-    ]
-  }
-}
-
-export const AVATAR_PALETTES: readonly AvatarPalette[] = [
-  {
-    id: 'signal',
-    name: 'Signal',
-    background: '#d8340c',
-    gradient: ['#d8340c', '#f47b61'],
-    foreground: '#fff8ef',
-    shadow: '#5c1808'
-  },
-  {
-    id: 'mint',
-    name: 'Mint',
-    background: '#0f766e',
-    gradient: ['#0f766e', '#72c8a4'],
-    foreground: '#f2fff8',
-    shadow: '#063d38'
-  },
-  {
-    id: 'graphite',
-    name: 'Graphite',
-    background: '#202321',
-    gradient: ['#202321', '#4a504b'],
-    foreground: '#f7f7f2',
-    shadow: '#e23f12'
-  },
-  {
-    id: 'black',
-    name: 'Black',
-    background: '#000000',
-    gradient: ['#000000', '#111827'],
-    foreground: '#ffffff',
-    shadow: '#334155'
-  },
-  {
-    id: 'white',
-    name: 'White',
-    background: '#ffffff',
-    gradient: ['#ffffff', '#e5e7eb'],
-    foreground: '#000000',
-    shadow: '#9ca3af'
-  },
-  {
-    id: 'sky',
-    name: 'Sky',
-    background: '#d7ecff',
-    gradient: ['#d7ecff', '#91c9f4'],
-    foreground: '#17324d',
-    shadow: '#8ca8bd'
-  },
-  {
-    id: 'gold',
-    name: 'Gold',
-    background: '#f2bd4b',
-    gradient: ['#f2bd4b', '#ffe6a1'],
-    foreground: '#201b12',
-    shadow: '#a86a1a'
-  },
-  {
-    id: 'moss',
-    name: 'Moss',
-    background: '#c8d77a',
-    gradient: ['#c8d77a', '#789d59'],
-    foreground: '#253119',
-    shadow: '#6f7e34'
-  },
-  {
-    id: 'coral',
-    name: 'Coral',
-    background: '#f47b61',
-    gradient: ['#f47b61', '#ffc1a9'],
-    foreground: '#27120f',
-    shadow: '#b33e2e'
-  },
-  {
-    id: 'iris',
-    name: 'Iris',
-    background: '#6750a4',
-    gradient: ['#6750a4', '#a991df'],
-    foreground: '#fff9ff',
-    shadow: '#2f2257'
-  },
-  {
-    id: 'terminal',
-    name: 'Terminal',
-    background: '#0b1020',
-    gradient: ['#0b1020', '#00a36c'],
-    foreground: '#d8ffe8',
-    shadow: '#007a53'
-  },
-  {
-    id: 'bubblegum',
-    name: 'Bubblegum',
-    background: '#ffd6e7',
-    gradient: ['#ffd6e7', '#ff8ab3'],
-    foreground: '#321322',
-    shadow: '#c94f78'
-  },
-  {
-    id: 'lagoon',
-    name: 'Lagoon',
-    background: '#5eead4',
-    gradient: ['#5eead4', '#1d9bd1'],
-    foreground: '#042f2e',
-    shadow: '#0f766e'
-  },
-  {
-    id: 'berry',
-    name: 'Berry',
-    background: '#9d174d',
-    gradient: ['#9d174d', '#f472b6'],
-    foreground: '#fff1f8',
-    shadow: '#4a0b25'
-  },
-  {
-    id: 'solar',
-    name: 'Solar',
-    background: '#fff2a8',
-    gradient: ['#fff2a8', '#f59e0b'],
-    foreground: '#2f2200',
-    shadow: '#c77700'
-  },
-  {
-    id: 'porcelain',
-    name: 'Porcelain',
-    background: '#f8fafc',
-    gradient: ['#f8fafc', '#93c5fd'],
-    foreground: '#111827',
-    shadow: '#94a3b8'
-  },
-  {
-    id: 'ember',
-    name: 'Ember',
-    background: '#32130f',
-    gradient: ['#32130f', '#ef5a24'],
-    foreground: '#fff2de',
-    shadow: '#a83216'
-  },
-  {
-    id: 'acid',
-    name: 'Acid',
-    background: '#d8ff47',
-    gradient: ['#d8ff47', '#49d17d'],
-    foreground: '#13220a',
-    shadow: '#80a317'
-  },
-  {
-    id: 'midnight',
-    name: 'Midnight',
-    background: '#15162b',
-    gradient: ['#15162b', '#5b6ee1'],
-    foreground: '#f2f0ff',
-    shadow: '#4b4db8'
-  },
-  {
-    id: 'jade',
-    name: 'Jade',
-    background: '#d1fae5',
-    gradient: ['#d1fae5', '#34d399'],
-    foreground: '#064e3b',
-    shadow: '#34d399'
-  },
-  {
-    id: 'plum',
-    name: 'Plum',
-    background: '#3b0764',
-    gradient: ['#3b0764', '#a855f7'],
-    foreground: '#faf5ff',
-    shadow: '#7e22ce'
-  },
-  {
-    id: 'peach',
-    name: 'Peach',
-    background: '#ffe0c7',
-    gradient: ['#ffe0c7', '#fb923c'],
-    foreground: '#3a1c0b',
-    shadow: '#ea580c'
-  },
-  {
-    id: 'ocean',
-    name: 'Ocean',
-    background: '#075985',
-    gradient: ['#075985', '#38bdf8'],
-    foreground: '#ecfeff',
-    shadow: '#0c4a6e'
-  },
-  {
-    id: 'rosewood',
-    name: 'Rosewood',
-    background: '#4c0519',
-    gradient: ['#4c0519', '#e11d48'],
-    foreground: '#fff1f2',
-    shadow: '#be123c'
-  },
-  {
-    id: 'limepop',
-    name: 'Limepop',
-    background: '#ecfccb',
-    gradient: ['#ecfccb', '#84cc16'],
-    foreground: '#1a2e05',
-    shadow: '#65a30d'
-  },
-  {
-    id: 'denim',
-    name: 'Denim',
-    background: '#1e3a8a',
-    gradient: ['#1e3a8a', '#60a5fa'],
-    foreground: '#eff6ff',
-    shadow: '#1d4ed8'
-  },
-  {
-    id: 'orchid',
-    name: 'Orchid',
-    background: '#f5d0fe',
-    gradient: ['#f5d0fe', '#d946ef'],
-    foreground: '#3b0a45',
-    shadow: '#c026d3'
-  },
-  {
-    id: 'cocoa',
-    name: 'Cocoa',
-    background: '#2a1712',
-    gradient: ['#2a1712', '#a16207'],
-    foreground: '#fff7ed',
-    shadow: '#854d0e'
-  },
-  {
-    id: 'ice',
-    name: 'Ice',
-    background: '#e0f2fe',
-    gradient: ['#e0f2fe', '#7dd3fc'],
-    foreground: '#082f49',
-    shadow: '#38bdf8'
-  },
-  {
-    id: 'ink',
-    name: 'Ink',
-    background: '#020617',
-    gradient: ['#020617', '#64748b'],
-    foreground: '#f8fafc',
-    shadow: '#334155'
-  },
-  {
-    id: 'clay',
-    name: 'Clay',
-    background: '#fca5a5',
-    gradient: ['#fca5a5', '#dc2626'],
-    foreground: '#2f0f0f',
-    shadow: '#b91c1c'
-  },
-  {
-    id: 'lilac',
-    name: 'Lilac',
-    background: '#ede9fe',
-    gradient: ['#ede9fe', '#8b5cf6'],
-    foreground: '#2e1065',
-    shadow: '#7c3aed'
-  },
-  {
-    id: 'pine',
-    name: 'Pine',
-    background: '#064e3b',
-    gradient: ['#064e3b', '#10b981'],
-    foreground: '#ecfdf5',
-    shadow: '#047857'
-  },
-  {
-    id: 'banana',
-    name: 'Banana',
-    background: '#fef08a',
-    gradient: ['#fef08a', '#facc15'],
-    foreground: '#29210c',
-    shadow: '#ca8a04'
-  }
-]
-
-export const AVATAR_EYES: readonly AvatarPart[] = [
-  { id: 'zero', label: '0', glyph: '0' },
-  { id: 'open-upper', label: 'O', glyph: 'O' },
-  { id: 'open-lower', label: 'o', glyph: 'o' },
-  { id: 'tear-upper', label: 'Q', glyph: 'Q' },
-  { id: 'tear-lower', label: 'q', glyph: 'q' },
-  { id: 'p-upper', label: 'P', glyph: 'P' },
-  { id: 'p-lower', label: 'p', glyph: 'p' },
-  { id: 'soft-upper', label: 'U', glyph: 'U' },
-  { id: 'soft-lower', label: 'u', glyph: 'u' },
-  { id: 'sharp-upper', label: 'V', glyph: 'V' },
-  { id: 'sharp-lower', label: 'v', glyph: 'v' },
-  { id: 'cross-upper', label: 'X', glyph: 'X' },
-  { id: 'cross-lower', label: 'x', glyph: 'x' },
-  { id: 'caret', label: '^', glyph: '^' },
-  { id: 'wave', label: '~', glyph: '~' },
-  { id: 'equal', label: '=', glyph: '=' },
-  { id: 'star', label: '*', glyph: '*' },
-  { id: 'at', label: '@', glyph: '@' },
-  { id: 'dash', label: '-', glyph: '-' },
-  { id: 'under', label: '_', glyph: '_' }
-]
-
-export const AVATAR_MOUTHS: readonly AvatarPart[] = [
-  { id: 'wow-lower', label: 'w', glyph: 'w' },
-  { id: 'wow-upper', label: 'W', glyph: 'W' },
-  { id: 'v-lower', label: 'v', glyph: 'v' },
-  { id: 'v-upper', label: 'V', glyph: 'V' },
-  { id: 'u-lower', label: 'u', glyph: 'u' },
-  { id: 'u-upper', label: 'U', glyph: 'U' },
-  { id: 'x-lower', label: 'x', glyph: 'x' },
-  { id: 'x-upper', label: 'X', glyph: 'X' },
-  { id: 'tear-lower', label: 'q', glyph: 'q' },
-  { id: 'tear-upper', label: 'Q', glyph: 'Q' },
-  { id: 'a-lower', label: 'a', glyph: 'a' },
-  { id: 'a-upper', label: 'A', glyph: 'A' },
-  { id: 'm-lower', label: 'm', glyph: 'm' },
-  { id: 'm-upper', label: 'M', glyph: 'M' },
-  { id: 'n-lower', label: 'n', glyph: 'n' },
-  { id: 'n-upper', label: 'N', glyph: 'N' },
-  { id: 'dot', label: '.', glyph: '.' },
-  { id: 'dash', label: '-', glyph: '-' },
-  { id: 'under', label: '_', glyph: '_' },
-  { id: 'caret', label: '^', glyph: '^' },
-  { id: 'wave', label: '~', glyph: '~' },
-  { id: 'equal', label: '=', glyph: '=' },
-  { id: 'plus', label: '+', glyph: '+' },
-  { id: 'star', label: '*', glyph: '*' }
-]
-
-export const AVATAR_PRESETS: readonly AvatarPreset[] = [
-  { id: 'zero-w', label: '0w0', emoticon: '0w0', paletteId: 'signal' },
-  { id: 'big-wow', label: 'OWO', emoticon: 'OWO', paletteId: 'graphite' },
-  { id: 'soft-v', label: 'Ovo', emoticon: 'Ovo', paletteId: 'sky' },
-  { id: 'tear-wow', label: 'qwq', emoticon: 'qwq', paletteId: 'mint' },
-  { id: 'small-wow', label: 'owo', emoticon: 'owo', paletteId: 'mint' },
-  { id: 'mixed-wow', label: 'OwO', emoticon: 'OwO', paletteId: 'gold' },
-  { id: 'soft-u', label: 'UwU', emoticon: 'UwU', paletteId: 'moss' },
-  { id: 'tear-v', label: 'qvq', emoticon: 'qvq', paletteId: 'coral' },
-  { id: 'sharp-v', label: 'UvU', emoticon: 'UvU', paletteId: 'coral' },
-  { id: 'small-v', label: 'oVo', emoticon: 'oVo', paletteId: 'iris' },
-  { id: 'zero-v', label: '0v0', emoticon: '0v0', paletteId: 'mint' },
-  { id: 'tear-o', label: 'qOq', emoticon: 'qOq', paletteId: 'sky' },
-  { id: 'soft-x', label: 'OxO', emoticon: 'OxO', paletteId: 'signal' },
-  { id: 'tiny-u', label: 'uvu', emoticon: 'uvu', paletteId: 'gold' },
-  { id: 'zero-wow', label: '0W0', emoticon: '0W0', paletteId: 'graphite' },
-  { id: 'tear-zero', label: 'q0q', emoticon: 'q0q', paletteId: 'iris' },
-  { id: 'soft-tear', label: 'quq', emoticon: 'quq', paletteId: 'moss' },
-  { id: 'tear-x', label: 'qxq', emoticon: 'qxq', paletteId: 'graphite' },
-  { id: 'zero-tear', label: '0q0', emoticon: '0q0', paletteId: 'signal' },
-  { id: 'open-tear', label: 'OqO', emoticon: 'OqO', paletteId: 'gold' },
-  { id: 'small-tear', label: 'oqo', emoticon: 'oqo', paletteId: 'sky' },
-  { id: 'u-tear', label: 'UqU', emoticon: 'UqU', paletteId: 'coral' },
-  { id: 'v-tear', label: 'vqv', emoticon: 'vqv', paletteId: 'mint' },
-  { id: 'w-tear', label: 'wqw', emoticon: 'wqw', paletteId: 'moss' },
-  { id: 'big-tear', label: 'qWq', emoticon: 'qWq', paletteId: 'iris' },
-  { id: 'zero-open', label: '0O0', emoticon: '0O0', paletteId: 'graphite' },
-  { id: 'dash-open', label: 'O-O', emoticon: 'O-O', paletteId: 'sky' },
-  { id: 'small-under', label: 'o_o', emoticon: 'o_o', paletteId: 'mint' },
-  { id: 'zero-dot', label: '0.0', emoticon: '0.0', paletteId: 'signal' },
-  { id: 'tear-caret', label: 'q^q', emoticon: 'q^q', paletteId: 'iris' },
-  { id: 'open-equal', label: 'O=O', emoticon: 'O=O', paletteId: 'graphite' },
-  { id: 'open-plus', label: 'O+O', emoticon: 'O+O', paletteId: 'gold' },
-  { id: 'star-wow', label: '*w*', emoticon: '*w*', paletteId: 'coral' },
-  { id: 'at-wow', label: '@w@', emoticon: '@w@', paletteId: 'moss' },
-  { id: 'caret-wow', label: '^w^', emoticon: '^w^', paletteId: 'signal' },
-  { id: 'zero-n', label: '0n0', emoticon: '0n0', paletteId: 'sky' },
-  { id: 'open-m', label: 'OmO', emoticon: 'OmO', paletteId: 'coral' },
-  { id: 'soft-a', label: 'oao', emoticon: 'oao', paletteId: 'moss' },
-  { id: 'tear-a', label: 'qaq', emoticon: 'qaq', paletteId: 'mint' },
-  { id: 'open-n', label: 'OnO', emoticon: 'OnO', paletteId: 'iris' },
-  { id: 'upper-m', label: 'OMO', emoticon: 'OMO', paletteId: 'gold' },
-  { id: 'tear-dash', label: 'q-q', emoticon: 'q-q', paletteId: 'graphite' },
-  { id: 'tear-under', label: 'q_q', emoticon: 'q_q', paletteId: 'signal' },
-  { id: 'soft-caret', label: 'o^o', emoticon: 'o^o', paletteId: 'sky' },
-  { id: 'soft-wave', label: 'O~O', emoticon: 'O~O', paletteId: 'mint' },
-  { id: 'zero-plus', label: '0+0', emoticon: '0+0', paletteId: 'coral' }
-]
-
-const escapeXml = (value: string) =>
-  value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-
-const safeIdPart = (value: string) => value.replaceAll(/[^\w-]/g, '-')
-
-const resolveGlyphs = (emoticon: string) => {
-  const chars = Array.from(emoticon.trim())
-  if (chars.length !== 3) {
-    throw new Error('Avatar emoticons must contain exactly 3 characters.')
-  }
-
-  return chars.map((char) => {
-    const glyph = GLYPHS[char]
-    if (glyph == null) {
-      throw new Error(`Unsupported avatar glyph: ${char}`)
-    }
-    return { char, glyph }
-  })
-}
-
-const AVATAR_SLOTS: readonly AvatarSlot[] = ['left', 'mouth', 'right']
-
-const getGlyphYOffset = (char: string) => char === 'p' || char === 'q' ? LOWERCASE_DESCENDER_Y_OFFSET : 0
-
-const glyphRects = (emoticon: string) => {
-  const glyphs = resolveGlyphs(emoticon)
-  const totalColumns = glyphs.reduce((sum, item, index) => {
-    return sum + item.glyph.width + (index === 0 ? 0 : CHAR_GAP)
-  }, 0)
-  const width = totalColumns * CELL_SIZE - (CELL_SIZE - MARK_SIZE)
-  const height = GLYPH_HEIGHT * CELL_SIZE - (CELL_SIZE - MARK_SIZE)
-  const startX = (VIEW_SIZE - width) / 2
-  const startY = (VIEW_SIZE - height) / 2
-  const rects: AvatarGlyphRect[] = []
-
-  let cursor = 0
-  for (let glyphIndex = 0; glyphIndex < glyphs.length; glyphIndex += 1) {
-    const item = glyphs[glyphIndex]
-    const slot = AVATAR_SLOTS[glyphIndex] ?? 'mouth'
-    for (let rowIndex = 0; rowIndex < item.glyph.rows.length; rowIndex += 1) {
-      const row = item.glyph.rows[rowIndex] ?? ''
-      for (let columnIndex = 0; columnIndex < item.glyph.width; columnIndex += 1) {
-        if (row[columnIndex] !== '1') continue
-        rects.push({
-          slot,
-          x: startX + (cursor + columnIndex) * CELL_SIZE,
-          y: startY + rowIndex * CELL_SIZE + getGlyphYOffset(item.char)
-        })
-      }
-    }
-    cursor += item.glyph.width + CHAR_GAP
-  }
-
-  return rects
-}
-
-export const createAvatarGlyphView = (glyph: string): AvatarGlyphView => {
-  const pixelGlyph = GLYPHS[glyph]
-  if (pixelGlyph == null) {
-    throw new Error(`Unsupported avatar glyph: ${glyph}`)
-  }
-
-  const marks: AvatarGlyphMark[] = []
-  for (let rowIndex = 0; rowIndex < pixelGlyph.rows.length; rowIndex += 1) {
-    const row = pixelGlyph.rows[rowIndex] ?? ''
-    for (let columnIndex = 0; columnIndex < pixelGlyph.width; columnIndex += 1) {
-      if (row[columnIndex] !== '1') continue
-      marks.push({
-        x: columnIndex * CELL_SIZE,
-        y: rowIndex * CELL_SIZE + getGlyphYOffset(glyph)
-      })
-    }
-  }
-
-  return {
-    width: pixelGlyph.width * CELL_SIZE - (CELL_SIZE - MARK_SIZE),
-    height: GLYPH_HEIGHT * CELL_SIZE - (CELL_SIZE - MARK_SIZE) + getGlyphYOffset(glyph),
-    markSize: MARK_SIZE,
-    marks
-  }
-}
-
-export const getAvatarPalette = (paletteId: string) =>
-  AVATAR_PALETTES.find(palette => palette.id === paletteId) ?? AVATAR_PALETTES[0]
-
-export const createAvatarSvg = ({
-  backgroundStyle = 'solid',
-  dimInactiveGlyphs = false,
-  emoticon,
-  highlightSlot,
-  palette,
-  showShadow = false,
-  size = 512,
-  title = `${emoticon} avatar`
-}: CreateAvatarSvgOptions) => {
-  const rects = glyphRects(emoticon)
-  const titleText = escapeXml(title)
-  const background = escapeXml(palette.background)
-  const gradientFrom = escapeXml(palette.gradient[0])
-  const gradientTo = escapeXml(palette.gradient[1])
-  const foreground = escapeXml(palette.foreground)
-  const shadow = escapeXml(palette.shadow)
-  const gradientId = `avatar-${safeIdPart(palette.id)}-${safeIdPart(emoticon)}-gradient`
-  const backgroundFill = backgroundStyle === 'gradient' ? `url(#${gradientId})` : background
-  const highlightSlots = highlightSlot == null ? [] : Array.isArray(highlightSlot) ? highlightSlot : [highlightSlot]
-  const shadowRects = showShadow
-    ? rects.map(({ x, y }) => {
-      return `<rect x="${x + 2}" y="${
-        y + 2
-      }" width="${MARK_SIZE}" height="${MARK_SIZE}" fill="${shadow}" opacity="0.34"/>`
-    })
-    : []
-  const foregroundRects = rects.map(({ slot, x, y }) => {
-    const opacity = dimInactiveGlyphs && highlightSlots.length > 0 && !highlightSlots.includes(slot)
-      ? ' opacity="0.42"'
-      : ''
-    return `<rect x="${x}" y="${y}" width="${MARK_SIZE}" height="${MARK_SIZE}" fill="${foreground}"${opacity}/>`
-  })
-
-  return [
-    '<?xml version="1.0" encoding="UTF-8"?>',
-    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${VIEW_SIZE} ${VIEW_SIZE}" width="${size}" height="${size}" role="img" aria-label="${titleText}" shape-rendering="crispEdges">`,
-    `  <title>${titleText}</title>`,
-    ...(backgroundStyle === 'gradient'
-      ? [
-        '  <defs>',
-        `    <linearGradient id="${gradientId}" x1="0" y1="0" x2="1" y2="1">`,
-        `      <stop offset="0%" stop-color="${gradientFrom}"/>`,
-        `      <stop offset="100%" stop-color="${gradientTo}"/>`,
-        '    </linearGradient>',
-        '  </defs>'
-      ]
-      : []),
-    `  <rect x="0" y="0" width="${VIEW_SIZE}" height="${VIEW_SIZE}" fill="${backgroundFill}"/>`,
-    ...(showShadow ? ['  <g>', ...shadowRects.map(rect => `    ${rect}`), '  </g>'] : []),
-    '  <g>',
-    ...foregroundRects.map(rect => `    ${rect}`),
-    '  </g>',
-    '</svg>',
-    ''
-  ].join('\n')
-}
-
-export const createAvatarDataUri = (options: CreateAvatarSvgOptions) =>
-  `data:image/svg+xml;charset=utf-8,${encodeURIComponent(createAvatarSvg(options))}`
-
-export const isSupportedAvatarEmoticon = (emoticon: string) => {
-  try {
-    resolveGlyphs(emoticon)
-    return true
-  } catch {
-    return false
-  }
-}
diff --git a/packages/avatar/src/index.ts b/packages/avatar/src/index.ts
deleted file mode 100644
index add6f21b4..000000000
--- a/packages/avatar/src/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export * from './avatar.js'
-export * from './seed.js'
diff --git a/packages/avatar/src/seed.ts b/packages/avatar/src/seed.ts
deleted file mode 100644
index 4a531e75c..000000000
--- a/packages/avatar/src/seed.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { AVATAR_PALETTES, AVATAR_PRESETS, createAvatarDataUri, createAvatarSvg, getAvatarPalette } from './avatar.js'
-import type { AvatarBackgroundStyle, AvatarPalette, CreateAvatarSvgOptions } from './avatar.js'
-
-export interface SeededAvatarConfig {
-  readonly backgroundStyle: AvatarBackgroundStyle
-  readonly emoticon: string
-  readonly palette: AvatarPalette
-  readonly showShadow: boolean
-}
-
-export interface ResolveSeededAvatarOptions {
-  readonly backgroundStyle?: AvatarBackgroundStyle
-  readonly emoticon?: string
-  readonly paletteId?: string
-  readonly seed: string
-  readonly showShadow?: boolean
-}
-
-export interface CreateSeededAvatarOptions extends ResolveSeededAvatarOptions {
-  readonly size?: number
-  readonly title?: string
-}
-
-export const hashAvatarSeed = (seed: string) => {
-  let hash = 2166136261
-  for (let index = 0; index < seed.length; index += 1) {
-    hash ^= seed.charCodeAt(index)
-    hash = Math.imul(hash, 16777619)
-  }
-  return hash >>> 0
-}
-
-export const resolveSeededAvatar = ({
-  backgroundStyle = 'solid',
-  emoticon,
-  paletteId,
-  seed,
-  showShadow = false
-}: ResolveSeededAvatarOptions): SeededAvatarConfig => {
-  const hash = hashAvatarSeed(seed)
-  const preset = AVATAR_PRESETS[hash % AVATAR_PRESETS.length] ?? AVATAR_PRESETS[0]
-  const resolvedEmoticon = emoticon ?? preset?.emoticon ?? '0w0'
-  const resolvedPaletteId = paletteId ?? preset?.paletteId ?? AVATAR_PALETTES[hash % AVATAR_PALETTES.length]?.id
-
-  return {
-    backgroundStyle,
-    emoticon: resolvedEmoticon,
-    palette: getAvatarPalette(resolvedPaletteId ?? AVATAR_PALETTES[0]?.id ?? ''),
-    showShadow
-  }
-}
-
-const resolveSeededSvgOptions = (options: CreateSeededAvatarOptions): CreateAvatarSvgOptions => {
-  const avatar = resolveSeededAvatar(options)
-
-  return {
-    backgroundStyle: avatar.backgroundStyle,
-    emoticon: avatar.emoticon,
-    palette: avatar.palette,
-    showShadow: avatar.showShadow,
-    size: options.size,
-    title: options.title ?? `OneWorks ${avatar.emoticon} avatar`
-  }
-}
-
-export const createSeededAvatarSvg = (options: CreateSeededAvatarOptions) => {
-  return createAvatarSvg(resolveSeededSvgOptions(options))
-}
-
-export const createSeededAvatarDataUri = (options: CreateSeededAvatarOptions) => {
-  return createAvatarDataUri(resolveSeededSvgOptions(options))
-}
diff --git a/packages/avatar/tsconfig.build.json b/packages/avatar/tsconfig.build.json
deleted file mode 100644
index e62bdbdfc..000000000
--- a/packages/avatar/tsconfig.build.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-  "extends": "../tsconfigs/tsconfig.bundler.json",
-  "compilerOptions": {
-    "composite": false,
-    "rootDir": "src",
-    "declaration": true,
-    "declarationMap": false,
-    "emitDeclarationOnly": false,
-    "noEmit": false,
-    "outDir": "dist",
-    "sourceMap": false
-  },
-  "include": [
-    "src/**/*"
-  ]
-}
diff --git a/packages/avatar/tsconfig.json b/packages/avatar/tsconfig.json
deleted file mode 100644
index 2c47791ad..000000000
--- a/packages/avatar/tsconfig.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "extends": "../tsconfigs/tsconfig.bundler.json",
-  "compilerOptions": {
-    "composite": false,
-    "noEmit": true
-  },
-  "include": [
-    "src/**/*",
-    "__tests__/**/*"
-  ]
-}
diff --git a/packages/channels/lark/AGENTS.md b/packages/channels/lark/AGENTS.md
index ed16ffe20..66afad9ce 100644
--- a/packages/channels/lark/AGENTS.md
+++ b/packages/channels/lark/AGENTS.md
@@ -28,7 +28,7 @@ This package implements the `lark` channel for Feishu / Lark bot apps.
 - Resolve the current bot `open_id` from `/open-apis/bot/v3/info` before registering the event dispatcher. Group ingress must use the structured mention target and fail closed when a message mentions a different bot; rendered `<at>` text alone is not enough in multi-bot chats.
 - External group support is a published-version setting in the Feishu Open Platform. Saving a draft is not enough; the version must be released and approved before the bot can be added to external groups.
 - Permission, event-subscription, icon, name, and external-group setting changes are effective only after the relevant published version is live.
-- Avatar URLs for OneWorks pixel avatars should come from generated image files. `https://oneworks.cloud/avatar/` is a preview/export UI, not a direct image endpoint.
+- Avatar image URLs should come from exported SVG, PNG, or GIF files. `https://oneworks.cloud/avatar/` is an editor/export UI, not a direct image endpoint; applications that render definitions directly should use the public 3D runtime packages.
 - `open_id` values are app-scoped. Re-resolve admin and external member IDs after switching the channel app or CLI profile.
 - A bot profile reporting `ready` only proves that local credentials exist. Exercise a real bot API before trusting the secret; synchronize a known-good secret through `lark-cli config init --app-secret-stdin` rather than exposing it in argv.
 - When the channel bot lacks member-read scope, capture a known real inbound message to recover that app's sender `open_id`; never copy an admin `open_id` from the CLI app profile.
diff --git a/packages/channels/lark/debugging/lessons.md b/packages/channels/lark/debugging/lessons.md
index 6c09a2eed..a98a3f5dc 100644
--- a/packages/channels/lark/debugging/lessons.md
+++ b/packages/channels/lark/debugging/lessons.md
@@ -18,7 +18,7 @@
 - 调试权限问题时，要同时看 adapter 启动参数和 settings 文件；只看到 `defaultMode = bypassPermissions` 还不够，headless 模式下往往还需要真实 CLI flag 才能生效。
 - MCP 工具拿 server API 结果时，要确认解包的是统一 envelope 里的真实结果，不能把 `success/data/result` 外层对象直接当最终答案。
 - 开放平台应用基础信息、头像或名称修改后还要提交发布并过审。`application/v7/applications/:app_id/base` 只改草稿；头像要先用 `application/v7/app_avatar/upload` 上传图片拿 `avatar_url`，再 patch 到应用基础信息，最后调用 publish 或在页面发布。
-- OneWorks 头像页是预览 / 导出 UI，不是图片直链。外部平台要上传头像时，先用 `packages/avatar` 生成 SVG，再渲染成 PNG/JPEG；不要把 `https://oneworks.cloud/avatar/` 页面 URL 当图片 URL。
+- OneWorks 头像页是编辑 / 导出 UI，不是图片直链。外部平台要上传头像时，从编辑器导出 SVG 或 PNG 后再上传；不要把 `https://oneworks.cloud/avatar/` 页面 URL 当图片 URL。
 - 飞书开放平台详情页是 SPA，直达 `/app/<app_id>/baseinfo` 或用自动化打开时可能先出现几秒空白 / 黑底。不要立刻判断为打不开；至少等到页面标题和主内容 DOM 都稳定，或重新抓一次 Computer Use 状态后再下结论。若标题已变成目标应用但内容区暂空，优先等待 / 重读状态，不要让用户接手验证。
 - 用户明确要求 `@chrome` 或任务依赖已登录 Chrome 状态时，优先用 Codex Chrome 插件，不要默认退到 CUA、AppleScript 或 CLI。只有 Chrome 插件明确失败并已向用户说明后，才考虑 fallback。
 - Chrome 插件出现 `native pipe is closed` 时，先按插件排障流程做轻量重试和只读检查：确认 Chrome 正在运行、Codex Chrome Extension 已安装启用、native host manifest 正常。若检查都通过，经用户同意后用同 profile 打开一个新 Chrome 窗口再重连；不要直接改 manifest、安装扩展或绕到系统脚本。
diff --git a/packages/plugins/channel-oneworks/package.json b/packages/plugins/channel-oneworks/package.json
index 75f21790b..77b0f94fd 100644
--- a/packages/plugins/channel-oneworks/package.json
+++ b/packages/plugins/channel-oneworks/package.json
@@ -35,7 +35,6 @@
     "typecheck": "tsc -p server/tsconfig.json --noEmit && tsc -p client/tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@oneworks/avatar": "workspace:*",
     "@oneworks/types": "workspace:*"
   },
   "devDependencies": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f8429262d..a187bb102 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -266,7 +266,10 @@ importers:
     dependencies:
       '@oneworks/avatar':
         specifier: workspace:*
-        version: link:../../packages/avatar
+        version: link:../../assets/avatar/packages/avatar
+      '@oneworks/avatar-react':
+        specifier: workspace:*
+        version: link:../../assets/avatar/packages/react
       '@oneworks/components':
         specifier: workspace:*
         version: link:../../packages/components
@@ -888,11 +891,8 @@ importers:
   assets/avatar:
     dependencies:
       '@oneworks/avatar':
-        specifier: beta
-        version: 0.1.0-beta.10
-      '@oneworks/avatar-core':
-        specifier: link:packages/core
-        version: link:packages/core
+        specifier: link:packages/avatar
+        version: link:packages/avatar
       '@oneworks/route-layout':
         specifier: beta
         version: 0.1.0-beta.10(react@18.3.1)
@@ -943,6 +943,47 @@ importers:
         specifier: ^2.2.12
         version: 2.2.12(typescript@5.9.3)
 
+  assets/avatar/packages/avatar: {}
+
+  assets/avatar/packages/react:
+    dependencies:
+      '@oneworks/avatar':
+        specifier: workspace:*
+        version: link:../avatar
+      react:
+        specifier: '>=18.3.0 <20'
+        version: 18.3.1
+      react-dom:
+        specifier: '>=18.3.0 <20'
+        version: 18.3.1(react@18.3.1)
+
+  assets/avatar/packages/vue:
+    dependencies:
+      '@oneworks/avatar':
+        specifier: workspace:*
+        version: link:../avatar
+      '@oneworks/avatar-web':
+        specifier: workspace:*
+        version: link:../web
+      vue:
+        specifier: '>=3.5.0 <4'
+        version: 3.5.41(typescript@5.9.3)
+
+  assets/avatar/packages/web:
+    dependencies:
+      '@oneworks/avatar':
+        specifier: workspace:*
+        version: link:../avatar
+      '@oneworks/avatar-react':
+        specifier: workspace:*
+        version: link:../react
+      react:
+        specifier: ^18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
+
   packages/adapters/claude-code:
     dependencies:
       '@oneworks/config':
@@ -1299,8 +1340,6 @@ importers:
         specifier: workspace:*
         version: link:../task
 
-  packages/avatar: {}
-
   packages/benchmark:
     dependencies:
       '@oneworks/task':
@@ -1575,9 +1614,6 @@ importers:
 
   packages/plugins/channel-oneworks:
     dependencies:
-      '@oneworks/avatar':
-        specifier: workspace:*
-        version: link:../../avatar
       '@oneworks/types':
         specifier: workspace:*
         version: link:../../types
@@ -3121,9 +3157,6 @@ packages:
     resolution: {integrity: sha512-mGUWr1uMnf0le2TwfOZY4SFxZGXGfm4Jtay/nwAa2FLNAKXUoUwaGwBMNH36UHPtinWfTSJ3nqFQr0091CxVGg==}
     engines: {node: ^20.17.0 || >=22.9.0}
 
-  '@oneworks/avatar@0.1.0-beta.10':
-    resolution: {integrity: sha512-ceWQG2HRG9/sUEBEJAbpcXgQOks5bveI+OOXnLjH7Hm/S3coagpZsjdt9dd3FTyvN9o0woAkl+IjbLUga6vP2Q==}
-
   '@oneworks/icon@0.1.0-beta.10':
     resolution: {integrity: sha512-1sE+Enefrv1kyg8rwOyDs2cQCsPMbU469NXKYxCi1r36wk7FEw8iTi0rMjcH2bhPqa0NKm355OVG/zKwegZzqg==}
 
@@ -10648,8 +10681,6 @@ snapshots:
       node-gyp: 12.4.0
       proc-log: 6.1.0
 
-  '@oneworks/avatar@0.1.0-beta.10': {}
-
   '@oneworks/icon@0.1.0-beta.10':
     dependencies:
       '@paper-design/shaders': 0.0.76
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 9a016bd3b..ccc05798e 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,5 +1,6 @@
 packages:
   - assets/avatar
+  - assets/avatar/packages/*
   - apps/*
   - packages/adapters/*
   - packages/channels/*
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
index 8395aec21..4da051750 100644
--- a/scripts/AGENTS.md
+++ b/scripts/AGENTS.md
@@ -6,7 +6,7 @@
 
 不要再往 `package.json` 新增一串独立脚本名。新增维护命令时，优先给 `scripts/cli.ts` 增加子命令，再在文档里写 `pnpm tools ...` 的调用方式。依赖型质量检查是冷 worktree 的例外：`scripts/run-workspace-check.mjs` 必须在加载任何 workspace 依赖前调用共享的 `workspace-dependency-bootstrap.mjs`，让并行检查串行准备依赖、随后各自执行真实命令并透传退出码；dprint 统一使用 `pnpm dprint check` / `pnpm dprint fmt`，桌面 package preflight 使用 `pnpm -C apps/desktop test:package-preflight`，不要改回直接并行的 `pnpm exec dprint` / `pnpm exec vitest`。
 
-仓库长期开发服务也走同一个 CLI：当用户要求拉取最新代码并启动 web / daemon / Electron / PWA / homepage / docs / Relay / desktop-control / Android emulator 时，直接在仓库根目录运行 `pnpm --silent tools dev-service ensure <target> --json`。`scripts/run-tools.mjs` 会注册 TS，缺少 register 依赖时先执行 `pnpm install`；统一入口会按需校验 workspace 安装，并在操作租约内复用或启动对应服务。
+仓库长期开发服务也走同一个 CLI：当用户要求拉取最新代码并启动 web / daemon / Electron / PWA / homepage / docs / Relay / desktop-control / Android emulator 时，直接在仓库根目录运行 `pnpm --silent tools dev-service ensure <target> --json`。`scripts/run-tools.mjs` 会先精确初始化 workspace 必需的 `assets/avatar` 与 `assets/demo-video` submodule，再注册 TS；缺少 register 依赖时执行 `pnpm install`。dev-start 在 fetch / pull 后还会把 `assets/avatar` 对齐到当前 gitlink，再校验 workspace 安装，并在操作租约内复用或启动对应服务。
 
 跨会话状态文件通常位于仓库根目录 `.logs/dev-start-<target>.json`，操作事件位于 `.logs/dev-start-<target>.events.jsonl`；机器级 `android-emulator`、`electron` 和 `electron-workspace` 改用 status 返回的用户目录 `.oneworks/dev-service/` 路径。需要回答“当前 worktree 已启动哪个服务、URL / PID / 端口是多少、是否有 agent 正在修改”时，运行 `pnpm --silent tools dev-service status <target> --json`，不要为了查询状态手动再启动 server/client。多步骤生命周期操作统一使用 `pnpm --silent tools dev-service ensure / status / events / logs / stop / restart ... --json`；同 target 或 resource group 由 operation lease 串行化，`stop` / `restart` 无论健康与否都必须先有用户对该 target 的显式授权。失败证据只通过 target-scoped、有限行且已脱敏的 `logs` 返回。协议与按需自定义运维 agent 见 `.oo/rules/maintenance/dev-service-coordination.md` 和 `.codex/agents/dev-service-operator.toml`。
 
diff --git a/scripts/__tests__/dev-service-output.spec.ts b/scripts/__tests__/dev-service-output.spec.ts
index 5ebfe669d..3a0f873bd 100644
--- a/scripts/__tests__/dev-service-output.spec.ts
+++ b/scripts/__tests__/dev-service-output.spec.ts
@@ -45,21 +45,31 @@ describe('dev service machine output', () => {
     const root = mkdtempSync(join(tmpdir(), 'oneworks-run-tools-bootstrap-'))
     tempDirs.push(root)
     const binDir = join(root, 'bin')
+    const scriptsDir = join(root, 'scripts')
     mkdirSync(binDir)
-    copyFileSync(join(process.cwd(), 'scripts/run-tools.mjs'), join(root, 'run-tools.mjs'))
+    mkdirSync(scriptsDir)
+    mkdirSync(join(root, 'assets/avatar/packages/avatar'), { recursive: true })
+    mkdirSync(join(root, 'assets/demo-video/src'), { recursive: true })
+    writeFileSync(join(root, 'assets/avatar/packages/avatar/package.json'), '{}')
+    writeFileSync(join(root, 'assets/demo-video/src/commands.ts'), '')
+    copyFileSync(join(process.cwd(), 'scripts/run-tools.mjs'), join(scriptsDir, 'run-tools.mjs'))
     copyFileSync(
       join(process.cwd(), 'scripts/workspace-dependency-bootstrap.mjs'),
-      join(root, 'workspace-dependency-bootstrap.mjs')
+      join(scriptsDir, 'workspace-dependency-bootstrap.mjs')
+    )
+    copyFileSync(
+      join(process.cwd(), 'scripts/workspace-submodule-bootstrap.mjs'),
+      join(scriptsDir, 'workspace-submodule-bootstrap.mjs')
     )
     copyFileSync(
       join(process.cwd(), 'scripts/fallback-bootstrap-lock.mjs'),
-      join(root, 'fallback-bootstrap-lock.mjs')
+      join(scriptsDir, 'fallback-bootstrap-lock.mjs')
     )
-    writeFileSync(join(root, 'cli.ts'), 'module.exports = { runScriptsCli: async () => {} }\n')
+    writeFileSync(join(scriptsDir, 'cli.ts'), 'module.exports = { runScriptsCli: async () => {} }\n')
     const pnpmPath = join(binDir, 'pnpm')
     writeFileSync(pnpmPath, `#!/usr/bin/env node\n${installerBody}\n`)
     chmodSync(pnpmPath, 0o755)
-    return { pnpmPath, root, script: join(root, 'run-tools.mjs') }
+    return { pnpmPath, root, script: join(scriptsDir, 'run-tools.mjs') }
   }
 
   const waitForExit = async (child: ReturnType<typeof spawn>) => (
diff --git a/scripts/__tests__/pr-validation-scope.spec.ts b/scripts/__tests__/pr-validation-scope.spec.ts
index 03eba2286..eab8c24c4 100644
--- a/scripts/__tests__/pr-validation-scope.spec.ts
+++ b/scripts/__tests__/pr-validation-scope.spec.ts
@@ -53,7 +53,7 @@ describe('pr validation scope', () => {
   it('does not turn shared-package documentation into a client production build', () => {
     expect(classifyChangedPaths([
       'packages/adapters/codex/AGENTS.md',
-      'packages/avatar/README.md'
+      'packages/icon/README.md'
     ])).toMatchObject({
       clientBuild: false,
       desktopPackage: false,
@@ -191,10 +191,13 @@ describe('pr validation scope', () => {
       typecheck: false
     })
     expect(classifyChangedPaths(['assets/avatar'])).toMatchObject({
-      desktopPackage: false,
+      clientBuild: true,
+      desktopPackage: true,
       docsMedia: false,
+      lint: true,
       publicDocs: false,
-      typecheck: false
+      typecheck: true,
+      typecheckScopes: fullTypecheckScopes
     })
   })
 
diff --git a/scripts/__tests__/publish-plan-repository.spec.ts b/scripts/__tests__/publish-plan-repository.spec.ts
index 3fc15b487..ed925655c 100644
--- a/scripts/__tests__/publish-plan-repository.spec.ts
+++ b/scripts/__tests__/publish-plan-repository.spec.ts
@@ -198,4 +198,34 @@ describe('publish-plan repository metadata', () => {
     expect(result.plan.items.map(item => item.name)).toEqual(['@oneworks/valid'])
     expect(fixture.runCommand).toHaveBeenCalledTimes(1)
   })
+
+  it('leaves packages owned by an independent source repository out of the app publish plan', async () => {
+    const fixture = createFixture([
+      ['packages/valid', {
+        name: '@oneworks/valid',
+        version: '1.0.0',
+        repository: createRepository('packages/valid')
+      }],
+      ['assets/avatar/packages/avatar', {
+        name: '@oneworks/avatar',
+        version: '1.0.0-rc.6',
+        repository: {
+          type: 'git',
+          url: 'https://github.com/oneworks-ai/avatar.git',
+          directory: 'packages/avatar'
+        }
+      }]
+    ])
+    const packages = await loadWorkspacePackages('/repo', fixture.fsOps)
+    const plan = createPublishPlan(packages, parseArgs([]))
+
+    expect(plan.items.map(item => item.name)).toEqual(['@oneworks/valid'])
+    expect(plan.skippedIndependent).toEqual(['@oneworks/avatar'])
+    expect(() =>
+      createPublishPlan(
+        packages,
+        parseArgs(['--package', '@oneworks/avatar'])
+      )
+    ).toThrow('由其独立源码仓库发布')
+  })
 })
diff --git a/scripts/__tests__/release-tags.spec.ts b/scripts/__tests__/release-tags.spec.ts
index 205bb776d..cb7a343b6 100644
--- a/scripts/__tests__/release-tags.spec.ts
+++ b/scripts/__tests__/release-tags.spec.ts
@@ -241,7 +241,7 @@ describe('release tag planning', () => {
     ).toThrow(/must be newer/u)
   })
 
-  it('coordinates the root and all 76 workspace manifests on 1.0.0-rc.5', () => {
+  it('coordinates the root and all 75 parent workspace manifests on 1.0.0-rc.5', () => {
     const manifestPaths = [
       'package.json',
       ...readPackageManifestPaths('apps'),
@@ -256,7 +256,7 @@ describe('release tag planning', () => {
       manifest: JSON.parse(readFileSync(manifestPath, 'utf8'))
     }))
 
-    expect(manifests).toHaveLength(77)
+    expect(manifests).toHaveLength(76)
     expect(
       manifests
         .map(({ manifest }) => `${manifest.name}@${manifest.version}`)
diff --git a/scripts/__tests__/run-tools-bootstrap.spec.ts b/scripts/__tests__/run-tools-bootstrap.spec.ts
new file mode 100644
index 000000000..af3f01b12
--- /dev/null
+++ b/scripts/__tests__/run-tools-bootstrap.spec.ts
@@ -0,0 +1,123 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { chmodSync, copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+describe('run-tools cold workspace bootstrap', () => {
+  const tempDirs: string[] = []
+
+  afterEach(() => {
+    for (const path of tempDirs.splice(0)) rmSync(path, { force: true, recursive: true })
+  })
+
+  const createFixture = () => {
+    const root = mkdtempSync(join(tmpdir(), 'oneworks-run-tools-submodules-'))
+    tempDirs.push(root)
+    const binDir = join(root, 'bin')
+    const scriptsDir = join(root, 'scripts')
+    mkdirSync(binDir)
+    mkdirSync(scriptsDir)
+    for (
+      const name of [
+        'fallback-bootstrap-lock.mjs',
+        'run-tools.mjs',
+        'workspace-dependency-bootstrap.mjs',
+        'workspace-submodule-bootstrap.mjs'
+      ]
+    ) copyFileSync(join(process.cwd(), 'scripts', name), join(scriptsDir, name))
+    writeFileSync(
+      join(scriptsDir, 'cli.ts'),
+      `module.exports = { runScriptsCli: async () => {
+        if (process.argv.includes('--json')) process.stdout.write('{"ok":true}\\n')
+      } }\n`
+    )
+    writeFileSync(join(root, '.gitmodules'), '[submodule "assets/avatar"]\n')
+    const gitPath = join(binDir, 'git')
+    writeFileSync(
+      gitPath,
+      `#!/usr/bin/env node
+        const fs = require('node:fs')
+        const path = require('node:path')
+        const root = process.cwd()
+        fs.appendFileSync(path.join(root, 'git-invocations'), JSON.stringify(process.argv.slice(2)) + '\\n')
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150)
+        fs.mkdirSync(path.join(root, 'assets/avatar/packages/avatar'), { recursive: true })
+        fs.mkdirSync(path.join(root, 'assets/demo-video/src'), { recursive: true })
+        fs.writeFileSync(path.join(root, 'assets/avatar/packages/avatar/package.json'), '{}')
+        fs.writeFileSync(path.join(root, 'assets/demo-video/src/commands.ts'), '')
+      `
+    )
+    chmodSync(gitPath, 0o755)
+    const pnpmPath = join(binDir, 'pnpm')
+    writeFileSync(
+      pnpmPath,
+      `#!/usr/bin/env node
+        const fs = require('node:fs')
+        const path = require('node:path')
+        const root = process.cwd()
+        const countPath = path.join(root, 'install-count')
+        const count = Number(fs.existsSync(countPath) ? fs.readFileSync(countPath, 'utf8') : '0') + 1
+        fs.writeFileSync(countPath, String(count))
+        const moduleDir = path.join(root, 'node_modules/esbuild-register/dist')
+        fs.mkdirSync(moduleDir, { recursive: true })
+        fs.writeFileSync(path.join(root, 'node_modules/.modules.yaml'), 'ready: true\\n')
+        fs.writeFileSync(path.join(root, 'node_modules/esbuild-register/package.json'), JSON.stringify({
+          name: 'esbuild-register',
+          exports: { './dist/node': './dist/node.js' }
+        }))
+        fs.writeFileSync(path.join(moduleDir, 'node.js'), 'exports.register = () => {}\\n')
+      `
+    )
+    chmodSync(pnpmPath, 0o755)
+    return {
+      env: { ...process.env, PATH: `${binDir}:${process.env.PATH}` },
+      root,
+      script: join(scriptsDir, 'run-tools.mjs')
+    }
+  }
+
+  const waitForExit = async (child: ReturnType<typeof spawn>) => (
+    await new Promise<number | null>((resolve, reject) => {
+      child.once('error', reject)
+      child.once('exit', resolve)
+    })
+  )
+
+  it('keeps generic JSON output clean during cold submodule initialization', () => {
+    const fixture = createFixture()
+    const result = spawnSync(
+      process.execPath,
+      [fixture.script, 'release-tags', 'plan', 'base', 'head', '--json'],
+      { cwd: fixture.root, encoding: 'utf8', env: fixture.env }
+    )
+
+    expect(result.status).toBe(0)
+    expect(JSON.parse(result.stdout)).toEqual({ ok: true })
+    expect(JSON.parse(readFileSync(join(fixture.root, 'git-invocations'), 'utf8'))).toEqual([
+      'submodule',
+      'update',
+      '--init',
+      '--depth',
+      '1',
+      '--',
+      'assets/avatar',
+      'assets/demo-video'
+    ])
+  })
+
+  it('serializes required submodules and dependency install across sessions', async () => {
+    const fixture = createFixture()
+    const args = [fixture.script, 'dev-service', 'status', 'web', '--json']
+    const children = [
+      spawn(process.execPath, args, { cwd: fixture.root, env: fixture.env, stdio: 'ignore' }),
+      spawn(process.execPath, args, { cwd: fixture.root, env: fixture.env, stdio: 'ignore' })
+    ]
+
+    await expect(Promise.all(children.map(waitForExit))).resolves.toEqual([0, 0])
+    expect(readFileSync(join(fixture.root, 'git-invocations'), 'utf8').trim().split('\n'))
+      .toHaveLength(1)
+    expect(readFileSync(join(fixture.root, 'install-count'), 'utf8')).toBe('1')
+  }, 10_000)
+})
diff --git a/scripts/__tests__/workspace-dependency-bootstrap.spec.ts b/scripts/__tests__/workspace-dependency-bootstrap.spec.ts
index d5abc8ba8..bfbeefa4d 100644
--- a/scripts/__tests__/workspace-dependency-bootstrap.spec.ts
+++ b/scripts/__tests__/workspace-dependency-bootstrap.spec.ts
@@ -49,7 +49,8 @@ describe('workspace dependency bootstrap', () => {
       const name of [
         'fallback-bootstrap-lock.mjs',
         'run-workspace-check.mjs',
-        'workspace-dependency-bootstrap.mjs'
+        'workspace-dependency-bootstrap.mjs',
+        'workspace-submodule-bootstrap.mjs'
       ]
     ) {
       copyFileSync(join(process.cwd(), 'scripts', name), join(scriptsDir, name))
diff --git a/scripts/dev-start/git-workspace.ts b/scripts/dev-start/git-workspace.ts
index 321ac747c..a4acb1333 100644
--- a/scripts/dev-start/git-workspace.ts
+++ b/scripts/dev-start/git-workspace.ts
@@ -46,3 +46,8 @@ export const ensureWorkspaceInstall = () => {
   log('workspace install missing or incomplete; running pnpm install')
   runSync('pnpm', ['install'])
 }
+
+export const ensureRequiredWorkspaceSubmodules = () => {
+  log('initializing required workspace submodules')
+  runSync('git', ['submodule', 'update', '--init', '--depth', '1', '--', 'assets/avatar'])
+}
diff --git a/scripts/dev-start/manager.ts b/scripts/dev-start/manager.ts
index fc06e9139..93b771f02 100644
--- a/scripts/dev-start/manager.ts
+++ b/scripts/dev-start/manager.ts
@@ -8,7 +8,7 @@ import { withDevServiceOperation } from './coordination'
 import { getDocsUrl } from './docs-process'
 import { buildRuntimeEnv } from './env'
 import { resolveElectronLaunchIdentity, startAndroidEmulator, startElectron } from './external-targets'
-import { ensureGitUpdated, ensureWorkspaceInstall } from './git-workspace'
+import { ensureGitUpdated, ensureRequiredWorkspaceSubmodules, ensureWorkspaceInstall } from './git-workspace'
 import { resolvePorts } from './network'
 import { log, logDir, repoRoot } from './paths'
 import { withDevStartPortLock, withDevStartPreparationLock } from './port-lock'
@@ -134,6 +134,7 @@ export const runMain = async (
 
   await withDevStartPreparationLock(async () => {
     ensureGitUpdated()
+    ensureRequiredWorkspaceSubmodules()
     ensureWorkspaceInstall()
   })
   if (target !== 'docs') {
diff --git a/scripts/pr-validation-scope.cjs b/scripts/pr-validation-scope.cjs
index 69b1f304a..6e5f14e49 100644
--- a/scripts/pr-validation-scope.cjs
+++ b/scripts/pr-validation-scope.cjs
@@ -6,7 +6,7 @@ const { execFileSync } = require('node:child_process')
 const { appendFileSync } = require('node:fs')
 const process = require('node:process')
 
-const prValidationScopeVersion = 2
+const prValidationScopeVersion = 3
 
 const markdownPathPattern = /\.md$/iu
 const documentationMediaPathPattern = /\.(?:avif|gif|jpe?g|mp4|png|svg|webm|webp)$/iu
@@ -65,7 +65,7 @@ const knownRootPaths = new Set([
 ])
 const dependencyGraphPathPattern = /(?:^|\/)package\.json$/u
 const typecheckConfigPathPattern = /(?:^|\/)tsconfig(?:\.[^/]+)?\.json$/u
-const sourceCoupledGitlinkPaths = new Set(['assets/demo-video'])
+const sourceCoupledGitlinkPaths = new Set(['assets/avatar', 'assets/demo-video'])
 const lintablePathPattern = /\.(?:astro|cjs|cts|js|json|json5|jsx|mjs|mts|svelte|ts|tsx|vue|ya?ml)$/iu
 const typecheckPathPattern = /\.(?:cts|mts|ts|tsx)$/iu
 const environmentContractPathPattern = /\.(?:cjs|cts|js|jsx|mjs|mts|ts|tsx)$/iu
@@ -144,6 +144,7 @@ const isClientTypecheckPath = (filePath) =>
   filePath.startsWith('apps/client/src/') || filePath.startsWith('apps/client/__tests__/')
 
 const isClientProductionPath = (filePath) =>
+  filePath === 'assets/avatar' ||
   filePath.startsWith('apps/client/src/') ||
   filePath.startsWith('apps/client/public/') ||
   filePath === 'apps/client/index.html' ||
diff --git a/scripts/publish-plan-core.d.mts b/scripts/publish-plan-core.d.mts
index 7ebbcd7f3..2b179a901 100644
--- a/scripts/publish-plan-core.d.mts
+++ b/scripts/publish-plan-core.d.mts
@@ -29,6 +29,7 @@ export interface PublishPlanPackageJson {
 export interface PublishPlanPackage {
   name: string
   dir: string
+  independentlyReleased?: boolean
   private: boolean
   json: PublishPlanPackageJson
   publishAliasFor?: string
@@ -55,6 +56,7 @@ export interface PublishPlanItem {
 export interface PublishPlan {
   explicitSelection: boolean
   requestedNames: string[]
+  skippedIndependent: string[]
   skippedPrivate: string[]
   items: PublishPlanItem[]
 }
@@ -63,6 +65,7 @@ export interface PublishPlanSerializeResult {
   summary: {
     mode: 'plan' | 'publish' | 'publish-dry-run'
     packageCount: number
+    skippedIndependent: string[]
     skippedPrivate: string[]
     bump: PublishPlanOptions['bump'] | null
     command: string[] | null
diff --git a/scripts/publish-plan-core.mjs b/scripts/publish-plan-core.mjs
index 3cf874d05..6660560d7 100644
--- a/scripts/publish-plan-core.mjs
+++ b/scripts/publish-plan-core.mjs
@@ -15,6 +15,10 @@ export const bumpKinds = new Set(['major', 'minor', 'patch'])
 
 export const canonicalRepositoryUrl = 'https://github.com/oneworks-ai/app.git'
 
+const independentlyReleasedRepositoryUrls = new Set([
+  'https://github.com/oneworks-ai/avatar.git'
+])
+
 export const defaultOptions = {
   packages: [],
   publish: false,
@@ -314,6 +318,7 @@ export async function loadWorkspacePackages(repoRoot, fsOps = defaultFs) {
         name: json.name,
         dir,
         json,
+        independentlyReleased: independentlyReleasedRepositoryUrls.has(json.repository?.url),
         private: Boolean(json.private)
       })
     } catch {
@@ -351,6 +356,9 @@ function collectRequestedPackages(packages, requestedNames) {
     if (!pkg) {
       throw new Error(`未找到包: ${name}`)
     }
+    if (pkg.independentlyReleased) {
+      throw new Error(`包 ${name} 由其独立源码仓库发布，不能从 ${canonicalRepositoryUrl} 发布`)
+    }
 
     const sourceName = pkg.publishAliasFor ?? pkg.name
     selected.add(sourceName)
@@ -507,6 +515,7 @@ function analyzeDependentImpacts(name, nextVersion, reverseDependencies) {
 
 function collectAllPackages(packages, includePrivate) {
   const selected = new Set()
+  const skippedIndependent = []
   const skippedPrivate = []
 
   for (const [name, pkg] of packages) {
@@ -514,11 +523,16 @@ function collectAllPackages(packages, includePrivate) {
       skippedPrivate.push(name)
       continue
     }
+    if (pkg.independentlyReleased) {
+      skippedIndependent.push(name)
+      continue
+    }
     selected.add(name)
   }
 
   return {
     selected,
+    skippedIndependent: skippedIndependent.sort(),
     skippedPrivate: skippedPrivate.sort()
   }
 }
@@ -526,10 +540,16 @@ function collectAllPackages(packages, includePrivate) {
 export function createPublishPlan(packages, options) {
   const requestedNames = Array.from(new Set(options.packages))
   const explicitSelection = requestedNames.length > 0
+  const skippedIndependent = []
   const skippedPrivate = []
+  const allPackages = collectAllPackages(packages, options.includePrivate)
   const selected = explicitSelection
     ? collectRequestedPackages(packages, requestedNames)
-    : collectAllPackages(packages, options.includePrivate).selected
+    : allPackages.selected
+
+  if (!explicitSelection) {
+    skippedIndependent.push(...allPackages.skippedIndependent)
+  }
 
   if (!explicitSelection && !options.includePrivate) {
     skippedPrivate.push(...collectAllPackages(packages, false).skippedPrivate)
@@ -674,6 +694,7 @@ export function createPublishPlan(packages, options) {
   return {
     explicitSelection,
     requestedNames,
+    skippedIndependent,
     skippedPrivate,
     items
   }
@@ -743,6 +764,9 @@ export function formatPlan(plan, repoRoot, options) {
   if (plan.skippedPrivate.length > 0) {
     lines.push(`跳过 private 包: ${plan.skippedPrivate.join(', ')}`)
   }
+  if (plan.skippedIndependent.length > 0) {
+    lines.push(`跳过由独立仓库发布的包: ${plan.skippedIndependent.join(', ')}`)
+  }
 
   lines.push('', '发布顺序:')
 
@@ -781,6 +805,7 @@ export function serializePlan(plan, repoRoot, options) {
         : 'plan',
       packageCount: plan.items.length,
       skippedPrivate: plan.skippedPrivate,
+      skippedIndependent: plan.skippedIndependent,
       bump: options.bump || null,
       command: options.publish ? ['pnpm', ...buildPublishArgs(options)] : null
     },
diff --git a/scripts/run-tools.mjs b/scripts/run-tools.mjs
index 7f99a15f1..bb482629e 100644
--- a/scripts/run-tools.mjs
+++ b/scripts/run-tools.mjs
@@ -1,9 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import path from 'node:path'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
@@ -11,9 +9,8 @@ import { ensureWorkspaceDependencies } from './workspace-dependency-bootstrap.mj
 
 const SOURCE_CONDITION_ARG = '--conditions=__oneworks__'
 const SOURCE_CONDITION_REEXEC_ENV = '__ONEWORKS_RUN_TOOLS_SOURCE_CONDITION__'
-const machineJsonOutput = process.argv.includes('dev-service') && process.argv.includes('--json')
+const machineJsonOutput = process.argv.includes('--json')
 const require = createRequire(import.meta.url)
-const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 
 if (!process.execArgv.includes(SOURCE_CONDITION_ARG)) {
   const result = spawnSync(
@@ -57,28 +54,16 @@ const printBootstrapError = (message) => {
   }\n`)
 }
 
-const ensureDemoVideoSubmodule = () => {
-  const commandPath = path.join(repoRoot, 'assets/demo-video/src/commands.ts')
-  if (existsSync(commandPath)) return
-  if (!existsSync(path.join(repoRoot, '.gitmodules'))) return
-
-  const result = spawnSync(
-    'git',
-    ['submodule', 'update', '--init', '--depth', '1', '--', 'assets/demo-video'],
-    {
-      cwd: repoRoot,
-      encoding: 'utf8',
-      stdio: machineJsonOutput ? 'pipe' : 'inherit'
-    }
-  )
-  if (result.status === 0 && existsSync(commandPath)) return
-
-  const message = `Demo video submodule bootstrap failed (status=${result.status ?? 'unknown'}).`
-  if (machineJsonOutput) printBootstrapError(message)
-  else if (result.error != null) throw result.error
-  else process.stderr.write(`${message}\n`)
-  process.exit(result.status ?? 1)
-}
+const requiredWorkspaceSubmodules = [
+  {
+    path: 'assets/avatar',
+    requiredPath: 'assets/avatar/packages/avatar/package.json'
+  },
+  {
+    path: 'assets/demo-video',
+    requiredPath: 'assets/demo-video/src/commands.ts'
+  }
+]
 
 const finishWorkspaceDependencyInstall = (result) => {
   if (result.error == null && result.status === 0) return true
@@ -97,7 +82,8 @@ const installWorkspaceDependencies = () =>
       requiredPaths: [
         'node_modules/esbuild-register/package.json',
         'node_modules/esbuild-register/dist/node.js'
-      ]
+      ],
+      requiredSubmodules: requiredWorkspaceSubmodules
     })
   )
 
@@ -110,7 +96,7 @@ const loadRegister = async () => {
   }
 }
 
-ensureDemoVideoSubmodule()
+installWorkspaceDependencies()
 
 const { register } = await loadRegister()
 
diff --git a/scripts/workspace-dependency-bootstrap.mjs b/scripts/workspace-dependency-bootstrap.mjs
index 0687f24ec..4b5ac3458 100644
--- a/scripts/workspace-dependency-bootstrap.mjs
+++ b/scripts/workspace-dependency-bootstrap.mjs
@@ -5,6 +5,7 @@ import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
 import { acquireFallbackBootstrapLock } from './fallback-bootstrap-lock.mjs'
+import { initializeRequiredSubmodules, requiredSubmodulesReady } from './workspace-submodule-bootstrap.mjs'
 
 const DEFAULT_TIMEOUT_MS = 120_000
 const bootstrapScriptPath = fileURLToPath(import.meta.url)
@@ -26,11 +27,13 @@ const requiredBinPaths = (repoRoot, name) => {
 export const workspaceDependenciesReady = ({
   repoRoot,
   requiredBins = [],
-  requiredPaths = []
+  requiredPaths = [],
+  requiredSubmodules = []
 }) => (
   existsSync(resolve(repoRoot, 'node_modules', '.modules.yaml')) &&
   requiredBins.every(name => requiredBinPaths(repoRoot, name).some(existsSync)) &&
-  requiredPaths.every(path => existsSync(resolve(repoRoot, path)))
+  requiredPaths.every(path => existsSync(resolve(repoRoot, path))) &&
+  requiredSubmodulesReady(repoRoot, requiredSubmodules)
 )
 
 const runWorkspaceDependencyInstall = ({ quiet, repoRoot }) =>
@@ -41,6 +44,9 @@ const runWorkspaceDependencyInstall = ({ quiet, repoRoot }) =>
   })
 
 const installUnderLock = (options) => {
+  if (workspaceDependenciesReady(options)) return successfulResult()
+  const submoduleResult = initializeRequiredSubmodules(options)
+  if (submoduleResult.error != null || submoduleResult.status !== 0) return submoduleResult
   if (workspaceDependenciesReady(options)) return successfulResult()
   if (!options.quiet) {
     console.error('[workspace] dependencies are missing; running pnpm install')
@@ -60,7 +66,12 @@ const serializeBootstrapOptions = (options) => [
   options.repoRoot,
   ...(options.quiet ? ['--quiet'] : []),
   ...options.requiredBins.flatMap(name => ['--require-bin', name]),
-  ...options.requiredPaths.flatMap(path => ['--require-path', path])
+  ...options.requiredPaths.flatMap(path => ['--require-path', path]),
+  ...options.requiredSubmodules.flatMap(({ path, requiredPath }) => [
+    '--require-submodule',
+    path,
+    requiredPath
+  ])
 ]
 
 export const ensureWorkspaceDependencies = ({
@@ -68,9 +79,10 @@ export const ensureWorkspaceDependencies = ({
   repoRoot,
   requiredBins = [],
   requiredPaths = [],
+  requiredSubmodules = [],
   timeoutMs = DEFAULT_TIMEOUT_MS
 }) => {
-  const options = { quiet, repoRoot, requiredBins, requiredPaths }
+  const options = { quiet, repoRoot, requiredBins, requiredPaths, requiredSubmodules }
   if (workspaceDependenciesReady(options)) return successfulResult()
 
   const lockDir = resolve(repoRoot, '.logs')
@@ -115,7 +127,8 @@ const parseBootstrapChildOptions = (args) => {
     quiet: false,
     repoRoot: undefined,
     requiredBins: [],
-    requiredPaths: []
+    requiredPaths: [],
+    requiredSubmodules: []
   }
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index]
@@ -138,6 +151,14 @@ const parseBootstrapChildOptions = (args) => {
       index += 1
       continue
     }
+    if (arg === '--require-submodule') {
+      options.requiredSubmodules.push({
+        path: args[index + 1],
+        requiredPath: args[index + 2]
+      })
+      index += 2
+      continue
+    }
     throw new Error(`Unknown workspace bootstrap argument: ${arg}`)
   }
   if (options.repoRoot == null) throw new Error('Workspace bootstrap requires --repo-root.')
diff --git a/scripts/workspace-submodule-bootstrap.mjs b/scripts/workspace-submodule-bootstrap.mjs
new file mode 100644
index 000000000..270cbfdba
--- /dev/null
+++ b/scripts/workspace-submodule-bootstrap.mjs
@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import process from 'node:process'
+
+const successfulResult = () => ({
+  error: undefined,
+  status: 0,
+  stderr: null,
+  stdout: null
+})
+
+export const requiredSubmodulesReady = (repoRoot, requiredSubmodules = []) =>
+  requiredSubmodules.every(({ requiredPath }) => existsSync(resolve(repoRoot, requiredPath)))
+
+export const initializeRequiredSubmodules = (options) => {
+  const missingSubmodules = options.requiredSubmodules.filter(({ requiredPath }) =>
+    !existsSync(resolve(options.repoRoot, requiredPath))
+  )
+  if (missingSubmodules.length === 0) return successfulResult()
+  if (!existsSync(resolve(options.repoRoot, '.gitmodules'))) {
+    if (!options.quiet) console.error('[workspace] required submodules are missing')
+    return { ...successfulResult(), status: 1 }
+  }
+
+  const result = spawnSync(
+    'git',
+    [
+      'submodule',
+      'update',
+      '--init',
+      '--depth',
+      '1',
+      '--',
+      ...missingSubmodules.map(({ path }) => path)
+    ],
+    {
+      cwd: options.repoRoot,
+      env: process.env,
+      stdio: options.quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+    }
+  )
+  if (
+    result.error == null &&
+    result.status === 0 &&
+    requiredSubmodulesReady(options.repoRoot, missingSubmodules)
+  ) return result
+  if (!options.quiet) console.error('[workspace] required submodule bootstrap failed')
+  return { ...result, status: result.status ?? 1 }
+}