@kitn.ai/ui/dist/primitives/link-preview.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';
/** Rich link / Open-Graph preview payload. The card renders from this; it never fetches. */
export interface LinkPreviewData {
    /** Canonical destination; opened via the contract `open` verb. */
    url: string;
    /** og:title — falls back to the domain. */
    title?: string;
    /** og:description — clamped to 3 lines. */
    description?: string;
    /** og:image — degrades gracefully when missing/broken. */
    image?: string;
    /** Alt for the preview image (defaults to title / decorative). */
    imageAlt?: string;
    /** Site favicon. */
    favicon?: string;
    /** Display domain; derived from `url` when omitted. */
    domain?: string;
    /** og:site_name; preferred over `domain` when present. */
    siteName?: string;
}
/** The full envelope an agent/server emits for a link preview card. */
export type LinkPreviewEnvelope = CardEnvelope<'link', LinkPreviewData>;
/** The `type` discriminator for link preview cards. */
export declare const LINK_PREVIEW_TYPE: "link";
/** App-supplied resolver: a bare URL → (partial) OG metadata. Usually hits YOUR backend. */
export type LinkMetadataFetcher = (url: string) => Promise<Partial<LinkPreviewData>>;
/**
 * App opt-in: supply a function (usually hitting YOUR backend/proxy) that resolves
 * a bare URL to OG metadata. CORS forbids reading cross-origin HTML in the browser,
 * so there is intentionally NO default network implementation.
 */
export declare function configureLinkPreview(opts: {
    fetchMetadata: LinkMetadataFetcher;
}): void;
/** True when an app has registered a fetcher (the bare-URL path is available). */
export declare function hasLinkPreviewFetcher(): boolean;
/**
 * Used by LinkPreview ONLY when the envelope lacks metadata AND a fetcher is set.
 * Returns the merged metadata or throws (card shows its fallback/error state).
 */
export declare function resolveLinkMetadata(url: string): Promise<Partial<LinkPreviewData>>;
/** Test-only: clear the configured fetcher so tests stay isolated. */
export declare function __resetLinkPreviewForTests(): void;
/** Derive a clean display domain from a URL (strips a leading `www.`). `undefined` if unparseable. */
export declare function deriveDomain(url: string): string | undefined;
/** True when `url` is a syntactically valid http(s) URL (the only renderable link schemes). */
export declare function isRenderableLink(url: string): boolean;