@tokamakdev/plugin 0.1.0-beta.83 → 0.1.0-beta.85

package/README.md

@@ -1,17 +1,70 @@
 # @tokamakdev/plugin
 
-The shared base of tokamak plugins: the page's native transport, Worker events,
-and test fakes.
+The shared base of tokamak plugins: the native transport, Worker events, and
+test fakes.
 
 | Entry | Contents |
 | --- | --- |
-| `@tokamakdev/plugin` | `FrontendPlugin`, the base class of a plugin's page API |
+| `@tokamakdev/plugin` | `Plugin`, the base class of a plugin's API, which the page and the Worker call alike |
 | `@tokamakdev/plugin/events` | `defineEvent`, which defines a plugin's Worker events |
 | `@tokamakdev/plugin/testing` | A fake native transport, and `dispatch`, which runs event listeners as the runtime does |
 
 A plugin lists `@tokamakdev/plugin` as a peer dependency, so an app has one
 copy of it, shared with `@tokamakdev/tok`, which depends on it.
 
+## Calls
+
+A plugin's API extends `Plugin`, whose `call` and `listen` reach its native
+code from the page through the shell's bridge, and from the Worker through the
+runtime. `hasNativeTransport` is false outside a tokamak app, such as on the
+web and Cloudflare, where the plugin uses its web implementation or rejects
+with `NotSupportedError`:
+
+```ts
+import { Plugin } from "@tokamakdev/plugin";
+
+class Alarms extends Plugin {
+  constructor() {
+    super("alarms");
+  }
+
+  set(at: number): Promise<void> {
+    return this.call("set", { at });
+  }
+
+  onRing(next: (id: string) => void, error: (error: DOMException) => void): () => void {
+    return this.listen("onRing", next, error);
+  }
+}
+
+export const alarms = new Alarms();
+```
+
+The native side runs each call and subscription on the main thread, for the
+page and the Worker alike. A `subscribe` that throws, as for a method the
+plugin does not have, ends the subscription; a failure it replies with does
+not.
+
+## Showing UI
+
+Calls come at any time, including while the app is off screen. Native code
+that would show UI then fails with `NeedsUIError` instead, through the host,
+so only calls that would show UI fail:
+
+- **Android:** `requestPermissions` throws `NeedsUIError` when a permission
+  would prompt while the app is in the background, and answers at once,
+  without UI, when none would. The host remembers the permissions the user has
+  refused for good, as Android reports them the same way as permissions never
+  asked for; `wouldPrompt` tells them apart. Other UI goes in the
+  activity `requireForegroundActivity()` returns, which throws `NeedsUIError`
+  in the background; `authenticateOwner` uses it. `isInForeground` reports the
+  app's stage.
+- **Apple:** `requireUI()` throws `NeedsUIError` on iOS while the app is in
+  the background. Call it on the main thread where the plugin decides to show
+  UI, and only when the UI would appear, such as before
+  `requestWhenInUseAuthorization` while the authorization is not determined.
+  A hidden macOS app still shows system prompts, so it never throws there.
+
 ## Worker events
 
 A plugin's native code delivers events to the app's Worker, whose listeners

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin",
-  "version": "0.1.0-beta.83",
+  "version": "0.1.0-beta.85",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",

package/src/index.ts

