@vestra-player/sdk 1.5.7 → 1.5.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.5.8
+
+**Trial loading is removed; `resolvers.fileTypes`; the CLI under `--permission`.** `apiVersion` stays `vestra/1`. The removal breaks code that called `PackageCandidate.trial()`: only Vestra Player AI did, and it moves to installing (an install can be rolled back).
+
+- **Removed: `PackageCandidate.trial()`, the `PackageTrial` type, `PluginInfo.origin` `"trial"` and the error code `cleanup`** (only `PackageTrial.stop` used it). The player (0.4.2) no longer answers `packages.trial`, `packages.trialState`, `packages.trialStateByRequest` or `packages.stopTrial`, and never lists a plugin with origin `"trial"`. Trial loads only supported plugins using `commands`, `ui.window` and `events`, listed the plugin under another id (`<id>.trial.<n>`), and `trial()` returned before activation ended, so the feature was removed instead of extended. Check a package with `validate` and install it; `rollback` restores the previous version.
+- **`plugin.resolvers.fileTypes`** (player 0.4.2): the extensions some plugin's file resolver handles, lower case, sorted, each once, without who registered them; `[]` from older players. Reading needs no capability. **`plugin.resolvers.onFileTypesChange(listener)`** follows it when a file resolver comes or goes (needs `events`). For a playlist that accepts ROMs while an emulator plugin runs. `TestHost`: `host.fileTypes()` (this plugin's file resolvers plus `otherResolvers`) and `host.updateFileTypes()` after changing `otherResolvers`.
+- **`vestra-plugin` runs under Node's permission model** (`--permission`, with `--allow-child-process` for the type checker): looking for `node_modules/@types`, `tsconfig.json` and `.git` in parent folders it may not read threw `ERR_ACCESS_DENIED`; such a folder now counts as absent.
+- `Packages.validate`: the player (0.4.2) keeps the 32 most recent candidates and drops the oldest, whose `install` then fails with `stale`; before, the 33rd validation of a run failed with `busy` until the player restarted.
+
 ## 1.5.7
 
 **Replaced or closed streams stop with `null`.** A fix; no API change, `apiVersion` stays `vestra/1`, any player.

package/bin/vestra-plugin.mjs

