nexus-shell 0.1.23 → 0.2.1

package/README.md

@@ -1,147 +1,232 @@
-# 🚀 Nexus Shell Framework
+# Nexus Shell
 
-[![npm version](https://img.shields.io/npm/v/nexus-shell.svg)](https://www.npmjs.com/package/nexus-shell)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build & Deploy Storybook](https://github.com/techmuch/nexus-shell/actions/workflows/deploy-storybook.yml/badge.svg)](https://github.com/techmuch/nexus-shell/actions/workflows/deploy-storybook.yml)
-[![Live Documentation](https://img.shields.io/badge/docs-live--pages-blueviolet)](https://techmuch.github.io/nexus-shell/?path=/docs/introduction--docs)
+React components for building IDE-style application shells — menu bar, activity
+bar, sidebar, docking layout, terminal, chat pane and status bar.
 
-Nexus Shell is a professional-grade, library-first React 19 / TypeScript frontend framework for building multi-panel **"Workbench"** style applications (resembling VS Code, JupyterLab, or specialized dashboard workstations). 
+**[Documentation and live examples →](https://techmuch.github.io/nexus-shell/)** ·
+[Storybook](https://techmuch.github.io/nexus-shell/storybook/)
 
-Instead of building a rigid layout from scratch, Nexus Shell provides a **fully decoupled, registry-driven workspace engine** powered by `flexlayout-react`, allowing tabs, menus, hotkeys, status bars, and custom sidebars to be dynamically declared and contextually composed.
+```bash
+npm install nexus-shell
+```
 
----
+```ts
+import 'nexus-shell/style.css';
+```
 
-## 📖 Live Interactive Documentation
-Explore the live documentation, interactive component playground, prop definitions, and layout compositions at:
-👉 **[Live Storybook Documentation Site](https://techmuch.github.io/nexus-shell/?path=/docs/introduction--docs)**
+React 19 is a peer dependency.
 
----
+## Start with the shell
 
-## 🎨 Visual Showcase & Capabilities
+An application built on this library starts with `ShellLayout` and grows by
+registering features into it.
 
-### 1. Tabbed Dialogue Mapping Workbench & Workspace
-A flexible workstation that integrates Compendium-style visual argumentation mapping (React Flow canvas) with external node libraries and logic inspectors as drag-and-drop tabs.
-![Dialogue Mapping Workbench (Dark Theme)](docs/images/dialogue-mapper-library-dark.png)
-*(Above: Dialogue Mapping workspace in Dark Theme showing interactive nodes, custom icons, and Straight connectors)*
+```tsx
+// main.tsx — a complete application
+import { createRoot } from 'react-dom/client';
+import { Boxes, Files } from 'lucide-react';
+import {
+  AppTitle,
+  ShellLayout,
+  componentRegistry,
+  initializeShell,
+  useLayoutStore,
+} from 'nexus-shell';
+import 'nexus-shell/style.css';
+
+// Views register by id, so the shell never has to import them.
+componentRegistry.register('editor', Editor);
+
+initializeShell({
+  panels: [{ id: 'files', label: 'Explorer', icon: Files, component: FileExplorer }],
+  commands: [
+    { id: 'file.save', label: 'File: Save', keybinding: 'Control+s', execute: save },
+  ],
+  menus: { File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] },
+  statusBar: [{ id: 'branch', label: 'main', alignment: 'left' }],
+});
 
-### 2. Georgia Tech Theme & Theme-Adaptivity
-Fully responsive styling driven by HSL CSS variables, conforming to WCAG contrast standards.
-![Dialogue Mapping Workbench (GT Theme)](docs/images/dialogue-mapper-library-light.png)
-*(Above: Light Theme workspace showing responsive menus, active tab headers, and the account widget)*
+useLayoutStore.getState().addTab('editor', 'App.tsx');
 
-### 3. Workflow Reviews & Mockup Canvas Overlay
-Draw overlay annotations directly onto child mockups and generate implementation plans dynamically using AI nodes.
-![Mockup Reviewer Layout](docs/images/mockup-reviewer-layout.png)
-*(Above: A complex Mockup Reviewer workstation running canvas drawing tools and terminal consoles side-by-side)*
+createRoot(document.getElementById('root')!).render(
+  <ShellLayout title={<AppTitle title="Acme Studio" icon={<Boxes size={16} />} />} />,
+);
+```
 
-### 4. Interactive Storybook Workspace
-Reorganized story taxonomy allowing you to build, test, and preview widgets in isolation or combined.
-![Storybook Taxonomy](docs/images/media__storybook_layout.png)
+That is a working IDE: dockable tabs, a command palette on `Cmd/Ctrl+Shift+P`, a
+terminal, a chat pane, and a themable frame.
 
----
+## Growing an app
 
-## 🤔 Why Choose Nexus Shell?
+You add capability by **registering** it. None of this changes the layout, which
+is what lets plugins and distant code contribute to the shell.
 
-| If you are building... | Nexus Shell provides... |
-| :--- | :--- |
-| **IDE/Workbench Web Apps** | A complete drag-and-drop tab layout engine with splits, resizing, and sidebars (`flexlayout-react` integration). |
-| **Modular Dashboard Interfaces** | Inversion of Control registries (`componentRegistry`, `commandRegistry`, `menuRegistry`) so features register themselves dynamically. |
-| **Complex Geospatial/Tactical Maps** | High-performance maps (`WargameMap`) combining `react-map-gl`, `deck.gl`, and `h3-js` for hexagonal grid overlays and MIL-STD military icons. |
-| **AI Orchestration Workbenches** | State-driven workflow templates, agent nodes, and drawing canvas mockups built with React Flow. |
+| To add | Do this |
+| :-- | :-- |
+| A view or tab | `componentRegistry.register(id, Component)`, then `useLayoutStore().addTab(id, title)` |
+| An action or hotkey | `commandRegistry.registerCommand({ id, label, keybinding, execute })` — appears in the palette automatically |
+| A menu entry | `menuRegistry.registerMenu('File', { id, label, commandId })` |
+| A sidebar panel | Add it to `panels`; it becomes an activity bar icon |
+| A status bar item | `useStatusBarStore.getState().addWidget(...)` |
+| A dialog from anywhere | `await useModalStore.getState().openConfirm('Sure?')` |
+| An unsaved-changes guard | `useLayoutStore.getState().setTabDirty(tabId, true)` |
 
----
+## When you need less than the shell
 
-## ✨ Key Features
+Every component the shell is assembled from is exported on its own — pure and
+prop-driven, with no global state or registry lookups. This is the escape hatch:
+reach for it when you're embedding one piece into an app you already have, or
+building a frame `ShellLayout` can't express.
 
-- **Advanced Docking Engine**: Full drag-and-drop tab management (dock, split, float, collapse) out-of-the-box.
-- **Inversion of Control (IoC) Registries**: Add new menu items, hotkeys, or tab contents programmatically from anywhere in your code without touching the layout container.
-- **Zustand State Persistence**: Automatically restores the user's workspace structure, theme preference, and pane configurations across page reloads.
-- **Accessibility & Contrast First**: Built to look beautiful and professional under three default themes (`theme-light`, `theme-dark`, and `theme-gt` for Georgia Tech fans) while satisfying AA/AAA color contrast ratios.
-- **Pre-Integrated Widgets**: A library of reusable layout widgets including terminal consoles, chat panels, tree file explorers, virtualized grids, and hex maps.
+```tsx
+import { ActivityBar, SidebarPane, StatusBar, TreeWidget } from 'nexus-shell';
+
+const [active, setActive] = useState<string | null>('files');
+
+<div className="theme-dark flex h-screen flex-col">
+  <div className="flex flex-1">
+    <ActivityBar
+      items={panels}
+      activeId={active}
+      onSelect={(id) => setActive(id === active ? null : id)}
+    />
+    {active && (
+      <SidebarPane title="Explorer" onClose={() => setActive(null)}>
+        <TreeWidget data={files} onToggle={toggle} onActivate={open} />
+      </SidebarPane>
+    )}
+    <main className="flex-1">{children}</main>
+  </div>
+  <StatusBar widgets={[{ id: 'branch', label: 'main', alignment: 'left' }]} />
+</div>;
+```
 
----
+These are controlled, so state stays in your app — a real cost the shell was
+absorbing for you.
 
-## 🚦 Quick Start
+Between the two sit the `Connected*` variants, each binding one component to its
+store. `ShellLayout` is built entirely out of them, so you can rearrange the
+shell's own frame and keep every registration working.
 
-### 1. Installation
+## Components
 
-```bash
-npm install nexus-shell
-```
+`ShellLayout` assembles all of these. Each is also exported on its own.
 
-### 2. Basic Setup
+| Component | What it is |
+| :-- | :-- |
+| `ActivityBar` | Vertical icon rail for switching sidebar panels |
+| `ChatPane` | Docked chat transcript with slash-command autocomplete |
+| `CommandPalette` | Filterable, keyboard-navigable command list |
+| `ContextMenu` | Floating menu positioned at viewport coordinates |
+| `DataGrid` | Sortable, filterable table with optional virtualisation |
+| `MenuBar` | Application menu bar with submenus and content slots |
+| `Modal` | Alert / confirm / prompt dialog |
+| `QuickSearch` | Compact search field with grouped results, for the menu bar |
+| `SearchWidget` | Full-height search panel with autocomplete, for the sidebar |
+| `SettingsPanel` | Theme picker body for the settings sidebar |
+| `SidebarPane` | Titled, closable container for sidebar content |
+| `StatusBar` | Footer with left / center / right item groups |
+| `TerminalPane` | Bottom-docked terminal log and input |
+| `ThemeSwitcher` | Segmented theme control |
+| `TreeWidget` | Virtualised file tree with drag-to-move and a data-driven menu |
+| `UserProfile` | Avatar and identity widget |
 
-In your main entry point (e.g., `main.tsx` or `App.tsx`):
+## Theming
 
-```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { ShellLayout, initializeShell } from 'nexus-shell';
-import 'nexus-shell/style.css'; // Essential styling properties
-
-// Initialize core registries and default welcome workspace
-initializeShell();
-
-export default function App() {
-  return (
-    <div className="h-screen w-screen bg-background text-foreground">
-      <ShellLayout 
-        title={<div className="font-bold text-lg">My Custom IDE</div>}
-      />
-    </div>
-  );
-}
-
-ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
-```
+Three themes ship in the stylesheet: `theme-light`, `theme-dark`, `theme-gt`.
+Colors are CSS custom properties scoped to those classes, so switching themes is
+a class on an ancestor — no React context, no provider.
 
----
+Add your own by defining a `.theme-yourname` block with the same properties.
 
-## 🏗 Registry-Driven Customization
+## Development
 
-Nexus Shell lets you register custom features dynamically:
+```bash
+npm install
+
+npm run site           # documentation site at :5173
+npm run storybook      # component workbench at :6006
+npm run dev            # showcase app at :5173
+
+npm run typecheck      # library sources
+npm test               # vitest — unit and architecture tests
+npm run site:test      # renders every site route and demo
+npm run build          # library build to dist/
+npm run build-storybook
+npm run site:build     # documentation site to website/dist/
+npm run e2e            # Playwright against the showcase app
+```
 
-### Register a Keyboard Shortcut (Command)
-```typescript
-import { commandRegistry } from 'nexus-shell';
+`npm run typecheck` covers `src/` only. To include the examples:
 
-commandRegistry.registerCommand({
-  id: 'my-app.hello',
-  label: 'Say Hello',
-  keybinding: 'Control+L',
-  execute: () => alert('Hello from Nexus Shell!'),
-});
+```bash
+npx tsc --noEmit -p tsconfig.examples.json
 ```
 
-### Register a Tab Component
-```typescript
-import { componentRegistry } from 'nexus-shell';
+CI runs all of the above on every push and pull request.
+
+### Layout
 
-componentRegistry.register('my-custom-widget', () => (
-  <div className="p-4 bg-card text-card-foreground">
-    <h2>Dynamic Custom Tab</h2>
-    <p>This tab can be docked anywhere in the workspace!</p>
-  </div>
-));
+```
+src/
+  components/       Pure, prop-driven components — what the shell is made of
+  connected/        Store-bound wrappers used by ShellLayout
+  core/             Stores (zustand), registries, and initializeShell
+  lib/              Shared utilities
+  stories/          MDX documentation pages
+examples/
+  showcase/         Demo apps built on the library — not published
+    dialogue-mapper/
+    mockup-reviewer/
+    wiki/
+    wargame/
+    e2e/            Playwright specs for the showcase app
+  basic-app/        Minimal integration example
+website/
+  src/demos/        Live examples — the source shown on the site
+  src/content/      The component gallery, as data
+  scripts/          Generates the props tables from the library's types
 ```
 
----
+### Documentation site
 
-## 🧪 Development & Testing
+`website/` is a Vite app that imports the library from `../src`, not from
+`dist`. Every example on the site is rendered by the current source, so a demo
+that no longer compiles against the real API fails the build rather than
+quietly documenting an API that no longer exists.
 
-```bash
-# Start Vite App & local Storybook server
-npm run dev:all
+Two generation steps keep it honest:
 
-# Build package artifacts (ESM, UMD, CSS, and Types)
-npm run build
+- **Props tables** come from `website/scripts/generate-api.mjs`, which parses
+  the component sources for prop names, types, defaults and JSDoc. Nothing is
+  hand-written.
+- **Code samples** are extracted from the demo files by `#region` marker, so the
+  snippet a visitor copies is provably the code that produced the thing they
+  just interacted with.
 
-# Run Playwright E2E and Visual Regression tests
-npx playwright test
-```
+Adding a component to the site is one entry in `website/src/content/components.ts`
+plus a demo file. There is no per-component page to keep in sync.
+
+The site ships no dependencies of its own — routing, syntax highlighting and the
+copy button are all local, so the docs can't drag the repo's install surface
+around.
+
+**Deployment.** `.github/workflows/deploy-pages.yml` builds the site and
+Storybook on every push to `main` and publishes them as one Pages artifact — the
+site at the root, Storybook under `/storybook/`. First-time setup needs your
+credentials: run `./scripts/setup-pages.sh`.
+
+The split between `components/` and `connected/` is the load-bearing one. A
+component that reads a global store can't be configured by its caller, rendered
+twice with different data, or documented — its props table is empty because it
+has no props. Everything in `components/` is therefore forbidden from importing
+`core/services`, and the tests in `components/__tests__` exist to keep it that
+way.
 
----
+Anything under `examples/` is a consumer of the library, not part of it. It's
+built and documented alongside the components to prove the primitives are
+sufficient, but it ships to nobody.
 
-## 📄 License
+## License
 
-MIT © [David/TechMuch]
+MIT

package/dist/components/layout/ShellLayout.d.ts

@@ -1,17 +1,95 @@
-import { Model } from 'flexlayout-react';
+import { ReactNode } from 'react';
+import { Model, IJsonModel } from 'flexlayout-react';
+import { IMenuItemConfig } from '../../core/registry/MenuRegistry';
+import { ISlashCommandConfig } from '../../core/services/ChatService';
 import { ISidebarPanel } from '../../core/services/SidebarService';
-import { ISlashCommand } from '../../core/services/ChatService';
-import { IStatusBarWidget } from '../../core/services/StatusBarService';
-import { IMenuItem } from '../../core/registry/MenuRegistry';
+import { IStatusBarWidgetConfig } from '../../core/services/StatusBarService';
 
-interface ShellLayoutProps {
+export interface ShellLayoutProps {
+    /**
+     * Sidebar panels to register. Each becomes an icon in the activity bar and
+     * renders its `component` in the sidebar when selected.
+     */
     panels?: ISidebarPanel[];
-    slashCommands?: ISlashCommand[];
-    menuConfig?: Record<string, IMenuItem[]>;
-    statusBarConfig?: IStatusBarWidget[];
-    rightMenuBarContent?: React.ReactNode;
-    title?: React.ReactNode;
+    /** Slash commands available in the chat pane. */
+    slashCommands?: ISlashCommandConfig[];
+    /** Menu structure, keyed by top-level menu name. Items dispatch by `commandId`. */
+    menuConfig?: Record<string, IMenuItemConfig[]>;
+    /** Items for the status bar, grouped by their `alignment`. */
+    statusBarConfig?: IStatusBarWidgetConfig[];
+    /** Branding shown at the far left of the menu bar. */
+    title?: ReactNode;
+    /** Slot at the far right of the menu bar, for actions or a theme switcher. */
+    rightMenuBarContent?: ReactNode;
+    /** Widget rendered between the menus and the right slot, sized for search. */
+    centerMenuBarContent?: ReactNode;
+    /**
+     * Take control of the docking layout. When provided, the shell renders this
+     * model and stops writing changes to `useLayoutStore` — useful for tests and
+     * stories. Omit it to use the store's persisted model.
+     */
     layoutModel?: Model;
+    /**
+     * Starting workspace, as a `flexlayout-react` JSON model. Applied once on
+     * mount and only when nothing has been restored from storage, so it seeds a
+     * first run without overwriting a layout the user has since arranged.
+     *
+     * Ignored when `layoutModel` is provided, which takes control outright.
+     */
+    initialLayoutJson?: IJsonModel;
+    /**
+     * Stop persisting the layout to `localStorage`. The workspace then resets to
+     * `initialLayoutJson` on every load — useful for embedded or multi-tenant
+     * shells where a per-browser layout would be wrong. Defaults to `false`.
+     */
+    disableLocalStorage?: boolean;
+    /**
+     * Called with the serialised model whenever the user moves, splits, opens or
+     * closes a tab. Use it to persist the layout somewhere of your own — a user
+     * profile on the server, say — instead of, or alongside, `localStorage`.
+     */
+    onLayoutChange?: (layout: IJsonModel) => void;
 }
-export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, rightMenuBarContent, title, layoutModel }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+/**
+ * The complete application shell: menu bar, activity bar, sidebar, a
+ * `flexlayout-react` docking workspace, terminal, chat pane and status bar.
+ *
+ * **This is where an application starts.** Call {@link initializeShell} once to
+ * register your commands, menus and panels, render this component, and add
+ * features by registering them rather than by restructuring the layout. Tab
+ * contents resolve through the {@link componentRegistry}, so a new view is a
+ * registration and a menu entry — the shell never needs to import it.
+ *
+ * Configuration can arrive either way. Props are convenient for values that
+ * change with your app's state; {@link initializeShell} is better for the fixed
+ * set, since it runs once and works outside React. Props passed here are
+ * written into the same stores on mount, so the two are interchangeable.
+ *
+ * Internally this composes the `Connected*` component variants, which read from
+ * the shell stores. Those components — and the pure ones beneath them — are
+ * exported too, for the cases where you need to rearrange the frame itself.
+ *
+ * Closing a tab marked dirty via `useLayoutStore().setTabDirty` prompts for
+ * confirmation before the tab is removed.
+ *
+ * @example
+ * ```tsx
+ * // main.tsx — a complete application
+ * import { initializeShell, ShellLayout, componentRegistry, AppTitle } from 'nexus-shell';
+ * import 'nexus-shell/style.css';
+ *
+ * componentRegistry.register('editor', Editor);
+ *
+ * initializeShell({
+ *   panels: [{ id: 'files', label: 'Explorer', icon: Files, component: FileTree }],
+ *   commands: [{ id: 'file.save', label: 'File: Save', keybinding: 'Control+s', execute: save }],
+ *   menus: { File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] },
+ *   statusBar: [{ id: 'branch', label: 'main', alignment: 'left' }],
+ * });
+ *
+ * createRoot(document.getElementById('root')!).render(
+ *   <ShellLayout title={<AppTitle title="Acme Studio" icon={<Boxes size={16} />} />} />,
+ * );
+ * ```
+ */
+export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, title, rightMenuBarContent, centerMenuBarContent, layoutModel, initialLayoutJson, disableLocalStorage, onLayoutChange, }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/ActivityBar.d.ts

@@ -1 +1,48 @@
-export declare const ActivityBar: () => import("react/jsx-runtime").JSX.Element;
+import { LucideIcon } from 'lucide-react';
+
+/** A single icon button in the {@link ActivityBar}. */
+export interface IActivityBarItem {
+    /** Stable identifier reported to `onSelect`. */
+    id: string;
+    /** Accessible label and tooltip text. */
+    label: string;
+    /** `lucide-react` icon rendered at 20px. */
+    icon: LucideIcon;
+}
+export interface ActivityBarProps {
+    /** Items rendered in the main (top) group, in order. */
+    items?: IActivityBarItem[];
+    /**
+     * Items rendered in the bottom group, below the flex spacer. Defaults to a
+     * single Settings item. Pass `[]` to render no bottom group.
+     */
+    bottomItems?: IActivityBarItem[];
+    /** Id of the currently active item, or `null` when nothing is selected. */
+    activeId?: string | null;
+    /**
+     * Called with the clicked item's id. Toggling — clicking the active item to
+     * deselect it — is the caller's decision, not the component's.
+     */
+    onSelect?: (id: string) => void;
+    /** Extra classes merged onto the root `<aside>`. */
+    className?: string;
+    /** Accessible label for the landmark. Defaults to `"Activity Bar"`. */
+    'aria-label'?: string;
+}
+/**
+ * The narrow vertical icon rail on the left edge of the shell, used to switch
+ * which panel the sidebar shows.
+ *
+ * Controlled — it holds no selection state. For the store-backed variant used
+ * by `ShellLayout`, see `ConnectedActivityBar`.
+ *
+ * @example
+ * ```tsx
+ * <ActivityBar
+ *   items={[{ id: 'files', label: 'Explorer', icon: Files }]}
+ *   activeId={active}
+ *   onSelect={(id) => setActive(id === active ? null : id)}
+ * />
+ * ```
+ */
+export declare const ActivityBar: ({ items, bottomItems, activeId, onSelect, className, "aria-label": ariaLabel, }: ActivityBarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/AppTitle.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+
+export interface AppTitleProps {
+    /** Primary line. Rendered uppercase in a mono face. */
+    title: string;
+    /** Secondary line beneath the title. Omit to render a single line. */
+    subtitle?: string;
+    /**
+     * Element shown in the leading badge, typically a 16px `lucide-react` icon.
+     * Omit to render no badge at all.
+     */
+    icon?: React.ReactNode;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A branding lockup — icon badge, title and subtitle — sized for the
+ * {@link MenuBar}'s `title` slot.
+ *
+ * Purely presentational. Pass whatever branding your app needs; the library
+ * supplies no default copy.
+ *
+ * @example
+ * ```tsx
+ * <MenuBar
+ *   title={<AppTitle title="Acme Studio" subtitle="Design System" icon={<Boxes size={16} />} />}
+ * />
+ * ```
+ */
+export declare const AppTitle: ({ title, subtitle, icon, className }: AppTitleProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/ChatPane.d.ts

@@ -1 +1,63 @@
-export declare const ChatPane: () => import("react/jsx-runtime").JSX.Element | null;
+import { default as React } from 'react';
+
+/** A single message in the {@link ChatPane} transcript. */
+export interface IChatMessage {
+    /** Stable identifier. Used as the React key. */
+    id: string;
+    /** Who sent it. `'user'` right-aligns; anything else left-aligns. */
+    role: 'user' | 'assistant';
+    /** Message body. Rendered as plain text with newlines preserved. */
+    text: string;
+    /** Optional display name shown above the bubble. Defaults from `role`. */
+    author?: string;
+}
+/** A `/`-prefixed shortcut offered in the composer's autocomplete. */
+export interface ISlashCommand {
+    /** Command word without the leading slash, e.g. `"clear"`. */
+    command: string;
+    /** One-line description shown beside the command in the suggestion list. */
+    description: string;
+}
+export interface ChatPaneProps {
+    /** Messages to display, oldest first. */
+    messages?: IChatMessage[];
+    /**
+     * Called with the trimmed message text on send. The component clears its
+     * composer but does not append to `messages` — that is the caller's job.
+     */
+    onSend?: (text: string) => void;
+    /** Slash commands offered once the composer starts with `/`. */
+    slashCommands?: ISlashCommand[];
+    /** Called when a slash command is picked from the suggestion list. */
+    onSlashCommand?: (command: ISlashCommand) => void;
+    /** Called when the close button is pressed. Omit to hide the button. */
+    onClose?: () => void;
+    /** Title shown in the pane header. Defaults to `"Chat"`. */
+    title?: string;
+    /** Placeholder for the composer. */
+    placeholder?: string;
+    /** Shown in place of the transcript when `messages` is empty. */
+    emptyState?: React.ReactNode;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A docked chat panel: a scrolling transcript over a composer with slash-command
+ * autocomplete.
+ *
+ * Fully controlled — it owns only the in-progress input and the suggestion
+ * highlight. Messages, sending and visibility belong to the caller, so the same
+ * component works against a local array, a websocket, or an LLM endpoint. For
+ * the store-backed variant used by `ShellLayout`, see `ConnectedChatPane`.
+ *
+ * @example
+ * ```tsx
+ * <ChatPane
+ *   messages={messages}
+ *   onSend={(text) => send(text)}
+ *   slashCommands={[{ command: 'clear', description: 'Clear the transcript' }]}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare const ChatPane: ({ messages, onSend, slashCommands, onSlashCommand, onClose, title, placeholder, emptyState, className, }: ChatPaneProps) => import("react/jsx-runtime").JSX.Element;