koan door 01010111

koan

A premium, sidebar-native userscript IDE and manager for Firefox & Zen Browser.

Koan is a lightweight, decentralized, high-performance extension designed to replace traditional userscript managers. Instead of relying on clunky popups or separate browser tabs, Koan embeds a fully featured CodeMirror IDE directly into your browser's sidebar. It bridges the gap between editing code and seeing it live, featuring real-time CSS injection and native page-level error trapping.

🏁 Quick Start Guide

Ready to write your first script? Here is how to take control of a webpage in under 60 seconds:

1. Summon the Workspace: Press Alt+Shift+K to open the Koan sidebar on any webpage.
2. Create a Script: Click the + Create new userscript button.
3. Set the Target: In the Metadata tab, give your script a name and add a URL match rule for the site you want to modify (e.g., https://example.com/*).
4. Inject Some Magic:
5. Switch to the CSS tab and type body { filter: invert(1); }. Watch the live page instantly switch to dark mode as you type.
6. Switch to the JS tab and type console.log("Koan is running!");.
7. Save & Execute: Click the blue Save button in the top right. Reload your target page to execute the JavaScript payload and check your browser's console!

That's it. You are officially injecting code.

✨ Core Features

• Sidebar-Native Design: Docks seamlessly into the Firefox/Zen sidebar. Toggle it instantly with Alt+Shift+K without losing your context on the active page.
• The Watch Shield (Error Trapping): Koan wraps your injected scripts in a custom runtime shield. If a script crashes on the target page, the error is piped directly back to the sidebar, automatically highlighting the exact line of code that failed in the editor.
• Real-Time CSS Pipeline: Bypass the reload cycle. CSS edits are streamed to the active tab keystroke-by-keystroke, creating a powerful rapid-prototyping environment for DOM styling.
• Smart CodeMirror IDE:
• Syntax highlighting with a custom One-Dark aesthetic.
• Custom autocomplete dictionary tailored for Javascript, CSS, and GM_* API methods.
• Sandbox Privilege Scanner: Automatically scans your code for native GM_ methods and prompts you to auto-fix missing @grant metadata tags.
• Unified & Split Views: Edit Metadata, CSS, and Javascript in isolated, focused tabs, or toggle "Split" view to see the fully compiled // ==UserScript== file.
• Frictionless Importing: Drag-and-drop .user.js files directly into the workspace, or paste URLs from GitHub, Gist, or GreasyFork to automatically pull and parse external scripts.

🚀 Installation

Koan is designed as a personal, developer-focused tool. Because it utilizes powerful userscript injection APIs, it must be installed via Mozilla's developer pathways.

Option A: Zen Browser / Firefox Developer Edition (Unsigned)

If you use a developer-focused browser, you can install Koan locally without signing it.

1. Download or clone this repository and zip the contents into koan-v1.zip (ensure manifest.json is at the root of the zip).
2. Open your browser and navigate to about:config.
3. Search for xpinstall.signatures.required and set it to false.
4. Navigate to about:addons, click the gear icon ⚙️, select Install Add-on From File..., and choose your zip file.

Option B: Standard Firefox (Private Signing)

Standard Firefox requires all extensions to be signed by Mozilla, even for local use.

1. Zip the extension contents (ensure manifest.json is at the root).
2. Go to the Mozilla Add-on Developer Hub.
3. Click Submit a New Add-on and select On my own (this keeps the extension private and unlisted).
4. Upload koan-v1.zip. Mozilla will automatically scan and sign it within a few minutes.
5. Download the resulting .xpi file and drag it into your Firefox window to install it permanently.

🛠️ Architecture

Koan is built with vanilla web technologies to ensure maximum speed and minimal overhead.

• Manifest V3: Fully compliant with modern extension security and background worker standards.
• No Heavy Frameworks: Built entirely with vanilla JavaScript, HTML, and CSS. No React, Vue, or build steps required.
• Local Storage: All scripts and configurations are saved locally via the browser.storage.local API. Use the built-in "Export All" tool to back up your entire workspace to a JSON archive.

⌨️ Shortcuts

• Alt+Shift+K: Toggle the Koan Workspace sidebar.
• Ctrl+Space: Trigger the CodeMirror autocomplete engine while inside the editor.

📝 License

MIT License.