@vormio/plugin-sdk 0.0.5 → 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, 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`.
+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",
@@ -78,7 +78,8 @@ Reading more formats or companion formats, or adding an extension point, require
 ```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')
@@ -114,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:
 

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;
@@ -13,7 +13,7 @@ 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');

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.5",
+  "version": "0.0.6",
   "description": "Manifest schema, runtime helpers and packaging for Vormio plugins.",
   "license": "MIT",
   "keywords": [