feat(avatar): replace legacy renderer with 3D SDK

.github/actions/setup-workspace/action.yml

@@ -4,13 +4,18 @@ 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
       with:
         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') }}
 

.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:

.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:

.github/workflows/deploy-avatar.yml

@@ -7,7 +7,6 @@ on:
     paths:
       - assets/avatar
       - assets/avatar/**
-      - packages/avatar/**
       - .github/workflows/deploy-avatar.yml
   workflow_dispatch:
 

.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/**

.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:

.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

.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:

.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 }}

.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:

.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

.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:

.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:

.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 }}

.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

.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'

.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`.

.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'