@linxin666/dsh-pet 0.2.3 → 0.2.4

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   node scripts/verify-docs.mjs --write <dir>
-README.md: 9470df0da7fc9b8cdf0c3816d792a842f17a769c
-README.zh.md: 76fa58171d7c49d04da4e6663d7010e6662408e4
+README.md: a0adc3fe2cb2767a8e372ed32cec6e8f7bb74660
+README.zh.md: e048ab6aece36283648b95ceddf705b3c6783f7e

package/README.md

@@ -26,6 +26,7 @@ Re-implemented from the pet feature of the Codex desktop app, as an official DSH
 | Status bubbles | Only the most recently active top-level session speaks by default — when several sessions run at once, the rest collapse behind a +N badge on the main bubble instead of stacking a tall column; hover the bubble (or tap the badge, for touch) to fan every session's bubble out above it and click one to jump to its session; subagent sessions report through their spawning conversation and never occupy a bubble of their own; transient interaction feedback temporarily takes priority. Bubble copy comes from generous rotating pools per scene (waiting / thinking / writing / done / failed...), tool calls map onto per-family witty lines carrying the real argument hint (e.g. 跑跑 npm test), and a long-lived scene re-phrases itself every few seconds |
 | Inner whispers | 碎碎念: while the model streams, the pet occasionally speaks its inner voice through its own bubble — a fresh whisper takes over the display session's bubble and marks it with 「」 quotes — sharing the same DeepSeek-blue glass as every status bubble, so stacked bubbles never clash — instead of stacking a second bubble — keyword moods woken by the model output (errors, test greens, plans, victories...) plus ambient whispers earned by output volume; paced by a cooldown, the status copy returns after a few seconds |
 | Multi-session activity | The pet is host-global: the most recent meaningful event drives the sprite animation while every active top-level session reports its own state in a separate bubble; completed turns from every session (subagents included) contribute affinity and treats |
+| Voice packs and panel DIY | A per-pet voice.json plus the global $DSH_HOME/pets/.voice.json override replace every bubble word and the hover panel (button labels, stat formats, button visibility); merge precedence per-pet > global > built-in, broken packs warn and never reject a pet |
 
 ## Pet contract
 
@@ -80,13 +81,47 @@ Where pets come from (later sources override earlier ones on id collision):
 Validate and install a pet directory with the CLI (no build step, no npm publish):
 
 ```sh
-node scripts/dsh-pet validate <dir>           # manifest + assets + Live2D reference closure
+node scripts/dsh-pet validate <dir>           # manifest + assets + Live2D reference closure + voice.json
 node scripts/dsh-pet install <dir>            # validate, then copy into $DSH_HOME/pets/<id>/
 node scripts/dsh-pet install <dir> --force    # overwrite an existing same-id install
 ```
 
 Invalid entries never override a working pet: they are skipped with a diagnostic listed in the settings (Pet section). The registry is built once at host startup; add or change a pet, then restart `dsh web`.
 
