@flamingo-stack/openframe-frontend-core 0.0.203 → 0.0.204-snapshot.20260523020255

package/src/components/shared/product-release/product-release-card.tsx

@@ -7,7 +7,6 @@ import { StatusBadge } from '../../ui/status-badge'
 import { SquareAvatar } from '../../ui/square-avatar'
 import {
   AlertTriangle,
-  ChevronRight,
   Eye,
   Package,
   Play,
@@ -18,21 +17,28 @@ import {
 import { cn } from '../../../utils/cn'
 
 /**
- * Card density:
- * - `default`: full /releases page row (vertical title + description on the
- *   left, version + date column on the right).
- * - `sm`: compact horizontal layout (~80px tall) sized for inline rendering
- *   inside chat messages and other tight surfaces. Drops `<h3>` (block-only,
+ * Card density. Two variants, both actively used across openframe + flamingo
+ * apps and the related-content rail:
+ *
+ * - `lg`: rich large card used everywhere a product release is the focal
+ *   item — openframe's `/releases` catalog row, flamingo's DevCenter tab,
+ *   investor-update related-content section. Three zones — hero (16:9 cover
+ *   + version pill + title + summary), changelog stats strip (icons +
+ *   counts), metadata grid footer (Type · Status · Released · Author). The
+ *   grid mirrors the hub's `<EntityAuthorCard>` byte-for-byte (see lg
+ *   branch comment).
+ *
+ * - `sm`: compact horizontal layout (~80px tall) for inline rendering inside
+ *   chat messages and other tight surfaces. Drops `<h3>` (block-only,
  *   illegal inside markdown `<p>`) for `<span>` text, swaps the outer
  *   `InteractiveCard` for a `<span>`-anchored link, and collapses to:
  *   56px icon + 1-line title + 1-line meta (version · date).
- * - `catalog`: rich /releases catalog row. Three zones — hero (16:9 cover +
- *   version pill + title + summary), changelog stats strip (icons + counts),
- *   metadata grid footer (Type · Status · Released · Author). The grid
- *   mirrors the hub's `<EntityAuthorCard>` byte-for-byte (see catalog
- *   branch comment).
+ *
+ * A previous `default` variant (vertical title+description / version+date
+ * column) was deleted in the 2026-05 DRY pass — it had a single consumer
+ * (the hub's RelatedContentSection) that has since moved to `lg`.
  */
-export type ProductReleaseCardSize = 'default' | 'sm' | 'catalog'
+export type ProductReleaseCardSize = 'lg' | 'sm'
 
 /**
  * Minimal structural `<a>` prop bundle the consumer composes (typically
@@ -80,7 +86,7 @@ export interface ProductReleaseCardProps {
   anchorProps?: ProductReleaseCardAnchorProps
   /** Additional CSS classes */
   className?: string
-  /** Card density. Defaults to `'default'`. */
+  /** Card density. Defaults to `'lg'` (the canonical large card). */
   size?: ProductReleaseCardSize
 
   // ─── Catalog-only props (ignored by `default` / `sm` branches) ─────────
@@ -125,7 +131,7 @@ export function ProductReleaseCard({
   onClick,
   anchorProps,
   className,
-  size = 'default',
+  size = 'lg',
   coverImage,
   hasVideoCover,
   releaseType,
@@ -135,7 +141,7 @@ export function ProductReleaseCard({
   author,
   changelogCounts,
 }: ProductReleaseCardProps) {
-  // ----- CATALOG branch (rich /releases catalog row) -------------------------
+  // ----- LG branch (rich /releases catalog row + related-content rail) -----
   // The card has THREE zones:
   //   1. Hero — cover image LEFT, version pill + title + summary RIGHT.
   //   2. Changelog strip — icons + counts (hidden when total === 0).
@@ -145,11 +151,11 @@ export function ProductReleaseCard({
   //      author-cell shapes, byte-for-byte). The OSS lib has zero hub
   //      coupling by design; we cannot import the hub's
   //      <EntityAuthorCard>. This is the SAME inline-duplication policy
-  //      documented for the COMPACT_CARD_* string set at lines ~104-108.
-  //      If the hub's <EntityAuthorCard> visual changes (cell padding,
-  //      divider styles, avatar size, etc.), update this branch in
-  //      lockstep.
-  if (size === 'catalog') {
+  //      documented for the COMPACT_CARD_* string set in the chat-card
+  //      file. If the hub's <EntityAuthorCard> visual changes (cell
+  //      padding, divider styles, avatar size, etc.), update this branch
+  //      in lockstep.
+  if (size === 'lg') {
     const totalChangelog =
       (changelogCounts?.features ?? 0) +
       (changelogCounts?.fixes ?? 0) +
@@ -157,46 +163,60 @@ export function ProductReleaseCard({
       (changelogCounts?.breaking ?? 0)
 
     // Build the metadata-grid cell array — mirrors the hub's
-    // EntityAuthorCard composition (extras → date → author). The
-    // release-type cell carries a colored chip; other cells are plain
-    // value + label.
+    // EntityAuthorCard composition. ALWAYS render all 3 value cells
+    // (Type / Status / Released) — missing values render as a plain
+    // em-dash + label so the grid keeps a fixed 4-cell shape (matching
+    // the skeleton). The Author cell is also always rendered below
+    // (effectiveAuthor falls back to a placeholder shape). This is
+    // load-to-resolve baseline parity: any conditional cell would
+    // introduce a reflow when the skeleton resolves.
+    //
+    // Plan note: em-dash placeholders read as plain text (NOT a colored
+    // StatusBadge for the Type cell) so empty badges don't look broken
+    // next to populated badges.
     type ValueCell = {
       value: string
       label: string
       uppercase: boolean
       colorScheme?: 'error' | 'cyan' | 'success' | 'warning'
     }
-    const valueCells: ValueCell[] = []
-    if (releaseType && releaseTypeBadgeColor) {
-      valueCells.push({
-        value: releaseType.toUpperCase(),
-        label: 'Type',
-        uppercase: true,
-        colorScheme: releaseTypeBadgeColor,
-      })
-    }
-    if (releaseStatus) {
-      valueCells.push({
-        value: releaseStatus.toUpperCase(),
-        label: 'Status',
-        uppercase: true,
-      })
-    }
-    if (formattedDate) {
-      valueCells.push({
-        value: formattedDate,
-        label: 'Released',
-        uppercase: false,
-      })
-    }
-    const hasAuthorCell = !!author?.full_name
-    const totalCells = valueCells.length + (hasAuthorCell ? 1 : 0)
-    // Tailwind JIT cannot compile dynamic class names — explicit branches:
-    const gridColsClass =
-      totalCells >= 4 ? 'md:grid-cols-4'
-        : totalCells === 3 ? 'md:grid-cols-3'
-          : totalCells === 2 ? 'md:grid-cols-2'
-            : 'md:grid-cols-1'
+    const valueCells: ValueCell[] = [
+      releaseType && releaseTypeBadgeColor
+        ? {
+            value: releaseType.toUpperCase(),
+            label: 'Type',
+            uppercase: true,
+            colorScheme: releaseTypeBadgeColor,
+          }
+        : { value: '—', label: 'Type', uppercase: false },
+      releaseStatus
+        ? {
+            value: releaseStatus.toUpperCase(),
+            label: 'Status',
+            uppercase: true,
+          }
+        : { value: '—', label: 'Status', uppercase: false },
+      formattedDate
+        ? {
+            value: formattedDate,
+            label: 'Released',
+            uppercase: false,
+          }
+        : { value: '—', label: 'Released', uppercase: false },
+    ]
+    // EMPTY_AUTHOR_PLACEHOLDER shape — mirrors the hub's
+    // EMPTY_AUTHOR_PLACEHOLDER constant exported from
+    // components/shared/entity-author-card.tsx (hub can't be imported
+    // here; the two are kept in lockstep per the inline-duplication
+    // policy documented in the catalog branch comment above).
+    const effectiveAuthor = author?.full_name
+      ? author
+      : { full_name: '—', avatar_url: null, job_title: 'Unknown' }
+    // Fixed 4-cell grid (Type / Status / Released / Author) so the
+    // skeleton's shape matches the loaded card exactly. The earlier
+    // dynamic `gridColsClass` ternary collapsed missing cells and
+    // caused 28-56px reflow on resolve.
+    const gridColsClass = 'md:grid-cols-4'
     const dividerClass = 'border-b md:border-b-0 md:border-r border-ods-border'
 
     const frameClass = cn(
@@ -242,107 +262,130 @@ export function ProductReleaseCard({
                 v{version}
               </span>
             </div>
-            <h3 className="font-['Azeret_Mono'] font-semibold text-xl md:text-2xl text-ods-text-primary leading-tight line-clamp-2 mb-3">
-              {title}
-            </h3>
-            {summary && (
-              <p className="font-['DM_Sans'] text-sm md:text-base text-ods-text-secondary leading-relaxed line-clamp-4 flex-1">
-                {summary}
+            {/* Title — reserve a fixed 2-line height so cards with
+                1-line titles don't shrink and the catalog skeleton-to-
+                content transition is shift-free. Mirrors the
+                onboarding-guide catalog card. */}
+            <div className="min-h-[60px] md:min-h-[72px] flex items-start mb-3">
+              <h3 className="font-['Azeret_Mono'] font-semibold text-xl md:text-2xl text-ods-text-primary leading-tight line-clamp-2">
+                {title}
+              </h3>
+            </div>
+            {/* Summary — fixed 3-line height. `line-clamp-3` caps long
+                summaries at 3 lines; `min-h` reserves the same vertical
+                space when content is shorter, so the catalog grid stays
+                row-consistent regardless of per-card content length.
+                Heights derived from text-sm md:text-base × leading-relaxed
+                (1.625): 14×1.625×3 ≈ 68 px mobile, 16×1.625×3 ≈ 78 px desktop. */}
+            <div className="min-h-[68px] md:min-h-[78px]">
+              <p className="font-['DM_Sans'] text-sm md:text-base text-ods-text-secondary leading-relaxed line-clamp-3">
+                {summary ?? ''}
               </p>
-            )}
+            </div>
           </div>
         </div>
 
-        {/* CHANGELOG STRIP — hidden when total === 0 */}
-        {totalChangelog > 0 && changelogCounts && (
-          <div className="border-t border-ods-border pt-3 flex flex-wrap items-center gap-x-4 gap-y-1.5 font-['DM_Sans'] text-sm text-ods-text-secondary">
-            {changelogCounts.features > 0 && (
-              <span className="inline-flex items-center gap-1.5">
-                <Sparkles className="w-3.5 h-3.5" />
-                {changelogCounts.features} {changelogCounts.features === 1 ? 'feature' : 'features'}
-              </span>
-            )}
-            {changelogCounts.fixes > 0 && (
-              <span className="inline-flex items-center gap-1.5">
-                <Wrench className="w-3.5 h-3.5" />
-                {changelogCounts.fixes} {changelogCounts.fixes === 1 ? 'fix' : 'fixes'}
-              </span>
-            )}
-            {changelogCounts.improvements > 0 && (
-              <span className="inline-flex items-center gap-1.5">
-                <TrendingUp className="w-3.5 h-3.5" />
-                {changelogCounts.improvements} {changelogCounts.improvements === 1 ? 'improvement' : 'improvements'}
-              </span>
-            )}
-            {changelogCounts.breaking > 0 && (
-              <span className="inline-flex items-center gap-1.5 text-[var(--ods-attention-yellow-warning)]">
-                <AlertTriangle className="w-3.5 h-3.5" />
-                {changelogCounts.breaking} breaking
-              </span>
-            )}
-          </div>
-        )}
+        {/* CHANGELOG STRIP — ALWAYS rendered so the skeleton's
+            always-on changelog placeholder matches the loaded shape
+            (zero reflow on resolve). When `totalChangelog === 0`, an
+            empty-state line takes the same vertical space as the
+            populated row. */}
+        <div className="border-t border-ods-border pt-3 flex flex-wrap items-center gap-x-4 gap-y-1.5 font-['DM_Sans'] text-sm text-ods-text-secondary">
+          {totalChangelog > 0 && changelogCounts ? (
+            <>
+              {changelogCounts.features > 0 && (
+                <span className="inline-flex items-center gap-1.5">
+                  <Sparkles className="w-3.5 h-3.5" />
+                  {changelogCounts.features} {changelogCounts.features === 1 ? 'feature' : 'features'}
+                </span>
+              )}
+              {changelogCounts.fixes > 0 && (
+                <span className="inline-flex items-center gap-1.5">
+                  <Wrench className="w-3.5 h-3.5" />
+                  {changelogCounts.fixes} {changelogCounts.fixes === 1 ? 'fix' : 'fixes'}
+                </span>
+              )}
+              {changelogCounts.improvements > 0 && (
+                <span className="inline-flex items-center gap-1.5">
+                  <TrendingUp className="w-3.5 h-3.5" />
+                  {changelogCounts.improvements} {changelogCounts.improvements === 1 ? 'improvement' : 'improvements'}
+                </span>
+              )}
+              {changelogCounts.breaking > 0 && (
+                <span className="inline-flex items-center gap-1.5 text-[var(--ods-attention-yellow-warning)]">
+                  <AlertTriangle className="w-3.5 h-3.5" />
+                  {changelogCounts.breaking} breaking
+                </span>
+              )}
+            </>
+          ) : (
+            <span className="text-sm text-ods-text-secondary">No changelog entries yet</span>
+          )}
+        </div>
 
-        {/* METADATA GRID FOOTER — mirrors EntityAuthorCard byte-for-byte */}
-        {totalCells > 0 && (
-          <div
-            className={cn(
-              'grid grid-cols-1',
-              gridColsClass,
-              'border border-ods-border rounded-md overflow-hidden w-full',
-            )}
-          >
-            {valueCells.map((cell, i) => (
-              <div
-                key={`${cell.label}-${i}`}
-                className={cn(
-                  'bg-ods-card p-4 flex flex-col gap-3',
-                  // Last value cell skips the trailing divider when no
-                  // author cell follows; otherwise every value cell gets it.
-                  (i < valueCells.length - 1 || hasAuthorCell) && dividerClass,
-                )}
-              >
-                <div className="flex flex-col gap-0">
-                  {cell.colorScheme ? (
-                    <StatusBadge
-                      text={cell.value}
-                      variant="card"
-                      colorScheme={cell.colorScheme}
-                      singleLine
-                      className="self-start"
-                    />
-                  ) : (
-                    <p className="text-h4 text-ods-text-primary">
-                      {cell.uppercase ? cell.value.toLocaleUpperCase() : cell.value}
-                    </p>
-                  )}
-                  <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary">
-                    {cell.label}
-                  </p>
-                </div>
-              </div>
-            ))}
-            {hasAuthorCell && author && (
-              <div className="bg-ods-card p-4 flex items-center gap-3">
-                <SquareAvatar
-                  src={author.avatar_url ?? undefined}
-                  alt={author.full_name}
-                  fallback={author.full_name.charAt(0).toUpperCase()}
-                  size="md"
-                  variant="round"
-                />
-                <div className="flex flex-col gap-0 flex-1 min-w-0">
-                  <p className="text-h3 tracking-[-0.36px] text-ods-text-primary truncate">
-                    {author.full_name}
-                  </p>
-                  <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary">
-                    {author.job_title || 'Author'}
+        {/* METADATA GRID FOOTER — fixed 4-cell shape (Type / Status /
+            Released / Author) so the skeleton mirrors the loaded card
+            exactly. Empty value cells render em-dash + label (plain
+            text, no colored badge — em-dash badges read as broken next
+            to populated ones); the Author cell falls back to the
+            EMPTY_AUTHOR_PLACEHOLDER shape declared above. */}
+        <div
+          className={cn(
+            'grid grid-cols-1',
+            gridColsClass,
+            'border border-ods-border rounded-md overflow-hidden w-full',
+          )}
+        >
+          {valueCells.map((cell, i) => (
+            <div
+              key={`${cell.label}-${i}`}
+              className={cn('bg-ods-card p-4 flex flex-col gap-3', dividerClass)}
+            >
+              <div className="flex flex-col gap-0">
+                {cell.colorScheme ? (
+                  <StatusBadge
+                    text={cell.value}
+                    variant="card"
+                    colorScheme={cell.colorScheme}
+                    singleLine
+                    className="self-start"
+                  />
+                ) : (
+                  <p
+                    className={cn(
+                      'text-h4',
+                      // Em-dash placeholder reads as secondary text;
+                      // populated values stay primary.
+                      cell.value === '—' ? 'text-ods-text-secondary' : 'text-ods-text-primary',
+                    )}
+                  >
+                    {cell.uppercase ? cell.value.toLocaleUpperCase() : cell.value}
                   </p>
-                </div>
+                )}
+                <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary">
+                  {cell.label}
+                </p>
               </div>
-            )}
+            </div>
+          ))}
+          <div className="bg-ods-card p-4 flex items-center gap-3">
+            <SquareAvatar
+              src={effectiveAuthor.avatar_url ?? undefined}
+              alt={effectiveAuthor.full_name}
+              fallback={effectiveAuthor.full_name.charAt(0).toUpperCase()}
+              size="md"
+              variant="round"
+            />
+            <div className="flex flex-col gap-0 flex-1 min-w-0">
+              <p className="text-h3 tracking-[-0.36px] text-ods-text-primary truncate">
+                {effectiveAuthor.full_name}
+              </p>
+              <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary">
+                {effectiveAuthor.job_title || 'Author'}
+              </p>
+            </div>
           </div>
-        )}
+        </div>
 
         {typeof viewCount === 'number' && viewCount > 0 && (
           <div className="flex items-center gap-1.5 text-xs text-ods-text-secondary">
@@ -519,99 +562,8 @@ export function ProductReleaseCard({
     )
   }
 
-  // ----- DEFAULT branch (existing /releases card layout) -----------------
-  // When `anchorProps` is supplied, the card behaves like every other
-  // entity card on the related-content rail — real `<a>` with the
-  // consumer's `useNavLink` bundle (cross-origin → new tab, same-origin
-  // → soft RSC nav, modifier-click → browser default). The
-  // `<InteractiveCard onClick>` form remains the back-compat path for
-  // the public `/releases` tab caller which still routes via
-  // `router.push()` directly.
-  if (anchorProps) {
-    return (
-      <a
-        {...anchorProps}
-        className={cn(
-          'bg-ods-card border border-ods-border rounded-[6px]',
-          'flex flex-col md:flex-row',
-          'items-start md:items-center',
-          'gap-3 md:gap-4',
-          'p-4 no-underline',
-          'transition-colors hover:border-ods-text-secondary/40',
-          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent focus-visible:ring-offset-1 focus-visible:ring-offset-ods-card',
-          className,
-        )}
-      >
-        {/* Left column - content */}
-        <div className="flex-1 w-full md:w-auto min-w-0 flex flex-col justify-center gap-2">
-          <div className="min-h-[48px] flex items-center">
-            <h3 className="text-h3 text-ods-text-primary tracking-[-0.36px] line-clamp-2" title={title}>
-              {title}
-            </h3>
-          </div>
-          <p className="text-h4 text-ods-text-secondary line-clamp-3" title={summary || ' '}>
-            {summary || ' '}
-          </p>
-        </div>
-        <div className="flex items-center gap-2 w-full md:w-auto justify-start md:justify-end shrink-0">
-          <div className="w-[200px] flex flex-col justify-center gap-2">
-            <p className="text-h3 text-ods-text-primary tracking-[-0.36px] truncate">
-              {version}
-            </p>
-            <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary truncate">
-              {formattedDate}
-            </p>
-          </div>
-          <div className="flex items-center justify-center p-3 shrink-0">
-            <ChevronRight className="h-6 w-6 text-ods-text-primary" />
-          </div>
-        </div>
-      </a>
-    )
-  }
-  return (
-    <InteractiveCard
-      clickable={true}
-      onClick={onClick}
-      className={cn(
-        'bg-ods-card border border-ods-border rounded-[6px]',
-        'flex flex-col md:flex-row',
-        'items-start md:items-center',
-        'gap-3 md:gap-4',
-        'p-4',
-        className
-      )}
-    >
-      {/* Left column - content */}
-      <div className="flex-1 w-full md:w-auto min-w-0 flex flex-col justify-center gap-2">
-        <div className="min-h-[48px] flex items-center">
-          <h3 className="text-h3 text-ods-text-primary tracking-[-0.36px] line-clamp-2" title={title}>
-            {title}
-          </h3>
-        </div>
-        <p className="text-h4 text-ods-text-secondary line-clamp-3" title={summary || ' '}>
-          {summary || ' '}
-        </p>
-      </div>
-
-      {/* Right column - version + date */}
-      <div
-        className="flex items-center gap-2 w-full md:w-auto justify-start md:justify-end shrink-0"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <div className="w-[200px] flex flex-col justify-center gap-2">
-          <p className="text-h3 text-ods-text-primary tracking-[-0.36px] truncate">
-            {version}
-          </p>
-          <p className="font-['DM_Sans'] font-medium text-[14px] leading-[20px] text-ods-text-secondary truncate">
-            {formattedDate}
-          </p>
-        </div>
-        {/* Icon column */}
-        <div className="flex items-center justify-center p-3 shrink-0">
-          <ChevronRight className="h-6 w-6 text-ods-text-primary" />
-        </div>
-      </div>
-    </InteractiveCard>
-  )
+  // Unreachable — `size` is typed `'lg' | 'sm'` and both branches return
+  // above. Kept as a defensive throw so a future variant addition that
+  // forgets to return doesn't silently render `undefined`.
+  throw new Error(`ProductReleaseCard: unsupported size '${size as string}'`)
 }

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,29 @@
+/**
+ * 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'

package/src/hooks/index.ts

@@ -18,3 +18,9 @@ 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'