cortico-world-wardrobe-studio 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0
+
+- Add an opt-in native wardrobe compatibility adapter for the checksum-verified desktop-pet 0.2.0 page: outfits followed by outfit-specific controls.
+- Keep standard native appearance persistence, Coo/unconfigured figures, preview and import/removal flows.
+- Back up before patching; restore on normal stop, recover interrupted installation and refuse overwriting external changes.
+- Use an origin/token-checked, read-only loopback feed without weakening CSP or modifying figure resources.
+- Document supported versions, explicit configuration, uninstall/recovery and the distinction from an official host API.
+- Refresh bilingual project documentation and make the GitHub README English by default.
+
 ## 0.3.0
 
 - Default to Chinese with a shared, persistent Chinese/English panel selector; preserve pending choices and JSON drafts when switching.

package/README.en.md

@@ -0,0 +1,5 @@
+# Wardrobe Studio
+
+English is now the default [README](README.md).
+
+[简体中文](README_zh.md)

package/README.md

@@ -1,46 +1,142 @@
-# Wardrobe Studio · a Cortico World extension
+<div align="center">
 
-Choose an outfit in a separate wardrobe panel, then configure only the options that belong to it. A local profile maps complete combinations to existing figure schemes. The original Coopanion wardrobe page and figure files remain unchanged.
+<img src="assets/icon.svg" width="72" height="72" alt="Wardrobe Studio">
 
-The extension defaults to Chinese. Use the Chinese/English selector above either panel; the choice is remembered across panels and restarts. It does not change the host language or imported names, and preserves pending outfit choices and JSON drafts.
+# Wardrobe Studio
 
-[中文说明](README_zh.md)
+**Choose an outfit. Configure what belongs to it.**
 
-![Wholly fictional wardrobe example](assets/wardrobe.png)
+Outfit-specific controls and a continuous-animation authoring guide for Coopanion.
 
