npm - @hoardodile/sdk-types - Versions diffs - 0.1.2 → 0.1.4 - Mend

@hoardodile/sdk-types 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -557,9 +557,23 @@ type PluginDefinition<TSchema extends PluginSchema = PluginSchema> = {
      * `undefined` (or a hook error) keeps the resource's hash rows empty.
      */
     readonly imageHashes?: (api: ResourceAPI<TSchema>) => Promise<ImageHashesResult | undefined>;
+    /**
+     * Optional post-install callback, invoked by the host after a
+     * successful install or update commit (marketplace install/update and
+     * zip uploads). Runs with an **install-scoped** API: no resource is
+     * attached — the file surface answers empty and there is no
+     * `context.detect` — while the asset methods still work and stay
+     * gated by the shared consent dialog exactly like the runtime path.
+     * A throwing (or consent-denied) hook never fails the install; the
+     * plugin should treat it as best-effort and re-check at runtime.
+     *
+     * Typical use: fetch pinned runtime files into the plugin vault once,
+     * so the first preview opens without a consent dialog.
+     */
+    readonly onInstall?: (api: ResourceAPI<TSchema>) => Promise<void>;
 };
 /** Plugin hook names the host can invoke, in contract order. */
-declare const HOOK_NAMES: readonly ["detect", "sourceMeta", "searchMeta", "coverLocal", "listFiles", "imageHashes"];
+declare const HOOK_NAMES: readonly ["detect", "sourceMeta", "searchMeta", "coverLocal", "listFiles", "imageHashes", "onInstall"];
 type HookName = (typeof HOOK_NAMES)[number];
 /**
  * Freeze and return a plugin definition. Runs shape validation upfront so

package/dist/index.js CHANGED Viewed

@@ -92,7 +92,8 @@ var HOOK_NAMES = [
   "searchMeta",
   "coverLocal",
   "listFiles",
-  "imageHashes"
+  "imageHashes",
+  "onInstall"
 ];
 function isAsyncFunction(value) {
   return typeof value === "function" && value.constructor.name === "AsyncFunction";

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/plugin-asset.ts","../src/media-exts.ts","../src/plugin-definition.ts","../src/result.ts"],"names":["err"],"mappings":"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","file":"index.js","sourcesContent":["/*\n The plugin asset contract — the download / read / delete surface of a\n * plugin's own \"vault\". The vault is a host-reserved namespace inside the\n * plugin's installed directory (`<plugin-dir>/vault/`) that the host\n * manages on the plugin's behalf: data lands there only through the\n * user-consented download API, and nothing a plugin ships in its zip can\n * ever be overwritten by downloading (see the vault-confined `dest`\n * rules).\n \n Both sides of the plugin speak the same shapes: the server-side\n * `ResourceAPI` (main.js hooks) and the iframe `WebPluginAPI` (render)\n * call the same four methods with the same request/result vocabulary.\n * `download` also accepts an array of requests — one batched call is\n * ONE consent question (the dialog lists every item) and is all-or-nothing\n * (results arrive in request order; any failure commits nothing).\n * All methods are gated by the manifest `download` permission and\n * denied inside the sandbox when the manifest does not declare it.\n \n Error convention (fixed rule): *classification uses `Result`,\n API calls throw.** `detect` (and other classifiers) return a\n * {@link Result}; every other API method rejects with an `Error` whose\n * `name` carries the machine-readable code. Plugins branch on\n * {@link isPluginAssetError} — never parse messages.\n \n Runtime limits live behind `@hoardodile/sdk-types/plugin-asset-limits`;\n * this module exports the types and the error helpers only.\n /\nimport type { PluginAssetErrorName } from \"./plugin-asset-limits.ts\"\n\nexport type { PluginAssetErrorName }\n\n/\n A download request: the plugin declares the plaintext URL, the vault\n * destination, and (optionally) an integrity pin plus a reason for the\n * consent dialog. `dest` is vault-relative only — it must resolve under\n * `<plugin-dir>/vault/` and can never reach the plugin's own bundled\n * files (`main.js`, `index.html`, `assets/`, ...).\n /\nexport type PluginDownloadRequest = {\n\t/* Absolute `http(s)` URL to fetch. Shown verbatim in the consent dialog. /\n\treadonly url: string\n\t/\n\t Vault-relative destination path (`\"runtime/live2d.min.js\"`). The host\n\t * resolves it inside the plugin vault and rejects absolute paths,\n\t * `..` traversal, path separators crossing segments, and reserved\n\t * names — before any network request is made.\n\t /\n\treadonly dest: string\n\t/\n\t Optional SRI-style integrity pin (64 lowercase hex chars). When\n\t * present the host verifies the downloaded bytes against it and\n\t * discards a mismatch, so a tampered or corrupted response can\n\t * never be stored.\n\t /\n\treadonly sha256?: string\n\t/* Optional short rationale shown in the consent dialog (plugin-authored copy). /\n\treadonly reason?: string\n}\n\n/\n Result of {@link PluginDownloadRequest}: the stored file's identity.\n * `cached` is true when the destination already existed — the host\n * answered from the vault without any dialog and without touching the\n * network (downloads are \"ensure present\", never unconditional).\n /\nexport type PluginDownloadResult = {\n\t/* The vault-relative destination that was resolved. /\n\treadonly path: string\n\treadonly sizeBytes: number\n\t/* sha256 of the stored bytes (host-computed, always present). /\n\treadonly sha256: string\n\t/* True when the file already existed and no consent/network was needed. /\n\treadonly cached: boolean\n}\n\n/\n Result of {@link ResourceAPI.deleteAsset} / `WebPluginAPI.deleteAsset`.\n * Deletion is idempotent: removing nothing is not an error.\n /\nexport type PluginAssetDeleteResult = {\n\t/* True when a file was actually removed. /\n\treadonly existed: boolean\n}\n\n/\n Error thrown by the asset methods. The name survives both wire\n * boundaries (worker IPC and the iframe postMessage bridge), so plugin\n * code can branch on `err.name` without parsing messages:\n \n - `DENIED` — the user declined the consent dialog, or consent timed out.\n * - `UNAVAILABLE` — this runtime has no consent channel (CLI, workbench,\n * offline mock) or the server is in read-only archive mode.\n * - `POLICY` — the host rejected the request before downloading:\n * manifest lacks the `download` permission, the URL or `dest` is not\n * allowed, the destination is a directory, or a quota would be\n * exceeded. Also used for reserved-name conflicts.\n \n Transport/network failures keep their own error names (e.g. socket\n * errors) and are not part of this vocabulary.\n /\nexport class PluginAssetError extends Error {\n\tconstructor(\n\t\treadonly code: PluginAssetErrorName,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message)\n\t\tthis.name = code\n\t}\n}\n\n/\n Narrow an asset error to a machine-readable name. Works across the\n * RPC boundaries because both preserve `Error.name` (the worker IPC and\n * the iframe bridge carry the name explicitly) — the instance is often\n * lost in transit, so the check keys on the name alone.\n /\nexport function isPluginAssetError(\n\terr: unknown,\n\tname: PluginAssetErrorName,\n): err is PluginAssetError {\n\treturn err instanceof Error && err.name === name\n}\n\n/* Build a `PluginAssetError` carrying the given machine-readable name. /\nexport function pluginAssetError(\n\tname: PluginAssetErrorName,\n\tmessage: string,\n): PluginAssetError {\n\treturn new PluginAssetError(name, message)\n}\n","/\n Canonical media-type knowledge: the extension sets, the extension →\n * MIME table and the MIME → media-kind mapping shared by content\n * plugins, the runtime host's sniffer and the server's classification\n * pipeline.\n \n Extensions are a hint, never the verdict: `ResourceAPI.sniff`\n * reads the file's magic bytes and only falls back to the tables here\n * when the content carries no recognizable signature (text formats).\n * The sets below therefore answer \"which extensions do we expect to\n * decode\", not \"what is this file\".\n \n Lower-case, with leading dot — match the output of\n * `path.extname(name).toLowerCase()`.\n \n Adding a new extension here widens classification everywhere at\n * once. Before adding, verify:\n * - sharp can extract width/height (image)\n * - ffprobe can read width/height/duration (video)\n * - ffprobe can read the stream/format metadata (audio), and the\n * extension has an entry in `AUDIO_FFMPEG_INPUT_FORMAT`\n * - the extension has an entry in {@link EXT_MIME}\n * - the gallery plugin's transcode-required set reflects the format\n * (browser-renderable originals stay native; HEIC/TIFF need the\n * sharp preview pipeline)\n /\nexport const IMAGE_EXTS: ReadonlySet<string> = new Set([\n\t\".jpg\",\n\t\".jpeg\",\n\t\".png\",\n\t\".webp\",\n\t\".gif\",\n\t\".bmp\",\n\t\".avif\",\n\t\".heic\",\n\t\".heif\",\n\t\".tif\",\n\t\".tiff\",\n\t\".svg\",\n\t\".jp2\",\n\t\".j2k\",\n\t\".jpx\",\n])\n\nexport const VIDEO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp4\",\n\t\".webm\",\n\t\".mov\",\n\t\".mkv\",\n\t\".m4v\",\n\t\".avi\",\n\t\".3gp\",\n])\n\nexport const AUDIO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp3\",\n\t\".flac\",\n\t\".ogg\",\n\t\".m4a\",\n\t\".wav\",\n\t\".opus\",\n\t\".aac\",\n])\n\n/\n Video containers ffmpeg can demux from a forward-only pipe (matroska,\n * avi). ISO-BMFF files (.mp4/.mov/.m4v) keep their moov index at the end\n * of the file, so a stream attempt on a zip-entry source is guaranteed to\n * fail after burning a full probesize read — consumers (thumb pipeline,\n * cover probing) send those straight to the materialized entry instead.\n /\nexport const STREAMABLE_VIDEO_EXTS: ReadonlySet<string> = new Set([\n\t\".webm\",\n\t\".mkv\",\n\t\".avi\",\n])\n\n/\n ffmpeg `-f` container name for piped audio bytes (no filename hint).\n * `.opus` files are Ogg containers; `.m4a` is ISO-BMFF, demuxed by the\n * mp4 demuxer.\n /\nexport const AUDIO_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {\n\t\".mp3\": \"mp3\",\n\t\".flac\": \"flac\",\n\t\".ogg\": \"ogg\",\n\t\".opus\": \"ogg\",\n\t\".wav\": \"wav\",\n\t\".m4a\": \"mp4\",\n\t\".aac\": \"aac\",\n}\n\n/\n ffmpeg `-f` container name keyed by sniffed MIME type, for piped\n * sources that have no filename ffprobe could key off. Content-derived\n * routing is what lets a mislabelled file still demux correctly, so\n * this table — not the extension one — drives `ResourceAPI.probe`.\n \n Several spellings map to the same container because magic-byte\n * matchers and IANA disagree on the canonical name (`audio/wav` vs\n * `audio/x-wav`, `video/vnd.avi` vs `video/x-msvideo`).\n /\nexport const MIME_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {\n\t\"video/mp4\": \"mp4\",\n\t\"video/quicktime\": \"mov\",\n\t\"video/webm\": \"webm\",\n\t\"video/x-matroska\": \"matroska\",\n\t\"video/matroska\": \"matroska\",\n\t\"video/vnd.avi\": \"avi\",\n\t\"video/x-msvideo\": \"avi\",\n\t\"video/avi\": \"avi\",\n\t\"video/ogg\": \"ogg\",\n\t\"audio/mpeg\": \"mp3\",\n\t\"audio/mp3\": \"mp3\",\n\t\"audio/flac\": \"flac\",\n\t\"audio/x-flac\": \"flac\",\n\t\"audio/ogg\": \"ogg\",\n\t\"audio/opus\": \"ogg\",\n\t\"audio/vorbis\": \"ogg\",\n\t\"audio/wav\": \"wav\",\n\t\"audio/x-wav\": \"wav\",\n\t\"audio/vnd.wave\": \"wav\",\n\t\"audio/wave\": \"wav\",\n\t\"audio/mp4\": \"mp4\",\n\t\"audio/x-m4a\": \"mp4\",\n\t\"audio/aac\": \"aac\",\n\t\"video/3gpp\": \"mp4\",\n\t\"application/ogg\": \"ogg\",\n\t\"application/x-matroska\": \"matroska\",\n\t\"application/mp4\": \"mp4\",\n}\n\n/\n The audio mirror of {@link STREAMABLE_VIDEO_EXTS}: containers whose\n * headers lead the file, so ffmpeg/ffprobe can demux them from a\n * forward-only pipe. `.m4a` is ISO-BMFF with a trailing moov index, so\n * it must be probed from a materialized (seekable) entry.\n /\nexport const STREAMABLE_AUDIO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp3\",\n\t\".flac\",\n\t\".ogg\",\n\t\".opus\",\n\t\".wav\",\n\t\".aac\",\n])\n\n/\n Media families a file can belong to. `other` covers everything the\n * media pipeline does not decode (text, documents, archives, ...) — it\n * is a real answer, not a failure.\n /\nexport const MEDIA_KINDS = [\"image\", \"video\", \"audio\", \"other\"] as const\n\nexport type MediaKind = (typeof MEDIA_KINDS)[number]\n\n/\n Extension → canonical MIME type. Used as the fallback branch of\n * content sniffing: magic-byte detection covers binary media, while\n * text-based formats (`.txt`, `.md`, `.csv`, subtitles, ...) carry no\n * signature and can only be named by their extension.\n /\nexport const EXT_MIME: Readonly<Record<string, string>> = {\n\t\".jpg\": \"image/jpeg\",\n\t\".jpeg\": \"image/jpeg\",\n\t\".png\": \"image/png\",\n\t\".webp\": \"image/webp\",\n\t\".gif\": \"image/gif\",\n\t\".bmp\": \"image/bmp\",\n\t\".avif\": \"image/avif\",\n\t\".heic\": \"image/heic\",\n\t\".heif\": \"image/heif\",\n\t\".tif\": \"image/tiff\",\n\t\".tiff\": \"image/tiff\",\n\t\".jp2\": \"image/jp2\",\n\t\".j2k\": \"image/jp2\",\n\t\".jpx\": \"image/jp2\",\n\t\".mp4\": \"video/mp4\",\n\t\".m4v\": \"video/mp4\",\n\t\".webm\": \"video/webm\",\n\t\".mov\": \"video/quicktime\",\n\t\".mkv\": \"video/x-matroska\",\n\t\".avi\": \"video/vnd.avi\",\n\t\".3gp\": \"video/3gpp\",\n\t\".mp3\": \"audio/mpeg\",\n\t\".flac\": \"audio/flac\",\n\t\".ogg\": \"audio/ogg\",\n\t\".opus\": \"audio/opus\",\n\t\".m4a\": \"audio/mp4\",\n\t\".wav\": \"audio/wav\",\n\t\".aac\": \"audio/aac\",\n\t\".txt\": \"text/plain\",\n\t\".md\": \"text/markdown\",\n\t\".csv\": \"text/csv\",\n\t\".json\": \"application/json\",\n\t\".xml\": \"text/xml\",\n\t\".html\": \"text/html\",\n\t\".htm\": \"text/html\",\n\t\".svg\": \"image/svg+xml\",\n\t\".srt\": \"application/x-subrip\",\n\t\".vtt\": \"text/vtt\",\n\t\".ass\": \"text/x-ssa\",\n\t\".epub\": \"application/epub+zip\",\n\t\".pdf\": \"application/pdf\",\n\t\".zip\": \"application/zip\",\n\t\".cbz\": \"application/vnd.comicbook+zip\",\n\t\".cbr\": \"application/vnd.comicbook-rar\",\n\t\".rar\": \"application/vnd.rar\",\n\t\".7z\": \"application/x-7z-compressed\",\n\t\".cb7\": \"application/x-7z-compressed\",\n\t\".tar\": \"application/x-tar\",\n\t\".cbt\": \"application/x-tar\",\n}\n\n/\n Container MIME types whose top-level type does not describe the\n * payload. Ogg and Matroska carry audio or video, and `application/`\n says nothing either way — the values here are the common case, and\n * `ResourceAPI.probe` overrides them with the stream layout ffprobe\n * actually reports.\n /\nexport const MIME_KIND_OVERRIDES: Readonly<Record<string, MediaKind>> = {\n\t\"application/ogg\": \"audio\",\n\t\"application/x-matroska\": \"video\",\n\t\"application/mp4\": \"video\",\n}\n\n/\n Media family of a MIME type: the override table first, then the\n * top-level type. Never throws — unknown types are `other`.\n /\nexport function mimeToKind(mime: string): MediaKind {\n\tconst normalized = mime.toLowerCase()\n\tconst override = MIME_KIND_OVERRIDES[normalized]\n\tif (override !== undefined) return override\n\tif (normalized.startsWith(\"image/\")) return \"image\"\n\tif (normalized.startsWith(\"video/\")) return \"video\"\n\tif (normalized.startsWith(\"audio/\")) return \"audio\"\n\treturn \"other\"\n}\n\n/* Canonical MIME type for an extension (leading dot), or `undefined`. /\nexport function extToMime(ext: string): string \| undefined {\n\treturn EXT_MIME[ext.toLowerCase()]\n}\n","/\n The plugin definition contract — the single source of truth shared by\n * the authoring SDK (`@hoardodile/sdk-server`), the runtime host\n * (`@hoardodile/host`) and the worker sandbox. Everything here is pure\n * TypeScript with no node or DOM dependencies, so the same contract\n * serves browser-facing packages and node runtimes alike.\n /\nimport type { MediaKind } from \"./media-exts.ts\"\nimport { extToMime, mimeToKind } from \"./media-exts.ts\"\nimport type {\n\tPluginAssetDeleteResult,\n\tPluginDownloadRequest,\n\tPluginDownloadResult,\n} from \"./plugin-asset.ts\"\nimport { pluginAssetError } from \"./plugin-asset.ts\"\nimport type { ReadFileRange } from \"./read-range.ts\"\nimport type { Result } from \"./result.ts\"\n\nexport type { MediaKind }\n\n/\n Schema contract shared between server and web plugin APIs.\n * Declared once per plugin and used to type both `definePlugin` and\n * `WebPluginAPI`.\n /\nexport interface PluginSchema {\n\treadonly file?: unknown\n\treadonly sourceMeta?: unknown\n\treadonly searchMeta?: unknown\n\t/\n\t Plugin-defined payload the `detect` hook may carry on a\n\t * successful match. The host keeps the last payload and exposes it\n\t * to the plugin's other hooks as `api.context.detect` — classify\n\t * once in `detect` instead of rescanning in every hook. Declaring\n\t * this slot types the context; hooks must still handle the absent\n\t * case (`undefined`: fresh worker, or detect never matched).\n\t /\n\treadonly detect?: unknown\n\t/\n\t Plugin-defined anchor location data: the payload carried inside the\n\t * wire {@link AnchorData} envelope (see {@link anchorData}). Outgoing\n\t * anchors are typed by this slot and passed raw (e.g.\n\t * `createMessage({ anchor: { page } })`); incoming anchor data is\n\t * validated by the plugin's `decodeAnchor` (see `definePluginAPI` in\n\t * `@hoardodile/sdk-react`).\n\t /\n\treadonly anchor?: unknown\n}\n\n/\n Server plugin detection result: the shared result vocabulary, where a\n * match carries the schema's `detect` payload (when one is declared)\n * and a miss carries its reasons. Plugins may return the literal\n * `{ ok: true } as const` / `{ ok: false, reasons }` shapes directly,\n * or use `ok()`/`err({ reasons })` from the result module.\n \n `TPayload` is the plugin's declared `detect` slot — the payload\n * spread onto a match is checked against it at compile time, so a\n * classification that drifts from the schema fails to build.\n /\nexport type Detection<TPayload extends object = object> = Result<\n\tTPayload,\n\t{ readonly reasons: readonly string[] }\n>\n\n/* Structured logger scoped to a single plugin. /\nexport type Logger = {\n\tinfo(message: string, data?: Record<string, unknown>): void\n\twarn(message: string, data?: Record<string, unknown>): void\n\terror(message: string, data?: Record<string, unknown>): void\n}\n\n/* Image probe payload. /\nexport type ImageInfo = {\n\treadonly width?: number\n\treadonly height?: number\n}\n\n/* Video probe payload. /\nexport type VideoInfo = {\n\treadonly width?: number\n\treadonly height?: number\n\treadonly durationMs?: number\n}\n\n/\n Embedded container tags carried by an audio file (ID3, Vorbis\n * comments, MP4 metadata atoms). Every field is optional — untagged\n * files are normal.\n /\nexport type AudioTags = {\n\treadonly title?: string\n\treadonly artist?: string\n\treadonly album?: string\n}\n\n/\n Embedded artwork carried by an audio file (ID3 APIC, FLAC PICTURE,\n * MP4 `covr`). Its presence is the signal that the host can extract a\n * real cover; the dimensions come from the same probe, so callers can\n * pre-size the cover slot without decoding the picture.\n /\nexport type AudioCoverArt = {\n\treadonly width?: number\n\treadonly height?: number\n}\n\n/\n Audio probe payload. Any field can be absent when the container does\n * not report it.\n /\nexport type AudioInfo = {\n\treadonly durationMs?: number\n\t/* Codec name of the first audio stream, e.g. `\"mp3\"`, `\"flac\"`. /\n\treadonly codec?: string\n\t/* Container bit rate in bits per second. /\n\treadonly bitRate?: number\n\t/* Sample rate of the first audio stream, in Hz. /\n\treadonly sampleRate?: number\n\t/* Channel count of the first audio stream. /\n\treadonly channels?: number\n\t/* Present only when the file embeds artwork. /\n\treadonly coverArt?: AudioCoverArt\n\treadonly tags?: AudioTags\n}\n\n/\n What a file's bytes say it is. Produced by {@link ResourceAPI.sniff}.\n \n `source` records who answered: `\"magic\"` means the file's own\n * signature was recognized (authoritative), `\"extension\"` means the\n * content carried no signature and the filename was used instead — the\n * normal outcome for text-based formats, which have no magic bytes.\n \n `kind` is provisional for container formats that can hold either\n * audio or video (Ogg, Matroska, ISO-BMFF); {@link ResourceAPI.probe}\n * overrides it with the stream layout actually found in the file.\n /\nexport type FileType = {\n\t/* Canonical MIME type, e.g. `\"image/jpeg\"`. /\n\treadonly mime: string\n\t/* Canonical extension for {@link mime}, with leading dot. /\n\treadonly ext: string\n\treadonly kind: MediaKind\n\treadonly source: \"magic\" \| \"extension\"\n}\n\n/\n Everything one media probe pass can say about a file, discriminated\n * by the family the content really belongs to — the shape every\n * mainstream prober uses (ffprobe's `format` + `streams`, sharp's\n * `metadata()`, Tika's `MediaType`).\n \n `other` is a successful answer: the file was identified and is not\n * decodable media (text, documents, archives). `unknown` is the failure\n * branch and always carries a reason, so \"this host has no probe\n * backend\" is never confused with \"this file is not an image\":\n \n - `unsupported` — identified, but no backend decodes this format\n * - `unavailable` — the host wired no probe implementation (raw\n * directory APIs and test fixtures)\n * - `failed` — a backend ran and could not decode the bytes\n /\nexport type ProbeResult =\n\t\| ({\n\t\t\treadonly kind: \"image\"\n\t\t\treadonly mime: string\n\t\t\t/* Multi-frame source: animated GIF / WebP / APNG / AVIF. /\n\t\t\treadonly animated: boolean\n\t } & ImageInfo)\n\t\| ({ readonly kind: \"video\"; readonly mime: string } & VideoInfo)\n\t\| ({ readonly kind: \"audio\"; readonly mime: string } & AudioInfo)\n\t\| { readonly kind: \"other\"; readonly mime: string }\n\t\| {\n\t\t\treadonly kind: \"unknown\"\n\t\t\treadonly reason: \"unsupported\" \| \"unavailable\" \| \"failed\"\n\t }\n\n/\n Perceptual hash kinds the host can compute for an image file.\n * `dhash` (difference hash) and `phash` (DCT-based perceptual hash)\n * are 64-bit similarity hashes compared by Hamming distance;\n * `sha256` is an exact byte hash. Animated images hash their first\n * frame. Plugins decide which kinds to request and which files to\n * hash — the host only provides the computation.\n /\nexport const IMAGE_HASH_KINDS = [\"sha256\", \"dhash\", \"phash\"] as const\nexport type ImageHashKind = (typeof IMAGE_HASH_KINDS)[number]\n\n/\n One content hash of a resource file, produced by the plugin's\n * `imageHashes` hook. `scope` is the archive-relative file path,\n * `type` the hash kind (`sha256`/`dhash`/`phash` or a plugin-defined\n * extension), `value` the lowercase hex digest. A resource may expose\n * several hashes (per file × per kind) or none.\n /\nexport type ImageHash = {\n\treadonly scope: string\n\treadonly type: string\n\treadonly value: string\n\t/* Bit length of the hash; required for perceptual kinds. /\n\treadonly bits?: number\n}\n\n/* Result of the `imageHashes` hook: hashes per file, possibly empty. /\nexport type ImageHashesResult = {\n\treadonly hashes: readonly ImageHash[]\n}\n\n/\n One file inside a container entry (zip/tar) as listed (or extracted)\n * by the plugin API. `path` is the entry's path inside the archive;\n * dimensions are present when the host probed the entry (image\n * backends) — a listing-only result carries no dimensions.\n /\nexport type ArchiveExtractionEntry = {\n\treadonly path: string\n\treadonly sizeBytes: number\n\treadonly kind: MediaKind\n\treadonly width?: number\n\treadonly height?: number\n\treadonly animated?: boolean\n}\n\n/\n A container listing without materialization — the cheap counterpart of\n * {@link ResourceAPI.extractArchive}. Carries entry names, sizes and\n * kinds only; no dimensions (probing those requires the bytes).\n /\nexport type ContainerListing = {\n\treadonly entries: readonly ArchiveExtractionEntry[]\n}\n\n/\n Result of {@link ResourceAPI.extractArchive}: the materialized\n * entries of a container entry. A completed extraction is marked by the\n * host's `index.json` manifest; extraction always writes the cache (the\n * host's `local/cache` is derived data, writable in every view mode).\n /\nexport type ArchiveExtraction = {\n\treadonly entries: readonly ArchiveExtractionEntry[]\n}\n\n/\n Resource-scoped API available to every plugin hook. All paths are\n * relative to the resource's source directory; the host resolves\n * absolute paths transparently.\n \n `TSchema` types the injected session context (`context.detect`); the\n * default keeps the API compatible with code that never reads it.\n /\nexport type ResourceAPI<TSchema extends PluginSchema = PluginSchema> = {\n\t/* Write an informational log entry. /\n\treadonly logInfo: (message: string, data?: Record<string, unknown>) => void\n\t/* Write a warning log entry. /\n\treadonly logWarn: (message: string, data?: Record<string, unknown>) => void\n\t/* Write an error log entry. /\n\treadonly logError: (message: string, data?: Record<string, unknown>) => void\n\t/\n\t List all regular-file names (flat list), in canonical display\n\t * order: the resource's explicit upload order when one exists (the\n\t * host's `.order` manifest), the natural name sort otherwise.\n\t * Plugins that need their own ordering should sort explicitly.\n\t \n\t This is the raw name list — the `listFiles` hook of the plugin\n\t * definition turns it into typed file entries.\n\t /\n\treadonly listFileNames: () => Promise<readonly string[]>\n\t/\n\t Read a regular file relative to the resource root.\n\t \n\t Without `range` the whole file is returned; hosts may reject\n\t * oversized full reads — pass a range (or use `readFileChunks` from\n\t * `@hoardodile/sdk-server/helpers`) for large files.\n\t \n\t Container addressing: a path of the form `outer!inner` reads the\n\t * file inside a zip/tar entry (e.g. `manga.cbz!Chapter 1/001.jpg`)\n\t * — the host streams the decompressed bytes. When `outer` is not a\n\t * container, or the inner entry is absent, the whole path is treated\n\t * as a literal filename.\n\t /\n\treadonly readFile: (\n\t\tpath: string,\n\t\trange?: ReadFileRange,\n\t) => Promise<Uint8Array>\n\t/\n\t Return the byte size of `path` without reading the file contents.\n\t * Resolves to `undefined` when the file does not exist or the artifact\n\t * is not yet committed. Supports container addressing (`outer!inner`).\n\t /\n\treadonly statFile: (\n\t\tpath: string,\n\t) => Promise<{ readonly sizeBytes: number } \| undefined>\n\t/\n\t Batch {@link statFile}: resolves every path in one host round-trip\n\t * (positions preserved). Prefer this over a per-file fan-out of\n\t * `statFile` when statting a whole archive — one RPC instead of N.\n\t /\n\treadonly statFiles: (\n\t\tpaths: readonly string[],\n\t) => Promise<readonly ({ readonly sizeBytes: number } \| undefined)[]>\n\t/\n\t Identify the file at `path` from its content: magic-byte\n\t * detection, falling back to the extension only for formats that\n\t * carry no signature (text, subtitles). Resolves to `undefined` when\n\t * neither can name the file. Supports container addressing.\n\t \n\t This is the cheap call — it reads a small header window, never\n\t * decodes. Use it to route work; use {@link probe} when you need\n\t * dimensions, duration or stream details.\n\t /\n\treadonly sniff: (path: string) => Promise<FileType \| undefined>\n\t/\n\t Decode the media metadata of `path` in one pass, routed by\n\t * {@link sniff} rather than by the filename: images resolve through\n\t * sharp, audio and video through ffprobe (which also settles\n\t * ambiguous containers — an `.ogg` holding only audio streams comes\n\t * back as `kind: \"audio\"`). Supports container addressing.\n\t \n\t Always resolves, never rejects. Non-media files answer\n\t * `{ kind: \"other\" }`; the `unknown` branch carries a `reason` that\n\t * distinguishes \"no backend wired\" (`unavailable`, what raw\n\t * directory APIs and fixtures return) from a real decode failure.\n\t /\n\treadonly probe: (path: string) => Promise<ProbeResult>\n\t/\n\t Stream-hash the file at `path` (any file kind). Rejects when the\n\t * file is missing or the read fails; the host streams the entry so\n\t * arbitrarily large files are safe. Supports container addressing.\n\t /\n\treadonly hashBytes: (path: string, algo: \"md5\" \| \"sha256\") => Promise<string>\n\t/\n\t Compute the requested hashes of the image at `path` in one pass:\n\t * `sha256` from the raw bytes, `dhash`/`phash` from a decoded\n\t * grayscale rendition (animated images use their first frame).\n\t * Resolves to `undefined` when the file is not a decodable image;\n\t * `kinds` names a subset of {@link IMAGE_HASH_KINDS} and the result\n\t * carries exactly those keys. Supports container addressing.\n\t /\n\treadonly computeImageHashes: (\n\t\tpath: string,\n\t\tkinds: readonly ImageHashKind[],\n\t) => Promise<Readonly<Record<ImageHashKind, string>> \| undefined>\n\t/\n\t List the file entries of a container entry (zip/tar) without\n\t * materializing anything — the cheap call for metadata-only needs\n\t * (detect, card counts). Rejects when `filename` is not a supported\n\t * container.\n\t /\n\treadonly listContainer: (filename: string) => Promise<ContainerListing>\n\t/\n\t Materialize the contents of a container entry (zip/tar) into the\n\t * host's extraction cache so the browser can serve the inner files\n\t * over plain URLs. `filename` is a literal container entry — the\n\t * cache holds one directory per archive with the inner paths\n\t * preserved, plus a completion manifest.\n\t \n\t Idempotent: an already-materialized archive re-lists from the\n\t * manifest without re-extracting. Rejects when the entry is not a\n\t * supported container, exceeds the host's byte/entry budgets, or\n\t * when this host wires no extraction cache (test fixtures, raw\n\t * directory APIs).\n\t /\n\treadonly extractArchive: (filename: string) => Promise<ArchiveExtraction>\n\t/\n\t Ensure remote assets exist in the plugin's own vault — one call with\n\t * one request, or one call with an array of requests. When `dest` is\n\t * already present the host answers `cached: true` without any dialog\n\t * and without touching the network; otherwise the host asks the user\n\t * (the web app shows the shared consent dialog with the URLs\n\t * verbatim) and downloads on approval.\n\t \n\t An array is ONE consent question for the WHOLE batch (the dialog\n\t * lists every item) and is all-or-nothing: any failure discards every\n\t * staged file and rejects with the first error, so nothing is\n\t * partially committed. Results arrive in request order with `cached`\n\t * items keeping their positions. Cap: {@link PLUGIN_ASSET_BATCH_MAX_ITEMS}\n\t * items per call. The file always lands inside\n\t * `<plugin-dir>/vault/` — `dest` is vault-relative and can never\n\t * reach the plugin's bundled files.\n\t \n\t Gated by the manifest `download` permission; rejections carry a\n\t * machine-readable {@link PluginAssetErrorName} in `err.name`\n\t * (`DENIED` / `UNAVAILABLE` / `POLICY`).\n\t /\n\treadonly download: ((\n\t\trequest: PluginDownloadRequest,\n\t) => Promise<PluginDownloadResult>) &\n\t\t((\n\t\t\trequests: readonly PluginDownloadRequest[],\n\t\t) => Promise<readonly PluginDownloadResult[]>)\n\t/\n\t Byte size of a vault file, or `undefined` when absent. The cheap\n\t * presence check on top of which `download` resolves cached hits.\n\t /\n\treadonly statAsset: (\n\t\tpath: string,\n\t) => Promise<{ readonly sizeBytes: number } \| undefined>\n\t/* Read a vault file's bytes (bounded by the same cap as {@link readFile}). /\n\treadonly readAsset: (path: string) => Promise<Uint8Array>\n\t/\n\t Remove a vault file; idempotent (absent files answer\n\t * `{ existed: false }`). The plugin decides the vault's own\n\t * lifecycle — e.g. cleaning stale layouts after a plugin update.\n\t * No user consent is required: nothing leaves the host. Directories\n\t * and paths outside the vault are rejected (`POLICY`).\n\t /\n\treadonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>\n\t/\n\t Session context injected by the host. `detect` carries the payload\n\t * the plugin's `detect` hook returned on its last successful match\n\t * (worker-session scope): the one-pass classification every other\n\t * hook can build on. `undefined` when detect has not matched in this\n\t * session — a fresh worker — so hooks must always handle the absent\n\t * case by re-deriving.\n\t /\n\treadonly context: { readonly detect: TSchema[\"detect\"] \| undefined }\n}\n\n/\n Declarative description of a content plugin. Plugins export an instance\n * of this shape as their default export; the host injects the resource\n * API at call time and never invokes a factory function.\n /\nexport type PluginDefinition<TSchema extends PluginSchema = PluginSchema> = {\n\t/\n\t Detect whether this plugin applies to the current resource. A\n\t * successful match may carry a payload — `ok({ ...shape })` — which\n\t * the host keeps and exposes to the other hooks as\n\t * `api.context.detect`. The payload is checked against the schema's\n\t * `detect` slot (when one is declared).\n\t /\n\treadonly detect: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<Detection<TSchema[\"detect\"] & object>>\n\t/* Optional source metadata builder. /\n\treadonly sourceMeta?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<TSchema[\"sourceMeta\"] \| undefined>\n\t/* Optional search metadata builder. /\n\treadonly searchMeta?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<TSchema[\"searchMeta\"] \| undefined>\n\t/* Optional local cover source resolver. /\n\treadonly coverLocal?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<string \| undefined>\n\t/\n\t Optional custom file list builder. Results are cached verbatim in a\n\t * sidecar. When absent the host falls back to a bare list of source\n\t * filenames.\n\t /\n\treadonly listFiles?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<readonly TSchema[\"file\"][]>\n\t/\n\t Optional content hashes for duplicate detection and image\n\t * similarity. The plugin decides the policy — which files to hash\n\t * and which kinds — by calling the API's hash primitives; a plugin\n\t * facing image-less resources simply omits this hook. Returning\n\t * `undefined` (or a hook error) keeps the resource's hash rows empty.\n\t /\n\treadonly imageHashes?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<ImageHashesResult \| undefined>\n}\n\n/* Plugin hook names the host can invoke, in contract order. /\nexport const HOOK_NAMES = [\n\t\"detect\",\n\t\"sourceMeta\",\n\t\"searchMeta\",\n\t\"coverLocal\",\n\t\"listFiles\",\n\t\"imageHashes\",\n] as const\n\nexport type HookName = (typeof HOOK_NAMES)[number]\n\nfunction isAsyncFunction(value: unknown): boolean {\n\treturn (\n\t\ttypeof value === \"function\" && value.constructor.name === \"AsyncFunction\"\n\t)\n}\n\n/\n Freeze and return a plugin definition. Runs shape validation upfront so\n * a malformed plugin fails at load time with a friendly message instead\n * of misbehaving at hook time.\n /\nexport function definePlugin<TSchema extends PluginSchema = PluginSchema>(\n\tdefinition: PluginDefinition<TSchema>,\n): PluginDefinition<TSchema> {\n\tassertPluginShape(definition)\n\treturn Object.freeze({ ...definition })\n}\n\n/\n Validate that a value satisfies the structural contract of a\n * {@link PluginDefinition}: only known hooks, all hooks async functions,\n * `detect` required. Does NOT exercise behaviour.\n /\nexport function assertPluginShape(\n\tvalue: unknown,\n): asserts value is PluginDefinition {\n\tif (typeof value !== \"object\" \|\| value === null) {\n\t\tthrow new Error(\"PluginDefinition: expected an object with hook functions\")\n\t}\n\n\tconst definition = value as Record<string, unknown>\n\n\tconst knownHooks = new Set<string>(HOOK_NAMES)\n\tconst unknown = Object.keys(definition).filter((key) => !knownHooks.has(key))\n\tif (unknown.length > 0) {\n\t\tthrow new Error(\n\t\t\t`PluginDefinition: unknown hook(s) ${unknown.map((k) => `\"${k}\"`).join(\", \")} — expected one of: ${HOOK_NAMES.join(\", \")}`,\n\t\t)\n\t}\n\n\tfor (const hook of HOOK_NAMES) {\n\t\tconst entry = definition[hook]\n\t\tif (entry === undefined) {\n\t\t\tif (hook === \"detect\") {\n\t\t\t\tthrow new Error(\"PluginDefinition: missing detect()\")\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (!isAsyncFunction(entry)) {\n\t\t\tconst kind =\n\t\t\t\ttypeof entry === \"function\" ? \"a synchronous function\" : typeof entry\n\t\t\tthrow new Error(\n\t\t\t\t`PluginDefinition: \"${hook}\" must be an async function (got ${kind}) — hooks may do heavy work and the host awaits every hook, so declare it with \\`async\\`.`,\n\t\t\t)\n\t\t}\n\t}\n}\n\n/\n Convenience wrapper that builds a failing plugin definition. Used by\n * the host when a plugin directory is missing or its main.js cannot be\n * loaded.\n /\nexport function createFailingPlugin(\n\treasons: readonly string[],\n): PluginDefinition {\n\treturn definePlugin({\n\t\tdetect: async () => ({ ok: false, reasons }),\n\t})\n}\n\n/* Type guard for the success branch of a {@link Detection}. /\nexport function isDetected(\n\tdetection: Detection,\n): detection is { readonly ok: true } {\n\treturn detection.ok\n}\n\n/* Type guard for the failure branch of a {@link Detection}. /\nexport function isMissed(\n\tdetection: Detection,\n): detection is { readonly ok: false; readonly reasons: readonly string[] } {\n\treturn !detection.ok\n}\n\n/* Declarative configuration for a {@link ResourceAPI} fixture. /\nexport type ResourceAPIFixtureConfig<\n\tTSchema extends PluginSchema = PluginSchema,\n> = {\n\t/* File names returned by `listFileNames`. /\n\treadonly files?: readonly string[]\n\t/* File contents returned by `readFile`. /\n\treadonly contents?: Readonly<Record<string, string \| Uint8Array>>\n\t/\n\t `sniff` results keyed by file path — `{ \"a.jpg\": … }` matches only\n\t * that file, keys starting with a dot match by extension suffix\n\t * (`{ \".mp4\": … }` applies to every .mp4 file, longest key wins),\n\t * and `{ \"\": … }` matches every path (the usual way to express a\n\t * default). Unconfigured paths fall back to the extension table,\n\t * exactly like the host's extension branch.\n\t /\n\treadonly types?: Readonly<Record<string, FileType \| undefined>>\n\t/\n\t `probe` results keyed by file path (same matching rules as\n\t * {@link types}). Unconfigured paths mirror the host's routing:\n\t * identified non-media answers `{ kind: \"other\" }`, identified media\n\t * answers `{ kind: \"unknown\", reason: \"unavailable\" }` — the fixture\n\t * decodes nothing, so a hook that needs real dimensions belongs in a\n\t * sandbox test instead.\n\t /\n\treadonly probes?: Readonly<Record<string, ProbeResult \| undefined>>\n\t/* Stat results. A plain value is used as the default for all paths. /\n\treadonly stats?:\n\t\t\| Readonly<Record<string, { readonly sizeBytes: number } \| undefined>>\n\t\t\| { readonly sizeBytes: number }\n\t\t\| undefined\n\t/* `hashBytes` results by path; a plain string is used for all paths. /\n\treadonly byteHashes?: Readonly<Record<string, string>> \| string\n\t/\n\t `computeImageHashes` results by path. A plain record is used as the\n\t * default for all paths; absent paths resolve to `undefined`.\n\t /\n\treadonly imageHashes?:\n\t\t\| Readonly<Record<string, ImageHashesResult>>\n\t\t\| ImageHashesResult\n\t/\n\t `listContainer` results keyed by the archive filename. Absent\n\t * names reject, mirroring the host's \"not a supported archive\" error.\n\t /\n\treadonly containerListings?: Readonly<Record<string, ContainerListing>>\n\t/\n\t `extractArchive` results keyed by the archive filename. Absent\n\t * names reject, mirroring the host's \"not a supported archive\" error.\n\t /\n\treadonly extractions?: Readonly<Record<string, ArchiveExtraction>>\n\t/\n\t Vault file contents keyed by vault-relative path, backing\n\t * `statAsset` / `readAsset` / `deleteAsset` in the fixture.\n\t /\n\treadonly assetFiles?: Readonly<Record<string, string \| Uint8Array>>\n\t/\n\t Handler for `download` (single request or batch of requests, typed\n\t * as the union — the fixture returns the matching shape). Absent\n\t * means the hosted runtime has no consent channel — `download`\n\t * rejects with `UNAVAILABLE`, exactly like the CLI, workbench and\n\t * offline mock hosts.\n\t /\n\treadonly downloadHandler?: (\n\t\trequest: PluginDownloadRequest \| readonly PluginDownloadRequest[],\n\t) => Promise<PluginDownloadResult \| readonly PluginDownloadResult[]>\n\t/\n\t Container addressing for the fixture: maps a virtual path\n\t * (`outer!inner`) to stat/sniff/probe results, so hooks that browse\n\t * inside archives can be tested without real archives. Matching rules\n\t * mirror {@link types}: exact path keys, dot fragments by suffix,\n\t * `{ \"\": … }` as the default.\n\t /\n\treadonly virtualEntries?: Readonly<Record<string, ArchiveExtractionEntry>>\n\t/\n\t Session context handed to hooks as `api.context` — mirrors the\n\t * host injecting the payload of a prior successful `detect`. Typed\n\t * by the schema generic when one is supplied.\n\t /\n\treadonly context?: { readonly detect?: TSchema[\"detect\"] }\n}\n\nfunction resolveKeyed<T>(\n\tpath: string,\n\ttable: Readonly<Record<string, T \| undefined>> \| undefined,\n): T \| undefined {\n\tif (table === undefined) return undefined\n\t// Keys match the path exactly, except keys that start with a dot —\n\t// those are extension fragments matching any path ending with them\n\t// (`.mp4` applies to every .mp4 file). The longest fragment wins so\n\t// a shared default is never shadowed; the empty key `\"\"` is the\n\t// catch-all default. Plain-name keys never match by substring, so\n\t// `\"a.jpg\"` cannot hijack `\"ba.jpg\"`.\n\tif (Object.hasOwn(table, path)) return table[path]\n\tlet bestKey: string \| undefined\n\tlet bestLen = -1\n\tfor (const key of Object.keys(table)) {\n\t\tif (key.length > bestLen && key.startsWith(\".\") && path.endsWith(key)) {\n\t\t\tbestKey = key\n\t\t\tbestLen = key.length\n\t\t}\n\t}\n\tif (bestKey !== undefined) return table[bestKey]\n\treturn table[\"\"]\n}\n\n/* Lower-cased extension from the last dot, or `\"\"` when there is none. /\nfunction lastExt(path: string): string {\n\tconst dot = path.lastIndexOf(\".\")\n\treturn dot === -1 ? \"\" : path.slice(dot).toLowerCase()\n}\n\n/\n Identify a file from its name alone: the extension branch of content\n * sniffing, exposed on its own because it is also the honest answer for\n * formats that carry no signature, and the shape test doubles need when\n * standing in for a real {@link ResourceAPI}.\n /\nexport function fileTypeFromName(path: string): FileType \| undefined {\n\tconst ext = lastExt(path)\n\tconst mime = extToMime(ext)\n\tif (mime === undefined) return undefined\n\treturn { mime, ext, kind: mimeToKind(mime), source: \"extension\" }\n}\n\nfunction resolveValue<T>(\n\tpath: string,\n\tvalue: Readonly<Record<string, T \| undefined>> \| T \| undefined,\n\tdefaultValue: T \| undefined,\n): T \| undefined {\n\tif (value === undefined \|\| value === null) return defaultValue\n\tif (typeof value !== \"object\" \|\| Array.isArray(value)) return value\n\t// Matching rules mirror {@link resolveKeyed}: exact keys, dot\n\t// fragments by suffix (longest wins), empty-key default.\n\tconst table = value as Readonly<Record<string, T \| undefined>>\n\tif (Object.hasOwn(table, path)) return table[path]\n\tlet bestKey: string \| undefined\n\tlet bestLen = -1\n\tfor (const key of Object.keys(table)) {\n\t\tif (key.length > bestLen && key.startsWith(\".\") && path.endsWith(key)) {\n\t\t\tbestKey = key\n\t\t\tbestLen = key.length\n\t\t}\n\t}\n\tif (bestKey !== undefined) return table[bestKey]\n\treturn table[\"\"] ?? defaultValue\n}\n\nfunction virtualStat(\n\tpath: string,\n\ttable:\n\t\t\| Readonly<Record<string, ArchiveExtractionEntry \| undefined>>\n\t\t\| undefined,\n): { readonly sizeBytes: number } \| undefined {\n\tconst entry = resolveKeyed(path, table)\n\treturn entry === undefined ? undefined : { sizeBytes: entry.sizeBytes }\n}\n\nfunction virtualType(\n\tpath: string,\n\ttable:\n\t\t\| Readonly<Record<string, ArchiveExtractionEntry \| undefined>>\n\t\t\| undefined,\n): FileType \| undefined {\n\tif (resolveKeyed(path, table) === undefined) return undefined\n\treturn fileTypeFromName(path.slice(path.lastIndexOf(\"!\") + 1))\n}\n\n/\n Create a mutable {@link ResourceAPI} fixture driven by a declarative\n * config. No filesystem involved — the standard way to unit-test plugin\n * hooks.\n \n Pass the plugin's schema as the generic\n * (`createResourceAPIFixture<MySchema>()`) so the returned api carries\n * the typed session context — the same shape schema-typed hooks receive\n * from the host.\n /\nexport function createResourceAPIFixture<\n\tTSchema extends PluginSchema = PluginSchema,\n>(\n\tinitialConfig: ResourceAPIFixtureConfig<TSchema> = {},\n): {\n\treadonly api: ResourceAPI<TSchema>\n\treadonly setConfig: (next: ResourceAPIFixtureConfig<TSchema>) => void\n} {\n\tlet config: ResourceAPIFixtureConfig<TSchema> = initialConfig\n\n\tfunction setConfig(next: ResourceAPIFixtureConfig<TSchema>): void {\n\t\tconfig = next\n\t}\n\n\tconst api: ResourceAPI<TSchema> = {\n\t\tlogInfo() {},\n\t\tlogWarn() {},\n\t\tlogError() {},\n\t\tcontext: { detect: config.context?.detect },\n\t\tasync listFileNames() {\n\t\t\treturn config.files ?? []\n\t\t},\n\t\tasync readFile(path, range) {\n\t\t\tconst content = config.contents?.[path]\n\t\t\tif (content === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no content for \"${path}\"`)\n\t\t\t}\n\t\t\tconst bytes =\n\t\t\t\ttypeof content === \"string\"\n\t\t\t\t\t? new TextEncoder().encode(content)\n\t\t\t\t\t: content\n\t\t\tif (range === undefined) return bytes\n\t\t\t// Mirrors host semantics: the range is clamped to the content size.\n\t\t\treturn bytes.slice(range.start ?? 0, range.end)\n\t\t},\n\t\tasync statFile(path) {\n\t\t\treturn (\n\t\t\t\tresolveValue(path, config.stats, undefined) ??\n\t\t\t\tvirtualStat(path, config.virtualEntries)\n\t\t\t)\n\t\t},\n\t\tasync statFiles(paths) {\n\t\t\treturn Promise.all(\n\t\t\t\tpaths.map(\n\t\t\t\t\t(path) =>\n\t\t\t\t\t\tresolveValue(path, config.stats, undefined) ??\n\t\t\t\t\t\tvirtualStat(path, config.virtualEntries),\n\t\t\t\t),\n\t\t\t)\n\t\t},\n\t\tasync sniff(path) {\n\t\t\treturn (\n\t\t\t\tresolveKeyed(path, config.types) ??\n\t\t\t\tfileTypeFromName(path) ??\n\t\t\t\tvirtualType(path, config.virtualEntries)\n\t\t\t)\n\t\t},\n\t\tasync probe(path) {\n\t\t\tconst configured = resolveKeyed(path, config.probes)\n\t\t\tif (configured !== undefined) return configured\n\t\t\t// Unconfigured paths mirror the host's own routing: a file the\n\t\t\t// fixture cannot identify is unsupported, an identified\n\t\t\t// non-media file answers `other`, and identified media needs a\n\t\t\t// real decode the fixture has no backend for.\n\t\t\tconst type =\n\t\t\t\tresolveKeyed(path, config.types) ??\n\t\t\t\tfileTypeFromName(path) ??\n\t\t\t\tvirtualType(path, config.virtualEntries)\n\t\t\tif (type === undefined) return { kind: \"unknown\", reason: \"unsupported\" }\n\t\t\tif (type.kind === \"other\") return { kind: \"other\", mime: type.mime }\n\t\t\tconst virtual = resolveKeyed(path, config.virtualEntries)\n\t\t\tif (virtual !== undefined && type.kind === \"image\") {\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"image\",\n\t\t\t\t\tmime: type.mime,\n\t\t\t\t\twidth: virtual.width,\n\t\t\t\t\theight: virtual.height,\n\t\t\t\t\tanimated: virtual.animated ?? false,\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { kind: \"unknown\", reason: \"unavailable\" }\n\t\t},\n\t\tasync hashBytes(path) {\n\t\t\tconst value = resolveValue(path, config.byteHashes, undefined)\n\t\t\tif (value === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no byte hash for \"${path}\"`)\n\t\t\t}\n\t\t\treturn value\n\t\t},\n\t\tasync computeImageHashes(path, kinds) {\n\t\t\tconst result = resolveValue(path, config.imageHashes, undefined)\n\t\t\tif (result === undefined) return undefined\n\t\t\tconst hashes: Record<string, string> = {}\n\t\t\tfor (const entry of result.hashes) {\n\t\t\t\tif ((kinds as readonly string[]).includes(entry.type)) {\n\t\t\t\t\thashes[entry.type] = entry.value\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn hashes as Record<ImageHashKind, string>\n\t\t},\n\t\tasync extractArchive(filename) {\n\t\t\tconst configured = config.extractions?.[filename]\n\t\t\tif (configured === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`ResourceAPIFixture: no extraction configured for \"${filename}\"`,\n\t\t\t\t)\n\t\t\t}\n\t\t\treturn configured\n\t\t},\n\t\tasync listContainer(filename) {\n\t\t\tconst configured = config.containerListings?.[filename]\n\t\t\tif (configured === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`ResourceAPIFixture: no container listing configured for \"${filename}\"`,\n\t\t\t\t)\n\t\t\t}\n\t\t\treturn configured\n\t\t},\n\t\tdownload: (async (\n\t\t\trequest: PluginDownloadRequest \| readonly PluginDownloadRequest[],\n\t\t) => {\n\t\t\tif (config.downloadHandler === undefined) {\n\t\t\t\tthrow pluginAssetError(\n\t\t\t\t\t\"UNAVAILABLE\",\n\t\t\t\t\t\"ResourceAPIFixture: no download handler configured\",\n\t\t\t\t)\n\t\t\t}\n\t\t\tconst result = await config.downloadHandler(request)\n\t\t\t// Mirror the real host: batch in → batch out, single in →\n\t\t\t// single out.\n\t\t\tif (Array.isArray(request)) {\n\t\t\t\treturn Array.isArray(result) ? result : [result]\n\t\t\t}\n\t\t\treturn Array.isArray(result) ? (result[0] ?? result) : result\n\t\t}) as ResourceAPI<TSchema>[\"download\"],\n\t\tasync statAsset(path) {\n\t\t\tconst content = resolveValue(path, config.assetFiles, undefined)\n\t\t\tif (content === undefined) return undefined\n\t\t\treturn { sizeBytes: fixtureContentBytes(content).byteLength }\n\t\t},\n\t\tasync readAsset(path) {\n\t\t\tconst content = resolveValue(path, config.assetFiles, undefined)\n\t\t\tif (content === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no vault file \"${path}\"`)\n\t\t\t}\n\t\t\treturn fixtureContentBytes(content)\n\t\t},\n\t\tasync deleteAsset(path) {\n\t\t\tconst table = config.assetFiles\n\t\t\tif (table === undefined \|\| !Object.hasOwn(table, path)) {\n\t\t\t\treturn { existed: false }\n\t\t\t}\n\t\t\t// Fixture config is immutable in spirit — a delete is simulated\n\t\t\t// by copying with the entry removed, so the next call sees it gone.\n\t\t\tconst next: Record<string, string \| Uint8Array> = {}\n\t\t\tfor (const [key, value] of Object.entries(table)) {\n\t\t\t\tif (key !== path) next[key] = value\n\t\t\t}\n\t\t\tconfig = { ...config, assetFiles: next }\n\t\t\treturn { existed: true }\n\t\t},\n\t}\n\n\treturn { api, setConfig }\n}\n\n/* Convert a fixture content entry (string or bytes) to `Uint8Array`. /\nfunction fixtureContentBytes(content: string \| Uint8Array): Uint8Array {\n\treturn typeof content === \"string\"\n\t\t? new TextEncoder().encode(content)\n\t\t: content\n}\n\n/* Return a minimal {@link Logger} for tests. /\nexport function stubLogger(overrides?: Partial<Logger>): Logger {\n\treturn {\n\t\tinfo() {},\n\t\twarn() {},\n\t\terror() {},\n\t\t...overrides,\n\t}\n}\n","/\n Shared `ok: true/false` result vocabulary (Rust's `Result` in spirit,\n * spread payloads in shape): every site that answers \"did it work?\" —\n * detections, parses, validations, benchmark runs — uses one type\n * family, one pair of constructors and one pair of guards instead of\n * hand-rolling its own union.\n \n The payloads are spread onto the marker rather than carried in a\n * `value`/`error` channel: `ok({ start, end })` is literally\n * `{ ok: true, start, end }`. This keeps every existing consumer's\n * field access (`r.start`, `r.code`, `r.failure`) and every `toEqual`\n * assertion working unchanged, and lets the plugin-facing `{ ok: true }`\n * literal stay the contract.\n /\nexport type Ok<TPayload extends object = object> = {\n\treadonly ok: true\n} & TPayload\nexport type Err<TPayload extends object = object> = {\n\treadonly ok: false\n} & TPayload\nexport type Result<TOk extends object = object, TErr extends object = object> =\n\t\| Ok<TOk>\n\t\| Err<TErr>\n\n/\n Build the success variant; `ok()` alone yields `{ ok: true }`. The\n * cast is the constructor boundary: the runtime value is exactly\n * `{ ok: true, ...payload }`, which the generic spread cannot prove.\n /\nexport function ok<TPayload extends object = object>(\n\tpayload?: TPayload,\n): Ok<TPayload> {\n\treturn { ok: true, ...payload } as Ok<TPayload>\n}\n\n/\n Build the failure variant; `err()` alone yields `{ ok: false }`. See\n * {@link ok} for the constructor-boundary cast.\n /\nexport function err<TPayload extends object = object>(\n\tpayload?: TPayload,\n): Err<TPayload> {\n\treturn { ok: false, ...payload } as Err<TPayload>\n}\n\n/* Narrow a result to its success variant. /\nexport function isOk<TOk extends object, TErr extends object>(\n\tresult: Result<TOk, TErr>,\n): result is Ok<TOk> {\n\treturn result.ok === true\n}\n\n/* Narrow a result to its failure variant. /\nexport function isErr<TOk extends object, TErr extends object>(\n\tresult: Result<TOk, TErr>,\n): result is Err<TErr> {\n\treturn result.ok === false\n}\n\n/\n Destructure a result through one of two handlers — the pattern-match\n * combinator. Both handlers must produce `R`; the chosen one receives\n * the spread payload of its variant.\n */\nexport function matchResult<TOk extends object, TErr extends object, R>(\n\tresult: Result<TOk, TErr>,\n\thandlers: {\n\t\treadonly ok: (payload: Ok<TOk>) => R\n\t\treadonly err: (payload: Err<TErr>) => R\n\t},\n): R {\n\treturn isOk(result) ? handlers.ok(result) : handlers.err(result)\n}\n"]}
1	+ {"version":3,"sources":["../src/plugin-asset.ts","../src/media-exts.ts","../src/plugin-definition.ts","../src/result.ts"],"names":["err"],"mappings":"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","file":"index.js","sourcesContent":["/*\n The plugin asset contract — the download / read / delete surface of a\n * plugin's own \"vault\". The vault is a host-reserved namespace inside the\n * plugin's installed directory (`<plugin-dir>/vault/`) that the host\n * manages on the plugin's behalf: data lands there only through the\n * user-consented download API, and nothing a plugin ships in its zip can\n * ever be overwritten by downloading (see the vault-confined `dest`\n * rules).\n \n Both sides of the plugin speak the same shapes: the server-side\n * `ResourceAPI` (main.js hooks) and the iframe `WebPluginAPI` (render)\n * call the same four methods with the same request/result vocabulary.\n * `download` also accepts an array of requests — one batched call is\n * ONE consent question (the dialog lists every item) and is all-or-nothing\n * (results arrive in request order; any failure commits nothing).\n * All methods are gated by the manifest `download` permission and\n * denied inside the sandbox when the manifest does not declare it.\n \n Error convention (fixed rule): *classification uses `Result`,\n API calls throw.** `detect` (and other classifiers) return a\n * {@link Result}; every other API method rejects with an `Error` whose\n * `name` carries the machine-readable code. Plugins branch on\n * {@link isPluginAssetError} — never parse messages.\n \n Runtime limits live behind `@hoardodile/sdk-types/plugin-asset-limits`;\n * this module exports the types and the error helpers only.\n /\nimport type { PluginAssetErrorName } from \"./plugin-asset-limits.ts\"\n\nexport type { PluginAssetErrorName }\n\n/\n A download request: the plugin declares the plaintext URL, the vault\n * destination, and (optionally) an integrity pin plus a reason for the\n * consent dialog. `dest` is vault-relative only — it must resolve under\n * `<plugin-dir>/vault/` and can never reach the plugin's own bundled\n * files (`main.js`, `index.html`, `assets/`, ...).\n /\nexport type PluginDownloadRequest = {\n\t/* Absolute `http(s)` URL to fetch. Shown verbatim in the consent dialog. /\n\treadonly url: string\n\t/\n\t Vault-relative destination path (`\"runtime/live2d.min.js\"`). The host\n\t * resolves it inside the plugin vault and rejects absolute paths,\n\t * `..` traversal, path separators crossing segments, and reserved\n\t * names — before any network request is made.\n\t /\n\treadonly dest: string\n\t/\n\t Optional SRI-style integrity pin (64 lowercase hex chars). When\n\t * present the host verifies the downloaded bytes against it and\n\t * discards a mismatch, so a tampered or corrupted response can\n\t * never be stored.\n\t /\n\treadonly sha256?: string\n\t/* Optional short rationale shown in the consent dialog (plugin-authored copy). /\n\treadonly reason?: string\n}\n\n/\n Result of {@link PluginDownloadRequest}: the stored file's identity.\n * `cached` is true when the destination already existed — the host\n * answered from the vault without any dialog and without touching the\n * network (downloads are \"ensure present\", never unconditional).\n /\nexport type PluginDownloadResult = {\n\t/* The vault-relative destination that was resolved. /\n\treadonly path: string\n\treadonly sizeBytes: number\n\t/* sha256 of the stored bytes (host-computed, always present). /\n\treadonly sha256: string\n\t/* True when the file already existed and no consent/network was needed. /\n\treadonly cached: boolean\n}\n\n/\n Result of {@link ResourceAPI.deleteAsset} / `WebPluginAPI.deleteAsset`.\n * Deletion is idempotent: removing nothing is not an error.\n /\nexport type PluginAssetDeleteResult = {\n\t/* True when a file was actually removed. /\n\treadonly existed: boolean\n}\n\n/\n Error thrown by the asset methods. The name survives both wire\n * boundaries (worker IPC and the iframe postMessage bridge), so plugin\n * code can branch on `err.name` without parsing messages:\n \n - `DENIED` — the user declined the consent dialog, or consent timed out.\n * - `UNAVAILABLE` — this runtime has no consent channel (CLI, workbench,\n * offline mock) or the server is in read-only archive mode.\n * - `POLICY` — the host rejected the request before downloading:\n * manifest lacks the `download` permission, the URL or `dest` is not\n * allowed, the destination is a directory, or a quota would be\n * exceeded. Also used for reserved-name conflicts.\n \n Transport/network failures keep their own error names (e.g. socket\n * errors) and are not part of this vocabulary.\n /\nexport class PluginAssetError extends Error {\n\tconstructor(\n\t\treadonly code: PluginAssetErrorName,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message)\n\t\tthis.name = code\n\t}\n}\n\n/\n Narrow an asset error to a machine-readable name. Works across the\n * RPC boundaries because both preserve `Error.name` (the worker IPC and\n * the iframe bridge carry the name explicitly) — the instance is often\n * lost in transit, so the check keys on the name alone.\n /\nexport function isPluginAssetError(\n\terr: unknown,\n\tname: PluginAssetErrorName,\n): err is PluginAssetError {\n\treturn err instanceof Error && err.name === name\n}\n\n/* Build a `PluginAssetError` carrying the given machine-readable name. /\nexport function pluginAssetError(\n\tname: PluginAssetErrorName,\n\tmessage: string,\n): PluginAssetError {\n\treturn new PluginAssetError(name, message)\n}\n","/\n Canonical media-type knowledge: the extension sets, the extension →\n * MIME table and the MIME → media-kind mapping shared by content\n * plugins, the runtime host's sniffer and the server's classification\n * pipeline.\n \n Extensions are a hint, never the verdict: `ResourceAPI.sniff`\n * reads the file's magic bytes and only falls back to the tables here\n * when the content carries no recognizable signature (text formats).\n * The sets below therefore answer \"which extensions do we expect to\n * decode\", not \"what is this file\".\n \n Lower-case, with leading dot — match the output of\n * `path.extname(name).toLowerCase()`.\n \n Adding a new extension here widens classification everywhere at\n * once. Before adding, verify:\n * - sharp can extract width/height (image)\n * - ffprobe can read width/height/duration (video)\n * - ffprobe can read the stream/format metadata (audio), and the\n * extension has an entry in `AUDIO_FFMPEG_INPUT_FORMAT`\n * - the extension has an entry in {@link EXT_MIME}\n * - the gallery plugin's transcode-required set reflects the format\n * (browser-renderable originals stay native; HEIC/TIFF need the\n * sharp preview pipeline)\n /\nexport const IMAGE_EXTS: ReadonlySet<string> = new Set([\n\t\".jpg\",\n\t\".jpeg\",\n\t\".png\",\n\t\".webp\",\n\t\".gif\",\n\t\".bmp\",\n\t\".avif\",\n\t\".heic\",\n\t\".heif\",\n\t\".tif\",\n\t\".tiff\",\n\t\".svg\",\n\t\".jp2\",\n\t\".j2k\",\n\t\".jpx\",\n])\n\nexport const VIDEO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp4\",\n\t\".webm\",\n\t\".mov\",\n\t\".mkv\",\n\t\".m4v\",\n\t\".avi\",\n\t\".3gp\",\n])\n\nexport const AUDIO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp3\",\n\t\".flac\",\n\t\".ogg\",\n\t\".m4a\",\n\t\".wav\",\n\t\".opus\",\n\t\".aac\",\n])\n\n/\n Video containers ffmpeg can demux from a forward-only pipe (matroska,\n * avi). ISO-BMFF files (.mp4/.mov/.m4v) keep their moov index at the end\n * of the file, so a stream attempt on a zip-entry source is guaranteed to\n * fail after burning a full probesize read — consumers (thumb pipeline,\n * cover probing) send those straight to the materialized entry instead.\n /\nexport const STREAMABLE_VIDEO_EXTS: ReadonlySet<string> = new Set([\n\t\".webm\",\n\t\".mkv\",\n\t\".avi\",\n])\n\n/\n ffmpeg `-f` container name for piped audio bytes (no filename hint).\n * `.opus` files are Ogg containers; `.m4a` is ISO-BMFF, demuxed by the\n * mp4 demuxer.\n /\nexport const AUDIO_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {\n\t\".mp3\": \"mp3\",\n\t\".flac\": \"flac\",\n\t\".ogg\": \"ogg\",\n\t\".opus\": \"ogg\",\n\t\".wav\": \"wav\",\n\t\".m4a\": \"mp4\",\n\t\".aac\": \"aac\",\n}\n\n/\n ffmpeg `-f` container name keyed by sniffed MIME type, for piped\n * sources that have no filename ffprobe could key off. Content-derived\n * routing is what lets a mislabelled file still demux correctly, so\n * this table — not the extension one — drives `ResourceAPI.probe`.\n \n Several spellings map to the same container because magic-byte\n * matchers and IANA disagree on the canonical name (`audio/wav` vs\n * `audio/x-wav`, `video/vnd.avi` vs `video/x-msvideo`).\n /\nexport const MIME_FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {\n\t\"video/mp4\": \"mp4\",\n\t\"video/quicktime\": \"mov\",\n\t\"video/webm\": \"webm\",\n\t\"video/x-matroska\": \"matroska\",\n\t\"video/matroska\": \"matroska\",\n\t\"video/vnd.avi\": \"avi\",\n\t\"video/x-msvideo\": \"avi\",\n\t\"video/avi\": \"avi\",\n\t\"video/ogg\": \"ogg\",\n\t\"audio/mpeg\": \"mp3\",\n\t\"audio/mp3\": \"mp3\",\n\t\"audio/flac\": \"flac\",\n\t\"audio/x-flac\": \"flac\",\n\t\"audio/ogg\": \"ogg\",\n\t\"audio/opus\": \"ogg\",\n\t\"audio/vorbis\": \"ogg\",\n\t\"audio/wav\": \"wav\",\n\t\"audio/x-wav\": \"wav\",\n\t\"audio/vnd.wave\": \"wav\",\n\t\"audio/wave\": \"wav\",\n\t\"audio/mp4\": \"mp4\",\n\t\"audio/x-m4a\": \"mp4\",\n\t\"audio/aac\": \"aac\",\n\t\"video/3gpp\": \"mp4\",\n\t\"application/ogg\": \"ogg\",\n\t\"application/x-matroska\": \"matroska\",\n\t\"application/mp4\": \"mp4\",\n}\n\n/\n The audio mirror of {@link STREAMABLE_VIDEO_EXTS}: containers whose\n * headers lead the file, so ffmpeg/ffprobe can demux them from a\n * forward-only pipe. `.m4a` is ISO-BMFF with a trailing moov index, so\n * it must be probed from a materialized (seekable) entry.\n /\nexport const STREAMABLE_AUDIO_EXTS: ReadonlySet<string> = new Set([\n\t\".mp3\",\n\t\".flac\",\n\t\".ogg\",\n\t\".opus\",\n\t\".wav\",\n\t\".aac\",\n])\n\n/\n Media families a file can belong to. `other` covers everything the\n * media pipeline does not decode (text, documents, archives, ...) — it\n * is a real answer, not a failure.\n /\nexport const MEDIA_KINDS = [\"image\", \"video\", \"audio\", \"other\"] as const\n\nexport type MediaKind = (typeof MEDIA_KINDS)[number]\n\n/\n Extension → canonical MIME type. Used as the fallback branch of\n * content sniffing: magic-byte detection covers binary media, while\n * text-based formats (`.txt`, `.md`, `.csv`, subtitles, ...) carry no\n * signature and can only be named by their extension.\n /\nexport const EXT_MIME: Readonly<Record<string, string>> = {\n\t\".jpg\": \"image/jpeg\",\n\t\".jpeg\": \"image/jpeg\",\n\t\".png\": \"image/png\",\n\t\".webp\": \"image/webp\",\n\t\".gif\": \"image/gif\",\n\t\".bmp\": \"image/bmp\",\n\t\".avif\": \"image/avif\",\n\t\".heic\": \"image/heic\",\n\t\".heif\": \"image/heif\",\n\t\".tif\": \"image/tiff\",\n\t\".tiff\": \"image/tiff\",\n\t\".jp2\": \"image/jp2\",\n\t\".j2k\": \"image/jp2\",\n\t\".jpx\": \"image/jp2\",\n\t\".mp4\": \"video/mp4\",\n\t\".m4v\": \"video/mp4\",\n\t\".webm\": \"video/webm\",\n\t\".mov\": \"video/quicktime\",\n\t\".mkv\": \"video/x-matroska\",\n\t\".avi\": \"video/vnd.avi\",\n\t\".3gp\": \"video/3gpp\",\n\t\".mp3\": \"audio/mpeg\",\n\t\".flac\": \"audio/flac\",\n\t\".ogg\": \"audio/ogg\",\n\t\".opus\": \"audio/opus\",\n\t\".m4a\": \"audio/mp4\",\n\t\".wav\": \"audio/wav\",\n\t\".aac\": \"audio/aac\",\n\t\".txt\": \"text/plain\",\n\t\".md\": \"text/markdown\",\n\t\".csv\": \"text/csv\",\n\t\".json\": \"application/json\",\n\t\".xml\": \"text/xml\",\n\t\".html\": \"text/html\",\n\t\".htm\": \"text/html\",\n\t\".svg\": \"image/svg+xml\",\n\t\".srt\": \"application/x-subrip\",\n\t\".vtt\": \"text/vtt\",\n\t\".ass\": \"text/x-ssa\",\n\t\".epub\": \"application/epub+zip\",\n\t\".pdf\": \"application/pdf\",\n\t\".zip\": \"application/zip\",\n\t\".cbz\": \"application/vnd.comicbook+zip\",\n\t\".cbr\": \"application/vnd.comicbook-rar\",\n\t\".rar\": \"application/vnd.rar\",\n\t\".7z\": \"application/x-7z-compressed\",\n\t\".cb7\": \"application/x-7z-compressed\",\n\t\".tar\": \"application/x-tar\",\n\t\".cbt\": \"application/x-tar\",\n}\n\n/\n Container MIME types whose top-level type does not describe the\n * payload. Ogg and Matroska carry audio or video, and `application/`\n says nothing either way — the values here are the common case, and\n * `ResourceAPI.probe` overrides them with the stream layout ffprobe\n * actually reports.\n /\nexport const MIME_KIND_OVERRIDES: Readonly<Record<string, MediaKind>> = {\n\t\"application/ogg\": \"audio\",\n\t\"application/x-matroska\": \"video\",\n\t\"application/mp4\": \"video\",\n}\n\n/\n Media family of a MIME type: the override table first, then the\n * top-level type. Never throws — unknown types are `other`.\n /\nexport function mimeToKind(mime: string): MediaKind {\n\tconst normalized = mime.toLowerCase()\n\tconst override = MIME_KIND_OVERRIDES[normalized]\n\tif (override !== undefined) return override\n\tif (normalized.startsWith(\"image/\")) return \"image\"\n\tif (normalized.startsWith(\"video/\")) return \"video\"\n\tif (normalized.startsWith(\"audio/\")) return \"audio\"\n\treturn \"other\"\n}\n\n/* Canonical MIME type for an extension (leading dot), or `undefined`. /\nexport function extToMime(ext: string): string \| undefined {\n\treturn EXT_MIME[ext.toLowerCase()]\n}\n","/\n The plugin definition contract — the single source of truth shared by\n * the authoring SDK (`@hoardodile/sdk-server`), the runtime host\n * (`@hoardodile/host`) and the worker sandbox. Everything here is pure\n * TypeScript with no node or DOM dependencies, so the same contract\n * serves browser-facing packages and node runtimes alike.\n /\nimport type { MediaKind } from \"./media-exts.ts\"\nimport { extToMime, mimeToKind } from \"./media-exts.ts\"\nimport type {\n\tPluginAssetDeleteResult,\n\tPluginDownloadRequest,\n\tPluginDownloadResult,\n} from \"./plugin-asset.ts\"\nimport { pluginAssetError } from \"./plugin-asset.ts\"\nimport type { ReadFileRange } from \"./read-range.ts\"\nimport type { Result } from \"./result.ts\"\n\nexport type { MediaKind }\n\n/\n Schema contract shared between server and web plugin APIs.\n * Declared once per plugin and used to type both `definePlugin` and\n * `WebPluginAPI`.\n /\nexport interface PluginSchema {\n\treadonly file?: unknown\n\treadonly sourceMeta?: unknown\n\treadonly searchMeta?: unknown\n\t/\n\t Plugin-defined payload the `detect` hook may carry on a\n\t * successful match. The host keeps the last payload and exposes it\n\t * to the plugin's other hooks as `api.context.detect` — classify\n\t * once in `detect` instead of rescanning in every hook. Declaring\n\t * this slot types the context; hooks must still handle the absent\n\t * case (`undefined`: fresh worker, or detect never matched).\n\t /\n\treadonly detect?: unknown\n\t/\n\t Plugin-defined anchor location data: the payload carried inside the\n\t * wire {@link AnchorData} envelope (see {@link anchorData}). Outgoing\n\t * anchors are typed by this slot and passed raw (e.g.\n\t * `createMessage({ anchor: { page } })`); incoming anchor data is\n\t * validated by the plugin's `decodeAnchor` (see `definePluginAPI` in\n\t * `@hoardodile/sdk-react`).\n\t /\n\treadonly anchor?: unknown\n}\n\n/\n Server plugin detection result: the shared result vocabulary, where a\n * match carries the schema's `detect` payload (when one is declared)\n * and a miss carries its reasons. Plugins may return the literal\n * `{ ok: true } as const` / `{ ok: false, reasons }` shapes directly,\n * or use `ok()`/`err({ reasons })` from the result module.\n \n `TPayload` is the plugin's declared `detect` slot — the payload\n * spread onto a match is checked against it at compile time, so a\n * classification that drifts from the schema fails to build.\n /\nexport type Detection<TPayload extends object = object> = Result<\n\tTPayload,\n\t{ readonly reasons: readonly string[] }\n>\n\n/* Structured logger scoped to a single plugin. /\nexport type Logger = {\n\tinfo(message: string, data?: Record<string, unknown>): void\n\twarn(message: string, data?: Record<string, unknown>): void\n\terror(message: string, data?: Record<string, unknown>): void\n}\n\n/* Image probe payload. /\nexport type ImageInfo = {\n\treadonly width?: number\n\treadonly height?: number\n}\n\n/* Video probe payload. /\nexport type VideoInfo = {\n\treadonly width?: number\n\treadonly height?: number\n\treadonly durationMs?: number\n}\n\n/\n Embedded container tags carried by an audio file (ID3, Vorbis\n * comments, MP4 metadata atoms). Every field is optional — untagged\n * files are normal.\n /\nexport type AudioTags = {\n\treadonly title?: string\n\treadonly artist?: string\n\treadonly album?: string\n}\n\n/\n Embedded artwork carried by an audio file (ID3 APIC, FLAC PICTURE,\n * MP4 `covr`). Its presence is the signal that the host can extract a\n * real cover; the dimensions come from the same probe, so callers can\n * pre-size the cover slot without decoding the picture.\n /\nexport type AudioCoverArt = {\n\treadonly width?: number\n\treadonly height?: number\n}\n\n/\n Audio probe payload. Any field can be absent when the container does\n * not report it.\n /\nexport type AudioInfo = {\n\treadonly durationMs?: number\n\t/* Codec name of the first audio stream, e.g. `\"mp3\"`, `\"flac\"`. /\n\treadonly codec?: string\n\t/* Container bit rate in bits per second. /\n\treadonly bitRate?: number\n\t/* Sample rate of the first audio stream, in Hz. /\n\treadonly sampleRate?: number\n\t/* Channel count of the first audio stream. /\n\treadonly channels?: number\n\t/* Present only when the file embeds artwork. /\n\treadonly coverArt?: AudioCoverArt\n\treadonly tags?: AudioTags\n}\n\n/\n What a file's bytes say it is. Produced by {@link ResourceAPI.sniff}.\n \n `source` records who answered: `\"magic\"` means the file's own\n * signature was recognized (authoritative), `\"extension\"` means the\n * content carried no signature and the filename was used instead — the\n * normal outcome for text-based formats, which have no magic bytes.\n \n `kind` is provisional for container formats that can hold either\n * audio or video (Ogg, Matroska, ISO-BMFF); {@link ResourceAPI.probe}\n * overrides it with the stream layout actually found in the file.\n /\nexport type FileType = {\n\t/* Canonical MIME type, e.g. `\"image/jpeg\"`. /\n\treadonly mime: string\n\t/* Canonical extension for {@link mime}, with leading dot. /\n\treadonly ext: string\n\treadonly kind: MediaKind\n\treadonly source: \"magic\" \| \"extension\"\n}\n\n/\n Everything one media probe pass can say about a file, discriminated\n * by the family the content really belongs to — the shape every\n * mainstream prober uses (ffprobe's `format` + `streams`, sharp's\n * `metadata()`, Tika's `MediaType`).\n \n `other` is a successful answer: the file was identified and is not\n * decodable media (text, documents, archives). `unknown` is the failure\n * branch and always carries a reason, so \"this host has no probe\n * backend\" is never confused with \"this file is not an image\":\n \n - `unsupported` — identified, but no backend decodes this format\n * - `unavailable` — the host wired no probe implementation (raw\n * directory APIs and test fixtures)\n * - `failed` — a backend ran and could not decode the bytes\n /\nexport type ProbeResult =\n\t\| ({\n\t\t\treadonly kind: \"image\"\n\t\t\treadonly mime: string\n\t\t\t/* Multi-frame source: animated GIF / WebP / APNG / AVIF. /\n\t\t\treadonly animated: boolean\n\t } & ImageInfo)\n\t\| ({ readonly kind: \"video\"; readonly mime: string } & VideoInfo)\n\t\| ({ readonly kind: \"audio\"; readonly mime: string } & AudioInfo)\n\t\| { readonly kind: \"other\"; readonly mime: string }\n\t\| {\n\t\t\treadonly kind: \"unknown\"\n\t\t\treadonly reason: \"unsupported\" \| \"unavailable\" \| \"failed\"\n\t }\n\n/\n Perceptual hash kinds the host can compute for an image file.\n * `dhash` (difference hash) and `phash` (DCT-based perceptual hash)\n * are 64-bit similarity hashes compared by Hamming distance;\n * `sha256` is an exact byte hash. Animated images hash their first\n * frame. Plugins decide which kinds to request and which files to\n * hash — the host only provides the computation.\n /\nexport const IMAGE_HASH_KINDS = [\"sha256\", \"dhash\", \"phash\"] as const\nexport type ImageHashKind = (typeof IMAGE_HASH_KINDS)[number]\n\n/\n One content hash of a resource file, produced by the plugin's\n * `imageHashes` hook. `scope` is the archive-relative file path,\n * `type` the hash kind (`sha256`/`dhash`/`phash` or a plugin-defined\n * extension), `value` the lowercase hex digest. A resource may expose\n * several hashes (per file × per kind) or none.\n /\nexport type ImageHash = {\n\treadonly scope: string\n\treadonly type: string\n\treadonly value: string\n\t/* Bit length of the hash; required for perceptual kinds. /\n\treadonly bits?: number\n}\n\n/* Result of the `imageHashes` hook: hashes per file, possibly empty. /\nexport type ImageHashesResult = {\n\treadonly hashes: readonly ImageHash[]\n}\n\n/\n One file inside a container entry (zip/tar) as listed (or extracted)\n * by the plugin API. `path` is the entry's path inside the archive;\n * dimensions are present when the host probed the entry (image\n * backends) — a listing-only result carries no dimensions.\n /\nexport type ArchiveExtractionEntry = {\n\treadonly path: string\n\treadonly sizeBytes: number\n\treadonly kind: MediaKind\n\treadonly width?: number\n\treadonly height?: number\n\treadonly animated?: boolean\n}\n\n/\n A container listing without materialization — the cheap counterpart of\n * {@link ResourceAPI.extractArchive}. Carries entry names, sizes and\n * kinds only; no dimensions (probing those requires the bytes).\n /\nexport type ContainerListing = {\n\treadonly entries: readonly ArchiveExtractionEntry[]\n}\n\n/\n Result of {@link ResourceAPI.extractArchive}: the materialized\n * entries of a container entry. A completed extraction is marked by the\n * host's `index.json` manifest; extraction always writes the cache (the\n * host's `local/cache` is derived data, writable in every view mode).\n /\nexport type ArchiveExtraction = {\n\treadonly entries: readonly ArchiveExtractionEntry[]\n}\n\n/\n Resource-scoped API available to every plugin hook. All paths are\n * relative to the resource's source directory; the host resolves\n * absolute paths transparently.\n \n `TSchema` types the injected session context (`context.detect`); the\n * default keeps the API compatible with code that never reads it.\n /\nexport type ResourceAPI<TSchema extends PluginSchema = PluginSchema> = {\n\t/* Write an informational log entry. /\n\treadonly logInfo: (message: string, data?: Record<string, unknown>) => void\n\t/* Write a warning log entry. /\n\treadonly logWarn: (message: string, data?: Record<string, unknown>) => void\n\t/* Write an error log entry. /\n\treadonly logError: (message: string, data?: Record<string, unknown>) => void\n\t/\n\t List all regular-file names (flat list), in canonical display\n\t * order: the resource's explicit upload order when one exists (the\n\t * host's `.order` manifest), the natural name sort otherwise.\n\t * Plugins that need their own ordering should sort explicitly.\n\t \n\t This is the raw name list — the `listFiles` hook of the plugin\n\t * definition turns it into typed file entries.\n\t /\n\treadonly listFileNames: () => Promise<readonly string[]>\n\t/\n\t Read a regular file relative to the resource root.\n\t \n\t Without `range` the whole file is returned; hosts may reject\n\t * oversized full reads — pass a range (or use `readFileChunks` from\n\t * `@hoardodile/sdk-server/helpers`) for large files.\n\t \n\t Container addressing: a path of the form `outer!inner` reads the\n\t * file inside a zip/tar entry (e.g. `manga.cbz!Chapter 1/001.jpg`)\n\t * — the host streams the decompressed bytes. When `outer` is not a\n\t * container, or the inner entry is absent, the whole path is treated\n\t * as a literal filename.\n\t /\n\treadonly readFile: (\n\t\tpath: string,\n\t\trange?: ReadFileRange,\n\t) => Promise<Uint8Array>\n\t/\n\t Return the byte size of `path` without reading the file contents.\n\t * Resolves to `undefined` when the file does not exist or the artifact\n\t * is not yet committed. Supports container addressing (`outer!inner`).\n\t /\n\treadonly statFile: (\n\t\tpath: string,\n\t) => Promise<{ readonly sizeBytes: number } \| undefined>\n\t/\n\t Batch {@link statFile}: resolves every path in one host round-trip\n\t * (positions preserved). Prefer this over a per-file fan-out of\n\t * `statFile` when statting a whole archive — one RPC instead of N.\n\t /\n\treadonly statFiles: (\n\t\tpaths: readonly string[],\n\t) => Promise<readonly ({ readonly sizeBytes: number } \| undefined)[]>\n\t/\n\t Identify the file at `path` from its content: magic-byte\n\t * detection, falling back to the extension only for formats that\n\t * carry no signature (text, subtitles). Resolves to `undefined` when\n\t * neither can name the file. Supports container addressing.\n\t \n\t This is the cheap call — it reads a small header window, never\n\t * decodes. Use it to route work; use {@link probe} when you need\n\t * dimensions, duration or stream details.\n\t /\n\treadonly sniff: (path: string) => Promise<FileType \| undefined>\n\t/\n\t Decode the media metadata of `path` in one pass, routed by\n\t * {@link sniff} rather than by the filename: images resolve through\n\t * sharp, audio and video through ffprobe (which also settles\n\t * ambiguous containers — an `.ogg` holding only audio streams comes\n\t * back as `kind: \"audio\"`). Supports container addressing.\n\t \n\t Always resolves, never rejects. Non-media files answer\n\t * `{ kind: \"other\" }`; the `unknown` branch carries a `reason` that\n\t * distinguishes \"no backend wired\" (`unavailable`, what raw\n\t * directory APIs and fixtures return) from a real decode failure.\n\t /\n\treadonly probe: (path: string) => Promise<ProbeResult>\n\t/\n\t Stream-hash the file at `path` (any file kind). Rejects when the\n\t * file is missing or the read fails; the host streams the entry so\n\t * arbitrarily large files are safe. Supports container addressing.\n\t /\n\treadonly hashBytes: (path: string, algo: \"md5\" \| \"sha256\") => Promise<string>\n\t/\n\t Compute the requested hashes of the image at `path` in one pass:\n\t * `sha256` from the raw bytes, `dhash`/`phash` from a decoded\n\t * grayscale rendition (animated images use their first frame).\n\t * Resolves to `undefined` when the file is not a decodable image;\n\t * `kinds` names a subset of {@link IMAGE_HASH_KINDS} and the result\n\t * carries exactly those keys. Supports container addressing.\n\t /\n\treadonly computeImageHashes: (\n\t\tpath: string,\n\t\tkinds: readonly ImageHashKind[],\n\t) => Promise<Readonly<Record<ImageHashKind, string>> \| undefined>\n\t/\n\t List the file entries of a container entry (zip/tar) without\n\t * materializing anything — the cheap call for metadata-only needs\n\t * (detect, card counts). Rejects when `filename` is not a supported\n\t * container.\n\t /\n\treadonly listContainer: (filename: string) => Promise<ContainerListing>\n\t/\n\t Materialize the contents of a container entry (zip/tar) into the\n\t * host's extraction cache so the browser can serve the inner files\n\t * over plain URLs. `filename` is a literal container entry — the\n\t * cache holds one directory per archive with the inner paths\n\t * preserved, plus a completion manifest.\n\t \n\t Idempotent: an already-materialized archive re-lists from the\n\t * manifest without re-extracting. Rejects when the entry is not a\n\t * supported container, exceeds the host's byte/entry budgets, or\n\t * when this host wires no extraction cache (test fixtures, raw\n\t * directory APIs).\n\t /\n\treadonly extractArchive: (filename: string) => Promise<ArchiveExtraction>\n\t/\n\t Ensure remote assets exist in the plugin's own vault — one call with\n\t * one request, or one call with an array of requests. When `dest` is\n\t * already present the host answers `cached: true` without any dialog\n\t * and without touching the network; otherwise the host asks the user\n\t * (the web app shows the shared consent dialog with the URLs\n\t * verbatim) and downloads on approval.\n\t \n\t An array is ONE consent question for the WHOLE batch (the dialog\n\t * lists every item) and is all-or-nothing: any failure discards every\n\t * staged file and rejects with the first error, so nothing is\n\t * partially committed. Results arrive in request order with `cached`\n\t * items keeping their positions. Cap: {@link PLUGIN_ASSET_BATCH_MAX_ITEMS}\n\t * items per call. The file always lands inside\n\t * `<plugin-dir>/vault/` — `dest` is vault-relative and can never\n\t * reach the plugin's bundled files.\n\t \n\t Gated by the manifest `download` permission; rejections carry a\n\t * machine-readable {@link PluginAssetErrorName} in `err.name`\n\t * (`DENIED` / `UNAVAILABLE` / `POLICY`).\n\t /\n\treadonly download: ((\n\t\trequest: PluginDownloadRequest,\n\t) => Promise<PluginDownloadResult>) &\n\t\t((\n\t\t\trequests: readonly PluginDownloadRequest[],\n\t\t) => Promise<readonly PluginDownloadResult[]>)\n\t/\n\t Byte size of a vault file, or `undefined` when absent. The cheap\n\t * presence check on top of which `download` resolves cached hits.\n\t /\n\treadonly statAsset: (\n\t\tpath: string,\n\t) => Promise<{ readonly sizeBytes: number } \| undefined>\n\t/* Read a vault file's bytes (bounded by the same cap as {@link readFile}). /\n\treadonly readAsset: (path: string) => Promise<Uint8Array>\n\t/\n\t Remove a vault file; idempotent (absent files answer\n\t * `{ existed: false }`). The plugin decides the vault's own\n\t * lifecycle — e.g. cleaning stale layouts after a plugin update.\n\t * No user consent is required: nothing leaves the host. Directories\n\t * and paths outside the vault are rejected (`POLICY`).\n\t /\n\treadonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>\n\t/\n\t Session context injected by the host. `detect` carries the payload\n\t * the plugin's `detect` hook returned on its last successful match\n\t * (worker-session scope): the one-pass classification every other\n\t * hook can build on. `undefined` when detect has not matched in this\n\t * session — a fresh worker — so hooks must always handle the absent\n\t * case by re-deriving.\n\t /\n\treadonly context: { readonly detect: TSchema[\"detect\"] \| undefined }\n}\n\n/\n Declarative description of a content plugin. Plugins export an instance\n * of this shape as their default export; the host injects the resource\n * API at call time and never invokes a factory function.\n /\nexport type PluginDefinition<TSchema extends PluginSchema = PluginSchema> = {\n\t/\n\t Detect whether this plugin applies to the current resource. A\n\t * successful match may carry a payload — `ok({ ...shape })` — which\n\t * the host keeps and exposes to the other hooks as\n\t * `api.context.detect`. The payload is checked against the schema's\n\t * `detect` slot (when one is declared).\n\t /\n\treadonly detect: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<Detection<TSchema[\"detect\"] & object>>\n\t/* Optional source metadata builder. /\n\treadonly sourceMeta?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<TSchema[\"sourceMeta\"] \| undefined>\n\t/* Optional search metadata builder. /\n\treadonly searchMeta?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<TSchema[\"searchMeta\"] \| undefined>\n\t/* Optional local cover source resolver. /\n\treadonly coverLocal?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<string \| undefined>\n\t/\n\t Optional custom file list builder. Results are cached verbatim in a\n\t * sidecar. When absent the host falls back to a bare list of source\n\t * filenames.\n\t /\n\treadonly listFiles?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<readonly TSchema[\"file\"][]>\n\t/\n\t Optional content hashes for duplicate detection and image\n\t * similarity. The plugin decides the policy — which files to hash\n\t * and which kinds — by calling the API's hash primitives; a plugin\n\t * facing image-less resources simply omits this hook. Returning\n\t * `undefined` (or a hook error) keeps the resource's hash rows empty.\n\t /\n\treadonly imageHashes?: (\n\t\tapi: ResourceAPI<TSchema>,\n\t) => Promise<ImageHashesResult \| undefined>\n\t/\n\t Optional post-install callback, invoked by the host after a\n\t * successful install or update commit (marketplace install/update and\n\t * zip uploads). Runs with an install-scoped API: no resource is\n\t * attached — the file surface answers empty and there is no\n\t * `context.detect` — while the asset methods still work and stay\n\t * gated by the shared consent dialog exactly like the runtime path.\n\t * A throwing (or consent-denied) hook never fails the install; the\n\t * plugin should treat it as best-effort and re-check at runtime.\n\t \n\t Typical use: fetch pinned runtime files into the plugin vault once,\n\t * so the first preview opens without a consent dialog.\n\t /\n\treadonly onInstall?: (api: ResourceAPI<TSchema>) => Promise<void>\n}\n\n/* Plugin hook names the host can invoke, in contract order. /\nexport const HOOK_NAMES = [\n\t\"detect\",\n\t\"sourceMeta\",\n\t\"searchMeta\",\n\t\"coverLocal\",\n\t\"listFiles\",\n\t\"imageHashes\",\n\t\"onInstall\",\n] as const\n\nexport type HookName = (typeof HOOK_NAMES)[number]\n\nfunction isAsyncFunction(value: unknown): boolean {\n\treturn (\n\t\ttypeof value === \"function\" && value.constructor.name === \"AsyncFunction\"\n\t)\n}\n\n/\n Freeze and return a plugin definition. Runs shape validation upfront so\n * a malformed plugin fails at load time with a friendly message instead\n * of misbehaving at hook time.\n /\nexport function definePlugin<TSchema extends PluginSchema = PluginSchema>(\n\tdefinition: PluginDefinition<TSchema>,\n): PluginDefinition<TSchema> {\n\tassertPluginShape(definition)\n\treturn Object.freeze({ ...definition })\n}\n\n/\n Validate that a value satisfies the structural contract of a\n * {@link PluginDefinition}: only known hooks, all hooks async functions,\n * `detect` required. Does NOT exercise behaviour.\n /\nexport function assertPluginShape(\n\tvalue: unknown,\n): asserts value is PluginDefinition {\n\tif (typeof value !== \"object\" \|\| value === null) {\n\t\tthrow new Error(\"PluginDefinition: expected an object with hook functions\")\n\t}\n\n\tconst definition = value as Record<string, unknown>\n\n\tconst knownHooks = new Set<string>(HOOK_NAMES)\n\tconst unknown = Object.keys(definition).filter((key) => !knownHooks.has(key))\n\tif (unknown.length > 0) {\n\t\tthrow new Error(\n\t\t\t`PluginDefinition: unknown hook(s) ${unknown.map((k) => `\"${k}\"`).join(\", \")} — expected one of: ${HOOK_NAMES.join(\", \")}`,\n\t\t)\n\t}\n\n\tfor (const hook of HOOK_NAMES) {\n\t\tconst entry = definition[hook]\n\t\tif (entry === undefined) {\n\t\t\tif (hook === \"detect\") {\n\t\t\t\tthrow new Error(\"PluginDefinition: missing detect()\")\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (!isAsyncFunction(entry)) {\n\t\t\tconst kind =\n\t\t\t\ttypeof entry === \"function\" ? \"a synchronous function\" : typeof entry\n\t\t\tthrow new Error(\n\t\t\t\t`PluginDefinition: \"${hook}\" must be an async function (got ${kind}) — hooks may do heavy work and the host awaits every hook, so declare it with \\`async\\`.`,\n\t\t\t)\n\t\t}\n\t}\n}\n\n/\n Convenience wrapper that builds a failing plugin definition. Used by\n * the host when a plugin directory is missing or its main.js cannot be\n * loaded.\n /\nexport function createFailingPlugin(\n\treasons: readonly string[],\n): PluginDefinition {\n\treturn definePlugin({\n\t\tdetect: async () => ({ ok: false, reasons }),\n\t})\n}\n\n/* Type guard for the success branch of a {@link Detection}. /\nexport function isDetected(\n\tdetection: Detection,\n): detection is { readonly ok: true } {\n\treturn detection.ok\n}\n\n/* Type guard for the failure branch of a {@link Detection}. /\nexport function isMissed(\n\tdetection: Detection,\n): detection is { readonly ok: false; readonly reasons: readonly string[] } {\n\treturn !detection.ok\n}\n\n/* Declarative configuration for a {@link ResourceAPI} fixture. /\nexport type ResourceAPIFixtureConfig<\n\tTSchema extends PluginSchema = PluginSchema,\n> = {\n\t/* File names returned by `listFileNames`. /\n\treadonly files?: readonly string[]\n\t/* File contents returned by `readFile`. /\n\treadonly contents?: Readonly<Record<string, string \| Uint8Array>>\n\t/\n\t `sniff` results keyed by file path — `{ \"a.jpg\": … }` matches only\n\t * that file, keys starting with a dot match by extension suffix\n\t * (`{ \".mp4\": … }` applies to every .mp4 file, longest key wins),\n\t * and `{ \"\": … }` matches every path (the usual way to express a\n\t * default). Unconfigured paths fall back to the extension table,\n\t * exactly like the host's extension branch.\n\t /\n\treadonly types?: Readonly<Record<string, FileType \| undefined>>\n\t/\n\t `probe` results keyed by file path (same matching rules as\n\t * {@link types}). Unconfigured paths mirror the host's routing:\n\t * identified non-media answers `{ kind: \"other\" }`, identified media\n\t * answers `{ kind: \"unknown\", reason: \"unavailable\" }` — the fixture\n\t * decodes nothing, so a hook that needs real dimensions belongs in a\n\t * sandbox test instead.\n\t /\n\treadonly probes?: Readonly<Record<string, ProbeResult \| undefined>>\n\t/* Stat results. A plain value is used as the default for all paths. /\n\treadonly stats?:\n\t\t\| Readonly<Record<string, { readonly sizeBytes: number } \| undefined>>\n\t\t\| { readonly sizeBytes: number }\n\t\t\| undefined\n\t/* `hashBytes` results by path; a plain string is used for all paths. /\n\treadonly byteHashes?: Readonly<Record<string, string>> \| string\n\t/\n\t `computeImageHashes` results by path. A plain record is used as the\n\t * default for all paths; absent paths resolve to `undefined`.\n\t /\n\treadonly imageHashes?:\n\t\t\| Readonly<Record<string, ImageHashesResult>>\n\t\t\| ImageHashesResult\n\t/\n\t `listContainer` results keyed by the archive filename. Absent\n\t * names reject, mirroring the host's \"not a supported archive\" error.\n\t /\n\treadonly containerListings?: Readonly<Record<string, ContainerListing>>\n\t/\n\t `extractArchive` results keyed by the archive filename. Absent\n\t * names reject, mirroring the host's \"not a supported archive\" error.\n\t /\n\treadonly extractions?: Readonly<Record<string, ArchiveExtraction>>\n\t/\n\t Vault file contents keyed by vault-relative path, backing\n\t * `statAsset` / `readAsset` / `deleteAsset` in the fixture.\n\t /\n\treadonly assetFiles?: Readonly<Record<string, string \| Uint8Array>>\n\t/\n\t Handler for `download` (single request or batch of requests, typed\n\t * as the union — the fixture returns the matching shape). Absent\n\t * means the hosted runtime has no consent channel — `download`\n\t * rejects with `UNAVAILABLE`, exactly like the CLI, workbench and\n\t * offline mock hosts.\n\t /\n\treadonly downloadHandler?: (\n\t\trequest: PluginDownloadRequest \| readonly PluginDownloadRequest[],\n\t) => Promise<PluginDownloadResult \| readonly PluginDownloadResult[]>\n\t/\n\t Container addressing for the fixture: maps a virtual path\n\t * (`outer!inner`) to stat/sniff/probe results, so hooks that browse\n\t * inside archives can be tested without real archives. Matching rules\n\t * mirror {@link types}: exact path keys, dot fragments by suffix,\n\t * `{ \"\": … }` as the default.\n\t /\n\treadonly virtualEntries?: Readonly<Record<string, ArchiveExtractionEntry>>\n\t/\n\t Session context handed to hooks as `api.context` — mirrors the\n\t * host injecting the payload of a prior successful `detect`. Typed\n\t * by the schema generic when one is supplied.\n\t /\n\treadonly context?: { readonly detect?: TSchema[\"detect\"] }\n}\n\nfunction resolveKeyed<T>(\n\tpath: string,\n\ttable: Readonly<Record<string, T \| undefined>> \| undefined,\n): T \| undefined {\n\tif (table === undefined) return undefined\n\t// Keys match the path exactly, except keys that start with a dot —\n\t// those are extension fragments matching any path ending with them\n\t// (`.mp4` applies to every .mp4 file). The longest fragment wins so\n\t// a shared default is never shadowed; the empty key `\"\"` is the\n\t// catch-all default. Plain-name keys never match by substring, so\n\t// `\"a.jpg\"` cannot hijack `\"ba.jpg\"`.\n\tif (Object.hasOwn(table, path)) return table[path]\n\tlet bestKey: string \| undefined\n\tlet bestLen = -1\n\tfor (const key of Object.keys(table)) {\n\t\tif (key.length > bestLen && key.startsWith(\".\") && path.endsWith(key)) {\n\t\t\tbestKey = key\n\t\t\tbestLen = key.length\n\t\t}\n\t}\n\tif (bestKey !== undefined) return table[bestKey]\n\treturn table[\"\"]\n}\n\n/* Lower-cased extension from the last dot, or `\"\"` when there is none. /\nfunction lastExt(path: string): string {\n\tconst dot = path.lastIndexOf(\".\")\n\treturn dot === -1 ? \"\" : path.slice(dot).toLowerCase()\n}\n\n/\n Identify a file from its name alone: the extension branch of content\n * sniffing, exposed on its own because it is also the honest answer for\n * formats that carry no signature, and the shape test doubles need when\n * standing in for a real {@link ResourceAPI}.\n /\nexport function fileTypeFromName(path: string): FileType \| undefined {\n\tconst ext = lastExt(path)\n\tconst mime = extToMime(ext)\n\tif (mime === undefined) return undefined\n\treturn { mime, ext, kind: mimeToKind(mime), source: \"extension\" }\n}\n\nfunction resolveValue<T>(\n\tpath: string,\n\tvalue: Readonly<Record<string, T \| undefined>> \| T \| undefined,\n\tdefaultValue: T \| undefined,\n): T \| undefined {\n\tif (value === undefined \|\| value === null) return defaultValue\n\tif (typeof value !== \"object\" \|\| Array.isArray(value)) return value\n\t// Matching rules mirror {@link resolveKeyed}: exact keys, dot\n\t// fragments by suffix (longest wins), empty-key default.\n\tconst table = value as Readonly<Record<string, T \| undefined>>\n\tif (Object.hasOwn(table, path)) return table[path]\n\tlet bestKey: string \| undefined\n\tlet bestLen = -1\n\tfor (const key of Object.keys(table)) {\n\t\tif (key.length > bestLen && key.startsWith(\".\") && path.endsWith(key)) {\n\t\t\tbestKey = key\n\t\t\tbestLen = key.length\n\t\t}\n\t}\n\tif (bestKey !== undefined) return table[bestKey]\n\treturn table[\"\"] ?? defaultValue\n}\n\nfunction virtualStat(\n\tpath: string,\n\ttable:\n\t\t\| Readonly<Record<string, ArchiveExtractionEntry \| undefined>>\n\t\t\| undefined,\n): { readonly sizeBytes: number } \| undefined {\n\tconst entry = resolveKeyed(path, table)\n\treturn entry === undefined ? undefined : { sizeBytes: entry.sizeBytes }\n}\n\nfunction virtualType(\n\tpath: string,\n\ttable:\n\t\t\| Readonly<Record<string, ArchiveExtractionEntry \| undefined>>\n\t\t\| undefined,\n): FileType \| undefined {\n\tif (resolveKeyed(path, table) === undefined) return undefined\n\treturn fileTypeFromName(path.slice(path.lastIndexOf(\"!\") + 1))\n}\n\n/\n Create a mutable {@link ResourceAPI} fixture driven by a declarative\n * config. No filesystem involved — the standard way to unit-test plugin\n * hooks.\n \n Pass the plugin's schema as the generic\n * (`createResourceAPIFixture<MySchema>()`) so the returned api carries\n * the typed session context — the same shape schema-typed hooks receive\n * from the host.\n /\nexport function createResourceAPIFixture<\n\tTSchema extends PluginSchema = PluginSchema,\n>(\n\tinitialConfig: ResourceAPIFixtureConfig<TSchema> = {},\n): {\n\treadonly api: ResourceAPI<TSchema>\n\treadonly setConfig: (next: ResourceAPIFixtureConfig<TSchema>) => void\n} {\n\tlet config: ResourceAPIFixtureConfig<TSchema> = initialConfig\n\n\tfunction setConfig(next: ResourceAPIFixtureConfig<TSchema>): void {\n\t\tconfig = next\n\t}\n\n\tconst api: ResourceAPI<TSchema> = {\n\t\tlogInfo() {},\n\t\tlogWarn() {},\n\t\tlogError() {},\n\t\tcontext: { detect: config.context?.detect },\n\t\tasync listFileNames() {\n\t\t\treturn config.files ?? []\n\t\t},\n\t\tasync readFile(path, range) {\n\t\t\tconst content = config.contents?.[path]\n\t\t\tif (content === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no content for \"${path}\"`)\n\t\t\t}\n\t\t\tconst bytes =\n\t\t\t\ttypeof content === \"string\"\n\t\t\t\t\t? new TextEncoder().encode(content)\n\t\t\t\t\t: content\n\t\t\tif (range === undefined) return bytes\n\t\t\t// Mirrors host semantics: the range is clamped to the content size.\n\t\t\treturn bytes.slice(range.start ?? 0, range.end)\n\t\t},\n\t\tasync statFile(path) {\n\t\t\treturn (\n\t\t\t\tresolveValue(path, config.stats, undefined) ??\n\t\t\t\tvirtualStat(path, config.virtualEntries)\n\t\t\t)\n\t\t},\n\t\tasync statFiles(paths) {\n\t\t\treturn Promise.all(\n\t\t\t\tpaths.map(\n\t\t\t\t\t(path) =>\n\t\t\t\t\t\tresolveValue(path, config.stats, undefined) ??\n\t\t\t\t\t\tvirtualStat(path, config.virtualEntries),\n\t\t\t\t),\n\t\t\t)\n\t\t},\n\t\tasync sniff(path) {\n\t\t\treturn (\n\t\t\t\tresolveKeyed(path, config.types) ??\n\t\t\t\tfileTypeFromName(path) ??\n\t\t\t\tvirtualType(path, config.virtualEntries)\n\t\t\t)\n\t\t},\n\t\tasync probe(path) {\n\t\t\tconst configured = resolveKeyed(path, config.probes)\n\t\t\tif (configured !== undefined) return configured\n\t\t\t// Unconfigured paths mirror the host's own routing: a file the\n\t\t\t// fixture cannot identify is unsupported, an identified\n\t\t\t// non-media file answers `other`, and identified media needs a\n\t\t\t// real decode the fixture has no backend for.\n\t\t\tconst type =\n\t\t\t\tresolveKeyed(path, config.types) ??\n\t\t\t\tfileTypeFromName(path) ??\n\t\t\t\tvirtualType(path, config.virtualEntries)\n\t\t\tif (type === undefined) return { kind: \"unknown\", reason: \"unsupported\" }\n\t\t\tif (type.kind === \"other\") return { kind: \"other\", mime: type.mime }\n\t\t\tconst virtual = resolveKeyed(path, config.virtualEntries)\n\t\t\tif (virtual !== undefined && type.kind === \"image\") {\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"image\",\n\t\t\t\t\tmime: type.mime,\n\t\t\t\t\twidth: virtual.width,\n\t\t\t\t\theight: virtual.height,\n\t\t\t\t\tanimated: virtual.animated ?? false,\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { kind: \"unknown\", reason: \"unavailable\" }\n\t\t},\n\t\tasync hashBytes(path) {\n\t\t\tconst value = resolveValue(path, config.byteHashes, undefined)\n\t\t\tif (value === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no byte hash for \"${path}\"`)\n\t\t\t}\n\t\t\treturn value\n\t\t},\n\t\tasync computeImageHashes(path, kinds) {\n\t\t\tconst result = resolveValue(path, config.imageHashes, undefined)\n\t\t\tif (result === undefined) return undefined\n\t\t\tconst hashes: Record<string, string> = {}\n\t\t\tfor (const entry of result.hashes) {\n\t\t\t\tif ((kinds as readonly string[]).includes(entry.type)) {\n\t\t\t\t\thashes[entry.type] = entry.value\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn hashes as Record<ImageHashKind, string>\n\t\t},\n\t\tasync extractArchive(filename) {\n\t\t\tconst configured = config.extractions?.[filename]\n\t\t\tif (configured === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`ResourceAPIFixture: no extraction configured for \"${filename}\"`,\n\t\t\t\t)\n\t\t\t}\n\t\t\treturn configured\n\t\t},\n\t\tasync listContainer(filename) {\n\t\t\tconst configured = config.containerListings?.[filename]\n\t\t\tif (configured === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`ResourceAPIFixture: no container listing configured for \"${filename}\"`,\n\t\t\t\t)\n\t\t\t}\n\t\t\treturn configured\n\t\t},\n\t\tdownload: (async (\n\t\t\trequest: PluginDownloadRequest \| readonly PluginDownloadRequest[],\n\t\t) => {\n\t\t\tif (config.downloadHandler === undefined) {\n\t\t\t\tthrow pluginAssetError(\n\t\t\t\t\t\"UNAVAILABLE\",\n\t\t\t\t\t\"ResourceAPIFixture: no download handler configured\",\n\t\t\t\t)\n\t\t\t}\n\t\t\tconst result = await config.downloadHandler(request)\n\t\t\t// Mirror the real host: batch in → batch out, single in →\n\t\t\t// single out.\n\t\t\tif (Array.isArray(request)) {\n\t\t\t\treturn Array.isArray(result) ? result : [result]\n\t\t\t}\n\t\t\treturn Array.isArray(result) ? (result[0] ?? result) : result\n\t\t}) as ResourceAPI<TSchema>[\"download\"],\n\t\tasync statAsset(path) {\n\t\t\tconst content = resolveValue(path, config.assetFiles, undefined)\n\t\t\tif (content === undefined) return undefined\n\t\t\treturn { sizeBytes: fixtureContentBytes(content).byteLength }\n\t\t},\n\t\tasync readAsset(path) {\n\t\t\tconst content = resolveValue(path, config.assetFiles, undefined)\n\t\t\tif (content === undefined) {\n\t\t\t\tthrow new Error(`ResourceAPIFixture: no vault file \"${path}\"`)\n\t\t\t}\n\t\t\treturn fixtureContentBytes(content)\n\t\t},\n\t\tasync deleteAsset(path) {\n\t\t\tconst table = config.assetFiles\n\t\t\tif (table === undefined \|\| !Object.hasOwn(table, path)) {\n\t\t\t\treturn { existed: false }\n\t\t\t}\n\t\t\t// Fixture config is immutable in spirit — a delete is simulated\n\t\t\t// by copying with the entry removed, so the next call sees it gone.\n\t\t\tconst next: Record<string, string \| Uint8Array> = {}\n\t\t\tfor (const [key, value] of Object.entries(table)) {\n\t\t\t\tif (key !== path) next[key] = value\n\t\t\t}\n\t\t\tconfig = { ...config, assetFiles: next }\n\t\t\treturn { existed: true }\n\t\t},\n\t}\n\n\treturn { api, setConfig }\n}\n\n/* Convert a fixture content entry (string or bytes) to `Uint8Array`. /\nfunction fixtureContentBytes(content: string \| Uint8Array): Uint8Array {\n\treturn typeof content === \"string\"\n\t\t? new TextEncoder().encode(content)\n\t\t: content\n}\n\n/* Return a minimal {@link Logger} for tests. /\nexport function stubLogger(overrides?: Partial<Logger>): Logger {\n\treturn {\n\t\tinfo() {},\n\t\twarn() {},\n\t\terror() {},\n\t\t...overrides,\n\t}\n}\n","/\n Shared `ok: true/false` result vocabulary (Rust's `Result` in spirit,\n * spread payloads in shape): every site that answers \"did it work?\" —\n * detections, parses, validations, benchmark runs — uses one type\n * family, one pair of constructors and one pair of guards instead of\n * hand-rolling its own union.\n \n The payloads are spread onto the marker rather than carried in a\n * `value`/`error` channel: `ok({ start, end })` is literally\n * `{ ok: true, start, end }`. This keeps every existing consumer's\n * field access (`r.start`, `r.code`, `r.failure`) and every `toEqual`\n * assertion working unchanged, and lets the plugin-facing `{ ok: true }`\n * literal stay the contract.\n /\nexport type Ok<TPayload extends object = object> = {\n\treadonly ok: true\n} & TPayload\nexport type Err<TPayload extends object = object> = {\n\treadonly ok: false\n} & TPayload\nexport type Result<TOk extends object = object, TErr extends object = object> =\n\t\| Ok<TOk>\n\t\| Err<TErr>\n\n/\n Build the success variant; `ok()` alone yields `{ ok: true }`. The\n * cast is the constructor boundary: the runtime value is exactly\n * `{ ok: true, ...payload }`, which the generic spread cannot prove.\n /\nexport function ok<TPayload extends object = object>(\n\tpayload?: TPayload,\n): Ok<TPayload> {\n\treturn { ok: true, ...payload } as Ok<TPayload>\n}\n\n/\n Build the failure variant; `err()` alone yields `{ ok: false }`. See\n * {@link ok} for the constructor-boundary cast.\n /\nexport function err<TPayload extends object = object>(\n\tpayload?: TPayload,\n): Err<TPayload> {\n\treturn { ok: false, ...payload } as Err<TPayload>\n}\n\n/* Narrow a result to its success variant. /\nexport function isOk<TOk extends object, TErr extends object>(\n\tresult: Result<TOk, TErr>,\n): result is Ok<TOk> {\n\treturn result.ok === true\n}\n\n/* Narrow a result to its failure variant. /\nexport function isErr<TOk extends object, TErr extends object>(\n\tresult: Result<TOk, TErr>,\n): result is Err<TErr> {\n\treturn result.ok === false\n}\n\n/\n Destructure a result through one of two handlers — the pattern-match\n * combinator. Both handlers must produce `R`; the chosen one receives\n * the spread payload of its variant.\n */\nexport function matchResult<TOk extends object, TErr extends object, R>(\n\tresult: Result<TOk, TErr>,\n\thandlers: {\n\t\treadonly ok: (payload: Ok<TOk>) => R\n\t\treadonly err: (payload: Err<TErr>) => R\n\t},\n): R {\n\treturn isOk(result) ? handlers.ok(result) : handlers.err(result)\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hoardodile/sdk-types",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
   "description": "Plugin manifest contract, shared types and constants for hoardodile content plugins.",
   "keywords": [

package/src/plugin-definition.ts CHANGED Viewed

@@ -463,6 +463,20 @@ export type PluginDefinition<TSchema extends PluginSchema = PluginSchema> = {
 	readonly imageHashes?: (
 		api: ResourceAPI<TSchema>,
 	) => Promise<ImageHashesResult | undefined>
+	/**
+	 * Optional post-install callback, invoked by the host after a
+	 * successful install or update commit (marketplace install/update and
+	 * zip uploads). Runs with an **install-scoped** API: no resource is
+	 * attached — the file surface answers empty and there is no
+	 * `context.detect` — while the asset methods still work and stay
+	 * gated by the shared consent dialog exactly like the runtime path.
+	 * A throwing (or consent-denied) hook never fails the install; the
+	 * plugin should treat it as best-effort and re-check at runtime.
+	 *
+	 * Typical use: fetch pinned runtime files into the plugin vault once,
+	 * so the first preview opens without a consent dialog.
+	 */
+	readonly onInstall?: (api: ResourceAPI<TSchema>) => Promise<void>
 }
 /** Plugin hook names the host can invoke, in contract order. */
@@ -473,6 +487,7 @@ export const HOOK_NAMES = [
 	"coverLocal",
 	"listFiles",
 	"imageHashes",
+	"onInstall",
 ] as const
 export type HookName = (typeof HOOK_NAMES)[number]