@tangle-network/blueprint-ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/blueprint-ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared blueprint UI components, hooks, and contract utilities for Tangle Network apps",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -43,6 +43,21 @@
       "types": "./dist/preset.d.ts",
       "default": "./dist/preset.js"
     },
+    "./wallet": {
+      "import": "./dist/wallet/index.js",
+      "types": "./dist/wallet/index.d.ts",
+      "default": "./dist/wallet/index.js"
+    },
+    "./iframe": {
+      "import": "./dist/iframe/index.js",
+      "types": "./dist/iframe/index.d.ts",
+      "default": "./dist/iframe/index.js"
+    },
+    "./iframe/testing": {
+      "import": "./dist/iframe/testing-index.js",
+      "types": "./dist/iframe/testing-index.d.ts",
+      "default": "./dist/iframe/testing-index.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "scripts": {

package/src/iframe/TangleIframeProvider.tsx

@@ -0,0 +1,171 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+
+import {
+  TangleIframeClient,
+  type ServiceSnapshot,
+  type TangleIframeClientOptions,
+  type WalletSnapshot,
+} from './tangleIframeClient';
+import {
+  detectTangleCloudParentOrigin,
+  TANGLE_CLOUD_ORIGINS_DEFAULT,
+} from '../wallet/detectParentOrigin';
+
+type Props = {
+  appId: string;
+  /** Override the detected parent origin (e.g. dev/staging deploys). */
+  parentOrigin?: string;
+  /** Extra trusted origins for `detectTangleCloudParentOrigin`. */
+  extraOrigins?: readonly string[];
+  /**
+   * Override the bootstrap behavior. When `'auto'` (default), the SDK
+   * sniffs the embed context: real parent → install the bridge, top-frame
+   * → drop into dev mode. `'bridge'` forces real-parent mode and throws
+   * if no parent is detected. `'dev'` forces dev mode even when embedded
+   * — useful for component-level tests.
+   */
+  mode?: 'auto' | 'bridge' | 'dev';
+  children: ReactNode;
+};
+
+type ContextValue = {
+  readonly client: TangleIframeClient | null;
+  readonly wallet: WalletSnapshot;
+  readonly service: ServiceSnapshot;
+  readonly mode: 'bridge' | 'dev';
+  readonly isReady: boolean;
+};
+
+const TangleIframeContext = createContext<ContextValue | null>(null);
+
+const NULL_WALLET: WalletSnapshot = {
+  address: null,
+  chainId: null,
+  isConnected: false,
+};
+const NULL_SERVICE: ServiceSnapshot = {
+  blueprintId: null,
+  serviceId: null,
+  operators: [],
+  jobs: [],
+  mode: null,
+};
+
+/**
+ * Iframe-blueprint root provider. Wrap your app once at the entry point.
+ *
+ * In `auto` mode (default) the SDK detects whether the app is embedded by a
+ * trusted Tangle Cloud parent. If yes → installs the postMessage bridge.
+ * If no (running standalone at `localhost:5173` etc.) → enters **dev mode**
+ * with an in-memory state machine that the developer can drive via the
+ * exported debug controls. Dev mode keeps the hook surface identical to
+ * production so component code never branches on embed-vs-not.
+ *
+ * Three lifecycle stages:
+ *
+ *   1. Mount — `client` is created, mode is decided.
+ *   2. Bootstrap — handshake (bridge) or first-paint setup (dev). The
+ *      `isReady` flag flips to true.
+ *   3. Active — wallet + service snapshots flow in via subscriptions.
+ */
+export function TangleIframeProvider({
+  appId,
+  parentOrigin: explicitOrigin,
+  extraOrigins,
+  mode: requestedMode = 'auto',
+  children,
+}: Props) {
+  // Resolve the effective mode once at mount. Switching modes mid-session
+  // would tear down the bridge / dev state inconsistently; restart instead.
+  const resolution = useMemo(() => {
+    if (requestedMode === 'dev') {
+      return { mode: 'dev' as const, parentOrigin: null };
+    }
+    const detected =
+      explicitOrigin ?? detectTangleCloudParentOrigin({ extraOrigins });
+    if (requestedMode === 'bridge') {
+      if (!detected) {
+        // eslint-disable-next-line no-console
+        console.error(
+          '[TangleIframeProvider] mode="bridge" but no trusted parent was detected. Falling back to dev mode.',
+        );
+        return { mode: 'dev' as const, parentOrigin: null };
+      }
+      return { mode: 'bridge' as const, parentOrigin: detected };
+    }
+    // auto: bridge when detected, dev otherwise.
+    return detected
+      ? { mode: 'bridge' as const, parentOrigin: detected }
+      : { mode: 'dev' as const, parentOrigin: null };
+  }, [requestedMode, explicitOrigin, extraOrigins]);
+
+  const clientRef = useRef<TangleIframeClient | null>(null);
+  const [wallet, setWallet] = useState<WalletSnapshot>(NULL_WALLET);
+  const [service, setService] = useState<ServiceSnapshot>(NULL_SERVICE);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    if (resolution.mode === 'dev') {
+      // Dev mode: no bridge. The DevHarness component (or a test) seeds
+      // wallet + service via `setDevWallet` / `setDevService` on the
+      // returned context. Mark ready immediately so app code unblocks.
+      setIsReady(true);
+      return undefined;
+    }
+    // Bridge mode
+    const options: TangleIframeClientOptions = {
+      parentOrigin: resolution.parentOrigin,
+      appId,
+    };
+    const client = new TangleIframeClient(options);
+    clientRef.current = client;
+    const unsubWallet = client.subscribe('wallet', setWallet);
+    const unsubService = client.subscribe('service', setService);
+    client.install();
+    setIsReady(true);
+    return () => {
+      unsubWallet();
+      unsubService();
+      client.uninstall();
+      clientRef.current = null;
+      setIsReady(false);
+    };
+  }, [resolution, appId]);
+
+  const value = useMemo<ContextValue>(
+    () => ({
+      client: clientRef.current,
+      wallet,
+      service,
+      mode: resolution.mode,
+      isReady,
+    }),
+    [wallet, service, resolution.mode, isReady],
+  );
+
+  return (
+    <TangleIframeContext.Provider value={value}>
+      {children}
+    </TangleIframeContext.Provider>
+  );
+}
+
+export function useTangleIframeContext(): ContextValue {
+  const ctx = useContext(TangleIframeContext);
+  if (!ctx) {
+    throw new Error(
+      'useTangleIframeContext must be used inside <TangleIframeProvider>.',
+    );
+  }
+  return ctx;
+}
+
+export { TANGLE_CLOUD_ORIGINS_DEFAULT };

