@vormio/plugin-sdk 0.0.3 → 0.0.6

package/README.md

@@ -1,8 +1,8 @@
 # @vormio/plugin-sdk
 
-The manifest schema, runtime helpers and packaging command for writing Vormio plugins. The package is versioned with Vormio-Core (currently 0.0.3) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.3`.
+The manifest schema, runtime helpers and packaging command for writing Vormio plugins, plus the commands that publish a signed plugin catalog. The package is versioned with Vormio-Core (currently 0.0.6) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.6`.
 
-Plugin contract version: `apiVersion: 1`. During development (0.0.x) there is no cross-version compatibility promise: the host loads only plugins with the same `apiVersion` as its own.
+Plugin contract version: `apiVersion: 2`. During development (0.0.x) there is no cross-version compatibility promise: the host loads only plugins with the same `apiVersion` as its own.
 
 ## What a plugin can do
 
@@ -28,7 +28,7 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 
 ```json
 {
-  "apiVersion": 1,
+  "apiVersion": 2,
   "id": "acme.model-viewer",
   "version": "0.1.0",
   "name": "Model Viewer",
@@ -63,16 +63,23 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 
 **Allowed files**: `html js mjs css json wasm png jpg jpeg webp svg woff2 txt md`. Links, `..` paths, Windows reserved names and names that differ only by case are not allowed.
 
-**Limits**: at most 1,024 files, 16 MiB per file and 64 MiB in total.
+**Limits**: at most 1,024 files, 16 MiB per file and 64 MiB in total; the `.vormioplugin` file itself is at most 96 MiB.
 
-**Permission fingerprint**: the grant a library records covers each extension point's ID (analyzers included), `formats` and `companionFormats`. An upgrade that changes only code, name or version keeps the grant; widening what the plugin reads or adding an extension point requires the user to enable it again.
+**Grants**: a library records what the user approved for each extension point (analyzers included): its ID, `formats` and `companionFormats`. A version that reads no more than that keeps running without asking again, including:
+
+- an upgrade that changes only code, name or version
+- an upgrade that reads less
+- a rollback
+
+Reading more formats or companion formats, or adding an extension point, requires the user to enable the plugin again, and that approval is added to what was approved before.
 
 ## Runtime API
 
 ```ts
 import { analyzer, readCompanion, readInput, thumbnail, viewer } from '@vormio/plugin-sdk'
 
