@xeonr/renderer-sdk 1.3.0 → 1.5.1

package/src/protocol.ts

@@ -1,286 +0,0 @@
-import type { InitPayload } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Message namespace — all messages use this prefix
-// ---------------------------------------------------------------------------
-export const MESSAGE_PREFIX = 'uplim:' as const;
-export const PROTOCOL_VERSION = 1 as const;
-
-// ---------------------------------------------------------------------------
-// Host → Iframe messages
-// ---------------------------------------------------------------------------
-
-/** Sent after the iframe reports 'ready'. Contains everything the renderer needs to bootstrap. */
-export interface HostInitMessage {
-	type: 'uplim:init';
-	payload: InitPayload;
-}
-
-/** Sent when the host theme changes. */
-export interface HostThemeUpdateMessage {
-	type: 'uplim:theme';
-	theme: 'light' | 'dark';
-}
-
-/** Sent proactively or in response to a token request. */
-export interface HostTokenRefreshMessage {
-	type: 'uplim:token';
-	token: string;
-	tokenExpiresAt: number;
-}
-
-/** Sent in response to a generateToken request from the iframe. */
-export interface HostGenerateTokenResultMessage {
-	type: 'uplim:generateTokenResult';
-	requestId: string;
-	accepted: boolean;
-}
-
-/** Tell the iframe to go back in its history. */
-export interface HostHistoryBackMessage {
-	type: 'uplim:historyBack';
-}
-
-/** Tell the iframe to go forward in its history. */
-export interface HostHistoryForwardMessage {
-	type: 'uplim:historyForward';
-}
-
-export type HostMessage =
-	| HostInitMessage
-	| HostThemeUpdateMessage
-	| HostTokenRefreshMessage
-	| HostGenerateTokenResultMessage
-	| HostHistoryBackMessage
-	| HostHistoryForwardMessage;
-
-// ---------------------------------------------------------------------------
-// Iframe → Host messages
-// ---------------------------------------------------------------------------
-
-/** Iframe is loaded and ready to receive the init message. */
-export interface IframeReadyMessage {
-	type: 'uplim:ready';
-}
-
-/** Request the host to open a specific upload (e.g. in a preview modal). */
-export interface IframeOpenUploadMessage {
-	type: 'uplim:openUpload';
-	uploadId: string;
-}
-
-/** Request a fresh delegated token. Host responds with HostTokenRefreshMessage. */
-export interface IframeTokenRequestMessage {
-	type: 'uplim:tokenRequest';
-}
-
-/** Request the host to close the renderer (relevant for modal mode). */
-export interface IframeCloseMessage {
-	type: 'uplim:close';
-}
-
-/** Acknowledge that init has been processed and the renderer is ready to be displayed. */
-export interface IframeInitAckMessage {
-	type: 'uplim:ack';
-}
-
-/** Request the host to prompt the user to generate a long-lived token. */
-export interface IframeGenerateTokenMessage {
-	type: 'uplim:generateToken';
-	requestId: string;
-	reason: string;
-	duration: 'forever' | string;
-}
-
-/** Notify the host that the renderer navigated to a new hash path. */
-export interface IframeHistoryPushMessage {
-	type: 'uplim:historyPush';
-	path: string;
-}
-
-/** Notify the host that the renderer replaced the current hash path. */
-export interface IframeHistoryReplaceMessage {
-	type: 'uplim:historyReplace';
-	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
-	| IframeTokenRequestMessage
-	| IframeCloseMessage
-	| IframeInitAckMessage
-	| IframeGenerateTokenMessage
-	| IframeHistoryPushMessage
-	| IframeHistoryReplaceMessage
-	| IframeCrashMessage;
-
-// ---------------------------------------------------------------------------
-// Union type for any message
-// ---------------------------------------------------------------------------
-export type RendererMessage = HostMessage | IframeMessage;
-
-// ---------------------------------------------------------------------------
-// Type guard helpers
-// ---------------------------------------------------------------------------
-export function isRendererMessage(data: unknown): data is RendererMessage {
-	return (
-		typeof data === 'object' &&
-		data !== null &&
-		'type' in data &&
-		typeof (data as { type: unknown }).type === 'string' &&
-		(data as { type: string }).type.startsWith(MESSAGE_PREFIX)
-	);
-}
-
-export function isHostMessage(data: unknown): data is HostMessage {
-	if (!isRendererMessage(data)) return false;
-	const t = data.type;
-	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

@@ -1,95 +0,0 @@
-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

@@ -1,53 +0,0 @@
-/**
- * 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,5 +0,0 @@
-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';

package/src/react/useRendererClient.ts

@@ -1,238 +0,0 @@
-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:
- *
- *   - `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: 'light' | 'dark'): void {
-	if (typeof document === 'undefined') return;
-	document.documentElement.dataset.theme = theme;
-	document.documentElement.style.colorScheme = theme;
-}
-
-export interface UseRendererClientResult {
-	/** Whether the host has sent the init message. */
-	connected: boolean;
-	/** What resource the renderer is scoped to. */
-	scope: RendererScope | null;
-	/** How the renderer is being displayed. */
-	renderingType: RenderingType | null;
-	/** The current integration access token. */
-	token: string | null;
-	/** Unix timestamp (ms) when the token expires. */
-	tokenExpiresAt: number | null;
-	/** The current host theme. */
-	theme: 'light' | 'dark';
-	/** The parsed config.json from the renderer archive. */
-	config: RendererConfig | null;
-	/** Which entrypoint was loaded (dashboard or portal). */
-	entrypoint: 'dashboard' | 'portal' | null;
-	/** Base URL for upl.im API calls. */
-	apiBaseUrl: string | null;
-	/** Pre-configured API adapter for use with `getUploadClientWithEnv()`. */
-	apiAdapter: RendererApiAdapter;
-	/** Current hash path within the renderer (e.g. '/settings'). Updated reactively on hash changes. */
-	path: string;
-
-	/** Request the host to open a specific upload. */
-	openUpload: (uploadId: string) => void;
-	/** Request a fresh integration access token. */
-	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;
-}
-
-/**
- * React hook for building custom renderers.
- *
- * Creates a `RendererClient` instance, manages its lifecycle, and exposes
- * reactive state that triggers re-renders when the host sends messages.
- *
- * ```tsx
- * import { useRendererClient } from '@xeonr/renderer-sdk/react';
- *
- * function App() {
- *   const { connected, scope, renderingType, theme, token } = useRendererClient();
- *
- *   if (!connected) return <div>Connecting...</div>;
- *
- *   return (
- *     <div data-theme={theme}>
- *       <pre>{JSON.stringify(scope, null, 2)}</pre>
- *     </div>
- *   );
- * }
- * ```
- */
-export function useRendererClient(options?: UseRendererClientOptions): UseRendererClientResult {
-	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) => {
-			setConnected(true);
-			setScope(payload.scope);
-			setRenderingType(payload.renderingType);
-			setToken(payload.token);
-			setTokenExpiresAt(payload.tokenExpiresAt);
-			setTheme(payload.theme);
-			setConfig(payload.config);
-			setEntrypoint(payload.entrypoint);
-			setApiBaseUrl(payload.apiBaseUrl);
-			setPath(client.getPath());
-			applyThemeToDocument(payload.theme);
-		});
-
-		const unsubTheme = client.onThemeChange((newTheme) => {
-			setTheme(newTheme);
-			applyThemeToDocument(newTheme);
-		});
-
-		const unsubToken = client.onTokenRefresh((newToken, newExpiresAt) => {
-			setToken(newToken);
-			setTokenExpiresAt(newExpiresAt);
-		});
-
-		const unsubNavigate = client.onNavigate((newPath) => {
-			setPath(newPath);
-		});
-
-		return () => {
-			unsubInit();
-			unsubTheme();
-			unsubToken();
-			unsubNavigate();
-			// 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: string) => client.openUpload(uploadId),
-		requestToken: () => client.requestToken(),
-		close: () => client.close(),
-		markReady: () => client.signalReady(),
-		apiAdapter: client.getApiAdapter(),
-	}), [client]);
-
-	return {
-		connected,
-		scope,
-		renderingType,
-		token,
-		tokenExpiresAt,
-		theme,
-		config,
-		entrypoint,
-		apiBaseUrl,
-		path,
-		client,
-		...methods,
-	};
-}