+## Voice packs and panel chrome (voice.json, pet-center M4, #677)
+
+Every word in the thought bubble (status / tool / whisper copy) and the hover panel (button labels, stat formats, button visibility) can be replaced by a pet — or by you — without touching plugin code. Pets ship an optional voice.json in their directory; a global override at $DSH_HOME/pets/.voice.json re-voices pets without editing their directories.
+
+```jsonc
+{
+  "voicePackVersion": 1,              // optional; absent reads as v1
+  "status": {                          // status pools keyed by scene id; per-key override
+    "done": ["Done for today!", "Another one down"]
+  },
+  "tools": {                           // tool pools keyed by tool family; {tool} / {hint} allowed
+    "shell": ["Running {hint}", "Hit enter: {hint}"]
+  },
+  "toolRemaining": ["{n} helpers still at work"],   // {n} allowed
+  "whispers": {                        // murmur pools; each section replaces the built-in one
+    "generic": ["On it", "Almost there"],  // ambient pool; an explicit empty array mutes it
+    "rules": [                         // ordered keyword rules; given rules replace the built-ins
+      { "keywords": ["all tests pass"], "pool": ["All green!"] }
+    ]
+  },
+  "panel": {                           // hover panel; unset slots keep the plugin i18n copy
+    "labels": { "feed": "Treat", "hide": "Dive", "rename": "Rename me", "confirm": "Sure" },
+    "stats": { "rank": "Affinity {rank}", "treats": "Treats x{n}", "points": "{points} pts" },
+    "actions": ["feed", "rename", "hide"]  // subset in canonical order; absent = all; [] = stats only
+  }
+}
+```
+
+- Merge precedence (per slot): the pet voice.json > the global .voice.json > built-in copy. status/tools merge per key, whispers replace per section, panel merges per slot; any slot a layer misses falls through.
+- Placeholder whitelist: tools accept {tool} / {hint}; toolRemaining accepts {n}; panel.stats accept {rank} / {n} / {points}; status, whisper and panel-label lines accept no placeholders (lines carrying one are dropped with a warning).
+- Caps (warn-and-drop): at most 64 lines per pool and 160 characters per line; at most 32 rules and 16 keywords (40 characters) per rule; panel labels 40 and stats 80 characters.
+- A broken pack never breaks the pet: voice.json that is not valid JSON or whose root is not an object is ignored with a warning; every other issue drops its slot only. Diagnostics appear under Settings > Pet directory diagnostics. node scripts/dsh-pet validate <dir> fails installs on structure errors and lists content issues as warnings.
+- Semantics: an empty status/tools pool falls back to the built-in copy (a scene line always renders); an explicit empty whisper pool mutes that channel; an empty panel actions array hides all three buttons; uncovered buttons and stats keep the plugin bilingual dictionary.
+
 ## Live2D pets (renderer: live2d)
 
 Live2D pets render through PixiJS/WebGL: the MIT pixi.js + untitled-pixi-live2d-engine stack ships inside this plugin as a lazily loaded vendor bundle, so sprite-only installations never download or parse it. **The Cubism Core runtime is never bundled or downloaded by this plugin** — Live2D's proprietary license forbids redistributing it. To enable a Live2D pet:
@@ -122,6 +157,34 @@ A Live2D manifest maps the seven activity phases onto the model's motion groups:
 
 Model licensing: the official Live2D sample models (Hiyori, Haru, and friends) are evaluation-only and must not be redistributed — ship only models you have rights to (original creations or permissively licensed ones).
 
+## Status decorations (decoration.json, pet-center M5, #567)
+
+A status bubble can carry a small ornament ahead of its text (built-in: the spouting whale), driven by the ActivityPhase stream. Decorations are independent of pets: own descriptor, own id, own directory — switching pets never switches decorations. Entry assets are PNG/WebP single-row sprite strips only (no SVG/CSS); the bubble always keeps its role=status/aria-live (or session-bubble button semantics), the ornament is aria-hidden; prefers-reduced-motion holds the segment first frame, and a broken asset only removes the ornament — the text stays.
+
+```jsonc
+{
+  "decorationManifestVersion": 1,
+  "id": "whale",                     // unique lowercase kebab id
+  "displayName": "Spouting whale",    // optional
+  "license": "MIT",                   // required: asset provenance
+  "entry": "whale-frames.png",        // PNG/WebP strip, relative to this directory
+  "cell": { "width": 64, "height": 48 },
+  "columns": 4,                       // strip frames (1..16)
+  "frameMs": 160,                     // constant frame duration; or "durations": [..] per frame
+  "loop": true,
+  "phases": {                         // ActivityPhase -> inclusive frame segment; "hide" = none; default hide
+    "idle": "hide",
+    "waiting": { "from": 0, "to": 1 },
+    "thinking": { "from": 0, "to": 3 },
+    "done": { "from": 2, "to": 3 },
+    "failed": { "from": 3, "to": 3 }
+  }
+}
+```
+
+- Structure is fail-closed (unknown fields, out-of-range geometry, non-PNG/WebP entries reject with diagnostics); segment content is warn-and-drop. The machine-readable twin lives at contracts/status-decoration-v1.schema.json; the authoritative validator is src/decoration.ts.
+- Sources: built-in assets/decorations/ plus the user directory $DSH_HOME/pets/decorations/<id>/ (same id overrides the built-in). Assets ride /api/pet/decoration/<id>/<file> with the same containment and allow-lists as pet assets.
+- Switch: Settings > Pet > Status decoration (on by default). The built-in whale derives from the DeepSeek wordmark (MIT); see THIRD_PARTY_NOTICES.md.
 ## Built-in pets
 
 | Registry id | Selector label | Source |

