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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.10-rows.0",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",
@@ -16,6 +16,6 @@
     "./testing": { "types": "./src/testing.d.ts", "import": "./src/testing.mjs" }
   },
   "bin": { "standard-plugin": "./bin/standard-plugin.mjs" },
-  "files": ["src", "bin", "README.md", "LICENSE"],
+  "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,6 +417,39 @@ 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 {

package/src/index.mjs

@@ -1,10 +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/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')
+}

package/src/runtime.mjs

@@ -1,5 +1,7 @@
 import { LIMITS, PluginError, ensure, jsonBytes, validateManifest, ANCHORS, identifier, object } from './manifest.mjs'
 import { RpcPeer, authorize, realClock } from './protocol.mjs'
+import { validateView } from './view.mjs'
+import { validateRowLayout } from './row-layout.mjs'
 
 const always = Object.freeze({ kind: 'always' })
 const menuPositions = ['top', 'after-open', 'before-danger', 'bottom']
@@ -9,6 +11,43 @@ function boundedText(value, label, limit = 512) {
     !/[\u0000-\u001f\u007f]/.test(value), 'invalid_payload', `Invalid ${label}`)
   return value
 }
+const HOVER_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
+function validatePassiveText(value, limit = LIMITS.canvasHoverBytes, label = 'canvas hover') {
+  if (typeof value === 'string') {
+    ensure(value.trim().length > 0 && !HOVER_FORBIDDEN.test(value),
+      'invalid_payload', `Invalid ${label} text`)
+    ensure(Buffer.byteLength(value) <= limit,
+      'payload_too_large', `${label} text exceeds ${limit} bytes`)
+    return
+  }
+  ensure(Array.isArray(value), 'invalid_payload', `Invalid ${label} spans`)
+  ensure(value.length > 0, 'invalid_payload', `${label} spans must contain text`)
+  ensure(value.length <= 32, 'payload_too_large', `${label} spans exceed 32 spans`)
+  let text = ''
+  for (const span of value) {
+    ensure(object(span), 'invalid_payload', `Invalid ${label} span`)
+    ensure(typeof span.text === 'string' && !HOVER_FORBIDDEN.test(span.text),
+      'invalid_payload', `Invalid ${label} span text`)
+    for (const field of ['foreground', 'background']) {
+      if (span[field] !== undefined) {
+        ensure(typeof span[field] === 'string' && span[field].trim().length > 0 &&
+          !HOVER_FORBIDDEN.test(span[field]), 'invalid_payload', `Invalid ${label} span ${field}`)
+        ensure(Buffer.byteLength(span[field]) <= 64,
+          'payload_too_large', `${label} span ${field} exceeds 64 bytes`)
+      }
+    }
+    for (const field of ['bold', 'italic', 'underline']) {
+      ensure(span[field] === undefined || typeof span[field] === 'boolean',
+        'invalid_payload', `Invalid ${label} span ${field}`)
+    }
+    ensure(span.actionId === undefined, 'invalid_payload', `${label} spans cannot contain actionId`)
+    text += span.text
+  }
+  ensure(text.trim().length > 0 && !HOVER_FORBIDDEN.test(text),
+    'invalid_payload', `Invalid ${label} text`)
+  ensure(Buffer.byteLength(text) <= limit,
+    'payload_too_large', `${label} text exceeds ${limit} bytes`)
+}
 function validateEntity(entity) {
   ensure(object(entity) && entityKinds.includes(entity.kind), 'invalid_payload', 'Invalid registration entity')
   boundedText(entity.id, 'entity id', 128)
@@ -40,14 +79,49 @@ function validateCondition(condition) {
     (condition.kind === 'always' || identifier(condition.contributionId)), 'invalid_payload', 'Invalid schedule condition')
   return structuredClone(condition)
 }
