@xeonr/renderer-sdk 1.5.0 → 1.5.2

package/src/react/useRendererClient.ts

@@ -1,250 +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;
-	/**
-	 * Pre-loaded resource snapshot (typically the Upload proto's JSON
-	 * form for upload-scoped renderers). Renderers should cast to the
-	 * expected proto JSON type and use this directly to avoid an extra
-	 * GetUpload round trip on first paint. `null` when the host didn't
-	 * supply one (older hosts, folder/virtual-file scopes); fall back
-	 * to a fetch in that case.
-	 */
-	resource: unknown;
-	/** 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 [resource, setResource] = useState<unknown>(() => client.getResource());
-	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);
-			setResource(payload.resource ?? null);
-			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,
-		resource,
-		path,
-		client,
-		...methods,
-	};
-}

package/src/react/useReportFatalError.tsx

@@ -1,71 +0,0 @@
-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/resources.ts

@@ -1,119 +0,0 @@
-/**
- * Typed resource accessors that read from the host-seeded `resource`
- * cache first and fall back to a real API call when the cache is
- * absent or stale.
- *
- * Lives in its own file so the imports against `@xeonr/uploads-protocol`
- * and `@xeonr/uploads-sdk` are kept out of `client.ts`. Those packages
- * are declared as optional peer dependencies — a renderer that never
- * calls `getUpload()` / `getFolder()` / `getBucket()` doesn't need to
- * install them. The fetch helpers throw at call time when the deps are
- * missing.
- */
-import { fromJson } from '@bufbuild/protobuf';
-import {
-	BucketUploadsService,
-	BucketFoldersService,
-	UploadSchema,
-	FolderSchema,
-	type Upload,
-	type Folder,
-} from '@xeonr/uploads-protocol/uplim/api/v1/uploads_pb';
-import {
-	BucketsService,
-	BucketSchema,
-	type Bucket,
-} from '@xeonr/uploads-protocol/uplim/api/v1/buckets_pb';
-import { getUploadClientWithEnv } from '@xeonr/uploads-sdk/api/base';
-import type { RendererApiAdapter, RendererScope } from './types.js';
-
-/**
- * Best-effort decoder for the host's pre-loaded `resource` field. The
- * host serialises via `toJson(UploadSchema, …)`/etc and posts the JSON
- * across the iframe boundary, so we run it back through `fromJson` to
- * land at a real Message instance with the right prototype methods.
- *
- * Returns null on any failure (schema mismatch, missing fields, etc.)
- * so callers fall through to a fresh fetch.
- */
-export function decodeUploadResource(value: unknown): Upload | null {
-	if (!value || typeof value !== 'object') return null;
-	try {
-		return fromJson(UploadSchema, value as Parameters<typeof fromJson<typeof UploadSchema>>[1]);
-	} catch {
-		return null;
-	}
-}
-
-export function decodeFolderResource(value: unknown): Folder | null {
-	if (!value || typeof value !== 'object') return null;
-	try {
-		return fromJson(FolderSchema, value as Parameters<typeof fromJson<typeof FolderSchema>>[1]);
-	} catch {
-		return null;
-	}
-}
-
-export function decodeBucketResource(value: unknown): Bucket | null {
-	if (!value || typeof value !== 'object') return null;
-	try {
-		return fromJson(BucketSchema, value as Parameters<typeof fromJson<typeof BucketSchema>>[1]);
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Fetch the upload for the current scope via the API. Caller already
- * narrowed the scope; we just translate to the BucketUploadsService
- * RPC. Throws when the API returns no upload (treated as a not-found
- * by the renderer).
- */
-export async function fetchUpload(
-	scope: RendererScope,
-	apiAdapter: RendererApiAdapter,
-): Promise<Upload> {
-	if (scope.type !== 'upload') {
-		throw new Error('fetchUpload requires an upload-typed scope');
-	}
-	const client = getUploadClientWithEnv(BucketUploadsService, apiAdapter);
-	const res = await client.getUpload({
-		bucketRef: { type: { case: 'bucketId', value: scope.bucketId } },
-		uploadRef: { type: { case: 'uploadId', value: scope.uploadId } },
-	});
-	if (!res.upload) throw new Error('Upload not found');
-	return res.upload;
-}
-
-export async function fetchFolder(
-	scope: RendererScope,
-	apiAdapter: RendererApiAdapter,
-): Promise<Folder> {
-	// Folder scopes ('folder' or 'virtual-file' with a folderId) carry
-	// the identifier; everything else is a misuse.
-	let folderId: string | undefined;
-	if (scope.type === 'folder') folderId = scope.folderId;
-	else if (scope.type === 'virtual-file') folderId = scope.folderId;
-	if (!folderId) {
-		throw new Error('fetchFolder requires a folder-typed scope with a folderId');
-	}
-	const client = getUploadClientWithEnv(BucketFoldersService, apiAdapter);
-	const res = await client.getFolder({
-		bucketRef: { type: { case: 'bucketId', value: scope.bucketId } },
-		folderRef: { type: { case: 'folderId', value: folderId } },
-	});
-	if (!res.folder) throw new Error('Folder not found');
-	return res.folder;
-}
-
-export async function fetchBucket(
-	scope: RendererScope,
-	apiAdapter: RendererApiAdapter,
-): Promise<Bucket> {
-	const client = getUploadClientWithEnv(BucketsService, apiAdapter);
-	const res = await client.getBucket({
-		bucketRef: { type: { case: 'bucketId', value: scope.bucketId } },
-	});
-	if (!res.bucket) throw new Error('Bucket not found');
-	return res.bucket;
-}

package/src/types.ts

@@ -1,156 +0,0 @@
-/**
- * config.json schema — lives at the root of a renderer archive.
- * Validated server-side on upload; provided to the renderer in the init message.
- */
-export interface RendererConfig {
-	version: 1;
-	/** Permissions the renderer requests from the host. */
-	permissions?: RendererPermission[];
-	sandbox?: {
-		allowPopups?: boolean;
-		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';
-
-/**
- * What resource the renderer is scoped to.
- * Sent from host to iframe in the init message.
- */
-export type RendererScope =
-	| RendererBucketScope
-	| RendererFolderScope
-	| RendererUploadScope
-	| RendererVirtualFileScope;
-
-export interface RendererBucketScope {
-	type: 'bucket';
-	bucketId: string;
-}
-
-export interface RendererFolderScope {
-	type: 'folder';
-	bucketId: string;
-	folderId: string;
-	path: string;
-}
-
-export interface RendererUploadScope {
-	type: 'upload';
-	bucketId: string;
-	uploadId: string;
-}
-
-export interface RendererVirtualFileScope {
-	type: 'virtual-file';
-	bucketId: string;
-	folderId?: string;
-	path: string;
-}
-
-/**
- * How the renderer is being displayed within the dashboard entrypoint.
- * A single renderer may handle multiple rendering types.
- */
-export type RenderingType =
-	| 'bucket-renderer'
-	| 'folder-renderer'
-	| 'preview-modal';
-
-/**
- * API adapter compatible with `IUploadAdapterEnv` from `@xeonr/uploads-sdk`.
- * Pass this to `getUploadClientWithEnv()` to get a pre-configured API client
- * that handles authentication and token refresh automatically.
- */
-export interface RendererApiAdapter {
-	hostname?: string;
-	tokenHelper?: () => Promise<string | null>;
-	onAuthenticationExpired?: (retryCount: number) => Promise<boolean>;
-	onAuthenticationFailed?: () => Promise<any>;
-}
-
-/** Payload received by the renderer on initialization. */
-export interface InitPayload {
-	/** Protocol version. */
-	version: 1;
-	/** Integration access token scoped to the integration's client. */
-	token: string;
-	/** Unix timestamp (ms) when the token expires. */
-	tokenExpiresAt: number;
-	/** Current host theme. */
-	theme: 'light' | 'dark';
-	/** Which entrypoint was loaded. */
-	entrypoint: 'dashboard' | 'portal';
-	/** What resource the renderer is scoped to. */
-	scope: RendererScope;
-	/** How the renderer is being displayed (dashboard only). */
-	renderingType: RenderingType;
-	/** Base URL for upl.im API calls. */
-	apiBaseUrl: string;
-	/** The parsed config.json from the renderer archive. */
-	config: RendererConfig;
-	/** Initial hash path to navigate to, derived from the host URL fragment. */
-	initialPath?: string;
-	/**
-	 * Pre-loaded resource snapshot the host already had on hand when it
-	 * mounted the iframe — typically the `Upload` proto (in its JSON
-	 * encoding) for upload-scoped renderers, or `Folder` for folder
-	 * scopes. Renderers can consume this directly to avoid an extra
-	 * GetUpload / GetFolder round trip on first paint.
-	 *
-	 * Shape is intentionally loose (`unknown`) because the SDK is
-	 * deliberately decoupled from the @xeonr/uploads-protocol types —
-	 * renderers cast to the proto JSON type (e.g. `UploadJson`) on use.
-	 * Treat as advisory: if absent or stale, fall back to a fresh fetch.
-	 *
-	 * Stays in sync via the existing `resource_url`-style fetches that
-	 * the renderer triggers when the host posts an updated init (e.g.
-	 * after edit / replace flows). For now hosts only populate the
-	 * field for upload-typed scopes; future hosts may extend.
-	 */
-	resource?: unknown;
-}

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "ESNext",
-		"moduleResolution": "bundler",
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"jsx": "react-jsx",
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": true,
-		"forceConsistentCasingInFileNames": true
-	},
-	"include": ["src"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/client.ts","./src/index.ts","./src/protocol.ts","./src/types.ts","./src/react/index.ts","./src/react/userendererclient.ts"],"version":"5.9.3"}