@vestra-player/sdk 1.5.24 → 1.5.26

package/dist/capability-rules.js

@@ -0,0 +1,132 @@
+/**
+ * The capability rule, as data: which manifest capability a request needs
+ * (the player's table, `HOST_CAPABILITIES`, synced from its
+ * `src/host/capabilities.json`) and which requests each public member of the
+ * plugin API sends (`API_REQUESTS`). `CAPABILITY_INFO`, `vestra-plugin check`
+ * and the TypeScript language-service plugin are all built from these two
+ * tables, so they and the player cannot disagree.
+ *
+ * @internal
+ */
+import { API_REQUESTS } from "./api-requests.js";
+import { HOST_CAPABILITIES } from "./host-capabilities.js";
+/** @internal The SDK's rules: the synced player table and `API_REQUESTS`. */
+export const RULES = {
+    host: HOST_CAPABILITIES,
+    apis: API_REQUESTS,
+};
+/**
+ * The player's entry for a method, as the player routes it: the exact name
+ * first, then the first `prefix.*` entry whose prefix it starts with.
+ * `undefined`: the player does not know the method.
+ *
+ * @internal
+ */
+export function hostMethod(method, host = RULES.host) {
+    const all = [
+        ...host.capabilities.flatMap((capability) => capability.methods),
+        ...host.uncapable,
+    ];
+    return (all.find((entry) => entry.name === method) ??
+        all.find((entry) => entry.name.endsWith(".*") && method.startsWith(entry.name.slice(0, -1))));
+}
+/**
+ * The capability one request needs, as the player decides it
+ * (`capabilities::Route::needs`): `null` for none, `undefined` for a method
+ * the player does not know.
+ *
+ * @param method - The wire method.
+ * @param params - Its string parameters that a `Needs::Param` rule reads.
+ * @param declared - Whether the plugin declared a capability.
+ *
+ * @internal
+ */
+export function requestNeeds(method, params, declared, host = RULES.host) {
+    const entry = hostMethod(method, host);
+    if (!entry)
+        return undefined;
+    const needs = entry.needs;
+    if (needs === null || typeof needs === "string")
+        return needs;
+    if ("param" in needs) {
+        const value = params?.[needs.param];
+        return value !== undefined && Object.hasOwn(needs.cases, value)
+            ? needs.cases[value]
+            : needs.otherwise;
+    }
+    return declared(needs.ifDeclared) ? needs.then : needs.otherwise;
+}
+/**
+ * Every capability a member of the plugin API needs with the given manifest:
+ * those its requests need and, through `requires`, those they need in turn.
+ * `undefined`: the member is not in the table (it needs none).
+ *
+ * @param api - The member as `Interface.member` (`Player.seek`).
+ * @param capabilities - The manifest's capabilities.
+ *
+ * @internal
+ */
+export function memberNeeds(api, capabilities, rules = RULES) {
+    const requests = rules.apis[api];
+    if (!requests)
+        return undefined;
+    // An `ifDeclared` rule is decided last, as if the plugin had declared what
+    // the member's other requests need: `Player.seek` needs `playback.control`
+    // for `source.submit`, and with it `source.operation` needs nothing more.
+    const declared = (name) => capabilities.includes(name) ||
+        needs.some((need) => need.capability === name);
+    const conditional = (request) => {
+        const rule = hostMethod(request.method, rules.host)?.needs;
+        return typeof rule === "object" && rule !== null && "ifDeclared" in rule;
+    };
+    const needs = [];
+    const add = (need) => {
+        if (needs.some((each) => each.capability === need.capability))
+            return;
+        needs.push(need);
+        const entry = rules.host.capabilities.find((capability) => capability.name === need.capability);
+        for (const required of entry?.requires ?? [])
+            add({
+                capability: required,
+                method: need.method,
+                requiredBy: need.capability,
+            });
+    };
+    for (const request of [
+        ...requests.filter((request) => !conditional(request)),
+        ...requests.filter(conditional),
+    ]) {
+        const capability = requestNeeds(request.method, request.params, declared, rules.host);
+        if (capability)
+            add({ capability, method: request.method });
+    }
+    return needs;
+}
+/**
+ * `CAPABILITY_INFO` from the tables: the label, highlight and requirements
+ * from the player's table; the members from `API_REQUESTS` (every member a
+ * request of which needs the capability, in the table's order; requests
+ * marked `also` are left out, as they are documented at the member).
+ *
+ * @internal
+ */
+export function capabilityInfo(rules = RULES) {
+    const info = {};
+    for (const capability of rules.host.capabilities)
+        info[capability.name] = {
+            apis: [],
+            requires: [...capability.requires],
+            label: capability.label,
+            risky: capability.risky,
+        };
+    for (const [api, requests] of Object.entries(rules.apis))
+        for (const request of requests) {
+            if (request.also)
+                continue;
+            const capability = requestNeeds(request.method, request.params, () => true, rules.host);
+            const entry = capability ? info[capability] : undefined;
+            if (entry && !entry.apis.includes(api))
+                entry.apis.push(api);
+        }
+    return info;
+}

