@standardagents/code-plugin-sdk 1.0.0-alpha.1 → 1.0.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",

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 boxed card in the sidebar under the `plugins` anchor. */
+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' |
@@ -19,6 +22,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 {
@@ -72,9 +79,11 @@ 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` is also the intrinsic width of a card, column, or plugin pane that shows the canvas. */
 export interface CanvasSpec {
   columns: number;
   rows: number;
@@ -82,7 +91,57 @@ export interface CanvasSpec {
   shade?: number;
   captureInput?: boolean;
 }
-export type SurfaceContent = NativeContent | { kind: 'canvas'; canvas: CanvasSpec };
+export type CanvasContent = { kind: 'canvas'; canvas: CanvasSpec };
+
+/** 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 }
+
+/** 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 +165,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>;
@@ -186,8 +246,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 +267,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;
@@ -262,6 +325,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; 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): 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,11 +1,15 @@
 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 })
@@ -72,13 +76,22 @@ export function validateManifest(value) {
       SURFACE_KINDS.includes(declaration.kind) && ANCHORS.includes(declaration.anchor), 'invalid_manifest', 'Invalid contribution declaration')
     ids.add(declaration.id)
     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

@@ -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/runtime.mjs

@@ -1,5 +1,6 @@
 import { LIMITS, PluginError, ensure, jsonBytes, validateManifest, ANCHORS, identifier, object } from './manifest.mjs'
 import { RpcPeer, authorize, realClock } from './protocol.mjs'
+import { validateView } from './view.mjs'
 
 const always = Object.freeze({ kind: 'always' })
 const menuPositions = ['top', 'after-open', 'before-danger', 'bottom']
@@ -40,9 +41,21 @@ 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 })
   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 ?? {}
     ensure(Number.isSafeInteger(columns) && columns > 0 && columns <= LIMITS.canvasColumns &&
@@ -102,7 +115,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 +305,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)

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>;

package/src/testing.mjs

@@ -88,6 +88,13 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
     },
     visibility: conditions => host.request({ op: 'runtime.visibility', args: { conditions } }),
     receive: frame => runtime.receive(frame),
+    /** The current content of a published contribution, or undefined when it is clear. */
+    surface(id, entity) {
+      const declaration = manifest.contributions.find(item => item.id === id)
+      if (!declaration) return undefined
+      const key = { contributionId: id, anchor: declaration.anchor, ...(entity ? { entity } : {}) }
+      return structuredClone(surfaces.get(JSON.stringify(key))?.content)
+    },
     drainTrace() { return trace.splice(0) },
     get resources() { return { timers: timers.size, subscriptions: subscriptions.size, surfaces: surfaces.size, disposed } },
     async dispose() {

package/src/view.mjs

@@ -0,0 +1,246 @@
+import { LIMITS, ensure, identifier, jsonBytes, object } from './manifest.mjs'
+
+// Mirrors crates/standard-protocol/src/plugin_view.rs. The host applies the
+// same bounds; checking here reports a mistake at the replace() call.
+export const VIEW_LIMITS = Object.freeze({ depth: 8, nodes: 4096, tableRows: 512, tableColumns: 12,
+  cardLines: 6, actionValueBytes: 512 })
+export const TONES = Object.freeze(['ok', 'info', 'warn', 'error', 'muted', 'accent', 'pending', 'bright'])
+const WEIGHTS = ['normal', 'bold', 'dim']
+const ALIGNS = ['start', 'center', 'end']
+// C0, DEL, C1, and the bidirectional formatting characters that can reorder terminal output.
+const FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
+
+const invalid = message => ensure(false, 'invalid_payload', message)
+function text(value, field) {
+  if (typeof value !== 'string') invalid(`Plugin view ${field} must be a string`)
+  ensure(!FORBIDDEN.test(value), 'invalid_payload', 'Plugin view text contains a control or bidirectional character')
+}
+function optionalText(value, field) { if (value !== undefined) text(value, field) }
+function choice(value, choices, field) {
+  ensure(value === undefined || choices.includes(value), 'invalid_payload', `Invalid plugin view ${field}`)
+}
+function tone(value) { choice(value, TONES, 'tone') }
+function integer(value, max, field) {
+  ensure(value === undefined || (Number.isInteger(value) && value >= 0 && value <= max), 'invalid_payload', `Invalid plugin view ${field}`)
+}
+function flag(value, field) { ensure(value === undefined || typeof value === 'boolean', 'invalid_payload', `Invalid plugin view ${field}`) }
+function number(value) {
+  ensure(typeof value === 'number' && Number.isFinite(value), 'invalid_payload', 'Plugin view number is not finite')
+}
+function list(value, field, optional = false) {
+  if (optional && value === undefined) return []
+  ensure(Array.isArray(value), 'invalid_payload', `Plugin view ${field} must be an array`)
+  return value
+}
+function entries(value, field, optional, check) {
+  for (const item of list(value, field, optional)) {
+    ensure(object(item), 'invalid_payload', `Plugin view ${field} must contain objects`)
+    check(item)
+  }
+}
+function spans(value, optional) {
+  entries(value, 'spans', optional, span => {
+    text(span.text, 'span text')
+    tone(span.tone)
+    choice(span.weight, WEIGHTS, 'weight')
+    flag(span.mono, 'mono')
+  })
+}
+function action(value, optional = true) {
+  if (optional && value === undefined) return
+  ensure(object(value), 'invalid_payload', 'Plugin view action must be an object')
+  text(value.actionId, 'action id')
+  optionalText(value.value, 'action value')
+  optionalText(value.opens, 'action opens')
+}
+function meter(item) {
+  number(item.value)
+  number(item.max)
+  tone(item.tone)
+  optionalText(item.label, 'label')
+}
+function children(node, depth, count) {
+  for (const child of list(node.children, 'children', true)) walk(child, depth + 1, count)
+}
+
+const NODES = {
+  stack(node, depth, count) { integer(node.gap, 255, 'gap'); children(node, depth, count) },
+  row(node, depth, count) { choice(node.align, ALIGNS, 'align'); children(node, depth, count) },
+  divider(node) { optionalText(node.label, 'label') },
+  text(node) {
+    optionalText(node.text, 'text')
+    spans(node.spans, true)
+    tone(node.tone)
+    choice(node.weight, WEIGHTS, 'weight')
+    flag(node.mono, 'mono')
+  },
+  badge(node) { text(node.label, 'label'); tone(node.tone) },
+  dot(node) { tone(node.tone) },
+  progress: meter,
+  segments(node) { entries(node.items, 'items', false, meter) },
+  card(node, depth, count) { optionalText(node.title, 'title'); tone(node.tone); children(node, depth, count) },
+  stat(node) {
+    text(node.label, 'label')
+    text(node.value, 'value')
+    tone(node.tone)
+    optionalText(node.hint, 'hint')
+  },
+  kv(node) {
+    entries(node.items, 'items', false, item => {
+      text(item.label, 'label')
+      text(item.value, 'value')
+      flag(item.mono, 'mono')
+      flag(item.copy, 'copy')
+    })
+  },
+  tabs(node) {
+    text(node.id, 'id')
+    optionalText(node.filters, 'filters')
+    action(node.action)
+    entries(node.items, 'items', false, item => {
+      text(item.id, 'id')
+      text(item.label, 'label')
+      optionalText(item.sublabel, 'sublabel')
+      tone(item.tone)
+      integer(item.count, 0xffffffff, 'count')
+      optionalText(item.tag, 'tag')
+    })
+  },
+  select(node) {
+    text(node.id, 'id')
+    text(node.label, 'label')
+    optionalText(node.filters, 'filters')
+    action(node.action)
+    entries(node.options, 'options', false, option => {
+      text(option.id, 'id')
+      text(option.label, 'label')
+      optionalText(option.group, 'group')
+      integer(option.count, 0xffffffff, 'count')
+      optionalText(option.tag, 'tag')
+    })
+  },
+  table(node, depth, count) {
+    const columns = list(node.columns, 'columns')
+    const rows = list(node.rows, 'rows', true)
+    ensure(columns.length <= VIEW_LIMITS.tableColumns, 'invalid_payload', 'Plugin table has more than 12 columns')
+    ensure(rows.length <= VIEW_LIMITS.tableRows, 'invalid_payload', 'Plugin table has more than 512 rows')
+    text(node.id, 'id')
+    entries(columns, 'columns', false, column => {
+      text(column.id, 'column id')
+      optionalText(column.label, 'column label')
+      if (column.width !== 'fill') integer(column.width, 0xffff, 'column width')
+      integer(column.maxWidth, 0xffff, 'column maxWidth')
+      choice(column.align, ALIGNS, 'align')
+      integer(column.priority, 255, 'column priority')
+    })
+    entries(rows, 'rows', false, row => {
+      text(row.id, 'row id')
+      tone(row.tone)
+      spans(row.note, true)
+      for (const tag of list(row.tags, 'tags', true)) text(tag, 'tag')
+      action(row.action)
+      ensure(row.cells === undefined || object(row.cells), 'invalid_payload', 'Plugin table cells must be an object')
+      for (const [column, cell] of Object.entries(row.cells ?? {})) {
+        text(column, 'cell column')
+        walk(cell, depth + 1, count)
+      }
+    })
+  },
+  log(node) { for (const line of list(node.lines, 'lines')) text(line, 'log line') },
+  button(node) { text(node.label, 'label'); action(node.action, false) },
+}
+
+function walk(node, depth, count) {
+  ensure(depth <= VIEW_LIMITS.depth, 'invalid_payload', 'Plugin view nests deeper than 8 nodes')
+  ensure(++count.nodes <= VIEW_LIMITS.nodes, 'invalid_payload', 'Plugin view has more than 4096 nodes')
+  ensure(object(node) && typeof node.type === 'string', 'invalid_payload', 'Plugin view node requires a type')
+  // A node type this SDK does not know draws nothing on hosts that do not know it either.
+  if (Object.hasOwn(NODES, node.type)) NODES[node.type](node, depth, count)
+}
+
+// The daemon checks below mirror crates/standardd/src/plugin_view_content.rs.
+
+/** Visits the actions a viewer can activate, in the nodes the daemon searches. */
+function visitActions(node, visit) {
+  switch (node.type) {
+    case 'stack': case 'row': case 'card':
+      for (const child of node.children ?? []) visitActions(child, visit)
+      break
+    case 'button': visit(node.action); break
+    case 'tabs': case 'select': if (node.action !== undefined) visit(node.action); break
+    case 'table':
+      for (const row of node.rows ?? []) {
+        if (row.action !== undefined) visit(row.action)
+        for (const cell of Object.values(row.cells ?? {})) visitActions(cell, visit)
+      }
+      break
+  }
+}
+
+const ONE_LINE = ['text', 'badge', 'dot', 'progress', 'segments', 'stat', 'divider']
+const PANEL_ONLY = ['card', 'kv', 'tabs', 'select', 'table', 'log', 'button']
+/** Cards hold one-line summaries arranged by stacks and rows; unknown nodes draw nothing. */
+function cardLines(node) {
+  if (node.type === 'stack') {
+    const children = node.children ?? []
+    return children.reduce((total, child) => total + cardLines(child), (node.gap ?? 0) * Math.max(children.length - 1, 0))
+  }
+  if (node.type === 'row') return (node.children ?? []).reduce((tallest, child) => Math.max(tallest, cardLines(child)), 0)
+  if (ONE_LINE.includes(node.type)) return 1
+  ensure(!PANEL_ONLY.includes(node.type), 'invalid_payload', `A card view cannot contain a ${node.type} node`)
+  return 0
+}
+
+/**
+ * Throws a PluginError when a view tree breaks a protocol bound or a rule the
+ * serving daemon applies. `kind: 'card'` adds the card rules, and `manifest`
+ * requires every action `opens` to name one of its panels.
+ */
+export function validateView(root, { kind, manifest } = {}) {
+  walk(root, 1, { nodes: 0 })
+  jsonBytes(root, LIMITS.frameBytes)
+  visitActions(root, action => {
+    ensure(identifier(action.actionId), 'invalid_payload', 'Plugin view action id must be a plugin identifier')
+    ensure(action.value === undefined || Buffer.byteLength(action.value) <= VIEW_LIMITS.actionValueBytes,
+      'payload_too_large', 'Plugin view action value exceeds 512 bytes')
+    ensure(action.opens === undefined || identifier(action.opens), 'invalid_payload', 'Plugin view action opens must be a plugin identifier')
+    ensure(action.opens === undefined || !manifest ||
+      manifest.contributions.some(item => item.id === action.opens && item.kind === 'panel'),
+    'invalid_payload', 'Plugin view action opens must name a declared panel')
+  })
+  if (kind === 'card') {
+    ensure(cardLines(root) <= VIEW_LIMITS.cardLines, 'payload_too_large', 'A card view is taller than 6 lines')
+  }
+}
+
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined))
+}
+const node = (type, fields) => compact({ type, ...fields })
+
+/** Optional builders. Each returns the plain protocol JSON for one node. */
+export const ui = Object.freeze({
+  view: root => ({ kind: 'view', root }),
+  action: (actionId, { value, opens } = {}) => compact({ actionId, value, opens }),
+  span: (value, { tone, weight, mono } = {}) => compact({ text: value, tone, weight, mono }),
+  stack: (items, { gap } = {}) => node('stack', { gap, children: items }),
+  row: (items, { align } = {}) => node('row', { children: items, align }),
+  divider: label => node('divider', { label }),
+  /** A string sets `text`; an array of spans sets `spans`. */
+  text: (content, { tone, weight, mono } = {}) =>
+    node('text', { ...(Array.isArray(content) ? { spans: content.map(compact) } : { text: content }), tone, weight, mono }),
+  badge: (label, tone) => node('badge', { label, tone }),
+  dot: tone => node('dot', { tone }),
+  progress: (value, max, { tone, label } = {}) => node('progress', { value, max, tone, label }),
+  segments: items => node('segments', { items: items.map(compact) }),
+  card: (items, { title, tone } = {}) => node('card', { title, tone, children: items }),
+  stat: (label, value, { tone, hint } = {}) => node('stat', { label, value, tone, hint }),
+  kv: items => node('kv', { items: items.map(compact) }),
+  tabs: (id, items, { filters, action } = {}) => node('tabs', { id, items: items.map(compact), filters, action }),
+  select: (id, label, options, { filters, action } = {}) =>
+    node('select', { id, label, options: options.map(compact), filters, action }),
+  table: (id, columns, rows = []) => node('table', { id, columns: columns.map(compact), rows: rows.map(compact) }),
+  log: lines => node('log', { lines }),
+  /** `action` is an action object or an action id. */
+  button: (label, action) => node('button', { label, action: typeof action === 'string' ? { actionId: action } : action }),
+})