@young1lin/dsh-ui-gitworkbench 0.1.0

package/src/client/index.ts

@@ -0,0 +1,198 @@
+/**
+ * Browser half of @young1lin/dsh-ui-gitworkbench.
+ *
+ * Contributes one entry to the `conversation.session.header.actions` list slot:
+ * a compact git-workbench chip. Clicking it opens a right-side drawer with the
+ * file list and per-file diff. The data is fetched from the host's
+ * `gitWorkbench/stats` Remote method through the generic connection RPC channel;
+ * `gitWorkbench/sessionWorktree` reports the session's worktree binding so the
+ * chip can badge it and the drawer can switch between bound/main sources;
+ * `gitWorkbench/styleGet` and `styleSet` carry the per-project and global drawer
+ * styling, which lives on the host rather than in this browser.
+ *
+ * The fetch callback is handed to the component through the slot registration's
+ * `inject` face (the dsh pattern: business callbacks cross from apply-scope to
+ * component via the inject factory, never through a global ctx).
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-runtime' // informational inject edge (loading order)
+import type {} from '@deepseek-ai/dsh-client-ui-slots' // SlotMap is reused, not extended
+import {
+  GitWorkbenchPanel,
+  type GitCommit, type GitOpName, type GitOpPayload, type GitOpResult,
+  type WorkbenchStats, type SyncStatus, type WorktreeStatus,
+} from './GitWorkbenchPanel.tsx'
+import type { StyleEntry, StyleScope, StyleSettings } from './themes.ts'
+import { en, zh } from './locales.ts'
+
+/**
+ * This plugin's dictionary namespace. It is outside dsh's `LocaleNamespaceMap`
+ * merge table (out-of-tree plugin), so registration uses the single-locale
+ * untyped `register` overload provided for that case.
+ */
+const NS = 'gitworkbench'
+
+/** Required client services: sessions store + slot registry + connection RPC + locale. */
+export const inject = ['sessions', 'slots', 'connection', 'locale']
+
+export function apply(ctx: ClientContext): void {
+  // `connection` is a root service; reach it off the root context the apply runs under.
+  const connection = (ctx as unknown as { connection: { rpc: { call: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown> } } }).connection
+  const locale = (ctx as unknown as {
+    locale: { register: (ns: string, id: string, dict: Record<string, string>) => () => void }
+  }).locale
+
+  // One effect per locale: each register call returns its own disposer, and the
+  // runtime rejects re-registering a locale a namespace already has (so a reload
+  // that failed to dispose fails loudly rather than silently keeping stale copy).
+  ctx.effect(() => locale.register(NS, 'zh', zh), 'dsh-ui-gitworkbench: zh dictionary')
+  ctx.effect(() => locale.register(NS, 'en', en), 'dsh-ui-gitworkbench: en dictionary')
+
+  ctx.slots.inject('conversation.session.header.actions', () => ctx.slots.register(
+    {
+      name: 'conversation.session.header.actions',
+      id: 'git-workbench',
+      // After the job-list action (order 20); a low-key stats chip.
+      order: 30,
+      // Declaring the namespace is what puts the framework's `t` in the
+      // component's props — it follows the user's language preference.
+      locale: NS,
+      inject: () => ({
+        // Bound RPC caller the component invokes on mount + poll. Plain args under SRC.
+        fetchStats: async (worktreePath: string | undefined, signal: AbortSignal): Promise<WorkbenchStats | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/stats',
+            worktreePath === undefined ? { args: {} } : { args: { worktreePath } },
+            signal,
+          ) as { ok: true; value: WorkbenchStats } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // On-demand single-file diff. With `commit` it is that commit's change to the
+        // file; without it, the working tree (tracked: git diff HEAD --; untracked: synthesized).
+        fetchFileDiff: async (worktreePath: string | undefined, path: string, commit: string | undefined, signal: AbortSignal): Promise<string> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/fileDiff',
+            { args: { worktreePath: worktreePath ?? '', path, ...commit === undefined ? {} : { commit } } },
+            signal,
+          ) as { ok: true; value: { diff: string } } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value.diff : ''
+        },
+        // One commit's change set, in the same shape as `stats` — the drawer's tree and
+        // diff panes render it through the same code path as the working tree.
+        fetchCommitStats: async (worktreePath: string | undefined, hash: string, signal: AbortSignal): Promise<WorkbenchStats | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/commitStats',
+            { args: { worktreePath: worktreePath ?? '', hash } },
+            signal,
+          ) as { ok: true; value: WorkbenchStats } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // One page of the commit log past what `stats` bundles, so the history
+        // list can grow instead of stopping at the first page.
+        fetchCommits: async (worktreePath: string | undefined, ref: string, skip: number, limit: number, signal: AbortSignal): Promise<{ commits: GitCommit[]; hasMore: boolean } | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/commits',
+            { args: { worktreePath: worktreePath ?? '', ref, skip, limit } },
+            signal,
+          ) as { ok: true; value: { commits: GitCommit[]; hasMore: boolean } } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // Two refs compared as `base...head`, in the same shape as every other
+        // view, so the drawer's tree and diff panes render it unchanged.
+        fetchCompare: async (worktreePath: string | undefined, base: string, head: string, signal: AbortSignal): Promise<WorkbenchStats | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/compareRefs',
+            { args: { worktreePath: worktreePath ?? '', base, head } },
+            signal,
+          ) as { ok: true; value: WorkbenchStats } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // The session's binding plus EVERY worktree of the surrounding repository.
+        // Polled in step with the stats, so the chip tracks the agent's enter/exit
+        // calls and the drawer's source list tracks worktrees added outside dsh.
+        fetchWorktreeStatus: async (sessionId: string, repoPath: string | undefined, signal: AbortSignal): Promise<WorktreeStatus | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/worktreeStatus',
+            { args: { sessionId, repoPath: repoPath ?? '' } },
+            signal,
+          ) as { ok: true; value: WorktreeStatus } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // The session's binding and nothing else. This one reads the bindings
+        // JSON and spawns no git, which is what lets the chip keep watching for
+        // an agent's `worktree_enter` with the drawer shut — where the full
+        // status call (rev-parse + worktree list + branch list) would be a git
+        // spawn per session header per tick. A disagreement here is what
+        // triggers one `worktreeStatus` to repaint everything.
+        fetchSessionBinding: async (sessionId: string, signal: AbortSignal): Promise<{ worktreePath: string | null; name: string | null } | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/sessionWorktree',
+            { args: { sessionId } },
+            signal,
+          ) as { ok: true; value: { worktreePath: string | null; name: string | null } } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // Drawer styling for this directory: the project's scope and the global
+        // one, unresolved — the menu edits each separately, so it needs both.
+        fetchStyle: async (worktreePath: string | undefined, signal: AbortSignal): Promise<StyleSettings | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/styleGet',
+            { args: { worktreePath: worktreePath ?? '' } },
+            signal,
+          ) as { ok: true; value: StyleSettings } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        // Replace one scope's styling. The host validates and clamps everything
+        // in the entry, so a rejected value comes back as ok:false with a reason.
+        saveStyle: async (worktreePath: string | undefined, scope: StyleScope, entry: StyleEntry, signal: AbortSignal): Promise<{ ok: boolean; error?: string }> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/styleSet',
+            { args: { worktreePath: worktreePath ?? '', scope, entry } },
+            signal,
+          // Flat rather than a discriminated union: this package compiles with
+          // `strictNullChecks` off, which cannot narrow one, and this is the only
+          // caller that reads the transport's own error rather than ignoring it.
+          ) as { ok: boolean; value?: { ok: boolean; error?: string }; error?: { message?: string } }
+          if (result.ok && result.value !== undefined) return result.value
+          return { ok: false, error: result.error?.message ?? 'rpc failed' }
+        },
+
+        // ---- write operations ----
+        //
+        // Each returns the host's own GitOpResult. A transport failure is folded
+        // into the same shape rather than thrown: the drawer shows one banner for
+        // "the operation failed", and it should not matter to that banner whether
+        // git refused or the socket did.
+        fetchSync: async (worktreePath: string | undefined, signal: AbortSignal): Promise<SyncStatus | null> => {
+          const result = await connection.rpc.call(
+            '/api',
+            'gitWorkbench/syncStatus',
+            { args: { worktreePath: worktreePath ?? '' } },
+            signal,
+          ) as { ok: true; value: SyncStatus } | { ok: false; error: { message?: string } }
+          return result.ok ? result.value : null
+        },
+        runGitOp: async (op: GitOpName, worktreePath: string | undefined, payload: GitOpPayload, signal: AbortSignal): Promise<GitOpResult> => {
+          const result = await connection.rpc.call(
+            '/api',
+            `gitWorkbench/${op}`,
+            { args: { worktreePath: worktreePath ?? '', ...payload } },
+            signal,
+          ) as { ok: boolean; value?: GitOpResult; error?: { message?: string } }
+          if (result.ok && result.value !== undefined) return result.value
+          return { ok: false, failure: 'unknown', error: result.error?.message ?? 'rpc failed' }
+        },
+      }),
+    },
+    GitWorkbenchPanel,
+  ))
+}

