@flamingo-stack/openframe-frontend-core 0.0.218 → 0.0.219

package/src/utils/__tests__/list-url.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+import { buildListUrl } from '../list-url'
+
+/**
+ * Byte-parity gate for the shared `buildListUrl`.
+ *
+ * `BASELINE` is the FROZEN output of each hub RAG mapper's `listApi(['a','b'])`
+ * captured BEFORE the 12 mappers were switched to delegate here (verbatim from
+ * `lib/config/rag-mappers/*.ts` in multi-platform-hub). `buildListUrl` MUST
+ * reproduce each string exactly — any drift in a path or query param fails
+ * here, which is the whole point: the hub mappers delegate to this builder, so
+ * this test is the contract that keeps the hub's chat-card fetch URLs identical
+ * across the migration. (The hub side asserts the same baseline against its own
+ * `entity-list-api.buildListUrl` + `buildListBasePath`.)
+ */
+const BASELINE: Record<string, string> = {
+  roadmap_item: '/api/roadmap?task_ids=a,b',
+  delivery_item: '/api/delivery?task_ids=a,b',
+  internal_task: '/api/internal-tasks?task_ids=a,b',
+  blog_post: '/api/blog/posts?ids=a,b&pageSize=2',
+  webinar: '/api/programs/webinars?ids=a,b&limit=2&filter=all',
+  podcast: '/api/programs/podcasts?ids=a,b&limit=2&filter=all',
+  event: '/api/programs/events?ids=a,b&limit=2&filter=all',
+  onboarding_guide: '/api/onboarding-guides?ids=a,b&limit=2',
+  case_study: '/api/case-studies?ids=a,b&limit=2',
+  product_release: '/api/releases?ids=a,b&limit=2',
+  customer_interview: '/api/customer-interviews?ids=a,b&limit=2',
+  investor_update: '/api/investor-updates?ids=a,b&limit=2',
+}
+
+describe('buildListUrl — byte parity with the hub mappers', () => {
+  it.each(Object.entries(BASELINE))('%s → exact prior listApi output', (type, expected) => {
+    expect(buildListUrl(type, ['a', 'b'])).toBe(expected)
+  })
+
+  it('un-aliases blog_post_existing → blog_post (mirrors hub LEGACY_TYPE_ALIASES)', () => {
+    expect(buildListUrl('blog_post_existing', ['a', 'b'])).toBe(BASELINE.blog_post)
+  })
+
+  it('builds marketing_campaign via the literal admin case', () => {
+    expect(buildListUrl('marketing_campaign', ['a', 'b'])).toBe(
+      '/api/admin/marketing/campaigns?ids=a,b&pageSize=2',
+    )
+  })
+})
+
+describe('buildListUrl — base prefix (embedder reverse-proxy)', () => {
+  it('prepends a non-empty base to every builder', () => {
+    expect(buildListUrl('roadmap_item', ['a', 'b'], '/content')).toBe(
+      '/content/api/roadmap?task_ids=a,b',
+    )
+    expect(buildListUrl('blog_post', ['a', 'b'], '/content')).toBe(
+      '/content/api/blog/posts?ids=a,b&pageSize=2',
+    )
+    expect(buildListUrl('webinar', ['a', 'b'], '/content')).toBe(
+      '/content/api/programs/webinars?ids=a,b&limit=2&filter=all',
+    )
+    expect(buildListUrl('marketing_campaign', ['a', 'b'], '/content')).toBe(
+      '/content/api/admin/marketing/campaigns?ids=a,b&pageSize=2',
+    )
+  })
+
+  it('default base is empty (hub-relative)', () => {
+    expect(buildListUrl('product_release', ['a', 'b'])).toBe(
+      buildListUrl('product_release', ['a', 'b'], ''),
+    )
+  })
+})
+
+describe('buildListUrl — pageSize / limit track ids.length', () => {
+  it('single id', () => {
+    expect(buildListUrl('blog_post', ['x'])).toBe('/api/blog/posts?ids=x&pageSize=1')
+    expect(buildListUrl('case_study', ['x'])).toBe('/api/case-studies?ids=x&limit=1')
+  })
+  it('three ids', () => {
+    expect(buildListUrl('onboarding_guide', ['a', 'b', 'c'])).toBe(
+      '/api/onboarding-guides?ids=a,b,c&limit=3',
+    )
+  })
+})
+
+// Mirrors the hub's `entity-list-api.buildListBasePath` (probe an id, strip the
+// query) — that fn is unchanged hub code, so proving the bare path each builder
+// emits is stable here transitively proves `buildListBasePath` is unchanged.
+describe('buildListUrl — base-path derivation (covers hub buildListBasePath)', () => {
+  const BASE_PATHS: Record<string, string> = {
+    roadmap_item: '/api/roadmap',
+    delivery_item: '/api/delivery',
+    internal_task: '/api/internal-tasks',
+    blog_post: '/api/blog/posts',
+    webinar: '/api/programs/webinars',
+    podcast: '/api/programs/podcasts',
+    event: '/api/programs/events',
+    onboarding_guide: '/api/onboarding-guides',
+    case_study: '/api/case-studies',
+    product_release: '/api/releases',
+    customer_interview: '/api/customer-interviews',
+    investor_update: '/api/investor-updates',
+    marketing_campaign: '/api/admin/marketing/campaigns',
+  }
+  it.each(Object.entries(BASE_PATHS))('%s → %s', (type, base) => {
+    const url = buildListUrl(type, ['__probe__'])
+    expect(url).not.toBeNull()
+    const q = url!.indexOf('?')
+    expect(q < 0 ? url : url!.slice(0, q)).toBe(base)
+  })
+})
+
+describe('buildListUrl — null (no list endpoint)', () => {
+  it('empty ids → null', () => {
+    expect(buildListUrl('roadmap_item', [])).toBeNull()
+    expect(buildListUrl('marketing_campaign', [])).toBeNull()
+  })
+
+  // No-fetch types are ABSENT keys (not enumerated as null) — their absence
+  // IS the null. Guards against accidentally adding a builder for one.
+  it.each([
+    'github_commit',
+    'github_pr',
+    'github_review',
+    'slack_message',
+    'financial_kpi',
+    'markdown',
+    'data_room_doc',
+    'hubspot_ticket',
+    'unknown_type',
+  ])('%s → null', (type) => {
+    expect(buildListUrl(type, ['a', 'b'])).toBeNull()
+  })
+
+  it('prototype keys do not dispatch (hasOwnProperty guard)', () => {
+    expect(buildListUrl('constructor', ['a', 'b'])).toBeNull()
+    expect(buildListUrl('__proto__', ['a', 'b'])).toBeNull()
+    expect(buildListUrl('hasOwnProperty', ['a', 'b'])).toBeNull()
+  })
+})

