@shenora/react 0.14.0 → 0.15.0

package/dist/appLifecycle.d.ts

@@ -0,0 +1,50 @@
+import { type ShenoraEventBus } from './eventBus.js';
+/** The module these events are published under. */
+export declare const LIFECYCLE_MODULE = "SHENORA.LIFECYCLE";
+/** The app left the foreground. No payload. */
+export declare const LIFECYCLE_STOPPED = "STOPPED";
+/** The app came back, carrying an {@link AppLifecycleReport}. */
+export declare const LIFECYCLE_RESUMED = "RESUMED";
+/** What a {@link LIFECYCLE_RESUMED} event carries. */
+export interface AppLifecycleReport {
+    /**
+     * How long the app was away, or `null` when there was no preceding stop to measure from — a first
+     * launch, or a shell that reported only the resume.
+     *
+     * ⚠ **`null` is not `0`.** Zero would be a measurement; this is the absence of one. Treating them
+     * alike makes the first resume after launch skip the reconnect every other resume performs.
+     */
+    backgroundMilliseconds: number | null;
+}
+/** What {@link useAppLifecycle} watches for. Every handler is optional. */
+export interface AppLifecycleHandlers {
+    /** The app left the foreground. */
+    onStopped?: () => void;
+    /**
+     * The app came back. `backgroundMilliseconds` is null when there was nothing to measure.
+     *
+     * ⚠ Branch on a THRESHOLD rather than on the event: reconnecting on every resume makes switching
+     * apps expensive, and doing nothing makes a long absence look like a hung page.
+     */
+    onResumed?: (report: AppLifecycleReport) => void;
+}
+/**
+ * Run something when the app leaves the foreground and when it comes back.
+ *
+ * ```tsx
+ * useAppLifecycle({
+ *   onResumed: ({ backgroundMilliseconds }) => {
+ *     // A short trip to the notification shade costs nothing; a long one means the socket is gone.
+ *     if (backgroundMilliseconds === null || backgroundMilliseconds > 30_000) reconnect();
+ *   },
+ * });
+ * ```
+ *
+ * ⚠ On a shell that reports no lifecycle — the desktop, or a mobile app that did not compose
+ * `MobileAppLifecycle` — neither handler ever runs. There is no capability to branch on, because there
+ * is nothing to render differently: an app that also wants a visibility signal should use
+ * `document.visibilitychange`, which works everywhere including a plain browser tab.
+ */
+export declare function useAppLifecycle(handlers: AppLifecycleHandlers, options?: {
+    eventBus?: ShenoraEventBus;
+}): void;

package/dist/appLifecycle.js

