@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

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

@@ -0,0 +1,68 @@
+'use client'
+
+/**
+ * Endpoints runtime — sibling of ChatRuntime. Carries the API path
+ * literals consumed by oss-lib components/hooks/utils so a host
+ * application can override them (e.g. when running behind a reverse
+ * proxy as `user1.openframe.ai` → `/api/mingo-guide/*`).
+ *
+ * The hub mounts `<HubRuntimeProvider>` at root with the
+ * canonical hub paths; an embedded app mounts its own provider with
+ * remapped paths. The pattern mirrors ChatRuntimeContext exactly:
+ *
+ *   - `useEndpointsRuntime()` returns null when no provider is mounted.
+ *     For optional consumers that should gracefully no-op without one.
+ *   - `useRequiredEndpointsRuntime()` throws on missing provider — for
+ *     hooks/components that cannot function without endpoints.
+ *
+ * IMPORTANT for embedders: memoize the value passed to
+ * `<EndpointsRuntimeContext.Provider value={...}>` (e.g. React.useMemo).
+ * Reference changes invalidate downstream effect dependency arrays and
+ * trigger unnecessary re-fetches.
+ */
+
+import { createContext, useContext } from 'react'
+
+export interface EndpointsRuntime {
+  /** GET active announcement (used by `<AnnouncementBar>` polling). */
+  announcementsUrl: string
+  accessCode: {
+    /** POST validate access code. */
+    validateUrl: string
+    /** POST consume / redeem access code after registration. */
+    consumeUrl: string
+  }
+  /** POST contact-form submission. */
+  contactUrl: string
+}
+
+export const EndpointsRuntimeContext = createContext<EndpointsRuntime | null>(null)
+
+/**
+ * Optional read — returns null when no provider is mounted. Use for
+ * surfaces that should silently skip the fetch (e.g. announcement
+ * polling on a page rendered outside the provider tree).
+ */
+export function useEndpointsRuntime(): EndpointsRuntime | null {
+  return useContext(EndpointsRuntimeContext)
+}
+
+/**
+ * Strict variant — throws on missing provider. Use for consumers that
+ * cannot function without an endpoint (form submission, code
+ * validation). In tests/Storybook, wrap with the hub's
+ * `<HubRuntimeProvider>` or a stub
+ * `<EndpointsRuntimeContext.Provider value={mockedEndpoints}>`.
+ */
+export function useRequiredEndpointsRuntime(): EndpointsRuntime {
+  const v = useContext(EndpointsRuntimeContext)
+  if (!v) {
+    throw new Error(
+      '[endpoints-runtime] hook called outside an <EndpointsRuntimeContext.Provider>. ' +
+        'Hub: mount <HubRuntimeProvider> in your providers tree. ' +
+        'Embedded app: mount your own provider with proxied URLs at the tree root. ' +
+        'Tests/Storybook: wrap render() in <EndpointsRuntimeContext.Provider value={mocked}>.',
+    )
+  }
+  return v
+}

package/src/contexts/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Runtime contexts for embeddable oss-lib components.
+ *
+ * BUNDLE-SPLIT CONVENTION — read before adding new files here:
+ *   Every module in `src/contexts/` calls `createContext()` at module
+ *   top level. The tsup config builds this directory under the CLIENT
+ *   bundle (with `"use client"` banner). Importing anything from here
+ *   into a SERVER-bundled module (`utils/index.ts` and its `export *`
+ *   transitive closure) crashes SSR with
+ *   `createContext is not a function`.
+ *
+ *   Rule of thumb when adding a runtime-aware helper:
+ *     - Pure functions that take endpoints/runtime as args → `utils/`.
+ *     - React hooks that READ the runtime via useContext → `hooks/`
+ *       (with `'use client'` at the top of the file).
+ *     - Never re-export from `utils/*` anything that pulls
+ *       `src/contexts/*` transitively.
+ *
+ *   The split between `utils/access-code-client.ts` (pure) and
+ *   `hooks/use-access-code-integration.ts` (runtime-aware) is the
+ *   reference example.
+ */
+
+export {
+  EndpointsRuntimeContext,
+  useEndpointsRuntime,
+  useRequiredEndpointsRuntime,
+  type EndpointsRuntime,
+} from './endpoints-runtime-context'
+
+export {
+  ChatRuntimeContext,
+  useChatRuntime,
+  useRequiredChatRuntime,
+  type ChatRuntime,
+} from './chat-runtime-context'
+
+export { useOuterOrDefault } from './use-outer-or-default'

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

