docs: Add special case warning for fullscreen condition (#2373)

docs/configuration/conditions.md

@@ -92,7 +92,17 @@ conditions:
 
 ## `fullscreen`
 
-Matches based on whether the card is in fullscreen.
+Matches based on whether the card (or media within it) is in fullscreen mode.
+
+> [!WARNING]
+> When fullscreen is entered via a video player's built-in controls (rather than
+> the card's own fullscreen [action](actions/custom/README.md) or menu button),
+> the browser fullscreens the video element itself rather than the card. Any
+> automation action that replaces that video element (e.g. switching substreams)
+> will immediately exit fullscreen. A partial workaround may be to use the
+> card's fullscreen action instead. See [Fullscreen with HD substream
+> switching](../examples.md?id=fullscreen-with-hd-substream-switching) for an
+> approach that combines substream switching with the card's fullscreen.
 
 ```yaml
 conditions:

docs/examples.md

@@ -43,6 +43,12 @@ This example will automatically turn on the first configured substream when the
 card is put in fullscreen mode, and turn off the substream when exiting
 fullscreen mode.
 
+> [!WARNING]
+> When fullscreen is entered via a video player's built-in controls (rather than
+> the card's fullscreen menu button), automation actions that replace _that_ video
+> element (e.g. switching substreams from one video to another) will immediately exit fullscreen (as the browser sees the video the user clicked on be destroyed). See the
+> [fullscreen condition](configuration/conditions.md?id=fullscreen) for details.
+
 ```yaml
 type: custom:advanced-camera-card
 cameras:
@@ -77,6 +83,55 @@ automations:
         advanced_camera_card_action: live_substream_off
 ```
 
+### Fullscreen with display mode and substream switching
+
+This example adds a custom menu button that switches to single display mode,
+activates the HD substream, and enters card fullscreen — all in a single tap.
+An automation restores the grid layout and substream when fullscreen is exited.
+This is useful in [grid](configuration/live.md) layouts where the card's
+standard fullscreen button would show all cameras rather than a single HD
+stream.
+
+```yaml
+type: custom:advanced-camera-card
+cameras:
+  - camera_entity: camera.office
+    dependencies:
+      cameras:
+        - office_hd
+  - camera_entity: camera.office_hd
+    title: Office HD
+    id: office_hd
+    capabilities:
+      disable_except:
+        - substream
+live:
+  display:
+    mode: grid
+elements:
+  - type: custom:advanced-camera-card-menu-icon
+    icon: mdi:fullscreen
+    title: Fullscreen HD
+    tap_action:
+      - action: custom:advanced-camera-card-action
+        advanced_camera_card_action: display_mode_select
+        display_mode: single
+      - action: custom:advanced-camera-card-action
+        advanced_camera_card_action: live_substream_on
+      - action: custom:advanced-camera-card-action
+        advanced_camera_card_action: fullscreen
+automations:
+  - conditions:
+      - condition: fullscreen
+        fullscreen: false
+    actions:
+      - action: custom:advanced-camera-card-action
+        advanced_camera_card_action: live_substream_off
+      - action: custom:advanced-camera-card-action
+        advanced_camera_card_action: display_mode_select
+        display_mode: grid
+```
+
 ### Responding to key input
 
 In addition to a handful of reconfigurable [built-in keyboard shortcuts](./usage/keyboard-shortcuts.md), `automations` can be used to take any action based on any keyboard input. These examples use [`key` conditions](./configuration/conditions.md?id=key) to assess keyboard state before taking action.