@nominalso/vibe-bridge 0.2.0 → 0.3.0

package/AGENTS.md

@@ -15,9 +15,7 @@ The host counterpart is `@nominalso/vibe-host` (used by Nominal's own app — yo
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN, // exact origin of the embedding Nominal app
-})
+const bridge = new VibeAppBridge() // no config — auto-detects the embedding Nominal app
 
 const ctx: ContextPayload = await bridge.connect() // call ONCE, await before anything else
 
@@ -32,8 +30,8 @@ bridge.destroy() // on unmount
 
 ## Core surface
 
-- `new VibeAppBridge({ parentOrigin, requestTimeout? })` — `requestTimeout` is optional; omit it and each op uses a tuned default (API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000` ms).
-- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on `parentOrigin` mismatch / host not mounted.
+- `new VibeAppBridge({ parentOrigin?, requestTimeout? })` — both optional; `new VibeAppBridge()` auto-detects the host. `requestTimeout` omitted → tuned per-op defaults (API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000` ms).
+- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on a host that never mounts, or immediately with code `PARENT_ORIGIN_UNRESOLVED` if no host could be detected/pinned.
 - ~46 typed data methods, e.g. `getChartOfAccounts`, `getSubsidiaries`, `getPeriods`, `getJournalEntries`, `getAccounts`, `postTaskOutput`. Each takes the operation's `payload` and returns its `data`.
 - `request('<OPERATION>', payload, onProgress?)` — typed escape hatch for any operation; `'<OPERATION>'` autocompletes and narrows the payload/return types.
 - `upload(file: File, { entityType, entityId?, onProgress? }): Promise<{ attachmentId, name }>`.
@@ -52,7 +50,7 @@ The full method/operation list is in `README.md` ("Operation catalog") and in `d
 ## Gotchas (wrong → right)
 
 - **Don't call data methods before `connect()` resolves.** Always `await bridge.connect()` first.
-- **`parentOrigin` is an origin, not a URL.** `https://app.nominal.so` ✅ — not `https://app.nominal.so/app` and not a trailing slash. A mismatch makes `connect()` time out after 10 s.
+- **`parentOrigin` is optional** — omit it and the bridge auto-detects the embedding host. If you do pass it, it's an origin or list of origins (not a URL): `https://app.nominal.so` ✅ — not `https://app.nominal.so/app`, no trailing slash. For preview testing pass a list with a glob: `['https://app.nominal.so', 'https://*.vercel.app']` — patterns match only when the app itself runs on a preview host.
 - **`upload()` takes a `File`**, not a path or `FormData`.
 - **Writes go through `postTaskOutput` only.** Vibe Apps never write Nominal data directly.
 - **Call `bridge.destroy()` on unmount** to remove listeners and reject pending requests.
@@ -60,5 +58,5 @@ The full method/operation list is in `README.md` ("Operation catalog") and in `d
 ## Don't
 
 - Don't poll or busy-wait for context — `await connect()` resolves when it's ready.
-- Don't hardcode `parentOrigin`; read it from an env var so dev and prod differ.
+- Don't pass `parentOrigin` unless you mean to pin the host; the default auto-detects it. If you pin, read it from an env var (and add a preview pattern to the list when testing deploy previews).
 - Don't import from `@nominalso/vibe-protocol-types` / `vibe-api-types` — they are not published; all public types are re-exported from `@nominalso/vibe-bridge`.

package/README.md

@@ -2,7 +2,7 @@
 
 Iframe-side SDK for building **Nominal Vibe Apps** — standalone web apps (typically built with [Lovable](https://lovable.dev)) embedded in the Nominal platform via a cross-origin `<iframe>`. The bridge connects your app to its Nominal host over a typed `postMessage` protocol: read Nominal data, submit Close-Management task outputs, upload files, and keep deep-link routing in sync.
 
-> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — construct `VibeAppBridge` with the host `parentOrigin`, `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
+> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — `new VibeAppBridge()` (no config — it auto-detects the Nominal host), `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
 
 ## Install
 
@@ -17,11 +17,10 @@ Zero runtime dependencies. Ships ESM + CJS and self-contained TypeScript types.
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-// 1. Construct with the origin of the Nominal app embedding this iframe.
-//    Must match exactly — drive it from an env var.
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
-})
+// 1. Construct. No config needed — the bridge auto-detects the Nominal app
+//    that embeds it. (Pin the host origin explicitly only if you want to;
+//    see "Pinning the host origin" below.)
+const bridge = new VibeAppBridge()
 
 // 2. Connect ONCE on init and await it before any other call.
 //    Resolves with the tenant/user context (or rejects after 10s).
@@ -47,28 +46,47 @@ await bridge.postTaskOutput({ path: { task_instance_id: 'task-1' }, body: {} })
 bridge.destroy()
 ```
 
