"/admin/screen/{screenId}":
    parameters:
        - in: path
          name: screenId
          required: true
          schema: { type: string }
    get:
        tags: [Screens]
        operationId: getScreen
        summary: Fetch a screen (not implemented)
        description: |
            **Not implemented.** Handler currently throws — calls return a 500.
            Endpoint is registered to reserve the path; expect this to land later.
        responses:
            "500":
                description: Always — handler is a stub.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
    put:
        tags: [Screens]
        operationId: updateScreen
        summary: Update a screen (incomplete)
        description: |
            Mutates a screen's settings. **Currently incomplete** — the handler
            throws after fetching the screen because the target-user wiring isn't
            done. Calls return a 500.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            settings:
                                type: object
                                description: "`ScreenSettings` payload."
                                additionalProperties: true
                        additionalProperties: true
        responses:
            "500":
                description: Handler currently throws.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
    delete:
        tags: [Screens]
        operationId: deleteScreen
        summary: Delete a screen (broken stub)
        description: |
            **Broken stub** — `deleteScreen` in
            `cloud/src/CloudAdminApi.ts` calls `Cloud.deleteScreen` but
            never sends a response on success, so requests **hang until
            the client times out** unless the underlying delete throws.
        deprecated: true
        responses:
            "504":
                description: Handler never responds on success — gateway / client timeout.
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]

"/admin/screen/{screenId}/session":
    parameters:
        - in: path
          name: screenId
          required: true
          schema: { type: string }
    put:
        tags: [Screens]
        operationId: updateScreenMediaSession
        summary: Update the screen's media session
        description: |
            Mutates the active media session on a screen — pause / resume,
            seek, change product. Used by the Arda screen-control panel.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            playbackState:
                                type: string
                                enum: [playing, paused, ended]
                            currentTimeMs: { type: integer }
                            mediaProductId:
                                type: string
                                description: Switch the screen to a different product.
                            bigMediaId: { type: string }
                        additionalProperties: true
        responses:
            "200":
                description: Updated screen.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
