import * as React from 'react';

/**
 * KindImage parts — the props, the sizing rule and the frame-safe default.
 * (Split from KindImage.tsx so the kit host can name the default without a cycle.)
 *
 * KindImage — THE image a shape shows. Never a bare `<img>`.
 *
 * A shape that shows a generated or saved image hands this the saved ref
 * (`itemState.<key>` after `run_shortcut … expect:"image"`, or any
 * `{ file_id, src?, width?, height?, mime_type? }`), or a web address (`{ url }` or the bare
 * string), whose bytes the host fetches through the image door (`fetch_image`). It:
 *   - sizes itself from the image's real width/height and shows the WHOLE image
 *     (`object-contain`) inside `maxHeight` — it never crops;
 *   - renders the host's canonical image component when the host registered one
 *     (the app's image block: expand, share, download, context menu);
 *   - otherwise (the sandbox frame, where no app component can run) shows the
 *     image with Expand and Share, which ask the host — through the component's
 *     own `runAction` — to open the canonical file preview / share window.
 *
 * Interface text is layout: labels only, one short line for an error.
 */

/**
 * An image a shape shows: a saved file (durable identity) or a web address. `src` is added by the
 * host when it hands state back. A bare string is a web address.
 */
interface KindImageRef {
    file_id?: string | null;
    /** A web address (https). The host fetches it through the platform image door, size-capped. */
    url?: string | null;
    src?: string | null;
    src_error?: string | null;
    width?: number | null;
    height?: number | null;
    mime_type?: string | null;
    organization_id?: string | null;
}
type RunAction$1 = (key: string, input: unknown) => Promise<{
    ok: true;
    result: unknown;
} | {
    ok: false;
    error: string;
}>;
interface KindImageProps {
    /** The saved image ref or a web address; a missing ref renders nothing, a ref with no `src` yet shows a placeholder. */
    image: KindImageRef | string | null | undefined;
    /** What the image shows (also the file name in the viewer). */
    alt?: string;
    /** The component's `runAction` prop — Expand and Share go through it inside a sandbox frame. */
    runAction?: RunAction$1;
    /** Tallest the image may render, in px. The whole image always shows; it scales down to fit. */
    maxHeight?: number;
    /** While a run is producing the image (no ref yet), show the placeholder anyway. */
    pending?: boolean;
    className?: string;
}
/** A bare web address is a ref with a url; anything else passes through. */
declare function toKindImageRef(image: KindImageRef | string | null | undefined): KindImageRef | null;
type Loaded = {
    src: string;
} | {
    error: string;
};
/** Test seam: forget every loaded image. */
declare function resetKindImageCache(): void;
/**
 * Bytes for an image the host has not handed over yet (a web address, or a saved file shown
 * outside item state), asked of the host with `fetch_image`; the answer's Blob becomes a local
 * `blob:` URL. Never throws; a refusal is the host's own sentence.
 */
declare function loadKindImage(runAction: RunAction$1, source: {
    url: string;
} | {
    file_id: string;
}): Promise<Loaded>;
/**
 * The `src` to draw for a ref: the host-supplied one, else bytes fetched through `fetch_image`
 * (web addresses always; saved files only when `fetchSaved`). Without `runAction` a web address is
 * drawn as is (inside the frame the image door routes it).
 */
declare function useKindImageSource(ref: KindImageRef | null, runAction: RunAction$1 | undefined, fetchSaved?: boolean): {
    src: string | null;
    error: string | null;
};
/** The box the image lives in: as wide as it can be without exceeding maxHeight, at its own ratio. */
declare function kindImageBoxStyle(image: KindImageRef | null | undefined, maxHeight: number): React.CSSProperties;
/** The frame-safe image: whole image, sized box, Expand + Share through the host. */
declare function DefaultKindImage({ image: given, alt, runAction, maxHeight, pending, className }: KindImageProps): React.JSX.Element | null;

/**
 * Shared bits of KindVideo / KindAudio: the ref shape, the actions' answer shape and small pure helpers.
 */

/** A video or audio a shape shows: a saved file (durable identity) or a web address. */
interface KindMediaRef {
    /** A saved file's id — preferred. The host fetches the bytes on demand. */
    file_id?: string | null;
    /** A web address, when the media is not a saved file. */
    url?: string | null;
    mime_type?: string | null;
    width?: number | null;
    height?: number | null;
    /** Length in seconds, when known. */
    duration?: number | null;
    organization_id?: string | null;
    /** A poster image address (web, or a blob: URL the host made). Optional. */
    poster?: string | null;
    /** A playable address the host already made (a blob: URL). When present the media plays at once. */
    src?: string | null;
}
type KindRunAction = (key: string, input: unknown) => Promise<{
    ok: true;
    result: unknown;
} | {
    ok: false;
    error: string;
}>;
/** 83 → "1:23", 3725 → "1:02:05"; null when not a usable number. */
declare function formatMediaDuration(seconds: number | null | undefined): string | null;
/** The box a video lives in: its real ratio, as wide as it can be without exceeding maxHeight. */
declare function kindVideoBoxStyle(ref: KindMediaRef | null | undefined, maxHeight: number): React.CSSProperties;

