@nominalso/vibe-bridge 0.5.0 → 0.6.0

package/docs/getting-started.md

@@ -8,7 +8,9 @@
 npm install @nominalso/vibe-bridge
 ```
 
-Bundles `posthog-js` (its only runtime dependency) for host-enabled in-iframe session recording. Ships ESM + CJS with self-contained TypeScript types.
+Ships ESM + CJS with self-contained TypeScript types. `posthog-js` is an **optional dependency** used only for host-enabled in-iframe session recording (the SDK no-ops gracefully if it's absent).
+
+**Safe to import anywhere.** The package draws a clean server/client boundary, so `import { VibeAppBridge } from '@nominalso/vibe-bridge'` is safe from an SSR entry, a React Server Component, or an edge/Worker runtime: importing has no side effects, `new VibeAppBridge()` is pure, and the browser is only needed when a method actually runs (calling one outside a browser throws `BridgeError` code `'SERVER_ENVIRONMENT'`). You do **not** need `createClientOnlyFn`, dynamic `import()`, or `typeof window` guards — just construct in a client component and `connect()` in an effect. See the README's "Safe to import anywhere" and "Common recipes" sections.
 
 ## Minimal app
 

package/llms.txt

@@ -1,9 +1,11 @@
 # @nominalso/vibe-bridge
 
-> 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, keep deep-link routing in sync, and (when the host enables it) record the in-iframe session to PostHog. Browser-only; bundles posthog-js as its only runtime dependency.
+> 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, keep deep-link routing in sync, and (when the host enables it) record the in-iframe session to PostHog. Methods run in the browser, but the package is safe to import from anywhere — SSR, React Server Components, and edge/Worker runtimes — with a clean server/client boundary; posthog-js is an optional dependency.
 
 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`. Session recording auto-initializes on `connect()` only when the host sends a `posthog` block with `enabled: true`; emit custom events with `bridge.track(event, properties?)` (a no-op until then).
 
+Server/client boundary: importing and `new VibeAppBridge()` are side-effect-free and safe during SSR / in a React Server Component / in a Worker; the browser is only required when a method actually runs (calling one without a `window` throws `BridgeError` code `SERVER_ENVIRONMENT`). RSC / Worker / edge runtimes resolve to a server-safe stub via `react-server`/`worker`/`workerd`/`edge-light`/`deno` export conditions, while plain Node and jsdom/happy-dom test runners (Vitest/Jest) get the real, self-guarding build; the client build is marked `'use client'`. No `createClientOnlyFn`, dynamic `import()`, or `typeof window` guards are needed. The error classes are import-safe from any environment; detect them with `BridgeError.isBridgeError(err)` / `HttpBridgeError.isHttpBridgeError(err)`.
+
 ## Docs
 
 - [README](./README.md): install, quickstart, full API, common mistakes, and the operation catalog.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.5.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).",
+  "version": "0.6.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). Safe to import from SSR, React Server Components, and edge/Worker runtimes.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",
   "bugs": {
@@ -13,16 +13,33 @@
     "directory": "packages/bridge"
   },
   "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.browser.cjs",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
+      "react-server": "./dist/index.server.js",
+      "workerd": "./dist/index.server.js",
+      "worker": "./dist/index.server.js",
+      "edge-light": "./dist/index.server.js",
+      "deno": "./dist/index.server.js",
+      "browser": {
+        "import": "./dist/index.browser.js",
+        "require": "./dist/index.browser.cjs"
+      },
+      "default": {
+        "import": "./dist/index.browser.js",
+        "require": "./dist/index.browser.cjs"
+      }
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.server.js",
+      "require": "./dist/index.server.cjs"
+    },
+    "./package.json": "./package.json"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "docs",
@@ -33,36 +50,16 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "posthog-js": "^1.393.5"
   },
   "devDependencies": {
     "@nominalso/vibe-api-types": "0.0.1",
     "@nominalso/vibe-protocol-types": "0.0.1"
   },
-  "tsup": {
-    "entry": [
-      "src/index.ts"
-    ],
-    "format": [
-      "cjs",
-      "esm"
-    ],
-    "noExternal": [
-      "@nominalso/vibe-protocol-types",
-      "@nominalso/vibe-api-types"
-    ],
-    "dts": {
-      "resolve": [
-        "@nominalso/vibe-protocol-types",
-        "@nominalso/vibe-api-types"
-      ]
-    },
-    "clean": true
-  },
   "scripts": {
     "clean": "rm -rf dist node_modules",
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"