@mentra/engine 0.1.0-beta.0

package/build/stores/apps.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Engine apps store — runtime state of installed and local applets.
+ *
+ * The OEM-facing API: subscribe to the running set, install/uninstall
+ * miniapps, start/stop them. The store delegates install plumbing to
+ * AppRegistry, and exposes hooks (`useApps`, `useStart`, `useStop`,
+ * `useRefresh`, `useStopAll`) that the host UI can read.
+ *
+ * Source of `apps`:
+ *   - Local: appRegistry.getInstalledMiniapps()    (always)
+ */
+import { AsyncResult, Result } from "typesafe-ts";
+import type { ClientApp } from "../types/applet";
+export interface StartOptions {
+    skipNavigation?: boolean;
+}
+export interface AppStoreHooks {
+    /**
+     * A start was blocked because the app is hardware-incompatible. Engine made
+     * the decision (and raised the `version_incompatible` notification); the host
+     * renders its branded alert here.
+     */
+    onIncompatibleBlocked?: (app: ClientApp) => void;
+    /**
+     * A start was blocked because the app requires the on-device STT model
+     * (declared at registration — see AppRegistry.installOfflineApp) and none is
+     * installed. Engine decided via its model manager; the host renders the
+     * alert / settings navigation here.
+     */
+    onMissingSpeechModel?: (app: ClientApp) => void;
+    /**
+     * An open request passed the gates — fired on EVERY open, including
+     * re-opening an already-running app, so the host's navigation / open
+     * animation always plays.
+     */
+    onOpenRequested?: (app: ClientApp, opts?: StartOptions) => void;
+}
+export declare function installAppStoreHooks(hooks: AppStoreHooks): void;
+interface AppStatusState {
+    apps: ClientApp[];
+    /**
+     * Source of truth for which app is foregrounded in the Compositor overlay.
+     * The per-app `foregrounded` boolean is derived from this in `projectApps`
+     * so a refresh can never drop the flag when an app is transiently missing
+     * from one of the two refresh passes (local-only then merged). See
+     * `projectApps` / `setForeground` / `clearForeground`.
+     */
+    foregroundedPackage: string | null;
+    refresh: () => Promise<void>;
+    /** Resolves true if the app actually started; false if a host gate aborted it or its JS context failed to spawn. */
+    start: (app: ClientApp, opts?: StartOptions) => Promise<boolean>;
+    stop: (packageName: string) => Promise<void>;
+    setForeground: (packageName: string) => Promise<void>;
+    clearForeground: () => void;
+    stopAll: () => AsyncResult<void, Error>;
+    install: (url: string, opts?: {
+        versionOverride?: string;
+    }) => AsyncResult<void, Error>;
+    uninstall: (packageName: string, version?: string) => AsyncResult<void, Error>;
+    saveScreenshot: (packageName: string, screenshot: string) => Promise<void>;
+    setHiddenStatus: (packageName: string, status: boolean) => void;
+    getHiddenStatus: (packageName: string) => boolean;
+    /** Replace the whole apps array. Hosts use this when their extra source changes. */
+    setApps: (apps: ClientApp[]) => void;
+}
+export declare const DUMMY_APPLET: ClientApp;
+export type OrderMap = Record<string, number>;
+export declare const saveAppsOrder: (orderMap: OrderMap) => Result<void, Error>;
+export declare const getAppsOrder: () => Result<OrderMap, Error>;
+export declare const sortAppsByPackageNamePriority: (a: ClientApp, b: ClientApp) => number;
+export declare const saveLastOpenTime: (packageName: string) => void;
+export declare const getLastOpenTime: (packageName: string) => number;
+export declare const sortAppsByLastOpenTime: <T extends {
+    packageName: string;
+}>(apps: T[]) => Promise<T[]>;
+export declare const useAppStatusStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AppStatusState>>;
+export declare const useApps: () => ClientApp[];
+export declare const useStart: () => (app: ClientApp, opts?: StartOptions) => Promise<boolean>;
+export declare const useStop: () => (packageName: string) => Promise<void>;
+export declare const useSetForeground: () => (packageName: string) => Promise<void>;
+export declare const useClearForeground: () => () => void;
+export declare const useRefresh: () => () => Promise<void>;
+export declare const useStopAll: () => () => AsyncResult<void, Error>;
+export declare const useInstall: () => (url: string, opts?: {
+    versionOverride?: string;
+}) => AsyncResult<void, Error>;
+export declare const useUninstall: () => (packageName: string, version?: string) => AsyncResult<void, Error>;
+export declare const useActiveApps: () => ClientApp[];
+export declare const useActiveBackgroundApps: () => ClientApp[];
+export declare const useBackgroundApps: () => {
+    active: ClientApp[];
+    inactive: ClientApp[];
+};
+export declare const useActiveForegroundApp: () => ClientApp | null;
+/**
+ * The single app currently foregrounded in the Compositor overlay, or null.
+ * Driven by setForeground/clearForeground — distinct from the "active
+ * standard app" (running) selector above.
+ */
+export declare const useForegroundApp: () => ClientApp | null;
+export declare const useActiveBackgroundAppsCount: () => number;
+export declare const useLocalMiniApps: () => ClientApp[];
+export {};
+//# sourceMappingURL=apps.d.ts.map

