@linxin666/dsh-usage 0.3.23 → 0.4.0

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@linxin666/dsh-usage",
-  "description": "Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a dedicated pet bubble for the current provider",
-  "version": "0.3.23",
+  "description": "Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a compact price glance card above the sidebar's Settings row",
+  "version": "0.4.0",
+  "icon": "icon.svg",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -26,12 +27,13 @@
     "lib/**/*.d.ts",
     "lib/**/*.d.ts.map",
     "src",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "icon.svg"
   ],
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.5-rc.1"
+      "dsh": ">=0.1.7-rc.1"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -51,26 +53,27 @@
     "schemastery": "^3.18.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.7-rc.1",
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-credentials": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
-    "@linxin666/dsh-pet": "0.3.23",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.5",
     "jsdom": "29.1.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

package/src/client/UsageFootCard.tsx

@@ -0,0 +1,300 @@
+/**
+ * Sidebar foot card: the compact usage glance seated below the shell sidebar's
+ * Settings row. It is deliberately a GLANCE, not the panel the 2026-09-18
+ * removal took out. Two states, persisted across reloads:
+ *
+ * - expanded (default): a price-first headline (today's estimated spend,
+ *   falling back to today's tokens when nothing priced was recorded), a
+ *   tokens/calls line, up to two configured-provider balances, and an
+ *   updated-at footer;
+ * - collapsed: a one-line strip with the gauge glyph, the spending
+ *   provider's name, the label and the headline value.
+ *
+ * The card body is one button that opens the settings panel on the usage
+ * section, so detail lives in exactly one place; the corner chevron toggles
+ * the collapse state (sibling buttons — buttons inside a button are invalid
+ * HTML).
+ *
+ * Data comes from the same shared store the settings section reads; the card
+ * runs its own relaxed poll loop (30 s, visible-tab only) because the sidebar
+ * foot is permanently mounted. The card disappears while the plugin is
+ * disabled (settings flag) or while the host serves no usage routes (a 404
+ * means the host half is off), matching the section's own gating.
+ * @module @linxin666/dsh-usage/client/UsageFootCard
+ */
+
+import { useEffect, useState, useSyncExternalStore, type ReactNode } from 'react'
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'
+import { t } from './locales.ts'
+import styles from './usage.module.css'
+import { formatTokens, type UsageSettings } from './UsageSectionCard.tsx'
+import { totalTokens } from '../core/ledger.ts'
+import type { BalanceView, ProviderSnapshotView, UsageOverviewView } from '../core/types.ts'
+import type { UsageStoreInstance } from './usage-store.ts'
+
+/** Props the mount forwards into the React tree. */
+export interface UsageFootCardProps {
+  /** The shared overview store (section and card read the same snapshot). */
+  store: UsageStoreInstance
+  /** Fetch one overview now. */
+  poll: () => void
+  /** Card-body click: open the settings panel on the usage section. */
+  onOpen: () => void
+  /** The shared settings form; the card hides while the plugin is disabled. */
+  settings: ConfigForm<UsageSettings>
+  /** Locale-change source; the plain copy re-renders on a language switch. */
+  locale?: { subscribe(listener: () => void): () => void }
+}
+
+/** Poll cadence of the permanently seated card; the section's 10 s loop stays its own. */
+export const FOOT_CARD_POLL_MS = 30_000
+
+/** localStorage key holding the collapsed flag ('1' = collapsed strip). */
+export const FOOT_CARD_COLLAPSED_KEY = 'dsh-usage.foot-card.collapsed'
+
+/** At most this many provider balances render before a +N overflow marker. */
+const BALANCE_CAP = 2
+
+/** Read the persisted collapsed flag (absent = expanded). */
+export function readFootCardCollapsed(): boolean {
+  try {
+    return window.localStorage.getItem(FOOT_CARD_COLLAPSED_KEY) === '1'
+  } catch {
+    // Storage can be unavailable (privacy modes); the card stays expanded.
+    return false
+  }
+}
+
+/** Persist the collapsed flag; storage failures keep the session state. */
+function writeFootCardCollapsed(collapsed: boolean): void {
+  try {
+    window.localStorage.setItem(FOOT_CARD_COLLAPSED_KEY, collapsed ? '1' : '0')
+  } catch {
+    // Storage unavailable: the state still flips for this session.
+  }
+}
+
+/** Inline gauge glyph, 14px beside the card title. */
+function GaugeIcon(): ReactNode {
+  return (
+    <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M2.5 12.5a7 7 0 0 1 11 -4.3" />
+      <path d="M8 12.5V8.2l2.9-2.1" />
+      <circle cx="8" cy="12.5" r="1" />
+    </svg>
+  )
+}
+
+/** Disclosure chevrons: down collapses the expanded card, up expands the strip. */
+function ChevronIcon(props: { collapsed: boolean }): ReactNode {
+  return props.collapsed
+    ? (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+        <path d="m4 10 4-4 4 4" />
+      </svg>
+    )
+    : (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+        <path d="m4 6 4 4 4-4" />
+      </svg>
+    )
+}
+
+/** A provider row worth showing a balance for: configured, with a probed balance. */
+function balanceRow(provider: ProviderSnapshotView): boolean {
+  const supported = provider.balanceSupported === true || (provider.balanceSupported === undefined && provider.supported)
+  return provider.credential !== 'none' && supported && provider.balance !== undefined
+}
+
+/** Currency-symbol prefix for the priced balances (CNY/USD), else the ISO code. */
+function formatBalance(balance: BalanceView): string {
+  const currency = balance.currency.toUpperCase()
+  if (currency === 'CNY') return '¥' + balance.totalBalance
+  if (currency === 'USD') return '$' + balance.totalBalance
+  return currency + ' ' + balance.totalBalance
+}
+
+function formatClock(ms: number): string {
+  try {
+    return new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Display name of the provider owning today's priced spend: the day's highest
+ * cost row, else the current session route, resolved through the provider
+ * snapshot (an older host without the day rows falls back to the current
+ * route). Undefined when there is no route to name.
+ */
+function spendProvider(snapshot: UsageOverviewView): string | undefined {
+  let top: UsageOverviewView['usage']['today']['providers'][number] | undefined
+  for (const row of snapshot.usage.today.providers) {
+    if (row.totals.cost <= 0) continue
+    if (top === undefined || row.totals.cost > top.totals.cost) top = row
+  }
+  const route = top?.provider ?? snapshot.current.provider
+  if (route === undefined) return undefined
+  return snapshot.providers.find((entry) => entry.provider === route)?.displayName
+    ?? (route === snapshot.current.provider ? snapshot.current.displayName : undefined)
+    ?? route
+}
+
+/**
+ * The headline triple: today's priced spend, else today's tokens, else zero.
+ * tokenFallback tells the sub-line to keep only the call count instead of
+ * repeating the total the headline already shows; provider names the spender
+ * beside the collapsed cost headline.
+ */
+function headline(snapshot: UsageOverviewView): { label: string; value: string; tokenFallback: boolean; provider?: string } {
+  const totals = snapshot.usage.today.totals
+  if (totals.cost > 0) return { label: t('usage.foot.cost'), value: '¥' + totals.cost.toFixed(2), tokenFallback: false, provider: spendProvider(snapshot) }
+  if (totals.calls > 0) return { label: t('usage.today'), value: formatTokens(totalTokens(totals)) + ' tokens', tokenFallback: true }
+  return { label: t('usage.foot.cost'), value: '¥0.00', tokenFallback: false }
+}
+
+/** The tokens/calls sub-line under the headline; a quiet no-data line on an empty day. */
+function usageLine(snapshot: UsageOverviewView, tokenFallback: boolean): string {
+  const totals = snapshot.usage.today.totals
+  if (totals.calls === 0) return t('usage.foot.noData')
+  const calls = t('usage.calls', { n: totals.calls })
+  return tokenFallback ? calls : formatTokens(totalTokens(totals)) + ' tokens · ' + calls
+}
+
+/** The balance line: up to BALANCE_CAP providers plus a +N overflow marker. */
+function balanceLine(snapshot: UsageOverviewView): string | undefined {
+  const rows = snapshot.providers.filter(balanceRow)
+  if (rows.length === 0) return undefined
+  const shown = rows.slice(0, BALANCE_CAP).map((provider) => provider.displayName + ' ' + formatBalance(provider.balance!))
+  return shown.join(' · ') + (rows.length > BALANCE_CAP ? ' +' + String(rows.length - BALANCE_CAP) : '')
+}
+
+/** Card chrome classes for the current collapse state. */
+function cardClass(collapsed: boolean): string {
+  return collapsed ? styles.footCard + ' ' + styles.footCardCollapsed : styles.footCard
+}
+
+/**
+ * Render the foot card content for the current store snapshot.
+ * @param props - store, poller, settings form and open callback from the mount.
+ * @returns the card, or null while disabled / host-off.
+ */
+export function UsageFootCard(props: UsageFootCardProps): ReactNode {
+  const { store, poll, onOpen, settings, locale } = props
+  const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
+  // Settings writes and locale switches both re-render the card's copy/visibility.
+  const [, bump] = useState(0)
+  useEffect(() => settings.subscribe(() => bump((count) => count + 1)), [settings])
+  useEffect(() => locale?.subscribe(() => bump((count) => count + 1)), [locale])
+  const enabled = settings.getSnapshot().value?.enabled ?? true
+
+  // The collapse choice is one localStorage flag, read at mount and persisted
+  // on every flip (the old sidebar strip used the same contract shape).
+  const [collapsed, setCollapsed] = useState(readFootCardCollapsed)
+  const toggleCollapsed = (): void => {
+    setCollapsed((current) => {
+      writeFootCardCollapsed(!current)
+      return !current
+    })
+  }
+
+  // The permanently seated card pays a relaxed cadence; a hidden tab pauses.
+  useEffect(() => {
+    if (!enabled) return undefined
+    poll()
+    let timer: number | undefined
+    const start = (): void => {
+      if (timer === undefined && document.visibilityState === 'visible') timer = window.setInterval(poll, FOOT_CARD_POLL_MS)
+    }
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'visible') {
+        poll()
+        start()
+      } else if (timer !== undefined) {
+        window.clearInterval(timer)
+        timer = undefined
+      }
+    }
+    start()
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      if (timer !== undefined) window.clearInterval(timer)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [poll, enabled])
+
+  if (!enabled) return null
+  const snapshot = ui.snapshot
+  // A 404 means the host half serves no usage routes (plugin off): the card
+  // bows out instead of pinning a permanent error to the sidebar foot.
+  if (snapshot === null && ui.status === 'error' && /failed: 404/.test(ui.error ?? '')) return null
+
+  const toggle = (
+    <button
+      type="button"
+      className={styles.footToggle}
+      data-dsh-part="foot-card-toggle"
+      aria-label={t(collapsed ? 'usage.foot.expand' : 'usage.foot.collapse')}
+      title={t(collapsed ? 'usage.foot.expand' : 'usage.foot.collapse')}
+      onClick={toggleCollapsed}
+    >
+      <ChevronIcon collapsed={collapsed} />
+    </button>
+  )
+
+  if (snapshot === null) {
+    const quiet = ui.status === 'error' ? t('usage.error', { error: ui.error ?? '' }) : t('usage.loading')
+    return (
+      <div className={cardClass(collapsed)} data-dsh-plugin="usage" data-dsh-part="foot-card">
+        <button type="button" className={styles.footMain} data-dsh-part="foot-card-main" aria-label={t('usage.foot.open')} title={t('usage.foot.open')} onClick={onOpen}>
+          {collapsed
+            ? <span className={styles.footStrip} data-dsh-part="foot-card-strip"><GaugeIcon /><span className={styles.footStripValue}>—</span></span>
+            : (
+              <>
+                <span className={styles.footHead}>
+                  <span className={styles.footTitle}><GaugeIcon />{t('usage.title')}</span>
+                </span>
+                <span className={styles.footLine}>{quiet}</span>
+              </>
+            )}
+        </button>
+        {toggle}
+      </div>
+    )
+  }
+
+  const head = headline(snapshot)
+  const balances = balanceLine(snapshot)
+
+  if (collapsed) {
+    return (
+      <div className={cardClass(true)} data-dsh-plugin="usage" data-dsh-part="foot-card">
+        <button type="button" className={styles.footMain} data-dsh-part="foot-card-main" aria-label={t('usage.foot.open')} title={t('usage.foot.open')} onClick={onOpen}>
+          <span className={styles.footStrip} data-dsh-part="foot-card-strip">
+            <GaugeIcon />
+            {head.provider !== undefined && <span className={styles.footStripProvider}>{head.provider}</span>}
+            <span className={styles.footStripLabel}>{head.label}</span>
+            <span className={styles.footStripValue}>{head.value}</span>
+          </span>
+        </button>
+        {toggle}
+      </div>
+    )
+  }
+
+  return (
+    <div className={cardClass(false)} data-dsh-plugin="usage" data-dsh-part="foot-card">
+      <button type="button" className={styles.footMain} data-dsh-part="foot-card-main" aria-label={t('usage.foot.open')} title={t('usage.foot.open')} onClick={onOpen}>
+        <span className={styles.footHead}>
+          <span className={styles.footTitle}><GaugeIcon />{head.label}</span>
+          <span className={styles.footValue}>{head.value}</span>
+        </span>
+        <span className={styles.footLine} data-dsh-part="foot-card-usage">{usageLine(snapshot, head.tokenFallback)}</span>
+        {balances !== undefined && <span className={styles.footLine} data-dsh-part="foot-card-balances">{balances}</span>}
+        <span className={styles.footMeta}>{t('usage.updated', { time: formatClock(snapshot.updatedAt) })}</span>
+      </button>
+      {toggle}
+    </div>
+  )
+}

package/src/client/UsageSectionCard.tsx

@@ -9,7 +9,7 @@
  */
 
 import { useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { UsageStoreInstance } from './usage-store.ts'
 import { t } from './locales.ts'
 import styles from './usage.module.css'
@@ -22,7 +22,6 @@ import type { ObservedSpendView, ProviderSnapshotView, UsageOverviewView, UsageP
 export interface UsageSettings {
   enabled?: boolean
   pollIntervalSec?: number
-  bubbleMode?: string
 }
 
 /** The registration-side face the section's slot entry injects. */
@@ -33,8 +32,8 @@ export interface UsageSectionFace {
   poll: () => void
   /** Force a host probe cycle now (resolves with the fresh overview). */
   refresh: () => void
-  /** Whether a forced refresh is in flight (component-local state mirrors it). */
-  settings: SettingsScope<UsageSettings>
+  /** The shared configuration form this section's settings row reads and writes. */
+  settings: ConfigForm<UsageSettings>
 }
 
 export interface UsageSectionProps extends UsageSectionFace {
@@ -154,9 +153,10 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
   const settingsValue = settingsSnapshot.value ?? {}
   const [tab, setTab] = useState<'usage' | 'plans' | 'bank'>('usage')
   const [refreshing, setRefreshing] = useState(false)
-  // The enable checkbox writes through the settings scope, so subscribing here
-  // keeps the flag below live: the poll starts and stops with it instead of
-  // waiting for an unrelated render.
+  // The enable checkbox writes through the shared form, so subscribing here
+  // keeps the flag below live: the form republishes the Host's accepted value,
+  // and the poll starts and stops with it instead of waiting for an unrelated
+  // render.
   const [, bumpSettings] = useState(0)
   useEffect(() => settings.subscribe(() => bumpSettings((count) => count + 1)), [settings])
   const enabled = settingsValue.enabled ?? true
@@ -534,14 +534,39 @@ function PlanCard(props: { provider: ProviderSnapshotView; current?: string }):
   )
 }
 
+/**
+ * The compact settings row. Both controls write through the shared form the
+ * moment the user changes them, and the Host answers each write with a
+ * boolean: a refused (or transport-failed) write is surfaced as a failed save,
+ * because a value that did not land must never read as applied.
+ */
 function SettingsRow(props: {
   settings: UsageSectionProps['settings']
-  snapshot?: { writable: boolean }
+  snapshot?: ConfigFormSnapshot<UsageSettings>
   value: UsageSettings
 }): ReactNode {
   const { settings, snapshot, value } = props
   const disabled = snapshot === undefined || !snapshot.writable
-  const bubbleMode = typeof value.bubbleMode === 'string' && ['always', 'change', 'off'].includes(value.bubbleMode) ? value.bubbleMode : 'always'
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+
+  const write = (field: 'enabled' | 'pollIntervalSec', next: boolean | number): void => {
+    setFailure(undefined)
+    let answer: Promise<boolean>
+    try {
+      answer = settings.set(field, next)
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : String(error))
+      return
+    }
+    // false is the contract's refusal/skip answer (the Host rejected the value,
+    // the entry is not writable, or the write was dropped); a rejecting
+    // transport reports through the same failed-save surface.
+    Promise.resolve(answer).then(
+      (accepted) => { if (!accepted) setFailure('') },
+      (error: unknown) => { setFailure(error instanceof Error ? error.message : String(error)) },
+    )
+  }
+
   return (
     <div className={styles.card} data-dsh-part="settings-row">
       <span className={styles.cardTitle}>{t('usage.config.title')}</span>
@@ -551,7 +576,7 @@ function SettingsRow(props: {
             type="checkbox"
             checked={value.enabled ?? true}
             disabled={disabled}
-            onChange={(event) => { void settings.set('enabled', event.target.checked) }}
+            onChange={(event) => { write('enabled', event.target.checked) }}
           />
           {t('usage.config.enabled')}
         </label>
@@ -565,23 +590,16 @@ function SettingsRow(props: {
             disabled={disabled}
             onChange={(event) => {
               const parsed = Number(event.target.value)
-              if (Number.isFinite(parsed) && parsed >= 30 && parsed <= 3600) void settings.set('pollIntervalSec', Math.round(parsed))
+              if (Number.isFinite(parsed) && parsed >= 30 && parsed <= 3600) write('pollIntervalSec', Math.round(parsed))
             }}
           />
         </label>
-        <label className={styles.settingItem}>
-          {t('usage.config.bubbleMode')}
-          <select
-            value={bubbleMode}
-            disabled={disabled}
-            onChange={(event) => { void settings.set('bubbleMode', event.target.value) }}
-          >
-            <option value="always">{t('usage.config.bubbleMode.always')}</option>
-            <option value="change">{t('usage.config.bubbleMode.change')}</option>
-            <option value="off">{t('usage.config.bubbleMode.off')}</option>
-          </select>
-        </label>
       </div>
+      {failure !== undefined && (
+        <span className={styles.errorLine} role="status">
+          {t('usage.config.saveFailed')}{failure === '' ? '' : ' - ' + failure}
+        </span>
+      )}
     </div>
   )
 }

package/src/client/body-mutations.ts

@@ -0,0 +1,133 @@
+// Generated by scripts/sync-shared.mjs from shared/client/body-mutations.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * One `document.body` MutationObserver per page, shared by every family
+ * plugin bundle.
+ *
+ * Family plugins that inject at the DOM level must notice when the shell
+ * re-renders around their injected node: the sidebar entry rows
+ * (sidebar-entry-core), the center-column panel containers
+ * (panel-mount-core), and the aggregate shell's column shims. Each consumer
+ * used to install its OWN `MutationObserver` on `document.body` with
+ * `{ childList: true, subtree: true }`, so a page carrying N family plugins
+ * paid N native observers and N callback invocations for EVERY mutation batch
+ * the app produced — chat token streaming alone produces many per second, and
+ * the count grows with the number of installed plugins.
+ *
+ * This module keeps exactly ONE body observer per page. The registry lives on
+ * `globalThis` under a `Symbol.for` key, so the per-package generated copies
+ * of this file (scripts/sync-shared.mjs) and separately bundled plugins all
+ * reach the same hub at runtime instead of one hub per module instance.
+ * Record subscribers receive the mutations accumulated since the last flush.
+ * Consumers that only re-check their DOM use subscribeBodyInvalidations:
+ * when all subscribers use that path, the hub retains no mutation records
+ * (or detached subtrees) while a background page's animation frames pause.
+ * Both paths run at most once per frame. The last subscriber disconnects the
+ * observer, cancels the pending frame and releases its records.
+ *
+ * Failure policy: without a DOM or `MutationObserver` the subscription is a
+ * no-op disposer (the same silence the per-consumer observers had), and when
+ * `requestAnimationFrame` is unavailable the flush runs synchronously so a
+ * subscriber is never silently dropped. A throwing subscriber cannot stop the
+ * others.
+ */
+
+/** The page-wide hub: one observer plus its subscribers and pending records. */
+interface BodyMutationHub {
+  observer: MutationObserver
+  subscribers: Set<(records: MutationRecord[]) => void>
+  pending: MutationRecord[]
+  scheduled: boolean
+  frame?: number
+}
+
+/** Cross-bundle registry key; `Symbol.for` so every module copy agrees. */
+const HUB_KEY = Symbol.for('dsh-web.body-mutation-hub')
+const INVALIDATION_ONLY = Symbol.for('dsh-web.body-mutation-invalidation')
+type Subscriber = ((records: MutationRecord[]) => void) & { [INVALIDATION_ONLY]?: true }
+
+function needsRecords(subscribers: Set<(records: MutationRecord[]) => void>): boolean {
+  for (const listener of subscribers) {
+    if (!(listener as Subscriber)[INVALIDATION_ONLY]) return true
+  }
+  return false
+}
+
+/**
+ * Subscribe to a coalesced DOM re-check without retaining mutation records.
+ * The marked wrapper also works with an older hub, which delivers records
+ * that it simply ignores until a page reload picks up the updated hub.
+ */
+export function subscribeBodyInvalidations(subscriber: () => void): () => void {
+  const listener: Subscriber = () => { subscriber() }
+  listener[INVALIDATION_ONLY] = true
+  return subscribeBodyMutations(listener)
+}
+
+/**
+ * Subscribe to body-level childList mutations.
+ * @param subscriber - called at most once per animation frame with the records
+ *   collected since the previous flush; must be safe to run repeatedly.
+ * @returns the disposer removing this subscriber (and the observer when it was
+ *   the last one).
+ */
+export function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void {
+  if (typeof globalThis === 'undefined' || typeof document === 'undefined') return () => {}
+  if (typeof MutationObserver !== 'function') return () => {}
+  const registry = globalThis as unknown as Record<symbol, unknown>
+  let hub = registry[HUB_KEY] as BodyMutationHub | undefined
+  if (hub === undefined) {
+    const subscribers = new Set<(records: MutationRecord[]) => void>()
+    const created: BodyMutationHub = {
+      observer: undefined as unknown as MutationObserver,
+      subscribers,
+      pending: [],
+      scheduled: false,
+    }
+    const flush = (): void => {
+      created.frame = undefined
+      created.scheduled = false
+      const batch = created.pending
+      created.pending = []
+      for (const listener of [...subscribers]) {
+        if (!subscribers.has(listener)) continue
+        try {
+          listener(batch)
+        } catch {
+          // One subscriber must never break the others; the next flush retries it.
+        }
+      }
+    }
+    const schedule = (): void => {
+      if (created.scheduled) return
+      created.scheduled = true
+      if (typeof requestAnimationFrame === 'function') created.frame = requestAnimationFrame(flush)
+      else flush()
+    }
+    created.observer = new MutationObserver((records) => {
+      if (needsRecords(subscribers)) {
+        for (const record of records) created.pending.push(record)
+      }
+      schedule()
+    })
+    created.observer.observe(document.body ?? document.documentElement, { childList: true, subtree: true })
+    registry[HUB_KEY] = created
+    hub = created
+  }
+  const active = hub
+  active.subscribers.add(subscriber)
+  let subscribed = true
+  return () => {
+    if (!subscribed) return
+    subscribed = false
+    active.subscribers.delete(subscriber)
+    if (!needsRecords(active.subscribers)) active.pending = []
+    if (active.subscribers.size === 0 && registry[HUB_KEY] === active) {
+      active.observer.disconnect()
+      if (active.frame !== undefined && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(active.frame)
+      active.frame = undefined
+      active.pending = []
+      active.scheduled = false
+      delete registry[HUB_KEY]
+    }
+  }
+}