@vestra-player/sdk 1.5.51 → 1.5.52

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.5.52
+
+**Who must change: nobody.** Additive: `WindowState` gains `maximized`, `apiVersion` stays `vestra/1`, no new capability. Players before 0.6.3 do not report it and it reads `false` there; a plugin that depends on it sets `"minPlayerVersion": "0.6.3"`. A test that deep-compares the whole `plugin.window.state` now also sees `maximized: false`.
+
+- **`plugin.window.state.maximized`** (player 0.6.3): `true` while the main window is maximized, `false` in fullscreen (also when the window was maximized before and is again after leaving it). Changes arrive through `plugin.window.onChange` like the other window facts (with `events` for changes made by the user). A plugin that resizes the window, such as the Window plugin's "Window size when playback starts", leaves a maximized window alone, as MPC-HC and mpv do. The player sends it as `maximized` in the `window.state` reply and event; the SDK reads a missing or non-boolean field as `false`.
+- **`TestHost`**: `host.mainWindow.maximized` (default `false`) and `host.setMainWindow({ maximized: true })`, which broadcasts `window.state` as the player does; like the player, `window.state` reports `false` while fullscreen.
+- _Docs_: `WindowState.maximized`, `MainWindow`, `TestHost.setMainWindow` and [Reference: testing](docs/reference/testing.md#simulating-the-player) describe it.
+
 ## 1.5.51
 
 **Who must change: nobody.** Additive: `MENU_IDS` and `MenuId` gain `reset`, `apiVersion` stays `vestra/1`, no new capability. A plugin that puts a command under `@reset` sets `"minPlayerVersion": "0.6.3"`: older players refuse `@reset` with `invalid` (since SDK 1.5.49 that command is skipped and the rest of the plugin activates).

package/dist/plugin/testing.d.ts

@@ -1664,14 +1664,22 @@ export declare class TestHost implements Transport {
     readonly confirms: Record<string, Json>[];
     /**
      * The main window as the player would show it. Change it with
-     * `setMainWindow` (the user resized it, entered fullscreen, closed the
-     * picture-in-picture window); `onTop`, `cursorAutoHide` and
+     * `setMainWindow` (the user resized or maximized it, entered fullscreen,
+     * closed the picture-in-picture window); `onTop`, `cursorAutoHide` and
      * `pictureInPicture.active` record the plugin's `window.set…` calls.
      * `pictureInPicture.supported: false` stands for Windows and Linux.
      */
     readonly mainWindow: {
         /** Whether the main window is fullscreen. */
         fullscreen: boolean;
+        /**
+         * Whether the main window is maximized (default `false`). Like the
+         * player, `window.state` reports `false` while fullscreen and this
+         * value again after leaving it.
+         *
+         * @since 1.5.52
+         */
+        maximized: boolean;
         /** The video area in logical points (default 780×609). */
         videoArea: {
             /** Width in logical points. */
@@ -2168,15 +2176,17 @@ export declare class TestHost implements Transport {
      */
     setSource(patch: Partial<SourceState>): void;
     /**
-     * Simulate the user changing the main window (resizing it, entering or
-     * leaving fullscreen, closing the picture-in-picture window) and broadcast
-     * it. Like the player, entering fullscreen collapses an attached, visible
+     * Simulate the user changing the main window (resizing, maximizing or
+     * restoring it, entering or leaving fullscreen, closing the
+     * picture-in-picture window) and broadcast it. `maximized` (SDK 1.5.52)
+     * reads `false` while fullscreen, as player 0.6.3 reports it. Like the player, entering fullscreen collapses an attached, visible
      * sidebar (`effective: false`, `reason: "fullscreen"`) and leaving
      * fullscreen docks it again.
      *
-     * @example Go fullscreen, then report picture-in-picture support
+     * @example Go fullscreen, report picture-in-picture support, maximize
      * The plugin sees the main window fullscreen at 1920×1080, then learns
-     * that picture-in-picture is available. `setMainWindow` changes the
+     * that picture-in-picture is available, then sees the window leave
+     * fullscreen maximized. `setMainWindow` changes the
      * host's window facts and broadcasts them as the player does when the
      * user resizes or toggles fullscreen; entering fullscreen also collapses
      * an attached sidebar.
@@ -2188,6 +2198,10 @@ export declare class TestHost implements Transport {
      * await host.settle();
      * assert.equal(plugin.window.state.fullscreen, true);
      * host.setMainWindow({ pictureInPicture: { supported: true, active: false } });
+     * // Leaving fullscreen into a maximized window: `maximized` reads true again.
+     * host.setMainWindow({ fullscreen: false, maximized: true });
+     * await host.settle();
+     * assert.equal(plugin.window.state.maximized, true);
      * ```
      *
      * @capability None.
@@ -2195,6 +2209,7 @@ export declare class TestHost implements Transport {
      */
     setMainWindow(patch: Partial<{
         fullscreen: boolean;
+        maximized: boolean;
         videoArea: {
             width: number;
             height: number;

package/dist/plugin/testing.js

@@ -1794,14 +1794,22 @@ export class TestHost {
     confirms = [];
     /**
      * The main window as the player would show it. Change it with
-     * `setMainWindow` (the user resized it, entered fullscreen, closed the
-     * picture-in-picture window); `onTop`, `cursorAutoHide` and
+     * `setMainWindow` (the user resized or maximized it, entered fullscreen,
+     * closed the picture-in-picture window); `onTop`, `cursorAutoHide` and
      * `pictureInPicture.active` record the plugin's `window.set…` calls.
      * `pictureInPicture.supported: false` stands for Windows and Linux.
      */
     mainWindow = {
         /** Whether the main window is fullscreen. */
         fullscreen: false,
+        /**
+         * Whether the main window is maximized (default `false`). Like the
+         * player, `window.state` reports `false` while fullscreen and this
+         * value again after leaving it.
+         *
+         * @since 1.5.52
+         */
+        maximized: false,
         /** The video area in logical points (default 780×609). */
         videoArea: {
             /** Width in logical points. */
@@ -2745,15 +2753,17 @@ export class TestHost {
             this.setBackdropEffective(true);
     }
     /**
-     * Simulate the user changing the main window (resizing it, entering or
-     * leaving fullscreen, closing the picture-in-picture window) and broadcast
-     * it. Like the player, entering fullscreen collapses an attached, visible
+     * Simulate the user changing the main window (resizing, maximizing or
+     * restoring it, entering or leaving fullscreen, closing the
+     * picture-in-picture window) and broadcast it. `maximized` (SDK 1.5.52)
+     * reads `false` while fullscreen, as player 0.6.3 reports it. Like the player, entering fullscreen collapses an attached, visible
      * sidebar (`effective: false`, `reason: "fullscreen"`) and leaving
      * fullscreen docks it again.
      *
-     * @example Go fullscreen, then report picture-in-picture support
+     * @example Go fullscreen, report picture-in-picture support, maximize
      * The plugin sees the main window fullscreen at 1920×1080, then learns
-     * that picture-in-picture is available. `setMainWindow` changes the
+     * that picture-in-picture is available, then sees the window leave
+     * fullscreen maximized. `setMainWindow` changes the
      * host's window facts and broadcasts them as the player does when the
      * user resizes or toggles fullscreen; entering fullscreen also collapses
      * an attached sidebar.
@@ -2765,6 +2775,10 @@ export class TestHost {
      * await host.settle();
      * assert.equal(plugin.window.state.fullscreen, true);
      * host.setMainWindow({ pictureInPicture: { supported: true, active: false } });
+     * // Leaving fullscreen into a maximized window: `maximized` reads true again.
+     * host.setMainWindow({ fullscreen: false, maximized: true });
+     * await host.settle();
+     * assert.equal(plugin.window.state.maximized, true);
      * ```
      *
      * @capability None.
@@ -2815,6 +2829,8 @@ export class TestHost {
     #windowFacts() {
         return {
             fullscreen: this.mainWindow.fullscreen,
+            // Like player 0.6.3: never maximized while fullscreen.
+            maximized: this.mainWindow.maximized && !this.mainWindow.fullscreen,
             videoArea: { ...this.mainWindow.videoArea },
             pictureInPicture: { ...this.mainWindow.pictureInPicture },
             appearance: this.appearance,

package/dist/plugin/types.d.ts

@@ -4041,6 +4041,18 @@ export interface Timeline {
 export interface WindowState {
     /** The main window is fullscreen. */
     readonly fullscreen: boolean;
+    /**
+     * The main window is maximized (`false` in fullscreen, also when it was
+     * maximized before and will be again after). Changes reach
+     * {@link MainWindow.onChange}. A plugin that sizes the window, such as to
+     * the video when playback starts, leaves a maximized window alone, as
+     * MPC-HC and mpv do. Always `false` with players before 0.6.3, which do
+     * not report it.
+     *
+     * @player 0.6.3; older players: always `false`.
+     * @since 1.5.52
+     */
+    readonly maximized: boolean;
     /** The video column, without the bottom bar, sidebar and splitter. */
     readonly videoArea: {
         /** Logical points. */
@@ -4089,8 +4101,8 @@ export interface WindowState {
  * ```
  *
  * @remarks
- * `plugin.window` is the player's main window: its size, fullscreen,
- * picture-in-picture and the video area. Reading it needs no capability;
+ * `plugin.window` is the player's main window: its size, whether it is
+ * maximized or fullscreen, picture-in-picture and the video area. Reading it needs no capability;
  * changing it needs `window.control`. Changes that last only while the
  * plugin runs (always on top, pointer auto-hide) revert when it stops.
  *

package/dist/plugin/window.js

@@ -2,6 +2,8 @@
 import { failure } from "./runtime.js";
 const view = (facts) => Object.freeze({
     fullscreen: facts.fullscreen === true,
+    // Players before 0.6.3 do not send it; never maximized in fullscreen.
+    maximized: facts.maximized === true && facts.fullscreen !== true,
     videoArea: Object.freeze({
         width: Number(facts.videoArea?.width ?? 0),
         height: Number(facts.videoArea?.height ?? 0),

package/dist/wire.d.ts

@@ -233,6 +233,8 @@ export interface BindingTable {
 /** `window.state`: the main window, in logical points (zero without one). */
 export interface WindowFacts {
     fullscreen: boolean;
+    /** The main window is maximized, `false` in fullscreen (player 0.6.3; absent from older players: `false`). */
+    maximized?: boolean;
     videoArea: {
         width: number;
         height: number;

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.51: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.5.52: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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