@linxin666/dsh-client-ui-skin-center 0.3.4 → 0.3.5

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: 04b1c524d8222926a64008329b4fb9454ab2f0c0
-README.zh.md: 56cd3679ad66705e5543409086911be3bf723fbd
+README.md: 6c66e64a68379e434045dd573fae29d2fbdf75f3
+README.zh.md: 278218950a5310342387b1a3c19c4b91013d43d3

package/README.md

@@ -22,7 +22,7 @@ dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center
 # From the repo (dev): dsh plugin --profile web add link:$(pwd)/packages/skins/skin-center
 ```
 
-`$(pwd)` is your clone of the dsh-web monorepo. Only the default skin (blue-fantasy) ships inside this package; every other skin installs on demand from dsh-market.com into `$DSH_HOME/skins/<id>/`, and community skins are plain directories in the same place (no install command, no restart — reopen the card or reload to pick them up). A fresh install activates blue-fantasy by default (host seed); an update whose active skin is no longer available falls back to the stock look. The package ships `skins/blue-fantasy` only; the remaining skins stay in the repository under `skins/` as the market-build and gallery source and are never published in the package.
+`$(pwd)` is your clone of the dsh-web monorepo. Only the default skin (blue-fantasy) ships inside this package; every other skin installs on demand from dsh-market.com into `$DSH_HOME/skins/<id>/`, and community skins are plain directories in the same place (no install command, no restart — reopen the card or reload to pick them up). A fresh install activates blue-fantasy by default (host seed); an update whose active skin is no longer available falls back to the stock look. The package ships `skins/blue-fantasy` only; the remaining skins stay in the repository under `skins/` as the market-build source and are never published in the package.
 
 skin-center is a self-contained bundle meeting the official DSH plugin standard (`dsh.bundle.patch` points to `cordis.patch.yml`); it can also be installed via git: `dsh plugin --profile web add github:<org>/dsh-web#<sha>` (the `prepare` script builds `lib/` in place). pnpm ≥10 requires authorizing `allowBuilds` before installing a git dependency; a local `link:` install has no such requirement.
 
@@ -40,7 +40,7 @@ skin-center is a self-contained bundle meeting the official DSH plugin standard
 - All `/api/skin-center/*` routes are same-origin only: writes reject cross-site requests (Sec-Fetch-Site / Origin fence), and asset reads are contained inside each skin directory (path escapes fail closed).
 - Skin CSS is sanitized (whitelist) before serving; `patches.css` (L3) is arbitrary CSS by design and disclosed as such — it runs with full page styling power and is not a security boundary.
 - The custom-theme editor emits only fixed declarations from `CUSTOM_THEME_ALLOWED_TOKENS`, each verified against the official token registry. User input is normalized color/contrast data and never becomes a selector, URL or free-form CSS payload.
-- `hooks.mjs` is trusted code that shares this repository's review and release; it is served same-origin only and its import/apply errors can never take the static skin down. Hooks run for built-in skins, and for user-directory skins installed from the official DSH Market whose `dsh-market.provenance.json` sha256-pins the on-disk `skin.json` and hooks entry to the market-served bytes (verified by `src/provenance.ts`, issue #1073); a missing or mismatched provenance — hand-dropped or tampered directories — keeps the hooks facet refused while the declarative parts still load.
+- `hooks.mjs` is trusted code that shares this repository's review and release; it is served same-origin only and its import/apply errors can never take the static skin down. Hooks run for built-in skins and for user-directory skins whose executable identity is byte-verified as reviewed official-market content: current Workshop installs use `dsh-market.provenance.json`, while legacy pre-provenance installs must match the generated `src/reviewed-hooks.generated.ts` identity for id, declared entry, complete `skin.json`, and hooks bytes (verified by `src/provenance.ts`, issue #1073). The fallback is read-only and offline; any modified, renamed, hand-dropped, or tampered directory keeps the hooks facet refused while the declarative parts still load.
 
 ## Known limitations
 

package/README.zh.md

