@neurosquad/card-sdk 1.0.0

package/dist/types/contract/ports.d.ts

@@ -0,0 +1,237 @@
+import type { CardJsonSchema } from './jsonSchema.js';
+import type { LocalizedText } from './localized.js';
+import type { PermissionId } from './permissions.js';
+/** `ns:*` well-known types, or `<package-name>/<type-name>` custom types (which must carry a schema). */
+export type PortTypeId = WellKnownPortType | `${string}/${string}`;
+export declare const CUSTOM_PORT_TYPE_RE: RegExp;
+export declare const PORT_ID_RE: RegExp;
+export declare const WELL_KNOWN_PORT_SCHEMAS: {
+    /** Anything JSON. As an input: accepts every output type unchanged. */
+    readonly 'ns:any': {};
+    readonly 'ns:text': {
+        readonly type: "string";
+        readonly maxLength: 1000000;
+    };
+    readonly 'ns:markdown': {
+        readonly type: "string";
+        readonly maxLength: 1000000;
+    };
+    readonly 'ns:number': {
+        readonly type: "number";
+    };
+    readonly 'ns:boolean': {
+        readonly type: "boolean";
+    };
+    readonly 'ns:json': {
+        readonly type: readonly ["object", "array"];
+    };
+    readonly 'ns:url': {
+        readonly type: "string";
+        readonly format: "uri";
+        readonly maxLength: 8192;
+    };
+    /** Base64 image, ≤ ~700 KB decoded (message limit). */
+    readonly 'ns:image': {
+        readonly type: "object";
+        readonly required: readonly ["mimeType", "data"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly mimeType: {
+                readonly enum: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+            };
+            readonly data: {
+                readonly type: "string";
+                readonly maxLength: 1000000;
+            };
+            readonly alt: {
+                readonly type: "string";
+                readonly maxLength: 500;
+            };
+        };
+    };
+    /** A file in the workspace folder (relative path). Receiving one grants no file access. */
+    readonly 'ns:file-ref': {
+        readonly type: "object";
+        readonly required: readonly ["path"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            };
+            readonly line: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+        };
+    };
+    readonly 'ns:task': CardJsonSchema;
+    readonly 'ns:tasks': {
+        readonly type: "array";
+        readonly maxItems: 200;
+        readonly items: CardJsonSchema;
+    };
+    /** Change one existing task; `ref` is its id or its exact text. */
+    readonly 'ns:task-patch': {
+        readonly type: "object";
+        readonly required: readonly ["ref"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly ref: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+            };
+            readonly text: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+            };
+            readonly status: {
+                readonly enum: readonly ["pending", "active", "done", "error"];
+            };
+            readonly column: {
+                readonly type: "string";
+                readonly maxLength: 64;
+            };
+        };
+    };
+    readonly 'ns:table': {
+        readonly type: "object";
+        readonly required: readonly ["columns", "rows"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly columns: {
+                readonly type: "array";
+                readonly maxItems: 64;
+                readonly items: {
+                    readonly type: "string";
+                    readonly maxLength: 200;
+                };
+            };
+            readonly rows: {
+                readonly type: "array";
+                readonly maxItems: 5000;
+                readonly items: {
+                    readonly type: "array";
+                    readonly maxItems: 64;
+                    readonly items: {
+                        readonly type: readonly ["string", "number", "boolean", "null"];
+                    };
+                };
+            };
+        };
+    };
+    readonly 'ns:event': {
+        readonly type: "object";
+        readonly required: readonly ["type"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly type: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly data: {};
+            readonly at: {
+                readonly type: "number";
+            };
+        };
+    };
+    /** A bare signal ("go", "refresh"). */
+    readonly 'ns:trigger': {
+        readonly type: readonly ["object", "null"];
+        readonly maxProperties: 0;
+    };
+};
+export type WellKnownPortType = keyof typeof WELL_KNOWN_PORT_SCHEMAS;
+export declare const WELL_KNOWN_PORT_TYPES: WellKnownPortType[];
+export declare function isWellKnownPortType(type: string): type is WellKnownPortType;
+export declare function isValidPortType(type: string): type is PortTypeId;
+/** A port as the manifest declares it. */
+export interface PortDeclaration {
+    /** Unique per direction within the card: `^[a-z][a-z0-9-]{0,31}$`. */
+    id: string;
+    label: LocalizedText;
+    /** What it means — shown to users and to peers (and agents) discovering it. */
+    description?: LocalizedText;
+    type: PortTypeId;
+    /** Extra constraints on top of the type (required for custom types). No `pattern`. */
+    schema?: CardJsonSchema;
+    /**
+     * Inputs only. `stream` (default): fire-and-forget messages.
+     * `request`: the sender waits for a reply (ports.request / ports.respond).
+     */
+    mode?: 'stream' | 'request';
+    /** Inputs with mode `request`: the reply's type. */
+    response?: {
+        type: PortTypeId;
+        schema?: CardJsonSchema;
+    };
+    /** Outputs only: the host keeps the last value; peers can read it any time and new peers get it on connect. */
+    retain?: boolean;
+    /** Inputs only: preferred target when a peer's output fits several inputs. */
+    default?: boolean;
+}
+/** A port as the runtime describes it (own ports, peers' ports). */
+export interface PortInfo {
+    id: string;
+    /** Resolved to the app language. */
+    label: string;
+    description?: string;
+    type: PortTypeId;
+    schema?: CardJsonSchema;
+    mode: 'stream' | 'request';
+    response?: {
+        type: PortTypeId;
+        schema?: CardJsonSchema;
+    };
+    retain: boolean;
+    default: boolean;
+    /** Built-in adapters: the permission the *other* card needs to use this port. */
+    permission?: PermissionId;
+}
+/** The schema a value on this port must satisfy: the type's own, and the declared one too (both must pass). */
+export declare function portSchemas(port: {
+    type: PortTypeId;
+    schema?: CardJsonSchema;
+}): CardJsonSchema[];
+export type PortCoercion = 'exact' | 'any' | 'identity' | 'stringify' | 'json-text' | 'json-markdown' | 'table-markdown' | 'tasks-markdown' | 'wrap-array' | 'lines-to-tasks';
+/** How a value of output type `from` reaches an input of type `to`; null = incompatible. */
+export declare function portCoercion(from: PortTypeId, to: PortTypeId): PortCoercion | null;
+export declare function portsCompatible(from: PortTypeId, to: PortTypeId): boolean;
+/**
+ * Converts a value from an output of type `from` for an input of type `to`.
+ * Call only when portCoercion() is non-null; the result is validated against
+ * the input's schemas by the caller (main) before delivery.
+ */
+export declare function coercePortValue(from: PortTypeId, to: PortTypeId, value: unknown): unknown;
+/**
+ * Picks the input on a peer that an output value goes to on `emit`: among
+ * compatible inputs (in declaration order) the one marked `default`,
+ * otherwise an exact type match, otherwise the first compatible. Request-mode
+ * inputs are never picked by emit (use ports.request).
+ */
+export declare function pickInputFor(outputType: PortTypeId, inputs: readonly PortInfo[]): PortInfo | null;
+export declare const BUILTIN_PEER_KINDS: readonly ["note", "todo", "kanban", "sticky", "agent", "terminal"];
+export type BuiltinPeerKind = (typeof BUILTIN_PEER_KINDS)[number];
+type BuiltinPort = Omit<PortInfo, 'label' | 'description'> & {
+    label: string;
+    description: string;
+};
+/**
+ * Virtual ports of built-in cards (labels are English; the host localizes
+ * them through `ext.cardSdk.builtinPorts.<kind>.<id>`). Using one requires
+ * the named permission on the *custom* card's side. Delivery semantics
+ * (spec §8.9): note.append appends a paragraph, note.replace replaces the
+ * text; todo/kanban.add add tasks, .update applies a task patch; sticky.title
+ * sets the title; agent.prompt submits a prompt through the prompt queue
+ * (same rules as agents.prompt); terminal.command runs a command
+ * (terminals.run). Outputs are emitted by the host when the card changes.
+ */
+export declare const BUILTIN_CARD_PORTS: Record<BuiltinPeerKind, {
+    inputs: BuiltinPort[];
+    outputs: BuiltinPort[];
+}>;
+export {};

