@plannotator/ui 0.45.1 → 0.46.1

package/HANDOFF.md

@@ -1032,7 +1032,8 @@ the people and what a mention means.
 
 ### Threading points
 
-- `AnnotationToolbar` (`selectionActions`, `selectionActionsIcon`, `quickLabels`) — the props live here. `selectionActionsIcon?: React.ReactNode` (0.43.1) is the glyph on the wand button, forwarded by `Viewer` (both toolbars) and `HtmlViewer`; absent → the package's own wand, which 0.43.1 also simplified to one thick diagonal with a single star (the six-spark glyph read as noise at 16px). Name, `data-selection-actions`, size and behavior of the button are untouched either way.
+- `AnnotationToolbar` (`selectionActions`, `selectionActionsIcon`, `quickLabels`) — the props live here.
+- **ui 0.45.2 (registry default):** `SETTINGS.reviewPanelView.defaultValue` is now `'tree'` (was `'sections'`). `configStore.ensureLoaded` seeds registry defaults into the host's `storageBackend`, so a host that never persisted a panel view now seeds `tree`; a persisted value still wins. No API change. Plannotator removed its first-run review setup dialog in the same change (#1587). `selectionActionsIcon?: React.ReactNode` (0.43.1) is the glyph on the wand button, forwarded by `Viewer` (both toolbars) and `HtmlViewer`; absent → the package's own wand, which 0.43.1 also simplified to one thick diagonal with a single star (the six-spark glyph read as noise at 16px). Name, `data-selection-actions`, size and behavior of the button are untouched either way.
 - `Viewer` forwards both to BOTH of its toolbars (the text-selection toolbar
   and the code-block hover toolbar).
 - `HtmlViewer` forwards `selectionActions` to its selection toolbar. It does
