@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/types/.supabase.md

@@ -1,31 +1,45 @@
-<!-- source-hash: e5e5528221514a1a868f47ffbc324b0c -->
-Auto-generated type definitions for the Flamingo/OpenFrame Supabase database schema, providing fully-typed `Row`, `Insert`, and `Update` interfaces for all public tables along with their foreign key relationships.
+<!-- source-hash: 23455e458da538aa93f78c3bc682573d -->
+Auto-generated Supabase database type definitions for the OpenFrame OSS library, providing strongly-typed interfaces for all public schema tables including announcements, Slack data, podcast episodes, webinars, and Luma events.
 
 ## Key Components
 
 ### `Json` Type
-A recursive union type representing any valid JSON value — `string`, `number`, `boolean`, `null`, nested objects, or arrays.
+
+A recursive union type representing any valid JSON value — primitives, objects, arrays, or `null`.
 
 ### `Database` Type
-The root type exported for use with the Supabase client. Contains a `public` schema with the following tables:
+
+The root type describing the full Supabase public schema. Each table is represented with three operation shapes:
+
+| Shape | Purpose |
+|-------|---------|
+| `Row` | Full record returned from `SELECT` queries |
+| `Insert` | Required + optional fields for `INSERT` |
+| `Update` | All fields optional for `PATCH`/`UPDATE` |
+
+### Tables
 
 | Table | Description |
-|---|---|
-| `announcement_assets` | File attachments (images, docs) linked to announcements |
-| `announcements` | Platform announcements with icon, color, and active state |
+|-------|-------------|
+| `announcement_assets` | File attachments linked to announcements |
+| `announcements` | Platform announcements with icons and styling |
 | `slack_channels` | Synced Slack workspace channels |
-| `slack_messages` | Slack messages with threading and reply support |
-| `slack_users` | Slack workspace user profiles |
-| `podcast_episodes` | Podbean podcast episodes linked to platforms |
-| `webinars` | Livestorm webinar events linked to platforms |
+| `slack_messages` | Slack messages with threading and metadata |
+| `slack_users` | Slack workspace member profiles |
+| `podcast_episodes` | Podbean-synced podcast episode records |
+| `webinars` | Livestorm-synced webinar events |
+| `luma_events` | Luma-synced community events |
+
+### Relationships
 
-Each table exposes three operation shapes:
-- **`Row`** — full record shape returned by `SELECT`
-- **`Insert`** — shape for `INSERT` (required fields enforced, optional fields use `?`)
-- **`Update`** — shape for `UPDATE` (all fields optional)
+- `announcement_assets.announcement_id` → `announcements.id`
+- `slack_messages.channel_id` → `slack_channels.channel_id`
+- `slack_messages.user_id` → `slack_users.user_id`
 
 ## Usage Example
 
+Pass the `Database` type to the Supabase client for full end-to-end type safety:
+
 ```typescript
 import { createClient } from '@supabase/supabase-js'
 import type { Database } from './supabase'
@@ -35,18 +49,18 @@ const supabase = createClient<Database>(
   process.env.SUPABASE_ANON_KEY!
 )
 
-// Fully typed query — row shape inferred automatically
-const { data: episodes } = await supabase
-  .from('podcast_episodes')
-  .select('id, title, audio_url, published_at')
-  .eq('platform_id', 'abc-123')
-
-// Typed insert
-const { error } = await supabase
+// Fully typed — Row shape inferred automatically
+const { data: announcements } = await supabase
   .from('announcements')
-  .insert({
-    title: 'New Feature',
-    description: 'Check out what is new!',
-    platform_id: 'abc-123',
-  })
-```
+  .select('id, title, description, is_active')
+  .eq('is_active', true)
+
+// Type-safe insert — Insert shape enforced
+await supabase.from('slack_users').insert({
+  user_id: 'U12345',
+  username: 'jane.doe',
+  display_name: 'Jane Doe',
+})
+```
+
+**Source:** [`supabase.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/supabase.ts)

package/src/types/.tool.types.md

@@ -1,36 +1,56 @@
-<!-- source-hash: 455ff90d32dc36ef99be5420007f9262 -->
-Centralized type definitions for MSP tool types used throughout the Flamingo/OpenFrame platform. Provides a single source of truth for tool type constants and display labels.
+<!-- source-hash: f34afe24b605fb7d34139a1142319f18 -->
+Defines the centralized type system for all MSP tool integrations in the OpenFrame platform, serving as the single source of truth for tool type identifiers and display labels.
 
 ## Key Components
 
