@flamingo-stack/openframe-frontend-core 0.0.445 → 0.0.446-snapshot.20260717214810

package/src/components/features/mux-origins.ts

@@ -1,12 +1,17 @@
 /**
- * Mux CDN origin constants — single source of truth, server-safe.
+ * Mux CDN origins + playback-URL helpers — single source of truth, server-safe.
  *
  * Lives in its own NON-`'use client'` module so server-side hub
  * modules (webhook handlers, URL builders, hostname comparisons in
- * `lib/config/mux-config.ts`) can import these strings without
+ * `lib/config/mux-config.ts`) can import these without
  * tripping Next.js's client-reference poisoning. Re-exported from
  * `use-video-warmup.ts` for backward-compat with client-side callers.
  *
+ * The Mux-HLS detection in `toMuxPreviewUrl` intentionally overlaps the
+ * hub's `lib/config/mux-config.ts` `isMuxHlsUrl` — same documented
+ * cross-repo duplication umbrella as the origin constants (the hub's
+ * server code cannot depend on this package's client-marked siblings).
+ *
  * Bug history (2026-05-29): when these constants lived in
  * `use-video-warmup.ts` (which is `'use client'`), the hub's
  * server-side `new URL(MUX_STREAM_ORIGIN).hostname` evaluation crashed
@@ -25,3 +30,36 @@ export const MUX_STREAM_ORIGIN = 'https://stream.mux.com'
 
 /** Server-generated thumbnails (`/{playback_id}/thumbnail.jpg`). */
 export const MUX_IMAGE_ORIGIN = 'https://image.mux.com'
+
+/** Valid values for Mux's `max_resolution` playback modifier (720p is the floor). */
+export type MuxMaxResolution = '720p' | '1080p' | '1440p' | '2160p'
+
+/**
+ * Cap the renditions offered by a public Mux HLS manifest for small
+ * preview players (e.g. the ~234px video-bite hover cards) by appending
+ * Mux's `max_resolution` playback modifier.
+ *
+ * Why a URL param and not a player prop: MuxPlayer's `maxResolution`
+ * prop only applies when playing via `playbackId` — our SSOT passes
+ * `src` URLs. And on Safari (native HLS, no hls.js) manifest-level
+ * filtering is the ONLY rendition cap; hls.js's `capLevelToPlayerSize`
+ * doesn't exist there.
+ *
+ * Pass-through (returns `url` unchanged) for: non-Mux hosts (Supabase
+ * MP4s, YouTube), non-`.m3u8` paths (MP4 renditions), signed URLs
+ * (`?token=` — Mux forbids loose modifiers alongside a token; they must
+ * live in the JWT), and unparseable strings.
+ */
+export function toMuxPreviewUrl(url: string, maxResolution: MuxMaxResolution = '720p'): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return url
+  }
+  if (parsed.origin !== MUX_STREAM_ORIGIN) return url
+  if (!parsed.pathname.endsWith('.m3u8')) return url
+  if (parsed.searchParams.has('token')) return url
+  parsed.searchParams.set('max_resolution', maxResolution)
+  return parsed.toString()
+}

package/src/components/features/policy-configuration-panel.tsx

@@ -1,9 +1,10 @@
 "use client"
 
 import * as React from 'react'
-import { useRef, useEffect, useState } from 'react'
+import { useEffect, useState } from 'react'
 import { ChevronDown, Shield } from 'lucide-react'
 import { cn } from '../../utils/cn'
