@@ -1,5 +1,5 @@
 {
-  "$comment": "Generated by screenrig-protocol-gen from api/openapi.yaml; sha256=11f6d9a8a78c28f001596d14354c0da67b5b767b53118361e989027301b13427. Shape validation for the adslot page union. Run canonical playlist-write-semantics.ts next. At most 16 adslot pages and one ordinary page with no visibility remain server checks.",
+  "$comment": "Generated by screenrig-protocol-gen from api/openapi.yaml; sha256=1b411f9213b31c6238575febb48f9818fd8b962f848cefe47aed6d6aee1f54a7. Shape validation for the adslot page union. Run canonical playlist-write-semantics.ts next. At most 16 adslot pages and one ordinary page with no visibility remain server checks.",
   "$defs": {
     "AdslotPageWrite": {
       "additionalProperties": false,
@@ -316,6 +316,9 @@
           "default": false,
           "type": "boolean"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays"
+        },
         "enter": {
           "$ref": "#/$defs/PrimitiveEnter"
         },
@@ -338,7 +341,8 @@
           "type": "string"
         },
         "rect": {
-          "$ref": "#/$defs/PlaylistRect"
+          "$ref": "#/$defs/PlaylistRect",
+          "description": "Required unless displays is set. With displays, omit it or send the rect derived from them."
         },
         "release_id": {
           "type": "string"
@@ -348,7 +352,6 @@
         "id",
         "primitive",
         "release_id",
-        "rect",
         "layer",
         "content_fit"
       ],
@@ -485,7 +488,7 @@
     },
     "PlaylistCardPrimitiveWrite": {
       "additionalProperties": false,
-      "description": "A built-in card the Player draws natively (clock, weather, menu board, ticker, KPI tiles and the rest of the vendored cards catalog, screenrig.cards.contract/v1). layout places it: full (the whole canvas), free (your own rect and layer), center (900 x 420), wide (the canvas inset 30 from the left and right and 80 from the top and bottom), header (the whole top edge, 80 high), footer (the whole bottom edge, 80 high), corner (270 square), chip (240 x 70) or strip (the whole edge, 120 high), in 1080p design units scaled by min(canvas width, canvas height) / 1080. corner and chip take an anchor corner (top-left, top-right, bottom-left, bottom-right) and strip an anchor edge (top, bottom, left, right); the other layouts take none. Except for free, the server derives rect and layer from the canvas: omit them, or send exactly what it derives. A page holds at most one full, center or wide card, one corner or chip card per corner, and one strip per edge (a card with presence may share an edge with a normal strip); a header takes the top edge's normal strip slot and a footer the bottom edge's, so a page holds at most one of each, no normal strip on that edge, and a card with presence may still share it. A corner or chip on an edge that holds a strip moves in past it by 120, and past a header or footer by 80. A card's tier decides its layouts (GET /api/card-types): core takes all nine, fullscreen takes full. params holds the placement's static properties (theme, location, titles, column definitions) and changes only with a republish. data names a card data document (GET/PUT /api/card-data/{key}) that holds the card's dynamic properties (menu sections, ticker items, KPI tiles); agents change it without a republish. With data, params may not carry dynamic properties; without it, params carry the whole configuration. Every string in params that begins with media: is a media reference, media:\u003cid\u003e, naming a ready image in this project that the card draws (spotlight people[].photo, product-grid products[].photo); a card never takes an image URL. Publish refuses an unknown card or major and invalid params (card_invalid), a layout, anchor, rect or layer the card may not carry (card_layout_invalid), cards that claim one place on the page (card_layout_conflict), a media reference that names no ready image of the project (card_media_invalid), and a bound key whose stored document the card rejects (card_data_invalid). The screens showing the placement are granted its media, and a live write approves pending media it names, as with a by:id selector. A card with a third-party feed (weather) reads it from the key the server derives from its static params.",
+      "description": "A built-in card the Player draws natively (clock, weather, menu board, ticker, KPI tiles and the rest of the vendored cards catalog, screenrig.cards.contract/v1). layout places it: full (the whole canvas), free (your own rect and layer), center (900 x 420), wide (the canvas inset 30 from the left and right and 80 from the top and bottom), header (the whole top edge, 80 high), footer (the whole bottom edge, 80 high), corner (270 square), chip (240 x 70) or strip (the whole edge, 120 high), in 1080p design units scaled by min(canvas width, canvas height) / 1080. corner and chip take an anchor corner (top-left, top-right, bottom-left, bottom-right) and strip an anchor edge (top, bottom, left, right); the other layouts take none. Except for free, the server derives rect and layer from the canvas, or from the frame displays cover: omit them, or send exactly what it derives. A page holds at most one full, center or wide card, one corner or chip card per corner, and one strip per edge (a card with presence may share an edge with a normal strip); a header takes the top edge's normal strip slot and a footer the bottom edge's, so a page holds at most one of each, no normal strip on that edge, and a card with presence may still share it. A corner or chip on an edge that holds a strip moves in past it by 120, and past a header or footer by 80. On a playlist with a format, displays is the frame the layout derives in (full is the frame, corner the frame's corner; free refuses displays), the card scale is the tile's min(width, height) / 1080 = 1 rather than derived from the frame, and two cards compete for a slot, or move in past each other's strips, only when their frames share a display (no displays is every display). A card's tier decides its layouts (GET /api/card-types): core takes all nine, fullscreen takes full. params holds the placement's static properties (theme, location, titles, column definitions) and changes only with a republish. data names a card data document (GET/PUT /api/card-data/{key}) that holds the card's dynamic properties (menu sections, ticker items, KPI tiles); agents change it without a republish. With data, params may not carry dynamic properties; without it, params carry the whole configuration. Every string in params that begins with media: is a media reference, media:\u003cid\u003e, naming a ready image in this project that the card draws (spotlight people[].photo, product-grid products[].photo); a card never takes an image URL. Publish refuses an unknown card or major and invalid params (card_invalid), a layout, anchor, rect or layer the card may not carry (card_layout_invalid), cards that claim one place on the page (card_layout_conflict), a media reference that names no ready image of the project (card_media_invalid), and a bound key whose stored document the card rejects (card_data_invalid). The screens showing the placement are granted its media, and a live write approves pending media it names, as with a by:id selector. A card with a third-party feed (weather) reads it from the key the server derives from its static params.",
       "properties": {
         "anchor": {
           "description": "Required for corner and chip (a corner) and strip (an edge); not allowed for full, free, center, wide, header and footer.",
@@ -516,6 +519,10 @@
           "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$",
           "type": "string"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays",
+          "description": "Playlists with a format only. The displays whose frame the layout derives in: full is the frame, corner the frame's corner, and so on. Ascending contiguous 1-based display numbers within 1..format.displays, such as [2] or [1, 2]. Absent is every display. Not allowed for layout free."
+        },
         "enter": {
           "$ref": "#/$defs/PrimitiveEnter"
         },
@@ -574,6 +581,18 @@
       ],
       "type": "object"
     },
