@onlook/capsule 0.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@onlook/capsule",
+  "type": "module",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Automatic isolated route previews — no stories, no manual curation",
+  "license": "ISC",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./runtime": {
+      "types": "./src/runtime/CapsuleShell.tsx",
+      "default": "./src/runtime/CapsuleShell.tsx"
+    },
+    "./safe-proxy": {
+      "types": "./src/runtime/safe-proxy.ts",
+      "default": "./src/runtime/safe-proxy.ts"
+    }
+  },
+  "bin": {
+    "capsule": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/runtime",
+    "src/types.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "dev:capsule": "bun run src/cli.ts seal",
+    "pack:sandbox": "tsup && npm pack",
+    "clean": "git clean -xdf dist node_modules",
+    "dev:evergreen": "./test-e2b/run-test-dev.sh"
+  },
+  "dependencies": {
+    "@drizzle-team/brocli": "^0.11.0",
+    "@openrouter/ai-sdk-provider": "^1.5.0",
+    "ai": "^6.0.0",
+    "esbuild": "^0.25.0",
+    "glob": "^10.3.10",
+    "happy-dom": "^20.8.3",
+    "minimatch": "^9.0.3",
+    "msw": "^2.7.0",
+    "oxc-parser": "^0.123.0",
+    "oxc-resolver": "^11.19.1",
+    "ts-morph": "^21.0.1",
+    "unenv": "^1.10.0",
+    "unplugin": "^3.0.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@onbook/tsconfig": "workspace:*",
+    "@types/node": "^22.15.32",
+    "@types/react": "^19.0.12",
+    "@types/react-dom": "^19.0.4",
+    "tsup": "^8.5.1",
+    "typescript": "5.8.3",
+    "vite": "^6.3.5"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/runtime/CapsuleShell.test.tsx

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'bun:test';
+import { renderToString } from 'react-dom/server';
+import type { CapsuleManifest } from '../types.js';
+import { CapsuleShell } from './CapsuleShell.js';
+
+function makeManifest(overrides: Partial<CapsuleManifest> = {}): CapsuleManifest {
+  return {
+    providers: overrides.providers ?? [],
+    hookStubs: overrides.hookStubs ?? [],
+    networkMocks: overrides.networkMocks ?? [],
+    globals: overrides.globals ?? {},
+  };
+}
+
+describe('CapsuleShell', () => {
+  it('renders children when no errors', () => {
+    const html = renderToString(
+      <CapsuleShell route="/test" manifest={makeManifest()}>
+        <div data-capsule="ok">Hello</div>
+      </CapsuleShell>,
+    );
+    expect(html).toContain('Hello');
+    expect(html).not.toContain('data-capsule-error');
+  });
+
+  it('applies globals from manifest', () => {
+    const g = globalThis as Record<string, unknown>;
+    const manifest = makeManifest({
+      globals: { TEST_CAPSULE_GLOBAL: 'applied' },
+    });
+
+    renderToString(
+      <CapsuleShell route="/test" manifest={manifest}>
+        <div />
+      </CapsuleShell>,
+    );
+
+    expect(g.TEST_CAPSULE_GLOBAL).toBe('applied');
+    delete g.TEST_CAPSULE_GLOBAL;
+  });
+
+  it('applies nested globals from manifest', () => {
+    const g = globalThis as Record<string, unknown>;
+    const manifest = makeManifest({
+      globals: { 'CAPSULE_TEST.nested.key': 42 },
+    });
+
+    renderToString(
+      <CapsuleShell route="/test" manifest={manifest}>
+        <div />
+      </CapsuleShell>,
+    );
+
+    const obj = g.CAPSULE_TEST as Record<string, Record<string, unknown>>;
+    expect(obj.nested?.key).toBe(42);
+    delete g.CAPSULE_TEST;
+  });
+
+  it('passes children through MockProvider unchanged', () => {
+    const manifest = makeManifest({
+      providers: [
+        {
+          id: 'auth',
+          import: '@/contexts/auth',
+          contextName: 'AuthContext',
+          mockValue: { user: null },
+        },
+      ],
+    });
+
+    const html = renderToString(
+      <CapsuleShell route="/test" manifest={manifest}>
+        <div data-capsule="ok">With provider</div>
+      </CapsuleShell>,
+    );
+
+    expect(html).toContain('With provider');
+    expect(html).not.toContain('data-capsule-error');
+  });
+
+  it('handles multiple providers without crashing', () => {
+    const manifest = makeManifest({
+      providers: [
+        {
+          id: 'auth',
+          import: '@/contexts/auth',
+          contextName: 'AuthContext',
+          mockValue: { user: null },
+        },
+        {
+          id: 'theme',
+          import: '@/contexts/theme',
+          contextName: 'ThemeContext',
+          mockValue: { theme: 'dark' },
+        },
+      ],
+    });
+
+    const html = renderToString(
+      <CapsuleShell route="/test" manifest={manifest}>
+        <div>Content</div>
+      </CapsuleShell>,
+    );
+
+    expect(html).toContain('Content');
+    expect(html).not.toContain('data-capsule-error');
+  });
+
+  it('handles empty manifest gracefully', () => {
+    const html = renderToString(
+      <CapsuleShell route="/" manifest={makeManifest()}>
+        <span>Minimal</span>
+      </CapsuleShell>,
+    );
+    expect(html).toContain('Minimal');
+  });
+
+  it('applies multiple globals', () => {
+    const g = globalThis as Record<string, unknown>;
+    const manifest = makeManifest({
+      globals: {
+        CAPSULE_A: 'first',
+        CAPSULE_B: 'second',
+      },
+    });
+
+    renderToString(
+      <CapsuleShell route="/test" manifest={manifest}>
+        <div />
+      </CapsuleShell>,
+    );
+
+    expect(g.CAPSULE_A).toBe('first');
+    expect(g.CAPSULE_B).toBe('second');
+    delete g.CAPSULE_A;
+    delete g.CAPSULE_B;
+  });
+});
+
+// Note: Error boundary categorization is tested through the seal loop
+// integration tests (seal.test.ts) because React SSR's renderToString
+// re-throws errors instead of catching them in error boundaries.
+// The categorizeError function is exercised when components render
+// in happy-dom via the seal pipeline.

package/src/runtime/CapsuleShell.tsx

@@ -0,0 +1,189 @@
+import React from 'react';
+import type { CapsuleManifest } from '../types.js';
+
+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.
+ */
+export function CapsuleShell({ manifest, children }: CapsuleShellProps) {
+  // Apply globals
+  for (const [key, value] of Object.entries(manifest.globals)) {
+    setNestedValue(globalThis, key, value);
+  }
+
+  // Build provider tree (innermost last in the array = innermost in the tree)
+  let tree = <>{children}</>;
+
+  // Providers are applied outermost-first, so iterate in reverse
+  // so that providers[0] is the outermost wrapper
+  for (let i = manifest.providers.length - 1; i >= 0; i--) {
+    const provider = manifest.providers[i];
+    if (!provider) continue;
+
+    // At runtime, we can't dynamically resolve context imports.
+    // The CapsuleShell is used in two modes:
+    // 1. Static shell files (generated code does the actual imports)
+    // 2. Seal loop testing (contexts are stubbed via module mocking)
+    //
+    // For now, we wrap with a simple value-providing context stub.
+    // The seal loop's esbuild step handles actual context resolution.
+    tree = (
+      <MockProvider contextName={provider.contextName} value={provider.mockValue}>
+        {tree}
+      </MockProvider>
+    );
+  }
+
+  return <CapsuleErrorBoundary>{tree}</CapsuleErrorBoundary>;
+}
+
+/**
+ * Simple mock provider that creates a React context on the fly.
+ * Used when the actual context isn't importable at bundle time.
+ */
+function MockProvider({
+  children,
+}: {
+  contextName: string;
+  value: Record<string, unknown>;
+  children: React.ReactNode;
+}) {
+  // In the sealed environment, hook stubs handle context access.
+  // This component just passes children through — the real provider
+  // wrapping happens via hook stubs in the seal loop.
+  return <>{children}</>;
+}
+
+/**
+ * Error boundary that catches render errors, categorizes them,
+ * and shows diagnostic information for the seal loop and viewer.
+ */
+class CapsuleErrorBoundary extends React.Component<
+  { children: React.ReactNode },
+  { hasError: boolean; error: Error | null; componentStack: string }
+> {
+  constructor(props: { children: React.ReactNode }) {
+    super(props);
+    this.state = { hasError: false, error: null, componentStack: '' };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(_error: Error, errorInfo: React.ErrorInfo) {
+    this.setState({
+      componentStack: errorInfo.componentStack ?? '',
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      const msg = this.state.error?.message ?? 'Unknown error';
+      const category = categorizeError(msg);
+
+      return (
+        <div data-capsule-error="true">
+          {msg}
+          {/* Hidden diagnostic data for the seal loop to parse */}
+          <div
+            data-capsule-category={category.type}
+            data-capsule-hint={category.hint}
+            data-capsule-stack={this.state.componentStack}
+            style={{ display: 'none' }}
+          />
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/** Categorize a render error to help the seal loop and viewer diagnose issues. */
+function categorizeError(message: string): {
+  type: string;
+  hint: string;
+} {
+  if (
+    message.includes('Cannot read properties of undefined') ||
+    message.includes('Cannot read properties of null') ||
+    message.includes('undefined is not an object')
+  ) {
+    return {
+      type: 'missing-property',
+      hint: 'A variable is undefined — likely a missing context provider, config, or data dependency.',
+    };
+  }
+  if (message.includes('useContext') || message.includes('provider')) {
+    return {
+      type: 'missing-provider',
+      hint: 'A React context provider is missing from the component tree. Add it to manifest.providers.',
+    };
+  }
+  if (message.includes('is not a function') || message.includes('is not a constructor')) {
+    return {
+      type: 'stubbed-call',
+      hint: 'A stubbed dependency was called as a function. Add a hookStub with proper return value.',
+    };
+  }
+  if (
+    message.includes('GraphQL') ||
+    message.includes('client was not initialized') ||
+    message.includes('ApolloError') ||
+    message.includes('gql')
+  ) {
+    return {
+      type: 'network-error',
+      hint: 'A GraphQL client is not initialized. Ensure @apollo/client or similar is stubbed.',
+    };
+  }
+  if (
+    message.includes('fetch') ||
+    message.includes('NetworkError') ||
+    message.includes('Failed to fetch')
+  ) {
+    return {
+      type: 'network-error',
+      hint: 'A network request failed. Add networkMocks to the manifest.',
+    };
+  }
+  return {
+    type: 'unknown',
+    hint: 'Unrecognized error — may need manual manifest entries or globals.',
+  };
+}
+
+/** Set a nested value on an object using dot-notation path */
+export function setNestedValue(
+  obj: Record<string, unknown>,
+  keyPath: string,
+  value: unknown,
+): void {
+  const keys = keyPath.split('.');
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!key) continue;
+    if (typeof current[key] !== 'object' || current[key] === null) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  const lastKey = keys[keys.length - 1];
+  if (lastKey) {
+    current[lastKey] = value;
+  }
+}

package/src/runtime/browser-stubs.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { applyBrowserStubs } from './browser-stubs.js';
+
+describe('applyBrowserStubs', () => {
+  const originalKeys = new Set(Object.keys(globalThis));
+
+  afterEach(() => {
+    // Clean up stubs we added (best-effort — some may not be deletable)
+    const g = globalThis as Record<string, unknown>;
+    for (const key of Object.keys(g)) {
+      if (!originalKeys.has(key)) {
+        try {
+          delete g[key];
+        } catch {
+          // some properties aren't configurable
+        }
+      }
+    }
+  });
+
+  it('creates window if missing', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.window;
+    delete g.window;
+    applyBrowserStubs();
+    expect(g.window).toBeDefined();
+    g.window = original;
+  });
+
+  it('creates localStorage with full Storage API', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.localStorage;
+    delete g.localStorage;
+    applyBrowserStubs();
+
+    const storage = g.localStorage as Storage;
+    expect(storage.getItem('missing')).toBeNull();
+
+    storage.setItem('key', 'value');
+    expect(storage.getItem('key')).toBe('value');
+    expect(storage.length).toBe(1);
+
+    storage.removeItem('key');
+    expect(storage.getItem('key')).toBeNull();
+    expect(storage.length).toBe(0);
+
+    storage.setItem('a', '1');
+    storage.setItem('b', '2');
+    storage.clear();
+    expect(storage.length).toBe(0);
+
+    g.localStorage = original;
+  });
+
+  it('creates matchMedia returning false matches', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.matchMedia;
+    delete g.matchMedia;
+    applyBrowserStubs();
+
+    const mql = (g.matchMedia as (q: string) => MediaQueryList)(
+      '(prefers-color-scheme: dark)',
+    );
+    expect(mql.matches).toBe(false);
+    expect(mql.media).toBe('(prefers-color-scheme: dark)');
+    // Should not throw
+    mql.addEventListener('change', () => {});
+    mql.removeEventListener('change', () => {});
+
+    g.matchMedia = original;
+  });
+
+  it('creates IntersectionObserver that does not throw', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.IntersectionObserver;
+    delete g.IntersectionObserver;
+    applyBrowserStubs();
+
+    const IO = g.IntersectionObserver as new (cb: () => void) => IntersectionObserver;
+    const observer = new IO(() => {});
+
+    // All methods should be callable without errors
+    observer.observe(null as unknown as Element);
+    observer.unobserve(null as unknown as Element);
+    observer.disconnect();
+    expect(observer.takeRecords()).toEqual([]);
+
+    g.IntersectionObserver = original;
+  });
+
+  it('creates ResizeObserver that does not throw', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.ResizeObserver;
+    delete g.ResizeObserver;
+    applyBrowserStubs();
+
+    const RO = g.ResizeObserver as new (cb: () => void) => ResizeObserver;
+    const observer = new RO(() => {});
+
+    observer.observe(null as unknown as Element);
+    observer.unobserve(null as unknown as Element);
+    observer.disconnect();
+
+    g.ResizeObserver = original;
+  });
+
+  it('creates history with pushState/replaceState', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.history;
+    delete g.history;
+    applyBrowserStubs();
+
+    const h = g.history as History;
+    // Should not throw
+    h.pushState({}, '', '/test');
+    h.replaceState({}, '', '/test');
+    h.back();
+    h.forward();
+    expect(h.length).toBe(1);
+
+    g.history = original;
+  });
+
+  it('creates location with localhost defaults', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.location;
+    delete g.location;
+    applyBrowserStubs();
+
+    const loc = g.location as Location;
+    expect(loc.hostname).toBe('localhost');
+    expect(loc.pathname).toBe('/');
+    expect(loc.protocol).toBe('http:');
+
+    g.location = original;
+  });
+
+  it('creates requestAnimationFrame that calls back', async () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.requestAnimationFrame;
+    delete g.requestAnimationFrame;
+    applyBrowserStubs();
+
+    const raf = g.requestAnimationFrame as (cb: FrameRequestCallback) => number;
+    const called = await new Promise<boolean>((resolve) => {
+      raf(() => resolve(true));
+      setTimeout(() => resolve(false), 100);
+    });
+    expect(called).toBe(true);
+
+    g.requestAnimationFrame = original;
+  });
+
+  it('does not overwrite existing globals', () => {
+    const g = globalThis as Record<string, unknown>;
+    const sentinel = { custom: true };
+    g.scrollTo = sentinel as unknown as typeof scrollTo;
+
+    applyBrowserStubs();
+
+    // Should not have replaced our custom value
+    expect(g.scrollTo).toBe(sentinel);
+  });
+
+  it('document stub provides querySelector returning null', () => {
+    const g = globalThis as Record<string, unknown>;
+    const original = g.document;
+    delete g.document;
+    applyBrowserStubs();
+
+    const doc = g.document as Document;
+    expect(doc.querySelector('.anything')).toBeNull();
+    expect(doc.querySelectorAll('.anything')).toHaveLength(0);
+    expect(doc.getElementById('anything')).toBeNull();
+
+    g.document = original;
+  });
+});