Runtime

@jrtilak-recall/runtime is the host-neutral public contract shared by Recall apps and JavaScript plugins. It provides registry implementations for hosts, serializable definitions for extensions, and the permission-scoped RuntimeCtx passed to plugin sandboxes.

Installation

Plugin projects normally install the package as a development dependency for types while Recall supplies the runtime context:

bun add --dev @jrtilak-recall/runtime typescript

Host applications install it as a runtime dependency:

bun add @jrtilak-recall/runtime

Plugin-facing context

Use RuntimeCtx in a JavaScript plugin entry:

import type { RuntimeCtx } from "@jrtilak-recall/runtime";

export async function init(ctx: RuntimeCtx) {
  if (!ctx.learningAlgorithms) {
    throw new Error("The learning-algorithm permission is required.");
  }

  const algorithms = await ctx.learningAlgorithms.list();
  console.log(`${algorithms.length} learning algorithms are available`);
}

ctx.app is always present. Other capabilities are optional because Recall only exposes APIs granted by the plugin manifest. Calls are asynchronous across the isolated-runtime RPC boundary, so await context methods even when the corresponding host API is synchronous.

The context includes public contracts for commands, menus, sorting methods, highlight colors, learning algorithms, dialogs, toasts, and shared app state. See JavaScript Plugin for the permission mapping and Plugin Lifecycle for cleanup rules.

Host context

Host applications create the complete Ctx with createCtx. The input makes platform responsibilities explicit: renderers, persistence, default data, application metadata, and a plugin-runner platform adapter.

import {
  createCtx,
  type CreateCtxInput,
} from "@jrtilak-recall/runtime";

export function createHostContext(input: CreateCtxInput) {
  return createCtx(input);
}

The returned context contains the host registries and plugin runner. Keep platform-specific navigation, storage, and UI objects behind the supplied adapters instead of exposing them to plugins.

Main surfaces

Export	Use
createCtx, Ctx, CreateCtxInput	Assemble a host runtime from explicit platform adapters.
RuntimeCtx	Type the permission-scoped context visible to a plugin.
createPluginRuntimeCtx	Build and track an owner-scoped plugin context inside a host.
createLearningAlgorithmsRegistry and learning types	Register, discover, validate, and execute flashcard schedulers.
Registry creators and public definition types	Build host capabilities for commands, menus, sorting methods, themes, dialogs, toasts, plugins, and marketplaces.
createPluginRunner and runner types	Coordinate plugin module initialization and cleanup through a platform implementation.

The package root exports the complete public surface. The /context entry provides the context contracts when a consumer wants a narrower import.

Learning algorithm authors should continue with Learning Algorithms and the plugin tutorial.