ManualCode

ManualCode is an offline-capable, local-first web development workbench and multi-language code execution environment engineered with Svelte 5 runes, CodeMirror 6, and Bun. Designed to run completely inside the client browser without external backends, user tracking, or cloud databases, ManualCode isolates arbitrary code execution inside an opaque-origin sandbox iframe while providing real-time transpilation for modern web stacks and in-memory WebAssembly relational databases.

Performance Benchmarks

Technical Specifications

System Architecture and Subsystems

The application architecture cleanly separates the privileged host workbench from untrusted user code execution:

ManualCode Host Workbench (Svelte 5 Runes & Bun)
├── routes/
│   ├── +layout.svelte (theme provider, shell layout, system modals)
│   └── +page.svelte (panes, responsive splitters, active workspace)
├── lib/editor/
│   ├── cm.ts (CodeMirror 6 view lifecycle, dynamic extensions, keymaps)
│   ├── language.ts (dynamic mode loader for 13+ language syntaxes)
│   └── theme.ts (dark and light syntax token palettes)
├── lib/files/
│   ├── FileTree.svelte (hierarchical tree, drag-and-drop, path validation)
│   ├── AssetPreview.svelte (in-browser media rendering and preview)
│   ├── PdfViewer.svelte (PDF.js canvas rendering)
│   └── ExcelViewer.svelte (Web Worker spreadsheet parser with SheetJS)
├── lib/preview/
│   ├── build-doc.ts (document assembler, asset inlining, script injection)
│   ├── bridge.ts (console interception script, circular serializer, ready ping)
│   ├── preprocess.ts (lazy compiler loaders: Sass, Less, Pug, Svelte, Markdown)
│   ├── transform.ts (Sucrase TS/TSX transform and module rewriting)
│   ├── runners.ts (sandbox doc builders for Python, Lua, SVG, and Pug)
│   └── markdown.ts (DOMPurify sanitization, marked GFM parser, KaTeX math)
├── lib/sql/
│   ├── engine.ts (SQL client coordinator, query timeouts, row limits)
│   ├── worker.ts (dedicated Web Worker executing vendored sql-wasm.js)
│   └── SqlResults.svelte (virtualized paginated query tables)
├── lib/project/
│   ├── local-project.ts (Svelte 5 runes state store, quota guards, normalization)
│   ├── idb.ts (raw IndexedDB transactional wrapper)
│   └── download.ts (zip export with directory traversal sanitization)
└── hooks.server.ts (HTTP security policy: CSP, COOP, HSTS, X-Frame-Options)

How It Works

1. Local-First Multi-Store Persistence and Quota Architecture

ManualCode requires no server authentication, cloud databases, or remote endpoints:

• All user files, folders, and binary assets persist locally inside browser IndexedDB database manualcode.
• The storage layer splits data between two dedicated object stores: projects (structured text trees, timestamps, revision numbers) and assets (binary blobs with MIME types and sizes).
• Strict resource budgets protect against browser tab termination: 15 MB per file, 100 maximum files, and 100 MB aggregate project storage.
• If an asset insertion triggers a browser quota error, the transaction automatically rolls back in-memory changes and provides corrective guidance.
• Ephemeral workbench layout state (active open tabs, pane split dimensions, collapsed folders, and theme selections) is stored separately in browser localStorage (mc-open-tabs, mc-panes, mc-folders-collapsed, mc-theme), keeping IndexedDB transactions lightweight.

2. In-Browser AST Transpilation and Compilation Pipeline

ManualCode avoids external compilation servers by executing all language transforms directly inside the browser using lazily imported WebAssembly and JavaScript AST parsers:

• TypeScript and TSX: Transpiled on-the-fly using Sucrase in under 4ms, transforming modern syntax into vanilla ECMAScript without heavy Babel or tsc overhead.
• Svelte 5 Components: Compiled in-browser via @sveltejs/compiler (generate: 'client') to emit reactive JavaScript modules.
• Stylesheets: Compiles SCSS through Dart Sass compiled to JavaScript, and Less stylesheets through an in-memory compiler instance.
• Pug Templates (Security-Gated): To prevent untrusted template scripts from compromising the host app thread, the privileged thread executes only pug.compileClient (parse and code generation). Template execution (template({})) is strictly deferred to the sandboxed preview iframe using placeholder replacement.

3. Sandboxed Iframe Execution and Opaque-Origin Isolation

Executing arbitrary user JavaScript inside a web application requires strict origin isolation:

