@shapesos/clay 0.10.0 → 0.12.0

package/dist/types-C0BvwliI.d.cts

@@ -0,0 +1,332 @@
+import { ComponentType } from 'react';
+import { C as ChartSeries } from './types-B2aYk82c.cjs';
+
+/**
+ * Shared artifact primitives — the discriminator constant and the cross-variant `ArtifactBase`
+ * shape that every concrete artifact record extends.
+ *
+ * Pulled into its own file so the per-type `types.ts` files (`table-artifact/types.ts`,
+ * `chart-artifact/types.ts`) and the union assembler (`artifacts/types.ts`) can all depend on
+ * one canonical source without creating a circular module graph between them.
+ */
+/**
+ * Artifact-type discriminator constants. Uppercase to match the server-side `artifactTypes`
+ * constant — io-server stores `artifact.type === "TABLE"` (aligned with the GraphQL enum).
+ */
+declare const artifactTypes: {
+    readonly TABLE: "TABLE";
+    readonly CHART: "CHART";
+};
+/** Discriminator for artifact types. Additive — new types extend this union. */
+type ArtifactType = (typeof artifactTypes)[keyof typeof artifactTypes];
+/** Common shape every artifact record carries. Discriminated by `type`. */
+interface ArtifactBase<TType extends ArtifactType, TConfig> {
+    /** Artifact-type discriminator. */
+    type: TType;
+    /** Human-readable label. Nullable when the artifact has no title. */
+    title: string | null;
+    /** Rendering config — shape varies per artifact type. */
+    config: TConfig;
+    /** Protected-asset metadata pointing to the underlying data payload. Null while the asset is unavailable. */
+    protectedAsset: {
+        /** Time-limited URL the renderer fetches the artifact's data from. */
+        presignedUrl: string;
+    } | null;
+}
+/**
+ * A row inside an artifact's parsed CSV. Every cell is the raw string from the CSV (or `null`
+ * for the empty string). Used by every artifact kind whose data wire is a CSV (`TABLE`, `CHART`).
+ * The renderer never coerces — type-aware formatting is a server concern (the CSV's contents
+ * are what the user sees).
+ */
+type ArtifactDataRow = Record<string, string | null>;
+
+/**
+ * Rendering config for a `BAR` chart. `xKey` selects the categorical axis; each series
+ * contributes one `<Bar>`. `stacked` collapses all series onto a single stack-id (so they sum
+ * vertically); when false / omitted bars are grouped side-by-side per x-tick.
+ */
+interface BarChartConfig extends ChartConfigBase {
+    variant: "BAR";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+    /** When true, stack all series on one stack-id. When false / omitted, group bars side-by-side. */
+    stacked?: boolean;
+}
+
+/**
+ * Rendering config for a `LINE` chart. `xKey` selects the categorical/temporal axis from the
+ * CSV; each series contributes one `<Line>` overlaid against that axis.
+ */
+interface LineChartConfig extends ChartConfigBase {
+    variant: "LINE";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+}
+
+/**
+ * Rendering config for a `PIE` chart. `categoryKey` names the slice; `valueKey` carries the
+ * slice's numeric magnitude. One row of CSV becomes one slice. The base's `series` array is
+ * always empty for pie — colors are resolved by row index from the palette.
+ */
+interface PieChartConfig extends ChartConfigBase {
+    variant: "PIE";
+    /** CSV column key used as the slice label. */
+    categoryKey: string;
+    /** CSV column key used as the slice numeric value. */
+    valueKey: string;
+}
+
+/**
+ * Discriminated union of all supported chart variant configs. Assembled here (not in the parent
+ * `types.ts`) because the union depends on each variant service file as its single source of
+ * truth for that variant's config type.
+ *
+ * Extension pattern: add a new variant by creating one `*-chart-variant-service.ts` file and
+ * extending this union + the `ChartVariantServices` map below. No edits to the dispatcher.
+ */
+type ChartConfig = LineChartConfig | BarChartConfig | PieChartConfig;
+
+/**
+ * Optional stats embedded in `ChartConfig` so clients can pre-render UI before fetching the
+ * actual CSV (e.g. a skeleton sized to the eventual row count). Mirrors `TableStats`.
+ */
+interface ChartStats {
+    /** Total number of rows in the materialised CSV. */
+    rowCount: number;
+}
+/**
+ * Cross-variant base for `ChartConfig`. Carries the fields every variant shares — series
+ * descriptors and optional stats. Per-variant config interfaces (in `chart-variant-services/`)
+ * extend this with their own required fields.
+ *
+ * Note: `series` is always present on the wire (matching the GraphQL `[ChartSeries!]!` shape)
+ * even for PIE — PIE just receives an empty array. Keeping it on the base mirrors the wire shape
+ * exactly and avoids TS object-literal freshness errors for callers that explicitly set
+ * `series: []` on a pie config.
+ */
+interface ChartConfigBase {
+    /** Series descriptors in render order. LINE/BAR consume these; PIE ignores in favour of `categoryKey`+`valueKey`. */
+    series: ChartSeries[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: ChartStats;
+}
+/** Concrete chart artifact record. */
+type ChartArtifactRecord = ArtifactBase<typeof artifactTypes.CHART, ChartConfig>;
+/**
+ * Localized labels for the `CHART` artifact's user-facing strings. Covers action buttons AND
+ * status messages — see `TableArtifactLabels` for the same shape philosophy. Extends as the
+ * chart artifact grows its action set (e.g. future `copyAsPng`); optional keys document
+ * anticipated additions without forcing every consumer to provide them today.
+ */
+interface ChartArtifactLabels {
+    /** Tooltip + aria-label on the Download CSV button in the chart artifact header. */
+    download: string;
+    /** Status message shown when no presigned URL is available or the chart config is malformed. */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime. */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched. */
+    loading: string;
+    /** Status message shown when the fetched CSV has zero data rows. */
+    empty: string;
+    /**
+     * Category labels treated as the "Others" bucket in pie charts (case-insensitive). Matching
+     * slices are pinned to the end of the sweep and rendered in neutral grey. The agent writes a
+     * translated bucket name in non-English UIs (e.g. "אחרים", "Otros") — consumer passes the
+     * localized list here so clay can detect the bucket regardless of language. English fallback
+     * is `["Others", "Other"]`. Pass `[]` to disable Others detection (every slice from the palette).
+     */
+    othersCategoryLabels: readonly string[];
+}
+/** English fallback for `ChartArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_CHART_ARTIFACT_LABELS: ChartArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the chart artifact. Mirrors
+ * `ChartArtifactLabels`'s shape philosophy: one entry per action this artifact exposes
+ * (download today; future "Copy as PNG" etc.). Every callback is optional — consumers wire
+ * only the actions they care about. The artifact passes its own `ChartArtifactRecord` as the
+ * only argument so consumers can derive analytics context (title, config.variant, etc.) without
+ * a per-block closure at every render site.
+ *
+ * The callback fires alongside the default browser behaviour (e.g. `onDownload` does not
+ * prevent the anchor's download navigation) — it's purely for analytics / observability hooks.
+ */
+interface ChartArtifactCallbacks {
+    /** Fires when the Download CSV button is clicked. Browser-native download still happens. */
+    onDownload?: (artifact: ChartArtifactRecord) => void;
+}
+
+/**
+ * A single column descriptor for a `TableArtifact`. Carries the ORDER and LABEL for the
+ * rendered table — `key` selects a column from the CSV header; `label` overrides the rendered
+ * header text. The CSV is always the source of truth for the data shape; clay never coerces,
+ * reformats, or interprets cell values.
+ */
+interface TableColumn {
+    /** Matches a header in the CSV. Required. Used to project + order the CSV's columns. */
+    key: string;
+    /** Human-readable header text. Required. */
+    label: string;
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every cell is rendered as
+     * the raw CSV string (or empty for null). Format conversion is a server concern; if a column
+     * needs to be "Yes/No" instead of "true/false", the server should emit it that way in the CSV.
+     * Kept in the interface so callers that pass `type` (e.g. io-client) don't get a type error.
+     */
+    type?: "string" | "number" | "date" | "boolean";
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every column is left-aligned
+     * by design. Kept in the interface for forward-compat; restore per-column alignment by editing
+     * `table-artifact-content.tsx` if a future use case justifies it.
+     */
+    align?: "left" | "center" | "right";
+}
+/**
+ * Optional stats embedded in `TableConfig` so clients can pre-render UI before fetching the
+ * actual data payload (e.g. N loading shimmers sized to the eventual row count).
+ *
+ * Backward-compat: optional everywhere — older artifacts persisted before this field shipped
+ * still validate. The renderer falls back to a single status-message line when `stats` is absent.
+ */
+interface TableStats {
+    /** Total number of rows in the materialised CSV. Lets the loading branch render shimmers. */
+    rowCount: number;
+}
+/** Rendering config for a table artifact, stored at `artifact.config` (JSONB on the server). */
+interface TableConfig {
+    /** Column descriptors in render order. */
+    columns: TableColumn[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: TableStats;
+}
+/** Alias retained for callers typed against the table-specific name. */
+type TableRow = ArtifactDataRow;
+/** Concrete table artifact record. */
+type TableArtifactRecord = ArtifactBase<typeof artifactTypes.TABLE, TableConfig>;
+/**
+ * Localized labels for the `TABLE` artifact's user-facing strings. Covers both action buttons
+ * (download today; future "Copy as CSV", etc.) AND status messages (loading / error / empty /
+ * unavailable). Consumer passes the bag from their i18n layer; clay falls back to English
+ * defaults when omitted (per-key Partial merge).
+ */
+interface TableArtifactLabels {
+    /** Tooltip + aria-label on the Download CSV button in the table artifact header. */
+    download: string;
+    /**
+     * Status message shown when no presigned URL is available (permanent server-side absence) or
+     * the artifact config is malformed. Both states reduce to "the underlying file isn't usable".
+     */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime (transient). */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched and `stats.rowCount` is not known. */
+    loading: string;
+    /** Empty-state row inside the table body when the fetched CSV has zero data rows. */
+    empty: string;
+}
+/** English fallback for `TableArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_TABLE_ARTIFACT_LABELS: TableArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the table artifact. Mirrors
+ * `ChartArtifactCallbacks` — see that interface for the shape philosophy. Every callback is
+ * optional; the artifact passes its own `TableArtifactRecord` as the only argument so consumers
+ * can derive analytics context without a per-block closure at every render site.
+ */
+interface TableArtifactCallbacks {
+    /** Fires when the Download CSV button is clicked. Browser-native download still happens. */
+    onDownload?: (artifact: TableArtifactRecord) => void;
+}
+
+/**
+ * Artifact-domain types — wire-protocol shapes shared between artifact components, block-services,
+ * and consumers. Splits responsibilities across three layers so each artifact kind owns its own
+ * `types.ts` and this file assembles the cross-type union + service contract:
+ *
+ * 1. **`artifact-base.ts`** — discriminator (`artifactTypes`), `ArtifactBase<TType, TConfig>`, and
+ *    `ArtifactDataRow`. Pulled out so each per-type `types.ts` and this assembler can depend on
+ *    one canonical base without a circular module graph.
+ * 2. **`<type>-artifact/types.ts`** — per-artifact-type records, configs, labels, and defaults.
+ *    Variant-specific types (e.g. `LineChartConfig`) live in even deeper per-variant service files.
+ * 3. **This file** — the cross-type `ArtifactRecord` union, the labels map keyed by artifact type,
+ *    and the `ArtifactService<TArtifact, TLabels>` registry contract used by the dispatcher.
+ *
+ * Mirrored from the agent / io-server contract — see the `chat-typed-content-blocks-and-artifacts`
+ * plan, §6.4 (table contract).
+ */
+
+/**
+ * Per-artifact-type labels map. Lets a consumer pass labels for every artifact kind in a single
+ * bag at the block layer (`<ArtifactRefBlock>` payload); the dispatcher routes the matching slice
+ * (`labels[artifact.type]`) to the concrete artifact component.
+ *
+ * Extension pattern: add a new field here when adding a new artifact type. Keep the field
+ * optional so older consumers don't break on upgrade.
+ */
+interface ArtifactLabelsMap {
+    TABLE: TableArtifactLabels;
+    CHART: ChartArtifactLabels;
+}
+/**
+ * Per-artifact-type callbacks map. Sibling to `ArtifactLabelsMap` — consumer passes a single
+ * bag at the block layer covering every artifact type's action callbacks (today: `onDownload`).
+ * Used for analytics / observability hooks — every callback is optional and fires alongside
+ * the default browser behaviour (it does NOT replace it).
+ *
+ * Each callback receives its artifact-type's `ArtifactBase`-derived record so consumers can
+ * derive analytics context (title, config, etc.) from one wiring at the chat-surface level
+ * instead of per-block closures.
+ */
+interface ArtifactCallbacksMap {
+    TABLE: TableArtifactCallbacks;
+    CHART: ChartArtifactCallbacks;
+}
+/**
+ * Discriminated union of all supported artifacts. Extension pattern: add the new branch here AND
+ * in the `ArtifactServices` map (single source of truth for the type→component mapping). Older
+ * clay versions that don't know about a new type silently render nothing — see `ArtifactRefBlock`
+ * guard.
+ */
+type ArtifactRecord = TableArtifactRecord | ChartArtifactRecord;
+/**
+ * Props every concrete artifact component receives from the dispatcher.
+ *
+ * `labels` is the FULL `ArtifactLabelsMap` bag — every artifact component receives the same
+ * shape and reads its own slice internally (`labels?.TABLE`, `labels?.CHART`). One uniform prop
+ * type across all artifact components keeps the block-layer dispatcher a generic forward — no
+ * per-type branch, no cast, no map-key extraction at the seam.
+ */
+interface ArtifactServiceProps<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** The artifact metadata (config + presigned URL). */
+    artifact: TArtifact;
+    /**
+     * Optional localized labels keyed by artifact type. Each artifact component reads only its
+     * own slice (`labels?.TABLE` or `labels?.CHART`); anything omitted falls back to the English
+     * default (per-key `Partial` merge against `DEFAULT_*_ARTIFACT_LABELS`).
+     */
+    labels?: Partial<ArtifactLabelsMap>;
+    /**
+     * Optional side-effect callbacks keyed by artifact type — for analytics / observability hooks
+     * (e.g. tracking a download event). Each artifact component reads only its own slice
+     * (`callbacks?.TABLE`, `callbacks?.CHART`). Callbacks fire alongside the default browser
+     * behaviour and do not replace it.
+     */
+    callbacks?: Partial<ArtifactCallbacksMap>;
+}
+/** Per-artifact-type service — registry entry that pairs a discriminator with its concrete component. */
+interface ArtifactService<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** Discriminator value this service handles. */
+    type: (typeof artifactTypes)[keyof typeof artifactTypes];
+    /** React component that renders an artifact of this type — composes ai-elements primitives
+     * (`Artifact`, `ArtifactHeader`, `ArtifactTitle`, `ArtifactActions`, `ArtifactContent`) directly. */
+    Component: ComponentType<ArtifactServiceProps<TArtifact>>;
+    /**
+     * Returns a plain-text / markdown string suitable for clipboard copy.
+     *
+     * Called by `ArtifactRefBlockService.toClipboardText` when the user copies a message that
+     * contains this artifact. Must be pure and synchronous.
+     */
+    toClipboardText: (artifact: TArtifact) => string;
+}
+
+export { type ArtifactDataRow as A, type BarChartConfig as B, type ChartArtifactLabels as C, DEFAULT_CHART_ARTIFACT_LABELS as D, type LineChartConfig as L, type PieChartConfig as P, type TableArtifactLabels as T, type ArtifactLabelsMap as a, type ArtifactRecord as b, type ArtifactService as c, type ArtifactServiceProps as d, type ArtifactType as e, type ChartArtifactRecord as f, type ChartConfig as g, type ChartStats as h, DEFAULT_TABLE_ARTIFACT_LABELS as i, type TableArtifactRecord as j, type TableColumn as k, type TableConfig as l, type TableRow as m, type TableStats as n, artifactTypes as o, type ArtifactCallbacksMap as p };

