@linxin666/dsh-client-ui-task-board 0.4.2 → 0.4.4

package/src/protocol.ts

@@ -1,15 +1,18 @@
 import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
 import { isTaskPermission, isTaskStatus, isTaskTagList, type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts'
 import { parseLedger } from './core/store.ts'
+import { isValidTimeZone } from './core/schedule.ts'
 import { sanitizeFreezeSnapshot, type FreezeSnapshot } from './core/freeze-snapshot.ts'
 import { sanitizeHandover, type TaskHandoverInput } from './core/handover.ts'
 
 /** Freeze payload carried by create/update actions after the gate (redacted in place). */
 type FreezePayload = FreezeSnapshot & { redacted?: boolean; frozenBy?: string }
 
-export const TASK_BOARD_SCHEMA_VERSION = 3 as const
-/** Ledger documents written before v3; loaded once and migrated on startup. */
-export const TASK_BOARD_LEGACY_SCHEMA_VERSION = 2 as const
+export const TASK_BOARD_SCHEMA_VERSION = 4 as const
+/** Ledger documents written before v4; loaded once and migrated on startup. */
+export const TASK_BOARD_LEGACY_SCHEMA_VERSION = 3 as const
+/** Ledger documents written before v3; migrated through the v3 normalization too. */
+export const TASK_BOARD_OLDER_SCHEMA_VERSION = 2 as const
 export const TASK_BOARD_API_PREFIX = '/api/task-board'
 
 export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported'
@@ -101,7 +104,8 @@ export type TaskBoardAction =
   | { kind: 'move'; taskId: string; status: TaskStatus }
   | { kind: 'archive'; taskId: string }
   | { kind: 'restore'; taskId: string }
-  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string } }
+  | { kind: 'settle'; taskId: string }
+  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string; timeZone?: string | null } }
   | { kind: 'run'; taskId: string }
   | { kind: 'rerun'; taskId: string }
   | { kind: 'confirm-permission'; taskId: string }
@@ -154,6 +158,8 @@ function validImportedKnownFields(value: Record<string, unknown>): boolean {
     const schedule = record(value.schedule)
     if (schedule === undefined || typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
     if (!optionalFiniteNumber(schedule.nextRunAt) || !optionalFiniteNumber(schedule.lastTriggeredAt)) return false
+    if (schedule.timeZone !== undefined
+      && (typeof schedule.timeZone !== 'string' || !isValidTimeZone(schedule.timeZone))) return false
   }
   if (value.executions !== undefined) {
     if (!Array.isArray(value.executions)) return false
@@ -199,6 +205,7 @@ function importedTask(value: unknown): TaskRecord | undefined {
       schedule: {
         enabled: task.schedule.enabled,
         cron: task.schedule.cron,
+        ...(task.schedule.timeZone === undefined ? {} : { timeZone: task.schedule.timeZone }),
         nextRunAt: task.schedule.nextRunAt,
         lastTriggeredAt: task.schedule.lastTriggeredAt,
       },
@@ -210,6 +217,7 @@ function importedTask(value: unknown): TaskRecord | undefined {
     ...(task.mode === undefined ? {} : { mode: task.mode }),
     ...(task.permission === undefined ? {} : { permission: task.permission }),
     ...(task.reuseSession === undefined ? {} : { reuseSession: task.reuseSession }),
+    ...(task.goalRun === undefined ? {} : { goalRun: task.goalRun }),
     ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
     ...(task.freeze === undefined ? {} : { freeze: task.freeze }),
     ...(task.handover === undefined ? {} : { handover: task.handover }),
@@ -247,30 +255,36 @@ function handoverPayload(value: unknown): TaskHandoverInput | undefined {
 
 function createInput(value: unknown): value is NewTaskInput {
   const input = record(value)
-  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'parentId', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'tags'])) return false
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'parentId', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'goalRun', 'tags'])) return false
   if (input.parentId !== undefined && (typeof input.parentId !== 'string' || input.parentId.trim() === '')) return false
   if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
   if (!optionalString(input.workspaceId) || !optionalString(input.mode) || !optionalString(input.model)) return false
   if (input.reuseSession !== undefined && typeof input.reuseSession !== 'boolean') return false
   if (input.teamRun !== undefined && typeof input.teamRun !== 'boolean') return false
