@glassly/engine 0.1.0-dev.0

package/build/services/uiShim.js

@@ -0,0 +1,369 @@
+/**
+ * window.glassly — WebView-side bridge to the per-miniapp background JSContext.
+ *
+ * Injected into every UI WebView via `injectedJavaScriptBeforeContentLoaded`
+ * (iOS) or `injectedJavaScriptObject` + a bundler-emitted inline `<script>`
+ * (Android, where the `BeforeContentLoaded` prop is documented unreliable
+ * per react-native-webview issues #1099 / #1609).
+ *
+ * The shim:
+ *   - Buffers `glassly.send(channel, payload)` calls until `glassly.ready()`
+ *     fires + the host acks the channel is open. WebView-side BUFFERS (the
+ *     WebView is the short-lived side and shouldn't drop user input).
+ *   - Installs `window.__glassly.recv(envelope)` for the host to push
+ *     background → WebView messages via `webview.injectJavaScript(...)`.
+ *   - Sends `__heartbeat__` every 5s; host considers the WebView gone
+ *     after 15s of silence.
+ *   - Maintains monotonic seq numbers; the host's per-WebView dedup window
+ *     drops replays during reconnect.
+ *
+ * This file exports a `buildUiShim()` function returning the JS
+ * source as a string. The host's UIRouter wraps it inside the
+ * existing WebView setup so a single bundler-time string emission covers
+ * both platforms.
+ *
+ * IMPORTANT: the shim runs in the WebView's bare ECMAScript scope before
+ * the miniapp's bundle. It must not import anything; the source is one
+ * IIFE. The only injected dependencies are
+ * `window.ReactNativeWebView.postMessage` (provided by react-native-webview)
+ * and (on Android) `window.ReactNativeWebView.injectedObjectJson()`
+ * (provided when the host sets `injectedJavaScriptObject`).
+ */
+export function buildUiShim(options) {
+    const packageNameJson = JSON.stringify(options.packageName);
+    // The IIFE assembles a typed `glassly` global plus an internal
+    // `__glassly` for host inbound calls. Quoted strings are JSON-safe so
+    // direct injection inside another JS literal also works.
+    return `
+(function () {
+  if (typeof window === 'undefined') return;
+  if (window.glassly && window.__glassly) return;
+  var packageName = ${packageNameJson};
+  // Resolve window.ReactNativeWebView.postMessage LAZILY, not once at shim-eval.
+  // On Android the shim is injected as a WebViewCompat document-start script
+  // (so it beats the page bundle and the ready handshake can't be raced — see
+  // the react-native-webview patch). But the order in which that document-start
+  // script runs vs. the WebMessageListener that installs
+  // window.ReactNativeWebView is not contractually fixed on Android the way it
+  // is on iOS (postMessageScript is registered before atStartScript there). If
+  // we captured rnPost once and the bridge object wasn't installed yet, every
+  // postMessage — including {type:'ready'} — would be silently dropped and the
+  // splash would hang forever. Resolving per-call means we always pick up the
+  // bridge once it exists, which it reliably does by the time the bundle mounts
+  // and calls glassly.ready().
+  function getRnPost() {
+    try {
+      return window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === 'function'
+        ? window.ReactNativeWebView.postMessage.bind(window.ReactNativeWebView)
+        : null;
+    } catch (e) { return null; }
+  }
+
+  // Outbound seq number — purely a log-correlation aid (the host's
+  // router doesn't dedup anymore since reconnect can't happen: one
+  // WebView, foreground-only, destroyed on close → fresh shim on
+  // next open).
+  var outboundSeq = 1;
+  var ready = false;
+  var channelHandlers = Object.create(null);
+  var openHandlers = [];
+  var closeHandlers = [];
+  // Queued glassly.send calls before glassly.ready() acks. FIFO drained
+  // on ack. Buffered so user input (button taps, etc.) isn't dropped
+  // when the WebView mounts faster than the host expects.
+  var outboundQueue = [];
+  // Inbound payloads that arrived before any glassly.on subscriber was
+  // registered for the channel. The background side fires
+  // session.ui.onOpen handlers as soon as the WebView posts {type:'ready'},
+  // and on a fast bridge the resulting ui.send round-trips back before
+  // React useEffects have had a chance to attach listeners. Without
+  // buffering, the very first snapshot (the one a controller pushes from
+  // its ui.onOpen handler to hydrate the fresh UI) is silently dropped.
+  //
+  // Drain policy: the queue for a channel is flushed into the FIRST
+  // glassly.on(channel, ...) subscriber, then discarded. Subsequent
+  // sends with no listener fall back to the old drop-on-floor behaviour
+  // — we don't want a re-subscribe to replay stale state.
+  //
+  // Cap: 32 entries per channel, oldest dropped on overflow. Bounds the
+  // memory cost when a controller pushes to a channel that no UI page
+  // ever subscribes to.
+  var pendingByChannel = Object.create(null);
+  var PENDING_CAP_PER_CHANNEL = 32;
+
+  function postEnvelope(envelope) {
+    var rnPost = getRnPost();
+    if (!rnPost) return;
+    try { rnPost(JSON.stringify(envelope)); } catch (_) {}
+  }
+
+  function send(channel, payload) {
+    var seq = outboundSeq++;
+    var envelope = { type: 'msg', seq: seq, channel: String(channel), payload: payload };
+    if (!ready) {
+      outboundQueue.push(envelope);
+      return;
+    }
+    postEnvelope(envelope);
+  }
+
+  function flushQueue() {
+    while (outboundQueue.length > 0) {
+      postEnvelope(outboundQueue.shift());
+    }
+  }
+
+  // NOTE: console.* tap lives in miniappGlobals.ts (injected alongside
+  // this shim for every UI WebView, two-layer or single-bundle). That
+  // shim posts {payload:{type:"dev_log", ...}} envelopes which
+  // LocalMiniappRuntime forwards to the dev sidecar tagged source:"ui".
+  // We don't re-wrap here to avoid double-delivery.
+
+  function on(channel, cb) {
+    if (typeof cb !== 'function') return function () {};
+    var list = channelHandlers[channel];
+    var firstSubscriber = !list || list.length === 0;
+    if (!list) { list = []; channelHandlers[channel] = list; }
+    list.push(cb);
+    // Drain any payloads buffered before this channel had a listener.
+    // Only fired on the first subscriber for the channel — a later
+    // re-subscribe (after an unsubscribe) does NOT replay history.
+    if (firstSubscriber) {
+      var pending = pendingByChannel[channel];
+      if (pending) {
+        delete pendingByChannel[channel];
+        for (var i = 0; i < pending.length; i++) {
+          try { cb(pending[i]); } catch (e) {}
+        }
+      }
+    }
+    return function () {
+      var idx = list.indexOf(cb);
+      if (idx >= 0) list.splice(idx, 1);
+    };
+  }
+
+  // ── RPC ─────────────────────────────────────────────────────────────
+  // Outbound RPC: every glassly.request() generates a request id, sends a
+  // 'msg' envelope tagged with requestId, and stashes a one-shot resolver
+  // keyed on the id. The background-side reply is a recv('msg') with the
+  // same channel + requestId; we route it directly to the resolver.
+  //
+  // Cancellation: caller's AbortSignal triggers a 'cancel' envelope to
+  // background and rejects the local promise with a DOM-standard
+  // AbortError. The background side's UI_CANCEL handler aborts the
+  // handler's ctx.signal and drops the reply.
+  var rpcCounter = 0;
+  var rpcInflight = Object.create(null);
+
+  function makeRequestId() {
+    rpcCounter += 1;
+    return 'r' + rpcCounter + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+  }
+
+  function RpcError(message, code, stage, transport) {
+    var e = new Error(message);
+    e.name = 'RpcError';
+    if (code) {
+      try { e.cause = {code: code}; } catch (_) { /* old runtimes */ }
+      e.code = code;
+    }
+    // Diagnostic fields ride as own props so a miniapp can show exactly which
+    // pipeline stage and transport failed, not just a message string.
+    if (stage) e.stage = stage;
+    if (transport) e.transport = transport;
+    return e;
+  }
+
+  function RpcTimeoutError(message) {
+    var e = new Error(message || 'RPC timed out');
+    e.name = 'RpcTimeoutError';
+    return e;
+  }
+
+  function makeAbortError() {
+    var e;
+    try { e = new DOMException('aborted', 'AbortError'); } catch (_) {
+      e = new Error('aborted');
+      e.name = 'AbortError';
+    }
+    return e;
+  }
+
+  function request(channel, payload, options) {
+    var opts = options || {};
+    var signal = opts.signal;
+    var timeoutMs = typeof opts.timeout === 'number' ? opts.timeout : null;
+    var id = makeRequestId();
+
+    return new Promise(function (resolve, reject) {
+      var done = false;
+      var timeoutHandle = null;
+      var abortListener = null;
+
+      function cleanup() {
+        if (done) return;
+        done = true;
+        delete rpcInflight[id];
+        if (timeoutHandle != null) { clearTimeout(timeoutHandle); timeoutHandle = null; }
+        if (signal && abortListener) {
+          try { signal.removeEventListener('abort', abortListener); } catch (_) {}
+        }
+      }
+
+      function settle(envelope) {
+        if (done) return;
+        cleanup();
+        if (envelope && envelope.ok === true) {
+          resolve(envelope.result);
+        } else if (envelope && envelope.ok === false) {
+          reject(RpcError(envelope.error && envelope.error.message || 'RPC failed', envelope.error && envelope.error.code, envelope.error && envelope.error.stage, envelope.error && envelope.error.transport));
+        } else {
+          reject(RpcError('malformed RPC reply'));
+        }
+      }
+
+      rpcInflight[id] = settle;
+
+      if (signal) {
+        if (signal.aborted) {
+          cleanup();
+          reject(makeAbortError());
+          return;
+        }
+        abortListener = function () {
+          if (done) return;
+          cleanup();
+          postEnvelope({type: 'cancel', requestId: id});
+          reject(makeAbortError());
+        };
+        try { signal.addEventListener('abort', abortListener); } catch (_) {}
+      }
+
+      if (timeoutMs != null) {
+        timeoutHandle = setTimeout(function () {
+          if (done) return;
+          cleanup();
+          postEnvelope({type: 'cancel', requestId: id});
+          reject(RpcTimeoutError());
+        }, timeoutMs);
+      }
+
+      var envelope = {type: 'msg', seq: outboundSeq++, channel: String(channel), payload: payload, requestId: id};
+      if (!ready) {
+        outboundQueue.push(envelope);
+        return;
+      }
+      postEnvelope(envelope);
+    });
+  }
+
+  function onOpen(cb) {
+    if (typeof cb !== 'function') return function () {};
+    openHandlers.push(cb);
+    if (ready) {
+      try { cb(); } catch (e) {}
+    }
+    return function () {
+      var idx = openHandlers.indexOf(cb);
+      if (idx >= 0) openHandlers.splice(idx, 1);
+    };
+  }
+
+  function onClose(cb) {
+    if (typeof cb !== 'function') return function () {};
+    closeHandlers.push(cb);
+    return function () {
+      var idx = closeHandlers.indexOf(cb);
+      if (idx >= 0) closeHandlers.splice(idx, 1);
+    };
+  }
+
+  function readyFn() {
+    if (ready) return;
+    ready = true;
+    postEnvelope({ type: 'ready' });
+    flushQueue();
+    for (var i = 0; i < openHandlers.length; i++) {
+      try { openHandlers[i](); } catch (e) {}
+    }
+  }
+
+  function setBackgroundColorFn(color) {
+    // Tells the host what to paint the native WebView layer (the surface
+    // exposed during keyboard push-up / resize animations, which page CSS
+    // cannot reach). Host validates and falls back to its theme background.
+    if (typeof color !== 'string' || !color) return;
+    postEnvelope({ type: 'set_background', color: color });
+  }
+
+  function fireChannel(channel, payload) {
+    var list = channelHandlers[channel];
+    if (!list || list.length === 0) {
+      // No subscriber yet — stash for the first glassly.on(channel, ...).
+      // Bounded FIFO: drop the oldest when capped so a stuck channel
+      // can't grow unbounded.
+      var q = pendingByChannel[channel];
+      if (!q) { q = []; pendingByChannel[channel] = q; }
+      q.push(payload);
+      if (q.length > PENDING_CAP_PER_CHANNEL) q.shift();
+      return;
+    }
+    for (var i = 0; i < list.length; i++) {
+      try { list[i](payload); } catch (e) {}
+    }
+  }
+
+  function recv(envelope) {
+    if (!envelope || typeof envelope !== 'object') return;
+    var type = envelope.type;
+    if (type === 'msg' && typeof envelope.channel === 'string') {
+      // RPC frames carry a requestId; broadcast frames don't. Treat them
+      // as disjoint — never fall through from RPC to broadcast. An orphan
+      // RPC reply (caller already aborted/timed out) is silently dropped.
+      if (typeof envelope.requestId === 'string') {
+        var settle = rpcInflight[envelope.requestId];
+        if (settle) settle(envelope.payload);
+        return;
+      }
+      fireChannel(envelope.channel, envelope.payload);
+      return;
+    }
+    if (type === 'open') {
+      for (var j = 0; j < openHandlers.length; j++) {
+        try { openHandlers[j](); } catch (e) {}
+      }
+      return;
+    }
+    if (type === 'close') {
+      for (var k = 0; k < closeHandlers.length; k++) {
+        try { closeHandlers[k](); } catch (e) {}
+      }
+      return;
+    }
+    if (type === 'cancel' && typeof envelope.requestId === 'string') {
+      // Background-side cancel (reserved; currently unused). If we had a
+      // future bidirectional RPC this would abort an in-flight UI handler.
+      return;
+    }
+    if (type === 'ack') {
+      return;
+    }
+  }
+
+  window.glassly = {
+    send: send,
+    on: on,
+    request: request,
+    onOpen: onOpen,
+    onClose: onClose,
+    ready: readyFn,
+    setBackgroundColor: setBackgroundColorFn,
+    /** @internal — packageName for diagnostic logs only. */
+    _packageName: packageName,
+  };
+  window.__glassly = { recv: recv };
+})();
+`.trim();
+}
+//# sourceMappingURL=uiShim.js.map

