@nominalso/vibe-bridge 0.1.0 → 0.3.0

package/docs/file-upload.md

@@ -25,6 +25,8 @@ Sandboxed cross-origin iframes cannot pass `File` handles across windows, so the
 ## Example — file input with a progress bar
 
 ```ts
+import { BridgeError } from '@nominalso/vibe-bridge'
+
 const input = document.querySelector<HTMLInputElement>('#file-input')!
 
 input.addEventListener('change', async () => {
@@ -40,9 +42,14 @@ input.addEventListener('change', async () => {
     })
     console.log('Uploaded:', result.attachmentId, result.name)
   } catch (err) {
+    // A failed upload throws a BridgeError with a code, e.g. 'FILE_TOO_LARGE'
+    // (host limit is 50 MB), 'RATE_LIMITED', or 'TIMEOUT' (uploads allow 120 s).
+    if (err instanceof BridgeError && err.code === 'FILE_TOO_LARGE') {
+      alert('That file is too large (50 MB max).')
+    }
     console.error('Upload failed:', err instanceof Error ? err.message : err)
   }
 })
 ```
 
-`upload()` resolves only after the host has fully stored the file; progress ticks arrive before it resolves.
+`upload()` resolves only after the host has fully stored the file; progress ticks arrive before it resolves. Import `BridgeError` from `@nominalso/vibe-bridge` to branch on `err.code`.

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.1.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",