dsh-diff-approval 0.30.1 → 0.31.0

package/lib/types/client/panel-memory.d.ts

@@ -125,18 +125,36 @@ export declare function rememberPlacedThreads(sessionId: string | undefined, thr
  */
 export declare function forgetPlacedThreadsNotIn(sessionId: string | undefined, listed: readonly string[]): void;
 /**
- * Whether the reader asked not to be asked again about removing one file.
+ * Whether the reader asked not to be asked again about rows leaving THIS session's list.
  * @param sessionId - the session the panel is reviewing; nothing is quiet without one.
- * @param fileId - the pending entry the question was about.
  * @returns true when the action should run without the question.
  */
-export declare function removalAskQuiet(sessionId: string | undefined, fileId: string): boolean;
+export declare function removalAskQuiet(sessionId: string | undefined): boolean;
 /**
- * Stop asking whether one file should leave the list, for the rest of this page.
+ * Stop asking whether rows should leave the list, for the rest of this page: the whole session, every
+ * file in it.
  * @param sessionId - the session the panel is reviewing; nothing is recorded without one.
- * @param fileId - the pending entry the question was about.
  */
-export declare function quietenRemovalAsk(sessionId: string | undefined, fileId: string): void;
+export declare function quietenRemovalAsk(sessionId: string | undefined): void;
+/**
+ * Window event a dismissal dispatches, so every mounted seat hears it.
+ *
+ * The notice's chip lives in the open file's status bar, and the panel that draws it can be mounted more than
+ * once (the footer seat and the right sidebar's docked tab are separate mounts): the state above is the fact,
+ * and this event is how the OTHER mount learns about it NOW rather than at its next mount. One state, one
+ * event — so whichever seat is on screen cannot disagree about whether the reader has said "got it".
+ */
+export declare const UPDATE_DISMISSED_EVENT = "diff-approval:update-dismissed";
+/**
+ * The release whose notice the reader dismissed on this page.
+ * @returns the dismissed version, or `''` when none has been dismissed here.
+ */
+export declare function dismissedUpdateVersion(): string;
+/**
+ * Remember that the reader dismissed the notice for one version on this page, and tell the other mounts.
+ * @param version - the version that notice was about.
+ */
+export declare function dismissUpdate(version: string): void;
 /**
  * Remember that a session's panel was left showing one file, and where in it.
  * @param sessionId - the session the panel was reviewing; nothing is recorded

package/lib/types/client/path-match.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Path comparison for the review's own references: is the path a press named the same file as one the
+ * pending list holds?
+ *
+ * Its own module because three places ask it and they must not disagree — the panel's jump to a file, the
+ * plugin's produced-file press bridge, and the store's "does the page hold this path" reader — while the
+ * panel itself is a React component module that a data-layer reader should not have to import.
+ *
+ * @module dsh-diff-approval/client/path-match
+ */
+/** Normalize a path for comparison: forward slashes, no trailing slash. */
+export declare function normalizeDiffPath(p: string): string;
+/**
+ * The directory a file path lives in, as the path was spelled.
+ *
+ * @param p - the file's own path.
+ * @returns the directory, or undefined when the path names no directory (empty, or a bare file name).
+ */
+export declare function directoryOfPath(p: string | undefined): string | undefined;
+/**
+ * The absolute path a Markdown link names, resolved the way Markdown means it: against the directory of
+ * the file the preview is showing.
+ *
+ * A link in a document is relative to THAT DOCUMENT — `../src/foo.ts` in `docs/a.md` is `src/foo.ts` at the
+ * workspace root, not `../src/foo.ts` of the page's own URL — which is why the base is the previewed file's
+ * own directory and not the workspace root. The href is percent-decoded, its `#line`/`?query` suffix is
+ * dropped, `.`/`..` are resolved, and both separators are accepted. An href that is already absolute
+ * (drive letter or a leading slash) needs no base.
+ *
+ * Exported so the panel's preview click and its tests share one implementation and cannot disagree about
+ * what a link points at.
+ *
+ * @param baseDirectory - the directory of the file being previewed, or the workspace root when that file's
+ *   own path is unknown.
+ * @param href - the anchor's href, as written in the Markdown.
+ * @returns the absolute path, or undefined when it cannot be named (an empty href, or a relative href with
+ *   no base to resolve against).
+ */
+export declare function resolveMarkdownHref(baseDirectory: string | undefined, href: string): string | undefined;
+/**
+ * Whether a produced-file chip path and a pending file path refer to the same file, tolerant of separator
+ * style (\\ vs /) and of a workspace-relative vs absolute form. `chipPath` is typically the harness's
+ * workspace-relative forward-slash path; `filePath` is the host's absolute native-separator path. Matching
+ * is case-insensitive so a Windows drive/segment case difference does not miss the file the user clicked.
+ * @param chipPath - the path a press (or a reference) named.
+ * @param filePath - the path the pending list holds.
+ * @param workspacePath - the session's workspace root, when it is known.
+ * @returns whether the two name one file.
+ */
+export declare function diffPathsMatch(chipPath: string, filePath: string, workspacePath: string | undefined): boolean;

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

@@ -5,7 +5,7 @@
  * @module dsh-diff-approval/client/port
  */
 import type { ClientConnectionRpc, SessionId } from '@deepseek-ai/dsh-client-connection/client';
-import type { CommentAnchor, CommentQuoteLine, DiffApprovalActionValue, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalBulkValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, 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";
 /**
@@ -33,6 +33,18 @@ export interface CommentDraft {
 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. */
@@ -56,6 +68,8 @@ 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). */
@@ -90,8 +104,21 @@ export interface DiffApprovalPort {
      * 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>;
-    /** Ask one stored comment as its own turn of the session. */
+    /** 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/produced-diff.d.ts

@@ -13,35 +13,89 @@
  *   `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 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
+ * 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.
+ * 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.
  */
+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, and where the press was (the menu hangs under it). */
+/** 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 panel holds this file right now. Called synchronously on every press, because
-     * the decision it answers is whether the press is prevented — there is no second chance at it.
+     * 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
@@ -55,6 +109,29 @@ export interface ProducedChipBridge {
  * @returns whether an element naming it was found to press.
  */
 export declare function replayFilePress(path: string): boolean;
+/**
+ * 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.
  *

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

@@ -18,12 +18,27 @@
  */
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 /**
- * Publish the session the header entry is showing.
+ * 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.
@@ -44,10 +59,35 @@ export declare function selectedSessionOf(state: unknown): SessionId | undefined
  */
 export declare function sessionIsBlank(state: unknown, id: SessionId | undefined): boolean;
 /**
- * The session this mount is about: the slot prop the shell composed, else the store's own selected
- * session, else what the header entry published (see the module doc).
- * @param propSessionId - `sessionId` from the composed slot props, when the shell sends one.
- * @param storeSelected - the store's selected session, when its shape names one.
- * @returns the id, or `undefined` when nothing here knows one.
+ * 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 sessionIdFor(propSessionId: SessionId | undefined, storeSelected: SessionId | undefined): SessionId | undefined;
+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;
 /**