@standardagents/code-plugin-sdk 1.0.0-alpha.3 → 1.0.0-alpha.4-hover.2

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.4-hover.2" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.4-hover.2" },
   "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,14 +175,18 @@ 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. A plugin holds at most 256 keys, and one value is at most
+64 KiB of JSON.
 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.
 
 ## License
 

package/REFERENCE.md

@@ -0,0 +1,439 @@
+# 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.4-hover.2`. 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 boxed card in the sidebar. `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.
+
+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
+
+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.
+
+### Current frontend coverage
+
+Sections, plugin cards, machine slots, canvas surfaces, host-rendered views,
+global command palette entries, and the three
+panel presentations are implemented. A popover is content-sized within the
+modal area. 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, pane
+header/footer anchors, 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.
+
+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",
+  "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.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4-hover.2",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",
@@ -16,6 +16,6 @@
     "./testing": { "types": "./src/testing.d.ts", "import": "./src/testing.mjs" }
   },
   "bin": { "standard-plugin": "./bin/standard-plugin.mjs" },
-  "files": ["src", "bin", "README.md", "LICENSE"],
+  "files": ["src", "bin", "README.md", "REFERENCE.md", "LICENSE"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/index.d.ts

@@ -90,6 +90,8 @@ export interface CanvasSpec {
   transparent?: boolean;
   shade?: number;
   captureInput?: boolean;
+  /** A bounded one-line string or styled spans shown while the pointer rests over the canvas. */
+  hover?: string | TextSpan[];
 }
 export type CanvasContent = { kind: 'canvas'; canvas: CanvasSpec };
 /**
@@ -355,7 +357,7 @@ export interface PluginContext {
   fetch(args: OperationMap['fetch']['input'], options?: RequestOptions): Promise<OperationMap['fetch']['output']>;
   secrets: { get(name: string, options?: RequestOptions): Promise<string | null> };
   config: { get(options?: RequestOptions): Promise<Record<string, Json>> };
-  /** Local state for one machine. It is never shared with other machines. */
+  /** Per-plugin key and value storage, held in the user's account and shared across their machines: 256 keys per plugin, 64 KiB per value. */
   state: { get(key: string, options?: RequestOptions): Promise<Json>; set(key: string, value: Json, options?: RequestOptions): Promise<null> };
   context: { get(options?: RequestOptions): Promise<PluginContextInfo> };
   popover: { open(args: Popover, options?: RequestOptions): Promise<OperationMap['popover.open']['output']> };
@@ -371,7 +373,7 @@ 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 }>;
+export const VIEW_LIMITS: Readonly<{ depth: 8; nodes: 4096; tableRows: 512; tableColumns: 12; items: 512; logLines: 2048; cardLines: 6; actionValueBytes: 512 }>;
 /**
  * Throws a PluginError when a view tree breaks a protocol bound or a daemon rule. Unknown node types pass.
  * `kind: 'card'` adds the card rules; `manifest` requires each action `opens` to name one of its panels.

package/src/manifest.mjs

@@ -12,7 +12,8 @@ export const LIMITS = Object.freeze({ manifestBytes: 65536, frameBytes: 262144,
   responseFrameBytes: 64 * 1024 * 1024,
   pendingRequests: 128, subscriptions: 256, schedules: 128, contributions: 256,
   queuedBytes: 4 * 1024 * 1024, hookTimeoutMs: 60000, requestTimeoutMs: 30000,
-  canvasColumns: 512, canvasRows: 256 })
+  canvasColumns: 512, canvasRows: 256, canvasHoverBytes: 512,
+  stateKeys: 256, stateValueBytes: 64 * 1024 })
 
 export class PluginError extends Error {
   constructor(code, message) { super(message); this.name = 'PluginError'; this.code = code }

package/src/runtime.mjs

@@ -10,6 +10,43 @@ function boundedText(value, label, limit = 512) {
     !/[\u0000-\u001f\u007f]/.test(value), 'invalid_payload', `Invalid ${label}`)
   return value
 }
+const HOVER_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
+function validateCanvasHover(value) {
+  if (typeof value === 'string') {
+    ensure(value.trim().length > 0 && !HOVER_FORBIDDEN.test(value),
+      'invalid_payload', 'Invalid canvas hover text')
+    ensure(Buffer.byteLength(value) <= LIMITS.canvasHoverBytes,
+      'payload_too_large', `Canvas hover text exceeds ${LIMITS.canvasHoverBytes} bytes`)
+    return
+  }
+  ensure(Array.isArray(value), 'invalid_payload', 'Invalid canvas hover spans')
+  ensure(value.length > 0, 'invalid_payload', 'Canvas hover spans must contain text')
+  ensure(value.length <= 32, 'payload_too_large', 'Canvas hover spans exceed 32 spans')
+  let text = ''
+  for (const span of value) {
+    ensure(object(span), 'invalid_payload', 'Invalid canvas hover span')
+    ensure(typeof span.text === 'string' && !HOVER_FORBIDDEN.test(span.text),
+      'invalid_payload', 'Invalid canvas hover span text')
+    for (const field of ['foreground', 'background']) {
+      if (span[field] !== undefined) {
+        ensure(typeof span[field] === 'string' && span[field].trim().length > 0 &&
+          !HOVER_FORBIDDEN.test(span[field]), 'invalid_payload', `Invalid canvas hover span ${field}`)
+        ensure(Buffer.byteLength(span[field]) <= 64,
+          'payload_too_large', `Canvas hover span ${field} exceeds 64 bytes`)
+      }
+    }
+    for (const field of ['bold', 'italic', 'underline']) {
+      ensure(span[field] === undefined || typeof span[field] === 'boolean',
+        'invalid_payload', `Invalid canvas hover span ${field}`)
+    }
+    ensure(span.actionId === undefined, 'invalid_payload', 'Canvas hover spans cannot contain actionId')
+    text += span.text
+  }
+  ensure(text.trim().length > 0 && !HOVER_FORBIDDEN.test(text),
+    'invalid_payload', 'Invalid canvas hover text')
+  ensure(Buffer.byteLength(text) <= LIMITS.canvasHoverBytes,
+    'payload_too_large', `Canvas hover text exceeds ${LIMITS.canvasHoverBytes} bytes`)
+}
 function validateEntity(entity) {
   ensure(object(entity) && entityKinds.includes(entity.kind), 'invalid_payload', 'Invalid registration entity')
   boundedText(entity.id, 'entity id', 128)
@@ -57,10 +94,11 @@ function validateContent(content, declaration, manifest) {
   if (content.kind === 'view') validateView(content.root, { kind: declaration.kind, manifest })
   jsonBytes(content)
   if (content.kind === 'canvas') {
-    const { columns, rows, shade = 0 } = content.canvas ?? {}
+    const { columns, rows, shade = 0, hover } = content.canvas ?? {}
     ensure(Number.isSafeInteger(columns) && columns > 0 && columns <= LIMITS.canvasColumns &&
       Number.isSafeInteger(rows) && rows > 0 && rows <= LIMITS.canvasRows &&
       Number.isFinite(shade) && shade >= 0 && shade <= 1, 'invalid_payload', 'Invalid canvas dimensions or shade')
+    if (hover !== undefined) validateCanvasHover(hover)
   }
 }
 

package/src/testing.mjs

@@ -1,6 +1,6 @@
 import { createRuntime } from './runtime.mjs'
 import { RpcPeer } from './protocol.mjs'
-import { PluginError, ensure, LIMITS, validateManifest } from './manifest.mjs'
+import { PluginError, ensure, jsonBytes, LIMITS, validateManifest } from './manifest.mjs'
 
 /** Explicit time and fixture-owned responses; this harness starts no threads or subprocesses. */
 export function createHarness({ manifest: input, machineId = 'test-machine', epoch = '1', handlers = {}, now = 0 } = {}) {
@@ -9,7 +9,7 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
   const trace = []
   const surfaces = new Map()
   const subscriptions = new Map()
-  const localState = new Map()
+  const accountState = new Map()
   const timers = new Map()
   let timerId = 0
   let disposed = false
@@ -36,10 +36,13 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
       switch (operation.op) {
         case 'subscription.add': subscriptions.set(args.id, structuredClone(args)); return null
         case 'subscription.remove': subscriptions.delete(args.id); return null
-        case 'state.get': return structuredClone(localState.get(args.key) ?? null)
+        case 'state.get': return structuredClone(accountState.get(args.key) ?? null)
         case 'state.set':
-          ensure(localState.has(args.key) || localState.size < LIMITS.contributions, 'queue_full', 'Harness state is full')
-          localState.set(args.key, structuredClone(args.value)); return null
+          // The product stores these values in the account: 256 keys per
+          // plugin, 64 KiB per value.
+          ensure(accountState.has(args.key) || accountState.size < LIMITS.stateKeys, 'queue_full', 'Harness state holds 256 keys for this plugin')
+          jsonBytes(args.value, LIMITS.stateValueBytes)
+          accountState.set(args.key, structuredClone(args.value)); return null
         case 'config.get': return {}
         case 'context.get': return { accountId: 'test-account', machineId, build: null, fleet: null }
         case 'health.set': return null

package/src/view.mjs

@@ -2,8 +2,10 @@ 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.
+// items and logLines bound the list-shaped nodes: the host lays every entry
+// out again on each paint, so a long list costs a frame, not just memory.
 export const VIEW_LIMITS = Object.freeze({ depth: 8, nodes: 4096, tableRows: 512, tableColumns: 12,
-  cardLines: 6, actionValueBytes: 512 })
+  items: 512, logLines: 2048, 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']
@@ -38,6 +40,15 @@ function entries(value, field, optional, check) {
     check(item)
   }
 }
+function bounded(value, field, limit, optional = false) {
+  const values = list(value, field, optional)
+  ensure(values.length <= limit, 'invalid_payload', `Plugin view ${field} has more than ${limit} entries`)
+  return values
+}
+// A list-shaped node's entries, held to the bound the host applies.
+function boundedEntries(value, field, check) {
+  entries(bounded(value, field, VIEW_LIMITS.items), field, false, check)
+}
 function spans(value, optional) {
   entries(value, 'spans', optional, span => {
     text(span.text, 'span text')
@@ -77,7 +88,7 @@ const NODES = {
   badge(node) { text(node.label, 'label'); tone(node.tone) },
   dot(node) { tone(node.tone) },
   progress: meter,
-  segments(node) { entries(node.items, 'items', false, meter) },
+  segments(node) { boundedEntries(node.items, 'items', meter) },
   card(node, depth, count) { optionalText(node.title, 'title'); tone(node.tone); children(node, depth, count) },
   stat(node) {
     text(node.label, 'label')
@@ -86,7 +97,7 @@ const NODES = {
     optionalText(node.hint, 'hint')
   },
   kv(node) {
-    entries(node.items, 'items', false, item => {
+    boundedEntries(node.items, 'items', item => {
       text(item.label, 'label')
       text(item.value, 'value')
       flag(item.mono, 'mono')
@@ -97,7 +108,7 @@ const NODES = {
     text(node.id, 'id')
     optionalText(node.filters, 'filters')
     action(node.action)
-    entries(node.items, 'items', false, item => {
+    boundedEntries(node.items, 'items', item => {
       text(item.id, 'id')
       text(item.label, 'label')
       optionalText(item.sublabel, 'sublabel')
@@ -111,7 +122,7 @@ const NODES = {
     text(node.label, 'label')
     optionalText(node.filters, 'filters')
     action(node.action)
-    entries(node.options, 'options', false, option => {
+    boundedEntries(node.options, 'options', option => {
       text(option.id, 'id')
       text(option.label, 'label')
       optionalText(option.group, 'group')
@@ -137,7 +148,7 @@ const NODES = {
       text(row.id, 'row id')
       tone(row.tone)
       spans(row.note, true)
-      for (const tag of list(row.tags, 'tags', true)) text(tag, 'tag')
+      for (const tag of bounded(row.tags, 'tags', VIEW_LIMITS.items, 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 ?? {})) {
@@ -146,7 +157,7 @@ const NODES = {
       }
     })
   },
-  log(node) { for (const line of list(node.lines, 'lines')) text(line, 'log line') },
+  log(node) { for (const line of bounded(node.lines, 'lines', VIEW_LIMITS.logLines)) text(line, 'log line') },
   button(node) { text(node.label, 'label'); action(node.action, false) },
 }