@crossbind/core-app-host 0.0.0-bootstrap.0 → 2.0.0-beta.65

package/js/page.js

@@ -0,0 +1,79 @@
+// The page's crossbind.js in an app: initNative() resolves to the module the app's host runs, with the contract of a
+// worker-backed web build.
+import { connect } from './lean-client.js';
+
+// The app's host gives this to the top frame of its page alone.
+const token = globalThis.__crossbind_token;
+
+// A request the host refuses fails its call with what the host answered.
+async function checked(response) {
+    if (!response.ok) throw new Error((await response.text()) || `crossbind: the app's host answered ${response.status}`);
+    return response;
+}
+
+// macOS, iOS and Linux: WebKit's message handler, and crossbind:// requests for the bytes.
+const WEBKIT = {
+    send: (text) => window.webkit.messageHandlers.crossbind.postMessage(text),
+    frame: (query, body) => fetch(`crossbind://app/b/frame?${query}`, { method: 'POST', body }).then(checked).then((response) => response.text()),
+    result: (query) => fetch(`crossbind://app/b/result?${query}`).then(checked).then((response) => response.arrayBuffer()),
+    attachBytes: 16384,
+    token,
+};
+
+// Android: the port the app hands the top frame as the page starts. A message goes as "<id>|m|<text>", a large result's
+// request as "<id>|r|<query>", and a frame as one ArrayBuffer, "<header length><id>|<query>" and the bytes; an answer
+// is "<id>|<text>", "<id>|!<what the host refused>", or an ArrayBuffer whose first four bytes hold the id.
+function androidTransport(port) {
+    const pending = new Map();
+    let nextId = 1;
+    port.onmessage = ({ data }) => {
+        const isBytes = data instanceof ArrayBuffer;
+        const bar = isBytes ? 0 : data.indexOf('|');
+        const id = isBytes ? new DataView(data).getUint32(0, true) : Number(data.slice(0, bar));
+        const { resolve, reject } = pending.get(id);
+        pending.delete(id);
+        if (isBytes) resolve(data.slice(4));
+        else if (data[bar + 1] === '!') reject(new Error(data.slice(bar + 2)));
+        else resolve(data.slice(bar + 1));
+    };
+    const call = (post) => new Promise((resolve, reject) => {
+        const id = nextId;
+        nextId += 1;
+        pending.set(id, { resolve, reject });
+        post(id);
+    });
+    const encoder = new TextEncoder();
+    return {
+        send: (text) => call((id) => port.postMessage(`${id}|m|${text}`)),
+        frame: (query, body) => call((id) => {
+            const header = encoder.encode(`${id}|${query}`);
+            const bytes = new Uint8Array(4 + header.length + body.length);
+            new DataView(bytes.buffer).setUint32(0, header.length, true);
+            bytes.set(header, 4);
+            bytes.set(body, 4 + header.length);
+            port.postMessage(bytes.buffer, [bytes.buffer]);
+        }),
+        result: (query) => call((id) => port.postMessage(`${id}|r|${query}`)),
+        attachBytes: 16384,
+        token,
+    };
+}
+
+const transport = globalThis.__crossbind_port ? globalThis.__crossbind_port.then(androidTransport) : WEBKIT;
+
+let booted = null;
+
+function initNative(config = {}) {
+    if (!booted) {
+        booted = token
+            ? Promise.resolve(transport).then((chosen) => connect(chosen, config.env))
+            : Promise.reject(new Error("crossbind: only the top frame of an app's own page reaches the app's module"));
+    }
+    return booted;
+}
+
+initNative.terminate = () => {
+    booted = null;
+};
+
+globalThis.Crossbind = { initNative };

package/js/polyfills.js

