@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260726003127

package/src/utils/.release-cover.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 90922d1a0fba270fdb0d92bc58406d0e -->
+Resolves the cover image for a `ProductReleaseCard` using a deterministic priority chain, serving as the single source of truth for all surfaces that render release covers.
+
+## Key Components
+
+### `ReleaseCoverSource`
+Input interface describing the available image candidates on a release entity:
+
+| Field | Description |
+|---|---|
+| `featured_image` | Editor-curated cover — highest priority |
+| `highlight_video_thumbnail` | AI-generated highlight reel thumbnail |
+| `main_video_thumbnail` | Full-release video thumbnail |
+| `og_image_url` | SEO/OG fallback image |
+
+### `ReleaseCoverResult`
+Output interface returned by the resolver:
+
+| Field | Description |
+|---|---|
+| `cover` | Resolved image URL, or `null` if none available |
+| `hasVideoCover` | `true` only when the active cover is a video thumbnail (priorities 2–3) |
+
+### `resolveReleaseCover(r: ReleaseCoverSource): ReleaseCoverResult`
+Applies the priority chain using `||` (not `??`) so empty strings fall through rather than rendering a broken `<Image src="">`. `hasVideoCover` is suppressed when `featured_image` is set, preventing a misleading Play overlay on still images.
+
+## Usage Example
+
+```typescript
+import { resolveReleaseCover } from './release-cover'
+
+const { cover, hasVideoCover } = resolveReleaseCover({
+  featured_image: null,
+  highlight_video_thumbnail: 'https://cdn.example.com/highlight.jpg',
+  main_video_thumbnail: 'https://cdn.example.com/main.jpg',
+  og_image_url: 'https://cdn.example.com/og.jpg',
+})
+
+// cover        → 'https://cdn.example.com/highlight.jpg'
+// hasVideoCover → true
+```
+
+> **Adding a new fallback source?** Edit only `ReleaseCoverSource`, `ReleaseCoverResult`, and the chain in `resolveReleaseCover` — all rendering surfaces pick up the change automatically.
+
+**Source:** [`release-cover.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/release-cover.ts)

package/src/utils/.same-page-hash-nav.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 67a0df770f7417b847b731191fc01a80 -->
+Handles same-page hash navigation by combining `history.pushState`, synthetic `hashchange` events, and smooth scrolling — working around Next.js limitations that suppress smooth scroll during navigation and treat same-URL `router.push` as a no-op.
+
+## Key Components
+
+### Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `STICKY_HEADER_OFFSET_PX` | `96` | Offset for pages with both a section-nav strip and the global hub header |
+| `HUB_HEADER_OFFSET_PX` | `80` | Offset for pages with only the global hub header (docs, blog, vendor detail) |
+
+### Functions & Interfaces
+
+- **`normalizeHashFragment(hash)`** — Strips any extra `#` segments from a fragment string (e.g., `'#a#b'` → `'#a'`), keeping the URL bar and `getElementById` in sync.
+- **`NavigateSamePageHashOptions`** — Interface with optional `headerOffset` (pixels to subtract for sticky chrome) and `history` mode (`'push'` or `'replace'`).
+- **`navigateSamePageHash(target, options)`** — Core primitive that validates the target is same-origin/pathname/search, normalizes malformed fragments, updates history, fires a synthetic `hashchange` event, and smooth-scrolls to the anchor. Returns `true` if the navigation was claimed, `false` for cross-page targets.
+
+## Usage Example
+
+```typescript
+import {
+  navigateSamePageHash,
+  HUB_HEADER_OFFSET_PX,
+  STICKY_HEADER_OFFSET_PX,
+} from './same-page-hash-nav'
+
+// In a TOC link click handler (replaces history entry instead of pushing)
+function handleTocClick(href: string) {
+  const claimed = navigateSamePageHash(href, {
+    headerOffset: HUB_HEADER_OFFSET_PX,
+    history: 'replace',
+  })
+  if (!claimed) {
+    router.push(href) // fall through for cross-page targets
+  }
+}
+
+// Bare-hash shorthand — no need to reconstruct pathname + search
+navigateSamePageHash('#features', {
+  headerOffset: STICKY_HEADER_OFFSET_PX,
+})
+```
+
+> **Dev-mode warnings:** In development, `navigateSamePageHash` logs to the console when it detects a malformed multi-fragment hash or a missing anchor element, pointing to the upstream composer as the source.

package/src/utils/.scroll-into-view.md

@@ -1,40 +1,47 @@
-<!-- source-hash: ec93c3a6544d7f572c8219bc65ceaf67 -->
-Smooth-scroll utility that positions an element at the top of the viewport with support for sticky header offsets and pre-computed layout-shift adjustments.
+<!-- source-hash: 265569e7b29e4fca2ffe9d67c0157121 -->
+Cancellation-proof scroll helper that animates a target element to the top of the viewport using a self-driven `requestAnimationFrame` tween — immune to browser scroll anchoring, layout shifts, and mid-scroll cancellation issues that affect native smooth scrolling.
 
 ## Key Components
 
-### `ScrollElementIntoViewOptions`
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `headerOffset` | `number` | `0` | Pixels to subtract for sticky chrome (e.g., `96` for `scroll-mt-24`) |
-| `behavior` | `ScrollBehavior` | `'smooth'` | `'smooth'` for animated scrolls, `'instant'` for deep-link jumps |
-| `adjustTargetY` | `(raw: number) => number` | — | Callback to correct the pixel target before animation starts |
-
-### `scrollElementIntoView(target, options?)`
-
-Computes a fixed pixel target via `getBoundingClientRect().top + scrollY - headerOffset`, then calls `window.scrollTo()` directly. This avoids the jitter caused by `element.scrollIntoView()`, which re-targets continuously during layout shifts. Handles `null`/`undefined` refs as a no-op and short-circuits in SSR environments.
+| Export | Type | Description |
+|---|---|---|
+| `ScrollElementIntoViewOptions` | `interface` | Configuration: `headerOffset`, `behavior`, `adjustTargetY`, `durationMs` |
+| `scrollElementIntoView` | `function` | Main entry point — resolves the scroll container, cancels any prior tween, and drives the animation |
+| `getScrollableAncestor` | `function` (internal) | Walks up the DOM to find the nearest real scroll container (`auto\|scroll\|overlay`), ignoring `clip`/`hidden` |
+| `cancelActiveScroll` | `function` (internal) | Cancels the in-flight `rAF` loop and removes gesture listeners |
+| `easeOutCubic` | `function` (internal) | Easing curve `1 - (1 - t)³` applied per frame |
 
 ## Usage Example
 
 ```typescript
 import { scrollElementIntoView } from './scroll-into-view'
 
-// Basic — scroll a ref to top, accounting for a 96px sticky header
-scrollElementIntoView(cardRef.current, { headerOffset: 96 })
+// Basic — smooth scroll below a 64px sticky header
+const el = document.getElementById('section-target')
+scrollElementIntoView(el, { headerOffset: 64 })
 
-// Instant jump on deep-link land
-scrollElementIntoView(anchorRef.current, {
-  headerOffset: 96,
-  behavior: 'instant',
-})
+// Instant jump (deep-link land, programmatic focus)
+scrollElementIntoView(el, { behavior: 'instant', headerOffset: 64 })
 
-// Pre-computed layout-shift adjustment (e.g. HelpCenterCard accordion)
-// Row A (above target) collapses simultaneously — shift target up by A's height
-scrollElementIntoView(rowBRef.current, {
+// With a layout-shift adjustment (e.g. sibling drawer collapsing adds 120px)
+scrollElementIntoView(el, {
   headerOffset: 96,
-  adjustTargetY: (raw) => raw - getAboveDrawerHeight(),
+  durationMs: 400,
+  adjustTargetY: (rawY) => rawY - 120,
 })
+
+// Null-safe — safe to pass a ref directly without defensive branching
+scrollElementIntoView(ref.current, { headerOffset: 96 })
 ```
 
-> **Why not `element.scrollIntoView()`?** That API re-targets continuously as the page reflows during the animation, causing visible jitter when sibling content is also moving. Pre-computing a fixed pixel value lets the browser commit to a clean, uninterrupted animation.
+**Behaviors at a glance:**
+
+- **Scroll container auto-detection** — drives the nearest `overflow-y: auto/scroll` ancestor (e.g. OpenFrame's `<main class="overflow-y-auto">`) rather than always targeting `window`
+- **Anchoring immunity** — per-frame instant writes mean there is no native smooth scroll for browser scroll anchoring or `focus()` to abort
+- **Live target recomputation** — target pixel is recalculated each frame, so a drawer still expanding is tracked to its resting position
+- **User takeover** — `wheel` and `touchmove` cancel the tween immediately; the user is never fought
+- **`prefers-reduced-motion`** — falls back to a single synchronous write automatically
+
+## Source
+
+[`scroll-into-view.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/scroll-into-view.ts)

package/src/utils/.seo-description.md

@@ -0,0 +1,37 @@
+<!-- source-hash: a978a1280534da5c75f87c43d8c70e25 -->
+Defines and exports the single source of truth for the `seo_description` field length constraint, enforcing a hard database-level character cap.
+
+## Key Components
+
+| Export | Type | Value | Description |
+|--------|------|-------|-------------|
+| `SEO_DESCRIPTION_MAX_LENGTH` | `number` | `160` | Hard cap matching the `varchar(160)` DB column constraint |
+
+## Usage Example
+
+```typescript
+import { SEO_DESCRIPTION_MAX_LENGTH } from '@flamingo-stack/openframe-frontend-core/utils';
+
+// UI input enforcement
+<input maxLength={SEO_DESCRIPTION_MAX_LENGTH} />
+
+// AI prompt guidance
+const prompt = `Generate a description under ${SEO_DESCRIPTION_MAX_LENGTH} characters.`;
+
+// Validation guard
+if (description.length > SEO_DESCRIPTION_MAX_LENGTH) {
+  throw new Error(`SEO description exceeds ${SEO_DESCRIPTION_MAX_LENGTH} character limit.`);
+}
+```
+
+## Notes
+
+> **Hard cap** — unlike `seo_title` (a soft search-engine recommendation), this limit is enforced at the database level (`varchar(160)`). Postgres will reject values exceeding it outright.
+
+**Known consumers:**
+- `SEOEditorPreview` — binds `maxLength` and renders an over-length alert
+- The hub — uses this constant for AI generation prompt guidance and the rewrite-to-fit helper
+
+---
+
+**Source:** [`seo-description.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/seo-description.ts)

package/src/utils/.seo-title.md

@@ -0,0 +1,25 @@
+<!-- source-hash: 822bf336cf43bc797363ba147feae651 -->
+Defines and exports the single source of truth for the `seo_title` field length budget used across SEO tooling, AI generation prompts, and database validation.
+
+## Key Components
+
+- **`SEO_TITLE_MAX_LENGTH`** — Constant (`60`) representing the maximum character length for an SEO title, aligned with search engine truncation thresholds.
+
+## Usage Example
+
+```typescript
+import { SEO_TITLE_MAX_LENGTH } from '@flamingo-stack/openframe-oss-lib/seo-title';
+
+// Validate an SEO title before saving
+if (title.length > SEO_TITLE_MAX_LENGTH) {
+  throw new Error(`SEO title must be ${SEO_TITLE_MAX_LENGTH} characters or fewer.`);
+}
+```
+
+## Notes
+
+- The `seo_title` is rendered **verbatim** as the HTML `<title>` tag — no brand suffix is appended (unlike the default title fallback).
+- The value `60` reflects the widely accepted character limit before search engines truncate page titles in results.
+- Consumers include:
+  - **`SEOEditorPreview`** — drives the `maxLength` attribute on the input field and triggers the too-long alert.
+  - **The hub** — imported via `@flamingo-stack/openframe-frontend-core/utils` for AI prompt guidance and database `CHECK` constraint values.

package/src/utils/.social-embed-cache.md

@@ -0,0 +1,37 @@
+<!-- source-hash: 9f786a0730fdf75c06716b087e1f5b2f -->
+Unified social media embed caching singleton that provides a three-tier cache hierarchy (memory → server → direct fetch) for Reddit and Twitter embed clients, with request deduplication and async background refresh.
+
+## Key Components
+
+- **`SocialEmbedCache`** — Singleton class exposing all cache operations
+- **`CacheOptions`** — Interface defining `platform`, `url`, and `apiEndpoint` per-call inputs
+- **`getFromMemory / setInMemory`** — In-process `Map`-backed cache layer
+- **`getFromServer`** — Checks the server-side cache via `?cache-only=true` query param
+- **`setInServer`** — Writes data to the server cache with promise-level deduplication via `cachingRequests`
+- **`fetchWithHierarchy`** — Orchestrates the full lookup chain: memory → server cache → Reddit direct browser fetch → server proxy fallback
+- **`scheduleAsyncRefresh`** — Fires a background refresh 1 second after load to keep the server cache warm without blocking the consumer
+- **`fetchDirect`** — Thin wrapper around a caller-supplied `directFetcher` function with uniform logging
+
+## Usage Example
+
+```typescript
+import { SocialEmbedCache } from './social-embed-cache';
+
+const cache = SocialEmbedCache.getInstance();
+
+await cache.fetchWithHierarchy({
+  platform: 'reddit',
+  url: 'https://www.reddit.com/r/example/comments/abc123/.json',
+  apiEndpoint: '/content/api/blog/reddit-proxy',
+  dataValidator: (data) => Array.isArray(data) && data.length > 0,
+  onDataUpdate: (data) => setEmbedData(data),
+  onError: (msg) => setError(msg),
+  onLoading: (loading) => setLoading(loading),
+});
+```
+
+> **Note:** Pass `apiEndpoint` on each call to route through your own reverse proxy rather than a hard-coded hub path. The singleton is pure TypeScript with no React dependency, making it safe to share across any embed satellite.
+
+## Source
+
+[`social-embed-cache.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/social-embed-cache.ts)

package/src/utils/.source-icons.md

@@ -1,16 +1,23 @@
-<!-- source-hash: 4129d05ad3798983504dba26d6153a8c -->
-Maps RAG table IDs to their display icons, human-readable labels, and document type lookups for the OpenFrame chat source chip system. Server-safe with no client-only imports.
+<!-- source-hash: 64605009d59b6e0fa3559c548a66b58b -->
+Provides static lookup maps and helper functions for resolving RAG table IDs to icon names, display labels, and document type mappings — designed to be server-safe so both server-side chat route handlers and client-side components can import from a single source.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `SOURCE_ICON_NAMES` | `Record<string, string>` | Maps `RagTableConfig.id` → icon name string (resolved to React components via `icon-registry.ts`) |
-| `SOURCE_LABELS_BY_TABLE` | `Record<string, string>` | Maps `RagTableConfig.id` → human-readable display label used in chat source chips |
-| `DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID` | `Record<string, string>` | Reverse maps LLM-emitted `documentType` strings → `RagTableConfig.id` |
-| `getSourceIconName()` | Function | Safe lookup returning `undefined` for unknown table IDs |
-| `getSourceLabel()` | Function | Lookup with fallback to raw table slug when no label is registered |
-| `defaultTableIdForDocumentType()` | Function | Default resolver for `useEmbeddedChat` when no custom callback is provided; returns `null` for unknown types |
+### Constants
+
+| Export | Purpose |
+|---|---|
+| `SOURCE_ICON_NAMES` | Maps `RagTableConfig.id` → icon name string (resolved to a React component client-side via `icon-registry.ts`) |
+| `SOURCE_LABELS_BY_TABLE` | Maps `RagTableConfig.id` → human-readable display label used in chat chip strips |
+| `DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID` | Reverse map from LLM-emitted `documentType` strings → `RagTableConfig.id` |
+
+### Functions
+
+| Export | Signature | Behavior |
+|---|---|---|
+| `getSourceIconName` | `(tableId: string \| null \| undefined) => string \| undefined` | Returns icon name or `undefined` (caller decides fallback) |
+| `getSourceLabel` | `(tableId: string) => string` | Returns display label; falls back to raw `tableId` slug if unmapped |
+| `defaultTableIdForDocumentType` | `(documentType: string) => string \| null` | Default resolver for `useEmbeddedChat`; returns `null` for unknown types |
 
 ## Usage Example
 
@@ -21,33 +28,22 @@ import {
   defaultTableIdForDocumentType,
 } from '@/utils/source-icons'
 
-// Resolve icon name for a known RAG table
-const iconName = getSourceIconName('github-commits')
-// → 'github'
-
-// Get display label for a chip strip
-const label = getSourceLabel('hubspot-tickets-anon')
-// → 'Tickets'
+// Resolve icon name for a chip strip glyph
+const iconName = getSourceIconName('github-commits') // → 'github'
 
-// Map a documentType emitted by the LLM to its table ID
-const tableId = defaultTableIdForDocumentType('slack_message')
-// → 'slack-messages'
+// Resolve display label for a sub-message chip
+const label = getSourceLabel('hubspot-tickets-self') // → 'My Tickets'
+getSourceLabel('unknown-table')                      // → 'unknown-table' (fallback)
 
-// Graceful handling of unknown types
-const unknown = defaultTableIdForDocumentType('custom_type')
-// → null
+// Map an LLM-emitted documentType to its RAG table
+const tableId = defaultTableIdForDocumentType('slack_message') // → 'slack-messages'
+defaultTableIdForDocumentType('custom_type')                   // → null
 ```
 
-## Supported Source Categories
+## Architecture Notes
 
-| Category | Tables Covered |
-|----------|---------------|
-| **Docs** | `openframe-docs`, `data-room-docs` |
-| **CMS / Programs** | Blog posts, releases, case studies, webinars, events, podcasts, interviews |
-| **Financials** | KPIs, cap table, P&L, balance sheet, cash flow, investor updates |
-| **ClickUp** | Roadmap, delivery, internal tasks |
-| **GitHub** | Commits, PRs, PR reviews (public + internal variants) |
-| **HubSpot** | Tickets (full, anon, self) |
-| **Communications** | Slack messages |
+- **Server-safe by design** — no `'use client'` banner; icon *names* live here while icon *components* remain client-only in `src/components/chat/utils/icon-registry.ts`.
+- The client-side chat barrel re-exports these helpers for ergonomic imports.
+- `DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID` mirrors the hub's `tableIdForDocumentType()` registry; embedders needing tenant-specific overrides pass a custom callback to `useEmbeddedChat` instead.
 
-> **Design note:** Icon names are intentionally decoupled from React components — the resolver (`icon-registry.ts`) stays client-only while this file remains server-safe, allowing hub-side RAG mappers and chat route handlers to call these utilities directly.
+**Source:** [`src/utils/source-icons.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/source-icons.ts)

package/src/utils/.suggestion-url.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 6fc430d117cdf20c7781e51705df5734 -->
+Composes fetch URLs for suggestion sections (FaqSection and RelatedContentSection) with a consistent query parameter shape, ensuring the two consumers never drift in their `entityType`/`entityId`/`count` parameter ordering.
+
+## Key Components
+
+### `SuggestionUrlOptions`
+Configuration interface controlling URL construction:
+
+| Property | Type | Description |
+|---|---|---|
+| `apiBaseUrl` | `string?` | Prefix for third-party embeds or reverse proxies; defaults to same-origin relative (`''`) |
+| `entityType` | `string?` | Entity scope qualifier; must be paired with `entityId` |
+| `entityId` | `number \| string?` | Entity scope qualifier; must be paired with `entityType` |
+| `count` | `number?` | Maps to the server's `count` param; omitted when undefined (server default applies) |
+| `extraParams` | `Record<string, string \| undefined>?` | Additional query params appended after the shared trio; empty/undefined values are skipped |
+
+### `buildSuggestionUrl(path, opts)`
+Pure, server-safe function that assembles the final URL string. Parameter ordering is fixed: `entityType` → `entityId` → `count` → `extraParams`. Both `entityType` and `entityId` must be non-empty to be included; a partial pair is silently dropped.
+
+## Usage Example
+
+```typescript
+// Same-origin relative URL with entity scope
+buildSuggestionUrl('/api/faqs', {
+  entityType: 'article',
+  entityId: 42,
+  count: 5,
+})
+// → '/api/faqs?entityType=article&entityId=42&count=5'
+
+// Absolute URL with extra params and no entity scope
+buildSuggestionUrl('/api/related', {
+  apiBaseUrl: 'https://api.example.com',
+  count: 10,
+  extraParams: { excludeTypes: 'video,file', draft: undefined }, // 'draft' skipped
+})
+// → 'https://api.example.com/api/related?count=10&excludeTypes=video%2Cfile'
+
+// Bare path — no query string appended
+buildSuggestionUrl('/api/faqs')
+// → '/api/faqs'
+```
+
+## Source
+
+[`suggestion-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/suggestion-url.ts)

package/src/utils/.tool-utils.md

@@ -1,40 +1,55 @@
-<!-- source-hash: 6ea14bfd05bc32d44e0bdda863e8da6c -->
-Provides normalization and conversion utilities for tool types across the Flamingo platform. Handles various input formats (aliases, case variations) and converts them to canonical ToolType values used throughout the system.
+<!-- source-hash: 656c2a7658a961c816d272983ab9827c -->
+Provides normalization and conversion utilities for mapping tool name variants (aliases, case variations, separator styles) to canonical `ToolType` values used across the OpenFrame platform.
 
 ## Key Components
 
-- **`normalizeToolType()`** - Converts tool name variants to canonical ToolType, returns undefined for invalid inputs
-- **`normalizeToolTypeWithFallback()`** - Same as above but defaults to 'SYSTEM' for invalid inputs
-- **`toToolLabel()`** - Converts any tool name variant to its display label
-- **`isValidToolType()`** - Validates if a string can be normalized to a valid ToolType
-- **`getToolTypeAliases()`** - Returns all valid aliases for a given canonical ToolType
-- **`getToolLabel()`** - Gets display label for a canonical ToolType
-- **`toolAliasMap`** - Internal mapping of tool name variants to canonical types
+| Export | Description |
+|---|---|
+| `normalizeToolType(input?)` | Converts any tool name variant to a canonical `ToolType`; returns `undefined` if no match |
+| `normalizeToolTypeWithFallback(input?)` | Same as above but defaults to `'SYSTEM'` when no match is found |
+| `toToolLabel(input?)` | Converts any tool name variant to its human-readable display label |
+| `isValidToolType(input?)` | Returns `true` if the input resolves to a known `ToolType` |
+| `getToolTypeAliases(toolType)` | Returns all alias strings that map to a given canonical `ToolType` |
+| `getToolLabel(toolType)` | Returns the display label for a canonical `ToolType` |
+| `toolAliasMap` | Internal lookup table covering all supported tools: `FLEET_MDM`, `MESHCENTRAL`, `AUTHENTIK`, `OPENFRAME`, `OPENFRAME_CHAT`, `OPENFRAME_CLIENT`, `OPENFRAME_RMM`, `OSQUERY`, `SYSTEM` |
 
 ## Usage Example
 
 ```typescript
-import { 
-  normalizeToolType, 
-  normalizeToolTypeWithFallback, 
+import {
+  normalizeToolType,
+  normalizeToolTypeWithFallback,
   toToolLabel,
-  isValidToolType 
+  isValidToolType,
+  getToolTypeAliases,
 } from './tool-utils'
 
 // Normalize various input formats
-normalizeToolType('FLEET-MDM')      // => 'FLEET_MDM'
-normalizeToolType('unknown')        // => undefined
+normalizeToolType('rmm')           // => 'OPENFRAME_RMM'
+normalizeToolType('FLEET-MDM')     // => 'FLEET_MDM'
+normalizeToolType('unknown')       // => undefined
 
-// With fallback to SYSTEM
-normalizeToolTypeWithFallback('mesh')    // => 'MESHCENTRAL'
-normalizeToolTypeWithFallback('invalid') // => 'SYSTEM'
+// Safe fallback for unknown inputs
+normalizeToolTypeWithFallback('unknown')  // => 'SYSTEM'
 
-// Convert to display labels
-toToolLabel('fleet_mdm')   // => 'Fleet'
+// Human-readable labels
+toToolLabel('fleet-mdm')  // => 'Fleet'
+toToolLabel('rmm')        // => 'RMM'
 
-// Validation
-isValidToolType('authentik')  // => true
-isValidToolType('invalid')    // => false
+// Validation guard
+if (isValidToolType(userInput)) {
+  // safe to use as ToolType
+}
+
+// Enumerate all aliases for a tool (e.g. docs or validation UI)
+getToolTypeAliases('FLEET_MDM')
+// => ['FLEET', 'FLEET_MDM', 'FLEET-MDM', 'FLEETMDM', 'fleet', ...]
 ```
 
-The utility supports all major MSP tools including Fleet MDM, MeshCentral, Authentik, and OpenFrame components with comprehensive alias mapping for different naming conventions.
+## Notes
+
+- Resolution order: exact match → uppercase → lowercase
+- All separator styles are supported: underscores (`FLEET_MDM`), hyphens (`fleet-mdm`), and concatenated (`fleetmdm`)
+- Agent suffixes like `fleetmdm-agent` and `openframe-rmm-agent` are included in the alias map
+
+**Source:** [`tool-utils.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool-utils.ts)

package/src/utils/.tree-builder.md

@@ -0,0 +1,64 @@
+<!-- source-hash: e02e3bf5bd0b2062565eb3542938d795 -->
+Builds hierarchical document trees from flat record lists using a generic 3-pass algorithm, shared across all doc-source DALs in the OpenFrame platform.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `TreeNodeBase` | Interface | Base shape for tree nodes — extend with domain-specific fields |
+| `formatDocName` | Function | Strips `.md` extension, handles `README` casing, and humanizes hyphenated names |
+| `sortTreeChildren` | Function | Recursively sorts nodes: README first → folders → files, each sub-group ordered by `sortOrder` then alphabetically |
+| `buildDocumentTree` | Function | Generic 3-pass tree builder accepting mapper and path resolver callbacks |
+
+## 3-Pass Algorithm
+
+```mermaid
+graph TD
+    Pass1["Pass 1: Map flat records to nodes"] --> Pass2["Pass 2: Resolve parent paths and build hierarchy"]
+    Pass2 --> Pass3["Pass 3: Sort children recursively"]
+    Pass3 --> Root["Return root nodes"]
+```
+
+## Usage Example
+
+```typescript
+import { buildDocumentTree, formatDocName, TreeNodeBase } from './tree-builder'
+
+interface DocNode extends TreeNodeBase {
+  slug: string
+}
+
+interface DbDoc {
+  path: string
+  parent_path: string | null
+  name: string
+  type: 'file' | 'folder'
+}
+
+const docs: DbDoc[] = fetchDocsFromDb()
+
+const tree = buildDocumentTree<DocNode, DbDoc>(
+  docs,
+  (doc) => ({
+    id: doc.path,
+    name: formatDocName(doc.name),
+    path: doc.path,
+    type: doc.type,
+    slug: doc.path.split('/').pop() ?? '',
+    children: [],
+  }),
+  (doc) => doc.parent_path,  // Pass 2: explicit parent path
+  (doc) => doc.path          // Pass 2: node's own path key
+)
+```
+
+## Sort Order
+
+| Priority | Rule |
+|---|---|
+| 1 | `README` / `readme.md` always first |
+| 2 | Folders before files |
+| 3 | Ascending `sortOrder` (nodes without it sort last) |
+| 4 | Alphabetical (locale-insensitive) |
+
+**Source:** [`lib/tree-builder.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/lib/tree-builder.ts)

package/src/utils/.video-bite-id.md

@@ -0,0 +1,42 @@
+<!-- source-hash: a8a83c1fb84a9906fd7502112718264a -->
+Isomorphic SSOT module for stable per-element identity on `video_bites` / `teasers` JSONB array elements. Provides ID generation, ID stamping, and the canonical element-matching predicate shared across the admin editor (browser) and Mux reconciliation sweep (Node).
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `BiteIdentity` | Interface | Identity-relevant subset of `VideoTeaser` (`id?`, `url`, `source_url?`) |
+| `BITE_ID_RE` | `RegExp` | Validates 8 lowercase hex char IDs — collision-safe within a single array |
+| `generateBiteId()` | Function | Produces a new 8-hex ID via `crypto.randomUUID()` |
+| `ensureBiteIds()` | Function | Stamps missing IDs and re-stamps in-array duplicates; returns same reference when unchanged |
+| `matchBiteElement()` | Function | Canonical three-leg predicate for identifying the same clip across array states |
+
+## Usage Example
+
+```typescript
+import { ensureBiteIds, matchBiteElement } from './video-bite-id'
+
+// Stamp incoming bites before persistence
+const { bites, changed } = ensureBiteIds(rawBites)
+if (changed) await persistBites(bites)
+
+// Match an incoming element against the existing array (multiset — consume each existing once)
+const matched = existingBites.find(existing => matchBiteElement(existing, incoming))
+if (matched) {
+  // Carry matched.id forward — id equality, url match, or source_url flip
+}
+```
+
+## Matching Legs
+
+`matchBiteElement` uses an **any-of** strategy (not short-circuit on ID mismatch) to handle cases where two sides represent the same clip with different IDs:
+
+1. **ID equality** — both sides carry an ID and they match
+2. **URL equality** — `incoming.url === existing.url` (pre-flip sessions, plain re-saves)
+3. **Source URL flip** — `incoming.url === existing.source_url` (Mux HLS pipeline already flipped the URL; redelivered Vizard ingests)
+
+> **Caller contract:** When matching a whole incoming array, each existing element must be consumed at most once to prevent duplicate incoming URLs from cloning a single element's ID.
+
+---
+
+**Source:** [`video-bite-id.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-bite-id.ts)