@standardagents/code-plugin-sdk 1.0.0-alpha.4-hover.1 → 1.0.0-alpha.5-usage.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.4-hover.1" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.4-hover.1" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.5-usage.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.5-usage.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -46,9 +46,9 @@ 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, canvas hover text, input focus, popover/column/pane
-presentations, remote read-only behavior, and the frontend surfaces that are
-still planned.
+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,
@@ -177,8 +177,15 @@ methods.
 
 `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 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

package/REFERENCE.md

@@ -5,7 +5,7 @@ The public declarations live in
 plugin authors.
 
 The bundled SDK and the npm package use the same public declarations. This
-reference describes SDK `1.0.0-alpha.4-hover.1`. Plugins should declare the
+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`.
 
@@ -44,6 +44,12 @@ panels:
 
 `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;
@@ -139,11 +145,15 @@ 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. It must be non-empty after trimming,
-fit within 512 UTF-8 bytes, and contain no C0, C1, DEL, or bidirectional
-formatting character. `Canvas.replace` publishes the canvas metadata, so a
-plugin can update the hover text with another `replace` call while retaining
-the same canvas grid.
+`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
@@ -152,6 +162,8 @@ 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
@@ -299,17 +311,48 @@ export default definePlugin({
 `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, canvas surfaces, host-rendered views,
+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 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,
+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`
@@ -342,6 +385,18 @@ 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,
@@ -367,6 +422,9 @@ capabilities govern SDK/host operations and do not provide OS sandboxing.
 {
   "accountId": "account-id",
   "machineId": "machine-id",
+  "projects": [],
+  "panes": [],
+  "complete": true,
   "build": {
     "version": "0.14.1-branch.3bd7f23c.98a422",
     "commit": "<40 hex digits>",
@@ -415,6 +473,21 @@ 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.

package/package.json

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

package/src/index.d.ts

@@ -90,8 +90,8 @@ export interface CanvasSpec {
   transparent?: boolean;
   shade?: number;
   captureInput?: boolean;
-  /** A bounded one-line string shown while the pointer rests over the canvas. */
-  hover?: string;
+  /** 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 };
 /**
@@ -235,13 +235,27 @@ export type FleetPolicy = {
   /** The pinned or target version, or null when it is not known. */
   version: string | null;
 };
+/** A local project available to plugins on its owning machine. */
+export interface PluginProjectContext { entity: EntityRef; name: string; path: string }
+/** Pane context with its configured project launch directory. */
+export interface PluginPaneContext { entity: EntityRef; projectId: string; name: string; cwd: string }
 /** The `context.get` result. `build` and `fleet` are null when unknown. */
 export type PluginContextInfo = {
   accountId: string;
   machineId: string;
+  projects: PluginProjectContext[];
+  panes: PluginPaneContext[];
+  /** False when local records could not be included or decoded. */
+  complete: boolean;
   build?: BuildInfo | null;
   fleet?: FleetPolicy | null;
 };
+/** Replaces the local pane/project context after an account change. */
+export type PaneContextEventData = Pick<PluginContextInfo, 'machineId' | 'projects' | 'panes' | 'complete'>;
+export interface PaneContextEvent extends PluginEvent {
+  name: 'pane-context';
+  data: PaneContextEventData;
+}
 /** The `data` of a `build-context` event. */
 export type BuildContextEventData = {
   build: BuildInfo | null;
@@ -275,6 +289,7 @@ export interface OperationMap {
   'config.get': { input: Record<string, never>; output: Record<string, Json> };
   'state.get': { input: { key: string }; output: Json };
   'state.set': { input: { key: string; value: Json }; output: null };
+  'state.keys': { input: Record<string, never>; output: string[] };
   'context.get': { input: Record<string, never>; output: PluginContextInfo };
   'popover.open': { input: Popover; output: { choiceId?: string; values?: Record<string, Json>; confirmationId?: string } | null };
   'canvas.write': { input: { key: ContributionKey; ansi: string }; output: null };
@@ -331,6 +346,7 @@ export interface PluginContext {
   key(id: string, handler: ActionHandler): KeyRegistration;
   link(id: string, options: LinkOptions, handler: LinkHandler): Subscription;
   link(id: string, handler: LinkHandler): Subscription;
+  onEvent(name: 'pane-context', handler: (event: PaneContextEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
   onEvent(name: 'build-context', handler: (event: BuildContextEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
   onEvent(name: string, handler: (event: PluginEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
   onHook(name: string, handler: (event: HookEvent, context: HandlerContext) => HookResult | Promise<HookResult>): Subscription;
@@ -357,8 +373,8 @@ 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>> };
-  /** 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> };
+  /** 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. `keys()` returns the sorted key names. */
+  state: { get(key: string, options?: RequestOptions): Promise<Json>; set(key: string, value: Json, options?: RequestOptions): Promise<null>; keys(options?: RequestOptions): Promise<string[]> };
   context: { get(options?: RequestOptions): Promise<PluginContextInfo> };
   popover: { open(args: Popover, options?: RequestOptions): Promise<OperationMap['popover.open']['output']> };
   health: { set(args: OperationMap['health.set']['input'], options?: RequestOptions): Promise<null> };

package/src/protocol.mjs

@@ -8,7 +8,7 @@ export const OPERATIONS = Object.freeze({
   'pane.input': 'panes', 'pane.focus': 'panes', 'pane.wait': 'panes',
   'project.create': 'projects', 'project.remove': 'projects',
   'notification.show': 'notifications', 'url.open': 'url', fetch: 'fetch',
-  'secret.get': 'secrets', 'config.get': null, 'state.get': null, 'state.set': null,
+  'secret.get': 'secrets', 'config.get': null, 'state.get': null, 'state.set': null, 'state.keys': null,
   'context.get': null, 'popover.open': 'surfaces', 'canvas.write': 'surfaces',
   'canvas.focus': 'surfaces', 'subscription.add': null, 'subscription.remove': null,
   'health.set': null, 'webhook.ack': 'webhook',

package/src/runtime.mjs

@@ -12,9 +12,39 @@ function boundedText(value, label, limit = 512) {
 }
 const HOVER_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
 function validateCanvasHover(value) {
-  ensure(typeof value === 'string' && value.trim().length > 0 && !HOVER_FORBIDDEN.test(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(value) <= LIMITS.canvasHoverBytes,
+  ensure(Buffer.byteLength(text) <= LIMITS.canvasHoverBytes,
     'payload_too_large', `Canvas hover text exceeds ${LIMITS.canvasHoverBytes} bytes`)
 }
 function validateEntity(entity) {
@@ -342,7 +372,8 @@ export function createRuntime({ manifest: input, producer, send, clock = realClo
     secrets: Object.freeze({ get: (name, options) => request('secret.get', { name }, options) }),
     config: Object.freeze({ get: options => request('config.get', {}, options) }),
     state: Object.freeze({ get: (key, options) => request('state.get', { key }, options),
-      set: (key, value, options) => request('state.set', { key, value }, options) }),
+      set: (key, value, options) => request('state.set', { key, value }, options),
+      keys: options => request('state.keys', {}, options) }),
     context: Object.freeze({ get: options => request('context.get', {}, options) }),
     popover: Object.freeze({ open: method('popover.open') }),
     health: Object.freeze({ set: method('health.set') }),

package/src/testing.mjs

@@ -43,8 +43,9 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
           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 'state.keys': return [...accountState.keys()].sort()
         case 'config.get': return {}
-        case 'context.get': return { accountId: 'test-account', machineId, build: null, fleet: null }
+        case 'context.get': return { accountId: 'test-account', machineId, build: null, fleet: null, projects: [], panes: [], complete: true }
         case 'health.set': return null
         default: throw new PluginError('missing_fixture', `Provide a harness handler for ${operation.op}`)
       }