@vormio/plugin-sdk 0.0.5 → 0.0.7-rc.1

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.7) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.7`.
 
-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: 3`. 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": 3,
   "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:
 
@@ -139,6 +164,7 @@ interface CompositionReport {
     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"
+    inferred?: string // Not written in the file: how you inferred it, e.g. "Same name as the skeleton"
   }[]
   /** Problems found during analysis, at most 500. */
   diagnostics: { severity: 'error' | 'warning' | 'info'; message: string; key?: string }[]
@@ -147,12 +173,37 @@ interface CompositionReport {
 }
 ```
 
-- 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`.
+- 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, bases of inference 120, evidence 300, diagnostics 500 and addresses 2,048. Names, kinds, roles, bases of inference 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, a reference with both or neither of `uri` and `key`, or an `inferred` reference with a `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.
 
+### Inferred references
+
+Some formats pair files by convention rather than by an address in the file. A Spine skeleton does not name its atlas; the runtime pairs `hero.json` with `hero.atlas` because they share a name. Report such a relation as an inferred reference, with the basis of the inference in `inferred`:
+
+```ts
+analyzer(async (input) => {
+  const skeleton = parseSkeleton(await readInput(input))
+  const atlas = `${input.name.replace(/\.[^.]*$/, '')}.atlas`
+  return {
+    ...skeleton.report,
+    references: [
+      ...skeleton.report.references,
+      { uri: atlas, role: 'Atlas', inferred: 'Same name as the skeleton' },
+    ],
+  }
+})
+```
+
+- Mark a reference as inferred only when the file does not write the address. References read from the file stay as they are.
+- The basis is shown to the user as is. Say why you think the relation exists, not where it is.
+- Write the address relative to the analyzed file and do not check that the target exists: the host decides at query time, so a target that appears or disappears needs no new analysis.
+- The host shows inferred references apart from written ones. A missing target is shown as "not found": it does not count as a missing reference, does not appear in the missing references filter and gets no note about where a moved file went, because the convention may simply not apply.
+- The inference may depend on the file's name. When an analyzed file with inferred references is renamed or moved, the host analyzes it again.
+- Do not report the same target both as written and as inferred.
+
 ## 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`.
@@ -165,6 +216,8 @@ The command validates the manifest and every file, then writes a zip-format `.vo
 
 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.
 
+When the host lacks something your plugin needs, or behaves wrongly, open an issue at [Vormio/Vormio-Core](https://github.com/Vormio/Vormio-Core/issues) with the plugin request template: the scenario, the plugin capability it blocks, what you expect, and how to tell it works. Host capabilities are added in a generic form, never for one format. A contract change may first ship as a prerelease under the npm tag `next` (`npm install @vormio/plugin-sdk@next`) so you can try it; `latest` follows Vormio releases.
+
 ## 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:

package/dist/bridge.d.ts

@@ -39,6 +39,11 @@ export interface ReportReference {
     role: string;
     /** Where in the file the reference is, such as "/images/2/uri". */
     evidence?: string;
+    /**
+     * The reference is not written in the file: how the analyzer inferred it, shown to the user, such
+     * as "Same name as the skeleton". Only with `uri`. A missing target is "not found", not missing.
+     */
+    inferred?: string;
 }
 export interface ReportDiagnostic {
     severity: 'error' | 'warning' | 'info';
@@ -54,6 +59,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 +79,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 = 3;
 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<3>;
     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 = 3;
 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/report.js

@@ -27,9 +27,13 @@ const referenceSchema = z
     key: key.optional(),
     role: plain(80).min(1),
     evidence: plain(300).optional(),
+    inferred: plain(120).min(1).optional(),
 })
     .refine((reference) => (reference.uri === undefined) !== (reference.key === undefined), {
     message: 'Give exactly one of uri and key',
+})
+    .refine((reference) => reference.inferred === undefined || reference.uri !== undefined, {
+    message: 'Only a reference with a uri can be inferred',
 });
 const diagnosticSchema = z.strictObject({
     severity: z.enum(['error', 'warning', 'info']),

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