@flamingo-stack/openframe-frontend-core 0.0.492-1506.3956.1 → 0.0.492

package/src/components/features/floating-walkthrough-video.tsx

@@ -738,7 +738,9 @@ export function FloatingWalkthroughVideo({
         ) : (
           <VideoPlayBadge size="sm" className="h-5 w-5 shrink-0" />
         )}
-        <span className="truncate">{label}</span>
+        {/* The video's OWN title is the point of the pill; `label` is only the
+            generic fallback for a video that carries no title. */}
+        <span className="truncate">{summaryTitle || label}</span>
       </span>
 
       {/* BIG centred glyph — the muted-fallback prompt (bite grammar). It IS

package/src/components/navigation/navigation-sidebar-item.tsx

@@ -1,6 +1,7 @@
 "use client"
 
-import { cloneElement, type ReactElement } from 'react'
+import { cloneElement, memo, type ReactElement, type ReactNode } from 'react'
+import Link from '../../embed-shims/next-link'
 import { NavigationSidebarItem } from '../../types/navigation'
 import { cn } from '../../utils'
 
@@ -11,46 +12,72 @@ interface IconProps {
 
 export interface NavigationSidebarItemButtonProps {
   item: NavigationSidebarItem
+  /** "You are on this page" — pathname-derived, and the only thing that carries `aria-current`. */
+  isActive: boolean
+  /**
+   * "You clicked this one and it has not arrived yet" — deliberately a separate,
+   * weaker state. Never promoted to active: the accent belongs to the page you
+   * are actually on.
+   */
+  isPending: boolean
   showLabel: boolean
   disabled: boolean
   onClick: (item: NavigationSidebarItem, event?: React.MouseEvent) => void
 }
 
