cartridge-gg · broody · Jan 28, 2026 · Jan 27, 2026 · Jan 27, 2026 · broody
diff --git a/.tool-versions b/.tool-versions
@@ -1,3 +1,3 @@
 scarb 2.9.4
 starknet-foundry 0.38.3
-nodejs v20.11.1
+nodejs 22.22.0
diff --git a/examples/capacitor/README.md b/examples/capacitor/README.md
@@ -0,0 +1,80 @@
+# Cartridge + Capacitor Session Example
+
+This example shows how to create and use a Controller session inside a
+Capacitor app. It uses the web session provider and opens the authorization
+URL in the system browser on native platforms.
+
+## Setup
+
+From the repo root:
+
+```bash
+pnpm install
+```
+
+Run the web version:
+
+```bash
+pnpm -C examples/capacitor dev
+```
+
+Build for Capacitor:
+
+```bash
+pnpm -C examples/capacitor build
+```
+
+Initialize native projects (first time):
+
+```bash
+pnpm -C examples/capacitor exec -- cap add ios
+pnpm -C examples/capacitor exec -- cap add android
+```
+
+Sync updates after builds:
+
+```bash
+pnpm -C examples/capacitor exec -- cap sync
+```
+
+## Live reload on device
+
+The Capacitor CLI expects the dev server on port 3000 by default. This example
+configures Vite to use port 3000, so just run:
+
+```bash
+pnpm -C examples/capacitor dev
+pnpm -C examples/capacitor exec -- cap run ios -l --external
+```
+
+## Deep link setup (required for session redirect)
+
+The session flow redirects back to the app using the custom scheme
+`cartridge-session://session`.
+
+### iOS
+
+1. Open the iOS project: `pnpm -C examples/capacitor exec -- cap open ios`
+2. In Xcode, select the App target → **Info** → **URL Types**
+3. Add a new URL type with **URL Schemes** set to `cartridge-session`
+
+### Android
+
+Add an intent filter for the custom scheme in
+`android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<intent-filter>
+  <action android:name=\"android.intent.action.VIEW\" />
+  <category android:name=\"android.intent.category.DEFAULT\" />
+  <category android:name=\"android.intent.category.BROWSABLE\" />
+  <data android:scheme=\"cartridge-session\" android:host=\"session\" />
+</intent-filter>
+```
+
+## Notes
+
+- The provider opens the session URL with `window.open`. In native builds we
+  intercept it with `@capacitor/browser` to ensure the system browser opens.
+- After authorizing the session in the browser, return to the app to complete
+  the flow.
diff --git a/examples/capacitor/capacitor.config.ts b/examples/capacitor/capacitor.config.ts
@@ -0,0 +1,9 @@
+import { CapacitorConfig } from "@capacitor/cli";
+
+const config: CapacitorConfig = {
+  appId: "gg.cartridge.controller.capacitor",
+  appName: "Cartridge Session",
+  webDir: "dist",
+};
+
+export default config;
diff --git a/examples/capacitor/index.html b/examples/capacitor/index.html
@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Cartridge Session + Capacitor</title>
+    <style>
+      :root {
+        font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+        color: #101827;
+        background: #f6f7fb;
+      }
+      body {
+        margin: 0;
+        padding: 32px;
+      }
+      .card {
+        max-width: 720px;
+        background: #fff;
+        border-radius: 16px;
+        padding: 24px;
+        box-shadow: 0 10px 30px rgba(16, 24, 39, 0.08);
+      }
+      h1 {
+        margin: 0 0 12px 0;
+        font-size: 22px;
+      }
+      p {
+        margin: 0 0 16px 0;
+        color: #4b5563;
+        line-height: 1.5;
+      }
+      button {
+        border: 0;
+        border-radius: 10px;
+        padding: 12px 16px;
+        font-weight: 600;
+        cursor: pointer;
+        margin-right: 10px;
+      }
+      #connect {
+        background: #2563eb;
+        color: white;
+      }
+      #execute {
+        background: #10b981;
+        color: white;
+      }
+      #status {
+        margin-top: 16px;
+        padding: 12px;
+        border-radius: 10px;
+        background: #f3f4f6;
+        font-size: 13px;
+        white-space: pre-wrap;
+      }
+      .hint {
+        font-size: 12px;
+        color: #6b7280;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>Capacitor Session Example</h1>
+      <p>
+        Registers a Controller session and uses it to submit a test transfer on
+        Sepolia.
+      </p>
+      <button id="connect">Connect Session</button>
+      <button id="execute" disabled>Execute Transfer</button>
+      <div id="status">Idle</div>
+      <p class="hint">
+        On mobile, a browser window will open for authorization. After approval,
+        return to the app to continue.
+      </p>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/examples/capacitor/ios/.gitignore b/examples/capacitor/ios/.gitignore
@@ -0,0 +1,13 @@
+App/build
+App/Pods
+App/output
+App/App/public
+DerivedData
+xcuserdata
+
+# Cordova plugins for Capacitor
+capacitor-cordova-ios-plugins
+
+# Generated Config files
+App/App/capacitor.config.json
+App/App/config.xml