-`parentOrigin` via environment variable:
+### Pinning the host origin (optional)
 
-```sh
-# .env (committed — standalone/dev default)
-VITE_PARENT_ORIGIN=http://localhost:5173
+By default you pass **nothing** — the bridge talks only to the Nominal page that
+actually embeds it. That's safe because Nominal serves Vibe Apps behind a
+`frame-ancestors` CSP, so only nom-ui can frame your app. Most apps need nothing
+more.
+
+Pass `parentOrigin` to pin explicitly — defense in depth, or when running
+outside Nominal's edge. Drive it from an env var, or use a list / **glob
+patterns** to accept dynamic preview deployments:
+
+```ts
+new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
+```
 
-# .env.local (git-ignored — override when testing inside nom-ui)
+```sh
+# .env.local
 VITE_PARENT_ORIGIN=http://localhost:3000
 ```
 
+A pattern's `*` matches exactly one DNS label or port (anchored, scheme
+literal): `https://*.vercel.app` matches `https://pr-7.vercel.app` but not
+`https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. **Patterns are
+honoured only when this app's own page is served from a recognised preview host**
+(`*.vercel.app`, `*.lovable.app`, `localhost`, …) — on a production custom
+domain pattern entries are ignored and only exact origins match. Always include
+at least one exact origin alongside any patterns.
+
 ## API
 
 ### `new VibeAppBridge(options)`
 
-| Option           | Type     | Default  | Description                                                                                                                                                                                               |
-| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parentOrigin`   | `string` | —        | Origin of the Nominal app embedding this iframe. **Must match the host origin exactly.**                                                                                                                  |
-| `requestTimeout` | `number` | _per-op_ | Global timeout (ms) before a call rejects with `BridgeError` code `'TIMEOUT'`. Omit to use per-operation defaults: API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`. |
+| Option           | Type                 | Default  | Description                                                                                                                                                                                               |
+| ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parentOrigin`   | `string \| string[]` | _auto_   | **Optional.** Omit to auto-detect the embedding Nominal host. Pass to pin: exact origins always match; glob patterns (`https://*.vercel.app`) match only when this app runs on a preview host. See above. |
+| `requestTimeout` | `number`             | _per-op_ | Global timeout (ms) before a call rejects with `BridgeError` code `'TIMEOUT'`. Omit to use per-operation defaults: API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`. |
 
 ### `connect(): Promise<ContextPayload>`
 
-Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). Concurrent calls return the same promise.
+Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). If no concrete parent origin can be resolved (e.g. a pattern-only `parentOrigin` on a non-preview host), it rejects immediately with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`. Concurrent calls return the same promise.
 
 ### Data operations
 
@@ -115,7 +133,7 @@ import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 function useVibeBridge() {
   const [ctx, setCtx] = useState<ContextPayload | null>(null)
   useEffect(() => {
-    const bridge = new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+    const bridge = new VibeAppBridge()
     bridge.connect().then(setCtx).catch(console.error)
     return () => bridge.destroy()
   }, [])
@@ -172,13 +190,15 @@ const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.su
 ```
 
 ```ts
-// ❌ WRONG — parentOrigin must be an ORIGIN, not a URL with a path, and must match exactly.
+// ❌ WRONG — each entry must be an ORIGIN (scheme + host + port), not a URL with a path.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so/some/path' })
 // ❌ a trailing slash or wrong port also fails → connect() times out after 10s.
 new VibeAppBridge({ parentOrigin: 'http://localhost:3000/' })
 
-// ✅ CORRECT — scheme + host + port only, exact match to the embedding app.
+// ✅ CORRECT — scheme + host + port only, matching the embedding app.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so' })
+// ✅ CORRECT — a list with a preview pattern (honoured only on a preview host).
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
 ```
 
 ```ts

package/dist/index.cjs

@@ -28,7 +28,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.2.0";
+var version = "0.3.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -73,6 +73,33 @@ var HttpBridgeError = class extends BridgeError {
     this.name = "HttpBridgeError";
   }
 };
