dsh-remote-vs 0.8.9 → 0.9.0

package/lib/types/client/CodeEditor.d.ts

@@ -23,7 +23,18 @@ export interface CodeEditorViewState {
 export interface CodeEditorHandle {
     getContent: () => string;
     isDirty: () => boolean;
-    markSaved: () => void;
+    /**
+     * Advance the dirty baseline to the bytes a save just wrote to the remote
+     * file, and re-derive the dirty flag from the LIVE buffer against them.
+     *
+     * Takes the saved text explicitly because the user may have typed while the
+     * remote write was in flight: the buffer is then NEWER than the file, and
+     * declaring it saved would be the same silent-loss bug in the other
+     * direction. `tabId` guards against the pane having switched to another tab
+     * while the save awaited — marking that editor saved would corrupt ITS
+     * baseline.
+     */
+    markSaved: (savedText: string, tabId: string) => void;
     /** Snapshot scroll + selection, for restoring after a remount. */
     getViewState: () => CodeEditorViewState | undefined;
     /** Scroll back and put the caret where it was. */
@@ -120,6 +131,21 @@ export declare const CodeEditor: import("react").ForwardRefExoticComponent<{
      * where a file was when its tab is re-selected.
      */
     viewState?: CodeEditorViewState;
+    /**
+     * The text as it was last LOADED from / SAVED to the remote file — the dirty
+     * baseline.
+     *
+     * Separate from `initial` because a tab switch or a surface flip remounts the
+     * editor with the LIVE buffer as `initial` (that is how unsaved edits survive
+     * the remount), while the file on disk is still the older `savedText`. Using
+     * `initial` as the baseline would declare the unsaved text clean: the dirty
+     * dot and status would lie, the close guard would stop prompting and Save
+     * would disable — a silent way to lose the very edits the handoff preserved.
+     *
+     * Absent (diff panes, older callers): the mount's own document is the
+     * baseline, which is the historical behaviour.
+     */
+    savedText?: string;
     onSave: () => void;
     onDirty: (dirty: boolean) => void;
 } & import("react").RefAttributes<CodeEditorHandle>>;

package/lib/types/client/FloatingEditorWindow.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The floating editor window: the plugin's ONE editor pane hosted in a
+ * draggable, resizable frame above the app shell.
+ *
+ * It is mounted by the client entry into the host's frame-wide overlay slot
+ * (`shell.overlay`) and reads the same module-level store as every other
+ * surface, so tabs / previews / diffs / find / change marks / undo / @file are
+ * not a re-implementation: this file only owns the FRAME (position, size,
+ * z-order, drag + resize + zoom) and the handoff around the mount swap.
+ *
+ * The mount is exclusive: `EditorPane` must exist exactly once, so the centre
+ * conversation view and the sidebar fallback render a placeholder while
+ * `editorSurface === 'float'` (see `FloatingEditorPlaceholder`).
+ */
+import { type ReactNode } from 'react';
+import type { Context } from '@deepseek-ai/cordis';
+/** The window frame plus the editor. `ctx` is only needed for the boot hook. */
+export declare function FloatingEditorWindow(props: {
+    ctx: Context;
+}): ReactNode;

package/lib/types/client/FloatingPlaceholder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What the centre conversation view and the sidebar fallback show while the
+ * editor is popped out: the editor itself is a single instance and lives in the
+ * floating window, so these surfaces must not mount a second one (that would
+ * be two live CodeMirror buffers for one tab — the exact defect `EditorPane`'s
+ * header warns about). A dock button keeps the surface from looking broken.
+ */
+import type { ReactNode } from 'react';
+export declare function FloatingEditorPlaceholder(): ReactNode;

package/lib/types/client/RemoteEditorView.d.ts

@@ -6,6 +6,10 @@
  * sidebar then keeps the whole column for the explorer. Both surfaces read
  * the same module-level store, so a diff opened from source control appears
  * here, and a save here repaints the sidebar's change list.
+ *
+ * While the editor floats (`editorSurface === 'float'`) this tab is NOT the
+ * editor's mount any more, so it renders a placeholder instead: mounting a
+ * second `EditorPane` would give the same tab two live buffers.
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { ReactNode } from 'react';

package/lib/types/client/float-editor.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Pure geometry and surface rules for the floating editor.
+ *
+ * Kept free of React and of the DOM on purpose: the drag / resize / zoom maths
+ * is the part that is easy to get subtly wrong (negative sizes, a window that
+ * escapes the viewport, a stale stored rect from a larger screen), and this
+ * module is what `scripts/check-float-editor.mjs` drives directly. The window
+ * component is then only wiring.
+ *
+ * The SURFACE rule lives here too: the plugin has exactly one live editor, and
+ * which mount owns it is a three-way decision (centre conversation view,
+ * sidebar fallback, floating window). Encoding it as a pure function keeps the
+ * invariant testable and out of three separate `=== 'center'` comparisons.
+ */
+/** Where the editor pane is mounted right now. */
+export type EditorSurface = 'center' | 'sidebar' | 'float';
+/** The persisted layout of the floating window, in viewport pixels. */
+export interface FloatRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Viewport size the geometry is clamped to. */
+export interface FloatViewport {
+    width: number;
+    height: number;
+}
+/** A resize grip: the compass directions of the eight handles. */
+export type FloatResizeHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/** Smallest window the editor can be squeezed into and stay usable. */
+export declare const FLOAT_MIN_WIDTH = 360;
+export declare const FLOAT_MIN_HEIGHT = 220;
+/** Height of the title bar; a minimized window keeps exactly this much. */
+export declare const FLOAT_TITLEBAR_HEIGHT = 34;
+/** Gap a maximized window keeps from the viewport edges. */
+export declare const FLOAT_VIEWPORT_EDGE = 8;
+/** Editor font-size range for Ctrl+wheel zoom (px). */
+export declare const FLOAT_FONT_MIN = 9;
+export declare const FLOAT_FONT_MAX = 28;
+export declare const FLOAT_FONT_DEFAULT = 13;
+/** Diameter of the minimized ball, in pixels. */
+export declare const FLOAT_BALL_SIZE = 44;
+/**
+ * How far a pointer may travel and still count as a CLICK: the minimized window
+ * is a single 44px ball, so "click restores / drag moves" has to be decided
+ * from one pointer gesture.
+ */
+export declare const FLOAT_BALL_CLICK_SLOP = 4;
+/** A point in viewport coordinates (the minimized ball's origin). */
+export interface FloatPoint {
+    x: number;
+    y: number;
+}
+/** The effective editor surface: floating wins, otherwise the base mount. */
+export declare function effectiveEditorSurface(base: 'center' | 'sidebar', floatOpen: boolean): EditorSurface;
+/**
+ * The rect a fresh floating window opens at: about two thirds of the frame,
+ * centred, with a hard size cap so a 4K monitor does not produce a 2600px
+ * editor for a 40-column file.
+ */
+export declare function defaultFloatRect(viewport: FloatViewport): FloatRect;
+/**
+ * Bring a rect back inside the viewport and to a legal size.
+ *
+ * Used on every drag step, on restore, and whenever the browser window is
+ * resized: a rect persisted on a 2560px screen must not open a window whose
+ * title bar is off-screen on a 1366px laptop.
+ */
+export declare function clampFloatRect(rect: FloatRect, viewport: FloatViewport): FloatRect;
+/** Move the window by a pointer delta, staying inside the viewport. */
+export declare function dragFloatRect(start: FloatRect, dx: number, dy: number, viewport: FloatViewport): FloatRect;
+/**
+ * Resize from one grip.
+ *
+ * Each axis is adjusted from the edge that MOVED (west/north resize changes the
+ * origin too), then clamped: the minimum size is anchored at the opposite edge
+ * (so dragging the north grip past the bottom stops instead of flipping the
+ * rect) and no edge may leave the viewport.
+ */
+export declare function resizeFloatRect(start: FloatRect, handle: FloatResizeHandle, dx: number, dy: number, viewport: FloatViewport): FloatRect;
+/** The rect a maximized window occupies: the frame minus a small margin. */
+export declare function maximizeFloatRect(viewport: FloatViewport): FloatRect;
+/**
+ * Parse a persisted rect.
+ *
+ * Anything malformed is discarded rather than repaired into a guess: the
+ * caller then opens the default rect. Values that are merely STALE (a rect from
+ * another screen) are legal input and get clamped.
+ */
+export declare function parseFloatRect(raw: string | null | undefined, viewport: FloatViewport): FloatRect | undefined;
+/** Serialize a rect for localStorage. */
+export declare function serializeFloatRect(rect: FloatRect): string;
+/**
+ * One Ctrl+wheel step: up (negative deltaY) grows the text, down shrinks it.
+ * Values are whole pixels so the stored size stays stable across sessions.
+ */
+export declare function stepFloatZoom(current: number, deltaY: number): number;
+/** Parse the persisted editor font size (fallback = the default 13px). */
+export declare function parseFloatFontSize(raw: string | null | undefined): number;
+/**
+ * Where the minimized ball may sit: fully on screen, whatever position was
+ * asked for (a ball restored on a smaller monitor must stay clickable).
+ */
+export declare function clampBallPosition(pos: FloatPoint, viewport: FloatViewport): FloatPoint;
+/**
+ * The ball's default spot when a window is minimized: its own top-left corner,
+ * so the ball appears where the window was instead of jumping to a corner.
+ */
+export declare function ballFromRect(rect: FloatRect, viewport: FloatViewport): FloatPoint;
+/**
+ * Whether a finished gesture was a CLICK rather than a drag.
+ *
+ * The minimized window is one small target with two actions on the same
+ * pointer: a press that never really moved restores the window, a real drag
+ * moves the ball. Without this distinction every move-by-3px would also
+ * restore, and every click would be a zero-distance drag.
+ */
+export declare function isBallClick(dx: number, dy: number): boolean;
+/** Parse a persisted ball position (stale geometry is clamped, garbage dropped). */
+export declare function parseBallPosition(raw: string | null | undefined, viewport: FloatViewport): FloatPoint | undefined;
+/** Serialize a ball position for localStorage. */
+export declare function serializeBallPosition(pos: FloatPoint): string;

package/lib/types/client/float-tab-trigger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Double-click on the shell's 「远程编辑器」 tab floats the editor.
+ *
+ * That tab belongs to the host's conversation-view header, not to us: the plugin
+ * registers a VIEW into the shell's tab strip and never sees the tab row's DOM.
+ * There is no public service for "the user double-clicked my tab" either, so the
+ * only way to honour the gesture is a document-level `dblclick` listener that
+ * recognises the tab the same way `reveal.ts` does for clicks — by its label,
+ * skipping our own surfaces.
+ *
+ * Fail-safe by construction: a miss (another host build, a renamed tab, a
+ * double-click somewhere else) simply does nothing. It never prevents the
+ * default action, never throws, and does not steal double-clicks from the
+ * plugin's own UI (`.rvs-root`) or from dialogs.
+ */
+/**
+ * Install the double-click trigger.
+ *
+ * @param label - the tab's visible label (the same localized string the view
+ *   registered with); matched against the tab's trimmed text.
+ * @param onTrigger - called once per recognised double-click.
+ * @returns disposer removing the listener.
+ */
+export declare function installFloatTabTrigger(label: string, onTrigger: () => void): () => void;

package/lib/types/client/live-editor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Handoff for the ONE live editor buffer when its mount is replaced.
+ *
+ * The plugin mounts exactly one `EditorPane` at a time (centre conversation
+ * view, sidebar fallback, or the floating window), and `CodeEditor` reads its
+ * `initial` text once on mount. So moving the editor between surfaces is
+ * effectively a remount: without a handoff the buffer typed since the last
+ * load is gone and the tab's stored text is the pre-edit one.
+ *
+ * This module is the handoff, and it is module-level for the same reason the
+ * store is: `EditorPane` is unmounted before the replacement mounts, so no
+ * React state survives the swap.
+ *
+ * Two things travel, and they are captured SEPARATELY because their costs
+ * differ by orders of magnitude:
+ *   - the buffer text (the store copies it onto the tab before the surface
+ *     flips, so the replacement mounts with it as `initial`) — materializes the
+ *     whole document, so it is taken only when the tab may differ from disk;
+ *   - scroll + caret (kept here and read back by the replacement, which is how
+ *     a tab switch already restored its position — same storage, now shared by
+ *     every surface instead of one component's `useRef`) — cheap, taken on
+ *     every switch.
+ */
+import type { CodeEditorHandle, CodeEditorViewState } from './CodeEditor.tsx';
+/**
+ * Register the editor that is on screen right now.
+ *
+ * The caller passes a getter, not a handle: `editorRef.current` is `null`
+ * during the first render and is cleared before the parent's cleanup runs, so
+ * a snapshot taken later must read through the getter.
+ * @returns disposer; only the registration that is still current is cleared.
+ */
+export declare function registerLiveEditor(tabId: string, getHandle: () => CodeEditorHandle | null): () => void;
+/**
+ * Snapshot the live position (scroll + caret) without touching the document.
+ *
+ * Cheap, so the store can call it on EVERY switch: a surface flip remounts the
+ * very same tab, and the replacement's render happens before the old view's
+ * unmount report — the position has to be in the map before that render.
+ */
+export declare function captureLiveEditorPosition(): void;
+/**
+ * Whether the live buffer differs from its disk baseline.
+ *
+ * The store uses this to skip the O(document) text copy on clean tabs (see
+ * `captureLiveBuffer`): the boolean is cheap, `getContent()` materializes the
+ * whole file as a string.
+ */
+export declare function isLiveEditorDirty(): boolean;
+/**
+ * Copy the live buffer's text, for a switch that would otherwise lose it.
+ *
+ * Called from the store BEFORE the tab switch / surface flip: at that moment
+ * the editor is still mounted and its CodeMirror view still owns the edits.
+ * @returns undefined when no file editor is live (a diff tab, or a view that
+ *   was never the selected one) — there is nothing to carry over then.
+ */
+export declare function captureLiveEditorText(): {
+    tabId: string;
+    text: string;
+} | undefined;
+/**
+ * Whether one tab's file editor is the one registered right now.
+ *
+ * The save path asks this before it clears a tab's dirty flag: if an editor IS
+ * mounted for that tab, the flag belongs to the live buffer and only the
+ * editor may clear it (see `markLiveEditorSaved`).
+ */
+export declare function isLiveEditorFor(tabId: string): boolean;
+/**
+ * Advance the registered editor's dirty baseline to the bytes a save wrote.
+ *
+ * Routed through the MODULE-LEVEL registration rather than a React ref on
+ * purpose: the pane can be remounted while the remote write is in flight (a
+ * surface flip, a dock, a tab switch), and the ref the save started with is
+ * then detached — that is exactly how a tab ended up reported clean while its
+ * live buffer was newer than the file. The registration always names the editor
+ * mounted NOW, so the correction lands on whichever instance is on screen, and
+ * it is skipped (never misapplied) when that editor shows another tab: that tab
+ * heals on its next mount from `savedText` (see `CodeEditor`).
+ * @returns true when an editor for this tab took the new baseline.
+ */
+export declare function markLiveEditorSaved(tabId: string, savedText: string): boolean;
+/** Remember one tab's scroll + caret (reported by the editor, see EditorPane). */
+export declare function rememberEditorViewState(tabId: string, state: CodeEditorViewState): void;
+/** The stored position for one tab, or undefined when it was never seen. */
+export declare function editorViewStateOf(tabId: string): CodeEditorViewState | undefined;
+/**
+ * Drop positions of tabs that no longer exist.
+ *
+ * The map used to live in a component with the same cleanup: without it a
+ * long session accumulated one state object per file ever opened.
+ */
+export declare function pruneEditorViewStates(liveIds: ReadonlySet<string>): void;

package/lib/types/client/store.d.ts

@@ -5,6 +5,7 @@ import { type StatusBuckets, type TreeMarks } from './scm/status-map.ts';
 import { type DiffPayload } from './scm/actions.ts';
 import { type DirExpansions } from './scm/untracked-dirs.ts';
 import { type Lang } from './i18n.ts';
+import { type EditorSurface } from './float-editor.ts';
 /** One editor tab (code file, preview or diff). */
 export interface EditorTab {
     id: string;
@@ -17,6 +18,16 @@ export interface EditorTab {
     error: string | undefined;
     /** File payload. */
     text: string;
+    /**
+     * The text as last LOADED from / SAVED to the remote file.
+     *
+     * `text` is the live-buffer handoff copy (see `captureLiveBuffer`) and may
+     * therefore hold unsaved edits; this is the disk-side reference the editor
+     * uses as its dirty baseline. Without the split, a remount with the handoff
+     * text would label unsaved edits "clean" (dirty dot off, Save disabled, close
+     * guard silent) — the exact silent-loss path the handoff exists to avoid.
+     */
+    baseline?: string;
     dirty: boolean;
     saving: boolean;
     binary: boolean;
@@ -144,7 +155,10 @@ export interface ExplorerValue {
     activeTab: EditorTab | undefined;
     activeTabId: string | undefined;
     revision: number;
-    editorSurface: 'center' | 'sidebar';
+    /** Effective editor mount: the floating window wins over the base surface. */
+    editorSurface: EditorSurface;
+    floatOpen: boolean;
+    floatAvailable: boolean;
     view: RailView;
     searchRequest: SearchRequest | undefined;
     /** Pending "show this folder in the tree" request (consumed by the explorer). */
@@ -199,6 +213,21 @@ export interface ExplorerValue {
     openFile: (fullPath: string, options?: {
         line?: number;
     }) => void;
+    /**
+     * 「在悬浮编辑器中打开」：把编辑器整体浮出，再打开这个文件。
+     *
+     * 先捕获当前编辑器缓冲区再切表面（见 `captureLiveBuffer`）：主界面里没保存
+     * 的编辑不会因为这次切换丢掉。
+     */
+    openInFloatEditor: (fullPath: string, options?: {
+        line?: number;
+    }) => void;
+    /** 同上，只是打开的是工作区 diff（SCM 更改列表的悬浮入口）。 */
+    openDiffInFloatEditor: (rel: string, staged: boolean, untracked?: boolean) => void;
+    /** 把当前编辑器整体浮出（双击会话视图的「远程编辑器」标签）。 */
+    openFloatingEditor: () => void;
+    /** 停靠回主界面（底层的中心视图或侧栏表面）。 */
+    dockFloatingEditor: () => void;
     openDiff: (rel: string, staged: boolean, untracked?: boolean) => void;
     openCommitFile: (hash: string, rel: string) => void;
     activateTab: (id: string) => void;
@@ -215,7 +244,12 @@ export interface ExplorerValue {
      * `changeSet.marks`，`hunk` 是 `patches` 的下标）。
      */
     undoChange: (tabId: string, mark: ChangeMark) => Promise<void>;
-    saveTab: (id: string, content: string) => Promise<void>;
+    /**
+     * Write one file tab back to the remote host.
+     * @returns true only when the write really succeeded — the caller uses it to
+     *   advance the editor's dirty baseline (see `CodeEditorHandle.markSaved`).
+     */
+    saveTab: (id: string, content: string) => Promise<boolean>;
     reloadTab: (id: string) => Promise<void>;
     info: (text: string) => void;
     fail: (text: string) => void;
@@ -438,8 +472,16 @@ export declare function remoteOpenBindings(): {
 export declare function openRemoteFileInBinding(bindingId: string, remotePath: string, options?: {
     line?: number;
 }): boolean;
-/** Whether the editor tab is mounted in the centre conversation view. */
-export declare function isEditorCentered(): boolean;
+/**
+ * Whether the plugin's own rich editor is the place a remote file click should
+ * land (the click interceptor's gate, see `remote-file-open.ts`).
+ *
+ * The centre conversation view is the normal case; while the editor floats it
+ * is the floating window instead — the file still belongs in OUR editor, not in
+ * the host's native preview. On the sidebar-fallback layout (`sidebar`) the
+ * interceptor stays off, exactly as before this feature.
+ */
+export declare function isEditorTakeoverActive(): boolean;
 /** Open (or focus) a working-tree diff of one repository path. */
 export declare function openDiff(rel: string, staged: boolean, untracked?: boolean): void;
 /** Open (or focus) one file of one commit (`ref^` against `ref`). */
@@ -447,8 +489,8 @@ export declare function openCommitFile(hash: string, rel: string): void;
 export declare function activateTab(id: string): void;
 export declare function closeTab(id: string): void;
 export declare function updateTab(id: string, next: Partial<EditorTab>): void;
-/** Write one tab back to the remote host. */
-export declare function saveTab(id: string, content: string): Promise<void>;
+/** Write one tab back to the remote host. @returns true when the write landed. */
+export declare function saveTab(id: string, content: string): Promise<boolean>;
 /**
  * Re-read one tab (file content or diff payload).
  *
@@ -470,6 +512,53 @@ export declare function saveTab(id: string, content: string): Promise<void>;
 export declare function reloadTab(id: string): Promise<void>;
 /** Note where the editor pane is mounted (set by the client entry). */
 export declare function setEditorSurface(surface: 'center' | 'sidebar'): void;
+/**
+ * Record that the host's frame-wide overlay slot actually rendered the
+ * floating window host (see `FloatingEditorWindow`).
+ *
+ * This is a runtime handshake, not a configuration flag: on a host whose
+ * `shell.overlay` slot is missing, the entry never mounts and the menu entries
+ * stay disabled instead of opening a surface that cannot paint.
+ */
+export declare function setFloatEditorAvailable(available: boolean): void;
+/**
+ * Float the editor in its current state, without opening anything.
+ *
+ * The entry is a double-click on the shell's 「远程编辑器」 tab (see
+ * `float-tab-trigger.ts`): the user is already looking at the editor and wants
+ * it out of the layout — no file, no diff, same tabs and buffers.
+ *
+ * Idempotent: while the editor already floats this does nothing (the window is
+ * on screen; a second trigger must not restart it).
+ */
+export declare function openFloatingEditor(): void;
+/**
+ * Open one file in the floating editor (file-tree / search / SCM menu action).
+ *
+ * Order matters twice:
+ *   1. the live buffer is captured BEFORE the surface flips (the flip unmounts
+ *      the editor that owns it);
+ *   2. a second capture runs even when already floating, because opening
+ *      another file is a tab switch — the very action that remounts the editor
+ *      and would otherwise drop the edits typed in the tab being left.
+ * A host whose overlay slot is unavailable gets the file in the normal surface
+ * instead (with the reason toasted), so the click is never a dead end.
+ */
+export declare function openInFloatEditor(fullPath: string, options?: {
+    line?: number;
+}): void;
+/**
+ * The floating variant of `openDiff` — the SCM change list's entry.
+ *
+ * Same handoff order as `openInFloatEditor`; a diff tab has no text buffer of
+ * its own, but the file editor that WAS on screen still does.
+ */
+export declare function openDiffInFloatEditor(rel: string, staged: boolean, untracked?: boolean): void;
+/**
+ * Dock the editor back onto its base surface (centre conversation view or the
+ * sidebar fallback), carrying the live buffer with it.
+ */
+export declare function dockFloatingEditor(): void;
 /**
  * 换一份「本会话改了什么」的标记。
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-remote-vs",
   "description": "VSCode-style remote development for DSH: SSH host manager (key/password), helper deploy pipeline with version check, remote file explorer + editor + terminal in dsh-better-sidebar.",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "icon": "icon.svg",
   "keywords": [
     "dsh",

package/src/client/CodeEditor.tsx

@@ -60,7 +60,18 @@ export interface CodeEditorViewState {
 export interface CodeEditorHandle {
   getContent: () => string
   isDirty: () => boolean
-  markSaved: () => void
+  /**
+   * Advance the dirty baseline to the bytes a save just wrote to the remote
+   * file, and re-derive the dirty flag from the LIVE buffer against them.
+   *
+   * Takes the saved text explicitly because the user may have typed while the
+   * remote write was in flight: the buffer is then NEWER than the file, and
+   * declaring it saved would be the same silent-loss bug in the other
+   * direction. `tabId` guards against the pane having switched to another tab
+   * while the save awaited — marking that editor saved would corrupt ITS
+   * baseline.
+   */
+  markSaved: (savedText: string, tabId: string) => void
   /** Snapshot scroll + selection, for restoring after a remount. */
   getViewState: () => CodeEditorViewState | undefined
   /** Scroll back and put the caret where it was. */
@@ -190,6 +201,21 @@ export const CodeEditor = forwardRef<CodeEditorHandle, {
    * where a file was when its tab is re-selected.
    */
   viewState?: CodeEditorViewState
+  /**
+   * The text as it was last LOADED from / SAVED to the remote file — the dirty
+   * baseline.
+   *
+   * Separate from `initial` because a tab switch or a surface flip remounts the
+   * editor with the LIVE buffer as `initial` (that is how unsaved edits survive
+   * the remount), while the file on disk is still the older `savedText`. Using
+   * `initial` as the baseline would declare the unsaved text clean: the dirty
+   * dot and status would lie, the close guard would stop prompting and Save
+   * would disable — a silent way to lose the very edits the handoff preserved.
+   *
+   * Absent (diff panes, older callers): the mount's own document is the
+   * baseline, which is the historical behaviour.
+   */
+  savedText?: string
   onSave: () => void
   onDirty: (dirty: boolean) => void
 }>(function CodeEditor(props, ref) {
@@ -402,14 +428,23 @@ export const CodeEditor = forwardRef<CodeEditorHandle, {
   useImperativeHandle(ref, () => ({
     getContent: () => viewRef.current?.state.doc.toString() ?? savedRef.current,
     isDirty: () => dirtyRef.current,
-    markSaved: () => {
+    markSaved: (savedText, tabId) => {
       const view = viewRef.current
-      if (view !== undefined) {
-        savedRef.current = view.state.doc.toString()
-        savedDocRef.current = view.state.doc
+      if (view === undefined) return
+      // The pane may have switched tabs while the save was in flight; this
+      // editor is then a different file and must not adopt the other tab's
+      // baseline.
+      if (propsRef.current.tabId !== tabId) return
+      // The written bytes themselves: no document copy needed (this string came
+      // from the caller's own `getContent`, or from the tab's baseline).
+      savedRef.current = savedText
+      const saved = EditorState.create({ doc: savedText }).doc
+      savedDocRef.current = saved
+      const dirty = view.state.doc !== saved && !view.state.doc.eq(saved)
+      if (dirty !== dirtyRef.current) {
+        dirtyRef.current = dirty
+        propsRef.current.onDirty(dirty)
       }
-      dirtyRef.current = false
-      propsRef.current.onDirty(false)
     },
     getViewState: () => {
       const view = viewRef.current
@@ -459,6 +494,34 @@ export const CodeEditor = forwardRef<CodeEditorHandle, {
     viewRef.current?.requestMeasure()
   }, [props.visible])
 
+  /**
+   * A save that landed AFTER this editor mounted.
+   *
+   * The save path moves the tab's `baseline` (the bytes now on disk) and asks
+   * the live editor to re-derive its dirty flag. That works while the same
+   * instance is mounted, but the pane can be remounted while the remote write
+   * is in flight (a surface flip, a dock, a tab switch): the replacement
+   * derives against the baseline it saw at MOUNT, and the corrected value only
+   * arrives later as a prop. Without this effect the tab keeps the `dirty:false`
+   * the save optimistically wrote, while the buffer holds newer text — dot off,
+   * Save disabled, close guard silent. Re-derive, never touch the document.
+   */
+  useEffect(() => {
+    const view = viewRef.current
+    const savedText = props.savedText
+    if (view === undefined || savedText === undefined) return
+    const baseline = EditorState.create({ doc: savedText }).doc
+    const previous = savedDocRef.current
+    if (previous !== undefined && previous.eq(baseline)) return
+    savedDocRef.current = baseline
+    savedRef.current = savedText
+    const dirty = view.state.doc !== baseline && !view.state.doc.eq(baseline)
+    if (dirty !== dirtyRef.current) {
+      dirtyRef.current = dirty
+      propsRef.current.onDirty(dirty)
+    }
+  }, [props.savedText])
+
   // The chat gate may flip while a popup is open (session switched away):
   // never commit into a session the file no longer belongs to.
   const chatGate = props.chatEnabled === true && props.sessionId !== undefined && props.remoteRoot !== undefined
@@ -670,7 +733,31 @@ export const CodeEditor = forwardRef<CodeEditorHandle, {
     viewRef.current = view
     // Baseline for the dirty check, kept as a `Text` so comparing on a
     // keystroke does not have to materialize the document as a string.
-    savedDocRef.current = view.state.doc
+    //
+    // `savedText` (the last loaded/saved bytes) wins over the mounted document:
+    // a remount can carry the UNSAVED buffer as `initial` (see the prop's doc),
+    // and that text must never become the "clean" reference.
+    const savedText = propsRef.current.savedText
+    const baseline = savedText !== undefined
+      ? EditorState.create({ doc: savedText }).doc
+      : view.state.doc
+    savedDocRef.current = baseline
+    if (savedText !== undefined) {
+      savedRef.current = savedText
+      // Report the dirty state AT MOUNT: the buffer can already be newer than
+      // the disk bytes (a handoff remount). Waiting for the first keystroke
+      // left exactly such a file shown as clean — dot off, Save disabled,
+      // close guard silent — which is the failure this baseline exists to
+      // prevent.
+      const dirty = view.state.doc !== baseline && !view.state.doc.eq(baseline)
+      // Only a CHANGE is worth a store write: this runs on every mount, and a
+      // clean tab reporting `false` would cost every subscriber a re-render for
+      // nothing.
+      if (dirty !== dirtyRef.current) {
+        dirtyRef.current = dirty
+        propsRef.current.onDirty(dirty)
+      }
+    }
     setView(view)
     /**
      * Come back to where this file was left.