Deranged Previewer is not a file-extension previewer. When you run Deranged: Open Preview, it analyses the whole workspace — languages, frameworks, package managers, runtimes, build systems, scripts, entry points, services and their dependencies — builds a Preview Plan, and starts the best available preview in a dedicated window. When something is broken it keeps previewing what still works and shows exactly what failed, instead of collapsing to a single BUILD FAILED screen.

Features

• Project Intelligence Engine — evidence-based, confidence-scored detection of languages, frameworks, package managers, architecture and individual components. Never claims a framework from a filename alone.
• Multi-component / monorepo aware — a workspace can contain a frontend, an API, a worker and a database; Deranged builds a service graph and lets you pick which application to preview.
• Automatic strategy selection — dev server, runtime execution, compile-and-run, server preview, static preview, document render or data inspection, chosen from evidence and local toolchain probing.
• Best Effort & Strict preview modes — Best Effort preserves the working parts of an application when one part fails; Strict blocks the preview on a compilation failure. Switch at any time.
• Last-Known-Good preview — a transient syntax error does not destroy the existing preview; you see the last valid render with a clear warning that the current source has errors.
• Live reload & incremental updates — uses your framework's own HMR (Vite, Next, Nuxt, …) when present, and a built-in SSE reload channel for the static fallback server. A dependency graph computes affected modules so a one-file change does not rebuild everything.
• Integrated panels — Console, Problems, Network, Services, Inspector and Document, with timestamps, search, filtering and auto-scroll.
• Document previewers — Markdown, JSON (tree), CSV (table), YAML, XML, TOML, SVG (sanitized) and SQL (statement analysis + destructive-query detection).
• Truthful state reporting — a service only shows Running when its process is actually up. Missing compilers, missing dependencies and failed services are reported honestly, never faked.
• Security-first — argument-array execution only (no shell strings), path-traversal and symlink-escape guards, localhost-only servers, secret redaction in every log/console/report, and explicit consent before running custom or unknown commands.
• No telemetry, no network uploads — nothing leaves your machine.

Supported technologies

Only technologies that are genuinely implemented are listed. "Tested" means covered by the automated suite in this repository; "Implemented" means the code path exists but the required toolchain was not available in the development environment, so it could not be exercised end-to-end here.

The Project Intelligence Engine is designed to be extensible: new languages, frameworks, runtimes and preview strategies plug in without touching the core (see ARCHITECTURE.md).

Installation

From the Marketplace

Search for Deranged Previewer and click Install.

From a VSIX (local build)

# build the package (see Development below)
npm install
npm run package        # produces deranged-previewer-<version>.vsix

# install it into your local VS Code
code --install-extension deranged-previewer-0.1.0.vsix

To update: install the newer .vsix the same way. To uninstall:

code --uninstall-extension deranged.deranged-previewer

Usage

1. Open a project folder in VS Code.
2. Run Deranged: Open Preview (F5 in the preview window, or the 👁 icon in the editor title bar).
3. Deranged scans the workspace, shows what it detected, and starts the planned preview. If several applications are previewable it asks you to choose.
4. Edit source files — affected parts update live; errors appear without destroying the working preview.

To preview a single file (Markdown, JSON, CSV, …), right-click it in the Explorer and choose Preview with Deranged Previewer.

Opening the preview in its own window

Deranged uses an official VS Code WebviewPanel. To float it into a separate OS window, drag the preview tab out of the editor area, or run VS Code's built-in "View: Move Editor into New Window" / "Float Editor" command while the preview is focused. This is the most robust, Marketplace-compatible way to get a detached window — see Known limitations.

Commands

Configuration

All settings live under derangedPreview.*. Only implemented features are exposed.

Manual preview configuration

For unusual projects, create .deranged/preview.json:

{
  "preview": {
    "command": ["npm", "run", "dev"],
    "port": 5173,
    "url": "http://127.0.0.1:5173",
    "kind": "web"
  }
}

