@vestra-player/sdk 1.5.34 → 1.5.35

package/CHANGELOG.md

@@ -1,11 +1,21 @@
 # Changelog
 
+## 1.5.35
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.13 (`"minPlayerVersion": "0.5.13"`): older players leave `SystemInfo.renderingReason` out, refuse `rendering.state` as an unknown request (`unsupported`), and do not load a plugin that declares the new capability `rendering.manage`. A plugin that uses none of it sees no difference.
+
+- **`plugin.rendering`** (player 0.5.13): the player's GPU or software rendering choice. `state()` (no capability) reports the renderer drawing now and why (`mode`, `reason`), the saved choice (`preference`: `"auto"`, `"gpu"` or `"software"`), what the next start will use and why (`nextMode`, `nextReason`), `restartPending` (the next start's mode differs from the mode this run started with) and whether `"gpu"` can be chosen now (`gpu.available`, `gpu.reason`). `setPreference(preference)` saves the choice at once and resolves with the new state; the running player keeps its renderer and the next start uses the choice whether or not the user restarts (`invalid`, `unsupported` for `"gpu"` without a GPU renderer or user interface, `unavailable` for `"gpu"` with a driver on the denylist or after a GPU crash, `failed`). `restartPlayer()` resolves once the player accepted, then the player quits normally (every plugin stops) and starts again with the same plugins, continuing a local file at its position (`unsupported` headless, `busy` while a restart is under way or within 30 s after one, `failed`). Reasons are `{ code, message }` with stable kebab-case codes (`RenderingReasonCode`: `default`, `pending`, `headless`, `no-gpu-backend`, `env`, `preference`, `denylist`, `previous-crash`, `init-failed`, `window-fallback`; a newer player may add codes). New types `Rendering`, `RenderingState`, `RenderingReason`, `RenderingReasonCode`, `RenderingMode`, `RenderingPreference`.
+- **New capability `rendering.manage`** ("Choose GPU or software rendering and restart the player", highlighted in the store), last in `CAPABILITIES`; needed by `setPreference` and `restartPlayer`, which reject with `capability` without it. `rendering.state` needs none. The player's capability table copy, `CAPABILITY_INFO`, `vestra-plugin check` and the editor plugin know it.
+- **`SystemInfo.renderingReason`** (player 0.5.13, optional): why `rendering` is what it is, the same reason as `RenderingState.reason`.
+- **`TestHost.rendering`** models the player (the next start's reason in the player's order: `headless` or `no-gpu-backend` before the preference): preset `reason`, `preference`, `startedWith` and `gpu` (available, and why not), with `videoRender.gpu` as the mode drawing now; `setPreference` saves the choice and refuses `"gpu"` while it is not available (`unsupported` for `no-gpu-backend` and `headless`, `unavailable` otherwise), `restartPending` follows the choice back and forth, and `restartPlayer` counts in `restarts` (a second one is `busy`). `failVideoRender("unsupported", …)` also sets the reason to `window-fallback`, and `app.system()` reports it as `renderingReason`.
+- New how-to guide _Offer a GPU rendering switch_.
+
 ## 1.5.34
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. A plugin that reads `SystemInfo.rendering` needs player 0.5.12 (`"minPlayerVersion": "0.5.12"`); older players leave the field out, and a plugin that does not read it sees no difference. Tests that load subtitles past the player's limits now fail with `busy` in `TestHost`, as they would in the player.
 
 - **`plugin.app.system()` reports the renderer** (player 0.5.12): `rendering` is `"gpu"` (render options apply) or `"software"` (they fail with `unsupported`), read at each call (an optional field: absent on players before 0.5.12, where the renderer is unknown), so a plugin can hide its render settings without creating `plugin.video.render()` to find out. No capability. It changes at most once while the player runs, from GPU to software when a window cannot show GPU frames. `TestHost` reports it from `videoRender.gpu`, so `failVideoRender("unsupported", …)` switches both.
-- **`SUBTITLE_LIMITS`** (`@vestra-player/sdk/testing`, `./runtime`): the player's limits on loaded subtitle files. Per source, 4 tracks of one plugin at once, 16 tracks of every plugin, 16 MiB of their files, 16 loads of one plugin and 128 of every plugin (removed tracks still count as loads); 2 loads of one plugin and 8 of every plugin in progress; a file of at most 2 MiB. A file over 2 MiB is `invalid`, the others `busy`. `TestHost` now enforces them with these codes (all but `totalBytes` and the all-plugin upload count, which one plugin cannot reach alone); external tracks a test adds to `subtitles.tracks` count as other plugins'. A new source drops the uploads of the old one (`uploads` entries carry `generation`). `Subtitles.load`, *Load subtitles from a plugin* and *Limits* name them.
+- **`SUBTITLE_LIMITS`** (`@vestra-player/sdk/testing`, `./runtime`): the player's limits on loaded subtitle files. Per source, 4 tracks of one plugin at once, 16 tracks of every plugin, 16 MiB of their files, 16 loads of one plugin and 128 of every plugin (removed tracks still count as loads); 2 loads of one plugin and 8 of every plugin in progress; a file of at most 2 MiB. A file over 2 MiB is `invalid`, the others `busy`. `TestHost` now enforces them with these codes (all but `totalBytes` and the all-plugin upload count, which one plugin cannot reach alone); external tracks a test adds to `subtitles.tracks` count as other plugins'. A new source drops the uploads of the old one (`uploads` entries carry `generation`). `Subtitles.load`, _Load subtitles from a plugin_ and _Limits_ name them.
 - Fix: a subtitle load the player refused no longer keeps one of the plugin's two upload slots. After a refused commit (`busy` at a track limit, `stale`, `invalid`…) the SDK now discards the upload, as it already did for a failure before the commit; before, two refusals on one source left the plugin unable to load any subtitle there until the source changed.
 
 ## 1.5.33
