@vestra-player/sdk 1.5.24 → 1.5.25

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.5.25
+
+**Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: `plugin.storage.json` and every other API do what they did. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.5.
+
+- **`plugin.storage.session`** (`SessionStorage`, player 0.5.5; user ruling of 2026-10-27, after Chrome's `chrome.storage.session`): `get(key)`, `set(key, value)`, `delete(key)` and `keys()` of JSON values that live as long as the **player**, not the plugin's process. They survive every restart of the plugin within one player session (a reload, also of a development load, an upgrade, a crash, a failed start) and are cleared when the user disables or uninstalls the plugin, and when the player quits. Per plugin, no capability. Keys are 1–1024 bytes of well-formed text; a plugin's keys, values (as compact JSON) and 128 bytes per key are at most 1 MiB together, and a `set` beyond fails with `limit` and changes nothing. One value must also fit in one 1 MiB message. A value `JSON.stringify` cannot write, or one with a lone surrogate in a string, fails with `invalid`; the order of an object's properties is not kept; `get` returns `undefined` for a missing key. Each `set` is one acknowledged request, without debounce. Players before 0.5.5 reject the calls with `unsupported`, so set `"minPlayerVersion": "0.5.5"`.
+- **`SESSION_STORAGE_LIMITS`** (`@vestra-player/sdk/testing` and `/runtime`): `keyBytes` 1024, `bytes` 1 MiB, `entryBytes` 128.
+- **`TestHost.sessionStorage`** (the player's store for the plugin, with the player's key rule and quota, objects stored with sorted properties as the player returns them) and **`startPlugin(..., { sessionStorage })`** to start with the values an earlier run left, to test a restart within one player session. `TestHost` now refuses any request over the 1 MiB message limit with `limit`, as the plugin runner does.
+- Docs: *How a plugin runs* gains *Restarts: activate can run more than once*: when the player restarts a plugin's process, and "keep state that must survive a restart in session storage (or persistent storage)", with a table of what survives what. *Test a plugin* (testing a restart with session values), *Reference: limits* (`SESSION_STORAGE_LIMITS`). `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.24
 
 **Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: `when: "interlaced"` and `when: "all"` do what they did. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.4.

package/dist/player-runtime.d.ts

@@ -15,7 +15,7 @@ export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./ca
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
-export { SECRET_LIMITS } from "./plugin/services.ts";
+export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";
 export { THEME_PALETTES } from "./palettes.ts";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";

package/dist/player-runtime.js

@@ -13,7 +13,7 @@ export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./ca
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
-export { SECRET_LIMITS } from "./plugin/services.js";
+export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";
 export { THEME_PALETTES } from "./palettes.js";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";

package/dist/plugin/services.d.ts

@@ -4,6 +4,41 @@ export declare const clipboard: (scope: ScopeImpl) => Clipboard;
 export declare const host: (scope: ScopeImpl) => Host;
 export declare const power: (scope: ScopeImpl) => Power;
 export declare function tools(scope: ScopeImpl): Tools;
+/**
+ * The player's limits on {@link SessionStorage}. A key outside them fails
+ * with code `invalid`; a `set` that would make the plugin's entries larger
+ * than `bytes` fails with `limit` and changes nothing. A single `set` must
+ * also fit in one message to the player
+ * ({@link "@vestra-player/sdk/testing"!MESSAGE_LIMIT | MESSAGE_LIMIT}, 1 MiB
+ * with the key and the request around the value). The player's tests check
+ * that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const key = "https://example.com/a.mkv";
+ * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * ```
+ *
+ * @since 1.5.25
+ */
+export declare const SESSION_STORAGE_LIMITS: Readonly<{
+    /** UTF-8 bytes of a key (1024, at least 1; no NUL character). */
+    readonly keyBytes: 1024;
+    /**
+     * Bytes one plugin may hold at the same time: for every key, its UTF-8
+     * bytes, its value written as compact JSON (`JSON.stringify(value)`) and
+     * `entryBytes`.
+     */
+    readonly bytes: number;
+    /**
+     * What each key costs on top of its text and value (128): the player's
+     * own bookkeeping, so that many tiny entries stay within `bytes` of memory.
+     */
+    readonly entryBytes: 128;
+}>;
 export declare const storage: (scope: ScopeImpl) => Storage;
 export declare function system(scope: ScopeImpl): System;
 /**

package/dist/plugin/services.js

@@ -1,7 +1,7 @@
 /**
  * Shared services: the clipboard, sleep prevention, showing and opening files
- * and links, and secrets go to the host; external tools and settings files
- * run in this plugin's own process.
+ * and links, secrets and session storage go to the host; external tools and
+ * settings files run in this plugin's own process.
  */
 import { existsSync, readFileSync, renameSync } from "node:fs";
 import { mkdir, open, rename, rm, stat } from "node:fs/promises";
@@ -238,6 +238,90 @@ class Store {
         this.#scope.forget(this);
     }
 }