-- **`ToolTypeValues`** - Const assertion object containing all available tool type constants (FLEET_MDM, MESHCENTRAL, etc.)
-- **`ToolType`** - Union type derived from ToolTypeValues for type-safe tool type references
-- **`toolLabels`** - Record mapping tool types to human-readable display names
+| Export | Type | Description |
+|--------|------|-------------|
+| `ToolTypeValues` | `const object` | Enum-like constant map of all supported tool type string literals |
+| `ToolType` | `type` | Union type derived from `ToolTypeValues` values |
+| `toolLabels` | `Record<ToolType, string>` | Maps each `ToolType` to its human-readable display label |
+
+### Supported Tool Types
+
+| Key | Value | Label |
+|-----|-------|-------|
+| `FLEET_MDM` | `'FLEET_MDM'` | Fleet |
+| `MESHCENTRAL` | `'MESHCENTRAL'` | MeshCentral |
+| `AUTHENTIK` | `'AUTHENTIK'` | Authentik |
+| `OPENFRAME` | `'OPENFRAME'` | OpenFrame |
+| `OPENFRAME_CHAT` | `'OPENFRAME_CHAT'` | OpenFrame Chat |
+| `OPENFRAME_CLIENT` | `'OPENFRAME_CLIENT'` | OpenFrame Client |
+| `OPENFRAME_RMM` | `'OPENFRAME_RMM'` | RMM |
+| `OSQUERY` | `'OSQUERY'` | Osquery |
+| `SYSTEM` | `'SYSTEM'` | System |
 
 ## Usage Example
 
 ```typescript
 import { ToolType, ToolTypeValues, toolLabels } from './tool.types'
 
-// Type-safe tool type usage
-const currentTool: ToolType = ToolTypeValues.MESHCENTRAL
-
-// Get display label for UI
-const displayName = toolLabels[currentTool] // "MeshCentral"
-
-// Use in component props
-interface ToolBadgeProps {
-  type: ToolType
-  label?: string
+// Type-safe tool type reference
+const currentTool: ToolType = ToolTypeValues.FLEET_MDM
+
+// Resolve display label for UI rendering (e.g. ToolBadge, ToolIcon)
+const label = toolLabels[currentTool] // → 'Fleet'
+
+// Narrow by tool type in a switch
+function handleTool(tool: ToolType) {
+  switch (tool) {
+    case ToolTypeValues.MESHCENTRAL:
+      // handle MeshCentral
+      break
+    case ToolTypeValues.OPENFRAME_RMM:
+      // handle RMM
+      break
+  }
 }
+```
 
-function ToolBadge({ type, label }: ToolBadgeProps) {
-  const defaultLabel = toolLabels[type]
-  return <span>{label || defaultLabel}</span>
-}
+## Notes
 
-// Usage with type safety
-<ToolBadge type={ToolTypeValues.OPENFRAME_CHAT} />
-```
+- Prefer `ToolTypeValues.X` over raw string literals to ensure compile-time safety.
+- `ToolType` is a strict union — TypeScript will error on unrecognized values.
+- Consumed by `ToolBadge`, `ToolIcon`, and any component requiring tool metadata.
 
-The const assertion pattern ensures type safety while maintaining runtime access to the values, making it ideal for components like ToolBadge and ToolIcon that need both compile-time type checking and runtime value access.
+**Source:** [`tool.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool.types.ts)

package/src/types/.video-processing.md

