The Element SDK is in beta and not yet publicly released — APIs may change without notice.

Loading Plugins

The PluginManifest format and loadElementFromManifest for dynamic element registration

Element SDK plugins are ES modules that export an ElementDefinition produced by defineElement. A plugin ships alongside a manifest — a JSON file that describes its identity, its Chalk element schema, and where the code lives. At runtime, a host loads the manifest and calls loadElementFromManifest to validate, import, and register the element.

The runtime cannot distinguish a loaded plugin from a built-in element. Once registered, plugins render through the same ElementRenderer path as every other element.

Writing a Plugin Module

A plugin module default-exports an ElementDefinition:

// my-plugin/src/index.ts
import { defineElement } from '@internote/element-sdk'

export default defineElement({
  kind: 'particle-sim',
  category: 'environment',
  renderEnvironment(props, api) {
    return <ParticleSimulation {...props} api={api} />
  },
})

// my-plugin/src/index.ts
import { defineElement } from '@internote/element-sdk'

export default defineElement({
  kind: 'particle-sim',
  category: 'environment',
  renderEnvironment(props, api) {
    return <ParticleSimulation {...props} api={api} />
  },
})

tsx

Read-only

The kind in the definition must match the chalk.element field in the manifest. loadElementFromManifest enforces this — it overwrites the definition's kind with the manifest value to prevent mismatches.

The PluginManifest

interface PluginManifest {
  id: string
  name: string
  version: string
  author?: string
  description?: string
  category?: 'inline' | 'hybrid' | 'environment'
  permissions?: string[]
  chalk: {
    element: string
    attributes?: Record<string, PluginAttributeSchema>
  }
  runtime?: 'module' | 'worker'
  src?: string
}

interface PluginManifest {
  id: string
  name: string
  version: string
  author?: string
  description?: string
  category?: 'inline' | 'hybrid' | 'environment'
  permissions?: string[]
  chalk: {
    element: string
    attributes?: Record<string, PluginAttributeSchema>
  }
  runtime?: 'module' | 'worker'
  src?: string
}

TypeScript

Read-only

id (string; required) — Unique plugin identifier, e.g. 'particle-sim'.
name (string; required) — Human-readable display name.
version (string; required) — Semver string, e.g. '1.0.0'.
chalk.element (string; required) — The Chalk identifier this plugin registers — must be unique across all registered elements.
chalk.attributes (object; optional) — Human-facing attribute schema used by the Chalk parser for validation.
runtime ('module' | 'worker'; optional; default: 'module') — 'module' is a trusted ES module. 'worker' is reserved for future sandboxed execution and not yet implemented.
src (string; required for module runtime) — URL or path to the ES module that default-exports the element definition.

PluginAttributeSchema

interface PluginAttributeSchema {
  type: 'string' | 'number' | 'boolean' | 'dimensions'
  label?: string
  default?: unknown
  required?: boolean
  min?: number
  max?: number
  description?: string
}

interface PluginAttributeSchema {
  type: 'string' | 'number' | 'boolean' | 'dimensions'
  label?: string
  default?: unknown
  required?: boolean
  min?: number
  max?: number
  description?: string
}

TypeScript

Read-only

Example Manifest

{
  "id": "particle-sim",
  "name": "Particle Simulator",
  "version": "1.0.0",
  "author": "your@email.com",
  "description": "Interactive N-body particle simulation.",
  "chalk": {
    "element": "particle-sim",
    "attributes": {
      "count": {
        "type": "number",
        "label": "Particle count",
        "default": 100,
        "min": 10,
        "max": 1000
      },
      "gravity": {
        "type": "number",
        "label": "Gravity",
        "default": 1.0,
        "min": 0,
        "max": 10
      }
    }
  },
  "runtime": "module",
  "src": "https://plugins.example.com/particle-sim/index.js"
}

{
  "id": "particle-sim",
  "name": "Particle Simulator",
  "version": "1.0.0",
  "author": "your@email.com",
  "description": "Interactive N-body particle simulation.",
  "chalk": {
    "element": "particle-sim",
    "attributes": {
      "count": {
        "type": "number",
        "label": "Particle count",
        "default": 100,
        "min": 10,
        "max": 1000
      },
      "gravity": {
        "type": "number",
        "label": "Gravity",
        "default": 1.0,
        "min": 0,
        "max": 10
      }
    }
  },
  "runtime": "module",
  "src": "https://plugins.example.com/particle-sim/index.js"
}