-function validateContent(content) {
+const CONTENT_KINDS = ['rows', 'text', 'badge', 'canvas', 'view']
+/** Mirrors PluginSurfaceKind::accepts: canvas suits every drawn kind, view suits cards, panels and sections. */
+export function acceptsContent(kind, content) {
+  if (['menu', 'command', 'key', 'link'].includes(kind)) return false
+  if (kind === 'badge') return content.kind === 'badge'
+  if (content.kind === 'badge') return false
+  return content.kind !== 'view' || ['section', 'card', 'panel'].includes(kind)
+}
+function validateContent(content, declaration, manifest) {
+  const { kind } = declaration
+  ensure(object(content) && CONTENT_KINDS.includes(content.kind), 'invalid_payload', 'Invalid surface content')
+  ensure(acceptsContent(kind, content), 'invalid_payload', `A ${kind} contribution cannot show ${content.kind} content`)
+  // The view walk bounds depth before serialization visits the tree.
+  if (content.kind === 'view') {
+    validateView(content.root, { kind: declaration.kind, manifest })
+    if (content.title !== undefined) {
+      ensure(kind === 'card' && Array.isArray(content.title), 'invalid_payload', 'Styled titles belong to card views')
+      validatePassiveText(content.title, 512, 'card title')
+    }
+  }
+  if (content.kind === 'rows') {
+    for (const row of content.rows ?? []) if (row.layout !== undefined) {
+      ensure(['pane.header', 'pane.footer'].includes(declaration.anchor), 'invalid_payload', 'Row layouts require a pane header or footer')
+      validateRowLayout(row.layout)
+    }
+  }
   jsonBytes(content)
-  ensure(content && ['rows', 'text', 'badge', 'canvas'].includes(content.kind), 'invalid_payload', 'Invalid surface content')
   if (content.kind === 'canvas') {
-    const { columns, rows, shade = 0 } = content.canvas ?? {}
+    const { columns, rows, shade = 0, hover, themeColors } = content.canvas ?? {}
     ensure(Number.isSafeInteger(columns) && columns > 0 && columns <= LIMITS.canvasColumns &&
       Number.isSafeInteger(rows) && rows > 0 && rows <= LIMITS.canvasRows &&
       Number.isFinite(shade) && shade >= 0 && shade <= 1, 'invalid_payload', 'Invalid canvas dimensions or shade')
+    if (themeColors !== undefined) {
+      ensure(object(themeColors) && Object.keys(themeColors).length <= 32, 'invalid_payload', 'Invalid canvas theme colors')
+      for (const [index, recipe] of Object.entries(themeColors)) {
+        ensure(/^(0|[1-9][0-9]{0,2})$/.test(index) && Number(index) <= 255 && object(recipe) &&
+          Object.keys(recipe).every(key=>['source','mix','opacity'].includes(key)) &&
+          ['source','mix'].every(key=>recipe[key] === undefined || (Number.isInteger(recipe[key]) && recipe[key]>=0 && recipe[key]<16)) &&
+          Number.isFinite(recipe.opacity) && recipe.opacity>=0 && recipe.opacity<=1,
+        'invalid_payload', 'Invalid canvas theme color recipe')
+      }
+    }
+    if (hover !== undefined) validatePassiveText(hover)
   }
 }
 
@@ -102,7 +176,7 @@ export function createRuntime({ manifest: input, producer, send, clock = realClo
     const replace = content => {
       active()
       ensure(!disposed, 'disposed', 'Contribution publisher is disposed')
-      if (content !== null) validateContent(content)
+      if (content !== null) validateContent(content, declaration, manifest)
       peer.transmit(peer.frame('surface', { key, sequence: String(++sequence), content }))
     }
     const publisher = { replace, clear: () => replace(null), dispose() {
@@ -292,7 +366,7 @@ export function createRuntime({ manifest: input, producer, send, clock = realClo
   const method = op => (args, options) => request(op, args, options)
   const context = Object.freeze({
     manifest, producer: peer.producer, signal: lifetime.signal, request,
-    ...Object.fromEntries(['section', 'slot', 'badge', 'panel', 'overlay'].map(kind => [kind,
+    ...Object.fromEntries(['section', 'card', 'slot', 'badge', 'panel', 'overlay'].map(kind => [kind,
       (id, entity) => publish(kind, id, entity).publisher])),
     canvas(id, spec, entity) {
       const { publisher, key } = publish(null, id, entity)
@@ -321,7 +395,8 @@ export function createRuntime({ manifest: input, producer, send, clock = realClo
     secrets: Object.freeze({ get: (name, options) => request('secret.get', { name }, options) }),
     config: Object.freeze({ get: options => request('config.get', {}, options) }),
     state: Object.freeze({ get: (key, options) => request('state.get', { key }, options),
-      set: (key, value, options) => request('state.set', { key, value }, options) }),
+      set: (key, value, options) => request('state.set', { key, value }, options),
+      keys: options => request('state.keys', {}, options) }),
     context: Object.freeze({ get: options => request('context.get', {}, options) }),
     popover: Object.freeze({ open: method('popover.open') }),
     health: Object.freeze({ set: method('health.set') }),

package/src/testing.d.ts

@@ -1,4 +1,4 @@
-import type { Json, ManifestInput, OperationMap, PluginContext, PluginDefinition, Condition, RequestOptions } from './index.js';
+import type { Json, ManifestInput, OperationMap, PluginContext, PluginDefinition, Condition, RequestOptions, EntityRef, SurfaceContent } from './index.js';
 import type { Envelope } from './internal.js';
 export interface Harness {
   context: PluginContext;
@@ -11,6 +11,8 @@ export interface Harness {
   emit(kind: string, name: string, event: Json, options?: RequestOptions): Promise<Json[]>;
   visibility(conditions: Condition[]): Promise<Json>;
   receive(frame: Envelope): void;
+  /** The current content of a published contribution, or undefined when it is clear. */
+  surface(id: string, entity?: EntityRef): SurfaceContent | undefined;
   drainTrace(): unknown[];
   readonly resources: { timers: number; subscriptions: number; surfaces: number; disposed: boolean };
   dispose(): Promise<void>;