ReticleJS

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

  1. Mutate state only via editor commands (never mutate MarkerState directly) so undo/redo, events, and future CRDT sync stay consistent.
  2. 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.
  3. 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();