package/dist/host-capabilities.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The player's capability table, copied from its `src/host/capabilities.json`
+ * by `npm run capabilities:sync -- <player repository>`. Do not edit: change
+ * the player's capability modules, regenerate its JSON and sync again.
+ *
+ * @internal
+ */
+import type { HostCapabilities } from "./capability-rules.ts";
+/** @internal */
+export declare const HOST_CAPABILITIES: HostCapabilities;

package/dist/host-capabilities.js

@@ -0,0 +1,360 @@
+// "then" is a field of the player's IfDeclared rule, not a thenable.
+/* oxlint-disable unicorn/no-thenable */
+/** @internal */
+export const HOST_CAPABILITIES = {
+    about: "Generated from src/host/src/capabilities/ (VESTRA_UPDATE_CAPABILITIES=1 cargo test capabilities); do not edit. A method's needs: null (none), a capability name, {param, cases, otherwise} (by a string parameter) or {ifDeclared, then, otherwise}. A method name ending in .* covers the prefix's other methods.",
+    apiVersion: "vestra/1",
+    capabilities: [
+        {
+            label: "Provide audio and video it generates itself",
+            methods: [
+                { name: "producer.prepare", needs: "producer.av" },
+                { name: "producer.state", needs: "producer.av" },
+                { name: "producer.release", needs: "producer.av" },
+                { name: "producer.ack", needs: "producer.av" },
+                { name: "producer.declareInput", needs: "producer.av" },
+                { name: "producer.ackInput", needs: "producer.av" },
+            ],
+            name: "producer.av",
+            requires: ["playback.control"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read what is playing and the position",
+            methods: [
+                { name: "source.state", needs: "playback.read" },
+                { name: "processing.state", needs: "playback.read" },
+                { name: "playback.stats", needs: "playback.read" },
+                { name: "player.chapters", needs: "playback.read" },
+                { name: "player.audioDevices", needs: "playback.read" },
+                { name: "timeline.marks", needs: "playback.read" },
+            ],
+            name: "playback.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Open media, control playback, keep the computer awake",
+            methods: [
+                { name: "playback.set", needs: "playback.control" },
+                { name: "source.submit", needs: "playback.control" },
+                {
+                    name: "source.operation",
+                    needs: {
+                        ifDeclared: "playback.control",
+                        otherwise: "playback.read",
+                        then: "playback.control",
+                    },
+                },
+                { name: "audio.addTrack", needs: "playback.control" },
+                { name: "audio.selectTrack", needs: "playback.control" },
+                { name: "player.setLoop", needs: "playback.control" },
+                { name: "player.setAudioDevice", needs: "playback.control" },
+                { name: "player.step", needs: "playback.control" },
+                { name: "player.setStepSeek", needs: "playback.control" },
+                { name: "power.preventSleep", needs: "playback.control" },
+                { name: "sequence.set", needs: "playback.control" },
+                { name: "sequence.step", needs: "playback.control" },
+            ],
+            name: "playback.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Resolve online video addresses",
+            methods: [
+                { name: "sourceResolvers.register", needs: "source.resolve" },
+                { name: "sourceResolvers.unregister", needs: "source.resolve" },
+                { name: "sourceResolvers.respond", needs: "source.resolve" },
+                { name: "sourceResolvers.*", needs: "source.resolve" },
+            ],
+            name: "source.resolve",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Receive playback changes as they happen",
+            methods: [
+                {
+                    name: "events.subscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+                {
+                    name: "events.unsubscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+            ],
+            name: "events",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Add menu commands and shortcuts",
+            methods: [
+                { name: "commands.register", needs: "commands" },
+                { name: "commands.update", needs: "commands" },
+                { name: "commands.unregister", needs: "commands" },
+                { name: "host.run", needs: "commands" },
+            ],
+            name: "commands",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Open tool windows",
+            methods: [
+                { name: "ui.open", needs: "ui.window" },
+                { name: "ui.set", needs: "ui.window" },
+                { name: "ui.show", needs: "ui.window" },
+                { name: "ui.close", needs: "ui.window" },
+            ],
+            name: "ui.window",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show panels in the bottom bar, the sidebar or behind the video",
+            methods: [
+                { name: "ui.mount", needs: "ui.mount" },
+                { name: "ui.setMount", needs: "ui.mount" },
+                { name: "ui.unmount", needs: "ui.mount" },
+                { name: "ui.interaction", needs: "ui.mount" },
+                { name: "ui.menu", needs: "ui.mount" },
+                { name: "layout.state", needs: "ui.mount" },
+                { name: "layout.set", needs: "ui.mount" },
+            ],
+            name: "ui.mount",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show file pickers and confirmations",
+            methods: [
+                { name: "dialogs.open", needs: "ui.dialog" },
+                { name: "dialogs.confirm", needs: "ui.dialog" },
+            ],
+            name: "ui.dialog",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Install, uninstall and disable other plugins",
+            methods: [{ name: "packages.*", needs: "plugins.manage" }],
+            name: "plugins.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Process the picture (filters, shaders)",
+            methods: [
+                {
+                    name: "processing.replace",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                {
+                    name: "processing.operation",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                { name: "video.view.set", needs: "processing.video" },
+                { name: "video.view.release", needs: "processing.video" },
+                { name: "video.render.set", needs: "processing.video" },
+                { name: "video.render.release", needs: "processing.video" },
+            ],
+            name: "processing.video",
+            requires: ["playback.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Process the sound",
+            methods: [],
+            name: "processing.audio",
+            requires: ["playback.read", "events"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read subtitles",
+            methods: [{ name: "subtitles.state", needs: "subtitles.read" }],
+            name: "subtitles.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Load and change subtitles",
+            methods: [{ name: "subtitles.*", needs: "subtitles.control" }],
+            name: "subtitles.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.state", needs: "media.read" },
+                { name: "jobs.state", needs: "media.read" },
+                { name: "jobs.operation", needs: "media.read" },
+            ],
+            name: "media.read",
+            requires: ["media.control"],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.*", needs: "media.control" },
+                { name: "jobs.*", needs: "media.control" },
+            ],
+            name: "media.control",
+            requires: ["media.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show messages on the video",
+            methods: [
+                { name: "osd.show", needs: "ui.osd" },
+                { name: "osd.panel", needs: "ui.osd" },
+            ],
+            name: "ui.osd",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read and write the clipboard",
+            methods: [
+                { name: "clipboard.readText", needs: "clipboard" },
+                { name: "clipboard.writeText", needs: "clipboard" },
+                { name: "clipboard.writeImage", needs: "clipboard" },
+            ],
+            name: "clipboard",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Adjust the main window (size, on top, picture-in-picture)",
+            methods: [
+                { name: "window.setVideoArea", needs: "window.control" },
+                { name: "window.setAlwaysOnTop", needs: "window.control" },
+                { name: "window.setCursorAutoHide", needs: "window.control" },
+                { name: "window.setPictureInPicture", needs: "window.control" },
+            ],
+            name: "window.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Change all shortcuts",
+            methods: [
+                { name: "bindings.list", needs: "bindings.manage" },
+                { name: "bindings.set", needs: "bindings.manage" },
+                { name: "bindings.reset", needs: "bindings.manage" },
+            ],
+            name: "bindings.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Show marks on the progress bar",
+            methods: [{ name: "timeline.set", needs: "timeline.marks" }],
+            name: "timeline.marks",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Receive files dropped on the player",
+            methods: [
+                { name: "drops.provide", needs: "ui.drop" },
+                { name: "drops.withdraw", needs: "ui.drop" },
+                { name: "drops.listen", needs: "ui.drop" },
+            ],
+            name: "ui.drop",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Add pages to the Options window",
+            methods: [{ name: "settings.*", needs: "ui.settings" }],
+            name: "ui.settings",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Change the player's palette",
+            methods: [
+                { name: "appearance.set", needs: "ui.theme" },
+                { name: "appearance.setLanguage", needs: "ui.theme" },
+            ],
+            name: "ui.theme",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Store sign-in details in the system keychain",
+            methods: [
+                { name: "secrets.get", needs: "secrets" },
+                { name: "secrets.set", needs: "secrets" },
+                { name: "secrets.delete", needs: "secrets" },
+            ],
+            name: "secrets",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+    ],
+    uncapable: [
+        { name: "packages.list", needs: null },
+        { name: "window.state", needs: null },
+        { name: "system.reveal", needs: null },
+        { name: "system.openPath", needs: null },
+        { name: "system.openUrl", needs: null },
+        { name: "app.system", needs: null },
+        { name: "ui.markdownScan", needs: null },
+        { name: "storage.session.get", needs: null },
+        { name: "storage.session.set", needs: null },
+        { name: "storage.session.delete", needs: null },
+        { name: "storage.session.keys", needs: null },
+    ],
+};

package/dist/player-runtime.d.ts

@@ -12,10 +12,11 @@ export type { PluginInstance, PluginManifest } from "./plugin/index.ts";
 export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.ts";
+export { HOST_CAPABILITIES } from "./host-capabilities.ts";
 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

@@ -10,10 +10,11 @@
 export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.js";
+export { HOST_CAPABILITIES } from "./host-capabilities.js";
 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) => {