-export function NavigationSidebarItemButton({
+/**
+ * One sidebar entry.
+ *
+ * Rendered as a real anchor whenever it has a `path` — which is what buys the
+ * two things a `<button>` + `router.push` cannot: Next prefetches links that
+ * are in the viewport (so the section is usually already loaded by the time it
+ * is clicked, instead of every first visit paying a cold segment fetch), and
+ * the browser's own affordances work — middle-click, ⌘/Ctrl-click, "open in new
+ * tab", copy link, and a status-bar URL on hover.
+ *
+ * Falls back to a `<button>` for entries that only carry an `onClick` (no
+ * destination to link to) and for the disabled state, which an anchor cannot
+ * express.
+ */
+export const NavigationSidebarItemButton = memo(function NavigationSidebarItemButton({
   item,
+  isActive,
+  isPending,
   showLabel,
   disabled,
   onClick,
 }: NavigationSidebarItemButtonProps) {
-  const isActive = item.isActive ?? false
   const unreadCount = item.unreadCount ?? 0
   const hasUnread = unreadCount > 0
 
-  return (
-    <button
-      onClick={(event) => onClick(item, event)}
-      disabled={disabled}
-      className={cn(
-        "w-full flex items-center justify-start relative",
-        "h-14 p-[var(--spacing-system-m)]",
-        "transition-colors duration-300",
-        "[&_svg]:transition-colors [&_svg]:duration-300",
-        "before:content-[''] before:absolute before:left-0 before:top-0 before:bottom-0 before:w-1",
-        "before:transition-colors before:duration-300",
-        !isActive && !disabled && "hover:bg-ods-bg-hover text-ods-text-primary [&_svg]:fill-ods-text-secondary",
-        !isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
-        isActive && !disabled && [
-          "bg-[var(--ods-open-yellow-light)] text-ods-accent",
-          "[&_svg]:fill-ods-accent",
-          "before:bg-ods-accent",
-        ],
-        isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
-        disabled && "cursor-not-allowed opacity-50",
-      )}
-      title={!showLabel ? item.label : undefined}
-      aria-label={item.label}
-      aria-current={isActive ? 'page' : undefined}
-    >
+  const className = cn(
+    "w-full flex items-center justify-start relative",
+    "h-14 p-[var(--spacing-system-m)]",
+    // 150ms, not 300: the outgoing and incoming entries cross-fade, so for the
+    // whole duration TWO rows read as half-active. At 300ms that window is long
+    // enough to look like a flicker rather than a transition.
+    "transition-colors duration-150",
+    "[&_svg]:transition-colors [&_svg]:duration-150",
+    "before:content-[''] before:absolute before:left-0 before:top-0 before:bottom-0 before:w-1",
+    "before:transition-colors before:duration-150",
+    // Pending borrows the HOVER weight and nothing else — no accent bar, no
+    // accent text, no `aria-current`. It says "this row is working", not "this
+    // is where you are", and it reads as the row staying pressed under the
+    // cursor, which is exactly what happened.
+    !isActive && !disabled && "hover:bg-ods-bg-hover text-ods-text-primary [&_svg]:fill-ods-text-secondary",
+    !isActive && !disabled && isPending && "bg-ods-bg-hover",
+    !isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
+    isActive && !disabled && [
+      "bg-[var(--ods-open-yellow-light)] text-ods-accent",
+      "[&_svg]:fill-ods-accent",
+      "before:bg-ods-accent",
+    ],
+    isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
+    disabled && "cursor-not-allowed opacity-50",
+  )
+
+  const content: ReactNode = (
+    <>
       <div className="relative flex items-center justify-center flex-shrink-0">
         {cloneElement(item.icon as ReactElement<IconProps>, {
           color: isActive && !disabled ? "text-ods-accent" : "text-ods-text-secondary",
@@ -77,6 +104,29 @@ export function NavigationSidebarItemButton({
           </span>
         </span>
       )}
-    </button>
+    </>
   )
-}
+
+  const shared = {
+    className,
+    title: !showLabel ? item.label : undefined,
+    'aria-label': item.label,
+    'aria-current': isActive ? ('page' as const) : undefined,
+  }
+
+  // An entry with a custom onClick has no destination of its own, and a
+  // disabled one must not be followable — both stay buttons.
+  if (disabled || !item.path || item.onClick) {
+    return (
+      <button type="button" onClick={(event) => onClick(item, event)} disabled={disabled} {...shared}>
+        {content}
+      </button>
+    )
+  }
+
+  return (
+    <Link href={item.path} onClick={(event) => onClick(item, event)} {...shared}>
+      {content}
+    </Link>
+  )
+})

package/src/components/navigation/navigation-sidebar.tsx

@@ -13,6 +13,10 @@ const MINIMIZED_WIDTH = 56 // 3.5rem = 56px
 const EXPANDED_WIDTH = 224 // 14rem = 224px
 const STORAGE_KEY = 'of.navigationSidebar.minimized'
 
+/** A click the browser will resolve itself — new tab, new window, middle button. */
+const isModifiedClick = (event?: React.MouseEvent): boolean =>
+  !!event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0)
+
 export interface NavigationSidebarProps {
   config: NavigationSidebarConfig
   /**
@@ -75,17 +79,68 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     return () => document.removeEventListener('keydown', handleKeyDown)
   }, [isOverlayOpen, closeOverlay])
 
+  // The entry the user just clicked, held until the route commits.
+  //
+  // PENDING IS NOT ACTIVE, and keeping the two apart is the whole point. Active
+  // means "this is the page you are on" — it carries the accent bar and
+  // `aria-current="page"`, and it stays derived from the pathname, so it is
+  // never asserted before it is true. Pending only means "this is the one you
+  // clicked": a click deserves an answer, but the answer must not be a claim
+  // about where you are. Folding pending into active would light the accent on
+  // a section still loading and announce it as the current page to a screen
+  // reader — a statement that is simply false until the router says otherwise.
+  const [pendingItemId, setPendingItemId] = useState<string | null>(null)
+  const committedActiveId = useMemo(
+    () => config.items.find(item => item.isActive)?.id ?? null,
+    [config.items],
+  )
+
+  // Any committed change clears it — including one that landed somewhere else
+  // entirely (a redirect, a link elsewhere on the page). A navigation that never
+  // commits leaves a faint hold on the row it started from; because pending is
+  // only ever a soft hint, that costs nothing but a stale hover-weight tint,
+  // where a stale ACTIVE state would have been a lie about the current page.
+  useEffect(() => {
+    setPendingItemId(null)
+  }, [committedActiveId])
+
   const handleItemClick = useCallback((item: NavigationSidebarItem, event?: React.MouseEvent) => {
     event?.stopPropagation()
 
     if (item.onClick) {
       item.onClick()
-    } else if (item.path) {
-      config.onNavigate?.(item.path)
+      if (isTablet) setTabletMinimized(true)
+      return
+    }
+
+    if (!item.path) return
+
+    // ⌘/Ctrl/Shift-click and middle-click open the link somewhere else. THIS
+    // window is not going anywhere, so the browser is left to it: no
+    // preventDefault, no optimistic highlight, no closing the tablet overlay.
+    // Entries render as real anchors precisely so those gestures work at all.
+    if (isModifiedClick(event)) return
+
+    // A plain click stays the host's to perform, through `onNavigate` exactly
+    // as before — the anchor is here for the href (Next prefetches links in the
+    // viewport) and for the browser affordances, not to take over routing.
+    //
+    // `onNavigate` is optional, though, and with no host router there is nothing
+    // to hand the click to: swallowing it would leave a real anchor, with a real
+    // href, that does nothing at all. So the guard is on having somewhere to
+    // send it — otherwise the anchor navigates on its own and we only close the
+    // overlay behind it.
+    if (config.onNavigate) {
+      event?.preventDefault()
+      // Re-clicking the page you are already on starts no navigation, so there
+      // is nothing to mark — and nothing would ever clear it, since the
+      // committed active id is not about to change.
+      if (item.id !== committedActiveId) setPendingItemId(item.id)
+      config.onNavigate(item.path)
     }
 
     if (isTablet) setTabletMinimized(true)
-  }, [config, isTablet])
+  }, [config, isTablet, committedActiveId])
 
   const { primaryItems, secondaryItems } = useMemo(() => ({
     primaryItems: config.items.filter(item => item.section !== 'secondary'),
@@ -97,16 +152,21 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     [minimized],
   )
 
-  const isHydrated = isMdUp !== undefined && isLgUp !== undefined
-
+  // There used to be an `isHydrated` gate here — `isMdUp !== undefined && ...`
+  // — meant to hold the sidebar's contents back until the media queries
+  // resolved. It could never be false: the `?? false` above had already
+  // swallowed the `undefined` it tested for. Removed rather than repaired,
+  // because repairing it would be the regression: the contents are server-
+  // rendered today, and gating them behind a client-only media query would
+  // trade a first paint of the real navigation for an empty rail.
   useLayoutEffect(() => {
-    if (isHydrated && !transitionsEnabled) {
+    if (!transitionsEnabled) {
       const id = requestAnimationFrame(() => {
         setTransitionsEnabled(true)
       })
       return () => cancelAnimationFrame(id)
     }
-  }, [isHydrated, transitionsEnabled])
+  }, [transitionsEnabled])
 
   return (
     <>
@@ -148,45 +208,45 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
         style={{ width: sidebarWidth }}
         aria-label="Main navigation sidebar"
       >
-        {isHydrated && (
-          <>
-            <NavigationSidebarHeader minimized={minimized} />
-
-            <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
-              <nav className="flex flex-col" aria-label="Primary navigation">
-                {primaryItems.map(item => (
-                  <NavigationSidebarItemButton
-                    key={item.id}
-                    item={item}
-                    showLabel={showLabel}
-                    disabled={disabled}
-                    onClick={handleItemClick}
-                  />
-                ))}
-              </nav>
-
-              {secondaryItems.length > 0 && (
-                <nav className="flex flex-col" aria-label="Secondary navigation">
-                  {secondaryItems.map(item => (
-                    <NavigationSidebarItemButton
-                      key={item.id}
-                      item={item}
-                      showLabel={showLabel}
-                      disabled={disabled}
-                      onClick={handleItemClick}
-                    />
-                  ))}
-                </nav>
-              )}
-            </div>
-
-            <NavigationSidebarToggle
-              minimized={minimized}
-              showLabel={showLabel}
-              onToggle={handleToggle}
-            />
-          </>
-        )}
+        <NavigationSidebarHeader minimized={minimized} />
+
+        <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
+          <nav className="flex flex-col" aria-label="Primary navigation">
+            {primaryItems.map(item => (
+              <NavigationSidebarItemButton
+                key={item.id}
+                item={item}
+                isActive={item.id === committedActiveId}
+                isPending={item.id === pendingItemId}
+                showLabel={showLabel}
+                disabled={disabled}
+                onClick={handleItemClick}
+              />
+            ))}
+          </nav>
+
+          {secondaryItems.length > 0 && (
+            <nav className="flex flex-col" aria-label="Secondary navigation">
+              {secondaryItems.map(item => (
+                <NavigationSidebarItemButton
+                  key={item.id}
+                  item={item}
+                  isActive={item.id === committedActiveId}
+                isPending={item.id === pendingItemId}
+                  showLabel={showLabel}
+                  disabled={disabled}
+                  onClick={handleItemClick}
+                />
+              ))}
+            </nav>
+          )}
+        </div>
+
+        <NavigationSidebarToggle
+          minimized={minimized}
+          showLabel={showLabel}
+          onToggle={handleToggle}
+        />
       </aside>
     </>
   )

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -15,7 +15,7 @@
  * renderer with extra plugins.
  */
 
-import { Fragment, type ComponentType, type ReactNode } from 'react'
+import { type ComponentType, type ReactNode } from 'react'
 import { PageLayout } from '../layout/page-layout'
 
 import { useRouter } from '../../embed-shims'
@@ -30,7 +30,7 @@ import { VideoBitesStrip } from '../features/video-bites-strip'
 import { toStripProfile } from '../features/video-bites-shared'
 import { useVideoWarmup } from '../features/use-video-warmup'
 import { getCaptionsUrl } from '../features/captions-url'
-import { RichMarkdownRenderer } from '../ui/markdown'
+import { RichMarkdownRenderer } from '../ui/rich-markdown-renderer'
 import { EntityTagBadges } from '../features/entity-tag-badges'
 import { LoadError } from '../ui/error-state'
 import { ArticleAuthorByline } from '../shared/article-author-byline'
@@ -244,26 +244,8 @@ export function OnboardingGuideDetailView({
           </div>
         )}
 
-        {/*
-         * Host slot — cross-type related-content / FAQ rail.
-         *
-         * KEYED DELIBERATELY. This is one member of PageLayout's static children
-         * array, and the only member whose element may be created in a SERVER
-         * component and crossed over the RSC boundary. Static JSX children are
-         * normally exempt from the key warning because `jsxs` runs
-         * `validateChildKeys` and stamps `_store.validated = 1` on each element —
-         * but a slot arriving over the wire is referenced as a lazy chunk wrapper,
-         * so validation marks the WRAPPER and the fulfilled path never copies the
-         * flag onto the revived element. It reaches the reconciler with
-         * `validated: 0, key: null` and warns, blaming PageLayout (the owner of the
-         * enclosing element) rather than anything actually at fault.
-         *
-         * A keyed Fragment emits no DOM, so rendered output is byte-identical.
-         * Do NOT "fix" this in PageLayout via `React.Children.toArray` — that would
-         * auto-key every consumer's children and change reconciliation identity for
-         * all of them, and that file carries an explicit FROZEN contract.
-         */}
-        <Fragment key="related-content">{relatedContent}</Fragment>
+        {/* Host slot — cross-type related-content / FAQ rail. */}
+        {relatedContent}
       </PageLayout>
   )
 }

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -19,7 +19,7 @@
 
 import type { ComponentType } from 'react';
 import { PageShell, PageLayout } from '../../ui';
-import { RichMarkdownRenderer } from '../../ui/markdown';
+import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
 import { formatLegalDate } from '../../../utils/format';

package/src/components/shared/product-release/release-detail-page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect, Fragment, ComponentType, type ReactNode } from 'react';
+import { useState, useEffect, ComponentType, type ReactNode } from 'react';
 import Link from '../../../embed-shims/next-link';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { Card, CardContent } from '../../ui/card';
@@ -11,7 +11,7 @@ import { PageShell } from '../../layout/article-detail-layout';
 import { PageLayout } from '../../layout/page-layout';
 import { FadePreview } from '../../ui/fade-preview';
 import { ReleaseChangelogSection } from '../../ui/release-changelog-section';
-import { RichMarkdownRenderer } from '../../ui/markdown';
+import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
 import { EntityTagBadges } from '../../features/entity-tag-badges';
 import { EntityMetadataAuthorCell } from '../../chat/entity-cards/entity-author-card';
 import type { EntityAuthor } from '../../../types/entity-author';
@@ -582,23 +582,8 @@ export function ReleaseDetailPage({
         )}
       </div>
 
-      {/*
-       * Host slot — end-of-article byline + related-content / FAQ rail.
-       *
-       * KEYED for the same reason as `onboarding-guide-detail-view.tsx`: this is a
-       * member of PageLayout's static children array, and a slot element built in a
-       * SERVER component crosses the RSC boundary as a lazy chunk wrapper, so
-       * `validateChildKeys` marks the wrapper and the fulfilled path never copies
-       * `_store.validated` onto the revived element — it reaches the reconciler
-       * unvalidated and warns.
-       *
-       * Today the hub's only consumer of this view is a `'use client'` wrapper that
-       * builds the slot locally, so no element actually crosses the boundary and
-       * this is pre-emptive. It is kept because the trap is invisible from here: a
-       * future server-built slot would warn with no clue pointing at this line.
-       * A keyed Fragment emits no DOM, so output is byte-identical either way.
-       */}
-      <Fragment key="related-content">{relatedContent}</Fragment>
+      {/* Host slot — end-of-article byline + related-content / FAQ rail. */}
+      {relatedContent}
       </PageLayout>
   );
 }