+    "PlaylistDisplays": {
+      "description": "Playlists with a format only. The displays a primitive covers: ascending contiguous 1-based display numbers within 1..format.displays, such as [2], [1, 2] or [1, 2, 3]. The server derives rect as the union of those tiles; rect is omitted or exactly the derived value. Stored and echoed on read.",
+      "items": {
+        "maximum": 3,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "maxItems": 3,
+      "minItems": 1,
+      "type": "array",
+      "uniqueItems": true
+    },
     "PlaylistDurationAdvance": {
       "additionalProperties": false,
       "properties": {
@@ -595,6 +614,39 @@
       ],
       "type": "object"
     },
+    "PlaylistFormat": {
+      "additionalProperties": false,
+      "description": "The video wall a playlist is authored for: displays tiles, each 1920 x 1080 (landscape) or 1080 x 1920 (portrait), laid out in a row or a column. The canvas of n tiles of width w and height h is (n * w, h) for a row and (w, n * h) for a column, for example 5760 x 1080 for 3 landscape displays in a row and 1080 x 3840 for 2 portrait displays in a column. Every ordinary page's canvas width and height must equal it exactly, else 400 invalid_request at pages[i].canvas. Card scale on such a playlist is the tile's min(width, height) / 1080 = 1. A playlist with a format may be bound only to a screen whose wall has the same shape (displays = number of outputs, arrangement, portrait if and only if rotation is 90 or 270), else 409 playlist_format_mismatch: assignment, fleet assignment, schedule entries and takeover. A playlist without a format binds to any screen.",
+      "properties": {
+        "arrangement": {
+          "enum": [
+            "row",
+            "column"
+          ],
+          "type": "string"
+        },
+        "displays": {
+          "enum": [
+            2,
+            3
+          ],
+          "type": "integer"
+        },
+        "orientation": {
+          "enum": [
+            "landscape",
+            "portrait"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "displays",
+        "arrangement",
+        "orientation"
+      ],
+      "type": "object"
+    },
     "PlaylistIframePrimitiveWrite": {
       "additionalProperties": false,
       "properties": {
@@ -604,6 +656,9 @@
           ],
           "type": "string"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays"
+        },
         "enter": {
           "$ref": "#/$defs/PrimitiveEnter"
         },
@@ -626,7 +681,8 @@
           "type": "string"
         },
         "rect": {
-          "$ref": "#/$defs/PlaylistRect"
+          "$ref": "#/$defs/PlaylistRect",
+          "description": "Required unless displays is set. With displays, omit it or send the rect derived from them."
         },
         "src": {
           "format": "uri",
@@ -644,7 +700,6 @@
         "primitive",
         "src",
         "title",
-        "rect",
         "layer",
         "content_fit"
       ],
@@ -665,6 +720,9 @@
           ],
           "type": "string"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays"
+        },
         "dwell_ms": {
           "description": "Required on media_end image primitives. Forbidden on duration and application pages.",
           "maximum": 86400000,
@@ -693,7 +751,8 @@
           "type": "string"
         },
         "rect": {
-          "$ref": "#/$defs/PlaylistRect"
+          "$ref": "#/$defs/PlaylistRect",
+          "description": "Required unless displays is set. With displays, omit it or send the rect derived from them."
         },
         "selector": {
           "$ref": "#/$defs/PlaylistMediaSelector"
@@ -703,7 +762,6 @@
         "id",
         "primitive",
         "selector",
-        "rect",
         "layer",
         "content_fit"
       ],
