@onlook/capsule 0.1.0

package/src/runtime/browser-stubs.ts

@@ -0,0 +1,201 @@
+/**
+ * Apply universal browser API stubs for happy-dom.
+ * Call once before importing any components.
+ */
+export function applyBrowserStubs(): void {
+  const g = globalThis as Record<string, unknown>;
+
+  // Ensure `window` exists (Node/happy-dom doesn't always set it)
+  if (!g.window) {
+    g.window = globalThis;
+  }
+
+  // Ensure `document` exists
+  if (!g.document) {
+    const stubElement = (): Record<string, unknown> => ({
+      style: {},
+      setAttribute: () => {},
+      getAttribute: () => null,
+      removeAttribute: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      appendChild: () => stubElement(),
+      removeChild: () => stubElement(),
+      insertBefore: () => stubElement(),
+      cloneNode: () => stubElement(),
+      contains: () => false,
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      children: [],
+      childNodes: [],
+      parentNode: null,
+      nextSibling: null,
+      previousSibling: null,
+      textContent: '',
+      innerHTML: '',
+      outerHTML: '',
+      tagName: 'DIV',
+      nodeName: 'DIV',
+      nodeType: 1,
+      classList: {
+        add: () => {},
+        remove: () => {},
+        toggle: () => false,
+        contains: () => false,
+      },
+      dataset: {},
+      getBoundingClientRect: () => ({
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+        width: 0,
+        height: 0,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      }),
+    });
+    g.document = {
+      createElement: () => stubElement(),
+      createElementNS: () => stubElement(),
+      createTextNode: () => ({ textContent: '', nodeType: 3 }),
+      createDocumentFragment: () => stubElement(),
+      getElementById: () => null,
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      head: stubElement(),
+      body: stubElement(),
+      documentElement: stubElement(),
+      cookie: '',
+      title: '',
+      referrer: '',
+    };
+  }
+
+  // Ensure `location` exists
+  if (!g.location) {
+    g.location = {
+      href: 'http://localhost/',
+      origin: 'http://localhost',
+      protocol: 'http:',
+      host: 'localhost',
+      hostname: 'localhost',
+      port: '',
+      pathname: '/',
+      search: '',
+      hash: '',
+      assign: () => {},
+      replace: () => {},
+      reload: () => {},
+    };
+  }
+
+  // Ensure `localStorage` and `sessionStorage` exist
+  const createStorage = () => {
+    const store = new Map<string, string>();
+    return {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => store.set(k, v),
+      removeItem: (k: string) => store.delete(k),
+      clear: () => store.clear(),
+      get length() {
+        return store.size;
+      },
+      key: (i: number) => [...store.keys()][i] ?? null,
+    };
+  };
+  if (!g.localStorage) g.localStorage = createStorage();
+  if (!g.sessionStorage) g.sessionStorage = createStorage();
+
+  // Ensure `history` exists
+  if (!g.history) {
+    g.history = {
+      pushState: () => {},
+      replaceState: () => {},
+      go: () => {},
+      back: () => {},
+      forward: () => {},
+      state: null,
+      length: 1,
+    };
+  }
+
+  // matchMedia
+  if (!g.matchMedia) {
+    g.matchMedia = (query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    });
+  }
+
+  // IntersectionObserver
+  if (!g.IntersectionObserver) {
+    g.IntersectionObserver = class IntersectionObserver {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+      get root() {
+        return null;
+      }
+      get rootMargin() {
+        return '0px';
+      }
+      get thresholds() {
+        return [0];
+      }
+    };
+  }
+
+  // ResizeObserver
+  if (!g.ResizeObserver) {
+    g.ResizeObserver = class ResizeObserver {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+
+  // scrollTo
+  if (!g.scrollTo) {
+    g.scrollTo = () => {};
+  }
+
+  // requestAnimationFrame
+  if (!g.requestAnimationFrame) {
+    g.requestAnimationFrame = (cb: FrameRequestCallback) => {
+      return setTimeout(() => cb(Date.now()), 0) as unknown as number;
+    };
+  }
+
+  // cancelAnimationFrame
+  if (!g.cancelAnimationFrame) {
+    g.cancelAnimationFrame = (id: number) => {
+      clearTimeout(id);
+    };
+  }
+
+  // Clipboard API
+  if (typeof navigator !== 'undefined' && !navigator.clipboard) {
+    Object.defineProperty(navigator, 'clipboard', {
+      value: {
+        writeText: async () => {},
+        readText: async () => '',
+        write: async () => {},
+        read: async () => [],
+      },
+      writable: true,
+    });
+  }
+}

package/src/runtime/msw-setup.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'bun:test';
+import { withMockServer } from './msw-setup.js';
+
+describe('withMockServer', () => {
+  it('returns the callback result', async () => {
+    const result = await withMockServer([], () => 'hello');
+    expect(result).toBe('hello');
+  });
+
+  it('returns async callback result', async () => {
+    const result = await withMockServer([], async () => {
+      await new Promise((r) => setTimeout(r, 5));
+      return 42;
+    });
+    expect(result).toBe(42);
+  });
+
+  it('cleans up server even when callback throws', async () => {
+    const error = new Error('intentional');
+    let caught: Error | undefined;
+
+    try {
+      await withMockServer([], () => {
+        throw error;
+      });
+    } catch (e) {
+      caught = e as Error;
+    }
+
+    expect(caught).toBe(error);
+
+    // If server wasn't cleaned up, a second call would fail or hang.
+    // This call succeeding proves cleanup worked.
+    const result = await withMockServer([], () => 'ok');
+    expect(result).toBe('ok');
+  });
+
+  it('works with empty mock list', async () => {
+    const result = await withMockServer([], () => 'no mocks');
+    expect(result).toBe('no mocks');
+  });
+});

package/src/runtime/msw-setup.ts

@@ -0,0 +1,63 @@
+import { HttpResponse, http } from 'msw';
+import { type SetupServerApi, setupServer } from 'msw/node';
+import type { NetworkMockSpec } from '../types.js';
+
+/** Shared singleton MSW server — avoids "fetch already patched" errors */
+let sharedServer: SetupServerApi | null = null;
+let refCount = 0;
+
+function getServer(): SetupServerApi {
+  if (!sharedServer) {
+    // Start with a catch-all handler; routes override via resetHandlers
+    sharedServer = setupServer(http.all('*', () => HttpResponse.json({})));
+    sharedServer.listen({ onUnhandledRequest: 'bypass' });
+  }
+  refCount++;
+  return sharedServer;
+}
+
+function releaseServer(): void {
+  refCount--;
+  if (refCount <= 0 && sharedServer) {
+    sharedServer.close();
+    sharedServer = null;
+    refCount = 0;
+  }
+}
+
+/**
+ * Create MSW handlers from a list of network mock specs.
+ */
+function buildHandlers(mocks: NetworkMockSpec[]) {
+  const handlers = mocks.map((mock) => {
+    const method = mock.method.toLowerCase() as keyof typeof http;
+    const pattern = `*${mock.path}`;
+    return http[method](pattern, () => {
+      return HttpResponse.json(mock.response as Record<string, unknown>, {
+        status: mock.status ?? 200,
+      });
+    });
+  });
+
+  // Catch-all: return empty JSON for any unmatched request
+  handlers.push(http.all('*', () => HttpResponse.json({})));
+
+  return handlers;
+}
+
+/**
+ * Run a callback with MSW network mocks active.
+ * Uses a shared server to avoid patching fetch multiple times.
+ */
+export async function withMockServer<T>(
+  mocks: NetworkMockSpec[],
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  const server = getServer();
+  server.resetHandlers(...buildHandlers(mocks));
+  try {
+    return await fn();
+  } finally {
+    releaseServer();
+  }
+}

package/src/runtime/safe-proxy.ts

@@ -0,0 +1,143 @@
+/**
+ * Safe proxy utilities for capsule hookStub virtual modules.
+ *
+ * These provide React-safe deep proxies and value resolution for
+ * hook stubs rendered in the capsule viewer. Imported at runtime
+ * by the virtual modules that stub-generators.ts emits.
+ */
+
+/** No-op function — default for function-typed stub values. */
+export function noop() {}
+
+/** Identity function — passthrough stub values. */
+export function identity<T>(x: T): T {
+  return x;
+}
+
+// React properties that must return undefined to prevent React from
+// treating the proxy as a React element or component.
+const REACT_UNDEFINED_PROPS = new Set([
+  '$$typeof',
+  '_owner',
+  '_store',
+  'ref',
+  'key',
+  'type',
+  'props',
+  '_self',
+  '_source',
+  'getDefaultProps',
+  'childContextTypes',
+  'defaultProps',
+  'getDerivedStateFromProps',
+  'contextType',
+  'contextTypes',
+  'propTypes',
+  'PropTypes',
+  'displayName',
+]);
+
+const dpHandler: ProxyHandler<(...args: unknown[]) => unknown> = {
+  get(_t, prop) {
+    if (typeof prop === 'string' && REACT_UNDEFINED_PROPS.has(prop)) {
+      return undefined;
+    }
+    if (
+      prop === Symbol.toPrimitive ||
+      prop === 'toString' ||
+      prop === 'valueOf' ||
+      prop === 'toJSON'
+    ) {
+      return () => '';
+    }
+    // Empty iterator for [...proxy], for...of, and destructuring
+    if (prop === Symbol.iterator) {
+      return () => ({ next: () => ({ done: true }) });
+    }
+    if (prop === Symbol.asyncIterator || typeof prop === 'symbol') {
+      return undefined;
+    }
+    // Prevent Promise auto-unwrapping
+    if (prop === 'then') return undefined;
+    if (prop === 'length') return 0;
+    if (prop === 'constructor') return Object;
+    // Any other property → recurse
+    return dp();
+  },
+  apply() {
+    return dp();
+  },
+  construct() {
+    return dp() as object;
+  },
+};
+
+/**
+ * Create a deep proxy safe for any property chain, function call,
+ * iteration, and string coercion. Returned for missing properties
+ * on hookStub objects so components never crash on access chains.
+ */
+export function dp(): unknown {
+  const target = () => {};
+  target.toString = () => '';
+  target.valueOf = () => '';
+  // biome-ignore lint/suspicious/noExplicitAny: Symbol index
+  (target as any)[Symbol.toPrimitive] = () => '';
+  return new Proxy(target, dpHandler);
+}
+
+/**
+ * Proxy handler for hookStub return-value objects. Known properties
+ * return their real value; unknown properties return a deep proxy.
+ */
+const safeHandler: ProxyHandler<Record<string, unknown>> = {
+  get(target, prop) {
+    if (typeof prop === 'symbol') return undefined;
+    if (prop in target) return target[prop];
+    return dp();
+  },
+};
+
+/**
+ * Resolve a JSON-serializable stub value into a runtime value.
+ *
+ * Sentinels:
+ *  - `"__NOOP_FN__"` → noop function
+ *  - `"__IDENTITY_FN__"` → identity function
+ *  - `"__DEEP_PROXY__"` → deep proxy
+ *
+ * Arrays are resolved recursively. Plain objects are wrapped in
+ * the safe proxy so missing properties return a deep proxy.
+ */
+export function rv(v: unknown): unknown {
+  if (v === '__NOOP_FN__') return noop;
+  if (v === '__IDENTITY_FN__') return identity;
+  if (v === '__DEEP_PROXY__') return dp();
+  if (Array.isArray(v)) return v.map(rv);
+  if (v && typeof v === 'object' && v.constructor === Object) {
+    const r: Record<string, unknown> = {};
+    for (const k in v) {
+      r[k] = rv((v as Record<string, unknown>)[k]);
+    }
+    return new Proxy(r, safeHandler);
+  }
+  return v;
+}
+
+/** Shallow merge of base and override objects. */
+export function merge(base: unknown, over: unknown): Record<string, unknown> {
+  if (!over || typeof over !== 'object') {
+    return base as Record<string, unknown>;
+  }
+  const r = typeof base === 'object' && base ? { ...base } : {};
+  Object.assign(r, over);
+  return r as Record<string, unknown>;
+}
+
+/** Read a per-hook override from window.__CAPSULE_OVERRIDES__. */
+export function getOverride(key: string): unknown {
+  const w =
+    typeof window !== 'undefined' &&
+    (window as unknown as Record<string, unknown>).__CAPSULE_OVERRIDES__;
+  return w ? (w as Record<string, unknown>)[key] : undefined;
+}

package/src/runtime/setNestedValue.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'bun:test';
+import { setNestedValue } from './CapsuleShell.js';
+
+describe('setNestedValue', () => {
+  it('sets a single key', () => {
+    const obj: Record<string, unknown> = {};
+    setNestedValue(obj, 'foo', 42);
+    expect(obj.foo).toBe(42);
+  });
+
+  it('sets a deep path, creating intermediates', () => {
+    const obj: Record<string, unknown> = {};
+    setNestedValue(obj, 'window.ENV.API_URL', 'http://test');
+    const win = obj.window as Record<string, Record<string, unknown>>;
+    expect(win.ENV?.API_URL).toBe('http://test');
+  });
+
+  it('overwrites existing values', () => {
+    const obj: Record<string, unknown> = { foo: 'old' };
+    setNestedValue(obj, 'foo', 'new');
+    expect(obj.foo).toBe('new');
+  });
+
+  it('overwrites non-object intermediate with object', () => {
+    const obj: Record<string, unknown> = { a: 'string' };
+    setNestedValue(obj, 'a.b', 'deep');
+    expect((obj.a as Record<string, unknown>).b).toBe('deep');
+  });
+
+  it('preserves sibling keys at intermediate levels', () => {
+    const obj: Record<string, unknown> = {
+      env: { EXISTING: true },
+    };
+    setNestedValue(obj, 'env.NEW', 'added');
+    const env = obj.env as Record<string, unknown>;
+    expect(env.EXISTING).toBe(true);
+    expect(env.NEW).toBe('added');
+  });
+
+  it('handles null intermediate by replacing with object', () => {
+    const obj: Record<string, unknown> = { a: null };
+    setNestedValue(obj, 'a.b', 'val');
+    expect((obj.a as Record<string, unknown>).b).toBe('val');
+  });
+});