@kitn.ai/ui/dist/primitives/embed-providers.d.ts

Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.

import { CardEnvelope } from './card-contract';
/** Media provider for an embed card. */
export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
export interface EmbedCardData {
    /** Media provider. 'generic' frames `url` directly. */
    provider: EmbedProvider;
    /** Provider video id (youtube/vimeo) when not parsing from `url`. */
    id?: string;
    /** Full media/watch/embed URL. */
    url?: string;
    /** Accessible iframe title + poster label. */
    title?: string;
    /** Thumbnail before play; derived for youtube/vimeo when omitted. */
    poster?: string;
    /** Start offset, seconds. */
    start?: number;
    /** Player aspect ratio. Default '16:9'. */
    aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
}
/** The full envelope an agent/server emits for an embed card. */
export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
/** The `type` discriminator for embed cards. */
export declare const EMBED_CARD_TYPE: "embed";
export interface ResolvedEmbed {
    /** The iframe src loaded on play (already including autoplay/start params). */
    embedUrl: string;
    /** Poster/thumbnail to show before play (derived when not supplied). */
    posterUrl?: string;
    /** sandbox attribute for the player iframe. */
    sandbox: string;
    /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
    allow: string;
}
/**
 * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
 * normalized via the URL parser (scheme + host + port). Only https origins are
 * accepted (a non-https origin is ignored). Call once at app startup.
 */
export declare function configureEmbedAllowlist(origins: string[]): void;
/** True when `url`'s origin has been allowlisted for `generic` embeds. */
export declare function isGenericOriginAllowed(url: string): boolean;
/** Test-only: clear the generic allowlist so tests stay isolated. */
export declare function __resetEmbedAllowlistForTests(): void;
/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
export declare function parseYouTubeId(url: string): string | undefined;
/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
export declare function parseVimeoId(url: string): string | undefined;
/**
 * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
 * Throws (with a human message) on a missing/invalid provider id, a non-https
 * generic URL, or a generic origin not in the app allowlist — the card turns these
 * into an inline error + an `error` event.
 */
export declare function resolveEmbed(data: EmbedCardData): ResolvedEmbed;
/**
 * The canonical "watch on the provider" URL for the optional fallback affordance
 * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
 * when there is nothing useful to link to.
 */
export declare function watchUrl(data: EmbedCardData): string | undefined;
/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
export declare function providerLabel(provider: EmbedProvider): string;
/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
export declare function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string;