JSON

Read-only

loadElementFromManifest

Validates the manifest, dynamically imports the plugin module from manifest.src, and registers the definition in the ElementRegistry.

import { loadElementFromManifest } from '@internote/element-sdk'

const manifest = await fetch('https://plugins.example.com/particle-sim/manifest.json')
  .then(r => r.json())

await loadElementFromManifest(manifest)
// 'particle-sim' is now registered and ready to render

import { loadElementFromManifest } from '@internote/element-sdk'

const manifest = await fetch('https://plugins.example.com/particle-sim/manifest.json')
  .then(r => r.json())

await loadElementFromManifest(manifest)
// 'particle-sim' is now registered and ready to render

TypeScript

Read-only

Options

interface LoadOptions {
  importModule?: (src: string) => Promise<any>
  register?: boolean
}

interface LoadOptions {
  importModule?: (src: string) => Promise<any>
  register?: boolean
}

TypeScript

Read-only

importModule — Override the module loader. Defaults to native dynamic import(). Use this to enforce allow-lists, validate integrity hashes, or inject a mock in tests:

await loadElementFromManifest(manifest, {
  importModule: async (src) => {
    await verifyIntegrity(src, manifest.id)
    return import(src)
  },
})

await loadElementFromManifest(manifest, {
  importModule: async (src) => {
    await verifyIntegrity(src, manifest.id)
    return import(src)
  },
})

TypeScript

Read-only

register — Set to false to load the definition without registering it. The definition is returned from the function so you can inspect it or register it manually:

const def = await loadElementFromManifest(manifest, { register: false })
console.log(def.kind, def.category)

// Register it yourself when ready
ElementRegistry.register(def)

const def = await loadElementFromManifest(manifest, { register: false })
console.log(def.kind, def.category)

// Register it yourself when ready
ElementRegistry.register(def)

TypeScript

Read-only

validateManifest

Validate a manifest object independently of loading. Throws with a descriptive message on the first problem found:

import { validateManifest } from '@internote/element-sdk'

try {
  validateManifest(unknownJson)
  // valid — unknownJson is asserted as PluginManifest
} catch (err) {
  console.error('Invalid manifest:', err.message)
}

import { validateManifest } from '@internote/element-sdk'

try {
  validateManifest(unknownJson)
  // valid — unknownJson is asserted as PluginManifest
} catch (err) {
  console.error('Invalid manifest:', err.message)
}

TypeScript

Read-only

Useful for validating a manifest before displaying it in a plugin marketplace UI, or for build-time checks.

ElementRegistry

After loading, definitions live in ElementRegistry — the same map that built-ins register into at startup.

import { ElementRegistry } from '@internote/element-sdk'

// Manual registration (built-ins and pre-loaded plugins)
ElementRegistry.register(def)

// Check if a kind is registered
ElementRegistry.has('particle-sim')           // → boolean

// Retrieve a definition
ElementRegistry.resolve('particle-sim')        // → ElementDefinition | undefined

// All registered kinds
ElementRegistry.registeredKinds()              // → string[]

import { ElementRegistry } from '@internote/element-sdk'

// Manual registration (built-ins and pre-loaded plugins)
ElementRegistry.register(def)

// Check if a kind is registered
ElementRegistry.has('particle-sim')           // → boolean

// Retrieve a definition
ElementRegistry.resolve('particle-sim')        // → ElementDefinition | undefined

// All registered kinds
ElementRegistry.registeredKinds()              // → string[]

TypeScript

Read-only

Later registrations for the same kind silently override earlier ones. This lets you update a plugin without reloading the page.

Loading Multiple Plugins

Fetch and load plugins concurrently with Promise.all:

const manifests = await Promise.all(
  pluginUrls.map((url) => fetch(url).then(r => r.json()))
)

await Promise.all(
  manifests.map((manifest) => loadElementFromManifest(manifest))
)

const manifests = await Promise.all(
  pluginUrls.map((url) => fetch(url).then(r => r.json()))
)

await Promise.all(
  manifests.map((manifest) => loadElementFromManifest(manifest))
)

TypeScript

Read-only

Trust and security

