@silo-code/sdk 0.31.0 → 0.32.0

package/src/ActivityGlyph.tsx

@@ -0,0 +1,43 @@
+import type { HTMLAttributes } from "react";
+import {
+  activityClass,
+  type Activity as ActivityKind,
+  type ActivitySize,
+} from "./activity";
+
+/**
+ * Host-painted activity glyph — same look on workspace rows, CenterDock tabs,
+ * and extension UI. Pick an {@link Activity}; the host owns color and motion
+ * (ADR 0030). Omit `activity` only for the workspace-row neutral gray fallback.
+ *
+ * Styled purely via host-provided `.silo-activity*` classes — no stylesheet
+ * import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <ActivityGlyph activity="working" size="md" />
+ * <ActivityGlyph activity="ready" />
+ * <ActivityGlyph size="sm" /> // workspace neutral (omit)
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function ActivityGlyph({
+  activity,
+  size = "sm",
+  className,
+  ...rest
+}: {
+  activity?: ActivityKind;
+  size?: ActivitySize;
+} & Omit<HTMLAttributes<HTMLSpanElement>, "children">) {
+  const classes = activityClass(activity, size);
+  return (
+    <span
+      className={className ? `${classes} ${className}` : classes}
+      aria-hidden={rest["aria-label"] == null ? true : undefined}
+      {...rest}
+    />
+  );
+}

package/src/IconButton.tsx

@@ -1,7 +1,11 @@
 import type { ButtonHTMLAttributes, ReactNode } from "react";
-import { iconButtonClass, type IconButtonSize } from "./icon-button-classes";
+import {
+  iconButtonClass,
+  type IconButtonSize,
+  type IconButtonVariant,
+} from "./icon-button-classes";
 
-export type { IconButtonSize };
+export type { IconButtonSize, IconButtonVariant };
 
 /**
  * A square icon-only button — the kit's one answer for ✕, ⋮, ↻, ✏️, and
@@ -9,18 +13,27 @@ export type { IconButtonSize };
  * label is the accessible name. Pair with {@link Tooltip} so sighted users
  * get the same label on hover.
  *
+ * Sized in terms of `--silo-font-size-base` so the hit target and child SVGs
+ * scale with Silo's UI zoom (`uiFontSize`). Prefer Phosphor `size="1em"`
+ * (or omit a fixed px size) so the glyph tracks the button.
+ *
  * Styled purely via host-provided `.silo-icon-button*` classes — no
  * stylesheet import is needed in the extension.
  *
  * @example
  * ```tsx
  * <IconButton aria-label="Refresh" onClick={refresh}>
- *   <RefreshIcon />
+ *   <RefreshIcon size="1em" />
  * </IconButton>
  *
  * // compact — e.g. in a ListRow's trailing slot
  * <IconButton size="sm" aria-label="Pin" onClick={pin}>
- *   <PinIcon />
+ *   <PinIcon size="1em" />
+ * </IconButton>
+ *
+ * // panel / breadcrumb toolbar (local-web-viewer tone)
+ * <IconButton size="sm" variant="toolbar" aria-label="Mark">
+ *   <FlagIcon size="1em" weight="bold" />
  * </IconButton>
  * ```
  *
@@ -29,19 +42,28 @@ export type { IconButtonSize };
  */
 export function IconButton({
   size = "normal",
+  variant = "normal",
   className,
   type = "button",
   children,
   "aria-label": ariaLabel,
   ...rest
 }: {
-  /** 32px standalone / 26px for tight or inline contexts. */
+  /**
+   * Hit-target size in `em` of `--silo-font-size-base` (tracks Zoom In/Out).
+   * `normal` = 2.5em, `sm` = 2em (local-web-viewer toolbar buttons).
+   */
   size?: IconButtonSize;
+  /**
+   * `"toolbar"` — black/white toolbar-text icons, hover fill only, no
+   * press-scale. Use on editor/terminal breadcrumb clusters and panel bars.
+   */
+  variant?: IconButtonVariant;
   /** Required — the icon is the only visual. */
   "aria-label": string;
   children?: ReactNode;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "aria-label">) {
-  const classes = iconButtonClass(size);
+  const classes = iconButtonClass(size, variant);
   return (
     <button
       type={type}

package/src/activity.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { activityClass, activityFromAgent } from "./activity";
+
+describe("activityClass", () => {
+  it("maps kinds and sizes", () => {
+    expect(activityClass("working", "md")).toBe(
+      "silo-activity silo-activity-working silo-activity-md",
+    );
+    expect(activityClass("ready")).toBe(
+      "silo-activity silo-activity-ready silo-activity-sm",
+    );
+    expect(activityClass("warn", "sm")).toBe(
+      "silo-activity silo-activity-warn silo-activity-sm",
+    );
+    expect(activityClass("error")).toBe(
+      "silo-activity silo-activity-error silo-activity-sm",
+    );
+  });
+
+  it("uses none fallback when activity is omitted", () => {
+    expect(activityClass(undefined)).toBe(
+      "silo-activity silo-activity-none silo-activity-sm",
+    );
+  });
+});
+
+describe("activityFromAgent", () => {
+  it("maps overlapping agent states", () => {
+    expect(activityFromAgent("working")).toBe("working");
+    expect(activityFromAgent("idle")).toBe("ready");
+    expect(activityFromAgent("error")).toBe("error");
+    expect(activityFromAgent("none")).toBeNull();
+    expect(activityFromAgent("dead")).toBeNull();
+  });
+});

package/src/activity.ts

@@ -0,0 +1,57 @@
+import type { AgentActivity } from "./agents-service";
+
+/**
+ * Host-owned activity state for chrome (workspace rows, CenterDock tabs,
+ * SideDock tabs, and the public {@link Activity} glyph). Extensions pick a
+ * kind only — never an icon, color, or motion. See ADR 0030.
+ *
+ * @category Core Types
+ * @public
+ */
+export type Activity = "working" | "ready" | "warn" | "error";
+
+/**
+ * Glyph size for {@link Activity}. `"sm"` matches workspace status rows (~6px);
+ * `"md"` is slightly larger for CenterDock / SideDock tabs.
+ *
+ * @category Core Types
+ * @public
+ */
+export type ActivitySize = "sm" | "md";
+
+/**
+ * Map {@link AgentActivity} onto UI {@link Activity}. Returns `null` when there
+ * is nothing to paint (`none` / `dead` — callers may map `dead` → `"error"`
+ * themselves if they want chrome).
+ *
+ * @category Core Types
+ * @public
+ */
+export function activityFromAgent(a: AgentActivity): Activity | null {
+  switch (a) {
+    case "working":
+      return "working";
+    case "idle":
+      return "ready";
+    case "error":
+      return "error";
+    case "none":
+    case "dead":
+      return null;
+  }
+}
+
+/**
+ * Resolve the host `.silo-activity*` class string. Pinned by unit tests
+ * (RFC 0016 class-contract pattern). When `activity` is omitted, uses the
+ * neutral workspace fallback (gray “none” look).
+ *
+ * @internal
+ */
+export function activityClass(
+  activity: Activity | undefined,
+  size: ActivitySize = "sm",
+): string {
+  const kind = activity ?? "none";
+  return `silo-activity silo-activity-${kind} silo-activity-${size}`;
+}

package/src/editor-service.ts

@@ -1,6 +1,7 @@
 import type { Disposable } from "./types";
 import type { Event } from "./event";
 import type { EditorMode } from "./domain-types";
+import type { TabAdornmentMethods } from "./tab-adornment";
 
 // `ctx.editors` — the editor & document domain (public contract). Opening files
 // into editor tabs, the active-editor save/close commands, the diff-content
@@ -225,10 +226,13 @@ export interface EditorSaveEvent {
  * editors register save handlers. The single entry point for opening editors —
  * prefer it over reaching into workspace/editor state.
  *
+ * Tab chrome adornments (`setIcon` / `setIndicator` / …) take an **editor id**
+ * as the target — see {@link TabAdornmentMethods}.
+ *
  * @category Consumer Services
  * @public
  */
-export interface EditorService {
+export interface EditorService extends TabAdornmentMethods {
   /**
    * Open a file in an editor tab. Promotes an existing preview, focuses an
    * already-open tab, or opens a new one.

package/src/icon-button-classes.test.ts

@@ -5,9 +5,19 @@ describe("iconButtonClass", () => {
   it("defaults to silo-icon-button", () => {
     expect(iconButtonClass()).toBe("silo-icon-button");
     expect(iconButtonClass("normal")).toBe("silo-icon-button");
+    expect(iconButtonClass("normal", "normal")).toBe("silo-icon-button");
   });
 
   it("adds the sm modifier", () => {
     expect(iconButtonClass("sm")).toBe("silo-icon-button silo-icon-button-sm");
   });
+
+  it("adds the toolbar variant", () => {
+    expect(iconButtonClass("normal", "toolbar")).toBe(
+      "silo-icon-button silo-icon-button-toolbar",
+    );
+    expect(iconButtonClass("sm", "toolbar")).toBe(
+      "silo-icon-button silo-icon-button-sm silo-icon-button-toolbar",
+    );
+  });
 });

package/src/icon-button-classes.ts

@@ -6,14 +6,27 @@
  */
 export type IconButtonSize = "normal" | "sm";
 
+/**
+ * Visual tone for {@link IconButton}. `"toolbar"` matches the local-web-viewer
+ * bar buttons (toolbar-text icons, hover fill only, no press-scale).
+ *
+ * @internal
+ */
+export type IconButtonVariant = "normal" | "toolbar";
+
 /**
  * Resolve the host `.silo-icon-button*` class string for an IconButton's
- * `size`. Default is the 32px standalone size; `sm` adds the 26px modifier.
+ * `size` + `variant`. Default is the standalone size; `sm` adds the compact
+ * modifier; `toolbar` swaps in the breadcrumb/panel-toolbar tone.
  *
  * @internal
  */
-export function iconButtonClass(size: IconButtonSize = "normal"): string {
-  return size === "sm"
-    ? "silo-icon-button silo-icon-button-sm"
-    : "silo-icon-button";
+export function iconButtonClass(
+  size: IconButtonSize = "normal",
+  variant: IconButtonVariant = "normal",
+): string {
+  const parts = ["silo-icon-button"];
+  if (size === "sm") parts.push("silo-icon-button-sm");
+  if (variant === "toolbar") parts.push("silo-icon-button-toolbar");
+  return parts.join(" ");
 }

package/src/index.ts

@@ -110,6 +110,37 @@ export type {
   TerminalTabDecorationProvider,
   OscEvent,
 } from "./terminal-service";
+export type {
+  TabAdornmentColor,
+  TabIconAdornment,
+  TabIndicatorAdornment,
+  TabIndicatorFlash,
+  TabActivityAdornment,
+  TabActivityFlash,
+  TabIconContribution,
+  TabIndicatorContribution,
+  TabActivityContribution,
+  TabIconBinder,
+  TabIndicatorBinder,
+  TabActivityBinder,
+  TabAdornmentMethods,
+} from "./tab-adornment";
+export type { Activity, ActivitySize } from "./activity";
+export { activityFromAgent } from "./activity";
+export { ActivityGlyph } from "./ActivityGlyph";
+export type { PhosphorIconName } from "./phosphor-icon";
+export type {
+  ToolbarSurface,
+  ToolbarItemContext,
+  ToolbarItemFields,
+  ToolbarCommandItemContribution,
+  ToolbarMenuItemContribution,
+  ToolbarChromeFields,
+  ToolbarSeparatorContribution,
+  ToolbarSpacerSize,
+  ToolbarSpacerContribution,
+  ToolbarItemContribution,
+} from "./toolbar-items";
 export type {
   FileService,
   FileMeta,
@@ -226,7 +257,7 @@ export { Tooltip } from "./Tooltip";
 export { Button } from "./Button";
 export type { ButtonVariant, ButtonSize } from "./Button";
 export { IconButton } from "./IconButton";
-export type { IconButtonSize } from "./IconButton";
+export type { IconButtonSize, IconButtonVariant } from "./IconButton";
 export { Input } from "./Input";
 export { Textarea } from "./Textarea";
 export { SearchInput } from "./SearchInput";

package/src/phosphor-icon.ts

@@ -0,0 +1,14 @@
+/**
+ * Export name of an icon from `@phosphor-icons/react` — e.g. `"Flag"`,
+ * `"ArrowClockwise"`, `"PushPin"`. The host resolves the name and paints it:
+ * toolbar chrome uses `weight="bold"`; tab decorations use `weight="regular"`
+ * by default (`filled: true` → `weight="fill"`); both use `size="1em"` so
+ * glyphs track UI zoom.
+ *
+ * Use the PascalCase component name from
+ * [Phosphor](https://phosphoricons.com), not a kebab-case path.
+ *
+ * @category Registration
+ * @public
+ */
+export type PhosphorIconName = string;

package/src/tab-adornment.ts

@@ -0,0 +1,208 @@
+import type { ReactNode } from "react";
+import type { Activity } from "./activity";
+import type { PhosphorIconName } from "./phosphor-icon";
+import type { Disposable } from "./types";
+
+/**
+ * Semantic color for a CenterDock tab trailing {@link TabIndicatorAdornment}
+ * (and optional chip background).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabAdornmentColor = "accent" | "warn" | "ok" | "error" | "muted";
+
+/**
+ * Leading identity adornment on a CenterDock tab — arbitrary React artwork
+ * (e.g. an app logo). Set via {@link EditorService.setIcon} /
+ * {@link TerminalService.setIcon}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIconAdornment {
+  /** Extension-owned key; stacking + {@link EditorService.clearIcon} target. */
+  id: string;
+  /** Leading glyph / logo rendered before the tab title. */
+  icon: ReactNode;
+}
+
+/**
+ * Trailing status adornment on a CenterDock tab — static Phosphor glyph.
+ * For busy/ready/warn/error chrome use {@link TabActivityAdornment} instead
+ * (ADR 0030).
+ *
+ * Set via {@link EditorService.setIndicator} /
+ * {@link TerminalService.setIndicator}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIndicatorAdornment {
+  /** Extension-owned key; stacking + clear target. */
+  id: string;
+  /**
+   * Glyph as a {@link PhosphorIconName} (e.g. `"Flag"`). The host resolves
+   * and paints it at 1em in regular weight by default. Set
+   * {@link TabIndicatorAdornment.filled | filled} for Phosphor fill weight;
+   * {@link TabIndicatorAdornment.color | color} tints the glyph; set
+   * {@link TabIndicatorAdornment.chip | chip} for a soft tinted background.
+   */
+  icon: PhosphorIconName;
+  /** Tooltip shown when hovering the indicator. */
+  tooltip?: string;
+  /** Semantic color for the glyph (and chip fill). */
+  color?: TabAdornmentColor;
+  /**
+   * When true, paint a soft tinted chip behind the icon. Default is
+   * glyph-only — no background.
+   */
+  chip?: boolean;
+  /**
+   * When true, paint the glyph with Phosphor `weight="fill"`. Default is
+   * regular weight (outline).
+   */
+  filled?: boolean;
+}
+
+/**
+ * Host-owned {@link Activity} on a CenterDock tab. Extensions pick the kind
+ * (+ optional tooltip); never an icon or color (ADR 0030).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabActivityAdornment {
+  /** Extension-owned key; stacking + clear target. */
+  id: string;
+  activity: Activity;
+  tooltip?: string;
+}
+
+/**
+ * Payload for {@link EditorService.flashIndicator} /
+ * {@link TerminalService.flashIndicator} — timed one-shot; no stable `id`
+ * (auto-cleared after `durationMs`).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIndicatorFlash = TabIndicatorContribution & {
+  /** How long to show the flash. Defaults to host choice (typically ~800ms). */
+  durationMs?: number;
+};
+
+/**
+ * Payload for {@link EditorService.flashActivity} /
+ * {@link TerminalService.flashActivity}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabActivityFlash = TabActivityContribution & {
+  durationMs?: number;
+};
+
+/**
+ * Fields contributed by a {@link TabIconBinder.provide} call (the binder’s
+ * own `id` is applied by the host).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIconContribution = Omit<TabIconAdornment, "id">;
+
+/**
+ * Fields contributed by a {@link TabIndicatorBinder.provide} call.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIndicatorContribution = Omit<TabIndicatorAdornment, "id">;
+
+/**
+ * Fields contributed by a {@link TabActivityBinder.provide} call.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabActivityContribution = Omit<TabActivityAdornment, "id">;
+
+/**
+ * Keep a leading-icon projection in sync for every editor/terminal tab.
+ * Prefer over repeatedly calling {@link EditorService.setIcon}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIconBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-icon"`. */
+  id: string;
+  /**
+   * Called synchronously per tab during render. Return `null` to contribute
+   * nothing for this target id (editor id or terminal session id).
+   */
+  provide(targetId: string): TabIconContribution | null;
+}
+
+/**
+ * Keep a trailing-indicator projection in sync for every editor/terminal tab.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIndicatorBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-indicator"`. */
+  id: string;
+  /**
+   * Called synchronously per tab during render. Return `null` to contribute
+   * nothing for this target id.
+   */
+  provide(targetId: string): TabIndicatorContribution | null;
+}
+
+/**
+ * Keep a trailing-activity projection in sync for every editor/terminal tab.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabActivityBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-activity"`. */
+  id: string;
+  provide(targetId: string): TabActivityContribution | null;
+}
+
+/**
+ * Shared adorn verbs for CenterDock editor and terminal tabs. Implemented by
+ * {@link EditorService} and {@link TerminalService} (target id is the editor
+ * or terminal session id respectively).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabAdornmentMethods {
+  setIcon(targetId: string, adornment: TabIconAdornment): void;
+  clearIcon(targetId: string, adornmentId: string): void;
+  bindIcon(binder: TabIconBinder): Disposable;
+
+  setIndicator(targetId: string, adornment: TabIndicatorAdornment): void;
+  clearIndicator(targetId: string, adornmentId: string): void;
+  flashIndicator(targetId: string, flash: TabIndicatorFlash): void;
+  bindIndicator(binder: TabIndicatorBinder): Disposable;
+
+  setActivity(targetId: string, adornment: TabActivityAdornment): void;
+  clearActivity(targetId: string, adornmentId: string): void;
+  flashActivity(targetId: string, flash: TabActivityFlash): void;
+  bindActivity(binder: TabActivityBinder): Disposable;
+
+  /** All leading icons for `targetId`, in set/bind order. */
+  getIcons(targetId: string): TabIconAdornment[];
+  /** All trailing indicators for `targetId`, in set/bind/flash order. */
+  getIndicators(targetId: string): TabIndicatorAdornment[];
+  /** All trailing activities for `targetId`, in set/bind/flash order. */
+  getActivities(targetId: string): TabActivityAdornment[];
+  /** Signal that binder data changed — re-query `provide` and re-render. */
+  invalidateTabAdornments(): void;
+  subscribeTabAdornments(listener: () => void): Disposable;
+}

