@flamingo-stack/openframe-frontend-core 0.0.405 → 0.0.406-snapshot.20260711131925

package/dist/utils/ods-color-utils.d.ts

@@ -75,7 +75,8 @@ export declare function usePlatformColors(platform?: Platform): {
 };
 /**
  * Picks a near-black or near-white text color with adequate contrast on `hex`.
- * Uses Rec. 601 luminance.
+ * Thin wrapper over `pickReadableTextColor` (color-analysis.ts) — ONE
+ * light-or-dark decision formula (WCAG relative luminance) for the whole lib.
  */
 export declare function getReadableTextColor(hex: string): string;
 export declare const HEX_PATTERN: RegExp;

package/dist/utils/ods-color-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ods-color-utils.d.ts","sourceRoot":"","sources":["../../src/utils/ods-color-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ods-color-utils.d.ts","sourceRoot":"","sources":["../../src/utils/ods-color-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AACzE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE9E;;GAEG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAAqB,GAC7B,MAAM,GAAG,SAAS,CAGpB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAUlE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAa7C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAa5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAyB9F;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,IAAI,GAAG,MAAM,GAAG,QAAe,GACpC,MAAM,GAAG,SAAS,CAsCpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,QAAQ;;;;;;EAcpD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAoB9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAgCR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,QAAQ;;;;;;yBAU5B,aAAa,SAAS,MAAM,YAAY,YAAY;+BAE9C,QAAQ;qCACF,MAAM;EAE1C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAID,eAAO,MAAM,WAAW,QAAsB,CAAC;AAM/C,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAIhF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhE;AAgBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAgB7F;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAyB7F;;;;;;;;;;;;;;;;AAED,wBAcE"}

package/package.json

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

package/src/components/announcement-bar.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { X } from 'lucide-react';
 import { Button } from './ui/button';
 import { EntityIcon } from './icon-display';
@@ -9,7 +9,7 @@ import {
   isAnnouncementDismissed,
   clearLegacyAnnouncementCache,
 } from '../utils/announcement-storage';
-import type { AnnouncementBarProps, AnnouncementResponse } from '../types/announcement';
+import type { Announcement, AnnouncementBarProps, AnnouncementResponse } from '../types/announcement';
 import { getAppType } from '../utils/app-config';
 import { useEndpointsRuntime } from '../contexts/endpoints-runtime-context';
 import { useSelfFetch } from '../hooks/use-self-fetch';
@@ -71,6 +71,15 @@ export function AnnouncementBar({
   });
   const announcement = data?.announcement ?? null;
 
+  // Hold the last non-null announcement so DEACTIVATION (a revalidation that
+  // returns null) collapses with the same 1fr->0fr animation as dismissal
+  // instead of unmounting in place (a hard 44px jump).
+  const lastAnnouncementRef = useRef<Announcement | null>(initialAnnouncement ?? null);
+  useEffect(() => {
+    if (announcement) lastAnnouncementRef.current = announcement;
+  }, [announcement]);
+  const displayAnnouncement = announcement ?? lastAnnouncementRef.current;
+
   // Expanded (height) state — initial value is a pure function of props so
   // the SSR HTML and the hydration render agree for every cohort.
   const [expandedState, setExpandedState] = useState<boolean>(() => initialAnnouncement != null);