@@ -1,54 +1,63 @@
-<!-- source-hash: d2e79259f53d9d688fe3d007c1eb382a -->
-Shared type definitions for video processing functionality used across multiple entities (CustomerInterview, ProductRelease, and other video-enabled features).
+<!-- source-hash: 6ec3f18beb42e1d118dec17403060310 -->
+Shared TypeScript type definitions for video processing functionality, providing the canonical data shapes used across video-enabled entities such as customer interviews, product releases, and marketing campaigns.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `VideoTeaser` | Interface | Short video clip for previews; tracks URL, thumbnail, visibility, and origin (`manual` \| `ai_generated`) |
-| `Speaker` | Interface | Speaker identification metadata from transcription |
-| `VideoClip` | Interface | AI-identified video segment with time range, confidence, and optional Twelve Labs ID |
-| `TranscriptWord` | Interface | Word-level transcript entry with millisecond timestamps and speaker attribution |
-| `SpeakerMapping` | Interface | Maps AssemblyAI speaker labels (e.g., `"A"`, `"B"`) to names and roles |
-| `ExcludedRange` | Interface | Time range exclusion (e.g., incentive mentions) in seconds |
-| `VideoProcessingFields` | Interface | Base fields shared across all video-enabled entities (transcript, highlight video, thumbnails, AI confidence scores) |
-| `VideoProcessingEntityType` | Union Type | Supported entity types for agent processing pipelines |
+| Export | Kind | Description |
+|---|---|---|
+| `VideoTeaser` | Interface | Canonical persistence shape for short video clips/bites stored in `video_bites`/`teasers` JSONB columns |
+| `Speaker` | Interface | Speaker identification metadata for transcription workflows |
+| `VideoClip` | Interface | AI-identified video segment from Twelve Labs analysis |
+| `TranscriptWord` | Interface | Word-level transcript data with millisecond-precision timing |
+| `SpeakerMapping` | Interface | Maps AssemblyAI speaker labels (`"A"`, `"B"`) to named participant info |
+| `ExcludedRange` | Interface | Time range exclusions (e.g., incentive mentions) in seconds |
+| `VideoProcessingFields` | Interface | Base set of video fields shared across all video-capable entities |
+| `VideoProcessingEntityType` | Type Union | Discriminator for agent routing across all supported entity types |
 
 ## Usage Example
 
 ```typescript
 import type {
+  VideoTeaser,
   VideoProcessingFields,
   SpeakerMapping,
-  VideoTeaser,
-  VideoProcessingEntityType
+  VideoProcessingEntityType,
 } from './video-processing'
 
-const speakerMapping: SpeakerMapping = {
-  A: { name: 'Jane Smith', role: 'interviewer' },
-  B: { name: 'John Doe',  role: 'interviewee', userId: 'usr_123' },
+// Composing a video-enabled entity record
+const speakerMap: SpeakerMapping = {
+  A: { name: 'Jane Doe', role: 'interviewer' },
+  B: { name: 'John Smith', role: 'interviewee', userId: 'usr_abc123' },
 }
 
-const videoFields: VideoProcessingFields = {
-  main_video_url: 'https://cdn.example.com/interviews/abc.mp4',
+const fields: VideoProcessingFields = {
+  main_video_url: 'https://stream.mux.com/abc123.m3u8',
   transcript: 'Full transcript text...',
-  transcript_words_data: [
-    { text: 'Hello', start: 0, end: 450, confidence: 0.98, speaker: 'A' },
-  ],
-  speaker_mapping: speakerMapping,
-  ai_confidence_transcript: 0.95,
-  ai_confidence_summary: 0.88,
+  speaker_mapping: speakerMap,
+  ai_confidence_transcript: 0.94,
+  ai_confidence_summary: 0.87,
 }
 
+const entityType: VideoProcessingEntityType = 'customer_interview'
+
+// Constructing a teaser bite (canonical shape)
 const teaser: VideoTeaser = {
-  url: 'https://cdn.example.com/teasers/clip1.mp4',
-  title: 'Key insight on onboarding',
+  id: 'a1b2c3d4',
+  url: 'https://stream.mux.com/bite_xyz.m3u8',
+  title: 'Key product insight moment',
+  start_time_ms: 134000,
+  end_time_ms: 162000,
   published: true,
+  featured: false,
   source: 'ai_generated',
-  created_at: new Date().toISOString(),
+  confidence: 87,
 }
-
-const entityType: VideoProcessingEntityType = 'customer_interview'
 ```
 
