@standardagents/code-plugin-sdk 1.0.0-alpha.0 → 1.0.0-alpha.10-rows.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.10-rows.0",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",
@@ -15,6 +15,7 @@
     ".": { "types": "./src/index.d.ts", "import": "./src/index.mjs" },
     "./testing": { "types": "./src/testing.d.ts", "import": "./src/testing.mjs" }
   },
-  "files": ["src", "README.md", "LICENSE"],
+  "bin": { "standard-plugin": "./bin/standard-plugin.mjs" },
+  "files": ["src", "bin", "README.md", "REFERENCE.md", "LICENSE"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/index.d.ts

@@ -1,8 +1,11 @@
 export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
 export type Capability = 'surfaces' | 'events' | 'hooks' | 'panes' | 'projects' |
   'notifications' | 'url' | 'fetch' | 'secrets' | 'webhook';
-export type SurfaceKind = 'section' | 'slot' | 'badge' | 'panel' | 'overlay' |
+/** `card` draws a sidebar card under the `plugins` anchor, with an optional border. */
+export type SurfaceKind = 'section' | 'card' | 'slot' | 'badge' | 'panel' | 'overlay' |
   'menu' | 'command' | 'key' | 'link';
+/** How a panel opens. Absent means `popover`. */
+export type Presentation = 'popover' | 'column' | 'pane';
 export type MenuPosition = 'top' | 'after-open' | 'before-danger' | 'bottom';
 export type Anchor = 'plugins' | 'machine.before' | 'machine.after' |
   'project.before' | 'project.after' | 'pane.header' | 'pane.footer' |
@@ -11,6 +14,10 @@ export interface ContributionDeclaration {
   id: string;
   kind: SurfaceKind;
   anchor: Anchor;
+  /** Sidebar card border. Defaults to true; false retains the title and content padding. */
+  border?: boolean;
+  /** One author-selected Nerd Font glyph; omitted on non-Nerd viewer tiers. */
+  icon?: string;
   title?: string;
   merge?: 'by-machine' | 'by-identity';
   width?: 'full' | 'half';
@@ -19,6 +26,10 @@ export interface ContributionDeclaration {
   chord?: string;
   pattern?: string;
   actionId?: string;
+  /** How a panel opens (panels), or how the panel named by `opens` opens (cards and commands). */
+  presentation?: Presentation;
+  /** The id of a declared panel that a card or command opens when activated. */
+  opens?: string;
 }
 /** The package.json standardPlugin field is read before any plugin code runs. */
 export interface PluginManifest {
@@ -62,7 +73,23 @@ export interface TextSpan {
   underline?: boolean;
   actionId?: string;
 }
+/** Viewer-resolved grouping and ordered truncation for pane header/footer rows. */
+export interface RowLayout {
+  projectTint?: boolean;
+  fields: Array<{
+    text: string;
+    icon?: string;
+    fallback?: string;
+    tone?: 'muted' | 'ok' | 'error' | 'info' | 'warning' | 'project';
+    surface?: boolean;
+    bold?: boolean;
+    gap?: number;
+    flex?: boolean;
+    shrink?: { priority: number; min: number; mode: 'start' | 'middle' | 'end' | 'hide' };
+  }>;
+}
 export interface NativeRow {
+  layout?: RowLayout;
   id: string;
   identity?: string;
   providerRevision?: string;
@@ -72,17 +99,89 @@ export interface NativeRow {
   spark?: number[];
   divider?: boolean;
 }
-export type NativeContent = { kind: 'rows'; rows: NativeRow[] } |
-  { kind: 'text'; lines: TextSpan[][] } |
-  { kind: 'badge'; spans: TextSpan[]; actionId?: string };
+export type RowsContent = { kind: 'rows'; rows: NativeRow[] };
+export type TextContent = { kind: 'text'; lines: TextSpan[][] };
+export type BadgeContent = { kind: 'badge'; spans: TextSpan[]; actionId?: string };
+export type NativeContent = RowsContent | TextContent | BadgeContent;
+/** `columns` sets canvas content width. Sidebar card borders fill the sidebar; columns and panes size to content. */
+export interface CanvasThemeColor {
+  /** ANSI palette index 0..15; omitted uses the viewer's default foreground. */
+  source?: number;
+  /** Optional second ANSI palette index, mixed equally with source. */
+  mix?: number;
+  /** Blend against the viewer background, from 0 to 1. */
+  opacity: number;
+}
 export interface CanvasSpec {
+  /** Up to 32 canvas-local indexed color recipes. Keys are ANSI indexes 0..255. */
+  themeColors?: Record<number, CanvasThemeColor>;
   columns: number;
   rows: number;
   transparent?: boolean;
   shade?: number;
   captureInput?: boolean;
+  /** A bounded one-line string or styled spans shown while the pointer rests over the canvas. */
+  hover?: string | TextSpan[];
 }
-export type SurfaceContent = NativeContent | { kind: 'canvas'; canvas: CanvasSpec };
+export type CanvasContent = { kind: 'canvas'; canvas: CanvasSpec };
+/**
+ * What an `onInput` handler for a canvas receives. Keys arrive while the canvas
+ * declares `captureInput` and holds focus; focus loss arrives when the host
+ * stops showing it.
+ */
+export type CanvasInputEvent =
+  | { kind: 'key'; key: string; phase: 'press' | 'repeat'; contributionId: string; entity?: EntityRef }
+  | { kind: 'focus'; focused: false; contributionId: string; entity?: EntityRef };
+
+/** Semantic tones. The host maps each tone to the viewer's theme. */
+export type Tone = 'ok' | 'info' | 'warn' | 'error' | 'muted' | 'accent' | 'pending' | 'bright';
+export type TextWeight = 'normal' | 'bold' | 'dim';
+export type Align = 'start' | 'center' | 'end';
+/** The host sends `actionId` and `value` to the plugin; `opens` names a panel the host opens after the plugin accepts. */
+export interface ViewAction { actionId: string; value?: string; opens?: string }
+export interface ViewSpan { text: string; tone?: Tone; weight?: TextWeight; mono?: boolean }
+export interface StackNode { type: 'stack'; gap?: number; children?: ViewNode[] }
+export interface RowNode { type: 'row'; children?: ViewNode[]; align?: Align }
+export interface DividerNode { type: 'divider'; label?: string }
+/** Either `text` or `spans`; a node with both draws `text` first. */
+export interface TextNode { type: 'text'; text?: string; spans?: ViewSpan[]; tone?: Tone; weight?: TextWeight; mono?: boolean }
+export interface BadgeNode { type: 'badge'; label: string; tone?: Tone }
+export interface DotNode { type: 'dot'; tone?: Tone }
+export interface Meter { value: number; max: number; tone?: Tone; label?: string }
+export interface ProgressNode extends Meter { type: 'progress' }
+export interface SegmentsNode { type: 'segments'; items: Meter[] }
+/** A boxed group inside a panel or section view. A card contribution's view cannot contain one. */
+export interface CardNode { type: 'card'; title?: string; tone?: Tone; children?: ViewNode[] }
+export interface StatNode { type: 'stat'; label: string; value: string; tone?: Tone; hint?: string }
+/** `copy` marks a value the viewer can copy from the focused row. */
+export interface KvItem { label: string; value: string; mono?: boolean; copy?: boolean }
+export interface KvNode { type: 'kv'; items: KvItem[] }
+export interface TabItem { id: string; label: string; sublabel?: string; tone?: Tone; count?: number; tag?: string }
+/**
+ * With `filters` naming a table in the same view, the host shows only rows whose `tags` contain the
+ * chosen item's `tag`; an item without `tag` shows every row. `action` also notifies the plugin, and
+ * its value defaults to the chosen item id.
+ */
+export interface TabsNode { type: 'tabs'; id: string; items: TabItem[]; filters?: string; action?: ViewAction }
+export interface SelectOption { id: string; label: string; group?: string; count?: number; tag?: string }
+export interface SelectNode { type: 'select'; id: string; label: string; options: SelectOption[]; filters?: string; action?: ViewAction }
+/** Lower `priority` values stay visible longest when the host drops columns to fit. */
+export interface TableColumn { id: string; label?: string; width?: 'fill' | number; maxWidth?: number; align?: Align; priority?: number }
+/** A missing cell draws empty. `note` is a secondary line; `tags` feed host-side filters. */
+export interface TableRow { id: string; cells?: Record<string, ViewNode>; tone?: Tone; note?: ViewSpan[]; tags?: string[]; action?: ViewAction }
+export interface TableNode { type: 'table'; id: string; columns: TableColumn[]; rows?: TableRow[] }
+export interface LogNode { type: 'log'; lines: string[] }
+export interface ButtonNode { type: 'button'; label: string; action: ViewAction }
+export type ViewNode = StackNode | RowNode | DividerNode | TextNode | BadgeNode | DotNode | ProgressNode |
+  SegmentsNode | CardNode | StatNode | KvNode | TabsNode | SelectNode | TableNode | LogNode | ButtonNode;
+/** A host-rendered view tree. Cards, panels, and sections accept it. */
+export interface ViewContent { kind: 'view'; root: ViewNode; /** Passive styled title for card views. */ title?: TextSpan[] }
+
+/** Slots and overlays accept rows, text, or canvas. */
+export type DrawnContent = RowsContent | TextContent | CanvasContent;
+/** Sections, cards, and panels also accept a view. */
+export type PanelContent = DrawnContent | ViewContent;
+export type SurfaceContent = NativeContent | CanvasContent | ViewContent;
 export interface RequestOptions { signal?: AbortSignal; timeoutMs?: number }
 export interface Disposable { dispose(): void }
 export type Cleanup = () => void | Promise<void>;
@@ -106,6 +205,7 @@ export interface PaneCreate {
   contributionId?: string;
 }
 export interface PaneResult { pane: EntityRef; operationId: string }
+/** A view action delivers its string `value`; other selections may carry any JSON value. */
 export interface Selection { entity?: EntityRef; actionId: string; value?: Json }
 export interface LinkSelection extends Selection { url: string }
 export type ActionHandler = (event: Selection, context: HandlerContext) => Json | void | Promise<Json | void>;
@@ -147,6 +247,54 @@ export interface PluginEvent {
   data: Json;
   deliveryId?: string;
 }
+/** The native release this machine runs. */
+export type BuildInfo = {
+  version: string;
+  /** The 40-character lowercase commit SHA. */
+  commit: string;
+  /** The Git ref of the build's source, such as `refs/heads/main`, or null when it is not known. */
+  ref: string | null;
+  channel: 'branch' | 'canary' | 'production' | 'team' | null;
+};
+/** The account-wide build policy every machine in the fleet follows. */
+export type FleetPolicy = {
+  mode: 'follow' | 'pin' | 'production' | null;
+  npmTag: string | null;
+  /** The Git ref of the followed channel, or null when it is not known. */
+  ref: string | null;
+  /** The pinned or target version, or null when it is not known. */
+  version: string | null;
+};
+/** A local project available to plugins on its owning machine. */
+export interface PluginProjectContext { entity: EntityRef; name: string; path: string }
+/** Pane context with its configured project launch directory. */
+export interface PluginPaneContext { entity: EntityRef; projectId: string; name: string; cwd: string }
+/** The `context.get` result. `build` and `fleet` are null when unknown. */
+export type PluginContextInfo = {
+  accountId: string;
+  machineId: string;
+  projects: PluginProjectContext[];
+  panes: PluginPaneContext[];
+  /** False when local records could not be included or decoded. */
+  complete: boolean;
+  build?: BuildInfo | null;
+  fleet?: FleetPolicy | null;
+};
+/** Replaces the local pane/project context after an account change. */
+export type PaneContextEventData = Pick<PluginContextInfo, 'machineId' | 'projects' | 'panes' | 'complete'>;
+export interface PaneContextEvent extends PluginEvent {
+  name: 'pane-context';
+  data: PaneContextEventData;
+}
+/** The `data` of a `build-context` event. */
+export type BuildContextEventData = {
+  build: BuildInfo | null;
+  fleet: FleetPolicy | null;
+};
+export interface BuildContextEvent extends PluginEvent {
+  name: 'build-context';
+  data: BuildContextEventData;
+}
 export interface Popover {
   kind: 'chooser' | 'form' | 'confirm';
   title: string;
@@ -171,7 +319,8 @@ export interface OperationMap {
   'config.get': { input: Record<string, never>; output: Record<string, Json> };
   'state.get': { input: { key: string }; output: Json };
   'state.set': { input: { key: string; value: Json }; output: null };
-  'context.get': { input: Record<string, never>; output: Json };
+  'state.keys': { input: Record<string, never>; output: string[] };
+  'context.get': { input: Record<string, never>; output: PluginContextInfo };
   'popover.open': { input: Popover; output: { choiceId?: string; values?: Record<string, Json>; confirmationId?: string } | null };
   'canvas.write': { input: { key: ContributionKey; ansi: string }; output: null };
   'canvas.focus': { input: { key: ContributionKey; capture: boolean }; output: null };
@@ -186,8 +335,9 @@ export interface OperationMap {
 export type OperationName = keyof OperationMap;
 export type Operation = { [K in OperationName]: { op: K; args: OperationMap[K]['input'] } }[OperationName];
 export type Request = <K extends OperationName>(op: K, args: OperationMap[K]['input'], options?: RequestOptions) => Promise<OperationMap[K]['output']>;
-export interface Publisher extends Disposable {
-  replace(content: SurfaceContent): void;
+export interface Publisher<C extends SurfaceContent = SurfaceContent> extends Disposable {
+  /** Throws a PluginError when the content breaks a protocol bound or does not suit the contribution kind. */
+  replace(content: C): void;
   clear(): void;
 }
 export interface Canvas extends Publisher {
@@ -206,11 +356,13 @@ export interface PluginContext {
   readonly producer: Readonly<Producer>;
   readonly signal: AbortSignal;
   request: Request;
-  section(id: string, entity?: EntityRef): Publisher;
-  slot(id: string, entity: EntityRef): Publisher;
-  badge(id: string, entity: EntityRef): Publisher;
-  panel(id: string, entity?: EntityRef): Publisher;
-  overlay(id: string, entity?: EntityRef): Publisher;
+  section(id: string, entity?: EntityRef): Publisher<PanelContent>;
+  card(id: string, entity?: EntityRef): Publisher<PanelContent>;
+  slot(id: string, entity: EntityRef): Publisher<DrawnContent>;
+  badge(id: string, entity: EntityRef): Publisher<BadgeContent>;
+  panel(id: string, entity?: EntityRef): Publisher<PanelContent>;
+  overlay(id: string, entity?: EntityRef): Publisher<DrawnContent>;
+  /** Publishes plugin-drawn content to any section, card, slot, panel, or overlay declaration. */
   canvas(id: string, spec: CanvasSpec, entity?: EntityRef): Canvas;
   /** IDs match static manifest contributions. Options override declaration defaults. */
   menu(id: string, options: MenuOptions, handler: ActionHandler): Subscription;
@@ -224,9 +376,12 @@ export interface PluginContext {
   key(id: string, handler: ActionHandler): KeyRegistration;
   link(id: string, options: LinkOptions, handler: LinkHandler): Subscription;
   link(id: string, handler: LinkHandler): Subscription;
+  onEvent(name: 'pane-context', handler: (event: PaneContextEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
+  onEvent(name: 'build-context', handler: (event: BuildContextEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
   onEvent(name: string, handler: (event: PluginEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
   onHook(name: string, handler: (event: HookEvent, context: HandlerContext) => HookResult | Promise<HookResult>): Subscription;
   onAction(name: string, handler: (event: Selection, context: HandlerContext) => Json | void | Promise<Json | void>): Subscription;
+  /** For a canvas, `name` is its contribution ID and events are `CanvasInputEvent` values. */
   onInput(name: string, handler: (event: Json, context: HandlerContext) => void | Promise<void>): Subscription;
   onSelect(name: string, handler: (event: Selection, context: HandlerContext) => void | Promise<void>): Subscription;
   onResize(name: string, handler: (event: { columns: number; rows: number }, context: HandlerContext) => void | Promise<void>): Subscription;
@@ -248,9 +403,9 @@ export interface PluginContext {
   fetch(args: OperationMap['fetch']['input'], options?: RequestOptions): Promise<OperationMap['fetch']['output']>;
   secrets: { get(name: string, options?: RequestOptions): Promise<string | null> };
   config: { get(options?: RequestOptions): Promise<Record<string, Json>> };
-  /** Local state for one machine. It is never shared with other machines. */
-  state: { get(key: string, options?: RequestOptions): Promise<Json>; set(key: string, value: Json, options?: RequestOptions): Promise<null> };
-  context: { get(options?: RequestOptions): Promise<Json> };
+  /** Per-plugin key and value storage, held in the user's account and shared across their machines: 256 keys per plugin, 64 KiB per value. `keys()` returns the sorted key names. */
+  state: { get(key: string, options?: RequestOptions): Promise<Json>; set(key: string, value: Json, options?: RequestOptions): Promise<null>; keys(options?: RequestOptions): Promise<string[]> };
+  context: { get(options?: RequestOptions): Promise<PluginContextInfo> };
   popover: { open(args: Popover, options?: RequestOptions): Promise<OperationMap['popover.open']['output']> };
   health: { set(args: OperationMap['health.set']['input'], options?: RequestOptions): Promise<null> };
   webhook: { ack(deliveryId: string, options?: RequestOptions): Promise<null> };
@@ -262,3 +417,82 @@ export interface PluginDefinition {
 export function definePlugin(definition: PluginDefinition): Readonly<PluginDefinition>;
 export function validateManifest(value: unknown): Readonly<PluginManifest>;
 export class PluginError extends Error { code: string; constructor(code: string, message: string) }
+export const PRESENTATIONS: readonly Presentation[];
+export const TONES: readonly Tone[];
+export const VIEW_LIMITS: Readonly<{ depth: 8; nodes: 4096; tableRows: 512; tableColumns: 12; items: 512; logLines: 2048; cardLines: 6; actionValueBytes: 512 }>;
+/**
+ * Throws a PluginError when a view tree breaks a protocol bound or a daemon rule. Unknown node types pass.
+ * `kind: 'card'` adds the card rules; `manifest` requires each action `opens` to name one of its panels.
+ */
+export function validateView(root: unknown, options?: { kind?: SurfaceKind; manifest?: Pick<PluginManifest, 'contributions'> }): void;
+type Options<T> = Omit<T, 'type' | 'children'>;
+/** Optional builders. Each returns the plain protocol JSON for one node; hand-written JSON is equivalent. */
+export const ui: {
+  view(root: ViewNode, options?: { title?: TextSpan[] }): ViewContent;
+  action(actionId: string, options?: { value?: string; opens?: string }): ViewAction;
+  span(text: string, options?: Omit<ViewSpan, 'text'>): ViewSpan;
+  stack(children: ViewNode[], options?: Options<StackNode>): StackNode;
+  row(children: ViewNode[], options?: Options<RowNode>): RowNode;
+  divider(label?: string): DividerNode;
+  /** A string sets `text`; an array of spans sets `spans`. */
+  text(content: string | ViewSpan[], options?: Omit<TextNode, 'type' | 'text' | 'spans'>): TextNode;
+  badge(label: string, tone?: Tone): BadgeNode;
+  dot(tone?: Tone): DotNode;
+  progress(value: number, max: number, options?: Omit<Meter, 'value' | 'max'>): ProgressNode;
+  segments(items: Meter[]): SegmentsNode;
+  card(children: ViewNode[], options?: Options<CardNode>): CardNode;
+  stat(label: string, value: string, options?: Omit<StatNode, 'type' | 'label' | 'value'>): StatNode;
+  kv(items: KvItem[]): KvNode;
+  tabs(id: string, items: TabItem[], options?: Omit<TabsNode, 'type' | 'id' | 'items'>): TabsNode;
+  select(id: string, label: string, options: SelectOption[], extra?: Omit<SelectNode, 'type' | 'id' | 'label' | 'options'>): SelectNode;
+  table(id: string, columns: TableColumn[], rows?: TableRow[]): TableNode;
+  log(lines: string[]): LogNode;
+  /** `action` is an action object or an action id. */
+  button(label: string, action: ViewAction | string): ButtonNode;
+};
+
+/** One plugin inside a collection. The path is relative to the source root. */
+export interface PluginCollectionEntry {
+  id: string;
+  /** Relative POSIX path; "" names the source root for a single-plugin source. */
+  path: string;
+}
+/** The standard-plugins.json file at the root of a repository or npm package. */
+export interface PluginCollection {
+  schema: 1;
+  plugins: PluginCollectionEntry[];
+}
+/** File name of the collection manifest: standard-plugins.json. */
+export const COLLECTION_FILE: 'standard-plugins.json';
+export function validateCollection(value: unknown): Readonly<PluginCollection>;
+/** A collection file wins; without one, a valid package manifest makes the root one plugin at path "". */
+export function resolveCollection(source: { collection?: unknown; packageJson?: unknown }): Readonly<PluginCollection>;
+
+export type SourceKind = 'git' | 'npm';
+export type LockfileName = 'package-lock.json' | 'npm-shrinkwrap.json';
+export interface LockfileRequirement {
+  /** True when the package declares dependencies or optionalDependencies. */
+  required: boolean;
+  dependencies: readonly string[];
+  /** Lockfile names that satisfy the rule for this source kind. */
+  lockfiles: readonly LockfileName[];
+}
+/** Package name of this SDK, which a plugin lists under peerDependencies. */
+export const SDK_PACKAGE: '@standardagents/code-plugin-sdk';
+export function lockfileRequirement(input: { packageJson: unknown; sourceKind: SourceKind }): LockfileRequirement;
+export interface PublishProblem {
+  code: 'invalid_package' | 'package_private' | 'lockfile_missing' | 'sdk_dependency' | 'sdk_peer_missing' |
+    'manifest_missing' | 'invalid_manifest' | 'invalid_payload' | 'payload_too_large' | 'incompatible_version' |
+    'entry_missing' | 'id_mismatch';
+  message: string;
+}
+/** Pure checks over a package.json and the relative paths of the files that ship with it. */
+export function checkPackageForPublish(input: {
+  packageJson: unknown;
+  files: readonly string[];
+  sourceKind?: SourceKind;
+  /** False for a collection root whose package.json carries no plugin manifest. */
+  requireManifest?: boolean;
+  /** The collection entry id the manifest must match. */
+  expectedId?: string;
+}): readonly PublishProblem[];

package/src/index.mjs

@@ -1,6 +1,11 @@
-import { ensure, identifier, validateManifest, PluginError } from './manifest.mjs'
+import { PRESENTATIONS, ensure, identifier, validateManifest, PluginError } from './manifest.mjs'
+import { COLLECTION_FILE, resolveCollection, validateCollection } from './collection.mjs'
+import { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement } from './publish.mjs'
 
-export { validateManifest, PluginError }
+export { PRESENTATIONS, validateManifest, PluginError }
+export { COLLECTION_FILE, resolveCollection, validateCollection }
+export { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement }
+export { TONES, VIEW_LIMITS, ui, validateView } from './view.mjs'
 
 export function definePlugin(definition) {
   ensure(definition && identifier(definition.id) && typeof definition.activate === 'function',

package/src/internal.d.ts

@@ -30,7 +30,8 @@ export interface Runtime {
 }
 export function createRuntime(options: { manifest: PluginManifest; producer: Producer; send(frame: Envelope): void; clock?: Clock; instanceId?: string; onError?(error: Error): void }): Runtime;
 export function authorize(operation: Operation, capabilities: string[]): void;
-export function validateEnvelope(frame: unknown): Envelope;
+export function frameLimit(frame: unknown, inbound: boolean): number;
+export function validateEnvelope(frame: unknown, options?: { inbound?: boolean }): Envelope;
 export class RpcPeer {
   constructor(options: { producer: Producer; send(frame: Envelope): void; clock?: Clock; idPrefix?: string; onRequest?(operation: Operation | HostOperation, options: { signal: AbortSignal; timeoutMs: number }): Promise<Json> | Json; onSurface?(frame: Envelope): void; onError?(error: Error): void });
   request(operation: Operation | HostOperation, options?: RequestOptions): Promise<Json>;

package/src/manifest.mjs

@@ -1,14 +1,19 @@
 export const CAPABILITIES = Object.freeze(['surfaces', 'events', 'hooks', 'panes', 'projects',
   'notifications', 'url', 'fetch', 'secrets', 'webhook'])
-export const SURFACE_KINDS = Object.freeze(['section', 'slot', 'badge', 'panel', 'overlay',
+export const SURFACE_KINDS = Object.freeze(['section', 'card', 'slot', 'badge', 'panel', 'overlay',
   'menu', 'command', 'key', 'link'])
+export const PRESENTATIONS = Object.freeze(['popover', 'column', 'pane'])
 export const ANCHORS = Object.freeze(['plugins', 'machine.before', 'machine.after',
   'project.before', 'project.after', 'pane.header', 'pane.footer',
   'account', 'machine', 'project', 'pane', 'section'])
+// responseFrameBytes admits a host response carrying a 16 MiB fetch body after
+// JSON escaping (PLUGIN_FETCH_RESULT_MAX_BYTES in standardd).
 export const LIMITS = Object.freeze({ manifestBytes: 65536, frameBytes: 262144,
+  responseFrameBytes: 64 * 1024 * 1024,
   pendingRequests: 128, subscriptions: 256, schedules: 128, contributions: 256,
   queuedBytes: 4 * 1024 * 1024, hookTimeoutMs: 60000, requestTimeoutMs: 30000,
-  canvasColumns: 512, canvasRows: 256 })
+  canvasColumns: 512, canvasRows: 256, canvasHoverBytes: 512,
+  stateKeys: 256, stateValueBytes: 64 * 1024 })
 
 export class PluginError extends Error {
   constructor(code, message) { super(message); this.name = 'PluginError'; this.code = code }
@@ -71,14 +76,28 @@ export function validateManifest(value) {
     ensure(object(declaration) && identifier(declaration.id) && !ids.has(declaration.id) &&
       SURFACE_KINDS.includes(declaration.kind) && ANCHORS.includes(declaration.anchor), 'invalid_manifest', 'Invalid contribution declaration')
     ids.add(declaration.id)
+    ensure(declaration.icon === undefined || (declaration.kind === 'card' && typeof declaration.icon === 'string' &&
+      /^[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]$/u.test(declaration.icon)),
+    'invalid_manifest', 'Card icon must be one Nerd Font private-use glyph')
+    ensure(declaration.border === undefined || (typeof declaration.border === 'boolean' && declaration.kind === 'card'),
+      'invalid_manifest', 'Only sidebar cards declare a boolean border preference')
     for (const [key, choices] of Object.entries({ merge: ['by-machine', 'by-identity'], width: ['full', 'half'],
-      position: ['top', 'after-open', 'before-danger', 'bottom'] })) {
+      position: ['top', 'after-open', 'before-danger', 'bottom'], presentation: PRESENTATIONS })) {
       ensure(declaration[key] === undefined || choices.includes(declaration[key]), 'invalid_manifest', `Invalid contribution ${key}`)
     }
     for (const key of ['title', 'group', 'chord', 'pattern', 'actionId']) {
       ensure(declaration[key] === undefined || (typeof declaration[key] === 'string' && declaration[key].length <= 512),
         'invalid_manifest', `Invalid contribution ${key}`)
     }
+    ensure(declaration.opens === undefined || identifier(declaration.opens), 'invalid_manifest', 'Invalid contribution opens')
+    ensure(declaration.presentation === undefined || ['panel', 'card', 'command'].includes(declaration.kind),
+      'invalid_manifest', 'Only panels, cards, and commands declare a presentation')
+    ensure(declaration.kind !== 'card' || declaration.anchor === 'plugins', 'invalid_manifest', 'Cards use the plugins anchor')
+  }
+  for (const declaration of manifest.contributions) {
+    ensure(declaration.opens === undefined ||
+      manifest.contributions.some(item => item.id === declaration.opens && item.kind === 'panel'),
+    'invalid_manifest', 'Contribution opens must name a declared panel')
   }
   ensure(!manifest.contributions.length || manifest.capabilities.includes('surfaces'), 'invalid_manifest', 'Contributions require surfaces capability')
   ensure(manifest.configSchema === undefined || object(manifest.configSchema), 'invalid_manifest', 'Configuration schema must be an object')

package/src/protocol.mjs

@@ -8,7 +8,7 @@ export const OPERATIONS = Object.freeze({
   'pane.input': 'panes', 'pane.focus': 'panes', 'pane.wait': 'panes',
   'project.create': 'projects', 'project.remove': 'projects',
   'notification.show': 'notifications', 'url.open': 'url', fetch: 'fetch',
-  'secret.get': 'secrets', 'config.get': null, 'state.get': null, 'state.set': null,
+  'secret.get': 'secrets', 'config.get': null, 'state.get': null, 'state.set': null, 'state.keys': null,
   'context.get': null, 'popover.open': 'surfaces', 'canvas.write': 'surfaces',
   'canvas.focus': 'surfaces', 'subscription.add': null, 'subscription.remove': null,
   'health.set': null, 'webhook.ack': 'webhook',
@@ -40,8 +40,12 @@ export function validateProducer(producer) {
 export function sameProducer(a, b) {
   return a.pluginId === b.pluginId && a.machineId === b.machineId && a.epoch === b.epoch
 }
-export function validateEnvelope(frame) {
-  jsonBytes(frame)
+/** Only an inbound response may exceed the frame limit, so a fetch body can reach the plugin. */
+export function frameLimit(frame, inbound) {
+  return inbound && object(frame) && frame.kind === 'response' ? LIMITS.responseFrameBytes : LIMITS.frameBytes
+}
+export function validateEnvelope(frame, { inbound = false } = {}) {
+  jsonBytes(frame, frameLimit(frame, inbound))
   ensure(object(frame) && frame.version === RUNNER_PROTOCOL_VERSION, 'incompatible_version', 'Daemon and runner protocol versions differ')
   validateProducer(frame.producer)
   ensure(['request', 'response', 'cancel', 'surface'].includes(frame.kind), 'invalid_payload', 'Unknown runner frame kind')
@@ -115,7 +119,7 @@ export class RpcPeer {
   }
   receive(frame) {
     if (this.closed) return
-    validateEnvelope(frame)
+    validateEnvelope(frame, { inbound: true })
     ensure(sameProducer(frame.producer, this.producer), 'stale_producer', 'Frame belongs to another plugin instance')
     if (frame.kind === 'surface') { this.onSurface?.(frame); return }
     if (frame.kind === 'response') {

package/src/publish.mjs

@@ -0,0 +1,62 @@
+import { PluginError, ensure, object, validateManifest } from './manifest.mjs'
+
+export const SDK_PACKAGE = '@standardagents/code-plugin-sdk'
+export const SOURCE_KINDS = Object.freeze(['git', 'npm'])
+const LOCKFILES = Object.freeze({ git: Object.freeze(['package-lock.json', 'npm-shrinkwrap.json']), npm: Object.freeze(['npm-shrinkwrap.json']) })
+
+function names(section) { return object(section) ? Object.keys(section) : [] }
+
+/** Runtime dependencies are the ones npm installs for a consumer of the package. */
+export function runtimeDependencies(packageJson) {
+  ensure(object(packageJson), 'invalid_package', 'package.json must contain an object')
+  return [...new Set([...names(packageJson.dependencies), ...names(packageJson.optionalDependencies)])]
+}
+
+/**
+ * A plugin with runtime dependencies ships a lockfile. npm publishes
+ * npm-shrinkwrap.json and drops package-lock.json, so an npm source needs the
+ * shrinkwrap; a Git source may keep either file.
+ */
+export function lockfileRequirement({ packageJson, sourceKind }) {
+  ensure(SOURCE_KINDS.includes(sourceKind), 'invalid_source', 'Source kind must be git or npm')
+  const dependencies = runtimeDependencies(packageJson)
+  return Object.freeze({ required: dependencies.length > 0, dependencies: Object.freeze(dependencies), lockfiles: LOCKFILES[sourceKind] })
+}
+
+function normalize(path) { return path.replace(/^\.\//, '') }
+
+/**
+ * Pure publish checks for one plugin directory. `files` lists the relative
+ * POSIX paths that ship with the package. Returns a list of problems; an empty
+ * list means the package passes.
+ */
+export function checkPackageForPublish({ packageJson, files, sourceKind = 'npm', requireManifest = true, expectedId } = {}) {
+  ensure(Array.isArray(files) && files.every(file => typeof file === 'string'), 'invalid_source', 'files must list relative paths')
+  const problems = []
+  const problem = (code, message) => problems.push(Object.freeze({ code, message }))
+  if (!object(packageJson)) return Object.freeze([Object.freeze({ code: 'invalid_package', message: 'package.json must contain an object' })])
+  const present = new Set(files.map(normalize))
+  if (packageJson.private === true && sourceKind === 'npm') problem('package_private', 'package.json marks the package private, so npm refuses to publish it')
+  const requirement = lockfileRequirement({ packageJson, sourceKind })
+  if (requirement.required && !requirement.lockfiles.some(name => present.has(name))) {
+    problem('lockfile_missing', `Dependencies (${requirement.dependencies.join(', ')}) need ${requirement.lockfiles.join(' or ')} beside package.json`)
+  }
+  for (const section of ['dependencies', 'optionalDependencies']) {
+    if (names(packageJson[section]).includes(SDK_PACKAGE)) problem('sdk_dependency', `${SDK_PACKAGE} belongs under peerDependencies, not ${section}`)
+  }
+  let manifest = null
+  if (packageJson.standardPlugin === undefined) {
+    if (requireManifest) problem('manifest_missing', 'package.json has no standardPlugin manifest')
+  } else {
+    try { manifest = validateManifest(packageJson.standardPlugin) } catch (error) {
+      if (!(error instanceof PluginError)) throw error
+      problem(error.code, error.message)
+    }
+  }
+  if (manifest) {
+    if (!names(packageJson.peerDependencies).includes(SDK_PACKAGE)) problem('sdk_peer_missing', `${SDK_PACKAGE} must be listed under peerDependencies`)
+    if (!present.has(normalize(manifest.entry))) problem('entry_missing', `Entry ${manifest.entry} is not among the package files`)
+    if (expectedId !== undefined && manifest.id !== expectedId) problem('id_mismatch', `Manifest id ${manifest.id} differs from collection entry ${expectedId}`)
+  }
+  return Object.freeze(problems)
+}

package/src/row-layout.mjs

@@ -0,0 +1,29 @@
+import { ensure, object } from './manifest.mjs'
+const forbidden = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
+const validText = (v, n) => typeof v === 'string' && Buffer.byteLength(v) <= n && !forbidden.test(v)
+const only = (v, keys) => Object.keys(v).every(key => keys.includes(key))
+export function validateRowLayout(layout) {
+  const valid = object(layout) && only(layout, ['projectTint','fields'])
+    && (layout.projectTint === undefined || typeof layout.projectTint === 'boolean')
+    && Array.isArray(layout.fields) && layout.fields.length > 0 && layout.fields.length <= 32
+  ensure(valid, 'invalid_payload', 'Invalid row layout')
+  let bytes = 0
+  for (const f of layout.fields) {
+    ensure(object(f) && only(f, ['text','icon','fallback','tone','surface','bold','gap','flex','shrink'])
+      && validText(f.text, 2048)
+      && (f.icon === undefined || (typeof f.icon === 'string' && /^[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]$/u.test(f.icon)))
+      && (f.fallback === undefined || (validText(f.fallback,16) && /^[\x20-\x7e]*$/.test(f.fallback)))
+      && (f.tone === undefined || ['muted','ok','error','info','warning','project'].includes(f.tone))
+      && ['surface','bold','flex'].every(k=>f[k] === undefined || typeof f[k] === 'boolean')
+      && (f.gap === undefined || Number.isInteger(f.gap) && f.gap >= 0 && f.gap <= 8),
+      'invalid_payload', 'Invalid row field')
+    bytes += Buffer.byteLength(f.text)
+    if (f.shrink !== undefined) {
+      const s = f.shrink
+      ensure(object(s) && only(s,['priority','min','mode']) && Number.isInteger(s.priority) && s.priority>=0 && s.priority<=255
+        && Number.isInteger(s.min) && s.min>=0 && s.min<=2048 && ['start','middle','end','hide'].includes(s.mode),
+        'invalid_payload', 'Invalid row shrink policy')
+    }
+  }
+  ensure(bytes <= 8192, 'payload_too_large', 'Row layout text exceeds 8192 bytes')
+}