+/**
+ * The player's limits on {@link SessionStorage}. A key outside them fails
+ * with code `invalid`; a `set` that would make the plugin's entries larger
+ * than `bytes` fails with `limit` and changes nothing. A single `set` must
+ * also fit in one message to the player
+ * ({@link "@vestra-player/sdk/testing"!MESSAGE_LIMIT | MESSAGE_LIMIT}, 1 MiB
+ * with the key and the request around the value). The player's tests check
+ * that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const key = "https://example.com/a.mkv";
+ * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * ```
+ *
+ * @since 1.5.25
+ */
+export const SESSION_STORAGE_LIMITS = Object.freeze({
+    /** UTF-8 bytes of a key (1024, at least 1; no NUL character). */
+    keyBytes: 1024,
+    /**
+     * Bytes one plugin may hold at the same time: for every key, its UTF-8
+     * bytes, its value written as compact JSON (`JSON.stringify(value)`) and
+     * `entryBytes`.
+     */
+    bytes: 1024 * 1024,
+    /**
+     * What each key costs on top of its text and value (128): the player's
+     * own bookkeeping, so that many tiny entries stay within `bytes` of memory.
+     */
+    entryBytes: 128,
+});
+/** A lone surrogate: the player's JSON parser refuses the whole message. */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+/** Whether a parsed JSON value has a string or a property name with a lone surrogate. */
+function hasLoneSurrogate(value) {
+    if (typeof value === "string")
+        return LONE_SURROGATE.test(value);
+    if (Array.isArray(value))
+        return value.some(hasLoneSurrogate);
+    if (value && typeof value === "object")
+        return Object.entries(value).some(([key, item]) => LONE_SURROGATE.test(key) || hasLoneSurrogate(item));
+    return false;
+}
+function sessionStorage(scope) {
+    const keyed = (key) => {
+        if (typeof key !== "string" ||
+            !key ||
+            key.includes("\0") ||
+            LONE_SURROGATE.test(key) ||
+            Buffer.byteLength(key) > SESSION_STORAGE_LIMITS.keyBytes)
+            throw failure("invalid", `session storage keys are 1–${SESSION_STORAGE_LIMITS.keyBytes} bytes of well-formed text without NUL`);
+        return key;
+    };
+    const host = () => scope.runtime.host.storageSession;
+    return {
+        async get(key) {
+            const found = await host().get(keyed(key));
+            return "value" in found ? found.value : undefined;
+        },
+        async set(key, value) {
+            const name = keyed(key);
+            let text;
+            try {
+                text = JSON.stringify(value);
+            }
+            catch {
+                text = undefined; // a cycle or a BigInt
+            }
+            if (text === undefined)
+                throw failure("invalid", "session storage values must be JSON; delete() removes one");
+            // What the player stores, and what `get` will return.
+            const json = JSON.parse(text);
+            if (hasLoneSurrogate(json))
+                throw failure("invalid", "session storage values must be well-formed text: a string has a lone surrogate");
+            await host().set(name, json);
+        },
+        delete: async (key) => host().delete(keyed(key)),
+        keys: async () => host().keys(),
+    };
+}
 export const storage = (scope) => ({
     json(name, options) {
         if (typeof name !== "string" || !NAME.test(name))
@@ -247,6 +331,7 @@ export const storage = (scope) => ({
             throw failure("invalid", "debounceMs must be a non-negative number");
         return new Store(scope, scope.dataDirectory, name, options);
     },
+    session: sessionStorage(scope),
 });
 export function system(scope) {
     const exists = async (path) => {

package/dist/plugin/testing.d.ts

@@ -7,7 +7,7 @@ import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
 import type { CapabilityInfo } from "../capabilities.ts";
 import { OSD_LIMITS } from "./osd.ts";
-import { SECRET_LIMITS } from "./services.ts";
+import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
 import { THEME_PALETTES } from "../palettes.ts";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
@@ -34,6 +34,8 @@ export { MESSAGE_LIMIT };
 export { OSD_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
+/** The player's limits on `plugin.storage.session`. */
+export { SESSION_STORAGE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -1072,6 +1074,18 @@ export declare class TestHost implements Transport {
      * new name fails `limit` once 256 names are stored.
      */
     readonly secrets: Map<string, string>;
+    /**
+     * `plugin.storage.session`: key → value, as the player keeps them. Preset
+     * entries to simulate values an earlier run of the plugin stored in the
+     * same player session, or pass `startPlugin(..., { sessionStorage })`.
+     * Like the player, a key is 1–1024 bytes, a `set` that would make the
+     * entries larger than 1 MiB (keys, values as compact JSON and
+     * `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an
+     * object's properties are stored sorted, as the player hands them back.
+     *
+     * @since 1.5.25
+     */
+    readonly sessionStorage: Map<string, Json>;
     /** What `plugin.app.system()` reports. */
     systemInfo: WireSystemInfo;
     /**
@@ -1594,6 +1608,15 @@ export declare function startPlugin(activate: (plugin: Plugin) => unknown, optio
     host?: TestHost;
     /** Use an existing directory as `plugin.dataDirectory` (to test a restart). */
     dataDirectory?: string;
+    /**
+     * Start with these `plugin.storage.session` values (to test a restart
+     * within one player session): pass the previous run's
+     * `host.sessionStorage`. They are copied into the new host's
+     * {@link TestHost.sessionStorage}.
+     *
+     * @since 1.5.25
+     */
+    sessionStorage?: ReadonlyMap<string, Json>;
     /**
      * The interface language to play ({@link TestHost.locale}): the plugin's
      * `locales/<locale>.po` (or `.json`) in `directory` is loaded and its

package/dist/plugin/testing.js

@@ -69,7 +69,7 @@ import { localSocketPath } from "./local.js";
 import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
-import { SECRET_LIMITS } from "./services.js";
+import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
 import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
@@ -93,6 +93,8 @@ export { MESSAGE_LIMIT };
 export { OSD_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
+/** The player's limits on `plugin.storage.session`. */
+export { SESSION_STORAGE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -131,6 +133,34 @@ export { LIST_SEPARATORS };
  * ```
  */
 export { LOCALES };
+/** A `plugin.storage.session` key, checked as the player does. */
+function sessionKey(key) {
+    if (typeof key !== "string" ||
+        !key ||
+        key.includes("\0") ||
+        Buffer.byteLength(key) > SESSION_STORAGE_LIMITS.keyBytes)
+        throw new HostError("invalid", "session storage keys are 1–1024 bytes of text without NUL");
+    return key;
+}
+/** Code point (UTF-8 byte) order, as the player sorts session keys. */
+const byCodePoint = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+/**
+ * A JSON value as the player hands it back: the player does not keep the
+ * order of object properties, it sorts them.
+ */
+function sortedJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortedJson);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.keys(value)
+            .sort(byCodePoint)
+            .map((key) => [key, sortedJson(value[key])]));
+    return value;
+}
+/** What one session entry counts towards the player's quota. */
+const sessionCost = (key, value) => Buffer.byteLength(key) +
+    Buffer.byteLength(JSON.stringify(value)) +
+    SESSION_STORAGE_LIMITS.entryBytes;
 const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 function initialSource() {
@@ -1156,6 +1186,18 @@ export class TestHost {
      * new name fails `limit` once 256 names are stored.
      */
     secrets = new Map();
+    /**
+     * `plugin.storage.session`: key → value, as the player keeps them. Preset
+     * entries to simulate values an earlier run of the plugin stored in the
+     * same player session, or pass `startPlugin(..., { sessionStorage })`.
+     * Like the player, a key is 1–1024 bytes, a `set` that would make the
+     * entries larger than 1 MiB (keys, values as compact JSON and
+     * `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an
+     * object's properties are stored sorted, as the player hands them back.
+     *
+     * @since 1.5.25
+     */
+    sessionStorage = new Map();
     /** What `plugin.app.system()` reports. */
     systemInfo = {
         os: "macos",
@@ -1622,6 +1664,11 @@ export class TestHost {
      */
     async request(method, params = {}) {
         const record = (params ?? {});
+        // The plugin runner refuses a request over the message limit before
+        // sending it (runtime/runner.ts): the player never sees it.
+        const line = JSON.stringify({ id: this.calls.length + 1, method, params });
+        if (Buffer.byteLength(line, "utf8") + 1 > MESSAGE_LIMIT)
+            throw new HostError("limit", `${method}: request exceeds the player's 1 MiB message limit`);
         this.calls.push({ method, params: record });
         this.#inFlight++;
         try {
@@ -2709,6 +2756,27 @@ export class TestHost {
             this.secrets.set(name, String(p.value));
         },
         "secrets.delete": (p) => void this.secrets.delete(String(p.name)),
+        // As the player (host/src/session_storage.rs).
+        "storage.session.get": (p) => {
+            const key = sessionKey(p.key);
+            return this.sessionStorage.has(key)
+                ? { value: structuredClone(this.sessionStorage.get(key)) }
+                : {};
+        },
+        "storage.session.set": (p) => {
+            const key = sessionKey(p.key);
+            if (!("value" in p))
+                throw new HostError("invalid", "set needs a JSON value");
+            let total = sessionCost(key, p.value);
+            for (const [other, value] of this.sessionStorage)
+                if (other !== key)
+                    total += sessionCost(other, value);
+            if (total > SESSION_STORAGE_LIMITS.bytes)
+                throw new HostError("limit", `session storage holds at most ${SESSION_STORAGE_LIMITS.bytes} bytes per plugin (keys, JSON values and ${SESSION_STORAGE_LIMITS.entryBytes} per key); this value would make ${total}`);
+            this.sessionStorage.set(key, sortedJson(p.value));
+        },
+        "storage.session.delete": (p) => void this.sessionStorage.delete(sessionKey(p.key)),
+        "storage.session.keys": () => [...this.sessionStorage.keys()].sort(byCodePoint),
         "app.system": () => structuredClone(this.systemInfo),
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
@@ -3741,6 +3809,8 @@ export async function startPlugin(activate, options = {}) {
     host.manifestId = manifest.id;
     host.loadCatalog(directory);
     const data = options.dataDirectory ?? host.dataDirectory;
+    for (const [key, value] of options.sessionStorage ?? [])
+        host.sessionStorage.set(key, sortedJson(value));
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);

package/dist/plugin/types.d.ts

@@ -5232,6 +5232,83 @@ export interface Storage {
         validate?: (value: unknown) => value is T;
         debounceMs?: number;
     }): JsonStore<T>;
+    /**
+     * Values the player keeps in its memory for this plugin until the player
+     * quits: they survive a restart of the plugin's process (reload, upgrade,
+     * crash, failed start) but not the player. See {@link SessionStorage}.
+     *
+     * @since 1.5.25
+     */
+    readonly session: SessionStorage;
+}
+/**
+ * `plugin.storage.session`: JSON values that live as long as the **player**,
+ * not as long as the plugin's process (like `chrome.storage.session`). No
+ * capability; needs player 0.5.5 (older players reject the calls with
+ * `unsupported`).
+ *
+ * `activate` can run more than once in one player session: the player stops
+ * and starts a plugin's process again when the plugin is reloaded (also a
+ * development load with `--plugin`) or upgraded, and after a crash or a
+ * failed start. A later player may also restart plugins that share a
+ * process, or stop an idle plugin and start it on its next use. Variables do
+ * not survive that; keep state that must survive a restart here (or in
+ * {@link Storage.json | storage.json} when it must also survive the player
+ * quitting).
+ *
+ * | | Values |
+ * | --- | --- |
+ * | The plugin's process restarts: reload, upgrade, crash | kept |
+ * | The plugin failed to start or failed, and starts again | kept |
+ * | The user disables the plugin, or uninstalls it | cleared |
+ * | The player quits | cleared |
+ *
+ * - **Per plugin.** A plugin sees only its own keys. Like
+ *   {@link Plugin.dataDirectory | dataDirectory}, the values belong to the
+ *   installation: a development load (`--plugin`) has its own.
+ * - **JSON.** `set` stores what `JSON.stringify(value)` writes, and `get`
+ *   returns that, parsed: `undefined` object properties are dropped, a `Date`
+ *   comes back as a string, `NaN` as `null`. **The order of an object's
+ *   properties is not kept**: they may come back in another order. A value
+ *   `JSON.stringify` cannot write (`undefined`, a function, a cycle, a
+ *   `BigInt`) or a string with a lone surrogate (`"\uD800"`) fails with
+ *   `invalid`. The value is not checked when it comes back: after an upgrade
+ *   an older version's value may be read, so check its shape when it matters.
+ * - **Bounded.** Keys are 1–1024 bytes of text. A plugin holds at most 1 MiB,
+ *   counting every key, its value as compact JSON and 128 bytes per key
+ *   ({@link "@vestra-player/sdk/testing"!SESSION_STORAGE_LIMITS | SESSION_STORAGE_LIMITS}); a
+ *   `set` beyond it fails with `limit` and changes nothing. One `set` is
+ *   also one message to the player, at most 1 MiB with its key, so a single
+ *   value is a little smaller than that; a larger one fails with `limit`.
+ *   Split large state over several keys.
+ * - **Each call is one request.** A `set` is kept once its promise
+ *   resolves, so a crash right after loses nothing; there is no debounce.
+ *   Calls answer in order.
+ *
+ * @example
+ * ```ts
+ * // A queue the plugin is working through: after a reload or a crash it
+ * // goes on where it stopped, after the player quits it starts afresh.
+ * const pending = (await plugin.storage.session.get<string[]>("queue")) ?? [];
+ * pending.push("https://example.com/a.mkv");
+ * await plugin.storage.session.set("queue", pending);
+ * ```
+ *
+ * @since 1.5.25
+ */
+export interface SessionStorage {
+    /** The value stored under `key`, or `undefined` when there is none. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store or replace `value` under `key`. `invalid` for a bad key or a value
+     * that is not JSON, `limit` when the plugin's values would be over 1 MiB
+     * or the request over the 1 MiB message limit.
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /** Remove a key; removing a missing one is fine. */
+    delete(key: string): Promise<void>;
+    /** The keys stored, in code point order. */
+    keys(): Promise<string[]>;
 }
 /**
  * `plugin.system`: files and links, executed by the player. No capability.

package/dist/wire.d.ts

@@ -488,6 +488,18 @@ export declare function createWire(transport: Transport): {
         set: (name: string, value: string) => Promise<void>;
         delete: (name: string) => Promise<void>;
     };
+    /**
+     * JSON values the player keeps per plugin until it quits (SDK 1.5.25,
+     * player 0.5.5). `get` answers `{}` for a missing key.
+     */
+    storageSession: {
+        get: (key: string) => Promise<{
+            value?: Json;
+        }>;
+        set: (key: string, value: Json) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        keys: () => Promise<string[]>;
+    };
     app: {
         system: () => Promise<WireSystemInfo>;
     };

package/dist/wire.js

@@ -182,6 +182,16 @@ export function createWire(transport) {
             set: (name, value) => transport.request("secrets.set", { name, value }),
             delete: (name) => transport.request("secrets.delete", { name }),
         },
+        /**
+         * JSON values the player keeps per plugin until it quits (SDK 1.5.25,
+         * player 0.5.5). `get` answers `{}` for a missing key.
+         */
+        storageSession: {
+            get: (key) => transport.request("storage.session.get", { key }),
+            set: (key, value) => transport.request("storage.session.set", { key, value }),
+            delete: (key) => transport.request("storage.session.delete", { key }),
+            keys: () => transport.request("storage.session.keys"),
+        },
         app: {
             system: () => transport.request("app.system"),
         },

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.24: full reference
+# @vestra-player/sdk 1.5.25: 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.
 
@@ -221,7 +221,7 @@ It assumes you have written a first plugin (Getting started). For each type's me
 #### The plugin process
 
 - **One Node.js process per plugin.** The player starts each plugin in a Node.js 26 process of its own (the installed player ships that Node.js). The plugin can use the Node standard library, the file system, the network and npm packages. A crash or a busy loop in one plugin does not stop the player or other plugins.
-- **No web storage.** The player starts Node with `--no-experimental-webstorage`, so `localStorage` and `sessionStorage` do not exist. Keep settings with plugin.storage or in your own files in the data directory.
+- **No web storage.** The player starts Node with `--no-experimental-webstorage`, so `localStorage` and `sessionStorage` do not exist. Keep settings with plugin.storage or in your own files in the data directory, and state that must outlive a restart of the plugin's process, but not the player, in plugin.storage.session (Restarts).
 - **Trusted code.** Manifest capabilities are a contract the player checks on every call (a missing one fails with `code: "capability"`), not a sandbox: the process has the user's file and network access. The full list of capabilities and the API each one opens is in Reference: capabilities.
 - **One API on every system.** The same plugin runs on macOS and Windows. Something a system cannot do fails with `unsupported`; the differences are collected in Reference: platforms.
 - **Types only.** The plugin imports `@vestra-player/sdk` with `import type`. The `plugin` object it receives is built by the player's copy of the SDK, so a built plugin contains only its own code and keeps working with the SDK version the player ships.
@@ -314,6 +314,27 @@ The player stops a plugin when the user disables or uninstalls it, when it is re
 
 So `onDispose` cleanup must be quick and must not rely on the player. Media the plugin opened with player.open **keeps playing** after it stops.
 
+#### Restarts: activate can run more than once
+
+A plugin's process does not live as long as the player. Within one player session the player stops a plugin and starts it again, and `activate` runs again in a new process, when:
+
+- the plugin is **reloaded** (from the plugin manager, or a development load with `--plugin`) or **upgraded**;
+- it **crashed**, or failed to start, and is started again.
+
+A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use. Write the plugin for those too.
+
+Everything in the process is gone after such a restart: variables, timers, caches, open sockets. The menus, windows and panels come back because `activate` creates them again. **Keep state that must survive a restart in session storage (or persistent storage):**
+
+| Where | Survives a restart of the plugin | Survives the player quitting | Cleared when |
+| --- | --- | --- | --- |
+| Variables in the process | no | no | the process stops |
+| plugin.storage.session (player 0.5.5) | yes | no | the user disables or uninstalls the plugin; the player quits |
+| plugin.storage.json, files in the data directory | yes | yes | uninstalling with `removeData` |
+
+Session storage is for state that belongs to this run of the player: a queue the plugin is working through, the item a panel was showing, a token that expires anyway. Settings and history the user expects to find tomorrow go in `storage.json`. Session storage keeps JSON values in the player's memory, at most 1 MiB per plugin (one value a little less, since it travels in one 1 MiB message; split large state over several keys), and does not keep the order of an object's properties. Each `set` is kept as soon as its promise resolves, so a crash right after loses nothing. Disabling a plugin is the user switching it off, so its session values go; a reload, a crash or a failed start keeps them.
+
+Write `activate` so that running it twice in one session is normal: read what you kept, then build the interface from it.
+
 #### The data directory
 
 plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
@@ -1660,7 +1681,7 @@ Every test follows the same five steps:
 4. **Assert** on what the host recorded.
 5. **Stop** with `await stop()`: the plugin is disposed as when the player stops it (scopes released, stores flushed) and the host's temporary files are removed. Each test creates its own host.
 
-`startPlugin` also returns `plugin`, the object `activate` received, to call the API directly (`plugin.player.state`). Its options: `host` (a host you prepared before activation, as above), `dataDirectory` (an existing folder as `plugin.dataDirectory`, to test a restart), `locale` (play another interface language, see Translate a plugin), and `id` with `capabilities` to start without a `manifest.json`.
+`startPlugin` also returns `plugin`, the object `activate` received, to call the API directly (`plugin.player.state`). Its options: `host` (a host you prepared before activation, as above), `dataDirectory` (an existing folder as `plugin.dataDirectory`, to test a restart), `sessionStorage` (the values of `plugin.storage.session` an earlier run left, to test a restart within one player session), `locale` (play another interface language, see Translate a plugin), and `id` with `capabilities` to start without a `manifest.json`.
 
 #### Act like the user
 
@@ -1775,6 +1796,29 @@ The host checks what the player checks: the command limits, the property value l
 
 Copy `host.dataDirectory` after the first run and pass it as `dataDirectory` to the second, to check what the plugin stored and restores; the example is on startPlugin, and Remember a window's state between runs is a plugin that needs it.
 
+A restart within one player session (a reload, an upgrade, a crash) keeps plugin.storage.session too. Pass the first run's `host.sessionStorage` as `sessionStorage` to the second run; leave it out to test a fresh player session, where those values are gone:
+
+```ts
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { startPlugin } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("goes on with the queue after a restart", async () => {
+  const first = await startPlugin(activate);
+  await first.plugin.storage.session.set("queue", ["a.mkv", "b.mkv"]);
+  const kept = first.host.sessionStorage;
+  await first.stop();
+
+  const second = await startPlugin(activate, { sessionStorage: kept });
+  assert.deepEqual(await second.plugin.storage.session.get("queue"), [
+    "a.mkv",
+    "b.mkv",
+  ]);
+  await second.stop();
+});
+```
+
 Every member of `TestHost` is in the @vestra-player/sdk/testing reference.
 
 ## How-to: Publish a plugin
@@ -2186,6 +2230,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.1 | ImageRef, ImageOptions.maxSide, PropValue, Ui.image, Ui.remoteImage, SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps, Player.setStepSeek, Host.run, Packages.reload |
 | 0.5.2 | HostAction |
 | 0.5.3 | Scrub.seek |
+| 0.5.5 | SessionStorage |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2307,6 +2352,16 @@ plugin.secrets. A name or value out of its rule fails with code `invalid`; a new
 | `SECRET_LIMITS.valueBytes` | 1024 (1 KiB) | UTF-8 bytes of a value. |
 | `SECRET_LIMITS.names` | 256 | Different names one plugin may have stored at the same time. |
 
+#### Session storage
+
+plugin.storage.session (player 0.5.5). A key out of its rule, or a value that is not JSON (or has a string with a lone surrogate), fails with code `invalid`; a `set` that would take the plugin over `bytes` fails with `limit` and changes nothing. Each key counts its UTF-8 bytes, its value as compact JSON and `entryBytes`. One `set` is also one message, so a single value must fit in `MESSAGE_LIMIT` with its key and the request around it.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `SESSION_STORAGE_LIMITS.keyBytes` | 1024 (1 KiB) | UTF-8 bytes of a key. |
+| `SESSION_STORAGE_LIMITS.bytes` | 1048576 (1 MiB) | Bytes one plugin may hold at the same time: for every key, its UTF-8 bytes, its value written as compact JSON (`JSON.stringify(value)`) and `entryBytes`. |
+| `SESSION_STORAGE_LIMITS.entryBytes` | 128 | What each key costs on top of its text and value (128): the player's own bookkeeping, so that many tiny entries stay within `bytes` of memory. |
+
 #### Messages
 
 Every request a plugin sends travels as one protocol line. The plugin's side refuses a longer one with code `limit` before sending it; property values meet their own limits first.
@@ -6427,6 +6482,70 @@ interface Storage {
     validate?: (value: unknown) => value is T;
     debounceMs?: number;
   }): JsonStore<T>;
+  /**
+   * Values the player keeps in its memory for this plugin until the player quits: they survive a restart of the plugin's process (reload, upgrade, crash, failed start) but not the player. See SessionStorage.
+   */
+  readonly session: SessionStorage;
+}
+```
+
+### SessionStorage
+
+`plugin.storage.session`: JSON values that live as long as the **player**,
+not as long as the plugin's process (like `chrome.storage.session`). No
+capability; needs player 0.5.5 (older players reject the calls with
+`unsupported`).
+
+`activate` can run more than once in one player session: the player stops
+and starts a plugin's process again when the plugin is reloaded (also a
+development load with `--plugin`) or upgraded, and after a crash or a
+failed start. A later player may also restart plugins that share a
+process, or stop an idle plugin and start it on its next use. Variables do
+not survive that; keep state that must survive a restart here (or in
+storage.json when it must also survive the player
+quitting).
+
+| | Values |
+| --- | --- |
+| The plugin's process restarts: reload, upgrade, crash | kept |
+| The plugin failed to start or failed, and starts again | kept |
+| The user disables the plugin, or uninstalls it | cleared |
+| The player quits | cleared |
+
+- **Per plugin.** A plugin sees only its own keys. Like
+  dataDirectory, the values belong to the
+  installation: a development load (`--plugin`) has its own.
+- **JSON.** `set` stores what `JSON.stringify(value)` writes, and `get`
+  returns that, parsed: `undefined` object properties are dropped, a `Date`
+  comes back as a string, `NaN` as `null`. **The order of an object's
+  properties is not kept**: they may come back in another order. A value
+  `JSON.stringify` cannot write (`undefined`, a function, a cycle, a
+  `BigInt`) or a string with a lone surrogate (`"\uD800"`) fails with
+  `invalid`. The value is not checked when it comes back: after an upgrade
+  an older version's value may be read, so check its shape when it matters.
+- **Bounded.** Keys are 1–1024 bytes of text. A plugin holds at most 1 MiB,
+  counting every key, its value as compact JSON and 128 bytes per key
+  (SESSION_STORAGE_LIMITS); a
+  `set` beyond it fails with `limit` and changes nothing. One `set` is
+  also one message to the player, at most 1 MiB with its key, so a single
+  value is a little smaller than that; a larger one fails with `limit`.
+  Split large state over several keys.
+- **Each call is one request.** A `set` is kept once its promise
+  resolves, so a crash right after loses nothing; there is no debounce.
+  Calls answer in order.
+
+```ts
+interface SessionStorage {
+  /** The value stored under `key`, or `undefined` when there is none. */
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  /**
+   * Store or replace `value` under `key`. `invalid` for a bad key or a value that is not JSON, `limit` when the plugin's values would be over 1 MiB or the request over the 1 MiB message limit.
+   */
+  set(key: string, value: unknown): Promise<void>;
+  /** Remove a key; removing a missing one is fine. */
+  delete(key: string): Promise<void>;
+  /** The keys stored, in code point order. */
+  keys(): Promise<string[]>;
 }
 ```
 
@@ -7436,6 +7555,10 @@ class TestHost implements Transport {
    * The player's secret store for this plugin: name → value. Preset entries to simulate stored secrets; inject failures with `host.handle("secrets.get", ...)`. Like the player, `secrets.set` of a new name fails `limit` once 256 names are stored.
    */
   readonly secrets: Map<string, string>;
+  /**
+   * `plugin.storage.session`: key → value, as the player keeps them. Preset entries to simulate values an earlier run of the plugin stored in the same player session, or pass `startPlugin(..., { sessionStorage })`. Like the player, a key is 1–1024 bytes, a `set` that would make the entries larger than 1 MiB (keys, values as compact JSON and `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an object's properties are stored sorted, as the player hands them back.
+   */
+  readonly sessionStorage: Map<string, Json>;
   /** What `plugin.app.system()` reports. */
   systemInfo: WireSystemInfo;
   /** What `plugin.app` reports. Set it before startPlugin: the plugin receives it once at start-up. */
@@ -7720,6 +7843,10 @@ function startPlugin(activate: (plugin: Plugin) => unknown, options?: {
   host?: TestHost;
   /** Use an existing directory as `plugin.dataDirectory` (to test a restart). */
   dataDirectory?: string;
+  /**
+   * Start with these `plugin.storage.session` values (to test a restart within one player session): pass the previous run's `host.sessionStorage`. They are copied into the new host's TestHost.sessionStorage.
+   */
+  sessionStorage?: ReadonlyMap<string, Json>;
   /**
    * The interface language to play (TestHost.locale): the plugin's `locales/<locale>.po` (or `.json`) in `directory` is loaded and its menus, messages and titles show translated. Default: the host's.
    */
@@ -8007,6 +8134,27 @@ const OSD_LIMITS: Readonly<{
 }>;
 ```
 
+### SESSION_STORAGE_LIMITS
+
+The player's limits on SessionStorage. A key outside them fails
+with code `invalid`; a `set` that would make the plugin's entries larger
+than `bytes` fails with `limit` and changes nothing. A single `set` must
+also fit in one message to the player
+(MESSAGE_LIMIT, 1 MiB
+with the key and the request around the value). The player's tests check
+that these agree with the player.
+
+```ts
+const SESSION_STORAGE_LIMITS: Readonly<{
+  /** UTF-8 bytes of a key (1024, at least 1; no NUL character). */
+  readonly keyBytes: 1024;
+  /** Bytes one plugin may hold at the same time: for every key, its UTF-8 bytes, its value written as compact JSON (`JSON.stringify(value)`) and `entryBytes`. */
+  readonly bytes: number;
+  /** What each key costs on top of its text and value (128): the player's own bookkeeping, so that many tiny entries stay within `bytes` of memory. */
+  readonly entryBytes: 128;
+}>;
+```
+
 ### SECRET_LIMITS
 
 The player's limits on Secrets. A name or value outside them

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.24: 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. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.25: 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. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2128–2193.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2172–2238.
 
 **main.ts**
 
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `ui.settings`: Settings.page/show
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2194–2236.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2239–2281.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1614–1779; TestHost: L6900.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1635–1823; TestHost: L7019.
 
 **Command line**
 
@@ -106,39 +106,39 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
-- Others: PluginError, llms-full.txt L3135.
+- Others: PluginError, llms-full.txt L3190.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–214
-- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–608; Video and audio processing L609–687; Windows, panels, settings pages, dialogs and the OSD L688–976
-- How-to: Keep a slider responsive while dragging L977–1151; Remember a window's state between runs L1152–1281; Translate a plugin L1282–1465; Migrate a plugin to English source text L1466–1613; Test a plugin L1614–1779; Publish a plugin L1780–1868; Migrating off package rollback (1.5.16, removed in 1.5.17) L1869–1944
-- Guidelines: Interface guidelines L1945–2029; Menu guidelines L2030–2127
-- Reference: Manifest L2128–2193; Capabilities L2194–2236; Limits L2237–2331; Commands, menus and bindings L2332–2800; Platforms L2801–2829; Theme L2830–3036; Command line L3037–3092
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3093–6735
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6736–8109
+- Concepts: How a plugin runs L215–385; Commands, menus and key bindings L386–483; Playback state, controls and sources L484–629; Video and audio processing L630–708; Windows, panels, settings pages, dialogs and the OSD L709–997
+- How-to: Keep a slider responsive while dragging L998–1172; Remember a window's state between runs L1173–1302; Translate a plugin L1303–1486; Migrate a plugin to English source text L1487–1634; Test a plugin L1635–1823; Publish a plugin L1824–1912; Migrating off package rollback (1.5.16, removed in 1.5.17) L1913–1988
+- Guidelines: Interface guidelines L1989–2073; Menu guidelines L2074–2171
+- Reference: Manifest L2172–2238; Capabilities L2239–2281; Limits L2282–2386; Commands, menus and bindings L2387–2855; Platforms L2856–2884; Theme L2885–3091; Command line L3092–3147
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3148–6854
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6855–8257
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3327, Scope L3196, PluginError L3135, Disposable L3108
-- Commands L3539; Windows L3769; Panels L4412; Dialogs L4698; Player L5165; video: VideoFilter L5472, VideoView L5535, RenderOptions L5577; audio: AudioFilter L5496; Subtitles L5675; media: MediaCapture L5835; Resolvers L5940; Packages L6182; Osd L5408; Host L5339; Clipboard L6314; Power L6334; Tools L6367; Storage L6410; System L6433; Secrets L6451; window: MainWindow L4535; App L4616; Bindings L6284; Ui L3644; Timeline L4492; Drops L4068; Appearance L4097; I18n L4239; Settings L4345.
+- Plugin L3382, Scope L3251, PluginError L3190, Disposable L3163
+- Commands L3594; Windows L3824; Panels L4467; Dialogs L4753; Player L5220; video: VideoFilter L5527, VideoView L5590, RenderOptions L5632; audio: AudioFilter L5551; Subtitles L5730; media: MediaCapture L5890; Resolvers L5995; Packages L6237; Osd L5463; Host L5394; Clipboard L6369; Power L6389; Tools L6422; Storage L6465; System L6552; Secrets L6570; window: MainWindow L4590; App L4671; Bindings L6339; Ui L3699; Timeline L4547; Drops L4123; Appearance L4152; I18n L4294; Settings L4400.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L8533–8622
-- blur: A tool window with one slider that blurs the playing video. L8623–8884
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8885–9217
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9218–9402
-- panel-menu: A sidebar panel with its own right-click menu. L9403–9608
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9609–9768
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9769–9932
-- markdown: A window that shows a Markdown document. L9933–10127
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10128–10295
+- hello: The README Quick start: one menu command and an on-screen message. L8681–8770
+- blur: A tool window with one slider that blurs the playing video. L8771–9032
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9033–9365
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9366–9550
+- panel-menu: A sidebar panel with its own right-click menu. L9551–9756
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9757–9916
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9917–10080
+- markdown: A window that shows a Markdown document. L10081–10275
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10276–10443
 
 ## Optional
 

package/package.json

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