Dynamic import() executes arbitrary code from the src URL. Only load plugins from sources you trust. Use the importModule option to add an allow-list or integrity check before loading from user-supplied URLs.

On this page

Writing a Plugin Module The PluginManifest loadElementFromManifest validateManifest ElementRegistry Loading Multiple Plugins

The Element SDK is in beta and not yet publicly released — APIs may change without notice.

Loading Plugins

The PluginManifest format and loadElementFromManifest for dynamic element registration

The runtime cannot distinguish a loaded plugin from a built-in element. Once registered, plugins render through the same ElementRenderer path as every other element.

Writing a Plugin Module

A plugin module default-exports an ElementDefinition:

// my-plugin/src/index.ts
import { defineElement } from '@internote/element-sdk'

export default defineElement({
  kind: 'particle-sim',
  category: 'environment',
  renderEnvironment(props, api) {
    return <ParticleSimulation {...props} api={api} />
  },
})

// my-plugin/src/index.ts
import { defineElement } from '@internote/element-sdk'

export default defineElement({
  kind: 'particle-sim',
  category: 'environment',
  renderEnvironment(props, api) {
    return <ParticleSimulation {...props} api={api} />
  },
})

tsx

Read-only

The PluginManifest

interface PluginManifest {
  id: string
  name: string
  version: string
  author?: string
  description?: string
  category?: 'inline' | 'hybrid' | 'environment'
  permissions?: string[]
  chalk: {
    element: string
    attributes?: Record<string, PluginAttributeSchema>
  }
  runtime?: 'module' | 'worker'
  src?: string
}

interface PluginManifest {
  id: string
  name: string
  version: string
  author?: string
  description?: string
  category?: 'inline' | 'hybrid' | 'environment'
  permissions?: string[]
  chalk: {
    element: string
    attributes?: Record<string, PluginAttributeSchema>
  }
  runtime?: 'module' | 'worker'
  src?: string
}

TypeScript

Read-only

id (string; required) — Unique plugin identifier, e.g. 'particle-sim'.
name (string; required) — Human-readable display name.
version (string; required) — Semver string, e.g. '1.0.0'.
chalk.element (string; required) — The Chalk identifier this plugin registers — must be unique across all registered elements.
chalk.attributes (object; optional) — Human-facing attribute schema used by the Chalk parser for validation.
runtime ('module' | 'worker'; optional; default: 'module') — 'module' is a trusted ES module. 'worker' is reserved for future sandboxed execution and not yet implemented.
src (string; required for module runtime) — URL or path to the ES module that default-exports the element definition.

PluginAttributeSchema

interface PluginAttributeSchema {
  type: 'string' | 'number' | 'boolean' | 'dimensions'
  label?: string
  default?: unknown
  required?: boolean
  min?: number
  max?: number
  description?: string
}

interface PluginAttributeSchema {
  type: 'string' | 'number' | 'boolean' | 'dimensions'
  label?: string
  default?: unknown
  required?: boolean
  min?: number
  max?: number
  description?: string
}

TypeScript

Read-only

Example Manifest

{
  "id": "particle-sim",
  "name": "Particle Simulator",
  "version": "1.0.0",
  "author": "your@email.com",
  "description": "Interactive N-body particle simulation.",
  "chalk": {
    "element": "particle-sim",
    "attributes": {
      "count": {
        "type": "number",
        "label": "Particle count",
        "default": 100,
        "min": 10,
        "max": 1000
      },
      "gravity": {
        "type": "number",
        "label": "Gravity",
        "default": 1.0,
        "min": 0,
        "max": 10
      }
    }
  },
  "runtime": "module",
  "src": "https://plugins.example.com/particle-sim/index.js"
}

{
  "id": "particle-sim",
  "name": "Particle Simulator",
  "version": "1.0.0",
  "author": "your@email.com",
  "description": "Interactive N-body particle simulation.",
  "chalk": {
    "element": "particle-sim",
    "attributes": {
      "count": {
        "type": "number",
        "label": "Particle count",
        "default": 100,
        "min": 10,
        "max": 1000
      },
      "gravity": {
        "type": "number",
        "label": "Gravity",
        "default": 1.0,
        "min": 0,
        "max": 10
      }
    }
  },
  "runtime": "module",
  "src": "https://plugins.example.com/particle-sim/index.js"
}

