dsh-rewind-plugin 0.15.0-beta.1 → 0.15.0

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

@@ -42,7 +42,7 @@
  */
 import { type ReactNode } from 'react';
 import type { SessionFace } from '@deepseek-ai/dsh-api-session-controller/client';
-import { type ChatOf, type ChatWatch, type HiddenChat } from './hidden.ts';
+import { type ChatOf, type ChatWatch, type HiddenChat, type MessageImageRef } from './hidden.ts';
 import type { RewindKey } from './locales.ts';
 type Translate = (key: RewindKey, params?: Record<string, unknown>) => string;
 /** One portal target: the actions row of a user/steering seat + its durable node. */
@@ -63,7 +63,7 @@ export type PortalTarget = {
     readonly container: HTMLElement;
     /** The host inbox occurrence the retract button addresses. */
     readonly itemId: string;
-    /** Complete editable text; null when the message contains non-text blocks. */
+    /** Complete editable text; null when the message contains no text block. */
     readonly text: string | null;
     readonly preview: string;
 };
@@ -96,6 +96,13 @@ export interface RewindBridgeDeps {
      * Session-scoped so the refill only lands in the session that just rewound.
      */
     readonly setComposerText: (sessionId: string, text: string) => boolean;
+    /**
+     * Session-aware image restorer (see `restoreImages` in index.ts): re-adds
+     * a withdrawn message's durable image references to that session's
+     * composer draft so a rewind of an image-bearing message does not lose
+     * the pictures. Optional — absent degrades to the text-only refill.
+     */
+    readonly restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>;
 }
 /** Structural face of the runtime slot service (see the module doc). */
 export interface SlotsLike {
@@ -162,7 +169,7 @@ export declare function writeComposer(text: string, facade: ComposerDraftWriter
  * the old baseline heuristic refilled withdrawn text into the composer
  * after switching sessions or restarting dsh.
  */
-export declare function runRewindAndFill(session: SessionFace, seq: number, mode: 'chat' | 'both', isMainViewSession: (sessionId: string) => boolean, chatOf: ChatOf, watchChat: ChatWatch, setComposerText: (sessionId: string, text: string) => boolean): Promise<void>;
+export declare function runRewindAndFill(session: SessionFace, seq: number, mode: 'chat' | 'both', isMainViewSession: (sessionId: string) => boolean, chatOf: ChatOf, watchChat: ChatWatch, setComposerText: (sessionId: string, text: string) => boolean, restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>): Promise<void>;
 /**
  * The snapshot seq a rendered seat stands for.
  *
@@ -183,12 +190,12 @@ export declare function resolveSeatAnchorSeq(element: HTMLElement, chat: HiddenC
  * Locate the actions container of a user/steering seat row — the element the
  * ↶ button portals into (the copy/branch IconActions row).
  *
- * The finder is STRUCTURAL on purpose: no harness attribute marks the actions
- * row on the user seat (the old `data-time-hover-root` marker lived on the
- * per-turn tail footer and is gone in 0.1.6-alpha.2), so the container is
- * located as the direct holder of the copy `<button>` (the `MessageIconActions`
- * container, which mounts that button as a direct child —
- * `MessageIconActions.tsx:83,86`).
+ * The finder is STRUCTURAL on purpose: `MessageIconActions` marks this container
+ * with `data-clock`, which names clock placement rather than the action row (the
+ * old `data-time-hover-root` marker lived on the per-turn tail footer and is
+ * gone in 0.1.6-alpha.2), so the container is located as the direct holder of
+ * the copy `<button>` (the `MessageIconActions` container, which mounts that
+ * button as a direct child).
  *
  * Returns undefined when no qualifying container is found; the caller refuses
  * to portal (never a crash, never a wrong attachment). Exported as a test seam
@@ -220,14 +227,8 @@ export declare function actionsContainerOf(row: HTMLElement | undefined): HTMLEl
  * withdrawn "command executed" tool group on screen as an empty expandable row
  * after every member below it had been hidden.
  *
- * Cost stays O(seats) per refresh: the caller queries the batch once, and each
- * shell decision reuses the member outcomes already computed here — no second
- * document scan, and no per-shell subtree walk.
- *
- * Every hidden element carries `data-dsh-rewind-hidden`, so DevTools, other DOM
- * plugins and tests can tell a rewind-hide apart from a collapse/filter hide; a
- * re-created row has no marker and is re-judged, and a row that leaves the
- * withdrawn span is shown again.
+ * Every hidden element carries `data-dsh-rewind-hidden` (see
+ * `docs/contract/client-contract.md`).
  *
  * @param chat - the live chat snapshot the seats belong to.
  * @param seats - this refresh's seat batch (every `[data-chat-anchor-key]`).
@@ -275,6 +276,27 @@ export declare function isRewindInertSession(snapshot: SessionKindLike): boolean
  * @param hiddenSeqs - anchor seqs withdrawn by previous rewinds.
  */
 export declare function collectDurableTargets(snapshot: SessionKindLike, chat: HiddenChat | undefined, hiddenSeqs: ReadonlySet<number>): readonly PortalTarget[];
+/**
+ * The pending bubble row's compared text and its message-attachment block
+ * count, read from a CLONE (the live row is never touched).
+ *
+ * Both the actions container and the message-attachment block are excluded from
+ * the text: the copy button's Tooltip mounts its label inside that button, and
+ * the attachment block renders text of its own (a file name/size, a lone
+ * image's loading label) that no inbox row reproduces. The block is counted
+ * instead, as the attachment half of the match key (`matchPendingRows`).
+ *
+ * The clone's counterpart is taken by query position, not by position among the
+ * row's children: the harness renders the attachment block BEFORE the message
+ * bubble, so "drop the first child" would drop the message text.
+ *
+ * @param row - one rendered `[data-pending-steering]` row.
+ * @returns the compared text and the attachment block count.
+ */
+export declare function bubbleTextOf(row: HTMLElement): {
+    readonly text: string;
+    readonly attachments: number;
+};
 interface RewindPortalsProps extends RewindBridgeDeps {
     readonly sessionId: string;
 }
@@ -289,7 +311,7 @@ interface RewindPortalsProps extends RewindBridgeDeps {
  * their actions containers) and the session's `inbox` projection (the pending
  * occurrences — see `syncInboxSubscription`).
  */
-export declare function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText }: RewindPortalsProps): ReactNode;
+export declare function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText, restoreImages }: RewindPortalsProps): ReactNode;
 /** The current composer draft: the contenteditable `textContent`.
  * Empty when the composer is absent. Exported as a test seam (the
  * empty-composer guard in `retractPending`). */