@@ -1097,6 +1155,9 @@
           ],
           "type": "string"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays"
+        },
         "enter": {
           "$ref": "#/$defs/PrimitiveEnter"
         },
@@ -1127,7 +1188,8 @@
           "type": "string"
         },
         "rect": {
-          "$ref": "#/$defs/PlaylistRect"
+          "$ref": "#/$defs/PlaylistRect",
+          "description": "Required unless displays is set. With displays, omit it or send the rect derived from them."
         },
         "sources": {
           "items": {
@@ -1143,7 +1205,6 @@
         "primitive",
         "sources",
         "fallback_media_id",
-        "rect",
         "layer",
         "content_fit"
       ],
@@ -1266,6 +1327,9 @@
           ],
           "type": "string"
         },
+        "displays": {
+          "$ref": "#/$defs/PlaylistDisplays"
+        },
         "enter": {
           "$ref": "#/$defs/PrimitiveEnter"
         },
@@ -1299,7 +1363,8 @@
           "type": "string"
         },
         "rect": {
-          "$ref": "#/$defs/PlaylistRect"
+          "$ref": "#/$defs/PlaylistRect",
+          "description": "Required unless displays is set. With displays, omit it or send the rect derived from them."
         },
         "selector": {
           "$ref": "#/$defs/PlaylistMediaSelector"
@@ -1309,7 +1374,6 @@
         "id",
         "primitive",
         "selector",
-        "rect",
         "layer",
         "content_fit"
       ],
@@ -1321,6 +1385,10 @@
         "audio": {
           "$ref": "#/$defs/PlaylistAudioWrite"
         },
+        "format": {
+          "$ref": "#/$defs/PlaylistFormat",
+          "description": "Omitted means none: an ordinary playlist."
+        },
         "name": {
           "maxLength": 120,
           "minLength": 1,