@vormio/plugin-sdk 0.0.7-rc.1 → 0.0.9-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.7) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.7`.
+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.9) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.9`.
 
-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.
+Plugin contract version: `apiVersion: 4`. 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": 3,
+  "apiVersion": 4,
   "id": "acme.model-viewer",
   "version": "0.1.0",
   "name": "Model Viewer",
@@ -117,6 +117,7 @@ analyzer(async (input) => {
 
 - 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.
+- `viewer(show, { focus })` also receives the host's requests to show a subresource of the shown file; see [Focusing a subresource](#focusing-a-subresource).
 
 ## Files that are not your format
 
@@ -162,6 +163,7 @@ interface CompositionReport {
     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
+    uriKey?: string // With uri: a subresource of that file, by the key its report gives it
     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"
@@ -174,7 +176,7 @@ 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, 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`.
+- 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`, a `uriKey` without a `uri`, or an `inferred` reference with a `key`. A `uriKey` is not checked against this report: it names a subresource of the other file.
 - 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.
@@ -204,6 +206,49 @@ analyzer(async (input) => {
 - 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.
 
+### References to subresources of other files
+
+When a format looks an object up by name in another file, report the object itself: give the file's address in `uri` and the object's key in that file's report in `uriKey`. A Spine skeleton's attachment uses the region of the same name in the paired atlas:
+
+```ts
+{
+  from: 'attachments/default/head/head',
+  uri: 'hero.atlas',
+  uriKey: 'region:head-front', // The key your atlas analyzer gives that region
+  role: 'Region',
+  inferred: 'Same name as the skeleton', // The atlas itself is inferred
+}
+```
+
+- A key that other files refer to is a contract within your plugin: derive it from the format's own lookup rule (for Spine, the region name), so that it stays the same when the target file is exported again. Never use a position in a list.
+- The host connects the two reports only when the same build of your plugin analyzed both files (same plugin ID and package). Your analyzers for both formats must be in one plugin.
+- Do not read the target file to check that the subresource exists. The host decides at query time, from the target's current report, and the status follows when the target is analyzed again:
+
+| The target file                                                                   | Written reference           | Inferred reference       |
+| --------------------------------------------------------------------------------- | --------------------------- | ------------------------ |
+| Does not exist                                                                    | Missing                     | Not found                |
+| Its report has the key                                                            | Resolved                    | Resolved                 |
+| Its complete report lacks the key                                                 | Missing                     | Not found                |
+| Its partial report lacks the key                                                  | Unknown (it may be omitted) | Unknown                  |
+| Has no report, an outdated one, a failed one, or one from another plugin or build | Unknown, with the reason    | Unknown, with the reason |
+
+- Keys follow the limits of `key`: at most 200 characters. Do not put the key in the address: the host ignores everything after `?` and `#`.
+
+## Focusing a subresource
+
+When the user picks a subresource in the inspector, or jumps to a subresource of another file, the host asks the viewer to show it:
+
+```ts
+viewer(showAtlas, {
+  focus: (key, input) => highlightRegion(key),
+})
+```
+
+- The key is from your own analyzer's report: the host asks only when the viewer and the shown file's analysis come from the same build of your plugin.
+- `focus` is called only after the viewer reported the file ready. A request about a file the viewer has moved away from is dropped. The same key can come again when the user asks again; show it again.
+- Find it if you can, for example by selecting, framing or highlighting it; ignore keys you cannot find. The host does not wait for an answer.
+- Pages that do not use `viewer()` subscribe with `window.vormio.onFocus(({ url, key }) => …)` and compare `url` with the input they show.
+
 ## 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`.

package/dist/bridge.d.ts

@@ -35,6 +35,11 @@ export interface ReportReference {
     uri?: string;
     /** A subresource of the analyzed file. */
     key?: string;
+    /**
+     * A subresource of the file at `uri`, by the key that file's report gives it; only with `uri`.
+     * The host connects it when the same build of your plugin analyzed that file.
+     */
+    uriKey?: string;
     /** Display label, such as "Base color texture". */
     role: string;
     /** Where in the file the reference is, such as "/images/2/uri". */
@@ -84,6 +89,15 @@ export interface PluginBridge {
      * preview.
      */
     notApplicable(input: PluginInput): void;
+    /**
+     * Called when the host asks the viewer to show a subresource of the input with `url`, by its key
+     * in your analyzer's report: only after `ready` for that input, and again whenever it is asked
+     * again. Returns the function that unsubscribes.
+     */
+    onFocus(listener: (focus: {
+        url: string;
+        key: string;
+    }) => void): () => void;
     /**
      * Thumbnail pages: handles each request from the host and returns PNG bytes no larger than
      * `maxEdge` on either side, or `{ notApplicable: true }`. (Blobs cannot cross the bridge;

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, isNotApplicable, notApplicable, readCompanion, readInput, thumbnail, viewer, type CompanionResult, type CompanionStatus, type CompositionReport, type NotApplicable, 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, type ViewerOptions, } from './runtime.ts';

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 = 3;
+export declare const pluginApiVersion = 4;
 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<3>;
+    apiVersion: z.ZodLiteral<4>;
     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 = 3;
+export const pluginApiVersion = 4;
 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

@@ -25,6 +25,7 @@ const referenceSchema = z
     from: key.optional(),
     uri: z.string().min(1).max(2048).optional(),
     key: key.optional(),
+    uriKey: key.optional(),
     role: plain(80).min(1),
     evidence: plain(300).optional(),
     inferred: plain(120).min(1).optional(),
@@ -34,6 +35,9 @@ const referenceSchema = z
 })
     .refine((reference) => reference.inferred === undefined || reference.uri !== undefined, {
     message: 'Only a reference with a uri can be inferred',
+})
+    .refine((reference) => reference.uriKey === undefined || reference.uri !== undefined, {
+    message: 'Give uriKey only with uri',
 });
 const diagnosticSchema = z.strictObject({
     severity: z.enum(['error', 'warning', 'info']),

package/dist/runtime.d.ts

@@ -15,13 +15,22 @@ export declare function bridge(): PluginBridge;
 export declare function readCompanion(input: PluginInput, relativePath: string): Promise<CompanionResult>;
 /** Reads the input's own bytes. */
 export declare function readInput(input: PluginInput): Promise<ArrayBuffer>;
+/** What a viewer can do besides showing its input. */
+export interface ViewerOptions {
+    /**
+     * Shows a subresource of the shown input, by its key in your analyzer's report, for example by
+     * highlighting it. Called only once the input is shown, and again each time the host asks again;
+     * ignore keys you cannot find.
+     */
+    focus?: (key: string, input: PluginInput) => void;
+}
 /**
  * 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, resolving with
  * `notApplicable()` reports the file is not this viewer's format, and throwing reports the error
- * message.
+ * message. `options.focus` receives the host's requests to show a subresource of the shown input.
  */
-export declare function viewer(show: (input: PluginInput, signal: AbortSignal) => Promise<void | NotApplicable>): void;
+export declare function viewer(show: (input: PluginInput, signal: AbortSignal) => Promise<void | NotApplicable>, options?: ViewerOptions): 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;

package/dist/runtime.js

@@ -49,13 +49,16 @@ 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, resolving with
  * `notApplicable()` reports the file is not this viewer's format, and throwing reports the error
- * message.
+ * message. `options.focus` receives the host's requests to show a subresource of the shown input.
  */
-export function viewer(show) {
+export function viewer(show, options = {}) {
     const host = bridge();
     let current;
+    /** The input the viewer last reported ready, until it moves to another. */
+    let shown;
     const run = async (input) => {
         current?.abort();
+        shown = undefined;
         const controller = new AbortController();
         current = controller;
         try {
@@ -64,8 +67,10 @@ export function viewer(show) {
                 return;
             if (isNotApplicable(result))
                 host.notApplicable(input);
-            else
+            else {
+                shown = input;
                 host.ready(input);
+            }
         }
         catch (error) {
             if (!controller.signal.aborted)
@@ -73,6 +78,13 @@ export function viewer(show) {
         }
     };
     host.onInput((input) => void run(input));
+    const { focus } = options;
+    if (focus)
+        host.onFocus(({ url, key }) => {
+            // A request about a file the viewer has moved away from is void.
+            if (shown?.url === url)
+                focus(key, shown);
+        });
     void host.getInput().then(run);
 }
 /** Runs a thumbnail provider; a canvas is converted to PNG. `render` may return `notApplicable()`. */

package/package.json

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