@kitn.ai/ui 0.17.0 → 0.18.1

package/dist/components/composer.d.ts

@@ -0,0 +1,86 @@
+import { JSX } from 'solid-js';
+import { ComposerDoc, EntityRef } from '../primitives/composer-model';
+export interface TriggerItem {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Secondary muted text shown beside the label in the menu (Codex-style). */
+    description?: string;
+    /** Section header to group this item under in the menu (e.g. 'Plugins', 'Agents'). */
+    group?: string;
+    /** Entity kind for the inserted pill; overrides the trigger's default `kind` so
+     *  one trigger can mix kinds across sections (e.g. agents + plugins under `@`). */
+    kind?: string;
+    promptText?: string;
+    data?: Record<string, unknown>;
+}
+export interface TriggerDef {
+    char: string;
+    kind: string;
+    items?: TriggerItem[];
+}
+export type HighlightRule = string | {
+    pattern: string;
+    flags?: string;
+    class?: string;
+};
+export interface ComposerChange {
+    doc: ComposerDoc;
+    text: string;
+    entities: EntityRef[];
+}
+/** Imperative handle exposed via `controllerRef` — surfaces the composer's latent
+ *  capabilities (focus/blur the editable, clear the doc, submit, insert a pill) so
+ *  the `<kai-composer>` facade can forward them as instance methods. */
+export interface ComposerController {
+    focus(options?: FocusOptions): void;
+    blur(): void;
+    clear(): void;
+    send(): void;
+    insertEntity(entity: EntityRef): void;
+}
+export interface ComposerProps {
+    value?: string | ComposerDoc;
+    placeholder?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    maxHeight?: number | string;
+    submitOnEnter?: boolean;
+    triggers?: TriggerDef[];
+    highlights?: HighlightRule[];
+    /** Default icon per entity kind (kind → image URL/data-URI), shown on a pill +
+     *  menu item when the item has no `icon` of its own. Overrides the built-in
+     *  glyphs (agent/plugin). Example: `{ agent: '/icons/bot.svg' }`. */
+    kindIcons?: Record<string, string>;
+    /** Render WITHOUT the rounded frame/background/padding — just the editable +
+     *  placeholder + menu. For embedding inside another frame (e.g. PromptInput). */
+    bare?: boolean;
+    /** Override the editable element's classes (used in `bare` mode to match an
+     *  existing input's exact look). The placeholder mirrors these for alignment. */
+    editableClass?: string;
+    /** Accessible name for the editable (role=textbox). Falls back to the
+     *  placeholder, then "Message input". */
+    ariaLabel?: string;
+    /** Receive the editable element (e.g. to register it for click-to-focus). */
+    editableRef?: (el: HTMLDivElement) => void;
+    /** Receive the imperative controller once mounted. The `<kai-composer>` facade
+     *  forwards these as element methods (focus/blur/clear/send/insertEntity). */
+    controllerRef?: (controller: ComposerController) => void;
+    onChange?: (change: ComposerChange) => void;
+    onSubmit?: (change: ComposerChange) => void;
+    onTrigger?: (info: {
+        char: string;
+        query: string;
+        rect: DOMRect;
+    }) => void;
+    onTriggerClose?: () => void;
+    onEntityAdd?: (entity: EntityRef) => void;
+    onEntityRemove?: (entity: EntityRef) => void;
+    /** The editable gained focus. `focus`/`blur` are NOT composed, so they don't
+     *  escape the shadow root — this re-exposes them. (keydown/paste/focusin/focusout
+     *  are composed and already reach the host as native events; no wrapper needed.) */
+    onFocus?: (e: FocusEvent) => void;
+    /** The editable lost focus. */
+    onBlur?: (e: FocusEvent) => void;
+}
+export declare function Composer(props: ComposerProps): JSX.Element;

package/dist/components/confirm-card.d.ts

@@ -28,6 +28,20 @@ export declare function normalizeActions(actions: unknown): {
 };
 /** The id of the default action (first with `default:true`), if any. */
 export declare function defaultActionId(actions: ConfirmAction[]): string | undefined;