@@ -0,0 +1,42 @@
+'use client'
+
+/**
+ * Outer-forward provider helper — used by hub + embedder providers
+ * that supply default runtime values while allowing OUTER providers
+ * to override.
+ *
+ * When an embedder mounts an outer `<ChatRuntimeContext.Provider>`
+ * (or `<EndpointsRuntimeContext.Provider>`) ABOVE the hub provider,
+ * the outer value wins. When no outer is mounted, the hub provider
+ * supplies its `factory()` default. Tree shape stays constant —
+ * same provider element at the same position regardless of outer
+ * presence — so consumers below never remount when an embedder
+ * toggles their providers at runtime.
+ *
+ * `deps` controls factory memoization:
+ *   - Empty `[]` (default) → factory runs ONCE per mount; safe ONLY
+ *     when factory closes over module-scope/constant values.
+ *   - Non-empty → factory re-runs when deps change. Use when the
+ *     factory closes over callbacks or other reactive values
+ *     (e.g. hub's ChatRuntime which includes `navigate` +
+ *     `decideNewTab` callbacks that depend on router + docNav).
+ *
+ * Returning the SAME reference across renders is critical for
+ * downstream `useMemo` consumers. With empty deps, identity is
+ * trivially stable. With reactive deps, the caller must memoize
+ * the deps themselves (typically via `useCallback`).
+ */
+
+import { useContext, useMemo, type Context } from 'react'
+
+export function useOuterOrDefault<T>(
+  context: Context<T | null>,
+  factory: () => T,
+  deps: ReadonlyArray<unknown> = [],
+): T {
+  const outer = useContext(context)
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- deps are the contract;
+  // factory identity is intentionally ignored (caller controls re-creation via deps).
+  const fallback = useMemo(factory, deps)
+  return outer ?? fallback
+}

package/src/embed-shims/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Barrel for the `embed-shims/` shims.
+ *
+ * Each shim is environment-aware: by default it renders a plain HTML
+ * equivalent so non-Next hosts (Vite, CRA, esbuild) work out of the
+ * box. Next.js hosts opt into the REAL Next primitives by calling the
+ * `register*` functions ONCE at app init — see each shim's docblock
+ * for the host wiring snippet. After registration, every lib component
+ * that renders through these shims delegates to the real Next impl
+ * (Image Optimization, client-router prefetching, full app-router
+ * navigation, etc.) without further config.
+ *
+ * Lib internals import each shim directly via its relative path
+ * (`../embed-shims/next-link`). Hub and external consumers import
+ * through this barrel:
+ *
+ *   import { Link, Image, dynamic, useRouter, usePathname } from
+ *     '@flamingo-stack/openframe-frontend-core/embed-shims'
+ *
+ * Or per-shim:
+ *
+ *   import Link  from '@flamingo-stack/openframe-frontend-core/embed-shims/next-link'
+ *   import Image from '@flamingo-stack/openframe-frontend-core/embed-shims/next-image'
+ *
+ * Companion to the docblocks on each individual shim file.
+ */
+export { default as Image, registerImage } from './next-image'
+export { default as Link, registerLink } from './next-link'
+export { default as dynamic, registerDynamic } from './next-dynamic'
+export {
+  useRouter,
+  usePathname,
+  useSearchParams,
+  useParams,
+  redirect,
+  permanentRedirect,
+  notFound,
+  RedirectType,
+  ServerInsertedHTMLContext,
+  registerNavigation,
+  type NavigationImpl,
+} from './next-navigation'

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