package/lib/types/client/settings-card.d.ts

@@ -39,7 +39,6 @@ export interface CleanupPolicy {
     readonly autoCleanupEnabled: boolean;
     readonly autoCleanupMaxAgeDays: number;
 }
-/** One form snapshot as this card reads it (the shared store's `getSnapshot`). */
 /**
  * One form snapshot as this card reads it: the shared form frame's own state
  * (`SettingsFormShell`) plus the two field drafts.

package/lib/types/index.d.ts

@@ -4,17 +4,9 @@
  * lives in `src/client/`).
  *
  * Rewind mechanism: planning is pure (`src/rewind.ts`); execution appends a
- * marker `user/message` into the session log whose `surfaceOp` replaces every
- * surface node after the target message with the marker. The append-only log
- * (and the rendered transcript) is untouched — only the model-visible surface
- * is cut, so the next request derives its context from the target onward.
- * The marker is a `user/message` carrying the shadowed-seq citations
- * (`sourceEventSeqs`): v3 reserves surface `replace` to a node that cites
- * every shadowed seq, and `assistant/message` can no longer carry those — so
- * the replacement node is a `user/message`, exactly as /compact's checkpoint
- * is. It derives to itself (a present user turn), so the marker stays as the
- * surface-tail cut point rather than vanishing.
- *
+ * marker `user/message` whose `surfaceOp` replaces every surface node after the
+ * target with itself, cutting only the model-visible surface
+ * (`docs/architecture.md`).
  *
  * File restore (mode `both`) follows Claude Code's checkpointing: the plugin
  * backs up each tracked write-class edit BEFORE it happens (at the

package/lib/types/locales.d.ts

@@ -60,6 +60,8 @@ export declare const en: {
     'skipReason.oversized': string;
     'uncovered.header': string;
     'error.invalidTarget': string;
+    'sep.list': string;
+    'sep.clause': string;
     'failures.suffix': string;
     'failures.item': string;
     inflight: string;

package/lib/types/marker.d.ts

@@ -1,12 +1,10 @@
 /**
- * The rewind marker's message-source identity, shared by the host and the
- * client.
+ * The rewind marker's message-source identity.
  *
  * A producer owns its source `kind` outright (`MessageSourceMap` is
  * merge-extensible and has no catch-all `plugin` kind since session format v4),
- * so this module declares `dsh-rewind` and owns the one predicate that
- * recognizes the marker. Keeping it in a leaf with no cordis or node imports
- * lets the browser half name the marker without pulling in the host plugin.
+ * so this module declares the `dsh-rewind` source every marker carries. Kept in
+ * a leaf with no cordis or node imports.
  *
  * @module dsh-rewind/marker
  */