+/** Imperative handle exposed via `controllerRef` — surfaces the confirm card's
+ *  latent action/dismiss capabilities so the `<kai-confirm>` facade can forward
+ *  them as instance methods (focus/confirm/dismiss/reopen). */
+export interface ConfirmController {
+    /** Focus the default action button (or the first action if none default). */
+    focus(options?: FocusOptions): void;
+    /** Activate an action by id (or the default action when omitted) — emits the
+     *  `action` verb + resolves single-shot. */
+    confirm(actionId?: string): void;
+    /** Dismiss the card — emits `dismiss` + optimistically collapses to the stub. */
+    dismiss(): void;
+    /** Re-open a dismissed card from its stub — emits `reopen`. */
+    reopen(): void;
+}
 export interface ConfirmCardProps {
     /** The confirm definition (CardEnvelope.data). */
     data?: ConfirmCardData;
@@ -45,6 +59,9 @@ export interface ConfirmCardProps {
     class?: string;
     /** When set, render the chromed read-only view instead of the buttons. */
     resolution?: CardResolution;
+    /** Receive the imperative controller once mounted. The `<kai-confirm>` facade
+     *  forwards these as element methods (focus/confirm/dismiss/reopen). */
+    controllerRef?: (controller: ConfirmController) => void;
 }
 /**
  * `ConfirmCard` — a named-intent approval card. Renders a title + body + a small

package/dist/components/conversation-item.d.ts

@@ -3,6 +3,15 @@ export interface ConversationItemProps {
     conversation: ConversationSummary;
     isActive: boolean;
     onSelect: (id: string) => void;
+    /** Dense single-line row: a leading dot + title, no message count. */
+    compact?: boolean;
     class?: string;
 }
+/**
+ * Short relative time from an ISO date string: "just now", "5m ago", "3h ago",
+ * "2d ago", "24d ago". Pure — it snapshots `now` (defaults to `Date.now()`) at
+ * call time, so it re-derives whenever the list re-renders; there is no internal
+ * ticking clock. Returns '' for a missing or unparseable date.
+ */
+export declare function relativeTimeShort(iso?: string, now?: number): string;
 export declare function ConversationItem(props: ConversationItemProps): import("solid-js").JSX.Element;

package/dist/components/conversation-list.d.ts

@@ -1,4 +1,17 @@
+import { JSX } from 'solid-js';
 import { ConversationSummary, ConversationGroup } from '../types';
