feat(theme): define a versioned portable contract

[rwang23]

Summary / 摘要

中文

• 新增机器可读的 Theme v1 JSON Schema，明确 schemaVersion、image、id、name、appearance 与 art 的跨平台核心语义，同时为平台扩展和社区元数据保留兼容空间。
• 统一 macOS 与 Windows 加载器的版本、文件名、文本、外观和构图校验；旧版无版本主题继续按 v1 读取，新建或重新保存的主题写入 schemaVersion: 1，无效类型和未来版本直接拒绝。
• 增加两端共用的有效/无效夹具矩阵和规范化结果比对，并让所有内置主题与预设同时通过两个加载器，避免平台行为继续漂移。
• 将契约测试接入 CI，并同步 macOS、Windows 与跨平台创作说明和 changelog，让贡献者能从同一份规范扩展主题。

English

• Add a machine-readable Theme v1 JSON Schema for the portable schemaVersion, image, id, name, appearance, and art core while preserving a safe extension seam for platform and community metadata.
• Align macOS and Windows loader semantics for versions, filenames, text, appearance, and composition. Legacy unversioned themes remain readable as v1; new or rewritten themes emit schemaVersion: 1; invalid types and future versions fail closed.
• Add one shared valid/invalid fixture matrix with normalized cross-loader comparisons, then verify every bundled theme and preset through both loaders to prevent platform drift.
• Run the contract suite in CI and update the macOS, Windows, and cross-platform authoring guidance and changelogs around the same source of truth.

Closes #63

Type / 类型

• Bug fix / 缺陷修复
• Feature / 新功能
• Docs / 文档
• Theme / CSS / visual / 主题或视觉
• Scripts / install / restore / 脚本或安装恢复
• Chore / 杂项

Platform / 平台

• macOS
• Windows
• Both / 双平台
• Docs / repo only / 仅文档或仓库元数据

Self-check / 自测

Check what you actually ran. Skip items that do not apply and say so under Notes.
请勾选实际跑过的项；不适用的在 Notes 说明。

Docs-only / 仅文档

• Links and wording reviewed / 已检查链接与表述

macOS (when code under macos/ changes)

• macos/tests/run-tests.sh passed / 已通过
• Doctor (optional): macos/scripts/doctor-macos.sh
• Live verify (if inject/CSS/start path): verify-dream-skin-macos.sh or Desktop Verify
• Restore / re-apply smoke (if install/restore/start changed) / 若改了安装恢复启动则做过恢复再应用

Windows (when code under windows/ changes)

• Relevant install / start / verify / restore scripts exercised / 已按改动跑过对应脚本
• Environment noted below (OS build, Codex source) / 下方注明环境

User-facing / 用户可见变更

• Updated macos/CHANGELOG.md (and macos/VERSION if release-worthy) / 已更新 changelog（发版时再 bump VERSION）
• N/A — no user-facing change / 无用户可见变更

Security / 安全

• Does not modify official Codex install / asar / signatures / 未修改官方安装与签名
• Does not silently write API Base URL or keys / 未静默写入 API Base URL 或 Key
• CDP remains loopback-oriented (127.0.0.1) where applicable / CDP 仍仅本机回环（如适用）

Notes / 补充

中文

• 共享契约套件通过 33/33，覆盖 22 组有效/无效主题和 8 个内置主题/预设；另用 Draft 2020-12 校验器核对了 21 组非旧版夹具与全部 8 个内置描述文件。
• Windows PowerShell 5.1 与 PowerShell 7 的完整回归套件均通过；macOS/Windows 共 7 个现有 Node 回归文件通过。Node 24/Linux 也通过共享契约与 macOS staging 回归。
• macOS 侧的改动只涉及主题读取与 staging 契约，不改变安装、启动、实时注入或恢复流程；Windows 侧新增了旧版读取、未来版本拒绝、精确小写版本写回和保留设备名拒绝测试。
• 兼容策略是“读取时迁移、写入时规范化”：完全缺少 schemaVersion 的旧描述文件按 v1 读取，但显式 null、字符串 "1" 和不支持的未来版本不会被猜测接受。未知 v1 字段由可移植核心忽略，平台已识别的扩展仍由各自适配器处理。
• 环境：Windows 11 Home 10.0.26200（Build 26200），Node.js v24.15.0，Windows PowerShell 5.1.26100.8875，PowerShell 7.6.3；Codex 来源为官方 Windows 桌面发行版，回归使用仓库夹具和隔离临时状态。
• 提交基于上游 main 的 a1c48b3，实现集中在一个提交中；没有新增运行时依赖，也没有改变 CDP 边界、API 配置或官方安装文件。

English

• The shared contract suite passes 33/33, covering 22 valid/invalid theme cases and 8 bundled themes/presets. A Draft 2020-12 validator also matches all 21 non-legacy fixture outcomes and accepts all 8 bundled descriptors.
• The full Windows regression suite passes under both Windows PowerShell 5.1 and PowerShell 7, and all 7 existing macOS/Windows Node regression files pass. Node 24 on Linux also passes the shared contract and macOS staging regression.
• The macOS changes are limited to the theme-loading and staging contract; install, launch, live-injection, and restore behavior are unchanged. Windows adds focused coverage for legacy reads, future-version rejection, exact lowercase version writeback, and reserved device-name rejection.
• Compatibility follows a read-migrate/write-normalize policy: a descriptor with no schemaVersion is read as v1, while explicit null, string "1", and unsupported future versions are never guessed into compatibility. Unknown v1 fields are ignored by the portable core, and recognized platform extensions remain owned by their local adapters.
• Environment: Windows 11 Home 10.0.26200 (Build 26200), Node.js v24.15.0, Windows PowerShell 5.1.26100.8875, and PowerShell 7.6.3. Codex source: the official Windows desktop distribution; regressions use repository fixtures and isolated temporary state.
• The change is based on upstream main at a1c48b3 and kept in one commit. It adds no runtime dependency and does not alter the CDP boundary, API configuration, or official installation files.

[Fei-Away]

Thanks for this! This overlaps heavily with #99 — closing both together since they cover the same ground (and both predate the #216 runtime unification anyway). Appreciate the effort here!

感谢！这个和 #99 内容高度重合，两个一起关闭（而且都早于 #216 的 runtime 统一）。谢谢你的付出！