Merge pull request #580 from danshapiro/feat/deck-icons-polish

feat(deck): visual polish — circular avatars, Inter font, token-derived palette, tinted agent icons

Author: danshapiro

docs/plans/2026-07-29-deck-icons-polish.md

@@ -88,6 +88,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@elgato-stream-deck/webhid": "^7.6.3",
+    "@fontsource/inter": "^5.3.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@monaco-editor/react": "^4.6.0",
     "@reduxjs/toolkit": "^2.3.0",

package-lock.json

@@ -27,6 +27,9 @@ function noopCtx(width: number, height: number): Ctx2D {
     fillRect: () => {},
     fillText: () => {},
     drawImage: () => {},
+    beginPath: () => {},
+    arc: () => {},
+    fill: () => {},
     measureText: () => ({ width: 0 }) as TextMetrics,
     getImageData: () => ({ data: new Uint8ClampedArray(width * height * 4) }) as ImageData,
   }

package.json

@@ -24,6 +24,18 @@ export function hueFromString(input: string): number {
   return Math.abs(hash) % 360
 }
 
+/**
+ * Canonical letter-avatar fill. 60% saturation / 42% lightness keeps white
+ * text readable in both themes. Shared with the deck's canvas replica
+ * (src/deck/tile-renderer.ts) — change it here and both surfaces follow.
+ */
+export function repoAvatarColor(hue: number): string {
+  return `hsl(${hue}, 60%, 42%)`
+}
+
+/** Letter font-size as a fraction of the avatar diameter (SVG: 9 units / 16-unit viewBox). */
+export const REPO_AVATAR_FONT_RATIO = 9 / 16
+
 /**
  * Decorative repo identity icon: the repo's own icon via the server when
  * available, else a letter avatar (uppercase first letter on a circle with a
@@ -44,18 +56,16 @@ export default function RepoIcon({ info, className }: RepoIconProps) {
     )
   }
   const letter = (info.repoName.trim()[0] || '?').toUpperCase()
-  // 60% saturation / 42% lightness keeps white text readable on the circle
-  // in both light and dark themes.
   const hue = hueFromString(info.repoName)
   return (
     <svg viewBox="0 0 16 16" aria-hidden="true" className={cn('shrink-0', className)}>
-      <circle cx="8" cy="8" r="8" fill={`hsl(${hue}, 60%, 42%)`} />
+      <circle cx="8" cy="8" r="8" fill={repoAvatarColor(hue)} />
       <text
         x="8"
         y="8.5"
         textAnchor="middle"
         dominantBaseline="central"
-        fontSize="9"
+        fontSize={16 * REPO_AVATAR_FONT_RATIO}
         fontWeight="600"
         fill="white"
       >

src/components/VirtualDeckPanel.tsx

@@ -27,6 +27,7 @@ import { fetchRepoIconMeta } from '@/store/repoIconsSlice'
 import { resolvePaneRepoCwd } from '@/lib/repo-icon'
 import { IconImageCache, getIconImageCache } from './icon-image-cache'
 import { defaultCtxFactory, renderKey as canvasRenderKey, renderStrip as canvasRenderStrip } from './tile-renderer'
+import { whenDeckFontReady } from './deck-font'
 
 export type DeckControllerOptions = {
   store: DeckStore & { subscribe(cb: () => void): () => void }
@@ -36,6 +37,8 @@ export type DeckControllerOptions = {
   settings: () => { brightness: number; idleBrightness: number; idleTimeoutSeconds: number; tileStyle: DeckTileStyle }
   now?: () => number
   iconCache?: IconImageCache
+  /** Injectable font-ready hook (defaults to whenDeckFontReady); tests drive it directly. */
+  fontReady?: (onReady: () => void) => () => void
 }
 
 /** What a key displayed at press-down - snapshotted so re-sorts can't retarget a press. */
