@chatcode/cco-better-sidebar 0.18.0-alpha.0

package/src/client/ui-tweaks/notifier.ts

@@ -0,0 +1,514 @@
+/**
+ * dsh-ui-tweaks — task notifications (browser half).
+ *
+ * Watches the sessions list feed (the same store the sidebar's running flag,
+ * amber interaction dot and green "done" reminder project from) and raises a
+ * browser-side heads-up when a session finishes its turn or starts blocking
+ * on the user — so a backgrounded tab can call you back:
+ *
+ * - "Finished" = a session's `running` flag drops (true → false) without an
+ *   interaction taking over, or its host-tracked `completed` reminder rises
+ *   (finished while not selected). The host `dshTurnOutcome` session
+ *   projection (`src/turn-outcome.ts`, folded from `turn/end` reasons) says
+ *   WHY it finished, so the copy distinguishes a clean completion from a
+ *   user abort and from a failed request (with the error text); when the
+ *   projection is missing or stale, falls back to a plain-finish announce.
+ * - "Interaction" = a session gains `pendingInteraction`
+ *   ('approval' | 'plan-review' | 'question') — exactly the sidebar's
+ *   amber-dot classification.
+ *
+ * Three independent channels, each silently degrading when unavailable:
+ * - Title flash: alternates `(N) 🔔 <title>` ↔ `(N) <title>` until the page
+ *   is visible and focused again, then restores the captured title. DSH may
+ *   rewrite `document.title` independently; while flashing our ticks win,
+ *   and on stop we restore the pre-flash capture (worst case a stale base).
+ * - System notification: the Web Notifications API; permission is requested
+ *   from the settings toggle's user gesture (`requestNotifyPermission`).
+ *   Clicking one focuses the window and opens that session. `silent` tracks
+ *   the chime channel so the two never double-beep.
+ * - Chime: a tiny WebAudio two-note motif (rising = done, falling = needs
+ *   you), synthesized in-process — no audio assets. Autoplay policy allows
+ *   this once the user has interacted with the origin (sticky activation),
+ *   which the settings-toggle clicks provide.
+ *
+ * Anti-spam: the first snapshot after install only arms the baseline (a page
+ * load never fires a burst); events fire on transitions only; a short
+ * per-session+kind cooldown absorbs reconnect re-pull flicker. Subagent child
+ * rows are skipped — their parent carries the turn, and mid-turn subagent
+ * completions would be noise.
+ * @module dsh-ui-tweaks/client/notifier
+ */
+
+import type { ISessions } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SessionPendingInteractionSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { TurnOutcomeValue } from '../../ui-tweaks/turn-outcome.ts'
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    dshTurnOutcome: TurnOutcomeValue | null
+  }
+}
+
+/** List-row key carrying the turn outcome; keep in sync with src/turn-outcome.ts. */
+const TURN_OUTCOME_KEY = 'dshTurnOutcome'
+
+/** Interaction kinds the host reports while a session blocks on the user. */
+export type NotifyPendingKind = 'approval' | 'plan-review' | 'question'
+
+/** Event classes the notifier can raise. */
+type NotifyEventKind = 'complete' | 'aborted' | 'failed' | 'interaction'
+
+/** Terminal-turn announcement kinds — they all answer "your task ended". */
+const TERMINAL_KINDS = ['complete', 'aborted', 'failed'] as const
+
+/** Localized copy snapshot the notifier needs (resolved once at install). */
+export interface NotifierText {
+  /** System-notification heading for completion events. */
+  notifyTitleDone: string
+  /** System-notification heading for user-interrupted turns. */
+  notifyTitleAborted: string
+  /** System-notification heading for failed requests. */
+  notifyTitleFailed: string
+  /** System-notification heading for interaction events. */
+  notifyTitlePending: string
+  /** Completion body template; `{title}` becomes the session display title. */
+  bodyComplete: string
+  /** Interruption body template. */
+  bodyAborted: string
+  /** Failure body template; `{error}` becomes the truncated failure message. */
+  bodyFailed: string
+  /** Approval body template. */
+  bodyApproval: string
+  /** Plan-review body template. */
+  bodyPlan: string
+  /** Question body template. */
+  bodyQuestion: string
+}
+
+/**
+ * Live-read behavior switches — read through {@link TaskNotifierInput.readState}
+ * on every feed tick so settings-panel flips apply without reinstalling.
+ */
+export interface NotifierOptions {
+  /** Raise alerts only while the page is hidden or unfocused. */
+  onlyWhenHidden: boolean
+  /** Alert when a session finishes its turn. */
+  onComplete: boolean
+  /** Alert when a session starts waiting on the user. */
+  onInteraction: boolean
+}
+
+/** Output channels, each independently toggleable. */
+export interface NotifierChannels {
+  titleFlash: boolean
+  systemNotification: boolean
+  sound: boolean
+}
+
+/** Install-time wiring for {@link installTaskNotifier}. */
+export interface TaskNotifierInput {
+  /** The client sessions service whose list feed carries the watch states. */
+  sessionsService: ISessions
+  /** Current Session-scoped interactions, published separately from list rows. */
+  pendingInteractions: HostObservable<SessionPendingInteractionSnapshot>
+  /** Localized copy snapshot used across the notifier's lifetime. */
+  text: NotifierText
+  /** Fresh behavior switches + channel toggles, read on every tick. */
+  readState(): { options: NotifierOptions; channels: NotifierChannels }
+}
+
+/** Per-session state the transition detector compares against. */
+interface WatchState {
+  running: boolean
+  pending: NotifyPendingKind | undefined
+  completed: boolean
+  outcome: TurnOutcomeValue | undefined
+}
+
+/** Narrow the extensible host interaction roster to the notification copy we own. */
+function pendingKind(
+  snapshot: SessionPendingInteractionSnapshot,
+  sessionId: SessionId,
+): NotifyPendingKind | undefined {
+  switch (snapshot.get(sessionId)?.kind) {
+    case 'approval':
+      return 'approval'
+    case 'plan-review':
+      return 'plan-review'
+    case 'question':
+      return 'question'
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Map a logged `turn/end` reason onto an announcement kind. Unknown or absent
+ * outcomes (older host, projection lag) degrade to a plain completion.
+ */
+const classifyFinish = (outcome: TurnOutcomeValue | undefined): 'complete' | 'aborted' | 'failed' => {
+  switch (outcome?.kind) {
+    case 'aborted':
+    case 'interrupted':
+      return 'aborted'
+    case 'error':
+      return 'failed'
+    default:
+      return 'complete'
+  }
+}
+
+/** Same event kind for one session never repeats inside this window. */
+const COOLDOWN_MS = 2000
+/**
+ * A background session's finish usually announces via the running-drop; the
+ * host's green `completed` reminder often lands a re-pull later — treat it as
+ * the SAME completion inside this window instead of re-toasting it.
+ */
+const COMPLETE_RENOTIFY_MS = 30000
+/** Title-flash blink period. */
+const FLASH_INTERVAL_MS = 900
+
+/**
+ * `NotificationOptions` plus Chrome's `renotify` (re-alert on tag replace).
+ * The option is real and supported at runtime, but this project's DOM lib
+ * predates its type declaration, so it is declared locally.
+ */
+interface RealertableNotificationOptions extends NotificationOptions {
+  renotify?: boolean
+}
+
+/** Replace the `{title}` / `{error}` placeholders (split/join — no regex escaping worries). */
+function fill(template: string, title: string, error: string | undefined): string {
+  return template.split('{error}').join(error ?? '').split('{title}').join(title)
+}
+
+/**
+ * Ask the browser for desktop-notification permission. Must run inside a user
+ * gesture (the settings toggle's click) to avoid a denied or ignored prompt;
+ * repeated calls are cheap no-ops once decided.
+ */
+export function requestNotifyPermission(): void {
+  try {
+    if (typeof Notification === 'undefined') return
+    if (Notification.permission === 'default') void Notification.requestPermission()
+  } catch {
+    // Notifications unsupported — the other channels carry on.
+  }
+}
+
+/**
+ * Forced title-flash preview for the settings panel's 测试 button: the real
+ * flash auto-clears the moment its page is visible AND focused — which is
+ * exactly the tester's situation, so a plain preview would heal instantly and
+ * show nothing. Instead this blinks unconditionally for a few seconds, then
+ * restores whatever title was current at click time.
+ */
+let previewBlinkTimer: number | undefined
+let previewStopTimer: number | undefined
+
+export function previewTitleFlash(durationMs = 6000): void {
+  // Restart cleanly on rapid re-clicks.
+  if (previewBlinkTimer !== undefined) window.clearInterval(previewBlinkTimer)
+  if (previewStopTimer !== undefined) window.clearTimeout(previewStopTimer)
+  const base = document.title
+  let tick = false
+  const blink = (): void => {
+    tick = !tick
+    document.title = tick ? `(1) 🔔 ${base}` : `(1) ${base}`
+  }
+  blink()
+  previewBlinkTimer = window.setInterval(blink, FLASH_INTERVAL_MS)
+  previewStopTimer = window.setTimeout(() => {
+    if (previewBlinkTimer !== undefined) {
+      window.clearInterval(previewBlinkTimer)
+      previewBlinkTimer = undefined
+    }
+    previewStopTimer = undefined
+    document.title = base
+  }, durationMs)
+}
+
+/**
+ * One-shot self-test for the settings panel's 测试 button: previews every
+ * enabled channel — a forced ~6s title-flash blink (the real one would clear
+ * instantly on a focused page), the falling (needs-you) chime, and, when
+ * permission is already granted, one sample system notification.
+ */
+export function previewAlerts(channels: NotifierChannels, text: NotifierText): void {
+  requestNotifyPermission()
+  if (channels.titleFlash) previewTitleFlash()
+  if (channels.sound) playChime('down')
+  if (!channels.systemNotification || typeof Notification === 'undefined') return
+  if (Notification.permission !== 'granted') return
+  try {
+    const sample = fill(text.bodyComplete, 'ChatCode CLI', undefined)
+    new Notification(text.notifyTitleDone, { body: sample, tag: 'dsh-ui-tweaks:preview', silent: true })
+  } catch {
+    // Construction can throw on some platforms — degrade quietly.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Chime — WebAudio two-note motif, synthesized, no assets.
+// ---------------------------------------------------------------------------
+
+let audioCtx: AudioContext | undefined
+
+function playChime(shape: 'up' | 'down'): void {
+  try {
+    audioCtx ??= new AudioContext()
+    const ctx = audioCtx
+    // Sticky activation from earlier clicks usually suffices; resume is best effort.
+    if (ctx.state === 'suspended') void ctx.resume().catch(() => {})
+    const now = ctx.currentTime
+    const notes = shape === 'up' ? [880, 1318.51] : [1174.66, 783.99]
+    // 240ms between notes with a long decay each: tight spacing read as ONE
+    // blip in listening tests; this wide a gap keeps the two tones distinct
+    // (rising = done, falling = needs you).
+    notes.forEach((freq, i) => {
+      const osc = ctx.createOscillator()
+      const gain = ctx.createGain()
+      osc.type = 'sine'
+      osc.frequency.value = freq
+      const t0 = now + i * 0.24
+      gain.gain.setValueAtTime(0.0001, t0)
+      gain.gain.exponentialRampToValueAtTime(0.22, t0 + 0.03)
+      gain.gain.exponentialRampToValueAtTime(0.0001, t0 + 0.2)
+      osc.connect(gain)
+      gain.connect(ctx.destination)
+      osc.start(t0)
+      osc.stop(t0 + 0.24)
+    })
+  } catch {
+    // Audio unavailable (autoplay policy, missing AudioContext) — stay silent.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Installer.
+// ---------------------------------------------------------------------------
+
+/**
+ * Install the task notifier against the sessions list feed.
+ * @returns disposer — unsubscribes, restores the tab title and tears the channels down.
+ */
+export function installTaskNotifier(input: TaskNotifierInput): () => void {
+  const { sessionsService, pendingInteractions, text, readState } = input
+  const list = sessionsService.list
+
+  // --- detector state ------------------------------------------------------
+  const watch = new Map<SessionId, WatchState>()
+  const lastFired = new Map<string, number>()
+
+  // --- title flash ---------------------------------------------------------
+  let originalTitle: string | null = null
+  let flashTimer: number | undefined
+  let flashTick = false
+  let unread = 0
+
+  const visibleAndFocused = (): boolean => document.visibilityState === 'visible' && document.hasFocus()
+
+  const startTitleFlash = (): void => {
+    if (flashTimer !== undefined) return
+    originalTitle = document.title
+    flashTimer = window.setInterval(() => {
+      flashTick = !flashTick
+      const base = originalTitle ?? ''
+      document.title = flashTick ? `(${unread}) 🔔 ${base}` : `(${unread}) ${base}`
+    }, FLASH_INTERVAL_MS)
+  }
+
+  const stopTitleFlash = (): void => {
+    if (flashTimer !== undefined) {
+      window.clearInterval(flashTimer)
+      flashTimer = undefined
+    }
+    if (originalTitle !== null) document.title = originalTitle
+    originalTitle = null
+    unread = 0
+  }
+
+  /** Coming back to a visible, focused page acknowledges everything. */
+  const settleIfBack = (): void => {
+    if (visibleAndFocused()) stopTitleFlash()
+  }
+  const onVisibilityChange = (): void => {
+    settleIfBack()
+  }
+  window.addEventListener('focus', settleIfBack)
+  document.addEventListener('visibilitychange', onVisibilityChange)
+
+  // --- system notification -------------------------------------------------
+  const fireSystemNotification = (
+    kind: NotifyEventKind,
+    sessionId: SessionId,
+    heading: string,
+    body: string,
+    chimeOn: boolean,
+  ): void => {
+    if (typeof Notification === 'undefined') return
+    if (Notification.permission !== 'granted') return
+    try {
+      // `silent` mirrors the chime channel: our motif is THE sound, so mute
+      // the OS bark while it will play; otherwise let the platform ring.
+      // `renotify` forces a fresh banner when this tag REPLACES an existing
+      // toast — without it Chrome swaps the old toast silently and Windows
+      // collapses it into the notification center.
+      const options: RealertableNotificationOptions = {
+        body,
+        tag: `dsh-ui-tweaks:${sessionId}:${kind}`,
+        silent: chimeOn,
+        renotify: true,
+      }
+      const n = new Notification(heading, options)
+      n.onclick = (): void => {
+        try { window.focus() } catch { /* ignore */ }
+        try { sessionsService.open(sessionId) } catch { /* session already gone — focus alone is fine */ }
+        n.close()
+      }
+    } catch {
+      // Construction can throw on some platforms — degrade quietly.
+    }
+  }
+
+  // --- delivery ------------------------------------------------------------
+  const deliver = (
+    sessionId: SessionId,
+    displayTitle: string,
+    kind: NotifyEventKind,
+    pending: NotifyPendingKind | undefined,
+    detail: string | undefined,
+    channels: NotifierChannels,
+    now: number,
+  ): void => {
+    const cooldownKey = `${sessionId}:${kind}`
+    const last = lastFired.get(cooldownKey)
+    if (last !== undefined && now - last < COOLDOWN_MS) return
+    lastFired.set(cooldownKey, now)
+
+    unread += 1
+    if (channels.titleFlash) startTitleFlash()
+    if (!channels.systemNotification && !channels.sound) return
+
+    const heading = kind === 'complete'
+      ? text.notifyTitleDone
+      : kind === 'aborted'
+        ? text.notifyTitleAborted
+        : kind === 'failed'
+          ? text.notifyTitleFailed
+          : text.notifyTitlePending
+    let body = kind === 'aborted'
+      ? text.bodyAborted
+      : kind === 'failed'
+        ? text.bodyFailed
+        : text.bodyComplete
+    if (kind === 'interaction') {
+      body = pending === 'approval'
+        ? text.bodyApproval
+        : pending === 'plan-review'
+          ? text.bodyPlan
+          : text.bodyQuestion
+    }
+    fireSystemNotification(kind, sessionId, heading, fill(body, displayTitle, detail), channels.sound)
+    if (channels.sound) playChime(kind === 'complete' ? 'up' : 'down')
+  }
+
+  // --- baseline arming -----------------------------------------------------
+  /** Seed the watch map without firing: fresh installs and reloads stay quiet. */
+  const armBaseline = (): void => {
+    watch.clear()
+    const interactions = pendingInteractions.getSnapshot()
+    for (const row of Object.values(list.getSnapshot().byId)) {
+      if (row.parentId !== undefined || row.blank) continue
+      const outcome = row.projectionValues?.[TURN_OUTCOME_KEY] ?? undefined
+      watch.set(row.id, {
+        running: row.running,
+        pending: pendingKind(interactions, row.id),
+        completed: row.completed === true,
+        outcome,
+      })
+    }
+  }
+
+  // --- feed tick -----------------------------------------------------------
+  const check = (): void => {
+    const { options, channels } = readState()
+    const deliverable = !options.onlyWhenHidden || !visibleAndFocused()
+    const now = Date.now()
+    const snap = list.getSnapshot()
+    const interactions = pendingInteractions.getSnapshot()
+    const seen = new Set<SessionId>()
+
+    for (const row of Object.values(snap.byId)) {
+      if (row.parentId !== undefined || row.blank) continue
+      seen.add(row.id)
+      const prev = watch.get(row.id)
+      const outcome = row.projectionValues?.[TURN_OUTCOME_KEY] ?? undefined
+      const pending = pendingKind(interactions, row.id)
+      watch.set(row.id, { running: row.running, pending, completed: row.completed === true, outcome })
+      if (prev === undefined) continue
+
+      // Interaction outranks completion: a turn ending ON a question must
+      // announce the question, not a completion.
+      if (prev.pending === undefined && pending !== undefined) {
+        if (options.onInteraction && deliverable) {
+          deliver(row.id, row.displayTitle, 'interaction', pending, undefined, channels, now)
+        }
+        continue
+      }
+
+      const finished = prev.running && !row.running && pending === undefined
+      const completedReminder = !prev.completed && row.completed === true
+      if (finished || completedReminder) {
+        // The green `completed` reminder often arrives a re-pull AFTER the
+        // running-drop already announced the same finish — inside the
+        // re-notify window it is a duplicate, not a new completion.
+        let shouldFire = finished
+        if (!shouldFire) {
+          // Any recent terminal announcement (of any outcome kind) makes the
+          // green-dot reminder a duplicate of the same finish.
+          shouldFire = TERMINAL_KINDS.every((kind) => {
+            const last = lastFired.get(`${row.id}:${kind}`)
+            return last === undefined || now - last >= COMPLETE_RENOTIFY_MS
+          })
+        }
+        if (shouldFire && options.onComplete && deliverable) {
+          // Trust the outcome only when it CHANGED on this very transition —
+          // a stale value from an earlier turn would mislabel the announce.
+          const fresh = prev.outcome === undefined
+            || outcome?.time !== prev.outcome.time
+            || outcome?.kind !== prev.outcome.kind
+          const announcement = fresh && outcome !== undefined ? classifyFinish(outcome) : 'complete'
+          deliver(row.id, row.displayTitle, announcement, undefined, outcome?.errorMessage, channels, now)
+        }
+      }
+    }
+
+    // Forget removed sessions so a re-added id arms fresh instead of comparing
+    // against stale pre-removal state.
+    for (const id of watch.keys()) {
+      if (!seen.has(id)) watch.delete(id)
+    }
+  }
+
+  armBaseline()
+  const disposeFeed = list.subscribe(check)
+  const disposeInteractions = pendingInteractions.subscribe(check)
+
+  return () => {
+    disposeFeed()
+    disposeInteractions()
+    stopTitleFlash()
+    window.removeEventListener('focus', settleIfBack)
+    document.removeEventListener('visibilitychange', onVisibilityChange)
+    watch.clear()
+    lastFired.clear()
+    if (audioCtx !== undefined) {
+      void audioCtx.close().catch(() => {})
+      audioCtx = undefined
+    }
+  }
+}

package/src/client/ui-tweaks/whale.tsx

@@ -0,0 +1,171 @@
+/**
+ * dsh-ui-tweaks — whale working indicator (browser half).
+ *
+ * A compact China-knot brand mark perched on the composer card's top-right
+ * corner over drifting red waves. It is resident while the feature is on;
+ * idle it rests in brand red, and while the model works it floats and breathes
+ * through the red accent spectrum.
+ *
+ * - Mounted in `conversation.input.dock` (the full-width row stacked by the
+ *   composer column right above the card), registered only while the
+ *   `whaleIndicatorEnabled` toggle is on — off costs nothing. The dock row is
+ *   WIDER than the card (the card is capped at
+ *   `--dsh-composer-card-max-width` and centered with
+ *   `--dsh-composer-side-clearance` side padding by the InputBar root), so
+ *   the row replicates that exact geometry — same max-width, centered, same
+ *   side padding — before right-aligning; a 6px `translateY` then straddles
+ *   the card's top edge. The extra 14px right inset centers the whale over
+ *   the send button (34px round button, 8px tool-row padding → its center
+ *   sits 25px from the card's right edge; the 22px whale's right edge at
+ *   14px puts its center at 25px).
+ * - "Working" = the current session's `running` flag on the sessions list
+ *   feed, OR the input machine's claimed/submitting phases (the window
+ *   between pressing Enter and the agent actually starting to run).
+ * - The mark is self-contained rather than lifted from the host sidebar, so
+ *   its branding remains consistent while DSH changes its own logo.
+ * @module dsh-ui-tweaks/client/whale
+ */
+
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import type { ISessions } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * China-knot-inspired geometry, painted in `currentColor`.
+ */
+const KNOT_PATHS = [
+  'M32 5c-8.5 0-15.5 6.9-15.5 15.5 0 8.6 6.1 12.8 15.5 18.8 9.4-6 15.5-10.2 15.5-18.8C47.5 11.9 40.5 5 32 5Z',
+  'M32 59c8.5 0 15.5-6.9 15.5-15.5 0-8.6-6.1-12.8-15.5-18.8-9.4 6-15.5 10.2-15.5 18.8C16.5 52.1 23.5 59 32 59Z',
+  'M5 32c0-8.5 6.9-15.5 15.5-15.5 8.6 0 12.8 6.1 18.8 15.5-6 9.4-10.2 15.5-18.8 15.5C11.9 47.5 5 40.5 5 32Z',
+  'M59 32c0 8.5-6.9 15.5-15.5 15.5-8.6 0-12.8-6.1-18.8-15.5 6-9.4 10.2-15.5 18.8-15.5C52.1 16.5 59 23.5 59 32Z',
+]
+
+/** Brand mark width in px; square geometry keeps it crisp beside Send. */
+const KNOT_WIDTH = 22
+
+// ---------------------------------------------------------------------------
+// Styles — resident (translucent, still) vs working (opaque, swimming).
+// ---------------------------------------------------------------------------
+
+export const WHALE_CSS = `
+.duwi-row{box-sizing:border-box;width:100%;max-width:calc(var(--dsh-composer-card-max-width) + 2 * var(--dsh-composer-side-clearance, 0px));margin:0 auto;padding:0 calc(var(--dsh-composer-side-clearance, 0px) + 14px) 0 var(--dsh-composer-side-clearance, 0px);display:flex;align-items:flex-end;justify-content:flex-end;height:27px;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
+.duwi-stack{display:flex;flex-direction:column;align-items:center;transform:translateY(6px)}
+.duwi-whale{display:block;color:#9B0B09;transform-origin:50% 60%;pointer-events:auto;cursor:pointer}
+.duwi-row.duwi-swim .duwi-whale{animation:duwi-swim 1.9s ease-in-out infinite,duwi-breathe 1.9s ease-in-out infinite}
+.duwi-whale:hover{animation:duwi-swim 1.9s ease-in-out infinite}
+.duwi-waves{display:block;width:26px;height:9px;margin-top:-3px;overflow:hidden}
+.duwi-wave-back{stroke:#d96a65;opacity:.35}
+.duwi-wave-front{stroke:#9B0B09;opacity:.8}
+.duwi-wave-front,.duwi-wave-back{animation:duwi-drift-front 1.9s linear infinite}
+.duwi-wave-back{animation-duration:3.4s;animation-direction:reverse}
+@keyframes duwi-swim{
+0%,100%{transform:translateY(0) rotate(-4deg)}
+50%{transform:translateY(-3.5px) rotate(4deg)}
+}
+@keyframes duwi-breathe{
+0%,100%{color:#9B0B09}
+50%{color:#d94b45}
+}
+@keyframes duwi-drift-front{
+from{transform:translateX(0)}
+to{transform:translateX(-8px)}
+}
+@media (prefers-reduced-motion:reduce){
+.duwi-row.duwi-swim .duwi-whale,.duwi-whale:hover{animation:none}
+.duwi-wave-front,.duwi-wave-back{animation:none}
+}
+`
+
+/** Idempotent installer for the indicator styles (same pattern as the other features). */
+export function installWhaleStyles(): () => void {
+  const id = 'dsh-ui-tweaks-whale'
+  const existing = document.querySelector(`style[data-plugin-css="${id}"]`)
+  if (existing !== null) return () => {}
+  const style = document.createElement('style')
+  style.dataset.plugin = 'dsh-ui-tweaks'
+  style.dataset.pluginCss = id
+  style.textContent = WHALE_CSS
+  document.head.appendChild(style)
+  return () => { style.remove() }
+}
+
+// ---------------------------------------------------------------------------
+// Live whale geometry refresh.
+// ---------------------------------------------------------------------------
+
+/**
+// ---------------------------------------------------------------------------
+// Component.
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural slice of the framework `InputState` (not re-exported by the
+ * package's client entry) — exactly the fields the indicator reads off the
+ * dock's owner share.
+ */
+interface InputPhaseSnapshot {
+  phase: 'plain' | 'adjudicating' | 'claimed' | 'submitting'
+}
+
+export interface WhaleIndicatorProps {
+  /** Framework seat (PropsRuntime): current session id. */
+  sessionId: SessionId | undefined
+  /** Owner share (InputZone): live input-machine snapshot — covers the send → run window. */
+  input: InputPhaseSnapshot
+  /** Injected: the client sessions service (list feed carrying `running`). */
+  sessionsService: ISessions
+}
+
+export function WhaleIndicator({ sessionId, input, sessionsService }: WhaleIndicatorProps) {
+  // Idle easter egg: a click swims the whale for a couple of cycles.
+  const [peek, setPeek] = useState(false)
+  const peekTimer = useRef<number | undefined>(undefined)
+  useEffect(() => () => { window.clearTimeout(peekTimer.current) }, [])
+  const swimFor = (): void => {
+    setPeek(true)
+    window.clearTimeout(peekTimer.current)
+    peekTimer.current = window.setTimeout(() => { setPeek(false) }, 3800)
+  }
+
+  // The current session's `running` flag, straight off the sessions list feed.
+  const list = sessionsService.list
+  const subscribe = useMemo(() => list.subscribe.bind(list), [list])
+  const running = useSyncExternalStore(
+    subscribe,
+    () => {
+      const snapshot = list.getSnapshot()
+      const id = sessionId ?? snapshot.current
+      return id !== undefined && (snapshot.byId[id]?.running ?? false)
+    },
+    () => false,
+  )
+
+  // `claimed`/`submitting` bridge the gap between Enter and the agent start.
+  const submitting = input.phase === 'claimed' || input.phase === 'submitting'
+  const swim = running || submitting || peek
+
+  return (
+    <div className={swim ? 'duwi-row duwi-swim' : 'duwi-row'} aria-hidden="true">
+      <div className="duwi-stack">
+        <svg
+          className="duwi-whale"
+          width={KNOT_WIDTH}
+          height={KNOT_WIDTH}
+          viewBox="0 0 64 64"
+          fill="none"
+          onClick={swimFor}
+        >
+          <g stroke="currentColor" strokeWidth="5.2" strokeLinecap="round" strokeLinejoin="round">
+            {KNOT_PATHS.map((path) => <path key={path} d={path} />)}
+          </g>
+          <circle cx="32" cy="32" r="5.5" fill="currentColor" />
+        </svg>
+        <svg className="duwi-waves" viewBox="0 0 26 9" fill="none">
+          {/* Wavelength-8 sine strips drawn from -8 to +40 so the ±8px drift loop stays covered. */}
+          <path className="duwi-wave-back" d="M-8 4 Q-4 5.8 0 4 T8 4 T16 4 T24 4 T32 4 T40 4" strokeWidth="1.4" strokeLinecap="round" />
+          <path className="duwi-wave-front" d="M-8 5.5 Q-4 3.3 0 5.5 T8 5.5 T16 5.5 T24 5.5 T32 5.5 T40 5.5" strokeWidth="1.4" strokeLinecap="round" />
+        </svg>
+      </div>
+    </div>
+  )
+}