@xeonr/renderer-sdk 1.0.5 → 1.3.0

package/src/react/useRendererClient.ts

@@ -1,10 +1,70 @@
-import { useState, useRef, useEffect, useMemo } from 'react';
+import { useState, useEffect, useMemo } from 'react';
 import { RendererClient } from '../client.js';
 import type { RendererClientOptions } from '../client.js';
 import type { RendererApiAdapter, RendererConfig, RendererScope, RenderingType, InitPayload } from '../types.js';
 
 export interface UseRendererClientOptions extends RendererClientOptions {}
 
+// 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: RendererClient | null = null;
+let sharedClientOptionsKey: string | null = null;
+
+function optionsKey(options: UseRendererClientOptions | undefined): string {
+	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: UseRendererClientOptions | undefined): RendererClient {
+	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 as ImportMeta & { hot?: { dispose: (cb: () => void) => void } }).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:
  *
@@ -54,6 +114,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;
@@ -82,25 +151,23 @@ export interface UseRendererClientResult {
  * ```
  */
 export function useRendererClient(options?: UseRendererClientOptions): UseRendererClientResult {
-	const clientRef = useRef<RendererClient | null>(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<RendererScope | null>(null);
-	const [renderingType, setRenderingType] = useState<RenderingType | null>(null);
-	const [token, setToken] = useState<string | null>(null);
-	const [tokenExpiresAt, setTokenExpiresAt] = useState<number | null>(null);
-	const [theme, setTheme] = useState<'light' | 'dark'>('light');
-	const [config, setConfig] = useState<RendererConfig | null>(null);
-	const [entrypoint, setEntrypoint] = useState<'dashboard' | 'portal' | null>(null);
-	const [apiBaseUrl, setApiBaseUrl] = useState<string | null>(null);
-	const [path, setPath] = useState<string>('/');
+	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<boolean>(() => client.isConnected());
+	const [scope, setScope] = useState<RendererScope | null>(() => client.getScope());
+	const [renderingType, setRenderingType] = useState<RenderingType | null>(() => client.getRenderingType());
+	const [token, setToken] = useState<string | null>(() => client.getToken());
+	const [tokenExpiresAt, setTokenExpiresAt] = useState<number | null>(() => client.getTokenExpiresAt());
+	const [theme, setTheme] = useState<'light' | 'dark'>(() => client.getTheme());
+	const [config, setConfig] = useState<RendererConfig | null>(() => client.getConfig());
+	const [entrypoint, setEntrypoint] = useState<'dashboard' | 'portal' | null>(() => client.getEntrypoint());
+	const [apiBaseUrl, setApiBaseUrl] = useState<string | null>(() => client.getApiBaseUrl());
+	const [path, setPath] = useState<string>(() => client.getPath());
 
 	useEffect(() => {
 		const unsubInit = client.onInit((payload: InitPayload) => {
@@ -136,7 +203,13 @@ export function useRendererClient(options?: UseRendererClientOptions): UseRender
 			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]);
 
@@ -144,6 +217,7 @@ export function useRendererClient(options?: UseRendererClientOptions): UseRender
 		openUpload: (uploadId: string) => client.openUpload(uploadId),
 		requestToken: () => client.requestToken(),
 		close: () => client.close(),
+		markReady: () => client.signalReady(),
 		apiAdapter: client.getApiAdapter(),
 	}), [client]);
 

package/src/react/useReportFatalError.tsx

@@ -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(): (err: unknown) => void {
+	// 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<never>();
+	return useCallback((err: unknown) => {
+		// 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');
+		});
+	}, []);
+}

package/src/types.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 =