@mentra/engine 0.1.0-beta.0

package/build/services/LocalSttFallbackCoordinator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Decides whether on-device Sherpa STT should produce transcripts for local
+ * miniapps, instead of (or in addition to) cloud transcription. Local STT is
+ * active when the cloud is unavailable or any subscription requires
+ * `forceLocal`.
+ *
+ * Activation flips `localSttFallbackActive` in the settings store, which
+ * the bluetooth-sdk native side reads to decide whether to feed PCM into
+ * the SherpaOnnxTranscriber. Local transcripts then flow back through the
+ * `local_transcription` Bridge event; the host wires that event to
+ * `localMiniappRuntime.forwardEvent`, with this coordinator providing the
+ * subscription-active gate so we never publish transcripts to miniapps that
+ * aren't asking for them. LocalMiniappRuntime filters mixed local/cloud
+ * delivery per miniapp.
+ */
+declare class LocalSttFallbackCoordinator {
+    private static instance;
+    private hasTranscriptionSubscription;
+    private hasForceLocalSubscription;
+    private activeLanguage;
+    /**
+     * Default to "cloud is up" so we never accidentally activate local STT before
+     * the cloud client has had a chance to start. We attach lazily on the first
+     * subscription/reconcile pass; once attached, this field reflects the real
+     * cloud-client runtime status.
+     */
+    private cloudConnected;
+    private localActive;
+    private cloudAdapterAttached;
+    private constructor();
+    /**
+     * Lazy-attach the engine cloud connection listener. The coordinator is
+     * constructed at module load, before engine.start() brings up the cloud
+     * client, so we defer until the first reconcile.
+     */
+    private attachCloudAdapterIfReady;
+    static getInstance(): LocalSttFallbackCoordinator;
+    isActive(): boolean;
+    getActiveLanguage(): string | null;
+    onSubscriptionChange(hasTranscription: boolean, language: string | null, hasForceLocal?: boolean): void;
+    /**
+     * Informational hook, retained for API stability. No longer called: the
+     * authoritative switching signal is the cloud-client adapter (local miniapps
+     * are powered only by V2). v1 cloud transcripts deliberately do NOT drive this
+     * coordinator anymore. Kept for future hysteresis if connection-state alone
+     * proves too coarse.
+     */
+    onCloudTranscript(): void;
+    private reconcile;
+    private startLocalStt;
+    private stopLocalStt;
+    private shouldUseLocalStt;
+    private log;
+}
+declare const localSttFallbackCoordinator: LocalSttFallbackCoordinator;
+export default localSttFallbackCoordinator;
+//# sourceMappingURL=LocalSttFallbackCoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalSttFallbackCoordinator.d.ts","sourceRoot":"","sources":["../../src/services/LocalSttFallbackCoordinator.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,cAAM,2BAA2B;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IAEpD,OAAO,CAAC,4BAA4B,CAAQ;IAC5C,OAAO,CAAC,yBAAyB,CAAQ;IACzC,OAAO,CAAC,cAAc,CAAsB;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAO;IAC7B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,oBAAoB,CAAQ;IAEpC,OAAO;IAQP;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAajC,MAAM,CAAC,WAAW,IAAI,2BAA2B;IAOjD,QAAQ,IAAI,OAAO;IAInB,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIlC,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,aAAa,UAAQ,GAAG,IAAI;IAQrG;;;;;;OAMG;IACH,iBAAiB,IAAI,IAAI;YAEX,SAAS;YAUT,aAAa;IAyB3B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,GAAG;CAGZ;AAED,QAAA,MAAM,2BAA2B,6BAA4C,CAAA;AAC7E,eAAe,2BAA2B,CAAA"}

package/build/services/LocalSttFallbackCoordinator.js

