API Reference

Every hudsonkit export, organized by subpath. Types are authoritative in packages/web/hudsonkit/src/types/; this doc is a map, not the source of truth.

Subpath exports

Types

Importable from hudsonkit:

Hooks (from hudsonkit)

Returned types (also exported): AppSettingsValues, HudsonAIChat, UseHudsonAIOptions, AIAttachment, AssistantChat, UseAssistantOptions, TerminalRelayHandle, UseTerminalRelayOptions, RelayStatus.

Cache (from hudsonkit/cache)

hudsonkit/cache is the shared cache substrate for values that can be refetched or recomputed. It supports TTL, stale-while-revalidate windows, in-flight async dedupe, tag invalidation, optional local/session storage, hydrate/dehydrate, and subscribed React reads.

Cache instances expose read, get, has, set, getOrLoad, revalidate, delete, clear, invalidateTag, keys, prune, dehydrate, hydrate, and subscribe.

Types: HudsonCache, HudsonCacheEntry, HudsonCacheRead, HudsonCacheEvent, HudsonCacheStatus, HudsonCacheStorage, HudsonCacheLoadOptions, HudsonCacheSetOptions, HudsonCacheOptions, HudsonCacheLoader, CachedResourceStatus, UseCachedResourceOptions, UseCachedResourceResult.

See Cache for the policy guidance: when to use Hudson's primitive, when to keep data in Provider state, and when to reach for TanStack Query, IndexedDB, Cache API, or Next.js caching instead.

Components

From hudsonkit

• AI — chat panel component, paired with useHudsonAI
• Assistant — assistant panel component, paired with useAssistant
• TerminalRelay, captureWorkspace — terminal relay component + screenshot helper
• ZoomControls — reusable widget (also re-exported from /chrome)

From hudsonkit/app-shell

AppShell props

From hudsonkit/shell (back-compat barrel)

All of: WorkspaceShell, AppShell, Frame, NavigationBar, SidePanel, StatusBar, CommandDock, Minimap, ZoomControls, AnimationTimeline, Canvas, AppWindow, TerminalDrawer, CommandPalette, HudsonContextMenu, design tokens.

From hudsonkit/context-menu

• HudsonContextMenu — right-click menu component. Pulls motion/react + @base-ui-components/react.

Theme (from hudsonkit)

Types: HudsonTheme, HudsonTemplate, ThemeProviderProps.

ThemeProviderProps: { children, defaultTheme?, defaultTemplate?, storageKey?, rootElement? }.

See Theming for usage.

Instance context (from hudsonkit)

Types: InstanceContextValue — { instanceId: string; appId: string }.

Assistant (from hudsonkit)

• Assistant — panel component. Props: { app: HudsonApp; commands: CommandOption[] }. Renders a chat UI wired to the app's declared intents.
• useAssistant(options) — lower-level hook. Builds context from app.intents, wires a dispatch tool call to the live commands array, delegates to useHudsonAI internally.

AssistantChat is an alias for HudsonAIChat.

Note: useAssistant is app-intent aware; useHudsonAI is the lower-level workspace AI panel transport.

Observability (from hudsonkit)

Exported types: HLogEvent, HLogInput, HLogLevel, HMetricEvent, HMetricInput, HMetricType, HObservabilityOptions, HObservation, HObservationBase, HObservationData, HObservationKind, HObservationSink, HObservationTags, HSubscribeOptions, HTraceInput, HTraceSpan, HTraceStatus, HUnsubscribe.

These are advanced — refer to src/observability.ts and hudsonkit/observability for the full surface.

Platform adapter (from hudsonkit)

• WEB_ADAPTER — default web platform adapter
• PlatformProvider — wraps a subtree with a specific adapter
• usePlatform(), usePlatformLayout() — consumer hooks
• Types: PlatformAdapter, PlatformLayout

Utilities (from hudsonkit)

• sounds — Web Audio event sounds: blipUp, blipDown, click, whoosh, thock, pop, confirm, error, chime, tick, slideIn, slideOut, boot, ping, type
• logEvent, FRAME_LOG_EVENT — instrumented event bus
• FrameLogEntry type
• worldToScreen, screenToWorld — canvas coordinate math
• deriveManifest(app) — build an AppManifest from a HudsonApp
• probeVoxAvailability() — check voice availability; returns VoxAvailability

The HudsonApp interface at a glance

interface HudsonApp {
  // Identity
  id: string;
  name: string;
  description?: string;
  mode: 'canvas' | 'panel';
  icon?: ReactNode;

  // Multi-instance behaviour (default: 'singleton')
  multiInstance?: MultiInstanceMode; // 'singleton' | 'spawnable' | 'duplicable'

  // Panel config
  leftPanel?: { title: string; icon?: ReactNode; headerActions?: React.FC };
  rightPanel?: { title: string; icon?: ReactNode; headerActions?: React.FC };

  // State owner — disabled/visible/focused reflect workspace mount state
  Provider: React.FC<{ children: ReactNode; disabled?: boolean; visible?: boolean; focused?: boolean }>;

  // Right sidebar tool accordion
  tools?: AppTool[];

  // Slots
  slots: {
    Content: React.FC;
    LeftPanel?: React.FC;
    RightPanel?: React.FC;              // @deprecated — use Inspector
    Inspector?: React.FC;
    LeftFooter?: React.FC;
    Terminal?: React.FC;
    /** Full-viewport overlay rendered above shell chrome. Shell marks
     *  background `inert` + `aria-hidden` while active. */
    Takeover?: React.FC;
  };

  // Shell bridge
  hooks: {
    useCommands: () => CommandOption[];
    useStatus: () => { label: string; color: StatusColor };
    useSearch?: () => SearchConfig;
    useNavCenter?: () => ReactNode | null;
    useNavActions?: () => ReactNode | null;
    useLayoutMode?: () => 'canvas' | 'panel' | 'focus';
    useActiveToolHint?: () => string | null;
    usePortOutput?: () => (portId: string) => unknown | null;
    usePortInput?: () => (portId: string, data: unknown) => void;
    /** Return active:true to mount Takeover above chrome. Shell is
     *  stateless about dismissal — the hook's own state drives it. */
    useTakeover?: () => TakeoverState | null;
  };

  // Optional integrations
  intents?: AppIntent[];
  manifest?: AppManifest;
  settings?: AppSettingsConfig;
  ports?: AppPorts;
  services?: ServiceDependency[];
}

See Building apps for a walkthrough.