@tanstack-ai-browser/afm 0.0.0-stage → 0.2.1

package/dist/messages.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TanStack AI's messages as a native session's conversation (`NativeMessage`):
+ * text, the assistant's tool calls, and the tools' results. The framework
+ * reads text only here, so other parts are left out.
+ */
+import type { ModelMessage } from "@tanstack/ai";
+import type { NativeMessage } from "./native.js";
+/** A message's text: its string, or its text parts joined. */
+export declare function contentText(content: ModelMessage["content"]): string;
+/** The messages as a session's conversation, each tool result named by its call's tool. */
+export declare function toNativeMessages(messages: ReadonlyArray<ModelMessage>): Array<NativeMessage>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG,MAAM,CAOpE;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC,CAgB5F"}

package/dist/messages.js

@@ -0,0 +1,29 @@
+/** A message's text: its string, or its text parts joined. */
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => (part.type === "text" ? part.content : ""))
+        .filter(Boolean)
+        .join("\n");
+}
+/** The messages as a session's conversation, each tool result named by its call's tool. */
+export function toNativeMessages(messages) {
+    const toolNames = new Map();
+    return messages.map((m) => {
+        if (m.role === "tool") {
+            const id = m.toolCallId ?? "";
+            return { role: "tool", toolCallId: id, name: m.name ?? toolNames.get(id) ?? "", text: contentText(m.content) };
+        }
+        if (m.role === "assistant") {
+            const toolCalls = (m.toolCalls ?? []).map((call) => {
+                toolNames.set(call.id, call.function.name);
+                return { id: call.id, name: call.function.name, arguments: call.function.arguments || "{}" };
+            });
+            return { role: "assistant", text: contentText(m.content), ...(toolCalls.length > 0 && { toolCalls }) };
+        }
+        return { role: "user", text: contentText(m.content) };
+    });
+}

package/dist/model-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The model the framework runs: Apple's system language model
+ * (`SystemLanguageModel.default`), the on-device model of Apple Intelligence.
+ * It calls tools natively, and holds structured answers to a schema. It doesn't
+ * reason, so `chat()` offers no `reasoning` option for it.
+ */
+/** What a Foundation Models model supports. */
+export type AfmModelMeta = {
+    /** The model's name here. */
+    name: string;
+    supports: {
+        input: ReadonlyArray<"text">;
+        output: ReadonlyArray<"text">;
+        capabilities: ReadonlyArray<"tools" | "structured-output">;
+    };
+};
+/** The models the framework runs: Apple's system language model. */
+export declare const AFM_CHAT_MODELS: readonly ["system"];
+/** A model the framework runs. */
+export type AfmChatModel = (typeof AFM_CHAT_MODELS)[number];
+/** Each model's metadata, by name. */
+export declare const AFM_MODEL_META: Readonly<Record<AfmChatModel, AfmModelMeta>>;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.d.ts","sourceRoot":"","sources":["../src/model-meta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACR,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;QAC5B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;QAC7B,YAAY,EAAE,aAAa,CAAC,OAAO,GAAG,mBAAmB,CAAC,CAAA;KAC3D,CAAA;CACF,CAAA;AAWD,oEAAoE;AACpE,eAAO,MAAM,eAAe,qBAA+B,CAAA;AAE3D,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,sCAAsC;AACtC,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CAEvE,CAAA"}

package/dist/model-meta.js

@@ -0,0 +1,20 @@
+/**
+ * The model the framework runs: Apple's system language model
+ * (`SystemLanguageModel.default`), the on-device model of Apple Intelligence.
+ * It calls tools natively, and holds structured answers to a schema. It doesn't
+ * reason, so `chat()` offers no `reasoning` option for it.
+ */
+const SYSTEM_MODEL = {
+    name: "system",
+    supports: {
+        input: ["text"],
+        output: ["text"],
+        capabilities: ["tools", "structured-output"]
+    }
+};
+/** The models the framework runs: Apple's system language model. */
+export const AFM_CHAT_MODELS = [SYSTEM_MODEL.name];
+/** Each model's metadata, by name. */
+export const AFM_MODEL_META = {
+    [SYSTEM_MODEL.name]: SYSTEM_MODEL
+};

