@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/.dialog.md

@@ -1,21 +1,24 @@
-<!-- source-hash: e422538f37348d581f42222f2cae8228 -->
-A comprehensive dialog component system built with React and TypeScript that provides a complete modal dialog implementation with overlay, content positioning, and accessibility features.
+<!-- source-hash: f32246d114b706570b821cefac3455d9 -->
+A custom client-side Dialog component system built without external libraries, providing a controlled modal overlay with backdrop blur, centered content panel, and composable sub-components.
 
 ## Key Components
 
-- **Dialog** - Main container component that manages open/closed state with backdrop
-- **DialogContent** - Centered modal content with built-in close button and click-outside handling
-- **DialogTrigger** - Button component for opening dialogs
-- **DialogClose** - Button component for closing dialogs
-- **DialogOverlay** - Backdrop overlay with blur effect
-- **DialogPortal** - Portal wrapper for rendering outside component tree
-- **DialogHeader/Footer** - Layout components for dialog structure
-- **DialogTitle/Description** - Text components with semantic styling
+| Component | Description |
+|-----------|-------------|
+| `Dialog` | Root container; renders a full-screen backdrop when `open` is `true`, closes on overlay click |
+| `DialogTrigger` | Button wrapper to programmatically open the dialog |
+| `DialogPortal` | Passthrough wrapper for portaling children (inline, no actual portal) |
+| `DialogOverlay` | Standalone backdrop overlay with blur effect |
+| `DialogClose` | Generic close button element |
+| `DialogContent` | Centered modal panel (`z-[10000]`) with built-in close (`X`) icon button and click-stop propagation |
+| `DialogHeader` | Flex column layout for title/description grouping |
+| `DialogFooter` | Responsive footer with reversed column on mobile, row on desktop |
+| `DialogTitle` | Styled `<h2>` for the modal heading |
+| `DialogDescription` | Styled `<p>` for supporting modal text |
 
 ## Usage Example
 
 ```typescript
-import { useState } from 'react'
 import {
   Dialog,
   DialogContent,
@@ -23,21 +26,20 @@ import {
   DialogTitle,
   DialogDescription,
   DialogFooter,
-  DialogClose,
-  DialogTrigger
-} from './dialog'
+  DialogTrigger,
+} from "./dialog"
 
-function MyComponent() {
-  const [isOpen, setIsOpen] = useState(false)
+export function ConfirmModal() {
+  const [open, setOpen] = React.useState(false)
 
   return (
     <>
-      <DialogTrigger onClick={() => setIsOpen(true)}>
-        Open Dialog
+      <DialogTrigger onClick={() => setOpen(true)}>
+        Open Modal
       </DialogTrigger>
-      
-      <Dialog open={isOpen} onOpenChange={setIsOpen}>
-        <DialogContent onCloseClick={() => setIsOpen(false)}>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent onCloseClick={() => setOpen(false)}>
           <DialogHeader>
             <DialogTitle>Confirm Action</DialogTitle>
             <DialogDescription>
@@ -45,10 +47,8 @@ function MyComponent() {
             </DialogDescription>
           </DialogHeader>
           <DialogFooter>
-            <DialogClose onClick={() => setIsOpen(false)}>
-              Cancel
-            </DialogClose>
-            <button>Confirm</button>
+            <button onClick={() => setOpen(false)}>Cancel</button>
+            <button onClick={() => setOpen(false)}>Confirm</button>
           </DialogFooter>
         </DialogContent>
       </Dialog>
@@ -57,4 +57,4 @@ function MyComponent() {
 }
 ```
 
-The component features a high z-index (9999-10000), click-outside-to-close behavior, and includes debug console logging for development.
+> **Note:** `DialogContent` uses `onCloseClick` (not the standard `onClose`) for the built-in `X` button handler. Backdrop clicks are handled by the root `Dialog` via `onOpenChange`.

package/src/components/.dynamic-skeleton.md

@@ -1,71 +1,68 @@
-<!-- source-hash: 10582d699bc264129f2c50203b2fd4ba -->
-A comprehensive skeleton loading component system that provides platform-aware, themed loading states with multiple animation types and pre-configured patterns for common UI elements.
+<!-- source-hash: 32b3dcc2ebc428837937e7dda53de3ce -->
+A theme-aware, platform-adaptive skeleton loading component that provides multiple animation styles, content-type variants, and pre-configured layout presets for common UI patterns.
 
 ## Key Components
 
