dsh-mini-utility-dock 0.1.0 → 0.1.2

package/CHANGELOG.en.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.2 - 2026-09-06
+
+- Fix the README `npm run dock:embed` examples: add the previously missing `dock:embed` script to `package.json` and switch the usage to `npm run dock:embed -- check|sync path/to/client.js` (npm argument passing needs the `--` separator, and the CLI takes `sync|check` subcommands, not `--check`). A new smoke test extracts the documented commands from both READMEs and runs them, preventing docs/script drift.
+
+## 0.1.1 - 2026-09-04
+
+- Normalize `label` in `register()`: a missing, blank, or non-string label falls back to `id`, so no item renders `aria-label="undefined"`.
+
 ## 0.1.0
 
 - Add the Mini Utility Dock protocol v1 bootstrap.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.2 - 2026-09-06
+
+- 修正 README 的 `npm run dock:embed` 示例：补上 `package.json` 缺失的 `dock:embed` 脚本，用法改为 `npm run dock:embed -- check|sync path/to/client.js`（npm 传参需要 `--` 分隔符，CLI 接受 `sync|check` 子命令而非 `--check`）。新增从双语 README 提取命令逐条执行的 smoke test，防止文档与脚本漂移。
+
+## 0.1.1 - 2026-09-04
+
+- 归一化 `register()` 的 `label`：缺省、空白或非字符串的 `label` 回退为 `id`，避免渲染出 `aria-label="undefined"`。
+
 ## 0.1.0
 
 - Add the Mini Utility Dock protocol v1 bootstrap.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 PracticalIssue
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 PracticalIssue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -10,3 +10,12 @@ Put these markers in the client file:
 ```
 
 Run `npx dsh-mini-utility-dock sync path/to/client.js` to embed the current fragment, or `... check ...` in CI. Marker indentation is preserved. The fragment deduplicates itself through the page-local global protocol v1.
+
+You can also embed from this repo's own script (it never hard-codes a consumer path; the target is passed by the caller):
+
+```sh
+npm run dock:embed -- check path/to/client.js  # verify only, non-zero on drift
+npm run dock:embed -- sync path/to/client.js   # write between the markers
+```
+
+When registering, a missing, blank, or non-string `label` falls back to `id` as the accessible name, avoiding `aria-label="undefined"`.

package/README.md

@@ -19,3 +19,12 @@ npx dsh-mini-utility-dock check path/to/client.js
 ```
 
 `sync` 保留标记及其缩进；`check` 在内容漂移时以非零状态退出。内嵌脚本通过 global protocol v1 在页面内去重，插件仍可单独运行。
+
+也可用本仓库脚本同步（不硬编码任何消费仓路径，目标由调用方传入）：
+
+```sh
+npm run dock:embed -- check path/to/client.js  # 仅校验，漂移时非零退出
+npm run dock:embed -- sync path/to/client.js   # 写入标记之间
+```
+
+注册时若 `label` 缺省、空白或非字符串，会回退为 `id` 作为可访问名称，避免 `aria-label="undefined"`。

package/dist/bootstrap.js

@@ -1,23 +1,23 @@
 // 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'
+//
+// 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
@@ -26,95 +26,106 @@ 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)
-}
-
-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'
+
+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 = () => {
@@ -138,112 +149,115 @@ function getUtilityDock() {
     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
-    }
+    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 = () => {
+    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, order: Number(item.order) || 0, active: !!item.active })
-      render()
-      return {
-        update(patch) {
-          const current = items.get(item.id)
-          if (!current || current.registration !== registration) return
-          items.set(item.id, { ...current, ...patch })
-          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
-}
+        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
+}

package/package.json

@@ -1,20 +1,36 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared classic-script utility dock protocol for DSH plugins.",
   "type": "module",
   "bin": {
     "dsh-mini-utility-dock": "bin/dsh-mini-utility-dock.js"
   },
-  "files": ["bin", "dist", "README.md", "README.en.md", "LICENSE", "CHANGELOG.md", "CHANGELOG.en.md"],
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CHANGELOG.en.md"
+  ],
   "scripts": {
+    "dock:embed": "node bin/dsh-mini-utility-dock.js",
     "test": "node --test test/*.test.js"
   },
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xswt442-cmd/dsh-mini-utility-dock.git"
   },
-  "keywords": ["dsh", "deepseek-harness", "dsh-plugin", "utility-dock"],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "utility-dock"
+  ],
   "license": "MIT"
 }