@standardagents/code-plugin-sdk 1.0.0-alpha.5-usage.0 → 1.0.0-alpha.7-theme.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.5-usage.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.5-usage.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",

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:
 
@@ -234,6 +241,11 @@ add node types.
 
 ### Card views
 
+Titles come from the contribution's `title`. The host adds no status dot,
+health text, or machine label to a card title or panel. Authors can include
+indicators in their own title or content. Runtime health remains available in
+plugin management through `ctx.health.set()`.
+
 A card shows a short summary. Its view can contain `stack`, `row`, `text`,
 `badge`, `dot`, `progress`, `segments`, `stat`, and `divider` nodes, and it
 is at most 6 lines tall. A `stack` is as tall as its children plus `gap`
@@ -346,8 +358,8 @@ contributions when their target disappears or changes generation.
 
 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
+panel presentations are implemented. A popover follows the content width and height within the
+modal area. Its title is the contribution title and its body starts beneath it. 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.
 
@@ -504,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.5-usage.0",
+  "version": "1.0.0-alpha.7-theme.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;

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

@@ -94,10 +94,20 @@ function validateContent(content, declaration, manifest) {
   if (content.kind === 'view') validateView(content.root, { kind: declaration.kind, manifest })
   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 (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) validateCanvasHover(hover)
   }
 }