dsh-remote-vs 0.8.8 → 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/TerminalView.d.ts

@@ -9,8 +9,11 @@
  */
 import { type ReactNode } from 'react';
 import type { RemoteHostSummary } from '../protocol.ts';
+import type { TerminalRequest } from './store.tsx';
 export declare function TerminalView(props: {
     t: (key: string) => string;
     hosts: RemoteHostSummary[];
     visible: boolean;
+    /** A pending "open a terminal here" request from the search results' menu. */
+    request?: TerminalRequest;
 }): ReactNode;

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

@@ -12,4 +12,10 @@ export declare function XTerm(props: {
     fontFamily?: string;
     /** When the parent sub-tab hides/shows this view without unmounting. */
     visible?: boolean;
+    /**
+     * Line typed into the fresh shell once its PTY reports ready (a menu entry's
+     * `cd`). Sent ONCE per mount: a reconnect is a new mount and thus a new shell,
+     * which correctly re-runs the line.
+     */
+    initialInput?: string;
 }): ReactNode;

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/remote-file-open-target.d.ts

@@ -1,25 +1,3 @@
-/**
- * Where a clicked file reference should open when the owning session lives in
- * a remote workspace (pure — no React, no fetch, so the gate can drive it).
- *
- * DSH renders every file reference as a `dsh-resource://file/…` address and
- * opens it through its own right-sidebar preview. That preview resolves the
- * address path against the SESSION WORKSPACE ROOT. A model that quotes a path
- * relative to its CURRENT directory (e.g. `_xfer/reports/x.md` while working
- * in `<workspace>/<inner-repo>`) therefore misses by one segment, and a
- * remote session's workspace root only exists as an EMPTY local alias dir —
- * the click dies with the host-side ENOENT the user sees.
- *
- * This module answers "which binding, which remote paths to try" for the
- * client interceptor:
- *  - relative paths are tried against the workspace root first and the
- *    session's current working directory second (the model's usual writing
- *    base), which is what makes the one-segment miss heal;
- *  - absolute spellings (local alias, POSIX remote, drive-qualified alias)
- *    are folded back onto the binding;
- *  - anything that does not name a known binding answers `undefined`, so the
- *    native preview keeps handling local sessions and unknown addresses.
- */
 /** One remote binding as the client store exposes it. */
 export interface RemoteOpenBinding {
     id: string;

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

@@ -0,0 +1,29 @@
+/**
+ * Shell quoting for the lines this plugin types into a remote terminal.
+ *
+ * One rule, one place: the client builds POSIX shell text in three spots (the
+ * `cd` typed into a fresh terminal, the bounded suffix search for an unresolved
+ * click target, and the terminal command a menu entry sends), and a second copy
+ * of the quoting rule is how an injection bug reappears after it was fixed once.
+ *
+ * Single quotes are the only form that is safe for arbitrary paths — double
+ * quotes still expand `$`, backticks and `\` — and the closing quote is the one
+ * character they cannot carry, so it is spliced in as `'\''`.
+ */
+/**
+ * Quote one value for a POSIX shell, as a single word.
+ *
+ * @param value - the raw path or word.
+ * @returns `'value'` with every embedded `'` spliced as `'\''`.
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * The command typed into a fresh remote terminal to land in one directory.
+ *
+ * A trailing newline is NOT included: the caller writes the line and the
+ * terminal's Enter, which keeps the same string reusable for display.
+ *
+ * @param dir - absolute remote directory.
+ * @returns `cd '<dir>'`.
+ */
+export declare function cdCommand(dir: string): string;

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;
@@ -82,6 +93,30 @@ export interface SearchRequest {
     /** Absolute remote directory the search is scoped to. */
     scope: string;
 }
+/** One "show this folder in the explorer tree" request. */
+export interface RevealRequest {
+    /** Monotonic id so asking for the same folder twice still re-triggers. */
+    id: number;
+    /** Absolute remote DIRECTORY to expand and scroll to. */
+    path: string;
+}
+/** One "open a terminal here" request. */
+export interface TerminalRequest {
+    /** Monotonic id so the same folder can be opened twice. */
+    id: number;
+    /**
+     * Host alias the directory lives on.
+     *
+     * Carried explicitly, and NOT taken from the terminal panel's own last-used
+     * host: the panel remembers whatever host the user ran a shell on last, so a
+     * menu action on a workspace bound elsewhere opened the shell on the WRONG
+     * machine — the `cd` then failed with "No such file or directory" for a path
+     * that exists perfectly well on its own host.
+     */
+    alias: string;
+    /** Absolute remote directory the fresh shell should `cd` into. */
+    dir: string;
+}
 /** Stored repository sub-directory for one binding ('' = the workspace root). */
 export declare function readRepoSubdir(workspaceId: string): string;
 /** Everything a view can read, plus the actions. */
@@ -120,9 +155,16 @@ 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). */
+    revealRequest: RevealRequest | undefined;
+    /** Pending "open a terminal here" request (consumed by the terminal panel). */
+    terminalRequest: TerminalRequest | undefined;
     setView: (view: RailView) => void;
     /** Switch to the search panel (optionally scoped to a folder) — the tree's
         "find in folder" entry point. */
@@ -131,6 +173,17 @@ export interface ExplorerValue {
         query?: string;
         scope: string;
     }) => void;
+    /**
+     * Show one remote directory in the explorer: switch to it, expand the folder
+     * and its ancestors, then scroll its row into view. Raised by the search
+     * results' "open containing folder" entry.
+     */
+    revealInExplorer: (dir: string) => void;
+    /**
+     * Open a fresh terminal tab whose shell `cd`s into `dir`. Raised by the
+     * search results' "open in terminal" entry.
+     */
+    openTerminalAt: (dir: string) => void;
     /**
      * The USER's pick — the workspace dropdowns and the wizard's "open files".
      *
@@ -160,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;
@@ -176,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;
@@ -197,6 +270,32 @@ export declare function requestSearch(request: {
     query?: string;
     scope: string;
 }): void;
+/**
+ * Show one remote directory in the explorer.
+ *
+ * Two stages, because the tree is lazily loaded: this raises the request and
+ * switches the panel, and the explorer itself expands the ancestors (loading
+ * each level) and scrolls the row into view — it is the only place that knows
+ * which directories are currently expanded.
+ *
+ * @param dir - absolute remote DIRECTORY (a file's parent for a file hit).
+ */
+export declare function revealInExplorer(dir: string): void;
+/**
+ * Open a fresh terminal tab whose shell lands in `dir` — on the CURRENT
+ * workspace's host.
+ *
+ * The terminal panel consumes the request (it owns the tabs) and the shell gets
+ * a quoted `cd` once its PTY reports ready — the host's terminal route has no
+ * "start in this directory" parameter, so a typed command is the honest way.
+ *
+ * The alias travels IN the request. The panel otherwise opens new tabs on the
+ * host it last used, which put the shell on a different machine than the path
+ * belongs to and made the `cd` fail with "No such file or directory".
+ *
+ * @param dir - absolute remote directory.
+ */
+export declare function openTerminalAt(dir: string): void;
 /**
  * Select the binding every view works against — the USER's choice.
  *
@@ -373,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`). */
@@ -382,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).
  *
@@ -405,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.8",
+  "version": "0.9.0",
   "icon": "icon.svg",
   "keywords": [
     "dsh",