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

package/README.md

@@ -11,8 +11,8 @@ Its `package.json` includes a static `standardPlugin` manifest.
 {
   "name": "example-status",
   "type": "module",
-  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -44,6 +44,20 @@ package, such as `@standardagents/code-plugin-sdk/testing`, are refused when
 the plugin runs inside Standard Code. The `testing` export serves the
 plugin's own test suite.
 
+The complete rendering contract is in [REFERENCE.md](./REFERENCE.md). It
+covers rows, styled text, badges, cards, slots, panels, overlays, host-rendered
+views, ANSI canvases, styled canvas hover text, input focus,
+popover/column/pane presentations, remote read-only behavior, and the frontend
+surfaces that are still planned.
+
+Plugin source imports the default package entry. Plugin tests may import
+`@standardagents/code-plugin-sdk/testing` for `createHarness`. Runner internals,
+raw host request envelopes, and internal module paths are outside the public
+package exports. First-party plugins use these same public entries and receive
+the same manifest validation, capability checks, request bounds, and remote
+ownership rules as third-party plugins. A plugin ID does not grant a host
+operation or fetch exception.
+
 The runtime disposes publishers, subscriptions, schedules and pending requests.
 Plugins register additional cleanup through `ctx.onDispose` or an activation return value.
 Handlers receive an abort signal.
@@ -148,7 +162,7 @@ The harness starts no subprocesses.
 
 ## Supported interface
 
-The public interface is the package's default export, its `testing` export,
+The public interface is the package root export, its `testing` export,
 the declarations in `src/index.d.ts` and `src/testing.d.ts`, and the
 `standard-plugin` command's `check` and `pack` behavior.
 
@@ -161,15 +175,92 @@ without notice. Plugin code and plugin tests should treat recorded frames as
 opaque values and drive the plugin through `PluginContext` and the harness
 methods.
 
-Local `ctx.state` belongs to one machine.
+`ctx.state` is per-plugin key and value storage. Standard Code stores these
+values in the user's account, so every machine the user has reads and writes
+the same keys. `ctx.state.keys()` returns the sorted key names for this
+plugin's account namespace. It returns an empty array when the plugin has no
+keys and accepts only `RequestOptions`; it has no prefix or pagination
+arguments. Another plugin cannot read these keys, even when it uses the same
+account. Key names are 1 to 128 bytes. The first character is ASCII
+alphanumeric or `_`; later characters are ASCII alphanumeric, `_`, `.`, `:`,
+or `-`. A plugin holds at most 256 keys, and one value is at most 64 KiB of
+JSON. The host applies the same account authority and revocation checks to
+`keys()` as it applies to `get()` and `set()`.
 The public context declarations are in `src/index.d.ts`.
 
 ## Releases
 
 The Standard Code build workflow publishes this package when the version in
-`package.json` changes. Prereleases publish under the `next` dist-tag and
-releases under `latest`.
+`package.json` changes. Main prereleases publish under `next` and main releases
+under `latest`. Feature branches publish under their product branch tag. Authors
+can install a published prerelease by its exact version.
+
+## Sidebar card titles
+
+Sidebar card titles use muted, regular-weight text. A card declaration may
+supply an `icon` containing one Nerd Font private-use glyph, for example
+`"icon": "\uDB81\uDCC5"` (a gauge). The author chooses the card's topic icon.
+The host shows it only on the viewer's Nerd Font tier. Other tiers omit the
+icon and its spacing. Omitted icons have no fallback. This applies to bordered
+and borderless cards. Empty titles remain empty.
+
+A card view may replace its declared title through
+`ui.view(root, { title: [{ text: 'Builds ' }, { text: '●', foreground: 'green' }] })`.
+The optional `title` uses native `TextSpan` fields, including `#RRGGBB` and the terminal colors `black`, `red`, `green`,
+`yellow`, `blue`, `magenta`, `cyan`, and `white`;
+`ui.span()` is a body-view builder with a different shape. Titles accept 1–32
+passive spans and at most 512 UTF-8 bytes of combined, nonblank single-line text.
+Actions, control characters, and bidi formatting are rejected. Each replacement
+updates the body and title together. Omitting `title` restores the manifest title.
+This option belongs to card views. Plugins own the meaning and color of any
+status light; the SDK adds no health indicator. Host title styling and supported
+author-selected Nerd Font icons apply around the author-supplied spans.
 
 ## License
 
 MIT. See `LICENSE`.
+
+## Responsive pane rows
+
+A pane header or footer slot can publish `rows` containing a `layout` and empty
+`spans`. `layout.fields` is an ordered list of passive text fields. The host
+resolves its geometry separately for every viewer, including pane resizes.
+No resize event or producer repaint is needed.
+
+```js
+slot.replace({ kind: 'rows', rows: [{ id: 'status', spans: [], layout: {
+  projectTint: true,
+  fields: [
+    { text: 'org/repo', bold: true },
+    { text: '~/src/repo', gap: 2, flex: true, tone: 'muted',
+      shrink: { priority: 1, min: 8, mode: 'middle' } },
+    { text: ' +24 ', gap: 2, flex: true, tone: 'ok', surface: true },
+    { text: ' −6 ', tone: 'error', surface: true },
+  ],
+} }] })
+```
+
+`gap` reserves 0–8 cells before a field. `flex` distributes spare width across
+marked gaps; related fields without flexible gaps stay together. The first
+field starts at the left edge and the final field reaches the right edge when
+at least one visible flexible gap exists. `projectTint` fills the whole row
+with the pane project's identity tint. `tone` accepts `muted`, `ok`, `error`,
+`info`, `warning`, or `project`; semantic colors resolve against the viewer's
+terminal palette. `surface` shades that field's background and `bold` emphasizes
+its text. Include spaces in a field for padded color blocks.
+
+`icon` is one Nerd Font private-use glyph. `fallback` is an optional ASCII
+replacement (up to 16 bytes); viewers without Nerd Font support use the fallback.
+The host supplies one space after an icon or fallback.
+
+`shrink` policies run by increasing `priority` (0–255), then field order.
+`min` is the retained text width in cells. `start`, `middle`, and `end` select
+where an ellipsis replaces removed text. `hide` removes a field including its
+icon and gap; all hide policies with equal priority are removed together.
+Trimming preserves grapheme boundaries. If the declared minimum widths still
+exceed the pane, remaining content clips at the right edge.
+
+Layouts allow 1–32 fields, 2,048 UTF-8 bytes per text field and 8,192 total text
+bytes. Controls and bidi formatting characters are rejected. Layouts are
+supported only in pane header/footer slots. Ordinary rows and full/half slot
+stacking retain their existing behavior.

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.