@swarmclawai/swarmclaw 0.7.7 → 0.8.0

package/src/components/wallets/wallet-section.tsx

@@ -1,29 +1,71 @@
 'use client'
 
-import { useState, useCallback } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
 import { api } from '@/lib/api-client'
 import { copyTextToClipboard } from '@/lib/clipboard'
-import type { AgentWallet, WalletChain } from '@/types'
+import type { AgentWallet, WalletAssetBalance, WalletPortfolioSummary, WalletChain } from '@/types'
 import { toast } from 'sonner'
+import {
+  SUPPORTED_WALLET_CHAINS,
+  formatWalletAmount,
+  getWalletBalanceAtomic,
+  getWalletChainMeta,
+  getWalletLimitAtomic,
+} from '@/lib/wallet'
+
+type SafeWallet = Omit<AgentWallet, 'encryptedPrivateKey'> & {
+  balanceAtomic?: string
+  balanceLamports?: number
+  balanceFormatted?: string
+  balanceSymbol?: string
+  assets?: WalletAssetBalance[]
+  portfolioSummary?: WalletPortfolioSummary
+  isActive?: boolean
+}
 
 interface WalletSectionProps {
   agentId: string
-  wallet: (Omit<AgentWallet, 'encryptedPrivateKey'> & { balanceLamports?: number; balanceSol?: number }) | null
+  wallets: SafeWallet[]
+  activeWalletId: string | null
   onWalletCreated: () => void
 }
 
-export function WalletSection({ agentId, wallet, onWalletCreated }: WalletSectionProps) {
+export function WalletSection({ agentId, wallets, activeWalletId, onWalletCreated }: WalletSectionProps) {
   const [creating, setCreating] = useState(false)
+  const [activatingWalletId, setActivatingWalletId] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
-  const [copied, setCopied] = useState(false)
+  const [copiedWalletId, setCopiedWalletId] = useState<string | null>(null)
+
+  const connectedChains = useMemo(() => new Set(wallets.map((wallet) => wallet.chain)), [wallets])
+  const availableChains = useMemo(
+    () => SUPPORTED_WALLET_CHAINS.filter((chain) => !connectedChains.has(chain)),
+    [connectedChains],
+  )
+  const sortedWallets = useMemo(
+    () => [...wallets].sort((a, b) => {
+      const aActive = a.id === activeWalletId || a.isActive === true
+      const bActive = b.id === activeWalletId || b.isActive === true
+      if (aActive !== bActive) return aActive ? -1 : 1
+      return a.chain.localeCompare(b.chain)
+    }),
+    [activeWalletId, wallets],
+  )
+
+  const [chain, setChain] = useState<WalletChain>(availableChains[0] || 'solana')
+
+  useEffect(() => {
+    if (availableChains.length === 0) return
+    if (!availableChains.includes(chain)) setChain(availableChains[0])
+  }, [availableChains, chain])
 
   const createWallet = useCallback(async () => {
+    if (!availableChains.includes(chain)) return
     setCreating(true)
     setError(null)
     try {
-      await api('POST', '/wallets', { agentId, chain: 'solana' as WalletChain })
+      await api('POST', '/wallets', { agentId, chain })
       toast.success('Agent wallet created successfully')
-      onWalletCreated()
+      await onWalletCreated()
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : String(err)
       setError(msg)
@@ -31,32 +73,165 @@ export function WalletSection({ agentId, wallet, onWalletCreated }: WalletSectio
     } finally {
       setCreating(false)
     }
-  }, [agentId, onWalletCreated])
+  }, [agentId, availableChains, chain, onWalletCreated])
 
-  const copyAddress = useCallback(async () => {
-    if (!wallet) return
+  const copyAddress = useCallback(async (wallet: SafeWallet) => {
     const copiedValue = await copyTextToClipboard(wallet.publicKey)
     if (!copiedValue) return
-    setCopied(true)
-    setTimeout(() => setCopied(false), 2000)
-  }, [wallet])
+    setCopiedWalletId(wallet.id)
+    setTimeout(() => {
+      setCopiedWalletId((current) => current === wallet.id ? null : current)
+    }, 2000)
+  }, [])
+
+  const setActiveWallet = useCallback(async (walletId: string) => {
+    setActivatingWalletId(walletId)
+    setError(null)
+    try {
+      await api('PATCH', `/wallets/${walletId}`, { makeActive: true })
+      toast.success('Default wallet updated')
+      await onWalletCreated()
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err)
+      setError(msg)
+      toast.error(msg)
+    } finally {
+      setActivatingWalletId(null)
+    }
+  }, [onWalletCreated])
 
   return (
     <div className="mb-8">
       <div className="flex items-center gap-2 mb-3">
         <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em]">
