@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/contexts/.chat-runtime-context.md

@@ -1,42 +1,63 @@
-<!-- source-hash: 246e5605bed712d2ecbfd71d23933d41 -->
-Provides the React context and typed interface that supply runtime configuration to the Flamingo/OpenFrame chat panel, decoupling API endpoints, navigation behavior, and identity source from the host environment.
+<!-- source-hash: 8291e5c1b6ca756b6bd0c1207bec4218 -->
+Provides the React context for configuring the chat panel's API endpoints, navigation behavior, and identity settings across host and embedded deployments.
 
 ## Key Components
 
 ### `ChatRuntime` Interface
-The central config shape with three top-level concerns:
 
-| Field | Description |
-|---|---|
-| `endpoints` | All API URLs: streaming chat, agent approval, slash-commands, attachment upload/view, identity, and optional image proxy |
-| `navigation` | Mode (`'host'` or `'embed'`), external URL handler, in-app router callback, and new-tab decision logic |
-| `source` | Required string used for `localStorage` namespacing (`mingo-chat-<source>-v1`) |
+The core configuration shape with three top-level concerns:
 
-### `ChatRuntimeContext`
-Raw React context (`createContext<ChatRuntime | null>(null)`). Mount via `<ChatRuntimeContext.Provider value={...}>` at your tree root.
+- **`endpoints`** — All API URLs consumed by the chat panel:
+  - `chatStreamUrl` — POST streaming chat
+  - `approvalToolUrl` — POST agent tool approval/rejection
+  - `commandsUrl` — GET slash-command catalog
+  - `buildListUrl` — Entity-card list URL builder
+  - `attachmentUploadUrl` / `attachmentViewUrlPrefix` — File attachment support
+  - `identityUrl` — Session capability resolution
+  - Optional: `findTicketUrl`, `ticketActionUrl`, `listEngagementsUrl`, `docsSearchUrl`, `docsResolveLinkUrl`, `emptyStateUrl`, `aiAgentConfigUrl`, `imageProxyUrlPrefix`, `ogPlaceholderUrl`, `supabaseStorageOrigin`
 
-### `useChatRuntime()`
-Nullable consumer hook. Returns `null` when no provider is mounted — signals unconfigured runtime. Use for optional/graceful-degradation consumers.
+- **`navigation`** — Click-routing behavior:
+  - `mode: 'host' | 'embed'` — Host uses in-app router; embed forces new-tab
+  - `defaultContentOrigin` — Required for embed mode to absolutize relative URLs
+  - `navigate` — Optional in-app routing callback (host mode)
+  - `decideNewTab` / `openExternal` — Optional override hooks
 
-### `useRequiredChatRuntime()`
-Strict consumer hook used inside chat internals. Throws a descriptive error if called outside a provider. Use this inside the chat panel itself.
+- **`composeContentUrl`** (`ComposeContentUrl`) — Optional platform-aware content href composer; falls back to relative paths when unset
+
+### Context Exports
+
+- `ChatRuntimeContext` — The React context object
+- `useChatRuntime()` — Hook to consume the context within the chat tree
 
 ## Usage Example
 
 ```typescript
-// Host (hub) — already handled by <HubRuntimeProvider>
-// Embedded app — wire your own provider:
+// Host mode (e.g. hub.openframe.ai)
+const runtime = React.useMemo<ChatRuntime>(() => ({
+  endpoints: {
+    chatStreamUrl: '/api/docs/chat',
+    approvalToolUrl: '/api/chat/agent/confirm-tool',
+    commandsUrl: '/api/docs/commands',
+    buildListUrl: (type, ids) => `/api/list/${type}?ids=${ids.join(',')}`,
+    attachmentUploadUrl: '/api/storage/upload/chat-attachments',
+    attachmentViewUrlPrefix: '/api/storage/view/chat-attachments/',
+    identityUrl: '/api/chat/identity',
+  },
+  navigation: {
+    mode: 'host',
+    navigate: ({ href }) => { router.push(href); return true },
+  },
+}), [router])
 
-const runtime = useMemo<ChatRuntime>(() => ({
-  source: 'my-embedded-app',
+// Embedded app (e.g. user1.openframe.ai)
+const embeddedRuntime = React.useMemo<ChatRuntime>(() => ({
   endpoints: {
-    chatStreamUrl: 'https://hub.openframe.ai/api/docs/chat',
-    approvalToolUrl: 'https://hub.openframe.ai/api/chat/agent/confirm-tool',
-    commandsUrl: 'https://hub.openframe.ai/api/docs/commands',
+    chatStreamUrl: '/api/mingo-guide/docs/chat',
+    // ...other proxied paths
     buildListUrl: (type, ids) => null,
-    attachmentUploadUrl: 'https://hub.openframe.ai/api/storage/upload',
-    attachmentViewUrlPrefix: 'https://hub.openframe.ai/api/storage/view/chat-attachments/',
-    identityUrl: 'https://hub.openframe.ai/api/chat/identity',
+    attachmentUploadUrl: '/api/mingo-guide/storage/upload',
+    attachmentViewUrlPrefix: 'https://hub.openframe.ai/api/storage/view/',
+    identityUrl: '/api/mingo-guide/chat/identity',
   },
   navigation: {
     mode: 'embed',
@@ -45,10 +66,18 @@ const runtime = useMemo<ChatRuntime>(() => ({
 }), [])
 
 return (
-  <ChatRuntimeContext.Provider value={runtime}>
+  <ChatRuntimeContext.Provider value={embeddedRuntime}>
     <ChatPanel />
   </ChatRuntimeContext.Provider>
 )
+
+// Inside chat components
+const runtime = useChatRuntime()
+const { chatStreamUrl } = runtime.endpoints
 ```
 
