@frontera-sdk/core 1.50.25 → 1.50.27

package/README.md

@@ -27,6 +27,27 @@ own routing themselves.
 
 ## Entry points
 
+### Embedded application lifecycle
+
+`useFronteraApp()` exposes `active` and `setUnsavedChanges(dirty)`. Use `active`
+to pause optional visible-only work; an inactive app may remain mounted, with
+its credentials refreshed. Inactivity does not cancel server-side operations.
+
+Report local draft changes explicitly, and report `false` only after the draft
+is saved or deliberately discarded. An app that never reports its state is
+treated as unknown when the platform is asked to release its session. This API
+does not implement saving for the app or provide recovery after a browser reload.
+
+The injected app-host bridge reports native push, replacement, traversal and
+fragment changes. A `frontera:host-navigate` request carries a `requestId` and
+relative app path; the bridge replaces the child location and responds with
+`frontera:navigation-ack` using the same ID. It does not add a second child history
+step for a navigation the host already owns. Both directions validate the
+expected origin and sender window. Older hosts may ignore the new lifecycle
+messages; older app-host scripts do not support acknowledged navigation.
+
+### Modules
+
 | Import | What it is |
 |---|---|
 | `@frontera-sdk/core/react` | `FronteraAppProvider`, `useFronteraApp`, and mode types |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/core",
