@shendeguize/dsh-agent-sidecar 0.1.1 → 0.2.0

package/src/client/navigation/center-overlay.module.css

@@ -0,0 +1,51 @@
+.dialog {
+  gap: 0;
+  width: min(1180px, calc(100vw - 48px));
+  height: min(860px, calc(100vh - 48px));
+  max-height: calc(100vh - 48px);
+  padding: 0;
+  border-color: var(--agsc-border-strong);
+  border-radius: var(--agsc-radius-card);
+  background: var(--agsc-bg);
+  box-shadow: var(--agsc-shadow-card);
+}
+
+.content {
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+}
+
+.content > :last-child {
+  flex: 1;
+  min-height: 0;
+  margin-top: 0;
+  padding: 0;
+  overflow: hidden;
+}
+
+.surface {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  height: 100%;
+  color: var(--agsc-fg);
+  background: var(--agsc-bg);
+  overflow: hidden;
+}
+
+.surface > :last-child {
+  flex: 1;
+  min-height: 0;
+  height: auto;
+}
+
+@media (max-width: 720px) {
+  .dialog {
+    width: calc(100vw - 16px);
+    height: calc(100dvh - 16px);
+    max-height: calc(100dvh - 16px);
+    border-radius: var(--agsc-radius-control);
+  }
+}

package/src/client/navigation/center.ts

