themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/actions/hooks.d.ts

@@ -1,8 +1,30 @@
 import { ActionDefinition, ActionRegistrationOptions, ActionStoreSnapshot, ActionSurfaceOptions, ResolvedAction, UseLocalActionOptions, UseActionOptions } from './actions.types.js';
+/** The nearest `ActionScope`'s id, or the global scope. For a surface resolving its own actions. */
 export declare function useActionScope(): string;
+/**
+ * Subscribes to the whole store. Prefer a narrower hook — this re-renders on any registry or
+ * run change.
+ */
 export declare function useActionSnapshot(): ActionStoreSnapshot;
+/**
+ * Registers `actions` for as long as the calling component is mounted, under `options.scope` or
+ * else the nearest `ActionScope`'s.
+ */
 export declare function useRegisterActions<TPayload = unknown, TValues = unknown, TResult = unknown>(actions: readonly ActionDefinition<TPayload, TValues, TResult>[], options?: ActionRegistrationOptions): void;
+/** The actions for one surface, already filtered by visibility, permission, and guards. */
 export declare function useActionSurface<TPayload = unknown, TValues = unknown, TResult = unknown>(options: ActionSurfaceOptions<TPayload>): ResolvedAction<TPayload, TValues, TResult>[];
+/**
+ * One action by id, when a surface is not the right shape. `null` when none is registered in
+ * scope or it is not visible.
+ */
 export declare function useAction<TPayload = unknown, TValues = unknown, TResult = unknown>(actionId: string, options?: UseActionOptions<TPayload>): ResolvedAction<TPayload, TValues, TResult> | null;
+/**
+ * One action registered for the lifetime of the component that declares it, for a definition no
+ * other surface needs.
+ */
 export declare function useLocalAction<TPayload = unknown, TValues = unknown, TResult = unknown>(definition: ActionDefinition<TPayload, TValues, TResult>, options?: UseLocalActionOptions<TPayload>): ResolvedAction<TPayload, TValues, TResult> | null;
+/**
+ * Whichever action is currently open, or `null`. The outlet reads this; a bespoke outlet would
+ * too.
+ */
 export declare function useActiveAction<TPayload = unknown, TValues = unknown, TResult = unknown>(): ResolvedAction<TPayload, TValues, TResult> | null;

package/dist/components/features/activities/activities-feed.d.ts

@@ -1,2 +1,3 @@
 import { ActivityFeedProps } from './activities.types.js';
+/** The timeline of events, grouped by date on one rail. */
 export declare function ActivityFeed<TData = unknown>({ activities, density, itemSpacing, groupByDate, expandedByDefault, detailsCollapsible, defaultExpandedIds, expandedIds, onExpandedIdsChange, currentUserId, loading, error, onRetry, eventConfig, strings, slots, rowClassNames, className, locale, formatRelativeTime, formatAbsoluteTime, formatDateGroupLabel, getSourceLabel, actionsForActivity, onActivityClick, onActorClick, onResourceClick, onAction, onActivityExpandedChange, resources, onResourcesChange, }: ActivityFeedProps<TData>): import("react").JSX.Element;

package/dist/components/features/activities/activities.types.d.ts

