@xeonr/renderer-sdk 1.0.5 → 1.3.0

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 {
@@ -17,6 +19,16 @@ export interface RendererClientOptions {
 	 * If omitted, all origins are accepted (suitable for local dev).
 	 */
 	targetOrigin?: string;
+
+	/**
+	 * How long after init to wait for `signalReady()` before auto-acking
+	 * anyway, in milliseconds. Only honored when the renderer's
+	 * `config.json` has `deferReady: true`. Default 30000 (30s).
+	 * Matches the host bridge's 10s init-timeout × ~3 — enough headroom
+	 * for slow data fetches without leaving the user staring at a
+	 * loading overlay indefinitely.
+	 */
+	readyTimeoutMs?: number;
 }
 
 type InitCallback = (payload: InitPayload) => void;
@@ -58,10 +70,21 @@ export class RendererClient {
 	private currentConfig: RendererConfig | null = null;
 	private currentTheme: 'light' | 'dark' = 'light';
 	private currentApiBaseUrl: string | null = null;
+	private currentEntrypoint: 'dashboard' | 'portal' | null = null;
 	private currentPath: string = '/';
+	private currentConnected = false;
 
 	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;
+	// `signalReady` machinery — see `deferReady` in RendererClientOptions.
+	// `ackDeferred` is set at construction; `ackSent` flips when we
+	// actually post the ack so signalReady stays idempotent.
+	private ackDeferred = false;
+	private ackSent = false;
+	private readyTimeoutMs = 30_000;
+	private readyTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
 	private readyRetryInterval: ReturnType<typeof setInterval> | null = null;
 	private readyRetryTimeout: ReturnType<typeof setTimeout> | null = null;
 	private historyPatched = false;
@@ -75,6 +98,13 @@ export class RendererClient {
 
 	constructor(options?: RendererClientOptions) {
 		this.targetOrigin = options?.targetOrigin ?? '*';
+		// `ackDeferred` is decided by config.json (read in handleInit)
+		// rather than the constructor — the SDK can't know which mode
+		// the renderer wants until init lands, but that's fine because
+		// the ack itself only fires after init anyway.
+		if (typeof options?.readyTimeoutMs === 'number' && options.readyTimeoutMs > 0) {
+			this.readyTimeoutMs = options.readyTimeoutMs;
+		}
 		this.setup();
 	}
 
@@ -208,6 +238,23 @@ export class RendererClient {
 		return this.currentPath;
 	}
 
+	/** Has the init message been processed? Late subscribers (e.g. a
+	 * second `useRendererClient` mount after init landed) read this to
+	 * seed their initial state without waiting for the next onInit. */
+	isConnected(): boolean {
+		return this.currentConnected;
+	}
+
+	/** Which HTML entrypoint was loaded (dashboard or portal). */
+	getEntrypoint(): 'dashboard' | 'portal' | null {
+		return this.currentEntrypoint;
+	}
+
+	/** Base URL for upl.im API calls, as supplied by the host. */
+	getApiBaseUrl(): string | null {
+		return this.currentApiBaseUrl;
+	}
+
 	/**
 	 * Returns an API adapter compatible with `getUploadClientWithEnv()` from `@xeonr/uploads-sdk`.
 	 * Handles authentication and automatic token refresh via the host bridge.
@@ -246,10 +293,22 @@ export class RendererClient {
 	destroy(): void {
 		this.destroyed = true;
 		this.stopReadyRetry();
+		if (this.readyTimeoutHandle) {
+			clearTimeout(this.readyTimeoutHandle);
+			this.readyTimeoutHandle = null;
+		}
 		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;
@@ -287,6 +346,8 @@ export class RendererClient {
 
 		window.addEventListener('message', this.listener);
 
+		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
@@ -346,6 +407,8 @@ export class RendererClient {
 		this.currentConfig = payload.config;
 		this.currentTheme = payload.theme;
 		this.currentApiBaseUrl = payload.apiBaseUrl;
+		this.currentEntrypoint = payload.entrypoint;
+		this.currentConnected = true;
 
 		// Apply initial path from host URL fragment
 		if (payload.initialPath) {
@@ -364,7 +427,48 @@ export class RendererClient {
 			cb(payload);
 		}
 
-		// Tell the host we've processed init and are ready to be displayed
+		// Ack semantics — driven by the renderer's config.json
+		// (`deferReady` field). Declaring it in config rather than as a
+		// constructor option keeps all renderer metadata in one place
+		// (alongside permissions / sandbox / connectHosts / buildHash)
+		// and avoids a code-vs-config-disagreement footgun.
+		this.ackDeferred = payload.config?.deferReady === true;
+		if (!this.ackDeferred) {
+			this.sendAck();
+		} else {
+			this.readyTimeoutHandle = setTimeout(() => {
+				if (this.destroyed || this.ackSent) return;
+				// Best-effort log so an operator can spot the late ack
+				// in dev tools; production console noise is acceptable
+				// here because this only fires when something is wrong.
+				console.warn(
+					'[uplim] signalReady() not called within ' +
+					this.readyTimeoutMs + 'ms — auto-acking so the host overlay can dismiss.',
+				);
+				this.sendAck();
+			}, this.readyTimeoutMs);
+		}
+	}
+
+	/**
+	 * Post the deferred ack so the host overlay dismisses. No-op once
+	 * the ack has been sent (the host-side bridge tolerates duplicates
+	 * but we suppress them here for cleanliness). When `deferReady` was
+	 * not set on construction this is also a no-op — the SDK already
+	 * acked synchronously on init.
+	 */
+	signalReady(): void {
+		if (this.destroyed || this.ackSent || !this.ackDeferred) return;
+		this.sendAck();
+	}
+
+	private sendAck(): void {
+		if (this.ackSent) return;
+		this.ackSent = true;
+		if (this.readyTimeoutHandle) {
+			clearTimeout(this.readyTimeoutHandle);
+			this.readyTimeoutHandle = null;
+		}
 		this.postToHost({ type: 'uplim:ack' });
 	}
 
@@ -452,4 +556,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;
+	}
+}

package/src/react/dom.ts

@@ -0,0 +1,53 @@
+/**
+ * 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,
+	type Root,
+	type RootOptions,
+	type HydrationOptions,
+} from 'react-dom/client';
+import { createElement, type ReactNode } from 'react';
+import { RendererErrorBoundary } from './RendererErrorBoundary.js';
+
+function wrap(children: ReactNode): ReactNode {
+	return createElement(RendererErrorBoundary, null, children);
+}
+
+export function createRoot(container: Element | DocumentFragment, options?: RootOptions): Root {
+	const root = origCreateRoot(container, options);
+	const originalRender = root.render.bind(root);
+	root.render = (children: ReactNode) => originalRender(wrap(children));
+	return root;
+}
+
+export function hydrateRoot(
+	container: Element | Document,
+	initialChildren: ReactNode,
+	options?: HydrationOptions,
+): Root {
+	const root = origHydrateRoot(container, wrap(initialChildren), options);
+	const originalRender = root.render.bind(root);
+	root.render = (children: ReactNode) => originalRender(wrap(children));
+	return root;
+}
+
+// Re-export every remaining symbol from `react-dom/client` so renderers
+// importing other named bindings (e.g. `Root` type) continue to work
+// after the specifier rewrite.
+export type { Root, RootOptions, HydrationOptions } from 'react-dom/client';

package/src/react/index.ts

@@ -1,2 +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';
+export { useReportFatalError } from './useReportFatalError.js';