/**
 * KindVideo parts — the props and the frame-safe default.
 *
 * KindVideo — THE video a shape shows. Never a bare `<video>`.
 *
 * A shape hands it a saved ref (`itemState.<key>` / `{ file_id, mime_type, width?, height?, duration? }`)
 * or a web address (`{ url }` or a plain string). It:
 *   - shows the WHOLE video at its real aspect (`object-contain`) inside `maxHeight`, never cropped;
 *   - renders the host's canonical video block when the host registered one (the app's video block:
 *     expand, download, share, context menu);
 *   - otherwise (the sandbox frame, where no app component can run and no network is reachable) shows a
 *     poster card whose Play asks the host, through the component's own `runAction`, for the bytes
 *     (`load_media`) and plays them from a blob: URL. Nothing downloads until Play, so a large file
 *     costs nothing until the reader asks. A web address cannot play inside the frame; its Play asks
 *     the host to open the real player in a window (`play_embed`).
 *
 * Interface text is layout: labels only, one short line for an error.
 */

interface KindVideoProps {
    /** The saved video ref, a web address, or a ref carrying `url`. Missing renders nothing. */
    video: KindMediaRef | string | null | undefined;
    /** What the video shows (also its title in the viewer). */
    title?: string;
    /** The component's `runAction` prop — Play and Expand go through it inside a sandbox frame. */
    runAction?: KindRunAction;
    /** Tallest the video may render, in px. The whole video always shows; it scales down to fit. */
    maxHeight?: number;
    /** While a run is producing the video (no ref yet), show the placeholder anyway. */
    pending?: boolean;
    className?: string;
}
/** The frame-safe video: poster card → Play loads the bytes on demand → whole video, real aspect. */
declare function DefaultKindVideo({ video, title, runAction, maxHeight, pending, className }: KindVideoProps): React.JSX.Element | null;

/**
 * KindAudio parts — the props and the frame-safe default.
 *
 * KindAudio — THE audio a shape plays. Never a bare `<audio>`.
 *
 * Takes a saved ref (`{ file_id, mime_type, duration? }`) or a web address. In the page it is the
 * host's canonical audio player (durable file handle, retry, playback session). In the sealed frame it
 * is a compact row with Play: Play asks the host for the bytes (`load_media`) and plays them from a
 * blob: URL — nothing downloads until Play. A web address cannot play inside the frame; its Play asks
 * the host to open the real player in a window (`play_embed`).
 */

interface KindAudioProps {
    /** The saved audio ref, a web address, or a ref carrying `url`. Missing renders nothing. */
    audio: KindMediaRef | string | null | undefined;
    /** What the audio is (shown on the row). */
    title?: string;
    /** The component's `runAction` prop — Play goes through it inside a sandbox frame. */
    runAction?: KindRunAction;
    /** While a run is producing the audio (no ref yet), show the placeholder anyway. */
    pending?: boolean;
    className?: string;
}
/** The frame-safe audio row: Play loads the bytes on demand, then the native controls take over. */
declare function DefaultKindAudio({ audio, title, runAction, pending, className }: KindAudioProps): React.JSX.Element | null;

/**
 * KindEmbed parts — the props and the frame-safe default.
 *
 * KindEmbed — THE way a shape shows a YouTube / Vimeo / Loom / Google Maps / Figma link. Never an
 * `<iframe>` (the sealed frame cannot open one, and an author must not try).
 *
 * In the page the host renders the provider's own embed. In the sealed frame — no frame-src, no
 * network — it is a poster card: the thumbnail where the link alone gives one (YouTube), the provider
 * and the title, and Play, which asks the host through `runAction("play_embed", { url, title })` to open
 * the real embed in a window. A link with no known embed shows an Open card (`open_url`).
 */

interface KindEmbedProps {
    /** The link to show: a YouTube, Vimeo, Loom, Google Maps or Figma address (any other link becomes an Open card). */
    url: string | null | undefined;
    /** What it is (card title and window title). Defaults to the provider's name. */
    title?: string;
    /** The component's `runAction` prop — Play and Open go through it inside a sandbox frame. */
    runAction?: KindRunAction;
    /** Tallest the embed may render, in px. */
    maxHeight?: number;
    className?: string;
}
/** The embed's box: its provider's ratio, as wide as it can be without exceeding maxHeight. */
declare function kindEmbedBoxStyle(aspect: number, maxHeight: number): React.CSSProperties;
/** The frame-safe embed: a poster card whose Play opens the real embed through the host. */
declare function DefaultKindEmbed({ url, title, runAction, maxHeight, className }: KindEmbedProps): React.JSX.Element | null;

