Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

40.4 KB
Raw Blame
import { Button } from '@/components/ui/button';
import * as AlertDialog from '@radix-ui/react-alert-dialog';
import { Flame, Zap, Wrench, Flower, ChevronDown } from 'lucide-react';
import {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState,
} from 'react';
import { useTranslation } from 'react-i18next';

import type {
  ReleaseNoteItem,
  ReleaseNoteSection,
  ReleaseNoteTopic,
  ReleaseNotes,
} from '@/release-notes';
import type { UpdateNoticeMode } from '@/hooks/useUpdateNotice';
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu';
import { Spinner } from '@/components/ui/spinner';
import { cn } from '@/lib/utils';

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

interface UpdateNoticeDialogProps {
  open: boolean;
  mode: UpdateNoticeMode | null;
  /**
   * Auto mode: pre-loaded diff range, newest-first.
   * Manual mode: `[appVersionNotes]` — just the top block preloaded; the rest
   * is discovered via `allVersions` and hydrated lazily via `loadVersion`.
   */
  releaseNotes: ReleaseNotes[] | null;
  /**
   * Manual mode only: full history of versions on CDN (`≤ appVersion`),
   * newest-first. Each entry becomes a placeholder in the scroll body that
   * hydrates on view via `loadVersion`. Null in auto mode.
   */
  allVersions: string[] | null;
  /**
   * Fetch a single version's notes. Returns null on 404 / parse / network.
   * Backed by two-tier cache (main + renderer) — safe to call repeatedly.
   */
  loadVersion: (version: string) => Promise<ReleaseNotes | null>;
  onDismiss: () => void;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/** Format date: '2026-04-18' -> locale-specific long date. */
function formatDate(dateStr: string, locale: string): string {
  const [year, month, day] = dateStr.split('-').map(Number);
  const date = new Date(year, month - 1, day);
  return date.toLocaleDateString(locale, {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  });
}

/** Shared content column: one reading measure for every block in the dialog. */
const CONTENT_COLUMN = 'w-full max-w-[800px]';

// ---------------------------------------------------------------------------
// Sub-components
// ---------------------------------------------------------------------------

interface VersionBadgeProps {
  label: string;
  /** Renders a small chevron on the right and hover state — used by dropdown trigger. */
  clickable?: boolean;
  /** Leading flame glyph. Off for the header's version-jump chip, which is a count, not a version. */
  icon?: boolean;
}

function VersionBadge({ label, clickable = false, icon = true }: VersionBadgeProps) {
  return (
    <span
      className={cn(
        'inline-flex items-center gap-1.5 rounded-full px-3 py-1 whitespace-nowrap',
        'bg-[var(--chat-input-chip-bg)]',
        // Chip text must use the chip's own semantic color. The previous
        // `--settings-section-desc` resolves to a mid grey that lands at
        // 2.33:1 against the chip background in dark mode (fails WCAG AA);
        // `--chat-input-chip-text` is the sanctioned pairing (7.46:1 dark,
        // 12:1 light).
        'text-xs font-medium text-[var(--chat-input-chip-text)]',
        clickable && 'cursor-pointer hover:bg-[var(--cmd-palette-item-hover)] transition-colors',
      )}
    >
      {icon && <Flame className="h-[13px] w-[13px] shrink-0" />}
      {label}
      {clickable && <ChevronDown className="h-[13px] w-[13px] shrink-0 opacity-70" />}
    </span>
  );
}

const SECTION_ICONS = { zap: Zap, wrench: Wrench } as const;

function groupItemsByAuthor(
  items: ReleaseNoteItem[],
): Array<{ author: string; items: ReleaseNoteItem[] }> {
  const order: string[] = [];
  const buckets = new Map<string, ReleaseNoteItem[]>();
  for (const item of items) {
    if (!buckets.has(item.by)) {
      buckets.set(item.by, []);
      order.push(item.by);
    }
    buckets.get(item.by)!.push(item);
  }
  return order.map((author) => ({ author, items: buckets.get(author)! }));
}

/**
 * Legacy (author-grouped) body, rendered in the SAME single column as the v2
 * topic layout. Previously this was a two-column split (features | fixes),
 * which left half the dialog empty on bugfix-only releases and — more
 * importantly — made scrolling through history alternate between two very
 * different layouts, since only the newest release uses the topic format.
 *
 * Empty sections are dropped rather than rendered as a bare heading.
 */
function SectionList({ sections }: { sections: ReleaseNoteSection[] }) {
  const { t } = useTranslation();
  // Only the two canonical titles get translated. The legacy schema allows an
  // arbitrary section title, and headings are now per-section rather than
  // per-column, so mapping "anything that isn't Bug Fixes" to "New Features"
  // would mislabel unknown sections and print the same heading twice when a
  // payload carries several non-bugfix sections. Unknown titles pass through
  // verbatim.
  const labelFor = (title: string) => {
    if (title === 'Bug Fixes') {
      return { text: t('update.notice.bugFixes'), Icon: SECTION_ICONS.wrench };
    }
    if (title === 'New Features') {
      return { text: t('update.notice.newFeatures'), Icon: SECTION_ICONS.zap };
    }
    return { text: title, Icon: SECTION_ICONS.zap };
  };
  const filled = sections.filter((s) => s.items.length > 0);
  return (
    <>
      {filled.map((section, i) => {
        const { text, Icon } = labelFor(section.title);
        const groups = groupItemsByAuthor(section.items);
        return (
          <div key={`${i}-${section.title}`} className={cn(CONTENT_COLUMN, 'pt-4 pb-1')}>
            <div className="mb-2.5 flex items-center gap-1.5">
              <Icon className="h-3.5 w-3.5 shrink-0 text-[var(--cmd-palette-item-meta)]" />
              <span className="text-13 font-medium text-[var(--cmd-palette-item-meta)]">
                {text}
              </span>
            </div>
            <div className="flex flex-col gap-3.5">
              {groups.map((group) => (
                <AuthorGroup key={group.author} author={group.author} items={group.items} />
              ))}
            </div>
          </div>
        );
      })}
    </>
  );
}

function AuthorGroup({ author, items }: { author: string; items: ReleaseNoteItem[] }) {
  return (
    <div>
      <div
        className={cn(
          'mb-2 text-15 font-semibold leading-none tracking-tight',
          'text-[var(--msg-assistant-text)]',
        )}
      >
        {author}
      </div>
      <ul className="flex flex-col gap-1 list-none">
        {items.map((item) => (
          <li key={item.text} className="flex gap-2">
            <span className="shrink-0 text-sm leading-[1.5] text-[var(--settings-section-desc)]">
              &bull;
            </span>
            <span className="text-sm leading-[1.5] text-[var(--msg-assistant-text)]">
              {item.text}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}

/**
 * Per-version thanks line, closing out that version's block like film credits.
 *
 * It used to live in the dialog chrome, which meant the same list was rendered
 * twice at once (chrome + the version block's own subheader) and, at ~30
 * contributors, turned the top of the dialog into a two-line wall of names.
 * Anchoring it to the end of the version it belongs to removes the duplication
 * and makes the attribution unambiguous. Regular weight + secondary color keeps
 * it a closing note rather than a heading.
 */
function ThanksLine({ contributors }: { contributors: string[] }) {
  const { t } = useTranslation();
  if (contributors.length === 0) return null;
  return (
    <div
      className={cn(
        CONTENT_COLUMN,
        'mt-3 flex items-start gap-1.5 border-t border-[var(--cmd-palette-border)] pt-4',
        'text-12 leading-[1.7] select-text',
      )}
    >
      <Flower
        className="mt-[3px] h-3.5 w-3.5 shrink-0 text-[var(--status-bar-accent)]"
        strokeWidth={2.25}
      />
      <span className="shrink-0 text-[var(--cmd-palette-item-meta)]">
        {t('update.notice.thanksTo')}
      </span>
      <span className="min-w-0 break-words text-[var(--cmd-palette-item-meta)]">
        {contributors.join(' · ')}
      </span>
    </div>
  );
}

// ---------------------------------------------------------------------------
// Topic-format (v2) body: single centered column of theme blocks. Replaces
// the two-column author-grouped layout for payloads that carry `topics` —
// notably fixes the half-empty dialog on bugfix-only releases.
// ---------------------------------------------------------------------------

function TopicList({ intro, topics }: { intro?: string; topics: ReleaseNoteTopic[] }) {
  return (
    <>
      {intro && (
        <div
          className={cn(
            CONTENT_COLUMN,
            'pt-3 pb-1 text-sm leading-[1.7] break-words text-[var(--cmd-palette-item-meta)]',
          )}
        >
          {intro}
        </div>
      )}
      {topics.map((topic, i) => (
        <div key={`${i}-${topic.title}`} className={cn(CONTENT_COLUMN, 'py-3')}>
          {/* flex-wrap + min-w-0: long titles shrink/wrap and an overlong
              contributor list drops to its own right-aligned line instead of
              overflowing the dialog at narrow widths. */}
          <div className="mb-1.5 flex flex-wrap items-baseline gap-x-2 gap-y-1">
            {topic.emoji && <span className="text-15 leading-none">{topic.emoji}</span>}
            <span
              className={cn(
                'min-w-0 break-words text-15 font-medium leading-tight tracking-tight',
                'text-[var(--msg-assistant-text)]',
              )}
            >
              {topic.title}
            </span>
            {topic.contributors.length > 0 && (
              <span className="ml-auto max-w-full break-words text-right text-12 text-[var(--cmd-palette-item-meta)]">
                {topic.contributors.join(' · ')}
              </span>
            )}
          </div>
          <div className="text-sm leading-[1.7] break-words text-[var(--msg-assistant-text)]">
            {topic.text}
          </div>
        </div>
      ))}
    </>
  );
}

/**
 * One version's block, single column throughout:
 *
 *   [v0.1.21]  2026年7月29日      <- subheader: version + date only
 *   intro / topics (v2)  or  sections (legacy)
 *   ─────────────────────────
 *   🌸 感谢 A · B · C            <- closing thanks line
 *
 * The subheader deliberately no longer repeats the contributor list: it is the
 * thanks line's job, once, at the end. The outer container owns scrolling.
 */
function VersionBlock({ notes, locale }: { notes: ReleaseNotes; locale: string }) {
  const isTopicFormat = notes.topics.length > 0;
  const formattedDate = formatDate(notes.date, locale);
  return (
    <div className="flex flex-col items-center px-7 pb-2">
      <div className={cn(CONTENT_COLUMN, 'flex items-center gap-2 pt-5')}>
        <VersionBadge label={`v${notes.version}`} />
        {/* nowrap: a long date must not be squeezed into three lines by
            whatever sits next to it (the old subheader did exactly that). */}
        <span className="whitespace-nowrap text-13 text-[var(--cmd-palette-item-meta)]">
          {formattedDate}
        </span>
      </div>
      {isTopicFormat ? (
        <TopicList intro={notes.intro} topics={notes.topics} />
      ) : (
        <SectionList sections={notes.sections} />
      )}
      <ThanksLine contributors={notes.contributors} />
    </div>
  );
}

/**
 * Placeholder for a manual-mode version whose notes haven't been loaded yet
 * (either not yet in view, or in flight, or permanently 404). Uses a fixed
 * min-height so scroll offsets stay stable when the real content swaps in.
 *
 * Error state is terminal (see ManualBody's startLoad guard) — but users can
 * hit the retry button to explicitly re-fire the fetch, useful when a CDN
 * eventually-consistent publish catches up after the initial miss.
 */
function PlaceholderBlock({
  version,
  isLoading,
  isError,
  onRetry,
}: {
  version: string;
  /**
   * True only while a fetch is actually in flight. `idle` (queued but not yet
   * observed) must NOT set this: every off-screen version used to render a
   * spinner + "loading", so a user opening the history saw a dozen versions
   * apparently stuck loading forever when in fact nothing had been requested.
   */
  isLoading: boolean;
  isError: boolean;
  onRetry?: () => void;
}) {
  const { t } = useTranslation();
  return (
    <div className="flex min-h-[180px] flex-col items-center px-7">
      <div className={cn(CONTENT_COLUMN, 'flex items-center gap-3 pt-5')}>
        <VersionBadge label={`v${version}`} />
        {isLoading && (
          <span className="inline-flex items-center gap-1.5 text-12 text-[var(--cmd-palette-item-meta)]">
            <Spinner size={14} />
            {t('update.notice.loading')}
          </span>
        )}
        {isError && (
          <span className="inline-flex items-center gap-2 text-12 text-[var(--cmd-palette-item-meta)]">
            {t('update.notice.loadFailed')}
            {onRetry && (
              <Button variant="secondary" size="xxs" compact type="button" onClick={onRetry}>
                {t('update.notice.retry')}
              </Button>
            )}
          </span>
        )}
      </div>
      {/* Idle (not yet scrolled near, nothing in flight) renders as reserved
          blank space, not as a spinner — see PlaceholderBlock's isLoading doc. */}
      <div className="flex min-h-[120px] flex-1 items-center justify-center" aria-hidden />
    </div>
  );
}

// ---------------------------------------------------------------------------
// Manual-mode dropdown: click header badge to jump to any version.
// ---------------------------------------------------------------------------

interface VersionDropdownProps {
  versions: string[];
  currentVersion: string;
  onSelect: (version: string) => void;
  triggerLabel: string;
  /**
   * Accessible name for the trigger. Must be given separately from
   * `triggerLabel`: the visible chip only shows a version *count*, so reusing
   * it as the accessible name would leave screen-reader users with no way to
   * tell which version they are currently on without opening the menu.
   */
  triggerAriaLabel: string;
  /**
   * Bubble open state up so the parent AlertDialog can guard its own
   * dismissal while the dropdown is open or has just closed.
   */
  onOpenChange?: (open: boolean) => void;
}

export function VersionDropdown({
  versions,
  currentVersion,
  onSelect,
  triggerLabel,
  triggerAriaLabel,
  onOpenChange,
}: VersionDropdownProps) {
  return (
    <DropdownMenu onOpenChange={onOpenChange} modal>
      <DropdownMenuTrigger asChild>
        <button
          type="button"
          className="inline-flex outline-none"
          aria-label={triggerAriaLabel}
        >
          {/* The trigger now reads "N versions", not a version number, so the
              flame glyph would be misleading — hence icon={false}. */}
          <VersionBadge label={triggerLabel} clickable icon={false} />
        </button>
      </DropdownMenuTrigger>
      <DropdownMenuContent
        side="bottom"
        align="end"
        sideOffset={6}
        // Stop clicks inside dropdown content from bubbling — belt-and-
        // suspenders on top of `modal` prop + parent dropdownOpenRef guard.
        onClick={(e) => e.stopPropagation()}
        // Above the AlertDialog layer; long version lists scroll.
        className="z-[10001] max-h-[400px] overflow-y-auto"
      >
        {/* The version on screen is the checked radio row. Each row still calls
            onSelect on activation, the current one included, as before. */}
        <DropdownMenuRadioGroup value={currentVersion}>
          {versions.map((v) => (
            <DropdownMenuRadioItem key={v} value={v} onSelect={() => onSelect(v)}>
              <span className="tabular-nums">v{v}</span>
            </DropdownMenuRadioItem>
          ))}
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

// ---------------------------------------------------------------------------
// Auto-mode body: static header badge (v<oldest> → v<newest>), preloaded
// blocks stacked.
// ---------------------------------------------------------------------------

function AutoBody({
  releaseNotes,
  locale,
  onStickyChange,
}: {
  releaseNotes: ReleaseNotes[];
  locale: string;
  onStickyChange: (version: string) => void;
}) {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  const blockRefs = useRef<Map<string, HTMLDivElement>>(new Map());

  // Sticky-header observer: track which version block is at the top of the
  // scroll area so the header badge can follow. Only active for multi-version
  // auto mode — single-version stays at its initial value.
  useEffect(() => {
    const root = scrollRef.current;
    if (!root || releaseNotes.length <= 1) return;
    const observer = new IntersectionObserver(
      (entries) => {
        let best: { v: string; top: number } | null = null;
        for (const entry of entries) {
          if (!entry.isIntersecting) continue;
          const v = (entry.target as HTMLElement).dataset.version;
          if (!v) continue;
          const top = entry.boundingClientRect.top;
          // Pick the entry whose top is closest to the container top
          // (largest top = nearest to 0, i.e. the version the user is reading).
          if (best === null || top > best.top) best = { v, top };
        }
        if (best) onStickyChange(best.v);
      },
      { root, rootMargin: '0px 0px -99% 0px', threshold: 0 },
    );
    for (const el of blockRefs.current.values()) observer.observe(el);
    return () => observer.disconnect();
  }, [releaseNotes, onStickyChange]);

  // Fallback: when scrolled to the bottom, pick the last version so the header
  // badge updates even if the last version is too short to reach the observation
  // zone at the top. When leaving the bottom, recompute the visible version so
  // the badge doesn't stay stuck on the last version.
  const lastVersion = releaseNotes[releaseNotes.length - 1]?.version;
  const handleAutoScroll = useCallback(() => {
    const el = scrollRef.current;
    if (!el || !lastVersion) return;
    // Guard: only apply the bottom override when the content is actually
    // scrollable.  A +1 px threshold prevents sub-pixel rounding at
    // non-integer zoom from making scrollHeight − clientHeight = 1 while
    // the content is visually unscrollable; otherwise scrollTop is always
    // 0 and the condition would trivially hold at the top, causing the
    // header to show the last version.
    if (
      el.scrollHeight > el.clientHeight + 1 &&
      el.scrollTop + el.clientHeight >= el.scrollHeight - 1
    ) {
      onStickyChange(lastVersion);
      return;
    }
    // Leaving the bottom: find the version block currently closest to the
    // container top. This mirrors the IntersectionObserver's sticky-header
    // logic but runs on every scroll event when not at the very bottom,
    // clearing the bottom override that the IO cannot undo on its own.
    const containerTop = el.getBoundingClientRect().top;
    let best: { v: string; top: number } | null = null;
    for (const [version, blockEl] of blockRefs.current.entries()) {
      const top = blockEl.getBoundingClientRect().top;
      if (top > containerTop + 9) continue; // block far below container top (9px = py-2 padding + 1px tolerance)
      if (best === null || top > best.top) best = { v: version, top };
    }
    if (best) onStickyChange(best.v);
  }, [lastVersion, onStickyChange]);

  return (
    <div
      ref={scrollRef}
      onScroll={handleAutoScroll}
      className="flex flex-1 min-h-0 flex-col overflow-y-auto py-2 select-text"
    >
      {releaseNotes.map((notes, i) => (
        <div
          key={notes.version}
          ref={(el) => {
            if (el) blockRefs.current.set(notes.version, el);
            else blockRefs.current.delete(notes.version);
          }}
          data-version={notes.version}
          className="flex flex-col"
        >
          {i > 0 && <div className="mx-auto h-px w-full max-w-[800px] bg-[var(--cmd-palette-border)]" />}
          <VersionBlock notes={notes} locale={locale} />
        </div>
      ))}
    </div>
  );
}

// ---------------------------------------------------------------------------
// Manual-mode body: full history with lazy hydration.
// ---------------------------------------------------------------------------

/** State of a single version's fetch. */
type LoadState = 'idle' | 'loading' | 'loaded' | 'error';

interface ManualBodyProps {
  allVersions: string[];
  initialLoaded: Map<string, ReleaseNotes>;
  loadVersion: (v: string) => Promise<ReleaseNotes | null>;
  locale: string;
  /** Called when the topmost visible version changes, so header can update. */
  onStickyChange: (version: string) => void;
  /** Setter registered by parent so `jumpToVersion` can programmatically scroll. */
  registerJump: (fn: (v: string) => void) => void;
}

function ManualBody({
  allVersions,
  initialLoaded,
  loadVersion,
  locale,
  onStickyChange,
  registerJump,
}: ManualBodyProps) {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  const blockRefs = useRef<Map<string, HTMLDivElement>>(new Map());
  const [notesMap, setNotesMap] = useState<Map<string, ReleaseNotes>>(initialLoaded);
  const [stateMap, setStateMap] = useState<Map<string, LoadState>>(() => {
    const m = new Map<string, LoadState>();
    for (const v of allVersions) {
      m.set(v, initialLoaded.has(v) ? 'loaded' : 'idle');
    }
    return m;
  });
  const inFlightRef = useRef<Map<string, number>>(new Map());
  const localeGenerationRef = useRef(0);
  const previousLocaleRef = useRef(locale);
  const notesMapRef = useRef(notesMap);
  // Ref mirror of stateMap so `startLoad` doesn't need it in useCallback deps.
  // Without this, every setStateMap → new startLoad identity → observer
  // useEffect re-runs → new observer immediately fires callbacks for still-
  // intersecting blocks → for `error` state blocks, retriggers fetch → error
  // again → infinite loading↔failed flicker (the bug this refactor fixes).
  const stateMapRef = useRef(stateMap);
  useEffect(() => { stateMapRef.current = stateMap; }, [stateMap]);
  useEffect(() => { notesMapRef.current = notesMap; }, [notesMap]);

  // Parent-owned seed notes change when the app locale changes. Merge them
  // into the manual body's local map instead of remounting the scroll area.
  useEffect(() => {
    if (initialLoaded.size === 0) return;
    setNotesMap((prev) => {
      const next = new Map(prev);
      for (const [version, notes] of initialLoaded) next.set(version, notes);
      notesMapRef.current = next;
      return next;
    });
    setStateMap((prev) => {
      const next = new Map(prev);
      for (const version of initialLoaded.keys()) next.set(version, 'loaded');
      stateMapRef.current = next;
      return next;
    });
  }, [initialLoaded]);

  // Refresh every already-loaded history block in place on locale changes.
  // Blocks that have never loaded stay idle and will use the new locale later.
  useEffect(() => {
    if (previousLocaleRef.current === locale) return;
    previousLocaleRef.current = locale;
    const generation = localeGenerationRef.current + 1;
    localeGenerationRef.current = generation;
    inFlightRef.current.clear();
    setStateMap((prev) => {
      const next = new Map(prev);
      for (const [version, state] of next) {
        if (state === 'loading') next.set(version, 'idle');
      }
      stateMapRef.current = next;
      return next;
    });

    const loadedVersions = [...notesMapRef.current.keys()];
    if (loadedVersions.length === 0) return;
    let cancelled = false;
    void Promise.all(loadedVersions.map((version) => loadVersion(version)))
      .then((results) => {
        if (cancelled || localeGenerationRef.current !== generation) return;
        setNotesMap((prev) => {
          const next = new Map(prev);
          results.forEach((notes, index) => {
            if (notes) next.set(loadedVersions[index], notes);
          });
          notesMapRef.current = next;
          return next;
        });
      })
      .catch(() => {
        // Keep the previous-language content visible; individual retry/loading
        // behavior remains unchanged and the next locale change can retry.
      });
    return () => { cancelled = true; };
  }, [locale, loadVersion]);

  const startLoad = useCallback(
    async (version: string) => {
      if (inFlightRef.current.has(version)) return;
      const current = stateMapRef.current.get(version);
      // Terminal states — never retry automatically. Loaded needs no work,
      // loading is already in flight (also guarded by inFlightRef), error is
      // sticky until user hits the retry button (see `retryVersion`).
      if (current === 'loaded' || current === 'loading' || current === 'error') return;
      const generation = localeGenerationRef.current;
      inFlightRef.current.set(version, generation);
      setStateMap((prev) => new Map(prev).set(version, 'loading'));
      try {
        const notes = await loadVersion(version);
        if (localeGenerationRef.current !== generation) return;
        if (notes) {
          setNotesMap((prev) => {
            const next = new Map(prev).set(version, notes);
            notesMapRef.current = next;
            return next;
          });
          setStateMap((prev) => new Map(prev).set(version, 'loaded'));
        } else {
          setStateMap((prev) => new Map(prev).set(version, 'error'));
        }
      } catch {
        if (localeGenerationRef.current !== generation) return;
        setStateMap((prev) => new Map(prev).set(version, 'error'));
      } finally {
        if (inFlightRef.current.get(version) === generation) {
          inFlightRef.current.delete(version);
        }
      }
    },
    [loadVersion],
  );

  // Manual retry from the error placeholder's button. Only meaningful for
  // 'error' state (idle/loading/loaded are no-ops). Resets state to idle so
  // startLoad's guard passes, then kicks off a fresh fetch. Sync-mutates the
  // ref so the immediate startLoad call sees the reset — the paired
  // setStateMap keeps React state consistent for rendering.
  const retryVersion = useCallback(
    (version: string) => {
      if (stateMapRef.current.get(version) !== 'error') return;
      const next = new Map(stateMapRef.current);
      next.set(version, 'idle');
      stateMapRef.current = next;
      setStateMap(next);
      void startLoad(version);
    },
    [startLoad],
  );

  // Lazy-load observer: fires when a block enters or is within 400px of the
  // viewport so hydration starts before the user actually reaches it.
  useEffect(() => {
    const root = scrollRef.current;
    if (!root) return;
    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          if (!entry.isIntersecting) continue;
          const v = (entry.target as HTMLElement).dataset.version;
          if (v) void startLoad(v);
        }
      },
      { root, rootMargin: '400px 0px 400px 0px', threshold: 0 },
    );
    for (const el of blockRefs.current.values()) observer.observe(el);
    return () => observer.disconnect();
  }, [allVersions, startLoad]);

  // Sticky-header observer: narrow band at the very top of the scroll area
  // tells us which version block the user is currently reading. Whichever
  // entry's top edge is closest to (but not past) the scroll-container top
  // wins the badge.
  useEffect(() => {
    const root = scrollRef.current;
    if (!root) return;
    // rootMargin trick: negative bottom margin equal to (100% - 1px) shrinks
    // the intersection zone to a 1px band at the top. Any element crossing
    // that band is by definition the topmost currently-scrolled-to element.
    const observer = new IntersectionObserver(
      (entries) => {
        // Pick the entry whose top is closest to the container top
        // (largest top = nearest to 0, i.e. the version the user is reading).
        let best: { v: string; top: number } | null = null;
        for (const entry of entries) {
          if (!entry.isIntersecting) continue;
          const v = (entry.target as HTMLElement).dataset.version;
          if (!v) continue;
          const top = entry.boundingClientRect.top;
          if (best === null || top > best.top) best = { v, top };
        }
        if (best) onStickyChange(best.v);
      },
      { root, rootMargin: '0px 0px -99% 0px', threshold: 0 },
    );
    for (const el of blockRefs.current.values()) observer.observe(el);
    return () => observer.disconnect();
  }, [allVersions, onStickyChange]);

  // Fallback: when scrolled to the bottom, pick the last version so the header
  // badge updates even if the last version is too short to reach the top
  // observation zone. When leaving the bottom, recompute the visible version so
  // the badge doesn't stay stuck on the last version.
  const lastVersion = allVersions[allVersions.length - 1];
  const handleManualScroll = useCallback(() => {
    const el = scrollRef.current;
    if (!el || !lastVersion) return;
    // Guard: only apply the bottom override when the content is actually
    // scrollable.  A +1 px threshold prevents sub-pixel rounding at
    // non-integer zoom from making scrollHeight − clientHeight = 1 while
    // the content is visually unscrollable; otherwise scrollTop is always
    // 0 and the condition would trivially hold at the top, causing the
    // header to show the last version.
    if (
      el.scrollHeight > el.clientHeight + 1 &&
      el.scrollTop + el.clientHeight >= el.scrollHeight - 1
    ) {
      onStickyChange(lastVersion);
      return;
    }
    // Leaving the bottom: find the version block currently closest to the
    // container top. This mirrors the IntersectionObserver's sticky-header
    // logic but runs on every scroll event when not at the very bottom,
    // clearing the bottom override that the IO cannot undo on its own.
    const containerTop = el.getBoundingClientRect().top;
    let best: { v: string; top: number } | null = null;
    for (const [version, blockEl] of blockRefs.current.entries()) {
      const top = blockEl.getBoundingClientRect().top;
      if (top > containerTop + 9) continue; // block far below container top (9px = py-2 padding + 1px tolerance)
      if (best === null || top > best.top) best = { v: version, top };
    }
    if (best) onStickyChange(best.v);
  }, [lastVersion, onStickyChange]);

  // Programmatic jump handler exposed to parent (header dropdown).
  useEffect(() => {
    registerJump((v: string) => {
      const el = blockRefs.current.get(v);
      if (!el) return;
      // Use instant scroll to avoid triggering IntersectionObserver for all
      // intermediate placeholders (smooth scroll would fan out CDN requests).
      el.scrollIntoView({ behavior: 'instant', block: 'start' });
      void startLoad(v);
    });
  }, [registerJump, startLoad]);

  return (
    <div
      ref={scrollRef}
      onScroll={handleManualScroll}
      className="flex flex-1 min-h-0 flex-col overflow-y-auto py-2 select-text"
    >
      {allVersions.map((v, i) => {
        const notes = notesMap.get(v);
        const state = stateMap.get(v) ?? 'idle';
        return (
          <div
            key={v}
            ref={(el) => {
              if (el) blockRefs.current.set(v, el);
              else blockRefs.current.delete(v);
            }}
            data-version={v}
            className="flex flex-col"
          >
            {i > 0 && <div className="mx-auto h-px w-full max-w-[800px] bg-[var(--cmd-palette-border)]" />}
            {notes ? (
              <VersionBlock notes={notes} locale={locale} />
            ) : (
              <PlaceholderBlock
                version={v}
                isLoading={state === 'loading'}
                isError={state === 'error'}
                onRetry={() => retryVersion(v)}
              />
            )}
          </div>
        );
      })}
    </div>
  );
}

// ---------------------------------------------------------------------------
// Main component
// ---------------------------------------------------------------------------

export function UpdateNoticeDialog({
  open,
  mode,
  releaseNotes,
  allVersions,
  loadVersion,
  onDismiss,
}: UpdateNoticeDialogProps) {
  const { t, i18n } = useTranslation();

  // Memo-ize the seed Map so ManualBody's useState(initialLoaded) doesn't
  // receive a new object identity on every parent re-render. The Map is only
  // read once at ManualBody mount, but avoiding the allocation cost is free.
  const initialLoaded = useMemo(
    () => new Map((releaseNotes ?? []).map((n) => [n.version, n])),
    [releaseNotes],
  );

  // Sticky version state — used only in manual mode; defaults to the newest
  // preloaded version so the header badge is populated from the very first
  // frame (no null flash while IntersectionObserver hasn't fired yet).
  const initialSticky = releaseNotes?.[0]?.version ?? '';
  const [stickyVersion, setStickyVersion] = useState<string>(initialSticky);

  const jumpRef = useRef<((v: string) => void) | null>(null);
  const registerJump = useCallback((fn: (v: string) => void) => {
    jumpRef.current = fn;
  }, []);

  // Track version-dropdown open state + timestamp of most recent close, so a
  // dismissal aimed at the dropdown (e.g. Escape) never cascades into closing
  // the whole dialog. Any dismissal within `GRACE_MS` of a dropdown close is
  // treated as part of the same gesture and bounces.
  const DROPDOWN_CLOSE_GRACE_MS = 200;
  const dropdownOpenRef = useRef(false);
  const dropdownClosedAtRef = useRef(0);
  const dismissIfDialogOnly = useCallback(() => {
    if (dropdownOpenRef.current) return;
    if (Date.now() - dropdownClosedAtRef.current < DROPDOWN_CLOSE_GRACE_MS) return;
    onDismiss();
  }, [onDismiss]);

  // Reset sticky when dialog re-opens (avoids showing last-session's badge).
  // Preserve the current sticky version across locale refreshes — when the
  // dialog is already open and releaseNotes changes only because of a locale
  // switch, the scroll position in ManualBody remains in place so the badge
  // should not jump back to the newest version.
  const wasOpenRef = useRef(false);
  useEffect(() => {
    if (open) {
      if (!wasOpenRef.current) {
        setStickyVersion(releaseNotes?.[0]?.version ?? '');
      }
    }
    wasOpenRef.current = open;
  }, [open, releaseNotes]);

  if (!releaseNotes || !mode || releaseNotes.length === 0) {
    return null;
  }

  const isManual = mode === 'manual';
  const newest = releaseNotes[0];
  const oldestLoaded = releaseNotes[releaseNotes.length - 1];

  const isAutoMulti = mode === 'auto' && releaseNotes.length > 1;

  // Aria description reads differently for each mode so screen-readers get
  // a sensible summary instead of a generic "release notes for vX".
  const ariaDescription = isManual
    ? t('update.notice.ariaDescriptionSpan', {
        from: (allVersions && allVersions.length > 0)
          ? allVersions[allVersions.length - 1]
          : newest.version,
        count: allVersions?.length ?? 1,
      })
    : isAutoMulti
      ? t('update.notice.ariaDescriptionSpan', {
          from: oldestLoaded.version,
          count: releaseNotes.length,
        })
      : t('update.notice.ariaDescription', { version: newest.version });

  // Header's right cell: version badge that follows scroll.
  //   - Manual multi:   v<version> badge + dropdown for history navigation.
  //   - Auto multi:     v<version> badge, updates as user scrolls.
  //   - Auto / manual single: static v<version> badge.

  return (
    <AlertDialog.Root
      open={open}
      // Route Radix-driven dismissal (Escape key) through dismissIfDialogOnly:
      // dropdownOpenRef + grace window prevent spurious closes triggered by
      // the version dropdown's own dismissal.
      onOpenChange={(v) => { if (!v) dismissIfDialogOnly(); }}
    >
      <AlertDialog.Portal>
        <AlertDialog.Overlay
          className={cn(
            'modal-scrim fixed inset-0 z-[10000]',
          )}
          style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
          // No scrim click-to-dismiss (DESIGN.md closing affordance): the
          // dialog closes only via 「知道了」 or Escape.
        />

        <AlertDialog.Content
          className={cn(
            'modal-panel fixed left-1/2 top-1/2 z-[10000] -translate-x-1/2 -translate-y-1/2',
            // 920px, not the previous 1240px: the body is a single ~800px
            // reading column now, so the extra width only produced dead margins
            // and made the full-width chrome visibly mismatch the narrow body.
            'w-[920px] h-[838px] max-w-[95vw] max-h-[90vh] flex flex-col',
          )}
          style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
        >
          <AlertDialog.Description className="sr-only">
            {ariaDescription}
          </AlertDialog.Description>

          {/* ---- Header ----
              3-column grid instead of flex-justify-between so the right cell's
              width changes never shift the centered title: each 1fr cell is
              exactly a third of the header width, so the title always sits at
              the true horizontal middle. The left cell is intentionally empty —
              it exists to balance the grid. `min-w-0` keeps a long right label
              from blowing out its track. */}
          <div className="grid grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 px-6 pt-4 pb-3.5">
            <span aria-hidden />
            <AlertDialog.Title className="text-20 leading-[1.4] font-medium text-[var(--msg-assistant-text)] justify-self-center whitespace-nowrap">
              {t('update.notice.title')}
            </AlertDialog.Title>
            <div className="min-w-0 justify-self-end">
              {isManual && allVersions && allVersions.length > 1 ? (
                <VersionDropdown
                  versions={allVersions}
                  currentVersion={stickyVersion || newest.version}
                  triggerLabel={`v${stickyVersion || newest.version}`}
                  triggerAriaLabel={t('update.notice.versionJumpAria', {
                    count: allVersions.length,
                    version: stickyVersion || newest.version,
                  })}
                  onSelect={(v) => jumpRef.current?.(v)}
                  onOpenChange={(dropOpen) => {
                    dropdownOpenRef.current = dropOpen;
                    // Record close timestamp so dismissIfDialogOnly can treat
                    // a dismissal within the grace window as part of the
                    // same close gesture and bounce it.
                    if (!dropOpen) dropdownClosedAtRef.current = Date.now();
                  }}
                />
              ) : (
                <VersionBadge label={`v${stickyVersion || newest.version}`} />
              )}
            </div>
          </div>

          <div className="h-px bg-[var(--cmd-palette-border)]" />

          {/* ---- Content ---- */}
          {/* Auto single-version no longer needs its own branch: VersionBlock
              carries the version, date and thanks itself, so one block and N
              blocks render through the same path. */}
          {isManual && allVersions ? (
            <ManualBody
              allVersions={allVersions}
              initialLoaded={initialLoaded}
              loadVersion={loadVersion}
              locale={i18n.language}
              onStickyChange={setStickyVersion}
              registerJump={registerJump}
            />
          ) : (
            <AutoBody
              releaseNotes={releaseNotes}
              locale={i18n.language}
              onStickyChange={setStickyVersion}
            />
          )}

          <div className="h-px bg-[var(--cmd-palette-border)]" />

          {/* ---- Footer ---- */}
          <div className="flex justify-center px-7 pt-4 pb-5">
            {/* flex-wrap + min-w-0: long titles shrink/wrap and an overlong
                contributor list drops to its own right-aligned line instead of
                overflowing the dialog at narrow widths. */}
            <Button variant="primary" size="lg" type="button" onClick={onDismiss}>
              {t('update.notice.gotIt')}
            </Button>
          </div>
        </AlertDialog.Content>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
}