dsh-rewind-plugin 0.14.0 → 0.15.0-beta.2

package/lib/client.js

@@ -55,6 +55,31 @@ function messageTextAt(chat, seq) {
   }
   return void 0;
 }
+function messageAttachmentsAt(chat, seq) {
+  if (chat === void 0) return void 0;
+  for (const key of chat.order) {
+    const node = chat.nodes.get(key);
+    if (node === void 0 || node.kind !== "user" && node.kind !== "steering") continue;
+    const data = node.data;
+    if (data.seq !== seq) continue;
+    const images = [];
+    for (const block of data.content ?? []) {
+      if (block.type !== "image") continue;
+      const attachment = block.attachment;
+      if (typeof attachment?.attachmentId !== "string" || typeof attachment.mediaType !== "string") continue;
+      images.push({
+        attachmentId: attachment.attachmentId,
+        mediaType: attachment.mediaType,
+        bytes: typeof attachment.bytes === "number" ? attachment.bytes : void 0,
+        width: typeof attachment.width === "number" ? attachment.width : void 0,
+        height: typeof attachment.height === "number" ? attachment.height : void 0,
+        name: typeof attachment.name === "string" ? attachment.name : void 0
+      });
+    }
+    return images;
+  }
+  return void 0;
+}
 function targetSeqOfArgs(args) {
   if (args === void 0 || args === null) return void 0;
   const match = args.match(/@(\d+)/);
@@ -259,8 +284,9 @@ var STYLE = `
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 28px;
-  height: 28px;
+  /* The neighbouring action buttons scale by this delta too. */
+  width: calc(28px + var(--dsh-content-font-delta, 0px));
+  height: calc(28px + var(--dsh-content-font-delta, 0px));
   padding: 6px;
   border: none;
   border-radius: var(--dsw-radius-sm, 8px);
@@ -268,6 +294,10 @@ var STYLE = `
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
 }
+.dsh-rewind-btn svg {
+  width: calc(15px + var(--dsh-content-font-delta, 0px));
+  height: calc(15px + var(--dsh-content-font-delta, 0px));
+}
 .dsh-rewind-btn:hover {
   background: var(--dsw-alias-interactive-bg-hover);
   color: var(--dsw-alias-label-secondary);
@@ -803,34 +833,41 @@ var import_react_dom = require("react-dom");
 // src/client/pending.ts
 var QUEUE_PREVIEW_CHARS = 200;
 function textOf(content) {
-  if (!content.every((block) => block.type === "text")) return null;
-  return content.map((block) => block.text ?? "").join("");
+  const texts = content.filter((block) => block.type === "text");
+  if (texts.length === 0) return null;
+  return texts.map((block) => block.text ?? "").join("");
+}
+function attachmentsCountOf(content) {
+  return content.filter((block) => block.type !== "text").length;
 }
-function previewOf(content) {
-  const flat = content.filter((block) => block.type !== "image" && block.type !== "file").map((block) => block.type === "text" ? block.text ?? "" : `[${block.type}]`).join(" ").replace(/\s+/g, " ").trim();
-  const chars = Array.from(flat);
-  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join("")}\u2026` : flat;
+function previewOf(text) {
+  const chars = Array.from((text ?? "").replace(/\s+/g, " ").trim());
+  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join("")}\u2026` : chars.join("");
 }
 function steeringItemsOf(nextStep) {
-  return (nextStep ?? []).filter((item) => item.source?.kind === "user").map((item) => ({
-    id: item.id,
-    text: textOf(item.content),
-    preview: previewOf(item.content)
-  }));
+  return (nextStep ?? []).filter((item) => item.source?.kind === "user").map((item) => {
+    const text = textOf(item.content);
+    return {
+      id: item.id,
+      text,
+      attachments: attachmentsCountOf(item.content),
+      preview: previewOf(text)
+    };
+  });
 }
 function matchPendingRows(rows, steering) {
   const matched = [];
   for (let i = 0; i < rows.length; i++) {
     const row = rows[i];
     const item = steering[i];
-    if (item !== void 0 && row.text === (item.text ?? "")) {
-      matched.push(item.id);
-    } else {
-      matched.push(null);
-    }
+    matched.push(item !== void 0 && matches2(item, row) ? item.id : null);
   }
   return matched;
 }
