Blackxiz Extension API

Blackxiz supports a browser-based extension system. Extensions are plain JavaScript files that register themselves with the BlackxizAPI global object. They can add panels, commands, themes, language support, and more.

Quick Start

The fastest way to create an extension is to write a single JS file and load it via the Extensions panel in the editor settings.

// my-extension.js
const ext = BlackxizAPI.registerExtension({
  id: 'my-extension',
  name: 'My Extension',
  version: '1.0.0',
  description: 'Does something cool',
  author: 'your-name',
});

// Add a command to the command palette
ext.addCommand({
  id: 'my-extension.hello',
  label: 'Hello from My Extension',
  run() {
    BlackxizAPI.ui.showToast('Hello World!');
  },
});

Extension Structure

An extension is a single JavaScript file. For complex extensions, you can bundle multiple files with a tool like esbuild or Rollup.

my-extension/
  ├── extension.js     // main entry point
  ├── manifest.json    // metadata (optional for single-file)
  └── README.md        // documentation

Manifest

The manifest describes your extension. It can be embedded in the JS file or provided as a separate manifest.json.

Editor API

Access and manipulate the CodeMirror editor instance.

const editor = BlackxizAPI.editor;

// Get current file content
const content = editor.getValue();

// Set content
editor.setValue('new content');

// Get cursor position
const pos = editor.getCursor(); // { line, ch }

// Insert text at cursor
editor.replaceSelection('inserted text');

// Get selected text
const sel = editor.getSelection();

// Listen for changes
editor.on('change', (cm, change) => {
  console.log('File changed', change);
});

Files API

Read and write files in the virtual file system.

const files = BlackxizAPI.files;

// Get all files
const all = files.getAll(); // { 'path/file.js': 'content', ... }

// Get active file path
const active = files.getActive(); // 'index.js' or null

// Read a file
const content = files.read('index.js');

// Write a file (creates if not exists)
files.write('output.txt', 'hello');

// Create a new file and open it
files.create('new-file.js', '// content');

// Open a file in the editor
files.open('index.js');

// Delete a file
files.delete('old-file.js');

UI API

Add panels, commands, and UI elements.

const ui = BlackxizAPI.ui;

// Show a toast notification
ui.showToast('Done!');

// Add a sidebar panel
ui.addPanel({
  id: 'my-panel',
  title: 'My Panel',
  icon: '🔍',
  render(container) {
    container.innerHTML = '<p>Hello from my panel!</p>';
  },
});

// Add a command to the palette (Ctrl+Shift+P)
ui.addCommand({
  id: 'my-ext.format',
  label: 'Format Document',
  keybinding: 'Ctrl+Shift+F',
  run() { /* ... */ },
});

// Add a status bar item
ui.addStatusBarItem({
  id: 'my-status',
  text: '✓ Ready',
  position: 'right', // 'left' | 'right'
  onClick() { /* ... */ },
});

Chat API

Interact with the AI chat panel.

const chat = BlackxizAPI.chat;

// Send a message to the AI
chat.send('Explain this code');

// Add a system prompt that persists
chat.addSystemPrompt('Always respond in Spanish');

// Listen for AI responses
chat.on('response', (message) => {
  console.log('AI said:', message);
});

Events

Subscribe to editor and file system events.

BlackxizAPI.events.on('file:open', ({ path }) => {
  console.log('Opened:', path);
});

BlackxizAPI.events.off('file:open', handler); // unsubscribe

Creating Themes

There are three ways to create and share themes in Blackxiz.

1. Visual Theme Editor (easiest)

Open the Themes panel in the sidebar, click + to open the visual editor. Pick colors with color pickers, see a live code preview, then click Save Theme. Use Export JSON to download a shareable .theme.json file.

2. Import from JSON or ZIP

Click the upload icon in the Themes panel header to import a .theme.json file or a .zip containing one.

ZIP structure:

my-theme.zip
  theme.json       <-- required
  README.md        <-- optional

theme.json format:

{
  "name": "Catppuccin Mocha",
  "id": "catppuccin-mocha",       // optional, auto-generated if omitted
  "cmTheme": "dracula",           // CodeMirror theme: dracula | monokai | material-darker | solarized dark | default
  "colors": {
    "--bg":          "#1e1e2e",
    "--surface":     "#181825",
    "--surface2":    "#1e1e2e",
    "--surface3":    "#313244",
    "--border":      "#45475a",
    "--text":        "#cdd6f4",
    "--text-muted":  "#6c7086",
    "--text-dim":    "#45475a",
    "--accent":      "#cba6f7",
    "--green":       "#a6e3a1",
    "--red":         "#f38ba8",
    "--yellow":      "#f9e2af",
    "--purple":      "#cba6f7"
  }
}

3. Via Extension API

Register a theme programmatically from an extension:

BlackxizAPI.themes.register({
  id: 'my-theme',
  name: 'My Dark Theme',
  cmTheme: 'dracula',
  colors: {
    '--bg': '#1e1e2e',
    '--surface': '#181825',
    '--text': '#cdd6f4',
    '--accent': '#cba6f7',
    // ... other tokens
  },
});

// Apply it immediately
BlackxizAPI.themes.apply('my-theme');

Color Tokens

Publishing

To share your extension with the community:

1. Host your extension JS file publicly (GitHub Gist, CDN, etc.)
2. Users can load it via Settings → Extensions → Load from URL
3. To be listed in the official extension gallery, open a PR to the Blackxiz Extensions Registry

Full Example: Word Count Panel

// word-count.js — shows word count in a sidebar panel
const ext = BlackxizAPI.registerExtension({
  id: 'word-count',
  name: 'Word Count',
  version: '1.0.0',
  icon: '📊',
});

let container;

ext.addPanel({
  id: 'word-count.panel',
  title: 'Word Count',
  icon: '📊',
  render(el) {
    container = el;
    update();
  },
});

function update() {
  if (!container) return;
  const text = BlackxizAPI.editor.getValue();
  const words = text.trim().split(/\s+/).filter(Boolean).length;
  const lines = text.split('\n').length;
  const chars = text.length;
  container.innerHTML = `
    <div style="padding:12px;font-size:0.82rem;color:#888">
      <div>Words: <strong style="color:#f0f0f0">${words}</strong></div>
      <div>Lines: <strong style="color:#f0f0f0">${lines}</strong></div>
      <div>Chars: <strong style="color:#f0f0f0">${chars}</strong></div>
    </div>`;
}

BlackxizAPI.events.on('file:change', update);
BlackxizAPI.events.on('file:open', update);