-> **Note:** `VideoProcessingFields` is intended as a base — extend it per entity rather than using it directly. `published` on `VideoTeaser` defaults to `false`; an admin must explicitly set it to `true` for public visibility.
+## Notes
+
+- `VideoTeaser` is the **true superset** for persistence — downstream display types (e.g., `VideoTeaserWithRatio`) extend it rather than diverging from it.
+- `VideoClip` intentionally remains a separate shape from `VideoTeaser`; it represents AI extraction candidates, not persisted bites.
+- `id` on `VideoTeaser` is a stable 8-char lowercase-hex identity key used by the Mux transcode pipeline — never derived from `url`.
+
+**Source:** [`video-processing.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-processing.ts)

package/src/types/supabase.ts

@@ -389,6 +389,86 @@ export type Database = {
         Relationships: [
         ]
       }
+      walkthrough_videos: {
+        Row: {
+          id: number
+          platform_id: string
+          title: string
+          status: string
+          youtube_url: string | null
+          main_video_url: string | null
+          main_video_thumbnail: string | null
+          video_summary: string | null
+          transcript: string | null
+          srt_content: string | null
+          transcript_words_data: Json | null
+          video_bites: Json
+          config: Json | null
+          custom_instructions: string | null
+          highlight_video_url: string | null
+          highlight_video_source: string | null
+          highlight_video_thumbnail: string | null
+          highlight_video_duration_ms: number | null
+          author_id: string | null
+          created_at: string
+          updated_at: string
+        }
+        Insert: {
+          id?: never
+          platform_id: string
+          title: string
+          status?: string
+          youtube_url?: string | null
+          main_video_url?: string | null
+          main_video_thumbnail?: string | null
+          video_summary?: string | null
+          transcript?: string | null
+          srt_content?: string | null
+          transcript_words_data?: Json | null
+          video_bites?: Json
+          config?: Json | null
+          custom_instructions?: string | null
+          highlight_video_url?: string | null
+          highlight_video_source?: string | null
+          highlight_video_thumbnail?: string | null
+          highlight_video_duration_ms?: number | null
+          author_id?: string | null
+          created_at?: string
+          updated_at?: string
+        }
+        Update: {
+          id?: never
+          platform_id?: string
+          title?: string
+          status?: string
+          youtube_url?: string | null
+          main_video_url?: string | null
+          main_video_thumbnail?: string | null
+          video_summary?: string | null
+          transcript?: string | null
+          srt_content?: string | null
+          transcript_words_data?: Json | null
+          video_bites?: Json
+          config?: Json | null
+          custom_instructions?: string | null
+          highlight_video_url?: string | null
+          highlight_video_source?: string | null
+          highlight_video_thumbnail?: string | null
+          highlight_video_duration_ms?: number | null
+          author_id?: string | null
+          created_at?: string
+          updated_at?: string
+        }
+        Relationships: [
+          {
+            foreignKeyName: "walkthrough_videos_platform_id_fkey"
+            columns: ["platform_id"]
+            isOneToOne: true
+            referencedRelation: "platforms"
+            referencedColumns: ["id"]
+          }
+        ]
+      }
       luma_events: {
         Row: {
           id: string

package/src/types/video-processing.ts

@@ -120,4 +120,5 @@ export type VideoProcessingEntityType =
   | 'investor_update'
   | 'onboarding_guide'
   | 'what_i_shipped'
+  | 'walkthrough_video'
 // Fri May 15 14:58:59 EDT 2026

package/src/utils/.announcement-storage.md

@@ -1,31 +1,63 @@
-<!-- source-hash: pending-regeneration -->
-Announcement dismissal store. The dismissal COOKIE is the single source of truth — the hub's root layout reads it server-side to decide whether to SSR-seed the AnnouncementBar (no flash for dismissed users); the legacy per-id localStorage key is read-only legacy consulted only when no cookie exists (migration trigger).
+<!-- source-hash: eaaab09af79a45c05efef4de2c5f0db6 -->
+Manages announcement dismissal state using a cookie-first strategy, enabling SSR-safe dismissal detection and seamless migration from a legacy localStorage approach.
 
 ## Key Components
 
-- **`announcementDismissCookieName(platform)`** - The ONE home for the cookie-name encoding (`<platform>-announcement-dismissed`), shared by the client writer and the hub's SSR reader
-- **`isDismissedCookieValue(cookieValue, id)`** - THE dismissal match rule (id-match, never mere cookie presence), pure and isomorphic — shared across the server/client boundary
-- **`dismissAnnouncement(platform, id)`** - Persists a dismissal (cookie only, 1 year, SameSite=Lax); localStorage is intentionally not written
-- **`isAnnouncementDismissed(platform, id)`** - Client-side check, cookie-first with legacy-localStorage fallback; reads browser storage so it must be called from effects, never during render
-- **`clearLegacyAnnouncementCache(platform)`** - One-time cleanup of the pre-refactor localStorage "instant paint" cache blob
+| Export | Type | Description |
+|--------|------|-------------|
+| `announcementDismissCookieName` | `function` | Returns the canonical cookie name for a platform's dismissed announcement ID |
+| `isDismissedCookieValue` | `function` | Pure/isomorphic ID-match check shared across server and client boundaries |
+| `dismissAnnouncement` | `function` | Persists a dismissal to cookie only (1-year `max-age`); intentionally skips localStorage |
+| `isAnnouncementDismissed` | `function` | Cookie-first client-side check, with legacy localStorage fallback when no cookie exists |
+| `clearAnnouncementDismissals` | `function` | Removes all dismissal state (cookie + legacy localStorage keys) — for tests/stories |
+| `clearLegacyAnnouncementCache` | `function` | One-time cleanup of the pre-refactor announcement cache blob from localStorage |
+
+## Storage Architecture
+
+```mermaid
+graph TD
+    SSR["SSR Layout (server)"] -->|reads cookie| Cookie["platform-announcement-dismissed cookie"]
+    Client["Client Mount Effect"] -->|reads cookie first| Cookie
+    Client -->|fallback, read-only| LS["Legacy localStorage key"]
+    Client -->|backfills on migration| Cookie
+    Dismiss["dismissAnnouncement()"] -->|writes| Cookie
+    Dismiss -. never writes .-> LS
+```
 
 ## Usage Example
 
 ```typescript
 import {
-  dismissAnnouncement,
-  isAnnouncementDismissed,
   announcementDismissCookieName,
   isDismissedCookieValue,
-} from './announcement-storage';
+  dismissAnnouncement,
+  isAnnouncementDismissed,
+  clearAnnouncementDismissals,
+} from './announcement-storage'
+
+// Server-side (Next.js layout): check if already dismissed via cookie
+const cookieValue = cookies().get(announcementDismissCookieName('hub'))?.value
+const shouldSeedBar = !isDismissedCookieValue(cookieValue, activeAnnouncement.id)
+
+// Client-side: check dismissal from an effect (never during render)
+useEffect(() => {
+  if (isAnnouncementDismissed('hub', announcement.id)) {
+    setVisible(false)
+  }
+}, [announcement.id])
 
