@onlook/capsule 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/** A react-router parent route that wraps child routes via <Outlet /> */
+type LayoutRoute = {
+    /** Route path segment, e.g. "/sign-in" */
+    path: string;
+    /** Relative path to the layout component */
+    component: string;
+    /** Named export (if omitted, assumes default export) */
+    exportName?: string;
+};
+/** A component that wraps <Routes> in the router (e.g. LocationManager, AuthGuard) */
+type AppWrapper = {
+    /** Component name, e.g. "LocationManager" */
+    componentName: string;
+    /** Relative path to component file */
+    component: string;
+    /** Named export (if omitted, assumes default export) */
+    exportName?: string;
+};
+type RouteEntry = {
+    /** URL path, e.g. "/dashboard/settings" */
+    path: string;
+    /** Relative path to the page component, e.g. "app/dashboard/settings/page.tsx" */
+    pageComponent: string;
+    /** Layout files from outermost to innermost (Next.js) */
+    layouts: string[];
+    /** Parent route components that wrap this route via Outlet (react-router) */
+    layoutRoutes?: LayoutRoute[];
+    /** Mock values for dynamic segments, e.g. { id: "mock-123" } */
+    params?: Record<string, string>;
+    /** Named export to use (if omitted, assumes default export) */
+    exportName?: string;
+};
+type RouteManifest = {
+    framework: 'nextjs-app' | 'vite-react-router';
+    routes: RouteEntry[];
+    /** Components that wrap <Routes> in the router file (react-router only) */
+    appWrappers?: AppWrapper[];
+};
+type ComponentBoundary = {
+    /** Import source strings, e.g. ["@/contexts/AuthContext", "@tanstack/react-query"] */
+    imports: string[];
+    /** Hook call names, e.g. ["useAuth", "useQuery", "useFeatureFlags"] */
+    hooks: string[];
+    /** Context names from useContext calls, e.g. ["AuthContext", "ThemeContext"] */
+    contexts: string[];
+};
+type PropInfo = {
+    /** Property name */
+    name: string;
+    /** TypeScript type text, e.g. "string", "User | null" */
+    type: string;
+    /** Whether the prop is optional (question token or `| undefined`) */
+    optional: boolean;
+};
+type StateInfo = {
+    /** Variable name, e.g. "count" */
+    name: string;
+    /** Inferred type from generic or initial value */
+    type: string;
+    /** Setter name, e.g. "setCount" */
+    setter: string;
+};
+type HookCallInfo = {
+    /** Hook name, e.g. "useAuth" */
+    name: string;
+    /** Import source module, e.g. "@/hooks/useAuth"; empty string if locally defined */
+    module: string;
+};
+type ComponentProfile = {
+    props: PropInfo[];
+    state: StateInfo[];
+    hookCalls: HookCallInfo[];
+};
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type ProviderSpec = {
+    /** Identifier for this provider, e.g. "auth" */
+    id: string;
+    /** Import path, e.g. "@/contexts/AuthContext" */
+    import: string;
+    /** Context variable name, e.g. "AuthContext" */
+    contextName: string;
+    /** Mock value to provide via Context.Provider */
+    mockValue: Record<string, unknown>;
+};
+type HookStubSpec = {
+    /** Module path to intercept, e.g. "@/hooks/useFeatureFlags" */
+    module: string;
+    /** Named export to stub, e.g. "useFeatureFlags" */
+    export: string;
+    /** Value the stub returns */
+    returns: unknown;
+    /** If true, export as a value instead of a function */
+    isValue?: boolean;
+};
+type NetworkMockSpec = {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** URL path pattern, e.g. "/api/settings" */
+    path: string;
+    /** HTTP status code, defaults to 200 */
+    status?: number;
+    /** Response body */
+    response: unknown;
+};
+type CapsuleManifest = {
+    providers: ProviderSpec[];
+    hookStubs: HookStubSpec[];
+    networkMocks: NetworkMockSpec[];
+    /** Global assignments, e.g. { "window.ENV": { API_URL: "..." } } */
+    globals: Record<string, JsonValue>;
+};
+type CapsuleResult = {
+    status: 'sealed';
+    html: string;
+    manifest: CapsuleManifest;
+    attempts: number;
+} | {
+    status: 'breached';
+    error: string;
+    componentStack: string;
+    manifest: CapsuleManifest;
+};
+type CapsuleStatus = {
+    route: RouteEntry;
+    status: 'sealed' | 'breached' | 'pending';
+    attempts: number;
+    error?: string;
+};
+type CapsuleConfig = {
+    /** Absolute path to the project root */
+    projectRoot: string;
+    /** Override route discovery glob */
+    routes?: string;
+    /** Max seal loop retries per route (default: 3) */
+    maxRetries: number;
+    /** Parallel seal operations (default: 4) */
+    concurrency: number;
+    /** Start viewer after sealing */
+    serve: boolean;
+    /** Viewer port (default: 5123) */
+    port: number;
+    /** Cache directory (default: .capsules/cache) */
+    cacheDir: string;
+    /** Show seal loop details */
+    verbose: boolean;
+    /** Run LLM fixes immediately on failure instead of after all routes render (default: false) */
+    eager: boolean;
+    /** Max parallel LLM calls in lazy mode (default: 1) */
+    llmConcurrency: number;
+    /** Path to the router file for Vite projects (auto-detected if not set) */
+    routerFile?: string;
+    /** Additional esbuild externals beyond the defaults */
+    external?: string[];
+    /** Workspace modules to allow through (bypass auto-proxy). Matched as prefixes. */
+    allowedModules?: string[];
+};
+
+/**
+ * No-op — oxc-parser is stateless (no shared Project to reset).
+ * Kept for API compatibility with consumers that call resetProject().
+ */
+declare function resetProject(): void;
+/**
+ * Extract the external boundary of a component file:
+ * - All import source strings
+ * - All hook calls (functions starting with "use")
+ * - All context names from useContext() calls
+ */
+declare function extractBoundary(filePath: string): ComponentBoundary;
+/**
+ * Compute a deterministic hash of a component boundary.
+ * This is the cache key — component internals can change freely
+ * without invalidating the manifest. Only boundary changes
+ * (new imports, hooks, contexts) trigger re-sealing.
+ */
+declare function boundaryHash(boundary: ComponentBoundary): string;
+/**
+ * Extract a richer component profile for LLM context:
+ * - Props with types and optionality
+ * - State variables with inferred types
+ * - Hook calls with their import sources
+ *
+ * This does NOT affect the boundary hash / cache key.
+ */
+declare function extractProfile(filePath: string): ComponentProfile;
+
+/**
+ * Look up a cached manifest by boundary hash.
+ * Returns null if no cache entry exists or the entry is invalid.
+ */
+declare function getCachedManifest(hash: string, outputDir: string): CapsuleManifest | null;
+/**
+ * Store a manifest in the cache by boundary hash.
+ */
+declare function setCachedManifest(hash: string, manifest: CapsuleManifest, outputDir: string): void;
+/**
+ * Clear the entire manifest cache.
+ */
+declare function clearCache(outputDir: string): void;
+
+/**
+ * Detect the framework used in a project by checking for config files.
+ */
+declare function detectFramework(projectRoot: string): RouteManifest['framework'] | null;
+/**
+ * Discover all routes in a project.
+ * Supports Next.js App Router and Vite + react-router.
+ */
+declare function discoverRoutes(projectRoot: string, routeGlob?: string, routerFile?: string): RouteManifest;
+
+/**
+ * Generate a capsule shell file for a single route.
+ *
+ * The shell imports the page component and its layout chain,
+ * wraps them in CapsuleShell with the manifest, and exports
+ * a default component.
+ */
+declare function generateShell(route: RouteEntry, outputDir: string, projectRoot: string, framework?: RouteManifest['framework'], appWrappers?: AppWrapper[]): string;
+/**
+ * Write capsule shells and empty manifests for all routes.
+ * Returns the list of generated shell file paths.
+ */
+declare function generateAllShells(routes: RouteEntry[], outputDir: string, projectRoot: string, framework?: RouteManifest['framework'], appWrappers?: AppWrapper[]): Map<string, string>;
+
+type LLMProvider = {
+    generateManifestFix: (opts: {
+        error: string;
+        componentStack: string;
+        componentSource: string;
+        currentManifest: CapsuleManifest;
+        componentProfile?: ComponentProfile;
+        unstubbedHooks?: {
+            name: string;
+            module: string;
+        }[];
+        routeParams?: Record<string, string>;
+    }) => Promise<CapsuleManifest>;
+};
+type SealOptions = {
+    projectRoot: string;
+    outputDir: string;
+    maxRetries: number;
+    verbose: boolean;
+    llm?: LLMProvider;
+    /** Skip LLM calls — render once and return breached on failure */
+    skipLlm?: boolean;
+    /** Additional esbuild externals */
+    external?: string[];
+};
+/**
+ * Run the seal loop for a single route.
+ *
+ * 1. Bundle the shell with esbuild
+ * 2. Render in happy-dom with MSW network mocks
+ * 3. On failure, check cache or call LLM for a manifest fix
+ * 4. Retry up to maxRetries times
+ */
+declare function sealRoute(route: RouteEntry, shellPath: string, manifestPath: string, options: SealOptions): Promise<CapsuleResult>;
+/** Load the global manifest from the output directory */
+declare function loadGlobalManifest(outputDir: string): CapsuleManifest;
+/**
+ * Merge a global manifest with a per-route manifest.
+ * Per-route entries override global ones when keys match.
+ */
+declare function mergeManifests(global: CapsuleManifest, perRoute: CapsuleManifest): CapsuleManifest;
+/**
+ * Create an LLM provider using the Vercel AI SDK + OpenRouter.
+ */
+declare function createOpenRouterLLM(apiKey: string, model?: string): Promise<LLMProvider>;
+
+type SealResult = {
+    route: string;
+    result: CapsuleResult;
+};
+type SealFn = (route: RouteEntry, shellPath: string, manifestPath: string, options: SealOptions) => Promise<CapsuleResult>;
+declare function runSealPool(routes: RouteEntry[], shells: Map<string, string>, outputDir: string, sealOpts: SealOptions, concurrency: number, seal?: SealFn): Promise<SealResult[]>;
+
+/**
+ * Apply universal browser API stubs for happy-dom.
+ * Call once before importing any components.
+ */
+declare function applyBrowserStubs(): void;
+
+type CapsuleShellProps = {
+    route: string;
+    manifest: CapsuleManifest;
+    children: React.ReactNode;
+};
+/**
+ * Generic wrapper that reads a CapsuleManifest and builds the render environment.
+ *
+ * 1. Applies global assignments from manifest.globals
+ * 2. Builds a provider tree from manifest.providers
+ * 3. Wraps children in an error boundary
+ *
+ * Note: MSW network mocks are set up externally by the seal loop,
+ * not inside this component (they need to be active before render).
+ * Hook stubs are also applied externally via module mocking.
+ */
+declare function CapsuleShell({ manifest, children }: CapsuleShellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Run a callback with MSW network mocks active.
+ * Uses a shared server to avoid patching fetch multiple times.
+ */
+declare function withMockServer<T>(mocks: NetworkMockSpec[], fn: () => T | Promise<T>): Promise<T>;
+
+/**
+ * Start the capsule viewer dev server.
+ * Creates a Vite server that serves an iframe-based route browser.
+ * Each route shell renders in the browser via Vite's transform pipeline.
+ */
+declare function startViewer(outputDir: string, manifest: RouteManifest, port: number, projectRoot?: string, shells?: Map<string, string>): Promise<void>;
+
+export { type AppWrapper, type CapsuleConfig, type CapsuleManifest, type CapsuleResult, CapsuleShell, type CapsuleStatus, type ComponentBoundary, type ComponentProfile, type HookCallInfo, type HookStubSpec, type LLMProvider, type LayoutRoute, type NetworkMockSpec, type PropInfo, type ProviderSpec, type RouteEntry, type RouteManifest, type SealFn, type SealOptions, type SealResult, type StateInfo, applyBrowserStubs, boundaryHash, clearCache, createOpenRouterLLM, detectFramework, discoverRoutes, extractBoundary, extractProfile, generateAllShells, generateShell, getCachedManifest, loadGlobalManifest, mergeManifests, resetProject, runSealPool, sealRoute, setCachedManifest, startViewer, withMockServer };