Page History

Given an app is loaded, I want to tell the app what level of loading is expected

...so that the app can load the correct level of resources for the intended use case, no more, no less.

WHEN an app is loaded

THEN the platform MUST be able to return the desired deep-link to the app as soon as the app calls Discovery.getNavigationIntent

AND there MUST be a valid, non null value for the intent

WHEN an app is loaded

  AND the platform is doing a standard pre-load to Paused

THEN the intent MUST be a PreloadIntent

AND the data.graphics value of the intent MUST be true

AND the platform MUST fire a more specific intent some time before dispatching an onActivate notification

WHEN an app is loaded

  AND the platform is doing a pre-load to Suspended

THEN the intent MUST be a PreloadIntent

AND the data.graphics value of the intent MUST be false

AND the platform MAY fire a more specific intent some time before dispatching an onResume notification

WHEN an app is loaded

  AND the platform is doing a cold launch to Paused and then Active

  AND the platform doesn't have a specific deep-link for the launch

THEN the intent MUST be a LaunchIntent

AND the platform MAY activate the app or not

WHEN an app is loaded

  AND the platform is doing a cold launch to Paused and then Active

  AND the platform has a specific deep-link for the launch

THEN the intent MUST represent the the deep-link that is desired*

AND the platform MAY activate the app or not 

*Complete list of NavigationIntents is out of scope for this document.

Given an app has initialized Firebolt, I want to immediately send the next state change

...so that the app can continue to load.

WHEN an app is loading / initializing

THEN the app MUST call Lifecycle.ready() as soon as it has set up it's Firebolt event listeners

AND the app MUST NOT wait for any asynchronous or CPU intensive process to complete before doing so

WHEN an app calls Lifecycle.ready()

  AND it has already called Lifecycle.ready()

THEN the platform MUST send an error response

WHEN an app calls Lifecycle.ready()

  AND it has already registered for the Lifecycle.onStart notification

  AND the platform is doing a cold launch or pre-load to Paused

THEN the platform MUST send a Lifecycle.onStart notification to the app as quickly as possible

WHEN an app calls Lifecycle.ready()

  AND it has already registered for the  Lifecycle.onSuspended notification

  AND the platform is doing a pre-load to Suspended

THEN the platform MUST send a Lifecycle.onSuspended notification to the app as quickly as possible 

Given an app is loaded, but not yet active, I want it to render a good user experience as quickly as possible

...so that the platform can make it visible any time and the user will have a visual cue that the app is starting up

WHEN an app is Paused (2)

THEN the platform MAY make the app visible at any point (3a)

AND the platform MUST notify the app of this (1, 8b, 4b)

AND the app MUST present graphics which provide a good* user experience as quickly as possible (2)

AND any animations for said experience MUST be ready, but not actively drawing frames (2)

Given an app moves into the foreground, it should have loaded and rendered any deep-links as quickly as possible

... so that the user can get to their intended use case quickly.

WHEN an app receives an onNavigateTo notification

AND the app SHOULD immediately begin to fetch and compose the appropriate UX (3b)

Given an app moves into the foreground, it should be made visible quickly and with a good user experience

...so that the user can be presented with the app's experience.

WHEN an app is launched with a deep-link

  AND the app is already in the Paused state

THEN the platform MUST dispatch a Discovery.onNavigateTo with the new intent

AND the platform MUST wait to make the app visible until after the onNavigateTo is sent (3a)

AND the platform MUST wait to make the app visible until after the has drawn something* (3a)

AND the shared requirements below... 

WHEN an app is launched without a deep-link

  AND the app is already in the Paused state

  AND the most recent intent was a PreloadIntent

THEN the platform MUST dispatch a Discovery.onNavigateTo with a LaunchIntent

AND the platform MUST wait to make the app visible until after the onNavigateTo is sent (3a)

AND the platform MUST wait to make the app visible until after the has drawn something* (3a)

AND the shared requirements below...

WHEN an app is launched without a deep-link

  AND the app is already in the Paused state

  AND the most recent intent was not a PreloadIntent

THEN the platform MUST wait to make the app visible until after the has drawn something* (3a)

AND the shared requirements below...

Shared requirements:

AND the app MUST now be in the Active state

AND the platform  MUST notify the app of this transition (3b)

AND the app MAY call getNavigationIntent() to check if there is an intent that it missed the event for (3b)

AND the app SHOULD immediately begin to fetch and compose the appropriate UX if it has not already (3b)

AND the app SHOULD render a UX indicated by the most recent Intent within a reasonable time (3c)

*detection of when the app has "drawn something" is an engineering effort, not in scope for this document.

Given an app moves out of the foreground, it should remain in it's current UX state for a short amount of time

...so that the user can navigate back quickly to the same experience

WHEN an app is explicitly exited, e.g. by an exit option in the app's navigation

THEN the platform MUST make the app invisible (4a)

AND the app MUST be moved to the Paused state (2)

AND the app MUST be informed of the exit (4b)

AND the app MUST keep it's most recent UX displayed on the screen (4b)

AND the platform MUST stop and destroy any audio / video sessions belong to the app (2)

AND the platform MAY decide to exit to app for any reason*

AND the rest of the acceptance criteria from requirement #3

*Details out of scope for this doc

Given an app has been paused for a while, I want to tell the app to clear out it's last UX and prepare for a new intent

...so that the app can take less memory and be ready with a good user experience.

WHEN an app has been paused for a set amount of time*