@@ -0,0 +1,32 @@
+// What a Hermes runtime embedded without React Native lacks; the host functions come from host_core.cpp.
+/* global __host_log, __host_timer */
+const consoleObject = {};
+for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
+    consoleObject[level] = (...args) => __host_log(level, args.map((arg) => (arg instanceof Error ? `${arg.message}\n${arg.stack}` : String(arg))).join(' '));
+}
+globalThis.console = consoleObject;
+
+let nextTimer = 1;
+const timers = new Map();
+globalThis.setTimeout = (fn, ms = 0, ...args) => {
+    const id = nextTimer;
+    nextTimer += 1;
+    timers.set(id, () => fn(...args));
+    // As a browser reads the delay: a number from 0 up to 32 bits, 0 for anything else.
+    __host_timer(id, Math.min(Math.max(Number(ms) || 0, 0), 2 ** 31 - 1));
+    return id;
+};
+globalThis.clearTimeout = (id) => {
+    timers.delete(id);
+};
+globalThis.__host_timer_fire = (id) => {
+    const fn = timers.get(id);
+    timers.delete(id);
+    if (fn) fn();
+};
+
+if (typeof globalThis.queueMicrotask !== 'function') {
+    globalThis.queueMicrotask = (fn) => {
+        Promise.resolve().then(fn);
+    };
+}

package/package.json

@@ -1,7 +1,31 @@
 {
-    "name": "@crossbind/core-app-host",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/core-app-host@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/core-app-host",
+  "version": "2.0.0-beta.65",
+  "description": "App host for the crossbind embind runtime: a desktop app whose page runs in the system webview and whose bindings run natively in Hermes.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/core/app-host#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "files": [
+    "android",
+    "cpp",
+    "js",
+    "third_party"
+  ],
+  "dependencies": {
+    "@crossbind/core-embind-jsi": "^2.0.0-beta.65"
+  },
+  "keywords": [
+    "embind",
+    "hermes",
+    "webview",
+    "desktop",
+    "app",
+    "bind",
+    "c++",
+    "rust",
+    "macos"
+  ]
+}

package/third_party/jsi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/third_party/jsi/README.md

@@ -0,0 +1,18 @@
+# JSI (vendored)
+
+`jsi.cpp`, the out-of-line part of JSI (`facebook::jsi`), which Hermes' prebuilt framework does not export. The JSI
+headers come with Hermes, so this file is taken from the same Hermes release. React Native's Android package of Hermes
+carries no JSI headers, so the three `jsi.cpp` includes and the one `hermes.h` adds are in `include/jsi/`, from the
+same tag.
+
+- Upstream: https://github.com/facebook/hermes, `API/jsi/jsi/`
+- Tag: `hermes-v250829098.0.17`, commit `3477757eb2475555cf8d8df24bfb1deb0613880d`
+- Files, from `https://raw.githubusercontent.com/facebook/hermes/3477757eb2475555cf8d8df24bfb1deb0613880d/API/jsi/jsi/`:
+  - `jsi.cpp`, sha256 `cb6274a22abc93ecc970066539815e716d3e47716e8f93a9971cf4eb5918ffc1`
+  - `include/jsi/jsi.h`, sha256 `db2f1ee9291340f3d05b11abdcdc3d12ac84c239e58599d4ef2ac06dbaa14d92`
+  - `include/jsi/jsi-inl.h`, sha256 `a6cbf72ee25991a25cd43049e96fb275c900e24da67d5c2b9581faaca11f06a4`
+  - `include/jsi/instrumentation.h`, sha256 `1395779ad53ec372518b977d077e65a876215bc31a94cf049ed55d0a3d2426f4`
+  - `include/jsi/hermes-interfaces.h`, sha256 `2cd4b50cdcdb9cf61bd5940b257d7878ceb018438cc2ea8b34acdb552d56d56d`
+- License: MIT, see `LICENSE`
+
+No local patches. A Hermes update takes these files from the new release's tag.

package/third_party/jsi/include/jsi/hermes-interfaces.h

