dsh-coding-sidebar 1.0.0

package/src/client/terminal-links.ts

@@ -0,0 +1,194 @@
+/**
+ * Terminal URL hyperlinks: xterm's `registerLinkProvider` is fed per-line
+ * link descriptors built from the pty stream, so URLs printed by any tool
+ * become hoverable / clickable spans.
+ *
+ * To stay out of the user's way (a terminal's primary interaction is text
+ * selection, not browsing), a click only activates when the user holds
+ * Ctrl (Win/Linux) or Cmd (mac) — a plain click is left for xterm's
+ * normal selection handling. Only http(s) URLs are dispatched to the
+ * browser; other schemes (`file://`, `mailto:`, `javascript:`, …) are
+ * underlined for visibility but rejected at activation, so a `file://`
+ * URL printed by a tool stays inert instead of being handed to
+ * `window.open`.
+ *
+ * Kept as a pure module (no xterm import) so the regex, the line
+ * scanner, the modifier gate and the scheme guard are unit-testable
+ * without mounting a terminal. `buildTerminalLinks` returns plain-object
+ * descriptors whose shape matches xterm's `ILink` minus the `activate`
+ * callback — the caller attaches `activate` (which closes over the
+ * event modifier check + `openTerminalUrl`) so this module never
+ * imports xterm types.
+ */
+
+/** Scheme allowlist for activation. Only http(s) is opened externally. */
+const OPENABLE_SCHEMES = new Set(['http:', 'https:'])
+
+/**
+ * The URL pattern used to scan each terminal line.
+ *
+ * A word boundary (`\b`) guards the leading scheme so `notttps://…` does
+ * not match. The character class excludes ASCII whitespace and the
+ * wrapping punctuation that shells commonly emit around URLs (quotes,
+ * angle brackets, brackets/braces, pipes, backslashes, backticks) so a
+ * URL printed as `"https://example.com"` or `<https://example.com>` does
+ * not drag the wrapping character into the link target.
+ *
+ * Carries the `g` flag so `findTerminalUrlsInLine` can iterate every
+ * match on a line; callers must reset `lastIndex` before reuse (the
+ * helper does this defensively).
+ */
+export const TERMINAL_URL_REGEX = /\bhttps?:\/\/[^\s"'<>\[\]{}|\\^`]+/gi
+
+/** A URL match in a terminal line: the text and its 0-based start offset. */
+export interface TerminalUrlMatch {
+  /** 0-based start index of the URL within the line string. */
+  start: number
+  /** The matched URL text. */
+  text: string
+}
+
+/**
+ * Strip trailing closing parens that are not balanced by an opening paren
+ * earlier in the URL.
+ *
+ * The regex's character class keeps `(` and `)` (Wikipedia-style URLs
+ * carry real parens: `…/Python_(programming_language)`), so a URL wrapped
+ * in parens by a shell (`(https://example.com)`) captures the trailing
+ * `)`. Balanced pairs are kept intact; only the unmatched excess is
+ * trimmed, so:
+ * - `https://example.com)` → `https://example.com`
+ * - `https://en.wikipedia.org/wiki/Python_(programming_language)` → unchanged
+ * - `https://example.com/(` → unchanged (more openers than closers; the
+ *   trailing `(` is the URL's own, not a wrapper)
+ */
+function trimUnbalancedTrailingParens(url: string): string {
+  let opens = 0
+  let closers = 0
+  for (let i = 0; i < url.length; i += 1) {
+    const ch = url[i]
+    if (ch === '(') opens += 1
+    else if (ch === ')') closers += 1
+  }
+  const excess = closers - opens
+  if (excess <= 0) return url
+  let end = url.length
+  let stripped = 0
+  while (end > 0 && url[end - 1] === ')' && stripped < excess) {
+    end -= 1
+    stripped += 1
+  }
+  return url.slice(0, end)
+}
+
+/**
+ * Find every http(s) URL in a line of terminal text, in source order
+ * with 0-based start offsets. A link provider maps these to buffer
+ * ranges for xterm's `registerLinkProvider`.
+ *
+ * Trailing unmatched closing parens are trimmed from each match (see
+ * {@link trimUnbalancedTrailingParens}), so a URL wrapped in parens by
+ * a shell opens without the trailing `)`, while Wikipedia-style URLs
+ * with balanced parens stay intact.
+ *
+ * Resets the regex's `lastIndex` before and after the scan so a
+ * previous partial iteration can't desynchronize a later one (the
+ * regex carries the `g` flag and is module-shared).
+ */
+export function findTerminalUrlsInLine(line: string): TerminalUrlMatch[] {
+  TERMINAL_URL_REGEX.lastIndex = 0
+  const matches: TerminalUrlMatch[] = []
+  let m: RegExpExecArray | null
+  while ((m = TERMINAL_URL_REGEX.exec(line)) !== null) {
+    const trimmed = trimUnbalancedTrailingParens(m[0])
+    if (trimmed.length > 0) {
+      matches.push({ start: m.index, text: trimmed })
+    }
+  }
+  TERMINAL_URL_REGEX.lastIndex = 0
+  return matches
+}
+
+/**
+ * A buffer range in xterm's coordinate system. xterm's cell `x` is
+ * 1-based (1..cols) and `y` is the buffer line number; the `end` is
+ * inclusive (the last cell covered by the link). Structurally
+ * compatible with xterm's `IBufferRange` so the caller can pass it
+ * straight through without importing xterm types here.
+ */
+export interface TerminalLinkRange {
+  start: { x: number; y: number }
+  end: { x: number; y: number }
+}
+
+/**
+ * A link descriptor: a buffer range plus the URL text. The caller
+ * (the link provider in `TerminalView`) attaches the `activate`
+ * callback, which closes over the modifier gate and `openTerminalUrl`.
+ */
+export interface TerminalLinkDescriptor {
+  range: TerminalLinkRange
+  text: string
+}
+
+/**
+ * Build link descriptors for every URL found in a terminal line.
+ *
+ * @param lineText - the line's text (e.g. from
+ *   `IBufferLine.translateToString(true)`).
+ * @param lineNumber - the buffer line number xterm passed to
+ *   `ILinkProvider.provideLinks` (used as the `y` of every range; URLs
+ *   never span wrapped lines because each wrapped row is its own
+ *   buffer line).
+ * @returns descriptors in source order; empty when the line has no URL.
+ */
+export function buildTerminalLinks(lineText: string, lineNumber: number): TerminalLinkDescriptor[] {
+  return findTerminalUrlsInLine(lineText).map(({ start, text: url }) => ({
+    range: {
+      // xterm's cell `x` is 1-based; `start` is 0-based from
+      // translateToString, so the first URL character sits at x = start + 1.
+      start: { x: start + 1, y: lineNumber },
+      // `end` is inclusive: the last URL character is at 0-based
+      // (start + url.length - 1), which is 1-based (start + url.length).
+      end: { x: start + url.length, y: lineNumber },
+    },
+    text: url,
+  }))
+}
+
+/**
+ * Decide whether a click on a terminal link should activate (open the URL).
+ *
+ * Mirrors what every modern terminal does (Windows Terminal, iTerm2, the
+ * VSCode integrated terminal): a plain click stays a text-selection
+ * gesture, and only Ctrl (Win/Linux) or Cmd (mac) hands the URL to the
+ * browser. The modifier is read off the activating `MouseEvent`, not
+ * tracked separately, so a key-up between hover and click never
+ * desynchronizes the gate.
+ */
+export function shouldActivateTerminalLink(event: MouseEvent): boolean {
+  return event.ctrlKey || event.metaKey
+}
+
+/**
+ * Open a URL matched in the terminal, with a scheme guard so a printed
+ * `file://` or anything that slipped past the regex cannot reach
+ * `window.open`. The URL is constructed via `new URL(...)` which throws
+ * on malformed input; the catch makes the function total so the xterm
+ * handler never throws into the terminal's event loop.
+ *
+ * @returns `true` when the URL was dispatched to `window.open`, `false`
+ *   when it was rejected (bad URL, disallowed scheme, no `window`).
+ */
+export function openTerminalUrl(uri: string): boolean {
+  if (typeof window === 'undefined') return false
+  let url: URL
+  try {
+    url = new URL(uri)
+  } catch {
+    return false
+  }
+  if (!OPENABLE_SCHEMES.has(url.protocol)) return false
+  window.open(url.toString(), '_blank', 'noopener,noreferrer')
+  return true
+}

package/src/client/theme.ts

@@ -0,0 +1,110 @@
+/**
+ * Live theme access for surfaces that cannot consume the token colors
+ * directly — xterm's palette and CodeMirror's theme extensions need concrete
+ * values, but the app's scheme flips at runtime (ui-layout's ThemePresenter
+ * projects prefers-color-scheme and the user's choice onto
+ * body[data-ds-dark-theme] and html { color-scheme }). This module reads the
+ * resolved scheme and token values, and notifies subscribers on flips, so
+ * the terminal and the editor re-theme in place instead of freezing in the
+ * scheme they happened to be created under.
+ */
+
+/** Whether the app shell resolved to the dark scheme.
+ *
+ * The presenter sets `html { color-scheme }` together with the body palette
+ * attribute, so a set color-scheme means the decision is authoritative (an
+ * absent attribute is then LIGHT even when the OS prefers dark — the user
+ * chose light). Before the presenter has run, fall back to the OS media
+ * query as the best guess.
+ */
+export function isDarkScheme(): boolean {
+  if (typeof document === 'undefined') return true
+  const decided = document.documentElement.style.colorScheme !== ''
+  if (decided) return document.body.hasAttribute('data-ds-dark-theme')
+  return typeof matchMedia !== 'undefined' && matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+/** One token's computed value on <body> ('' while the theme has not applied). */
+export function tokenValue(name: string): string {
+  if (typeof document === 'undefined') return ''
+  return getComputedStyle(document.body).getPropertyValue(name).trim()
+}
+
+/** Minimal alpha for a token color to count as effectively opaque. Skin
+ *  systems turn `--dsw-alias-bg-base` translucent for glass panels (the
+ *  dsh-web-ui skins use rgba 0.16–0.7; `transparent` is 0); below this
+ *  floor a text surface (terminal, editor) would render over the skin's
+ *  backdrop art, so callers fall back to an opaque color. Values at or
+ *  above the floor (e.g. a skin's scoped 0.96 porcelain) pass through —
+ *  the skin still controls the surface. */
+const OPAQUE_ALPHA_MIN = 0.9
+
+/** The alpha channel of a computed CSS color, or null when the format is
+ *  not parseable (named colors, `color()`… — treated as opaque). Handles
+ *  the shapes getComputedStyle actually returns: the rgb()/rgba() and
+ *  hsl()/hsla() function forms (comma or space syntax, with or without the
+ *  `/ alpha` slot) and the #rgb/#rgba/#rrggbb/#rrggbbaa hex family. */
+export function colorAlpha(color: string): number | null {
+  const s = color.trim()
+  // #rgb / #rgba / #rrggbb / #rrggbbaa
+  const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(s)
+  if (hex !== null) {
+    const digits = hex[1]!
+    if (digits.length === 3 || digits.length === 4) {
+      const a = digits.length === 4 ? digits[3]! : 'f'
+      return parseInt(a + a, 16) / 255
+    }
+    const alphaHex = digits.length === 8 ? digits.slice(6) : 'ff'
+    return parseInt(alphaHex, 16) / 255
+  }
+  // rgb(r g b) / rgb(r g b / a) / rgba(r, g, b, a) — the trailing slot is alpha.
+  const fn = /^(rgba?|hsla?)\(([^)]+)\)$/i.exec(s)
+  if (fn !== null) {
+    const parts = fn[2]!.split(/[,\s/]+/).filter(Boolean)
+    const alphaPart = parts[3]
+    if (alphaPart === undefined) return 1
+    const alpha = Number.parseFloat(alphaPart)
+    return Number.isFinite(alpha) ? alpha : 1
+  }
+  return null
+}
+
+/**
+ * A token value that actually PAINTS something — the guard for text
+ * surfaces (issue #90). Skin systems routinely set global tokens to
+ * `transparent` (glass skins) or translucent glass values (`rgba(…,0.16–0.7)`,
+ * e.g. the dsh-web-ui skins) — both are truthy strings, so callers using
+ * `|| fallback` never fire and the terminal/editor goes see-through over
+ * the skin's backdrop. This returns '' for visually inert values (unset
+ * keywords, transparent, and any color below the opacity floor) so the
+ * caller's fallback chain engages; effectively opaque values pass through.
+ */
+export function effectiveTokenValue(name: string): string {
+  const raw = tokenValue(name)
+  switch (raw) {
+    case '':
+    case 'transparent':
+    case 'initial':
+    case 'inherit':
+    case 'unset':
+      return ''
+    default: {
+      const alpha = colorAlpha(raw)
+      if (alpha !== null && alpha < OPAQUE_ALPHA_MIN) return ''
+      return raw
+    }
+  }
+}
+
+/**
+ * Subscribe to color-scheme flips (the presenter toggles the body
+ * attribute). The callback fires after the attribute changed; re-read the
+ * scheme inside it.
+ * @returns the disposer.
+ */
+export function subscribeColorScheme(callback: () => void): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const observer = new MutationObserver(() => { callback() })
+  observer.observe(document.body, { attributes: true, attributeFilter: ['data-ds-dark-theme'] })
+  return () => { observer.disconnect() }
+}