@@ -40,7 +40,7 @@ dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center
 - 所有 `/api/skin-center/*` 路由仅接受同源请求：写操作拒绝跨站请求（Sec-Fetch-Site / Origin 围栏），资产读取限定在各皮肤目录之内（路径逃逸 fail-closed）。
 - 皮肤 CSS 在服务前经白名单净化；`patches.css`（L3）按设计就是任意 CSS 并如实公示——它拥有完整页面样式能力，不构成安全边界。
 - 自定义主题编辑器只会从 `CUSTOM_THEME_ALLOWED_TOKENS` 生成固定声明，且每个 token 都对照官方 token 注册表校验。用户输入只作为规范化后的颜色/对比度数据，不会成为选择器、URL 或自由 CSS 载荷。
-- `hooks.mjs` 是与本仓库同审同发的受信代码，仅同源 serve，其 import/apply 错误永远不会拖垮静态皮肤。hooks 对内置皮肤放行；对用户目录皮肤，仅当其从官方 DSH 市场安装且 `dsh-market.provenance.json` 以 sha256 钉住磁盘上的 `skin.json` 与 hooks 入口字节时放行（由 `src/provenance.ts` 校验，issue #1073）；provenance 缺失或不匹配——手工投放或被篡改的目录——hooks facet 保持拒绝，声明式部分仍正常加载。
+- `hooks.mjs` 是与本仓库同审同发的受信代码，仅同源 serve，其 import/apply 错误永远不会拖垮静态皮肤。hooks 对内置皮肤及可按字节验证为官方市场已审查内容的用户目录皮肤放行：当前 Workshop 安装使用 `dsh-market.provenance.json`，而早于 provenance 的历史安装必须同时匹配生成的 `src/reviewed-hooks.generated.ts` 身份中的 id、声明入口、完整 `skin.json` 与 hooks 字节（由 `src/provenance.ts` 校验，issue #1073）。回退只读且离线；任何被修改、改名、手工投放或篡改的目录都会继续拒绝 hooks facet，声明式部分仍正常加载。
 
 ## 已知限制
 

package/contracts/README.md

@@ -44,16 +44,9 @@ and release. It is served verbatim over `GET /skins/<id>/hooks.mjs` only for:
 
 - **built-in skins** — shipped inside the skin-center npm package, same
   review and release by definition;
