@hoardodile/sdk-types 0.0.0

package/src/manifest.ts

@@ -0,0 +1,186 @@
+import { z } from "zod"
+
+/**
+ * Plugin manifest UUID (v4). Generated once when scaffolding a plugin
+ * (e.g. `crypto.randomUUID()`) and never reused across plugins — the
+ * server keys installed plugins by this id.
+ */
+export const pluginManifestId = z.string().uuid()
+export type PluginManifestId = z.infer<typeof pluginManifestId>
+
+/**
+ * Declared plugin capabilities. Each flag gates the corresponding API
+ * surface: a plugin without `danmaku` gets no danmaku methods and the
+ * host enforces the permission at the capability guard, so a manifest
+ * that does not declare a capability cannot call it.
+ */
+export const pluginPermissions = z.object({
+	/** Read/write the resource's source metadata. */
+	sourceMeta: z.boolean().default(false),
+	/** Produce and store search metadata facets. */
+	searchMeta: z.boolean().default(false),
+	/** Create/list danmaku for resources this plugin renders. */
+	danmaku: z.boolean().default(false),
+	/** Create/list messages for resources this plugin renders. */
+	message: z.boolean().default(false),
+	/** Produce content hashes for duplicate detection / image similarity. */
+	imageHashes: z.boolean().default(false),
+	/**
+	 * List and extract archive (zip/tar/7z/…) entries. The only API
+	 * surface with a write side effect (the host's extraction cache), so
+	 * it is denied by default.
+	 */
+	container: z.boolean().default(false),
+	/**
+	 * The plugin asset vault: user-consented downloads into the plugin's
+	 * own `vault/` directory plus the vault read/delete methods. Denied
+	 * by default — every download needs this capability AND the user's
+	 * per-request approval.
+	 */
+	download: z.boolean().default(false),
+})
+export type PluginPermissions = z.infer<typeof pluginPermissions>
+
+/**
+ * Label key → locale table: `{ "cover.open": { "en": "Open", "zh-CN": "打开" } }`.
+ * The host's template engine resolves `t('cover.open')` against the
+ * resource's locale from this map.
+ */
+export const localeString = z.record(z.string(), z.string())
+
+/** Icon reference: an asset path inside the plugin zip (`assets/icon.svg`). */
+export const iconRef = z.string().min(1)
+
+/**
+ * Corner template slot: a string rendered by the host's template engine
+ * over the resource scope. The engine supports `{{data.field}}` paths,
+ * pipes (`bytes`, `duration`, `number`, `inc`), comparisons
+ * (`eq`/`ne`/`gt`/`lt`/`gte`/`lte`), `if(cond, a, b)`, `join`,
+ * `t('key')` for i18n, `icon('Icon')`, `asset('path')`,
+ * `kind(...)`, and `searchKindIcons()` (the plugin's search kinds).
+ * Unknown expressions render as the empty string.
+ */
+const templateValue = z.string()
+
+/**
+ * Corner template slots for one content kind. Templates are rendered by
+ * the host's template engine over the resource's file list; supported
+ * directives include `{{data.field}}`, `{{duration(ms)}}`, `{{inc(n)}}`
+ * and `{{t('key')}}`.
+ */
+const coverKindUi = z.object({
+	tl: z.array(templateValue).optional(),
+	tr: z.array(templateValue).optional(),
+	bl: z.array(templateValue).optional(),
+	br: z.array(templateValue).optional(),
+})
+
+/**
+ * Cover templates per content kind. A plugin declares the kinds it can
+ * produce; the host picks the block matching the resource's cover type
+ * (`image`/`video`/`audio`/`default`) and renders each corner as
+ * specified, or falls back to the default cover when no block matches.
+ */
+const coverKindUiMap = z.object({
+	image: coverKindUi.optional(),
+	video: coverKindUi.optional(),
+	audio: coverKindUi.optional(),
+	default: coverKindUi.optional(),
+})
+
+/**
+ * A search facet kind: a named dimension with an icon, rendered as a
+ * facet group in the host's search UI. `key` becomes the facet key in
+ * the search metadata the plugin produces.
+ */
+export const searchKind = z.object({
+	key: z.string().min(1),
+	/** i18n label key shown as the facet group's title. */
+	label: z.string().min(1),
+	/** Optional icon asset path in the plugin zip. */
+	icon: templateValue.optional(),
+})
+export type SearchKind = z.infer<typeof searchKind>
+
+const searchUi = z.object({
+	kinds: z.array(searchKind),
+})
+
+const messageUi = z.object({
+	/**
+	 * Template string for message anchor chip labels. Rendered by the
+	 * host's template engine. Supports `{{data.field}}`, `{{duration(ms)}}`,
+	 * `{{inc(n)}}`, `{{t('key')}}`, etc.
+	 */
+	anchor: z.string().min(1).optional(),
+})
+
+/**
+ * Manifest-declared UI preferences. These shape how the host app
+ * presents the plugin's iframe without the plugin shipping any host
+ * integration code.
+ */
+export const pluginManifestUi = z.object({
+	/**
+	 * Preferred preview surface height (any CSS length, e.g. "85vh").
+	 * Applied by both the resource detail page and the preview dialog.
+	 */
+	height: z.string().min(1).optional(),
+	/**
+	 * Preferred preview surface aspect ratio (e.g. "16/9"), capped by the
+	 * host at 70vh. Intended for video-centric plugins; takes precedence
+	 * over `height`. When neither is set the host falls back to 60vh.
+	 */
+	aspect: z.string().min(1).optional(),
+	/**
+	 * Cover template blocks per content kind. When present, the host
+	 * renders the resource cover from the plugin's file templates
+	 * instead of the built-in thumbnail pipeline.
+	 */
+	card: coverKindUiMap.optional(),
+	/** Search facet kinds; enables the plugin's search integration. */
+	search: searchUi.optional(),
+	/**
+	 * Anchor chip label template for messages; declares message-anchor
+	 * support in the host UI.
+	 */
+	message: messageUi.optional(),
+	/**
+	 * Whether the plugin iframe inherits the host's app font (default true).
+	 * Set to false for plugins that must render with their own fonts.
+	 */
+	inheritFont: z.boolean().optional(),
+})
+export type PluginManifestUi = z.infer<typeof pluginManifestUi>
+export type CoverKindUi = z.infer<typeof coverKindUi>
+export type CoverKindUiMap = z.infer<typeof coverKindUiMap>
+
+/**
+ * The plugin manifest contract — the single schema validated everywhere
+ * via its parse: the server at install time, the build CLI, and the
+ * workbench. A manifest lives at the zip root of a built plugin next to
+ * `main.js` and `index.html`.
+ */
+export const pluginManifest = z.object({
+	id: pluginManifestId,
+	/** Display name shown in the plugins list and resource badges. */
+	name: z.string().min(1),
+	/** One-line description shown in the plugins list. */
+	description: z.string().min(1),
+	/** Icon asset path inside the plugin zip. */
+	icon: iconRef.optional(),
+	/** Semantic plugin version; shown to users on the plugin card. */
+	version: z.string().min(1),
+	/** Declared capabilities (see {@link pluginPermissions}). */
+	permissions: pluginPermissions,
+	/**
+	 * Localized label tables: `{ labelKey: { locale: label } }`, e.g.
+	 * `{ "cover.open": { "en": "Open", "zh-CN": "打开" } }` — labels are
+	 * referenced from templates with `{{t('labelKey')}}` (see
+	 * {@link localeString}).
+	 */
+	i18n: z.record(z.string(), localeString).optional(),
+	/** UI preferences (see {@link pluginManifestUi}). */
+	ui: pluginManifestUi.optional(),
+})
+export type PluginManifest = z.infer<typeof pluginManifest>

