@tangle-network/blueprint-ui 0.1.1 → 0.3.0

package/src/host/types.ts

@@ -0,0 +1,111 @@
+export type BlueprintAppVisibility = 'first-party' | 'third-party';
+
+export type BlueprintPublisherVerification =
+  | 'first-party'
+  | 'verified'
+  | 'unverified';
+
+export type BlueprintExperienceTier =
+  | 'generic'
+  | 'declarative'
+  | 'curated-module'
+  | 'external-app';
+
+export type BlueprintSlugPolicy =
+  | 'reserved'
+  | 'publisher-scoped'
+  | 'public-requested';
+
+export type BlueprintUiSurface =
+  | 'generic-overview'
+  | 'service-explorer'
+  | 'service-console'
+  | 'actions-panel'
+  | 'resources'
+  | 'chat'
+  | 'vaults'
+  | 'metrics'
+  | 'permissions';
+
+export type BlueprintResourceRoute =
+  | 'bots'
+  | 'agents'
+  | 'runs'
+  | 'vault'
+  | 'chat'
+  | 'custom';
+
+export type BlueprintPermissionScope =
+  | 'blueprint'
+  | 'service'
+  | 'resource';
+
+export type BlueprintExternalAppMode = 'link' | 'iframe';
+export type BlueprintExternalAppTrust = 'trusted' | 'restricted';
+
+export type BlueprintPublisher = {
+  label: string;
+  namespace?: string;
+  visibility: BlueprintAppVisibility;
+  verification: BlueprintPublisherVerification;
+};
+
+export type BlueprintResourceModel = {
+  serviceNoun: string;
+  resourceNoun: string;
+  resourceRoute?: BlueprintResourceRoute;
+};
+
+export type BlueprintPermissionDescriptor = {
+  key: string;
+  label: string;
+  scope: BlueprintPermissionScope;
+  description?: string;
+};
+
+export type BlueprintExternalAppConfig = {
+  url: string;
+  mode: BlueprintExternalAppMode;
+  label?: string;
+  host: string;
+  trust: BlueprintExternalAppTrust;
+  reason?: string;
+};
+
+export type BlueprintUiManifest = {
+  displayName: string;
+  tagline: string;
+  description: string;
+  surfaces: BlueprintUiSurface[];
+  resources: BlueprintResourceModel;
+  permissions?: BlueprintPermissionDescriptor[];
+  externalApp?: BlueprintExternalAppConfig;
+};
+
+export type BlueprintAppModuleBinding = {
+  moduleId: string;
+  status: 'active' | 'planned';
+};
+
+export type BlueprintAppEntry = {
+  slug: string;
+  canonicalSlug?: string;
+  blueprintId?: bigint;
+  publisher: BlueprintPublisher;
+  tier: BlueprintExperienceTier;
+  slugPolicy: BlueprintSlugPolicy;
+  manifest: BlueprintUiManifest;
+  module?: BlueprintAppModuleBinding;
+};
+
+export type BlueprintAppResolvedView = {
+  slug: string;
+  canonicalSlug: string;
+  blueprintId?: bigint;
+  publisher: BlueprintPublisher;
+  tier: BlueprintExperienceTier;
+  slugPolicy: BlueprintSlugPolicy;
+  manifest: BlueprintUiManifest;
+  module?: BlueprintAppModuleBinding;
+  fallbackEnabled: boolean;
+};

package/src/index.ts

@@ -61,9 +61,49 @@ export {
   getJobById,
 } from './blueprints/registry';
 
+// ── Blueprint Host ──
+export type {
+  BlueprintAppVisibility,
+  BlueprintPublisherVerification,
+  BlueprintExperienceTier,
+  BlueprintSlugPolicy,
+  BlueprintUiSurface,
+  BlueprintResourceRoute,
+  BlueprintPermissionScope,
+  BlueprintExternalAppMode,
+  BlueprintExternalAppTrust,
+  BlueprintPublisher,
+  BlueprintResourceModel,
+  BlueprintPermissionDescriptor,
+  BlueprintExternalAppConfig,
+  BlueprintUiManifest,
+  BlueprintAppModuleBinding,
+  BlueprintAppEntry,
+  BlueprintAppResolvedView,
+} from './host';
+export {
+  buildCanonicalBlueprintSlug,
+  resolveBlueprintAppView,
+  toBlueprintAppEntry,
+  getBlueprintExperienceTierLabel,
+  getBlueprintSlugPolicyLabel,
+  getBlueprintSurfaceLabel,
+  getBlueprintPublisherVerificationLabel,
+  getExternalAppTrustLabel,
+  isVerifiedBlueprintPublisher,
+  canPublisherClaimSlug,
+  isTrustedExternalAppHost,
+  getBlueprintPath,
+  getBlueprintServicePath,
+  sanitizeBlueprintSlugPart,
+  deriveBlueprintRequestedSlug,
+} from './host';
+export type { BlueprintHostHeroProps, BlueprintHostPanelProps } from './host';
+export { BlueprintHostHero, BlueprintHostPanel } from './host';
+
 // ── Hooks ──
 export type { DiscoveredOperator } from './hooks/useOperators';
