dsh-git-ui 0.0.2 → 0.1.0

package/src/client/GitPill.tsx

@@ -15,10 +15,17 @@ import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import type { JSX } from 'react'
 import { completedTurnCount, type TurnSignalSnapshot } from './turn-signal.ts'
-import type { GitObservable, GitView } from './controller.ts'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { GitObservable, GitQueryOutcome, GitView } from './controller.ts'
 import { GitCenter } from './GitCenter.tsx'
-import type { GitAction, GitActionResult } from '../host/types.ts'
+import { fileIconForPath, FolderIcon, AlertIcon, CloseIcon, RollbackIcon, StageIcon, UnstageIcon } from './icons.tsx'
+import type { GitAction, GitActionResult, GitBranch, GitOperationErrorCode, GitQueryRequest } from '../host/types.ts'
 import type { GitKey } from './locales.ts'
+import { SelectMenu } from './select-menu.tsx'
+import { splitChangePath } from './file-tree.ts'
+import { shouldClosePopup } from './popup-close.ts'
+import { diffBaseOf } from './changes-diff.ts'
+import { errorText, errorAction } from './error-text.ts'
 import * as css from './styles.ts'
 
 // Inject the plugin's interaction styles once (idempotent, browser-only).
@@ -35,6 +42,8 @@ export interface GitInjected {
   refresh: () => Promise<void>
   /** Execute one management action (host returns a fresh snapshot). */
   run: (action: GitAction) => Promise<GitActionResult>
+  /** Run one read-only query (history / diff / show / branches). */
+  query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
 }
 
 /** Selector hook shape the slot runtime binds from `hooks.git`. */
@@ -57,16 +66,7 @@ export interface GitPillProps extends GitInjected {
   readonly t: (key: GitKey) => string
 }
 