+function matches2(item, row) {
+  if (item.attachments > 0) return row.attachments === item.attachments;
+  return row.text === (item.text ?? "");
+}
 function retractSpan(steering, targetId) {
   const index = steering.findIndex((item) => item.id === targetId);
   if (index === -1) return [];
@@ -883,7 +920,7 @@ function userNodeOf(chat, key) {
   if (node === void 0 || node.kind !== "user" && node.kind !== "steering") return void 0;
   return node.data;
 }
-async function runRewindAndFill(session, seq, mode, isMainViewSession, chatOf, watchChat, setComposerText) {
+async function runRewindAndFill(session, seq, mode, isMainViewSession, chatOf, watchChat, setComposerText, restoreImages) {
   const known = knownCommandSeqs(session, chatOf, (node) => isExecutedRewindCommand(node, seq));
   let result;
   try {
@@ -919,12 +956,22 @@ async function runRewindAndFill(session, seq, mode, isMainViewSession, chatOf, w
     return;
   }
   let text;
+  let images;
   try {
-    text = messageTextAt(chatOf(session), seq);
+    const chat = chatOf(session);
+    text = messageTextAt(chat, seq);
+    images = messageAttachmentsAt(chat, seq);
   } catch (error) {
-    rewindLog.warn("refill", `reading target text for @${seq} threw`, error);
+    rewindLog.warn("refill", `reading target content for @${seq} threw`, error);
     return;
   }
+  if (restoreImages !== void 0 && images !== void 0 && images.length > 0) {
+    try {
+      await restoreImages(session.sessionId, images);
+    } catch (error) {
+      rewindLog.warn("refill", `image restore for @${seq} threw`, error);
+    }
+  }
   if (text === void 0 || text === "") {
     return;
   }
@@ -968,6 +1015,7 @@ function resolveSeatAnchorSeq(element, chat) {
   return node?.anchorSeq;
 }
 var PENDING_SEAT_SELECTOR = "[data-pending-steering]";
+var MESSAGE_ATTACHMENT_SELECTOR = "[data-message-attachments]";
 function actionsContainerOf(row) {
   const buttons = Array.from(row?.querySelectorAll("button") ?? []);
   const lastButton = buttons.filter((button) => !button.classList.contains(CLASS.button)).at(-1);
@@ -1041,16 +1089,16 @@ var INBOX_PROJECTION = "inbox";
 function bubbleTextOf(row) {
   const clone = row.cloneNode(true);
   clone.lastElementChild?.remove();
-  return clone.textContent ?? "";
+  const originals = row.querySelectorAll(MESSAGE_ATTACHMENT_SELECTOR);
+  const copies = clone.querySelectorAll(MESSAGE_ATTACHMENT_SELECTOR);
+  for (let index = 0; index < copies.length; index++) copies[index]?.remove();
+  return { text: clone.textContent ?? "", attachments: originals.length };
 }
 function collectPendingTargets(snapshot, steering) {
   if (snapshot.subagent !== null) return [];
   if (steering.length === 0) return [];
   const rows = Array.from(document.querySelectorAll(PENDING_SEAT_SELECTOR));
-  const matched = matchPendingRows(
-    rows.map((row) => ({ text: bubbleTextOf(row) })),
-    steering
-  );
+  const matched = matchPendingRows(rows.map(bubbleTextOf), steering);
   const targets = [];
   for (let i = 0; i < matched.length; i++) {
     const itemId = matched[i];
@@ -1079,7 +1127,7 @@ function sameTargets(left, right) {
     return other.kind === "pending" && target.itemId === other.itemId;
   });
 }
-function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText }) {
+function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText, restoreImages }) {
   const [targets, setTargets] = (0, import_react.useState)([]);
   const hidden = (0, import_react.useRef)(/* @__PURE__ */ new WeakSet());
   const [, forceRender] = (0, import_react.useReducer)((count) => count + 1, 0);
@@ -1166,6 +1214,7 @@ function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchC
         watchChat,
         isMainViewSession,
         setComposerText,
+        restoreImages,
         t
       },
       target.key
@@ -1174,7 +1223,7 @@ function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchC
     target.key
   ));
 }
