@vormio/plugin-sdk 0.0.0-stage → 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vormio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# @vormio/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.5) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.5`.
+
+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.
+
+## What a plugin can do
+
+A plugin provides three capabilities for the formats it declares. They are independent: declaring one does not grant the others.
+
+| Extension point | Runs in                                        | Result                                                                                                                       |
+| --------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Thumbnail       | A hidden sandboxed page; Canvas and WebGL work | One PNG whose longest edge is at most the host's `maxEdge` (currently 320); the host then caps it at 512×512 and 4 MiB       |
+| Viewer          | A sandboxed page over Vormio's viewing area    | Shows the file read-only; the user can interact with it                                                                      |
+| Analyzer        | A hidden sandboxed page                        | A composition report: the file's internal subresources, the files it references and diagnostics; see [Analyzers](#analyzers) |
+
+A plugin runs only after it is enabled in a library. Each plugin has its own memory partition:
+
+- No access to the network, `file:` or other plugins.
+- No Node and no `eval`.
+- WebAssembly and Workers are available.
+- It can read only the file the host binds to it, plus companion files in the same linked folder whose extensions are listed in `companionFormats`.
+- It cannot modify any file.
+
+## Package layout
+
+A plugin is a folder: a `manifest.json` at the root plus the built static files.
+
+```json
+{
+  "apiVersion": 1,
+  "id": "acme.model-viewer",
+  "version": "0.1.0",
+  "name": "Model Viewer",
+  "description": "Example.",
+  "contributions": {
+    "thumbnails": [
+      {
+        "id": "model",
+        "entry": "thumbnail.html",
+        "formats": ["gltf", "glb"],
+        "companionFormats": ["bin", "png", "jpg"]
+      }
+    ],
+    "viewers": [
+      {
+        "id": "model",
+        "entry": "viewer.html",
+        "formats": ["gltf", "glb"],
+        "companionFormats": ["bin", "png", "jpg"]
+      }
+    ],
+    "analyzers": [{ "id": "model", "entry": "analyzer.html", "formats": ["gltf", "glb"] }]
+  }
+}
+```
+
+- `thumbnails`, `viewers` and `analyzers` are each optional, but there must be at least one extension point. Each kind allows up to 8, with unique IDs within the kind.
+- `id` is `publisher.name`, using only lowercase letters, digits and hyphens. The `vormio` publisher is reserved for the host.
+- `formats` and `companionFormats` are lowercase extensions without the dot. Wildcards are not allowed.
+- `entry` is an HTML file in the package. Pages run under a strict Content Security Policy: scripts must be separate files, not inline.
+- Unknown fields are rejected.
+
+**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; the `.vormioplugin` file itself is at most 96 MiB.
+
+**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(async (input, signal) => {
+  const bytes = await readInput(input)
+  const texture = await readCompanion(input, 'textures/base.png')
+  if (texture.status !== 'ok') console.warn(texture.status)
+  // …render; signal aborts when the viewer moves to the next file.
+})
+
+// Thumbnail: return a Blob, HTMLCanvasElement or OffscreenCanvas.
+thumbnail(async (input, { maxEdge }) => {
+  const canvas = new OffscreenCanvas(maxEdge, maxEdge)
+  // …draw
+  return canvas
+})
+
+// Analyzer: return the file's composition report; see the next section.
+analyzer(async (input) => {
+  const gltf = JSON.parse(new TextDecoder().decode(await readInput(input)))
+  // …
+  return { subresources: [], references: [], diagnostics: [] }
+})
+```
+
+- `input.url` is the main file's address. Companion files resolve by relative address, just as on disk: for `textures/a.png` in a glTF, `fetch(new URL('textures/a.png', input.url))` works, and loaders can use these addresses directly. The addresses support Range requests.
+- Read results:
+
+| Status          | Meaning                                                                                                     | HTTP  |
+| --------------- | ----------------------------------------------------------------------------------------------------------- | ----- |
+| `ok`            | Read succeeded                                                                                              | 200   |
+| `out-of-bounds` | Invalid path                                                                                                | 400   |
+| `unauthorized`  | The extension is not in `companionFormats`                                                                  | 403   |
+| `over-limit`    | More than 256 companion requests in one binding                                                             | 429   |
+| `missing`       | The file is not in the linked folder, or it was skipped by the scan, removed from the library or is missing | 404   |
+| `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.
+- 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.
+
+## 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.
+
+A report describes one version of the analyzed file:
+
+```ts
+interface CompositionReport {
+  /** Locatable objects inside the file, at most 10,000. */
+  subresources: {
+    key: string // Unique within this file version, chosen by the plugin, e.g. "materials/0"
+    kind: string // Display category, e.g. "Material"; the host uses it only for grouping
+    name: string // Display name; may be an empty string
+    parent?: string // Key of the parent subresource, for display hierarchy
+  }[]
+  /** References, at most 50,000. */
+  references: {
+    from?: string // Key of the referencing subresource; omitted means the file itself
+    uri?: string // Points to another file: the raw address written in the file
+    key?: string // Points to a subresource in this file; give exactly one of uri and key
+    role: string // Display role, e.g. "Base color texture"
+    evidence?: string // Location in the file, e.g. "/images/2/uri"
+  }[]
+  /** Problems found during analysis, at most 500. */
+  diagnostics: { severity: 'error' | 'warning' | 'info'; message: string; key?: string }[]
+  /** Only part of the analysis completed. */
+  partial?: boolean
+}
+```
+
+- The host validates reports with `compositionReportSchema` (`parseReport` also checks the size); plugins can check themselves against the same schema before returning. The report serialized as JSON is at most 4 MiB (counted in UTF-8 bytes). Names and keys are at most 200 characters, kinds and roles 80, evidence 300, diagnostics 500 and addresses 2,048. Names, kinds, roles and evidence must not contain control characters.
+- The report is invalid if it has duplicate keys, a `parent`, `from` or `key` that points to a missing subresource, a cyclic hierarchy, or a reference with both or neither of `uri` and `key`.
+- Write `uri` exactly as it appears in the file; do not resolve it yourself. The host decodes percent-encoding once, ignores everything after `?` and `#`, treats `\` as `/`, resolves it relative to the analyzed file and classifies it: a file in the linked folder, out of bounds (`..` leaving the linked folder), embedded (`data:`), external (absolute paths, drive letters, other schemes) or invalid (undecodable, containing control characters, or pointing to a folder). Whether the target exists is decided by the host at query time.
+- For embedded data (`data:`), report only the header up to the comma, e.g. `data:image/png;base64`. The host classifies it as embedded by prefix and does not store the content; a full `data:` address often exceeds 2,048 characters and would invalidate the whole report.
+- Reporting a reference does not require reading the target file, so you do not need `companionFormats` just to report references. Declare them only when the analysis actually reads companion files.
+
+## Packaging and development
+
+The package declares `"sideEffects": false`: when a plugin page uses only the runtime helpers, bundlers (esbuild, Vite, Rollup, webpack) drop the manifest schema and its zod dependency, leaving about 1 KB of runtime code for a minimal page. Node-side packaging and validation are imported from `@vormio/plugin-sdk/node`.
+
+```bash
+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

