@flamingo-stack/openframe-frontend-core 0.0.299 → 0.0.300

package/dist/utils/og-placeholder.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Branded OG-placeholder URL construction — the DEFAULT cover-image fallback
+ * for entity cards (onboarding guides, blog/case-study/release/etc.) that have
+ * no image.
+ *
+ * ALL of the logic lives here, in the lib. A consumer hands over its runtime
+ * `endpoints` object and NOTHING else — base resolution AND the `?title=…`
+ * concatenation happen inside `buildOgPlaceholderUrl`. For the entity-card +
+ * onboarding-detail surfaces this is the single entry point — no card builds an
+ * og-placeholder URL itself (that was the bug this replaced: each embedder
+ * wired a per-surface callback that concatenated the URL, and a host that
+ * forgot it rendered a blank slot with no request). (Other server-side OG paths
+ * such as the hub's blog og:image generator construct their own URLs and are
+ * out of this module's scope.)
+ *
+ * The base API URL is taken from the endpoints the host already configures:
+ *   1. explicit `endpoints.ogPlaceholderUrl`
+ *   2. derived from the sibling `endpoints.imageProxyUrlPrefix` (same API base)
+ *   3. same-origin relative `/api/og-placeholder`
+ * The base may already carry pre-existing query params; they're preserved and
+ * `title` (+ dimensions) are layered on top. Per-platform brand colors are NOT
+ * baked into this URL — the `/api/og-placeholder` route resolves them
+ * server-side from the platform. Most hosts leave `ogPlaceholderUrl` unset and
+ * let the base derive from `imageProxyUrlPrefix`.
+ */
+/** The slice of `ChatRuntime.endpoints` this module needs. */
+export interface OgPlaceholderEndpoints {
+    /** Explicit base URL for the og-placeholder route. May already carry query
+     *  params — they're preserved. Per-platform colors are NOT baked here; the
+     *  route resolves them server-side from the platform. */
+    ogPlaceholderUrl?: string;
+    /** Sibling image route under the SAME API base. When `ogPlaceholderUrl` is
+     *  unset, the base is derived from this by swapping the trailing
+     *  `/image-proxy` segment for `/og-placeholder` — so a host that already
+     *  proxies images gets the placeholder for free, with zero extra wiring. */
+    imageProxyUrlPrefix?: string;
+}
+export interface BuildOgPlaceholderOptions {
+    /** Site name shown under the title. Skipped when empty. */
+    site?: string;
+    /** `'wide'` (1200×630, the route default — no `w`/`h` emitted) or
+     *  `'square'` (1024×1024, for compact 56×56 chat-inline slots). */
+    aspect?: 'wide' | 'square';
+    /** Explicit pixel overrides (win over `aspect`). */
+    width?: number;
+    height?: number;
+}
+/**
+ * Build the branded og-placeholder image URL from the host's `endpoints` + a
+ * title. This is the single entry point for entity-card + onboarding-detail
+ * cover fallbacks: it resolves the route base from `endpoints` AND concatenates
+ * `title` (+ dimensions), so those consumers never construct a URL themselves.
+ *
+ * Pure string construction — SSR- and browser-safe. Always returns a usable
+ * URL (relative default at worst), so a missing/unknown image degrades
+ * gracefully via the `<img onError>` recovery in the card components.
+ */
+export declare function buildOgPlaceholderUrl(endpoints: OgPlaceholderEndpoints | null | undefined, title: string, options?: BuildOgPlaceholderOptions): string;
+//# sourceMappingURL=og-placeholder.d.ts.map

package/dist/utils/og-placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-placeholder.d.ts","sourceRoot":"","sources":["../../src/utils/og-placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC;;6DAEyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;gFAG4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;uEACmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EACpD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAoBR"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.299",
+  "version": "0.0.300",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/entity-cards/admin-content-card.tsx

@@ -17,7 +17,7 @@ interface AdminContentCardProps {
   /** Cover image URL */
   imageUrl?: string | null
   /** Pre-computed placeholder URL used when `imageUrl` is missing or
-   *  fails to load. Hub callers pass `useOgPlaceholder(title)`; embedders
+   *  fails to load. Hub callers pass `useOgPlaceholderUrl({ title })`; embedders
    *  supply their own URL or leave null for a plain background fallback. */
   placeholderUrl?: string | null
   /** Alt text / fallback title */

package/src/components/chat/entity-cards/blog-card.tsx

@@ -14,7 +14,7 @@
  *
  * Image-fallback chain:
  *   `post.featured_image` → `placeholderUrl` (caller passes
- *   `useOgPlaceholder(...)` from the hub OR any pre-resolved URL) →
+ *   `useOgPlaceholderUrl(...)` from the hub OR any pre-resolved URL) →
  *   `bg-ods-bg` (via the slot's background).
  */
 
@@ -53,7 +53,7 @@ export interface BlogCardProps {
    *  pure-presentation contract. */
   targetPlatform?: string | null
   /** Placeholder URL when `post.featured_image` is missing. Caller
-   *  resolves via `useOgPlaceholder` (hub) or a static asset. */
+   *  resolves via `useOgPlaceholderUrl` (hub) or a static asset. */
   placeholderUrl?: string | null
   size?: 'default' | 'sm'
   className?: string

package/src/components/chat/entity-cards/blog-image-placeholder.tsx

@@ -3,7 +3,7 @@
 import React from 'react'
 
 interface BlogImagePlaceholderProps {
-  /** Cover-image URL. The hub passes a `useOgPlaceholder(title, category)`
+  /** Cover-image URL. The hub passes a `useOgPlaceholderUrl({ title, siteName })`
    *  result; embedders pass their own pre-resolved URL. When null, the
    *  component renders nothing. */
   imageUrl: string | null

package/src/components/chat/entity-cards/case-study-card.tsx

@@ -9,7 +9,7 @@
  *
  * Image-fallback chain:
  *   `study.featured_image` → `placeholderUrl` (caller passes
- *   `useOgPlaceholder(...)`) → `bg-ods-bg`.
+ *   `useOgPlaceholderUrl(...)`) → `bg-ods-bg`.
  */
 
 import React from 'react'

package/src/components/chat/entity-cards/onboarding-guide-card.tsx

@@ -11,9 +11,10 @@
  *
  * Link semantics: the card derives `target`/`rel` from `ChatRuntime.navigation
  * .decideNewTab` (hub-wired via `HubRuntimeProvider`) and the placeholder
- * image from `ChatRuntime.resolvePlaceholderUrl`. Explicit `target` / `rel`
- * / `placeholderUrl` props always WIN — chat dispatch and tests can
- * pre-resolve. No runtime mounted → same-tab + no placeholder.
+ * image from the runtime's base API URL (`endpoints.ogPlaceholderUrl`, via
+ * `useEntityCardPlaceholder`). Explicit `target` / `rel` / `placeholderUrl`
+ * props always WIN — chat dispatch and tests can pre-resolve. No runtime
+ * mounted → same-tab + same-origin relative placeholder.
  */
 
 import React from 'react'

package/src/components/chat/entity-cards/use-entity-card-placeholder.ts

@@ -1,50 +1,37 @@
 'use client'
 
 /**
- * Shared OG-placeholder resolver for every entity card.
+ * Entity-card OG-placeholder resolver.
  *
- * Pure-presentation cards historically required callers to
- * pre-compute `placeholderUrl` via a hub-side `useOgPlaceholder`
- * wrapper that injected the hub's `buildOgPlaceholderUrl` (resolves
- * CSS-var ODS colors to hex via the static map).
- *
- * This hook moves that resolution INTO the card via the
- * `ChatRuntime.resolvePlaceholderUrl` callback. Embedders that don't
- * wire the callback get no placeholder (the card's empty-state path
- * activates) — same fallback semantics as before.
- *
- * Backwards compat: explicit `placeholderUrl` prop ALWAYS wins over
- * runtime-derived value. Callers that pre-resolve (chat dispatch,
- * tests) are unaffected.
+ * A thin wrapper over the one og-placeholder hook (`useOgPlaceholderUrl`) that
+ * adds a single concern: an explicit `placeholderUrl` prop (incl. `null`) wins
+ * over the runtime-derived URL — chat dispatch + tests pre-resolve through it.
+ * All URL construction lives in `useOgPlaceholderUrl` / `buildOgPlaceholderUrl`,
+ * so this surface shares one memo + one code path with every other consumer.
  */
 
-import { useChatRuntime } from '../../../contexts/chat-runtime-context'
-import { useOgPlaceholder } from '../../../hooks/use-og-placeholder'
+import { useOgPlaceholderUrl } from '../../../hooks/use-og-placeholder-url'
 
 export interface UseEntityCardPlaceholderArgs {
   /** Entity title — used as the placeholder label. */
   title: string | undefined | null
-  /** Explicit override. When set, runtime resolver is skipped. */
+  /** Explicit override. When set (including `null`), the runtime default is
+   *  skipped. */
   placeholderUrl?: string | null
   /** Site name shown under the title. Optional. */
   siteName?: string
-  /** Output aspect ratio. `'wide'` (default) for catalog cards,
-   *  `'square'` for compact chat-inline cards. */
+  /** Output aspect ratio. `'wide'` (default) for catalog cards, `'square'`
+   *  for compact chat-inline cards. */
   aspect?: 'wide' | 'square'
 }
 
-const NO_OP_BUILDER = () => ''
-
 export function useEntityCardPlaceholder({
   title,
   placeholderUrl,
   siteName = '',
   aspect = 'wide',
 }: UseEntityCardPlaceholderArgs): string | null {
-  const runtime = useChatRuntime()
-  const builder = runtime?.resolvePlaceholderUrl ?? NO_OP_BUILDER
-  const enabled = placeholderUrl === undefined && !!runtime?.resolvePlaceholderUrl
-  const derived = useOgPlaceholder(builder, title, siteName, enabled, aspect)
-  // Explicit prop (including explicit null) wins; `undefined` falls back to derived.
+  const derived = useOgPlaceholderUrl({ title, siteName, aspect })
+  // Explicit prop (including explicit null) wins; `undefined` → derived default.
   return placeholderUrl !== undefined ? placeholderUrl : derived
 }

package/src/components/chat/entity-cards/what-i-shipped-card.tsx

@@ -17,7 +17,7 @@ export interface WhatIShippedCardData {
 
 export interface WhatIShippedCardProps {
   entry: WhatIShippedCardData
-  /** OG fallback cover. Caller computes it (hub: `useOgPlaceholder`; related
+  /** OG fallback cover. Caller computes it (hub: `useOgPlaceholderUrl`; related
    *  rail: `extras.buildOgPlaceholderUrl`). */
   placeholderUrl?: string | null
   /** Owner action row (dashboard). Omit for a read-only card. */

package/src/components/embeds/og-link-preview.tsx

@@ -65,8 +65,8 @@ export class OGLinkErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoun
 
 /**
  * Builds a placeholder image URL when the scrape returns no image. Hub passes
- * its own `buildOgPlaceholderUrl` (which resolves CSS-var ODS colors against
- * the platform's brand palette + hits `/api/og-placeholder`); other embedders
+ * its own `buildOgPlaceholderUrl` (which hits `/api/og-placeholder?…&platform=`;
+ * the route resolves the platform's brand colors server-side); other embedders
  * can omit the prop to disable the placeholder entirely.
  *
  * Receives the post-scrape `title` and `siteName` so the placeholder can echo

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -39,6 +39,7 @@ import { useChatRuntime } from '../../contexts/chat-runtime-context'
 import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide'
 import type { VideoTeaser } from '../../types/video-processing'
 import { resolveContentHref } from '../../utils/content-href'
+import { buildOgPlaceholderUrl } from '../../utils/og-placeholder'
 import { useSelfFetch } from '../../hooks/use-self-fetch'
 
 export interface OnboardingGuideDetailViewProps {
@@ -133,8 +134,9 @@ export function OnboardingGuideDetailView({
     guide.main_video_thumbnail ||
     guide.featured_image ||
     guide.og_image_url ||
-    runtime?.resolvePlaceholderUrl?.(guide.title, { aspect: 'wide' }) ||
-    undefined
+    // `buildOgPlaceholderUrl` always returns a usable string (relative route at
+    // worst), so it's the terminal fallback — no trailing `|| undefined` needed.
+    buildOgPlaceholderUrl(runtime?.endpoints, guide.title, { aspect: 'wide' })
 
   const defaultRenderRelatedCard = (g: OnboardingGuide) => {
     const cta = resolveContentHref(runtime?.composeContentUrl, {

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

@@ -117,6 +117,23 @@ export interface ChatRuntime {
      *  leave it unset. Matches the `skipDomains` parameter of
      *  `getProxiedImageUrl`. */
     imageProxySkipDomains?: string[]
+    /** Optional base URL for the branded og-placeholder image route — the
+     *  DEFAULT cover-image fallback for entity cards with no image. The lib
+     *  appends `?title=…` (+ `w`/`h` for square slots) itself, so this is
+     *  the base, NOT a full URL: relative (`/api/og-placeholder`) for same-
+     *  origin hosts, or the proxied path (`/content/api/og-placeholder`) for
+     *  cross-origin embedders. May carry baked-in query params (preserved when
+     *  the lib layers `title`/dimensions on top) — but per-platform brand
+     *  colors are NO LONGER baked here; the `/api/og-placeholder` route
+     *  resolves them server-side from the platform. Most hosts leave this unset
+     *  and let the lib derive the base from `imageProxyUrlPrefix`.
+     *
+     *  OPTIONAL — when unset the lib derives the base from the sibling
+     *  `imageProxyUrlPrefix` (same API base, route name swapped), then falls
+     *  back to the relative `/api/og-placeholder`. So an embedder that already
+     *  proxies images needs NO og-placeholder wiring. See
+     *  `resolveOgPlaceholderBase` / `buildOgPlaceholderUrl` in `../utils`. */
+    ogPlaceholderUrl?: string
     /** Supabase storage origin (e.g. `https://xyz.supabase.co`) — used
      *  by `useVideoWarmup` to scope the `<link rel="preload" as="video">`
      *  hint to MP4s the deployment actually hosts. Hub wires it via
@@ -158,19 +175,6 @@ export interface ChatRuntime {
      *  same-origin/same-platform → same tab, else new tab. */
     decideNewTab?: (args: { href: string; targetPlatform?: string | null }) => boolean
   }
-  /** Optional OG placeholder URL builder. Returns a branded
-   *  `/api/og-placeholder?...` URL for the given title. Hub wires this
-   *  to its `buildOgPlaceholderUrl` (resolves CSS-var ODS colors to
-   *  hex via the static map). Embedders can wire any equivalent that
-   *  hits their own placeholder route — or omit, in which case entity
-   *  cards fall back to no placeholder.
-   *
-   *  Pure synchronous function — NOT a hook. Callers wrap with
-   *  `useMemo`/`useOgPlaceholder` for memoization. */
-  resolvePlaceholderUrl?: (
-    title: string,
-    options?: { site?: string; aspect?: 'wide' | 'square' },
-  ) => string
   /** Optional content-URL composer. Returns the platform-aware href +
    *  target-platform tuple for a content entity. Hub wires this to its
    *  `buildContentURL(type, slug, extractPrimaryPlatform(platforms))`

package/src/hooks/index.ts

@@ -25,8 +25,8 @@ export * from './use-near-viewport'
 // 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'
+// THE og-placeholder URL hook (endpoints-driven; no injected builder)
+export * from './use-og-placeholder-url'
 
 // Deep-link "scroll to URL hash" after data loads. Pairs with URL
 // composers that emit `?<filter>=<id>#<prefix>-<id>` — the filter

package/src/hooks/use-og-placeholder-url.ts

@@ -0,0 +1,46 @@
+'use client'
+
+import { useMemo } from 'react'
+
+import { useChatRuntime } from '../contexts/chat-runtime-context'
+import { buildOgPlaceholderUrl } from '../utils/og-placeholder'
+
+/**
+ * Resolve a branded og-placeholder image URL for a title, driven entirely by
+ * the runtime `endpoints` (no injected builder).
+ *
+ * THE one og-placeholder hook. It reads the host's `endpoints` from
+ * `ChatRuntime` and hands them to `buildOgPlaceholderUrl`, which resolves the
+ * route base (explicit `ogPlaceholderUrl` → derived from `imageProxyUrlPrefix`
+ * → same-origin `/api/og-placeholder`) and appends `?title=…`. Per-platform
+ * brand colors are resolved SERVER-SIDE by the route — nothing is baked here.
+ *
+ * Replaces the old builder-injection `useOgPlaceholder(buildUrl, …)`: callers
+ * no longer pass a URL builder. `useEntityCardPlaceholder` delegates here too,
+ * so every surface shares one memo + one code path.
+ */
+export interface UseOgPlaceholderUrlArgs {
+  /** Text to display on the placeholder. */
+  title: string | undefined | null
+  /** Site name shown below the title (optional). */
+  siteName?: string
+  /** `'wide'` (1200×630 social-card; default) or `'square'` (1024×1024 — for
+   *  compact chat-inline slots so `object-cover` doesn't crop the title off). */
+  aspect?: 'wide' | 'square'
+  /** When `false`, returns `null` instead of a URL. */
+  enabled?: boolean
+}
+
+export function useOgPlaceholderUrl({
+  title,
+  siteName = '',
+  aspect = 'wide',
+  enabled = true,
+}: UseOgPlaceholderUrlArgs): string | null {
+  const endpoints = useChatRuntime()?.endpoints
+
+  return useMemo(() => {
+    if (!enabled || !title) return null
+    return buildOgPlaceholderUrl(endpoints, title, { site: siteName || undefined, aspect })
+  }, [endpoints, title, siteName, aspect, enabled])
+}

package/src/utils/index.ts

@@ -41,6 +41,10 @@ export * from './date-formatters'
 // rich card metadata): badge-color mapping + cover-image fallback resolution.
 export * from './release-badge'
 export * from './release-cover'
+// OG-placeholder fallback image — the lib-owned DEFAULT URL builder (replaces
+// the old per-embedder `ChatRuntime.resolvePlaceholderUrl` callback). Driven by
+// the runtime's base API URL; embedders override via `endpoints.ogPlaceholderUrl`.
+export * from './og-placeholder'
 // Dev-center URL param keys — the ONE source for the `?search=` / `?status=` / … keys the
 // chrome registry writes and the list views read; re-exported so embedders (and the hub's
 // dev-section-url helper) build deep-links with the same keys instead of a bare literal.

package/src/utils/og-placeholder.ts

@@ -0,0 +1,105 @@
+/**
+ * Branded OG-placeholder URL construction — the DEFAULT cover-image fallback
+ * for entity cards (onboarding guides, blog/case-study/release/etc.) that have
+ * no image.
+ *
+ * ALL of the logic lives here, in the lib. A consumer hands over its runtime
+ * `endpoints` object and NOTHING else — base resolution AND the `?title=…`
+ * concatenation happen inside `buildOgPlaceholderUrl`. For the entity-card +
+ * onboarding-detail surfaces this is the single entry point — no card builds an
+ * og-placeholder URL itself (that was the bug this replaced: each embedder
+ * wired a per-surface callback that concatenated the URL, and a host that
+ * forgot it rendered a blank slot with no request). (Other server-side OG paths
+ * such as the hub's blog og:image generator construct their own URLs and are
+ * out of this module's scope.)
+ *
+ * The base API URL is taken from the endpoints the host already configures:
+ *   1. explicit `endpoints.ogPlaceholderUrl`
+ *   2. derived from the sibling `endpoints.imageProxyUrlPrefix` (same API base)
+ *   3. same-origin relative `/api/og-placeholder`
+ * The base may already carry pre-existing query params; they're preserved and
+ * `title` (+ dimensions) are layered on top. Per-platform brand colors are NOT
+ * baked into this URL — the `/api/og-placeholder` route resolves them
+ * server-side from the platform. Most hosts leave `ogPlaceholderUrl` unset and
+ * let the base derive from `imageProxyUrlPrefix`.
+ */
+
+/** The slice of `ChatRuntime.endpoints` this module needs. */
+export interface OgPlaceholderEndpoints {
+  /** Explicit base URL for the og-placeholder route. May already carry query
+   *  params — they're preserved. Per-platform colors are NOT baked here; the
+   *  route resolves them server-side from the platform. */
+  ogPlaceholderUrl?: string
+  /** Sibling image route under the SAME API base. When `ogPlaceholderUrl` is
+   *  unset, the base is derived from this by swapping the trailing
+   *  `/image-proxy` segment for `/og-placeholder` — so a host that already
+   *  proxies images gets the placeholder for free, with zero extra wiring. */
+  imageProxyUrlPrefix?: string
+}
+
+export interface BuildOgPlaceholderOptions {
+  /** Site name shown under the title. Skipped when empty. */
+  site?: string
+  /** `'wide'` (1200×630, the route default — no `w`/`h` emitted) or
+   *  `'square'` (1024×1024, for compact 56×56 chat-inline slots). */
+  aspect?: 'wide' | 'square'
+  /** Explicit pixel overrides (win over `aspect`). */
+  width?: number
+  height?: number
+}
+
+/** Same-origin default — for hosts that serve the route themselves (the hub).
+ *  Cross-origin embedders override via `ogPlaceholderUrl` or inherit it from
+ *  `imageProxyUrlPrefix`. */
+const DEFAULT_OG_PLACEHOLDER_PATH = '/api/og-placeholder'
+
+/** Resolve the og-placeholder route base from the host's endpoints.
+ *  Internal — callers go through `buildOgPlaceholderUrl(endpoints, …)`. */
+function resolveOgPlaceholderBase(endpoints?: OgPlaceholderEndpoints | null): string {
+  if (endpoints?.ogPlaceholderUrl) return endpoints.ogPlaceholderUrl
+  const imageProxy = endpoints?.imageProxyUrlPrefix
+  if (imageProxy) {
+    // `/image-proxy` and `/og-placeholder` are sibling API routes under one
+    // base. Anchor to a path-segment boundary so we only rewrite the route
+    // name, never an incidental substring.
+    const derived = imageProxy.replace(/\/image-proxy(?=$|[?/])/, '/og-placeholder')
+    if (derived !== imageProxy) return derived
+  }
+  return DEFAULT_OG_PLACEHOLDER_PATH
+}
+
+/**
+ * Build the branded og-placeholder image URL from the host's `endpoints` + a
+ * title. This is the single entry point for entity-card + onboarding-detail
+ * cover fallbacks: it resolves the route base from `endpoints` AND concatenates
+ * `title` (+ dimensions), so those consumers never construct a URL themselves.
+ *
+ * Pure string construction — SSR- and browser-safe. Always returns a usable
+ * URL (relative default at worst), so a missing/unknown image degrades
+ * gracefully via the `<img onError>` recovery in the card components.
+ */
+export function buildOgPlaceholderUrl(
+  endpoints: OgPlaceholderEndpoints | null | undefined,
+  title: string,
+  options: BuildOgPlaceholderOptions = {},
+): string {
+  const base = resolveOgPlaceholderBase(endpoints)
+  const qIndex = base.indexOf('?')
+  const path = qIndex === -1 ? base : base.slice(0, qIndex)
+  const params = new URLSearchParams(qIndex === -1 ? '' : base.slice(qIndex + 1))
+
+  params.set('title', title)
+  if (options.site) params.set('site', options.site)
+
+  // Square aspect → request a 1024×1024 image so `object-cover` doesn't crop
+  // the title off in compact slots. Wide leaves dimensions to the route
+  // default (1200×630). Explicit width/height always win.
+  const width = options.width ?? (options.aspect === 'square' ? 1024 : undefined)
+  const height = options.height ?? (options.aspect === 'square' ? 1024 : undefined)
+  // `Number.isFinite` does not coerce, so it already rejects `undefined` — no
+  // separate `typeof === 'number'` guard needed.
+  if (Number.isFinite(width)) params.set('w', String(width))
+  if (Number.isFinite(height)) params.set('h', String(height))
+
+  return `${path}?${params.toString()}`
+}

package/dist/chunk-27APPAJN.cjs

@@ -1,24 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
-
-// src/contexts/endpoints-runtime-context.tsx
-var _react = require('react');
-var EndpointsRuntimeContext = _react.createContext.call(void 0, null);
-function useEndpointsRuntime() {
-  return _react.useContext.call(void 0, EndpointsRuntimeContext);
-}
-function useRequiredEndpointsRuntime() {
-  const v = _react.useContext.call(void 0, 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;
-}
-
-
-
-
-
-exports.EndpointsRuntimeContext = EndpointsRuntimeContext; exports.useEndpointsRuntime = useEndpointsRuntime; exports.useRequiredEndpointsRuntime = useRequiredEndpointsRuntime;
-//# sourceMappingURL=chunk-27APPAJN.cjs.map

package/dist/chunk-27APPAJN.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-27APPAJN.cjs","../src/contexts/endpoints-runtime-context.tsx"],"names":[],"mappings":"AAAA,qFAAY;AACZ;AACA;ACqBA,8BAA0C;AAenC,IAAM,wBAAA,EAA0B,kCAAA,IAA2C,CAAA;AAO3E,SAAS,mBAAA,CAAA,EAA+C;AAC7D,EAAA,OAAO,+BAAA,uBAAkC,CAAA;AAC3C;AASO,SAAS,2BAAA,CAAA,EAAgD;AAC9D,EAAA,MAAM,EAAA,EAAI,+BAAA,uBAAkC,CAAA;AAC5C,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAIF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;ADlDA;AACA;AACE;AACA;AACA;AACF,gLAAC","file":"/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-27APPAJN.cjs","sourcesContent":[null,"'use client'\n\n/**\n * Endpoints runtime — sibling of ChatRuntime. Carries the API path\n * literals consumed by oss-lib components/hooks/utils so a host\n * application can override them (e.g. when running behind a reverse\n * proxy as `user1.openframe.ai` → `/api/mingo-guide/*`).\n *\n * The hub mounts `<HubRuntimeProvider>` at root with the\n * canonical hub paths; an embedded app mounts its own provider with\n * remapped paths. The pattern mirrors ChatRuntimeContext exactly:\n *\n *   - `useEndpointsRuntime()` returns null when no provider is mounted.\n *     For optional consumers that should gracefully no-op without one.\n *   - `useRequiredEndpointsRuntime()` throws on missing provider — for\n *     hooks/components that cannot function without endpoints.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<EndpointsRuntimeContext.Provider value={...}>` (e.g. React.useMemo).\n * Reference changes invalidate downstream effect dependency arrays and\n * trigger unnecessary re-fetches.\n */\n\nimport { createContext, useContext } from 'react'\n\nexport interface EndpointsRuntime {\n  /** GET active announcement (used by `<AnnouncementBar>` polling). */\n  announcementsUrl: string\n  accessCode: {\n    /** POST validate access code. */\n    validateUrl: string\n    /** POST consume / redeem access code after registration. */\n    consumeUrl: string\n  }\n  /** POST contact-form submission. */\n  contactUrl: string\n}\n\nexport const EndpointsRuntimeContext = createContext<EndpointsRuntime | null>(null)\n\n/**\n * Optional read — returns null when no provider is mounted. Use for\n * surfaces that should silently skip the fetch (e.g. announcement\n * polling on a page rendered outside the provider tree).\n */\nexport function useEndpointsRuntime(): EndpointsRuntime | null {\n  return useContext(EndpointsRuntimeContext)\n}\n\n/**\n * Strict variant — throws on missing provider. Use for consumers that\n * cannot function without an endpoint (form submission, code\n * validation). In tests/Storybook, wrap with the hub's\n * `<HubRuntimeProvider>` or a stub\n * `<EndpointsRuntimeContext.Provider value={mockedEndpoints}>`.\n */\nexport function useRequiredEndpointsRuntime(): EndpointsRuntime {\n  const v = useContext(EndpointsRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[endpoints-runtime] hook called outside an <EndpointsRuntimeContext.Provider>. ' +\n        'Hub: mount <HubRuntimeProvider> in your providers tree. ' +\n        'Embedded app: mount your own provider with proxied URLs at the tree root. ' +\n        'Tests/Storybook: wrap render() in <EndpointsRuntimeContext.Provider value={mocked}>.',\n    )\n  }\n  return v\n}\n"]}