@@ -0,0 +1,189 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+struct SHUnit;
+struct SHRuntime;
+using SHUnitCreator = SHUnit* (*)();
+namespace hermes::vm {
+class GCExecTrace;
+}
+
+namespace facebook::hermes {
+
+namespace sampling_profiler {
+class Profile;
+}
+
+namespace debugger {
+class Debugger;
+}
+
+/// Interface for Hermes-specific runtime methods.The actual implementations of
+/// the pure virtual methods are provided by Hermes API.
+class JSI_EXPORT IHermes : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0xe85cfa22,
+      0xdfae,
+      0x11ef,
+      0xa6f7,
+      0x325096b39f47};
+
+  struct DebugFlags {
+    // Looking for the .lazy flag? It's no longer necessary.
+    // Source is evaluated lazily by default. See
+    // RuntimeConfig::CompilationMode.
+  };
+
+  /// Evaluate the given code in an unoptimized form, used for debugging.
+  /// This will be no-op if the implementation does not have debugger enabled.
+  virtual void debugJavaScript(
+      const std::string& src,
+      const std::string& sourceURL,
+      const DebugFlags& debugFlags) = 0;
+
+  /// Return a ICast pointer to an object that be cast into the interface
+  /// IHermesRootAPI. This root API object has static lifetime.
+  virtual ICast* getHermesRootAPI() = 0;
+
+  /// Dump sampled stack trace for a given runtime to a data structure that can
+  /// be used by third parties.
+  virtual sampling_profiler::Profile dumpSampledTraceToProfile() = 0;
+
+  /// Serialize the sampled stack to the format expected by DevTools'
+  /// Profiler.stop return type.
+  virtual void sampledTraceToStreamInDevToolsFormat(std::ostream& stream) = 0;
+
+  /// Resets the timezone offset cache used by Hermes for performance
+  /// optimization. Hermes maintains a cached timezone offset to accelerate date
+  /// and time calculations. However, this cache does not automatically detect
+  /// changes to the system timezone. When the system timezone changes, the
+  /// integration layer (e.g., React Native) must call this method to invalidate
+  /// the cache and ensure correct time calculations.
+  ///
+  /// \note Call this method immediately after detecting any timezone change in
+  /// the integrator.
+  virtual void resetTimezoneCache() = 0;
+
+  /// Load a new segment into the Runtime.
+  /// The \param context must be a valid RequireContext retrieved from JS
+  /// using `require.context`.
+  virtual void loadSegment(
+      std::unique_ptr<const jsi::Buffer> buffer,
+      const jsi::Value& context) = 0;
+
+  /// Gets a guaranteed unique id for an Object (or, respectively, String
+  /// or PropNameId), which is assigned at allocation time and is
+  /// static throughout that object's (or string's, or PropNameID's)
+  /// lifetime.
+  virtual uint64_t getUniqueID(const jsi::Object& o) const = 0;
+  virtual uint64_t getUniqueID(const jsi::BigInt& s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::String& s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::PropNameID& pni) const = 0;
+  virtual uint64_t getUniqueID(const jsi::Symbol& sym) const = 0;
+
+  /// Same as the other \c getUniqueID, except it can return 0 for some values.
+  /// 0 means there is no ID associated with the value.
+  virtual uint64_t getUniqueID(const jsi::Value& val) const = 0;
+
+  /// From an ID retrieved from \p getUniqueID, go back to the object.
+  /// NOTE: This is much slower in general than the reverse operation, and takes
+  /// up more memory. Don't use this unless it's absolutely necessary.
+  /// \return a jsi::Object if a matching object is found, else returns null.
+  virtual jsi::Value getObjectForID(uint64_t id) = 0;
+
+  /// Get a structure representing the execution history (currently just of
+  /// GC, but will be generalized as necessary), to aid in debugging
+  /// non-deterministic execution.
+  virtual const ::hermes::vm::GCExecTrace& getGCExecTrace() const = 0;
+
+  /// Get IO tracking (aka HBC page access) info as a JSON string.
+  /// See hermes::vm::Runtime::getIOTrackingInfoJSON() for conditions
+  /// needed for there to be useful output.
+  virtual std::string getIOTrackingInfoJSON() = 0;
+
+  /// \return a reference to the Debugger for this Runtime.
+  virtual debugger::Debugger& getDebugger() = 0;
+
+  /// Register this runtime and thread for sampling profiler. Before using the
+  /// runtime on another thread, invoke this function again from the new thread
+  /// to make the sampling profiler target the new thread (and forget the old
+  /// thread).
+  virtual void registerForProfiling() = 0;
+  /// Unregister this runtime for sampling profiler.
+  virtual void unregisterForProfiling() = 0;
+
+  /// Define methods to interrupt JS execution and set time limits.
+  /// All JS compiled to bytecode via prepareJS, or evaluateJS, will support
+  /// interruption and time limit monitoring if the runtime is configured with
+  /// AsyncBreakCheckInEval. If JS prepared in other ways is executed, care must
+  /// be taken to ensure that it is compiled in a mode that supports it (i.e.,
+  /// the emitted code contains async break checks).
+
+  /// Asynchronously terminates the current execution. This can be called on
+  /// any thread.
+  virtual void asyncTriggerTimeout() = 0;
+
+  /// Register this runtime for execution time limit monitoring, with a time
+  /// limit of \p timeoutInMs milliseconds.
+  /// See compilation notes above.
+  virtual void watchTimeLimit(uint32_t timeoutInMs) = 0;
+  /// Unregister this runtime for execution time limit monitoring.
+  virtual void unwatchTimeLimit() = 0;
+
+  /// Same as \c evaluate JavaScript but with a source map, which will be
+  /// applied to exception traces and debug information.
+  ///
+  /// This is an experimental Hermes-specific API. In the future it may be
+  /// renamed, moved or combined with another API, but the provided
+  /// functionality will continue to be available in some form.
+  virtual jsi::Value evaluateJavaScriptWithSourceMap(
+      const std::shared_ptr<const jsi::Buffer>& buffer,
+      const std::shared_ptr<const jsi::Buffer>& sourceMapBuf,
+      const std::string& sourceURL) = 0;
+
+  /// Associate the SHUnit returned by \p shUnitCreator with this runtime and
+  /// run its initialization code. The unit will be freed when the runtime is
+  /// destroyed.
+  virtual jsi::Value evaluateSHUnit(SHUnitCreator shUnitCreator) = 0;
+
+  /// Retrieve the underlying SHRuntime.
+  virtual SHRuntime* getSHRuntime() noexcept = 0;
+
+  /// Returns the underlying low level Hermes VM runtime instance.
+  /// This function is considered unsafe and unstable.
+  /// Direct use of a vm::Runtime should be avoided as the lower level APIs are
+  /// unsafe and they can change without notice.
+  virtual void* getVMRuntimeUnsafe() const = 0;
+
+ protected:
+  ~IHermes() = default;
+};
+
+/// Interface for provide Hermes backend specific methods.
+class IHermesSHUnit : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0x52a2d522,
+      0xcbc6,
+      0x4236,
+      0x8d5d,
+      0x2636c320ed65,
+  };
+
+  /// Get the unit creating function pointer which can be passed to
+  /// evaluateSHUnit() for evaluation.
+  virtual SHUnitCreator getSHUnitCreator() const = 0;
+
+ protected:
+  ~IHermesSHUnit() = default;
+};
+} // namespace facebook::hermes

