@young1lin/dsh-ui-gitworkbench 0.1.11 → 0.1.13

package/src/client/WorktreeGlyph.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react'
+import css from './GitWorkbenchPanel.module.css'
+
+/**
+ * Tree glyph: a root with two working copies hanging off it.
+ *
+ * This was git's fork glyph — the three-dot branch symbol — which named the
+ * wrong thing. A worktree is not a branch; the picker beside it is already full
+ * of branch names, and the two ideas need to stay tellable apart at 12px. A
+ * hierarchy reads as "one repository, several directories", which is what a
+ * worktree list is.
+ */
+export function WorktreeGlyph(): ReactNode {
+  return (
+    <svg className={css.cardGlyph} width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      {/* Trunk down from the root, and the two limbs it puts out. */}
+      <path d="M2.25 2.75h1.5v10.5h-1.5zM3 6.75h7.25v1.5H3zM3 11.75h7.25v1.5H3z" />
+      {/* The root, then the worktrees. */}
+      <circle cx="3" cy="2.75" r="1.75" />
+      <circle cx="12" cy="7.5" r="1.75" />
+      <circle cx="12" cy="12.5" r="1.75" />
+    </svg>
+  )
+}

package/src/client/cm-search-theme.ts

@@ -0,0 +1,250 @@
+/**
+ * The Ctrl/Cmd+F panel, restated in the drawer's own controls.
+ *
+ * `@codemirror/search` ships the panel with the library's stock chrome, and
+ * none of it follows a palette: the strip is `#f5f5f5` with black text (or
+ * `#333338` with white), the buttons carry a grey `linear-gradient` and a 1px
+ * radius, the fields are `1px solid silver`, the ticks are whatever the
+ * platform draws, and a match is `#ffff0054`. Worse, form controls do not
+ * inherit a font, and the library asks for `font-size: 70%` without naming a
+ * family — so the panel renders in the browser's default face at a size no
+ * other control in the drawer uses. Over a Nord or a cyberpunk drawer the
+ * strip stays light grey with black text on it.
+ *
+ * So the panel is dressed here, and ONLY through `--gs-*` tokens: every
+ * palette then clothes it for free, exactly as it clothes the pane around it.
+ * None of the shapes are invented for this panel — each is the one already on
+ * screen beside it:
+ *
+ * - the strip follows `.blockBar`, the drawer's other float over code, where
+ *   `--gs-surface-2` plus a soft shadow are what keep it readable.
+ * - the buttons follow the shared compact control (`.treeIcon`,
+ *   `.funnelPreset`, `.layoutButton`): `--gs-h-compact`, `--gs-pad-compact`,
+ *   `--gs-r-control`, `--gs-t-dense`, and the same hover.
+ * - the fields follow the tree's own filter box, `.fbSearch`.
+ * - the ticks follow `.funnelRow input[type=checkbox]`: `appearance: none`
+ *   and a rotated border for the mark, so nothing ships as an asset and every
+ *   state recolors with the theme.
+ *
+ * Layout is the other half, and it stays in INLINE FLOW on purpose. The
+ * obvious answer — make the panel a wrapping flex row with one gap — costs
+ * the find/replace break: the library separates the two halves with a `<br>`,
+ * and Blink gives a `<br>` no box of its own inside a flex container. Neither
+ * `flex-basis: 100%`, `width: 100%` nor `min-width: 100%` on it makes the
+ * replace field start a line (measured on the running app; all four left it
+ * beside `by word`). So the controls stay inline-level atoms instead, and
+ * carry the rhythm the library asked for with `.2em .6em .2em 0` in a single
+ * margin. Wrapping still works when the pane is narrow: an atomic inline is a
+ * line-break opportunity, which is what lets the strip reflow in the 190px
+ * the Changes column drags down to.
+ *
+ * Kept out of `CodeEditor.tsx` so a test can read it: that file pulls React
+ * and a CSS Module, and neither loads under vitest.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/cm-search-theme
+ */
+
+/** A CodeMirror theme spec, narrowed to what this module writes: one flat
+ *  declaration block per selector, no nesting and no at-rules. */
+export type ThemeSpec = Readonly<Record<string, Readonly<Record<string, string>>>>
+
+/** Selector prefix for everything inside the panel. Spelled out per rule
+ *  rather than nested, because CodeMirror's style builder only nests under a
+ *  `&`, and a flat key is what a test can read back. */
+const PANEL = '.cm-panel.cm-search'
+
+/** Between two controls on a row, and between the find row and the replace
+ *  row. The row gap is carried as a bottom margin per control, because inline
+ *  flow has no `gap`; the panel's bottom padding is short by exactly this. */
+const GAP = '6px'
+const ROW_GAP = '6px'
+
+export const SEARCH_PANEL_THEME: ThemeSpec = {
+  /* The strip. `.cm-panels` is the element the library paints, so the
+     override belongs there rather than on the panel inside it. The shadow is
+     `.blockBar`'s: this is a sticky bar with code scrolling under it, and a
+     border alone leaves the two planes touching. */
+  '.cm-panels': {
+    backgroundColor: 'var(--gs-surface-2)',
+    color: 'var(--gs-fg)',
+    boxShadow: '0 4px 14px var(--gs-shadow)',
+  },
+  '.cm-panels-top': { borderBottom: '1px solid var(--gs-border)' },
+  '.cm-panels-bottom': { borderTop: '1px solid var(--gs-border)' },
+
+  [PANEL]: {
+    position: 'relative',
+    /* The right gutter is the close button's: it is positioned over it, so
+       nothing may wrap underneath. The bottom is short by ROW_GAP, which every
+       control carries below itself; the two add back up to the top. */
+    padding: '8px 32px 2px 10px',
+    lineHeight: '1',
+  },
+  /* One rhythm for the whole strip, replacing the library's `.2em .6em .2em 0`.
+     `vertical-align: top` with one height is what makes a row of controls a
+     row rather than four boxes on a shared baseline. */
+  [`${PANEL} input, ${PANEL} button, ${PANEL} label`]: {
+    boxSizing: 'border-box',
+    verticalAlign: 'top',
+    margin: `0 ${GAP} ${ROW_GAP} 0`,
+  },
+
+  [`${PANEL} .cm-textfield`]: {
+    /* A column rather than a share of the row: find and replace are read as a
+       pair, and a pair that does not start and end at the same x is noise. */
+    width: '220px',
+    maxWidth: '100%',
+    boxSizing: 'border-box',
+    height: 'var(--gs-h-compact)',
+    padding: '0 8px',
+    font: 'inherit',
+    fontSize: 'var(--gs-t-dense)',
+    color: 'var(--gs-fg)',
+    backgroundColor: 'var(--gs-surface)',
+    border: '1px solid var(--gs-border)',
+    borderRadius: 'var(--gs-r-control)',
+  },
+  [`${PANEL} .cm-textfield::placeholder`]: { color: 'var(--gs-fg-faint)' },
+  [`${PANEL} .cm-textfield:focus`]: { outline: 'none', borderColor: 'var(--gs-accent)' },
+
+  /* `3/128`. A span rather than a control, so it takes none of the shared
+     rule above and states its own box; the meta size and the faint ink keep it
+     a readout beside the field rather than a fourth thing to click. */
+  [`${PANEL} .cm-gwSearchCount`]: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    boxSizing: 'border-box',
+    height: 'var(--gs-h-compact)',
+    margin: `0 ${GAP} ${ROW_GAP} 0`,
+    verticalAlign: 'top',
+    font: 'inherit',
+    fontSize: 'var(--gs-t-meta)',
+    lineHeight: '1',
+    whiteSpace: 'nowrap',
+    fontVariantNumeric: 'tabular-nums',
+    color: 'var(--gs-fg-faint)',
+  },
+
+  [`${PANEL} .cm-button`]: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    boxSizing: 'border-box',
+    height: 'var(--gs-h-compact)',
+    padding: 'var(--gs-pad-compact)',
+    font: 'inherit',
+    fontSize: 'var(--gs-t-dense)',
+    lineHeight: '1',
+    whiteSpace: 'nowrap',
+    color: 'var(--gs-fg-dim)',
+    /* The gradient is the library's, and it is on `background-image`: a
+       background COLOUR alone would leave it painted on top. */
+    backgroundColor: 'transparent',
+    backgroundImage: 'none',
+    border: '1px solid var(--gs-border)',
+    borderRadius: 'var(--gs-r-control)',
+    cursor: 'pointer',
+    transition: 'background 120ms ease, color 120ms ease, border-color 120ms ease',
+  },
+  [`${PANEL} .cm-button:hover`]: {
+    color: 'var(--gs-fg)',
+    backgroundColor: 'var(--gs-raise)',
+    backgroundImage: 'none',
+    borderColor: 'var(--gs-fg-fainter)',
+  },
+  /* The library keeps a second gradient for the pressed state. */
+  [`${PANEL} .cm-button:active`]: {
+    backgroundColor: 'var(--gs-raise)',
+    backgroundImage: 'none',
+  },
+  [`${PANEL} .cm-button:focus-visible`]: { outline: '2px solid var(--gs-accent)', outlineOffset: '1px' },
+
+  [`${PANEL} label`]: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    boxSizing: 'border-box',
+    height: 'var(--gs-h-compact)',
+    gap: '5px',
+    font: 'inherit',
+    fontSize: 'var(--gs-t-meta)',
+    lineHeight: '1',
+    whiteSpace: 'nowrap',
+    color: 'var(--gs-fg-dim)',
+    cursor: 'pointer',
+    WebkitUserSelect: 'none',
+    userSelect: 'none',
+  },
+
+  [`${PANEL} input[type=checkbox]`]: {
+    WebkitAppearance: 'none',
+    appearance: 'none',
+    position: 'relative',
+    boxSizing: 'border-box',
+    width: '14px',
+    height: '14px',
+    margin: '0',
+    backgroundColor: 'transparent',
+    border: '1px solid var(--gs-fg-fainter)',
+    borderRadius: '3px',
+    cursor: 'pointer',
+    transition: 'background 120ms ease, border-color 120ms ease',
+  },
+  [`${PANEL} input[type=checkbox]:hover`]: { borderColor: 'var(--gs-fg-dim)' },
+  [`${PANEL} input[type=checkbox]:checked`]: {
+    backgroundColor: 'var(--gs-accent)',
+    borderColor: 'var(--gs-accent)',
+  },
+  [`${PANEL} input[type=checkbox]:focus-visible`]: { outline: '2px solid var(--gs-accent)', outlineOffset: '1px' },
+  [`${PANEL} input[type=checkbox]:checked::after`]: {
+    content: '""',
+    position: 'absolute',
+    left: '4px',
+    top: '1px',
+    width: '3px',
+    height: '7px',
+    border: 'solid var(--gs-on-accent)',
+    borderWidth: '0 1.5px 1.5px 0',
+    transform: 'rotate(42deg)',
+  },
+
+  /* Close. Square and quiet — it dismisses a panel, so it is not the drawer's
+     red header close. `background-color` is restated because the library sets
+     it to `inherit`, which would take the strip's fill. */
+  [`${PANEL} [name=close]`]: {
+    position: 'absolute',
+    top: '8px',
+    right: '8px',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: '20px',
+    height: '20px',
+    padding: '0',
+    margin: '0',
+    font: 'inherit',
+    fontSize: 'var(--gs-t-ui)',
+    lineHeight: '1',
+    color: 'var(--gs-fg-faint)',
+    backgroundColor: 'transparent',
+    border: '1px solid transparent',
+    borderRadius: 'var(--gs-r-control)',
+    cursor: 'pointer',
+  },
+  [`${PANEL} [name=close]:hover`]: { color: 'var(--gs-fg)', backgroundColor: 'var(--gs-raise)' },
+  [`${PANEL} [name=close]:focus-visible`]: { outline: '2px solid var(--gs-accent)', outlineOffset: '1px' },
+
+  /* A hit, and the hit the caret is on. Amber is what an editor uses to say
+     "found", and `--gs-warn` is the only warm token every palette defines;
+     the current one takes the drawer's single selected idiom —
+     `--gs-accent-bg` inside `--gs-accent-border` — rather than a second
+     highlighter colour. Declared after the plain match: both classes sit on
+     the same span at the same specificity, so source order decides. */
+  '.cm-searchMatch': {
+    backgroundColor: 'color-mix(in srgb, var(--gs-warn) 30%, transparent)',
+    borderRadius: '2px',
+  },
+  '.cm-searchMatch-selected': {
+    backgroundColor: 'color-mix(in srgb, var(--gs-accent) 34%, transparent)',
+    boxShadow: 'inset 0 0 0 1px var(--gs-accent)',
+  },
+}

