@standardagents/code-plugin-sdk 1.0.0-alpha.4-hover.1 → 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.4-hover.1" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.4-hover.1" },
+  "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",
@@ -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,

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.4-hover.2`. Plugins should declare the
 version published for their product build in both `peerDependencies` and
 `devDependencies`; the manifest `apiVersion` remains `1`.
 
@@ -139,11 +139,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 +156,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

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.4-hover.2",
   "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 };
 /**

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