@xeonr/renderer-sdk 1.1.0 → 1.5.0

package/src/client.ts

@@ -10,6 +10,20 @@ import type {
 	RendererCrashKind,
 } from './protocol.js';
 import { buildCrashMessage, isHostMessage, postCrashToHost } from './protocol.js';
+import {
+	decodeUploadResource,
+	decodeFolderResource,
+	decodeBucketResource,
+	fetchUpload as apiFetchUpload,
+	fetchFolder as apiFetchFolder,
+	fetchBucket as apiFetchBucket,
+} from './resources.js';
+// Lazy-loaded proto types — kept as type-only imports so they don't
+// pull the runtime modules into the SDK bundle for renderers that
+// never call the typed resource accessors. The actual runtime fetch
+// code lives in `resources.ts`.
+import type { Upload, Folder } from '@xeonr/uploads-protocol/uplim/api/v1/uploads_pb';
+import type { Bucket } from '@xeonr/uploads-protocol/uplim/api/v1/buckets_pb';
 import type { InitPayload, RendererApiAdapter, RendererConfig, RendererScope, RenderingType } from './types.js';
 
 export interface RendererClientOptions {
@@ -19,6 +33,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;
@@ -60,12 +84,30 @@ 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 currentResource: unknown = null;
+	// Typed resource cache. Populated lazily — `currentResource` is the
+	// raw JSON the host sent; these are the decoded Message instances
+	// (with proper prototypes for any methods callers might use). We
+	// keep all three slots so a renderer can call `getBucket()` on an
+	// upload scope without invalidating the upload cache.
+	private cachedUpload: Upload | null = null;
+	private cachedFolder: Folder | null = null;
+	private cachedBucket: Bucket | 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;
@@ -79,6 +121,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();
 	}
 
