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

package/README.md

@@ -54,6 +54,89 @@ Plugins retain Node access to files, networking and subprocesses under the user'
 Worker threads provide JavaScript fault isolation.
 Memory exhaustion outside V8 limits and native crashes can affect the runner process.
 
+## Collections
+
+A plugin installs from a Git repository or an npm package. One source holds
+one plugin or a collection of plugins.
+
+A collection lists its plugins in `standard-plugins.json` at the root of the
+repository or package:
+
+```json
+{
+  "schema": 1,
+  "plugins": [
+    { "id": "builds-monitor", "path": "builds-monitor" },
+    { "id": "pong", "path": "games/pong" }
+  ]
+}
+```
+
+`schema` is `1`. `plugins` holds 1 to 256 entries. Each `id` follows the
+plugin id pattern of the manifest and equals the `standardPlugin.id` in that
+entry's `package.json`. Each `path` is a relative POSIX path of at most 512
+characters with no leading slash, no backslash, and no empty, `.`, or `..`
+segment. Ids and paths are unique within one collection. An installer
+selects one entry with `--plugin <id>`.
+
+A root without `standard-plugins.json` is a single plugin when its
+`package.json` carries a valid `standardPlugin` manifest. Discovery treats it
+as one entry at path `""`.
+
+`validateCollection(value)` checks a parsed collection file and returns a
+frozen `PluginCollection`. `resolveCollection({ collection, packageJson })`
+applies the single-plugin fallback. `COLLECTION_FILE` names the file.
+
+## Dependencies
+
+A plugin with `dependencies` or `optionalDependencies` ships a lockfile
+beside its `package.json`, so every machine installs the same dependency
+tree. The installer refuses a plugin with dependencies and no lockfile.
+
+For an npm package the lockfile is `npm-shrinkwrap.json`. npm never
+publishes `package-lock.json`; `npm shrinkwrap` converts an existing
+`package-lock.json` into `npm-shrinkwrap.json`, and npm includes that file
+when it publishes the package. For a Git repository either
+`package-lock.json` or `npm-shrinkwrap.json` satisfies the rule.
+
+The SDK belongs under `peerDependencies`, with a `devDependencies` copy for
+the plugin's own tests. Inside Standard Code the bundled runtime supplies it.
+
+`lockfileRequirement({ packageJson, sourceKind })` returns whether the rule
+applies and which lockfile names satisfy it for `"npm"` or `"git"`.
+`checkPackageForPublish({ packageJson, files })` reports problems as
+`{ code, message }` objects: a missing lockfile, the SDK under
+`dependencies`, a missing peer declaration, a missing or invalid manifest, an
+entry outside the package files, or an id that differs from the collection
+entry. Both helpers are pure; they read no files.
+
+In a collection, each plugin directory holds its own `package.json` and its
+own lockfile.
+
+## Publishing a plugin
+
+The package installs a `standard-plugin` command for authoring.
+
+```sh
+npx standard-plugin check
+npx standard-plugin pack
+npm publish
+```
+
+`check [dir] [--source npm|git]` reads `package.json`, the optional
+`standard-plugins.json`, every collection entry's `package.json`, and the
+lockfiles. It prints each problem as `<path>: <code>: <message>` and exits
+with status 1 when it finds one. `--source git` applies the Git lockfile
+rule; the default is `npm`.
+
+`pack [dir]` runs `check`. When a plugin has dependencies and no
+`npm-shrinkwrap.json`, it runs `npm shrinkwrap`, which converts
+`package-lock.json`, and asks you to commit the new file. It then runs
+`npm pack --dry-run` and prints the files that npm will publish.
+
+The command is authoring tooling. The SDK entry never imports it, and a
+plugin never depends on it at run time.
+
 ## Testing
 
 `@standardagents/code-plugin-sdk/testing` exports `createHarness`.
@@ -66,7 +149,8 @@ The harness starts no subprocesses.
 ## Supported interface
 
 The public interface is the package's default export, its `testing` export,
-and the declarations in `src/index.d.ts` and `src/testing.d.ts`.
+the declarations in `src/index.d.ts` and `src/testing.d.ts`, and the
+`standard-plugin` command's `check` and `pack` behavior.
 
 The harness records the frames that the SDK runtime exchanges with its host,
 and `harness.receive` accepts such a frame. That wire protocol between the

