A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file index.ts — THE public type surface of the editor plugin API.
*
* Deliberately SELF-CONTAINED (types only, zero imports): the editor copies this
* file's text verbatim into a project's `.esengine/plugins/.types/editor-api.d.ts`,
* so plugin authors get full typings with no package to install and no copy that
* can go stale. An import here would break that, so keep every shape local — and
* that constraint is a feature: it forces the surface to stay small and explicit
* rather than leaking the editor's whole internal vocabulary.
*
* What a plugin gets is a CURATED subset, not the editor's internals. `scene` in
* particular exposes the model write door (undoable, transactional) and omits the
* verification/headless machinery on the internal control surface, which plugins
* have no business driving.
*
* ---------------------------------------------------------------------------
* STABILITY: EXPERIMENTAL — this surface is NOT part of Estella's 1.x
* compatibility contract, and will keep changing after 1.0. See the
* "Editor Plugin API" section of VERSIONING.md for the whole policy.
*
* What you can rely on instead:
* - `engines.editor` is honoured. A plugin outside its declared range is
* refused with a reason and never half-loaded, so a change here costs you a
* version bump — never a user a broken editor.
* - Every breaking change is in the CHANGELOG under "Editor plugin API",
* with what to change.
* - A contribution point is deprecated for one MINOR before it is removed.
*
* Why it is not frozen: the contribution registries are still converging onto
* one ownership mechanism; a plugin runs as TRUSTED code in the editor's
* renderer, and the isolation a third-party ecosystem needs would make this API
* asynchronous; and no shipped plugin yet holds any of these shapes up, which is
* the same evidence the SDK requires before it freezes anything.
* ---------------------------------------------------------------------------
*/
/** A human string a plugin supplies, per locale (falling back to `en`). */
export type LocalizedString = string | { en: string; [locale: string]: string };
/** Retracts one registration. Push it on `ctx.subscriptions` to tie it to unload. */
export interface Disposable {
dispose(): void;
}
/** A scene entity's stable id (a source id — survives play/stop rebuilds). */
export type EntityId = number;
/** Values a component field can hold through the plugin write door. */
export type FieldValue = number | boolean | string | number[];
/** A node of the scene tree as plugins read it. */
export interface SceneNode {
id: EntityId;
name: string;
children?: SceneNode[];
}
// =============================================================================
// Contributions
// =============================================================================
/** Keybinding chord, e.g. `mod+alt+b`. `mod` is ⌘ on macOS, Ctrl elsewhere. */
export type Keybinding = string | string[];
export interface CommandContribution {
/** Under your plugin id, e.g. `acme.level-tools.bake`. The host puts it there
* if you do not, so it can never claim a built-in's id. */
id: string;
title: LocalizedString;
/** Grouping shown in the command palette. */
category?: LocalizedString;
keybinding?: Keybinding;
/**
* Menu to place this command in. `tools` is the default home for plugin
* commands; the other menu bar ids are available for a command that genuinely
* belongs beside its built-in siblings.
*/
menu?: 'tools' | 'file' | 'edit' | 'entity' | 'view' | 'build' | 'window' | 'help';
run(): void;
/** Greys the row out when false (default: always enabled). */
isEnabled?(): boolean;
/** Drives a checkmark for a toggle command. */
isChecked?(): boolean;
}
/** Where a contributed panel docks the first time it opens. */
export type PanelPlacement = 'document' | 'side-left' | 'side-right' | 'bottom';
export interface PanelContribution {
/** Under your plugin id, e.g. `acme.level-tools.budget` (see {@link CommandContribution.id}). */
id: string;
title: LocalizedString;
placement?: PanelPlacement;
/** `side-*` panels: initial column width in CSS px. */
width?: number;
/**
* Build the panel's contents into `host`, and return a teardown function. Called
* when the panel mounts, torn down when it closes or the plugin unloads.
*
* The host element is inside the editor's own dock frame, so the theme CSS
* variables (`--bg`, `--text`, `--accent`, …) are in scope: style against those
* and the panel matches the editor in both light and dark.
*/
mount(host: HTMLElement): () => void;
}
// — Activity bar ——————————————————————————————————————————————————————————————
/**
* A button on the far-left icon rail, beside the ones that reveal the editor's
* own panels — one click to the surface a plugin owns, rather than a menu.
*
* The rail is short and shared. Contribute one button, for the thing your plugin
* IS; a second belongs in the Tools menu, where a command already goes.
*/
export interface ActivityBarContribution {
/** Under your plugin id, e.g. `acme.level-tools.rail`. */
id: string;
/** Tooltip — the rail shows no text. */
title: LocalizedString;
/**
* Inline `<svg>` for the glyph, drawn at 19px. `stroke="currentColor"` (or
* `fill`) makes it follow the rail through hover and both themes. Anything
* else falls back to the plug every contributed thing wears — which two
* plugins would then collide on, so ship an icon.
*/
icon?: string;
run(): void;
}
export interface SettingContributionBase {
/** Under your plugin id, e.g. `acme.level-tools.warnAt`. Read it back with
* {@link PluginContext.settings}.get, which takes the same id you wrote. */
id: string;
label: LocalizedString;
description?: LocalizedString;
}
export interface BooleanSettingContribution extends SettingContributionBase {
type: 'boolean';
default: boolean;
}
export interface NumberSettingContribution extends SettingContributionBase {
type: 'number';
default: number;
min?: number;
max?: number;
step?: number;
}
export interface StringSettingContribution extends SettingContributionBase {
type: 'string';
default: string;
placeholder?: string;
}
export interface EnumSettingContribution extends SettingContributionBase {
type: 'enum';
default: string;
options: { value: string; label: LocalizedString }[];
}
export type SettingContribution =
| BooleanSettingContribution
| NumberSettingContribution
| StringSettingContribution
| EnumSettingContribution;
/** A point in scene (world) space. */
export interface Vec2 {
x: number;
y: number;
}
// — Viewport tools ————————————————————————————————————————————————————————————
/**
* A pointer event reduced to what a tool needs (no DOM coupling). `x`/`y` are in
* VIEWPORT space — CSS pixels from the viewport canvas's top-left — the same space
* {@link EditorViewportApi} and {@link OverlayGraphics} project to, so a tool can
* hand its input straight to `viewportToWorld` with no conversion.
*/
export interface PointerInput {
x: number;
y: number;
pointerId: number;
button: number;
shift: boolean;
alt: boolean;
}
/** Host services during a stroke. */
export interface ToolContext {
/** Keep receiving move/up even when the pointer leaves the viewport. */
capture(pointerId: number): void;
release(pointerId: number): void;
}
/**
* A viewport tool. While ARMED (`ctx.tools.activate(id)`) it gets first refusal on
* every pointer-down; returning true claims the stroke and its move/up. Return
* false for a one-shot action or a click that shouldn't take over.
*
* Choosing any built-in tool (Select/Move/… or a tile brush) disarms it, so the
* user is never stuck in a plugin's tool.
*/
export interface ToolContribution {
/** Under your plugin id, e.g. `acme.level-tools.measure`. */
id: string;
title: LocalizedString;
/** Restrict to these editor modes ('scene' | 'ui' | 'tilemap'); omitted ⇒ all. */
modes?: readonly string[];
onPointerDown(p: PointerInput, ctx: ToolContext): boolean;
onPointerMove(p: PointerInput, ctx: ToolContext): void;
onPointerUp(p: PointerInput, ctx: ToolContext): void;
/** Roll back an in-progress stroke (Esc / tool switch). */
cancel?(ctx: ToolContext): void;
}
// — Viewport overlays —————————————————————————————————————————————————————————
export interface GizmoStyle {
/** Any CSS color — including a theme token, e.g. `var(--acc)`, which is the way
* to stay consistent with the editor's own gizmos in both light and dark. */
color?: string;
/** Stroke width in SCREEN pixels, so it stays legible at any zoom. */
width?: number;
dashed?: boolean;
fill?: string;
opacity?: number;
/** `text` only: font size in screen pixels. */
fontSize?: number;
}
/**
* Drawing surface for a viewport overlay, redrawn every frame.
*
* Every primitive takes WORLD coordinates and is projected by the host, so a gizmo
* tracks the scene through pan and zoom without the plugin doing camera math — and
* a radius in world units scales the way a scene-anchored circle should. Stroke
* widths and font sizes are in SCREEN pixels, which is what keeps a hairline a
* hairline when you zoom out.
*/
export interface OverlayGraphics {
/** World → viewport CSS pixels, for plugins that need screen-space math. */
worldToViewport(x: number, y: number): Vec2 | null;
/** Viewport CSS pixels → world (the exact inverse). */
viewportToWorld(x: number, y: number): Vec2 | null;
line(a: Vec2, b: Vec2, style?: GizmoStyle): void;
polyline(points: readonly Vec2[], style?: GizmoStyle): void;
/** `radius` is in world units. */
circle(center: Vec2, radius: number, style?: GizmoStyle): void;
/** Axis-aligned world rect (corners in any order). */
rect(a: Vec2, b: Vec2, style?: GizmoStyle): void;
/** Label anchored at a world point, drawn at a fixed screen size. */
text(at: Vec2, text: string, style?: GizmoStyle): void;
}
export interface OverlayContribution {
/** Under your plugin id, e.g. `acme.level-tools.spawn-radius`. */
id: string;
/** Restrict to these editor modes; omitted ⇒ drawn in all of them. */
modes?: readonly string[];
/** Draw this frame. Called on every viewport frame — keep it cheap. */
render(g: OverlayGraphics): void;
}
// — Inspector sections ————————————————————————————————————————————————————————
/**
* Builds inspector rows. The host turns these calls into the same property UI the
* editor renders for its own components, so a contributed section is visually
* native and needs no styling — and the plugin never handles the editor's internal
* field vocabulary.
*
* A row's `key` identifies it in the contribution's `write` callback.
*/
export interface InspectorSectionBuilder {
/** A read-only labelled value. */
info(label: LocalizedString, value: string): void;
number(key: string, label: LocalizedString, value: number, opts?: { min?: number; max?: number; step?: number; unit?: string }): void;
bool(key: string, label: LocalizedString, value: boolean): void;
text(key: string, label: LocalizedString, value: string): void;
vec2(key: string, label: LocalizedString, value: Vec2): void;
/** `#rrggbb` / `#rrggbbaa`. */
color(key: string, label: LocalizedString, value: string): void;
select(key: string, label: LocalizedString, value: string, options: readonly string[]): void;
}
/** Extra section shown under a component, for entities that carry it. */
export interface ComponentInspectorContribution {
kind: 'component';
/** Namespaced id, e.g. `acme.sprite-audit`. */
id: string;
/** The component type this attaches to, e.g. `Sprite`. */
component: string;
title: LocalizedString;
build(entity: EntityId, ui: InspectorSectionBuilder): void;
/** A button in the section header. */
action?: { label: LocalizedString; run(entity: EntityId): void };
/** An edit to one of the rows `build` produced. Wrap scene writes in
* `ctx.scene.transact` if one edit should be one undo step. */
write?(entity: EntityId, key: string, value: FieldValue): void;
}
/** Section shown when an asset of `assetType` is selected in the Content Browser. */
export interface AssetInspectorContribution {
kind: 'asset';
id: string;
/** Asset type id — a built-in one (`texture`, `scene`, …) or a contributed one. */
assetType: string;
title: LocalizedString;
build(path: string, ui: InspectorSectionBuilder): void;
action?: { label: LocalizedString; run(path: string): void };
write?(path: string, key: string, value: FieldValue): void;
}
export type InspectorContribution = ComponentInspectorContribution | AssetInspectorContribution;
// — Asset types ———————————————————————————————————————————————————————————————
export interface AssetTypeContribution {
/** Under your plugin id, e.g. `acme.level-tools.dialogue`. */
id: string;
/** Extensions (lower-case, no dot) that resolve to this type. */
extensions: readonly string[];
/** Short uppercase badge on the Content Browser tile (e.g. `DLG`). */
badge?: string;
/** Tile tint — any CSS color. */
tint?: string;
/** Double-click action. */
open?(path: string): void;
/** A "New ▸ …" entry in the Content Browser's create menu. Returning the new
* path makes the browser reveal it and drop into rename. */
create?: { label: LocalizedString; run(dir: string): Promise<string | void> | string | void };
}
// — Asset importers ————————————————————————————————————————————————————————————
/**
* Turns a file the engine cannot read into assets it can.
*
* The editor calls `import` when a claimed file appears or changes, and on a
* reimport. Write the result with `ctx.fs.writeProject` (so declare `fs:project`):
* it is then an ordinary asset, and nothing downstream learns your format.
*/
export interface AssetImporterContribution {
/** Under your plugin id, e.g. `acme.level-tools.ldtk`. */
id: string;
/** Source extensions (lower-case, no dot) this converts. */
extensions: readonly string[];
/** Convert one source file, project-relative. Throwing (or rejecting) reports
* the failure against your plugin; the other importers still run. */
import(path: string): void | Promise<void>;
}
// — Entity templates ——————————————————————————————————————————————————————————
/** One component of a template: its type, and any non-default field values. */
export interface ComponentSpec {
type: string;
data?: Record<string, unknown>;
}
/** A ready-made entity offered by the Create picker (and drag-drop, and the menu). */
export interface EntityTemplateContribution {
/** Under your plugin id, e.g. `acme.level-tools.turret`. */
id: string;
label: LocalizedString;
/** Create-picker bucket; unknown categories fall under `Other`. */
category?: string;
/** Extra search terms for the picker. */
keywords?: readonly string[];
/** The entity's components, applied over their registered defaults. */
components: readonly ComponentSpec[];
}
// — Context menus ——————————————————————————————————————————————————————————————
/**
* Where a contributed row can appear. Deliberately only the menus that EXIST — the
* viewport has no context menu to host rows, and declaring a location the editor
* never opens would be a seam that silently does nothing.
*/
export type ContextMenuLocation =
| 'outliner/item'
| 'outliner/background'
| 'content/item'
| 'content/background';
/** What was right-clicked. Which fields are set depends on the location. */
export interface ContextMenuTarget {
/** `outliner/item` — the entity whose row was clicked. */
entity?: EntityId | null;
/** `content/item` — the asset path; `content/background` — the current folder. */
path?: string | null;
}
/**
* A tool a connected (MCP) agent may call.
*
* The agent's entire vocabulary is the tool catalog, so a plugin that adds a
* capability without adding a tool has added it for the person and not for the
* agent. Namespace `name` with your plugin id — an un-namespaced tool can
* shadow a built-in one, and the model would call it believing it knows what it
* does.
*
* `description` is not documentation; it is the ONLY thing the model reads when
* deciding whether this is the right tool. Say what it does and when to reach
* for it, in a sentence.
*/
export interface AgentToolContribution {
/**
* Namespaced with your plugin id, with every dot in it as `_` — plugin
* `acme.tools` offers `acme_tools_bake-occlusion`. Letters, digits, `_` and
* `-` only: this is what the model addresses on the wire, and an endpoint
* answers a name outside that by refusing the whole conversation.
*/
name: string;
/** What it does and when to use it — written for the model, not for a menu. */
description: string;
/**
* JSON Schema for `input`. Defaults to "an object with no properties".
* The MCP front validates against this before your handler runs, so a
* malformed call — or an argument the schema does not declare — is refused
* rather than handed to you half-parsed.
*/
schema?: unknown;
/**
* What calling it costs, which decides who may call it. A `read` tool is
* offered to every connected agent; anything else is offered only while the
* person lets agents change the project (Settings > AI Agents), and refused
* otherwise. `journaled` is for writes through `ctx.fs.writeProject`, which
* are captured before they land.
*
* Declare it honestly — nothing verifies it. A tool calling itself
* `journaled` while writing outside `ctx.fs` claims a net not holding it.
*/
effect?: 'read' | 'ephemeral' | 'undoable' | 'journaled' | 'irreversible';
/** Do the work. Whatever it returns is JSON-encoded for the model; throwing
* reports the message as a failed call, which the model can act on. */
run(input: unknown): unknown | Promise<unknown>;
}
export interface ContextMenuContribution {
/** Under your plugin id, e.g. `acme.level-tools.reveal-refs`. */
id: string;
location: ContextMenuLocation;
label: LocalizedString;
/** Hide the row entirely for this target (distinct from disabling it). */
when?(target: ContextMenuTarget): boolean;
run(target: ContextMenuTarget): void;
}
// =============================================================================
// Editor APIs
// =============================================================================
/**
* The scene write/read door. Every mutation here routes through the editor's
* command layer, so it lands in the undo history and survives a play→stop rebuild.
* Never reach around this to the live engine World: edits made there are dropped
* the moment the scene is rebuilt from the model.
*/
export interface EditorSceneApi {
/** The primary selected entity, or null. */
getSelection(): EntityId | null;
/** The full multi-selection. */
getSelectionIds(): EntityId[];
select(id: EntityId | null): void;
selectMany(ids: EntityId[], primary: EntityId): void;
/** The scene tree (roots, each with children). */
getSceneTree(): SceneNode[];
/** An entity's name + the component types on it, or null if it's gone. */
getEntity(id: EntityId): { name: string; components: string[] } | null;
/** A single component field's current value, or null if absent. */
getFieldValue(entity: EntityId, component: string, key: string): FieldValue | null;
addEntity(): EntityId | null;
deleteEntity(id: EntityId): void;
duplicateEntity(id: EntityId): EntityId | null;
renameEntity(id: EntityId, name: string): void;
setParent(id: EntityId, parent: EntityId | null): void;
/** Write a component field. Throws if the component or key doesn't exist. */
setField(entity: EntityId, component: string, key: string, value: FieldValue): void;
addComponent(entity: EntityId, component: string): void;
removeComponent(entity: EntityId, component: string): void;
setEntityXY(id: EntityId, x: number, y: number): void;
/** Run `fn` as ONE undo step (committed on return, rolled back if it throws). */
transact(label: string, fn: () => void): void;
undo(): void;
redo(): void;
}
export interface EditorProjectApi {
/** Absolute path of the open project root, or null when none is open. */
root(): string | null;
/** Project-relative path of the open scene, or null. */
currentScene(): string | null;
/** Save the open scene. */
save(): Promise<void>;
/** Project-relative paths of every asset the editor knows about. */
listAssets(): string[];
/** Re-scan the asset registry; resolves when a new ref is resolvable. */
refreshAssets(): Promise<void>;
/**
* One block of the project's own settings — `features.<name>` in
* `project.esproject`. A built-in name (`audio`, `physics`, `rendering`, …)
* reads what Project Settings edits; any other name is yours to define.
*/
feature<T = unknown>(name: string): T | undefined;
/**
* Replace a settings block and persist it. Requires the `fs:project`
* capability — it writes the project. Fields the editor does not model
* survive, so a block you own is safe to keep anything in.
*/
setFeature(name: string, value: unknown): Promise<void>;
}
export interface PluginDirEntry { name: string; isDir: boolean }
export interface PluginFileStat { size: number; mtimeMs: number; isDir: boolean }
/** Files a plugin may read/write. Paths are relative to the plugin's own folder
* unless the plugin declared the `fs:project` capability and uses `project*`. */
export interface PluginFs {
read(relPath: string): Promise<string>;
write(relPath: string, contents: string): Promise<void>;
readBytes(relPath: string): Promise<Uint8Array>;
writeBytes(relPath: string, bytes: Uint8Array): Promise<void>;
readDir(relPath: string): Promise<PluginDirEntry[]>;
stat(relPath: string): Promise<PluginFileStat>;
/** Moves to the OS trash, including an asset's .meta sidecar. */
delete(relPath: string): Promise<void>;
/** Moves without overwriting the destination; asset identity is preserved. */
rename(relPath: string, newRelPath: string): Promise<void>;
mkdir(relPath: string): Promise<void>;
/** Requires the `fs:project` capability; paths are project-relative. */
readProject(relPath: string): Promise<string>;
/** Requires the `fs:project` capability; paths are project-relative. */
writeProject(relPath: string, contents: string): Promise<void>;
/** The following methods also require fs:project. */
readProjectBytes(relPath: string): Promise<Uint8Array>;
writeProjectBytes(relPath: string, bytes: Uint8Array): Promise<void>;
readProjectDir(relPath: string): Promise<PluginDirEntry[]>;
statProject(relPath: string): Promise<PluginFileStat>;
deleteProject(relPath: string): Promise<void>;
renameProject(relPath: string, newRelPath: string): Promise<void>;
mkdirProject(relPath: string): Promise<void>;
}
/**
* The viewport's camera projection. A tool needs this to turn its pointer input into
* scene coordinates, so it lives on the context rather than only inside an overlay's
* draw call — both use the same VIEWPORT space (CSS pixels from the canvas top-left).
* Returns null before the viewport has a camera (no scene open yet).
*/
export interface EditorViewportApi {
viewportToWorld(x: number, y: number): Vec2 | null;
worldToViewport(x: number, y: number): Vec2 | null;
}
/**
* Editor events a plugin can observe. Handlers are dropped on unload.
*
* `sceneChanged` and `projectChanged` share a source today — the open scene is
* part of the project's state. Neither ever misses; either may fire more often
* than its name suggests.
*/
export interface EditorEvents {
on(
event: 'selectionChanged' | 'sceneChanged' | 'playStateChanged' | 'projectChanged',
handler: () => void,
): Disposable;
}
// =============================================================================
// Context
// =============================================================================
/**
* Everything a plugin is handed. Every `register` here is attributed to THIS
* plugin, which is what makes unload, disable, and hot reload possible: the editor
* retracts the whole set in one operation rather than trusting cleanup code.
*/
export interface PluginContext {
readonly id: string;
readonly version: string;
/** The editor's language (`en`, `zh-CN`), for text a plugin renders ITSELF —
* {@link localize} resolves your own {@link LocalizedString}s against it.
* Labels handed to a contribution are resolved by the host already. Fixed for
* the session: changing the language reloads the editor. */
readonly locale: string;
/** Disposables retracted on unload — the simplest correct cleanup. */
readonly subscriptions: Disposable[];
/** Log lines, attributed to this plugin in the Output Log. */
readonly log: {
info(...args: unknown[]): void;
warn(...args: unknown[]): void;
error(...args: unknown[]): void;
};
/** Transient user-facing notices. */
readonly ui: {
toast(message: string, level?: 'info' | 'success' | 'warn' | 'error'): void;
};
/** Persisted per-plugin key/value state (per user, not in the project). */
readonly state: {
get<T>(key: string, fallback: T): T;
set(key: string, value: unknown): void;
};
readonly commands: {
register(command: CommandContribution): Disposable;
/** Run any editor command by id — including built-ins. */
run(id: string): void;
};
readonly panels: {
register(panel: PanelContribution): Disposable;
/** Open (or bring forward) a panel by id. */
open(id: string): void;
};
readonly activityBar: {
register(item: ActivityBarContribution): Disposable;
};
readonly settings: {
register(setting: SettingContribution): Disposable;
/** Current value of one of YOUR settings. */
get<T extends boolean | number | string>(id: string): T | undefined;
};
readonly tools: {
register(tool: ToolContribution): Disposable;
/** Arm one of your tools (null disarms). It then gets first refusal on strokes. */
activate(id: string | null): void;
/** The currently armed contributed tool, or null. */
activeId(): string | null;
};
readonly overlays: {
register(overlay: OverlayContribution): Disposable;
};
readonly inspector: {
register(section: InspectorContribution): Disposable;
};
readonly assets: {
registerType(type: AssetTypeContribution): Disposable;
/** Convert a foreign file into engine assets. See {@link AssetImporterContribution}. */
registerImporter(importer: AssetImporterContribution): Disposable;
/** Re-run the importers claiming `path` (project-relative), as the Content
* Browser's Reimport does. Resolves when they have finished. */
reimport(path: string): Promise<void>;
};
readonly entities: {
registerTemplate(template: EntityTemplateContribution): Disposable;
};
readonly contextMenus: {
register(item: ContextMenuContribution): Disposable;
};
/** Lend connected (MCP) agents a tool. See {@link AgentToolContribution}. */
readonly agentTools: {
register(tool: AgentToolContribution): Disposable;
};
readonly scene: EditorSceneApi;
readonly project: EditorProjectApi;
readonly viewport: EditorViewportApi;
readonly fs: PluginFs;
readonly events: EditorEvents;
}
/** What a plugin's entry module default-exports. */
export interface EditorPlugin {
/** Called once when the plugin loads. May be async. */
activate(ctx: PluginContext): void | Promise<void>;
/** Optional extra teardown; registrations and `subscriptions` are retracted
* automatically, so most plugins don't need this. */
deactivate?(): void | Promise<void>;
}
// =============================================================================
// Runtime exports of `@estella/editor-api`
//
// Declared (not defined) here so this file remains the WHOLE public surface — the
// copy shipped to plugin authors has to describe the functions they can import,
// not just the shapes. api.ts implements these and is type-checked against these
// declarations, so the two cannot drift.
// =============================================================================
/**
* Declare a plugin. An identity function whose only job is to type-check the object
* literal at the definition site, so a typo in `activate` is a compile error in your
* editor rather than a load failure in ours.
*/
export declare function definePlugin(plugin: EditorPlugin): EditorPlugin;
/** Resolve a {@link LocalizedString} for a locale, falling back to `en`. */
export declare function localize(value: LocalizedString | undefined, locale: string): string;