package/build/stores/apps.d.ts.map

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

package/build/stores/apps.js

@@ -0,0 +1,492 @@
+/**
+ * Engine apps store — runtime state of installed and local applets.
+ *
+ * The OEM-facing API: subscribe to the running set, install/uninstall
+ * miniapps, start/stop them. The store delegates install plumbing to
+ * AppRegistry, and exposes hooks (`useApps`, `useStart`, `useStop`,
+ * `useRefresh`, `useStopAll`) that the host UI can read.
+ *
+ * Source of `apps`:
+ *   - Local: appRegistry.getInstalledMiniapps()    (always)
+ */
+import { useMemo } from "react";
+import { result as Res } from "typesafe-ts";
+import { create } from "zustand";
+import { DeviceTypes } from "../types/enums";
+import { getModelCapabilities } from "../types/hardware";
+import { HardwareCompatibility } from "../utils/hardware/hardware";
+import { storage } from "../utils/storage/storage";
+import appRegistry from "../services/AppRegistry";
+import { islandNotifications } from "../services/NotificationsEmitter";
+import sttModelManager from "../services/STTModelManager";
+import { miniappLauncher } from "../services/MiniappLauncher";
+import { miniappRunningRegistry } from "../services/MiniappRunningRegistry";
+import { SETTINGS, useSettingsStore } from "./settings";
+import BluetoothSdk from "@mentra/bluetooth-sdk";
+let hostHooks = {};
+export function installAppStoreHooks(hooks) {
+    hostHooks = { ...hostHooks, ...hooks };
+}
+export const DUMMY_APPLET = {
+    packageName: "",
+    name: "",
+    webviewUrl: "",
+    logoUrl: "",
+    type: "standard",
+    permissions: [],
+    running: false,
+    loading: false,
+    healthy: true,
+    hardwareRequirements: [],
+    offline: true,
+    offlineRoute: "",
+    local: false,
+    hidden: false,
+};
+const APP_ORDER_KEY = "foreground_apps_order";
+export const saveAppsOrder = (orderMap) => {
+    return storage.save(APP_ORDER_KEY, orderMap);
+};
+export const getAppsOrder = () => {
+    return storage.load(APP_ORDER_KEY);
+};
+// In-memory cache for hidden flags. `projectApps` reads getHiddenStatus once
+// per app per refresh — without a cache that was a synchronous JNI hop per
+// app per refresh on a hot UI path. Kept consistent with disk by writing
+// through in setHiddenStatus. Map of packageName → hidden boolean.
+const hiddenStatusCache = new Map();
+const getRawPackageNamePriority = (pkg) => {
+    if (pkg.includes("@empty")) {
+        return 1000;
+    }
+    return 0;
+};
+export const sortAppsByPackageNamePriority = (a, b) => {
+    const pa = getRawPackageNamePriority(a.packageName);
+    const pb = getRawPackageNamePriority(b.packageName);
+    if (pa !== pb) {
+        return pa - pb;
+    }
+    return a.name.localeCompare(b.name);
+};
+export const saveLastOpenTime = (packageName) => {
+    storage.save(`${packageName}_last_open_time`, Date.now());
+};
+export const getLastOpenTime = (packageName) => {
+    const res = storage.load(`${packageName}_last_open_time`);
+    if (res.is_ok())
+        return res.value;
+    return 0;
+};
+export const sortAppsByLastOpenTime = async (apps) => {
+    const timestamps = apps.map((app) => ({ app, time: getLastOpenTime(app.packageName) }));
+    return timestamps.sort((a, b) => a.time - b.time).map((entry) => entry.app);
+};
+const startStopApp = async (app, status) => {
+    if (!status && app.onStop) {
+        try {
+            app.onStop();
+        }
+        catch (e) {
+            console.warn(`ISLAND: onStop threw for ${app.packageName}`, e);
+        }
+    }
+    if (status && app.onStart) {
+        try {
+            app.onStart();
+        }
+        catch (e) {
+            console.warn(`ISLAND: onStart threw for ${app.packageName}`, e);
+        }
+    }
+};
+/**
+ * Build the final `apps` array for the store from the installed/offline app
+ * source. Pure — same inputs -> same outputs.
+ */
+function projectApps(previousState, localApps) {
+    // Dedupe by packageName, keep first occurrence.
+    const byPackage = new Map();
+    for (const app of localApps) {
+        if (!byPackage.has(app.packageName))
+            byPackage.set(app.packageName, app);
+    }
+    // Index previous snapshot for cheap lookups (was O(N²) via .find()).
+    const previousByPackage = new Map();
+    for (const oldApp of previousState.apps) {
+        previousByPackage.set(oldApp.packageName, oldApp);
+    }
+    const defaultWearable = useSettingsStore.getState().getSetting(SETTINGS.default_wearable.key) ||
+        DeviceTypes.NONE;
+    const capabilities = getModelCapabilities(defaultWearable);
+    // Single pass: dedupe → screenshot carry-over → compat → hidden, all into
+    // fresh objects. The previous in-place mutation re-used object references
+    // across refreshes, which broke React.memo / referential-equality
+    // memoization downstream (every refresh propagated re-renders even when
+    // nothing meaningful changed) AND tripped Reanimated's "tried to modify
+    // key of an object already passed to a worklet" warning whenever the home
+    // screen's animated app cards held a reference to a previous snapshot's
+    // app object that we then mutated.
+    //
+    // Identity stability: refresh() is event-driven and fires repeatedly (and
+    // twice per cycle via the local-only → merged two-pass emit). If we always
+    // returned fresh objects, every poll changed the identity of EVERY app —
+    // which re-rendered the Compositor (via useForegroundApp) mid-slide and made
+    // the open/close animation hitch, and churned the home grid / switcher pill.
+    // So we build the candidate object, then REUSE the previous reference when
+    // nothing meaningful changed. Same pattern as the miniappRunningRegistry
+    // projection below. A stable foreground-app reference lets the Compositor's
+    // slide run uninterrupted on the UI thread.
+    return Array.from(byPackage.values()).map((app) => {
+        const next = {
+            ...app,
+            screenshot: previousByPackage.get(app.packageName)?.screenshot ?? app.screenshot,
+            compatibility: HardwareCompatibility.checkCompatibility(app.hardwareRequirements, capabilities),
+            hidden: previousState.getHiddenStatus(app.packageName),
+            // Derive the foreground flag from the store's single source of truth
+            // (`foregroundedPackage`), NOT from the previous snapshot. Carrying it over
+            // per-app meant a refresh that momentarily omitted an app (e.g. the
+            // two-pass local-only → merged emit) would reset its flag to false — which
+            // raced OfflineAppHost's interceptor guard and made the hosted miniapp fall
+            // through to the root router (restart). Deriving here keeps the flag stable
+            // across both passes.
+            foregrounded: app.packageName === previousState.foregroundedPackage,
+        };
+        const prev = previousByPackage.get(app.packageName);
+        return prev && shallowEqualApp(prev, next) ? prev : next;
+    });
+}
+// Cheap equality check used by projectApps to preserve object identity across
+// refreshes when nothing meaningful changed. Most keys are compared by
+// reference (the source app's nested fields — permissions, hardwareRequirements,
+// parameters — are reference-stable within a refresh). The ONE exception is
+// `compatibility`, which projectApps recomputes into a fresh object every call;
+// comparing it by reference would always differ and defeat the whole point. We
+// compare it structurally instead so identity is only broken when the device's
+// actual compatibility verdict changes (e.g. glasses connect/disconnect).
+function shallowEqualApp(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (k === "compatibility") {
+            if (!compatibilityEqual(a.compatibility, b.compatibility))
+                return false;
+            continue;
+        }
+        if (a[k] !== b[k])
+            return false;
+    }
+    return true;
+}
+function compatibilityEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.isCompatible === b.isCompatible &&
+        a.missingRequired.length === b.missingRequired.length &&
+        a.missingOptional.length === b.missingOptional.length &&
+        a.warnings.length === b.warnings.length);
+}
+export const useAppStatusStore = create((set, get) => ({
+    apps: [],
+    foregroundedPackage: null,
+    refresh: async () => {
+        const previousState = get();
+        const localApps = await appRegistry.getInstalledMiniapps();
+        set({ apps: projectApps(previousState, localApps) });
+    },
+    start: async (clientApp, opts) => {
+        const state = get();
+        const packageName = clientApp.packageName;
+        const app = state.apps.find((a) => a.packageName === packageName);
+        if (!app) {
+            console.error(`ISLAND: app not found for package name: ${packageName}`);
+            return false;
+        }
+        // Skip spawning a NEW app while another is mid-launch — concurrent spawns
+        // race the foreground-only-one teardown. This is checked BEFORE the gates
+        // and the onOpenRequested seam (which navigates/foregrounds) so a gated
+        // launch doesn't paint a splash it can't back. Re-opening an already-running
+        // app is exempt: it has nothing to spawn, so it skips this gate and is
+        // allowed to re-navigate/animate below.
+        // That exemption is the fix for the "second tap during another app's launch
+        // window silently does nothing" bug.
+        if (!app.running && state.apps.some((a) => a.loading)) {
+            console.log(`ISLAND: skipping start ${packageName} — another app is loading`);
+            return false;
+        }
+        if (!app.offline && !app.local) {
+            console.warn(`ISLAND: cloud-v1 app entries are no longer supported: ${packageName}`);
+            return false;
+        }
+        // Hardware-compatibility gate — engine decides and blocks; the host renders
+        // its branded alert via onIncompatibleBlocked (and/or the structured
+        // notification below). `!isCompatible` (not `=== false`) keeps the semantics
+        // of the host gate this replaces: an unknown verdict blocks, not launches.
+        if (!app.compatibility?.isCompatible) {
+            islandNotifications.emit({
+                kind: "version_incompatible",
+                packageName,
+                reason: `${app.name ?? packageName} is not compatible with the connected glasses`,
+                metadata: { missingRequired: app.compatibility?.missingRequired ?? [] },
+                timestamp: Date.now(),
+            });
+            hostHooks.onIncompatibleBlocked?.(app);
+            return false;
+        }
+        // Missing-speech-model gate for apps registered with requiresLocalSttModel.
+        // Engine decides via its own model manager; the host renders the alert and
+        // any settings navigation via onMissingSpeechModel.
+        if (appRegistry.requiresLocalSttModel(packageName) && !(await sttModelManager.isModelAvailable())) {
+            islandNotifications.emit({
+                kind: "missing_speech_model",
+                packageName,
+                reason: `${app.name ?? packageName} needs an on-device speech model before it can start`,
+                timestamp: Date.now(),
+            });
+            hostHooks.onMissingSpeechModel?.(app);
+            return false;
+        }
+        // Host navigation / open-animation seam. Runs on EVERY accepted open —
+        // including re-opening an already-running app — so the animation always
+        // plays (BuiltInMiniappCatalog.navigateForApp: overlay apps setForeground
+        // for the slide).
+        hostHooks.onOpenRequested?.(app, opts);
+        // First-activation mark (moved from the host's old beforeStart — engine
+        // owns the settings store).
+        useSettingsStore.getState().setSetting(SETTINGS.has_ever_activated_app.key, true);
+        // If the tapped app is already running, this is a re-open: the nav/foreground
+        // above already drove the animation, and there's nothing to spawn. Short-
+        // circuit before the spawn pipeline.
+        if (app.running) {
+            saveLastOpenTime(packageName);
+            return true;
+        }
+        // Foreground-only-one rule: stop other running standard apps.
+        if (app.type === "standard") {
+            const runningForeground = state.apps.filter((a) => a.running && a.type === "standard" && a.packageName !== packageName);
+            for (const r of runningForeground) {
+                await get().stop(r.packageName);
+            }
+        }
+        set((s) => ({
+            apps: s.apps.map((a) => (a.packageName === packageName ? { ...a, running: true, loading: false } : a)),
+        }));
+        saveLastOpenTime(packageName);
+        await startStopApp(app, true);
+        // Spawn the background JS context for local miniapps. This used to be a
+        // side effect of LocalMiniappView mounting on foreground; pulling it here
+        // lets start() actually run the app even when nothing foregrounds it (e.g.
+        // a system app launching another miniapp via session.miniapps). Idempotent
+        // with the view's own ensureRunning; a no-op for native offline built-ins
+        // and cloud apps (no JS bundle).
+        if (app.local) {
+            try {
+                await miniappLauncher.ensureRunning(packageName);
+            }
+            catch (e) {
+                // Spawn / bundle-resolve failed — revert the optimistic running flag so
+                // the home list and miniapps.list() don't show a "running" app with no
+                // JS context, and report failure to the caller (session.miniapps.start).
+                console.warn(`ISLAND: launcher.ensureRunning failed for ${packageName}`, e);
+                set((s) => ({
+                    apps: s.apps.map((a) => (a.packageName === packageName ? { ...a, running: false, loading: false } : a)),
+                }));
+                // onStart already persisted running:true to disk (saveLocalAppRunningState)
+                // before the spawn; run onStop to undo it so a refresh/reboot doesn't
+                // resurrect a "running" app with no JS context.
+                await startStopApp(app, false);
+                return false;
+            }
+        }
+        return true;
+    },
+    stop: async (packageName) => {
+        const state = get();
+        const app = state.apps.find((a) => a.packageName === packageName);
+        if (!app) {
+            console.error(`ISLAND: app not found for package name: ${packageName}`);
+            return;
+        }
+        set((s) => ({
+            apps: s.apps.map((a) => a.packageName === packageName ? { ...a, running: false, screenshot: undefined, loading: false } : a),
+        }));
+        // if there are no apps running, call clearDisplay():
+        // read fresh state via get() — `state` was captured before the set() above, so it still shows
+        // this app as running and would never reach 0 when stopping the last app.
+        if (get().apps.filter((a) => a.running).length === 0) {
+            BluetoothSdk.clearDisplay();
+        }
+        await startStopApp(app, false);
+        // Tear down the background JS context for local miniapps. No-op for native
+        // offline built-ins.
+        if (app.local) {
+            try {
+                await miniappLauncher.stop(packageName);
+            }
+            catch (e) {
+                console.warn(`ISLAND: launcher.stop failed for ${packageName}`, e);
+            }
+        }
+    },
+    setForeground: async (packageName) => {
+        const app = get().apps.find((a) => a.packageName === packageName);
+        if (!app) {
+            console.error(`ISLAND: setForeground — app not found: ${packageName}`);
+            return;
+        }
+        // Flip the foreground flag synchronously so the Compositor's open
+        // animation starts on the same frame as the tap. We do NOT await start()
+        // first — that gated the flag (and thus the animation) behind the whole
+        // JSContext-spawn chain, which was the perceived launch delay. The
+        // Compositor/LocalMiniappView already handle the spawn being in-flight
+        // (the phase machine), so foregrounding needn't wait for it.
+        saveLastOpenTime(packageName);
+        set((s) => ({
+            foregroundedPackage: packageName,
+            apps: s.apps.map((a) => ({ ...a, foregrounded: a.packageName === packageName })),
+        }));
+        // Ensure the JSContext exists. start() is idempotent for an
+        // already-running app and enforces the foreground-only-one rule for
+        // standard apps. Fire-and-forget after the flag flip so it doesn't block
+        // paint.
+        // if (!app.running) {
+        //   get().start(app)
+        // }
+    },
+    clearForeground: () => {
+        set((s) => ({
+            foregroundedPackage: null,
+            apps: s.apps.some((a) => a.foregrounded)
+                ? s.apps.map((a) => (a.foregrounded ? { ...a, foregrounded: false } : a))
+                : s.apps,
+        }));
+    },
+    stopAll: () => {
+        return Res.try_async(async () => {
+            const running = get().apps.filter((a) => a.running);
+            for (const a of running) {
+                await get().stop(a.packageName);
+            }
+        });
+    },
+    install: (url, opts) => appRegistry.installFromUrl(url, opts),
+    uninstall: (packageName, version) => {
+        return Res.try_async(async () => {
+            const res = await appRegistry.uninstall(packageName, version);
+            if (res.is_error())
+                throw res.error;
+            set((s) => ({ apps: s.apps.filter((a) => a.packageName !== packageName) }));
+        });
+    },
+    saveScreenshot: async (packageName, screenshot) => {
+        storage.save(`${packageName}_screenshot`, screenshot);
+        set((s) => ({
+            apps: s.apps.map((a) => (a.packageName === packageName ? { ...a, screenshot } : a)),
+        }));
+    },
+    setHiddenStatus: (packageName, status) => {
+        hiddenStatusCache.set(packageName, status);
+        set((s) => ({
+            apps: s.apps.map((a) => (a.packageName === packageName ? { ...a, hidden: status } : a)),
+        }));
+        storage.save(`${packageName}_hidden`, status);
+        if (!status) {
+            const orderMap = getAppsOrder();
+            if (orderMap.is_ok()) {
+                delete orderMap.value[packageName];
+                saveAppsOrder(orderMap.value);
+            }
+        }
+    },
+    getHiddenStatus: (packageName) => {
+        const cached = hiddenStatusCache.get(packageName);
+        if (cached !== undefined)
+            return cached;
+        const res = storage.load(`${packageName}_hidden`);
+        const value = res.is_ok() ? res.value : false;
+        hiddenStatusCache.set(packageName, value);
+        return value;
+    },
+    setApps: (apps) => set({ apps }),
+}));
+// Project miniappRunningRegistry membership into the store's `running` field
+// for local apps so the home tray and switcher reflect actual mount state
+// without waiting for the next refresh() cycle.
+miniappRunningRegistry.subscribe(() => {
+    const running = new Set(miniappRunningRegistry.getAll());
+    const state = useAppStatusStore.getState();
+    let changed = false;
+    const updated = state.apps.map((app) => {
+        if (!app.local)
+            return app;
+        const next = running.has(app.packageName);
+        if (app.running === next)
+            return app;
+        changed = true;
+        return { ...app, running: next };
+    });
+    if (changed) {
+        useAppStatusStore.setState({ apps: updated });
+    }
+});
+// AppRegistry change events trigger a store refresh.
+appRegistry.subscribe(() => {
+    void useAppStatusStore.getState().refresh();
+});
+// Re-evaluate hardware compatibility when the paired/default wearable changes.
+useSettingsStore.subscribe((state) => state.getSetting(SETTINGS.default_wearable.key), () => {
+    void useAppStatusStore.getState().refresh();
+});
+// ---------------------------------------------------------------------------
+// Public hooks
+// ---------------------------------------------------------------------------
+export const useApps = () => useAppStatusStore((state) => state.apps);
+export const useStart = () => useAppStatusStore((state) => state.start);
+export const useStop = () => useAppStatusStore((state) => state.stop);
+export const useSetForeground = () => useAppStatusStore((state) => state.setForeground);
+export const useClearForeground = () => useAppStatusStore((state) => state.clearForeground);
+export const useRefresh = () => useAppStatusStore((state) => state.refresh);
+export const useStopAll = () => useAppStatusStore((state) => state.stopAll);
+export const useInstall = () => useAppStatusStore((state) => state.install);
+export const useUninstall = () => useAppStatusStore((state) => state.uninstall);
+export const useActiveApps = () => {
+    const apps = useApps();
+    return useMemo(() => apps.filter((app) => app.running), [apps]);
+};
+export const useActiveBackgroundApps = () => {
+    const apps = useApps();
+    return useMemo(() => apps.filter((app) => app.type === "background" && app.running), [apps]);
+};
+export const useBackgroundApps = () => {
+    const apps = useApps();
+    return useMemo(() => ({
+        active: apps.filter((app) => app.type === "background" && app.running),
+        inactive: apps.filter((app) => app.type === "background" && !app.running),
+    }), [apps]);
+};
+export const useActiveForegroundApp = () => {
+    const apps = useApps();
+    return useMemo(() => apps.find((app) => (app.type === "standard" || !app.type) && app.running) ?? null, [apps]);
+};
+/**
+ * The single app currently foregrounded in the Compositor overlay, or null.
+ * Driven by setForeground/clearForeground — distinct from the "active
+ * standard app" (running) selector above.
+ */
+export const useForegroundApp = () => {
+    const apps = useApps();
+    return useMemo(() => apps.find((app) => app.foregrounded) ?? null, [apps]);
+};
+export const useActiveBackgroundAppsCount = () => {
+    const apps = useApps();
+    return useMemo(() => apps.filter((app) => app.type === "background" && app.running).length, [apps]);
+};
+export const useLocalMiniApps = () => {
+    const apps = useApps();
+    return useMemo(() => apps.filter((app) => app.local), [apps]);
+};
+//# sourceMappingURL=apps.js.map