@pupt/react 0.0.1 → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,922 @@
+import { CHILDREN } from '@pupt/lib';
+import { Component } from '@pupt/lib';
+import { COMPONENT_MARKER } from '@pupt/lib';
+import { Context } from 'react';
+import { createRuntimeConfig } from '@pupt/lib';
+import { DEFERRED_REF } from '@pupt/lib';
+import { DeferredRef } from '@pupt/lib';
+import { DiscoveredPromptWithMethods } from '@pupt/lib';
+import { EnvironmentContext } from '@pupt/lib';
+import { evaluateFormula } from '@pupt/lib';
+import { InputRequirement } from '@pupt/lib';
+import { isComponentClass } from '@pupt/lib';
+import { isDeferredRef } from '@pupt/lib';
+import { isPuptElement } from '@pupt/lib';
+import { ModuleEntry } from '@pupt/lib';
+import { OnMissingDefaultStrategy } from '@pupt/lib';
+import { PostExecutionAction } from '@pupt/lib';
+import { PROPS } from '@pupt/lib';
+import { PuptElement } from '@pupt/lib';
+import { PuptInitConfig } from '@pupt/lib';
+import { PuptNode } from '@pupt/lib';
+import { RenderError } from '@pupt/lib';
+import { RenderOptions } from '@pupt/lib';
+import { RenderResult } from '@pupt/lib';
+import { RuntimeConfig } from '@pupt/lib';
+import { SearchablePrompt } from '@pupt/lib';
+import { SearchEngine } from '@pupt/lib';
+import { SearchEngineConfig } from '@pupt/lib';
+import { SearchOptions } from '@pupt/lib';
+import { SearchResult } from '@pupt/lib';
+import { TYPE } from '@pupt/lib';
+import { ValidationResult } from '@pupt/lib';
+
+/**
+ * Headless component for collecting user input through Ask components.
+ *
+ * Wraps the useAskIterator hook and adds getInputProps for generating
+ * accessible input element props.
+ *
+ * @example
+ * ```tsx
+ * <AskHandler element={element} onComplete={(values) => console.log(values)}>
+ *   {({ current, submit, progress, getInputProps }) => {
+ *     if (!current) return <div>Loading...</div>;
+ *     const { inputProps } = getInputProps(current.name);
+ *     return (
+ *       <div>
+ *         <label>{current.label}</label>
+ *         <input {...inputProps} />
+ *         <span>{progress}% complete</span>
+ *       </div>
+ *     );
+ *   }}
+ * </AskHandler>
+ * ```
+ */
+export declare function AskHandler({ children, element, onComplete, initialValues }: AskHandlerProps): React.ReactElement;
+
+/**
+ * Props for AskHandler component
+ */
+export declare interface AskHandlerProps {
+    /** Render function receiving handler state */
+    children: (props: AskHandlerRenderProps) => React.ReactNode;
+    /** The PuptElement containing Ask components */
+    element: PuptElement | null;
+    /** Called when all inputs have been collected */
+    onComplete?: (values: Map<string, unknown>) => void;
+    /** Pre-supplied initial values */
+    initialValues?: Map<string, unknown>;
+}
+
+/**
+ * Render props provided by AskHandler
+ */
+export declare interface AskHandlerRenderProps {
+    /** All input requirements */
+    requirements: InputRequirement[];
+    /** The current input requirement being collected */
+    current: InputRequirement | null;
+    /** Current step index */
+    currentIndex: number;
+    /** Total number of inputs */
+    totalInputs: number;
+    /** Progress as a percentage (0-100) */
+    progress: number;
+    /** Whether all inputs have been collected */
+    isDone: boolean;
+    /** Whether the handler is initializing */
+    isLoading: boolean;
+    /** All collected values */
+    values: Map<string, unknown>;
+    /** Submit a value for the current input */
+    submit: (value: unknown) => Promise<ValidationResult>;
+    /** Go to the previous input */
+    previous: () => void;
+    /** Go to a specific input by index */
+    goTo: (index: number) => void;
+    /** Reset all inputs */
+    reset: () => void;
+    /** Get input props for a specific field by name */
+    getInputProps: (name: string) => AskInputProps;
+}
+
+/**
+ * Input props helper returned by AskHandler.getInputProps
+ */
+export declare interface AskInputProps {
+    /** Props to spread onto an input element */
+    inputProps: {
+        id: string;
+        name: string;
+        type: string;
+        required: boolean;
+        "aria-label": string;
+    };
+    /** The input requirement metadata */
+    requirement: InputRequirement;
+    /** The current value for this input */
+    value: unknown;
+    /** Set the value for this input */
+    setValue: (value: unknown) => void;
+    /** Validation errors for this input */
+    errors: string[];
+}
+
+export { CHILDREN }
+
+export { Component }
+
+export { COMPONENT_MARKER }
+
+export { createRuntimeConfig }
+
+export { DEFERRED_REF }
+
+export { DeferredRef }
+
+export { DiscoveredPromptWithMethods }
+
+export { EnvironmentContext }
+
+export { evaluateFormula }
+
+/**
+ * Extract input requirements from a PuptElement by traversing its tree
+ * and finding Ask components.
+ *
+ * Uses createInputIterator with validation disabled, submitting placeholder
+ * values to advance through all requirements.
+ *
+ * @param element - The PuptElement to extract requirements from
+ * @param options - Optional configuration including pre-supplied values
+ * @returns Array of InputRequirement objects
+ */
+export declare function extractInputRequirements(element: PuptElement, options?: ExtractOptions): Promise<InputRequirement[]>;
+
+/**
+ * Options for extractInputRequirements
+ */
+declare interface ExtractOptions {
+    /** Pre-supply values to skip during iteration */
+    values?: Record<string, unknown>;
+}
+
+export { InputRequirement }
+
+/**
+ * Check if a PuptElement type represents an Ask component
+ */
+export declare function isAskComponent(type: string | symbol): boolean;
+
+export { isComponentClass }
+
+export { isDeferredRef }
+
+/**
+ * Type guard to check if a value is a PuptElement
+ */
+export declare function isElement(value: unknown): value is PuptElement;
+
+export { isPuptElement }
+
+export { OnMissingDefaultStrategy }
+
+/**
+ * Handler function for a post-execution action
+ */
+export declare type PostActionHandler = (action: PostExecutionAction) => void | Promise<void>;
+
+export { PostExecutionAction }
+
+/**
+ * Headless component that provides state and props for a prompt source editor.
+ *
+ * Uses the render-prop pattern to give consumers full control over the UI
+ * while managing source value state and transformation.
+ *
+ * @example
+ * ```tsx
+ * <PromptEditor defaultValue="<Prompt>Hello</Prompt>">
+ *   {({ inputProps, error, isTransforming }) => (
+ *     <div>
+ *       <textarea {...inputProps} />
+ *       {isTransforming && <span>Transforming...</span>}
+ *       {error && <span>{error.message}</span>}
+ *     </div>
+ *   )}
+ * </PromptEditor>
+ * ```
+ */
+export declare function PromptEditor({ children, defaultValue, onChange, debounce, }: PromptEditorProps): React.ReactElement;
+
+/**
+ * Props for PromptEditor component
+ */
+export declare interface PromptEditorProps {
+    /** Render function receiving editor state */
+    children: (props: PromptEditorRenderProps) => React.ReactNode;
+    /** Default source value */
+    defaultValue?: string;
+    /** Called when the source value changes */
+    onChange?: (value: string) => void;
+    /** Debounce delay for transformation in ms (default: 300) */
+    debounce?: number;
+}
+
+/**
+ * Render props provided by PromptEditor
+ */
+export declare interface PromptEditorRenderProps {
+    /** Props to spread onto the textarea/input element */
+    inputProps: {
+        value: string;
+        onChange: (e: React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void;
+    };
+    /** The current source value */
+    value: string;
+    /** Set the source value directly */
+    setValue: (value: string) => void;
+    /** The transformed PuptElement (null if transformation failed or pending) */
+    element: PuptElement | null;
+    /** Transformation error */
+    error: Error | null;
+    /** Whether transformation is in progress */
+    isTransforming: boolean;
+}
+
+/**
+ * Headless component that renders a prompt and provides the result via render props.
+ *
+ * Wraps the usePromptRender hook and adds clipboard copy functionality.
+ *
+ * @example
+ * ```tsx
+ * <PromptRenderer source="<Prompt><Task>Hello</Task></Prompt>" autoRender>
+ *   {({ output, copyToClipboard, isCopied }) => (
+ *     <div>
+ *       <pre>{output}</pre>
+ *       <button onClick={copyToClipboard}>
+ *         {isCopied ? 'Copied!' : 'Copy'}
+ *       </button>
+ *     </div>
+ *   )}
+ * </PromptRenderer>
+ * ```
+ */
+export declare function PromptRenderer({ children, source, autoRender, inputs, renderOptions, environment, filename, }: PromptRendererProps): React.ReactElement;
+
+/**
+ * Props for PromptRenderer component
+ */
+export declare interface PromptRendererProps {
+    /** Render function receiving renderer state */
+    children: (props: PromptRendererRenderProps) => React.ReactNode;
+    /** Prompt source (string or element) */
+    source: PromptSource | string;
+    /** Whether to automatically render when source changes (default: true) */
+    autoRender?: boolean;
+    /** Input values for Ask components */
+    inputs?: Map<string, unknown>;
+    /** Render options */
+    renderOptions?: Partial<RenderOptions>;
+    /** Environment context */
+    environment?: Partial<EnvironmentContext>;
+    /** Filename hint for source transformation (e.g. "prompt.prompt" or "prompt.tsx").
+     *  Controls whether pupt-lib auto-injects imports for built-in components.
+     *  Defaults to "prompt.tsx". Use "prompt.prompt" for raw JSX without imports. */
+    filename?: string;
+}
+
+/**
+ * Render props provided by PromptRenderer
+ */
+export declare interface PromptRendererRenderProps {
+    /** The rendered text output */
+    output: string | null;
+    /** Whether the prompt is ready (has output and no pending inputs) */
+    isReady: boolean;
+    /** Whether rendering is in progress */
+    isLoading: boolean;
+    /** Rendering error */
+    error: Error | null;
+    /** Input requirements from Ask components */
+    pendingInputs: InputRequirement[];
+    /** Post-execution actions from the rendered prompt */
+    postActions: PostExecutionAction[];
+    /** Copy the rendered output to the clipboard */
+    copyToClipboard: () => Promise<void>;
+    /** Whether the output was recently copied */
+    isCopied: boolean;
+    /** Manually trigger a re-render */
+    render: () => Promise<void>;
+}
+
+/**
+ * Source for prompt rendering - either raw source code or pre-parsed element
+ */
+export declare type PromptSource = {
+    type: "source";
+    value: string;
+} | {
+    type: "element";
+    value: PuptElement;
+};
+
+export { PROPS }
+
+/**
+ * React context for pupt-lib functionality
+ *
+ * Provides access to:
+ * - SearchEngine for prompt searching
+ * - Default render options
+ * - Environment context
+ *
+ * @example
+ * ```tsx
+ * import { useContext } from 'react';
+ * import { PuptContext } from '@pupt/react';
+ *
+ * function MyComponent() {
+ *   const { searchEngine, isLoading, error } = useContext(PuptContext);
+ *   // ...
+ * }
+ * ```
+ */
+export declare const PuptContext: Context<PuptContextValue>;
+
+/**
+ * Value provided by PuptContext
+ */
+export declare interface PuptContextValue {
+    /** Internal marker indicating provider is present (not exposed to consumers) */
+    _initialized: boolean;
+    /** Search engine for finding prompts (null if no prompts provided) */
+    searchEngine: SearchEngine | null;
+    /** All indexed prompts (empty array if no prompts provided) */
+    prompts: SearchablePrompt[];
+    /** Default render options */
+    renderOptions: Partial<RenderOptions>;
+    /** Environment context */
+    environment: Partial<EnvironmentContext>;
+    /** Loading state during initialization */
+    isLoading: boolean;
+    /** Error state if initialization failed */
+    error: Error | null;
+}
+
+export { PuptElement }
+
+export { PuptInitConfig }
+
+/**
+ * Context value for PuptLibraryProvider
+ */
+export declare const PuptLibraryContext: Context<UsePuptLibraryReturn | null>;
+
+/**
+ * Provider component that wraps usePuptLibrary and provides library state via context.
+ *
+ * @example
+ * ```tsx
+ * <PuptLibraryProvider modules={["@my-org/prompts"]}>
+ *   <MyApp />
+ * </PuptLibraryProvider>
+ * ```
+ */
+export declare function PuptLibraryProvider({ children, modules, searchConfig }: PuptLibraryProviderProps): React.ReactElement;
+
+/**
+ * Props for PuptLibraryProvider
+ */
+declare interface PuptLibraryProviderProps extends UsePuptLibraryOptions {
+    children: React.ReactNode;
+}
+
+export { PuptNode }
+
+/**
+ * Provider component that initializes pupt-lib and provides context to children
+ *
+ * @example
+ * ```tsx
+ * import { PuptProvider } from '@pupt/react';
+ *
+ * function App() {
+ *   return (
+ *     <PuptProvider>
+ *       <MyComponent />
+ *     </PuptProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With prompts for search:
+ * ```tsx
+ * const prompts = [
+ *   { name: 'greeting', description: 'A greeting prompt', tags: ['hello'] }
+ * ];
+ *
+ * function App() {
+ *   return (
+ *     <PuptProvider prompts={prompts}>
+ *       <MyComponent />
+ *     </PuptProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function PuptProvider({ children, prompts, searchConfig, renderOptions, environment, }: PuptProviderProps): React.ReactElement;
+
+/**
+ * Props for PuptProvider component
+ */
+export declare interface PuptProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Initial prompts to index for search */
+    prompts?: SearchablePrompt[];
+    /** Configuration for the search engine (threshold, weights, fuzzy matching, etc.) */
+    searchConfig?: SearchEngineConfig;
+    /** Default render options to use for all renders */
+    renderOptions?: Partial<RenderOptions>;
+    /** Environment context */
+    environment?: Partial<EnvironmentContext>;
+}
+
+export { RenderOptions }
+
+export { RenderResult }
+
+export { RuntimeConfig }
+
+export { SearchablePrompt }
+
+export { SearchEngineConfig }
+
+export { SearchOptions }
+
+export { SearchResult }
+
+/**
+ * Options for transformSource function
+ */
+declare interface TransformOptions {
+    /** Filename for error messages (default: "prompt.tsx") */
+    filename?: string;
+}
+
+/**
+ * Transform source code string into a PuptElement.
+ * Delegates to pupt-lib's createPromptFromSource.
+ *
+ * @param source - TSX/JSX source code (should export default a PuptElement)
+ * @param options - Transform options including filename
+ * @returns Promise resolving to the transformed PuptElement
+ */
+export declare function transformSource(source: string, options?: TransformOptions): Promise<PuptElement>;
+
+/**
+ * Recursively traverse a PuptElement tree and call a visitor function
+ * for each element.
+ */
+export declare function traverseElement(element: PuptElement, visitor: (element: PuptElement) => void): void;
+
+export { TYPE }
+
+/**
+ * Hook for iterating through Ask components in a PuptElement and collecting
+ * validated user input.
+ *
+ * Provides a wizard-like interface for stepping through input requirements,
+ * validating submissions, and navigating back to previous inputs.
+ *
+ * @param options - Configuration including the element to iterate and callbacks
+ * @returns Object containing current state, navigation, and submission functions
+ *
+ * @example
+ * ```tsx
+ * function InputCollector({ element }) {
+ *   const { current, submit, isDone, inputs } = useAskIterator({ element });
+ *
+ *   if (isDone) return <div>All inputs collected!</div>;
+ *   if (!current) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <label>{current.label}</label>
+ *       <input onKeyDown={(e) => {
+ *         if (e.key === 'Enter') submit(e.currentTarget.value);
+ *       }} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAskIterator(options: UseAskIteratorOptions): UseAskIteratorReturn;
+
+/**
+ * Options for useAskIterator hook
+ */
+export declare interface UseAskIteratorOptions {
+    /** The PuptElement to extract Ask components from */
+    element: PuptElement | null;
+    /** Callback when all inputs have been collected */
+    onComplete?: (values: Map<string, unknown>) => void;
+    /** Pre-supplied initial values for inputs */
+    initialValues?: Map<string, unknown>;
+    /** Pre-supply values that skip interactive iteration */
+    preSuppliedValues?: Record<string, unknown>;
+    /** Enable non-interactive mode to auto-fill with defaults */
+    nonInteractive?: boolean;
+    /** Strategy when required input has no default in non-interactive mode */
+    onMissingDefault?: OnMissingDefaultStrategy;
+}
+
+/**
+ * Return value of useAskIterator hook
+ */
+export declare interface UseAskIteratorReturn {
+    /** All input requirements extracted from the element */
+    requirements: InputRequirement[];
+    /** The current input requirement being collected */
+    current: InputRequirement | null;
+    /** Index of the current requirement */
+    currentIndex: number;
+    /** Total number of input requirements */
+    totalInputs: number;
+    /** Whether all inputs have been collected */
+    isDone: boolean;
+    /** Whether the iterator is initializing */
+    isLoading: boolean;
+    /** All collected input values */
+    inputs: Map<string, unknown>;
+    /** Submit a value for the current input, returns validation result */
+    submit: (value: unknown) => Promise<ValidationResult>;
+    /** Navigate to the previous input */
+    previous: () => void;
+    /** Navigate to a specific input index */
+    goTo: (index: number) => void;
+    /** Reset all collected inputs and go back to the first */
+    reset: () => void;
+    /** Set a value for a specific input by name */
+    setValue: (name: string, value: unknown) => void;
+    /** Get the value for a specific input by name */
+    getValue: (name: string) => unknown;
+    /** Run all inputs non-interactively using defaults and pre-supplied values */
+    runNonInteractive: () => Promise<Map<string, unknown>>;
+}
+
+/**
+ * Hook for evaluating Excel-style formulas reactively against input values.
+ *
+ * Re-evaluates automatically when the formula string or inputs Map changes.
+ *
+ * @param options - Formula string and input values
+ * @returns Object containing the boolean result and any evaluation error
+ *
+ * @example
+ * ```tsx
+ * function ConditionalSection({ inputs }) {
+ *   const { result } = useFormula({
+ *     formula: "=count>5",
+ *     inputs,
+ *   });
+ *
+ *   if (!result) return null;
+ *   return <div>Count exceeds threshold!</div>;
+ * }
+ * ```
+ */
+export declare function useFormula(options: UseFormulaOptions): UseFormulaReturn;
+
+/**
+ * Options for useFormula hook
+ */
+export declare interface UseFormulaOptions {
+    /** Formula string (e.g., "=count>5", "=AND(a>1, b<10)") */
+    formula: string;
+    /** Input values for formula variables */
+    inputs: Map<string, unknown>;
+}
+
+/**
+ * Return value of useFormula hook
+ */
+export declare interface UseFormulaReturn {
+    /** Boolean result of formula evaluation */
+    result: boolean;
+    /** Error if evaluation failed */
+    error: Error | null;
+}
+
+/**
+ * Hook for managing post-execution actions extracted from rendered prompts.
+ *
+ * Tracks pending, executed, and dismissed actions. Supports custom handlers
+ * per action type and bulk operations.
+ *
+ * @param options - Configuration including actions and optional handlers
+ * @returns Object containing action lists and control functions
+ *
+ * @example
+ * ```tsx
+ * function PostActions({ actions }) {
+ *   const { pendingActions, execute, dismiss, allDone } = usePostActions({
+ *     actions,
+ *     handlers: {
+ *       openUrl: (action) => window.open(action.url),
+ *     },
+ *   });
+ *
+ *   if (allDone) return <div>All actions handled!</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {pendingActions.map((action, i) => (
+ *         <li key={i}>
+ *           {action.type}
+ *           <button onClick={() => execute(action)}>Execute</button>
+ *           <button onClick={() => dismiss(action)}>Dismiss</button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePostActions(options: UsePostActionsOptions): UsePostActionsReturn;
+
+/**
+ * Options for usePostActions hook
+ */
+export declare interface UsePostActionsOptions {
+    /** Post-execution actions to manage */
+    actions: PostExecutionAction[];
+    /** Custom handlers by action type */
+    handlers?: Partial<Record<PostExecutionAction["type"], PostActionHandler>>;
+}
+
+/**
+ * Return value of usePostActions hook
+ */
+export declare interface UsePostActionsReturn {
+    /** Actions that have not yet been executed or dismissed */
+    pendingActions: PostExecutionAction[];
+    /** Actions that have been executed */
+    executedActions: PostExecutionAction[];
+    /** Actions that have been dismissed */
+    dismissedActions: PostExecutionAction[];
+    /** Whether all actions have been handled (executed or dismissed) */
+    allDone: boolean;
+    /** Execute a specific action */
+    execute: (action: PostExecutionAction) => Promise<void>;
+    /** Dismiss a specific action without executing */
+    dismiss: (action: PostExecutionAction) => void;
+    /** Execute all remaining pending actions */
+    executeAll: () => Promise<void>;
+    /** Dismiss all remaining pending actions */
+    dismissAll: () => void;
+    /** Reset all actions back to pending */
+    reset: () => void;
+}
+
+/**
+ * Hook for transforming JSX/prompt source into rendered text output.
+ *
+ * Provides functionality to:
+ * - Transform source code strings into PuptElement trees
+ * - Render elements to text output
+ * - Extract input requirements from Ask components
+ * - Track loading and error states
+ *
+ * @param options - Configuration options for the hook
+ * @returns Object containing element, output, loading states, and control functions
+ *
+ * @example
+ * ```tsx
+ * function PromptDemo() {
+ *   const { output, error, isLoading } = usePromptRender({
+ *     source: { type: 'source', value: '<Prompt><Task>Hello</Task></Prompt>' },
+ *     autoRender: true,
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <pre>{output}</pre>;
+ * }
+ * ```
+ */
+export declare function usePromptRender(options?: UsePromptRenderOptions): UsePromptRenderReturn;
+
+/**
+ * Options for usePromptRender hook
+ */
+export declare interface UsePromptRenderOptions {
+    /** Initial source to transform/render */
+    source?: PromptSource;
+    /** Input values to pass to the prompt during rendering */
+    inputs?: Map<string, unknown>;
+    /** Environment context for rendering */
+    environment?: Partial<EnvironmentContext>;
+    /** Render options to pass to pupt-lib */
+    renderOptions?: Partial<RenderOptions>;
+    /** Whether to automatically render after transformation (default: false) */
+    autoRender?: boolean;
+    /** Filename hint for source transformation (e.g. "prompt.prompt" or "prompt.tsx").
+     *  Controls whether pupt-lib auto-injects imports for built-in components.
+     *  Defaults to "prompt.tsx". Use "prompt.prompt" for raw JSX without imports. */
+    filename?: string;
+}
+
+/**
+ * Return value of usePromptRender hook
+ */
+export declare interface UsePromptRenderReturn {
+    /** Current source being rendered */
+    source: PromptSource | null;
+    /** Set a new source to transform */
+    setSource: (source: PromptSource) => void;
+    /** The transformed PuptElement */
+    element: PuptElement | null;
+    /** The rendered text output */
+    output: string | null;
+    /** Error that occurred during transformation or rendering */
+    error: Error | null;
+    /** Detailed render errors from component validation/runtime failures */
+    renderErrors: RenderError[];
+    /** Whether transformation is in progress */
+    isTransforming: boolean;
+    /** Whether rendering is in progress */
+    isRendering: boolean;
+    /** Combined loading state (transforming or rendering) */
+    isLoading: boolean;
+    /** Input requirements extracted from Ask components */
+    inputRequirements: InputRequirement[];
+    /** Post-execution actions extracted from the prompt */
+    postActions: PostExecutionAction[];
+    /** Manually trigger rendering with current element and inputs */
+    render: () => Promise<void>;
+    /** Manually trigger transformation of source code */
+    transform: (sourceCode?: string) => Promise<PuptElement | null>;
+}
+
+/**
+ * Hook for searching through prompts indexed in the PuptProvider.
+ *
+ * Uses the search engine from PuptContext and provides debounced searching
+ * with query state management.
+ *
+ * @param options - Configuration including debounce delay and result limit
+ * @returns Object containing query state, results, and search controls
+ *
+ * @example
+ * ```tsx
+ * function SearchBar() {
+ *   const { query, setQuery, results, isSearching } = usePromptSearch();
+ *
+ *   return (
+ *     <div>
+ *       <input value={query} onChange={e => setQuery(e.target.value)} />
+ *       {isSearching && <span>Searching...</span>}
+ *       <ul>{results.map(r => <li key={r.prompt.name}>{r.prompt.name}</li>)}</ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePromptSearch(options?: UsePromptSearchOptions): UsePromptSearchReturn;
+
+/**
+ * Options for usePromptSearch hook
+ */
+export declare interface UsePromptSearchOptions {
+    /** Debounce delay in milliseconds (default: 200) */
+    debounce?: number;
+    /** Maximum number of results to return */
+    limit?: number;
+}
+
+/**
+ * Return value of usePromptSearch hook
+ */
+export declare interface UsePromptSearchReturn {
+    /** Current search query */
+    query: string;
+    /** Set the search query */
+    setQuery: (query: string) => void;
+    /** Search results */
+    results: SearchResult[];
+    /** Whether a search is in progress */
+    isSearching: boolean;
+    /** All available tags from indexed prompts */
+    allTags: string[];
+    /** Clear the search query and results */
+    clear: () => void;
+}
+
+/**
+ * Hook to access the pupt-lib context
+ *
+ * Must be used within a PuptProvider component.
+ * Throws an error if used outside of provider.
+ *
+ * @returns The pupt context value containing searchEngine, renderOptions, etc.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { searchEngine, isLoading, error } = usePupt();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   // Use searchEngine for finding prompts...
+ * }
+ * ```
+ *
+ * @throws {Error} When used outside of PuptProvider
+ */
+export declare function usePupt(): PuptContextValue;
+
+/**
+ * Hook that wraps the Pupt class with React state management.
+ *
+ * Creates a Pupt instance, loads modules, and exposes discovered prompts.
+ * Re-initializes when the modules list changes.
+ *
+ * @example
+ * ```tsx
+ * const { prompts, isLoading, addModule } = usePuptLibrary({
+ *   modules: ["@my-org/prompts"],
+ * });
+ * ```
+ */
+export declare function usePuptLibrary(options?: UsePuptLibraryOptions): UsePuptLibraryReturn;
+
+/**
+ * Hook to access the PuptLibraryProvider context.
+ *
+ * Must be used within a PuptLibraryProvider.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { prompts, addModule, isLoading } = usePuptLibraryContext();
+ *   // ...
+ * }
+ * ```
+ */
+export declare function usePuptLibraryContext(): UsePuptLibraryReturn;
+
+/**
+ * Options for usePuptLibrary hook
+ */
+export declare interface UsePuptLibraryOptions {
+    /** Module entries to load prompts from */
+    modules?: ModuleEntry[];
+    /** Configuration for the search engine */
+    searchConfig?: SearchEngineConfig;
+}
+
+/**
+ * Return value of usePuptLibrary hook
+ */
+export declare interface UsePuptLibraryReturn {
+    /** Whether the library is loading/initializing */
+    isLoading: boolean;
+    /** Error that occurred during initialization */
+    error: Error | null;
+    /** All discovered prompts from loaded modules */
+    prompts: DiscoveredPromptWithMethods[];
+    /** All unique tags from discovered prompts */
+    tags: string[];
+    /** Get a specific prompt by name */
+    getPrompt: (name: string) => DiscoveredPromptWithMethods | undefined;
+    /** Get all prompts with a specific tag */
+    getPromptsByTag: (tag: string) => DiscoveredPromptWithMethods[];
+    /** Add a module entry */
+    addModule: (source: ModuleEntry) => void;
+    /** Remove a module entry */
+    removeModule: (source: ModuleEntry) => void;
+    /** Currently loaded module entries */
+    modules: ModuleEntry[];
+}
+
+/**
+ * Validate a value against an InputRequirement's constraints.
+ *
+ * @param requirement - The input requirement to validate against
+ * @param value - The value to validate
+ * @returns A ValidationResult indicating success or failure
+ */
+export declare function validateInput(requirement: InputRequirement, value: unknown): ValidationResult;
+
+export { ValidationResult }
+
+export declare const VERSION = "1.0.0";
+
+export { }