@@ -0,0 +1,76 @@
+/**
+ * What the host binds a plugin page to: one observed version of one file. `url` serves its bytes
+ * (with byte ranges); companion files resolve relative to it, as they do on disk.
+ */
+export interface PluginInput {
+    url: string;
+    name: string;
+    extension: string;
+    size: number;
+}
+export type CompanionStatus = 'out-of-bounds' | 'unauthorized' | 'over-limit' | 'missing' | 'changed' | 'unavailable';
+export type CompanionResult = {
+    status: 'ok';
+    url: string;
+    bytes: ArrayBuffer;
+} | {
+    status: CompanionStatus;
+    url: string;
+};
+/** An object inside the analyzed file that can be located, such as a mesh or a material. */
+export interface ReportSubresource {
+    /** Unique and stable within this version of the file; chosen by the plugin. */
+    key: string;
+    /** Display label used for grouping, such as "Material"; the host does not interpret it. */
+    kind: string;
+    name: string;
+    /** Key of the subresource this one belongs to, for display as a hierarchy. */
+    parent?: string;
+}
+/** A reference to another file (`uri`) or to a subresource of this file (`key`): exactly one. */
+export interface ReportReference {
+    /** Key of the subresource that refers; omitted when the file itself refers. */
+    from?: string;
+    /** The address as written in the file, relative to the analyzed file. */
+    uri?: string;
+    /** A subresource of the analyzed file. */
+    key?: string;
+    /** Display label, such as "Base color texture". */
+    role: string;
+    /** Where in the file the reference is, such as "/images/2/uri". */
+    evidence?: string;
+}
+export interface ReportDiagnostic {
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    /** The subresource the diagnostic is about. */
+    key?: string;
+}
+/** What an analyzer found in one observed version of one file. */
+export interface CompositionReport {
+    subresources: ReportSubresource[];
+    references: ReportReference[];
+    diagnostics: ReportDiagnostic[];
+    /** The analyzer could only finish part of the file. */
+    partial?: boolean;
+}
+/** The frozen object the host's plugin preload exposes as `window.vormio`. */
+export interface PluginBridge {
+    /** The viewer's current input. */
+    getInput(): Promise<PluginInput>;
+    /** Called when the viewer moves to another file; returns the function that unsubscribes. */
+    onInput(listener: (input: PluginInput) => void): () => void;
+    /** The viewer shows `input`; the host removes its loading state. */
+    ready(input: PluginInput): void;
+    /** The viewer cannot show `input`; the host shows `message` as plain text. */
+    fail(input: PluginInput, message: string): 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.)
+     */
+    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;
+}

package/dist/bridge.js

@@ -0,0 +1,2 @@
+// Types shared by plugin pages and the host's plugin preload. No DOM types, so Node code can use them.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, type Contribution, type ContributionKind, type ManifestResult, type PluginManifest, } from './manifest.ts';
+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';