@@ -21,7 +31,7 @@
 - **TestHost follows the player more closely.** A core action run from its menu record (`host.coreAction(id).run()`) while it is disabled now rejects with `command`, like the player (it rejected with `unavailable`, which is what `plugin.host.run` gives). When only disabled commands hold a pressed key, `press` now looks only at the first of them, as the player does: without a `reason` the key passes, even if a later one has a reason. Tests that relied on the old behaviour see a different code or `"passed"`.
 - More corrections from the review: built-in plugins cannot be disabled, so another plugin never gets the built-in playlist's drop extensions or the sequence provider (except a development load replacing the playlist); `validateArchive` reports an archive that cannot be unpacked (over 64 MB, too many files, damaged, unsafe paths) as `invalid` and a broken unpacked package as `host`; `install` is `busy` only while the library is being cleaned up or 64 change records are kept, and `revisionConflict` is retried by calling `install` again; the `PluginError` table no longer lists `staleDigest`, and `versionMismatch` means a newer `minPlayerVersion` only.
 - `llms.txt` may now be 10 KB (10,240 bytes, up from 9 KB) to leave room for about 20 more how-to pages in its index; it stays under 2.6k tokens.
-- New how-to guide: *Load subtitles from a plugin* (reading tracks, selecting with `stale`, uploading SRT/ASS with the limits, the style layer and which plugin's layer the player shows).
+- New how-to guide: _Load subtitles from a plugin_ (reading tracks, selecting with `stale`, uploading SRT/ASS with the limits, the style layer and which plugin's layer the player shows).
 
 ## 1.5.31
 
@@ -29,8 +39,8 @@
 
 - **The Commands, Playback and Services categories reach the full reference standard** (they are now in `STRICT_CATEGORIES`, so CI keeps them complete): `Commands`, `Command`, `Host` and their option types; `Player`, `Media`, `Scrub`, `Stream` and the playback state and stream types; `Storage`, `JsonStore`, `SessionStorage`, `Secrets`, `Clipboard`, `System`, `Tools`, `Power`. Every method has an example (what it does and how it works), `@capability`, `@since` and a `@throws` per error code it can reject with, checked against the SDK and the player's source; every type has `@category`, so the API reference lists them under their category instead of "Other". Methods with an explained example: 75 of 191 → 121.
 - Error codes the reference now names, from the player's source: a control while nothing is open is `invalid` (`close` is not: closing with nothing open just succeeds); `setRate` takes 0.05–10 (the player's own keys stay within 0.25–4); `setOutput`'s volume outside 0–200 is `invalid`; `Stream.stop` rejects only when closing the source fails, and releases the stream either way.
-- **Corrections from the review against the player's source.** `stale` means any change of the source since the state a call is based on: another file or a close, but also any pause, seek or speed change by the user or another plugin. A second sequence provider is refused with `conflict` (`sequence-taken`) without failing activation, and the built-in playlist registers first. `VESTRA_FFMPEG` / `VESTRA_FFPROBE` replace the `PATH` search instead of coming before it. More `@throws`: `capability` for `Secrets` and `Clipboard`; for a generated stream `busy` and `unsupported` for `seek` and `setRate`, `busy` for `setPaused` and `unsupported` for `restart`; `replaced`, `busy` and the resolver failures (`backend`, `unsupported`, `unavailable`) for `open`; `capability` for `Command.ready`; `aborted` for `openStream`; `stale` and `unsupported` for `Scrub.seek`; `disabled` and `unsupported` (players before 0.5.5) for session storage; `failed` and `timeout` (macOS) for `System`. *Store a plugin's data* no longer promises that a quit right after `save` loses nothing (a stopping plugin gets about 300 ms).
-- New how-to guides: *Control playback* (reading and following the state, `stale` and `ifCurrent`, `Media`, core actions, Next and Previous) and *Store a plugin's data* (settings files, session values, secrets, your own files).
+- **Corrections from the review against the player's source.** `stale` means any change of the source since the state a call is based on: another file or a close, but also any pause, seek or speed change by the user or another plugin. A second sequence provider is refused with `conflict` (`sequence-taken`) without failing activation, and the built-in playlist registers first. `VESTRA_FFMPEG` / `VESTRA_FFPROBE` replace the `PATH` search instead of coming before it. More `@throws`: `capability` for `Secrets` and `Clipboard`; for a generated stream `busy` and `unsupported` for `seek` and `setRate`, `busy` for `setPaused` and `unsupported` for `restart`; `replaced`, `busy` and the resolver failures (`backend`, `unsupported`, `unavailable`) for `open`; `capability` for `Command.ready`; `aborted` for `openStream`; `stale` and `unsupported` for `Scrub.seek`; `disabled` and `unsupported` (players before 0.5.5) for session storage; `failed` and `timeout` (macOS) for `System`. _Store a plugin's data_ no longer promises that a quit right after `save` loses nothing (a stopping plugin gets about 300 ms).
+- New how-to guides: _Control playback_ (reading and following the state, `stale` and `ifCurrent`, `Media`, core actions, Next and Previous) and _Store a plugin's data_ (settings files, session values, secrets, your own files).
 - `doc-lint`: `--list explained` lists the methods without an explained example; its summary line no longer says "Not enforced yet" (every example has been enforced since 1.5.30).
 - Comments and docs name the player's host files at their new places (`src/host/src/packages/manifest.rs`, `ui/ui_image.rs`, `ui/ui_values.rs`, `playback/effects.rs`, `ui/theme.rs`).
 
@@ -38,7 +48,7 @@
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Only documentation, its checks and the generated `llms-full.txt` change.
 
-- **Every example explains what it does and how it works.** The standard, in *Maintaining* ("Examples in reference comments"): an `@example` has a task title, a lead saying what it does and how it works (checked against the SDK and the player's source), code that compiles on its own with comments on the key lines, and error handling where the user can make a call fail. All 159 examples of the API now meet it (none did before this release), including the 65 of the UI category, the test helpers (`TestHost`, `startPlugin`, `HostError`), the limits and tables (`COMMAND_LIMITS`, `MENU_IDS`, `BUILTIN_*`, `BAR_BUTTON_ICONS`, `CAPABILITY_INFO`, `BINDING_INPUTS`, `OSD_LIMITS`, `SESSION_STORAGE_LIMITS`, `SECRET_LIMITS`, `UI_VALUE_LIMITS`, `THEME_PALETTES`) and the 1.5.29 bar buttons (`CommandButton`, `TestHost.barButtons`). Every example now type checks (61 did not). Examples no longer compose shown sentences in TypeScript: OSD and dialog texts are templates with arguments.
+- **Every example explains what it does and how it works.** The standard, in _Maintaining_ ("Examples in reference comments"): an `@example` has a task title, a lead saying what it does and how it works (checked against the SDK and the player's source), code that compiles on its own with comments on the key lines, and error handling where the user can make a call fail. All 159 examples of the API now meet it (none did before this release), including the 65 of the UI category, the test helpers (`TestHost`, `startPlugin`, `HostError`), the limits and tables (`COMMAND_LIMITS`, `MENU_IDS`, `BUILTIN_*`, `BAR_BUTTON_ICONS`, `CAPABILITY_INFO`, `BINDING_INPUTS`, `OSD_LIMITS`, `SESSION_STORAGE_LIMITS`, `SECRET_LIMITS`, `UI_VALUE_LIMITS`, `THEME_PALETTES`) and the 1.5.29 bar buttons (`CommandButton`, `TestHost.barButtons`). Every example now type checks (61 did not). Examples no longer compose shown sentences in TypeScript: OSD and dialog texts are templates with arguments.
 - **Corrections found on the way.** `Subtitles.setStyle`, `SubtitlesState.style` and `SubtitleStyle`: when several plugins set a style layer, the effective one is the layer of the plugin whose manifest id sorts last, not the latest call. `COMMAND_LIMITS`: `add` never throws `limit`; the player refuses the registration (activation fails, or `Scope.onError`). `startPlugin`'s restart example gives both runs the same `dataDirectory` instead of copying the data before `stop()` (which could miss a pending store write). `TestHost.settle` says the debounced store write is not waited for. `TestHost.dialogAnswers` is one queue for every kind of dialog. `TestHost.openElsewhere`: calls that return nothing (`TimelineLayer.set` with `ifCurrent`) drop the write silently instead of rejecting. Resolver examples (`I18n.error`, `FileResolverOptions`, `TestHost.otherResolvers`) use a made-up `.ch8` format instead of `.nes`, which the store plugin VestraNES owns.
 - **`llms-full.txt` carries the examples and `@remarks`** of every declaration and member (hidden setup lines dropped, `{@includeCode}` inlined), so the plugin workshop's model sees them: 536 KB → 693 KB (about 137k → 177k tokens). `llms.txt` wording trimmed to stay under its 9 KB limit (9,134 bytes).
 - **Hidden setup lines**: in an `@example` code block, lines above `// ---cut---` are type checked but not shown on the site or in `llms-full.txt`.
@@ -55,7 +65,7 @@
 - **`TestHost.barButtons`**: the plugin's button as the player shows it (`command`, `icon`, `image`, `order`, `enabled`, `checked`, `tooltip`) with `click()`, which runs the command and rejects while it is disabled or once it is gone; empty after the command is disposed. The test host checks buttons as the player does.
 - **`vestra-plugin check` warns** when a plugin mounts a bottom bar whose Slint file does not import `BarButtons` from `@vestra/bar-buttons.slint`, itself or through the plugin's own Slint files it imports (comments do not count; a warning, the check still passes).
 - `BUILTIN_COMMANDS` gains the player's **Toggle Sidebar** (`host/sidebar`, outside the menu, no default key).
-- Docs: *Commands* (concepts) gains *Bottom-bar buttons*; *Commands, menus and bindings* (reference) gains *Bottom-bar buttons*; *Interface guidelines* gains *Writing a bottom bar*; *Limits* gains *Bottom-bar buttons*; *Theme* gains *Bar buttons* and the two icons; *Windows, panels…* points to buttons for a one-click entry point. `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Commands_ (concepts) gains _Bottom-bar buttons_; _Commands, menus and bindings_ (reference) gains _Bottom-bar buttons_; _Interface guidelines_ gains _Writing a bottom bar_; _Limits_ gains _Bottom-bar buttons_; _Theme_ gains _Bar buttons_ and the two icons; _Windows, panels…_ points to buttons for a one-click entry point. `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.28
 
@@ -64,14 +74,14 @@
 - **`BUILTIN_COMMANDS` and `BUILTIN_SUBMENUS` follow the player** (its agreement test failed on them):
   - Subtitles 0.4.6: `vestra.subtitles` **Move Up** and **Move Down** have no default keys any more (they were `Alt+ArrowUp` / `Alt+ArrowDown`, which pan the video).
   - The NES emulator is no longer a built-in plugin (it moved to the plugin repository as VestraNES, under **Games ▸ VestraNES**): its three commands (`nes.open`, `nes.stop`, `nes.window`) and the built-in **Emulator** submenu are gone. The player has no built-in Games item.
-- Docs: *Built-in commands* regenerated; *Menu guidelines* names a domain submenu **Games** for an emulator and no longer lists Emulator at the top level. `TestHost.otherResolvers` examples use a neutral id (`example.emulator`). `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Built-in commands_ regenerated; _Menu guidelines_ names a domain submenu **Games** for an emulator and no longer lists Emulator at the top level. `TestHost.otherResolvers` examples use a neutral id (`example.emulator`). `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.27
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Plugins pick the fix up with the player's next SDK upgrade (the player builds the `plugin` object with its own copy); nothing in a plugin changes.
 
 - **Generated streams reach their full frame rate on Windows.** A stream from `openStream` or a file resolver (the NES emulator: one 1/60 s picture per `frame()`) played at 23–26 frames a second on Windows instead of 60. The SDK asked the player how much audio the sound card had played, rendered at most one frame, and waited 5 ms before asking again; Windows rounds that wait up to its 15.6 ms timer tick, and with the round trip one pass took about 40 ms, so one frame per pass could not keep up. macOS timers are about 1 ms, which hid it. Each pass now calls `frame()` as many times in a row as it takes to refill the whole lead (about 50 ms of audio, unchanged, so latency is unchanged), at most 16 times, and stops early when a frame carries no audio; and a pass that rendered frames and already took longer than 5 ms is followed at once instead of after another timer tick. A pass that rendered nothing (paused, lead full) still waits 5 ms after it ends, so an idle or paused stream asks the player no more often than before. Measured against a real-time audio clock with the NES core and its homebrew ROM: with a 15–30 ms round trip 1.5.26 rendered 22–32 frames a second and let the device run dry, 1.5.27 renders 60 and keeps it fed; only a round trip near 50 ms (the whole lead) still lets it run dry now and then. Controls (start, pause, seek) still apply between frames and never while one renders, and `stop()` still ends after the frame being rendered.
-- Docs: *Example: signal generator* says `frame()` may be called several times back to back. `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Example: signal generator_ says `frame()` may be called several times back to back. `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.26
 
@@ -81,7 +91,7 @@
   - **`vestra-plugin check`** runs it after the type check and fails on any finding; `build` and `pack` run `check` first. **`check --json`** prints the findings as JSON.
   - **`@vestra-player/sdk/ts-plugin`**, a TypeScript language-service plugin: the same findings as errors in the editor, with the quick fix "Add '<capability>' to manifest.json". List it in `tsconfig.json` (`"plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }]`) and use the workspace's TypeScript (VS Code: **Use Workspace Version**).
 - **One rule with the player.** The SDK carries a copy of the player's generated capability table (`src/host/capabilities.json`: which request needs which capability, by event name or processing stage where it depends on one) and the requests each member sends. `CAPABILITY_INFO` is now built from them; its contents are unchanged. `HOST_CAPABILITIES` (`@vestra-player/sdk/runtime`, for the player's agreement test) is the copy.
-- Docs: *Capabilities* gains *Catching a missing capability*; *Getting started* adds the `tsconfig.json` with the plugin and the VS Code step; *Command line* (the rule and `--json`); *Subtitles* and *Capabilities*: changes also need `subtitles.read` (they read the current selection first; the table now says so). `examples/tsconfig.json` lists the plugin. `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Capabilities_ gains _Catching a missing capability_; _Getting started_ adds the `tsconfig.json` with the plugin and the VS Code step; _Command line_ (the rule and `--json`); _Subtitles_ and _Capabilities_: changes also need `subtitles.read` (they read the current selection first; the table now says so). `examples/tsconfig.json` lists the plugin. `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.25
 
@@ -90,7 +100,7 @@
 - **`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.
+- 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
 
@@ -98,11 +108,11 @@
 
 - **`VideoNode` `{ kind: "deinterlace", when: "auto", output: "field" }`** (player 0.5.4; requested by the video plugin, DEINT-AUTO-1: user ruling of 2026-10-27, Auto deinterlacing must cost nothing on progressive files). The player's own deinterlacer instead of BWDIF in the chain: decided per frame from the decoder's interlaced flag, with the decoder's hardware deinterlacer where frames stay on the GPU, one output frame per field; progressive frames pass untouched. It needs no frames in memory, so a chain with only this node keeps zero-copy hardware decoding, where any other node switches to a copy back to memory. It runs before every plugin's chain wherever it is written, and it is shared: on while any plugin's chain has one, off when the last one is removed or its plugin stops. `output: "frame"` with it, or another `deinterlace` node in the same chain, fails with `invalid`. Processed snapshots and exports deinterlace the same frames with BWDIF at field rate. Players before 0.5.4 refuse `auto` with `invalid`, so set `"minPlayerVersion": "0.5.4"`.
 - **`TestHost`** validates the new value as the player does (`nodeProblem`).
-- Docs: *Processing* (ordering and side effects). `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Processing_ (ordering and side effects). `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.23
 
-**Who must change: nobody.** Republishes 1.5.22 with a clean API documentation build; 1.5.22 was tagged but never published to npm: TypeDoc treats warnings as errors and failed on two `{@link}` labels in *Playback* that contained a brace (`Scrub.seek(seconds, { keyframes })`). Documentation only; the code is the same as 1.5.22 below.
+**Who must change: nobody.** Republishes 1.5.22 with a clean API documentation build; 1.5.22 was tagged but never published to npm: TypeDoc treats warnings as errors and failed on two `{@link}` labels in _Playback_ that contained a brace (`Scrub.seek(seconds, { keyframes })`). Documentation only; the code is the same as 1.5.22 below.
 
 ## 1.5.22
 
@@ -110,7 +120,7 @@
 
 - **`Scrub.seek(seconds, { keyframes?: boolean })`** (player 0.5.3; requested by the playback plugin for the seek bar, user ruling of 2026-10-27: the bar follows the same "Jump to keyframes only" switch as the arrow keys, PotPlayer style, no second exact seek). With `keyframes: true` the seek lands on the last keyframe at or before `seconds` (mpv `absolute+keyframes`) instead of decoding up to the exact frame: the picture appears in tens of milliseconds on any file, up to one keyframe interval before the target, and the reported position is the keyframe's. Omitted or `false`: exact, as before. The option goes on the wire only when true (`control: { kind: "seek", seconds, keyframes: true }`); players before 0.5.3 ignore the field and seek exactly, so set `"minPlayerVersion": "0.5.3"` when you rely on it. The player sends a repeated target of the same gesture only once while that seek is still running (a click is a press and a release), keyed on the target and the mode: an exact seek to the target of a keyframe seek is always sent.
 - **`TestHost.seeks`**: every seek a plugin submitted (`player.seek`, `Scrub.seek`), newest last, as `{ seconds, keyframes }`. The test host lands on the exact target in both modes; a non-boolean `keyframes` is `invalid`.
-- Docs: *Playback* (scrubs and the keyframe switch); *Windows, panels, settings pages* gains a pitfall: an `if` that flips under the pointer (a hover highlight created and destroyed on every hover change) rebuilds the window's accessibility tree and drops the video to 10–15 frames a second while the pointer moves; keep the element and change `visible` or `opacity`. `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Playback_ (scrubs and the keyframe switch); _Windows, panels, settings pages_ gains a pitfall: an `if` that flips under the pointer (a hover highlight created and destroyed on every hover change) rebuilds the window's accessibility tree and drops the video to 10–15 frames a second while the pointer moves; keep the element and change `visible` or `opacity`. `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.21
 
@@ -121,7 +131,7 @@
 - **`ToolTipArea` no longer swallows a press** (`slint/vestra/widgets.slint`, the player's widget library; bug fix): the tip was a `PopupWindow`, so while it showed, the first press anywhere only closed it, and it took the keyboard focus. It is now Slint's input-transparent tooltip: every press reaches the control under the pointer. It shows after about half a second (was 600 ms), and `showing` follows that delay closely. No API change.
 - **Icons `fullscreen` and `exit-fullscreen`** in `slint/vestra/icons.slint` (14 × 12, the V-Line style).
 - **`TestHost`**: `host.run("fullscreen")` flips `host.mainWindow.fullscreen` and emits `window.state` (recorded in `coreRuns`); `host/play-pause` declares `Space` and `Mouse:LeftClick`.
-- Docs: *Commands* (the player's mouse defaults), *Playback* (a fullscreen button), the Theme and widgets example (the tooltip); generated tables and `llms.txt` / `llms-full.txt` regenerated.
+- Docs: _Commands_ (the player's mouse defaults), _Playback_ (a fullscreen button), the Theme and widgets example (the tooltip); generated tables and `llms.txt` / `llms-full.txt` regenerated.
 
 ## 1.5.20
 
@@ -139,7 +149,7 @@ Images in list rows, restarting a plugin, and keyframe step seeks (player 0.5.1)
 - **`Player.setStepSeek({ seconds, keyframes })`** (player 0.5.1): with `keyframes: true` the step seeks land on a keyframe (forward at or after position + step, backward at or before position − step, always moving), presses during a seek add up from the landed position, and the on-screen text shows the landed time. Sources without moving video seek exactly; the seek bar, `player.seek`, scrubs, chapters, loops and `player.step` are unaffected. A non-boolean `keyframes` is `invalid`.
 - **`Host.run("seek-backward" | "seek-forward", { seconds })`** (player 0.5.1): one step seek of another step, with the core's checks, mode, accumulation and text. In keyframe mode it resolves once the seek has landed. `seconds` with another action, or outside 0.1–3600 in tenths, is `invalid`. Older players ignore `seconds`: set `"minPlayerVersion": "0.5.1"`.
 - **`TestHost`**: nested images are recorded in `host.images` (with `maxSide`); `ui.remoteImage` is served from `host.remoteImages`; `packages.reload` is modelled (`starting`, then `running`; `packageCalls` method `"reload"`); `stepSeekKeyframes`, the test data `keyframes` and the log `coreSeeks` model keyframe step seeks, and `host.run` takes `seconds`. The test host lands each press at once (the player completes presses that add up together, with one text).
-- Docs: *Windows, panels, settings pages* (images in rows), *Playback* (Step seeks: exact or keyframe); `llms.txt` and `llms-full.txt` regenerated.
+- Docs: _Windows, panels, settings pages_ (images in rows), _Playback_ (Step seeks: exact or keyframe); `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.18
 
@@ -147,7 +157,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 
 - **`TestHost` streams on Windows**: `openStream`'s default transport listened on a socket file in the temp folder, which Windows refuses (`listen EACCES`), so stream tests failed there. It now listens on a named pipe (`\\.\pipe\vestra-test-host-…-producer-<id>`) on Windows and on a Unix socket elsewhere. `producerTransport = "tcp"` still gives the player's own Windows transport (loopback TCP with a token).
 - **The CLI runs from an SDK outside any `node_modules`** (a copy with TypeScript on `NODE_PATH`, as the player's AI workshop vendors it): `dist/i18n-tools.js` resolved TypeScript with a bare ES module import, which ignores `NODE_PATH`, so `vestra-plugin` stopped at start with `ERR_MODULE_NOT_FOUND`. It now resolves TypeScript as the rest of the CLI does.
-- **Built-in plugins cannot be disabled** (user ruling, 2026-10-26: users manage third-party plugins only). The player and `TestHost` answer `packages.setEnabled(builtin, false)` with `unsupported`; a built-in an older player let the user disable runs again after the upgrade. `PluginInfo.builtin`, `Packages.setEnabled` and *Migrating off package rollback* say so; a plugin manager offers no action for a built-in.
+- **Built-in plugins cannot be disabled** (user ruling, 2026-10-26: users manage third-party plugins only). The player and `TestHost` answer `packages.setEnabled(builtin, false)` with `unsupported`; a built-in an older player let the user disable runs again after the upgrade. `PluginInfo.builtin`, `Packages.setEnabled` and _Migrating off package rollback_ say so; a plugin manager offers no action for a built-in.
 
 ## 1.5.17
 
@@ -158,7 +168,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 - **Removed from `CAPABILITY_INFO["plugins.manage"].apis`**: `"Packages.rollback"`; the capability is unchanged otherwise.
 - **`TestHost`**: `host.packages` entries have no `previousVersion` field (delete it from test data), and there is no `packages.rollback` handler.
 - Unchanged: `revisionConflict`, and the `restoring` and `failedDegraded` statuses of `PackageChange`, which belong to recovery from a failed install.
-- Docs: the Capabilities reference loses the deprecation note; *Migrating off package rollback* says what 1.5.17 removed; `llms.txt` and `llms-full.txt` regenerated.
+- Docs: the Capabilities reference loses the deprecation note; _Migrating off package rollback_ says what 1.5.17 removed; `llms.txt` and `llms-full.txt` regenerated.
 
 ## 1.5.16
 
@@ -169,7 +179,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 - **Built-in plugins** run in place from the player installation: `PluginInfo.directory` of a built-in is `<install resources>/plugins/<id>` and read-only (plugins write only under `plugin.dataDirectory`); they can be disabled and enabled, not uninstalled (`unsupported`, as before).
 - **`TestHost`** matches the player: `packages.list` and `packages.changed` report `previousVersion: null` for every plugin, an install no longer records the replaced version, and `packages.rollback` rejects with `unsupported` ("unknown package method"). The `previousVersion` field of `host.packages` entries is deprecated and ignored; it stays required (as `PluginInfo.previousVersion` does), so existing test code compiles unchanged.
 - `"Packages.rollback"` stays in `CAPABILITY_INFO["plugins.manage"].apis` until 1.5.17; the Capabilities reference notes the deprecation.
-- Docs: the new how-to *Migrating off package rollback (1.5.16)*; *Publish a plugin* no longer mentions a roll back button, installing an older version from the store or the user's rollback as a safety net; the data directory is "kept across restarts, disabling and upgrades"; `revisionConflict`, `PackageChange` and `PackageChangeStatus` speak of installs and uninstalls (the statuses are unchanged).
+- Docs: the new how-to _Migrating off package rollback (1.5.16)_; _Publish a plugin_ no longer mentions a roll back button, installing an older version from the store or the user's rollback as a safety net; the data directory is "kept across restarts, disabling and upgrades"; `revisionConflict`, `PackageChange` and `PackageChangeStatus` speak of installs and uninstalls (the statuses are unchanged).
 
 ## 1.5.15
 
@@ -191,7 +201,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 - **Seven groups**: Tutorials, Concepts, How-to, Guidelines, Examples, Reference and API. `scripts/doc-structure.mjs` lists every page and why it is a page of its own; `npm run docs:check` fails on a page that is not listed, a page without a `description`, a placeholder ("coming soon"), a nested folder, a stale generated table or a page far over its size limit.
 - **Reference** (new): Manifest (every field and the player version each newer part of the API needs), Capabilities, Limits, Commands, menus and bindings (built-in menus, submenu keys in use, the built-in commands and their default keys, binding syntax and names, core actions, the keys the system takes first), Platforms, Theme (tokens with their current `vestra` values, fonts, icons, widgets) and Command line. Their tables are generated from the SDK's code and Slint files (`npm run docs:tables`), so they cannot drift from it.
 - **Guidelines** (new): interface and menu rules.
-- **New pages**: Concepts *How a plugin runs*, *Commands, menus and key bindings*, *Playback state, controls and sources*, *Video and audio processing*; How-to *Test a plugin*, *Publish a plugin*; *Translate a plugin* gains the language list and the machine translation review. Getting started and the README link to the Reference instead of repeating its tables; the old compatibility tables are replaced by the generated player version table.
+- **New pages**: Concepts _How a plugin runs_, _Commands, menus and key bindings_, _Playback state, controls and sources_, _Video and audio processing_; How-to _Test a plugin_, _Publish a plugin_; _Translate a plugin_ gains the language list and the machine translation review. Getting started and the README link to the Reference instead of repeating its tables; the old compatibility tables are replaced by the generated player version table.
 - **New exports** for the generated tables and for tests (`@vestra-player/sdk/testing`): `CAPABILITY_INFO` (per capability: the members it opens, the capabilities they also need, the store's wording, whether the store highlights it; `CAPABILITIES` is derived from it), `MESSAGE_LIMIT` (1 MiB per message), `OSD_LIMITS`, `SECRET_LIMITS`, `BINDING_INPUTS` (the key and mouse names a binding is made of), `BUILTIN_SUBMENUS` (the submenu keys the built-in plugins use), `BUILTIN_COMMANDS` (the built-in commands with their menu paths and default keys) and `THEME_PALETTES` (the colours of `vestra` and `vestra-light` by `Theme` token). The player's tests check them against the player.
 - **`TestHost`** enforces the information block's limits like the player: `OsdPanel.set` with more than 32 lines or 4096 bytes (after `maxColumns` is applied) fails with `invalid`.
 - `llms.txt` lists every capability and points at every page of the site in `llms-full.txt`, which now contains all of them.
@@ -286,6 +296,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 
 - Only the plugins built into the player are official plugins; the ids `vestra` and `vestra.*` (any case) are reserved for them. Every other plugin is a third-party plugin, including those hosted in the official plugin repository, and uses `<GitHub user or organization>.<plugin name>`.
 - `PluginError` lists the code `reserved`: `packages.validate`, `packages.validateArchive`, `PackageCandidate.trial` and `PackageCandidate.install` refuse a package with a reserved id. Development loads (`vestra-player --plugin DIR`) still accept one, with a warning, so built-in plugins can be developed; they are never installed.
+
 ## 1.5.4
 
 **Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.
@@ -296,6 +307,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 - **Code copy, opt in.** With `code-copy: true`, code blocks get a 复制 button that reports `copy-code(code)` with the block's text; the plugin copies it (`plugin.clipboard.writeText`). Off by default: views that do not set it look and behave as before.
 - **Cheaper updates** (player): writing a value again with unchanged documents does not parse them again (a new reference for the same text included), and a value with documents is updated in place where its shape allows: changed rows, rows added or removed at the end, and only the changed blocks of a changed document. Streaming a reply into the last row of a 200-message list therefore keeps the list, its scroll position and the other rows. Nothing to change in plugins.
 - `TestHost` keeps nested documents in the view's properties as they were sent; `host.markdown(value)` reads one back from a field (`host.markdown(rows[0].body)`).
+
 ## 1.5.3
 
 **File resolvers: local files as generated streams** (player 0.4.1). Additive; `apiVersion` stays `vestra/1`. Plugins that register one set `"minPlayerVersion": "0.4.1"`: an older player refuses the declaration (`invalid`).

package/dist/api-requests.js

@@ -140,4 +140,7 @@ export const API_REQUESTS = Object.freeze({
     "Secrets.get": [{ method: "secrets.get" }],
     "Secrets.set": [{ method: "secrets.set" }],
     "Secrets.delete": [{ method: "secrets.delete" }],
+    "Rendering.state": [{ method: "rendering.state" }],
+    "Rendering.setPreference": [{ method: "rendering.setPreference" }],
+    "Rendering.restartPlayer": [{ method: "rendering.restart" }],
 });

package/dist/capabilities.d.ts

@@ -48,8 +48,8 @@ export interface CapabilityInfo {
  *
  * A member not listed under any capability needs none (`plugin.tools`,
  * `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
- * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
- * and `plugin.packages.list`).
+ * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`,
+ * `plugin.packages.list` and `plugin.rendering.state`).
  *
  * @example Check in a test that the manifest declares every required capability
  * The test fails, naming the missing capability, when the manifest declares

package/dist/capabilities.js

@@ -10,8 +10,8 @@ import { capabilityInfo } from "./capability-rules.js";
  *
  * A member not listed under any capability needs none (`plugin.tools`,
  * `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
- * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
- * and `plugin.packages.list`).
+ * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`,
+ * `plugin.packages.list` and `plugin.rendering.state`).
  *
  * @example Check in a test that the manifest declares every required capability
  * The test fails, naming the missing capability, when the manifest declares

package/dist/host-capabilities.js

@@ -343,6 +343,17 @@ export const HOST_CAPABILITIES = {
             residency: "none",
             risky: true,
         },
+        {
+            label: "Choose GPU or software rendering and restart the player",
+            methods: [
+                { name: "rendering.setPreference", needs: "rendering.manage" },
+                { name: "rendering.restart", needs: "rendering.manage" },
+            ],
+            name: "rendering.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
     ],
     uncapable: [
         { name: "packages.list", needs: null },
@@ -356,5 +367,6 @@ export const HOST_CAPABILITIES = {
         { name: "storage.session.set", needs: null },
         { name: "storage.session.delete", needs: null },
         { name: "storage.session.keys", needs: null },
+        { name: "rendering.state", needs: null },
     ],
 };

package/dist/plugin/scope.d.ts

@@ -32,6 +32,7 @@ export declare class ScopeImpl implements Plugin {
     readonly storage: import("./types.ts").Storage;
     readonly system: import("./types.ts").System;
     readonly secrets: import("./types.ts").Secrets;
+    readonly rendering: import("./types.ts").Rendering;
     readonly window: import("./types.ts").MainWindow;
     readonly bindings: import("./types.ts").Bindings;
     readonly ui: import("./types.ts").Ui;

package/dist/plugin/scope.js

@@ -17,7 +17,7 @@ import { packages } from "./packages.js";
 import { osd } from "./osd.js";
 import { mainWindow } from "./window.js";
 import { bindingsApi } from "./bindings.js";
-import { clipboard, host, power, secrets, storage, system, tools, } from "./services.js";
+import { clipboard, host, power, rendering, secrets, storage, system, tools, } from "./services.js";
 export class ScopeImpl {
     runtime;
     #parent;
@@ -63,6 +63,7 @@ export class ScopeImpl {
     storage = storage(this);
     system = system(this);
     secrets = secrets(this);
+    rendering = rendering(this);
     window = mainWindow(this);
     bindings = bindingsApi(this);
     ui = ui(this);

package/dist/plugin/services.d.ts

@@ -1,5 +1,5 @@
 import type { ScopeImpl } from "./scope.ts";
-import type { Clipboard, Host, Power, Secrets, Storage, System, Tools } from "./types.ts";
+import type { Clipboard, Host, Power, Rendering, Secrets, Storage, System, Tools } from "./types.ts";
 export declare const clipboard: (scope: ScopeImpl) => Clipboard;
 export declare const host: (scope: ScopeImpl) => Host;
 export declare const power: (scope: ScopeImpl) => Power;
@@ -112,3 +112,4 @@ export declare const SECRET_LIMITS: Readonly<{
     readonly names: 256;
 }>;
 export declare const secrets: (scope: ScopeImpl) => Secrets;
+export declare const rendering: (scope: ScopeImpl) => Rendering;

package/dist/plugin/services.js

@@ -1,7 +1,7 @@
 /**
  * Shared services: the clipboard, sleep prevention, showing and opening files
- * and links, secrets and session storage go to the host; external tools and
- * settings files run in this plugin's own process.
+ * and links, secrets, session storage and the rendering choice 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";
@@ -477,3 +477,23 @@ export const secrets = (scope) => {
         delete: async (name) => scope.runtime.host.secrets.delete(named(name)),
     };
 };
+const PREFERENCES = new Set(["auto", "gpu", "software"]);
+export const rendering = (scope) => {
+    const manage = () => {
+        if (!scope.runtime.can("rendering.manage"))
+            throw failure("capability", "rendering.manage must be declared in manifest");
+    };
+    return {
+        state: async () => (await scope.runtime.host.rendering.state()),
+        async setPreference(preference) {
+            manage();
+            if (typeof preference !== "string" || !PREFERENCES.has(preference))
+                throw failure("invalid", 'the rendering preference is "auto", "gpu" or "software"');
+            return (await scope.runtime.host.rendering.setPreference(preference));
+        },
+        async restartPlayer() {
+            manage();
+            await scope.runtime.host.rendering.restart();
+        },
+    };
+};

package/dist/plugin/testing.d.ts

@@ -15,7 +15,7 @@ import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
-import type { RenderSettings, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
@@ -469,7 +469,7 @@ export interface MarkdownWire {
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -1306,7 +1306,8 @@ export declare class TestHost implements Transport {
     /**
      * What the player pushes when mpv cannot compile a shader (code `failed`)
      * or switches to software rendering (`unsupported`, which also sets
-     * `videoRender.gpu` to false). Pushed only when this plugin is the owner.
+     * `videoRender.gpu` to false and `rendering.reason` to `window-fallback`
+     * with `message`). Pushed only when this plugin is the owner.
      *
      * @example Make a shader fail to compile
      * The plugin's render options report `failed`, as when mpv rejects a
@@ -1611,9 +1612,10 @@ export declare class TestHost implements Transport {
     /**
      * What `plugin.app.system()` reports. Its `rendering` follows
      * {@link TestHost.videoRender | videoRender.gpu} (`"gpu"` or
-     * `"software"`), so one switch covers the render options and the fact.
+     * `"software"`), so one switch covers the render options and the fact;
+     * its `renderingReason` is {@link TestHost.rendering | rendering.reason}.
      */
-    systemInfo: Omit<WireSystemInfo, "rendering">;
+    systemInfo: Omit<WireSystemInfo, "rendering" | "renderingReason">;
     /**
      * What `plugin.app` reports. Set it before {@link startPlugin}: the plugin
      * receives it once at start-up.
@@ -1633,6 +1635,74 @@ export declare class TestHost implements Transport {
             slint: string;
         };
     };
+    /**
+     * The player's rendering choice behind `plugin.rendering` (player
+     * 0.5.13). The mode drawing now is {@link TestHost.videoRender |
+     * videoRender.gpu}, as for `plugin.app.system()`; the rest is preset here
+     * and changed by the plugin's calls, as the player would:
+     *
+     * - `setPreference` saves `preference` and never changes the mode. It
+     *   refuses `"gpu"` while `gpu.available` is false: with `unsupported`
+     *   when `gpu.reason.code` is `no-gpu-backend` or `headless`, otherwise
+     *   with `unavailable`, the reason's message in both cases.
+     * - The next start uses `"software"` for the `"software"` choice, else
+     *   software with `gpu.reason` while the GPU is not available, else the
+     *   GPU (code `preference` for a `"gpu"` choice, `default` for
+     *   `"auto"`). `restartPending` compares that with `startedWith`.
+     * - `restartPlayer` counts in `restarts` and leaves the plugin running
+     *   (call `stop()` yourself); a second one rejects with `busy`, as a
+     *   restart is then under way.
+     *
+     * Inject other refusals (`failed` for an unwritable settings file or a
+     * new process that could not start) with `host.handle("rendering.setPreference", …)`
+     * or `host.handle("rendering.restart", …)`. The defaults are a macOS
+     * player on the GPU: `"auto"`, available, started on the GPU.
+     *
+     * @example Test a GPU switch on a system without a GPU renderer
+     * The plugin's GPU menu item is greyed out with the player's reason when
+     * the GPU cannot be chosen. The host is preset before the plugin starts,
+     * because the plugin reads the state while activating; software
+     * rendering is `videoRender.gpu = false`, and `gpu` says why the GPU
+     * cannot be chosen.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.rendering.startedWith = "software";
+     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.gpu = { available: false, reason: host.rendering.reason };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * const item = host.command("gpu-rendering");
+     * assert.equal(item.state.enabled, false);
+     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * await stop();
+     * ```
+     *
+     * @since 1.5.35
+     */
+    readonly rendering: {
+        /** Why the mode drawing now is what it is (`RenderingState.reason`, `SystemInfo.renderingReason`). */
+        reason: RenderingReason;
+        /** The saved choice: `"auto"`, `"gpu"` or `"software"`. */
+        preference: RenderingPreference;
+        /** The mode this run started with; `restartPending` compares the next start's mode with it. */
+        startedWith: RenderingMode;
+        /** Whether the plugin may choose `"gpu"`, and why not (`null` while available). */
+        gpu: {
+            /** `false`: `setPreference("gpu")` is refused. */
+            available: boolean;
+            /** Why the GPU cannot be chosen; `null` while it can. */
+            reason: RenderingReason | null;
+        };
+        /** Accepted `restartPlayer` calls. */
+        restarts: number;
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */