dsh-mini-utility-dock 0.3.0 → 0.5.1

package/CHANGELOG.en.md

@@ -3,6 +3,19 @@
 Release notes are generated from the matching version section; newest first.
 For Chinese, see [CHANGELOG.md](CHANGELOG.md).
 
+## 0.5.1 - 2026-09-25
+
+- Fix the launcher disappearing after a hot reload: the claim is released with its owner, which wakes the other copies to register again instead of requiring a full page reload.
+
+## 0.5.0 - 2026-09-24
+
+- New `dist/launcher.js` (marker `dsh-utility-launcher`): the family's shared entry point — one icon at the bottom-left that opens a menu of the family's panels. It goes through slots rather than a page-local protocol: one copy of the assembly runs per page (the first plugin to load wins the `window` mutex and declares the menu seat `createhelper.utility.item`), and every other plugin contributes one row to that seat. Consumers maintain it with `launcher:sync` / `launcher:check`, so the three client halves no longer each carry their own copy.
+
+## 0.4.0 - 2026-09-24
+
+- Remove `dist/bootstrap.js` (the dock bootstrap fragment) and its `FRAGMENTS` row. It made every consumer append a `position:fixed; z-index:9997` container to `document.body` and locate it by measuring the sidebar — so it necessarily floated above the page and covered the composer's own controls. The three consumers now register the host's `sidebar.footer.action` seat instead (an icon button directly above Settings), embed no fragment in `lib/client.js` at all, and drop their `dock:sync` / `dock:check` scripts.
+- Consumers stay pinned to `0.3.0`: the two remaining fragments (loopback predicates, host guard) are unchanged, so `loopback:check` / `guard:check` keep comparing against that version byte for byte.
+
 ## 0.3.0 - 2026-09-22
 
 - New `dsh-plugin-docs`: a bilingual docs structure check, adopted from the `check-docs.mjs` copy each plugin repository carried. Same interface: no arguments checks the README and CHANGELOG pairs for structural alignment, `--base <revision>` requires bilingual pairs to change together. This package's own bilingual docs are now checked by it too.

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 Release Notes 由对应版本段生成；最新版本在前。
 英文版见 [CHANGELOG.en.md](CHANGELOG.en.md)。
 
+## 0.5.1 - 2026-09-25
+
+- 修复 launcher 热重载后消失：归属从一次性闩锁改为可释放的认领，owner 被销毁时唤醒其余副本重新注册，不再需要刷新整页。
+
+## 0.5.0 - 2026-09-24
+
+- 新增 `dist/launcher.js`（片段标记 `dsh-utility-launcher`）：族的共享入口——左下角一个图标，点开一个列出各插件面板的菜单。它走槽位而不是页面级协议：每页只有一份装配（先加载的插件赢得 `window` 互斥并声明菜单座位 `createhelper.utility.item`），其余插件各往那个座位投一行。消费插件用 `launcher:sync` / `launcher:check` 维护，三个 client 半从此不再各写一份。
+
+## 0.4.0 - 2026-09-24
+
+- 移除 `dist/bootstrap.js`（dock 引导片段）与对应的 `FRAGMENTS` 条目。它让每个消费插件在 `document.body` 上挂一个 `position:fixed; z-index:9997` 的容器，位置靠自己量侧边栏算出来——于是它必然悬在页面上方，会压住 composer 自己的控件。三个消费插件已改为注册宿主槽位 `sidebar.footer.action`（图标按钮，就在设置上方），`lib/client.js` 不再嵌任何片段，各仓的 `dock:sync` / `dock:check` 随之删除。
+- 消费仓仍 pin `0.3.0`：本仓剩下两个片段（loopback 判定、host 守卫）未变，`loopback:check` / `guard:check` 继续按该版本逐字节比对。
+
 ## 0.3.0 - 2026-09-22
 
 - 新增 `dsh-plugin-docs`：双语文档结构校验，收编自插件仓里各自维护的 `check-docs.mjs`。接口不变：无参数查 README 与 CHANGELOG 的中英结构对齐，`--base <revision>` 检查双语对同改。本包自身的双语文档也由此接入校验。

package/README.en.md

@@ -15,9 +15,9 @@ The DSH plugin family's shared assets: source fragments, an embedding CLI, and t
 
 | Fragment | Marker | Target file | Exports |
 | --- | --- | --- | --- |
