@xeonr/renderer-sdk 1.0.4 → 1.1.0

package/dist/react/dom.js

@@ -0,0 +1,36 @@
+/**
+ * Drop-in replacement for `react-dom/client` that auto-wraps the rendered
+ * tree in `<RendererErrorBoundary>`. Used by `@xeonr/renderer-plugin-vite`
+ * to rewrite renderer-archive build imports so the boundary is mandatory
+ * without renderer authors having to opt in.
+ *
+ * Renderer authors do NOT need to import this directly — the vite plugin
+ * substitutes `react-dom/client` specifiers in renderer source code at
+ * build time. If a renderer is built outside the plugin (e.g. a custom
+ * pipeline), authors can import from here explicitly instead.
+ *
+ * Mirrors React 18+ `Root` / `RootOptions` surface; passes everything
+ * through unchanged except for `render` and `hydrateRoot`'s initial
+ * children, which are wrapped in the boundary so a single render-time
+ * crash is forwarded to the host overlay rather than tearing down the
+ * iframe silently.
+ */
+import { createRoot as origCreateRoot, hydrateRoot as origHydrateRoot, } from 'react-dom/client';
+import { createElement } from 'react';
+import { RendererErrorBoundary } from './RendererErrorBoundary.js';
+function wrap(children) {
+    return createElement(RendererErrorBoundary, null, children);
+}
+export function createRoot(container, options) {
+    const root = origCreateRoot(container, options);
+    const originalRender = root.render.bind(root);
+    root.render = (children) => originalRender(wrap(children));
+    return root;
+}
+export function hydrateRoot(container, initialChildren, options) {
+    const root = origHydrateRoot(container, wrap(initialChildren), options);
+    const originalRender = root.render.bind(root);
+    root.render = (children) => originalRender(wrap(children));
+    return root;
+}
+//# sourceMappingURL=dom.js.map

package/dist/react/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/react/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACN,UAAU,IAAI,cAAc,EAC5B,WAAW,IAAI,eAAe,GAI9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,SAAS,IAAI,CAAC,QAAmB;IAChC,OAAO,aAAa,CAAC,qBAAqB,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAAqC,EAAE,OAAqB;IACtF,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,GAAG,CAAC,QAAmB,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CAC1B,SAA6B,EAC7B,eAA0B,EAC1B,OAA0B;IAE1B,MAAM,IAAI,GAAG,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;IACxE,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,GAAG,CAAC,QAAmB,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/react/index.d.ts

@@ -1,3 +1,5 @@
 export { useRendererClient } from './useRendererClient.js';
 export type { UseRendererClientOptions, UseRendererClientResult } from './useRendererClient.js';
+export { RendererErrorBoundary } from './RendererErrorBoundary.js';
+export type { RendererErrorBoundaryProps } from './RendererErrorBoundary.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/react/index.js

@@ -1,2 +1,3 @@
 export { useRendererClient } from './useRendererClient.js';