package/README.zh.md

@@ -26,6 +26,7 @@
 | 状态气泡 | 默认只有最近活动的顶层会话说话——多会话并行时，其余会话收进主气泡右上角的 +N 角标，不再叠出一长列；悬停气泡（触屏点按角标）即可向上展开所有会话的气泡，点击任一气泡跳转到对应会话；子代理会话借由其发起会话体现，不占用独立气泡；瞬时互动反馈临时优先。气泡文案按场景准备了大量轮换词库（等待 / 思考 / 整理 / 完成 / 失败……），工具调用按工具族映射俏皮文案并带上真实参数（如 跑跑 npm test），同一场景持续数秒会自动换一种说法 |
 | 碎碎念 | 模型流式输出期间，宠物会偶尔借自己的气泡说出内心独白——新鲜的碎碎念会接管展示会话的气泡并以「」引号标记——与状态气泡共用同一片 DeepSeek 蓝黑玻璃，气泡栈内颜色统一不再色差——不再叠出第二只气泡——由模型输出里的关键词触发对应心境（报错、测试全绿、做计划、打胜仗……），输出量累积也会换来日常碎碎念；有冷却节制，数秒后气泡恢复状态文案 |
 | 多会话活动 | 宠物是宿主全局的：最近一次有意义事件驱动精灵动画，同时每个活动的顶层会话用自己的气泡报告各自状态；每个会话（含子代理）完成的轮次都计入亲密度与小鱼干 |
+| 语音包与面板 DIY | 宠物目录 voice.json + 全局 $DSH_HOME/pets/.voice.json 覆盖气泡全部文案与悬浮面板（按钮标签/统计格式/按钮显隐）；合并优先级 宠物自带 > 全局 > 内置，坏包警告不拒载 |
 
 ## 宠物契约
 
@@ -80,13 +81,47 @@
 用 CLI 校验并安装宠物目录（零构建、零发布）：
 
 ```sh
-node scripts/dsh-pet validate <dir>           # 清单 + 资产 + Live2D 引用闭包
+node scripts/dsh-pet validate <dir>           # 清单 + 资产 + Live2D 引用闭包 + voice.json
 node scripts/dsh-pet install <dir>            # 校验通过后拷入 $DSH_HOME/pets/<id>/
 node scripts/dsh-pet install <dir> --force    # 覆盖同名已安装宠物
 ```
 
 非法条目永不覆盖可用宠物：它们被跳过并在设置（宠物栏目）给出诊断。注册表在宿主启动时构建一次；新增或修改宠物后重启 `dsh web` 生效。
 
