Manifest and Plugin Action Types

Two Types of Plugin Actions

SwiftBiu supports two plugin architectures. The following currency-converter example shows when to use each one.

1. Standard Action (Logic-Only)

Example: CurrencyConverterLite

Use this for API calls, text extraction, calculations, and other background work that does not require a custom interface. Return results through native capabilities such as notifications, clipboard actions, or direct paste.

manifest.json

"actions": [
  {
    "title": "Lite: Convert Currency",
    "script": "script.js"
  }
]

script.js

A background action implements two hooks:

• isAvailable(context): decides whether the action is available and whether it should be prioritized with isContextMatch: true.
• performAction(context): runs the action and returns the result through host APIs.

function performAction(context) {
    // ... fetch rates and calculate ...
    const result = "720 CNY";
    SwiftBiu.copyText(result);
    SwiftBiu.showNotification("Success", `Copied: ${result}`);
}

2. Web App Action (Custom UI)

Example: CurrencyConverter

Use this for forms, complex interaction, animation, or a complete visual interface. The plugin packages HTML, CSS, and JavaScript as a small Web App.

manifest.json

"actions": [
  {
    "title": "Pro: Currency Panel",
    "script": "script.js"
  }
],
"ui": {
  "main": "ui/index.html"
}

Launch Flow and Sandbox Isolation

First, launch the page from the background script:

function performAction(context) {
    SwiftBiu.displayUI({
        htmlPath: "ui/index.html",
        width: 320,
        height: 480
    });
}

Then receive context inside the page:

window.swiftBiu_initialize = async function (context) {
    const text = context.selectedText || "";
    const selectedFiles = context.selectedFiles || [];
    console.log("User selected:", text);
};

manifest.json Reference

manifest.json is the plugin's identity and capability declaration.

Each action can declare title, icon, description, script, appleScriptFile, shellScriptFile, requiredShortcut, rules.regex, supportedFileExtensions, extensionKind, and ai. An action-level ai declaration replaces the root ai declaration for that action.

SwiftBiu-Managed AI Metadata

{
  "ai": {
    "useCase": "chat",
    "providerKey": "chatProvider",
    "modelKey": "chatModel",
    "allowedProviders": ["codex", "custom-endpoint"]
  }
}

• useCase: chat / textGeneration, imageGeneration, vision, videoGeneration, tts, or stt. role is a compatible alias.
• providerKey and modelKey: configuration keys that SwiftBiu renders as native provider/model pickers.
• allowedProviders: optional provider-only allowlist. SwiftBiu filters the picker and validates every native AI proxy request again at runtime.
• Provider-specific plugins should keep the same allowlist in each action-level ai override. Add custom-endpoint only when the extension's actual protocol is compatible.

See Configuration and the SwiftBiu-managed AI contract for examples and API mapping.

Plugin Icon Formats

SF Symbol

{
  "icon": "sparkles",
  "iconType": "sfSymbol"
}

When iconType is omitted and the value does not look like an image filename, SwiftBiu treats it as an SF Symbol.

Packaged Image File

Supported formats include .png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff, .heic, .icns, .pdf, and .svg.

{
  "icon": "icon.png",
  "iconType": "file"
}

Prefer transparent assets and provide a high-resolution source such as 64x64 or 128x128.

Text Icon

{
  "icon": "AI",
  "iconType": "text"
}

The explicit prefix form is also supported:

{
  "icon": "text:AI"
}

Up to two visible characters are rendered. Alphanumeric content is automatically uppercased.

Iconify Icon

{
  "icon": "solar:flag-bold",
  "iconType": "iconify"
}

Or use the explicit prefix:

{
  "icon": "iconify:solar:flag-bold"
}

Data URI Icon

{
  "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "iconType": "data"
}

This is useful for generated icons or packages that should not ship a separate image asset.

Lottie Dynamic Icon

Package the Lottie JSON in the extension and reference it from the manifest:

{
  "icon": "spark-motion.json",
  "iconType": "lottie",
  "iconLottieStillFrame": "first",
  "iconScale": 1.1
}

iconLottieStillFrame accepts "first", "last", or a numeric frame. iconScale is normalized to 0.5–2.0. In SwiftBiu, the user can choose whether dynamic toolbar icons animate on hover or play automatically; a static icon remains still, which preserves a clear visual contrast.

Parsing Rules and Recommendations

• Explicit prefixes take priority over iconType.
• For released plugins, prefer a clean Iconify name with iconType: "iconify".
• Keep file icons inside the plugin package and reference them by filename.
• Keep text icons short so they remain balanced in toolbars and lists.
• Prefer vectors, transparent backgrounds, optical padding, and high contrast at 18–24px sizes.

Reviewable Source Sharing in 1.3.9

SwiftBiu uses two related package formats:

From Installed Extensions, the user can export an extension with Save to File…, Share…, or Copy iCloud Link. SwiftBiu combines the manifest, scripts, UI, and assets into one sealed source document, records per-file and bundle SHA-256 integrity data, and excludes saved configuration and credentials.

The recipient reviews the plugin name, author, version, files, requested permissions, and integrity state before confirming installation. An iCloud link transports the sealed source; it does not bypass validation or execute remote code.

Continue Reading

• Configuration: settings, defaults, and documented convention keys.
• Background SwiftBiu API: host capabilities available to script.js.
• Native Workflows: file task panel and AI response bubble.
• Web UI API: window.swiftBiu, window lifecycle, and file interaction.
• Cross-Platform Compatibility: macOS, iOS, and App Store sandbox behavior.
• Permissions: declare the minimum permissions for these capabilities.