first commit

packages/mobile/README.md

@@ -0,0 +1,24 @@
+# @wrnexus/mobile
+
+SSR-safe access to Capacitor plugins from WrNexus browser code.
+
+```bash
+wrnexus mobile add @capacitor/camera
+```
+
+```ts
+import { Camera } from "@capacitor/camera";
+import { mobile } from "@wrnexus/mobile";
+
+if (mobile.isNative()) {
+  mobile.registerPlugin("Camera", Camera);
+  const photo = await mobile.invoke("Camera", "getPhoto", { resultType: "uri" });
+}
+```
+
+`isNative()` is false and `platform()` is `web` during SSR. `plugin()` returns
+`undefined` when unavailable; `requirePlugin()` and `invoke()` throw an
+actionable `MobileUnavailableError`.
+
+Import and register Capacitor packages only from browser-owned code. Do not
+import them in server routes, SSR helpers, or other Bun-only modules.

packages/mobile/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@wrnexus/mobile",
+  "version": "0.2.12",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@wrnexus/native": "workspace:*"
+  }
+}

packages/mobile/src/index.ts

@@ -0,0 +1,91 @@
+/** @wrnexus/mobile — SSR-safe access to Capacitor's native bridge. */
+
+export { native } from "@wrnexus/native";
+
+export type MobilePlatform = "ios" | "android" | "web" | string;
+
+export interface CapacitorBridge {
+  isNativePlatform?: () => boolean;
+  getPlatform?: () => MobilePlatform;
+  Plugins?: Record<string, unknown>;
+}
+
+export class MobileUnavailableError extends Error {
+  constructor(message = "A Capacitor native runtime is not available") {
+    super(message);
+    this.name = "MobileUnavailableError";
+  }
+}
+
+function bridge(): CapacitorBridge | undefined {
+  if (typeof globalThis === "undefined") return undefined;
+  return (globalThis as typeof globalThis & { Capacitor?: CapacitorBridge }).Capacitor;
+}
+
+const registered = new Map<string, object>();
+
+/** Register a plugin imported by browser-only application code. */
+export function registerPlugin<T extends object>(name: string, instance: T): T {
+  registered.set(name, instance);
+  return instance;
+}
+
+/** True only inside a native Capacitor iOS or Android WebView. SSR-safe. */
+export function isNative(): boolean {
+  return bridge()?.isNativePlatform?.() ?? false;
+}
+
+/** Current Capacitor platform, falling back to `web` during SSR and in browsers. */
+export function platform(): MobilePlatform {
+  return bridge()?.getPlatform?.() ?? "web";
+}
+
+/** Return an injected Capacitor plugin, or undefined when it is unavailable. */
+export function plugin<T extends object>(name: string): T | undefined {
+  if (!isNative()) return undefined;
+  return (registered.get(name) ?? bridge()?.Plugins?.[name]) as T | undefined;
+}
+
+/** Require an installed native plugin and produce a useful error when absent. */
+export function requirePlugin<T extends object>(name: string): T {
+  const value = plugin<T>(name);
+  if (!value) {
+    throw new MobileUnavailableError(
+      `Capacitor plugin "${name}" is unavailable. Run \`wrnexus mobile add <package>\` and rebuild the native app.`,
+    );
+  }
+  return value;
+}
+
+/** Invoke a plugin method without importing native code into an SSR module. */
+export async function invoke<TResult = unknown>(
+  pluginName: string,
+  method: string,
+  options?: unknown,
+): Promise<TResult> {
+  const target = requirePlugin<Record<string, unknown>>(pluginName);
+  const fn = target[method];
+  if (typeof fn !== "function") {
+    throw new MobileUnavailableError(`Capacitor plugin "${pluginName}" has no method "${method}".`);
+  }
+  return (await fn.call(target, options)) as TResult;
+}
+
+/** Run native behavior when available, with an optional SSR/web fallback. */
+export async function whenNative<T>(
+  native: () => T | Promise<T>,
+  fallback?: () => T | Promise<T>,
+): Promise<T | undefined> {
+  if (isNative()) return native();
+  return fallback?.();
+}
+
+export const mobile = {
+  isNative,
+  platform,
+  registerPlugin,
+  plugin,
+  requirePlugin,
+  invoke,
+  whenNative,
+};

packages/mobile/test/mobile.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  MobileUnavailableError,
+  invoke,
+  isNative,
+  platform,
+  plugin,
+  registerPlugin,
+  whenNative,
+} from "../src/index.ts";
+
+const root = globalThis as typeof globalThis & { Capacitor?: unknown };
+const original = root.Capacitor;
+
+afterEach(() => {
+  if (original === undefined) delete root.Capacitor;
+  else root.Capacitor = original;
+});
+
+test("falls back safely without Capacitor", async () => {
+  delete root.Capacitor;
+  expect(isNative()).toBe(false);
+  expect(platform()).toBe("web");
+  expect(plugin("Camera")).toBeUndefined();
+  expect(
+    await whenNative(
+      () => "native",
+      () => "browser",
+    ),
+  ).toBe("browser");
+});
+
+test("exposes and invokes injected plugins", async () => {
+  root.Capacitor = {
+    isNativePlatform: () => true,
+    getPlatform: () => "android",
+    Plugins: { Haptics: { impact: async (options: unknown) => ({ options, completed: true }) } },
+  };
+  expect(isNative()).toBe(true);
+  expect(platform()).toBe("android");
+  expect(plugin("Haptics")).toBeDefined();
+  expect(
+    await invoke<{ options: { style: string }; completed: boolean }>("Haptics", "impact", {
+      style: "MEDIUM",
+    }),
+  ).toEqual({
+    options: { style: "MEDIUM" },
+    completed: true,
+  });
+});
+
+test("registered JavaScript plugin proxies take precedence", async () => {
+  root.Capacitor = { isNativePlatform: () => true, Plugins: {} };
+  registerPlugin("Device", { getInfo: async () => ({ model: "test" }) });
+  expect(await invoke<{ model: string }>("Device", "getInfo")).toEqual({ model: "test" });
+});
+
+test("explains missing plugins", async () => {
+  root.Capacitor = { isNativePlatform: () => true, Plugins: {} };
+  expect(invoke("Camera", "getPhoto")).rejects.toBeInstanceOf(MobileUnavailableError);
+});