package/dist/native.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The native side of the adapter: Apple's Foundation Models framework, reached
+ * through the Capacitor plugin on iOS (ios/Sources), or the Electron main
+ * process (`serveAfm()`, whose preload puts it at `window.afm`). Any host can
+ * stand in for them by implementing `AfmNative`.
+ */
+import type { PluginListenerHandle } from "@capacitor/core";
+/** Why the model can't run: Apple's reasons, or an OS before 26. */
+export type UnavailableReason = "deviceNotEligible" | "appleIntelligenceNotEnabled" | "modelNotReady" | "unsupportedOS" | "unavailable";
+export type NativeAvailability = {
+    available: boolean;
+    reason?: UnavailableReason;
+    /** Tokens a session holds (iOS/macOS 26.4 and later). */
+    contextSize?: number;
+};
+/**
+ * A schema as the framework takes it: JSON Schema read into an ordered form
+ * (`schema.ts`), properties in the order given, and named definitions for
+ * `reference`s.
+ */
+export type NativeSchema = {
+    kind: "object";
+    name: string;
+    description?: string;
+    properties: Array<NativeProperty>;
+} | {
+    kind: "array";
+    items: NativeSchema;
+    minimumElements?: number;
+    maximumElements?: number;
+} | {
+    kind: "string";
+    choices?: Array<string>;
+    constant?: string;
+} | {
+    kind: "integer" | "number";
+    minimum?: number;
+    maximum?: number;
+} | {
+    kind: "boolean";
+} | {
+    kind: "null";
+} | {
+    kind: "anyOf";
+    name: string;
+    description?: string;
+    choices: Array<NativeSchema>;
+} | {
+    kind: "reference";
+    name: string;
+};
+export type NativeProperty = {
+    name: string;
+    description?: string;
+    optional: boolean;
+    schema: NativeSchema;
+};
+/** A root schema and the definitions its references name. */
+export type NativeGenerationSchema = {
+    root: NativeSchema;
+    definitions: Array<NativeSchema>;
+};
+export type NativeTool = {
+    name: string;
+    description: string;
+    parameters: NativeGenerationSchema;
+};
+/** A message of the conversation a session starts from. */
+export type NativeMessage = {
+    role: "user";
+    text: string;
+} | {
+    role: "assistant";
+    text: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+} | {
+    role: "tool";
+    toolCallId: string;
+    name: string;
+    text: string;
+};
+/**
+ * A response's tokens, over every pass of the model (a tool call's too).
+ * `cachedTokens` is there only where the framework counts it right: for a
+ * session without tools.
+ */
+export type NativeUsage = {
+    inputTokens: number;
+    cachedTokens?: number;
+    outputTokens: number;
+};
+/** What a session sends while it responds, for the `turn` of the `respond` call. */
+export type NativeEvent = {
+    sessionId: string;
+    turn: number;
+} & ({
+    type: "delta";
+    text: string;
+} | {
+    type: "toolCalls";
+    calls: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+} | {
+    type: "done";
+    text: string;
+    usage?: NativeUsage;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+});
+export interface AfmNative {
+    availability(): Promise<NativeAvailability>;
+    createSession(options: {
+        sessionId: string;
+        instructions?: string;
+        tools: Array<NativeTool>;
+        messages: Array<NativeMessage>;
+    }): Promise<void>;
+    prewarm(options: {
+        sessionId: string;
+    }): Promise<void>;
+    /** Prompts a session; the response comes as events. A `schema` holds the answer to it (JSON in `done`). */
+    respond(options: {
+        sessionId: string;
+        turn: number;
+        prompt: string;
+        options?: {
+            temperature?: number;
+            maximumResponseTokens?: number;
+            /** Whether the model may call the session's tools, must, or mustn't (iOS/macOS 27). Left out, the framework decides. */
+            toolCallingMode?: "allowed" | "required" | "disallowed";
+        };
+        schema?: NativeGenerationSchema;
+    }): Promise<void>;
+    /** A tool's result: the session's waiting call returns it, and the response goes on. */
+    submitToolResult(options: {
+        sessionId: string;
+        callId: string;
+        output: string;
+    }): Promise<void>;
+    /** Stops a session's response. */
+    cancel(options: {
+        sessionId: string;
+    }): Promise<void>;
+    deleteSession(options: {
+        sessionId: string;
+    }): Promise<void>;
+    addListener(eventName: "event", listener: (event: NativeEvent) => void): Promise<PluginListenerHandle>;
+}
+/**
+ * The Capacitor plugin (iOS), loading Capacitor on its first call. Elsewhere
+ * its calls reject: Capacitor has no web version of it.
+ */
+export declare const Afm: AfmNative;
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

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

