@hoardodile/sdk-web 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,727 @@
+import * as _hoardodile_sdk_types from '@hoardodile/sdk-types';
+import { SerializedFileList, ReadFileRange, PluginDownloadRequest, PluginDownloadResult, PluginAssetDeleteResult, SearchMeta, FileStats, PluginSchema, Message, DanmakuListFilter, Danmaku, DanmakuMode, AnchorData } from '@hoardodile/sdk-types';
+export { AnchorData, Danmaku, DanmakuListFilter, DanmakuMode, FileStats, Message, ReadFileRange, ResAnchor } from '@hoardodile/sdk-types';
+import { ImageVariantSpec } from '@hoardodile/sdk-types/image-variant';
+export { ImageVariantSpec } from '@hoardodile/sdk-types/image-variant';
+
+/**
+ * Wire protocol version shared between the plugin SDK and the browser
+ * host. Bumped only on incompatible protocol changes. Plugins stamp every
+ * outbound message with it; the host warns loudly when a plugin was built
+ * against a different version.
+ */
+declare const PROTOCOL_VERSION: 1;
+
+type PluginResolvedTheme = "light" | "dark";
+/**
+ * Canonical list of theme palette ids — the single source of truth shared
+ * by the host app and every plugin. `mono` is the default and has no CSS
+ * class (it lives in `:root` / `.dark`); every other id maps to a
+ * `.theme-<id>` block in `@hoardodile/ui/theme.css` and a
+ * `theme.palette.<id>` i18n label.
+ */
+declare const pluginThemePalettes: readonly ["mono", "sage", "parchment", "azure", "hoardodile"];
+type PluginThemePalette = (typeof pluginThemePalettes)[number];
+/** Icon rendering style as chosen in host Settings → Icons. */
+type PluginIconStyle = "duotone" | "grayscale" | "linear";
+/** Host app font as observed by the plugin. */
+type PluginFonts = {
+    /** CSS `font-family` stack; empty when the plugin opted out of inheritance. */
+    readonly family: string;
+    /** Absolute paths (`/fonts/...`) of the preset stylesheets backing the stack. */
+    readonly cssPaths: readonly string[];
+};
+/**
+ * Context injected into the iframe as `window.__context__` and pushed via
+ * the `context` host push. Not a one-shot: the host may push a replacement
+ * context at any time (a pooled iframe is rebound across resources without
+ * a reload), and every push re-invokes the `mountPlugin` mount callback.
+ */
+type PluginIframeContext = {
+    readonly pluginId: string;
+    readonly resId: string;
+    readonly resName: string;
+    readonly sourceMeta: unknown;
+    readonly searchMeta: SearchMeta | undefined;
+    readonly fileStats: FileStats | undefined;
+    readonly contentPluginId: string;
+    /** Current UI language code. The iframe uses this to select its own locale bundle. */
+    readonly language: string;
+    /** Current resolved theme (light or dark). */
+    readonly resolvedTheme: PluginResolvedTheme;
+    /** Current theme palette. */
+    readonly palette: PluginThemePalette;
+    /** Current icon rendering style (Settings → Icons). */
+    readonly iconStyle: PluginIconStyle;
+    /**
+     * Host app font to apply inside the iframe: a CSS `font-family` stack
+     * plus the preset stylesheets that back it. An empty family means the
+     * plugin opted out (`ui.inheritFont: false`) and keeps its own fonts.
+     */
+    readonly fonts: PluginFonts;
+    /** Initial plugin-scoped prefs (unprefixed keys) loaded from server. */
+    readonly initialPrefs: Record<string, string>;
+    /** Initial plugin+resId cache entries (unprefixed keys) loaded from server. */
+    readonly initialCache: Record<string, string>;
+    /**
+     * Short-lived token that lets the sandboxed iframe fetch resource files
+     * without a session cookie (null-origin iframe cannot send SameSite cookies).
+     */
+    readonly fileToken: string;
+    /**
+     * Short-lived token for the plugin's own asset vault URLs
+     * (`/api/plugin-assets/<pluginId>/<token>/<path>`), issued only when
+     * the plugin's manifest declares the `download` permission. Empty
+     * string otherwise — `resolveAssetUrl` throws on the empty token
+     * (never builds a malformed `/…//path` URL); check the permission
+     * before relying on vault URLs.
+     */
+    readonly assetToken: string;
+};
+/** Wire request from plugin (iframe) to host. */
+type PluginRequest = {
+    readonly type: "request";
+    readonly id: number;
+    readonly method: string;
+    readonly params?: unknown;
+    /** Wire protocol version the plugin was built against (see {@link PROTOCOL_VERSION}). */
+    readonly proto?: number;
+    /**
+     * SDK-internal scope stamp: the resource the request was issued for,
+     * captured by the runtime when the plugin called the API. The host
+     * drops the request as stale when the stamp no longer matches the
+     * iframe's binding (e.g. an unmount flush racing a rebind), so late
+     * requests never leak into the wrong resource. Plugin code never
+     * sets this.
+     */
+    readonly resId?: string;
+};
+/** Wire response from host to plugin for a prior request. */
+type HostResponse = {
+    readonly type: "response";
+    readonly id: number;
+    readonly ok: boolean;
+    readonly data?: unknown;
+    readonly error?: string;
+    /**
+     * Optional machine-readable plugin error code (e.g. the asset
+     * `DENIED` / `UNAVAILABLE` / `POLICY` vocabulary) so the bridge can
+     * reject with an Error carrying the code — plugin code branches on
+     * `err.name` across the postMessage boundary.
+     */
+    readonly errorCode?: string;
+    /**
+     * Legacy alias of {@link errorCode} (same value) kept for host
+     * builds predating the unified field. The bridge reads
+     * `errorCode ?? errorName`.
+     */
+    readonly errorName?: string;
+};
+/** Wire push event from host to plugin. */
+type HostPush = {
+    readonly type: "push";
+    readonly key: string;
+    readonly data?: unknown;
+};
+/** Wire subscription request from plugin to host. */
+type PluginSubscribe = {
+    readonly type: "subscribe";
+    readonly key: string;
+    /** Wire protocol version the plugin was built against (see {@link PROTOCOL_VERSION}). */
+    readonly proto?: number;
+};
+/**
+ * Wire acknowledgement from plugin to host: the pushed context has been
+ * applied *and painted* — the mount callback returned (for React plugins
+ * the new tree is already committed via flushSync) and a frame with the
+ * new content has reached the compositor. The host keeps a freshly
+ * claimed pooled iframe transparent until this arrives, so the previous
+ * resource's content never shows under a new claim.
+ */
+type PluginContextPainted = {
+    readonly type: "contextPainted";
+    readonly resId: string;
+    /** Wire protocol version the plugin was built against (see {@link PROTOCOL_VERSION}). */
+    readonly proto?: number;
+};
+/** Union of all messages a plugin can send to the host. */
+type PluginMessage = PluginRequest | PluginSubscribe | PluginContextPainted;
+/** Union of all messages the host can send to a plugin. */
+type HostMessage = HostResponse | HostPush;
+/** Type-safe request protocol table. Each entry declares input and output. */
+type PluginRequests = {
+    logInfo: {
+        readonly input: {
+            readonly message: string;
+            readonly data?: Record<string, unknown>;
+        };
+        readonly output: undefined;
+    };
+    logWarn: {
+        readonly input: {
+            readonly message: string;
+            readonly data?: Record<string, unknown>;
+        };
+        readonly output: undefined;
+    };
+    logError: {
+        readonly input: {
+            readonly message: string;
+            readonly data?: Record<string, unknown>;
+        };
+        readonly output: undefined;
+    };
+    listFiles: {
+        readonly input: undefined;
+        readonly output: SerializedFileList;
+    };
+    readFile: {
+        readonly input: {
+            readonly path: string;
+            /** Byte range (see {@link ReadFileRange}); omitted = whole file. */
+            readonly range?: ReadFileRange;
+        };
+        readonly output: ArrayBuffer;
+    };
+    listMessages: {
+        readonly input: undefined;
+        readonly output: readonly _hoardodile_sdk_types.Message[];
+    };
+    createMessage: {
+        readonly input: {
+            readonly body: string;
+            /** Wire anchor envelope; plugins pass raw data, the SDK wraps it. */
+            readonly anchor?: _hoardodile_sdk_types.AnchorData;
+        };
+        readonly output: _hoardodile_sdk_types.Message;
+    };
+    listDanmaku: {
+        readonly input: {
+            readonly filter?: _hoardodile_sdk_types.DanmakuListFilter;
+        };
+        readonly output: readonly _hoardodile_sdk_types.Danmaku[];
+    };
+    createDanmaku: {
+        readonly input: {
+            readonly text: string;
+            /** Wire anchor envelope (see {@link PluginRequests.createMessage}). */
+            readonly anchor: _hoardodile_sdk_types.AnchorData;
+            readonly mode?: _hoardodile_sdk_types.DanmakuMode;
+        };
+        readonly output: _hoardodile_sdk_types.Danmaku;
+    };
+    setPref: {
+        /** Persist a plugin-wide preference; host broadcasts `prefsChanged`. */
+        readonly input: {
+            readonly key: string;
+            readonly value: string;
+        };
+        readonly output: undefined;
+    };
+    setCache: {
+        /**
+         * Persist a per-resource cache entry; host broadcasts
+         * `cacheChanged`.
+         */
+        readonly input: {
+            readonly key: string;
+            readonly value: string;
+        };
+        readonly output: undefined;
+    };
+    invalidate: {
+        /** Request the host to invalidate cached data for a target. */
+        readonly input: {
+            readonly target: InvalidateTarget;
+        };
+        readonly output: undefined;
+    };
+    /**
+     * User-consented download into the plugin's own asset vault (see
+     * `@hoardodile/sdk-types/plugin-asset`). The host asks the user with
+     * the shared consent dialog; cached destinations resolve without any
+     * dialog. Rejections carry a machine-readable `err.name`
+     * (`DENIED` / `UNAVAILABLE` / `POLICY`).
+     *
+     * Timeout: {@link pluginRequestTimeouts.download} — the client-side
+     * ceiling for the whole flow (consent dialog + transfer), declared in
+     * the protocol meta rather than ad hoc at the call site.
+     */
+    download: {
+        readonly input: PluginDownloadRequest;
+        readonly output: PluginDownloadResult;
+    };
+    /**
+     * Remove a vault file (idempotent); the plugin decides its own vault
+     * lifecycle — no user consent, nothing leaves the host.
+     */
+    deleteAsset: {
+        readonly input: {
+            readonly path: string;
+        };
+        readonly output: PluginAssetDeleteResult;
+    };
+};
+/** Type-safe push protocol table. */
+type HostPushes = {
+    context: PluginIframeContext;
+    visibility: {
+        readonly visible: boolean;
+    };
+    themeChanged: {
+        readonly resolvedTheme: string;
+        readonly palette: string;
+        /** Active icon rendering style — host applies it as `data-icon-style`. */
+        readonly iconStyle: PluginIconStyle;
+    };
+    fontsChanged: PluginFonts;
+    /**
+     * The wire payload is a bare language-code string: it predates the
+     * typed protocol table and must stay stable for already-installed
+     * plugin builds (see `pushLanguageChanged` in apps/web — do not wrap
+     * it in an object).
+     */
+    languageChanged: string;
+    prefsChanged: {
+        readonly key: string;
+        readonly value?: string;
+    };
+    /**
+     * A plugin+resource cache entry changed. With data, carries the single
+     * changed entry; without data (undefined), all entries were cleared and
+     * the plugin should drop its whole cache store.
+     */
+    cacheChanged: {
+        readonly resId: string;
+        readonly key: string;
+        readonly value?: string;
+    } | undefined;
+    /**
+     * Host-initiated request to jump to an anchor (e.g. the user clicked a
+     * comment anchor in the host UI). Carries the plugin-defined anchor data
+     * only — the resource is always the iframe's own.
+     */
+    anchorJump: _hoardodile_sdk_types.AnchorData;
+    "res:invalidate": undefined;
+    "resources:invalidate": undefined;
+    "messages:invalidate": undefined;
+    "danmaku:invalidate": undefined;
+};
+/** Extract the input type for a request key. */
+type RequestInput<K extends keyof PluginRequests> = PluginRequests[K]["input"];
+/** Extract the output type for a request key. */
+type RequestOutput<K extends keyof PluginRequests> = PluginRequests[K]["output"];
+/** Targets that can be invalidated from the plugin runtime. */
+type InvalidateTarget = "resource" | "resources" | "messages" | "danmaku";
+/** Wire keys for host→plugin pushes, mirroring {@link HostPushes}. */
+declare const hostPushKeys: {
+    readonly context: "context";
+    readonly visibility: "visibility";
+    readonly themeChanged: "themeChanged";
+    readonly fontsChanged: "fontsChanged";
+    readonly languageChanged: "languageChanged";
+    readonly prefsChanged: "prefsChanged";
+    readonly cacheChanged: "cacheChanged";
+    readonly anchorJump: "anchorJump";
+    readonly resInvalidate: "res:invalidate";
+    readonly resourcesInvalidate: "resources:invalidate";
+    readonly messagesInvalidate: "messages:invalidate";
+    readonly danmakuInvalidate: "danmaku:invalidate";
+};
+/** Wire method names for plugin→host requests, mirroring {@link PluginRequests}. */
+declare const pluginMethods: {
+    readonly readFile: "readFile";
+    readonly listFiles: "listFiles";
+    readonly listMessages: "listMessages";
+    readonly createMessage: "createMessage";
+    readonly listDanmaku: "listDanmaku";
+    readonly createDanmaku: "createDanmaku";
+    readonly setPref: "setPref";
+    readonly setCache: "setCache";
+    readonly invalidate: "invalidate";
+    readonly download: "download";
+    readonly deleteAsset: "deleteAsset";
+    readonly logInfo: "logInfo";
+    readonly logWarn: "logWarn";
+    readonly logError: "logError";
+};
+/** Push key broadcast after each {@link InvalidateTarget} is invalidated. */
+declare const invalidatePushKeys: {
+    readonly resource: "res:invalidate";
+    readonly resources: "resources:invalidate";
+    readonly messages: "messages:invalidate";
+    readonly danmaku: "danmaku:invalidate";
+};
+/**
+ * Type-safe host bridge. The runtime still serialises messages as plain
+ * postMessage objects; this contract gives compile-time guarantees to callers.
+ *
+ * Per-method timeouts are declared on the protocol table entries
+ * (`timeoutMs`) — the bridge reads them, callers never pass one.
+ */
+type Host = {
+    request<K extends keyof PluginRequests>(method: K, ...args: RequestInput<K> extends void ? [] : [RequestInput<K>]): Promise<RequestOutput<K>>;
+    subscribe<K extends keyof HostPushes>(key: K, handler: (data: HostPushes[K]) => void): () => void;
+    /**
+     * Internal — returns a Host whose requests are stamped with the given
+     * resource scope (see {@link PluginRequest.resId}). Used by the runtime
+     * to bind one API instance to the resource it was created for.
+     */
+    withScope: (resId: string) => Host;
+};
+
+/**
+ * Narrow an unknown value to a plain record. Handy for decoding
+ * plugin-defined payloads (e.g. anchor data) without assertion casts.
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Lazily create (and then reuse) the singleton postMessage bridge to the
+ * host parent window: request/response with a 10s timeout plus push
+ * subscriptions. Only the host window may drive the bridge — messages
+ * from any other source are ignored. Called automatically by
+ * {@link createIframeHostAPI}; you only need this when talking to the
+ * host outside the plugin API surface.
+ */
+declare function ensureHostBridge(): Host;
+
+/**
+ * What {@link WebPluginAPI.resolveFileUrl} may address: the original
+ * bytes (`"original"`, or omit the argument), the default preview
+ * variant (`"preview"`), or a custom derived image via
+ * {@link ImageVariantSpec}.
+ */
+type FileUrlVariant = "original" | "preview" | ImageVariantSpec;
+/**
+ * The current resource as seen by the plugin iframe: id/name plus the
+ * schema-typed metadata (`sourceMeta`, `searchMeta`, `fileStats`) that
+ * the host derived at import time. Injected via the iframe context; the
+ * reactive hooks derive from it, so render code reads the live value
+ * from `usePluginAPI().resource`.
+ */
+type PluginResource<TSchema extends PluginSchema = PluginSchema> = {
+    readonly id: string;
+    readonly name: string;
+    readonly sourceMeta: TSchema["sourceMeta"];
+    readonly searchMeta: TSchema["searchMeta"];
+    readonly fileStats: FileStats | undefined;
+    readonly contentPluginId: string;
+};
+/** Encode/decode pair for typed preference values. */
+type Codec<T> = {
+    readonly encode: (value: T) => string;
+    readonly decode: (raw: string) => T | undefined;
+};
+/** Reactive query state returned by hooks. */
+type QueryState<T> = {
+    readonly data: T | undefined;
+    readonly isLoading: boolean;
+    readonly isError: boolean;
+    readonly error: Error | null;
+};
+/** Reactive mutation state returned by hooks. */
+type MutationState<TInput, TOutput> = {
+    readonly mutate: (input: TInput) => Promise<TOutput>;
+    readonly isPending: boolean;
+};
+/** Current theme as observed by the plugin. */
+type Theme = {
+    readonly resolvedTheme: string;
+    readonly palette: string;
+    /** Icon rendering style (`duotone` | `grayscale` | `linear`). */
+    readonly iconStyle: string;
+};
+/**
+ * Imperative, framework-agnostic API surface injected into plugin render
+ * modules. Reactive hooks (see {@link ReactivePluginAPI}) are provided by
+ * framework adapters — `@hoardodile/sdk-react` composes both into the
+ * full API seen by React plugin components.
+ */
+type WebPluginAPI<TSchema extends PluginSchema = PluginSchema> = {
+    /** Logging */
+    readonly logInfo: (message: string, data?: Record<string, unknown>) => void;
+    readonly logWarn: (message: string, data?: Record<string, unknown>) => void;
+    readonly logError: (message: string, data?: Record<string, unknown>) => void;
+    /** Resource context. */
+    readonly resource: PluginResource<TSchema>;
+    /** Files. */
+    readonly listFiles: () => Promise<readonly TSchema["file"][]>;
+    /**
+     * Read a file relative to the resource root. Without `range` the whole
+     * file is returned; large files should be read in bounded chunks via
+     * the byte range (mirrors the server-side `ResourceAPI.readFile`).
+     */
+    readonly readFile: (path: string, range?: ReadFileRange) => Promise<ArrayBuffer>;
+    /**
+     * Resolve a server-rendered URL for a file inside the resource.
+     * Without `variant` (or with `"original"`) the URL addresses the
+     * original bytes; `"preview"` selects the default preview variant
+     * (AVIF, fit inside the standard area cap); pass an
+     * {@link ImageVariantSpec} to request a custom derived image —
+     * e.g. `{ format: "webp", fit: "exact" }` transcodes to WebP at the
+     * source's exact pixel dimensions (no resize), and
+     * `{ maxArea: 2_000_000 }` caps a downscale. Variant renders are
+     * cached by the host; pick the `file.preview` flag to gate an
+     * original/preview toggle.
+     */
+    readonly resolveFileUrl: (filename: string, variant?: FileUrlVariant) => string;
+    /**
+     * Resolve the URL of a file materialized by the plugin's
+     * `extractArchive` hook: an inner entry of an archive (zip/tar)
+     * served from the host's extraction cache. `path` is the entry's
+     * relative path inside the archive, exactly as returned by
+     * `extractArchive` / the `listFiles` hook. Tokenized like
+     * `resolveFileUrl`.
+     */
+    readonly resolveExtractedUrl: (path: string) => string;
+    /**
+     * Resolve the URL of the host's in-flight extraction progress for
+     * this resource (see `extractArchive`). Returns
+     * `{ done, total }` while materializing, `null` otherwise. Tokenized
+     * like `resolveFileUrl`; polls are cheap (no-store JSON).
+     */
+    readonly extractProgressUrl: () => string;
+    /**
+     * Root URL of the current resource's files directory, trailing-slash
+     * included. For vendor SDKs that internally join relative paths and need
+     * a base.
+     */
+    readonly resolveBaseUrl: () => string;
+    /**
+     * Resolve a server-rendered frame thumbnail URL for a video file at the
+     * given timestamp (in milliseconds, measured from the start of the
+     * file). The server decodes the requested frame on demand; callers
+     * should debounce frequent invocations (e.g. while scrubbing) to avoid
+     * a flood of decode requests.
+     */
+    readonly resolveFrameUrl: (filename: string, timeMs: number) => string;
+    /** Plugin asset vault. */
+    /**
+     * User-consented download into the plugin's own asset vault: when the
+     * destination already exists the host answers `cached: true` (no
+     * dialog, no network); otherwise the host asks the user (shared
+     * consent dialog, URL shown verbatim) and downloads on approval.
+     * Rejections carry a machine-readable `err.name`
+     * (`DENIED` / `UNAVAILABLE` / `POLICY`).
+     */
+    readonly download: (request: PluginDownloadRequest) => Promise<PluginDownloadResult>;
+    /**
+     * Resolve the tokenized URL of a file in the plugin's own vault
+     * (`/api/plugin-assets/<pluginId>/<token>/<path>`). Use it to load a
+     * downloaded runtime or asset from inside the sandboxed iframe, e.g.
+     * `<script src={api.resolveAssetUrl("runtime/live2d.min.js")} />`
+     * (served with an exact JS MIME + `nosniff`, so classic scripts,
+     * module imports and `fetch` all work).
+     */
+    readonly resolveAssetUrl: (path: string) => string;
+    /**
+     * Remove a vault file (idempotent: an absent file answers
+     * `{ existed: false }`). The plugin decides the vault's lifecycle —
+     * no user consent, nothing leaves the host.
+     */
+    readonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>;
+    /** Messages. */
+    readonly listMessages: () => Promise<readonly Message[]>;
+    readonly createMessage: (input: {
+        readonly body: string;
+        /** Raw plugin location data (see {@link PluginSchema.anchor}). */
+        readonly anchor?: TSchema["anchor"];
+    }) => Promise<Message>;
+    /** Danmaku. */
+    readonly listDanmaku: (filter?: DanmakuListFilter) => Promise<readonly Danmaku[]>;
+    readonly createDanmaku: (input: {
+        readonly text: string;
+        /** Raw plugin location data (see {@link PluginSchema.anchor}). */
+        readonly anchor: TSchema["anchor"];
+        readonly mode?: DanmakuMode;
+    }) => Promise<Danmaku>;
+    /** Preferences. */
+    readonly getPref: (key: string) => string | undefined;
+    readonly setPref: (key: string, value: string) => void;
+    /** Cache. */
+    readonly getCache: (key: string) => string | undefined;
+    readonly setCache: (key: string, value: string) => void;
+    readonly listCache: () => readonly {
+        readonly key: string;
+        readonly value: string;
+    }[];
+    /** Invalidation. */
+    readonly invalidate: (target: InvalidateTarget) => Promise<void>;
+    /**
+     * Subscribe to host-initiated anchor jumps (e.g. the user clicked a
+     * comment anchor in the host UI). The callback receives the raw wire
+     * envelope ({@link AnchorData}) — decode `anchor.data` yourself, or
+     * use the typed `useAnchorJump` from `@hoardodile/sdk-react`, which
+     * decodes at the SDK boundary. Always targets the iframe's own
+     * resource. Returns an unsubscribe function.
+     */
+    readonly onAnchorJump: (cb: (anchor: AnchorData) => void) => () => void;
+};
+/**
+ * Reactive (hook-based) API surface, implemented by framework adapters.
+ * Plain `@hoardodile/sdk-web` consumers get the imperative
+ * {@link WebPluginAPI} only; `@hoardodile/sdk-react` provides these via
+ * `createPluginQueryAPI`.
+ */
+type ReactivePluginAPI<TSchema extends PluginSchema = PluginSchema> = {
+    readonly useFileList: () => QueryState<readonly TSchema["file"][]>;
+    readonly useMessageList: () => QueryState<readonly Message[]>;
+    readonly useCreateMessage: () => MutationState<{
+        readonly body: string;
+        readonly anchor?: TSchema["anchor"];
+    }, Message>;
+    readonly useDanmakuList: (filter?: DanmakuListFilter) => QueryState<readonly Danmaku[]>;
+    readonly useCreateDanmaku: () => MutationState<{
+        readonly text: string;
+        readonly anchor: TSchema["anchor"];
+        readonly mode?: DanmakuMode;
+    }, Danmaku>;
+    readonly usePref: <T>(key: string, defaultValue: T, codec?: Codec<T>) => readonly [T, (value: T) => void];
+    readonly useTheme: () => Theme;
+    readonly useFont: () => PluginFonts;
+};
+
+/**
+ * JSON codec covering the common case (`number`, `string`, `boolean`, plain
+ * objects). Falls back to `undefined` on parse errors so callers see "missing"
+ * instead of a corrupted value.
+ */
+declare function jsonCodec<T>(): Codec<T>;
+/**
+ * Plain-string number codec. Avoids the `""` → `0` ambiguity of
+ * {@link jsonCodec} by treating any non-finite parse as missing.
+ */
+declare function numberCodec(fallback?: number): Codec<number>;
+/**
+ * Boolean codec using `"1"`/`"0"` for compact storage. Also accepts
+ * `"true"`/`"false"` for interoperability.
+ */
+declare function booleanCodec(): Codec<boolean>;
+
+/**
+ * Deep-partial override type for {@link createWebPluginAPI}: nested
+ * objects and functions can be overridden selectively; functions may
+ * also be replaced by `undefined` to drop the default no-op.
+ */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends (...args: never[]) => unknown ? T[K] | undefined : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/** The complete plugin API shape stubbed by {@link createWebPluginAPI}. */
+type StubbedPluginAPI = WebPluginAPI & ReactivePluginAPI;
+/**
+ * Returns a minimal complete plugin API for render tests — the imperative
+ * surface plus no-op reactive hooks. All fields return empty/loading/no-op
+ * values; override via `overrides` to exercise plugin-specific code paths.
+ *
+ * Framework-agnostic counterpart of the React `createWebPluginAPI` in
+ * `@hoardodile/sdk-react`: this one returns a plain object (no React
+ * provider), that one wraps the same stub in a `StubPluginAPIProvider`
+ * so component tests can render against it.
+ */
+declare function createWebPluginAPI(overrides?: DeepPartial<StubbedPluginAPI>): StubbedPluginAPI;
+
+/** The last context pushed by the host, if any. */
+declare function getPluginContext(): PluginIframeContext | undefined;
+/**
+ * Subscribe to iframe visibility changes (tab hidden, iframe released,
+ * overlays opened by the host). The callback receives the current
+ * visibility; returns an unsubscribe function. Backs `useVisibility`
+ * in `@hoardodile/sdk-react`.
+ */
+declare function subscribeToVisibility(cb: (visible: boolean) => void): () => void;
+/** Current visibility snapshot without subscribing. */
+declare function getVisibilitySnapshot(): boolean;
+/**
+ * Sets up listeners for host→plugin communication via `postMessage` and
+ * `CustomEvent` fallback. The host pushes context and visibility updates;
+ * this function invokes `mount(ctx)` whenever a new context arrives.
+ *
+ * Lifecycle contract: the host may replace the context at any time — a
+ * pooled iframe document is reused across resources without a reload — so
+ * `mount` runs once per context, not once per page load. Clean up
+ * per-resource state yourself, or rely on `createPluginRoot` from
+ * `@hoardodile/sdk-react`, which remounts the tree by `resId` by
+ * default. When the host rebinds the iframe to a new resource, a late
+ * unmount cache flush stamped with the old resId is stale-dropped by the
+ * host (the plugin's debounced write still lands via the new binding).
+ */
+declare function mountPlugin(mount: (ctx: PluginIframeContext) => void): void;
+/** Applies theme classes to `document.documentElement` so CSS variables update. */
+declare function applyTheme(resolvedTheme: string, palette: string, iconStyle: string): void;
+/**
+ * Applies the host app font to the iframe document: injects each preset
+ * stylesheet once (idempotent per path — they are absolute `/fonts/...`
+ * URLs statically served by the host, which the sandboxed iframe can
+ * load), then points `--font-app` at the family stack. An empty family
+ * means the plugin opted out of font inheritance: the variable is
+ * removed and the document falls back to the plugin's own `--font-sans`.
+ */
+declare function applyFonts(family: string, cssPaths: readonly string[]): void;
+
+/**
+ * Extract `{ resolvedTheme, palette, iconStyle }` from an unknown host
+ * payload. Malformed input yields `undefined` fields rather than throwing —
+ * theme pushes are best-effort.
+ */
+declare function extractThemePayload(data: unknown): {
+    resolvedTheme: string | undefined;
+    palette: string | undefined;
+    iconStyle: string | undefined;
+};
+/**
+ * Extract the host app font payload (`family` + stylesheet paths) from
+ * an unknown host push; `undefined` when the shape does not match.
+ */
+declare function extractFontsPayload(data: unknown): PluginFonts | undefined;
+/**
+ * Extract a `{ key, value }` pref update from an unknown host push;
+ * `undefined` when the shape does not match. `value` may be `undefined`
+ * for a removal.
+ */
+declare function extractPrefPayload(data: unknown): {
+    readonly key: string;
+    readonly value: string | undefined;
+} | undefined;
+/**
+ * Builds the full {@link WebPluginAPI} for a plugin running inside a sandboxed
+ * iframe. Communicates with the host via postMessage.
+ */
+declare function createIframeHostAPI<TSchema extends PluginSchema = PluginSchema>(ctx: PluginIframeContext): WebPluginAPI<TSchema>;
+
+/**
+ * Reset both stores and seed them from the iframe context. Called once
+ * by the runtime on mount; must run before any pref/cache access.
+ */
+declare function seedPluginStores(ctx: PluginIframeContext): void;
+/** Read-only view of the plugin's in-memory pref store. */
+declare function getPluginPrefStore(): ReadonlyMap<string, string>;
+/** Write a pref locally; mirror it to the host immediately. */
+declare function setPluginPref(key: string, value: string): void;
+/** Read-only view of the plugin's in-memory cache store. */
+declare function getPluginCacheStore(): ReadonlyMap<string, string>;
+/**
+ * Write a cache entry locally and mirror it to the host for persistence.
+ * Continuously-changing state (scroll positions, resume timestamps)
+ * should go through the debounced `useCacheWriter` in
+ * `@hoardodile/sdk-react` instead of calling this directly on every
+ * change.
+ */
+declare function setPluginCache(key: string, value: string): void;
+/**
+ * Snapshot of all cache entries, as returned by `api.listCache`. Values
+ * are the raw serialized strings stored via {@link setPluginCache}.
+ */
+declare function snapshotCacheEntries(): {
+    readonly key: string;
+    readonly value: string;
+}[];
+/**
+ * Subscribe to pref changes for `key` (both local writes and host-pushed
+ * updates). Returns an unsubscribe function. Backs the reactive
+ * `usePref` hook in `@hoardodile/sdk-react`.
+ */
+declare function subscribeToPrefChanges(key: string, cb: () => void): () => void;
+/** Notify all subscribers of `key` about a value change. */
+declare function broadcastPrefChange(key: string): void;
+
+export { type Codec, type DeepPartial, type FileUrlVariant, type Host, type HostMessage, type HostPush, type HostPushes, type HostResponse, type InvalidateTarget, type MutationState, PROTOCOL_VERSION, type PluginContextPainted, type PluginFonts, type PluginIframeContext, type PluginMessage, type PluginRequest, type PluginRequests, type PluginResolvedTheme, type PluginResource, type PluginSubscribe, type PluginThemePalette, type QueryState, type ReactivePluginAPI, type RequestInput, type RequestOutput, type StubbedPluginAPI, type Theme, type WebPluginAPI, applyFonts, applyTheme, booleanCodec, broadcastPrefChange, createIframeHostAPI, createWebPluginAPI, ensureHostBridge, extractFontsPayload, extractPrefPayload, extractThemePayload, getPluginCacheStore, getPluginContext, getPluginPrefStore, getVisibilitySnapshot, hostPushKeys, invalidatePushKeys, isRecord, jsonCodec, mountPlugin, numberCodec, pluginMethods, pluginThemePalettes, seedPluginStores, setPluginCache, setPluginPref, snapshotCacheEntries, subscribeToPrefChanges, subscribeToVisibility };