package/src/client/diff-nav.ts

@@ -58,6 +58,20 @@ export interface BlockTop {
   readonly top: number
 }
 
+/** The change nearest a viewport position, used to retain the reader's place
+ * when the right diff grid becomes a dense editor. */
+export function blockNearestTo(anchors: readonly BlockTop[], top: number): BlockTop | null {
+  let nearest: BlockTop | null = null
+  let distance = Number.POSITIVE_INFINITY
+  for (const anchor of anchors) {
+    const next = Math.abs(anchor.top - top)
+    if (next >= distance) continue
+    nearest = anchor
+    distance = next
+  }
+  return nearest
+}
+
 /**
  * The content position that counts as "where the reader is".
  *
@@ -116,6 +130,13 @@ export function anchorFrom(
   return anchorFor(scrollTop)
 }
 
+/** The adjacent explicit editor selection, wrapping at both ends. */
+export function stepBlockIndex(totalBlocks: number, currentBlock: number, direction: 1 | -1): number | null {
+  if (totalBlocks <= 0) return null
+  const current = Number.isInteger(currentBlock) && currentBlock >= 0 && currentBlock < totalBlocks ? currentBlock : 0
+  return (current + direction + totalBlocks) % totalBlocks
+}
+
 /**
  * The next or previous change block, wrapping at the ends.
  *
@@ -224,3 +245,41 @@ export function blockTopsFromRows(
   }
   return tops
 }
+
+/**
+ * Place change blocks in one dense side of an aligned diff.
+ *
+ * Edit mode removes alignment holes: the working-tree CodeMirror has one row
+ * per real right-side line. A deletion-only block has no line on that side, so
+ * it sits at the following line's insertion point, or just after the final
+ * present line when the deletion reaches EOF.
+ */
+export function blockTopsFromSideRows(
+  rows: readonly import('./side-rows.ts').SideRow[],
+  side: 'left' | 'right',
+  rowH: number,
+  offset = 0,
+): readonly BlockTop[] {
+  const nextLine: Array<number | undefined> = new Array(rows.length)
+  let following: number | undefined
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const cell = rows[i]![side]
+    if (cell !== null) following = cell.line
+    nextLine[i] = following
+  }
+
+  const tops: BlockTop[] = []
+  const seen = new Set<number>()
+  let previous = 0
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i]!
+    const cell = row[side]
+    if (row.block >= 0 && !seen.has(row.block)) {
+      seen.add(row.block)
+      const line = cell?.line ?? nextLine[i] ?? previous + 1
+      tops.push({ block: row.block, top: offset + Math.max(0, line - 1) * rowH })
+    }
+    if (cell !== null) previous = cell.line
+  }
+  return tops
+}

package/src/client/git-workbench-types.ts

@@ -0,0 +1,252 @@
+/** Shared JSON-safe contracts between the panel, feature views, and RPC adapters. */
+
+export type GitFileStatus = 'added' | 'deleted' | 'modified' | 'renamed' | 'untracked'
+
+export interface GitFile {
+  readonly path: string
+  readonly status: GitFileStatus
+  readonly addedLines: number
+  readonly deletedLines: number
+  readonly binary: boolean
+  readonly previousPath?: string
+  /**
+   * Which side of the index this file's change is on. Both can be true — a file
+   * staged and then edited again. Absent outside the working-tree view: a
+   * commit's files were staged long ago and the question is meaningless.
+   */
+  readonly staged?: boolean
+  readonly unstaged?: boolean
+}
+
+export interface GitCommit {
+  readonly hash: string
+  readonly subject: string
+  readonly when: string
+  /** Everything after the subject. Empty string when the commit has none. */
+  readonly body: string
+  /** Author name (`%an`). Optional only because a pre-0.1.4 host half sends none. */
+  readonly authorName?: string
+  /** Committer name (`%cn`); equals the author except on rebases and patches a maintainer applied. */
+  readonly committerName?: string
+  /** Committer date, strict ISO 8601 (`%cI`) — the exact moment `when` summarizes. */
+  readonly dateIso?: string
+  /** Abbreviated parent hashes, first parent first — the graph's edges. */
+  readonly parents?: readonly string[]
+  /** Branch and tag names pointing here, already stripped of git's decoration syntax. */
+  readonly refs?: readonly string[]
+}
+
+export interface WorkbenchStats {
+  readonly worktreePath: string
+  readonly branch: string
+  readonly ahead: number
+  readonly behind: number
+  readonly detached: boolean
+  readonly addedLines: number
+  readonly deletedLines: number
+  readonly addedFiles: number
+  readonly deletedFiles: number
+  readonly modifiedFiles: number
+  readonly files: readonly GitFile[]
+  readonly diff: string
+  /**
+   * Commits this view is about: the single commit for a commit view, the range's
+   * commits for a comparison. Empty for the working tree — the history list
+   * loads its own pages so it can follow a ref of its own.
+   */
+  readonly commits: readonly GitCommit[]
+  readonly error?: string
+}
+
+/** One worktree of the repository, as `git worktree list --porcelain` reports it. */
+export interface WorktreeEntry {
+  readonly path: string
+  readonly head: string
+  readonly branch: string
+}
+
+/** The session's worktree binding, as persisted by the worktree tools. */
+export interface WorktreeBinding {
+  readonly repoRoot: string
+  readonly worktreePath: string
+  readonly name: string
+  readonly enteredAt: string
+  readonly baseCommit?: string
+}
+
+/**
+ * `gitWorkbench/worktreeStatus`: the session's binding (null when unbound) plus every
+ * worktree of the surrounding repository. Git allows at most one worktree per
+ * branch, so this one list is both the worktree picker and the branch picker.
+ */
+export interface WorktreeStatus {
+  readonly binding: WorktreeBinding | null
+  readonly worktrees: readonly WorktreeEntry[]
+  /**
+   * Every local branch, most-recently-committed first. Distinct from
+   * {@link worktrees} on purpose: a branch without a worktree has no directory
+   * to read, so it can be browsed or compared but not viewed as a working tree.
+   */
+  readonly branches: readonly string[]
+  /** Whether the host cut {@link branches} short at its cap. */
+  readonly branchesTruncated: boolean
+}
+
+/**
+ * `gitWorkbench/syncStatus`: where the current branch stands against its upstream.
+ *
+ * `upstream: null` and "level with the upstream" are different states and the
+ * drawer treats them differently — the first is what makes the first push pass
+ * `--set-upstream`, and both otherwise read as zero ahead and zero behind.
+ */
+export interface SyncStatus {
+  readonly branch: string
+  readonly upstream: string | null
+  readonly ahead: number
+  readonly behind: number
+  readonly detached: boolean
+  /** Whether the repository has any remote at all. No remote, no sync bar. */
+  readonly hasRemote: boolean
+}
+
+/** Why a write operation failed, in terms the drawer can explain. `stale` is
+ *  a sha the host re-derived and refused; `invalid` an argument combination
+ *  the host rejected before running anything. */
+export type GitOpFailure =
+  | 'auth' | 'network' | 'no-upstream' | 'diverged' | 'conflict'
+  | 'nothing-to-commit' | 'dirty' | 'stale' | 'invalid' | 'unknown'
+
+export interface GitOpResult {
+  readonly ok: boolean
+  readonly failure?: GitOpFailure
+  /** git's own message on failure. Shown verbatim: a classification is a hint. */
+  readonly error?: string
+  readonly output?: string
+}
+
+/** The host endpoints under `gitWorkbench/` that change something. */
+export type GitOpName = 'stage' | 'unstage' | 'commit' | 'fetch' | 'pull' | 'push' | 'discardFile' | 'applyBlocks'
+
+/** Extra arguments an operation needs beyond the worktree path. */
+export interface GitOpPayload {
+  readonly paths?: readonly string[]
+  readonly message?: string
+  readonly amend?: boolean
+  /** `pull` picks how to integrate; `applyBlocks` which block mutation. One
+   *  field serves both because the payload is a flat bag keyed by op — the
+   *  host narrows and validates it per endpoint. */
+  readonly mode?: 'ff-only' | 'rebase' | 'merge' | BlockMode
+  /** `discardFile` and `applyBlocks`, and deliberately singular: the one
+   *  irreversible thing the drawer does takes one file per call, so a mistaken
+   *  click costs one file. */
+  readonly path?: string
+  /** `discardFile` only: the effect the confirmation stated. The host refuses
+   *  if the file changed underneath the dialog and now means something else. */
+  readonly expectedEffect?: string
+  /** `applyBlocks` only: the layer whose diff the `diffSha` is over, and the
+   *  block's hunk-line indices (`side-rows.blockLines`). The host re-fetches
+   *  that layer's diff and refuses unless the sha still matches. */
+  readonly layer?: SideLayer
+  readonly diffSha?: string
+  readonly lines?: readonly number[]
+}
+
+export type { DiscardAnswer, DiscardNext, DiscardPreview } from './discard-flow.ts'
+export type { WriteResult } from './side-edit.ts'
+
+/** Which side of the index a side-by-side pane shows: `unstaged` is
+ *  index→worktree (the editable side), `staged` is HEAD→index (read-only). */
+export type SideLayer = 'unstaged' | 'staged'
+
+/** A block mutation the side pane's buttons request: `stage` and `discard` act
+ *  on the unstaged layer, `unstage` on the staged one. The host enforces the
+ *  same matrix. */
+export type BlockMode = 'stage' | 'unstage' | 'discard'
+
+/**
+ * What one block action acts on, snapshotted from the diff the pane had
+ * rendered when the click (or its confirmation) happened.
+ *
+ * The snapshot is the point: `diffSha` proves the file has not changed since
+ * the pane rendered it, and `lines` — the block's hunk-line indices — only
+ * mean anything against exactly that diff. A confirmed roll-back carries the
+ * ask it opened with, so the answer cannot drift under the dialog.
+ */
+export interface BlockAsk {
+  readonly path: string
+  readonly layer: SideLayer
+  readonly diffSha: string
+  readonly lines: readonly number[]
+  /** The block's line tallies, for the roll-back confirmation's wording. */
+  readonly added: number
+  readonly deleted: number
+  /** Whether the block is the file's entire content — the untracked case,
+   *  whose roll-back DELETES the file and whose confirmation says so. */
+  readonly wholeFile: boolean
+}
+
+/**
+ * `gitWorkbench/fileSides`: one layer of one file for the side-by-side pane.
+ * Mirrors the host's `FileSides` (the client re-declares host shapes rather
+ * than importing the host module, which pulls node and the RPC decorators).
+ */
+export interface FileSides {
+  /** Unified diff at full context; '' when the layer has no change. */
+  readonly diff: string
+  /** sha1 of `diff`, echoed back by mutations to prove the same snapshot. */
+  readonly diffSha: string
+  /** Whole right-hand text, the editor's initial buffer. */
+  readonly targetText: string
+  /** Blob sha of the right-hand side; '' when it does not exist. */
+  readonly targetSha: string
+  readonly binary: boolean
+  /** True when the file is past the size guard; the client shows the old view. */
+  readonly tooLarge: boolean
+  /** True when the working-tree file is not valid UTF-8; the pane shows the
+   *  diff but withholds the editor. Optional so an older host half reads as
+   *  "fine" rather than as a refusal this client cannot explain. */
+  readonly lossyEncoding?: boolean
+}
+
+/**
+ * `gitWorkbench/fileImage`: one working-tree file's bytes, when the host's
+ * signature check confirms they are an image a browser can draw.
+ *
+ * Every field is present in both outcomes — an image and a refusal — because
+ * the gateway's payloads carry no `undefined`. `reason` is '' exactly when
+ * `ok`, and names the refusal otherwise: 'notImage', 'tooLarge', 'missing'.
+ */
+export interface FileImage {
+  readonly ok: boolean
+  /** MIME type to label the blob with; '' when declined. */
+  readonly mime: string
+  /** Short label for the caption — 'PNG', 'WebP', 'SVG'; '' when declined. */
+  readonly kind: string
+  /** The whole file, base64; '' when declined. */
+  readonly base64: string
+  /** The file's size in bytes, reported either way. */
+  readonly bytes: number
+  readonly reason: string
+}
+
+/** One line's provenance, as `gitWorkbench/blame` reports it. */
+export interface BlameLine {
+  /** Full commit sha; all zeros for a line not committed yet. */
+  readonly hash: string
+  readonly author: string
+  /** Author time, unix seconds; 0 when git did not say. */
+  readonly time: number
+  readonly summary: string
+  readonly uncommitted: boolean
+}
+
+/** `gitWorkbench/blame`'s answer. `error` is present only on failure. */
+export interface BlameAnswer {
+  readonly lines: readonly BlameLine[]
+  /** Whether the file was longer than the gutter's cap. */
+  readonly truncated: boolean
+  readonly error?: string
+}
+
+/** Translate a key of this plugin's namespace, with optional `{name}` params. */
+export type Translate = (key: string, params?: Record<string, string | number>) => string

package/src/client/locales.ts

@@ -28,7 +28,7 @@ export type WorkbenchKey =
   | 'filesUnsavedAsk' | 'filesDiscardOpen' | 'filesMore' | 'filesVanished' | 'fileReadOnlyCrlf' | 'fileReadOnlyEncoding'
   | 'blameWhileEditing' | 'blameLine' | 'blamePick' | 'blameInHistory'
   | 'imageBroken' | 'imageFit' | 'imageActual' | 'imageTooLarge' | 'imageSource' | 'imagePreview'
-  | 'prevChange' | 'nextChange' | 'prevChangeHint' | 'nextChangeHint' | 'changeCount'
+  | 'prevChange' | 'nextChange' | 'prevChangeHint' | 'nextChangeHint' | 'changeCount' | 'changePosition'
   | 'sourceLabel' | 'workingTree'
   | 'loadingCommit' | 'renamedFrom' | 'binaryFile' | 'loadingDiff' | 'noTextDiff'
   | 'noCommits' | 'historyLabel' | 'historyEnd' | 'loading' | 'maximize' | 'restore'
@@ -62,7 +62,7 @@ export type WorkbenchKey =
   | 'discardAction' | 'discardTitle' | 'discardConfirm' | 'discardCancel'
   | 'discardBodyRestore' | 'discardBodyDelete' | 'discardBodyUnrename'
   // side-by-side block actions: the three buttons and the roll-back confirmation's wording
-  | 'blockStage' | 'blockDiscard' | 'blockUnstage' | 'blockDiscardBody' | 'blockDiscardBodyDelete'
+  | 'blockStage' | 'blockDiscard' | 'blockUnstage' | 'fileUnstage' | 'blockActionsDirty' | 'blockDiscardBody' | 'blockDiscardBodyDelete'
   // side-by-side editing: arm the editor, save, revert, the stale/conflict
   // banner, the CRLF refusal notice, and the unsaved-changes prompt that
   // guards every gesture dropping the buffer (tab, file, close)
@@ -171,6 +171,7 @@ export const zh: Record<WorkbenchKey, string> = {
   prevChangeHint: '上一处变更（Shift+F7）',
   nextChangeHint: '下一处变更（F7）',
   changeCount: '变更 {n} 处',
+  changePosition: '第 {current} / {total} 处变更',
   loadingDiff: '加载 diff…',
   noTextDiff: '无文本差异',
   // The side-by-side pane's layer tabs: unstaged is index→worktree, staged is
@@ -267,9 +268,11 @@ export const zh: Record<WorkbenchKey, string> = {
   discardBodyUnrename: '撤销重命名：{path} 改回 {previousPath}，改名期间的内容改动一并丢弃。',
   // One BLOCK, not the whole file: the side pane's roll-back states exactly
   // which lines leave and that the working-tree file is rewritten to do it.
-  blockStage: '暂存这块',
-  blockDiscard: '撤回这块',
-  blockUnstage: '取消暂存这块',
+  blockStage: '暂存此变更块',
+  blockDiscard: '恢复此变更块',
+  blockUnstage: '取消暂存此变更块',
+  fileUnstage: '取消暂存整个文件',
+  blockActionsDirty: '请先保存或放弃编辑器修改，再操作当前变更块',
   blockDiscardBody: '{path} 的这一块改动（{added} 行新增、{deleted} 行删除）将被撤回，工作区文件随之改写，无法找回。',
   // The untracked case: the file's whole content is the one block, so rolling
   // the block back reverse-applies the new-file patch and DELETES the file —
@@ -408,6 +411,7 @@ export const en: Record<WorkbenchKey, string> = {
   prevChangeHint: 'Previous change (Shift+F7)',
   nextChangeHint: 'Next change (F7)',
   changeCount: 'changes: {n}',
+  changePosition: 'change {current} / {total}',
   loadingDiff: 'Loading diff…',
   noTextDiff: 'No text changes',
   tabUnstaged: 'Unstaged',
@@ -489,9 +493,11 @@ export const en: Record<WorkbenchKey, string> = {
   discardBodyUnrename: 'Undo the rename: {path} goes back to {previousPath}, and content changed along the way is lost.',
   // One BLOCK, not the whole file: the side pane's roll-back states exactly
   // which lines leave and that the working-tree file is rewritten to do it.
-  blockStage: 'Stage block',
-  blockDiscard: 'Roll back block',
-  blockUnstage: 'Unstage block',
+  blockStage: 'Stage hunk',
+  blockDiscard: 'Revert hunk',
+  blockUnstage: 'Unstage hunk',
+  fileUnstage: 'Unstage file',
+  blockActionsDirty: 'Save or discard editor changes before operating on this hunk.',
   blockDiscardBody: 'This block of {path} ({added} added, {deleted} deleted lines) is rolled back and the working-tree file rewritten to do it. This cannot be undone.',
   // The untracked case: the file's whole content is the one block, so rolling
   // the block back reverse-applies the new-file patch and DELETES the file —