package/dist/native.js

@@ -0,0 +1,21 @@
+let loading;
+/**
+ * The plugin, loading Capacitor on first use: pages elsewhere never load it.
+ * It's wrapped: a Capacitor plugin answers every property, `then` too, so a
+ * promise of the plugin itself would wait on it forever.
+ */
+const capacitor = () => (loading ??= import("@capacitor/core").then(({ registerPlugin }) => ({ plugin: registerPlugin("Afm") })));
+/**
+ * The Capacitor plugin (iOS), loading Capacitor on its first call. Elsewhere
+ * its calls reject: Capacitor has no web version of it.
+ */
+export const Afm = {
+    availability: async () => (await capacitor()).plugin.availability(),
+    createSession: async (options) => (await capacitor()).plugin.createSession(options),
+    prewarm: async (options) => (await capacitor()).plugin.prewarm(options),
+    respond: async (options) => (await capacitor()).plugin.respond(options),
+    submitToolResult: async (options) => (await capacitor()).plugin.submitToolResult(options),
+    cancel: async (options) => (await capacitor()).plugin.cancel(options),
+    deleteSession: async (options) => (await capacitor()).plugin.deleteSession(options),
+    addListener: async (name, listener) => (await capacitor()).plugin.addListener(name, listener)
+};

package/dist/schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSON Schema (what `chat()` gives adapters for tools and structured output)
+ * read into the framework's own schema (`NativeSchema`), which the model's
+ * output is held to: a tool's arguments always fit its parameters.
+ *
+ * Properties keep their order, which the model writes them in. Each object is
+ * named by its path, so two objects never share a name. A property that may be
+ * null is optional. `$ref`s to `$defs` (or `definitions`) become references to
+ * named definitions; one to a plain value is written in place.
+ */
+import type { NativeGenerationSchema } from "./native.js";
+/**
+ * The framework's schema for a JSON Schema, named `name` (a tool's name, or
+ * the structured answer's).
+ */
+export declare function toNativeSchema(schema: unknown, name: string): NativeGenerationSchema;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,aAAa,CAAA;AA2BvE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,sBAAsB,CA+GpF"}

package/dist/schema.js