@@ -1494,8 +1495,39 @@ Tests (both DOM-gated, both added to the workflow's DOM_TESTS step):
 `components/AnnotationPanel.cardHeader.test.tsx` (6) and
 `components/AnnotationPanel.editMentions.test.tsx` (10).
 
+## Discovered model catalogs (0.46.0, core 0.25.6) — BREAKING for hosts
+
+Claude and Codex model lists are no longer hand-maintained in `@plannotator/ui`. They come from the installed CLIs through the Ask AI provider (`/api/ai/capabilities?activate=<id>`), in the shared `CatalogModel` shape from the new `@plannotator/core/model-catalog` subpath, with one small static fallback per provider (`CLAUDE_FALLBACK_MODELS`, `CODEX_FALLBACK_MODELS`). A host that imported any of the following must switch:
+
+| Removed | Use instead |
+| --- | --- |
+| `@plannotator/ui/utils/codexModels` (the whole module: `CODEX_MODELS`, `CODEX_EFFORT_LABELS`, `codexReasoningOptions`, `clampCodexReasoning`) | `useModelCatalogs(capabilities)` for the live list, `effortSelectOptions` / `resolveEffortChoice` / `EFFORT_LABELS` from `@plannotator/core/model-catalog` |
+| `CLAUDE_MODELS`, `CLAUDE_EFFORT`, `TOUR_CLAUDE_MODELS`, `CODEX_MODELS`, `codexReasoningOptions` exports of `components/AgentsTab` | the same catalog helpers (`modelSelectOptions`, `effortSelectOptions`) |
+| `sanitizeCodexPerModel`, `migrateCodexSection` from `hooks/useAgentSettings` | nothing: saved picks now resolve at read time with `resolveModelChoice` |
+
+Behaviour changes a host may notice:
+
+- `DEFAULT_CODEX_MODEL` (and the tour/guide Codex defaults) are now `''`, meaning "the model the Codex list marks default"; `DEFAULT_CLAUDE_MODEL` is `'opus'` (was `'claude-opus-5'`).
+- `useAgentSettings(catalogs?)` takes the catalogs and returns EFFECTIVE (resolved) model/effort values; called without catalogs it returns the saved values unchanged, as before.
+- `AIProviderModel` is now an alias of `CatalogModel` (adds optional `resolvedId`, `fastMode`); `resolveAIModelForProvider` uses the shared resolver, so a stale pinned id keeps its model family instead of snapping to the provider default.
+
+## Forge-aware `#123` / `@user` links (unreleased, additive; #1596)
+
+Bare `#123` and `@user` in a document used to link to github.com whenever `githubRepo` held a slash, so GitLab and GitHub Enterprise repos got links to the wrong forge. `InlineMarkdown` (and every block component that forwards `githubRepo`: `BlockRenderer`, `RenderedMarkdown`, `TableBlock`, `TablePopout`, `AlertBlock`, `Callout`, `proseBody`) gains an optional `repoHost?: string` beside it; `Viewer` passes `repoInfo.host`. The rule is the new `@plannotator/core/forge-refs` subpath (`forgeRefLinks`, `classifyForgeHost`, `normalizeForgeHost`). The host is normalized first: lowercased, port dropped, `www.github.com` / `ssh.github.com` / SSH aliases starting `github.com-` folded to `github.com` and `altssh.gitlab.com` to `gitlab.com`; a host that is not a plausible DNS name (no dot, brackets, `@`, a dotless SSH alias) counts as absent. Then a github host (`github.com`, `github.*`) links to `https://<host>/<path>/issues/N`, a gitlab host (`gitlab.com`, `gitlab.*`, `*.gitlab.*`) to `https://<host>/<path>/-/issues/N`, users to `https://<host>/<user>`, and any other host renders the ref as an unlinked span. **A host that passes no `repoHost` (or an implausible one) keeps the old github.com links**, so nothing changes until it opts in. Because ui imports a new core subpath and `@plannotator/ui` pins `@plannotator/core` EXACTLY (currently `"0.25.6"`), the core version bump and ui's pin must move together in the same release: bump core, set ui's `@plannotator/core` dependency to that same version, `bun install`, then publish `core` first and `ui` second. A ui built against this code on the old core pin would import a `forge-refs` subpath the pinned core does not ship.
+
+## Guided Review generation in core (core 0.25.6, unreleased, additive)
+
+Core-only; `@plannotator/ui` imports none of it, so ui's exact `0.25.6` pin is unchanged. The pure half of Guided Review generation moved verbatim from the private `@plannotator/server` (`packages/server/guide/guide-review.ts`, which re-exports every name) so a host such as Workspaces generates guides with Plannotator's exact prompt and holds the output to the same coverage rule. All three subpaths are browser-safe and zero-dependency:
+
+- `@plannotator/core/guide-prompt`: `GUIDE_REVIEW_PROMPT` (the organizer methodology), `GUIDE_SCHEMA_JSON` (the output JSON schema, as a string), `buildGuideUserMessage(patch, diffType, options?, prMetadata?, changedFiles?)`, `validateGuideOutput(raw, changedFiles)`, `GUIDE_NO_SECTIONS_ERROR`, the sanitizers `sanitizeGuideSection` / `sanitizeGuideSections` / `sanitizeUnplacedFiles`, and the types `GuideChangedFile` and `GuidePromptPRMetadata` (`{ url, baseBranch }`, structural, so a full GitHub/GitLab `PRMetadata` is accepted).
+- `@plannotator/core/review-prompt` (what `buildGuideUserMessage` frames a local diff with): `getLocalDiffInstruction`, `buildWorkspacePromptContextLines`, and the types `LocalDiffInstruction`, `WorkspaceReviewPromptContext`, `WorkspacePromptRepoContext`, `WorkspaceChildVcsType`.
+- `@plannotator/core/diff-type`: the `DiffType` union (including jj's `jj-commit:<id>`) plus `parseCommitDiffType`, `parseJjCommitDiffType`, `jjCommitRevset`, `commitFamilyId`, `parseWorktreeDiffType`, `JJ_TRUNK_REVSET`, `jjLineBaseRevset`, `jjCompareTargetRevset`, `parseRemoteBookmark`, `BARE_HEX_SHA_RE` (moved from `packages/shared/review-core.ts`, which re-exports them).
+
+The guide chain's engine plumbing (Claude/Codex/marker commands, output parsing, `composeGuideMethodology`, sessions) stays in the server. It ships in core 0.25.6 alongside what that unpublished version already carries; ui needs no change for it.
+
 ## Publishing & versioning
 
+- **ui 0.46.1 (fix, ui only, core pin unchanged at `0.25.6`):** `useVimSelection` (mounted by every `Viewer`) now only clears a page selection whose anchor or focus lies inside the viewer's own container; with vim off it used to clear the WHOLE page's selection on every mount and `contentVersion` change, so a selection in another host panel vanished whenever the document behind it loaded or changed.
 - **ui 0.45.0 (annotation card header slot + mentions on the card's edit box): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.44.0, both props on `AnnotationPanel`: `renderCardHeader` (the header-row twin of `renderCardFooter`, wrapper `[data-annotation-card-header]`, renders under `readOnly`, open-document cards only in the All-files view) and `mentionSource` (the 0.43.0 type, applied to the card's EDIT box, saving `onEdit(id, { text, mentions })` only when a source was supplied and a pick survived). Nothing is removed, no new supported imports (`components/MentionAutocomplete` is internal glue), no export-, share- or archive-visible change, and Plannotator passes neither — `packages/editor` and `packages/review-editor` have zero source diff, and the panel is byte-identical to 0.44.0. Known difference from `CommentPopover`: no chips in the card's edit box (follow-up named in the section). See "Annotation card header slot and mentions on the edit box (0.45.0)".
 - **ui 0.44.0 (mention token chips in the composer): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.43.2: the `@Label` tokens a `mentionSource` composer inserted render as chips in the composer's existing highlight overlay, `MentionSource.tokenClassName?` lets a host restyle them (under the metric rule), `useMentionAutocomplete` also returns the surviving `mentions`, and `utils/composerTokens` joins the supported-import list. Nothing is removed, no export-, share- or archive-visible change, and Plannotator passes none of it — with neither `mentionSource` nor `skillReferences` the composer is byte-identical to 0.43.2. See "Mention token chips in the composer (0.44.0)".
 - **ui 0.43.1 (`mentionSource` on the viewers): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.43.0: `mentionSource` on `Viewer` and `HtmlViewer` (forwarded to every comment composer each mounts) and the optional `Annotation.mentions` field the picked ids land on, set only when a source was supplied and a token survived. Nothing is removed, no new modules, no export-, share- or archive-visible change, and Plannotator passes none of it. See "`mentionSource` on the viewers (0.43.1)".
@@ -1517,6 +1549,25 @@ Tests (both DOM-gated, both added to the workflow's DOM_TESTS step):
 
 ---
 
+## `Settings` `annotateParity` (shipped in 0.46.0)
+
+`<Settings mode="annotate">` takes a new optional `annotateParity?: boolean`,
+default `false`. **A host that omits it sees exactly the annotate Settings it
+had**: General, Theme, Vim, Shortcuts, Files, plus the OpenCode agent-switch
+row when `origin="opencode"`. Plannotator's own annotate app passes `true`,
+which adds the plan-review document tabs (Display, Saving, Labels, Obsidian,
+Bear, Octarine) and hides the agent-switch row, which only ever applied to
+plan approval.
+
+Within those tabs the plan-decision rows stay plan-only: Save Plans and the
+three "Auto-save on Plan Arrival" switches. The Obsidian / Bear / Octarine
+enable switches are the SAME cookies plan review reads on approve, so turning
+one on from annotate also makes plan review save every approved plan there;
+the annotate description says so. `mode="plan"` and `mode="review"` are
+unaffected by the prop. Purely additive: no export, share or archive change.
+
+---
+
 ## The law (guardrails for anyone editing `@plannotator/ui`)
 
 These are enforced socially and, where possible, by CI. They exist because a prior from-scratch reimplementation of this UI broke the app and was reverted.

package/README.md

@@ -367,7 +367,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Currently `@plannotator/ui` 0.43.0 depends exactly on `@plannotator/core` 0.25.5. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
+- Currently `@plannotator/ui` 0.46.1 depends exactly on `@plannotator/core` 0.25.6. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 

package/components/AgentsTab.tsx

@@ -23,51 +23,27 @@ import { useAgentSettings } from '../hooks/useAgentSettings';
 import type { AgentEngine, AgentMode, ReviewEngine } from '../hooks/useAgentSettings';
 import type { AgentLaunchParams } from '../hooks/useAgentJobs';
 import { ConfigRow, SegmentedPicker, Toggle, SelectMenu } from './AgentControls';
-import { CODEX_MODELS, CODEX_EFFORT_LABELS, codexReasoningOptions } from '../utils/codexModels';
+import {
+  CLAUDE_FALLBACK_MODELS,
+  CODEX_FALLBACK_MODELS,
+  EFFORT_LABELS,
+  effortSelectOptions,
+  modelLabel,
+  modelSelectOptions,
+  type CatalogModel,
+} from '@plannotator/core/model-catalog';
+import { useModelCatalogs, type ModelCatalogs } from '../hooks/useModelCatalogs';
 
 export type { AgentLaunchParams } from '../hooks/useAgentJobs';
 
-// --- Agent option catalogs (shared across review + tour engine dropdowns) ---
-
-export const CLAUDE_MODELS: Array<{ value: string; label: string }> = [
-  { value: 'claude-fable-5', label: 'Fable 5' },
-  { value: 'claude-opus-5', label: 'Opus 5' },
-  { value: 'claude-opus-4-8', label: 'Opus 4.8' },
-  { value: 'claude-opus-4-8[1m]', label: 'Opus 4.8 (1M)' },
-  { value: 'claude-sonnet-5', label: 'Sonnet 5' },
-  { value: 'claude-sonnet-4-6', label: 'Sonnet 4.6' },
-  { value: 'claude-sonnet-4-6[1m]', label: 'Sonnet 4.6 (1M)' },
-  { value: 'claude-opus-4-7', label: 'Opus 4.7' },
-  { value: 'claude-opus-4-7[1m]', label: 'Opus 4.7 (1M)' },
-  { value: 'claude-opus-4-6', label: 'Opus 4.6' },
-  { value: 'claude-opus-4-6[1m]', label: 'Opus 4.6 (1M)' },
-  { value: 'claude-haiku-4-5', label: 'Haiku 4.5' },
-];
+// --- Agent option catalogs ---
+// Claude and Codex models come from the installed CLIs (useModelCatalogs —
+// the same lists Ask AI shows); only the marker-engine fallbacks live here.
 
-export const CLAUDE_EFFORT: Array<{ value: string; label: string }> = [
-  { value: 'low', label: 'Low' },
-  { value: 'medium', label: 'Medium' },
-  { value: 'high', label: 'High' },
-  { value: 'xhigh', label: 'XHigh' },
-  { value: 'max', label: 'Max' },
-];
-
-// Codex model catalog + per-model reasoning efforts live in
-// utils/codexModels (useAgentSettings needs them too, for effort clamping);
-// re-exported here so both launch surfaces keep one import site.
-export { CODEX_MODELS, codexReasoningOptions } from '../utils/codexModels';
-
-// Tour/guide Claude catalog: the CLI's latest-resolving aliases on top
-// (verified against `claude --help`: "Provide an alias for the latest model
-// (e.g. 'fable', 'opus', or 'sonnet') or a model's full name"), then every
-// pinned version from the review catalog.
-// Also reused by GuideEmptyState (packages/review-editor).
-export const TOUR_CLAUDE_MODELS: Array<{ value: string; label: string }> = [
-  { value: 'sonnet', label: 'Sonnet (latest)' },
-  { value: 'opus', label: 'Opus (latest)' },
-  { value: 'fable', label: 'Fable (latest)' },
-  ...CLAUDE_MODELS,
-];
+/** Whether a model offers a fast tier (Codex's fast mode toggle). */
+export function modelSupportsFast(models: readonly CatalogModel[], modelId: string): boolean {
+  return models.find((m) => m.id === modelId)?.fastMode === true;
+}
 
 // Fallback Cursor model catalog (just `auto`). The real, account-specific list
 // is discovered server-side via `agent models` and delivered on the cursor
@@ -227,18 +203,24 @@ function catalogLabel(list: Array<{ value: string; label: string }>, value: stri
   return list.find((o) => o.value === value)?.label ?? value;
 }
 
-function formatModel(provider: string, engine: string | undefined, model: string): string {
+type ModelLabelCatalogs = Pick<ModelCatalogs, 'claude' | 'codex'>;
+
+function formatModel(provider: string, engine: string | undefined, model: string, catalogs: ModelLabelCatalogs): string {
+  // Claude/Codex: the discovered catalog's label (fallback list, then alias
+  // naming, then the raw id for anything neither knows).
+  const claudeLabel = () => modelLabel([...catalogs.claude.models, ...CLAUDE_FALLBACK_MODELS], model);
+  const codexLabel = () => modelLabel([...catalogs.codex.models, ...CODEX_FALLBACK_MODELS], model);
   if (provider === 'cursor') return catalogLabel(CURSOR_MODELS, model);
   if (provider === 'opencode') return model ? model : 'Default';
   if (provider === 'pi') return model || 'Default';
   if (provider === 'copilot') return model || 'Default';
-  if (provider === 'codex' || engine === 'codex') return catalogLabel(CODEX_MODELS, model);
-  if ((provider === 'tour' || provider === 'guide') && engine === 'claude') return catalogLabel(TOUR_CLAUDE_MODELS, model);
+  if (provider === 'codex' || engine === 'codex') return codexLabel();
+  if ((provider === 'tour' || provider === 'guide') && engine === 'claude') return claudeLabel();
   if (provider === 'tour' || provider === 'guide') {
     if (engine === 'cursor') return catalogLabel(CURSOR_MODELS, model);
     if (engine === 'opencode' || engine === 'pi' || engine === 'copilot') return model || 'Default';
   }
-  return catalogLabel(CLAUDE_MODELS, model);
+  return claudeLabel();
 }
 
 function formatThinking(value: string): string {
@@ -247,11 +229,7 @@ function formatThinking(value: string): string {
 
 
 function formatEffort(value: string): string {
-  return catalogLabel(CLAUDE_EFFORT, value);
-}
-
-function formatReasoning(value: string): string {
-  return CODEX_EFFORT_LABELS[value] ?? value;
+  return EFFORT_LABELS[value] ?? value;
 }
 
 // --- Add-a-review dialog: a type-ahead picker over every discovered skill ---
@@ -383,8 +361,10 @@ function JobCard({
   onToggle,
   onViewDetails,
   onOpenGuide,
+  catalogs,
 }: {
   job: AgentJobInfo;
+  catalogs: ModelLabelCatalogs;
   annotationCount: number;
   onKill: () => void;
   expanded: boolean;
@@ -412,10 +392,10 @@ function JobCard({
           <div className="mt-0.5 flex flex-wrap items-center gap-1 text-[9px] text-muted-foreground/50">
             <span className="rounded bg-surface-1 px-1 py-px">{job.provider}</span>
             {job.model && (
-              <span className="rounded bg-surface-1 px-1 py-px font-mono">{formatModel(job.provider, job.engine, job.model)}</span>
+              <span className="rounded bg-surface-1 px-1 py-px font-mono">{formatModel(job.provider, job.engine, job.model, catalogs)}</span>
             )}
             {job.effort && <span className="rounded bg-surface-1 px-1 py-px">{formatEffort(job.effort)}</span>}
-            {job.reasoningEffort && <span className="rounded bg-surface-1 px-1 py-px">{formatReasoning(job.reasoningEffort)}</span>}
+            {job.reasoningEffort && <span className="rounded bg-surface-1 px-1 py-px">{formatEffort(job.reasoningEffort)}</span>}
             {job.thinking && <span className="rounded bg-surface-1 px-1 py-px">{formatThinking(job.thinking)}</span>}
             {job.fastMode && (
               <span className="rounded bg-amber-500/10 px-1 py-px text-amber-600 dark:text-amber-400">
@@ -521,7 +501,11 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
   const [pendingLaunch, setPendingLaunch] = useState<{ label: string; provider?: string; startedAt: number } | null>(null);
   const [launchError, setLaunchError] = useState<string | null>(null);
   const launchingRef = useRef(false);
-  const settings = useAgentSettings();
+  // Claude/Codex catalogs are shared with Ask AI; only the engine this panel
+  // is set to is fetched (never on page load), and saved picks resolve
+  // against it.
+  const catalogs = useModelCatalogs(capabilities);
+  const settings = useAgentSettings(catalogs);
   const {
     selectedMode,
     reviewEngine,
@@ -582,6 +566,9 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
     setGuidePiThinking,
     setGuideCopilotModel,
   } = settings;
+  const activeEngine = selectedMode === 'review' ? reviewEngine : selectedMode === 'tour' ? tourEngine : guideEngine;
+  const loadCatalog = catalogs.load;
+  useEffect(() => loadCatalog(activeEngine), [loadCatalog, activeEngine]);
 
   // Review profiles (built-in default plus the user's enabled skills). Loaded
   // from the discovery endpoint and refreshed after a skill is added.
@@ -923,12 +910,16 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
   // the saved id can't be found yet and the launch would quietly run Default. A
   // Default pick has nothing to resolve, so it never waits.
   const reviewReady = profilesLoaded || reviewProfileId === 'builtin:default';
+  // Claude/Codex launches wait for the model catalog to settle (it always
+  // does — the fallback on failure), so a launch never uses an unresolved pick.
+  const modelsReady = (engine: ReviewEngine) =>
+    engine === 'claude' || engine === 'codex' ? catalogs[engine].settled : true;
   const canLaunch = selectedMode === 'review'
-    ? reviewEngineAvailable(reviewEngine) && reviewReady
+    ? reviewEngineAvailable(reviewEngine) && reviewReady && modelsReady(reviewEngine)
     : selectedMode === 'tour'
-      ? tourAvailable && engineAvailable(tourEngine)
+      ? tourAvailable && engineAvailable(tourEngine) && modelsReady(tourEngine)
       : selectedMode === 'guide'
-        ? guideAvailable && reviewEngineAvailable(guideEngine) && guideLaunchable
+        ? guideAvailable && reviewEngineAvailable(guideEngine) && guideLaunchable && modelsReady(guideEngine)
         : false;
 
   const handleLaunch = async () => {
@@ -1015,6 +1006,40 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
     );
   }
 
+  // Model picker for Claude and Codex, or a quiet loading row while that
+  // engine's catalog is still settling (launch is held until it does).
+  const renderCatalogModelPicker = (
+    engine: 'claude' | 'codex',
+    value: string,
+    onChange: (value: string) => void,
+  ) => (
+    <ConfigRow label="Model" stacked>
+      {catalogs[engine].settled ? (
+        <SelectMenu value={value} options={modelSelectOptions(catalogs[engine].models, value)} onChange={onChange} />
+      ) : (
+        renderStaticChoice('Loading models…', <Loader2 className="animate-spin text-muted-foreground" size={11} />)
+      )}
+    </ConfigRow>
+  );
+
+  // Effort / reasoning picker for Claude and Codex: only the levels the
+  // selected model accepts, and no picker at all for a model that takes none.
+  const renderEffortPicker = (
+    label: string,
+    models: readonly CatalogModel[],
+    model: string,
+    value: string,
+    onChange: (value: string) => void,
+  ) => {
+    const options = effortSelectOptions(models, model);
+    if (options.length === 0) return null;
+    return (
+      <ConfigRow label={label} stacked>
+        <SegmentedPicker options={options} value={value} onChange={onChange} />
+      </ConfigRow>
+    );
+  };
+
   // Cursor and OpenCode share the same review config: an "experimental" note and
   // a single model picker driven by their live (or fallback) catalog.
   const renderMarkerEngineConfig = (
@@ -1084,25 +1109,19 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
                 </ConfigRow>
                 {reviewEngine === 'claude' && (
                   <>
-                    <ConfigRow label="Model" stacked>
-                      <SelectMenu value={claudeModel} options={CLAUDE_MODELS} onChange={setClaudeModel} />
-                    </ConfigRow>
-                    <ConfigRow label="Effort" stacked>
-                      <SegmentedPicker options={CLAUDE_EFFORT} value={claudeEffort} onChange={setClaudeEffort} />
-                    </ConfigRow>
+                    {renderCatalogModelPicker('claude', claudeModel, setClaudeModel)}
+                    {renderEffortPicker('Effort', catalogs.claude.models, claudeModel, claudeEffort, setClaudeEffort)}
                   </>
                 )}
                 {reviewEngine === 'codex' && (
                   <>
-                    <ConfigRow label="Model" stacked>
-                      <SelectMenu value={codexModel} options={CODEX_MODELS} onChange={setCodexModel} />
-                    </ConfigRow>
-                    <ConfigRow label="Reasoning" stacked>
-                      <SegmentedPicker options={codexReasoningOptions(codexModel)} value={codexReasoning} onChange={setCodexReasoning} />
-                    </ConfigRow>
-                    <ConfigRow label="Fast mode">
-                      <Toggle checked={codexFast} onChange={setCodexFast} />
-                    </ConfigRow>
+                    {renderCatalogModelPicker('codex', codexModel, setCodexModel)}
+                    {renderEffortPicker('Reasoning', catalogs.codex.models, codexModel, codexReasoning, setCodexReasoning)}
+                    {modelSupportsFast(catalogs.codex.models, codexModel) && (
+                      <ConfigRow label="Fast mode">
+                        <Toggle checked={codexFast} onChange={setCodexFast} />
+                      </ConfigRow>
+                    )}
                   </>
                 )}
                 {reviewEngine === 'cursor' && renderMarkerEngineConfig(cursorModel, cursorModels, setCursorModel)}
@@ -1122,30 +1141,23 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
             {selectedMode === 'tour' && (
               <>
                 {renderEngineSelect(tourEngine, setTourEngine, availableEngines, ENGINE_ICON, ENGINE_LABEL)}
-                <ConfigRow label="Model" stacked>
-                  <SelectMenu
-                    value={tourEngine === 'claude' ? tourClaudeModel : tourCodexModel}
-                    options={tourEngine === 'claude' ? TOUR_CLAUDE_MODELS : CODEX_MODELS}
-                    onChange={tourEngine === 'claude' ? setTourClaudeModel : setTourCodexModel}
-                  />
-                </ConfigRow>
+                {tourEngine === 'claude'
+                  ? renderCatalogModelPicker('claude', tourClaudeModel, setTourClaudeModel)
+                  : renderCatalogModelPicker('codex', tourCodexModel, setTourCodexModel)}
 
                 {/* Claude-only: effort level */}
-                {tourEngine === 'claude' && (
-                  <ConfigRow label="Effort" stacked>
-                    <SegmentedPicker options={CLAUDE_EFFORT} value={tourClaudeEffort} onChange={setTourClaudeEffort} />
-                  </ConfigRow>
-                )}
+                {tourEngine === 'claude' &&
+                  renderEffortPicker('Effort', catalogs.claude.models, tourClaudeModel, tourClaudeEffort, setTourClaudeEffort)}
 
                 {/* Codex-only: reasoning effort + fast mode */}
                 {tourEngine === 'codex' && (
                   <>
-                    <ConfigRow label="Reasoning" stacked>
-                      <SegmentedPicker options={codexReasoningOptions(tourCodexModel)} value={tourCodexReasoning} onChange={setTourCodexReasoning} />
-                    </ConfigRow>
-                    <ConfigRow label="Fast mode">
-                      <Toggle checked={tourCodexFast} onChange={setTourCodexFast} />
-                    </ConfigRow>
+                    {renderEffortPicker('Reasoning', catalogs.codex.models, tourCodexModel, tourCodexReasoning, setTourCodexReasoning)}
+                    {modelSupportsFast(catalogs.codex.models, tourCodexModel) && (
+                      <ConfigRow label="Fast mode">
+                        <Toggle checked={tourCodexFast} onChange={setTourCodexFast} />
+                      </ConfigRow>
+                    )}
                   </>
                 )}
               </>
@@ -1154,31 +1166,18 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
             {selectedMode === 'guide' && (
               <>
                 {renderEngineSelect(guideEngine, setGuideEngine, availableReviewEngines, REVIEW_ENGINE_ICON, REVIEW_ENGINE_LABEL)}
-                {(guideEngine === 'claude' || guideEngine === 'codex') && (
-                  <ConfigRow label="Model" stacked>
-                    <SelectMenu
-                      value={guideEngine === 'claude' ? guideClaudeModel : guideCodexModel}
-                      options={guideEngine === 'claude' ? TOUR_CLAUDE_MODELS : CODEX_MODELS}
-                      onChange={guideEngine === 'claude' ? setGuideClaudeModel : setGuideCodexModel}
-                    />
-                  </ConfigRow>
-                )}
+                {guideEngine === 'claude' && renderCatalogModelPicker('claude', guideClaudeModel, setGuideClaudeModel)}
+                {guideEngine === 'codex' && renderCatalogModelPicker('codex', guideCodexModel, setGuideCodexModel)}
 
                 {/* Claude-only: effort level */}
-                {guideEngine === 'claude' && (
-                  <ConfigRow label="Effort" stacked>
-                    <SegmentedPicker options={CLAUDE_EFFORT} value={guideClaudeEffort} onChange={setGuideClaudeEffort} />
-                  </ConfigRow>
-                )}
+                {guideEngine === 'claude' &&
+                  renderEffortPicker('Effort', catalogs.claude.models, guideClaudeModel, guideClaudeEffort, setGuideClaudeEffort)}
 
                 {/* Codex-only: reasoning effort. No "Fast mode" toggle here
                     (unlike review/tour's codex blocks above) — fast mode is
                     deliberately not offered for guide. */}
-                {guideEngine === 'codex' && (
-                  <ConfigRow label="Reasoning" stacked>
-                    <SegmentedPicker options={codexReasoningOptions(guideCodexModel)} value={guideCodexReasoning} onChange={setGuideCodexReasoning} />
-                  </ConfigRow>
-                )}
+                {guideEngine === 'codex' &&
+                  renderEffortPicker('Reasoning', catalogs.codex.models, guideCodexModel, guideCodexReasoning, setGuideCodexReasoning)}
 
                 {/* Marker engines: same live-catalog model picker as review mode,
                     but bound to the guide-scoped settings (see useAgentSettings) so
@@ -1237,6 +1236,7 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
             <JobCard
               key={job.id}
               job={job}
+              catalogs={catalogs}
               annotationCount={annotationCounts.get(job.source) ?? 0}
               onKill={() => onKillJob(job.id)}
               expanded={expandedJobId === job.id}

package/components/BlockRenderer.tsx

@@ -19,9 +19,10 @@ export const BlockRenderer: React.FC<{
   checkboxOverrides?: Map<string, boolean>;
   orderedIndex?: number | null;
   githubRepo?: string;
+  repoHost?: string;
   headingAnchorId?: string;
   onNavigateAnchor?: (hash: string) => void;
-}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, headingAnchorId, onNavigateAnchor }) => {
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor }) => {
   switch (block.type) {
     case 'heading': {
       const Tag = `h${block.level || 1}` as React.ElementType;
@@ -37,7 +38,7 @@ export const BlockRenderer: React.FC<{
           data-block-id={block.id}
           data-block-type="heading"
         >
-          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} repoHost={repoHost} onNavigateAnchor={onNavigateAnchor} />
         </Tag>
       );
     }
@@ -54,6 +55,7 @@ export const BlockRenderer: React.FC<{
             imageBaseDir={imageBaseDir}
             onImageClick={onImageClick}
             githubRepo={githubRepo}
+            repoHost={repoHost}
             onNavigateAnchor={onNavigateAnchor}
           />
         );
@@ -68,7 +70,7 @@ export const BlockRenderer: React.FC<{
         >
           {paragraphs.map((para, i) => (
             <p key={i} className={i > 0 ? 'mt-2' : ''}>
-              <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={para} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+              <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={para} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} repoHost={repoHost} onNavigateAnchor={onNavigateAnchor} />
             </p>
           ))}
         </blockquote>
@@ -83,7 +85,7 @@ export const BlockRenderer: React.FC<{
         : block.checked;
       const isInteractive = isCheckbox && !!onToggleCheckbox;
       const textClass = `text-sm leading-relaxed ${isCheckbox && isChecked ? 'text-muted-foreground line-through' : 'text-foreground/90'}`;
-      const inlineProps = { imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, githubRepo, onNavigateAnchor };
+      const inlineProps = { imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, githubRepo, repoHost, onNavigateAnchor };
       return (
         <div
           className="flex items-start gap-3 my-1.5"
@@ -117,6 +119,7 @@ export const BlockRenderer: React.FC<{
           onOpenLinkedDoc={onOpenLinkedDoc}
           onOpenCodeFile={onOpenCodeFile}
           githubRepo={githubRepo}
+          repoHost={repoHost}
           onNavigateAnchor={onNavigateAnchor}
         />
       );
@@ -145,6 +148,7 @@ export const BlockRenderer: React.FC<{
           imageBaseDir={imageBaseDir}
           onImageClick={onImageClick}
           githubRepo={githubRepo}
+          repoHost={repoHost}
           onNavigateAnchor={onNavigateAnchor}
         />
       );
@@ -156,7 +160,7 @@ export const BlockRenderer: React.FC<{
           className="mb-4 leading-relaxed text-foreground/90 text-[15px]"
           data-block-id={block.id}
         >
-          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} repoHost={repoHost} onNavigateAnchor={onNavigateAnchor} />
         </p>
       );
   }

package/components/ExportModal.tsx

@@ -136,7 +136,7 @@ export const ExportModal: React.FC<ExportModalProps> = ({
     await handleCopy(wrapCopiedAnnotations(annotationsOutput), 'annotations');
   };
 
-  // Whether the hash URL is large enough to warrant a short URL option
+  // Warn when the hash URL may be too long for messaging apps
   const urlIsLarge = shareUrl.length > 2048;
   // Hash-based sharing unavailable (e.g. HTML render mode) — show only short link
   const hashUnavailable = !shareUrl && !!onGenerateShortUrl;
@@ -327,9 +327,13 @@ export const ExportModal: React.FC<ExportModalProps> = ({
                   </svg>
                   Generating short link...
                 </div>
-              ) : (urlIsLarge || hashUnavailable) && onGenerateShortUrl ? (
-                <div className="p-3 bg-amber-500/10 border border-amber-500/20 rounded-lg">
-                  {!hashUnavailable && (
+              ) : onGenerateShortUrl ? (
+                <div className={`p-3 rounded-lg border ${
+                  urlIsLarge
+                    ? 'bg-amber-500/10 border-amber-500/20'
+                    : 'bg-muted/50 border-border'
+                }`}>
+                  {urlIsLarge && (
                     <p className="text-xs text-amber-600 dark:text-amber-400 mb-2">
                       This URL may be too long for some messaging apps.
                     </p>

package/components/ImageAnnotator/Toolbar.tsx

@@ -104,7 +104,15 @@ export const Toolbar: React.FC<ToolbarProps> = ({
   const canIncrease = currentSizeIndex < STROKE_SIZES.length - 1;
 
   return (
-    <div className="flex items-center gap-2 px-3 py-2 bg-popover border border-border rounded-lg shadow-xl">
+    <div
+      data-pn-image-annotator-toolbar
+      className="flex w-fit max-w-full items-center gap-2 px-3 py-2 bg-popover border border-border rounded-lg shadow-xl"
+    >
+      <div
+        data-pn-image-toolbar-scroll
+        className="min-w-0 flex-1 overflow-x-auto overscroll-x-contain"
+      >
+        <div className="flex w-max items-center gap-2">
       {/* Tools */}
       <div className="flex items-center gap-1">
         {TOOLS.map(({ id, icon: Icon, label }) => (
@@ -228,15 +236,17 @@ export const Toolbar: React.FC<ToolbarProps> = ({
       >
         <ClearIcon />
       </button>
+        </div>
+      </div>
 
-      <div className="w-px h-5 bg-border" />
+      <div className="w-px h-5 shrink-0 bg-border" />
 
       {/* Save */}
       <button
         type="button"
         onClick={onSave}
         title="Save (Esc)"
-        className="p-1.5 rounded transition-colors bg-success text-success-foreground hover:opacity-90"
+        className="shrink-0 p-1.5 rounded transition-colors bg-success text-success-foreground hover:opacity-90"
       >
         <CheckIcon />
       </button>

package/components/ImageAnnotator/index.tsx

@@ -185,12 +185,16 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
 
   return (
     <div
-      className="fixed inset-0 z-[200] flex items-center justify-center bg-background/90 backdrop-blur-sm"
+      className="pn-visible-viewport-overlay z-[200] flex items-center justify-center bg-background/90 backdrop-blur-sm"
       data-popover-layer
       onClick={handleBackdropClick}
     >
       {/* Canvas with image and toolbar */}
-      <div className="relative flex flex-col items-center gap-3" onClick={(e) => e.stopPropagation()}>
+      <div
+        data-pn-image-annotator-stage
+        className="relative flex max-w-full flex-col items-center gap-3"
+        onClick={(e) => e.stopPropagation()}
+      >
         {/* Toolbar - above image */}
         <Toolbar
           tool={state.tool}