package/third_party/jsi/include/jsi/instrumentation.h

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <chrono>
+#include <iosfwd>
+#include <string>
+#include <tuple>
+#include <unordered_map>
+
+#include <jsi/jsi.h>
+
+namespace facebook {
+namespace jsi {
+
+/// Methods for starting and collecting instrumentation, an \c Instrumentation
+/// instance is associated with a particular \c Runtime instance, which it
+/// controls the instrumentation of.
+/// None of these functions should return newly created jsi values, nor should
+/// it modify the values of any jsi values in the heap (although GCs are fine).
+class JSI_EXPORT Instrumentation {
+ public:
+  /// Additional options controlling what to include when capturing a heap
+  /// snapshot.
+  struct HeapSnapshotOptions {
+    bool captureNumericValue{false};
+  };
+
+  virtual ~Instrumentation() = default;
+
+  /// Returns GC statistics as a JSON-encoded string, with an object containing
+  /// "type" and "version" fields outermost. "type" is a string, unique to a
+  /// particular implementation of \c jsi::Instrumentation, and "version" is a
+  /// number to indicate any revision to that implementation and its output
+  /// format.
+  ///
+  /// \pre This call can only be made on the instrumentation instance of a
+  ///   runtime initialised to collect GC statistics.
+  ///
+  /// \post All cumulative measurements mentioned in the output are accumulated
+  ///   across the entire lifetime of the Runtime.
+  ///
+  /// \return the GC statistics collected so far, as a JSON-encoded string.
+  virtual std::string getRecordedGCStats() = 0;
+
+  /// Request statistics about the current state of the runtime's heap. This
+  /// function can be called at any time, and should produce information that is
+  /// correct at the instant it is called (i.e, not stale).
+  ///
+  /// \return a map from a string key to a number associated with that
+  /// statistic.
+  virtual std::unordered_map<std::string, int64_t> getHeapInfo(
+      bool includeExpensive) = 0;
+
+  /// Perform a full garbage collection.
+  /// \param cause The cause of this collection, as it should be reported in
+  ///   logs.
+  virtual void collectGarbage(std::string cause) = 0;
+
+  /// A HeapStatsUpdate is a tuple of the fragment index, the number of objects
+  /// in that fragment, and the number of bytes used by those objects.
+  /// A "fragment" is a view of all objects allocated within a time slice.
+  using HeapStatsUpdate = std::tuple<uint64_t, uint64_t, uint64_t>;
+
+  /// Start capturing JS stack-traces for all JS heap allocated objects. These
+  /// can be accessed via \c ::createSnapshotToFile().
+  /// \param fragmentCallback If present, invoke this callback every so often
+  ///   with the most recently seen object ID, and a list of fragments that have
+  ///   been updated. This callback will be invoked on the same thread that the
+  ///   runtime is using.
+  virtual void startTrackingHeapObjectStackTraces(
+      std::function<void(
+          uint64_t lastSeenObjectID,
+          std::chrono::microseconds timestamp,
+          std::vector<HeapStatsUpdate> stats)> fragmentCallback) = 0;
+
+  /// Stop capture JS stack-traces for JS heap allocated objects.
+  virtual void stopTrackingHeapObjectStackTraces() = 0;
+
+  /// Start a heap sampling profiler that will sample heap allocations, and the
+  /// stack trace they were allocated at. Reports a summary of which functions
+  /// allocated the most.
+  /// \param samplingInterval The number of bytes allocated to wait between
+  ///   samples. This will be used as the expected value of a poisson
+  ///   distribution.
+  virtual void startHeapSampling(size_t samplingInterval) = 0;
+
+  /// Turns off the heap sampling profiler previously enabled via
+  /// \c startHeapSampling. Writes the output of the sampling heap profiler to
+  /// \p os. The output is a JSON formatted string.
+  virtual void stopHeapSampling(std::ostream& os) = 0;
+
+  /// Captures the heap to a file
+  ///
+  /// \param path to save the heap capture.
+  /// \param options additional options for what to capture.
+  virtual void createSnapshotToFile(
+      const std::string& path,
+      const HeapSnapshotOptions& options = {false}) = 0;
+
+  /// Captures the heap to an output stream
+  ///
+  /// \param os output stream to write to.
+  /// \param options additional options for what to capture.
+  virtual void createSnapshotToStream(
+      std::ostream& os,
+      const HeapSnapshotOptions& options = {false}) = 0;
+
+  /// If the runtime has been created to trace to a temp file, flush
+  /// any unwritten parts of the trace of bridge traffic to the file,
+  /// and return the name of  the file.  Otherwise, return the empty string.
+  /// Tracing is disabled after this call.
+  virtual std::string flushAndDisableBridgeTrafficTrace() = 0;
+
+  /// Write basic block profile trace to the given file name.
+  virtual void writeBasicBlockProfileTraceToFile(
+      const std::string& fileName) const = 0;
+
+  /// Write the opcode stats to the given stream.
+  virtual void dumpOpcodeStats(std::ostream& os) const = 0;
+
+  /// Dump external profiler symbols to the given file name.
+  virtual void dumpProfilerSymbolsToFile(const std::string& fileName) const = 0;
+};
+
+} // namespace jsi
+} // namespace facebook