@@ -212,6 +261,124 @@ 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;
+	}
+
+	/**
+	 * Pre-loaded resource snapshot the host sent in init.
+	 *
+	 * @deprecated Prefer the typed accessors `getUpload()` / `getFolder()`
+	 * / `getBucket()` — they return real Message instances rather than
+	 * untyped JSON and fall back transparently to a fresh fetch when
+	 * the cache is absent. This getter is kept for forward compat with
+	 * renderers building against older SDK versions.
+	 */
+	getResource(): unknown {
+		return this.currentResource;
+	}
+
+	/**
+	 * Return the Upload for the current scope. Returns the host-seeded
+	 * snapshot from init when present (no network call); otherwise
+	 * fetches via BucketUploadsService and caches the result for
+	 * subsequent calls in the same session.
+	 *
+	 * Throws when the scope isn't upload-typed — bucket / folder /
+	 * virtual-file scopes don't have a single Upload to return.
+	 *
+	 * Presigned URLs inside the Upload have ~1h TTL from issuance. For
+	 * long-running renderer sessions, call `refreshUpload()` before
+	 * any operation that needs a definitely-fresh URL.
+	 */
+	async getUpload(): Promise<Upload> {
+		if (this.currentScope?.type !== 'upload') {
+			throw new Error('getUpload() requires an upload-typed scope');
+		}
+		if (this.cachedUpload && this.cachedUpload.uploadId === this.currentScope.uploadId) {
+			return this.cachedUpload;
+		}
+		const upload = await apiFetchUpload(this.currentScope, this.getApiAdapter());
+		this.cachedUpload = upload;
+		return upload;
+	}
+
+	/** Force a fresh fetch of the Upload, bypassing the host-seeded cache. */
+	async refreshUpload(): Promise<Upload> {
+		if (this.currentScope?.type !== 'upload') {
+			throw new Error('refreshUpload() requires an upload-typed scope');
+		}
+		const upload = await apiFetchUpload(this.currentScope, this.getApiAdapter());
+		this.cachedUpload = upload;
+		return upload;
+	}
+
+	/**
+	 * Return the Folder for the current scope. Works for `folder` and
+	 * `virtual-file` scopes (when the virtual file is folder-bound).
+	 */
+	async getFolder(): Promise<Folder> {
+		if (!this.currentScope) {
+			throw new Error('getFolder() called before init');
+		}
+		if (this.cachedFolder) {
+			return this.cachedFolder;
+		}
+		const folder = await apiFetchFolder(this.currentScope, this.getApiAdapter());
+		this.cachedFolder = folder;
+		return folder;
+	}
+
+	/** Force a fresh fetch of the Folder, bypassing the host-seeded cache. */
+	async refreshFolder(): Promise<Folder> {
+		if (!this.currentScope) {
+			throw new Error('refreshFolder() called before init');
+		}
+		const folder = await apiFetchFolder(this.currentScope, this.getApiAdapter());
+		this.cachedFolder = folder;
+		return folder;
+	}
+
+	/**
+	 * Return the Bucket the current scope sits inside. Every scope
+	 * carries a `bucketId`, so this is always callable (subject to init
+	 * having landed).
+	 */
+	async getBucket(): Promise<Bucket> {
+		if (!this.currentScope) {
+			throw new Error('getBucket() called before init');
+		}
+		if (this.cachedBucket && this.cachedBucket.bucketId === this.currentScope.bucketId) {
+			return this.cachedBucket;
+		}
+		const bucket = await apiFetchBucket(this.currentScope, this.getApiAdapter());
+		this.cachedBucket = bucket;
+		return bucket;
+	}
+
+	/** Force a fresh fetch of the Bucket, bypassing the host-seeded cache. */
+	async refreshBucket(): Promise<Bucket> {
+		if (!this.currentScope) {
+			throw new Error('refreshBucket() called before init');
+		}
+		const bucket = await apiFetchBucket(this.currentScope, this.getApiAdapter());
+		this.cachedBucket = bucket;
+		return bucket;
+	}
+
 	/**
 	 * Returns an API adapter compatible with `getUploadClientWithEnv()` from `@xeonr/uploads-sdk`.
 	 * Handles authentication and automatic token refresh via the host bridge.
@@ -250,6 +417,10 @@ 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;
@@ -360,6 +531,30 @@ export class RendererClient {
 		this.currentConfig = payload.config;
 		this.currentTheme = payload.theme;
 		this.currentApiBaseUrl = payload.apiBaseUrl;
+		this.currentEntrypoint = payload.entrypoint;
+		this.currentResource = payload.resource ?? null;
+		// Decode the host-seeded resource into the matching typed slot
+		// based on scope. Decode failures (schema drift, partial host
+		// payload) fall back to `null` and the typed accessors then
+		// fetch from the API on demand.
+		this.cachedUpload = null;
+		this.cachedFolder = null;
+		this.cachedBucket = null;
+		if (payload.resource) {
+			switch (payload.scope.type) {
+				case 'upload':
+					this.cachedUpload = decodeUploadResource(payload.resource);
+					break;
+				case 'folder':
+				case 'virtual-file':
+					this.cachedFolder = decodeFolderResource(payload.resource);
+					break;
+				case 'bucket':
+					this.cachedBucket = decodeBucketResource(payload.resource);
+					break;
+			}
+		}
+		this.currentConnected = true;
 
 		// Apply initial path from host URL fragment
 		if (payload.initialPath) {
@@ -378,7 +573,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' });
 	}
 

package/src/react/index.ts

@@ -2,3 +2,4 @@ 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,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:
  *
@@ -45,6 +105,15 @@ export interface UseRendererClientResult {
 	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;
 
@@ -54,6 +123,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 +160,24 @@ 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 [resource, setResource] = useState<unknown>(() => client.getResource());
+	const [path, setPath] = useState<string>(() => client.getPath());
 
 	useEffect(() => {
 		const unsubInit = client.onInit((payload: InitPayload) => {
@@ -113,6 +190,7 @@ export function useRendererClient(options?: UseRendererClientOptions): UseRender
 			setConfig(payload.config);
 			setEntrypoint(payload.entrypoint);
 			setApiBaseUrl(payload.apiBaseUrl);
+			setResource(payload.resource ?? null);
 			setPath(client.getPath());
 			applyThemeToDocument(payload.theme);
 		});
@@ -136,7 +214,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 +228,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]);
 
@@ -157,6 +242,7 @@ export function useRendererClient(options?: UseRendererClientOptions): UseRender
 		config,
 		entrypoint,
 		apiBaseUrl,
+		resource,
 		path,
 		client,
 		...methods,

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/resources.ts

@@ -0,0 +1,119 @@
+/**
+ * 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;
+}