-// Viewer: called first and on every file change. Returning means ready; throwing reports a failure.
+// Viewer: called first and on every file change. Returning means ready; throwing reports a failure;
+// returning notApplicable() hands the file to the next viewer (see below).
 viewer(async (input, signal) => {
   const bytes = await readInput(input)
   const texture = await readCompanion(input, 'textures/base.png')
@@ -108,12 +115,36 @@ analyzer(async (input) => {
 | `changed`       | The file changed on disk and no longer matches the library's record                                         | 409   |
 | `unavailable`   | Any other reason, such as an offline linked folder or an expired binding                                    | Other |
 
-- Pages that do not use these helpers can call `window.vormio` directly; see the `PluginBridge` type in `@vormio/plugin-sdk/bridge`. A thumbnail handler returns the PNG as an `ArrayBuffer`, and an analyzer handler (`onAnalyzeRequest`) returns the composition report.
+- Pages that do not use these helpers can call `window.vormio` directly; see the `PluginBridge` type in `@vormio/plugin-sdk/bridge`. A thumbnail handler returns the PNG as an `ArrayBuffer`, and an analyzer handler (`onAnalyzeRequest`) returns the composition report; either can return `{ notApplicable: true }` instead, and a viewer calls `notApplicable(input)`.
 - While a plugin view has focus, unmodified Esc, ← and → are handled by the host (back to the grid, previous, next); the plugin does not receive these keys.
 
+## Files that are not your format
+
+The host chooses plugins by extension only. When a format you declare is shared with other tools, such as `json`, every file with that extension comes to you. Return `notApplicable()` for the files that are not yours:
+
+```ts
+import { analyzer, notApplicable, readInput, thumbnail, viewer } from '@vormio/plugin-sdk'
+
+analyzer(async (input) => {
+  const data = JSON.parse(new TextDecoder().decode(await readInput(input)))
+  if (!isSkeleton(data)) return notApplicable()
+  return analyzeSkeleton(data)
+})
+```
+
+`thumbnail()` and `viewer()` accept the same answer.
+
+- It is not a failure. The host records no reason and shows nothing for it:
+  - an analyzer's file gets no composition section;
+  - thumbnails and viewers move on to the next enabled plugin for the format, then to the built-in preview or the type icon.
+- The host asks each extension point about each file version once. It asks again when the file changes or your plugin's code changes, so a plugin loaded from a development folder is asked again after every reload.
+- Decide from the file alone; companion files read before answering are not tracked. Decide from the start of the file when you can (the input supports Range requests): a viewer's user waits for the answer before seeing the built-in preview.
+- A file that is your format but has a problem should throw, or report diagnostics, so the user sees why.
+- When several enabled plugins declare a format, the host asks them in order of plugin ID. Thumbnails and viewers ask the next one after a `notApplicable()`; analyzers ask only the first.
+
 ## Analyzers
 
-Once a plugin is enabled in a library, the host analyzes its declared formats in the background. Matching files join the queue when linking and scanning find new files or versions, when the plugin is enabled, and when the plugin's code changes. The file whose details the user is viewing goes first, and the user can also re-analyze manually. At most 2 analyses run at once, each with a 30-second timeout. A thrown error, a timeout or an invalid report counts as a failed analysis and shows the reason; the same plugin code is not retried on the same file version.
+Once a plugin is enabled in a library, the host analyzes its declared formats in the background. Matching files join the queue when linking and scanning find new files or versions, when the plugin is enabled, and when the plugin's code changes. The file whose details the user is viewing goes first, and the user can also re-analyze manually. At most 2 analyses run at once, each with a 30-second timeout. A thrown error, a timeout or an invalid report counts as a failed analysis and shows the reason; the same plugin code is not retried on the same file version. For files that are not your format, return `notApplicable()` (see [Files that are not your format](#files-that-are-not-your-format)).
 
 A report describes one version of the analyzed file:
 
@@ -158,3 +189,69 @@ npx vormio-plugin pack <build-output-folder> <output-file.vormioplugin>
 The command validates the manifest and every file, then writes a zip-format `.vormioplugin`. It never overwrites an existing output file.
 
 During development, open the **插件** (Plugins) page in Vormio, choose **添加开发目录…** (Add development folder…) and point it at the build output folder. The host watches the folder: every change is validated again, and a valid build reloads the plugin. If validation fails, the last valid version stays loaded and the error is shown on the plugin card. Vormio never runs build commands.
+
+## Plugin catalogs
+
+A plugin catalog is a signed `catalog.json` plus the plugin packages it lists, on static hosting. Vormio installs and updates plugins from it. Publishers produce one with two commands:
+
+```bash
+npx vormio-plugin keygen <key-path-prefix>
+npx vormio-plugin catalog <release-config.json> --key <private-key.pem> --out <new-folder>
+```
+
+- `keygen` generates an Ed25519 key pair: `<prefix>.private.pem` (PKCS#8) and `<prefix>.public.txt` (the base64 of the 32-byte public key; hosts build this line in). It refuses to write inside a Git working tree and never overwrites a file. The private key stays on the publisher's machine: never commit or upload it.
+- The release configuration lists every package in the new catalog, relative to the configuration file:
+
+  ```json
+  {
+    "previous": "published/3/catalog.json",
+    "packages": ["artifacts/model-viewer-0.2.0.vormioplugin"]
+  }
+  ```
+
+  `previous` is the catalog currently online. The new catalog's sequence is its sequence plus 1, and it must be signed with the same key. A first publication has no previous catalog and uses `"initialSequence": 1` instead.
+
+- `catalog` does the following:
+  - Validates every package with the rules a host applies when installing it.
+  - Copies each package to `packages/<plugin ID>-<version>-<first 12 hex digits of its SHA-256>.vormioplugin`.
+  - Writes and signs `catalog.json`, then verifies it with the public key.
+
+  The output folder must be new or empty. If any check fails, nothing is written.
+
+- Upload `packages/` first and `catalog.json` last. Do not cache `catalog.json`. Package file names change with their content, so packages can be cached for a long time.
+
+**Format**: `catalog.json` is an envelope `{ format: 1, keyId, payload, signature }`:
+
+- `payload` is the base64 of the content's UTF-8 JSON.
+- `signature` is the Ed25519 signature of those bytes.
+- `keyId` is the first 16 hex digits of the public key's SHA-256.
+
+The content:
+
+```ts
+interface CatalogPayload {
+  sequence: number // Grows by 1 per publication; hosts refuse a sequence lower than one they have seen
+  publishedAt: string // ISO 8601, UTC
+  plugins: {
+    id: string
+    releases: {
+      manifest: object // The package's manifest.json, as is
+      file: string // packages/<name>.vormioplugin, relative to catalog.json
+      bytes: number
+      sha256: string // SHA-256 of the whole package file, lowercase hex
+    }[]
+  }[]
+}
+```
+
+- Limits:
+  - `catalog.json` is at most 1 MiB.
+  - At most 256 plugins, with at most 8 releases each.
+  - Package files are at most 96 MiB.
+
+  Plugin IDs, and the versions of one plugin, must not repeat. `manifest.id` must match the plugin ID.
+
+- One plugin can list releases for hosts of different `apiVersion`s side by side. A host installs only releases with its own `apiVersion` whose manifest passes its own validation; it shows the rest as needing a newer Vormio.
+- Hosts verify the signature before reading the content. A downloaded package must match `bytes` and `sha256`, then pass the rules of a local install, and its manifest must equal the one in the catalog.
+
+`@vormio/plugin-sdk/node` exports the same functionality: `verifyCatalog`, `signCatalog`, `writeCatalog`, `writeCatalogKeys`, `releaseManifest` and `compareVersions`.

package/dist/bridge.d.ts

@@ -54,6 +54,16 @@ export interface CompositionReport {
     /** The analyzer could only finish part of the file. */
     partial?: boolean;
 }
+/**
+ * A handler's answer for a file that is not its format, such as a JSON file that is no skeleton.
+ * It is not a failure: the host shows nothing for it and does not ask again about this version of
+ * the file until the plugin's code changes.
+ */
+export interface NotApplicable {
+    notApplicable: true;
+}
+/** Whether a handler's answer is exactly `{ notApplicable: true }`. */
+export declare function isNotApplicable(value: unknown): value is NotApplicable;
 /** The frozen object the host's plugin preload exposes as `window.vormio`. */
 export interface PluginBridge {
     /** The viewer's current input. */
@@ -64,13 +74,22 @@ export interface PluginBridge {
     ready(input: PluginInput): void;
     /** The viewer cannot show `input`; the host shows `message` as plain text. */
     fail(input: PluginInput, message: string): void;
+    /**
+     * `input` is not the viewer's format; the host moves on to the next viewer or the built-in
+     * preview.
+     */
+    notApplicable(input: PluginInput): void;
     /**
      * Thumbnail pages: handles each request from the host and returns PNG bytes no larger than
-     * `maxEdge` on either side. (Blobs cannot cross the bridge; `thumbnail()` converts them.)
+     * `maxEdge` on either side, or `{ notApplicable: true }`. (Blobs cannot cross the bridge;
+     * `thumbnail()` converts them.)
      */
     onThumbnailRequest(handler: (input: PluginInput, size: {
         maxEdge: number;
-    }) => Promise<ArrayBuffer>): void;
-    /** Analyzer pages: handles each request from the host and returns the composition report. */
-    onAnalyzeRequest(handler: (input: PluginInput) => Promise<CompositionReport>): void;
+    }) => Promise<ArrayBuffer | NotApplicable>): void;
+    /**
+     * Analyzer pages: handles each request from the host and returns the composition report, or
+     * `{ notApplicable: true }`.
+     */
+    onAnalyzeRequest(handler: (input: PluginInput) => Promise<CompositionReport | NotApplicable>): void;
 }

package/dist/bridge.js

@@ -1,2 +1,11 @@
-// Types shared by plugin pages and the host's plugin preload. No DOM types, so Node code can use them.
-export {};
+// Types shared by plugin pages and the host's plugin preload, and one check free of schemas that the
+// preload uses. No DOM types, so Node code can use them.
+/** Whether a handler's answer is exactly `{ notApplicable: true }`. */
+export function isNotApplicable(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return (keys.length === 1 &&
+        keys[0] === 'notApplicable' &&
+        value.notApplicable === true);
+}

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { contributionsOf, manifestSchema, missingEntries, parseManifest, permiss
 export { checkPackageFiles, checkPackagePath, packageExtensions, packageLimits, type PackageFile, } from './package-rules.ts';
 export { compositionReportSchema, parseReport, reportLimits, type ReportResult } from './report.ts';
 export type { ReportDiagnostic, ReportReference, ReportSubresource } from './bridge.ts';
-export { analyzer, bridge, readCompanion, readInput, thumbnail, viewer, type CompanionResult, type CompanionStatus, type CompositionReport, type PluginBridge, type PluginInput, } from './runtime.ts';
+export { analyzer, bridge, isNotApplicable, notApplicable, readCompanion, readInput, thumbnail, viewer, type CompanionResult, type CompanionStatus, type CompositionReport, type NotApplicable, type PluginBridge, type PluginInput, } from './runtime.ts';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, } from "./manifest.js";
 export { checkPackageFiles, checkPackagePath, packageExtensions, packageLimits, } from "./package-rules.js";
 export { compositionReportSchema, parseReport, reportLimits } from "./report.js";
-export { analyzer, bridge, readCompanion, readInput, thumbnail, viewer, } from "./runtime.js";
+export { analyzer, bridge, isNotApplicable, notApplicable, readCompanion, readInput, thumbnail, viewer, } from "./runtime.js";

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 /** The plugin contract version this SDK describes. Hosts load only plugins with this version. */
-export declare const pluginApiVersion = 1;
+export declare const pluginApiVersion = 2;
 declare const contributionSchema: z.ZodObject<{
     id: z.ZodString;
     entry: z.ZodString;
@@ -8,8 +8,12 @@ declare const contributionSchema: z.ZodObject<{
     companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type Contribution = z.output<typeof contributionSchema>;
+/** `publisher.name`. The `vormio` publisher is reserved for the host. */
+export declare const pluginIdSchema: z.ZodString;
+/** A semantic version without build metadata. */
+export declare const versionSchema: z.ZodString;
 export declare const manifestSchema: z.ZodObject<{
-    apiVersion: z.ZodLiteral<1>;
+    apiVersion: z.ZodLiteral<2>;
     id: z.ZodString;
     version: z.ZodString;
     name: z.ZodString;

package/dist/manifest.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { checkPackagePath } from "./package-rules.js";
 /** The plugin contract version this SDK describes. Hosts load only plugins with this version. */
-export const pluginApiVersion = 1;
+export const pluginApiVersion = 2;
 const unique = (values) => new Set(values).size === values.length;
 const extension = z.string().regex(/^[a-z0-9]{1,16}$/, 'Use a lower-case extension without a dot');
 const extensions = (min) => z.array(extension).min(min).max(64).refine(unique, 'Extensions must not repeat');
@@ -22,16 +22,19 @@ const contributionList = z
     .max(8)
     .default([])
     .refine((items) => unique(items.map((item) => item.id)), 'Contribution IDs must not repeat');
+/** `publisher.name`. The `vormio` publisher is reserved for the host. */
+export const pluginIdSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]{0,39}\.[a-z0-9][a-z0-9-]{0,39}$/, 'Use publisher.name')
+    .refine((id) => !id.startsWith('vormio.'), 'The vormio publisher is reserved');
+/** A semantic version without build metadata. */
+export const versionSchema = z
+    .string()
+    .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/, 'Use a semantic version');
 export const manifestSchema = z.strictObject({
     apiVersion: z.literal(pluginApiVersion),
-    /** `publisher.name`. The `vormio` publisher is reserved for the host. */
-    id: z
-        .string()
-        .regex(/^[a-z0-9][a-z0-9-]{0,39}\.[a-z0-9][a-z0-9-]{0,39}$/, 'Use publisher.name')
-        .refine((id) => !id.startsWith('vormio.'), 'The vormio publisher is reserved'),
-    version: z
-        .string()
-        .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/, 'Use a semantic version'),
+    id: pluginIdSchema,
+    version: versionSchema,
     name: z.string().trim().min(1).max(80),
     description: z.string().max(400).default(''),
     contributions: z

package/dist/node/catalog.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { type ManifestResult } from '../manifest.ts';
+/** Limits for a signed plugin catalog. */
+export declare const catalogLimits: {
+    readonly maxCatalogBytes: number;
+    readonly maxPlugins: 256;
+    readonly maxReleasesPerPlugin: 8;
+};
+/** Which check a catalog failed: its shape, the key it was signed with, or the signature itself. */
+export type CatalogErrorCode = 'format' | 'key' | 'signature';
+export declare class CatalogError extends Error {
+    readonly code: CatalogErrorCode;
+    readonly problems: readonly string[];
+    constructor(code: CatalogErrorCode, problems: readonly string[]);
+}
+declare const payloadSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    publishedAt: z.ZodISODateTime;
+    plugins: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        releases: z.ZodArray<z.ZodObject<{
+            manifest: z.ZodObject<{
+                apiVersion: z.ZodNumber;
+                id: z.ZodString;
+                version: z.ZodString;
+                name: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>;
+            file: z.ZodString;
+            bytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** What `signCatalog` signs. */
+export type CatalogPayload = z.input<typeof payloadSchema>;
+/** A catalog whose signature has been verified. */
+export type Catalog = z.output<typeof payloadSchema> & {
+    keyId: string;
+};
+export type CatalogPlugin = Catalog['plugins'][number];
+export type CatalogRelease = CatalogPlugin['releases'][number];
+/** The first 16 hexadecimal digits of the public key's SHA-256; catalogs name their key by it. */
+export declare function catalogKeyId(publicKey: string): string;
+/** The public key that belongs to a PEM private key. */
+export declare function catalogPublicKey(privateKey: string): string;
+export interface CatalogKeys {
+    /** Base64 of the raw key; hosts build it in. */
+    publicKey: string;
+    /** PKCS#8 PEM. */
+    privateKey: string;
+    keyId: string;
+}
+export declare function generateCatalogKeys(): CatalogKeys;
+/** Validates a payload and returns the signed `catalog.json` bytes. */
+export declare function signCatalog(payload: CatalogPayload, privateKey: string): Buffer;
+/**
+ * Checks `catalog.json` against a public key: shape of the envelope, key ID, signature, and only
+ * then the payload. Throws `CatalogError` at the first check that fails.
+ */
+export declare function verifyCatalog(bytes: Uint8Array, publicKey: string): Catalog;
+/**
+ * The release's manifest when this SDK's hosts can install it: same apiVersion, and valid under
+ * this SDK's manifest schema. Otherwise the reasons, typically that the release needs a newer host.
+ */
+export declare function releaseManifest(release: CatalogRelease): ManifestResult;
+/** Orders two semantic versions by precedence: negative, zero or positive, like a sort callback. */
+export declare function compareVersions(a: string, b: string): number;
+export {};

package/dist/node/catalog.js

@@ -0,0 +1,240 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from 'node:crypto';
+import { z } from 'zod';
+import { parseManifest, pluginApiVersion, pluginIdSchema, versionSchema, } from "../manifest.js";
+import { packageLimits } from "../package-rules.js";
+/** Limits for a signed plugin catalog. */
+export const catalogLimits = {
+    maxCatalogBytes: 1024 * 1024,
+    maxPlugins: 256,
+    maxReleasesPerPlugin: 8,
+};
+export class CatalogError extends Error {
+    code;
+    problems;
+    constructor(code, problems) {
+        super(problems.join('\n'));
+        this.code = code;
+        this.problems = problems;
+        this.name = 'CatalogError';
+    }
+}
+/**
+ * The manifest fields every host reads, whatever the release's apiVersion. The rest of the manifest
+ * is kept as is: a host parses it fully only for releases of its own apiVersion (`releaseManifest`).
+ */
+const releaseManifestSchema = z.looseObject({
+    apiVersion: z.number().int().min(1),
+    id: pluginIdSchema,
+    version: versionSchema,
+    name: z.string().trim().min(1).max(80),
+    description: z.string().max(400).optional(),
+});
+const releaseSchema = z.strictObject({
+    /** The package's `manifest.json`. */
+    manifest: releaseManifestSchema,
+    /** The package file, relative to the catalog: always directly inside `packages/`. */
+    file: z
+        .string()
+        .regex(/^packages\/[A-Za-z0-9][A-Za-z0-9._-]{0,199}\.vormioplugin$/, 'Use packages/<name>.vormioplugin'),
+    bytes: z.number().int().min(1).max(packageLimits.maxArchiveBytes),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, 'Use lower-case hexadecimal'),
+});
+const payloadSchema = z
+    .strictObject({
+    /** Grows with every publication; hosts refuse a catalog older than one they have seen. */
+    sequence: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    publishedAt: z.iso.datetime(),
+    plugins: z
+        .array(z.strictObject({
+        id: pluginIdSchema,
+        releases: z.array(releaseSchema).min(1).max(catalogLimits.maxReleasesPerPlugin),
+    }))
+        .max(catalogLimits.maxPlugins),
+})
+    .superRefine((payload, context) => {
+    const ids = new Set();
+    const files = new Set();
+    payload.plugins.forEach((plugin, index) => {
+        const issue = (path, message) => context.addIssue({ code: 'custom', path: ['plugins', index, ...path], message });
+        if (ids.has(plugin.id))
+            issue(['id'], 'Plugin IDs must not repeat');
+        ids.add(plugin.id);
+        const versions = new Set();
+        plugin.releases.forEach((release, at) => {
+            if (release.manifest.id !== plugin.id)
+                issue(['releases', at, 'manifest', 'id'], 'The manifest ID must match the plugin ID');
+            if (versions.has(release.manifest.version))
+                issue(['releases', at, 'manifest', 'version'], 'Versions must not repeat');
+            versions.add(release.manifest.version);
+            const file = release.file.toLowerCase();
+            if (files.has(file))
+                issue(['releases', at, 'file'], 'Files must not repeat');
+            files.add(file);
+        });
+    });
+});
+const envelopeSchema = z.strictObject({
+    format: z.literal(1),
+    keyId: z.string().regex(/^[0-9a-f]{16}$/),
+    /** The payload's UTF-8 JSON, base64; the signature covers exactly these bytes. */
+    payload: z.string().min(1),
+    signature: z.string().min(1),
+});
+function problemsOf(error) {
+    return error.issues.map((issue) => `${issue.path.length ? issue.path.join('.') : 'catalog'}: ${issue.message}`);
+}
+/** Decodes canonical base64 only, so that one envelope has exactly one meaning. */
+function decodeBase64(text) {
+    const bytes = Buffer.from(text, 'base64');
+    return bytes.length > 0 && bytes.toString('base64') === text ? bytes : undefined;
+}
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+function parseJson(bytes, what) {
+    try {
+        return JSON.parse(utf8.decode(bytes));
+    }
+    catch {
+        throw new CatalogError('format', [`${what} is not valid UTF-8 JSON`]);
+    }
+}
+// --- Keys ------------------------------------------------------------------------------------
+// A public key is written as the base64 of its 32 raw Ed25519 bytes, short enough to build into the
+// app. Private keys are PKCS#8 PEM files that never leave the publisher's machine.
+function rawPublicKey(publicKey) {
+    const bytes = decodeBase64(publicKey.trim());
+    if (bytes?.length !== 32)
+        throw new CatalogError('key', ['A public key is 32 raw Ed25519 bytes in base64']);
+    return bytes;
+}
+function publicKeyObject(publicKey) {
+    const x = rawPublicKey(publicKey).toString('base64url');
+    return createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x }, format: 'jwk' });
+}
+function publicKeyText(key) {
+    return Buffer.from(key.export({ format: 'jwk' }).x, 'base64url').toString('base64');
+}
+function privateKeyObject(privateKey) {
+    let key;
+    try {
+        key = createPrivateKey(privateKey);
+    }
+    catch {
+        throw new CatalogError('key', ['The private key is not a PEM private key']);
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new CatalogError('key', ['The private key is not an Ed25519 key']);
+    return key;
+}
+/** The first 16 hexadecimal digits of the public key's SHA-256; catalogs name their key by it. */
+export function catalogKeyId(publicKey) {
+    return createHash('sha256').update(rawPublicKey(publicKey)).digest('hex').slice(0, 16);
+}
+/** The public key that belongs to a PEM private key. */
+export function catalogPublicKey(privateKey) {
+    return publicKeyText(createPublicKey(privateKeyObject(privateKey)));
+}
+export function generateCatalogKeys() {
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const text = publicKeyText(publicKey);
+    return {
+        publicKey: text,
+        privateKey: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(),
+        keyId: catalogKeyId(text),
+    };
+}
+// --- Signing and verification ----------------------------------------------------------------
+/** Validates a payload and returns the signed `catalog.json` bytes. */
+export function signCatalog(payload, privateKey) {
+    const result = payloadSchema.safeParse(payload);
+    if (!result.success)
+        throw new CatalogError('format', problemsOf(result.error));
+    const key = privateKeyObject(privateKey);
+    const bytes = Buffer.from(JSON.stringify(payload));
+    const envelope = {
+        format: 1,
+        keyId: catalogKeyId(publicKeyText(createPublicKey(key))),
+        payload: bytes.toString('base64'),
+        signature: sign(null, bytes, key).toString('base64'),
+    };
+    const text = Buffer.from(`${JSON.stringify(envelope, null, 2)}\n`);
+    if (text.length > catalogLimits.maxCatalogBytes)
+        throw new CatalogError('format', ['The catalog is larger than 1 MiB']);
+    return text;
+}
+/**
+ * Checks `catalog.json` against a public key: shape of the envelope, key ID, signature, and only
+ * then the payload. Throws `CatalogError` at the first check that fails.
+ */
+export function verifyCatalog(bytes, publicKey) {
+    if (bytes.length > catalogLimits.maxCatalogBytes)
+        throw new CatalogError('format', ['The catalog is larger than 1 MiB']);
+    const envelope = envelopeSchema.safeParse(parseJson(bytes, 'The catalog'));
+    if (!envelope.success)
+        throw new CatalogError('format', problemsOf(envelope.error));
+    const keyId = catalogKeyId(publicKey);
+    if (envelope.data.keyId !== keyId)
+        throw new CatalogError('key', [
+            `The catalog is signed with key ${envelope.data.keyId}, not ${keyId}`,
+        ]);
+    const payload = decodeBase64(envelope.data.payload);
+    const signature = decodeBase64(envelope.data.signature);
+    if (!payload || signature?.length !== 64)
+        throw new CatalogError('format', ['The payload or signature is not canonical base64']);
+    if (!verify(null, payload, publicKeyObject(publicKey), signature))
+        throw new CatalogError('signature', ['The signature does not match the catalog']);
+    const result = payloadSchema.safeParse(parseJson(payload, 'The payload'));
+    if (!result.success)
+        throw new CatalogError('format', problemsOf(result.error));
+    return { keyId, ...result.data };
+}
+/**
+ * The release's manifest when this SDK's hosts can install it: same apiVersion, and valid under
+ * this SDK's manifest schema. Otherwise the reasons, typically that the release needs a newer host.
+ */
+export function releaseManifest(release) {
+    if (release.manifest.apiVersion !== pluginApiVersion)
+        return {
+            ok: false,
+            problems: [
+                `apiVersion ${release.manifest.apiVersion}; this version supports ${pluginApiVersion}`,
+            ],
+        };
+    return parseManifest(release.manifest);
+}
+// --- Versions --------------------------------------------------------------------------------
+function versionParts(version) {
+    const dash = version.indexOf('-');
+    const core = dash < 0 ? version : version.slice(0, dash);
+    return {
+        core: core.split('.').map(Number),
+        prerelease: dash < 0 ? [] : version.slice(dash + 1).split('.'),
+    };
+}
+/** Orders two semantic versions by precedence: negative, zero or positive, like a sort callback. */
+export function compareVersions(a, b) {
+    const left = versionParts(a);
+    const right = versionParts(b);
+    for (let at = 0; at < 3; at++) {
+        const difference = (left.core[at] ?? 0) - (right.core[at] ?? 0);
+        if (difference)
+            return Math.sign(difference);
+    }
+    // A version without a pre-release ranks above any pre-release of it.
+    if (!left.prerelease.length || !right.prerelease.length)
+        return Math.sign(right.prerelease.length - left.prerelease.length);
+    const count = Math.min(left.prerelease.length, right.prerelease.length);
+    for (let at = 0; at < count; at++) {
+        const x = left.prerelease[at];
+        const y = right.prerelease[at];
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return Math.sign(Number(x) - Number(y));
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return Math.sign(left.prerelease.length - right.prerelease.length);
+}

package/dist/node/cli.js

@@ -2,16 +2,18 @@
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { CatalogError } from "./catalog.js";
 import { checkPackage, PackageError, readPackageDirectory } from "./package.js";
+import { PublishError, writeCatalog, writeCatalogKeys } from "./publish.js";
 import { writeZip, ZipError } from "./zip.js";
-const usage = 'Usage: vormio-plugin pack <plugin directory> <output.vormioplugin>';
+const usage = [
+    'Usage:',
+    '  vormio-plugin pack <plugin directory> <output.vormioplugin>',
+    '  vormio-plugin keygen <output path prefix>',
+    '  vormio-plugin catalog <release config.json> --key <private key.pem> --out <new folder>',
+].join('\n');
 /** `vormio-plugin pack`: validates a built plugin directory and writes a `.vormioplugin` file. */
-async function main(args) {
-    const [command, source, output] = args;
-    if (command !== 'pack' || !source || !output) {
-        console.error(usage);
-        return 2;
-    }
+async function pack(source, output) {
     if (!output.endsWith('.vormioplugin')) {
         console.error('The output file must end with .vormioplugin');
         return 2;
@@ -21,23 +23,76 @@ async function main(args) {
         console.error(`${target} already exists; choose another name or remove it first`);
         return 1;
     }
+    const contents = await readPackageDirectory(resolve(source));
+    const checked = checkPackage(contents);
+    const entries = checked.files.map((file) => ({
+        path: file.path,
+        data: contents.get(file.path),
+    }));
+    await writeFile(target, writeZip(entries), { flag: 'wx' });
+    console.log(`${checked.manifest.id} ${checked.manifest.version}: ${entries.length} files → ${target}`);
+    console.log(`digest ${checked.digest}`);
+    return 0;
+}
+/** `vormio-plugin keygen`: creates the key pair a catalog is signed with. */
+async function keygen(prefix) {
+    const keys = await writeCatalogKeys(prefix);
+    console.log(`key ${keys.keyId}`);
+    console.log(`public key ${keys.publicKey}`);
+    console.log(`private key → ${keys.privateKeyFile}`);
+    console.log(`public key → ${keys.publicKeyFile}`);
+    console.log('Keep the private key offline. Never commit, upload or share it.');
+    return 0;
+}
+/** `vormio-plugin catalog`: publishes a signed catalog and its packages into a new folder. */
+async function catalog(args) {
+    let config;
+    let key;
+    let out;
+    for (let at = 0; at < args.length; at++) {
+        const arg = args[at];
+        if (arg === '--key')
+            key = args[++at];
+        else if (arg === '--out')
+            out = args[++at];
+        else if (config === undefined && arg && !arg.startsWith('--'))
+            config = arg;
+        else
+            return usageError();
+    }
+    if (!config || !key || !out)
+        return usageError();
+    const written = await writeCatalog({ config, privateKey: key, out });
+    console.log(`catalog.json: sequence ${written.sequence}, key ${written.keyId}`);
+    for (const release of written.releases)
+        console.log(`  ${release.id} ${release.version} → ${release.file}`);
+    console.log(`Upload the packages folder of ${resolve(out)} first, then catalog.json.`);
+    return 0;
+}
+function usageError() {
+    console.error(usage);
+    return 2;
+}
+async function main(args) {
+    const [command, ...rest] = args;
     try {
-        const contents = await readPackageDirectory(resolve(source));
-        const checked = checkPackage(contents);
-        const entries = checked.files.map((file) => ({
-            path: file.path,
-            data: contents.get(file.path),
-        }));
-        await writeFile(target, writeZip(entries), { flag: 'wx' });
-        console.log(`${checked.manifest.id} ${checked.manifest.version}: ${entries.length} files → ${target}`);
-        console.log(`digest ${checked.digest}`);
-        return 0;
+        if (command === 'pack' && rest.length === 2)
+            return await pack(rest[0], rest[1]);
+        if (command === 'keygen' && rest.length === 1)
+            return await keygen(rest[0]);
+        if (command === 'catalog')
+            return await catalog(rest);
+        return usageError();
     }
     catch (error) {
         if (error instanceof PackageError || error instanceof ZipError) {
             console.error(`The plugin is not valid:\n${error.message}`);
             return 1;
         }
+        if (error instanceof PublishError || error instanceof CatalogError) {
+            console.error(error.message);
+            return 1;
+        }
         throw error;
     }
 }

package/dist/node/index.d.ts

@@ -1,5 +1,7 @@
 export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, type CheckedPackage, } from './package.ts';
 export { readZip, writeZip, ZipError, type ZipEntry } from './zip.ts';
+export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, type Catalog, type CatalogErrorCode, type CatalogKeys, type CatalogPayload, type CatalogPlugin, type CatalogRelease, } from './catalog.ts';
+export { PublishError, writeCatalog, writeCatalogKeys, type WrittenCatalog, type WrittenKeys, } from './publish.ts';
 export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, type Contribution, type ContributionKind, type PluginManifest, } from '../manifest.ts';
 export { checkPackageFiles, checkPackagePath, packageLimits } from '../package-rules.ts';
 export { compositionReportSchema, parseReport, reportLimits } from '../report.ts';

package/dist/node/index.js

@@ -1,5 +1,7 @@
 export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, } from "./package.js";
 export { readZip, writeZip, ZipError } from "./zip.js";
+export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, } from "./catalog.js";
+export { PublishError, writeCatalog, writeCatalogKeys, } from "./publish.js";
 // The manifest and package rules again, so Node code needs no DOM types from the runtime entry.
 export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, } from "../manifest.js";
 export { checkPackageFiles, checkPackagePath, packageLimits } from "../package-rules.js";