@@ -0,0 +1,133 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Drops undefined fields: the native bridge takes JSON. */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+const isNull = (schema) => isObject(schema) && (schema.type === "null" || (Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === "null"));
+/** Whether a schema allows null: `type: [..., "null"]`, or a null choice in `anyOf`. */
+function nullable(schema) {
+    if (!isObject(schema))
+        return false;
+    if (Array.isArray(schema.type) && schema.type.includes("null"))
+        return true;
+    const variants = schema.anyOf ?? schema.oneOf;
+    return Array.isArray(variants) && variants.some(isNull);
+}
+const number = (value) => (typeof value === "number" && Number.isFinite(value) ? value : undefined);
+/** A schema's name for the framework: letters, digits and underscores. */
+const typeName = (name) => name.replace(/[^A-Za-z0-9_]/g, "_") || "Value";
+/**
+ * The framework's schema for a JSON Schema, named `name` (a tool's name, or
+ * the structured answer's).
+ */
+export function toNativeSchema(schema, name) {
+    const json = isObject(schema) ? schema : {};
+    const defs = { ...(isObject(json.definitions) ? json.definitions : {}), ...(isObject(json.$defs) ? json.$defs : {}) };
+    const definitions = new Map();
+    const convert = (value, path) => {
+        if (!isObject(value))
+            return { kind: "string" };
+        if (typeof value.$ref === "string") {
+            const target = value.$ref.split("/").at(-1) ?? "";
+            const def = defs[target];
+            if (!isObject(def))
+                return { kind: "string" };
+            const converted = definitions.get(target) ?? convertDefinition(def, target);
+            // Only named schemas (objects, choices) can be referred to.
+            return converted.kind === "object" || converted.kind === "anyOf" ? { kind: "reference", name: typeName(target) } : converted;
+        }
+        if ("const" in value && typeof value.const === "string")
+            return { kind: "string", constant: value.const };
+        if (Array.isArray(value.enum)) {
+            const members = value.enum.filter((v) => v !== null);
+            if (members.every((v) => typeof v === "string")) {
+                return members.length > 0 ? { kind: "string", choices: members } : { kind: "string" };
+            }
+            // true and false both: any boolean. One alone, the framework can't hold it to.
+            if (members.every((v) => typeof v === "boolean")) {
+                if (new Set(members).size === 2)
+                    return { kind: "boolean" };
+                throw new Error(`${path}: an enum of only ${String(members[0])} isn't supported (Apple's framework can't hold a boolean to one value)`);
+            }
+            // Integers (and strings among them): a choice of exact values, each integer
+            // a range of itself, which the framework holds the model to. A decimal
+            // can't be: a range of one decimal fails in Apple's generator.
+            if (members.some((v) => typeof v === "number" && !Number.isInteger(v))) {
+                throw new Error(`${path}: an enum of decimal numbers isn't supported (Apple's framework can't hold a decimal to exact values)`);
+            }
+            if (members.every((v) => typeof v === "string" || Number.isInteger(v))) {
+                const choices = members.map((v) => typeof v === "string" ? { kind: "string", constant: v } : { kind: "integer", minimum: v, maximum: v });
+                if (choices.length === 1)
+                    return choices[0];
+                return defined({ kind: "anyOf", name: typeName(path), description: typeof value.description === "string" ? value.description : undefined, choices });
+            }
+            throw new Error(`${path}: an enum mixing ${[...new Set(members.map((v) => typeof v))].join(" and ")} values isn't supported by Apple's framework`);
+        }
+        const variants = value.anyOf ?? value.oneOf;
+        if (Array.isArray(variants)) {
+            const choices = variants.filter((v) => !isNull(v));
+            if (choices.length === 1)
+                return convert({ ...choices[0], description: value.description ?? choices[0].description }, path);
+            if (choices.length > 1) {
+                return defined({
+                    kind: "anyOf",
+                    name: typeName(path),
+                    description: typeof value.description === "string" ? value.description : undefined,
+                    choices: choices.map((choice, i) => convert(choice, `${path}_${i + 1}`))
+                });
+            }
+        }
+        const types = Array.isArray(value.type) ? value.type.filter((t) => t !== "null") : [value.type];
+        const type = typeof types[0] === "string" ? types[0] : isObject(value.properties) ? "object" : value.items ? "array" : "string";
+        switch (type) {
+            case "object": {
+                const required = Array.isArray(value.required) ? value.required : [];
+                const properties = Object.entries(isObject(value.properties) ? value.properties : {}).map(([key, property]) => defined({
+                    name: key,
+                    description: isObject(property) && typeof property.description === "string" ? property.description : undefined,
+                    optional: !required.includes(key) || nullable(property),
+                    schema: convert(property, `${path}_${key}`)
+                }));
+                return defined({
+                    kind: "object",
+                    name: typeName(path),
+                    description: typeof value.description === "string" ? value.description : undefined,
+                    properties
+                });
+            }
+            case "array":
+                return defined({
+                    kind: "array",
+                    items: convert(Array.isArray(value.items) ? value.items[0] : value.items, `${path}_item`),
+                    minimumElements: number(value.minItems),
+                    maximumElements: number(value.maxItems)
+                });
+            case "integer":
+            case "number":
+                return defined({
+                    kind: type,
+                    minimum: number(value.minimum) ?? number(value.exclusiveMinimum),
+                    maximum: number(value.maximum) ?? number(value.exclusiveMaximum)
+                });
+            case "boolean":
+                return { kind: "boolean" };
+            case "null":
+                return { kind: "null" };
+            default:
+                return { kind: "string" };
+        }
+    };
+    const convertDefinition = (def, target) => {
+        // Set first, so a definition that refers to itself finds its name.
+        definitions.set(target, { kind: "object", name: typeName(target), properties: [] });
+        const converted = convert(def, target);
+        const named = converted.kind === "object" || converted.kind === "anyOf" ? { ...converted, name: typeName(target) } : converted;
+        definitions.set(target, named);
+        return named;
+    };
+    const root = convert(json, name);
+    return {
+        root,
+        definitions: [...definitions.values()].filter((d) => d.kind === "object" || d.kind === "anyOf")
+    };
+}

