<!-- source-hash: f8a0a33feba94cc42bfec8295a8e57f2 -->
Determines whether a navigation action should open in a new browser tab, using a prioritized rule chain to handle embed mode, explicit overrides, platform comparisons, and cross-origin fallbacks.

## Key Components

### Types
- **`NavSurface`** — Labels the calling surface (`'useNavLink'` | `'useUnifiedNav'`) for trace logging
- **`RuntimeMode`** — Chat runtime context (`'host'` | `'embed'`)
- **`DecideNewTabInput`** — Input shape for the decision function

### Function
- **`decideNewTab(input: DecideNewTabInput): boolean`** — Returns `true` if navigation should open a new tab

## Branch Priority

| Priority | Condition | Result |
|----------|-----------|--------|
| 1 | `runtimeMode === 'embed'` | Always new tab |
| 2 | `openIn === 'new-tab'` | New tab |
| 3 | `alwaysNewTab === true` | New tab |
| 4 | `openIn === 'same-tab'` | Same tab |
| 5 | `targetPlatform` defined + `currentSource` non-empty | New tab if platforms differ |
| 6 | Fallback: `isCrossOriginUrl(href)` | New tab if cross-origin |

## Usage Example

```typescript
import { decideNewTab } from './decide-new-tab'

// Embed mode — always opens new tab regardless of other options
decideNewTab({
  href: '/dashboard',
  currentSource: 'flamingo',
  runtimeMode: 'embed',
}) // → true

// Platform comparison — cross-app link
decideNewTab({
  href: '/tickets',
  targetPlatform: 'openframe',
  currentSource: 'flamingo',
}) // → true (different platforms)

// Explicit override
decideNewTab({
  href: '/settings',
  openIn: 'same-tab',
  currentSource: 'flamingo',
  runtimeMode: 'host',
}) // → false
```