package/dist/types/contract/protocol.d.ts

@@ -0,0 +1,74 @@
+import { PROTOCOL_TAG } from './version.js';
+export declare const CARD_ERROR_CODES: readonly ["BAD_REQUEST", "INVALID_PARAMS", "METHOD_NOT_FOUND", "PERMISSION_DENIED", "NOT_CONNECTED", "NOT_FOUND", "QUOTA_EXCEEDED", "RATE_LIMITED", "TOO_LARGE", "TIMEOUT", "BUDGET_PAUSED", "BUSY", "HOST_NOT_ALLOWED", "NETWORK_ERROR", "FS_DENIED", "FS_ERROR", "NOT_VISIBLE", "USER_CANCELLED", "UNAVAILABLE", "PROTOCOL_MISMATCH", "NOT_READY", "INTERNAL"];
+export type CardErrorCode = (typeof CARD_ERROR_CODES)[number];
+export interface CardErrorPayload {
+    code: CardErrorCode;
+    /** English, for developers. UIs show their own text per code. */
+    message: string;
+    data?: unknown;
+}
+interface Envelope {
+    ns: typeof PROTOCOL_TAG;
+    v: number;
+}
+export interface RequestMessage extends Envelope {
+    kind: 'req';
+    /** Positive integer, unique among the card's in-flight requests. */
+    id: number;
+    method: string;
+    params?: unknown;
+}
+export interface ResponseMessage extends Envelope {
+    kind: 'res';
+    id: number;
+    ok: boolean;
+    result?: unknown;
+    error?: CardErrorPayload;
+}
+export interface EventMessage extends Envelope {
+    kind: 'evt';
+    event: string;
+    data?: unknown;
+}
+export type CardToHostMessage = RequestMessage;
+export type HostToCardMessage = ResponseMessage | EventMessage;
+/** The first message the *renderer* posts into the frame's window, with the MessagePort as transfer. */
+export interface ConnectMessage {
+    ns: typeof PROTOCOL_TAG;
+    type: 'connect';
+    protocol: number;
+}
+export declare function isConnectMessage(data: unknown): data is ConnectMessage;
+/** Size of a message as the limits count it (JSON text length). Infinity when it cannot be serialized. */
+export declare function messageSize(message: unknown): number;
+export type CardMessageParse = {
+    ok: true;
+    message: RequestMessage;
+} | {
+    ok: false;
+    id: number | null;
+    error: CardErrorPayload;
+};
+/**
+ * Main's first check on everything that arrives on a card's port. Returns the
+ * request, or an error to send back (with the id when one could be read;
+ * `id: null` means drop silently — nothing to answer to).
+ */
+export declare function parseCardMessage(data: unknown, maxBytes?: number): CardMessageParse;
+/** The SDK's check on host messages (defensive: the host is trusted, but a bug should not crash the card). */
+export declare function parseHostMessage(data: unknown): HostToCardMessage | null;
+export declare function okResponse(id: number, result?: unknown): ResponseMessage;
+export declare function errorResponse(id: number, code: CardErrorCode, message: string, data?: unknown): ResponseMessage;
+export declare function eventMessage(event: string, data?: unknown): EventMessage;
+export declare function requestMessage(id: number, method: string, params?: unknown): RequestMessage;
+/** Token bucket used per instance for requests (and by main per port/network where the spec says so). */
+export declare class TokenBucket {
+    private readonly perSecond;
+    private readonly capacity;
+    private tokens;
+    private last;
+    constructor(perSecond: number, capacity: number, now: number);
+    /** Takes one token; returns 0 when allowed, else the ms until one is available. */
+    take(now: number): number;
+}
+export {};