@@ -30,8 +30,24 @@ interface PendingSubscription {
 
 type Pending = PendingCall | PendingSubscription;
 
+/** Calls `method` of `plugin` from the Worker, resolving with its value. */
+type WorkerCall = (plugin: string, method: string, arguments_: unknown) => Promise<unknown>;
+
+/** Subscribes to `method` of `plugin` from the Worker, returning the function that unsubscribes. */
+type WorkerListen = (
+  plugin: string,
+  method: string,
+  arguments_: unknown,
+  next: (value: unknown) => void,
+  error: (error: DOMException) => void,
+) => () => void;
+
 declare global {
+  /** The page's native transport, which the shells define. */
   var __tokamakNative: NativeTransport | undefined;
+  /** The Worker's native calls, which the runtime and `tok dev` define. */
+  var __tokamakNativeCall: WorkerCall | undefined;
+  var __tokamakNativeListen: WorkerListen | undefined;
 }
 
 let nextRequestId = 1;
@@ -39,17 +55,24 @@ const session = `${String(Date.now())}-${String(Math.random())}`;
 let connected: NativeTransport | undefined;
 const pending = new Map<number, Pending>();
 
-export abstract class FrontendPlugin {
+/** The base class of a plugin's API, which the page and the Worker call alike. */
+export abstract class Plugin {
   protected constructor(private readonly pluginId: string) {}
 
   protected get hasNativeTransport(): boolean {
-    return nativeTransport() !== undefined;
+    return pageTransport() !== undefined || globalThis.__tokamakNativeCall !== undefined;
   }
 
   protected call<T>(method: string, arguments_: unknown = null): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-      send("call", this.pluginId, method, arguments_, { kind: "call", resolve, reject });
-    });
+    const page = pageTransport();
+    if (page) {
+      return new Promise<T>((resolve, reject) => {
+        send(page, this.pluginId, method, arguments_, { kind: "call", resolve, reject });
+      });
+    }
+    const call = globalThis.__tokamakNativeCall;
+    if (call) return call(this.pluginId, method, arguments_) as Promise<T>;
+    return Promise.reject(unavailable());
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T types the native values, as in call.
@@ -59,47 +82,58 @@ export abstract class FrontendPlugin {
     error: (error: DOMException) => void,
     arguments_: unknown = null,
   ): () => void {
-    const { transport, id } = send("subscribe", this.pluginId, method, arguments_, {
-      kind: "subscription",
-      next,
-      error,
-    });
-    return () => {
-      if (!pending.delete(id)) return;
-      transport.postMessage(JSON.stringify({ type: "cancel", session, id }));
-    };
+    const page = pageTransport();
+    if (page) {
+      const id = send(page, this.pluginId, method, arguments_, {
+        kind: "subscription",
+        next,
+        error,
+      });
+      return () => {
+        if (!pending.delete(id)) return;
+        page.postMessage(JSON.stringify({ type: "cancel", session, id }));
+      };
+    }
+    const listen = globalThis.__tokamakNativeListen;
+    if (listen) return listen(this.pluginId, method, arguments_, next as (value: unknown) => void, error);
+    throw unavailable();
   }
 }
 
-function nativeTransport(): NativeTransport | undefined {
+function unavailable(): DOMException {
+  return new DOMException("Native plugin transport is unavailable", "NotSupportedError");
+}
+
+/** The page's native transport, connected on first use. */
+function pageTransport(): NativeTransport | undefined {
   const transport = globalThis.__tokamakNative;
   if (!transport || typeof transport.postMessage !== "function") return undefined;
-  if (connected !== transport) {
-    connected = transport;
-    transport.onmessage = ({ data }) => {
-      receive(JSON.parse(data) as NativeResponse);
-    };
-    transport.postMessage(JSON.stringify({ type: "reset", session }));
-  }
+  if (connected !== transport) connect(transport);
   return transport;
 }
 
-function requireNativeTransport(): NativeTransport {
-  const transport = nativeTransport();
-  if (transport) return transport;
-  throw new DOMException("Native plugin transport is unavailable", "NotSupportedError");
+function connect(transport: NativeTransport): void {
+  if (!connected) {
+    const page: { addEventListener?: (type: string, listener: () => void) => void } = globalThis;
+    page.addEventListener?.("pagehide", cancelSubscriptions);
+  }
+  connected = transport;
+  transport.onmessage = ({ data }) => {
+    receive(JSON.parse(data) as NativeResponse);
+  };
+  transport.postMessage(JSON.stringify({ type: "reset", session }));
 }
 
 /** Posts a call or subscription, keeping `request` pending unless posting throws. */
 function send(
-  type: "call" | "subscribe",
+  transport: NativeTransport,
   plugin: string,
   method: string,
   arguments_: unknown,
   request: Pending,
-): { transport: NativeTransport; id: number } {
-  const transport = requireNativeTransport();
+): number {
   const id = nextRequestId++;
+  const type = request.kind === "call" ? "call" : "subscribe";
   pending.set(id, request);
   try {
     transport.postMessage(
@@ -109,7 +143,7 @@ function send(
     pending.delete(id);
     throw error;
   }
-  return { transport, id };
+  return id;
 }
 
 function receive(response: NativeResponse): void {
@@ -129,15 +163,11 @@ function receive(response: NativeResponse): void {
   else request.next(response.value);
 }
 
-const eventTarget: {
-  addEventListener?: (type: string, listener: () => void) => void;
-} = globalThis;
-
-eventTarget.addEventListener?.("pagehide", () => {
+function cancelSubscriptions(): void {
   if (!connected) return;
   for (const [id, request] of pending) {
     if (request.kind !== "subscription") continue;
     pending.delete(id);
     connected.postMessage(JSON.stringify({ type: "cancel", session, id }));
   }
-});
+}