ReticleJS Plugin API
reticlejs is built around a headless Editor kernel (src/core/Editor.ts) with zero DOM dependencies. Interactive behaviors—keyboard shortcuts, clipboard handling, smart alignment snapping, inline text editing, and opt-in on-device AI tools—are implemented as composable plugins.
Plugin Interface
Every plugin implements the Plugin interface from src/core/Plugin.ts:
import type { Editor } from '../core/Editor';
export interface Plugin {
/** Unique identifier for this plugin (used by editor.hasPlugin / editor.unuse). */
readonly name: string;
/**
* Called once when registered via `editor.use(plugin)`.
* Subscribe to `editor.events`, attach DOM listeners, or register helpers.
* Return a teardown function to clean up when `editor.unuse(name)` or `editor.destroy()` is called.
*/
install(editor: Editor): (() => void) | void;
}
Registering & Removing Plugins
import { Editor } from 'reticlejs';
import { createShortcutsPlugin, createClipboardPlugin, createSnapPlugin } from 'reticlejs';
const editor = new Editor();
// Install plugins
editor.use(createSnapPlugin());
editor.use(createClipboardPlugin());
editor.use(createShortcutsPlugin({ host: containerEl }));
// Check or uninstall a plugin by name
if (editor.hasPlugin('snap')) {
editor.unuse('snap');
}
// Tears down all installed plugins
editor.destroy();
Built-in Plugins
MarkerArea installs built-in plugins by default (and ReticleJS also exports AccessibilityPlugin for WCAG 2.2 AA keyboard-only workflows). Each can also be used standalone with a headless Editor or custom renderer:
| Plugin | File | Purpose |
|---|---|---|
SnapPlugin |
src/plugins/SnapPlugin.ts |
Computes edge/center alignment snap offsets and guide lines against image bounds and other markers (Alt bypasses). |
ClipboardPlugin |
src/plugins/ClipboardPlugin.ts |
In-memory & system clipboard copy/cut/paste for single or multi-selected markers, plus pasted-image forwarding. |
ShortcutsPlugin |
src/plugins/ShortcutsPlugin.ts |
Keyboard shortcuts (tool hotkeys, Undo/Redo, Delete, Duplicate, Copy/Cut/Paste, Arrow nudge, Tab cycling, Z-order, Zoom, Space-pan, Escape). |
TextEditorPlugin |
src/plugins/TextEditorPlugin.ts |
Floating <textarea> overlay for inline editing of text-capable markers (TextMarker, CalloutMarker, CaptionFrameMarker), committing edits via Editor commands. |
AccessibilityPlugin |
src/plugins/AccessibilityPlugin.ts |
WCAG 2.2 AA ARIA live-region announcements, virtual keyboard cursor, and full keyboard-only marker creation/resizing/rotation. |
Writing a Custom Plugin
- Mutate state only via
editorcommands (never mutateMarkerStatedirectly) so undo/redo, events, and future CRDT sync stay consistent. - Keep core plugins DOM-free where possible; when a plugin needs a DOM host (e.g., keyboard/clipboard/overlay), accept the element(s) via a factory options object.
- Always return a teardown function that unsubscribes every
editor.events.on(...)listener and removes any DOM listeners or nodes.
Example: Autosave Plugin
import type { Editor, Plugin } from 'reticlejs';
export function createAutosavePlugin(storageKey: string, debounceMs = 400): Plugin {
return {
name: 'autosave',
install(editor: Editor) {
let timer: ReturnType<typeof setTimeout> | null = null;
const off = editor.events.on('statechange', ({ state }) => {
if (timer) clearTimeout(timer);
timer = setTimeout(() => {
localStorage.setItem(storageKey, JSON.stringify(state));
}, debounceMs);
});
return () => {
if (timer) clearTimeout(timer);
off();
};
},
};
}
Lazy-Loaded On-Device AI Plugins
Heavy or optional capabilities such as on-device PII/face auto-redaction (src/plugins/ai-redact/) are packaged as separate opt-in entry points that are dynamically imported on first use. They never increase the core library bundle size and execute 100% locally in the browser.
// Lazy-load only when the user clicks "✦ Auto-Redact"
const { createAiRedactPlugin } = await import('reticlejs/ai-redact');
const aiRedact = createAiRedactPlugin({
defaultMarkerType: 'BlurMarker', // or 'PixelateMarker'
onProposalsChange: (proposals) => renderDrawer(proposals),
});
editor.use(aiRedact);
await aiRedact.scan(targetImage);
// Accept individually or apply all pending proposals as a single undoable command:
aiRedact.applyAll();