<!-- source-hash: 788b2f31d1bae5bb48d44855c468c228 -->
Defines the single source of truth for all platform domain registrations and derives host resolution, cookie base-domain sets, URL normalization, and preview detection from one central registry table.

## Key Components

### Types & Registry

- **`PlatformDomainKey`** — Union of `PlatformName` plus the forward-only `'openframe-dashboard'`
- **`PlatformDomainEntry`** — Shape of each registry row: `key`, `defaultUrl`, `envVar`, optional `aliasHostnames`, optional `pseudo` flag
- **`PLATFORM_DOMAINS`** — Readonly registry array; ordering is load-bearing (`flamingo` must precede `flamingo-teaser` and `universal`)

### URL Resolution

- **`getPlatformProductionUrl(platform)`** — Returns the effective URL: env override → `defaultUrl` → flamingo fallback; always scheme-safe
- **`ensureScheme(url)`** — Normalizes bare-host or protocol-relative env overrides to `https://`; exported as the single owner of this rule
- **`byKey(key)`** — Looks up a registry entry by platform key

### Host Utilities

- **`hostOf(value)`** — Parses a URL to its lowercase, port-stripped hostname; returns `null` on failure
- **`expandWwwApex(host)`** — Expands a host to its `www.`/apex pair for reverse matching
- **`toRegistrableBaseDomain(host)`** — Extracts the registrable base domain (e.g. `flamingo.run`)
- **`getPlatformByHostname(hostname)`** — Reverse resolves a hostname to a platform key (first-wins, non-pseudo only)

### Preview Detection

- **`isPreviewEnv()`** — Checks `VERCEL_ENV === 'preview'`
- **`isPreviewHost(hostname)`** — Checks for `*.vercel.app` suffix

### Cookie SSO

- **`getAllPlatformBaseDomains()`** — ⚠️ Non-pure. Returns the cross-subdomain SSO cookie domain set; branches on localhost, Vercel preview, and production

## Usage Example

```typescript
import {
  getPlatformProductionUrl,
  getPlatformByHostname,
  getAllPlatformBaseDomains,
  ensureScheme,
} from './platform-domains'

// Resolve the effective URL for a platform (env override or default)
const url = getPlatformProductionUrl('openframe')
// → 'https://openframe.ai' (or NEXT_PUBLIC_OPENFRAME_URL if set)

// Normalize a bare-host env override
ensureScheme('hub.openframe.ai')
// → 'https://hub.openframe.ai'

// Reverse-resolve an incoming request hostname to a platform key
getPlatformByHostname('www.openframe.ai')
// → 'openframe'

// Get all cookie base domains for cross-hub SSO (client-side only)
getAllPlatformBaseDomains()
// → ['.flamingo.run', 'flamingo.run', '.openframe.ai', 'openframe.ai', ...]
```

## Notes

- **Edge-safe and pure** — no React, no Node builtins, no `server-only`; safe in middleware (`proxy.ts`), `'use client'` providers, and `server-only` modules simultaneously
- **Compile-time guards** — `satisfies` checks enforce bidirectional consistency between `PLATFORM_DOMAINS` and `ENV_OVERRIDES`; a missing or stale env var fails the build
- **Ordering invariant** — `flamingo` must appear before `flamingo-teaser` and `universal` in the registry; a module-load self-check enforces this at runtime