-- **DynamicSkeleton** - Main skeleton component with customizable animations (pulse, shimmer, wave), variants (text, avatar, card, button, image), and platform-aware styling
-- **SkeletonPresets** - Pre-built skeleton configurations for common patterns (Card, Profile, Navigation, Table, VendorGrid, BlogPost)
-- **PlatformSkeletonContainer** - Conditional wrapper that shows skeleton during loading state
-- **ProgressiveSkeleton** - Multi-stage skeleton that becomes more detailed as loading progresses
+### `DynamicSkeleton`
+Core skeleton element supporting configurable animation, variant, size, and dimensions with built-in accessibility (`role="status"`, `aria-label`) and multi-line text support.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animation` | `pulse \| shimmer \| wave \| static` | `shimmer` | Skeleton animation style |
+| `variant` | `text \| avatar \| card \| button \| image \| custom` | `text` | Content type shape |
+| `size` | `sm \| md \| lg \| xl` | `md` | Dimension preset |
+| `width` / `height` | `string \| number` | — | Custom dimensions |
+| `lines` | `number` | `1` | Lines for text skeletons (last line renders at 75% width) |
+| `platformAware` | `boolean` | `true` | Applies platform-specific color mixing via CSS vars |
+| `includeAriaLabel` | `boolean` | `true` | Adds `aria-label="Loading content..."` |
+
+### `SkeletonPresets`
+Pre-built composite skeletons for common layouts:
+
+| Preset | Props | Description |
+|--------|-------|-------------|
+| `Card` | `showActions`, `showImage` | Card with header, body, and optional actions |
+| `Profile` | — | Avatar + name + bio lines |
+| `Navigation` | `items` | Repeated icon + label rows |
+| `Table` | `rows`, `columns` | Grid-based header and data rows |
+| `VendorGrid` | `items` | Responsive 3-column vendor cards |
+| `BlogPost` | — | Title, metadata, hero image, paragraphs |
+
+### `PlatformSkeletonContainer`
+Conditional wrapper that renders content when `isLoading` is `false`, or a named `SkeletonPresets` component when loading.
+
+### `ProgressiveSkeleton`
+Multi-stage skeleton that transitions through `pulse → shimmer → wave` animations and `text → card → custom` variants as `currentStage` increments.
 
 ## Usage Example
 
 ```typescript
-import { DynamicSkeleton, SkeletonPresets, PlatformSkeletonContainer } from './dynamic-skeleton';
+// Basic skeleton
+<DynamicSkeleton variant="avatar" size="lg" />
 
-// Basic skeleton with shimmer animation
-function LoadingText() {
-  return (
-    <DynamicSkeleton 
-      variant="text" 
-      animation="shimmer" 
-      lines={3} 
-      size="md" 
-    />
-  );
-}
+// Multi-line text skeleton
+<DynamicSkeleton variant="text" lines={3} size="md" animation="shimmer" />
 
-// Platform-aware card skeleton
-function LoadingCard() {
-  return (
-    <DynamicSkeleton
-      variant="card"
-      width="100%"
-      height="200px"
-      platformAware={true}
-      includeAriaLabel={true}
-    />
-  );
-}
+// Custom dimensions
+<DynamicSkeleton variant="image" width={400} height={200} />
 
-// Pre-configured vendor grid
-function LoadingVendors() {
-  return <SkeletonPresets.VendorGrid items={6} />;
-}
+// Preset: vendor grid
+<SkeletonPresets.VendorGrid items={9} />
 
 // Conditional loading wrapper
-function DataContainer({ isLoading, children }) {
-  return (
-    <PlatformSkeletonContainer
-      isLoading={isLoading}
-      skeletonType="Profile"
-    >
-      {children}
-    </PlatformSkeletonContainer>
-  );
-}
+<PlatformSkeletonContainer
+  isLoading={isLoading}
+  skeletonType="Profile"
+>
+  <UserProfile user={user} />
+</PlatformSkeletonContainer>
 
 // Progressive loading stages
