@xeonr/renderer-sdk 1.5.0 → 1.5.1

package/src/index.ts

@@ -1,47 +0,0 @@
-export { RendererClient } from './client.js';
-export type { RendererClientOptions } from './client.js';
-
-export type {
-	RendererConfig,
-	RendererPermission,
-	RendererScope,
-	RendererBucketScope,
-	RendererFolderScope,
-	RendererUploadScope,
-	RendererVirtualFileScope,
-	RenderingType,
-	InitPayload,
-	RendererApiAdapter,
-} from './types.js';
-
-export {
-	MESSAGE_PREFIX,
-	PROTOCOL_VERSION,
-	isRendererMessage,
-	isHostMessage,
-	isIframeMessage,
-	buildCrashMessage,
-	postCrashToHost,
-} from './protocol.js';
-
-export type {
-	HostMessage,
-	HostInitMessage,
-	HostThemeUpdateMessage,
-	HostTokenRefreshMessage,
-	HostGenerateTokenResultMessage,
-	HostHistoryBackMessage,
-	HostHistoryForwardMessage,
-	IframeMessage,
-	IframeReadyMessage,
-	IframeOpenUploadMessage,
-	IframeTokenRequestMessage,
-	IframeCloseMessage,
-	IframeInitAckMessage,
-	IframeGenerateTokenMessage,
-	IframeHistoryPushMessage,
-	IframeHistoryReplaceMessage,
-	IframeCrashMessage,
-	RendererCrashKind,
-	RendererMessage,
-} from './protocol.js';

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';