-  "version": "1.50.25",
+  "version": "1.50.27",
   "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
   "keywords": [
     "frontera",

package/src/app-session.ts

@@ -112,6 +112,9 @@ export async function connectToSessionEndpoint(
     onTheme() {
       return () => {}
     },
+    onActivation() {
+      return () => {}
+    },
     dispose() {
       disposed = true
       if (timer !== undefined) clearTimer(timer)

package/src/bridge-client.ts

@@ -22,6 +22,8 @@ export interface BridgeSession {
   onToken(handler: (token: string) => void): () => void
   /** Subscribe to host palette / colour-scheme changes. */
   onTheme(handler: (theme: HostTheme) => void): () => void
+  /** Visibility changes do not revoke credentials or imply execution is paused. */
+  onActivation(handler: (active: boolean) => void): () => void
   dispose(): void
 }
 
@@ -84,6 +86,8 @@ export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSessi
   const stateHandlers = new Set<(s: Record<string, unknown>) => void>()
   const tokenHandlers = new Set<(t: string) => void>()
   const themeHandlers = new Set<(t: HostTheme) => void>()
+  const activationHandlers = new Set<(active: boolean) => void>()
+  let active = true
 
   return new Promise<BridgeSession>((resolve, reject) => {
     let settled = false
@@ -91,7 +95,7 @@ export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSessi
     const send = (message: AppMessage) => window.parent.postMessage(message, parentOrigin)
 
     const onMessage = (event: MessageEvent) => {
-      if (event.origin !== parentOrigin) return
+      if (event.origin !== parentOrigin || event.source !== window.parent) return
       if (!isHostMessage(event.data)) return
       const message = event.data
 
@@ -100,6 +104,7 @@ export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSessi
           if (settled) return
           settled = true
           clearTimeout(timer)
+          active = message.active ?? active
           resolve({
             init: message,
             send,
@@ -115,11 +120,17 @@ export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSessi
               themeHandlers.add(handler)
               return () => themeHandlers.delete(handler)
             },
+            onActivation(handler) {
+              activationHandlers.add(handler)
+              handler(active)
+              return () => activationHandlers.delete(handler)
+            },
             dispose() {
               window.removeEventListener('message', onMessage)
               stateHandlers.clear()
               tokenHandlers.clear()
               themeHandlers.clear()
+              activationHandlers.clear()
             },
           })
           break
@@ -138,6 +149,10 @@ export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSessi
             handler({ tokens: message.tokens, colorScheme: message.colorScheme })
           }
           break
+        case 'frontera:activation':
+          active = message.active
+          for (const handler of activationHandlers) handler(message.active)
+          break
         default:
           break
       }

package/src/bridge-protocol.ts

@@ -35,10 +35,14 @@ export interface BridgeInit {
    * own default.
    */
   path?: string
+  active?: boolean
 }
 
 export type HostMessage =
   | BridgeInit
+  | { type: 'frontera:host-ready' }
+  | { type: 'frontera:host-navigate'; requestId: string; path: string }
+  | { type: 'frontera:activation'; active: boolean }
   | { type: 'frontera:state'; state: Record<string, unknown> }
   | {
       type: 'frontera:theme'
@@ -50,7 +54,10 @@ export type HostMessage =
 
 export type AppMessage =
   | { type: 'frontera:ready' }
-  | { type: 'frontera:navigate'; path: string }
+  | { type: 'frontera:route-ready'; protocol: 1 }
+  | { type: 'frontera:navigate'; path: string; mode?: 'push' | 'replace' | 'traverse' | 'hash' | 'load' }
+  | { type: 'frontera:navigation-ack'; requestId: string; path: string }
+  | { type: 'frontera:unsaved'; dirty: boolean }
   | { type: 'frontera:resize'; height: number }
   | { type: 'frontera:state-write'; patch: Record<string, unknown> }
   | { type: 'frontera:error'; message: string; stack?: string }
@@ -60,6 +67,12 @@ export function isHostMessage(data: unknown): data is HostMessage {
   if (!data || typeof data !== 'object') return false
   const m = data as Record<string, unknown>
   switch (m.type) {
+    case 'frontera:host-ready':
+      return true
+    case 'frontera:host-navigate':
+      return typeof m.requestId === 'string' && isAppPath(m.path)
+    case 'frontera:activation':
+      return typeof m.active === 'boolean'
     case 'frontera:init':
       return typeof m.token === 'string' && typeof m.apiBaseUrl === 'string' && typeof m.appId === 'string'
     case 'frontera:state':
@@ -77,10 +90,16 @@ export function isAppMessage(data: unknown): data is AppMessage {
   if (!data || typeof data !== 'object') return false
   const m = data as Record<string, unknown>
   switch (m.type) {
+    case 'frontera:unsaved':
+      return typeof m.dirty === 'boolean'
+    case 'frontera:route-ready':
+      return m.protocol === 1
+    case 'frontera:navigation-ack':
+      return typeof m.requestId === 'string' && isAppPath(m.path)
     case 'frontera:ready':
       return true
     case 'frontera:navigate':
-      return typeof m.path === 'string'
+      return isAppPath(m.path) && (m.mode === undefined || ['push', 'replace', 'traverse', 'hash', 'load'].includes(m.mode as string))
     case 'frontera:resize':
       return typeof m.height === 'number' && Number.isFinite(m.height)
     case 'frontera:state-write':
@@ -93,3 +112,8 @@ export function isAppMessage(data: unknown): data is AppMessage {
       return false
   }
 }
+
+/** App locations are relative to the isolated app origin. */
+function isAppPath(path: unknown): path is string {
+  return typeof path === 'string' && path.startsWith('/') && !path.startsWith('//') && !path.includes('\\')
+}

package/src/create-frontera-app.tsx

@@ -2,6 +2,7 @@ import {
   Component,
   StrictMode,
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useState,
@@ -42,6 +43,10 @@ export interface FronteraAppValue {
   /** Everything the host said at handshake, including `path`. */
   init: BridgeInit
   client: FronteraClient
+  /** Whether this app is the visible platform surface. */
+  active: boolean
+  /** Report local work explicitly; unreported state remains unknown to the host. */
+  setUnsavedChanges(dirty: boolean): void
   /** Ask the platform to change its URL — the counterpart to `init.path`. */
   navigate(path: string): void
 }
@@ -383,11 +388,18 @@ function FronteraRoot({
   )
 
   useEffect(() => session.onTheme((theme) => applyHostTheme(theme)), [session])
+  const [active, setActive] = useState(init.active ?? true)
+  useEffect(() => session.onActivation(setActive), [session])
+  const setUnsavedChanges = useCallback((dirty: boolean) => {
+    if (mode === 'embedded') session.send({ type: 'frontera:unsaved', dirty })
+  }, [mode, session])
 
   const value: FronteraAppValue = {
     mode,
     init,
     client,
+    active,
+    setUnsavedChanges,
     navigate: (path) => {
       if (mode === 'embedded') session.send({ type: 'frontera:navigate', path })
     },