/**
 * The kit's HOST SLOTS. The kit never imports app code; the three things it cannot own are
 * handed in once by the host through `setKindKitHost`:
 *   - `CopyButtons`   the copy bar `KindHeaderBar` renders for its `copy` prop;
 *   - `ReadEmpty`     what `SortableList` / `TagList` show instead of an empty state while a
 *                     read has not succeeded;
 *   - `ReadStaleNotice` the notice above rows left on screen by a failed refresh;
 *   - `Image`         what `KindImage` renders: the host's canonical image component.
 *   - `Video`, `Audio`, `Embed`  the same for `KindVideo`, `KindAudio`, `KindEmbed`.
 * Each default is honest and working: a plain Copy button, and text that says what happened.
 * State lives on globalThis under a Symbol.for key so two copies of the package share one host.
 */

/**
 * The copy bar's props: a LOCAL port shape, so this package never imports the copy menu's own
 * package (that would make a dependency cycle). It is a structural subset of the copy menu's props
 * (`label`, `human`, `json`, `size`, `className`), so a host registers its own `CopyButtons`
 * (the full copy menu takes this shape) with no adapter. Every other copy-menu prop
 * (`agent`, `references`, `export`, ...) passes through untouched, which is what the index signature is for.
 * Type-only: no runtime import.
 */
interface KindKitCopyProps {
    label: string;
    human?: string | (() => string);
    json?: unknown;
    size?: "xs" | "icon" | "sm" | "toolbar";
    className?: string;
    [passthrough: string]: unknown;
}
type ReadStatus = "loading" | "error" | "ready";
/** A read's outcome, handed to a list primitive's `read` prop. */
interface ReadOutcome {
    status: ReadStatus;
    /** The failure itself, or a truthy flag when the read only says it failed. */
    error?: unknown;
    onRetry?: (() => void) | undefined;
    /** What was read, in the reader's words: "your tasks". */
    what?: string | undefined;
    /** A successful read has already produced a value. */
    hasData?: boolean | undefined;
}
interface KindKitReadEmptyProps {
    read?: ReadOutcome | undefined;
    loading?: React.ReactNode;
    children?: React.ReactNode;
}
interface KindKitReadStaleNoticeProps {
    read?: ReadOutcome | undefined;
    className?: string;
}
interface KindKitHost {
    CopyButtons: React.ComponentType<KindKitCopyProps>;
    ReadEmpty: React.ComponentType<KindKitReadEmptyProps>;
    ReadStaleNotice: React.ComponentType<KindKitReadStaleNoticeProps>;
    Image: React.ComponentType<KindImageProps>;
    Video: React.ComponentType<KindVideoProps>;
    Audio: React.ComponentType<KindAudioProps>;
    Embed: React.ComponentType<KindEmbedProps>;
}
/** Default copy bar: one "Copy" button that writes the `human` text (else the JSON) to the clipboard. */
declare function DefaultCopyButtons({ label, human, json, size, className }: KindKitCopyProps): React.JSX.Element;
/** Default: loading says it is loading; an error says what failed (with retry); ready shows the host's empty state. */
declare function DefaultReadEmpty({ read, loading, children }: KindKitReadEmptyProps): React.JSX.Element;
/** Default: when the latest read failed, the rows on screen may be out of date; says so, with retry. */
declare function DefaultReadStaleNotice({ read, className }: KindKitReadStaleNoticeProps): React.JSX.Element | null;
/** Register the host's copy bar and read notices. Call once at boot; a slot left out keeps its default. */
declare function setKindKitHost(host: Partial<KindKitHost>): void;
/** The slots in force: the host's where registered, the defaults elsewhere. */
declare function getKindKitHost(): KindKitHost;
/** Clear every registered slot (tests, hot reload). */
declare function resetKindKitHost(): void;

/**
 * SortableList — drag-to-reorder list for kind components.
 *
 * The mandated reorder UX, built once: while a row is dragged, the rows it
 * passes DISPLACE (translate) out of the way and a SHADOWED placeholder marks
 * exactly where the item will land. Native HTML5 drag-and-drop (no deps); a
 * grab handle starts the drag (so text and inputs inside rows stay usable);
 * up/down buttons are the keyboard + touch fallback; `onRemove` adds an inline
 * remove control. Rows are FLAT, split by hairlines (`divide-y`) — never a
 * bordered box per row; the row's own controls sit in flow, always reachable.
 * Contract: `kind-kit/README.md`.
 *
 * Sandbox-safe by construction: imports only react, the design system,
 * and `cn`.
 */