@@ -0,0 +1,65 @@
+/**
+ * When the APP went away and came back — and how long it was gone, which is the part this page cannot
+ * measure itself. Mirrors `Shenora.Modules.Platform.AppLifecycle`, pinned by `WireMirrorTests`.
+ *
+ * 🔴 **For "am I on screen", use `document.visibilitychange`.** It fires on both mobile shells and is
+ * the web platform's own answer; this would only arrive later and over IPC. What it adds is the two
+ * things a hidden document genuinely cannot know:
+ *
+ * 1. **How long it was away, on a clock that was not throttled.** A backgrounded page's timers are
+ *    throttled and its process may be frozen, so a `Date.now()` delta across the gap is unreliable —
+ *    and the duration is what the decision actually turns on. Three seconds in the notification shade
+ *    needs no reconnect; forty minutes means the socket is dead.
+ * 2. **That this was the user leaving the APP**, rather than anything else that can hide a document.
+ *
+ * ⚠ It reports; it does not act. Reconnecting, re-probing or refetching is yours — the host has no way
+ * to know what this page was holding.
+ */
+import { useEffect, useRef } from 'react';
+import { eventBus as defaultEventBus } from './eventBus.js';
+/** The module these events are published under. */
+export const LIFECYCLE_MODULE = 'SHENORA.LIFECYCLE';
+/** The app left the foreground. No payload. */
+export const LIFECYCLE_STOPPED = 'STOPPED';
+/** The app came back, carrying an {@link AppLifecycleReport}. */
+export const LIFECYCLE_RESUMED = 'RESUMED';
+/**
+ * Run something when the app leaves the foreground and when it comes back.
+ *
+ * ```tsx
+ * useAppLifecycle({
+ *   onResumed: ({ backgroundMilliseconds }) => {
+ *     // A short trip to the notification shade costs nothing; a long one means the socket is gone.
+ *     if (backgroundMilliseconds === null || backgroundMilliseconds > 30_000) reconnect();
+ *   },
+ * });
+ * ```
+ *
+ * ⚠ On a shell that reports no lifecycle — the desktop, or a mobile app that did not compose
+ * `MobileAppLifecycle` — neither handler ever runs. There is no capability to branch on, because there
+ * is nothing to render differently: an app that also wants a visibility signal should use
+ * `document.visibilitychange`, which works everywhere including a plain browser tab.
+ */
+export function useAppLifecycle(handlers, options = {}) {
+    const eventBus = options.eventBus ?? defaultEventBus;
+    // Read through a ref so a handler rebuilt every render — the normal case for inline arrows — does not
+    // tear down and rebuild the subscription, losing any transition that lands in the gap.
+    const latest = useRef(handlers);
+    latest.current = handlers;
+    useEffect(() => {
+        const subscriptions = [
+            eventBus.subscribe(LIFECYCLE_MODULE, LIFECYCLE_STOPPED, () => {
+                latest.current.onStopped?.();
+            }),
+            eventBus.subscribe(LIFECYCLE_MODULE, LIFECYCLE_RESUMED, (message) => {
+                // ⚠ Absent rather than 0 when the host sent nothing usable — the same distinction the payload
+                // documents, preserved here so a missing field cannot read as "away for no time".
+                const reported = message.payload?.backgroundMilliseconds;
+                latest.current.onResumed?.({
+                    backgroundMilliseconds: typeof reported === 'number' ? reported : null,
+                });
+            }),
+        ];
+        return () => subscriptions.forEach((off) => off());
+    }, [eventBus]);
+}

package/dist/backNavigation.d.ts

