@linxin666/dsh-usage 0.3.24 → 0.4.0

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

@@ -1,87 +0,0 @@
-/**
- * One trailing action button seated at the entry row's right edge (e.g. a
- * refresh command or a collapse chevron). Rows with actions switch from the
- * classic single-button structure to a container with a main button plus the
- * action buttons (nested interactive elements are invalid HTML); rows without
- * actions keep the classic structure untouched.
- */
-export interface SidebarEntryAction {
-    /** Stable id stamped as data-dsh-entry-action="<id>" (CSS hooks and tests). */
-    id: string;
-    /** Inline icon markup while the row is active (always, when inactiveIcon is unset). */
-    icon: string;
-    /**
-     * Optional icon while the row is inactive. Setting it makes the action a
-     * state mirror (a collapse chevron): the core swaps the icon and stamps
-     * aria-expanded on every active-state change. Requires the active bridge.
-     */
-    inactiveIcon?: string;
-    /** Localized accessible label (aria-label + title); receives the active state. */
-    label(active: boolean): string;
-    /**
-     * Click handler; receives the button so the caller can drive transient
-     * affordances (a refresh cooldown) without a re-render.
-     */
-    onClick(button: HTMLButtonElement): void;
-}
-/** 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;
-    /**
-     * Optional trailing action buttons at the row's right edge. Requires the
-     * package CSS to seat entryMain / entryAction; empty keeps the classic
-     * single-button row.
-     */
-    actions?: readonly SidebarEntryAction[];
-    /** 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,35 +0,0 @@
-/**
- * Sidebar entry injection for the usage panel (issue #1592) — wiring over the
- * shared core. Unlike the panel-takeover family (task board / SSH / skill
- * center) this row does not participate in the family block, so it is placed
- * directly under the New Session row and ordered after those entries. The row
- * seats the panel's controls as trailing actions: a refresh command and a
- * collapse chevron mirroring the open state, so the panel below renders only
- * its content.
- * @module @linxin666/dsh-usage/client/sidebar-entry
- */
-/** Stable data attribute identifying the injected entry row. */
-export declare const ENTRY_SELECTOR = "[data-dsh-usage-entry]";
-/** Locale-change subscription the shared core asks for (ctx.locale.subscribe shape). */
-export interface LocaleRefreshSource {
-    subscribe(listener: () => void): () => void;
-}
-/** Panel-facing callbacks and state the entry row's controls drive. */
-export interface UsageSidebarEntryHandlers {
-    /** Toggles the panel (the row's main area and the collapse chevron). */
-    onToggle(): void;
-    /** Forces one host probe cycle (the refresh action). */
-    onRefresh(): void;
-    /** Reads the panel's expanded state (row highlight and chevron direction). */
-    isOpen(): boolean;
-    /** Subscribes to expanded-state changes (the chevron mirrors them live). */
-    subscribeOpen(listener: () => void): () => void;
-}
-/**
- * Mount the usage sidebar entry.
- * @param handlers - the panel's toggle/refresh callbacks and open-state face.
- * @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(handlers: UsageSidebarEntryHandlers, locale?: LocaleRefreshSource): () => void;

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

@@ -1,40 +0,0 @@
-/**
- * Sidebar usage panel mounting (issue #1592).
- *
- * The panel is a plain DOM row inserted into the sidebar right below the
- * usage entry row, carrying its own React root. Placement self-heals with the
- * same page-wide body-mutation hub the entry row uses; the entry row stays the
- * anchor, so the sidebar order never depends on this module's timing.
- *
- * The mount owns the panel's single open state: initialized from localStorage,
- * flipped by the entry row's toggle controls, and mirrored to the React body
- * through the subscribe/isOpen face (the same face the entry row's chevron
- * and highlight read).
- * @module @linxin666/dsh-usage/client/sidebar-panel-mount
- */
-import type { UsageStoreInstance } from './usage-store.ts';
-/** localStorage key holding the collapsed flag ('1' = collapsed). */
-export declare const COLLAPSED_STORAGE_KEY = "dsh-usage.sidebar.collapsed";
-/** Panel inputs the mount forwards into the React tree. */
-export interface UsagePanelMountProps {
-    store: UsageStoreInstance;
-    /** Fetch one overview now. */
-    poll: () => void;
-}
-/** Mounted panel controller: the entry row drives the toggle and mirrors the state. */
-export interface UsagePanelMount {
-    /** Whether the panel body is currently expanded. */
-    isOpen(): boolean;
-    /** Subscribe to open/collapse changes (the entry row's chevron and highlight). */
-    subscribe(listener: () => void): () => void;
-    /** Flip the open state, persist it, and notify subscribers. */
-    toggle(): void;
-    /** Unmount the panel and remove its container. */
-    dispose(): void;
-}
-/**
- * Mount the sidebar usage panel below its entry row.
- * @param props - the store and poll callback of the apply body.
- * @returns the panel controller.
- */
-export declare function mountUsagePanel(props: UsagePanelMountProps): UsagePanelMount;