-| dock bootstrap | `dsh-mini-utility-dock` | `lib/client.js` | — |
 | loopback predicates | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`, `normalizeHostValue`, `hostHostname`, `isLoopbackName`, `isLoopbackAddress` |
 | host request guard | `dsh-host-guard` | `lib/shared.js` | `portOf`, `GUARD_REASONS`, `DEFAULT_GUARD_POLICY` |
+| utility launcher | `dsh-utility-launcher` | `lib/client.js` | `registerUtilityLauncher`, `UTILITY_ITEM_SLOT` |
 
 ## Usage
 
@@ -33,11 +33,11 @@ The CLI maintains every marked fragment in the file, applied bottom-up in `FRAGM
 Equivalent entry point from this repository (target passed by the caller):
 
 ```sh
-npm run dock:embed -- check path/to/client.js
-npm run dock:embed -- sync path/to/client.js
+npm run dock:embed -- check path/to/shared.js
+npm run dock:embed -- sync path/to/shared.js
 ```
 
-Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target fixed to their own `lib/shared.js`.
+Consumers invoke the same CLI as `loopback:sync` / `guard:sync` with the target fixed to their own `lib/shared.js`, and as `launcher:sync` for the `dsh-utility-launcher` block in their own `lib/client.js`.
 
 ## Constraints
 
@@ -45,7 +45,6 @@ Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target
 - The two fragments in `lib/shared.js` have a fixed order, `dsh-loopback-helpers` first: `dsh-host-guard` uses the module-scope names the preceding fragment exports, and neither redeclares nor imports them.
 - A fragment must not contain `import` or `require`; a consumer must publish standalone.
 - `bindGuard` is not exported — a consumer declares its own guard export in the same file. Each plugin passes its own error codes and wording through `policy`; the enforcement is shared.
-- A missing, blank, or non-string `label` falls back to `id`.
 
 ## Cross-repo consistency
 

package/README.md

@@ -15,9 +15,9 @@ DSH 插件族的共享资产：源码片段、嵌入 CLI，以及围绕它们的
 
 | 片段 | 标记 | 目标文件 | 导出 |
 | --- | --- | --- | --- |
-| dock 引导 | `dsh-mini-utility-dock` | `lib/client.js` | — |
 | loopback 判定 | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`、`normalizeHostValue`、`hostHostname`、`isLoopbackName`、`isLoopbackAddress` |
 | host 请求守卫 | `dsh-host-guard` | `lib/shared.js` | `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` |
+| utility 入口 | `dsh-utility-launcher` | `lib/client.js` | `registerUtilityLauncher`、`UTILITY_ITEM_SLOT` |
 
 ## 使用
 
@@ -33,11 +33,11 @@ CLI 处理文件中所有已标记的片段，按 `FRAGMENTS` 顺序自下而上
 本仓库等价入口（目标由调用方传入）：
 
 ```sh