@@ -0,0 +1,101 @@
+import type { ShenoraBridge } from './bridge.js';
+import { type ShenoraEventBus } from './eventBus.js';
+import { BaseModuleService } from './moduleService.js';
+/** The module a back press is published under, and the one this page answers on. */
+export declare const BACK_MODULE = "SHENORA.BACK";
+/** The event type carrying one press. */
+export declare const BACK_PRESSED = "PRESSED";
+/** The payload of a {@link BACK_PRESSED} event. */
+export interface BackNavigationEvent {
+    /**
+     * Identifies this press. Return it verbatim — an answer naming a press that already timed out is
+     * refused rather than applied to the one after it.
+     */
+    token: string;
+}
+/** What `RESOLVE` answers with. */
+export interface BackNavigationResult {
+    /**
+     * False when the press was no longer waiting — it timed out, or was already answered.
+     *
+     * ⚠ Not an error; the platform has already taken the press. But seeing it repeatedly means this
+     * page's back handling is not running at all, and the user is getting the platform default.
+     */
+    accepted: boolean;
+}
+interface BackRequests {
+    INTERCEPT: {
+        enabled: boolean;
+    };
+    RESOLVE: {
+        token: string;
+        handled: boolean;
+    };
+}
+/**
+ * Typed client for the host's `SHENORA.BACK` module (`BackNavigationModule`).
+ *
+ * ⚠ On a shell with no system back gesture — iOS, desktop — {@link intercept} is accepted and no press
+ * ever arrives, because there is nothing to intercept. Harmless, but indistinguishable from a broken
+ * handler, so use {@link useBackNavigation}'s `supported` to decide what to RENDER.
+ */
+export declare class BackNavigationAccess extends BaseModuleService<BackRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /**
+     * Take or release responsibility for the back gesture.
+     *
+     * ⚠ Ask again after a navigation that replaces the document: the host cannot know the new page wanted
+     * it, and asking twice is harmless.
+     */
+    intercept(enabled: boolean): Promise<void>;
+    /**
+     * Answer one press. `handled: true` consumes it; `false` sends it to the platform, which is how a page
+     * at the root of its own history lets the user leave.
+     */
+    resolve(token: string, handled: boolean): Promise<BackNavigationResult>;
+}
+/** What {@link useBackNavigation} reports back. */
+export interface BackNavigationHandle {
+    /** The typed client. Stable across renders. */
+    back: BackNavigationAccess;
+    /**
+     * This shell has a system back gesture at all. False on iOS and the desktop — read from the ready
+     * handshake rather than sniffed from the user agent (D36).
+     */
+    supported: boolean;
+}
+/**
+ * Handle the system back gesture for as long as the component is mounted.
+ *
+ * Your handler returns `true` if it consumed the press and `false` to let the user leave. The
+ * subscription, the answer and the release on unmount are all done for you — which matters, because
+ * every one of those is a way to silently end up back at "the back button quits the app".
+ *
+ * ```tsx
+ * const { supported } = useBackNavigation(() => {
+ *   if (playerExpanded) { collapsePlayer(); return true; }   // consumed
+ *   if (history.length > 1) { history.back(); return true; } // consumed
+ *   return false;                                            // at the root — let them exit
+ * });
+ * ```
+ *
+ * ⚠ **The handler may be async**, for a page that has to ask something before deciding — but the host
+ * gives it a bounded window (2 seconds by default) and then hands the press to the platform. Do not put
+ * a confirmation dialog behind it.
+ *
+ * ⚠ A THROWING handler answers `false`, so a bug in your own code leaves the user able to leave rather
+ * than trapping them in an app whose back button does nothing.
+ *
+ * ⚠ **Several components may use this at once**, which is the layered case above: the most recently
+ * mounted handler is asked FIRST — a modal before the player behind it — and the first to return `true`
+ * claims the press. The host is told once, however many components are listening.
+ *
+ * ⚠ **Ask again after a navigation that replaces the document.** The host has no document-lifecycle
+ * signal to reset on, so a new page that does not re-register leaves the old interception standing and
+ * every press waits the full timeout before reaching the platform.
+ */
+export declare function useBackNavigation(onBack: () => boolean | Promise<boolean>, options?: {
+    client?: BackNavigationAccess;
+    eventBus?: ShenoraEventBus;
+}): BackNavigationHandle;
+export {};

package/dist/backNavigation.js