JSON

Read-only

loadElementFromManifest

Validates the manifest, dynamically imports the plugin module from manifest.src, and registers the definition in the ElementRegistry.

import { loadElementFromManifest } from '@internote/element-sdk'

const manifest = await fetch('https://plugins.example.com/particle-sim/manifest.json')
  .then(r => r.json())

await loadElementFromManifest(manifest)
// 'particle-sim' is now registered and ready to render

import { loadElementFromManifest } from '@internote/element-sdk'

const manifest = await fetch('https://plugins.example.com/particle-sim/manifest.json')
  .then(r => r.json())

await loadElementFromManifest(manifest)
// 'particle-sim' is now registered and ready to render

TypeScript

Read-only

Options

interface LoadOptions {
  importModule?: (src: string) => Promise<any>
  register?: boolean
}

interface LoadOptions {
  importModule?: (src: string) => Promise<any>
  register?: boolean
}

TypeScript

Read-only

importModule — Override the module loader. Defaults to native dynamic import(). Use this to enforce allow-lists, validate integrity hashes, or inject a mock in tests:

await loadElementFromManifest(manifest, {
  importModule: async (src) => {
    await verifyIntegrity(src, manifest.id)
    return import(src)
  },
})

await loadElementFromManifest(manifest, {
  importModule: async (src) => {
    await verifyIntegrity(src, manifest.id)
    return import(src)
  },
})

TypeScript

Read-only

register — Set to false to load the definition without registering it. The definition is returned from the function so you can inspect it or register it manually:

const def = await loadElementFromManifest(manifest, { register: false })
console.log(def.kind, def.category)

// Register it yourself when ready
ElementRegistry.register(def)

const def = await loadElementFromManifest(manifest, { register: false })
console.log(def.kind, def.category)

// Register it yourself when ready
ElementRegistry.register(def)

TypeScript

Read-only

validateManifest

Validate a manifest object independently of loading. Throws with a descriptive message on the first problem found:

import { validateManifest } from '@internote/element-sdk'

try {
  validateManifest(unknownJson)
  // valid — unknownJson is asserted as PluginManifest
} catch (err) {
  console.error('Invalid manifest:', err.message)
}

import { validateManifest } from '@internote/element-sdk'

try {
  validateManifest(unknownJson)
  // valid — unknownJson is asserted as PluginManifest
} catch (err) {
  console.error('Invalid manifest:', err.message)
}

TypeScript

Read-only

Useful for validating a manifest before displaying it in a plugin marketplace UI, or for build-time checks.

ElementRegistry

After loading, definitions live in ElementRegistry — the same map that built-ins register into at startup.

import { ElementRegistry } from '@internote/element-sdk'

// Manual registration (built-ins and pre-loaded plugins)
ElementRegistry.register(def)

// Check if a kind is registered
ElementRegistry.has('particle-sim')           // → boolean

// Retrieve a definition
ElementRegistry.resolve('particle-sim')        // → ElementDefinition | undefined

// All registered kinds
ElementRegistry.registeredKinds()              // → string[]

import { ElementRegistry } from '@internote/element-sdk'

// Manual registration (built-ins and pre-loaded plugins)
ElementRegistry.register(def)

// Check if a kind is registered
ElementRegistry.has('particle-sim')           // → boolean

// Retrieve a definition
ElementRegistry.resolve('particle-sim')        // → ElementDefinition | undefined

// All registered kinds
ElementRegistry.registeredKinds()              // → string[]

TypeScript

Read-only

Later registrations for the same kind silently override earlier ones. This lets you update a plugin without reloading the page.

Loading Multiple Plugins

Fetch and load plugins concurrently with Promise.all:

const manifests = await Promise.all(
  pluginUrls.map((url) => fetch(url).then(r => r.json()))
)

await Promise.all(
  manifests.map((manifest) => loadElementFromManifest(manifest))
)

const manifests = await Promise.all(
  pluginUrls.map((url) => fetch(url).then(r => r.json()))
)

await Promise.all(
  manifests.map((manifest) => loadElementFromManifest(manifest))
)

TypeScript

Read-only

Trust and security

On this page

Writing a Plugin Module The PluginManifest loadElementFromManifest validateManifest ElementRegistry Loading Multiple Plugins