@hoardodile/host 0.0.0

package/src/loader.test.ts

@@ -0,0 +1,442 @@
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import type { PluginManifest } from "@hoardodile/sdk-types"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+import { createPluginLoader } from "./loader.ts"
+import type { PluginSandbox } from "./sandbox/host.ts"
+import type { PluginSettingsStore } from "./settings-store.ts"
+
+const SHARED_ID = "11111111-1111-4111-8111-111111111111"
+
+/** Empty settings store — these tests never record plugin settings. */
+function createTestSettingsStore(): PluginSettingsStore {
+	return {
+		get: () => undefined,
+		all: () => [],
+	}
+}
+
+function writePluginDir(dir: string, manifest: PluginManifest): void {
+	mkdirSync(dir, { recursive: true })
+	writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest))
+}
+
+function buildManifest(
+	overrides: Partial<PluginManifest> = {},
+): PluginManifest {
+	return {
+		id: SHARED_ID,
+		name: "Test Plugin",
+		description: "Loader test fixture",
+		version: "1.0.0",
+		permissions: {
+			sourceMeta: false,
+			searchMeta: false,
+			danmaku: false,
+			message: false,
+			imageHashes: false,
+			container: false,
+			download: false,
+		},
+		...overrides,
+	}
+}
+
+describe("plugin loader: dev plugin overrides same-id disk plugin", () => {
+	let root: string
+	let pluginsDir: string
+	let devDir: string
+	let consoleWarnSpy: ReturnType<typeof vi.spyOn> | undefined
+	let consoleInfoSpy: ReturnType<typeof vi.spyOn> | undefined
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "app-plugin-loader-"))
+		pluginsDir = join(root, "plugins")
+		devDir = join(root, "dev")
+		mkdirSync(pluginsDir, { recursive: true })
+		consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+		consoleInfoSpy = vi.spyOn(console, "info").mockImplementation(() => {})
+	})
+
+	afterEach(() => {
+		consoleWarnSpy?.mockRestore()
+		consoleInfoSpy?.mockRestore()
+		rmSync(root, { recursive: true, force: true })
+	})
+
+	test("only the dev entry survives, disk entry is skipped with a warning", async () => {
+		writePluginDir(join(pluginsDir, "shared"), buildManifest())
+		writePluginDir(devDir, buildManifest())
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			devPluginDirs: [devDir],
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const matching = registry.getAll().filter((e) => e.id === SHARED_ID)
+		expect(matching).toHaveLength(1)
+		expect(matching[0]?.dev).toBe(true)
+		expect(matching[0]?.diskPath).toBe(devDir)
+
+		const skipLogs = consoleWarnSpy?.mock.calls.filter((args: unknown[]) => {
+			const first = args[0]
+			return (
+				typeof first === "string" &&
+				first.includes("skipping disk plugin") &&
+				first.includes(SHARED_ID)
+			)
+		})
+		expect(skipLogs).toHaveLength(1)
+	})
+
+	test("disk entry loads when no dev plugin overrides it", async () => {
+		writePluginDir(join(pluginsDir, "shared"), buildManifest())
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const matching = registry.getAll().filter((e) => e.id === SHARED_ID)
+		expect(matching).toHaveLength(1)
+		expect(matching[0]?.dev).toBe(false)
+		expect(matching[0]?.diskPath).toBe(join(pluginsDir, "shared"))
+	})
+
+	test("dev plugins are ignored when disableDevPlugins is true", async () => {
+		writePluginDir(join(pluginsDir, "shared"), buildManifest())
+		writePluginDir(devDir, buildManifest({ name: "Dev Override" }))
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			devPluginDirs: [devDir],
+			disableDevPlugins: true,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const matching = registry.getAll().filter((e) => e.id === SHARED_ID)
+		expect(matching).toHaveLength(1)
+		expect(matching[0]?.dev).toBe(false)
+		expect(matching[0]?.diskPath).toBe(join(pluginsDir, "shared"))
+	})
+
+	test("manifest with ui.card loads and parses slot templates", async () => {
+		writePluginDir(
+			join(pluginsDir, "card"),
+			buildManifest({
+				id: "22222222-2222-4222-8222-222222222222",
+				ui: {
+					card: {
+						image: {
+							br: ["{{bytes(file.sizeBytes)}}"],
+							bl: ["{{source.width}}×{{source.height}}"],
+						},
+						video: {
+							br: ["{{bytes(file.sizeBytes)}}"],
+							tl: ["▶ {{duration(source.durationMs)}}"],
+						},
+						audio: {
+							br: ["{{bytes(file.sizeBytes)}}"],
+						},
+					},
+				},
+			}),
+		)
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const entry = registry.getById("22222222-2222-4222-8222-222222222222")
+		expect(entry).toBeDefined()
+		expect(entry?.manifest.ui?.card?.image?.br).toEqual([
+			"{{bytes(file.sizeBytes)}}",
+		])
+		expect(entry?.manifest.ui?.card?.video?.tl).toEqual([
+			"▶ {{duration(source.durationMs)}}",
+		])
+	})
+
+	test("manifest with invalid ui.card kind strips unknown keys", async () => {
+		writePluginDir(
+			join(pluginsDir, "bad"),
+			buildManifest({
+				id: "33333333-3333-4333-8333-333333333333",
+				ui: {
+					card: {
+						// @ts-expect-error — injecting an invalid kind for testing
+						invalidKind: {
+							br: ["bad"],
+						},
+					},
+				},
+			}),
+		)
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const entry = registry.getById("33333333-3333-4333-8333-333333333333")
+		expect(entry).toBeDefined()
+		// Zod strips unknown keys during parse, so invalidKind is discarded.
+		expect(
+			// @ts-expect-error — accessing a stripped key
+			entry?.manifest.ui?.card?.invalidKind,
+		).toBeUndefined()
+	})
+})
+
+describe("plugin loader: plugin seeding", () => {
+	let root: string
+	let pluginsDir: string
+	let seedDir: string
+	let consoleWarnSpy: ReturnType<typeof vi.spyOn> | undefined
+	let consoleInfoSpy: ReturnType<typeof vi.spyOn> | undefined
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "app-plugin-seed-"))
+		pluginsDir = join(root, "plugins")
+		seedDir = join(root, "seed")
+		mkdirSync(pluginsDir, { recursive: true })
+		consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+		consoleInfoSpy = vi.spyOn(console, "info").mockImplementation(() => {})
+	})
+
+	afterEach(() => {
+		consoleWarnSpy?.mockRestore()
+		consoleInfoSpy?.mockRestore()
+		rmSync(root, { recursive: true, force: true })
+	})
+
+	test("each seed directory is copied into pluginsDir under its manifest id", async () => {
+		const firstId = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
+		const secondId = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
+		writePluginDir(join(seedDir, "first"), buildManifest({ id: firstId }))
+		writePluginDir(join(seedDir, "second"), buildManifest({ id: secondId }))
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			seedPluginDirs: [join(seedDir, "first"), join(seedDir, "second")],
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		expect(registry.getById(firstId)?.diskPath).toBe(join(pluginsDir, firstId))
+		expect(registry.getById(secondId)?.diskPath).toBe(
+			join(pluginsDir, secondId),
+		)
+		expect(existsSync(join(pluginsDir, firstId, "manifest.json"))).toBe(true)
+	})
+
+	test("seed replaces an existing installed copy", async () => {
+		writePluginDir(join(pluginsDir, SHARED_ID), buildManifest({ name: "old" }))
+		writePluginDir(join(seedDir, "plugin"), buildManifest({ name: "new" }))
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			seedPluginDirs: [join(seedDir, "plugin")],
+			settings: createTestSettingsStore(),
+		})
+		await loader.loadAll()
+
+		const seeded = readFileSync(
+			join(pluginsDir, SHARED_ID, "manifest.json"),
+			"utf-8",
+		)
+		expect(JSON.parse(seeded).name).toBe("new")
+	})
+
+	test("dev plugin still overrides its seeded disk copy", async () => {
+		const devDir = join(root, "dev")
+		writePluginDir(join(seedDir, "plugin"), buildManifest({ name: "disk" }))
+		writePluginDir(devDir, buildManifest({ name: "dev" }))
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			devPluginDirs: [devDir],
+			seedPluginDirs: [join(seedDir, "plugin")],
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		const matching = registry.getAll().filter((e) => e.id === SHARED_ID)
+		expect(matching).toHaveLength(1)
+		expect(matching[0]?.dev).toBe(true)
+		expect(matching[0]?.diskPath).toBe(devDir)
+	})
+
+	test("invalid seed directories are skipped", async () => {
+		const loader = createPluginLoader({
+			pluginsDir,
+			seedPluginDirs: [join(root, "missing"), join(root, "invalid")],
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		expect(registry.getAll()).toEqual([])
+		expect(readdirSync(pluginsDir)).toEqual([])
+	})
+})
+
+describe("plugin loader: same-id dedupe", () => {
+	let root: string
+	let pluginsDir: string
+	let consoleWarnSpy: ReturnType<typeof vi.spyOn> | undefined
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "app-plugin-dedupe-"))
+		pluginsDir = join(root, "plugins")
+		mkdirSync(pluginsDir, { recursive: true })
+		consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+	})
+
+	afterEach(() => {
+		consoleWarnSpy?.mockRestore()
+		rmSync(root, { recursive: true, force: true })
+	})
+
+	test("two dev dirs with the same id: only the last one survives", async () => {
+		const devA = join(root, "dev-a")
+		const devB = join(root, "dev-b")
+		writePluginDir(devA, buildManifest({ name: "A" }))
+		writePluginDir(devB, buildManifest({ name: "B" }))
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			devPluginDirs: [devA, devB],
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		// One entry per id everywhere — the last dev dir wins.
+		expect(registry.getAll().filter((e) => e.id === SHARED_ID)).toHaveLength(1)
+		expect(registry.getById(SHARED_ID)?.diskPath).toBe(devB)
+		expect(registry.getEnabled()).toHaveLength(1)
+	})
+
+	test("a disk copy of the builtin plugin id is skipped", async () => {
+		const builtinDir = join(root, "builtin")
+		writePluginDir(builtinDir, buildManifest({ name: "Builtin" }))
+		writePluginDir(join(pluginsDir, "copy"), buildManifest({ name: "Copy" }))
+
+		const loader = createPluginLoader({
+			builtinDir,
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		expect(registry.getAll().filter((e) => e.id === SHARED_ID)).toHaveLength(1)
+		expect(registry.getBuiltin()?.id).toBe(SHARED_ID)
+		expect(registry.getBuiltin()?.builtin).toBe(true)
+		expect(registry.getBuiltin()?.diskPath).toBe(builtinDir)
+	})
+
+	test("two disk dirs with the same id: only the first survives", async () => {
+		writePluginDir(join(pluginsDir, "first"), buildManifest({ name: "First" }))
+		writePluginDir(
+			join(pluginsDir, "second"),
+			buildManifest({ name: "Second" }),
+		)
+
+		const loader = createPluginLoader({
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const registry = await loader.loadAll()
+
+		expect(registry.getAll().filter((e) => e.id === SHARED_ID)).toHaveLength(1)
+		expect(registry.getById(SHARED_ID)?.diskPath).toBe(
+			join(pluginsDir, "first"),
+		)
+	})
+
+	test("a later loadAll after a broken builtin degrades without stranding the registry", async () => {
+		const builtinDir = join(root, "builtin")
+		writePluginDir(builtinDir, buildManifest({ name: "Builtin" }))
+
+		const loader = createPluginLoader({
+			builtinDir,
+			pluginsDir,
+			settings: createTestSettingsStore(),
+		})
+		const first = await loader.loadAll()
+		expect(first.getBuiltin()?.id).toBe(SHARED_ID)
+
+		// The builtin directory disappears mid-session: the FIRST load at
+		// boot fails fast (config error), but a later rescan must not throw
+		// — it degrades to a registry without the builtin.
+		rmSync(builtinDir, { recursive: true, force: true })
+		const second = await loader.rescan()
+		expect(second.getBuiltin()).toBeUndefined()
+		expect(second).not.toBe(first)
+	})
+})
+
+describe("plugin loader: loadAll serialization", () => {
+	let root: string
+	let consoleLogSpy: ReturnType<typeof vi.spyOn> | undefined
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "app-plugin-loader-"))
+		consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+	})
+
+	afterEach(() => {
+		consoleLogSpy?.mockRestore()
+		rmSync(root, { recursive: true, force: true })
+	})
+
+	test("concurrent loadAll calls never interleave sandbox teardown", async () => {
+		const log: string[] = []
+		const sandbox: PluginSandbox = {
+			loadPlugin: async () => undefined,
+			unloadPlugin: () => {},
+			disposeExcept: async (keepIds) => {
+				log.push("dispose:start")
+				await new Promise((resolve) => setTimeout(resolve, 10))
+				log.push(`dispose:end:${[...keepIds].length}`)
+			},
+			disposeAll: async () => {},
+		}
+		const loader = createPluginLoader({
+			pluginsDir: join(root, "plugins"),
+			settings: createTestSettingsStore(),
+			sandbox,
+		})
+
+		const [first, second] = await Promise.all([
+			loader.loadAll(),
+			loader.loadAll(),
+		])
+		expect(first).toBeDefined()
+		expect(loader.getRegistry()).toBe(second)
+
+		// Every teardown must complete before the next run starts one.
+		const starts = log.flatMap((event, i) =>
+			event === "dispose:start" ? [i] : [],
+		)
+		expect(starts).toHaveLength(2)
+		for (const i of starts) {
+			expect(log[i + 1]).toMatch(/^dispose:end:/)
+		}
+	})
+})