package/src/components/ui/.simple-markdown-renderer.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 9a47236bd9fd4f90eece958d3708b946 -->
+A client-side React component that renders Markdown content with GFM support, syntax highlighting, raw HTML passthrough, and a layered XSS sanitization pipeline designed for safe rendering of LLM-generated output.
+
+## Key Components
+
+### Rehype Plugins
+
+- **`rehypeStripUnsafe()`** — Custom HAST sanitizer that runs after `rehype-raw`. Strips dangerous elements (`<script>`, `<style>`, `<object>`, etc.), removes `on*` event handler attributes, and blocks `javascript:` / `data:` URI schemes on all URL-bearing attributes including multi-candidate `srcset`.
+
+- **`srcsetHasUnsafeCandidate(srcset)`** — Helper that splits `srcset` attribute values by comma and validates each URL candidate individually to prevent injection via secondary candidates.
+
+- **`escapeUnknownHtmlT...` (truncated)** — Pre-pass that escapes unrecognized HTML-like tags in raw markdown text before `rehype-raw` processes them, preventing React warnings/errors from LLM-emitted pseudo-XML tags like `<ticket>` or `<their>`.
+
+### URL Transform
+
+- **`cardAwareUrlTransform(url, key)`** — Extends `react-markdown`'s default URL sanitizer to allow `card://` and `mention://` internal schemes on `href` attributes only (used by `remarkCardLinks` and `remarkMentionChips` plugins), while keeping all other dangerous schemes blocked.
+
+### Constants
+
+- **`SAFE_HTML_TAGS`** — Allowlist of permitted HTML tag names forwarded to React. Explicitly excludes `<video>` (handled by a separate pipeline component).
+- **`TAG_LIKE_REGEX`** — ReDoS-safe regex (CodeQL-hardened, bounded quantifiers) for matching HTML-like tags in markdown source.
+
+## Usage Example
+
+```typescript
+import { SimpleMarkdownRenderer } from './simple-markdown-renderer';
+
+// Basic rendering with safe LLM output
+<SimpleMarkdownRenderer content="## Hello\n\nThis is **markdown** with `code`." />
+
+// With authenticated image sources and link resolution
+<SimpleMarkdownRenderer
+  content={llmMarkdownOutput}
+  resolveLink={(href) => ({ url: href, label: href })}
+/>
+```
+
+## Security Model
+
+The sanitization runs in two layers:
+
+```mermaid
+graph TD
+    A[Raw Markdown] --> B[escapeUnknownHtmlTags pre-pass]
+    B --> C[remark-gfm / remark-breaks]
+    C --> D[rehype-raw]
+    D --> E[rehypeStripUnsafe HAST sanitizer]
+    E --> F[rehype-highlight]
+    F --> G[Safe React Output]
+```
+
+> **Source:** [`simple-markdown-renderer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/simple-markdown-renderer.tsx)

package/src/components/ui/__tests__/tab-navigation.test.tsx

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { render, fireEvent, screen } from '@testing-library/react'
+import { mockReplace, setMockSearchParams } from '../../../../vitest.setup'
+import { TabNavigation, type TabItem } from '../tab-navigation'
+
+beforeAll(() => {
+  // jsdom ships no ResizeObserver; the tab strip observes itself on mount to
+  // keep the edge fades and the underline in sync with its own width.
+  globalThis.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver
+})
+
+const TABS: TabItem[] = [
+  { id: 'general', label: 'General' },
+  { id: 'software', label: 'Software' },
+]
+
+/**
+ * Renders with `urlSync` and reports the tab id the BODY was last rendered with
+ * — the one thing a consumer actually observes, and the value the deferred
+ * render settles on once React has flushed.
+ */
+function renderNav(tabs: TabItem[]) {
+  let seen = '__never-rendered__'
+  const element = (next: TabItem[]) => (
+    <TabNavigation tabs={next} urlSync>
+      {(active) => {
+        seen = active
+        return null
+      }}
+    </TabNavigation>
+  )
+  const utils = render(element(tabs))
+  return {
+    get active() {
+      return seen
+    },
+    rerenderWith(next: TabItem[]) {
+      utils.rerender(element(next))
+    },
+  }
+}
+
+describe('TabNavigation with urlSync', () => {
+  describe('a tab list that arrives late', () => {
+    // The sync effect is guarded on the URL value changing, so that our own
+    // `router.replace` doesn't come back looking like someone else's edit. The
+    // guard must not also swallow the tabs themselves arriving — an empty list
+    // resolves to no active tab, and the URL never moves again to correct it.
+    it('applies the deep-linked tab once the tabs arrive', () => {
+      setMockSearchParams(new URLSearchParams('tab=software'))
+      const nav = renderNav([])
+      expect(nav.active).toBe('')
+
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('software')
+    })
+
+    it('falls back to the first tab once the tabs arrive', () => {
+      const nav = renderNav([])
+      expect(nav.active).toBe('')
+
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('general')
+    })
+
+    it('leaves a tab the user picked alone when the tabs array is merely re-created', () => {
+      const nav = renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+      expect(nav.active).toBe('software')
+
+      // Same ids, new array + new Set identity — what a consumer passing an
+      // inline literal produces on every one of its renders.
+      nav.rerenderWith([...TABS])
+      expect(nav.active).toBe('software')
+    })
+  })
+
+  describe('clicking a tab', () => {
+    // The regression this component was rewritten for: state moves on click,
+    // `router.replace` lands a tick or more later, and an effect comparing the
+    // state against the URL in between would read the tab just LEFT and push
+    // the tab back to it.
+    it('does not revert before the navigation lands', () => {
+      const nav = renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+
+      // The URL has deliberately NOT been updated here — this is the window in
+      // which the old effect fought its own click.
+      expect(nav.active).toBe('software')
+    })
+
+    it('writes the tab to the URL without scrolling to the top', () => {
+      renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+
+      expect(mockReplace).toHaveBeenCalledWith('/?tab=software', { scroll: false })
+    })
+
+    it('stays put when its own write finally lands', () => {
+      const nav = renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+
+      setMockSearchParams(new URLSearchParams('tab=software'))
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('software')
+    })
+
+    // Two clicks inside one navigation: the FIRST write lands while the second
+    // is still in flight. Arriving out of step like that, it is indistinguishable
+    // from an external change unless the component remembers what it wrote.
+    it('ignores an earlier write landing after a second click', () => {
+      const nav = renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+      fireEvent.click(screen.getByText('General'))
+      expect(nav.active).toBe('general')
+
+      setMockSearchParams(new URLSearchParams('tab=software'))
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('general')
+
+      setMockSearchParams(new URLSearchParams('tab=general'))
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('general')
+    })
+
+    it('keeps unrelated query params', () => {
+      setMockSearchParams(new URLSearchParams('page=2&tab=general'))
+      renderNav(TABS)
+      fireEvent.click(screen.getByText('Software'))
+
+      expect(mockReplace).toHaveBeenCalledWith('/?page=2&tab=software', { scroll: false })
+    })
+  })
+
+  describe('an external URL change', () => {
+    it('moves the tab (back/forward, or a link into a tab)', () => {
+      setMockSearchParams(new URLSearchParams('tab=general'))
+      const nav = renderNav(TABS)
+      expect(nav.active).toBe('general')
+
+      setMockSearchParams(new URLSearchParams('tab=software'))
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('software')
+    })
+
+    it('falls back when the URL names a tab that does not exist', () => {
+      setMockSearchParams(new URLSearchParams('tab=general'))
+      const nav = renderNav(TABS)
+
+      setMockSearchParams(new URLSearchParams('tab=nonsense'))
+      nav.rerenderWith(TABS)
+      expect(nav.active).toBe('general')
+    })
+  })
+})