@@ -93,9 +93,16 @@ export interface ActivityItem<TData = unknown> {
     /** Which system it came from. Drives the source badge. */
     source?: string;
     actor?: ActivityActor;
-    /** Preferred over `headline`. */
+    /**
+     * The headline as typed parts: actor, field, value, status, resource, text. Preferred over
+     * `headline`: “Maria changed Status from Draft to Published” is a person, a field, and two
+     * values, and a template string cannot express that.
+     */
     segments?: readonly ActivityHeadlineSegment[];
-    /** The fallback when there are no segments. */
+    /**
+     * The fallback when there are no segments. The actor's name is split out of it, so a feed
+     * migrated from a system that only stored sentences still gets a clickable actor.
+     */
     headline?: string;
     description?: ReactNode;
     createdAt?: string;
@@ -188,31 +195,68 @@ export interface ActivityFeedCallbacks<TData = unknown> {
     onActivityExpandedChange?: (activity: ActivityItem<TData>, expanded: boolean) => void;
 }
 export interface ActivityResourcesProps {
-    /** The registry's seed. Re-seeded whenever this reference changes. */
+    /**
+     * The registry rows look their resources up in, by key. A hundred rows referencing
+     * `order:1234` follow when it is renamed, and none of them stores the name. This is the
+     * registry's seed, re-seeded whenever this reference changes.
+     */
     resources?: Readonly<Record<string, ActivityResourceConfig>>;
     /** Fires on every mutation, so the registry can be persisted. */
     onResourcesChange?: (registry: Readonly<Record<string, ActivityResourceConfig>>) => void;
 }
 export interface ActivityFeedProps<TData = unknown> extends ActivityFeedAccessors<TData>, ActivityFeedCallbacks<TData>, ActivityResourcesProps {
+    /**
+     * In display order. Grouped by date as they come, not bucketed — bucketing would silently
+     * reorder a feed sorted by something other than date.
+     */
     activities?: ReadonlyArray<ActivityItem<TData>>;
+    /** How much of a row is drawn. `rich` adds metadata, changes, resources, and actions. */
     density?: ActivityDensity;
+    /** The rhythm between rows, independent of how much each row draws. */
     itemSpacing?: ActivityItemSpacing;
     groupByDate?: boolean;
     expandedByDefault?: boolean;
     detailsCollapsible?: boolean;
+    /** Uncontrolled: the rows expanded at first. */
     defaultExpandedIds?: ReadonlyArray<string>;
     /** Controlled. Supplying it hands expansion to the caller. */
     expandedIds?: ReadonlyArray<string>;
+    /**
+     * Always gets the full id list, controlled or not, because a consumer persisting the set
+     * needs the set.
+     */
     onExpandedIdsChange?: (ids: string[]) => void;
-    /** Turns this person's own name into "You". */
+    /**
+     * Turns this person's own name into “You”. Both ids must be defined for the match, or a
+     * feed with no ids anywhere would call every actor “You”.
+     */
     currentUserId?: string;
+    /**
+     * Shows initial loading for an empty feed, or an update status above existing rows. Keeps
+     * loaded details and composer drafts mounted.
+     */
     loading?: boolean;
-    /** A failed load or refresh. Existing activity stays visible. */
+    /**
+     * Failure feedback for a load or refresh, with an optional retry action through `onRetry`.
+     * A failed refresh keeps existing history visible; the consumer owns the request and its
+     * loading state.
+     */
     error?: ReactNode;
+    /** The retry action offered with `error`. */
     onRetry?: () => void;
-    /** Merged over the kit's defaults, so one event can be redefined without the rest. */
+    /**
+     * Merged over the kit's defaults, so one event can be redefined without restating the rest.
+     * Every `status_changed` in an application should look the same; deciding per call site
+     * guarantees it eventually does not.
+     */
     eventConfig?: ActivityEventConfigMap;
     strings?: Partial<ActivitiesStrings>;
+    /**
+     * `renderRow`, `renderHeadline`, `renderMarker` and `renderDetails` replace a row's parts;
+     * `renderDateLabel`, `empty`, `loading`, `header` and `footer` the feed's own regions.
+     * `renderRow` returning `undefined` hands the row back to the feed — which is how
+     * ActivityLog replaces only its comment rows.
+     */
     slots?: ActivityFeedSlots<TData>;
     rowClassNames?: ActivityRowClassNames<TData>;
     className?: string;
@@ -309,11 +353,23 @@ export interface ActivityLogClassNames<TResource extends string = string> {
     eventDetails?: ActivityLogClassNameValue<TResource>;
 }
 export interface ActivityLogProps<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors {
+    /**
+     * A union of comment entries and activity entries, sorted here by `order`. An entry with no
+     * timestamp sorts to the far end rather than shuffling.
+     */
     entries: ReadonlyArray<ActivityLogEntry<TUser, TMeta, TResource>>;
-    /** Keep loaded entries and the composer mounted during a refresh. */
+    /**
+     * Shows initial loading for an empty log, or an update status above existing entries. Keeps
+     * loaded entries and the composer mounted during a refresh.
+     */
     loading?: boolean;
-    /** Fetch failure feedback, independent of comment submission errors. */
+    /**
+     * Fetch failure feedback, independent of comment submission errors, with an optional retry
+     * action through `onRetry`. A failed refresh keeps existing history visible; the consumer
+     * owns the request and its loading state.
+     */
     error?: ReactNode;
+    /** The retry action offered with `error`. */
     onRetry?: () => void;
     /** `desc` puts the newest first, which is what a log usually wants. */
     order?: "asc" | "desc";
@@ -338,7 +394,12 @@ export interface ActivityLogProps<TUser extends CommentUser = CommentUser, TMeta
     onEventExpandedChange?: (entry: ActivityLogActivityEntry<TResource>, expanded: boolean) => void;
     onEventAction?: (actionId: string, entry: ActivityLogActivityEntry<TResource>) => void;
     classNames?: ActivityLogClassNames<TResource>;
-    /** Omit to render the log read-only. */
+    /**
+     * The comment composer: `enabled`, the `context` it posts against, `onSubmit`, and its
+     * `position`. Omit to render the log read-only. Its `inlineSubmit` defaults to `false` here,
+     * unlike a standalone composer: a log's submit sits above a wall of history, and one hidden
+     * on the toolbar reads as formatting.
+     */
     composer?: ActivityLogComposerConfig<TResource>;
     bare?: boolean;
     title?: ReactNode;

package/dist/components/features/activities/activity-headline.d.ts

@@ -8,4 +8,9 @@ export interface ActivityHeadlineProps<TData = unknown> {
     onResourceClick?: (resource: ActivityResourceRef, config: ActivityResourceConfig | undefined, activity: ActivityItem<TData>) => void;
     getResourceConfig?: (ref: ActivityResourceRef) => ActivityResourceConfig | undefined;
 }
+/**
+ * The sentence, assembled from typed segments rather than interpolated. The fallback is the
+ * point: an event whose actor or subject is missing still reads as a sentence instead of
+ * rendering “undefined updated”.
+ */
 export declare function ActivityHeadline<TData = unknown>(props: ActivityHeadlineProps<TData>): import("react").JSX.Element;

package/dist/components/features/activities/activity-log.d.ts

@@ -1,3 +1,7 @@
 import { CommentUser } from '../comments/index.js';
 import { ActivityLogProps } from './activities.types.js';
+/**
+ * Events and comments on one rail, built on ActivityFeed: a comment is an activity whose row is
+ * a `CommentItem`, so both share markers, date groups and ordering.
+ */
 export declare function ActivityLog<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>({ entries, loading, error, onRetry, order, itemSpacing, resources, onResourceSearch, canModerate, onCommentDelete, onCommentReact, onCommentReply, onCommentPinToggle, strings, activityStrings, renderers, renderEventDetails, eventDetailsCollapsible, defaultExpandedIds, expandedIds, onExpandedIdsChange, onEventExpandedChange, onEventAction, classNames, composer, bare, title, getMediaUrl, getMediaName, getStatusLabel, className, }: ActivityLogProps<TUser, TMeta, TResource>): import("react").JSX.Element;

package/dist/components/features/activities/activity-parts.d.ts

@@ -8,12 +8,24 @@ export interface ActivityMarkerProps {
     last: boolean;
     className?: string;
 }
+/**
+ * The dot on the rail. It knows whether it is last, because the connector below it is what
+ * tells a reader the run has ended.
+ */
 export declare function ActivityMarker({ icon, tone, density, last, className }: ActivityMarkerProps): import("react").JSX.Element;
+/**
+ * The date heading a group of rows on the rail. An empty label, from an ungrouped feed,
+ * renders nothing.
+ */
 export declare function ActivityDateLabel({ label, first, className, }: {
     label: string;
     first: boolean;
     className?: string;
 }): import("react").JSX.Element | null;
+/**
+ * The before-and-after of an edit. Changes render as pairs rather than prose so a long diff
+ * stays scannable.
+ */
 export declare function ActivityChanges({ changes, bare, className, }: {
     changes: readonly ActivityChange[];
     /** Drops the frame, for use inside a panel that already has one. */
@@ -29,13 +41,22 @@ export interface ActivityResourceTagProps {
     /** Compact references inside a headline omit their secondary facts. */
     showDetails?: boolean;
 }
+/**
+ * The chip naming what was edited, or whatever else an event acted on. Its label is the
+ * registry entry's (`config`), then `fallbackText`, then the ref's own, then the raw key.
+ */
 export declare function ActivityResourceTag({ resource, config, fallbackText, onClick, showDetails, }: ActivityResourceTagProps): import("react").JSX.Element;
+/** A row's overflow menu: its actions, bound to the activity. */
 export declare function ActivityActionsMenu<TData = unknown>({ activity, actions, onAction, label, }: {
     activity: ActivityItem<TData>;
     actions: readonly ActivityAction<TData>[];
     onAction?: (actionId: string, activity: ActivityItem<TData>) => void;
     label: string;
 }): import("react").JSX.Element | null;
+/**
+ * The control that opens a row's detail. A real button rather than a clickable row, so a
+ * keyboard reader can reach it without traversing the entry.
+ */
 export declare function ActivityExpandToggle({ expanded, showLabel, hideLabel, onToggle, controls, }: {
     expanded: boolean;
     showLabel: string;
@@ -50,5 +71,8 @@ export interface ActivityEmptyStateProps {
     action?: ReactNode;
     className?: string;
 }
-/** The empty feed, with a glyph in the marker column so it reads as empty rather than broken. */
+/**
+ * The state with no events: the empty feed, with a glyph in the marker column so it reads as
+ * empty rather than broken.
+ */
 export declare function ActivityEmptyState({ title, hint, action, className, }: ActivityEmptyStateProps): import("react").JSX.Element;

package/dist/components/features/activities/activity-row.d.ts

@@ -40,4 +40,9 @@ export interface ActivityRowProps<TData = unknown> {
     contentClassName?: string;
     detailsClassName?: string;
 }
+/**
+ * One entry on the rail. Density changes the marker size and the row rhythm together —
+ * changing one without the other is what makes a compact feed look mis-aligned rather than
+ * dense.
+ */
 export declare function ActivityRow<TData = unknown>({ activity, density, itemSpacing, eventConfig, tone, last, expanded, onExpandedChange, detailsCollapsible, detailLabels, relativeTime, absoluteTime, sourceLabel, youLabel, showChangesLabel, hideChangesLabel, moreLabel, actionsLabel, currentUserId, actions, onActivityClick, onActorClick, onResourceClick, onAction, getResourceConfig, headlineOverride, markerOverride, customDetails, rowClassName, markerClassName, contentClassName, detailsClassName, }: ActivityRowProps<TData>): import("react").JSX.Element;

package/dist/components/features/activities/use-activity-resources.d.ts

@@ -15,4 +15,9 @@ export interface UseActivityResourcesReturn {
     /** Back to the `resources` prop as it was last seen. */
     reset: () => void;
 }
+/**
+ * Resolves the resources an event refers to, from a registry keyed like `order:1234`, so a feed
+ * can render a chip per subject without every consumer re-implementing the lookup and its
+ * cache. Every mutation emits the whole registry through `onResourcesChange` for persistence.
+ */
 export declare function useActivityResources({ resources, onResourcesChange, }?: UseActivityResourcesOptions): UseActivityResourcesReturn;

package/dist/components/features/ai-chat/ai-chat-parts.d.ts

@@ -7,6 +7,10 @@ export interface AiChatAttachmentsStripProps {
     onOpen?: (attachment: AiChatAttachment) => void;
     className?: string;
 }
+/**
+ * The files attached to the turn being written, as one of the strips above the composer's
+ * field; a sent turn's attachments render as one too.
+ */
 export declare function AiChatAttachmentsStrip({ attachments, onRemove, onOpen, className, }: AiChatAttachmentsStripProps): import("react").JSX.Element | null;
 export interface AiChatMessageProps {
     message: AiChatMessageData;
@@ -32,6 +36,10 @@ export interface AiChatConversationProps {
     className?: string;
     strings?: Partial<AiChatConversationStrings>;
 }
+/**
+ * The transcript. Exported, like the composer and the empty state, because a consumer building
+ * a different chat layout against the same data should get the parts without taking the shell.
+ */
 export declare function AiChatConversation({ messages, renderMessage, intro, footer, empty, disableAutoScroll, className, strings, }: AiChatConversationProps): import("react").JSX.Element;
 export interface AiChatEmptyStateProps {
     title?: ReactNode;
@@ -41,6 +49,11 @@ export interface AiChatEmptyStateProps {
     below?: ReactNode;
     className?: string;
 }
+/**
+ * The state before the first turn. Exported, like the transcript and the composer, because a
+ * consumer building a different chat layout against the same data should get the parts
+ * without taking the shell.
+ */
 export declare function AiChatEmptyState({ title, description, icon, below, className, }: AiChatEmptyStateProps): import("react").JSX.Element;
 export interface AiChatQueueProps {
     items: readonly AiChatQueueItem[];
@@ -49,6 +62,7 @@ export interface AiChatQueueProps {
     className?: string;
     strings?: Partial<AiChatQueueStrings>;
 }
+/** The strip above the composer holding the messages waiting to send. */
 export declare function AiChatQueue({ items, hideHeader, onCancel, className, strings, }: AiChatQueueProps): import("react").JSX.Element | null;
 export interface AiChatSuggestionsRowProps<TData = unknown> {
     suggestions: readonly AiChatSuggestion<TData>[];
@@ -57,6 +71,7 @@ export interface AiChatSuggestionsRowProps<TData = unknown> {
     className?: string;
     strings?: Partial<AiChatSuggestionsStrings>;
 }
+/** The strip above the composer offering prompt suggestions. */
 export declare function AiChatSuggestionsRow<TData = unknown>({ suggestions, onPick, hideHeader, className, strings, }: AiChatSuggestionsRowProps<TData>): import("react").JSX.Element | null;
 export interface AiChatPromptInputProps {
     value: string;
@@ -84,4 +99,8 @@ export interface AiChatPromptInputProps {
     className?: string;
     strings?: Partial<AiChatPromptInputStrings>;
 }
+/**
+ * The composer. Exported, like the transcript and the empty state, because a consumer building
+ * a different chat layout against the same data should get the parts without taking the shell.
+ */
 export declare function AiChatPromptInput({ value, onValueChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, leadingActions, trailingActions, hideHint, minRows, maxRows, autoFocus, submitKeyLabel, className, strings, }: AiChatPromptInputProps): import("react").JSX.Element;

package/dist/components/features/ai-chat/ai-chat.d.ts

@@ -2,19 +2,41 @@ import { ReactNode } from 'react';
 import { AiChatStrings } from './ai-chat.strings.js';
 import { AiChatAgent, AiChatAttachment, AiChatMessage as AiChatMessageData, AiChatQueueItem, AiChatSlots, AiChatSubmitValues, AiChatSuggestion } from './ai-chat.types.js';
 export interface AiChatProps<TSuggestionData = unknown> {
-    /** Oldest first. */
+    /**
+     * Oldest first. Each carries `parts`, which is where the mix lives — text, reasoning, a chain
+     * of thought, a tool call, code, sources, a task, an artifact, a confirmation, attachments,
+     * or custom.
+     */
     messages: readonly AiChatMessageData[];
+    /**
+     * The composer's text. Controlled: the composer holds no draft of its own, so clearing it
+     * after a submit is the consumer's, which is also where the failed-send-restores-the-text
+     * case lives.
+     */
     inputValue: string;
+    /** Receives every edit to `inputValue`. */
     onInputChange: (value: string) => void;
+    /**
+     * Fires on Enter or the send button. An attachment on its own is a valid message — “here,
+     * look at this” needs no words.
+     */
     onSubmit?: (values: AiChatSubmitValues) => void;
+    /** What the stop control calls while `streaming`. */
     onStop?: () => void;
+    /**
+     * Flips submit to stop. Separate from `disabled`, because a streaming chat is still readable
+     * and still cancellable; a disabled one is neither.
+     */
     streaming?: boolean;
     disabled?: boolean;
     attachments?: readonly AiChatAttachment[];
     onRemoveAttachment?: (id: string) => void;
     onAttach?: () => void;
     showAttach?: boolean;
-    /** `null` hides the header strip. */
+    /**
+     * Name, icon, subtitle, tone and status for the header strip. `null` hides the strip
+     * entirely.
+     */
     agent?: AiChatAgent | null;
     headerActions?: ReactNode;
     queue?: readonly AiChatQueueItem[];
@@ -25,8 +47,18 @@ export interface AiChatProps<TSuggestionData = unknown> {
     onMessageRegenerate?: (message: AiChatMessageData) => void;
     onAttachmentOpen?: (messageId: string, attachmentId: string) => void;
     disableAutoScroll?: boolean;
+    /**
+     * Seven regions replaced outright — `header`, `intro`, `belowMessages`, `empty`, `queue`,
+     * `suggestions`, `input` — plus `renderMessage` for a turn. This is the seam that keeps a
+     * prop per idea out of the API.
+     */
     slots?: AiChatSlots;
     strings?: Partial<AiChatStrings>;
     className?: string;
 }
+/**
+ * The agent header, the transcript, and the composer, wired together. No fetcher, router or
+ * streaming client: messages, input, queue and attachments are props, and submitting is a
+ * callback.
+ */
 export declare function AiChat<TSuggestionData = unknown>({ messages, inputValue, onInputChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, agent, headerActions, queue, onCancelQueueItem, suggestions, onPickSuggestion, onMessageCopy, onMessageRegenerate, onAttachmentOpen, disableAutoScroll, slots, strings, className, }: AiChatProps<TSuggestionData>): import("react").JSX.Element;

package/dist/components/features/ai-chat/ai-chat.types.d.ts

@@ -32,7 +32,10 @@ export interface AiReasoningProps {
     children?: ReactNode;
     streaming?: boolean;
     durationSeconds?: number;
-    /** Opens while streaming and closes when it stops. */
+    /**
+     * Opens on the edge where streaming starts and closes on the edge where it stops, so a reader
+     * who opened or closed it in between is not fought.
+     */
     expandWhileStreaming?: boolean;
     defaultExpanded?: boolean;
     expanded?: boolean;
@@ -61,6 +64,7 @@ export interface AiChainOfThoughtProps {
 export type AiToolCallStatus = "pending" | "running" | "success" | "error";
 export interface AiToolCallProps {
     name: string;
+    /** Where the call is, as the header's badge: its tone, glyph and label. */
     status: AiToolCallStatus;
     icon?: LucideIcon;
     args?: ReactNode;
@@ -131,7 +135,10 @@ export interface AiCodeBlockProps {
     language?: string;
     filename?: string;
     showLineNumbers?: boolean;
-    /** 1-indexed. */
+    /**
+     * 1-indexed. The gutter and the line share a grid row, so a highlight covers both rather than
+     * stopping at the number.
+     */
     highlightLines?: readonly number[];
     hideHeader?: boolean;
     maxHeight?: number | string;
@@ -179,7 +186,10 @@ export interface AiSourcesProps {
     expanded?: boolean;
     defaultExpanded?: boolean;
     onExpandedChange?: (expanded: boolean) => void;
-    /** Preferred over `url`, so a source can route inside the app. */
+    /**
+     * Wins over `url`, so an app that routes internally is not forced to hand the reader a full
+     * page load to reach its own document.
+     */
     onSelect?: (source: AiSourceItem, index: number) => void;
     className?: string;
     strings?: Partial<Strings.AiSourcesStrings>;

package/dist/components/features/ai-chat/ai-content-surfaces.d.ts

@@ -1,5 +1,16 @@
 import { AiArtifactProps, AiAttachmentProps, AiCodeBlockProps, AiSourcesProps } from './ai-chat.types.js';
+/**
+ * Code as produced. There is deliberately no syntax highlighting — that means shipping a
+ * grammar per language, and a chat can be handed any of them. Bring a highlighter and pass its
+ * output as `AiArtifact` children, or replace the code block.
+ */
 export declare function AiCodeBlock({ code, language, filename, showLineNumbers, highlightLines, hideHeader, maxHeight, headerActions, onCopy, className, strings, }: AiCodeBlockProps): import("react").JSX.Element;
+/** The frame around a produced artifact: its title, its actions, and what it holds. */
 export declare function AiArtifact({ title, subtitle, icon, copyText, children, collapsed, onOpen, actions, onDownload, className, strings, }: AiArtifactProps): import("react").JSX.Element;
+/**
+ * What the model read. Sources are listed rather than footnoted, because a reader checking an
+ * answer is looking for the list, not for a marker in the prose.
+ */
 export declare function AiSources({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, className, strings, }: AiSourcesProps): import("react").JSX.Element;
+/** One file a turn carried, as a chip or a thumbnail tile, with its upload progress. */
 export declare function AiAttachment({ name, meta, kind, icon, thumbnailUrl, progress, errored, onOpen, onRemove, className, strings, }: AiAttachmentProps): import("react").JSX.Element;

package/dist/components/features/ai-chat/ai-message-surfaces.d.ts

@@ -1,5 +1,13 @@
 import { AiChainOfThoughtProps, AiMessageBubbleProps, AiReasoningProps, AiShimmerProps } from './ai-chat.types.js';
+/**
+ * “Thinking…” as a swept highlight rather than a spinner. A spinner says something is
+ * happening; a sweep says something is being produced, which is the difference the reader is
+ * waiting on. It paints through `background-clip`, so its colour is transparent by design — a
+ * contrast probe reading `color` alone will call it a 1:1 failure.
+ */
 export declare function AiShimmer({ children, paused, duration, className, }: AiShimmerProps): import("react").JSX.Element;
 export declare function AiMessageBubble({ role, avatar, avatarLabel, authorName, timestamp, children, plainText, loading, onCopy, onRegenerate, className, strings, }: AiMessageBubbleProps): import("react").JSX.Element;
+/** The reasoning disclosure: the model's trace, and how long it thought. */
 export declare function AiReasoning({ children, streaming, durationSeconds, expandWhileStreaming, defaultExpanded, expanded: expandedProp, onExpandedChange, className, strings, }: AiReasoningProps): import("react").JSX.Element;
+/** The step timeline of an agent's plan. */
 export declare function AiChainOfThought({ steps, hideHeader, streaming, className, strings, }: AiChainOfThoughtProps): import("react").JSX.Element;

package/dist/components/features/ai-chat/ai-work-surfaces.d.ts

@@ -1,5 +1,19 @@
 import { AiAgentProps, AiConfirmationProps, AiTaskProps, AiToolCallProps } from './ai-chat.types.js';
+/**
+ * One tool call: its name, status, arguments and result. With neither args nor result (nor an
+ * error) the header is a plain row, not a disclosure — a control that opens an empty panel is
+ * worse than no control.
+ */
 export declare function AiToolCall({ name, status, icon, args, result, error, durationMs, expanded: expandedProp, defaultExpanded, onExpandedChange, className, strings, }: AiToolCallProps): import("react").JSX.Element;
+/**
+ * One task of an agent's plan, with its status and its sub-tasks. A task reports what is being
+ * done, not merely that something is.
+ */
 export declare function AiTask({ task, density, indent, className, strings, }: AiTaskProps): import("react").JSX.Element;
+/** The identity strip that says which agent is answering. */
 export declare function AiAgent({ name, icon, avatar, subtitle, tone, status, variant, trailing, className, strings, }: AiAgentProps): import("react").JSX.Element;
+/**
+ * The approval prompt that stops an agent before it acts. A confirmation is a decision surface:
+ * it does not auto-dismiss.
+ */
 export declare function AiConfirmation({ title, description, icon, tone, status, onApprove, onReject, approveLabel, rejectLabel, details, className, strings, }: AiConfirmationProps): import("react").JSX.Element;

package/dist/components/features/ai-chat/use-ai-chat-scroll.d.ts

@@ -14,4 +14,10 @@ export interface UseAiChatScrollResult {
     isAtBottom: boolean;
     scrollToBottom: (behavior?: ScrollBehavior) => void;
 }
+/**
+ * The stick-to-bottom behaviour without the layout, for a consumer building their own
+ * transcript: new content scrolls it only while the reader is at the bottom. Returns the
+ * `containerRef` for the scroll viewport, the `endRef` sentinel for the end of the content,
+ * `isAtBottom`, and `scrollToBottom`.
+ */
 export declare function useAiChatScroll({ threshold, dependency, disableAutoScroll, }?: UseAiChatScrollOptions): UseAiChatScrollResult;

package/dist/components/features/async-preview/async-preview-bundles.d.ts

@@ -9,7 +9,10 @@ export declare const AsyncPreview: {
     Error: typeof AsyncPreviewError;
     Empty: typeof AsyncPreviewEmpty;
 };
-/** Binds the generics once, for a record shape used in more than one place. */
+/**
+ * Binds the generics once, for a record shape used in more than one place, instead of restating
+ * them at every part.
+ */
 export declare function createAsyncPreview<TData, TContext = unknown, TType extends string = string>(): {
     Root: ({ children, strings, ...options }: import('./async-preview.types.js').AsyncPreviewRootProps<TData, TContext, TType>) => import("react").JSX.Element;
     Trigger: ({ children, prefetchOnHover, className, }: import('./async-preview.types.js').AsyncPreviewTriggerProps<TData, TContext, TType>) => import("react").JSX.Element;

package/dist/components/features/async-preview/async-preview-context.d.ts

@@ -7,4 +7,8 @@ export interface PreviewContextValue {
     triggerId: string;
 }
 export declare const PreviewContext: import('react').Context<PreviewContextValue | null>;
+/**
+ * The current state and data, for a part rendered outside the provided ones — a footer that
+ * counts results, a header that names what is loading.
+ */
 export declare function useAsyncPreviewContext<TData, TContext = unknown, TType extends string = string>(): AsyncPreviewState<TData, TContext, TType>;

package/dist/components/features/async-preview/async-preview.d.ts

@@ -1,11 +1,34 @@
 import { AsyncPreviewBodyProps, AsyncPreviewContentProps, AsyncPreviewRootProps, AsyncPreviewSlotProps, AsyncPreviewStateProps, AsyncPreviewTriggerProps } from './async-preview.types.js';
+/**
+ * The root of the compound over `useAsyncPreview`: it runs the fetch, the cache and the open
+ * state for the parts inside it. Compound rather than one `renderPreview` prop because the four
+ * states want four different shapes, and a single render prop makes the caller branch on all
+ * of them every time.
+ */
 export declare function AsyncPreviewRoot<TData, TContext = unknown, TType extends string = string>({ children, strings, ...options }: AsyncPreviewRootProps<TData, TContext, TType>): import("react").JSX.Element;
+/** The element the preview hangs off: it opens the popover, and hovering it prefetches. */
 export declare function AsyncPreviewTrigger<TData, TContext = unknown, TType extends string = string>({ children, prefetchOnHover, className, }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
+/** The popover the states render in, labelled by its trigger. */
 export declare function AsyncPreviewContent({ className, children, width, side, align, }: AsyncPreviewContentProps): import("react").JSX.Element;
-/** The whole state, for a preview that renders its own four cases. */
+/**
+ * The whole state, for a preview that renders its own four cases: the escape hatch for a caller
+ * who genuinely wants to branch themselves.
+ */
 export declare function AsyncPreviewState<TData, TContext = unknown, TType extends string = string>({ children, }: AsyncPreviewStateProps<TData, TContext, TType>): import("react").JSX.Element;
 /** The success case, with the data narrowed to non-null. */
 export declare function AsyncPreviewBody<TData, TContext = unknown, TType extends string = string>({ children, }: AsyncPreviewBodyProps<TData, TContext, TType>): import("react").JSX.Element | null;
+/**
+ * The loading case: a spinner with the fetcher's slow-step label, unless replaced. One part per
+ * state, so each is styled where it is written.
+ */
 export declare function AsyncPreviewLoading({ className, children }: AsyncPreviewSlotProps): import("react").JSX.Element | null;
+/**
+ * The error case: a message with a retry, unless replaced. One part per state, so each is
+ * styled where it is written.
+ */
 export declare function AsyncPreviewError({ className, children }: AsyncPreviewSlotProps): import("react").JSX.Element | null;
+/**
+ * The case where the fetch resolved to nothing. One part per state, so each is styled where it
+ * is written.
+ */
 export declare function AsyncPreviewEmpty({ className, children }: AsyncPreviewSlotProps): import("react").JSX.Element | null;