<!-- source-hash: d2815a723188c45f4c5d2910a19ffd76 -->
Aspect-ratio tab and grouping primitives for video grids, used by `VideoBitesDisplay` and admin editors to render portrait, square, and landscape clips in cohesive tabbed groups.

## Key Components

### Types & Interfaces
- **`VizardAspectRatio`** — Union type for Vizard clip ratios: `'9:16' | '16:9' | '1:1'`
- **`VideoTeaserWithRatio`** — Extends `VideoTeaser` with `aspect_ratio`, `confidence`, `viral_reason`, and timing metadata
- **`RatioCategory`** — Grid grouping label: `'portrait' | 'square' | 'landscape'`

### Constants
- **`RATIO_GRID_CLASS`** — Tailwind grid classes for admin editor views (narrower columns)
- **`RATIO_DISPLAY_GRID_CLASS`** — Tailwind grid classes for public display pages (wider columns)

### Components
- **`RatioTabs`** — Tab wrapper that only renders tabs with content; auto-collapses to flat render when only one ratio group is populated; uses `forceMount` to prevent scroll-jump on tab switch

### Utilities
- **`detectAspectRatio(ratioString?, width?, height?)`** — Resolves a `VizardAspectRatio` from a string, falling back to dimension inference, defaulting to `'9:16'`
- **`ratioToCategory(ratio)`** — Maps `VizardAspectRatio` → `RatioCategory`
- **`groupByAspectRatio(items, getAspectRatio)`** — Buckets any item array into `{ portrait, square, landscape, hasMultiple }`

## Usage Example

```typescript
import {
  RatioTabs,
  groupByAspectRatio,
  detectAspectRatio,
  ratioToCategory,
  RATIO_DISPLAY_GRID_CLASS,
} from './video-ratio-tabs';

// Group clips by detected aspect ratio
const { portrait, square, landscape, hasMultiple } = groupByAspectRatio(
  clips,
  (clip) => detectAspectRatio(clip.aspect_ratio, clip.width, clip.height),
);

// Render with tabbed UI
<RatioTabs
  groups={{
    portrait: {
      count: portrait.length,
      render: () => (
        <div className={RATIO_DISPLAY_GRID_CLASS.portrait}>
          {portrait.map((c) => <ClipCard key={c.id} clip={c} />)}
        </div>
      ),
    },
    square: { count: square.length, render: () => <SquareGrid items={square} /> },
    landscape: { count: landscape.length, render: () => <LandscapeGrid items={landscape} /> },
  }}
  defaultTab="portrait"
/>
```