@xeonr/renderer-sdk 1.1.0 → 1.5.0

package/src/types.ts

@@ -32,6 +32,25 @@ export interface RendererConfig {
 	 * 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 =
@@ -116,4 +135,22 @@ export interface InitPayload {
 	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;
 }