-/** Status chip colors for the changed-file list. */
-const CHIP_COLORS: Record<string, string> = {
-  added: '#2e7d32',
-  modified: '#b26a00',
-  deleted: '#c62828',
-  renamed: '#1565c0',
-  untracked: '#6a6a6a',
-  conflicted: '#d32f2f',
-  typechange: '#7b1fa2',
-}
+/** 状态字符映射（配色见 styles.chipStyles，全语义 token）。 */
 
 const CHIP_LETTERS: Record<string, string> = {
   added: 'A', modified: 'M', deleted: 'D', renamed: 'R',
@@ -102,16 +102,14 @@ function timeAgo(iso: string, now: number, t: (key: GitKey) => string): string {
   return fill('time.daysAgo', Math.floor(seconds / 86_400))
 }
 
-/** The pill label for a ready snapshot. */
-function pillLabel(view: GitView & { state: 'ready' }, t: (key: GitKey) => string): string {
+/** The pill label parts: 分支名（可 ellipsis 收缩）+ 徽标（不截断保留）。 */
+function pillParts(view: GitView & { state: 'ready' }, t: (key: GitKey) => string): { branch: string; badges: string[] } {
   const s = view.snapshot
   const branch = s.branch === null
     ? `(${t('pill.detached')}) · ${s.head ?? ''}`
-    : s.branch
-  const base = s.unborn ? `${branch} · ${t('pill.noCommits')}` : branch
-  const badge = dirtyBadge(view)
-  const ahead = aheadBehind(view)
-  return [base, badge, ahead].filter(Boolean).join(' · ')
+    : (s.unborn ? `${s.branch} · ${t('pill.noCommits')}` : s.branch)
+  const badges = [dirtyBadge(view), aheadBehind(view)].filter(Boolean)
+  return { branch, badges }
 }
 
 /** Dimmed pill for degraded states. */
@@ -124,40 +122,195 @@ function DegradedPill({ label, title, t }: { label: string; title?: string; t: (
   )
 }
 
-/** Popup body (rendered inside the portaled card): root, counts, commits, changes, refresh. */
+/**
+ * Popup body (rendered inside the portaled card)。
+ * 分支管理（切换/新建）已并入本组件：头部内联切换 + 新建行上提；
+ * 变更行带 hover 内联操作（暂存/取消/丢弃两步）。
+ */
 function GitPopupBody({
-  view, refresh, openCenter, t,
+  view, refresh, openCenter, onOpenDiff, run, query, t,
 }: {
   view: GitView & { state: 'ready' }
   refresh: () => Promise<void>
   openCenter: () => void
+  /** 变更文件点击：打开 Git 中心并定位该文件的对照视图。 */
+  onOpenDiff: (path: string, base: 'worktree' | 'staged') => void
+  run: (action: GitAction) => Promise<GitActionResult>
+  query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
   t: (key: GitKey) => string
 }): JSX.Element {
   const now = Date.now()
   const s = view.snapshot
+  const branchLabel = s.branch === null ? `(${t('pill.detached')})` : s.branch
+
+  /** 分支管理状态（自原 BranchQuickManage 并入）：切换（头部内联）+ 新建（上提）。 */
+  const [branchData, setBranchData] = useState<{ current: string | null; local: readonly GitBranch[] } | null>(null)
+  const [busy, setBusy] = useState(false)
+  const [newName, setNewName] = useState('')
+  const [note, setNote] = useState<{ text: string; detail?: string; action?: 'open-center' } | null>(null)
+  // 变更行丢弃两步确认：armed 记录待确认的路径，3s 自动解除。
+  const [armed, setArmed] = useState<string | null>(null)
+
+  /** 操作失败 → 友好告警：业务错误用 i18n 文案 + 行动按钮，原始信息留 detail。 */
+  const setErrorNote = (err: { code: GitOperationErrorCode; message?: string }): void => {
+    setNote({
+      text: errorText(err.code, err.message, t),
+      ...(err.message === undefined ? {} : { detail: err.message }),
+      ...(errorAction(err.code) === null ? {} : { action: errorAction(err.code) ?? undefined }),
+    })
+  }
+
+  const reload = async (): Promise<void> => {
+    const outcome = await query({ kind: 'branches' })
+    if (outcome.ok && outcome.value.kind === 'branches') {
+      setBranchData({ current: outcome.value.current, local: outcome.value.local })
+    }
+  }
+
+  useEffect(() => {
+    void reload()
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only
+  }, [])
+
+  useEffect(() => {
+    if (armed === null) return
+    const timer = setTimeout(() => setArmed(null), 3000)
+    return () => clearTimeout(timer)
+  }, [armed])
+
+  const switchTo = async (name: string): Promise<void> => {
+    if (busy || name === '') return
+    setBusy(true)
+    setNote(null)
+    const result = await run({ kind: 'branch-checkout', name })
+    setBusy(false)
+    if (!result.ok) setErrorNote(result.error)
+    await reload()
+  }
+
+  const createAndSwitch = async (): Promise<void> => {
+    const name = newName.trim()
+    if (name === '' || busy) return
+    setBusy(true)
+    setNote(null)
+    const created = await run({ kind: 'branch-create', name })
+    if (created.ok) {
+      const switched = await run({ kind: 'branch-checkout', name })
+      if (!switched.ok) setErrorNote(switched.error)
+      setNewName('')
+    } else {
+      setErrorNote(created.error)
+    }
+    setBusy(false)
+    await reload()
+  }
+
+  /** 执行一条变更行操作（暂存/取消/丢弃），失败以 note 显示。 */
+  const runChange = async (action: GitAction, path: string): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    setNote(null)
+    const result = await run(action)
+    setBusy(false)
+    if (!result.ok) setErrorNote(result.error)
+  }
+
+  const stage = (path: string): void => void runChange({ kind: 'stage', paths: [path] }, path)
+  const unstage = (path: string): void => void runChange({ kind: 'unstage', paths: [path] }, path)
+  const discard = (path: string): void => {
+    if (busy) return
+    if (armed !== path) { setArmed(path); return }
+    setArmed(null)
+    void runChange({ kind: 'discard', paths: [path] }, path)
+  }
+
   return (
     <>
-      <h4 style={css.popupTitle}>{t('popup.title')}</h4>
-      <div style={css.rootLine} title={s.root}>{s.root}</div>
-      <div style={css.countGrid}>
+      <header style={css.popupHeader}>
+        <div style={css.popupHeaderMain}>
+          <span style={s.dirty ? css.dotDirty : css.dot} aria-hidden="true" />
+          {branchData === null ? (
+            <span style={css.popupHeaderBranch}>{branchLabel}</span>
+          ) : (
+            <SelectMenu
+              value={branchData.current ?? ''}
+              options={[
+                // 游离 HEAD：注入伪选项让头部显示游离标签，仍可下拉切换本地分支。
+                ...(branchData.current === null ? [{ value: '', label: branchLabel }] : []),
+                ...branchData.local.map((b) => ({ value: b.name, label: b.name })),
+              ]}
+              onSelect={(name) => void switchTo(name)}
+              ariaLabel={t('center.currentBranch')}
+              buttonStyle={css.popupBranchMenu}
+            />
+          )}
+          {s.unborn && <span style={css.popupBadge}>{t('pill.noCommits')}</span>}
+          {s.dirty && <span style={css.popupBadge}>{dirtyBadge(view)}</span>}
+          {(s.ahead > 0 || s.behind > 0) && <span style={css.popupBadge}>{aheadBehind(view)}</span>}
+        </div>
+        <div style={css.popupHeaderRoot} title={s.root}>
+          <FolderIcon />
+          <span style={css.popupHeaderRootText}>{s.root}</span>
+        </div>
+      </header>
+      <div style={css.popupStatusBar}>
         {([
           ['popup.staged', s.staged], ['popup.modified', s.modified], ['popup.untracked', s.untracked],
-          ['popup.ahead', s.ahead], ['popup.behind', s.behind],
         ] as const).map(([key, value]) => (
-          <div key={key} style={css.countCell}>
-            <div style={css.countValue}>{value}</div>
-            <div style={css.countLabel}>{t(key)}</div>
-          </div>
+          <span key={key} style={css.popupStatItem}>
+            <span style={css.popupStatValue}>{value}</span>
+            <span style={css.popupStatLabel}>{t(key)}</span>
+          </span>
         ))}
       </div>
+      <div style={css.popupBranchOps}>
+        <input
+          className="dsh-git-ui__branch-input"
+          style={css.branchNameInput}
+          placeholder={t('center.branchName')}
+          value={newName}
+          disabled={busy}
+          onChange={(e) => setNewName(e.target.value)}
+          onKeyDown={(e) => { if (e.key === 'Enter') void createAndSwitch() }}
+        />
+        <Button size="sm" disabled={busy || newName.trim() === ''} onClick={() => void createAndSwitch()}>
+          {t('center.createAndSwitch')}
+        </Button>
+      </div>
+      {note !== null && (
+        <div style={css.popupNote} role="alert">
+          <span style={css.popupNoteIcon} aria-hidden="true"><AlertIcon /></span>
+          <span style={css.popupNoteText} title={note.detail}>{note.text}</span>
+          {note.action === 'open-center' && (
+            <button type="button" className="dsh-git-ui__change-link" style={css.popupNoteAction} onClick={openCenter}>
+              {t('error.handleChanges')}
+            </button>
+          )}
+          <button
+            type="button"
+            className="dsh-git-ui__icon-btn"
+            style={css.popupNoteClose}
+            title={t('center.close')}
+            aria-label={t('center.close')}
+            onClick={() => setNote(null)}
+          >
+            <CloseIcon />
+          </button>
+        </div>
+      )}
       <div style={css.sectionTitle}>{t('popup.recentCommits')}</div>
       {s.recentCommits.length === 0
         ? <div style={css.emptyNote}>{t('popup.emptyCommits')}</div>
-        : s.recentCommits.map((commit) => (
-          <div key={commit.hash} style={css.commitRow}>
-            <span style={css.commitHash}>{commit.shortHash}</span>
-            <span style={css.commitSubject} title={commit.subject}>{commit.subject}</span>
-            <span style={css.commitMeta}>{commit.author} · {timeAgo(commit.dateIso, now, t)}</span>
+        : s.recentCommits.slice(0, 3).map((commit) => (
+          <div key={commit.hash} className="dsh-git-ui__row" style={css.commitRow}>
+            <div style={css.commitSubjectPop} title={commit.subject}>{commit.subject}</div>
+            <div style={css.commitMetaLine}>
+              <span style={css.commitHash}>{commit.shortHash}</span>
+              <span style={css.commitDot}>·</span>
+              <span style={css.commitMeta}>{commit.author}</span>
+              <span style={css.commitDot}>·</span>
+              <span style={css.commitMeta}>{timeAgo(commit.dateIso, now, t)}</span>
+            </div>
           </div>
         ))}
       <div style={css.sectionTitle}>{t('popup.changes')}</div>
@@ -165,17 +318,75 @@ function GitPopupBody({
         ? <div style={css.emptyNote}>{t('popup.empty')}</div>
         : (
           <>
-            {s.changes.map((change) => (
-              <div key={change.path} style={css.changeRow}>
-                <span
-                  style={{ ...css.changeChip, background: CHIP_COLORS[change.status] ?? '#888' }}
-                  title={change.status}
-                >
-                  {CHIP_LETTERS[change.status] ?? '•'}
-                </span>
-                <span style={css.changePath} title={change.path}>{change.path}</span>
-              </div>
-            ))}
+            {s.changes.map((change) => {
+              const { name, dir, isDir } = splitChangePath(change.path, change.isDirectory)
+              const untracked = change.status === 'untracked'
+              return (
+                <div key={change.path} className="dsh-git-ui__row" style={css.changeRow}>
+                  <span
+                    style={{ ...css.changeChip, ...(css.chipStyles[change.status] ?? css.chipStyles.untracked) }}
+                    title={change.status}
+                  >
+                    {CHIP_LETTERS[change.status] ?? '•'}
+                  </span>
+                  <span style={css.rowFileIcon} aria-hidden="true">
+                    {isDir ? <FolderIcon /> : fileIconForPath(change.path)}
+                  </span>
+                  {isDir ? (
+                    // 目录条目：点击打开 Git 中心变更页（目录无 diff 语义，展开后选具体文件）。
+                    <button
+                      type="button"
+                      className="dsh-git-ui__change-link"
+                      style={css.changeNamePopBtn}
+                      title={change.path}
+                      aria-label={`${name} — ${t('center.open')}`}
+                      onClick={openCenter}
+                    >
+                      {name}
+                    </button>
+                  ) : (
+                    // 文件条目：点击打开 Git 中心并直接展示该文件对照。
+                    <button
+                      type="button"
+                      className="dsh-git-ui__change-link"
+                      style={css.changeNamePopBtn}
+                      title={change.path}
+                      aria-label={`${name} — ${t('changes.actionDiff')}`}
+                      onClick={() => onOpenDiff(change.path, diffBaseOf(change))}
+                    >
+                      {name}
+                    </button>
+                  )}
+                  {dir !== '' ? <span style={css.changeDirPop}>{dir}</span> : <span style={{ flex: '1 1 0%', minWidth: 0 }} />}
+                  <span className="dsh-git-ui__row-actions" style={css.rowActions}>
+                    {change.staged
+                      ? (
+                        <button type="button" className="dsh-git-ui__icon-btn" style={css.rowIconButton} title={t('center.unstage')} aria-label={t('center.unstage')} disabled={busy} onClick={() => unstage(change.path)}>
+                          <UnstageIcon />
+                        </button>
+                      )
+                      : (
+                        <button type="button" className="dsh-git-ui__icon-btn" style={css.rowIconButton} title={t('center.stage')} aria-label={t('center.stage')} disabled={busy} onClick={() => stage(change.path)}>
+                          <StageIcon />
+                        </button>
+                      )}
+                    {!untracked && (
+                      <button
+                        type="button"
+                        className="dsh-git-ui__icon-btn"
+                        style={armed === change.path ? { ...css.rowIconButton, color: 'var(--dsw-alias-state-error-primary)' } : css.rowIconButton}
+                        title={armed === change.path ? t('center.confirmDiscard') : t('center.discard')}
+                        aria-label={armed === change.path ? t('center.confirmDiscard') : t('center.discard')}
+                        disabled={busy}
+                        onClick={() => discard(change.path)}
+                      >
+                        <RollbackIcon />
+                      </button>
+                    )}
+                  </span>
+                </div>
+              )
+            })}
             {s.truncated && (
               <div style={css.emptyNote}>{t('popup.changesTruncated').replace('{count}', String(s.changes.length))}</div>
             )}
@@ -183,11 +394,11 @@ function GitPopupBody({
         )}
       <div style={css.footerRow}>
         <span style={css.checkedAt}>{t('popup.checkedAt').replace('{time}', new Date(s.checkedAt).toLocaleTimeString())}</span>
-        <span style={{ display: 'inline-flex', gap: 4, alignItems: 'center' }}>
-          <button type="button" className="dsh-git-ui__refresh" style={css.refreshButton} onClick={openCenter}>
+        <span style={css.footerActions}>
+          <PopRefresher refresh={refresh} t={t} />
+          <button type="button" className="dsh-git-ui__footer-primary" style={{ ...css.refreshButton, ...css.footerPrimary, padding: '4px 10px' }} onClick={openCenter}>
             {t('center.open')}
           </button>
-          <PopRefresher refresh={refresh} t={t} />
         </span>
       </div>
     </>
@@ -220,7 +431,7 @@ const VIEW_GUTTER = 8
  * The header utility entry: a branch pill that opens a portaled detail popup
  * and the Git center management panel.
  */
-export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps): JSX.Element | null {
+export function GitPill({ useGit, useSession, refresh, run, query, t }: GitPillProps): JSX.Element | null {
   // The selector hook requires a selector function (with-selector calls it
   // unconditionally); identity selection reads the whole view snapshot.
   const view = useGit((view) => view)
@@ -251,6 +462,16 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
   const [open, setOpen] = useState(false)
   const [centerOpen, setCenterOpen] = useState(false)
   const [pos, setPos] = useState<{ top: number; left: number } | null>(null)
+  /** 从 pill 变更行点击「打开 Git 中心并定位该文件 diff」的请求。 */
+  const [centerRequest, setCenterRequest] = useState<{ path: string; base: 'worktree' | 'staged' } | null>(null)
+
+  /** 打开 Git 中心并直接定位到该文件的对照视图（关 popup、切 changes 标签、查询 diff）。 */
+  const openDiffInCenter = (path: string, base: 'worktree' | 'staged'): void => {
+    setCenterRequest({ path, base })
+    setOpen(false)
+    setPos(null)
+    setCenterOpen(true)
+  }
 
   useEffect(() => {
     // First mount only: kick the controller once (single-flight; a cold
@@ -302,10 +523,7 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
     if (!open) return
     const close = (): void => { setOpen(false); setPos(null) }
     const onDown = (e: MouseEvent): void => {
-      const target = e.target as Node
-      if (wrapRef.current?.contains(target) ?? false) return
-      if (popRef.current?.contains(target) ?? false) return
-      close()
+      if (shouldClosePopup(e.target, wrapRef.current, popRef.current)) close()
     }
     const onKey = (e: KeyboardEvent): void => { if (e.key === 'Escape') close() }
     document.addEventListener('mousedown', onDown)
@@ -335,6 +553,7 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
   }
 
   const dirty = display.snapshot.dirty
+  const parts = pillParts(display, t)
   return (
     <span ref={wrapRef} style={{ display: 'inline-flex' }}>
       <button
@@ -344,10 +563,11 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
         onClick={() => setOpen(!open)}
         aria-haspopup="dialog"
         aria-expanded={open}
-        title={`${display.snapshot.root}\n${pillLabel(display, t)}`}
+        title={`${display.snapshot.root}\n${[parts.branch, ...parts.badges].filter(Boolean).join(' · ')}`}
       >
         <span style={dirty ? css.dotDirty : css.dot} aria-hidden="true" />
-        <span>{pillLabel(display, t)}</span>
+        <span style={css.pillBranch}>{parts.branch}</span>
+        {parts.badges.length > 0 && <span style={css.pillBadges}>{parts.badges.join(' · ')}</span>}
       </button>
       {open && pos !== null && createPortal(
         <div
@@ -361,6 +581,9 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
             view={display}
             refresh={refresh}
             openCenter={() => { setOpen(false); setPos(null); setCenterOpen(true) }}
+            onOpenDiff={openDiffInCenter}
+            run={run}
+            query={query}
             t={t}
           />
         </div>,
@@ -371,7 +594,9 @@ export function GitPill({ useGit, useSession, refresh, run, t }: GitPillProps):
         onClose={() => setCenterOpen(false)}
         snapshot={display.snapshot}
         run={run}
+        query={query}
         t={t}
+        openRequest={centerRequest}
       />
     </span>
   )

package/src/client/changes-diff.ts

@@ -0,0 +1,63 @@
+/**
+ * Changes 差异视图的选择态协调（纯函数，可单元测试）。
+ *
+ * 快照变化后（轮询 / 管理操作成功），正在对照的文件可能消失，也可能在
+ * 已暂存/未暂存两侧之间迁移（混合态拆分出的双条目）。
+ * `reconcileDiffSelection` 给出视图应维持的选择态：
+ *   - null           → 文件已不在变更清单，关闭对照；
+ *   - 基线不变的选择 → 保持当前基线（MM 双条目优先复用原基线）；
+ *   - 基线变更的选择 → 按文件当前所属侧重取。
+ * 无论基线是否变化，调用方都应重取差异内容——操作可能刚改变了同一文件。
+ */
+
+/** 正在对照查看的文件（base 由打开行时的暂存态决定）。 */
+export interface DiffSelection {
+  readonly path: string
+  readonly base: 'worktree' | 'staged'
+}
+
+/** 变更行结构面（与宿主 GitChange 同构）。 */
+export interface ChangeLike {
+  readonly path: string
+  readonly status: string
+  readonly staged: boolean
+}
+
+/** 变更行对应的差异基线：未跟踪与未暂存侧 → 工作区；已暂存侧 → 暂存区。 */
+export function diffBaseOf(change: ChangeLike): 'worktree' | 'staged' {
+  if (change.status === 'untracked') return 'worktree'
+  return change.staged ? 'staged' : 'worktree'
+}
+
+/** 按新的变更清单协调当前选择态；语义见模块注释。 */
+export function reconcileDiffSelection(
+  selection: DiffSelection,
+  changes: readonly ChangeLike[],
+): DiffSelection | null {
+  const entries = changes.filter((c) => c.path === selection.path)
+  if (entries.length === 0) return null
+  const sameBase = entries.find((c) => diffBaseOf(c) === selection.base)
+  if (sameBase !== undefined) return { path: selection.path, base: selection.base }
+  return { path: selection.path, base: diffBaseOf(entries[0]!) }
+}
+
+/**
+ * 上一个/下一个更改的循环导航：`entries` 为导航序列（分组顺序），
+ * `current` 为空时定位第一条；当前项不在序列中时按首项计；
+ * `delta` 取 ±1（模长度循环，首尾相接）。空序列返回 null。
+ */
+export function stepDiffSelection(
+  entries: readonly ChangeLike[],
+  current: DiffSelection | null,
+  delta: number,
+): DiffSelection | null {
+  if (entries.length === 0) return null
+  if (current === null) {
+    const first = entries[0]!
+    return { path: first.path, base: diffBaseOf(first) }
+  }
+  const found = entries.findIndex((c) => c.path === current.path && diffBaseOf(c) === current.base)
+  const index = found === -1 ? 0 : found
+  const next = entries[(index + delta + entries.length) % entries.length]!
+  return { path: next.path, base: diffBaseOf(next) }
+}

package/src/client/controller.ts

@@ -5,7 +5,7 @@
  * connection reset, `dispose()` on slot teardown (clears the timer and
  * rejects nothing — in-flight work settles into a withdrawn view).
  */
-import type { GitActionResult, GitActionRequest, GitSnapshot, GitSnapshotFailure, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+import type { GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshot, GitSnapshotFailure, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
 
 /** The observable view contract components consume (useSyncExternalStore shape). */
 export interface GitObservable<V> {
@@ -36,8 +36,14 @@ export type GitRemoteEnvelope<T> =
 export interface GitRemoteLike {
   snapshot(request: GitSnapshotRequest): Promise<GitRemoteEnvelope<GitSnapshotResult>>
   run(request: GitActionRequest): Promise<GitRemoteEnvelope<GitActionResult>>
+  query(request: GitQueryRequest): Promise<GitRemoteEnvelope<GitQueryResponse>>
 }
 
+/** Simplified query outcome for the UI (envelope + business errors unwrapped). */
+export type GitQueryOutcome =
+  | { readonly ok: true; readonly value: Extract<GitQueryResponse, { ok: true }>['value'] }
+  | { readonly ok: false; readonly message: string }
+
 /** 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'])
@@ -173,6 +179,35 @@ export class GitController implements GitObservable<GitView> {
     return promise
   }
 
+  /**
+   * Run one read-only query (history / diff / show / branches). The view is
+   * untouched — the result goes straight back to the caller. Queues behind
+   * any in-flight refresh/run like everything else (single-flight).
+   */
+  query(query: GitQueryRequest['query']): Promise<GitQueryOutcome> {
+    if (this.inflight !== undefined) return this.inflight.then(() => this.query(query))
+    if (this.disposed) return Promise.resolve({ ok: false, message: 'controller disposed' })
+    const promise = this.remote.query({ sessionId: this.sessionId, query })
+      .then((result): GitQueryOutcome => {
+        if (!result.ok) {
+          const detail = [result.error.code, result.error.message].filter(Boolean).join(': ')
+          return { ok: false, message: detail || 'rpc failure' }
+        }
+        const inner = result.value
+        if (inner.ok) return { ok: true, value: inner.value }
+        return { ok: false, message: inner.error.message ?? inner.error.code }
+      })
+      .catch((error: unknown): GitQueryOutcome => {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) }
+      })
+      .finally(() => {
+        this.inflight = undefined
+        if (!this.disposed) this.schedulePoll()
+      })
+    this.inflight = promise.then(() => undefined)
+    return promise
+  }
+
   /** Tear down: stop the timer; in-flight work settles into a no-op. */
   dispose(): void {
     this.disposed = true

package/src/client/error-text.ts

@@ -0,0 +1,21 @@
+import type { GitKey } from './locales.ts'
+import type { GitOperationErrorCode } from '../host/types.ts'
+
+/**
+ * 操作错误 → 展示文案。可预期的业务错误（如切换分支被未提交变更阻止）
+ * 映射本地化友好文案；其余错误回退原始 git message（无 message 时用 code）。
+ * 原始信息由调用方经 errorTextDetail 保留，供 title 等按需展示。
+ */
+export function errorText(code: GitOperationErrorCode, message: string | undefined, t: (key: GitKey) => string): string {
+  switch (code) {
+    case 'local-changes-block':
+      return t('error.localChangesBlock')
+    default:
+      return message ?? code
+  }
+}
+
+/** 该错误是否应附带「处理变更」行动（打开 Git 中心变更页）。 */
+export function errorAction(code: GitOperationErrorCode): 'open-center' | null {
+  return code === 'local-changes-block' ? 'open-center' : null
+}