interface SortableRenderContext {
    index: number;
    /** True for the row currently being dragged (rendered as the placeholder). */
    isDragging: boolean;
}
interface SortableListProps<T> {
    /** Current order. Treated as read-only; the new order arrives via `onReorder`. */
    items: readonly T[];
    /**
     * Stable key per item. Default: the item itself when it is a string, else
     * `item.id` / `item.key` when present, else the index (unstable — pass one).
     */
    getKey?: (item: T, index: number) => string;
    /** Called with the full reordered array after a drop or an arrow press. */
    onReorder: (items: T[]) => void;
    /**
     * Row content. Default: the item when it is a string/number, else its
     * `label` / `title` / `name` / `text` field, else `JSON.stringify`.
     */
    renderItem?: (item: T, ctx: SortableRenderContext) => React.ReactNode;
    /** When set, every row gets an inline remove (X) control. */
    onRemove?: (item: T, index: number) => void;
    /** Disables drag, arrows and remove (rows still render). */
    disabled?: boolean;
    /** Hide the up/down arrow buttons (drag only). Default false. */
    hideArrows?: boolean;
    /** Shown when `items` is empty. */
    emptyState?: React.ReactNode;
    /**
     * The outcome of the read behind the rows (RC-B12 r13). `emptyState` shows
     * only after a read that succeeded; a failed read shows the failure + retry.
     */
    read?: ReadOutcome;
    /** Wrapper `<ul>` className. */
    className?: string;
    /** Per-row className (applied to every `<li>`). */
    itemClassName?: string;
    /** Accessible name for the list. */
    ariaLabel?: string;
}
declare function SortableList<T>({ items, getKey, onReorder, renderItem, onRemove, disabled, hideArrows, emptyState, read, className, itemClassName, ariaLabel, }: SortableListProps<T>): React.JSX.Element | null;

/**
 * KindPanelGrid — content-aware responsive grid for side-by-side panels.
 *
 * Never more columns than the content can afford: every track is at least
 * `minColumnWidth` (default 280px) wide, the column count is whatever fits
 * (`auto-fit`), and every panel in a row stretches to the same height so the
 * panels' footers line up. Pair with `KindPanel` (its `footer` is pinned to
 * the bottom). Panels are flat by default, so the grid separates them by
 * SPACE (default 16px), never by boxing them. Contract: `kind-kit/README.md`.
 */

declare const GAP_PX: {
    readonly sm: 8;
    readonly md: 12;
    readonly lg: 16;
};
interface KindPanelGridProps {
    children: React.ReactNode;
    /** Minimum width (px) of a column before the grid drops a column. Default 280. */
    minColumnWidth?: number;
    /** Hard ceiling on columns, however wide the container is. */
    maxColumns?: number;
    /** Space between panels. Default "lg" (16px) — flat sections need air, not borders. */
    gap?: keyof typeof GAP_PX;
    /**
     * "auto-fit" (default): a short last row lets panels grow to fill the width.
     * "auto-fill": tracks stay the same width and the row is left short.
     */
    fill?: "auto-fit" | "auto-fill";
    className?: string;
}
declare function KindPanelGrid({ children, minColumnWidth, maxColumns, gap, fill, className, }: KindPanelGridProps): React.JSX.Element;

type KindKitIcon = React.ComponentType<{
    className?: string;
}> | React.ReactElement<{
    className?: string;
}>;
/** Render either icon authoring form without treating an element as a component type. */
declare function renderKindKitIcon(icon: KindKitIcon | undefined, className: string): React.ReactElement | null;

/**
 * KindPanel — the standard section of a kind component (a keyword bucket, an
 * option, a group of results).
 *
 * FLAT BY DEFAULT (Arman, 2026-10-24: "Avoid cards at all costs. Especially
 * cards within other cards."): no border, no card background, no shadow, no
 * padding of its own — the section sits on the shape's surface, aligned to the
 * header's edge, and siblings in a `KindPanelGrid` are separated by spacing.
 * `variant="card"` is the one deliberate opt-in surface; it is never the
 * default. `title` is optional: a shape with one section omits it (the header
 * already named the thing), and the icon is optional too — never repeat the
 * header's icon here.
 *
 * Layout is fixed so agent-authored panels come out right by construction:
 *  - quiet heading row: icon · title (wraps, never squeezed) · count · ≤2 inline
 *    actions · an overflow menu that absorbs EVERY other control (no control
 *    row ever gets crammed);
 *  - full-width subline (a rationale, a hint) on its own line UNDER the
 *    header — never beside the title;
 *  - body;
 *  - `footer` pinned to the bottom (flex column + mt-auto) so "Add" rows
 *    line up across sibling panels in a `KindPanelGrid`.
 * Contract: `kind-kit/README.md`.
 */

interface KindPanelMenuItem {
    label: string;
    onSelect: () => void;
    icon?: React.ComponentType<{
        className?: string;
    }>;
    disabled?: boolean;
    /** Renders in the destructive color (delete, clear, reset). */
    destructive?: boolean;
    /** Draws a separator ABOVE this item. */
    separatorBefore?: boolean;
}
interface KindPanelProps {
    /**
     * Section heading. Wraps onto extra lines rather than truncating. Omit it
     * (with no count/badge/actions/menu) and the heading row is not drawn — a
     * shape with a single section never repeats the header's title.
     */
    title?: React.ReactNode;
    /** Optional glyph before the title. Never the header's icon again. */
    icon?: KindKitIcon;
    /** Quiet count after the title (e.g. number of items). */
    count?: number | string;
    /** Any extra pill/badge after the count (a status, a score); plain text is drawn as a tag. */
    badge?: React.ReactNode;
    /** Shows a spinner in the header while this panel's data is still arriving. */
    streaming?: boolean;
    /**
     * At most one or two compact controls rendered inline on the right of the
     * header (a toggle, a tiny icon button). Put everything else in `menuItems`.
     */
    actions?: React.ReactNode;
    /** Controls collapsed into the header's overflow (⋯) menu. */
    menuItems?: KindPanelMenuItem[];
    /** Full-width line under the header — a rationale, a hint. Never beside the title. */
    subline?: React.ReactNode;
    /** Panel body. */
    children?: React.ReactNode;
    /** Pinned to the bottom of the panel (an "Add" row, a summary, a copy bar). */
    footer?: React.ReactNode;
    /**
     * "flat" (default): no border, background or padding — the section sits on
     * the shape's surface. "card": the deliberate opt-in bordered surface (a
     * thing that truly is an object on a board); never nest one in another.
     * "bare" is accepted as "flat".
     */
    variant?: "flat" | "card" | "bare";
    /** Tighter paddings for dense lists. */
    dense?: boolean;
    className?: string;
    /** className for the body wrapper. */
    bodyClassName?: string;
}
declare function KindPanel({ title, icon, count, badge, streaming, actions, menuItems, subline, children, footer, variant, dense, className, bodyClassName, }: KindPanelProps): React.JSX.Element;

/**
 * KindHeaderBar — the standard compact header of a kind component:
 * icon · title (the instance's `title_key` value) · at-a-glance stats · the
 * copy bar (the host's `CopyButtons` slot: Copy / Copy-for-AI / JSON / Export from builders
 * the caller supplies). One row that wraps on narrow widths; the copy bar
 * stays on the right. Never a card: a full-width row with no border or
 * background, and no padding of its own — the shape's frame supplies the one
 * normal padding, so the header and the sections under it share one left
 * edge. The icon and the title appear here ONCE; sections never repeat them.
 * Contract: `kind-kit/README.md`.
 */

interface KindHeaderStat {
    /** Short label, e.g. "keywords". */
    label: string;
    /** The number/text, e.g. 42 or "3 buckets". */
    value: React.ReactNode;
    /** Lucide component or an already-created icon element. */
    icon?: KindKitIcon;
    /** Optional hover text. */
    title?: string;
}
interface KindHeaderBarProps {
    /** The instance title (usually `data[title_key]`). */
    title: React.ReactNode;
    /** Lucide component or an already-created icon element. */
    icon?: KindKitIcon;
    /** Small muted line under the title (a primary keyword, a subtitle). */
    subtitle?: React.ReactNode;
    /** At-a-glance numbers rendered as compact "value label" stats. */
    stats?: KindHeaderStat[];
    /** Shows a spinner + "Streaming" while the instance is still arriving. */
    streaming?: boolean;
    /** Word shown beside the spinner. Default "Streaming". */
    streamingLabel?: string;
    /**
     * The copy bar. Pass the builders you have — `human` (text), `agent`
     * (payload or string), `json` (raw record), `export` (download items) and
     * the `label` used in toasts. Omit to render no copy bar.
     */
    copy?: KindKitCopyProps;
    /** Extra controls rendered between the stats and the copy bar. */
    actions?: React.ReactNode;
    /** "sm" (default) for in-chat blocks; "md" for page-level kind surfaces. */
    size?: "sm" | "md";
    className?: string;
}
declare function KindHeaderBar({ title, icon, subtitle, stats, streaming, streamingLabel, copy, actions, size, className, }: KindHeaderBarProps): React.JSX.Element;

/**
 * KindActionButton — the one-click door from a kind component to a host
 * Action. Wraps the component's `runAction(key, input)` prop (the ONLY
 * side-effect channel; it never throws, it returns an `{ok}` envelope), with
 * a busy state, no double fire, an optional inline confirm that states the
 * consequence, and a one-line inline error (the host already toasts).
 * Contract: `kind-kit/README.md`.
 */

type KindActionEnvelope = {
    ok: true;
    result?: unknown;
} | {
    ok: false;
    error: string;
};
/** One action: `runAction` + `action` + `input`. */
interface KindActionSingle {
    /** The component's `runAction` prop, passed straight through. */
    runAction: (key: string, input: unknown) => Promise<KindActionEnvelope>;
    /** Action key, e.g. "run_shortcut". */
    action: string;
    /** The action input, or a function that builds it at click time. */
    input: unknown | (() => unknown);
    run?: never;
}
/** A chain: `run` awaits several `runAction` calls and returns the final envelope. */
interface KindActionChain {
    run: () => Promise<KindActionEnvelope>;
    runAction?: never;
    action?: never;
    input?: never;
}
interface KindActionButtonBase {
    /** Short label. Also the aria-label/tooltip when `compact`. */
    label: string;
    /** Lucide component or an already-created icon element. */
    icon?: KindKitIcon;
    /** Label while running. Defaults to `label`. */
    busyLabel?: string;
    /** One-sentence consequence. When set, the first click asks to confirm. */
    confirm?: string;
    onDone?: (result: unknown) => void;
    onError?: (error: string) => void;
    variant?: "default" | "primary" | "destructive" | "success" | "outline" | "secondary" | "ghost" | "subtle";
    /** Icon-only with tooltip + aria-label, for menus and header rows. */
    compact?: boolean;
    disabled?: boolean;
    className?: string;
}
type KindActionButtonProps = KindActionButtonBase & (KindActionSingle | KindActionChain);
declare function KindActionButton({ runAction, action, input, run: runChain, label, icon, busyLabel, confirm, onDone, onError, variant, compact, disabled, className, }: KindActionButtonProps): React.JSX.Element;

/**
 * StreamingSkeleton + useStreamingValue — the "before data lands" kit.
 *
 * A kind component receives partial `data` on every envelope flush while the
 * agent streams: fields are absent, arrays are short, strings are cut. The
 * skeleton mimics the layout the real content will have (list / sections
 * ("cards", a legacy name — drawn flat) / table / text) for the instant before anything arrives; the helpers make
 * field reads tolerant so a component never crashes on a half-built
 * instance and never flickers a value away. Contract:
 * `kind-kit/README.md`.
 */

interface StreamingSkeletonProps {
    /** Layout to mimic. Default "list". */
    layout?: "list" | "cards" | "table" | "text";
    /** Rows (list/table/text lines) or cards. Default 3. */
    rows?: number;
    /** Columns for "table" / "cards". Default 3 (table) / 2 (cards). */
    columns?: number;
    /** Render a title bar line above the body. Default true. */
    header?: boolean;
    /** Accessible label. Default "Loading". */
    label?: string;
    className?: string;
}
declare function StreamingSkeleton({ layout, rows, columns, header, label, className, }: StreamingSkeletonProps): React.JSX.Element;
/**
 * Sticky, tolerant read of a value that may be absent mid-stream.
 *
 * Returns the latest DEFINED value seen (so a re-parse that momentarily drops
 * a field does not blank the UI), `fallback` until one arrives, and `arrived`
 * once any real value has been observed. Implemented with the React
 * "remember the previous render" pattern (state updated during render), so
 * pass a FIELD READ (`data?.summary`) — never an expression that builds a
 * new object/array on every render (`data?.items ?? []`), which would
 * re-trigger the update each render.
 */
declare function useStreamingValue<T>(value: T | null | undefined, fallback: T): {
    value: T;
    arrived: boolean;
};
/** `value` when it is an array, else `[]` — for `data.items` that is not there yet. */
declare function streamList<T = unknown>(value: unknown): T[];
/** `value` when it is a non-empty string, else `fallback` ("" by default). */
declare function streamText(value: unknown, fallback?: string): string;