-function ProgressiveLoader({ loadingStage }) {
-  return (
-    <ProgressiveSkeleton
-      currentStage={loadingStage}
-      stages={['basic', 'detailed', 'interactive']}
-      variant="card"
-      size="lg"
-    />
-  );
-}
-```
-
-The component integrates with the theme system to provide consistent styling across different platforms and supports accessibility features with proper ARIA labels and semantic HTML structure.
+<ProgressiveSkeleton
+  stages={['basic', 'detailed', 'interactive']}
+  currentStage={loadingStage}
+  size="lg"
+/>
+```

package/src/components/.empty-state.md

@@ -1,61 +1,52 @@
-<!-- source-hash: 752cfd7c91c54af0e2d9145803566dd6 -->
-A reusable React component that displays contextual empty states for different content types (vendors, posts, search results) with smart call-to-action buttons and customizable messaging.
+<!-- source-hash: 50c4ce7ece14f33f4a6cb6591ed66364 -->
+A reusable React client component that renders context-aware empty state UI for vendors, posts, search results, or generic scenarios — with smart CTA logic that adapts based on the current URL path.
 
 ## Key Components
 
-### EmptyStateProps Interface
-- **type**: Determines the empty state variant (`'vendors' | 'posts' | 'search' | 'generic'`)
-- **title/description**: Optional custom content overrides
-- **showBackButton**: Toggle for back navigation functionality
-- **showCTA**: Toggle for call-to-action button display
-- **ctaText/onCtaClick**: Custom CTA configuration
-- **ctaVariant**: Button styling variant (`'primary' | 'secondary'`)
+### `EmptyStateProps` Interface
 
-### EmptyState Component
-- **getDefaultContent()**: Returns type-specific icons, titles, and descriptions
-- **getSmartCTA()**: Generates contextual call-to-action buttons based on current route and type
-- **Smart Navigation**: Automatically handles URL parameter clearing and route-based actions
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'vendors' \| 'posts' \| 'search' \| 'generic'` | required | Determines default icon, title, and description |
+| `title` | `string` | — | Overrides default title |
+| `description` | `string` | — | Overrides default description |
+| `showBackButton` | `boolean` | `false` | Renders an optional back button |
+| `onGoBack` | `() => void` | — | Handler for the back button |
+| `backButtonText` | `string` | `"Go Back"` | Back button label |
+| `showCTA` | `boolean` | `true` | Toggles the smart CTA button |
+| `ctaText` | `string` | — | Overrides smart CTA label |
+| `onCtaClick` | `() => void` | — | Overrides smart CTA action |
+| `ctaVariant` | `'primary' \| 'secondary'` | `'primary'` | CTA button styling |
+
+### Internal Helpers
+
+- **`getDefaultContent()`** — Returns icon, title, and description based on `type`
+- **`getSmartCTA()`** — Derives CTA label and action from `type` + current pathname (e.g., resets filters on `/vendors` or `/blog`, navigates to `/vendors` from `/profile`)
 
 ## Usage Example
 
 ```typescript