@@ -17,23 +15,7 @@ declare module '@deepseek-ai/dsh-llm' {
         };
     }
 }
-/** Producer kind carried by every marker this plugin appends. */
-export declare const REWIND_MARKER_KIND = "dsh-rewind";
 /** The marker's source: one producer-owned kind, no private fields. */
 export declare const REWIND_MARKER_SOURCE: Readonly<{
     readonly kind: "dsh-rewind";
 }>;
-/**
- * Test whether a persisted message source identifies a rewind marker.
- *
- * Three shapes are recognized because a marker's source is immutable once
- * written: the current producer-owned kind, the released v3 plugin wrapper
- * (`{ kind: 'plugin', plugin: 'dsh-rewind' }`) on logs this build has not yet
- * rewritten, and the migrated form of that wrapper (`plugin:dsh-rewind`) that
- * the v3→v4 conversion produces for a producer it does not know by name.
- * @param source - source restored from a surface user message, or any stored
- *   value: a log written by an earlier build carries shapes the current union
- *   no longer names.
- * @returns whether the source carries the rewind brand.
- */
-export declare function isRewindMarker(source: unknown): boolean;

package/lib/types/rewind.d.ts

@@ -3,32 +3,19 @@
  * No I/O and no `Session` dependency — everything derives from the event log
  * and the ordered surface, so this module stays unit-testable.
  *
- * Rewind semantics (see README): rewinding to a user message appends a marker
- * node into the session log whose `surfaceOp` replaces every surface node
- * AFTER the target with itself. The log (the audit trail and the rendered
- * transcript) is untouched; only the model-visible surface is cut, so the
- * next request derives its context from the target message onward.
- *
- * Marker shape (v4): the marker is a `user/message` carrying a replace
- * `surfaceOp` and the producer-owned source `{ kind: 'dsh-rewind' }` (see
- * `marker.ts`) — a single event:
- *
- *   user/message (marker content) → { surfaceOp {replace, startSeq, endSeq} }
- *
- * v3 reserves surface `replace` to a node that cites every shadowed seq via
- * `sourceEventSeqs`, and `assistant/message` can no longer carry
- * `sourceEventSeqs` (it now embeds its provider stream instead) — so the
- * replacement node must be a `user/message`, exactly as /compact's checkpoint
- * is. No ghost `step/start`…`step/end` frame is needed: the token-meter's
- * step state machine ignores `user/message`, and the session invariant
- * (`invariant.ts`) imposes no open-turn requirement on it, so the marker is
- * appended while idle, outside any turn. It sits at the surface tail as the
- * model-visible "cut point" — a present user turn in derived history.
+ * Rewind semantics: rewinding to a user message appends a marker node into the
+ * session log whose `surfaceOp` replaces every surface node AFTER the target
+ * with itself. The log (audit trail, rendered transcript) is untouched; only
+ * the model-visible surface is cut, so the next request derives its context
+ * from the target message onward. The marker is a `user/message` carrying a
+ * replace `surfaceOp` and the producer-owned source `{ kind: 'dsh-rewind' }`
+ * (see `marker.ts`); the shape's invariants and history are documented in
+ * `docs/architecture.md`.
  *
  * @module dsh-rewind/rewind
  */
 import type { SessionEvent, UserMessage } from '@deepseek-ai/dsh-session';
-export { REWIND_MARKER_KIND, REWIND_MARKER_SOURCE, isRewindMarker } from './marker.ts';
+export { REWIND_MARKER_SOURCE } from './marker.ts';
 /** Which of the two rewind modes a rewind executes. */
 export type RewindMode = 'chat' | 'both';
 /**
@@ -101,7 +88,9 @@ export declare function isHumanUserMessageEvent(event: SessionEvent): event is S
 /** Join the text blocks of a message into one plain string. */
 export declare function messagePreview(message: UserMessage): string;
 /**
- * Parse a raw command token into a rewind target.
+ * Parse a raw command token into a rewind target. Both forms must be plain
+ * decimal integers: a bare `Number()` would also accept `@1e3`, `@0x10` and
+ * `@+5`, and would read a bare `@` as seq 0.
  * @param raw - one token: `@123` (absolute seq) or `12` (recency index).
  * @returns the parsed target, or undefined when the token is malformed.
  */