@@ -34,7 +34,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync as exists } from "node:fs";
 import {
   cp,
   mkdir,
@@ -110,6 +110,20 @@ async function json(path, fallback) {
 }
 
 /** A module from the plugin's project first, else the SDK's own dependencies. */
+/**
+ * Whether a path exists. Under Node's permission model (`--permission`)
+ * `existsSync` throws for a path outside the allowed ones; such a path
+ * counts as absent, as for a user who cannot read it.
+ */
+function present(path) {
+  try {
+    return exists(path);
+  } catch (error) {
+    if (error?.code === "ERR_ACCESS_DENIED") return false;
+    throw error;
+  }
+}
+
 function resolveFrom(directory, specifier) {
   for (const base of [directory, sdkRoot]) {
     try {
@@ -139,7 +153,7 @@ async function typescript() {
 async function plugin(path) {
   const directory = resolve(path);
   const name = relative(process.cwd(), directory) || basename(directory);
-  if (!existsSync(join(directory, "manifest.json")))
+  if (!present(join(directory, "manifest.json")))
     fail(`${name}: no manifest.json in ${directory}`);
   const manifest = await json(join(directory, "manifest.json"));
   const { problems, hints } = manifestProblems(manifest, directory);
@@ -165,7 +179,7 @@ function displayFiles(target) {
     const field = name === "README.md" ? "readme" : "changelog";
     if (
       target.manifest[field] === undefined &&
-      existsSync(join(target.directory, name))
+      present(join(target.directory, name))
     )
       files.add(name);
   }
@@ -200,7 +214,7 @@ function dependencies(target) {
   };
   if (
     !Object.keys(deps).length ||
-    existsSync(join(target.directory, "node_modules"))
+    present(join(target.directory, "node_modules"))
   )
     return;
   console.log(`${target.name}: installing dependencies (npm ci)`);
@@ -221,7 +235,7 @@ function* upwards(directory) {
   for (let current = directory; ;) {
     yield current;
     const parent = dirname(current);
-    if (parent === current || existsSync(join(current, ".git"))) return;
+    if (parent === current || present(join(current, ".git"))) return;
     current = parent;
   }
 }
@@ -235,13 +249,13 @@ function checkConfig(target, sources) {
   const roots = [];
   for (const directory of upwards(target.directory)) {
     const types = join(directory, "node_modules/@types");
-    if (existsSync(types)) roots.push(types);
+    if (present(types)) roots.push(types);
   }
   const node = resolveFrom(target.directory, "@types/node/package.json");
   if (node) roots.push(dirname(dirname(node)));
   const base = [...upwards(target.directory)]
     .map((directory) => join(directory, "tsconfig.json"))
-    .find((file) => existsSync(file));
+    .find((file) => present(file));
   return {
     ...(base ? { extends: base } : {}),
     compilerOptions: {
@@ -262,7 +276,7 @@ async function check(target) {
   const own = (await files(target.directory)).filter(
     (file) => isTypeScript(file) || file.endsWith(".mts"),
   );
-  const tests = existsSync(join(target.directory, "tests"))
+  const tests = present(join(target.directory, "tests"))
     ? (await readdir(join(target.directory, "tests")))
         .filter(isTypeScript)
         .map((file) => join("tests", file))
@@ -308,7 +322,7 @@ function entries(target) {
   const entry = target.manifest.entry.replace(/^dist\//, "");
   const candidates = [entry.replace(/\.js$/, ".ts"), entry];
   const found = candidates.find((file) =>
-    existsSync(join(target.directory, file)),
+    present(join(target.directory, file)),
   );
   if (!found)
     fail(`${target.name}: entry ${target.manifest.entry} has no source file`);
@@ -454,7 +468,7 @@ async function build(target, flag) {
 
 async function test(target) {
   const directory = join(target.directory, "tests");
-  const tests = existsSync(directory)
+  const tests = present(directory)
     ? (await readdir(directory))
         .filter((file) => /\.test\.(ts|mjs)$/.test(file))
         .sort()

package/dist/commands.d.ts

@@ -20,8 +20,7 @@ import type { Transport } from "./wire.ts";
  */
 export declare const COMMAND_LIMITS: {
     /**
-     * Commands one plugin instance may have at the same time (160). A trial
-     * package is its own instance.
+     * Commands one plugin instance may have at the same time (160).
      */
     readonly perPlugin: 160;
     /** Commands of every plugin plus the player's own, together (1024). */

package/dist/commands.js

@@ -18,8 +18,7 @@
  */
 export const COMMAND_LIMITS = {
     /**
-     * Commands one plugin instance may have at the same time (160). A trial
-     * package is its own instance.
+     * Commands one plugin instance may have at the same time (160).
      */
     perPlugin: 160,
     /** Commands of every plugin plus the player's own, together (1024). */

package/dist/plugin/packages.js

@@ -1,4 +1,4 @@
-/** Package validation, trial loading and install/rollback (`plugins.manage`). */
+/** Package validation and install/rollback (`plugins.manage`). */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { failure, sleep, uncertain } from "./runtime.js";
@@ -9,51 +9,6 @@ const TERMINAL = [
     "failedDegraded",
     "tooLate",
 ];
-const STARTING = ["preparing", "activating", "starting"];
-class TrialHandle {
-    #scope;
-    #record;
-    #stopped;
-    constructor(scope, record) {
-        this.#scope = scope;
-        this.#record = record;
-        scope.add(this);
-    }
-    get status() {
-        return this.#record.status;
-    }
-    /**
-     * Concurrent calls share one stop; a confirmed stop is final. A failed one
-     * (code `cleanup`: the host did not confirm cleanup) is forgotten, so the
-     * next call sends a new stop to the host.
-     */
-    stop() {
-        const host = this.#scope.runtime.host.packages;
-        if (this.#stopped)
-            return this.#stopped;
-        const stopping = (async () => {
-            this.#record = await host.stopTrial(this.#record.trialId);
-            while (!this.#record.cleanupConfirmed &&
-                this.#record.status !== "stopped" &&
-                this.#record.status !== "failed") {
-                await sleep(250);
-                this.#record = await host.trialState(this.#record.trialId);
-            }
-            if (!this.#record.cleanupConfirmed)
-                throw failure("cleanup", `trial cleanup not confirmed: ${this.#record.status}`);
-        })();
-        this.#stopped = stopping;
-        stopping.catch(() => {
-            if (this.#stopped === stopping)
-                this.#stopped = undefined;
-        });
-        return stopping;
-    }
-    async dispose() {
-        this.#scope.forget(this);
-        await this.stop().catch(() => { });
-    }
-}
 class ChangeHandle {
     #scope;
     #id;
@@ -123,24 +78,6 @@ async function change(scope, submit, id) {
     }
     return new ChangeHandle(scope, operation);
 }
-async function trial(scope, runtime, token) {
-    const host = runtime.host.packages;
-    const requestId = randomUUID();
-    let record;
-    try {
-        record = await host.trial(token, requestId);
-    }
-    catch (error) {
-        if (!uncertain(error))
-            throw error;
-        record = await host.trialStateByRequest(requestId);
-    }
-    while (STARTING.includes(record.status)) {
-        await sleep(250);
-        record = await host.trialState(record.trialId);
-    }
-    return new TrialHandle(scope, record);
-}
 function installOptions(options) {
     if (options === undefined)
         return {};
@@ -171,7 +108,6 @@ function candidate(scope, directory, checked) {
         digest: checked.digest,
         manifest: checked.manifest,
         checks: checked.checks,
-        trial: () => trial(scope, runtime, checked.token),
         install: async (options) => {
             const wire = installOptions(options);
             return change(scope, (requestId, revision) => runtime.host.packages.install(checked.token, revision, requestId, wire), checked.manifest.id);

package/dist/plugin/resolvers.js

@@ -5,8 +5,72 @@
 import { failure, quiet } from "./runtime.js";
 import { playerOf } from "./player.js";
 import { resolvedStream } from "./stream.js";
+import { windowOf } from "./window.js";
 const isFiles = (options) => "extensions" in options;
+const sameTypes = (a, b) => a.length === b.length && a.every((type, i) => type === b[i]);
+/**
+ * One per plugin: the list comes with the `window.state` read before
+ * activation (`[]` from older players) and is read again when the plugin
+ * first uses it; with `events`, `resolvers.fileTypes` keeps it current.
+ */
+class FileTypesService {
+    #runtime;
+    types;
+    #listeners = new Set();
+    #started = false;
+    constructor(runtime) {
+        this.#runtime = runtime;
+        this.types = Object.freeze([...(windowOf(runtime).fileTypes ?? [])]);
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#runtime.on("resolvers.fileTypes", (data) => {
+            const types = data?.fileTypes;
+            if (Array.isArray(types) && types.every((t) => typeof t === "string"))
+                this.accept(types);
+        });
+        // What changed between the start-up read and the subscription.
+        const window = windowOf(this.#runtime);
+        void window.read().then(() => {
+            if (window.fileTypes)
+                this.accept(window.fileTypes, this.#runtime.can("events"));
+        });
+    }
+    /** `notify`: false without `events`, whose listeners never fire. */
+    accept(types, notify = true) {
+        if (sameTypes(types, this.types))
+            return;
+        this.types = Object.freeze([...types]);
+        if (notify)
+            for (const listener of [...this.#listeners])
+                listener([...types]);
+        this.#runtime.invalidate();
+    }
+    watch(listener) {
+        this.#listeners.add(listener);
+        return { dispose: async () => void this.#listeners.delete(listener) };
+    }
+}
+const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
 export const resolvers = (scope) => ({
+    get fileTypes() {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        return service.types;
+    },
+    onFileTypesChange(listener) {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        const watch = service.watch((types) => scope.run(listener, types));
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    },
     add(options) {
         const runtime = scope.runtime;
         const registration = isFiles(options)

package/dist/plugin/testing.d.ts

@@ -773,6 +773,27 @@ export declare class TestHost implements Transport {
         /** Exact host names it resolves (a web resolver), with `schemes`. */
         hosts?: string[];
     }[];
+    /**
+     * What `plugin.resolvers.fileTypes` reports: the extensions of this
+     * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
+     * each once.
+     */
+    fileTypes(): string[];
+    /**
+     * Push `resolvers.fileTypes` when {@link TestHost.fileTypes} changed:
+     * called after this plugin's resolvers come and go; call it yourself
+     * after changing {@link TestHost.otherResolvers} (another plugin started
+     * or stopped).
+     *
+     * @example
+     * ```ts
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.updateFileTypes();
+     * await host.settle();
+     * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
+     * ```
+     */
+    updateFileTypes(): void;
     /**
      * File opens waiting for this plugin's file resolver (`extensions`), by
      * request id: the path and how it was opened. Opening a matching path
@@ -1095,7 +1116,7 @@ export declare class TestHost implements Transport {
         /** Its version, `null` when unknown. */
         version: string | null;
         /** Where it was loaded from. */
-        origin: "installed" | "development" | "trial";
+        origin: "installed" | "development";
         /** Its run state. */
         state: "starting" | "running" | "disabled" | "failed" | "stopped";
         /** Why it failed (`state: "failed"`). */

package/dist/plugin/testing.js

@@ -773,6 +773,43 @@ export class TestHost {
      * ```
      */
     otherResolvers = [];
+    /**
+     * What `plugin.resolvers.fileTypes` reports: the extensions of this
+     * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
+     * each once.
+     */
+    fileTypes() {
+        const types = new Set();
+        for (const declaration of [
+            ...this.resolvers.values(),
+            ...this.otherResolvers,
+        ])
+            for (const type of declaration.extensions ?? [])
+                types.add(type);
+        return [...types].sort();
+    }
+    #sentTypes = "[]";
+    /**
+     * Push `resolvers.fileTypes` when {@link TestHost.fileTypes} changed:
+     * called after this plugin's resolvers come and go; call it yourself
+     * after changing {@link TestHost.otherResolvers} (another plugin started
+     * or stopped).
+     *
+     * @example
+     * ```ts
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.updateFileTypes();
+     * await host.settle();
+     * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
+     * ```
+     */
+    updateFileTypes() {
+        const types = this.fileTypes();
+        if (JSON.stringify(types) === this.#sentTypes)
+            return;
+        this.#sentTypes = JSON.stringify(types);
+        this.emit("resolvers.fileTypes", { fileTypes: types });
+    }
     /**
      * File opens waiting for this plugin's file resolver (`extensions`), by
      * request id: the path and how it was opened. Opening a matching path
@@ -1361,6 +1398,7 @@ export class TestHost {
             videoArea: { ...this.mainWindow.videoArea },
             pictureInPicture: { ...this.mainWindow.pictureInPicture },
             appearance: this.appearance,
+            fileTypes: this.fileTypes(),
         };
     }
     /**
@@ -2683,8 +2721,6 @@ export class TestHost {
             const entry = this.packages.find((each) => each.id === id);
             if (!entry)
                 throw new HostError("missing", `no plugin ${id}`);
-            if (entry.origin === "trial")
-                throw new HostError("unsupported", "a trial is stopped with its handle");
             this.packageCalls.push({
                 method: "setEnabled",
                 id,
@@ -2944,10 +2980,14 @@ export class TestHost {
             return { jobId: job.jobId, cancel: "requested" };
         },
         "jobs.operation": () => ({ status: "unknown" }),
-        "sourceResolvers.register": (p) => void this.#register(p),
+        "sourceResolvers.register": (p) => {
+            this.#register(p);
+            this.updateFileTypes();
+        },
         "sourceResolvers.unregister": (p) => {
             this.resolvers.delete(String(p.id));
             this.#cancelResolutions();
+            this.updateFileTypes();
         },
         "sourceResolvers.respond": (p) => this.#respond(p),
         "producer.prepare": async () => {

package/dist/plugin/types.d.ts

@@ -73,9 +73,8 @@ export interface Disposable {
  * | `timeout` | A time limit ran out (`openStream` start-up, `tools.run`, `system.*` after 10 s). |
  * | `stream`, `device` | `openStream`: the producer failed / the audio device is not ready. |
  * | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
- * | `cleanup` | {@link PackageTrial.stop} could not confirm cleanup; call it again. |
  * | `limit` | A player-wide limit was reached (for example the number of commands). |
- * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.trial}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
+ * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
  * | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
  * | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
  * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
@@ -195,7 +194,7 @@ export interface Scope extends Disposable {
     readonly media: MediaCapture;
     /** Page-URL to stream-URL resolvers (`source.resolve`). */
     readonly resolvers: Resolvers;
-    /** The installed plugins; validation, trials, installs (`plugins.manage` for changes). */
+    /** The installed plugins; validation, installs (`plugins.manage` for changes). */
     readonly packages: Packages;
     /** On-screen messages over the video (`ui.osd`). */
     readonly osd: Osd;
@@ -320,8 +319,7 @@ export interface Plugin extends Scope {
     readonly id: string;
     /**
      * A writable directory for this plugin's own files (settings, remembered
-     * folders). Kept across restarts, disabling and upgrades; a trial gets a
-     * temporary one. Write files atomically: to a temporary name, then rename.
+     * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
      * Throws `unavailable` when the player provided none.
      *
      * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
@@ -4008,6 +4006,47 @@ export interface Resolvers {
      * error's message.
      */
     add(options: ResolverOptions): Resolver;
+    /**
+     * The extensions some plugin's file resolver handles (SDK 1.5.8, player
+     * 0.4.2): lower case, without the dot, sorted, each once; not who
+     * registered them. Reading needs no capability; `[]` from older players.
+     * Without `events` it is the list from when the plugin first read it.
+     * Use it to accept such files beside the player's own media types, for
+     * example in a playlist's drop or folder scan.
+     *
+     * @example
+     * ```ts
+     * const MEDIA = ["mp4", "mkv", "mp3"];
+     * const accepted = (path: string) => {
+     *   const extension = path.split(".").pop()?.toLowerCase() ?? "";
+     *   return MEDIA.includes(extension) || plugin.resolvers.fileTypes.includes(extension);
+     * };
+     * ```
+     *
+     * @capability None.
+     * @player 0.4.2
+     * @since 1.5.8
+     */
+    readonly fileTypes: readonly string[];
+    /**
+     * {@link Resolvers.fileTypes} changed: a file resolver was added, or its
+     * plugin stopped. Needs `events`; without it the listener never fires.
+     *
+     * @param listener - Receives the new list.
+     * @returns A handle that removes the listener.
+     *
+     * @example
+     * ```ts
+     * plugin.resolvers.onFileTypesChange((types) => {
+     *   void plugin.osd.show(`Also accepted: ${types.join(", ")}`);
+     * });
+     * ```
+     *
+     * @capability `events`
+     * @player 0.4.2
+     * @since 1.5.8
+     */
+    onFileTypesChange(listener: (types: string[]) => void): Disposable;
 }
 /**
  * The manifest of a package, as validated. The display fields and
@@ -4099,11 +4138,6 @@ export interface PackageCandidate {
     readonly manifest: PackageManifest;
     /** The checks the player ran. */
     readonly checks: string[];
-    /**
-     * Load it temporarily alongside the installed plugins. A reserved id
-     * (`vestra.*`) fails with `reserved`.
-     */
-    trial(): Promise<PackageTrial>;
     /**
      * Install it. The same source upgrades the installed plugin (its data
      * stays); another source fails with `conflict` unless `replace` is set;
@@ -4114,17 +4148,6 @@ export interface PackageCandidate {
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
-/** A trial load of a package. Disposing it stops the trial and waits for cleanup. */
-export interface PackageTrial extends Disposable {
-    /** The trial's status as the player reports it. */
-    readonly status: string;
-    /**
-     * Stop and wait until the host confirmed cleanup. Rejects with code
-     * `cleanup` when the host stopped the trial without confirming cleanup;
-     * calling `stop()` again then asks the host again.
-     */
-    stop(): Promise<void>;
-}
 /** The progress of an install, rollback or uninstall. */
 export type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed" | "cancelled" | "failed" | "failedDegraded" | "tooLate";
 /**
@@ -4149,8 +4172,8 @@ export interface PluginInfo {
     id: string;
     /** Version, `null` when unknown. */
     version: string | null;
-    /** From the install library, a `--plugin` development load, or a trial. */
-    origin: "installed" | "development" | "trial";
+    /** From the install library, or a `--plugin` development load. */
+    origin: "installed" | "development";
     /** Run state. */
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     /** Why it failed (`state: "failed"`). */
@@ -4166,7 +4189,7 @@ export interface PluginInfo {
      * replaced. `false` from players before 0.2.0.
      */
     builtin: boolean;
-    /** Where an installed plugin came from; `null` for development loads and trials. */
+    /** Where an installed plugin came from; `null` for development loads. */
     source: PackageSource | null;
     /**
      * Its data directory (`plugin.dataDirectory` of that plugin); `null` when
@@ -4222,6 +4245,10 @@ export interface Packages {
      * Validate a package directory (`plugins.manage`). A package whose id is
      * reserved for the built-in plugins (`vestra` or `vestra.*`) fails with
      * `reserved` (player 0.4.1).
+     *
+     * The player keeps the 32 most recent candidates of all plugins; an
+     * older one's `install` fails with `stale` (validate again). Before
+     * player 0.4.2 the 33rd validation of a run failed with `busy` instead.
      */
     validate(directory: string): Promise<PackageCandidate>;
     /**
@@ -4240,7 +4267,7 @@ export interface Packages {
     /**
      * Stop or start a plugin (`plugins.manage`). An installed plugin stays
      * disabled across launches; a development load only for this run.
-     * `invalid` to disable oneself, `unsupported` for a trial, `missing` unknown.
+     * `invalid` to disable oneself, `missing` unknown.
      * `busy` while it is being installed.
      */
     setEnabled(id: string, enabled: boolean): Promise<void>;
@@ -4248,7 +4275,7 @@ export interface Packages {
      * Remove an installed plugin (`plugins.manage`); `removeData` also deletes
      * its data directory, otherwise reinstalling it from the same source
      * reconnects to its data. Its user bindings stay (as orphans).
-     * `unsupported` for built-ins, development loads and trials, `missing`
+     * `unsupported` for built-ins and development loads, `missing`
      * unknown, `invalid` for oneself.
      */
     uninstall(id: string, options?: {

package/dist/plugin/window.d.ts

@@ -19,6 +19,8 @@ export declare class WindowService {
     start(): void;
     /** The palette, as the `window.state` reply carried it (`plugin.appearance`). */
     appearance: string | undefined;
+    /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
+    fileTypes: string[] | undefined;
     accept(facts: WindowFacts): void;
     read(): Promise<void>;
     watch(listener: (state: WindowState) => void): {

package/dist/plugin/window.js

@@ -52,9 +52,13 @@ export class WindowService {
     }
     /** The palette, as the `window.state` reply carried it (`plugin.appearance`). */
     appearance;
+    /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
+    fileTypes;
     accept(facts) {
         if (facts.appearance)
             this.appearance = facts.appearance;
+        if (Array.isArray(facts.fileTypes))
+            this.fileTypes = [...facts.fileTypes];
         const next = view(facts);
         if (JSON.stringify(next) === JSON.stringify(this.state))
             return;

package/dist/wire.d.ts

@@ -25,12 +25,6 @@ export interface PackageValidation {
     checks: string[];
     trustedExecution: true;
 }
-export interface PackageTrial {
-    trialId: number;
-    activationOwner?: number;
-    status: string;
-    cleanupConfirmed?: boolean;
-}
 export interface InstalledPackage {
     revision: number;
     current: null | {
@@ -102,7 +96,7 @@ export declare class HostError extends Error {
 export interface PackageInfo {
     id: string;
     version: string | null;
-    origin: "installed" | "development" | "trial";
+    origin: "installed" | "development";
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     error: string | null;
     capabilities: string[];
@@ -175,6 +169,8 @@ export interface WindowFacts {
     };
     /** The palette (`plugin.appearance`), with the `window.state` reply; a newer player may name a palette this SDK does not list. */
     appearance?: string;
+    /** The file resolvers' extensions (`plugin.resolvers.fileTypes`; player 0.4.2). */
+    fileTypes?: string[];
 }
 /** One timeline mark as the player merges them (`timeline.marks`). */
 export interface WireMark {
@@ -530,11 +526,6 @@ export declare function createWire(transport: Transport): {
         validate: (directory: string, apiVersion?: string) => Promise<PackageValidation>;
         /** Player 0.2.0: a `.vxp` file. */
         validateArchive: (file: string) => Promise<PackageValidation>;
-        /** `requestId` recovers a lost first reply in this owner session. */
-        trial: (token: string, requestId: string) => Promise<PackageTrial>;
-        trialStateByRequest: (requestId: string) => Promise<PackageTrial>;
-        trialState: (trialId: number) => Promise<PackageTrial>;
-        stopTrial: (trialId: number) => Promise<PackageTrial>;
         installed: (id: string) => Promise<InstalledPackage>;
         /** `source` and `replace` are sent only when given (player 0.2.0). */
         install: (token: string, expectedRevision: number, requestId: string, options?: {

package/dist/wire.js

@@ -258,16 +258,6 @@ export function createWire(transport) {
             validateArchive: (file) => transport.request("packages.validateArchive", {
                 file,
             }),
-            /** `requestId` recovers a lost first reply in this owner session. */
-            trial: (token, requestId) => transport.request("packages.trial", {
-                token,
-                requestId,
-            }),
-            trialStateByRequest: (requestId) => transport.request("packages.trialStateByRequest", {
-                requestId,
-            }),
-            trialState: (trialId) => transport.request("packages.trialState", { trialId }),
-            stopTrial: (trialId) => transport.request("packages.stopTrial", { trialId }),
             installed: (id) => transport.request("packages.installed", { id }),
             /** `source` and `replace` are sent only when given (player 0.2.0). */
             install: (token, expectedRevision, requestId, options = {}) => transport.request("packages.install", {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.7: full reference
+# @vestra-player/sdk 1.5.8: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -124,7 +124,7 @@ A manifest with every field. `id`, `apiVersion`, `entry` and `capabilities` are
 }
 ```
 
-Unknown fields, unknown capabilities and paths that leave the package directory (including through symbolic links) are rejected. The id's characters are ASCII letters, digits, `.`, `-` and `_`; the official plugin repository additionally requires `<GitHub user or organization>.<plugin name>`. The `vestra.` prefix (and the id `vestra`, in any case) is reserved for the plugins built into the player: from player 0.4.1 the player refuses to install or trial such a package (`reserved`). Every other plugin is a third-party plugin, including those hosted in the official repository.
+Unknown fields, unknown capabilities and paths that leave the package directory (including through symbolic links) are rejected. The id's characters are ASCII letters, digits, `.`, `-` and `_`; the official plugin repository additionally requires `<GitHub user or organization>.<plugin name>`. The `vestra.` prefix (and the id `vestra`, in any case) is reserved for the plugins built into the player: from player 0.4.1 the player refuses to install such a package (`reserved`). Every other plugin is a third-party plugin, including those hosted in the official repository.
 
 | Capability                             | Opens                                                                                                   |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
@@ -998,9 +998,8 @@ change).
 | `timeout` | A time limit ran out (`openStream` start-up, `tools.run`, `system.*` after 10 s). |
 | `stream`, `device` | `openStream`: the producer failed / the audio device is not ready. |
 | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
-| `cleanup` | PackageTrial.stop could not confirm cleanup; call it again. |
 | `limit` | A player-wide limit was reached (for example the number of commands). |
-| `reserved` | Packages.validate, PackageCandidate.trial, PackageCandidate.install: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
+| `reserved` | Packages.validate, PackageCandidate.install: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
 | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
 | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
 | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
@@ -1080,7 +1079,7 @@ interface Scope extends Disposable {
   readonly media: MediaCapture;
   /** Page-URL to stream-URL resolvers (`source.resolve`). */
   readonly resolvers: Resolvers;
-  /** The installed plugins; validation, trials, installs (`plugins.manage` for changes). */
+  /** The installed plugins; validation, installs (`plugins.manage` for changes). */
   readonly packages: Packages;
   /** On-screen messages over the video (`ui.osd`). */
   readonly osd: Osd;
@@ -1174,8 +1173,7 @@ interface Plugin extends Scope {
   readonly id: string;
   /**
    * A writable directory for this plugin's own files (settings, remembered
-   * folders). Kept across restarts, disabling and upgrades; a trial gets a
-   * temporary one. Write files atomically: to a temporary name, then rename.
+   * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
    * Throws `unavailable` when the player provided none.
    *
    * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
@@ -3450,6 +3448,20 @@ interface Resolvers {
    * Register a resolver. When anyone opens a matching URL or file the player calls `resolve`; `signal` aborts when the open is cancelled or replaced. One scheme + host pair, and one extension, has one resolver (`conflict` otherwise). A rejected `resolve` fails the open with the error's message.
    */
   add(options: ResolverOptions): Resolver;
+  /**
+   * The extensions some plugin's file resolver handles (SDK 1.5.8, player 0.4.2): lower case, without the dot, sorted, each once; not who registered them. Reading needs no capability; `[]` from older players. Without `events` it is the list from when the plugin first read it. Use it to accept such files beside the player's own media types, for example in a playlist's drop or folder scan.
+   * @capability None.
+   * @player 0.4.2
+   */
+  readonly fileTypes: readonly string[];
+  /**
+   * Resolvers.fileTypes changed: a file resolver was added, or its plugin stopped. Needs `events`; without it the listener never fires.
+   * @param listener - Receives the new list.
+   * @returns A handle that removes the listener.
+   * @capability `events`
+   * @player 0.4.2
+   */
+  onFileTypesChange(listener: (types: string[]) => void): Disposable;
 }
 ```
 
@@ -3555,8 +3567,6 @@ interface PackageCandidate {
   readonly manifest: PackageManifest;
   /** The checks the player ran. */
   readonly checks: string[];
-  /** Load it temporarily alongside the installed plugins. A reserved id (`vestra.*`) fails with `reserved`. */
-  trial(): Promise<PackageTrial>;
   /**
    * Install it. The same source upgrades the installed plugin (its data stays); another source fails with `conflict` unless `replace` is set; a built-in id fails with `unsupported` (built-ins update with the player). A reserved id (`vestra` or `vestra.*`, which every built-in uses) fails with `reserved` (player 0.4.1; already when validated), as only the player installs built-in plugins.
    */
@@ -3564,21 +3574,6 @@ interface PackageCandidate {
 }
 ```
 
-### PackageTrial
-
-A trial load of a package. Disposing it stops the trial and waits for cleanup.
-
-```ts
-interface PackageTrial extends Disposable {
-  /** The trial's status as the player reports it. */
-  readonly status: string;
-  /**
-   * Stop and wait until the host confirmed cleanup. Rejects with code `cleanup` when the host stopped the trial without confirming cleanup; calling `stop()` again then asks the host again.
-   */
-  stop(): Promise<void>;
-}
-```
-
 ### PackageChangeStatus
 
 The progress of an install, rollback or uninstall.
@@ -3617,8 +3612,8 @@ interface PluginInfo {
   id: string;
   /** Version, `null` when unknown. */
   version: string | null;
-  /** From the install library, a `--plugin` development load, or a trial. */
-  origin: "installed" | "development" | "trial";
+  /** From the install library, or a `--plugin` development load. */
+  origin: "installed" | "development";
   /** Run state. */
   state: "starting" | "running" | "disabled" | "failed" | "stopped";
   /** Why it failed (`state: "failed"`). */
@@ -3631,7 +3626,7 @@ interface PluginInfo {
   previousVersion: string | null;
   /** Shipped with the player: it can be disabled, not uninstalled or replaced. `false` from players before 0.2.0. */
   builtin: boolean;
-  /** Where an installed plugin came from; `null` for development loads and trials. */
+  /** Where an installed plugin came from; `null` for development loads. */
   source: PackageSource | null;
   /** Its data directory (`plugin.dataDirectory` of that plugin); `null` when the player has none. The path's layout is not part of the API. */
   dataDirectory: string | null;
@@ -3667,7 +3662,13 @@ need no capability; everything else needs `plugins.manage`.
 ```ts
 interface Packages {
   /**
-   * Validate a package directory (`plugins.manage`). A package whose id is reserved for the built-in plugins (`vestra` or `vestra.*`) fails with `reserved` (player 0.4.1).
+   * Validate a package directory (`plugins.manage`). A package whose id is
+   * reserved for the built-in plugins (`vestra` or `vestra.*`) fails with
+   * `reserved` (player 0.4.1).
+   *
+   * The player keeps the 32 most recent candidates of all plugins; an
+   * older one's `install` fails with `stale` (validate again). Before
+   * player 0.4.2 the 33rd validation of a run failed with `busy` instead.
    */
   validate(directory: string): Promise<PackageCandidate>;
   /**
@@ -3681,11 +3682,11 @@ interface Packages {
   /** The new list after any start, stop, failure, install or uninstall. No capability. */
   onChange(listener: (plugins: PluginInfo[]) => void): Disposable;
   /**
-   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `unsupported` for a trial, `missing` unknown. `busy` while it is being installed.
+   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `missing` unknown. `busy` while it is being installed.
    */
   setEnabled(id: string, enabled: boolean): Promise<void>;
   /**
-   * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins, development loads and trials, `missing` unknown, `invalid` for oneself.
+   * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins and development loads, `missing` unknown, `invalid` for oneself.
    */
   uninstall(id: string, options?: {
     removeData?: boolean;
@@ -4721,6 +4722,12 @@ class TestHost implements Transport {
     /** Exact host names it resolves (a web resolver), with `schemes`. */
     hosts?: string[];
   }[];
+  /** What `plugin.resolvers.fileTypes` reports: the extensions of this plugin's file resolvers and of TestHost.otherResolvers, sorted, each once. */
+  fileTypes(): string[];
+  /**
+   * Push `resolvers.fileTypes` when TestHost.fileTypes changed: called after this plugin's resolvers come and go; call it yourself after changing TestHost.otherResolvers (another plugin started or stopped).
+   */
+  updateFileTypes(): void;
   /**
    * File opens waiting for this plugin's file resolver (`extensions`), by request id: the path and how it was opened. Opening a matching path (`player.open`, TestHost.openElsewhere) sends `source.resolveRequest`; the answer selects the stream, fails the open or, once the source changed, is `stale`. Any later source change cancels it (`source.resolveCancel`). Web resolvers are not simulated: emit `source.resolveRequest` yourself.
    */
@@ -4905,7 +4912,7 @@ class TestHost implements Transport {
     /** Its version, `null` when unknown. */
     version: string | null;
     /** Where it was loaded from. */
-    origin: "installed" | "development" | "trial";
+    origin: "installed" | "development";
     /** Its run state. */
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     /** Why it failed (`state: "failed"`). */
@@ -5059,7 +5066,7 @@ own sensible display cap well below `perPlugin`.
 
 ```ts
 const COMMAND_LIMITS: {
-  /** Commands one plugin instance may have at the same time (160). A trial package is its own instance. */
+  /** Commands one plugin instance may have at the same time (160). */
   readonly perPlugin: 160;
   /** Commands of every plugin plus the player's own, together (1024). */
   readonly total: 1024;

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.7: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
+> @vestra-player/sdk 1.5.8: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
 
 **How plugins run**
 
@@ -136,7 +136,7 @@ test("shows the position", async () => {
 - `aborted`: An `AbortSignal` fired
 - `timeout`: A time limit ran out
 - `limit`: A player-wide limit was reached
-- `reserved`: Packages.validate, PackageCandidate.trial, PackageCandidate.install: the id is `vestra` or starts with `vestra.`, which only the player's built-in plugins use
+- `reserved`: Packages.validate, PackageCandidate.install: the id is `vestra` or starts with `vestra.`, which only the player's built-in plugins use
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
 - `ui-prepare`: The player could not prepare a mounted panel or a settings page
 - `ui`: The player could not apply a property to a tool window or a settings page, or could not build the Options window
@@ -150,54 +150,54 @@ test("shows the position", async () => {
 - [Concept: Windows, panels, settings pages, dialogs and the OSD](https://vestrasys.github.io/vestra-player-sdk/documents/Windows__panels__settings_pages__dialogs_and_the_OSD.html): L281–626
 - [How-to: Keep a slider responsive while dragging](https://vestrasys.github.io/vestra-player-sdk/documents/Keep_a_slider_responsive_while_dragging.html): L627–801
 - [How-to: Remember a window's state between runs](https://vestrasys.github.io/vestra-player-sdk/documents/Remember_a_window_s_state_between_runs.html): L802–931
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4172
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4173–5113
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4173
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4174–5120
 
 ## API
 
 Where each module of `plugin` is declared:
 
-- Plugin L1152, Scope L1023, PluginError L974, Disposable L947
-- plugin.commands: Commands L1349
-- plugin.windows: Windows L1554
-- plugin.panels: Panels L2005
-- plugin.dialogs: Dialogs L2287
-- plugin.player: Player L2726
-- plugin.video: VideoFilter L2975, VideoView L3038, RenderOptions L3080
-- plugin.audio: AudioFilter L2999
-- plugin.subtitles: Subtitles L3178
-- plugin.media: MediaCapture L3336
-- plugin.resolvers: Resolvers L3441
-- plugin.packages: Packages L3662
-- plugin.osd: Osd L2912
-- plugin.host: Host L2875
-- plugin.clipboard: Clipboard L3769
-- plugin.power: Power L3789
-- plugin.tools: Tools L3822
-- plugin.storage: Storage L3865
-- plugin.system: System L3888
-- plugin.secrets: Secrets L3906
-- plugin.window: MainWindow L2128
-- plugin.app: App L2209
-- plugin.bindings: Bindings L3739
-- plugin.ui: Ui L1441
-- plugin.timeline: Timeline L2085
-- plugin.drops: Drops L1851
-- plugin.appearance: Appearance L1880
-- plugin.settings: Settings L1938
+- Plugin L1151, Scope L1022, PluginError L974, Disposable L947
+- plugin.commands: Commands L1347
+- plugin.windows: Windows L1552
+- plugin.panels: Panels L2003
+- plugin.dialogs: Dialogs L2285
+- plugin.player: Player L2724
+- plugin.video: VideoFilter L2973, VideoView L3036, RenderOptions L3078
+- plugin.audio: AudioFilter L2997
+- plugin.subtitles: Subtitles L3176
+- plugin.media: MediaCapture L3334
+- plugin.resolvers: Resolvers L3439
+- plugin.packages: Packages L3657
+- plugin.osd: Osd L2910
+- plugin.host: Host L2873
+- plugin.clipboard: Clipboard L3770
+- plugin.power: Power L3790
+- plugin.tools: Tools L3823
+- plugin.storage: Storage L3866
+- plugin.system: System L3889
+- plugin.secrets: Secrets L3907
+- plugin.window: MainWindow L2126
+- plugin.app: App L2207
+- plugin.bindings: Bindings L3740
+- plugin.ui: Ui L1439
+- plugin.timeline: Timeline L2083
+- plugin.drops: Drops L1849
+- plugin.appearance: Appearance L1878
+- plugin.settings: Settings L1936
 
 ## Examples
 
 Complete plugins with tests, in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples) and in llms-full.txt:
 
-- hello: The README Quick start: one menu command and an on-screen message. L5527–5616
-- blur: A tool window with one slider that blurs the playing video. L5617–5878
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L5879–6211
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6212–6396
-- panel-menu: A sidebar panel with its own right-click menu. L6397–6602
-- menus: Radio menu items, separator groups and a menu item whose title changes. L6603–6762
-- theme-widgets: A tool window drawn with the player's theme and widgets. L6763–6926
-- markdown: A window that shows a Markdown document. L6927–7120
+- hello: The README Quick start: one menu command and an on-screen message. L5534–5623
+- blur: A tool window with one slider that blurs the playing video. L5624–5885
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L5886–6218
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6219–6403
+- panel-menu: A sidebar panel with its own right-click menu. L6404–6609
+- menus: Radio menu items, separator groups and a menu item whose title changes. L6610–6769
+- theme-widgets: A tool window drawn with the player's theme and widgets. L6770–6933
+- markdown: A window that shows a Markdown document. L6934–7127
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.7",
+  "version": "1.5.8",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {