@young1lin/dsh-ui-gitworkbench 0.1.4 → 0.1.6

package/src/client/locales.ts

@@ -22,10 +22,18 @@ export type WorkbenchKey =
   | 'aheadTitle' | 'behindTitle' | 'files'
   | 'filterFiles' | 'filterFilesPlaceholder' | 'filterFilesClear' | 'filesFiltered' | 'filterNoMatch'
   | 'drawerLabel' | 'totalsDim' | 'refresh' | 'close'
-  | 'tabsLabel' | 'tabChanges' | 'tabHistory' | 'tabCompare'
+  | 'tabsLabel' | 'tabChanges' | 'tabHistory' | 'tabCompare' | 'tabFiles'
+  // the Files tab: browse the repository, read a file, blame it, edit it
+  | 'fileSearchPlaceholder' | 'filesTruncated' | 'filesEmpty' | 'filesNoMatch' | 'filesPick'
+  | 'filesUnsavedAsk' | 'filesDiscardOpen' | 'filesMore' | 'filesVanished' | 'fileReadOnlyCrlf' | 'fileReadOnlyEncoding'
+  | 'blameWhileEditing' | 'blameLine' | 'blamePick' | 'blameInHistory' | 'paintTooLarge'
+  | 'imageBroken' | 'imageFit' | 'imageActual' | 'imageTooLarge' | 'imageSource' | 'imagePreview'
+  | 'prevChange' | 'nextChange' | 'prevChangeHint' | 'nextChangeHint' | 'changeCount'
   | 'sourceLabel' | 'workingTree'
   | 'loadingCommit' | 'renamedFrom' | 'binaryFile' | 'loadingDiff' | 'noTextDiff'
   | 'noCommits' | 'historyLabel' | 'historyEnd' | 'loading' | 'maximize' | 'restore'
+  // side-by-side diff pane: the two layer tabs, and the size-guard notice
+  | 'tabUnstaged' | 'tabStaged' | 'diffTooLarge'
   | 'commitAuthor' | 'commitCommitter' | 'commitDate' | 'historyFilterPlaceholder' | 'historyNoMatch'
   | 'filterClearAll' | 'filterBy' | 'filterUsers' | 'filterUserSearch' | 'filterAuthorsMore'
   | 'filterDate' | 'filterToday' | 'filterLast7' | 'filterLast30' | 'filterAfter' | 'filterBefore'
@@ -38,7 +46,7 @@ export type WorkbenchKey =
   | 'scopeProject' | 'scopeGlobal' | 'scopeGlobalHint' | 'scopeNoRepo'
   | 'bgNone' | 'bgChoose' | 'bgClear' | 'bgBlur' | 'bgVeil' | 'bgWorking' | 'bgFailed' | 'bgTooBig'
   | 'cssPlaceholder' | 'cssImport' | 'cssApply' | 'cssUnapplied' | 'styleFailed'
-  | 'resizeLabel' | 'resizeCommits' | 'resizeTree'
+  | 'resizeLabel' | 'resizeCommits' | 'resizeTree' | 'resizeSides'
   | 'expandAll' | 'collapseAll' | 'noBranch'
   | 'copyCommit' | 'copiedCommit'
   // write operations
@@ -48,11 +56,22 @@ export type WorkbenchKey =
   | '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.ok.discardFile'
+  | 'op.ok.discardFile' | 'op.ok.applyBlocks'
   | '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'
+  // 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)
+  | 'editFile' | 'fileSave' | 'fileRevert' | 'editingNotice' | 'crlfNotice' | 'encodingNotice'
+  // blame gutter on the working-tree column
+  | 'blameToggle' | 'blameHint' | 'blameUncommitted' | 'blameFailed' | 'blameTruncated'
+  | 'saveFailed' | 'saveUnavailable' | 'saveRetry'
+  | 'staleTitle' | 'staleBody' | 'staleReload' | 'staleOverwrite'
+  | 'unsavedTitle' | 'unsavedBody' | 'unsavedLeave' | 'unsavedStay'
   | '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'
+  | 'op.fail.nothing-to-commit' | 'op.fail.dirty' | 'op.fail.stale' | 'op.fail.invalid' | 'op.fail.unknown'
 
 export const zh: Record<WorkbenchKey, string> = {
   aheadTitle: '领先上游 {count} 个提交',
@@ -66,6 +85,25 @@ export const zh: Record<WorkbenchKey, string> = {
   tabChanges: '变更',
   tabHistory: '历史',
   tabCompare: '对比',
+  tabFiles: '文件',
+  fileSearchPlaceholder: '搜索文件…',
+  filesTruncated: '文件太多，列表已截断；用搜索找剩下的。',
+  filesEmpty: '这个仓库还没有文件',
+  filesNoMatch: '没有匹配的文件',
+  filesMore: '还有 {count} 个，用上面的搜索找',
+  filesPick: '从左边选一个文件打开',
+  filesVanished: '{path} 已不在仓库里（被删除、重命名，或者切到了没有它的分支）。',
+  filesUnsavedAsk: '有未保存的修改，打开其他文件会丢弃它们。',
+  filesDiscardOpen: '丢弃并打开',
+  // Read-only rather than withheld: in this view READING the file is the
+  // point, and only saving it back would rewrite bytes nobody touched.
+  fileReadOnlyCrlf: '这个文件的行尾是 CRLF，只能查看不能编辑（编辑器会把行尾统一成 LF，保存时整份文件都会被改写）。',
+  fileReadOnlyEncoding: '这个文件不是 UTF-8 编码，只能查看不能编辑：页面上的文字是一次有损解码，保存回去会改写每一个非 ASCII 字节。',
+  blameLine: '第 {line} 行',
+  paintTooLarge: '文件较长，已关闭语法上色（整文件上色每次要一秒以上，每次停手都卡一下比纯文本更难用）。编辑、保存、追溯不受影响。',
+  blameInHistory: '他在本文件的提交',
+  blamePick: '点左边的名字，看那一行是哪个提交改的',
+  blameWhileEditing: '正在编辑，追溯已暂时收起：改过的行号已经对不上它背后的提交。保存或放弃后会重新出现。',
   historyEnd: '已到最早的提交',
   loading: '加载中…',
   maximize: '最大化',
@@ -112,13 +150,30 @@ export const zh: Record<WorkbenchKey, string> = {
   resizeLabel: '拖动调整抽屉宽度',
   resizeCommits: '拖动调整提交列表宽度',
   resizeTree: '拖动调整文件树宽度',
+  resizeSides: '拖动调整左右两栏宽度',
   sourceLabel: '统计来源切换',
   workingTree: '工作区',
   loadingCommit: '加载提交…',
   renamedFrom: '重命名自',
   binaryFile: '二进制文件 —— 不显示文本 diff',
+  imageBroken: '浏览器无法解码这个图片文件（文件头对得上，但内容可能已损坏或被截断）。',
+  imageFit: '适应窗口',
+  imageActual: '实际大小',
+  imageTooLarge: '图片有 {size}，超过 {cap} 的预览上限。',
+  imageSource: '看源码',
+  imagePreview: '看图',
+  prevChange: '上一处变更',
+  nextChange: '下一处变更',
+  prevChangeHint: '上一处变更（Shift+F7）',
+  nextChangeHint: '下一处变更（F7）',
+  changeCount: '变更 {n} 处',
   loadingDiff: '加载 diff…',
   noTextDiff: '无文本差异',
+  // The side-by-side pane's layer tabs: unstaged is index→worktree, staged is
+  // HEAD→index — the two halves of what the old combined view showed at once.
+  tabUnstaged: '未暂存',
+  tabStaged: '已暂存',
+  diffTooLarge: '文件过大（超过 20000 行或 2 MB），已改用普通 diff 视图',
   noCommits: '无提交历史',
   historyLabel: '提交历史',
   commitAuthor: '作者',
@@ -193,6 +248,7 @@ export const zh: Record<WorkbenchKey, string> = {
   'op.ok.pull': '拉取完成',
   'op.ok.push': '推送成功',
   'op.ok.discardFile': '已撤回',
+  'op.ok.applyBlocks': '已应用',
   // The row action, and the dialog it opens. IDEA calls this Rollback and
   // means "take the file back to its committed state" — not "undo my last
   // edit", which is the editor's job and a different promise.
@@ -205,6 +261,43 @@ export const zh: Record<WorkbenchKey, string> = {
   discardBodyRestore: '{path} 将还原成上次提交时的样子。这里的 {added} 行新增、{deleted} 行删除无法找回。',
   discardBodyDelete: '{path} 从未被 git 记录过，删除后无法找回。',
   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: '取消暂存这块',
+  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 —
+  // the same consequence class the file-level delete wording exists to name.
+  blockDiscardBodyDelete: '{path} 从未被 git 记录过，这一块就是整个文件，撤回后文件将被删除，无法找回。',
+  // The editable right column: editing arms explicitly (never per keystroke —
+  // an autosave racing a concurrent agent write is the data-loss case), and
+  // every save carries the sha the editor opened with.
+  editFile: '编辑',
+  fileSave: '保存（Ctrl/Cmd+S）',
+  fileRevert: '放弃修改',
+  editingNotice: '正在编辑且未保存：保存前区块操作不可用；切走前（换页签、选其他文件、关闭抽屉）会先确认。',
+  // Why the edit affordance is withheld on a CRLF file: the editor control
+  // itself rewrites \r\n to \n, so any save would change every line ending.
+  blameToggle: 'Blame',
+  blameHint: '显示每一行最后是被谁、在哪个提交里改的',
+  blameUncommitted: '尚未提交',
+  blameFailed: '这个文件没有可追溯的历史（可能是未跟踪的新文件）。',
+  blameTruncated: '文件过长，追溯信息只显示了前面一部分。',
+  crlfNotice: '这个文件的行尾是 CRLF，暂不支持在线编辑（编辑框会把行尾统一成 LF，保存时整份文件都会被改写）；查看和按块暂存/撤回不受影响。',
+  encodingNotice: '这个文件不是 UTF-8 编码（可能是 GBK、Shift JIS 之类），暂不支持在线编辑：页面上看到的文字是一次有损解码，保存回去会把文件里每一个非 ASCII 字节都改写掉，包括你没动过的行。查看和按块暂存/撤回不受影响。',
+  saveFailed: '保存失败',
+  saveUnavailable: '当前宿主还不支持保存（需要重启 dsh web 加载新版宿主端）。',
+  saveRetry: '重试保存',
+  staleTitle: '这个文件在你编辑期间被修改了',
+  staleBody: '磁盘上的内容已不是编辑器打开时的那份（保存时会被拒绝，文件保持原样）。可以放弃你的修改重新加载，也可以用编辑器里的内容覆盖磁盘上的新版本。',
+  staleReload: '重新加载（丢弃修改）',
+  staleOverwrite: '用编辑器内容覆盖',
+  unsavedTitle: '有未保存的修改',
+  unsavedBody: '{path} 有未保存的修改，切换后将丢弃这些修改。',
+  unsavedLeave: '仍要切换',
+  unsavedStay: '继续编辑',
   'op.fail.auth': '认证失败。凭据提示已被禁用，请先在终端里配置好凭据再重试。',
   'op.fail.network': '网络不可达：主机名解析失败或连接不上。检查网络与远程地址后重试。',
   'op.fail.no-upstream': '当前分支没有上游分支。',
@@ -212,6 +305,8 @@ export const zh: Record<WorkbenchKey, string> = {
   'op.fail.conflict': '出现冲突，工作区已被改动。请在编辑器里解决冲突后继续。',
   'op.fail.nothing-to-commit': '暂存区是空的，没有可提交的内容。',
   'op.fail.dirty': '本地改动会被覆盖。先提交或暂存它们。',
+  'op.fail.stale': 'diff 已过期。',
+  'op.fail.invalid': '无效的操作。',
   'op.fail.unknown': '操作失败。',
 }
 
@@ -227,6 +322,23 @@ export const en: Record<WorkbenchKey, string> = {
   tabChanges: 'Changes',
   tabHistory: 'History',
   tabCompare: 'Compare',
+  tabFiles: 'Files',
+  fileSearchPlaceholder: 'Search files…',
+  filesTruncated: 'Too many files to list; use the search for the rest.',
+  filesEmpty: 'This repository has no files yet',
+  filesNoMatch: 'No matching files',
+  filesMore: 'and {count} more — use the search above',
+  filesPick: 'Pick a file on the left to open it',
+  filesVanished: '{path} is not in the repository any more — deleted, renamed, or on a branch that no longer has it.',
+  filesUnsavedAsk: 'You have unsaved edits; opening another file discards them.',
+  filesDiscardOpen: 'Discard and open',
+  fileReadOnlyCrlf: 'This file uses CRLF line endings, so it opens read-only (the editor normalises them to LF, and a save would rewrite every line).',
+  fileReadOnlyEncoding: 'This file is not UTF-8, so it opens read-only: the text shown is a lossy decode, and saving it back would rewrite every non-ASCII byte.',
+  blameLine: 'Line {line}',
+  paintTooLarge: 'This file is long, so syntax colouring is off (a full repaint costs over a second, and a freeze on every pause is worse than plain text). Editing, saving and blame are unaffected.',
+  blameInHistory: 'Their commits on this file',
+  blamePick: 'Click a name to see which commit changed that line',
+  blameWhileEditing: 'Blame is hidden while you type: edited line numbers no longer match the commits behind them. It returns once you save or revert.',
   historyEnd: 'Start of history',
   loading: 'Loading…',
   maximize: 'Maximize',
@@ -273,13 +385,28 @@ export const en: Record<WorkbenchKey, string> = {
   resizeLabel: 'Drag to resize the drawer',
   resizeCommits: 'Drag to resize the commit list',
   resizeTree: 'Drag to resize the file tree',
+  resizeSides: 'Drag to resize the two columns',
   sourceLabel: 'Switch stats source',
   workingTree: 'Working tree',
   loadingCommit: 'Loading commit…',
   renamedFrom: 'Renamed from',
   binaryFile: 'Binary file — no text diff',
+  imageBroken: 'The browser could not decode this image (the header checks out, so the file is probably damaged or truncated).',
+  imageFit: 'Fit',
+  imageActual: 'Actual size',
+  imageTooLarge: 'This image is {size}, past the {cap} preview limit.',
+  imageSource: 'Source',
+  imagePreview: 'Preview',
+  prevChange: 'Previous change',
+  nextChange: 'Next change',
+  prevChangeHint: 'Previous change (Shift+F7)',
+  nextChangeHint: 'Next change (F7)',
+  changeCount: 'changes: {n}',
   loadingDiff: 'Loading diff…',
   noTextDiff: 'No text changes',
+  tabUnstaged: 'Unstaged',
+  tabStaged: 'Staged',
+  diffTooLarge: 'File too large (over 20,000 lines or 2 MB) — showing the plain diff view',
   noCommits: 'No commit history',
   historyLabel: 'Commit history',
   commitAuthor: 'Author',
@@ -346,6 +473,7 @@ export const en: Record<WorkbenchKey, string> = {
   'op.ok.pull': 'Pulled',
   'op.ok.push': 'Pushed',
   'op.ok.discardFile': 'Rolled back',
+  'op.ok.applyBlocks': 'Applied',
   discardAction: 'Roll back changes',
   discardTitle: 'Roll back changes?',
   discardConfirm: 'Roll back',
@@ -353,6 +481,43 @@ export const en: Record<WorkbenchKey, string> = {
   discardBodyRestore: '{path} goes back to its committed content. The {added} added and {deleted} deleted lines here cannot be recovered.',
   discardBodyDelete: '{path} was never recorded by git. Deleting it cannot be undone.',
   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',
+  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 —
+  // the same consequence class the file-level delete wording exists to name.
+  blockDiscardBodyDelete: '{path} was never recorded by git, and this block is its whole content — rolling it back deletes the file. This cannot be undone.',
+  // The editable right column: editing arms explicitly (never per keystroke —
+  // an autosave racing a concurrent agent write is the data-loss case), and
+  // every save carries the sha the editor opened with.
+  editFile: 'Edit',
+  fileSave: 'Save (Ctrl/Cmd+S)',
+  fileRevert: 'Discard edits',
+  editingNotice: 'Editing with unsaved changes: block actions wait until the file is saved, and leaving first — another tab, another file, closing the drawer — asks.',
+  // Why the edit affordance is withheld on a CRLF file: the editor control
+  // itself rewrites \r\n to \n, so any save would change every line ending.
+  blameToggle: 'Blame',
+  blameHint: 'Show which commit last changed each line',
+  blameUncommitted: 'Not committed yet',
+  blameFailed: 'This file has no history to blame (it may be a new, untracked file).',
+  blameTruncated: 'The file is long, so blame is shown for the first part only.',
+  crlfNotice: 'This file has CRLF line endings, which the editor does not support yet (the edit box would turn every ending into LF, so a save rewrites the whole file); viewing and block staging/rolling back still work.',
+  encodingNotice: 'This file is not UTF-8 (GBK, Shift JIS or similar), so the editor is unavailable: the text shown is a lossy decode of it, and saving that back would rewrite every non-ASCII byte in the file, including lines you never touched. Viewing and block staging/rolling back still work.',
+  saveFailed: 'Save failed',
+  saveUnavailable: 'This host does not support saving yet — restart dsh web to load the new host half.',
+  saveRetry: 'Retry save',
+  staleTitle: 'This file changed while you were editing it',
+  staleBody: 'What is on disk is no longer what the editor opened (a save is refused and nothing written). Reload and lose your edits, or overwrite the newer file with what the editor holds.',
+  staleReload: 'Reload (discard my edits)',
+  staleOverwrite: 'Overwrite with my version',
+  unsavedTitle: 'Unsaved edits',
+  unsavedBody: '{path} has unsaved edits; switching now discards them.',
+  unsavedLeave: 'Switch anyway',
+  unsavedStay: 'Keep editing',
   '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.',
@@ -360,5 +525,7 @@ export const en: Record<WorkbenchKey, string> = {
   '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.stale': 'The diff is stale.',
+  'op.fail.invalid': 'Invalid operation.',
   'op.fail.unknown': 'The operation failed.',
 }

package/src/client/pane-size.ts

@@ -0,0 +1,71 @@
+/**
+ * How wide a dragged pane is allowed to be.
+ *
+ * A pane may grow only into space the others do not need, so the ceiling is
+ * the drawer minus its neighbour minus the floor under the diff. The part that
+ * broke is the word NEIGHBOUR: the History tab stacks the commit list across
+ * the top, where it is a sibling of the tree-and-diff row rather than a column
+ * beside the tree — and counting a full-drawer-wide list as the tree's
+ * neighbour makes the ceiling smaller than the floor. The tree then sits at its
+ * minimum whatever the pointer does, which reads as a divider that will not
+ * move.
+ *
+ * So the question is asked of the geometry instead of the tab: two boxes are
+ * neighbours when one actually ends where the other begins. That stays true if
+ * another tab is stacked later, and it cannot be got wrong by a rename.
+ *
+ * Pure: no React, no DOM — the caller measures, this decides.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/pane-size
+ */
+
+/** As much of a `DOMRect` as any of this needs. */
+export interface PaneBox {
+  readonly left: number
+  readonly right: number
+  readonly width: number
+}
+
+/** Sub-pixel tolerance: two boxes a third of a pixel apart are touching. */
+const EPSILON_PX = 1
+
+/**
+ * The width `other` contributes to a drag on `pane` — zero unless the two are
+ * side by side.
+ *
+ * @param other - the pane that might be in the way, or null when it is not on
+ *   screen at all.
+ * @param pane - the pane being dragged.
+ */
+export function neighbourWidth(other: PaneBox | null, pane: PaneBox | null): number {
+  if (other === null || pane === null) return 0
+  // Either order: whichever is on the left, they are neighbours only if one's
+  // trailing edge meets the other's leading edge. A box stacked above spans
+  // the same columns as the one below, so neither test holds.
+  const beside = other.right <= pane.left + EPSILON_PX || pane.right <= other.left + EPSILON_PX
+  return beside ? other.width : 0
+}
+
+/**
+ * Clamp a dragged width between the pane's floor and the room actually left.
+ *
+ * The outer `Math.max` keeps the range from inverting in a drawer too narrow to
+ * hold both floors — the pane then simply takes its minimum, rather than the
+ * clamp returning a number below it.
+ *
+ * @param next - the width the pointer implies.
+ * @param min - this pane's floor.
+ * @param drawer - the drawer's inner width.
+ * @param other - the neighbour's width, from {@link neighbourWidth}.
+ * @param minDiff - the floor under the diff, which is never dragged directly.
+ */
+export function clampPane(
+  next: number,
+  min: number,
+  drawer: number,
+  other: number,
+  minDiff: number,
+): number {
+  const max = Math.max(min, drawer - other - minDiff)
+  return Math.min(Math.max(next, min), max)
+}

package/src/client/side-edit.ts

@@ -0,0 +1,244 @@
+/**
+ * The editable right column's decision core: when a fetched layer payload may
+ * replace the editor buffer and when it must not, what a save's answer does to
+ * the buffer's basis, what "dirty" means, and what any gesture that would drop
+ * the buffer must ask first.
+ *
+ * The host's sha check is the hard wall between the editor and a concurrent
+ * agent write; these rules are everything the UI does around that wall. The
+ * one with teeth is {@link applySides}: a refresh that lands over a DIRTY
+ * buffer keeps the buffer and only notes whether the file moved underneath —
+ * the tree refreshes, the editor does not, which is what makes polling safe to
+ * leave running while somebody is typing.
+ *
+ * Pure: no React, no CSS, no git. `tests/side-edit.test.ts` loads it directly.
+ */
+
+/**
+ * `gitWorkbench/writeChecked`'s answer, mirrored from the host's `WriteResult`
+ * (the client re-declares host shapes rather than importing the host module,
+ * which pulls node and the RPC decorators).
+ */
+export interface WriteResult {
+  readonly ok: boolean
+  /** Present only on failure; `stale` is the sha refusal. */
+  readonly failure?: string
+  /** A sentence for the user; names the file on the stale path. */
+  readonly error?: string
+  /** The file's blob sha after a successful write, for the next save. */
+  readonly sha?: string
+}
+
+/** What a fetched layer payload contributes to the editor's basis. */
+export interface EditSides {
+  readonly targetText: string
+  readonly targetSha: string
+  /** Host's word that the working-tree file is not valid UTF-8. Optional so a
+   *  payload from a host half older than this client reads as "fine" rather
+   *  than as a refusal it cannot explain. */
+  readonly lossyEncoding?: boolean
+}
+
+/** The editable right column's whole state, minus transient banners. */
+export interface EditState {
+  /** Whether the right column is the editor at all (unstaged tab only). */
+  readonly armed: boolean
+  /** The editor's text — the only thing the user changes directly. */
+  readonly buffer: string
+  /** Blob sha the buffer is based on: `writeChecked`'s `expectedSha`. */
+  readonly baseSha: string
+  /** The text `baseSha` names; dirty is buffer against THIS, not the disk. */
+  readonly baseText: string
+  /** The file changed underneath (fresh targetSha !== baseSha) while dirty. */
+  readonly conflict: boolean
+}
+
+/** Before the first arm: nothing editable, no basis, nothing conflicting. */
+export const DISARMED: EditState = { armed: false, buffer: '', baseSha: '', baseText: '', conflict: false }
+
+/**
+ * Whether the buffer holds edits no save has landed yet.
+ *
+ * Dirty is measured against `baseText` — the text of the last save or load —
+ * not against what a poll says the disk holds: the poll's view is a snapshot
+ * old by up to one interval, and "the agent changed the file" is a different
+ * question from "you have unsaved edits".
+ */
+export function isDirty(edit: EditState): boolean {
+  return edit.armed && edit.buffer !== edit.baseText
+}
+
+/**
+ * Whether the editor may hold this payload's text: it must carry no carriage
+ * return.
+ *
+ * The HTML textarea value API normalises `\r\n` to `\n` the moment text
+ * enters it, so an armed CRLF file (an `core.autocrlf=true` checkout, or
+ * `eol=crlf`) would save ANY later edit with every line ending rewritten —
+ * a whole-file diff the reader never asked for. The first cut declines the
+ * edit rather than translate endings on the way out: the file stays viewable
+ * and the block actions keep working (they act on git's diff, not on the
+ * buffer); only the editor is withheld, with a notice saying why.
+ */
+export type ArmRefusal = 'encoding' | 'crlf'
+
+/**
+ * Why the editor is withheld for this payload, or null when it may arm.
+ *
+ * Two reasons, and the pane says WHICH: a reader shown one sentence for two
+ * different causes cannot tell whether converting line endings would help.
+ *
+ *   - `encoding` — the file is not UTF-8 (GBK, Shift JIS, Latin-1). The text
+ *     on screen is a lossy decode of it, so saving it back would replace every
+ *     non-ASCII byte in the file, including lines nobody touched. The host
+ *     refuses such a save too; this is what keeps the reader from reaching it.
+ *   - `crlf` — the text carries carriage returns. The textarea normalises
+ *     `{CR}{LF}` to `{LF}` the moment the text lands in it, so the next save
+ *     would rewrite every line ending in the file.
+ *
+ * Encoding is reported first: it is the more fundamental of the two, and its
+ * sentence is the one that tells the reader nothing here will help.
+ *
+ * Either way only the EDITOR is withheld — the diff still renders and the
+ * block actions still work, because those act on git's own diff rather than
+ * on the buffer.
+ */
+export function armRefusal(sides: EditSides): ArmRefusal | null {
+  if (sides.lossyEncoding === true) return 'encoding'
+  if (sides.targetText.includes('\r')) return 'crlf'
+  return null
+}
+
+export function editableSides(sides: EditSides): boolean {
+  return armRefusal(sides) === null
+}
+
+/** The adopt core: buffer and basis become the payload, conflict cleared. */
+function adopt(armed: boolean, sides: EditSides): EditState {
+  return { armed, buffer: sides.targetText, baseSha: sides.targetSha, baseText: sides.targetText, conflict: false }
+}
+
+/**
+ * Arm the editor from the payload currently on screen: the buffer starts as
+ * the working-tree text, and the first save is checked against its sha.
+ * A payload {@link editableSides} refuses is handed back unchanged — the
+ * caller shows the notice instead of an editor.
+ */
+export function armEdit(edit: EditState, sides: EditSides): EditState {
+  return editableSides(sides) ? adopt(true, sides) : edit
+}
+
+/**
+ * A fetched payload lands over the editor.
+ *
+ * Clean (or disarmed): adopt — the editor follows the file, so the drawer
+ * keeps up with the agent exactly as it did before editing existed, and an
+ * armed editor whose file turned CRLF underneath disarms with the payload
+ * adopted (clean costs no edits, and an armed editor must never hold text
+ * the textarea would normalise). Dirty: keep the buffer whatever the payload
+ * says (a poll must never overwrite unsaved edits) and record whether the
+ * file itself moved, which is what the reload-and-lose-edits banner keys on.
+ * An index-only change (same targetSha) leaves the flag down: the diff moved,
+ * the edited file did not.
+ */
+export function applySides(edit: EditState, sides: EditSides): EditState {
+  if (!isDirty(edit)) {
+    return adopt(edit.armed && editableSides(sides), sides)
+  }
+  return { ...edit, conflict: sides.targetSha !== edit.baseSha }
+}
+
+/**
+ * The banner's reload action, on the user's explicit say-so: drop the edits
+ * onto the fresh text with a clean, current basis — and disarmed when the
+ * fresh text carries CRLF, for the same reason arming refuses it.
+ */
+export function reloadSides(edit: EditState, sides: EditSides): EditState {
+  return adopt(editableSides(sides), sides)
+}
+
+/**
+ * Another file or layer selected: the edit session belonged to what was on
+ * screen, so the editor disarms and adopts the new payload from scratch.
+ */
+export function resetSides(edit: EditState, sides: EditSides): EditState {
+  return adopt(false, sides)
+}
+
+/** The drawer-level unsaved-edits guard's state. */
+export interface LeaveGuard {
+  /** The pane's last dirty report — the pane is this flag's only writer. */
+  readonly dirty: boolean
+  /** Whether the unsaved-edits dialog is holding a deferred gesture. */
+  readonly askOpen: boolean
+}
+
+/** No edits, no open ask: the guard at rest. */
+export const LEAVE_GUARD_CLEAR: LeaveGuard = { dirty: false, askOpen: false }
+
+/** What a gesture that would drop the editor's surface should do. */
+export type LeaveGate = { readonly kind: 'run' } | { readonly kind: 'ask' } | { readonly kind: 'wait' }
+
+/**
+ * Decide a leave gesture — a layer tab, a file selection, the drawer's close,
+ * a main-tab switch — against unsaved edits.
+ *
+ * `same` names a gesture whose target is what the pane already shows: the
+ * already-active tab, the tree row of the file already rendered. Such a
+ * gesture changes nothing the pane renders and discards nothing, so it runs
+ * without asking — a dialog over it would promise "switching discards your
+ * edits" and then discard nothing, and a Leave answer on it used to disarm
+ * the guard entirely. For a real target: `run` acts now, `ask` opens the
+ * unsaved-edits dialog (Stay keeps editing, Leave drops), `wait` does
+ * nothing because an ask is already open — a second gesture waits on the
+ * first's answer rather than stacking a dialog on it.
+ */
+export function gateLeave(guard: LeaveGuard, same: boolean): LeaveGate {
+  if (same) return { kind: 'run' }
+  if (!guard.dirty) return { kind: 'run' }
+  return guard.askOpen ? { kind: 'wait' } : { kind: 'ask' }
+}
+
+/** An ask opened: the gesture is held for the dialog's answer. */
+export function leaveAsked(guard: LeaveGuard): LeaveGuard {
+  return { ...guard, askOpen: true }
+}
+
+/**
+ * The dialog answered — Leave or Stay, both close the ask — and the dirty
+ * flag is deliberately NOT touched.
+ *
+ * The pane is the flag's only writer: a genuine navigation routes through
+ * `resetSides`, whose clean transition is what reports false, while a no-op
+ * gesture leaves the pane armed and dirty and the guard correctly still
+ * armed for the next one. Clearing the flag here — on the guess that "Leave
+ * means the buffer went away" — is exactly what let a Leave confirmed on a
+ * no-op gesture disarm the guard for every gesture after it.
+ */
+export function leaveAnswered(guard: LeaveGuard): LeaveGuard {
+  return { ...guard, askOpen: false }
+}
+
+/** The pane reports its dirty flag — the one transition that writes it. */
+export function paneDirtyReport(guard: LeaveGuard, dirty: boolean): LeaveGuard {
+  return { ...guard, dirty }
+}
+
+/**
+ * A successful `writeChecked`: the basis becomes the saved text and the sha
+ * the host read back. The buffer is NOT touched — typing that landed while
+ * the write was in flight stays dirty against the new basis, so it stays
+ * visible as unsaved rather than being silently declared written.
+ */
+export function applySaveOk(edit: EditState, savedText: string, sha: string): EditState {
+  return { ...edit, baseSha: sha, baseText: savedText, conflict: false }
+}
+
+/**
+ * A refused save (`failure: 'stale'`): the buffer stands, the banner goes up.
+ * The reload/overwrite the banner offers reads the fresh sha off the next
+ * fetch, not off this refusal.
+ */
+export function markConflict(edit: EditState): EditState {
+  return { ...edit, conflict: true }
+}