@makinbakin/sdk 0.0.1-rc.26 → 0.0.1-rc.28

package/README.md

@@ -96,16 +96,260 @@ The public npm package exposes these sub-paths:
 | Import path              | What it exposes                              |
 | ------------------------ | -------------------------------------------- |
 | `@makinbakin/sdk` | Plugin registration, route helpers, top-level exports |
-| `@makinbakin/sdk/ui` | Base UI components |
+| `@makinbakin/sdk/ui` | Supported Bakin UI primitives and semantic style helpers |
+| `@makinbakin/sdk/layout` | Canonical page and responsive composition |
+| `@makinbakin/sdk/patterns` | Reusable application-aware UI patterns |
+| `@makinbakin/sdk/charts` | Isolated data-visualization components |
+| `@makinbakin/sdk/conversation` | Isolated conversation UI and models |
+| `@makinbakin/sdk/content` | Opt-in rich content rendering and editing |
 | `@makinbakin/sdk/hooks` | Shared React hooks |
-| `@makinbakin/sdk/components` | Higher-level shell components |
+| `@makinbakin/sdk/components` | Migration-only legacy component barrel |
 | `@makinbakin/sdk/slots` | Slot runtime and provider |
 | `@makinbakin/sdk/types` | TypeScript contract types |
 | `@makinbakin/sdk/utils` | Shared utilities |
 | `@makinbakin/sdk/metadata` | Docs-aware contract metadata helpers |
 | `@makinbakin/sdk/routing` | Typed declarative route helpers |
+| `@makinbakin/sdk/navigation` | Browser links, URL state, history, and dirty-exit guards |
+| `@makinbakin/sdk/testing/ui` | Deterministic browser fixture host for plugin pages and slots |
+| `@makinbakin/sdk/testing/ui/conformance` | Plugin UI test config, reports, CSS gate, and runner |
+| `@makinbakin/sdk/styles.css` | Canonical compiled design-system stylesheet |
 