package/src/utils/cn.ts

@@ -43,6 +43,13 @@ export function getPlatformProductionUrl(platform: string): string {
       return process.env.NEXT_PUBLIC_FLAMINGO_URL || 'https://www.flamingo.run';
     case 'openframe':
       return process.env.NEXT_PUBLIC_OPENFRAME_URL || 'https://openframe.ai';
+    // OpenFrame product / dashboard — the "Start Free Trial" CTA target. DISTINCT from
+    // the `openframe` content hub above: production overrides that one to
+    // hub.openframe.ai via NEXT_PUBLIC_OPENFRAME_URL (the knowledge/docs deployment),
+    // so a product CTA must NOT reuse it. Defaults to the product apex so the CTA is
+    // correct even when the (optional) dashboard override is unset.
+    case 'openframe-dashboard':
+      return process.env.NEXT_PUBLIC_OPENFRAME_DASHBOARD_URL || 'https://openframe.ai';
     case 'universal':
       return process.env.NEXT_PUBLIC_FLAMINGO_URL || 'https://www.flamingo.run';
     default:
@@ -142,6 +149,8 @@ export function getAllPlatformBaseDomains(): string[] {
  * - NEXT_PUBLIC_TMCG_URL             -> www.tmcg.miami
  * - NEXT_PUBLIC_FLAMINGO_TEASER_URL  -> www.flamingo.cx
  * - NEXT_PUBLIC_OPENFRAME_URL        -> openframe.ai
+ * - NEXT_PUBLIC_OPENFRAME_DASHBOARD_URL -> openframe.ai (product/dashboard CTA target;
+ *     distinct from the openframe content hub, which prod points at hub.openframe.ai)
  *
  * @example
  * getBaseUrl() // Current app URL

package/src/utils/content-href.ts

@@ -0,0 +1,180 @@
+/**
+ * The SINGLE content-href authority for every embeddable surface — the
+ * `ChatRuntime.composeContentUrl` seam. Page views (onboarding catalog/detail,
+ * product releases) AND chat surfaces (entity cards, source chips, search
+ * results) all resolve a content link through this one function, so a given
+ * content type lands in the SAME place no matter where it's rendered.
+ *
+ * ## Why this exists
+ *
+ * Before unification there were two link builders: `composeContentUrl` (pages)
+ * and `resolveSourceRowCTA` (chat), and only the former honored the embedder's
+ * in-app routing config — so the same `product_release` soft-navigated in-app on
+ * the releases page but opened OUT to the hub as a chat card. Now `resolveSource-
+ * RowCTA` delegates its href to this seam, so one config (`hostedTypes` /
+ * `overrides`) governs internal-vs-external for pages and chat alike.
+ *
+ * `makeComposeContentUrl` builds the embedder default from a small config: the
+ * set of types THIS host serves in-app (→ relative href, soft-navigates) vs.
+ * everything else (→ the canonical hub URL, opens out). The hub wires its own
+ * composer (`composeContentUrlFromPlatforms` — cross-platform topology) to the
+ * same seam. Pure + server-safe (no React, no browser APIs).
+ *
+ *   composeContentUrl: makeComposeContentUrl({
+ *     hostedTypes: new Set(['onboarding_guide', 'product_release']),
+ *     contentOrigin: VITE_HUB_ORIGIN,
+ *   })
+ */
+
+/**
+ * Type → in-app route suffix. The public-hostable subset of the hub's
+ * `PUBLIC_URL_PATHS` (`lib/utils/content-url-builder.ts`); the hub keeps
+ * its own copy, this is the embedder default and must stay in sync. (The
+ * cross-repo boundary makes a shared import impossible; the lib test pins this
+ * constant against a literal copy of itself, so it does NOT detect hub-side
+ * drift — values match today and are kept aligned by hand.)
+ */
+export const DEFAULT_CONTENT_SUFFIXES: Record<string, string> = {
+  onboarding_guide: 'onboarding-guides',
+  product_release: 'releases',
+  blog_post: 'blog',
+  case_study: 'case-studies',
+  customer_interview: 'interviews',
+  investor_update: 'investor-updates',
+  webinar: 'webinars',
+  podcast: 'podcasts',
+  event: 'events',
+}
+
+/** Input to the unified content-href seam. ONE object covers both callers:
+ *  page views pass `type` + `identifier` (the slug); chat rows pass `type` +
+ *  `identifier` (the primary-key id) + `externalUrl` (the canonical hub URL,
+ *  from which the slug is recovered for in-app routing). */
+export interface ComposeContentUrlInput {
+  /** The content's documentType (e.g. `'product_release'`, `'blog_post'`). */
+  type: string
+  /** Content identifier. Page views pass the slug; chat rows pass the
+   *  primary-key id (the slug is recovered from `externalUrl` when hosted). */
+  identifier: string
+  /** Hydrated platform junction (page views). Unused by the embedder default
+   *  — `hostedTypes` membership decides in-vs-out — but threaded for the hub
+   *  composer's cross-platform topology. */
+  platforms?: Array<{ name?: string }>
+  /** The canonical hub URL when the caller already has it (chat entity rows
+   *  carry it from the RAG mapper). Hosted types relativize it to an in-app
+   *  path; non-hosted types use it verbatim (authoritative). Absent for pages. */
+  externalUrl?: string | null
+  /** Platform that owns `externalUrl` (chat rows). Passed through on the
+   *  non-hosted branch. */
+  targetPlatform?: string | null
+}
+
+export interface ContentHrefOptions {
+  /** Types THIS host serves in-app → relative href (soft-nav). Everything
+   *  else resolves to the row's `externalUrl` / `contentOrigin` (opens out). */
+  hostedTypes: ReadonlySet<string>
+  /** Hub origin for non-hosted types with no `externalUrl` (e.g.
+   *  `https://openframe.app`). */
+  contentOrigin: string
+  /** Per-type route suffix. Defaults to {@link DEFAULT_CONTENT_SUFFIXES}. */
+  suffixes?: Record<string, string>
+  /** Per-type full override — wins over the suffix logic. Receives the same
+   *  `identifier` the seam was called with. */
+  overrides?: Record<string, (identifier: string) => { href: string; targetPlatform: string | null }>
+}
+
+/** The unified `composeContentUrl` seam shape on `ChatRuntime`. ALWAYS returns
+ *  a tuple (never null) — the seam type is non-nullable and callers read
+ *  `.href` unconditionally. */
+export type ComposeContentUrl = (
+  input: ComposeContentUrlInput,
+) => { href: string; targetPlatform: string | null }
+
+/** Last non-empty path segment of a URL (relative or absolute) — the content
+ *  slug of a canonical detail URL like `https://hub/releases/my-release`.
+ *  Returns `null` on a malformed URL or empty path. */
+function lastPathSegment(url: string): string | null {
+  try {
+    // Resolve against a dummy base so relative inputs parse too.
+    const pathname = new URL(url, 'https://_.local').pathname
+    const segs = pathname.split('/').filter(Boolean)
+    return segs.length > 0 ? segs[segs.length - 1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the embedder's `composeContentUrl` for the unified seam.
+ *
+ * Resolution order (the merged rule used by BOTH page views and chat cards):
+ *   1. `overrides[type]` — explicit per-type href.
+ *   2. `hostedTypes.has(type)` → relative `/<suffix>/<slug>` (in-app, soft-nav).
+ *      Chat rows carry the hub URL not the slug, so the slug is recovered from
+ *      `externalUrl`; page views pass the slug as `identifier`.
+ *   3. `externalUrl` present → use it verbatim (RAG-authoritative hub URL; the
+ *      chat non-hosted case).
+ *   4. else → `${contentOrigin}/<suffix>/<identifier>` (page-view non-hosted).
+ *
+ * In-vs-out is decided by `hostedTypes` membership — NOT platform equality,
+ * since an embedder has a free-form `source`. The `platforms` arg is part of the
+ * seam signature but unused here.
+ */
+export function makeComposeContentUrl(opts: ContentHrefOptions): ComposeContentUrl {
+  const suffixes = opts.suffixes ?? DEFAULT_CONTENT_SUFFIXES
+  return ({ type, identifier, externalUrl, targetPlatform }) => {
+    const override =
+      opts.overrides && Object.prototype.hasOwnProperty.call(opts.overrides, type)
+        ? opts.overrides[type]
+        : undefined
+    if (override) return override(identifier)
+
+    const seg =
+      (Object.prototype.hasOwnProperty.call(suffixes, type) ? suffixes[type] : undefined) ?? type
+
+    if (opts.hostedTypes.has(type)) {
+      // In-app (soft-nav). Recover the slug from the hub URL for chat rows;
+      // page views already pass the slug as `identifier`. Guard: if the recovered
+      // segment is the type's OWN suffix (e.g. a malformed/list externalUrl like
+      // `https://hub/releases/` → `'releases'`), fall back to `identifier` instead
+      // of emitting a nonsensical `/releases/releases`.
+      const recovered = externalUrl ? lastPathSegment(externalUrl) : null
+      const slug = recovered && recovered !== seg ? recovered : identifier
+      return { href: `/${seg}/${slug}`, targetPlatform: null }
+    }
+    // Not hosted → opens out. Prefer the RAG-authoritative `externalUrl` (chat);
+    // else compose against the hub origin (page views with no externalUrl).
+    return externalUrl
+      ? { href: externalUrl, targetPlatform: targetPlatform ?? null }
+      : { href: `${opts.contentOrigin}/${seg}/${identifier}`, targetPlatform: null }
+  }
+}
+
+/**
+ * Default href shape when `runtime.composeContentUrl` is NOT wired
+ * (single-platform embedders without cross-platform topology). Shared by
+ * every catalog/detail view that composes a content link (onboarding guides,
+ * product releases, …) so the no-composer fallback has ONE source — both
+ * views pass their `basePath`-derived shape through here.
+ */
+export function buildDefaultHref(
+  basePath: string,
+  slug: string,
+): { href: string; targetPlatform: string | null } {
+  return { href: `${basePath}/${slug}`, targetPlatform: null }
+}
+
+/**
+ * Resolve a content link via the host's `composeContentUrl` when wired, else the
+ * same-origin `buildDefaultHref` fallback — the exact ternary every catalog/detail page
+ * VIEW repeated. Centralizes the `composeContentUrl` input shape + the fallback in one
+ * place so a future input-shape change lands once, not per view.
+ */
+export function resolveContentHref(
+  composeContentUrl: ComposeContentUrl | undefined,
+  args: { type: string; slug: string; basePath: string; platforms?: ComposeContentUrlInput['platforms'] },
+): { href: string; targetPlatform: string | null } {
+  return composeContentUrl
+    ? composeContentUrl({ type: args.type, identifier: args.slug, platforms: args.platforms })
+    : buildDefaultHref(args.basePath, args.slug)
+}

package/src/utils/dev-sections/dev-section-param-keys.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical URL param keys for the dev-center sections — the ONE source for both:
+ *   - the chrome registry (`OPENFRAME_DEV_SECTIONS`), which WRITES `?<key>=…` to the URL, and
+ *   - the list views (`RoadmapView` / `ProductReleasesView` / `DeliveryLists`), which READ
+ *     `?<key>=…` to fetch the filtered list.
+ *
+ * The chrome and the view MUST agree on the key or filtering silently breaks. Importing
+ * from here (instead of re-declaring the literal in each place) makes that impossible to
+ * get wrong. Pure string constants — no React, no heavy deps — so both server-bundled
+ * utils and client views can import it freely.
+ */
+export const DEV_SECTION_PARAM_KEYS = {
+  /** Free-text search box — shared by every dev-center section. */
+  search: 'search',
+  /** Roadmap (and Help Center tickets) status filter. */
+  status: 'status',
+  /** Product-releases stability-tier filter. */
+  releaseStatus: 'release_status',
+  /** Delivery (bug-fix / enhancement) task-type filter. */
+  deliveryTaskType: 'task_type',
+} as const

package/src/utils/dev-sections/openframe-dev-sections.ts

@@ -30,6 +30,7 @@
 
 import { Map as MapIcon, Wrench, Rocket, GraduationCap, LifeBuoy, type LucideIcon } from 'lucide-react'
 import { releaseStatusOptions } from '../../types'
+import { DEV_SECTION_PARAM_KEYS } from './dev-section-param-keys'
 
 // Roadmap status options — `as const` preserves readonly tuple typing
 // across the registry boundary.
@@ -105,8 +106,8 @@ export const OPENFRAME_DEV_SECTIONS = {
       description:
         "See what's in flight, what's planned, and what's up for community vote. The entire OpenFrame roadmap is public.",
     },
-    search: { placeholder: 'Search roadmap items...', paramKey: 'search' },
-    filter: { label: 'Status', paramKey: 'status', defaultValue: 'all', options: ROADMAP_STATUS_OPTIONS },
+    search: { placeholder: 'Search roadmap items...', paramKey: DEV_SECTION_PARAM_KEYS.search },
+    filter: { label: 'Status', paramKey: DEV_SECTION_PARAM_KEYS.status, defaultValue: 'all', options: ROADMAP_STATUS_OPTIONS },
   },
   delivery: {
     href: '/bug-fixes-and-enhancements',
@@ -120,8 +121,8 @@ export const OPENFRAME_DEV_SECTIONS = {
       description:
         'A running log of fixes and improvements shipping into OpenFrame — recently completed and actively in progress.',
     },
-    search: { placeholder: 'Search tasks...', paramKey: 'search' },
-    filter: { label: 'Type', paramKey: 'task_type', defaultValue: 'all', options: DELIVERY_TASK_TYPE_OPTIONS },
+    search: { placeholder: 'Search tasks...', paramKey: DEV_SECTION_PARAM_KEYS.search },
+    filter: { label: 'Type', paramKey: DEV_SECTION_PARAM_KEYS.deliveryTaskType, defaultValue: 'all', options: DELIVERY_TASK_TYPE_OPTIONS },
   },
   releases: {
     href: '/releases',
@@ -135,8 +136,8 @@ export const OPENFRAME_DEV_SECTIONS = {
       description:
         'Version notes, change summaries, and stability tier (alpha / beta / stable) for every OpenFrame release.',
     },
-    search: { placeholder: 'Search releases...', paramKey: 'search' },
-    filter: { label: 'Status', paramKey: 'release_status', defaultValue: 'all', options: releaseStatusOptions },
+    search: { placeholder: 'Search releases...', paramKey: DEV_SECTION_PARAM_KEYS.search },
+    filter: { label: 'Status', paramKey: DEV_SECTION_PARAM_KEYS.releaseStatus, defaultValue: 'all', options: releaseStatusOptions },
   },
   onboarding: {
     href: '/onboarding-guides',
@@ -172,10 +173,10 @@ export const OPENFRAME_DEV_SECTIONS = {
       description:
         'Open new tickets, follow up on existing ones, and track responses from the team — all in one place.',
     },
-    search: { placeholder: 'Search your tickets...', paramKey: 'search' },
+    search: { placeholder: 'Search your tickets...', paramKey: DEV_SECTION_PARAM_KEYS.search },
     filter: {
       label: 'Status',
-      paramKey: 'status',
+      paramKey: DEV_SECTION_PARAM_KEYS.status,
       defaultValue: 'all',
       options: TICKET_STATUS_OPTIONS,
     },

package/src/utils/index.ts

@@ -6,7 +6,7 @@ export { cn, getAllPlatformBaseDomains } from './cn'
 export { formatDate, formatNumber, formatPrice, formatBytes } from './format'
 // SVG path constants — re-exported here (server-safe) because icons-v2 has "use client"
 export { PLAY_ICON_PATH } from '../components/icons-v2-generated/media-playback/play-icon'
-export { getPlatformAccentColor, getCurrentPlatform, type ColorCategory } from './ods-color-utils'
+export { getPlatformAccentColor, getCurrentPlatform, type ColorCategory, HEX_PATTERN } from './ods-color-utils'
 export { delay, generateRandomString, truncateString, deepClone, getSlackCommunityJoinUrl } from './common'
 export { getBaseUrl, getPlatformProductionUrl } from '../utils/cn'
 
@@ -20,6 +20,14 @@ export * from './validation-utils'
 export * from './confidence-helpers'
 // Release date formatting utilities
 export * from './date-formatters'
+// Product-release card helpers (lifted from the hub so every embedder gets the
+// rich card metadata): badge-color mapping + cover-image fallback resolution.
+export * from './release-badge'
+export * from './release-cover'
+// 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.
+export { DEV_SECTION_PARAM_KEYS } from './dev-sections/dev-section-param-keys'
 // Dynamic icon registry — single source of truth lives at
 // components/chat/utils/icon-registry. Re-exported here so existing
 // `@flamingo-stack/openframe-frontend-core/utils` callers (hub admin
@@ -216,3 +224,21 @@ export {
   type ScrollElementIntoViewOptions,
   scrollElementIntoView,
 } from './scroll-into-view'
+
+// Shared list-API URL builder — the single source for the per-type chat
+// entity-card fetch shapes. The hub's 12 RAG mapper `listApi` closures
+// delegate here (byte-parity test guards the migration); embedders wire
+// `endpoints.buildListUrl = (t, ids) => buildListUrl(t, ids, '/content')`.
+// Pure + server-safe (the hub imports it server-side from this barrel).
+export { buildListUrl } from './list-url'
+
+// Embedder-configurable content-URL composer for the existing
+// `runtime.composeContentUrl` seam — relative href for host-served types,
+// hub origin for the rest. Pure + server-safe.
+export {
+  DEFAULT_CONTENT_SUFFIXES,
+  makeComposeContentUrl,
+  buildDefaultHref,
+  type ContentHrefOptions,
+  type ComposeContentUrl,
+} from './content-href'

package/src/utils/list-url.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared list-API URL builder — the single un-replicable piece of the
+ * chat entity-card fetch path.
+ *
+ * ## Why this exists
+ *
+ * A fetch-mode entity card (`dispatch.tsx` → `useChatCardItem`) expands a
+ * compact `[card://<type>:<id>]` marker by fetching the type's public list
+ * endpoint with an `?ids=` (or `?task_ids=`) filter and matching the row
+ * back by id. The per-type URL SHAPE is non-obvious — `task_ids` for the
+ * ClickUp-backed types, `pageSize` for blog, `&limit=N&filter=all` for the
+ * programs trio, a distinct `/customer-interviews` path, etc. — and lives in
+ * the hub's 12 RAG mapper closures (`lib/config/rag-mappers/*.ts`). An
+ * embedder can't reverse-engineer those shapes, so a wrong/missing builder
+ * resolves a null URL ⇒ `enabled:false` ⇒ the card never fetches and renders
+ * nothing.
+ *
+ * This builder is the ONE source for those shapes. The hub's 12 mappers
+ * delegate their `listApi` here (a byte-parity test guards the migration),
+ * and embedders wire it once:
+ *
+ *   endpoints.buildListUrl = (type, ids) => buildListUrl(type, ids, '/content')
+ *
+ * `base=''` (default) yields the hub-relative `/api/...`; `base='/content'`
+ * (or any reverse-proxy prefix) yields `/content/api/...`.
+ *
+ * Pure + server-safe (no React, no browser APIs) so the hub's server-side
+ * mappers can import it from `@flamingo-stack/openframe-frontend-core/utils`.
+ */
+
+/**
+ * Legacy ContentRef aliases that predate the RAG `documentType`
+ * unification — direct lib/embedder callers (e.g. the chat dispatcher's
+ * `endpoints.buildListUrl`) still emit `blog_post_existing`. Mirrors the
+ * hub's own `LEGACY_TYPE_ALIASES` (`lib/utils/entity-list-api.ts`); both
+ * entry points un-alias to the canonical `documentType` before lookup.
+ */
+const ALIASES: Record<string, string> = { blog_post_existing: 'blog_post' }
+
+/**
+ * One builder per fetch-mode `contentRefType`, keyed by the canonical
+ * `documentType`. Each body is copied VERBATIM from the matching hub
+ * mapper's `listApi` (raw, unencoded `join(',')`; exact param names) —
+ * the byte-parity test (`__tests__/list-url.test.ts`) fails if any drifts.
+ *
+ * An ABSENT key ⇒ `buildListUrl` returns null (no-fetch). The no-list
+ * types (`github_*`, `slack_message`, financials, docs) are intentionally
+ * NOT enumerated here — their absence IS the null. `marketing_campaign`
+ * is handled as a literal case in `buildListUrl` (see there).
+ */
+const BUILDERS: Record<string, (ids: string[], base: string) => string> = {
+  roadmap_item: (ids, b) => `${b}/api/roadmap?task_ids=${ids.join(',')}`,
+  delivery_item: (ids, b) => `${b}/api/delivery?task_ids=${ids.join(',')}`,
+  internal_task: (ids, b) => `${b}/api/internal-tasks?task_ids=${ids.join(',')}`,
+  blog_post: (ids, b) => `${b}/api/blog/posts?ids=${ids.join(',')}&pageSize=${ids.length}`,
+  webinar: (ids, b) => `${b}/api/programs/webinars?ids=${ids.join(',')}&limit=${ids.length}&filter=all`,
+  podcast: (ids, b) => `${b}/api/programs/podcasts?ids=${ids.join(',')}&limit=${ids.length}&filter=all`,
+  event: (ids, b) => `${b}/api/programs/events?ids=${ids.join(',')}&limit=${ids.length}&filter=all`,
+  onboarding_guide: (ids, b) => `${b}/api/onboarding-guides?ids=${ids.join(',')}&limit=${ids.length}`,
+  case_study: (ids, b) => `${b}/api/case-studies?ids=${ids.join(',')}&limit=${ids.length}`,
+  product_release: (ids, b) => `${b}/api/releases?ids=${ids.join(',')}&limit=${ids.length}`,
+  customer_interview: (ids, b) => `${b}/api/customer-interviews?ids=${ids.join(',')}&limit=${ids.length}`,
+  investor_update: (ids, b) => `${b}/api/investor-updates?ids=${ids.join(',')}&limit=${ids.length}`,
+}
+
+/**
+ * Build a list-API URL that returns full rows for the given ids, or `null`
+ * when the type has no list endpoint (the caller skips fetching rather than
+ * fabricating a URL).
+ *
+ *   buildListUrl('roadmap_item', ['a','b'])             → '/api/roadmap?task_ids=a,b'
+ *   buildListUrl('blog_post_existing', ['a','b'])       → '/api/blog/posts?ids=a,b&pageSize=2'  (alias)
+ *   buildListUrl('roadmap_item', ['a','b'], '/content') → '/content/api/roadmap?task_ids=a,b'
+ *   buildListUrl('github_pr', ['a'])                    → null  (absent key)
+ *
+ * `marketing_campaign` (admin-only, non-RAG) is a LITERAL case, NOT a
+ * `BUILDERS` entry — a static branch keeps CodeQL able to prove no
+ * user-controlled dynamic dispatch reaches the admin endpoint; embedders
+ * can't hit `/api/admin` through their proxy anyway.
+ */
+export function buildListUrl(contentRefType: string, ids: string[], base = ''): string | null {
+  if (ids.length === 0) return null
+  const key = ALIASES[contentRefType] ?? contentRefType
+  if (key === 'marketing_campaign') {
+    // Keep this URL in sync with the hub's `entity-list-api.ts` buildNonRagListUrl
+    // — an intentional dual literal (a static branch in each) so CodeQL can prove
+    // no user-controlled dynamic dispatch reaches `/api/admin`.
+    return `${base}/api/admin/marketing/campaigns?ids=${ids.join(',')}&pageSize=${ids.length}`
+  }
+  // `hasOwnProperty` guard so a prototype key (`constructor`, `__proto__`)
+  // can't dispatch to a non-builder — absent key ⇒ null.
+  const fn = Object.prototype.hasOwnProperty.call(BUILDERS, key) ? BUILDERS[key] : undefined
+  return fn ? fn(ids, base) : null
+}

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

@@ -303,6 +303,92 @@ export function getReadableTextColor(hex: string): string {
   return luminance > 0.5 ? '#212121' : '#fafafa'
 }
 
+// Hex <-> RGB <-> HSL. Hex is #rrggbb lowercase; hexToRgb returns null on invalid.
+
+export const HEX_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}
+
+export function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  if (!HEX_PATTERN.test(hex)) return null;
+  const n = Number.parseInt(hex.slice(1), 16);
+  return { r: (n >> 16) & 0xff, g: (n >> 8) & 0xff, b: n & 0xff };
+}
+
+export function rgbToHex(r: number, g: number, b: number): string {
+  const to = (n: number) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, '0');
+  return `#${to(r)}${to(g)}${to(b)}`;
+}
+
+// Ticket-status interaction states. The design-system presets derive their
+// hover/active fills by darkening each RGB channel a fixed step (10 → hover,
+// 20 → active). Applying the same rule to user-picked custom colors keeps their
+// interaction states consistent with the presets without hardcoding a variant
+// per color. Channels floor at 0 via rgbToHex's clamp.
+const HOVER_DARKEN_STEP = 10;
+const ACTIVE_DARKEN_STEP = 20;
+
+function darkenByStep(hex: string, step: number): string {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return hex;
+  return rgbToHex(rgb.r - step, rgb.g - step, rgb.b - step);
+}
+
+export function deriveHoverColor(hex: string): string {
+  return darkenByStep(hex, HOVER_DARKEN_STEP);
+}
+
+export function deriveActiveColor(hex: string): string {
+  return darkenByStep(hex, ACTIVE_DARKEN_STEP);
+}
+
+export function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l: Math.round(l * 100) };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h: number;
+  if (max === rn) h = (gn - bn) / d + (gn < bn ? 6 : 0);
+  else if (max === gn) h = (bn - rn) / d + 2;
+  else h = (rn - gn) / d + 4;
+  h *= 60;
+  return { h: Math.round(h), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+export function hslToRgb(h: number, s: number, l: number): { r: number; g: number; b: number } {
+  const sn = clamp(s, 0, 100) / 100;
+  const ln = clamp(l, 0, 100) / 100;
+  const hn = ((h % 360) + 360) % 360;
+  if (sn === 0) {
+    const v = Math.round(ln * 255);
+    return { r: v, g: v, b: v };
+  }
+  const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+  const p = 2 * ln - q;
+  const hue2rgb = (t: number) => {
+    let tn = t;
+    if (tn < 0) tn += 1;
+    if (tn > 1) tn -= 1;
+    if (tn < 1 / 6) return p + (q - p) * 6 * tn;
+    if (tn < 1 / 2) return q;
+    if (tn < 2 / 3) return p + (q - p) * (2 / 3 - tn) * 6;
+    return p;
+  };
+  const hk = hn / 360;
+  return {
+    r: Math.round(hue2rgb(hk + 1 / 3) * 255),
+    g: Math.round(hue2rgb(hk) * 255),
+    b: Math.round(hue2rgb(hk - 1 / 3) * 255),
+  };
+}
+
 export default {
   getODSToken,
   getPlatformAccentColor,