@makinbakin/sdk 0.0.1-rc.35 → 0.0.1-rc.36

package/_internal/app/components/drawer.d.ts

@@ -3,9 +3,7 @@ declare const MIN_WIDTH = 320;
 declare const MAX_WIDTH = 960;
 declare const DEFAULT_WIDTH = 810;
 declare const DRAWER_WIDTH_STORAGE_KEY = "bakin-drawer-width";
-declare function clampDrawerWidth(width: number): number;
 declare function getDrawerWidthStorageKey(storageKey?: string): string;
-declare function getStoredDrawerWidth(defaultWidth: number, storageKey?: string): number;
 export interface DrawerProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
@@ -26,4 +24,4 @@ export interface DrawerProps {
     busy?: boolean;
 }
 export declare function Drawer({ open, onOpenChange, title, ariaLabel, description, actions, children, defaultWidth, storageKey, onBack, dirty, busy, }: DrawerProps): import("react/jsx-runtime").JSX.Element;
-export { MIN_WIDTH, MAX_WIDTH, DEFAULT_WIDTH, DRAWER_WIDTH_STORAGE_KEY, clampDrawerWidth, getDrawerWidthStorageKey, getStoredDrawerWidth, };
+export { MIN_WIDTH, MAX_WIDTH, DEFAULT_WIDTH, DRAWER_WIDTH_STORAGE_KEY, getDrawerWidthStorageKey, };

package/_internal/app/hooks/use-available-models.d.ts

@@ -1,5 +1,25 @@
 import type { AvailableModel } from '@makinbakin/sdk/types';
-/** The available-models catalog (empty array until loaded / on failure). */
-export declare function useAvailableModels(): AvailableModel[];
-/** Test-only: reset the module-level cache so tests run with a clean slate. */
-export declare function __resetAvailableModelsCache(): void;
+/**
+ * The available-models catalog (empty array until loaded / on failure);
+ * refetches when the server says it changed. Pass the agent a picker belongs
+ * to so its verdicts are that agent's.
+ */
+export declare function useAvailableModels(agentId?: string): AvailableModel[];
+/** The option shape `ModelSelect` consumes — kept structurally identical to `ModelSelectOption`. */
+export interface EligibleModelOption {
+    id: string;
+    name: string;
+    provider?: string;
+    disabled: boolean;
+    description?: string;
+    tone?: 'default' | 'danger';
+}
+/**
+ * Map catalog rows to picker options so NO picker can select a dead model
+ * (#907): `ineligible` rows are disabled, carry the reason as the option's
+ * DESCRIPTION (secondary text + `aria-describedby`; the name stays the
+ * name) and the `danger` tone (a dead value that is currently selected
+ * renders as such in the trigger) — D23; `unknown` rows stay selectable —
+ * missing evidence is never a refusal.
+ */
+export declare function toModelSelectOptions(models: readonly AvailableModel[]): EligibleModelOption[];

package/_internal/app/hooks/use-runtime-status.d.ts