-The fictional Moss Fox demonstrates three different groups: trail outfits expose cape and footwear, rain outfits expose hood and raincoat colour, and stargazer outfits expose a visor. Combinations without animation resources cannot be applied. The panel follows the host theme, with a dotted preview stage and compact outfit cards. Installed-character previews use local figure thumbnails; the demonstration contains only fictional artwork.
+[![npm](https://img.shields.io/npm/v/cortico-world-wardrobe-studio?color=c87c5d&label=npm)](https://www.npmjs.com/package/cortico-world-wardrobe-studio)
+[![Checks](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/actions/workflows/check.yml/badge.svg)](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/actions/workflows/check.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-6b9f87)](LICENSE)
 
-## Use
+**English** · [简体中文](README_zh.md)
 
-1. Install this folder using the manual World extension installer. Restart the Core process as requested and enable Wardrobe Studio. Verify it with isolated data before adopting it in a running deployment.
-2. Keep the desktop-pet World available. The default service origin is `http://127.0.0.1:7797`; change it in the extension configuration and restart this World if necessary.
-3. Read Format reference in the import area, download the fictional example/JSON Schema, inspect installed IDs and Check configuration before importing. Then choose an outfit/options and Apply. See the [profile format](docs/profile-format.md) and the fictional example.
-4. Before uninstalling, use Restore previous appearance, verify success, disable the World and uninstall it. Normal stopping also attempts restoration. External appearance changes are preserved. See [lifecycle and recovery](docs/lifecycle.md).
+[Get started](#get-started) · [Create a character](docs/agent-workflow.md) · [Profile format](docs/profile-format.md) · [Downloads](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/releases)
 
-Every mapped combination must already have complete figure resources. The extension does not combine images into new clothing or fill missing motion. Coo's separate accessory contract continues to use its native wardrobe.
+</div>
 
-## Authoring guide
+---
 
-The detailed guide includes copyable image/video prompts, input/output formats, alpha extraction and playback steps, a figure manifest scaffold, complete wardrobe JSON fields/examples, and stale-upgrade recovery. The guide panel and agent tool cover complete dressed references, continuous action video, normal/half-speed and loop acceptance, temporal local matting, declared pose/expression support, runtime integration and versioned releases. The [full workflow](docs/agent-workflow.md) uses generic practices and a fictional example.
+## One outfit, its own controls
 
-Tools: `wardrobe_list`, `wardrobe_choose`, `wardrobe_restore`, `wardrobe_authoring_guide`. Guidance returns instructions; it does not install tools, download models, run generation or read conversations.
+A character's outfits do not need to share every option. Wardrobe Studio groups existing complete figure schemes and displays only the controls that belong to the selected outfit.
 
-## Data and compatibility
+| You want to… | Wardrobe Studio provides… |
+| :--- | :--- |
+| Organize a wardrobe | Outfit-specific options; unavailable combinations disabled |
+| Choose a combination | Standard appearance persistence and local thumbnails |
+| Use the native wardrobe | Optional, reversible compatibility adapter in 0.4 |
+| Create a character | Reference prompts, continuous video, playback gates and temporal matting guidance |
+| Write an import profile | Field tables, fictional examples, JSON Schema and installed-ID checks |
+
+> [!IMPORTANT]
+> Native integration is an **experimental opt-in compatibility patch**, not an official World slot. It temporarily patches the checksum-verified desktop-pet page and restores it on normal stop. Unsupported versions are refused. [Supported host, setup and recovery →](docs/native-integration.md)
+
+<details>
+<summary><strong>Separate-panel preview · entirely fictional artwork</strong></summary>
+<br>
+<div align="center"><img src="assets/wardrobe.png" width="500" alt="A wholly fictional Moss Fox wardrobe"></div>
+
+Moss Fox has cape/footwear options for trail outfits, hood/colour for rain outfits, and a visor for stargazer outfits. This screenshot illustrates the separate panel, not native compatibility mode.
+
+</details>
+
+## Get started
+
+### 1 · Install and enable
+
+Find **Wardrobe Studio** / `cortico-world-wardrobe-studio` in Coopanion's World extension market. Restart Core when requested and enable it. Alternatively, download a [GitHub release](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/releases), extract it and select the folder containing `package.json` in the manual installer.
+
+### 2 · Prepare figure resources
+
+Keep the desktop-pet World running and install/verify your figure pack first. The default service is `http://127.0.0.1:7797`; change it in the extension configuration if necessary, then restart this World.
+
+**A wardrobe JSON groups existing resources; it contains no images or videos.** Every mapped combination must already be playable.
+
+### 3 · Check and import
+
+Open **Wardrobe Studio → Wardrobe → Import profile**. Inspect installed IDs, download the fictional example or JSON Schema, fill in your figure/schemes, run **Check configuration**, then import. Choose an outfit/options and **Apply**.
+
+The extension UI defaults to Chinese. Its **中文 / English** selector is persistent and independent of the host language; imported names remain your own text.
+
+[Complete profile format and example →](docs/profile-format.md)
+
+### 4 · Optional native integration
+
+Configure the installed desktop-pet `web` directory, enable **Native wardrobe compatibility patch**, and restart this World. Reopen the native wardrobe page. Configured figures show outfit/part rows; Coo and unconfigured figures retain their controls.
+
+This mode is off by default. Read the [compatibility and rollback guide](docs/native-integration.md) before enabling it.
 
-The extension stores profiles and appearance recovery records only under its own `wardrobe-studio/` directory. Applying an outfit changes the selected figure/scheme through the desktop pet's appearance API. Other preferences are preserved. Application code, original figure files and other extensions are not edited.
+### 5 · Disable or uninstall
 
-Normal stop restores the appearance still owned by this extension. Forced termination, an unavailable desktop service or removal of the old figure can require recovery on the next activation; unconditional restoration cannot be promised in those cases. All selected schemes are existing valid schemes, so the original figure does not depend on this extension after removal.
+For changes made in the separate panel, use **Restore previous appearance** first. Disable the World and verify any native patch was restored before uninstalling. Native-page selections are ordinary host selections and remain valid after removal.
 
-This initial release is experimental: World API 6, figure manifest/API 2, Node.js ≥22, no runtime npm dependencies. Configuration changes, applying appearances, disable restoration and reactivation were checked in a real Core host. The separate panel does not change native fixed-axis layout. See the [verification scope](docs/verification.md) and [publishing guide](docs/publishing.md).
+[Lifecycle and recovery →](docs/lifecycle.md)
 
-## Develop
+## Create your own character
+
+The guide panel, agent tool and downloadable manuals share the same source documents.
+
+| Stage | Deliverable and acceptance |
+| :--- | :--- |
+| ① Plan | Identity, wardrobe/action matrix and reversible environment record |
+| ② Reference | Fully dressed reference for each supported combination |
+| ③ Continuous video | Dressed reference plus motion guidance; validate one short action first |
+| ④ Raw-video review | Complete normal-speed, half-speed and loop playback |
+| ⑤ Temporal matting | Correct masks, propagate over time and review on contrasting backgrounds |
+| ⑥ Figure package | Coordinates, movement, transitions and actual expression coverage |
+| ⑦ Wardrobe profile | Map installed complete schemes, validate and import |
+
+[Read the detailed workflow →](docs/agent-workflow.md)
+
+## Documentation
+
+| Document | What it covers |
+| :--- | :--- |
+| [Authoring workflow](docs/agent-workflow.md) | Inputs, outputs, prompts, video/alpha requirements and figure interface |
+| [Profile format](docs/profile-format.md) | Required fields, limits, full example and missing combinations |
+| [Native integration](docs/native-integration.md) | Opt-in setup, exact compatibility, file changes and recovery |
+| [Troubleshooting](docs/troubleshooting.md) | Stale resource URLs, connections and runtime resources |
+| [Verification](docs/verification.md) | Checks performed and compatibility boundaries |
+| [Changelog](CHANGELOG.md) | Version history |
+
+## Data and compatibility
+
+- Profiles, language and recovery records stay in this extension's local namespace. No conversation reading or internet requests.
+- Figure manifests and animation assets are never modified. The optional native adapter temporarily changes only its documented page files.
+- Native integration requires the exact reviewed desktop-pet page. Host updates can disable it; the independent panel remains available.
+- World API 6, figure manifest/API 2, Node.js ≥22; no runtime npm dependencies or model downloads.
+- Guidance provides instructions, not automatic media generation or missing animation resources.
+
+<details>
+<summary><strong>Development and agent tools</strong></summary>
 
 ```sh
-npm test
 npm run check
+npm test
 npm run preview
 ```
 
-The preview uses an isolated temporary deployment and fictional data. The package contains source, guidance and fictional examples, without private character media or generation models.
+The preview uses isolated temporary data and fictional artwork. Tests exercise recovery and origin restrictions against disposable fixtures.
+
+| Tool | Purpose |
+| :--- | :--- |
+| `wardrobe_list` | Inspect local profiles and current appearance |
+| `wardrobe_choose` | Apply an existing valid combination |
+| `wardrobe_restore` | Restore a separately leased appearance |
+| `wardrobe_authoring_guide` | Read workflow, format and troubleshooting guidance |
+
+Public examples are entirely fictional. Keep personal figures, profiles and production records outside this repository.
+
+</details>
+
+---
+
+<div align="center">
+
+[MIT License](LICENSE) · Independent extension · Not an official Coopanion / Pal AI Lab component
 
-MIT License. Independent third-party extension; not an official Coopanion or Pal AI Lab component.
+</div>

package/README_zh.md

@@ -1,37 +1,121 @@
-# 装扮工作室 · World 扩展
+<div align="center">
 
-在独立衣橱面板中，先选择服装，再显示这套服装自己的搭配选项。通过本地配置把选项组合映射到形象包已有的完整装扮，不修改 Coopanion 原生装扮页或角色文件。
+<img src="assets/icon.svg" width="72" height="72" alt="装扮工作室">
 
-扩展默认中文，衣橱和制作指导上方可切换 English，并记住选择。切换不会改变 Coopanion 整体语言、已导入名称、待应用搭配或编辑中的 JSON。
+# 装扮工作室
 
-![完全虚构的衣橱示例](assets/wardrobe.png)
+**先选服装，再选搭配。**
 
-例如，虚构角色“苔星狐”的森林探险装有斗篷、足部装备；雨林装有雨帽、雨披颜色；观星装有护目镜。切换服装后，配置项随之改变。没有资源的组合不能应用。界面跟随宿主配色，采用点阵预览区、紧凑服装卡片和横排选项；本机预览读取形象包缩略图，公开示例只使用虚构角色。
+为 Coopanion 整理角色衣橱，提供从参考图到连续动画的制作指南。
 
-## 使用
+[![npm](https://img.shields.io/npm/v/cortico-world-wardrobe-studio?color=c87c5d&label=npm)](https://www.npmjs.com/package/cortico-world-wardrobe-studio)
+[![Checks](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/actions/workflows/check.yml/badge.svg)](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/actions/workflows/check.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-6b9f87)](LICENSE)
 
-1. 在 World 扩展的手动安装中选择本包目录；按宿主提示重启进程，再启用“装扮工作室”。首次接入请先用隔离数据验证。
-2. 保持桌宠 World 可用。默认地址为 `http://127.0.0.1:7797`；端口不同可在扩展配置中修改，之后重启此 World。
-3. 打开扩展的“衣橱”面板，在导入区查看“格式说明”，下载虚构示例／JSON Schema，查看本机 ID，先“校验配置”再导入属于本机角色的 JSON 分组配置，选择服装和搭配，点击“应用装扮”。[配置格式](docs/profile-format.zh.md)包含完整虚构示例。
-4. 卸载前点击“恢复原外观”，确认成功后停用并卸载扩展。正常停用也会尝试恢复；在原生页另做的选择会被保留。[生命周期和异常恢复](docs/lifecycle.md)说明边界。
+**简体中文** · [English](README.md)
 
-本扩展不会把已有图片拼成未制作的服装，也不会自动补齐动作。先为每个有效搭配制作并验收完整资源，再配置其映射。Coo 自带配件使用独立契约，继续由原生页管理。
+[开始使用](#开始使用) · [制作自己的角色](docs/agent-workflow.zh.md) · [JSON 格式](docs/profile-format.zh.md) · [下载版本](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/releases)
 
-## 角色制作指导
+</div>
 
-“角色制作指导”提供可复制的参考图／动作提示词、输入输出与帧格式、连续抠像步骤、形象接口骨架、完整衣橱 JSON 字段／示例、升级故障排查。面板和 agent 工具提供分阶段工作流：角色与完整穿衣参考定稿、连续动作视频、原速／半速及循环验收、本地连续抠像、姿态与表情支持范围、运行时接入和版本发布。[完整指南](docs/agent-workflow.zh.md)只包含可复用的制作流程，没有个人角色或历史素材。
+---
 
-工具：`wardrobe_list`、`wardrobe_choose`、`wardrobe_restore`、`wardrobe_authoring_guide`。指导工具只返回说明，不安装工具、下载模型、执行生成任务或读取聊天记录。
+## 一套服装，一组自己的选项
 
-## 数据与兼容
+同一角色的不同服装不必共用所有配置项。装扮工作室把角色包已有的完整外观重新分组，只显示当前服装支持的搭配。
+
+| 你要做的事 | 扩展提供什么 |
+| :--- | :--- |
+| 整理衣橱 | 按服装显示独立选项，禁用没有完整资源的组合 |
+| 切换搭配 | 使用桌宠标准外观接口，读取本机角色缩略图 |
+| 制作角色 | 参考图提示词、连续视频、播放验收、连续抠像、形象包接入指南 |
+| 编写配置 | 完整字段表、虚构示例、JSON Schema、本机 ID 查询和只读校验 |
+| 切换语言 | 默认中文，可选 English，记住选择并保留编辑草稿 |
+
+> [!IMPORTANT]
+> **0.4 新增可选的原生装扮页兼容补丁，默认关闭。** 这不是官方 World 插槽，会临时修改经过校验的原生页面，正常停用时恢复。不兼容版本会拒绝修改。[支持版本、设置和回滚说明 →](docs/native-integration.zh.md)
+
+<details>
+<summary><strong>查看独立衣橱预览 · 完全虚构角色</strong></summary>
+<br>
+<div align="center"><img src="assets/wardrobe.png" width="500" alt="虚构苔星狐的独立衣橱面板"></div>
+
+示例“苔星狐”的探险装有斗篷和足部装备，雨林装有雨帽与雨披颜色，观星装只有护目镜。公开素材仅包含虚构示例。
+
+</details>
+
+## 开始使用
+
+### 1 · 安装并启用
+
+在 Coopanion 的 **World 扩展市场**搜索 `装扮工作室` 或 `cortico-world-wardrobe-studio`，安装后按宿主提示重启 Core，再启用扩展。
+
+也可从 [GitHub Releases](https://github.com/FelixHenrikChristian/cortico-world-wardrobe-studio/releases) 下载归档，解压后在手动安装中选择含 `package.json` 的目录。
+
+### 2 · 准备已有的角色资源
+
+保持桌宠 World 运行，并先安装、验收自己的形象包。默认本机服务地址为 `http://127.0.0.1:7797`；端口不同可在扩展配置中修改，之后重启此 World。
+
+**衣橱 JSON 负责分组，不包含图片或视频。** 每个有效搭配需要先有能实际播放的角色资源。
+
+### 3 · 校验并导入衣橱
+
+打开 **装扮工作室 → 衣橱 → 导入衣橱配置**：
+
+1. 查看本机装扮 ID，下载虚构示例或 JSON Schema。
+2. 按自己的角色填写 `figure`、服装选项和已有 `scheme`。
+3. 点击 **校验配置**，修复结构或 ID 报错后再导入。
+4. 选择服装与搭配，点击 **应用装扮**。
+
+[完整 JSON 字段与可复制示例 →](docs/profile-format.zh.md)
 
-扩展只在自己的 `wardrobe-studio/` 目录保存本机衣橱和外观恢复记录。选择已有搭配通过桌宠标准外观接口生效，其他偏好保持原值。形象包、主程序、其他扩展和素材不被改写。
+### 4 · 可选：在原生装扮页选择
 
-正常停用时会恢复仍由本扩展接管的外观。强制结束进程、桌宠服务提前停止或旧形象被删除时，恢复可能需要下次启用后执行；不能承诺这些情形下无条件自动恢复。扩展通过现有有效装扮切换，卸载不会让原形象依赖缺失的扩展代码。
+导入配置后，在扩展配置填写已安装 desktop-pet 包的 `web` 绝对目录，开启「原生装扮页兼容补丁」，重启此 World 并重新打开原生装扮页。配置过的角色显示「服装 → 当前服装的部件」；其他角色与 Coo 保持原控件。启用前请阅读[兼容与回滚说明](docs/native-integration.zh.md)。
 
-当前为实验性首版：World API 6、形象包 manifest/API 2、Node.js ≥22，零运行时 npm 依赖。已在真实 Core 宿主中验收配置切换、应用外观、停用恢复和重新启用。独立面板不改变原生装扮页的固定配置轴。[验证范围](docs/verification.md)与[发布方式](docs/publishing.md)说明当前边界和市场流程。
+### 5 · 停用或卸载
 
-## 开发预览
+独立面板应用的外观先点 **恢复原外观**并确认成功，再停用 World，确认原生页兼容补丁已恢复后卸载。正常停用也会尝试恢复仍由扩展接管的外观；原生页选择按普通宿主装扮保存，停用后保留。
+
+[生命周期、异常恢复与边界 →](docs/lifecycle.md)
+
+## 制作自己的角色
+
+手册与扩展内“角色制作指导”使用同一份内容，可以下载完整 Markdown 版。
+
+| 阶段 | 交付与检查 |
+| :--- | :--- |
+| ① 规划 | 角色设定、服装／动作清单、环境与回退记录 |
+| ② 参考图 | 每个有效搭配的完整穿衣图、统一轮廓与画风 |
+| ③ 连续视频 | 完整穿衣参考 + 动作驱动，先验证一个短动作 |
+| ④ 原片验收 | 完整原速、半速及循环接缝检查 |
+| ⑤ 连续抠像 | 首帧纠正、时序传播、多背景透明度播放检查 |
+| ⑥ 形象包 | 坐标、移动、动作衔接及真实表情覆盖验收 |
+| ⑦ 衣橱配置 | 映射已安装搭配，校验后导入 |
+
+[阅读详细制作指南 →](docs/agent-workflow.zh.md)
+
+## 文档导航
+
+| 文档 | 内容 |
+| :--- | :--- |
+| [从零制作](docs/agent-workflow.zh.md) | 输入输出、提示词、视频与透明素材要求、形象接口骨架 |
+| [衣橱 JSON](docs/profile-format.zh.md) | 必填字段、ID 规则、完整示例、缺失组合和常见报错 |
+| [故障排查](docs/troubleshooting.zh.md) | 旧资源地址、连接与预览、配置通过但动画缺失 |
+| [原生页兼容](docs/native-integration.zh.md) | 实验集成、精确版本限制、文件变更与卸载恢复 |
+| [验证范围](docs/verification.md) | 实际检查过什么、兼容性边界 |
+| [更新记录](CHANGELOG.md) | 已发布版本变更 |
+
+## 数据与兼容
+
+- **本机存储**：配置、语言偏好和外观恢复记录保存在扩展自己的目录。
+- **资源保护**：角色 manifest 与动画素材始终不改写；原生页兼容选项开启后临时修改其文档列出的页面文件。
+- **恢复边界**：强制结束进程、服务不可用或旧角色被删除时，可能需要下次启用后恢复；卸载前应确认结果。
+- **运行要求**：World API 6、形象包 manifest/API 2、Node.js ≥22，零运行时 npm 依赖。
+- **能力范围**：指导工具提供步骤，不自动安装模型、生成素材或补齐未制作的动作。Coo 自带配件继续使用原生页。
+
+<details>
+<summary><strong>开发与 agent 工具</strong></summary>
 
 ```sh
 npm test
@@ -39,6 +123,23 @@ npm run check
 npm run preview
 ```
 
-预览使用独立临时数据和虚构角色，不连接已有 Coopanion。正式包没有图片、视频模型或私有角色素材，只有虚构示例和工具代码。
+开发预览使用独立临时数据与虚构角色。原生集成原型是另一个隔离服务，启动方式见其文档。
+
+| 工具 | 作用 |
+| :--- | :--- |
+| `wardrobe_list` | 读取本地衣橱和当前外观 |
+| `wardrobe_choose` | 切换已有合法搭配 |
+| `wardrobe_restore` | 恢复扩展接管前外观 |
+| `wardrobe_authoring_guide` | 读取制作流程、格式与排查说明 |
+
+公共源码只使用完全虚构的示例。个人角色、衣橱配置和生产记录应放在仓库之外。
+
+</details>
+
+---
+
+<div align="center">
+
+[MIT License](LICENSE) · 第三方独立扩展 · 非 Coopanion / Pal AI Lab 官方组件
 
-MIT License。第三方独立扩展，不代表 Coopanion 或 Pal AI Lab 官方。
+</div>

package/docs/lifecycle.md

@@ -1,10 +1,10 @@
 # Appearance ownership and lifecycle · `src/bridge.js`, `src/store.js`, `src/index.js`
 
-Wardrobe Studio reads a local desktop-pet HTTP service at a configurable loopback origin. Runtime requests use `/api/figures`, `/api/state`, `/api/skin` and read-only thumbnail assets declared by installed packs. Thumbnail URLs must remain within the same loopback origin and pack asset directory; redirects are rejected, image MIME types are restricted and responses are limited to 2 MiB. The state response is reduced to appearance data before it is returned by the extension. The extension opens no listening service in production and makes no internet request. The optional development preview listens on loopback and uses fictional data.
+Wardrobe Studio reads a local desktop-pet HTTP service at a configurable loopback origin. Runtime requests use `/api/figures`, `/api/state`, `/api/skin` and read-only thumbnail assets declared by installed packs. Thumbnail URLs must remain within the same loopback origin and pack asset directory; redirects are rejected, image MIME types are restricted and responses are limited to 2 MiB. The state response is reduced to appearance data before it is returned by the extension. The extension makes no internet request. When explicitly enabled, the [native compatibility adapter](native-integration.md) opens a read-only, origin/token-checked loopback WebSocket feed; otherwise no listening production service is opened.
 
 ## What changes
 
-Importing a profile writes `wardrobe-studio/profiles.json` under the extension's supplied data directory. Applying a combination uses the desktop pet's standard appearance API; this changes its selected figure/scheme as an ordinary wardrobe selection does. It never edits the original figure manifest, assets, code, other extensions or the application.
+Importing a profile writes `wardrobe-studio/profiles.json` under the extension's supplied data directory. Applying a combination uses the desktop pet's standard appearance API; this changes its selected figure/scheme as an ordinary wardrobe selection does. Figure manifests and animation assets are never edited. The optional native adapter writes a backup and temporarily patches only the documented native page files; it is not an official host hook.
 
 The extension defaults to Chinese independently of the host language. Its Chinese/English selector stores only `{language}` in its own `wardrobe-studio/preferences.json`, shared by both panels and retained across restart. It does not change the host language, profiles or appearance. Imported names remain user-provided text. Switching panel language preserves the pending outfit selection and JSON draft.
 
@@ -16,6 +16,8 @@ The Restore button and World `stop()` compare the current figure/scheme with the
 
 The standard uninstall sequence is: Restore, disable the World, then uninstall it from World extensions. Normal stopping also attempts restoration. The resulting figure remains a standard installed pack with no dependency on this extension. Cortico may retain the extension's own configuration and local profiles; they do not alter original figure data.
 
+In native compatibility mode, ordinary native selections are not leased by this extension: they remain selected after stopping. The adapter closes its feed and conditionally restores its owned page files on stop. Verify rollback before uninstalling. Forced termination, external page edits and host upgrades require the recovery procedure in the native integration guide; unknown files are never overwritten automatically.
+
 If the process is forcibly killed, the desktop service is unavailable during shutdown, or the previous figure has been removed, automatic restoration cannot be guaranteed. The lease remains for recovery on the next activation, and restoration problems are reported in the panel and shutdown verification. Restore while the desktop service is available before uninstalling. Retained schemes are existing valid schemes, so removing the extension does not make the original figure unloadable.
 
 The desktop API has no compare-and-swap contract. Ownership is checked immediately before restoration, but simultaneous writes from another client cannot be made atomic by an external extension. Avoid changing the same appearance from two panels at the same instant.

package/docs/native-integration-prototype.md

@@ -0,0 +1,50 @@
+# 原生装扮页集成 · 隔离原型
+
+## 状态
+
+此原型验证“原生装扮页 → 服装 → 当前服装的部件选项”的交互。**这是 0.3 开发阶段的历史原型；0.4 的可选兼容实现见[正式设置说明](native-integration.zh.md)。** 此原型本身没有安装到真实 Coopanion，也没有修改其程序或角色文件。
+
+原生页目前直接遍历角色包的 axes/options，没有供外部 World 接管这一块的正式接口。原型在独立 HTTP 服务中只读加载本机原生页面，对发送给浏览器的 dress.js 副本增加一个明确的渲染钩子；磁盘上的源文件保持不变。没有把未知脚本注入正在使用的窗口。
+
+## 验证的交互
+
+| 场景 | 预期行为 |
+| --- | --- |
+| 已启用，角色有合法衣橱配置 | 隐藏原配置轴，显示服装与该服装自己的部件 |
+| 没有资源的组合 | 对应部件选项禁用 |
+| 换到无配置角色或 Coo | 保留其原生控件 |
+| 停用、模拟卸载或提供方离线 | 恢复原配置轴与完整搭配列表 |
+| 选择已有搭配 | 原生预览切换，预览 iframe 保持存在 |
+
+原型中的外观修改只写入该进程的内存。停用集成只撤回分组 UI；已经选中的合法 scheme 仍可由原生页显示。未来正式原生集成应将用户点击视为宿主的普通装扮选择，不依赖插件文件才能继续播放。独立衣橱面板已有的外观接管／恢复机制保持其原有定义。
+
+## 运行
+
+需要现有的 Node.js 与已安装 desktop-pet 包。脚本复用该包已有的 ws 模块，不下载依赖、模型或角色资源。
+
+```sh
+node prototypes/native-dress/server.mjs --web "<desktop-pet 包的 web 目录>" --port 65088
+```
+
+浏览器打开终端打印的回环地址。默认只使用 Coo 和本仓库原创虚构狐狸。狐狸只有用于界面验证的轻微待机运动，不是完整动画资源包，也不代表生成素材通过了验收。
+
+页面上方可模拟启用、停用、卸载、重新注册及接口离线。原生安装／删除入口在隔离服务中不可用。
+
+也可以明确指定自己的私有配置及本机角色资源目录：
+
+```sh
+node prototypes/native-dress/server.mjs --web "<desktop-pet/web>" --profile "<私有 wardrobe.json>" --figure-root "<本机 figures 目录>" --seed "http://127.0.0.1:7797" --port 65089
+```
+
+此模式只在启动时 GET 读取本机形象列表和外观，之后使用隔离内存状态；角色文件只读、按需加载，不复制整套素材。个人配置、截图、日志和绝对路径不要提交到公开仓库。
+
+## 原型边界与正式接入
+
+本轮已手动检查虚构角色的服装／部件切换、原生预览、Coo 配件保留、停用、模拟卸载、重新注册和接口离线回退。另在隔离状态中检查了已有本机角色及不完整组合禁用；个人配置和该轮截图不在公开仓库中。安装目录的原生源文件哈希保持不变。
+
+- 复制页中的渲染钩子不是现有 World API 的能力。正式接入需要 desktop-pet 或 Coopanion 增加受控接口。
+- 建议宿主接收声明式衣橱配置，由宿主校验 figure/scheme 并绘制控件；提供方失效时立即回退原 UI。
+- 资源选择继续由宿主外观接口保存，保留原生预览、其他角色与 Coo 配件。
+- 提供方注册、撤销、冲突优先级和当前角色作用域需要正式定义；不靠全局 DOM 注入或修改角色 manifest 接管界面。
+- 脚本检查原生源文件的三个明确锚点。源版本改变时会停止，需人工复核；这不是承诺所有宿主版本兼容的安装器。
+- prototypes 目录不在 npm 发布文件清单中。这里的开发原型不会随着当前插件包自动执行。

package/docs/native-integration.md

@@ -0,0 +1,53 @@
+# Native wardrobe compatibility · 0.4
+
+This is an **experimental, explicit opt-in compatibility patch**, disabled by default. It is not an official Coopanion World slot. The separate wardrobe and authoring guide remain available without it.
+
+## Behaviour
+
+For a figure with an imported profile, the native wardrobe shows outfits followed by the selected outfit's own controls. Missing combinations are disabled. Unconfigured figures and Coo retain their native controls. Preview, import, removal and theme stay with the original page.
+
+Native selections use the ordinary desktop-pet appearance API and remain selected when the extension is disabled. The separate panel's Apply button retains its own appearance lease/restoration behaviour. Do not operate both simultaneously.
+
+## Supported host
+
+Only the reviewed `cortico-world-desktop-pet@0.2.0` shipped with Coopanion 0.2.17, **and** this exact `web/dress.js` SHA-256, are supported:
+
+```text
+b594171051e90e4f368c635b4fd008405f6e41e6dfd3dbd907fdbffa767fbe9f
+```
+
+Matching the version number alone is insufficient. Unknown checksums are refused without patching.
+
+## Enable
+
+1. Install 0.4.0, restart Core as required and retain/import your local wardrobe profile.
+2. In Wardrobe Studio → Configuration, enter the absolute **web directory of the installed desktop-pet package**, not a figure directory. The extension does not scan the disk.
+3. Enable **Native wardrobe compatibility patch**. The loopback port defaults to `17891`; choose another 1024–65535 port if occupied. Save and restart this World.
+4. Check its native compatibility status lamp, then reopen the native wardrobe page to clear old module instances.
+5. Check outfit/part changes, missing combinations and unchanged controls on other figures.
+
+Before changing the directory or port, disable the World and verify rollback. Then edit configuration, reactivate and reopen the native page. Do not move or overwrite the application installation while the adapter runs.
+
+## Files and connection
+
+The extension writes a private write-ahead backup under its own `wardrobe-studio/native-adapter.json` before changing application files. Do not publish that record. Only three checked locations in `web/dress.js` and three `wardrobe-studio-*.js` helper modules are affected. No figure manifests, animation assets or other application files are modified.
+
+A read-only WebSocket server binds only to `127.0.0.1`. It sends profile metadata and language, verifies the exact desktop-page Origin plus a random token, and provides no commands, filesystem or appearance-writing RPCs. All HTTP requests return 404. CSP is not weakened; no internet scripts, dependencies or models are downloaded. Disconnection restores native rows; an abnormal stale connection has a roughly 6.5-second watchdog.
+
+## Disable, uninstall and recovery
+
+Normal stopping closes the feed, restores the original page only when its checksum still matches the owned patch, and removes only matching owned helpers. Stopping is idempotent. Reopen the native page to confirm the original layout before uninstalling.
+
+A forced process termination can leave the disk patch installed. Loaded pages fall back when the feed goes offline, and the next activation first recovers the previous patch. Disable normally and verify restoration before removing extension files.
+
+If Core cannot start, quit Coopanion first and use your existing Node.js to run the recovery tool inside the installed extension package:
+
+```sh
+node src/native-restore.js --data-dir "<World dataDir>" --web-dir "<desktop-pet/web>"
+```
+
+The data directory is the parent containing `wardrobe-studio`, not that subdirectory itself. The tool uses the private backup and refuses to overwrite externally changed pages or delete modified helpers. Preserve recovery records after a host upgrade and inspect the new official files before repairing; never overwrite an unknown new version with the old backup. Disable compatibility to continue using the separate panel.
+
+## Verification boundary
+
+Disposable tests cover rollback, repeated stopping, crash recovery, external changes, filename collisions and feed origin/token checks. Real-window acceptance is performed only with permission. Compatibility can break after a host update; this adapter does not claim a general official host hook.

package/docs/native-integration.zh.md

@@ -0,0 +1,57 @@
+# 原生装扮页兼容集成 · 0.4
+
+这是**默认关闭、显式启用的实验兼容补丁**，不是 Coopanion 正式提供的 World 插槽。独立衣橱与制作指导仍可照常使用。
+
+## 效果
+
+在原生「装扮」页选择已导入衣橱配置的角色后，完整搭配列表变成「服装 → 当前服装的部件」。缺少资源的组合禁用。无配置角色和 Coo 使用原有控件，预览、导入、删除及主题由原页面负责。
+
+在这里点击搭配是普通原生装扮选择，由桌宠标准接口保存；停用扩展只恢复原页面布局，保留这次选择。独立衣橱面板的「应用」仍使用其外观恢复机制，两者不要同时操作。
+
+## 支持版本
+
+仅支持已验收的 Coopanion 0.2.17 所带 `cortico-world-desktop-pet@0.2.0`，还必须匹配此 `web/dress.js` SHA-256：
+
+```text
+b594171051e90e4f368c635b4fd008405f6e41e6dfd3dbd907fdbffa767fbe9f
+```
+
+仅版本号相同不代表兼容。文件校验不符时不会修补，不会自动扩大支持范围。
+
+## 启用
+
+1. 安装 0.4.0，按宿主要求重启 Core，保留已经导入的衣橱配置。
+2. 打开「装扮工作室 → 配置」，填写 **desktop-pet 包的 web 绝对目录**。这是已安装 `cortico-world-desktop-pet` 下的 `web` 文件夹，不是角色素材目录。扩展不会搜索磁盘。
+3. 开启 **原生装扮页兼容补丁**；默认本机端口 `17891`。冲突时可指定另一个 1024–65535 端口。保存后重启此 World。
+4. 检查「原生页兼容」状态灯。成功后重新打开原生「装扮」页面；已经打开的页面可能仍缓存旧模块。
+5. 检查服装切换、该服装的部件、缺失组合禁用和其他角色的原有功能。
+
+修改路径或端口前，先停用 World 并确认回滚成功；修改配置后再启用并重新打开原生页。不要在补丁仍运行时移动安装目录或覆盖安装程序。
+
+## 写入与通信范围
+
+- 先在扩展自己的 `wardrobe-studio/native-adapter.json` 记录原始字节、校验值和恢复信息，再修改页面。此文件是私有本机记录，不要上传到公开仓库。
+- 只临时修改 `web/dress.js` 的三个已检查位置，另写入三个 `wardrobe-studio-*.js` 辅助模块。不会改其他程序文件、角色 manifest 或动画素材。
+- 开启一个仅监听 `127.0.0.1` 的**只读** WebSocket 接口，向原生页发送衣橱分组和语言。不提供命令、文件读取或外观写入 RPC。检查精确桌宠 Origin 和随机令牌；HTTP 路径一律返回 404。
+- 不放宽宿主 CSP，不载入外网脚本，不安装依赖或模型。
+- 提供方断开时回到原控件；异常失联由约 6.5 秒看门狗兜底。恢复连接后可以重新分组。配置内容变化不需要改写页面。
+
+## 停用、卸载与恢复
+
+正常停用先关闭只读接口，再按校验值恢复原始 `dress.js`，移除仍匹配本扩展校验值的辅助文件。重复停用是幂等的。重新打开原生页可确认恢复。最后再卸载扩展。
+
+若程序被强制结束，磁盘补丁可能暂留；接口离线后，已经加载的原生页会使用原控件。下次启用会先恢复上次补丁，再重新安装。卸载前应正常停用并确认恢复，不能仅删除扩展目录。
+
+若无法启动 Core，可先退出 Coopanion，使用已有 Node.js 执行已安装扩展包内的恢复工具：
+
+```sh
+node src/native-restore.js --data-dir "<World 的 dataDir>" --web-dir "<desktop-pet/web>"
+```
+
+`--data-dir` 是包含 `wardrobe-studio` 文件夹的父目录，不是该文件夹本身。工具只根据私有备份恢复已知原页，拒绝覆盖外部更新过的页面或删除外部修改的辅助文件。不要手动把未知文件当成原始备份。
+
+宿主升级后若出现「外部修改／回滚拒绝」，先保留私有恢复记录并检查更新后的官方文件，再决定是否需要修复或重新安装宿主；不要盲目用旧文件覆盖新版本。关闭此兼容选项后仍可使用独立面板。
+
+## 验证边界
+
+发布前必须在临时目录测试备份、回滚、重复停止、崩溃后恢复、外部改动保护、文件名冲突、接口 Origin/令牌拒绝；再经本人授权检查真实原生窗口。无需生成或改写人物素材。此兼容实现会随宿主更新失效，不代表已存在通用的官方接口。

package/docs/verification.md

@@ -1,4 +1,10 @@
-# Verification · package 0.3.0
+# Verification
+
+## Package 0.4.0
+
+Twenty-six isolated tests pass locally, including seven native-adapter tests for exact anchors, unknown-source refusal, backup/rollback and repeated stop, interrupted installation recovery, external page changes, helper collisions and read-only feed origin/token checks. Disposable original fixtures substitute for the host source only inside the tests; the production adapter requires the documented exact checksum. The 0.3 checks below remain relevant to the separate panel. The optional adapter has a narrow compatibility boundary, not general host API support.
+
+## Package 0.3.0
 
 The initial local checks ran on Windows with Node.js 26.3.1. No runtime dependency installation was required. The packaged World was also installed and activated in a real Coopanion 0.2.17/Core deployment with the person's permission.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-wardrobe-studio",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Outfit-specific wardrobe controls and a continuous-animation authoring guide for Coopanion figure packs.",
   "license": "MIT",
@@ -35,7 +35,8 @@
     "README.md",
     "README_zh.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "README.en.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",

package/src/index.js

@@ -3,9 +3,10 @@ import {PetBridge,AppearanceLease,localBase} from './bridge.js';
 import {validateProfile,validateAgainstPack,outfitOf,selectVariant} from './profile.js';
 import {authoringGuide} from './guide.js';
 import {TOOL_SPECS,DESCRIBE} from './tools.js';
+import {NativeAdapter} from './native-adapter.js';
 import profileExample from '../examples/forest-fox.profile.json' with {type:'json'};
 import profileSchema from '../docs/wardrobe-profile.schema.json' with {type:'json'};
-export const DEFAULTS=Object.freeze({enabled:false,desktopPetUrl:'http://127.0.0.1:7797'});
+export const DEFAULTS=Object.freeze({enabled:false,desktopPetUrl:'http://127.0.0.1:7797',nativeIntegration:false,nativeWebDir:'',nativePort:17891});
 const appearance=s=>({figure:s.figure,scheme:s.scheme});
 export class WardrobeWorld{
   id='wardrobe-studio';
@@ -14,9 +15,14 @@ export class WardrobeWorld{
   async start(host){
     this.host=host;this.profiles=(await this.store.read('profiles.json',[])).map(validateProfile);this.language=(await this.store.read('preferences.json',{}))?.language==='en'?'en':'zh';this.started=true;
     try{this.restoration=await this.lease.restore();}catch(e){this.error=String(e.message);}
+    if(this.ctx.cfg.nativeIntegration){
+      this.native=new NativeAdapter({webDir:this.ctx.cfg.nativeWebDir,store:this.store,origin:this.bridge.base,port:this.ctx.cfg.nativePort??17891,snapshot:()=>({contract:1,enabled:this.started,language:this.language,profiles:this.profiles})});
+      try{await this.native.start();}catch(e){this.native.status={state:'error',error:String(e.message)};this.host?.log?.warn?.('Native wardrobe compatibility adapter is off; see its panel status');}
+    }
   }
   async stop(){
     this.started=false;
+    try{await this.native?.stop();}catch(e){this.native.status={state:'error',error:String(e.message)};this.host?.log?.warn?.('Native wardrobe rollback requires attention');}
     await this.serial(async()=>{try{this.restoration=await this.lease.restore();this.error=null;}catch(e){this.error=String(e.message);this.host?.log?.warn?.('Wardrobe appearance restoration requires attention');}});
   }
   envPromptVars(){return null;}
@@ -32,12 +38,12 @@ export class WardrobeWorld{
   async state(){
     let packs=[],current=null,connectionError=null;
     try{packs=(await this.bridge.packs()).filter(p=>p.id!=='coo').map(p=>({id:p.id,name:p.name,axes:p.axes,presets:p.presets??[]}));current=appearance(await this.bridge.skin());}catch(e){connectionError=String(e.message);}
-    return{profiles:this.profiles,packs,current,desktopPetUrl:this.bridge.base,connected:!connectionError,error:connectionError??this.error,lease:await this.store.read('lease.json',null),restoration:this.restoration};
+    return{profiles:this.profiles,packs,current,desktopPetUrl:this.bridge.base,connected:!connectionError,error:connectionError??this.error,lease:await this.store.read('lease.json',null),restoration:this.restoration,nativeIntegration:this.native?.status??{state:'off'}};
   }
   async importProfile(raw){return this.serial(async()=>{
     if(!this.started)throw Error('Wardrobe World is not active');
     const profile=validateProfile(raw);await this.bridge.validate(profile);
-    const next=this.profiles.filter(p=>p.id!==profile.id);next.push(profile);await this.store.write('profiles.json',next);this.profiles=next;return profile;
+    const next=this.profiles.filter(p=>p.id!==profile.id);next.push(profile);await this.store.write('profiles.json',next);this.profiles=next;this.native?.broadcast();return profile;
   });}
   async checkProfile(raw){
     const p=validateProfile(raw);await this.bridge.validate(p);
@@ -46,11 +52,11 @@ export class WardrobeWorld{
   async setLanguage(language){return this.serial(async()=>{
     if(!this.started)throw Error('Wardrobe World is not active');
     if(!['zh','en'].includes(language))throw Error('Unsupported wardrobe language');
-    await this.store.write('preferences.json',{language});this.language=language;return{language};
+    await this.store.write('preferences.json',{language});this.language=language;this.native?.broadcast();return{language};
   });}
   async removeProfile(id){return this.serial(async()=>{
     if(!this.started)throw Error('Wardrobe World is not active');
-    const next=this.profiles.filter(p=>p.id!==id);await this.store.write('profiles.json',next);this.profiles=next;return{removed:id};
+    const next=this.profiles.filter(p=>p.id!==id);await this.store.write('profiles.json',next);this.profiles=next;this.native?.broadcast();return{removed:id};
   });}
   async choose({profile:id,outfit,pick={}}){return this.serial(async()=>{
     if(!this.started)throw Error('Wardrobe World is not active');
@@ -69,7 +75,7 @@ export class WardrobeWorld{
   webUi(language='zh'){
     const zh=this.language!=='en';
     return{label:zh?'装扮工作室':'Wardrobe Studio',panels:[{id:'wardrobe',title:zh?'衣橱':'Wardrobe'},{id:'guide',title:zh?'角色制作指导':'Authoring guide'}],
-      lamps:[{label:zh?'外观恢复':'Appearance restoration',state:this.error?'error':'online',hint:this.error??(zh?'角色包文件保持不变':'Figure pack files remain unchanged')}],
+      lamps:[{label:zh?'外观恢复':'Appearance restoration',state:this.error?'error':'online',hint:this.error??(zh?'角色包文件保持不变':'Figure pack files remain unchanged')},{label:zh?'原生页兼容':'Native compatibility',state:this.native?.status.state==='error'?'error':this.native?.status.state==='active'?'online':'offline',hint:this.native?.status.error??(this.native?.status.state==='active'?(zh?'已接入原生装扮页；停用时回滚补丁':'Native wardrobe connected; stopping restores the patch'):(zh?'未启用原生页兼容补丁':'Native compatibility patch is off'))}],
       invoke:async(panel,method,args)=>{
         if((panel==='guide'||panel==='wardrobe')&&method==='locale')return{language:this.language};
         if((panel==='guide'||panel==='wardrobe')&&method==='setLanguage')return this.setLanguage(args[0]);
@@ -87,9 +93,9 @@ export class WardrobeWorld{
         if(method==='restore')return this.restore();
         throw Error('Unknown wardrobe method');
       },
-      config:[{id:'world:wardrobe-studio',owner:'world:wardrobe-studio',schema:{type:'object',title:zh?'桌宠连接':'Desktop pet connection',properties:{'worlds.wardrobe-studio.desktopPetUrl':{type:'string',title:zh?'本机桌宠地址':'Local desktop pet address',description:zh?'修改后重启此 World。只接受本机 HTTP 地址。':'Restart this World after changing the loopback HTTP origin.','x-hot':false}}}}]
+      config:[{id:'world:wardrobe-studio',owner:'world:wardrobe-studio',schema:{type:'object',title:zh?'桌宠与原生页兼容':'Desktop pet and native compatibility',properties:{'worlds.wardrobe-studio.desktopPetUrl':{type:'string',title:zh?'本机桌宠地址':'Local desktop pet address',description:zh?'修改后重启此 World。只接受本机 HTTP 地址。':'Restart this World after changing the loopback HTTP origin.','x-hot':false},'worlds.wardrobe-studio.nativeIntegration':{type:'boolean',title:zh?'启用原生装扮页兼容补丁':'Enable native wardrobe compatibility patch',description:zh?'实验功能，会备份并临时修改指定桌宠包的装扮页面。停用 World 时恢复。修改后重启此 World。':'Experimental: backs up and temporarily patches the specified native wardrobe page. Stopping restores it. Restart this World after changes.','x-hot':false},'worlds.wardrobe-studio.nativeWebDir':{type:'string',title:zh?'desktop-pet 包的 web 绝对目录':'Absolute desktop-pet web directory',description:zh?'仅支持已校验版本；留空不自动搜索磁盘。修改后重启此 World。':'Only the verified version is supported; an empty path does not scan the disk. Restart this World after changes.','x-hot':false},'worlds.wardrobe-studio.nativePort':{type:'integer',minimum:1024,maximum:65535,title:zh?'兼容接口本机端口':'Compatibility loopback port','x-hot':false}}}}]
     };
   }
-  shutdownVerification(){return[{key:'appearance',label:'Wardrobe appearance',status:this.error?'unknown':'verified-ended',detail:this.error??this.restoration?.status??'unchanged',manualAction:this.error?'Enable Wardrobe Studio and use Restore after the desktop pet is available.':''}];}
+  shutdownVerification(){return[{key:'appearance',label:'Wardrobe appearance',status:this.error?'unknown':'verified-ended',detail:this.error??this.restoration?.status??'unchanged',manualAction:this.error?'Enable Wardrobe Studio and use Restore after the desktop pet is available.':''},{key:'native-adapter',label:'Native wardrobe patch',status:this.native?.status.state==='error'?'unknown':'verified-ended',detail:this.native?.status.error??this.native?.status.state??'off',manualAction:this.native?.status.state==='error'?'Read the native integration recovery guide before uninstalling.':''}];}
 }
-export default {id:'wardrobe-studio',label:'Wardrobe Studio',defaults:()=>({...DEFAULTS}),preflight:ctx=>{localBase(ctx.cfg.desktopPetUrl);},create:ctx=>new WardrobeWorld(ctx),describe:DESCRIBE};
+export default {id:'wardrobe-studio',label:'Wardrobe Studio',defaults:()=>({...DEFAULTS}),preflight:ctx=>{localBase(ctx.cfg.desktopPetUrl);if(ctx.cfg.nativeIntegration&&(!Number.isInteger(ctx.cfg.nativePort??17891)||(ctx.cfg.nativePort??17891)<1024||(ctx.cfg.nativePort??17891)>65535))throw Error('Native compatibility port must be between 1024 and 65535');},create:ctx=>new WardrobeWorld(ctx),describe:DESCRIBE};

package/src/native-adapter.js

@@ -0,0 +1,56 @@
+import {readFile,writeFile,rename,realpath,unlink,mkdir} from 'node:fs/promises';
+import {join,dirname,basename,isAbsolute} from 'node:path';
+import {createHash,randomBytes,randomUUID} from 'node:crypto';
+import {NativeFeed} from './native-feed.js';
+export const SUPPORTED_DRESS_SHA256='b594171051e90e4f368c635b4fd008405f6e41e6dfd3dbd907fdbffa767fbe9f';
+const hash=data=>createHash('sha256').update(data).digest('hex');
+const MAIN='dress.js',FILES=['wardrobe-studio-controls.js','wardrobe-studio-profile.js','wardrobe-studio-native.js'];
+const readMaybe=async file=>{try{return await readFile(file);}catch(e){if(e.code==='ENOENT')return null;throw e;}};
+async function atomic(file,bytes){const tmp=file+'.'+randomUUID()+'.tmp';try{await writeFile(tmp,bytes,{flag:'wx',mode:0o600});await rename(tmp,file);}finally{await unlink(tmp).catch(e=>{if(e.code!=='ENOENT')throw e;});}}
+export function patchDress(source){
+  const edits=[
+    ["import { ICONS, themeButton } from './ui.js';","import { ICONS, themeButton } from './ui.js';\nimport {nativeWardrobe as wardrobe} from './wardrobe-studio-native.js';"],
+    ['  const picks = picksOf(pack, skin.scheme);','  if (wardrobe.render({pack,skin,after:box,apply,language:language()})) return;\n  const picks = picksOf(pack, skin.scheme);'],
+    ['void ready.then(() => { connect(); apply(skin, false); });',"wardrobe.onChange(() => render());\nvoid ready.then(() => { connect(); apply(skin, false); });"]
+  ];
+  for(const [before,after] of edits){if(source.split(before).length!==2)throw Error('Unsupported native wardrobe source anchors');source=source.replace(before,after);}return source;
+}
+/** Explicit opt-in compatibility adapter, not an official World API hook. */
+export class NativeAdapter{
+  constructor({webDir,store,origin,port=17891,snapshot}){this.webDir=webDir;this.store=store;this.origin=origin;this.port=port;this.snapshot=snapshot;this.status={state:'off'};}
+  async readRecord(){const bytes=await readMaybe(join(this.store.root,'native-adapter.json'));return bytes?JSON.parse(bytes):null;}
+  async saveRecord(record){await mkdir(this.store.root,{recursive:true});await atomic(join(this.store.root,'native-adapter.json'),JSON.stringify(record,null,2)+'\n');}
+  verifyOriginal(bytes){if(hash(bytes)!==SUPPORTED_DRESS_SHA256)throw Error('Unsupported dress.js checksum; native integration left off');}
+  async start(){
+    if(!isAbsolute(this.webDir))throw Error('Native web directory must be an explicit absolute path');
+    const web=await realpath(this.webDir),meta=JSON.parse(await readFile(join(dirname(web),'package.json'),'utf8'));
+    if(basename(web)!=='web'||meta.name!=='cortico-world-desktop-pet'||meta.version!=='0.2.0')throw Error('Unsupported desktop-pet package; native integration left off');
+    this.web=web;let record=await this.readRecord();
+    if(record){if(record.web!==web)throw Error('Restore the previous native adapter before changing its directory');await this.restoreFiles(record);}
+    const original=await readFile(join(web,MAIN));this.verifyOriginal(original);
+    const token=record?.token??randomBytes(32).toString('hex');
+    this.feed=new NativeFeed({origin:this.origin,token,port:this.port,snapshot:this.snapshot});await this.feed.start();
+    try{
+      const controls=(await readFile(new URL('../web/native-controls.js',import.meta.url),'utf8')).replace("'./profile.js'","'./wardrobe-studio-profile.js'");
+      const client=(await readFile(new URL('../web/native-client.js',import.meta.url),'utf8')).replace("'./native-controls.js'","'./wardrobe-studio-controls.js'").replace('__WARDROBE_SOCKET__',`ws://127.0.0.1:${this.feed.port}/wardrobe-view?key=${token}`);
+      const payloads={[MAIN]:Buffer.from(patchDress(original.toString('utf8'))),[FILES[0]]:Buffer.from(controls),[FILES[1]]:await readFile(new URL('./profile.js',import.meta.url)),[FILES[2]]:Buffer.from(client)};
+      for(const name of FILES)if(await readMaybe(join(web,name)))throw Error('Native adapter helper filename already exists');
+      record={contract:1,web,token,original:original.toString('base64'),originalHash:hash(original),patchedHash:hash(payloads[MAIN]),files:Object.fromEntries(FILES.map(name=>[name,hash(payloads[name])]))};
+      // Write-ahead recovery record precedes every application-file mutation.
+      await this.saveRecord(record);
+      for(const name of FILES)await atomic(join(web,name),payloads[name]);
+      if(hash(await readFile(join(web,MAIN)))!==record.originalHash)throw Error('Native page changed during installation');
+      await atomic(join(web,MAIN),payloads[MAIN]);this.status={state:'active',compatibility:'desktop-pet 0.2.0 / verified dress.js',port:this.feed.port};
+    }catch(error){await this.feed.stop();if(record)await this.restoreFiles(record);throw error;}
+  }
+  async restoreFiles(record){
+    if(record.web!==await realpath(this.webDir)||record.contract!==1||hash(Buffer.from(record.original,'base64'))!==record.originalHash)throw Error('Invalid native adapter backup');
+    this.verifyOriginal(Buffer.from(record.original,'base64'));
+    const file=join(record.web,MAIN),current=await readFile(file),currentHash=hash(current);
+    if(currentHash===record.patchedHash)await atomic(file,Buffer.from(record.original,'base64'));
+    else if(currentHash!==record.originalHash)throw Error('Native page changed externally; automatic rollback refused');
+    for(const name of FILES){const bytes=await readMaybe(join(record.web,name));if(bytes&&hash(bytes)===record.files[name])await unlink(join(record.web,name));else if(bytes)throw Error('Native helper changed externally; automatic deletion refused');}
+  }
+  async stop(){await this.feed?.stop();const record=await this.readRecord();if(record)await this.restoreFiles(record);this.status={state:'off',restored:true};}
+  broadcast(){this.feed?.broadcast();}
+}

package/src/native-feed.js

@@ -0,0 +1,32 @@
+import {createServer} from 'node:http';
+import {createHash,timingSafeEqual} from 'node:crypto';
+
+/** Read-only, origin-checked loopback feed. No command or filesystem RPCs. */
+export class NativeFeed {
+  constructor({origin,token,port=17891,snapshot}){this.origin=origin;this.token=token;this.port=port;this.snapshot=snapshot;this.clients=new Set();}
+  async start(){
+    const server=this.server=createServer((_req,res)=>res.writeHead(404).end());
+    server.headersTimeout=3000;
+    server.on('upgrade',(req,socket,head)=>{
+      const reject=()=>{socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');};
+      const key=req.headers['sec-websocket-key'];let url;try{url=new URL(req.url,'http://127.0.0.1');}catch{return reject();}
+      const supplied=Buffer.from(url.searchParams.get('key')??''),expected=Buffer.from(this.token);
+      if(req.headers.origin!==this.origin||req.headers.host!==`127.0.0.1:${this.port}`||url.pathname!=='/wardrobe-view'||supplied.length!==expected.length||!timingSafeEqual(supplied,expected)||req.headers['sec-websocket-version']!=='13'||typeof key!=='string'||!/^[A-Za-z0-9+/]{22}==$/.test(key)||head.length)return reject();
+      const accept=createHash('sha1').update(key+'258EAFA5-E914-47DA-95CA-C5AB0DC85B11').digest('base64');
+      socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+      this.clients.add(socket);socket.on('error',()=>{});socket.on('close',()=>this.clients.delete(socket));
+      // Clients never send commands; even unsolicited application frames close the connection.
+      socket.on('data',()=>socket.destroy());this.send(socket);
+    });
+    await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(this.port,'127.0.0.1',()=>{server.off('error',reject);this.port=server.address().port;resolve();});});
+    this.timer=setInterval(()=>this.broadcast(),2000);this.timer.unref();
+  }
+  send(socket){
+    let body;try{body=Buffer.from(JSON.stringify(this.snapshot()));}catch{socket.destroy();return;}
+    if(body.length>1024*1024||socket.writableLength>2*1024*1024){socket.destroy();return;}
+    let header;if(body.length<126)header=Buffer.from([0x81,body.length]);else if(body.length<65536){header=Buffer.alloc(4);header[0]=0x81;header[1]=126;header.writeUInt16BE(body.length,2);}else{header=Buffer.alloc(10);header[0]=0x81;header[1]=127;header.writeBigUInt64BE(BigInt(body.length),2);}
+    socket.write(Buffer.concat([header,body]));
+  }
+  broadcast(){for(const socket of this.clients)this.send(socket);}
+  async stop(){clearInterval(this.timer);for(const s of this.clients)s.destroy();this.clients.clear();if(this.server?.listening)await new Promise(resolve=>this.server.close(resolve));}
+}

package/src/native-restore.js

@@ -0,0 +1,9 @@
+import {NativeAdapter} from './native-adapter.js';
+import {Store} from './store.js';
+const args=process.argv.slice(2);
+if(args.length!==4||args[0]!=='--data-dir'||args[2]!=='--web-dir'){
+  console.error('Usage: node src/native-restore.js --data-dir <World dataDir> --web-dir <desktop-pet/web>');process.exitCode=1;
+}else{
+  try{await new NativeAdapter({webDir:args[3],store:new Store(args[1])}).stop();console.log('Native adapter files restored; reopen the native wardrobe page.');}
+  catch(error){console.error(error.message);process.exitCode=1;}
+}

package/web/native-client.js

@@ -0,0 +1,22 @@
+import {createWardrobeControls} from './native-controls.js';
+let snapshot={enabled:false,profiles:[]},changed=()=>{},socket,retry,watchdog,closed=false,last='';
+export const nativeWardrobe=createWardrobeControls({load:async()=>snapshot,onChange:()=>changed()});
+nativeWardrobe.onChange=fn=>{changed=fn;};
+const render=nativeWardrobe.render;
+nativeWardrobe.render=args=>render({...args,language:snapshot.language??'zh'});
+function accept(next){
+  snapshot=next;const value=JSON.stringify(next);
+  if(value!==last){last=value;void nativeWardrobe.refresh();}
+}
+function offline(){clearTimeout(watchdog);accept({enabled:false,profiles:[]});}
+function connect(){
+  if(closed)return;
+  socket=new WebSocket('__WARDROBE_SOCKET__');
+  socket.onmessage=e=>{
+    try{if(typeof e.data!=='string'||e.data.length>1024*1024)throw Error('Invalid provider frame');const next=JSON.parse(e.data);if(next.contract!==1||next.enabled!==true||!Array.isArray(next.profiles))throw Error('Invalid provider');accept(next);clearTimeout(watchdog);watchdog=setTimeout(()=>{offline();socket.close();},6500);}catch{offline();socket.close();}
+  };
+  socket.onerror=()=>socket.close();
+  socket.onclose=()=>{offline();if(!closed)retry=setTimeout(connect,2000);};
+}
+connect();
+addEventListener('pagehide',()=>{closed=true;clearTimeout(retry);clearTimeout(watchdog);socket?.close();},{once:true});

package/web/native-controls.js

@@ -0,0 +1,43 @@
+import {validateProfile,validateAgainstPack,selectVariant,availableOptions} from './profile.js';
+
+/** Compatibility rendering hook, restricted to the native outfit rows. */
+export function createWardrobeControls({load,onChange,onError}){
+ let provider={enabled:false,profiles:[]},request=0;
+ return{
+  async refresh(){
+   const epoch=++request;
+   try{const next=await load();if(epoch!==request)return;provider={enabled:next.enabled===true,profiles:(next.profiles??[]).map(validateProfile)};}
+   catch(error){if(epoch!==request)return;provider={enabled:false,profiles:[]};onError?.(error);}
+   onChange();
+  },
+  render({pack,skin,after,apply,language='zh'}){
+   if(!provider.enabled||pack.id==='coo')return false;
+   const profile=provider.profiles.find(p=>p.figure===pack.id);if(!profile)return false;
+   try{validateAgainstPack(profile,pack);}catch(error){onError?.(error);return false;}
+   const outfit=profile.outfits.find(o=>o.variants.some(v=>v.scheme===skin.scheme))??profile.outfits[0];
+   const active=outfit.variants.find(v=>v.scheme===skin.scheme)??selectVariant(outfit);
+   const doc=after.ownerDocument,el=(tag,cls,text)=>{const e=doc.createElement(tag);e.className=cls;if(text!==undefined)e.textContent=text;return e;};
+   let cursor=after;
+   function row(id,label,choices){
+    const title=el('div','row-label pack-axis',label),slot=el('div','slot pack-axis'),list=el('div','opts');title.id='wardrobe-'+id;slot.setAttribute('role','group');slot.setAttribute('aria-labelledby',title.id);
+    for(const choice of choices){
+     const button=el('button','opt wide');button.type='button';button.setAttribute('aria-pressed',String(choice.selected));button.disabled=!!choice.disabled;
+     if(choice.disabled)button.title=language==='en'?'No complete resources for this combination':'此搭配暂无完整资源';
+     if(choice.thumb){const image=el('img','');image.alt='';image.src=pack.base+choice.thumb;button.append(image);}
+     button.append(el('span','',choice.label));button.addEventListener('click',()=>{if(!button.disabled)apply({...skin,scheme:choice.scheme},true);});list.append(button);
+    }
+    slot.append(list);cursor.after(title,slot);cursor=slot;
+   }
+   const thumb=scheme=>{
+    const preset=pack.presets?.find(p=>p.id===scheme),parts=scheme.split('-');
+    return [...pack.axes].reverse().map((a,j)=>a.options.find(o=>o.id===(preset?.pick[a.id]??parts[pack.axes.length-1-j]))?.thumb).find(Boolean)??pack.thumb;
+   };
+   row('outfit',language==='en'?'Outfit':'服装',profile.outfits.map(o=>{const v=o.id===outfit.id?active:selectVariant(o);return{label:o.label,selected:o.id===outfit.id,thumb:thumb(v.scheme),scheme:v.scheme};}));
+   for(const control of outfit.controls){const valid=new Set(availableOptions(outfit,active.pick,control.id).map(o=>o.id));
+    row(control.id,control.label,control.options.map(option=>({label:option.label,selected:active.pick[control.id]===option.id,disabled:!valid.has(option.id),scheme:valid.has(option.id)?selectVariant(outfit,{...active.pick,[control.id]:option.id}).scheme:skin.scheme})));
+   }
+   return true;
+  }
+ };
+}
+