+## 语音包与面板定制（voice.json，宠物中心 M4，#677）
+
+气泡里的状态/工具/碎碎念文案与悬浮面板的按钮/统计文案，都可以被一只宠物（或你本人）整体替换——宠物不再只能换图，还能换「话」与「面板」。载体是宠物目录内的可选 voice.json（随宠物分发），以及全局覆盖文件 $DSH_HOME/pets/.voice.json（不改宠物目录即可换词）。
+
+```jsonc
+{
+  "voicePackVersion": 1,              // 可选；缺省视为 1
+  "status": {                          // 状态池：键 = 场景 id，逐键覆盖内置池
+    "done": ["搞定收工～", "交差！下一位"]
+  },
+  "tools": {                           // 工具池：键 = 工具族；允许 {tool} / {hint}
+    "shell": ["跑跑 {hint}", "敲回车！{hint}"]
+  },
+  "toolRemaining": ["后台还有 {n} 位小助手"],   // 允许 {n}
+  "whispers": {                        // 碎碎念：按节替换（非逐条合并）
+    "generic": ["冲了冲了", "稳"],      // 环境池；显式空数组 = 静音
+    "rules": [                         // 关键词规则（有序；给出即整体替换内置规则）
+      { "keywords": ["测试通过"], "pool": ["全绿！"] }
+    ]
+  },
+  "panel": {                           // 悬浮面板（每槽未声明时回落插件 i18n 文案）
+    "labels": { "feed": "投喂", "hide": "藏起来", "rename": "起名字", "confirm": "好的" },
+    "stats": { "rank": "好感 {rank}", "treats": "鱼干 ×{n}", "points": "{points} 分" },
+    "actions": ["feed", "rename", "hide"]  // 子集（按规范顺序）；省略 = 全部；[] = 只显示统计行
+  }
+}
+```
+
+- 合并优先级（逐槽）：宠物自带 voice.json > 全局 .voice.json > 内置文案。status/tools 逐键合并、whispers 按节替换、panel 逐槽合并，任何层缺失的槽位回落下一层。
+- 占位符白名单：tools 允许 {tool} / {hint}；toolRemaining 允许 {n}；panel.stats 允许 {rank} / {n} / {points}；status、碎碎念与面板标签不允许任何占位符（含非法占位符的行被警告丢弃）。
+- 上限（warn-and-drop）：每池 64 行以内、每行 160 字符以内；规则 32 条以内、每规则关键词 16 条以内（40 字符以内）；面板标签 40 以内、统计 80 字符以内。
+- 坏包不影响宠物：voice.json 不是合法 JSON 或根不是对象 → 警告并整体忽略；其余问题逐槽警告丢弃。诊断显示在设置 → 宠物目录诊断。node scripts/dsh-pet validate <dir> 会把结构错误判为安装失败、内容问题列为警告。
+- 语义细节：status/tools 的空池回落内置文案（场景行始终有话说）；whispers 的显式空数组是静音（关掉该通道）；面板 actions 为空数组 = 三个按钮全部隐藏；未覆盖的按钮/统计继续使用插件双语字典。
+
 ## Live2D 宠物（renderer: live2d）
 
 Live2D 宠物经 PixiJS/WebGL 渲染：MIT 许可的 pixi.js + untitled-pixi-live2d-engine 栈以按需加载的 vendor 分包随插件内置，纯 sprite 用户永不下载、永不解析它。**本插件永不内置、永不代下 Cubism Core 运行时**——Live2D 专有许可不允许再分发。启用 Live2D 宠物：
@@ -122,6 +157,34 @@ Live2D 清单把七个活动相位映射到模型的动作组：
 
 模型授权：Live2D 官方示例模型（Hiyori、Haru 等）仅供评估、禁止再分发——只发布你有权的模型（原创作品或宽松授权的模型）。
 
+## 状态装饰（decoration.json，宠物中心 M5，#567）
+
+宠物状态气泡里的文字之前可以有一个小的状态装饰（内置：喷水鲸鱼），由 ActivityPhase 流驱动换帧。装饰与宠物相互独立：独立描述符、独立 id、独立目录，换宠物不换装饰。入口资产只收 PNG/WebP 单行精灵条带（不收 SVG/CSS）；气泡自身的 role=status/aria-live（或会话气泡按钮语义）永远保留，装饰 aria-hidden；prefers-reduced-motion 时停在帧段首帧，资产加载失败只消失装饰、文字照常。
+
+```jsonc
+{
+  "decorationManifestVersion": 1,
+  "id": "whale",                     // 唯一小写 kebab id
+  "displayName": "喷水鲸鱼",           // 可选
+  "license": "MIT",                   // 必填：资产授权（社区装饰必须携带来源声明）
+  "entry": "whale-frames.png",        // PNG/WebP 单行条带，相对本目录
+  "cell": { "width": 64, "height": 48 },
+  "columns": 4,                       // 条带帧数（1..16）
+  "frameMs": 160,                     // 常量帧时长；或用 "durations": [..] 逐帧覆盖
+  "loop": true,
+  "phases": {                         // ActivityPhase 七态 -> 帧段（含端点）；"hide" = 不显示；缺省 = hide
+    "idle": "hide",
+    "waiting": { "from": 0, "to": 1 },
+    "thinking": { "from": 0, "to": 3 },
+    "done": { "from": 2, "to": 3 },
+    "failed": { "from": 3, "to": 3 }
+  }
+}
+```
+
+- 结构 fail-closed（未知字段、越界尺寸、非 PNG/WebP 入口直接拒载并进诊断），帧段内容 warn-and-drop。机器可读 schema 见 contracts/status-decoration-v1.schema.json，权威校验器为 src/decoration.ts。
+- 来源：内置 assets/decorations/ + 用户目录 $DSH_HOME/pets/decorations/<id>/（同 id 覆盖内置）。资产经 /api/pet/decoration/<id>/<file> 路由，containment 与白名单与宠物资产同构。
+- 开关：设置 → 宠物 → 状态装饰（默认开）。内置鲸鱼素材派生自 DeepSeek wordmark（MIT），完整声明见 THIRD_PARTY_NOTICES.md。
 ## 内置宠物
 
 | 注册表 id | 选择器名称 | 来源 |

