@vormio/plugin-sdk 0.0.0-stage → 0.0.3

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,160 @@
-# 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. 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`.
+
+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.
+
+**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.
+
+## 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.

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,62 @@
+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>;
+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,100 @@
+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');
+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'),
+    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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/node/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { checkPackage, PackageError, readPackageDirectory } from "./package.js";
+import { writeZip, ZipError } from "./zip.js";
+const usage = 'Usage: vormio-plugin pack <plugin directory> <output.vormioplugin>';
+/** `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;
+    }
+    if (!output.endsWith('.vormioplugin')) {
+        console.error('The output file must end with .vormioplugin');
+        return 2;
+    }
+    const target = resolve(output);
+    if (existsSync(target)) {
+        console.error(`${target} already exists; choose another name or remove it first`);
+        return 1;
+    }
+    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;
+    }
+    catch (error) {
+        if (error instanceof PackageError || error instanceof ZipError) {
+            console.error(`The plugin is not valid:\n${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/node/index.d.ts

@@ -0,0 +1,6 @@
+export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, type CheckedPackage, } from './package.ts';
+export { readZip, writeZip, ZipError, type ZipEntry } from './zip.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';
+export type { CompositionReport } from '../bridge.ts';

package/dist/node/index.js

@@ -0,0 +1,6 @@
+export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, } from "./package.js";
+export { readZip, writeZip, ZipError } from "./zip.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";
+export { compositionReportSchema, parseReport, reportLimits } from "../report.js";

package/dist/node/package.d.ts

@@ -0,0 +1,25 @@
+import { type PluginManifest } from '../manifest.ts';
+import { type PackageFile } from '../package-rules.ts';
+export declare class PackageError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** A validated plugin: its manifest, file list and content digest. */
+export interface CheckedPackage {
+    manifest: PluginManifest;
+    files: PackageFile[];
+    /** SHA-256 over every file's path and content, in path order. */
+    digest: string;
+}
+/** Validates file contents given as path → bytes (from a zip or a directory). */
+export declare function checkPackage(contents: ReadonlyMap<string, Buffer>): CheckedPackage;
+/**
+ * Reads a plugin directory. Links and junctions are refused rather than followed, and reading stops
+ * as soon as the package limits are exceeded.
+ */
+export declare function readPackageDirectory(directory: string): Promise<Map<string, Buffer>>;
+/** Reads and validates a `.vormioplugin` file. */
+export declare function readPackageArchive(zip: Buffer): {
+    checked: CheckedPackage;
+    contents: Map<string, Buffer>;
+};