package/electron/AfmNode.swift

@@ -0,0 +1,81 @@
+// AfmBridge for the Node-API addon (afm.c) that serveAfm() loads: plain C functions,
+// JSON strings in and out, built into one afm.node with AfmCore (build.mjs). macOS only.
+import Foundation
+
+/// The C function the addon gives for events: called with each event in JSON, from
+/// any thread.
+public typealias AfmListener = @convention(c) (UnsafePointer<CChar>) -> Void
+
+private final class State: @unchecked Sendable {
+    let lock = NSLock()
+    var listener: AfmListener?
+    var bridge: AnyObject?
+}
+
+private let state = State()
+
+private func json(_ object: Any) -> String {
+    guard JSONSerialization.isValidJSONObject(object),
+          let data = try? JSONSerialization.data(withJSONObject: object) else { return "{}" }
+    return String(decoding: data, as: UTF8.self)
+}
+
+private func emit(_ event: [String: Any]) {
+    let listener = state.lock.withLock { state.listener }
+    guard let listener else { return }
+    json(event).withCString { listener($0) }
+}
+
+@available(macOS 26.0, *)
+private func bridge() -> AfmBridge {
+    state.lock.withLock {
+        if let bridge = state.bridge as? AfmBridge { return bridge }
+        let bridge = AfmBridge { emit($0) }
+        state.bridge = bridge
+        return bridge
+    }
+}
+
+/// Sets the function events go to.
+@_cdecl("afm_set_listener")
+public func afm_set_listener(_ listener: AfmListener?) {
+    state.lock.withLock { state.listener = listener }
+}
+
+/// Calls one of AfmBridge's methods with its options in JSON. Returns
+/// `{ "result": … }` or `{ "error": … }` in JSON, which the caller frees with `afm_free`.
+@_cdecl("afm_call")
+public func afm_call(_ method: UnsafePointer<CChar>, _ options: UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar> {
+    let name = String(cString: method)
+    let object = (try? JSONSerialization.jsonObject(with: Data(String(cString: options).utf8))) as? [String: Any] ?? [:]
+    var reply: [String: Any]
+    if #available(macOS 26.0, *) {
+        do {
+            switch name {
+            case "availability": reply = ["result": AfmBridge.availability()]
+            case "createSession": try bridge().createSession(object); reply = ["result": NSNull()]
+            case "prewarm": try bridge().prewarm(object); reply = ["result": NSNull()]
+            case "respond": try bridge().respond(object); reply = ["result": NSNull()]
+            case "submitToolResult": try bridge().submitToolResult(object); reply = ["result": NSNull()]
+            case "cancel": try bridge().cancel(object); reply = ["result": NSNull()]
+            case "deleteSession":
+                bridge().deleteSession(object["sessionId"] as? String ?? "")
+                reply = ["result": NSNull()]
+            default: reply = ["error": "Unknown method \(name)"]
+            }
+        } catch {
+            reply = ["error": String(describing: error)]
+        }
+    } else {
+        reply = name == "availability"
+            ? ["result": ["available": false, "reason": "unsupportedOS"]]
+            : ["error": "Apple's on-device model needs macOS 26 or later"]
+    }
+    return strdup(json(reply))!
+}
+
+/// Frees a string `afm_call` returned.
+@_cdecl("afm_free")
+public func afm_free(_ pointer: UnsafeMutablePointer<CChar>?) {
+    free(pointer)
+}

