@tangle-network/blueprint-ui 0.1.0 → 0.1.2

package/src/hooks/useWalletEthBalance.ts

@@ -0,0 +1,68 @@
+import { useEffect, useState } from 'react';
+
+const WEI_PER_ETH = 1_000_000_000_000_000_000n;
+const DISPLAY_SCALE = 1_000n; // 3 decimal places
+
+function formatEthBalance(wei: bigint): string {
+  const whole = wei / WEI_PER_ETH;
+  const fraction = ((wei % WEI_PER_ETH) * DISPLAY_SCALE) / WEI_PER_ETH;
+  return `${whole.toString()}.${fraction.toString().padStart(3, '0')}`;
+}
+
+interface UseWalletEthBalanceOptions {
+  address?: string;
+  refreshKey?: number | string;
+  readBalance: (address: string) => Promise<bigint>;
+  pollMs?: number;
+  onError?: (error: unknown) => void;
+}
+
+interface UseWalletEthBalanceResult {
+  balance: string | null;
+  hasError: boolean;
+}
+
+export function useWalletEthBalance({
+  address,
+  refreshKey,
+  readBalance,
+  pollMs = 15_000,
+  onError,
+}: UseWalletEthBalanceOptions): UseWalletEthBalanceResult {
+  const [balance, setBalance] = useState<string | null>(null);
+  const [hasError, setHasError] = useState(false);
+
+  useEffect(() => {
+    if (!address) {
+      setBalance(null);
+      setHasError(false);
+      return;
+    }
+
+    let cancelled = false;
+
+    const fetchBalance = () => {
+      readBalance(address)
+        .then((wei) => {
+          if (cancelled) return;
+          setBalance(formatEthBalance(wei));
+          setHasError(false);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          setHasError(true);
+          onError?.(error);
+        });
+    };
+
+    fetchBalance();
+    const interval = setInterval(fetchBalance, pollMs);
+
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [address, refreshKey, readBalance, pollMs, onError]);
+
+  return { balance, hasError };
+}

package/src/host/components/BlueprintHostHero.tsx

@@ -0,0 +1,91 @@
+import * as React from 'react';
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '../../components/ui/card';
+import { Badge } from '../../components/ui/badge';
+import { Button } from '../../components/ui/button';
+import { cn } from '../../utils';
+
+type Action = {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+  variant?: React.ComponentProps<typeof Button>['variant'];
+  disabled?: boolean;
+};
+
+export type BlueprintHostHeroProps = {
+  title: string;
+  tagline?: string;
+  description?: string;
+  badges?: string[];
+  actions?: Action[];
+  children?: React.ReactNode;
+  className?: string;
+};
+
+export function BlueprintHostHero({
+  title,
+  tagline,
+  description,
+  badges = [],
+  actions = [],
+  children,
+  className,
+}: BlueprintHostHeroProps) {
+  return (
+    <Card className={cn('rounded-3xl border-bp-elements-borderColor/70 bg-bp-elements-background-depth-2', className)}>
+      <CardHeader className="space-y-4">
+        {badges.length > 0 ? (
+          <div className="flex flex-wrap gap-2">
+            {badges.map((badge) => (
+              <Badge key={badge} variant="secondary">
+                {badge}
+              </Badge>
+            ))}
+          </div>
+        ) : null}
+        <div className="space-y-2">
+          <CardTitle className="text-3xl">{title}</CardTitle>
+          {tagline ? (
+            <CardDescription className="text-base text-bp-elements-textPrimary/80">
+              {tagline}
+            </CardDescription>
+          ) : null}
+        </div>
+        {description ? (
+          <p className="max-w-3xl text-sm leading-6 text-bp-elements-textSecondary">
+            {description}
+          </p>
+        ) : null}
+      </CardHeader>
+      {(actions.length > 0 || children) && (
+        <CardContent className="space-y-4">
+          {actions.length > 0 ? (
+            <div className="flex flex-wrap gap-3">
+              {actions.map((action) => {
+                const button = (
+                  <Button
+                    key={action.label}
+                    variant={action.variant ?? 'default'}
+                    onClick={action.onClick}
+                    disabled={action.disabled}
+                  >
+                    {action.label}
+                  </Button>
+                );
+
+                return action.href ? (
+                  <a key={action.label} href={action.href}>
+                    {button}
+                  </a>
+                ) : (
+                  button
+                );
+              })}
+            </div>
+          ) : null}
+          {children}
+        </CardContent>
+      )}
+    </Card>
+  );
+}

package/src/host/components/BlueprintHostPanel.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from '../../components/ui/card';
+import { cn } from '../../utils';
+
+export type BlueprintHostPanelProps = {
+  title: string;
+  children: React.ReactNode;
+  className?: string;
+};
+
+export function BlueprintHostPanel({
+  title,
+  children,
+  className,
+}: BlueprintHostPanelProps) {
+  return (
+    <Card className={cn('rounded-3xl border-bp-elements-borderColor/70 bg-bp-elements-background-depth-2', className)}>
+      <CardHeader>
+        <CardTitle className="text-xl">{title}</CardTitle>
+      </CardHeader>
+      <CardContent>{children}</CardContent>
+    </Card>
+  );
+}

package/src/host/index.ts

@@ -0,0 +1,42 @@
+export type {
+  BlueprintAppVisibility,
+  BlueprintPublisherVerification,
+  BlueprintExperienceTier,
+  BlueprintSlugPolicy,
+  BlueprintUiSurface,
+  BlueprintResourceRoute,
+  BlueprintPermissionScope,
+  BlueprintExternalAppMode,
+  BlueprintExternalAppTrust,
+  BlueprintPublisher,
+  BlueprintResourceModel,
+  BlueprintPermissionDescriptor,
+  BlueprintExternalAppConfig,
+  BlueprintUiManifest,
+  BlueprintAppModuleBinding,
+  BlueprintAppEntry,
+  BlueprintAppResolvedView,
+} from './types';
+
+export {
+  buildCanonicalBlueprintSlug,
+  resolveBlueprintAppView,
+  toBlueprintAppEntry,
+  getBlueprintExperienceTierLabel,
+  getBlueprintSlugPolicyLabel,
+  getBlueprintSurfaceLabel,
+  getBlueprintPublisherVerificationLabel,
+  getExternalAppTrustLabel,
+  isVerifiedBlueprintPublisher,
+  canPublisherClaimSlug,
+  isTrustedExternalAppHost,
+  getBlueprintPath,
+  getBlueprintServicePath,
+  sanitizeBlueprintSlugPart,
+  deriveBlueprintRequestedSlug,
+} from './resolver';
+
+export type { BlueprintHostHeroProps } from './components/BlueprintHostHero';
+export { BlueprintHostHero } from './components/BlueprintHostHero';
+export type { BlueprintHostPanelProps } from './components/BlueprintHostPanel';
+export { BlueprintHostPanel } from './components/BlueprintHostPanel';

package/src/host/resolver.ts

@@ -0,0 +1,204 @@
+import type {
+  BlueprintAppEntry,
+  BlueprintAppResolvedView,
+  BlueprintExperienceTier,
+  BlueprintExternalAppTrust,
+  BlueprintPublisher,
+  BlueprintPublisherVerification,
+  BlueprintSlugPolicy,
+  BlueprintUiSurface,
+} from './types';
+
+const EXPERIENCE_TIER_LABELS: Record<BlueprintExperienceTier, string> = {
+  generic: 'Protocol fallback',
+  declarative: 'Declarative blueprint UI',
+  'curated-module': 'Curated app module',
+  'external-app': 'External app handoff',
+};
+
+const SLUG_POLICY_LABELS: Record<BlueprintSlugPolicy, string> = {
+  reserved: 'Reserved slug',
+  'publisher-scoped': 'Publisher-scoped slug',
+  'public-requested': 'Public requested slug',
+};
+
+const SURFACE_LABELS: Record<BlueprintUiSurface, string> = {
+  'generic-overview': 'Generic overview',
+  'service-explorer': 'Service explorer',
+  'service-console': 'Service console',
+  'actions-panel': 'Actions panel',
+  resources: 'Resources',
+  chat: 'Chat',
+  vaults: 'Vaults',
+  metrics: 'Metrics',
+  permissions: 'Permissions',
+};
+
+const PUBLISHER_VERIFICATION_LABELS: Record<
+  BlueprintPublisherVerification,
+  string
+> = {
+  'first-party': 'First-party publisher',
+  verified: 'Verified publisher',
+  unverified: 'Unverified publisher',
+};
+
+const EXTERNAL_APP_TRUST_LABELS: Record<BlueprintExternalAppTrust, string> = {
+  trusted: 'Trusted external app',
+  restricted: 'Restricted external app',
+};
+
+export function buildCanonicalBlueprintSlug(entry: BlueprintAppEntry): string {
+  if (entry.canonicalSlug) {
+    return entry.canonicalSlug;
+  }
+
+  if (entry.slugPolicy === 'reserved' || !entry.publisher.namespace) {
+    return entry.slug;
+  }
+
+  return `@${entry.publisher.namespace}/${entry.slug}`;
+}
+
+export function resolveBlueprintAppView(
+  entry: BlueprintAppEntry,
+): BlueprintAppResolvedView {
+  return {
+    slug: entry.slug,
+    canonicalSlug: buildCanonicalBlueprintSlug(entry),
+    blueprintId: entry.blueprintId,
+    publisher: entry.publisher,
+    tier: entry.tier,
+    slugPolicy: entry.slugPolicy,
+    manifest: entry.manifest,
+    module: entry.module,
+    fallbackEnabled: true,
+  };
+}
+
+export function toBlueprintAppEntry(
+  view: BlueprintAppResolvedView,
+): BlueprintAppEntry {
+  return {
+    slug: view.slug,
+    canonicalSlug: view.canonicalSlug,
+    blueprintId: view.blueprintId,
+    publisher: view.publisher,
+    tier: view.tier,
+    slugPolicy: view.slugPolicy,
+    manifest: view.manifest,
+    module: view.module,
+  };
+}
+
+export function getBlueprintExperienceTierLabel(
+  tier: BlueprintExperienceTier,
+): string {
+  return EXPERIENCE_TIER_LABELS[tier];
+}
+
+export function getBlueprintSlugPolicyLabel(policy: BlueprintSlugPolicy): string {
+  return SLUG_POLICY_LABELS[policy];
+}
+
+export function getBlueprintSurfaceLabel(surface: BlueprintUiSurface): string {
+  return SURFACE_LABELS[surface];
+}
+
+export function getBlueprintPublisherVerificationLabel(
+  verification: BlueprintPublisherVerification,
+): string {
+  return PUBLISHER_VERIFICATION_LABELS[verification];
+}
+
+export function getExternalAppTrustLabel(
+  trust: BlueprintExternalAppTrust,
+): string {
+  return EXTERNAL_APP_TRUST_LABELS[trust];
+}
+
+export function isVerifiedBlueprintPublisher(
+  publisher: BlueprintPublisher,
+): boolean {
+  return (
+    publisher.verification === 'first-party' ||
+    publisher.verification === 'verified'
+  );
+}
+
+export function canPublisherClaimSlug(
+  slug: string,
+  publisher?: Pick<BlueprintPublisher, 'namespace' | 'verification'>,
+  reservedSlugs: Set<string> = new Set(),
+): boolean {
+  if (reservedSlugs.has(slug)) {
+    return false;
+  }
+
+  return (
+    publisher?.namespace !== undefined &&
+    publisher.namespace.trim().length > 0 &&
+    (publisher.verification === 'verified' ||
+      publisher.verification === 'first-party')
+  );
+}
+
+export function isTrustedExternalAppHost(
+  host: string,
+  trustedHosts: readonly string[] = [],
+): boolean {
+  const normalizedHost = host.trim().toLowerCase();
+
+  return trustedHosts.some(
+    (trustedHost) =>
+      normalizedHost === trustedHost || normalizedHost.endsWith(`.${trustedHost}`),
+  );
+}
+
+export function getBlueprintPath(view: BlueprintAppResolvedView): string {
+  if (view.tier === 'curated-module' || view.tier === 'external-app') {
+    return `/blueprints/${view.canonicalSlug}`;
+  }
+
+  if (view.blueprintId !== undefined) {
+    return `/blueprints/${view.blueprintId.toString()}`;
+  }
+
+  return `/blueprints/${view.slug}`;
+}
+
+export function getBlueprintServicePath(
+  view: BlueprintAppResolvedView,
+  serviceId: string,
+): string {
+  if (view.tier === 'curated-module' || view.tier === 'external-app') {
+    return `${getBlueprintPath(view)}/${serviceId}`;
+  }
+
+  return `${getBlueprintPath(view)}/services/${serviceId}`;
+}
+
+export function sanitizeBlueprintSlugPart(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
+export function deriveBlueprintRequestedSlug(
+  blueprint: Pick<{ name: string; author: string; id: bigint }, 'name' | 'author' | 'id'>,
+): string {
+  const fromName = sanitizeBlueprintSlugPart(blueprint.name);
+  if (fromName.length > 0) {
+    return fromName;
+  }
+
+  const fromAuthor = sanitizeBlueprintSlugPart(blueprint.author);
+  if (fromAuthor.length > 0) {
+    return `${fromAuthor}-${blueprint.id.toString()}`;
+  }
+
+  return `blueprint-${blueprint.id.toString()}`;
+}

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

@@ -6,7 +6,7 @@
 // ── Utils ──
 export { cn } from './utils';
 export { resolveOperatorRpc } from './utils/resolveOperatorRpc';
-export { createTangleTransports, defaultConnectKitOptions, tangleWalletChains } from './utils/web3';
+export { createTangleTransports, defaultConnectKitOptions, getTangleWalletChains, tangleWalletChains } from './utils/web3';
 export { bpThemeTokens } from './preset';
 
 // ── Stores ──
@@ -25,6 +25,7 @@ export { tangleJobsAbi, tangleServicesAbi, tangleOperatorsAbi } from './contract
 export type { CoreAddresses, NetworkConfig } from './contracts/chains';
 export {
   resolveRpcUrl,
+  createTangleLocalChain,
   rpcUrl,
   tangleLocal,
   tangleTestnet,
@@ -36,6 +37,7 @@ export {
 } from './contracts/chains';
 export {
   selectedChainIdStore,
+  sanitizeSelectedChainId,
   publicClientStore,
   getPublicClient,
   publicClient,
@@ -59,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';
@@ -77,3 +119,7 @@ export { useSessionAuth } from './hooks/useSessionAuth';
 export type { ProvisionPhase, ProvisionStatus } from './hooks/useProvisionProgress';
 export { getPhaseLabel, isTerminalPhase, useProvisionProgress } from './hooks/useProvisionProgress';
 export { useThemeValue } from './hooks/useThemeValue';
+export type { UseSidecarAuthOptions, SidecarAuth } from './hooks/useSidecarAuth';
+export { useSidecarAuth } from './hooks/useSidecarAuth';
+export { useWagmiSidecarAuth } from './hooks/useWagmiSidecarAuth';
+export { useWalletEthBalance } from './hooks/useWalletEthBalance';

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;