+  if (input.goalRun !== undefined && typeof input.goalRun !== 'boolean') return false
   if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
   if (input.tags !== undefined && !isTaskTagList(input.tags)) return false
   if (input.freeze !== undefined && freezePayload(input.freeze) === undefined) return false
   if (input.handover !== undefined && handoverPayload(input.handover) === undefined) return false
   if (input.schedule !== undefined) {
     const schedule = record(input.schedule)
-    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron'])) return false
+    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron', 'timeZone'])) return false
     if (typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+    if (schedule.timeZone !== undefined
+      && (typeof schedule.timeZone !== 'string' || !isValidTimeZone(schedule.timeZone))) return false
   }
   return true
 }
 
 function updatePatch(value: unknown): boolean {
   const patch = record(value)
-  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'tags'])) return false
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'goalRun', 'tags'])) return false
   // null (or false) clears the reuse opt-in; only a real boolean is accepted.
   if (patch.reuseSession !== undefined && patch.reuseSession !== null && typeof patch.reuseSession !== 'boolean') return false
   if (patch.teamRun !== undefined && patch.teamRun !== null && typeof patch.teamRun !== 'boolean') return false
+  // The goal opt-in is tri-state: null/true return the card to its default
+  // (goal run), false pins a single plain turn.
+  if (patch.goalRun !== undefined && patch.goalRun !== null && typeof patch.goalRun !== 'boolean') return false
   for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode', 'model'] as const) {
     if (!optionalString(patch[key])) return false
   }