package/src/client/titlebar-strip.ts

@@ -0,0 +1,37 @@
+/**
+ * The title-bar strip resolution chain — the ONE place that decides how
+ * many pixels the sidebar yields at the top. Standard signals first, then
+ * the user's chosen scheme; never a per-shell branch:
+ *
+ *   0. `web` scheme — EXPLICIT "DSH official web": never adapt, not even
+ *      standard WCO geometry (the user declares the plain web UI).
+ *   1. Window Controls Overlay real geometry (standard API, authoritative
+ *      when present — even 0, e.g. the overlay is hidden while maximized).
+ *   2. The `dsh-desktop-titlebar-inset` URL contract parameter (a shell
+ *      declares the exact pixels it reserves).
+ *   3. The active shell preset's strip (scheme `preset` — opt-in data).
+ *   4. The legacy manual `titleBarStripPx` (scheme `custom`).
+ *   5. 0 — plain-browser semantics, nothing modified.
+ *
+ * The result drives `--dsh-title-bar-strip` + `body[data-dsh-title-bar-compat]`
+ * exactly like the legacy boolean did; only the VALUE source changed.
+ */
+import type { DesktopEnv } from './desktop-env.ts'
+import type { TitleBarScheme } from '../prefs-shared.ts'
+import type { WcoSnapshot } from './wco.ts'
+import { presetStripFor, type ShellPreset } from './shell-presets.ts'
+
+export function computeTitleBarStrip(
+  env: DesktopEnv,
+  wco: WcoSnapshot,
+  scheme: TitleBarScheme,
+  preset: ShellPreset | undefined,
+  customStripPx: number,
+): number {
+  if (scheme === 'web') return 0
+  if (wco.present) return wco.height
+  if (env.titlebarInset > 0) return env.titlebarInset
+  if (scheme === 'preset') return presetStripFor(preset, env) ?? 0
+  if (scheme === 'custom') return customStripPx
+  return 0
+}