-          Wallet
+          Wallets
         </label>
         <span className="px-1.5 py-0.5 rounded-[4px] bg-amber-500/15 text-amber-400 text-[9px] font-600 uppercase tracking-wide">
           Experimental
         </span>
       </div>
 
-      {!wallet ? (
-        <div className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50">
+      {sortedWallets.length > 0 ? (
+        <div className="space-y-3">
+          <div className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50">
+            <div className="flex items-center justify-between gap-3 mb-2">
+              <div>
+                <div className="text-[12px] font-600 text-text-1">Combined Wallet Summary</div>
+                <p className="text-[11px] text-text-3/70 mt-1">
+                  {sortedWallets.length} wallet{sortedWallets.length === 1 ? '' : 's'} connected. The active wallet is used by default when the agent does not specify a chain explicitly.
+                </p>
+              </div>
+              <div className="text-right">
+                <div className="text-[18px] font-600 text-text-1">{sortedWallets.length}</div>
+                <div className="text-[10px] uppercase tracking-wide text-text-3/50">Connected</div>
+              </div>
+            </div>
+            <div className="grid gap-2 md:grid-cols-2">
+              {sortedWallets.map((wallet) => {
+                const walletMeta = getWalletChainMeta(wallet.chain)
+                const balanceFormatted = wallet.balanceFormatted || formatWalletAmount(wallet.chain, getWalletBalanceAtomic(wallet), { minFractionDigits: 4, maxFractionDigits: 6 })
+                const isActive = wallet.id === activeWalletId || wallet.isActive === true
+                return (
+                  <div key={wallet.id} className="rounded-[10px] border border-white/[0.06] bg-black/10 px-3 py-2">
+                    <div className="flex items-center gap-2">
+                      <span className="text-[10px] text-text-3/60 uppercase tracking-wide font-600">{walletMeta.label}</span>
+                      {isActive && (
+                        <span className="px-1.5 py-0.5 rounded-[999px] bg-accent-soft text-accent-bright text-[9px] font-600 uppercase tracking-wide">
+                          Active
+                        </span>
+                      )}
+                    </div>
+                    <div className="mt-1 text-[14px] font-600 text-text-1">{balanceFormatted} {walletMeta.symbol}</div>
+                    {wallet.portfolioSummary?.nonZeroAssets ? (
+                      <div className="mt-1 text-[10px] text-text-3/55">
+                        {wallet.portfolioSummary.nonZeroAssets} asset{wallet.portfolioSummary.nonZeroAssets === 1 ? '' : 's'} tracked
+                      </div>
+                    ) : null}
+                    <div className="mt-1 text-[10px] text-text-3/55 font-mono truncate">{wallet.publicKey}</div>
+                  </div>
+                )
+              })}
+            </div>
+          </div>
+
+          {sortedWallets.map((wallet) => {
+            const walletMeta = getWalletChainMeta(wallet.chain)
+            const balanceFormatted = wallet.balanceFormatted || formatWalletAmount(wallet.chain, getWalletBalanceAtomic(wallet), { minFractionDigits: 4, maxFractionDigits: 6 })
+            const perTxLimit = formatWalletAmount(wallet.chain, getWalletLimitAtomic(wallet, 'perTx'), { maxFractionDigits: 6 })
+            const dailyLimit = formatWalletAmount(wallet.chain, getWalletLimitAtomic(wallet, 'daily'), { maxFractionDigits: 6 })
+            const isActive = wallet.id === activeWalletId || wallet.isActive === true
+            return (
+              <div key={wallet.id} className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50 space-y-3">
+                <div className="flex items-center gap-2">
+                  <span className="text-[10px] text-text-3/60 uppercase tracking-wide font-600">
+                    {walletMeta.label}
+                  </span>
+                  {isActive && (
+                    <span className="px-1.5 py-0.5 rounded-[999px] bg-accent-soft text-accent-bright text-[9px] font-600 uppercase tracking-wide">
+                      Default
+                    </span>
+                  )}
+                  <span className="flex-1" />
+                  <span className="text-[13px] font-600 text-text-1">
+                    {balanceFormatted} {walletMeta.symbol}
+                  </span>
+                </div>
+                <div className="flex items-center gap-2">
+                  <code className="text-[11px] text-text-3 bg-black/20 px-2 py-1 rounded-[6px] font-mono truncate flex-1">
+                    {wallet.publicKey}
+                  </code>
+                  <button
+                    type="button"
+                    onClick={() => copyAddress(wallet)}
+                    className="shrink-0 px-2 py-1 rounded-[6px] text-[10px] text-text-3 hover:text-text-2 border border-white/[0.08] bg-surface transition-colors cursor-pointer"
+                    style={{ fontFamily: 'inherit' }}
+                  >
+                    {copiedWalletId === wallet.id ? 'Copied!' : 'Copy'}
+                  </button>
+                  {!isActive && (
+                    <button
+                      type="button"
+                      onClick={() => setActiveWallet(wallet.id)}
+                      disabled={activatingWalletId === wallet.id}
+                      className="shrink-0 px-2 py-1 rounded-[6px] text-[10px] font-600 text-accent-bright border border-accent-bright/20 bg-accent-soft/10 hover:bg-accent-soft/20 transition-colors cursor-pointer disabled:opacity-50"
+                      style={{ fontFamily: 'inherit' }}
+                    >
+                      {activatingWalletId === wallet.id ? 'Setting...' : 'Set Default'}
+                    </button>
+                  )}
+                </div>
+                <div className="flex flex-wrap items-center gap-3 text-[10px] text-text-3/60">
+                  <span>Limit: {perTxLimit} {walletMeta.symbol}/tx</span>
+                  <span>Daily: {dailyLimit} {walletMeta.symbol}</span>
+                  <span>{wallet.requireApproval ? 'Approval required' : 'Auto-send'}</span>
+                  {wallet.portfolioSummary?.nonZeroAssets ? (
+                    <span>{wallet.portfolioSummary.nonZeroAssets} asset{wallet.portfolioSummary.nonZeroAssets === 1 ? '' : 's'} detected</span>
+                  ) : null}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      ) : null}
+
+      {availableChains.length > 0 ? (
+        <div className="mt-3 p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50">
           <p className="text-[12px] text-text-3/70 mb-3">
-            Create a Solana wallet for this agent to hold funds, pay for services, and trade autonomously.
+            {getWalletChainMeta(chain).createDescription}
           </p>
+          <label className="block text-[11px] text-text-3/70 mb-1">Wallet Type</label>
+          <select
+            value={chain}
+            onChange={(event) => setChain(event.target.value as WalletChain)}
+            className="w-full mb-3 px-3 py-2 rounded-[8px] border border-white/[0.08] bg-surface text-[12px] text-text-1 outline-none focus:border-accent/40"
+            style={{ fontFamily: 'inherit' }}
+          >
+            {availableChains.map((availableChain) => (
+              <option key={availableChain} value={availableChain}>
+                {getWalletChainMeta(availableChain).label}
+              </option>
+            ))}
+          </select>
           <button
             type="button"
             onClick={createWallet}
@@ -64,41 +239,16 @@ export function WalletSection({ agentId, wallet, onWalletCreated }: WalletSectio
             className="px-3 py-1.5 rounded-[8px] bg-accent-soft text-accent-bright text-[11px] font-600 hover:bg-accent-bright/15 transition-all cursor-pointer disabled:opacity-50 border border-accent-bright/20"
             style={{ fontFamily: 'inherit' }}
           >
-            {creating ? 'Creating...' : 'Create Wallet'}
+            {creating ? 'Creating...' : `Create ${getWalletChainMeta(chain).label} Wallet`}
           </button>
           {error && <p className="text-[11px] text-red-400 mt-2">{error}</p>}
         </div>
       ) : (
-        <div className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50 space-y-3">
-          <div className="flex items-center gap-2">
-            <span className="text-[10px] text-text-3/60 uppercase tracking-wide font-600">
-              {wallet.chain}
-            </span>
-            <span className="flex-1" />
-            {typeof wallet.balanceSol === 'number' && (
-              <span className="text-[13px] font-600 text-text-1">
-                {wallet.balanceSol.toFixed(4)} SOL
-              </span>
-            )}
-          </div>
-          <div className="flex items-center gap-2">
-            <code className="text-[11px] text-text-3 bg-black/20 px-2 py-1 rounded-[6px] font-mono truncate flex-1">
-              {wallet.publicKey}
-            </code>
-            <button
-              type="button"
-              onClick={copyAddress}
-              className="shrink-0 px-2 py-1 rounded-[6px] text-[10px] text-text-3 hover:text-text-2 border border-white/[0.08] bg-surface transition-colors cursor-pointer"
-              style={{ fontFamily: 'inherit' }}
-            >
-              {copied ? 'Copied!' : 'Copy'}
-            </button>
-          </div>
-          <div className="flex items-center gap-3 text-[10px] text-text-3/60">
-            <span>Limit: {((wallet.spendingLimitLamports ?? 100_000_000) / 1e9).toFixed(2)} SOL/tx</span>
-            <span>Daily: {((wallet.dailyLimitLamports ?? 1_000_000_000) / 1e9).toFixed(1)} SOL</span>
-            <span>{wallet.requireApproval ? 'Approval required' : 'Auto-send'}</span>
-          </div>
+        <div className="mt-3 p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50">
+          <p className="text-[12px] text-text-3/70">
+            This agent already has both supported wallet types connected. Use the default toggle above to choose which wallet autonomous actions use when no chain is specified.
+          </p>
+          {error && <p className="text-[11px] text-red-400 mt-2">{error}</p>}
         </div>
       )}
     </div>

package/src/components/webhooks/webhook-sheet.tsx

@@ -3,6 +3,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
 import { BottomSheet } from '@/components/shared/bottom-sheet'
+import { ConfirmDialog } from '@/components/shared/confirm-dialog'
 import { api } from '@/lib/api-client'
 import { copyTextToClipboard } from '@/lib/clipboard'
 import type { Webhook, WebhookLogEntry } from '@/types'
@@ -61,6 +62,8 @@ export function WebhookSheet() {
   const [tab, setTab] = useState<'config' | 'history'>('config')
   const [history, setHistory] = useState<WebhookLogEntry[]>([])
   const [historyLoading, setHistoryLoading] = useState(false)
+  const [confirmDelete, setConfirmDelete] = useState(false)
+  const [deleting, setDeleting] = useState(false)
 
   const editing = editingId ? (webhooks[editingId] as Webhook | undefined) : null
   const endpoint = editing ? webhookUrl(editing.id) : ''
@@ -109,6 +112,8 @@ export function WebhookSheet() {
   }, [editing, open])
 
   const handleClose = () => {
+    setConfirmDelete(false)
+    setDeleting(false)
     setOpen(false)
     setEditingId(null)
   }
@@ -164,17 +169,21 @@ export function WebhookSheet() {
   }
 
   const handleDelete = async () => {
-    if (!editing || !confirm('Delete this webhook?')) return
+    if (!editing) return
+    setDeleting(true)
     try {
       const res = await api<DeleteWebhookResponse>('DELETE', `/webhooks/${editing.id}`)
       if ('error' in res && res.error) throw new Error(res.error)
       toast.success('Webhook deleted')
       await loadWebhooks()
+      setConfirmDelete(false)
       handleClose()
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : 'Failed to delete webhook'
       setError(msg)
       toast.error(msg)
+    } finally {
+      setDeleting(false)
     }
   }
 
@@ -381,7 +390,7 @@ export function WebhookSheet() {
         <div className="flex gap-3 pt-2">
           {editing && (
             <button
-              onClick={handleDelete}
+              onClick={() => setConfirmDelete(true)}
               className="px-5 py-3 rounded-[14px] border border-danger/30 bg-transparent text-danger text-[14px] font-600 cursor-pointer hover:bg-danger/10 transition-colors"
               style={{ fontFamily: 'inherit' }}
             >
@@ -407,6 +416,17 @@ export function WebhookSheet() {
         </div>
         </>}
       </div>
+      <ConfirmDialog
+        open={confirmDelete}
+        title="Delete Webhook?"
+        message={editing ? `Delete "${editing.name}"? This will remove the endpoint and its saved webhook configuration.` : 'Delete this webhook?'}
+        confirmLabel={deleting ? 'Deleting...' : 'Delete'}
+        confirmDisabled={deleting}
+        cancelDisabled={deleting}
+        danger
+        onConfirm={() => { void handleDelete() }}
+        onCancel={() => { if (!deleting) setConfirmDelete(false) }}
+      />
     </BottomSheet>
   )
 }

package/src/lib/approval-display.ts

@@ -36,6 +36,14 @@ export function getApprovalTitle(approval: ApprovalRequest): string {
     const pluginId = getApprovalPluginId(approval)
     return pluginId ? `Enable Plugin: ${pluginId}` : 'Enable Plugin'
   }
+  if (approval.category === 'connector_sender') {
+    const data = dataObject(approval)
+    const senderName = typeof data.senderName === 'string' ? data.senderName.trim() : ''
+    const senderId = typeof data.senderId === 'string' ? data.senderId.trim() : ''
+    const connectorName = typeof data.connectorName === 'string' ? data.connectorName.trim() : ''
+    const subject = senderName || senderId || 'Unknown sender'
+    return connectorName ? `Approve ${subject} on ${connectorName}` : `Approve ${subject}`
+  }
   return approval.title || 'Approval Request'
 }
 
@@ -58,5 +66,17 @@ export function getApprovalPayload(approval: ApprovalRequest): Record<string, un
     }
   }
 
+  if (approval.category === 'connector_sender') {
+    return {
+      connectorId: typeof data.connectorId === 'string' ? data.connectorId : null,
+      connectorName: typeof data.connectorName === 'string' ? data.connectorName : null,
+      platform: typeof data.platform === 'string' ? data.platform : null,
+      senderId: typeof data.senderId === 'string' ? data.senderId : null,
+      senderName: typeof data.senderName === 'string' ? data.senderName : null,
+      channelId: typeof data.channelId === 'string' ? data.channelId : null,
+      policy: typeof data.policy === 'string' ? data.policy : null,
+    }
+  }
+
   return (sanitizeValue(data) || {}) as Record<string, unknown>
 }

package/src/lib/canvas-content.ts

@@ -0,0 +1,198 @@
+import type {
+  CanvasActionItem,
+  CanvasBlock,
+  CanvasCardItem,
+  CanvasContent,
+  CanvasDocument,
+  CanvasMetricItem,
+  CanvasTableData,
+} from '@/types'
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+function asTrimmedString(value: unknown, max = 8000): string | null {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value).slice(0, max)
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed ? trimmed.slice(0, max) : null
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value
+    .map((entry) => asTrimmedString(entry, 240))
+    .filter((entry): entry is string => Boolean(entry))
+}
+
+function normalizeMetricItems(value: unknown): CanvasMetricItem[] {
+  if (!Array.isArray(value)) return []
+  const items: CanvasMetricItem[] = []
+  for (const entry of value) {
+    const row = asObject(entry)
+    if (!row) continue
+    const label = asTrimmedString(row.label, 120)
+    const metricValue = asTrimmedString(row.value, 120)
+    if (!label || !metricValue) continue
+    items.push({
+      label,
+      value: metricValue,
+      detail: asTrimmedString(row.detail, 240) || undefined,
+      tone: row.tone === 'positive' || row.tone === 'negative' || row.tone === 'warning' ? row.tone : 'default',
+    })
+    if (items.length >= 24) break
+  }
+  return items
+}
+
+function normalizeCardItems(value: unknown): CanvasCardItem[] {
+  if (!Array.isArray(value)) return []
+  const items: CanvasCardItem[] = []
+  for (const entry of value) {
+    const row = asObject(entry)
+    if (!row) continue
+    const title = asTrimmedString(row.title, 180)
+    if (!title) continue
+    items.push({
+      title,
+      body: asTrimmedString(row.body, 1600) || undefined,
+      meta: asTrimmedString(row.meta, 200) || undefined,
+      tone: row.tone === 'positive' || row.tone === 'negative' || row.tone === 'warning' ? row.tone : 'default',
+    })
+    if (items.length >= 24) break
+  }
+  return items
+}
+
+function normalizeActionItems(value: unknown): CanvasActionItem[] {
+  if (!Array.isArray(value)) return []
+  const items: CanvasActionItem[] = []
+  for (const entry of value) {
+    const row = asObject(entry)
+    if (!row) continue
+    const label = asTrimmedString(row.label, 120)
+    if (!label) continue
+    items.push({
+      label,
+      href: asTrimmedString(row.href, 1000) || undefined,
+      note: asTrimmedString(row.note, 240) || undefined,
+      intent: row.intent === 'primary' || row.intent === 'success' || row.intent === 'danger' ? row.intent : 'secondary',
+    })
+    if (items.length >= 24) break
+  }
+  return items
+}
+
+function normalizeTable(value: unknown): CanvasTableData | null {
+  const row = asObject(value)
+  if (!row) return null
+  const columns = asStringArray(row.columns).slice(0, 20)
+  if (!columns.length) return null
+  const rows = Array.isArray(row.rows)
+    ? row.rows
+        .map((entry) => Array.isArray(entry)
+          ? entry.slice(0, columns.length).map((cell) => (
+            typeof cell === 'string'
+            || typeof cell === 'number'
+            || typeof cell === 'boolean'
+            || cell === null
+              ? cell
+              : JSON.stringify(cell)
+          ))
+          : null)
+        .filter((entry): entry is Array<string | number | boolean | null> => Array.isArray(entry))
+        .slice(0, 100)
+    : []
+  return rows.length
+    ? {
+        columns,
+        rows,
+        caption: asTrimmedString(row.caption, 240) || undefined,
+      }
+    : null
+}
+
+function normalizeBlock(value: unknown): CanvasBlock | null {
+  const row = asObject(value)
+  if (!row) return null
+  const title = asTrimmedString(row.title, 160) || undefined
+  switch (row.type) {
+    case 'markdown': {
+      const markdown = asTrimmedString(row.markdown, 20_000)
+      return markdown ? { type: 'markdown', title, markdown } : null
+    }
+    case 'metrics': {
+      const items = normalizeMetricItems(row.items)
+      return items.length ? { type: 'metrics', title, items } : null
+    }
+    case 'cards': {
+      const items = normalizeCardItems(row.items)
+      return items.length ? { type: 'cards', title, items } : null
+    }
+    case 'table': {
+      const table = normalizeTable(row.table)
+      return table ? { type: 'table', title, table } : null
+    }
+    case 'code': {
+      const code = asTrimmedString(row.code, 20_000)
+      return code ? { type: 'code', title, code, language: asTrimmedString(row.language, 60) || undefined } : null
+    }
+    case 'actions': {
+      const items = normalizeActionItems(row.items)
+      return items.length ? { type: 'actions', title, items } : null
+    }
+    default:
+      return null
+  }
+}
+
+export function normalizeCanvasDocument(value: unknown): CanvasDocument | null {
+  const row = asObject(value)
+  if (!row) return null
+  const blocks = Array.isArray(row.blocks)
+    ? row.blocks.map((entry) => normalizeBlock(entry)).filter((entry): entry is CanvasBlock => entry !== null).slice(0, 24)
+    : []
+  if (!blocks.length) return null
+  return {
+    kind: 'structured',
+    title: asTrimmedString(row.title, 180) || undefined,
+    subtitle: asTrimmedString(row.subtitle, 320) || undefined,
+    theme: row.theme === 'sky' || row.theme === 'emerald' || row.theme === 'amber' || row.theme === 'rose' ? row.theme : 'slate',
+    blocks,
+    updatedAt: typeof row.updatedAt === 'number' && Number.isFinite(row.updatedAt) ? row.updatedAt : Date.now(),
+  }
+}
+
+export function isCanvasDocument(value: unknown): value is CanvasDocument {
+  return normalizeCanvasDocument(value) !== null
+}
+
+export function normalizeCanvasContent(value: unknown): CanvasContent {
+  if (typeof value === 'string') return value || null
+  if (value === null || value === undefined) return null
+  return normalizeCanvasDocument(value)
+}
+
+export function summarizeCanvasContent(content: CanvasContent): Record<string, unknown> {
+  if (!content) {
+    return { kind: 'empty', hasContent: false, contentLength: 0, preview: null }
+  }
+  if (typeof content === 'string') {
+    return {
+      kind: 'html',
+      hasContent: true,
+      contentLength: content.length,
+      preview: content.slice(0, 500),
+    }
+  }
+  return {
+    kind: 'structured',
+    hasContent: true,
+    blockCount: content.blocks.length,
+    title: content.title || null,
+    blockTypes: content.blocks.map((block) => block.type),
+    preview: JSON.stringify(content).slice(0, 500),
+  }
+}