@xeonr/renderer-sdk 1.0.5 → 1.3.0

package/dist/react/RendererErrorBoundary.d.ts

@@ -0,0 +1,60 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+/**
+ * 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 declare class RendererErrorBoundary extends Component<RendererErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};
+//# sourceMappingURL=RendererErrorBoundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RendererErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/react/RendererErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,SAAS,CAAC;IACpB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CACpD;AAED,UAAU,KAAK;IACd,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,qBAAsB,SAAQ,SAAS,CAAC,0BAA0B,EAAE,KAAK,CAAC;IACtF,KAAK,EAAE,KAAK,CAAsB;IAElC,MAAM,CAAC,wBAAwB,IAAI,KAAK;IAIxC,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAyBxD,MAAM,IAAI,SAAS;CAMnB"}

package/dist/react/RendererErrorBoundary.js

@@ -0,0 +1,37 @@
+import { Component } from 'react';
+import { buildCrashMessage, postCrashToHost } from '../protocol.js';
+export class RendererErrorBoundary extends Component {
+    state = { crashed: false };
+    static getDerivedStateFromError() {
+        return { crashed: true };
+    }
+    componentDidCatch(error, info) {
+        // 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() {
+        if (this.state.crashed) {
+            return this.props.fallback ?? null;
+        }
+        return this.props.children;
+    }
+}
+//# sourceMappingURL=RendererErrorBoundary.js.map

package/dist/react/RendererErrorBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RendererErrorBoundary.js","sourceRoot":"","sources":["../../src/react/RendererErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAkC,MAAM,OAAO,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAuDpE,MAAM,OAAO,qBAAsB,SAAQ,SAA4C;IACtF,KAAK,GAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAElC,MAAM,CAAC,wBAAwB;QAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,IAAe;QAChD,wEAAwE;QACxE,0CAA0C;QAC1C,MAAM,GAAG,GAAG,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAE/C,sEAAsE;QACtE,sEAAsE;QACtE,+CAA+C;QAC/C,IAAI,IAAI,EAAE,cAAc,EAAE,CAAC;YAC1B,MAAM,cAAc,GAAG,+BAA+B,IAAI,CAAC,cAAc,EAAE,CAAC;YAC5E,sEAAsE;YACtE,2EAA2E;YAC3E,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC;YACtE,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;QACjG,CAAC;QAED,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,GAAG,CAAC,CAAC;QAErD,IAAI,CAAC;YACJ,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACR,qEAAqE;QACtE,CAAC;IACF,CAAC;IAED,MAAM;QACL,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC5B,CAAC;CACD"}

package/dist/react/dom.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { type Root, type RootOptions, type HydrationOptions } from 'react-dom/client';
+import { type ReactNode } from 'react';
+export declare function createRoot(container: Element | DocumentFragment, options?: RootOptions): Root;
+export declare function hydrateRoot(container: Element | Document, initialChildren: ReactNode, options?: HydrationOptions): Root;
+export type { Root, RootOptions, HydrationOptions } from 'react-dom/client';
+//# sourceMappingURL=dom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/react/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGN,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAOtD,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAK7F;AAED,wBAAgB,WAAW,CAC1B,SAAS,EAAE,OAAO,GAAG,QAAQ,EAC7B,eAAe,EAAE,SAAS,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACxB,IAAI,CAKN;AAKD,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

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,6 @@
 export { useRendererClient } from './useRendererClient.js';
 export type { UseRendererClientOptions, UseRendererClientResult } from './useRendererClient.js';
+export { RendererErrorBoundary } from './RendererErrorBoundary.js';
+export type { RendererErrorBoundaryProps } from './RendererErrorBoundary.js';
+export { useReportFatalError } from './useReportFatalError.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;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/react/index.js

@@ -1,2 +1,4 @@
 export { useRendererClient } from './useRendererClient.js';
+export { RendererErrorBoundary } from './RendererErrorBoundary.js';
+export { useReportFatalError } from './useReportFatalError.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;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/react/useRendererClient.d.ts

@@ -32,6 +32,15 @@ export interface UseRendererClientResult {
     requestToken: () => void;
     /** Request the host to close this renderer (modal mode). */
     close: () => void;
