Install

npm install @siliph/pdf-engine-plugin-sdk

Features

• 5 typed extension points — annotations, toolbar, export, operators, commands
• Sandboxed access — read-only document facade (mutations only via Commands)
• Error isolation — plugin crashes don't affect the engine
• Disposal handles — clean unregistration without affecting other plugins
• TypeScript-first — full type safety for all extension points

Quick Start

import { createPluginFacade } from '@siliph/pdf-engine-plugin-sdk';

const facade = createPluginFacade(document);

// 1. Register custom annotation type
const handle = facade.registerAnnotationType({
  type: 'my-highlight',
  render: (ctx, rect) => {
    ctx.fillStyle = 'rgba(255, 255, 0, 0.3)';
    ctx.fillRect(rect.llx, rect.lly, rect.urx - rect.llx, rect.ury - rect.lly);
  },
  serialize: (annot) => ({ Type: '/Annot', Subtype: '/MyHighlight' }),
});

// 2. Register toolbar action
facade.registerToolbarAction({
  id: 'export-csv',
  label: 'Export as CSV',
  icon: 'table-icon',
  execute: (doc) => { /* extract table data */ },
});

// 3. Register export transform
facade.registerExportTransform({
  name: 'add-watermark-bytes',
  transform: (bytes) => { /* modify final PDF bytes */ return bytes; },
});

// 4. Handle content stream operators
facade.registerContentStreamOperatorHandler({
  operator: 'BMC',
  handle: (operands, state) => { /* process marked content */ },
});

// 5. Listen to all commands
facade.onCommand((command) => {
  console.log(`Applied: ${command.type}`);
});

// Clean up
handle.dispose();

Extension Points

| Extension | Description | |-----------|-------------| | registerAnnotationType | Custom annotation rendering + serialization | | registerToolbarAction | Add buttons/actions to the toolbar | | registerExportTransform | Modify PDF bytes before save | | registerContentStreamOperatorHandler | Handle custom operators | | onCommand | Listen to document mutations |

Safety Guarantees

• Plugins receive read-only document access
• Attempting to mutate the document throws PluginError
• Unhandled errors in plugins are caught and surfaced via onPluginError
• Engine continues operating even if a plugin crashes
• DisposalHandle.dispose() cleanly removes an extension

Exported API

| Export | Type | Description | |--------|------|-------------| | createPluginFacade | function | Create a facade for a document | | createPluginFacadeWithRegistry | function | Create with custom registry | | ExtensionRegistry | class | Manual extension management | | createReadonlyDocumentView | function | Wrap document in read-only proxy |

Subpath Imports

import { ExtensionRegistry } from '@siliph/pdf-engine-plugin-sdk/extensions';
import { createReadonlyDocumentView } from '@siliph/pdf-engine-plugin-sdk/facade';

Part of @siliph/pdf-engine

| Package | Description | |---------|-------------| | @siliph/pdf-engine | Umbrella (re-exports all) | | @siliph/pdf-engine-core | Parser, engines, task API | | @siliph/pdf-engine-ui | Viewport, toolbar, accessibility | | @siliph/pdf-engine-plugin-sdk | Plugin extension system (this package) |

Links

• 🌐 siliph.com — Documentation
• 📦 GitHub — Source code
• 🐛 Issues — Bug reports

License

MIT