dsh-mini-utility-dock 0.5.1 → 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()
@@ -156,11 +159,11 @@ function UtilityLauncher (props) {
 // 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.
+// 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]
@@ -199,7 +202,7 @@ const registerUtilityLauncher = (scope) => {
     } catch (error) {
       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.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.",
+  "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",