@silo-code/sdk 0.19.1 → 0.21.0

package/dist/types.d.ts

@@ -18,7 +18,6 @@
  * @packageDocumentation
  */
 import type React from "react";
-import type { IDockviewPanelProps } from "dockview";
 import type { ContextKeys } from "./context-keys";
 import type { WorkspaceService } from "./workspace-service";
 import type { EditorService } from "./editor-service";
@@ -33,6 +32,7 @@ import type { DndService } from "./dnd-service";
 import type { UiService } from "./ui-service";
 import type { NetworkService } from "./network-service";
 import type { SystemService } from "./system-service";
+import type { LogService } from "./output-service";
 import type { ExtensionStorage, ExtensionStorageScopes } from "./extension-storage";
 /**
  * The teardown handle returned by every `register*` call on
@@ -48,24 +48,69 @@ export interface Disposable {
     dispose(): void;
 }
 /**
- * The dockview panel API handed to a {@link DockPanelKind} component — used to
- * drive the panel's own tab (title, close, focus). Re-exported from `dockview`
- * so extensions don't take a direct dependency on it.
+ * The panel API handed to a {@link DockPanelKind} component. Use these methods
+ * to drive the panel's own tab (title, close, focus) and update its stored
+ * parameters. The host provides the implementation; extensions never construct
+ * this object directly.
  *
  * @category Core Types
  * @public
  */
-export type DockPanelApi = IDockviewPanelProps["api"];
+export interface DockPanelApi {
+    /** Update the title shown in the panel's tab. */
+    setTitle(title: string): void;
+    /** Programmatically close this panel. */
+    close(): void;
+    /** Bring this panel to focus (make it the active panel in its group). */
+    setActive(): void;
+    /** `true` while this panel is the active one in its dock group. */
+    readonly isActive: boolean;
+    /**
+     * Subscribe to active-state transitions. The listener is called whenever
+     * the panel gains or loses active status, with an event carrying the new
+     * state. Returns a {@link Disposable} that cancels the subscription.
+     */
+    onDidActiveChange(listener: (event: {
+        readonly isActive: boolean;
+    }) => void): Disposable;
+    /**
+     * `true` while this panel is visible — its tab is the selected one in its
+     * group. Distinct from {@link DockPanelApi.isActive | isActive}: with split
+     * groups, every group's selected tab is visible but only one panel in the
+     * whole dock is active.
+     */
+    readonly isVisible: boolean;
+    /**
+     * Subscribe to visibility transitions (the panel's tab being selected or
+     * deselected in its group). Use to pause expensive work while hidden, or to
+     * re-measure on reveal (e.g. the terminal refits xterm when its tab becomes
+     * visible again). Returns a {@link Disposable} that cancels the subscription.
+     */
+    onDidVisibilityChange(listener: (event: {
+        readonly isVisible: boolean;
+    }) => void): Disposable;
+    /**
+     * Shallow-merge `params` into this panel's stored parameters. Keys absent
+     * from `params` are left unchanged. Useful for keeping tabs-serializable
+     * state (e.g. the open URL in a web-viewer panel) consistent with the UI.
+     */
+    updateParameters(params: object): void;
+}
 /**
  * Props handed to a {@link DockPanelKind} component. Use this type to annotate
- * your component instead of importing `IDockviewPanelProps` from `dockview`
- * directly — the SDK wraps it so extensions remain insulated from dockview
- * version changes. The optional generic `T` narrows the shape of `params`.
+ * your component instead of importing from the underlying dock framework
+ * directly — the SDK owns this surface so extensions remain insulated from
+ * host implementation details. The optional generic `T` narrows `params`.
  *
  * @category Core Types
  * @public
  */
-export type DockPanelProps<T extends object = Record<string, unknown>> = IDockviewPanelProps<T>;
+export interface DockPanelProps<T extends object = Record<string, unknown>> {
+    /** The panel API — drives the tab (title, close, focus, params). */
+    api: DockPanelApi;
+    /** Serializable parameters forwarded to the panel at open time. */
+    params: T;
+}
 /**
  * Props passed to an {@link Editor} component. An editor renders the contents of
  * one editor tab (a presenter for a file type — distinct from
@@ -182,8 +227,15 @@ export interface Command {
     id: string;
     /** Human-readable label (shown where the command surfaces in UI). */
     label: string;
