@mentra/engine 0.1.0-beta.0

package/build/services/LocalDisplayManager.d.ts

@@ -0,0 +1,139 @@
+/**
+ * LocalDisplayManager
+ *
+ * Phone-side arbiter for display requests originating from LOCAL miniapps
+ * (the @mentra/miniapp SDK). Mirrors the user-facing behavior of the cloud
+ * DisplayManager (cloud/packages/cloud/src/services/layout/DisplayManager6.1.ts)
+ * for the features that matter on the phone:
+ *
+ *   - boot message ("Starting <AppName>…") with a bounded window
+ *   - durationMs auto-clear
+ *   - core-app vs background-app arbitration with a background lock
+ *
+ * Scope is deliberately local-only. Cloud-originated displays are untouched
+ * and may race with local displays during dev; that's acceptable per plan
+ * (agents/local-display-manager-plan.md).
+ *
+ * Display pacing is NOT done here. A JS-side ~300ms throttle used to live in
+ * this class, but JS timers (and therefore the throttle's trailing flush) do
+ * not fire on schedule while the iOS app is suspended in the background — so
+ * under streaming captions, updates accumulated and then flushed in a burst on
+ * the next wake. Pacing + last-wins coalescing now live in the native per-device
+ * queue (e.g. G2's event-driven EvenHub queue), which drains off the same BLE
+ * events that wake the process. This class forwards every request straight
+ * through; the native layer collapses redundant frames per display target.
+ *
+ * The remaining BgTimer use (boot window, durationMs expiry) is timing that
+ * does not need sub-second background fidelity.
+ */
+import type { SceneElementInput } from "../utils/display/scene";
+export interface DisplayPayload {
+    view?: "main" | "dashboard" | string;
+    /** Legacy layout (sugar / old bundles / cloud shapes). Either this or `scene`. */
+    layout?: {
+        layoutType: string;
+        [key: string]: unknown;
+    };
+    /** Scene elements from display.render(). Either this or `layout`. */
+    scene?: SceneElementInput[];
+    durationMs?: number;
+}
+/** Outcome delivered to an awaiting render() call (REQUEST_RESULT payload). */
+export interface DisplayRequestResult {
+    status: "displayed" | "blocked";
+    degraded?: boolean;
+    dropped?: string[];
+    reason?: string;
+}
+export type DisplayRequestResolver = (result: DisplayRequestResult) => void;
+declare class LocalDisplayManager {
+    private static instance;
+    private coreApp;
+    private coreAppDisplay;
+    private currentDisplay;
+    private backgroundLock;
+    private bootingApp;
+    private bootQueue;
+    private expiryTimerId;
+    /** Reconnect-replay subscription state (attachToRuntime). */
+    private runtimeAttached;
+    private glassesWasConnected;
+    private unsubscribeGlassesStatus;
+    /** Injectable for tests. */
+    private now;
+    private constructor();
+    static getInstance(): LocalDisplayManager;
+    /**
+     * A new local miniapp just mounted. Start the boot window.
+     * Calling this for a different pkg while another is booting cancels the
+     * previous boot.
+     */
+    onMount(packageName: string, displayName: string): void;
+    /**
+     * Mark which miniapp is the "core" (foreground) app. Pass null when no local
+     * miniapp is foreground.
+     */
+    onCoreAppChange(packageName: string | null): void;
+    /**
+     * A local miniapp is going away. Clean up all state associated with it.
+     */
+    onUnmount(packageName: string): void;
+    /**
+     * A miniapp requested a display. Routes through boot queue, arbitration,
+     * and throttle. This is the only public entry point for miniapp display
+     * traffic on the local path.
+     *
+     * `resolve`, when provided (render() requests), is guaranteed to be called
+     * exactly once with the request's outcome — including for requests parked in
+     * the boot queue (resolved when drained or superseded).
+     */
+    request(packageName: string, payload: DisplayPayload, resolve?: DisplayRequestResolver): void;
+    private arbitrateAndSend;
+    private sendNow;
+    /**
+     * Send a scene through SceneRenderer. On positioning devices this emits a
+     * SceneFrame; on degrade devices SceneRenderer hands back a legacy layout
+     * that rides the existing (unchanged) DisplayProcessor path.
+     */
+    private sendScene;
+    private sendToNative;
+    private handleExpiry;
+    private tryRestoreCoreDisplay;
+    private sendClear;
+    private cancelBoot;
+    private endBoot;
+    /**
+     * Re-push a previously-captured on-glasses frame (e.g. the display a boot
+     * window overwrote). Mirrors tryRestoreCoreDisplay: the saved event is already
+     * processed, and any remaining duration is recomputed from its expiry.
+     */
+    private restoreDisplay;
+    /**
+     * Subscribe to glasses connection state so the current owner's frame is
+     * replayed after a reconnect. Safe to call repeatedly; attaches once. Wired
+     * from MantleManager next to displayProcessor.attachToRuntime().
+     */
+    attachToRuntime(): void;
+    /**
+     * Re-push the current on-glasses frame after a device recovery. Scenes replay
+     * from SceneRenderer's retained state (create-based, epoch-bumped); legacy
+     * frames re-send their processed event. Expired frames don't come back.
+     */
+    replayCurrent(): void;
+    private clearExpiryTimer;
+    /** Injected clock — tests only. */
+    _setNowForTest(fn: () => number): void;
+    /** Wipe state — tests only. */
+    _resetForTest(): void;
+    /** Read-only state snapshot — tests only. */
+    _peekForTest(): {
+        coreApp: string | null;
+        currentDisplayPkg: string | null;
+        bgLockPkg: string | null;
+        isBooting: boolean;
+    };
+}
+declare const localDisplayManager: LocalDisplayManager;
+export default localDisplayManager;
+export { LocalDisplayManager };
+//# sourceMappingURL=LocalDisplayManager.d.ts.map

package/build/services/LocalDisplayManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalDisplayManager.d.ts","sourceRoot":"","sources":["../../src/services/LocalDisplayManager.ts"],"names":[],"mappings":"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"}