@@ -0,0 +1,137 @@
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal";
+import { ISLAND_SETTINGS_KEYS } from "../runtime/config";
+import { useSettingsStore } from "../stores/settings";
+import { cloudClientService } from "./CloudClientService";
+import sttModelManager from "./STTModelManager";
+/**
+ * Decides whether on-device Sherpa STT should produce transcripts for local
+ * miniapps, instead of (or in addition to) cloud transcription. Local STT is
+ * active when the cloud is unavailable or any subscription requires
+ * `forceLocal`.
+ *
+ * Activation flips `localSttFallbackActive` in the settings store, which
+ * the bluetooth-sdk native side reads to decide whether to feed PCM into
+ * the SherpaOnnxTranscriber. Local transcripts then flow back through the
+ * `local_transcription` Bridge event; the host wires that event to
+ * `localMiniappRuntime.forwardEvent`, with this coordinator providing the
+ * subscription-active gate so we never publish transcripts to miniapps that
+ * aren't asking for them. LocalMiniappRuntime filters mixed local/cloud
+ * delivery per miniapp.
+ */
+class LocalSttFallbackCoordinator {
+    static instance;
+    hasTranscriptionSubscription = false;
+    hasForceLocalSubscription = false;
+    activeLanguage = null;
+    /**
+     * Default to "cloud is up" so we never accidentally activate local STT before
+     * the cloud client has had a chance to start. We attach lazily on the first
+     * subscription/reconcile pass; once attached, this field reflects the real
+     * cloud-client runtime status.
+     */
+    cloudConnected = true;
+    localActive = false;
+    cloudAdapterAttached = false;
+    constructor() {
+        // Reset the persisted mirror flag on boot — the in-memory state in this
+        // coordinator is the source of truth, and a stale "true" left from the
+        // previous session would cause native to feed Sherpa before any miniapp
+        // registered a subscription.
+        useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, false);
+    }
+    /**
+     * Lazy-attach the engine cloud connection listener. The coordinator is
+     * constructed at module load, before engine.start() brings up the cloud
+     * client, so we defer until the first reconcile.
+     */
+    attachCloudAdapterIfReady() {
+        if (this.cloudAdapterAttached)
+            return;
+        this.cloudConnected = cloudClientService.isConnected();
+        cloudClientService.onStatusChanged((status) => {
+            const connected = status.status === "connected";
+            if (this.cloudConnected === connected)
+                return;
+            this.log(`cloud connection -> ${connected ? "up" : "down"}`);
+            this.cloudConnected = connected;
+            void this.reconcile();
+        });
+        this.cloudAdapterAttached = true;
+    }
+    static getInstance() {
+        if (!LocalSttFallbackCoordinator.instance) {
+            LocalSttFallbackCoordinator.instance = new LocalSttFallbackCoordinator();
+        }
+        return LocalSttFallbackCoordinator.instance;
+    }
+    isActive() {
+        return this.localActive;
+    }
+    getActiveLanguage() {
+        return this.activeLanguage;
+    }
+    onSubscriptionChange(hasTranscription, language, hasForceLocal = false) {
+        this.log(`onSubscriptionChange(hasTx=${hasTranscription}, lang=${language}, forceLocal=${hasForceLocal})`);
+        this.hasTranscriptionSubscription = hasTranscription;
+        this.hasForceLocalSubscription = hasTranscription && hasForceLocal;
+        this.activeLanguage = hasTranscription ? language : null;
+        void this.reconcile();
+    }
+    /**
+     * Informational hook, retained for API stability. No longer called: the
+     * authoritative switching signal is the cloud-client adapter (local miniapps
+     * are powered only by V2). v1 cloud transcripts deliberately do NOT drive this
+     * coordinator anymore. Kept for future hysteresis if connection-state alone
+     * proves too coarse.
+     */
+    onCloudTranscript() { }
+    async reconcile() {
+        this.attachCloudAdapterIfReady();
+        const shouldBeActive = this.shouldUseLocalStt();
+        if (shouldBeActive && !this.localActive) {
+            await this.startLocalStt();
+        }
+        else if (!shouldBeActive && this.localActive) {
+            this.stopLocalStt(this.hasTranscriptionSubscription ? "cloud reconnected" : "subscription gone");
+        }
+    }
+    async startLocalStt() {
+        this.log("starting local stt");
+        const modelAvailable = await sttModelManager.isModelAvailable();
+        if (!modelAvailable) {
+            this.log("local stt model is not available yet — skipping activation");
+            return;
+        }
+        if (!this.shouldUseLocalStt()) {
+            this.log("local stt activation skipped: routing changed before start completed");
+            return;
+        }
+        try {
+            // Direct btsdk call now (was a host restartTranscriber hook).
+            await BluetoothSdk.restartTranscriber();
+        }
+        catch (err) {
+            this.log(`restartTranscriber failed: ${err}`);
+        }
+        if (!this.shouldUseLocalStt()) {
+            this.log("local stt activation skipped: routing changed during transcriber restart");
+            return;
+        }
+        useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, true);
+        this.localActive = true;
+    }
+    stopLocalStt(reason) {
+        this.log(`stopping local stt: ${reason}`);
+        useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, false);
+        this.localActive = false;
+    }
+    shouldUseLocalStt() {
+        return this.hasTranscriptionSubscription && (this.hasForceLocalSubscription || !this.cloudConnected);
+    }
+    log(msg) {
+        console.log(`[LocalSttFallback] ${msg}`);
+    }
+}
+const localSttFallbackCoordinator = LocalSttFallbackCoordinator.getInstance();
+export default localSttFallbackCoordinator;
+//# sourceMappingURL=LocalSttFallbackCoordinator.js.map