/**
 * KeywordChip + TagList — chips that WRAP, never truncate.
 *
 * A keyword / tag / phrase is always shown in full: the chip wraps its text
 * onto extra lines inside the chip, and the list wraps chips onto extra rows.
 *
 * ONE GEOMETRY (the design system's chip: a 6px-radius rectangle, 24px tall
 * for a single line, 8px text inset, 12px/500 label) for every chip, the add
 * control and the inline inputs, so a row of labels is one even band. Before
 * 2026-10-24 each chip was a capsule that grew a checkbox square, a pencil and
 * an X of three different sizes, and the add control was a differently padded
 * dashed capsule — every chip a different height and width of chrome.
 * Now:
 *  - select: the chip itself is the toggle (tinted when on) — no checkbox box;
 *  - edit: the label is the edit control (click; or double-click / F2 when the
 *    chip also selects) — no pencil;
 *  - remove: one small X in flow, quiet until the chip is hovered or focused.
 * `TagList` adds an "Add" control at the end when `onAdd` is given.
 * Contract: `kind-kit/README.md`.
 */

interface KeywordChipProps {
    /** The phrase. Rendered in full — wraps, never truncates. */
    label: string;
    /** Small trailing detail (a count, a volume, a score). */
    meta?: React.ReactNode;
    /** Lucide component or an already-created icon element. */
    icon?: KindKitIcon;
    /** Selected state; pass `onSelect` to make the chip a toggle. */
    selected?: boolean;
    /** Makes the chip a toggle; called with the next selected state. */
    onSelect?: ((selected: boolean) => void) | undefined;
    /** Adds an X control. */
    onRemove?: (() => void) | undefined;
    /** Enables inline edit (the label is the edit control; double-click / F2 when the chip also selects); called with the committed text. */
    onEdit?: ((next: string) => void) | undefined;
    /** Grays the chip and disables select/remove/edit. */
    disabled?: boolean | undefined;
    tone?: "default" | "primary" | "muted" | undefined;
    size?: "sm" | "md";
    className?: string;
}
declare function KeywordChip({ label, meta, icon, selected, onSelect, onRemove, onEdit, disabled, tone, size, className, }: KeywordChipProps): React.JSX.Element;
interface TagItem {
    label: string;
    /** Stable key; defaults to `label`. */
    key?: string;
    meta?: React.ReactNode;
    disabled?: boolean;
}
interface TagListProps {
    /** Phrases, as strings or `{ label, key?, meta?, disabled? }` objects. */
    items: readonly (string | TagItem)[];
    /** Selected keys (label when no key). Pass with `onToggle` for selectable chips. */
    selected?: readonly string[];
    /** Makes chips toggles; called with (key, nextSelected). */
    onToggle?: (key: string, selected: boolean) => void;
    /** Adds an X on every chip; called with (key, index). */
    onRemove?: (key: string, index: number) => void;
    /** Enables inline edit on every chip; called with (key, index, nextLabel). */
    onEdit?: (key: string, index: number, next: string) => void;
    /** Renders an inline "Add" input at the end; called with the trimmed text. */
    onAdd?: (label: string) => void;
    /** Placeholder of the add input. Default "Add…". */
    addPlaceholder?: string;
    /** Shown when `items` is empty (and there is no add input). */
    emptyState?: React.ReactNode;
    /**
     * The outcome of the read behind the rows (RC-B12 r13). `emptyState` shows
     * only after a read that succeeded; a failed read shows the failure + retry.
     */
    read?: ReadOutcome;
    tone?: KeywordChipProps["tone"];
    size?: KeywordChipProps["size"];
    disabled?: boolean;
    className?: string;
}
declare function TagList({ items, selected, onToggle, onRemove, onEdit, onAdd, addPlaceholder, emptyState, read, tone, size, disabled, className, }: TagListProps): React.JSX.Element | null;

/** The image a shape shows: the host's canonical image component when registered, else the frame-safe one. */
declare function KindImage(props: KindImageProps): React.JSX.Element;

/**
 * KindFile — THE way a shape shows any saved file: one flat row (never a card) with the file's type glyph (an
 * image file shows its own thumbnail), its name and size, and Open / Download / Share.
 *
 * Every button goes through the component's own `runAction`, so it works the same in the page and
 * inside the sealed frame:
 *   - Open     → `open_file`  (the platform's file preview: PDFs, documents, images, media);
 *   - Download → `download { file_id, filename }` (the platform's download door);
 *   - Share    → `share_file` (the platform's share window).
 * A shape never builds a URL from a `file_id`.
 *
 * Interface text is layout: labels only, one short line for an error.
 */