package/bin/standard-plugin.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Authoring tool for plugin packages. The SDK entry never imports this file.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { COLLECTION_FILE, PluginError, checkPackageForPublish, validateCollection } from '../src/index.mjs'
+
+const USAGE = `usage: standard-plugin check [dir] [--source npm|git]
+       standard-plugin pack [dir]
+
+check  validates package.json, ${COLLECTION_FILE}, each collection entry, and lockfiles
+pack   runs check, creates npm-shrinkwrap.json when dependencies need one, then runs npm pack --dry-run`
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git'])
+const FILE_LIMIT = 50000
+
+function readJson(path) {
+  let text
+  try { text = readFileSync(path, 'utf8') } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+  return JSON.parse(text)
+}
+
+/** Relative POSIX paths of regular files under root, without following links. */
+function listFiles(root) {
+  const files = []
+  const pending = ['']
+  while (pending.length) {
+    const directory = pending.pop()
+    for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+      const path = directory ? `${directory}/${entry.name}` : entry.name
+      if (entry.isDirectory()) { if (!IGNORED_DIRECTORIES.has(entry.name)) pending.push(path) }
+      else if (entry.isFile()) files.push(path)
+      if (files.length > FILE_LIMIT) throw new Error(`More than ${FILE_LIMIT} files under ${root}`)
+    }
+  }
+  return files
+}
+
+function tryJson(root, name, problems, location) {
+  try { return readJson(join(root, name)) } catch (error) {
+    problems.push({ location, code: 'invalid_json', message: `${name}: ${error.message}` })
+    return undefined
+  }
+}
+
+function collect(problems, location, list) {
+  for (const problem of list) problems.push({ location, ...problem })
+}
+
+/** Checks one source directory. Returns problems with the directory each one belongs to. */
+function checkDirectory(root, { sourceKind = 'npm' } = {}) {
+  const problems = []
+  const files = listFiles(root)
+  const packageJson = tryJson(root, 'package.json', problems, '.')
+  const collectionInput = tryJson(root, COLLECTION_FILE, problems, '.')
+  if (collectionInput === undefined) {
+    if (packageJson === undefined) problems.push({ location: '.', code: 'package_missing', message: `package.json or ${COLLECTION_FILE} is required` })
+    else collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind }))
+    return problems
+  }
+  let collection
+  try { collection = validateCollection(collectionInput) } catch (error) {
+    if (!(error instanceof PluginError)) throw error
+    problems.push({ location: '.', code: error.code, message: `${COLLECTION_FILE}: ${error.message}` })
+    return problems
+  }
+  if (packageJson !== undefined) collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind, requireManifest: false }))
+  else if (sourceKind === 'npm') problems.push({ location: '.', code: 'package_missing', message: 'an npm package needs a root package.json' })
+  for (const entry of collection.plugins) {
+    const entryPackage = tryJson(join(root, entry.path), 'package.json', problems, entry.path)
+    if (entryPackage === undefined) {
+      if (!problems.some(problem => problem.location === entry.path)) {
+        problems.push({ location: entry.path, code: 'package_missing', message: `collection entry ${entry.id} has no package.json` })
+      }
+      continue
+    }
+    const prefix = `${entry.path}/`
+    const entryFiles = files.filter(file => file.startsWith(prefix)).map(file => file.slice(prefix.length))
+    collect(problems, entry.path, checkPackageForPublish({ packageJson: entryPackage, files: entryFiles, sourceKind, expectedId: entry.id }))
+  }
+  return problems
+}
+
+function report(problems) {
+  for (const problem of problems) console.log(`${problem.location}: ${problem.code}: ${problem.message}`)
+  console.log(problems.length ? `${problems.length} problem${problems.length === 1 ? '' : 's'}` : 'ok')
+}
+
+function npm(args, cwd) {
+  const result = spawnSync('npm', args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function parse(argv) {
+  const [command, ...rest] = argv
+  const options = { directory: '.', sourceKind: 'npm' }
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index]
+    if (argument === '--source') {
+      options.sourceKind = rest[++index]
+      if (!['npm', 'git'].includes(options.sourceKind)) throw new Error('--source takes npm or git')
+    } else if (argument.startsWith('-')) throw new Error(`unknown option ${argument}`)
+    else options.directory = argument
+  }
+  return { command, ...options, directory: resolve(options.directory) }
+}
+
+function check(options) {
+  const problems = checkDirectory(options.directory, options)
+  report(problems)
+  return problems.length ? 1 : 0
+}
+
+function pack(options) {
+  if (options.sourceKind !== 'npm') throw new Error('pack checks an npm package; --source git does not apply')
+  let problems = checkDirectory(options.directory, options)
+  const missing = problems.filter(problem => problem.code === 'lockfile_missing')
+  for (const problem of missing) {
+    const directory = resolve(options.directory, problem.location)
+    if (!existsSync(join(directory, 'package-lock.json'))) {
+      console.log(`${problem.location}: run npm install first so npm shrinkwrap has a package-lock.json to convert`)
+      continue
+    }
+    console.log(`${problem.location}: creating npm-shrinkwrap.json from package-lock.json`)
+    const status = npm(['shrinkwrap'], directory)
+    if (status !== 0) return status
+    console.log(`${problem.location}: commit npm-shrinkwrap.json; npm publishes it with the package`)
+  }
+  if (missing.length) problems = checkDirectory(options.directory, options)
+  report(problems)
+  if (problems.length) return 1
+  return npm(['pack', '--dry-run'], options.directory)
+}
+
+function main(argv) {
+  let options
+  try { options = parse(argv) } catch (error) { console.error(error.message); console.error(USAGE); return 2 }
+  try {
+    if (options.command === 'check') return check(options)
+    if (options.command === 'pack') return pack(options)
+  } catch (error) { console.error(`standard-plugin: ${error.message}`); return 2 }
+  console.error(USAGE)
+  return 2
+}
+
+process.exitCode = main(process.argv.slice(2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "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", "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 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,3 +325,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; 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 {
+  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,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/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/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 }),
+})