package/build/services/LocalSttFallbackCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalSttFallbackCoordinator.js","sourceRoot":"","sources":["../../src/services/LocalSttFallbackCoordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import BluetoothSdk from \"@mentra/bluetooth-sdk/internal\"\nimport {ISLAND_SETTINGS_KEYS} from \"../runtime/config\"\nimport {useSettingsStore} from \"../stores/settings\"\nimport {cloudClientService} from \"./CloudClientService\"\nimport sttModelManager from \"./STTModelManager\"\n\n/**\n * Decides whether on-device Sherpa STT should produce transcripts for local\n * miniapps, instead of (or in addition to) cloud transcription. Local STT is\n * active when the cloud is unavailable or any subscription requires\n * `forceLocal`.\n *\n * Activation flips `localSttFallbackActive` in the settings store, which\n * the bluetooth-sdk native side reads to decide whether to feed PCM into\n * the SherpaOnnxTranscriber. Local transcripts then flow back through the\n * `local_transcription` Bridge event; the host wires that event to\n * `localMiniappRuntime.forwardEvent`, with this coordinator providing the\n * subscription-active gate so we never publish transcripts to miniapps that\n * aren't asking for them. LocalMiniappRuntime filters mixed local/cloud\n * delivery per miniapp.\n */\nclass LocalSttFallbackCoordinator {\n  private static instance: LocalSttFallbackCoordinator\n\n  private hasTranscriptionSubscription = false\n  private hasForceLocalSubscription = false\n  private activeLanguage: string | null = null\n  /**\n   * Default to \"cloud is up\" so we never accidentally activate local STT before\n   * the cloud client has had a chance to start. We attach lazily on the first\n   * subscription/reconcile pass; once attached, this field reflects the real\n   * cloud-client runtime status.\n   */\n  private cloudConnected = true\n  private localActive = false\n  private cloudAdapterAttached = false\n\n  private constructor() {\n    // Reset the persisted mirror flag on boot — the in-memory state in this\n    // coordinator is the source of truth, and a stale \"true\" left from the\n    // previous session would cause native to feed Sherpa before any miniapp\n    // registered a subscription.\n    useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, false)\n  }\n\n  /**\n   * Lazy-attach the engine cloud connection listener. The coordinator is\n   * constructed at module load, before engine.start() brings up the cloud\n   * client, so we defer until the first reconcile.\n   */\n  private attachCloudAdapterIfReady(): void {\n    if (this.cloudAdapterAttached) return\n    this.cloudConnected = cloudClientService.isConnected()\n    cloudClientService.onStatusChanged((status) => {\n      const connected = status.status === \"connected\"\n      if (this.cloudConnected === connected) return\n      this.log(`cloud connection -> ${connected ? \"up\" : \"down\"}`)\n      this.cloudConnected = connected\n      void this.reconcile()\n    })\n    this.cloudAdapterAttached = true\n  }\n\n  static getInstance(): LocalSttFallbackCoordinator {\n    if (!LocalSttFallbackCoordinator.instance) {\n      LocalSttFallbackCoordinator.instance = new LocalSttFallbackCoordinator()\n    }\n    return LocalSttFallbackCoordinator.instance\n  }\n\n  isActive(): boolean {\n    return this.localActive\n  }\n\n  getActiveLanguage(): string | null {\n    return this.activeLanguage\n  }\n\n  onSubscriptionChange(hasTranscription: boolean, language: string | null, hasForceLocal = false): void {\n    this.log(`onSubscriptionChange(hasTx=${hasTranscription}, lang=${language}, forceLocal=${hasForceLocal})`)\n    this.hasTranscriptionSubscription = hasTranscription\n    this.hasForceLocalSubscription = hasTranscription && hasForceLocal\n    this.activeLanguage = hasTranscription ? language : null\n    void this.reconcile()\n  }\n\n  /**\n   * Informational hook, retained for API stability. No longer called: the\n   * authoritative switching signal is the cloud-client adapter (local miniapps\n   * are powered only by V2). v1 cloud transcripts deliberately do NOT drive this\n   * coordinator anymore. Kept for future hysteresis if connection-state alone\n   * proves too coarse.\n   */\n  onCloudTranscript(): void {}\n\n  private async reconcile(): Promise<void> {\n    this.attachCloudAdapterIfReady()\n    const shouldBeActive = this.shouldUseLocalStt()\n    if (shouldBeActive && !this.localActive) {\n      await this.startLocalStt()\n    } else if (!shouldBeActive && this.localActive) {\n      this.stopLocalStt(this.hasTranscriptionSubscription ? \"cloud reconnected\" : \"subscription gone\")\n    }\n  }\n\n  private async startLocalStt(): Promise<void> {\n    this.log(\"starting local stt\")\n    const modelAvailable = await sttModelManager.isModelAvailable()\n    if (!modelAvailable) {\n      this.log(\"local stt model is not available yet — skipping activation\")\n      return\n    }\n    if (!this.shouldUseLocalStt()) {\n      this.log(\"local stt activation skipped: routing changed before start completed\")\n      return\n    }\n    try {\n      // Direct btsdk call now (was a host restartTranscriber hook).\n      await BluetoothSdk.restartTranscriber()\n    } catch (err) {\n      this.log(`restartTranscriber failed: ${err}`)\n    }\n    if (!this.shouldUseLocalStt()) {\n      this.log(\"local stt activation skipped: routing changed during transcriber restart\")\n      return\n    }\n    useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, true)\n    this.localActive = true\n  }\n\n  private stopLocalStt(reason: string): void {\n    this.log(`stopping local stt: ${reason}`)\n    useSettingsStore.getState().setSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive, false)\n    this.localActive = false\n  }\n\n  private shouldUseLocalStt(): boolean {\n    return this.hasTranscriptionSubscription && (this.hasForceLocalSubscription || !this.cloudConnected)\n  }\n\n  private log(msg: string): void {\n    console.log(`[LocalSttFallback] ${msg}`)\n  }\n}\n\nconst localSttFallbackCoordinator = LocalSttFallbackCoordinator.getInstance()\nexport default localSttFallbackCoordinator\n"]}

package/build/services/MentraJSCrashController.d.ts