package/src/terminal-service.ts

@@ -1,6 +1,9 @@
-import type React from "react";
 import type { Disposable } from "./types";
 import type { TerminalKind, TerminalRecord } from "./domain-types";
+import type {
+  TabAdornmentMethods,
+  TabIndicatorContribution,
+} from "./tab-adornment";
 
 /**
  * A parsed OSC (Operating System Command) escape sequence emitted by a
@@ -26,32 +29,18 @@ export interface OscEvent {
 export type { TerminalKind, TerminalRecord } from "./domain-types";
 
 /**
- * A decoration that an extension can attach to a terminal tab — a small icon
- * with an optional tooltip and semantic color. Registered via
- * {@link TerminalService.registerTabDecoration}.
+ * @deprecated Prefer {@link TerminalService.setIndicator} /
+ * {@link TerminalService.bindIndicator}. Alias for a trailing indicator
+ * contribution (no `id` — the provider id supplies it).
  *
  * @category Consumer Services
  * @public
  */
-export interface TerminalTabDecoration {
-  /**
-   * Small React node rendered as a decoration badge on the tab (≤16 px).
-   * The extension supplies the shape; the host applies `color` via a CSS
-   * data attribute mapped to design tokens.
-   */
-  icon: React.ReactNode;
-  /** Tooltip shown when hovering the decoration icon. */
-  tooltip?: string;
-  /**
-   * Semantic color applied to the icon element. The host maps this to the
-   * matching `--silo-color-*` design token so themes control the exact shade.
-   */
-  color?: "accent" | "warn" | "ok" | "error" | "muted";
-}
+export type TerminalTabDecoration = TabIndicatorContribution;
 
 /**
- * A decoration provider for terminal tabs. Register via
- * {@link TerminalService.registerTabDecoration}.
+ * @deprecated Prefer {@link TerminalService.bindIndicator}. Terminal-only
+ * trailing-indicator provider kept as a shim over the adornment registry.
  *
  * @category Consumer Services
  * @public
@@ -61,8 +50,7 @@ export interface TerminalTabDecorationProvider {
   id: string;
   /**
    * Called synchronously for each terminal tab during render. Return `null`
-   * to contribute nothing for this terminal. When multiple providers are
-   * registered, the first non-null result wins.
+   * to contribute nothing for this terminal.
    */
   provide(terminalId: string): TerminalTabDecoration | null;
 }
