> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withheadlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Known footguns

# Known footguns

## Trailing slash on frameOrigin

Mint compares exact strings. `https://partner.com/` will fail if the allowlist entry is `https://partner.com`. CloudFront `frame-ancestors` also matches bare origins.

## Cloudflare orange cloud

Proxy mode rewrites bytes and headers. Immutable pinning verification and CSP assertions will fail even when the page appears to work.

## Mutable embed URLs

Never serve `/chart/latest`. Pin `/chart/v<semver>/index.html` and fail CI if the S3 prefix already exists. CloudFront has no directory-index rewrite, so `/chart/v<semver>/` will not load the chart.

## TOKEN\_KEY\_UNKNOWN after key rotation

Public keys are baked into pinned bundles. Key rotation requires shipping a new embed version and updating the partner pin.

## Global allowlist

`EMBED_ALLOWED_FRAME_ORIGINS` is one list for all partners in MVP. Any allowed origin can frame using another partner's token until per-partner scoping exists.

## SDK copy vs npm

MVP docs use a copied snippet (\~40 lines). An npm package is optional later; a script tag from our CDN is rejected because it places Headlight code in the partner origin.

## postMessage targetOrigin

Always pass the embed CDN origin to `postMessage`. Using `*` defeats origin checks on the parent side.