+function isOriginPattern(entry) {
+  return entry.includes("*");
+}
+var patternCache = /* @__PURE__ */ new Map();
+function patternToRegExp(pattern) {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = escaped.replace(/\\\*/g, "[^./:@?#\\s]+");
+  const compiled = new RegExp(`^${body}$`);
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+function matchesOrigin(origin, entry) {
+  if (!isOriginPattern(entry)) return origin === entry;
+  return patternToRegExp(entry).test(origin);
+}
+function isOriginAllowed(origin, allowlist, { allowPatterns }) {
+  for (const entry of allowlist) {
+    if (isOriginPattern(entry)) {
+      if (allowPatterns && matchesOrigin(origin, entry)) return true;
+    } else if (origin === entry) {
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/data-methods.ts
 var BridgeDataMethods = class {
@@ -391,13 +418,72 @@ function resolveRequestTimeout(type, requestTimeout) {
 }
 
 // src/VibeAppBridge.ts
+var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
+var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
+function isPreviewSelfHost(hostname) {
+  return PREVIEW_HOST_RE.test(hostname);
+}
+function resolveActualParentOrigin() {
+  if (typeof window === "undefined") return null;
+  try {
+    const ancestors = window.location.ancestorOrigins;
+    if (ancestors && ancestors.length > 0 && ancestors[0]) return ancestors[0];
+  } catch {
+  }
+  try {
+    if (document.referrer) return new URL(document.referrer).origin;
+  } catch {
+  }
+  return null;
+}
+function resolveOriginPolicy(configured) {
+  if (typeof window !== "undefined") {
+    const override = window[PARENT_ORIGIN_OVERRIDE_KEY];
+    if (typeof override === "string" && override.length > 0) {
+      console.log(`[vibe-bridge] Using dev-bridge parentOrigin override: ${override}`);
+      return { targetOrigin: override, isTrusted: (o) => o === override };
+    }
+  }
+  const rawList = configured === void 0 ? [] : Array.isArray(configured) ? configured : [configured];
+  const allowlist = rawList.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (allowlist.length === 0) {
+    const actual2 = resolveActualParentOrigin();
+    if (actual2) return { targetOrigin: actual2, isTrusted: (o) => o === actual2 };
+    console.warn(
+      "[vibe-bridge] No `parentOrigin` set and the embedding host could not be auto-detected (no ancestorOrigins/referrer). Pass `parentOrigin` explicitly."
+    );
+    return { targetOrigin: null, isTrusted: () => false };
+  }
+  const exactEntries = allowlist.filter((entry) => !isOriginPattern(entry));
+  const hasPatterns = exactEntries.length !== allowlist.length;
+  if (allowlist.length === 1 && !hasPatterns) {
+    const only = allowlist[0];
+    return { targetOrigin: only, isTrusted: (o) => o === only };
+  }
+  const allowPatterns = hasPatterns && typeof window !== "undefined" && isPreviewSelfHost(window.location.hostname);
+  const isTrusted = (o) => isOriginAllowed(o, allowlist, { allowPatterns });
+  const actual = resolveActualParentOrigin();
+  let targetOrigin = null;
+  if (actual && isTrusted(actual)) {
+    targetOrigin = actual;
+  } else if (actual === null && !allowPatterns && exactEntries.length === 1) {
+    targetOrigin = exactEntries[0];
+  }
+  if (targetOrigin === null) {
+    console.warn(
+      "[vibe-bridge] Could not resolve a parent origin to post to. Check `parentOrigin` against the embedding host" + (hasPatterns && !allowPatterns ? " \u2014 pattern entries are ignored because this page is not served from a recognised preview host." : ".")
+    );
+  }
+  return { targetOrigin, isTrusted };
+}
 var VibeAppBridge = class extends BridgeDataMethods {
-  constructor({ parentOrigin, requestTimeout }) {
+  constructor({ parentOrigin, requestTimeout } = {}) {
     super();
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.context = null;
     this.connectPromise = null;
     this.connectPollInterval = null;
+    this.connectTimeout = null;
     this.onContextReceived = null;
     this.onContextError = null;
     /**
@@ -452,7 +538,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
       }
     };
-    this.parentOrigin = parentOrigin;
+    const policy = resolveOriginPolicy(parentOrigin);
+    this.targetOrigin = policy.targetOrigin;
+    this.isTrustedOrigin = policy.isTrusted;
     this.requestTimeout = requestTimeout;
     this.boundHandleMessage = this.handleMessage.bind(this);
     window.addEventListener("message", this.boundHandleMessage);
@@ -488,6 +576,14 @@ var VibeAppBridge = class extends BridgeDataMethods {
   connect() {
     if (this.context) return Promise.resolve(this.context);
     if (this.connectPromise) return this.connectPromise;
+    if (this.targetOrigin === null) {
+      return Promise.reject(
+        new BridgeError(
+          "PARENT_ORIGIN_UNRESOLVED",
+          "Could not resolve a parent origin to connect to. Check `parentOrigin` against the embedding host."
+        )
+      );
+    }
     this.connectPromise = new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.stopConnectPolling();
@@ -496,6 +592,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.onContextError = null;
         reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
       }, CONNECT_TIMEOUT_MS);
+      this.connectTimeout = timer;
       this.onContextError = (error) => {
         clearTimeout(timer);
         this.stopConnectPolling();
@@ -538,7 +635,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
           requestId,
           payload: { bridgeVersion: version }
         };
-        window.parent.postMessage(message, this.parentOrigin);
+        this.postToParent(message);
       };
       poll();
       this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
@@ -620,6 +717,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
   }
   destroy() {
     this.teardownNavigationTracking();
+    this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
@@ -638,6 +736,10 @@ var VibeAppBridge = class extends BridgeDataMethods {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    if (this.connectTimeout !== null) {
+      clearTimeout(this.connectTimeout);
+      this.connectTimeout = null;
+    }
     this.connectPollIds.clear();
   }
   /**
@@ -694,10 +796,13 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
   }
   sendCommand(type, payload) {
-    window.parent.postMessage(
-      { __protocol: PROTOCOL_ID, __version: PROTOCOL_VERSION, kind: "command", type, payload },
-      this.parentOrigin
-    );
+    this.postToParent({
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "command",
+      type,
+      payload
+    });
   }
   /**
    * Low-level typed request for **any** operation in {@link RequestRegistry}.
@@ -740,11 +845,20 @@ var VibeAppBridge = class extends BridgeDataMethods {
         requestId,
         payload
       };
-      window.parent.postMessage(message, this.parentOrigin);
+      this.postToParent(message);
     });
   }
+  /**
+   * Posts to the embedding host. No-op when no concrete target origin could be
+   * resolved (a config/embedding error) — `connect()` rejects fast in that case
+   * so calls never silently hang waiting on a timeout.
+   */
+  postToParent(message) {
+    if (this.targetOrigin === null) return;
+    window.parent.postMessage(message, this.targetOrigin);
+  }
   handleMessage(event) {
-    if (event.origin !== this.parentOrigin) return;
+    if (!this.isTrustedOrigin(event.origin)) return;
     if (!isBridgeMessage(event.data)) return;
     this.kindHandlers[event.data.kind]?.(event.data);
   }

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.2.0";
+var version = "0.3.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3659,13 +3659,34 @@ declare abstract class BridgeDataMethods {
 
 interface VibeAppBridgeOptions {
     /**
-     * Origin of the Nominal app embedding this iframe (e.g.
-     * `https://app.nominal.so` or `http://localhost:3000`). Must match the host
-     * origin **exactly** — messages from any other origin are ignored, and the
-     * bridge only `postMessage`s to this origin. Drive it from an env var so the
-     * same code works locally and in production.
+     * Origin(s) of the Nominal app embedding this iframe. **Optional.**
+     *
+     * **Omit it** (the recommended default) and the bridge auto-detects the
+     * Nominal page that actually embeds it and talks only to that origin. This is
+     * safe because Nominal serves Vibe Apps behind a `frame-ancestors` CSP, so
+     * only nom-ui can frame the app — a hostile site can't embed it to intercept
+     * what the iframe sends out (`postTaskOutput` bodies, file uploads). Most apps
+     * need nothing here.
+     *
+     * Provide a value to **pin explicitly** — defense in depth, or when deploying
+     * outside Nominal's edge:
+     *
+     * ```ts
+     * parentOrigin: 'https://app.nominal.so'                           // one exact origin
+     * parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app']  // exact + preview pattern
+     * ```
+     *
+     * A pattern's `*` matches exactly one DNS label or port — anchored, scheme
+     * literal — so `https://*.vercel.app` matches `https://pr-7.vercel.app` but
+     * not `https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. Patterns
+     * are honoured only when this app's own page is served from a recognised
+     * preview host (`*.vercel.app`, `*.lovable.app`, `localhost`, …); on a
+     * production custom domain only exact origins match.
+     *
+     * If neither an explicit value nor an auto-detected parent is available,
+     * `connect()` rejects with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`.
      */
-    parentOrigin: string;
+    parentOrigin?: string | string[];
     /**
      * Global per-request timeout in milliseconds before a call rejects with a
      * `BridgeError` whose `code` is `'TIMEOUT'`.
@@ -3702,13 +3723,17 @@ interface VibeAppBridgeOptions {
  * ```
  */
 declare class VibeAppBridge extends BridgeDataMethods {
-    private readonly parentOrigin;
+    /** Concrete origin to `postMessage` to, or `null` if none could be resolved. */
+    private readonly targetOrigin;
+    /** Validates an inbound `event.origin` against the configured allowlist. */
+    private readonly isTrustedOrigin;
     private readonly requestTimeout;
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
     private connectPromise;
     private connectPollInterval;
+    private connectTimeout;
     private onContextReceived;
     private onContextError;
     /**
@@ -3726,7 +3751,7 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly kindHandlers;
     private dispatchPush;
     private readonly pushHandlers;
-    constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
+    constructor({ parentOrigin, requestTimeout }?: VibeAppBridgeOptions);
     /**
      * Connects to the host and returns the tenant/user {@link ContextPayload}.
      * **Call this once on app init and await it before any other method** — data
@@ -3842,6 +3867,12 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     request<K extends keyof RequestRegistry>(type: K, payload: RequestRegistry[K]['payload'], onProgress?: (payload: unknown) => void): Promise<RequestRegistry[K]['data']>;
+    /**
+     * Posts to the embedding host. No-op when no concrete target origin could be
+     * resolved (a config/embedding error) — `connect()` rejects fast in that case
+     * so calls never silently hang waiting on a timeout.
+     */
+    private postToParent;
     private handleMessage;
     private handleResponse;
     private handleProgress;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-var version = "0.2.0";
+var version = "0.3.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3659,13 +3659,34 @@ declare abstract class BridgeDataMethods {
 
 interface VibeAppBridgeOptions {
     /**
-     * Origin of the Nominal app embedding this iframe (e.g.
-     * `https://app.nominal.so` or `http://localhost:3000`). Must match the host
-     * origin **exactly** — messages from any other origin are ignored, and the
-     * bridge only `postMessage`s to this origin. Drive it from an env var so the
-     * same code works locally and in production.
+     * Origin(s) of the Nominal app embedding this iframe. **Optional.**
+     *
+     * **Omit it** (the recommended default) and the bridge auto-detects the
+     * Nominal page that actually embeds it and talks only to that origin. This is
+     * safe because Nominal serves Vibe Apps behind a `frame-ancestors` CSP, so
+     * only nom-ui can frame the app — a hostile site can't embed it to intercept
+     * what the iframe sends out (`postTaskOutput` bodies, file uploads). Most apps
+     * need nothing here.
+     *
+     * Provide a value to **pin explicitly** — defense in depth, or when deploying
+     * outside Nominal's edge:
+     *
+     * ```ts
+     * parentOrigin: 'https://app.nominal.so'                           // one exact origin
+     * parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app']  // exact + preview pattern
+     * ```
+     *
+     * A pattern's `*` matches exactly one DNS label or port — anchored, scheme
+     * literal — so `https://*.vercel.app` matches `https://pr-7.vercel.app` but
+     * not `https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. Patterns
+     * are honoured only when this app's own page is served from a recognised
+     * preview host (`*.vercel.app`, `*.lovable.app`, `localhost`, …); on a
+     * production custom domain only exact origins match.
+     *
+     * If neither an explicit value nor an auto-detected parent is available,
+     * `connect()` rejects with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`.
      */
-    parentOrigin: string;
+    parentOrigin?: string | string[];
     /**
      * Global per-request timeout in milliseconds before a call rejects with a
      * `BridgeError` whose `code` is `'TIMEOUT'`.
@@ -3702,13 +3723,17 @@ interface VibeAppBridgeOptions {
  * ```
  */
 declare class VibeAppBridge extends BridgeDataMethods {
-    private readonly parentOrigin;
+    /** Concrete origin to `postMessage` to, or `null` if none could be resolved. */
+    private readonly targetOrigin;
+    /** Validates an inbound `event.origin` against the configured allowlist. */
+    private readonly isTrustedOrigin;
     private readonly requestTimeout;
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
     private connectPromise;
     private connectPollInterval;
+    private connectTimeout;
     private onContextReceived;
     private onContextError;
     /**
@@ -3726,7 +3751,7 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly kindHandlers;
     private dispatchPush;
     private readonly pushHandlers;
-    constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
+    constructor({ parentOrigin, requestTimeout }?: VibeAppBridgeOptions);
     /**
      * Connects to the host and returns the tenant/user {@link ContextPayload}.
      * **Call this once on app init and await it before any other method** — data
@@ -3842,6 +3867,12 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     request<K extends keyof RequestRegistry>(type: K, payload: RequestRegistry[K]['payload'], onProgress?: (payload: unknown) => void): Promise<RequestRegistry[K]['data']>;
+    /**
+     * Posts to the embedding host. No-op when no concrete target origin could be
+     * resolved (a config/embedding error) — `connect()` rejects fast in that case
+     * so calls never silently hang waiting on a timeout.
+     */
+    private postToParent;
     private handleMessage;
     private handleResponse;
     private handleProgress;

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.2.0";
+var version = "0.3.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -44,6 +44,33 @@ var HttpBridgeError = class extends BridgeError {
     this.name = "HttpBridgeError";
   }
 };
+function isOriginPattern(entry) {
+  return entry.includes("*");
+}
+var patternCache = /* @__PURE__ */ new Map();
+function patternToRegExp(pattern) {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = escaped.replace(/\\\*/g, "[^./:@?#\\s]+");
+  const compiled = new RegExp(`^${body}$`);
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+function matchesOrigin(origin, entry) {
+  if (!isOriginPattern(entry)) return origin === entry;
+  return patternToRegExp(entry).test(origin);
+}
+function isOriginAllowed(origin, allowlist, { allowPatterns }) {
+  for (const entry of allowlist) {
+    if (isOriginPattern(entry)) {
+      if (allowPatterns && matchesOrigin(origin, entry)) return true;
+    } else if (origin === entry) {
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/data-methods.ts
 var BridgeDataMethods = class {
@@ -362,13 +389,72 @@ function resolveRequestTimeout(type, requestTimeout) {
 }
 
 // src/VibeAppBridge.ts
+var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
+var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
+function isPreviewSelfHost(hostname) {
+  return PREVIEW_HOST_RE.test(hostname);
+}
+function resolveActualParentOrigin() {
+  if (typeof window === "undefined") return null;
+  try {
+    const ancestors = window.location.ancestorOrigins;
+    if (ancestors && ancestors.length > 0 && ancestors[0]) return ancestors[0];
+  } catch {
+  }
+  try {
+    if (document.referrer) return new URL(document.referrer).origin;
+  } catch {
+  }
+  return null;
+}
+function resolveOriginPolicy(configured) {
+  if (typeof window !== "undefined") {
+    const override = window[PARENT_ORIGIN_OVERRIDE_KEY];
+    if (typeof override === "string" && override.length > 0) {
+      console.log(`[vibe-bridge] Using dev-bridge parentOrigin override: ${override}`);
+      return { targetOrigin: override, isTrusted: (o) => o === override };
+    }
+  }
+  const rawList = configured === void 0 ? [] : Array.isArray(configured) ? configured : [configured];
+  const allowlist = rawList.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (allowlist.length === 0) {
+    const actual2 = resolveActualParentOrigin();
+    if (actual2) return { targetOrigin: actual2, isTrusted: (o) => o === actual2 };
+    console.warn(
+      "[vibe-bridge] No `parentOrigin` set and the embedding host could not be auto-detected (no ancestorOrigins/referrer). Pass `parentOrigin` explicitly."
+    );
+    return { targetOrigin: null, isTrusted: () => false };
+  }
+  const exactEntries = allowlist.filter((entry) => !isOriginPattern(entry));
+  const hasPatterns = exactEntries.length !== allowlist.length;
+  if (allowlist.length === 1 && !hasPatterns) {
+    const only = allowlist[0];
+    return { targetOrigin: only, isTrusted: (o) => o === only };
+  }
+  const allowPatterns = hasPatterns && typeof window !== "undefined" && isPreviewSelfHost(window.location.hostname);
+  const isTrusted = (o) => isOriginAllowed(o, allowlist, { allowPatterns });
+  const actual = resolveActualParentOrigin();
+  let targetOrigin = null;
+  if (actual && isTrusted(actual)) {
+    targetOrigin = actual;
+  } else if (actual === null && !allowPatterns && exactEntries.length === 1) {
+    targetOrigin = exactEntries[0];
+  }
+  if (targetOrigin === null) {
+    console.warn(
+      "[vibe-bridge] Could not resolve a parent origin to post to. Check `parentOrigin` against the embedding host" + (hasPatterns && !allowPatterns ? " \u2014 pattern entries are ignored because this page is not served from a recognised preview host." : ".")
+    );
+  }
+  return { targetOrigin, isTrusted };
+}
 var VibeAppBridge = class extends BridgeDataMethods {
-  constructor({ parentOrigin, requestTimeout }) {
+  constructor({ parentOrigin, requestTimeout } = {}) {
     super();
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.context = null;
     this.connectPromise = null;
     this.connectPollInterval = null;
+    this.connectTimeout = null;
     this.onContextReceived = null;
     this.onContextError = null;
     /**
@@ -423,7 +509,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
       }
     };
-    this.parentOrigin = parentOrigin;
+    const policy = resolveOriginPolicy(parentOrigin);
+    this.targetOrigin = policy.targetOrigin;
+    this.isTrustedOrigin = policy.isTrusted;
     this.requestTimeout = requestTimeout;
     this.boundHandleMessage = this.handleMessage.bind(this);
     window.addEventListener("message", this.boundHandleMessage);
@@ -459,6 +547,14 @@ var VibeAppBridge = class extends BridgeDataMethods {
   connect() {
     if (this.context) return Promise.resolve(this.context);
     if (this.connectPromise) return this.connectPromise;
+    if (this.targetOrigin === null) {
+      return Promise.reject(
+        new BridgeError(
+          "PARENT_ORIGIN_UNRESOLVED",
+          "Could not resolve a parent origin to connect to. Check `parentOrigin` against the embedding host."
+        )
+      );
+    }
     this.connectPromise = new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.stopConnectPolling();
@@ -467,6 +563,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.onContextError = null;
         reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
       }, CONNECT_TIMEOUT_MS);
+      this.connectTimeout = timer;
       this.onContextError = (error) => {
         clearTimeout(timer);
         this.stopConnectPolling();
@@ -509,7 +606,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
           requestId,
           payload: { bridgeVersion: version }
         };
-        window.parent.postMessage(message, this.parentOrigin);
+        this.postToParent(message);
       };
       poll();
       this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
@@ -591,6 +688,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
   }
   destroy() {
     this.teardownNavigationTracking();
+    this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
@@ -609,6 +707,10 @@ var VibeAppBridge = class extends BridgeDataMethods {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    if (this.connectTimeout !== null) {
+      clearTimeout(this.connectTimeout);
+      this.connectTimeout = null;
+    }
     this.connectPollIds.clear();
   }
   /**
@@ -665,10 +767,13 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
   }
   sendCommand(type, payload) {
-    window.parent.postMessage(
-      { __protocol: PROTOCOL_ID, __version: PROTOCOL_VERSION, kind: "command", type, payload },
-      this.parentOrigin
-    );
+    this.postToParent({
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "command",
+      type,
+      payload
+    });
   }
   /**
    * Low-level typed request for **any** operation in {@link RequestRegistry}.
@@ -711,11 +816,20 @@ var VibeAppBridge = class extends BridgeDataMethods {
         requestId,
         payload
       };
-      window.parent.postMessage(message, this.parentOrigin);
+      this.postToParent(message);
     });
   }
+  /**
+   * Posts to the embedding host. No-op when no concrete target origin could be
+   * resolved (a config/embedding error) — `connect()` rejects fast in that case
+   * so calls never silently hang waiting on a timeout.
+   */
+  postToParent(message) {
+    if (this.targetOrigin === null) return;
+    window.parent.postMessage(message, this.targetOrigin);
+  }
   handleMessage(event) {
-    if (event.origin !== this.parentOrigin) return;
+    if (!this.isTrustedOrigin(event.origin)) return;
     if (!isBridgeMessage(event.data)) return;
     this.kindHandlers[event.data.kind]?.(event.data);
   }

package/docs/connect-lifecycle.md

@@ -34,7 +34,7 @@ The host pushes context to the iframe on load, but the iframe's listener may not
 4. The bridge begins auto-tracking SPA navigation (see below).
 5. If nothing arrives within **10 seconds**, `connect()` rejects with a `BridgeError` (code `'TIMEOUT'`, message `Bridge connect timed out`).
 
-A timeout almost always means a `parentOrigin` mismatch or the host never mounted.
+A timeout almost always means a `parentOrigin` mismatch or the host never mounted. A separate, immediate rejection — `BridgeError` code `PARENT_ORIGIN_UNRESOLVED` — means no concrete parent origin could be resolved at all (e.g. a pattern-only `parentOrigin` on a non-preview host); fix `parentOrigin` rather than waiting on the timeout.
 
 ## Initial deep link
 

package/docs/getting-started.md

@@ -15,9 +15,7 @@ No runtime dependencies. Ships ESM + CJS with self-contained TypeScript types.
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
-})
+const bridge = new VibeAppBridge() // auto-detects the embedding Nominal host
 
 async function main() {
   const ctx: ContextPayload = await bridge.connect()
@@ -32,20 +30,24 @@ async function main() {
 main().catch(console.error)
 ```
 
-## `parentOrigin`
+## `parentOrigin` (optional)
 
-`parentOrigin` is the **origin** (scheme + host + port, no path, no trailing slash) of the Nominal app that embeds your iframe. It must match exactly — the bridge ignores messages from any other origin and only posts to this one.
+By default you pass **nothing** — the bridge auto-detects the Nominal app that embeds your iframe and talks only to it. This is safe because Nominal serves Vibe Apps behind a `frame-ancestors` CSP, so only nom-ui can frame the app. Most apps need nothing here.
 
-Drive it from an environment variable so the same code works locally and in production:
+Pass `parentOrigin` to **pin the host origin** explicitly (defense in depth, or when running outside Nominal's edge). It's an **origin** — scheme + host + port, no path, no trailing slash. Drive it from an env var, or use a list / **glob patterns** for dynamic preview deployments:
 
-```sh
-# .env (committed — standalone/dev default)
-VITE_PARENT_ORIGIN=http://localhost:5173
+```ts
+new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
+```
 
-# .env.local (git-ignored — when testing inside nom-ui locally)
+```sh
+# .env.local — when pinning explicitly while testing inside nom-ui locally
 VITE_PARENT_ORIGIN=http://localhost:3000
 ```
 
+A pattern's `*` matches exactly one DNS label or port (anchored, scheme literal). Patterns are honoured **only when the app's own page is served from a recognised preview host** (`*.vercel.app`, `*.lovable.app`, `localhost`, …); on a production custom domain they are ignored and only exact origins match. Keep at least one exact origin in the list.
+
 ## Next
 
 - [`connect-lifecycle.md`](./connect-lifecycle.md) — how `connect()` works and the connection lifecycle.

package/llms.txt

@@ -2,12 +2,12 @@
 
 > Iframe-side TypeScript SDK for building Nominal Vibe Apps — standalone browser apps (often built with Lovable) embedded in the Nominal platform via a cross-origin iframe. Connects the app to its Nominal host over a typed postMessage protocol: read Nominal data, submit Close-Management task outputs, upload files, and keep deep-link routing in sync. Browser-only, zero runtime dependencies.
 
-The integration is always the same: construct `VibeAppBridge` with the host `parentOrigin`, `await bridge.connect()` once (it returns the tenant/user `ContextPayload`), then call any of the ~46 typed data methods, `upload(file, options)`, or `postTaskOutput(...)`. Tear down with `bridge.destroy()`. The only write path into Nominal is `postTaskOutput`.
+The integration is always the same: `new VibeAppBridge()` (no config — `parentOrigin` is optional and the bridge auto-detects the embedding Nominal host; pass it only to pin explicitly or to allow preview origins), `await bridge.connect()` once (it returns the tenant/user `ContextPayload`), then call any of the ~46 typed data methods, `upload(file, options)`, or `postTaskOutput(...)`. Tear down with `bridge.destroy()`. The only write path into Nominal is `postTaskOutput`.
 
 ## Docs
 
 - [README](./README.md): install, quickstart, full API, common mistakes, and the operation catalog.
-- [Getting started](./docs/getting-started.md): install + minimal app + `parentOrigin` setup.
+- [Getting started](./docs/getting-started.md): install + minimal app + optional `parentOrigin` pinning.
 - [Connection lifecycle](./docs/connect-lifecycle.md): `connect()` semantics, `ContextPayload`, timeout, subroute sync, teardown.
 - [Fetching data](./docs/data-fetching.md): named methods vs the typed `request()` escape hatch, payload shapes, errors/timeouts, operation list.
 - [File upload](./docs/file-upload.md): `upload(file, options)`, progress events, constraints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Iframe-side SDK for building Nominal Vibe Apps — connects an embedded app to its Nominal host over a typed postMessage bridge (context, data fetch, file upload, subroute deep-linking).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",