Interface: EditorService

Defined in: packages/sdk/src/editor-service.ts:235

The editor & document domain, exposed as ExtensionContext.editors. Open files into editor tabs, drive the active editor (save / close), and let 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 TabAdornmentMethods.

Extends

TabAdornmentMethods

Properties

onDidSave

onDidSave: Event<EditorSaveEvent>;

Defined in: packages/sdk/src/editor-service.ts:331

Fires after an editor tab's contents are saved to disk — a formatter, linter, or build-on-save extension's entry point. See Event.

Example

ctx.subscriptions.push(
  ctx.editors.onDidSave(({ editorId, filePath }) => {
    ctx.log.info(`saved ${filePath}`);
  }),
);

Methods

open()

open(path, opts?): void;

Defined in: packages/sdk/src/editor-service.ts:240

Open a file in an editor tab. Promotes an existing preview, focuses an already-open tab, or opens a new one.

Parameters

path

string

opts?

OpenFileOptions

Returns

void

openUntitled()

openUntitled(opts?): void;

Defined in: packages/sdk/src/editor-service.ts:242

Open a fresh untitled editor.

Parameters

opts?

OpenFileOptions

Returns

void

openDiff()

openDiff(spec, opts?): void;

Defined in: packages/sdk/src/editor-service.ts:247

Open a diff view. The content is supplied by the provider named in spec — the editor itself is content-agnostic.

Parameters

spec

OpenDiffSpec

opts?

OpenFileOptions

Returns

void

save()

save(): boolean;

Defined in: packages/sdk/src/editor-service.ts:249

Save the active editor. Returns false if there's no active saveable editor.

Returns

boolean

saveAs()

saveAs(): boolean;

Defined in: packages/sdk/src/editor-service.ts:251

Save-as the active editor. Returns false if unavailable.

Returns

boolean

closeActive()

closeActive(): boolean;

Defined in: packages/sdk/src/editor-service.ts:253

Close the active dock panel. Returns false if there's nothing to close.

Returns

boolean

editorsFor()

editorsFor(path): EditorViewInfo[];

Defined in: packages/sdk/src/editor-service.ts:262

List the editor views that match path (or null for an untitled buffer), highest-priority first, each flagged whether it's the one the host resolves by default. Read-only enumeration for building "Open With" menus and the breadcrumb view-switcher. Returns [] only when nothing matches — in practice never empty for a real path, since the core text editor matches everything.

Parameters

path

string | null

Returns

EditorViewInfo[]

setViewType()

setViewType(
   editorId, 
   viewType, 
   opts?): void;

Defined in: packages/sdk/src/editor-service.ts:271

Switch an already-open editor tab to a different view in place — without closing and reopening it — and persist the choice on the tab. No-op if the editor isn't found, viewType names no registered editor, or that editor doesn't match the tab's file. The panel remounts onto the new view, so per-instance state (scroll, selection) resets — expected, it's a different presenter.

Parameters

editorId

string

viewType

string

opts?

workspaceId?

string

Returns

void

registerSaveHandler()

registerSaveHandler(editorId, handlers): Disposable;

Defined in: packages/sdk/src/editor-service.ts:281

Register save handlers for an editor instance (by its editorId), so the active-editor save / saveAs dispatch to it while it's focused. Dispose to unregister (do this when the editor unmounts).

Parameters

editorId

string

handlers

EditorSaveHandlers

Returns

Disposable

registerDiffContentProvider()

registerDiffContentProvider(providerId, provider): Disposable;

Defined in: packages/sdk/src/editor-service.ts:290

Register a DiffContentProvider under providerId. A diff opened with that providerId (see OpenDiffSpec) resolves its two sides through this provider, on every mount. Dispose to unregister.

Parameters

providerId

string

provider

DiffContentProvider

Returns

Disposable

getText()

getText(editorId): Promise<string | undefined>;

Defined in: packages/sdk/src/editor-service.ts:311