+export { RendererErrorBoundary } from './RendererErrorBoundary.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/react/useRendererClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRendererClient.d.ts","sourceRoot":"","sources":["../../src/react/useRendererClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAEjH,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;CAAG;AAE1E,MAAM,WAAW,uBAAuB;IACvC,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,2CAA2C;IAC3C,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kDAAkD;IAClD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,UAAU,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC1C,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gDAAgD;IAChD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,+DAA+D;IAC/D,MAAM,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAgF7F"}
+{"version":3,"file":"useRendererClient.d.ts","sourceRoot":"","sources":["../../src/react/useRendererClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAEjH,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;CAAG;AAqB1E,MAAM,WAAW,uBAAuB;IACvC,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,2CAA2C;IAC3C,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kDAAkD;IAClD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,UAAU,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC1C,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gDAAgD;IAChD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,+DAA+D;IAC/D,MAAM,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAgF7F"}

package/dist/react/useRendererClient.js

@@ -1,5 +1,24 @@
 import { useState, useRef, useEffect, useMemo } from 'react';
 import { RendererClient } from '../client.js';
+/**
+ * Apply the host's theme to the renderer document. Two distinct effects:
+ *
+ *   - `documentElement.dataset.theme` — surfaces the theme as a
+ *     `[data-theme="dark"]` selector for renderer-authored CSS.
+ *   - `documentElement.style.colorScheme` — tells the browser to render
+ *     scrollbars, form controls, and (critically) the iframe's default
+ *     canvas in the matching mode. Without this, a cross-origin iframe
+ *     defaults to a white canvas regardless of what the host's
+ *     `color-scheme` is — so `background: transparent` in the renderer
+ *     reveals white, not the host's dark surface. This is the fix for
+ *     "renderer shows light mode when host is dark".
+ */
+function applyThemeToDocument(theme) {
+    if (typeof document === 'undefined')
+        return;
+    document.documentElement.dataset.theme = theme;
+    document.documentElement.style.colorScheme = theme;
+}
 /**
  * React hook for building custom renderers.
  *
@@ -51,11 +70,11 @@ export function useRendererClient(options) {
             setEntrypoint(payload.entrypoint);
             setApiBaseUrl(payload.apiBaseUrl);
             setPath(client.getPath());
-            document.documentElement.dataset.theme = payload.theme;
+            applyThemeToDocument(payload.theme);
         });
         const unsubTheme = client.onThemeChange((newTheme) => {
             setTheme(newTheme);
-            document.documentElement.dataset.theme = newTheme;
+            applyThemeToDocument(newTheme);
         });
         const unsubToken = client.onTokenRefresh((newToken, newExpiresAt) => {
             setToken(newToken);

package/dist/react/useRendererClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"useRendererClient.js","sourceRoot":"","sources":["../../src/react/useRendererClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useRendererClient.js","sourceRoot":"","sources":["../../src/react/useRendererClient.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -11,6 +11,27 @@ export interface RendererConfig {
         allowForms?: boolean;
         allowDownloads?: boolean;
     };
+    /**
+     * Extra origins this renderer needs to reach via `fetch` / `XMLHttpRequest`
+     * / WebSocket. Surfaced to the browser as additional entries in the CSP
+     * `connect-src` directive. The upl.im API + auth hosts are always allowed
+     * by the renderer-proxy; only list extras here (e.g. a third-party API
+     * the renderer integrates with).
+     *
+     * Each entry is a fully-qualified origin like `https://api.example.com`
+     * or a wildcarded host like `https://*.example.com`. No paths, no
+     * trailing slashes. Origins are validated at deploy time.
+     */
+    connectHosts?: string[];
+    /**
+     * Short build identifier the build pipeline stamps into config.json
+     * (e.g. the renderer-plugin-vite hash of the output directory).
+     * Surfaced in crash telemetry as a separate dimension so we can
+     * distinguish "crashed in build A" from "crashed in build B" even
+     * when both builds share the same archive_upload_id (the developer
+     * republished without bumping the archive). Bounded to 64 chars.
+     */
+    buildHash?: string;
 }
 export type RendererPermission = 'createFolder' | 'openUpload';
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,uDAAuD;IACvD,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,cAAc,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACF;AAED,MAAM,MAAM,kBAAkB,GAC3B,cAAc,GACd,YAAY,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,uBAAuB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;CAC5C;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC3B,wBAAwB;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,mCAAmC;IACnC,UAAU,EAAE,WAAW,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,KAAK,EAAE,aAAa,CAAC;IACrB,4DAA4D;IAC5D,aAAa,EAAE,aAAa,CAAC;IAC7B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,uDAAuD;IACvD,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,cAAc,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,kBAAkB,GAC3B,cAAc,GACd,YAAY,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,uBAAuB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;CAC5C;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC3B,wBAAwB;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,mCAAmC;IACnC,UAAU,EAAE,WAAW,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,KAAK,EAAE,aAAa,CAAC;IACrB,4DAA4D;IAC5D,aAAa,EAAE,aAAa,CAAC;IAC7B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeonr/renderer-sdk",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "license": "ISC",
   "description": "SDK for building custom renderers for upl.im integrations",
@@ -15,6 +15,10 @@
       "default": "./dist/react/index.js",
       "types": "./dist/react/index.d.ts"
     },
