@hoardodile/sdk-web 0.0.0

package/src/runtime.ts

@@ -0,0 +1,279 @@
+import type {
+	AnchorData,
+	Danmaku,
+	DanmakuListFilter,
+	DanmakuMode,
+	Message,
+	PluginAssetDeleteResult,
+	PluginDownloadRequest,
+	PluginDownloadResult,
+	PluginSchema,
+} from "@hoardodile/sdk-types"
+import { ensureHostBridge } from "./bridge.ts"
+import type {
+	InvalidateTarget,
+	PluginFonts,
+	PluginIframeContext,
+	ReadFileRange,
+} from "./protocol.ts"
+import {
+	broadcastPrefChange,
+	getPluginCacheStore,
+	getPluginPrefStore,
+	seedPluginStores,
+	setPluginCache,
+	setPluginPref,
+	snapshotCacheEntries,
+} from "./stores.ts"
+import type { FileUrlVariant, WebPluginAPI } from "./types.ts"
+import {
+	buildAssetUrl,
+	buildFileUrl,
+	buildFrameUrl,
+	resolveFilesBaseUrl,
+} from "./urls.ts"
+
+// ── Pure helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Narrow an unknown value to a plain record. Handy for decoding
+ * plugin-defined payloads (e.g. anchor data) without assertion casts.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+/**
+ * Extract `{ resolvedTheme, palette, iconStyle }` from an unknown host
+ * payload. Malformed input yields `undefined` fields rather than throwing —
+ * theme pushes are best-effort.
+ */
+export function extractThemePayload(data: unknown): {
+	resolvedTheme: string | undefined
+	palette: string | undefined
+	iconStyle: string | undefined
+} {
+	if (!isRecord(data)) {
+		return {
+			resolvedTheme: undefined,
+			palette: undefined,
+			iconStyle: undefined,
+		}
+	}
+	return {
+		resolvedTheme:
+			typeof data.resolvedTheme === "string" ? data.resolvedTheme : undefined,
+		palette: typeof data.palette === "string" ? data.palette : undefined,
+		iconStyle: typeof data.iconStyle === "string" ? data.iconStyle : undefined,
+	}
+}
+
+/**
+ * Extract the host app font payload (`family` + stylesheet paths) from
+ * an unknown host push; `undefined` when the shape does not match.
+ */
+export function extractFontsPayload(data: unknown): PluginFonts | undefined {
+	if (!isRecord(data) || typeof data.family !== "string") return undefined
+	const cssPaths = Array.isArray(data.cssPaths)
+		? data.cssPaths.filter((p): p is string => typeof p === "string")
+		: []
+	return { family: data.family, cssPaths }
+}
+
+/**
+ * Extract a `{ key, value }` pref update from an unknown host push;
+ * `undefined` when the shape does not match. `value` may be `undefined`
+ * for a removal.
+ */
+export function extractPrefPayload(
+	data: unknown,
+): { readonly key: string; readonly value: string | undefined } | undefined {
+	if (!isRecord(data)) return undefined
+	const key = data.key
+	if (typeof key !== "string") return undefined
+	return {
+		key,
+		value: typeof data.value === "string" ? data.value : undefined,
+	}
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Builds the full {@link WebPluginAPI} for a plugin running inside a sandboxed
+ * iframe. Communicates with the host via postMessage.
+ */
+export function createIframeHostAPI<
+	TSchema extends PluginSchema = PluginSchema,
+>(ctx: PluginIframeContext): WebPluginAPI<TSchema> {
+	const host = ensureHostBridge().withScope(ctx.resId)
+	seedPluginStores(ctx)
+
+	function logInfo(message: string, data?: Record<string, unknown>): void {
+		host.request("logInfo", { message, data }).catch(() => {})
+	}
+	function logWarn(message: string, data?: Record<string, unknown>): void {
+		host.request("logWarn", { message, data }).catch(() => {})
+	}
+	function logError(message: string, data?: Record<string, unknown>): void {
+		host.request("logError", { message, data }).catch(() => {})
+	}
+
+	function listFiles(): Promise<readonly TSchema["file"][]> {
+		return host.request("listFiles") as Promise<readonly TSchema["file"][]>
+	}
+
+	function readFile(path: string, range?: ReadFileRange): Promise<ArrayBuffer> {
+		return host.request("readFile", { path, range })
+	}
+
+	function resolveFileUrl(filename: string, variant?: FileUrlVariant): string {
+		return buildFileUrl(ctx.resId, filename, ctx.fileToken, variant)
+	}
+
+	function resolveExtractedUrl(path: string): string {
+		return `/api/resources/${ctx.resId}/extracted/${encodeURIComponent(
+			ctx.fileToken,
+		)}/${encodeURIComponent(path)}`
+	}
+
+	function extractProgressUrl(): string {
+		// The trailing slash carries the token segment the auth preHandler
+		// strips (see apps/server/src/infra/http/plugin.ts).
+		return `/api/resources/${ctx.resId}/extract-progress/${encodeURIComponent(
+			ctx.fileToken,
+		)}/`
+	}
+
+	function resolveBaseUrl(): string {
+		return resolveFilesBaseUrl(ctx.resId, ctx.fileToken)
+	}
+
+	function resolveFrameUrl(filename: string, timeMs: number): string {
+		return buildFrameUrl(ctx.resId, filename, timeMs, ctx.fileToken)
+	}
+
+	function listMessages(): Promise<readonly Message[]> {
+		return host.request("listMessages")
+	}
+
+	function createMessage(input: {
+		readonly body: string
+		readonly anchor?: unknown
+	}): Promise<Message> {
+		// The plugin deals in raw location data; the wire anchor is the
+		// `{ data }` envelope (the resource id is host state).
+		return host.request("createMessage", {
+			body: input.body,
+			anchor: input.anchor === undefined ? undefined : { data: input.anchor },
+		})
+	}
+
+	function listDanmaku(
+		filter?: DanmakuListFilter,
+	): Promise<readonly Danmaku[]> {
+		return host.request("listDanmaku", { filter })
+	}
+
+	function createDanmaku(input: {
+		readonly text: string
+		readonly anchor: unknown
+		readonly mode?: DanmakuMode
+	}): Promise<Danmaku> {
+		return host.request("createDanmaku", {
+			text: input.text,
+			anchor: { data: input.anchor },
+			mode: input.mode,
+		})
+	}
+
+	function getPref(key: string): string | undefined {
+		return getPluginPrefStore().get(key) ?? undefined
+	}
+
+	function setPref(key: string, value: string): void {
+		setPluginPref(key, value)
+		broadcastPrefChange(key)
+		host.request("setPref", { key, value }).catch(() => {})
+	}
+
+	function getCache(key: string): string | undefined {
+		return getPluginCacheStore().get(key) ?? undefined
+	}
+
+	function setCache(key: string, value: string): void {
+		setPluginCache(key, value)
+		host.request("setCache", { key, value }).catch(() => {})
+	}
+
+	function listCache(): readonly {
+		readonly key: string
+		readonly value: string
+	}[] {
+		return snapshotCacheEntries()
+	}
+
+	function invalidate(target: InvalidateTarget): Promise<void> {
+		return host.request("invalidate", { target })
+	}
+
+	function download(
+		request: PluginDownloadRequest,
+	): Promise<PluginDownloadResult> {
+		// The protocol table declares the 5-minute ceiling (consent dialog
+		// + transfer) — the bridge reads it; no per-call override here.
+		return host.request("download", request)
+	}
+
+	function resolveAssetUrl(path: string): string {
+		if (ctx.assetToken.length === 0) {
+			throw new Error(
+				'resolveAssetUrl() — the plugin has no asset token: declare "download": true in the manifest and reload the preview',
+			)
+		}
+		return buildAssetUrl(ctx.pluginId, path, ctx.assetToken)
+	}
+
+	function deleteAsset(path: string): Promise<PluginAssetDeleteResult> {
+		return host.request("deleteAsset", { path })
+	}
+
+	function onAnchorJump(cb: (anchor: AnchorData) => void): () => void {
+		return host.subscribe("anchorJump", cb)
+	}
+
+	return {
+		logInfo,
+		logWarn,
+		logError,
+		resource: {
+			id: ctx.resId,
+			name: ctx.resName,
+			sourceMeta: ctx.sourceMeta as TSchema["sourceMeta"],
+			searchMeta: ctx.searchMeta as TSchema["searchMeta"],
+			fileStats: ctx.fileStats,
+			contentPluginId: ctx.contentPluginId,
+		},
+		listFiles,
+		readFile,
+		resolveFileUrl,
+		resolveExtractedUrl,
+		extractProgressUrl,
+		resolveBaseUrl,
+		resolveFrameUrl,
+		download,
+		resolveAssetUrl,
+		deleteAsset,
+		listMessages,
+		createMessage,
+		listDanmaku,
+		createDanmaku,
+		getPref,
+		setPref,
+		getCache,
+		setCache,
+		listCache,
+		invalidate,
+		onAnchorJump,
+	} satisfies WebPluginAPI<TSchema>
+}

package/src/stores.ts

@@ -0,0 +1,103 @@
+import type { PluginIframeContext } from "./protocol.ts"
+
+/**
+ * In-memory module-level stores backing the plugin's pref/cache APIs
+ * (`api.getPref`/`setPref`, `api.getCache`/`setCache`). Seeded from the
+ * iframe context on mount; prefs mirror the host's plugin-wide settings,
+ * cache is per-resource state that the host persists (debounced) and
+ * restores on the next visit.
+ */
+const pluginPrefStore = new Map<string, string>()
+const pluginCacheStore = new Map<string, string>()
+
+/**
+ * Reset both stores and seed them from the iframe context. Called once
+ * by the runtime on mount; must run before any pref/cache access.
+ */
+export function seedPluginStores(ctx: PluginIframeContext): void {
+	pluginPrefStore.clear()
+	for (const [k, v] of Object.entries(ctx.initialPrefs)) {
+		pluginPrefStore.set(k, v)
+	}
+	pluginCacheStore.clear()
+	for (const [k, v] of Object.entries(ctx.initialCache)) {
+		pluginCacheStore.set(k, v)
+	}
+}
+
+/** Read-only view of the plugin's in-memory pref store. */
+export function getPluginPrefStore(): ReadonlyMap<string, string> {
+	return pluginPrefStore
+}
+
+/** Write a pref locally; mirror it to the host immediately. */
+export function setPluginPref(key: string, value: string): void {
+	pluginPrefStore.set(key, value)
+}
+
+/** Read-only view of the plugin's in-memory cache store. */
+export function getPluginCacheStore(): ReadonlyMap<string, string> {
+	return pluginCacheStore
+}
+
+/**
+ * Write a cache entry locally and mirror it to the host for persistence.
+ * Continuously-changing state (scroll positions, resume timestamps)
+ * should go through the debounced `useCacheWriter` in
+ * `@hoardodile/sdk-react` instead of calling this directly on every
+ * change.
+ */
+export function setPluginCache(key: string, value: string): void {
+	pluginCacheStore.set(key, value)
+}
+
+/**
+ * Snapshot of all cache entries, as returned by `api.listCache`. Values
+ * are the raw serialized strings stored via {@link setPluginCache}.
+ */
+export function snapshotCacheEntries(): {
+	readonly key: string
+	readonly value: string
+}[] {
+	const result: { readonly key: string; readonly value: string }[] = []
+	for (const [key, value] of pluginCacheStore) {
+		result.push({ key, value })
+	}
+	return result
+}
+
+// ── Pref change pub/sub ──────────────────────────────────────────────────
+
+const prefChangeListeners = new Map<string, Set<() => void>>()
+
+/**
+ * Subscribe to pref changes for `key` (both local writes and host-pushed
+ * updates). Returns an unsubscribe function. Backs the reactive
+ * `usePref` hook in `@hoardodile/sdk-react`.
+ */
+export function subscribeToPrefChanges(
+	key: string,
+	cb: () => void,
+): () => void {
+	let listeners = prefChangeListeners.get(key)
+	if (listeners === undefined) {
+		listeners = new Set()
+		prefChangeListeners.set(key, listeners)
+	}
+	listeners.add(cb)
+	return function unsubscribe() {
+		listeners!.delete(cb)
+		if (listeners!.size === 0) {
+			prefChangeListeners.delete(key)
+		}
+	}
+}
+
+/** Notify all subscribers of `key` about a value change. */
+export function broadcastPrefChange(key: string): void {
+	const listeners = prefChangeListeners.get(key)
+	if (listeners === undefined) return
+	for (const cb of listeners) {
+		cb()
+	}
+}

package/src/types.ts

@@ -0,0 +1,252 @@
+import type {
+	AnchorData,
+	Danmaku,
+	DanmakuListFilter,
+	DanmakuMode,
+	FileStats,
+	Message,
+	PluginAssetDeleteResult,
+	PluginDownloadRequest,
+	PluginDownloadResult,
+	PluginSchema,
+} from "@hoardodile/sdk-types"
+import type { ImageVariantSpec } from "@hoardodile/sdk-types/image-variant"
+import type {
+	InvalidateTarget,
+	PluginFonts,
+	ReadFileRange,
+} from "./protocol.ts"
+
+/**
+ * What {@link WebPluginAPI.resolveFileUrl} may address: the original
+ * bytes (`"original"`, or omit the argument), the default preview
+ * variant (`"preview"`), or a custom derived image via
+ * {@link ImageVariantSpec}.
+ */
+export type FileUrlVariant = "original" | "preview" | ImageVariantSpec
+
+/**
+ * The current resource as seen by the plugin iframe: id/name plus the
+ * schema-typed metadata (`sourceMeta`, `searchMeta`, `fileStats`) that
+ * the host derived at import time. Injected via the iframe context; the
+ * reactive hooks derive from it, so render code reads the live value
+ * from `usePluginAPI().resource`.
+ */
+export type PluginResource<TSchema extends PluginSchema = PluginSchema> = {
+	readonly id: string
+	readonly name: string
+	readonly sourceMeta: TSchema["sourceMeta"]
+	readonly searchMeta: TSchema["searchMeta"]
+	readonly fileStats: FileStats | undefined
+	readonly contentPluginId: string
+}
+
+/** Encode/decode pair for typed preference values. */
+export type Codec<T> = {
+	readonly encode: (value: T) => string
+	readonly decode: (raw: string) => T | undefined
+}
+
+/** Reactive query state returned by hooks. */
+export type QueryState<T> = {
+	readonly data: T | undefined
+	readonly isLoading: boolean
+	readonly isError: boolean
+	readonly error: Error | null
+}
+
+/** Reactive mutation state returned by hooks. */
+export type MutationState<TInput, TOutput> = {
+	readonly mutate: (input: TInput) => Promise<TOutput>
+	readonly isPending: boolean
+}
+
+/** Current theme as observed by the plugin. */
+export type Theme = {
+	readonly resolvedTheme: string
+	readonly palette: string
+	/** Icon rendering style (`duotone` | `grayscale` | `linear`). */
+	readonly iconStyle: string
+}
+
+/**
+ * Imperative, framework-agnostic API surface injected into plugin render
+ * modules. Reactive hooks (see {@link ReactivePluginAPI}) are provided by
+ * framework adapters — `@hoardodile/sdk-react` composes both into the
+ * full API seen by React plugin components.
+ */
+export type WebPluginAPI<TSchema extends PluginSchema = PluginSchema> = {
+	/** Logging */
+	readonly logInfo: (message: string, data?: Record<string, unknown>) => void
+	readonly logWarn: (message: string, data?: Record<string, unknown>) => void
+	readonly logError: (message: string, data?: Record<string, unknown>) => void
+
+	/** Resource context. */
+	readonly resource: PluginResource<TSchema>
+
+	/** Files. */
+	readonly listFiles: () => Promise<readonly TSchema["file"][]>
+	/**
+	 * Read a file relative to the resource root. Without `range` the whole
+	 * file is returned; large files should be read in bounded chunks via
+	 * the byte range (mirrors the server-side `ResourceAPI.readFile`).
+	 */
+	readonly readFile: (
+		path: string,
+		range?: ReadFileRange,
+	) => Promise<ArrayBuffer>
+	/**
+	 * Resolve a server-rendered URL for a file inside the resource.
+	 * Without `variant` (or with `"original"`) the URL addresses the
+	 * original bytes; `"preview"` selects the default preview variant
+	 * (AVIF, fit inside the standard area cap); pass an
+	 * {@link ImageVariantSpec} to request a custom derived image —
+	 * e.g. `{ format: "webp", fit: "exact" }` transcodes to WebP at the
+	 * source's exact pixel dimensions (no resize), and
+	 * `{ maxArea: 2_000_000 }` caps a downscale. Variant renders are
+	 * cached by the host; pick the `file.preview` flag to gate an
+	 * original/preview toggle.
+	 */
+	readonly resolveFileUrl: (
+		filename: string,
+		variant?: FileUrlVariant,
+	) => string
+	/**
+	 * Resolve the URL of a file materialized by the plugin's
+	 * `extractArchive` hook: an inner entry of an archive (zip/tar)
+	 * served from the host's extraction cache. `path` is the entry's
+	 * relative path inside the archive, exactly as returned by
+	 * `extractArchive` / the `listFiles` hook. Tokenized like
+	 * `resolveFileUrl`.
+	 */
+	readonly resolveExtractedUrl: (path: string) => string
+	/**
+	 * Resolve the URL of the host's in-flight extraction progress for
+	 * this resource (see `extractArchive`). Returns
+	 * `{ done, total }` while materializing, `null` otherwise. Tokenized
+	 * like `resolveFileUrl`; polls are cheap (no-store JSON).
+	 */
+	readonly extractProgressUrl: () => string
+	/**
+	 * Root URL of the current resource's files directory, trailing-slash
+	 * included. For vendor SDKs that internally join relative paths and need
+	 * a base.
+	 */
+	readonly resolveBaseUrl: () => string
+	/**
+	 * Resolve a server-rendered frame thumbnail URL for a video file at the
+	 * given timestamp (in milliseconds, measured from the start of the
+	 * file). The server decodes the requested frame on demand; callers
+	 * should debounce frequent invocations (e.g. while scrubbing) to avoid
+	 * a flood of decode requests.
+	 */
+	readonly resolveFrameUrl: (filename: string, timeMs: number) => string
+
+	/** Plugin asset vault. */
+	/**
+	 * User-consented download into the plugin's own asset vault: when the
+	 * destination already exists the host answers `cached: true` (no
+	 * dialog, no network); otherwise the host asks the user (shared
+	 * consent dialog, URL shown verbatim) and downloads on approval.
+	 * Rejections carry a machine-readable `err.name`
+	 * (`DENIED` / `UNAVAILABLE` / `POLICY`).
+	 */
+	readonly download: (
+		request: PluginDownloadRequest,
+	) => Promise<PluginDownloadResult>
+	/**
+	 * Resolve the tokenized URL of a file in the plugin's own vault
+	 * (`/api/plugin-assets/<pluginId>/<token>/<path>`). Use it to load a
+	 * downloaded runtime or asset from inside the sandboxed iframe, e.g.
+	 * `<script src={api.resolveAssetUrl("runtime/live2d.min.js")} />`
+	 * (served with an exact JS MIME + `nosniff`, so classic scripts,
+	 * module imports and `fetch` all work).
+	 */
+	readonly resolveAssetUrl: (path: string) => string
+	/**
+	 * Remove a vault file (idempotent: an absent file answers
+	 * `{ existed: false }`). The plugin decides the vault's lifecycle —
+	 * no user consent, nothing leaves the host.
+	 */
+	readonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>
+
+	/** Messages. */
+	readonly listMessages: () => Promise<readonly Message[]>
+	readonly createMessage: (input: {
+		readonly body: string
+		/** Raw plugin location data (see {@link PluginSchema.anchor}). */
+		readonly anchor?: TSchema["anchor"]
+	}) => Promise<Message>
+
+	/** Danmaku. */
+	readonly listDanmaku: (
+		filter?: DanmakuListFilter,
+	) => Promise<readonly Danmaku[]>
+	readonly createDanmaku: (input: {
+		readonly text: string
+		/** Raw plugin location data (see {@link PluginSchema.anchor}). */
+		readonly anchor: TSchema["anchor"]
+		readonly mode?: DanmakuMode
+	}) => Promise<Danmaku>
+
+	/** Preferences. */
+	readonly getPref: (key: string) => string | undefined
+	readonly setPref: (key: string, value: string) => void
+
+	/** Cache. */
+	readonly getCache: (key: string) => string | undefined
+	readonly setCache: (key: string, value: string) => void
+	readonly listCache: () => readonly {
+		readonly key: string
+		readonly value: string
+	}[]
+
+	/** Invalidation. */
+	readonly invalidate: (target: InvalidateTarget) => Promise<void>
+
+	/**
+	 * Subscribe to host-initiated anchor jumps (e.g. the user clicked a
+	 * comment anchor in the host UI). The callback receives the raw wire
+	 * envelope ({@link AnchorData}) — decode `anchor.data` yourself, or
+	 * use the typed `useAnchorJump` from `@hoardodile/sdk-react`, which
+	 * decodes at the SDK boundary. Always targets the iframe's own
+	 * resource. Returns an unsubscribe function.
+	 */
+	readonly onAnchorJump: (cb: (anchor: AnchorData) => void) => () => void
+}
+
+/**
+ * Reactive (hook-based) API surface, implemented by framework adapters.
+ * Plain `@hoardodile/sdk-web` consumers get the imperative
+ * {@link WebPluginAPI} only; `@hoardodile/sdk-react` provides these via
+ * `createPluginQueryAPI`.
+ */
+export type ReactivePluginAPI<TSchema extends PluginSchema = PluginSchema> = {
+	readonly useFileList: () => QueryState<readonly TSchema["file"][]>
+	readonly useMessageList: () => QueryState<readonly Message[]>
+	readonly useCreateMessage: () => MutationState<
+		{
+			readonly body: string
+			readonly anchor?: TSchema["anchor"]
+		},
+		Message
+	>
+	readonly useDanmakuList: (
+		filter?: DanmakuListFilter,
+	) => QueryState<readonly Danmaku[]>
+	readonly useCreateDanmaku: () => MutationState<
+		{
+			readonly text: string
+			readonly anchor: TSchema["anchor"]
+			readonly mode?: DanmakuMode
+		},
+		Danmaku
+	>
+	readonly usePref: <T>(
+		key: string,
+		defaultValue: T,
+		codec?: Codec<T>,
+	) => readonly [T, (value: T) => void]
+	readonly useTheme: () => Theme
+	readonly useFont: () => PluginFonts
+}

package/src/urls.ts

@@ -0,0 +1,66 @@
+import { imageVariantQuery } from "@hoardodile/sdk-types/image-variant"
+import type { FileUrlVariant } from "./types.ts"
+
+// ── File URL resolution ──────────────────────────────────────────────────
+// Pure string builders: the iframe's null origin cannot send cookies, so
+// the host embeds a short-lived token in the path (see
+// apps/server/src/infra/http/plugin.ts). Kept side-effect free so the
+// wire shape is unit-testable without the host bridge.
+
+export function resolveFilesBaseUrl(resId: string, token: string): string {
+	return `/api/resources/${resId}/files/${encodeURIComponent(token)}/`
+}
+
+/**
+ * Build the URL for a resource file. Without `variant` (or with
+ * `"original"`) the original bytes are addressed; `"preview"` selects
+ * the default preview variant; an {@link ImageVariantSpec} requests a
+ * custom derived image. Derived URLs always carry `size=preview` (the
+ * compatibility alias) alongside the explicit variant parameters, so a
+ * server that predates the generic contract degrades to its default
+ * preview instead of silently serving the original.
+ */
+export function buildFileUrl(
+	resId: string,
+	filename: string,
+	token: string,
+	variant?: FileUrlVariant,
+): string {
+	const url = `/api/resources/${resId}/files/${encodeURIComponent(token)}/${encodeURIComponent(filename)}`
+	if (variant === "preview") {
+		return `${url}?size=preview`
+	}
+	if (variant !== undefined && variant !== "original") {
+		return `${url}?${imageVariantQuery(variant)}`
+	}
+	return url
+}
+
+/** Build the URL for a video frame thumbnail at `timeMs`. */
+export function buildFrameUrl(
+	resId: string,
+	filename: string,
+	timeMs: number,
+	token: string,
+): string {
+	const time = String(Math.max(0, Math.round(timeMs)))
+	return `/api/resources/${resId}/frame/${encodeURIComponent(token)}/${encodeURIComponent(filename)}/${time}`
+}
+
+/**
+ * Build the URL of a file in the plugin's own asset vault. The host
+ * serves it via the tokenized `/api/plugin-assets/:id/:token/:path`
+ * route (see `apps/server/src/infra/http/plugin-assets.ts`): `token` is
+ * the plugin-scoped asset token from the iframe context — vault files
+ * are host data, so they are served fresh (`no-cache`), never through
+ * the service worker.
+ */
+export function buildAssetUrl(
+	pluginId: string,
+	path: string,
+	token: string,
+): string {
+	return `/api/plugin-assets/${encodeURIComponent(pluginId)}/${encodeURIComponent(
+		token,
+	)}/${encodeURIComponent(path)}`
+}