@hoardodile/host-web 0.0.0

package/dist/node.js

@@ -0,0 +1,25 @@
+import { createPluginResourceAPI, createDirectoryContainer } from '@hoardodile/host';
+
+// src/mock-node/index.ts
+function createDirectoryFileBackend(dir) {
+  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) {
+  return bytes.slice().buffer;
+}
+
+export { createDirectoryFileBackend };
+//# sourceMappingURL=node.js.map
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mock-node/index.ts"],"names":[],"mappings":";;;AAkBO,SAAS,2BAA2B,GAAA,EAA8B;AACxE,EAAA,MAAM,MAAM,uBAAA,CAAwB,EAAE,MAAM,wBAAA,CAAyB,GAAG,GAAG,CAAA;AAC3E,EAAA,OAAO;AAAA,IACN,MAAM,SAAA,GAAY;AACjB,MAAA,OAAO,IAAI,aAAA,EAAc;AAAA,IAC1B,CAAA;AAAA,IACA,MAAM,QAAA,CAAS,MAAA,EAAQ,IAAA,EAAM,KAAA,EAAO;AACnC,MAAA,MAAM,KAAA,GAAQ,MAAM,GAAA,CAAI,QAAA,CAAS,MAAM,KAAK,CAAA;AAC5C,MAAA,OAAO,cAAc,KAAK,CAAA;AAAA,IAC3B,CAAA;AAAA,IACA,MAAM,QAAA,CAAS,MAAA,EAAQ,IAAA,EAAM;AAC5B,MAAA,OAAO,GAAA,CAAI,SAAS,IAAI,CAAA;AAAA,IACzB;AAAA,GACD;AACD;AAEA,SAAS,cAAc,KAAA,EAAgC;AACtD,EAAA,OAAO,KAAA,CAAM,OAAM,CAAE,MAAA;AACtB","file":"node.js","sourcesContent":["/**\n * Node-side file backends for the offline mock host: real directories,\n * read through the host's own containers so mock reads behave exactly\n * like production reads. Component tests point the mock at a storage\n * root or a fixture directory with no server involved.\n */\nimport {\n\tcreateDirectoryContainer,\n\tcreatePluginResourceAPI,\n} from \"@hoardodile/host\"\nimport type { MockFileBackend } from \"../mock/file-backends.ts\"\n\n/**\n * A mock file backend over a raw directory — a resource folder under a\n * real storage root (bare files, the production shape) or a plain\n * fixture directory. Read-only by construction — immutable versioned\n * partitions make this bypass safe.\n */\nexport function createDirectoryFileBackend(dir: string): MockFileBackend {\n\tconst api = createPluginResourceAPI({ view: createDirectoryContainer(dir) })\n\treturn {\n\t\tasync listFiles() {\n\t\t\treturn api.listFileNames()\n\t\t},\n\t\tasync readFile(_resId, path, range) {\n\t\t\tconst bytes = await api.readFile(path, range)\n\t\t\treturn transferOwned(bytes)\n\t\t},\n\t\tasync statFile(_resId, path) {\n\t\t\treturn api.statFile(path)\n\t\t},\n\t}\n}\n\nfunction transferOwned(bytes: Uint8Array): ArrayBuffer {\n\treturn bytes.slice().buffer\n}\n"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@hoardodile/host-web",
+  "version": "0.0.0",
+  "license": "MIT",
+  "description": "Browser-side hoardodile host runtime: host-core protocol router and the offline mock host.",
+  "keywords": [
+    "hoardodile",
+    "plugin",
+    "host",
+    "browser",
+    "mock"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoardodile/hoardodile.git",
+    "directory": "plugins/host-web"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "development": "./src/node.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@hoardodile/host": "0.0.0",
+    "@hoardodile/sdk-types": "0.0.0",
+    "@hoardodile/sdk-web": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "jsdom": "^30.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/consent/consent-store.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it } from "vitest"
+import {
+	closeDownloadConsent,
+	type DownloadConsentEntry,
+	decideDownloadConsent,
+	enqueueDownloadConsent,
+	getDownloadConsentSnapshot,
+	rehydrateDownloadConsent,
+	requestDownloadConsent,
+	resetDownloadConsent,
+	subscribeDownloadConsent,
+} from "./consent-store"
+
+function ticket(ticketId: string, dest = "runtime.mjs"): DownloadConsentEntry {
+	return {
+		ticketId,
+		pluginId: "p-1",
+		pluginName: "Test",
+		url: "https://example.com/runtime.mjs",
+		dest,
+	}
+}
+
+describe("download consent store", () => {
+	beforeEach(() => {
+		resetDownloadConsent()
+	})
+
+	it("queues tickets FIFO and dedupes by id", () => {
+		enqueueDownloadConsent(ticket("a1"))
+		enqueueDownloadConsent(ticket("a2"))
+		enqueueDownloadConsent(ticket("a1"))
+		const { queue } = getDownloadConsentSnapshot()
+		expect(queue.map((t) => t.ticketId)).toEqual(["a1", "a2"])
+	})
+
+	it("closes a ticket by id and notifies subscribers", () => {
+		let notified = 0
+		const unsubscribe = subscribeDownloadConsent(() => {
+			notified += 1
+		})
+		try {
+			enqueueDownloadConsent(ticket("b1"))
+			enqueueDownloadConsent(ticket("b2"))
+			closeDownloadConsent("b1")
+			expect(getDownloadConsentSnapshot().queue.map((t) => t.ticketId)).toEqual(
+				["b2"],
+			)
+			expect(notified).toBe(3)
+		} finally {
+			unsubscribe()
+		}
+	})
+
+	it("rehydrates the whole queue (SSE reconnect / engine restart)", () => {
+		enqueueDownloadConsent(ticket("c1"))
+		rehydrateDownloadConsent([ticket("c3", "b.mjs"), ticket("c4", "c.mjs")])
+		expect(getDownloadConsentSnapshot().queue.map((t) => t.ticketId)).toEqual([
+			"c3",
+			"c4",
+		])
+	})
+
+	it("unsubscribe stops notifications", () => {
+		let notified = 0
+		const unsubscribe = subscribeDownloadConsent(() => {
+			notified += 1
+		})
+		unsubscribe()
+		enqueueDownloadConsent(ticket("d1"))
+		expect(notified).toBe(0)
+	})
+
+	it("request enqueues and waits; decide resolves and closes (engine path)", async () => {
+		const consent = requestDownloadConsent(ticket("e1"))
+		expect(getDownloadConsentSnapshot().queue).toHaveLength(1)
+		decideDownloadConsent("e1", true)
+		await expect(consent).resolves.toBe(true)
+		expect(getDownloadConsentSnapshot().queue).toHaveLength(0)
+	})
+
+	it("denied decision resolves false and closes; unknown ids are no-ops", async () => {
+		const consent = requestDownloadConsent(ticket("f1"))
+		decideDownloadConsent("unknown", true)
+		decideDownloadConsent("f1", false)
+		await expect(consent).resolves.toBe(false)
+		expect(getDownloadConsentSnapshot().queue).toHaveLength(0)
+	})
+
+	it("a duplicate in-flight request resolves false without double queueing", async () => {
+		const first = requestDownloadConsent(ticket("g1"))
+		const second = requestDownloadConsent(ticket("g1"))
+		await expect(second).resolves.toBe(false)
+		expect(getDownloadConsentSnapshot().queue).toHaveLength(1)
+		decideDownloadConsent("g1", true)
+		await expect(first).resolves.toBe(true)
+	})
+
+	it("reset resolves every waiter and empties the queue", async () => {
+		const consent = requestDownloadConsent(ticket("h1"))
+		resetDownloadConsent()
+		await expect(consent).resolves.toBe(false)
+		expect(getDownloadConsentSnapshot().queue).toHaveLength(0)
+	})
+})

package/src/consent/consent-store.ts

@@ -0,0 +1,129 @@
+/**
+ * The consent-dialog queue for plugin asset downloads — the shared
+ * implementation both host apps mount:
+ *
+ * - the **app** feeds it from SSE (`pluginDownloadRequested` /
+ *   `pluginDownloadResolved`) and drives decisions through the server
+ *   (`pluginAsset.decide`); the resolved broadcast closes entries here;
+ * - the **workbench** has no server: its asset engine enqueues via
+ *   {@link request} and the dialog answers via {@link decide} — the same
+ *   dialog component, one queue per page, FIFO, one dialog at a time.
+ *
+ * State-only by design: decisions never mutate the queue directly
+ * except through `close`/`decide`, which the two hosts wire to their
+ * own decision path.
+ */
+
+/**
+ * A queued consent question: the ticket shape. Structurally identical to
+ * the server's `pluginDownloadRequested` SSE event minus its `type`
+ * discriminator (and to `pluginAsset.listPending` rows) — declared here
+ * instead of importing `@hoardodile/schemas` so the host-core package
+ * stays dependency-lean.
+ */
+export type DownloadConsentEntry = {
+	readonly ticketId: string
+	readonly pluginId: string
+	readonly pluginName: string
+	readonly url: string
+	readonly dest: string
+	readonly sizeBytes?: number
+	readonly reason?: string
+}
+
+type State = {
+	readonly queue: readonly DownloadConsentEntry[]
+}
+
+let state: State = { queue: [] }
+const listeners = new Set<() => void>()
+
+/** Engine side: tickets awaiting a local decision (workbench path). */
+const pending = new Map<
+	string,
+	{ readonly resolve: (approved: boolean) => void }
+>()
+
+function setState(next: State): void {
+	state = next
+	for (const listener of listeners) {
+		listener()
+	}
+}
+
+export function subscribeDownloadConsent(listener: () => void): () => void {
+	listeners.add(listener)
+	return () => {
+		listeners.delete(listener)
+	}
+}
+
+export function getDownloadConsentSnapshot(): State {
+	return state
+}
+
+/** A new ticket arrived (SSE) or was requested locally: append if absent. */
+export function enqueueDownloadConsent(entry: DownloadConsentEntry): void {
+	for (const existing of state.queue) {
+		if (existing.ticketId === entry.ticketId) return
+	}
+	setState({ queue: [...state.queue, entry] })
+}
+
+/** A ticket resolved (decide/timeout/dispose): drop it in every consumer. */
+export function closeDownloadConsent(ticketId: string): void {
+	const queue = state.queue.filter((entry) => entry.ticketId !== ticketId)
+	if (queue.length === state.queue.length) return
+	setState({ queue })
+}
+
+/**
+ * Replace the queue from a pending list (app: `listPending` after an SSE
+ * reconnect; workbench: same API on restart).
+ */
+export function rehydrateDownloadConsent(
+	entries: readonly DownloadConsentEntry[],
+): void {
+	const byTicket = new Map<string, DownloadConsentEntry>()
+	for (const entry of entries) byTicket.set(entry.ticketId, entry)
+	setState({ queue: [...byTicket.values()] })
+}
+
+/**
+ * Enqueue a ticket and wait for its decision (workbench engine path).
+ * The dialog's answer arrives through {@link decideDownloadConsent}.
+ */
+export function requestDownloadConsent(
+	entry: DownloadConsentEntry,
+): Promise<boolean> {
+	if (pending.has(entry.ticketId)) {
+		return Promise.resolve(false)
+	}
+	enqueueDownloadConsent(entry)
+	return new Promise<boolean>((resolve) => {
+		pending.set(entry.ticketId, { resolve })
+	})
+}
+
+/**
+ * Answer a ticket from the dialog. Closes the entry and resolves any
+ * awaiting engine call. Idempotent; unknown tickets are a no-op.
+ */
+export function decideDownloadConsent(
+	ticketId: string,
+	approved: boolean,
+): void {
+	const waiter = pending.get(ticketId)
+	if (waiter !== undefined) {
+		pending.delete(ticketId)
+		waiter.resolve(approved)
+	}
+	closeDownloadConsent(ticketId)
+}
+
+/** Test-only: reset the singleton between tests. */
+export function resetDownloadConsent(): void {
+	for (const waiter of pending.values()) waiter.resolve(false)
+	pending.clear()
+	setState({ queue: [] })
+}

package/src/host-core/request-schemas.ts

@@ -0,0 +1,85 @@
+import { anchorData as anchorDataSchema } from "@hoardodile/sdk-types/schema"
+import type { PluginRequests } from "@hoardodile/sdk-web"
+import { pluginMethods } from "@hoardodile/sdk-web"
+import { z } from "zod"
+
+/**
+ * Wire-level param schemas for every request method, shared by the real
+ * host (apps/web) and the offline mock host. Both hosts validate
+ * identical shapes, so a plugin that passes validation in the mock is
+ * guaranteed to pass in production.
+ */
+
+/**
+ * Wire shape of a message/danmaku anchor: the plugin location payload
+ * only. The resource id is host state — the host stamps its own binding
+ * into the anchor before it reaches the server.
+ */
+export const anchorData = anchorDataSchema
+
+export const requestSchemas = {
+	[pluginMethods.readFile]: z.object({
+		path: z.string().min(1),
+		range: z
+			.object({
+				start: z.number().int().nonnegative().optional(),
+				end: z.number().int().nonnegative().optional(),
+			})
+			.optional(),
+	}),
+	[pluginMethods.listFiles]: undefined,
+	[pluginMethods.listMessages]: undefined,
+	[pluginMethods.createMessage]: z.object({
+		body: z.string().min(1),
+		anchor: anchorData.optional(),
+	}),
+	[pluginMethods.listDanmaku]: z.object({
+		// Filter keys are plugin-defined vocabulary; matching is generic
+		// strict equality against the anchor's data.
+		filter: z
+			.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+			.optional(),
+	}),
+	[pluginMethods.createDanmaku]: z.object({
+		text: z.string().min(1),
+		anchor: anchorData,
+		mode: z.string().optional(),
+	}),
+	[pluginMethods.setPref]: z.object({
+		key: z.string().min(1),
+		value: z.string(),
+	}),
+	[pluginMethods.setCache]: z.object({
+		key: z.string().min(1),
+		value: z.string(),
+	}),
+	[pluginMethods.invalidate]: z.object({
+		target: z.enum(["resource", "resources", "messages", "danmaku"]),
+	}),
+	// The URL is length-capped but not URI-validated here: the host parses
+	// it server-side and answers with a machine-readable POLICY error.
+	[pluginMethods.download]: z.object({
+		url: z.string().min(1).max(2048),
+		dest: z.string().min(1).max(256),
+		sha256: z
+			.string()
+			.regex(/^[0-9a-f]{64}$/)
+			.optional(),
+		reason: z.string().max(200).optional(),
+	}),
+	[pluginMethods.deleteAsset]: z.object({
+		path: z.string().min(1).max(256),
+	}),
+	[pluginMethods.logInfo]: z.object({
+		message: z.string(),
+		data: z.record(z.string(), z.unknown()).optional(),
+	}),
+	[pluginMethods.logWarn]: z.object({
+		message: z.string(),
+		data: z.record(z.string(), z.unknown()).optional(),
+	}),
+	[pluginMethods.logError]: z.object({
+		message: z.string(),
+		data: z.record(z.string(), z.unknown()).optional(),
+	}),
+} satisfies Record<keyof PluginRequests, z.ZodTypeAny | undefined>

package/src/host-core/router.test.ts

@@ -0,0 +1,231 @@
+import { pluginMethods } from "@hoardodile/sdk-web"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { anchorData, requestSchemas } from "./request-schemas.ts"
+import type { HostHandlerEntry } from "./router.ts"
+import { createHostRouter, defineHandler } from "./router.ts"
+
+type FakeWindow = Window & { postMessage: (...args: unknown[]) => void }
+
+function fakeWindow(): FakeWindow {
+	const w = new EventTarget() as unknown as FakeWindow
+	w.postMessage = vi.fn() as unknown as (...args: unknown[]) => void
+	return w
+}
+
+function fakeMessageEvent(data: unknown, source: Window): MessageEvent {
+	return new MessageEvent("message", {
+		data,
+		source,
+		origin: "null",
+	})
+}
+
+function buildRouter(handlers: readonly HostHandlerEntry[] = []) {
+	const respond = vi.fn()
+	const subscribe = vi.fn()
+	const router = createHostRouter(handlers, {
+		resolveSource(event) {
+			const source = event.source
+			if (source === null) return undefined
+			return { source, record: { pluginId: "p-1", resId: "r-1" } }
+		},
+		respond,
+		subscribe,
+	})
+	return { router, respond, subscribe }
+}
+
+afterEach(() => {
+	vi.restoreAllMocks()
+})
+
+describe("createHostRouter", () => {
+	it("routes a request to its handler and responds", async () => {
+		const { router, respond } = buildRouter([
+			defineHandler(pluginMethods.listFiles, async () => ["a.png"]),
+		])
+		const source = fakeWindow()
+		router(
+			fakeMessageEvent(
+				{ type: "request", id: 1, method: pluginMethods.listFiles },
+				source,
+			),
+		)
+		await vi.waitFor(() => expect(respond).toHaveBeenCalled())
+		expect(respond).toHaveBeenCalledWith(source, {
+			type: "response",
+			id: 1,
+			ok: true,
+			data: ["a.png"],
+		})
+	})
+
+	it("validates params with the shared schema before the handler", async () => {
+		const handler = vi.fn(async () => "ran")
+		const { router, respond } = buildRouter([
+			defineHandler(
+				pluginMethods.readFile,
+				requestSchemas[pluginMethods.readFile],
+				handler,
+			),
+		])
+		const source = fakeWindow()
+		router(
+			fakeMessageEvent(
+				{ type: "request", id: 1, method: pluginMethods.readFile, params: {} },
+				source,
+			),
+		)
+		await vi.waitFor(() => expect(respond).toHaveBeenCalled())
+		expect(handler).not.toHaveBeenCalled()
+		expect(respond).toHaveBeenCalledWith(source, {
+			type: "response",
+			id: 1,
+			ok: false,
+			error: expect.stringContaining("Invalid params"),
+		})
+	})
+
+	it("passes validated params to the handler", async () => {
+		const seen: unknown[] = []
+		const { router } = buildRouter([
+			defineHandler(
+				pluginMethods.createMessage,
+				requestSchemas[pluginMethods.createMessage],
+				async (_ctx, params) => {
+					seen.push(params)
+					return "ok"
+				},
+			),
+		])
+		const source = fakeWindow()
+		router(
+			fakeMessageEvent(
+				{
+					type: "request",
+					id: 1,
+					method: pluginMethods.createMessage,
+					params: { body: "hi", anchor: { data: { page: 3 } } },
+				},
+				source,
+			),
+		)
+		await vi.waitFor(() => expect(seen).toHaveLength(1))
+		expect(seen[0]).toEqual({ body: "hi", anchor: { data: { page: 3 } } })
+	})
+
+	it("drops a stale resId stamp without invoking the handler", async () => {
+		const handler = vi.fn(async () => "ran")
+		const { router, respond } = buildRouter([
+			defineHandler(
+				pluginMethods.readFile,
+				requestSchemas[pluginMethods.readFile],
+				handler,
+			),
+		])
+		const source = fakeWindow()
+		router(
+			fakeMessageEvent(
+				{
+					type: "request",
+					id: 1,
+					method: pluginMethods.readFile,
+					params: { path: "a.png" },
+					resId: "r-foreign",
+				},
+				source,
+			),
+		)
+		await vi.waitFor(() => expect(respond).toHaveBeenCalled())
+		expect(handler).not.toHaveBeenCalled()
+		expect(respond).toHaveBeenCalledWith(source, {
+			type: "response",
+			id: 1,
+			ok: true,
+		})
+	})
+
+	it("rejects unknown methods with an error response", async () => {
+		const { router, respond } = buildRouter()
+		const source = fakeWindow()
+		router(fakeMessageEvent({ type: "request", id: 1, method: "nope" }, source))
+		await vi.waitFor(() => expect(respond).toHaveBeenCalled())
+		expect(respond).toHaveBeenCalledWith(source, {
+			type: "response",
+			id: 1,
+			ok: false,
+			error: "Unknown method: nope",
+		})
+	})
+
+	it("records subscriptions without responding", async () => {
+		const { router, respond, subscribe } = buildRouter()
+		const source = fakeWindow()
+		router(fakeMessageEvent({ type: "subscribe", key: "themeChanged" }, source))
+		expect(subscribe).toHaveBeenCalledWith(source, "themeChanged")
+		expect(respond).not.toHaveBeenCalled()
+	})
+
+	it("drops messages from unresolved sources", async () => {
+		const respond = vi.fn()
+		const router = createHostRouter([], {
+			resolveSource: () => undefined,
+			respond,
+			subscribe: () => {},
+		})
+		router(
+			fakeMessageEvent(
+				{ type: "request", id: 1, method: pluginMethods.listFiles },
+				fakeWindow(),
+			),
+		)
+		expect(respond).not.toHaveBeenCalled()
+	})
+
+	it("warns once per source about a missing protocol stamp", async () => {
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+		const { router, respond } = buildRouter()
+		const source = fakeWindow()
+		const event = (data: unknown) => fakeMessageEvent(data, source)
+		router(event({ type: "subscribe", key: "themeChanged" }))
+		router(event({ type: "subscribe", key: "visibility" }))
+		expect(warnSpy).toHaveBeenCalledTimes(1)
+		expect(warnSpy.mock.calls[0]?.[0]).toContain("did not stamp")
+		expect(respond).not.toHaveBeenCalled()
+	})
+
+	it("warns once per source about a protocol version mismatch", async () => {
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+		const { router, respond } = buildRouter()
+		const source = fakeWindow()
+		const event = (data: unknown) => fakeMessageEvent(data, source)
+		router(event({ type: "subscribe", key: "themeChanged", proto: 999 }))
+		router(event({ type: "subscribe", key: "visibility", proto: 999 }))
+		expect(warnSpy).toHaveBeenCalledTimes(1)
+		expect(warnSpy.mock.calls[0]?.[0]).toContain("protocol version 999")
+		expect(respond).not.toHaveBeenCalled()
+	})
+
+	it("does not warn for matching protocol stamps", async () => {
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+		const { router } = buildRouter()
+		const source = fakeWindow()
+		router(
+			fakeMessageEvent(
+				{ type: "subscribe", key: "themeChanged", proto: 1 },
+				source,
+			),
+		)
+		expect(warnSpy).not.toHaveBeenCalled()
+	})
+})
+
+describe("requestSchemas", () => {
+	it("anchorData accepts only the plugin location payload", () => {
+		expect(anchorData.safeParse({ data: { page: 1 } }).success).toBe(true)
+		expect(anchorData.safeParse({ data: 1 }).success).toBe(true)
+		expect(anchorData.safeParse({}).success).toBe(true)
+		// The resource id is host state — a plugin sending it is rejected.
+		expect(anchorData.safeParse({ resId: "r-1" }).success).toBe(false)
+	})
+})