@@ -0,0 +1,45 @@
+/** Callback port used by UI entry points that open Agent Center. */
+export type CenterNavigation = () => boolean
+
+/** Observable state port bound to the shell overlay at the composition root. */
+export interface CenterNavigationStore {
+  readonly open: CenterNavigation
+  close(): void
+  subscribe(listener: () => void): () => void
+  getSnapshot(): boolean
+}
+
+/**
+ * Create one DOM-free navigation source for every Agent Center entry point.
+ * Opening is always accepted; a shell overlay that mounts later observes the
+ * retained snapshot instead of losing the request.
+ */
+export function createCenterNavigation(): CenterNavigationStore {
+  let isOpen = false
+  const listeners = new Set<() => void>()
+  const notify = (): void => {
+    for (const listener of [...listeners]) listener()
+  }
+
+  const open: CenterNavigation = () => {
+    if (!isOpen) {
+      isOpen = true
+      notify()
+    }
+    return true
+  }
+
+  return {
+    open,
+    close: () => {
+      if (!isOpen) return
+      isOpen = false
+      notify()
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    getSnapshot: () => isOpen,
+  }
+}

package/src/client/navigation/modal-isolation.ts

@@ -0,0 +1,152 @@
+import { useEffect } from 'react'
+import type { RefObject } from 'react'
+const DIALOG_SELECTOR = '[role="dialog"][aria-modal="true"]'
+const FOCUSABLE_SELECTOR = [
+  'a[href],area[href],button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"]),select:not([disabled])',
+  'textarea:not([disabled]),iframe,[contenteditable="true"],[tabindex]',
+].join(',')
+function focusableElements(dialog: HTMLElement): HTMLElement[] {
+  return Array.from(dialog.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+    .filter((element) =>
+      element.tabIndex >= 0 &&
+      !element.hidden &&
+      element.closest('[inert],[aria-hidden="true"]') === null &&
+      element.getClientRects().length > 0)
+}
+function restorableIn(element: HTMLElement | null, dialog: HTMLElement): element is HTMLElement {
+  return element?.isConnected === true &&
+    dialog.contains(element) &&
+    !element.hidden &&
+    element.closest('[inert],[aria-hidden="true"]') === null &&
+    element.getClientRects().length > 0
+}
+type DialogFrame = { dialog: HTMLElement; opener: HTMLElement | null; focus: HTMLElement | null }
+/** Isolate the active official Modal, including sibling-portaled nested dialogs. */
+export function useModalIsolation(
+  open: boolean,
+  surfaceRef: RefObject<HTMLElement>,
+): void {
+  useEffect(() => {
+    if (!open || typeof document === 'undefined' || typeof window === 'undefined') return
+    const body = document.body
+    if (body === null || typeof window.MutationObserver === 'undefined') return
+    const previousFocus =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null
+    const originalInert = new Map<HTMLElement, boolean>()
+    const dialogStack: DialogFrame[] = []
+    let topDialog: HTMLElement | null = null
+    let focusFrame: number | null = null
+    const getTopDialog = (): HTMLElement | null => {
+      const outer = surfaceRef.current?.closest<HTMLElement>(DIALOG_SELECTOR) ?? null
+      if (outer === null) return null
+      const dialogs = Array.from(body.querySelectorAll<HTMLElement>(DIALOG_SELECTOR))
+      const outerIndex = dialogs.indexOf(outer)
+      return outerIndex < 0 ? null : dialogs.at(-1) ?? null
+    }
+    const bodyBranch = (dialog: HTMLElement): HTMLElement | null => {
+      let branch: Node = dialog
+      while (branch.parentNode !== null && branch.parentNode !== body) {
+        branch = branch.parentNode
+      }
+      return branch instanceof HTMLElement ? branch : null
+    }
+    const isolateAround = (dialog: HTMLElement | null): void => {
+      const activeBranch = dialog === null ? null : bodyBranch(dialog)
+      const next = new Set(
+        Array.from(body.children)
+          .filter((element): element is HTMLElement =>
+            element instanceof HTMLElement && element !== activeBranch),
+      )
+      for (const [element, wasInert] of originalInert) {
+        if (next.has(element)) continue
+        element.inert = wasInert
+        originalInert.delete(element)
+      }
+      for (const element of next) {
+        if (!originalInert.has(element)) originalInert.set(element, element.inert)
+        element.inert = true
+      }
+    }
+    const queueFocus = (dialog: HTMLElement, preferred: HTMLElement | null = null): void => {
+      if (focusFrame !== null) window.cancelAnimationFrame(focusFrame)
+      focusFrame = window.requestAnimationFrame(() => {
+        focusFrame = null
+        if (getTopDialog() !== dialog) return
+        const target = restorableIn(preferred, dialog)
+          ? preferred
+          : focusableElements(dialog)[0]
+        target?.focus({ preventScroll: true })
+      })
+    }
+    const sync = (): void => {
+      const next = getTopDialog()
+      const changed = next !== topDialog
+      let closed: DialogFrame[] = []
+      if (changed && next !== null) {
+        const index = dialogStack.findIndex(frame => frame.dialog === next)
+        if (index < 0) {
+          const parent = dialogStack.at(-1)
+          const active =
+            document.activeElement instanceof HTMLElement ? document.activeElement : null
+          const opener = parent !== undefined && restorableIn(active, parent.dialog)
+            ? active
+            : parent?.focus ?? null
+          dialogStack.push({ dialog: next, opener, focus: null })
+        } else {
+          closed = dialogStack.splice(index + 1)
+        }
+      }
+      topDialog = next
+      isolateAround(next)
+      const opener = next === null
+        ? null
+        : closed.reverse().find(frame => restorableIn(frame.opener, next))?.opener ?? null
+      if (
+        next !== null &&
+        (changed || !next.contains(document.activeElement))
+      ) {
+        queueFocus(next, opener)
+      }
+    }
+    const onFocusIn = (event: FocusEvent): void => {
+      if (!(event.target instanceof HTMLElement)) return
+      const dialog = event.target.closest<HTMLElement>(DIALOG_SELECTOR)
+      const frame = dialogStack.find(item => item.dialog === dialog)
+      if (frame !== undefined) frame.focus = event.target
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'Tab' || event.defaultPrevented) return
+      const dialog = getTopDialog()
+      if (dialog === null) return
+      if (dialog !== topDialog) sync()
+
+      const focusable = focusableElements(dialog)
+      if (focusable.length === 0) {
+        event.preventDefault()
+        return
+      }
+      const activeIndex = focusable.indexOf(document.activeElement as HTMLElement)
+      const wrapsBackward = event.shiftKey && activeIndex <= 0
+      const wrapsForward = !event.shiftKey && activeIndex === focusable.length - 1
+      if (activeIndex < 0 || wrapsBackward || wrapsForward) {
+        event.preventDefault()
+        const target = event.shiftKey ? focusable.at(-1) : focusable[0]
+        target?.focus({ preventScroll: true })
+      }
+    }
+    const observer = new window.MutationObserver(sync)
+    observer.observe(body, { childList: true, subtree: true })
+    document.addEventListener('focusin', onFocusIn)
+    document.addEventListener('keydown', onKeyDown, true)
+    sync()
+    return () => {
+      observer.disconnect()
+      document.removeEventListener('focusin', onFocusIn)
+      document.removeEventListener('keydown', onKeyDown, true)
+      if (focusFrame !== null) window.cancelAnimationFrame(focusFrame)
+      for (const [element, wasInert] of originalInert) element.inert = wasInert
+      if (previousFocus?.isConnected === true) previousFocus.focus({ preventScroll: true })
+    }
+  }, [open, surfaceRef])
+}

package/src/client/navigation/modal-surface-anchor.ts

@@ -0,0 +1,72 @@
+import { useEffect, useLayoutEffect } from 'react'
+import type { RefObject } from 'react'
+import type { SurfaceProps } from '../theme/parts.ts'
+
+const DIALOG_SELECTOR = '[role="dialog"][aria-modal="true"]'
+const MODAL_SURFACE_OWNER = Symbol.for(
+  '@shendeguize/dsh-agent-sidecar/modal-surface-anchor-owner',
+)
+
+type ModalSurfaceAttributes = Pick<
+  SurfaceProps,
+  'data-dsh-plugin' | 'data-dsh-part'
+>
+
+export interface ModalSurfaceAnchorTarget {
+  setAttribute(name: string, value: string): void
+  removeAttribute(name: string): void
+}
+
+/** Use a pre-paint effect in the browser without warning during SSR. */
+export function selectModalSurfaceAnchorEffect(
+  hasDocument: boolean,
+): typeof useEffect {
+  return hasDocument ? useLayoutEffect : useEffect
+}
+
+const useIsomorphicLayoutEffect = selectModalSurfaceAnchorEffect(
+  typeof document !== 'undefined',
+)
+
+function ownerSlot(target: ModalSurfaceAnchorTarget): Record<PropertyKey, unknown> {
+  return target as unknown as Record<PropertyKey, unknown>
+}
+
+/** Attach the public surface attributes with latest-owner-safe cleanup. */
+export function attachModalSurfaceAnchor(
+  target: ModalSurfaceAnchorTarget | null,
+  attributes: ModalSurfaceAttributes,
+): () => void {
+  if (target === null) return () => {}
+
+  const owner = Symbol('modal-surface-anchor')
+  const slot = ownerSlot(target)
+  slot[MODAL_SURFACE_OWNER] = owner
+  target.setAttribute('data-dsh-plugin', attributes['data-dsh-plugin'])
+  target.setAttribute('data-dsh-part', attributes['data-dsh-part'])
+
+  return () => {
+    if (slot[MODAL_SURFACE_OWNER] !== owner) return
+    target.removeAttribute('data-dsh-plugin')
+    target.removeAttribute('data-dsh-part')
+    delete slot[MODAL_SURFACE_OWNER]
+  }
+}
+
+/** Commit the public anchor onto the official Modal's real dialog element. */
+export function useModalSurfaceAnchor(
+  open: boolean,
+  surfaceRef: RefObject<HTMLElement>,
+  attributes: ModalSurfaceAttributes,
+): void {
+  useIsomorphicLayoutEffect(() => {
+    if (!open || typeof document === 'undefined') return
+    const dialog = surfaceRef.current?.closest<HTMLElement>(DIALOG_SELECTOR) ?? null
+    return attachModalSurfaceAnchor(dialog, attributes)
+  }, [
+    open,
+    surfaceRef,
+    attributes['data-dsh-plugin'],
+    attributes['data-dsh-part'],
+  ])
+}

package/src/client/navigation/sidebar-entry.module.css

@@ -0,0 +1,73 @@
+.entry {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  height: 36px;
+  padding: 0 10px;
+  border: 0;
+  border-radius: var(--agsc-radius-control);
+  background: none;
+  color: var(--agsc-fg-secondary);
+  cursor: pointer;
+  font: inherit;
+  font-size: 13px;
+  text-align: left;
+  white-space: nowrap;
+  transition: background-color 120ms ease, color 120ms ease, transform 120ms ease;
+}
+
+.entry:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--agsc-fg);
+}
+
+.entry:active {
+  background: var(--dsw-alias-interactive-bg-active);
+  color: var(--agsc-fg);
+  transform: translateY(1px);
+}
+
+.entry:focus-visible {
+  outline: 2px solid var(--agsc-accent);
+  outline-offset: 2px;
+}
+
+.entryIcon {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+}
+
+.entryIcon svg {
+  display: block;
+  width: 16px;
+  height: 16px;
+}
+
+.entryLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+[data-dsh-frame][data-sidebar-collapsed] .entry {
+  justify-content: center;
+  width: 36px;
+  padding: 0;
+  margin: 0 auto 12px;
+  border-radius: 50%;
+}
+
+[data-dsh-frame][data-sidebar-collapsed] .entryLabel {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .entry {
+    transition: none;
+  }
+}

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

