@standardagents/code-plugin-sdk 1.0.0-alpha.7-theme.0 → 1.0.0-alpha.9-icons.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.7-theme.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.7-theme.0" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.9-icons.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.9-icons.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -195,6 +195,27 @@ The Standard Code build workflow publishes this package when the version in
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.7-theme.0",
+  "version": "1.0.0-alpha.9-icons.0",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",

package/src/index.d.ts

@@ -16,6 +16,8 @@ export interface ContributionDeclaration {
   anchor: Anchor;
   /** Sidebar card border. Defaults to true; false retains the title and content padding. */
   border?: boolean;
+  /** One author-selected Nerd Font glyph; omitted on non-Nerd viewer tiers. */
+  icon?: string;
   title?: string;
   merge?: 'by-machine' | 'by-identity';
   width?: 'full' | 'half';
@@ -157,7 +159,7 @@ export interface ButtonNode { type: 'button'; label: string; action: ViewAction
 export type ViewNode = StackNode | RowNode | DividerNode | TextNode | BadgeNode | DotNode | ProgressNode |
   SegmentsNode | CardNode | StatNode | KvNode | TabsNode | SelectNode | TableNode | LogNode | ButtonNode;
 /** A host-rendered view tree. Cards, panels, and sections accept it. */
-export interface ViewContent { kind: 'view'; root: ViewNode }
+export interface ViewContent { kind: 'view'; root: ViewNode; /** Passive styled title for card views. */ title?: TextSpan[] }
 
 /** Slots and overlays accept rows, text, or canvas. */
 export type DrawnContent = RowsContent | TextContent | CanvasContent;
@@ -410,7 +412,7 @@ export function validateView(root: unknown, options?: { kind?: SurfaceKind; mani
 type Options<T> = Omit<T, 'type' | 'children'>;
 /** Optional builders. Each returns the plain protocol JSON for one node; hand-written JSON is equivalent. */
 export const ui: {
-  view(root: ViewNode): ViewContent;
+  view(root: ViewNode, options?: { title?: TextSpan[] }): ViewContent;
   action(actionId: string, options?: { value?: string; opens?: string }): ViewAction;
   span(text: string, options?: Omit<ViewSpan, 'text'>): ViewSpan;
   stack(children: ViewNode[], options?: Options<StackNode>): StackNode;

package/src/manifest.mjs

@@ -76,6 +76,9 @@ export function validateManifest(value) {
     ensure(object(declaration) && identifier(declaration.id) && !ids.has(declaration.id) &&
       SURFACE_KINDS.includes(declaration.kind) && ANCHORS.includes(declaration.anchor), 'invalid_manifest', 'Invalid contribution declaration')
     ids.add(declaration.id)
+    ensure(declaration.icon === undefined || (declaration.kind === 'card' && typeof declaration.icon === 'string' &&
+      /^[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]$/u.test(declaration.icon)),
+    'invalid_manifest', 'Card icon must be one Nerd Font private-use glyph')
     ensure(declaration.border === undefined || (typeof declaration.border === 'boolean' && declaration.kind === 'card'),
       'invalid_manifest', 'Only sidebar cards declare a boolean border preference')
     for (const [key, choices] of Object.entries({ merge: ['by-machine', 'by-identity'], width: ['full', 'half'],

package/src/runtime.mjs

@@ -11,41 +11,41 @@ function boundedText(value, label, limit = 512) {
   return value
 }
 const HOVER_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
-function validateCanvasHover(value) {
+function validatePassiveText(value, limit = LIMITS.canvasHoverBytes, label = 'canvas hover') {
   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`)
+      'invalid_payload', `Invalid ${label} text`)
+    ensure(Buffer.byteLength(value) <= limit,
+      'payload_too_large', `${label} text exceeds ${limit} 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')
+  ensure(Array.isArray(value), 'invalid_payload', `Invalid ${label} spans`)
+  ensure(value.length > 0, 'invalid_payload', `${label} spans must contain text`)
+  ensure(value.length <= 32, 'payload_too_large', `${label} spans exceed 32 spans`)
   let text = ''
   for (const span of value) {
-    ensure(object(span), 'invalid_payload', 'Invalid canvas hover span')
+    ensure(object(span), 'invalid_payload', `Invalid ${label} span`)
     ensure(typeof span.text === 'string' && !HOVER_FORBIDDEN.test(span.text),
-      'invalid_payload', 'Invalid canvas hover span text')
+      'invalid_payload', `Invalid ${label} 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}`)
+          !HOVER_FORBIDDEN.test(span[field]), 'invalid_payload', `Invalid ${label} span ${field}`)
         ensure(Buffer.byteLength(span[field]) <= 64,
-          'payload_too_large', `Canvas hover span ${field} exceeds 64 bytes`)
+          'payload_too_large', `${label} 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}`)
+        'invalid_payload', `Invalid ${label} span ${field}`)
     }
-    ensure(span.actionId === undefined, 'invalid_payload', 'Canvas hover spans cannot contain actionId')
+    ensure(span.actionId === undefined, 'invalid_payload', `${label} 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`)
+    'invalid_payload', `Invalid ${label} text`)
+  ensure(Buffer.byteLength(text) <= limit,
+    'payload_too_large', `${label} text exceeds ${limit} bytes`)
 }
 function validateEntity(entity) {
   ensure(object(entity) && entityKinds.includes(entity.kind), 'invalid_payload', 'Invalid registration entity')
@@ -91,7 +91,13 @@ function validateContent(content, declaration, manifest) {
   ensure(object(content) && CONTENT_KINDS.includes(content.kind), 'invalid_payload', 'Invalid surface content')
   ensure(acceptsContent(kind, content), 'invalid_payload', `A ${kind} contribution cannot show ${content.kind} content`)
   // The view walk bounds depth before serialization visits the tree.
-  if (content.kind === 'view') validateView(content.root, { kind: declaration.kind, manifest })
+  if (content.kind === 'view') {
+    validateView(content.root, { kind: declaration.kind, manifest })
+    if (content.title !== undefined) {
+      ensure(kind === 'card' && Array.isArray(content.title), 'invalid_payload', 'Styled titles belong to card views')
+      validatePassiveText(content.title, 512, 'card title')
+    }
+  }
   jsonBytes(content)
   if (content.kind === 'canvas') {
     const { columns, rows, shade = 0, hover, themeColors } = content.canvas ?? {}
@@ -108,7 +114,7 @@ function validateContent(content, declaration, manifest) {
         'invalid_payload', 'Invalid canvas theme color recipe')
       }
     }
-    if (hover !== undefined) validateCanvasHover(hover)
+    if (hover !== undefined) validatePassiveText(hover)
   }
 }
 

package/src/view.mjs

@@ -231,7 +231,7 @@ const node = (type, fields) => compact({ type, ...fields })
 
 /** Optional builders. Each returns the plain protocol JSON for one node. */
 export const ui = Object.freeze({
-  view: root => ({ kind: 'view', root }),
+  view: (root, { title } = {}) => compact({ kind: 'view', root, title }),
   action: (actionId, { value, opens } = {}) => compact({ actionId, value, opens }),
   span: (value, { tone, weight, mono } = {}) => compact({ text: value, tone, weight, mono }),
   stack: (items, { gap } = {}) => node('stack', { gap, children: items }),