@neurosquad/card-sdk 1.0.0

package/dist/types/react/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `@neurosquad/card-sdk/react` — React bindings: a provider that connects
+ * the card, and hooks over its live state.
+ *
+ * @example
+ * import { createRoot } from 'react-dom/client'
+ * import { CardProvider, useCardContext, useStorage } from '@neurosquad/card-sdk/react'
+ *
+ * function App() {
+ *   const { instance } = useCardContext()
+ *   const [count, setCount] = useStorage('count', 0)
+ *   return <button onClick={() => setCount(count + 1)}>{instance.displayName}: {count}</button>
+ * }
+ *
+ * createRoot(document.getElementById('root')!).render(
+ *   <CardProvider fallback={<p>Connecting…</p>}><App /></CardProvider>
+ * )
+ *
+ * @packageDocumentation
+ */
+import { type ReactNode } from 'react';
+import { type AgentInfo, type AgentStatus, type Card, type CardEvents, type CardVisibility, type Catalog, type ConnectOptions, type HostContext, type I18nSnapshot, type JsonValue, type PeerInfo, type PortRequestHandler, type SettingValue, type StorageScope, type ThemeSnapshot, type ToolHandler, type Widen, type Translator } from '../index.js';
+/** Props of {@link CardProvider}. */
+export interface CardProviderProps {
+    /** A card you connected yourself (or from `createMockHost().connect()`). Without it the provider calls `connect()`. */
+    card?: Card;
+    /** Options for `connect()` when the provider connects. */
+    connectOptions?: ConnectOptions;
+    /** Shown while connecting. */
+    fallback?: ReactNode;
+    /** Shown when connecting fails. Default: the error message. */
+    errorFallback?: (error: Error) => ReactNode;
+    children?: ReactNode;
+}
+/**
+ * Connects the card (or uses the one you pass) and makes it available to
+ * the hooks below. Renders `fallback` until connected.
+ */
+export declare function CardProvider({ card, connectOptions, fallback, errorFallback, children }: CardProviderProps): ReactNode;
+/** The connected {@link Card}. Must be used under {@link CardProvider}. */
+export declare function useCard(): Card;
+/**
+ * The live HostContext (visibility, size, theme, language, settings,
+ * permissions, peers…). Re-renders when any of it changes.
+ */
+export declare function useCardContext(): HostContext;
+/**
+ * The card's settings values and a setter for non-secret ones.
+ *
+ * @example
+ * const [settings, setSettings] = useSettings()
+ * <Switch checked={settings.values.compact === true} onChange={(v) => setSettings({ compact: v })} />
+ */
+export declare function useSettings(): [
+    HostContext['settings'],
+    (values: Record<string, SettingValue>) => Promise<void>
+];
+/** Result of {@link useStorage} beyond value and setter. */
+export interface StorageState {
+    /** True until the first read finished. */
+    loading: boolean;
+    /** The last read or write error. */
+    error: Error | null;
+}
+/**
+ * A persisted value in the card's storage, like `useState`. The setter
+ * updates at once and writes in the background. Package-scope values follow
+ * writes from other instances.
+ *
+ * @param key Storage key.
+ * @param initial Value until (and unless) one is stored.
+ * @param options `scope`: `'instance'` (default) or `'package'`.
+ */
+export declare function useStorage<I extends JsonValue>(key: string, initial: I, options?: {
+    scope?: StorageScope;
+}): [Widen<I>, (value: Widen<I> | ((previous: Widen<I>) => Widen<I>)) => void, StorageState];
+/**
+ * The agents and shells of the workspace (`agents.read`), kept current from
+ * `agents.changed` and `agents.status`.
+ */
+export declare function useAgents(): {
+    agents: AgentInfo[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+};
+/** One agent's live status, or `undefined` while unknown. */
+export declare function useAgentStatus(agentId: string | null | undefined): AgentStatus | undefined;
+/**
+ * The last value that arrived on an input port (or any input when omitted),
+ * with who sent it.
+ */
+export declare function usePort<T = JsonValue>(input?: string): {
+    data: T | undefined;
+    message: CardEvents['ports.message'] | undefined;
+};
+/** A stable function that emits on one output port; resolves with the number of peers reached. */
+export declare function useEmit<T = JsonValue>(output: string): (data: T) => Promise<number>;
+/** Arrow-connected cards and their ports, live. */
+export declare function usePeers(): PeerInfo[];
+/** The app theme snapshot, live. (The `--ns-*` CSS variables are already applied for you.) */
+export declare function useTheme(): ThemeSnapshot;
+/** The app language (`en`, `ru`, `zh`) and locale, live. */
+export declare function useLanguage(): I18nSnapshot;
+/** `visible`, `offscreen`, `overview` or `hidden`, live. */
+export declare function useVisibility(): CardVisibility;
+/** Whether the card is expanded to fill the canvas. */
+export declare function useExpanded(): boolean;
+/**
+ * True when nobody can see the card's body (offscreen, zoomed out to the
+ * overview, or hidden). Pause animations and polling while it is.
+ */
+export declare function usePaused(): boolean;
+/**
+ * Implements a manifest tool while the component is mounted. The latest
+ * handler is always used — no need to memoize it.
+ */
+export declare function useTool<A = JsonValue>(name: string, handler: ToolHandler<A>): void;
+/** Answers requests to a `mode: "request"` input while mounted. */
+export declare function usePortRequest<T = JsonValue>(input: string, handler: PortRequestHandler<T>): void;
+/**
+ * Subscribes to any host event while mounted (the latest handler is used).
+ *
+ * @example
+ * useCardEvent('agents.turn', (turn) => turn.phase === 'end' && refresh())
+ */
+export declare function useCardEvent<E extends keyof CardEvents>(event: E, handler: (data: CardEvents[E]) => void): void;
+/**
+ * A translator for your own strings that follows the app language.
+ * Create the catalog outside the component (or memoize it).
+ */
+export declare function useTranslator(catalog: Catalog): Translator;

package/dist/types/testing/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@neurosquad/card-sdk/testing` — an in-memory NeuroSquad host for unit
+ * tests and for previewing a card outside the app.
+ *
+ * @packageDocumentation
+ */
+export { createMockHost, MockHost, type MockFetchRequest, type MockFetchResponse, type MockHostOptions, type MockPeer } from './mockHost.js';

package/dist/types/testing/mockHost.d.ts

@@ -0,0 +1,315 @@
+import { type AgentInfo, type CardEvents, type CardEventName, type CardLanguage, type CardManifest, type CardMethodName, type CardSize, type CardVisibility, type EventTopic, type HostContext, type JsonValue, type MethodParams, type MethodResult, type NormalizedManifest, type PeerInfo, type PermissionId, type PortInfo, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type Card, type ConnectOptions } from '../index.js';
+/** A peer card in the mock: its description plus optional behaviour. */
+export interface MockPeer extends PeerInfo {
+    /** Retained output values (`ports.read`). */
+    retained?: Record<string, JsonValue>;
+    /** Answers `ports.request` to this peer. */
+    respond?: (input: string, data: JsonValue) => JsonValue | Promise<JsonValue>;
+}
+/** What a mock `net.fetch` handler receives. */
+export interface MockFetchRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    /** Decoded body (base64 bodies arrive as bytes). */
+    body?: string | Uint8Array;
+}
+/** What a mock `net.fetch` handler returns. */
+export interface MockFetchResponse {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    /** A string, bytes, or a JSON value (serialized). */
+    body?: string | Uint8Array | JsonValue;
+    /** For `responseType: 'stream'`: the chunks to send, in order. */
+    stream?: (string | Uint8Array)[];
+    /** Fail the request with NETWORK_ERROR. */
+    error?: string;
+}
+/** Options of {@link createMockHost}. */
+export interface MockHostOptions {
+    /** The card's manifest (validated like the app does). Default: a minimal manifest named `mock-card`. */
+    manifest?: CardManifest;
+    /**
+     * Granted permissions. Default: every *required* permission of the manifest
+     * (as after install consent); `'all'` also grants optional ones.
+     */
+    grant?: 'all' | PermissionId[];
+    /** Overrides of the HostContext sent on `host.ready`. */
+    context?: Partial<Omit<HostContext, 'instance'>> & {
+        instance?: Partial<HostContext['instance']>;
+    };
+    /** Agents and shells in the workspace. */
+    agents?: AgentInfo[];
+    /** What `agents.readScreen` returns per agent id. */
+    screens?: Record<string, string>;
+    /** What `agents.lastReply` returns per agent id. */
+    replies?: Record<string, string>;
+    /** Arrow-connected cards. */
+    peers?: MockPeer[];
+    /** Files of the in-memory workspace folder (relative paths). */
+    files?: Record<string, string | Uint8Array>;
+    /** Handles `net.fetch` after the host's URL/permission checks. Default: NETWORK_ERROR. */
+    fetch?: (request: MockFetchRequest) => MockFetchResponse | Promise<MockFetchResponse>;
+    /** Answers `ui.confirm`, `card.openLink` and dangerous prompts. Default: confirms. */
+    confirm?: (request: {
+        type: 'confirm' | 'open-link';
+        title?: string;
+        message?: string;
+        url?: string;
+    }) => boolean | Promise<boolean>;
+    /** Answers `permissions.request`. Default: grants every requested optional permission. */
+    requestPermissions?: (ids: PermissionId[]) => PermissionId[] | Promise<PermissionId[]>;
+    /** Protocol the mock host speaks (to test PROTOCOL_MISMATCH). Default: the SDK's. */
+    hostProtocol?: number;
+    /** Apply per-method throttles (`minIntervalMs`, `perMinute`). Default false — tests stay deterministic. */
+    enforceRateLimits?: boolean;
+    /** Usage summary for `usage.summary`. */
+    usage?: UsageSummary;
+    /**
+     * Initial setting values (as if the user had saved them in the host form).
+     * Same as calling `setSettings(values)` before `connect()`.
+     */
+    settings?: Record<string, SettingValue>;
+    /**
+     * Values of the manifest's `secret` settings the user has entered. The card
+     * never sees them; `{{secret:key}}` in `net.fetch` headers is replaced with
+     * them, and a declared secret missing here fails with INVALID_PARAMS like
+     * the app. Change later with `setSecret()`.
+     */
+    secrets?: Record<string, string>;
+    /** Log every request and event to the console. */
+    verbose?: boolean;
+}
+interface StoredFile {
+    data: Uint8Array;
+    mtimeMs: number;
+}
+/**
+ * An in-memory host. Create it with {@link createMockHost}, then
+ * `await host.connect()` to get a real {@link Card} wired to it.
+ *
+ * @example
+ * import { createMockHost } from '@neurosquad/card-sdk/testing'
+ *
+ * const host = createMockHost({ manifest, peers: [notePeer] })
+ * const card = await host.connect()
+ * await card.ports.emit('summary', '# Done')
+ * expect(host.deliveries).toEqual([{ to: 'note-1', input: 'append', data: '# Done', output: 'summary' }])
+ */
+export declare class MockHost {
+    private readonly options;
+    /** The validated, normalized manifest. */
+    readonly manifest: NormalizedManifest;
+    /** Every request the card made, in order (after the envelope check). */
+    readonly calls: {
+        method: string;
+        params: unknown;
+    }[];
+    /** Every event sent to the card. */
+    readonly events: {
+        event: string;
+        data: unknown;
+    }[];
+    /** Storage per scope. */
+    readonly storage: {
+        instance: Map<string, JsonValue>;
+        package: Map<string, JsonValue>;
+    };
+    /** `ports.emit` / `ports.send` deliveries to peers. */
+    readonly deliveries: {
+        to: string;
+        output: string;
+        input: string;
+        data: JsonValue;
+    }[];
+    /** Retained values of the card's own outputs. */
+    readonly retained: Map<string, {
+        data: JsonValue;
+        at: number;
+    }>;
+    /** Prompts the card sent to agents. */
+    readonly prompts: {
+        agentId: string;
+        text: string;
+        delivered: 'sent' | 'queued' | 'inserted';
+    }[];
+    /** Terminal writes and runs. */
+    readonly terminal: {
+        agentId: string;
+        text: string;
+        kind: 'write' | 'run';
+    }[];
+    /** `host.log` lines. */
+    readonly logs: {
+        level: string;
+        message: string;
+    }[];
+    /** `ui.toast` messages. */
+    readonly toasts: {
+        message: string;
+        tone?: string;
+    }[];
+    /** Clipboard writes. */
+    readonly clipboard: string[];
+    /** Cards spawned with `card.spawn`. */
+    readonly spawned: {
+        cardId: string;
+        kind: string;
+        title?: string;
+        init?: JsonValue;
+    }[];
+    /** `net.abort` request ids. */
+    readonly aborted: string[];
+    /** `host.pong` sequence numbers received. */
+    readonly pongs: number[];
+    /** Topics the card is subscribed to (and agent ids for agents.output). */
+    readonly subscriptions: Set<EventTopic>;
+    outputAgents: string[];
+    /** Header/tile state the card set. */
+    readonly chrome: {
+        title: string | null;
+        status: MethodParams<'card.setStatus'> | null;
+        badge: MethodParams<'card.setBadge'> | null;
+        overview: MethodParams<'card.setOverview'> | null;
+        attention: MethodParams<'card.attention'> | null;
+        menu: MethodParams<'ui.setMenu'>['items'];
+        enabledTools: Record<string, boolean>;
+    };
+    /** Workspace files. */
+    readonly files: Map<string, StoredFile>;
+    private context;
+    private granted;
+    private port;
+    private ready;
+    private readonly overrides;
+    private readonly lastCall;
+    private readonly minuteCalls;
+    private readonly toolCalls;
+    private readonly portRequests;
+    private readonly watchers;
+    private seq;
+    private counter;
+    private settingsValues;
+    private secretsSet;
+    private readonly secretValues;
+    /** Agents whose last status was `working` (the turn rule main applies). */
+    private readonly lastStatus;
+    constructor(options?: MockHostOptions);
+    /** A new channel for a card; the returned port goes to `connect({ port })`. Replaces a previous one. */
+    createPort(): MessagePort;
+    /** Connects a real SDK {@link Card} to this host. */
+    connect(options?: Omit<ConnectOptions, 'port' | 'window'>): Promise<Card>;
+    /** Replaces or adds the handler of a method (runs after the host's schema/permission checks). */
+    handle<M extends CardMethodName>(method: M, handler: (params: MethodParams<M>, host: MockHost) => MethodResult<M> | Promise<MethodResult<M>>): this;
+    /** Closes the channel (the card sees UNAVAILABLE on later calls). */
+    close(): void;
+    /** Current HostContext (as it would be sent on `host.ready` now). */
+    get hostContext(): HostContext;
+    /** Currently granted permission ids (with implications). */
+    get grants(): Set<PermissionId>;
+    /** Sends any event to the card. */
+    emit<E extends CardEventName>(event: E, data: CardEvents[E]): void;
+    /** Sends `host.ping` and resolves when the card's `host.pong` arrives. */
+    ping(timeoutMs?: number): Promise<number>;
+    setVisibility(state: CardVisibility): void;
+    setExpanded(expanded: boolean): void;
+    resize(size: CardSize): void;
+    /** Sends `lifecycle.suspend`. */
+    suspend(graceMs?: number): void;
+    setTheme(theme: ThemeSnapshot): void;
+    setLanguage(language: CardLanguage): void;
+    /** The user changed settings in the host form (secrets: pass `true`/`false` in `secrets`). */
+    setSettings(values: Record<string, SettingValue>, secrets?: Record<string, boolean>): void;
+    /**
+     * The user entered (or cleared, with `null`) a secret setting in the host
+     * form. The card only sees `settings.secrets[key]` flip; the value is used
+     * for `{{secret:key}}` in `net.fetch` headers.
+     */
+    setSecret(key: string, value: string | null): void;
+    /** Grants or revokes permissions (the card gets `permissions.changed`). */
+    setGrants(ids: PermissionId[]): void;
+    /** Replaces the connected cards (the card gets `ports.peersChanged`). */
+    setPeers(peers: MockPeer[]): void;
+    /**
+     * Delivers a value to one of the card's inputs, as if a peer emitted it —
+     * with the app's checks: `from.cardId`, when given, must be a peer whose
+     * arrow points at this card (`upstream` or `both`); the value is converted
+     * from the sender's output type (`from.output` of that peer, or
+     * `from.type`) to the input's type and must fit the input's schema.
+     * Without `from.cardId` the first upstream peer is the sender, or an
+     * anonymous custom card when there is none. Throws when the app would not
+     * deliver the value.
+     */
+    sendPortMessage(input: string, data: JsonValue, from?: {
+        cardId?: string;
+        kind?: PeerInfo['kind'];
+        output?: string;
+        /** The sender's output type (default: the peer's output's type, else the input's type). */
+        type?: PortInfo['type'];
+    }): void;
+    /** Asks one of the card's `mode: "request"` inputs and resolves with its reply. */
+    requestPort(input: string, data: JsonValue, options?: {
+        from?: string;
+        timeoutMs?: number;
+    }): Promise<JsonValue>;
+    /**
+     * Calls one of the card's tools as a connected agent would, and resolves
+     * with the result (rejects with the card's error message).
+     */
+    callTool(tool: string, args?: JsonValue, options?: {
+        agent?: {
+            id: string;
+            name: string;
+        };
+        timeoutMs?: number;
+    }): Promise<ToolResultPayload> & {
+        callId: string;
+    };
+    /** Cancels a running tool call (`tools.cancel`); the promise from callTool rejects. */
+    cancelTool(callId: string): void;
+    /**
+     * Changes an agent's status; the card gets `agents.status` if subscribed,
+     * and `agents.turn` by the app's rule: `start` on entering `working`,
+     * `end` on leaving it for `finished` or `needs-input`.
+     */
+    setAgentStatus(agentId: string, status: AgentInfo['status']): void;
+    /** Output of an agent; the card gets `agents.output` if subscribed for that agent. */
+    agentOutput(agentId: string, text: string): void;
+    /** Changes a file (or creates it) and notifies matching watchers. */
+    touchFile(path: string, data?: string | Uint8Array): void;
+    /** Text of a file in the mock workspace, or undefined. */
+    readFile(path: string): string | undefined;
+    private putFile;
+    private agentList;
+    private permissionList;
+    private peerInfos;
+    private peer;
+    private connectedAgent;
+    private until;
+    private reply;
+    private receive;
+    private dispatch;
+    private throttle;
+    private builtin;
+    /** HostContext.chrome as the app would send it. */
+    chromeState(): NonNullable<HostContext['chrome']>;
+    private storageBytes;
+    private confirmed;
+    private deliver;
+    private fetch;
+    /** The app's write rules: any `.git` segment, agent config (`.claude/`, `CLAUDE.md`, `.mcp.json`…). */
+    private assertWritable;
+    private fs;
+}
+/**
+ * Creates an in-memory host for tests and standalone previews. See
+ * {@link MockHost} for what it records and how to drive the card.
+ *
+ * @example Standalone preview (a page opened outside the app)
+ * const card = window.parent === window
+ *   ? await createMockHost({ manifest }).connect()
+ *   : await connect()
+ */
+export declare function createMockHost(options?: MockHostOptions): MockHost;
+export {};

package/dist/types/version.d.ts

@@ -0,0 +1,2 @@
+/** Version of `@neurosquad/card-sdk` (sent to the host in `host.ready`). Kept equal to package.json by a test. */
+export declare const SDK_VERSION = "1.0.0";