@@ -0,0 +1,97 @@
+/**
+ * MentraJSCrashController — crash recovery state machine for the
+ * per-miniapp JSContexts owned by MentraJSRouter.
+ *
+ *   RUNNING
+ *     │  crash detected (uncaught exception, native bridge throw,
+ *     │   ping miss, soft-watchdog kill, etc.)
+ *     ▼
+ *   CRASHED ──── respawn allowed? ──── no ──► CRASHLOOP_DISABLED
+ *     │                                          (persistent banner)
+ *     ▼ yes
+ *   BACKOFF(2s → 8s → 30s)
+ *     │  timer fires
+ *     ▼
+ *   RUNNING (and stays here on a clean 60s window;
+ *            otherwise crash count increments)
+ *
+ * Retry policy: zero retries by default — the first crash escalates
+ * straight to CRASHLOOP_DISABLED, matching how Android / iOS treat crashed
+ * apps. Callers that prefer auto-respawn opt in by passing
+ * `{maxRetries: 3, backoffMs: [2_000, 8_000, 30_000]}`; the BACKOFF state
+ * machine and exponential delays are implemented and unit-tested for that
+ * case.
+ *
+ * The controller is purely a policy engine — it doesn't actually call
+ * mentraJsSpawn / mentraJsKill. Callers (MentraJSRouter) read the
+ * Outcome returned from onCrash() and drive the host accordingly. This
+ * makes the controller unit-testable with synthetic timer.
+ */
+export type CrashState = {
+    kind: "RUNNING";
+    sinceMs: number;
+} | {
+    kind: "CRASHED";
+    reason: string;
+    crashedAtMs: number;
+} | {
+    kind: "BACKOFF";
+    until: number;
+    attempt: number;
+    reason: string;
+} | {
+    kind: "CRASHLOOP_DISABLED";
+    sinceMs: number;
+    reason: string;
+};
+export interface CrashOutcome {
+    /** Caller must call `respawn(packageName)` after this delay (ms from now). */
+    scheduleRespawnAfterMs?: number;
+    /** Caller should surface "X restarted" toast (2nd-within-5m crash). */
+    showRestartToast?: boolean;
+    /** Caller should surface persistent "crashloop disabled" banner. */
+    surfaceCrashloopBanner?: boolean;
+    /** Caller may push the crash event to dev portal / Sentry as warn-level. */
+    sentryLevel?: "info" | "warning" | "error";
+}
+export interface CrashControllerOptions {
+    /** Override the wall clock for tests. Defaults to Date.now. */
+    now?: () => number;
+    /** Backoff sequence in ms. Defaults to [2_000, 8_000, 30_000]. */
+    backoffMs?: number[];
+    /** Window in ms — N crashes inside this window escalates. Defaults to 5min. */
+    crashWindowMs?: number;
+    /** Max retries before CRASHLOOP_DISABLED. Defaults to 0 — first crash
+     *  escalates immediately, matching Android / iOS app conventions. */
+    maxRetries?: number;
+    /** Clean-uptime threshold that resets the retry counter. Defaults to 60s. */
+    cleanUptimeResetMs?: number;
+}
+export declare class MentraJSCrashController {
+    private readonly now;
+    private readonly backoffMs;
+    private readonly crashWindowMs;
+    private readonly maxRetries;
+    private readonly cleanUptimeResetMs;
+    private readonly packages;
+    constructor(opts?: CrashControllerOptions);
+    /** Tracking starts when MentraJSRouter spawns a fresh JSContext. */
+    onSpawn(packageName: string): void;
+    /** Called when MentraJSRouter explicitly tears down (user-initiated). */
+    onKill(packageName: string): void;
+    /**
+     * Record a crash and return the policy outcome. Caller is responsible for
+     * scheduling the respawn (timer ownership belongs at the orchestration
+     * layer that holds the host context, not here).
+     */
+    onCrash(packageName: string, reason: string): CrashOutcome;
+    /** Inspect current state — useful for tests and diagnostics. */
+    stateFor(packageName: string): CrashState | null;
+    /** Total respawns since registration — surfaced to Sentry as a counter. */
+    respawnCount(packageName: string): number;
+    /** Currently-disabled packages. Host UI uses this to show banners. */
+    disabledPackages(): string[];
+    /** Manually re-enable a disabled package (user "Try again" tap). */
+    reset(packageName: string): void;
+}
+//# sourceMappingURL=MentraJSCrashController.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MentraJSCrashController.d.ts","sourceRoot":"","sources":["../../src/services/MentraJSCrashController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,UAAU,GAClB;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAClC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,GACtD;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GACjE;IAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAA;AAEjE,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,oEAAoE;IACpE,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;yEACqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAeD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;gBAEpD,IAAI,GAAE,sBAA2B;IAQ7C,oEAAoE;IACpE,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAiBlC,yEAAyE;IACzE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY;IA4C1D,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIhD,2EAA2E;IAC3E,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIzC,sEAAsE;IACtE,gBAAgB,IAAI,MAAM,EAAE;IAQ5B,oEAAoE;IACpE,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;CAMjC"}

package/build/services/MentraJSCrashController.js