package/src/media-exts.ts

@@ -0,0 +1,245 @@
+/**
+ * Canonical media-type knowledge: the extension sets, the extension →
+ * MIME table and the MIME → media-kind mapping shared by content
+ * plugins, the runtime host's sniffer and the server's classification
+ * pipeline.
+ *
+ * Extensions are a **hint**, never the verdict: `ResourceAPI.sniff`
+ * reads the file's magic bytes and only falls back to the tables here
+ * when the content carries no recognizable signature (text formats).
+ * The sets below therefore answer "which extensions do we expect to
+ * decode", not "what is this file".
+ *
+ * Lower-case, with leading dot — match the output of
+ * `path.extname(name).toLowerCase()`.
+ *
+ * Adding a new extension here widens classification everywhere at
+ * once. Before adding, verify:
+ * - sharp can extract width/height (image)
+ * - ffprobe can read width/height/duration (video)
+ * - ffprobe can read the stream/format metadata (audio), and the
+ *   extension has an entry in `AUDIO_FFMPEG_INPUT_FORMAT`
+ * - the extension has an entry in {@link EXT_MIME}
+ * - the gallery plugin's transcode-required set reflects the format
+ *   (browser-renderable originals stay native; HEIC/TIFF need the
+ *   sharp preview pipeline)
+ */
+export const IMAGE_EXTS: ReadonlySet<string> = new Set([
+	".jpg",
+	".jpeg",
+	".png",
+	".webp",
+	".gif",
+	".bmp",
+	".avif",
+	".heic",
+	".heif",
+	".tif",
+	".tiff",
+	".svg",
+	".jp2",
+	".j2k",
+	".jpx",
+])
+
+export const VIDEO_EXTS: ReadonlySet<string> = new Set([
+	".mp4",
+	".webm",
+	".mov",
+	".mkv",
+	".m4v",
+	".avi",
+	".3gp",
+])
+
+export const AUDIO_EXTS: ReadonlySet<string> = new Set([
+	".mp3",
+	".flac",
+	".ogg",
+	".m4a",
+	".wav",
+	".opus",
+	".aac",
+])
+
+/**
+ * Video containers ffmpeg can demux from a forward-only pipe (matroska,
+ * avi). ISO-BMFF files (.mp4/.mov/.m4v) keep their moov index at the end
+ * of the file, so a stream attempt on a zip-entry source is guaranteed to
+ * fail after burning a full probesize read — consumers (thumb pipeline,
+ * cover probing) send those straight to the materialized entry instead.
+ */
+export const STREAMABLE_VIDEO_EXTS: ReadonlySet<string> = new Set([
+	".webm",
+	".mkv",
+	".avi",
+])
+
+/**
+ * ffmpeg `-f` container name for piped audio bytes (no filename hint).
+ * `.opus` files are Ogg containers; `.m4a` is ISO-BMFF, demuxed by the
+ * mp4 demuxer.
+ */
+export const AUDIO_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {
+	".mp3": "mp3",
+	".flac": "flac",
+	".ogg": "ogg",
+	".opus": "ogg",
+	".wav": "wav",
+	".m4a": "mp4",
+	".aac": "aac",
+}
+
+/**
+ * ffmpeg `-f` container name keyed by **sniffed MIME type**, for piped
+ * sources that have no filename ffprobe could key off. Content-derived
+ * routing is what lets a mislabelled file still demux correctly, so
+ * this table — not the extension one — drives `ResourceAPI.probe`.
+ *
+ * Several spellings map to the same container because magic-byte
+ * matchers and IANA disagree on the canonical name (`audio/wav` vs
+ * `audio/x-wav`, `video/vnd.avi` vs `video/x-msvideo`).
+ */
+export const MIME_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {
+	"video/mp4": "mp4",
+	"video/quicktime": "mov",
+	"video/webm": "webm",
+	"video/x-matroska": "matroska",
+	"video/matroska": "matroska",
+	"video/vnd.avi": "avi",
+	"video/x-msvideo": "avi",
+	"video/avi": "avi",
+	"video/ogg": "ogg",
+	"audio/mpeg": "mp3",
+	"audio/mp3": "mp3",
+	"audio/flac": "flac",
+	"audio/x-flac": "flac",
+	"audio/ogg": "ogg",
+	"audio/opus": "ogg",
+	"audio/vorbis": "ogg",
+	"audio/wav": "wav",
+	"audio/x-wav": "wav",
+	"audio/vnd.wave": "wav",
+	"audio/wave": "wav",
+	"audio/mp4": "mp4",
+	"audio/x-m4a": "mp4",
+	"audio/aac": "aac",
+	"video/3gpp": "mp4",
+	"application/ogg": "ogg",
+	"application/x-matroska": "matroska",
+	"application/mp4": "mp4",
+}
+
+/**
+ * The audio mirror of {@link STREAMABLE_VIDEO_EXTS}: containers whose
+ * headers lead the file, so ffmpeg/ffprobe can demux them from a
+ * forward-only pipe. `.m4a` is ISO-BMFF with a trailing moov index, so
+ * it must be probed from a materialized (seekable) entry.
+ */
+export const STREAMABLE_AUDIO_EXTS: ReadonlySet<string> = new Set([
+	".mp3",
+	".flac",
+	".ogg",
+	".opus",
+	".wav",
+	".aac",
+])
+
+/**
+ * Media families a file can belong to. `other` covers everything the
+ * media pipeline does not decode (text, documents, archives, ...) — it
+ * is a real answer, not a failure.
+ */
+export const MEDIA_KINDS = ["image", "video", "audio", "other"] as const
+
+export type MediaKind = (typeof MEDIA_KINDS)[number]
+
+/**
+ * Extension → canonical MIME type. Used as the *fallback* branch of
+ * content sniffing: magic-byte detection covers binary media, while
+ * text-based formats (`.txt`, `.md`, `.csv`, subtitles, ...) carry no
+ * signature and can only be named by their extension.
+ */
+export const EXT_MIME: Readonly<Record<string, string>> = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".bmp": "image/bmp",
+	".avif": "image/avif",
+	".heic": "image/heic",
+	".heif": "image/heif",
+	".tif": "image/tiff",
+	".tiff": "image/tiff",
+	".jp2": "image/jp2",
+	".j2k": "image/jp2",
+	".jpx": "image/jp2",
+	".mp4": "video/mp4",
+	".m4v": "video/mp4",
+	".webm": "video/webm",
+	".mov": "video/quicktime",
+	".mkv": "video/x-matroska",
+	".avi": "video/vnd.avi",
+	".3gp": "video/3gpp",
+	".mp3": "audio/mpeg",
+	".flac": "audio/flac",
+	".ogg": "audio/ogg",
+	".opus": "audio/opus",
+	".m4a": "audio/mp4",
+	".wav": "audio/wav",
+	".aac": "audio/aac",
+	".txt": "text/plain",
+	".md": "text/markdown",
+	".csv": "text/csv",
+	".json": "application/json",
+	".xml": "text/xml",
+	".html": "text/html",
+	".htm": "text/html",
+	".svg": "image/svg+xml",
+	".srt": "application/x-subrip",
+	".vtt": "text/vtt",
+	".ass": "text/x-ssa",
+	".epub": "application/epub+zip",
+	".pdf": "application/pdf",
+	".zip": "application/zip",
+	".cbz": "application/vnd.comicbook+zip",
+	".cbr": "application/vnd.comicbook-rar",
+	".rar": "application/vnd.rar",
+	".7z": "application/x-7z-compressed",
+	".cb7": "application/x-7z-compressed",
+	".tar": "application/x-tar",
+	".cbt": "application/x-tar",
+}
+
+/**
+ * Container MIME types whose top-level type does not describe the
+ * payload. Ogg and Matroska carry audio *or* video, and `application/*`
+ * says nothing either way — the values here are the common case, and
+ * `ResourceAPI.probe` overrides them with the stream layout ffprobe
+ * actually reports.
+ */
+export const MIME_KIND_OVERRIDES: Readonly<Record<string, MediaKind>> = {
+	"application/ogg": "audio",
+	"application/x-matroska": "video",
+	"application/mp4": "video",
+}
+
+/**
+ * Media family of a MIME type: the override table first, then the
+ * top-level type. Never throws — unknown types are `other`.
+ */
+export function mimeToKind(mime: string): MediaKind {
+	const normalized = mime.toLowerCase()
+	const override = MIME_KIND_OVERRIDES[normalized]
+	if (override !== undefined) return override
+	if (normalized.startsWith("image/")) return "image"
+	if (normalized.startsWith("video/")) return "video"
+	if (normalized.startsWith("audio/")) return "audio"
+	return "other"
+}
+
+/** Canonical MIME type for an extension (leading dot), or `undefined`. */
+export function extToMime(ext: string): string | undefined {
+	return EXT_MIME[ext.toLowerCase()]
+}

