Plugin Schema

@jrtilak-recall/plugin-schema is the public contract for Recall plugins. Use its JSON Schemas for editor support, or install the package when you need Zod validation and TypeScript types.

Current contract versions:

Manifest: 0.1
Theme: 0.1

JSON Schema URLs

Add these URLs to plugin files for autocomplete and basic structural validation:

https://recall.jrtilak.dev/schemas/plugin-config/v0.1/schema.json
https://recall.jrtilak.dev/schemas/theme-config/v0.1/schema.json

Use the package for complete programmatic validation, including rules such as unique declarations and safe entry paths.

Installation and validation

bun add @jrtilak-recall/plugin-schema

import {
  PluginConfigSchema,
  ThemeSchema,
  type PluginConfig,
  type Theme,
} from "@jrtilak-recall/plugin-schema";

const plugin: PluginConfig = PluginConfigSchema.parse(packageJson);
const theme: Theme = ThemeSchema.parse(themeJson);

parse() returns validated data or throws a validation error. Use safeParse() when invalid user input should be returned as a result instead:

const result = PluginConfigSchema.safeParse(packageJson);

if (!result.success) {
  console.error(result.error.issues);
}

Plugin manifest

Plugin metadata belongs in package.json. Standard package fields can remain beside the Recall contract under recall.

{
  "$schema": "https://recall.jrtilak.dev/schemas/plugin-config/v0.1/schema.json",
  "name": "@example/focus-tools",
  "displayName": "Focus Tools",
  "version": "1.0.0",
  "description": "Adds focused study commands to Recall.",
  "author": "Example Developer <https://example.com>",
  "homepage": "https://example.com/focus-tools",
  "recall": {
    "manifestVersion": "0.1",
    "category": "productivity",
    "tags": ["focus", "study"],
    "iconUrl": "https://example.com/icon.png",
    "preview": ["https://example.com/preview.png"],
    "permissions": ["registry.command", "api.toast"],
    "entry": {
      "runtime": "js",
      "file": "src/index.ts"
    }
  }
}

Package fields

Field	Required	Description
`name`	Yes	Package-style plugin identifier, such as `plugin-name` or `@publisher/plugin-name`. Maximum 214 characters.
`displayName`	Yes	Name displayed to users. Maximum 100 characters.
`version`	Yes	Numeric `Major.Minor.Patch` version, such as `1.2.0`.
`author`	Yes	Author name, optionally followed by an email or URL. Maximum 256 characters.
`description`	No	Short plugin description. Maximum 500 characters.
`homepage`	No	HTTP or HTTPS project or documentation URL.
`recall`	Yes	Recall-specific plugin configuration.

Recall fields

Field	Required	Description
`manifestVersion`	Yes	Manifest contract version. Use `0.1`.
`entry`	Yes	Runtime and relative file path that Recall loads.
`permissions`	Yes	Unique capabilities requested by the plugin.
`category`	No	Marketplace category used for discovery.
`iconUrl`	No	HTTP or HTTPS icon URL.
`tags`	No	Up to 20 unique lowercase tags using letters, numbers, and hyphens. Each tag can contain up to 40 characters.
`preview`	No	Up to eight unique HTTP or HTTPS preview image URLs.

entry.runtime is either js or theme. JavaScript plugins must request at least one permission. Theme plugins must request registry.theme.

All manifest URL fields can contain up to 2,048 characters.

entry.file must be a portable relative path. It can contain letters, numbers, ., _, @, +, -, and /, with a maximum length of 512 characters. Absolute paths and . or .. path segments are rejected.

Available categories are:

theme
feature
integration
productivity
study
import-export
accessibility
developer-tools
other

Permissions

Declare only the capabilities the plugin needs in recall.permissions. Permission values must be unique.

{
  "recall": {
    "permissions": ["registry.command", "api.toast"]
  }
}

Permission	Capability
`registry.theme`	Add themes to the app.
`registry.sorting-method`	Add or change sorting methods.
`registry.command`	Access and manage app commands.
`registry.menu`	Add or change app menus.
`registry.sheet`	Reserved for a future data-driven plugin sheet API.
`registry.highlight-color`	Add or change highlight colors.
`registry.learning-algorithm`	Add or change flashcard learning algorithms.
`api.toast`	Show toast notifications.
`api.dialog`	Show alerts and confirmation dialogs.
`api.app-state`	Read and change shared app settings and state.
`fs.read`	Reserved; the current headless runtime does not expose file reads.
`clipboard.read`	Reserved; the current headless runtime does not expose clipboard reads.

The schema validates permission declarations. The host application determines how requested capabilities are made available to a plugin.

The older ui.theme.static.write and sorting-method.modify values are deprecated. Use registry.theme and registry.sorting-method respectively in new plugins.

Theme plugins

A theme plugin points its manifest at a theme JSON file:

{
  "recall": {
    "manifestVersion": "0.1",
    "entry": {
      "runtime": "theme",
      "file": "src/theme.json"
    },
    "permissions": ["registry.theme"]
  }
}

One file can provide multiple light or dark themes:

{
  "$schema": "https://recall.jrtilak.dev/schemas/theme-config/v0.1/schema.json",
  "version": "0.1",
  "themeFor": "app",
  "themes": [
    {
      "id": "ocean-light",
      "name": "Ocean Light",
      "mode": "light",
      "theme": {
        "colors": {
          "primary": "#007CFF",
          "primaryForeground": "#FFFFFF",
          "background": "#F7FAFC",
          "foreground": "#101828"
        }
      }
    },
    {
      "id": "ocean-dark",
      "name": "Ocean Dark",
      "mode": "dark",
      "theme": {
        "colors": {
          "primary": "#65A8FF",
          "background": "#0B1020",
          "foreground": "#F8FAFC",
          "destructiveLight": "#FF4D4D33"
        }
      }
    }
  ]
}

A file contains between one and 32 themes.
id is a unique lowercase identifier using letters, numbers, and hyphens, with a maximum length of 64 characters.
name is the user-facing name and can contain up to 100 characters.
mode is light or dark; omitted colors inherit from that base mode.
Colors use #RRGGBB or #RRGGBBAA. The last two digits represent alpha.
Unknown root fields, theme fields, and color tokens are rejected.

Supported color tokens:

Core: primary, primaryForeground, background, foreground, muted, mutedForeground, card, cardForeground, accent, accentForeground, border, and ring.
Status: destructive, destructiveLight, destructiveForeground, warning, warningForeground, success, and successForeground.
Utility: folder, yellow, black, and white.

Main exports

Export	Use
`PluginConfigSchema`	Validate a full plugin `package.json` contract.
`RecallPluginConfigSchema`	Validate only the object under `recall`.
`PluginPermissionSchema`	Validate one permission identifier.
`PluginPermissionsSchema`	Validate a permission list.
`ThemeSchema`	Validate a complete theme file.
`ThemeDefinitionSchema`	Validate one theme definition.
`PluginConfig`, `RecallPluginConfig`, `PluginPermission`, `Theme`, `ThemeDefinition`	TypeScript types inferred from the schemas.
`PLUGIN_CATEGORIES`, `PLUGIN_PERMISSIONS`, `THEME_COLOR_NAMES`	Supported public values for selectors, forms, and tooling.
`LATEST_MANIFEST_VERSION`, `LATEST_THEME_FILE_VERSION`	Current contract versions.

See the plugin-schema changelog for release history.