package/assets/decorations/whale/decoration.json

@@ -0,0 +1,20 @@
+{
+  "decorationManifestVersion": 1,
+  "id": "whale",
+  "displayName": "喷水鲸鱼",
+  "license": "MIT",
+  "entry": "whale-frames.png",
+  "cell": { "width": 64, "height": 48 },
+  "columns": 4,
+  "frameMs": 160,
+  "loop": true,
+  "phases": {
+    "idle": "hide",
+    "waiting": { "from": 0, "to": 1 },
+    "thinking": { "from": 0, "to": 3 },
+    "tool": { "from": 0, "to": 3 },
+    "review": { "from": 0, "to": 1 },
+    "done": { "from": 2, "to": 3 },
+    "failed": { "from": 3, "to": 3 }
+  }
+}

package/contracts/pet-manifest-v2.schema.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.linxin666.org/dsh-pet/pet-manifest-v2.schema.json",
+  "title": "DSH Pet Manifest v2",
+  "description": "Pet-center manifest v2 (issue #623). Pure-asset pet directory contract: renderer type declaration, license metadata, and renderer-specific blocks. Top level and renderer blocks are fail-closed; v1 manifests (no petManifestVersion) are compat-read as sprite2d by the registry.",
+  "type": "object",
+  "required": [
+    "petManifestVersion",
+    "id",
+    "displayName",
+    "license"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "petManifestVersion": {
+      "const": 2
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "maxLength": 64,
+      "description": "Globally unique lowercase kebab-case pet id."
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "author": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Asset license identifier (SPDX id or free text). Required so community pets always carry provenance."
+    },
+    "homepage": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Optional provenance URL for the pet assets."
+    },
+    "renderer": {
+      "enum": [
+        "sprite2d",
+        "live2d"
+      ],
+      "default": "sprite2d",
+      "description": "Renderer kind; omitted means sprite2d (v1 compatibility). Unknown values are rejected."
+    },
+    "sprite2d": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "spritesheetPath"
+      ],
+      "description": "Spritesheet renderer block; required when renderer=sprite2d.",
+      "properties": {
+        "spritesheetPath": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Atlas path relative to the manifest directory (safe segments only)."
+        },
+        "cell": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Atlas cell size in px; defaults to the Codex contract 192x208.",
+          "properties": {
+            "width": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2048
+            },
+            "height": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2048
+            }
+          }
+        },
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "default": 8
+        },
+        "atlasRows": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "description": "Total atlas rows; 9 for the classic contract, 11 for v2 look-row atlases."
+        },
+        "frames": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 32
+          },
+          "description": "Per-row used frame counts; omitted rows fall back to the hatch-pet contract table."
+        },
+        "tracks": {
+          "type": "object",
+          "description": "Per-track rhythm overrides (durations/loop/fallback), v1 structure unchanged."
+        }
+      }
+    },
+    "live2d": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "model",
+        "motions"
+      ],
+      "description": "Live2D renderer block; required when renderer=live2d. The Cubism Core runtime is always user-supplied; the plugin never bundles or downloads it.",
+      "properties": {
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\.model3\\.json$",
+          "description": "Path of the .model3.json relative to the manifest directory."
+        },
+        "scale": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 10,
+          "default": 1
+        },
+        "translate": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "x": {
+              "type": "number"
+            },
+            "y": {
+              "type": "number"
+            }
+          }
+        },
+        "motions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "idle"
+          ],
+          "description": "ActivityPhase -> model motion group name. Unmapped phases fall back to the idle group; missing groups degrade to the first frame with a diagnostic.",
+          "properties": {
+            "idle": {
+              "type": "string",
+              "minLength": 1
+            },
+            "waiting": {
+              "type": "string",
+              "minLength": 1
+            },
+            "thinking": {
+              "type": "string",
+              "minLength": 1
+            },
+            "tool": {
+              "type": "string",
+              "minLength": 1
+            },
+            "review": {
+              "type": "string",
+              "minLength": 1
+            },
+            "done": {
+              "type": "string",
+              "minLength": 1
+            },
+            "failed": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "expressions": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Optional ActivityPhase -> expression name (layered over the motion).",
+          "properties": {
+            "idle": {
+              "type": "string",
+              "minLength": 1
+            },
+            "waiting": {
+              "type": "string",
+              "minLength": 1
+            },
+            "thinking": {
+              "type": "string",
+              "minLength": 1
+            },
+            "tool": {
+              "type": "string",
+              "minLength": 1
+            },
+            "review": {
+              "type": "string",
+              "minLength": 1
+            },
+            "done": {
+              "type": "string",
+              "minLength": 1
+            },
+            "failed": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "hitAreas": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Hit area names that trigger pet.interact; defaults to every HitArea the model declares."
+        },
+        "lipSync": {
+          "type": "boolean",
+          "default": false,
+          "description": "Optional whisper-paced lip sync (post-M3)."
+        }
+      }
+    },
+    "sequences": {
+      "type": "object",
+      "description": "Renderer-agnostic ActivityPhase sequence table (v1 structure; every declared sequence has at least 5 items)."
+    },
+    "remarks": {
+      "type": "object",
+      "description": "Per-slot witty-remark pools (v1 structure; a slot replaces the built-in pool for that slot only)."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "renderer": {
+            "const": "sprite2d"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "sprite2d"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "renderer": {
+            "const": "live2d"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "live2d"
+        ]
+      }
+    }
+  ]
+}