-    /** The action. Runs synchronously; do async work inside if needed. */
-    run: () => void;
+    /**
+     * The action. May accept arguments passed through from
+     * {@link ExtensionContext.executeCommand} and may return a value (sync or
+     * async); `executeCommand` resolves with whatever this returns.
+     *
+     * Zero-argument, void-returning commands are still valid — `() => void`
+     * satisfies this type, so existing registrations compile unchanged.
+     */
+    run: (...args: unknown[]) => unknown | Promise<unknown>;
 }
 /**
  * The top-level application menus a {@link MenuItemContribution} can target.
@@ -218,7 +270,13 @@ export interface MenuItemContribution {
      * Defaults to "9_default" so unspecified items land at the bottom.
      */
     group?: string;
-    /** Sort order within a group. Defaults to 0. */
+    /**
+     * Sort order within a group. Defaults to 0.
+     *
+     * **Convention:** built-in (core) items use negative values; extensions
+     * should use `0` or greater so they appear after built-in items within
+     * the same group by default.
+     */
     order?: number;
     /**
      * Optional predicate against current context keys. Items whose `when`
@@ -299,16 +357,19 @@ export interface SidePanel {
 }
 /**
  * Registers a kind of dock panel (a tab that can live in the center dock area,
- * e.g. the terminal). Workspaces open panels of registered kinds by id.
+ * e.g. the terminal). Workspaces open panels of registered kinds by id. The
+ * optional generic `T` is the shape of the params this kind's panels are
+ * opened with — annotate your component with `DockPanelProps<T>` and
+ * {@link ExtensionContext.registerDockPanelKind} infers it, no casts needed.
  *
  * @category Registration
  * @public
  */