package/dist/node/publish.d.ts

@@ -0,0 +1,42 @@
+/** A publication that cannot go ahead; nothing has been written. */
+export declare class PublishError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+export interface WrittenKeys {
+    keyId: string;
+    publicKey: string;
+    privateKeyFile: string;
+    publicKeyFile: string;
+}
+/**
+ * Generates a catalog key pair into `<prefix>.private.pem` and `<prefix>.public.txt`. Refuses to
+ * write inside a Git working tree, where the private key could end up in a commit, and never
+ * overwrites a file.
+ */
+export declare function writeCatalogKeys(prefix: string): Promise<WrittenKeys>;
+export interface WrittenCatalog {
+    keyId: string;
+    sequence: number;
+    releases: {
+        id: string;
+        version: string;
+        file: string;
+        bytes: number;
+        sha256: string;
+    }[];
+}
+/**
+ * Publishes a catalog into a new, empty folder: validates every package the way a host does before
+ * installing it, copies each under a name derived from its content, signs `catalog.json` and checks
+ * the result with the public key. Every check runs before anything is written. Upload the
+ * `packages` folder first and `catalog.json` last.
+ */
+export declare function writeCatalog(options: {
+    /** Release configuration; relative paths in it are resolved against its folder. */
+    config: string;
+    /** PKCS#8 PEM file of the catalog's private key. */
+    privateKey: string;
+    out: string;
+    now?: Date;
+}): Promise<WrittenCatalog>;