-npm run dock:embed -- check path/to/client.js
-npm run dock:embed -- sync path/to/client.js
+npm run dock:embed -- check path/to/shared.js
+npm run dock:embed -- sync path/to/shared.js
 ```
 
-消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身 `lib/shared.js`。
+消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身 `lib/shared.js`；client 半以 `launcher:sync` 维护 `dsh-utility-launcher` 块，目标固定为自身 `lib/client.js`。
 
 ## 约束
 
@@ -45,7 +45,6 @@ npm run dock:embed -- sync path/to/client.js
 - `lib/shared.js` 中两个片段顺序固定，`dsh-loopback-helpers` 在前：`dsh-host-guard` 直接使用前一片段导出的模块级名字，既不重新声明也不 import。
 - 片段不得包含 `import` 或 `require`；消费插件必须能独立发布。
 - `bindGuard` 不从片段导出——消费插件在同一文件中声明自己的 guard 导出。各插件通过 `policy` 传入自身错误码与文案，判定逻辑共用。
-- `label` 缺省、空白或非字符串时回退为 `id`。
 
 ## 跨仓一致性
 

package/bin/dsh-mini-utility-dock.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Embed a canonical fragment from this package into a consumer file.
 //
-// Two fragments are maintained the same way, because both have the same shape
-// of problem: the consumer must ship the code standalone (a browser classic
+// Three fragments are maintained the same way, because all three have the same
+// shape of problem: the consumer must ship the code standalone (a browser classic
 // script cannot `import`, and a host half must not depend on the dock being
 // installed), so the code is embedded at build time and drift is a build error.
 //
-//   dsh-mini-utility-dock  -> <dsh-mini-utility-dock> ... </dsh-mini-utility-dock>
-//     the Mini Utility Dock bootstrap, embedded into a plugin's lib/client.js
+//   dsh-utility-launcher   -> <dsh-utility-launcher> ... </dsh-utility-launcher>
+//     the family launcher (one icon plus the menu of family panels it opens),
+//     embedded into a plugin's lib/client.js
 //
 //   dsh-loopback-helpers   -> <dsh-loopback-helpers> ... </dsh-loopback-helpers>
 //     the loopback predicates, embedded into a plugin's lib/shared.js
@@ -21,8 +22,9 @@
 // embed just those.
 //
 // The fragment is selected by the marker already present in the target file, so
-// one command serves either target. A consumer calls this through its own
-// `dock:sync` / `guard:sync` script; the paired `check` mode is what CI runs.
+// one command serves every target and only a named block is ever touched. A
+// consumer calls this through its own `launcher:sync` / `guard:sync` /
+// `loopback:sync` script; the paired `check` mode is what CI runs.
 
 import { readFile, writeFile, stat } from 'node:fs/promises'
 import { resolve } from 'node:path'
@@ -30,11 +32,12 @@ import { fileURLToPath } from 'node:url'
 
 // Listed in dependency order: the guard fragment reads the predicates the
 // loopback fragment declares, so a consumer that wants the guard syncs both, in
-// this order, into the same file.
+// this order, into the same file. The launcher is independent of both and lands
+// in the client half instead, so it sits last.
 const FRAGMENTS = [
-  { name: 'dsh-mini-utility-dock', source: 'bootstrap.js' },
   { name: 'dsh-loopback-helpers', source: 'loopback.js' },
-  { name: 'dsh-host-guard', source: 'guard.js' }
+  { name: 'dsh-host-guard', source: 'guard.js' },
+  { name: 'dsh-utility-launcher', source: 'launcher.js' }
 ]
 
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))

package/dist/launcher.js

@@ -0,0 +1,206 @@
+// Family utility launcher shared by the browser halves of the DSH plugins.
+//
+// This fragment has ONE source of truth: dsh-mini-utility-dock/dist/launcher.js.
+// DSH client artifacts are self-contained classic scripts, so the fragment is
+// embedded into lib/client.js at build time by
+//   npm run launcher:sync    (write it)
+//   npm run launcher:check   (fail on drift)
+// instead of being imported: a bare import would put a runtime dependency on the
+// dock into every plugin, and the whole point of the dock is that a plugin ships
+// standalone, with nothing else required.
+//
+// The launcher is one icon that opens a menu of family panels. It is contributed
+// through slots, not through a page-local protocol: exactly one copy of this
+// assembly runs per page (the first plugin to load wins the window mutex and
+// declares the menu seat), and every plugin adds one row to that seat.
+const UTILITY_ITEM_SLOT = 'createhelper.utility.item'
+const UTILITY_MUTEX_KEY = '__CREATEHELPER_DSH_UTILITY_LAUNCHER_V1__'
+const UTILITY_CSS_ID = 'createhelper-utility-launcher'
+const UTILITY_FALLBACK_LEFT_PX = 80
+const UTILITY_MEASURE_TRIES = 120
+const UTILITY_ICON = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="7" height="7" rx="2"></rect><rect x="14" y="3" width="7" height="7" rx="2"></rect><rect x="3" y="14" width="7" height="7" rx="2"></rect><rect x="14" y="14" width="7" height="7" rx="2"></rect></svg>'
+
+// The launcher's own chrome, injected once by whichever copy wins the mutex.
+// The rows belong to other plugins, so the menu styles its own buttons by
+// position instead of asking every contributor for a class name.
+function ensureUtilityStyles() {
+  if (typeof document === 'undefined') return
+  if (document.querySelector('style[data-plugin-css="' + UTILITY_CSS_ID + '"]') !== null) return
+  const styleEl = document.createElement('style')
+  styleEl.setAttribute('data-plugin-css', UTILITY_CSS_ID)
+  styleEl.textContent =
+    '.createhelper-utility-anchor{position:fixed;bottom:16px;z-index:9997;pointer-events:auto}' +
+    '.createhelper-utility-launcher{display:inline-flex;align-items:center;justify-content:center;width:30px;height:30px;padding:0;border:1px solid var(--dsw-alias-border-l1);border-radius:9px;background:var(--dsw-alias-bg-overlay);color:var(--dsw-alias-label-secondary);cursor:pointer;box-shadow:0 4px 14px rgba(0,0,0,.22)}' +
+    '.createhelper-utility-launcher:hover,.createhelper-utility-launcher[aria-expanded="true"]{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}' +
+    '.createhelper-utility-launcher svg{display:block}' +
+    '.createhelper-utility-menu{display:flex;flex-direction:column;gap:2px;min-width:172px;margin-bottom:6px;padding:4px;border:1px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-alias-bg-overlay);box-shadow:0 10px 30px rgba(0,0,0,.28)}' +
+    '.createhelper-utility-menu[hidden]{display:none}' +
+    '.createhelper-utility-menu button{display:flex;align-items:center;gap:8px;width:100%;height:30px;padding:0 8px;border:0;border-radius:8px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;font:inherit;font-size:12px;text-align:left;white-space:nowrap}' +
+    '.createhelper-utility-menu button:hover,.createhelper-utility-menu button[aria-pressed="true"]{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}' +
+    '.createhelper-utility-menu button svg{display:block;flex:none}'
+  document.head.appendChild(styleEl)
+}
+
+// The position rule the retired page dock used: right of the sidebar, 16px
+// in, and 80px when the shell has not laid the column out yet.
+const measureUtilityLeft = () => {
+  if (typeof document === 'undefined') return UTILITY_FALLBACK_LEFT_PX
+  const overlay = document.querySelector('[data-shell-overlay]')
+  const frame = overlay && overlay.parentElement
+  const sidebar = frame && frame.firstElementChild
+  const rect = sidebar && typeof sidebar.getBoundingClientRect === 'function'
+    ? sidebar.getBoundingClientRect()
+    : null
+  if (!rect || !rect.right) return UTILITY_FALLBACK_LEFT_PX
+  return Math.max(16, Math.round(rect.right + 16))
+}
+// The overlay layer commits before the frame's columns are laid out, so the
+// first read answers the fallback; keep re-reading for ~2s and then stop.
+const useUtilityLeft = () => {
+  const [left, setLeft] = React.useState(UTILITY_FALLBACK_LEFT_PX)
+  React.useEffect(() => {
+    let stopped = false
+    let tries = 0
+    let frameId = 0
+    const raf = typeof requestAnimationFrame === 'function' ? requestAnimationFrame : null
+    const sync = () => {
+      if (stopped) return
+      const next = measureUtilityLeft()
+      setLeft(next)
+      if (next === UTILITY_FALLBACK_LEFT_PX && raf !== null && tries < UTILITY_MEASURE_TRIES) {
+        tries += 1
+        frameId = raf(sync)
+      }
+    }
+    sync()
+    window.addEventListener('resize', sync)
+    return () => {
+      stopped = true
+      if (raf !== null && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(frameId)
+      window.removeEventListener('resize', sync)
+    }
+  }, [])
+  return left
+}
+// The block owns no dictionary, so its own title follows the browser
+// language; each row's label comes from the plugin that contributes it.
+const utilityTitle = () => {
+  const nav = (typeof navigator !== 'undefined' && navigator.language) || ''
+  return /^zh/i.test(nav) ? '工具面板' : 'Utility panels'
+}
+const utilityMenu = { open: false, listeners: new Set() }
+const setUtilityMenu = (value) => {
+  utilityMenu.open = !!value
+  utilityMenu.listeners.forEach((listener) => listener())
+}
+const useUtilityMenu = () => {
+  const [, setTick] = React.useState(0)
+  React.useEffect(() => {
+    const listener = () => setTick((value) => value + 1)
+    utilityMenu.listeners.add(listener)
+    return () => utilityMenu.listeners.delete(listener)
+  }, [])
+  return utilityMenu.open
+}
+// The launcher and its menu. The menu is always rendered - a declared child
+// slot is not conditionally declared - and hidden when closed. Choosing a row
+// closes the menu through the click that bubbles out of it, because the rows
+// are other plugins' components.
+function UtilityLauncher (props) {
+  const left = useUtilityLeft()
+  const open = useUtilityMenu()
+  ensureUtilityStyles()
+  React.useEffect(() => {
+    if (!open) return undefined
+    const onDown = (event) => {
+      const target = event && event.target
+      if (target && typeof target.closest === 'function' && target.closest('[data-utility-anchor]') !== null) return
+      setUtilityMenu(false)
+    }
+    const onKey = (event) => { if (event && event.key === 'Escape') setUtilityMenu(false) }
+    document.addEventListener('mousedown', onDown)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onDown)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+  return h('div', {
+    'data-utility-anchor': '',
+    className: 'createhelper-utility-anchor',
+    style: { left: left + 'px' }
+  }, [
+    h('div', {
+      key: 'menu',
+      className: 'createhelper-utility-menu',
+      hidden: !open,
+      onClick: () => setUtilityMenu(false)
+    }, props && typeof props.renderSlot === 'function' ? props.renderSlot(UTILITY_ITEM_SLOT, {}) : null),
+    h('button', {
+      key: 'icon',
+      type: 'button',
+      className: 'createhelper-utility-launcher',
+      title: utilityTitle(),
+      'aria-label': utilityTitle(),
+      'aria-expanded': open ? 'true' : 'false',
+      onClick: () => setUtilityMenu(!open),
+      dangerouslySetInnerHTML: { __html: UTILITY_ICON }
+    })
+  ])
+}
+// Whoever loads first owns the assembly; everyone else only contributes rows.
+// The child slot is declared here, so a plugin that joins later still finds it
+// through slots.inject, and an install with one plugin still gets a launcher.
+//
+// The seat belongs to the shell, so it is reached through inject: registering
+// into it directly throws while that declaration is still pending, and a
+// launcher must never cost the caller the surfaces it registers afterwards.
+//
+// The claim lives on the page and is released with its owner. Every family
+// client half carries this assembly, so without the release a hot reload of the
+// owner would dispose its registration while the claim stayed taken, and the
+// launcher would stay missing until the page was reloaded. A released claim
+// wakes the other copies, which re-register immediately.
+const utilityClaim = () => {
+  if (typeof window === 'undefined') return null
+  const existing = window[UTILITY_MUTEX_KEY]
+  if (existing !== null && typeof existing === 'object') return existing
+  const claim = { owner: null, waiters: new Set() }
+  window[UTILITY_MUTEX_KEY] = claim
+  return claim
+}
+const registerUtilityLauncher = (scope) => {
+  const claim = utilityClaim()
+  if (claim === null) return
+  if (claim.owner !== null) {
+    claim.waiters.add(() => registerUtilityLauncher(scope))
+    return
+  }
+  claim.owner = scope
+  let released = false
+  const release = () => {
+    if (released) return
+    released = true
+    if (claim.owner === scope) claim.owner = null
+    if (window[UTILITY_MUTEX_KEY] !== claim) return
+    const waiters = [...claim.waiters]
+    claim.waiters.clear()
+    for (const wake of waiters) wake()
+  }
+  scope.on('dispose', release)
+  scope.slots.inject('shell.overlay', () => {
+    try {
+      scope.slots.register({
+        name: 'shell.overlay',
+        id: 'utility-launcher',
+        order: 98,
+        children: { [UTILITY_ITEM_SLOT]: { kind: 'list', scope: 'root' } }
+      }, UtilityLauncher)
+    } catch (error) {
+      release()
+      if (typeof console !== 'undefined' && typeof console.error === 'function') {
+        console.error('[utility-launcher] could not register the family launcher', error)
+      }
+    }
+  })
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.3.0",
-  "description": "The DSH plugin family's shared assets: source fragments (the Mini Utility Dock bootstrap for client halves, the loopback predicates and host request guard for host halves), the embedding CLI, and the family diagnostics — cross-repo drift check and bilingual docs structure check.",
+  "version": "0.5.1",
+  "description": "The DSH plugin family's shared assets: source fragments (the loopback predicates and host request guard for host halves, the utility launcher for client halves), the embedding CLI, and the family diagnostics — cross-repo drift check and bilingual docs structure check.",
   "type": "module",
   "bin": {
     "dsh-mini-utility-dock": "bin/dsh-mini-utility-dock.js",

package/dist/bootstrap.js

@@ -1,263 +0,0 @@
-// Mini Utility Dock bootstrap. DSH client artifacts are self-contained classic
-// scripts, so this fragment is embedded at build time. At runtime the dock is a
-// page-local protocol with no package or plugin dependency.
-//
-// Protocol invariants (createhelper.dsh.utility-dock v1), all page-local:
-//   - Exactly one dock container in the page. Whoever loads first creates it;
-//     everyone else joins. Joining never takes over an existing dock.
-//   - register() requires a non-empty `id` and an `onActivate()`; a dock item
-//     is a launcher, and each plugin owns and renders its own panel.
-//   - Activating one item deactivates the others.
-//   - An item's `icon` is untrusted markup: only a presentational inline SVG
-//     reaches the page, anything else renders the label as text.
-//   - The registration disposer carries an ownership token, so a stale HMR
-//     disposer cannot delete a newer registration for the same id.
-//   - Placement is shared and persisted; `hidden` keeps a recovery entry.
-
-const DOCK_KEY = '__CREATEHELPER_DSH_UTILITY_DOCK_V1__'
-const DOCK_PROTOCOL = 'createhelper.dsh.utility-dock'
-const DOCK_VERSION = 1
-const DOCK_PLACEMENT_KEY = 'createhelper.utilityDock.placement'
-const DOCK_CSS_ID = 'createhelper-utility-dock'
-const DOCK_SNAPSHOT = 'createhelper.utility-dock/1+placement'
-const DOCK_LEFT_FALLBACK_PX = 80
-
-const warnDockGeometry = (left) => {
-  if (typeof console === 'undefined' || typeof console.warn !== 'function') return
-  console.warn('[dsh-mini-utility-dock] shell geometry unavailable; falling back to left=' + left + 'px')
-}
-
-const isCompatibleDock = (value) => !!value &&
-  typeof value.register === 'function' &&
-  typeof value.setPlacement === 'function' &&
-  typeof value.getPlacement === 'function' &&
-  // Builds before the protocol metadata shipped already implemented v1.
-  (value.protocol === undefined ||
-    (value.protocol === DOCK_PROTOCOL && value.version === DOCK_VERSION))
-
-/**
- * Dock chrome styles live here because the creator owns the container. Both
- * shipped plugins previously carried their own copy of these five rules, so a
- * dock created by the plugin that happens to load second still painted.
- */
-function ensureUtilityDockStyles() {
-  if (typeof document === 'undefined') return
-  if (document.querySelector('style[data-plugin-css="' + DOCK_CSS_ID + '"]') !== null) return
-  const styleEl = document.createElement('style')
-  styleEl.setAttribute('data-plugin-css', DOCK_CSS_ID)
-  styleEl.textContent =
-    '.createhelper-utility-dock{position:fixed;bottom:16px;z-index:9997;display:flex;align-items:center;gap:2px;padding:3px;border:1px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-alias-bg-overlay);box-shadow:0 6px 22px rgba(0,0,0,.24);pointer-events:auto}' +
-    '.createhelper-utility-dock[hidden]{display:none}' +
-    '.createhelper-utility-dock-item{width:32px;height:32px;display:inline-flex;align-items:center;justify-content:center;padding:0;border:0;border-radius:9px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer}' +
-    '.createhelper-utility-dock-item:hover,.createhelper-utility-dock-item[aria-pressed="true"]{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}' +
-    '.createhelper-utility-dock-item svg{display:block}'
-  document.head.appendChild(styleEl)
-}
-
-/**
- * An item's `icon` is markup another plugin hands to `innerHTML`, so the dock —
- * not each registrant — owns what reaches the page. Admit a single inline SVG
- * whose tags and attributes are presentational; `href`, `style`, `on*`,
- * `<script>` and `<foreignObject>` are exactly the shapes that turn an icon
- * into a script, and none of them draws a glyph.
- */
-const DOCK_ICON_TAGS = /^(svg|g|path|rect|circle|ellipse|line|polyline|polygon)$/i
-const DOCK_ICON_ATTRS = /^(width|height|viewBox|preserveAspectRatio|fill|fill-rule|fill-opacity|stroke|stroke-width|stroke-linecap|stroke-linejoin|stroke-miterlimit|stroke-opacity|stroke-dasharray|stroke-dashoffset|opacity|d|x|y|x1|y1|x2|y2|rx|ry|cx|cy|r|points|transform|role|aria-hidden|focusable|class)$/i
-
-function safeDockIcon(icon) {
-  if (typeof icon !== 'string') return false
-  const markup = icon.trim()
-  if (!/^<svg(?:\s|>)/i.test(markup) || !/<\/svg>$/i.test(markup)) return false
-  // A comment, CDATA or processing instruction can carry markup the scans below
-  // never look at.
-  if (/<!--|<!\[CDATA\[|<\?|]]>/.test(markup)) return false
-  // Splitting on `"` pairs the quotes up: an even segment count is an unbalanced
-  // quote, and only the odd-index segments are quoted values. A value holding a
-  // tag boundary would move `>` past what the scans below can see.
-  const quoted = markup.split('"')
-  if (quoted.length % 2 === 0) return false
-  for (let i = 1; i < quoted.length; i += 2) {
-    if (/[<>]/.test(quoted[i])) return false
-  }
-  if (/[\s"']on[a-z]+\s*=/i.test(markup)) return false
-  if (/javascript\s*:/i.test(markup)) return false
-  // A same-document fragment reference is how a gradient is painted; anything
-  // else turns a presentational attribute into a network read.
-  if (/url\(\s*(?!#)/i.test(markup)) return false
-  const tags = markup.match(/<\/?[a-zA-Z][^>]*>/g)
-  if (!tags) return false
-  for (const tag of tags) {
-    const name = /^<\/?\s*([^/>\s]+)/.exec(tag)
-    if (!name || !DOCK_ICON_TAGS.test(name[1])) return false
-    for (const raw of tag.match(/[^=<>\s]+\s*=/g) || []) {
-      if (!DOCK_ICON_ATTRS.test(raw.replace(/\s*=$/, ''))) return false
-    }
-  }
-  return true
-}
-
-/** Two characters stand in for an icon the dock could not admit. */
-function dockIconFallback(item) {
-  const label = String(item.label || item.id || '')
-  return label.slice(0, 2)
-}
-
-/**
- * A missing, blank, or non-string `label` would reach `render()` as `undefined`
- * and produce aria-label="undefined". `id` is always present (register() rejects
- * an empty one), so it is the safe, meaningful accessible name. Normalize once
- * on store — not at every render — so the stored item is always valid.
- */
-const normalizeDockLabel = (item) => {
-  const label = typeof item.label === 'string' ? item.label.trim() : ''
-  return label || item.id
-}
-
-function getUtilityDock() {
-  if (isCompatibleDock(window[DOCK_KEY])) return window[DOCK_KEY]
-  ensureUtilityDockStyles()
-  const items = new Map()
-  let root = null
-  let resizeObserver = null
-  let mutationObserver = null
-  const readPlacement = () => {
-    try {
-      const value = localStorage.getItem(DOCK_PLACEMENT_KEY)
-      if (value === 'main-bottom-right' || value === 'hidden') return value
-    } catch (e) { }
-    return 'main-bottom-left'
-  }
-  let placement = readPlacement()
-  const findShellFrame = () => {
-    const overlay = document.querySelector('[data-shell-overlay]')
-    return (overlay && overlay.parentElement) || null
-  }
-  let geometryWarned = false
-  const measureDockLeft = () => {
-    const frame = findShellFrame()
-    const sidebar = frame && frame.firstElementChild
-    const sidebarRect = sidebar && typeof sidebar.getBoundingClientRect === 'function'
-      ? sidebar.getBoundingClientRect()
-      : null
-    if (!sidebarRect) {
-      if (!geometryWarned) {
-        geometryWarned = true
-        warnDockGeometry(DOCK_LEFT_FALLBACK_PX)
-      }
-      return DOCK_LEFT_FALLBACK_PX
-    }
-    return Math.max(16, Math.round(sidebarRect.right + 16))
-  }
-  const updateGeometry = () => {
-    if (!root) return
-    root.hidden = placement === 'hidden'
-    root.dataset.placement = placement
-    document.documentElement.dataset.createhelperUtilityDockPlacement = placement
-    root.style.right = ''
-    root.style.left = ''
-    if (placement === 'main-bottom-right') {
-      root.style.right = '16px'
-      return
-    }
-    const left = measureDockLeft()
-    root.style.left = left + 'px'
-    document.documentElement.style.setProperty('--createhelper-utility-dock-left', left + 'px')
-  }
-  const render = () => {
-    if (!root) {
-      root = document.createElement('nav')
-      root.className = 'createhelper-utility-dock'
-      root.setAttribute('aria-label', 'DSH utilities')
-      document.body.appendChild(root)
-      window.addEventListener('resize', updateGeometry)
-      const observeLayout = () => {
-        const frame = findShellFrame()
-        if (!frame) return false
-        mutationObserver?.disconnect()
-        mutationObserver = null
-        if (typeof ResizeObserver === 'function' && !resizeObserver) {
-          resizeObserver = new ResizeObserver(updateGeometry)
-          resizeObserver.observe(frame)
-          if (frame.firstElementChild) resizeObserver.observe(frame.firstElementChild)
-        }
-        updateGeometry()
-        return true
-      }
-      if (!observeLayout() && typeof MutationObserver === 'function') {
-        mutationObserver = new MutationObserver(() => { observeLayout() })
-        mutationObserver.observe(document.body, { childList: true, subtree: true })
-      }
-    }
-    root.replaceChildren()
-    Array.from(items.values()).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)).forEach((item) => {
-      const button = document.createElement('button')
-      button.type = 'button'
-      button.className = 'createhelper-utility-dock-item'
-      button.dataset.createhelperDockItem = item.id
-      button.title = item.label
-      button.setAttribute('aria-label', item.label)
-      button.setAttribute('aria-pressed', item.active ? 'true' : 'false')
-      // Sanitized here, not in register(), so `update({ icon })` cannot be a
-      // second way past the gate.
-      if (safeDockIcon(item.icon)) button.innerHTML = item.icon
-      else button.textContent = dockIconFallback(item)
-      button.addEventListener('click', () => {
-        if (!item.active) {
-          for (const other of items.values()) {
-            if (other.id !== item.id && other.active && typeof other.onDeactivate === 'function') {
-              other.onDeactivate()
-            }
-          }
-        }
-        item.onActivate()
-      })
-      root.appendChild(button)
-    })
-    updateGeometry()
-  }
-  const api = {
-    protocol: DOCK_PROTOCOL,
-    version: DOCK_VERSION,
-    snapshot: DOCK_SNAPSHOT,
-    register(item) {
-      if (!item || typeof item.id !== 'string' || !item.id || typeof item.onActivate !== 'function') {
-        throw new TypeError('utility dock item requires a non-empty id and onActivate()')
-      }
-      const registration = Object.freeze({})
-      items.set(item.id, { ...item, registration, label: normalizeDockLabel(item), order: Number(item.order) || 0, active: !!item.active })
-      render()
-      return {
-        update(patch) {
-          const current = items.get(item.id)
-          if (!current || current.registration !== registration) return
-          const next = { ...current, ...patch }
-          // Keep the stored label valid even when `update({ label })` is passed.
-          next.label = normalizeDockLabel(next)
-          items.set(item.id, next)
-          render()
-        },
-        dispose() {
-          const current = items.get(item.id)
-          if (!current || current.registration !== registration) return
-          items.delete(item.id)
-          if (items.size) { render(); return }
-          resizeObserver?.disconnect()
-          resizeObserver = null
-          mutationObserver?.disconnect()
-          mutationObserver = null
-          window.removeEventListener('resize', updateGeometry)
-          root?.remove()
-          root = null
-        }
-      }
-    },
-    setPlacement(next) {
-      placement = next === 'main-bottom-right' || next === 'hidden' ? next : 'main-bottom-left'
-      try { localStorage.setItem(DOCK_PLACEMENT_KEY, placement) } catch (e) { }
-      updateGeometry()
-    },
-    getPlacement() { return placement }
-  }
-  window[DOCK_KEY] = api
-  return api
-}