@glassly/engine 0.1.0-dev.0

package/build/services/MicStateCoordinator.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MicStateCoordinator
+ *
+ * Owns local-miniapp-driven microphone requirements.
+ *
+ * Local miniapps subscribe to audio_chunk / transcription streams.
+ * This coordinator pushes the aggregate local requirement set to BluetoothSdk
+ * so the mic runs whenever at least one local consumer needs it.
+ */
+type MicGate = "vad" | "loudnessGate";
+interface ConfiguredMicGates {
+    vadEnabled?: boolean | null;
+    loudnessGateEnabled?: boolean | null;
+}
+declare class MicStateCoordinator {
+    private static instance;
+    private localWantsPcm;
+    private localWantsLc3;
+    private configuredVad;
+    private configuredLoudnessGate;
+    private readonly miniappVadOverrides;
+    private readonly miniappLoudnessGateOverrides;
+    private overrideSequence;
+    private constructor();
+    static getInstance(): MicStateCoordinator;
+    /**
+     * Update local miniapp requirements. Called by LocalMiniappRuntime when
+     * the aggregated set of local subscriptions changes.
+     */
+    setLocalRequirements(req: {
+        pcm: boolean;
+        lc3: boolean;
+    } & ConfiguredMicGates): void;
+    /**
+     * Apply a miniapp-owned gate override without changing the OS preference.
+     * Overrides are lifecycle-scoped and last-live-owner-wins independently for
+     * VAD and Barrier.
+     */
+    setMiniappGateOverride(packageName: string, gate: MicGate, enabled: boolean, configured?: ConfiguredMicGates): Promise<void>;
+    /**
+     * Remove every gate override owned by a miniapp. This is synchronous so
+     * unregister can drop ownership before recomputing aggregate mic state.
+     */
+    clearMiniappGateOverrides(packageName: string): boolean;
+    /** Re-apply the current runtime policy after an owner is released. */
+    syncEffectiveGatePolicy(configured?: ConfiguredMicGates): Promise<void>;
+    /**
+     * Preserve the runtime microphone contract when the persisted device
+     * settings are replayed (for example after a glasses reconnect). Active
+     * miniapp gate overrides replace the OS values, and raw PCM keeps VAD off
+     * until the last raw-audio consumer unsubscribes.
+     */
+    applyRuntimeOverrides(settings: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Apply the complete current gate policy without treating the input as an OS
+     * preference update. Used by debounced mic-requirement writes, whose queued
+     * gate values may be stale after an override is acquired or released.
+     */
+    applyEffectiveGatePolicy(settings: Record<string, unknown>): Record<string, unknown>;
+    private applyActiveRuntimeOverrides;
+    /**
+     * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for
+     * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.
+     */
+    private applyUnion;
+    private rememberConfiguredGates;
+    private overridesFor;
+    private latestOverride;
+    private effectiveGatePatch;
+    /**
+     * Reset all requirements to off. Called during cleanup.
+     */
+    reset(): void;
+    cleanup(): void;
+}
+declare const micStateCoordinator: MicStateCoordinator;
+export default micStateCoordinator;
+//# sourceMappingURL=MicStateCoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MicStateCoordinator.d.ts","sourceRoot":"","sources":["../../src/services/MicStateCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,KAAK,OAAO,GAAG,KAAK,GAAG,cAAc,CAAA;AAOrC,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3B,mBAAmB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CACrC;AAkBD,cAAM,mBAAmB;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAG1D,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IACtE,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAkC;IAC/E,OAAO,CAAC,gBAAgB,CAAI;IAE5B,OAAO;WAEO,WAAW,IAAI,mBAAmB;IAOhD;;;OAGG;IACI,oBAAoB,CAAC,GAAG,EAAE;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAC,GAAG,kBAAkB,GAAG,IAAI;IAQzF;;;;OAIG;IACU,sBAAsB,CACjC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,kBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC;IAoBhB;;;OAGG;IACI,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAM9D,sEAAsE;IACzD,uBAAuB,CAAC,UAAU,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxF;;;;;OAKG;IACI,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAaxF;;;;OAIG;IACI,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAO3F,OAAO,CAAC,2BAA2B;IAiBnC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,kBAAkB;IAmB1B;;OAEG;IACI,KAAK,IAAI,IAAI;IAMb,OAAO,IAAI,IAAI;CAOvB;AAED,QAAA,MAAM,mBAAmB,qBAAoC,CAAA;AAC7D,eAAe,mBAAmB,CAAA"}

package/build/services/MicStateCoordinator.js

@@ -0,0 +1,219 @@
+/**
+ * MicStateCoordinator
+ *
+ * Owns local-miniapp-driven microphone requirements.
+ *
+ * Local miniapps subscribe to audio_chunk / transcription streams.
+ * This coordinator pushes the aggregate local requirement set to BluetoothSdk
+ * so the mic runs whenever at least one local consumer needs it.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal";
+import { createDebouncedPatchFlusher } from "../utils/debouncedPatch";
+const LOG_TAG = "MIC_COORDINATOR";
+/** Mic-requirement flips are debounced (300ms) and merged into one BLE write
+ *  (wire v2 keeps BLE JSON small and infrequent). */
+const flushMicRequirementsPatch = createDebouncedPatchFlusher((patch) => {
+    try {
+        // Resolve runtime overrides at flush time. A miniapp can acquire/release a
+        // gate override during the debounce window, and a captured stale value
+        // must not win after that lifecycle transition.
+        const runtimePatch = micStateCoordinator.applyEffectiveGatePolicy(patch);
+        void Promise.resolve(BluetoothSdk.updateBluetoothSettings(runtimePatch)).catch((err) => {
+            console.error(`${LOG_TAG}: failed to apply mic requirements:`, err);
+        });
+    }
+    catch (err) {
+        console.error(`${LOG_TAG}: failed to apply mic requirements:`, err);
+    }
+}, 300);
+class MicStateCoordinator {
+    static instance = null;
+    // Local miniapp requirements (set when miniapps subscribe to audio streams)
+    localWantsPcm = false;
+    localWantsLc3 = false;
+    configuredVad;
+    configuredLoudnessGate;
+    miniappVadOverrides = new Map();
+    miniappLoudnessGateOverrides = new Map();
+    overrideSequence = 0;
+    constructor() { }
+    static getInstance() {
+        if (!MicStateCoordinator.instance) {
+            MicStateCoordinator.instance = new MicStateCoordinator();
+        }
+        return MicStateCoordinator.instance;
+    }
+    /**
+     * Update local miniapp requirements. Called by LocalMiniappRuntime when
+     * the aggregated set of local subscriptions changes.
+     */
+    setLocalRequirements(req) {
+        this.localWantsPcm = req.pcm;
+        this.localWantsLc3 = req.lc3;
+        this.rememberConfiguredGates(req);
+        console.log(`${LOG_TAG}: local requirements updated — pcm=${req.pcm} lc3=${req.lc3}`);
+        this.applyUnion();
+    }
+    /**
+     * Apply a miniapp-owned gate override without changing the OS preference.
+     * Overrides are lifecycle-scoped and last-live-owner-wins independently for
+     * VAD and Barrier.
+     */
+    async setMiniappGateOverride(packageName, gate, enabled, configured = {}) {
+        this.rememberConfiguredGates(configured);
+        const overrides = this.overridesFor(gate);
+        const previous = overrides.get(packageName);
+        const next = { enabled, order: ++this.overrideSequence };
+        overrides.set(packageName, next);
+        try {
+            await BluetoothSdk.updateBluetoothSettings(this.effectiveGatePatch());
+        }
+        catch (error) {
+            // Do not roll back a newer request from the same package that landed
+            // while this native write was in flight.
+            if (overrides.get(packageName) === next) {
+                if (previous)
+                    overrides.set(packageName, previous);
+                else
+                    overrides.delete(packageName);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Remove every gate override owned by a miniapp. This is synchronous so
+     * unregister can drop ownership before recomputing aggregate mic state.
+     */
+    clearMiniappGateOverrides(packageName) {
+        const removedVad = this.miniappVadOverrides.delete(packageName);
+        const removedLoudness = this.miniappLoudnessGateOverrides.delete(packageName);
+        return removedVad || removedLoudness;
+    }
+    /** Re-apply the current runtime policy after an owner is released. */
+    async syncEffectiveGatePolicy(configured = {}) {
+        this.rememberConfiguredGates(configured);
+        const patch = this.effectiveGatePatch();
+        if (Object.keys(patch).length === 0)
+            return;
+        await BluetoothSdk.updateBluetoothSettings(patch);
+    }
+    /**
+     * Preserve the runtime microphone contract when the persisted device
+     * settings are replayed (for example after a glasses reconnect). Active
+     * miniapp gate overrides replace the OS values, and raw PCM keeps VAD off
+     * until the last raw-audio consumer unsubscribes.
+     */
+    applyRuntimeOverrides(settings) {
+        this.rememberConfiguredGates({
+            vadEnabled: typeof settings.voice_activity_detection_enabled === "boolean"
+                ? settings.voice_activity_detection_enabled
+                : undefined,
+            loudnessGateEnabled: typeof settings.loudness_gate_enabled === "boolean" ? settings.loudness_gate_enabled : undefined,
+        });
+        return this.applyActiveRuntimeOverrides(settings);
+    }
+    /**
+     * Apply the complete current gate policy without treating the input as an OS
+     * preference update. Used by debounced mic-requirement writes, whose queued
+     * gate values may be stale after an override is acquired or released.
+     */
+    applyEffectiveGatePolicy(settings) {
+        return {
+            ...settings,
+            ...this.effectiveGatePatch(),
+        };
+    }
+    applyActiveRuntimeOverrides(settings) {
+        const runtimeSettings = { ...settings };
+        const vadOverride = this.latestOverride(this.miniappVadOverrides);
+        const loudnessOverride = this.latestOverride(this.miniappLoudnessGateOverrides);
+        if (this.localWantsPcm) {
+            runtimeSettings.voice_activity_detection_enabled = false;
+        }
+        else if (vadOverride) {
+            runtimeSettings.voice_activity_detection_enabled = vadOverride.enabled;
+        }
+        if (loudnessOverride) {
+            runtimeSettings.loudness_gate_enabled = loudnessOverride.enabled;
+        }
+        return runtimeSettings;
+    }
+    /**
+     * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for
+     * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.
+     */
+    applyUnion() {
+        const shouldSendPcm = this.localWantsPcm;
+        const shouldSendLc3 = this.localWantsLc3;
+        // console.log(
+        //   `${LOG_TAG}: applying requirements — pcm=${shouldSendPcm} lc3=${shouldSendLc3}`,
+        // )
+        // The mic control plane is a direct btsdk call now (was a host setMicRequirements
+        // hook) so a bare OEM streams audio without wiring it.
+        const patch = {
+            should_send_pcm: shouldSendPcm,
+            should_send_lc3: shouldSendLc3,
+            should_send_transcript: false,
+            ...this.effectiveGatePatch(),
+        };
+        flushMicRequirementsPatch(patch);
+    }
+    rememberConfiguredGates(configured) {
+        // null means the connected device intentionally omits that setting.
+        // undefined means the caller is not updating the remembered preference.
+        if (configured.vadEnabled !== undefined) {
+            this.configuredVad = configured.vadEnabled ?? undefined;
+        }
+        if (configured.loudnessGateEnabled !== undefined) {
+            this.configuredLoudnessGate = configured.loudnessGateEnabled ?? undefined;
+        }
+    }
+    overridesFor(gate) {
+        return gate === "vad" ? this.miniappVadOverrides : this.miniappLoudnessGateOverrides;
+    }
+    latestOverride(overrides) {
+        let latest;
+        for (const entry of overrides.values()) {
+            if (!latest || entry.order > latest.order)
+                latest = entry;
+        }
+        return latest;
+    }
+    effectiveGatePatch() {
+        const patch = {};
+        const vadOverride = this.latestOverride(this.miniappVadOverrides);
+        const loudnessOverride = this.latestOverride(this.miniappLoudnessGateOverrides);
+        // Hardware VAD suppresses silence. Raw-audio consumers need a continuous
+        // timeline, so their requirement wins over both OS and miniapp VAD values.
+        if (this.localWantsPcm)
+            patch.voice_activity_detection_enabled = false;
+        else if (vadOverride)
+            patch.voice_activity_detection_enabled = vadOverride.enabled;
+        else if (this.configuredVad !== undefined)
+            patch.voice_activity_detection_enabled = this.configuredVad;
+        if (loudnessOverride)
+            patch.loudness_gate_enabled = loudnessOverride.enabled;
+        else if (this.configuredLoudnessGate !== undefined) {
+            patch.loudness_gate_enabled = this.configuredLoudnessGate;
+        }
+        return patch;
+    }
+    /**
+     * Reset all requirements to off. Called during cleanup.
+     */
+    reset() {
+        this.localWantsPcm = false;
+        this.localWantsLc3 = false;
+        this.applyUnion();
+    }
+    cleanup() {
+        console.log(`${LOG_TAG}: cleanup()`);
+        this.miniappVadOverrides.clear();
+        this.miniappLoudnessGateOverrides.clear();
+        this.reset();
+        MicStateCoordinator.instance = null;
+    }
+}
+const micStateCoordinator = MicStateCoordinator.getInstance();
+export default micStateCoordinator;
+//# sourceMappingURL=MicStateCoordinator.js.map

package/build/services/MicStateCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicStateCoordinator.js","sourceRoot":"","sources":["../../src/services/MicStateCoordinator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MicStateCoordinator\n *\n * Owns local-miniapp-driven microphone requirements.\n *\n * Local miniapps subscribe to audio_chunk / transcription streams.\n * This coordinator pushes the aggregate local requirement set to BluetoothSdk\n * so the mic runs whenever at least one local consumer needs it.\n */\n\nimport BluetoothSdk from \"@glassly/bluetooth-sdk/internal\"\n\nimport {createDebouncedPatchFlusher} from \"../utils/debouncedPatch\"\n\nconst LOG_TAG = \"MIC_COORDINATOR\"\n\ntype MicGate = \"vad\" | \"loudnessGate\"\n\ninterface GateOverride {\n  enabled: boolean\n  order: number\n}\n\ninterface ConfiguredMicGates {\n  vadEnabled?: boolean | null\n  loudnessGateEnabled?: boolean | null\n}\n\n/** Mic-requirement flips are debounced (300ms) and merged into one BLE write\n *  (wire v2 keeps BLE JSON small and infrequent). */\nconst flushMicRequirementsPatch = createDebouncedPatchFlusher<Record<string, unknown>>((patch) => {\n  try {\n    // Resolve runtime overrides at flush time. A miniapp can acquire/release a\n    // gate override during the debounce window, and a captured stale value\n    // must not win after that lifecycle transition.\n    const runtimePatch = micStateCoordinator.applyEffectiveGatePolicy(patch)\n    void Promise.resolve(BluetoothSdk.updateBluetoothSettings(runtimePatch)).catch((err) => {\n      console.error(`${LOG_TAG}: failed to apply mic requirements:`, err)\n    })\n  } catch (err) {\n    console.error(`${LOG_TAG}: failed to apply mic requirements:`, err)\n  }\n}, 300)\n\nclass MicStateCoordinator {\n  private static instance: MicStateCoordinator | null = null\n\n  // Local miniapp requirements (set when miniapps subscribe to audio streams)\n  private localWantsPcm = false\n  private localWantsLc3 = false\n  private configuredVad: boolean | undefined\n  private configuredLoudnessGate: boolean | undefined\n  private readonly miniappVadOverrides = new Map<string, GateOverride>()\n  private readonly miniappLoudnessGateOverrides = new Map<string, GateOverride>()\n  private overrideSequence = 0\n\n  private constructor() {}\n\n  public static getInstance(): MicStateCoordinator {\n    if (!MicStateCoordinator.instance) {\n      MicStateCoordinator.instance = new MicStateCoordinator()\n    }\n    return MicStateCoordinator.instance\n  }\n\n  /**\n   * Update local miniapp requirements. Called by LocalMiniappRuntime when\n   * the aggregated set of local subscriptions changes.\n   */\n  public setLocalRequirements(req: {pcm: boolean; lc3: boolean} & ConfiguredMicGates): void {\n    this.localWantsPcm = req.pcm\n    this.localWantsLc3 = req.lc3\n    this.rememberConfiguredGates(req)\n    console.log(`${LOG_TAG}: local requirements updated — pcm=${req.pcm} lc3=${req.lc3}`)\n    this.applyUnion()\n  }\n\n  /**\n   * Apply a miniapp-owned gate override without changing the OS preference.\n   * Overrides are lifecycle-scoped and last-live-owner-wins independently for\n   * VAD and Barrier.\n   */\n  public async setMiniappGateOverride(\n    packageName: string,\n    gate: MicGate,\n    enabled: boolean,\n    configured: ConfiguredMicGates = {},\n  ): Promise<void> {\n    this.rememberConfiguredGates(configured)\n    const overrides = this.overridesFor(gate)\n    const previous = overrides.get(packageName)\n    const next = {enabled, order: ++this.overrideSequence}\n    overrides.set(packageName, next)\n\n    try {\n      await BluetoothSdk.updateBluetoothSettings(this.effectiveGatePatch())\n    } catch (error) {\n      // Do not roll back a newer request from the same package that landed\n      // while this native write was in flight.\n      if (overrides.get(packageName) === next) {\n        if (previous) overrides.set(packageName, previous)\n        else overrides.delete(packageName)\n      }\n      throw error\n    }\n  }\n\n  /**\n   * Remove every gate override owned by a miniapp. This is synchronous so\n   * unregister can drop ownership before recomputing aggregate mic state.\n   */\n  public clearMiniappGateOverrides(packageName: string): boolean {\n    const removedVad = this.miniappVadOverrides.delete(packageName)\n    const removedLoudness = this.miniappLoudnessGateOverrides.delete(packageName)\n    return removedVad || removedLoudness\n  }\n\n  /** Re-apply the current runtime policy after an owner is released. */\n  public async syncEffectiveGatePolicy(configured: ConfiguredMicGates = {}): Promise<void> {\n    this.rememberConfiguredGates(configured)\n    const patch = this.effectiveGatePatch()\n    if (Object.keys(patch).length === 0) return\n    await BluetoothSdk.updateBluetoothSettings(patch)\n  }\n\n  /**\n   * Preserve the runtime microphone contract when the persisted device\n   * settings are replayed (for example after a glasses reconnect). Active\n   * miniapp gate overrides replace the OS values, and raw PCM keeps VAD off\n   * until the last raw-audio consumer unsubscribes.\n   */\n  public applyRuntimeOverrides(settings: Record<string, unknown>): Record<string, unknown> {\n    this.rememberConfiguredGates({\n      vadEnabled:\n        typeof settings.voice_activity_detection_enabled === \"boolean\"\n          ? settings.voice_activity_detection_enabled\n          : undefined,\n      loudnessGateEnabled:\n        typeof settings.loudness_gate_enabled === \"boolean\" ? settings.loudness_gate_enabled : undefined,\n    })\n\n    return this.applyActiveRuntimeOverrides(settings)\n  }\n\n  /**\n   * Apply the complete current gate policy without treating the input as an OS\n   * preference update. Used by debounced mic-requirement writes, whose queued\n   * gate values may be stale after an override is acquired or released.\n   */\n  public applyEffectiveGatePolicy(settings: Record<string, unknown>): Record<string, unknown> {\n    return {\n      ...settings,\n      ...this.effectiveGatePatch(),\n    }\n  }\n\n  private applyActiveRuntimeOverrides(settings: Record<string, unknown>): Record<string, unknown> {\n    const runtimeSettings = {...settings}\n    const vadOverride = this.latestOverride(this.miniappVadOverrides)\n    const loudnessOverride = this.latestOverride(this.miniappLoudnessGateOverrides)\n\n    if (this.localWantsPcm) {\n      runtimeSettings.voice_activity_detection_enabled = false\n    } else if (vadOverride) {\n      runtimeSettings.voice_activity_detection_enabled = vadOverride.enabled\n    }\n    if (loudnessOverride) {\n      runtimeSettings.loudness_gate_enabled = loudnessOverride.enabled\n    }\n\n    return runtimeSettings\n  }\n\n  /**\n   * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for\n   * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.\n   */\n  private applyUnion(): void {\n    const shouldSendPcm = this.localWantsPcm\n    const shouldSendLc3 = this.localWantsLc3\n\n    // console.log(\n    //   `${LOG_TAG}: applying requirements — pcm=${shouldSendPcm} lc3=${shouldSendLc3}`,\n    // )\n\n    // The mic control plane is a direct btsdk call now (was a host setMicRequirements\n    // hook) so a bare OEM streams audio without wiring it.\n    const patch: Record<string, unknown> = {\n      should_send_pcm: shouldSendPcm,\n      should_send_lc3: shouldSendLc3,\n      should_send_transcript: false,\n      ...this.effectiveGatePatch(),\n    }\n\n    flushMicRequirementsPatch(patch)\n  }\n\n  private rememberConfiguredGates(configured: ConfiguredMicGates): void {\n    // null means the connected device intentionally omits that setting.\n    // undefined means the caller is not updating the remembered preference.\n    if (configured.vadEnabled !== undefined) {\n      this.configuredVad = configured.vadEnabled ?? undefined\n    }\n    if (configured.loudnessGateEnabled !== undefined) {\n      this.configuredLoudnessGate = configured.loudnessGateEnabled ?? undefined\n    }\n  }\n\n  private overridesFor(gate: MicGate): Map<string, GateOverride> {\n    return gate === \"vad\" ? this.miniappVadOverrides : this.miniappLoudnessGateOverrides\n  }\n\n  private latestOverride(overrides: Map<string, GateOverride>): GateOverride | undefined {\n    let latest: GateOverride | undefined\n    for (const entry of overrides.values()) {\n      if (!latest || entry.order > latest.order) latest = entry\n    }\n    return latest\n  }\n\n  private effectiveGatePatch(): Record<string, unknown> {\n    const patch: Record<string, unknown> = {}\n    const vadOverride = this.latestOverride(this.miniappVadOverrides)\n    const loudnessOverride = this.latestOverride(this.miniappLoudnessGateOverrides)\n\n    // Hardware VAD suppresses silence. Raw-audio consumers need a continuous\n    // timeline, so their requirement wins over both OS and miniapp VAD values.\n    if (this.localWantsPcm) patch.voice_activity_detection_enabled = false\n    else if (vadOverride) patch.voice_activity_detection_enabled = vadOverride.enabled\n    else if (this.configuredVad !== undefined) patch.voice_activity_detection_enabled = this.configuredVad\n\n    if (loudnessOverride) patch.loudness_gate_enabled = loudnessOverride.enabled\n    else if (this.configuredLoudnessGate !== undefined) {\n      patch.loudness_gate_enabled = this.configuredLoudnessGate\n    }\n\n    return patch\n  }\n\n  /**\n   * Reset all requirements to off. Called during cleanup.\n   */\n  public reset(): void {\n    this.localWantsPcm = false\n    this.localWantsLc3 = false\n    this.applyUnion()\n  }\n\n  public cleanup(): void {\n    console.log(`${LOG_TAG}: cleanup()`)\n    this.miniappVadOverrides.clear()\n    this.miniappLoudnessGateOverrides.clear()\n    this.reset()\n    MicStateCoordinator.instance = null\n  }\n}\n\nconst micStateCoordinator = MicStateCoordinator.getInstance()\nexport default micStateCoordinator\n"]}

package/build/services/MiniappEngine.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MiniappEngine — constructs the GlasslyJS router singletons (crash controller,
+ * UI router, JS router), binds them to the native Crust module + the launcher,
+ * wires the dev-server background-respawn signal, and starts the message pump.
+ *
+ * Engine owns this so a bare OEM's `engine.start()` brings up the local-miniapp
+ * engine with no host construction step. Host-only concerns that remain outside
+ * engine, such as Glassly-app crashloop telemetry, are attached by the host after
+ * this returns via `router.onCrashloop` / `router.onRestartToast`.
+ *
+ * Idempotent — `ensureMiniappEngine()` returns the same singletons on every call,
+ * so it's safe to call from both `engine.start()` and the host bootstrap.
+ */
+import { JSCrashController } from "./JSCrashController";
+import { JSRouter } from "./JSRouter";
+import { UIRouter } from "./UIRouter";
+export interface MiniappEngine {
+    router: JSRouter;
+    uiRouter: UIRouter;
+    crashController: JSCrashController;
+}
+/**
+ * Construct (once) and return the GlasslyJS engine singletons. Starts the router's
+ * message pump on first call. Subsequent calls return the same instances.
+ */
+export declare function ensureMiniappEngine(): MiniappEngine;
+/** Stop the GlasslyJS message pump and tear down router-managed JSContexts. */
+export declare function stopMiniappEngine(): Promise<void>;
+/** Returns the engine singletons if already constructed, else null. */
+export declare function getMiniappEngine(): MiniappEngine | null;
+//# sourceMappingURL=MiniappEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappEngine.d.ts","sourceRoot":"","sources":["../../src/services/MiniappEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAC,QAAQ,EAAsB,MAAM,YAAY,CAAA;AACxD,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAA;AAEnC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,EAAE,QAAQ,CAAA;IAClB,eAAe,EAAE,iBAAiB,CAAA;CACnC;AAwCD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAyCnD;AAED,+EAA+E;AAC/E,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBvD;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD"}

package/build/services/MiniappEngine.js

@@ -0,0 +1,119 @@
+/**
+ * MiniappEngine — constructs the GlasslyJS router singletons (crash controller,
+ * UI router, JS router), binds them to the native Crust module + the launcher,
+ * wires the dev-server background-respawn signal, and starts the message pump.
+ *
+ * Engine owns this so a bare OEM's `engine.start()` brings up the local-miniapp
+ * engine with no host construction step. Host-only concerns that remain outside
+ * engine, such as Glassly-app crashloop telemetry, are attached by the host after
+ * this returns via `router.onCrashloop` / `router.onRestartToast`.
+ *
+ * Idempotent — `ensureMiniappEngine()` returns the same singletons on every call,
+ * so it's safe to call from both `engine.start()` and the host bootstrap.
+ */
+import CrustModule from "@glassly/crust";
+import devServerBridge from "./DevServerBridge";
+import localMiniappRuntime from "./LocalMiniappRuntime";
+import { miniappLauncher } from "./MiniappLauncher";
+import { JSCrashController } from "./JSCrashController";
+import { JSRouter } from "./JSRouter";
+import { UIRouter } from "./UIRouter";
+let engine = null;
+function wireDevServerRespawnBackground(router, uiRouter) {
+    devServerBridge.onRespawnBackground(async (packageName) => {
+        try {
+            // Re-resolve the freshly built bundle (dev: HTTP off the dev server;
+            // released: file:// snapshot) via the launcher's shared recipe. Carries
+            // the declared permissions + manifest across the respawn — omitting them
+            // would respawn the JSContext with no permissions, so SUBSCRIBE gates and
+            // per-call dispatch checks would start rejecting after a background
+            // hot-reload.
+            const resolved = await miniappLauncher.resolveBundle(packageName);
+            if (!resolved) {
+                console.warn(`GlasslyJS: respawn-bg could not resolve bundle for ${packageName}`);
+                return;
+            }
+            // Force a respawn (kill + spawn) rather than launcher.ensureRunning,
+            // which is idempotent and would no-op an already-registered context.
+            await router.unregister(packageName);
+            const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {
+                permissions: resolved.declaredPermissions,
+                installedManifest: resolved.installedManifest,
+            });
+            if (!ok) {
+                console.warn(`GlasslyJS: respawn-bg failed for ${packageName}`);
+                return;
+            }
+            // The respawned JSContext is a fresh MiniappSession with ui.bound false.
+            // The mounted WebView won't re-fire glassly.ready() (it's latched), so
+            // re-announce it so RPC replies (glassly.request) reach the UI again
+            // instead of being dropped while unbound.
+            uiRouter.notifyReopen(packageName);
+        }
+        catch (e) {
+            console.warn(`GlasslyJS: respawn-bg threw for ${packageName}:`, e);
+        }
+    });
+}
+/**
+ * Construct (once) and return the GlasslyJS engine singletons. Starts the router's
+ * message pump on first call. Subsequent calls return the same instances.
+ */
+export function ensureMiniappEngine() {
+    if (engine) {
+        wireDevServerRespawnBackground(engine.router, engine.uiRouter);
+        engine.router.start();
+        return engine;
+    }
+    // The Crust native module's published TS typing doesn't include the new
+    // js* functions until expo prebuild regenerates it; cast to the binding
+    // shapes the routers expect.
+    const crust = CrustModule;
+    const crashController = new JSCrashController({
+        maxRetries: 3,
+    });
+    const uiRouter = new UIRouter({
+        jsDispatchToJs: (packageName, envelope) => CrustModule.jsDispatchToJs(packageName, envelope),
+    });
+    const router = new JSRouter(localMiniappRuntime, crust);
+    router.crashController = crashController;
+    router.uiRouter = uiRouter;
+    // Hand the router to the engine MiniappLauncher so headless launch/teardown
+    // (apps.ts start/stop, the action broker, the WebView mount path) all spawn
+    // through one place.
+    miniappLauncher.configure({ router });
+    // Wire up the dev server's "respawn-bg" signal so a touch under
+    // src/background/ kills + re-spawns the JSContext with the latest bundle.
+    // The WebView reload path stays separate (devServerBridge.onReload).
+    wireDevServerRespawnBackground(router, uiRouter);
+    router.start();
+    engine = { router, uiRouter, crashController };
+    return engine;
+}
+/** Stop the GlasslyJS message pump and tear down router-managed JSContexts. */
+export async function stopMiniappEngine() {
+    const current = engine;
+    if (!current)
+        return;
+    // Null the singleton BEFORE the async teardown below: a concurrent
+    // ensureMiniappEngine() must construct fresh instead of re-starting (and
+    // re-subscribing) the router that is mid-teardown, which would leak a zombie
+    // Crust subscription once this function finishes.
+    engine = null;
+    devServerBridge.clearRespawnBackgroundHandler();
+    current.router.stop();
+    const packages = current.router.registeredPackages();
+    await Promise.all(packages.map(async (packageName) => {
+        try {
+            await current.router.unregister(packageName);
+        }
+        catch (err) {
+            console.warn(`GlasslyJS: failed to unregister ${packageName} during stop:`, err);
+        }
+    }));
+}
+/** Returns the engine singletons if already constructed, else null. */
+export function getMiniappEngine() {
+    return engine;
+}
+//# sourceMappingURL=MiniappEngine.js.map

package/build/services/MiniappEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappEngine.js","sourceRoot":"","sources":["../../src/services/MiniappEngine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MiniappEngine — constructs the GlasslyJS router singletons (crash controller,\n * UI router, JS router), binds them to the native Crust module + the launcher,\n * wires the dev-server background-respawn signal, and starts the message pump.\n *\n * Engine owns this so a bare OEM's `engine.start()` brings up the local-miniapp\n * engine with no host construction step. Host-only concerns that remain outside\n * engine, such as Glassly-app crashloop telemetry, are attached by the host after\n * this returns via `router.onCrashloop` / `router.onRestartToast`.\n *\n * Idempotent — `ensureMiniappEngine()` returns the same singletons on every call,\n * so it's safe to call from both `engine.start()` and the host bootstrap.\n */\n\nimport CrustModule from \"@glassly/crust\"\n\nimport devServerBridge from \"./DevServerBridge\"\nimport localMiniappRuntime from \"./LocalMiniappRuntime\"\nimport {miniappLauncher} from \"./MiniappLauncher\"\nimport {JSCrashController} from \"./JSCrashController\"\nimport {JSRouter, type JSCrustBinding} from \"./JSRouter\"\nimport {UIRouter} from \"./UIRouter\"\n\nexport interface MiniappEngine {\n  router: JSRouter\n  uiRouter: UIRouter\n  crashController: JSCrashController\n}\n\nlet engine: MiniappEngine | null = null\n\nfunction wireDevServerRespawnBackground(router: JSRouter, uiRouter: UIRouter): void {\n  devServerBridge.onRespawnBackground(async (packageName) => {\n    try {\n      // Re-resolve the freshly built bundle (dev: HTTP off the dev server;\n      // released: file:// snapshot) via the launcher's shared recipe. Carries\n      // the declared permissions + manifest across the respawn — omitting them\n      // would respawn the JSContext with no permissions, so SUBSCRIBE gates and\n      // per-call dispatch checks would start rejecting after a background\n      // hot-reload.\n      const resolved = await miniappLauncher.resolveBundle(packageName)\n      if (!resolved) {\n        console.warn(`GlasslyJS: respawn-bg could not resolve bundle for ${packageName}`)\n        return\n      }\n      // Force a respawn (kill + spawn) rather than launcher.ensureRunning,\n      // which is idempotent and would no-op an already-registered context.\n      await router.unregister(packageName)\n      const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {\n        permissions: resolved.declaredPermissions,\n        installedManifest: resolved.installedManifest,\n      })\n      if (!ok) {\n        console.warn(`GlasslyJS: respawn-bg failed for ${packageName}`)\n        return\n      }\n      // The respawned JSContext is a fresh MiniappSession with ui.bound false.\n      // The mounted WebView won't re-fire glassly.ready() (it's latched), so\n      // re-announce it so RPC replies (glassly.request) reach the UI again\n      // instead of being dropped while unbound.\n      uiRouter.notifyReopen(packageName)\n    } catch (e) {\n      console.warn(`GlasslyJS: respawn-bg threw for ${packageName}:`, e)\n    }\n  })\n}\n\n/**\n * Construct (once) and return the GlasslyJS engine singletons. Starts the router's\n * message pump on first call. Subsequent calls return the same instances.\n */\nexport function ensureMiniappEngine(): MiniappEngine {\n  if (engine) {\n    wireDevServerRespawnBackground(engine.router, engine.uiRouter)\n    engine.router.start()\n    return engine\n  }\n\n  // The Crust native module's published TS typing doesn't include the new\n  // js* functions until expo prebuild regenerates it; cast to the binding\n  // shapes the routers expect.\n  const crust = CrustModule as unknown as JSCrustBinding\n\n  const crashController = new JSCrashController({\n    maxRetries: 3,\n  })\n  const uiRouter = new UIRouter({\n    jsDispatchToJs: (packageName: string, envelope: Record<string, unknown>) =>\n      (\n        CrustModule as unknown as {\n          jsDispatchToJs: (p: string, e: Record<string, unknown>) => Promise<void>\n        }\n      ).jsDispatchToJs(packageName, envelope),\n  })\n  const router = new JSRouter(localMiniappRuntime, crust)\n  router.crashController = crashController\n  router.uiRouter = uiRouter\n\n  // Hand the router to the engine MiniappLauncher so headless launch/teardown\n  // (apps.ts start/stop, the action broker, the WebView mount path) all spawn\n  // through one place.\n  miniappLauncher.configure({router})\n\n  // Wire up the dev server's \"respawn-bg\" signal so a touch under\n  // src/background/ kills + re-spawns the JSContext with the latest bundle.\n  // The WebView reload path stays separate (devServerBridge.onReload).\n  wireDevServerRespawnBackground(router, uiRouter)\n\n  router.start()\n\n  engine = {router, uiRouter, crashController}\n  return engine\n}\n\n/** Stop the GlasslyJS message pump and tear down router-managed JSContexts. */\nexport async function stopMiniappEngine(): Promise<void> {\n  const current = engine\n  if (!current) return\n  // Null the singleton BEFORE the async teardown below: a concurrent\n  // ensureMiniappEngine() must construct fresh instead of re-starting (and\n  // re-subscribing) the router that is mid-teardown, which would leak a zombie\n  // Crust subscription once this function finishes.\n  engine = null\n\n  devServerBridge.clearRespawnBackgroundHandler()\n  current.router.stop()\n\n  const packages = current.router.registeredPackages()\n  await Promise.all(\n    packages.map(async (packageName) => {\n      try {\n        await current.router.unregister(packageName)\n      } catch (err) {\n        console.warn(`GlasslyJS: failed to unregister ${packageName} during stop:`, err)\n      }\n    }),\n  )\n}\n\n/** Returns the engine singletons if already constructed, else null. */\nexport function getMiniappEngine(): MiniappEngine | null {\n  return engine\n}\n"]}

