lumiverse-spindle-types 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1266,6 +1266,99 @@ export interface PermissionChangedDetail {
   allGranted: string[];
 }
 
+// ─── Web Search DTOs ────────────────────────────────────────────────────
+
+/** Identifies which provider backs the user's configured web search engine. */
+export type WebSearchProviderDTO = "searxng";
+
+/**
+ * Safe view of a user's web search configuration. The raw API key is never
+ * exposed — only `hasApiKey` indicates whether one is on file.
+ */
+export interface WebSearchSettingsDTO {
+  enabled: boolean;
+  provider: WebSearchProviderDTO;
+  apiUrl: string;
+  requestTimeoutMs: number;
+  defaultResultCount: number;
+  maxResultCount: number;
+  maxPagesToScrape: number;
+  maxCharsPerPage: number;
+  language: string;
+  safeSearch: 0 | 1 | 2;
+  engines: string[];
+  hasApiKey: boolean;
+}
+
+/** A single search result row, normalized across providers. */
+export interface WebSearchResultDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** Provider-reported engine identifier when available (e.g. `"google"`, `"bing"`). */
+  engine?: string;
+  /** Provider-reported relevance score when available. */
+  score?: number;
+}
+
+/**
+ * A search result enriched with scraped page content. Only present when the
+ * query was run with `scrape: true` (the default).
+ */
+export interface WebSearchDocumentDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** How the page content was extracted (e.g. `"html"`, `"pdf"`). */
+  sourceType?: string;
+  /** Extracted page text, clipped to `WebSearchSettingsDTO.maxCharsPerPage`. */
+  content?: string;
+  /** Length of the source page content before clipping. */
+  contentLength?: number;
+  /** Populated when scraping failed for this result; `content` is then absent. */
+  error?: string;
+}
+
+/** Options forwarded to `spindle.webSearch.query()`. */
+export interface WebSearchRequestDTO {
+  /** Free-text search query. Trimmed by the host; empty values are rejected. */
+  query: string;
+  /**
+   * Desired number of results. Clamped to `WebSearchSettingsDTO.maxResultCount`
+   * on the host; omit to use the user's `defaultResultCount`.
+   */
+  count?: number;
+  /**
+   * When `true` (default), the host scrapes the first
+   * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+   * `documents[].content`, and assembles the `context` block. Set to `false`
+   * to skip scraping entirely — only `results` are returned, and
+   * `documents` / `context` are omitted from the response. Useful when the
+   * extension only needs titles, URLs, and snippets.
+   */
+  scrape?: boolean;
+  /** For operator-scoped extensions; ignored on user-scoped extensions. */
+  userId?: string;
+}
+
+/**
+ * Result of a successful `spindle.webSearch.query()` call. `documents` and
+ * `context` are omitted when the request was issued with `scrape: false`.
+ */
+export interface WebSearchResponseDTO {
+  /** The (trimmed) query that was executed. */
+  query: string;
+  /** Raw normalized results from the search provider. */
+  results: WebSearchResultDTO[];
+  /** Per-result scraped page content. Absent when `scrape: false`. */
+  documents?: WebSearchDocumentDTO[];
+  /**
+   * Pre-assembled, prompt-ready context block summarizing the query plus the
+   * scraped documents. Absent when `scrape: false`.
+   */
+  context?: string;
+}
+
 // ─── Theme DTOs ──────────────────────────────────────────────────────────
 
 /**
@@ -2448,7 +2541,17 @@ export type WorkerToHost =
       model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
-    };
+    }
+  // ─── Web Search (gated: "web_search") ─────────────────────────────────
+  | {
+      type: "web_search_query";
+      requestId: string;
+      query: string;
+      count?: number;
+      scrape?: boolean;
+      userId?: string;
+    }
+  | { type: "web_search_get_settings"; requestId: string; userId?: string };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/components.ts

@@ -0,0 +1,496 @@
+/**
+ * Host-provided shared UI components.
+ *
+ * These types describe an API surface that lets a frontend extension mount
+ * instances of Lumiverse's first-party React components inside extension-owned
+ * DOM nodes (drawer tabs, float widgets, dock panels, app mounts, message
+ * widgets, etc.). The host renders the real React component into the supplied
+ * target element — extensions never need to depend on React themselves.
+ *
+ * Common shape:
+ *   - Each `mountX(target, options)` call returns a `SpindleMountedComponent`
+ *     handle scoped to the supplied target.
+ *   - Options carry initial values plus user-event callbacks (e.g. `onChange`).
+ *   - The host owns internal state and re-renders on user interaction. To
+ *     programmatically change inputs from the extension side, call
+ *     `handle.update({ ... })`. To read current state, call `handle.getValue()`
+ *     where available.
+ *   - Calling `handle.destroy()` unmounts the React tree and removes any host
+ *     resources. The supplied target element is not removed from the DOM —
+ *     extensions own placement and lifetime of the container.
+ *
+ * Components inherit the active Lumiverse theme via CSS variables, so they
+ * visually match the rest of the host UI without any additional wiring.
+ */
+
+// ──────────────────────────────────────────────────────────────────────────
+// Shared base shapes
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Common handle shape returned by every `ctx.components.mount*` call.
+ *
+ * @template TOptions Options shape used at mount time. `update()` accepts a
+ *   partial of the same shape so callers get IntelliSense for every field they
+ *   are allowed to change post-mount.
+ */
+export interface SpindleMountedComponent<TOptions> {
+  /** Host-assigned component instance ID, unique per extension. */
+  readonly componentId: string;
+  /** The container element the component was mounted into. Same node passed as `target`. */
+  readonly element: HTMLElement;
+  /**
+   * Merge a partial set of options into the live component. Pass any subset of
+   * the original mount options — undefined fields are ignored.
+   */
+  update(patch: Partial<TOptions>): void;
+  /** Unmount the React tree and release host resources. The target element is left in place. */
+  destroy(): void;
+}
+
+/** Mount-time target. Either a CSS selector resolved against the extension-owned DOM, or an Element. */
+export type SpindleComponentTarget = string | Element;
+
+/** Connection kinds the host can wire shared pickers up to. */
+export type SpindleConnectionKind = "llm" | "image" | "tts" | "embedding";
+
+/**
+ * Reference to a host-managed connection profile.
+ *
+ * When supplied to a connection-aware picker (e.g. {@link SpindleModelComboboxOptions}),
+ * the host populates available choices, loading state, and refresh behavior
+ * from its own connection registry. The extension does not need to fetch or
+ * cache anything itself.
+ */
+export interface SpindleConnectionRef {
+  /** Which connection family the picker should bind to. */
+  kind: SpindleConnectionKind;
+  /**
+   * Specific connection ID. If omitted, the host binds to the currently
+   * active connection of the given `kind` and follows live changes when the
+   * user switches active connections.
+   */
+  id?: string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Text inputs
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface SpindleTextInputOptions {
+  /** Initial value. */
+  value?: string;
+  /** Fired whenever the user changes the input. */
+  onChange?: (value: string) => void;
+  /** Placeholder text shown when value is empty. */
+  placeholder?: string;
+  /** Focus the input on mount. */
+  autoFocus?: boolean;
+  /** Disable user interaction. */
+  disabled?: boolean;
+  /** Additional CSS class merged onto the input element. */
+  className?: string;
+  /** Optional accessible label. Surfaces as `aria-label` on the input. */
+  ariaLabel?: string;
+}
+
+export interface SpindleTextInputHandle extends SpindleMountedComponent<SpindleTextInputOptions> {
+  /** Read the current value. */
+  getValue(): string;
+  /** Programmatically focus the input. */
+  focus(): void;
+  /** Programmatically blur the input. */
+  blur(): void;
+}
+
+export interface SpindleTextAreaOptions {
+  value?: string;
+  onChange?: (value: string) => void;
+  placeholder?: string;
+  /** Visible row count. Default: `4`. */
+  rows?: number;
+  disabled?: boolean;
+  className?: string;
+  ariaLabel?: string;
+}
+
+export interface SpindleTextAreaHandle extends SpindleMountedComponent<SpindleTextAreaOptions> {
+  getValue(): string;
+  focus(): void;
+  blur(): void;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Numeric inputs
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface SpindleNumericInputOptions {
+  /** Initial value, or `null` for empty. */
+  value?: number | null;
+  /** Fired whenever the value changes. `null` means the field is empty. */
+  onChange?: (value: number | null) => void;
+  /** Allow the field to be empty (`null`). Default: `false`. */
+  allowEmpty?: boolean;
+  /** Restrict input to integers. Default: `false`. */
+  integer?: boolean;
+  /** Minimum allowed value. */
+  min?: number;
+  /** Maximum allowed value. */
+  max?: number;
+  /** Step size used by the underlying `<input type="number">`. */
+  step?: number;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  ariaLabel?: string;
+}
+
+export interface SpindleNumericInputHandle extends SpindleMountedComponent<SpindleNumericInputOptions> {
+  getValue(): number | null;
+  focus(): void;
+  blur(): void;
+}
+
+export interface SpindleNumberStepperOptions {
+  value?: number | null;
+  onChange?: (value: number | null) => void;
+  min?: number;
+  max?: number;
+  /** Increment/decrement step. Default: `1`. */
+  step?: number;
+  allowEmpty?: boolean;
+  integer?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SpindleNumberStepperHandle extends SpindleMountedComponent<SpindleNumberStepperOptions> {
+  getValue(): number | null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Boolean inputs
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface SpindleCheckboxOptions {
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  /** Label rendered next to the checkbox. */
+  label?: string;
+  /** Optional helper text rendered below the label. */
+  hint?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SpindleCheckboxHandle extends SpindleMountedComponent<SpindleCheckboxOptions> {
+  getValue(): boolean;
+}
+
+export interface SpindleSwitchOptions {
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  /** Visual size. Default: `"md"`. */
+  size?: "sm" | "md";
+  disabled?: boolean;
+  className?: string;
+  ariaLabel?: string;
+}
+
+export interface SpindleSwitchHandle extends SpindleMountedComponent<SpindleSwitchOptions> {
+  getValue(): boolean;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Pickers & selects
+// ──────────────────────────────────────────────────────────────────────────
+
+/** A single option in a select-style picker. */
+export interface SpindleSelectOption {
+  /** Stable value emitted to `onChange`. */
+  value: string;
+  /** Display label. */
+  label: string;
+  /** Secondary text rendered beneath the label. */
+  sublabel?: string;
+  /** Group key. Options sharing a group are visually clustered with a header. */
+  group?: string;
+  /** Render as disabled. */
+  disabled?: boolean;
+}
+
+export interface SpindleSelectOptionsBase {
+  /** Available options. */
+  options?: SpindleSelectOption[];
+  /** Placeholder text shown when no value is selected. */
+  placeholder?: string;
+  /** Placeholder for the search field inside the dropdown. */
+  searchPlaceholder?: string;
+  /** Minimum option count before the search field is shown. Default: `8`. */
+  searchThreshold?: number;
+  /** Message rendered when the filtered option list is empty. */
+  emptyMessage?: string;
+  /**
+   * Render the dropdown into a React portal anchored to `document.body` so it
+   * escapes containers with `overflow:hidden`. Default: `true`.
+   */
+  portal?: boolean;
+  /** Dropdown horizontal alignment relative to the trigger. Default: `"left"`. */
+  align?: "left" | "right";
+  /** Maximum dropdown height in CSS pixels. */
+  maxHeight?: number;
+  /** Minimum dropdown width in CSS pixels. */
+  minWidth?: number;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SpindleSelectOptions extends SpindleSelectOptionsBase {
+  /** Initial value. */
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+export interface SpindleSelectHandle extends SpindleMountedComponent<SpindleSelectOptions> {
+  getValue(): string;
+  /** Open the dropdown programmatically. */
+  open(): void;
+  /** Close the dropdown programmatically. */
+  close(): void;
+}
+
+export interface SpindleMultiSelectOptions extends SpindleSelectOptionsBase {
+  /** Initial value. */
+  value?: string[];
+  onChange?: (value: string[]) => void;
+}
+
+export interface SpindleMultiSelectHandle extends SpindleMountedComponent<SpindleMultiSelectOptions> {
+  getValue(): string[];
+  open(): void;
+  close(): void;
+}
+
+/**
+ * Connection-aware model picker.
+ *
+ * **Recommended (connection-bound) mode:** supply `connection` and the host
+ * will populate `models`, drive the refresh button, manage loading state, and
+ * react to live connection changes.
+ *
+ * **Manual mode:** supply `models`, `loading`, and `onRefresh` directly. Use
+ * this when the extension fetches model lists from its own backend or proxy.
+ *
+ * The two modes are mutually exclusive. If both `connection` and `models` are
+ * supplied, `connection` wins and the manual fields are ignored.
+ */
+export interface SpindleModelComboboxOptions {
+  /** Currently entered model ID. */
+  value?: string;
+  /** Fired when the user types or selects a model. */
+  onChange?: (value: string) => void;
+
+  /**
+   * Bind to a host-managed connection. The host populates the model list,
+   * handles the refresh affordance, and reports loading state automatically.
+   *
+   * Pass just `{ kind }` to follow the user's currently active connection of
+   * that kind. Pass `{ kind, id }` to pin to a specific connection.
+   */
+  connection?: SpindleConnectionRef;
+
+  /** Manual mode: explicit model list. Ignored when `connection` is set. */
+  models?: string[];
+  /** Manual mode: optional map of model ID → human-readable label. */
+  modelLabels?: Record<string, string>;
+  /** Manual mode: surface the host spinner inside the refresh affordance. */
+  loading?: boolean;
+  /** Manual mode: render a refresh button that invokes this handler when clicked. */
+  onRefresh?: () => void;
+
+  /** Trigger an auto-refresh the first time the input gains focus (manual mode only). */
+  autoRefreshOnFocus?: boolean;
+  /** Opaque key — when it changes, the host re-arms the autoRefreshOnFocus guard. */
+  refreshKey?: string;
+
+  /** Visual density. `"compact"` matches inline rows; `"standard"` matches form rows; `"editor"` matches the prompt editor. */
+  appearance?: "compact" | "standard" | "editor";
+  placeholder?: string;
+  emptyMessage?: string;
+  loadingMessage?: string;
+  /** Optional hint shown beneath the input (e.g. "Search the catalog"). */
+  browseHint?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SpindleModelComboboxHandle extends SpindleMountedComponent<SpindleModelComboboxOptions> {
+  getValue(): string;
+  /** Force a refresh of the host-managed model list. No-op in manual mode unless `onRefresh` is set. */
+  refresh(): void;
+}
+
+export interface SpindleFolderDropdownOptions {
+  /** Available folder names. */
+  folders?: string[];
+  /** Currently selected folder. */
+  value?: string;
+  onChange?: (folder: string) => void;
+  /** Fired when the user creates a new folder via the inline affordance. */
+  onCreateFolder?: (name: string) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SpindleFolderDropdownHandle extends SpindleMountedComponent<SpindleFolderDropdownOptions> {
+  getValue(): string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Display & layout
+// ──────────────────────────────────────────────────────────────────────────
+
+export type SpindleBadgeColor = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
+
+export interface SpindleBadgeOptions {
+  /** Badge text. */
+  text?: string;
+  /** Accent color. Default: `"neutral"`. */
+  color?: SpindleBadgeColor;
+  /** Visual size. Default: `"md"`. */
+  size?: "sm" | "md" | "pill";
+  className?: string;
+}
+
+export type SpindleBadgeHandle = SpindleMountedComponent<SpindleBadgeOptions>;
+
+export interface SpindleSpinnerOptions {
+  /** Diameter in CSS pixels. Default: `16`. */
+  size?: number;
+  /** Use the faster rotation variant for impatient contexts. */
+  fast?: boolean;
+  className?: string;
+}
+
+export type SpindleSpinnerHandle = SpindleMountedComponent<SpindleSpinnerOptions>;
+
+export interface SpindleCollapsibleSectionOptions {
+  /** Section title rendered in the collapsible header. */
+  title: string;
+  /** Inline SVG string for an optional leading icon. */
+  iconSvg?: string;
+  /** URL to an icon image. Mutually exclusive with `iconSvg`. */
+  iconUrl?: string;
+  /** Optional badge text shown next to the title. */
+  badge?: string | number;
+  /** Initial expanded state. Default: `true`. */
+  defaultExpanded?: boolean;
+  /** Fired whenever the user toggles the section. */
+  onToggle?: (expanded: boolean) => void;
+  className?: string;
+}
+
+export interface SpindleCollapsibleSectionHandle extends SpindleMountedComponent<SpindleCollapsibleSectionOptions> {
+  /**
+   * Body container the extension owns. Append child elements here — the host
+   * renders the collapsible chrome around them.
+   */
+  readonly body: HTMLElement;
+  /** Returns the current expanded state. */
+  isExpanded(): boolean;
+  /** Expand the section. */
+  expand(): void;
+  /** Collapse the section. */
+  collapse(): void;
+  /** Toggle the section. */
+  toggle(): void;
+}
+
+export interface SpindlePaginationOptions {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  /** Optional items-per-page selector. Omit to hide the selector entirely. */
+  perPage?: number;
+  perPageOptions?: number[];
+  onPerPageChange?: (perPage: number) => void;
+  /** Total item count for the "Showing X–Y of N" summary. Omit to hide the summary. */
+  totalItems?: number;
+  className?: string;
+}
+
+export type SpindlePaginationHandle = SpindleMountedComponent<SpindlePaginationOptions>;
+
+export interface SpindleCloseButtonOptions {
+  onClick?: () => void;
+  /** Visual size. Default: `"md"`. */
+  size?: "sm" | "md";
+  /** Visual variant. Default: `"subtle"`. */
+  variant?: "subtle" | "solid";
+  /** Positioning behavior. Default: `"static"`. */
+  position?: "static" | "absolute";
+  /** Icon size override in CSS pixels. */
+  iconSize?: number;
+  ariaLabel?: string;
+  className?: string;
+}
+
+export type SpindleCloseButtonHandle = SpindleMountedComponent<SpindleCloseButtonOptions>;
+
+// ──────────────────────────────────────────────────────────────────────────
+// Aggregator
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mount points for host-rendered shared components.
+ *
+ * Each method takes a `target` (the DOM node or selector inside the
+ * extension-owned tree to render into) and an `options` object. The returned
+ * handle exposes `update()`, `destroy()`, and component-specific helpers.
+ *
+ * @example
+ * ```ts
+ * // Inside a drawer tab
+ * const tab = ctx.ui.registerDrawerTab({ id: "settings", title: "My Tab" })
+ * const wrap = ctx.dom.createElement("div")
+ * tab.root.appendChild(wrap)
+ *
+ * const picker = ctx.components.mountModelCombobox(wrap, {
+ *   value: "",
+ *   connection: { kind: "llm" },
+ *   appearance: "standard",
+ *   onChange: (model) => ctx.sendToBackend({ type: "set_model", model }),
+ * })
+ *
+ * // Later — force the input to a specific value
+ * picker.update({ value: "claude-opus-4-7" })
+ * ```
+ */
+export interface SpindleComponentsHelper {
+  // Text inputs
+  mountTextInput(target: SpindleComponentTarget, options?: SpindleTextInputOptions): SpindleTextInputHandle;
+  mountTextArea(target: SpindleComponentTarget, options?: SpindleTextAreaOptions): SpindleTextAreaHandle;
+
+  // Numeric inputs
+  mountNumericInput(target: SpindleComponentTarget, options?: SpindleNumericInputOptions): SpindleNumericInputHandle;
+  mountNumberStepper(target: SpindleComponentTarget, options?: SpindleNumberStepperOptions): SpindleNumberStepperHandle;
+
+  // Boolean inputs
+  mountCheckbox(target: SpindleComponentTarget, options?: SpindleCheckboxOptions): SpindleCheckboxHandle;
+  mountSwitch(target: SpindleComponentTarget, options?: SpindleSwitchOptions): SpindleSwitchHandle;
+
+  // Pickers & selects
+  mountSelect(target: SpindleComponentTarget, options: SpindleSelectOptions): SpindleSelectHandle;
+  mountMultiSelect(target: SpindleComponentTarget, options: SpindleMultiSelectOptions): SpindleMultiSelectHandle;
+  mountModelCombobox(target: SpindleComponentTarget, options: SpindleModelComboboxOptions): SpindleModelComboboxHandle;
+  mountFolderDropdown(target: SpindleComponentTarget, options: SpindleFolderDropdownOptions): SpindleFolderDropdownHandle;
+
+  // Display & layout
+  mountBadge(target: SpindleComponentTarget, options: SpindleBadgeOptions): SpindleBadgeHandle;
+  mountSpinner(target: SpindleComponentTarget, options?: SpindleSpinnerOptions): SpindleSpinnerHandle;
+  mountCollapsibleSection(target: SpindleComponentTarget, options: SpindleCollapsibleSectionOptions): SpindleCollapsibleSectionHandle;
+  mountPagination(target: SpindleComponentTarget, options: SpindlePaginationOptions): SpindlePaginationHandle;
+  mountCloseButton(target: SpindleComponentTarget, options?: SpindleCloseButtonOptions): SpindleCloseButtonHandle;
+}

package/src/dom.ts

@@ -1,4 +1,5 @@
 import type { RequestInitDTO } from "./api";
+import type { SpindleComponentsHelper } from "./components";
 
 /** DOM helper API provided to frontend extension modules. */
 export interface SpindleDOMHelper {
@@ -598,6 +599,14 @@ export interface SpindleFrontendContext {
      */
     showConfirm(options: SpindleConfirmOptions): Promise<SpindleConfirmResult>;
   };
+  /**
+   * Mount instances of Lumiverse's first-party shared UI components (form
+   * atoms, model picker, select, pagination, etc.) inside extension-owned DOM.
+   * The host renders real React components into the supplied container — the
+   * extension never needs to depend on React directly. See
+   * {@link SpindleComponentsHelper} for the full surface.
+   */
+  components: SpindleComponentsHelper;
   uploads: {
     pickFile(options?: {
       accept?: string[];

package/src/index.ts

@@ -155,6 +155,12 @@ export type {
   MessageContentProcessorOrigin,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
+  WebSearchProviderDTO,
+  WebSearchSettingsDTO,
+  WebSearchResultDTO,
+  WebSearchDocumentDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";
@@ -208,6 +214,47 @@ export type {
     SpindleFrontendProcessRegistry,
  } from "./dom";
 
+export type {
+  SpindleMountedComponent,
+  SpindleComponentTarget,
+  SpindleConnectionKind,
+  SpindleConnectionRef,
+  SpindleTextInputOptions,
+  SpindleTextInputHandle,
+  SpindleTextAreaOptions,
+  SpindleTextAreaHandle,
+  SpindleNumericInputOptions,
+  SpindleNumericInputHandle,
+  SpindleNumberStepperOptions,
+  SpindleNumberStepperHandle,
+  SpindleCheckboxOptions,
+  SpindleCheckboxHandle,
+  SpindleSwitchOptions,
+  SpindleSwitchHandle,
+  SpindleSelectOption,
+  SpindleSelectOptionsBase,
+  SpindleSelectOptions,
+  SpindleSelectHandle,
+  SpindleMultiSelectOptions,
+  SpindleMultiSelectHandle,
+  SpindleModelComboboxOptions,
+  SpindleModelComboboxHandle,
+  SpindleFolderDropdownOptions,
+  SpindleFolderDropdownHandle,
+  SpindleBadgeColor,
+  SpindleBadgeOptions,
+  SpindleBadgeHandle,
+  SpindleSpinnerOptions,
+  SpindleSpinnerHandle,
+  SpindleCollapsibleSectionOptions,
+  SpindleCollapsibleSectionHandle,
+  SpindlePaginationOptions,
+  SpindlePaginationHandle,
+  SpindleCloseButtonOptions,
+  SpindleCloseButtonHandle,
+  SpindleComponentsHelper,
+} from "./components";
+
 export type { ExtensionInfo } from "./extension-info";
 
 export type {

package/src/permissions.ts

@@ -19,6 +19,9 @@
  *                            links, consolidations) and long-term chat memory (vectorized
  *                            chat-chunk retrieval, warmup, cache).
  * - "macro_interceptor"    — transform raw templates before macro parsing/dispatch
+ * - "web_search"           — execute searches via the user's configured web search
+ *                            provider (e.g. SearXNG) and read the safe view of their
+ *                            web search settings (never the API key).
  */
 export type SpindlePermission =
   | "generation"
@@ -44,7 +47,8 @@ export type SpindlePermission =
   | "image_gen"
   | "images"
   | "generation_parameters"
-  | "macro_interceptor";
+  | "macro_interceptor"
+  | "web_search";
 
 export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "generation",
@@ -71,6 +75,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "images",
   "generation_parameters",
   "macro_interceptor",
+  "web_search",
 ] as const;
 
 export function isValidPermission(p: string): p is SpindlePermission {

package/src/spindle-api.ts

@@ -103,6 +103,9 @@ import type {
   MessageContentProcessorResultDTO,
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
+  WebSearchSettingsDTO,
 } from "./api";
 import type {
   ChatChunkDTO,
@@ -1370,6 +1373,74 @@ export interface SpindleAPI {
     }>;
   };
 
+  /**
+   * Web search (permission: `"web_search"`).
+   *
+   * Execute searches via the user's configured web search provider
+   * (currently SearXNG; additional providers will be added over time) and
+   * read the safe view of their web search settings. The host enforces all
+   * upstream limits (engine list, max result count, max pages to scrape,
+   * timeouts) — extensions cannot supply their own endpoint or API key.
+   *
+   * For user-scoped extensions, `userId` is inferred from the extension
+   * owner. Operator-scoped extensions should pass the `userId` of the user
+   * whose search engine should run the query.
+   *
+   * @example
+   * ```ts
+   * // Pre-flight: confirm web search is configured before issuing a query.
+   * const settings = await spindle.webSearch.getSettings()
+   * if (!settings.enabled) {
+   *   spindle.toast.warning('Configure a web search provider in Settings → Web Search first.')
+   *   return
+   * }
+   *
+   * // Full enriched query — scrapes the top-N pages and returns a
+   * // ready-to-inject context block.
+   * const enriched = await spindle.webSearch.query({
+   *   query: 'latest LLM benchmark results',
+   *   count: 5,
+   * })
+   * await spindle.chat.appendMessage(chatId, {
+   *   role: 'system',
+   *   content: enriched.context ?? '',
+   * })
+   *
+   * // Lightweight query — titles, URLs, snippets only.
+   * const quick = await spindle.webSearch.query({
+   *   query: 'who won the 2026 world cup',
+   *   scrape: false,
+   * })
+   * for (const row of quick.results) {
+   *   spindle.log.info(`${row.title} — ${row.url}`)
+   * }
+   * ```
+   */
+  webSearch: {
+    /**
+     * Run a search against the user's configured provider.
+     *
+     * Rejects with `"Web search is disabled"` when the user has not
+     * configured a provider, and with `"Web search API URL is not configured"`
+     * when the upstream endpoint is missing. Other upstream errors surface
+     * as `Error("SearXNG returned HTTP NNN")` (or equivalent for future
+     * providers).
+     *
+     * When `input.scrape` is `false`, `documents` and `context` are omitted
+     * from the response. Otherwise the host scrapes up to
+     * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+     * `documents[].content`, and assembles a prompt-ready `context` block.
+     */
+    query(input: WebSearchRequestDTO): Promise<WebSearchResponseDTO>;
+    /**
+     * Read the safe view of the user's web search configuration. The raw
+     * API key is never exposed — only `hasApiKey` indicates whether one is
+     * on file. Useful for branching on `enabled` / `provider` /
+     * `maxResultCount` before issuing a query.
+     */
+    getSettings(userId?: string): Promise<WebSearchSettingsDTO>;
+  };
+
   /**
    * Text editor (free tier — no permission needed).
    * Opens the native Lumiverse expanded text editor modal on the user's