-export interface DockPanelKind {
+export interface DockPanelKind<T extends object = Record<string, unknown>> {
     /** Unique id for this panel kind. */
     id: string;
-    /** The React component; receives the raw dockview panel props. */
-    component: React.ComponentType<IDockviewPanelProps>;
+    /** The React component that renders this panel; receives {@link DockPanelProps}. */
+    component: React.ComponentType<DockPanelProps<T>>;
     /**
      * When set, this kind appears as an entry in the center dock's **+** add
      * menu (the per-group header button). Omit to keep the kind internal.
@@ -344,7 +405,19 @@ export interface StatusItem {
     id: string;
     /** Which end of the status bar this item sits at. */
     alignment: "left" | "right";
-    /** Sort order within its alignment group. Lower sorts first. Defaults to 0. */
+    /**
+     * Sort order within its alignment group. Defaults to 0.
+     *
+     * The sort direction mirrors the alignment so that **negative values always
+     * anchor an item toward the nearest edge**:
+     * - **Left items** sort ascending — lower priority = closer to the left edge.
+     * - **Right items** sort descending — lower priority = closer to the right edge.
+     *
+     * **Convention:** built-in (core) items use negative values so they are
+     * anchored to their respective edges. Extensions should use `0` or greater,
+     * which places them between the two built-in zones by default. An extension
+     * may still choose a negative value intentionally to interleave with built-ins.
+     */
     priority?: number;
     /**
      * Tooltip shown on hover over the entire status item. The host renders a
@@ -423,20 +496,37 @@ export interface ExtensionContext {
     registerKeybinding(binding: Keybinding): Disposable;
     /** Register a {@link SidePanel} (a left/right column panel). */
     registerSidePanel(panel: SidePanel): Disposable;
-    /** Register a {@link DockPanelKind} (a center-dock tab kind). */
-    registerDockPanelKind(kind: DockPanelKind): Disposable;
+    /**
+     * Register a {@link DockPanelKind} (a center-dock tab kind). The params
+     * generic `T` is inferred from the component's {@link DockPanelProps}
+     * annotation, so kinds with typed params register without casts.
+     */
+    registerDockPanelKind<T extends object = Record<string, unknown>>(kind: DockPanelKind<T>): Disposable;
     /** Register a {@link StatusItem} (a status-bar widget). */
     registerStatusItem(item: StatusItem): Disposable;
     /** Register a {@link SettingsPage} (a page in the Settings dialog). */
     registerSettingsPage(page: SettingsPage): Disposable;
-    /** Register a {@link ThemePreset} (a selectable theme in the picker). */
+    /**
+     * Register a {@link ThemePreset} (a selectable theme in the picker).
+     * @deprecated Use {@link ThemeService.registerPreset | ctx.theme.registerPreset()} instead.
+     *   This method will be removed in a future release.
+     */
     registerThemePreset(preset: ThemePreset): Disposable;
     /**
      * Invoke a registered command by id — including commands contributed by
      * other extensions. The minimal "operate" primitive; pairs with the typed
      * services for read access.
+     *
+     * Optional positional `args` are forwarded to the command's
+     * {@link Command.run} function. The returned `Promise` resolves with the
+     * command's return value, or rejects if the command throws, is async and
+     * rejects, or the id is not registered. Sync commands dispatch synchronously
+     * before the promise settles, so callers that read state the command mutates
+     * immediately after `await executeCommand(…)` see the updated state.
+     *
+     * @typeParam T - Expected return type of the command (defaults to `unknown`).
      */
-    executeCommand(id: string): void;
+    executeCommand<T = unknown>(id: string, ...args: unknown[]): Promise<T>;
     /**
      * Consumer API for driving workspace state — create, rename, reorder,
      * activate, soft close/reopen, and hard delete. Subscribe to a frozen
@@ -527,6 +617,19 @@ export interface ExtensionContext {
      * See {@link SystemService} for the full API.
      */
     readonly system: SystemService;
+    /**
+     * Write-only structured logger scoped to this extension. Entries appear in
+     * the **Output** panel under the extension's display name. A channel is
+     * created automatically at activation and removed at deactivation — no setup
+     * required.
+     *
+     * ```ts
+     * ctx.log.info("Extension activated");
+     * ctx.log.warn("Unexpected state", { detail: 42 });
+     * ctx.log.show(); // open the Output panel, select this extension's channel
+     * ```
+     */
+    readonly log: LogService;
     /**
      * Resolve a handle to another extension in order to consume the API it
      * published (the value its {@link Extension.activate} returned). This is how

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silo-code/sdk",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "The public, types-first SDK for building Silo extensions — the only surface third-party extensions import.",
   "license": "MIT",
   "author": "Dave Weaver",
@@ -36,9 +36,7 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },
-  "dependencies": {
-    "dockview": "~6.3.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.0",

package/src/context-keys.ts

@@ -11,8 +11,23 @@
  * @public
  */
 export interface ContextKeys {
-  /** id of the viewer rendered by the dock's active panel, or null. */
-  activeViewerId: string | null;
-  /** editorId of the active dock panel if it's an editor panel, or null. */
+  /**
+   * The {@link Editor.id} of the presenter currently rendering the active dock
+   * panel (e.g. `"core.text-editor"`, `"silo.markdown-preview"`), or `null`
+   * when the active panel is not an editor. Identifies the *view type*, not the
+   * tab instance — see {@link ContextKeys.activeEditorId} for the tab record id.
+   */
+  activeEditorViewId: string | null;
+  /**
+   * The `editorId` of the active editor tab record, or `null` when the active
+   * dock panel is not an editor tab. Identifies the *tab instance* — see
+   * {@link ContextKeys.activeEditorViewId} for the view-type (presenter) id.
+   */
   activeEditorId: string | null;
+  /**
+   * @deprecated Use {@link ContextKeys.activeEditorViewId} instead.
+   * Kept for one release so extensions compiled against the old SDK continue
+   * to receive the correct value at runtime without a silent break.
+   */
+  activeViewerId: string | null;
 }

package/src/domain-types.ts

@@ -104,6 +104,11 @@ export type SidePanelSlot = "left" | "right" | "left-bottom" | "right-bottom";
  * A workspace — the unit Silo switches between, keeping its terminals, editors,
  * and layout alive. Read via {@link WorkspaceService}.
  *
+ * This is the public surface: it carries the fields an extension needs to read
+ * (name, folder, open tabs). Layout, scroll, and panel-state fields are
+ * host-internal (`WorkspaceInternal` in `@silo-code/extension-host`) and are
+ * intentionally absent here.
+ *
  * @category Core Types
  * @public
  */
@@ -115,41 +120,15 @@ export interface Workspace {
   extraFolders?: string[];
   createdAt: string;
   lastOpenedAt: string;
-  terminals: TerminalRecord[];
-  /** Editor tabs — text editors and diffs alike (a diff is a record with `mode: "diff"`). */
-  editors: EditorRecord[];
-  dockLayout: unknown | null;
-  /** Scroll positions keyed by editor record ID: { top, left } in pixels. */
-  editorScrollPositions?: Record<string, { top: number; left: number }>;
-  /**
-   * Monaco view states keyed by editor record ID. Each value is the opaque
-   * JSON produced by `editor.saveViewState()` — captures cursor position,
-   * selection, scroll, and folded regions. Supersedes
-   * {@link Workspace.editorScrollPositions} for editors that support it;
-   * scroll-only data is kept as a fallback for older persisted workspaces.
-   */
-  editorViewStates?: Record<string, unknown>;
   /**
    * ISO timestamp of when the workspace was soft-closed, or null/undefined
    * if the workspace is open. Closed workspaces are hidden from the main
    * list and surfaced in a "reopen" picker.
    */
   closedAt?: string | null;
-  /** Per-workspace side panel state — saved/restored on workspace switch. */
-  sidePanelLocations?: Record<string, SidePanelSlot>;
-  sidePanelOrder?: Record<string, number>;
-  activeSidePanelTabs?: Record<string, string>;
-  sidePanelScrollPositions?: Record<string, number>;
-  /** Hidden side panels, keyed by panel id; only an explicit `false` (hidden)
-   * is stored, so an absent key means visible (the default). */
-  sidePanelVisibility?: Record<string, boolean>;
-  extensionState?: Record<string, Record<string, unknown>>;
-  /** Whether the left side column is collapsed. Per-workspace. */
-  leftPanelCollapsed?: boolean;
-  /** Whether the right side column is collapsed. Per-workspace. */
-  rightPanelCollapsed?: boolean;
-  /** ID of the current preview (temporary) editor, if any. */
-  previewEditorId?: string | null;
+  terminals: readonly TerminalRecord[];
+  /** Editor tabs — text editors and diffs alike (a diff is a record with `mode: "diff"`). */
+  editors: readonly EditorRecord[];
 }
 
 /**

package/src/extension-storage.ts

@@ -1,3 +1,5 @@
+import type { Disposable } from "./types";
+
 /**
  * Namespaced, persisted key/value storage handed to extensions. Two scopes are
  * exposed on {@link ExtensionContext.storage} ({@link ExtensionStorageScopes}):
@@ -24,10 +26,13 @@ export interface ExtensionStorage {
   /**
    * Subscribe to changes in this namespace. Called when a value in this
    * namespace changes, when the underlying app state finishes hydrating, and
-   * (for the workspace scope) when the active workspace changes. Returns an
-   * unsubscribe function.
+   * (for the workspace scope) when the active workspace changes.
+   *
+   * Returns a {@link Disposable} — call `.dispose()` to unsubscribe, or push
+   * it onto `ctx.subscriptions` for automatic teardown. Consistent with every
+   * other subscription in the SDK.
    */
-  subscribe(listener: () => void): () => void;
+  subscribe(listener: () => void): Disposable;
 }
 
 /**

package/src/file-service.ts

@@ -24,6 +24,16 @@ export interface FileMeta {
   modifiedMs: number;
 }
 
+/**
+ * The normalized kind of a filesystem change, as delivered in
+ * {@link FileChangeEvent.kind}. Backend-specific event kinds that don't map to
+ * one of the three meaningful values are surfaced as `"other"`.
+ *
+ * @category Core Types
+ * @public
+ */
+export type FileChangeKind = "create" | "modify" | "remove" | "other";
+
 /**
  * A filesystem change event delivered to a {@link FileService.watch} listener,
  * for changes under that watch's path.
@@ -34,8 +44,12 @@ export interface FileMeta {
 export interface FileChangeEvent {
   /** The paths that changed in this event. */
   paths: string[];
-  /** The backend's change kind (e.g. `"create"`, `"modify"`, `"remove"`). */
-  kind: string;
+  /**
+   * Normalized change kind. The host maps the backend's vocabulary to this
+   * closed union; backend-specific kinds that don't match arrive as `"other"`.
+   * Always compare against the union values — never against raw backend strings.
+   */
+  kind: FileChangeKind;
 }
 
 /**

package/src/index.ts

@@ -94,7 +94,12 @@ export type {
   TerminalTabDecorationProvider,
   OscEvent,
 } from "./terminal-service";
-export type { FileService, FileMeta, FileChangeEvent } from "./file-service";
+export type {
+  FileService,
+  FileMeta,
+  FileChangeKind,
+  FileChangeEvent,
+} from "./file-service";
 // Cross-file content search exposed on the ExtensionContext as `ctx.search`.
 export type {
   SearchService,
@@ -157,6 +162,7 @@ export type {
 } from "./ui-service";
 
 // Server-side HTTP client — bypasses CORS, readable response headers.
+export { NetworkError } from "./network-service";
 export type {
   NetworkService,
   NetworkRequestOptions,
@@ -166,6 +172,11 @@ export type {
 // Static host-platform metadata: OS, CPU arch, and Silo version.
 export type { SystemService, SystemInfo } from "./system-service";
 
+// Structured output logging — the write-only channel extensions receive as
+// `ctx.log`. LogLevel is also used by the Output panel's built-in channels
+// (e.g. `silo:notifications`).
+export type { LogService, LogLevel } from "./output-service";
+
 // Context keys referenced by `when` predicates on menu items / keybindings.
 export type { ContextKeys } from "./context-keys";
 

package/src/layout-service.ts

@@ -60,9 +60,23 @@ export interface LayoutService {
    * web-viewer tab). No-op when the center dock has no active workspace.
    *
    * @param kindId - The {@link DockPanelKind.id} to instantiate.
-   * @param params - Arbitrary params forwarded to the panel's
-   *   `IDockviewPanelProps`. Serialized into `ws.dockLayout` so URL/state
-   *   survives workspace close/reopen.
+   * @param params - Arbitrary params forwarded to the panel component.
+   *   Serialized into `ws.dockLayout` so state survives workspace
+   *   close/reopen.
+   * @param options - `singleton: true` opens at most one instance at a time:
+   *   if a panel with `kindId` already exists, it is focused instead of
+   *   creating a new one. The panel's id equals `kindId` (not UUID-based) when
+   *   singleton is set.
    */