package/src/plugin-asset-limits.ts

@@ -0,0 +1,23 @@
+/**
+ * Plugin asset runtime limits — the constants shared by the host, the
+ * SDK validators and the tooling. Backed by the `./plugin-asset-limits`
+ * subpath (plugin-facing constants never export from the root entry).
+ */
+
+/** Max length of a vault-relative `dest` (a plugin path is bounded, not arbitrary). */
+export const PLUGIN_ASSET_DEST_MAX_LENGTH = 256
+
+/** Max length of the optional human `reason` shown in the consent dialog. */
+export const PLUGIN_ASSET_REASON_MAX_LENGTH = 200
+
+/** Expected shape of an SRI-style sha256 pin: 64 lowercase hex characters. */
+export const PLUGIN_ASSET_SHA256_PATTERN = /^[0-9a-f]{64}$/
+
+/** The machine-readable asset error names, in contract order. */
+export const PLUGIN_ASSET_ERROR_NAMES = [
+	"DENIED",
+	"UNAVAILABLE",
+	"POLICY",
+] as const
+
+export type PluginAssetErrorName = (typeof PLUGIN_ASSET_ERROR_NAMES)[number]

package/src/plugin-asset.ts

@@ -0,0 +1,127 @@
+/**
+ * The plugin asset contract — the download / read / delete surface of a
+ * plugin's own "vault". The vault is a host-reserved namespace inside the
+ * plugin's installed directory (`<plugin-dir>/vault/`) that the host
+ * manages on the plugin's behalf: data lands there only through the
+ * user-consented download API, and nothing a plugin ships in its zip can
+ * ever be overwritten by downloading (see the vault-confined `dest`
+ * rules).
+ *
+ * Both sides of the plugin speak the same shapes: the server-side
+ * `ResourceAPI` (main.js hooks) and the iframe `WebPluginAPI` (render)
+ * call the same four methods with the same request/result vocabulary.
+ * All methods are gated by the manifest `download` permission and
+ * denied inside the sandbox when the manifest does not declare it.
+ *
+ * Error convention (fixed rule): **classification uses `Result`,
+ * API calls throw.** `detect` (and other classifiers) return a
+ * {@link Result}; every other API method rejects with an `Error` whose
+ * `name` carries the machine-readable code. Plugins branch on
+ * {@link isPluginAssetError} — never parse messages.
+ *
+ * Runtime limits live behind `@hoardodile/sdk-types/plugin-asset-limits`;
+ * this module exports the types and the error helpers only.
+ */
+import type { PluginAssetErrorName } from "./plugin-asset-limits.ts"
+
+export type { PluginAssetErrorName }
+
+/**
+ * A download request: the plugin declares the plaintext URL, the vault
+ * destination, and (optionally) an integrity pin plus a reason for the
+ * consent dialog. `dest` is vault-relative only — it must resolve under
+ * `<plugin-dir>/vault/` and can never reach the plugin's own bundled
+ * files (`main.js`, `index.html`, `assets/`, ...).
+ */
+export type PluginDownloadRequest = {
+	/** Absolute `http(s)` URL to fetch. Shown verbatim in the consent dialog. */
+	readonly url: string
+	/**
+	 * Vault-relative destination path (`"runtime/live2d.min.js"`). The host
+	 * resolves it inside the plugin vault and rejects absolute paths,
+	 * `..` traversal, path separators crossing segments, and reserved
+	 * names — before any network request is made.
+	 */
+	readonly dest: string
+	/**
+	 * Optional SRI-style integrity pin (64 lowercase hex chars). When
+	 * present the host verifies the downloaded bytes against it and
+	 * discards a mismatch, so a tampered or corrupted response can
+	 * never be stored.
+	 */
+	readonly sha256?: string
+	/** Optional short rationale shown in the consent dialog (plugin-authored copy). */
+	readonly reason?: string
+}
+
+/**
+ * Result of {@link PluginDownloadRequest}: the stored file's identity.
+ * `cached` is true when the destination already existed — the host
+ * answered from the vault without any dialog and without touching the
+ * network (downloads are "ensure present", never unconditional).
+ */
+export type PluginDownloadResult = {
+	/** The vault-relative destination that was resolved. */
+	readonly path: string
+	readonly sizeBytes: number
+	/** sha256 of the stored bytes (host-computed, always present). */
+	readonly sha256: string
+	/** True when the file already existed and no consent/network was needed. */
+	readonly cached: boolean
+}
+
+/**
+ * Result of {@link ResourceAPI.deleteAsset} / `WebPluginAPI.deleteAsset`.
+ * Deletion is idempotent: removing nothing is not an error.
+ */
+export type PluginAssetDeleteResult = {
+	/** True when a file was actually removed. */
+	readonly existed: boolean
+}
+
+/**
+ * Error thrown by the asset methods. The name survives both wire
+ * boundaries (worker IPC and the iframe postMessage bridge), so plugin
+ * code can branch on `err.name` without parsing messages:
+ *
+ * - `DENIED` — the user declined the consent dialog, or consent timed out.
+ * - `UNAVAILABLE` — this runtime has no consent channel (CLI, workbench,
+ *   offline mock) or the server is in read-only archive mode.
+ * - `POLICY` — the host rejected the request before downloading:
+ *   manifest lacks the `download` permission, the URL or `dest` is not
+ *   allowed, the destination is a directory, or a quota would be
+ *   exceeded. Also used for reserved-name conflicts.
+ *
+ * Transport/network failures keep their own error names (e.g. socket
+ * errors) and are not part of this vocabulary.
+ */
+export class PluginAssetError extends Error {
+	constructor(
+		readonly code: PluginAssetErrorName,
+		message: string,
+	) {
+		super(message)
+		this.name = code
+	}
+}
+
+/**
+ * Narrow an asset error to a machine-readable name. Works across the
+ * RPC boundaries because both preserve `Error.name` (the worker IPC and
+ * the iframe bridge carry the name explicitly) — the instance is often
+ * lost in transit, so the check keys on the name alone.
+ */
+export function isPluginAssetError(
+	err: unknown,
+	name: PluginAssetErrorName,
+): err is PluginAssetError {
+	return err instanceof Error && err.name === name
+}
+
+/** Build a `PluginAssetError` carrying the given machine-readable name. */
+export function pluginAssetError(
+	name: PluginAssetErrorName,
+	message: string,
+): PluginAssetError {
+	return new PluginAssetError(name, message)
+}