package/dist/types/contract/source.d.ts

@@ -0,0 +1,111 @@
+export interface GithubSource {
+    type: 'github';
+    /** Lowercased — GitHub owners and repos are case-insensitive. */
+    owner: string;
+    repo: string;
+    /** Package root inside the repo (POSIX, no leading/trailing slash), case kept. */
+    subdir?: string;
+    /** Branch, tag or commit the user asked for; absent = the default branch. */
+    ref?: string;
+    /** True when the input named a release (`/releases/tag/<tag>`): updates follow the latest release. */
+    release?: boolean;
+}
+export interface DevSource {
+    type: 'dev';
+    /** Absolute folder path as main resolved it (realpath). */
+    folder: string;
+}
+export type PackageSource = GithubSource | DevSource;
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** A git ref name we are willing to put in an API URL. */
+export declare function isSafeRef(ref: string): boolean;
+export declare function isCommitSha(value: string): boolean;
+/**
+ * Parses what a user types into "Install from GitHub":
+ *
+ *   owner/repo                         owner/repo@v1.2.0
+ *   owner/repo/cards/pomodoro          owner/repo/cards/pomodoro@main
+ *   github.com/owner/repo              https://github.com/owner/repo.git
+ *   https://github.com/owner/repo/tree/<ref>/<subdir…>   (ref without slashes)
+ *   https://github.com/owner/repo/releases/tag/<tag>
+ *
+ * A ref containing slashes must use the `@ref` form.
+ */
+export declare function parseGithubSource(input: string): ParseResult<GithubSource>;
+/**
+ * The package identity: `github:<owner>/<repo>[/<subdir>]` or `dev:<folder>`.
+ * Ref is deliberately not part of it — updating a package keeps its id,
+ * grants, storage and card instances.
+ */
+export declare function packageIdFor(source: PackageSource): string;
+/** `https://github.com/<owner>/<repo>[/tree/<commit>/<subdir>]` — the "view source" link consent shows. */
+export declare function githubBrowseUrl(source: GithubSource, commit?: string): string;
+/** `https://github.com/<owner>/<repo>/compare/<from>...<to>` — what an update changes. */
+export declare function githubCompareUrl(source: GithubSource, from: string, to: string): string;
+/**
+ * A path inside a package (manifest `entry`, `icon`, an archive entry after
+ * its root is stripped, a URL path the protocol serves). Relative, POSIX
+ * separators, portable to Windows, within the depth/length limits, and never
+ * inside the host's reserved `__ns/` prefix. Returns it normalized.
+ */
+export declare function validatePackagePath(path: string): ParseResult<string>;
+/**
+ * Maps one tarball entry name to a package path. GitHub tarballs put
+ * everything under `<owner>-<repo>-<shortsha>/`; that first segment is
+ * dropped, then `subdir` (when set) must prefix the rest and is dropped too.
+ *
+ * `null` — the entry is outside the package (other folders of a monorepo, the
+ * root directory entry itself): skip it silently. An error — the archive is
+ * hostile or broken: abort the whole install.
+ */
+export declare function archiveEntryToPackagePath(entryName: string, subdir?: string): {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A path a card passes to `fs.*`: relative to the workspace folder. Accepts
+ * `''`/`'.'` (the root) and backslashes (converted); rejects anything absolute,
+ * any drive/UNC/ADS form, NUL, and `..` segments at all — even ones that
+ * would stay inside, so the check never depends on normalization order.
+ * Returns the normalized relative path (`''` = the root).
+ *
+ * This is only the first gate: main joins it to the workspace folder and
+ * then requires realpath(target) — or, for a path that does not exist yet,
+ * realpath of its nearest existing parent — to stay inside realpath(root).
+ */
+export declare function normalizeWorkspacePath(input: string): ParseResult<string>;
+/**
+ * Is any segment of this path `.git`? Hooks and config in a git folder run
+ * code, and a `.git` *file* (submodule, worktree) points git at another
+ * folder, so both are refused at any depth: a workspace often holds several
+ * repositories (MC-1). Case-insensitive (Windows, macOS).
+ */
+export declare function isGitInternalPath(normalized: string): boolean;
+/**
+ * Why `fs.write`/`mkdir`/`trash` must refuse this workspace-relative path, or
+ * null. Covers `.git` anywhere (MC-1) and the files and folders that make
+ * agents or developer tools run commands without a build step (MC-10): agent
+ * hooks and MCP configs (`.claude/`, `.mcp.json`, …), agent instructions
+ * (`CLAUDE.md`, `AGENTS.md`, …: persistent prompt injection), editor tasks
+ * (`.vscode/`), git hooks managers (`.husky/`), CI (`.github/workflows/`),
+ * direnv and package-manager rc files. Case-insensitive.
+ */
+export declare function protectedWriteReason(normalized: string): string | null;
+/**
+ * The canonical text a package's tree hash is the sha256 of: one line per
+ * file, `<sha256 hex>  <path>\n`, sorted by path (UTF-16 code unit order).
+ * Recorded at install; a reinstall of the same commit must reproduce it.
+ */
+export declare function treeHashInput(entries: readonly {
+    path: string;
+    sha256: string;
+}[]): string;

package/dist/types/contract/theme.d.ts

@@ -0,0 +1,21 @@
+export declare const THEME_TOKENS: readonly ["background", "background-secondary", "background-tertiary", "foreground", "muted", "surface", "surface-foreground", "surface-secondary", "surface-secondary-foreground", "surface-tertiary", "surface-tertiary-foreground", "overlay", "overlay-foreground", "default", "default-foreground", "accent", "accent-foreground", "accent-soft", "accent-soft-foreground", "success", "success-foreground", "success-soft", "warning", "warning-foreground", "warning-soft", "danger", "danger-foreground", "danger-soft", "border", "border-secondary", "separator", "focus", "link", "field-background", "field-foreground", "field-placeholder", "field-border", "radius", "field-radius"];
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+export interface ThemeSnapshot {
+    /** Always 'dark' today; a card must not assume it stays that way. */
+    scheme: 'dark' | 'light';
+    tokens: Record<ThemeToken, string>;
+    /** Computed font stacks of the app. The fonts themselves are not shared; cards ship their own or use system fonts. */
+    fontSans: string;
+    fontMono: string;
+}
+/** Header/status tones the host renders. */
+export declare const CARD_TONES: readonly ["default", "accent", "success", "warning", "danger"];
+export type CardTone = (typeof CARD_TONES)[number];
+/**
+ * Icons a card may ask the *host* to draw (overview tile, menu items,
+ * status). Host UI is heroicons-only (CLAUDE.md); these are
+ * `@heroicons/react/24/outline` names in kebab case. Inside its own frame a
+ * card draws whatever it likes.
+ */
+export declare const HOST_ICON_NAMES: readonly ["academic-cap", "arrow-path", "beaker", "bell", "bolt", "book-open", "bug-ant", "calendar", "camera", "chart-bar", "chart-pie", "chat-bubble-left-right", "check-circle", "clock", "cloud", "code-bracket", "command-line", "cpu-chip", "cube", "currency-dollar", "document-text", "exclamation-triangle", "film", "fire", "flag", "folder", "globe-alt", "heart", "inbox", "key", "light-bulb", "link", "list-bullet", "map", "megaphone", "moon", "musical-note", "newspaper", "paper-airplane", "pause", "photo", "play", "puzzle-piece", "rocket-launch", "server", "shield-check", "signal", "sparkles", "star", "stop", "sun", "table-cells", "tag", "trash", "trophy", "users", "wrench-screwdriver"];
+export type HostIconName = (typeof HOST_ICON_NAMES)[number];

package/dist/types/contract/version.d.ts

@@ -0,0 +1,126 @@
+/** Major version of the wire protocol. A card built for a higher one is refused with PROTOCOL_MISMATCH. */
+export declare const CARD_PROTOCOL_VERSION = 1;
+/** Version of this contract (and of `@neurosquad/card-sdk`'s protocol layer). */
+export declare const CARD_SDK_CONTRACT_VERSION = "1.0.0";
+/** The manifest at the root of every card package. */
+export declare const MANIFEST_FILE = "neurosquad-card.json";
+/** `manifestVersion` this app reads. */
+export declare const MANIFEST_VERSION = 1;
+/** Custom protocol that serves installed packages: `nscard://<hostId>/<path>`. */
+export declare const CARD_SCHEME = "nscard";
+/** `ns` field of every wire message. */
+export declare const PROTOCOL_TAG = "nscard";
+/**
+ * Paths under this prefix are served by the host, never from the package
+ * (`/__ns/boot.js`). A package file whose path starts with it is refused at install.
+ */
+export declare const RESERVED_PATH_PREFIX = "__ns/";
+/** Query parameter carrying the single-use document token (spec §4.3). */
+export declare const FRAME_TOKEN_PARAM = "__ns";
+/** The plugin-card kind (shared/pluginCards.ts) every custom card instance is: `Agent.harness === 'custom'`. */
+export declare const CUSTOM_CARD_KIND = "custom";
+/**
+ * `hostId` — the DNS label a package is served under. `p` + 26 chars of
+ * lowercase base32 (RFC 4648 alphabet, lowercased) of sha256(packageId).
+ * Main computes it; everyone else only checks the shape.
+ */
+export declare const CARD_HOST_ID_RE: RegExp;
+/**
+ * Hard limits. Main enforces every one of them; the SDK checks the cheap ones
+ * early to give authors a readable error. Changing a limit is a contract change.
+ */
+export declare const LIMITS: {
+    /** Serialized size of one message (JSON length in UTF-16 code units, as measured by JSON.stringify). */
+    readonly messageBytes: number;
+    /** Responses of fs.read / net.fetch may be this large. */
+    readonly largeMessageBytes: number;
+    readonly inFlightRequests: 64;
+    /** Token bucket per instance: refill per second / bucket size. */
+    readonly requestsPerSecond: 200;
+    readonly requestBurst: 400;
+    readonly valueDepth: 64;
+    readonly valueNodes: 200000;
+    readonly tarballBytes: number;
+    readonly unpackedBytes: number;
+    readonly fileBytes: number;
+    readonly files: 5000;
+    readonly pathDepth: 20;
+    readonly pathChars: 240;
+    readonly manifestBytes: number;
+    readonly iconBytes: number;
+    readonly storageKeyChars: 256;
+    readonly storageValueBytes: number;
+    readonly storageKeys: 10000;
+    readonly instanceStorageBytes: number;
+    readonly packageStorageBytes: number;
+    readonly settings: 40;
+    readonly portsPerDirection: 16;
+    readonly toolsPerPackage: 32;
+    readonly permissionHosts: 32;
+    readonly schemaNodes: 500;
+    readonly schemaDepth: 16;
+    /** `enum` options per schema node, and their serialized size (MC-2: comparisons cost main CPU). */
+    readonly schemaEnumOptions: 256;
+    readonly schemaEnumBytes: number;
+    /** Serialized size of one `const` value in a card schema. */
+    readonly schemaConstBytes: number;
+    readonly menuItems: 12;
+    readonly netRequestBodyBytes: number;
+    readonly netResponseBytes: number;
+    readonly netConcurrent: 6;
+    readonly netPerMinute: 120;
+    readonly netRedirects: 5;
+    readonly netTimeoutMs: 30000;
+    readonly netMaxTimeoutMs: 120000;
+    readonly netStreams: 4;
+    readonly fsReadBytes: number;
+    readonly fsWriteBytes: number;
+    readonly fsListEntries: 5000;
+    readonly fsWatchers: 20;
+    readonly promptChars: 20000;
+    readonly promptsPerMinute: 6;
+    readonly terminalWriteChars: 20000;
+    readonly terminalRunTimeoutMs: 120000;
+    readonly screenLines: 500;
+    readonly outputFlushMs: 100;
+    readonly outputFlushBytes: number;
+    readonly toolResultBytes: number;
+    readonly toolTimeoutMs: 30000;
+    readonly toolMaxTimeoutMs: 120000;
+    readonly portMessagesPerSecond: 20;
+    readonly retainedValueBytes: number;
+    readonly portRequestTimeoutMs: 30000;
+    readonly attentionIntervalMs: 10000;
+    readonly focusIntervalMs: 5000;
+    readonly toastIntervalMs: 2000;
+    readonly clipboardIntervalMs: 1000;
+    readonly clipboardChars: number;
+    readonly spawnsPerInstance: 4;
+    readonly resizeIntervalMs: 500;
+    readonly titleChars: 120;
+    /** card.setStatus / setBadge / setOverview per minute (the SDK client coalesces to stay under it). */
+    readonly chromeUpdatesPerMinute: 120;
+    readonly statusChars: 80;
+    readonly overviewChars: 160;
+    readonly toastChars: 280;
+    readonly confirmChars: 1000;
+    readonly logLineChars: 2000;
+    readonly logLinesPerSecond: 50;
+    /** Card frames alive at once across the app; beyond it the least recently seen offscreen/hidden ones are suspended. */
+    readonly liveFrames: 24;
+    /** Of those, how many may be kept alive while hidden thanks to the `background` permission. */
+    readonly backgroundFrames: 8;
+    /** A card in a hidden workspace is suspended after this long (unless `background`). */
+    readonly hiddenSuspendMs: 60000;
+    /** Time a card gets between `lifecycle.suspend` and its frame being unloaded. */
+    readonly suspendGraceMs: 1000;
+    /** Single-use document token lifetime. */
+    readonly frameTokenTtlMs: 30000;
+    /** From frame attach to `host.ready`; after that the card shows "not responding". */
+    readonly readyTimeoutMs: 10000;
+    readonly heartbeatMs: 5000;
+    readonly unresponsiveMs: 15000;
+    /** Mounting at most this many card frames per animation frame (canvas perf). */
+    readonly frameMountsPerFrame: 2;
+};
+export type CardLimits = typeof LIMITS;

package/dist/types/i18n.d.ts

@@ -0,0 +1,50 @@
+import type { CardLanguage, I18nSnapshot } from './contract/index.js';
+/** Nested dictionary of strings. Keys are joined with dots: `{ list: { empty: '…' } }` → `list.empty`. */
+export interface Messages {
+    [key: string]: string | Messages;
+}
+/** Translations per app language; `en` is required and is the fallback. */
+export type Catalog = {
+    en: Messages;
+} & Partial<Record<Exclude<CardLanguage, 'en'>, Messages>>;
+/** Values for `{{name}}` placeholders. `count` also picks plural forms. */
+export type TranslateValues = Record<string, string | number | boolean | null | undefined>;
+/** Something that reports the app language — a `Card` fits. */
+export interface LanguageSource {
+    readonly i18n: I18nSnapshot;
+    on(event: 'i18n.changed', handler: (snapshot: I18nSnapshot) => void): () => void;
+}
+/** The function {@link createTranslator} returns, with a few extras. */
+export interface Translator {
+    /**
+     * The text for `key` in the current language (falling back to English,
+     * then to the key itself), with `{{name}}` placeholders filled in.
+     *
+     * Plurals: with `values.count`, `key_one`/`key_few`/`key_many`/`key_other`
+     * (chosen by `Intl.PluralRules`) are tried before `key` — the same
+     * convention as the app (ru has one/few/many/other, zh only other).
+     */
+    (key: string, values?: TranslateValues): string;
+    /** Current language. */
+    readonly language: CardLanguage;
+    /** BCP 47 locale for `Intl` formatting. */
+    readonly locale: string;
+    /** Switches language by hand (normally it follows the card). */
+    setLanguage(language: CardLanguage, locale?: string): void;
+    /** Called after every language change. */
+    onChange(listener: (language: CardLanguage) => void): () => void;
+    /** Stops following the card's language. */
+    dispose(): void;
+}
+/**
+ * Creates a translator. Pass the card (or anything with `i18n` and
+ * `on('i18n.changed')`) to follow the app's language live.
+ *
+ * @example
+ * const t = createTranslator({
+ *   en: { title: 'Tests', failed_one: '{{count}} test failed', failed_other: '{{count}} tests failed' },
+ *   ru: { title: 'Тесты', failed_one: '{{count}} тест упал', failed_few: '{{count}} теста упало', failed_many: '{{count}} тестов упало', failed_other: '{{count}} теста упало' }
+ * }, card)
+ * t('failed', { count: 3 })
+ */
+export declare function createTranslator(catalog: Catalog, source?: LanguageSource): Translator;

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@neurosquad/card-sdk` — build custom cards for NeuroSquad.
+ *
+ * A card is a small web app that runs in a sandboxed frame on the canvas.
+ * `connect()` gives it a typed {@link Card}: agents, typed ports between
+ * cards, tools for connected agents, storage, settings, network through the
+ * host's proxy, workspace files, theme and language.
+ *
+ * @example
+ * import { connect } from '@neurosquad/card-sdk'
+ *
+ * const card = await connect()
+ * card.setStatus('Hello from my card', { tone: 'success' })
+ *
+ * @packageDocumentation
+ */
+export { connect, type ConnectOptions, type HandshakeWindow } from './client/connect.js';
+export { Card, CardAgents, CardFs, CardLifecycle, CardNet, CardPermissions, CardPorts, CardSettings, CardTerminals, CardTools, CardUi, type CallArgs, type CardLog, type CardMenuItem, type CardOptions, type CardStorage, type EventHandler, type PortRequest, type PortRequestHandler, type ScopedStorage, type StorageScope, type ToolCall, type ToolHandler, type ToolReturn, type Unsubscribe, type Widen } from './client/card.js';
+export { LARGE_REQUEST_METHODS, type CallOptions, type CardPort } from './client/channel.js';
+export { CardSdkError, isCardSdkError } from './client/errors.js';
+export { CardHeaders, CardResponse, type CardFetchInit, type NetResponseType } from './client/net.js';
+export { applyTheme, DEFAULT_DARK_THEME, type ThemeTarget } from './client/theme.js';
+export { base64ToBytes, bytesToBase64 } from './client/base64.js';
+export { toolError, toolImage, toolText } from './client/toolResult.js';
+export { hasDownstreamPeer, permissionForPeer, requestPermissions } from './client/helpers.js';
+export { createTranslator, type Catalog, type LanguageSource, type Messages, type TranslateValues, type Translator } from './i18n.js';
+export { SDK_VERSION } from './version.js';
+export * from './contract/index.js';