API Overview
Learn the design philosophy behind OpenGPEX core APIs and context architecture.
Static vs. Reactive Context
To achieve high rendering performance and avoid unnecessary re-renders in third-party plugins, OpenGPEX splits its React context into two separate layers:
- EditorStateContext: Holds the reactive, high-frequency state tree (e.g. activeFrame, activeLayer). React components subscribe to updates via the
useEditorState()hook. - EditorServiceContext: Holds reference-stable, read-only service singletons and action handlers. Accessing this via
useEditorServices()does not trigger component re-renders.
Scoped API Binding
When you request actions or hooks from within a plugin, the workspace automatically wraps the raw context to adapt it to your plugin's UID. This provides:
- Scoped command execution (short IDs map automatically to UIDs).
- Scoped signal management (auto-prefixes plugin UID).
- Scoped configuration management (zero-argument self-config hooks).
Service Architecture
All services are accessible via a single useEditorServices() call:
| Service | Domain | Key Capabilities |
|---|---|---|
actions |
State Mutations | 4-layer dispatch (Atomic → Fast → Facade → Bus) |
geometry |
Coordinates | Bounding boxes, hit testing, snap alignment |
pixels |
Pixel Processing | Coordinate projection, composite, decode, resample, rasterize, filter, file I/O |
layers |
Layer Operations | Safe add/remove/activate with composite expansion and cascade |
assets |
Asset Management | CAS blob registry, URL management, reference-counting GC |
clipboard |
System Clipboard | Blob read/write with metadata |
plugins |
Plugin Registry | Plugin lifecycle, config, enable/disable, busy state |
files |
File Format I/O | Unified decode/encode with metadata (EXIF, ICC, DPI) |
fonts |
Font Management | WOFF2 font persistence and registration |
storage |
Persistence | State save/restore, export/import frames |
API Design Principles
- Namespace isolation — Each service owns one domain; no cross-domain methods
- Promise-based — All async operations return Promises (no callbacks)
- Zero main-thread pixel work — All heavy processing delegated to Workers via typed message protocol
- Plugin-safe — All public APIs are safe to call from plugins; internal APIs are not exported
- Stable references — Service instances are singletons; re-renders never recreate them
Last updated: 2026-07-30