package/dist/node/package.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { missingEntries, parseManifest } from "../manifest.js";
+import { checkPackageFiles, packageLimits } from "../package-rules.js";
+import { readZip } from "./zip.js";
+export class PackageError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.problems = problems;
+        this.name = 'PackageError';
+    }
+}
+/** Validates file contents given as path → bytes (from a zip or a directory). */
+export function checkPackage(contents) {
+    const files = [...contents].map(([path, data]) => ({ path, size: data.length }));
+    const problems = checkPackageFiles(files);
+    const manifestBytes = contents.get('manifest.json');
+    if (problems.length || !manifestBytes)
+        throw new PackageError(problems);
+    let json;
+    try {
+        json = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw new PackageError(['manifest.json: not valid JSON']);
+    }
+    const parsed = parseManifest(json);
+    if (!parsed.ok)
+        throw new PackageError(parsed.problems);
+    const missing = missingEntries(parsed.manifest, new Set(contents.keys()));
+    if (missing.length)
+        throw new PackageError(missing.map((entry) => `${entry}: entry not found`));
+    const digest = createHash('sha256');
+    for (const path of [...contents.keys()].sort()) {
+        digest.update(path).update('\0');
+        digest.update(createHash('sha256').update(contents.get(path)).digest()).update('\0');
+    }
+    return {
+        manifest: parsed.manifest,
+        files: files.sort((a, b) => (a.path < b.path ? -1 : 1)),
+        digest: digest.digest('hex'),
+    };
+}
+/**
+ * Reads a plugin directory. Links and junctions are refused rather than followed, and reading stops
+ * as soon as the package limits are exceeded.
+ */
+export async function readPackageDirectory(directory) {
+    const contents = new Map();
+    let total = 0;
+    const visit = async (relative) => {
+        for (const name of (await readdir(join(directory, relative))).sort()) {
+            const path = relative ? `${relative}/${name}` : name;
+            const info = await lstat(join(directory, path));
+            if (info.isSymbolicLink())
+                throw new PackageError([`${path}: links are not allowed`]);
+            if (info.isDirectory()) {
+                await visit(path);
+                continue;
+            }
+            if (!info.isFile())
+                throw new PackageError([`${path}: not a regular file`]);
+            if (contents.size >= packageLimits.maxFiles)
+                throw new PackageError([`more than ${packageLimits.maxFiles} files`]);
+            if (info.size > packageLimits.maxFileBytes)
+                throw new PackageError([`${path}: file too large`]);
+            total += info.size;
+            if (total > packageLimits.maxTotalBytes)
+                throw new PackageError(['package too large']);
+            contents.set(path, await readFile(join(directory, path)));
+        }
+    };
+    await visit('');
+    return contents;
+}
+/** Reads and validates a `.vormioplugin` file. */
+export function readPackageArchive(zip) {
+    const contents = new Map(readZip(zip).map((entry) => [entry.path, entry.data]));
+    return { checked: checkPackage(contents), contents };
+}

package/dist/node/zip.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A minimal zip reader and writer for `.vormioplugin` files: stored and deflated entries only, no
+ * encryption, no zip64, no spanning. Anything else is rejected rather than guessed at.
+ */
+export interface ZipEntry {
+    path: string;
+    data: Buffer;
+}
+export declare class ZipError extends Error {
+    constructor(message: string);
+}
+export declare function writeZip(entries: readonly ZipEntry[]): Buffer;
+/** Reads every file entry, checking sizes against the package limits and each CRC. */
+export declare function readZip(zip: Buffer): ZipEntry[];

package/dist/node/zip.js