package/build/services/uiShim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiShim.js","sourceRoot":"","sources":["../../src/services/uiShim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3D,+DAA+D;IAC/D,sEAAsE;IACtE,yDAAyD;IACzD,OAAO;;;;sBAIa,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsUpC,CAAC,IAAI,EAAE,CAAA;AACR,CAAC","sourcesContent":["/**\n * window.glassly — WebView-side bridge to the per-miniapp background JSContext.\n *\n * Injected into every UI WebView via `injectedJavaScriptBeforeContentLoaded`\n * (iOS) or `injectedJavaScriptObject` + a bundler-emitted inline `<script>`\n * (Android, where the `BeforeContentLoaded` prop is documented unreliable\n * per react-native-webview issues #1099 / #1609).\n *\n * The shim:\n *   - Buffers `glassly.send(channel, payload)` calls until `glassly.ready()`\n *     fires + the host acks the channel is open. WebView-side BUFFERS (the\n *     WebView is the short-lived side and shouldn't drop user input).\n *   - Installs `window.__glassly.recv(envelope)` for the host to push\n *     background → WebView messages via `webview.injectJavaScript(...)`.\n *   - Sends `__heartbeat__` every 5s; host considers the WebView gone\n *     after 15s of silence.\n *   - Maintains monotonic seq numbers; the host's per-WebView dedup window\n *     drops replays during reconnect.\n *\n * This file exports a `buildUiShim()` function returning the JS\n * source as a string. The host's UIRouter wraps it inside the\n * existing WebView setup so a single bundler-time string emission covers\n * both platforms.\n *\n * IMPORTANT: the shim runs in the WebView's bare ECMAScript scope before\n * the miniapp's bundle. It must not import anything; the source is one\n * IIFE. The only injected dependencies are\n * `window.ReactNativeWebView.postMessage` (provided by react-native-webview)\n * and (on Android) `window.ReactNativeWebView.injectedObjectJson()`\n * (provided when the host sets `injectedJavaScriptObject`).\n */\n\nexport interface UiShimOptions {\n  packageName: string\n  /** @deprecated No longer used — heartbeat removed since WebViews are foreground-only. */\n  heartbeatIntervalMs?: number\n}\n\nexport function buildUiShim(options: UiShimOptions): string {\n  const packageNameJson = JSON.stringify(options.packageName)\n  // The IIFE assembles a typed `glassly` global plus an internal\n  // `__glassly` for host inbound calls. Quoted strings are JSON-safe so\n  // direct injection inside another JS literal also works.\n  return `\n(function () {\n  if (typeof window === 'undefined') return;\n  if (window.glassly && window.__glassly) return;\n  var packageName = ${packageNameJson};\n  // Resolve window.ReactNativeWebView.postMessage LAZILY, not once at shim-eval.\n  // On Android the shim is injected as a WebViewCompat document-start script\n  // (so it beats the page bundle and the ready handshake can't be raced — see\n  // the react-native-webview patch). But the order in which that document-start\n  // script runs vs. the WebMessageListener that installs\n  // window.ReactNativeWebView is not contractually fixed on Android the way it\n  // is on iOS (postMessageScript is registered before atStartScript there). If\n  // we captured rnPost once and the bridge object wasn't installed yet, every\n  // postMessage — including {type:'ready'} — would be silently dropped and the\n  // splash would hang forever. Resolving per-call means we always pick up the\n  // bridge once it exists, which it reliably does by the time the bundle mounts\n  // and calls glassly.ready().\n  function getRnPost() {\n    try {\n      return window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === 'function'\n        ? window.ReactNativeWebView.postMessage.bind(window.ReactNativeWebView)\n        : null;\n    } catch (e) { return null; }\n  }\n\n  // Outbound seq number — purely a log-correlation aid (the host's\n  // router doesn't dedup anymore since reconnect can't happen: one\n  // WebView, foreground-only, destroyed on close → fresh shim on\n  // next open).\n  var outboundSeq = 1;\n  var ready = false;\n  var channelHandlers = Object.create(null);\n  var openHandlers = [];\n  var closeHandlers = [];\n  // Queued glassly.send calls before glassly.ready() acks. FIFO drained\n  // on ack. Buffered so user input (button taps, etc.) isn't dropped\n  // when the WebView mounts faster than the host expects.\n  var outboundQueue = [];\n  // Inbound payloads that arrived before any glassly.on subscriber was\n  // registered for the channel. The background side fires\n  // session.ui.onOpen handlers as soon as the WebView posts {type:'ready'},\n  // and on a fast bridge the resulting ui.send round-trips back before\n  // React useEffects have had a chance to attach listeners. Without\n  // buffering, the very first snapshot (the one a controller pushes from\n  // its ui.onOpen handler to hydrate the fresh UI) is silently dropped.\n  //\n  // Drain policy: the queue for a channel is flushed into the FIRST\n  // glassly.on(channel, ...) subscriber, then discarded. Subsequent\n  // sends with no listener fall back to the old drop-on-floor behaviour\n  // — we don't want a re-subscribe to replay stale state.\n  //\n  // Cap: 32 entries per channel, oldest dropped on overflow. Bounds the\n  // memory cost when a controller pushes to a channel that no UI page\n  // ever subscribes to.\n  var pendingByChannel = Object.create(null);\n  var PENDING_CAP_PER_CHANNEL = 32;\n\n  function postEnvelope(envelope) {\n    var rnPost = getRnPost();\n    if (!rnPost) return;\n    try { rnPost(JSON.stringify(envelope)); } catch (_) {}\n  }\n\n  function send(channel, payload) {\n    var seq = outboundSeq++;\n    var envelope = { type: 'msg', seq: seq, channel: String(channel), payload: payload };\n    if (!ready) {\n      outboundQueue.push(envelope);\n      return;\n    }\n    postEnvelope(envelope);\n  }\n\n  function flushQueue() {\n    while (outboundQueue.length > 0) {\n      postEnvelope(outboundQueue.shift());\n    }\n  }\n\n  // NOTE: console.* tap lives in miniappGlobals.ts (injected alongside\n  // this shim for every UI WebView, two-layer or single-bundle). That\n  // shim posts {payload:{type:\"dev_log\", ...}} envelopes which\n  // LocalMiniappRuntime forwards to the dev sidecar tagged source:\"ui\".\n  // We don't re-wrap here to avoid double-delivery.\n\n  function on(channel, cb) {\n    if (typeof cb !== 'function') return function () {};\n    var list = channelHandlers[channel];\n    var firstSubscriber = !list || list.length === 0;\n    if (!list) { list = []; channelHandlers[channel] = list; }\n    list.push(cb);\n    // Drain any payloads buffered before this channel had a listener.\n    // Only fired on the first subscriber for the channel — a later\n    // re-subscribe (after an unsubscribe) does NOT replay history.\n    if (firstSubscriber) {\n      var pending = pendingByChannel[channel];\n      if (pending) {\n        delete pendingByChannel[channel];\n        for (var i = 0; i < pending.length; i++) {\n          try { cb(pending[i]); } catch (e) {}\n        }\n      }\n    }\n    return function () {\n      var idx = list.indexOf(cb);\n      if (idx >= 0) list.splice(idx, 1);\n    };\n  }\n\n  // ── RPC ─────────────────────────────────────────────────────────────\n  // Outbound RPC: every glassly.request() generates a request id, sends a\n  // 'msg' envelope tagged with requestId, and stashes a one-shot resolver\n  // keyed on the id. The background-side reply is a recv('msg') with the\n  // same channel + requestId; we route it directly to the resolver.\n  //\n  // Cancellation: caller's AbortSignal triggers a 'cancel' envelope to\n  // background and rejects the local promise with a DOM-standard\n  // AbortError. The background side's UI_CANCEL handler aborts the\n  // handler's ctx.signal and drops the reply.\n  var rpcCounter = 0;\n  var rpcInflight = Object.create(null);\n\n  function makeRequestId() {\n    rpcCounter += 1;\n    return 'r' + rpcCounter + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);\n  }\n\n  function RpcError(message, code, stage, transport) {\n    var e = new Error(message);\n    e.name = 'RpcError';\n    if (code) {\n      try { e.cause = {code: code}; } catch (_) { /* old runtimes */ }\n      e.code = code;\n    }\n    // Diagnostic fields ride as own props so a miniapp can show exactly which\n    // pipeline stage and transport failed, not just a message string.\n    if (stage) e.stage = stage;\n    if (transport) e.transport = transport;\n    return e;\n  }\n\n  function RpcTimeoutError(message) {\n    var e = new Error(message || 'RPC timed out');\n    e.name = 'RpcTimeoutError';\n    return e;\n  }\n\n  function makeAbortError() {\n    var e;\n    try { e = new DOMException('aborted', 'AbortError'); } catch (_) {\n      e = new Error('aborted');\n      e.name = 'AbortError';\n    }\n    return e;\n  }\n\n  function request(channel, payload, options) {\n    var opts = options || {};\n    var signal = opts.signal;\n    var timeoutMs = typeof opts.timeout === 'number' ? opts.timeout : null;\n    var id = makeRequestId();\n\n    return new Promise(function (resolve, reject) {\n      var done = false;\n      var timeoutHandle = null;\n      var abortListener = null;\n\n      function cleanup() {\n        if (done) return;\n        done = true;\n        delete rpcInflight[id];\n        if (timeoutHandle != null) { clearTimeout(timeoutHandle); timeoutHandle = null; }\n        if (signal && abortListener) {\n          try { signal.removeEventListener('abort', abortListener); } catch (_) {}\n        }\n      }\n\n      function settle(envelope) {\n        if (done) return;\n        cleanup();\n        if (envelope && envelope.ok === true) {\n          resolve(envelope.result);\n        } else if (envelope && envelope.ok === false) {\n          reject(RpcError(envelope.error && envelope.error.message || 'RPC failed', envelope.error && envelope.error.code, envelope.error && envelope.error.stage, envelope.error && envelope.error.transport));\n        } else {\n          reject(RpcError('malformed RPC reply'));\n        }\n      }\n\n      rpcInflight[id] = settle;\n\n      if (signal) {\n        if (signal.aborted) {\n          cleanup();\n          reject(makeAbortError());\n          return;\n        }\n        abortListener = function () {\n          if (done) return;\n          cleanup();\n          postEnvelope({type: 'cancel', requestId: id});\n          reject(makeAbortError());\n        };\n        try { signal.addEventListener('abort', abortListener); } catch (_) {}\n      }\n\n      if (timeoutMs != null) {\n        timeoutHandle = setTimeout(function () {\n          if (done) return;\n          cleanup();\n          postEnvelope({type: 'cancel', requestId: id});\n          reject(RpcTimeoutError());\n        }, timeoutMs);\n      }\n\n      var envelope = {type: 'msg', seq: outboundSeq++, channel: String(channel), payload: payload, requestId: id};\n      if (!ready) {\n        outboundQueue.push(envelope);\n        return;\n      }\n      postEnvelope(envelope);\n    });\n  }\n\n  function onOpen(cb) {\n    if (typeof cb !== 'function') return function () {};\n    openHandlers.push(cb);\n    if (ready) {\n      try { cb(); } catch (e) {}\n    }\n    return function () {\n      var idx = openHandlers.indexOf(cb);\n      if (idx >= 0) openHandlers.splice(idx, 1);\n    };\n  }\n\n  function onClose(cb) {\n    if (typeof cb !== 'function') return function () {};\n    closeHandlers.push(cb);\n    return function () {\n      var idx = closeHandlers.indexOf(cb);\n      if (idx >= 0) closeHandlers.splice(idx, 1);\n    };\n  }\n\n  function readyFn() {\n    if (ready) return;\n    ready = true;\n    postEnvelope({ type: 'ready' });\n    flushQueue();\n    for (var i = 0; i < openHandlers.length; i++) {\n      try { openHandlers[i](); } catch (e) {}\n    }\n  }\n\n  function setBackgroundColorFn(color) {\n    // Tells the host what to paint the native WebView layer (the surface\n    // exposed during keyboard push-up / resize animations, which page CSS\n    // cannot reach). Host validates and falls back to its theme background.\n    if (typeof color !== 'string' || !color) return;\n    postEnvelope({ type: 'set_background', color: color });\n  }\n\n  function fireChannel(channel, payload) {\n    var list = channelHandlers[channel];\n    if (!list || list.length === 0) {\n      // No subscriber yet — stash for the first glassly.on(channel, ...).\n      // Bounded FIFO: drop the oldest when capped so a stuck channel\n      // can't grow unbounded.\n      var q = pendingByChannel[channel];\n      if (!q) { q = []; pendingByChannel[channel] = q; }\n      q.push(payload);\n      if (q.length > PENDING_CAP_PER_CHANNEL) q.shift();\n      return;\n    }\n    for (var i = 0; i < list.length; i++) {\n      try { list[i](payload); } catch (e) {}\n    }\n  }\n\n  function recv(envelope) {\n    if (!envelope || typeof envelope !== 'object') return;\n    var type = envelope.type;\n    if (type === 'msg' && typeof envelope.channel === 'string') {\n      // RPC frames carry a requestId; broadcast frames don't. Treat them\n      // as disjoint — never fall through from RPC to broadcast. An orphan\n      // RPC reply (caller already aborted/timed out) is silently dropped.\n      if (typeof envelope.requestId === 'string') {\n        var settle = rpcInflight[envelope.requestId];\n        if (settle) settle(envelope.payload);\n        return;\n      }\n      fireChannel(envelope.channel, envelope.payload);\n      return;\n    }\n    if (type === 'open') {\n      for (var j = 0; j < openHandlers.length; j++) {\n        try { openHandlers[j](); } catch (e) {}\n      }\n      return;\n    }\n    if (type === 'close') {\n      for (var k = 0; k < closeHandlers.length; k++) {\n        try { closeHandlers[k](); } catch (e) {}\n      }\n      return;\n    }\n    if (type === 'cancel' && typeof envelope.requestId === 'string') {\n      // Background-side cancel (reserved; currently unused). If we had a\n      // future bidirectional RPC this would abort an in-flight UI handler.\n      return;\n    }\n    if (type === 'ack') {\n      return;\n    }\n  }\n\n  window.glassly = {\n    send: send,\n    on: on,\n    request: request,\n    onOpen: onOpen,\n    onClose: onClose,\n    ready: readyFn,\n    setBackgroundColor: setBackgroundColorFn,\n    /** @internal — packageName for diagnostic logs only. */\n    _packageName: packageName,\n  };\n  window.__glassly = { recv: recv };\n})();\n`.trim()\n}\n"]}

package/build/stores/apps.d.ts

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

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

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