package/src/iframe/hooks.ts

@@ -0,0 +1,142 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { Address, Hex } from 'viem';
+
+import { useTangleIframeContext } from './TangleIframeProvider';
+import type {
+  JobInvocation,
+  ServiceSnapshot,
+  WalletSnapshot,
+} from './tangleIframeClient';
+import type { JobInputs } from '../wallet/parentBridgeProtocol';
+
+/**
+ * Read-only view of the connected wallet, plus the operations the iframe
+ * can request the parent to perform.
+ *
+ * The iframe never holds a private key, never sees `window.ethereum`, never
+ * imports wagmi. All wallet work happens upstream in the Tangle Cloud
+ * dapp's wagmi config + ConnectKit modal.
+ */
+export function useTangleWallet(): WalletSnapshot & {
+  signMessage: (message: string) => Promise<Hex>;
+  sendTransaction: (tx: {
+    to: Address;
+    data: Hex;
+    value?: bigint;
+  }) => Promise<Hex>;
+  switchChain: (chainId: number) => Promise<number>;
+} {
+  const { client, wallet } = useTangleIframeContext();
+  const signMessage = useCallback(
+    (message: string) => {
+      if (!client) throw new Error('Wallet not available in dev mode.');
+      return client.signMessage(message);
+    },
+    [client],
+  );
+  const sendTransaction = useCallback(
+    (tx: { to: Address; data: Hex; value?: bigint }) => {
+      if (!client) throw new Error('Wallet not available in dev mode.');
+      return client.sendTransaction(tx);
+    },
+    [client],
+  );
+  const switchChain = useCallback(
+    (chainId: number) => {
+      if (!client) throw new Error('Wallet not available in dev mode.');
+      return client.switchChain(chainId);
+    },
+    [client],
+  );
+  return { ...wallet, signMessage, sendTransaction, switchChain };
+}
+
+/**
+ * The service the iframe is currently rendering for. Broadcast by the
+ * parent dapp on mount + every time the service/mode changes — the iframe
+ * never queries the chain or the indexer itself.
+ *
+ * `serviceId === null` means the operator hasn't deployed an instance yet;
+ * the iframe should render its deploy-ready / configuration surface.
+ */
+export function useTangleService(): ServiceSnapshot {
+  return useTangleIframeContext().service;
+}
+
+/**
+ * Invoke a blueprint job. Returns a callable + a snapshot of the most
+ * recent invocation (or null if none yet).
+ *
+ * Streaming jobs (LLM, video, audio) opt in via `stream: true`. The hook's
+ * `invocation.chunks` accumulates each streaming chunk so the UI can render
+ * progressive output. For one-shot jobs (embeddings, classification), use
+ * the `invocation.data` once `status === 'success'`.
+ *
+ * Multiple in-flight invocations are supported — each `call()` returns its
+ * own correlationId. The hook tracks only the *latest* invocation in its
+ * state; consumers that need all history can subscribe to the client's
+ * `job` event directly.
+ */
+export function useCallJob() {
+  const { client } = useTangleIframeContext();
+  const [invocation, setInvocation] = useState<JobInvocation | null>(null);
+  const [latestId, setLatestId] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!client) return undefined;
+    return client.subscribe('job', (next) => {
+      // Only update if this is the latest invocation, or no latest tracked.
+      setLatestId((prevLatest) => {
+        if (prevLatest === null || prevLatest === next.correlationId) {
+          setInvocation(next);
+          return next.correlationId;
+        }
+        return prevLatest;
+      });
+    });
+  }, [client]);
+
+  const call = useCallback(
+    async (args: { jobIndex: number; inputs: JobInputs; stream?: boolean }) => {
+      if (!client) {
+        throw new Error(
+          'Job invocation not available in dev mode without a configured stub. See `setDevJobHandler` in the testing harness.',
+        );
+      }
+      // Clear prior invocation state when starting a new call.
+      setInvocation(null);
+      const result = await client.callJob(args);
+      setLatestId(result.correlationId);
+      return result;
+    },
+    [client],
+  );
+
+  const reset = useCallback(() => {
+    setInvocation(null);
+    setLatestId(null);
+  }, []);
+
+  return useMemo(
+    () => ({ call, invocation, reset, isPending: invocation?.status === 'pending' || invocation?.status === 'streaming' }),
+    [call, invocation, reset],
+  );
+}
+
+/**
+ * Convenience: returns just the address when connected, or `null`. Most
+ * iframe components only care about the address.
+ */
+export function useTangleAddress(): Address | null {
+  return useTangleIframeContext().wallet.address;
+}
+
+/** Whether the iframe has completed its parent-handshake (or is in dev mode). */
+export function useTangleReady(): boolean {
+  return useTangleIframeContext().isReady;
+}
+
+/** Resolved mode — `'bridge'` (real parent) or `'dev'` (standalone). */
+export function useTangleMode(): 'bridge' | 'dev' {
+  return useTangleIframeContext().mode;
+}

