@zhin.js/client 1.1.4 → 1.1.5

package/client/bootstrap/loadConsoleEntries.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
-import { createPluginRegisterHostApi, getRegisterFn } from "./loadConsoleEntries.js";
+import {
+  createPluginRegisterHostApi,
+  getRegisterFn,
+  resolveEntryRegister,
+} from "./loadConsoleEntries.js";
 
 describe("console entries bootstrap", () => {
   it("resolves named register export", () => {
@@ -16,6 +20,29 @@ describe("console entries bootstrap", () => {
     expect(getRegisterFn({ default: {} })).toBeNull();
   });
 
+  it("synthesizes register from default component + entry.route", () => {
+    const Page = () => null;
+    const register = resolveEntryRegister(
+      { default: Page, meta: { title: "Sandbox", icon: "Box" } },
+      { id: "sandbox", resolvedModule: "/assets/client/sandbox.js", route: "/p-sandbox" } as any,
+    );
+    expect(typeof register).toBe("function");
+    const addRoute = vi.fn();
+    const createElement = vi.fn((c: unknown) => ({ type: c }));
+    register!({
+      React: { createElement } as any,
+      addRoute,
+      addPage: addRoute,
+      addTool: vi.fn(),
+    });
+    expect(addRoute).toHaveBeenCalledWith(expect.objectContaining({
+      path: "/p-sandbox",
+      name: "Sandbox",
+      icon: "Box",
+    }));
+    expect(createElement).toHaveBeenCalledWith(Page);
+  });
+
   it("creates a host API with addPage aliased to addRoute", () => {
     const React = {} as any;
     const addRoute = vi.fn();
@@ -29,4 +56,3 @@ describe("console entries bootstrap", () => {
     expect(api.addTool({ id: "t", name: "T" })).toBe("tool-id");
   });
 });
-

package/client/bootstrap/loadConsoleEntries.ts

@@ -1,10 +1,5 @@
-import type {
-  ConsoleClientEntry,
-  ConsoleEntriesResponse,
-  ConsolePluginRegister,
-  PluginRegisterHostApi,
-} from "@zhin.js/console-types";
-import { DEFAULT_CONSOLE_BASE_PATH } from "@zhin.js/console-types";
+import { DEFAULT_CONSOLE_BASE_PATH, type ConsoleClientEntry, type ConsoleEntriesResponse, type ConsolePluginRegister, type PluginRegisterHostApi } from '@zhin.js/contract';
+import type * as React from 'react';
 
 export type FetchConsoleEntriesOptions = {
   entriesUrl?: string;
@@ -97,6 +92,43 @@ export function getRegisterFn(mod: Record<string, unknown> | null | undefined):
   return null;
 }
 
+/**
+ * Convention pages (ADR 0046) export a React component as `default` + optional `meta`,
+ * without a legacy `register(api)`. Synthesize register from entry.route / entry meta
+ * so Remote Console can still mount them.
+ */
+export function resolveEntryRegister(
+  mod: Record<string, unknown> | null | undefined,
+  entry: ConsoleClientEntry & { readonly route?: string; readonly title?: string },
+): ConsolePluginRegister | null {
+  const named = getRegisterFn(mod);
+  if (named) return named;
+  if (!mod) return null;
+  const Component = mod["default"];
+  if (typeof Component !== "function" && !(Component && typeof Component === "object")) {
+    return null;
+  }
+  const path = typeof entry.route === "string" && entry.route
+    ? entry.route
+    : `/${entry.id}`;
+  const meta = mod["meta"] && typeof mod["meta"] === "object"
+    ? mod["meta"] as { title?: string; icon?: unknown; hideInNav?: boolean }
+    : undefined;
+  const name = (typeof meta?.title === "string" && meta.title)
+    || (typeof entry.title === "string" && entry.title)
+    || entry.meta?.name
+    || entry.id;
+  return (api) => {
+    api.addRoute({
+      path,
+      name,
+      element: api.React.createElement(Component as React.ComponentType),
+      ...(meta?.icon != null ? { icon: meta.icon } : {}),
+      meta: { hideInMenu: meta?.hideInNav === true },
+    });
+  };
+}
+
 export async function registerConsolePluginsFromEntries(
   entries: ConsoleClientEntry[],
   hostApi: PluginRegisterHostApi,
@@ -109,7 +141,7 @@ export async function registerConsolePluginsFromEntries(
       try {
         const specifier = resolvePluginImportUrl(entry.resolvedModule, assetOrigin);
         const mod = (await import(/* @vite-ignore */ specifier)) as Record<string, unknown>;
-        const register = getRegisterFn(mod);
+        const register = resolveEntryRegister(mod, entry);
         if (register) await register(hostApi);
         else throw new Error(`entry "${entry.id}" has no register export`);
       } catch (error) {

package/client/console-events.ts

@@ -0,0 +1,37 @@
+import type {
+  ConsoleEventHistoryPage,
+  ConsoleEventHistoryQuery,
+} from '@zhin.js/console-protocol';
+import { getStoredToken, resolveApiUrl } from './websocket/remote-settings.js';
+
+export interface FetchConsoleEventHistoryOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Read a typed page from the Host's bounded Console event journal. */
+export async function fetchConsoleEventHistory(
+  query: ConsoleEventHistoryQuery = {},
+  options: FetchConsoleEventHistoryOptions = {},
+): Promise<ConsoleEventHistoryPage> {
+  const params = new URLSearchParams();
+  if (query.runtimeId) params.set('runtimeId', query.runtimeId);
+  if (query.after !== undefined) params.set('after', String(query.after));
+  if (query.limit !== undefined) params.set('limit', String(query.limit));
+  const token = getStoredToken();
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const suffix = params.size ? `?${params}` : '';
+  const response = await fetch(resolveApiUrl(`/api/events/history${suffix}`), {
+    headers,
+    signal: options.signal,
+  });
+  const body = await response.json() as {
+    success?: boolean;
+    data?: ConsoleEventHistoryPage;
+    error?: string;
+  };
+  if (!response.ok || body.success !== true || !body.data) {
+    throw new Error(body.error ?? `Console event history failed: HTTP ${response.status}`);
+  }
+  return body.data;
+}

package/client/console-utils/remoteApi.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { apiFetch, consoleRpc, getToken } from "./remoteApi.js";
+
+function mockStorage(map: Record<string, string> = {}): Storage {
+  return {
+    getItem: (key: string) => map[key] ?? null,
+    setItem: (key: string, value: string) => {
+      map[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete map[key];
+    },
+    clear: () => {
+      for (const key of Object.keys(map)) delete map[key];
+    },
+    key: () => null,
+    length: 0,
+  };
+}
+
+function installBrowserGlobals(runtimeToken?: string) {
+  const win = {
+    location: { origin: "http://localhost:5173", protocol: "http:", host: "localhost:5173" },
+    __ZHIN_API_TOKEN: runtimeToken as string | undefined,
+    dispatchEvent: vi.fn(),
+  };
+  vi.stubGlobal("window", win);
+  vi.stubGlobal("localStorage", mockStorage());
+  vi.stubGlobal("sessionStorage", mockStorage());
+  return win;
+}
+
+function fakeResponse(status: number): Response {
+  return { ok: status >= 200 && status < 300, status } as Response;
+}
+
+describe("apiFetch 401 handling", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("invalidates an expired runtime token on 401 so it cannot 401-loop forever", async () => {
+    // 回归：runtime token（Demo 预置）优先级最高，而旧实现 401 只清 local/sessionStorage，
+    // 过期 demo token 会让后续每个请求都 401。
+    const win = installBrowserGlobals("expired-demo-token");
+    vi.stubGlobal("fetch", vi.fn(async () => fakeResponse(401)));
+
+    expect(getToken()).toBe("expired-demo-token");
+    await apiFetch("/api/system/status");
+
+    expect(win.__ZHIN_API_TOKEN).toBeUndefined();
+    expect(getToken()).toBeNull();
+    expect(win.dispatchEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the runtime token when the response is not 401", async () => {
+    const win = installBrowserGlobals("valid-demo-token");
+    vi.stubGlobal("fetch", vi.fn(async () => fakeResponse(200)));
+
+    await apiFetch("/api/system/status");
+
+    expect(win.__ZHIN_API_TOKEN).toBe("valid-demo-token");
+    expect(getToken()).toBe("valid-demo-token");
+    expect(win.dispatchEvent).not.toHaveBeenCalled();
+  });
+
+  it("sends canonical Console RPC envelopes and returns typed data", async () => {
+    installBrowserGlobals("sponsor-token");
+    const fetchMock = vi.fn(async (_url: unknown, init?: RequestInit) => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ success: true, data: { ready: true } }),
+      request: init,
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(consoleRpc<{ ready: boolean }>("workroom.profile.status", {
+      projectId: "alpha",
+    })).resolves.toEqual({ ready: true });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://localhost:5173/api/console/request",
+      expect.objectContaining({ method: "POST" }),
+    );
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    expect(JSON.parse(String(init.body))).toMatchObject({
+      type: "workroom.profile.status", projectId: "alpha",
+    });
+  });
+});

package/client/console-utils/remoteApi.ts

@@ -3,13 +3,23 @@ const API_BASE_KEY = "zhin_api_base";
 
 export function getApiBase(): string {
   const stored = localStorage.getItem(API_BASE_KEY)?.trim();
-  if (stored) return stored.replace(/\/$/, "");
+  if (stored) return trimTrailingSlash(stored);
   if (typeof window !== "undefined") return window.location.origin;
   return "";
 }
 
 export function getToken(): string | null {
-  return localStorage.getItem(TOKEN_KEY);
+  const runtime = getRuntimeToken();
+  if (runtime) return runtime;
+  if (typeof localStorage !== "undefined") {
+    const local = localStorage.getItem(TOKEN_KEY)?.trim();
+    if (local) return local;
+  }
+  if (typeof sessionStorage !== "undefined") {
+    const session = sessionStorage.getItem(TOKEN_KEY)?.trim();
+    if (session) return session;
+  }
+  return null;
 }
 
 export function resolveApiUrl(path: string): string {
@@ -41,8 +51,43 @@ export async function apiFetch(
 
   const res = await fetch(url, { ...init, headers });
   if (res.status === 401) {
+    // runtime token（Demo 预置）过期后也必须失效，否则 getToken() 永远优先命中它，
+    // local/sessionStorage 清理不掉，造成 401 死循环。
+    clearRuntimeToken();
+    sessionStorage.removeItem(TOKEN_KEY);
     localStorage.removeItem(TOKEN_KEY);
     window.dispatchEvent(new CustomEvent("zhin:auth-required"));
   }
   return res;
 }
+
+/** Typed POST adapter for the canonical Plugin Runtime Console RPC endpoint. */
+export async function consoleRpc<T>(
+  type: string,
+  data: Readonly<Record<string, unknown>> = {},
+): Promise<T> {
+  const requestId = Date.now();
+  const res = await apiFetch('/api/console/request', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type, requestId, ...data }),
+  });
+  const body = await res.json() as { success?: boolean; data?: T; error?: string };
+  if (!res.ok || !body.success) throw new Error(body.error ?? `HTTP ${res.status}`);
+  return body.data as T;
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+function getRuntimeToken(): string | null {
+  if (typeof window === "undefined") return null;
+  const token = (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN;
+  return token?.trim() || null;
+}
+
+function clearRuntimeToken(): void {
+  if (typeof window === "undefined") return;
+  delete (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN;
+}

package/client/index.ts

@@ -1,10 +1,70 @@
 // Types
 export * from "./types";
+export {
+  ENDPOINT_RPC,
+  CONSOLE_EVENT_RECOVERY_GAP_EVENT,
+  ENDPOINT_MANAGEMENT_CAPABILITIES,
+  INBOX_RPC,
+  SIDE_EVENT_PUSH,
+  SIDE_EVENT_RPC,
+  normalizeConsolePushMessage,
+  normalizeConsolePushType,
+  parseConsoleInboxEvent,
+  type ConsoleInboxEvent,
+  type ConsoleInboxEventKind,
+  type ConsoleInboxNoticeRow,
+  type ConsoleInboxNoticesQuery,
+  type ConsoleInboxNoticesResult,
+  type ConsoleEndpointPhase,
+  type ConsoleEndpointSummary,
+  type ConsoleEventActor,
+  type ConsoleEventChannel,
+  type EndpointManagementCapability,
+  parseConsoleSseFrame,
+  type ConsoleEventDelivery,
+  type ConsoleEventData,
+  type ConsoleEndpointEventData,
+  type ConsoleEventEnvelope,
+  type ConsoleEventHistoryPage,
+  type ConsoleEventHistoryQuery,
+  type ConsoleEventPayloadMap,
+  type ConsoleMessageEventData,
+  type ConsoleNoticeEventData,
+  type ConsoleRequestEventData,
+  type KnownConsoleEventType,
+  type KnownConsoleEventEnvelope,
+  type ParsedConsoleSseFrame,
+} from "@zhin.js/console-protocol";
+
+export {
+  fetchConsoleEventHistory,
+  type FetchConsoleEventHistoryOptions,
+} from './console-events.js';
 
 // Media URL resolution
 export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from "./mediaSrc";
 
-// Console app singleton (page-manager style)
+// Safe rich message rendering (Markdown + code blocks; no raw HTML execution)
+export {
+  MarkdownContent,
+  CodeBlock,
+  type MarkdownContentProps,
+} from "./message-content/MarkdownContent.js";
+export {
+  parseMarkdown,
+  parseMarkdownInline,
+  highlightCodeLine,
+  isSafeMarkdownHref,
+  type MarkdownBlock,
+  type MarkdownInline,
+  type CodeToken,
+  type CodeTokenKind,
+} from "./message-content/markdown.js";
+
+// Segment IM visibility (inbox vs agent panel)
+export { segmentsForImDelivery, segmentsForAgentPanel } from "./segments.js";
+
+// Console app singleton (pagemanager / registry style)
 export {
   app,
   type ConsoleApp,
@@ -19,24 +79,6 @@ export {
 // WebSocket (business data only)
 export * from "./websocket";
 
-// Re-export console-types
-export type {
-  PluginRegisterHostApi,
-  PluginAddRouteInput,
-  PluginAddToolInput,
-  ConsolePluginRegister,
-  ConsoleClientEntry,
-  ConsoleEntriesResponse,
-  ConsoleEntry,
-  ConsoleFileAddEntryInput,
-  RuntimeEnv,
-} from "@zhin.js/console-types";
-
-export {
-  DEFAULT_CONSOLE_BASE_PATH,
-  CONSOLE_HOST_REACT_NAMESPACE_KEY,
-} from "@zhin.js/console-types";
-
 export { configureConsole, getRuntimeEnv } from "./runtime/index.js";
 
 export {
@@ -61,7 +103,21 @@ export {
   getRegisterFn,
   loadConsoleEntries,
   registerConsolePluginsFromEntries,
+  resolveEntryRegister,
   type CreatePluginRegisterHostApiOptions,
   type FetchConsoleEntriesOptions,
   type LoadConsoleEntriesOptions,
 } from "./bootstrap/loadConsoleEntries.js";
+
+export { registerWorkroomConsole } from "./workroom/registerWorkroomConsole.js";
+export { default as WorkroomRunsPage } from "./workroom/WorkroomRunsPage.js";
+
+export {
+  startAgentSession,
+  continueAgentSession,
+  subscribeAgentStream,
+  iterateAgentStreamNdjson,
+  foldAgentStreamNdjson,
+  type AgentStreamClientOptions,
+  type SubscribeAgentStreamOptions,
+} from "./agent-stream.js";

package/client/mediaSrc.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { pickMediaRawUrl, resolveMediaSrc } from '../client/mediaSrc.js';
+
+describe('pickMediaRawUrl', () => {
+  it('prefers canonical media.value / url / file', () => {
+    expect(pickMediaRawUrl({ media: { value: 'https://a/b.png' } })).toBe('https://a/b.png');
+    expect(pickMediaRawUrl({ url: 'https://a/b.png' })).toBe('https://a/b.png');
+    expect(pickMediaRawUrl({ file: '/tmp/a.png' })).toBe('/tmp/a.png');
+  });
+
+  it('reads agent outbound image segment (base64 + mime, no url)', () => {
+    // media-publisher 出站形态：{ type:'image', data:{ base64, mime, name } }
+    const raw = pickMediaRawUrl({ base64: 'aGVsbG8=', mime: 'image/png', name: 'system-status.png' });
+    expect(raw).toBe('data:image/png;base64,aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'image')).toBe('data:image/png;base64,aGVsbG8=');
+  });
+
+  it('falls back to base64:// so resolveMediaSrc applies the kind default MIME', () => {
+    const raw = pickMediaRawUrl({ base64: 'aGVsbG8=' });
+    expect(raw).toBe('base64://aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'image')).toBe('data:image/png;base64,aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'audio')).toBe('data:audio/mpeg;base64,aGVsbG8=');
+  });
+
+  it('passes through base64 values that already carry a scheme', () => {
+    expect(pickMediaRawUrl({ base64: 'base64://aGVsbG8=' })).toBe('base64://aGVsbG8=');
+    expect(pickMediaRawUrl({ base64: 'data:image/png;base64,aGVsbG8=' })).toBe('data:image/png;base64,aGVsbG8=');
+  });
+
+  it('returns undefined when no media field exists', () => {
+    expect(pickMediaRawUrl(undefined)).toBeUndefined();
+    expect(pickMediaRawUrl({})).toBeUndefined();
+  });
+
+  it('rejects executable data URLs, credentials, and malformed base64', () => {
+    expect(resolveMediaSrc('data:text/html;base64,PHNjcmlwdD4=', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('data:image/svg+xml;base64,PHN2Zz4=', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('https://user:secret@example.com/a.png', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('base64://not:base64', 'image')).toBeUndefined();
+  });
+
+  it('accepts only data MIME types matching the rendered media kind', () => {
+    expect(resolveMediaSrc('data:image/png;base64,aGVsbG8=', 'image')).toBe(
+      'data:image/png;base64,aGVsbG8=',
+    );
+    expect(resolveMediaSrc('data:image/png;base64,aGVsbG8=', 'video')).toBeUndefined();
+    expect(resolveMediaSrc('javascript:alert(1)', 'image')).toBeUndefined();
+  });
+});

package/client/mediaSrc.ts

@@ -3,6 +3,56 @@ export type MediaKind = 'image' | 'video' | 'audio'
 
 const BASE64_PROTO = 'base64://'
 
+const SAFE_DATA_MIME: Readonly<Record<MediaKind, ReadonlySet<string>>> = Object.freeze({
+  image: new Set(['image/avif', 'image/gif', 'image/jpeg', 'image/png', 'image/webp']),
+  video: new Set(['video/mp4', 'video/ogg', 'video/webm']),
+  audio: new Set(['audio/mpeg', 'audio/mp4', 'audio/ogg', 'audio/wav', 'audio/webm']),
+})
+
+function resolveSafeRemoteUrl(value: string): string | undefined {
+  try {
+    const parsed = new URL(value)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:' && parsed.protocol !== 'blob:') {
+      return undefined
+    }
+    if (parsed.username || parsed.password) return undefined
+    return parsed.href
+  } catch {
+    return undefined
+  }
+}
+
+function resolveSafeDataUrl(value: string, kind: MediaKind): string | undefined {
+  if (!value.startsWith('data:')) return undefined
+  const separator = value.indexOf(',')
+  if (separator < 0) return undefined
+  const header = value.slice('data:'.length, separator).toLowerCase()
+  if (!header.endsWith(';base64')) return undefined
+  const mime = header.slice(0, -';base64'.length)
+  if (!SAFE_DATA_MIME[kind].has(mime)) return undefined
+  const payload = compactBase64(value.slice(separator + 1))
+  return payload ? `data:${mime};base64,${payload}` : undefined
+}
+
+function compactBase64(value: string): string | undefined {
+  let compact = ''
+  for (const character of value) {
+    if (character === ' ' || character === '\n' || character === '\r' || character === '\t') continue
+    const code = character.charCodeAt(0)
+    const allowed = (code >= 48 && code <= 57)
+      || (code >= 65 && code <= 90)
+      || (code >= 97 && code <= 122)
+      || character === '+' || character === '/' || character === '='
+    if (!allowed) return undefined
+    compact += character
+  }
+  const padding = compact.indexOf('=')
+  if (padding >= 0 && (compact.length - padding > 2 || compact.slice(padding).replace(/=/g, '') !== '')) {
+    return undefined
+  }
+  return compact || undefined
+}
+
 /**
  * 将消息段中的 url/file 等转为浏览器可用的媒体地址。
  *
@@ -21,31 +71,54 @@ export function resolveMediaSrc(
   const s = raw.trim()
   if (!s) return undefined
 
-  if (s.startsWith('data:') || s.startsWith('blob:') || s.startsWith('http://') || s.startsWith('https://')) {
-    return s
-  }
+  const dataUrl = resolveSafeDataUrl(s, kind)
+  if (dataUrl) return dataUrl
+
+  const remoteUrl = resolveSafeRemoteUrl(s)
+  if (remoteUrl) return remoteUrl
 
   if (!s.startsWith(BASE64_PROTO)) {
-    return s
+    return undefined
   }
 
-  const payload = s.slice(BASE64_PROTO.length).replace(/^\s+/, '')
+  const payload = s.slice(BASE64_PROTO.length).trimStart()
   if (!payload) return undefined
 
   // 已是 type/subtype;base64, 片段（不含 data: 前缀）
-  if (/^[\w+.-]+\/[\w+.-]+;base64,/i.test(payload)) {
-    return `data:${payload}`
+  const declared = resolveSafeDataUrl(`data:${payload}`, kind)
+  if (declared) {
+    return declared
   }
 
   const defaultMime =
     kind === 'image' ? 'image/png' : kind === 'video' ? 'video/mp4' : 'audio/mpeg'
-  const b64 = payload.replace(/\s/g, '')
-  return `data:${defaultMime};base64,${b64}`
+  const b64 = compactBase64(payload)
+  return b64 ? `data:${defaultMime};base64,${b64}` : undefined
 }
 
-/** 从 segment.data 取常见媒体字段 */
+/** 从 segment.data 取常见媒体字段（优先 canonical MediaRef） */
 export function pickMediaRawUrl(data: Record<string, unknown> | undefined): string | undefined {
   if (!data) return undefined
+  const media = data.media
+  if (media && typeof media === 'object' && media !== null) {
+    const value = (media as { value?: unknown }).value
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
   const v = data.url ?? data.file ?? data.src ?? data.href
-  return typeof v === 'string' && v.trim() ? v.trim() : undefined
+  if (typeof v === 'string' && v.trim()) return v.trim()
+  // agent 出站媒体段（media-publisher）直接携带纯 base64，无 url/file；
+  // 有 mime 时拼成 data: URL 透传，否则走 base64:// 让 resolveMediaSrc 按 kind 补默认 MIME
+  const b64 = data.base64
+  if (typeof b64 === 'string' && b64.trim()) {
+    const payload = b64.trim()
+    if (payload.startsWith('data:') || payload.startsWith('base64://')
+      || payload.startsWith('http://') || payload.startsWith('https://')) {
+      return payload
+    }
+    const mime = typeof data.mime === 'string' && data.mime.trim() ? data.mime.trim() : ''
+    return mime
+      ? `data:${mime};base64,${payload.replace(/\s/g, '')}`
+      : `base64://${payload}`
+  }
+  return undefined
 }