+/**
+ * The collapsed-rail fallback: a floating reopen button shown when the
+ * conversation sidebar is collapsed. Shared by `kai-workspace` (its collapsed
+ * branch) and the standalone `kai-conversations` (collapsed mode), so the rail
+ * collapses identically in both. Renders only the button; the host owns the
+ * surrounding region (the workspace puts the thread beside it, the standalone
+ * element stands alone). `onExpand` reopens the rail.
+ */
+export declare function CollapsedRail(props: {
+    onExpand: () => void;
+    class?: string;
+}): JSX.Element;
 export interface ConversationListProps {
     groups: ConversationGroup[];
     conversations: ConversationSummary[];
@@ -6,6 +19,28 @@ export interface ConversationListProps {
     onSelect: (id: string) => void;
     onNewChat: () => void;
     onToggleSidebar?: () => void;
+    /** Replaces the built-in title bar (toggle / "Chats" / New chat). */
+    header?: JSX.Element;
+    /** A row below the list (e.g. account / settings / usage). */
+    footer?: JSX.Element;
+    /** Replaces the built-in "no conversations yet" state. */
+    empty?: JSX.Element;
+    /** Dense single-line rows (a leading dot + title, no message count). */
+    compact?: boolean;
+    /** Fired whenever the built-in search box query changes (typing or a
+     *  programmatic `clear()`). Lets the facade surface a `kai-search` event. */
+    onSearchChange?: (query: string) => void;
+    /** Receive the imperative controller once mounted. The `kai-conversations`
+     *  facade uses it to focus / clear the internal search input. */
+    controllerRef?: (controller: ConversationListController) => void;
     class?: string;
 }
-export declare function ConversationList(props: ConversationListProps): import("solid-js").JSX.Element;
+/** Imperative handle exposed via `controllerRef` — surfaces the internal search
+ *  box to the `kai-conversations` facade (the searchQuery signal lives here). */
+export interface ConversationListController {
+    /** Focus the built-in search `<input>`. */
+    focus(options?: FocusOptions): void;
+    /** Clear the internal search query (resets the list filter). */
+    clearSearch(): void;
+}
+export declare function ConversationList(props: ConversationListProps): JSX.Element;

package/dist/components/file-tree.d.ts

@@ -11,7 +11,18 @@ export interface FileTreeFile {
     language?: string;
     /** Kind — drives the icon + whether Code applies. */
     type?: 'html' | 'pdf' | 'image' | 'other';
+    /** Lines added vs the base. Rendered as a trailing `+N` stat (success hue,
+     *  tabular-nums). Only shown when present; omit for a plain file row. */
+    additions?: number;
+    /** Lines removed vs the base. Rendered as a trailing `-N` stat (error hue). */
+    deletions?: number;
+    /** Change status vs the base. Drives a small trailing status letter in the
+     *  conventional VCS hue (added=green, modified=amber, deleted=red,
+     *  renamed=blue, untracked=muted). Only shown when present. */
+    status?: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
 }
+/** A change status a file can carry. */
+export type FileStatus = NonNullable<FileTreeFile['status']>;
 /** A folder node in the built tree. */
 export interface FileTreeFolderNode {
     kind: 'folder';
@@ -48,6 +59,10 @@ export interface FileTreeProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
     onSelect?: (path: string, file: FileTreeFile) => void;
     /** Folder paths expanded by default. When omitted, all folders start open. */
     defaultExpanded?: string[];
+    /** Show a summary header above the tree: the changed-file count, the summed
+     *  `+additions / -deletions`, and a Collapse-all/Expand-all toggle wired to the
+     *  folder-expand state. Off by default (no header — unchanged behavior). */
+    summary?: boolean;
 }
 /**
  * `FileTree` — a collapsible, keyboard-navigable file explorer built from a flat

package/dist/components/form.d.ts

@@ -77,6 +77,27 @@ export declare function summarizeForm(def: FormDefinition, data: Record<string,
 /** Build the result object: coerced values with empty optional fields omitted.
  *  `false` and `0` are kept (they are real values, not "empty"). */
 export declare function buildResult(def: FormDefinition, values: Record<string, unknown>): Record<string, unknown>;
+/** Imperative handle exposed via `controllerRef` — surfaces the form's latent
+ *  capabilities (focus the first/first-invalid control, validate, programmatic
+ *  send, reset to defaults, dismiss/reopen) so the `<kai-form>` facade can forward
+ *  them as instance methods. */
+export interface FormController {
+    /** Focus the first control, or the first INVALID control after a failed validation. */
+    focus(options?: FocusOptions): void;
+    /** Run full validation + submit: focus the first invalid field on failure, else emit `submit`. */
+    send(): void;
+    /** Run client-side validation now and return per-field errors WITHOUT submitting. */
+    validate(): {
+        valid: boolean;
+        errors?: Record<string, string>;
+    };
+    /** Re-seed from each field's `default` and clear errors. */
+    reset(): void;
+    /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+    dismiss(): void;
+    /** Re-open a dismissed card from its stub (emit `reopen`). */
+    reopen(): void;
+}
 export interface FormProps {
     /** The form definition (CardEnvelope.data). */
     data?: FormDefinition;
@@ -92,6 +113,19 @@ export interface FormProps {
     class?: string;
     /** When set, render the chromed read-only view instead of the form inputs. */
     resolution?: CardResolution;
+    /** Controlled field values — when set, this wins over internal/uncontrolled state. */
+    values?: Record<string, unknown>;
+    /** Initial values overlaying the schema defaults (uncontrolled seed). */
+    defaultValues?: Record<string, unknown>;
+    /** Disable all fields + submit. */
+    disabled?: boolean;
+    /** Fires on input with the current coerced values + validity (distinct from submit). */
+    onValuesChange?: (payload: {
+        values: Record<string, unknown>;
+        valid: boolean;
+    }) => void;
+    /** Receive the imperative controller once mounted. */
+    controllerRef?: (controller: FormController) => void;
 }
 /**
  * `Form` — renders a JSON-Schema form definition into themed, accessible widgets

package/dist/components/markdown.d.ts

@@ -3,6 +3,9 @@ export interface MarkdownProps {
     id?: string;
     class?: string;
     codeTheme?: string;
+    /** Optional `::part` name(s) to expose on the rendered root. Lets callers
+     *  (e.g. the message bubble) surface a styleable part through the shadow. */
+    part?: string;
 }
 declare function Markdown(props: MarkdownProps): import("solid-js").JSX.Element;
 export { Markdown };

package/dist/components/message.d.ts

@@ -16,6 +16,10 @@ declare function MessageAvatar(props: MessageAvatarProps): JSX.Element;
 export interface MessageContentProps extends JSX.HTMLAttributes<HTMLDivElement> {
     children: JSX.Element | string;
     markdown?: boolean;
+    /** `::part` name(s) exposed on the content node. The body passes
+     *  `"bubble content"` so consumers can target either the rounded bubble or the
+     *  text region from outside the shadow boundary. */
+    part?: string;
 }
 declare function MessageContent(props: MessageContentProps): JSX.Element;
 export interface MessageActionsProps extends JSX.HTMLAttributes<HTMLDivElement> {
@@ -85,6 +89,14 @@ export interface MessageBodyProps {
     activeFeedback?: FeedbackVote;
     /** When true, the copy button shows its "copied" check icon. */
     copied?: boolean;
+    /** INJECT slot projected at the TOP of the body — above the reasoning / tools /
+     *  content. A per-message header: a model-name label, a role + timestamp line.
+     *  In the `<kai-message>` shadow this is `<slot name="before-body" />`. */
+    beforeBody?: JSX.Element;
+    /** INJECT slot projected at the BOTTOM of the body — below the action bar. A
+     *  citation / sources row, a token-cost / latency line. In the `<kai-message>`
+     *  shadow this is `<slot name="after-body" />`. */
+    afterBody?: JSX.Element;
 }
 /**
  * The shared message body: an optional reasoning block, tool calls, inline

package/dist/components/model-switcher.d.ts

@@ -1,8 +1,15 @@
+import { DropdownController } from '../ui/dropdown';
 import { ModelOption } from '../types';
 export interface ModelSwitcherProps {
     models: ModelOption[];
     currentModelId: string;
     onModelChange: (modelId: string) => void;
     class?: string;
+    /** Initial open state of the dropdown (uncontrolled seed). */
+    defaultOpen?: boolean;
+    /** Disable the trigger — click/keyboard no longer open the dropdown. */
+    disabled?: boolean;
+    /** Receive the dropdown's open controller (forwarded from the inner Dropdown). */
+    controllerRef?: (api: DropdownController) => void;
 }
 export declare function ModelSwitcher(props: ModelSwitcherProps): import("solid-js").JSX.Element;

package/dist/components/prompt-input.d.ts

@@ -1,18 +1,21 @@
 import { JSX } from 'solid-js';
+import { TriggerDef, ComposerChange } from './composer';
+import { ComposerDoc } from '../primitives/composer-model';
 interface PromptInputContextType {
     isLoading: boolean;
-    value: () => string;
+    value: () => string | ComposerDoc;
     setValue: (value: string) => void;
     maxHeight: number | string;
     onSubmit?: () => void;
     disabled?: boolean;
-    textareaRef: HTMLTextAreaElement | undefined;
-    setTextareaRef: (el: HTMLTextAreaElement) => void;
+    textareaRef: HTMLElement | undefined;
+    setTextareaRef: (el: HTMLElement) => void;
 }
 declare function usePromptInput(): PromptInputContextType;
 export interface PromptInputProps extends JSX.HTMLAttributes<HTMLDivElement> {
     isLoading?: boolean;
-    value?: string;
+    /** String = controlled text; ComposerDoc = a seed that pre-populates pills. */
+    value?: string | ComposerDoc;
     onValueChange?: (value: string) => void;
     maxHeight?: number | string;
     onSubmit?: () => void;
@@ -22,6 +25,12 @@ export interface PromptInputProps extends JSX.HTMLAttributes<HTMLDivElement> {
 declare function PromptInput(props: PromptInputProps): JSX.Element;
 export interface PromptInputTextareaProps extends JSX.TextareaHTMLAttributes<HTMLTextAreaElement> {
     disableAutosize?: boolean;
+    /** Rich entity triggers (`/`, `@`) forwarded to the composer. */
+    triggers?: TriggerDef[];
+    /** Default icon per entity kind (kind → image src), forwarded to the composer. */
+    kindIcons?: Record<string, string>;
+    /** Structured change (doc + entities) from the composer, on every edit. */
+    onComposerChange?: (change: ComposerChange) => void;
 }
 declare function PromptInputTextarea(props: PromptInputTextareaProps): JSX.Element;
 export interface PromptInputActionsProps extends JSX.HTMLAttributes<HTMLDivElement> {

package/dist/components/prompt-suggestion.d.ts

@@ -2,12 +2,20 @@ import { JSX } from 'solid-js';
 export interface PromptSuggestionProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {
     children: JSX.Element | string;
     variant?: 'outline' | 'ghost' | 'default';
-    size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+    /** Row height for the `list` layout: `'md'` (default) or `'lg'` for taller
+     *  rows (more vertical padding). Chips/block/highlight are unaffected. */
+    size?: 'md' | 'lg';
+    /** Optional leading icon (named icon, image URL/data-URI, or text). */
+    icon?: string;
     highlight?: string;
     /** Render as a full-width, left-aligned list row (the "suggested questions"
      *  idiom) instead of a rounded pill. Wraps long text. Ignored in highlight
      *  mode, which is always a list row. */
     block?: boolean;
+    /** Render as a full-width "Ideas for you" list row: a leading icon, a
+     *  left-aligned label, and a hover background. Like `block`, but keeps the
+     *  leading icon. Ignored in highlight mode. */
+    list?: boolean;
 }
 declare function PromptSuggestion(props: PromptSuggestionProps): JSX.Element;
 export { PromptSuggestion };

package/dist/components/reasoning.d.ts

@@ -1,10 +1,23 @@
-import { JSX } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
+/** Imperative open controller, handed to a parent (the kai-reasoning facade) via
+ *  `controllerRef` so it can drive/observe open state — mirrors
+ *  CollapsibleController/HoverCardController. */
+export interface ReasoningController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
 export interface ReasoningProps {
     children: JSX.Element;
     class?: string;
     open?: boolean;
+    /** Initial open state (uncontrolled seed). */
+    defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
     isStreaming?: boolean;
+    /** Gate the trigger — programmatic control via the controller still works. */
+    disabled?: boolean;
+    /** Receive the open controller (open accessor + setOpen) once mounted. */
+    controllerRef?: (api: ReasoningController) => void;
 }
 declare function Reasoning(props: ReasoningProps): JSX.Element;
 export interface ReasoningTriggerProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {

package/dist/components/response-compare.d.ts

@@ -3,6 +3,17 @@ import { CompareSelection, ResponseCompareData } from './response-compare-types'
 export type { CompareCandidate, ComparePair, CompareCollapse, ResponseCompareData, CompareSelection, } from './response-compare-types';
 export { normalizeCandidates, buildSelection, isAnyStreaming } from './response-compare-types';
 export type CompareLayout = 'auto' | 'columns' | 'tabs';
+/** Imperative handle exposed via `controllerRef` — surfaces the compare's latent
+ *  capabilities (commit a pick by candidate id, focus the roving tab stop) so the
+ *  `<kai-compare>` facade can forward them as instance methods (Pattern C). */
+export interface ResponseCompareController {
+    /** Commit a pick by candidate id — same path as the "Pick this" button: emits
+     *  onSelect + optimistically collapses (single-shot; inert while streaming or
+     *  already resolved). No-op for an unknown id. */
+    select(candidateId: string): void;
+    /** Focus the current roving tab stop (the focused candidate's "Pick this" radio). */
+    focus(options?: FocusOptions): void;
+}
 export interface ResolvedController<T> {
     value: Accessor<T | undefined>;
     isResolved: Accessor<boolean>;
@@ -26,6 +37,9 @@ export interface ResponseCompareProps {
      *  component is ≥640px wide, tabs when narrower (e.g. on a phone). */
     layout?: CompareLayout;
     class?: string;
+    /** Receive the imperative controller once mounted. The `<kai-compare>` facade
+     *  forwards these as element methods (select/focus). */
+    controllerRef?: (controller: ResponseCompareController) => void;
     /** Fired when the user commits a pick. */
     onSelect?: (sel: CompareSelection) => void;
     /** Fired once both candidates have settled (stopped streaming) and a valid

package/dist/components/screen.d.ts

@@ -0,0 +1,46 @@
+import { Accessor, JSX } from 'solid-js';
+/** Imperative open controller, handed to a parent (the kai-screen facade) via
+ *  `controllerRef` so it can drive/observe open state with `wireDisclosure`. */
+export interface ScreenController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
+export interface ScreenProps {
+    /** The screen body. */
+    children?: JSX.Element;
+    /** Header title text. A projected `title` slot overrides this. */
+    title?: JSX.Element;
+    /** Header title slot content (the facade's `<slot name="title" />`). Overrides `title`. */
+    titleSlot?: JSX.Element;
+    /** Header trailing cluster (the facade's `<slot name="actions" />`). */
+    actions?: JSX.Element;
+    /** Controlled open state. When set, the component never changes it itself;
+     *  drive it from `onOpenChange`. Omit for uncontrolled (internal) state. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Show the back button (default true). */
+    back?: boolean;
+    /** Skip marking sibling elements inert/aria-hidden while open. */
+    noInert?: boolean;
+    /** The custom-element host, whose siblings get inert-ed while open. */
+    host?: () => HTMLElement | undefined;
+    /** Fires whenever open wants to change (back button / method). */
+    onOpenChange?: (open: boolean) => void;
+    /** Back navigation intent: the back button or Escape. */
+    onBack?: () => void;
+    /** Receive the open controller once mounted. */
+    controllerRef?: (api: ScreenController) => void;
+    /** Receive the focusable surface node so the facade's `focus()` can target it. */
+    surfaceRef?: (el: HTMLElement) => void;
+}
+/**
+ * Screen is the presentational full-bleed overlay surface. It owns the hard parts
+ * of being a takeover: it fills its mount point while open, marks sibling
+ * elements `inert` + `aria-hidden` (the standard modal pattern), moves focus into
+ * the surface on open and restores it on close, fires `onBack` on Escape, and
+ * runs an enter/exit transition that honors `prefers-reduced-motion`. When closed
+ * it is removed from layout (no space, not focusable). The developer owns the swap
+ * (their own routing flips `open`); this owns being the overlay.
+ */
+export declare function Screen(props: ScreenProps): JSX.Element;

package/dist/components/tasks-card.d.ts

@@ -8,7 +8,15 @@ export interface TasksTask {
     disabled?: boolean;
 }
 export interface TasksCardData {
-    mode?: 'select';
+    /**
+     * `select` (default) = checkbox rows + a confirm button that emits the contract
+     * `submit`. `progress` = an onboarding/checklist look: a header `done / total`
+     * count, circular indicators, per-item title + muted description, and NO confirm
+     * button (checking a row is itself the terminal action). Both share the same
+     * selection model (toggle by id, the `max` gate, `kai-value-change`); `progress`
+     * is purely a presentational variant.
+     */
+    mode?: 'select' | 'progress';
     heading?: string;
     tasks: TasksTask[];
     selectAll?: boolean;
@@ -40,12 +48,36 @@ export declare function selectAllState(tasks: TasksTask[], selected: Set<string>
 /** Whether select-all should be shown: requested AND not blocked by `max` (since
  *  "all" would violate max). */
 export declare function showSelectAll(data: TasksCardData, tasks: TasksTask[]): boolean;
+/** Whether the card is in the onboarding-checklist `progress` look (no confirm). */
+export declare function isProgressMode(data: TasksCardData): boolean;
+/** The header progress count (`done` checked / `total` rows) for `progress` mode. */
+export declare function progressCount(tasks: TasksTask[], selected: Set<string>): {
+    done: number;
+    total: number;
+};
 /** Whether confirm is enabled for the current selection count. */
 export declare function canConfirm(data: TasksCardData, count: number): boolean;
 /** Whether an unchecked row is blocked because `max` is reached. */
 export declare function isMaxReached(data: TasksCardData, count: number): boolean;
 /** The disabled-reason text for confirm (for aria-describedby), or undefined. */
 export declare function confirmReason(data: TasksCardData, count: number): string | undefined;
+/** Imperative handle exposed via `controllerRef` — surfaces the tasks card's latent
+ *  selection model (set the checked ids, toggle one, confirm, focus the group,
+ *  dismiss/reopen) so the `<kai-tasks>` facade can forward them as instance methods. */
+export interface TasksCardController {
+    /** Set the checked ids (local-only, no emit), respecting disabled/max. No arg = select all toggleable rows. */
+    select(taskIds?: string[]): void;
+    /** Toggle one task by id, honoring the max gate. */
+    toggle(taskId: string, checked?: boolean): void;
+    /** Confirm the current selection (only when allowed) — emits `submit` + resolves. */
+    send(): void;
+    /** Focus the task group (select-all checkbox if shown, else the first row). */
+    focus(options?: FocusOptions): void;
+    /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+    dismiss(): void;
+    /** Re-open a dismissed card from its stub (emit `reopen`). */
+    reopen(): void;
+}
 export interface TasksCardProps {
     /** The tasks definition (CardEnvelope.data). */
     data?: TasksCardData;
@@ -61,6 +93,22 @@ export interface TasksCardProps {
     class?: string;
     /** When set, render the chromed read-only summary instead of the interactive controls. */
     resolution?: CardResolution;
+    /** Controlled selection (task ids) — when set, this wins over internal state. */
+    value?: string[];
+    /** Uncontrolled initial selection (task ids), overlaying per-task `checked`. */
+    defaultValue?: string[];
+    /** Freeze the whole list + Confirm. */
+    disabled?: boolean;
+    /** Display-only: rows can't be toggled and show the default cursor (no pointer,
+     *  no hover background, no focus ring). Keeps the visual content as-is — this only
+     *  drops the interactive affordances + a11y exposure. */
+    readonly?: boolean;
+    /** Fires on every selection change with the selected ids (distinct from submit). */
+    onValueChange?: (payload: {
+        value: string[];
+    }) => void;
+    /** Receive the imperative controller once mounted. */
+    controllerRef?: (controller: TasksCardController) => void;
 }
 /**
  * `TasksCard` — a selectable task/plan list (checkbox rows + optional select-all

package/dist/components/toast.d.ts

@@ -1,5 +1,5 @@
-import { ToastItem, ToastVariant } from '../primitives/toast-store';
-export type { ToastItem, ToastVariant };
+import { ToastItem, ToastVariant, ToastAppearance } from '../primitives/toast-store';
+export type { ToastItem, ToastVariant, ToastAppearance };
 /** Why a toast went away — surfaced to `onDismiss` (and the facade event). */
 export type ToastDismissReason = 'timeout' | 'close' | 'action';
 export type ToastPosition = 'top-center' | 'top-right' | 'top-left' | 'bottom-center' | 'bottom-right' | 'bottom-left';
@@ -15,6 +15,12 @@ export interface ToastRegionProps {
     /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style
      *  pile that expands on hover/focus). Attribute: stack. */
     stack?: 'expanded' | 'collapsed';
+    /** Region-level default appearance for toasts that don't set their own. A
+     *  per-toast `appearance` always wins. Defaults to `'pill'`. */
+    appearance?: ToastAppearance;
+    /** Region-level default inverse treatment for toasts that don't set their own.
+     *  A per-toast `inverse` always wins. Defaults to `false`. */
+    inverse?: boolean;
     /** When set, this region renders only the toasts scoped to that element and
      *  anchors over its bounds (top-center), following it on scroll/resize. Unset =
      *  the global, viewport-anchored region. */
@@ -31,6 +37,10 @@ interface ToastProps {
     /** Hold the auto-dismiss timer (the region sets this true while the whole stack
      *  is hovered/expanded, so peers don't dismiss out from under the cursor). */
     paused?: boolean;
+    /** Region-level default appearance, used when the item doesn't set its own. */
+    appearance?: ToastAppearance;
+    /** Region-level default inverse, used when the item doesn't set its own. */
+    inverse?: boolean;
 }
 /**
  * A single toast pill. Auto-dismisses after its (action-floored) duration, holds

package/dist/components/tool-types.d.ts

@@ -0,0 +1,10 @@
+/** A tool-call part rendered by <Tool>. Pure type — kept JSX-free so it can be
+ *  imported by the framework-neutral state core and the React typecheck pass. */
+export interface ToolPart {
+    type: string;
+    state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    toolCallId?: string;
+    errorText?: string;
+}

package/dist/components/tool.d.ts

@@ -1,15 +1,15 @@
 import { JSX } from 'solid-js';
-export interface ToolPart {
-    type: string;
-    state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
-    input?: Record<string, unknown>;
-    output?: Record<string, unknown>;
-    toolCallId?: string;
-    errorText?: string;
-}
+import { CollapsibleController } from '../ui/collapsible';
+import { ToolPart } from './tool-types';
+export type { ToolPart } from './tool-types';
 export interface ToolProps {
     toolPart: ToolPart;
     defaultOpen?: boolean;
+    /** Gate the disclosure trigger (programmatic control still works). */
+    disabled?: boolean;
+    /** Receive the open controller once mounted (forwarded from the Collapsible),
+     *  so a parent (the kai-tool facade) can drive/observe open state. */
+    controllerRef?: (api: CollapsibleController) => void;
     class?: string;
 }
 declare function Tool(props: ToolProps): JSX.Element;