-function RewindButton({ target, sessionId, sessionOf, chatOf, watchChat, isMainViewSession, setComposerText, t }) {
+function RewindButton({ target, sessionId, sessionOf, chatOf, watchChat, isMainViewSession, setComposerText, restoreImages, t }) {
   const onClick = (event) => {
     event.stopPropagation();
     const session = sessionOf(sessionId);
@@ -1194,7 +1243,7 @@ function RewindButton({ target, sessionId, sessionOf, chatOf, watchChat, isMainV
       anchor: event.currentTarget,
       t,
       onRewind: (mode) => {
-        void runRewindAndFill(session, node.seq, mode, isMainViewSession, chatOf, watchChat, setComposerText);
+        void runRewindAndFill(session, node.seq, mode, isMainViewSession, chatOf, watchChat, setComposerText, restoreImages);
       }
     });
   };
@@ -1271,9 +1320,9 @@ function createRewindBridge(deps) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.14.0" : "dev";
+var PLUGIN_VERSION = true ? "0.15.0-beta.2" : "dev";
 var PLUGIN_PACKAGE = "dsh-rewind-plugin";
-var BUILD_HASH = true ? "09b74c90" : "dev";
+var BUILD_HASH = true ? "0582c3a6" : "dev";
 
 // src/client/locales.ts
 var zh = {
@@ -1490,6 +1539,48 @@ function apply(ctx) {
         }
       };
     };
+    const IMAGE_MEDIA_EXTENSION = {
+      "image/png": "png",
+      "image/jpeg": "jpg",
+      "image/webp": "webp",
+      "image/gif": "gif"
+    };
+    const restoreImages = async (sessionId, images) => {
+      if (images.length === 0) return;
+      const ui = uiConversation();
+      const conversation = ctx.get("conversation");
+      const scope = ctx.sessions.scope?.(sessionId);
+      if (ui?.imageUrl === void 0 || conversation?.input === void 0 || conversation.createDrafts === void 0 || scope === void 0) {
+        rewindLog.warn("refill", "image restore unavailable (conversation services not ready)");
+        return;
+      }
+      const files = [];
+      for (const [index, ref] of images.entries()) {
+        const extension = IMAGE_MEDIA_EXTENSION[ref.mediaType];
+        if (extension === void 0) {
+          rewindLog.warn("refill", `skipping image with unsupported type ${ref.mediaType}`);
+          continue;
+        }
+        try {
+          const url = await ui.imageUrl(sessionId, ref);
+          const blob = await (await fetch(url)).blob();
+          files.push(new File([blob], ref.name ?? `image-${index + 1}.${extension}`, { type: ref.mediaType }));
+        } catch (error) {
+          rewindLog.warn("refill", `image fetch threw for ${ref.attachmentId}`, error);
+        }
+      }
+      if (files.length === 0) return;
+      try {
+        const drafts = conversation.createDrafts(sessionId, files);
+        const admitted = conversation.input.for(scope).addAttachments(drafts.map((draft) => draft.id));
+        if (!admitted) {
+          rewindLog.warn("refill", `composer refused ${drafts.length} restored image(s) (busy)`);
+          conversation.releaseDraftAttachments?.(drafts);
+        }
+      } catch (error) {
+        rewindLog.warn("refill", "image restore threw", error);
+      }
+    };
     const setComposerText = (sessionId, text) => {
       try {
         return writeComposer(text, composerFacade(sessionId));
@@ -1525,7 +1616,7 @@ function apply(ctx) {
         id: "dsh-rewind-portals",
         order: 1e3
       },
-      createRewindBridge({ sessionOf, chatOf, isMainViewSession, watchChat, setComposerText, t, subscribeLocale })
+      createRewindBridge({ sessionOf, chatOf, isMainViewSession, watchChat, setComposerText, restoreImages, t, subscribeLocale })
     ));
     try {
       const { store, form } = cleanupForm(
@@ -1599,7 +1690,7 @@ function apply(ctx) {
             anchor: composerAnchor(),
             t,
             onRewind: (mode) => {
-              void runRewindAndFill(face, candidate.seq, mode, isMainViewSession, chatOf, watchChat, setComposerText);
+              void runRewindAndFill(face, candidate.seq, mode, isMainViewSession, chatOf, watchChat, setComposerText, restoreImages);
             }
           });
         }

package/lib/index.js

@@ -24,6 +24,8 @@ var en = {
   "skipReason.oversized": "over the {limit} backup limit, so the recorded state predates untracked edits",
   "uncovered.header": "{count} tracked file(s) exceed the {limit} backup limit and are not covered:",
   "error.invalidTarget": 'Cannot parse target "{raw}" (expected <index> or @<seq>)',
+  "sep.list": ", ",
+  "sep.clause": "; ",
   "failures.suffix": "; {count} file(s) failed to restore: {list}",
   "failures.item": "{path} ({message})",
   "inflight": "A rewind is already running for this session; please wait.",
@@ -77,6 +79,8 @@ var zh = {
   "skipReason.oversized": "\u5DF2\u8D85\u8FC7 {limit} \u7684\u5907\u4EFD\u4E0A\u9650\uFF0C\u8BB0\u5F55\u7684\u72B6\u6001\u65E9\u4E8E\u672A\u88AB\u8DDF\u8E2A\u7684\u4FEE\u6539",
   "uncovered.header": "{count} \u4E2A\u5DF2\u8DDF\u8E2A\u6587\u4EF6\u8D85\u8FC7 {limit} \u7684\u5907\u4EFD\u4E0A\u9650\uFF0C\u672A\u7EB3\u5165\u8BB0\u5F55\uFF1A",
   "error.invalidTarget": '\u65E0\u6CD5\u89E3\u6790\u76EE\u6807 "{raw}"\uFF08\u5E94\u4E3A <\u5E8F\u53F7> \u6216 @<seq>\uFF09',
+  "sep.list": "\u3001",
+  "sep.clause": "\uFF1B",
   "failures.suffix": "\uFF1B{count} \u4E2A\u6587\u4EF6\u8FD8\u539F\u5931\u8D25\uFF1A{list}",
   "failures.item": "{path}\uFF08{message}\uFF09",
   "inflight": "\u8BE5\u4F1A\u8BDD\u5DF2\u6709\u4E00\u4E2A\u56DE\u9000\u6B63\u5728\u6267\u884C\uFF0C\u8BF7\u7A0D\u5019\u3002",
@@ -149,15 +153,21 @@ function messagePreview(message) {
   const text = message.content.map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").join("").replace(/\s+/g, " ").trim();
   return text.length <= CANDIDATE_PREVIEW_CHARS ? text : `${text.slice(0, CANDIDATE_PREVIEW_CHARS - 1)}\u2026`;
 }
+var SEQ_TOKEN = /^@(\d+)$/;
+var INDEX_TOKEN = /^(\d+)$/;
 function parseRewindTarget(raw) {
   const token = raw.trim();
-  if (token === "") return void 0;
-  if (token.startsWith("@")) {
-    const seq = Number(token.slice(1));
-    return Number.isSafeInteger(seq) && seq >= 0 ? { kind: "seq", seq } : void 0;
+  const seq = SEQ_TOKEN.exec(token);
+  if (seq !== null) {
+    const value = Number(seq[1] ?? "");
+    return Number.isSafeInteger(value) ? { kind: "seq", seq: value } : void 0;
   }
-  const index = Number(token);
-  return Number.isSafeInteger(index) && index >= 1 ? { kind: "index", index } : void 0;
+  const index = INDEX_TOKEN.exec(token);
+  if (index !== null) {
+    const value = Number(index[1] ?? "");
+    return Number.isSafeInteger(value) && value >= 1 ? { kind: "index", index: value } : void 0;
+  }
+  return void 0;
 }
 function listRewindCandidates(events, surface, limit = DEFAULT_CANDIDATE_LIMIT) {
   const surfaceIndexes = /* @__PURE__ */ new Map();
@@ -2517,7 +2527,7 @@ function renderFailures(failed) {
   if (failed.length === 0) return "";
   return t("failures.suffix", {
     count: failed.length,
-    list: failed.map((f) => t("failures.item", { path: f.path, message: f.message })).join("\u3001")
+    list: failed.map((f) => t("failures.item", { path: f.path, message: f.message })).join(t("sep.list"))
   });
 }
 function renderSkipped(outcome, uncovered, maxFileBytes) {
@@ -2620,7 +2630,7 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
       } catch (error) {
         if (!(error instanceof UnknownStoreVersionError)) throw error;
         const version = await store.readStoreVersion(agent.session.id);
-        restore = `\uFF1B${t("storeUnsupported", { version: version ?? error.version })}`;
+        restore = `${t("sep.clause")}${t("storeUnsupported", { version: version ?? error.version })}`;
       }
       if (outcome !== void 0) {
         await syncRestoreObservations(ctx, fs, agent, outcome);
@@ -2633,7 +2643,7 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
           const skippedLines = renderSkipped(outcome, capped, store.fileCapBytes);
           if (skippedLines !== "") parts.push(skippedLines);
         }
-        restore = parts.length > 0 ? `\uFF1B${parts.join("\u3001")}` : t("noRestorable");
+        restore = parts.length > 0 ? `${t("sep.clause")}${parts.join(t("sep.list"))}` : t("noRestorable");
         restore += renderFailures(outcome.failed);
       }
     }

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

@@ -74,12 +74,6 @@ export declare function formatCandidateTime(time: number): string;
 export declare function rewindCandidatesOf(snap: CandidateChat, hidden: ReadonlySet<number>, limit?: number): RewindCandidate[];
 /** The candidates of a live chat snapshot, withdrawn rows already excluded. */
 export declare function rewindCandidatesOfChat(snap: CandidateChat): RewindCandidate[];
-/**
- * Map the candidates to popupSelect rows: the message preview as the row
- * label (left) and the clock time as the detail (right) — the shell's native
- * label/detail flex layout, with no recency numbers.
- */
-export declare function rewindOptionsOf(snap: CandidateChat, t: Translate): SelectOption[];
 /**
  * Parse the host's candidate-list encoding (see `formatCandidateList` in
  * src/rewind.ts) into typed candidates. Malformed lines are skipped; a
@@ -92,9 +86,4 @@ export declare function rewindCandidatesFromHostText(text: string): RewindCandid
  * `__candidates` channel instead of the windowed chat snapshot.
  */
 export declare function rewindOptionsFromCandidates(candidates: readonly RewindCandidate[], t: Translate): SelectOption[];
-/**
- * Parse the host's candidate-list encoding (see `formatCandidateList` in
- * src/rewind.ts) into popupSelect rows.
- */
-export declare function rewindOptionsFromHostText(text: string, t: Translate): SelectOption[];
 export {};

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

@@ -60,11 +60,42 @@ export declare function chatSnapshotOf(chatView: {
  * filling the composer after a withdraw. Accepts BOTH `user` and `steering`
  * nodes: a plan-mode (`/plan <text>`) input is delivered through the agent
  * inbox next-step and claimed, so it renders as `steering`, and its text must
- * still return to the composer (`portals.tsx` `runRewindAndFill`) — the old
- * `user`-only read silently left it empty. State absent → undefined; a message
- * with no text blocks → ''. Same text-blocks join the candidate side uses.
+ * still return to the composer (`portals.tsx` `runRewindAndFill`). State absent
+ * → undefined; a message with no text blocks → ''. Same text-blocks join the
+ * candidate side uses.
  */
 export declare function messageTextAt(chat: HiddenChat | undefined, seq: number): string | undefined;
+/**
+ * A durable image reference carried by an `image` content block in the chat
+ * snapshot, read structurally (the harness's `ImageAttachmentRef` from
+ * dsh-attachment, without importing it, so the plugin survives harness
+ * drift). Fields beyond `attachmentId`/`mediaType` pass through to the
+ * durable image URL loader unchanged.
+ */
+export interface MessageImageRef {
+    readonly attachmentId: string;
+    readonly mediaType: string;
+    readonly bytes?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly name?: string;
+}
+/**
+ * The durable image references of the human message at `seq` in the chat
+ * snapshot, in message order. The composer-refill counterpart of
+ * `messageTextAt` (see `portals.tsx` `runRewindAndFill`): rewinding an
+ * image-bearing message restores its pictures into the composer so the
+ * withdraw does not silently drop them.
+ *
+ * Reads the same node kinds as `messageTextAt` (`user` and `steering`).
+ * Blocks tolerate malformed or missing references (skipped, never a throw),
+ * and `image/offload` projections leave the durable reference in place —
+ * which is all the URL loader needs. `file` blocks are intentionally
+ * excluded: the harness exposes no client-side file-bytes loader (file
+ * uploads go one-way), so a file is not restorable.
+ * State absent → undefined; a message without images → [].
+ */
+export declare function messageAttachmentsAt(chat: HiddenChat | undefined, seq: number): readonly MessageImageRef[] | undefined;
 /**
  * Extract the rewind target seq from a `/rewind` command's structured `args`
  * (e.g. `@5 chat`, `preview @5 both`). Locale-independent — never parses the
@@ -98,25 +129,16 @@ export declare function hasFileImpact(text: string | undefined): boolean;
  */
 export declare function isCandidateCommand(command: CommandNode): boolean;
 /**
- * Anchor seqs that must be hidden from the rendered transcript so the user
- * sees the conversation as the agent sees it: every impact-preview flow node
- * (pending, succeeded, or errored — it only exists to feed the popover) and
- * every SUCCESSFUL executed `/rewind` command row, plus every message
- * withdrawn by a rewind — the target message itself, everything after it, and
- * the (unrendered) marker.
- *
- * Each executed rewind cuts ONE span `[target, marker]`: the target message
- * and everything after it, up to the marker appended at rewind time. Spans are
- * kept SEPARATE (never collapsed to a single `[min target, max marker]`)
- * because a later rewind to a LATER point leaves a visible gap of new traffic
- * between the earlier marker and the later target — collapsing the spans would
- * hide that still-on-surface gap. Endpoints come from the command nodes:
- * `sourceEventSeq` is the marker's log seq, and the outcome text carries the
- * target seq.
+ * Anchor seqs that must be hidden from the rendered transcript so the user sees
+ * the conversation as the agent sees it: every impact-preview flow node (it only
+ * exists to feed the popover) and every SUCCESSFUL executed `/rewind` command
+ * row, plus every message a rewind withdrew — the target, everything after it,
+ * and the (unrendered) marker.
  *
- * The spans are coalesced into disjoint ascending ranges before the membership
- * test, so a node costs one binary search instead of a scan of every rewind's
- * range: that keeps the walk linear in the nodes rather than in nodes ×
- * rewinds, on a pass that runs for every chat mutation.
+ * Each executed rewind cuts ONE span `[target, marker]`, and callers must keep
+ * the spans SEPARATE: collapsing them to `[min target, max marker]` would hide a
+ * still-on-surface gap of new traffic between an earlier marker and a later
+ * target. Endpoints come from the command nodes (`sourceEventSeq` is the
+ * marker's log seq; the outcome text carries the target seq).
  */
 export declare function hiddenSeqsOf(snap: HiddenChat): Set<number>;

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

@@ -1,28 +1,16 @@
 /**
  * dsh-rewind client half: the `/rewind` command decoration, the locale
  * registration, and the session-scoped portal bridge that renders the
- * per-message ↶ rewind button (see
- * `portals.tsx` for the button itself).
+ * per-message ↶ rewind button (`portals.tsx` owns the button and the popover).
  *
- * The button is NOT injected by hand into the DOM anymore: the plugin
- * registers a bridge into the harness's `conversation.session.header.actions`
- * list slot, and that bridge portals a React button into every user message's
- * IconActions row — the same rendering family as the copy button (a React
- * child of the actions row), without touching any harness source. The
- * registration is typed structurally (see `SlotsLike` in portals.tsx), so the
- * plugin never imports conversation UI types and survives harness version
- * drift.
- *
- * The text-driven flow is the harness's STANDARD command decoration
- * (`ctx.commandUi.decorate`): a bare `/rewind` (or its alias `/undo`) —
- * picked from the slash-menu completion, or typed in full and Entered —
- * opens the harness's own popupSelect shell (search, ↑↓/Enter, Esc) listing
- * the rewind candidates instead of executing the command. Picking one
- * continues the SAME flow as the ↶ button: the mode popover, both-impact
- * confirmation, execution, row hiding and the composer refill
- * (`runRewindAndFill`). The parameterized forms (`/rewind @<seq> chat|both`,
- * `/rewind preview …`) stay internal channels the ↶ button and the popover
- * drive through `session.command`.
+ * The button registers through the harness's
+ * `conversation.session.header.actions` slot — a typed structural registration,
+ * so the plugin imports no conversation UI types and survives harness drift.
+ * The command decoration (`ctx.commandUi.decorate`) makes a bare `/rewind` (or
+ * its alias `/undo`) open the harness's own popupSelect instead of executing;
+ * the parameterized `@<seq>` / `preview` forms stay internal channels the
+ * button and the popover drive. The exported contract is specified in
+ * `docs/contract/client-contract.md`.
  *
  * @module dsh-rewind/client
  */

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

@@ -1,25 +1,17 @@
 /**
- * dsh-rewind client logger: a single, namespaced, level-filtered logging
- * channel for every browser-side diagnostic in this plugin.
+ * dsh-rewind client logger: one namespaced, level-filtered channel for every
+ * browser-side diagnostic in this plugin.
  *
- * Design (industry-normal layering, kept dependency-free):
- * - `error` / `warn` are ALWAYS emitted (they are the anomaly guard: rare,
- *   cheap, and must surface even for a user who never touched the switch).
- * - `info` / `debug` are gated by a DEBUG switch and further filtered by
- *   namespace, so verbose detail never floods a normal user's console.
+ * `error` / `warn` are ALWAYS emitted (the anomaly guard: rare, cheap, and
+ * surfaced even for a user who never touched the switch). `info` / `debug` are
+ * gated by the exclusively-own, per-origin `localStorage['dsh-rewind.debug']`
+ * switch and further filtered by namespace. The switch is read on every call
+ * (never cached), so flipping it and reloading takes effect on any published
+ * build without a plugin rebuild.
  *
- * The DEBUG switch is a runtime, per-origin knob read from
- * `localStorage['dsh-rewind.debug']` — the convention-debug-scan pattern
- * (namespace match, comma-separated, `*` wildcard), scoped to an
- * exclusively-own key so it can never enable any other plugin/feature and no
- * other feature can wake this one. Because it is read on every call (never
- * cached), flipping it and reloading takes effect on any published build
- * without a plugin rebuild.
- *
- * Values accepted by the switch (empty/unset = off):
- * - `dsh-rewind*`  — every dsh-rewind namespace.
- * - `dsh-rewind:refill` — just one subsystem (exact match).
- * - `dsh-rewind:refill,dsh-rewind:hiding` — several (comma-separated).
+ * Values accepted (empty/unset = off): `dsh-rewind*` — every namespace;
+ * `dsh-rewind:refill` — one subsystem (exact match);
+ * `dsh-rewind:refill,dsh-rewind:portals` — several (comma-separated).
  *
  * @module dsh-rewind/client/log
  */

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

@@ -3,12 +3,14 @@
  * bubble rows with the session's `next-step` inbox rows.
  *
  * Both sides follow the same host order, so index-primary matching is reliable;
- * text equality is still verified per row, and a row that fails (or has no
+ * the match key is still verified per row, and a row that fails (or has no
  * counterpart) is skipped INDIVIDUALLY: one bad row never takes down the other
- * rows' buttons. The compared text excludes the bubble's actions container —
- * the copy button's Tooltip mounts a label bubble there on hover, so the row's
- * full `textContent` would flip between "message" and "message+Copy" with the
- * mouse (see `bubbleTextOf` in portals.tsx).
+ * rows' buttons. The key is `(text, attachment count)`: exact text for a
+ * text-only message, the count for one that carries attachments — whose
+ * rendered attachment block contributes text no inbox row reproduces.
+ *
+ * The compared text excludes the bubble's actions container and its
+ * message-attachment block (see `bubbleTextOf` in portals.tsx).
  *
  * The browser half lives in `portals.tsx`; this module stays DOM-free so the
  * matching contract is unit-testable in a plain node environment.
@@ -19,6 +21,8 @@
 export interface PendingRow {
     /** The bubble's message text, excluding the actions container (see module doc). */
     readonly text: string;
+    /** Message-attachment blocks the row renders; compared against the item's count. */
+    readonly attachments: number;
 }
 /** One wire content block of an inbox row (only the fields the derivation reads). */
 export interface InboxBlockLike {
@@ -51,8 +55,10 @@ export interface InboxLike {
 /** One steering occurrence derived from the session's inbox projection. */
 export interface PendingSteeringItem {
     readonly id: string;
-    /** Complete editable text; null when the message contains non-text blocks. */
+    /** Complete editable text; null when the message carries no text block at all. */
     readonly text: string | null;
+    /** Non-text blocks (image/file/…) the message carries, in prompt order. */
+    readonly attachments: number;
     /** Space-collapsed preview with image/file blocks excluded (the harness QueueDock rule). */
     readonly preview: string;
 }
@@ -72,11 +78,16 @@ export interface PendingSteeringItem {
  */
 export declare function steeringItemsOf(nextStep: readonly InboxMessageLike[] | undefined): readonly PendingSteeringItem[];
 /**
- * Pair rows to steering items by index, verifying text equality per row.
+ * Pair rows to steering items by index, verifying the match key per row: the
+ * visible text when the message has no attachments, otherwise the attachment
+ * count. Exact text equality cannot apply to an attachment-bearing row — which
+ * is why its ↶ button never mounted — because the rendered attachment block
+ * contributes text no inbox row reproduces.
+ *
  * @param rows - pending bubble rows in DOM order (== render order).
  * @param steering - steering items in host order (== render order).
  * @returns the item id for each row, or null for rows that cannot be matched
- *   safely (missing counterpart, text mismatch). A bad row never affects the
+ *   safely (missing counterpart, key mismatch). A bad row never affects the
  *   other rows.
  */
 export declare function matchPendingRows(rows: readonly PendingRow[], steering: readonly PendingSteeringItem[]): readonly (string | null)[];