package/dist/node/publish.js

@@ -0,0 +1,213 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { packageLimits } from "../package-rules.js";
+import { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, signCatalog, verifyCatalog, } from "./catalog.js";
+import { PackageError, readPackageArchive } from "./package.js";
+import { ZipError } from "./zip.js";
+/** A publication that cannot go ahead; nothing has been written. */
+export class PublishError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.problems = problems;
+        this.name = 'PublishError';
+    }
+}
+/** The Git working tree containing a folder, if any. */
+function gitWorkingTree(folder) {
+    for (let current = resolve(folder);;) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function readInput(path, what) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new PublishError([`${what} not found: ${path}`]);
+        throw error;
+    }
+}
+/**
+ * Generates a catalog key pair into `<prefix>.private.pem` and `<prefix>.public.txt`. Refuses to
+ * write inside a Git working tree, where the private key could end up in a commit, and never
+ * overwrites a file.
+ */
+export async function writeCatalogKeys(prefix) {
+    const base = resolve(prefix);
+    const repository = gitWorkingTree(dirname(base));
+    if (repository)
+        throw new PublishError([
+            `${dirname(base)} is inside the Git working tree ${repository}; keep private keys outside every repository`,
+        ]);
+    const privateKeyFile = `${base}.private.pem`;
+    const publicKeyFile = `${base}.public.txt`;
+    for (const file of [privateKeyFile, publicKeyFile])
+        if (existsSync(file))
+            throw new PublishError([`${file} already exists`]);
+    const keys = generateCatalogKeys();
+    await mkdir(dirname(base), { recursive: true });
+    await writeFile(privateKeyFile, keys.privateKey, { flag: 'wx', mode: 0o600 });
+    await writeFile(publicKeyFile, `${keys.publicKey}\n`, { flag: 'wx' });
+    return { keyId: keys.keyId, publicKey: keys.publicKey, privateKeyFile, publicKeyFile };
+}
+const releaseConfigSchema = z
+    .strictObject({
+    /** The catalog currently published; the new one continues its sequence. */
+    previous: z.string().min(1).optional(),
+    /** The sequence of a first publication, when there is no previous catalog. */
+    initialSequence: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
+    /** Every package the new catalog offers, as `.vormioplugin` files. */
+    packages: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(catalogLimits.maxPlugins * catalogLimits.maxReleasesPerPlugin),
+})
+    .refine((config) => (config.previous === undefined) !== (config.initialSequence === undefined), {
+    message: 'Give either previous or initialSequence',
+});
+async function readRelease(path) {
+    const size = (await stat(path).catch(() => undefined))?.size;
+    if (size === undefined)
+        throw new PublishError([`Package not found: ${path}`]);
+    if (size > packageLimits.maxArchiveBytes)
+        throw new PublishError([`${path}: larger than ${packageLimits.maxArchiveBytes} bytes`]);
+    const data = await readInput(path, 'Package');
+    try {
+        const { checked, contents } = readPackageArchive(data);
+        const sha256 = createHash('sha256').update(data).digest('hex');
+        const { id, version } = checked.manifest;
+        return {
+            id,
+            version,
+            // The manifest as the package has it, so hosts compare like with like after downloading.
+            manifest: JSON.parse(contents.get('manifest.json').toString('utf8')),
+            data,
+            sha256,
+            file: `packages/${id}-${version}-${sha256.slice(0, 12)}.vormioplugin`,
+        };
+    }
+    catch (error) {
+        if (error instanceof PackageError)
+            throw new PublishError(error.problems.map((problem) => `${path}: ${problem}`));
+        if (error instanceof ZipError)
+            throw new PublishError([`${path}: ${error.message}`]);
+        throw error;
+    }
+}
+/**
+ * Publishes a catalog into a new, empty folder: validates every package the way a host does before
+ * installing it, copies each under a name derived from its content, signs `catalog.json` and checks
+ * the result with the public key. Every check runs before anything is written. Upload the
+ * `packages` folder first and `catalog.json` last.
+ */
+export async function writeCatalog(options) {
+    const configFile = resolve(options.config);
+    const base = dirname(configFile);
+    let json;
+    try {
+        json = JSON.parse((await readInput(configFile, 'Release configuration')).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new PublishError([`${configFile}: not valid JSON`]);
+        throw error;
+    }
+    const parsed = releaseConfigSchema.safeParse(json);
+    if (!parsed.success)
+        throw new PublishError(parsed.error.issues.map((issue) => `${issue.path.join('.') || 'config'}: ${issue.message}`));
+    const config = parsed.data;
+    const privateKey = (await readInput(resolve(options.privateKey), 'Private key')).toString('utf8');
+    const publicKey = catalogPublicKey(privateKey);
+    const keyId = catalogKeyId(publicKey);
+    // The private key cannot be inside an empty folder, so this also keeps it out of the upload.
+    const out = resolve(options.out);
+    if (existsSync(out) && (await readdir(out)).length > 0)
+        throw new PublishError([`${out} is not empty; publish into a new folder`]);
+    let sequence = config.initialSequence;
+    if (config.previous !== undefined) {
+        const previousFile = resolve(base, config.previous);
+        try {
+            sequence =
+                verifyCatalog(await readInput(previousFile, 'Previous catalog'), publicKey).sequence + 1;
+        }
+        catch (error) {
+            if (error instanceof CatalogError)
+                throw new PublishError(error.problems.map((problem) => `${previousFile}: ${problem}`));
+            throw error;
+        }
+    }
+    const problems = [];
+    const plugins = new Map();
+    for (const path of config.packages) {
+        try {
+            const release = await readRelease(resolve(base, path));
+            const releases = plugins.get(release.id) ?? [];
+            if (releases.some((other) => other.version === release.version))
+                problems.push(`${release.id} ${release.version} is listed more than once`);
+            releases.push(release);
+            plugins.set(release.id, releases);
+        }
+        catch (error) {
+            if (!(error instanceof PublishError))
+                throw error;
+            problems.push(...error.problems);
+        }
+    }
+    if (problems.length)
+        throw new PublishError(problems);
+    const ordered = [...plugins.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([id, releases]) => ({
+        id,
+        releases: releases.sort((a, b) => compareVersions(b.version, a.version)),
+    }));
+    const payload = {
+        sequence,
+        publishedAt: (options.now ?? new Date()).toISOString(),
+        plugins: ordered.map(({ id, releases }) => ({
+            id,
+            releases: releases.map(({ manifest, file, data, sha256 }) => ({
+                manifest: manifest,
+                file,
+                bytes: data.length,
+                sha256,
+            })),
+        })),
+    };
+    let catalog;
+    try {
+        catalog = signCatalog(payload, privateKey);
+    }
+    catch (error) {
+        if (error instanceof CatalogError)
+            throw new PublishError([...error.problems]);
+        throw error;
+    }
+    await mkdir(join(out, 'packages'), { recursive: true });
+    const releases = ordered.flatMap(({ releases }) => releases);
+    for (const release of releases)
+        await writeFile(join(out, release.file), release.data, { flag: 'wx' });
+    await writeFile(join(out, 'catalog.json'), catalog, { flag: 'wx' });
+    verifyCatalog(await readFile(join(out, 'catalog.json')), publicKey);
+    return {
+        keyId,
+        sequence,
+        releases: releases.map(({ id, version, file, data, sha256 }) => ({
+            id,
+            version,
+            file,
+            bytes: data.length,
+            sha256,
+        })),
+    };
+}

package/dist/package-rules.d.ts

@@ -4,6 +4,8 @@ export declare const packageLimits: {
     readonly maxFileBytes: number;
     readonly maxTotalBytes: number;
     readonly maxPathLength: 240;
+    /** A `.vormioplugin` file. Archives are read whole, so this bounds memory before validation. */
+    readonly maxArchiveBytes: number;
 };
 /** Static file types a package may contain. Executables and archives are never accepted. */
 export declare const packageExtensions: ReadonlySet<string>;

package/dist/package-rules.js

@@ -4,6 +4,8 @@ export const packageLimits = {
     maxFileBytes: 16 * 1024 * 1024,
     maxTotalBytes: 64 * 1024 * 1024,
     maxPathLength: 240,
+    /** A `.vormioplugin` file. Archives are read whole, so this bounds memory before validation. */
+    maxArchiveBytes: 96 * 1024 * 1024,
 };
 /** Static file types a package may contain. Executables and archives are never accepted. */
 export const packageExtensions = new Set([

package/dist/runtime.d.ts

@@ -1,5 +1,11 @@
-import type { CompanionResult, CompanionStatus, CompositionReport, PluginBridge, PluginInput } from './bridge.ts';
-export type { CompanionResult, CompanionStatus, CompositionReport, PluginBridge, PluginInput };
+import { isNotApplicable, type CompanionResult, type CompanionStatus, type CompositionReport, type NotApplicable, type PluginBridge, type PluginInput } from './bridge.ts';
+export type { CompanionResult, CompanionStatus, CompositionReport, NotApplicable, PluginBridge, PluginInput, };
+export { isNotApplicable };
+/**
+ * The answer for a file that is not this handler's format. Return it from a viewer, thumbnail or
+ * analyzer handler; a file of your format with a problem should throw instead, so the user sees why.
+ */
+export declare function notApplicable(): NotApplicable;
 /** The host bridge; throws outside a Vormio plugin page. */
 export declare function bridge(): PluginBridge;
 /**
@@ -11,16 +17,17 @@ export declare function readCompanion(input: PluginInput, relativePath: string):
 export declare function readInput(input: PluginInput): Promise<ArrayBuffer>;
 /**
  * Runs a viewer: `show` is called for the first input and again whenever the host moves to another
- * file, with the previous call's signal aborted. Resolving reports ready; throwing reports the
- * error message.
+ * file, with the previous call's signal aborted. Resolving reports ready, resolving with
+ * `notApplicable()` reports the file is not this viewer's format, and throwing reports the error
+ * message.
  */
-export declare function viewer(show: (input: PluginInput, signal: AbortSignal) => Promise<void>): void;
-/** Runs a thumbnail provider; a canvas is converted to PNG. */
+export declare function viewer(show: (input: PluginInput, signal: AbortSignal) => Promise<void | NotApplicable>): void;
+/** Runs a thumbnail provider; a canvas is converted to PNG. `render` may return `notApplicable()`. */
 export declare function thumbnail(render: (input: PluginInput, size: {
     maxEdge: number;
-}) => Promise<Blob | HTMLCanvasElement | OffscreenCanvas>): void;
+}) => Promise<Blob | HTMLCanvasElement | OffscreenCanvas | NotApplicable>): void;
 /**
  * Runs an analyzer: `analyze` is called once per request and returns the composition report of
- * the input. Throwing reports the analysis as failed with the error message.
+ * the input, or `notApplicable()`. Throwing reports the analysis as failed with the error message.
  */