@@ -0,0 +1,138 @@
+/**
+ * MentraJSCrashController — crash recovery state machine for the
+ * per-miniapp JSContexts owned by MentraJSRouter.
+ *
+ *   RUNNING
+ *     │  crash detected (uncaught exception, native bridge throw,
+ *     │   ping miss, soft-watchdog kill, etc.)
+ *     ▼
+ *   CRASHED ──── respawn allowed? ──── no ──► CRASHLOOP_DISABLED
+ *     │                                          (persistent banner)
+ *     ▼ yes
+ *   BACKOFF(2s → 8s → 30s)
+ *     │  timer fires
+ *     ▼
+ *   RUNNING (and stays here on a clean 60s window;
+ *            otherwise crash count increments)
+ *
+ * Retry policy: zero retries by default — the first crash escalates
+ * straight to CRASHLOOP_DISABLED, matching how Android / iOS treat crashed
+ * apps. Callers that prefer auto-respawn opt in by passing
+ * `{maxRetries: 3, backoffMs: [2_000, 8_000, 30_000]}`; the BACKOFF state
+ * machine and exponential delays are implemented and unit-tested for that
+ * case.
+ *
+ * The controller is purely a policy engine — it doesn't actually call
+ * mentraJsSpawn / mentraJsKill. Callers (MentraJSRouter) read the
+ * Outcome returned from onCrash() and drive the host accordingly. This
+ * makes the controller unit-testable with synthetic timer.
+ */
+const DEFAULT_BACKOFFS = [2_000, 8_000, 30_000];
+const DEFAULT_WINDOW_MS = 5 * 60_000;
+const DEFAULT_MAX_RETRIES = 0;
+const DEFAULT_CLEAN_UPTIME_RESET_MS = 60_000;
+export class MentraJSCrashController {
+    now;
+    backoffMs;
+    crashWindowMs;
+    maxRetries;
+    cleanUptimeResetMs;
+    packages = new Map();
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        this.backoffMs = opts.backoffMs ?? DEFAULT_BACKOFFS;
+        this.crashWindowMs = opts.crashWindowMs ?? DEFAULT_WINDOW_MS;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.cleanUptimeResetMs = opts.cleanUptimeResetMs ?? DEFAULT_CLEAN_UPTIME_RESET_MS;
+    }
+    /** Tracking starts when MentraJSRouter spawns a fresh JSContext. */
+    onSpawn(packageName) {
+        const at = this.now();
+        const prev = this.packages.get(packageName);
+        if (prev) {
+            // Carry forward the crash history; a respawn doesn't reset retry
+            // budget unless the previous RUNNING state survived >= cleanUptimeResetMs.
+            prev.state = { kind: "RUNNING", sinceMs: at };
+            prev.totalRespawns += 1;
+        }
+        else {
+            this.packages.set(packageName, {
+                state: { kind: "RUNNING", sinceMs: at },
+                crashesInWindow: [],
+                totalRespawns: 0,
+            });
+        }
+    }
+    /** Called when MentraJSRouter explicitly tears down (user-initiated). */
+    onKill(packageName) {
+        this.packages.delete(packageName);
+    }
+    /**
+     * Record a crash and return the policy outcome. Caller is responsible for
+     * scheduling the respawn (timer ownership belongs at the orchestration
+     * layer that holds the host context, not here).
+     */
+    onCrash(packageName, reason) {
+        const at = this.now();
+        const entry = this.packages.get(packageName) ?? {
+            state: { kind: "RUNNING", sinceMs: at },
+            crashesInWindow: [],
+            totalRespawns: 0,
+        };
+        // If the previous RUNNING window was long enough, reset the retry
+        // counter — a crash after a stable session shouldn't burn budget.
+        if (entry.state.kind === "RUNNING") {
+            const uptime = at - entry.state.sinceMs;
+            if (uptime >= this.cleanUptimeResetMs) {
+                entry.crashesInWindow = [];
+            }
+        }
+        // Drop crashes that fell out of the window before counting the new one.
+        const cutoff = at - this.crashWindowMs;
+        entry.crashesInWindow = entry.crashesInWindow.filter((t) => t >= cutoff);
+        entry.crashesInWindow.push(at);
+        this.packages.set(packageName, entry);
+        const crashCount = entry.crashesInWindow.length;
+        if (crashCount > this.maxRetries) {
+            entry.state = { kind: "CRASHLOOP_DISABLED", sinceMs: at, reason };
+            return {
+                surfaceCrashloopBanner: true,
+                sentryLevel: "error",
+            };
+        }
+        const attempt = crashCount - 1;
+        const delayMs = this.backoffMs[Math.min(attempt, this.backoffMs.length - 1)];
+        entry.state = { kind: "BACKOFF", until: at + delayMs, attempt: crashCount, reason };
+        return {
+            scheduleRespawnAfterMs: delayMs,
+            showRestartToast: crashCount >= 2,
+            sentryLevel: crashCount === 1 ? "info" : "warning",
+        };
+    }
+    /** Inspect current state — useful for tests and diagnostics. */
+    stateFor(packageName) {
+        return this.packages.get(packageName)?.state ?? null;
+    }
+    /** Total respawns since registration — surfaced to Sentry as a counter. */
+    respawnCount(packageName) {
+        return this.packages.get(packageName)?.totalRespawns ?? 0;
+    }
+    /** Currently-disabled packages. Host UI uses this to show banners. */
+    disabledPackages() {
+        const out = [];
+        for (const [name, entry] of this.packages) {
+            if (entry.state.kind === "CRASHLOOP_DISABLED")
+                out.push(name);
+        }
+        return out;
+    }
+    /** Manually re-enable a disabled package (user "Try again" tap). */
+    reset(packageName) {
+        const entry = this.packages.get(packageName);
+        if (!entry)
+            return;
+        entry.crashesInWindow = [];
+        entry.state = { kind: "RUNNING", sinceMs: this.now() };
+    }
+}
+//# sourceMappingURL=MentraJSCrashController.js.map