@@ -0,0 +1,70 @@
+'use client'
+
+/**
+ * `next/dynamic` shim — environment-aware lazy loader.
+ *
+ * Defaults to `React.lazy` so non-Next hosts (Vite, CRA, esbuild) work
+ * out of the box. Callers MUST be wrapped in a `<Suspense>` boundary
+ * somewhere up the tree (Next.js's runtime provides one automatically;
+ * non-Next embedders provide their own).
+ *
+ * Next.js hosts can opt into the REAL `next/dynamic` (with SSR support,
+ * loading components, prefetch hints) by calling {@link registerDynamic}
+ * ONCE at app init:
+ *
+ *   // hub: lib/embed-shim-registration.ts
+ *   import nextDynamic from 'next/dynamic'
+ *   import { registerDynamic } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+ *   registerDynamic(nextDynamic)
+ *
+ * After registration, every lib call to this shim's default export
+ * delegates to `next/dynamic`. Without registration, `ssr` / `loading`
+ * options are ignored (React.lazy doesn't support them).
+ */
+import { lazy, type ComponentType, type ReactNode } from 'react'
+
+interface DynamicOptions {
+  loading?: (props: {
+    error?: Error | null
+    isLoading?: boolean
+    pastDelay?: boolean
+    retry?: () => void
+    timedOut?: boolean
+  }) => ReactNode | null
+  ssr?: boolean
+  suspense?: boolean
+}
+
+type DynamicLoader<P> = () => Promise<{ default: ComponentType<P> } | ComponentType<P>>
+
+/** Matches `next/dynamic`'s exported signature. */
+type DynamicFn = <P extends Record<string, any> = Record<string, never>>(
+  loader: DynamicLoader<P>,
+  options?: DynamicOptions,
+) => ComponentType<P>
+
+const fallback: DynamicFn = (loader, _options) => {
+  // React.lazy expects a loader returning { default }. Wrap loaders
+  // that return a bare component (legacy next/dynamic shape).
+  const wrapped = () =>
+    loader().then((mod: any) => ('default' in mod ? mod : { default: mod }))
+  return lazy(wrapped) as unknown as ComponentType<any>
+}
+
+let impl: DynamicFn = fallback
+
+/**
+ * Register the real `next/dynamic` so this shim delegates to it instead
+ * of `React.lazy`. Call ONCE at app init in a Next.js host. The function
+ * signature must match `next/dynamic`'s default export.
+ */
+export function registerDynamic(fn: DynamicFn): void {
+  impl = fn
+}
+
+export default function dynamic<P extends Record<string, any> = Record<string, never>>(
+  loader: DynamicLoader<P>,
+  options?: DynamicOptions,
+): ComponentType<P> {
+  return impl(loader, options)
+}

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

@@ -0,0 +1,114 @@
+/**
+ * `next/image` shim — environment-aware Image component.
+ *
+ * Defaults to a plain `<img>` so non-Next hosts (Vite, CRA, esbuild)
+ * work out of the box without aliasing tricks. Next.js hosts can opt
+ * into the REAL `next/image` (with Image Optimization) by calling
+ * {@link registerImage} ONCE at app init:
+ *
+ *   // hub: lib/embed-shim-registration.ts
+ *   import NextImage from 'next/image'
+ *   import { registerImage } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+ *   registerImage(NextImage)
+ *
+ * After registration, every lib component that renders this shim
+ * delegates to `NextImage` — full Image Optimization, blur placeholders,
+ * priority, etc. Without registration, the shim falls through to the
+ * plain `<img>` path that drops Next-specific props.
+ *
+ * Lib internals import this shim directly (relative path); hub-side
+ * code goes through the barrel (`@flamingo-stack/.../embed-shims`).
+ */
+'use client'
+import {
+  forwardRef,
+  type ComponentType,
+  type ImgHTMLAttributes,
+} from 'react'
+
+type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'placeholder'> & {
+  src?: string | { src: string }
+  alt?: string
+  width?: number | string
+  height?: number | string
+  fill?: boolean
+  sizes?: string
+  quality?: number
+  priority?: boolean
+  loading?: 'eager' | 'lazy'
+  placeholder?: 'blur' | 'empty' | `data:image/${string}`
+  blurDataURL?: string
+  unoptimized?: boolean
+  onLoadingComplete?: (img: HTMLImageElement) => void
+  loader?: unknown
+}
+
+let impl: ComponentType<any> | null = null
+
+/**
+ * Register the real `next/image` so this shim delegates to it instead
+ * of rendering a plain `<img>`. Call ONCE at app init in a Next.js host
+ * — subsequent calls overwrite the registration silently. Safe to skip
+ * entirely in non-Next environments.
+ */
+export function registerImage(component: ComponentType<any>): void {
+  impl = component
+}
+
+const Image = forwardRef<HTMLImageElement, ImageProps>(function NextImageShim(
+  props,
+  ref,
+) {
+  // Real impl path — registered by the host. Hand off untouched so
+  // every Next-specific prop (priority, placeholder, sizes, loader…)
+  // reaches the real component intact.
+  if (impl) {
+    const Real = impl
+    return <Real ref={ref} {...props} />
+  }
+
+  // Fallback path — plain <img>. Drops Next-only props and reduces
+  // `StaticImageData` src to a string.
+  const {
+    src,
+    alt,
+    width,
+    height,
+    fill,
+    sizes: _sizes,
+    quality: _quality,
+    priority: _priority,
+    placeholder: _placeholder,
+    blurDataURL: _blurDataURL,
+    unoptimized: _unoptimized,
+    onLoadingComplete,
+    loader: _loader,
+    style,
+    ...rest
+  } = props
+  const srcStr = typeof src === 'string' ? src : src?.src
+  const finalStyle = fill
+    ? {
+        position: 'absolute' as const,
+        inset: 0,
+        width: '100%',
+        height: '100%',
+        objectFit: 'cover' as const,
+        ...style,
+      }
+    : style
+  return (
+    <img
+      ref={ref}
+      src={srcStr}
+      alt={alt ?? ''}
+      width={fill ? undefined : width}
+      height={fill ? undefined : height}
+      style={finalStyle}
+      onLoad={onLoadingComplete ? (e) => onLoadingComplete(e.currentTarget) : undefined}
+      {...rest}
+    />
+  )
+})
+
+export default Image

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

@@ -0,0 +1,91 @@
+/**
+ * `next/link` shim — environment-aware Link component.
+ *
+ * Defaults to a plain `<a>` so non-Next hosts (Vite, CRA, esbuild)
+ * work out of the box. Next.js hosts can opt into the REAL `next/link`
+ * (with client-router prefetching) by calling {@link registerLink}
+ * ONCE at app init:
+ *
+ *   // hub: lib/embed-shim-registration.ts
+ *   import NextLink from 'next/link'
+ *   import { registerLink } from '@flamingo-stack/openframe-frontend-core/embed-shims'
+ *   registerLink(NextLink)
+ *
+ * After registration, every lib component that renders this shim
+ * delegates to `NextLink` — prefetch, replace, scroll, locale, etc.
+ * all work as expected. Without registration, the shim falls through
+ * to the plain `<a>` path that drops Next-specific props.
+ *
+ * Lib internals import this shim directly (relative path); hub-side
+ * code goes through the barrel (`@flamingo-stack/.../embed-shims`).
+ */
+'use client'
+import {
+  forwardRef,
+  type AnchorHTMLAttributes,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+
+type LinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
+  href?: string | { pathname?: string; query?: Record<string, string> }
+  prefetch?: boolean | null
+  replace?: boolean
+  scroll?: boolean
+  shallow?: boolean
+  passHref?: boolean
+  legacyBehavior?: boolean
+  locale?: string | false
+  children?: ReactNode
+}
+
+let impl: ComponentType<any> | null = null
+
+/**
+ * Register the real `next/link` so this shim delegates to it instead
+ * of rendering a plain `<a>`. Call ONCE at app init in a Next.js host.
+ */
+export function registerLink(component: ComponentType<any>): void {
+  impl = component
+}
+
+const Link = forwardRef<HTMLAnchorElement, LinkProps>(function NextLinkShim(
+  props,
+  ref,
+) {
+  // Real impl path — registered by the host. Hand off untouched so
+  // every Next-specific prop (prefetch, replace, scroll, locale…)
+  // reaches the real component intact.
+  if (impl) {
+    const Real = impl
+    return <Real ref={ref} {...props} />
+  }
+
+  // Fallback path — plain <a>. Drops Next-only props and reduces
+  // `UrlObject` href to its pathname.
+  const {
+    href,
+    children,
+    prefetch: _prefetch,
+    replace: _replace,
+    scroll: _scroll,
+    shallow: _shallow,
+    passHref: _passHref,
+    legacyBehavior: _legacyBehavior,
+    locale: _locale,
+    ...rest
+  } = props
+  const hrefStr =
+    typeof href === 'string'
+      ? href
+      : href?.pathname
+        ? href.pathname
+        : undefined
+  return (
+    <a ref={ref} href={hrefStr} {...rest}>
+      {children}
+    </a>
+  )
+})
+
+export default Link

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

@@ -0,0 +1,201 @@
+/**
+ * `next/navigation` shim — environment-aware app-router hooks.
+ *
+ * Defaults to lightweight stubs backed by `window.location` and
+ * `URLSearchParams` so lib components that read the URL work outside
+ * a Next.js router shell. Next.js hosts can opt into the REAL
+ * `next/navigation` exports (full client-router integration —
+ * `router.replace(href, { scroll: false })`, etc.) by calling
+ * {@link registerNavigation} ONCE at app init:
+ *
+ *   // hub: 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'
+ *   registerNavigation({
+ *     useRouter, usePathname, useSearchParams, useParams,
+ *     redirect, permanentRedirect, notFound,
+ *   })
+ *
+ * After registration, every exported hook in this file delegates to
+ * the real implementation. Without registration, the stubs run:
+ *
+ *   - `useRouter()` → push/replace use `window.location.assign/replace`;
+ *     back/forward use `history.back/forward`; refresh reloads; prefetch
+ *     is a no-op.
+ *   - `usePathname()` → returns `window.location.pathname` (popstate-
+ *     subscribed so back/forward re-renders).
+ *   - `useSearchParams()` → returns `URLSearchParams` view of
+ *     `window.location.search` (popstate-subscribed).
+ *   - `useParams()` → returns `{}` — embedders that need dynamic
+ *     params should parse them from `usePathname()` themselves.
+ *   - `notFound()` / `redirect()` / `permanentRedirect()` —
+ *     best-effort equivalents using `window.location`.
+ *
+ * The fallback path subscribes to `popstate` only. Programmatic
+ * `pushState`/`replaceState` does NOT fire popstate, so the fallback
+ * does not auto-re-render on programmatic navigation. Embedders that
+ * need that should register a real router or supply their own.
+ */
+'use client'
+import { useEffect, useState } from 'react'
+
+// --- Router shape — matches Next's AppRouterInstance surface enough to
+// --- satisfy hub callsites that pass options like `{ scroll: false }`.
+interface NavigateOptions {
+  scroll?: boolean
+}
+
+interface PrefetchOptions {
+  kind?: unknown
+}
+
+interface RouterStub {
+  push: (href: string, options?: NavigateOptions) => void
+  replace: (href: string, options?: NavigateOptions) => void
+  back: () => void
+  forward: () => void
+  refresh: () => void
+  prefetch: (href: string, options?: PrefetchOptions) => void
+}
+
+// --- Registration surface — partial so a host can register only the
+// --- hooks it needs (e.g. routes that don't use redirect()).
+export interface NavigationImpl {
+  useRouter: () => RouterStub
+  usePathname: () => string
+  useSearchParams: () => URLSearchParams
+  useParams: <T extends Record<string, string | string[]>>() => T
+  redirect: (url: string, type?: unknown) => never
+  permanentRedirect: (url: string, type?: unknown) => never
+  notFound: () => never
+}
+
+let impl: Partial<NavigationImpl> = {}
+
+/**
+ * Register real `next/navigation` exports. Merges with any prior
+ * registration so partial-overrides are safe. Call ONCE at app init
+ * in a Next.js host.
+ */
+export function registerNavigation(nav: Partial<NavigationImpl>): void {
+  impl = { ...impl, ...nav }
+}
+
+// --- Fallback impls ----------------------------------------------------
+
+const noopRouter: RouterStub = {
+  push: () => {},
+  replace: () => {},
+  back: () => {},
+  forward: () => {},
+  refresh: () => {},
+  prefetch: () => {},
+}
+
+function fallbackUseRouter(): RouterStub {
+  if (typeof window === 'undefined') return noopRouter
+  return {
+    push: (href: string) => window.location.assign(href),
+    replace: (href: string) => window.location.replace(href),
+    back: () => window.history.back(),
+    forward: () => window.history.forward(),
+    refresh: () => window.location.reload(),
+    prefetch: () => {},
+  }
+}
+
+function readLocation<T>(read: () => T, fallback: T): T {
+  return typeof window === 'undefined' ? fallback : read()
+}
+
+/** Subscribes to `popstate` only. pushState/replaceState do NOT fire
+ *  popstate by design — callers that mutate the URL programmatically
+ *  (and want their component to re-render in response) need a real
+ *  router. */
+function useLocationSubscription(): number {
+  const [tick, setTick] = useState(0)
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const onChange = () => setTick((t) => t + 1)
+    window.addEventListener('popstate', onChange)
+    return () => window.removeEventListener('popstate', onChange)
+  }, [])
+  return tick
+}
+
+function fallbackUsePathname(): string {
+  useLocationSubscription()
+  return readLocation(() => window.location.pathname, '/')
+}
+
+function fallbackUseSearchParams(): URLSearchParams {
+  useLocationSubscription()
+  return readLocation(
+    () => new URLSearchParams(window.location.search),
+    new URLSearchParams(),
+  )
+}
+
+function fallbackUseParams<T extends Record<string, string | string[]>>(): T {
+  return {} as T
+}
+
+function fallbackRedirect(url: string): never {
+  if (typeof window !== 'undefined') window.location.assign(url)
+  throw new Error(`[next-navigation shim] redirect(${url})`)
+}
+
+function fallbackPermanentRedirect(url: string): never {
+  if (typeof window !== 'undefined') window.location.replace(url)
+  throw new Error(`[next-navigation shim] permanentRedirect(${url})`)
+}
+
+function fallbackNotFound(): never {
+  throw new Error('[next-navigation shim] notFound()')
+}
+
+// --- Public surface — each export checks the registry and falls
+// --- through to the fallback. Hooks must remain hooks (no early-
+// --- return-before-hook) — the registry lookup is itself synchronous
+// --- and the registered impl is a hook in its own right.
+
+export function useRouter(): RouterStub {
+  return (impl.useRouter ?? fallbackUseRouter)()
+}
+
+export function usePathname(): string {
+  return (impl.usePathname ?? fallbackUsePathname)()
+}
+
+export function useSearchParams(): URLSearchParams {
+  return (impl.useSearchParams ?? fallbackUseSearchParams)()
+}
+
+export function useParams<T extends Record<string, string | string[]>>(): T {
+  return ((impl.useParams as (() => T) | undefined) ?? fallbackUseParams)()
+}
+
+export function redirect(url: string, type?: unknown): never {
+  return (impl.redirect ?? fallbackRedirect)(url, type)
+}
+
+export function permanentRedirect(url: string, type?: unknown): never {
+  return (impl.permanentRedirect ?? fallbackPermanentRedirect)(url, type)
+}
+
+export function notFound(): never {
+  return (impl.notFound ?? fallbackNotFound)()
+}
+
+/** Match Next's RedirectType enum surface for code that imports it. */
+export const RedirectType = {
+  push: 'push' as const,
+  replace: 'replace' as const,
+}
+
+/** Match Next's ServerInsertedHTMLContext surface — non-functional in
+ *  the embed environment but importable so consumers don't crash. */
+export const ServerInsertedHTMLContext = null as any

package/src/hooks/index.ts

@@ -18,3 +18,12 @@ export * from './nats/use-nats-client'
 
 // Viewport / lazy-mount primitive (shared IO singleton)
 export * from './use-near-viewport'
+
+// Access code integration — pairs with the standalone helpers in
+// `utils/access-code-client`. Lives in `hooks/` so the createContext
+// pulled in via EndpointsRuntimeContext doesn't end up in the
+// server-safe utils bundle.
+export * from './use-access-code-integration'
+
+// OG placeholder URL builder hook (requires host-supplied URL builder)
+export * from './use-og-placeholder'

package/src/hooks/state/use-api-params.ts

@@ -19,7 +19,7 @@
 
 'use client'
 
-import { useRouter, useSearchParams } from 'next/navigation'
+import { useRouter, useSearchParams } from '../../embed-shims/next-navigation'
 import { useCallback, useMemo, useRef } from 'react'
 import { FlattenedParam, shouldIncludeInUrl } from './flatten-schema'
 import { JSType } from './graphql-parser'