@@ -109,6 +118,10 @@ export function AnnouncementBar({
   const handleDismiss = () => {
     if (previewMode || !announcement) return;
     dismissAnnouncement(platform, announcement.id);
+    // Release focus BEFORE the wrapper goes aria-hidden — a focused descendant
+    // inside an aria-hidden subtree strands screen-reader focus (and Chrome
+    // refuses to apply the attribute).
+    (document.activeElement as HTMLElement | null)?.blur?.();
     setExpandedState(false);
   };
 
@@ -119,7 +132,9 @@ export function AnnouncementBar({
     // via location.href / window.open (stored XSS).
     let safeUrl: string;
     try {
-      const parsed = new URL(announcement.cta_url, window.location.origin);
+      // Resolve against the CURRENT page (not the origin) so path-relative and
+      // fragment CTAs keep their pre-guard semantics.
+      const parsed = new URL(announcement.cta_url, window.location.href);
       if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
       safeUrl = parsed.href;
     } catch {
@@ -130,10 +145,10 @@ export function AnnouncementBar({
       : (window.location.href = safeUrl);
   };
 
-  // Nothing to show (and nothing to animate around): render nothing. The
-  // dismissed/deactivated case keeps the element mounted at 0fr so the
-  // collapse animates.
-  if (!announcement) return null;
+  // Never had anything to show: render nothing. Dismissal AND deactivation
+  // keep the element mounted (displayAnnouncement holds the last content) at
+  // 0fr so the collapse animates.
+  if (!displayAnnouncement) return null;
 
   // Contrast is solved with the ODS THEME system, not color literals: the
   // admin background's tone selects which ODS theme scopes the bar's content
@@ -141,7 +156,7 @@ export function AnnouncementBar({
   // dark-toned needs the dark theme's). `.theme-light` / `.theme-dark` are
   // the design system's own scoping classes (ods-colors.css) and flip every
   // Tier-1 `--ods-*` primitive for descendants.
-  const themeScope = pickReadableTextColor(announcement.background_color) === 'dark' ? 'theme-light' : 'theme-dark';
+  const themeScope = pickReadableTextColor(displayAnnouncement.background_color) === 'dark' ? 'theme-light' : 'theme-dark';
 
   // Inside the scope, colors reference Tier-1 theme primitives directly
   // (Tier-2 `--color-*` aliases resolve once at :root and do NOT re-resolve
@@ -152,7 +167,7 @@ export function AnnouncementBar({
   const barButtonClasses =
     'text-[color:var(--ods-system-greys-white)] hover:bg-[var(--ods-system-greys-black-hover)] active:bg-[var(--ods-system-greys-black-action)]';
 
-  const hasCta = Boolean(announcement.cta_enabled && announcement.cta_url);
+  const hasCta = Boolean(displayAnnouncement.cta_enabled && displayAnnouncement.cta_url && displayAnnouncement.cta_text);
 
   return (
     <div
@@ -171,9 +186,11 @@ export function AnnouncementBar({
         compact CTA on the right, and a ghost-icon dismiss (design-system
         icon-sm: 32px target, >= the 24px WCAG 2.2 SC 2.5.8 AA floor).
       */}
-      <div className={`min-h-0 overflow-hidden ${themeScope}`} style={{ backgroundColor: announcement.background_color }}>
+      <div className={`min-h-0 overflow-hidden ${themeScope}`} style={{ backgroundColor: displayAnnouncement.background_color }}>
         <div className="flex items-center w-full max-w-full min-h-11 text-[color:var(--ods-system-greys-white)]">
-          {/* Mobile: Clickable content area, Desktop: Regular content */}
+          {/* Mobile: whole-bar tap target (touch-first by design; the CTA
+              Button below is the keyboard/AT path and is CSS-hidden < md —
+              known tradeoff carried from the original bar). */}
           <div
             className={`flex flex-row gap-2 md:gap-3 items-center pl-4 md:pl-6 py-1.5 flex-1 min-w-0 ${
               hasCta ? 'md:cursor-default cursor-pointer' : ''
@@ -190,9 +207,9 @@ export function AnnouncementBar({
                 wins, else a library glyph by name (+ props), via <EntityIcon>. */}
             <EntityIcon
               icon={{
-                name: announcement.icon_name || 'openframe-logo',
-                url: announcement.icon_url,
-                props: announcement.icon_props,
+                name: displayAnnouncement.icon_name || 'openframe-logo',
+                url: displayAnnouncement.icon_url,
+                props: displayAnnouncement.icon_props,
               }}
               size={24}
               className="relative shrink-0 w-5 h-5 md:w-6 md:h-6"
@@ -202,9 +219,9 @@ export function AnnouncementBar({
                 truncating as one unit. Separator is a middot (house rule: no
                 en/em dashes in copy). */}
             <p className="font-body flex-1 min-w-0 max-w-full text-[13px] md:text-sm leading-snug truncate mb-0">
-              <span className="font-semibold">{announcement.title}</span>
-              {announcement.description && (
-                <span className="hidden sm:inline opacity-80"> · {announcement.description}</span>
+              <span className="font-semibold">{displayAnnouncement.title}</span>
+              {displayAnnouncement.description && (
+                <span className="hidden sm:inline opacity-80"> · {displayAnnouncement.description}</span>
               )}
             </p>
 
@@ -214,7 +231,7 @@ export function AnnouncementBar({
                 admin color. The admin cta_button_* colors are NOT applied:
                 they were designed for the legacy bespoke treatment. Hidden
                 on mobile, where the whole bar is the tap target. */}
-            {hasCta && announcement.cta_text && (
+            {hasCta && displayAnnouncement.cta_text && (
               <div className="hidden md:flex flex-shrink-0 ml-1">
                 <Button
                   onClick={handleCtaClick}
@@ -223,10 +240,10 @@ export function AnnouncementBar({
                   className={barButtonClasses}
                   tabIndex={expanded ? 0 : -1}
                   leftIcon={
-                    announcement.cta_show_icon && announcement.cta_icon_name
+                    displayAnnouncement.cta_show_icon && displayAnnouncement.cta_icon_name
                       ? (
                           <EntityIcon
-                            icon={{ name: announcement.cta_icon_name, props: announcement.cta_icon_props }}
+                            icon={{ name: displayAnnouncement.cta_icon_name, props: displayAnnouncement.cta_icon_props }}
                             size={14}
                             className="w-3.5 h-3.5"
                           />
@@ -234,7 +251,7 @@ export function AnnouncementBar({
                       : undefined
                   }
                 >
-                  {announcement.cta_text}
+                  {displayAnnouncement.cta_text}
                 </Button>
               </div>
             )}

package/src/components/features/video.tsx

@@ -892,6 +892,14 @@ function YouTubeFacadeInner({
           src={embedUrl}
           allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
           allowFullScreen
+          // YouTube verifies the embedding domain from the Referer header. When the
+          // host page runs under a strict `Referrer-Policy: no-referrer` (common on
+          // deployed environments behind a gateway/CDN), the iframe would otherwise
+          // inherit it, send no referrer, and YouTube rejects playback with
+          // "Error 153 — Video player configuration error". Pin the policy to the
+          // value YouTube's own recommended embed code uses so the origin is always
+          // sent and embedding is authorized.
+          referrerPolicy="strict-origin-when-cross-origin"
           title={title}
           className="absolute inset-0 w-full h-full border-0 rounded-lg"
         />

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

@@ -24,7 +24,7 @@
 import { createContext, useContext } from 'react'
 
 export interface EndpointsRuntime {
-  /** GET active announcement (used by `<AnnouncementBar>` polling). */
+  /** GET active announcement (used by `<AnnouncementBar>` mount fetch + refocus revalidation). */
   announcementsUrl: string
   accessCode: {
     /** POST validate access code. */

package/src/hooks/use-self-fetch.ts

@@ -112,6 +112,13 @@ export function useSelfFetch<T>(
     // `url` folds in every query param; `reloadKey` drives retry.
   }, [url, reloadKey])
 
+  // ONE force-refetch mechanic shared by reload() and the visibility
+  // revalidation: clear the held-url skip, bump the effect key.
+  const forceReload = () => {
+    dataUrlRef.current = null
+    setReloadKey((k) => k + 1)
+  }
+
   // Opt-in visibility-driven revalidation. Registered only when the option is
   // set and fetching is enabled; SSR-safe (effects don't run on the server)
   // and StrictMode-safe (idempotent listener, cleaned up per mount cycle).
@@ -120,9 +127,7 @@ export function useSelfFetch<T>(
     const onVisible = () => {
       if (document.visibilityState !== 'visible') return
       if (Date.now() - dataAtRef.current < revalidateOnVisibleAfterMs) return
-      // Same mechanics as reload(): clear the held-url skip, bump the key.
-      dataUrlRef.current = null
-      setReloadKey((k) => k + 1)
+      forceReload()
     }
     document.addEventListener('visibilitychange', onVisible)
     return () => document.removeEventListener('visibilitychange', onVisible)
@@ -133,11 +138,7 @@ export function useSelfFetch<T>(
     setData,
     isLoading,
     error,
-    // Force a re-fetch of the current url: clear the held-url ref so the skip above
-    // doesn't short-circuit, then bump the effect key.
-    reload: () => {
-      dataUrlRef.current = null
-      setReloadKey((k) => k + 1)
-    },
+    // Force a re-fetch of the current url (error-retry affordance).
+    reload: forceReload,
   }
 }

package/src/stories/AnnouncementBar.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/nextjs-vite'
 import type { Announcement } from '../types/announcement'
 import { AnnouncementBar } from '../components/announcement-bar'
-import { announcementDismissCookieName } from '../utils/announcement-storage'
+import { clearAnnouncementDismissals } from '../utils/announcement-storage'
 import { getAppType } from '../utils/app-config'
 import { EndpointsRuntimeContext, type EndpointsRuntime } from '../contexts/endpoints-runtime-context'
 
@@ -12,13 +12,7 @@ import { EndpointsRuntimeContext, type EndpointsRuntime } from '../contexts/endp
  * by a previous interaction so every story starts visible.
  */
 function clearDismissals() {
-  const platform = getAppType()
-  document.cookie = `${announcementDismissCookieName(platform)}=; path=/; max-age=0`
-  Object.keys(localStorage).forEach((key) => {
-    if (key.includes('-announcement-') && key.endsWith('-dismissed')) {
-      localStorage.removeItem(key)
-    }
-  })
+  clearAnnouncementDismissals(getAppType())
 }
 
 const now = new Date().toISOString()
@@ -110,7 +104,7 @@ export const WithCTASameTab: Story = {
 }
 
 /**
- * Dark background — text flips to the light shade via pickReadableTextColor.
+ * Dark background: text flips to the light shade via pickReadableTextColor.
  */
 export const DarkBackground: Story = {
   args: {
@@ -217,7 +211,7 @@ export const LongContent: Story = {
 }
 
 /**
- * previewMode — the admin live-preview path: render-only, inert dismiss,
+ * previewMode, the admin live-preview path: render-only, inert dismiss,
  * no fetch and no storage side effects.
  */
 export const PreviewMode: Story = {
@@ -233,7 +227,7 @@ export const PreviewMode: Story = {
 }
 
 /**
- * No active announcement — the bar renders nothing.
+ * No active announcement: the bar renders nothing.
  */
 export const NoAnnouncement: Story = {
   args: { initialAnnouncement: null },
@@ -241,8 +235,8 @@ export const NoAnnouncement: Story = {
     (Story) => (
       <div>
         <Story />
-        <p className="p-4 text-sm text-gray-500">
-          No announcement is active — the bar renders nothing above this text.
+        <p className="p-4 text-sm text-ods-text-secondary">
+          No announcement is active. The bar renders nothing above this text.
         </p>
       </div>
     ),
@@ -250,7 +244,7 @@ export const NoAnnouncement: Story = {
 }
 
 /**
- * Client-only mode (no SSR) — the react-embedding-example structure: the
+ * Client-only mode (no SSR), the react-embedding-example structure: the
  * embedder mounts an EndpointsRuntime provider (announcementsUrl is a fixed
  * suffix under its one content base) and drops in a PROP-LESS bar. No
  * platform knob anywhere on the client: the proxied server resolves its own

package/src/types/announcement.ts

@@ -220,14 +220,6 @@ export interface AnnouncementValidation {
 // Import unified platform configuration (removed duplicate definition)
 export type { PlatformConfig } from './platform';
 
-// Admin Dashboard Types
-export interface AnnouncementStats {
-  total_announcements: number;
-  active_announcements: number;
-  announcements_by_platform: Record<LegacyPlatform, number>;
-  recent_announcements: Announcement[];
-}
-
 // Component Props Types
 export interface AnnouncementBarProps {
   /**

package/src/utils/announcement-storage.ts

@@ -70,6 +70,23 @@ export function isAnnouncementDismissed(platform: string, id: string): boolean {
   }
 }
 
+/** Remove ALL dismissal state for a platform (cookie + legacy localStorage
+ *  keys) — test/story helper so callers never restate the key encoding. */
+export function clearAnnouncementDismissals(platform: string): void {
+  if (typeof document === 'undefined') return
+  document.cookie = `${announcementDismissCookieName(platform)}=; path=/; max-age=0`
+  try {
+    const prefix = `${platform}-announcement-`
+    Object.keys(localStorage).forEach((key) => {
+      if (key.startsWith(prefix) && key.endsWith('-dismissed')) {
+        localStorage.removeItem(key)
+      }
+    })
+  } catch {
+    // ignore storage errors
+  }
+}
+
 /** One-time cleanup of pre-refactor storage: the orphaned announcement cache
  *  (the old "instant paint" blob) — called from the bar's mount effect. */
 export function clearLegacyAnnouncementCache(platform: string): void {

package/src/utils/app-config.ts

@@ -19,8 +19,9 @@ export function getAppType() {
   // The exact `process.env.NEXT_PUBLIC_APP_TYPE` member expression is kept so
   // Next/webpack can statically inline it. The try/catch makes the call safe
   // in non-Next React hosts (Vite/CRA embeds) where `process` does not exist
-  // at runtime — those hosts fall back to 'openmsp' or pass an explicit
-  // platform where it matters (e.g. AnnouncementBar's `platform` prop).
+  // at runtime — those hosts get the 'openmsp' fallback, which is fine for
+  // embeds: dismissal cookies are domain-scoped and an embed domain serves
+  // one platform's announcements.
   try {
     return process.env.NEXT_PUBLIC_APP_TYPE || 'openmsp';
   } catch {

package/src/utils/color-analysis.ts

@@ -17,7 +17,10 @@ export const DESIGN_PALETTE: ColorPalette[] = [
  * Convert hex color to RGB
  */
 export function hexToRgb(hex: string): [number, number, number] {
-  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  // Expand shorthand (#fc0 -> #ffcc00) so legacy/hand-entered values classify
+  // by their real color instead of falling through to black.
+  const normalized = hex.replace(/^#?([a-f\d])([a-f\d])([a-f\d])$/i, (_, r, g, b) => `${r}${r}${g}${g}${b}${b}`);
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(normalized);
   return result
     ? [parseInt(result[1], 16), parseInt(result[2], 16), parseInt(result[3], 16)]
     : [0, 0, 0];
@@ -26,7 +29,7 @@ export function hexToRgb(hex: string): [number, number, number] {
 /**
  * Calculate relative luminance for contrast calculations
  */
-export function getLuminance(rgb: [number, number, number]): number {
+function getLuminance(rgb: [number, number, number]): number {
   const [r, g, b] = rgb.map(c => {
     c = c / 255;
     return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);

package/src/utils/ods-color-utils.ts

@@ -4,6 +4,7 @@
  * Provides runtime utilities for working with ODS color tokens
  */
 
+import { pickReadableTextColor } from './color-analysis';
 import { colorTokens as odsTokens } from './ods-color-tokens-stub';
 
 export type Platform = 'openmsp' | 'openframe' | 'flamingo';
@@ -292,15 +293,11 @@ export function usePlatformColors(platform?: Platform) {
 
 /**
  * Picks a near-black or near-white text color with adequate contrast on `hex`.
- * Uses Rec. 601 luminance.
+ * Thin wrapper over `pickReadableTextColor` (color-analysis.ts) — ONE
+ * light-or-dark decision formula (WCAG relative luminance) for the whole lib.
  */
 export function getReadableTextColor(hex: string): string {
-  const n = parseInt(hex.replace('#', ''), 16)
-  const r = (n >> 16) & 0xff
-  const g = (n >> 8) & 0xff
-  const b = n & 0xff
-  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
-  return luminance > 0.5 ? '#212121' : '#fafafa'
+  return pickReadableTextColor(hex) === 'dark' ? '#212121' : '#fafafa'
 }
 
 // Hex <-> RGB <-> HSL. Hex is #rrggbb lowercase; hexToRgb returns null on invalid.

package/dist/chunk-3KEBI6TP.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-3KEBI6TP.cjs","../src/contexts/endpoints-runtime-context.tsx","../src/contexts/chat-runtime-context.tsx"],"names":["createContext","useContext"],"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;AEiBA;AA0MO,IAAM,mBAAA,EAAqBA,kCAAAA,IAAsC,CAAA;AAQjE,SAAS,cAAA,CAAA,EAAqC;AACnD,EAAA,OAAOC,+BAAAA,kBAA6B,CAAA;AACtC;AAUO,SAAS,sBAAA,CAAA,EAAsC;AACpD,EAAA,MAAM,EAAA,EAAIA,+BAAAA,kBAA6B,CAAA;AACvC,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAMF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;AF7OA;AACA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,mUAAC","file":"/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-3KEBI6TP.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","'use client'\n\n/**\n * Chat runtime context — single seam for embedding the chat panel in a\n * different host (e.g. user1.openframe.ai reverse-proxying API calls\n * under /api/mingo-guide/* to hub.openframe.ai/api/*).\n *\n * Three concerns, one context:\n *   1. API endpoints: chatStreamUrl / approvalToolUrl / commandsUrl /\n *      buildListUrl + attachment endpoints + chat-identity. The chat\n *      reads them from runtime; hub vs embedded app supply different\n *      strings via different providers.\n *   2. Navigation mode + callbacks: 'host' or 'embed' mode. Host wires\n *      its own router/docNav via the optional `navigate` callback\n *      (plain function, NOT a hook); embed forces new-tab via\n *      `defaultContentOrigin` + lib's `resolveExternalNavigation`.\n *   3. Identity context: only `source` (required for localStorage\n *      namespacing). The display identity (greeting first-name etc.)\n *      comes from the server via `useChatIdentity()` — never injected\n *      client-side, so it always matches the server-resolved auth.\n *\n * Sibling of EndpointsRuntimeContext (announcement bar, contact form,\n * access codes). Each runtime stays an independent React context so\n * embedders can opt into either feature without forcing the other.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<ChatRuntimeContext.Provider value={...}>` (e.g. via React.useMemo).\n * Every change to its reference identity invalidates downstream\n * `useMemo` consumers (the chat input's slash-commands binding,\n * useNavLink's embed-resolution memo, useDocChat's streamFn factory).\n * The hub's `<HubRuntimeProvider>` already memoizes correctly with\n * stable deps. Embedded apps that build the value inline on each render\n * will pay an avoidable re-render cost across the entire chat tree.\n */\n\nimport { createContext, useContext, type ReactNode } from 'react'\n\nimport type { ComposeContentUrl } from '../utils/content-href'\n\n/**\n * Runtime config consumed by the chat panel.\n */\nexport interface ChatRuntime {\n  endpoints: {\n    /** POST streaming chat. Hub: '/api/docs/chat'. */\n    chatStreamUrl: string\n    /** POST agent approve/reject. Hub: '/api/chat/agent/confirm-tool'. */\n    approvalToolUrl: string\n    /** Customer-ticket agent endpoints (Help Center). OPTIONAL — when unset,\n     *  the ticket hooks fall back to the bare hub paths\n     *  (`/api/chat/agent/{find-ticket,ticket-action,list-engagements}`).\n     *  Embedders behind a reverse proxy set these to their proxied paths\n     *  (e.g. `/content/api/chat/agent/...`) so tickets route through the SAME\n     *  endpoint config + proxy as every other endpoint. */\n    findTicketUrl?: string\n    ticketActionUrl?: string\n    listEngagementsUrl?: string\n    /** GET slash-command catalog. Hub: '/api/docs/commands'. */\n    commandsUrl: string\n    /** GET RAG-search endpoint behind `<DocSearchBar>` (the in-source search\n     *  bar mounted by `<DocViewer>` / `<DocsHubPage>` when `showAIChat` is on).\n     *  Hub: '/api/docs/search'. OPTIONAL — falls back to the hub path so\n     *  same-origin Next.js hosts don't need to set it. Cross-origin embedders\n     *  set their proxied path so the search bar routes through the same\n     *  reverse proxy as everything else. Same pattern as `findTicketUrl`. */\n    docsSearchUrl?: string\n    /** POST internal-link resolver. The in-source markdown renderer (lib or\n     *  custom) calls `<DocViewer>`'s `handlers.onResolveLink(href, currentPath)`\n     *  for relative hrefs like `./getting-started/intro.md` — that callback\n     *  posts to this URL with `{ link, currentPath, source }` and expects a\n     *  `ResolveLinkResult` back. Hub: '/api/docs/resolve-link'. OPTIONAL — same\n     *  fall-back chain as `docsSearchUrl`: prop override → runtime → default. */\n    docsResolveLinkUrl?: string\n    /** GET per-platform empty-state config (admin-edited in\n     *  `/admin/chat-config`): `{ greeting, enabledRagTableIds, suggestedQueries }`.\n     *  Hub: '/api/docs/empty-state'. OPTIONAL — the in-app (host-mode) chat\n     *  injects these values as SSR props instead, so it leaves this unset.\n     *  Cross-origin EMBEDDERS (no server hop) set it to their proxied path\n     *  (e.g. '/content/api/docs/empty-state') so `<EmbeddableChat>` can fetch\n     *  the greeting / quick-action chips / RAG-source filter at runtime. When\n     *  unset, the chat falls back to the explicit `emptyStateGreeting` /\n     *  `suggestedQueries` / `enabledRagTableIds` props (or in-code defaults). */\n    emptyStateUrl?: string\n    /** Build the per-agent display-config URL for an OpenFrame AI agent\n     *  (Fae/Mingo). OPTIONAL. The returned endpoint MUST be byte-compatible\n     *  with the empty-state wire shape ({ greeting, suggestedQueries,\n     *  enabledRagTableIds }). When set AND `EmbeddableChat` receives an\n     *  `activeAgentSlug` in embed mode, the chat fetches THIS url instead of\n     *  `emptyStateUrl` to render the selected agent's greeting + suggested\n     *  prompts (the \"agent mode\" URL override). Hub: `(slug) =>\n     *  '/api/ai-agents/' + encodeURIComponent(slug)`. */\n    aiAgentConfigUrl?: (slug: string) => string\n    /** Build entity-card list URL for a content type + ids. Hub delegates\n     *  to the rag-table-config registry; embedded app provides its own\n     *  per-type URL builder against the reverse proxy. Returns null when\n     *  the type has no list endpoint (caller skips rendering). */\n    buildListUrl: (type: string, ids: string[]) => string | null\n    /** Chat-attachment endpoints — added for the v2 attachment feature.\n     *\n     *  Three concerns:\n     *    - `attachmentUploadUrl` — POSTed by the chat-attachment hook\n     *      to mint a Supabase signed-upload-URL + HMAC view token.\n     *    - `attachmentViewUrlPrefix` — embedded in markdown URLs the\n     *      chat hosts in user message bubbles (`![]()` / `[Attached]`).\n     *      Stored in chat history; chosen at SEND time. In host mode the\n     *      relative `/api/storage/view/chat-attachments/` is sufficient\n     *      (same-origin); embedders supply an absolute hub URL so the\n     *      browser can fetch cross-origin.\n     *    - `identityUrl` — GET endpoint the `useChatIdentity` hook\n     *      hits to learn the `{authTier, source, attachmentsEnabled}`\n     *      capability bag for the current session. Used beyond chat\n     *      (tickets / contact form / any embedded surface that needs\n     *      to identify the proxied customer), so the name has no\n     *      \"chat\" prefix even though the consuming hook still does. */\n    attachmentUploadUrl: string\n    attachmentViewUrlPrefix: string\n    identityUrl: string\n    /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).\n     *  When unset, lib's `getProxiedImageUrl` returns the original URL\n     *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't\n     *  host an image-proxy route leave this undefined → images load\n     *  directly cross-origin (CORS-permitting). */\n    imageProxyUrlPrefix?: string\n    /** Optional list of hostnames that should bypass the image proxy\n     *  (rendered direct). Hub uses ['openmsp.ai']; embedders typically\n     *  leave it unset. Matches the `skipDomains` parameter of\n     *  `getProxiedImageUrl`. */\n    imageProxySkipDomains?: string[]\n    /** Optional base URL for the branded og-placeholder image route — the\n     *  DEFAULT cover-image fallback for entity cards with no image. The lib\n     *  appends `?title=…` (+ `w`/`h` for square slots) itself, so this is\n     *  the base, NOT a full URL: relative (`/api/og-placeholder`) for same-\n     *  origin hosts, or the proxied path (`/content/api/og-placeholder`) for\n     *  cross-origin embedders. May carry baked-in query params (preserved when\n     *  the lib layers `title`/dimensions on top) — but per-platform brand\n     *  colors are NO LONGER baked here; the `/api/og-placeholder` route\n     *  resolves them server-side from the platform. Most hosts leave this unset\n     *  and let the lib derive the base from `imageProxyUrlPrefix`.\n     *\n     *  OPTIONAL — when unset the lib derives the base from the sibling\n     *  `imageProxyUrlPrefix` (same API base, route name swapped), then falls\n     *  back to the relative `/api/og-placeholder`. So an embedder that already\n     *  proxies images needs NO og-placeholder wiring. See\n     *  `resolveOgPlaceholderBase` / `buildOgPlaceholderUrl` in `../utils`. */\n    ogPlaceholderUrl?: string\n    /** Supabase storage origin (e.g. `https://xyz.supabase.co`) — used\n     *  by `useVideoWarmup` to scope the `<link rel=\"preload\" as=\"video\">`\n     *  hint to MP4s the deployment actually hosts. Hub wires it via\n     *  `getSupabaseStorageOrigin()`; embedders without a Supabase\n     *  storage origin leave it unset (preload is then skipped; Mux/\n     *  YouTube preconnect still fires). */\n    supabaseStorageOrigin?: string\n  }\n  navigation: {\n    /** ONE knob, two behaviors:\n     *  - 'host' = use the host page's existing click-routing untouched.\n     *    The chat panel calls `navigate?.()` for in-app routing.\n     *  - 'embed' = guest inside another app: short-circuit at the top\n     *    of click handlers to force new-tab + absolutize via\n     *    resolveExternalNavigation. */\n    mode: 'host' | 'embed'\n    /** Embed-only fallback origin for relative URLs whose target platform\n     *  can't be inferred. Used by resolveExternalNavigation when\n     *  `targetPlatform` is null — without this, a relative `/foo` href would\n     *  window.open against the embedder's origin, which is WRONG.\n     *  Set to your content host (e.g. 'https://hub.openframe.ai').\n     *  Required by the embedded app whenever mode='embed'. */\n    defaultContentOrigin?: string\n    /** Override for opening external URLs. MUST BE SYNCHRONOUS —\n     *  Safari/Firefox block popups opened outside a direct user gesture.\n     *  Default: window.open(href, '_blank', 'noopener,noreferrer'). */\n    openExternal?: (href: string) => void\n    /** Optional in-app navigation callback (host-mode only).\n     *  Returns `true` if the host handled the click in-app\n     *  (router.push + docNav.navigate); returns `false`, `undefined`,\n     *  or `void` → lib falls back to window.location.assign(href).\n     *  Hub wires this via HubRuntimeProvider's HubNavigationWiring;\n     *  embedders not in Next.js leave it undefined. */\n    navigate?: (input: { href: string; path?: string | null; targetPlatform?: string | null }) => boolean | void\n    /** Optional new-tab decision callback. Returns true → lib opens in\n     *  new tab; false → same tab via `navigate`. Hub wires the existing\n     *  `decideNewTab` logic from use-nav-link.tsx (re-imports the pure\n     *  helper from lib). Embedders may omit; lib defaults to:\n     *  same-origin/same-platform → same tab, else new tab. */\n    decideNewTab?: (args: { href: string; targetPlatform?: string | null }) => boolean\n  }\n  /** Optional content-URL composer. Returns the platform-aware href +\n   *  target-platform tuple for a content entity. Hub wires this to its\n   *  `buildContentURL(type, slug, extractPrimaryPlatform(platforms))`\n   *  pipeline so the lib catalog/detail views can derive cross-\n   *  platform hrefs without knowing the hub's platform topology\n   *  (openmsp.ai / openframe.app / flamingo.run / tmcg).\n   *\n   *  THE single content-href authority for every embeddable surface — page\n   *  views (onboarding catalog/detail, releases) AND chat cards / chips /\n   *  search results all resolve content links through this one seam, so a\n   *  given type lands in the SAME place regardless of where it's rendered.\n   *  Embedders wire `makeComposeContentUrl({ hostedTypes, contentOrigin })`;\n   *  omit it and lib views fall back to a same-origin relative path\n   *  (`buildDefaultHref`).\n   *\n   *  Takes a single `ComposeContentUrlInput`: `type` + `identifier` (page\n   *  views pass the slug; chat rows pass the id + `externalUrl`, whose path\n   *  yields the slug for in-app routing) + optional `platforms` /\n   *  `externalUrl` / `targetPlatform`. */\n  composeContentUrl?: ComposeContentUrl\n  /** Per-`documentType` doc-viewer targets — the UNIFIED, DYNAMIC replacement for\n   *  the single `chipBasePlatform` prop. Maps a doc-table documentType\n   *  (`'markdown'`, `'data_room_doc'`, …) → `{ platform, basePath }` for the PUBLIC\n   *  doc viewer that hosts it. Doc chips with no `externalUrl` resolve PER ROW to\n   *  `getBaseUrl(platform)/<basePath>/<path>`, so a chat mixing several doc sources\n   *  sends EACH to its own home (markdown→flamingo/knowledge-base,\n   *  data_room_doc→company-hub/data-room) instead of one static fallback. The hub\n   *  may keep using `chipBasePlatform` (one doc source per platform); embedders that\n   *  surface multiple doc sources wire this. Threaded into `resolveSourceRowCTA`. */\n  docPlatformTargets?: Record<string, { platform: string; basePath: string }>\n  /** Chat source / platform identifier — OPTIONAL. The hub sets it from\n   *  `currentPlatform()`; EMBEDDERS leave it unset and stay platform-agnostic.\n   *\n   *  It is NOT required for chat to work. The wire resolves source server-side\n   *  (`/docs/chat|search|commands` reject any client `source`); the\n   *  same-tab-vs-new-tab link decision falls back to an origin comparison when\n   *  it's absent (`decideNewTab` → `isCrossOriginUrl`); and the localStorage\n   *  history namespace falls back to a stable constant. Set it only where the\n   *  client legitimately needs to know its platform a priori — i.e. the hub,\n   *  where several platforms share related origins so \"same platform\" can't be\n   *  inferred from a URL alone. */\n  source?: string\n  // NOTE: No `user` field. The chat's display identity (greeting\n  // first-name, etc.) comes from the SERVER-resolved auth via\n  // `useChatIdentity()` — the same identity the server uses to\n  // authorize requests. Letting embedders pass a client-side `user`\n  // would let it desync from the actual auth tier, causing greetings\n  // like \"Hey Bob\" while the server treats the session as\n  // alice@example.com. Single source of truth: the server.\n}\n\nexport const ChatRuntimeContext = createContext<ChatRuntime | null>(null)\n\n/**\n * Returns the active runtime, or null when no provider is mounted.\n * NULL is a first-class value — it signals \"no chat runtime configured.\"\n * Optional consumers fall back to no-op behavior; strict consumers\n * use `useRequiredChatRuntime` (below).\n */\nexport function useChatRuntime(): ChatRuntime | null {\n  return useContext(ChatRuntimeContext)\n}\n\n/**\n * Strict variant used INSIDE the chat panel. Throws if no provider.\n * The hub guarantees one exists by mounting `<HubRuntimeProvider>` at\n * root; the embedded app mounts its own `<ChatRuntimeContext.Provider>`\n * at the tree root. In Jest / Storybook tests that render chat\n * internals directly, wrap with `<HubRuntimeProvider>` (hub defaults)\n * or supply `<ChatRuntimeContext.Provider value={mockedRuntime}>`.\n */\nexport function useRequiredChatRuntime(): ChatRuntime {\n  const v = useContext(ChatRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[chat-runtime] hook called outside a <ChatRuntimeContext.Provider>. ' +\n        'The hub mounts <HubRuntimeProvider> at root — this only fires when ' +\n        'chat internals are rendered above the provider tree. ' +\n        'Fix: ensure the rendering subtree descends from the runtime provider. ' +\n        'In tests/Storybook: wrap with <HubRuntimeProvider> or supply ' +\n        'a <ChatRuntimeContext.Provider value={mockedRuntime}>.',\n    )\n  }\n  return v\n}\n"]}