-  openPanel(kindId: string, params?: Record<string, unknown>): void;
+  openPanel(
+    kindId: string,
+    params?: Record<string, unknown>,
+    options?: { singleton?: boolean },
+  ): void;
+  /**
+   * Open a **singleton** dock panel.
+   * @deprecated Use `openPanel(kindId, params, { singleton: true })` instead.
+   *   This method will be removed in a future release.
+   */
+  openSingletonPanel(kindId: string, params?: Record<string, unknown>): void;
 }

package/src/network-service.ts

@@ -1,3 +1,35 @@
+/**
+ * Thrown by {@link NetworkService.fetch} and {@link NetworkService.fetchHeaders}
+ * when a request fails (network error, DNS failure, TLS error, timeout, etc.).
+ *
+ * ```ts
+ * try {
+ *   const res = await ctx.net.fetch("https://api.example.com/data");
+ * } catch (err) {
+ *   if (err instanceof NetworkError) {
+ *     console.error(`Request to ${err.url} failed: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export class NetworkError extends Error {
+  /** The URL that was requested when the error occurred. */
+  readonly url: string;
+
+  constructor(url: string, message: string) {
+    super(message);
+    this.name = "NetworkError";
+    this.url = url;
+    // Restore the prototype chain so `instanceof` works across the down-leveled
+    // class output the SDK ships (and across the host↔extension boundary, where
+    // there's a single shared SDK instance).
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+}
+
 /**
  * Options for {@link NetworkService.fetch} and {@link NetworkService.fetchHeaders}.
  *
@@ -62,7 +94,7 @@ export interface NetworkService {
    *
    * @param url - The URL to fetch.
    * @param options - Method, headers, body, redirect and timeout controls.
-   * @throws A string error message if the request fails (network error, DNS
+   * @throws {@link NetworkError} if the request fails (network error, DNS
    *   failure, TLS error, etc.).
    *
    * @example
@@ -83,7 +115,7 @@ export interface NetworkService {
    * @param url - The URL to probe.
    * @param options - Redirect and timeout controls (`method` and `body` are
    *   ignored — this is always a HEAD request).
-   * @throws A string error message if the request fails.
+   * @throws {@link NetworkError} if the request fails.
    *
    * @example
    * ```ts

package/src/output-service.ts

@@ -0,0 +1,43 @@
+/**
+ * Output channel logging — the write-only structured logger extensions receive
+ * as {@link ExtensionContext.log}. Each extension gets one channel
+ * auto-created at activation and auto-removed at deactivation; no setup is
+ * required from the extension author.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Log severity levels, ordered debug < info < warn < error.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * Write-only structured logger automatically scoped to the calling extension.
+ * A channel is created for the extension at activation time and removed when
+ * the extension deactivates — no setup needed; just call `ctx.log.info("...")`.
+ *
+ * All entries appear in the **Output** panel (`core.openOutput`) under the
+ * extension's display name. Use {@link LogService.show} to focus the panel and
+ * select this extension's channel.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface LogService {
+  /** Append a debug-level entry. Use for verbose diagnostic output. */
+  debug(message: string, data?: unknown): void;
+  /** Append an info-level entry. The default level for routine progress. */
+  info(message: string, data?: unknown): void;
+  /** Append a warn-level entry. Something unexpected but recoverable. */
+  warn(message: string, data?: unknown): void;
+  /** Append an error-level entry. A failure the user should know about. */
+  error(message: string, data?: unknown): void;
+  /** Open (or focus) the Output panel and select this extension's channel. */
+  show(): void;
+  /** Clear this extension's output channel entries. */
+  clear(): void;
+}