package/build/services/MentraJSCrashController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MentraJSCrashController.js","sourceRoot":"","sources":["../../src/services/MentraJSCrashController.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MentraJSCrashController — crash recovery state machine for the\n * per-miniapp JSContexts owned by MentraJSRouter.\n *\n *   RUNNING\n *     │  crash detected (uncaught exception, native bridge throw,\n *     │   ping miss, soft-watchdog kill, etc.)\n *     ▼\n *   CRASHED ──── respawn allowed? ──── no ──► CRASHLOOP_DISABLED\n *     │                                          (persistent banner)\n *     ▼ yes\n *   BACKOFF(2s → 8s → 30s)\n *     │  timer fires\n *     ▼\n *   RUNNING (and stays here on a clean 60s window;\n *            otherwise crash count increments)\n *\n * Retry policy: zero retries by default — the first crash escalates\n * straight to CRASHLOOP_DISABLED, matching how Android / iOS treat crashed\n * apps. Callers that prefer auto-respawn opt in by passing\n * `{maxRetries: 3, backoffMs: [2_000, 8_000, 30_000]}`; the BACKOFF state\n * machine and exponential delays are implemented and unit-tested for that\n * case.\n *\n * The controller is purely a policy engine — it doesn't actually call\n * mentraJsSpawn / mentraJsKill. Callers (MentraJSRouter) read the\n * Outcome returned from onCrash() and drive the host accordingly. This\n * makes the controller unit-testable with synthetic timer.\n */\n\nexport type CrashState =\n  | {kind: \"RUNNING\"; sinceMs: number}\n  | {kind: \"CRASHED\"; reason: string; crashedAtMs: number}\n  | {kind: \"BACKOFF\"; until: number; attempt: number; reason: string}\n  | {kind: \"CRASHLOOP_DISABLED\"; sinceMs: number; reason: string}\n\nexport interface CrashOutcome {\n  /** Caller must call `respawn(packageName)` after this delay (ms from now). */\n  scheduleRespawnAfterMs?: number\n  /** Caller should surface \"X restarted\" toast (2nd-within-5m crash). */\n  showRestartToast?: boolean\n  /** Caller should surface persistent \"crashloop disabled\" banner. */\n  surfaceCrashloopBanner?: boolean\n  /** Caller may push the crash event to dev portal / Sentry as warn-level. */\n  sentryLevel?: \"info\" | \"warning\" | \"error\"\n}\n\nexport interface CrashControllerOptions {\n  /** Override the wall clock for tests. Defaults to Date.now. */\n  now?: () => number\n  /** Backoff sequence in ms. Defaults to [2_000, 8_000, 30_000]. */\n  backoffMs?: number[]\n  /** Window in ms — N crashes inside this window escalates. Defaults to 5min. */\n  crashWindowMs?: number\n  /** Max retries before CRASHLOOP_DISABLED. Defaults to 0 — first crash\n   *  escalates immediately, matching Android / iOS app conventions. */\n  maxRetries?: number\n  /** Clean-uptime threshold that resets the retry counter. Defaults to 60s. */\n  cleanUptimeResetMs?: number\n}\n\ninterface PackageState {\n  state: CrashState\n  /** Crash timestamps inside the current window (sorted ascending). */\n  crashesInWindow: number[]\n  /** Total respawns since the package was first registered (for telemetry). */\n  totalRespawns: number\n}\n\nconst DEFAULT_BACKOFFS = [2_000, 8_000, 30_000]\nconst DEFAULT_WINDOW_MS = 5 * 60_000\nconst DEFAULT_MAX_RETRIES = 0\nconst DEFAULT_CLEAN_UPTIME_RESET_MS = 60_000\n\nexport class MentraJSCrashController {\n  private readonly now: () => number\n  private readonly backoffMs: number[]\n  private readonly crashWindowMs: number\n  private readonly maxRetries: number\n  private readonly cleanUptimeResetMs: number\n  private readonly packages: Map<string, PackageState> = new Map()\n\n  constructor(opts: CrashControllerOptions = {}) {\n    this.now = opts.now ?? (() => Date.now())\n    this.backoffMs = opts.backoffMs ?? DEFAULT_BACKOFFS\n    this.crashWindowMs = opts.crashWindowMs ?? DEFAULT_WINDOW_MS\n    this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES\n    this.cleanUptimeResetMs = opts.cleanUptimeResetMs ?? DEFAULT_CLEAN_UPTIME_RESET_MS\n  }\n\n  /** Tracking starts when MentraJSRouter spawns a fresh JSContext. */\n  onSpawn(packageName: string): void {\n    const at = this.now()\n    const prev = this.packages.get(packageName)\n    if (prev) {\n      // Carry forward the crash history; a respawn doesn't reset retry\n      // budget unless the previous RUNNING state survived >= cleanUptimeResetMs.\n      prev.state = {kind: \"RUNNING\", sinceMs: at}\n      prev.totalRespawns += 1\n    } else {\n      this.packages.set(packageName, {\n        state: {kind: \"RUNNING\", sinceMs: at},\n        crashesInWindow: [],\n        totalRespawns: 0,\n      })\n    }\n  }\n\n  /** Called when MentraJSRouter explicitly tears down (user-initiated). */\n  onKill(packageName: string): void {\n    this.packages.delete(packageName)\n  }\n\n  /**\n   * Record a crash and return the policy outcome. Caller is responsible for\n   * scheduling the respawn (timer ownership belongs at the orchestration\n   * layer that holds the host context, not here).\n   */\n  onCrash(packageName: string, reason: string): CrashOutcome {\n    const at = this.now()\n    const entry = this.packages.get(packageName) ?? {\n      state: {kind: \"RUNNING\", sinceMs: at},\n      crashesInWindow: [],\n      totalRespawns: 0,\n    }\n\n    // If the previous RUNNING window was long enough, reset the retry\n    // counter — a crash after a stable session shouldn't burn budget.\n    if (entry.state.kind === \"RUNNING\") {\n      const uptime = at - entry.state.sinceMs\n      if (uptime >= this.cleanUptimeResetMs) {\n        entry.crashesInWindow = []\n      }\n    }\n\n    // Drop crashes that fell out of the window before counting the new one.\n    const cutoff = at - this.crashWindowMs\n    entry.crashesInWindow = entry.crashesInWindow.filter((t) => t >= cutoff)\n    entry.crashesInWindow.push(at)\n    this.packages.set(packageName, entry)\n\n    const crashCount = entry.crashesInWindow.length\n\n    if (crashCount > this.maxRetries) {\n      entry.state = {kind: \"CRASHLOOP_DISABLED\", sinceMs: at, reason}\n      return {\n        surfaceCrashloopBanner: true,\n        sentryLevel: \"error\",\n      }\n    }\n\n    const attempt = crashCount - 1\n    const delayMs = this.backoffMs[Math.min(attempt, this.backoffMs.length - 1)]!\n    entry.state = {kind: \"BACKOFF\", until: at + delayMs, attempt: crashCount, reason}\n\n    return {\n      scheduleRespawnAfterMs: delayMs,\n      showRestartToast: crashCount >= 2,\n      sentryLevel: crashCount === 1 ? \"info\" : \"warning\",\n    }\n  }\n\n  /** Inspect current state — useful for tests and diagnostics. */\n  stateFor(packageName: string): CrashState | null {\n    return this.packages.get(packageName)?.state ?? null\n  }\n\n  /** Total respawns since registration — surfaced to Sentry as a counter. */\n  respawnCount(packageName: string): number {\n    return this.packages.get(packageName)?.totalRespawns ?? 0\n  }\n\n  /** Currently-disabled packages. Host UI uses this to show banners. */\n  disabledPackages(): string[] {\n    const out: string[] = []\n    for (const [name, entry] of this.packages) {\n      if (entry.state.kind === \"CRASHLOOP_DISABLED\") out.push(name)\n    }\n    return out\n  }\n\n  /** Manually re-enable a disabled package (user \"Try again\" tap). */\n  reset(packageName: string): void {\n    const entry = this.packages.get(packageName)\n    if (!entry) return\n    entry.crashesInWindow = []\n    entry.state = {kind: \"RUNNING\", sinceMs: this.now()}\n  }\n}\n"]}

package/build/services/MentraJSCrashloopReportService.d.ts

@@ -0,0 +1,9 @@
+import { type AutomaticReportSubmissionStatus } from "./AutomaticReportResult";
+export declare function submitMentraJSCrashloopReport(params: {
+    packageName: string;
+    reason: string;
+    lastLogLines?: string[];
+}): Promise<AutomaticReportSubmissionStatus>;
+export declare function startMentraJSCrashloopReportService(): void;
+export declare function stopMentraJSCrashloopReportService(): void;
+//# sourceMappingURL=MentraJSCrashloopReportService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MentraJSCrashloopReportService.d.ts","sourceRoot":"","sources":["../../src/services/MentraJSCrashloopReportService.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,+BAA+B,EACrC,MAAM,yBAAyB,CAAA;AAQhC,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAwB3C;AAeD,wBAAgB,mCAAmC,IAAI,IAAI,CAG1D;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAGzD"}