@@ -286,9 +300,13 @@ function updatePatch(value: unknown): boolean {
 function schedulePatch(value: unknown): boolean {
   const patch = record(value)
   return patch !== undefined
-    && exactKeys(patch, ['enabled', 'cron'])
+    && exactKeys(patch, ['enabled', 'cron', 'timeZone'])
     && (patch.enabled === undefined || typeof patch.enabled === 'boolean')
     && (patch.cron === undefined || typeof patch.cron === 'string')
+    // `null` clears the stored zone back to the Host zone; an unknown name is
+    // rejected here so the Host never has to guess at an unusable zone.
+    && (patch.timeZone === undefined || patch.timeZone === null
+      || (typeof patch.timeZone === 'string' && isValidTimeZone(patch.timeZone)))
 }
 
 export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | undefined {
@@ -364,6 +382,7 @@ function parseEnvelopeAction(value: unknown): TaskBoardActionEnvelope | undefine
     case 'delete':
     case 'archive':
     case 'restore':
+    case 'settle':
     case 'run':
     case 'rerun':
       if (!exactKeys(action, ['kind', 'taskId'])) return undefined

package/lib/types/client/board-mount.d.ts

@@ -1,23 +0,0 @@
-/**
- * Board view mounting (dsh-task-board wrapper).
- *
- * The single-occupant takeover lifecycle — container injection into the
- * center column, sibling eviction, remount resilience, sidebar click-out —
- * lives exactly once in shared/client/panel-mount-core.ts (synced copy); this
- * wrapper supplies the board tree, view dataset key, CSS module, and the html
- * attribute names. Those names are pinned by board.module.css, skins, and the
- * semantic attributes contract.
- */
-import type { BoardController } from '../core/controller.ts';
-import type { LocaleRefreshSource } from './sidebar-entry.ts';
-/** The injected board container (kept in the DOM, hidden when inactive). */
-export declare const BOARD_VIEW_SELECTOR = "[data-dsh-taskboard-view]";
-/**
- * Mount the board React tree into the center column and bind its visibility
- * to the controller's boardOpen state.
- * @param controller - the board controller driving the view.
- * @param locale - locale-change source; when given, re-renders a mounted board
- *   on a Language switch.
- * @returns disposer unmounting the tree and restoring the column.
- */
-export declare function mountBoard(controller: BoardController, locale?: LocaleRefreshSource): () => void;

package/lib/types/client/body-mutations.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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 declare function subscribeBodyInvalidations(subscriber: () => void): () => void;
-/**
- * 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 declare function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void;

package/lib/types/client/panel-mount-core.d.ts

@@ -1,56 +0,0 @@
-/**
- * Center-column panel takeover lifecycle.
- *
- * The `conversation` slot is single-occupant (ui-conversation) and external
- * plugins cannot declare slots, so a family panel takes over the center
- * column at the DOM level: a container is appended inside the center column
- * (`[class*="centerCol"]`, the 0.1.0-rc.6+ AppFrame layout; previously
- * `[data-pane="conversation"]` on older shells — the mount selector keeps
- * both, ssh #243 / task-board #107) as an extra trailing child React never
- * manages, and a stylesheet rule hides the conversation content while the
- * panel is active. Toggling is a data attribute on <html> — no React
- * involvement, so the conversation subtree underneath stays mounted and
- * stateful.
- *
- * Consuming plugins keep a thin wrapper that supplies the panel tree,
- * container attribute names, and stylesheet class; those names are pinned by
- * each package's CSS, skins, and the semantic-attributes contract. The
- * sidebar row toggling the panel shares its core the same way
- * (shared/client/sidebar-entry-core.ts, synced copy).
- */
-import { type Root } from 'react-dom/client';
-/** Options for mountCenterPanel; dsh-ssh mount.tsx and dsh-task-board board-mount.tsx are the canonical consumers. */
-export interface CenterPanelMountOptions {
-    /** Render the panel tree (first open, remount while open, locale refresh). */
-    render: (root: Root) => void;
-    /** dataset key of the injected container's view attribute, e.g. `dshSshView` for `data-dsh-ssh-view`. */
-    viewDatasetKey: string;
-    /** value of the container's L2 `data-dsh-plugin` semantic attribute. */
-    pluginName: string;
-    /** stylesheet class applied to the injected container. */
-    viewClassName: string;
-    /** <html> attribute set while this panel is active. */
-    activeAttribute: string;
-    /** the sibling panel's active attribute, removed from <html> when this panel opens. */
-    siblingActiveAttribute: string;
-    /** detail value this panel broadcasts on the cross-plugin activation event. */
-    panelName: string;
-    /** sibling detail value whose activation closes this panel. */
-    siblingPanelName: string;
-    /** open flag of the owning controller. */
-    isOpen: () => boolean;
-    /** close the panel, handing the center column back to the conversation. */
-    close: () => void;
-    /** subscribe to the owning controller's open-state changes; returns an unsubscriber. */
-    subscribe: (listener: () => void) => () => void;
-    /** locale-change source; when given, re-renders an open panel on a Language switch. */
-    locale?: {
-        subscribe(listener: () => void): () => void;
-    };
-}
-/**
- * Mount a family panel into the center column and bind its visibility to the
- * owning controller's open state.
- * @returns disposer unmounting the tree and restoring the column.
- */
-export declare function mountCenterPanel(options: CenterPanelMountOptions): () => void;

package/lib/types/client/sidebar-entry-core.d.ts

@@ -1,55 +0,0 @@
-/** Per-package configuration for one sidebar entry row. */
-export interface SidebarEntryOptions {
-    /** Full attribute name identifying the injected row (idempotency key), e.g. 'data-dsh-ssh-entry'. */
-    rowAttribute: string;
-    /** CSS selector matching the injected row, e.g. '[data-dsh-ssh-entry]'. */
-    rowSelector: string;
-    /**
-     * L2 semantic-attribute plugin id (issue #506, enum table:
-     * skins/skin-center/contracts/semantic-attrs-v1.md). When set, the row also
-     * outputs data-dsh-plugin="<id>" and data-dsh-part="sidebar-entry"; unset
-     * leaves the row without semantic attributes.
-     */
-    plugin?: string;
-    /** Inline icon markup (matches the shell's 16px nav-icon look). */
-    icon: string;
-    /** CSS module class names for the row and its two spans (entry / entryIcon / entryLabel). */
-    css: Record<string, string>;
-    /** Localized row label (aria-label + visible text). */
-    label(): string;
-    /** Optional localized tooltip (title attribute). */
-    tooltip?(): string;
-    /**
-     * Optional locale-change subscription: re-applies label / aria-label /
-     * tooltip whenever the active locale changes. Plain-DOM rows would
-     * otherwise keep the label captured at mount; pass the SDK locale runtime
-     * subscription (ctx.locale.subscribe) so the row follows the language
-     * switch without a reload.
-     */
-    refresh?: {
-        subscribe(listener: () => void): () => void;
-    };
-    /** Click action (open/toggle the owning panel). */
-    onToggle(): void;
-    /** Family-block position: 'before' inserts ahead of sibling plugin rows, 'after' behind them. */
-    position: 'before' | 'after';
-    /**
-     * Selectors of the sibling plugin entry rows this package orders against
-     * (its own row included — the placement guard excludes a row that is
-     * already inside the root). Each package passes the same list it used
-     * before the consolidation so the rendered order stays stable.
-     */
-    familySelectors: readonly string[];
-    /** Optional active-state bridge; highlights the row while the panel is open. */
-    active?: {
-        subscribe(listener: () => void): () => void;
-        isOpen(): boolean;
-    };
-}
-/**
- * Mount the sidebar entry, waiting for the shell to render and self-healing
- * on later React re-renders.
- * @param options - the row's attribute/icon/copy/action/ordering configuration.
- * @returns disposer removing the entry and its observers.
- */
-export declare function mountSidebarEntry(options: SidebarEntryOptions): () => void;

package/lib/types/client/sidebar-entry.d.ts

@@ -1,29 +0,0 @@
-/**
- * Sidebar entry injection — package-specific wiring over the shared core.
- *
- * dsh's sidebar shell exposes no slot an external plugin can register into
- * (`sidebar.workspaces` / `sidebar.settings` are single-occupant and already
- * taken), so the entry row is injected between the shell's New Session button
- * and the workspace browser. The DOM injection / self-healing / idempotency
- * logic lives exactly once in shared/client/sidebar-entry-core.ts (synced
- * copy); this wrapper supplies the task-board icon, copy, CSS module, and the
- * board toggle. The row is plain DOM (no React tree); the board view it
- * toggles is a separate React root mounted in the center column
- * (see board-mount.ts).
- */
-import type { BoardController } from '../core/controller.ts';
-/** Stable data attribute identifying the injected entry row. */
-export declare const ENTRY_SELECTOR = "[data-dsh-taskboard-entry]";
-/** Locale-change subscription the shared core asks for (ctx.locale.subscribe shape). */
-export interface LocaleRefreshSource {
-    subscribe(listener: () => void): () => void;
-}
-/**
- * Mount the sidebar entry, waiting for the shell to render and self-healing
- * on later React re-renders.
- * @param controller - the board controller the entry toggles.
- * @param locale - locale-change source; when given, re-applies the label on
- *   a Language switch (the plain-DOM row otherwise keeps the mount-time copy).
- * @returns disposer removing the entry and its observers.
- */
-export declare function mountSidebarEntry(controller: BoardController, locale?: LocaleRefreshSource): () => void;

package/lib/types/host/run-guarded.d.ts

@@ -1,39 +0,0 @@
-/**
- * Async-boundary guard shared by the plugin family's Host halves: every
- * fire-and-forget promise chain and callback the host runtime does not own
- * (route handlers, timers, event listeners, spawned work) funnels through
- * these helpers. The dsh host installs a process-level fail-loud guard that
- * turns ANY unhandled promise rejection into a whole-process exit — one
- * plugin's stray rejection would otherwise take every plugin down. These
- * helpers exist so that failure mode is structurally impossible in family
- * code: the rejection becomes a logged error at the plugin boundary instead.
- *
- * Complements the aggregate's shell isolation (packages/dsh-web-all): the
- * shell contains import/activation failures at boot; runGuarded contains
- * run-time failures after activation.
- * @module dsh-web-shared/host/run-guarded
- */
-/**
- * Run one async operation, logging (never propagating) a rejection. Use for
- * promises whose lifecycle the caller does not await: spawned work, retry
- * loops, background flushes. Returns the original promise so callers can
- * still chain when they want to.
- * @param promise - the work to shield; any thenable.
- * @param label - log prefix naming the work site.
- * @param log - error sink; defaults to console.error.
- * @returns the input promise (rejection already consumed).
- */
-export declare function runGuarded<T>(promise: PromiseLike<T>, label: string, log?: (error: unknown) => void): PromiseLike<T>;
-/**
- * Wrap one callback so every invocation is individually guarded: a rejection
- * inside one call is logged and swallowed instead of escaping into whatever
- * infrastructure invoked the callback (HTTP server, EventEmitter, interval).
- * Sync throws are caught identically; a returned promise is replaced by
- * `undefined` after guarding (callers that need the original rejection should
- * await inside their own try/catch instead).
- * @param label - log prefix naming the callback site.
- * @param handler - the work to guard.
- * @param log - error sink; defaults to console.error.
- * @returns a wrapped callback with the same parameter list.
- */
-export declare function guardedHandler<A extends unknown[]>(label: string, handler: (...args: A) => unknown, log?: (error: unknown) => void): (...args: A) => unknown;

package/src/client/board-mount.tsx

@@ -1,43 +0,0 @@
-/**
- * Board view mounting (dsh-task-board wrapper).
- *
- * The single-occupant takeover lifecycle — container injection into the
- * center column, sibling eviction, remount resilience, sidebar click-out —
- * lives exactly once in shared/client/panel-mount-core.ts (synced copy); this
- * wrapper supplies the board tree, view dataset key, CSS module, and the html
- * attribute names. Those names are pinned by board.module.css, skins, and the
- * semantic attributes contract.
- */
-import type { BoardController } from '../core/controller.ts'
-import { TaskBoard } from './board/TaskBoard.tsx'
-import { mountCenterPanel } from './panel-mount-core.ts'
-import type { LocaleRefreshSource } from './sidebar-entry.ts'
-import css from './board.module.css'
-
-/** The injected board container (kept in the DOM, hidden when inactive). */
-export const BOARD_VIEW_SELECTOR = '[data-dsh-taskboard-view]'
-
-/**
- * Mount the board React tree into the center column and bind its visibility
- * to the controller's boardOpen state.
- * @param controller - the board controller driving the view.
- * @param locale - locale-change source; when given, re-renders a mounted board
- *   on a Language switch.
- * @returns disposer unmounting the tree and restoring the column.
- */
-export function mountBoard(controller: BoardController, locale?: LocaleRefreshSource): () => void {
-  return mountCenterPanel({
-    render: root => root.render(<TaskBoard controller={controller} />),
-    viewDatasetKey: 'dshTaskboardView',
-    pluginName: 'task-board',
-    viewClassName: css.boardView,
-    activeAttribute: 'data-dsh-taskboard-active',
-    siblingActiveAttribute: 'data-dsh-ssh-active',
-    panelName: 'taskboard',
-    siblingPanelName: 'ssh',
-    isOpen: () => controller.getSnapshot().boardOpen,
-    close: () => controller.closeBoard(),
-    subscribe: listener => controller.subscribe(listener),
-    locale,
-  })
-}

package/src/client/body-mutations.ts

@@ -1,133 +0,0 @@
-// 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]
-    }
-  }
-}