The BPI Plugin System

// ── PLUGIN ANATOMY ─────────────────────────────────────────────
//
//  1. Wrap everything in a lifecycle hook
//  2. Use BPI globals — no import needed, all pre-exposed
//  3. Register UI, commands, snippets, event listeners here
//

OnThe_Function('afterBoot', function() {

  // ── UI ──────────────────────────────────────────────────────
  add_header('MyPlugin', function() { /* click handler */ }, {
    icon: 'ri-plug-line',    // RemixIcon class
    tooltip: 'My Plugin',   // hover tooltip
    color: '#6366f1'        // optional icon tint
  });

  // ── COMMAND ─────────────────────────────────────────────────
  BeyoCommand_({
    name: 'My Action',
    shortcut: 'ctrl+shift+m',
    icon: 'ri-plug-line',
    action: function() { /* run action */ }
  });

  // ── STORAGE (triggers trust dialog on first run) ─────────────
  var data = localStorage.getItem('myplugin_key');

  // ── NOTIFICATIONS ───────────────────────────────────────────
  BeyoConsole_.log('Plugin loaded!');
});

OnThe_Function('hookName', function(...args) {
  // your code
});

// onFileOpen example — show file stats on every open
OnThe_Function('onFileOpen', function(path, content) {
  var lines = (content || '').split('\n').length;
  BeyoConsole_.log('📄 ' + path + ' — ' + lines + ' lines');
});

// You can register multiple callbacks for the same hook
OnThe_Function('afterBoot', function() { /* plugin A */ });
OnThe_Function('afterBoot', function() { /* plugin B */ });

add_header( ) — Toolbar Button

add_header(name, fn, opts)

// Parameters:
//   name    string   Label / dedup key (unique per plugin)
//   fn      function Click handler, receives button element
//   opts    object   { icon, tooltip, color, w, h, t }

add_header('Minify', function() {
  BeyoFormat_.minify();
  Toast_notification_({ message: 'Minified!', type: 'success' });
}, { icon: 'ri-compress-line', tooltip: 'Minify current file', color: '#f472b6' });

add_footer( ) — Footer Chip

add_footer(name, fn, opts)

// opts: { icon, color, tooltip, id }
// Chips appear in the plugin footer bar below the editor

add_footer('Stats', function() {
  var s = BeyoProject_.stats();
  Toast_notification_({ message: s.files + ' files, ' + s.bytes + ' bytes', type: 'info' });
}, { icon: 'ri-bar-chart-line', color: '#22d3ee', tooltip: 'Project Stats' });

// Alternative: BeyoFooterChip_ (full config object)
BeyoFooterChip_({ id: 'my-chip', name: 'Stats', icon: 'ri-bar-chart-line', action: fn });

Mobile Dock Injection

// Add buttons to the mobile bottom dock
var dock = document.getElementById('mobileDock');
if (dock) {
  var btn = document.createElement('button');
  btn.setAttribute('data-plugin-dock', '1'); // mark as plugin button
  btn.innerHTML = '<i class="ri-magic-line"></i>';
  btn.onclick = myAction;
  dock.appendChild(btn);
}

BeyoCommand_({
  name: 'string',       // displayed in command list
  shortcut: 'string',   // 'ctrl+shift+x', 'alt+f', 'ctrl+F11'
  icon: 'string',       // RemixIcon class (optional)
  action: function() {} // called when shortcut fires
});

// Register a shortcut + toolbar button together
OnThe_Function('afterBoot', function() {
  function dupLine() {
    var state = editorView.state;
    var line = state.doc.lineAt(state.selection.main.head);
    editorView.dispatch({
      changes: { from: line.to, insert: '\n' + line.text }
    });
  }
  BeyoCommand_({ name: 'Duplicate Line', shortcut: 'ctrl+d', action: dupLine });
  add_header('DupLine', dupLine, { icon: 'ri-file-copy-line' });
});

BeyoKeyMap_ — Advanced Key Binding

BeyoKeyMap_.bind('ctrl+alt+t', function() { /* action */ });
BeyoKeyMap_.unbind('ctrl+alt+t');
BeyoKeyMap_.list(); // → array of { key, fn } objects

