@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

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

@@ -0,0 +1,58 @@
+<!-- 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.
+
+## 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 |
+
+## 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',
+  }), [])}
+>
+  <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 (silently skips when outside provider)
+const endpoints = useEndpointsRuntime()
+if (endpoints) poll(endpoints.announcementsUrl)
+
+// Required consumer (throws outside provider)
+const { contactUrl } = useRequiredEndpointsRuntime()
+await fetch(contactUrl, { method: 'POST', body })
+
+// Tests / Storybook
+<EndpointsRuntimeContext.Provider value={mockedEndpoints}>
+  <ComponentUnderTest />
+</EndpointsRuntimeContext.Provider>
+```
+
+> **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.

package/src/contexts/.index.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 16840d639c023ac4c1efa4df208dc4be -->
+Barrel export for runtime React contexts used by embeddable OSS-lib components, enforcing a client-only bundle boundary to prevent SSR crashes.
+
+## Key Components
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `EndpointsRuntimeContext` | `endpoints-runtime-context` | React context object for endpoints runtime |
+| `useEndpointsRuntime` | `endpoints-runtime-context` | Hook returning the current endpoints runtime (nullable) |
+| `useRequiredEndpointsRuntime` | `endpoints-runtime-context` | Hook returning the endpoints runtime, throwing if absent |
+| `EndpointsRuntime` | `endpoints-runtime-context` | TypeScript type for the endpoints runtime shape |
+| `ChatRuntimeContext` | `chat-runtime-context` | React context object for chat runtime |
+| `useChatRuntime` | `chat-runtime-context` | Hook returning the current chat runtime (nullable) |
+| `useRequiredChatRuntime` | `chat-runtime-context` | Hook returning the chat runtime, throwing if absent |
+| `ChatRuntime` | `chat-runtime-context` | TypeScript type for the chat runtime shape |
+| `useOuterOrDefault` | `use-outer-or-default` | Utility hook for resolving outer context or falling back to a default |
+
+## Usage Example
+
+```typescript
+import {
+  EndpointsRuntimeContext,
+  useRequiredEndpointsRuntime,
+  useChatRuntime,
+  type ChatRuntime,
+} from '@your-org/oss-lib/contexts'
+
+// Provide a runtime at the tree root
+function AppRoot() {
+  return (
+    <EndpointsRuntimeContext.Provider value={myEndpointsRuntime}>
+      <ChatPanel />
+    </EndpointsRuntimeContext.Provider>
+  )
+}
+
+// Consume in a child component (must be a Client Component)
+function ChatPanel() {
+  const endpoints = useRequiredEndpointsRuntime() // throws if missing
+  const chat: ChatRuntime | null = useChatRuntime() // null-safe
+  // ...
+}
+```
+
+## Bundle-Split Rules
+
+> **Never import from `src/contexts/`** inside server-bundled modules (`utils/index.ts` and its transitive exports). All contexts call `createContext()` at module top-level, which crashes SSR. See `utils/access-code-client.ts` vs `hooks/use-access-code-integration.ts` as the canonical split pattern.
+
+| Code type | Goes in |
+|-----------|---------|
+| Pure functions with runtime as args | `utils/` |
+| Hooks that read runtime via `useContext` | `hooks/` (with `'use client'`) |
+| Context objects / providers | `contexts/` (client bundle only) |

package/src/contexts/.use-outer-or-default.md

@@ -0,0 +1,36 @@
+<!-- source-hash: d7ee3e1b5c0c5cbc9cc3e58aa144f151 -->
+Resolves a React context value by preferring an outer provider's value when present, falling back to a memoized factory default when no outer provider exists.
+
+## Key Components
+
+### `useOuterOrDefault<T>(context, factory, deps)`
+
+A generic hook that enables "outer-override" provider patterns used across hub and embedder providers.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `context` | `Context<T \| null>` | The React context to read from |
+| `factory` | `() => T` | Produces the default value when no outer provider is mounted |
+| `deps` | `ReadonlyArray<unknown>` | Memoization dependencies for `factory` (defaults to `[]`) |
+
+**Returns:** The outer context value if available, otherwise the memoized factory result.
+
+## Usage Example
+
+```typescript
+// Stable default (factory runs once — safe for constant/module-scope values)
+const runtime = useOuterOrDefault(ChatRuntimeContext, () => createDefaultRuntime())
+
+// Reactive default (factory re-runs when callbacks change)
+const runtime = useOuterOrDefault(
+  ChatRuntimeContext,
+  () => createChatRuntime({ navigate, decideNewTab }),
+  [navigate, decideNewTab], // must be stable refs (e.g. from useCallback)
+)
+```
+
+## Key Behaviors
+
+- **Tree shape stability** — the same provider element renders at the same position regardless of whether an outer provider is mounted, preventing unnecessary consumer remounts.
+- **Reference stability** — returns the same object reference across renders to avoid breaking downstream `useMemo` consumers. With `deps: []` this is trivially guaranteed; with reactive deps, callers must stabilize deps via `useCallback`.
+- **Outer wins** — if an embedder mounts a matching provider above the hub provider, that outer value takes precedence unconditionally.

package/src/embed-shims/.index.md

@@ -0,0 +1,45 @@
+<!-- source-hash: a9946becafacc3106b896d97c9d39009 -->
+Barrel export file for the `embed-shims/` module, providing environment-aware shims for Next.js primitives (`Image`, `Link`, `dynamic`, and navigation hooks) that work in any host environment (Vite, CRA, esbuild) while allowing full Next.js optimization via opt-in registration.
+
+## Key Components
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `Image` / `registerImage` | `./next-image` | Next.js Image Optimization shim |
+| `Link` / `registerLink` | `./next-link` | Client-router prefetching shim |
+| `dynamic` / `registerDynamic` | `./next-dynamic` | Dynamic import shim |
+| `useRouter`, `usePathname`, `useSearchParams`, `useParams` | `./next-navigation` | Navigation hooks shim |
+| `redirect`, `permanentRedirect`, `notFound`, `RedirectType` | `./next-navigation` | Navigation utilities shim |
+| `registerNavigation` / `NavigationImpl` | `./next-navigation` | Navigation registration and type |
+
+## Usage Example
+
+**Default (non-Next host — Vite, CRA, esbuild):**
+
+```typescript
+import { Link, Image, dynamic, useRouter } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+
+// Works out of the box with plain HTML equivalents — no config needed
+```
+
+**Next.js host — register real implementations once at app init:**
+
+```typescript
+import { registerImage, registerLink, registerDynamic, registerNavigation } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+import NextImage from 'next/image'
+import NextLink from 'next/link'
+import * as NextNavigation from 'next/navigation'
+
+registerImage(NextImage)
+registerLink(NextLink)
+registerDynamic(/* next/dynamic */)
+registerNavigation(NextNavigation)
+// All lib components now delegate to real Next.js primitives
+```
+
+**Per-shim import:**
+
+```typescript
+import Link  from '@flamingo-stack/openframe-frontend-core/embed-shims/next-link'
+import Image from '@flamingo-stack/openframe-frontend-core/embed-shims/next-image'
+```

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

@@ -0,0 +1,43 @@
+<!-- source-hash: d56fe778d5cc9e99389a419b59c5dcc9 -->
+Environment-aware lazy loader shim that defaults to `React.lazy` for non-Next.js hosts (Vite, esbuild, CRA) while supporting opt-in delegation to the real `next/dynamic` in Next.js environments.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `dynamic` | Default export | Drop-in lazy loader; delegates to `React.lazy` or registered `next/dynamic` |
+| `registerDynamic` | Named export | One-time registration to swap in the real `next/dynamic` at app init |
+| `DynamicOptions` | Interface | Subset of `next/dynamic` options (`loading`, `ssr`, `suspense`) |
+| `DynamicLoader<P>` | Type | Loader function returning `{ default: ComponentType }` or bare component |
+
+## Usage Example
+
+**Non-Next.js host (Vite/CRA) — no setup required:**
+
+```typescript
+import dynamic from '@flamingo-stack/openframe-frontend-core/next-dynamic'
+
+// Callers must be wrapped in a <Suspense> boundary
+const HeavyWidget = dynamic(() => import('./HeavyWidget'))
+```
+
+**Next.js host — register once at app init:**
+
+```typescript
+// lib/embed-shim-registration.ts
+import nextDynamic from 'next/dynamic'
+import { registerDynamic } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+
+registerDynamic(nextDynamic)
+```
+
+**With options (Next.js only — ignored on React.lazy fallback):**
+
+```typescript
+const Chart = dynamic(() => import('./Chart'), {
+  ssr: false,
+  loading: ({ isLoading }) => isLoading ? <Spinner /> : null,
+})
+```
+
+> **Note:** `ssr` and `loading` options are silently ignored when running on the `React.lazy` fallback. Consumers relying on those options must call `registerDynamic` first. All call sites must have a `<Suspense>` boundary in the component tree.

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

@@ -0,0 +1,45 @@
+<!-- source-hash: 38660f97f3dee9cba42a817ae6b6490d -->
+Environment-aware `next/image` shim that renders a plain `<img>` by default, delegating to the real `next/image` component only when explicitly registered — allowing library components to work across Next.js, Vite, CRA, and esbuild hosts without aliasing.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Image` | `React.ForwardRefExoticComponent` | Default export; the shim component. Renders `<img>` or delegates to registered `next/image` |
+| `registerImage` | `(component: ComponentType) => void` | Registers the real `next/image` implementation; call once at app init in Next.js hosts |
+| `ImageProps` | `type` | Extended image props supporting both HTML `<img>` attributes and Next.js-specific props |
+
+### `ImageProps` Next.js-specific fields
+
+`fill`, `sizes`, `quality`, `priority`, `placeholder`, `blurDataURL`, `unoptimized`, `loader`, `onLoadingComplete`
+
+## Usage Example
+
+**Non-Next host (Vite/CRA)** — no setup required:
+
+```typescript
+import Image from './next-image'
+
+// Renders a plain <img> automatically
+<Image src="/hero.png" alt="Hero" width={800} height={400} />
+```
+
+**Next.js host** — register once at app init:
+
+```typescript
+// lib/embed-shim-registration.ts
+import NextImage from 'next/image'
+import { registerImage } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+
+registerImage(NextImage) // All shim instances now delegate to next/image
+```
+
+**`fill` mode fallback behavior:**
+
+```typescript
+// When unregistered, `fill` maps to absolute positioning via inline style
+<Image src="/bg.png" alt="Background" fill />
+// Renders: <img style="position:absolute; inset:0; width:100%; height:100%; object-fit:cover" />
+```
+
+> **Note:** Next.js-only props (`priority`, `placeholder`, `blurDataURL`, `loader`, etc.) are silently dropped on the plain `<img>` fallback path — no runtime errors in non-Next environments.

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