+    /**
+     * When the renderer's `config.json` has `deferReady: true`, call
+     * this once the renderer's data is loaded and the UI is ready to
+     * be visible. The host overlay stays up until this fires (or until
+     * the SDK's safety timeout elapses — see
+     * `RendererClientOptions.readyTimeoutMs`). No-op when `deferReady`
+     * isn't set in config.
+     */
+    markReady: () => void;
     /** The underlying RendererClient instance for advanced use. */
     client: RendererClient;
 }

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;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"}
+{"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;AAiF1E,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;IAClB;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IAEtB,+DAA+D;IAC/D,MAAM,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAqF7F"}

package/dist/react/useRendererClient.js

@@ -1,5 +1,60 @@
-import { useState, useRef, useEffect, useMemo } from 'react';
+import { useState, useEffect, useMemo } from 'react';
 import { RendererClient } from '../client.js';
+// One RendererClient per page. Multiple `useRendererClient()` calls
+// (different components subscribing to the same state) all share the
+// singleton — previously each call spawned its own client, which
+// caused duplicate `window.error` / `unhandledrejection` listeners
+// (so every crash got reported N times), duplicate `uplim:ready`
+// pings, and state divergence between instances.
+//
+// Page lifetime: the iframe is full-reloaded for HMR / test, so the
+// module-level singleton lives exactly as long as it should. SDK-level
+// HMR (developer working on the SDK in monorepo, hot-replacing this
+// module) is handled via `import.meta.hot.dispose` at the bottom of
+// the file.
+let sharedClient = null;
+let sharedClientOptionsKey = null;
+function optionsKey(options) {
+    if (!options)
+        return '';
+    // Stable order so { a, b } and { b, a } produce the same key. Used
+    // only for the dev-mode mismatch warning — never for behavior.
+    const entries = Object.entries(options).sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify(entries);
+}
+function getSharedClient(options) {
+    if (sharedClient) {
+        const key = optionsKey(options);
+        // Best-effort dev nudge: if a later mount passes different
+        // options than the first one, those options are silently
+        // ignored. Only flag when keys differ AND the later caller
+        // passed non-empty options (passing nothing is the common
+        // case for downstream subscribers).
+        if (key && sharedClientOptionsKey !== null && key !== sharedClientOptionsKey) {
+            // eslint-disable-next-line no-console
+            console.warn('[uplim] useRendererClient called with different options after first call; ' +
+                'later options are ignored (the client is a per-page singleton).');
+        }
+        return sharedClient;
+    }
+    sharedClient = new RendererClient(options);
+    sharedClientOptionsKey = optionsKey(options);
+    return sharedClient;
+}
+// SDK-dev HMR cleanup: when this module is hot-replaced (e.g. someone
+// editing the SDK with the renderer harness running), detach the old
+// client's listeners before the new module evaluates. Prod / non-HMR
+// builds skip the entire block — `import.meta.hot` is undefined.
+const maybeHot = import.meta.hot;
+if (maybeHot) {
+    maybeHot.dispose(() => {
+        if (sharedClient) {
+            sharedClient.destroy();
+            sharedClient = null;
+            sharedClientOptionsKey = null;
+        }
+    });
+}
 /**
  * Apply the host's theme to the renderer document. Two distinct effects:
  *
@@ -42,22 +97,22 @@ function applyThemeToDocument(theme) {
  * ```
  */
 export function useRendererClient(options) {
-    const clientRef = useRef(null);
-    // Lazy-init the client (only once)
-    if (clientRef.current === null) {
-        clientRef.current = new RendererClient(options);
-    }
-    const client = clientRef.current;
-    const [connected, setConnected] = useState(false);
-    const [scope, setScope] = useState(null);
-    const [renderingType, setRenderingType] = useState(null);
-    const [token, setToken] = useState(null);
-    const [tokenExpiresAt, setTokenExpiresAt] = useState(null);
-    const [theme, setTheme] = useState('light');
-    const [config, setConfig] = useState(null);
-    const [entrypoint, setEntrypoint] = useState(null);
-    const [apiBaseUrl, setApiBaseUrl] = useState(null);
-    const [path, setPath] = useState('/');
+    const client = getSharedClient(options);
+    // Initial state read directly from the client — handles late
+    // subscribers (a second `useRendererClient` mount that happens
+    // after init has already fired). Without this, the late mount
+    // would sit at `connected: false` forever because onInit only
+    // fires for NEW init events, not for already-received state.
+    const [connected, setConnected] = useState(() => client.isConnected());
+    const [scope, setScope] = useState(() => client.getScope());
+    const [renderingType, setRenderingType] = useState(() => client.getRenderingType());
+    const [token, setToken] = useState(() => client.getToken());
+    const [tokenExpiresAt, setTokenExpiresAt] = useState(() => client.getTokenExpiresAt());
+    const [theme, setTheme] = useState(() => client.getTheme());
+    const [config, setConfig] = useState(() => client.getConfig());
+    const [entrypoint, setEntrypoint] = useState(() => client.getEntrypoint());
+    const [apiBaseUrl, setApiBaseUrl] = useState(() => client.getApiBaseUrl());
+    const [path, setPath] = useState(() => client.getPath());
     useEffect(() => {
         const unsubInit = client.onInit((payload) => {
             setConnected(true);
@@ -88,13 +143,20 @@ export function useRendererClient(options) {
             unsubTheme();
             unsubToken();
             unsubNavigate();
-            client.destroy();
+            // NB: do NOT destroy() here — the client is a per-page
+            // singleton, not a per-component instance. Component
+            // unmounts (route changes / strict-mode double-mount /
+            // React render-time tearing) shouldn't kill the shared
+            // state. The iframe full-reload tears the singleton down
+            // implicitly when the page goes away; SDK-level HMR is
+            // handled by import.meta.hot.dispose at the top of file.
         };
     }, [client]);
     const methods = useMemo(() => ({
         openUpload: (uploadId) => client.openUpload(uploadId),
         requestToken: () => client.requestToken(),
         close: () => client.close(),
+        markReady: () => client.signalReady(),
         apiAdapter: client.getApiAdapter(),
     }), [client]);
     return {

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/react/useReportFatalError.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook for surfacing async failures to `<RendererErrorBoundary>` (and from
+ * there to the host's crash overlay + telemetry).
+ *
+ * Renderers shouldn't render their own "Upload not found" / "Failed to
+ * load" inline UI — those are still crashes from a telemetry standpoint,
+ * and the host already owns a polished overlay with reload + fallback
+ * actions. This hook lets a renderer take an error caught in an async
+ * context (fetch `.catch()`, useEffect cleanup, etc.) and route it to
+ * the host instead of rendering a half-broken inline state.
+ *
+ * Pattern:
+ *
+ * ```tsx
+ * const reportFatal = useReportFatalError();
+ * useEffect(() => {
+ *   client.getUpload(...).catch(reportFatal);
+ * }, []);
+ * ```
+ *
+ * Mechanics: we keep an error in component state. When set, the *next*
+ * render throws it — React's error-handling pipeline catches the throw
+ * and bubbles to the nearest boundary. From there
+ * `RendererErrorBoundary.componentDidCatch` reports the crash to the
+ * host and renders nothing, and the host overlay (Reload / Copy /
+ * Fallback) takes over the visible iframe area.
+ *
+ * Why state-then-throw rather than a direct `throw err`? You can't
+ * throw to React from async code — React only sees throws that happen
+ * during render or in event handlers. Routing through state ensures
+ * the throw lands inside the render phase.
+ *
+ * The returned callback is stable across renders so it's safe to drop
+ * straight into a `.catch()`.
+ */
+export declare function useReportFatalError(): (err: unknown) => void;
+//# sourceMappingURL=useReportFatalError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useReportFatalError.d.ts","sourceRoot":"","sources":["../../src/react/useReportFatalError.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,mBAAmB,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAiC5D"}

package/dist/react/useReportFatalError.js

@@ -0,0 +1,71 @@
+import { useCallback, useState } from 'react';
+/**
+ * Hook for surfacing async failures to `<RendererErrorBoundary>` (and from
+ * there to the host's crash overlay + telemetry).
+ *
+ * Renderers shouldn't render their own "Upload not found" / "Failed to
+ * load" inline UI — those are still crashes from a telemetry standpoint,
+ * and the host already owns a polished overlay with reload + fallback
+ * actions. This hook lets a renderer take an error caught in an async
+ * context (fetch `.catch()`, useEffect cleanup, etc.) and route it to
+ * the host instead of rendering a half-broken inline state.
+ *
+ * Pattern:
+ *
+ * ```tsx
+ * const reportFatal = useReportFatalError();
+ * useEffect(() => {
+ *   client.getUpload(...).catch(reportFatal);
+ * }, []);
+ * ```
+ *
+ * Mechanics: we keep an error in component state. When set, the *next*
+ * render throws it — React's error-handling pipeline catches the throw
+ * and bubbles to the nearest boundary. From there
+ * `RendererErrorBoundary.componentDidCatch` reports the crash to the
+ * host and renders nothing, and the host overlay (Reload / Copy /
+ * Fallback) takes over the visible iframe area.
+ *
+ * Why state-then-throw rather than a direct `throw err`? You can't
+ * throw to React from async code — React only sees throws that happen
+ * during render or in event handlers. Routing through state ensures
+ * the throw lands inside the render phase.
+ *
+ * The returned callback is stable across renders so it's safe to drop
+ * straight into a `.catch()`.
+ */
+export function useReportFatalError() {
+    // Generic state slot — we never read the value, only use the
+    // updater. We narrow to `never` so TypeScript stops us from
+    // accidentally using it as data anywhere.
+    const [, setState] = useState();
+    return useCallback((err) => {
+        // Functional updater throws — React invokes it during the next
+        // render attempt, which puts the throw inside the render phase
+        // where boundaries can see it.
+        setState(() => {
+            if (err instanceof Error) {
+                throw err;
+            }
+            // Wrap non-Error throws so the boundary always sees a real
+            // Error instance with a meaningful .name / .message. Without
+            // this, `client.reportCrash` would synthesise a generic
+            // 'UnknownError' which loses the original payload's shape.
+            if (typeof err === 'string') {
+                throw new Error(err);
+            }
+            if (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string') {
+                const wrapped = new Error(err.message);
+                if ('name' in err && typeof err.name === 'string') {
+                    wrapped.name = err.name;
+                }
+                if ('stack' in err && typeof err.stack === 'string') {
+                    wrapped.stack = err.stack;
+                }
+                throw wrapped;
+            }
+            throw new Error('Unknown renderer error');
+        });
+    }, []);
+}
+//# sourceMappingURL=useReportFatalError.js.map

package/dist/react/useReportFatalError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReportFatalError.js","sourceRoot":"","sources":["../../src/react/useReportFatalError.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,mBAAmB;IAClC,6DAA6D;IAC7D,4DAA4D;IAC5D,0CAA0C;IAC1C,MAAM,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ,EAAS,CAAC;IACvC,OAAO,WAAW,CAAC,CAAC,GAAY,EAAE,EAAE;QACnC,+DAA+D;QAC/D,+DAA+D;QAC/D,+BAA+B;QAC/B,QAAQ,CAAC,GAAG,EAAE;YACb,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;gBAC1B,MAAM,GAAG,CAAC;YACX,CAAC;YACD,2DAA2D;YAC3D,6DAA6D;YAC7D,wDAAwD;YACxD,2DAA2D;YAC3D,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;YACD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC3F,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACvC,IAAI,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACnD,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;gBACzB,CAAC;gBACD,IAAI,OAAO,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBACrD,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;gBAC3B,CAAC;gBACD,MAAM,OAAO,CAAC;YACf,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;AACR,CAAC"}

package/dist/types.d.ts

@@ -11,6 +11,46 @@ 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;
+    /**
+     * When true, the SDK holds `uplim:ack` until the renderer explicitly
+     * calls `markReady()` from `useRendererClient()`. The host's loading
+     * overlay stays visible until that signal arrives, so the user
+     * never sees a blank canvas between bridge ack and the renderer's
+     * first paint.
+     *
+     * Leave unset (or `false`) for fast renderers where the gap is
+     * invisible — that's the right default and lowest-friction pattern
+     * (image, code, plain markdown). Set `true` when the renderer takes
+     * perceptible time to settle (large file fetch, video decode,
+     * multi-page paginate) and the blank-canvas flash is noticeable.
+     *
+     * The SDK auto-acks after 30s (configurable via
+     * `RendererClientOptions.readyTimeoutMs`) and logs a warning if
+     * `markReady()` never fires — so a forgotten signal can't trap
+     * users behind the overlay.
+     */
+    deferReady?: boolean;
 }
 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;IACnB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;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.5",
+  "version": "1.3.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": {