@plannotator/ui 0.30.0 → 0.32.0

package/theme.css

@@ -627,6 +627,14 @@
    * the surface/sidebar-aware components expect. Themes that pin explicit
    * values (e.g. "simple") override these. */
   :root {
+    /* Mobile browser environment. Safe areas are CSS-owned because they are
+     * available before React mounts; the observed viewport values are written
+     * by useViewportEnvironment and fall back cleanly in the utilities below. */
+    --pn-safe-top: env(safe-area-inset-top, 0px);
+    --pn-safe-right: env(safe-area-inset-right, 0px);
+    --pn-safe-bottom: env(safe-area-inset-bottom, 0px);
+    --pn-safe-left: env(safe-area-inset-left, 0px);
+    --pn-touch-target: 2.75rem;
     --surface-0: color-mix(in oklch, var(--muted) 40%, var(--background));
     --surface-1: var(--muted);
     --surface-2: color-mix(in oklch, var(--muted) 70%, var(--foreground));
@@ -704,6 +712,227 @@ body {
   font-feature-settings: "ss01", "ss02", "cv01";
 }
 
+/* Safari extends the page canvas beneath its floating browser controls. The
+ * plan document is a card-colored nested scroller, so leaving the outer canvas
+ * on `--background` produces an opaque dark band around those controls. Match
+ * the browser canvas to the active surface while preserving the incumbent
+ * background for grid, HTML, Review, loading, and non-editor consumers. */
+html:has([data-pn-browser-canvas="card"]),
+body:has([data-pn-browser-canvas="card"]) {
+  background-color: var(--card);
+}
+
+html:has([data-pn-browser-canvas="background"]),
+body:has([data-pn-browser-canvas="background"]) {
+  background-color: var(--background);
+}
+
+/* Mobile Safari only collapses its browser controls for page scrolling; it
+ * deliberately leaves them expanded when a gesture scrolls a nested element.
+ * Plan opts compact coarse-pointer layouts into document scrolling while the
+ * fixed application-stage architecture remains unchanged everywhere else. */
+html:has([data-pn-document-scroll="true"]),
+body:has([data-pn-document-scroll="true"]) {
+  height: auto;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: auto;
+}
+
+body:has([data-pn-document-scroll="true"]) > #root {
+  height: auto;
+  overflow: visible;
+}
+
+.pn-app-viewport[data-pn-document-scroll="true"] {
+  height: auto;
+  min-height: 100vh;
+  min-height: 100dvh;
+}
+
+/* The application stage owns the top and lateral safe areas. Bottom-edge
+ * surfaces opt into `.pn-safe-bottom` themselves so the home-indicator inset
+ * is never counted twice. The ordered height declarations preserve desktop
+ * behavior and old-browser support before the observer publishes a value. */
+.pn-app-viewport {
+  box-sizing: border-box;
+  height: 100vh;
+  height: 100dvh;
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: var(--pn-safe-top);
+  padding-right: var(--pn-safe-right);
+  padding-left: var(--pn-safe-left);
+}
+
+.pn-safe-top {
+  padding-top: var(--pn-safe-top);
+}
+
+.pn-safe-inline {
+  padding-right: var(--pn-safe-right);
+  padding-left: var(--pn-safe-left);
+}
+
+.pn-safe-bottom {
+  padding-bottom: var(--pn-safe-bottom);
+}
+
+.pn-viewport-bounded {
+  max-height: calc(
+    var(--pn-viewport-height, 100vh) - var(--pn-safe-top) - var(--pn-safe-bottom)
+  );
+}
+
+/* Portaled overlays cannot inherit the application root's safe-area padding.
+ * This utility gives them the same observed visible stage without assuming
+ * that the software keyboard is a rectangular bottom inset. */
+.pn-visible-viewport-overlay {
+  position: fixed;
+  top: var(--pn-viewport-offset-top, 0px);
+  left: var(--pn-viewport-offset-left, 0px);
+  box-sizing: border-box;
+  width: var(--pn-viewport-width, 100vw);
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: max(1rem, var(--pn-safe-top));
+  padding-right: max(1rem, var(--pn-safe-right));
+  padding-bottom: max(1rem, var(--pn-safe-bottom));
+  padding-left: max(1rem, var(--pn-safe-left));
+}
+
+/* Full-stage compact surfaces (for example the Plan navigator) use the same
+ * observed visual viewport as portaled dialogs without inheriting their 1rem
+ * ornamental margin. The stage owns its safe areas and contains scroll-chain
+ * gestures so the document beneath it does not move at a list boundary. */
+.pn-visible-viewport-stage {
+  position: fixed;
+  top: var(--pn-viewport-offset-top, 0px);
+  left: var(--pn-viewport-offset-left, 0px);
+  box-sizing: border-box;
+  width: var(--pn-viewport-width, 100vw);
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: var(--pn-safe-top);
+  padding-right: var(--pn-safe-right);
+  padding-bottom: var(--pn-safe-bottom);
+  padding-left: var(--pn-safe-left);
+  overscroll-behavior: contain;
+}
+
+/* The navigator reuses information-dense desktop browser content, but its
+ * interactive rows become physical controls on touch. Scope both the 44px
+ * target and the TOC's legible type lift to the compact stage only. */
+[data-pn-plan-navigator="true"] button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+[data-pn-plan-navigator="true"] nav button {
+  font-size: 0.8125rem;
+}
+
+[data-pn-plan-navigator="true"] .file-browser-filter-field {
+  height: var(--pn-touch-target);
+}
+
+[data-pn-plan-navigator="true"] .file-browser-filter-clear {
+  min-inline-size: var(--pn-touch-target);
+}
+
+/* Compact Plan auxiliary stages reuse dense desktop panel contents, but every
+ * nested action remains a physical touch control. This selector is stage-only,
+ * so the incumbent desktop panel geometry stays pixel-identical. */
+[data-pn-compact-plan-stage="true"] button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+/* Existing expanded composers keep their 85dvh desktop proportion. Compact
+ * and touch layouts use the full safe visible stage so the keyboard cannot
+ * strand the footer below an ornamental desktop margin. */
+.pn-responsive-composer-dialog {
+  width: 100%;
+  height: min(36rem, 85vh);
+  height: min(36rem, 85dvh);
+  max-width: 42rem;
+  max-height: 100%;
+}
+
+@media (pointer: coarse), (max-width: 639px), (max-height: 419px) {
+  .pn-responsive-composer-dialog {
+    height: 100%;
+  }
+
+  /* Code review often promotes a line selection straight into the expanded
+   * composer. Keep its idle surface proportional to the content instead of
+   * covering the whole phone; once the keyboard reduces the visible viewport,
+   * the same cap naturally yields to all available space. Plan's explicit
+   * expanded-composer treatment remains unchanged. */
+  .pn-responsive-composer-dialog.pn-review-composer-dialog {
+    height: min(28rem, 100%);
+  }
+}
+
+/* iOS zooms focused text controls below 16px. Scope the correction to
+ * user-authored primary inputs so labels, counters, and diff text stay at the
+ * established desktop scale. The mirror selector keeps skill-token glyphs
+ * metrically identical to the transparent textarea above it. */
+@media (pointer: coarse), (max-width: 639px) {
+  [data-pn-mobile-editable],
+  [data-pn-mobile-editable-mirror] {
+    font-size: 1rem !important;
+  }
+}
+
+/* Shared controls keep their incumbent visual density but gain a physical
+ * 44px target inside the canonical compact touch shell. The root marker comes
+ * from the same JS media query that owns scroll and shell composition, so a
+ * secondary touchscreen cannot reclassify a fine-primary-pointer desktop.
+ * Selecting from `html` also reaches portaled controls outside the app root. */
+html:has([data-pn-compact-touch-layout='true']) [data-pn-touch-target] {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-touch-target][data-pn-touch-target-icon] {
+  min-inline-size: var(--pn-touch-target);
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-compact-diff-options]
+  button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+/* The selection toolbar packs its controls at desktop density (2px gaps), so
+ * 44px targets alone would still leave adjacent destructive and comment
+ * actions a mis-tap apart. Space them only inside the compact scope. */
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-annotation-toolbar-row] {
+  gap: 0.5rem;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-touch-target]:not(:disabled):not([aria-disabled='true']):active {
+  filter: brightness(0.92);
+  transition: filter 100ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html:has([data-pn-compact-touch-layout='true'])
+    [data-pn-touch-target]:not(:disabled):not([aria-disabled='true']):active {
+    filter: brightness(0.9);
+    transition: none;
+  }
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .plan-look-choice-option[aria-pressed='false']:hover {
+    border-color: color-mix(in srgb, var(--muted-foreground) 40%, transparent);
+    background: color-mix(in srgb, var(--muted) 35%, transparent);
+  }
+}
+
 .math-inline {
   display: inline-flex;
   align-items: center;

package/types.ts

@@ -79,6 +79,8 @@ export interface Annotation {
     displayMode: boolean;
   }>; // math elements covered by a mixed text+formula selection
   prUrl?: string; // code-review PR mode: the PR this note belongs to, so it isn't shown/exported against another PR after an in-place switch
+  pageUrl?: string; // set only by live app annotate sessions: the page (pathname + search) the annotation was made on; restore filters to the current page and export groups by page
+  inReplyTo?: string; // id of the annotation this one replies to; a reply inherits its parent's anchor, renders indented under it in the panel, and exports grouped under it. Additive: annotations without it render and export exactly as before.
   htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections
@@ -155,6 +157,32 @@ export type CodeAnnotationType = 'comment' | 'suggestion' | 'concern';
 // must branch on scope, never read those sentinels as a real path or row.
 export type CodeAnnotationScope = 'line' | 'file' | 'general';
 
+/**
+ * One inferred step selected from the Call Flow analysis surface.
+ *
+ * Source location is optional because CallDiff can surface structural steps
+ * without a concrete line. `CodeAnnotation` uses an in-patch located target
+ * as its native inline anchor when one exists; otherwise the annotation is
+ * file- or review-scoped while this target remains its durable Call Flow
+ * anchor. Raw output selections use a one-based `rawLine` instead of a source
+ * location. This lets every rendered Call Flow row and raw line participate in
+ * feedback without pretending an out-of-hunk or diagnostic line can be posted
+ * as an inline source comment.
+ */
+interface CallFlowAnnotationTargetBase {
+  treePath: string;
+  entry: string;
+  label: string;
+  side: 'old' | 'new';
+}
+
+export type CallFlowAnnotationTarget = CallFlowAnnotationTargetBase & (
+  | { filePath: string; lineStart: number; lineEnd: number; rawLine?: undefined }
+  | { filePath: string; lineStart?: undefined; lineEnd?: undefined; rawLine?: undefined }
+  | { rawLine: number; filePath?: undefined; lineStart?: undefined; lineEnd?: undefined }
+  | { rawLine?: undefined; filePath?: undefined; lineStart?: undefined; lineEnd?: undefined }
+);
+
 /** Conventional Comments label — see https://conventionalcomments.org */
 export type ConventionalLabel =
   | 'praise'
@@ -214,6 +242,13 @@ export interface CodeAnnotation {
    *  line anchor maps to the pristine lines those edits replace, so it is
    *  approximate and the export labels it as such. */
   selectedTextFromEdits?: boolean;
+  /**
+   * Complete Call Flow selection for an annotation authored from that
+   * surface. When any target maps to the patch, one target also supplies this
+   * annotation's primary inline anchor; otherwise the annotation is file- or
+   * review-scoped. Target order always preserves the user's selection order.
+   */
+  callFlowTargets?: CallFlowAnnotationTarget[];
   createdAt: number;
   author?: string;
   source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API

package/utils/annotateAgentTerminal.ts

@@ -1,14 +1,45 @@
-import type { AgentTerminalAgent } from "@plannotator/core/agent-terminal";
-import { storage } from "./storage";
+import type {
+  AgentTerminalAgent,
+  AnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
+import { configStore } from "../config";
 
-const DEFAULT_AGENT_KEY = "plannotator-annotate-agent-terminal-default";
+// The side/placement vocabulary lives in @plannotator/core so the settings
+// registry can reach it without importing this module (which would close a
+// cycle through ConfigStore). Re-exported here because this is the seam the
+// editor package imports from.
+export {
+  ANNOTATE_AGENT_TERMINAL_SIDES,
+  isAnnotateAgentTerminalSide,
+  resolveAnnotateAgentTerminalPlacement,
+  resolveAnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
+export type {
+  AnnotateAgentTerminalPlacement,
+  AnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
 
+/**
+ * Both Agent TUI preferences resolve through ConfigStore (server config file >
+ * cookie > default) rather than reading cookies directly. Annotate sessions run
+ * on a fresh random port every time, so a cookie is scoped to a single session;
+ * the server round-trip through ~/.plannotator/config.json is what makes these
+ * choices durable. Same seam identity.ts uses for `displayName`.
+ */
 export function getSavedAnnotateAgentId(): string | null {
-  return storage.getItem(DEFAULT_AGENT_KEY);
+  return configStore.get("agentTerminalDefaultAgent") || null;
 }
 
 export function saveAnnotateAgentId(agentId: string): void {
-  storage.setItem(DEFAULT_AGENT_KEY, agentId);
+  configStore.set("agentTerminalDefaultAgent", agentId);
+}
+
+export function getSavedAnnotateAgentTerminalSide(): AnnotateAgentTerminalSide {
+  return configStore.get("agentTerminalSide");
+}
+
+export function saveAnnotateAgentTerminalSide(side: AnnotateAgentTerminalSide): void {
+  configStore.set("agentTerminalSide", side);
 }
 
 export function resolveAnnotateAgentId(

package/utils/blockTargeting.ts

@@ -1,11 +1,12 @@
+import { getScrollViewportRect } from '../hooks/useScrollViewport';
+import { createTextRange } from './domSelection';
+
 /**
  * Semantic document targeting shared by pointer Pinpoint and Vim navigation.
  *
  * The graph is rebuilt from the live rendered document whenever a consumer
  * needs it. Callers persist stable keys, never DOM nodes, across renders.
  */
-import { createTextRange } from './domSelection';
-
 /** Elements that never participate in document targeting. */
 const SKIP_SELECTORS = [
   '.annotation-toolbar',
@@ -362,7 +363,9 @@ export function findInitialSemanticTarget(
   graph: SemanticTargetGraph,
   scrollViewport?: HTMLElement | null,
 ): SemanticTarget | null {
-  const viewportRect = (scrollViewport ?? graph.container).getBoundingClientRect();
+  const viewportRect = scrollViewport
+    ? getScrollViewportRect(scrollViewport)
+    : graph.container.getBoundingClientRect();
   const centerY = viewportRect.top + viewportRect.height / 2;
   return graph.blockKeys
     .map((key) => resolveSemanticTarget(graph, key))

package/utils/composerYield.ts

@@ -0,0 +1,45 @@
+/**
+ * Composer-yield state machine for shift-click multi-select.
+ *
+ * While Shift is held during a multi-target draft, the comment composer gets
+ * out of the pointer's way: it fades as the pointer approaches and becomes
+ * click-through when the pointer is over it. Restoration uses hysteresis so
+ * the composer does not flicker at its boundary.
+ */
+
+export type ComposerYieldState = 'none' | 'near' | 'over';
+
+/** Distance (px from the composer rect) at which the composer starts fading. */
+export const COMPOSER_YIELD_NEAR_ENTER_PX = 80;
+/** Distance the pointer must exceed before a faded composer fully restores. */
+export const COMPOSER_YIELD_NEAR_EXIT_PX = 96;
+/** Distance the pointer must clear a click-through composer by to restore. */
+export const COMPOSER_YIELD_OVER_EXIT_PX = 48;
+
+/** Shortest distance from a point to a rect's edge; <= 0 means inside. */
+export function distanceToRect(
+  x: number,
+  y: number,
+  rect: { left: number; top: number; right: number; bottom: number },
+): number {
+  const dx = Math.max(rect.left - x, 0, x - rect.right);
+  const dy = Math.max(rect.top - y, 0, y - rect.bottom);
+  if (dx === 0 && dy === 0) return 0;
+  return Math.hypot(dx, dy);
+}
+
+/** Next yield state for a pointer at `distance` px from the composer rect. */
+export function computeComposerYield(
+  previous: ComposerYieldState,
+  distance: number,
+): ComposerYieldState {
+  if (distance <= 0) return 'over';
+  if (previous === 'over') {
+    if (distance <= COMPOSER_YIELD_OVER_EXIT_PX) return 'over';
+    return distance <= COMPOSER_YIELD_NEAR_EXIT_PX ? 'near' : 'none';
+  }
+  if (previous === 'near') {
+    return distance <= COMPOSER_YIELD_NEAR_EXIT_PX ? 'near' : 'none';
+  }
+  return distance <= COMPOSER_YIELD_NEAR_ENTER_PX ? 'near' : 'none';
+}

package/utils/generateIdentity.ts

@@ -1,12 +1,73 @@
 /**
- * Tater name generator — pure function, no storage dependencies.
+ * Tater name generator: pure function, no storage dependencies.
  *
  * Extracted to its own module to avoid circular imports:
  * settings.ts needs this for the default value, and identity.ts
  * needs configStore (which imports settings.ts).
+ *
+ * The full `unique-username-generator` dictionary is NOT imported here. It is
+ * registered into the slot below by `./identity-tater`, which every
+ * Plannotator entry imports eagerly, so Plannotator mints names from the
+ * full dictionary exactly as before. A host that provides its own
+ * `identityProvider` never calls the generator and, with the static import
+ * gone, no longer ships the word lists.
+ *
+ * The slot is SYNCHRONOUS on purpose: `configStore.ensureLoaded()` evaluates
+ * this default during the first settings read (a render-time read) and
+ * persists the result to the identity cookie at once, so a name that arrived
+ * later would be a visible identity change. The built-in fallback below keeps
+ * the same `{adjective}-{noun}-tater` shape from a small inline pool.
  */
 
-import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-generator';
+export type IdentityGenerator = () => string;
+
+const FALLBACK_ADJECTIVES = [
+  'swift', 'gentle', 'brave', 'calm', 'clever', 'bright', 'quiet', 'bold',
+  'eager', 'kind', 'lucky', 'merry', 'nimble', 'proud', 'sunny', 'witty',
+] as const;
+
+const FALLBACK_NOUNS = [
+  'falcon', 'crystal', 'river', 'meadow', 'harbor', 'comet', 'maple', 'otter',
+  'summit', 'lantern', 'willow', 'ember', 'pebble', 'breeze', 'orchid', 'canyon',
+] as const;
+
+/** Pool words: exported for tests only. */
+export const FALLBACK_IDENTITY_POOL: {
+  readonly adjectives: readonly string[];
+  readonly nouns: readonly string[];
+} = {
+  adjectives: FALLBACK_ADJECTIVES,
+  nouns: FALLBACK_NOUNS,
+};
+
+function pick<T>(list: readonly T[]): T {
+  return list[Math.floor(Math.random() * list.length)]!;
+}
+
+/** Built-in generator: same shape as the dictionary one, from a 16 x 16 pool. */
+export const fallbackIdentityGenerator: IdentityGenerator = () =>
+  `${pick(FALLBACK_ADJECTIVES)}-${pick(FALLBACK_NOUNS)}-tater`;
+
+let generator: IdentityGenerator = fallbackIdentityGenerator;
+
+/**
+ * Register the generator `generateIdentity()` delegates to. Must return a
+ * string synchronously. `./identity-tater` registers the full dictionary;
+ * a host may register its own via `configurePlannotatorUI({ identityGenerator })`.
+ */
+export function setIdentityGenerator(next: IdentityGenerator): void {
+  generator = next;
+}
+
+/** The active generator. Exported so a test can assert which one is registered. */
+export function getIdentityGenerator(): IdentityGenerator {
+  return generator;
+}
+
+/** Reset to the built-in fallback pool. Mainly for tests. */
+export function resetIdentityGenerator(): void {
+  generator = fallbackIdentityGenerator;
+}
 
 /**
  * Generate a new random tater identity.
@@ -14,16 +75,5 @@ import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-gene
  * Examples: "swift-falcon-tater", "gentle-crystal-tater"
  */
 export function generateIdentity(): string {
-  // Use a unique separator to split adjective from noun, avoiding issues
-  // with compound words that contain hyphens (e.g., "behind-the-scenes")
-  const generated = uniqueUsernameGenerator({
-    dictionaries: [adjectives, nouns],
-    separator: '|||',
-    style: 'lowerCase',
-    randomDigits: 0,
-    length: 50, // Prevent word truncation (default is too short)
-  });
-
-  const [adjective, noun] = generated.split('|||');
-  return `${adjective}-${noun}-tater`;
+  return generator();
 }

package/utils/htmlChrome.ts

@@ -2,37 +2,41 @@ import { storage } from './storage';
 import { isStalePreference } from './preferenceTtl';
 
 /**
- * Cross-session chrome visibility for raw-HTML annotate sessions.
+ * Cross-session sidebar/panel state for raw-HTML annotate sessions.
  *
- * A raw-HTML session should open as close to "just the page" as possible, so
- * the default is minimal paint: tools hidden, sidebar closed, annotations
- * drawer closed. An explicit change the user makes (showing tools, opening the
- * drawer) persists for later HTML sessions, but only while they keep using
- * HTML annotate: state not refreshed within the staleness TTL (explicit
- * changes or annotation activity re-stamp it) expires back to the minimal
+ * A raw-HTML session opens with both side surfaces closed so the page gets
+ * the viewport; an explicit change the user makes (opening the sidebar or the
+ * annotations drawer) persists for later HTML sessions, but only while they
+ * keep using HTML annotate: state not refreshed within the staleness TTL
+ * (explicit changes or annotation activity re-stamp it) expires back to the
  * defaults. Persisted as a cookie (like every other cross-session UI pref;
  * hook servers run on random ports, and cookies are scoped by domain, not
  * port). Markdown sessions are untouched. A legacy record without a timestamp
- * has an unknowable age and is treated as expired, which one-time resets
- * everyone to the minimal defaults.
+ * has an unknowable age and is treated as expired.
+ *
+ * `toolsHidden` is the header "Hide tools" toggle: while true, ALL floating
+ * chrome over the page (sidebar tongue tabs + the comment/attachments
+ * cluster) is removed from the DOM. Restoring it hidden can never strand a
+ * user: the header button that flips it back is part of the header, not the
+ * hidden chrome.
  */
 
 const STORAGE_KEY = 'plannotator-html-chrome';
 
 export interface HtmlChromeState {
-  /** The header "Hide tools" toggle — true hides all annotation chrome. */
-  toolsHidden: boolean;
   /** Whether the left sidebar was open when the user last left. */
   sidebarOpen: boolean;
   /** Whether the right annotations drawer was open when the user last left. */
   panelOpen: boolean;
+  /** Whether ALL floating tools over the page were hidden when the user left. */
+  toolsHidden: boolean;
 }
 
-/** Default: minimal paint — everything hidden, both side surfaces closed. */
+/** Default: both side surfaces closed — the page gets the viewport. */
 export const DEFAULT_HTML_CHROME_STATE: HtmlChromeState = {
-  toolsHidden: true,
   sidebarOpen: false,
   panelOpen: false,
+  toolsHidden: false,
 };
 
 /** Pure resolution logic (exported for tests): raw cookie value → state. */
@@ -49,15 +53,15 @@ export function resolveHtmlChromeState(
     const record = parsed as Record<string, unknown>;
     if (isStalePreference(record.savedAt, now)) return DEFAULT_HTML_CHROME_STATE;
     return {
-      toolsHidden: typeof record.toolsHidden === 'boolean'
-        ? record.toolsHidden
-        : DEFAULT_HTML_CHROME_STATE.toolsHidden,
       sidebarOpen: typeof record.sidebarOpen === 'boolean'
         ? record.sidebarOpen
         : DEFAULT_HTML_CHROME_STATE.sidebarOpen,
       panelOpen: typeof record.panelOpen === 'boolean'
         ? record.panelOpen
         : DEFAULT_HTML_CHROME_STATE.panelOpen,
+      toolsHidden: typeof record.toolsHidden === 'boolean'
+        ? record.toolsHidden
+        : DEFAULT_HTML_CHROME_STATE.toolsHidden,
     };
   } catch {
     return DEFAULT_HTML_CHROME_STATE;

package/utils/identity-tater.ts

@@ -0,0 +1,36 @@
+/**
+ * Eager identity registration: installs the full `unique-username-generator`
+ * dictionary into the generator slot in `./generateIdentity` at module
+ * evaluation, before any settings read can mint a name.
+ *
+ * Every Plannotator entry (`packages/editor/App.tsx`, `packages/review-editor/App.tsx`)
+ * imports this module for its side effect, which keeps Plannotator's tater
+ * names byte-identical to before: same library, same config, same call. A host
+ * that wants the full dictionary without its own identity provider imports it
+ * too:
+ *
+ *   import '@plannotator/ui/utils/identity-tater';
+ *
+ * A host that provides `identityProvider` never calls the generator and should
+ * NOT import this, so the word lists stay out of its bundle.
+ */
+import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-generator';
+import { setIdentityGenerator, type IdentityGenerator } from './generateIdentity';
+
+/** The dictionary generator Plannotator has always used. */
+export const generateTaterIdentity: IdentityGenerator = () => {
+  // Use a unique separator to split adjective from noun, avoiding issues
+  // with compound words that contain hyphens (e.g., "behind-the-scenes")
+  const generated = uniqueUsernameGenerator({
+    dictionaries: [adjectives, nouns],
+    separator: '|||',
+    style: 'lowerCase',
+    randomDigits: 0,
+    length: 50, // Prevent word truncation (default is too short)
+  });
+
+  const [adjective, noun] = generated.split('|||');
+  return `${adjective}-${noun}-tater`;
+};
+
+setIdentityGenerator(generateTaterIdentity);

package/utils/lookAndFeelAnnouncement.ts

@@ -1,18 +1,22 @@
 /**
- * Tracks whether the user has seen the UI 2.0 "look & feel" refresh announcement.
- * Uses cookies so the dismissal survives Plannotator's random localhost ports.
+ * Tracks whether the user has explicitly resolved the Grid/Clean plan choice.
+ * This is separate from `gridEnabled`: ConfigStore seeds that preference with
+ * its default on first access, which is not evidence that the user chose it.
  */
 
 import { storage } from './storage';
 
-const STORAGE_KEY = 'plannotator-look-feel-announcement-seen';
-// v2: grid is the default again; the dialog became a grid-vs-clean image chooser.
-const CURRENT_VERSION = '2';
+const CHOICE_RESOLVED_KEY = 'plannotator-plan-look-choice-resolved';
+const LEGACY_ANNOUNCEMENT_KEY = 'plannotator-look-feel-announcement-seen';
 
 export function needsLookAndFeelAnnouncement(): boolean {
-  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+  if (storage.getItem(CHOICE_RESOLVED_KEY) === 'true') return false;
+  // v2 was the old Grid/Clean chooser wrapped in the 0.20.0 announcement.
+  // A dismissal there resolved the same decision; migrate it without showing
+  // another dialog merely because the release framing was removed.
+  return storage.getItem(LEGACY_ANNOUNCEMENT_KEY) !== '2';
 }
 
-export function markLookAndFeelAnnouncementSeen(): void {
-  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+export function markLookAndFeelChoiceResolved(): void {
+  storage.setItem(CHOICE_RESOLVED_KEY, 'true');
 }