@plannotator/ui 0.53.1 → 0.55.0

package/config/settings.ts

@@ -13,8 +13,14 @@ import {
   isAnnotateAgentTerminalSide,
   type AnnotateAgentTerminalSide,
 } from '@plannotator/core/agent-terminal';
-import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
+import type { DiffLineBgIntensity, ReviewDefaults } from '@plannotator/core/config-types';
 import { isFaviconStyle, type FaviconStyle } from '@plannotator/core/favicon';
+import {
+  agentSwitchConfigValue,
+  isAgentSwitchName,
+  parseAgentSwitchConfig,
+  type AgentSwitchChoice,
+} from '@plannotator/core/agent-switch';
 import {
   DEFAULT_TOKEN_HOVER_DELAY_MS,
   isTokenHoverDelay,
@@ -23,7 +29,14 @@ import {
   type TokenHoverTrigger,
 } from '@plannotator/core/token-hover';
 import { DEFAULT_DIAGRAM_SHADOW, isDiagramShadow } from '../utils/diagramShadow';
+import {
+  DEFAULT_DOCUMENT_TEXT_SIZE,
+  isDocumentTextSize,
+  type DocumentTextSize,
+} from '../utils/documentTextSize';
+import { normalizeFontFamilyName } from '../utils/cssFontFamily';
 import { storage } from '../utils/storage';
+import { isLookChoiceResolved } from '../utils/lookAndFeelAnnouncement';
 import { generateIdentity } from '../utils/generateIdentity';
 import {
   getDefaultThemePair,
@@ -89,11 +102,45 @@ export function readThemePairCookies(keys?: ThemePairLegacyKeys): ThemePair | un
   return normalizeThemePair({ mode, light: light ?? seeded.light, dark: dark ?? seeded.dark }, seeded);
 }
 
+/** Pre-registry cookie keys of the agent switch, kept so an upgrade keeps the choice. */
+const AGENT_SWITCH_COOKIE = 'plannotator-agent-switch';
+const AGENT_SWITCH_CUSTOM_COOKIE = 'plannotator-agent-custom';
+
+function readAgentSwitchCookies(): AgentSwitchChoice | undefined {
+  const choice = parseAgentSwitchConfig(storage.getItem(AGENT_SWITCH_COOKIE));
+  if (!choice) return undefined;
+  const customName = storage.getItem(AGENT_SWITCH_CUSTOM_COOKIE);
+  return isAgentSwitchName(customName) ? { switchTo: choice.switchTo, customName } : choice;
+}
+
+function writeAgentSwitchCookies(choice: AgentSwitchChoice | null): void {
+  // null = never chosen: write nothing, so the surface default keeps applying.
+  if (!choice) return;
+  storage.setItem(AGENT_SWITCH_COOKIE, choice.switchTo);
+  if (choice.customName) storage.setItem(AGENT_SWITCH_CUSTOM_COOKIE, choice.customName);
+  // Custom with its name cleared: drop the old name, or the next read would
+  // pair it with "custom" and switch to that old agent again.
+  else if (choice.switchTo === 'custom') storage.removeItem(AGENT_SWITCH_CUSTOM_COOKIE);
+}
+
 const DIFF_LINE_BG_INTENSITY_VALUES = ['subtle', 'normal', 'strong'] as const;
 function isDiffLineBgIntensity(v: unknown): v is DiffLineBgIntensity {
   return typeof v === 'string' && (DIFF_LINE_BG_INTENSITY_VALUES as readonly string[]).includes(v);
 }
 
+function parseReviewDefaults(value: unknown): ReviewDefaults | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const defaults: ReviewDefaults = {};
+  for (const [providerId, providerValue] of Object.entries(value)) {
+    if (!providerId || !providerValue || typeof providerValue !== 'object' || Array.isArray(providerValue)) continue;
+    const defaultDiffType = (providerValue as Record<string, unknown>).defaultDiffType;
+    if (typeof defaultDiffType === 'string' && defaultDiffType) {
+      defaults[providerId] = { defaultDiffType };
+    }
+  }
+  return defaults;
+}
+
 export interface SettingDef<T> {
   defaultValue: T | (() => T);
   fromCookie: () => T | undefined;
@@ -160,10 +207,18 @@ export const SETTINGS = {
   },
 
   gridEnabled: {
-    // Default ON: plans open in the classic grid / floating-card look. The UI 2.0
-    // flat look is offered as an opt-in via the look-and-feel chooser dialog.
-    defaultValue: true as boolean,
+    // Default OFF: plans open in the Clean look (the document edge to edge).
+    // Grid (the classic floating card on grid paper) is a choice, made in the
+    // first-run chooser or in Settings.
+    defaultValue: false as boolean,
     fromCookie: () => {
+      // ConfigStore writes the default into this cookie on first load, so every
+      // browser that ran an older build stored 'true' (the old default) without
+      // anyone choosing it. The stored value counts only once the person has
+      // resolved the Grid/Clean choice under the Clean default (the v2 marker;
+      // a v1 marker with Grid stored is moved to Clean once, see
+      // utils/lookAndFeelAnnouncement); until then they get Clean.
+      if (!isLookChoiceResolved()) return undefined;
       const v = storage.getItem('plannotator-grid-enabled');
       return v === 'true' ? true : v === 'false' ? false : undefined;
     },
@@ -192,6 +247,54 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  /**
+   * The document's body text size in plan review and annotate, in px (#2066;
+   * see `utils/documentTextSize`). Default 15, today's size. Cookie-only, like
+   * the other display knobs; an unknown value reads as the default.
+   */
+  documentTextSize: {
+    defaultValue: DEFAULT_DOCUMENT_TEXT_SIZE as DocumentTextSize,
+    fromCookie: () => {
+      const raw = storage.getItem('plannotator-document-text-size');
+      if (raw === null || raw.trim() === '') return undefined;
+      const parsed = Number(raw);
+      return isDocumentTextSize(parsed) ? parsed : undefined;
+    },
+    toCookie: (value: DocumentTextSize) =>
+      storage.setItem('plannotator-document-text-size', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  /**
+   * The document's font in plan review and annotate (#1657; see
+   * `utils/documentFont`): a generic preset or an installed family name.
+   * Empty = the theme's font. Cookie-only, like Text size.
+   */
+  documentFontFamily: {
+    defaultValue: '' as string,
+    fromCookie: () =>
+      normalizeFontFamilyName(storage.getItem('plannotator-document-font-family') ?? '') || undefined,
+    toCookie: (value: string) => storage.setItem('plannotator-document-font-family', value),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  /**
+   * Enter saves a comment and Shift+Enter adds a new line (#1934). Default
+   * OFF: comments save with Cmd/Ctrl+Enter only, as they always have, and
+   * Cmd/Ctrl+Enter keeps saving with it on. Read by every comment composer
+   * through `isCommentSubmitKey` (`utils/commentSubmitKey`). Cookie-only.
+   */
+  enterSavesComment: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-enter-saves-comment');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-enter-saves-comment', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   vimModeEnabled: {
     // Vim bindings deliberately default OFF. Unmodified letter keys must remain
     // inert for existing users until they explicitly opt into modal document
@@ -360,6 +463,25 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  reviewDefaults: {
+    defaultValue: {} as ReviewDefaults,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-review-defaults');
+      if (!value) return undefined;
+      try {
+        return parseReviewDefaults(JSON.parse(value));
+      } catch {
+        return undefined;
+      }
+    },
+    toCookie: (value: ReviewDefaults) =>
+      storage.setItem('plannotator-review-defaults', JSON.stringify(value)),
+    serverKey: 'reviewDefaults',
+    fromServer: (serverConfig: Record<string, unknown>) =>
+      parseReviewDefaults(serverConfig.reviewDefaults),
+    toServer: (value: ReviewDefaults) => ({ reviewDefaults: value }),
+  },
+
   defaultDiffType: {
     defaultValue: 'since-base' as 'since-base' | 'local-vs-remote' | 'uncommitted' | 'unstaged' | 'staged' | 'merge-base' | 'all',
     fromCookie: () => {
@@ -655,6 +777,35 @@ export const SETTINGS = {
       }
     },
   },
+  /**
+   * OpenCode's agent switch after plan approval / review feedback (#1390).
+   * null = never chosen: each surface applies its own default (plan approval
+   * switches to "build", review feedback stays), see utils/agentSwitch.
+   *
+   * Server-synced to `agentSwitch` in ~/.plannotator/config.json because some
+   * webviews (Glimpse's WKWebView) keep no cookies between runs, and a lost
+   * choice silently hands the session to the build agent. The cookie keys
+   * are the pre-registry ones, so an upgrade keeps an existing choice.
+   */
+  agentSwitch: {
+    defaultValue: null as AgentSwitchChoice | null,
+    fromCookie: () => readAgentSwitchCookies(),
+    toCookie: (v: AgentSwitchChoice | null) => writeAgentSwitchCookies(v),
+    serverKey: 'agentSwitch',
+    fromServer: (sc: Record<string, unknown>) => {
+      const choice = parseAgentSwitchConfig(sc.agentSwitch);
+      // Custom with no name means no switch: never pair it with an old name.
+      if (!choice || choice.customName || choice.switchTo === 'custom') return choice;
+      // A plain choice keeps the name typed in the Custom field earlier, so
+      // picking Custom again shows it (the cookie is the only place it lives).
+      const customName = storage.getItem(AGENT_SWITCH_CUSTOM_COOKIE);
+      return isAgentSwitchName(customName) ? { ...choice, customName } : choice;
+    },
+    toServer: (v: AgentSwitchChoice | null) => {
+      const value = v ? agentSwitchConfigValue(v) : undefined;
+      return value === undefined ? {} : { agentSwitch: value };
+    },
+  },
   /**
    * Where the annotate-mode Agent TUI docks: 'left' (where it always docked),
    * 'right', or 'hidden' (no slot until the user opens it for the session).

package/configure.ts

@@ -18,6 +18,9 @@ import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
 import { setComponentTooltips } from './components/HostTitle';
+import { setRichCopyEnabled } from './utils/richCopyPolicy';
+import { setDigitHexIssueRefs } from './components/InlineMarkdown';
+import { setRefCardTransport, type RefCardTransport } from './utils/refCard';
 
 // One-stop type barrel: every seam contract a host implements is importable
 // from this module, next to configurePlannotatorUI itself.
@@ -44,6 +47,7 @@ export type {
   IdentityGenerator,
   AlertIconRenderer,
   FenceThemeResolver,
+  RefCardTransport,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -127,6 +131,27 @@ export interface PlannotatorUIConfig {
    * as before. The Plannotator Inbox passes true.
    */
   componentTooltips?: boolean;
+  /**
+   * Render a digit-only 6/8-digit `#123456` (word boundary, no leading zero)
+   * as an issue ref instead of a hex colour swatch, when a ref link can be
+   * built (a repo on a known forge). Default: false, swatches exactly as
+   * before. The Plannotator Inbox passes true (#1932).
+   */
+  digitHexIssueRefs?: boolean;
+  /**
+   * Make the selection toolbar's Copy button (Viewer and HtmlViewer) copy rich
+   * text: text/html plus text/plain in one clipboard write, and show Copy
+   * where `hideCopyButton` hid it (the Viewer on desktop). Default: false,
+   * Copy exactly as before. Plannotator's plan review, annotate, code review
+   * and Inbox pass true (#1972, `utils/richCopyPolicy`).
+   */
+  richCopy?: boolean;
+  /**
+   * Fetch an issue / PR / MR hover card's data (`components/RefHoverCard`).
+   * Default: none, so no card is drawn and nothing is requested. The
+   * Plannotator Inbox passes one over its `/api/inbox/ref` route.
+   */
+  refCardTransport?: RefCardTransport;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -152,6 +177,9 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.alertIconRenderer) setAlertIconRenderer(config.alertIconRenderer);
   if (config.fenceTheme) setFenceThemeResolver(config.fenceTheme);
   if (config.componentTooltips !== undefined) setComponentTooltips(config.componentTooltips);
+  if (config.digitHexIssueRefs !== undefined) setDigitHexIssueRefs(config.digitHexIssueRefs);
+  if (config.richCopy !== undefined) setRichCopyEnabled(config.richCopy);
+  if (config.refCardTransport) setRefCardTransport(config.refCardTransport);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/contents-rail.css

@@ -0,0 +1,337 @@
+/*
+ * @plannotator/ui/contents-rail.css: the document contents rail
+ * (components/MarkdownContentsRail.tsx). Its own stylesheet, NOT part of
+ * theme.css or styles.css: import it OUTSIDE any CSS cascade layer, after the
+ * host's base reset. A layered copy loses to a later unlayered reset (the
+ * marker's margin-inline-start: auto, the tick, title and label paddings and
+ * margins, the depth indents), and the ticks then sit over the prose.
+ *
+ * Moved from the Workspaces app's `ws-markdown-contents-*` rules (approved
+ * 2026-10-03). A stable marker dock sits in the document's existing right
+ * padding without participating in layout. The Contents surface opens to its
+ * LEFT and may overlay the document, never a docked comments column. Pointer
+ * events stay on the real navigation buttons; selection and scrolling remain
+ * untouched. Plain CSS, no Tailwind. Tokens are the host's (Workspaces defines
+ * them all); each has a fallback.
+ */
+@keyframes pn-contents-rail-enter {
+  from {
+    opacity: 0;
+  }
+}
+
+.pn-contents-rail {
+  --pn-contents-dock-width: 36px;
+  --pn-contents-panel-gap: 6px;
+  --pn-contents-panel-width: 256px;
+
+  position: fixed;
+  z-index: 20;
+  translate: 0 -50%;
+  width: calc(
+    var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + var(--pn-contents-panel-width)
+  );
+  pointer-events: none;
+  animation: pn-contents-rail-enter var(--motion-duration-fast, 120ms)
+    var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1)) both;
+}
+
+.pn-contents-rail-dock {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: var(--pn-contents-dock-width);
+  pointer-events: none;
+}
+
+/* The floating surface (Workspaces' `floating-surface`: popover fill, no drawn
+ * border, the edge is the hairline ring in the menu shadow). */
+.pn-contents-rail-surface {
+  position: absolute;
+  top: -40px;
+  bottom: -8px;
+  left: 0;
+  width: var(--pn-contents-panel-width);
+  border-radius: var(--geometry-floating-radius, 10px);
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: var(
+    --shadow-menu,
+    0 0 0 1px color-mix(in oklch, var(--foreground) 8%, transparent),
+    0 12px 32px -8px color-mix(in oklch, var(--foreground) 22%, transparent)
+  );
+  transform: translateX(4px) scale(0.98);
+  transform-origin: right center;
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* The section eyebrow (Workspaces' EYEBROW: 12 px, weight 500). */
+.pn-contents-rail-title {
+  position: absolute;
+  top: -32px;
+  left: 8px;
+  display: flex;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 28px;
+  align-items: center;
+  padding-inline: 4px;
+  color: var(--foreground);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 20px;
+  transform: translateX(4px);
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* A host's one control at the right of the open panel's title (panelAction). */
+.pn-contents-rail-action {
+  position: absolute;
+  z-index: 2;
+  top: -32px;
+  right: calc(var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + 8px);
+  display: flex;
+  height: 28px;
+  align-items: center;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transform: translateX(0) scale(1);
+  opacity: 1;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms);
+}
+
+.pn-contents-rail-list {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  /* The closed rail renders at most ten sampled document spans, so it never
+   * needs an internal scroll position. Shorter maps retain their natural
+   * height and stay centered by the rail's fixed midpoint anchor. */
+  max-height: 160px;
+  overflow-x: hidden;
+  overflow-y: hidden;
+  overscroll-behavior: contain;
+  scrollbar-width: none;
+  touch-action: none;
+  pointer-events: none;
+  transition: max-height var(--motion-duration-basic, 150ms) var(--ease-exit, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-list {
+  max-height: min(62vh, 560px);
+  overflow-y: auto;
+  transition-duration: var(--motion-duration-relaxed, 300ms);
+  transition-timing-function: var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+.pn-contents-rail-list::-webkit-scrollbar {
+  display: none;
+}
+
+.pn-contents-rail-marker {
+  --pn-contents-line-width: 26px;
+
+  position: relative;
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  height: 16px;
+  flex-direction: row-reverse;
+  align-items: center;
+  justify-content: flex-start;
+  overflow: hidden;
+  margin-inline-start: auto;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-marker {
+  width: 100%;
+  overflow: visible;
+}
+
+.pn-contents-rail-tick {
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  flex: none;
+  align-items: center;
+  justify-content: flex-start;
+  padding-inline-start: 4px;
+}
+
+.pn-contents-rail-line {
+  --marker-progress: 0;
+
+  display: block;
+  width: var(--pn-contents-line-width);
+  height: 2px;
+  transform: scaleX(calc(0.6154 + 0.3846 * var(--marker-progress)));
+  transform-origin: left center;
+  background: var(--muted-foreground);
+  opacity: 0.4;
+  pointer-events: none;
+  transition: none;
+}
+
+/* The frequently scanned closed map updates immediately. The local lens is
+ * motion reserved for the explicitly opened Contents state. */
+.pn-contents-rail[data-revealed] .pn-contents-rail-line {
+  transition:
+    transform var(--motion-duration-basic, 150ms)
+      linear(0, 0.398 10%, 0.682 20%, 0.843 30%, 0.925 40%, 0.972 50%, 1.004 60%, 1.008 70%, 1.003 80%, 1),
+    opacity var(--motion-duration-basic, 150ms) ease,
+    background-color var(--motion-duration-basic, 150ms) ease;
+}
+
+/* H1:H2 is 12px:10px with the shorter line inset 2px toward the document, at
+ * a deliberately longer scale, then the same step for H3 and H4. */
+.pn-contents-rail-marker[data-level="2"] {
+  --pn-contents-line-width: 22px;
+}
+
+.pn-contents-rail-marker[data-level="3"] {
+  --pn-contents-line-width: 18px;
+}
+
+.pn-contents-rail-marker[data-level="4"] {
+  --pn-contents-line-width: 14px;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-line {
+  background: var(--primary);
+  opacity: 0.68;
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-line {
+  --marker-progress: 1;
+  background: var(--foreground);
+  opacity: 1;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.7;
+  opacity: 0.78;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.4;
+  opacity: 0.58;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.2;
+  opacity: 0.46;
+}
+
+.pn-contents-rail-label {
+  display: block;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 16px;
+  min-width: 0;
+  flex: none;
+  overflow: hidden;
+  margin-inline-end: calc(var(--pn-contents-panel-gap) + 8px);
+  padding-inline: 4px;
+  border-radius: var(--geometry-structure-radius, 4px);
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: inherit;
+  font-weight: 400;
+  line-height: 16px;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  opacity: 0;
+  transform: translateX(-4px);
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    color var(--motion-duration-fast, 120ms) ease,
+    background-color var(--motion-duration-fast, 120ms) ease;
+}
+
+.pn-contents-rail-marker[data-depth="1"] .pn-contents-rail-label {
+  padding-inline-start: 16px;
+}
+
+.pn-contents-rail-marker[data-depth="2"] .pn-contents-rail-label {
+  padding-inline-start: 28px;
+}
+
+.pn-contents-rail-marker[data-depth="3"] .pn-contents-rail-label {
+  padding-inline-start: 40px;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-label {
+  opacity: 1;
+  transform: translateX(0);
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms), 0ms, 0ms;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-label {
+  color: var(--foreground);
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-label,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-label {
+  background: var(--surface-hover, color-mix(in oklch, var(--foreground) 6%, transparent));
+  color: var(--foreground);
+}
+
+.pn-contents-rail:focus-within .pn-contents-rail-surface,
+.pn-contents-rail:focus-within .pn-contents-rail-title,
+.pn-contents-rail:focus-within .pn-contents-rail-label,
+.pn-contents-rail:focus-within .pn-contents-rail-list {
+  transition-duration: 0ms;
+  transition-delay: 0ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pn-contents-rail {
+    animation: none;
+  }
+  .pn-contents-rail-line {
+    transition: none;
+  }
+  .pn-contents-rail-surface,
+  .pn-contents-rail-title,
+  .pn-contents-rail-label,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-title,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-label {
+    transform: none;
+    transition: opacity var(--motion-duration-fast, 120ms) ease;
+    transition-delay: 0ms;
+  }
+  .pn-contents-rail-list,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-list {
+    transition: none;
+  }
+}

package/hooks/pfm/useCodeFilePopout.ts

@@ -1,4 +1,4 @@
-import { useState, useCallback } from "react";
+import { useState, useCallback, useRef } from "react";
 import { parseCodePath } from "@plannotator/core/code-file";
 
 interface CodeFileState {
@@ -9,6 +9,7 @@ interface CodeFileState {
   requestedPath?: string;
   line?: number;
   lineEnd?: number;
+  revealKey?: number;
 }
 
 interface UseCodeFilePopoutOptions {
@@ -29,6 +30,8 @@ export interface UseCodeFilePopoutReturn {
     requestedPath?: string;
     line?: number;
     lineEnd?: number;
+    /** Changes on every open, so reopening the same file:line scrolls to it again. */
+    revealKey?: number;
   } | null;
 }
 
@@ -38,6 +41,7 @@ export function useCodeFilePopout(
   const { buildUrl } = options;
   const [state, setState] = useState<CodeFileState | null>(null);
   const [isLoading, setIsLoading] = useState(false);
+  const revealCount = useRef(0);
 
   const close = useCallback(() => {
     setState(null);
@@ -75,6 +79,7 @@ export function useCodeFilePopout(
           prerenderedHTML: data.prerenderedHTML,
           line: data.line ?? parsed.line,
           lineEnd: data.lineEnd ?? parsed.lineEnd,
+          revealKey: ++revealCount.current,
         });
         setIsLoading(false);
       } catch {
@@ -105,6 +110,7 @@ export function useCodeFilePopout(
           requestedPath: state.requestedPath,
           line: state.line,
           lineEnd: state.lineEnd,
+          revealKey: state.revealKey,
         }
       : null,
   };