@@ -0,0 +1,309 @@
+/** First-class Agent Center row inserted after the shell's New Session row. */
+import type { CenterNavigation } from './center.ts'
+import css from './sidebar-entry.module.css'
+import { PLUGIN_DOM_ID, surfaceProps } from '../theme/parts.ts'
+
+export const SIDEBAR_ENTRY_SELECTOR = '[data-agent-sidecar-sidebar-entry]'
+const ENTRY_ATTRIBUTE = 'data-agent-sidecar-sidebar-entry'
+const LABEL_ATTRIBUTE = 'data-agent-sidecar-sidebar-entry-label'
+const SVG_NS = 'http://www.w3.org/2000/svg'
+const ENTRY_BINDING = Symbol.for('@shendeguize/dsh-agent-sidecar/sidebar-entry-binding')
+const ENTRY_BRAND = Symbol.for('@shendeguize/dsh-agent-sidecar/sidebar-entry-brand')
+const ENTRY_DISPATCHER = Symbol.for('@shendeguize/dsh-agent-sidecar/sidebar-entry-dispatcher')
+const warnedForeignEntries = new WeakSet<object>()
+
+interface QueryScope { querySelector(selector: string): unknown | null }
+export interface SidebarEntryCopyPort {
+  readonly label: string
+  readonly accessibilityLabel: string
+  subscribe(listener: () => void): () => void
+}
+export interface SidebarEntryCopyTarget {
+  readonly button: {
+    title: string
+    setAttribute(name: string, value: string): void
+  }
+  readonly label: { textContent: string | null }
+}
+interface SidebarEntryElements extends SidebarEntryCopyTarget { readonly button: HTMLButtonElement }
+interface SidebarEntryObserver { disconnect(): void }
+interface SidebarEntryBinding {
+  readonly owner: object
+  readonly openCenter: CenterNavigation
+  stopCopy: () => void
+  observer: SidebarEntryObserver | null
+}
+export interface SidebarEntryOwnerTarget extends SidebarEntryCopyTarget {
+  readonly button: SidebarEntryCopyTarget['button'] & { remove(): void }
+}
+/** Narrow, DOM-independent idempotency check used by mount and unit tests. */
+export function hasSidebarEntry(scope: QueryScope): boolean {
+  return scope.querySelector(SIDEBAR_ENTRY_SELECTOR) !== null
+}
+export function applyCopy(target: SidebarEntryCopyTarget, copy: SidebarEntryCopyPort): void {
+  target.label.textContent = copy.label
+  target.button.setAttribute('aria-label', copy.accessibilityLabel)
+  target.button.title = copy.accessibilityLabel
+}
+
+export function bindSidebarEntryCopy(
+  target: SidebarEntryCopyTarget,
+  copy: SidebarEntryCopyPort,
+): () => void {
+  const update = (): void => { applyCopy(target, copy) }
+  update()
+  return copy.subscribe(update)
+}
+
+function bindingOf(button: object): SidebarEntryBinding | undefined {
+  return (button as Record<PropertyKey, unknown>)[ENTRY_BINDING] as SidebarEntryBinding | undefined
+}
+function hasCurrentDispatcher(button: object): boolean {
+  const record = button as Record<PropertyKey, unknown>
+  return (record[ENTRY_BRAND] === true || record[ENTRY_BINDING] !== undefined)
+    && record[ENTRY_DISPATCHER] === true
+}
+/** A pure, DOM-independent ownership check; the idempotency attribute alone is foreign. */
+export function isOwnedSidebarEntry(candidate: unknown): boolean {
+  if (candidate === null
+    || (typeof candidate !== 'object' && typeof candidate !== 'function')) return false
+  const record = candidate as Record<PropertyKey, unknown>
+  if (record[ENTRY_BRAND] === true || record[ENTRY_BINDING] !== undefined) return true
+  const element = candidate as {
+    tagName?: unknown
+    getAttribute?: (name: string) => string | null
+    querySelector?: (selector: string) => unknown | null
+  }
+  return element.tagName === 'BUTTON'
+    && element.getAttribute?.('data-dsh-plugin') === PLUGIN_DOM_ID
+    && element.getAttribute?.('data-dsh-part') === 'sidebar-entry'
+    && element.querySelector?.(`[${LABEL_ATTRIBUTE}]`) != null
+}
+
+function brandSidebarEntry(button: object): void {
+  (button as Record<PropertyKey, unknown>)[ENTRY_BRAND] = true
+}
+function installClickDispatcher(button: HTMLButtonElement): void {
+  const record = button as unknown as Record<PropertyKey, unknown>
+  if (record[ENTRY_DISPATCHER] === true) return
+  button.addEventListener('click', () => { openBoundSidebarEntry(button) })
+  record[ENTRY_DISPATCHER] = true
+}
+function once(dispose: () => void): () => void {
+  let active = true
+  return () => {
+    if (!active) return
+    active = false
+    dispose()
+  }
+}
+/** Invoke the latest cross-bundle binding, never a captured HMR closure. */
+export function openBoundSidebarEntry(button: object): void {
+  try {
+    bindingOf(button)?.openCenter()
+  } catch {
+    // Navigation is a best-effort bridge to host-owned tab DOM.
+  }
+}
+/** Latest-owner-wins binding over one shared DOM button. */
+export function bindSidebarEntryOwner(
+  target: SidebarEntryOwnerTarget,
+  owner: object,
+  openCenter: CenterNavigation,
+  copy: SidebarEntryCopyPort,
+  startObserver: () => SidebarEntryObserver | null,
+): () => void {
+  const previous = bindingOf(target.button)
+  previous?.observer?.disconnect()
+  previous?.stopCopy()
+
+  const binding: SidebarEntryBinding = {
+    owner,
+    openCenter,
+    stopCopy: () => {},
+    observer: null,
+  }
+  const sharedButton = target.button as unknown as Record<PropertyKey, unknown>
+  sharedButton[ENTRY_BINDING] = binding
+  binding.stopCopy = once(bindSidebarEntryCopy(target, copy))
+  binding.observer = startObserver()
+
+  return () => {
+    binding.observer?.disconnect()
+    if (bindingOf(target.button)?.owner !== owner) return
+    binding.stopCopy()
+    delete sharedButton[ENTRY_BINDING]
+    target.button.remove()
+  }
+}
+
+function createIcon(): SVGSVGElement {
+  const icon = document.createElementNS(SVG_NS, 'svg')
+  for (const [name, value] of Object.entries({
+    viewBox: '0 0 16 16',
+    width: '16',
+    height: '16',
+    fill: 'none',
+    stroke: 'currentColor',
+    'stroke-width': '1.4',
+    'stroke-linecap': 'round',
+    'stroke-linejoin': 'round',
+    'aria-hidden': 'true',
+    focusable: 'false',
+  })) {
+    icon.setAttribute(name, value)
+  }
+  const orbit = document.createElementNS(SVG_NS, 'circle')
+  orbit.setAttribute('cx', '8')
+  orbit.setAttribute('cy', '8')
+  orbit.setAttribute('r', '5.5')
+  const center = document.createElementNS(SVG_NS, 'circle')
+  center.setAttribute('cx', '8')
+  center.setAttribute('cy', '8')
+  center.setAttribute('r', '1.75')
+  const path = document.createElementNS(SVG_NS, 'path')
+  path.setAttribute('d', 'M8 2.5v3.75M8 9.75v3.75M2.5 8h3.75M9.75 8h3.75')
+  icon.append(orbit, center, path)
+  return icon
+}
+
+function createEntry(): SidebarEntryElements {
+  const entry = document.createElement('button')
+  brandSidebarEntry(entry)
+  const surface = surfaceProps('sidebar-entry', css.entry)
+  entry.type = 'button'
+  entry.className = surface.className
+  entry.setAttribute(ENTRY_ATTRIBUTE, '')
+  entry.setAttribute('data-dsh-plugin', surface['data-dsh-plugin'])
+  entry.setAttribute('data-dsh-part', surface['data-dsh-part'])
+
+  const icon = document.createElement('span')
+  icon.className = css.entryIcon ?? ''
+  icon.setAttribute('aria-hidden', 'true')
+  icon.appendChild(createIcon())
+  const label = document.createElement('span')
+  label.className = css.entryLabel ?? ''
+  label.setAttribute(LABEL_ATTRIBUTE, '')
+  entry.append(icon, label)
+  installClickDispatcher(entry)
+  return { button: entry, label }
+}
+
+function existingEntry(button: HTMLButtonElement): SidebarEntryElements | null {
+  const label = button.querySelector<HTMLElement>(`[${LABEL_ATTRIBUTE}]`)
+    ?? (button.lastElementChild as HTMLElement | null)
+  return label === null ? null : { button, label }
+}
+
+function rejectLegacyEntry(): null {
+  console.warn('[agent-sidecar] Sidebar legacy entry cannot be safely replaced; leaving it untouched.')
+  return null
+}
+
+function replaceLegacyEntry(button: HTMLButtonElement): SidebarEntryElements | null {
+  if (typeof button.cloneNode !== 'function' || typeof button.replaceWith !== 'function') {
+    return rejectLegacyEntry()
+  }
+  let clone: HTMLButtonElement
+  try {
+    clone = button.cloneNode(true) as HTMLButtonElement
+  } catch {
+    return rejectLegacyEntry()
+  }
+  const elements = clone.tagName === 'BUTTON' && typeof clone.addEventListener === 'function'
+    ? existingEntry(clone)
+    : null
+  if (elements === null) return rejectLegacyEntry()
+  try {
+    button.replaceWith(clone)
+  } catch {
+    return rejectLegacyEntry()
+  }
+  brandSidebarEntry(clone)
+  installClickDispatcher(clone)
+  return elements
+}
+
+function sidebarRoot(): HTMLElement | null {
+  const column = document.querySelector<HTMLElement>(
+    '[data-pane="sidebar"], [class*="sidebarCol"]',
+  )
+  if (column === null) return null
+  const logoOwner = column.querySelector<HTMLElement>('[class*="logoRow"]')?.parentElement
+  return logoOwner ?? (column.firstElementChild as HTMLElement | null)
+}
+
+function newSessionRow(root: HTMLElement): Element | null {
+  const nested = root.querySelector<HTMLButtonElement>('button[class*="newSession"]')
+  const button = nested ?? Array.from(root.children).find((child) => child.tagName === 'BUTTON')
+  if (button === undefined) return null
+  const row = button.closest('[class*="logoRow"]')
+  if (row !== null && row.parentElement === root) return row
+  return button.parentElement === root ? button : null
+}
+
+function placeEntry(entry: HTMLButtonElement): boolean {
+  const root = sidebarRoot()
+  if (root === null) return false
+  const anchor = newSessionRow(root)
+  if (anchor === null) return false
+  if (entry.parentElement !== root || anchor.nextElementSibling !== entry) {
+    root.insertBefore(entry, anchor.nextElementSibling)
+  }
+  return true
+}
+
+/**
+ * Wait for the sidebar, restore the row after React rebuilds, and return full
+ * cleanup. Overlapping applies synchronously adopt the existing row.
+ */
+export function mountSidebarEntry(
+  openCenter: CenterNavigation,
+  copy: SidebarEntryCopyPort,
+): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const candidate = document.querySelector<HTMLButtonElement>(SIDEBAR_ENTRY_SELECTOR)
+  if (candidate !== null && !isOwnedSidebarEntry(candidate)) {
+    if (!warnedForeignEntries.has(candidate)) {
+      warnedForeignEntries.add(candidate)
+      console.warn('[agent-sidecar] Sidebar entry collision: refusing to modify a foreign '
+        + SIDEBAR_ENTRY_SELECTOR + ' node.')
+    }
+    return () => {}
+  }
+  const elements = candidate === null
+    ? createEntry()
+    : hasCurrentDispatcher(candidate)
+      ? existingEntry(candidate)
+      : replaceLegacyEntry(candidate)
+  if (elements === null) return () => {}
+  brandSidebarEntry(elements.button)
+  const entry = elements.button
+  const owner = {}
+  let disposed = false
+  const ensurePlaced = (): void => {
+    if (disposed) return
+    if (entry.isConnected) return
+    const existing = document.querySelector(SIDEBAR_ENTRY_SELECTOR)
+    if (existing !== null && existing !== entry) return
+    placeEntry(entry)
+  }
+  ensurePlaced()
+  const disposeBinding = bindSidebarEntryOwner(
+    elements,
+    owner,
+    openCenter,
+    copy,
+    () => {
+      if (typeof MutationObserver === 'undefined') return null
+      const observer = new MutationObserver(ensurePlaced)
+      observer.observe(document.body, { childList: true, subtree: true })
+      return observer
+    },
+  )
+  return () => {
+    if (disposed) return
+    disposed = true
+    disposeBinding()
+  }
+}