// Common pattern: read → transform → write
var code = BeyoEditor_.getValue();
var upper = code.toUpperCase();
BeyoEditor_.setValue(upper);

// Mobile-safe insert — reads window._beyoLastSel internally
BeyoEditor_.insertAtCursor('// inserted by plugin\n');

Direct editorView Access

For advanced CodeMirror 6 operations, access the view directly:

// window.editorView is the live CodeMirror EditorView
var state = editorView.state;
var pos = state.selection.main.head;
var line = state.doc.lineAt(pos);

editorView.dispatch({
  changes: { from: line.from, to: line.to, insert: 'replacement' },
  selection: { anchor: line.from + 11 }
});

Toast_notification_( ) — Quick Toast

Toast_notification_({ message: 'Done!', type: 'success' });
Toast_notification_({ message: 'Oops', type: 'error', duration: 5000 });
// type: 'success' | 'error' | 'warn' | 'info'

BeyoConsole_ — IDE Console Output

BeyoConsole_.log('Plugin loaded');
BeyoConsole_.warn('Missing dependency');
BeyoConsole_.error('Something failed');
BeyoConsole_.dim('Verbose debug info');

BeyoNotify_ — Rich Notification System

BeyoLogger_ — Structured Logging

BeyoLogger_.info('Plugin start');
BeyoLogger_.debug('detail', { key: 'val' });
BeyoLogger_.groupStart('Batch Op');
BeyoLogger_.groupAdd('Step 1 done');
BeyoLogger_.groupEnd();
BeyoLogger_.table([{ file: 'a.js', size: 1200 }]);
BeyoLogger_.query('error');  // search logs
BeyoLogger_.export();       // download as JSON
BeyoLogger_.summary();      // count by level

BeyoDialog_( ) — Modal Dialog

BeyoDialog_({
  title: 'My Dialog',
  icon: 'ri-question-line',
  content: '<p>HTML content here</p>',
  actions: [
    { label: 'Cancel', action: 'Dlg.close()' },
    { label: 'Confirm', primary: true, action: 'window.myHandler()' }
  ]
});

// Close programmatically:
Dlg.close();

BeyoPanel_( ) — Draggable Floating Panel

BeyoPanel_({
  id: 'my-panel',          // unique — toggle on/off
  title: 'My Tool',
  icon: 'ri-tools-line',
  position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right'
  width: 360,
  height: 280,
  html: '<div>Panel content</div>'
});
// Calling BeyoPanel_ with same id again toggles it off

BeyoUI_ — Dynamic UI Builder

// Check cursor position (saved on editor blur — mobile-safe)
var pos = window._beyoLastSel; // { head, anchor } | null

// Show a line picker so users can choose where to insert
BeyoMobile_.showLinePicker({
  title: 'Insert After Line',
  multi: false,
  onSelect: function(lineNum) {
    // insert after chosen line
  }
});

// Select a range of lines
BeyoMobile_.selectLines(3, 7);

// Change editor font size
BeyoMobile_.fontScale(16);

// Open/close sidebar
BeyoMobile_.openSidebar();
BeyoMobile_.closeSidebar();

BeyoFS.writeFile('output.txt', 'hello world');
var src = BeyoFS.readFile('index.html');
var jsFiles = BeyoFS.listByExt('js'); // → ['app.js', 'utils.js']

BeyoExecute_.benchmark(function() {
  // heavy operation
}, 100); // runs 100x, logs avg time

var search = BeyoExecute_.debounce(myFn, 300);

var info = BeyoProject_.info();
// → { name, id, files, created, modified }
var s = BeyoProject_.stats();
// → { files: 4, bytes: 12048, lines: 380 }

BeyoEnv_.set('API_KEY', 'abc123');
BeyoEnv_.get('API_KEY'); // → 'abc123'
BeyoEnv_.toggle('DEBUG'); // true ↔ false
BeyoEnv_.dump(); // logs all vars to console

BeyoClipboard_.copyEditor();    // copy full file
BeyoClipboard_.copySelection();  // copy selected text
BeyoClipboard_.pasteToEditor();  // paste from clipboard