package/contracts/status-decoration-v1.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.linxin666.org/dsh-pet/status-decoration-v1.schema.json",
+  "title": "DSH Pet Status Decoration v1",
+  "description": "Status-decoration descriptor (issue #623 M5, protocol #567). A pure-content entry ornamenting the pet center's status bubble chrome with a PNG/WebP sprite strip driven by the ActivityPhase stream. Structure is fail-closed; phase-binding content issues drop that binding only. Entry assets are PNG/WebP strips only (no SVG/CSS) per the adopted disciplines.",
+  "type": "object",
+  "required": [
+    "decorationManifestVersion",
+    "id",
+    "license",
+    "entry",
+    "cell",
+    "columns"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "decorationManifestVersion": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "maxLength": 64
+    },
+    "displayName": {
+      "type": "string",
+      "maxLength": 64
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Asset license identifier (SPDX id or free text). Required so community decorations always carry provenance."
+    },
+    "entry": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "PNG/WebP single-row sprite strip, relative to the descriptor directory."
+    },
+    "cell": {
+      "type": "object",
+      "required": [
+        "width",
+        "height"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 256
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 256
+        }
+      }
+    },
+    "columns": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 16
+    },
+    "frameMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2000,
+      "description": "Constant per-frame duration; 'durations' overrides per frame."
+    },
+    "durations": {
+      "type": "array",
+      "items": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 2000
+      },
+      "description": "Per-frame durations; length must equal 'columns'."
+    },
+    "loop": {
+      "type": "boolean",
+      "default": true
+    },
+    "phases": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "ActivityPhase -> frame segment; 'hide' (default) shows no ornament.",
+      "properties": {
+        "idle": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "waiting": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "thinking": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "tool": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "review": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "done": {
+          "$ref": "#/definitions/phaseBinding"
+        },
+        "failed": {
+          "$ref": "#/definitions/phaseBinding"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "phaseBinding": {
+      "oneOf": [
+        {
+          "const": "hide"
+        },
+        {
+          "type": "object",
+          "required": [
+            "from",
+            "to"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "from": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "to": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "description": "Inclusive frame segment into the strip; must satisfy from <= to < columns."
+        }
+      ]
+    }
+  }
+}