package/lib/types/snapshot.d.ts

@@ -20,33 +20,9 @@
  * - Because entries live on disk under the dsh data directory, they survive a
  *   host restart, are bounded (the newest 100 anchor groups per session are
  *   kept), and restores read/write the real file system with plain `node:fs`
- *   — independent of the fs service.
- *
- * Security note: this `node:fs` authority is the DSH host authority every host
- * plugin holds — the model-facing fences constrain the model's tools, not this
- * code. The store stays bounded to the model-touched paths, so excluding a
- * file (e.g. `.env`) is a model-permission concern (see `SECURITY.md`).
- *
- * Crash safety (this module's own engineering asset):
- *  - Checkpoint commits are ATOMIC: the sidecar is fully written first, then
- *    the entry JSON is written to a sibling temp file and renamed over the
- *    target, so a host crash mid-write can never leave a readable entry
- *    without its bytes — at worst an unreferenced orphan sidecar, or an inert
- *    `.tmp` leftover that the next commit of the same file overwrites and that
- *    no reader ever picks up.
- *  - Every restore pass is JOURNALED. Before mutating anything the store
- *    captures the pre-restore ("rescue") state of each planned path as a raw
- *    byte copy and persists an intent journal (`journal-<op>.json` in the
- *    session dir) holding only references, then marks each action done as it
- *    is applied. A crash at any point leaves the journal on disk; after a host
- *    restart `reconcileRestores(sessionId)` re-derives from the REAL disk which
- *    paths already match the target and which are still pending (reporting
- *    "restored up to where, what changed"), auto-heals journals whose goal is
- *    already reached, and `continueRestore` / `rollbackRestore` finish the
- *    interrupted op or undo it back to the exact pre-restore state.
- *  - Journal IO is best-effort and never fails a restore: if the journal
- *    cannot be written the restore proceeds exactly like the pre-journal code
- *    (crash safety degrades, behavior does not).
+ *   — independent of the fs service. The atomic-commit and journaled-restore
+ * guarantees, the security model and the in-store layout are specified in
+ * `SECURITY.md` and `docs/format.md`.
  *
  * Restore semantics (identical to Claude Code): for every path with entries
  * anchored at or after the target message, apply the EARLIEST entry — write
@@ -54,13 +30,8 @@
  * creation. Symlinked and hard-linked paths are skipped and reported, never
  * written through.
  *
- * Format compatibility: entries written before this module stored bytes
- * (released v1: `{callId, anchorSeq, path, before: string | null}` plus the
- * `restore-journal-` prefix) are still READ — their string content is the
- * exact UTF-8 bytes it always was, except for records that were decoded
- * lossily (they contain U+FFFD: comparable, but never written back). New
- * writes are always the byte format; the marker contract that keeps a
- * downgraded v1 build from touching the workspace lives in
+ * Released-v1 entries stay readable and the byte format is specified in
+ * `docs/format.md`; the downgrade marker contract lives in
  * `tests/downgrade-safety.test.ts`.
  *
  * @module dsh-rewind/snapshot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.0",
   "description": "In-window conversation rewind with workspace file restore · 同窗口内对话回退并可还原工作区文件",
   "icon": "./assets/icon.svg",
   "keywords": [
@@ -68,7 +68,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json && tsc --noEmit -p tsconfig.client-test.json",
     "test": "vitest run",
     "verify:host": "node scripts/verify-host.mjs",
-    "check": "npm run typecheck && npm test && npm run build && node scripts/verify-host.mjs && npm pack --dry-run",
+    "check": "npm run typecheck && npm run build && npm test && node scripts/verify-host.mjs && npm pack --dry-run",
     "prepare": "npm run build"
   },
   "publishConfig": {
@@ -145,41 +145,41 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.3",
     "@deepseek-ai/cosmokit": "1.8.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-store": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-commands": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-command-compact": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-commands": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-compaction": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-compaction-basic": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-compaction-image-offload": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-fs": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-goal": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-plan-mode": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-stats": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-title": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-token-meter": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-user-questions": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-commands": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-command-compact": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-compaction-image-offload": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-goal": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-plan-mode": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-stats": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-title": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-questions": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.31",