package/src/loader.ts

@@ -0,0 +1,213 @@
+import type { PluginManifestId } from "@hoardodile/sdk-types"
+import { createPluginActivation } from "./activation.ts"
+import type { PluginRegistry, PluginRegistryEntry } from "./api-types.ts"
+import { createPluginDiscovery } from "./discovery.ts"
+import { createPluginSandbox, type PluginSandbox } from "./sandbox/host.ts"
+import { seedPlugins } from "./seed.ts"
+import type { PluginSettingsStore } from "./settings-store.ts"
+
+export { seedPlugins } from "./seed.ts"
+
+/**
+ * Loads plugins into a live {@link PluginRegistry}: seed the configured
+ * plugin directories, discover, activate, and sort by priority.
+ * `loadAll`/`rescan` are serialized — an overlapping run would replace
+ * workers out from under the previous run's in-flight loads.
+ *
+ * The previous registry and its workers are only replaced AFTER the new
+ * registry finished activating: a failed load never strands a stale
+ * registry whose workers were already disposed (every hook would then
+ * fail until the next restart).
+ */
+export type PluginLoader = {
+	readonly loadAll: () => Promise<PluginRegistry>
+	readonly rescan: () => Promise<PluginRegistry>
+	/** The current registry; throws when `loadAll` has not run yet. */
+	readonly getRegistry: () => PluginRegistry
+}
+
+export type PluginLoaderDeps = {
+	readonly builtinDir?: string
+	readonly devPluginDirs?: readonly string[]
+	/**
+	 * Plugin directories (each with `manifest.json` at its root, e.g. a
+	 * built plugin's `dist/`) that are seeded into `pluginsDir` on every
+	 * load. Each plugin is copied into `pluginsDir/<manifest.id>` before
+	 * discovery runs when the destination tree differs — so a seeded
+	 * plugin behaves like a regular installed one (DB settings, caching,
+	 * uninstall). The server passes an empty list and seeds through
+	 * `writeVersioned` instead. When omitted, nothing is seeded.
+	 */
+	readonly seedPluginDirs?: readonly string[]
+	readonly pluginsDir: string
+	readonly settings: PluginSettingsStore
+	readonly disableDevPlugins?: boolean
+	/**
+	 * Worker-thread sandbox that executes plugin hooks. Optional so tests
+	 * without any `main.js` on disk can omit it; the default spawns real
+	 * workers when a loadable bundle is found.
+	 */
+	readonly sandbox?: PluginSandbox
+	/**
+	 * Optional timing sink for boot diagnostics — receives the duration of
+	 * each `loadAll` step. Defaults to a no-op so tests stay quiet.
+	 */
+	readonly onTiming?: (step: string, ms: number) => void
+}
+
+/**
+ * Create the plugin loader. Workers are respawned on every load so a
+ * rescan picks up changed plugin code — the new worker re-imports
+ * `main.js`, bypassing the main thread's ESM module cache. Configured
+ * {@link PluginLoaderDeps.seedPluginDirs} are copied into `pluginsDir`
+ * on each load.
+ */
+export function createPluginLoader(deps: PluginLoaderDeps): PluginLoader {
+	let registry: PluginRegistry | undefined
+	// Serializes loadAll/rescan: an overlapping run would replace workers
+	// out from under the previous run's in-flight plugin loads.
+	let chain: Promise<unknown> = Promise.resolve()
+
+	const discovery = createPluginDiscovery(deps)
+	const sandbox = deps.sandbox ?? createPluginSandbox()
+	const activation = createPluginActivation({ sandbox })
+
+	function loadAll(): Promise<PluginRegistry> {
+		const run = chain.then(doLoadAll)
+		chain = run.catch(() => {})
+		return run
+	}
+
+	async function doLoadAll(): Promise<PluginRegistry> {
+		// Seed first — tolerant of individual failures: a locked directory
+		// (Windows/AV races with a plugin watch rebuilding dist) only skips
+		// that plugin instead of aborting the whole load.
+		const seedStart = performance.now()
+		seedPlugins(deps.pluginsDir, deps.seedPluginDirs)
+		deps.onTiming?.("seed", Math.round(performance.now() - seedStart))
+
+		const discoverStart = performance.now()
+		const { found, missing } = await discovery.discover()
+		deps.onTiming?.("discover", Math.round(performance.now() - discoverStart))
+
+		// Activate BEFORE disposing anything from the previous registry:
+		// same-id plugins replace their worker in the sandbox, and a
+		// failure anywhere above leaves the previous registry (and its
+		// workers) fully alive instead of stranding a stale registry with
+		// disposed workers.
+		const activateStart = performance.now()
+		const activated = await activation.activateAll(found)
+		deps.onTiming?.("activate", Math.round(performance.now() - activateStart))
+
+		const failing = activation.createFailingEntries(missing)
+
+		const entries = [...activated, ...failing]
+		entries.sort((a, b) => a.priority - b.priority)
+
+		const next = buildRegistry(entries)
+		// Plugins that left the registry (uninstalled/removed) free their
+		// workers; everything still registered keeps the worker activation
+		// just loaded.
+		await sandbox.disposeExcept(new Set(next.getAll().map((e) => e.id)))
+		registry = next
+		return registry
+	}
+
+	async function rescan(): Promise<PluginRegistry> {
+		return loadAll()
+	}
+
+	function getRegistry(): PluginRegistry {
+		if (registry === undefined) {
+			throw new Error("Plugin registry not initialised — call loadAll() first")
+		}
+		return registry
+	}
+
+	return { loadAll, rescan, getRegistry }
+}
+
+/**
+ * Build the immutable-ish registry from entries, keyed by plugin UUID.
+ * Duplicate ids keep the first entry and warn (the UUID contract is
+ * unique — duplicates signal a broken install). Duplicates are dropped
+ * from every accessor, not just the id map: keeping a duplicate in
+ * `getAll()` would make enabled-list iteration invoke a plugin whose
+ * worker activation already replaced (and disposed) the first load.
+ * `updateEntry` patches a single entry in place and re-sorts by priority.
+ */
+export function buildRegistry(
+	entries: readonly PluginRegistryEntry[],
+): PluginRegistry {
+	const byId = new Map<PluginManifestId, PluginRegistryEntry>()
+	const deduped: PluginRegistryEntry[] = []
+	for (const entry of entries) {
+		const existing = byId.get(entry.id)
+		if (existing !== undefined) {
+			console.warn(
+				`[plugin-loader] skipping ${entry.id}: UUID conflicts with already registered plugin (${existing.manifest.name ?? existing.id}), keeping first`,
+			)
+			continue
+		}
+		byId.set(entry.id, entry)
+		deduped.push(entry)
+	}
+
+	let sortedEntries = deduped
+
+	return {
+		getAll(): readonly PluginRegistryEntry[] {
+			return sortedEntries
+		},
+		getEnabled(): readonly PluginRegistryEntry[] {
+			return sortedEntries.filter((e) => e.enabled)
+		},
+		getById(id: PluginManifestId): PluginRegistryEntry | undefined {
+			return byId.get(id)
+		},
+		getBuiltin(): PluginRegistryEntry | undefined {
+			return sortedEntries.find((e) => e.builtin)
+		},
+		getForResource(
+			resPluginId: PluginManifestId,
+		): PluginRegistryEntry | undefined {
+			const entry = byId.get(resPluginId)
+			if (entry === undefined || !entry.enabled) return undefined
+			return entry
+		},
+		updateEntry(
+			id: PluginManifestId,
+			patch: Partial<
+				Pick<
+					PluginRegistryEntry,
+					"enabled" | "priority" | "pinned" | "color" | "missing"
+				>
+			>,
+		): void {
+			const index = sortedEntries.findIndex((e) => e.id === id)
+			if (index === -1) return
+			const old = sortedEntries[index]
+			if (old === undefined) return
+			const updated: PluginRegistryEntry = {
+				id: old.id,
+				manifest: old.manifest,
+				plugin: old.plugin,
+				diskPath: old.diskPath,
+				enabled: patch.enabled ?? old.enabled,
+				priority: patch.priority ?? old.priority,
+				pinned: patch.pinned ?? old.pinned,
+				color: patch.color ?? old.color,
+				missing: patch.missing ?? old.missing,
+				builtin: old.builtin,
+				dev: old.dev,
+			}
+			sortedEntries = [
+				...sortedEntries.slice(0, index),
+				updated,
+				...sortedEntries.slice(index + 1),
+			]
+			sortedEntries.sort((a, b) => a.priority - b.priority)
+			byId.set(id, updated)
+		},
+	}
+}