package/electron/afm.c

@@ -0,0 +1,94 @@
+// The Node-API addon around AfmBridge (AfmNode.swift): `call(method, optionsJson)`
+// returns `{ result }` or `{ error }` in JSON, and `setListener(fn)` gets each
+// event in JSON. Events come from Swift's threads, so they reach JavaScript through
+// a thread-safe function, on Node's own thread.
+#define NAPI_VERSION 8
+#include <node_api.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef void (*afm_listener)(const char *json);
+extern void afm_set_listener(afm_listener listener);
+extern char *afm_call(const char *method, const char *options);
+extern void afm_free(char *pointer);
+
+static napi_threadsafe_function events = NULL;
+
+static void call_js(napi_env env, napi_value callback, void *context, void *data) {
+    (void)context;
+    char *json = data;
+    if (env != NULL && callback != NULL) {
+        napi_value argument, undefined;
+        napi_create_string_utf8(env, json, NAPI_AUTO_LENGTH, &argument);
+        napi_get_undefined(env, &undefined);
+        napi_call_function(env, undefined, callback, 1, &argument, NULL);
+    }
+    free(json);
+}
+
+static void on_event(const char *json) {
+    napi_threadsafe_function target = events;
+    if (target == NULL) return;
+    char *copy = strdup(json);
+    if (napi_call_threadsafe_function(target, copy, napi_tsfn_nonblocking) != napi_ok) free(copy);
+}
+
+static char *string_argument(napi_env env, napi_value value) {
+    size_t length = 0;
+    if (napi_get_value_string_utf8(env, value, NULL, 0, &length) != napi_ok) return NULL;
+    char *string = malloc(length + 1);
+    napi_get_value_string_utf8(env, value, string, length + 1, &length);
+    return string;
+}
+
+static napi_value set_listener(napi_env env, napi_callback_info info) {
+    size_t count = 1;
+    napi_value arguments[1];
+    napi_get_cb_info(env, info, &count, arguments, NULL, NULL);
+    if (events != NULL) {
+        afm_set_listener(NULL);
+        napi_release_threadsafe_function(events, napi_tsfn_abort);
+        events = NULL;
+    }
+    napi_valuetype type = napi_undefined;
+    if (count > 0) napi_typeof(env, arguments[0], &type);
+    if (type == napi_function) {
+        napi_value name;
+        napi_create_string_utf8(env, "afm events", NAPI_AUTO_LENGTH, &name);
+        napi_create_threadsafe_function(env, arguments[0], NULL, name, 0, 1, NULL, NULL, NULL, call_js, &events);
+        // Events don't keep the process running.
+        napi_unref_threadsafe_function(env, events);
+        afm_set_listener(on_event);
+    }
+    return NULL;
+}
+
+static napi_value call(napi_env env, napi_callback_info info) {
+    size_t count = 2;
+    napi_value arguments[2];
+    napi_get_cb_info(env, info, &count, arguments, NULL, NULL);
+    char *method = count > 0 ? string_argument(env, arguments[0]) : NULL;
+    char *options = count > 1 ? string_argument(env, arguments[1]) : NULL;
+    if (method == NULL || options == NULL) {
+        free(method);
+        free(options);
+        napi_throw_type_error(env, NULL, "call(method, optionsJson) takes two strings");
+        return NULL;
+    }
+    char *reply = afm_call(method, options);
+    napi_value result;
+    napi_create_string_utf8(env, reply, NAPI_AUTO_LENGTH, &result);
+    afm_free(reply);
+    free(method);
+    free(options);
+    return result;
+}
+
+NAPI_MODULE_INIT() {
+    napi_property_descriptor properties[] = {
+        { "call", NULL, call, NULL, NULL, NULL, napi_default, NULL },
+        { "setListener", NULL, set_listener, NULL, NULL, NULL, napi_default, NULL }
+    };
+    napi_define_properties(env, exports, 2, properties);
+    return exports;
+}

package/electron/afm.node.sha256

@@ -0,0 +1 @@
+2e804dcb3921aad737e0924db1975955882393feff18f01dddd48bb5a7855ad3