dsh-remote-vs 0.9.1 → 0.9.2

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

@@ -1,83 +1,170 @@
 /**
- * Remote `@file` insertion into the current session's composer draft: the
- * far-side twin of dsh-better-sidebar's `conversation-draft.ts` /
- * `selection-payload.ts` (logic vendored, see below). The stock local flow
- * projects explorer rows against the host-confirmed workspace root; remote
- * rows are POSIX absolutes on another machine, so they project against the
- * binding's `remotePath` instead — the same workspace-relative spelling the
- * P3 `TransparentFileReferences` router completes, and the `read` tool
- * consumes through the fs router.
+ * Remote `@file` / selection insertion into the current session's composer
+ * draft: the far-side twin of dsh-better-sidebar's `conversation-draft.ts` +
+ * `selection-payload.ts`. The stock local flow projects explorer rows against
+ * the host-confirmed workspace root; remote rows are POSIX absolutes on
+ * another machine, so they project against the binding's `remotePath` instead —
+ * the same workspace-relative spelling the P3 `TransparentFileReferences`
+ * router completes, and the `read` tool consumes through the fs router.
  *
- * Vendored pieces (behavior-identical to better-sidebar 0.25.0):
- * - `spliceInsert` / `insertAtCaret` (whitespace-aware caret splice),
- * - `findComposerTextarea` / `probeComposerCaret` /
- *   `placeComposerCaretAfterInsert` (DOM caret probe; on DSH 0.2.1 the
- *   composer is a Lexical editor, so the probe misses and inserts append at
- *   the end — exactly what the local explorer does there),
- * - `appendToDraft` (draft read + `setDraft` write through
- *   `ctx.get('conversation')`, missing service degrades to a logged no-op),
+ * Vendored behavior (dsh-better-sidebar **0.28.1**, same semantics):
+ * - `leadFor` / `appendText` (the one separating-space rule),
+ * - `foldClipboardOffset` / `appendOffset` (the host keeps TWO coordinate
+ *   systems over the draft: the clipboard projection — `draft` — expands every
+ *   chip to its whole `clipboardText`, while every insert event's `span` speaks
+ *   the editor's DETECT projection, one placeholder character per chip; a span
+ *   derived without folding is rejected by the host on the second chip),
+ * - `insertDraftReference` — mint one structured chip through the host's public
+ *   `insertReference` facade (the method the native `@` picker calls), with a
+ *   leading space pushed through `slash/input-insert-text` when the draft needs
+ *   one,
+ * - `appendToDraft` — plain text: `setDraft` only for a chipless draft;
+ *   anything carrying chips (or a claimed `/command`) is written through the
+ *   span channel, because `setDraft` rebuilds the document from a string and
+ *   FLATTENS every chip,
+ * - `insertReferenceOrText` — the single fallback policy both surfaces use,
  * - `mentionFor` / `directoryMention` (the `@` quoting grammar),
- * - `insertFileReference` (`slash/input-insert-reference`, verified present
- *   in DSH 0.2.1-alpha.2's dsh-client-ui-conversation contract),
- * - `SELECTION_LIMIT` / `buildRemoteSelectionInsert` (the fenced
- *   `rel:lines` payload shape).
+ * - `SELECTION_LIMIT` / `buildRemoteSelectionInsert` (fenced `rel:lines`
+ *   payload; over the limit the content is dropped and the chip carries the
+ *   plain path line, so an empty fenced block never occupies the draft).
+ *
+ * The 0.25.0-era version of this file inserted at the composer's DOM caret and
+ * always wrote plain text through `setDraft`; both are gone on purpose — the
+ * host publishes no caret for the Lexical composer, and `setDraft` silently
+ * destroyed existing chips.
  *
  * Remote adaptations (ours):
  * - `remoteRelativePath`: POSIX-only prefix strip against `remoteRoot`
  *   (case-sensitive; outside/traversal refuses with `undefined`, never an
  *   absolute mention — the local `workspaceRelativePath` policy).
- * - `insertRemoteReference`: the caller passes `remoteRoot` directly; there
- *   is no workspaces-membership lookup here because the binding gate lives
- *   in `use-remote-chat-target.ts` (current session must belong to the
- *   viewed binding, else the button is disabled — a remote-relative mention
- *   in a local session would name nothing).
+ * - `insertRemoteReference`: the caller passes `remoteRoot` directly; there is
+ *   no workspaces-membership lookup here because the binding gate lives in
+ *   `use-remote-chat-target.ts` (current session must belong to the viewed
+ *   binding, else the button is disabled).
  * - `sameLocalDir`: Windows-tolerant alias-dir comparison for that gate.
  *
- * No ctx reads at module scope (explicit `ctx` params only) so every
- * function degrades to a logged no-op when a web-core service is missing,
- * and the pure pieces stay unit-testable. DOM-only: no Node builtins (the
- * client purity gate forbids them).
+ * No ctx reads at module scope (explicit `ctx` params only) so every function
+ * degrades to a logged no-op when a web-core service is missing, and the pure
+ * pieces stay unit-testable. DOM-only: no Node builtins (the client purity gate
+ * forbids them).
  */
 import type { Context } from '@deepseek-ai/cordis';
