dsh-mini-utility-dock 0.5.0 → 0.6.0

package/dist/launcher.js

@@ -1,18 +1,20 @@
-// Family utility launcher shared by the browser halves of the DSH plugins.
+// The shared launcher assembly: one icon plus the menu of panels it opens, for a
+// plugin's browser half.
 //
 // 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
+// instead of being imported: a bare import would put a runtime dependency on
+// this package into the bundle that embeds it, and an embedding plugin ships
 // standalone, with nothing else required.
 //
-// The launcher is one icon that opens a menu of family panels. It is contributed
+// The launcher is one icon that opens a menu of utility 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.
+// assembly runs per page — the first to load wins the window mutex, registers the
+// launcher, and declares the menu seat — while the other copies register nothing
+// here and only wait to take the claim over once their owner is disposed.
 const UTILITY_ITEM_SLOT = 'createhelper.utility.item'
 const UTILITY_MUTEX_KEY = '__CREATEHELPER_DSH_UTILITY_LAUNCHER_V1__'
 const UTILITY_CSS_ID = 'createhelper-utility-launcher'
@@ -21,7 +23,7 @@ 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
+// The rows are other plugins' components, so the menu styles its buttons by
 // position instead of asking every contributor for a class name.
 function ensureUtilityStyles() {
   if (typeof document === 'undefined') return
@@ -41,8 +43,9 @@ function ensureUtilityStyles() {
   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.
+// The launcher tracks the shell's sidebar column rather than a fixed offset: its
+// left edge sits 16px right of the sidebar's edge, and 80px while the shell has
+// not laid that column out yet.
 const measureUtilityLeft = () => {
   if (typeof document === 'undefined') return UTILITY_FALLBACK_LEFT_PX
   const overlay = document.querySelector('[data-shell-overlay]')
@@ -105,7 +108,7 @@ const useUtilityMenu = () => {
 // 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.
+// belong to other plugins, not to this block.
 function UtilityLauncher (props) {
   const left = useUtilityLeft()
   const open = useUtilityMenu()
@@ -155,9 +158,39 @@ function UtilityLauncher (props) {
 // 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. Any plugin that
+// embeds this block may win the claim, 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 on the page, 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) => {
-  if (typeof window === 'undefined' || window[UTILITY_MUTEX_KEY] === true) return
-  window[UTILITY_MUTEX_KEY] = true
+  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({
@@ -167,9 +200,9 @@ const registerUtilityLauncher = (scope) => {
         children: { [UTILITY_ITEM_SLOT]: { kind: 'list', scope: 'root' } }
       }, UtilityLauncher)
     } catch (error) {
-      window[UTILITY_MUTEX_KEY] = false
+      release()
       if (typeof console !== 'undefined' && typeof console.error === 'function') {
-        console.error('[utility-launcher] could not register the family launcher', error)
+        console.error('[utility-launcher] could not register the launcher', error)
       }
     }
   })

package/dist/loopback.js

@@ -1,28 +1,25 @@
-// Loopback predicates shared by the host halves of the DSH plugins.
+// The loopback predicates: which Host names and which peer addresses count as
+// loopback, for a plugin's host half that binds an API to the loopback interface.
 //
 // This fragment has ONE source of truth: dsh-mini-utility-dock/dist/loopback.js.
-// DSH plugin host halves are plain Node ESM that each package ships standalone,
-// so the fragment is embedded into `lib/shared.js` at build time by
+// A host half is plain Node ESM that its package ships standalone, so the
+// fragment is embedded into `lib/shared.js` at build time by
 //   npm run loopback:sync    (write it)
 //   npm run loopback:check   (fail on drift)
 // instead of being imported: a bare `import 'dsh-mini-utility-dock/...'` 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.
-//
-// Why it is shared at all: these predicates were copy-pasted per repo and
-// drifted twice. The first drift rejected IPv6 loopback everywhere; the second
-// is that consumers disagreed on which Host spellings count as loopback
-// (see the parity bin this package ships, which compares this block across repositories).
+// put a runtime dependency on this package into the file that embeds it, and an
+// embedding plugin ships standalone, with nothing else required.
 //
 // "Loopback" is decided in exactly one place — LOOPBACK_HOSTNAMES plus the
 // IPv4-mapped IPv6 form of each entry — and both the name and the address
-// predicate route through it, so the Host path and the peer path cannot drift
-// apart again.
+// predicate route through it, so the Host path and the peer path cannot
+// disagree. Every spelling this file accepts is a documented one; anything
+// unrecognised fails closed.
 //
 // Kept a separate fragment from the host guard on purpose: the predicates are
 // stable facts about what an address is, while the guard is a policy about who
-// may call an API. `dist/guard.js` imports this module, so the guard depends on
-// this block and never the other way round.
+// may call an API. The guard block reads the names this block declares, so it
+// depends on this block and never the other way round.
 
 // Hostnames a request to a loopback-bound API may legitimately arrive with.
 // Exact spellings only: `api.localhost` and `127.0.0.1.evil.example` must stay

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.5.0",
-  "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.",
+  "version": "0.6.0",
+  "description": "The DSH plugin family's shared assets: source fragments (the loopback predicates, host request guard and host HTTP glue 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",
@@ -29,6 +29,11 @@
     "type": "git",
     "url": "git+https://github.com/xswt442-cmd/dsh-mini-utility-dock.git"
   },
+  "homepage": "https://github.com/xswt442-cmd/dsh-mini-utility-dock#readme",
+  "bugs": {
+    "url": "https://github.com/xswt442-cmd/dsh-mini-utility-dock/issues"
+  },
+  "author": "xswt442-cmd",
   "keywords": [
     "dsh",
     "deepseek-harness",