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

package/REFERENCE.md

@@ -0,0 +1,536 @@
+# Plugin SDK reference
+
+The public declarations live in
+`packages/plugin-sdk/src/index.d.ts`. This page groups the stable concepts for
+plugin authors.
+
+The bundled SDK and the npm package use the same public declarations. This
+reference describes SDK `1.0.0-alpha.5-usage.0`. Plugins should declare the
+version published for their product build in both `peerDependencies` and
+`devDependencies`; the manifest `apiVersion` remains `1`.
+
+## Definition and context
+
+`definePlugin({ id, activate })` creates the default plugin export. The
+activation function receives a `PluginContext` with the immutable manifest,
+producer identity, abort signal, typed request function, surface publishers,
+subscriptions, schedules, lifecycle operations, and host capabilities.
+
+`section`, `card`, `slot`, `badge`, `panel`, and `overlay` each return a
+publisher for a declared contribution of that kind; `canvas(id, spec)`
+returns a canvas publisher for any declaration that draws content.
+Publishers expose `replace(content)` and `clear()`. A canvas publisher also
+exposes `write(ansi)` and `focus(capture)`. Registration objects return a
+disposable subscription. Key registrations support one pending chord update.
+
+## Manifest
+
+`PluginManifest` contains `apiVersion`, `id`, `name`, `version`, `entry`,
+`singleton`, `order`, `capabilities`, `contributions`, and `hookTimeoutMs`.
+Contribution declarations contain a stable ID, surface kind, anchor, title,
+merge mode, width, menu position, palette group, chord, URL pattern, and
+action ID as appropriate.
+
+A `card` declaration draws a sidebar card. Its optional `border` boolean
+defaults to `true`. Set `border: false` for a borderless group: the host
+retains the author title, content padding, focus indication, and activation
+behavior, and removes the outline and bottom border row. This preference
+is declared by each plugin on its own cards; other surface kinds reject it.
+The nested view node named `card` is a separate content element.
+
+`validateManifest`
+refuses a card whose anchor is not `plugins`. Two optional fields control
+panels:
+
+- `presentation` is `popover` (the default), `column`, or `pane`. On a panel
+  it sets how the panel opens. On a card or command it sets how the panel
+  named by `opens` opens. Other kinds cannot declare a presentation.
+- `opens` is the ID of a panel that a card or command opens when the viewer
+  activates it. `validateManifest` refuses an `opens` value that does not name
+  a declared panel.
+
+`PRESENTATIONS` lists the accepted presentation values.
+
+Account-level sidebar cards prefer a live producer on the viewing machine.
+This keeps card actions and attached panels local to that viewer. If no live
+local producer exists, the host uses its deterministic remote-source fallback;
+remote source authority restrictions still apply. Plugins aggregate shared
+account data themselves through the public state API.
+
+An anchor determines the entity that owns a contribution. Machine anchors use
+a machine entity, project anchors use a project entity, and pane anchors use a
+pane entity. The `plugins` and `account` anchors are account-level surfaces;
+`section` may use a section entity. A machine contribution normally omits its
+generation so the host resolves the current generation. The host rejects a
+contribution whose entity belongs to another machine or project.
+
+## Sources and collections
+
+A plugin installs from a Git repository or an npm package. A source is one
+plugin or a collection. `PluginCollection` is the parsed
+`standard-plugins.json` at the source root: `schema` is `1` and `plugins`
+holds 1 to 256 `PluginCollectionEntry` values. Each entry has an `id` in the
+plugin id pattern and a relative POSIX `path` with no leading slash, no
+backslash, and no empty, `.`, or `..` segment. Ids and paths are unique.
+`standard plugin install <source> --plugin <id>` selects one entry.
+
+`validateCollection(value)` returns a frozen collection or throws a
+`PluginError` with code `invalid_collection`.
+`resolveCollection({ collection, packageJson })` returns the validated
+collection when a file is present; otherwise a valid `standardPlugin`
+manifest in `packageJson` yields one entry at path `""`. `COLLECTION_FILE`
+is the file name.
+
+## Dependencies and publishing
+
+A plugin with `dependencies` or `optionalDependencies` ships a lockfile
+beside its `package.json`. `lockfileRequirement({ packageJson, sourceKind })`
+returns `{ required, dependencies, lockfiles }`: for `"npm"` the accepted
+name is `npm-shrinkwrap.json`; for `"git"` it is `package-lock.json` or
+`npm-shrinkwrap.json`. The SDK itself stays under `peerDependencies`.
+
+`checkPackageForPublish({ packageJson, files, sourceKind, requireManifest,
+expectedId })` is pure and returns `PublishProblem` values with a `code` and
+a `message`. Codes cover a missing lockfile, the SDK under `dependencies`, a
+missing peer declaration, a missing or invalid manifest, an entry absent from
+`files`, an id that differs from `expectedId`, and a private package.
+
+The package's `standard-plugin` command applies these rules to a directory:
+`check [dir] [--source npm|git]` prints problems and exits with status 1
+when it finds one, and `pack [dir]` runs `check`, runs `npm shrinkwrap` when
+dependencies lack `npm-shrinkwrap.json`, and then prints the
+`npm pack --dry-run` file list.
+
+## Content
+
+Native content uses rows, styled text, or badges. A row can carry an identity,
+provider revision, styled spans, an action ID, a meter, spark samples, and a
+divider marker. Canvas content declares canonical columns, rows, transparency,
+shade, input capture, and optional hover metadata.
+
+View content, `{ kind: 'view', root }`, is a tree of host-rendered nodes. The
+host draws it with the viewer's theme, symbols, focus, and hit testing.
+
+Each contribution kind accepts a fixed set of content kinds, and
+`replace(content)` throws a `PluginError` for any other pairing:
+
+| Contribution | Rows, text | Canvas | View | Badge |
+|---|---|---|---|---|
+| `section`, `card`, `panel` | yes | yes | yes | no |
+| `slot`, `overlay` | yes | yes | no | no |
+| `badge` | no | no | no | yes |
+| `menu`, `command`, `key`, `link` | no | no | no | no |
+
+### Custom interfaces with canvas
+
+Canvas is the fully supported path for a plugin that draws its own
+interface. A section, card, or panel can show a canvas in every
+presentation: a sidebar card, a pop-over, a column, or a plugin pane.
+`canvas.columns` is the intrinsic width that the host uses to size the card,
+column, or plugin pane. The view helpers below are optional, and a plugin can
+combine a view card with a canvas panel.
+
+`write(ansi)` draws into a grid that the host keeps for the canvas. The grid
+keeps its cells between writes, so a plugin that redraws a whole frame starts
+it with `\x1b[2J\x1b[H`. The host honours these sequences:
+
+- SGR (`CSI … m`): reset, bold, dim, italic, underline, inverse, hidden,
+  strikethrough, their resets, the 8 and 16 colour forms, and `38`/`48`
+  with `5;n` or `2;r;g;b` (colon forms too).
+- Cursor positioning: `CUP`/`HVP` (`H`, `f`), `CUU`, `CUD`, `CUF`, `CUB`,
+  `CNL`, `CPL`, `CHA`, and `VPA`, clamped to the canvas.
+- Erasing: `ED` (`J`), `EL` (`K`), and `ECH` (`X`), with the current
+  background colour.
+- Carriage return, line feed (which also returns to the first column),
+  tab, and backspace.
+
+The host drops every other escape and control sequence, including private
+modes, OSC (titles, hyperlinks, clipboard), DCS, APC, PM, and SOS, and every
+C0, C1, and bidirectional formatting character. Text past the right edge is
+clipped, and a line feed on the last row stays on that row: a canvas never
+wraps or scrolls. Wide characters take two cells. Cells in default colours
+take the viewer's theme, and a blank default cell shows the surface under the
+canvas.
+
+`hover` is an optional one-line string or an array of styled `TextSpan` values.
+The string must be non-empty after trimming, fit within 512 UTF-8 bytes, and
+contain no C0, C1, DEL, or bidirectional formatting character. Styled hover
+values contain at most 32 spans whose joined text follows the same bounds and
+must be non-empty. Span styling supports `foreground`, `background`, `bold`,
+`italic`, and `underline`; `actionId` is rejected because hover text is
+passive. `Canvas.replace` publishes the canvas metadata, so a plugin can update
+the hover text with another `replace` call while retaining the same canvas
+grid.
+
+On the current frontend, live canvases in `machine.before` and
+`machine.after` slots are hover targets. The viewer waits 300 milliseconds
+while the pointer remains over the canvas, then shows the text in a single
+line owned by the host. Leaving the canvas dismisses it immediately. Hover
+does not focus the canvas or change its geometry. The dwell timer and pointer
+state belong to each viewer, so remote viewers can see hover text for a
+machine slot independently.
+Hover overlays for these machine slots use the same 22% sidebar machine colour
+blend as the machine name bar over the viewer's background.
+
+`focus(true)` asks for keyboard input and needs `captureInput: true` in the
+canvas spec. While the canvas is shown in a pop-over, column, or plugin pane
+and holds focus, the host sends every key except Escape and
+Control, Alt, or Super chords to `onInput(id, handler)` subscriptions as
+`{ kind: 'key', key, phase, contributionId, entity? }`. `key` is the typed
+character or one of `up`, `down`, `left`, `right`, `enter`, `tab`,
+`backspace`, `delete`, `escape`, `space`, `home`, `end`, `pageup`,
+`pagedown`, or `f1`-`f12`; `phase` is `press` or `repeat`. When the canvas
+stops being shown, for example after Escape, input subscriptions receive
+`{ kind: 'focus', focused: false }` and `onDeactivate(id, handler)`
+subscriptions run. The plugin calls `focus(true)` again to take keys back.
+Sidebar cards and machine slots show only canvases without `captureInput`.
+Local frontends receive canvas cells and send input. Remote viewers receive
+the canvas grids and hover metadata, but remote actions, commands, panel
+visibility changes, and canvas input are read-only until transport support is
+added.
+
+## View nodes
+
+Every node has a `type`. Field names use camelCase, and tone, weight,
+alignment, and width keywords are lowercase.
+
+| Type | Fields |
+|---|---|
+| `stack` | `gap?`, `children` |
+| `row` | `children`, `align?` |
+| `divider` | `label?` |
+| `text` | `text?` or `spans?`, `tone?`, `weight?`, `mono?` |
+| `badge` | `label`, `tone?` |
+| `dot` | `tone?` |
+| `progress` | `value`, `max`, `tone?`, `label?` |
+| `segments` | `items`: `{ value, max, tone?, label? }` |
+| `card` | `title?`, `tone?`, `children` |
+| `stat` | `label`, `value`, `tone?`, `hint?` |
+| `kv` | `items`: `{ label, value, mono?, copy? }` |
+| `tabs` | `id`, `items`, `filters?`, `action?` |
+| `select` | `id`, `label`, `options`, `filters?`, `action?` |
+| `table` | `id`, `columns`, `rows` |
+| `log` | `lines` |
+| `button` | `label`, `action` |
+
+Tones are `ok`, `info`, `warn`, `error`, `muted`, `accent`, `pending`, and
+`bright` (`TONES`). Weights are `normal`, `bold`, and `dim`. Alignments are
+`start`, `center`, and `end`.
+
+A table column has an `id`, an optional `label`, a `width` of `'fill'` or a
+cell count, an optional `maxWidth` and `align`, and a `priority`. The host
+drops the columns with the highest `priority` values first on a narrow
+surface. A table row has an `id`, `cells` keyed by column ID, and optional
+`tone`, `note` spans, `tags`, and `action`.
+
+Tab items and select options carry an `id`, a `label`, an optional `count`,
+and an optional `tag`. When `filters` names a table in the same view, the
+host shows the rows whose `tags` contain the chosen item's `tag`. An item
+without a `tag` shows every row. The host filters and counts for each viewer
+without a plugin round trip.
+
+A view action is `{ actionId, value?, opens? }`. The host sends `actionId`
+and the string `value` to the plugin, so an `onAction(actionId, handler)`
+handler receives `event.value`. One action ID with a per-row value replaces
+one subscription per row. When `opens` names a panel, the host opens that
+panel after the plugin accepts the action. A `tabs` or `select` action value
+defaults to the chosen item ID.
+
+A node type that the host does not know draws nothing, so a newer SDK can
+add node types.
+
+### Card views
+
+Titles come from the contribution's `title`. The host adds no status dot,
+health text, or machine label to a card title or panel. Authors can include
+indicators in their own title or content. Runtime health remains available in
+plugin management through `ctx.health.set()`.
+
+A card shows a short summary. Its view can contain `stack`, `row`, `text`,
+`badge`, `dot`, `progress`, `segments`, `stat`, and `divider` nodes, and it
+is at most 6 lines tall. A `stack` is as tall as its children plus `gap`
+lines between them. A `row` is as tall as its tallest child. Each other
+allowed node is 1 line, and an unknown node is 0 lines. Put `card`, `kv`,
+`tabs`, `select`, `table`, `log`, and `button` nodes in a panel. A card that
+shows a canvas uses the general canvas bounds.
+
+### Bounds
+
+`validateView(root)` applies the bounds that the host applies, and
+`replace(content)` calls it for view content. `VIEW_LIMITS` holds the
+numbers.
+
+- A tree nests at most 8 nodes deep and holds at most 4,096 nodes. Table
+  cells count toward both limits.
+- A table has at most 512 rows and 12 columns.
+- No string contains a C0 or C1 control character, DEL, or a bidirectional
+  formatting character.
+- Every number is finite.
+- The serialized tree fits in one 256 KiB frame.
+- An action ID and an action `opens` value are plugin identifiers, and an
+  action `value` is at most 512 UTF-8 bytes.
+- An action `opens` value names a panel that the plugin declares.
+- A card view follows the card rules above.
+
+`validateView(root, { kind, manifest })` applies the card rules when `kind`
+is `'card'` and the `opens` rule when `manifest` is present.
+
+### View helpers
+
+`ui` builds nodes as plain JSON. The helpers are optional; hand-written JSON
+with the same fields is equivalent. Options that are `undefined` are left
+out.
+
+```js
+import { definePlugin, ui } from '@standardagents/code-plugin-sdk'
+
+export default definePlugin({
+  id: 'builds-monitor',
+  activate(ctx) {
+    const card = ctx.card('summary')
+    card.replace(ui.view(ui.stack([
+      ui.stat('Queue', '3', { tone: 'pending' }),
+      ui.table('builds', [{ id: 'version', label: 'Version' }], [{
+        id: 'b-1',
+        cells: { version: ui.text('0.4.12', { weight: 'bold' }) },
+        action: ui.action('open-build', { value: 'b-1', opens: 'build-detail' }),
+      }]),
+      ui.button('Open dashboard', 'open-dashboard'),
+    ])))
+    ctx.onAction('open-build', event => { /* event.value is 'b-1' */ })
+  },
+})
+```
+
+| Helper | Result |
+|---|---|
+| `ui.view(root)` | `{ kind: 'view', root }` |
+| `ui.action(actionId, { value, opens })` | an action |
+| `ui.span(text, { tone, weight, mono })` | a span |
+| `ui.stack(children, { gap })`, `ui.row(children, { align })` | a layout node |
+| `ui.card(children, { title, tone })` | a card node |
+| `ui.divider(label)` | a divider |
+| `ui.text(textOrSpans, { tone, weight, mono })` | a text node; an array sets `spans` |
+| `ui.badge(label, tone)`, `ui.dot(tone)` | a badge or dot |
+| `ui.progress(value, max, { tone, label })`, `ui.segments(items)` | a meter |
+| `ui.stat(label, value, { tone, hint })`, `ui.kv(items)` | a value display |
+| `ui.tabs(id, items, { filters, action })` | a tab strip |
+| `ui.select(id, label, options, { filters, action })` | a drop-down |
+| `ui.table(id, columns, rows)` | a table |
+| `ui.log(lines)` | a log |
+| `ui.button(label, action)` | a button; `action` is an action or an action ID |
+
+`packages/plugin-sdk/test/fixtures/view-builds-monitor.json` holds a complete
+view that matches the protocol's round-trip test.
+
+### Pane header and footer slots
+
+A `slot` on `pane.header` or `pane.footer` contributes rows inside the pane
+frame, above or below its terminal body. Declarations use `width: "full"`
+(the default) or `width: "half"`. Contributions stack in ascending plugin
+order, then plugin ID and contribution ID. Full contributions occupy their
+own rows. Consecutive half contributions share a row, with the odd column
+assigned to the left. An unpaired half leaves the right half empty.
+Multiline half contributions share a block as tall as the taller contribution.
+
+Rows, styled text, and non-interactive canvas cells render in these slots.
+Each slot is bounded to 32 rows. Small panes clip slot rows while preserving
+terminal space. Slot height participates in the same geometry used for terminal
+painting, pointer input, graphics clipping, and controller-owned resizing.
+Remote viewers receive the same contributions. Missing panes, stale producer
+snapshots, and mismatched pane generations withdraw their rows.
+
+Pane-slot actions, input capture, hover popovers, and persisted slot collapse
+remain unconnected. They are separate from the implemented row rendering.
+
+`ctx.context.get()` exposes `projects`, `panes`, and `complete` for the owning
+machine. Project records contain `{ entity, name, path }`; pane records contain
+`{ entity, projectId, name, cwd }`. Entities include machine ID and a decimal
+string generation. The pane `cwd` is its configured project launch directory.
+Live shell-directory observations are a separate future capability. Each list
+has at most 128 records, and their combined JSON is bounded to 32 KiB. `complete`
+is false when a local path could not be decoded or a bound omitted records.
+Commands, launch environment, prompts, and encrypted payloads are excluded.
+Plugins must perform filesystem work on their owning machine and clear
+contributions when their target disappears or changes generation.
+
+### Current frontend coverage
+
+Sections, plugin cards, machine slots, stacked pane header/footer slots, canvas surfaces, host-rendered views,
+global command palette entries, and the three
+panel presentations are implemented. A popover follows the content width and height within the
+modal area. Its title is the contribution title and its body starts beneath it. A column attaches to the sidebar and resizes the workspace. A
+plugin pane has a tab and focus, drag, close, and reveal behavior; its width
+follows content and it does not create a tmux pane or resize a terminal.
+
+Project slot anchors, standalone badges attached to hierarchy rows,
+menu registrations, key registrations, link registrations,
+and entity-scoped command palette entries have protocol and composition support
+but do not have connected production frontend surfaces. Badge nodes inside a
+view tree are rendered. The `overlay`
+contribution kind has protocol validation, while general workspace overlay
+placement and input remain unfinished. Use a supported panel presentation for
+current interactive canvases.
+
+## Actions and subscriptions
+
+Commands, menus, keys, and links carry stable action IDs. Actions receive a
+selection and handler context with an abort signal. Link handlers return a
+boolean that controls matching-handler traversal.
+
+Global command registrations appear in the command palette. Menu, key, and
+link registrations are accepted and stored by the SDK and daemon, while their
+frontend menus, global key dispatch, and link list are still planned. An
+entity-scoped command also has no current palette surface. `url.open` is the
+supported host operation for opening a URL.
+
+Event, hook, input, select, resize, activate, deactivate, and visibility
+subscriptions use bounded conditions. Schedules allow `always`,
+`section-visible`, `slot-visible`, or `panel-open` conditions. One schedule
+invocation runs at a time.
+
+## Typed requests
+
+The operation map covers pane and project lifecycle, notifications, URL and
+fetch access, secrets, configuration, account state, context, popovers, canvas
+write and focus, subscription changes, health, and webhook acknowledgements.
+Each operation has a typed input and output. `RequestOptions` accepts an abort
+signal and a timeout.
+
+`ctx.state` provides account-backed `get(key)`, `set(key, value)`, and
+`keys()` methods. State is isolated by the plugin ID. `keys()` takes no input
+besides optional `RequestOptions` and returns a sorted `string[]` containing
+the plugin's key names. The result is empty when no keys exist, is limited to
+256 keys, and has no prefix or pagination parameters. A key written by one
+machine is visible to the other machines signed into the same account, so a
+plugin can use distinct machine-specific key names without maintaining a
+shared index. Key names are 1 to 128 bytes. The first character is ASCII
+alphanumeric or `_`; later characters are ASCII alphanumeric, `_`, `.`, `:`,
+or `-`. Values remain limited to 64 KiB of JSON. The host applies the same
+account authority and revocation checks to all three methods.
+
+The public SDK applies the same capability checks and request bounds to every
+plugin. Plugin IDs do not grant fetch, pane, project, or secret exceptions.
+The current native host connects fetch, secrets, configuration, account state,
+context, URL opening, subscription changes, health, canvas writes, and canvas
+focus. Pane/project lifecycle requests, notifications, `popover.open`, and
+webhook acknowledgements have public types but currently return an unsupported
+operation error through the production context. Declaring a capability does
+not supply an unfinished host adapter.
+
+The shared fetch policy currently permits HTTPS GET requests to
+`builds.standardcode.ai` on port 443 under `/admin/api/` or `/builds/`. Requests
+have no body, user-info, or fragment. Allowed request headers are authorization,
+range, accept, and cache-control. The response body limit is 16 MiB. These
+bounds apply to every fetch-authorized plugin. Plugin code retains normal
+Node.js access to files, networking, and subprocesses under the user's identity;
+capabilities govern SDK/host operations and do not provide OS sandboxing.
+
+## Build context
+
+`context.get` returns a `PluginContextInfo`:
+
+```json
+{
+  "accountId": "account-id",
+  "machineId": "machine-id",
+  "projects": [],
+  "panes": [],
+  "complete": true,
+  "build": {
+    "version": "0.14.1-branch.3bd7f23c.98a422",
+    "commit": "<40 hex digits>",
+    "ref": "refs/heads/feat/sidebar-plugins",
+    "channel": "branch"
+  },
+  "fleet": {
+    "mode": "follow",
+    "npmTag": "branch-feat-sidebar-plugins-3bd7f23c-b-6e049b24f5928544",
+    "ref": "refs/heads/feat/sidebar-plugins",
+    "version": "0.14.1-branch.3bd7f23c.98a422"
+  }
+}
+```
+
+`build` describes the native release that this machine runs. It is `null` for
+a development binary without release metadata.
+
+- `channel` is `branch` for branch and issue builds, `canary` for `main`
+  builds, `production` for a stable version, and `team` for a legacy team
+  release.
+- `ref` is `refs/heads/main` for canary and team builds and
+  `refs/tags/vX.Y.Z` for production builds. A branch build reports its sealed
+  branch name.
+
+`fleet` describes the account build policy. It is `null` when the account has
+no build policy.
+
+- `mode` is `follow` for a followed npm tag, `production` for the `latest`
+  tag, and `pin` for an exact version.
+- `npmTag` is the followed tag, or `null` for a pin.
+- `version` is the pinned version, or the target of the current rollout, or
+  the active account version. It is `null` when none is known.
+- `ref` is `refs/heads/main` for `canary`. A branch or issue tag has a `ref`
+  only when it names the branch of the running build. The daemon does not
+  read the network to resolve other branch names, so `ref` is `null` for them.
+
+Older daemons return only `accountId` and `machineId`. Treat a missing
+`build` or `fleet` as `null`.
+
+A plugin with the `events` capability can subscribe with
+`onEvent('build-context', handler)`. The daemon delivers a `BuildContextEvent`
+when `build` or `fleet` changes. Its `data` holds the new `build` and `fleet`
+values in the shape above. Other account changes do not deliver the event, and
+the daemon does not deliver it when a plugin starts. Read `context.get` at
+activation for the initial values. The daemon pushes each change, so a plugin
+needs no schedule to track the followed channel.
+
+Plugins with `events` can subscribe to `onEvent('pane-context', handler)`.
+Its `data` replaces the local `machineId`, `projects`, `panes`, and `complete`
+fields from `context.get`. Only a changed local context produces an event.
+Subscribe before the initial `context.get` request and discard that response
+if an event arrives while it is pending. Pane removal and generation changes
+must withdraw publishers for the old entity. Project launch directories are
+configured paths; shell `cd` changes are outside this event's current contract.
+
+A plugin can watch these directories with Node's native filesystem events.
+Debounce bursts with a one-shot timer, retain changes that arrive during a read,
+and close watchers on disposal or target removal. Do not schedule directory
+or Git refresh polling. Watch linked-worktree Git metadata and shared refs as
+well as the working tree. Filesystem notification errors should report degraded
+health; they must not silently switch to polling.
+
+## Hooks and delivery
+
+Hook dispatch and durable webhook delivery are planned host integrations.
+The public contract defines hook events with an entity, launch specification,
+ancestry, operation ID, and deadline. A hook returns `proceed` with an optional replacement launch or
+`cancel` with a bounded reason. Webhook events carry a delivery ID for
+acknowledgement and replay-safe handling.
+
+## Testing harness
+
+`@standardagents/code-plugin-sdk/testing` provides `createHarness`. A harness drives
+activation, event delivery, visibility, manual time, flushing, and disposal.
+It records traces, surface replacement, subscriptions, and resources without
+starting subprocesses. `harness.surface(id, entity?)` returns the current
+content of a published contribution, including view and canvas content, or
+`undefined` after the contribution clears.
+
+### Canvas theme colors
+
+`CanvasSpec.themeColors` maps up to 32 canvas-local ANSI indexes (0–255) to
+recipes. Each recipe has `source` (optional ANSI index 0–15, omitted for the
+default foreground), `mix` (optional second ANSI index mixed equally), and
+`opacity` (0–1, blended against the viewer background). Both foreground and
+background SGR references to that index resolve through the same recipe.
+For example, `{ 16: { source: 4, opacity: 0.72 }, 20: { opacity: 0.4 } }`
+provides muted terminal blue at index 16 and a subtle foreground at index 20.
+
+Resolution occurs in the viewer for sidebar, pane, slot, column, and popover
+canvases. Remote producers do not read or bake another machine's colors.
+Recipes remain unchanged across terminal theme updates. Unavailable source
+colors fall back to the named ANSI index or default foreground; unavailable
+background colors leave opacity unapplied. OSC queries remain unsupported
+in plugin canvas streams. This capability is public and identical for all
+plugins.

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