@@ -0,0 +1,132 @@
+import { crc32, deflateRawSync, inflateRawSync } from 'node:zlib';
+import { packageLimits } from "../package-rules.js";
+export class ZipError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZipError';
+    }
+}
+const signatures = { local: 0x04034b50, central: 0x02014b50, end: 0x06054b50 };
+const utf8Flag = 0x0800;
+const symlinkMode = 0o120000;
+export function writeZip(entries) {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.path, 'utf8');
+        const compressed = deflateRawSync(entry.data, { level: 9 });
+        const stored = compressed.length >= entry.data.length;
+        const body = stored ? entry.data : compressed;
+        const checksum = crc32(entry.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(signatures.local, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(utf8Flag, 6);
+        local.writeUInt16LE(stored ? 0 : 8, 8);
+        local.writeUInt32LE(checksum, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(entry.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        locals.push(local, name, body);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(signatures.central, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(utf8Flag, 8);
+        central.writeUInt16LE(stored ? 0 : 8, 10);
+        central.writeUInt32LE(checksum, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(entry.data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, name);
+        offset += local.length + name.length + body.length;
+    }
+    const directory = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(signatures.end, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, directory, end]);
+}
+/** Reads every file entry, checking sizes against the package limits and each CRC. */
+export function readZip(zip) {
+    const endOffset = findEnd(zip);
+    const count = zip.readUInt16LE(endOffset + 10);
+    const directorySize = zip.readUInt32LE(endOffset + 12);
+    const directoryOffset = zip.readUInt32LE(endOffset + 16);
+    if (zip.readUInt16LE(endOffset + 4) !== 0 || zip.readUInt16LE(endOffset + 6) !== 0)
+        throw new ZipError('Multi-part archives are not supported');
+    if (directoryOffset + directorySize > endOffset)
+        throw new ZipError('Damaged central directory');
+    if (count > packageLimits.maxFiles * 2)
+        throw new ZipError('Too many entries');
+    const entries = [];
+    let total = 0;
+    let position = directoryOffset;
+    for (let index = 0; index < count; index++) {
+        if (position + 46 > endOffset || zip.readUInt32LE(position) !== signatures.central)
+            throw new ZipError('Damaged central directory');
+        const flags = zip.readUInt16LE(position + 8);
+        const method = zip.readUInt16LE(position + 10);
+        const checksum = zip.readUInt32LE(position + 16);
+        const compressedSize = zip.readUInt32LE(position + 20);
+        const size = zip.readUInt32LE(position + 24);
+        const nameLength = zip.readUInt16LE(position + 28);
+        const extraLength = zip.readUInt16LE(position + 30);
+        const commentLength = zip.readUInt16LE(position + 32);
+        const madeBy = zip.readUInt16LE(position + 4) >> 8;
+        const attributes = zip.readUInt32LE(position + 38);
+        const localOffset = zip.readUInt32LE(position + 42);
+        const nameBytes = zip.subarray(position + 46, position + 46 + nameLength);
+        const path = flags & utf8Flag ? nameBytes.toString('utf8') : nameBytes.toString('latin1');
+        position += 46 + nameLength + extraLength + commentLength;
+        if (flags & 0x1)
+            throw new ZipError(`${path}: encrypted entries are not supported`);
+        if (size === 0xffffffff || compressedSize === 0xffffffff || localOffset === 0xffffffff)
+            throw new ZipError(`${path}: zip64 is not supported`);
+        // Unix-made archives keep the file mode in the upper attribute bits.
+        if (madeBy === 3 && ((attributes >>> 16) & 0o170000) === symlinkMode)
+            throw new ZipError(`${path}: symbolic links are not allowed`);
+        if (path.endsWith('/'))
+            continue;
+        if (size > packageLimits.maxFileBytes)
+            throw new ZipError(`${path}: file too large`);
+        total += size;
+        if (total > packageLimits.maxTotalBytes)
+            throw new ZipError('Package too large');
+        if (method !== 0 && method !== 8)
+            throw new ZipError(`${path}: unsupported compression`);
+        if (localOffset + 30 > zip.length || zip.readUInt32LE(localOffset) !== signatures.local)
+            throw new ZipError(`${path}: damaged entry`);
+        // A local name that differs from the central one would let tools disagree on the file name.
+        const localNameLength = zip.readUInt16LE(localOffset + 26);
+        if (!zip.subarray(localOffset + 30, localOffset + 30 + localNameLength).equals(nameBytes))
+            throw new ZipError(`${path}: inconsistent entry name`);
+        const dataStart = localOffset + 30 + localNameLength + zip.readUInt16LE(localOffset + 28);
+        if (dataStart + compressedSize > directoryOffset)
+            throw new ZipError(`${path}: damaged entry`);
+        const body = zip.subarray(dataStart, dataStart + compressedSize);
+        let data;
+        try {
+            data = method === 0 ? Buffer.from(body) : inflateRawSync(body, { maxOutputLength: size });
+        }
+        catch {
+            throw new ZipError(`${path}: damaged data`);
+        }
+        if (data.length !== size || crc32(data) !== checksum)
+            throw new ZipError(`${path}: damaged data`);
+        entries.push({ path, data });
+    }
+    return entries;
+}
+function findEnd(zip) {
+    const earliest = Math.max(0, zip.length - 22 - 0xffff);
+    for (let offset = zip.length - 22; offset >= earliest; offset--)
+        if (zip.readUInt32LE(offset) === signatures.end)
+            return offset;
+    throw new ZipError('Not a zip file');
+}

package/dist/package-rules.d.ts

@@ -0,0 +1,20 @@
+/** Limits for a plugin package or development directory. */
+export declare const packageLimits: {
+    readonly maxFiles: 1024;
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+    readonly maxPathLength: 240;
+};
+/** Static file types a package may contain. Executables and archives are never accepted. */
+export declare const packageExtensions: ReadonlySet<string>;
+/**
+ * Checks a path inside a package: forward slashes, NFC, no empty, `.` or `..` segments, no
+ * characters or names Windows cannot store, and an allowed extension. Returns the problem, or null.
+ */
+export declare function checkPackagePath(path: string): string | null;
+export interface PackageFile {
+    path: string;
+    size: number;
+}
+/** Checks a package's file list as a whole; returns every problem found. */
+export declare function checkPackageFiles(files: readonly PackageFile[]): string[];

package/dist/package-rules.js

@@ -0,0 +1,78 @@
+/** Limits for a plugin package or development directory. */
+export const packageLimits = {
+    maxFiles: 1024,
+    maxFileBytes: 16 * 1024 * 1024,
+    maxTotalBytes: 64 * 1024 * 1024,
+    maxPathLength: 240,
+};
+/** Static file types a package may contain. Executables and archives are never accepted. */
+export const packageExtensions = new Set([
+    'html',
+    'js',
+    'mjs',
+    'css',
+    'json',
+    'wasm',
+    'png',
+    'jpg',
+    'jpeg',
+    'webp',
+    'svg',
+    'woff2',
+    'txt',
+    'md',
+]);
+const reservedNames = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+// eslint-disable-next-line no-control-regex
+const forbiddenCharacters = /[\u0000-\u001f\u007f\\:*?"<>|]/;
+/**
+ * Checks a path inside a package: forward slashes, NFC, no empty, `.` or `..` segments, no
+ * characters or names Windows cannot store, and an allowed extension. Returns the problem, or null.
+ */
+export function checkPackagePath(path) {
+    if (path.length === 0 || path.length > packageLimits.maxPathLength)
+        return 'invalid length';
+    if (path !== path.normalize('NFC'))
+        return 'not NFC';
+    if (forbiddenCharacters.test(path))
+        return 'forbidden character';
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.' || segment === '..')
+            return 'invalid segment';
+        if (/[. ]$/.test(segment))
+            return 'segment ends with a dot or space';
+        if (reservedNames.test(segment.split('.')[0]))
+            return 'reserved name';
+    }
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    const extension = dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+    if (!packageExtensions.has(extension))
+        return `file type .${extension || '(none)'} not allowed`;
+    return null;
+}
+/** Checks a package's file list as a whole; returns every problem found. */
+export function checkPackageFiles(files) {
+    const problems = [];
+    if (files.length > packageLimits.maxFiles)
+        problems.push(`more than ${packageLimits.maxFiles} files`);
+    let total = 0;
+    const seen = new Set();
+    for (const file of files) {
+        const problem = checkPackagePath(file.path);
+        if (problem)
+            problems.push(`${file.path}: ${problem}`);
+        if (file.size > packageLimits.maxFileBytes)
+            problems.push(`${file.path}: file too large`);
+        total += file.size;
+        const folded = file.path.toLowerCase();
+        if (seen.has(folded))
+            problems.push(`${file.path}: duplicate name ignoring case`);
+        seen.add(folded);
+    }
+    if (total > packageLimits.maxTotalBytes)
+        problems.push('package too large');
+    if (!files.some((file) => file.path === 'manifest.json'))
+        problems.push('manifest.json missing');
+    return problems;
+}

package/dist/report.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { CompositionReport } from './bridge.ts';
+/** Limits of a composition report; larger reports are rejected as a failed analysis. */
+export declare const reportLimits: {
+    readonly subresources: 10000;
+    readonly references: 50000;
+    readonly diagnostics: 500;
+    /** Serialized size: UTF-8 bytes of the report as JSON. */
+    readonly bytes: number;
+};
+export declare const compositionReportSchema: z.ZodType<CompositionReport>;
+export type ReportResult = {
+    ok: true;
+    report: CompositionReport;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** Validates a report as received from an analyzer, including its serialized size. */
+export declare function parseReport(value: unknown): ReportResult;

package/dist/report.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/** Limits of a composition report; larger reports are rejected as a failed analysis. */
+export const reportLimits = {
+    subresources: 10_000,
+    references: 50_000,
+    diagnostics: 500,
+    /** Serialized size: UTF-8 bytes of the report as JSON. */
+    bytes: 4 * 1024 * 1024,
+};
+const controlCharacters = /[\u0000-\u001f\u007f]/; // eslint-disable-line no-control-regex
+/** Display text: bounded and free of control characters. */
+const plain = (max) => z
+    .string()
+    .max(max)
+    .refine((text) => !controlCharacters.test(text), 'Control characters are not allowed');
+const key = z.string().min(1).max(200);
+const subresourceSchema = z.strictObject({
+    key,
+    kind: plain(80).min(1),
+    name: plain(200),
+    parent: key.optional(),
+});
+const referenceSchema = z
+    .strictObject({
+    from: key.optional(),
+    uri: z.string().min(1).max(2048).optional(),
+    key: key.optional(),
+    role: plain(80).min(1),
+    evidence: plain(300).optional(),
+})
+    .refine((reference) => (reference.uri === undefined) !== (reference.key === undefined), {
+    message: 'Give exactly one of uri and key',
+});
+const diagnosticSchema = z.strictObject({
+    severity: z.enum(['error', 'warning', 'info']),
+    message: z.string().min(1).max(500),
+    key: key.optional(),
+});
+/**
+ * Checks a report as a whole: unique keys, references and parents that name existing keys, and no
+ * cycles in the hierarchy.
+ */
+function consistent(report, context) {
+    const keys = new Set();
+    for (const subresource of report.subresources) {
+        if (keys.has(subresource.key))
+            context.addIssue({ code: 'custom', message: `Duplicate key ${subresource.key}` });
+        keys.add(subresource.key);
+    }
+    const known = (value, where) => {
+        if (value !== undefined && !keys.has(value))
+            context.addIssue({ code: 'custom', message: `${where} names unknown key ${value}` });
+    };
+    for (const subresource of report.subresources)
+        known(subresource.parent, 'A parent');
+    for (const reference of report.references) {
+        known(reference.from, 'A reference');
+        known(reference.key, 'A reference target');
+    }
+    for (const diagnostic of report.diagnostics)
+        known(diagnostic.key, 'A diagnostic');
+    const parents = new Map(report.subresources.map((each) => [each.key, each.parent]));
+    // Keys whose chain of parents is known to end at a root, so each key is walked only once.
+    const settled = new Set();
+    for (const start of parents.keys()) {
+        const path = new Set();
+        let current = start;
+        while (current !== undefined && !settled.has(current)) {
+            if (path.has(current)) {
+                context.addIssue({ code: 'custom', message: `The hierarchy has a cycle at ${current}` });
+                return;
+            }
+            path.add(current);
+            current = parents.get(current);
+        }
+        for (const key of path)
+            settled.add(key);
+    }
+}
+export const compositionReportSchema = z
+    .strictObject({
+    subresources: z.array(subresourceSchema).max(reportLimits.subresources),
+    references: z.array(referenceSchema).max(reportLimits.references),
+    diagnostics: z.array(diagnosticSchema).max(reportLimits.diagnostics),
+    partial: z.boolean().optional(),
+})
+    .superRefine(consistent);
+/** Validates a report as received from an analyzer, including its serialized size. */
+export function parseReport(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return { ok: false, problems: ['The report cannot be serialized'] };
+    }
+    // Measured in UTF-8 bytes. UTF-8 never takes fewer bytes than there are UTF-16 code units, so a
+    // string already too long is refused without encoding it.
+    const tooLarge = json !== undefined &&
+        (json.length > reportLimits.bytes ||
+            new TextEncoder().encode(json).byteLength > reportLimits.bytes);
+    if (tooLarge)
+        return { ok: false, problems: ['The report is larger than 4 MiB'] };
+    const result = compositionReportSchema.safeParse(value);
+    if (result.success)
+        return { ok: true, report: result.data };
+    return {
+        ok: false,
+        problems: result.error.issues
+            .slice(0, 20)
+            .map((issue) => `${issue.path.length ? issue.path.join('.') : 'report'}: ${issue.message}`),
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { CompanionResult, CompanionStatus, CompositionReport, PluginBridge, PluginInput } from './bridge.ts';
+export type { CompanionResult, CompanionStatus, CompositionReport, PluginBridge, PluginInput };
+/** The host bridge; throws outside a Vormio plugin page. */
+export declare function bridge(): PluginBridge;
+/**
+ * Reads a file next to the input, relative to the input's folder (`../` may move up within the
+ * linked folder). The host allows only extensions the contribution declares.
+ */
+export declare function readCompanion(input: PluginInput, relativePath: string): Promise<CompanionResult>;
+/** Reads the input's own bytes. */
+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.
+ */
+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 thumbnail(render: (input: PluginInput, size: {
+    maxEdge: number;
+}) => Promise<Blob | HTMLCanvasElement | OffscreenCanvas>): 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.
+ */
+export declare function analyzer(analyze: (input: PluginInput) => Promise<CompositionReport>): void;

package/dist/runtime.js

@@ -0,0 +1,84 @@
+/** The host bridge; throws outside a Vormio plugin page. */
+export function bridge() {
+    const host = globalThis.vormio;
+    if (!host)
+        throw new Error('This page is not running inside Vormio');
+    return host;
+}
+const statuses = {
+    400: 'out-of-bounds',
+    403: 'unauthorized',
+    429: 'over-limit',
+    404: 'missing',
+    409: 'changed',
+};
+/**
+ * Reads a file next to the input, relative to the input's folder (`../` may move up within the
+ * linked folder). The host allows only extensions the contribution declares.
+ */
+export async function readCompanion(input, relativePath) {
+    const url = new URL(relativePath, input.url).href;
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch {
+        return { status: 'unavailable', url };
+    }
+    if (response.ok)
+        return { status: 'ok', url, bytes: await response.arrayBuffer() };
+    return { status: statuses[response.status] ?? 'unavailable', url };
+}
+/** Reads the input's own bytes. */
+export async function readInput(input) {
+    const response = await fetch(input.url);
+    if (!response.ok)
+        throw new Error(`The file could not be read (${response.status})`);
+    return response.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.
+ */
+export function viewer(show) {
+    const host = bridge();
+    let current;
+    const run = async (input) => {
+        current?.abort();
+        const controller = new AbortController();
+        current = controller;
+        try {
+            await show(input, controller.signal);
+            if (!controller.signal.aborted)
+                host.ready(input);
+        }
+        catch (error) {
+            if (!controller.signal.aborted)
+                host.fail(input, error instanceof Error ? error.message : String(error));
+        }
+    };
+    host.onInput((input) => void run(input));
+    void host.getInput().then(run);
+}
+/** Runs a thumbnail provider; a canvas is converted to PNG. */
+export function thumbnail(render) {
+    bridge().onThumbnailRequest(async (input, size) => {
+        const result = await render(input, size);
+        let blob;
+        if (result instanceof Blob)
+            blob = result;
+        else if ('convertToBlob' in result)
+            blob = await result.convertToBlob({ type: 'image/png' });
+        else
+            blob = await new Promise((resolve, reject) => result.toBlob((png) => (png ? resolve(png) : reject(new Error('The canvas is empty'))), 'image/png'));
+        return blob.arrayBuffer();
+    });
+}
+/**
+ * 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.
+ */
+export function analyzer(analyze) {
+    bridge().onAnalyzeRequest(analyze);
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@vormio/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.3",
+  "description": "Manifest schema, runtime helpers and packaging for Vormio plugins.",
+  "license": "MIT",
+  "keywords": [
+    "vormio",
+    "plugin",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "default": "./dist/bridge.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.21.0"
+  },
+  "dependencies": {
+    "zod": "^4.6.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vormio-plugin": "./dist/node/cli.js"
+  }
 }