-export declare function analyzer(analyze: (input: PluginInput) => Promise<CompositionReport>): void;
+export declare function analyzer(analyze: (input: PluginInput) => Promise<CompositionReport | NotApplicable>): void;

package/dist/runtime.js

@@ -1,3 +1,12 @@
+import { isNotApplicable, } from "./bridge.js";
+export { isNotApplicable };
+/**
+ * The answer for a file that is not this handler's format. Return it from a viewer, thumbnail or
+ * analyzer handler; a file of your format with a problem should throw instead, so the user sees why.
+ */
+export function notApplicable() {
+    return { notApplicable: true };
+}
 /** The host bridge; throws outside a Vormio plugin page. */
 export function bridge() {
     const host = globalThis.vormio;
@@ -38,8 +47,9 @@ export async function readInput(input) {
 }
 /**
  * Runs a viewer: `show` is called for the first input and again whenever the host moves to another
- * file, with the previous call's signal aborted. Resolving reports ready; throwing reports the
- * error message.
+ * file, with the previous call's signal aborted. Resolving reports ready, resolving with
+ * `notApplicable()` reports the file is not this viewer's format, and throwing reports the error
+ * message.
  */
 export function viewer(show) {
     const host = bridge();
@@ -49,8 +59,12 @@ export function viewer(show) {
         const controller = new AbortController();
         current = controller;
         try {
-            await show(input, controller.signal);
-            if (!controller.signal.aborted)
+            const result = await show(input, controller.signal);
+            if (controller.signal.aborted)
+                return;
+            if (isNotApplicable(result))
+                host.notApplicable(input);
+            else
                 host.ready(input);
         }
         catch (error) {
@@ -61,10 +75,12 @@ export function viewer(show) {
     host.onInput((input) => void run(input));
     void host.getInput().then(run);
 }
-/** Runs a thumbnail provider; a canvas is converted to PNG. */
+/** Runs a thumbnail provider; a canvas is converted to PNG. `render` may return `notApplicable()`. */
 export function thumbnail(render) {
     bridge().onThumbnailRequest(async (input, size) => {
         const result = await render(input, size);
+        if (isNotApplicable(result))
+            return result;
         let blob;
         if (result instanceof Blob)
             blob = result;
@@ -77,7 +93,7 @@ export function thumbnail(render) {
 }
 /**
  * Runs an analyzer: `analyze` is called once per request and returns the composition report of
- * the input. Throwing reports the analysis as failed with the error message.
+ * the input, or `notApplicable()`. Throwing reports the analysis as failed with the error message.
  */
 export function analyzer(analyze) {
     bridge().onAnalyzeRequest(analyze);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vormio/plugin-sdk",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Manifest schema, runtime helpers and packaging for Vormio plugins.",
   "license": "MIT",
   "keywords": [