package/src/plugin-capabilities.ts

@@ -0,0 +1,91 @@
+/**
+ * The single permission→capability declaration: every manifest
+ * permission key, what it gates, and which runtime layers enforce it.
+ * Consumers read this table instead of hand-mirrored sets — a new
+ * permission is declared once here, and the compile-time coverage
+ * checks below make a missing declaration impossible.
+ *
+ * This module is pure TypeScript (no zod): it is type-driven off
+ * {@link PluginPermissions} and consumed by the host sandbox, the
+ * server domain and the tooling. Plugin bundles never import it.
+ */
+import type { PluginPermissions } from "./manifest.ts"
+
+export type PluginCapabilityGate = {
+	/** One-line contract description (mirrors the manifest schema docs). */
+	readonly description: string
+	/**
+	 * ResourceAPI method names gated at the sandbox RPC boundary. Absent
+	 * means the permission is enforced at the host/service layer only
+	 * (meta hooks, web routes).
+	 */
+	readonly sandboxMethods?: readonly string[]
+}
+
+/**
+ * The capability gates, keyed by the manifest permission key. The
+ * `satisfies` below fails to compile when a permission is declared on
+ * the manifest but missing here; the AssertTrue checks at the bottom
+ * cover the reverse direction.
+ */
+export const PLUGIN_CAPABILITY_GATES = {
+	sourceMeta: {
+		description: "Read/write the resource's source metadata (sourceMeta hook).",
+	},
+	searchMeta: {
+		description: "Produce and store search metadata facets (searchMeta hook).",
+	},
+	danmaku: {
+		description: "Create/list danmaku for resources this plugin renders.",
+	},
+	message: {
+		description: "Create/list messages for resources this plugin renders.",
+	},
+	imageHashes: {
+		description:
+			"Produce content hashes for duplicate detection / image similarity.",
+	},
+	container: {
+		description:
+			"List and extract archive (zip/tar/7z/…) entries; the only API surface with a write side effect.",
+		sandboxMethods: ["listContainer", "extractArchive"],
+	},
+	download: {
+		description:
+			"The plugin asset vault: user-consented downloads into the plugin's own vault/ plus the vault read/delete methods; denied by default and per-download by the user.",
+		sandboxMethods: ["download", "statAsset", "readAsset", "deleteAsset"],
+	},
+} as const satisfies Record<keyof PluginPermissions, PluginCapabilityGate>
+
+export type PluginCapabilityKey = keyof typeof PLUGIN_CAPABILITY_GATES
+
+// -- compile-time coverage --------------------------------------------------
+// Every manifest permission key is declared here and nothing more — the
+// two assertions fail the build on either drift. Exported only so
+// noUnusedLocals keeps them alive — never import.
+type AssertTrue<T extends true> = T
+export type _ManifestKeysCovered = AssertTrue<
+	keyof PluginPermissions extends keyof typeof PLUGIN_CAPABILITY_GATES
+		? true
+		: false
+>
+export type _TableKeysCovered = AssertTrue<
+	keyof typeof PLUGIN_CAPABILITY_GATES extends keyof PluginPermissions
+		? true
+		: false
+>
+
+/** Sandbox API method → capability key, derived once from the table. */
+export const CAPABILITY_BY_METHOD: ReadonlyMap<string, PluginCapabilityKey> =
+	new Map(
+		(
+			Object.entries(PLUGIN_CAPABILITY_GATES) as [
+				PluginCapabilityKey,
+				PluginCapabilityGate,
+			][]
+		).flatMap(([capability, gate]) =>
+			(gate.sandboxMethods ?? []).map(
+				(method) => [method, capability] as [string, PluginCapabilityKey],
+			),
+		),
+	)