package/src/client/UsageSidebarPanel.tsx

@@ -1,196 +0,0 @@
-/**
- * Sidebar usage panel (issue #1592): the usage body seated directly under the
- * sidebar entry row. The row carries the panel's controls (refresh, collapse
- * chevron), so this component renders only the content: expanded, plan
- * providers show their quota windows and balance-only providers their
- * remaining amount; collapsed, a one-line strip shows the current session
- * provider's today usage (tokens, calls, and cost when priced) from the same
- * /api/dsh-usage/overview document the settings section renders. The open
- * state lives in the mount (persisted to localStorage) and arrives through
- * the open face; polling runs at 10s expanded, 30s collapsed, and pauses
- * while the page is hidden.
- * @module @linxin666/dsh-usage/client/UsageSidebarPanel
- */
-
-import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
-import { t } from './locales.ts'
-import styles from './usage.module.css'
-import { formatTokens } from './UsageSectionCard.tsx'
-import type { UsageStoreInstance } from './usage-store.ts'
-import { adapterFor } from '../core/adapters.ts'
-import { totalTokens } from '../core/ledger.ts'
-import type { ProviderSnapshotView, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
-import { addTotals, emptyTotals } from '../core/types.ts'
-
-/** Expanded-state face the owning mount supplies (subscribe + current value). */
-export interface OpenStateSource {
-  subscribe(listener: () => void): () => void
-  isOpen(): boolean
-}
-
-/** Props of the sidebar panel (the apply body supplies the store and poller). */
-export interface UsageSidebarPanelProps {
-  store: UsageStoreInstance
-  /** Fetch one overview now. */
-  poll: () => void
-  /** Expanded state owned by the mount; false renders nothing and pauses polling. */
-  open: OpenStateSource
-}
-
-/** Poll cadence while the panel is expanded and the page visible. */
-const PANEL_POLL_MS = 10_000
-
-/**
- * Poll cadence of the collapsed strip: the current session's usage should
- * stay visibly live, but a collapsed surface pays a relaxed cadence instead
- * of the expanded one.
- */
-const COLLAPSED_POLL_MS = 30_000
-
-/** Bar tone, matching the settings section's thresholds. */
-function tone(percent: number): string {
-  if (percent >= 90) return styles.barLow
-  if (percent >= 70) return styles.barWarn
-  return styles.sidebarBarFill
-}
-
-/**
- * The collapsed-strip facts for the current provider: display name plus
- * today's adapter-family totals (tokens, calls, cost). The host serves them
- * strip-ready inside `current`; an older host document is derived against
- * here. Undefined on a day without usage — a strip about nothing is noise.
- */
-function collapsedSummary(snapshot: UsageOverviewView): { name: string; totals: UsageTokenTotals } | undefined {
-  const provider = snapshot.current.provider
-  if (provider === undefined) return undefined
-  const name = snapshot.current.displayName
-    ?? snapshot.providers.find((entry) => entry.provider === provider)?.displayName
-    ?? provider
-  if (snapshot.current.today !== undefined) {
-    const totals = snapshot.current.today
-    return totals.calls > 0 && totalTokens(totals) > 0 ? { name, totals } : undefined
-  }
-  const family = adapterFor(provider)
-  let merged = emptyTotals()
-  for (const row of snapshot.usage.today.providers) {
-    const same = family === undefined ? row.provider === provider : adapterFor(row.provider) === family
-    if (same) merged = addTotals(merged, row.totals)
-  }
-  return merged.calls > 0 && totalTokens(merged) > 0 ? { name, totals: merged } : undefined
-}
-
-/** A provider is worth listing when it is configured and carries a fact. */
-function listable(provider: ProviderSnapshotView): boolean {
-  return provider.credential !== 'none' && (provider.plan !== undefined || provider.balance !== undefined)
-}
-
-/** One provider row: plan windows when present, otherwise the balance line. */
-function ProviderBlock(props: { provider: ProviderSnapshotView }): ReactNode {
-  const { provider } = props
-  const windows = provider.plan?.windows ?? []
-  if (windows.length > 0) {
-    return (
-      <div className={styles.sidebarProvider} data-dsh-part="sidebar-provider">
-        <div className={styles.sidebarProviderHead}>
-          <span className={styles.sidebarProviderName}>{provider.displayName}</span>
-        </div>
-        {windows.map((window) => (
-          <div key={window.key} className={styles.sidebarWindowRow} data-dsh-part="sidebar-window">
-            <span>{window.name ?? t(`usage.plan.windows.${window.key}`)}</span>
-            {window.percent !== undefined && (
-              <>
-                <span className={styles.sidebarBar}>
-                  <span className={tone(window.percent)} style={{ width: `${Math.min(100, Math.max(0, window.percent))}%` }} />
-                </span>
-                <span>{window.percent >= 10 ? Math.round(window.percent) : window.percent.toFixed(1)}%</span>
-              </>
-            )}
-          </div>
-        ))}
-      </div>
-    )
-  }
-  if (provider.balance !== undefined) {
-    return (
-      <div className={styles.sidebarProvider} data-dsh-part="sidebar-provider">
-        <div className={styles.sidebarProviderHead}>
-          <span className={styles.sidebarProviderName}>{provider.displayName}</span>
-          <span className={styles.sidebarBalance}>
-            {t('usage.sidebar.balanceLeft', { balance: `${provider.balance.currency} ${provider.balance.totalBalance}` })}
-          </span>
-        </div>
-      </div>
-    )
-  }
-  return null
-}
-
-/**
- * Render the sidebar usage panel body.
- * @param props - store, the poll callback, and the mount's open-state face.
- * @returns the panel content, or null while collapsed.
- */
-export function UsageSidebarPanel(props: UsageSidebarPanelProps): ReactNode {
-  const { store, poll, open: openState } = props
-  const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
-  const open = useSyncExternalStore(openState.subscribe, openState.isOpen)
-
-  // The strip stays live at a relaxed cadence while collapsed; the
-  // expanded panel keeps the section's own 10s cadence. A hidden tab always
-  // pauses, matching the settings section's gating.
-  useEffect(() => {
-    poll()
-    const cadence = open ? PANEL_POLL_MS : COLLAPSED_POLL_MS
-    let timer: number | undefined
-    const start = (): void => {
-      if (timer === undefined && document.visibilityState === 'visible') timer = window.setInterval(poll, cadence)
-    }
-    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, open])
-
-  const snapshot: UsageOverviewView | null = ui.snapshot
-
-  if (!open) {
-    const summary = snapshot === null ? undefined : collapsedSummary(snapshot)
-    if (summary === undefined) return null
-    return (
-      <div className={styles.sidebarSummary} data-dsh-plugin="usage" data-dsh-part="sidebar-summary">
-        <span className={styles.sidebarSummaryName}>{summary.name}</span>
-        <span className={styles.sidebarSummaryFacts}>
-          {t('usage.sidebar.todayUsage', { tokens: formatTokens(totalTokens(summary.totals)) })}
-          {' · '}
-          {t('usage.calls', { n: summary.totals.calls })}
-          {summary.totals.cost > 0 ? ` · ¥${summary.totals.cost.toFixed(2)}` : ''}
-        </span>
-      </div>
-    )
-  }
-
-  const providers = snapshot === null ? [] : snapshot.providers.filter(listable)
-
-  return (
-    <div className={styles.sidebarPanel} data-dsh-plugin="usage" data-dsh-part="sidebar-panel">
-      {ui.status === 'error'
-        ? <span className={styles.sidebarMuted}>{t('usage.sidebar.error', { error: ui.error ?? '' })}</span>
-        : snapshot === null
-          ? <span className={styles.sidebarMuted}>{t('usage.sidebar.loading')}</span>
-          : providers.length === 0
-            ? <span className={styles.sidebarMuted}>{t('usage.sidebar.empty')}</span>
-            : providers.map((provider) => <ProviderBlock key={provider.provider} provider={provider} />)}
-    </div>
-  )
-}

package/src/client/sidebar-entry-core.ts

@@ -1,321 +0,0 @@
-// Generated by scripts/sync-shared.mjs from shared/client/sidebar-entry-core.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
-/**
- * Shared sidebar entry injection core.
- *
- * dsh's sidebar shell exposes no slot an external plugin can register into,
- * so the entry row is injected between the shell's New Session button and the
- * workspace browser. The injection self-heals: a MutationObserver watches the
- * sidebar root and re-inserts the row whenever a React re-render displaces it
- * (re-insertion happens in the same frame, before paint, so no flicker).
- *
- * The row is plain DOM (no React tree) so it can never disturb the shell's
- * reconciliation; the view it toggles is a separate root owned by the caller.
- *
- * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
- * edit the shared source and re-run the sync instead of editing a copy.
- */
-import { subscribeBodyInvalidations } from './body-mutations.ts'
-
-/**
- * One trailing action button seated at the entry row's right edge (e.g. a
- * refresh command or a collapse chevron). Rows with actions switch from the
- * classic single-button structure to a container with a main button plus the
- * action buttons (nested interactive elements are invalid HTML); rows without
- * actions keep the classic structure untouched.
- */
-export interface SidebarEntryAction {
-  /** Stable id stamped as data-dsh-entry-action="<id>" (CSS hooks and tests). */
-  id: string
-  /** Inline icon markup while the row is active (always, when inactiveIcon is unset). */
-  icon: string
-  /**
-   * Optional icon while the row is inactive. Setting it makes the action a
-   * state mirror (a collapse chevron): the core swaps the icon and stamps
-   * aria-expanded on every active-state change. Requires the active bridge.
-   */
-  inactiveIcon?: string
-  /** Localized accessible label (aria-label + title); receives the active state. */
-  label(active: boolean): string
-  /**
-   * Click handler; receives the button so the caller can drive transient
-   * affordances (a refresh cooldown) without a re-render.
-   */
-  onClick(button: HTMLButtonElement): void
-}
-
-/** 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
-  /**
-   * Optional trailing action buttons at the row's right edge. Requires the
-   * package CSS to seat entryMain / entryAction; empty keeps the classic
-   * single-button row.
-   */
-  actions?: readonly SidebarEntryAction[]
-  /** 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
-  }
-}
-
-/** Find the sidebar shell root element, or undefined while not yet mounted. */
-function sidebarRoot(): HTMLElement | undefined {
-  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
-  if (column === null) return undefined
-  // Current shells wrap the sidebar UI: column > wrapper > root(logoRow owner).
-  // Prefer the element that owns the logo row — the real sidebar UI root —
-  // and fall back to the column's first child for legacy shells.
-  const logoOwner = column.querySelector<HTMLElement>('[class*="logoRow"]')?.parentElement
-  return logoOwner ?? (column.firstElementChild as HTMLElement | undefined)
-}
-
-/** The New Session button: nested in the logo row on current shells, a direct child on legacy shells. */
-function newSessionButton(root: HTMLElement): HTMLButtonElement | undefined {
-  const nested = root.querySelector<HTMLButtonElement>('button[class*="newSession"]')
-  if (nested !== null) return nested
-  for (const child of root.children) {
-    if (child.tagName === 'BUTTON') return child as HTMLButtonElement
-  }
-  return undefined
-}
-
-/** Build the entry row (detached; inserted once the shell is up). */
-function createEntry(options: SidebarEntryOptions): { entry: HTMLElement; applyLabel: () => void; setOpen: (open: boolean) => void } {
-  const actions = options.actions ?? []
-  const composite = actions.length > 0
-  const entry = document.createElement(composite ? 'div' : 'button') as HTMLElement
-  if (!composite) (entry as HTMLButtonElement).type = 'button'
-  entry.setAttribute(options.rowAttribute, '')
-  if (options.plugin !== undefined) {
-    entry.setAttribute('data-dsh-plugin', options.plugin)
-    entry.setAttribute('data-dsh-part', 'sidebar-entry')
-  }
-  entry.className = options.css['entry'] ?? ''
-  const labelSpan = document.createElement('span')
-  labelSpan.className = options.css['entryLabel'] ?? ''
-  const iconSpan = document.createElement('span')
-  iconSpan.className = options.css['entryIcon'] ?? ''
-  iconSpan.innerHTML = options.icon
-  // The main hit area: the classic row IS the button; with trailing actions
-  // the row becomes a container and the main area its own button, so the row
-  // never nests interactive elements.
-  const main = composite ? document.createElement('button') : (entry as HTMLButtonElement)
-  if (composite) {
-    main.type = 'button'
-    main.className = options.css['entryMain'] ?? ''
-    main.append(iconSpan, labelSpan)
-    entry.append(main)
-  } else {
-    entry.append(iconSpan, labelSpan)
-  }
-  const actionButtons: { action: SidebarEntryAction; button: HTMLButtonElement }[] = []
-  for (const action of actions) {
-    const button = document.createElement('button')
-    button.type = 'button'
-    button.className = options.css['entryAction'] ?? ''
-    button.setAttribute('data-dsh-entry-action', action.id)
-    button.innerHTML = action.icon
-    button.addEventListener('click', () => { action.onClick(button) })
-    entry.append(button)
-    actionButtons.push({ action, button })
-  }
-  let open = false
-  const applyActions = (): void => {
-    for (const { action, button } of actionButtons) {
-      button.innerHTML = open || action.inactiveIcon === undefined ? action.icon : action.inactiveIcon
-      const text = action.label(open)
-      button.setAttribute('aria-label', text)
-      button.setAttribute('title', text)
-      if (action.inactiveIcon !== undefined) button.setAttribute('aria-expanded', String(open))
-    }
-  }
-  const applyLabel = (): void => {
-    main.setAttribute('aria-label', options.label())
-    if (options.tooltip !== undefined) main.setAttribute('title', options.tooltip())
-    labelSpan.textContent = options.label()
-    applyActions()
-  }
-  applyLabel()
-  main.addEventListener('click', options.onToggle)
-  if (composite) {
-    // The old row was clickable edge to edge; keep the padding between the
-    // main area and the action buttons a toggle target as well.
-    entry.addEventListener('click', (event) => {
-      if (event.target === entry) options.onToggle()
-    })
-  }
-  return {
-    entry,
-    applyLabel,
-    setOpen: (next: boolean) => {
-      open = next
-      applyActions()
-    },
-  }
-}
-
-/** Re-insert the entry after the New Session row (before the browser region). */
-function placeEntry(root: HTMLElement, entry: HTMLElement, options: SidebarEntryOptions): boolean {
-  const button = newSessionButton(root)
-  if (button === undefined) return false
-  if (entry.parentElement !== root) {
-    // Position relative to the family block (entries injected by sibling
-    // plugins), never relative to transient logoRow geometry: every family
-    // plugin that self-heals during a re-render then lands in the same
-    // relative order, so the entries cannot swap positions regardless of
-    // observer callback order or of shell wrapper changes. There is no
-    // append-to-end fallback: appending at the end would randomly reorder
-    // the block after a shell re-render.
-    const row = button.closest('[class*="logoRow"]')
-    const base = (row !== null && row.parentElement === root) ? row : button
-    const family = Array.from(root.children).filter(
-      (el): el is HTMLElement => el instanceof HTMLElement && el.matches(options.familySelectors.join(', ')),
-    )
-    const anchor = options.position === 'before'
-      ? (family.length > 0 ? family[0] : base.nextElementSibling)
-      : (family.length > 0 ? family[family.length - 1]!.nextElementSibling : base.nextElementSibling)
-    root.insertBefore(entry, anchor)
-  }
-  return true
-}
-
-/**
- * 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 function mountSidebarEntry(options: SidebarEntryOptions): () => void {
-  // DOM-level idempotency: whatever path mounted an entry row before this
-  // call (a duplicated apply, an HMR re-injection, a stale module still
-  // alive), never mount a second one. The existing row keeps working; a full
-  // page reload is the ultimate reset.
-  if (typeof document !== 'undefined' && document.querySelector(options.rowSelector) !== null) {
-    return () => {}
-  }
-  const { entry, applyLabel, setOpen } = createEntry(options)
-  let root: HTMLElement | undefined
-  let placed = false
-  let unsubscribeRefresh: (() => void) | undefined
-  if (options.refresh !== undefined) {
-    try {
-      unsubscribeRefresh = options.refresh.subscribe(applyLabel)
-    } catch {
-      // A throwing subscription must not break the mount; the label stays at
-      // its initial value and the next reload resolves it again.
-    }
-  }
-
-  const tryPlace = (): void => {
-    if (root !== undefined && !root.isConnected) {
-      // The shell rebuilt the sidebar pane (whole-tree teardown); the root
-      // observer is gone with the old tree, so detach it and re-query from
-      // scratch. The new pane is later noticed by the body-level watcher.
-      rootObserver.disconnect()
-      root = undefined
-      placed = false
-    }
-    if (placed) {
-      // Cheap short-circuit: entry still lives in a mountable subtree.
-      if (document.body.contains(entry)) return
-      // Entry was torn down together with the old tree; reset and re-place.
-      rootObserver.disconnect()
-      root = undefined
-      placed = false
-    }
-    root ??= sidebarRoot()
-    if (root === undefined) return
-    placed = placeEntry(root, entry, options)
-    if (placed) {
-      rootObserver.observe(root, { childList: true, subtree: true })
-    }
-  }
-
-  // Body-level watcher retained as the "whole rebuild" fallback: when the shell
-  // tears down the whole sidebar pane, the root observer is gone with it and
-  // only this body observation can notice the new pane mounting. It stays
-  // subscribed after placement; the placed-and-still-mounted case
-  // short-circuits through the cheap document.body.contains(entry) check, so
-  // unrelated app mutations (e.g. chat streaming) cost one contains check per
-  // frame instead of churning the full re-query. The body observation itself is
-  // the page-wide hub (shared/client/body-mutations.ts): every family plugin
-  // used to hold its own body subtree observer, so the per-mutation cost grew
-  // with the number of installed plugins; the hub keeps exactly one.
-  const unsubscribeBody = subscribeBodyInvalidations(() => { tryPlace() })
-
-  // Self-heal: if a React re-render displaces the row, re-insert it in the
-  // same frame (microtask before paint -> no visible flicker).
-  const rootObserver = new MutationObserver(() => {
-    if (root === undefined || !root.isConnected) {
-      placed = false
-      tryPlace()
-      return
-    }
-    if (!root.contains(entry)) {
-      placed = placeEntry(root, entry, options)
-    }
-  })
-
-  // Reflect the panel's open state on the row (active highlight). Note: assigning
-  // undefined to dataset.active materializes data-active="undefined" and keeps the
-  // row permanently highlighted — delete the attribute instead.
-  const unsubscribeActive = options.active === undefined ? undefined : (() => {
-    const syncActive = (): void => {
-      const open = options.active!.isOpen()
-      if (open) entry.dataset.active = 'true'
-      else delete entry.dataset.active
-      setOpen(open)
-    }
-    const unsubscribe = options.active.subscribe(syncActive)
-    syncActive()
-    return unsubscribe
-  })()
-
-  tryPlace()
-
-  return () => {
-    unsubscribeBody()
-    rootObserver.disconnect()
-    unsubscribeRefresh?.()
-    unsubscribeActive?.()
-    entry.remove()
-  }
-}