@silo-code/sdk 0.31.0 → 0.33.0

package/src/tab-adornment.ts

@@ -0,0 +1,261 @@
+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;
+}
+
+/**
+ * Soft tinted highlight across the entire CenterDock tab (icon, title, and
+ * every other adornment) — not just the label. Contributing one (via `set`
+ * or a `bind` that returns non-`null`) is itself the on/off signal; there's
+ * no separate boolean. At most one applies per tab — if multiple extensions
+ * contribute one for the same target, the first found wins.
+ *
+ * Set via {@link EditorService.setHighlight} / {@link TerminalService.setHighlight}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabHighlightAdornment {
+  /** Extension-owned key; clear target. */
+  id: string;
+  /** Semantic color for the highlight fill. Defaults to `"accent"`. */
+  color?: TabAdornmentColor;
+}
+
+/**
+ * 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 TabHighlightBinder.provide} call.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabHighlightContribution = Omit<TabHighlightAdornment, "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 whole-tab highlight projection in sync for every editor/terminal
+ * tab.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabHighlightBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-highlight"`. */
+  id: string;
+  /**
+   * Called synchronously per tab during render. Return `null` to contribute
+   * no highlight for this target id.
+   */
+  provide(targetId: string): TabHighlightContribution | 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;
+
+  setHighlight(targetId: string, adornment: TabHighlightAdornment): void;
+  clearHighlight(targetId: string, adornmentId: string): void;
+  bindHighlight(binder: TabHighlightBinder): 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[];
+  /**
+   * The whole-tab highlight for `targetId`, or `null` if none. At most one
+   * applies — first found across `set`/`bind` order.
+   */
+  getHighlight(targetId: string): TabHighlightAdornment | null;
+  /** 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;
 

package/src/toolbar-items.ts

@@ -0,0 +1,190 @@
+import type { ContextKeys } from "./context-keys";
+import type { PhosphorIconName } from "./phosphor-icon";
+import type { MenuEntry } from "./ui-service";
+
+/**
+ * Built-in CenterDock surfaces that accept
+ * {@link ToolbarItemContribution}s. One surface per registration.
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarSurface = "editor" | "terminal";
+
+/**
+ * The typed target each {@link ToolbarSurface} passes to an invoked command
+ * and to `when` / `checked` / {@link ToolbarMenuItemContribution.menu} builders.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarItemContext {
+  editor: { editorId: string };
+  terminal: { terminalId: string };
+}
+
+/**
+ * Shared fields for interactive toolbar contributions. Render chrome is driven
+ * by {@link ToolbarItemFields.icon | icon} + {@link ToolbarItemFields.title | title}:
+ *
+ * | icon | title | Control        |
+ * | ---- | ----- | -------------- |
+ * | ✓    | —     | icon-only      |
+ * | —    | ✓     | text-only      |
+ * | ✓    | ✓     | icon + text    |
+ *
+ * Icons are Phosphor export names ({@link PhosphorIconName}); the host
+ * resolves and paints them bold at 1em so they match local-web-viewer and
+ * track UI zoom. Pass a React node is no longer supported — use the name.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarItemFields<S extends ToolbarSurface = ToolbarSurface> {
+  /** Unique id for this contribution. */
+  id: string;
+  /** Which toolbar to contribute to. */
+  surface: S;
+  /**
+   * Leading glyph as a {@link PhosphorIconName} (e.g. `"Flag"`). Omit for a
+   * text-only control (requires {@link ToolbarItemFields.title | title}).
+   */
+  icon?: PhosphorIconName;
+  /**
+   * Visible label painted in the control. Omit for icon-only. When both
+   * `icon` and `title` are set, the host renders icon + text.
+   */
+  title?: string;
+  /** Hover tooltip (falls back to title / label / command label). */
+  tooltip?: string;
+  /**
+   * Accessible name (falls back to title / the command's label). Always used
+   * for `aria-label`; not painted unless {@link ToolbarItemFields.title | title}
+   * is also set.
+   */
+  label?: string;
+  /** Ordering within the trailing cluster; lower sorts first. */
+  order?: number;
+  /**
+   * Visibility predicate. Returning false hides the item for this target.
+   */
+  when?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+  /**
+   * Toggle-state predicate for command items. When provided, the host renders
+   * the control in a pressed/checked visual state whenever this returns true.
+   * Menu items put checks on individual {@link MenuEntry} rows instead.
+   */
+  checked?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+}
+
+/**
+ * Command-backed toolbar control — click runs {@link ToolbarCommandItemContribution.command}.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarCommandItemContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarItemFields<S> {
+  /** The command to run; receives {@link ToolbarItemContext}[S] as its first arg. */
+  command: string;
+  menu?: undefined;
+  type?: undefined;
+}
+
+/**
+ * Menu-backed toolbar control — click opens a host dropdown via
+ * {@link UiService.showMenu} with entries from
+ * {@link ToolbarMenuItemContribution.menu}.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarMenuItemContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarItemFields<S> {
+  /**
+   * Build the dropdown for this target. May be sync or async. The host
+   * anchors the menu on the toolbar control (`align: "end"`, toggle on).
+   */
+  menu: (target: ToolbarItemContext[S]) => MenuEntry[] | Promise<MenuEntry[]>;
+  command?: undefined;
+  type?: undefined;
+}
+
+/**
+ * Shared placement fields for non-interactive toolbar chrome
+ * ({@link ToolbarSeparatorContribution} / {@link ToolbarSpacerContribution}).
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarChromeFields<
+  S extends ToolbarSurface = ToolbarSurface,
+> {
+  id: string;
+  surface: S;
+  order?: number;
+  when?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+}
+
+/**
+ * A light vertical rule between toolbar controls. Softer than the Text |
+ * Preview pipe — host paints it with a low-opacity mix of toolbar text, not
+ * `--silo-color-toolbar-text-disabled`.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarSeparatorContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarChromeFields<S> {
+  type: "separator";
+}
+
+/**
+ * Gap size for {@link ToolbarSpacerContribution}. Maps to em of the toolbar
+ * font (`sm` 0.25em / `md` 0.5em / `lg` 0.75em).
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarSpacerSize = "sm" | "md" | "lg";
+
+/**
+ * An empty gap between toolbar controls (no rule). Use to group without a
+ * hard split; prefer {@link ToolbarSeparatorContribution} when a hairline helps.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarSpacerContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarChromeFields<S> {
+  type: "spacer";
+  /** Default `"md"`. */
+  size?: ToolbarSpacerSize;
+}
+
+/**
+ * Adds a control or chrome element to the trailing cluster of a built-in
+ * editor or terminal toolbar. Register via
+ * {@link ExtensionContext.registerToolbarItem}.
+ *
+ * Interactive items set exactly one of
+ * {@link ToolbarCommandItemContribution.command | command} or
+ * {@link ToolbarMenuItemContribution.menu | menu}. Separators and spacers use
+ * `type: "separator" | "spacer"`.
+ *
+ * Contributions are independent of context-menu items — an extension may
+ * register either, both, or neither. Hosts only render items while that
+ * surface's breadcrumbs setting is on.
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarItemContribution<S extends ToolbarSurface = ToolbarSurface> =
+  | ToolbarCommandItemContribution<S>
+  | ToolbarMenuItemContribution<S>
+  | ToolbarSeparatorContribution<S>
+  | ToolbarSpacerContribution<S>;

package/src/types.ts

@@ -47,6 +47,7 @@ import type {
   ExtensionStorage,
   ExtensionStorageScopes,
 } from "./extension-storage";
+import type { ToolbarItemContribution, ToolbarSurface } from "./toolbar-items";
 
 /**
  * The teardown handle returned by every `register*` call on
@@ -630,6 +631,22 @@ export interface ExtensionContext {
   registerContextMenuItem<S extends MenuSurface>(
     item: ContextMenuContribution<S>,
   ): Disposable;
+  /**
+   * Register a {@link ToolbarItemContribution} (icon-only, text-only,
+   * icon+text, or dropdown) in the trailing cluster of an editor or terminal
+   * toolbar. Independent of {@link ExtensionContext.registerContextMenuItem}
+   * — register either, both, or neither. Hosts only show items while that
+   * surface's breadcrumbs setting is on. See
+   * {@link ExtensionContext.invalidateToolbarItems}.
+   */
+  registerToolbarItem<S extends ToolbarSurface>(
+    item: ToolbarItemContribution<S>,
+  ): Disposable;
+  /**
+   * Signal that toolbar-item `when` / `checked` data changed. Causes editor
+   * and terminal toolbars to re-query contributions and re-render.
+   */
+  invalidateToolbarItems(): void;
   /** Register a {@link Keybinding} (bind a shortcut to a command). */
   registerKeybinding(binding: Keybinding): Disposable;
   /** Register a {@link SidePanel} (a left/right column panel). */