Lumen Mod SDK
Documentation

git clone https://github.com/Gav2011/lumen-mod-starter my-mod
cd my-mod

{
  "name": "My First Mod",
  "id": "com.yourname.my-mod",
  "version": "0.1.0",
  "author": "yourname",
  "description": "My first Lumen mod.",
  "permissions": ["browser.css"],
  "browser_css": "theme.css"
}

const lumen = window.__lumen__;

lumen.log("Mod loaded");
lumen.log("Tab count:", await lumen.tabs.count());
lumen.warn("Something unexpected");
lumen.error("Shows red in the dev console");

{
  // ── Identity ────────────────────────────────
  "name":         "Mod display name",     // required
  "id":           "com.author.modname",   // required, permanent
  "version":      "1.0.0",               // required, semver
  "author":       "Your Name",
  "description":  "Short description.",
  "icon":         "icon.png",            // 128x128 PNG
  "preview":      "preview.jpg",         // 640x360 min
  "homepage":     "https://yoursite.com",
  "tags":         ["dark", "minimal"],

  // ── Permissions ─────────────────────────────
  "permissions": [
    "browser.css",   // inject CSS into browser chrome
    "browser.js",    // run JS in browser shell context
    "browser.html",  // inject HTML (newtab, overlays)
    "page.inject",   // inject into web pages
    "mod.fs",        // save settings/data to disk
    "network",       // outbound fetch / WebSocket
    "location",      // geolocation (IP or OS)
    "audio.ui",      // browser event sounds
    "audio.bg",      // persistent background audio
    "settings",      // read/write browser settings
    "tabs"           // tab list, titles, screenshots
  ],

  // ── Entry Points ────────────────────────────
  "entry":           "index.js",
  "browser_css":     "theme.css",

  // ── Page Injection ──────────────────────────
  "inject_rules": [{
    "matches":  ["https://github.com/*"],
    "js":       ["inject/github.js"],
    "css":      ["inject/github.css"],
    "run_at":   "document_end",
    "world":    "ISOLATED"
  }],

  // ── Sounds ──────────────────────────────────
  "sounds": {
    "tab.open":       "sounds/open.wav",
    "tab.close":      "sounds/close.wav",
    "tab.switch":     "sounds/switch.wav",
    "navigate.start": "sounds/nav.wav",
    "navigate.done":  "sounds/done.wav",
    "download.done":  "sounds/dl.wav",
    "error.404":      "sounds/err.wav"
  },

  // ── New Tab ─────────────────────────────────
  "newtab": {
    "type":            "html",
    "entry":           "newtab/index.html",
    "settings_widget": "newtab/settings.html",
    "preview_image":   "newtab/preview.jpg"
  },

  // ── Alt-Tab ─────────────────────────────────
  "alttab_panel":    "alttab/panel.html",

  // ── Background Audio ────────────────────────
  "background_audio": {
    "playlist":       ["music/track1.mp3"],
    "loop":           true,
    "default_volume": 0.25,
    "auto_duck":      true,
    "duck_volume":    0.05
  },

  "min_lumen_version": "1.0.0"
}

{
  "name": "Midnight Skin",
  "id": "com.you.midnight-skin",
  "version": "1.0.0",
  "permissions": ["browser.css", "mod.fs"],
  "browser_css": "theme.css",
  "entry": "index.js"
}

{
  "name": "Stellar Newtab",
  "id": "com.cosmicbytes.stellar-newtab",
  "version": "2.1.0",
  "author": "cosmicbytes",
  "description": "Real-time WebGL star field for your new tab.",
  "icon": "icon.png",
  "preview": "preview.jpg",
  "tags": ["webgl", "3d", "animated"],
  "permissions": [
    "browser.html", "browser.css", "browser.js",
    "location", "network", "mod.fs"
  ],
  "newtab": {
    "type": "webgl",
    "entry": "newtab/index.html",
    "settings_widget": "newtab/settings.html",
    "preview_image": "preview.jpg"
  },
  "entry": "index.js",
  "min_lumen_version": "1.2.0"
}

const lumen = window.__lumen__;

// Or destructure only what you need
const { css, browser, tabs, audio, storage, newtab, alttab, inject } = window.__lumen__;

const DEFAULTS = { volume: 0.3, theme: 'dark' };

async function loadSettings() {
  const saved = await lumen.storage.get('settings');
  return { ...DEFAULTS, ...(saved ?? {}) };
}
async function saveSettings(patch) {
  const cur = await loadSettings();
  await lumen.storage.set('settings', { ...cur, ...patch });
}

lumen.newtab.onMount(({ canvas }) => {
  const gl = canvas.getContext('webgl2');
  let raf;
  (function loop() { /* render */ raf = requestAnimationFrame(loop); })();
  lumen.newtab.onUnmount(() => cancelAnimationFrame(raf));
});

my-skin/
├── manifest.json
├── icon.png
├── preview.jpg
├── theme.css
└── index.js

/* Override the default CSS variables */
:root {
  --lumen-tab-bg:       #0a0a12;
  --lumen-tab-active:   #1a1a2e;
  --lumen-toolbar-bg:   #05050d;
  --lumen-accent:       #cc5de8;
  --lumen-border:       rgba(204,93,232,.15);
  --lumen-radius:       4px;
}
/* Target specific shell elements */
.lumen-tab.active {
  box-shadow: inset 0 2px 0 var(--lumen-accent);
}
.lumen-address-bar {
  font-family: 'DM Mono', monospace;
  border-radius: 6px;
}

const lumen = window.__lumen__;
const THEMES = {
  purple: { '--lumen-accent': '#cc5de8' },
  blue:   { '--lumen-accent': '#4dabf7' },
  green:  { '--lumen-accent': '#69db7c' },
};
async function init() {
  const s = await lumen.storage.get('settings') ?? { theme: 'purple' };
  for (const [k, v] of Object.entries(THEMES[s.theme] ?? THEMES.purple)) {
    lumen.css.vars[k] = v;
  }
}
init();

const lumen = window.__lumenMod__;

// Inject CSS into this page only
lumen.css.inject(`
  .author-name { color: #c77dff !important; }
`);

// Re-apply after SPA navigation
lumen.browser.on('navigate.done', applyTweaks);

function applyTweaks() {
  document.querySelectorAll('.js-navigation-item').forEach(el => {
    el.style.borderRadius = '8px';
  });
}
applyTweaks();

<!DOCTYPE html>
<html><head>
  <style>
    body { margin:0; background:#07050f; overflow:hidden; }
    canvas { display:block; width:100vw; height:100vh; }
  </style>
</head><body>
  <canvas id="c"></canvas>
  <script>
    lumen.newtab.onMount(async () => {
      const canvas = document.getElementById('c');
      let coords = null;
      if (await lumen.hasPermission('location')) {
        coords = await lumen.location.get();
      }
      const gl = canvas.getContext('webgl2');
      startStarField(gl, coords);
    });
    lumen.newtab.onUnmount(() => stopStarField());
  </script>
</body></html>

zip -r my-mod.zip . -x "*.DS_Store" -x ".git/*"
mv my-mod.zip my-mod.lmod