package/src/iframe/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Tangle Cloud iframe SDK — thin renderer for marketplace blueprints.
+ *
+ * Use this when building a blueprint UI that will be embedded by the
+ * Tangle Cloud dapp. The SDK ships wallet + service-context state
+ * subscriptions and a `callJob` helper, all driven by the parent dapp
+ * over postMessage. The iframe never imports wagmi, never holds a wallet,
+ * never touches the chain.
+ *
+ * Quick start:
+ *
+ *   import { TangleIframeProvider, useTangleWallet, useCallJob }
+ *     from '@tangle-network/blueprint-iframe-sdk';
+ *
+ *   <TangleIframeProvider appId="llm-inference">
+ *     <App />
+ *   </TangleIframeProvider>
+ *
+ *   function PromptBar() {
+ *     const { address } = useTangleWallet();
+ *     const { call, invocation } = useCallJob();
+ *     return <button onClick={() => call({ jobIndex: 0, inputs: { prompt: '...' }, stream: true })} />;
+ *   }
+ *
+ * Two execution modes auto-detected:
+ *
+ *   - **bridge** (production): real Tangle Cloud parent. Wallet + service
+ *     state flows in via postMessage. `callJob` is forwarded upstream and
+ *     the parent handles RFQ + signing + submission.
+ *   - **dev** (standalone): no parent detected. Hook surface is identical;
+ *     drive state via the testing harness or a `<TangleParentHarness>`
+ *     wrapped around the provider with `mode="bridge"` + the harness
+ *     origin.
+ *
+ * The mode is decided once at mount and doesn't switch mid-session.
+ */
+
+export {
+  TangleIframeProvider,
+  useTangleIframeContext,
+  TANGLE_CLOUD_ORIGINS_DEFAULT,
+} from './TangleIframeProvider';
+
+export {
+  useTangleWallet,
+  useTangleService,
+  useCallJob,
+  useTangleAddress,
+  useTangleReady,
+  useTangleMode,
+} from './hooks';
+
+export {
+  TangleIframeClient,
+  type ClientEventMap,
+  type JobInvocation,
+  type ServiceSnapshot,
+  type TangleIframeClientOptions,
+  type WalletSnapshot,
+} from './tangleIframeClient';
+
+// Re-export the protocol types so consumers can build their own clients
+// against the same wire format if they want to skip the React layer.
+export type {
+  CallJobRequest,
+  JobInputs,
+  JobResultEvent,
+  JobResultStatus,
+  ServiceContextBroadcast,
+  ServiceContextJob,
+  ServiceContextOperator,
+} from '../wallet/parentBridgeProtocol';