-/** A resolved composer caret/selection in draft coordinates. */
-export interface DraftCaret {
+/** One reference chip's footprint in clipboard-projection coordinates. */
+export interface OccurrenceLike {
+    /** Start offset in the clipboard projection (same plane as `draft`). */
+    offset: number;
+    /** Length in the clipboard projection (the chip's whole `clipboardText`). */
+    length: number;
+}
+/** Pick-time draft span guarded by the input revision (detect coordinates). */
+export interface TokenSpan {
     start: number;
     end: number;
+    draftRev: number;
+}
+/** The host's structured-reference payload (mirror of `ReferenceInsert`). */
+export interface ReferenceInsert {
+    /** Trigger source id; `'reference'` for a programmatic insert. */
+    source: string;
+    /** What the model receives on send — the chip's full serialized form. */
+    ref: string;
+    /** What the composer shows in place of `ref`. */
+    label: string;
+    /** Chip icon family; the host picks its own default when omitted. */
+    appearance?: 'session' | 'file' | 'folder';
+    /** The text this chip occupies in the draft projection. */
+    clipboardText: string;
+}
+/**
+ * One reference to insert: the compact `label` the composer shows, and the
+ * `text` the model receives on send. The two are deliberately different — a
+ * selection reads as `docs/a.md:12-15` on screen while the model still gets the
+ * whole fenced block. A plain-text fallback inserts `text` (never the label),
+ * so a chip failure still delivers the payload the user meant.
+ */
+export interface PendingReference {
+    label: string;
+    text: string;
+    /** What the draft string carries for this chip; defaults to `label`. */
+    clipboardText?: string;
+    /** Chip icon family. Omit when `text` is not a path (a selection). */
+    appearance?: 'file' | 'folder' | 'session';
 }
+/** Snapshot the insertion logic reads (structural slice of the host's InputState). */
+interface InputSnapshot {
+    draft: string;
+    draftRev?: number;
+    occurrences?: readonly OccurrenceLike[];
+    phase?: 'plain' | 'adjudicating' | 'claimed' | 'submitting';
+    claim?: {
+        readonly token: string;
+    };
+}
+/** `draft` with `text` appended behind one separating space when needed. */
+export declare function appendText(draft: string, text: string): string;
 /**
- * The spliced draft string (see {@link spliceInsert}); pure string math —
- * unit-tested directly.
+ * Fold one clipboard-projection offset to its detect-projection twin.
+ *
+ * An offset inside a chip's expansion snaps to that chip's trailing edge (the
+ * host only ever replaces whole chips, never splits one). An offset exactly at
+ * a chip's START resolves to the position BEFORE the chip — the host's own
+ * `detectOffsetOfClipboardOffset` reads that case as "inside" and would move a
+ * caret one chip too far right.
  */
-export declare function insertAtCaret(draft: string, text: string, caret: DraftCaret | null): string;
+export declare function foldClipboardOffset(draft: string, occurrences: readonly OccurrenceLike[], offset: number): number;
 /**
- * Resolve the composer's live caret from its DOM `<textarea>`. The draft
- * store has no caret API, so the value-sync check (`el.value === draft`)
- * discards stale or wrong-composer reads — a caret must never be applied
- * against a draft it was not measured on.
+ * The detect-projection offset that appends at the document end, or
+ * `undefined` when it cannot be derived.
  *
- * Returns null when the composer is missing, disabled/read-only, out of
- * sync with the store draft, or has no measurable selection (jsdom/odd
- * hosts report null selectionStart/End).
+ * `foldClipboardOffset` alone is not enough: a command chip (`/goal `, present
+ * while `phase === 'claimed'`) collapses to one detect character but never
+ * appears in `occurrences` — the host only collects REFERENCE chips.
+ *
+ * CORRECTION over the upstream 0.28.1 formula: the chip's clipboard text is
+ * `claim.token.trimEnd()` and the separator is a SEPARATE text node, so the
+ * detect projection is `1 (chip) + separator.length + rest`. Upstream folds the
+ * whole `claim.token` into that one placeholder, which lands one character
+ * short — a selection or `@file` appended while a slash command is claimed then
+ * splices INSIDE the command's last argument word (`/goal do it` became
+ * `/goal do i <payload>t`). Verified against the installed host:
+ * `CommandChipNode.getTextContent()` returns the token without its separator,
+ * and `insertCommand` inserts the separator as its own text node.
  */
-export declare function probeComposerCaret(draft: string): DraftCaret | null;
+export declare function appendOffset(snapshot: InputSnapshot): number | undefined;
 /**
- * Restore the composer caret to `caretIndex` after a programmatic
- * `setDraft` commit. A controlled textarea update resets the caret (React
- * commits the value asynchronously and the browser moves the caret to the
- * start/end), so the placement is scheduled and retried across at most two
- * animation frames (setTimeout fallback for jsdom), and only applied when
- * the textarea still matches `expectedDraft` — a newer edit or a different
- * composer wins the race untouched. The caret is clamped into the value
- * bounds, mirroring how browsers clamp type-in positions.
+ * Mint one reference chip through the host's public `insertReference` facade —
+ * the same method the native `@` picker's event listener calls, so the
+ * composer shows a compact chip while the model receives `reference.text`.
+ * The host runs its own admission-phase and revision guards and reports whether
+ * the edit applied.
+ *
+ * The chip's `clipboardText` is the compact `label` by default, not the full
+ * payload: other draft consumers (copy, plain projections) stay short, and the
+ * full payload rides in `text` for send.
+ *
+ * @returns false when the host refused the insert (stale revision, frozen
+ *   submission phase, or no chip channel) so the caller can fall back.
  */
-export declare function placeComposerCaretAfterInsert(expectedDraft: string, caretIndex: number): void;
+export declare function insertDraftReference(ctx: Context, sessionId: string, reference: PendingReference): boolean;
 /**
- * Insert `text` into the session's composer draft at the composer's live
- * caret (see {@link probeComposerCaret}), falling back to appending at the
- * end when the caret cannot be resolved. Returns false — and logs — when the
- * conversation service or the session scope is unavailable.
+ * Append `text` to the session's composer draft. Returns false — and logs —
+ * when the conversation service or the session scope is unavailable.
+ *
+ * A chipless draft takes the plain `setDraft` path. A draft that CARRIES chips
+ * is written through `slash/input-insert-text` at the folded end offset
+ * instead: `setDraft` rebuilds the document from a string and flattens every
+ * chip, which quietly destroys references the user placed by hand. The same
+ * span path covers a claimed `/command`, whose prefix chip is not in
+ * `occurrences` (see {@link appendOffset}).
  */
 export declare function appendToDraft(ctx: Context, sessionId: string, text: string): boolean;
+/**
+ * Insert one reference as a chip, degrading to its plain-text form when the
+ * host has no chip channel or refuses the insert. This is the ONE place the
+ * fallback policy lives: the explorer's `@` button and the viewer selection
+ * popup both come through here.
+ */
+export declare function insertReferenceOrText(ctx: Context, sessionId: string, reference: PendingReference): boolean;
 /**
  * The DSH `@` spelling for one relative path, mirroring the host grammar
  * (`formatFileMention` in `@deepseek-ai/dsh-file-reference`): plain when
@@ -127,24 +214,14 @@ export declare function remoteRelativePath(root: string | undefined, path: strin
 export declare function sameLocalDir(left: string, right: string): boolean;
 /**
  * Insert one remote explorer entry into the session's composer draft. Files
- * mint a structured chip like the native `@` picker
- * (`insertFileReference`); directories append the folder mention as plain
- * text so DSH's folder decoration and completion keep working. The caller
- * owns the binding gate (the session must belong to the viewed binding —
- * see `use-remote-chat-target.ts`); an unrepresentable path is a logged
- * no-op, never an absolute mention.
+ * mint a structured chip exactly like the native `@` picker (same facade the
+ * viewer selection popup uses, with a plain-text fallback); directories append
+ * the folder mention as plain text so DSH's folder decoration and completion
+ * keep working. The caller owns the binding gate (the session must belong to
+ * the viewed binding — see `use-remote-chat-target.ts`); an unrepresentable
+ * path is a logged no-op, never an absolute mention.
  */
 export declare function insertRemoteReference(ctx: Context | undefined, sessionId: string, remoteRoot: string, absPath: string, isDir: boolean): boolean;
-/**
- * Insert one FILE reference as a structured chip (like DSH's own `@` picker).
- * The chip displays `@<basename>` but serializes to `@<relative path>` on
- * send, so the reference stays a single link from trigger to basename.
- *
- * Directories keep the plain-text completion behavior (`@dir/`) through
- * `insertRemoteReference`. The rc.1 picker also supports folder chips on
- * explicit selection; its drill action still inserts plain text.
- */
-export declare function insertFileReference(ctx: Context, sessionId: string, relativePath: string): boolean;
 /** Max inserted selection length (UTF-16 code units, i.e. JS `.length`). */
 export declare const SELECTION_LIMIT = 500;
 /** The source line span a selection maps to (1-based, inclusive). */
@@ -158,8 +235,14 @@ export interface SelectionLines {
  */
 export declare function remoteHeaderOf(remoteRoot: string, absPath: string, lines?: SelectionLines): string;
 /**
- * The full text appended to the composer draft for one selection.
- * Over the limit the content is dropped: the plain path line is the whole
- * payload (an empty fenced block would just occupy the draft).
+ * The composer payload for one selection: the chip label and the model text.
+ *
+ * The chip reads as `rel:start-end` (compact, and it is what the draft
+ * projection carries); the model receives the whole fenced block. Over the
+ * limit the content is dropped and BOTH halves are the plain path line — an
+ * empty fenced block would just occupy the draft. No `appearance` is set: the
+ * host can make `'file'` chips openable, and a selection's `text` is not a
+ * path, so a click must not hand a fenced block to the file opener.
  */
-export declare function buildRemoteSelectionInsert(absPath: string, remoteRoot: string, lines: SelectionLines | undefined, selected: string): string;
+export declare function buildRemoteSelectionInsert(absPath: string, remoteRoot: string, lines: SelectionLines | undefined, selected: string): PendingReference;
+export {};

package/lib/types/client/selection-popup.d.ts

@@ -32,30 +32,30 @@
  */
 import { type RefObject } from 'react';
 /** The floating "add to conversation" action: payload + viewport anchor. */
-export interface SelectionPopup {
-    insert: string;
+export interface SelectionPopup<T> {
+    insert: T;
     left: number;
     top: number;
 }
-export interface SelectionPopupOptions {
+export interface SelectionPopupOptions<T> {
     /** Commit the payload into the composer draft (button click). */
-    onCommit(insert: string): void;
+    onCommit(insert: T): void;
     /**
      * The DOM surface that must stay on screen for the popup to live: the
      * CodeMirror host. Called lazily (refs are null until the content loads).
      */
     getSurface(): HTMLElement | null;
 }
-export interface SelectionPopupControls {
+export interface SelectionPopupControls<T> {
     /** The current popup (null = hidden). */
-    popup: SelectionPopup | null;
+    popup: SelectionPopup<T> | null;
     /** Attach to the portaled button element. */
     buttonRef: RefObject<HTMLButtonElement>;
     /** Anchor the popup above a selection (viewport-clamped). */
-    show(insert: string, left: number, top: number): void;
+    show(insert: T, left: number, top: number): void;
     /** Hide the popup (idempotent). */
     hide(): void;
     /** The button's click: commit the stored payload, then hide. */
     commit(): void;
 }
-export declare function useSelectionPopup(options: SelectionPopupOptions): SelectionPopupControls;
+export declare function useSelectionPopup<T>(options: SelectionPopupOptions<T>): SelectionPopupControls<T>;

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.9.1",
+  "version": "0.9.2",
   "icon": "icon.svg",
   "keywords": [
     "dsh",

package/src/client/CodeEditor.tsx

@@ -34,7 +34,7 @@ import { shell } from '@codemirror/legacy-modes/mode/shell'
 import { properties } from '@codemirror/legacy-modes/mode/properties'
 import { dockerFile } from '@codemirror/legacy-modes/mode/dockerfile'
 import { diff } from '@codemirror/legacy-modes/mode/diff'
-import { appendToDraft, buildRemoteSelectionInsert } from './composer.ts'
+import { buildRemoteSelectionInsert, insertReferenceOrText, type PendingReference } from './composer.ts'
 import { useSelectionPopup } from './selection-popup.ts'
 import { initialEditorTheme, watchEditorScheme } from './vsc/editor-theme.ts'
 
@@ -243,11 +243,14 @@ export const CodeEditor = forwardRef<CodeEditorHandle, {
    * listeners (outside mousedown, Escape, hidden tab/window, surface
    * leaving the viewport) — see selection-popup.ts.
    */
-  const selectionPopup = useSelectionPopup({
+  const selectionPopup = useSelectionPopup<PendingReference>({
     onCommit: (insert) => {
       const ctx = ctxRef.current
       const sessionId = targetRef.current.sessionId
-      if (ctx !== undefined && sessionId !== undefined) appendToDraft(ctx, sessionId, insert)
+      // The same entry the explorer's @ button uses: mint one structured chip
+      // (compact `rel:start-end` label, fenced block to the model), falling back
+      // to plain text only when the host refuses the chip channel.
+      if (ctx !== undefined && sessionId !== undefined) insertReferenceOrText(ctx, sessionId, insert)
     },
     getSurface: () => hostRef.current,
   })