command must be an argument array (or a simple single command string); shell operators are rejected. url must point at localhost. Execution still requires derangedPreview.allowCustomCommands and a per-run confirmation.

Runtime requirements

Deranged itself needs only VS Code ≥ 1.85. To preview a project you need that project's own toolchain installed locally — Deranged detects existing runtimes and never bundles compilers:

• Web projects: Node.js + the project's package manager (npm/pnpm/yarn/bun)
• Python: python / python3 / py
• Rust: cargo/rustc · Go: go · .NET: dotnet · Java: JDK + Gradle/Maven
• C/C++: gcc/g++/clang

If a required runtime is missing, Deranged reports it clearly and offers a fallback where one is technically valid — it does not crash or fake success.

Security

Deranged can execute code, so security is a first-class concern. The full threat model and mitigations are in SECURITY.md. Highlights:

• All subprocesses run via argument arrays with shell: false; shell metacharacters in arguments are rejected.
• Path-traversal and symlink-escape protection on every served file.
• Dev servers and the static server bind to 127.0.0.1 only.
• Secrets (API keys, tokens, JWTs, connection strings, private keys) are redacted from every log, console line and report; secret-named env vars are dropped.
• No telemetry, no analytics, no project uploads.
• Custom/unknown commands and dependency installs require explicit consent.

Best Effort Preview

When a project contains errors, Best Effort mode:

1. analyses the failure,
2. determines which component is affected,
3. keeps previewing the unaffected components,
4. preserves the Last-Known-Good render where appropriate,
5. clearly labels the state as Preview running with errors or Showing last valid preview.

Switch to Strict mode when you want the preview blocked on any compile failure. The system always distinguishes CURRENT VALID, CURRENT WITH ERRORS, LAST KNOWN GOOD and FALLBACK — it never misrepresents state.

Troubleshooting

• "No runnable services in the plan" — the detected toolchain is missing, or dependencies aren't installed. Run Deranged: Check Environment, then install deps (npm install, etc.) with your project's package manager.
• Port already in use — Deranged auto-selects a free localhost port and reports the substitution in the Console.
• Preview shows an old state — you are viewing the Last-Known-Good render; fix the reported errors and it updates.
• Custom command refused — enable derangedPreview.allowCustomCommands and confirm the run prompt.
• A file won't preview as a document — right-click it and use Preview with Deranged Previewer (the editor-title button previews the project, not the file).

Development

npm install
npm run compile      # tsc -> out/
npm run watch        # incremental build
npm run lint         # eslint
npm test             # compile + run all unit & integration tests (64)
npm run package      # vsce package -> deranged-previewer-<version>.vsix

Press F5 in VS Code to launch an Extension Development Host.

Packaging & publishing

See PUBLISHING.md for the full, current Marketplace workflow. Verify the latest Microsoft authentication requirements before publishing — they change over time.

Known limitations (honest list)

• Separate OS window. The VS Code extension API exposes no public, Marketplace-safe way to open an arbitrary native Electron window. Deranged uses a WebviewPanel, which the user can float into a separate window via VS Code's own "Move/Float Editor" commands. This is documented, not faked.
• Live dev-server launch for web frameworks is fully wired, but the automated suite exercises detection + planning + the built-in static server; launching a real Vite/Next server requires a project with its dependencies installed.
• Compiled-language adapters (Rust/Go/.NET/Java/C++) are implemented and toolchain-gated, but were not run end-to-end in this environment because those compilers are not installed here.
• Network panel captures the built-in static/inspector server's traffic; it does not proxy or packet-capture a third-party dev server (that would be invasive). Use browser DevTools for full network inspection.
• Inspector is a lightweight DOM inspector for the static preview; it is not a Chrome DevTools replacement.
• SQL is analysed and structured; actual query execution against a live database is intentionally out of scope for this release (no auto-run of destructive queries, no bundled DB clients).
• Markdown renderer covers the documented subset (headings, lists, code, tables, links, images, blockquotes, rules), not the entire CommonMark spec.

License

Released under the MIT License.