package/src/iframe/tangleIframeClient.test.ts

@@ -0,0 +1,229 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TangleIframeClient } from './tangleIframeClient';
+import { HARNESS_ORIGIN } from './testing';
+
+const PARENT_ORIGIN = HARNESS_ORIGIN;
+
+/**
+ * Drive the client against a fake parent that lives in the same window.
+ * Production flow goes iframe → window.parent (a different window); these
+ * tests collapse the two windows for assertability while keeping the
+ * exact protocol surface.
+ */
+function setupFakeParent() {
+  const captured: object[] = [];
+  const originalParent = window.parent;
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    get: () => ({
+      postMessage: (message: object) => {
+        captured.push(message);
+      },
+    }),
+  });
+  const restore = () => {
+    Object.defineProperty(window, 'parent', {
+      configurable: true,
+      value: originalParent,
+    });
+  };
+  const sendFromParent = (data: object) =>
+    window.dispatchEvent(new MessageEvent('message', { data, origin: PARENT_ORIGIN }));
+  return { captured, sendFromParent, restore };
+}
+
+describe('TangleIframeClient', () => {
+  let fake: ReturnType<typeof setupFakeParent>;
+  let client: TangleIframeClient;
+
+  beforeEach(() => {
+    fake = setupFakeParent();
+    client = new TangleIframeClient({
+      parentOrigin: PARENT_ORIGIN,
+      appId: 'test-app',
+      requestTimeoutMs: 1_000,
+    });
+  });
+
+  afterEach(() => {
+    client.uninstall();
+    fake.restore();
+  });
+
+  it('posts a versioned handshake on install', () => {
+    client.install();
+    expect(fake.captured[0]).toEqual({
+      kind: 'tangle.app.handshake',
+      appId: 'test-app',
+      version: '1',
+    });
+  });
+
+  it('emits a wallet snapshot when the parent broadcasts accountChanged', () => {
+    client.install();
+    const seen: unknown[] = [];
+    client.subscribe('wallet', (snap) => seen.push(snap));
+    fake.sendFromParent({
+      kind: 'tangle.app.accountChanged',
+      account: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
+    });
+    expect(seen).toEqual([
+      {
+        address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
+        chainId: null,
+        isConnected: true,
+      },
+    ]);
+  });
+
+  it('emits a service snapshot when the parent broadcasts serviceContext', () => {
+    client.install();
+    const seen: unknown[] = [];
+    client.subscribe('service', (snap) => seen.push(snap));
+    fake.sendFromParent({
+      kind: 'tangle.app.serviceContext',
+      blueprintId: '12',
+      serviceId: '42',
+      operators: [
+        {
+          address: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+          rpcAddress: 'http://op1:8000',
+          status: 'active',
+        },
+      ],
+      jobs: [{ index: 0, name: 'invoke' }],
+      mode: 'cloud',
+    });
+    expect(seen).toHaveLength(1);
+    const snap = seen[0] as {
+      blueprintId: string;
+      serviceId: string;
+      operators: unknown[];
+      jobs: unknown[];
+    };
+    expect(snap.blueprintId).toBe('12');
+    expect(snap.serviceId).toBe('42');
+    expect(snap.operators).toHaveLength(1);
+    expect(snap.jobs).toHaveLength(1);
+  });
+
+  it('routes callJob requests + resolves on success terminal status', async () => {
+    client.install();
+    fake.sendFromParent({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'test-app',
+      protocolVersion: '1',
+    });
+    const call = client.callJob({
+      jobIndex: 0,
+      inputs: { prompt: 'hi' },
+    });
+    // First captured message is the handshake; the callJob is somewhere after.
+    const outbound = await vi.waitFor(() => {
+      const msg = fake.captured.find(
+        (c) => (c as { kind?: string }).kind === 'tangle.app.callJob',
+      );
+      if (!msg) throw new Error('callJob not posted yet');
+      return msg as { correlationId: string; inputs: Record<string, unknown> };
+    });
+    expect(outbound.inputs).toEqual({ prompt: 'hi' });
+    // Reply with terminal success
+    fake.sendFromParent({
+      kind: 'tangle.app.jobResult',
+      correlationId: outbound.correlationId,
+      status: 'success',
+      data: { text: 'hello world' },
+    });
+    const result = await call;
+    expect(result.status).toBe('success');
+    expect(result.data).toEqual({ text: 'hello world' });
+  });
+
+  it('accumulates streaming chunks in invocation state', async () => {
+    client.install();
+    fake.sendFromParent({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'test-app',
+      protocolVersion: '1',
+    });
+    const jobEvents: unknown[] = [];
+    client.subscribe('job', (inv) => jobEvents.push(inv));
+    const call = client.callJob({
+      jobIndex: 0,
+      inputs: { prompt: 'stream' },
+      stream: true,
+    });
+    const outbound = await vi.waitFor(() => {
+      const msg = fake.captured.find(
+        (c) => (c as { kind?: string }).kind === 'tangle.app.callJob',
+      );
+      if (!msg) throw new Error('callJob not posted yet');
+      return msg as { correlationId: string };
+    });
+    // Stream chunks then terminal
+    fake.sendFromParent({
+      kind: 'tangle.app.jobResult',
+      correlationId: outbound.correlationId,
+      status: 'streaming',
+      chunk: 'hel',
+    });
+    fake.sendFromParent({
+      kind: 'tangle.app.jobResult',
+      correlationId: outbound.correlationId,
+      status: 'streaming',
+      chunk: 'lo',
+    });
+    fake.sendFromParent({
+      kind: 'tangle.app.jobResult',
+      correlationId: outbound.correlationId,
+      status: 'success',
+      data: { text: 'hello' },
+    });
+    const result = await call;
+    expect(result.chunks).toEqual(['hel', 'lo']);
+    expect(result.data).toEqual({ text: 'hello' });
+    // Job events: initial pending + 2 streaming + final success = 4
+    expect(jobEvents).toHaveLength(4);
+  });
+
+  it('rejects callJob on parent error', async () => {
+    client.install();
+    fake.sendFromParent({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'test-app',
+      protocolVersion: '1',
+    });
+    const call = client.callJob({ jobIndex: 0, inputs: {} });
+    const outbound = await vi.waitFor(() => {
+      const msg = fake.captured.find(
+        (c) => (c as { kind?: string }).kind === 'tangle.app.callJob',
+      );
+      if (!msg) throw new Error('callJob not posted yet');
+      return msg as { correlationId: string };
+    });
+    fake.sendFromParent({
+      kind: 'tangle.app.jobResult',
+      correlationId: outbound.correlationId,
+      status: 'error',
+      error: 'operator-unavailable',
+    });
+    await expect(call).rejects.toThrow('operator-unavailable');
+  });
+
+  it('ignores parent messages from untrusted origins', () => {
+    client.install();
+    const seen: unknown[] = [];
+    client.subscribe('wallet', (snap) => seen.push(snap));
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: {
+          kind: 'tangle.app.accountChanged',
+          account: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+        },
+        origin: 'https://evil.example.com',
+      }),
+    );
+    expect(seen).toEqual([]);
+  });
+});