diff --git a/requirements/specifications/lifecycle/index.md b/requirements/specifications/lifecycle/index.md index 091cbe377..5ae71cb67 100644 --- a/requirements/specifications/lifecycle/index.md +++ b/requirements/specifications/lifecycle/index.md @@ -56,24 +56,27 @@ CPU cycles, which allows the platform to optimise memory consumption. *Waking* an app refers to copying a Sleeping app back into the memory space of a compatible process so that it resumes where it left off. + +## 2. Table of Contents - [1. Overview](#1-overview) -- [2. Lifecycle States](#2-lifecycle-states) - - [2.1. Initializing](#21-initializing) - - [2.2. Running](#22-running) - - [2.3. Active](#23-active) - - [2.4. Suspended](#24-suspended) - - [2.5. Sleeping](#25-sleeping) -- [3. Getting the current state](#3-getting-the-current-state) -- [4. Lifecycle State Transitions](#4-lifecycle-state-transitions) - - [4.1. Initializing an app](#41-initializing-an-app) - - [4.2. Activating an app](#42-activating-an-app) - - [4.3. Deactivating an app](#43-deactivating-an-app) - - [4.4. Suspending an app](#44-suspending-an-app) - - [4.5. Resuming an app](#45-resuming-an-app) - - [4.6. Putting an app to sleep](#46-putting-an-app-to-sleep) - - [4.7. Waking an app from sleep](#47-waking-an-app-from-sleep) - - [4.8. Destroying an app](#48-destroying-an-app) - - [4.9. Terminating an app](#49-terminating-an-app) +- [2. Table of Contents](#2-table-of-contents) +- [3. Lifecycle States](#3-lifecycle-states) + - [3.1. Initializing](#31-initializing) + - [3.2. Running](#32-running) + - [3.3. Active](#33-active) + - [3.4. Suspended](#34-suspended) + - [3.5. Sleeping](#35-sleeping) +- [4. Getting the current state](#4-getting-the-current-state) +- [5. Lifecycle State Transitions](#5-lifecycle-state-transitions) + - [5.1. Initializing an app](#51-initializing-an-app) + - [5.2. Activating an app](#52-activating-an-app) + - [5.3. Deactivating an app](#53-deactivating-an-app) + - [5.4. Suspending an app](#54-suspending-an-app) + - [5.5. Resuming an app](#55-resuming-an-app) + - [5.6. Putting an app to sleep](#56-putting-an-app-to-sleep) + - [5.7. Waking an app from sleep](#57-waking-an-app-from-sleep) + - [5.8. Destroying an app](#58-destroying-an-app) + - [5.9. Terminating an app](#59-terminating-an-app) - [6. Create Parameters](#6-create-parameters) - [7. Core SDK APIs](#7-core-sdk-apis) - [7.1. Application Interface](#71-application-interface) @@ -86,7 +89,7 @@ a compatible process so that it resumes where it left off. - [8. Lifecycle Configuration](#8-lifecycle-configuration) -## 2. Lifecycle States +## 3. Lifecycle States Firebolt platforms **MUST** support running one or more apps concurrently. The platform **MUST** manage transition of apps from state to state. @@ -95,7 +98,7 @@ A Firebolt app, once running, **MUST** be in one of several states and **MUST NOT** be in more than one state at a time. As an app changes states the platform will invoke specific app-provided -transition methods, see [Transitions](#4-lifecycle-state-transitions), for more +transition methods, see [Transitions](#5-lifecycle-state-transitions), for more on this. ![Lifecycle States](../../images/specifications/lifecycle/lifecycle-states.png) @@ -121,7 +124,7 @@ on this. | ✔ | Normal access | | ? | Unknown | -### 2.1. Initializing +### 3.1. Initializing This is the initial state an app exists from the moment it starts receiving CPU @@ -141,8 +144,8 @@ Apps in this state **MUST NOT** have access to the audio-video decoder. Apps in this state **MUST NOT** use the media pipeline. -See [Initializing an app](#41-initializing-an-app) for more information. -### 2.2. Running +See [Initializing an app](#51-initializing-an-app) for more information. +### 3.2. Running This state allows an app to be running and ready to go, but not actively part @@ -164,14 +167,14 @@ Apps in this state **MUST NOT** have access to the audio-video decoder. Apps in this state **MUST NOT** use the media pipeline and the platform **MUST** tear down any Media Pipeline sessions associated with this app. -### 2.3. Active +### 3.3. Active This state allows an app to be presented as part of the user-perceptible experience. To determine if an app is the *primary* experience, e.g. fullscreen, etc., see -[Presentation](./presentation.md#3-display). +[Presentation](./presentation.md#4-display). It is a platform decision as to how many apps may be in this state at once. @@ -194,7 +197,7 @@ Apps in this state **SHOULD** reduce memory usage, if possible. When an app transitions to this state, the platform **MUST** dispatch the `Lifecycle.onStateChanged` notification with the current state. -### 2.4. Suspended +### 3.4. Suspended This state allows an app to remain in memory and consume fewer resources. @@ -216,7 +219,7 @@ Apps in this state **SHOULD** further reduce memory usage (more so than in the **TODO**:: add all the transition pre-requisites, e.g. Apps **MUST** only enter this state from the `SUSPENDED` state, via the `sleep()` interface. -### 2.5. Sleeping +### 3.5. Sleeping This state allows an app to be copied from memory to local storage and then @@ -242,14 +245,14 @@ If a platform supports copying sleeping apps memory out of RAM then: > > Finally, the app and its container **MAY** be removed from memory and have > other resources released as well. -## 3. Getting the current state +## 4. Getting the current state The Lifecycle module **MUST** provide a `state` property API that returns the current lifecycle state of the app. If an app is in a transtition from one state to another, then it **MUST** be considered in the state *before* the transition until such time as the app's -implementation of the [transition](#4-lifecycle-state-transitions) has returned +implementation of the [transition](#5-lifecycle-state-transitions) has returned and the platfrom has finshed the transition. The `state` API **MUST** have a corresponding `onStateChanged` notification. @@ -264,7 +267,7 @@ The `state` API must have one of the following values: Note that the `onStateChanged` notification **MUST** never be dispatched for the `Sleeping` state since it would not be received anyway. -## 4. Lifecycle State Transitions +## 5. Lifecycle State Transitions There are several state transitions where the app and the platform need to interact to ensure the transition goes smoothly. @@ -338,7 +341,7 @@ By providing an implementation of the `xrn:firebolt:capability:lifecycle:activatible` interface, an app can influence how resources are managed during these state transitions. See [Activity Interface](#82-activity-interface) for more info. -### 4.1. Initializing an app +### 5.1. Initializing an app Once an app is loaded it **MUST** be initialized immediately. @@ -394,7 +397,7 @@ Example Launch Parameters: Once the `create` method returns the app **MUST** be immediately transitioned to the `RUNNING` state. -### 4.2. Activating an app +### 5.2. Activating an app Activating an app transitions it to the `ACTIVE` state so that it becomes part @@ -418,9 +421,9 @@ If the app is not loaded, then the platform **MUST** [load](undefined) it first. If the app is not initialized, the platform **MUST** -[initialize](#41-initializing-an-app) it first. +[initialize](#51-initializing-an-app) it first. -If the app is suspended, then it **MUST** be [resumed](#45-resuming-an-app) +If the app is suspended, then it **MUST** be [resumed](#55-resuming-an-app) first. At this point, the app **MUST** be in the `RUNNING` state. @@ -468,7 +471,7 @@ the user with content that fulfills the `intent` without additional loading screens in the app's UX. **TODO**: Discuss ^^ -### 4.3. Deactivating an app +### 5.3. Deactivating an app Closing an app transitions it to the `RUNNING` state, so that it is no longer @@ -502,13 +505,13 @@ complete, and the remainder of this section does not apply. If an app is already performing an `activate()` transition, the platform **MUST** wait for the activate call to succeed or fail and then skip the -remaining [activation steps](#42-activating-an-app). +remaining [activation steps](#52-activating-an-app). -If an app is currently [initializing](#41-initializing-an-app), the platform +If an app is currently [initializing](#51-initializing-an-app), the platform **MUST** wait for initialization to succeed or fail and then skip any activation that may have been pending. -If an app is currently in a [destroy](#48-destroying-an-app) transition then +If an app is currently in a [destroy](#58-destroying-an-app) transition then the app cannot be closed and the platform **MUST NOT** close it, and the remainder of this section does not apply. @@ -534,7 +537,7 @@ decoders. The platform **MAY** begin to transition the app out of view as soon as `deactivate()` is called. -### 4.4. Suspending an app +### 5.4. Suspending an app Suspending an app transitions it to the `SUSPENDED` state, where it is no @@ -579,14 +582,14 @@ Since every app **MUST** provide the > moved to the `SUSPENDED` state. > > If the app times out or makes a `suspendError` call, then the app **MUST** be -> [destroyed](#48-destroying-an-app). +> [destroyed](#58-destroying-an-app). During the `suspend()` transition, the app: > **MUST** deallocate any graphics surface. > > **SHOULD** reduce memory usage, if possible. -### 4.5. Resuming an app +### 5.5. Resuming an app Resuming an app allows it to reallocate graphics composition and reload any @@ -623,7 +626,7 @@ terminated. During the `resume()` transition, apps **SHOULD** reallocate graphics composition and other necessary resources. -### 4.6. Putting an app to sleep +### 5.6. Putting an app to sleep TBD @@ -632,14 +635,14 @@ Firebolt apps that have permission to use the `Sleepable.sleep()`. TODO: if you don't call provide, we won't do this. -### 4.7. Waking an app from sleep +### 5.7. Waking an app from sleep TBD Firebolt apps that have permission to use the `xrn:firebolt:capability:lifecycle:sleepable` capability **MUST** implement `Sleepable.wake()`. -### 4.8. Destroying an app +### 5.8. Destroying an app Destroying an app transitions it out of memory, so that it is no longer using @@ -671,7 +674,7 @@ Since every app **MUST** provide the > > If the app times out or makes an `destroyError` call, then the app **MUST** > be terminated. -### 4.9. Terminating an app +### 5.9. Terminating an app Terminating an app removes it from memory without dispatching any state @@ -684,7 +687,7 @@ Terminating an app results in removing it from memory and all resources held by the app and it's container being freed up. Platforms **MAY** terminate an app when needed but **SHOULD NOT** do this in -place of graceful [destroying](#48-destroying-an-app). +place of graceful [destroying](#58-destroying-an-app). ## 6. Create Parameters The `CreateParameters` type is an object with the following properties: diff --git a/requirements/specifications/lifecycle/presentation.md b/requirements/specifications/lifecycle/presentation.md index 70b754e5d..95add4178 100644 --- a/requirements/specifications/lifecycle/presentation.md +++ b/requirements/specifications/lifecycle/presentation.md @@ -1,7 +1,5 @@ # App Presentation -need to write this up... - Document Status: Working Draft See [Firebolt Requirements Governance](../../governance.md) for more info. @@ -18,22 +16,37 @@ See [Firebolt Requirements Governance](../../governance.md) for more info. ## 1. Overview -TBD... +This document describes the requirements that Firebolt platforms and Firebolt +applications must fulfill when managing App Presention. *App Presentation* +refers to the display, focus, and navigational aspects of an App. + +The *display* of an app refers to it its visibility and size. + +Whether an app has an *overlay* refers to any other apps or UX being presented +on top of the app. + +Apps that are presented to users by the platform may receive *navigation* +intents, which are like deep links from the platform. + + +## 2. Table of Contents - [1. Overview](#1-overview) -- [2. Focus](#2-focus) -- [3. Display](#3-display) - - [3.1. Display vs Lifecycle](#31-display-vs-lifecycle) -- [4. Overlay](#4-overlay) - - [4.1. 4.1 Overlay vs Focus](#41-41-overlay-vs-focus) -- [5. Background Audio](#5-background-audio) -- [6. Picture-in-Picture Video](#6-picture-in-picture-video) +- [2. Table of Contents](#2-table-of-contents-) +- [3. Focus](#3-focus) +- [4. Display](#4-display) + - [4.1. Display vs Lifecycle](#41-display-vs-lifecycle) +- [5. Loading Screen](#5-loading-screen) + - [5.1. Platform-provided Loading Screen](#51-platform-provided-loading-screen) + - [5.2. App-provided Loading Screen](#52-app-provided-loading-screen) + - [5.3. When to use a loading screen](#53-when-to-use-a-loading-screen) +- [6. Overlay](#6-overlay) + - [6.1. 4.1 Overlay vs Focus](#61-41-overlay-vs-focus) - [7. Navigation](#7-navigation) -- [8. Platform-provided Loading Screen](#8-platform-provided-loading-screen) -- [9. App-provided Loading Screen](#9-app-provided-loading-screen) -- [10. When to use a loading screen](#10-when-to-use-a-loading-screen) +- [8. Background Audio](#8-background-audio) +- [9. Picture-in-Picture Video](#9-picture-in-picture-video) -## 2. Focus +## 3. Focus The `Presentation` module **MUST** have a `focus` boolean property that returns whether or not the app has input, e.g. RCU, focus. @@ -42,7 +55,7 @@ whether or not the app has input, e.g. RCU, focus. As a property, this API also has an `onFocusChanged` notification. -## 3. Display +## 4. Display The `Presentation` module **MUST** have a `display` string property that returns one of the following values: @@ -59,7 +72,7 @@ returns one of the following values: **TODO**: an app could be offscreen & scaled. If a scaled or thumbnailed app goes offscreen, it's now offscreen. -### 3.1. Display vs Lifecycle +### 4.1. Display vs Lifecycle Each Lifecycle state only supports certain display states: | Lifecycle | Supported Displays | @@ -71,10 +84,66 @@ Each Lifecycle state only supports certain display states: | `sleeping` | `none`, `loading` | -See [Picture-in-picture](#6-picture-in-picture-video) and [Background -Audio](#5-background-audio) for exceptions to this. +See [Picture-in-picture](#9-picture-in-picture-video) and [Background +Audio](#8-background-audio) for exceptions to this. + +## 5. Loading Screen +In order to manage user expectations, Firebolt platforms **MAY** display +loading screens to end users when an app is going to be activated. Loading +Screens may be rendered either by the platform, the app, or both, depending on +Capability configuration. + +### 5.1. Platform-provided Loading Screen + +Most apps will leverage a platform-provided loading screen. + +If an app provides the `xrn:firebolt:capability:presentation:loading-screen` +capability, then the platform **MAY** use the app-provided loading screen, in +which case, the rest of the section does not apply. + +The loading screen **SHOULD** include a loading image referenced in the app's +manifest and cached on the device. + +The loading screen **MUST** be displayed when the user attempts to launch the +app. + +The loading screen **MUST** stay displayed until the app becomes active, or +launching is cancelled. + +The presentation state of the app **MUST** be `LOADING` for the entire time the +loading screen is displayed. + +See [Lifecycle](./index.md) for more info on launching. -## 4. Overlay +### 5.2. App-provided Loading Screen + +If an app provides the `xrn:firebolt:capability:presentation:loading-screen` +capability, then the platform **MAY** invoke this capability in some +situations. + +If the app is in the [Initializing](./index.md#51-initializing-an-app) state or +the create transition w/ `preload: false` then it **MUST** be made visible at +the end of the `Application.create()` transition. + +If the app is in any other state or transition, then it **MUST** be made +visible at the beginning of the `activate()` transition. + +The presentation state of the app **SHOULD NOT** be `none` at any time during +the `activate()` transition. + +See [Lifecycle](./index.md) for more info on loading and activating apps. + +### 5.3. When to use a loading screen + +It is up to each platform to determine when a loading screen is useful. + +Platforms **SHOULD** consider displaying a loading screen for: + +- app cold launch +- app wake from sleep + + +## 6. Overlay The `Presentation` module **MUST** have an `overlay` string property that returns one of the following values: @@ -84,41 +153,17 @@ returns one of the following values: | `blocking` | There is a significantly sized UX covering a majority of the app. | | `none` | There is nothing covering the app. | -### 4.1. 4.1 Overlay vs Focus +### 6.1. 4.1 Overlay vs Focus | Focus | Overlay | | ----- | ----------------------- | | true | none | | false | partial, blocking, none | -## 5. Background Audio - -When an app has this capability, it **MAY** be put into the `none` display -state while in the `active` Lifecycle state. - -If an app has the `xrn:firebolt:capability:media:background-audio`, then it can -keep playing audio/video when the app is in the `none` display state and the -audio will be played for the user. - -TODO: do we want background apps to have a gfx surface? that means they'd be in -'offscreen' display and using more memory TODO: we probably want to support -both modes here. -## 6. Picture-in-Picture Video - -When an app has the `xrn:firebolt:capability:media:picture-in-picture` -capability, it **MAY** be put into the `none` display state while in the -`active` Lifecycle state. - -If an app has the `xrn:firebolt:capability:media:picture-in-picture`, then it -can keep playing audio/video when the app is in the `none` display state and -the audio & video will be presented to the user in bounding box determined by -the platform. Note that this does not include the entire UX of the app, just -the active media pipeline. - ## 7. Navigation Typically navigation is handled either when the app is activated, via the -`intent` parameter of the [`activate` method](./index.md#42-activating-an-app), -or by internal input within the app. +`intent` parameter of the [`activate()` +method](./index.md#52-activating-an-app), or by internal input within the app. There are other times when the platform needs to inform an app of a user's intent to navigate when the app is already `ACTIVE`, e.g. when a voice command @@ -166,48 +211,24 @@ To invoke an app's `navigateTo` provider API the platform **MUST**: > `intent` in some other way -## 8. Platform-provided Loading Screen - -Most apps will leverage a platform-provided loading screen. - -If an app provides the `xrn:firebolt:capability:presentation:loading-screen` -capability, then the platform **MAY** use the app-provided loading screen, in -which case, the rest of the section does not apply. - -The loading screen **SHOULD** include a loading image referenced in the app's -manifest and cached on the device. - -The loading screen **MUST** be displayed when the user attempts to launch the -app. - -The loading screen **MUST** stay displayed until the app becomes active, or -launching is cancelled. - -The presentation state of the app **MUST** be `LOADING` for the entire time the -loading screen is displayed. - -See [Lifecycle](./index.md) for more info on launching. -## 9. App-provided Loading Screen - -If an app provides the `xrn:firebolt:capability:presentation:loading-screen` -capability, then the platform **MAY** invoke this capability in some -situations. - -If the app is being created w/ preload: false then: - -Apps that provide the loading screen capability **MUST** be made visible at the -end of the `Application.create()` transition, rather than at the end of the -activate transition. - -**TODO**: if an app is in the running state already, show it at the beginning -of `activate()` +## 8. Background Audio +If an app has the `xrn:firebolt:capability:media:background-audio`, then it can +keep playing audio/video when the app is in the `none` display state and the +audio will be played for the user. -The presentation state of the app **SHOULD NOT** be `none` at any time during -the `activate()` transition. +When an app has this capability, it **MAY** be put into the `none` display +state while in the `active` Lifecycle state. -See [Lifecycle](./index.md) for more info on loading and activating apps. +TODO: do we want background apps to have a gfx surface? that means they'd be in +'offscreen' display and using more memory TODO: we probably want to support +both modes here. -## 10. When to use a loading screen +## 9. Picture-in-Picture Video +If an app has the `xrn:firebolt:capability:media:picture-in-picture`, then it +can keep playing audio/video when the app is in the `none` display state and +the audio & video will be presented to the user in bounding box determined by +the platform. Note that this does not include the entire UX of the app, just +the active media pipeline. -- cold launch -- wake from sleep +When an app has this capability, it **MAY** be put into the `none` display +state while in the `active` Lifecycle state. diff --git a/src/js/github.io/markdown.mjs b/src/js/github.io/markdown.mjs index a7641d3e5..b0e78a06e 100644 --- a/src/js/github.io/markdown.mjs +++ b/src/js/github.io/markdown.mjs @@ -145,10 +145,6 @@ function wrapText(data) { if (word.match(block_regex)) { throw "Found > in line: " + line } - - if (i === 0) { - console.error(`First word of line: ${word}`) - } if (word && !word.match(/^\s+$/)) { let len = word.length + 1 // .replace(/\(.*?\)/g, '')