-- **official-market installs** — user-directory skins carrying a
-  `dsh-market.provenance.json` whose sha256 pins the on-disk `skin.json`
-  and hooks entry to the bytes the official DSH Market served (the market
-  content is built from this repository, so a hash match means the bytes
-  are the reviewed ones). Verification lives in `src/provenance.ts` and
-  fails closed: any missing, foreign-source or mismatched provenance keeps
-  the hooks facet refused with a catalog warning while the declarative
-  parts (skin.css / patches.css / assets) still load (issue #1073).
-
-Locally dropped or third-party skin directories never run hooks.
+- **official-market installs** — user-directory skins whose executable identity is byte-verified as reviewed content. Current Workshop installs carry a `dsh-market.provenance.json` whose sha256 pins the on-disk `skin.json` and hooks entry to the bytes the official DSH Market served. Historical installs created before provenance existed may recover only when id, declared entry, complete `skin.json`, and hooks bytes match one identity in generated `src/reviewed-hooks.generated.ts`. The registry is generated from this repository's market skin sources by `scripts/skin-hooks-registry.mjs`; `--check` is part of `skin-center:check`, so any reviewed manifest or hook change must regenerate it. Verification lives in `src/provenance.ts`, is read-only and offline, and fails closed: a foreign source, unknown identity, renamed skin, or an executable-identity mismatch keeps the hooks facet refused with a catalog warning while the declarative parts (skin.css / patches.css / assets) still load (issue #1073).
+
+Locally dropped or third-party skin directories never run hooks unless their executable identity is byte-identical to a reviewed official-market skin. Declarative files outside that identity may be customized without granting additional executable capability.
 
 ## Loader-side rules (pinned here, enforced in M2)
 

package/contracts/performance-guidelines-v1.md

@@ -0,0 +1,107 @@
+# Skin Runtime Performance Guidelines (v1)
+
+Contract owner: skin-center (single owner, conflict resolution does not rely
+on load order). Version: `performance-guidelines/v1` (2026-02, authored after
+the orca-link session-switch latency investigation).
+
+These are the runtime-performance rules for skin **hooks** (`hooks.mjs`,
+`facets.client`) and their stylesheets. They exist because skins share the
+host page with the DSH shell and every plugin: a skin that watches the whole
+document or keeps GPU layers alive degrades everyone. The rules are advice
+with teeth — a code review hook check and a human review of the case study
+([orca-link hooks](../../../packages/skins/skin-center/skins/orca-link/hooks.mjs),
+[patches](../../../packages/skins/skin-center/skins/orca-link/patches.css))
+should reject their violation.
+
+## R1 — DOM observation must be scoped and short-circuited
+
+Never broadcast a full-tree scan from a `MutationObserver` callback:
+
+- Watch the narrowest possible scope. Observing `document.body` with
+  `subtree: true` is only acceptable when every callback answers "did my
+  anchor actually change?" in O(1) before doing any work.
+- Cache the anchor. A conversation/session root is rebuilt only on session
+  switches; between switches the phase lives on the same node, so a
+  `let memo = null; memo = memo?.isConnected ? memo : locate()` cache is
+  exact (a rebuilt root is a different node, `isConnected` flips on the old
+  one, and the next callback re-locates).
+- Skip fully mounted state. For per-seat work, record the mount phase or the
+  exact element references on the binding and return early when nothing
+  changed; only re-run the "may need rebuild" path when an element or phase
+  actually changed.
+- High-churn regions (terminals, streaming input backdrops) should be
+  excluded from work with a fast `closest()` check before any scanning.
+
+## R2 — Host-glyph fingerprint matching must be one regex pre-scan
+
+When a skin redraws host SVG glyphs by matching path fingerprints:
+
+- Compile the fingerprint table once into a single alternation regex and use
+  `regex.test(html)` as the boolean gate. Per-svg `includes()` loops over
+  N fingerprints turn a session-loading DOM insert into O(svgs × N × len)
+  string work; one regex test makes it O(len).
+- Keep the ordered key table for the *decision*: "first key in the table that
+  appears" is the precedence contract, and the pre-scan regex only answers
+  the boolean. Do not reorder or deduplicate keys to let the regex decide.
+- Never clone a fresh svg. A svg that has no skin art yet carries only host
+  markup — read `svg.innerHTML` directly. The clone/remove-art dance is only
+  needed on an already-reconciled svg.
+- Preserve idempotency: re-reconciling an already-art'd svg must not stack a
+  second art group (guard on the art attribute / recorded name).
+
+## R3 — Frame loops and infinite animations must pause when hidden
+
+- A `setTimeout` frame chain (character sprite atlases, per-frame CSS-variable
+  writes) must subscribe to `visibilitychange`: hidden = clear the pending
+  timeout; visible = reschedule from the current sequence index (never reset
+  the animation state).
+- Mirror the hidden state onto an attribute the stylesheet can read
+  (e.g. `body[data-*tab-hidden]`) and set `animation-play-state: paused` for
+  the skin's own infinite `@keyframes` loops. The stylesheet pause is what
+  actually stops the compositor work.
+- Do not write CSS custom properties that nothing consumes. Each
+  `style.setProperty` is a style-recalc surface; a consumed-by-nobody
+  variable written 60+ times per second is pure waste.
+- Animate with composited properties (`transform`, `opacity`). Animating
+  `background-position` repaints per frame: it rasterizes instead of
+  compositing and shows up in long-task traces.
+
+## R4 — `will-change` must not be parked on full-screen or idle layers
+
+- `will-change: opacity, transform, filter` keeps a GPU compositing layer
+  alive **forever**, even when nothing is animating. A static 0px filter
+  (`blur()`) is a no-op; the layer cost is not.
+- Only keep `will-change` on elements in a *sustained* animation (e.g. an
+  infinite loop already covered by R3); never on full-viewport fixed
+  backgrounds that merely crossfade — a .64s transition promotes the layer
+  automatically for its duration and releases it afterwards.
+- Prefer visibility/display switches (with the opposite theme hidden) over
+  layering both scene sets, and keep the visible scene count at one.
+- `backdrop-filter` is realtime and expensive: keep its covered area to the
+  smallest surface that needs the effect, avoid animating it, and test with
+  scrolling under the blurred surface.
+
+## R5 — Never interleave layout reads and writes in mutation callbacks
+
+- `getBoundingClientRect()` / `offset*` reads force layout. In a mutation
+  storm (large DOM inserts), a read-write-read-write pattern in one callback
+  is layout thrashing: batch all reads first, then all writes.
+- Cache measurements on the binding; recompute only when the referenced
+  element changes. A restore-button re-anchor on an unchanged seat is the
+  classic offender — skip it via the R1 short-circuit.
+
+## R6 — Delegation of cleanup (existing contract, restated)
+
+Every observer, listener (`visibilitychange`, `pointermove`, `click`,
+`focusin`...), timer and interval created in `apply()` must be registered
+through `ctx.onCleanup` and torn down in reverse order, including new
+global-body attributes. A skin that leaks observers doubles the cost of every
+future session switch.
+
+## Verification
+
+Measure before and after with the DevTools Performance panel during session
+load and session switch (the heaviest DOM operations a skin hooks into).
+Long tasks with an aggregate > 100ms, or frames on the main busied line
+during those operations, indicate a violation of the rules above. Per-skin
+tracking numbers serve as regression baselines; include them in the PR body.

package/contracts/semantic-attrs-v1.md

@@ -78,6 +78,7 @@ family / 插件区域：
 | `dialog` | git-graph | 图对话框；`[data-gitgraph-dialog]` |
 | `graph-row` | git-graph | 提交行；dialog 内行容器 |
 | `ref` | git-graph | 分支徽标；`[data-gitgraph-ref]` |
+| `worktree-create` / `worktree-manage` | git-graph | worktree 创建/管理入口按钮；分支弹层 footer 内裸值按钮 |
 | `sprite` | pet | 精灵；`[data-dsh-pet-root]` 子树 float 容器 |
 | `bubble` | pet | 气泡容器 |
 | `panel` | pet | 交互面板；`[data-placement]` |
@@ -120,7 +121,7 @@ family / 插件区域：
 | `remote-web-ui` | dsh-remote-web-ui | slot entry id `remote-web-ui` |
 | `web-ui-settings` | dsh-web-settings | settings.section id `web-ui-plugins` |
 | `skill-explorer` | dsh-skill-explorer | `[data-dsh-skill-explorer-view]` / `[data-dsh-skill-explorer-entry]` |
-| `doctor` | dsh-doctor | web-ui.plugin.item 槽 entry id `doctor`（设置 → Web UI 插件 → Doctor 卡片）；卡片内 `[data-dsh-plugin="doctor"]` |
+| `doctor` | dsh-doctor | web-ui.plugin.item 槽 entry id `doctor`（设置 → Web 插件 → Doctor 卡片）；卡片内 `[data-dsh-plugin="doctor"]` |
 | `aionui-panel` | dsh-aionui-panel（停更） | dock entry id `aionui-*` |
 | `dsh-web-ui-market` | dsh-market | 创意工坊商店一级页（settings.section id `dsh-web-ui-market`），商店卡与目录条目容器 |
 | `skin-center` | skins/skin-center | 一级设置分区 settings.section id `skin-center`（列已安装皮肤，属内置源时显式标记） |

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

@@ -80,7 +80,7 @@
     },
     "attribution": {
       "type": "string",
-      "description": "Optional attribution line shown in the gallery."
+      "description": "Optional attribution line shown in the shop."
     },
     "preview": {
       "type": "object",
@@ -144,7 +144,7 @@
         },
         "patches": {
           "$ref": "#/$defs/relPath",
-          "description": "Optional L3 free-selector patches. High sensitivity; disclosed in UI and gallery."
+          "description": "Optional L3 free-selector patches. High sensitivity; disclosed in the Skin Center UI and the shop."
         },
         "backgroundMedia": {
           "type": "object",