package/build/services/MentraJSCrashloopReportService.js

@@ -0,0 +1,54 @@
+import { submitAutomaticReport } from "../facades/reports";
+import { useAppStatusStore } from "../stores/apps";
+import { logAutomaticReportSubmissionStatus, toAutomaticReportSubmissionStatus, } from "./AutomaticReportResult";
+import { getMiniappEngine } from "./MiniappEngine";
+import { islandNotifications } from "./NotificationsEmitter";
+const LOG_TAG = "MentraJSCrashloopReport";
+let unsubscribe = null;
+export async function submitMentraJSCrashloopReport(params) {
+    const { packageName, reason, lastLogLines = [] } = params;
+    const app = useAppStatusStore.getState().apps.find((a) => a.packageName === packageName);
+    const appName = app?.name ?? packageName;
+    const result = await submitAutomaticReport({
+        kind: "automatic",
+        trigger: {
+            type: "automatic",
+            source: "miniapp_crashloop",
+            reason: "mentrajs_crashloop_disabled",
+            sourceAppletPackageName: packageName,
+            sourceAppletName: appName,
+        },
+        report: {
+            expectedBehavior: `${appName} should run without crashing.`,
+            actualBehavior: JSON.stringify({ reason, lastLogLines }, null, 2),
+            systemPriority: "critical",
+        },
+        throttleKey: `mentrajs_crashloop:${packageName}`,
+    });
+    const status = toAutomaticReportSubmissionStatus(result);
+    logAutomaticReportSubmissionStatus(LOG_TAG, status, packageName);
+    return status;
+}
+function handleNotification(notification) {
+    if (notification.kind !== "miniapp_crashloop" || !notification.packageName)
+        return;
+    const packageName = notification.packageName;
+    const lastLogLines = getMiniappEngine()?.router.logRing.snapshot(packageName) ?? [];
+    void submitMentraJSCrashloopReport({
+        packageName,
+        reason: notification.reason,
+        lastLogLines,
+    }).catch((error) => {
+        console.error(`[${LOG_TAG}] Unexpected error:`, error);
+    });
+}
+export function startMentraJSCrashloopReportService() {
+    if (unsubscribe)
+        return;
+    unsubscribe = islandNotifications.subscribe(handleNotification);
+}
+export function stopMentraJSCrashloopReportService() {
+    unsubscribe?.();
+    unsubscribe = null;
+}
+//# sourceMappingURL=MentraJSCrashloopReportService.js.map

package/build/services/MentraJSCrashloopReportService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MentraJSCrashloopReportService.js","sourceRoot":"","sources":["../../src/services/MentraJSCrashloopReportService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,qBAAqB,EAAC,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAChD,OAAO,EACL,kCAAkC,EAClC,iCAAiC,GAElC,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAC,gBAAgB,EAAC,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAC,mBAAmB,EAA0B,MAAM,wBAAwB,CAAA;AAEnF,MAAM,OAAO,GAAG,yBAAyB,CAAA;AAEzC,IAAI,WAAW,GAAwB,IAAI,CAAA;AAE3C,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,MAInD;IACC,MAAM,EAAC,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,EAAE,EAAC,GAAG,MAAM,CAAA;IACvD,MAAM,GAAG,GAAG,iBAAiB,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,WAAW,CAAC,CAAA;IACxF,MAAM,OAAO,GAAG,GAAG,EAAE,IAAI,IAAI,WAAW,CAAA;IACxC,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC;QACzC,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE;YACP,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,mBAAmB;YAC3B,MAAM,EAAE,6BAA6B;YACrC,uBAAuB,EAAE,WAAW;YACpC,gBAAgB,EAAE,OAAO;SAC1B;QACD,MAAM,EAAE;YACN,gBAAgB,EAAE,GAAG,OAAO,+BAA+B;YAC3D,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,EAAC,MAAM,EAAE,YAAY,EAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,cAAc,EAAE,UAAU;SAC3B;QACD,WAAW,EAAE,sBAAsB,WAAW,EAAE;KACjD,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,iCAAiC,CAAC,MAAM,CAAC,CAAA;IACxD,kCAAkC,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAA;IAChE,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,YAAgC;IAC1D,IAAI,YAAY,CAAC,IAAI,KAAK,mBAAmB,IAAI,CAAC,YAAY,CAAC,WAAW;QAAE,OAAM;IAClF,MAAM,WAAW,GAAG,YAAY,CAAC,WAAW,CAAA;IAC5C,MAAM,YAAY,GAAG,gBAAgB,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,CAAA;IACnF,KAAK,6BAA6B,CAAC;QACjC,WAAW;QACX,MAAM,EAAE,YAAY,CAAC,MAAM;QAC3B,YAAY;KACb,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACjB,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,qBAAqB,EAAE,KAAK,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,mCAAmC;IACjD,IAAI,WAAW;QAAE,OAAM;IACvB,WAAW,GAAG,mBAAmB,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,kCAAkC;IAChD,WAAW,EAAE,EAAE,CAAA;IACf,WAAW,GAAG,IAAI,CAAA;AACpB,CAAC","sourcesContent":["import {submitAutomaticReport} from \"../facades/reports\"\nimport {useAppStatusStore} from \"../stores/apps\"\nimport {\n  logAutomaticReportSubmissionStatus,\n  toAutomaticReportSubmissionStatus,\n  type AutomaticReportSubmissionStatus,\n} from \"./AutomaticReportResult\"\nimport {getMiniappEngine} from \"./MiniappEngine\"\nimport {islandNotifications, type IslandNotification} from \"./NotificationsEmitter\"\n\nconst LOG_TAG = \"MentraJSCrashloopReport\"\n\nlet unsubscribe: (() => void) | null = null\n\nexport async function submitMentraJSCrashloopReport(params: {\n  packageName: string\n  reason: string\n  lastLogLines?: string[]\n}): Promise<AutomaticReportSubmissionStatus> {\n  const {packageName, reason, lastLogLines = []} = params\n  const app = useAppStatusStore.getState().apps.find((a) => a.packageName === packageName)\n  const appName = app?.name ?? packageName\n  const result = await submitAutomaticReport({\n    kind: \"automatic\",\n    trigger: {\n      type: \"automatic\",\n      source: \"miniapp_crashloop\",\n      reason: \"mentrajs_crashloop_disabled\",\n      sourceAppletPackageName: packageName,\n      sourceAppletName: appName,\n    },\n    report: {\n      expectedBehavior: `${appName} should run without crashing.`,\n      actualBehavior: JSON.stringify({reason, lastLogLines}, null, 2),\n      systemPriority: \"critical\",\n    },\n    throttleKey: `mentrajs_crashloop:${packageName}`,\n  })\n\n  const status = toAutomaticReportSubmissionStatus(result)\n  logAutomaticReportSubmissionStatus(LOG_TAG, status, packageName)\n  return status\n}\n\nfunction handleNotification(notification: IslandNotification): void {\n  if (notification.kind !== \"miniapp_crashloop\" || !notification.packageName) return\n  const packageName = notification.packageName\n  const lastLogLines = getMiniappEngine()?.router.logRing.snapshot(packageName) ?? []\n  void submitMentraJSCrashloopReport({\n    packageName,\n    reason: notification.reason,\n    lastLogLines,\n  }).catch((error) => {\n    console.error(`[${LOG_TAG}] Unexpected error:`, error)\n  })\n}\n\nexport function startMentraJSCrashloopReportService(): void {\n  if (unsubscribe) return\n  unsubscribe = islandNotifications.subscribe(handleNotification)\n}\n\nexport function stopMentraJSCrashloopReportService(): void {\n  unsubscribe?.()\n  unsubscribe = null\n}\n"]}

