@mentra/engine 0.1.0-beta.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"MentraJSLogPipeline.d.ts","sourceRoot":"","sources":["../../src/services/MentraJSLogPipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmBrD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AASD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;gBAEpD,IAAI,GAAE,eAAoB;IAMtC;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG;QAAC,OAAO,EAAE,IAAI,CAAA;KAAC,GAAG;QAAC,OAAO,EAAE,KAAK,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAC;IA4BxF,oCAAoC;IACpC,aAAa,IAAI,IAAI;CAGtB;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAE/C,kBAAkB,SAAM;IAIpC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAU7C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;IAIvC,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;CAGjC"}

package/build/services/MentraJSLogPipeline.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+const SECRET_KEY_PATTERN = /\b(token|password|secret|auth|bearer|key|api[_-]?key)\b/i;
+/**
+ * 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 function redactSecrets(value) {
+    if (typeof value === "string") {
+        return SECRET_KEY_PATTERN.test(value) ? "[REDACTED]" : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => redactSecrets(v));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (SECRET_KEY_PATTERN.test(k)) {
+                out[k] = "[REDACTED]";
+            }
+            else {
+                out[k] = redactSecrets(v);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+export class MentraJSLogThrottle {
+    tokensPerSecond;
+    bucketCapacity;
+    now;
+    buckets = new Map();
+    constructor(opts = {}) {
+        this.tokensPerSecond = opts.tokensPerSecond ?? 100 / 60;
+        this.bucketCapacity = opts.bucketCapacity ?? 500;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * 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) {
+        const at = this.now();
+        let bucket = this.buckets.get(packageName);
+        if (!bucket) {
+            bucket = {
+                tokens: this.bucketCapacity,
+                lastRefillAtMs: at,
+                pendingDrops: 0,
+            };
+            this.buckets.set(packageName, bucket);
+        }
+        else {
+            const elapsedSec = (at - bucket.lastRefillAtMs) / 1000;
+            bucket.tokens = Math.min(this.bucketCapacity, bucket.tokens + elapsedSec * this.tokensPerSecond);
+            bucket.lastRefillAtMs = at;
+        }
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            if (bucket.pendingDrops > 0) {
+                const dropped = bucket.pendingDrops;
+                bucket.pendingDrops = 0;
+                return { allowed: false, throttledLine: `[throttled ${dropped}]` };
+            }
+            return { allowed: true };
+        }
+        bucket.pendingDrops += 1;
+        return { allowed: false };
+    }
+    /** Test/dev — reset all buckets. */
+    resetForTests() {
+        this.buckets.clear();
+    }
+}
+/**
+ * In-memory ring buffer holding the last N lines per package. Useful as a
+ * "last words" context attached to crash reports.
+ */
+export class MentraJSLogRingBuffer {
+    capacity;
+    buffers = new Map();
+    constructor(capacityPerPackage = 200) {
+        this.capacity = capacityPerPackage;
+    }
+    push(packageName, line) {
+        let buf = this.buffers.get(packageName);
+        if (!buf) {
+            buf = [];
+            this.buffers.set(packageName, buf);
+        }
+        buf.push(line);
+        if (buf.length > this.capacity)
+            buf.shift();
+    }
+    snapshot(packageName) {
+        return [...(this.buffers.get(packageName) ?? [])];
+    }
+    clear(packageName) {
+        this.buffers.delete(packageName);
+    }
+}
+//# sourceMappingURL=MentraJSLogPipeline.js.map

package/build/services/MentraJSLogPipeline.js.map

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

