@vormio/plugin-sdk 0.0.9 → 0.0.10-rc.1

package/README.md

@@ -2,7 +2,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: 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.
+Plugin contract version: `apiVersion: 5`. 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": 4,
+  "apiVersion": 5,
   "id": "acme.model-viewer",
   "version": "0.1.0",
   "name": "Model Viewer",
@@ -59,6 +59,7 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 - `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.
+- `agreement` is optional; see [Agreements users accept before enabling](#agreements-users-accept-before-enabling).
 - 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.
@@ -73,6 +74,24 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 
 Reading more formats or companion formats, or adding an extension point, requires the user to enable the plugin again, and that approval is added to what was approved before.
 
+### Agreements users accept before enabling
+
+Some third-party terms require every user of the plugin to accept them, such as a runtime license that each user must hold. Name the terms in the manifest:
+
+```json
+{
+  "agreement": {
+    "title": "Spine Runtimes License Agreement",
+    "file": "licenses/SPINE-RUNTIMES.txt"
+  }
+}
+```
+
+- `title` is 1–80 characters without control characters. `file` is a `.txt` or `.md` file in the package, at most 256 KiB of UTF-8; Markdown is shown as plain text. A package whose agreement file is missing, too large or not UTF-8 is invalid. One agreement per plugin.
+- When the plugin is enabled in a library, the host's confirmation names the agreement and offers its full text; the plugin is enabled only when the user agrees. Declining leaves the plugin installed and not enabled. Development folders ask the same way.
+- The library records the SHA-256 of the file's bytes with the grant. A version whose agreement file differs needs enabling again, like reading more formats; a version with a file the user already accepted, such as one rolled back to, does not.
+- Use it only for terms that require acceptance by each user. The host shows and records the user's choice; neither the host nor your plugin can verify that the user meets the terms, so do not suggest otherwise.
+
 ## Runtime API
 
 ```ts