package/src/terminal-service.ts

@@ -168,4 +168,35 @@ export interface TerminalService {
     terminalId: string,
     handler: (event: OscEvent) => void,
   ): Disposable;
+
+  /**
+   * The record id of the terminal tab that is currently active in the active
+   * workspace's center dock, or `null` when an editor tab (or nothing) is
+   * active. "Active" is the dock's single active panel — the tab the user is
+   * looking at and typing into — so a terminal merely visible in a non-active
+   * split does not count.
+   */
+  getActive(): string | null;
+
+  /**
+   * Subscribe to active-terminal changes. The listener receives the terminal
+   * record id whenever a terminal tab becomes the active center-dock panel,
+   * and `null` when activation moves elsewhere (an editor tab, or no panel —
+   * including transiently during a workspace switch, before the incoming
+   * workspace's active tab is published).
+   *
+   * Fires on tab activation, group activation, and workspace switches.
+   * Returns a {@link Disposable} that cancels the subscription.
+   *
+   * @example
+   * ```ts
+   * // Clear a "needs attention" marker once the user views the terminal.
+   * ctx.subscriptions.push(
+   *   ctx.terminals.subscribeActive((terminalId) => {
+   *     if (terminalId) attention.delete(terminalId);
+   *   }),
+   * );
+   * ```
+   */
+  subscribeActive(listener: (terminalId: string | null) => void): Disposable;
 }