-// Client (in an effect):
-if (isAnnouncementDismissed('openframe', announcement.id)) { /* collapse */ }
-dismissAnnouncement('openframe', announcement.id);
+// On user dismiss
+function handleDismiss() {
+  dismissAnnouncement('hub', announcement.id)
+  setVisible(false)
+}
 
-// Server (hub root layout):
-const cookieValue = (await cookies()).get(announcementDismissCookieName(platform))?.value;
-const dismissed = isDismissedCookieValue(cookieValue, announcement?.id);
+// In tests/Storybook: reset state between stories
+afterEach(() => clearAnnouncementDismissals('hub'))
 ```
 
-No `"use client"` directive on purpose — the name/match helpers are imported by the hub's server layout; DOM-touching helpers guard on `typeof document`.
+> **Note:** `isAnnouncementDismissed` reads browser storage and must only be called from effects — never during render — to avoid SSR/hydration mismatches.
+
+## Source
+
+[`announcement-storage.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/announcement-storage.ts)

package/src/utils/.app-config.md

@@ -1,32 +1,36 @@
-<!-- source-hash: e85f6b3fb26728490c7a8f3f9f1cfba8 -->
-A configuration module that defines the application's core settings and provides utilities for accessing app-specific configuration values.
+<!-- source-hash: 74f778fe6f21ac592b390d0c7e37584e -->
+Provides static application configuration and runtime app-type resolution for the OpenMSP platform, with safe fallbacks for non-Next.js host environments.
 
 ## Key Components
 
