WRNexusJSDoc/app/pages/packages/mobile.wrn

page wrnexusmobile {
  seo {
    title = "@wrnexus/mobile"
    description = "SSR-safe compatibility access to Capacitor plugins."
  }

  view {
    <div class="docs-shell">
      <a class="skip-link" href="#main">Skip to content</a>
      <header class="topbar">
        <a class="brand" href="/"><span>W</span> WRNexusJS</a>
        <nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
        <div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.24</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
      </header>
      <div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
      <main class="page package-page">
      <aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Native</span><h2>@wrnexus/mobile</h2><p>SSR-safe compatibility access to Capacitor plugins.</p><span class="status status-beta">Private preview · 0.2.24</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
      <article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Native · Preview</span><h1>@wrnexus/mobile</h1><p>SSR-safe compatibility access to Capacitor plugins.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/mobile@0.2.24</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide" class="prose"><blockquote>SSR-safe access to Capacitor plugins from WRNexusJS browser code.</blockquote>
<h3 id="overview">Overview</h3>
<p><code>@wrnexus/mobile</code> keeps optional native imports out of server rendering while giving browser-owned modules one consistent registry for Capacitor plugins. During SSR, <code>mobile.isNative()</code> is <code>false</code> and <code>mobile.platform()</code> is <code>&quot;web&quot;</code>.</p>
<p>Install a plugin through the WRNexusJS CLI so the web and native projects stay aligned:</p>
<pre data-language="bash"><code>wrnexus mobile add @capacitor/camera @capacitor/haptics</code></pre>
<h3 id="usage">Usage</h3>
<h4 id="register-and-invoke-a-capacitor-plugin">Register and invoke a Capacitor plugin</h4>
<p>Import Capacitor packages only from browser-owned code, never from API routes or SSR helpers.</p>
<pre data-language="ts"><code>import &#123; Camera, CameraResultType &#125; from &quot;@capacitor/camera&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

mobile.registerPlugin(&quot;Camera&quot;, Camera);

export async function takePhoto() &#123;
  if (!mobile.isNative()) return null;
  return mobile.invoke(&quot;Camera&quot;, &quot;getPhoto&quot;, &#123;
    quality: 85,
    resultType: CameraResultType.Uri,
  &#125;);
&#125;</code></pre>
<h4 id="provide-a-browser-fallback">Provide a browser fallback</h4>
<p><code>whenNative</code> runs the first callback only in a Capacitor WebView and can return a web/SSR-safe fallback everywhere else.</p>
<pre data-language="ts"><code>import &#123; Haptics, ImpactStyle &#125; from &quot;@capacitor/haptics&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

mobile.registerPlugin(&quot;Haptics&quot;, Haptics);

export const confirmAction = () =&gt;
  mobile.whenNative(
    () =&gt; mobile.invoke(&quot;Haptics&quot;, &quot;impact&quot;, &#123; style: ImpactStyle.Medium &#125;),
    () =&gt; navigator.vibrate?.(30),
  );</code></pre>
<h4 id="read-an-optional-plugin-without-throwing">Read an optional plugin without throwing</h4>
<pre data-language="ts"><code>import type &#123; NetworkPlugin &#125; from &quot;@capacitor/network&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

const network = mobile.plugin&lt;NetworkPlugin&gt;(&quot;Network&quot;);
const status = network ? await network.getStatus() : &#123; connected: true, connectionType: &quot;unknown&quot; &#125;;</code></pre>
<h3 id="api">API</h3>
<ul>
<li><code>registerPlugin(name, instance)</code> registers a browser-imported plugin.</li>
<li><code>plugin(name)</code> returns a plugin or <code>undefined</code>; <code>requirePlugin(name)</code> throws when absent.</li>
<li><code>invoke(plugin, method, options?)</code> calls a registered method and returns its result.</li>
<li><code>whenNative(native, fallback?)</code> selects native behavior without breaking SSR.</li>
<li><code>isNative()</code> and <code>platform()</code> report the current Capacitor environment.</li>
</ul>
<p>Unavailable required plugins throw <code>MobileUnavailableError</code> with an actionable message.</p>
<h3 id="requirements-notes">Requirements / Notes</h3>
<ul>
<li>Capacitor plugin imports must remain in browser-owned modules.</li>
<li><code>@wrnexus/mobile</code> re-exports <code>native</code> from <code>@wrnexus/native</code> for applications that</li>
<p>prefer the higher-level cross-platform capability API.</p>
</ul></section><section id="api" class="prose api"><h2>Complete TypeScript API</h2><p>This declaration comes from the exact installed package and lists its exported functions, classes, interfaces, and types.</p><pre data-language="typescript"><code>export &#123; native &#125; from '@wrnexus/native';

/** @wrnexus/mobile — SSR-safe access to Capacitor's native bridge. */

type MobilePlatform = &quot;ios&quot; | &quot;android&quot; | &quot;web&quot; | string;
interface CapacitorBridge &#123;
    isNativePlatform?: () =&gt; boolean;
    getPlatform?: () =&gt; MobilePlatform;
    Plugins?: Record&lt;string, unknown&gt;;
&#125;
declare class MobileUnavailableError extends Error &#123;
    constructor(message?: string);
&#125;
/** Register a plugin imported by browser-only application code. */
declare function registerPlugin&lt;T extends object&gt;(name: string, instance: T): T;
/** True only inside a native Capacitor iOS or Android WebView. SSR-safe. */
declare function isNative(): boolean;
/** Current Capacitor platform, falling back to `web` during SSR and in browsers. */
declare function platform(): MobilePlatform;
/** Return an injected Capacitor plugin, or undefined when it is unavailable. */
declare function plugin&lt;T extends object&gt;(name: string): T | undefined;
/** Require an installed native plugin and produce a useful error when absent. */
declare function requirePlugin&lt;T extends object&gt;(name: string): T;
/** Invoke a plugin method without importing native code into an SSR module. */
declare function invoke&lt;TResult = unknown&gt;(pluginName: string, method: string, options?: unknown): Promise&lt;TResult&gt;;
/** Run native behavior when available, with an optional SSR/web fallback. */
declare function whenNative&lt;T&gt;(native: () =&gt; T | Promise&lt;T&gt;, fallback?: () =&gt; T | Promise&lt;T&gt;): Promise&lt;T | undefined&gt;;
declare const mobile: &#123;
    isNative: typeof isNative;
    platform: typeof platform;
    registerPlugin: typeof registerPlugin;
    plugin: typeof plugin;
    requirePlugin: typeof requirePlugin;
    invoke: typeof invoke;
    whenNative: typeof whenNative;
&#125;;

export &#123; type CapacitorBridge, type MobilePlatform, MobileUnavailableError, invoke, isNative, mobile, platform, plugin, registerPlugin, requirePlugin, whenNative &#125;;
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Examples are taken from this package's installed documentation and must be evaluated with its requirements and stability notes.</p><div class="example-grid"><article class="example-card"><h3>Register and invoke a Capacitor plugin</h3><pre data-language="ts"><code>import &#123; Camera, CameraResultType &#125; from &quot;@capacitor/camera&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

mobile.registerPlugin(&quot;Camera&quot;, Camera);

export async function takePhoto() &#123;
  if (!mobile.isNative()) return null;
  return mobile.invoke(&quot;Camera&quot;, &quot;getPhoto&quot;, &#123;
    quality: 85,
    resultType: CameraResultType.Uri,
  &#125;);
&#125;</code></pre></article><article class="example-card"><h3>Provide a browser fallback</h3><pre data-language="ts"><code>import &#123; Haptics, ImpactStyle &#125; from &quot;@capacitor/haptics&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

mobile.registerPlugin(&quot;Haptics&quot;, Haptics);

export const confirmAction = () =&gt;
  mobile.whenNative(
    () =&gt; mobile.invoke(&quot;Haptics&quot;, &quot;impact&quot;, &#123; style: ImpactStyle.Medium &#125;),
    () =&gt; navigator.vibrate?.(30),
  );</code></pre></article><article class="example-card"><h3>Read an optional plugin without throwing</h3><pre data-language="ts"><code>import type &#123; NetworkPlugin &#125; from &quot;@capacitor/network&quot;;
import &#123; mobile &#125; from &quot;@wrnexus/mobile&quot;;

const network = mobile.plugin&lt;NetworkPlugin&gt;(&quot;Network&quot;);
const status = network ? await network.getStatus() : &#123; connected: true, connectionType: &quot;unknown&quot; &#125;;</code></pre></article></div></section></article>
      <aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#register-and-invoke-a-capacitor-plugin">Register and invoke a Capacitor plugin</a><a class="toc-level-4" href="#provide-a-browser-fallback">Provide a browser fallback</a><a class="toc-level-4" href="#read-an-optional-plugin-without-throwing">Read an optional plugin without throwing</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
    </main>
      <footer>WRNexusJS 0.2.24 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
    </div>
  }
}