package/src/media/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Media pipeline helpers: entry-to-render-input dispatch, the
+ * streamable-vs-materialized source gate, and the cache/queue render
+ * gate. Shared by the server's thumbnail service and cover-meta probes
+ * so both paths agree on how a zip entry becomes a renderable source.
+ */
+
+export type { KeyedTaskQueue } from "./render-cache.ts"
+export { withCacheAndQueue } from "./render-cache.ts"
+export { withMediaSource } from "./seekable.ts"
+export type { ThumbInput, WithThumbInputOptions } from "./thumb-input.ts"
+export {
+	ffmpegThumbSource,
+	imageThumbSource,
+	withThumbInput,
+} from "./thumb-input.ts"

package/src/media/render-cache.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal keyed task queue contract. Structural: the server's
+ * `createKeyedQueue` (and the CLI's bench queue) satisfy it.
+ */
+export type KeyedTaskQueue<T> = {
+	readonly run: (key: string, job: () => Promise<T>) => Promise<T>
+}
+
+/**
+ * Cache-first render gate: return the cached result when present, else
+ * run the render job through the queue — re-checking the cache inside
+ * the queued task so concurrent callers coalesce onto one render.
+ */
+export async function withCacheAndQueue<T>(
+	queue: KeyedTaskQueue<T>,
+	checkCache: () => Promise<T | undefined>,
+	queueKey: string,
+	job: () => Promise<T>,
+): Promise<T> {
+	const cached = await checkCache()
+	if (cached !== undefined) return cached
+	return queue.run(queueKey, async () => {
+		const raced = await checkCache()
+		if (raced !== undefined) return raced
+		return job()
+	})
+}