+import { useCollapsible } from '../chat/hooks/use-collapsible'
 import { ToolIcon } from '../tool-icon'
 import { Button } from '../ui/button'
 import {
@@ -19,21 +20,22 @@ import {
   PolicyConfigurationPanelProps
 } from '../../types/permissions'
 
-const approvalLevelOptions: { value: ApprovalLevel; label: string }[] = [
-  { value: 'ALLOW', label: 'Allow' },
-  { value: 'ASK_USER', label: 'Ask User' },
-  { value: 'ASK_TECHNICIAN', label: 'Ask Technician' },
-  { value: 'DENY', label: 'Restrict' },
-]
-
-const getApprovalLevelLabel = (level: ApprovalLevel | undefined, editMode: boolean = false): string => {
-  if (!level) {
-    return editMode ? 'Set Global Permission' : ''
-  }
-  const option = approvalLevelOptions.find(opt => opt.value === level)
-  return option?.label || level
+const approvalLevelLabels: Record<ApprovalLevel, string> = {
+  ALLOW: 'Allow',
+  ASK_USER: 'Ask User',
+  ASK_TECHNICIAN: 'Ask Technician',
+  DENY: 'Restrict',
 }
 
+const approvalLevelOptions = (Object.keys(approvalLevelLabels) as ApprovalLevel[]).map(
+  value => ({ value, label: approvalLevelLabels[value] })
+)
+
+const POLICY_LEVEL_WIDTH = 'w-[180px]'
+const CATEGORY_LEVEL_WIDTH = 'w-[256px]'
+
+const getApprovalLevelLabel = (level: ApprovalLevel): string => approvalLevelLabels[level] ?? level
+
 const ApprovalLevelDropdown: React.FC<{
   value: ApprovalLevel | undefined;
   onChange: (level: ApprovalLevel | undefined) => void;
@@ -53,7 +55,7 @@ const ApprovalLevelDropdown: React.FC<{
           triggerClassName
         )}
       >
-        {getApprovalLevelLabel(value, true)}
+        {value ? getApprovalLevelLabel(value) : 'Set Global Permission'}
       </Button>
     </DropdownMenuTrigger>
     <DropdownMenuContent align="end" className={contentClassName}>
@@ -106,7 +108,7 @@ const PolicyRow: React.FC<{
               value={policy.approvalLevel}
               onChange={handleChange}
               triggerClassName="w-full"
-              contentClassName="w-[180px]"
+              contentClassName={POLICY_LEVEL_WIDTH}
             />
           </div>
         ) : policy.approvalLevel ? (
@@ -122,11 +124,11 @@ const PolicyRow: React.FC<{
           <ApprovalLevelDropdown
             value={policy.approvalLevel}
             onChange={handleChange}
-            triggerClassName="w-[180px]"
-            contentClassName="w-[180px]"
+            triggerClassName={POLICY_LEVEL_WIDTH}
+            contentClassName={POLICY_LEVEL_WIDTH}
           />
         ) : (
-          <div className="px-[var(--spacing-system-sf)] py-[var(--spacing-system-xsf)] w-[180px]">
+          <div className={cn("px-[var(--spacing-system-sf)] py-[var(--spacing-system-xsf)]", POLICY_LEVEL_WIDTH)}>
             {policy.approvalLevel && (
               <span className="text-h4 text-ods-text-primary">
                 {getApprovalLevelLabel(policy.approvalLevel)}
@@ -139,20 +141,6 @@ const PolicyRow: React.FC<{
   )
 }
 
-const useAnimatedHeight = (isExpanded: boolean) => {
-  const [height, setHeight] = useState<number | 'auto'>(0);
-  const contentRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (contentRef.current) {
-      const contentHeight = contentRef.current.scrollHeight;
-      setHeight(isExpanded ? contentHeight : 0);
-    }
-  }, [isExpanded]);
-
-  return { contentRef, height };
-};
-
 const CategorySection: React.FC<{
   category: PermissionCategory;
   editMode: boolean;
@@ -171,7 +159,7 @@ const CategorySection: React.FC<{
   onBulkLevelChange,
   onPolicyPermissionChange
 }) => {
-  const { contentRef, height } = useAnimatedHeight(isExpanded);
+  const { innerRef, containerStyle } = useCollapsible({ expanded: isExpanded, durationMs: 300 })
   const handleBulkChange = (level: ApprovalLevel | undefined) => onBulkLevelChange(category.id, level)
 
   return (
@@ -203,7 +191,7 @@ const CategorySection: React.FC<{
                 onChange={handleBulkChange}
                 allowClear
                 triggerClassName="w-full"
-                contentClassName="w-[256px]"
+                contentClassName={CATEGORY_LEVEL_WIDTH}
               />
             </div>
           )}
@@ -216,15 +204,12 @@ const CategorySection: React.FC<{
               value={bulkLevel}
               onChange={handleBulkChange}
               allowClear
-              triggerClassName="w-[256px]"
-              contentClassName="w-[256px]"
+              triggerClassName={CATEGORY_LEVEL_WIDTH}
+              contentClassName={CATEGORY_LEVEL_WIDTH}
             />
           </div>
         ) : (
-          <div
-            className="hidden md:block px-[var(--spacing-system-sf)] py-[var(--spacing-system-xsf)] w-[256px] shrink-0"
-            onClick={(e) => e.stopPropagation()}
-          />
+          <div className={cn("hidden md:block px-[var(--spacing-system-sf)] py-[var(--spacing-system-xsf)] shrink-0", CATEGORY_LEVEL_WIDTH)} />
         )}
 
         {/* Expand/Collapse Button */}
@@ -248,17 +233,16 @@ const CategorySection: React.FC<{
 
       {/* Policies List */}
       <div
-        ref={contentRef}
         style={{
-          height: height === 'auto' ? 'auto' : `${height}px`,
-          transition: 'height 300ms ease-in-out, opacity 300ms ease-in-out'
+          ...containerStyle,
+          transition: `${containerStyle.transition}, opacity 300ms ease-in-out, visibility 300ms`,
+          // visibility drops collapsed content from the tab order and a11y
+          // tree; its discrete transition delays hiding until the fade ends.
+          visibility: isExpanded ? 'visible' : 'hidden',
         }}
-        className={cn(
-          "overflow-hidden",
-          isExpanded ? "opacity-100" : "opacity-0"
-        )}
+        className={isExpanded ? "opacity-100" : "opacity-0"}
       >
-        <div className="px-[var(--spacing-system-mf)] pb-[var(--spacing-system-mf)] pt-0">
+        <div ref={innerRef} className="px-[var(--spacing-system-mf)] pb-[var(--spacing-system-mf)] pt-0">
           <div className="border border-ods-border rounded-md overflow-hidden">
             {category.policies.map((policy) => (
               <PolicyRow
@@ -297,6 +281,7 @@ export const PolicyConfigurationPanel: React.FC<PolicyConfigurationPanelProps> =
   const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(new Set())
   const [bulkLevels, setBulkLevels] = useState<Record<string, ApprovalLevel | undefined>>({})
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: editMode is the reset trigger, not read in the body
   useEffect(() => {
     setBulkLevels({})
   }, [editMode])

package/src/components/features/release-media-manager.tsx

@@ -2,8 +2,9 @@
 
 import { useState, useRef } from 'react';
 import { Button, Input, Label, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Textarea } from '../ui';
-import { Trash2, Plus, Image as ImageIcon, Video, Upload, Loader2, GripVertical } from 'lucide-react';
+import { Trash2, Plus, Image as ImageIcon, Video as VideoIcon, Upload, Loader2, GripVertical } from 'lucide-react';
 import Image from '../../embed-shims/next-image';
+import { Video } from './video';
 
 export interface ReleaseMediaItem {
   media_type: 'image' | 'video' | 'screenshot' | 'demo';
@@ -113,7 +114,7 @@ export function ReleaseMediaManager({
     switch (type) {
       case 'video':
       case 'demo':
-        return <Video className="w-5 h-5 text-ods-text-secondary" />;
+        return <VideoIcon className="w-5 h-5 text-ods-text-secondary" />;
       default:
         return <ImageIcon className="w-5 h-5 text-ods-text-secondary" />;
     }
@@ -205,12 +206,9 @@ export function ReleaseMediaManager({
                 {item.media_url && (
                   <div className="aspect-video relative bg-ods-bg">
                     {item.media_type === 'video' || item.media_type === 'demo' ? (
-                      <video
-                        src={item.media_url}
-                        className="w-full h-full object-cover"
-                        controls
-                        preload="metadata"
-                      />
+                      // <Video> SSOT (MuxPlayer) — plays Mux HLS + MP4 alike;
+                      // fit="cover" crops to the aspect-video cell.
+                      <Video kind="file" url={item.media_url} fit="cover" className="w-full h-full" />
                     ) : (
                       <Image
                         src={item.media_url}

package/src/components/features/use-video-warmup.ts

@@ -48,6 +48,18 @@ import { useChatRuntime } from '../../contexts/chat-runtime-context'
 export { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from './mux-origins'
 import { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from './mux-origins'
 
+/**
+ * Save-Data detection — the ONE source of truth for "is this a metered
+ * connection". Consumed by the preload gate below and by `video.tsx`'s
+ * default `preload` policy. SSR-safe (returns false on the server).
+ */
+export function saveDataEnabled(): boolean {
+  if (typeof navigator === 'undefined') return false
+  type Connection = { saveData?: boolean }
+  const conn = (navigator as Navigator & { connection?: Connection }).connection
+  return conn?.saveData === true
+}
+
 /**
  * Preconnect-only variant — fires the three video-bearing origin
  * preconnects (Supabase Storage + Mux stream + Mux image) without
@@ -68,6 +80,12 @@ import { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from './mux-origins'
  * any equivalent provider that wires the field) get the origin
  * automatically. The explicit `supabaseStorageOrigin` argument
  * overrides the runtime value when set.
+ *
+ * The hub's `app/layout.tsx` also emits STATIC `<link rel="preconnect">`
+ * tags for the same Mux origins (document-parse-time warmup; React
+ * dedupes against these runtime calls via the matching
+ * crossOrigin="anonymous"). A change to the origin list here must be
+ * mirrored there.
  */
 export function useVideoOriginPreconnect({
   supabaseStorageOrigin,
@@ -139,9 +157,7 @@ export function useVideoWarmup<T extends Element = HTMLDivElement>({
     if (!isNear || !videoUrl || !resolvedOrigin) return
 
     // Save-Data gate — metered connections skip preload.
-    type Connection = { saveData?: boolean }
-    const conn = (navigator as Navigator & { connection?: Connection }).connection
-    if (conn?.saveData === true) return
+    if (saveDataEnabled()) return
 
     // Origin gate: only preload Supabase-hosted MP4s. Mux HLS warms
     // via the manifest fetch when MuxPlayer mounts; YouTube has no

package/src/components/features/video-bites-strip.tsx

@@ -29,6 +29,8 @@ import React, { useMemo, useRef, useState, useEffect } from 'react';
 import { cn } from '../../utils/cn';
 import { Video } from './video';
 import { useVideoWarmup } from './use-video-warmup';
+import { toMuxPreviewUrl } from './mux-origins';
+import { NEAR_VIEWPORT_ROOT_MARGIN } from '../../hooks/use-near-viewport';
 import { detectAspectRatio, RATIO_TO_CSS_ASPECT, ratioToCategory } from './video-ratio-tabs';
 import type { VideoTeaserWithRatio } from './video-ratio-tabs';
 import {
@@ -227,7 +229,16 @@ export function VideoBiteCard({
   const cssAspect = RATIO_TO_CSS_ASPECT[ratioToCategory(detectAspectRatio(bite.aspect_ratio))];
   const targetHref = bite.href ?? sectionHref;
   const hasTarget = !!(targetHref || bite.onNavigate || onBiteNavigate);
+  // Strip keys and navigation stay on the RAW bite.url — only playback gets
+  // the rendition-capped preview URL below, so keys are stable regardless of
+  // the cap and original + clone share one HTTP cache entry per URL.
   const key = cardKey ?? `${bite.url}__${index}`;
+  // Rendition-capped playback URL for this ~234px preview card: public Mux
+  // HLS manifests get `?max_resolution=720p` (the only Safari-side cap —
+  // native HLS ignores hls.js's player-size capping); everything else passes
+  // through unchanged. Used by BOTH the first-frame facade and the hover
+  // player so the two layers share the manifest fetch.
+  const previewUrl = toMuxPreviewUrl(bite.url);
 
   // Hover activation: controlled by the strip (activeKey) or self-managed
   // when rendered standalone (admin editor).
@@ -250,7 +261,7 @@ export function VideoBiteCard({
     if (!el || typeof IntersectionObserver === 'undefined') return;
     const io = new IntersectionObserver(
       entries => setIsNear(entries[0]?.isIntersecting ?? false),
-      { rootMargin: '500px' },
+      { rootMargin: NEAR_VIEWPORT_ROOT_MARGIN },
     );
     io.observe(el);
     return () => io.disconnect();
@@ -392,7 +403,7 @@ export function VideoBiteCard({
               className="object-cover"
             />
           ) : (
-            <Video kind="file" url={bite.url} firstFrameOnly layout="fill" />
+            <Video kind="file" url={previewUrl} firstFrameOnly layout="fill" />
           )}
 
           {/* Play affordance for every non-playing state (resting poster,
@@ -415,10 +426,19 @@ export function VideoBiteCard({
                   it keeps playing. Sound at 50% (pre-activation: muted start +
                   live unmute on the user's first gesture); CHROMELESS — the
                   card's mux-replica badge above is the play affordance for
-                  every non-playing state. */}
+                  every non-playing state.
+
+                  INVARIANTS (do not regress):
+                  - No explicit `preload` — the SSOT default ('metadata',
+                    'none' under Save-Data) buffers manifest + ~1 segment on
+                    mount, which is exactly what makes hover start instant.
+                  - The poster <Image> layer above stays mounted UNDER this
+                    player permanently, and play() is imperative — never gated
+                    on poster load — so there is no black flash and no
+                    loading state between hover and first frame. */}
               <Video
                 kind="file"
-                url={bite.url}
+                url={previewUrl}
                 poster={bite.thumbnail_url}
                 playWhenHovered={isActive}
                 chromeless

package/src/components/features/video-source-selector.tsx

@@ -1,13 +1,14 @@
 "use client";
 
-import React, { useState, useCallback, useEffect } from 'react';
-import { Upload, Sparkles, X, Video, Loader2 } from 'lucide-react';
+import React, { useState, useCallback } from 'react';
+import { Upload, X, Video as VideoIcon } from 'lucide-react';
 import { AIGeneratedBadge } from '../ui/ai-generated-badge';
 import { Button } from '../ui/button';
 import { Input } from '../ui/input';
 import { Label } from '../ui/label';
 import { Badge } from '../ui/badge';
 import { YouTubeIcon } from '../icons/youtube-icon';
+import { Video } from './video';
 
 export type VideoSourceType = 'youtube' | 'uploaded';
 
@@ -48,16 +49,6 @@ export interface VideoSourceSelectorProps {
     onDelete: () => void;
     isAIGenerated?: boolean;
   }>;
-  /**
-   * Optional: resolve the uploaded video URL before it's handed to the DEFAULT
-   * `<video>` preview (no-op when a `VideoPreviewComponent` is supplied — that
-   * component owns its own rendering). Lets a consumer swap a URL that a native
-   * `<video>` can't play — e.g. a Mux HLS manifest (`stream.mux.com/{id}.m3u8`),
-   * which Chrome/Firefox/Edge can't play natively — for a playable MP4. Without
-   * it the URL is used as-is (backward compatible). A rejected resolve degrades
-   * gracefully to the original URL.
-   */
-  resolveVideoUrl?: (url: string) => Promise<string>;
   /** Optional: Upload progress bar component */
   UploadProgressComponent?: React.ComponentType<{
     progress: number;
@@ -95,7 +86,6 @@ export function VideoSourceSelector({
   uploadEmptyText = 'No video uploaded yet. Click "Upload Video" to add one.',
   disabled = false,
   VideoPreviewComponent,
-  resolveVideoUrl,
   UploadProgressComponent,
   title = 'Video',
   showTitle = true,
@@ -149,7 +139,7 @@ export function VideoSourceSelector({
       {/* Section Title */}
       {showTitle && (
         <h3 className="text-h5 text-ods-text-primary flex items-center gap-2">
-          <Video className="h-5 w-5" />
+          <VideoIcon className="h-5 w-5" />
           {title}
         </h3>
       )}
@@ -256,10 +246,8 @@ export function VideoSourceSelector({
                 isAIGenerated={isAIGenerated}
               />
             ) : (
-              // Default simple preview (resolver-aware — see DefaultVideoPreview)
               <DefaultVideoPreview
                 videoUrl={mainVideoUrl}
-                resolveVideoUrl={resolveVideoUrl}
                 onDelete={handleDeleteVideo}
                 disabled={disabled}
               />
@@ -276,55 +264,27 @@ export function VideoSourceSelector({
 }
 
 interface DefaultVideoPreviewProps {
-  /** Uploaded video URL (possibly an HLS manifest a native `<video>` can't play). */
+  /** Uploaded video URL — MP4 or Mux HLS manifest, both playable via <Video>. */
   videoUrl: string;
-  /** Optional resolver → playable MP4 URL; omit for as-is (backward-compatible) behaviour. */
-  resolveVideoUrl?: (url: string) => Promise<string>;
   onDelete: () => void;
   disabled?: boolean;
 }
 
 /**
- * Default `<video>` preview for {@link VideoSourceSelector} when no
- * `VideoPreviewComponent` is supplied. When `resolveVideoUrl` is provided the URL
- * is resolved (e.g. Mux HLS → MP4) before it reaches the native `<video>`, which
- * can't play HLS on Chrome/Firefox/Edge; a rejected resolve degrades to the
- * original URL. Without a resolver the URL is used synchronously, unchanged.
+ * Default preview for {@link VideoSourceSelector} when no
+ * `VideoPreviewComponent` is supplied. Renders through the `<Video>` SSOT
+ * (MuxPlayer), which plays Mux HLS manifests directly on every browser —
+ * no HLS→MP4 resolve step needed for playback.
  */
-function DefaultVideoPreview({ videoUrl, resolveVideoUrl, onDelete, disabled }: DefaultVideoPreviewProps) {
-  // `undefined` only while an async resolve is in flight (first paint); otherwise
-  // the (possibly resolved) URL. Synchronous passthrough when there's no resolver.
-  const [resolvedUrl, setResolvedUrl] = useState<string | undefined>(
-    resolveVideoUrl ? undefined : videoUrl,
-  );
-
-  useEffect(() => {
-    if (!resolveVideoUrl) {
-      setResolvedUrl(videoUrl);
-      return;
-    }
-    // Guard against a late resolve overwriting a newer URL / unmounted preview.
-    let active = true;
-    setResolvedUrl(undefined);
-    resolveVideoUrl(videoUrl)
-      .then((url) => { if (active) setResolvedUrl(url); })
-      .catch(() => { if (active) setResolvedUrl(videoUrl); });
-    return () => { active = false; };
-  }, [videoUrl, resolveVideoUrl]);
-
+function DefaultVideoPreview({ videoUrl, onDelete, disabled }: DefaultVideoPreviewProps) {
   return (
     <div className="relative rounded-lg border border-ods-border overflow-hidden">
-      {resolvedUrl === undefined ? (
-        <div className="w-full h-[200px] flex items-center justify-center bg-black">
-          <Loader2 className="h-6 w-6 animate-spin text-ods-accent" />
-        </div>
-      ) : (
-        <video
-          src={resolvedUrl}
-          className="w-full h-auto max-h-[300px] object-contain bg-black"
-          controls
-        />
-      )}
+      {/* aspect-video box: MuxPlayer fills its container (width/height 100%),
+          so the wrapper must reserve the height the intrinsic-sized native
+          <video> used to provide. */}
+      <div className="w-full aspect-video max-h-[300px]">
+        <Video kind="file" url={videoUrl} />
+      </div>
       <button
         type="button"
         onClick={onDelete}