@@ -0,0 +1,189 @@
+/**
+ * The page's half of the host's `SHENORA.BACK` module — Android's system back gesture, offered to this
+ * page before the platform acts on it. Mirrors `Shenora.Modules.Platform.BackNavigationModule`, pinned
+ * by `WireMirrorTests`.
+ *
+ * 🔴 **This is the one shell primitive whose absence is a BROKEN APP rather than a missing feature.**
+ * Unhandled, Android's back finishes the activity from whatever screen the user is on — so a user two
+ * levels into your UI is dumped to the home screen instead of going back one step. There is no web API
+ * for it: `popstate` fires only for history the page itself pushed, and it cannot tell you that the
+ * press would otherwise EXIT.
+ *
+ * ⚠ **Every press must be answered**, including the ones you do not want. An unanswered press is held
+ * for the host's timeout and then goes to the platform — so a page that stops answering does not freeze
+ * back, it silently reverts to quitting the app.
+ */
+import { useEffect, useRef } from 'react';
+import { eventBus as defaultEventBus } from './eventBus.js';
+import { useShellInfo } from './hooks.js';
+import { BaseModuleService } from './moduleService.js';
+import { ShellCapabilities } from './types.js';
+/** The module a back press is published under, and the one this page answers on. */
+export const BACK_MODULE = 'SHENORA.BACK';
+/** The event type carrying one press. */
+export const BACK_PRESSED = 'PRESSED';
+/**
+ * Typed client for the host's `SHENORA.BACK` module (`BackNavigationModule`).
+ *
+ * ⚠ On a shell with no system back gesture — iOS, desktop — {@link intercept} is accepted and no press
+ * ever arrives, because there is nothing to intercept. Harmless, but indistinguishable from a broken
+ * handler, so use {@link useBackNavigation}'s `supported` to decide what to RENDER.
+ */
+export class BackNavigationAccess extends BaseModuleService {
+    constructor(bridge) {
+        super(BACK_MODULE, bridge);
+    }
+    /**
+     * Take or release responsibility for the back gesture.
+     *
+     * ⚠ Ask again after a navigation that replaces the document: the host cannot know the new page wanted
+     * it, and asking twice is harmless.
+     */
+    intercept(enabled) {
+        return this.send('INTERCEPT', { payload: { enabled } });
+    }
+    /**
+     * Answer one press. `handled: true` consumes it; `false` sends it to the platform, which is how a page
+     * at the root of its own history lets the user leave.
+     */
+    resolve(token, handled) {
+        return this.send('RESOLVE', { payload: { token, handled } });
+    }
+}
+/**
+ * Handle the system back gesture for as long as the component is mounted.
+ *
+ * Your handler returns `true` if it consumed the press and `false` to let the user leave. The
+ * subscription, the answer and the release on unmount are all done for you — which matters, because
+ * every one of those is a way to silently end up back at "the back button quits the app".
+ *
+ * ```tsx
+ * const { supported } = useBackNavigation(() => {
+ *   if (playerExpanded) { collapsePlayer(); return true; }   // consumed
+ *   if (history.length > 1) { history.back(); return true; } // consumed
+ *   return false;                                            // at the root — let them exit
+ * });
+ * ```
+ *
+ * ⚠ **The handler may be async**, for a page that has to ask something before deciding — but the host
+ * gives it a bounded window (2 seconds by default) and then hands the press to the platform. Do not put
+ * a confirmation dialog behind it.
+ *
+ * ⚠ A THROWING handler answers `false`, so a bug in your own code leaves the user able to leave rather
+ * than trapping them in an app whose back button does nothing.
+ *
+ * ⚠ **Several components may use this at once**, which is the layered case above: the most recently
+ * mounted handler is asked FIRST — a modal before the player behind it — and the first to return `true`
+ * claims the press. The host is told once, however many components are listening.
+ *
+ * ⚠ **Ask again after a navigation that replaces the document.** The host has no document-lifecycle
+ * signal to reset on, so a new page that does not re-register leaves the old interception standing and
+ * every press waits the full timeout before reaching the platform.
+ */
+export function useBackNavigation(onBack, options = {}) {
+    const { client, eventBus = defaultEventBus } = options;
+    const shell = useShellInfo();
+    const supported = shell?.capabilities?.includes(ShellCapabilities.backNavigation) ?? false;
+    const back = client ?? defaultClient();
+    // 🔴 The handler is read through a ref rather than depended on. An inline arrow — which is how this
+    // hook will always be called — is a new function every render, so depending on it would unsubscribe
+    // and resubscribe on every render, and a press landing in that gap is answered by NOBODY. It then
+    // sits until the host's timeout and goes to the platform, i.e. the app quits mid-interaction.
+    const handler = useRef(onBack);
+    handler.current = onBack;
+    // 🔴 INTERCEPT UNLESS THE SHELL IS KNOWN NOT TO HAVE IT — never "only when known to have it".
+    // `useShellInfo` is a synchronous cache read that does NOT re-render when the handshake lands later,
+    // and child effects run before parent effects — so a page that calls `notifyReady()` from a root
+    // effect mounts every child while `shell` is still undefined. Gating on `supported` there would
+    // silently never intercept, for the whole session, and back would quit the app from every screen:
+    // the exact defect this hook exists to prevent, arriving from the most ordinary bootstrap. Asking to
+    // intercept on a shell that turns out to have no back gesture costs nothing — no press ever arrives.
+    const declined = shell !== undefined && !supported;
+    useEffect(() => {
+        if (declined)
+            return;
+        return register(back, eventBus, handler);
+    }, [back, eventBus, declined, handler]);
+    return { back, supported };
+}
+/**
+ * The live handlers, newest LAST — module scope on purpose.
+ *
+ * 🔴 **Two components may use the hook at once, and that is the shape D79 describes** ("close the
+ * expanded player, then walk the history"). Per-component `intercept(true)/(false)` calls would make
+ * the *first* unmount switch interception off for everyone still mounted, and back would quit the app
+ * with every remaining handler still subscribed and looking healthy. So the host is told once, on
+ * 0→1, and told again only on 1→0.
+ */
+const handlers = [];
+let release;
+function register(back, eventBus, handler) {
+    handlers.push(handler);
+    if (handlers.length === 1)
+        release = subscribe(back, eventBus);
+    return () => {
+        const at = handlers.indexOf(handler);
+        if (at >= 0)
+            handlers.splice(at, 1);
+        if (handlers.length === 0) {
+            release?.();
+            release = undefined;
+        }
+    };
+}
+function subscribe(back, eventBus) {
+    // ⚠ A rejection HERE means interception was never established — the adopter did half the host-side
+    // pair, or a payload key drifted. Silence would leave `supported` true, the handlers subscribed and
+    // back quitting the app, which is the failure the kit's own registration doc lectures about. The
+    // teardown call below is the opposite case and is correctly silent.
+    back.intercept(true).catch((error) => {
+        console.warn('[shenora] the host refused to hand over the back gesture, so back will quit the app. Check that '
+            + 'the host called AddShenoraBackNavigation() AND constructed MobileBackNavigation.', error);
+    });
+    const unsubscribe = eventBus.subscribe(BACK_MODULE, BACK_PRESSED, async (message) => {
+        const token = message.payload?.token;
+        if (typeof token !== 'string')
+            return;
+        // Innermost first: the most recently mounted component is the one on top of the user's screen, so
+        // a modal gets the press before the player behind it. The first to claim it wins.
+        // Snapshot: a handler may unmount another while deciding, and splicing the live array mid-walk
+        // would skip its neighbour.
+        let handled = false;
+        for (const entry of [...handlers].reverse()) {
+            if (handled)
+                break;
+            try {
+                handled = await entry.current();
+            }
+            catch {
+                // Answering false is the safe direction: the user can still leave. Swallowing the press here
+                // would be a back button that does nothing, which is not recoverable from the outside.
+                handled = false;
+            }
+        }
+        try {
+            const answer = await back.resolve(token, handled);
+            if (answer && answer.accepted === false) {
+                // The host had already given the press to the platform. Not an error — but a page seeing this
+                // is a page whose back handling is not running, and this is the only place that is visible
+                // without a device attached.
+                console.warn('[shenora] a back press was answered too late — the platform already took it.');
+            }
+        }
+        catch {
+            // The host went away mid-answer; the press is the platform's now, which is the safe direction.
+        }
+    });
+    return () => {
+        unsubscribe();
+        // Releasing is what stops a page whose handlers have all unmounted from holding every press for
+        // the host's whole timeout before the platform gets it. Silent: the one moment this reliably
+        // rejects is a host that has already gone, which is exactly when a page unmounts.
+        back.intercept(false).catch(() => { });
+    };
+}
+let shared;
+function defaultClient() {
+    shared ?? (shared = new BackNavigationAccess());
+    return shared;
+}

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export { useDropZone, DROP_ZONE_MODULE, type DropZoneFileDrop, type UseDropZoneO
 export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, type ShenoraQueryResult, } from './hooks.js';
 export { FileDialogs, useFileDialogs, type FileDialogFilter, type FileDialogOptions, type OpenFileOptions, type OpenFolderOptions, type SaveFileOptions, type FileDialogResult, type FileDialogsHandle, } from './fileDialogs.js';
 export { ClipboardAccess, useClipboard, PNG_IMAGE, HTML, type ClipboardContent, type ClipboardHandle, } from './clipboard.js';