package/src/client/locales.ts

@@ -0,0 +1,270 @@
+/**
+ * Dictionaries for this plugin's UI copy, registered into the app's locale
+ * runtime under the `gitworkbench` namespace so the panel follows the user's
+ * language preference instead of shipping one hardcoded language.
+ *
+ * The namespace lives outside dsh's `LocaleNamespaceMap` merge table (this is an
+ * out-of-tree plugin), so registration uses `ctx.locale.register(ns, locale, dict)`
+ * — the single-locale untyped form the runtime provides for exactly that case.
+ * Keys ARE compile-time checked — both dictionaries are `Record<WorkbenchKey, string>`,
+ * so tsc keeps them in step — but a lookup miss still renders the key itself
+ * rather than blank.
+ *
+ * Values are templates with `{name}` placeholders.
+ *
+ * English wording follows git's own vocabulary rather than translating the
+ * Chinese literally: a change set is `added / modified / deleted`, matching
+ * `git status` and the file badges (A / M / D) the tree already renders.
+ */
+
+/** Every key this plugin looks up — the two dictionaries below must both cover it. */
+export type WorkbenchKey =
+  | 'aheadTitle' | 'behindTitle' | 'files'
+  | 'drawerLabel' | 'totalsDim' | 'refresh' | 'close'
+  | 'tabsLabel' | 'tabChanges' | 'tabHistory' | 'tabCompare'
+  | 'sourceLabel' | 'workingTree'
+  | 'loadingCommit' | 'renamedFrom' | 'binaryFile' | 'loadingDiff' | 'noTextDiff'
+  | 'noCommits' | 'historyLabel' | 'historyEnd' | 'loading' | 'maximize' | 'restore'
+  | 'compareBase' | 'compareHead' | 'comparePick' | 'compareCommits' | 'loadingCompare' | 'noBranches'
+  | 'refSearch' | 'refNone' | 'refCount' | 'refTruncated' | 'refWorktrees' | 'refBranches' | 'historyRefLabel'
+  | 'settings' | 'themeMode' | 'themePalette' | 'themeScope' | 'themeBackground' | 'themeCss'
+  | 'modeSystem' | 'modeLight' | 'modeDark'
+  | 'scopeProject' | 'scopeGlobal' | 'scopeGlobalHint' | 'scopeNoRepo'
+  | 'bgNone' | 'bgChoose' | 'bgClear' | 'bgBlur' | 'bgVeil' | 'bgWorking' | 'bgFailed' | 'bgTooBig'
+  | 'cssPlaceholder' | 'cssImport' | 'cssApply' | 'cssUnapplied' | 'styleFailed'
+  | 'resizeLabel' | 'resizeCommits' | 'resizeTree'
+  | 'expandAll' | 'collapseAll' | 'noBranch'
+  | 'copyCommit' | 'copiedCommit'
+  // write operations
+  | 'syncLabel' | 'noUpstream' | 'noUpstreamHint' | 'upToDate' | 'opRunning'
+  | 'fetch' | 'pull' | 'push' | 'publish' | 'pushSetUpstream'
+  | 'pullModeLabel' | 'pullFf' | 'pullRebase' | 'pullMerge'
+  | 'stage' | 'unstage' | 'stageAll' | 'unstageAll' | 'stagedCount'
+  | 'commit' | 'amend' | 'commitPlaceholder' | 'commitNeedMessage' | 'commitLead'
+  | 'op.ok.stage' | 'op.ok.unstage' | 'op.ok.commit' | 'op.ok.fetch' | 'op.ok.pull' | 'op.ok.push'
+  | 'op.fail.auth' | 'op.fail.network' | 'op.fail.no-upstream' | 'op.fail.diverged' | 'op.fail.conflict'
+  | 'op.fail.nothing-to-commit' | 'op.fail.dirty' | 'op.fail.unknown'
+
+export const zh: Record<WorkbenchKey, string> = {
+  aheadTitle: '领先上游 {count} 个提交',
+  behindTitle: '落后上游 {count} 个提交',
+  files: '{count} 文件',
+  drawerLabel: 'git 变更',
+  totalsDim: '{added} 新 · {modified} 改 · {deleted} 删',
+  refresh: '刷新',
+  close: '关闭',
+  tabsLabel: '变更视图',
+  tabChanges: '变更',
+  tabHistory: '历史',
+  tabCompare: '对比',
+  historyEnd: '已到最早的提交',
+  loading: '加载中…',
+  maximize: '最大化',
+  restore: '还原',
+  compareBase: '基准',
+  compareHead: '对比',
+  comparePick: '选择两个不同的分支进行对比',
+  compareCommits: '{count} 个提交（自共同祖先起）',
+  loadingCompare: '加载对比…',
+  noBranches: '没有可对比的分支',
+  refSearch: '筛选分支…',
+  refNone: '没有匹配的分支',
+  refCount: '{shown} / {total}',
+  refTruncated: '仅显示最近的若干分支',
+  refWorktrees: '有工作树的分支',
+  refBranches: '其他分支',
+  historyRefLabel: '分支',
+  settings: '设置',
+  themeMode: '明暗',
+  themePalette: '配色',
+  themeScope: '作用范围',
+  themeBackground: '背景图',
+  themeCss: '自定义 CSS',
+  modeSystem: '跟随',
+  modeLight: '亮色',
+  modeDark: '暗色',
+  scopeProject: '本项目',
+  scopeGlobal: '全局',
+  scopeGlobalHint: '所有项目；本项目单独设置时以本项目为准',
+  scopeNoRepo: '当前目录不是 git 仓库，只能设置全局',
+  bgNone: '未设置背景图',
+  bgChoose: '选择图片…',
+  bgClear: '清除',
+  bgBlur: '虚化',
+  bgVeil: '遮罩',
+  bgWorking: '处理中…',
+  bgFailed: '这个文件无法作为图片读取',
+  bgTooBig: '图片过大，请换一张',
+  cssPlaceholder: '例如 [data-gs-part="card"] { --gs-accent: #ff0066; }',
+  cssImport: '导入…',
+  cssApply: '应用',
+  cssUnapplied: '有未应用的修改',
+  styleFailed: '保存失败',
+  resizeLabel: '拖动调整抽屉宽度',
+  resizeCommits: '拖动调整提交列表宽度',
+  resizeTree: '拖动调整文件树宽度',
+  sourceLabel: '统计来源切换',
+  workingTree: '工作区',
+  loadingCommit: '加载提交…',
+  renamedFrom: '重命名自',
+  binaryFile: '二进制文件 —— 不显示文本 diff',
+  loadingDiff: '加载 diff…',
+  noTextDiff: '无文本差异',
+  noCommits: '无提交历史',
+  historyLabel: '提交历史',
+  expandAll: '展开全部',
+  collapseAll: '收起全部',
+  noBranch: '(无分支)',
+  copyCommit: '复制提交说明',
+  copiedCommit: '已复制',
+  syncLabel: '与远端同步',
+  noUpstream: '未跟踪远端分支',
+  noUpstreamHint: '当前分支没有上游分支，先推送一次即可建立',
+  upToDate: '已同步',
+  opRunning: '执行中…',
+  fetch: '拉取远端信息',
+  pull: '拉取',
+  push: '推送',
+  publish: '发布分支',
+  pushSetUpstream: '首次推送，将建立 origin 上的同名分支',
+  pullModeLabel: '拉取方式',
+  pullFf: '仅快进',
+  pullRebase: '变基',
+  pullMerge: '合并',
+  stage: '暂存',
+  unstage: '取消暂存',
+  stageAll: '勾选全部',
+  unstageAll: '取消全部勾选',
+  stagedCount: '已勾选 {count} 个',
+  commit: '提交',
+  amend: '修改上一条提交',
+  commitPlaceholder: '提交说明（Ctrl+Enter 提交）',
+  commitNeedMessage: '请先填写提交说明',
+  commitLead: '先勾选文件暂存，再提交',
+  'op.ok.stage': '已暂存',
+  'op.ok.unstage': '已取消暂存',
+  'op.ok.commit': '提交成功',
+  'op.ok.fetch': '已获取远端信息',
+  'op.ok.pull': '拉取完成',
+  'op.ok.push': '推送成功',
+  'op.fail.auth': '认证失败。凭据提示已被禁用，请先在终端里配置好凭据再重试。',
+  'op.fail.network': '网络不可达：主机名解析失败或连接不上。检查网络与远程地址后重试。',
+  'op.fail.no-upstream': '当前分支没有上游分支。',
+  'op.fail.diverged': '远端有本地没有的提交。先拉取再推送——这里不会强制覆盖。',
+  'op.fail.conflict': '出现冲突，工作区已被改动。请在编辑器里解决冲突后继续。',
+  'op.fail.nothing-to-commit': '暂存区是空的，没有可提交的内容。',
+  'op.fail.dirty': '本地改动会被覆盖。先提交或暂存它们。',
+  'op.fail.unknown': '操作失败。',
+}
+
+export const en: Record<WorkbenchKey, string> = {
+  aheadTitle: '{count} commits ahead of upstream',
+  behindTitle: '{count} commits behind upstream',
+  files: '{count} files',
+  drawerLabel: 'git changes',
+  totalsDim: '{added} added · {modified} modified · {deleted} deleted',
+  refresh: 'Refresh',
+  close: 'Close',
+  tabsLabel: 'Change views',
+  tabChanges: 'Changes',
+  tabHistory: 'History',
+  tabCompare: 'Compare',
+  historyEnd: 'Start of history',
+  loading: 'Loading…',
+  maximize: 'Maximize',
+  restore: 'Restore',
+  compareBase: 'Base',
+  compareHead: 'Compare',
+  comparePick: 'Pick two different branches to compare',
+  compareCommits: '{count} commits since they diverged',
+  loadingCompare: 'Loading comparison…',
+  noBranches: 'No branches to compare',
+  refSearch: 'Filter branches…',
+  refNone: 'No matching branch',
+  refCount: '{shown} / {total}',
+  refTruncated: 'showing the most recent only',
+  refWorktrees: 'With a worktree',
+  refBranches: 'Other branches',
+  historyRefLabel: 'Branch',
+  settings: 'Settings',
+  themeMode: 'Mode',
+  themePalette: 'Palette',
+  themeScope: 'Applies to',
+  themeBackground: 'Background',
+  themeCss: 'Custom CSS',
+  modeSystem: 'Match app',
+  modeLight: 'Light',
+  modeDark: 'Dark',
+  scopeProject: 'This project',
+  scopeGlobal: 'Global',
+  scopeGlobalHint: 'Every project; a project setting wins over this one',
+  scopeNoRepo: 'Not a git repository — global only',
+  bgNone: 'No background image',
+  bgChoose: 'Choose image…',
+  bgClear: 'Clear',
+  bgBlur: 'Blur',
+  bgVeil: 'Veil',
+  bgWorking: 'Working…',
+  bgFailed: 'That file could not be read as an image',
+  bgTooBig: 'Image too large — pick another',
+  cssPlaceholder: 'e.g. [data-gs-part="card"] { --gs-accent: #ff0066; }',
+  cssImport: 'Import…',
+  cssApply: 'Apply',
+  cssUnapplied: 'Unapplied changes',
+  styleFailed: 'Could not save',
+  resizeLabel: 'Drag to resize the drawer',
+  resizeCommits: 'Drag to resize the commit list',
+  resizeTree: 'Drag to resize the file tree',
+  sourceLabel: 'Switch stats source',
+  workingTree: 'Working tree',
+  loadingCommit: 'Loading commit…',
+  renamedFrom: 'Renamed from',
+  binaryFile: 'Binary file — no text diff',
+  loadingDiff: 'Loading diff…',
+  noTextDiff: 'No text changes',
+  noCommits: 'No commit history',
+  historyLabel: 'Commit history',
+  expandAll: 'Expand all',
+  collapseAll: 'Collapse all',
+  noBranch: '(no branch)',
+  copyCommit: 'Copy message',
+  copiedCommit: 'Copied',
+  syncLabel: 'Sync with remote',
+  noUpstream: 'No upstream branch',
+  noUpstreamHint: 'This branch tracks nothing yet; one push establishes it',
+  upToDate: 'Up to date',
+  opRunning: 'Working…',
+  fetch: 'Fetch',
+  pull: 'Pull',
+  push: 'Push',
+  publish: 'Publish branch',
+  pushSetUpstream: 'First push — creates the branch on origin',
+  pullModeLabel: 'Pull strategy',
+  pullFf: 'Fast-forward only',
+  pullRebase: 'Rebase',
+  pullMerge: 'Merge',
+  stage: 'Stage',
+  unstage: 'Unstage',
+  stageAll: 'Tick all',
+  unstageAll: 'Untick all',
+  stagedCount: '{count} ticked',
+  commit: 'Commit',
+  amend: 'Amend last commit',
+  commitPlaceholder: 'Commit message (Ctrl+Enter to commit)',
+  commitNeedMessage: 'Write a commit message first',
+  commitLead: 'Tick to stage, then commit',
+  'op.ok.stage': 'Staged',
+  'op.ok.unstage': 'Unstaged',
+  'op.ok.commit': 'Committed',
+  'op.ok.fetch': 'Fetched',
+  'op.ok.pull': 'Pulled',
+  'op.ok.push': 'Pushed',
+  'op.fail.auth': 'Authentication failed. Credential prompts are disabled here — set your credentials up in a terminal first.',
+  'op.fail.network': 'The network was unreachable — the host could not be resolved or the connection failed. Check connectivity and the remote URL, then retry.',
+  'op.fail.no-upstream': 'This branch has no upstream.',
+  'op.fail.diverged': 'The remote has commits this branch does not. Pull first — nothing here force-pushes.',
+  'op.fail.conflict': 'Conflicts. The working tree has been changed; resolve them in the editor before continuing.',
+  'op.fail.nothing-to-commit': 'Nothing staged to commit.',
+  'op.fail.dirty': 'Local changes would be overwritten. Commit or stash them first.',
+  'op.fail.unknown': 'The operation failed.',
+}