package/build/services/MentraJSLogPipeline.d.ts

@@ -0,0 +1,87 @@
+/**
+ * MentraJSLogPipeline — the three log-side utilities that
+ * MentraJSRouter's `__log` handler runs every miniapp log line through:
+ *
+ *   1. redactSecrets — walks a value (string / array / object) and
+ *      replaces anything matching the secret-key regex
+ *      (token|password|secret|auth|bearer|key|api[_-]?key) with
+ *      "[REDACTED]". Conservative: over-redaction is preferable to
+ *      leaking a real secret into Sentry breadcrumbs.
+ *
+ *   2. MentraJSLogThrottle — token-bucket rate limiter, 100 lines/min
+ *      sustained with a 500-line burst, per miniapp. Excess is dropped
+ *      and surfaced once as a `[throttled N]` summary. Stops a
+ *      misbehaving miniapp from drowning the host's log stream.
+ *
+ *   3. MentraJSLogRingBuffer — fixed-size circular buffer (default 200)
+ *      holding the most recent log lines per miniapp. Dumped into the
+ *      crash report so post-mortem tooling sees the miniapp's last words.
+ *
+ * All three are pure (no React Native imports) and unit-tested in
+ * MentraJSLogPipeline.test.ts.
+ */
+/**
+ * Redact obvious secret-like strings from a log line. Walks the JSON
+ * argument list, replacing any value that looks like a secret with
+ * `[REDACTED]`. Conservative — false negatives are fine, false positives
+ * are bad (devs lose visibility into their own data).
+ *
+ * Heuristics:
+ *   1. Top-level strings matching SECRET_KEY_PATTERN get the entire value
+ *      redacted (e.g. `console.log("token=abc123")` → `[REDACTED]`).
+ *   2. Object keys matching the pattern get their values replaced.
+ *   3. Arrays are walked element-by-element.
+ *
+ * Returns a new structure — never mutates the input.
+ */
+export declare function redactSecrets(value: unknown): unknown;
+/**
+ * Token bucket throttler. Per-package: 100 logs/min sustained with a 500
+ * burst. Excess lines are dropped; the first drop in each refill window
+ * emits a `[throttled N]` synthetic line so the dev knows messages
+ * were lost.
+ */
+export interface ThrottleOptions {
+    /** Tokens added per second. Default 100/60 = ~1.67. */
+    tokensPerSecond?: number;
+    /** Bucket capacity. Default 500. */
+    bucketCapacity?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export declare class MentraJSLogThrottle {
+    private readonly tokensPerSecond;
+    private readonly bucketCapacity;
+    private readonly now;
+    private readonly buckets;
+    constructor(opts?: ThrottleOptions);
+    /**
+     * Try to consume one token for the named package. Returns either:
+     *   - `{allowed: true}` — caller emits the original log line.
+     *   - `{allowed: false, throttledLine}` — caller may emit the
+     *     synthetic throttled line (the first drop in each window).
+     *     If `throttledLine` is undefined the caller drops silently
+     *     (subsequent drops in the same window).
+     */
+    consume(packageName: string): {
+        allowed: true;
+    } | {
+        allowed: false;
+        throttledLine?: string;
+    };
+    /** Test/dev — reset all buckets. */
+    resetForTests(): void;
+}
+/**
+ * In-memory ring buffer holding the last N lines per package. Useful as a
+ * "last words" context attached to crash reports.
+ */
+export declare class MentraJSLogRingBuffer {
+    private readonly capacity;
+    private readonly buffers;
+    constructor(capacityPerPackage?: number);
+    push(packageName: string, line: string): void;
+    snapshot(packageName: string): string[];
+    clear(packageName: string): void;
+}
+//# sourceMappingURL=MentraJSLogPipeline.d.ts.map