+export { BackNavigationAccess, useBackNavigation, BACK_MODULE, BACK_PRESSED, type BackNavigationEvent, type BackNavigationResult, type BackNavigationHandle, } from './backNavigation.js';
+export { useAppLifecycle, LIFECYCLE_MODULE, LIFECYCLE_STOPPED, LIFECYCLE_RESUMED, type AppLifecycleReport, type AppLifecycleHandlers, } from './appLifecycle.js';
 export { installDevInterceptor, type DevInterceptorOptions, type DevIpcEntry, type DevEventEntry, } from './devInterceptor.js';
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';
 export { parseManifest, pickMediaSource, nextSegment, segmentMimeType, codecsFromInitSegment, remoteSegmentUrl, SEGMENT_REMOTE_PREFIX, } from './segmentStream.js';

package/dist/index.js

@@ -21,6 +21,12 @@ export { FileDialogs, useFileDialogs, } from './fileDialogs.js';
 // The native clipboard, for the two things navigator.clipboard cannot do: FILES, and access with no
 // user gesture. The client half of the host's SHENORA.CLIPBOARD module.
 export { ClipboardAccess, useClipboard, PNG_IMAGE, HTML, } from './clipboard.js';
+// Android's system back gesture. Unhandled it FINISHES THE ACTIVITY from any screen, so a page with
+// its own navigation must answer it — the client half of the host's SHENORA.BACK module.
+export { BackNavigationAccess, useBackNavigation, BACK_MODULE, BACK_PRESSED, } from './backNavigation.js';
+// When the APP went away and came back, and how long it was gone — the part a throttled, possibly
+// frozen page cannot measure. For "am I on screen", use document.visibilitychange instead.
+export { useAppLifecycle, LIFECYCLE_MODULE, LIFECYCLE_STOPPED, LIFECYCLE_RESUMED, } from './appLifecycle.js';
 export { installDevInterceptor, } from './devInterceptor.js';
 // Addressing local content the page cannot reach itself. Pure functions, not hooks.
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';