-export { useOperators } from './hooks/useOperators';
+export { discoverOperatorsWithClient, useOperators } from './hooks/useOperators';
 export type { JobFormState } from './hooks/useJobForm';
 export { useJobForm } from './hooks/useJobForm';
 export type { JobQuote, UseJobPriceResult, JobPriceEntry, UseJobPricesResult } from './hooks/useJobPrice';

package/src/stores/infra.ts

@@ -1,7 +1,8 @@
 import { persistedAtom } from './persistedAtom';
+import { getEnvVar } from '../utils/env';
 
-const defaultBlueprintId = import.meta.env.VITE_BLUEPRINT_ID ?? '0';
-const defaultServiceId = import.meta.env.VITE_SERVICE_ID ?? import.meta.env.VITE_SERVICE_IDS?.split(',')[0] ?? '0';
+const defaultBlueprintId = getEnvVar('VITE_BLUEPRINT_ID') ?? '0';
+const defaultServiceId = getEnvVar('VITE_SERVICE_ID') ?? getEnvVar('VITE_SERVICE_IDS')?.split(',')[0] ?? '0';
 
 export interface OperatorInfo {
   address: string;

package/src/styles.css

@@ -0,0 +1,128 @@
+:root,
+.bp-tone-cloud {
+  --bp-font-display: var(--font-display, 'Outfit', system-ui, sans-serif);
+  --bp-font-data: var(--font-data, 'IBM Plex Mono', 'JetBrains Mono', ui-monospace, monospace);
+
+  --bp-glass-bg: var(--glass-bg, transparent);
+  --bp-glass-bg-strong: var(--glass-bg-strong, var(--bp-glass-bg, transparent));
+  --bp-glass-border: var(--glass-border, transparent);
+  --bp-glass-border-hover: var(--glass-border-hover, var(--bp-glass-border, transparent));
+  --bp-glass-blur: var(--glass-blur, 0px);
+  --bp-glass-blur-strong: 24px;
+
+  --bp-elements-borderColor: var(--cloud-elements-borderColor, rgba(240, 240, 245, 0.06));
+  --bp-elements-borderColorActive: var(--cloud-elements-borderColorActive, #8B5CF6);
+
+  --bp-elements-bg-depth-1: var(--cloud-elements-bg-depth-1, #0A0A0F);
+  --bp-elements-bg-depth-2: var(--cloud-elements-bg-depth-2, #12121A);
+  --bp-elements-bg-depth-3: var(--cloud-elements-bg-depth-3, #1A1A25);
+  --bp-elements-bg-depth-4: var(--cloud-elements-bg-depth-4, #22222E);
+
+  --bp-elements-textPrimary: var(--cloud-elements-textPrimary, #F0F0F5);
+  --bp-elements-textSecondary: var(--cloud-elements-textSecondary, #8A8A9E);
+  --bp-elements-textTertiary: var(--cloud-elements-textTertiary, #5A5A6E);
+
+  --bp-elements-button-primary-background: var(--cloud-elements-button-primary-background, rgba(142, 89, 255, 0.14));
+  --bp-elements-button-primary-backgroundHover: var(--cloud-elements-button-primary-backgroundHover, rgba(142, 89, 255, 0.24));
+  --bp-elements-button-primary-text: var(--cloud-elements-button-primary-text, #A87BFF);
+
+  --bp-elements-button-secondary-background: var(--cloud-elements-button-secondary-background, rgba(240, 240, 245, 0.06));
+  --bp-elements-button-secondary-backgroundHover: var(--cloud-elements-button-secondary-backgroundHover, rgba(240, 240, 245, 0.10));
+  --bp-elements-button-secondary-text: var(--cloud-elements-button-secondary-text, #F0F0F5);
+
+  --bp-elements-button-danger-background: var(--cloud-elements-button-danger-background, rgba(255, 59, 92, 0.12));
+  --bp-elements-button-danger-backgroundHover: var(--cloud-elements-button-danger-backgroundHover, rgba(255, 59, 92, 0.20));
+  --bp-elements-button-danger-text: var(--cloud-elements-button-danger-text, #FF3B5C);
+
+  --bp-elements-icon-success: var(--cloud-elements-icon-success, #38B2AC);
+  --bp-elements-icon-error: var(--cloud-elements-icon-error, #FF4D6A);
+  --bp-elements-icon-warning: var(--cloud-elements-icon-warning, #FFB800);
+  --bp-elements-icon-primary: var(--cloud-elements-icon-primary, #F0F0F5);
+  --bp-elements-icon-secondary: var(--cloud-elements-icon-secondary, #5A5A6E);
+
+  --bp-elements-dividerColor: var(--cloud-elements-dividerColor, rgba(240, 240, 245, 0.06));
+  --bp-elements-item-backgroundHover: var(--cloud-elements-item-backgroundHover, rgba(240, 240, 245, 0.03));
+  --bp-elements-item-backgroundActive: var(--cloud-elements-item-backgroundActive, rgba(240, 240, 245, 0.06));
+  --bp-elements-focus: var(--cloud-elements-focus, #8B5CF6);
+}
+
+.bp-tone-arena {
+  --bp-elements-borderColor: var(--arena-elements-borderColor, var(--bp-elements-borderColor));
+  --bp-elements-borderColorActive: var(--arena-elements-borderColorActive, var(--bp-elements-borderColorActive));
+
+  --bp-elements-bg-depth-1: var(--arena-elements-bg-depth-1, var(--bp-elements-bg-depth-1));
+  --bp-elements-bg-depth-2: var(--arena-elements-bg-depth-2, var(--bp-elements-bg-depth-2));
+  --bp-elements-bg-depth-3: var(--arena-elements-bg-depth-3, var(--bp-elements-bg-depth-3));
+  --bp-elements-bg-depth-4: var(--arena-elements-bg-depth-4, var(--bp-elements-bg-depth-4));
+
+  --bp-elements-textPrimary: var(--arena-elements-textPrimary, var(--bp-elements-textPrimary));
+  --bp-elements-textSecondary: var(--arena-elements-textSecondary, var(--bp-elements-textSecondary));
+  --bp-elements-textTertiary: var(--arena-elements-textTertiary, var(--bp-elements-textTertiary));
+
+  --bp-elements-button-primary-background: var(--arena-elements-button-primary-background, var(--bp-elements-button-primary-background));
+  --bp-elements-button-primary-backgroundHover: var(--arena-elements-button-primary-backgroundHover, var(--bp-elements-button-primary-backgroundHover));
+  --bp-elements-button-primary-text: var(--arena-elements-button-primary-text, var(--bp-elements-button-primary-text));
+
+  --bp-elements-button-secondary-background: var(--arena-elements-button-secondary-background, var(--bp-elements-button-secondary-background));
+  --bp-elements-button-secondary-backgroundHover: var(--arena-elements-button-secondary-backgroundHover, var(--bp-elements-button-secondary-backgroundHover));
+  --bp-elements-button-secondary-text: var(--arena-elements-button-secondary-text, var(--bp-elements-button-secondary-text));
+
+  --bp-elements-button-danger-background: var(--arena-elements-button-danger-background, var(--bp-elements-button-danger-background));
+  --bp-elements-button-danger-backgroundHover: var(--arena-elements-button-danger-backgroundHover, var(--bp-elements-button-danger-backgroundHover));
+  --bp-elements-button-danger-text: var(--arena-elements-button-danger-text, var(--bp-elements-button-danger-text));
+
+  --bp-elements-icon-success: var(--arena-elements-icon-success, var(--bp-elements-icon-success));
+  --bp-elements-icon-error: var(--arena-elements-icon-error, var(--bp-elements-icon-error));
+  --bp-elements-icon-warning: var(--arena-elements-icon-warning, var(--bp-elements-icon-warning));
+  --bp-elements-icon-primary: var(--arena-elements-icon-primary, var(--bp-elements-icon-primary));
+  --bp-elements-icon-secondary: var(--arena-elements-icon-secondary, var(--bp-elements-icon-secondary));
+
+  --bp-elements-dividerColor: var(--arena-elements-dividerColor, var(--bp-elements-dividerColor));
+  --bp-elements-item-backgroundHover: var(--arena-elements-item-backgroundHover, var(--bp-elements-item-backgroundHover));
+  --bp-elements-item-backgroundActive: var(--arena-elements-item-backgroundActive, var(--bp-elements-item-backgroundActive));
+  --bp-elements-focus: var(--arena-elements-focus, var(--bp-elements-focus));
+}
+
+.font-display {
+  font-family: var(--bp-font-display);
+}
+
+.font-data {
+  font-family: var(--bp-font-data);
+  font-feature-settings: 'tnum' 1;
+}
+
+.glass {
+  background: var(--bp-glass-bg);
+  backdrop-filter: blur(var(--bp-glass-blur));
+  -webkit-backdrop-filter: blur(var(--bp-glass-blur));
+  border: 1px solid var(--bp-glass-border);
+}
+
+.glass-hover {
+  transition: border-color 0.2s ease, box-shadow 0.2s ease, background-color 0.2s ease;
+}
+
+.glass-hover:hover {
+  background: var(--bp-glass-bg-strong);
+  border-color: var(--bp-glass-border-hover);
+}
+
+.glass-card {
+  background: var(--bp-glass-bg);
+  backdrop-filter: blur(var(--bp-glass-blur));
+  -webkit-backdrop-filter: blur(var(--bp-glass-blur));
+  border: 1px solid var(--bp-glass-border);
+  transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.glass-card:hover {
+  border-color: var(--bp-glass-border-hover);
+}
+
+.glass-card-strong {
+  background: var(--bp-glass-bg-strong);
+  backdrop-filter: blur(var(--bp-glass-blur-strong));
+  -webkit-backdrop-filter: blur(var(--bp-glass-blur-strong));
+  border: 1px solid var(--bp-glass-border);
+}

package/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/src/utils/env.ts

@@ -0,0 +1,22 @@
+type ImportMetaEnvLike = {
+  DEV?: boolean;
+  VITE_RPC_URL?: string;
+  VITE_CHAIN_ID?: string;
+  VITE_BLUEPRINT_ID?: string;
+  VITE_SERVICE_ID?: string;
+  VITE_SERVICE_IDS?: string;
+  VITE_OPERATOR_API_URL?: string;
+};
+
+function readImportMetaEnv(): ImportMetaEnvLike {
+  return ((import.meta as ImportMeta & { env?: ImportMetaEnvLike }).env ?? {});
+}
+
+export function getEnvVar(key: keyof ImportMetaEnvLike): string | undefined {
+  const value = readImportMetaEnv()[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function isDevEnv(): boolean {
+  return Boolean(readImportMetaEnv().DEV);
+}

package/src/wallet/detectParentOrigin.ts

@@ -0,0 +1,74 @@
+// Determine which origin to trust as the parent dapp.
+//
+// `document.referrer` is the *initial* embedder — it's set when the iframe is
+// first loaded and survives reloads (though it can be cleared by `referrerpolicy`
+// or by the embedder). The Tangle Cloud iframe wrapper deliberately omits
+// `referrerpolicy="no-referrer"` so we get the embedder's origin here.
+//
+// We compare it against an allowlist of known Tangle Cloud origins. If it
+// matches, that's the parent. Otherwise the iframe is being loaded directly
+// (standalone domain visit, dev server, untrusted embedder) and the bridge
+// stays disabled — the app falls back to its normal injected/WC wallet path.
+
+/**
+ * Default Tangle Cloud origins. Consumers (agent-sandbox UI,
+ * trading-arena, future iframe blueprints) pass app-specific additions
+ * via `extraOrigins` rather than mutating this list.
+ */
+export const TANGLE_CLOUD_ORIGINS_DEFAULT = Object.freeze([
+  'https://cloud.tangle.tools',
+  'https://develop.cloud.tangle.tools',
+  // Local dev (Vite default port for tangle-cloud + Netlify dev preview).
+  'http://localhost:4300',
+  'http://localhost:8888',
+] as const);
+
+function originFromReferrer(): string | null {
+  if (typeof document === 'undefined') return null;
+  const ref = document.referrer;
+  if (!ref) return null;
+  try {
+    return new URL(ref).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns the parent origin to bridge to, or null when no trusted parent is
+ * detected. Caller should skip installing the bridge connector when this
+ * returns null.
+ *
+ * `extraOrigins` is the application's escape hatch for staging or dev
+ * deploys not covered by the default list. The library deliberately does
+ * not read environment variables itself (consumers may bundle for non-Vite
+ * runtimes); the consuming app threads `import.meta.env.VITE_*` or
+ * `process.env.*` in itself.
+ *
+ * Falls back to a `?parent=<origin>` query parameter when no referrer is
+ * present (some browsers strip referrer from cross-origin loads). Useful
+ * for dev embedding flows.
+ */
+export function detectTangleCloudParentOrigin(
+  options: { extraOrigins?: readonly string[] } = {},
+): string | null {
+  if (typeof window === 'undefined' || window.parent === window) {
+    return null;
+  }
+  const allowlist = new Set<string>([
+    ...TANGLE_CLOUD_ORIGINS_DEFAULT,
+    ...(options.extraOrigins ?? []),
+  ]);
+  const referrerOrigin = originFromReferrer();
+  if (referrerOrigin && allowlist.has(referrerOrigin)) {
+    return referrerOrigin;
+  }
+  try {
+    const url = new URL(window.location.href);
+    const explicit = url.searchParams.get('parent');
+    if (explicit && allowlist.has(explicit)) return explicit;
+  } catch {
+    // ignore
+  }
+  return null;
+}

package/src/wallet/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Tangle Cloud parent-bridge wallet adapter.
+ *
+ * iframe blueprints embedded by the Tangle Cloud dapp can't use the usual
+ * `window.ethereum` connector — browser wallet extensions don't inject into
+ * sandboxed iframes. This module ships a wagmi connector that proxies wallet
+ * operations to the parent dapp through the existing `tangle.app.*`
+ * postMessage protocol, so the iframe inherits the parent's wallet without
+ * its own picker.
+ *
+ * Usage in an iframe app's wagmi config:
+ *
+ *   import {
+ *     detectTangleCloudParentOrigin,
+ *     parentBridgeConnector,
+ *   } from '@tangle-network/blueprint-ui/wallet';
+ *
+ *   const parent = detectTangleCloudParentOrigin();
+ *   const config = createConfig(
+ *     parent !== null
+ *       ? { ...getDefaultConfig({...}), connectors: [
+ *           parentBridgeConnector({ parentOrigin: parent, appId: 'my-app' }),
+ *         ] }
+ *       : getDefaultConfig({...}),
+ *   );
+ *
+ * The bridge is intentionally the ONLY connector when running inside the
+ * dapp — surfacing injected / WalletConnect / Coinbase inside a sandboxed
+ * iframe doesn't work (no popup, no extension injection) and would just
+ * confuse operators.
+ */
+
+export {
+  detectTangleCloudParentOrigin,
+  TANGLE_CLOUD_ORIGINS_DEFAULT,
+} from './detectParentOrigin';
+
+export {
+  parentBridgeConnector,
+  type ParentBridgeConnectorOptions,
+} from './parentBridgeConnector';
+
+export {
+  ParentBridgeProvider,
+  isRunningInIframe,
+  type ParentBridgeOptions,
+} from './parentBridgeProvider';
+
+export {
+  TANGLE_IFRAME_PROTOCOL_PREFIX,
+  TANGLE_IFRAME_PROTOCOL_VERSION,
+  NO_WALLET_ADDRESS,
+  makeCorrelationId,
+  type AccountChanged,
+  type ChainChanged,
+  type HandshakeAck,
+  type HandshakeRequest,
+  type ParentMessage,
+  type ReadAccountRequest,
+  type ReadAccountResult,
+  type SignMessageRequest,
+  type SignMessageResult,
+  type SignTransactionRequest,
+  type SignTransactionResult,
+  type SwitchChainRequest,
+  type SwitchChainResult,
+} from './parentBridgeProtocol';

package/src/wallet/parentBridgeConnector.ts

@@ -0,0 +1,156 @@
+// Wagmi connector that proxies wallet operations to the Tangle Cloud parent
+// dapp via the iframe postMessage bridge. Becomes the autoConnect target
+// when this app is loaded inside an iframe sandbox without a window.ethereum
+// — i.e. always, when embedded by cloud.tangle.tools.
+//
+// Architecture: the connector owns one `ParentBridgeProvider` (singleton),
+// forwards every wagmi method to it, and reflects the provider's EIP-1193
+// events back to wagmi's emitter so the rest of the dapp (ConnectKit's
+// account chip, hooks like useAccount/useChainId) reacts to parent-state
+// changes without polling.
+
+import type { Address, Chain } from 'viem';
+import { createConnector } from 'wagmi';
+
+import { ParentBridgeProvider, type ParentBridgeOptions } from './parentBridgeProvider';
+
+export type ParentBridgeConnectorOptions = ParentBridgeOptions;
+
+export function parentBridgeConnector(options: ParentBridgeConnectorOptions) {
+  let provider: ParentBridgeProvider | undefined;
+  let installed = false;
+
+  return createConnector<ParentBridgeProvider>((config) => {
+    const ensureProvider = (): ParentBridgeProvider => {
+      if (!provider) provider = new ParentBridgeProvider(options);
+      if (!installed) {
+        provider.install();
+        installed = true;
+        // Wire the provider's EIP-1193 events to wagmi's emitter so
+        // ConnectKit and useAccount/useChainId reflect parent-state changes
+        // without polling.
+        provider.on('accountsChanged', (accounts) => {
+          config.emitter.emit('change', {
+            accounts: Array.isArray(accounts)
+              ? (accounts as readonly Address[])
+              : ([] as readonly Address[]),
+          });
+        });
+        provider.on('chainChanged', (chainIdHex) => {
+          const chainId =
+            typeof chainIdHex === 'string'
+              ? Number.parseInt(chainIdHex, 16)
+              : Number(chainIdHex);
+          if (Number.isFinite(chainId)) {
+            config.emitter.emit('change', { chainId });
+          }
+        });
+        provider.on('disconnect', () => {
+          config.emitter.emit('disconnect');
+        });
+      }
+      return provider;
+    };
+
+    return {
+      id: 'tangleParentBridge',
+      name: 'Tangle Cloud',
+      type: 'parentBridge',
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async connect(): Promise<any> {
+        // wagmi v3's connect() return type is a conditional based on
+        // `withCapabilities`. We always return plain addresses; cast through
+        // `any` rather than re-implementing the type predicate.
+        const p = ensureProvider();
+        const accountsResult = (await p.request({
+          method: 'eth_requestAccounts',
+        })) as readonly Address[];
+        const chainIdHex = (await p.request({ method: 'eth_chainId' })) as string;
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return {
+          accounts: accountsResult,
+          chainId: Number.isFinite(chainId) ? chainId : 0,
+        };
+      },
+
+      async disconnect() {
+        // Disconnect from the iframe's perspective is a local-only state
+        // reset — we can't ask the parent dapp to disconnect its wallet on
+        // our behalf, and a real disconnect should be initiated from the
+        // parent's UI. Tear down listeners + the message bridge so a future
+        // reconnect re-handshakes cleanly.
+        if (provider) provider.uninstall();
+        installed = false;
+        provider = undefined;
+      },
+
+      async getAccounts() {
+        const p = ensureProvider();
+        const cached = p.getCachedAccount();
+        if (cached) return [cached];
+        const accounts = (await p.request({
+          method: 'eth_accounts',
+        })) as readonly Address[];
+        return accounts;
+      },
+
+      async getChainId() {
+        const p = ensureProvider();
+        const cached = p.getCachedChainId();
+        if (cached !== null) return cached;
+        const chainIdHex = (await p.request({ method: 'eth_chainId' })) as string;
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return Number.isFinite(chainId) ? chainId : 0;
+      },
+
+      async getProvider() {
+        return ensureProvider();
+      },
+
+      async isAuthorized() {
+        // Always authorized when in iframe mode — the parent dapp has
+        // already gated access by being the embedder. Returning `true`
+        // makes wagmi auto-reconnect on every page load, which is the
+        // right UX (iframe → parent wallet is always-on).
+        try {
+          const p = ensureProvider();
+          const accounts = (await p.request({
+            method: 'eth_accounts',
+          })) as readonly Address[];
+          return accounts.length > 0;
+        } catch {
+          return false;
+        }
+      },
+
+      async switchChain({ chainId }): Promise<Chain> {
+        const p = ensureProvider();
+        await p.request({
+          method: 'wallet_switchEthereumChain',
+          params: [{ chainId: `0x${chainId.toString(16)}` }],
+        });
+        const chain = config.chains.find((c) => c.id === chainId);
+        if (!chain) {
+          throw new Error(`Chain ${chainId} not configured for this app`);
+        }
+        return chain;
+      },
+
+      onAccountsChanged(accounts) {
+        config.emitter.emit('change', {
+          accounts: accounts as readonly Address[],
+        });
+      },
+      onChainChanged(chainIdHex) {
+        const chainId = Number.parseInt(chainIdHex, 16);
+        if (Number.isFinite(chainId)) {
+          config.emitter.emit('change', { chainId });
+        }
+      },
+      onDisconnect() {
+        config.emitter.emit('disconnect');
+      },
+    };
+  });
+}