@@ -0,0 +1,59 @@
+<!-- source-hash: 0eb3ce12c588e5ff9c30c2f3550ce64f -->
+Environment-aware `next/link` shim that renders a plain `<a>` tag by default, enabling use in non-Next.js hosts (Vite, CRA, esbuild), while allowing full `next/link` functionality via opt-in registration.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Link` | `ForwardRefExoticComponent` | Default export — the shim component itself |
+| `registerLink` | `(component: ComponentType) => void` | Registers the real `next/link` at app init |
+| `LinkProps` | `type` | Extended anchor props including Next.js-specific options (`prefetch`, `replace`, `scroll`, `locale`, etc.) |
+
+## Behavior
+
+```mermaid
+graph TD
+    A["Link shim renders"] --> B{"impl registered?"}
+    B -- Yes --> C["Delegate to real next/link\n(all props intact)"]
+    B -- No --> D["Render plain anchor tag\n(Next-only props dropped)"]
+    D --> E["UrlObject href → pathname string"]
+```
+
+## Usage Example
+
+**Non-Next.js host (default fallback — no setup needed):**
+
+```typescript
+import Link from './next-link'
+
+// Renders a plain <a href="/about">
+<Link href="/about">About</Link>
+```
+
+**Next.js host — register once at app init:**
+
+```typescript
+// lib/embed-shim-registration.ts
+import NextLink from 'next/link'
+import { registerLink } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+
+registerLink(NextLink)
+```
+
+**After registration — full Next.js routing features work:**
+
+```typescript
+import Link from './next-link'
+
+// Delegates to real next/link with prefetch, replace, scroll, locale
+<Link href="/dashboard" prefetch replace scroll={false} locale="en">
+  Dashboard
+</Link>
+
+// UrlObject href also supported
+<Link href={{ pathname: '/user', query: { id: '42' } }}>
+  Profile
+</Link>
+```
+
+> **Note:** `registerLink` must be called exactly once before any shim renders. In the fallback path, Next.js-specific props (`prefetch`, `replace`, `scroll`, `shallow`, `locale`, etc.) are silently dropped to keep the plain `<a>` clean.

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

@@ -0,0 +1,59 @@
+<!-- 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.
+
+## 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 |
+|---|---|
+| `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 |
+
+## Usage Example
+
+```typescript
+// In a Next.js host — lib/embed-shim-registration.ts
+import {
+  useRouter, usePathname, useSearchParams,
+  useParams, redirect, permanentRedirect, notFound,
+} from 'next/navigation'
+import { registerNavigation } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+
+// Call ONCE at app init — partial registration is safe
+registerNavigation({
+  useRouter,
+  usePathname,
+  useSearchParams,
+  useParams,
+  redirect,
+  permanentRedirect,
+  notFound,
+})
+```
+
+```typescript
+// In a lib component — works in both Next.js and standalone embed
+import { usePathname, useSearchParams } from './next-navigation'
+
+export function ActiveRoute() {
+  const pathname = usePathname()
+  const params = useSearchParams()
+  return <span>{pathname}?{params.toString()}</span>
+}
+```
+
+> **Note:** The fallback stubs only react to `popstate` events. Programmatic `pushState`/`replaceState` calls will **not** trigger re-renders without a registered real router.

