dsh-diff-approval 0.29.1 → 0.31.0

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

@@ -5,13 +5,46 @@
  * @module dsh-diff-approval/client/port
  */
 import type { ClientConnectionRpc, SessionId } from '@deepseek-ai/dsh-client-connection/client';
-import type { DiffApprovalActionValue, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalBulkValue, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalPreviewImageValue, DiffApprovalRefreshValue, VcsImportValue } from '../types.ts';
+import type { CommentAnchor, CommentQuoteLine, DiffApprovalActionValue, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalBulkValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalListCountValue, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalPreviewImageValue, DiffApprovalRefreshValue, DiffApprovalUpdateValue, VcsImportValue } from '../types.ts';
 /** The channel the host half registers and this port calls. */
 export declare const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+/**
+ * One annotation as the panel hands it over: what the reader wrote and where they
+ * wrote it. The display path is not part of it — the entry a comment hangs off is the
+ * host's authority on what the file is called.
+ */
+export interface CommentDraft {
+    /** Caller-minted id, so a retried write lands on the same comment. */
+    id: string;
+    /** The listed entry the annotation hangs off. */
+    entryId: string;
+    /** The lines it was made on, as new-file line numbers. */
+    anchor: CommentAnchor;
+    /** The anchored lines as they read then (the re-anchor fingerprint). */
+    quote: string;
+    /** `quote` with one line of context on each side, as it read then. */
+    quoteContext?: string | undefined;
+    /** The gutter numbers of `quote`'s lines, in the same order. */
+    quoteLines?: CommentQuoteLine[] | undefined;
+    /** What the reader wrote. */
+    text: string;
+}
 /** This package's business verbs over the review channel. */
 export interface DiffApprovalPort {
     /** Read one session's pending entries (plus its workspace root), oldest capture first. */
     list(sessionId: SessionId): Promise<DiffApprovalListValue>;
+    /**
+     * Ask HOW MANY rows a full `list` read would carry for this session, reading no file content.
+     *
+     * This is the badge's own question: the full read ships every visible entry's whole old/new text
+     * (megabytes on a long-lived session), while the count costs one stat per visible row on the host and
+     * puts a single number on the wire. It is the SAME visibility rule as `list` on the host's side.
+     *
+     * A host that predates the endpoint throws instead — its handler answers `unknown endpoint
+     * "list-count"` — and the caller is expected to fall back to the full read (see
+     * `PendingDiffStore.refreshCount`), which is exactly the behaviour a page had before this verb existed.
+     */
+    listCount(sessionId: SessionId): Promise<DiffApprovalListCountValue>;
     /** Keep one operation. `keepListed` leaves the resolved entry in the list. */
     keep(sessionId: SessionId, id: string, keepListed?: boolean): Promise<DiffApprovalActionValue>;
     /** Revert one operation. `keepListed` leaves the resolved entry in the list. */
@@ -35,14 +68,57 @@ export interface DiffApprovalPort {
      * path must be one regular file: a directory is refused instead of being scanned.
      */
     addPath(sessionId: SessionId, path: string, includeUnchanged: boolean, exact?: boolean): Promise<DiffApprovalAddValue>;
+    /** Tell the host the reader is looking at a file: the row's unseen dot goes out. */
+    markSeen(sessionId: SessionId, id: string): Promise<void>;
     /** Open one file with its default application or reveal it in the folder. */
     open(sessionId: SessionId, id: string, action: DiffApprovalOpenAction): Promise<DiffApprovalOpenValue>;
     /** Keep every pending entry of one session in a single host call (one batch). */
     keepAll(sessionId: SessionId): Promise<DiffApprovalBulkValue>;
     /** Revert every pending entry of one session in a single host call (one batch). */
     revertAll(sessionId: SessionId): Promise<DiffApprovalBulkValue>;
+    /**
+     * Keep a PICK of entries in one host call: one request, one durable write and one undo step — the
+     * host records the whole pick as a single batch, so one Ctrl+Z takes that one decision back instead
+     * of peeling it apart file by file. `keepListed` says whether the resolved files stay listed.
+     *
+     * There is a `revertMany` beside it, and the pair is NOT symmetric: a keep writes nothing, while a
+     * revert writes the baseline over each file — and DELETES the ones the agent created, which the host
+     * cannot undo. The panel asks before sending a pick whose revert would delete anything.
+     */
+    keepMany(sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined): Promise<DiffApprovalBulkValue>;
+    /** Revert a PICK of entries in one host call: the same one request, one write, one undo step. The undo
+     *  restores the entries the host could snapshot — see `keepMany` for the deletes it cannot. */
+    revertMany(sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined): Promise<DiffApprovalBulkValue>;
     /** Read one workspace image and inline it as a base64 data URI (for the Markdown preview). */
     previewImage(sessionId: SessionId, path: string): Promise<DiffApprovalPreviewImageValue>;
+    /**
+     * Write one annotation down. The host refuses a comment whose entry is not in the
+     * session's list, and the refusal is reported rather than retried.
+     */
+    commentAdd(sessionId: SessionId, comment: CommentDraft): Promise<DiffApprovalCommentAddValue>;
+    /** Drop one annotation (what "a comment dies with its entry" does by hand). */
+    commentRemove(sessionId: SessionId, id: string): Promise<DiffApprovalCommentRemoveValue>;
+    /**
+     * Drop several annotations in one host call: one request, one write of the session's comment file,
+     * and one read afterwards (`store.commentRemoveMany`). A batch that is a loop of `commentRemove`
+     * calls is a different thing — N requests, N writes — which is what this endpoint exists to avoid.
+     */
+    commentRemoveMany(sessionId: SessionId, ids: readonly string[]): Promise<DiffApprovalCommentRemoveManyValue>;
+    /** Asks one stored comment as its own turn of the session. */
+    commentAsk(sessionId: SessionId, id: string, prompt: string, text: string): Promise<DiffApprovalCommentAskValue>;
+    /** Tell the host the reader is looking at a comment: the card's unseen dot goes out. */
+    commentSeen(sessionId: SessionId, id: string): Promise<void>;
+    /**
+     * Ask whether a newer release of this plugin is published, and what changed since the
+     * installed one.
+     *
+     * No session is named: the answer is about the PACKAGE, not about a review. The host owns
+     * the whole question — it reads its own `package.json`, reaches the registry (a browser
+     * may not: no CORS header there) and decides `newer` — so a caller only has to render the
+     * answer. A host that predates the endpoint answers `unknown endpoint "update-check"`, and
+     * the caller is expected to ignore that failure exactly as it ignores a network one.
+     */
+    checkUpdate(): Promise<DiffApprovalUpdateValue>;
 }
 /** Build the port over one generic RPC caller.
  * @param rpc - the connection's channel caller.

package/lib/types/client/presentation-menu.d.ts

@@ -13,7 +13,7 @@
  * @module dsh-diff-approval/client/presentation-menu
  */
 import type { ReactNode } from 'react';
-import type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { MenuEntry } from './dsh-icons.ts';
 import type { DiffApprovalPresentation } from './settings.ts';
 import type { Translator } from './locales.ts';
 /**

package/lib/types/client/produced-diff.d.ts

@@ -1,27 +1,141 @@
 /**
- * Inject a "查看差异" button beside each DSH produced-file chip.
- *
- * The harness's `ProducedFiles` component renders each produced file as a
- * `<button>` chip inside `[data-produced-files-row]`; the full path rides the
- * chip's `title`. This plugin wants a quick "view this file's diff" affordance
- * there, but the plugin should not have to touch the harness component. So this
- * module watches the DOM for those chips (via a MutationObserver, the same
- * bridge the dsh-pocket mobile fork uses to inject its 复制 buttons) and injects
- * a small button after each one. Clicking it dispatches a window event that the
- * diff-approval panel listens for (see PendingPanel), which opens the panel and
- * selects the file when it is still pending, or toasts otherwise.
- *
- * The injected button is intentionally self-contained (inline styles + a fixed
- * label) so it needs no stylesheet and no harness change.
+ * Route a file press's own click.
+ *
+ * The harness draws several presses that answer by opening a file in a viewer of its OWN, and this
+ * module takes over exactly those — and only for a file the review panel is already holding — so the
+ * reader gets both ways of opening it instead of one fixed behaviour:
+ *
+ *   `[data-produced-files-row] button`    0.1.5's produced-file card       `title` = the path
+ *   `[data-presented-files-row] button`   0.1.7's presented-file card      `title` = the path
+ *   `[data-changed-files] button`         0.1.7's changed-files row        `aria-describedby` = the path
+ *   `button[title]`                       a message's file LINK (0.1.7)    `title` = the path
+ *   `button[data-ref-chip]`               a `@file` chip in a message      `title` = the token
+ *   `a[href]`                             any other link naming a file     `href`  = the path
+ *
+ * Everything else is left entirely alone: a link to a URL, an in-page anchor, a chip naming something
+ * that is not a file, a file LINK whose file this panel does not hold, a modified press (Ctrl/Cmd/Shift/
+ * Alt, or a middle click — gestures the harness may give its own meaning later), and any press inside this
+ * plugin's own surface, whose buttons carry paths too and belong to the panel that is already showing
+ * the file. A file-list ROW is the one press taken over whether or not the panel holds its file (see
+ * `ROW_SELECTOR`); "we do not hold it" then decides what the menu offers, not whether it appears.
+ *
+ * The name of the module (and of the event it raises) dates from when the produced-file card was the
+ * only press of this kind; `data-presented-files-row` is that same list under 0.1.7's name for it.
  */
-/** Window event dispatched by the injected button; PendingPanel listens for it. */
+import type { PendingDiffSnapshot } from './slots.ts';
+/** Window event dispatched when a pending file's press is taken over; the panel listens for it. */
+export declare const CHIP_MENU_EVENT = "diff-approval:chip-menu";
+/**
+ * Whether the page HOLDS this path — the `held` label a press carries into the menu.
+ *
+ * It is a LABEL now, not a gate: every file-list row's press becomes the menu regardless, and `held` only
+ * decides whether "在审批面板中查看" opens the row directly or adds it first (see `PendingPanel`). It is
+ * answered from the views the page is holding, i.e. from the last FULL read of each session: while every
+ * surface is shut nothing re-reads the list, so a row edited since then is labelled not-held. That is
+ * acceptable rather than hidden: the add answers the truth (a path already listed comes back `duplicate` and
+ * selects the same entry), so the item still opens the file — one request later. What the label must not do
+ * is claim a row exists that does not: `false` errs towards adding, never towards acting on nothing.
+ * @param views - the views this page is holding, one per session it has read (see `PendingDiffStore.views`).
+ * @param path - the path a press named.
+ * @returns whether any held view holds it.
+ */
+export declare function panelHolds(views: readonly PendingDiffSnapshot[], path: string): boolean;
+/** Window event dispatched by the panel to open a file in the panel; PendingPanel listens for it. */
 export declare const OPEN_FILE_EVENT = "diff-approval:open-file";
+/** What a press tells the panel: which file, where the press was (the menu hangs under it), and whether
+ *  the review list already holds that file. */
+export interface ProducedChipMenuDetail {
+    /** The path the pressed element names. */
+    path: string;
+    /** The pressed element's own box, in viewport coordinates. */
+    x: number;
+    y: number;
+    /**
+     * Whether the review list holds this path right now.
+     *
+     * It decides what the menu's items DO, never whether the menu appears: a row press always becomes the
+     * menu, and "not held" is what makes "在审批面板中查看" add the path first (see `PendingPanel`). It is
+     * also what a future item that NEEDS a listed entry has to gate on — pressing keep or revert for a file
+     * the host is not holding would simply fail.
+     */
+    held: boolean;
+    /**
+     * The session the press belongs to, when its own surface says so.
+     *
+     * WITHOUT THIS the panel can only ask the session IT is showing to add the path, and the host resolves that
+     * path against that session's workspace: a press in session A's transcript while the panel is still bound
+     * to session B answers `outside` ("路径不在当前工作区内") — measured, and it was the reader's bug: the first
+     * press refused and the second worked, because by then the panel had followed the shell's selection.
+     *
+     * Read from the ANCESTORS of the pressed element only (see `sessionOfPress`), and `undefined` when none of
+     * them names a session. That is the honest half: the panel then asks its own session and, if the host
+     * refuses, says so with the wording that names what was checked rather than blaming the path.
+     */
+    sessionId?: string | undefined;
+}
+/** What the bridge needs from the host to decide, and to report. */
+export interface ProducedChipBridge {
+    /**
+     * Whether the review list holds this path right now.
+     *
+     * A LABEL, not a gate: it rides every press this bridge takes over (a file-list row and a message's file
+     * link alike) and decides only what the menu's items DO — see `held` above. It is called synchronously on
+     * every press because that is when the menu is raised, and there is no second chance at a press.
+     */
+    isPending: (path: string) => boolean;
+    /** A pending file's press was taken over: open the menu the press asked for. */
+    onMenu: (detail: ProducedChipMenuDetail) => void;
+    /**
+     * Whether this plugin's file menu is MOUNTED at all — the reader's setting, read at press time.
+     *
+     * `false` leaves every press exactly as DSH has it: no menu, no `preventDefault`, not even a path lookup,
+     * so the plugin's presence is indistinguishable from it never having loaded. It is read per press rather
+     * than latched, because the setting can be switched while the page is open.
+     *
+     * ABSENT means enabled: a host, or a test, that offers no setting keeps the behaviour this bridge has
+     * always had.
+     */
+    enabled?: (() => boolean) | undefined;
+}
+/**
+ * Press a file's own press again — the shell's open, run the only way this plugin can run it
+ * faithfully, with the bridge standing down for that press (see the file's own doc).
+ *
+ * The menu's first row must open the file exactly the way the shell does, and what that is is the
+ * shell's business, not this plugin's: pressing the same element again keeps every part of it —
+ * the viewer it opens, the line a `#L24` suffix asked for, whatever a future shell adds there.
+ *
+ * @param path - the file the press names.
+ * @returns whether an element naming it was found to press.
+ */
+export declare function replayFilePress(path: string): boolean;
 /**
- * Start injecting diff buttons into the produced-files row.
- * @param label - localized "查看差异" text, used as the icon button's accessible
- *   name + hover title (the button renders only an icon).
- * @param openPath - called with a produced-file path when its injected button is
- *   clicked; the diff-approval panel decides whether that file is still pending.
- * @returns a cleanup that disconnects the observer and removes injected buttons.
+ * The session a press belongs to, read from the pressed element's OWN surface.
+ *
+ * Ancestors only, and the NEAREST ancestor that names a session wins — whichever spelling it uses:
+ *
+ *   `data-row-key="session:<id>"`  a session-LIST item, measured by this repo's e2e harness. Right for a
+ *                                  press raised inside the sidebar, and NOT an ancestor of a transcript
+ *                                  chip (measured on the live shell: exactly one such element in the whole
+ *                                  document, and it does not contain the chip).
+ *   `data-conversation-session`    the conversation BODY, measured on the live shell — this is the one that
+ *                                  covers the reader's press, a chip inside a message.
+ *   `data-session-id`              unmeasured alternative spelling, kept as a last resort.
+ *
+ * Walking the chain rather than asking three separate `closest` queries is what makes "nearest wins" true
+ * across spellings: a chip inside a session row that ALSO nests a conversation body takes the nearer
+ * body's session. A document-wide search is still deliberately NOT done — an identity hit may be a SIBLING,
+ * an `href` or an `aria-controls`, and guessing which session a press belongs to would be worse than not
+ * knowing: a wrong guess would ask a THIRD session to add the file, which this can never do.
+ *
+ * @param press - the element the press landed on.
+ * @returns the session id, or undefined when no ancestor names one.
+ */
+export declare function sessionOfPress(press: Element): string | undefined;
+/**
+ * Start routing the presses that would open a file in the shell's own viewer.
+ *
+ * @param bridge - the host's decision (is the file pending) and where to report a press that is.
+ * @returns a cleanup that stops routing.
  */
-export declare function startProducedDiffInjection(label: string, openPath: (path: string) => void): () => void;
+export declare function startProducedChipMenu(bridge: ProducedChipBridge): () => void;

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

@@ -5,8 +5,6 @@
  * the panel.
  * @module dsh-diff-approval/client/reference
  */
-/** The marker that replaces a reference's line number when its lines are gone. */
-export declare const LINE_MISSING_LABEL = "LINE_MISSING";
 /**
  * Last path segment of a file path, any separator style.
  * @param path - the path to shorten.

package/lib/types/client/remap-sync.d.ts

@@ -6,6 +6,7 @@
  * `reference.ts`.
  * @module dsh-diff-approval/client/remap-sync
  */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { PendingDiffStore } from './store.ts';
 /** One queued message's minimal content block; text blocks carry `text`, and every other kind passes through verbatim. */
 interface QueueBlock {
@@ -28,6 +29,22 @@ export interface ReferenceRemapOpts {
     readQueue: () => readonly QueueMessage[];
     /** Apply an edit mutation to one queued message's full content. */
     writeQueue: (itemId: string, content: readonly QueueBlock[]) => void;
+    /**
+     * The session whose list this sync follows and whose view supplies the workspace path, read per
+     * observation.
+     *
+     * The pending list is per session now, and the draft and the queue this sync rewrites belong to the
+     * session the page is SHOWING (see `shownSessionId`): observing another session's files would remap one
+     * session's references inside another session's composer. It must not be a pointer to whichever mount
+     * refreshed last either — with a dock tab on one session and the header on another, alternating polls
+     * moved that pointer about once a second and dropped these baselines with it, so a file that really
+     * changed was only ever re-seeded and never remapped. The baselines are still dropped when this answers
+     * a DIFFERENT session, so a session switch seeds fresh baselines instead of reading as "file changed".
+     *
+     * Absent, the page-wide view is observed instead — the same fallback a reader with no session gets
+     * (`viewFor(undefined)`, which answers the newest read).
+     */
+    sessionId?: (() => SessionId | undefined) | undefined;
 }
 /**
  * Subscribe to the pending store and remap references as each file's content
@@ -39,6 +56,6 @@ export interface ReferenceRemapOpts {
  */
 export declare function attachReferenceRemap(opts: ReferenceRemapOpts): {
     unsubscribe: () => void;
-    remapFile: (path: string, oldText: string, newText: string) => void;
+    remapFile: (sessionId: SessionId, path: string, oldText: string, newText: string) => void;
 };
 export {};

package/lib/types/client/session-seat.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Which session the review is about, as every shell of this plugin has offered it.
+ *
+ * 0.1.7 changed how a client learns the selected session. Its session-list store carries
+ * `{ ids, byId, phase, projectionsBySession }` — there is no `current` any more — and the shell's own
+ * components take the id from their composed SLOT PROPS instead (`const { sessionId, useSessions } =
+ * props`, then `useSessions(s => s.byId[sessionId]?.blank)`; measured in `dsh-client-ui-conversation`
+ * and `dsh-client-ui-agent-preset`). Older shells put it in the store as `state.current`.
+ *
+ * The seats differ, and that is the whole reason this module exists: the Session HEADER seat is
+ * session-scoped and is handed `sessionId`; the sidebar FOOTER seat — where this panel's own badge
+ * lives — is rendered `renderSlot('sidebar.footer.action', { wide })` and is handed nothing else. So
+ * the header publishes what it is showing, the footer reads it, and the store is the third fallback
+ * (`current` on the shells that have it). Every reader here is total: an unknown shape answers
+ * "nothing known" rather than throwing, and no field that is absent is taken for a value.
+ *
+ * @module dsh-diff-approval/client/session-seat
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+/**
+ * Publish the session the header entry is showing. Call it from an EFFECT, never during render.
+ *
+ * Writing this during the header's render was the cross-talk's other half: the value a render read
+ * depended on whether another component had already rendered, so two mounts could disagree about which
+ * session was showing — and, in concurrent rendering, a discarded render could publish a session that
+ * was never committed. From an effect the value only ever describes a committed render.
+ * @param id - the id, or `undefined` when the shell named none.
+ */
+export declare function publishSessionId(id: SessionId | undefined): void;
+/** The session the header entry last showed, or `undefined` when it never named one. */
+export declare function publishedSessionId(): SessionId | undefined;
+/**
+ * The published session as a React value: the root-scoped mounts (the sidebar footer's badge) have no
+ * session prop, so this is how they follow the one the Session header is showing.
+ *
+ * It subscribes rather than reading the module global at render time, because the write now happens in
+ * an effect: a reader that only read the global would keep whatever the value was on its first render
+ * and never notice the reader switching sessions.
+ * @returns the session the header entry is showing, or `undefined`.
+ */
+export declare function usePublishedSessionId(): SessionId | undefined;
+/**
+ * The selected session a shell's session-list state names, by every field the shells have used.
+ * @param state - the store state handed to the selector.
+ * @returns the id, or `undefined` when this shape names none.
+ */
+export declare function selectedSessionOf(state: unknown): SessionId | undefined;
+/**
+ * Whether one session row is BLANK — a freshly created session with nothing in it yet, which has
+ * nothing to review and leaves this plugin's entry inert exactly like no session at all.
+ *
+ * `byId[id].blank` is the row's own flag and has kept its name across the shells; a store that
+ * carries `blank` on the STATE (with the id beside it) is read too. An absent flag is not blank: a
+ * shape this plugin does not recognise must not disable the panel.
+ *
+ * @param state - the store state handed to the selector.
+ * @param id - the session the answer is about; `undefined` answers false.
+ * @returns true only when the shell says that session is blank.
+ */
+export declare function sessionIsBlank(state: unknown, id: SessionId | undefined): boolean;
+/**
+ * Whether a seat has NO reviewable session: it cannot name one at all, or the shell says the one it names
+ * is blank (a brand-new session with nothing said in it yet).
+ *
+ * The two halves are ONE question and must be asked of the SAME id — the id the seat would read its view
+ * for. Splitting them is what this helper exists to stop: a seat that drew its view for the published
+ * session while testing `sessionIsBlank` against a different (absent) id stayed enabled on a blank session
+ * and drew the previous session's list — from another workspace as readily as from its own, because nothing
+ * in this client compares workspaces.
+ *
+ * @param state - the session-list state handed to the selector.
+ * @param id - the session this seat would read its view for.
+ * @returns true when there is nothing to review.
+ */
+export declare function unreviewableSession(state: unknown, id: SessionId | undefined): boolean;
+/**
+ * The session the PAGE is showing, resolved the way a whole-page reader has to resolve it: the
+ * session-list store's own selection first, else what the Session header entry published.
+ *
+ * `readSessionsSelection` is supplied by the plugin body (it owns the `sessions` service), and may
+ * return `undefined` for a shell whose state names none — 0.1.7's store carries no selected session and
+ * hands the id to its own session-scoped seats instead, which is why the published id is read here too
+ * (`publishSessionId` runs from the header entry's effect). This is a plain read for non-React code: the
+ * component that publishes it reads the SUBSCRIBED value ({@link usePublishedSessionId}).
+ *
+ * It is deliberately NOT every session anyone has read: the page-wide readers here (the reference remap,
+ * which rewrites the visible composer's draft) mean the session the reader is looking at, and taking the
+ * newest session some other mount polled would address a composer that is not on screen.
+ *
+ * @param readSessionsSelection - the store's own selected session, when its shape names one.
+ * @returns the id, or `undefined` when nothing on this page names a session.
+ */
+export declare function shownSessionId(readSessionsSelection: () => SessionId | undefined): SessionId | undefined;

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

@@ -204,32 +204,58 @@ export declare function setSplitMode(value: boolean): void;
 export declare function mdPreviewEnabled(): boolean;
 /** Persist the Markdown-preview default preference. */
 export declare function setMdPreviewEnabled(value: boolean): void;
+/**
+ * Whether this plugin MOUNTS its own file menu at all — the press bridge that takes over a file press in
+ * the shell's lists, a file link in a message, and a relative link in the Markdown preview.
+ *
+ * Default ON, and the default is the interesting half: only an explicit `'0'` turns it off, so a reader who
+ * never touches the setting keeps the menu they have always had (and a storage that cannot be read — a
+ * privacy mode, a cleared profile — leaves the plugin working rather than silently disabled).
+ *
+ * Off means the bridge does not take the press over AT ALL: no menu, and the shell's own behaviour runs
+ * exactly as if this plugin were not installed. That includes this plugin's own preview, where a relative
+ * link therefore goes back to the browser's own navigation — which is the honest consequence of asking this
+ * plugin to keep its hands off, not a bug to special-case.
+ *
+ * @returns whether the file menu is enabled.
+ */
+export declare function chipMenuEnabled(): boolean;
+/** Persist the file-menu preference (see {@link chipMenuEnabled}). */
+export declare function setChipMenuEnabled(value: boolean): void;
 /**
  * Whether commenting on a diff range is offered: the selection frame's comment button,
- * and the chord that stands for it. Defaults to off while the mode is a preview (see
- * {@link COMMENT_MODE_PREVIEW_KEY}); only an explicit `'1'` enables it. This gates
- * STARTING a thread, not the threads themselves — one already written keeps rendering,
- * so turning the mode off never hides work or interrupts an answer on its way back.
+ * and the chord that stands for it. **Defaults to ON** — comment mode is the mode now,
+ * not a preview — so only an explicit `'0'` turns it off (the `chipMenuEnabled` idiom a
+ * few lines up), and an absent field means on for every profile that predates the flip.
+ * This gates STARTING a thread, not the threads themselves — one already written keeps
+ * rendering, so turning the mode off never hides work or interrupts an answer on its way
+ * back.
  * @returns whether comment mode is on.
  */
 export declare function commentModeEnabled(): boolean;
-/** Window event: comment mode was toggled (see {@link setCommentModeEnabled}). */
-export declare const COMMENT_MODE_CHANGED_EVENT = "diff-approval:comment-mode";
-/** Persist the comment-mode preference. */
+/** Window event: comment mode was toggled (see {@link setCommentModeEnabled}). A DIFFERENT string from
+ *  {@link COMMENT_MODE_KEY} on purpose: a key literal and an event literal that read the same make every
+ *  grep a guess (the hazard this file already names for the file-menu key at the top). */
+export declare const COMMENT_MODE_CHANGED_EVENT = "diff-approval:comment-mode-changed";
+/** Persist the comment-mode preference (`'1'` on, `'0'` off — see {@link commentModeEnabled}). */
 export declare function setCommentModeEnabled(value: boolean): void;
 /**
  * Whether the diff's code uses the font this plugin bundles.
  *
- * Defaults to **off**: the bundled face is JetBrains Maple Mono subset and
- * sliced into 138 woff2 files, and a page pulls the slices its characters land
- * in — tens of kilobytes for a comment, up to ~120 KB for a rare character. That
- * is real traffic, so it is the reader's decision, not a default they discover.
- * Only an explicit `'1'` enables it.
+ * **Defaults to ON**, like comment mode: absent means on, and only an explicit `'0'` turns
+ * it off. The old field's answer is deliberately NOT carried over (see the constant): a
+ * reader who had turned the bundled face off before this change comes back with it on, which
+ * is the one behaviour the reader asked for. The cost is real and worth naming where the
+ * switch is: the face is a JetBrains Maple Mono subset sliced into 138 woff2 files, and a
+ * page pulls only the slices its characters land in — tens of kilobytes for a comment, up to
+ * ~120 KB for a rare character — downloaded on demand rather than shipped.
  * @returns whether the bundled code font is enabled.
  */
 export declare function codeFontEnabled(): boolean;
-/** Window event: the bundled code font was turned on or off (see {@link setCodeFontEnabled}). */
-export declare const CODE_FONT_CHANGED_EVENT = "diff-approval:code-font";
+/** Window event: the bundled code font was turned on or off (see {@link setCodeFontEnabled}). A DIFFERENT
+ *  string from {@link CODE_FONT_KEY} on purpose — they used to be the same literal, which made a grep for
+ *  either one a guess (the hazard this file names for the file-menu key at the top). */
+export declare const CODE_FONT_CHANGED_EVENT = "diff-approval:code-font-changed";
 /** Persist the bundled-code-font preference. */
 export declare function setCodeFontEnabled(value: boolean): void;
 /**