• Untrusted user code runs inside an iframe configured with sandbox="allow-scripts".
• The allow-same-origin token is explicitly omitted, forcing the browser to assign the sandbox an opaque unique origin (null).
• The sandboxed document cannot access host localStorage, IndexedDB, session cookies, or the parent window DOM tree.
• Document assembly (buildPreviewDoc) aggregates entry HTML files, inlines local project CSS and JS, and transforms local asset references (<img src="...">, CSS url(...)) into base64 data: URLs, ensuring images and media render without cross-origin blob URL blocks.
• Non-HTML projects automatically boot standalone sandboxed runtimes: Python scripts execute via Pyodide WebAssembly, Lua scripts execute via Fengari, and vector graphics render via SVG document templates.

4. Bi-Directional Console Interception Bridge and Hang Watchdog

The host workbench captures real-time runtime diagnostics from the sandbox without allowing the iframe to hijack the host thread:

• BRIDGE_SOURCE is injected as the first script in the sandboxed <head> element, wrapping console.log, warn, error, info, and debug.
• Global error listeners trap unhandled exceptions via window.onerror and window.addEventListener("unhandledrejection"), reporting line and column locations back to the host.
• A circular reference serializer uses Set tracking to serialize nested objects, Functions, Symbols, and BigInt primitives, truncating individual arguments at 2,000 characters.
• Token-Bucket Rate Limiter: Malicious or accidental infinite loops (such as while(true) console.log(1)) are throttled by a token-bucket algorithm: 100 messages per second, 200 burst capacity, and 200 KB/second throughput cap. Output is scheduled via requestAnimationFrame batching, dropping excess spam with a system warning and keeping the host browser responsive.
• Hang Watchdog: The bridge transmits an immediate ready handshake upon initialization; missing heartbeats trigger an unresponsive script status in the host UI.

5. Isolated Web Worker SQLite Engine

ManualCode integrates a dedicated relational SQL laboratory for running local queries and database schemas:

• SQLite runs via sql.js 1.12.0 WebAssembly, vendored same-origin at /static/sql-wasm.{js,wasm} to eliminate third-party CDN attack surfaces on the privileged path.
• Query execution runs in a dedicated Web Worker thread (src/lib/sql/worker.ts), preventing database operations from blocking the main UI thread.
• Execution Watchdog: A 15-second timer monitors active queries. If a runaway query (such as an infinite recursive common table expression) hangs the worker, the host terminates the worker thread, respawns a clean SQLite instance, and alerts the user.
• Result Virtualization: The worker pre-truncates query result sets to a maximum of 2,000 rows. The UI displays results through SqlResults.svelte with 200-row pagination to prevent DOM bloat.

6. Defensive Content Sanitization and Asset Virtualization

ManualCode implements defensive layers to protect the host workbench against cross-site scripting and path traversal:

• App-Path DOMPurify Sanitization: The in-editor Markdown preview renders in the privileged host origin. DOMPurify uses an explicit deny-list that eliminates <form> tags, script tags, inline style= attributes, and external <img> tracker beacons, while preserving KaTeX mathematical formulas, task lists, and syntax-highlighted code blocks.
• Path Normalization: The normalizePath utility rejects directory traversal payloads (.., %2e%2e, leading slashes, Windows drive letters, and null bytes).
• Safe Zip Packaging: Project archive exports use sanitizeZipEntry to drop escaping path entries, preventing zip slip vulnerabilities.
• HTTP Security Headers: hooks.server.ts enforces strict response policies, including Content-Security-Policy with frame-ancestors 'self' and wasm-unsafe-eval, Cross-Origin-Opener-Policy (same-origin), nosniff, no-referrer, and HSTS.

7. CodeMirror 6 Modular State Architecture

The editor is built on CodeMirror 6’s functional state and extension pipeline:

• Language syntax extensions are lazily imported based on file extensions, keeping initial bundle load times minimal.
• Supports bracket matching, auto-closing tags, code folding, active line indicators, indentation guides, and multi-cursor selection.
• Features unified command palette integration (Ctrl+K or Cmd+K) for rapid file jumping, editor actions, and project exports.

Core Features

• Local-First Architecture: Operates 100% in-browser with zero backend servers, accounts, or telemetry.
• Multi-Language Sandbox: Live preview for HTML, CSS, JavaScript, TypeScript, SCSS, Less, Pug, Svelte, Markdown, Python, Lua, and SVG.
• In-Memory SQLite Studio: Relational database runner with schema exploration, Web Worker isolation, and 15-second hang watchdog.
• Resilient Console Bridge: Intercepts runtime logs and errors with token-bucket rate limiting and circular reference serialization.
• Strict Opaque Sandboxing: Runs untrusted user scripts in isolated iframes without parent storage access.
• Dual-Store IndexedDB: Automatic saving of project files and binary asset blobs with transactional quota safeguards.
• Rich Markdown Tooling: GitHub Flavored Markdown editor with live preview, KaTeX math typesetting, and task checklists.
• One-Click Offline Export: Export projects as clean zip archives with sanitized paths and zero runtime dependencies.