@@ -76,6 +79,9 @@ export class DeckController {
   private intervalId: ReturnType<typeof setInterval> | null = null
   private onVisibilityChange: (() => void) | null = null
 
+  private readonly fontReady: (onReady: () => void) => () => void
+  private cancelFontWait: (() => void) | null = null
+
   constructor(options: DeckControllerOptions) {
     this.store = options.store
     this.device = options.device
@@ -85,6 +91,7 @@ export class DeckController {
     this.renderStripFn = options.renderStrip ?? ((text, width, height) => canvasRenderStrip(text, width, height, defaultCtxFactory))
     this.settings = options.settings
     this.now = options.now ?? (() => Date.now())
+    this.fontReady = options.fontReady ?? whenDeckFontReady
   }
 
   start(): void {
@@ -93,6 +100,13 @@ export class DeckController {
     this.repaint()
     this.probeRepoIcons()
     this.unsubscribeIcons = this.iconCache.subscribe(() => this.repaint())
+    this.cancelFontWait = this.fontReady(() => {
+      // A font load changes no KeySpec, so the JSON diff (repaint(), line ~148)
+      // would paint nothing: invalidate the caches to force a real repaint in Inter.
+      this.lastPaintedSpecs = []
+      this.lastStripText = null
+      this.repaint()
+    })
     this.unsubscribeStore = this.store.subscribe(() => this.onStoreChange())
     this.unsubscribeInput = this.device.onInput((event) => this.handleInput(event))
     this.intervalId = setInterval(() => this.tick(), TICK_MS)
@@ -110,6 +124,8 @@ export class DeckController {
     this.unsubscribeInput = null
     this.unsubscribeIcons?.()
     this.unsubscribeIcons = null
+    this.cancelFontWait?.()
+    this.cancelFontWait = null
     if (this.intervalId !== null) {
       clearInterval(this.intervalId)
       this.intervalId = null

src/components/icons/RepoIcon.tsx

@@ -0,0 +1,40 @@
+// Deck tile typeface: Inter, bundled locally via @fontsource (src/index.css
+// imports weights 400/600 — no CDN fetch). Canvas ctx.font does NOT trigger
+// webfont loading, so the deck controller waits for the FontFace load and
+// forces a repaint; until then every deck font string falls back to
+// sans-serif (DECK_FONT_STACK lists it second) without breaking.
+// jsdom has no document.fonts: every path here degrades to a silent no-op
+// (console.error is fatal in tests; a missing font is expected, not
+// exceptional — same rule as icon-image-cache.ts).
+// Two verified FontFaceSet facts shape this module: (1) fonts.load('400 16px
+// "Inter"') uses load()'s default sample text (a single space), so it loads
+// only the latin-subset face — non-Latin deck text stays in the sans-serif
+// fallback (accepted as fine for v1); (2) load() REJECTS on a broken src, so
+// the .catch below is MANDATORY (without it a failed load is an unhandled
+// rejection, which is fatal under the test rules).
+
+export const DECK_FONT_FAMILY = 'Inter'
+/** Family list for ctx.font strings: Inter once loaded, sans-serif before. */
+export const DECK_FONT_STACK = `${DECK_FONT_FAMILY}, sans-serif`
+
+/**
+ * Invoke onReady once the deck's font weights (400 + 600) are loaded so the
+ * caller can repaint with Inter. Returns a cancel function — after cancel a
+ * late load is ignored (the controller calls it from stop()).
+ */
+export function whenDeckFontReady(onReady: () => void): () => void {
+  let cancelled = false
+  const fonts = typeof document !== 'undefined' ? document.fonts : undefined
+  if (!fonts?.load) return () => { cancelled = true }
+  void Promise.all([
+    fonts.load(`400 16px "${DECK_FONT_FAMILY}"`),
+    fonts.load(`600 16px "${DECK_FONT_FAMILY}"`),
+  ])
+    .then(() => {
+      if (!cancelled) onReady()
+    })
+    .catch(() => {
+      // Font failure -> keep the sans-serif fallback, silently.
+    })
+  return () => { cancelled = true }
+}

src/deck/deck-controller.ts

@@ -10,6 +10,10 @@ import { buildRepoIconUrl, pathBasename, resolvePaneRepoCwd } from '@/lib/repo-i
 import { hueFromString } from '@/components/icons/RepoIcon'
 import { makeFreshAgentSessionKey } from '@shared/fresh-agent'
 import type { DeckTileStyle } from '@shared/settings'
+import { isNonShellMode } from '@/lib/coding-cli-utils'
+
+export type TilePaneTint = 'blue' | 'green' | 'amber' | 'red' | 'mutedDim' | 'muted'
+export type TilePaneIcon = { provider: string; tint: TilePaneTint }
 
 export type DeckTab = {
   id: string
@@ -22,6 +26,7 @@ export type DeckTab = {
   dot: TileDot
   priority: number
   repoIcons: TileRepoIcon[]
+  paneIcons: TilePaneIcon[]
 }
 export type DeckModel = { tabs: DeckTab[]; activeTabId: string | null; tileStyle: DeckTileStyle }
 
@@ -122,6 +127,48 @@ export function getTabRepoIcons(state: RootState, tab: Tab): TileRepoIcon[] {
   return icons
 }
 
+/** Mirrors getTerminalStatusIconClassName (src/lib/terminal-status-indicator.ts). */
+function paneStatusTint(status: string): TilePaneTint {
+  switch (status) {
+    case 'running': return 'green'      // text-success
+    case 'recovering': return 'amber'   // text-warning
+    case 'exited': return 'mutedDim'    // text-muted-foreground/40
+    case 'error': return 'red'          // text-destructive
+    default: return 'muted'             // creating etc. -> text-muted-foreground
+  }
+}
+
+/**
+ * Agent pane icons for a tab, in layout order, UNCAPPED (the renderer caps
+ * drawn icons and folds the rest into a +N badge — TabItem's MAX_PANE_ICONS
+ * overflow rule adapted to key size). Agent panes are non-shell terminals
+ * (provider = mode) and fresh-agent panes (provider = sessionType);
+ * shell/browser/editor/picker/extension panes draw no agent icon on a key
+ * this small. Tint mirrors TabItem.tsx renderIcons: busy -> blue (wins),
+ * else the pane's effective status (non-terminal kinds count as 'running').
+ */
+export function getTabPaneIcons(state: RootState, tab: Tab): TilePaneIcon[] {
+  const busyIds = getBusyPaneIdsForTab({
+    tab,
+    paneLayouts: state.panes.layouts as Record<string, PaneNode | undefined>,
+    ...activityInputs(state),
+  })
+  const icons: TilePaneIcon[] = []
+  for (const { paneId, content } of panesForTab(state, tab)) {
+    let provider: string | null = null
+    let status = 'running'
+    if (content.kind === 'terminal' && isNonShellMode(content.mode)) {
+      provider = content.mode
+      status = content.status
+    } else if (content.kind === 'fresh-agent') {
+      provider = content.sessionType
+    }
+    if (!provider) continue
+    icons.push({ provider, tint: busyIds.includes(paneId) ? 'blue' : paneStatusTint(status) })
+  }
+  return icons
+}
+
 /**
  * Per-tab status flags, derived from the SAME conditions the tab bar uses:
  * - busy: any pane busy (getBusyPaneIdsForTab, TabBar.tsx:329-338)
@@ -167,6 +214,7 @@ export function selectDeckModel(state: RootState): DeckModel {
       dot: tileDot(flags),
       priority: tilePriority(active, flags),
       repoIcons: getTabRepoIcons(state, tab),
+      paneIcons: getTabPaneIcons(state, tab),
     }
   })
   if (tileStyle === 'status-icons') {

src/deck/deck-font.ts

@@ -1,13 +1,16 @@
 import type { DeckCapabilities } from './deck-device'
-import type { DeckModel } from './deck-selectors'
-import type { TileFill, TileDot } from './tile-state'
+import type { DeckModel, TilePaneIcon } from './deck-selectors'
+import type { TileFill } from './tile-state'
+import { PANE_TINT_COLORS } from './pane-tint-colors'
+import { providerIconDataUrl } from './provider-icon-svg'
 
 export type RingColor = 'amber' | 'green' | 'blue' | null
 export type DeckAction = 'back' | 'approve' | 'stop'
 export type TileIcon = { url: string | null; letter: string; hue: number; ready: boolean }
+export type TilePaneIconSpec = TilePaneIcon & { ready: boolean }
 export type KeySpec =
   | { kind: 'empty' }
-  | { kind: 'tab'; style: 'icons'; tabId: string; title: string; active: boolean; fill: TileFill; dot: TileDot; icons: TileIcon[] }
+  | { kind: 'tab'; style: 'icons'; tabId: string; title: string; active: boolean; fill: TileFill; paneIcons: TilePaneIconSpec[]; icons: TileIcon[] }
   | { kind: 'tab'; style: 'preview'; tabId: string; title: string; active: boolean; previewLines: string[]; ring: RingColor }
   | { kind: 'pager'; page: number; pageCount: number }
   | { kind: 'action'; action: DeckAction; enabled: boolean }
@@ -119,7 +122,18 @@ export function buildFrame({ model, caps, page, actionLayer, iconReady, previewF
           }
         : {
             kind: 'tab', style: 'icons', tabId: tab.id, title: tab.title, active: tab.active,
-            fill: tab.fill, dot: tab.dot,
+            fill: tab.fill,
+            // Readiness must live IN the spec: the controller's repaint() skips
+            // keys whose JSON is unchanged, so the decode completing has to flip
+            // a spec field to trigger the repaint — same mechanism as the repo
+            // icons below. iconReady (bitmapFor in production) also STARTS the
+            // async load on first miss, so the first frame kicks off the fetch.
+            // The URL is recomputed, never stored: providerIconDataUrl is
+            // memoized, and the spec stays small (no multi-KB data URLs).
+            paneIcons: tab.paneIcons.map((icon) => ({
+              ...icon,
+              ready: iconReady(providerIconDataUrl(icon.provider, PANE_TINT_COLORS[icon.tint])),
+            })),
             icons: tab.repoIcons.map((icon) => ({
               ...icon,
               ready: icon.url !== null && iconReady(icon.url),

src/deck/deck-selectors.ts

@@ -0,0 +1,36 @@
+// ============================================================================
+// PANE-ICON TINT COLORS — TabItem.tsx's icon tint classes projected to canvas
+// hex, derived from freshell's own UI tokens. KEEP IN SYNC: when an app token
+// changes, update the deck constant to match (same rule as tile-renderer.ts's
+// palette block). These live in their own leaf module because BOTH frame.ts
+// (which stamps per-icon readiness by computing the tinted data URL at
+// frame-build time) and tile-renderer.ts (which draws) need them — a shared
+// leaf module keeps the deck import graph free of runtime cycles.
+//
+//   deck constant     <- app source token                                  value
+//   STATUS_GREEN      <- text-success       (TabItem pane running tint)    hsl(142 71% 45%) = #21c45d
+//   STATUS_BLUE       <- text-blue-500      (TabItem pane busy tint)       #3b82f6
+//   STATUS_AMBER      <- --warning / text-warning                          hsl(38 92% 50%)  = #f59f0a
+//   STATUS_RED        <- --destructive light / text-destructive            hsl(0 72% 51%)   = #dc2828
+//   STATUS_MUTED      <- text-muted-foreground dark                        hsl(240 5% 65%)  = #a1a1aa
+//   STATUS_MUTED_DIM  <- text-muted-foreground/40 dark                     rgba(161,161,170,0.4)
+// ============================================================================
+
+import type { TilePaneTint } from './deck-selectors'
+
+export const STATUS_GREEN = '#21c45d'
+export const STATUS_BLUE = '#3b82f6'
+export const STATUS_AMBER = '#f59f0a'
+export const STATUS_RED = '#dc2828'
+export const STATUS_MUTED = '#a1a1aa'
+export const STATUS_MUTED_DIM = 'rgba(161,161,170,0.4)'
+
+/** TabItem.tsx pane-icon tint classes -> canvas colors (keyed by Task 8's TilePaneTint). */
+export const PANE_TINT_COLORS: Record<TilePaneTint, string> = {
+  blue: STATUS_BLUE,
+  green: STATUS_GREEN,
+  amber: STATUS_AMBER,
+  red: STATUS_RED,
+  muted: STATUS_MUTED,
+  mutedDim: STATUS_MUTED_DIM,
+}