@hoardodile/sdk-types 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,772 @@
+export { C as CoverKindUi, a as CoverKindUiMap, P as PluginManifest, b as PluginManifestId, c as PluginManifestUi, d as PluginPermissions, S as SearchKind } from './manifest-Dk6_xyNy.js';
+import { PluginAssetErrorName } from './plugin-asset-limits.js';
+import { MediaKind } from './media-exts.js';
+import { Result } from './result.js';
+export { Err, Ok, err, isErr, isOk, matchResult, ok } from './result.js';
+export { AnchorData } from './schema.js';
+import 'zod';
+
+/**
+ * One item in a serialized file list: a bare filename string or a
+ * metadata object. Object entries carry `filename` plus any extra
+ * fields; the host renders covers and chips from this shape.
+ */
+type SerializedFileEntry = string | Record<string, string | number | boolean>;
+/**
+ * Serialized file list as stored in the sidecar cache and sent over the
+ * wire. Order is the display order; the host preserves it verbatim.
+ */
+type SerializedFileList = readonly SerializedFileEntry[];
+
+/**
+ * The plugin asset contract — the download / read / delete surface of a
+ * plugin's own "vault". The vault is a host-reserved namespace inside the
+ * plugin's installed directory (`<plugin-dir>/vault/`) that the host
+ * manages on the plugin's behalf: data lands there only through the
+ * user-consented download API, and nothing a plugin ships in its zip can
+ * ever be overwritten by downloading (see the vault-confined `dest`
+ * rules).
+ *
+ * Both sides of the plugin speak the same shapes: the server-side
+ * `ResourceAPI` (main.js hooks) and the iframe `WebPluginAPI` (render)
+ * call the same four methods with the same request/result vocabulary.
+ * All methods are gated by the manifest `download` permission and
+ * denied inside the sandbox when the manifest does not declare it.
+ *
+ * Error convention (fixed rule): **classification uses `Result`,
+ * API calls throw.** `detect` (and other classifiers) return a
+ * {@link Result}; every other API method rejects with an `Error` whose
+ * `name` carries the machine-readable code. Plugins branch on
+ * {@link isPluginAssetError} — never parse messages.
+ *
+ * Runtime limits live behind `@hoardodile/sdk-types/plugin-asset-limits`;
+ * this module exports the types and the error helpers only.
+ */
+
+/**
+ * A download request: the plugin declares the plaintext URL, the vault
+ * destination, and (optionally) an integrity pin plus a reason for the
+ * consent dialog. `dest` is vault-relative only — it must resolve under
+ * `<plugin-dir>/vault/` and can never reach the plugin's own bundled
+ * files (`main.js`, `index.html`, `assets/`, ...).
+ */
+type PluginDownloadRequest = {
+    /** Absolute `http(s)` URL to fetch. Shown verbatim in the consent dialog. */
+    readonly url: string;
+    /**
+     * Vault-relative destination path (`"runtime/live2d.min.js"`). The host
+     * resolves it inside the plugin vault and rejects absolute paths,
+     * `..` traversal, path separators crossing segments, and reserved
+     * names — before any network request is made.
+     */
+    readonly dest: string;
+    /**
+     * Optional SRI-style integrity pin (64 lowercase hex chars). When
+     * present the host verifies the downloaded bytes against it and
+     * discards a mismatch, so a tampered or corrupted response can
+     * never be stored.
+     */
+    readonly sha256?: string;
+    /** Optional short rationale shown in the consent dialog (plugin-authored copy). */
+    readonly reason?: string;
+};
+/**
+ * Result of {@link PluginDownloadRequest}: the stored file's identity.
+ * `cached` is true when the destination already existed — the host
+ * answered from the vault without any dialog and without touching the
+ * network (downloads are "ensure present", never unconditional).
+ */
+type PluginDownloadResult = {
+    /** The vault-relative destination that was resolved. */
+    readonly path: string;
+    readonly sizeBytes: number;
+    /** sha256 of the stored bytes (host-computed, always present). */
+    readonly sha256: string;
+    /** True when the file already existed and no consent/network was needed. */
+    readonly cached: boolean;
+};
+/**
+ * Result of {@link ResourceAPI.deleteAsset} / `WebPluginAPI.deleteAsset`.
+ * Deletion is idempotent: removing nothing is not an error.
+ */
+type PluginAssetDeleteResult = {
+    /** True when a file was actually removed. */
+    readonly existed: boolean;
+};
+/**
+ * Error thrown by the asset methods. The name survives both wire
+ * boundaries (worker IPC and the iframe postMessage bridge), so plugin
+ * code can branch on `err.name` without parsing messages:
+ *
+ * - `DENIED` — the user declined the consent dialog, or consent timed out.
+ * - `UNAVAILABLE` — this runtime has no consent channel (CLI, workbench,
+ *   offline mock) or the server is in read-only archive mode.
+ * - `POLICY` — the host rejected the request before downloading:
+ *   manifest lacks the `download` permission, the URL or `dest` is not
+ *   allowed, the destination is a directory, or a quota would be
+ *   exceeded. Also used for reserved-name conflicts.
+ *
+ * Transport/network failures keep their own error names (e.g. socket
+ * errors) and are not part of this vocabulary.
+ */
+declare class PluginAssetError extends Error {
+    readonly code: PluginAssetErrorName;
+    constructor(code: PluginAssetErrorName, message: string);
+}
+/**
+ * Narrow an asset error to a machine-readable name. Works across the
+ * RPC boundaries because both preserve `Error.name` (the worker IPC and
+ * the iframe bridge carry the name explicitly) — the instance is often
+ * lost in transit, so the check keys on the name alone.
+ */
+declare function isPluginAssetError(err: unknown, name: PluginAssetErrorName): err is PluginAssetError;
+/** Build a `PluginAssetError` carrying the given machine-readable name. */
+declare function pluginAssetError(name: PluginAssetErrorName, message: string): PluginAssetError;
+
+/**
+ * Byte range used by every file read across the plugin stack — the
+ * server-side `ResourceAPI.readFile` (see `@hoardodile/host`) and the
+ * browser-side `PluginRequests.readFile` (see `@hoardodile/sdk-web`) —
+ * so the contract lives exactly once. `start` is inclusive (default 0),
+ * `end` is exclusive (default end of file). Hosts clamp the range to the
+ * file size; a range at or past the end resolves to an empty result.
+ */
+type ReadFileRange = {
+    readonly start?: number;
+    readonly end?: number;
+};
+
+/**
+ * The plugin definition contract — the single source of truth shared by
+ * the authoring SDK (`@hoardodile/sdk-server`), the runtime host
+ * (`@hoardodile/host`) and the worker sandbox. Everything here is pure
+ * TypeScript with no node or DOM dependencies, so the same contract
+ * serves browser-facing packages and node runtimes alike.
+ */
+
+/**
+ * Schema contract shared between server and web plugin APIs.
+ * Declared once per plugin and used to type both `definePlugin` and
+ * `WebPluginAPI`.
+ */
+interface PluginSchema {
+    readonly file?: unknown;
+    readonly sourceMeta?: unknown;
+    readonly searchMeta?: unknown;
+    /**
+     * Plugin-defined payload the `detect` hook may carry on a
+     * successful match. The host keeps the last payload and exposes it
+     * to the plugin's other hooks as `api.context.detect` — classify
+     * once in `detect` instead of rescanning in every hook. Declaring
+     * this slot types the context; hooks must still handle the absent
+     * case (`undefined`: fresh worker, or detect never matched).
+     */
+    readonly detect?: unknown;
+    /**
+     * Plugin-defined anchor location data: the payload carried inside the
+     * wire {@link AnchorData} envelope (see {@link anchorData}). Outgoing
+     * anchors are typed by this slot and passed raw (e.g.
+     * `createMessage({ anchor: { page } })`); incoming anchor data is
+     * validated by the plugin's `decodeAnchor` (see `definePluginAPI` in
+     * `@hoardodile/sdk-react`).
+     */
+    readonly anchor?: unknown;
+}
+/**
+ * Server plugin detection result: the shared result vocabulary, where a
+ * match carries the schema's `detect` payload (when one is declared)
+ * and a miss carries its reasons. Plugins may return the literal
+ * `{ ok: true } as const` / `{ ok: false, reasons }` shapes directly,
+ * or use `ok()`/`err({ reasons })` from the result module.
+ *
+ * `TPayload` is the plugin's declared `detect` slot — the payload
+ * spread onto a match is checked against it at compile time, so a
+ * classification that drifts from the schema fails to build.
+ */
+type Detection<TPayload extends object = object> = Result<TPayload, {
+    readonly reasons: readonly string[];
+}>;
+/** Structured logger scoped to a single plugin. */
+type Logger = {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+};
+/** Image probe payload. */
+type ImageInfo = {
+    readonly width?: number;
+    readonly height?: number;
+};
+/** Video probe payload. */
+type VideoInfo = {
+    readonly width?: number;
+    readonly height?: number;
+    readonly durationMs?: number;
+};
+/**
+ * Embedded container tags carried by an audio file (ID3, Vorbis
+ * comments, MP4 metadata atoms). Every field is optional — untagged
+ * files are normal.
+ */
+type AudioTags = {
+    readonly title?: string;
+    readonly artist?: string;
+    readonly album?: string;
+};
+/**
+ * Embedded artwork carried by an audio file (ID3 APIC, FLAC PICTURE,
+ * MP4 `covr`). Its presence is the signal that the host can extract a
+ * real cover; the dimensions come from the same probe, so callers can
+ * pre-size the cover slot without decoding the picture.
+ */
+type AudioCoverArt = {
+    readonly width?: number;
+    readonly height?: number;
+};
+/**
+ * Audio probe payload. Any field can be absent when the container does
+ * not report it.
+ */
+type AudioInfo = {
+    readonly durationMs?: number;
+    /** Codec name of the first audio stream, e.g. `"mp3"`, `"flac"`. */
+    readonly codec?: string;
+    /** Container bit rate in bits per second. */
+    readonly bitRate?: number;
+    /** Sample rate of the first audio stream, in Hz. */
+    readonly sampleRate?: number;
+    /** Channel count of the first audio stream. */
+    readonly channels?: number;
+    /** Present only when the file embeds artwork. */
+    readonly coverArt?: AudioCoverArt;
+    readonly tags?: AudioTags;
+};
+/**
+ * What a file's bytes say it is. Produced by {@link ResourceAPI.sniff}.
+ *
+ * `source` records who answered: `"magic"` means the file's own
+ * signature was recognized (authoritative), `"extension"` means the
+ * content carried no signature and the filename was used instead — the
+ * normal outcome for text-based formats, which have no magic bytes.
+ *
+ * `kind` is provisional for container formats that can hold either
+ * audio or video (Ogg, Matroska, ISO-BMFF); {@link ResourceAPI.probe}
+ * overrides it with the stream layout actually found in the file.
+ */
+type FileType = {
+    /** Canonical MIME type, e.g. `"image/jpeg"`. */
+    readonly mime: string;
+    /** Canonical extension for {@link mime}, with leading dot. */
+    readonly ext: string;
+    readonly kind: MediaKind;
+    readonly source: "magic" | "extension";
+};
+/**
+ * Everything one media probe pass can say about a file, discriminated
+ * by the family the content really belongs to — the shape every
+ * mainstream prober uses (ffprobe's `format` + `streams`, sharp's
+ * `metadata()`, Tika's `MediaType`).
+ *
+ * `other` is a successful answer: the file was identified and is not
+ * decodable media (text, documents, archives). `unknown` is the failure
+ * branch and always carries a reason, so "this host has no probe
+ * backend" is never confused with "this file is not an image":
+ *
+ * - `unsupported` — identified, but no backend decodes this format
+ * - `unavailable` — the host wired no probe implementation (raw
+ *   directory APIs and test fixtures)
+ * - `failed` — a backend ran and could not decode the bytes
+ */
+type ProbeResult = ({
+    readonly kind: "image";
+    readonly mime: string;
+    /** Multi-frame source: animated GIF / WebP / APNG / AVIF. */
+    readonly animated: boolean;
+} & ImageInfo) | ({
+    readonly kind: "video";
+    readonly mime: string;
+} & VideoInfo) | ({
+    readonly kind: "audio";
+    readonly mime: string;
+} & AudioInfo) | {
+    readonly kind: "other";
+    readonly mime: string;
+} | {
+    readonly kind: "unknown";
+    readonly reason: "unsupported" | "unavailable" | "failed";
+};
+/**
+ * Perceptual hash kinds the host can compute for an image file.
+ * `dhash` (difference hash) and `phash` (DCT-based perceptual hash)
+ * are 64-bit similarity hashes compared by Hamming distance;
+ * `sha256` is an exact byte hash. Animated images hash their first
+ * frame. Plugins decide which kinds to request and which files to
+ * hash — the host only provides the computation.
+ */
+declare const IMAGE_HASH_KINDS: readonly ["sha256", "dhash", "phash"];
+type ImageHashKind = (typeof IMAGE_HASH_KINDS)[number];
+/**
+ * One content hash of a resource file, produced by the plugin's
+ * `imageHashes` hook. `scope` is the archive-relative file path,
+ * `type` the hash kind (`sha256`/`dhash`/`phash` or a plugin-defined
+ * extension), `value` the lowercase hex digest. A resource may expose
+ * several hashes (per file × per kind) or none.
+ */
+type ImageHash = {
+    readonly scope: string;
+    readonly type: string;
+    readonly value: string;
+    /** Bit length of the hash; required for perceptual kinds. */
+    readonly bits?: number;
+};
+/** Result of the `imageHashes` hook: hashes per file, possibly empty. */
+type ImageHashesResult = {
+    readonly hashes: readonly ImageHash[];
+};
+/**
+ * One file inside a container entry (zip/tar) as listed (or extracted)
+ * by the plugin API. `path` is the entry's path inside the archive;
+ * dimensions are present when the host probed the entry (image
+ * backends) — a listing-only result carries no dimensions.
+ */
+type ArchiveExtractionEntry = {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly kind: MediaKind;
+    readonly width?: number;
+    readonly height?: number;
+    readonly animated?: boolean;
+};
+/**
+ * A container listing without materialization — the cheap counterpart of
+ * {@link ResourceAPI.extractArchive}. Carries entry names, sizes and
+ * kinds only; no dimensions (probing those requires the bytes).
+ */
+type ContainerListing = {
+    readonly entries: readonly ArchiveExtractionEntry[];
+};
+/**
+ * Result of {@link ResourceAPI.extractArchive}: the materialized
+ * entries of a container entry. A completed extraction is marked by the
+ * host's `index.json` manifest; extraction always writes the cache (the
+ * host's `local/cache` is derived data, writable in every view mode).
+ */
+type ArchiveExtraction = {
+    readonly entries: readonly ArchiveExtractionEntry[];
+};
+/**
+ * Resource-scoped API available to every plugin hook. All paths are
+ * relative to the resource's source directory; the host resolves
+ * absolute paths transparently.
+ *
+ * `TSchema` types the injected session context (`context.detect`); the
+ * default keeps the API compatible with code that never reads it.
+ */
+type ResourceAPI<TSchema extends PluginSchema = PluginSchema> = {
+    /** Write an informational log entry. */
+    readonly logInfo: (message: string, data?: Record<string, unknown>) => void;
+    /** Write a warning log entry. */
+    readonly logWarn: (message: string, data?: Record<string, unknown>) => void;
+    /** Write an error log entry. */
+    readonly logError: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * List all regular-file names (flat list), in canonical display
+     * order: the resource's explicit upload order when one exists (the
+     * host's `.order` manifest), the natural name sort otherwise.
+     * Plugins that need their own ordering should sort explicitly.
+     *
+     * This is the raw name list — the `listFiles` hook of the plugin
+     * definition turns it into typed file entries.
+     */
+    readonly listFileNames: () => Promise<readonly string[]>;
+    /**
+     * Read a regular file relative to the resource root.
+     *
+     * Without `range` the whole file is returned; hosts may reject
+     * oversized full reads — pass a range (or use `readFileChunks` from
+     * `@hoardodile/sdk-server/helpers`) for large files.
+     *
+     * Container addressing: a path of the form `outer!inner` reads the
+     * file *inside* a zip/tar entry (e.g. `manga.cbz!Chapter 1/001.jpg`)
+     * — the host streams the decompressed bytes. When `outer` is not a
+     * container, or the inner entry is absent, the whole path is treated
+     * as a literal filename.
+     */
+    readonly readFile: (path: string, range?: ReadFileRange) => Promise<Uint8Array>;
+    /**
+     * Return the byte size of `path` without reading the file contents.
+     * Resolves to `undefined` when the file does not exist or the artifact
+     * is not yet committed. Supports container addressing (`outer!inner`).
+     */
+    readonly statFile: (path: string) => Promise<{
+        readonly sizeBytes: number;
+    } | undefined>;
+    /**
+     * Batch {@link statFile}: resolves every path in one host round-trip
+     * (positions preserved). Prefer this over a per-file fan-out of
+     * `statFile` when statting a whole archive — one RPC instead of N.
+     */
+    readonly statFiles: (paths: readonly string[]) => Promise<readonly ({
+        readonly sizeBytes: number;
+    } | undefined)[]>;
+    /**
+     * Identify the file at `path` from its content: magic-byte
+     * detection, falling back to the extension only for formats that
+     * carry no signature (text, subtitles). Resolves to `undefined` when
+     * neither can name the file. Supports container addressing.
+     *
+     * This is the cheap call — it reads a small header window, never
+     * decodes. Use it to route work; use {@link probe} when you need
+     * dimensions, duration or stream details.
+     */
+    readonly sniff: (path: string) => Promise<FileType | undefined>;
+    /**
+     * Decode the media metadata of `path` in one pass, routed by
+     * {@link sniff} rather than by the filename: images resolve through
+     * sharp, audio and video through ffprobe (which also settles
+     * ambiguous containers — an `.ogg` holding only audio streams comes
+     * back as `kind: "audio"`). Supports container addressing.
+     *
+     * Always resolves, never rejects. Non-media files answer
+     * `{ kind: "other" }`; the `unknown` branch carries a `reason` that
+     * distinguishes "no backend wired" (`unavailable`, what raw
+     * directory APIs and fixtures return) from a real decode failure.
+     */
+    readonly probe: (path: string) => Promise<ProbeResult>;
+    /**
+     * Stream-hash the file at `path` (any file kind). Rejects when the
+     * file is missing or the read fails; the host streams the entry so
+     * arbitrarily large files are safe. Supports container addressing.
+     */
+    readonly hashBytes: (path: string, algo: "md5" | "sha256") => Promise<string>;
+    /**
+     * Compute the requested hashes of the image at `path` in one pass:
+     * `sha256` from the raw bytes, `dhash`/`phash` from a decoded
+     * grayscale rendition (animated images use their first frame).
+     * Resolves to `undefined` when the file is not a decodable image;
+     * `kinds` names a subset of {@link IMAGE_HASH_KINDS} and the result
+     * carries exactly those keys. Supports container addressing.
+     */
+    readonly computeImageHashes: (path: string, kinds: readonly ImageHashKind[]) => Promise<Readonly<Record<ImageHashKind, string>> | undefined>;
+    /**
+     * List the file entries of a container entry (zip/tar) without
+     * materializing anything — the cheap call for metadata-only needs
+     * (detect, card counts). Rejects when `filename` is not a supported
+     * container.
+     */
+    readonly listContainer: (filename: string) => Promise<ContainerListing>;
+    /**
+     * Materialize the contents of a container entry (zip/tar) into the
+     * host's extraction cache so the browser can serve the inner files
+     * over plain URLs. `filename` is a literal container entry — the
+     * cache holds one directory per archive with the inner paths
+     * preserved, plus a completion manifest.
+     *
+     * Idempotent: an already-materialized archive re-lists from the
+     * manifest without re-extracting. Rejects when the entry is not a
+     * supported container, exceeds the host's byte/entry budgets, or
+     * when this host wires no extraction cache (test fixtures, raw
+     * directory APIs).
+     */
+    readonly extractArchive: (filename: string) => Promise<ArchiveExtraction>;
+    /**
+     * Ensure a remote asset exists in the plugin's own vault: when
+     * `dest` is already present the host answers `cached: true` without
+     * any dialog and without touching the network; otherwise the host
+     * asks the user (the web app shows the consent dialog with the URL
+     * verbatim) and downloads on approval. The file always lands inside
+     * `<plugin-dir>/vault/` — `dest` is vault-relative and can never
+     * reach the plugin's bundled files.
+     *
+     * Gated by the manifest `download` permission; rejections carry a
+     * machine-readable {@link PluginAssetErrorName} in `err.name`
+     * (`DENIED` / `UNAVAILABLE` / `POLICY`).
+     */
+    readonly download: (request: PluginDownloadRequest) => Promise<PluginDownloadResult>;
+    /**
+     * Byte size of a vault file, or `undefined` when absent. The cheap
+     * presence check on top of which `download` resolves cached hits.
+     */
+    readonly statAsset: (path: string) => Promise<{
+        readonly sizeBytes: number;
+    } | undefined>;
+    /** Read a vault file's bytes (bounded by the same cap as {@link readFile}). */
+    readonly readAsset: (path: string) => Promise<Uint8Array>;
+    /**
+     * Remove a vault file; idempotent (absent files answer
+     * `{ existed: false }`). The plugin decides the vault's own
+     * lifecycle — e.g. cleaning stale layouts after a plugin update.
+     * No user consent is required: nothing leaves the host. Directories
+     * and paths outside the vault are rejected (`POLICY`).
+     */
+    readonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>;
+    /**
+     * Session context injected by the host. `detect` carries the payload
+     * the plugin's `detect` hook returned on its last successful match
+     * (worker-session scope): the one-pass classification every other
+     * hook can build on. `undefined` when detect has not matched in this
+     * session — a fresh worker — so hooks must always handle the absent
+     * case by re-deriving.
+     */
+    readonly context: {
+        readonly detect: TSchema["detect"] | undefined;
+    };
+};
+/**
+ * Declarative description of a content plugin. Plugins export an instance
+ * of this shape as their default export; the host injects the resource
+ * API at call time and never invokes a factory function.
+ */
+type PluginDefinition<TSchema extends PluginSchema = PluginSchema> = {
+    /**
+     * Detect whether this plugin applies to the current resource. A
+     * successful match may carry a payload — `ok({ ...shape })` — which
+     * the host keeps and exposes to the other hooks as
+     * `api.context.detect`. The payload is checked against the schema's
+     * `detect` slot (when one is declared).
+     */
+    readonly detect: (api: ResourceAPI<TSchema>) => Promise<Detection<TSchema["detect"] & object>>;
+    /** Optional source metadata builder. */
+    readonly sourceMeta?: (api: ResourceAPI<TSchema>) => Promise<TSchema["sourceMeta"] | undefined>;
+    /** Optional search metadata builder. */
+    readonly searchMeta?: (api: ResourceAPI<TSchema>) => Promise<TSchema["searchMeta"] | undefined>;
+    /** Optional local cover source resolver. */
+    readonly coverLocal?: (api: ResourceAPI<TSchema>) => Promise<string | undefined>;
+    /**
+     * Optional custom file list builder. Results are cached verbatim in a
+     * sidecar. When absent the host falls back to a bare list of source
+     * filenames.
+     */
+    readonly listFiles?: (api: ResourceAPI<TSchema>) => Promise<readonly TSchema["file"][]>;
+    /**
+     * Optional content hashes for duplicate detection and image
+     * similarity. The plugin decides the policy — which files to hash
+     * and which kinds — by calling the API's hash primitives; a plugin
+     * facing image-less resources simply omits this hook. Returning
+     * `undefined` (or a hook error) keeps the resource's hash rows empty.
+     */
+    readonly imageHashes?: (api: ResourceAPI<TSchema>) => Promise<ImageHashesResult | undefined>;
+};
+/** Plugin hook names the host can invoke, in contract order. */
+declare const HOOK_NAMES: readonly ["detect", "sourceMeta", "searchMeta", "coverLocal", "listFiles", "imageHashes"];
+type HookName = (typeof HOOK_NAMES)[number];
+/**
+ * Freeze and return a plugin definition. Runs shape validation upfront so
+ * a malformed plugin fails at load time with a friendly message instead
+ * of misbehaving at hook time.
+ */
+declare function definePlugin<TSchema extends PluginSchema = PluginSchema>(definition: PluginDefinition<TSchema>): PluginDefinition<TSchema>;
+/**
+ * Validate that a value satisfies the structural contract of a
+ * {@link PluginDefinition}: only known hooks, all hooks async functions,
+ * `detect` required. Does NOT exercise behaviour.
+ */
+declare function assertPluginShape(value: unknown): asserts value is PluginDefinition;
+/**
+ * Convenience wrapper that builds a failing plugin definition. Used by
+ * the host when a plugin directory is missing or its main.js cannot be
+ * loaded.
+ */
+declare function createFailingPlugin(reasons: readonly string[]): PluginDefinition;
+/** Type guard for the success branch of a {@link Detection}. */
+declare function isDetected(detection: Detection): detection is {
+    readonly ok: true;
+};
+/** Type guard for the failure branch of a {@link Detection}. */
+declare function isMissed(detection: Detection): detection is {
+    readonly ok: false;
+    readonly reasons: readonly string[];
+};
+/** Declarative configuration for a {@link ResourceAPI} fixture. */
+type ResourceAPIFixtureConfig<TSchema extends PluginSchema = PluginSchema> = {
+    /** File names returned by `listFileNames`. */
+    readonly files?: readonly string[];
+    /** File contents returned by `readFile`. */
+    readonly contents?: Readonly<Record<string, string | Uint8Array>>;
+    /**
+     * `sniff` results keyed by file path — `{ "a.jpg": … }` matches only
+     * that file, keys starting with a dot match by extension suffix
+     * (`{ ".mp4": … }` applies to every .mp4 file, longest key wins),
+     * and `{ "": … }` matches every path (the usual way to express a
+     * default). Unconfigured paths fall back to the extension table,
+     * exactly like the host's extension branch.
+     */
+    readonly types?: Readonly<Record<string, FileType | undefined>>;
+    /**
+     * `probe` results keyed by file path (same matching rules as
+     * {@link types}). Unconfigured paths mirror the host's routing:
+     * identified non-media answers `{ kind: "other" }`, identified media
+     * answers `{ kind: "unknown", reason: "unavailable" }` — the fixture
+     * decodes nothing, so a hook that needs real dimensions belongs in a
+     * sandbox test instead.
+     */
+    readonly probes?: Readonly<Record<string, ProbeResult | undefined>>;
+    /** Stat results. A plain value is used as the default for all paths. */
+    readonly stats?: Readonly<Record<string, {
+        readonly sizeBytes: number;
+    } | undefined>> | {
+        readonly sizeBytes: number;
+    } | undefined;
+    /** `hashBytes` results by path; a plain string is used for all paths. */
+    readonly byteHashes?: Readonly<Record<string, string>> | string;
+    /**
+     * `computeImageHashes` results by path. A plain record is used as the
+     * default for all paths; absent paths resolve to `undefined`.
+     */
+    readonly imageHashes?: Readonly<Record<string, ImageHashesResult>> | ImageHashesResult;
+    /**
+     * `listContainer` results keyed by the archive filename. Absent
+     * names reject, mirroring the host's "not a supported archive" error.
+     */
+    readonly containerListings?: Readonly<Record<string, ContainerListing>>;
+    /**
+     * `extractArchive` results keyed by the archive filename. Absent
+     * names reject, mirroring the host's "not a supported archive" error.
+     */
+    readonly extractions?: Readonly<Record<string, ArchiveExtraction>>;
+    /**
+     * Vault file contents keyed by vault-relative path, backing
+     * `statAsset` / `readAsset` / `deleteAsset` in the fixture.
+     */
+    readonly assetFiles?: Readonly<Record<string, string | Uint8Array>>;
+    /**
+     * Handler for `download`. Absent means the hosted runtime has no
+     * consent channel — `download` rejects with `UNAVAILABLE`, exactly
+     * like the CLI, workbench and offline mock hosts.
+     */
+    readonly downloadHandler?: (request: PluginDownloadRequest) => Promise<PluginDownloadResult>;
+    /**
+     * Container addressing for the fixture: maps a virtual path
+     * (`outer!inner`) to stat/sniff/probe results, so hooks that browse
+     * inside archives can be tested without real archives. Matching rules
+     * mirror {@link types}: exact path keys, dot fragments by suffix,
+     * `{ "": … }` as the default.
+     */
+    readonly virtualEntries?: Readonly<Record<string, ArchiveExtractionEntry>>;
+    /**
+     * Session context handed to hooks as `api.context` — mirrors the
+     * host injecting the payload of a prior successful `detect`. Typed
+     * by the schema generic when one is supplied.
+     */
+    readonly context?: {
+        readonly detect?: TSchema["detect"];
+    };
+};
+/**
+ * Identify a file from its name alone: the extension branch of content
+ * sniffing, exposed on its own because it is also the honest answer for
+ * formats that carry no signature, and the shape test doubles need when
+ * standing in for a real {@link ResourceAPI}.
+ */
+declare function fileTypeFromName(path: string): FileType | undefined;
+/**
+ * Create a mutable {@link ResourceAPI} fixture driven by a declarative
+ * config. No filesystem involved — the standard way to unit-test plugin
+ * hooks.
+ *
+ * Pass the plugin's schema as the generic
+ * (`createResourceAPIFixture<MySchema>()`) so the returned api carries
+ * the typed session context — the same shape schema-typed hooks receive
+ * from the host.
+ */
+declare function createResourceAPIFixture<TSchema extends PluginSchema = PluginSchema>(initialConfig?: ResourceAPIFixtureConfig<TSchema>): {
+    readonly api: ResourceAPI<TSchema>;
+    readonly setConfig: (next: ResourceAPIFixtureConfig<TSchema>) => void;
+};
+/** Return a minimal {@link Logger} for tests. */
+declare function stubLogger(overrides?: Partial<Logger>): Logger;
+
+/**
+ * @hoardodile/sdk-types — the plugin contract: manifest schema, the
+ * plugin definition contract (`PluginDefinition`/`ResourceAPI`/
+ * `definePlugin`/fixtures), and the shared message/danmaku/anchor wire
+ * shapes. Single source of truth consumed by every SDK package, the
+ * host, and the app; nothing here touches the DOM or node.
+ *
+ * This package is the contract — plugins normally import it for types
+ * (`PluginSchema`, `PluginManifest`, ...) and (via
+ * `@hoardodile/sdk-server`) the `definePlugin` factory. The zod
+ * runtime validators (`pluginManifest`, `anchorData`) live behind the
+ * `@hoardodile/sdk-types/schema` subpath so plugin bundles never pull
+ * zod.
+ *
+ * Plugin-facing constants (data, plus the pure lookups that read it)
+ * live in subpaths mirroring their source files — there is no root
+ * export for them:
+ *
+ * - `@hoardodile/sdk-types/image-variant` — derived-image variant
+ *   contract: spec types, query parsing/encoding, canonical cache
+ *   identity
+ * - `@hoardodile/sdk-types/media-exts` — media-type tables: extension
+ *   sets, extension ↔ MIME, MIME ↔ media kind
+ * - `@hoardodile/sdk-types/plugin` — plugin runtime limits (read cap,
+ *   probe/stat fan-out bounds)
+ * - `@hoardodile/sdk-types/resource` — resource caps (search-meta version,
+ *   preview eligibility)
+ * - `@hoardodile/sdk-types/template` — the host cover/message template
+ *   grammar (fragment splitter, tokeniser, parser — shared with the
+ *   web renderer and the CLI's build-time lint)
+ * - `@hoardodile/sdk-types/text-limits` — plugin input limits (danmaku
+ *   body, comment body)
+ *
+ * App-only constants live in `@hoardodile/shared` (infra limits) and
+ * `@hoardodile/schemas` (field lengths) instead.
+ */
+
+/** Web plugin danmaku mode. */
+type DanmakuMode = "scroll" | "top" | "bottom";
+/**
+ * Client-side danmaku list filter: every entry is matched by strict
+ * equality against the same key in the danmaku's anchor `data`. Keys are
+ * plugin-defined vocabulary (e.g. `{ kind: "videoTime", filename }` in
+ * an official content plugin) — the SDK only defines the matching semantics,
+ * not which keys exist.
+ */
+type DanmakuListFilter = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Anchor as returned in `Message` / `Danmaku` API shapes: the resource
+ * the anchor points into plus the plugin location payload. The server
+ * derives `resId` from the row's own `anchor_resource_id` column —
+ * plugin code never supplies it (see `anchorData` in
+ * `@hoardodile/sdk-types/schema`).
+ */
+type ResAnchor = {
+    readonly resId: string;
+    readonly data?: unknown;
+};
+/** Web plugin message shape. */
+type Message = {
+    readonly id: string;
+    readonly parentId?: string;
+    readonly body: string;
+    readonly createdAt: number;
+    readonly deletedAt?: number;
+    readonly charIds: readonly string[];
+    readonly resIds: readonly string[];
+    readonly likeCount: number;
+    readonly dislikeCount: number;
+    readonly replyCount: number;
+    readonly floor?: number;
+    readonly anchor?: ResAnchor;
+};
+/** Web plugin danmaku shape. */
+type Danmaku = {
+    readonly id: string;
+    readonly anchor: ResAnchor;
+    readonly text: string;
+    readonly color: string;
+    readonly mode: DanmakuMode;
+    readonly createdAt: number;
+};
+/** Plugin-facing file stats slice of a resource. */
+type FileStats = {
+    readonly sizeBytes?: number;
+    readonly count?: number;
+};
+/** Plugin-produced search metadata. The host enforces its own schema at ingestion time. */
+type SearchMeta = {
+    readonly v: number;
+    readonly facets?: Readonly<Record<string, boolean>>;
+};
+
+export { type ArchiveExtraction, type ArchiveExtractionEntry, type AudioCoverArt, type AudioInfo, type AudioTags, type ContainerListing, type Danmaku, type DanmakuListFilter, type DanmakuMode, type Detection, type FileStats, type FileType, HOOK_NAMES, type HookName, IMAGE_HASH_KINDS, type ImageHash, type ImageHashKind, type ImageHashesResult, type ImageInfo, type Logger, MediaKind, type Message, type PluginAssetDeleteResult, PluginAssetError, PluginAssetErrorName, type PluginDefinition, type PluginDownloadRequest, type PluginDownloadResult, type PluginSchema, type ProbeResult, type ReadFileRange, type ResAnchor, type ResourceAPI, type ResourceAPIFixtureConfig, Result, type SearchMeta, type SerializedFileEntry, type SerializedFileList, type VideoInfo, assertPluginShape, createFailingPlugin, createResourceAPIFixture, definePlugin, fileTypeFromName, isDetected, isMissed, isPluginAssetError, pluginAssetError, stubLogger };