-> **Memoization is required.** Passing a new object reference on every render invalidates downstream `useMemo` consumers across the entire chat tree (slash-commands, nav links, stream factory). Always stabilize with `useMemo` and stable deps.
+> **Performance note:** Always memoize the value passed to `<ChatRuntimeContext.Provider>`. Inline object literals recreated on each render will invalidate downstream `useMemo` consumers across the entire chat tree.
+
+## Source
+
+[`chat-runtime-context.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-runtime-context.tsx)

package/src/contexts/.endpoints-runtime-context.md

@@ -1,58 +1,54 @@
-<!-- source-hash: 9d75df8f934797fae402329b05b9e8c2 -->
-Provides a React context for sharing API endpoint URLs across the component tree, enabling host applications (including reverse-proxy deployments) to override canonical paths consumed by `oss-lib` components.
+<!-- source-hash: 91729e745dc7597ae611c9a11fcb6839 -->
+Provides a React context for sharing API endpoint URL literals across OSS-lib components, enabling host applications to override paths (e.g., when running behind a reverse proxy).
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `EndpointsRuntime` | `interface` | Shape of the runtime value: `announcementsUrl`, `accessCode.validateUrl`, `accessCode.consumeUrl`, `contactUrl` |
-| `EndpointsRuntimeContext` | `Context<EndpointsRuntime \| null>` | Raw React context — use directly only when mounting a `Provider` |
-| `useEndpointsRuntime()` | hook | Returns `null` when no provider is mounted; safe for optional consumers |
-| `useRequiredEndpointsRuntime()` | hook | Throws a descriptive error when no provider is mounted; use for form submissions and code validation |
+### `EndpointsRuntime` Interface
+Defines the shape of the endpoint configuration:
+
+| Field | Type | Description |
+|---|---|---|
+| `announcementsUrl` | `string` | GET active announcement (used by `<AnnouncementBar>`) |
+| `accessCode.validateUrl` | `string` | POST validate access code |
+| `accessCode.consumeUrl` | `string` | POST redeem access code after registration |
+| `contactUrl` | `string` | POST contact-form submission |
+
+### `EndpointsRuntimeContext`
+A React context initialized to `null`. Mount `<EndpointsRuntimeContext.Provider value={...}>` at your application root with the appropriate endpoint paths.
+
+### `useEndpointsRuntime()`
+Optional hook — returns `null` when no provider is mounted. Use for components that should silently no-op when outside the provider tree (e.g., announcement polling).
+
+### `useRequiredEndpointsRuntime()`
+Strict hook — throws a descriptive error when no provider is mounted. Use for components that cannot function without endpoints (form submission, code validation).
 
 ## Usage Example
 
 ```typescript
-// Hub root — canonical paths
-<EndpointsRuntimeContext.Provider
-  value={React.useMemo(() => ({
-    announcementsUrl: '/api/announcements/active',
-    accessCode: {
-      validateUrl: '/api/access-codes/validate',
-      consumeUrl:  '/api/access-codes/consume',
-    },
-    contactUrl: '/api/contact',
-  }), [])}
->
+// Mounting the provider (e.g., in your root layout)
+const endpoints: EndpointsRuntime = React.useMemo(() => ({
+  announcementsUrl: '/api/announcements/active',
+  accessCode: {
+    validateUrl: '/api/access-codes/validate',
+    consumeUrl: '/api/access-codes/consume',
+  },
+  contactUrl: '/api/contact',
+}), [])
+
+<EndpointsRuntimeContext.Provider value={endpoints}>
   <App />
 </EndpointsRuntimeContext.Provider>
 
-// Embedded app — proxied paths (e.g. user1.openframe.ai)
-<EndpointsRuntimeContext.Provider
-  value={React.useMemo(() => ({
-    announcementsUrl: '/api/mingo-guide/announcements/active',
-    accessCode: {
-      validateUrl: '/api/mingo-guide/access-codes/validate',
-      consumeUrl:  '/api/mingo-guide/access-codes/consume',
-    },
-    contactUrl: '/api/mingo-guide/contact',
-  }), [])}
->
-  <EmbeddedApp />
-</EndpointsRuntimeContext.Provider>
+// Optional consumer
+const endpoints = useEndpointsRuntime() // null if no provider
+if (endpoints) fetchAnnouncement(endpoints.announcementsUrl)
 
-// Optional consumer (silently skips when outside provider)
-const endpoints = useEndpointsRuntime()
-if (endpoints) poll(endpoints.announcementsUrl)
+// Strict consumer
+const { contactUrl } = useRequiredEndpointsRuntime() // throws if no provider
+```
 
-// Required consumer (throws outside provider)
-const { contactUrl } = useRequiredEndpointsRuntime()
-await fetch(contactUrl, { method: 'POST', body })
+> **Embedders:** Always memoize the value passed to the provider. Reference changes invalidate downstream effect dependencies and cause unnecessary re-fetches.
 
-// Tests / Storybook
-<EndpointsRuntimeContext.Provider value={mockedEndpoints}>
-  <ComponentUnderTest />
-</EndpointsRuntimeContext.Provider>
-```
+## Source
 
-> **Embedders:** always `useMemo` the value object passed to the provider. A new object reference on every render invalidates downstream `useEffect` dependency arrays and triggers unnecessary re-fetches.
+[`endpoints-runtime-context.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/endpoints-runtime-context.tsx)

package/src/embed-shims/.next-navigation.md

@@ -1,39 +1,38 @@
-<!-- source-hash: 6464e6b8e81567378d067bf37a01cd1c -->
-Environment-aware shim for `next/navigation` app-router hooks. Provides lightweight `window.location`-backed stubs by default, with an opt-in registration mechanism for full Next.js router integration in host applications.
+<!-- source-hash: d193779b512ad2acfd37fa2c977da11e -->
+Environment-aware shim for `next/navigation` app-router hooks. Provides lightweight `window.location`/History API fallbacks so library components work outside a Next.js host, with opt-in delegation to real `next/navigation` exports via `registerNavigation`.
 
 ## Key Components
 
-### `registerNavigation(nav)`
-Merges real `next/navigation` exports into the internal registry. Call once at app init in a Next.js host to enable full client-router integration.
-
-### `NavigationImpl` (interface)
-Describes the full set of registerable hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`, `redirect`, `permanentRedirect`, `notFound`.
-
-### Exported Hooks & Utilities
-
-| Export | Stub Behavior |
+| Export | Description |
 |---|---|
-| `useRouter()` | `push`/`replace` → `window.location`; `back`/`forward` → `history`; `refresh` → `reload` |
-| `usePathname()` | Returns `window.location.pathname`, popstate-subscribed |
-| `useSearchParams()` | Returns `URLSearchParams` from `window.location.search`, popstate-subscribed |
-| `useParams<T>()` | Returns `{}` — parse params from `usePathname()` manually |
-| `redirect(url)` | `window.location.assign(url)` + throws |
-| `permanentRedirect(url)` | `window.location.replace(url)` + throws |
-| `notFound()` | Throws with shim message |
-| `RedirectType` | Mirrors Next's enum (`push` / `replace`) |
-| `ServerInsertedHTMLContext` | `null` stub — importable, non-functional |
+| `registerNavigation(nav)` | Merges real `next/navigation` exports into the registry. Call once at app init in a Next.js host. |
+| `useRouter()` | Returns a router stub; fallback uses `pushState`/`replaceState` + synthetic `popstate` for SPA navigation without page reloads. Cross-origin and malformed hrefs fall back to `window.location`. |
+| `usePathname()` | Returns `window.location.pathname`, subscribed to `popstate`. |
+| `useSearchParams()` | Returns a `URLSearchParams` view of `window.location.search`, subscribed to `popstate`. |
+| `useParams()` | Returns `{}` — embedders needing dynamic params should parse from `usePathname()`. |
+| `redirect()` / `permanentRedirect()` | Best-effort via `window.location.assign` / `.replace`. |
+| `notFound()` | Throws an error in non-Next environments. |
+| `RedirectType` | Mirrors Next's `RedirectType` enum (`push` / `replace`). |
+| `ServerInsertedHTMLContext` | Stub (`null`) so consumers can import without crashing. |
+| `NavigationImpl` | Interface describing the full registration surface; all fields are optional. |
 
 ## Usage Example
 
+**In a Next.js host — register once at app init:**
+
 ```typescript
-// In a Next.js host — lib/embed-shim-registration.ts
+// lib/embed-shim-registration.ts
 import {
-  useRouter, usePathname, useSearchParams,
-  useParams, redirect, permanentRedirect, notFound,
+  useRouter,
+  usePathname,
+  useSearchParams,
+  useParams,
+  redirect,
+  permanentRedirect,
+  notFound,
 } from 'next/navigation'
-import { registerNavigation } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+import { registerNavigation } from '@flamingo-stack/openframe-oss-lib/embed-shims'
 
-// Call ONCE at app init — partial registration is safe
 registerNavigation({
   useRouter,
   usePathname,
@@ -45,15 +44,23 @@ registerNavigation({
 })
 ```
 
+**In a standalone/embed environment — no setup required:**
+
 ```typescript
-// In a lib component — works in both Next.js and standalone embed
-import { usePathname, useSearchParams } from './next-navigation'
+// Works out of the box using History API fallbacks
+import { useRouter, useSearchParams } from '@flamingo-stack/openframe-oss-lib/next-navigation'
 
-export function ActiveRoute() {
-  const pathname = usePathname()
+function MyComponent() {
+  const router = useRouter()
   const params = useSearchParams()
-  return <span>{pathname}?{params.toString()}</span>
+
+  // SPA navigation — no document reload, popstate fires, subscribers re-render
+  return <button onClick={() => router.replace('?page=2')}>Next</button>
 }
 ```
 
-> **Note:** The fallback stubs only react to `popstate` events. Programmatic `pushState`/`replaceState` calls will **not** trigger re-renders without a registered real router.
+> **Note:** The fallback `usePathname` / `useSearchParams` hooks react to `popstate` events. Programmatic `pushState`/`replaceState` calls outside this shim will NOT trigger re-renders — register a real router or use the shim's own `useRouter` for mutations.
+
+## Source
+
+[`next-navigation.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/next-navigation.tsx)

package/src/hooks/.api-hooks.md

@@ -1,36 +1,43 @@
-<!-- source-hash: 6a72fca68f38313717239664519205f9 -->
-This file provides stub React hooks for API data fetching, offering consistent interfaces for loading states and error handling across different data types without actual API implementation.
+<!-- source-hash: ecdb4d3c79e0accd705583d0d62187db -->
+Stub React hooks providing placeholder API data-fetching interfaces for categories, vendors, and subcategory counts — returning empty state without making actual network requests.
 
 ## Key Components
 
-- **`useCategories()`** - Hook for fetching and managing category data with loading/error states
-- **`useVendors()`** - Hook for fetching and managing vendor data with loading/error states  
-- **`useSubcategoryCountByCategory()`** - Hook that returns empty subcategory count data
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useCategories` | `{ categories, loading, error }` | Fetches category list |
+| `useVendors` | `{ vendors, loading, error }` | Fetches vendor list |
+| `useSubcategoryCountByCategory` | `{ data, loading }` | Returns subcategory counts keyed by category |
 
 ## Usage Example
 
 ```typescript
-import { useCategories, useVendors } from './api-hooks';
+import {
+  useCategories,
+  useVendors,
+  useSubcategoryCountByCategory,
+} from './api-hooks';
 
-function MyComponent() {
-  const { categories, loading: categoriesLoading, error: categoriesError } = useCategories();
-  const { vendors, loading: vendorsLoading, error: vendorsError } = useVendors();
+function CatalogView() {
+  const { categories, loading, error } = useCategories();
+  const { vendors } = useVendors();
+  const { data: subcategoryCounts } = useSubcategoryCountByCategory();
 
-  if (categoriesLoading || vendorsLoading) {
-    return <div>Loading...</div>;
-  }
-
-  if (categoriesError || vendorsError) {
-    return <div>Error loading data</div>;
-  }
+  if (loading) return <span>Loading...</span>;
+  if (error) return <span>Error loading data</span>;
 
   return (
-    <div>
-      <h2>Categories: {categories.length}</h2>
-      <h2>Vendors: {vendors.length}</h2>
-    </div>
+    <ul>
+      {categories.map((cat) => (
+        <li key={cat.id}>{cat.name}</li>
+      ))}
+    </ul>
   );
 }
 ```
 
-These hooks currently return empty arrays and default states, serving as placeholders for future API integration while maintaining the expected interface for components that consume them.
+> **Note:** These are stub implementations — all hooks return empty/static state and no network calls are made. They are intended as placeholders until real API endpoints are wired in.
+
+## Source
+
+[`api-hooks.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/api-hooks.ts)

package/src/hooks/.index.md

@@ -1,47 +1,52 @@
-<!-- source-hash: 23bacbbf103fe8e3ffb15ca1d779391b -->
-Central barrel export file for the hooks package, re-exporting all custom React hooks organized by domain.
+<!-- source-hash: 2e6175823c7681e92d95bc1e1551a854 -->
+Central barrel export file for the hooks package, re-exporting all hook modules from a single entry point.
 
 ## Key Components
 
-| Export Module | Description |
-|---------------|-------------|
-| `./ui` | UI interaction hooks |
-| `./platform` | Platform-specific hooks |
-| `./use-toast` | Toast notification hook |
-| `./use-contact-submission` | Contact form submission hook |
-| `./use-copy-to-clipboard` | Clipboard write hook |
-| `./use-batch-images` | Authenticated batch image loading |
-| `./use-authenticated-image` | Single authenticated image hook |
-| `./state` | URL state management hooks |
-| `./nats/use-nats-client` | NATS messaging client hook |
-| `./use-near-viewport` | Shared IntersectionObserver lazy-mount primitive |
-| `./use-access-code-integration` | Access code context integration (client-only) |
-| `./use-og-placeholder` | OG placeholder URL builder hook |
+| Export Group | Module | Description |
+|---|---|---|
+| UI/Platform | `./ui`, `./platform` | Core UI and platform-specific hooks |
+| Toast | `./use-toast` | Toast notification hook |
+| Contact | `./use-contact-submission` | Contact form submission hook |
+| Clipboard | `./use-copy-to-clipboard` | Clipboard interaction hook |
+| Image Auth | `./use-batch-images`, `./use-authenticated-image`, `./use-authed-image-src` | Authenticated image loading hooks |
+| URL State | `./state` | URL-based state management hooks |
+| NATS | `./nats/use-nats-client` | NATS messaging client hook |
+| Viewport | `./use-near-viewport` | Shared IntersectionObserver lazy-mount primitive |
+| Access Code | `./use-access-code-integration` | Access code context integration |
+| OG Placeholder | `./use-og-placeholder-url` | Endpoint-driven OG placeholder URL hook |
+| Scroll | `./use-scroll-to-hash` | Deep-link scroll-to-hash after data load |
+| Bot Protection | `./use-humanity-signals` | Honeypot + submit-timing bot protection primitive |
 
 ## Usage Example
 
 ```typescript
-// Import any hook directly from the hooks package root
+// Import any hook directly from the package root
 import {
   useToast,
   useCopyToClipboard,
+  useAuthenticatedImage,
   useNatsClient,
   useNearViewport,
-  useAccessCodeIntegration,
-} from '@flamingo/hooks'
+  useScrollToHash,
+  useHumanitySignals,
+} from '@openframe/hooks'
 
 function MyComponent() {
   const { toast } = useToast()
   const { copy } = useCopyToClipboard()
-  const nats = useNatsClient()
-  const ref = useNearViewport()
+  const { ref: viewportRef } = useNearViewport()
 
-  return <div ref={ref}>...</div>
+  useScrollToHash({ prefix: 'ticket', isLoading: false })
+
+  return <div ref={viewportRef} />
 }
 ```
 
 ## Notes
 
-- `use-access-code-integration` is intentionally placed in `hooks/` rather than `utils/` to keep React context dependencies out of the server-safe utilities bundle.
-- `use-near-viewport` uses a shared `IntersectionObserver` singleton to minimize DOM overhead across lazy-mounted components.
-- Image hooks (`use-batch-images`, `use-authenticated-image`) handle auth token injection for protected media endpoints.
+- **`use-access-code-integration`** is intentionally kept in `hooks/` (not `utils/`) to avoid pulling `EndpointsRuntimeContext` into server-safe bundles.
+- **`use-humanity-signals`** pairs with the server-side decision function in `utils/humanity-signals` — the hook handles only the client primitive (honeypot ref + timing).
+- **`use-near-viewport`** uses a shared `IntersectionObserver` singleton for efficient lazy-mounting across many components.
+
+**Source:** [`hooks/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/hooks/index.ts)

package/src/hooks/.use-authed-image-src.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 15b1f2d897deb354fe984a6b0d805f9f -->
+Resolves authenticated image URLs for native shell environments (Capacitor, Tauri) where bearer token auth cannot be carried by native `<img>` requests. Acts as a pass-through on cookie-authenticated web clients.
+
+## Key Components
+
+### `useAuthedImageSrc(src?)` _(hook)_
+Primary hook that returns a resolved image source string. Returns `undefined` while a fetch is in-flight or after failure (allowing callers to render a placeholder/fallback), and returns the original `src` unchanged on cookie-auth web clients.
+
+### `clearAuthedImageCache()` _(export)_
+Clears all cached blob object-URLs and revokes them via `URL.revokeObjectURL`. Should be called at session end (logout/forced re-login) to prevent blob reuse across different identities. A generation counter fences any in-flight fetches at the time of the clear.
+
+### `fetchAsBlobUrl(src)` _(internal)_
+Deduplicates concurrent fetches for the same URL using a module-level `inFlight` map, then stores the resolved blob object-URL in `resolvedCache`. Fetch is delegated to `embedAuthedFetch` (bearer auth + 401-refresh-retry + cross-origin guard).
+
+### Module-level Cache
+- `resolvedCache`: `Map<string, string>` — session-lifetime blob URL cache keyed by full image URL
+- `inFlight`: `Map<string, Promise<void>>` — deduplicates concurrent fetches for the same URL
+- `cacheGeneration`: integer counter incremented on `clearAuthedImageCache` to fence stale fetch results
+
+## Usage Example
+
+```typescript
+import { useAuthedImageSrc, clearAuthedImageCache } from './use-authed-image-src'
+
+// In a component — renders placeholder while fetching or on error
+function Avatar({ imageUrl }: { imageUrl: string }) {
+  const src = useAuthedImageSrc(imageUrl)
+
+  if (!src) return <InitialsAvatar />
+  return <img src={src} alt="User avatar" />
+}
+
+// At logout
+function handleLogout() {
+  clearAuthedImageCache()
+  // ...rest of logout logic
+}
+```

package/src/hooks/.use-contact-submission.md

@@ -1,29 +1,27 @@
-<!-- source-hash: 76fefb8d1dd3113ac55a32017a2a8fe1 -->
-React hook that manages contact form submission state, API communication, toast notifications, and post-submission routing for the `/api/contact` endpoint.
+<!-- source-hash: af4536ad2bb59120a690271ba368f845 -->
+A React hook that manages contact form submission state, including loading/success tracking, toast notifications, and post-submission redirect logic.
 
 ## Key Components
 
 ### `ContactSubmissionOptions`
-Configuration interface for hook behavior:
-- `userId` — optional authenticated user identifier appended to the payload
-- `successRedirectUrl` — destination after successful submission (supports absolute URLs and internal paths)
-- `successToastMessage` — appends custom text to the default success toast
-- `onSuccess` — optional callback fired after successful submission
+Configuration interface for the hook:
+- `userId` – Optional authenticated user ID appended to the payload
+- `successRedirectUrl` – URL to navigate to after successful submission (1.5s delay)
+- `successToastMessage` – Custom suffix appended to the default success toast
+- `onSuccess` – Optional callback fired on successful submission
 
 ### `ContactFormData`
-Mirrors the `ContactBaseSchema` Zod contract on the server. Required fields are `name`, `email`, `helpCategory`, and `message`. Includes an index signature (`[key: string]: unknown`) so tracking metadata (`utm_*`, `rdt_cid`, `referrer_url`) and A/B variant fields pass through unchanged.
+Mirrors the `ContactBaseSchema` on the `POST /api/contact` endpoint. Core fields (`name`, `email`, `helpCategory`, `message`) are required; tracking fields (`rdt_cid`, `utm_*`, `referrer_url`) and future per-form fields pass through via the permissive `[key: string]: unknown` index signature.
 
 ### `useContactSubmission(options)`
-The exported hook. Pulls `contactUrl` from `useRequiredEndpointsRuntime` (throws if no provider is mounted), then returns:
+The exported hook. Resolves the endpoint URL via `useRequiredEndpointsRuntime` (throws if no provider is mounted), then exposes:
 
-| Return Value | Type | Description |
+| Return | Type | Description |
 |---|---|---|
-| `submit` | `(formData: ContactFormData) => Promise<void>` | Sends POST request; shows toast on success or error |
-| `isSubmitting` | `boolean` | True while the fetch is in-flight |
+| `submit` | `(formData) => Promise<void>` | Sends `POST` with form data; re-throws on error |
+| `isSubmitting` | `boolean` | True while request is in-flight |
 | `isSuccess` | `boolean` | True after a successful response |
-| `setIsSuccess` | `Dispatch<SetStateAction<boolean>>` | Allows caller to manually reset success state |
-
-Redirect logic waits 1500ms after `isSuccess` before navigating — using `window.location.href` for absolute URLs and `router.push` for relative paths.
+| `setIsSuccess` | `Dispatch` | Allows caller to reset success state |
 
 ## Usage Example
 
@@ -34,32 +32,33 @@ function ContactForm() {
   const { submit, isSubmitting, isSuccess } = useContactSubmission({
     userId: currentUser?.id,
     successRedirectUrl: '/thank-you',
-    successToastMessage: 'Our team will respond within 24 hours.',
+    successToastMessage: 'We will get back to you within 24 hours.',
     onSuccess: () => analytics.track('contact_submitted'),
   });
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    await submit({
-      name: 'Jane Smith',
-      email: 'jane@acme.com',
-      helpCategory: 'billing',
-      message: 'I have a question about my invoice.',
-      // Tracking fields forwarded transparently
-      utm_source: 'homepage',
-      rdt_cid: 'abc123',
-    });
+  const handleSubmit = async (formData: ContactFormData) => {
+    try {
+      await submit({
+        name: formData.name,
+        email: formData.email,
+        helpCategory: 'support',
+        message: formData.message,
+        // Tracking fields forwarded transparently
+        rdt_cid: getRedditClickId(),
+      });
+    } catch {
+      // Error toast is shown automatically; handle UI reset here if needed
+    }
   };
 
-  return (
-    <form onSubmit={handleSubmit}>
-      {/* form fields */}
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Sending...' : 'Send Message'}
-      </button>
-    </form>
-  );
+  return <button disabled={isSubmitting}>Submit</button>;
 }
 ```
 
-> **Note:** This hook requires `EndpointsRuntimeProvider` to be mounted in the component tree. The hub supplies the default contact endpoint; embedded apps provide a proxied path via the same context.
+## Notes
+
+- Redirect uses `window.location.href` for absolute URLs and `router.push` for relative paths
+- Guards against duplicate submissions via `isSubmitting` check at the top of `submit`
+- Endpoint URL is injected via context, making the hook compatible with both hub and embedded/proxied deployments
+
+**Source:** [`use-contact-submission.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-contact-submission.ts)