THEN the platform MAY send a "Preload" intent via the onNavigateTo notification

AND the rest of the acceptance criteria from requirement #3

*Details out of scope for this doc

Given an app is loaded but not active, I want to ensure it does not negatively impact performance of active apps

...so that the user has a fast, responsive experience

WHEN an app is Paused (2)

    AND the app is no longer needed*

THEN the app MUST be moved to the Suspended state (6)

AND the app MUST be informed of the transition (5)

AND the app MUST deallocate it's EGL surface (5)

AND the app MUST deallocate GPU textures and other GPU memory (5)

AND the app MUST deallocate any other memory not necessary for a hot launch (5)

AND the platform SHOULD reduce CPU cycles given to the app (5)

AND the platform SHOULD reduce platform resources given to the app's graphics surface, e.g. destroy or set it 1x1 (5)

AND the platform MAY reduce Network bandwidth available to the app (5)

AND the platform MAY decide to suspend the app for any reason*

*Details out of scope for this doc

Given the user launches a suspended app, I want to bring it back to the running state and activate it

...so that the user has a faster launch time

WHEN an app is launched

    AND the app is in the Suspended state

THEN the platform MUST resize the app's graphics plane to full screen (8a)

AND the app MUST be moved to the Paused state (8a)

AND the app MUST be informed that is is resuming (8b)

AND the rest of the acceptance criteria from requirement #3

AND the rest of the acceptance criteria from requirement #4

Given the user launches many apps, I want to keep the platform running smoothly and manage resources

...so that the user has a fast, responsive experience

WHEN an app is Suspended

    AND the platform needs more resources*

THEN the platform MAY hibernate if appropriate* (7a)

OR the platform MAY destroy the app if appropriate* (10)

OR the platform MAY leave the app Suspended if appropriate*

*Details out of scope for this document

Given a platform pre-loads an app due to contractual obligations, I want to load it directly to suspended

...so that we don't waste platform resources on apps that might never be launched

WHEN an app is loaded

    AND the platform wants to save additional resources

    AND the app supports these criteria

    AND the platform decides to do so*

THEN the platform MUST load the app directly into the Suspended state (9)

AND the app MUST be informed (5)

AND the app SHOULD NOT allocate it's EGL surface (5)

AND the app SHOULD NOT allocate GPU textures and other GPU memory (5)

AND the app SHOULD NOT allocate any other memory not necessary for a hot launch (5)

AND the platform SHOULD reduce CPU cycles given to the app (5)

AND the platform SHOULD reduce platform resources given to the app's graphics surface, e.g. destroy or set it 1x1 (5)

AND the platform MAY reduce Network bandwidth available to the app (5)

AND the platform MAY decide to suspend the app for any reason*

*Details out of scope for this doc

Given the user launches many apps, I want to keep as many of them pre-loaded as possible

...so that the user has a faster launch time

WHEN a Suspended app is a candidate for hibernation*

    AND the platform has determined that the app has released sufficient resources*

THEN the app MUST be moved to the Hibernated state (7a)

AND the app MUST be informed of the transition (7b) TODO is this a SHOULD?

AND the platform MUST execute the MemCR routine to store the app's state (7c)

AND the platform MUST terminate the original app process and free up its resources TODO is this right?

Given a user launches a hibernated app, I want to restore it to memory and activate it

...so that the user has a faster launch time

WHEN an app is launched

    AND the app is in the Hibernated state

THEN the platform MUST execute the reverse MemCR routine to restore the app's state (7d)

AND the app MUST be moved to the Suspended state (7d)

AND the rest of the acceptance criteria from requirement #11

Given my app is loading, I want access to the Firebolt ENV variables

WHEN JS execution begins (0)

THEN

document._firebolt.environment

MUST already have the ENV values set.

Given Lifecycle.onStart happens, I want to be notified via Window.load

WHEN Lifecycle.onActivate is invoked on WPE

THEN Window.load MUST be fired

P0

Given Lifecycle.onActivate happens, I want to be notified via Document.visibilityChange

WHEN Lifecycle.onActivate is invoked on WPE

THEN Document.visibilityState MUST be fired

AND

document.visibilityState = 'visible'

AND Discovery.getNavigationIntent() MUST return the current Intent

WHEN the Intent is not null

THEN my app MUST do all of the responsibilities denoted in Lifecycle.activate() (requirement #4)

WHEN the Intent is a Launch Intent

  AND the platform had previously dispatched an Lifecycle.onPause notification to the app

THEN any HTMLMediaElements that were paused by WPE MUST have their play method invoked by WPE

P2

Given Lifecycle.onPause happens, I want to be notified via standard HTML events

WHEN Lifecycle.onPause is invoked

THEN Document.visibilityState MUST be fired

AND

document.visibilityState = 'hidden'

AND any HTMLMediaElements MUST have their pause method invoked by WPE

THEN Window.freeze MUST be fired

AND Canvas.onContextLost MUST be fired on all Canvas elements

P1

Given Lifecycle.onResume happens, I want to be notified via standard HTML events

WHEN Lifecycle.onResume is invoked on WPE

THEN Window.resume MUST be fired

P1

Given Lifecycle.onHibernate happens, I want to not worry about it

WHEN Lifecycle.onHibernate is invoked on WPE

THEN the WPE browser MUST handle all necessary work 

P1

Given Lifecycle.onRestore happens,  I want to not worry about it

THEN the WPE browser MUST handle all necessary work