/** A saved file, by durable identity. */
interface KindFileRef {
    file_id?: string | null;
    name?: string | null;
    mime_type?: string | null;
    /** Size in bytes, when known. */
    size?: number | null;
    organization_id?: string | null;
}
type RunAction = (key: string, input: unknown) => Promise<{
    ok: true;
    result: unknown;
} | {
    ok: false;
    error: string;
}>;
interface KindFileProps {
    /** The saved file; a missing ref (or one with no `file_id`) renders nothing. */
    file: KindFileRef | null | undefined;
    /** The component's `runAction` prop — every button goes through it. */
    runAction?: RunAction;
    /** Leave buttons out: `hide={["share"]}`. */
    hide?: ReadonlyArray<"open" | "download" | "share">;
    className?: string;
}
type KindFileType = "image" | "pdf" | "video" | "audio" | "sheet" | "archive" | "text" | "file";
/** What kind of file this is, from its mime type, else its name's extension. */
declare function kindFileType(mime: string | null | undefined, name: string | null | undefined): KindFileType;
/** A saved file as one flat row: glyph or thumbnail tile, name, size, Open / Download / Share. */
declare function KindFile({ file, runAction, hide, className }: KindFileProps): React.JSX.Element | null;

/** The video a shape shows: the host's canonical video block when registered, else the frame-safe one. */
declare function KindVideo(props: KindVideoProps): React.JSX.Element;

/** The audio a shape plays: the host's canonical player when registered, else the frame-safe row. */
declare function KindAudio(props: KindAudioProps): React.JSX.Element;

/**
 * embed-url — pure: a pasted link → how to show it. No network, no DOM.
 *
 * Providers: YouTube, Vimeo, Loom, Google Maps, Figma. Anything else is `generic`: it has no known
 * embed, so a shape shows a link card and the host opens it in a new tab.
 * `embedUrl` is the provider's own embeddable address (the page puts it in an iframe; the sealed
 * frame never does — it opens it through the host, see KindEmbedDefault).
 */
type EmbedProvider = "youtube" | "vimeo" | "loom" | "google-maps" | "figma" | "generic";
interface ParsedEmbed {
    provider: EmbedProvider;
    /** The link as the person gave it (trimmed). */
    url: string;
    /** What to put in an iframe; null when the provider has no embed for this link. */
    embedUrl: string | null;
    /** A thumbnail derivable from the link alone (YouTube); null otherwise. */
    poster: string | null;
    /** width / height of the embed. */
    aspect: number;
    /** A short name for the provider, for a card with no better title. */
    label: string;
    /** YouTube only: the video id. */
    videoId?: string;
    /** YouTube only: start offset in seconds. */
    start?: number;
}
/** Parse a link. A string that is not an http(s) URL is `generic` with no embed. */
declare function parseEmbed(input: string | null | undefined): ParsedEmbed;

/** The embed a shape shows: the host's provider embed when registered, else the frame-safe poster card. */
declare function KindEmbed(props: KindEmbedProps): React.JSX.Element;

interface KindLocale {
    /** BCP-47 language tag, e.g. "en-US", "ar-EG". */
    locale: string;
    /** IANA time zone, e.g. "America/Los_Angeles". */
    timeZone: string;
    /** Text direction of the reader's page. */
    dir: "ltr" | "rtl";
}
/** Where nothing was sent: the document and browser the code is running in. */
declare function readDocumentLocale(): KindLocale;
/** The host (or the sealed frame, on a message) states the reader's locale. Idempotent. */
declare function setKindLocale(value: KindLocale | null): void;
/** The locale in force right now (non-hook). */
declare function getKindLocale(): KindLocale;
/** The reader's `{ locale, timeZone, dir }`; re-renders when the host says it changed. */
declare function useKindLocale(): KindLocale;

export { DefaultCopyButtons, DefaultKindAudio, DefaultKindEmbed, DefaultKindImage, DefaultKindVideo, DefaultReadEmpty, DefaultReadStaleNotice, KeywordChip, KindActionButton, KindAudio, KindEmbed, KindFile, KindHeaderBar, KindImage, KindPanel, KindPanelGrid, KindVideo, SortableList, StreamingSkeleton, TagList, formatMediaDuration, getKindKitHost, getKindLocale, kindEmbedBoxStyle, kindFileType, kindImageBoxStyle, kindVideoBoxStyle, loadKindImage, parseEmbed, readDocumentLocale, renderKindKitIcon, resetKindImageCache, resetKindKitHost, setKindKitHost, setKindLocale, streamList, streamText, toKindImageRef, useKindImageSource, useKindLocale, useStreamingValue };
export type { EmbedProvider, KeywordChipProps, KindActionButtonProps, KindActionEnvelope, KindAudioProps, KindEmbedProps, KindFileProps, KindFileRef, KindFileType, KindHeaderBarProps, KindHeaderStat, KindImageProps, KindImageRef, KindKitCopyProps, KindKitHost, KindKitIcon, KindKitReadEmptyProps, KindKitReadStaleNoticeProps, KindLocale, KindMediaRef, KindPanelGridProps, KindPanelMenuItem, KindPanelProps, KindVideoProps, ParsedEmbed, ReadOutcome, ReadStatus, SortableListProps, SortableRenderContext, StreamingSkeletonProps, TagItem, TagListProps };