@corbits/react-ui 0.1.0

package/dist/lib/chart-geometry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The arithmetic every chart in this registry does before it draws anything:
+ * pick round axis numbers, map a value onto a pixel, turn points into a path,
+ * and shorten a number without lying about it.
+ *
+ * It is plain functions over plain numbers, with no SVG and no React, so the
+ * hard part of a chart is the part you can read in isolation and check by hand.
+ * That is also the reason there is no charting dependency here: the geometry a
+ * bar chart and a line chart actually need is this file, and a library would
+ * bring a renderer, a theme layer and an interaction model that then have to be
+ * fought to match everything else.
+ */
+/**
+ * Axis ticks on round numbers, covering `[0, max]`.
+ *
+ * Rounds the *step* to 1, 2, 5 or 10 × a power of ten, then extends the top of
+ * the axis to a multiple of it. Ticks at 0 / 2,500 / 5,000 are read at a glance;
+ * ticks at 0 / 2,317 / 4,634 — what you get from dividing the data range — have
+ * to be decoded, and the reader stops trusting their own estimate of where a bar
+ * lands.
+ *
+ * Always starts at zero. A bar chart with a truncated baseline overstates
+ * differences by whatever fraction you cut off, which is the most effective way
+ * to mislead with a chart and the easiest to do by accident.
+ */
+export declare function niceTicks(max: number, count?: number): readonly number[];
+/**
+ * Maps `value` from `[0, domainMax]` onto `[0, rangeMax]` pixels.
+ *
+ * Guards a zero domain by returning zero rather than `NaN`. An all-zero series
+ * is a real thing to plot — "nothing happened" — and one `NaN` in a path
+ * attribute makes the entire path vanish, so a flat line at the baseline is both
+ * correct and the only readable failure mode.
+ */
+export declare function scaleLinear(value: number, domainMax: number, rangeMax: number): number;
+export type Point = {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * An SVG path through points, as straight segments.
+ *
+ * Straight, not smoothed. A spline through data invents values between the
+ * points — it will overshoot a local maximum and draw a peak that was never
+ * measured. Curves are for decoration; these are measurements.
+ */
+export declare function linePath(points: readonly Point[]): string;
+/**
+ * The filled region under a line: the line itself, then down to `baselineY`
+ * and back to the first x, closed. The baseline is passed in rather than
+ * assumed to be the box edge so the fill lands on the plot's zero line, inside
+ * whatever padding the chart drew around it.
+ */
+export declare function areaPath(points: readonly Point[], baselineY: number): string;
+/**
+ * "1,284" · "12.9K" · "4.2M".
+ *
+ * Compacts only past a thousand, and keeps one decimal so 12.9K and 13.4K stay
+ * distinguishable. Below a thousand the exact number is short enough to show,
+ * and rounding it would be a loss with no gain.
+ */
+export declare function formatCompact(value: number): string;

package/dist/lib/chart-geometry.js

@@ -0,0 +1,86 @@
+/**
+ * The arithmetic every chart in this registry does before it draws anything:
+ * pick round axis numbers, map a value onto a pixel, turn points into a path,
+ * and shorten a number without lying about it.
+ *
+ * It is plain functions over plain numbers, with no SVG and no React, so the
+ * hard part of a chart is the part you can read in isolation and check by hand.
+ * That is also the reason there is no charting dependency here: the geometry a
+ * bar chart and a line chart actually need is this file, and a library would
+ * bring a renderer, a theme layer and an interaction model that then have to be
+ * fought to match everything else.
+ */ /**
+ * Axis ticks on round numbers, covering `[0, max]`.
+ *
+ * Rounds the *step* to 1, 2, 5 or 10 × a power of ten, then extends the top of
+ * the axis to a multiple of it. Ticks at 0 / 2,500 / 5,000 are read at a glance;
+ * ticks at 0 / 2,317 / 4,634 — what you get from dividing the data range — have
+ * to be decoded, and the reader stops trusting their own estimate of where a bar
+ * lands.
+ *
+ * Always starts at zero. A bar chart with a truncated baseline overstates
+ * differences by whatever fraction you cut off, which is the most effective way
+ * to mislead with a chart and the easiest to do by accident.
+ */ export function niceTicks(max, count = 4) {
+    if (!Number.isFinite(max) || max <= 0) return [
+        0,
+        1
+    ];
+    const rough = max / count;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    const normalized = rough / magnitude;
+    const step = (normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10) * magnitude;
+    const top = Math.ceil(max / step) * step;
+    const ticks = [];
+    // Accumulating `value += step` drifts on fractional steps (0.1 + 0.2 …);
+    // multiplying an integer index does not.
+    for(let index = 0; index * step <= top + step / 2; index += 1){
+        ticks.push(index * step);
+    }
+    return ticks;
+}
+/**
+ * Maps `value` from `[0, domainMax]` onto `[0, rangeMax]` pixels.
+ *
+ * Guards a zero domain by returning zero rather than `NaN`. An all-zero series
+ * is a real thing to plot — "nothing happened" — and one `NaN` in a path
+ * attribute makes the entire path vanish, so a flat line at the baseline is both
+ * correct and the only readable failure mode.
+ */ export function scaleLinear(value, domainMax, rangeMax) {
+    if (domainMax <= 0) return 0;
+    return value / domainMax * rangeMax;
+}
+/**
+ * An SVG path through points, as straight segments.
+ *
+ * Straight, not smoothed. A spline through data invents values between the
+ * points — it will overshoot a local maximum and draw a peak that was never
+ * measured. Curves are for decoration; these are measurements.
+ */ export function linePath(points) {
+    if (points.length === 0) return "";
+    return points.map((point, index)=>`${index === 0 ? "M" : "L"}${point.x} ${point.y}`).join(" ");
+}
+/**
+ * The filled region under a line: the line itself, then down to `baselineY`
+ * and back to the first x, closed. The baseline is passed in rather than
+ * assumed to be the box edge so the fill lands on the plot's zero line, inside
+ * whatever padding the chart drew around it.
+ */ export function areaPath(points, baselineY) {
+    if (points.length === 0) return "";
+    const first = points[0];
+    const last = points[points.length - 1];
+    if (first === undefined || last === undefined) return "";
+    return `${linePath(points)} L${last.x} ${baselineY} L${first.x} ${baselineY} Z`;
+}
+/**
+ * "1,284" · "12.9K" · "4.2M".
+ *
+ * Compacts only past a thousand, and keeps one decimal so 12.9K and 13.4K stay
+ * distinguishable. Below a thousand the exact number is short enough to show,
+ * and rounding it would be a loss with no gain.
+ */ export function formatCompact(value) {
+    const magnitude = Math.abs(value);
+    if (magnitude >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+    if (magnitude >= 10_000) return `${(value / 1000).toFixed(1)}K`;
+    return value.toLocaleString();
+}

package/dist/lib/chart-palette.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Series colour, assigned by position and never by value.
+ *
+ * The five `--chart-*` tokens are a *fixed order*, not a pool. Slot 1 is always
+ * the first series in the data, slot 2 the second, and so on — so filtering a
+ * series out never repaints the survivors. A chart whose colours move when the
+ * legend changes destroys the one thing colour is doing here, which is identity.
+ *
+ * The ramp is blue, green, deep green, deep blue, red — and never orange.
+ * Orange is the reserved action accent: it marks the one thing on a screen a
+ * user can act on, so it must never paint a passive data series, where it would
+ * read as a call to action that is not there. Each step holds ≥3:1 against both
+ * the page and the card in both modes (the theme's contrast gate re-checks that
+ * on every build). Colour-vision safety comes from the ordering: green- and
+ * red-family slots never neighbour each other — under deuteranopia adjacent
+ * green/red collapse into one hue — and adjacent same-family steps differ by
+ * lightness, a channel colour-vision deficiency preserves. That separation is
+ * legal **only** alongside a second, non-colour channel — which is why every
+ * chart in this registry ships a legend, direct labels, a per-slot dash and a
+ * data table rather than treating them as polish.
+ */
+/** How many distinct series the palette can carry. Past this, fold. */
+export declare const CHART_SERIES_SLOTS = 5;
+export type ChartSeriesSlot = {
+    /** Stable slot key — a readable name for the token family, and a React key. */
+    readonly key: string;
+    /** CSS colour for strokes, fills, and legend swatches. */
+    readonly color: string;
+    /** SVG `stroke-dasharray` — the second channel. `undefined` means solid. */
+    readonly dash: string | undefined;
+};
+/**
+ * The ramp itself, in slot order, for callers that lay out a legend or paint a
+ * stacked mosaic and need the whole sequence rather than one slot. Same rules
+ * as `seriesColor`: fixed order, never cycled, orange never appears.
+ */
+export declare const CHART_SERIES: readonly ChartSeriesSlot[];
+/**
+ * The CSS colour for series `index`.
+ *
+ * Out-of-range indices get the muted ink, not a sixth invented hue and not slot
+ * 1 again. Cycling would give two different series the same colour — a silent
+ * misread — and generating a hue would put an unvalidated colour on screen.
+ * Grey says "these are lumped together", which is the truth once you are past
+ * five; use `foldSeries` so the label says so too.
+ */
+export declare function seriesColor(index: number): string;
+/**
+ * The stroke pattern for series `index` — the second channel, so a line chart
+ * is not read by colour alone.
+ *
+ * Colour carries identity; the dash carries it again for anyone who cannot
+ * separate two of the five hues, and for anyone printing this in grey. Slot 1
+ * is solid because the commonest chart has one series and a dashed lone line
+ * reads as "projected". The patterns get longer as the slots go on, so adjacent
+ * slots differ in period as well as in rhythm.
+ *
+ * Returned as an SVG `stroke-dasharray`; `undefined` means solid. Out-of-range
+ * indices are solid too, matching `seriesColor`'s grey — past five, the tail is
+ * one lumped-together thing and does not need a pattern of its own.
+ */
+export declare function seriesDash(index: number): string | undefined;
+export type FoldedSeries<T> = {
+    readonly named: readonly T[];
+    /** Everything past the last slot. Empty when it all fit. */
+    readonly rest: readonly T[];
+};
+/**
+ * Splits a series list into the ones that get their own colour and the tail.
+ *
+ * Five is not a styling limit, it is a reading limit: nobody tracks nine hues
+ * against a legend, and the sixth colour would have to be either a repeat or an
+ * unvalidated one. Sum `rest` into an "Other" series, or facet into small
+ * multiples — both are better charts than a nine-colour one.
+ */
+export declare function foldSeries<T>(series: readonly T[]): FoldedSeries<T>;

package/dist/lib/chart-palette.js

@@ -0,0 +1,92 @@
+/**
+ * Series colour, assigned by position and never by value.
+ *
+ * The five `--chart-*` tokens are a *fixed order*, not a pool. Slot 1 is always
+ * the first series in the data, slot 2 the second, and so on — so filtering a
+ * series out never repaints the survivors. A chart whose colours move when the
+ * legend changes destroys the one thing colour is doing here, which is identity.
+ *
+ * The ramp is blue, green, deep green, deep blue, red — and never orange.
+ * Orange is the reserved action accent: it marks the one thing on a screen a
+ * user can act on, so it must never paint a passive data series, where it would
+ * read as a call to action that is not there. Each step holds ≥3:1 against both
+ * the page and the card in both modes (the theme's contrast gate re-checks that
+ * on every build). Colour-vision safety comes from the ordering: green- and
+ * red-family slots never neighbour each other — under deuteranopia adjacent
+ * green/red collapse into one hue — and adjacent same-family steps differ by
+ * lightness, a channel colour-vision deficiency preserves. That separation is
+ * legal **only** alongside a second, non-colour channel — which is why every
+ * chart in this registry ships a legend, direct labels, a per-slot dash and a
+ * data table rather than treating them as polish.
+ */ /** How many distinct series the palette can carry. Past this, fold. */ export const CHART_SERIES_SLOTS = 5;
+/**
+ * The ramp itself, in slot order, for callers that lay out a legend or paint a
+ * stacked mosaic and need the whole sequence rather than one slot. Same rules
+ * as `seriesColor`: fixed order, never cycled, orange never appears.
+ */ export const CHART_SERIES = [
+    {
+        key: "blue",
+        color: "var(--chart-1)",
+        dash: undefined
+    },
+    {
+        key: "green",
+        color: "var(--chart-2)",
+        dash: "6 3"
+    },
+    {
+        key: "green-deep",
+        color: "var(--chart-3)",
+        dash: "2 3"
+    },
+    {
+        key: "blue-deep",
+        color: "var(--chart-4)",
+        dash: "10 3 2 3"
+    },
+    {
+        key: "red",
+        color: "var(--chart-5)",
+        dash: "1 3"
+    }
+];
+/**
+ * The CSS colour for series `index`.
+ *
+ * Out-of-range indices get the muted ink, not a sixth invented hue and not slot
+ * 1 again. Cycling would give two different series the same colour — a silent
+ * misread — and generating a hue would put an unvalidated colour on screen.
+ * Grey says "these are lumped together", which is the truth once you are past
+ * five; use `foldSeries` so the label says so too.
+ */ export function seriesColor(index) {
+    return CHART_SERIES[index]?.color ?? "var(--muted-foreground)";
+}
+/**
+ * The stroke pattern for series `index` — the second channel, so a line chart
+ * is not read by colour alone.
+ *
+ * Colour carries identity; the dash carries it again for anyone who cannot
+ * separate two of the five hues, and for anyone printing this in grey. Slot 1
+ * is solid because the commonest chart has one series and a dashed lone line
+ * reads as "projected". The patterns get longer as the slots go on, so adjacent
+ * slots differ in period as well as in rhythm.
+ *
+ * Returned as an SVG `stroke-dasharray`; `undefined` means solid. Out-of-range
+ * indices are solid too, matching `seriesColor`'s grey — past five, the tail is
+ * one lumped-together thing and does not need a pattern of its own.
+ */ export function seriesDash(index) {
+    return CHART_SERIES[index]?.dash;
+}
+/**
+ * Splits a series list into the ones that get their own colour and the tail.
+ *
+ * Five is not a styling limit, it is a reading limit: nobody tracks nine hues
+ * against a legend, and the sixth colour would have to be either a repeat or an
+ * unvalidated one. Sum `rest` into an "Other" series, or facet into small
+ * multiples — both are better charts than a nine-colour one.
+ */ export function foldSeries(series) {
+    return {
+        named: series.slice(0, CHART_SERIES_SLOTS),
+        rest: series.slice(CHART_SERIES_SLOTS)
+    };
+}

package/dist/lib/chat-message.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The conversation data model. Agent-agnostic on purpose: nothing here names a
+ * particular assistant, and the identity shown in the header is a prop.
+ *
+ * A message is an ordered list of parts rather than a string, because a single
+ * agent reply genuinely interleaves kinds — think, call a tool, think again,
+ * answer. Flattening that to `text` plus a `toolCalls` array loses the order,
+ * and the order is the only thing that makes a transcript readable.
+ */
+export type ChatRole = "user" | "agent" | "system";
+/** Delivery state of a message the user sent. Absent on received messages. */
+export type MessageStatus = "sending" | "sent" | "failed";
+export type TextPart = {
+    readonly type: "text";
+    readonly text: string;
+};
+/** Thinking text. One cumulative string per turn — there are no segment boundaries. */
+export type ReasoningPart = {
+    readonly type: "reasoning";
+    readonly text: string;
+};
+/**
+ * Tool lifecycle, restricted to states a caller can actually distinguish:
+ * running, finished, or finished badly. There is no "input streaming" state
+ * because a surface cannot render one usefully.
+ */
+export type ToolPartState = "running" | "done" | "error";
+export type ToolPart = {
+    readonly type: "tool";
+    readonly toolCallId: string;
+    /** Raw tool identifier, e.g. `slack__post_message`. */
+    readonly toolName: string;
+    readonly state: ToolPartState;
+    /** Human phrasing for what the tool did. Falls back to `toolName` when absent. */
+    readonly label?: string;
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Result or failure text, already stringified by the host. */
+    readonly output?: string;
+};
+export type FilePart = {
+    readonly type: "file";
+    readonly name: string;
+    readonly mediaType: string;
+    /** Resolved by the host — this model never fetches bytes. */
+    readonly url?: string;
+};
+export type MessagePart = TextPart | ReasoningPart | ToolPart | FilePart;
+export type ChatMessage = {
+    readonly id: string;
+    readonly role: ChatRole;
+    readonly parts: readonly MessagePart[];
+    /** ISO timestamp. */
+    readonly createdAt: string;
+    readonly status?: MessageStatus;
+};
+/** A tappable suggestion the agent offered. */
+export type QuickReply = {
+    readonly id: string;
+    readonly label: string;
+    /** Sent instead of the label when present. */
+    readonly value?: string;
+};
+/** Who the user is talking to. The host names its own agent. */
+export type AgentIdentity = {
+    readonly name: string;
+    readonly tagline?: string;
+    /** Two or three characters for the avatar. Derived from `name` when absent. */
+    readonly initials?: string;
+};
+/**
+ * Work the agent handed to a helper of its own.
+ *
+ * The same four states as a tool call plus `queued`, because a delegated task
+ * that has not started yet is a thing the user can see and a tool call is not.
+ * `tools` is the helper's own calls, so a subagent's detail is the same
+ * narrative the main transcript already renders rather than a second format.
+ */
+export type SubagentState = "queued" | "running" | "done" | "error";
+export type SubagentRun = {
+    readonly id: string;
+    /** What this helper is, e.g. "Researcher". Named by the host, not the registry. */
+    readonly name: string;
+    /** The one-line instruction it was given. */
+    readonly task?: string;
+    readonly state: SubagentState;
+    /** ISO timestamp. Absent while queued. */
+    readonly startedAt?: string;
+    readonly tools?: readonly ToolPart[];
+    /** Its answer, once it has one. */
+    readonly result?: string;
+};
+/** One conversation in the thread list. */
+export type ChatThreadSummary = {
+    readonly id: string;
+    readonly title: string;
+    /** ISO timestamp of the most recent message. */
+    readonly updatedAt: string;
+    readonly preview?: string;
+};
+/** The answer text: every text part joined, thinking and tools excluded. */
+export declare function messageText(message: ChatMessage): string;
+/** The turn's thinking, if the agent exposed any. */
+export declare function reasoningText(message: ChatMessage): string;
+export declare function toolParts(message: ChatMessage): readonly ToolPart[];
+/** True while any tool in the turn is still running — drives the live marker. */
+export declare function isTurnWorking(message: ChatMessage): boolean;
+/**
+ * A readable name for a tool id. `slack__post_message` → "Post message
+ * (Slack)"; `mail_send` → "Mail send". Never shows a raw snake_case id, and
+ * never invents a label for a tool it does not recognise — it only reformats
+ * what it was given, so a new tool reads correctly with no table to update.
+ */
+export declare function toolLabel(part: ToolPart): string;
+/** Avatar initials from a display name, capped at two characters. */
+export declare function agentInitials(identity: AgentIdentity): string;

package/dist/lib/chat-message.js

@@ -0,0 +1,41 @@
+/**
+ * The conversation data model. Agent-agnostic on purpose: nothing here names a
+ * particular assistant, and the identity shown in the header is a prop.
+ *
+ * A message is an ordered list of parts rather than a string, because a single
+ * agent reply genuinely interleaves kinds — think, call a tool, think again,
+ * answer. Flattening that to `text` plus a `toolCalls` array loses the order,
+ * and the order is the only thing that makes a transcript readable.
+ */ /** The answer text: every text part joined, thinking and tools excluded. */ export function messageText(message) {
+    return message.parts.filter((part)=>part.type === "text").map((part)=>part.text).join("");
+}
+/** The turn's thinking, if the agent exposed any. */ export function reasoningText(message) {
+    return message.parts.filter((part)=>part.type === "reasoning").map((part)=>part.text).join("");
+}
+export function toolParts(message) {
+    return message.parts.filter((part)=>part.type === "tool");
+}
+/** True while any tool in the turn is still running — drives the live marker. */ export function isTurnWorking(message) {
+    return toolParts(message).some((part)=>part.state === "running");
+}
+/**
+ * A readable name for a tool id. `slack__post_message` → "Post message
+ * (Slack)"; `mail_send` → "Mail send". Never shows a raw snake_case id, and
+ * never invents a label for a tool it does not recognise — it only reformats
+ * what it was given, so a new tool reads correctly with no table to update.
+ */ export function toolLabel(part) {
+    if (part.label !== undefined && part.label.length > 0) return part.label;
+    const [provider, ...rest] = part.toolName.split("__");
+    const humanise = (value)=>{
+        const words = value.replace(/[_-]+/g, " ").trim();
+        return words.charAt(0).toUpperCase() + words.slice(1);
+    };
+    if (rest.length > 0 && provider !== undefined) {
+        return `${humanise(rest.join("__"))} (${humanise(provider)})`;
+    }
+    return humanise(part.toolName);
+}
+/** Avatar initials from a display name, capped at two characters. */ export function agentInitials(identity) {
+    if (identity.initials !== undefined) return identity.initials;
+    return identity.name.split(/\s+/).map((word)=>word.charAt(0)).join("").slice(0, 2).toUpperCase() || "··";
+}

package/dist/lib/chat-parts.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The structural shape of a message's content: an ordered list of `Part`s
+ * rather than a string, because a single turn genuinely interleaves kinds —
+ * think, call a tool, emit a generative block, answer.
+ *
+ * This mirrors the wire shape a host's own parsed/validated part type would
+ * take (text, reasoning, tool-trace, block, file, event) but carries no
+ * validation of its own — parsing untrusted data into this shape is the
+ * host's job, at its own trust boundary, with whatever schema library it
+ * already uses. This package only renders a `Part[]` it is handed.
+ *
+ * Members are named `Part*` rather than the bare `TextPart` / `FilePart` a
+ * host might reach for on its own, because `lib/chat-message.ts` already
+ * publishes those names for its own, simpler message model — the two are
+ * deliberately separate types.
+ */
+export type PartText = {
+    readonly kind: "text";
+    readonly text: string;
+};
+/** Thinking text, plus how long the agent spent producing it. */
+export type PartReasoning = {
+    readonly kind: "reasoning";
+    readonly text: string;
+    /** Wall-clock milliseconds spent on this reasoning segment, once known. */
+    readonly durationMs?: number;
+};
+/**
+ * A tool call's lifecycle. Six states, not three: a tool call is not only
+ * running-or-finished, it can wait on human approval and that approval can be
+ * refused — a state distinct from an execution error. See `ToolBlockState`
+ * (`ui/tool-block.tsx`) for the matching render-side union.
+ */
+export type ToolTraceStatus = "pending" | "running" | "output-available" | "error" | "approval-requested" | "output-denied";
+export type PartToolTrace = {
+    readonly kind: "tool-trace";
+    readonly toolCallId: string;
+    readonly name: string;
+    readonly status: ToolTraceStatus;
+    readonly input?: unknown;
+    readonly output?: unknown;
+};
+/** A generative-UI block. `data` is opaque here — a host-specific registry parses it. */
+export type PartBlock = {
+    readonly kind: "block";
+    readonly block: {
+        readonly type: string;
+        readonly data: unknown;
+    };
+};
+export type PartFile = {
+    readonly kind: "file";
+    readonly name: string;
+    readonly mediaType: string;
+    /** Resolved by the host — this model never fetches bytes. */
+    readonly url?: string;
+};
+/** A system/lifecycle line, e.g. "agent joined". `data` carries whatever the event needs. */
+export type PartEvent = {
+    readonly kind: "event";
+    readonly event: string;
+    readonly data?: unknown;
+};
+export type Part = PartText | PartReasoning | PartToolTrace | PartBlock | PartFile | PartEvent;

package/dist/lib/chat-parts.js

@@ -0,0 +1,16 @@
+/**
+ * The structural shape of a message's content: an ordered list of `Part`s
+ * rather than a string, because a single turn genuinely interleaves kinds —
+ * think, call a tool, emit a generative block, answer.
+ *
+ * This mirrors the wire shape a host's own parsed/validated part type would
+ * take (text, reasoning, tool-trace, block, file, event) but carries no
+ * validation of its own — parsing untrusted data into this shape is the
+ * host's job, at its own trust boundary, with whatever schema library it
+ * already uses. This package only renders a `Part[]` it is handed.
+ *
+ * Members are named `Part*` rather than the bare `TextPart` / `FilePart` a
+ * host might reach for on its own, because `lib/chat-message.ts` already
+ * publishes those names for its own, simpler message model — the two are
+ * deliberately separate types.
+ */ export { };

package/dist/lib/csv.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A CSV parser sized for previewing a file in a browser tab, not for ingesting
+ * one.
+ *
+ * The distinction matters and drives every decision here. A preview has a
+ * hostile input (a user's arbitrary file), a hard latency budget (the tab must
+ * stay responsive), and a low cost of being approximate (the user can always
+ * download the original). So this refuses oversized input up front instead of
+ * streaming it, caps what it hands back instead of virtualising, and reports
+ * "not tabular" instead of guessing — a ragged file rendered as a grid puts
+ * cells under the wrong headers, which is a worse failure than showing raw text.
+ */
+/** Rows past this are dropped; the caller must say so in the UI. */
+export declare const CSV_ROW_CAP = 500;
+/** Columns past this are dropped; the caller must say so in the UI. */
+export declare const CSV_COLUMN_CAP = 40;
+/**
+ * Refuse to parse beyond this. 2 MiB of CSV is roughly 20k rows — already far
+ * past what anyone reads on screen, and enough DOM to lock the tab.
+ */
+export declare const CSV_MAX_PREVIEW_BYTES: number;
+export type ParsedCsv = {
+    readonly headers: readonly string[];
+    readonly rows: readonly (readonly string[])[];
+};
+/**
+ * True UTF-8 length, not `string.length`.
+ *
+ * `"é".length` is 1 but it costs 2 bytes, and a file of CJK text is three times
+ * its character count — sizing the guard by character count would let a file
+ * three times over budget through.
+ */
+export declare function utf8ByteLength(text: string): number;
+/**
+ * Parses CSV text, or returns `null` when it is too large to parse safely.
+ *
+ * `null` rather than a throw: "too big to preview" is an expected outcome of
+ * showing a user their own file, not an exceptional one, and the caller's
+ * response is to render a different surface rather than to catch.
+ */
+export declare function parseCsv(text: string): ParsedCsv | null;
+/**
+ * Whether the parse is rectangular enough to render as a grid.
+ *
+ * Requires at least two columns and every row to match the header width. A
+ * single-column "CSV" is prose that happens to have no commas, and a ragged one
+ * has no reliable column alignment — in both cases raw text tells the truth and
+ * a table does not.
+ */
+export declare function isTabular(parsed: ParsedCsv): boolean;
+export type CappedCsv = {
+    readonly headers: readonly string[];
+    readonly rows: readonly (readonly string[])[];
+    readonly totalRows: number;
+    readonly totalColumns: number;
+    readonly rowsTruncated: boolean;
+    readonly columnsTruncated: boolean;
+};
+/** Trims a parse to the caps, keeping the original totals so the UI can say so. */
+export declare function capCsv(parsed: ParsedCsv): CappedCsv;