@adonis-agora/agent 0.72.0 → 0.74.0

package/dist/src/genui/channels.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Per-channel generative UI: what a turn may draw depends on where it is read. A web page draws the
+ * catalog's components (and the sandbox); WhatsApp and Telegram draw text, reply buttons, lists and
+ * images; an email draws HTML. `genui({ channels: { … } })` sets, per channel, which tools the model
+ * is offered and how what it pushes is delivered — and the model is told only what that channel can
+ * draw.
+ *
+ * Framework-free and isomorphic, like the rest of `genui`.
+ */
+import type { UiAction } from './actions.js';
+import { type Catalog, type ComponentDefinition, type GenuiStreaming } from './catalog.js';
+import { type DefineSandboxOptions } from './sandbox.js';
+/** The channel a turn runs on when nothing says otherwise: a browser (AG-UI, the HTTP chat, A2UI). */
+export declare const WEB_CHANNEL = "web";
+/** The `channels` entry that serves every channel without one of its own. */
+export declare const DEFAULT_CHANNEL = "default";
+/** Channels a person reads in a messaging app or a mailbox: the server draws for them. */
+export declare const MESSAGING_CHANNELS: readonly string[];
+/**
+ * What the model is offered on a channel: `tree` — one `ui__render` tool composing the catalog (and
+ * the sandbox, when on); `per-component` — one `ui__show_<component>` tool per component that can be
+ * drawn there; `text` — no UI tools, the model answers in text.
+ */
+export type GenuiChannelMode = 'tree' | 'per-component' | 'text';
+/**
+ * How what the model pushed reaches a channel the server draws for (WhatsApp, Telegram, email):
+ * `native` — each component's channel conversion (`defineComponent(…, { channels })`: text, reply
+ * buttons, a list, an image), its text summary otherwise; `text` — always the text summary; `html` —
+ * HTML (email). A web channel draws in the browser and ignores it.
+ */
+export type GenuiChannelRender = 'native' | 'text' | 'html';
+/** One channel's generative UI — every field falls back to the `default` entry, then to the top level. */
+export interface GenuiChannelOptions {
+    /** Default: the top-level `mode` on a web channel; `per-component` on a messaging channel. */
+    mode?: GenuiChannelMode;
+    /** Tree mode: draw the layout while the model writes it (`partial`) or once it is whole. */
+    streaming?: GenuiStreaming;
+    /**
+     * The sandbox on this channel: `false` for none, `true` / a config for the sandbox with those
+     * options (a web channel may use the app's kit while a mobile one does not). Default: the
+     * top-level `sandbox` on a web channel; never on a messaging channel (it cannot run there).
+     */
+    sandbox?: boolean | DefineSandboxOptions;
+    /** Default `native` (`html` for `email`). */
+    render?: GenuiChannelRender;
+    /** Charts as PNG images on a channel that takes images ({@link ChartImageRenderer}, `chartImages()`). */
+    chartImages?: ChartImageRenderer;
+    /** Extra words for the model on this channel, added to the UI tools' descriptions. */
+    instructions?: string;
+}
+/** `genui({ channels })`: an entry per channel name, plus `default` for every other one. */
+export interface GenuiChannels {
+    web?: GenuiChannelOptions;
+    mobile?: GenuiChannelOptions;
+    whatsapp?: GenuiChannelOptions;
+    telegram?: GenuiChannelOptions;
+    email?: GenuiChannelOptions;
+    default?: GenuiChannelOptions;
+    [channel: string]: GenuiChannelOptions | undefined;
+}
+/** The top-level genui options a channel falls back to. */
+export interface GenuiChannelBase {
+    mode?: 'per-component' | 'tree';
+    streaming?: GenuiStreaming;
+    sandbox?: boolean | DefineSandboxOptions;
+}
+/** A channel's options with every default applied — what the tools and the channel handler follow. */
+export interface ResolvedGenuiChannel {
+    /** The channel's name (`web`, `whatsapp`, `mobile`, …). */
+    name: string;
+    /** The server draws for it (WhatsApp, Telegram, email): it never runs a sandbox or a React renderer. */
+    messaging: boolean;
+    /** `channels` has an entry for it (its own or `default`). `false` → it behaves as it always did. */
+    configured: boolean;
+    mode: GenuiChannelMode;
+    streaming?: GenuiStreaming;
+    /** `undefined` → the catalog's own sandbox (if it has one) is left as it is. */
+    sandbox?: boolean | DefineSandboxOptions;
+    render: GenuiChannelRender;
+    chartImages?: ChartImageRenderer;
+    instructions?: string;
+}
+/**
+ * THE rule for which channel a turn runs on, read from its page context:
+ *
+ * - `pageContext.channel` is a string → that channel (an explicit override: `send({ channel })`, a
+ *   mobile client posting `pageContext: { channel: 'mobile' }`);
+ * - `pageContext.channel` is the address a text-channel adapter stamps (`{ name, conversation,
+ *   kind? }`) → its `kind` (`whatsapp`, `telegram`), else its `name`;
+ * - nothing → `web`: what AG-UI, the HTTP chat and A2UI serve (they stamp nothing, so a tool that
+ *   skips skeletons when `pageContext.channel` is set keeps working).
+ */
+export declare function turnChannel(pageContext: {
+    [key: string]: unknown;
+} | undefined): string;
+/** WhatsApp, Telegram and email are drawn by the server; every other channel by a client. */
+export declare function isMessagingChannel(channel: string): boolean;
+/** One channel's options, its own entry over `default` over the top level. */
+export declare function resolveGenuiChannel(base: GenuiChannelBase, channels: GenuiChannels | undefined, channel: string | undefined): ResolvedGenuiChannel;
+/** Throws on a `channels` entry that names an unknown mode or render. */
+export declare function assertGenuiChannels(channels: GenuiChannels | undefined): void;
+/**
+ * A reply button. Pressed, it becomes the user's next turn — a {@link UiAction} whose text is the
+ * label and whose context is `value`, exactly like a sandbox's `agent.send`.
+ */
+export interface ChannelNativeButton {
+    label: string;
+    /** The action's name. Default `select`. */
+    action?: string;
+    /** The values that go with the press (JSON). */
+    value?: Record<string, unknown>;
+}
+export interface ChannelNativeListItem extends ChannelNativeButton {
+    /** A second line under the label. */
+    description?: string;
+}
+/** A list to pick one entry from (a WhatsApp list message, a Telegram keyboard of one row each). */
+export interface ChannelNativeList {
+    /** The label of the button that opens the list (WhatsApp). */
+    button: string;
+    /** A heading over the entries. */
+    title?: string;
+    items: ChannelNativeListItem[];
+}
+/** An image: by an `https` url the provider fetches, or its bytes. */
+export interface ChannelNativeImage {
+    url?: string;
+    data?: Uint8Array;
+    /** Default `image/png`. */
+    contentType?: string;
+}
+/**
+ * What a component is on a channel the server draws for. Each field is optional; a message with an
+ * image sends `text` as its caption, one with buttons or a list sends `text` as its body.
+ */
+export interface ChannelNativeMessage {
+    /** In the model's markdown — converted to the channel's. */
+    text?: string;
+    /** For `render: 'html'` (email). Trusted markup: build it from props, escaping what you insert. */
+    html?: string;
+    /** Reply buttons — at most 3 on WhatsApp; more become a list. */
+    buttons?: ChannelNativeButton[];
+    list?: ChannelNativeList;
+    image?: ChannelNativeImage;
+}
+/** `defineComponent(…, { channels: { whatsapp: (props) => ({ text, buttons }) } })`. */
+export type ChannelConversion<P = Record<string, unknown>> = {
+    convert(props: P, context: {
+        channel: string;
+    }): ChannelNativeMessage | ChannelNativeMessage[] | null | undefined | Promise<ChannelNativeMessage | ChannelNativeMessage[] | null | undefined>;
+}['convert'];
+/**
+ * A component's conversions, by channel name. `false` → the component is never offered on that
+ * channel (it has nothing to say there).
+ */
+export type ComponentChannels<P = Record<string, unknown>> = {
+    [channel: string]: ChannelConversion<P> | false | undefined;
+};
+/** Renders chart components as images, for a channel that takes them. */
+export interface ChartImageRenderer {
+    /** The components it draws (default for `chartImages()`: `['Chart']`). */
+    readonly components: readonly string[];
+    render(component: string, props: Record<string, unknown>): Promise<ChannelNativeImage | null>;
+}
+/**
+ * Whether `definition` can be drawn on `channel`. On a web channel every component can (the client's
+ * `uiCapabilities` narrow it); on a messaging channel a component can when it has a conversion for
+ * it, a chart renderer draws it, or it has a text summary (`fallbackText`) — a component without one
+ * would arrive as a JSON dump, so it is not offered. A sandbox never can, and `channels: { x: false }`
+ * opts a component out.
+ */
+export declare function canRenderOnChannel(definition: ComponentDefinition<unknown>, channel: ResolvedGenuiChannel): boolean;
+/**
+ * The catalog as `channel` may draw it: only what it can render, and its own sandbox (or none). With
+ * no `channels` configured the catalog is returned as it is.
+ */
+export declare function channelCatalog(catalog: Catalog, channel: ResolvedGenuiChannel): Catalog;
+/** What a UI tool's description says about the channel the conversation is on. */
+export declare function channelInstructions(channel: ResolvedGenuiChannel): string | undefined;
+/** A pushed component, as a channel delivers it. */
+export interface ChannelComponentInput {
+    /** The frame's id — what a button press reports as its `componentId`. */
+    id?: string;
+    name: string;
+    props: Record<string, unknown>;
+}
+/** {@link ChannelNativeMessage} plus the component it came from (so a press can name it). */
+export interface ChannelRenderedMessage extends ChannelNativeMessage {
+    component: string;
+    componentId?: string;
+    title?: string;
+}
+/** Plain text as minimal HTML: paragraphs, line breaks, `*bold*`. */
+export declare function textToHtml(text: string): string;
+/**
+ * What a pushed component (a tree included) is on a channel the server draws for: one or more
+ * messages — its conversions, chart images, and the text summary of everything else, in order.
+ * Consecutive text is joined. Never throws: a conversion that fails sends the summary.
+ */
+export declare function renderChannelMessages(catalog: Catalog, component: ChannelComponentInput, channel: ResolvedGenuiChannel): Promise<ChannelRenderedMessage[]>;
+/** The UI action a pressed button (or picked list entry) stands for — the user's next turn. */
+export declare function channelButtonAction(button: ChannelNativeButton, from: {
+    componentId?: string;
+    title?: string;
+}): UiAction;
+//# sourceMappingURL=channels.d.ts.map

