@standardagents/code-plugin-sdk 1.0.0-alpha.6-surfaces.0 → 1.0.0-alpha.8-title.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.6-surfaces.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.6-surfaces.0" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.7-theme.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.7-theme.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -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/REFERENCE.md

@@ -31,7 +31,14 @@ 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`
+A `card` declaration draws a sidebar card. Its optional `border` boolean
+defaults to `true`. Set `border: false` for a borderless group: the host
+retains the author title, content padding, focus indication, and activation
+behavior, and removes the outline and bottom border row. This preference
+is declared by each plugin on its own cards; other surface kinds reject it.
+The nested view node named `card` is a separate content element.
+
+`validateManifest`
 refuses a card whose anchor is not `plugins`. Two optional fields control
 panels:
 
@@ -509,3 +516,21 @@ 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.
+
+### Canvas theme colors
+
+`CanvasSpec.themeColors` maps up to 32 canvas-local ANSI indexes (0–255) to
+recipes. Each recipe has `source` (optional ANSI index 0–15, omitted for the
+default foreground), `mix` (optional second ANSI index mixed equally), and
+`opacity` (0–1, blended against the viewer background). Both foreground and
+background SGR references to that index resolve through the same recipe.
+For example, `{ 16: { source: 4, opacity: 0.72 }, 20: { opacity: 0.4 } }`
+provides muted terminal blue at index 16 and a subtle foreground at index 20.
+
+Resolution occurs in the viewer for sidebar, pane, slot, column, and popover
+canvases. Remote producers do not read or bake another machine's colors.
+Recipes remain unchanged across terminal theme updates. Unavailable source
+colors fall back to the named ANSI index or default foreground; unavailable
+background colors leave opacity unapplied. OSC queries remain unsupported
+in plugin canvas streams. This capability is public and identical for all
+plugins.

package/package.json

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

package/src/index.d.ts

@@ -1,7 +1,7 @@
 export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
 export type Capability = 'surfaces' | 'events' | 'hooks' | 'panes' | 'projects' |
   'notifications' | 'url' | 'fetch' | 'secrets' | 'webhook';
-/** `card` draws a boxed card in the sidebar under the `plugins` anchor. */
+/** `card` draws a sidebar card under the `plugins` anchor, with an optional border. */
 export type SurfaceKind = 'section' | 'card' | 'slot' | 'badge' | 'panel' | 'overlay' |
   'menu' | 'command' | 'key' | 'link';
 /** How a panel opens. Absent means `popover`. */
@@ -14,6 +14,8 @@ export interface ContributionDeclaration {
   id: string;
   kind: SurfaceKind;
   anchor: Anchor;
+  /** Sidebar card border. Defaults to true; false retains the title and content padding. */
+  border?: boolean;
   title?: string;
   merge?: 'by-machine' | 'by-identity';
   width?: 'full' | 'half';
@@ -84,7 +86,17 @@ export type TextContent = { kind: 'text'; lines: TextSpan[][] };
 export type BadgeContent = { kind: 'badge'; spans: TextSpan[]; actionId?: string };
 export type NativeContent = RowsContent | TextContent | BadgeContent;
 /** `columns` is also the intrinsic width of a card, column, or plugin pane that shows the canvas. */
+export interface CanvasThemeColor {
+  /** ANSI palette index 0..15; omitted uses the viewer's default foreground. */
+  source?: number;
+  /** Optional second ANSI palette index, mixed equally with source. */
+  mix?: number;
+  /** Blend against the viewer background, from 0 to 1. */
+  opacity: number;
+}
 export interface CanvasSpec {
+  /** Up to 32 canvas-local indexed color recipes. Keys are ANSI indexes 0..255. */
+  themeColors?: Record<number, CanvasThemeColor>;
   columns: number;
   rows: number;
   transparent?: boolean;
@@ -145,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;
@@ -398,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/manifest.mjs

@@ -76,6 +76,8 @@ 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.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'],
       position: ['top', 'after-open', 'before-danger', 'bottom'], presentation: PRESENTATIONS })) {
       ensure(declaration[key] === undefined || choices.includes(declaration[key]), 'invalid_manifest', `Invalid contribution ${key}`)

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,14 +91,30 @@ 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 } = content.canvas ?? {}
+    const { columns, rows, shade = 0, hover, themeColors } = 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)
+    if (themeColors !== undefined) {
+      ensure(object(themeColors) && Object.keys(themeColors).length <= 32, 'invalid_payload', 'Invalid canvas theme colors')
+      for (const [index, recipe] of Object.entries(themeColors)) {
+        ensure(/^(0|[1-9][0-9]{0,2})$/.test(index) && Number(index) <= 255 && object(recipe) &&
+          Object.keys(recipe).every(key=>['source','mix','opacity'].includes(key)) &&
+          ['source','mix'].every(key=>recipe[key] === undefined || (Number.isInteger(recipe[key]) && recipe[key]>=0 && recipe[key]<16)) &&
+          Number.isFinite(recipe.opacity) && recipe.opacity>=0 && recipe.opacity<=1,
+        'invalid_payload', 'Invalid canvas theme color recipe')
+      }
+    }
+    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 }),