@hoardodile/host-web 0.0.0

package/src/mock/host.ts

@@ -0,0 +1,370 @@
+import type {
+	DanmakuListFilter,
+	PluginAssetDeleteResult,
+	PluginDownloadRequest,
+	PluginDownloadResult,
+} from "@hoardodile/sdk-types"
+import {
+	type HostPush,
+	type HostResponse,
+	hostPushKeys,
+	invalidatePushKeys,
+	type PluginIframeContext,
+	pluginMethods,
+} from "@hoardodile/sdk-web"
+import { requestSchemas } from "../host-core/request-schemas.ts"
+import type { HostBinding } from "../host-core/router.ts"
+import {
+	createHostRouter,
+	defineHandler,
+	type HostHandlerEntry,
+} from "../host-core/router.ts"
+import type { MockFileBackend } from "./file-backends.ts"
+import {
+	createMockDanmakuStore,
+	createMockMessageStore,
+	type MockDanmakuStore,
+	type MockMessageStore,
+} from "./stores.ts"
+
+/**
+ * The offline host side of the plugin postMessage bridge. Implements the
+ * same routing, validation and scoping as the production host (via
+ * host-core) with in-memory data — so plugin iframes run with no server
+ * at all. Shared by automated component tests (jsdom: register the test
+ * window) and the manual workbench page (register the real iframe
+ * window).
+ */
+
+export type MockHostLogger = {
+	readonly info: (message: string, data?: unknown) => void
+	readonly warn: (message: string, data?: unknown) => void
+	readonly error: (message: string, data?: unknown) => void
+}
+
+const defaultLogger: MockHostLogger = {
+	info(message, data) {
+		console.log(`[mock-host] ${message}`, data ?? "")
+	},
+	warn(message, data) {
+		console.warn(`[mock-host] ${message}`, data ?? "")
+	},
+	error(message, data) {
+		console.error(`[mock-host] ${message}`, data ?? "")
+	},
+}
+
+export type MockHostOptions = {
+	/**
+	 * Window that receives plugin postMessage traffic: the page window in
+	 * a workbench, the test window in jsdom. The host listens on it and
+	 * posts responses to it.
+	 */
+	readonly targetWindow: Window
+	readonly files: MockFileBackend
+	readonly messages?: MockMessageStore
+	readonly danmaku?: MockDanmakuStore
+	/** Initial plugin-scoped prefs. */
+	readonly prefs?: Readonly<Record<string, string>>
+	/** Initial plugin+resId cache entries. */
+	readonly cache?: Readonly<Record<string, string>>
+	readonly logger?: MockHostLogger
+	/** Called after a plugin writes a pref. */
+	readonly onPrefChanged?: (key: string, value: string) => void
+	/** Called after a plugin writes a cache entry. */
+	readonly onCacheChanged?: (resId: string, key: string, value: string) => void
+	/**
+	 * Plugin asset vault implementation (workbench only). Absent → the
+	 * asset methods answer `UNAVAILABLE` (tests, jsdom hosts). The real
+	 * app routes these through its server pipeline via tRPC — the mock
+	 * never talks to it.
+	 */
+	readonly assetVault?: PluginAssetVaultMock
+}
+
+/**
+ * The workbench-side plugin asset vault: the mock hands `download` and
+ * `deleteAsset` to the host app's implementation (consent dialog + dev
+ * server fetch + local vault), mirroring the server pipeline's
+ * request/result vocabulary.
+ */
+export type PluginAssetVaultMock = {
+	readonly download: (
+		request: PluginDownloadRequest,
+	) => Promise<PluginDownloadResult>
+	readonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>
+}
+
+export type MockHost = {
+	/**
+	 * Bind a message source to a plugin/resource. The real host binds
+	 * iframe contentWindows; jsdom tests register the test window itself
+	 * (plugin code posts to `window.parent`, which is itself).
+	 */
+	readonly register: (source: unknown, binding: HostBinding) => void
+	readonly unregister: (source: unknown) => void
+	/** Push a host event to one source. */
+	readonly push: (source: unknown, key: string, data?: unknown) => void
+	/** Push the plugin context (the iframe mounts on this). */
+	readonly pushContext: (source: unknown, ctx: PluginIframeContext) => void
+	readonly setVisibility: (source: unknown, visible: boolean) => void
+	readonly messages: MockMessageStore
+	readonly danmaku: MockDanmakuStore
+	readonly prefs: ReadonlyMap<string, string>
+	readonly cache: ReadonlyMap<string, string>
+	readonly dispose: () => void
+}
+
+export function createMockHost(opts: MockHostOptions): MockHost {
+	const targetWindow = opts.targetWindow
+	const logger = opts.logger ?? defaultLogger
+	const messages = opts.messages ?? createMockMessageStore()
+	const danmaku = opts.danmaku ?? createMockDanmakuStore()
+	const prefs = new Map(Object.entries(opts.prefs ?? {}))
+	const cache = new Map(Object.entries(opts.cache ?? {}))
+	const bindings = new Map<unknown, HostBinding>()
+	const subscriptions = new Map<unknown, Set<string>>()
+
+	function postToSource(source: unknown, msg: HostPush | HostResponse): void {
+		;(source as Window).postMessage(msg, "*")
+	}
+
+	function pushToSource(source: unknown, key: string, data?: unknown): void {
+		postToSource(source, { type: "push", key, data })
+	}
+
+	const handlers: readonly HostHandlerEntry[] = [
+		defineHandler(
+			pluginMethods.readFile,
+			requestSchemas[pluginMethods.readFile],
+			async (ctx, params) => {
+				return opts.files.readFile(ctx.resId, params.path, params.range)
+			},
+		),
+
+		defineHandler(pluginMethods.listFiles, async (ctx) => {
+			// Production answers with the rows the plugin's own listFiles
+			// hook produced; a backend that can obtain them serves those.
+			const entries = await opts.files.listFileEntries?.(ctx.resId)
+			if (entries !== undefined) return entries
+			// No hook (or no way to reach it): the server falls back to
+			// bare, naturally sorted filenames — mirror that exactly, or
+			// plugins typed against the fallback shape break here only.
+			const names = [...(await opts.files.listFiles(ctx.resId))]
+			names.sort((a, b) =>
+				a.localeCompare(b, undefined, { sensitivity: "base", numeric: true }),
+			)
+			return names
+		}),
+
+		defineHandler(
+			pluginMethods.logInfo,
+			requestSchemas[pluginMethods.logInfo],
+			(_ctx, params) => {
+				logger.info(logMessage(params), logData(params))
+			},
+		),
+		defineHandler(
+			pluginMethods.logWarn,
+			requestSchemas[pluginMethods.logWarn],
+			(_ctx, params) => {
+				logger.warn(logMessage(params), logData(params))
+			},
+		),
+		defineHandler(
+			pluginMethods.logError,
+			requestSchemas[pluginMethods.logError],
+			(_ctx, params) => {
+				logger.error(logMessage(params), logData(params))
+			},
+		),
+
+		defineHandler(pluginMethods.listMessages, async (ctx) => {
+			return messages.list(ctx.resId)
+		}),
+
+		defineHandler(
+			pluginMethods.createMessage,
+			requestSchemas[pluginMethods.createMessage],
+			async (ctx, params) => {
+				const anchor =
+					params.anchor === undefined
+						? undefined
+						: { ...params.anchor, resId: ctx.resId }
+				return messages.create(ctx.resId, { body: params.body, anchor })
+			},
+		),
+
+		defineHandler(
+			pluginMethods.listDanmaku,
+			requestSchemas[pluginMethods.listDanmaku],
+			async (ctx, params) => {
+				const rows = danmaku.list(ctx.resId)
+				const filter = params.filter
+				if (filter === undefined) return rows
+				return rows.filter((d) => matchesDanmakuFilter(d.anchor.data, filter))
+			},
+		),
+
+		defineHandler(
+			pluginMethods.createDanmaku,
+			requestSchemas[pluginMethods.createDanmaku],
+			async (ctx, params) => {
+				return danmaku.create(ctx.resId, {
+					text: params.text,
+					anchor: { ...params.anchor, resId: ctx.resId },
+					mode: params.mode,
+				})
+			},
+		),
+
+		defineHandler(
+			pluginMethods.setPref,
+			requestSchemas[pluginMethods.setPref],
+			async (_ctx, params) => {
+				prefs.set(params.key, params.value)
+				opts.onPrefChanged?.(params.key, params.value)
+			},
+		),
+
+		defineHandler(
+			pluginMethods.setCache,
+			requestSchemas[pluginMethods.setCache],
+			async (ctx, params) => {
+				// A write from a never-bound iframe has nowhere to land —
+				// drop it silently, same as the production host.
+				if (ctx.resId === "") return
+				cache.set(`${ctx.resId}:${params.key}`, params.value)
+				opts.onCacheChanged?.(ctx.resId, params.key, params.value)
+			},
+		),
+
+		defineHandler(
+			pluginMethods.invalidate,
+			requestSchemas[pluginMethods.invalidate],
+			async (ctx, params) => {
+				// Notify the caller so its query hooks refetch — the mock's
+				// stores are the source of truth, so the refetch returns the
+				// updated data.
+				pushToSource(ctx.source, invalidatePushKeys[params.target])
+			},
+		),
+
+		// Without a wired asset vault the offline host answers
+		// UNAVAILABLE — the exact vocabulary a plugin sees from a generic
+		// mock. The workbench passes `assetVault` to run the real flow
+		// (consent dialog + dev-server download into a local vault).
+		defineHandler(
+			pluginMethods.download,
+			requestSchemas[pluginMethods.download],
+			async (_ctx, params) => {
+				const vault = opts.assetVault
+				if (vault === undefined) throw unavailableAssetError("download")
+				return vault.download(params)
+			},
+		),
+		defineHandler(
+			pluginMethods.deleteAsset,
+			requestSchemas[pluginMethods.deleteAsset],
+			async (_ctx, params) => {
+				const vault = opts.assetVault
+				if (vault === undefined) throw unavailableAssetError("deleteAsset")
+				return vault.deleteAsset(params.path)
+			},
+		),
+	]
+
+	const router = createHostRouter(handlers, {
+		resolveSource(event) {
+			// jsdom delivers same-window messages with source nulled out;
+			// real iframes always carry their contentWindow.
+			const source = event.source === null ? targetWindow : event.source
+			const record = bindings.get(source)
+			if (record === undefined) return undefined
+			return { source, record }
+		},
+		respond(source, response) {
+			postToSource(source, response)
+		},
+		subscribe(source, key) {
+			let keys = subscriptions.get(source)
+			if (keys === undefined) {
+				keys = new Set()
+				subscriptions.set(source, keys)
+			}
+			keys.add(key)
+		},
+	})
+
+	function onMessage(event: MessageEvent): void {
+		router(event)
+	}
+	targetWindow.addEventListener("message", onMessage)
+
+	return {
+		register(source, binding) {
+			bindings.set(source, binding)
+		},
+		unregister(source) {
+			bindings.delete(source)
+			subscriptions.delete(source)
+		},
+		push(source, key, data) {
+			pushToSource(source, key, data)
+		},
+		pushContext(source, ctx) {
+			pushToSource(source, hostPushKeys.context, ctx)
+		},
+		setVisibility(source, visible) {
+			pushToSource(source, hostPushKeys.visibility, { visible })
+		},
+		messages,
+		danmaku,
+		prefs,
+		cache,
+		dispose() {
+			targetWindow.removeEventListener("message", onMessage)
+			bindings.clear()
+			subscriptions.clear()
+		},
+	}
+}
+
+function logMessage(params: unknown): string {
+	const p = params as { message?: unknown } | undefined
+	return typeof p?.message === "string" ? p.message : String(params)
+}
+
+function logData(params: unknown): unknown {
+	const p = params as { data?: unknown } | undefined
+	return p?.data
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+/**
+ * Matches a danmaku against the plugin-declared filter: every declared
+ * field must equal the value stored under the same key in the anchor's
+ * `data` — identical semantics to the production host handler.
+ */
+function matchesDanmakuFilter(
+	data: unknown,
+	filter: DanmakuListFilter,
+): boolean {
+	if (!isRecord(data)) return false
+	for (const [key, value] of Object.entries(filter)) {
+		if (value !== undefined && data[key] !== value) return false
+	}
+	return true
+}
+
+/** Machine-readable asset-error rejection (the shared vocabulary). */
+function unavailableAssetError(method: string): Error {
+	const err = new Error(
+		`${method}() is unavailable in the offline host — plugin asset downloads need the app server runtime`,
+	)
+	err.name = "UNAVAILABLE"
+	return err
+}

package/src/mock/stores.ts

@@ -0,0 +1,89 @@
+import type { Danmaku, Message } from "@hoardodile/sdk-types"
+
+/**
+ * In-memory stores backing the offline mock host's message and danmaku
+ * handlers. Rows are shaped like the server's responses so plugin UI
+ * tests exercise the real consumption paths.
+ */
+
+let nextId = 1
+
+function generateId(prefix: string): string {
+	return `${prefix}-${nextId++}`
+}
+
+export type MockMessageStore = {
+	readonly list: (resId: string) => readonly Message[]
+	readonly create: (
+		resId: string,
+		input: { body: string; anchor?: unknown },
+	) => Message
+}
+
+/**
+ * `seed` pre-fills the store with rows the plugin should already see —
+ * the workbench passes the resource's real comments so the iframe opens
+ * with the same content the app would show.
+ */
+export function createMockMessageStore(
+	seed: readonly Message[] = [],
+): MockMessageStore {
+	const rows: Message[] = [...seed]
+	return {
+		list(resId) {
+			return rows.filter((m) => m.resIds.includes(resId))
+		},
+		create(resId, input) {
+			const message: Message = {
+				id: generateId("msg"),
+				body: input.body,
+				createdAt: Date.now(),
+				charIds: [],
+				resIds: [resId],
+				likeCount: 0,
+				dislikeCount: 0,
+				replyCount: 0,
+				anchor: input.anchor as Message["anchor"],
+			}
+			rows.push(message)
+			return message
+		},
+	}
+}
+
+export type MockDanmakuStore = {
+	readonly list: (resId: string) => readonly Danmaku[]
+	readonly create: (
+		resId: string,
+		input: { text: string; anchor: unknown; mode?: string },
+	) => Danmaku
+}
+
+/** See {@link createMockMessageStore} for `seed`. */
+export function createMockDanmakuStore(
+	seed: readonly Danmaku[] = [],
+): MockDanmakuStore {
+	const rows: Danmaku[] = [...seed]
+	return {
+		list(resId) {
+			return rows.filter((d) => d.anchor.resId === resId)
+		},
+		create(resId, input) {
+			const danmaku: Danmaku = {
+				id: generateId("dm"),
+				anchor: { resId, data: (input.anchor as { data?: unknown }).data },
+				text: input.text,
+				color: "#fff",
+				mode:
+					input.mode === "scroll" ||
+					input.mode === "top" ||
+					input.mode === "bottom"
+						? input.mode
+						: "scroll",
+				createdAt: Date.now(),
+			}
+			rows.push(danmaku)
+			return danmaku
+		},
+	}
+}

package/src/mock-node/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Node-side file backends for the offline mock host: real directories,
+ * read through the host's own containers so mock reads behave exactly
+ * like production reads. Component tests point the mock at a storage
+ * root or a fixture directory with no server involved.
+ */
+import {
+	createDirectoryContainer,
+	createPluginResourceAPI,
+} from "@hoardodile/host"
+import type { MockFileBackend } from "../mock/file-backends.ts"
+
+/**
+ * A mock file backend over a raw directory — a resource folder under a
+ * real storage root (bare files, the production shape) or a plain
+ * fixture directory. Read-only by construction — immutable versioned
+ * partitions make this bypass safe.
+ */
+export function createDirectoryFileBackend(dir: string): MockFileBackend {
+	const api = createPluginResourceAPI({ view: createDirectoryContainer(dir) })
+	return {
+		async listFiles() {
+			return api.listFileNames()
+		},
+		async readFile(_resId, path, range) {
+			const bytes = await api.readFile(path, range)
+			return transferOwned(bytes)
+		},
+		async statFile(_resId, path) {
+			return api.statFile(path)
+		},
+	}
+}
+
+function transferOwned(bytes: Uint8Array): ArrayBuffer {
+	return bytes.slice().buffer
+}