@standardagents/code-plugin-sdk 1.0.0-alpha.7-theme.0 → 1.0.0-alpha.8-title.0

package/README.md

@@ -198,3 +198,20 @@ can install a published prerelease by its exact version.
 ## License
 
 MIT. See `LICENSE`.
+
+Sidebar card titles use muted, regular-weight text. The host prefixes a plugin
+identity icon only on the viewer's Nerd Font symbol tier. Other tiers render
+the title alone. This applies to bordered and borderless cards. Empty titles
+remain empty; no author-supplied icon or font detection is required.
+
+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
+Nerd Font identity icons apply around the author-supplied spans.

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.8-title.0",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",

package/src/index.d.ts

@@ -157,7 +157,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 +410,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/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 }),