package/dist/index.js

@@ -0,0 +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";

package/dist/manifest.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/** The plugin contract version this SDK describes. Hosts load only plugins with this version. */
+export declare const pluginApiVersion = 1;
+declare const contributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    entry: z.ZodString;
+    formats: z.ZodArray<z.ZodString>;
+    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>;
+    id: z.ZodString;
+    version: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    contributions: z.ZodObject<{
+        thumbnails: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            entry: z.ZodString;
+            formats: z.ZodArray<z.ZodString>;
+            companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        viewers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            entry: z.ZodString;
+            formats: z.ZodArray<z.ZodString>;
+            companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        analyzers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            entry: z.ZodString;
+            formats: z.ZodArray<z.ZodString>;
+            companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PluginManifest = z.output<typeof manifestSchema>;
+export type ContributionKind = 'thumbnail' | 'viewer' | 'analyzer';
+/** Every contribution of a manifest with its kind. */
+export declare function contributionsOf(manifest: PluginManifest): {
+    kind: ContributionKind;
+    contribution: Contribution;
+}[];
+export type ManifestResult = {
+    ok: true;
+    manifest: PluginManifest;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** Validates parsed `manifest.json` content and reports every problem with its field path. */
+export declare function parseManifest(value: unknown): ManifestResult;
+/** Entry files the manifest names but the package does not contain. */
+export declare function missingEntries(manifest: PluginManifest, paths: ReadonlySet<string>): string[];
+/**
+ * What a plugin may do, in a canonical form: every contribution's kind, ID, formats and companion
+ * formats, sorted. Hosts hash it into the permission fingerprint that a library's grant records;
+ * names, descriptions, versions and code are not part of it.
+ */
+export declare function permissionSummary(manifest: PluginManifest): string;
+export {};

package/dist/manifest.js

@@ -0,0 +1,103 @@
+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;
+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');
+const contributionSchema = z.strictObject({
+    /** Unique within its kind; lower case, digits and hyphens. */
+    id: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),
+    /** An HTML file in the package that the host loads in a sandboxed page. */
+    entry: z.string().refine((path) => checkPackagePath(path) === null && path.endsWith('.html'), {
+        message: 'The entry must be an .html file inside the package',
+    }),
+    /** Extensions of the main files this contribution handles. */
+    formats: extensions(1),
+    /** Extensions of other files it may read next to the main file. */
+    companionFormats: extensions(0).default([]),
+});
+const contributionList = z
+    .array(contributionSchema)
+    .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),
+    id: pluginIdSchema,
+    version: versionSchema,
+    name: z.string().trim().min(1).max(80),
+    description: z.string().max(400).default(''),
+    contributions: z
+        .strictObject({
+        thumbnails: contributionList,
+        viewers: contributionList,
+        analyzers: contributionList,
+    })
+        .refine((contributions) => contributions.thumbnails.length +
+        contributions.viewers.length +
+        contributions.analyzers.length >
+        0, 'Declare at least one contribution'),
+});
+/** Every contribution of a manifest with its kind. */
+export function contributionsOf(manifest) {
+    return [
+        ...manifest.contributions.thumbnails.map((contribution) => ({
+            kind: 'thumbnail',
+            contribution,
+        })),
+        ...manifest.contributions.viewers.map((contribution) => ({
+            kind: 'viewer',
+            contribution,
+        })),
+        ...manifest.contributions.analyzers.map((contribution) => ({
+            kind: 'analyzer',
+            contribution,
+        })),
+    ];
+}
+/** Validates parsed `manifest.json` content and reports every problem with its field path. */
+export function parseManifest(value) {
+    const result = manifestSchema.safeParse(value);
+    if (result.success)
+        return { ok: true, manifest: result.data };
+    return {
+        ok: false,
+        problems: result.error.issues.map((issue) => `${issue.path.length ? issue.path.join('.') : 'manifest'}: ${issue.message}`),
+    };
+}
+/** Entry files the manifest names but the package does not contain. */
+export function missingEntries(manifest, paths) {
+    return contributionsOf(manifest)
+        .map(({ contribution }) => contribution.entry)
+        .filter((entry) => !paths.has(entry));
+}
+/**
+ * What a plugin may do, in a canonical form: every contribution's kind, ID, formats and companion
+ * formats, sorted. Hosts hash it into the permission fingerprint that a library's grant records;
+ * names, descriptions, versions and code are not part of it.
+ */
+export function permissionSummary(manifest) {
+    const entries = contributionsOf(manifest)
+        .map(({ kind, contribution }) => ({
+        kind,
+        id: contribution.id,
+        formats: [...contribution.formats].sort(),
+        companionFormats: [...contribution.companionFormats].sort(),
+    }))
+        .sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+    return JSON.stringify({
+        apiVersion: manifest.apiVersion,
+        id: manifest.id,
+        contributions: entries,
+    });
+}

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 {};