-- **`APP_CONFIG`** - Immutable configuration object containing app metadata and feature flags
-- **`getAppConfig()`** - Function that returns the complete application configuration
-- **`getAppType()`** - Function that retrieves the app type from environment variables with fallback
+- **`APP_CONFIG`** — Immutable (`as const`) config object containing app identity (`type`, `name`, `domain`) and feature flags (`announcements`, `notifications`).
+- **`getAppConfig()`** — Returns the full `APP_CONFIG` object.
+- **`getAppType()`** — Resolves the active app type at runtime, reading `process.env.NEXT_PUBLIC_APP_TYPE` for Next.js/webpack static inlining, with a `try/catch` guard that returns `'openmsp'` in environments where `process` is unavailable (e.g., Vite, CRA embeds).
 
 ## Usage Example
 
 ```typescript
-import { APP_CONFIG, getAppConfig, getAppType } from './app-config';
+import { getAppConfig, getAppType } from './app-config';
 
-// Access static configuration
-console.log(APP_CONFIG.app.name); // 'OpenMSP'
-console.log(APP_CONFIG.features.announcements); // true
-
-// Get configuration dynamically
+// Access full config
 const config = getAppConfig();
-if (config.features.notifications) {
-  // Enable notification features
-}
+console.log(config.app.name);         // 'OpenMSP'
+console.log(config.features.announcements); // true
 
-// Check app type (useful for multi-tenant applications)
+// Resolve app type at runtime (safe in Next.js and Vite/CRA embeds)
 const appType = getAppType();
-if (appType === 'openmsp') {
-  // OpenMSP-specific logic
+console.log(appType); // 'openmsp' (or value of NEXT_PUBLIC_APP_TYPE)
+
+// Feature-flag guard
+if (getAppConfig().features.notifications) {
+  // initialize notification system
 }
 ```
 
-The configuration uses TypeScript's `as const` assertion to ensure type safety and immutability. The `getAppType()` function allows runtime determination of the application type through environment variables, making it suitable for multi-tenant or white-label applications.
+## Notes
+
+- `NEXT_PUBLIC_APP_TYPE` must be set at **build time** in Next.js for webpack to statically inline it; runtime assignment has no effect.
+- The `try/catch` in `getAppType()` ensures embed hosts (Vite, CRA) that lack a global `process` object receive the `'openmsp'` fallback without throwing.
+- Dismissal cookies for announcements are domain-scoped, so the `'openmsp'` fallback is safe for single-platform embed deployments.
+
+**Source:** [`app-config.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/app-config.ts)

package/src/utils/.brand-marks.md

@@ -0,0 +1,46 @@
+<!-- source-hash: d68a2227a3551e27e65a194850078361 -->
+Centralized repository of monochrome SVG brand mark silhouettes, keyed by lowercase brand name, intended for use with CSS `mask-image` tinting.
+
+## Key Components
+
+**`BRAND_MARK_SVGS`** — `Record<string, string>`
+
+A constant map of brand name strings to raw SVG markup. Each SVG uses `role="img"` and a `<title>` element for accessibility. Current entries include:
+
+| Key | Brand |
+|---|---|
+| `amazonwebservices` | Amazon Web Services |
+| `datadog` | Datadog |
+| `git` | Git |
+| `github` | GitHub |
+| `gnubash` | GNU Bash |
+| `googlecloud` | Google Cloud |
+| `grafana` | Grafana |
+
+## Usage Example
+
+```typescript
+import { BRAND_MARK_SVGS } from './brand-marks';
+
+// Render an inline SVG
+const svgMarkup = BRAND_MARK_SVGS['github'];
+element.innerHTML = svgMarkup;
+
+// Use as a CSS mask for tinted icons
+const maskStyle = {
+  maskImage: `url("data:image/svg+xml,${encodeURIComponent(BRAND_MARK_SVGS['github'])}")`,
+  maskRepeat: 'no-repeat',
+  maskSize: 'contain',
+  backgroundColor: 'currentColor',
+};
+```
+
+## Notes
+
+- All SVGs are monochrome (single `<path>`) to support CSS `mask-image` tinting — applying color via `background-color` or `color` without modifying the SVG source.
+- Centralizing these assets prevents consumers from bundling duplicate copies.
+- Lookup keys are always **lowercase** with no spaces or hyphens (e.g., `amazonwebservices`, `googlecloud`).
+
+## Source
+
+[`brand-marks.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/brand-marks.ts)

package/src/utils/.cn.md