package/src/hooks/.index.md

@@ -1,43 +1,48 @@
-<!-- source-hash: 5571a4440f18dbeb10c86804976c24b1 -->
-This file serves as the main export barrel for all React hooks used throughout the application, providing a centralized access point for UI interactions, state management, API calls, and real-time messaging functionality.
+<!-- source-hash: 23bacbbf103fe8e3ffb15ca1d779391b -->
+Central barrel export file for the hooks package, re-exporting all custom React hooks organized by domain.
 
 ## Key Components
 
-### Core Hook Categories
-- **UI Hooks** - Interface and user interaction utilities
-- **Platform Hooks** - Platform-specific functionality and integrations
-- **Toast System** - Notification and alert management
-- **Contact Submission** - Form handling for user contact flows
-- **Quick Action Hints** - User guidance and tooltip system
-- **API Stubs** - Mock or development API interfaces
-
-### Specialized Features
-- **Image Authentication** - Secure image loading and batch processing hooks
-- **URL State Management** - Browser state synchronization utilities
-- **Product Releases API** - Hooks for fetching and managing product version data
-- **NATS Client** - Real-time messaging and event streaming integration
+| Export Module | Description |
+|---------------|-------------|
+| `./ui` | UI interaction hooks |
+| `./platform` | Platform-specific hooks |
+| `./use-toast` | Toast notification hook |
+| `./use-contact-submission` | Contact form submission hook |
+| `./use-quick-action-hint` | Quick action hint display 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 |
 
 ## Usage Example
 
 ```typescript
+// Import any hook directly from the hooks package root
 import {
   useToast,
-  useContactSubmission,
-  useAuthenticatedImage,
-  useProductReleases,
-  useNatsClient
-} from './hooks'
+  useCopyToClipboard,
+  useNatsClient,
+  useNearViewport,
+  useAccessCodeIntegration,
+} from '@flamingo/hooks'
 
 function MyComponent() {
-  const { showToast } = useToast()
-  const { submitContact, isLoading } = useContactSubmission()
-  const { imageUrl, isAuthenticated } = useAuthenticatedImage('/api/secure-image')
-  const { releases, refetch } = useProductReleases()
-  const { client, isConnected } = useNatsClient()
-
-  // Use hooks for various application features
-  return <div>...</div>
+  const { toast } = useToast()
+  const { copy } = useCopyToClipboard()
+  const nats = useNatsClient()
+  const ref = useNearViewport()
+
+  return <div ref={ref}>...</div>
 }
 ```
 