-Use `@makinbakin/sdk/*` imports for external plugin code.
+Use the focused entrypoints for new plugin UI and browser navigation. Existing
+`@makinbakin/sdk/components` consumers migrate as their replacement exports
+land; do not add new dependencies on that legacy barrel.
+
+## Browser UI fixtures
+
+Use `PluginUiFixtureHost` from `@makinbakin/sdk/testing/ui` to exercise a
+plugin's real client registration without a Bakin account, host database, or
+live service. The browser-only entrypoint mounts registered pages and slots
+through the production route matcher, ownership wrappers, and SDK portal
+roots. It also provides deterministic time, random values, UUIDs, theme,
+motion preferences, routes, and explicit network responses.
+
+```tsx
+import '@makinbakin/sdk/styles.css'
+import { PluginUiFixtureHost } from '@makinbakin/sdk/testing/ui'
+import { pluginRegistration } from './client-registration'
+
+export function PluginPreview() {
+  return (
+    <PluginUiFixtureHost
+      registrations={[pluginRegistration]}
+      fixture={{
+        fixedNow: '2026-01-15T12:00:00.000Z',
+        route: '/bookmarks?tag=release',
+        randomSeed: 'bookmarks-preview',
+        colorScheme: 'dark',
+        reducedMotion: true,
+        viewport: 'desktop',
+        network: [{ path: '/api/plugins/bookmarks', status: 200, json: { bookmarks: [] } }],
+      }}
+      slots={[{ name: 'home-widget', label: 'Home widget contributions' }]}
+    />
+  )
+}
+```
+
+Import the canonical stylesheet exactly once at the preview root; installed
+plugin clients still leave stylesheet loading to Bakin. Apply the matching
+`PLUGIN_UI_VIEWPORTS.desktop` or `.mobile` dimensions in the browser runner—the
+fixture's viewport field freezes responsive preferences and records intent but
+cannot resize the browser from inside React. Unlisted requests fail loudly so
+fixtures cannot silently depend on a developer machine or user state.
+
+Add the one-command conformance suite to a client-bearing plugin package:
+
+```json
+{
+  "scripts": { "test:ui": "bakin-plugin-test-ui" },
+  "devDependencies": {
+    "axe-core": "^4.12.0",
+    "playwright": "^1.60.0"
+  }
+}
+```
+
+Install the browser once with `bunx playwright install chromium`.
+
+Then define the package-root fixture in `bakin.ui-test.ts`:
+
+```ts
+import { definePluginUiConformance } from '@makinbakin/sdk/testing/ui/conformance'
+
+export default definePluginUiConformance({
+  pluginId: 'bookmarks',
+  fixtureEntry: './tests/ui.fixture.tsx',
+})
+```
+
+`bun run test:ui` builds that real fixture, verifies CSS ownership and exactly
+one canonical stylesheet import, then runs axe, keyboard/focus, overflow, and
+browser-error checks in 1440×900 and 320×800 Chromium viewports. It writes
+machine-readable JSON, a self-contained HTML report, and both screenshots to
+`test-results/bakin-ui/`. CSS scope and stylesheet identity are reusable
+package/install blockers; broader browser findings gate CI or release without
+changing runtime installation policy.
+
+The prerelease migration surface is machine-inventoried in
+[`design-system/public-api.json`](https://github.com/markhayden/bakin/blob/main/design-system/public-api.json).
+Any value or type addition, removal, or entrypoint ownership change requires an
+explicit inventory review. The legacy components symbol set is frozen: it may
+shrink during migration but must not receive new exports.
+
+Action and status UI starts with `Button`, `Badge`, `Alert`, and `Progress`.
+Choose their semantic `variant`, `tone`, and `size` props instead of recreating
+colors or dimensions in plugin CSS. The `buttonVariants` and `badgeVariants`
+helpers are supported when a link or render integration needs the same visual
+treatment while preserving its native element semantics.
+
+Routine forms compose `Field`, `FieldLabel`, `FieldDescription`, `FieldError`,
+and SDK controls inside `Form`. Use `Fieldset` for related choices and finish
+with `FormActions` plus `SubmitButton`; the form's `busy` prop marks submission
+and prevents duplicate saves. Form-state libraries may manage values and dirty
+state, but the SDK components continue to own labels, errors, spacing, and
+actions.
+
+Data-driven surfaces use `SystemState` for initial-empty, filtered no-results,
+loading, recoverable or terminal error, and permission-denied states. A
+no-results state requires a clear/adjust action; a recoverable error requires a
+recovery action. Use `Banner` for persistent page context. Plugins call
+`toast()` from `@makinbakin/sdk/hooks` for transient outcomes and leave the
+shell-owned `ToastRegion` to Bakin.
+
+Routed indexes and record pages compose from `@makinbakin/sdk/patterns`.
+`PageHeader` owns the single page heading and its responsive controls/action
+order. Use its `controls` slot for the canonical compact `SearchInput` and peer
+view navigation when they belong beside the primary action; the reserved
+search slot expands without repacking the desktop header row. Longer queries
+remain intact behind an ellipsis, and the pattern supplies its own accessible
+clear action instead of a browser-dependent native cancel control.
+`Page` owns the page canvas (width measure, density, scroll ownership);
+`PageControls` and `PageBody` keep query controls separate from the named
+result/state boundary, and `PageBody layout="aside"` composes a primary flow
+with an optional named `PageAside` that reflows below it. The recipes do not own
+data or routing: keep filters, search, tabs, pagination, and overlays in the
+existing `useQueryState` contract, and use `PluginLink` for client-routed page
+navigation. The host retains the `main` landmark and vertical page scroll.
+
+Settings and overview pages also compose the same archetype. A multi-category
+settings surface keeps a consumer-owned named category `nav` beside a
+`PageBody` region so the active form owns only its own feedback and
+replacement-state boundary. A dashboard is a named `PageBody gap="page"`
+overview canvas that consumers compose with `Section`, `Stack`, and `Grid`.
+Keep settings categories and dashboard view state in the existing query-state
+contract. Values, validation, dirty state, saves, telemetry, and domain actions
+remain consumer owned; avoid equal-weight card walls and nested page scrollers.
+
+Conversation pages use the default `Page` document scroll. Choose
+`scroll="contained"` only inside an explicitly bounded parent; then
+`PageTimeline` is the single named log scroller and the composer
+remains outside it. Render folded turns with `Conversation` from
+`@makinbakin/sdk/conversation`; its default `document` mode avoids creating a
+second scroller inside the page recipe. `mode="contained"` is reserved for a
+standalone conversation with an explicit height boundary. `ConversationEmptyState`
+renders starter suggestions only when their callback is supplied. Put `Composer`
+inside `PageComposer`; its stable `storageKey` scopes browser-local
+draft/history/resize preferences, while the consumer owns routing, upload requests,
+object-URL cleanup, persistence, and send mutations. Attachment `acceptedTypes`
+apply consistently to picker, paste, and drop. Pending uploads hold send, `busy`
+keeps typing live, and a stop control appears only when `onAbort` exists.
+`InspectorPanel` supplies named header/content/footer hierarchy beside a canvas
+or inside `Drawer`. Transport, server persistence, rich text, routing, selection,
+drawer focus, and domain mutations remain consumer owned.
+
+Workflow and action workspaces use `Page density="compact"` with a named
+`PageControls as="toolbar"`, a bounded `PageCanvas`, and a consumer-owned
+named actions group.
+Vertical is the default graph orientation; horizontal is an explicit option.
+The recipe supplies hierarchy and a bounded overflow region without importing
+React Flow or owning nodes, edges, selection, graph commands, persistence,
+drawers, or URL state. Use the existing routing contract for linkable selected
+nodes and view modes, and provide named non-drag actions for required graph
+operations.
+
+Consequential actions and staged drafts use `ConfirmDialog`, `DangerZone`,
+`SaveBar`, and `UnsavedChangesDialog` from `@makinbakin/sdk/patterns`.
+Consumers retain mutation, dirty, persistence, retry, and routing behavior;
+the patterns provide typed confirmation, busy/error presentation, responsive
+action placement, and the save/discard/stay decision. Keep normal links and
+query-only state changes on the existing SDK router contract.
+
+Filtering and view navigation use `FacetFilter`, `AgentFilter`,
+`SegmentedControl`, and `SortableHead` from the same focused patterns
+entrypoint, and page-section tabs use `Tabs` with
+`<TabsList variant="underline">` from `@makinbakin/sdk/ui`. These components
+own searchable counts, clearing, keyboard selection, linked-tab semantics,
+long-label overflow, and table sort semantics. Consumers still own values and routing: connect linkable filters and
+views to `useQueryArrayState` or `useQueryState` from
+`@makinbakin/sdk/hooks`. The public `AgentFilter` accepts presentation-ready
+options; host adapters may add app-owned agent metadata and avatars.
+
+Agent identity and assignment use the same focused patterns entrypoint.
+`AgentAvatar`, `AgentStatus`, and `AgentSelect` accept presentation-ready
+identity, status, agent, and team options; they never fetch the registry or
+team API. Status remains visible in text, and consumers keep assignment state,
+heartbeat timing, URL state, and persistence. Existing official surfaces may
+continue through the migration-only components adapters until fleet migration.
+
+Asset, model, and color choices use `AssetPicker`, `ModelSelect`, and
+`ColorPicker` from the focused patterns entrypoint. `AssetPicker` supports a
+controlled library dialog plus inline grid or list composition with exact
+loading, error, empty, and filtered states. Consumers own asset endpoints,
+uploads, eligibility, attachment mutations, and route state. `ModelSelect`
+groups presentation-ready catalog options by provider and exports the stable
+`DEFAULT_MODEL_VALUE` sentinel; consumers own catalog loading and persistence.
+`ColorPicker` provides labelled radio semantics and enabled-option keyboard
+movement while consumers own palette values and saving. Existing official
+surfaces may remain on the migration-only components adapters until their
+incremental migration.
+
+Schema-driven plugin forms use `PluginSettingsRenderer` from
+`@makinbakin/sdk/patterns`; the settings schema and field types are co-exported
+from that entrypoint. The renderer owns defaults, draft editing, validation,
+list-row controls, and accessible feedback placement. Consumers own loading,
+persistence, retry, route state, and the durable `busy`/`feedback` values that
+describe a save result. Official surfaces may continue through the app-aware
+components adapter until fleet migration.
+
+Compact task and workflow output uses `TurnOutputView`, `TurnToolChip`, and
+`foldTurnChunks` from `@makinbakin/sdk/conversation`. They share the canonical
+conversation fold and tool-row semantics, keep wide code output locally
+scrollable, and expose typed live, terminal, and error evidence. Markdown is
+plain safe text by default; consumers that need rich content provide
+`renderText`, normally with `MarkdownContent` from the opt-in
+`@makinbakin/sdk/content` entrypoint. The compatibility adapter retains the
+host's existing rich-Markdown behavior during migration.
+
+Compact display patterns use `StatusBadge` and `StatTile`. Status labels carry
+meaning without color, while optional icons remain decorative. Focused status
+tones use `attention` and `danger`; the legacy components adapter maps the old
+`warning` and `destructive` names during migration. `StatTile` is low-chrome by
+default, offers an explicit bounded `surface` variant, and exposes labelled
+progress values to assistive technology.
+
+## Stylesheet
+
+Bakin loads one shared copy of `@makinbakin/sdk/styles.css` for the host and all
+installed plugins. Do not import it from a plugin client entry or copy its
+contents into plugin-owned CSS.
+
+Standalone browser previews and test harnesses do not have the Bakin host, so
+they import the public artifact once at their application root:
+
+```ts
+import '@makinbakin/sdk/styles.css'
+```
+
+That package export is the exact compiled stylesheet used by the host and the
+public component catalog. Plugin-owned CSS remains for domain-specific styling
+and should be scoped to the plugin root.
+
+SDK dialogs, sheets, popovers, menus, selects, and tooltips automatically keep
+the host-injected plugin identity when their content is portalled. Plugin code
+uses the normal primitive APIs without adding ownership wrappers or custom
+portal containers for styling. Toast presentation remains host-owned; plugins
+request toasts through the SDK instead of mounting a toast region.
 
 ## Repository
 

package/_internal/app/components/agent-avatar.d.ts

@@ -7,5 +7,6 @@ interface AgentAvatarProps {
     status?: StatusValue;
     className?: string;
 }
-export declare function AgentAvatar({ agentId, size, showStatus, status, className, }: AgentAvatarProps): import("react/jsx-runtime").JSX.Element;
+/** Compatibility adapter that supplies registered-agent identity to the public presentation pattern. */
+export declare function AgentAvatar({ agentId, size, showStatus, status, className }: AgentAvatarProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/_internal/app/components/conversation/fold.d.ts

@@ -1,129 +1,3 @@
-/**
- * foldConversation — THE single folding engine for conversation surfaces.
- *
- * Consumes persisted `ConversationMessage` rows plus the in-flight turn's
- * raw `RuntimeChatChunk`s and produces the renderable turn model
- * (`ConversationTurn[]`). Every conversational surface (chat plugin,
- * embedded brainstorm panels, task/workflow turn output) folds through
- * here — never hand-roll chunk heuristics in a component.
- *
- * Semantics (pinned by tests/sdk/conversation-fold.test.ts):
- * - Item ORDER inside a turn is preserved: text and tool-activity items
- *   interleave in arrival order. Consecutive tool chunks group into ONE
- *   activity item; a text chunk closes the group and later tools start a
- *   new one.
- * - Tool call/result pairs match by callId ACROSS group boundaries (a
- *   result settles its original call even if text arrived in between).
- *   A callId-less result closes the most recent RUNNING call of the same
- *   tool; an orphan result settles as its own call.
- * - Consecutive same-format text chunks coalesce; a format change starts
- *   a new text item.
- * - The newest status chunk is the streaming label. `done` → complete,
- *   `error` → error (with a typed error item). Aborted turns come from
- *   persisted `aborted` rows — the stream itself ends aborts with a clean
- *   `done` (runtime contract).
- */
-import type { ChatChunk as RuntimeChatChunk, ChatTextFormat } from '../../../core/adapters/runtime';
-/** Attachment as displayed in a conversation (URL-addressed, not path). */
-export interface DisplayAttachment {
-    name: string;
-    mimeType: string;
-    url: string;
-}
-/**
- * One persisted conversation row — the kit's storable message shape.
- * The chat plugin's transcript rows serialize to exactly this (plus its
- * own storage concerns); embedded surfaces map their local shapes onto it.
- * `turnId` groups the rows of one agent turn; rows without it (legacy)
- * group by adjacency between user rows.
- */
-export type ConversationMessage = {
-    kind: 'user';
-    ts: string;
-    content: string;
-    attachments?: DisplayAttachment[];
-} | {
-    kind: 'assistant';
-    ts: string;
-    turnId?: string;
-    agentId?: string;
-    content: string;
-} | {
-    kind: 'tool';
-    ts: string;
-    turnId?: string;
-    agentId?: string;
-    callId?: string;
-    toolName: string;
-    status?: 'running' | 'completed' | 'failed' | string;
-    summary?: string;
-    inputPreview?: string;
-    outputPreview?: string;
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-} | {
-    kind: 'error';
-    ts: string;
-    turnId?: string;
-    message: string;
-    errorKind?: string;
-} | {
-    kind: 'aborted';
-    ts: string;
-    turnId?: string;
-};
-/** One tool invocation inside an activity group. */
-export interface ConversationToolCall {
-    /** Stable render key (callId when present). */
-    key: string;
-    callId?: string;
-    toolName: string;
-    status: 'running' | 'completed' | 'failed';
-    summary?: string;
-    inputPreview?: string;
-    outputPreview?: string;
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-}
-export type TurnItem = {
-    type: 'text';
-    format: ChatTextFormat;
-    content: string;
-} | {
-    type: 'activity';
-    calls: ConversationToolCall[];
-} | {
-    type: 'error';
-    message: string;
-    errorKind?: string;
-};
-export type TurnStatus = 'streaming' | 'complete' | 'error' | 'aborted';
-export type ConversationTurn = {
-    kind: 'user';
-    key: string;
-    ts: string;
-    content: string;
-    attachments?: DisplayAttachment[];
-} | {
-    kind: 'agent';
-    key: string;
-    ts?: string;
-    /** Author agent, when known (multi-agent embedded threads switch mid-conversation). */
-    agentId?: string;
-    items: TurnItem[];
-    status: TurnStatus;
-    /** Latest runtime status label ('thinking', …) — meaningful while streaming. */
-    statusLabel?: string;
-};
-export interface FoldOptions {
-    /** Raw chunks of the in-flight turn; presence (even empty) appends a streaming turn. */
-    liveChunks?: readonly RuntimeChatChunk[];
-    /** Author of the live turn, when known. */
-    liveAgentId?: string;
-}
-/**
- * Fold persisted rows + optional live chunks into the renderable turn list.
- * Pure — same inputs, same output (keys are derived from row position, so
- * they're stable across re-folds).
- */
-export declare function foldConversation(messages: readonly ConversationMessage[], opts?: FoldOptions): ConversationTurn[];
+/** @deprecated Import conversation models and folding from `@makinbakin/sdk/conversation`. */
+export { foldConversation } from '@makinbakin/sdk/conversation';
+export type { ConversationChunk, ConversationMessage, ConversationTextFormat, ConversationToolActivity, ConversationToolCall, ConversationTurn, DisplayAttachment, FoldOptions, TurnItem, TurnStatus, } from '@makinbakin/sdk/conversation';

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

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+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;
+    title?: ReactNode;
+    /** Accessible title used when the visible title is intentionally omitted. */
+    ariaLabel?: string;
+    description?: ReactNode;
+    actions?: ReactNode;
+    children: ReactNode;
+    defaultWidth?: number;
+    /** Optional suffix for per-context drawer width persistence. */
+    storageKey?: string;
+    /** When provided, a back action appears left of the title. */
+    onBack?: () => void;
+    /** When true, closing the drawer shows an unsaved-changes confirmation. */
+    dirty?: boolean;
+    /** Prevents escape, outside, close-button, and dirty-confirm dismissal while work is in flight. */
+    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, };

package/_internal/app/components/ui/button.d.ts

@@ -1,8 +1,2 @@
-import { Button as ButtonPrimitive } from "@base-ui/react/button";
-import { type VariantProps } from "class-variance-authority";
-declare const buttonVariants: (props?: ({
-    variant?: "warning" | "destructive" | "info" | "default" | "link" | "outline" | "secondary" | "ghost" | "accent" | null | undefined;
-    size?: "default" | "sm" | "lg" | "icon" | "xs" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react/jsx-runtime").JSX.Element;
-export { Button, buttonVariants };
+export { Button, buttonVariants } from '../../../host/ui/action-status';
+export type { ButtonProps, ButtonSize, ButtonVariant, ButtonVariantOptions, LegacyButtonSize, LegacyButtonVariant, } from '../../../host/ui/action-status';

package/_internal/app/components/ui/dialog.d.ts

@@ -1,17 +1,2 @@
-import * as React from "react";
-import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
-declare function Dialog({ ...props }: DialogPrimitive.Root.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogPortal({ ...props }: DialogPrimitive.Portal.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogClose({ ...props }: DialogPrimitive.Close.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogOverlay({ className, ...props }: DialogPrimitive.Backdrop.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogContent({ className, children, showCloseButton, ...props }: DialogPrimitive.Popup.Props & {
-    showCloseButton?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
-declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
-declare function DialogFooter({ className, showCloseButton, children, ...props }: React.ComponentProps<"div"> & {
-    showCloseButton?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
-declare function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props): import("react/jsx-runtime").JSX.Element;
-declare function DialogDescription({ className, ...props }: DialogPrimitive.Description.Props): import("react/jsx-runtime").JSX.Element;
-export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, };
+export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, UnsavedChangesDialog, } from '../../../host/ui/modals';
+export type { DialogCloseProps, DialogContentProps, DialogDescriptionProps, DialogFooterProps, DialogHeaderProps, DialogOverlayProps, DialogPortalProps, DialogProps, DialogTitleProps, DialogTriggerProps, UnsavedChangesDialogProps, } from '../../../host/ui/modals';

package/_internal/app/components/ui/sheet.d.ts

@@ -1,14 +1,2 @@
-import * as React from "react";
-import { Dialog as SheetPrimitive } from "@base-ui/react/dialog";
-declare function Sheet({ ...props }: SheetPrimitive.Root.Props): import("react/jsx-runtime").JSX.Element;
-declare function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props): import("react/jsx-runtime").JSX.Element;
-declare function SheetClose({ ...props }: SheetPrimitive.Close.Props): import("react/jsx-runtime").JSX.Element;
-declare function SheetContent({ className, children, side, showCloseButton, ...props }: SheetPrimitive.Popup.Props & {
-    side?: "top" | "right" | "bottom" | "left";
-    showCloseButton?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
-declare function SheetHeader({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
-declare function SheetFooter({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
-declare function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props): import("react/jsx-runtime").JSX.Element;
-declare function SheetDescription({ className, ...props }: SheetPrimitive.Description.Props): import("react/jsx-runtime").JSX.Element;
-export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, };
+export { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, } from '../../../host/ui/modals';
+export type { SheetCloseProps, SheetContentProps, SheetDescriptionProps, SheetFooterProps, SheetHeaderProps, SheetOverlayProps, SheetPortalProps, SheetProps, SheetSide, SheetTitleProps, SheetTriggerProps, } from '../../../host/ui/modals';

package/_internal/app/core/conversation-turns.d.ts

@@ -7,6 +7,14 @@ export interface TurnAttachment {
     mimeType: string;
     path: string;
 }
+export declare function isRasterAttachment(a: TurnAttachment): boolean;
+/**
+ * THE file-lane note generator (#742) — every chat-like surface (web
+ * composer, Discord inbound) converges here; never hand-roll this note.
+ * PDFs point at the blessed pdf tool rendered in the active runtime's
+ * calling style; other files get the generic file-tools wording.
+ */
+export declare function fileLaneNote(a: TurnAttachment, agentId: string, renderCall?: (tool: string, args: string) => string): string;
 /**
  * The durable transcript row shape (identical to chat's schema-v2 rows —
  * user attachments are path-addressed server-side; display URLs are a
@@ -44,12 +52,42 @@ export type ConversationTurnRow = {
     kind: 'aborted';
     ts: string;
     turnId?: string;
+} | {
+    kind: 'done';
+    ts: string;
+    turnId?: string;
 };
 export interface TurnOutcome {
     aborted: boolean;
     errored: boolean;
 }
-export type StartTurnResult = 'accepted' | 'not_found' | 'busy';
+export type StartTurnResult = 'accepted' | 'not_found' | 'busy' | QueuedStart;
+/**
+ * The queued acceptance (#729) — captured synchronously at push time so
+ * callers get THEIR item's id, never a tail re-read that a concurrent
+ * enqueue could poison (review finding: the awaited persist can park
+ * behind streaming transcript writes, making post-await reads stale).
+ */
+export interface QueuedStart {
+    queued: true;
+    queueId: string;
+    queueLength: number;
+}
+/**
+ * A message accepted while the slot was busy (#729). Queued messages are a
+ * consumer-durable snapshot (the `queue.persist` hook) and drain as ONE
+ * combined turn when the active turn settles — done, error, and abort all
+ * drain. `agentId` is the agent resolved at enqueue time; the drain's
+ * synchronous slot reservation uses it, then refreshes from resolveThread
+ * before the runtime call.
+ */
+export interface QueuedMessage {
+    id: string;
+    ts: string;
+    content: string;
+    agentId: string;
+    attachments?: TurnAttachment[];
+}
 export interface InflightTurnInfo {
     key: string;
     agentId: string;
@@ -89,6 +127,29 @@ export interface ConversationTurnServiceConfig {
     framing?: string;
     /** Run turns as ephemeral runtime sessions (no provider-side accumulation). */
     ephemeral?: boolean;
+    /**
+     * Persist an invisible `{kind:'done'}` marker row at clean success settle
+     * (#735). Abort/error settles already end on their own terminal rows, so
+     * with this on EVERY settled turn ends on a terminal row — the evidence a
+     * boot sweep needs to stamp partial-output deaths without ever falsely
+     * marking a completed turn. Chat-style sweepable transcripts only:
+     * bounded stores (brands' 300-row brainstorm array) would evict real
+     * rows, and foreign zod schemas would reject the kind.
+     */
+    terminalMarkerRows?: boolean;
+    /**
+     * Opt-in pending queue (#729). Without this, a busy slot always answers
+     * `'busy'` — strict surfaces are unchanged.
+     */
+    queue?: {
+        /**
+         * Full-snapshot persistence after every queue mutation — the restart
+         * durability promise. Failures are logged, never thrown to callers.
+         */
+        persist?: (key: string, items: QueuedMessage[]) => void | Promise<void>;
+        /** Bus event emitted on enqueue (payload + queueId + queueLength). */
+        event?: string;
+    };
     hooks?: {
         /** Read-only tap on EVERY runtime chunk (e.g. messaging proposal parsing). */
         onChunk?: (key: string, chunk: ChatChunk) => void;
@@ -121,6 +182,15 @@ export interface StartTurnOptions {
     attachments?: TurnAttachment[];
     /** Per-turn agent override (surfaces with an agent picker); default = resolveThread's. */
     agentId?: string;
+    /**
+     * Busy slot → enqueue instead of `'busy'` (requires `config.queue`).
+     * The busy-check and enqueue happen in one synchronous block (no TOCTOU).
+     * CAVEAT: a QUEUED send keeps only content + attachments — a per-turn
+     * `agentId` override and `runtimeContent` are DISCARDED at drain time
+     * (the combined turn resolves the thread's agent fresh and joins clean
+     * content). Surfaces that need either must not opt into queueing.
+     */
+    queueIfBusy?: boolean;
     /**
      * Pre-assembled runtime content for THIS turn (embedded surfaces inject
      * doc/context prompts here). The persisted user row always keeps the
@@ -130,8 +200,19 @@ export interface StartTurnOptions {
 }
 export interface ConversationTurnService {
     start(ctx: TurnContext, key: string, content: string, opts?: StartTurnOptions): Promise<StartTurnResult>;
-    /** Abort the in-flight turn; false when the thread is idle. */
+    /** Abort the in-flight turn; false when the thread is idle. Queued messages stay — they drain at settle. */
     abort(key: string): boolean;
+    /** Snapshot of the pending queue (empty for strict surfaces). */
+    listQueued(key: string): QueuedMessage[];
+    /** Remove one queued message by id; persists. False when absent. */
+    removeQueued(key: string, id: string): boolean;
+    /** Drop the whole queue (delete-thread path); persists empty. */
+    clearQueue(key: string): void;
+    /**
+     * Seed the queue from persisted state (boot path) and drain immediately
+     * when the slot is idle. Does NOT re-persist — the items came from disk.
+     */
+    restore(ctx: TurnContext, key: string, items: QueuedMessage[]): void;
     isInFlight(key: string): boolean;
     /** Assistant text streamed so far for the in-flight turn (null when idle) —
      *  lets GET responses seed mid-turn rehydration without the missing-start gap. */

package/_internal/app/core/tool-access.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The ONE renderer for a runtime's tool-access instructions (P1.2).
+ *
+ * A runtime declares HOW its agents reach Bakin's `bakin_exec_*` tools via
+ * `describeToolAccess()` → {@link RuntimeToolAccess}. This module turns that
+ * declaration into the agent-facing instruction block. Both the projected
+ * AGENTS.md role layer and the per-dispatch prompt render through here (P1.4),
+ * so the two surfaces can never drift.
+ *
+ * Style intent:
+ *  - `in-process`  — exec tools are first-class session tools; bare calls,
+ *                    no cheat-sheet (the agent discovers the live set).
+ *  - `mcp`         — tools appear as native MCP tools under a per-agent
+ *                    server; prefixed calls, still discovered live.
+ *  - `cli-shim`    — tools are reached through a shell command; the exhaustive
+ *                    cheat-sheet IS warranted here because the invocation is
+ *                    non-obvious and easy to get wrong.
+ */
+import type { RuntimeToolAccess } from '../../core/adapters/runtime';
+export interface ToolAccessRenderOptions {
+    /** Agent whose per-agent server / shim names to substitute (mcp, cli-shim). */
+    agentId: string;
+}
+/**
+ * Render ONE tool invocation in the runtime's style — the primitive shared by
+ * both the standing tool-access block (below) and the per-dispatch prompt
+ * authors, so invocation bytes cannot drift between the two surfaces.
+ *   - in-process → `bakin_exec_x arg=1`
+ *   - mcp        → `bakin-<agent>.bakin_exec_x arg=1`
+ *   - cli-shim   → the shim command with `<tool>`/`<args>` filled in
+ * `args` may be empty (trailing space is trimmed).
+ */
+export declare function renderToolCall(access: RuntimeToolAccess, opts: {
+    agentId: string;
+    tool: string;
+    args?: string;
+}): string;
+/**
+ * Render the runtime-specific tool-access instruction block for `agentId`.
+ * Returns a single markdown string (no trailing newline).
+ */
+export declare function renderToolAccessInstructions(access: RuntimeToolAccess, opts: ToolAccessRenderOptions): string;