-import { EmptyState } from './empty-state'
-
-// Basic vendor empty state with smart CTA
-function VendorList() {
-  return (
-    <EmptyState 
-      type="vendors"
-    />
-  )
-}
-
-// Custom search empty state with back button
-function SearchResults() {
-  return (
-    <EmptyState
-      type="search"
-      title="No matching results"
-      description="Try different keywords or check your spelling"
-      showBackButton={true}
-      onGoBack={() => router.back()}
-      ctaText="Clear Filters"
-      onCtaClick={() => clearSearchFilters()}
-    />
-  )
-}
-
-// Generic empty state with custom CTA
-function CustomContent() {
-  return (
-    <EmptyState
-      type="generic"
-      showCTA={true}
-      ctaVariant="secondary"
-      onCtaClick={() => handleCustomAction()}
-    />
-  )
-}
+// Basic usage
+<EmptyState type="vendors" />
+
+// Search with custom CTA
+<EmptyState
+  type="search"
+  title="No results"
+  description="Try different keywords."
+  ctaText="Clear Search"
+  onCtaClick={() => setQuery('')}
+  ctaVariant="secondary"
+/>
+
+// With back button, no CTA
+<EmptyState
+  type="posts"
+  showCTA={false}
+  showBackButton={true}
+  onGoBack={() => router.back()}
+  backButtonText="Return to Feed"
+/>
 ```
 
-The component automatically adapts its messaging and actions based on the current page context, providing relevant navigation options like "Reset Filters" on search pages or "Browse Vendors" on profile pages.
+> **Smart CTA behavior:** When no `ctaText`/`onCtaClick` is provided, the component inspects `window.location.pathname` to decide whether to reset URL filters or navigate to `/vendors` or `/blog`.

package/src/components/.faq-accordion.md

@@ -1,42 +1,48 @@
-<!-- source-hash: 5a3bed11c9b0686b28fc7626e02b503e -->
-A React FAQ accordion component with smooth animations and keyboard accessibility, featuring expandable/collapsible sections with height transitions.
+<!-- source-hash: 287c2bd98ac7a3ef2c0c3e9abfc07ed3 -->
+Accessible, animated FAQ accordion component that renders a list of question/answer pairs with smooth height transitions and keyboard navigation support.
 
 ## Key Components
 
-- **`FaqItem`** - Interface defining FAQ structure with id, question, and answer
-- **`FaqAccordion`** - Main accordion component with toggle functionality
-- **`useMeasuredHeight`** - Custom hook for measuring and animating content height
-- **`toggle`** - Function to handle expanding/collapsing individual FAQ items
+### Interfaces
+- **`FaqItem`** — Data shape for each FAQ entry (`id`, `question`, `answer`)
+- **`FaqAccordionProps`** — Component props accepting `items` array and optional `defaultOpenIds` for pre-expanded panels
+
+### Hooks
+- **`useMeasuredHeight(isOpen)`** — Internal hook that measures `scrollHeight` outside the render cycle to drive CSS `max-height` animations; returns `ref` and `maxHeight` string
+
+### Component
+- **`FaqAccordion`** — Main export; manages a `Set`-based open/close state, renders each item with animated expansion, `aria-expanded` attribute, and keyboard (`Enter`/`Space`) support
 
 ## Usage Example
 
 ```typescript
 import { FaqAccordion, FaqItem } from './faq-accordion'
 
-const faqData: FaqItem[] = [
+const faqs: FaqItem[] = [
   {
     id: 1,
-    question: "What is OpenFrame?",
-    answer: "OpenFrame is a decentralized platform for creative applications."
+    question: 'What is Flamingo?',
+    answer: 'Flamingo is an AI-powered MSP platform that replaces expensive proprietary software.',
   },
   {
     id: 2,
-    question: "How do I get started?",
-    answer: "You can start by installing the OpenFrame client and creating your first frame."
-  }
+    question: 'What is OpenFrame?',
+    answer: 'OpenFrame is a unified platform integrating multiple MSP tools into a single AI-driven interface.',
+  },
 ]
 