@@ -1,12 +1,28 @@
-interface RuntimeStatus {
-    restartNeeded: boolean;
+export interface RestartAdviceWire {
+    needed: boolean;
+    title?: string;
+    body?: string;
+    action?: {
+        label: string;
+        kind: 'restart-runtime';
+    };
+}
+export interface RuntimeStatus {
+    /** A config change is waiting on a runtime restart (adapter-advised, persisted server-side). */
+    pending: boolean;
+    /** What to render: the adapter's own title/body/action, or the generic fallback. */
+    advice: RestartAdviceWire;
     restarting: boolean;
+    /** The last restart attempt's failure, when the banner is retained because of it. */
+    lastError: string | null;
     restart: () => Promise<void>;
-    markDirty: () => void;
+    /** Re-read server state after a save — the SERVER decides whether a restart is pending. */
+    refresh: () => Promise<void>;
 }
 /**
- * Check if the active runtime needs a restart after config changes.
- * Shared across agent detail, models page, and team grid.
+ * Pending-restart status for the active runtime (#878): the banner is a
+ * dumb renderer of what the adapter said. Shared by the Models page, agent
+ * detail and the team grid. Never set optimistically on the client — a
+ * save calls `refresh()` and the server answers from persisted state.
  */
 export declare function useRuntimeStatus(): RuntimeStatus;
-export {};

package/_internal/app/hooks/use-toast.d.ts

@@ -4,6 +4,16 @@ export interface Toast {
     message: ReactNode;
     type: 'success' | 'error' | 'info';
     duration?: number;
+    /** Optional heading above the message (the kit Toast's title slot). */
+    title?: ReactNode;
+    /** Optional action row (the kit Toast's action slot). */
+    action?: ReactNode;
+    /**
+     * Stays until dismissed — no timer. For attention the operator must act
+     * on (the spend ladder's 90% and cap toasts); a caller that needs to know
+     * WHEN it was closed subscribes to the store and watches its id go.
+     */
+    persistent?: boolean;
 }
 interface ToastStore {
     toasts: Toast[];

package/_internal/core/adapters/runtime/concepts.d.ts

@@ -533,9 +533,60 @@ export interface RuntimeAvailableModel {
     contextWindow?: number;
     local?: boolean;
     available?: boolean;
+    /**
+     * WHY `available` is false, when the runtime knows (#907). Pi reports
+     * `no_credentials` for catalog models whose provider has no configured
+     * auth — the model exists, the account cannot reach it. Consumers never
+     * infer a reason the runtime did not give: absent ⇒ "runtime reports
+     * this model unavailable", never "retired".
+     */
+    unavailableReason?: 'no_credentials' | 'not_configured' | 'other';
     tags?: string[];
     metadata?: RuntimeMetadata;
 }
+/**
+ * Status-only record for ONE LLM provider (#907 / the model slice of #378).
+ * `configured` is the runtime's own auth resolution (Pi: configured auth;
+ * OpenClaw: the merged auth-profiles + CLI probe) — never config-key
+ * presence. `authFree` marks providers that need no credential (local
+ * models). NEVER carries secret material — the declared field set is
+ * pinned by tests/architecture/provider-inventory-shape.test.ts and the
+ * runtime values by the conformance suite.
+ */
+export interface ProviderCredentialStatus {
+    providerId: string;
+    configured: boolean;
+    authFree?: boolean;
+    source?: 'runtime' | 'env' | 'store';
+}
+/**
+ * The provider inventory `credentials.providers()` returns. `evidence` is
+ * HONEST: 'partial' whenever one of the adapter's credential sources failed
+ * (OpenClaw's CLI probe), so consumers treat providers absent from a partial
+ * inventory as UNKNOWN — never as credential-less.
+ */
+export interface ProviderCredentialInventory {
+    providers: ProviderCredentialStatus[];
+    evidence: 'complete' | 'partial';
+    detail?: string;
+}
+/** Kinds of Bakin-initiated config change an adapter may need a restart to apply. */
+export type RuntimeConfigChangeKind = 'model-config' | 'roster' | 'routing-policy';
+/**
+ * What the runtime says about applying a config change (#878 Models half).
+ * The Models page renders this verbatim — title/body/action come from the
+ * adapter, never from adapter-id branching upstream. `needed: false` means
+ * the change is live already (Pi re-reads its stores per turn).
+ */
+export interface RestartAdvice {
+    needed: boolean;
+    title?: string;
+    body?: string;
+    action?: {
+        label: string;
+        kind: 'restart-runtime';
+    };
+}
 export type RuntimeImageOutputFormat = 'png' | 'jpeg' | 'jpg' | 'webp';
 export type RuntimeImageBackground = 'transparent' | 'opaque' | 'auto';
 /**
@@ -729,6 +780,15 @@ export interface AgentRuntimeAdapter {
      * writes and expect the next read to reflect them.
      */
     restart(): Promise<void>;
+    /**
+     * OPTIONAL (#878): does a change of this kind need `restart()` before the
+     * runtime applies it, and how should the UI say so? SYNC + static, like
+     * describeToolAccess(). Adapters that omit the member get a conservative
+     * generic banner from the caller; absence is member omission, never a
+     * throwing stub (conformance-pinned). Callers feature-detect
+     * (`runtime.restartAdvice?.(kind)`).
+     */
+    restartAdvice?(change: RuntimeConfigChangeKind): RestartAdvice | undefined;
     /**
      * CRUD error contract (R28): `get` returns `null` for a missing agent —
      * absence is a value, never a throw. Mutations addressing a MISSING agent
@@ -857,6 +917,18 @@ export interface AgentRuntimeAdapter {
         probe?(modelId: string, opts?: {
             signal?: AbortSignal;
         }): Promise<void>;
+        /**
+         * OPTIONAL (#907 review): the catalog id this runtime would RUN `ref`
+         * as — `ref` itself when the catalog lists it verbatim, the runtime's
+         * OWN resolution of a non-verbatim reference (Pi accepts bare model
+         * ids and resolves them by its registry rule), or null when the
+         * runtime would not resolve it. The eligibility engine judges a
+         * persisted selection by this row, so the verdict follows the
+         * adapter's actual turn-time semantics — never a catalog-shape guess.
+         * A runtime that omits the member runs exactly what its catalog lists.
+         * Read-only: no network, no turn.
+         */
+        resolveId?(ref: string): Promise<string | null>;
         /** Static declaration of which routing-policy fields this runtime honors. */
         routingSupport(): RuntimeRoutingSupport;
         /** The runtime's current routing policy (unsupported fields empty). */
@@ -900,6 +972,21 @@ export interface AgentRuntimeAdapter {
     credentialStatus(opts?: {
         agentId?: string;
     }): Promise<RuntimeCredentialStatus>;
+    /**
+     * OPTIONAL (#907 / #378 model slice): the per-provider STATUS-ONLY
+     * credential inventory the model-eligibility engine reads. Derived from
+     * the adapter's real auth resolution (the same path `credentialStatus`
+     * uses), with honest `evidence` when a source failed. `opts.agentId`
+     * scopes it where the runtime keys credentials per agent. Absence is
+     * member omission (conformance-pinned); callers feature-detect
+     * (`runtime.credentials?.providers(...)`) and treat absence as
+     * "credential evidence unavailable".
+     */
+    credentials?: {
+        providers(opts?: {
+            agentId?: string;
+        }): Promise<ProviderCredentialInventory>;
+    };
     /**
      * Wire up this runtime so its agents can reach Bakin's exec tools.
      * Idempotent + re-invokable: run at init AND whenever the agent roster or

package/_internal/core/adapters/runtime/index.d.ts

@@ -6,6 +6,6 @@ export { hasChannelCapability } from './capabilities';
 export { RuntimeError, RuntimeTurnError } from './errors';
 export type { RuntimeErrorKind, RuntimeErrorOptions, RuntimeProviderInfo, RuntimeTurnDiagnosis, RuntimeTurnFailureReason, } from './errors';
 export { getRuntimeMainAgent, getRuntimeMainAgentId, getRuntimeMainAgentName, selectRuntimeMainAgent, } from './helpers';
-export type { AgentRuntimeAdapter, ApprovalDelivery, ApprovalOption, ApprovalPatch, ApprovalRenderRef, ApprovalRenderResult, ApprovalResolveEvent, ApprovalResponse, CancelApprovalArgs, ChannelInfo, ChannelMessageArgs, ChatChunk, ChatTextFormat, ContentDeliveryArgs, CreateApprovalArgs, CreateThreadArgs, CreatedThread, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, EditChannelMessageArgs, InboundChannelAttachment, InboundChannelMessage, MessageArgs, MessageAttachment, MessageResult, MessageUsage, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeCapabilities, CapabilityMode, ToolAccessStyle, RuntimeToolAccess, ToolAccessProvisioningStatus, RuntimeCredentialStatus, RuntimeRoutingPolicy, RuntimeRoutingSupport, CapabilitySet, RuntimeImageBackground, RuntimeImageEditInput, RuntimeImageFile, RuntimeImageGenerateInput, RuntimeImageGenerationResult, RuntimeImageOutputFormat, RuntimeImageProvider, RuntimeImageProviderCapabilities, RuntimeImagesAccess, RuntimeExtensionInfo, RuntimeExtensionsAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMessageToolPolicy, RuntimeMessageToolsMode, RuntimeMetadata, RawCronSnapshot, RuntimeSession, RuntimeSessionStoreStats, RuntimeSessionContextStats, RuntimeSkill, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, WorkspaceFileStat, } from './concepts';
+export type { AgentRuntimeAdapter, ApprovalDelivery, ApprovalOption, ApprovalPatch, ApprovalRenderRef, ApprovalRenderResult, ApprovalResolveEvent, ApprovalResponse, CancelApprovalArgs, ChannelInfo, ChannelMessageArgs, ChatChunk, ChatTextFormat, ContentDeliveryArgs, CreateApprovalArgs, CreateThreadArgs, CreatedThread, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, EditChannelMessageArgs, InboundChannelAttachment, InboundChannelMessage, MessageArgs, MessageAttachment, MessageResult, MessageUsage, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeCapabilities, CapabilityMode, ToolAccessStyle, RuntimeToolAccess, ToolAccessProvisioningStatus, RuntimeCredentialStatus, ProviderCredentialStatus, ProviderCredentialInventory, RuntimeConfigChangeKind, RestartAdvice, RuntimeRoutingPolicy, RuntimeRoutingSupport, CapabilitySet, RuntimeImageBackground, RuntimeImageEditInput, RuntimeImageFile, RuntimeImageGenerateInput, RuntimeImageGenerationResult, RuntimeImageOutputFormat, RuntimeImageProvider, RuntimeImageProviderCapabilities, RuntimeImagesAccess, RuntimeExtensionInfo, RuntimeExtensionsAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMessageToolPolicy, RuntimeMessageToolsMode, RuntimeMetadata, RawCronSnapshot, RuntimeSession, RuntimeSessionStoreStats, RuntimeSessionContextStats, RuntimeSkill, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, WorkspaceFileStat, } from './concepts';
 export { RUNTIME_MEDIA_URI_SCHEME, DEFAULT_OVERSIZED_OUTPUT_BYTES } from './concepts';
 export { isSafeSkillFilePath, isExecutableSkillFile, readSkillTree, SKILL_SIDECAR_NAMES } from './skill-files';

package/_internal/core/adapters/runtime/testing.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRuntimeAdapter } from './concepts';
+import type { AgentRuntimeAdapter, ProviderCredentialStatus, RestartAdvice } from './concepts';
 /**
  * Opt-in channels surface for the mock (delivery capability pairs with it —
  * see createMockRuntimeAdapter). The DEFAULT mock omits `channels` entirely:
@@ -9,6 +9,26 @@ import type { AgentRuntimeAdapter } from './concepts';
  * Usage: `createMockRuntimeAdapter({ channels: mockChannels() })`
  */
 export declare function mockChannels(): NonNullable<AgentRuntimeAdapter['channels']>;
+/**
+ * Opt-in status-only credential inventory for the mock (#907 / #378 slice).
+ * `credentials` is an optional contract member, so the DEFAULT mock omits
+ * it — eligibility code must feature-detect and treat absence as
+ * "credential evidence unavailable" (models read `unknown`, never
+ * `ineligible`). Pass `evidence: 'partial'` to exercise the honest-partial
+ * branch (OpenClaw's CLI probe failing).
+ *
+ * Usage: `createMockRuntimeAdapter({ credentials: mockCredentials([{ providerId: 'mock', configured: true }]) })`
+ */
+export declare function mockCredentials(providers?: ProviderCredentialStatus[], evidence?: 'complete' | 'partial'): NonNullable<AgentRuntimeAdapter['credentials']>;
+/**
+ * Opt-in restart advice for the mock (#878). Optional member; the default
+ * mock omits it so the Models banner's generic-fallback path is what mock
+ * consumers see unless they opt in. The same advice is returned for every
+ * change kind unless a per-kind map is given.
+ *
+ * Usage: `createMockRuntimeAdapter({ restartAdvice: mockRestartAdvice({ needed: false }) })`
+ */
+export declare function mockRestartAdvice(advice: RestartAdvice | Partial<Record<'model-config' | 'roster' | 'routing-policy', RestartAdvice>>): NonNullable<AgentRuntimeAdapter['restartAdvice']>;
 /**
  * Opt-in cron surface for the mock — same rationale as mockChannels():
  * `cron` is an optional contract member (Pi omits it), so the default mock

package/_internal/core/plugin-types.d.ts

@@ -612,6 +612,18 @@ export interface BakinPlugin {
     onShutdown?(): void | Promise<void>;
     /** Called when this plugin's settings are updated */
     onSettingsChange?(settings: Record<string, unknown>): void | Promise<void>;
+    /**
+     * Validate a whole settings document BEFORE the generic
+     * `PUT /api/plugin-settings/{id}` writes it. A plugin whose settings are
+     * money or policy (the spend plugin) refuses documents its own routes
+     * would refuse, so no side door can leave an invalid file on disk.
+     */
+    validateSettings?(value: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    };
     /**
      * Called by `bakin plugins remove` BEFORE Bakin tears down the plugin's
      * own bookkeeping (registry rows, settings JSON, plugin dir, etc.).

package/_internal/core/routing/define.d.ts

@@ -36,6 +36,12 @@ export interface DefinePluginInput {
     onReady?(): void | Promise<void>;
     onShutdown?(): void | Promise<void>;
     onSettingsChange?(settings: Record<string, unknown>): void | Promise<void>;
+    validateSettings?(value: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    };
     onUninstall?(ctx: any): void | Promise<void>;
     beforeUninstall?(ctx: any): void | Promise<void>;
     settingsSchema?: PluginSettingsSchema;

package/_internal/host/ui/resize.d.ts

@@ -0,0 +1,2 @@
+export { ResizeHandle } from '../../ui/behaviors/resize-handle';
+export { usePersistedLeadingEdgeResize } from '../../ui/behaviors/use-persisted-leading-edge-resize';

package/_internal/ui/{conversation → behaviors}/resize-handle.d.ts

@@ -1,4 +1,4 @@
-import type { PersistedResizeHandleProps } from '../behaviors/use-persisted-leading-edge-resize';
+import type { PersistedResizeHandleProps } from './use-persisted-leading-edge-resize';
 /** Props for the shared grab-bar chrome over `usePersistedLeadingEdgeResize`. */
 export interface ResizeHandleProps {
     /** Direction of the grab bar itself: `horizontal` resizes height, `vertical` resizes width. */
@@ -6,8 +6,10 @@ export interface ResizeHandleProps {
     handleProps: PersistedResizeHandleProps;
     /** Accessible name for the separator, e.g. "Resize message input". */
     label: string;
+    /** Keep a quiet grab bar visible for panel and drawer boundaries. */
+    visibleAtRest?: boolean;
     /** Site-owned layout, positioning, and cursor classes. */
     className?: string;
 }
 /** One resize grab bar; every consumer keeps its own positioning and cursor rules. */
-export declare function ResizeHandle({ orientation, handleProps, label, className }: ResizeHandleProps): import("react/jsx-runtime").JSX.Element;
+export declare function ResizeHandle({ orientation, handleProps, label, visibleAtRest, className }: ResizeHandleProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/behaviors/use-persisted-leading-edge-resize.d.ts

@@ -15,10 +15,12 @@ export interface PersistedResizeHandleProps {
     'aria-valuemin': number;
     'aria-valuemax': number;
     'aria-valuenow': number;
+    'data-resizing': boolean;
     onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
     onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
     onPointerUp: (event: PointerEvent<HTMLDivElement>) => void;
     onPointerCancel: (event: PointerEvent<HTMLDivElement>) => void;
+    onLostPointerCapture: (event: PointerEvent<HTMLDivElement>) => void;
     onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
 }
 /** Private shared mechanics for a pane resized from its leading edge. */

package/_internal/ui/charts/composition-bar.d.ts

@@ -12,8 +12,13 @@ export interface CompositionBarProps {
     data: readonly CompositionBarSegment[];
     /** Accessible name for the strip and basis for its legend name. */
     label: string;
-    /** `inline` fits inside a metric row; `default` leaves room for the legend. */
-    size?: 'inline' | 'default';
+    /**
+     * `inline` fits inside a metric row; `default` leaves room for the legend;
+     * `large` is the tall strip for a headline part-to-whole — each segment
+     * carries its label and value inside it (clipped when the segment is too
+     * narrow; the legend and the accessible summary always carry them all).
+     */
+    size?: 'inline' | 'default' | 'large';
     /**
      * List legend with exact values below the strip. Defaults to true at size
      * `default`; forced off at size `inline`, where the accessible summary

package/_internal/ui/conversation/conversation-panel.d.ts

@@ -1,6 +1,6 @@
-import { type ReactNode } from 'react';
+import { type ReactNode, type Ref } from 'react';
 import { type AgentTurnProps, type ConversationAgent, type ConversationAvatarRenderer, type ConversationTextRenderer } from './agent-turn';
-import { type ComposerAttachments } from './composer';
+import { type ComposerAttachments, type ComposerHandle } from './composer';
 import { type ConversationProps } from './conversation';
 import { type ConversationChunk, type ConversationMessage } from './fold';
 import { type ConversationQueuedItem } from './queued-message-list';
@@ -39,6 +39,8 @@ export interface ConversationPanelProps {
     inputLabel?: string;
     /** Focus the composer when this panel mounts. Disable for panels embedded below page content. */
     autoFocus?: boolean;
+    /** Existing composer draft/focus handle; null while read-only or unmounted. */
+    composerHandleRef?: Ref<ComposerHandle>;
     emptyState?: ReactNode;
     maxLength?: number;
     attachments?: ComposerAttachments;
@@ -56,4 +58,4 @@ export interface ConversationPanelProps {
  * Focused conversation composition for embedded sessions. The consumer owns
  * transport, persistence, routing, identity lookup, and attachment mutation.
  */
-export declare function ConversationPanel({ messages, liveChunks, streaming, agent, resolveAgent, agentControl, onSend, onAbort, onRetry, renderAvatar, renderText, renderAttachment, transformText, formatToolSummary, storageKey, title, showHeader, fitParent, chrome, readOnly, readOnlyNotice, placeholder, inputLabel, autoFocus, emptyState, maxLength, attachments, queueMode, queuedItems, onRemoveQueued, defaultHeight, minHeight, maxHeight, className, }: ConversationPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConversationPanel({ messages, liveChunks, streaming, agent, resolveAgent, agentControl, onSend, onAbort, onRetry, renderAvatar, renderText, renderAttachment, transformText, formatToolSummary, storageKey, title, showHeader, fitParent, chrome, readOnly, readOnlyNotice, placeholder, inputLabel, autoFocus, composerHandleRef, emptyState, maxLength, attachments, queueMode, queuedItems, onRemoveQueued, defaultHeight, minHeight, maxHeight, className, }: ConversationPanelProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/conversation/conversation.d.ts

@@ -9,6 +9,8 @@ export interface ConversationProps {
     turns: readonly ConversationTurn[];
     /** Document scroll is the product default; contained is for an explicitly bounded standalone surface. */
     mode?: ConversationMode;
+    /** Distinguishes contained transcript regions when a page has multiple sessions. */
+    ariaLabel?: string;
     /** Fallback identity for agent turns. */
     agent?: ConversationAgent;
     /** Resolve identity when a turn carries its own agent id. */
@@ -32,4 +34,4 @@ export interface ConversationProps {
  * It owns scrolling only in explicit `contained` mode; page recipes should
  * keep this in document mode and let `PageTimeline` own the log.
  */
-export declare function Conversation({ turns, mode, agent, resolveAgent, emptyState, onRetry, onOpenCall, renderAvatar, renderText, renderAttachment, transformText, formatToolSummary, turnUsage, liveOutEstimate, className, }: ConversationProps): import("react/jsx-runtime").JSX.Element;
+export declare function Conversation({ turns, mode, ariaLabel, agent, resolveAgent, emptyState, onRetry, onOpenCall, renderAvatar, renderText, renderAttachment, transformText, formatToolSummary, turnUsage, liveOutEstimate, className, }: ConversationProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/forms/field.d.ts

@@ -1,5 +1,6 @@
 import { Field as FieldPrimitive } from '@base-ui/react/field';
 import type { ReactNode } from 'react';
+import { type ControlSize, type ControlVariant } from '../primitives/control-styles';
 export type FieldOrientation = 'vertical' | 'horizontal';
 export type FieldProps = Omit<FieldPrimitive.Root.Props, 'className'> & {
     className?: FieldPrimitive.Root.Props['className'];
@@ -17,9 +18,13 @@ export type FieldDescriptionProps = FieldPrimitive.Description.Props;
 export declare function FieldDescription({ className, ...props }: FieldDescriptionProps): import("react/jsx-runtime").JSX.Element;
 export type FieldErrorProps = FieldPrimitive.Error.Props;
 export declare function FieldError({ className, role, ...props }: FieldErrorProps): import("react/jsx-runtime").JSX.Element;
-export type FieldControlProps = FieldPrimitive.Control.Props;
+export type FieldControlProps = Omit<FieldPrimitive.Control.Props, 'size'> & {
+    size?: ControlSize;
+    variant?: ControlVariant;
+    htmlSize?: number;
+};
 /**
  * A styled input by default. Pass `render={<Textarea />}` to associate native
  * controls that do not participate in Base UI's field context themselves.
  */
-export declare function FieldControl({ className, render, ...props }: FieldControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function FieldControl({ className, render, size, variant, htmlSize, ...props }: FieldControlProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/index.d.ts

@@ -53,6 +53,7 @@ export type { CollapsibleContentProps, CollapsibleProps, CollapsibleTriggerProps
 export { Label } from './primitives/label';
 export type { LabelProps } from './primitives/label';
 export { Input } from './primitives/input';
+export type { ControlSize, ControlVariant } from './primitives/control-styles';
 export type { InputProps } from './primitives/input';
 export { Textarea } from './primitives/textarea';
 export type { TextareaProps } from './primitives/textarea';
@@ -84,3 +85,5 @@ export type { CommandDialogProps, CommandEmptyProps, CommandGroupProps, CommandI
 export type { InputGroupAddonAlign, InputGroupAddonProps, InputGroupButtonProps, InputGroupButtonSize, InputGroupInputProps, InputGroupProps, InputGroupTextProps, InputGroupTextareaProps, } from './primitives/input-group';
 export { DrawerSection } from './patterns/drawer-section';
 export type { DrawerSectionHeadingLevel, DrawerSectionProps, } from './patterns/drawer-section';
+export { Combobox, ComboboxControl, ComboboxInput, ComboboxTrigger, ComboboxClear, ComboboxValue, ComboboxContent, ComboboxList, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxEmpty, ComboboxStatus, ComboboxChips, ComboboxChip, ComboboxChipRemove } from './primitives/combobox';
+export type { ComboboxProps, ComboboxControlProps, ComboboxInputProps, ComboboxTriggerProps, ComboboxClearProps, ComboboxValueProps, ComboboxContentProps, ComboboxListProps, ComboboxItemProps, ComboboxGroupProps, ComboboxLabelProps, ComboboxEmptyProps, ComboboxStatusProps, ComboboxChipsProps, ComboboxChipProps, ComboboxChipRemoveProps } from './primitives/combobox';

package/_internal/ui/patterns/data-table.d.ts

@@ -114,6 +114,12 @@ export interface DataTableProps<Row, F extends string = string> {
     renderTableRow?: (row: Row) => ReactNode;
     /** Extra props merged onto each default `<tr>` (row click handlers, data attributes). */
     rowProps?: (row: Row) => WithDataAttributes<ComponentPropsWithoutRef<'tr'>>;
+    /**
+     * Kit-owned selected treatment for a row (the ListRow `selected` tint on
+     * both renders, `data-selected` on the wide `<tr>`): a deep-linked or
+     * currently chosen record. Consumers manage the state.
+     */
+    rowSelected?: (row: Row) => boolean;
     /**
      * Kit-owned whole-row activation: pointer click plus Enter/Space with a
      * real focus ring on the wide render, and the ListRow interactive overlay
@@ -147,5 +153,5 @@ export interface DataTableProps<Row, F extends string = string> {
  * by not declaring `sortValue`, not by hiding the affordance). `Table*` stays public as the D9-gated escape hatch
  * for tables this configuration cannot express.
  */
-export declare function DataTable<Row, F extends string = string>({ columns, rows: inputRows, rowKey, label, sort: controlledSort, onSortChange, defaultSort, pagination, collapseBelow, listVariant, renderTableRow, rowProps, renderRow, onRowActivate, rowActivateLabel, tableProps, className, }: DataTableProps<Row, F>): import("react/jsx-runtime").JSX.Element;
+export declare function DataTable<Row, F extends string = string>({ columns, rows: inputRows, rowKey, label, sort: controlledSort, onSortChange, defaultSort, pagination, collapseBelow, listVariant, renderTableRow, rowProps, rowSelected, renderRow, onRowActivate, rowActivateLabel, tableProps, className, }: DataTableProps<Row, F>): import("react/jsx-runtime").JSX.Element;
 export {};

package/_internal/ui/patterns/guide-card.d.ts

@@ -0,0 +1,33 @@
+import type { ComponentType, ReactNode } from 'react';
+export interface GuideCardPoint {
+    /** Short overline-style heading for one consideration. */
+    heading: string;
+    /** One or two sentences a new user can act on. */
+    body: ReactNode;
+}
+export type GuideCardHeadingLevel = 2 | 3;
+export interface GuideCardProps {
+    /** Optional icon drawn in a tinted gutter that indents the whole card body. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    title: ReactNode;
+    /** What this surface controls and why it exists — always visible. */
+    lead: ReactNode;
+    /** The things worth weighing before changing anything; rendered as a railed strip. */
+    points?: ReadonlyArray<GuideCardPoint>;
+    /** Page-level actions that belong to this surface (kept one visual weight below the page header's). */
+    actions?: ReactNode;
+    /** Document-outline level for the title; the card sits directly under a page title by default. */
+    headingLevel?: GuideCardHeadingLevel;
+    className?: string;
+}
+/**
+ * The plain-words opener for a settings surface: what it controls, why it
+ * exists, and what to think about before touching it. One icon gutter
+ * indents title, lead and the points together; the points read as a railed
+ * strip (the stat-strip rhythm with prose in place of numbers) that stacks
+ * on narrow containers. Prose stays prose — the accessible outline gets one
+ * heading for the card and an overline per point.
+ */
+export declare function GuideCard({ icon: Icon, title, lead, points, actions, headingLevel, className, }: GuideCardProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/patterns/index.d.ts

@@ -67,6 +67,8 @@ export { StatTile } from './stat-tile';
 export type { StatTileProgress, StatTileProgressTone, StatTileProps, StatTileVariant, } from './stat-tile';
 export { StatGroup } from './stat-group';
 export type { StatGroupProps } from './stat-group';
+export { GuideCard } from './guide-card';
+export type { GuideCardHeadingLevel, GuideCardPoint, GuideCardProps } from './guide-card';
 export { DataTable } from './data-table';
 export type { DataTableAlign, DataTableCollapse, DataTableColumn, DataTableNarrowRole, DataTableProps, DataTableSort, } from './data-table';
 export { Timeline, TimelineEntry } from './timeline';

package/_internal/ui/patterns/search-input.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { Input } from '../primitives/input';
-type NativeSearchInputProps = Omit<React.ComponentPropsWithoutRef<typeof Input>, 'aria-label' | 'children' | 'className' | 'defaultValue' | 'onChange' | 'size' | 'type' | 'value'>;
+type NativeSearchInputProps = Omit<React.ComponentPropsWithoutRef<typeof Input>, 'aria-label' | 'children' | 'className' | 'defaultValue' | 'onChange' | 'size' | 'variant' | 'type' | 'value'>;
 export interface SearchInputProps extends NativeSearchInputProps {
     /** Durable accessible name; the placeholder is only a visual hint. */
     label: string;

package/_internal/ui/primitives/card.d.ts

@@ -29,7 +29,15 @@ export declare function Card({ className, size, tone, selected, orientation, int
  */
 export declare function CardMedia({ className, ...props }: ComponentProps<'div'>): import("react/jsx-runtime").JSX.Element;
 export declare function CardHeader({ className, ...props }: ComponentProps<'div'>): import("react/jsx-runtime").JSX.Element;
-export declare function CardTitle({ className, ...props }: ComponentProps<'div'>): import("react/jsx-runtime").JSX.Element;
+export type CardTitleElement = 'div' | 'h2' | 'h3' | 'h4';
+/**
+ * The card's title. `as` renders it as a real heading when the card is a
+ * section of the page (a settings lane, a guide) so the document outline
+ * and heading navigation reach it; the visual treatment is the same.
+ */
+export declare function CardTitle({ as: Comp, className, ...props }: ComponentProps<'div'> & {
+    as?: CardTitleElement;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function CardDescription({ className, ...props }: ComponentProps<'div'>): import("react/jsx-runtime").JSX.Element;
 export type CardActionReveal = 'always' | 'hover';
 export declare function CardAction({ className, reveal, ...props }: ComponentProps<'div'> & {

package/_internal/ui/primitives/combobox.d.ts

@@ -0,0 +1,40 @@
+import { Combobox as ComboboxPrimitive } from '@base-ui/react/combobox';
+import { type ControlSize, type ControlVariant } from './control-styles';
+export type ComboboxProps<Value, Multiple extends boolean | undefined = false> = ComboboxPrimitive.Root.Props<Value, Multiple>;
+export declare const Combobox: typeof ComboboxPrimitive.Root;
+export type ComboboxValueProps = ComboboxPrimitive.Value.Props;
+export declare const ComboboxValue: typeof ComboboxPrimitive.Value;
+export type ComboboxControlProps = ComboboxPrimitive.InputGroup.Props & {
+    size?: ControlSize;
+    variant?: ControlVariant;
+    width?: 'full' | 'auto';
+};
+export declare function ComboboxControl({ size, variant, width, className, ...props }: ComboboxControlProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxInputProps = Omit<ComboboxPrimitive.Input.Props, 'size'> & {
+    htmlSize?: number;
+};
+export declare function ComboboxInput({ className, htmlSize, ...props }: ComboboxInputProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxTriggerProps = ComboboxPrimitive.Trigger.Props;
+export declare function ComboboxTrigger({ className, children, ...props }: ComboboxTriggerProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxClearProps = ComboboxPrimitive.Clear.Props;
+export declare function ComboboxClear({ className, children, ...props }: ComboboxClearProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxContentProps = ComboboxPrimitive.Popup.Props & Pick<ComboboxPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset'>;
+export declare function ComboboxContent({ className, side, sideOffset, align, alignOffset, ...props }: ComboboxContentProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxListProps = ComboboxPrimitive.List.Props;
+export declare function ComboboxList({ className, ...props }: ComboboxListProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxItemProps = ComboboxPrimitive.Item.Props;
+export declare function ComboboxItem({ className, children, ...props }: ComboboxItemProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxGroupProps = ComboboxPrimitive.Group.Props;
+export declare function ComboboxGroup({ className, ...props }: ComboboxGroupProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxLabelProps = ComboboxPrimitive.GroupLabel.Props;
+export declare function ComboboxLabel({ className, ...props }: ComboboxLabelProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxEmptyProps = ComboboxPrimitive.Empty.Props;
+export declare function ComboboxEmpty({ className, ...props }: ComboboxEmptyProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxStatusProps = ComboboxPrimitive.Status.Props;
+export declare function ComboboxStatus({ className, ...props }: ComboboxStatusProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxChipsProps = ComboboxPrimitive.Chips.Props;
+export declare function ComboboxChips({ className, ...props }: ComboboxChipsProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxChipProps = ComboboxPrimitive.Chip.Props;
+export declare function ComboboxChip({ className, ...props }: ComboboxChipProps): import("react/jsx-runtime").JSX.Element;
+export type ComboboxChipRemoveProps = ComboboxPrimitive.ChipRemove.Props;
+export declare function ComboboxChipRemove({ className, children, ...props }: ComboboxChipRemoveProps): import("react/jsx-runtime").JSX.Element;

package/_internal/ui/primitives/control-styles.d.ts

@@ -0,0 +1,10 @@
+export type ControlSize = 'sm' | 'md' | 'lg';
+export type ControlVariant = 'outlined' | 'filled' | 'ghost';
+/** Private presentation shared by field shells, never by Form/Field providers. */
+export declare const controlStyles: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    variant?: "ghost" | "outlined" | "filled" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const controlHeight: Record<ControlSize, string>;
+/** Group focus follows the editable control; addon buttons keep their own ring. */
+export declare const controlGroupFocus = "has-[:is(input,textarea):focus-visible]:outline-solid has-[:is(input,textarea):focus-visible]:outline-2 has-[:is(input,textarea):focus-visible]:outline-offset-2 has-[:is(input,textarea):focus-visible]:outline-bakin-focus-ring";

package/_internal/ui/primitives/input-group.d.ts

@@ -1,9 +1,13 @@
-import type { ComponentProps } from 'react';
+import { type ComponentProps } from 'react';
 import type { ButtonProps, ButtonVariant, LegacyButtonVariant } from './button';
+import { type ControlSize, type ControlVariant } from './control-styles';
 import type { InputProps } from './input';
 import type { TextareaProps } from './textarea';
-export type InputGroupProps = ComponentProps<'div'>;
-export declare function InputGroup({ className, ...props }: InputGroupProps): import("react/jsx-runtime").JSX.Element;
+export type InputGroupProps = ComponentProps<'div'> & {
+    size?: ControlSize;
+    variant?: ControlVariant;
+};
+export declare function InputGroup({ className, size, variant, ...props }: InputGroupProps): import("react/jsx-runtime").JSX.Element;
 export type InputGroupAddonAlign = 'inline-start' | 'inline-end' | 'block-start' | 'block-end';
 export type InputGroupAddonProps = ComponentProps<'div'> & {
     align?: InputGroupAddonAlign;
@@ -18,7 +22,9 @@ export type InputGroupButtonProps = Omit<ButtonProps, 'size' | 'type' | 'variant
 export declare function InputGroupButton({ className, type, variant, size, ...props }: InputGroupButtonProps): import("react/jsx-runtime").JSX.Element;
 export type InputGroupTextProps = ComponentProps<'span'>;
 export declare function InputGroupText({ className, ...props }: InputGroupTextProps): import("react/jsx-runtime").JSX.Element;
-export type InputGroupInputProps = InputProps;
+export type InputGroupInputProps = Omit<InputProps, 'size' | 'variant'>;
 export declare function InputGroupInput({ className, ...props }: InputGroupInputProps): import("react/jsx-runtime").JSX.Element;
-export type InputGroupTextareaProps = TextareaProps;
+type WithoutAppearance<T> = T extends unknown ? Omit<T, 'size' | 'variant'> : never;
+export type InputGroupTextareaProps = WithoutAppearance<TextareaProps>;
 export declare function InputGroupTextarea({ className, ...props }: InputGroupTextareaProps): import("react/jsx-runtime").JSX.Element;
+export {};