package/dist/types.d.ts

@@ -106,6 +106,14 @@ export declare const ShellCapabilities: {
     readonly savePicker: "savePicker";
     readonly secondaryWindows: "secondaryWindows";
     readonly tray: "tray";
+    /**
+     * The shell has a system BACK gesture this page can take responsibility for — Android only. Absent
+     * on iOS and the desktop, which have none.
+     *
+     * ⚠ Branch on it. Asking to intercept where there is no gesture is accepted and no press ever
+     * arrives, which looks exactly like a handler that is broken.
+     */
+    readonly backNavigation: "backNavigation";
     /**
      * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
      * file manager. No web API expresses this, so it is the one part of the clipboard worth branching on.

package/dist/types.js

@@ -76,6 +76,14 @@ export const ShellCapabilities = {
     savePicker: 'savePicker',
     secondaryWindows: 'secondaryWindows',
     tray: 'tray',
+    /**
+     * The shell has a system BACK gesture this page can take responsibility for — Android only. Absent
+     * on iOS and the desktop, which have none.
+     *
+     * ⚠ Branch on it. Asking to intercept where there is no gesture is accepted and no press ever
+     * arrives, which looks exactly like a handler that is broken.
+     */
+    backNavigation: 'backNavigation',
     /**
      * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
      * file manager. No web API expresses this, so it is the one part of the clipboard worth branching on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenora/react",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "React client for Shenora hosts on Windows, Android and iOS: correlated invoke/send/subscribe over the desktop postMessage bridge or the MAUI HybridWebView transport, typed module services, host-backed stores, and hooks for request tracking and media playback. Drop zones and window commands are desktop-only, because the capabilities are. Ships a browser fallback for pure-UI development.",
   "license": "MIT",
   "author": "Jiarong Gu",