@@ -92,10 +80,13 @@ export interface CreateTerminalInput {
  * deleting the workspace. The tab itself is rendered by the core dock from the
  * workspace's terminal records.
  *
+ * Tab chrome adornments (`setIcon` / `setIndicator` / …) take a **terminal
+ * session id** as the target — see {@link TabAdornmentMethods}.
+ *
  * @category Consumer Services
  * @public
  */
-export interface TerminalService {
+export interface TerminalService extends TabAdornmentMethods {
   /**
    * Open a new terminal in a workspace (defaults to the active one). Returns the
    * created {@link TerminalRecord}; the PTY session spawns lazily when its tab
@@ -156,29 +147,24 @@ export interface TerminalService {
   focus(terminalId: string): void;
 
   /**
-   * Register a decoration provider for terminal tabs. The first registered
-   * provider that returns a non-null decoration for a terminal wins; subsequent
-   * providers are not consulted. Returns a {@link Disposable} that unregisters
-   * the provider.
+   * @deprecated Prefer {@link TerminalService.bindIndicator}. Thin shim that
+   * registers a trailing-indicator binder for terminal tabs only.
    */
   registerTabDecoration(provider: TerminalTabDecorationProvider): Disposable;
 
   /**
-   * Get the current decoration for a terminal tab. Returns the first non-null
-   * result from registered providers, or `null` if none apply.
+   * @deprecated Prefer {@link TerminalService.getIndicators}. Returns the first
+   * trailing indicator for a terminal tab, or `null`.
    */
   getTabDecoration(terminalId: string): TerminalTabDecoration | null;
 
   /**
-   * Signal that tab decoration data has changed. Fires all listeners registered
-   * via {@link TerminalService.subscribeTabDecorations}, causing terminal tabs
-   * to re-query providers and re-render their decoration.
+   * @deprecated Prefer {@link TerminalService.invalidateTabAdornments}.
    */
   invalidateTabDecorations(): void;
 
   /**
-   * Subscribe to tab decoration invalidations. Returns a {@link Disposable}
-   * that cancels the subscription.
+   * @deprecated Prefer {@link TerminalService.subscribeTabAdornments}.
    */
   subscribeTabDecorations(listener: () => void): Disposable;