BeyoFormat_.formatCurrent();  // Prettier on active file
BeyoFormat_.minify();          // minify in place
BeyoFormat_.camelToSnake('myVar'); // → 'my_var'

var hits = BeyoSearch_.findAll('console.log');
// → [{ line: 4, text: '  console.log(x)' }, ...]
BeyoSearch_.replaceAll('var ', 'let ');
var proj = BeyoSearch_.findInProject('TODO');
// → [{ file: 'app.js', line: 7, text: '// TODO: fix' }]

BeyoDiff_.diffEditorVsFile('index.html');
// logs +added -removed ~changed to console

BeyoLint_.lintCurrent(); // lint active file → console
BeyoLint_.lintProject();  // scan all project files
var issues = BeyoLint_.checkSyntax('var x = ;', 'js');

var data = await BeyoHttp_.getJSON('https://api.github.com/users/octocat');
await BeyoHttp_.loadScript('https://cdn.jsdelivr.net/npm/marked/marked.min.js');

BeyoGit_.commit('app.js', 'before refactor');
var log = BeyoGit_.log('app.js'); // → array of snapshots
BeyoGit_.checkout('app.js', 0); // restore latest snapshot

BeyoTask_.register('autoSave', async function() {
  await DB.save();
});
BeyoTask_.run('autoSave');
BeyoTask_.isRunning('autoSave'); // → true | false

BeyoEvent_.on('my:event', function(data) {
  Toast_notification_({ message: data.msg, type: 'info' });
});
BeyoEvent_.emit('my:event', { msg: 'Hello from plugin A' });

BeyoConfig_.set('myplugin.theme', 'dark');
var theme = BeyoConfig_.get('myplugin.theme');

BeyoBench_.start('parse');
parseCode();
BeyoBench_.end('parse'); // logs ms to console

BeyoBench_.memory(); // logs heap usage

// Register a snippet (also: BeyoSnippet_ shorthand)
BeyoSnippet_({ trigger: 'clg', code: 'console.log($1)', lang: 'js' });
BeyoInsertSnippet_('clg'); // insert at cursor

★ NEW New in v1.15

// Quick theme patch (shim available at boot)
BeyoTheme_({ primary: '#e879f9', bg: '#0d0221', font: 15 });

// Full API
BeyoTheme_.setVar('--primary', '#6366f1');
BeyoTheme_.save('MyTheme');
BeyoTheme_.isDark(); // → true

BeyoColor_.contrast('#3b82f6', '#09090b'); // → 7.42
BeyoColor_.readable('#3b82f6'); // → '#ffffff'
BeyoColor_.randomHex(); // → '#a3e4d7'

await BeyoStorage_.setIDB('myplugin_prefs', { theme: 'dark' });
var prefs = await BeyoStorage_.getIDB('myplugin_prefs');

BeyoStorage_.local.set('flag', '1');
BeyoStorage_.session.set('temp', 'abc');

// run(fn, data) — quick one-shot worker
BeyoWorker_.run(function(data) {
  return data.reduce(function(a, b) { return a + b; }, 0);
}, [1,2,3,4,5]).then(function(result) {
  Toast_notification_({ message: 'Sum: ' + result, type: 'info' });
});

BeyoTemplate_.saveFromEditor('MyBoilerplate');
BeyoTemplate_.apply('MyBoilerplate'); // replaces editor
BeyoTemplate_.insert('MyBoilerplate'); // inserts at cursor

BeyoI18n_.register('hi', { hello: 'नमस्ते', save: 'सहेजें' });
BeyoI18n_.setLang('hi');
BeyoI18n_.t('hello'); // → 'नमस्ते'

// ── HOW SANDBOX WORKS (simplified) ─────────────────────────────
const safeDocWrite = () => { /* blocked */ };
(new Function('BPI', 'document', pluginCode))(
  window.BPI || {},     // BPI API injected
  { ...document, write: safeDocWrite }  // document.write() shadowed
);

Storage Trust Dialog

If a custom (non-built-in) plugin's code contains any of these strings, a one-time trust dialog appears before activation:

Quick Reference Card