The current buffer text of an open editor tab, including unsaved edits.

Resolves undefined when the tab isn't text-backed (e.g. the image viewer), has never mounted a text document, and has no retained unsaved buffer. A dirty text editor that unmounts on a view switch (e.g. Text → Markdown Preview) retains its buffer so presenters can still read it. A lazy-mounted dock panel is not force-mounted to read its text. It is async precisely because the live text lives in the mounted editor component, not in host state.

Parameters

editorId

string

Returns

Promise<string | undefined>

Example

const text = await ctx.editors.getText(editorId);
if (text !== undefined) ctx.log.info(`${text.length} chars`);

isDirty()

isDirty(editorId): boolean;

Defined in: packages/sdk/src/editor-service.ts:317

Whether an open editor tab has unsaved changes. Returns false for an unknown id or a tab that isn't text-backed and has no retained dirty buffer. Stays true across a dirty Text → Preview view switch.

Parameters

editorId

string

Returns

boolean

getState()

getState(): EditorsState;

Defined in: packages/sdk/src/editor-service.ts:344

Current frozen snapshot of editor state. The returned object is referentially stable between renders — getState() === getState() when nothing has changed, which satisfies useSyncExternalStore's contract and means useServiceState(ctx.editors) works without extra memoization.

Returns

EditorsState

Example

const { active } = ctx.editors.getState();
if (active) ctx.log.info(`Active file: ${active.filePath ?? "(untitled)"}`);

subscribe(listener): Disposable;

Defined in: packages/sdk/src/editor-service.ts:363

Subscribe to changes in the active editor. The listener is called whenever active changes (tab focus moves, workspace switches, editor opens or closes) or hydrated flips. Returns a Disposable that cancels the subscription.

Use useServiceState(ctx.editors) in React components instead of calling subscribe directly — it wraps getState + subscribe for you.

Parameters

listener

(state) => void

Returns

Disposable

Example

ctx.subscriptions.push(
  ctx.editors.subscribe(({ active }) => {
    statusItem.setTitle(active?.filePath ?? "No file");
  }),
);

setIcon()

