Plugin SDK

The Plugin SDK is the bridge between your plugin and the internote runtime. It wraps the postMessage protocol that the sandboxed iframe uses to communicate with the parent page and exposes a typed API your plugin calls directly.

Installation

Install the SDK as a dependency in your plugin project:

npm install @internote/plugin-sdk

The package includes TypeScript declarations. No separate @types package is needed.

The internote Object

The SDK exports a single internote object. Import it at the top of your plugin entry file:

import { internote } from '@internote/plugin-sdk'

internote is a singleton — it is pre-constructed and wired to window.addEventListener('message', ...) on import. You do not instantiate it yourself.

What the SDK Exposes

• internote.onInitialize(handler) — fires once when the plugin loads with its initial attrs and dimensions
• internote.onAttrsUpdate(handler) — fires when parameter-driven attr values change at runtime
• internote.onResize(handler) — fires when the element is resized by the internote layout
• internote.onUnload(handler) — fires when the plugin element is removed
• internote.ready() — signals the host that your plugin has rendered its first frame
• internote.animation — synchronise with the cue and cut timeline
• internote.storage — persist and retrieve plugin state across sessions
• internote.onPointer(handler) — receive pointer events forwarded from the host page
• internote.onKeyboard(handler) — receive keyboard events forwarded from the host page

TypeScript Types

Import the types you need alongside internote:

import {
  internote,
  type InitContext,
  type ResizeContext,
  type AnimationState,
  type PluginPointerEvent,
  type PluginKeyboardEvent
} from '@internote/plugin-sdk'

Minimal Plugin

Every plugin follows this structure: register an onInitialize handler, set up your render, call ready(), and register an onUnload handler for cleanup.

import { internote } from '@internote/plugin-sdk'

internote.onInitialize(({ attrs, width, height }) => {
  document.body.style.cssText = `
    margin: 0; display: flex; align-items: center;
    justify-content: center; height: ${height}px;
    font-family: sans-serif; font-size: 24px;
  `
  document.body.textContent = `Hello from plugin! (${width}×${height})`

  internote.ready()
})

internote.onUnload(() => {
  // Cancel loops, disconnect observers, close connections
})

Handler Registration Order

Register all handlers at the top level of your entry file — not inside setTimeout, fetch callbacks, or dynamically. The SDK queues incoming messages and delivers them once each handler is registered, but handlers registered after the init message arrives may miss data.

import { internote } from '@internote/plugin-sdk'

// Register at the top level, before any async work
internote.onInitialize(setup)
internote.onAttrsUpdate(applyAttrs)
internote.onResize(handleResize)
internote.onUnload(cleanup)
internote.animation.onState(syncTimeline)

async function setup({ attrs, width, height }) {
  await loadAssets()
  render(attrs, width, height)
  internote.ready()
}