@neurosquad/card-sdk 1.0.0

package/templates/react/src/App.tsx

@@ -0,0 +1,131 @@
+import {
+  permissionForPeer,
+  requestPermissions,
+  type AgentStatus,
+  type PermissionId
+} from '@neurosquad/card-sdk'
+import {
+  useAgents,
+  useCard,
+  useCardContext,
+  useEmit,
+  usePort,
+  useSettings,
+  useStorage,
+  useTool,
+  useTranslator
+} from '@neurosquad/card-sdk/react'
+import { useEffect, useState } from 'react'
+import { catalog } from './i18n'
+
+const TONE: Record<AgentStatus, string> = {
+  working: 'ns-dot--accent',
+  'needs-input': 'ns-dot--warning',
+  finished: 'ns-dot--success',
+  idle: '',
+  exited: 'ns-dot--danger'
+}
+
+export function App(): React.JSX.Element {
+  const card = useCard()
+  const { workspace, instance } = useCardContext()
+  const [settings] = useSettings()
+  const t = useTranslator(catalog)
+  const { agents } = useAgents()
+  const [pad, setPad] = useStorage('scratchpad', '')
+  const [hint, setHint] = useState('')
+  const emitScratchpad = useEmit<string>('scratchpad')
+
+  const working = agents.filter((agent) => agent.status === 'working').length
+
+  // What the overview tile shows when the canvas is zoomed out.
+  useEffect(() => {
+    void card.setOverview({
+      primary: t('working', { count: working }),
+      tone: working ? 'accent' : 'default',
+      icon: 'users'
+    })
+  }, [card, t, working])
+
+  // Text arriving on the "text" input port is appended to the scratchpad.
+  const { message } = usePort<string>('text')
+  useEffect(() => {
+    if (message)
+      setPad((previous) =>
+        previous ? `${previous}\n${message.data as string}` : (message.data as string)
+      )
+  }, [message, setPad])
+
+  // A tool for connected agents: they can read what the user wrote here.
+  useTool('read_scratchpad', () => pad || '(the scratchpad is empty)')
+
+  const send = async (): Promise<void> => {
+    try {
+      // A note's input needs the optional cards.connected permission: ask for
+      // it (the app shows its own prompt) before the first send.
+      const needed = card.ports.peers
+        .filter((peer) => peer.direction !== 'upstream')
+        .map((peer) => permissionForPeer(peer, { outputType: 'ns:markdown' }))
+        .filter((id): id is PermissionId => id !== null)
+      if (needed.length > 0) await requestPermissions(card, ...new Set(needed))
+      const delivered = await emitScratchpad(pad)
+      setHint(delivered > 0 ? t('sent', { count: delivered }) : t('notConnected'))
+    } catch (error) {
+      setHint(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  return (
+    <main className="app">
+      <header className="ns-spread">
+        <div className="ns-grow">
+          <p className="ns-subtitle ns-truncate">{workspace.name}</p>
+          <h1 className="ns-title ns-truncate">
+            {String(settings.values['greeting'] ?? instance.displayName)}
+          </h1>
+        </div>
+        <span className="ns-badge ns-badge--accent" title={t('working', { count: working })}>
+          {working}
+        </span>
+      </header>
+
+      <section className="ns-surface ns-surface--inset agents">
+        <p className="ns-subtitle">{t('agents')}</p>
+        <ul className="ns-list ns-scroll">
+          {agents.length === 0 && <li className="ns-list-item ns-muted">{t('noAgents')}</li>}
+          {agents.map((agent) => (
+            <li key={agent.id} className="ns-list-item">
+              <span className={`ns-dot ${TONE[agent.status]}`} />
+              <span className="ns-truncate">{agent.name}</span>
+              <span className="agent-status ns-muted">{t(`status.${agent.status}`)}</span>
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <section className="ns-field pad">
+        <label className="ns-label" htmlFor="pad">
+          {t('scratchpad')}
+        </label>
+        <textarea
+          id="pad"
+          className="ns-textarea"
+          spellCheck={false}
+          value={pad}
+          onChange={(event) => setPad(event.target.value)}
+        />
+      </section>
+
+      <footer className="ns-spread">
+        <span className="ns-small ns-muted ns-truncate">{hint}</span>
+        <button
+          className="ns-btn ns-btn--primary ns-btn--sm"
+          type="button"
+          onClick={() => void send()}
+        >
+          {t('send')}
+        </button>
+      </footer>
+    </main>
+  )
+}

package/templates/react/src/i18n.ts

@@ -0,0 +1,61 @@
+import type { Catalog } from '@neurosquad/card-sdk'
+
+/** The card's own strings in the app's three languages (en is the fallback). */
+export const catalog: Catalog = {
+  en: {
+    agents: 'Agents',
+    scratchpad: 'Scratchpad',
+    send: 'Send',
+    noAgents: 'No agents on this canvas yet',
+    working_one: '{{count}} agent working',
+    working_other: '{{count}} agents working',
+    sent_one: 'Sent to {{count}} card',
+    sent_other: 'Sent to {{count}} cards',
+    notConnected: 'Draw an arrow from this card to a note to send it there',
+    status: {
+      working: 'working',
+      'needs-input': 'waiting for you',
+      finished: 'finished',
+      idle: 'idle',
+      exited: 'stopped'
+    }
+  },
+  ru: {
+    agents: 'Агенты',
+    scratchpad: 'Черновик',
+    send: 'Отправить',
+    noAgents: 'На холсте пока нет агентов',
+    working_one: 'Работает {{count}} агент',
+    working_few: 'Работают {{count}} агента',
+    working_many: 'Работают {{count}} агентов',
+    working_other: 'Работают {{count}} агента',
+    sent_one: 'Отправлено в {{count}} карточку',
+    sent_few: 'Отправлено в {{count}} карточки',
+    sent_many: 'Отправлено в {{count}} карточек',
+    sent_other: 'Отправлено в {{count}} карточки',
+    notConnected: 'Проведите стрелку от этой карточки к заметке, чтобы отправить туда',
+    status: {
+      working: 'работает',
+      'needs-input': 'ждёт вас',
+      finished: 'закончил',
+      idle: 'свободен',
+      exited: 'остановлен'
+    }
+  },
+  zh: {
+    agents: '智能体',
+    scratchpad: '草稿',
+    send: '发送',
+    noAgents: '画布上还没有智能体',
+    working_other: '{{count}} 个智能体正在工作',
+    sent_other: '已发送到 {{count}} 张卡片',
+    notConnected: '从此卡片画一条箭头到笔记，即可发送到那里',
+    status: {
+      working: '工作中',
+      'needs-input': '等待你',
+      finished: '已完成',
+      idle: '空闲',
+      exited: '已停止'
+    }
+  }
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,77 @@
+// Import the SDK first, from the entry module: it starts listening for the
+// app's handshake as soon as it loads.
+import { connect, type Card, type CardManifest } from '@neurosquad/card-sdk'
+import { CardProvider } from '@neurosquad/card-sdk/react'
+import '@neurosquad/card-sdk/ui.css'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import manifest from '../neurosquad-card.json'
+import { App } from './App'
+import './styles.css'
+
+/** Opened on its own (`npm run dev`), the card runs against a mock host with sample data. */
+async function previewCard(): Promise<Card> {
+  const { createMockHost } = await import('@neurosquad/card-sdk/testing')
+  const host = createMockHost({
+    manifest: manifest as unknown as CardManifest,
+    agents: [
+      {
+        id: 'a1',
+        name: 'Claude Code',
+        harness: 'claude-code',
+        kind: 'ai',
+        status: 'working',
+        connected: true
+      },
+      {
+        id: 'a2',
+        name: 'Codex',
+        harness: 'codex-cli',
+        kind: 'ai',
+        status: 'needs-input',
+        connected: false
+      },
+      {
+        id: 't1',
+        name: 'PowerShell',
+        harness: 'shell-powershell',
+        kind: 'shell',
+        status: 'idle',
+        connected: false
+      }
+    ],
+    peers: [
+      {
+        cardId: 'note-1',
+        kind: 'note',
+        name: 'Notes',
+        direction: 'downstream',
+        inputs: [
+          {
+            id: 'append',
+            label: 'Append',
+            type: 'ns:markdown',
+            mode: 'stream',
+            retain: false,
+            default: true,
+            // Like the app: sending to a note needs cards.connected.
+            permission: 'cards.connected'
+          }
+        ],
+        outputs: []
+      }
+    ]
+  })
+  Object.assign(window, { mockHost: host }) // try mockHost.setAgentStatus('a2', 'working') in DevTools
+  return host.connect()
+}
+
+const card = window.parent === window ? await previewCard() : await connect()
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <CardProvider card={card}>
+      <App />
+    </CardProvider>
+  </StrictMode>
+)

package/templates/react/src/styles.css

@@ -0,0 +1,42 @@
+/* Your card's own styles, on top of the optional kit (@neurosquad/card-sdk/ui.css). */
+html,
+body,
+#root {
+  height: 100%;
+  overflow: hidden;
+}
+
+.app {
+  display: grid;
+  grid-template-rows: auto minmax(64px, 1fr) minmax(96px, 1.2fr) auto;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 10px;
+  height: 100%;
+  padding: 12px;
+}
+
+.agents {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-height: 0;
+  padding: 10px;
+}
+
+.agents .ns-list {
+  flex: 1;
+}
+
+.pad {
+  min-height: 0;
+}
+
+.pad .ns-textarea {
+  height: 100%;
+  resize: none;
+}
+
+.agent-status {
+  margin-left: auto;
+  font-size: 12px;
+}

package/templates/react/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"],
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,19 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+// The app serves the built card from nscard://<id>/dist/…, so every URL must be
+// relative (base './'). Commit dist/: installs come straight from the repository.
+export default defineConfig({
+  base: './',
+  plugins: [react()],
+  // One React even when the SDK is linked from a local checkout (file: deps are
+  // symlinks, and Vite would resolve react next to the SDK's real path).
+  resolve: { dedupe: ['react', 'react-dom'] },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+    // The card CSP allows scripts only from the package; no inline preload polyfill.
+    modulePreload: { polyfill: false },
+    target: 'es2022'
+  }
+})

package/templates/vanilla/README.md

@@ -0,0 +1,37 @@
+# __CARD_DISPLAY_NAME__
+
+A custom card for [NeuroSquad](https://neurosquad.ai), made with `@neurosquad/card-sdk`
+(vanilla template — no build step).
+
+## Files
+
+| File | What it is |
+| --- | --- |
+| `neurosquad-card.json` | The manifest: name, size, permissions, settings, ports, tools |
+| `index.html`, `main.js`, `style.css` | The card itself — a small web page |
+| `icon.png` | Square PNG/WebP, ≤ 128 KB |
+| `vendor/` | The SDK (`card-sdk.js`), the optional UI kit (`ui.css`), the mock host for previews and the manifest schema |
+
+## Develop
+
+1. In NeuroSquad: **Settings → Custom cards → Developer mode**.
+2. In this folder: `npx @neurosquad/card-sdk dev` — confirm the link in the app,
+   then add the card from the canvas (**+ → Custom card…**). Saving a file reloads it;
+   the card's log prints in your terminal.
+
+Preview in a browser without the app: `npx serve .` and open the page — it runs
+against a mock host with sample agents.
+
+## Check and share
+
+```sh
+npx @neurosquad/card-sdk validate   # the app's own checks + the install dialog preview
+npx @neurosquad/card-sdk pack       # what would be installed, and the tree hash
+```
+
+Push this folder to GitHub. People install it by pasting `owner/repo` (or
+`owner/repo/path/to/folder`) into **Settings → Custom cards**.
+
+Card code runs in a sandbox: no inline scripts, no external resources (bundle
+everything into the folder), network only through `card.net.fetch` to hosts you
+declare in the `network` permission.

package/templates/vanilla/_gitignore

@@ -0,0 +1,6 @@
+# packed archives (neurosquad-card pack)
+*.tgz
+.DS_Store
+# secrets never go into a card package (pack refuses them anyway)
+.env*
+!.env.example

package/templates/vanilla/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__CARD_DISPLAY_NAME__</title>
+    <!-- Optional dark kit that follows the app theme (--ns-* variables). Delete it to style from scratch. -->
+    <link rel="stylesheet" href="vendor/ui.css" />
+    <link rel="stylesheet" href="style.css" />
+    <!-- Card code must live in files: the card's CSP blocks inline scripts. -->
+    <script type="module" src="main.js"></script>
+  </head>
+  <body class="ns-kit">
+    <main class="app" aria-busy="true">
+      <header class="ns-spread">
+        <div class="ns-grow">
+          <p class="ns-subtitle ns-truncate" id="workspace">&nbsp;</p>
+          <h1 class="ns-title ns-truncate" id="greeting">&nbsp;</h1>
+        </div>
+        <span class="ns-badge ns-badge--accent" id="working" title="">0</span>
+      </header>
+
+      <section class="ns-surface ns-surface--inset agents">
+        <p class="ns-subtitle" data-t="agents">Agents</p>
+        <ul class="ns-list ns-scroll" id="agents"></ul>
+      </section>
+
+      <section class="ns-field pad">
+        <label class="ns-label" for="pad" data-t="scratchpad">Scratchpad</label>
+        <textarea class="ns-textarea ns-grow" id="pad" spellcheck="false"></textarea>
+      </section>
+
+      <footer class="ns-spread">
+        <span class="ns-small ns-muted ns-truncate" id="hint"></span>
+        <button class="ns-btn ns-btn--primary ns-btn--sm" id="send" type="button" data-t="send">
+          Send
+        </button>
+      </footer>
+    </main>
+  </body>
+</html>