dsh-git-ui 0.0.1

package/src/client/controller.ts

@@ -0,0 +1,158 @@
+/**
+ * Per-session Git view controller (React-free object layer).
+ * Lifecycle: `ensure()` on first mount, single-flight `refresh()`, polling at
+ * the interval the host snapshot carries (0 disables), `resync()` on
+ * connection reset, `dispose()` on slot teardown (clears the timer and
+ * rejects nothing — in-flight work settles into a withdrawn view).
+ */
+import type { GitSnapshot, GitSnapshotFailure, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+
+/** The observable view contract components consume (useSyncExternalStore shape). */
+export interface GitObservable<V> {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): V
+}
+
+export type GitView =
+  | { readonly state: 'no-cwd' }
+  | { readonly state: 'cold' }
+  | { readonly state: 'loading' }
+  | { readonly state: 'ready'; readonly snapshot: GitSnapshot }
+  | { readonly state: 'error'; readonly error: GitSnapshotFailure }
+
+/**
+ * RPC envelope returned by every mounted Remote method (see the api-gateway
+ * client's `invoke`): `ok` reflects the transport/gateway outcome, and the
+ * business return value of the host method rides inside `value`. For
+ * `gitInfo/snapshot` that business value is a `GitSnapshotResult` — so a
+ * successful call resolves to `{ ok: true, value: { ok: true, value:
+ * GitSnapshot } }`.
+ */
+export type GitRemoteEnvelope<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: { readonly code?: string; readonly message?: string; readonly details?: unknown } }
+
+/** Structural face of the mounted gitInfo Remote namespace. */
+export interface GitRemoteLike {
+  snapshot(request: GitSnapshotRequest): Promise<GitRemoteEnvelope<GitSnapshotResult>>
+}
+
+/** Failure codes that mean "no working directory to watch" — degrade to a
+ * low-frequency probe instead of a normal poll. */
+const TERMINAL_CODES: ReadonlySet<string> = new Set(['cwd-unavailable', 'session-not-found'])
+
+/** Fallback poll interval while no snapshot has been received yet (ms). */
+const DEFAULT_POLL_MS = 30_000
+
+/** Probe interval for the no-cwd state: the session may gain a working
+ * directory later (workspace selection, host-side session update) without a
+ * slot remount, so keep a cheap retry instead of parking forever. */
+const NO_CWD_POLL_MS = 60_000
+
+export class GitController implements GitObservable<GitView> {
+  private view: GitView = { state: 'cold' }
+  private readonly listeners = new Set<() => void>()
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private inflight: Promise<void> | undefined
+  private disposed = false
+  private pollMs: number = DEFAULT_POLL_MS
+
+  constructor(
+    private readonly remote: GitRemoteLike,
+    private readonly sessionId: string,
+  ) {}
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  getSnapshot(): GitView {
+    return this.view
+  }
+
+  /** Load once on first mount (cold) or after a terminal no-cwd state. */
+  ensure(): void {
+    if (this.view.state !== 'cold' && this.view.state !== 'no-cwd') return
+    void this.refresh()
+  }
+
+  /** Single-flight refresh; shares the in-flight request when busy. */
+  refresh(): Promise<void> {
+    if (this.inflight !== undefined) return this.inflight
+    if (this.disposed) return Promise.resolve()
+    this.setView({ state: 'loading' })
+    this.inflight = this.remote.snapshot({ sessionId: this.sessionId })
+      .then((result) => {
+        if (this.disposed) return
+        // RPC envelope: `result.ok` is the transport/gateway outcome; the
+        // business GitSnapshotResult (ok/value or ok/error) sits in
+        // `result.value`.
+        if (!result.ok) {
+          const detail = [result.error.code, result.error.message].filter(Boolean).join(': ')
+          this.setView({ state: 'error', error: { code: 'git-unavailable', detail: detail || 'rpc failure' } })
+          return
+        }
+        const inner = result.value
+        if (inner.ok) {
+          this.pollMs = inner.value.refreshIntervalMs
+          this.setView({ state: 'ready', snapshot: inner.value })
+        } else if (TERMINAL_CODES.has(inner.error.code)) {
+          // Terminal no-cwd view: the finally-branch schedules the low-
+          // frequency probe (schedulePoll), so no explicit stop here.
+          this.setView({ state: 'no-cwd' })
+        } else {
+          this.setView({ state: 'error', error: inner.error })
+        }
+      })
+      .catch(() => {
+        // Transport failure: surface an error view and keep polling so the
+        // state recovers automatically.
+        if (this.disposed) return
+        this.setView({ state: 'error', error: { code: 'git-unavailable', detail: 'transport failure' } })
+      })
+      .finally(() => {
+        this.inflight = undefined
+        if (!this.disposed) this.schedulePoll()
+      })
+    return this.inflight
+  }
+
+  /** Re-sync after a connection reset (reconnect). */
+  resync(): void {
+    // no-cwd is skipped: the low-frequency probe already covers recovery,
+    // and a reconnect alone does not create a working directory.
+    if (this.disposed || this.view.state === 'cold' || this.view.state === 'no-cwd') return
+    void this.refresh()
+  }
+
+  /** Tear down: stop the timer; in-flight work settles into a no-op. */
+  dispose(): void {
+    this.disposed = true
+    this.stopPolling()
+  }
+
+  private schedulePoll(): void {
+    this.stopPolling()
+    if (this.disposed || this.pollMs <= 0 || this.view.state === 'cold') return
+    // no-cwd keeps a low-frequency probe so a later cwd arrival recovers
+    // without a remount; every other state polls at the snapshot interval.
+    const interval = this.view.state === 'no-cwd' ? NO_CWD_POLL_MS : this.pollMs
+    this.timer = setTimeout(() => {
+      if (this.disposed || this.inflight !== undefined) return
+      void this.refresh()
+    }, interval)
+  }
+
+  private stopPolling(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+  }
+
+  private setView(view: GitView): void {
+    this.view = view
+    for (const listener of [...this.listeners]) listener()
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,149 @@
+/**
+ * Git status widget — client half entry.
+ *
+ * The bundle is a ModuleLoader closure: `factory(require)` returns the plugin
+ * shape `{ name, inject, apply }`; the framework activates it once the listed
+ * services exist.
+ *
+ * Service-access contract (verified against cordis 0.1.0-rc.x): the gitInfo
+ * namespace service is provided by OUR OWN `ctx.remote.$mount(gitInfoRemote)`
+ * inside apply, so the main fiber can never declare `remote.gitInfo` in its
+ * `inject` — cordis would wait for the service before running apply, and the
+ * service only appears once apply runs (deadlock). Conversely, accessing
+ * `ctx.remote.gitInfo` without the inject declaration throws cordis's
+ * "cannot get property ... without inject". The consumer therefore lives in a
+ * CHILD fiber created after the mount: its inject declares `remote.gitInfo`,
+ * and by the time it activates the service already exists — no wait, no
+ * access violation. (In-repo plugins like ui-message-feedback can inject
+ * their namespace directly because a separate assembly package mounts it; a
+ * standalone plugin mounts its own.)
+ */
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
+import { GitController, type GitView, type GitObservable, type GitRemoteLike } from './controller.ts'
+import { gitInfoRemote } from './remote.ts'
+import { GitPill, type GitInjected } from './GitPill.tsx'
+import { en, zh } from './locales.ts'
+
+/** Structural face of the browser plugin context (host-provided). */
+interface ClientContext {
+  get<T = unknown>(key: string): T | undefined
+  /** Subscribe to an application event (auto-cleaned on fiber dispose). */
+  on(event: string, listener: (...args: never[]) => void): (() => void) | void
+  /** Register a side effect with auto-cleanup on fiber dispose. */
+  effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+  /** Register a nested cordis plugin (fiber) under this context. */
+  plugin(definition: {
+    readonly name: string
+    readonly inject: readonly string[]
+    apply: (ctx: ClientContext) => void | Promise<void>
+  }): Promise<unknown>
+  /** The typed Client Remote mount + mounted namespaces. */
+  remote: {
+    $mount(contribution: TypertRemoteContribution): Promise<() => Promise<void>>
+    gitInfo: GitRemoteLike
+  }
+  /** The slot registry (ui-slots). */
+  slots: {
+    inject(slotName: string, provider: () => (() => void) | void): void
+    register(
+      options: {
+        readonly name: string
+        readonly id: string
+        readonly order?: number
+        readonly locale?: string
+        readonly inject: (sessionId: string) => GitInjected
+      },
+      component: unknown,
+    ): () => void
+  }
+  /** The locale service (ui-locale). */
+  locale: {
+    register(namespace: string, dictionaries: { readonly zh: Record<string, string>; readonly en: Record<string, string> }): void
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Required services: slot registry, Remote base (gateway client), and copy.
+ *
+ * `remote.gitInfo` is deliberately NOT listed here — see the module comment:
+ * the namespace is mounted by our own apply, so injecting it would deadlock.
+ * The child fiber that consumes it declares it instead (after the mount).
+ */
+export const inject = ['slots', 'remote', 'locale'] as const
+
+/** Plugin identity: the factory handoff returns this plus the exports above. */
+export const name = 'dsh-git-ui'
+
+/**
+ * Plugin body: register copy, mount the gitInfo Remote, then host the header
+ * utility in a child fiber that may legitimately access `remote.gitInfo`.
+ */
+export async function apply(ctx: ClientContext): Promise<void> {
+  ctx.effect(() => ctx.locale.register('git', { zh, en }), 'dsh-git-ui: dictionaries')
+
+  // Mount first — the namespace service only exists after this resolves.
+  await ctx.remote.$mount(gitInfoRemote)
+
+  const controllers = new Map<string, GitController>()
+  const faces = new Map<string, GitInjected>()
+
+  // Consumer fiber: `remote.gitInfo` is declared in ITS inject list, so the
+  // access inside the controller factory is legal; the service is already
+  // provided by the mount above, so activation does not wait (no deadlock).
+  const child = ctx.plugin({
+    name: 'dsh-git-ui:git',
+    inject: ['slots', 'remote.gitInfo'],
+    apply: (sub) => {
+      const controllerFor = (sessionId: string): GitController => {
+        let controller = controllers.get(sessionId)
+        if (controller === undefined) {
+          controller = new GitController(sub.remote.gitInfo, sessionId)
+          controllers.set(sessionId, controller)
+        }
+        return controller
+      }
+
+      sub.slots.inject('conversation.session.header.utilities', () => {
+        const dispose = sub.slots.register({
+          name: 'conversation.session.header.utilities',
+          id: 'git',
+          order: 10,
+          locale: 'git',
+          inject: (sessionId): GitInjected => {
+            // Per-session stable face: the slot runtime may re-invoke the
+            // inject factory on every render, and components depend on the
+            // `refresh` reference staying stable (a fresh arrow function per
+            // call would re-run mount effects and loop: refresh → view
+            // change → re-render → new refresh → refresh …). Cache the face
+            // so the same controller (and its bound refresh) is always
+            // handed out per session.
+            let face = faces.get(sessionId)
+            if (face === undefined) {
+              const controller = controllerFor(sessionId)
+              face = {
+                hooks: { git: controller as GitInjected['hooks']['git'] },
+                refresh: () => controller.refresh(),
+              }
+              faces.set(sessionId, face)
+            }
+            return face
+          },
+        }, GitPill)
+        return () => {
+          dispose()
+          for (const controller of controllers.values()) controller.dispose()
+          controllers.clear()
+          faces.clear()
+        }
+      })
+    },
+  })
+  await child
+
+  // A reconnect can only invalidate what was already read; a cold Session
+  // stays cold until something asks for it.
+  ctx.on('connection/reset', () => {
+    for (const controller of controllers.values()) controller.resync()
+  })
+}

package/src/client/locales.ts

@@ -0,0 +1,55 @@
+/** `git` namespace dictionaries (zh is the key-set source of truth). */
+
+export const zh = {
+  'pill.branch': '分支',
+  'pill.detached': '游离 HEAD',
+  'pill.noCommits': '无提交',
+  'pill.noRepo': '无 Git 仓库',
+  'pill.unavailable': 'Git 不可用',
+  'popup.title': 'Git 状态',
+  'popup.root': '仓库根目录',
+  'popup.staged': '已暂存',
+  'popup.modified': '已修改',
+  'popup.untracked': '未跟踪',
+  'popup.ahead': '领先',
+  'popup.behind': '落后',
+  'popup.recentCommits': '最近提交',
+  'popup.changes': '变更文件',
+  'popup.changesTruncated': '仅显示前 {count} 条',
+  'popup.refresh': '刷新',
+  'popup.checkedAt': '检查于 {time}',
+  'popup.empty': '工作区干净',
+  'popup.emptyCommits': '暂无提交',
+  'time.justNow': '刚刚',
+  'time.minutesAgo': '{n} 分钟前',
+  'time.hoursAgo': '{n} 小时前',
+  'time.daysAgo': '{n} 天前',
+} satisfies Record<string, string>
+
+export type GitKey = keyof typeof zh
+
+export const en: Record<GitKey, string> = {
+  'pill.branch': 'branch',
+  'pill.detached': 'detached HEAD',
+  'pill.noCommits': 'no commits',
+  'pill.noRepo': 'No Git repository',
+  'pill.unavailable': 'Git unavailable',
+  'popup.title': 'Git status',
+  'popup.root': 'Repository root',
+  'popup.staged': 'staged',
+  'popup.modified': 'modified',
+  'popup.untracked': 'untracked',
+  'popup.ahead': 'ahead',
+  'popup.behind': 'behind',
+  'popup.recentCommits': 'Recent commits',
+  'popup.changes': 'Changed files',
+  'popup.changesTruncated': 'Showing first {count} entries',
+  'popup.refresh': 'Refresh',
+  'popup.checkedAt': 'Checked at {time}',
+  'popup.empty': 'Working tree clean',
+  'popup.emptyCommits': 'No commits yet',
+  'time.justNow': 'just now',
+  'time.minutesAgo': '{n}m ago',
+  'time.hoursAgo': '{n}h ago',
+  'time.daysAgo': '{n}d ago',
+}

package/src/client/remote.ts

@@ -0,0 +1,97 @@
+/**
+ * Hand-written Typert Remote contribution for the gitInfo namespace.
+ *
+ * The host side exposes `gitInfo/snapshot` through SRC discovery (decorator
+ * metadata); the browser side must mount an equivalent strict contribution
+ * (requireStrictDescriptor enforces zod codecs), so the schemas here mirror
+ * `src/host/types.ts` by hand. `tests/client/remote.spec.ts` keeps the two in
+ * sync by parsing host-typed samples through these schemas.
+ */
+import { z } from 'zod'
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
+
+export const gitCommitSchema = z.object({
+  hash: z.string(),
+  shortHash: z.string(),
+  subject: z.string(),
+  author: z.string(),
+  dateIso: z.string(),
+})
+
+export const gitChangeSchema = z.object({
+  path: z.string(),
+  status: z.enum(['added', 'modified', 'deleted', 'renamed', 'untracked', 'conflicted', 'typechange']),
+  staged: z.boolean(),
+})
+
+export const gitSnapshotSchema = z.object({
+  root: z.string(),
+  branch: z.string().nullable(),
+  head: z.string().nullable(),
+  unborn: z.boolean(),
+  dirty: z.boolean(),
+  staged: z.number(),
+  modified: z.number(),
+  untracked: z.number(),
+  ahead: z.number(),
+  behind: z.number(),
+  lastCommit: gitCommitSchema.nullable(),
+  recentCommits: z.array(gitCommitSchema),
+  changes: z.array(gitChangeSchema),
+  truncated: z.boolean(),
+  refreshIntervalMs: z.number(),
+  checkedAt: z.number(),
+})
+
+export const gitSnapshotFailureSchema = z.discriminatedUnion('code', [
+  z.object({ code: z.literal('session-not-found'), sessionId: z.string() }),
+  z.object({ code: z.literal('cwd-unavailable'), sessionId: z.string() }),
+  z.object({ code: z.literal('path-not-found'), path: z.string() }),
+  z.object({ code: z.literal('git-unavailable'), detail: z.string() }),
+  z.object({ code: z.literal('timeout') }),
+  z.object({ code: z.literal('not-a-git-repo') }),
+])
+
+export const gitSnapshotResultSchema = z.discriminatedUnion('ok', [
+  z.object({ ok: z.literal(true), value: gitSnapshotSchema }),
+  z.object({ ok: z.literal(false), error: gitSnapshotFailureSchema }),
+])
+
+export const gitSnapshotRequestSchema = z.object({
+  sessionId: z.string(),
+})
+
+/** The contribution mounted into `ctx.remote` by the client plugin body. */
+export const gitInfoRemote: TypertRemoteContribution = {
+  package: 'dsh-git-ui',
+  descriptors: [
+    {
+      id: 'dsh-git-ui#gitInfo/snapshot',
+      service: 'gitInfo',
+      namespace: 'gitInfo',
+      method: 'snapshot',
+      invocation: { kind: 'direct' },
+      // Mirrors the host SRC descriptor: the trailing `signal` parameter is
+      // the cancellation slot, so an aborted call also stops the host-side
+      // git runs instead of letting them finish.
+      cancellation: { parameter: 'signal' },
+      parameters: [
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'dsh-git-ui/types#GitSnapshotRequest',
+            schema: gitSnapshotRequestSchema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'dsh-git-ui/types#GitSnapshotResult',
+        schema: gitSnapshotResultSchema,
+      },
+    },
+  ],
+}

package/src/client/styles.ts

@@ -0,0 +1,229 @@
+/**
+ * Style constants for the git widget.
+ *
+ * Colors resolve exclusively through the host theme's `--dsw-alias-*` design
+ * tokens (ui-theme design-platform.css), so the widget follows the active
+ * light/dark theme automatically — never hard-coded surfaces. Layout mirrors
+ * the official primitives: the pill is a 24px `Pill`-style chip, the popup a
+ * `Menu`-surface card (border-l1, radius 12, shadow-lv3).
+ *
+ * The popup is a fixed-position card portaled to document.body (see
+ * GitPill.tsx) — it must never participate in header layout, otherwise it
+ * grows the header and distorts it.
+ */
+import type { CSSProperties } from 'react'
+
+/** Pill: compact branch chip, right-aligned in the session header. */
+export const pill: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 6,
+  height: 24,
+  padding: '0 8px',
+  border: 0,
+  borderRadius: 12,
+  font: 'inherit',
+  fontSize: 12,
+  lineHeight: '18px',
+  whiteSpace: 'nowrap',
+  cursor: 'pointer',
+  color: 'var(--dsw-alias-label-secondary)',
+  background: 'var(--dsw-alias-bg-layer-2)',
+}
+
+/** Dimmed pill for degraded states (no repo / unavailable). */
+export const pillDimmed: CSSProperties = {
+  ...pill,
+  opacity: 0.55,
+  cursor: 'default',
+}
+
+/** Status dot: green when clean, warn when the tree is dirty. */
+export const dot: CSSProperties = {
+  flex: 'none',
+  width: 8,
+  height: 8,
+  borderRadius: 999,
+  background: 'var(--dsw-alias-state-success-primary)',
+}
+
+export const dotDirty: CSSProperties = {
+  ...dot,
+  background: 'var(--dsw-alias-state-warn-primary)',
+}
+
+/** Popup panel: fixed-position card (top/left come from the anchor math). */
+export const popup: CSSProperties = {
+  position: 'fixed',
+  zIndex: 1100,
+  boxSizing: 'border-box',
+  width: 340,
+  maxHeight: 420,
+  overflowY: 'auto',
+  padding: '10px 12px',
+  fontSize: 12,
+  lineHeight: '18px',
+  background: 'var(--dsw-alias-bg-layer-3)',
+  color: 'var(--dsw-alias-label-primary)',
+  border: '1px solid var(--dsw-alias-border-l1)',
+  borderRadius: 12,
+  boxShadow: 'var(--dsw-shadow-lv3)',
+}
+
+export const popupTitle: CSSProperties = {
+  margin: 0,
+  fontSize: 13,
+  fontWeight: 600,
+  marginBottom: 6,
+}
+
+export const rootLine: CSSProperties = {
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+  color: 'var(--dsw-alias-label-tertiary)',
+  marginBottom: 8,
+}
+
+export const countGrid: CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'repeat(5, 1fr)',
+  gap: 6,
+  marginBottom: 8,
+}
+
+export const countCell: CSSProperties = {
+  textAlign: 'center',
+  padding: '4px 2px',
+  borderRadius: 8,
+  background: 'var(--dsw-alias-bg-layer-2)',
+}
+
+export const countValue: CSSProperties = {
+  fontWeight: 600,
+  fontSize: 14,
+  color: 'var(--dsw-alias-label-primary)',
+}
+
+export const countLabel: CSSProperties = {
+  fontSize: 11,
+  color: 'var(--dsw-alias-label-tertiary)',
+}
+
+export const sectionTitle: CSSProperties = {
+  margin: '8px 0 4px',
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--dsw-alias-label-secondary)',
+  textTransform: 'uppercase',
+  letterSpacing: 0.4,
+}
+
+export const commitRow: CSSProperties = {
+  display: 'flex',
+  gap: 6,
+  alignItems: 'baseline',
+  padding: '2px 0',
+}
+
+export const commitHash: CSSProperties = {
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 11,
+  color: 'var(--dsw-alias-label-secondary)',
+}
+
+export const commitSubject: CSSProperties = {
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+  flex: 1,
+  color: 'var(--dsw-alias-label-primary)',
+}
+
+export const commitMeta: CSSProperties = {
+  fontSize: 11,
+  color: 'var(--dsw-alias-label-tertiary)',
+  whiteSpace: 'nowrap',
+}
+
+export const changeRow: CSSProperties = {
+  display: 'flex',
+  gap: 6,
+  alignItems: 'center',
+  padding: '1px 0',
+  borderRadius: 6,
+}
+
+export const changeChip: CSSProperties = {
+  width: 20,
+  textAlign: 'center',
+  borderRadius: 4,
+  fontSize: 11,
+  fontWeight: 600,
+  flexShrink: 0,
+  color: '#fff',
+}
+
+export const changePath: CSSProperties = {
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+  flex: 1,
+  color: 'var(--dsw-alias-label-primary)',
+}
+
+export const footerRow: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+  marginTop: 10,
+}
+
+export const checkedAt: CSSProperties = {
+  fontSize: 11,
+  color: 'var(--dsw-alias-label-tertiary)',
+}
+
+/** Text button inside the popup (refresh). */
+export const refreshButton: CSSProperties = {
+  border: 0,
+  background: 'transparent',
+  padding: '2px 6px',
+  fontSize: 12,
+  cursor: 'pointer',
+  color: 'var(--dsw-alias-label-secondary)',
+  borderRadius: 6,
+  font: 'inherit',
+}
+
+export const emptyNote: CSSProperties = {
+  color: 'var(--dsw-alias-label-tertiary)',
+  padding: '4px 0',
+}
+
+/**
+ * Global styles for pseudo-class interactions (inline styles can't express
+ * :hover/:focus-visible). Injected once per document under a plugin-scoped id.
+ */
+const GLOBAL_CSS_ID = 'dsh-git-ui/styles'
+
+const globalCss = [
+  '.dsh-git-ui__pill:hover { background: var(--dsw-alias-interactive-bg-hover); }',
+  '.dsh-git-ui__pill:focus-visible { outline: 2px solid var(--dsw-alias-state-business-primary); outline-offset: -2px; }',
+  '.dsh-git-ui__row { border-radius: 6px; }',
+  '.dsh-git-ui__row:hover { background: var(--dsw-alias-interactive-bg-hover); }',
+  '.dsh-git-ui__refresh:hover { color: var(--dsw-alias-state-business-primary); }',
+  '.dsh-git-ui__refresh:focus-visible { outline: 2px solid var(--dsw-alias-state-business-primary); outline-offset: 2px; }',
+].join('\n')
+
+/** Ensure the global interaction styles exist (idempotent; browser only). */
+export function ensureGlobalCss(): void {
+  if (typeof document === 'undefined') return
+  if (document.getElementById(GLOBAL_CSS_ID) !== null) return
+  const tag = document.createElement('style')
+  tag.id = GLOBAL_CSS_ID
+  tag.dataset.plugin = 'dsh-git-ui'
+  tag.textContent = globalCss
+  document.head.appendChild(tag)
+}