From 68d67c819225b085e6e56ab5af5a0314cc14a789 Mon Sep 17 00:00:00 2001
From: Jeremy LaCivita <jeremy.lacivita@comcast.com>
Date: Sat, 30 Sep 2023 20:25:44 -0400
Subject: [PATCH] fix: Aligning Presentation w/ Lifecycle

---
 .../specifications/lifecycle/presentation.md  | 44 ++++++++++++++-----
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/requirements/specifications/lifecycle/presentation.md b/requirements/specifications/lifecycle/presentation.md
index cf3694e99..5d2791e0b 100644
--- a/requirements/specifications/lifecycle/presentation.md
+++ b/requirements/specifications/lifecycle/presentation.md
@@ -1,19 +1,43 @@
 # App Presentation
 need to write this up...
 
-## 1. States
-
-- fullscreen
-- obscured
-- offscreen
-- scaled
-- thumbnail
-- loading
+## 1. Display
+The `Presentation` module **MUST** have a `display` string property that returns one of the following values:
+
+| Value | Description |
+|-------|-------------|
+| `FULLSCREEN` | The app is displayed such that the dimensions fill the entire screen |
+| `OFFSCREEN`  | The app is not displayed on the screen at all |
+| `SCALED`     | The app is displayed at a size smaller than the entire screen but at least 25% of the width or height |
+| `THUMBNAIL` | The app is displayed at a size smaller than 25% of the width or height of the entire screen |
+| `LOADING` | The platform is displaying a loading screen while  the app loads | 
+
+### 1.1 Display vs Lifecycle
+Each Lifecycle state only supports certain display states:
+
+| Lifecycle | Supported Displays |
+|-------|-------------|
+| `FOREGROUND` | `FULLSCREEN`, `SCALED` |
+| `BACKGROUND` | `FULLSCREEN`, `SCALED`, `THUMBNAIL` |
+| `STARTED`    | `OFFSCREEN` |
+| `SUSPENDED`  |             |
+
+See [Off-screen Video](#2-offscreen-video) for an exception to this.
+
+## 2. Overlay
+The `Presentation` module **MUST** have an `overlay` string property that returns one of the following values:
+
+| Value | Description |
+|-------|-------------|
+| `ICON` | There is an informative icon, e.g. volume, on top of the app. |
+| `BAND`  | There is a horizontal overlay at the top or bottom of the app. |
+| `SIDEBAR`     | There is a vertical sidebar covering less than 33% of the app on one side. |
+| `BLOCKED` | There is a significantly sized UX covering a majority of the app. |
 
 ## 2. Off-screen Video
-If an app has the `xrn:firebolt:capability:presentation:offscreen-audio` or `-video` capability, then it can keep playing video/audio.
+If an app has the `xrn:firebolt:capability:presentation:offscreen-audio` or `-video` capability, then it can keep playing video/audio when the app is off-screen.
 
-Need a transition interface, e.g. `PresentationManager.hide()` to allow app to tear down video.
+When an app has this capability, it **MAY** be put into the `OFFSCREEN` display state while in the `BACKGROUND` Lifecycle state.
 
 ## 3. Platform-provided Loading Screen
 Most apps will leverage a platform-provided loading screen.