package/dist/src/genui/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../../src/genui/channels.ts"],"names":[],"mappings":"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"}

package/dist/src/genui/channels.js

@@ -0,0 +1,322 @@
+import { defineCatalog, } from './catalog.js';
+import { defineSandbox, sandboxPolicyOf } from './sandbox.js';
+import { componentToText } from './text.js';
+import { GENUI_TREE_COMPONENT } from './tree.js';
+/** The channel a turn runs on when nothing says otherwise: a browser (AG-UI, the HTTP chat, A2UI). */
+export const WEB_CHANNEL = 'web';
+/** The `channels` entry that serves every channel without one of its own. */
+export const DEFAULT_CHANNEL = 'default';
+/** Channels a person reads in a messaging app or a mailbox: the server draws for them. */
+export const MESSAGING_CHANNELS = Object.freeze([
+    'whatsapp',
+    'telegram',
+    'email',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * THE rule for which channel a turn runs on, read from its page context:
+ *
+ * - `pageContext.channel` is a string → that channel (an explicit override: `send({ channel })`, a
+ *   mobile client posting `pageContext: { channel: 'mobile' }`);
+ * - `pageContext.channel` is the address a text-channel adapter stamps (`{ name, conversation,
+ *   kind? }`) → its `kind` (`whatsapp`, `telegram`), else its `name`;
+ * - nothing → `web`: what AG-UI, the HTTP chat and A2UI serve (they stamp nothing, so a tool that
+ *   skips skeletons when `pageContext.channel` is set keeps working).
+ */
+export function turnChannel(pageContext) {
+    const value = pageContext?.channel;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    if (isRecord(value)) {
+        if (typeof value.kind === 'string' && value.kind.length > 0)
+            return value.kind;
+        if (typeof value.name === 'string' && value.name.length > 0)
+            return value.name;
+    }
+    return WEB_CHANNEL;
+}
+/** WhatsApp, Telegram and email are drawn by the server; every other channel by a client. */
+export function isMessagingChannel(channel) {
+    return MESSAGING_CHANNELS.includes(channel);
+}
+/** One channel's options, its own entry over `default` over the top level. */
+export function resolveGenuiChannel(base, channels, channel) {
+    const name = channel ?? WEB_CHANNEL;
+    const messaging = isMessagingChannel(name);
+    const entry = channels === undefined ? undefined : (channels[name] ?? channels.default);
+    if (entry === undefined) {
+        return {
+            name,
+            messaging,
+            configured: false,
+            mode: base.mode ?? 'tree',
+            ...(base.streaming !== undefined ? { streaming: base.streaming } : {}),
+            ...(base.sandbox !== undefined ? { sandbox: base.sandbox } : {}),
+            render: name === 'email' ? 'html' : 'native',
+        };
+    }
+    const sandbox = messaging ? false : (entry.sandbox ?? base.sandbox);
+    const streaming = entry.streaming ?? base.streaming;
+    return {
+        name,
+        messaging,
+        configured: true,
+        mode: entry.mode ?? (messaging ? 'per-component' : (base.mode ?? 'tree')),
+        ...(streaming !== undefined ? { streaming } : {}),
+        ...(sandbox !== undefined ? { sandbox } : {}),
+        render: entry.render ?? (name === 'email' ? 'html' : 'native'),
+        ...(entry.chartImages !== undefined ? { chartImages: entry.chartImages } : {}),
+        ...(entry.instructions !== undefined ? { instructions: entry.instructions } : {}),
+    };
+}
+/** Throws on a `channels` entry that names an unknown mode or render. */
+export function assertGenuiChannels(channels) {
+    if (channels === undefined)
+        return;
+    if (!isRecord(channels))
+        throw new TypeError('genui: channels must be an object');
+    for (const [name, entry] of Object.entries(channels)) {
+        if (entry === undefined)
+            continue;
+        if (!isRecord(entry))
+            throw new TypeError(`genui: channels.${name} must be an object`);
+        if (entry.mode !== undefined && !['tree', 'per-component', 'text'].includes(String(entry.mode)))
+            throw new TypeError(`genui: channels.${name}.mode must be 'tree', 'per-component' or 'text'`);
+        if (entry.render !== undefined && !['native', 'text', 'html'].includes(String(entry.render)))
+            throw new TypeError(`genui: channels.${name}.render must be 'native', 'text' or 'html'`);
+        if (entry.streaming !== undefined &&
+            entry.streaming !== 'partial' &&
+            entry.streaming !== 'complete')
+            throw new TypeError(`genui: channels.${name}.streaming must be 'partial' or 'complete'`);
+    }
+}
+function conversionOf(definition, channel) {
+    const channels = definition?.channels;
+    return channels === undefined || !Object.hasOwn(channels, channel)
+        ? undefined
+        : channels[channel];
+}
+/** A sandbox component (it carries a sandbox policy). */
+function isSandbox(definition) {
+    return sandboxPolicyOf(definition) !== undefined;
+}
+/**
+ * Whether `definition` can be drawn on `channel`. On a web channel every component can (the client's
+ * `uiCapabilities` narrow it); on a messaging channel a component can when it has a conversion for
+ * it, a chart renderer draws it, or it has a text summary (`fallbackText`) — a component without one
+ * would arrive as a JSON dump, so it is not offered. A sandbox never can, and `channels: { x: false }`
+ * opts a component out.
+ */
+export function canRenderOnChannel(definition, channel) {
+    if (definition.internal === true)
+        return false;
+    if (isSandbox(definition))
+        return !channel.messaging && channel.sandbox !== false;
+    if (!channel.messaging)
+        return conversionOf(definition, channel.name) !== false;
+    const conversion = conversionOf(definition, channel.name);
+    if (conversion === false)
+        return false;
+    if (definition.fallbackText !== undefined)
+        return true;
+    if (channel.render === 'text')
+        return false;
+    if (typeof conversion === 'function')
+        return true;
+    return channel.chartImages?.components.includes(definition.name) === true;
+}
+/**
+ * The catalog as `channel` may draw it: only what it can render, and its own sandbox (or none). With
+ * no `channels` configured the catalog is returned as it is.
+ */
+export function channelCatalog(catalog, channel) {
+    if (!channel.configured)
+        return catalog;
+    if (channel.mode === 'text')
+        return defineCatalog([], { jsonSchemaValidator: catalog.validator });
+    const existing = catalog.components.find(isSandbox);
+    const kept = catalog.components.filter((definition) => !isSandbox(definition) && canRenderOnChannel(definition, channel));
+    const sandbox = channel.messaging || channel.sandbox === false
+        ? undefined
+        : channel.sandbox === undefined || channel.sandbox === true
+            ? (existing ?? (channel.sandbox === true ? defineSandbox() : undefined))
+            : defineSandbox({
+                ...(existing !== undefined ? { name: existing.name } : {}),
+                ...channel.sandbox,
+            });
+    return defineCatalog(sandbox === undefined ? kept : [...kept, sandbox], {
+        jsonSchemaValidator: catalog.validator,
+    });
+}
+const CHANNEL_LABELS = {
+    whatsapp: 'WhatsApp',
+    telegram: 'Telegram',
+    email: 'email',
+};
+/** What a UI tool's description says about the channel the conversation is on. */
+export function channelInstructions(channel) {
+    if (!channel.configured)
+        return undefined;
+    const lines = [];
+    if (channel.messaging) {
+        const label = CHANNEL_LABELS[channel.name] ?? channel.name;
+        lines.push(channel.render === 'html'
+            ? `This conversation is read by ${label}: components arrive as formatted messages.`
+            : channel.render === 'text'
+                ? `This conversation is on ${label}: components arrive as their text summary.`
+                : `This conversation is on ${label}: components arrive as ${label} messages (text, reply buttons, lists, images) — no interactive views, no custom layouts.`);
+    }
+    if (channel.instructions !== undefined)
+        lines.push(channel.instructions);
+    return lines.length > 0 ? lines.join(' ') : undefined;
+}
+function titleOf(props) {
+    return typeof props.title === 'string' && props.title.length > 0 ? props.title : undefined;
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/** Plain text as minimal HTML: paragraphs, line breaks, `*bold*`. */
+export function textToHtml(text) {
+    return text
+        .split(/\n{2,}/)
+        .filter((block) => block.trim() !== '')
+        .map((block) => `<p>${escapeHtml(block)
+        .replace(/\*\*([^*\n]+)\*\*/g, '<strong>$1</strong>')
+        .replace(/\*([^*\n]+)\*/g, '<strong>$1</strong>')
+        .replace(/\n/g, '<br>')}</p>`)
+        .join('\n');
+}
+async function nodeMessages(catalog, name, props, channel) {
+    if (channel.render === 'text')
+        return undefined;
+    const definition = catalog.get(name);
+    const conversion = conversionOf(definition, channel.name);
+    if (typeof conversion === 'function') {
+        try {
+            const converted = await conversion(props, { channel: channel.name });
+            if (converted !== null && converted !== undefined)
+                return Array.isArray(converted) ? converted : [converted];
+        }
+        catch {
+            /* a failing conversion falls back to the text summary */
+        }
+    }
+    if (channel.chartImages?.components.includes(name) === true) {
+        try {
+            const image = await channel.chartImages.render(name, props);
+            if (image !== null) {
+                const title = titleOf(props);
+                return [{ image, ...(title !== undefined ? { text: `*${title}*` } : {}) }];
+            }
+        }
+        catch {
+            /* no image: the text summary */
+        }
+    }
+    return undefined;
+}
+/**
+ * What a pushed component (a tree included) is on a channel the server draws for: one or more
+ * messages — its conversions, chart images, and the text summary of everything else, in order.
+ * Consecutive text is joined. Never throws: a conversion that fails sends the summary.
+ */
+export async function renderChannelMessages(catalog, component, channel) {
+    const out = [];
+    const pushText = (text, from) => {
+        // (`from` names where the text came from: the first component of a run of text.)
+        if (text.trim() === '')
+            return;
+        const last = out.at(-1);
+        if (last !== undefined &&
+            last.buttons === undefined &&
+            last.list === undefined &&
+            last.image === undefined &&
+            last.html === undefined &&
+            last.text !== undefined) {
+            last.text = `${last.text}\n\n${text}`;
+            return;
+        }
+        out.push({
+            text,
+            component: from.name,
+            ...(from.id !== undefined ? { componentId: from.id } : {}),
+            ...(from.title !== undefined ? { title: from.title } : {}),
+        });
+    };
+    const visit = async (name, props, id, children, depth) => {
+        if (depth > 32)
+            return;
+        const title = titleOf(props);
+        const from = {
+            name,
+            ...(id !== undefined ? { id } : {}),
+            ...(title !== undefined ? { title } : {}),
+        };
+        const native = await nodeMessages(catalog, name, props, channel);
+        if (native !== undefined) {
+            for (const message of native) {
+                if (message.image === undefined &&
+                    message.buttons === undefined &&
+                    message.list === undefined &&
+                    message.html === undefined &&
+                    typeof message.text === 'string') {
+                    pushText(message.text, from);
+                    continue;
+                }
+                out.push({
+                    ...message,
+                    component: name,
+                    ...(id !== undefined ? { componentId: id } : {}),
+                    ...(title !== undefined ? { title } : {}),
+                });
+            }
+        }
+        else {
+            const definition = catalog.get(name);
+            const own = definition?.children === true && definition.fallbackText === undefined
+                ? ''
+                : componentToText(catalog, name, props);
+            pushText(own, from);
+        }
+        for (const child of children ?? [])
+            await visit(child.type, child.props, id, child.children, depth + 1);
+    };
+    if (component.name === GENUI_TREE_COMPONENT) {
+        const root = component.props.root;
+        if (root !== undefined) {
+            await visit(root.type, root.props, component.id, root.children, 0);
+        }
+    }
+    else {
+        await visit(component.name, component.props, component.id, undefined, 0);
+    }
+    if (channel.render === 'html') {
+        for (const message of out) {
+            if (message.html === undefined && message.text !== undefined)
+                message.html = textToHtml(message.text);
+        }
+    }
+    return out;
+}
+/** The UI action a pressed button (or picked list entry) stands for — the user's next turn. */
+export function channelButtonAction(button, from) {
+    return {
+        source: 'component',
+        name: button.action !== undefined && /^[A-Za-z0-9_.:-]{1,64}$/.test(button.action)
+            ? button.action
+            : 'select',
+        context: isRecord(button.value) ? button.value : {},
+        text: button.label,
+        ...(from.componentId !== undefined ? { componentId: from.componentId } : {}),
+        ...(from.title !== undefined ? { title: from.title } : {}),
+        timestamp: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=channels.js.map

package/dist/src/genui/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../../src/genui/channels.ts"],"names":[],"mappings":"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"}

package/dist/src/genui/chart-image.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Charts as images, for channels that take images but cannot draw a chart (WhatsApp, Telegram, an
+ * email): `chartSvg(props)` draws the builtin `Chart` (bar or line) as SVG, and `chartImages()` turns
+ * it into a PNG with `@resvg/resvg-js` — an OPTIONAL peer dependency, loaded only when a chart is
+ * actually drawn.
+ *
+ * ```ts
+ * import { chartImages } from '@adonis-agora/agent/genui/chart-image'
+ * genui({ catalog, channels: { whatsapp: { chartImages: chartImages() } } })
+ * ```
+ */
+import type { ChartImageRenderer } from './channels.js';
+import type { ChartProps } from './registry.js';
+export interface ChartSvgOptions {
+    /** Default 800. */
+    width?: number;
+    /** Default 450. */
+    height?: number;
+    /** Series colors, in order. Default: a palette readable on white. */
+    colors?: readonly string[];
+    /** Default `#ffffff`. */
+    background?: string;
+    /** Default `#1f2328`. */
+    foreground?: string;
+    /** Default: a list of common sans-serif families (resvg picks the first installed one). */
+    fontFamily?: string;
+}
+/** The builtin `Chart` as an SVG document: axes, gridlines, bars or lines, a legend for 2+ series. */
+export declare function chartSvg(props: ChartProps, options?: ChartSvgOptions): string;
+export interface ChartImagesOptions extends ChartSvgOptions {
+    /** The components drawn as images, all taking {@link ChartProps}. Default `['Chart']`. */
+    components?: readonly string[];
+    /** Font files for resvg (a server without system fonts draws no text otherwise). */
+    fontFiles?: readonly string[];
+}
+/** SVG → PNG bytes, with `@resvg/resvg-js`. */
+export declare function svgToPng(svg: string, options?: {
+    width?: number;
+    fontFiles?: readonly string[];
+}): Promise<Uint8Array>;
+/**
+ * Charts as PNG images on a channel (`genui({ channels: { whatsapp: { chartImages: chartImages() } } })`).
+ * A chart the renderer cannot draw (resvg missing, bad props) falls back to its text summary.
+ */
+export declare function chartImages(options?: ChartImagesOptions): ChartImageRenderer;
+//# sourceMappingURL=chart-image.d.ts.map

package/dist/src/genui/chart-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-image.d.ts","sourceRoot":"","sources":["../../../src/genui/chart-image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8BD,sGAAsG;AACtG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAoGjF;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,0FAA0F;IAC1F,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAuBD,+CAA+C;AAC/C,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC9D,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,kBAAkB,CAehF"}