@fx-/chat-ink 0.0.0-stage → 0.1.0

package/dist/images.d-KUBzdbd9.d.ts

@@ -0,0 +1,383 @@
+import { CustomBlock, DetailLevel, RenderableMessage } from "@fx-/chat-core";
+
+//#region src/lines/measure.d.ts
+type Measure = (text: string) => number;
+/**
+* `width`'s results (default: `string-width`, which Ink measures with), with
+* each distinct grapheme cluster measured once. The package sums independent
+* per-cluster widths, so caching changes no result; on Bun its emoji check is
+* pathologically slow and the same few clusters are measured over and over.
+* Text with ANSI escapes goes to `width` as it is (stripping spans clusters).
+* The cache is bounded and starts over when full.
+*/
+declare function cachedMeasure(width?: Measure, limit?: number): Measure;
+declare const defaultMeasure: Measure;
+/** Grapheme clusters of `text` (so a wide or combined character is never split). */
+declare function graphemes(text: string): string[];
+/** Cut `text` to at most `cells`, ending with `…` when cut. */
+declare function truncate(text: string, cells: number, measure?: Measure): string;
+/** Split `text` into pieces of at most `cells` each, never inside a grapheme. */
+declare function hardSplit(text: string, cells: number, measure?: Measure): string[];
+/** One wrapped row and how it joins the previous row when copied. */
+interface WrappedRow {
+    text: string;
+    wrap?: 'soft' | 'hard';
+}
+/**
+* Wrap one paragraph (no newlines) to `width` cells at spaces. A word longer
+* than the line is split with a `hard` join; other continuation rows are
+* `soft` (a copy rejoins them with a space).
+*/
+declare function wrapText(text: string, width: number, measure?: Measure): WrappedRow[];
+/** Wrap text with newlines: each line wrapped on its own (hard line breaks stay). */
+declare function wrapLines(text: string, width: number, measure?: Measure): WrappedRow[];
+
+//#endregion
+//#region src/theme.d.ts
+/**
+* The injected look of the terminal renderer.
+*
+* Like `@fx-/chat`'s `classNames`, the package decides structure and semantics
+* and the host decides appearance: every piece of text names its ROLE and the
+* theme answers with an appearance. Glyphs (icons, disclosure markers, spinner
+* frames) are injected the same way. The defaults are greyscale and plain, so
+* an un-themed transcript reads correctly on any terminal.
+*/
+/** Text attributes for one role. An absent attribute is not applied. */
+interface InkAppearance {
+    /** Any Ink/chalk colour name or hex string. */
+    color?: string;
+    dim?: boolean;
+    bold?: boolean;
+    italic?: boolean;
+    inverse?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+/** The semantic roles text is drawn in. */
+type InkThemeRole = 
+/** Ordinary answer text. */
+'content'
+/** Secondary text: timers, metrics, hints, reasoning bodies. */
+ | 'muted'
+/** Emphasis: group/row labels. */
+ | 'strong'
+/** Markers: glyphs, disclosure carets, `+N` counts. */
+ | 'marker'
+/** Frame and separators (composer border). */
+ | 'chrome'
+/** The composer cursor. */
+ | 'cursor' | 'positive' | 'caution' | 'danger'
+/** The user's own messages. */
+ | 'user'
+/** The assistant's role label. */
+ | 'assistant'
+/** Per-message accent: frame gutters, footer corners, the live pulse. */
+ | 'accent'
+/** Code spans and blocks. */
+ | 'code'
+/** Links. */
+ | 'link'
+/** Selected text (mouse selection). */
+ | 'selection';
+type InkTheme = Record<InkThemeRole, InkAppearance>;
+/** Greyscale defaults: no hue anywhere. */
+declare const plainTheme: InkTheme;
+/** Glyphs used by the renderer. */
+interface InkGlyphs {
+    collapsed: string;
+    expanded: string;
+    /** Kind icons, by the core summary icon name. */
+    brain: string;
+    wrench: string;
+    gear: string;
+    checklist: string;
+    /** Plan entry markers by status (a live in-progress entry draws the spinner). */
+    planDone: string;
+    planActive: string;
+    planPending: string;
+    success: string;
+    error: string;
+    /** Prefix of the user's messages. */
+    user: string;
+    /** Prefix of the assistant's messages. */
+    assistant: string;
+    /** Prompt shown before the composer input. */
+    prompt: string;
+    /** Spinner animation frames. */
+    spinner: readonly string[];
+    /** Between footer facts and status facts. */
+    separator: string;
+    /** @deprecated No longer drawn (the live tail's row uses `earlier`); kept for existing glyph sets. */
+    tool: string;
+    /** Before the live tail's row counting hidden earlier activity (empty: no marker). */
+    earlier: string;
+    /** Tool row status markers (a live call draws the spinner). */
+    toolSuccess: string;
+    toolError: string;
+    /** @deprecated No longer drawn (a live call draws the spinner); kept for existing glyph sets. */
+    toolRunning: string;
+    toolIdle: string;
+    /** Frames: boxes, gutters and footer corner. */
+    boxTopLeft: string;
+    boxTopRight: string;
+    boxBottomLeft: string;
+    boxBottomRight: string;
+    boxJunction: string;
+    boxHorizontal: string;
+    boxVertical: string;
+    footer: string;
+    /** The dotted bar before tool output lines. */
+    outputBar: string;
+    attachment: string;
+    image: string;
+    /** Queued (pending) message rows. */
+    pending: string;
+    /** Live pulse frames for the status line. */
+    pulse: readonly string[];
+    /** Markdown: list bullets, task markers, rules, quote/code bars, table joints. */
+    bullet: string;
+    taskOpen: string;
+    taskDone: string;
+    rule: string;
+    quoteBar: string;
+    codeBar: string;
+    tableColumn: string;
+    tableCross: string;
+}
+/**
+* The default glyphs: monochrome text, one cell each. No glyph is
+* emoji-capable (Unicode `Emoji=No`), so terminals cannot widen or colour one,
+* and every glyph is one that common monospace fonts carry.
+*/
+declare const plainGlyphs: InkGlyphs;
+/** Glyphs using only ASCII, for terminals without box-drawing or emoji symbols. */
+declare const asciiGlyphs: InkGlyphs;
+/**
+* Opt-in colour icons over {@link plainGlyphs}: only code points that are
+* emoji by default (`Emoji_Presentation=Yes`), which terminals and the
+* default measure both treat as two cells. Turn it on with
+* `<InkChatProvider components={{ glyphs: emojiGlyphs }}>`.
+*/
+declare const emojiGlyphs: InkGlyphs;
+
+//#endregion
+//#region src/lines/model.d.ts
+interface Span {
+    text: string;
+    /** Theme role, resolved at render time. */
+    role?: InkThemeRole;
+    /** An explicit appearance (e.g. a per-message accent), applied over the role. */
+    style?: InkAppearance;
+    bold?: boolean;
+    italic?: boolean;
+    dim?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    inverse?: boolean;
+    /** A literal colour, only where no role can say it. */
+    color?: string;
+    /** Layout (borders, gutters, indents, bars): drawn, never copied. */
+    chrome?: boolean;
+    /** Copied as this string once per character instead of as itself. */
+    copyEach?: string;
+}
+/** What a click on a line acts on. */
+type LineTarget = {
+    kind: 'tool-output';
+    blockId: string;
+} | {
+    kind: 'json-toggle';
+    blockId: string;
+    path: string;
+    open: boolean;
+} | {
+    kind: 'image';
+    src: string;
+} | {
+    kind: 'row-toggle';
+    rowKey: string;
+};
+interface Line {
+    spans: Span[];
+    /** How this line joins the previous one in a copy: a space (`soft`) or nothing (`hard`). */
+    wrap?: 'soft' | 'hard';
+    /** Pure decoration (rules, frames, footers): skipped by copy. */
+    frame?: boolean;
+    /** Which message (and block) produced it. */
+    owner: {
+        messageId: string;
+        blockId?: string;
+    };
+    target?: LineTarget;
+}
+/** A span. */
+declare function span(text: string, extra?: Omit<Span, 'text'>): Span;
+/** Prepend spans, keeping the line's metadata. */
+declare function prefix(line: Line, spans: Span[]): Line;
+/** Append spans, keeping the line's metadata. */
+declare function suffix(line: Line, spans: Span[]): Line;
+/** The line's text as drawn. */
+declare function lineText(line: Line): string;
+
+//#endregion
+//#region src/lines/layout.d.ts
+/** A line before its owner is assigned. */
+type LineDraft = Omit<Line, 'owner'> & {
+    owner?: Line['owner'];
+};
+/** Host labels for the keys that act on a message (empty by default). */
+interface FooterHints {
+    /** Shown with an outcome, e.g. `^R again`. */
+    retry?: string;
+    /** Collapsed with activity, e.g. `^T details`. */
+    details?: string;
+    /** In details with tool output, e.g. `^T open all`. */
+    openAll?: string;
+    /** In details or full, e.g. `Esc close`. */
+    close?: string;
+}
+/** Open state of foldable rows and JSON members, per block (or row key) and path. */
+interface OpenState {
+    version: number;
+    isOpen(blockId: string, path: string): boolean;
+}
+declare const NOTHING_OPEN: OpenState;
+/** The path a collapsible row's open state is kept under. */
+declare const ROW_PATH = "#row";
+/** A markdown layout: source → lines (owners are assigned by the caller). */
+type MarkdownLayout = (source: string, width: number, options: {
+    streaming?: boolean;
+    measure: Measure;
+    glyphs: InkGlyphs;
+    /** Lays out a line that is only an image, when the host draws images. */
+    image?: LayoutContext['image'];
+}) => LineDraft[];
+/** The default markdown layout: plain text, wrapped, in the `content` role. */
+declare const plainMarkdownLayout: MarkdownLayout;
+/** Context for a host's custom block layout. */
+interface BlockLayoutContext {
+    width: number;
+    isLive: boolean;
+    measure: Measure;
+}
+interface LayoutContext {
+    width: number;
+    detail: DetailLevel;
+    placement: 'inline' | 'after-content';
+    /** Newest tool rows a collapsed live message shows (default 3). */
+    liveTail: number;
+    isActive: (message: RenderableMessage) => boolean;
+    /** Whole-second clock for live facts and timers; only live messages read it. */
+    now: number;
+    opened: OpenState;
+    markdown: MarkdownLayout;
+    glyphs: InkGlyphs;
+    theme: InkTheme;
+    hints: FooterHints;
+    /** Footer on a live message (default true in the viewport). */
+    liveFooter: boolean;
+    blockLayouts?: Record<string, (block: CustomBlock, ctx: BlockLayoutContext) => LineDraft[]>;
+    frame: MessageFrame;
+    accentFor?: ((message: RenderableMessage) => InkThemeRole | InkAppearance) | undefined;
+    measure: Measure;
+    /** Lays out a block image line, when the host draws images. */
+    image?: ((src: string, alt: string, width: number) => LineDraft[] | undefined) | undefined;
+    /** Host facts after a message's own footer facts (e.g. `turn 42` in details). */
+    footerExtras?: ((message: RenderableMessage, detail: DetailLevel) => string[]) | undefined;
+    /**
+     * A finished answer's activity when collapsed: its own rows (default), or
+     * only the footer's counts (every activity row is dropped, in either
+     * placement, when the answer has a footer).
+     */
+    finishedActivity?: 'row' | 'footer' | undefined;
+    /**
+     * A blank decoration line between content and an adjacent activity row or
+     * group (default true). Consecutive activity rows stay together.
+     */
+    activitySpacing?: boolean | undefined;
+}
+/** What a frame needs to wrap a laid-out message. */
+interface FrameInput {
+    message: RenderableMessage;
+    body: LineDraft[];
+    /** Footer spans (facts and hints), when the message has a footer. */
+    footer?: Span[];
+    /** Whether this message shows anything. */
+    shows: boolean;
+    /** Whether the next message (an answer) shows — a frame junction may hang from it. */
+    nextShows: boolean;
+    live: boolean;
+    /** The message's accent as an explicit appearance. */
+    accent: InkAppearance;
+    ctx: LayoutContext;
+}
+/** A message frame: the injected look around a message. */
+interface MessageFrame {
+    /** Stable id (part of the layout cache key). */
+    id: string;
+    /** Width available to the message body inside the frame. */
+    innerWidth(message: RenderableMessage, width: number): number;
+    layout(input: FrameInput): LineDraft[];
+}
+/** Resolve an accent to an explicit appearance. */
+declare function resolveAccent(message: RenderableMessage, ctx: Pick<LayoutContext, 'accentFor' | 'theme'>): InkAppearance;
+/** Lay out a message's body (no frame) at `w` cells. */
+declare function layoutBody(original: RenderableMessage, w: number, ctx: LayoutContext): LineDraft[];
+/** The footer spans of a message: planned facts with injected glyphs, then hints. */
+declare function footerSpans(original: RenderableMessage, ctx: LayoutContext): Span[] | undefined;
+/** Whether an answer shows anything: content, reasoning, an outcome, a tool call or a plan. */
+declare function showsSomething(message: RenderableMessage): boolean;
+/** Lay out one message inside its frame. */
+declare function layoutMessage(original: RenderableMessage, ctx: LayoutContext, next?: RenderableMessage): Line[];
+
+//#endregion
+//#region src/lines/images.d.ts
+/** A cell box: columns × rows. */
+interface CellBox {
+    columns: number;
+    rows: number;
+}
+type ImageState = {
+    kind: 'ask';
+} | {
+    kind: 'loading';
+} | {
+    kind: 'failed';
+    error: string;
+}
+/** One string per cell row, drawn as text in `color`. */
+ | {
+    kind: 'ready';
+    rows: string[];
+    color?: string;
+};
+interface ImageProvider {
+    /** The state for a source in a box, or undefined for "not mine — render as text". */
+    get(src: string, box: CellBox): ImageState | undefined;
+    /** Allow an `ask` source (the user clicked it). */
+    allow(src: string): void;
+    /** Bumped on any change; part of the layout cache key. */
+    readonly version: number;
+    /** Called on every change; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** A terminal query the viewport writes once (e.g. the cell size in pixels). */
+    readonly query?: string;
+    /** Recognise the terminal's reply to the query; returns whether `input` was one. */
+    takeReply?(input: string): boolean;
+}
+/** The largest thumbnail, in cells. */
+declare const THUMBNAIL: CellBox;
+interface ImageLayoutOptions {
+    provider?: ImageProvider | undefined;
+    expanded: boolean;
+    /** Rows an expanded image may take. */
+    maxHeight: number;
+    glyphs: InkGlyphs;
+    measure: Measure;
+}
+/** Lay out a block image: its ready rows, then a wrapped caption; every line targets the source. */
+declare function layoutImage(src: string, alt: string, width: number, { provider, expanded, maxHeight, glyphs, measure }: ImageLayoutOptions): LineDraft[];
+
+//#endregion
+export { BlockLayoutContext, CellBox, FooterHints, FrameInput, ImageLayoutOptions, ImageProvider, ImageState, InkAppearance, InkGlyphs, InkTheme, InkThemeRole, LayoutContext, Line, LineDraft, LineTarget, MarkdownLayout, Measure, MessageFrame, NOTHING_OPEN, OpenState, ROW_PATH, Span, THUMBNAIL, WrappedRow, asciiGlyphs, cachedMeasure, defaultMeasure, emojiGlyphs, footerSpans, graphemes, hardSplit, layoutBody, layoutImage, layoutMessage, lineText, plainGlyphs, plainMarkdownLayout, plainTheme, prefix, resolveAccent, showsSomething, span, suffix, truncate, wrapLines, wrapText };