setIcon(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:229

Parameters

targetId

string

adornment

TabIconAdornment

Returns

void

Inherited from

TabAdornmentMethods.setIcon

clearIcon()

clearIcon(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:230

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearIcon

bindIcon()

bindIcon(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:231

Parameters

setHighlight()

setHighlight(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:233

Parameters

targetId

string

adornment

TabHighlightAdornment

Returns

void

Inherited from

TabAdornmentMethods.setHighlight

clearHighlight()

clearHighlight(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:234

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearHighlight

bindHighlight()

bindHighlight(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:235

Parameters

binder

TabHighlightBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindHighlight

setIndicator()

setIndicator(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:237

Parameters

targetId

string

adornment

TabIndicatorAdornment

Returns

void

Inherited from

TabAdornmentMethods.setIndicator

clearIndicator()

clearIndicator(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:238

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearIndicator

flashIndicator()

flashIndicator(targetId, flash): void;

Defined in: packages/sdk/src/tab-adornment.ts:239

Parameters

targetId

string

flash

TabIndicatorFlash

Returns

void

Inherited from

TabAdornmentMethods.flashIndicator

bindIndicator()

bindIndicator(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:240

Parameters

binder

TabIndicatorBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindIndicator

setActivity()

setActivity(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:242

Parameters

targetId

string

adornment

TabActivityAdornment

Returns

void

Inherited from

TabAdornmentMethods.setActivity

clearActivity()

clearActivity(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:243

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearActivity

flashActivity()

flashActivity(targetId, flash): void;

Defined in: packages/sdk/src/tab-adornment.ts:244

Parameters

targetId

string

flash

TabActivityFlash

Returns

void

Inherited from

TabAdornmentMethods.flashActivity

bindActivity()

bindActivity(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:245

Parameters

binder

TabActivityBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindActivity

getIcons()

getIcons(targetId): TabIconAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:248

All leading icons for targetId, in set/bind order.

Parameters

targetId

string

Returns

TabIconAdornment[]

Inherited from

TabAdornmentMethods.getIcons

getHighlight()

getHighlight(targetId): TabHighlightAdornment | null;

Defined in: packages/sdk/src/tab-adornment.ts:253

The whole-tab highlight for targetId, or null if none. At most one applies — first found across set/bind order.

Parameters

targetId

string

Returns

TabHighlightAdornment | null

Inherited from

TabAdornmentMethods.getHighlight

getIndicators()

getIndicators(targetId): TabIndicatorAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:255

All trailing indicators for targetId, in set/bind/flash order.

Parameters

targetId

string

Returns

TabIndicatorAdornment[]

Inherited from

TabAdornmentMethods.getIndicators

getActivities()

getActivities(targetId): TabActivityAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:257

All trailing activities for targetId, in set/bind/flash order.

Parameters

targetId

string

Returns

TabActivityAdornment[]

Inherited from

TabAdornmentMethods.getActivities

invalidateTabAdornments()

invalidateTabAdornments(): void;

Defined in: packages/sdk/src/tab-adornment.ts:259

Signal that binder data changed — re-query provide and re-render.

Returns

void

Inherited from

TabAdornmentMethods.invalidateTabAdornments

subscribeTabAdornments()

subscribeTabAdornments(listener): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:260

Parameters

listener

() => void

Returns

Disposable

Inherited from

TabAdornmentMethods.subscribeTabAdornments

Interface: EditorService ​

Extends ​

Properties ​

onDidSave ​

Example ​

Methods ​

open() ​

Parameters ​

path ​

opts? ​

Returns ​

openUntitled() ​

Parameters ​

opts? ​

Returns ​

openDiff() ​

Parameters ​

spec ​

opts? ​

Returns ​

save() ​

Returns ​

saveAs() ​

Returns ​

closeActive() ​

Returns ​

editorsFor() ​

Parameters ​

path ​

Returns ​

setViewType() ​

Parameters ​

editorId ​

viewType ​

opts? ​

workspaceId? ​

Returns ​

registerSaveHandler() ​

Parameters ​

editorId ​

handlers ​

Returns ​

registerDiffContentProvider() ​

Parameters ​

providerId ​

provider ​

Returns ​

getText() ​

Parameters ​

editorId ​

Returns ​

Example ​

isDirty() ​

Parameters ​

editorId ​

Returns ​

getState() ​

Returns ​

Example ​

subscribe() ​

Parameters ​

listener ​

Returns ​

Example ​

setIcon() ​

Parameters ​

targetId ​

adornment ​

Returns ​

Inherited from ​

clearIcon() ​

Parameters ​

targetId ​

adornmentId ​

Returns ​

Inherited from ​

bindIcon() ​

Parameters ​

binder ​

Returns ​

Interface: EditorService

Extends

Properties

onDidSave

Example

Methods

open()

Parameters

path

opts?

Returns

openUntitled()

Parameters

opts?

Returns

openDiff()

Parameters

spec

opts?

Returns

save()

Returns

saveAs()

Returns

closeActive()

Returns

editorsFor()

Parameters

path

Returns

setViewType()

Parameters

editorId

viewType

opts?

workspaceId?

Returns

registerSaveHandler()

Parameters

editorId

handlers

Returns

registerDiffContentProvider()

Parameters

providerId

provider

Returns

getText()

Parameters

editorId

Returns

Example

isDirty()

Parameters

editorId

Returns

getState()

Returns

Example

subscribe()

Parameters

listener

Returns

Example

setIcon()

Parameters

targetId

adornment

Returns

Inherited from

clearIcon()

Parameters

targetId

adornmentId

Returns

Inherited from

bindIcon()

Parameters

binder

Returns