@hoardodile/host-web 0.0.0

package/src/host-core/router.ts

@@ -0,0 +1,234 @@
+import {
+	type HostResponse,
+	type PluginMessage,
+	PROTOCOL_VERSION,
+} from "@hoardodile/sdk-web"
+import type { z } from "zod"
+
+/**
+ * The shared host-side protocol core: message demux, method routing,
+ * per-method param validation, stale-request scoping and the response
+ * envelope. Both the real host (apps/web) and the offline mock host
+ * assemble on this module, so routing and validation never drift.
+ */
+
+/** What a registered iframe (or mock window) is bound to. */
+export type HostBinding = {
+	readonly pluginId: string
+	readonly resId: string
+}
+
+export type HostRouterDeps = {
+	/**
+	 * Authenticate an inbound message event: narrow it to a trusted source
+	 * + binding, or return `undefined` to drop the message. The real host
+	 * validates origin/source against its iframe registry; the mock
+	 * validates against its own registered windows.
+	 */
+	readonly resolveSource: (
+		event: MessageEvent,
+	) => { readonly source: unknown; readonly record: HostBinding } | undefined
+	/** Send a response back to the source (the layer's postMessage exit). */
+	readonly respond: (source: unknown, response: HostResponse) => void
+	/** Record a subscription key for the source. */
+	readonly subscribe: (source: unknown, key: string) => void
+}
+
+export type HostHandlerContext = {
+	readonly source: unknown
+	/**
+	 * The resource this request is scoped to: the source's current
+	 * binding ("" only for never-bound sources). Requests stamped by the
+	 * SDK with a different resource are dropped as stale before they
+	 * reach a handler.
+	 */
+	readonly resId: string
+	readonly pluginId: string
+}
+
+export type HostHandlerEntry = {
+	readonly method: string
+	/** Param schema; validated in the router before the handler runs. */
+	readonly schema: z.ZodTypeAny | undefined
+	readonly handler: (
+		ctx: HostHandlerContext,
+		params: unknown,
+	) => Promise<unknown>
+}
+
+export function defineHandler<TReturn>(
+	method: string,
+	handler: (ctx: HostHandlerContext) => Promise<TReturn> | TReturn,
+): HostHandlerEntry
+
+export function defineHandler<TSchema extends z.ZodTypeAny, TReturn>(
+	method: string,
+	schema: TSchema,
+	handler: (
+		ctx: HostHandlerContext,
+		params: z.infer<TSchema>,
+	) => Promise<TReturn> | TReturn,
+): HostHandlerEntry
+
+export function defineHandler(
+	method: string,
+	schemaOrHandler:
+		| z.ZodTypeAny
+		| ((ctx: HostHandlerContext) => Promise<unknown> | unknown),
+	maybeHandler?: (
+		ctx: HostHandlerContext,
+		params: unknown,
+	) => Promise<unknown> | unknown,
+): HostHandlerEntry {
+	if (typeof schemaOrHandler === "function") {
+		return {
+			method,
+			schema: undefined,
+			handler: async (ctx) => schemaOrHandler(ctx),
+		}
+	}
+	if (maybeHandler === undefined) {
+		throw new Error(`defineHandler("${method}") called without a handler`)
+	}
+	return {
+		method,
+		schema: schemaOrHandler,
+		handler: async (ctx, params) => maybeHandler(ctx, params),
+	}
+}
+
+/**
+ * Create the per-window message handler: authenticates the event,
+ * routes requests by method, validates params, drops stale scopes and
+ * wraps every outcome in the response envelope.
+ */
+export function createHostRouter(
+	handlers: readonly HostHandlerEntry[],
+	deps: HostRouterDeps,
+): (event: MessageEvent) => void {
+	const registry = new Map<string, HostHandlerEntry["handler"]>()
+	const schemas = new Map<string, z.ZodTypeAny>()
+	for (const entry of handlers) {
+		if (registry.has(entry.method)) {
+			throw new Error(`Duplicate handler method: ${entry.method}`)
+		}
+		registry.set(entry.method, entry.handler)
+		if (entry.schema !== undefined) schemas.set(entry.method, entry.schema)
+	}
+
+	// Warn once per source so a mismatched plugin build does not spam the
+	// console on every message, while still surfacing the problem loudly.
+	const warnedSources = new WeakSet<object>()
+
+	return function handleMessage(event: MessageEvent) {
+		const resolved = deps.resolveSource(event)
+		if (resolved === undefined) return
+		const { source, record } = resolved
+
+		const msg = event.data as PluginMessage
+		if (msg == null || typeof msg !== "object" || msg.type === undefined) {
+			return
+		}
+
+		// Protocol handshake: every SDK-build plugin stamps its messages
+		// with the protocol version it was built against. A mismatch (or a
+		// missing stamp — an old plugin build) means the wire contract may
+		// have drifted; the message still routes so old plugins keep
+		// working, but the developer gets a loud warning.
+		const proto = (msg as { proto?: unknown }).proto
+		if (proto !== PROTOCOL_VERSION && !warnedSources.has(source as object)) {
+			warnedSources.add(source as object)
+			if (proto === undefined) {
+				console.warn(
+					`[host-web] plugin iframe (${record.pluginId}) did not stamp its protocol version — it was built against an older SDK. Assuming PROTOCOL_VERSION ${PROTOCOL_VERSION}; rebuild the plugin to silence this warning.`,
+				)
+			} else {
+				console.warn(
+					`[host-web] plugin iframe (${record.pluginId}) speaks protocol version ${String(proto)} but this host speaks ${PROTOCOL_VERSION} — the plugin was built against a different SDK version and may misbehave.`,
+				)
+			}
+		}
+
+		if (msg.type === "subscribe") {
+			deps.subscribe(source, msg.key)
+			return
+		}
+
+		if (msg.type !== "request") return
+
+		function respond(response: HostResponse): void {
+			deps.respond(source, response)
+		}
+
+		// The SDK stamps each request with the resource it was issued for
+		// (PluginRequest.resId). A stamp that no longer matches the
+		// binding marks the request as stale — the tree that issued it is
+		// gone (e.g. an unmount flush racing a rebind) — so it is dropped
+		// silently instead of leaking into the wrong resource. Unstamped
+		// requests (older plugin builds) use the current binding, which
+		// outlives release, so late flushes after a close still land.
+		if (
+			typeof msg.resId === "string" &&
+			msg.resId !== "" &&
+			msg.resId !== record.resId
+		) {
+			respond({ type: "response", id: msg.id, ok: true })
+			return
+		}
+
+		const ctx: HostHandlerContext = {
+			source,
+			resId: record.resId,
+			pluginId: record.pluginId,
+		}
+
+		const handler = registry.get(msg.method)
+		if (handler === undefined) {
+			respond({
+				type: "response",
+				id: msg.id,
+				ok: false,
+				error: `Unknown method: ${msg.method}`,
+			})
+			return
+		}
+
+		let params: unknown
+		const schema = schemas.get(msg.method)
+		if (schema !== undefined) {
+			const parsed = schema.safeParse(msg.params)
+			if (!parsed.success) {
+				respond({
+					type: "response",
+					id: msg.id,
+					ok: false,
+					error: `Invalid params for ${msg.method}: ${parsed.error.message}`,
+				})
+				return
+			}
+			params = parsed.data
+		} else {
+			params = msg.params
+		}
+
+		handler(ctx, params)
+			.then((data) => {
+				respond({ type: "response", id: msg.id, ok: true, data })
+			})
+			.catch((err) => {
+				const errorName =
+					err instanceof Error && err.name !== "Error" ? err.name : undefined
+				respond({
+					type: "response",
+					id: msg.id,
+					ok: false,
+					error: err instanceof Error ? err.message : String(err),
+					// Machine-readable plugin error code (`DENIED`/…)
+					// travels as `errorCode`; `errorName` is the legacy
+					// alias (same value) so older SDK builds keep working.
+					errorCode: errorName,
+					errorName,
+				})
+			})
+	}
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @hoardodile/host-web — the browser-side plugin host runtime:
+ * the shared host-core protocol router (used by apps/web in production
+ * and by the offline mock) plus the mock host for component tests and
+ * the workbench. The wire protocol itself stays in
+ * @hoardodile/sdk-web — this package consumes it, never redefines
+ * it. Node file backends live in `@hoardodile/host-web/node`.
+ */
+
+export {
+	closeDownloadConsent,
+	type DownloadConsentEntry,
+	decideDownloadConsent,
+	enqueueDownloadConsent,
+	getDownloadConsentSnapshot,
+	rehydrateDownloadConsent,
+	requestDownloadConsent,
+	resetDownloadConsent,
+	subscribeDownloadConsent,
+} from "./consent/consent-store.ts"
+export { anchorData, requestSchemas } from "./host-core/request-schemas.ts"
+export {
+	createHostRouter,
+	defineHandler,
+	type HostBinding,
+	type HostHandlerContext,
+	type HostHandlerEntry,
+	type HostRouterDeps,
+} from "./host-core/router.ts"
+export {
+	createInMemoryFileBackend,
+	type MockFileBackend,
+	type ReadFileRange,
+} from "./mock/file-backends.ts"
+export {
+	createMockHost,
+	type MockHost,
+	type MockHostLogger,
+	type MockHostOptions,
+	type PluginAssetVaultMock,
+} from "./mock/host.ts"
+export {
+	createMockDanmakuStore,
+	createMockMessageStore,
+	type MockDanmakuStore,
+	type MockMessageStore,
+} from "./mock/stores.ts"

package/src/mock/file-backends.ts

@@ -0,0 +1,69 @@
+import type { ReadFileRange } from "@hoardodile/sdk-types"
+
+/** Shared read-range contract; defined once in `@hoardodile/sdk-types`. */
+export type { ReadFileRange } from "@hoardodile/sdk-types"
+
+/**
+ * File backends for the offline mock host: the plugin's `listFiles` and
+ * `readFile` requests resolve against this interface, so a mock can be
+ * pointed at an in-memory map, a real directory (Node), or a read-only
+ * HTTP mount (workbench) without changing the host.
+ */
+export type MockFileBackend = {
+	readonly listFiles: (resId: string) => Promise<readonly string[]>
+	readonly readFile: (
+		resId: string,
+		path: string,
+		range?: ReadFileRange,
+	) => Promise<ArrayBuffer>
+	readonly statFile: (
+		resId: string,
+		path: string,
+	) => Promise<{ readonly sizeBytes: number } | undefined>
+	/**
+	 * The rows the plugin's own `listFiles` hook produced, when the
+	 * backend can obtain them (the workbench reads them from a sandboxed
+	 * hook snapshot). In production the host answers `listFiles` with
+	 * exactly these plugin-shaped entries; returning `undefined` falls
+	 * back to generic `{filename, ext, sizeBytes}` rows.
+	 */
+	readonly listFileEntries?: (
+		resId: string,
+	) => Promise<readonly unknown[] | undefined>
+}
+
+/** In-memory file map backend for unit tests. `resId` is ignored. */
+export function createInMemoryFileBackend(
+	files: Readonly<Record<string, string | Uint8Array>> = {},
+): MockFileBackend {
+	return {
+		async listFiles() {
+			return Object.keys(files)
+		},
+		async readFile(_resId, path, range) {
+			const content = files[path]
+			if (content === undefined) {
+				throw new Error(`mock file backend has no entry ${path}`)
+			}
+			const bytes =
+				typeof content === "string"
+					? new TextEncoder().encode(content)
+					: content
+			// Mirrors host semantics: the range is clamped to the content
+			// size; a start at or past the end resolves to an empty result.
+			if (range === undefined) return bytes.slice().buffer
+			const start = Math.max(0, range.start ?? 0)
+			const end = Math.min(range.end ?? bytes.length, bytes.length)
+			return bytes.slice(start, end).buffer
+		},
+		async statFile(_resId, path) {
+			const content = files[path]
+			if (content === undefined) return undefined
+			const bytes =
+				typeof content === "string"
+					? new TextEncoder().encode(content)
+					: content
+			return { sizeBytes: bytes.byteLength }
+		},
+	}
+}

package/src/mock/host.test.ts

@@ -0,0 +1,188 @@
+import type { PluginIframeContext } from "@hoardodile/sdk-web"
+import { createIframeHostAPI, ensureHostBridge } from "@hoardodile/sdk-web"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { createInMemoryFileBackend } from "./file-backends.ts"
+import { createMockHost } from "./host.ts"
+
+/**
+ * Full bridge round-trip in jsdom: the plugin-side runtime posts to
+ * `window.parent` (itself here), the mock host listens on the same
+ * window, and responses come back through the same postMessage channel —
+ * the exact wire a real sandboxed iframe uses.
+ */
+
+function buildContext(
+	overrides: Partial<PluginIframeContext> = {},
+): PluginIframeContext {
+	return {
+		pluginId: "test-plugin",
+		resId: "r-1",
+		resName: "Test Resource",
+		sourceMeta: undefined,
+		searchMeta: undefined,
+		fileStats: undefined,
+		contentPluginId: "test-plugin",
+		language: "en",
+		resolvedTheme: "dark",
+		palette: "parchment",
+		iconStyle: "duotone",
+		fonts: { family: "", cssPaths: [] },
+		initialPrefs: {},
+		initialCache: {},
+		fileToken: "",
+		assetToken: "",
+		...overrides,
+	}
+}
+
+afterEach(() => {
+	// Ensure no global bridge listener leaks between tests.
+	window.parent.postMessage = window.parent.postMessage
+})
+
+describe("createMockHost bridge", () => {
+	test("listFiles and readFile round-trip through postMessage", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: createInMemoryFileBackend({ "a.txt": "hello", "b.bin": "beta" }),
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			// No listFileEntries: the server's own fallback is bare,
+			// naturally sorted filenames.
+			expect(await api.listFiles()).toEqual(["a.txt", "b.bin"])
+			const data = await api.readFile("a.txt")
+			expect(new TextDecoder().decode(data)).toBe("hello")
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("the listFiles fallback sorts naturally, not lexicographically", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: createInMemoryFileBackend({
+				"10.png": "a",
+				"2.png": "b",
+				"1.png": "c",
+			}),
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			expect(await api.listFiles()).toEqual(["1.png", "2.png", "10.png"])
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("listFileEntries serves the plugin's own file rows", async () => {
+		const pluginRows = [
+			{ filename: "01.jpg", type: "image", width: 800, height: 1200 },
+			{ filename: "clip.mp4", type: "video", durationMs: 4200 },
+		]
+		const host = createMockHost({
+			targetWindow: window,
+			files: {
+				...createInMemoryFileBackend({ "01.jpg": "a", "clip.mp4": "b" }),
+				listFileEntries: async () => pluginRows,
+			},
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			expect(await api.listFiles()).toEqual(pluginRows)
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("listFileEntries returning undefined falls back to bare filenames", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: {
+				...createInMemoryFileBackend({ "a.txt": "hello" }),
+				listFileEntries: async () => undefined,
+			},
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			expect(await api.listFiles()).toEqual(["a.txt"])
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("messages round-trip into the in-memory store", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: createInMemoryFileBackend(),
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			const created = await api.createMessage({
+				body: "hello world",
+				anchor: { data: { page: 2 } },
+			})
+			expect(created.body).toBe("hello world")
+			expect((created.anchor as { resId: string }).resId).toBe("r-1")
+
+			const list = await api.listMessages()
+			expect(list).toHaveLength(1)
+			expect(list[0]?.body).toBe("hello world")
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("prefs and cache writes land in the host maps", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: createInMemoryFileBackend(),
+		})
+		host.register(window, { pluginId: "test-plugin", resId: "r-1" })
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			// setPref/setCache are fire-and-forget on the wire — poll for
+			// the request to land in the host maps.
+			api.setPref("theme", "dark")
+			await vi.waitFor(() => expect(host.prefs.get("theme")).toBe("dark"))
+			api.setCache("scroll", "42")
+			await vi.waitFor(() => expect(host.cache.get("r-1:scroll")).toBe("42"))
+		} finally {
+			host.dispose()
+		}
+	})
+
+	test("requests from unregistered sources are dropped", async () => {
+		const host = createMockHost({
+			targetWindow: window,
+			files: createInMemoryFileBackend({ "a.txt": "hello" }),
+		})
+		try {
+			ensureHostBridge()
+			const api = createIframeHostAPI(buildContext())
+
+			// No registration: the request never resolves. The bridge's
+			// request timeout (10s) bounds the wait.
+			await expect(api.listFiles()).rejects.toThrow(/timed out/)
+		} finally {
+			host.dispose()
+		}
+	}, 15_000)
+})