@openwaggle/extension-sdk

Browser-safe OpenWaggle extension SDK types, broker helpers, theme helpers, and federated-module context helpers.

@openwaggle/extension-sdk is the browser-safe author package for OpenWaggle extension surfaces.

Use it in extension modules that mount into OpenWaggle-owned containers. The package gives you the public mount(context) types, Effect Schema boundary values, manifest validation helpers, broker SDK helpers, theme helpers, UI class names, and stylesheet generation helpers without importing OpenWaggle renderer internals.

The package supports Node.js 22.19 and newer. Its runtime exports are browser-safe; Node.js is required for extension build tooling and package consumers.

Main Imports

import type {
  OpenWaggleExtensionManifest,
  OpenWaggleExtensionMountContext,
  OpenWaggleFederatedModule,
} from '@openwaggle/extension-sdk'
import {
  createExtensionBrokerSdk,
  createOpenWaggleExtensionUiStylesheet,
  OPENWAGGLE_EXTENSION_UI_CLASS_NAMES as ui,
} from '@openwaggle/extension-sdk'

Supported public subpaths include:

Federated Module Example

A visual contribution exports mount(context). OpenWaggle owns the container and passes the mount context; the extension owns the content appended to context.root.

import type { OpenWaggleFederatedModule } from '@openwaggle/extension-sdk'
import {
  createOpenWaggleExtensionUiStylesheet,
  OPENWAGGLE_EXTENSION_UI_CLASS_NAMES as ui,
  openWaggleExtensionClassName,
} from '@openwaggle/extension-sdk'

const module: OpenWaggleFederatedModule = {
  async mount(context) {
    const style = document.createElement('style')
    style.textContent = createOpenWaggleExtensionUiStylesheet({
      theme: context.theme,
    })

    const panel = document.createElement('section')
    panel.className = openWaggleExtensionClassName(ui.root, ui.panel, ui.stack)

    const heading = document.createElement('h2')
    heading.className = ui.heading
    heading.textContent = context.contribution.title

    const body = document.createElement('p')
    body.className = ui.text
    body.textContent = `Mounted ${context.extension.name}`

    panel.append(heading, body)
    context.root.append(style, panel)

    return () => {
      style.remove()
      panel.remove()
    }
  },
}

export const mount = module.mount

Brokered Capability Calls

Extension code should call OpenWaggle through the broker SDK on the mount context instead of importing stores, IPC helpers, Electron APIs, or Pi SDK internals.

import type { OpenWaggleExtensionMountContext } from '@openwaggle/extension-sdk'

export async function saveSettings(context: OpenWaggleExtensionMountContext) {
  const projectPath = context.projectPaths[0]
  if (!projectPath) return

  await context.sdk.storage.packageConfig.project.set(
    { kind: 'project', projectPath },
    'github-token-source',
    'keychain',
  )
}

Declare matching capabilities and methods in openwaggle.extension.json; undeclared capability calls fail closed.

Manifest Typing

Use the manifest type to keep package metadata aligned with the public extension contract.

import type { OpenWaggleExtensionManifest } from '@openwaggle/extension-sdk'

export default {
  manifestVersion: 1,
  id: 'example-extension',
  name: 'Example Extension',
  version: '0.1.0',
  sdk: { openwaggle: '>=0.1.0 <0.2.0' },
  sourceFiles: ['package.json', 'src/settings.ts'],
  builtArtifacts: ['dist/settings.js'],
  install: { source: 'prebuilt' },
  capabilities: [
    {
      id: 'openwaggle.storage',
      methods: ['get', 'set'],
      scopes: ['project'],
    },
  ],
  contributions: {
    settingsSections: [
      {
        id: 'example.settings',
        title: 'Example Settings',
        runtime: 'federated-module',
        execution: 'host-renderer',
        entry: 'dist/settings.js',
        capability: 'openwaggle.storage',
        methods: ['get', 'set'],
      },
    ],
  },
} satisfies OpenWaggleExtensionManifest

Boundary Rules

@openwaggle/extension-sdk is browser-safe. Extension modules that use it must still stay inside the public SDK surface:

• Do not import OpenWaggle renderer feature files, Zustand stores, Electron IPC helpers, main-process services, or Pi SDK internals.
• Do not deep-import from @openwaggle/extension-sdk/src, dist, or dist-cjs.
• Use context.theme and SDK UI helpers instead of importing OpenWaggle app CSS or Tailwind internals.
• Bundle compatible helper code into your extension artifact or resolve the versioned package supplied by the installed SDK path.

For the full extension package lifecycle and manifest model, see OpenWaggle Extensions.

Reference And Support

• Complete API reference
• npm package
• Package changelog
• Report an issue

Troubleshooting

A capability call fails with an undeclared error. Confirm the capability, method, and scope are declared in openwaggle.extension.json. The broker rejects privileges that are not declared.

An import from src or dist fails. Import only the documented root and subpath exports. Build directories and source paths are intentionally private.

Styles do not match the host. Use context.theme, createOpenWaggleExtensionUiStylesheet, and the exported UI class names instead of copying OpenWaggle renderer CSS.

There are no migrations within the 0.1 documentation line. Future incompatible changes will receive a new versioned documentation line and migration guide.