-export default function HelpPage() {
+export default function FaqPage() {
   return (
-    <div className="max-w-4xl mx-auto p-6">
-      <h1 className="text-3xl font-bold mb-8">Frequently Asked Questions</h1>
-      <FaqAccordion 
-        items={faqData}
-        defaultOpenIds={[1]} // First item open by default
-      />
-    </div>
+    <FaqAccordion
+      items={faqs}
+      defaultOpenIds={[1]} // First item open by default
+    />
   )
 }
 ```
 
-The component uses a `Set` for tracking open items, supports keyboard navigation (Enter/Space), and includes smooth height animations with opacity transitions. The `useMeasuredHeight` hook efficiently measures content height only when needed to enable smooth expand/collapse animations.
+## Notes
+
+- Multiple panels can be open simultaneously
+- Height animation uses a measured `scrollHeight` approach rather than fixed values, so dynamic content is handled correctly
+- Fully keyboard accessible via `role="button"`, `tabIndex`, and `onKeyDown` handlers

package/src/components/.filter-chip.md

@@ -1,39 +1,56 @@
-<!-- source-hash: 4174ee7f3ac49529233a0c26fda153e7 -->
-A unified React component for displaying interactive filter chips with consistent styling and multiple variants across the Flamingo platform. Supports selection states, removal functionality, and accessibility features with dark theme optimization.
+<!-- source-hash: fe89e2561aca7887d4e55361b739f66e -->
+Reusable pill-shaped filter chip component for displaying and managing active filters, category tags, and selection states across the UI.
 
 ## Key Components
 
-- **FilterChipProps** - Comprehensive interface supporting multiple variants (selected, unselected, category, subcategory, tag, info)
-- **FilterChip** - Main component with hover effects, focus management, and responsive sizing
-- **Variant System** - Six predefined styles with subtle border color differences for hierarchy
-- **Accessibility Features** - ARIA attributes, keyboard navigation, and screen reader support
+### `FilterChip`
+The sole export — a styled, accessible chip element built with Tailwind CSS classes via `cn`.
+
+### `FilterChipProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | — | Unique identifier |
+| `label` | `string` | — | Display text (truncated with tooltip) |
+| `variant` | `'selected' \| 'unselected' \| 'category' \| 'subcategory' \| 'tag' \| 'info'` | `'unselected'` | Visual style preset |
+| `size` | `'sm' \| 'md'` | `'md'` | Controls padding and text sizing |
+| `removable` | `boolean` | `false` | Shows an `×` remove button when `true` |
+| `onRemove` | `() => void` | — | Callback fired when remove button is clicked |
+| `onClick` | `() => void` | — | Makes the chip interactive as a toggle button |
+| `disabled` | `boolean` | `false` | Dims chip and disables all interactions |
+| `className` | `string` | — | Additional Tailwind classes |
+
+**Variants summary:**
+- `selected` / `category` / `subcategory` / `tag` — yellow (`#FFC008`) border at varying opacities for hierarchy
+- `unselected` — neutral dark border
+- `info` — static display only, hover/scale effects disabled
 
 ## Usage Example
 
 ```typescript
-import { FilterChip } from './filter-chip'
-
-// Basic usage with click handler
+// Basic selectable filter
 <FilterChip
-  id="tech-filter"
-  label="Technology"
+  id="status-active"
+  label="Active"
   variant="selected"
-  onClick={() => console.log('Filter clicked')}
+  onClick={() => toggleFilter('active')}
 />
 
-// Removable filter chip
+// Removable tag chip
 <FilterChip
-  id="category-chip"
-  label="Security"
-  variant="category"
+  id="tag-windows"
+  label="Windows"
+  variant="tag"
   removable
-  onRemove={() => removeFilter('security')}
+  onRemove={() => removeTag('windows')}
 />
 
-// Different variants for hierarchical filtering
-<FilterChip id="cat" label="Networking" variant="category" />
-<FilterChip id="sub" label="DNS" variant="subcategory" />
-<FilterChip id="tag" label="troubleshooting" variant="tag" size="sm" />
-```
-
-The component uses Flamingo's design system with `#FFC008` accent color and responsive breakpoints for optimal mobile/desktop experience. All variants maintain consistent backgrounds while varying border opacity for visual hierarchy.
+// Small category chip (disabled)
+<FilterChip
+  id="cat-networking"
+  label="Networking"
+  variant="category"
+  size="sm"
+  disabled
+/>
+```

package/src/components/.flamingo-logo.md

@@ -1,35 +1,32 @@
-<!-- source-hash: aa57675ccada693fa68db3d957dfd4ca -->
-A React SVG component that renders the Flamingo logo with customizable styling properties.
+<!-- source-hash: 36bcab31fa5bcda7078052eae1d8dda1 -->
+SVG React component that renders the Flamingo brand logo, accepting configurable size, color, and standard SVG props.
 
 ## Key Components
 
-- **FlamingoLogo**: Main functional component that renders an SVG flamingo logo
-- **FlamingoLogoProps**: TypeScript interface extending SVG props with custom properties:
-  - `className` - CSS classes for styling
-  - `size` - Logo dimensions (default: 120px)
-  - `color` - Fill color (default: CSS variable `--ods-flamingo-pink-base`)
+### `FlamingoLogo`
+A named export functional component with the following props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `number` | `120` | Width and height of the SVG in pixels |
+| `color` | `string` | `var(--ods-flamingo-pink-base)` | Fill color for the logo path |
+| `className` | `string` | `''` | Additional CSS class names |
+| `...props` | `React.SVGProps<SVGSVGElement>` | — | Any valid SVG element props |
 
 ## Usage Example
 
 ```typescript
 import { FlamingoLogo } from './flamingo-logo';
 
-// Basic usage with defaults
+// Default usage
 <FlamingoLogo />
 
 // Custom size and color
-<FlamingoLogo 
-  size={80} 
-  color="#ff6b9d" 
-  className="my-logo-class" 
-/>
-
-// With additional SVG props
-<FlamingoLogo 
-  size={150}
-  onClick={() => console.log('Logo clicked')}
-  aria-label="Flamingo Documentation Logo"
-/>
-```
-
-The component uses `React.useId()` for unique identifier generation and spreads additional props to the underlying SVG element. The logo maintains its aspect ratio and uses a fixed viewBox while allowing size customization through the `size` prop that controls both width and height.
+<FlamingoLogo size={48} color="#FFC008" />
+
+// With className for Tailwind/CSS overrides
+<FlamingoLogo className="opacity-80 hover:opacity-100" size={32} />
+
+// Override to white for dark backgrounds
+<FlamingoLogo color="#FFFFFF" size={64} />
+```

package/src/components/.footer-waitlist-button.md

@@ -1,38 +1,45 @@
-<!-- source-hash: f79f8bb1d9edf6587a6e5969375e5636 -->
-A Next.js client component that provides a context-aware waitlist button for use in footers, with smart navigation and form focusing capabilities.
+<!-- source-hash: 8e25a68fa3e51dd5cde8b484877f10f2 -->
+A footer button component that navigates users to the OpenFrame waitlist page, routing through the unified navigation system when available.
 
 ## Key Components
 
-**`FooterWaitlistButton`**: Main component that renders a button with OpenFrame logo and intelligent click behavior
-- **Props**: `FooterWaitlistButtonProps` interface with optional `className`
-- **Dependencies**: Next.js navigation hooks (`usePathname`, `useRouter`), custom UI components (`Button`, `OpenFrameLogo`)
+### `FooterWaitlistButtonProps`
+- `className?: string` — Optional CSS class for styling overrides.
+
+### `FooterWaitlistButton`
+A `Button` wrapper that handles navigation to `/waitlist#top` via a two-tier fallback strategy:
+
+1. **Primary:** `runtime.navigation.navigate` — the host's unified-nav hook (provided by `HubRuntimeProvider`), which handles cross-platform new-tab decisions, same-URL re-scroll, and embed-mode short-circuiting.
+2. **Fallback:** `router.push` via the embed-shim's `useRouter` — used when no `ChatRuntimeContext` is mounted (e.g., third-party embedders).
+
+Renders with the `OpenFrameLogo` icon as a left icon inside the button.
 
 ## Usage Example
 
 ```typescript
 import { FooterWaitlistButton } from './footer-waitlist-button';
 
-// Basic usage in footer
-function Footer() {
+// Basic usage inside a footer layout
+export function AppFooter() {
   return (
-    <footer className="bg-gray-900">
-      <div className="container mx-auto px-4 py-8">
-        <FooterWaitlistButton className="mt-4" />
-      </div>
+    <footer>
+      <FooterWaitlistButton className="mt-4 w-full" />
     </footer>
   );
 }
-
-// With custom styling
-function CustomFooter() {
-  return (
-    <FooterWaitlistButton className="bg-primary hover:bg-primary/90 text-white" />
-  );
-}
 ```
 
-The component implements smart navigation logic:
-- **On `/waitlist` page**: Smoothly scrolls to `#waitlist-form` element and focuses the email input after 400ms delay
-- **On other pages**: Navigates to `/waitlist#waitlist-form` URL with anchor
+> **Navigation note:** The `#top` anchor targets an explicit `<div id="top">` at the top of the waitlist page's `<main>` element, ensuring consistent scroll behavior across all browsers regardless of HTML5 magic-anchor handling.
+
+## Navigation Flow
 
-The button displays "Join Waitlist" text with the OpenFrame logo as a left icon, providing consistent branding across the application.
+```mermaid
+graph TD
+    A["FooterWaitlistButton clicked"] --> B{"runtime.navigation.navigate available?"}
+    B -->|Yes| C["Call runtime.navigation.navigate"]
+    C --> D{"Handled?"}
+    D -->|Yes| E["Done - unified nav handled"]
+    D -->|No| F["Fallback: router.push"]
+    B -->|No| F
+    F --> G["Navigate to /waitlist#top"]
+```