@@ -162,8 +181,9 @@ interface CompositionReport {
   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
-    uriKey?: string // With uri: a subresource of that file, by the key its report gives it
+    uris?: string[] // Several candidate files, the preferred first; only with uriKey
+    key?: string // Points to a subresource in this file; give exactly one of uri, uris and key
+    uriKey?: string // With uri or uris: 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"
@@ -175,8 +195,8 @@ 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`, 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.
+- 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; `uris` has 2–16 addresses. 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 other than exactly one of `uri`, `uris` and `key`, a `uriKey` with a `key`, `uris` without a `uriKey` or with a repeated address, 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.
@@ -235,6 +255,34 @@ When a format looks an object up by name in another file, report the object itse
 
 - Keys follow the limits of `key`: at most 200 characters. Do not put the key in the address: the host ignores everything after `?` and `#`.
 
+### References that look in one of several files
+
+Some formats look an object up by name in several files in turn. An OBJ file can name several material libraries, and `usemtl Body` uses the `Body` of the last library that defines it. Report one reference with every candidate file in `uris`, the one that wins first:
+
+```ts
+// mtllib base.mtl
+// mtllib ../materials/paint.mtl
+// usemtl Body
+{
+  from: 'groups/0',
+  uris: ['../materials/paint.mtl', 'base.mtl'], // The last mtllib wins, so it comes first
+  uriKey: 'material:Body',
+  role: 'Material',
+}
+```
+
+- Use `uris` only when there is more than one candidate; with one, give `uri` as before. The order is yours to get right: the host cannot tell which file the format would use.
+- The host goes through the candidates in order, at query time, and resolves to the first whose report has the key. A candidate that does not exist is skipped. A candidate the host cannot settle stops it, and the reference is unknown with that candidate and the reason: never resolved to a later candidate while an earlier one might have the key.
+
+| The candidates                                                                                           | Written reference        | Inferred reference       |
+| -------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------ |
+| One has the key, and every earlier one does not exist or has a complete report without it                | Resolved to that one     | Resolved to that one     |
+| None exists, or every existing one has a complete report without the key                                 | Missing                  | Not found                |
+| An earlier one is ignored, offline, outside the linked folder, or has no complete report from your build | Unknown, with the reason | Unknown, with the reason |
+
+- A missing reference counts once, however many candidates it has. The reference is listed as a referrer only of the file it resolves to; a candidate whose object is shadowed by an earlier one does not list it. Report the files themselves (each `mtllib`) as references of their own.
+- As with `uri` and `uriKey`, every candidate must be analyzed by the same build of your plugin, and you do not read the candidates to check them.
+
 ## 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:

package/dist/bridge.d.ts

@@ -33,10 +33,18 @@ export interface ReportReference {
     from?: string;
     /** The address as written in the file, relative to the analyzed file. */
     uri?: string;
+    /**
+     * Files the target is looked up in, in priority order with the preferred first: 2–16 addresses as
+     * written in the file, relative to the analyzed file. Only with `uriKey`, instead of `uri`. The
+     * host resolves to the first candidate whose report has `uriKey`; while an earlier candidate is
+     * not settled, such as not yet analyzed, the reference is unknown.
+     */
+    uris?: 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`.
+     * A subresource of the file at `uri`, or of one of the files in `uris`, by the key that file's
+     * report gives it; required with `uris`.
      * The host connects it when the same build of your plugin analyzed that file.
      */
     uriKey?: string;
@@ -46,7 +54,8 @@ export interface ReportReference {
     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.
+     * as "Same name as the skeleton". Only with `uri` or `uris`. A missing target is "not found", not
+     * missing.
      */
     inferred?: string;
 }

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, } from "./manifest.js";
+export { agreementMaxBytes, 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, 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 = 4;
+export declare const pluginApiVersion = 5;
 declare const contributionSchema: z.ZodObject<{
     id: z.ZodString;
     entry: z.ZodString;
@@ -8,16 +8,32 @@ declare const contributionSchema: z.ZodObject<{
     companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type Contribution = z.output<typeof contributionSchema>;
+/** The largest agreement file, in bytes. */
+export declare const agreementMaxBytes: number;
+/**
+ * Terms a third party requires every user to accept before using the plugin, such as a runtime
+ * license. The host shows the file when the plugin is enabled and runs the plugin only once the user
+ * agrees, per library; a changed file asks again. Nothing is verified.
+ */
+declare const agreementSchema: z.ZodObject<{
+    title: z.ZodString;
+    file: z.ZodString;
+}, z.core.$strict>;
+export type PluginAgreement = z.output<typeof agreementSchema>;
 /** `publisher.name`. The `vormio` publisher is reserved for the host. */
 export declare const pluginIdSchema: z.ZodString;
 /** A semantic version without build metadata. */
 export declare const versionSchema: z.ZodString;
 export declare const manifestSchema: z.ZodObject<{
-    apiVersion: z.ZodLiteral<4>;
+    apiVersion: z.ZodLiteral<5>;
     id: z.ZodString;
     version: z.ZodString;
     name: z.ZodString;
     description: z.ZodDefault<z.ZodString>;
+    agreement: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        file: z.ZodString;
+    }, z.core.$strict>>;
     contributions: z.ZodObject<{
         thumbnails: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;

package/dist/node/index.d.ts

@@ -1,8 +1,8 @@
-export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, type CheckedPackage, } from './package.ts';
+export { checkPackage, PackageError, type CheckedAgreement, readPackageArchive, readPackageDirectory, type CheckedPackage, } from './package.ts';
 export { readZip, writeZip, ZipError, type ZipEntry } from './zip.ts';
 export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, type Catalog, type CatalogErrorCode, type CatalogKeys, type CatalogPayload, type CatalogPlugin, type CatalogRelease, } from './catalog.ts';
 export { PublishError, writeCatalog, writeCatalogKeys, type WrittenCatalog, type WrittenKeys, } from './publish.ts';
-export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, type Contribution, type ContributionKind, type PluginManifest, } from '../manifest.ts';
+export { agreementMaxBytes, contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, type Contribution, type ContributionKind, type PluginAgreement, 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

@@ -3,6 +3,6 @@ export { readZip, writeZip, ZipError } from "./zip.js";
 export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, } from "./catalog.js";
 export { PublishError, writeCatalog, writeCatalogKeys, } from "./publish.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 { agreementMaxBytes, 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

@@ -10,6 +10,14 @@ export interface CheckedPackage {
     files: PackageFile[];
     /** SHA-256 over every file's path and content, in path order. */
     digest: string;
+    /** The agreement the manifest names, with its text and the SHA-256 of its bytes. */
+    agreement: CheckedAgreement | null;
+}
+export interface CheckedAgreement {
+    title: string;
+    file: string;
+    text: string;
+    sha256: string;
 }
 /** Validates file contents given as path → bytes (from a zip or a directory). */
 export declare function checkPackage(contents: ReadonlyMap<string, Buffer>): CheckedPackage;

package/dist/node/package.js

@@ -1,7 +1,7 @@
 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 { agreementMaxBytes, missingEntries, parseManifest, } from "../manifest.js";
 import { checkPackageFiles, packageLimits } from "../package-rules.js";
 import { readZip } from "./zip.js";
 export class PackageError extends Error {
@@ -12,6 +12,25 @@ export class PackageError extends Error {
         this.name = 'PackageError';
     }
 }
+/** Reads the agreement file the manifest names: present, at most 256 KiB, and valid UTF-8. */
+function checkAgreement(manifest, contents) {
+    if (!manifest.agreement)
+        return null;
+    const { title, file } = manifest.agreement;
+    const data = contents.get(file);
+    if (!data)
+        throw new PackageError([`${file}: agreement not found`]);
+    if (data.length > agreementMaxBytes)
+        throw new PackageError([`${file}: agreement larger than 256 KiB`]);
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(data);
+    }
+    catch {
+        throw new PackageError([`${file}: agreement is not UTF-8`]);
+    }
+    return { title, file, text, sha256: createHash('sha256').update(data).digest('hex') };
+}
 /** 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 }));
@@ -32,6 +51,7 @@ export function checkPackage(contents) {
     const missing = missingEntries(parsed.manifest, new Set(contents.keys()));
     if (missing.length)
         throw new PackageError(missing.map((entry) => `${entry}: entry not found`));
+    const agreement = checkAgreement(parsed.manifest, contents);
     const digest = createHash('sha256');
     for (const path of [...contents.keys()].sort()) {
         digest.update(path).update('\0');
@@ -41,6 +61,7 @@ export function checkPackage(contents) {
         manifest: parsed.manifest,
         files: files.sort((a, b) => (a.path < b.path ? -1 : 1)),
         digest: digest.digest('hex'),
+        agreement,
     };
 }
 /**

package/dist/report.d.ts

@@ -4,6 +4,8 @@ import type { CompositionReport } from './bridge.ts';
 export declare const reportLimits: {
     readonly subresources: 10000;
     readonly references: 50000;
+    /** Candidate files of one reference (`uris`). */
+    readonly candidates: 16;
     readonly diagnostics: 500;
     /** Serialized size: UTF-8 bytes of the report as JSON. */
     readonly bytes: number;

package/dist/report.js

@@ -3,6 +3,8 @@ import { z } from 'zod';
 export const reportLimits = {
     subresources: 10_000,
     references: 50_000,
+    /** Candidate files of one reference (`uris`). */
+    candidates: 16,
     diagnostics: 500,
     /** Serialized size: UTF-8 bytes of the report as JSON. */
     bytes: 4 * 1024 * 1024,
@@ -14,6 +16,7 @@ const plain = (max) => z
     .max(max)
     .refine((text) => !controlCharacters.test(text), 'Control characters are not allowed');
 const key = z.string().min(1).max(200);
+const uri = z.string().min(1).max(2048);
 const subresourceSchema = z.strictObject({
     key,
     kind: plain(80).min(1),
@@ -23,21 +26,29 @@ const subresourceSchema = z.strictObject({
 const referenceSchema = z
     .strictObject({
     from: key.optional(),
-    uri: z.string().min(1).max(2048).optional(),
+    uri: uri.optional(),
+    uris: z
+        .array(uri)
+        .min(2)
+        .max(reportLimits.candidates)
+        .refine((uris) => new Set(uris).size === uris.length, 'Candidates must not repeat')
+        .optional(),
     key: key.optional(),
     uriKey: 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.uri, reference.uris, reference.key].filter((each) => each !== undefined).length ===
+    1, { message: 'Give exactly one of uri, uris and key' })
+    .refine((reference) => reference.inferred === undefined || reference.key === undefined, {
+    message: 'Only a reference with a uri or uris can be inferred',
 })
-    .refine((reference) => reference.inferred === undefined || reference.uri !== undefined, {
-    message: 'Only a reference with a uri can be inferred',
+    .refine((reference) => reference.uriKey === undefined || reference.key === undefined, {
+    message: 'Give uriKey only with uri or uris',
 })
-    .refine((reference) => reference.uriKey === undefined || reference.uri !== undefined, {
-    message: 'Give uriKey only with uri',
+    .refine((reference) => reference.uris === undefined || reference.uriKey !== undefined, {
+    message: 'Give uriKey with uris',
 });
 const diagnosticSchema = z.strictObject({
     severity: z.enum(['error', 'warning', 'info']),

package/package.json

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