package/src/client/upload.ts

@@ -0,0 +1,187 @@
+/**
+ * File-upload plumbing for the files window: turn a file picker or a drag-drop
+ * into per-file raw-byte uploads through the sidebar's `/sidebar/upload` route.
+ *
+ * Folders keep their tree in both flows: the picker's `webkitdirectory`
+ * selection arrives as Files with `webkitRelativePath` filled, and dropped
+ * folders — which never surface in `dataTransfer.files` — are traversed via
+ * `webkitGetAsEntry`, so the relative path is preserved for every nested file
+ * and the host recreates the tree under the chosen directory. The File is
+ * streamed straight into the POST body (no base64 inflation); uploads run
+ * sequentially so one slow file cannot starve the others, and each result
+ * reports its own outcome (the tree keeps going after a failure). An
+ * optional `AbortSignal` stops the queue at the next item boundary and
+ * aborts the in-flight request; the host cleans up its temp file when the
+ * request stream dies.
+ */
+import { api, SidebarApiError, type SessionScope } from './api.ts'
+import { isAbsolutePath } from './paths.ts'
+import type { CopyKey } from './locales.ts'
+
+/** One pending file: the browser File plus the workspace-relative target path. */
+export interface UploadItem {
+  file: File
+  relativePath: string
+}
+
+/** One settled upload. */
+export interface UploadResult {
+  relativePath: string
+  ok: boolean
+  path?: string
+  /** Wire error code when the host refused the upload ('too-large', ...). */
+  code?: string
+  /** The host's error message (English wire text; localize via `code`). */
+  error?: string
+}
+
+/** Sanitize a relative target: absolute paths, traversal, and empty segments
+ *  are rejected (the host enforces the same rules with a 400). */
+function sanitizeRelativePath(rel: string): string | undefined {
+  if (rel === '' || isAbsolutePath(rel)) return undefined
+  if (rel.split(/[\\/]/).some((s) => s === '' || s === '.' || s === '..')) return undefined
+  return rel
+}
+
+/** The picker's relative path: webkitRelativePath when present, else the name. */
+function relativePathOf(file: File): string | undefined {
+  return sanitizeRelativePath(file.webkitRelativePath || file.name || '')
+}
+
+/** Collect a picker selection (webkitdirectory folders carry relative paths). */
+export function uploadItemsFromFiles(files: FileList | readonly File[]): UploadItem[] {
+  const items: UploadItem[] = []
+  for (const file of files) {
+    const rel = relativePathOf(file)
+    if (rel !== undefined) items.push({ file, relativePath: rel })
+  }
+  return items
+}
+
+/** Read one dropped file-system entry into upload items; directories
+ *  recurse, prefixing their name onto every descendant's relative path. */
+async function itemsFromEntry(entry: FileSystemEntry, prefix: string): Promise<UploadItem[]> {
+  if (entry.isFile) {
+    const file = await new Promise<File>((resolve, reject) => {
+      ;(entry as FileSystemFileEntry).file(resolve, reject)
+    })
+    const rel = sanitizeRelativePath(prefix + file.name)
+    return rel === undefined ? [] : [{ file, relativePath: rel }]
+  }
+  if (entry.isDirectory) {
+    const reader = (entry as FileSystemDirectoryEntry).createReader()
+    const entries: FileSystemEntry[] = []
+    // readEntries returns one BATCH per call; drain until an empty batch.
+    for (;;) {
+      const batch = await new Promise<FileSystemEntry[]>((resolve, reject) => {
+        reader.readEntries(resolve, reject)
+      })
+      if (batch.length === 0) break
+      entries.push(...batch)
+    }
+    const nested = await Promise.all(entries.map(child => itemsFromEntry(child, `${prefix}${entry.name}/`)))
+    return nested.flat()
+  }
+  return []
+}
+
+/**
+ * Collect a drag-drop payload. Dropped folders do NOT surface in
+ * `dataTransfer.files` — they arrive as directory items, so entries are
+ * captured via `webkitGetAsEntry` and traversed (draining readEntries
+ * batches), keeping each nested file's relative path. MUST be invoked
+ * synchronously from the drop handler: the dataTransfer enters protected
+ * mode once the event dispatch ends, while the captured entry handles stay
+ * readable asynchronously. Falls back to the flat file list when the entry
+ * API is unavailable; an entry that fails to read is skipped, not fatal.
+ */
+export async function uploadItemsFromDrop(data: DataTransfer | undefined): Promise<UploadItem[]> {
+  if (data === undefined) return []
+  // Synchronous section: capture every entry handle before returning.
+  const entries = [...data.items]
+    .map(item => (item.kind === 'file' ? item.webkitGetAsEntry() : null))
+    .filter((entry): entry is FileSystemEntry => entry !== null)
+  if (entries.length === 0) return uploadItemsFromFiles(data.files)
+  const nested = await Promise.all(entries.map(entry => itemsFromEntry(entry, '').catch(() => [])))
+  return nested.flat()
+}
+
+/**
+ * Client-side pre-check cap. Mirrors the host's default (config `uploadLimit`)
+ * only — the host enforces the real, configurable limit, so a lowered host
+ * limit surfaces as a `too-large` wire error, never as a silent pass.
+ */
+export const MAX_UPLOAD_BYTES = 128 * 1024 * 1024
+
+/** How long a success hint stays before fading (failures stay until the next action). */
+export const UPLOAD_HINT_MS = 3500
+
+/**
+ * One-line upload progress text: 'Uploading into {dir}…' while no file is in
+ * flight, then 'Uploading {done}/{total}: {name}' per file. Shared by the tree
+ * hint and the full-window upload overlay.
+ */
+export function uploadHintText(
+  done: number,
+  total: number,
+  current: string,
+  dir: string,
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  return current === '' ? t('uploadingTo', { dir }) : t('uploadProgress', { done, total, name: current })
+}
+
+/**
+ * Upload every item into `dir` (absolute, inside the session workspace),
+ * sequentially, reporting progress as `(done, total, currentRelativePath)`.
+ * Resolves with one result per item — never rejects; `signal.aborted` stops
+ * the queue at the next item boundary (completed items stay uploaded).
+ */
+export async function uploadToDir(
+  scope: SessionScope,
+  dir: string,
+  items: UploadItem[],
+  onProgress?: (done: number, total: number, current: string) => void,
+  signal?: AbortSignal,
+): Promise<UploadResult[]> {
+  const results: UploadResult[] = []
+  let done = 0
+  for (const item of items) {
+    if (signal?.aborted) break
+    onProgress?.(done, items.length, item.relativePath)
+    try {
+      if (item.file.size > MAX_UPLOAD_BYTES) {
+        results.push({ relativePath: item.relativePath, ok: false, code: 'too-large' })
+      } else {
+        const res = await api.uploadFile(scope, dir, item.relativePath, item.file, signal)
+        results.push({ relativePath: item.relativePath, ok: true, path: res.path })
+      }
+    } catch (error) {
+      // An aborted in-flight request is a cancel, not a failure: stop quietly.
+      if (error instanceof DOMException && error.name === 'AbortError') break
+      results.push({
+        relativePath: item.relativePath,
+        ok: false,
+        code: error instanceof SidebarApiError ? error.code : undefined,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+    done++
+  }
+  onProgress?.(done, items.length, '')
+  return results
+}
+
+/** Fold a result list into a one-line status for the tree hint. */
+export function summarizeResults(
+  results: UploadResult[],
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  const okCount = results.filter((r) => r.ok).length
+  const failed = results.find((r) => !r.ok)
+  if (failed !== undefined) {
+    const detail = failed.code === 'too-large' ? t('uploadTooLarge') : (failed.error ?? t('uploadFailedUnknown'))
+    return t('uploadFailed', { error: detail })
+  }
+  return t('uploadDone', { count: okCount })
+}

package/src/client/wco.ts

@@ -0,0 +1,120 @@
+/**
+ * Reactive Window Controls Overlay geometry — the STANDARD web mechanism
+ * for frameless Chromium shells that draw the native caption buttons
+ * (minimize / maximize / close) OVER the web content (Electron
+ * `titleBarOverlay` on Windows; issue #257). Feature-detected: absent in
+ * plain browsers, macOS, Tauri etc., where the snapshot stays `NONE` and
+ * the sidebar adapts nothing — this is the conservative "auto" signal.
+ *
+ * The API reports the real titlebar rect (CSS px), which differs between
+ * shells and Electron versions (32 / 36 …), and fires `geometrychange`
+ * when the window maximizes / restores / moves — so the strip must be
+ * reactive, not memoized like the URL stamps.
+ *
+ * Module-level store so the Sidebar shell can subscribe via
+ * `useSyncExternalStore`; `setWcoSourceForTests` swaps the source for unit
+ * tests (no real API exists in jsdom/headless).
+ */
+export interface WcoSource {
+  readonly visible: boolean
+  getTitlebarAreaRect(): { readonly x: number; readonly y: number; readonly width: number; readonly height: number }
+  addEventListener(type: 'geometrychange', listener: () => void): void
+  removeEventListener(type: 'geometrychange', listener: () => void): void
+}
+
+/** The current overlay geometry (present=false = API unavailable). */
+export interface WcoSnapshot {
+  readonly present: boolean
+  readonly height: number
+}
+
+/** Snapshot when the API is unavailable (plain browser / non-overlay shell). */
+export const WCO_NONE: WcoSnapshot = Object.freeze({ present: false, height: 0 })
+
+type Listener = () => void
+
+let source: WcoSource | undefined
+let snapshot: WcoSnapshot = WCO_NONE
+let attached = false
+let sourceListener: (() => void) | undefined
+const listeners = new Set<Listener>()
+
+function read(): WcoSnapshot {
+  if (source === undefined) return WCO_NONE
+  try {
+    // A present-but-NOT-visible API is a PHANTOM: headless Chromium and
+    // macOS builds expose the interface but draw no overlay (empty rect,
+    // visible=false). Only a genuinely visible overlay is authoritative —
+    // otherwise the resolution chain would trust a zero rect and silently
+    // skip the shell's real reserved space.
+    if (source.visible !== true) return { present: false, height: 0 }
+    const rect = source.getTitlebarAreaRect()
+    const height = Math.round(rect.height)
+    return Number.isFinite(height) && height > 0
+      ? { present: true, height }
+      : { present: true, height: 0 }
+  } catch {
+    // A hostile/racy API must never break the layout — treat as absent.
+    return { present: false, height: 0 }
+  }
+}
+
+function onGeometryChange(): void {
+  snapshot = read()
+  emit()
+}
+
+function emit(): void {
+  for (const listener of listeners) listener()
+}
+
+/** Attach the native geometrychange listener (once). */
+function attach(): void {
+  if (attached) return
+  attached = true
+  // The test hook may have installed a source already; otherwise attach to
+  // the real navigator API (absent in plain browsers → stay NONE).
+  const candidate = source ?? (navigator as unknown as { windowControlsOverlay?: WcoSource }).windowControlsOverlay
+  if (candidate === undefined) return
+  source = candidate
+  sourceListener = onGeometryChange
+  snapshot = read()
+  source.addEventListener('geometrychange', sourceListener)
+}
+
+/** Detach the native listener (last subscriber left or source swapped). */
+function detach(): void {
+  if (source !== undefined && sourceListener !== undefined) {
+    source.removeEventListener('geometrychange', sourceListener)
+  }
+  sourceListener = undefined
+  attached = false
+}
+
+/** Read the current snapshot (returns the frozen NONE when unavailable). */
+export function getWcoSnapshot(): WcoSnapshot {
+  return snapshot
+}
+
+/**
+ * Subscribe to overlay geometry changes. Attaches to the real
+ * `navigator.windowControlsOverlay` on first subscribe; the disposer
+ * detaches the native listener when the last subscriber leaves.
+ */
+export function subscribeWco(onChange: Listener): () => void {
+  listeners.add(onChange)
+  attach()
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0) detach()
+  }
+}
+
+/** Test hook: swap the geometry source (undefined = API unavailable). */
+export function setWcoSourceForTests(next: WcoSource | undefined): void {
+  detach()
+  source = next
+  snapshot = next === undefined ? WCO_NONE : read()
+  if (next !== undefined && listeners.size > 0) attach()
+  emit()
+}