@@ -1,44 +1,55 @@
-<!-- source-hash: c1693a304ddf9b29bde0ca02b6f6b8ea -->
-Utility module providing class name merging with extended Tailwind support, and platform URL resolution helpers for multi-tenant Flamingo/OpenFrame deployments.
+<!-- source-hash: 700d6c65ebfb65630e665b437acf4e83 -->
+Utility module providing two core helpers: a Tailwind-aware class name merger (`cn`) that correctly handles custom ODS typography utilities, and an environment-aware base URL resolver (`getBaseUrl`) that delegates platform canonical URLs to the SSOT in `platform-domains.ts`.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `cn` | Function | Merges class names using `clsx` + `tailwind-merge`, extended with custom ODS typography classes (`text-h1`–`text-h6`) |
-| `getPlatformProductionUrl` | Function | Returns the production URL for a named platform, with `NEXT_PUBLIC_*` env var override support |
-| `getAllPlatformBaseDomains` | Function | Extracts all unique base domains across platforms; handles localhost, Vercel preview, and production cases (useful for cross-domain cookie scope) |
-| `getBaseUrl` | Function | Resolves the current app's base URL using a priority chain: env override → platform URL → Vercel domain → production fallback → `localhost:3000` |
+| `cn` | `function` | Combines class names using `clsx` + a custom `tailwind-merge` instance |
+| `getBaseUrl` | `function` | Returns the application base URL for the current environment |
+| `twMerge` | internal | Extended `tailwind-merge` instance with the `ods-typography` class group |
+
+### `ods-typography` Class Group
+
+Custom Tailwind text-size utilities registered to prevent silent conflicts with `text-color` utilities:
+
+```text
+text-h1 · text-h2 · text-h3 · text-h4 · text-h5 · text-h6 · text-code · text-badge
+```
+
+Without this registration, `cn('text-badge', 'text-ods-text-on-accent')` would drop `text-badge` — only the colour survives.
 
 ## Usage Example
 
 ```typescript
-import { cn, getBaseUrl, getPlatformProductionUrl, getAllPlatformBaseDomains } from '@/lib/cn'
-
-// Merge Tailwind classes (including custom ODS typography)
-const className = cn('text-h1 font-bold', isActive && 'text-yellow-400')
+import { cn, getBaseUrl } from '@/lib/cn'
 
-// Resolve current app base URL
-const apiBase = getBaseUrl()                      // http://localhost:3000 (dev)
-                                                  // https://www.openmsp.ai (prod fallback)
+// Merge conditional classes safely — typography and colour both survive
+const className = cn(
+  'text-badge',
+  'text-ods-text-on-accent',
+  isActive && 'bg-accent',
+)
 
-// Resolve a specific platform URL (respects NEXT_PUBLIC_* overrides)
-const flamingoUrl = getBaseUrl('flamingo')        // https://www.flamingo.run
-const openframeUrl = getPlatformProductionUrl('openframe') // https://openframe.ai
+// Current deployment URL (dev → localhost, prod → Vercel/canonical domain)
+const currentUrl = getBaseUrl()
 
-// Get all cookie-scoped base domains (e.g. for document.cookie domain=)
-const domains = getAllPlatformBaseDomains()
-// Production: ['.flamingo.run', 'flamingo.run', '.openmsp.ai', 'openmsp.ai', ...]
-// Vercel preview: ['.vercel.app', 'vercel.app']
-// Localhost: []
+// Specific platform URL (respects env override, falls back to canonical)
+const flamingoUrl = getBaseUrl('flamingo')  // https://www.flamingo.run
+const openMspUrl  = getBaseUrl('openmsp')   // https://www.openmsp.ai
 ```
 
-## Environment Variables
+## `getBaseUrl` Resolution Order
+
+```mermaid
+graph TD
+    A[getBaseUrl called] --> B{NODE_ENV !== production?}
+    B -->|Yes| C[NEXT_PUBLIC_DEV_URL or localhost:3000]
+    B -->|No| D{platform arg provided?}
+    D -->|Yes| E[getPlatformProductionUrl from SSOT]
+    D -->|No| F{VERCEL_PROJECT_PRODUCTION_URL set?}
+    F -->|Yes| G[https://vercel-domain]
+    F -->|No| H[getPlatformProductionUrl via NEXT_PUBLIC_APP_TYPE]
+```
 
-| Variable | Platform | Default |
-|----------|----------|---------|
-| `NEXT_PUBLIC_FLAMINGO_URL` | `flamingo`, `universal` | `https://www.flamingo.run` |
-| `NEXT_PUBLIC_OPENMSP_URL` | `openmsp` | `https://www.openmsp.ai` |
-| `NEXT_PUBLIC_OPENFRAME_URL` | `openframe` | `https://openframe.ai` |
-| `NEXT_PUBLIC_MARKETING_HUB_URL` | `marketing-hub` | `https://marketing-hub.flamingo.so` |
-| `NEXT_PUBLIC_DEV_URL` | all (dev only) | `http://localhost:3000` |
+> Platform canonical URLs and their `NEXT_PUBLIC_*_URL` environment overrides are defined exclusively in [`src/platform-domains.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/platform-domains.ts).