@standardagents/code-plugin-sdk 1.0.0-alpha.1 → 1.0.0-alpha.11-headers.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.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -44,6 +44,20 @@ package, such as `@standardagents/code-plugin-sdk/testing`, are refused when
 the plugin runs inside Standard Code. The `testing` export serves the
 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, 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,
+raw host request envelopes, and internal module paths are outside the public
+package exports. First-party plugins use these same public entries and receive
+the same manifest validation, capability checks, request bounds, and remote
+ownership rules as third-party plugins. A plugin ID does not grant a host
+operation or fetch exception.
+
 The runtime disposes publishers, subscriptions, schedules and pending requests.
 Plugins register additional cleanup through `ctx.onDispose` or an activation return value.
 Handlers receive an abort signal.
@@ -148,7 +162,7 @@ The harness starts no subprocesses.
 
 ## Supported interface
 
-The public interface is the package's default export, its `testing` export,
+The public interface is the package root export, its `testing` export,
 the declarations in `src/index.d.ts` and `src/testing.d.ts`, and the
 `standard-plugin` command's `check` and `pack` behavior.
 
@@ -161,15 +175,103 @@ without notice. Plugin code and plugin tests should treat recorded frames as
 opaque values and drive the plugin through `PluginContext` and the harness
 methods.
 
-Local `ctx.state` belongs to one machine.
+`ctx.state` is per-plugin key and value storage. Standard Code stores these
+values in the user's account, so every machine the user has reads and writes
+the same keys. `ctx.state.keys()` returns the sorted key names for this
+plugin's account namespace. It returns an empty array when the plugin has no
+keys and accepts only `RequestOptions`; it has no prefix or pagination
+arguments. Another plugin cannot read these keys, even when it uses the same
+account. Key names are 1 to 128 bytes. The first character is ASCII
+alphanumeric or `_`; later characters are ASCII alphanumeric, `_`, `.`, `:`,
+or `-`. A plugin holds at most 256 keys, and one value is at most 64 KiB of
+JSON. The host applies the same account authority and revocation checks to
+`keys()` as it applies to `get()` and `set()`.
 The public context declarations are in `src/index.d.ts`.
 
 ## Releases
 
 The Standard Code build workflow publishes this package when the version in
-`package.json` changes. Prereleases publish under the `next` dist-tag and
-releases under `latest`.
+`package.json` changes. Main prereleases publish under `next` and main releases
+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`.
+
+## Responsive pane rows
+
+A pane header or footer slot can publish `rows` containing a `layout` and empty
+`spans`. `layout.fields` is an ordered list of passive text fields. The host
+resolves its geometry separately for every viewer, including pane resizes.
+No resize event or producer repaint is needed.
+
+```js
+slot.replace({ kind: 'rows', rows: [{ id: 'status', spans: [], layout: {
+  projectTint: true,
+  fields: [
+    { text: 'org/repo', bold: true },
+    { text: '~/src/repo', gap: 2, flex: true, tone: 'muted',
+      shrink: { priority: 1, min: 8, mode: 'middle' } },
+    { text: ' +24 ', gap: 2, flex: true, tone: 'ok', surface: true },
+    { text: ' −6 ', tone: 'error', surface: true },
+  ],
+} }] })
+```
+
+`gap` reserves 0–8 cells before a field. `flex` distributes spare width across
+marked gaps; related fields without flexible gaps stay together. The first
+field starts at the left edge and the final field reaches the right edge when
+at least one visible flexible gap exists. `projectTint` fills the whole row
+with the pane project's identity tint. `tone` accepts `muted`, `ok`, `error`,
+`info`, `warning`, or `project`; semantic colors resolve against the viewer's
+terminal palette. `surface` shades that field's background and `bold` emphasizes
+its text. Include spaces in a field for padded color blocks.
+
+`icon` is one Nerd Font private-use glyph. `fallback` is an optional ASCII
+replacement (up to 16 bytes); viewers without Nerd Font support use the fallback.
+The host supplies one space after an icon or fallback.
+
+`shrink` policies run by increasing `priority` (0–255), then field order.
+`min` is the retained text width in cells. `start`, `middle`, and `end` select
+where an ellipsis replaces removed text. `hide` removes a field including its
+icon and gap; all hide policies with equal priority are removed together.
+Trimming preserves grapheme boundaries. If the declared minimum widths still
+exceed the pane, remaining content clips at the right edge.
+
+Layouts allow 1–32 fields, 2,048 UTF-8 bytes per text field and 8,192 total text
+bytes. Controls and bidi formatting characters are rejected. Layouts are
+supported only in pane header/footer slots. Ordinary rows and full/half slot
+stacking retain their existing behavior.
+
+Set a card declaration’s `title` to `""` to omit its heading and icon. With
+`border: false`, that also removes the heading row. An omitted title uses the
+plugin name.
+
+Canvas cards can set `CanvasSpec.titleRight` to a passive, right-aligned header label.
+It accepts a nonempty single-line string of up to 512 UTF-8 bytes; controls and
+bidirectional formatting characters are rejected. The host reserves the main
+title and icon, truncates the right label to fit, and preserves the pane-open
+indicator. Other canvas surface kinds reject this option. Update it through
+`canvas.replace({ kind: "canvas", canvas: { ...spec, titleRight: "sidebar-plugins" } })`.