package/build/services/MentraJSRouter.d.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview MentraJSRouter — RN-side host that bridges the per-miniapp
+ * JS contexts (iOS-JSC and Android-QuickJS via Zipline) into the existing
+ * {@link LocalMiniappRuntime} handler set.
+ *
+ * Rather than re-implement the 33 dispatch arms inline, the router
+ * consumes Crust's `mentrajs_message` Expo event and forwards its
+ * `__bridge.send(raw)` payloads to {@link LocalMiniappRuntime.handleRawMessage}.
+ * The SDK envelope shape (`{type: "DISPLAY", ...}` etc.) is unchanged from
+ * the WebView path, so every existing handler runs verbatim. What changes
+ * is the *transport*:
+ *
+ *   - **Inbound** (background JS → host): `__dispatch("__bridge", "send",
+ *     [rawJsonString])` → `mentrajs_message` event → router →
+ *     `LocalMiniappRuntime.handleRawMessage(packageName, raw)`.
+ *   - **Outbound** (host → background JS): every package registered with
+ *     the router gets a `sendMessage(raw)` fn that calls
+ *     `Crust.mentraJsDispatchToJs(packageName, {kind: "bridge", raw})`.
+ *     The polyfill's `__deliver` recognises `kind === "bridge"` and calls
+ *     `__mentraDeliverBridgeRaw(raw)`, which routes into the SDK's
+ *     {@link DispatchTransport.onMessage} handler.
+ *
+ * Host-side handler bodies (display fan-out, mic state, transcription,
+ * navigation, etc.) live untouched in `LocalMiniappRuntime.ts`.
+ *
+ * Cloud-message routing (`phone_stream_status`, `phone_managed_stream_status`)
+ * goes straight through `LocalMiniappRuntime.handleCloudMessage` — nothing
+ * for the router to do; the responses arrive inside an envelope whose
+ * `sendMessage` was already registered via the same path here.
+ *
+ * The router also bridges native error / log / unhandled-rejection
+ * events (`iface: "__log"`, `iface: "__error"`) into the standard
+ * `console.*` + Sentry breadcrumb pipeline so miniapp telemetry is
+ * visible without bringing up a separate sink.
+ */
+import type { EventSubscription } from "expo-modules-core";
+import type localMiniappRuntime from "./LocalMiniappRuntime";
+import type { InstalledMiniappManifest } from "./LocalMiniappRuntime";
+import type { MentraJSCrashController } from "./MentraJSCrashController";
+import { MentraJSLogRingBuffer, MentraJSLogThrottle } from "./MentraJSLogPipeline";
+import type { MentraUIRouter } from "./MentraUIRouter";
+/** The runtime's runtime instance type — the singleton exported from
+ * LocalMiniappRuntime.ts (the file's `export default` is the instance,
+ * not the class).
+ */
+type LocalMiniappRuntime = typeof localMiniappRuntime;
+/**
+ * Minimal subset of the Crust native module the router uses. Keeping the
+ * binding loose lets us mock the module in unit tests without bringing
+ * the whole Expo module surface along.
+ */
+export interface MentraJSCrustBinding {
+    mentraJsDispatchToJs(packageName: string, envelope: Record<string, unknown>): Promise<void> | void;
+    mentraJsSetManifest(packageName: string, permissions: string[]): Promise<void> | void;
+    mentraJsLoadPolyfillBundle?: () => string;
+    mentraJsSpawn?: (packageName: string, polyfill: string, miniappJs: string) => Promise<boolean> | boolean;
+    mentraJsKill?: (packageName: string) => Promise<void> | void;
+    mentraJsAlivePackages?: () => string[];
+    addListener: (event: string, handler: (payload: Record<string, unknown>) => void) => EventSubscription;
+}
+export interface OutboundMessagePayload {
+    packageName: string;
+    iface: string;
+    method: string;
+    argsJson?: string;
+    args?: unknown[];
+    reqId?: string;
+    [extra: string]: unknown;
+}
+export type RouterLogger = {
+    log: (message: string, payload?: unknown) => void;
+    warn: (message: string, payload?: unknown) => void;
+    error: (message: string, payload?: unknown) => void;
+};
+export declare class MentraJSRouter {
+    private readonly runtime;
+    private readonly crust;
+    private readonly logger;
+    private subscription;
+    private readonly registered;
+    /** Cached spawn arguments so the crash controller can respawn after a backoff. */
+    private readonly spawnCache;
+    /** Active respawn timers (so unregister() can cancel a pending respawn). */
+    private readonly respawnTimers;
+    /**
+     * Optional crash controller. When wired, every `__error` frame from a
+     * JSContext drives the state machine; an Outcome with
+     * scheduleRespawnAfterMs queues a setTimeout that re-spawns the
+     * miniapp's last-known JS source after the backoff delay.
+     */
+    crashController: MentraJSCrashController | null;
+    /** Hook called when a package transitions to CRASHLOOP_DISABLED. */
+    onCrashloop: ((packageName: string, reason: string) => void) | null;
+    /** Hook called on the 2nd-within-window crash (toast UX). */
+    onRestartToast: ((packageName: string, reason: string) => void) | null;
+    /**
+     * Logging plumbing. Every `__log` frame passes through `redactSecrets`
+     * (token/password/etc. scrubbed), then the throttle (100/min sustained
+     * per pkg, 500 burst), then lands in the ring buffer + the host
+     * logger. The ring buffer holds the last 200 lines/pkg so a crash
+     * report can attach "last words" context.
+     *
+     * Replace with new instances in tests; production code uses the
+     * defaults.
+     */
+    logThrottle: MentraJSLogThrottle;
+    logRing: MentraJSLogRingBuffer;
+    /**
+     * Optional UI router — when wired, `__bridge.send` envelopes whose
+     * inner payload type is `UI_SEND` get routed to the bound WebView
+     * instead of through LocalMiniappRuntime. Two-layer miniapps set
+     * this; legacy single-bundle WebView miniapps don't and the bridge
+     * frames pass through unchanged.
+     */
+    uiRouter: MentraUIRouter | null;
+    constructor(runtime: LocalMiniappRuntime, crust: MentraJSCrustBinding, logger?: RouterLogger);
+    /**
+     * Subscribe to Crust's `mentrajs_message` event. Idempotent — calling
+     * start() twice attaches a single listener.
+     */
+    start(): void;
+    /**
+     * Detach the Crust subscription. The router can be restarted later
+     * with start(); registrations survive (the runtime's app map is the
+     * source of truth).
+     */
+    stop(): void;
+    /**
+     * Register a JSContext with the runtime so its handlers can fire
+     * `sendMessage(raw)` against the right context. The router builds a
+     * `sendMessage` that calls `Crust.mentraJsDispatchToJs(packageName,
+     * {kind: "bridge", raw})`; the polyfill's `__deliver` then hands the
+     * envelope to `DispatchTransport.onMessage` inside the miniapp.
+     *
+     * Mirrors `MiniappHost.registerRuntime` on the WebView side. Callers
+     * (e.g. {@link spawnAndRegister} below, or the host's miniapp launch
+     * pipeline) should call this once per spawn.
+     */
+    registerApp(packageName: string, installedManifest?: InstalledMiniappManifest): void;
+    /**
+     * Convenience: spawn a JSContext via Crust, register the app, and
+     * set its declared permissions. Returns true on successful spawn.
+     *
+     * The host's miniapp launch path
+     * (`mobile/src/services/miniapps/launchLocalMiniapp.ts`) calls this
+     * once per JSContext mount.
+     */
+    spawnAndRegister(packageName: string, miniappJs: string, options?: {
+        permissions?: string[];
+        installedManifest?: InstalledMiniappManifest;
+    }): Promise<boolean>;
+    /**
+     * Crash-controller integration. Called from the `__error` frame
+     * handler. The controller returns an outcome that tells us whether
+     * to respawn (with delay) or leave the context dead.
+     */
+    private handleCrash;
+    private summarizeReason;
+    /**
+     * Tear down a JSContext and unregister from the runtime. Synchronous
+     * teardown — the spec drops the 50ms WILL_DISCONNECT grace window
+     * because there's no transport handshake to flush in the JSC world.
+     */
+    unregister(packageName: string): Promise<void>;
+    /** List packages the router has registered. */
+    registeredPackages(): string[];
+    /**
+     * Validate that a reused background JSContext is still responsive when its
+     * WebView comes foreground. The runtime owns the ping/timeout mechanics; the
+     * router gates this to registered packages and keeps LocalMiniappView from
+     * reaching into runtime internals.
+     */
+    probeForegroundLiveness(packageName: string, reason?: string): void;
+    private handleOutbound;
+    /**
+     * The wire format for `__bridge.send` is `argsJson = JSON.stringify([raw])`
+     * — a single-element array containing the original raw envelope. The
+     * dispatcher passes the parsed array through as either:
+     *   - `msg.args` when the dispatcher unpacked (Android path that turns
+     *     `argsJson` into a List on the way to RN), or
+     *   - `msg.argsJson` (iOS path that ships the string verbatim).
+     * Cover both shapes here.
+     */
+    /**
+     * Parse a raw bridge envelope just enough to peek at the inner
+     * payload's `type` field. Used by the UI_SEND interception path.
+     * Returns null if the envelope isn't a valid bridge frame.
+     */
+    private peekBridgePayloadType;
+    private coerceArgsToBridgeRaw;
+    private tryParseArgs;
+    /**
+     * Push a `kind="bridge"` envelope into the named JSContext's
+     * `globalThis.__deliver`. Used both by the per-app `sendMessage`
+     * registered via {@link registerApp} and by ad-hoc callers (e.g.
+     * cloud-relayed stream-status responses route through
+     * `LocalMiniappRuntime.handleCloudMessage`, which then calls the
+     * `app.sendMessage(serialized)` registered above).
+     */
+    private dispatchBridgeRaw;
+}
+export {};
+//# sourceMappingURL=MentraJSRouter.d.ts.map

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

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