-This barrel export pattern enables clean imports and maintains a single source of truth for all hook dependencies across the application.
+## 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.

package/src/hooks/.use-access-code-integration.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 0cad99bc77f5a6b497a57ffae290c55d -->
+React hook that binds access-code endpoint URLs from `EndpointsRuntimeContext` to the pure `access-code-client` utilities, exposing loading-state-aware wrappers for validating and consuming access codes without requiring callers to manage endpoint plumbing.
+
+## Key Components
+
+### `useAccessCodeIntegration()`
+
+The sole export. Reads endpoints from `useRequiredEndpointsRuntime()` (throws if no provider is mounted) and returns:
+
+| Field | Type | Description |
+|---|---|---|
+| `validate` | `(email, code) => Promise` | Validates the code without consuming it |
+| `consume` | `(email, code) => Promise` | Consumes the code without re-validating |
+| `validateAndConsume` | `(email, code) => Promise` | One-step validate-then-consume |
+| `isValidating` | `boolean` | A validate call is in flight |
+| `isConsuming` | `boolean` | A consume call is in flight |
+| `isProcessing` | `boolean` | Convenience alias: `isValidating \|\| isConsuming` |
+
+> **Note:** The returned functions and object are **not memoized** — they are re-created each render. Wrap with `useCallback` / `useMemo` at the call site if stable identities are needed in effect dependency arrays.
+
+## Usage Example
+
+```typescript
+const { validate, consume, validateAndConsume, isProcessing } =
+  useAccessCodeIntegration();
+
+const handleRegistration = async (formData: RegistrationForm) => {
+  const result = await validate(formData.email, formData.accessCode);
+
+  if (!result.valid) {
+    setError(result.message);
+    return;
+  }
+
+  const registration = await registerUser(formData);
+
+  if (registration.success) {
+    await consume(formData.email, formData.accessCode);
+  }
+};
+
+// Or as a single atomic operation:
+const handleInviteFlow = async (email: string, code: string) => {
+  const result = await validateAndConsume(email, code);
+  if (!result.valid) setError(result.message);
+};
+```
+
+Use `isProcessing` to disable submit buttons or show spinners during any in-flight operation, and `isValidating` / `isConsuming` independently when the UI distinguishes between the two phases.

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

@@ -1,13 +1,29 @@
-<!-- source-hash: 7a5064abe11480f3e1148317ad4cc605 -->
-A React hook that manages contact form submissions with loading states, toast notifications, and automatic redirect handling.
+<!-- source-hash: 76fefb8d1dd3113ac55a32017a2a8fe1 -->
+React hook that manages contact form submission state, API communication, toast notifications, and post-submission routing for the `/api/contact` endpoint.
 
 ## Key Components
 
-- **`useContactSubmission`** - Main hook that provides contact form submission functionality
-- **`ContactSubmissionOptions`** - Configuration interface for customizing behavior (userId, redirect URL, success message, callback)
-- **`ContactFormData`** - Type definition for contact form fields (name, email, company size, referral source, help category, message)
-- **`submit`** - Async function that handles form submission to `/api/contact` endpoint
-- **State management** - Tracks `isSubmitting`, `isSuccess` states and handles automatic redirects
+### `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
+
+### `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.
+
+### `useContactSubmission(options)`
+The exported hook. Pulls `contactUrl` from `useRequiredEndpointsRuntime` (throws if no provider is mounted), then returns:
+
+| Return Value | 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 |
+| `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.
 
 ## Usage Example
 
@@ -16,33 +32,28 @@ import { useContactSubmission } from './use-contact-submission';
 
 function ContactForm() {
   const { submit, isSubmitting, isSuccess } = useContactSubmission({
-    userId: 'user-123',
+    userId: currentUser?.id,
     successRedirectUrl: '/thank-you',
-    successToastMessage: 'We will get back to you within 24 hours.',
-    onSuccess: () => console.log('Form submitted successfully!')
+    successToastMessage: 'Our team will respond within 24 hours.',
+    onSuccess: () => analytics.track('contact_submitted'),
   });
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    
-    const formData = {
-      name: 'John Doe',
-      email: 'john@example.com',
-      companySize: '1-10',
-      referralSource: 'Google',
-      helpCategory: 'Support',
-      message: 'Need help with implementation'
-    };
-
-    try {
-      await submit(formData);
-    } catch (error) {
-      // Handle error if needed
-    }
+    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',
+    });
   };
 
   return (
     <form onSubmit={handleSubmit}>
+      {/* form fields */}
       <button type="submit" disabled={isSubmitting}>
         {isSubmitting ? 'Sending...' : 'Send Message'}
       </button>
@@ -51,4 +62,4 @@ function ContactForm() {
 }
 ```
 
-The hook automatically handles success toast notifications, optional redirects after a 1.5-second delay, and follows the same pattern as `useWaitlistRegistration` for consistency across the application.
+> **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.