+    "./react/dom": {
+      "default": "./dist/react/dom.js",
+      "types": "./dist/react/dom.d.ts"
+    },
     "./protocol": {
       "default": "./dist/protocol.js",
       "types": "./dist/protocol.d.ts"
@@ -25,16 +29,22 @@
     }
   },
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.8.3"
   },
   "scripts": {

package/src/client.ts

@@ -6,8 +6,10 @@ import type {
 	HostGenerateTokenResultMessage,
 	IframeHistoryPushMessage,
 	IframeHistoryReplaceMessage,
+	IframeCrashMessage,
+	RendererCrashKind,
 } from './protocol.js';
-import { isHostMessage } from './protocol.js';
+import { buildCrashMessage, isHostMessage, postCrashToHost } from './protocol.js';
 import type { InitPayload, RendererApiAdapter, RendererConfig, RendererScope, RenderingType } from './types.js';
 
 export interface RendererClientOptions {
@@ -61,7 +63,11 @@ export class RendererClient {
 	private currentPath: string = '/';
 
 	private listener: ((event: MessageEvent) => void) | null = null;
+	private errorListener: ((event: ErrorEvent) => void) | null = null;
+	private rejectionListener: ((event: PromiseRejectionEvent) => void) | null = null;
 	private hashChangeListener: (() => void) | null = null;
+	private readyRetryInterval: ReturnType<typeof setInterval> | null = null;
+	private readyRetryTimeout: ReturnType<typeof setTimeout> | null = null;
 	private historyPatched = false;
 	private originalPushState: typeof history.pushState | null = null;
 	private originalReplaceState: typeof history.replaceState | null = null;
@@ -243,10 +249,19 @@ export class RendererClient {
 	/** Remove all listeners and stop the client. */
 	destroy(): void {
 		this.destroyed = true;
+		this.stopReadyRetry();
 		if (this.listener) {
 			window.removeEventListener('message', this.listener);
 			this.listener = null;
 		}
+		if (this.errorListener) {
+			window.removeEventListener('error', this.errorListener);
+			this.errorListener = null;
+		}
+		if (this.rejectionListener) {
+			window.removeEventListener('unhandledrejection', this.rejectionListener);
+			this.rejectionListener = null;
+		}
 		if (this.hashChangeListener) {
 			window.removeEventListener('hashchange', this.hashChangeListener);
 			this.hashChangeListener = null;
@@ -276,13 +291,41 @@ export class RendererClient {
 			if (this.targetOrigin !== '*' && event.origin !== this.targetOrigin) return;
 			if (!isHostMessage(event.data)) return;
 
+			// Any valid host message implies the host's listener is attached and the
+			// handshake is underway, so stop pinging.
+			this.stopReadyRetry();
 			this.handleMessage(event.data);
 		};
 
 		window.addEventListener('message', this.listener);
 
-		// Tell the host we're ready
+		this.installCrashHooks();
+
+		// Tell the host we're ready. We retry on an interval because a fast iframe can
+		// post 'ready' before the host has attached its message listener — the first
+		// ping is lost, the host times out, and the user has to click retry. Pinging
+		// until the host responds closes that race without changing the protocol.
 		this.postToHost({ type: 'uplim:ready' });
+		this.readyRetryInterval = setInterval(() => {
+			if (this.destroyed) return;
+			this.postToHost({ type: 'uplim:ready' });
+		}, 200);
+		// Bound the retries: if the host genuinely isn't there after 8s, stop pinging
+		// so we don't spam a misbehaving parent.
+		this.readyRetryTimeout = setTimeout(() => {
+			this.stopReadyRetry();
+		}, 8000);
+	}
+
+	private stopReadyRetry(): void {
+		if (this.readyRetryInterval) {
+			clearInterval(this.readyRetryInterval);
+			this.readyRetryInterval = null;
+		}
+		if (this.readyRetryTimeout) {
+			clearTimeout(this.readyRetryTimeout);
+			this.readyRetryTimeout = null;
+		}
 	}
 
 	private handleMessage(message: HostMessage): void {
@@ -423,4 +466,64 @@ export class RendererClient {
 		if (this.destroyed) return;
 		window.parent.postMessage(message, this.targetOrigin);
 	}
+
+	/**
+	 * Install window-level crash hooks the moment the client is constructed
+	 * (i.e. as soon as a renderer touches the SDK). We deliberately do this
+	 * here — not in a React-only entry point — so that even renderers that
+	 * forget to wrap their root in `<RendererErrorBoundary>` still report
+	 * async / global failures to the host.
+	 *
+	 * The two hooks cover the failure modes a React boundary can't see:
+	 *   - `window.error` — synchronous throws outside React's tree (raw
+	 *     <script> bugs, event-handler exceptions, image onerror handlers).
+	 *   - `unhandledrejection` — Promise chains with no `.catch()`, which
+	 *     are surprisingly common in fetch-heavy renderers.
+	 *
+	 * Both fire-and-forget via `postCrashToHost`; the host decides whether
+	 * to render the overlay (a single render-time crash usually warrants
+	 * it, a stray unhandled rejection may not).
+	 */
+	private installCrashHooks(): void {
+		if (typeof window === 'undefined') return;
+
+		this.errorListener = (event: ErrorEvent) => {
+			if (this.destroyed) return;
+			// Prefer event.error for the real stack; fall back to a synthetic
+			// shape when the browser only gave us message/filename/lineno
+			// (cross-origin scripts strip event.error to null).
+			const thrown = event.error ?? {
+				name: 'ErrorEvent',
+				message: event.message || 'Uncaught error',
+				stack: event.filename
+					? `at ${event.filename}:${event.lineno ?? '?'}:${event.colno ?? '?'}`
+					: '',
+			};
+			this.reportCrash('error', thrown);
+		};
+		window.addEventListener('error', this.errorListener);
+
+		this.rejectionListener = (event: PromiseRejectionEvent) => {
+			if (this.destroyed) return;
+			this.reportCrash('unhandled-rejection', event.reason);
+		};
+		window.addEventListener('unhandledrejection', this.rejectionListener);
+	}
+
+	/**
+	 * Forward a crash to the host. Called by the global hooks and by
+	 * `<RendererErrorBoundary>`; renderers may also call it explicitly if
+	 * they catch something themselves and want it surfaced (e.g. data-load
+	 * failure that wipes the UI even though no exception escaped).
+	 *
+	 * No-throw: telemetry must never make the underlying crash worse.
+	 */
+	reportCrash(kind: RendererCrashKind, thrown: unknown): void {
+		try {
+			const msg: IframeCrashMessage = buildCrashMessage(kind, thrown);
+			postCrashToHost(msg, this.targetOrigin);
+		} catch {
+			// Swallowed on purpose — see above.
+		}
+	}
 }

package/src/index.ts

@@ -20,6 +20,8 @@ export {
 	isRendererMessage,
 	isHostMessage,
 	isIframeMessage,
+	buildCrashMessage,
+	postCrashToHost,
 } from './protocol.js';
 
 export type {
@@ -39,5 +41,7 @@ export type {
 	IframeGenerateTokenMessage,
 	IframeHistoryPushMessage,
 	IframeHistoryReplaceMessage,
+	IframeCrashMessage,
+	RendererCrashKind,
 	RendererMessage,
 } from './protocol.js';

package/src/protocol.ts

@@ -104,6 +104,53 @@ export interface IframeHistoryReplaceMessage {
 	path: string;
 }
 
+/**
+ * Which SDK code path observed the failure. Maps directly to the host's
+ * `RendererCrashKind` enum so the wire schema and the telemetry shape
+ * stay in sync.
+ *
+ * - `render` — React tree threw during render/commit; caught by the
+ *   SDK's mandatory ErrorBoundary at the renderer root. The UI is gone.
+ * - `error` — `window.onerror`: synchronous uncaught exception outside
+ *   React (event handler, top-level script). UI may or may not still
+ *   be visible.
+ * - `unhandled-rejection` — `window.onunhandledrejection`: a Promise
+ *   rejected with no `.catch()`. Almost always async, often non-fatal,
+ *   but a useful signal that something is wrong.
+ */
+export type RendererCrashKind = 'render' | 'error' | 'unhandled-rejection';
+
+/**
+ * Tells the host the renderer just hit an unhandled exception. The host
+ * decides what to render in response (typically an overlay with reload
+ * and fallback options); the renderer never paints its own crash screen
+ * because (a) styling would be inconsistent with the host UI and (b) a
+ * render-time crash may have left the renderer's CSS / DOM unusable.
+ *
+ * Fields are deliberately string-bounded on the proto side (see
+ * `ReportRendererCrashRequest`) — keep payloads under those limits
+ * before posting.
+ */
+export interface IframeCrashMessage {
+	type: 'uplim:crash';
+	kind: RendererCrashKind;
+	/** Error.name (e.g. `TypeError`). Empty when the source threw a non-Error. */
+	name: string;
+	/** Error.message — user-facing description of the failure. */
+	message: string;
+	/** Stack trace if the browser exposed one. May be minified in prod builds. */
+	stack: string;
+	/** `window.location.href` at the time of the crash, for narrowing down the route. */
+	rendererLocation?: string;
+	/** Iframe-side wall-clock millis when the crash was observed. */
+	reportedAtMs: number;
+	// NOTE: things the parent can observe for itself (user agent, viewport,
+	// buildHash from the rendererConfig the host already holds) are
+	// captured host-side in useRendererBridge — we don't trust the iframe
+	// to populate them. The iframe only sends what *only* it can know:
+	// the crash facts.
+}
+
 export type IframeMessage =
 	| IframeReadyMessage
 	| IframeOpenUploadMessage
@@ -112,7 +159,8 @@ export type IframeMessage =
 	| IframeInitAckMessage
 	| IframeGenerateTokenMessage
 	| IframeHistoryPushMessage
-	| IframeHistoryReplaceMessage;
+	| IframeHistoryReplaceMessage
+	| IframeCrashMessage;
 
 // ---------------------------------------------------------------------------
 // Union type for any message
@@ -138,6 +186,100 @@ export function isHostMessage(data: unknown): data is HostMessage {
 	return t === 'uplim:init' || t === 'uplim:theme' || t === 'uplim:token' || t === 'uplim:generateTokenResult' || t === 'uplim:historyBack' || t === 'uplim:historyForward';
 }
 
+// Proto-side limits (see ReportRendererCrashRequest) — clamp before sending so
+// we don't get truncated mid-string by buf.validate and miss the crash entirely.
+const CRASH_NAME_MAX = 256;
+const CRASH_MESSAGE_MAX = 4096;
+const CRASH_STACK_MAX = 32768;
+const CRASH_LOCATION_MAX = 2048;
+
+function clampString(value: string, max: number): string {
+	if (value.length <= max) return value;
+	// Reserve a marker so it's obvious in telemetry that we truncated.
+	const suffix = '…[truncated]';
+	return value.slice(0, max - suffix.length) + suffix;
+}
+
+/**
+ * Build an `IframeCrashMessage` from an unknown thrown value. Centralised so
+ * the React boundary and the global `error` / `unhandledrejection` hooks all
+ * produce identically-shaped payloads regardless of what JS threw at them
+ * (strings, objects, DOMExceptions, real Errors, …).
+ *
+ * Only includes what the iframe is the sole source-of-truth for —
+ * `name`, `message`, `stack`, `rendererLocation`, `kind`. UA, viewport,
+ * buildHash are deliberately omitted: the parent observes them directly
+ * (and trusting the iframe to self-report those opens a small but
+ * pointless spoof surface).
+ */
+export function buildCrashMessage(
+	kind: RendererCrashKind,
+	thrown: unknown,
+): IframeCrashMessage {
+	let name = '';
+	let message = '';
+	let stack = '';
+	if (thrown instanceof Error) {
+		name = thrown.name || 'Error';
+		message = thrown.message || String(thrown);
+		stack = thrown.stack ?? '';
+	} else if (typeof thrown === 'string') {
+		name = 'StringError';
+		message = thrown;
+	} else if (thrown && typeof thrown === 'object') {
+		const obj = thrown as { name?: unknown; message?: unknown; stack?: unknown };
+		name = typeof obj.name === 'string' ? obj.name : 'UnknownError';
+		message = typeof obj.message === 'string' ? obj.message : safeStringify(thrown);
+		stack = typeof obj.stack === 'string' ? obj.stack : '';
+	} else {
+		name = 'UnknownError';
+		message = String(thrown);
+	}
+
+	let rendererLocation: string | undefined;
+	if (typeof window !== 'undefined' && window.location) {
+		rendererLocation = clampString(window.location.href, CRASH_LOCATION_MAX);
+	}
+
+	return {
+		type: 'uplim:crash',
+		kind,
+		name: clampString(name, CRASH_NAME_MAX),
+		message: clampString(message, CRASH_MESSAGE_MAX),
+		stack: clampString(stack, CRASH_STACK_MAX),
+		rendererLocation,
+		reportedAtMs: Date.now(),
+	};
+}
+
+function safeStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+/**
+ * Fire-and-forget post of a crash message to the host. Used by both the SDK's
+ * global hooks and the React boundary. Falls back silently when called outside
+ * an iframe (e.g. SSR tests) so the SDK never throws on `window.parent` being
+ * `undefined`.
+ *
+ * `targetOrigin` defaults to `'*'` — at crash time we deliberately do not
+ * filter, because the renderer may have lost the host origin context (e.g.
+ * if the crash happened before `init` arrived).
+ */
+export function postCrashToHost(message: IframeCrashMessage, targetOrigin: string = '*'): void {
+	if (typeof window === 'undefined' || !window.parent || window.parent === window) return;
+	try {
+		window.parent.postMessage(message, targetOrigin);
+	} catch {
+		// postMessage can throw on some browsers if the target origin is bad
+		// (cross-origin frame missing). Telemetry is best-effort.
+	}
+}
+
 export function isIframeMessage(data: unknown): data is IframeMessage {
 	if (!isRendererMessage(data)) return false;
 	return !isHostMessage(data);

package/src/react/RendererErrorBoundary.tsx

@@ -0,0 +1,95 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { buildCrashMessage, postCrashToHost } from '../protocol.js';
+
+/**
+ * React error boundary that catches render-time exceptions and forwards
+ * them to the host via `uplim:crash`. **Renderers should wrap their root
+ * in this component** — the SDK's global window hooks catch async
+ * failures, but they cannot catch errors thrown during React render or
+ * commit (those abort the tree before bubbling to `window.error`).
+ *
+ * Deliberately renders **nothing** on crash. The host owns the overlay
+ * UI for two reasons:
+ *   1. Styling stays consistent with the dashboard chrome — a renderer's
+ *      CSS may itself be the thing that broke, so painting an inline
+ *      fallback inside the iframe risks an invisible / unreadable
+ *      screen.
+ *   2. The host's overlay can offer recovery actions the renderer
+ *      can't, like "open the built-in preview instead" (which involves
+ *      tearing this iframe down and rendering something else).
+ *
+ * Renderers may pass a `fallback` if they want a minimal visible
+ * placeholder while the host's overlay paints (e.g. so users don't
+ * stare at a transparent iframe for a frame), but the host overlay
+ * remains the source of truth.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * import { createRoot } from 'react-dom/client';
+ * import { RendererErrorBoundary } from '@xeonr/renderer-sdk/react';
+ *
+ * createRoot(document.getElementById('root')!).render(
+ *   <RendererErrorBoundary>
+ *     <App />
+ *   </RendererErrorBoundary>
+ * );
+ * ```
+ */
+export interface RendererErrorBoundaryProps {
+	children: ReactNode;
+	/** Optional inline fallback rendered after the crash is reported. Default: nothing. */
+	fallback?: ReactNode;
+	/**
+	 * Optional targetOrigin override for the postMessage. Matches
+	 * `RendererClientOptions.targetOrigin`. Defaults to `'*'` because at
+	 * crash time we don't want to gate telemetry on origin matching.
+	 */
+	targetOrigin?: string;
+	/** Optional hook called after the host has been notified — useful for sentry / console wiring. */
+	onCrash?: (error: unknown, info: ErrorInfo) => void;
+}
+
+interface State {
+	crashed: boolean;
+}
+
+export class RendererErrorBoundary extends Component<RendererErrorBoundaryProps, State> {
+	state: State = { crashed: false };
+
+	static getDerivedStateFromError(): State {
+		return { crashed: true };
+	}
+
+	componentDidCatch(error: unknown, info: ErrorInfo): void {
+		// Build the crash payload via the shared helper so global hooks and the
+		// boundary produce identical wire shapes.
+		const msg = buildCrashMessage('render', error);
+
+		// React stack is more useful than the JS stack for render-time bugs —
+		// it points at the component path, not just the throwing function. We
+		// append it so server-side logs preserve both.
+		if (info?.componentStack) {
+			const componentStack = `\n\nReact component stack:\n${info.componentStack}`;
+			// Respect the proto's stack limit (32768) — buildCrashMessage already
+			// clamped, but we have new content to add, so re-clamp the combined value.
+			const combined = (msg.stack ? `${msg.stack}\n` : '') + componentStack;
+			msg.stack = combined.length > 32768 ? combined.slice(0, 32768 - 12) + '…[truncated]' : combined;
+		}
+
+		postCrashToHost(msg, this.props.targetOrigin ?? '*');
+
+		try {
+			this.props.onCrash?.(error, info);
+		} catch {
+			// Best-effort: never let the consumer's handler resurface the crash.
+		}
+	}
+
+	render(): ReactNode {
+		if (this.state.crashed) {
+			return this.props.fallback ?? null;
+		}
+		return this.props.children;
+	}
+}