package/dist/types-C5bFH4v3.d.ts

@@ -0,0 +1,332 @@
+import { ComponentType } from 'react';
+import { C as ChartSeries } from './types-B2aYk82c.js';
+
+/**
+ * Shared artifact primitives — the discriminator constant and the cross-variant `ArtifactBase`
+ * shape that every concrete artifact record extends.
+ *
+ * Pulled into its own file so the per-type `types.ts` files (`table-artifact/types.ts`,
+ * `chart-artifact/types.ts`) and the union assembler (`artifacts/types.ts`) can all depend on
+ * one canonical source without creating a circular module graph between them.
+ */
+/**
+ * Artifact-type discriminator constants. Uppercase to match the server-side `artifactTypes`
+ * constant — io-server stores `artifact.type === "TABLE"` (aligned with the GraphQL enum).
+ */
+declare const artifactTypes: {
+    readonly TABLE: "TABLE";
+    readonly CHART: "CHART";
+};
+/** Discriminator for artifact types. Additive — new types extend this union. */
+type ArtifactType = (typeof artifactTypes)[keyof typeof artifactTypes];
+/** Common shape every artifact record carries. Discriminated by `type`. */
+interface ArtifactBase<TType extends ArtifactType, TConfig> {
+    /** Artifact-type discriminator. */
+    type: TType;
+    /** Human-readable label. Nullable when the artifact has no title. */
+    title: string | null;
+    /** Rendering config — shape varies per artifact type. */
+    config: TConfig;
+    /** Protected-asset metadata pointing to the underlying data payload. Null while the asset is unavailable. */
+    protectedAsset: {
+        /** Time-limited URL the renderer fetches the artifact's data from. */
+        presignedUrl: string;
+    } | null;
+}
+/**
+ * A row inside an artifact's parsed CSV. Every cell is the raw string from the CSV (or `null`
+ * for the empty string). Used by every artifact kind whose data wire is a CSV (`TABLE`, `CHART`).
+ * The renderer never coerces — type-aware formatting is a server concern (the CSV's contents
+ * are what the user sees).
+ */
+type ArtifactDataRow = Record<string, string | null>;
+
+/**
+ * Rendering config for a `BAR` chart. `xKey` selects the categorical axis; each series
+ * contributes one `<Bar>`. `stacked` collapses all series onto a single stack-id (so they sum
+ * vertically); when false / omitted bars are grouped side-by-side per x-tick.
+ */
+interface BarChartConfig extends ChartConfigBase {
+    variant: "BAR";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+    /** When true, stack all series on one stack-id. When false / omitted, group bars side-by-side. */
+    stacked?: boolean;
+}
+
+/**
+ * Rendering config for a `LINE` chart. `xKey` selects the categorical/temporal axis from the
+ * CSV; each series contributes one `<Line>` overlaid against that axis.
+ */
+interface LineChartConfig extends ChartConfigBase {
+    variant: "LINE";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+}
+
+/**
+ * Rendering config for a `PIE` chart. `categoryKey` names the slice; `valueKey` carries the
+ * slice's numeric magnitude. One row of CSV becomes one slice. The base's `series` array is
+ * always empty for pie — colors are resolved by row index from the palette.
+ */
+interface PieChartConfig extends ChartConfigBase {
+    variant: "PIE";
+    /** CSV column key used as the slice label. */
+    categoryKey: string;
+    /** CSV column key used as the slice numeric value. */
+    valueKey: string;
+}
+
+/**
+ * Discriminated union of all supported chart variant configs. Assembled here (not in the parent
+ * `types.ts`) because the union depends on each variant service file as its single source of
+ * truth for that variant's config type.
+ *
+ * Extension pattern: add a new variant by creating one `*-chart-variant-service.ts` file and
+ * extending this union + the `ChartVariantServices` map below. No edits to the dispatcher.
+ */
+type ChartConfig = LineChartConfig | BarChartConfig | PieChartConfig;
+
+/**
+ * Optional stats embedded in `ChartConfig` so clients can pre-render UI before fetching the
+ * actual CSV (e.g. a skeleton sized to the eventual row count). Mirrors `TableStats`.
+ */
+interface ChartStats {
+    /** Total number of rows in the materialised CSV. */
+    rowCount: number;
+}
+/**
+ * Cross-variant base for `ChartConfig`. Carries the fields every variant shares — series
+ * descriptors and optional stats. Per-variant config interfaces (in `chart-variant-services/`)
+ * extend this with their own required fields.
+ *
+ * Note: `series` is always present on the wire (matching the GraphQL `[ChartSeries!]!` shape)
+ * even for PIE — PIE just receives an empty array. Keeping it on the base mirrors the wire shape
+ * exactly and avoids TS object-literal freshness errors for callers that explicitly set
+ * `series: []` on a pie config.
+ */
+interface ChartConfigBase {
+    /** Series descriptors in render order. LINE/BAR consume these; PIE ignores in favour of `categoryKey`+`valueKey`. */
+    series: ChartSeries[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: ChartStats;
+}
+/** Concrete chart artifact record. */
+type ChartArtifactRecord = ArtifactBase<typeof artifactTypes.CHART, ChartConfig>;
+/**
+ * Localized labels for the `CHART` artifact's user-facing strings. Covers action buttons AND
+ * status messages — see `TableArtifactLabels` for the same shape philosophy. Extends as the
+ * chart artifact grows its action set (e.g. future `copyAsPng`); optional keys document
+ * anticipated additions without forcing every consumer to provide them today.
+ */
+interface ChartArtifactLabels {
+    /** Tooltip + aria-label on the Download CSV button in the chart artifact header. */
+    download: string;
+    /** Status message shown when no presigned URL is available or the chart config is malformed. */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime. */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched. */
+    loading: string;
+    /** Status message shown when the fetched CSV has zero data rows. */
+    empty: string;
+    /**
+     * Category labels treated as the "Others" bucket in pie charts (case-insensitive). Matching
+     * slices are pinned to the end of the sweep and rendered in neutral grey. The agent writes a
+     * translated bucket name in non-English UIs (e.g. "אחרים", "Otros") — consumer passes the
+     * localized list here so clay can detect the bucket regardless of language. English fallback
+     * is `["Others", "Other"]`. Pass `[]` to disable Others detection (every slice from the palette).
+     */
+    othersCategoryLabels: readonly string[];
+}
+/** English fallback for `ChartArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_CHART_ARTIFACT_LABELS: ChartArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the chart artifact. Mirrors
+ * `ChartArtifactLabels`'s shape philosophy: one entry per action this artifact exposes
+ * (download today; future "Copy as PNG" etc.). Every callback is optional — consumers wire
+ * only the actions they care about. The artifact passes its own `ChartArtifactRecord` as the
+ * only argument so consumers can derive analytics context (title, config.variant, etc.) without
+ * a per-block closure at every render site.
+ *
+ * The callback fires alongside the default browser behaviour (e.g. `onDownload` does not
+ * prevent the anchor's download navigation) — it's purely for analytics / observability hooks.
+ */
+interface ChartArtifactCallbacks {
+    /** Fires when the Download CSV button is clicked. Browser-native download still happens. */
+    onDownload?: (artifact: ChartArtifactRecord) => void;
+}
+
+/**
+ * A single column descriptor for a `TableArtifact`. Carries the ORDER and LABEL for the
+ * rendered table — `key` selects a column from the CSV header; `label` overrides the rendered
+ * header text. The CSV is always the source of truth for the data shape; clay never coerces,
+ * reformats, or interprets cell values.
+ */
+interface TableColumn {
+    /** Matches a header in the CSV. Required. Used to project + order the CSV's columns. */
+    key: string;
+    /** Human-readable header text. Required. */
+    label: string;
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every cell is rendered as
+     * the raw CSV string (or empty for null). Format conversion is a server concern; if a column
+     * needs to be "Yes/No" instead of "true/false", the server should emit it that way in the CSV.
+     * Kept in the interface so callers that pass `type` (e.g. io-client) don't get a type error.
+     */
+    type?: "string" | "number" | "date" | "boolean";
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every column is left-aligned
+     * by design. Kept in the interface for forward-compat; restore per-column alignment by editing
+     * `table-artifact-content.tsx` if a future use case justifies it.
+     */
+    align?: "left" | "center" | "right";
+}
+/**
+ * Optional stats embedded in `TableConfig` so clients can pre-render UI before fetching the
+ * actual data payload (e.g. N loading shimmers sized to the eventual row count).
+ *
+ * Backward-compat: optional everywhere — older artifacts persisted before this field shipped
+ * still validate. The renderer falls back to a single status-message line when `stats` is absent.
+ */
+interface TableStats {
+    /** Total number of rows in the materialised CSV. Lets the loading branch render shimmers. */
+    rowCount: number;
+}
+/** Rendering config for a table artifact, stored at `artifact.config` (JSONB on the server). */
+interface TableConfig {
+    /** Column descriptors in render order. */
+    columns: TableColumn[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: TableStats;
+}
+/** Alias retained for callers typed against the table-specific name. */
+type TableRow = ArtifactDataRow;
+/** Concrete table artifact record. */
+type TableArtifactRecord = ArtifactBase<typeof artifactTypes.TABLE, TableConfig>;
+/**
+ * Localized labels for the `TABLE` artifact's user-facing strings. Covers both action buttons
+ * (download today; future "Copy as CSV", etc.) AND status messages (loading / error / empty /
+ * unavailable). Consumer passes the bag from their i18n layer; clay falls back to English
+ * defaults when omitted (per-key Partial merge).
+ */
+interface TableArtifactLabels {
+    /** Tooltip + aria-label on the Download CSV button in the table artifact header. */
+    download: string;
+    /**
+     * Status message shown when no presigned URL is available (permanent server-side absence) or
+     * the artifact config is malformed. Both states reduce to "the underlying file isn't usable".
+     */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime (transient). */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched and `stats.rowCount` is not known. */
+    loading: string;
+    /** Empty-state row inside the table body when the fetched CSV has zero data rows. */
+    empty: string;
+}
+/** English fallback for `TableArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_TABLE_ARTIFACT_LABELS: TableArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the table artifact. Mirrors
+ * `ChartArtifactCallbacks` — see that interface for the shape philosophy. Every callback is
+ * optional; the artifact passes its own `TableArtifactRecord` as the only argument so consumers
+ * can derive analytics context without a per-block closure at every render site.
+ */
+interface TableArtifactCallbacks {
+    /** Fires when the Download CSV button is clicked. Browser-native download still happens. */
+    onDownload?: (artifact: TableArtifactRecord) => void;
+}
+
+/**
+ * Artifact-domain types — wire-protocol shapes shared between artifact components, block-services,
+ * and consumers. Splits responsibilities across three layers so each artifact kind owns its own
+ * `types.ts` and this file assembles the cross-type union + service contract:
+ *
+ * 1. **`artifact-base.ts`** — discriminator (`artifactTypes`), `ArtifactBase<TType, TConfig>`, and
+ *    `ArtifactDataRow`. Pulled out so each per-type `types.ts` and this assembler can depend on
+ *    one canonical base without a circular module graph.
+ * 2. **`<type>-artifact/types.ts`** — per-artifact-type records, configs, labels, and defaults.
+ *    Variant-specific types (e.g. `LineChartConfig`) live in even deeper per-variant service files.
+ * 3. **This file** — the cross-type `ArtifactRecord` union, the labels map keyed by artifact type,
+ *    and the `ArtifactService<TArtifact, TLabels>` registry contract used by the dispatcher.
+ *
+ * Mirrored from the agent / io-server contract — see the `chat-typed-content-blocks-and-artifacts`
+ * plan, §6.4 (table contract).
+ */
+
+/**
+ * Per-artifact-type labels map. Lets a consumer pass labels for every artifact kind in a single
+ * bag at the block layer (`<ArtifactRefBlock>` payload); the dispatcher routes the matching slice
+ * (`labels[artifact.type]`) to the concrete artifact component.
+ *
+ * Extension pattern: add a new field here when adding a new artifact type. Keep the field
+ * optional so older consumers don't break on upgrade.
+ */
+interface ArtifactLabelsMap {
+    TABLE: TableArtifactLabels;
+    CHART: ChartArtifactLabels;
+}
+/**
+ * Per-artifact-type callbacks map. Sibling to `ArtifactLabelsMap` — consumer passes a single
+ * bag at the block layer covering every artifact type's action callbacks (today: `onDownload`).
+ * Used for analytics / observability hooks — every callback is optional and fires alongside
+ * the default browser behaviour (it does NOT replace it).
+ *
+ * Each callback receives its artifact-type's `ArtifactBase`-derived record so consumers can
+ * derive analytics context (title, config, etc.) from one wiring at the chat-surface level
+ * instead of per-block closures.
+ */
+interface ArtifactCallbacksMap {
+    TABLE: TableArtifactCallbacks;
+    CHART: ChartArtifactCallbacks;
+}
+/**
+ * Discriminated union of all supported artifacts. Extension pattern: add the new branch here AND
+ * in the `ArtifactServices` map (single source of truth for the type→component mapping). Older
+ * clay versions that don't know about a new type silently render nothing — see `ArtifactRefBlock`
+ * guard.
+ */
+type ArtifactRecord = TableArtifactRecord | ChartArtifactRecord;
+/**
+ * Props every concrete artifact component receives from the dispatcher.
+ *
+ * `labels` is the FULL `ArtifactLabelsMap` bag — every artifact component receives the same
+ * shape and reads its own slice internally (`labels?.TABLE`, `labels?.CHART`). One uniform prop
+ * type across all artifact components keeps the block-layer dispatcher a generic forward — no
+ * per-type branch, no cast, no map-key extraction at the seam.
+ */
+interface ArtifactServiceProps<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** The artifact metadata (config + presigned URL). */
+    artifact: TArtifact;
+    /**
+     * Optional localized labels keyed by artifact type. Each artifact component reads only its
+     * own slice (`labels?.TABLE` or `labels?.CHART`); anything omitted falls back to the English
+     * default (per-key `Partial` merge against `DEFAULT_*_ARTIFACT_LABELS`).
+     */
+    labels?: Partial<ArtifactLabelsMap>;
+    /**
+     * Optional side-effect callbacks keyed by artifact type — for analytics / observability hooks
+     * (e.g. tracking a download event). Each artifact component reads only its own slice
+     * (`callbacks?.TABLE`, `callbacks?.CHART`). Callbacks fire alongside the default browser
+     * behaviour and do not replace it.
+     */
+    callbacks?: Partial<ArtifactCallbacksMap>;
+}
+/** Per-artifact-type service — registry entry that pairs a discriminator with its concrete component. */
+interface ArtifactService<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** Discriminator value this service handles. */
+    type: (typeof artifactTypes)[keyof typeof artifactTypes];
+    /** React component that renders an artifact of this type — composes ai-elements primitives
+     * (`Artifact`, `ArtifactHeader`, `ArtifactTitle`, `ArtifactActions`, `ArtifactContent`) directly. */
+    Component: ComponentType<ArtifactServiceProps<TArtifact>>;
+    /**
+     * Returns a plain-text / markdown string suitable for clipboard copy.
+     *
+     * Called by `ArtifactRefBlockService.toClipboardText` when the user copies a message that
+     * contains this artifact. Must be pure and synchronous.
+     */
+    toClipboardText: (artifact: TArtifact) => string;
+}
+
+export { type ArtifactDataRow as A, type BarChartConfig as B, type ChartArtifactLabels as C, DEFAULT_CHART_ARTIFACT_LABELS as D, type LineChartConfig as L, type PieChartConfig as P, type TableArtifactLabels as T, type ArtifactLabelsMap as a, type ArtifactRecord as b, type ArtifactService as c, type ArtifactServiceProps as d, type ArtifactType as e, type ChartArtifactRecord as f, type ChartConfig as g, type ChartStats as h, DEFAULT_TABLE_ARTIFACT_LABELS as i, type TableArtifactRecord as j, type TableColumn as k, type TableConfig as l, type TableRow as m, type TableStats as n, artifactTypes as o, type ArtifactCallbacksMap as p };