package/src/client/op-feedback.ts

@@ -0,0 +1,65 @@
+/**
+ * Pacing for the drawer's "an operation is running" appearance.
+ *
+ * `busy` in GitWorkbenchPanel names two different facts. The first is a guard: an
+ * operation is in flight, so every control refuses to start another. That has
+ * to be true on the same tick as the click, or a double click fires two git
+ * calls. The second is an announcement — the drawer dims what it has disabled,
+ * so the user can see why a click did nothing.
+ *
+ * Only the announcement is worth pacing. A tick IS a git call (`add` on the way
+ * in, `restore --staged` on the way out) and it completes in about 150ms; that
+ * was long enough to fade the whole sync row to `opacity: .45` and back on
+ * every single click, which reads as a flicker rather than as feedback. Nobody
+ * can act on a message that brief — its only effect was the blink.
+ *
+ * So the appearance waits, and once it arrives it stays. A threshold on its own
+ * would just move the boundary: an operation finishing a little past it would
+ * paint the dim for a few milliseconds, which is the same blink one notch
+ * slower. The hold is what makes the dim always mean something.
+ *
+ * These live outside the panel so they can be tested — importing
+ * GitWorkbenchPanel.tsx pulls a CSS module and React, which a node test environment
+ * cannot load.
+ */
+
+/**
+ * How long an operation must run before the drawer dims what it disabled.
+ *
+ * Above the ~150ms a stage/unstage round trip measured on the live drawer, so
+ * the operation behind every tick never paints at all.
+ */
+export const BUSY_DELAY_MS = 220
+
+/** Once the dim is up, the shortest time it stays — long enough to read. */
+export const BUSY_HOLD_MS = 320
+
+/**
+ * Whether a control is disabled ONLY by an operation too young to report.
+ *
+ * Such a control keeps its full strength: it is already refusing clicks, and
+ * saying so costs more than it gives when the answer arrives in 150ms.
+ *
+ * @param running - whether any git operation is in flight.
+ * @param sustained - whether that operation has lasted long enough to report.
+ * @param steady - whether this control is disabled for a reason of its own,
+ *   like Pull with no upstream. Those keep their dim: it states an
+ *   unavailable action, and dropping it mid-operation would be a new flicker.
+ */
+export function quietlyDisabled(running: boolean, sustained: boolean, steady: boolean): boolean {
+  return running && !sustained && !steady
+}
+
+/**
+ * Milliseconds the dim must stay up before it may be taken down.
+ *
+ * @param shownAt - when the dim appeared, in `Date.now()` terms.
+ * @param now - the current time.
+ * @param hold - the minimum visible duration.
+ * @returns the remaining time, never negative — a negative delay would
+ *   schedule a timer into the past and make the dim vanish on the same frame
+ *   it was granted.
+ */
+export function holdRemaining(shownAt: number, now: number, hold: number = BUSY_HOLD_MS): number {
+  return Math.max(0, hold - (now - shownAt))
+}