package/build/services/MiniappLauncher.d.ts

@@ -0,0 +1,127 @@
+/**
+ * MiniappLauncher — headless launch/teardown of a local miniapp's background
+ * JS context.
+ *
+ * This is the one piece of "run a miniapp" that used to live inside the
+ * `LocalMiniappView` React component (resolve the bundle → read the manifest →
+ * `spawnAndRegister`), triggered only when the Compositor mounted that
+ * component on foreground. Pulling it into the runtime means:
+ *
+ *   - `start()` can actually spawn an app even when nothing foregrounds it
+ *     (e.g. a system app launching another miniapp via `session.miniapps`).
+ *   - the action broker can wake a stopped target headlessly — no UI at all.
+ *   - the dev hot-reload respawn path and the WebView mount path share one
+ *     resolve+spawn recipe instead of three copies.
+ *
+ * The launcher is **headless**: no React, no RN components. The engine-owned
+ * MiniappEngine hands it the {@link JSRouter} instance once during
+ * engine construction. OEMs embedding the runtime drive miniapp lifecycle
+ * through the engine facade and stores, not a separate launcher configure API.
+ *
+ * Boundary: the launcher owns the **background** context. WebView *rendering*
+ * (the UI layer) stays with the host — the launcher just hands back the
+ * resolved UI entry so the host can mount its `<WebView>`.
+ */
+import { type InstalledMiniappManifest } from "./LocalMiniappRuntime";
+import type { JSRouter } from "./JSRouter";
+interface LauncherDeps {
+    /** The host-constructed router (needs the native Crust binding). */
+    router: JSRouter;
+}
+/** Hints the host may pass from a view's props to avoid re-deriving them. */
+export interface LaunchHints {
+    devUrl?: string;
+    version?: string;
+    devPort?: string;
+}
+/** Everything the launcher resolved for a package — bg source + UI entry. */
+export interface ResolvedBundle {
+    bgSource: string;
+    uiUri: string | null;
+    uiBaseDir: string | null;
+    declaredPermissions: string[];
+    installedManifest?: InstalledMiniappManifest;
+    /** Set for dev miniapps (HTTP off the dev server); null for released. */
+    devUrl: string | null;
+    devPort: number | null;
+}
+/** What the host needs back to render the UI layer. */
+export interface LaunchResult {
+    uiUri: string | null;
+    uiBaseDir: string | null;
+}
+declare class MiniappLauncher {
+    private deps;
+    /**
+     * In-flight launches keyed by packageName. Both apps.ts start() and the
+     * WebView mount call ensureRunning() before the first spawnAndRegister
+     * resolves — without this, neither sees the package in registeredPackages()
+     * yet and both spawn the same context (a clobber/double-spawn). Concurrent
+     * callers share the same promise.
+     */
+    private readonly inFlight;
+    /** Wire the router in. Called once from MiniappEngine construction. */
+    configure(deps: LauncherDeps): void;
+    private requireRouter;
+    /** True iff the package's background JS context is currently spawned. */
+    isRunning(packageName: string): boolean;
+    /**
+     * Resolve the background JS source + UI entry + declared permissions for a
+     * package. Handles both dev (HTTP off the running dev server) and released
+     * (file:// from the installed snapshot). Reads disk/network/storage; does
+     * NOT spawn. Returns null when the bundle can't be resolved (dev server
+     * unreachable, missing entry, no installed version).
+     */
+    resolveBundle(packageName: string, hints?: LaunchHints): Promise<ResolvedBundle | null>;
+    /**
+     * Ensure a miniapp's background JS context is spawned. Idempotent — if the
+     * context is already alive this is a no-op spawn-wise (it still resolves the
+     * UI entry so a re-mounting host gets its `<WebView>` source back).
+     *
+     * Resolves once the context is SPAWNED. It does NOT block on the context's
+     * CONNECT handshake — the host's WebView mount shouldn't wait on background
+     * JS. Callers that need the context to be connected and ready to receive
+     * messages (the action broker) follow up with
+     * {@link LocalMiniappRuntime.waitForConnect}.
+     */
+    ensureRunning(packageName: string, hints?: LaunchHints): Promise<LaunchResult>;
+    /** Resolve the bundle and spawn the context. Serialized via {@link inFlight}. */
+    private spawn;
+    /**
+     * Re-spawn local miniapps that were running when the app was last killed.
+     *
+     * Miniapps run in the phone's own JS engine, so a host-process kill tears
+     * down their JSContext with nothing to resurrect them. Without this they
+     * would silently stay stopped on the next launch even though the user left
+     * them running.
+     *
+     * Each local miniapp persists its running flag to disk on start/stop
+     * (`saveLocalAppRunningState`, via the applet's `onStart`/`onStop`). We read
+     * those flags back and re-spawn the background context headlessly (no
+     * foreground, no navigation) — the spawn registers the package so the home
+     * tray/switcher project it as running, exactly as a normal start would. The
+     * WebView, if any, re-attaches lazily when the user opens the app.
+     *
+     * Idempotent and best-effort: skips already-spawned contexts, and clears the
+     * persisted flag for any app whose bundle can no longer be resolved
+     * (uninstalled, or dev server gone) so a dead entry doesn't retry every boot.
+     * Not compatibility-gated: a previously-running background app shouldn't be
+     * dropped just because glasses are momentarily disconnected at boot — it
+     * resumes when they reconnect, same as mid-session.
+     */
+    autostartLocalMiniapps(): Promise<void>;
+    /**
+     * Ensure the context is running AND has completed its CONNECT handshake.
+     * Used by the action broker, which must not deliver to a context that hasn't
+     * come up yet. Throws on spawn failure or connect timeout.
+     */
+    ensureConnected(packageName: string, connectTimeoutMs?: number, hints?: LaunchHints): Promise<void>;
+    /** Tear down a miniapp's background JS context. */
+    stop(packageName: string): Promise<void>;
+    private storedDevUrl;
+    /** resolveDevPort — moved verbatim from the old LocalMiniappView helper. */
+    private resolveDevPort;
+}
+export declare const miniappLauncher: MiniappLauncher;
+export {};
+//# sourceMappingURL=MiniappLauncher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappLauncher.d.ts","sourceRoot":"","sources":["../../src/services/MiniappLauncher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAA4B,EAAC,KAAK,wBAAwB,EAAC,MAAM,uBAAuB,CAAA;AACxF,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAA;AAExC,UAAU,YAAY;IACpB,oEAAoE;IACpE,MAAM,EAAE,QAAQ,CAAA;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,cAAM,eAAe;IACnB,OAAO,CAAC,IAAI,CAA4B;IAExC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IAEpE,uEAAuE;IACvE,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAInC,OAAO,CAAC,aAAa;IAOrB,yEAAyE;IACzE,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;;OAMG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA8G7F;;;;;;;;;;OAUG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBpF,iFAAiF;YACnE,KAAK;IAiCnB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB7C;;;;OAIG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,gBAAgB,SAAS,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzG,mDAAmD;IAC7C,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB9C,OAAO,CAAC,YAAY;IAKpB,4EAA4E;IAC5E,OAAO,CAAC,cAAc;CASvB;AAED,eAAO,MAAM,eAAe,iBAAwB,CAAA"}