The Stdio & Stability Update

Release Notes — v0.2.2-alpha

This release introduces the production-ready Stdio MCP Transport to enable seamless integration with agentic frameworks like Codex and Claude Code. It also addresses critical agent-engine friction points, resolving catastrophic session invalidation loops and a major zero-node rendering bug on complex websites like Wikipedia.

New Features

Stdio MCP Transport Integration

Implemented an asynchronous NDJSON read/write loop to support the Stdio Model Context Protocol. A new --stdio CLI flag bypasses the HTTP/SSE server binding entirely. To ensure sub-500ms startup handshakes required by MCP hosts, V8 and QuickJS engines are now lazily initialized upon the first tool execution.

Bug Fixes

Zero-Node Scene Graph on Websites

The phantom-serializer visibility pipeline contained a catastrophic cascading bug. If a parent element had a bounding height or width of 0 (common for absolute wrappers or un-cleared floats), it was marked invisible and incorrectly cascaded that invisibility to all children, resulting in an empty DOM tree. The logic in visibility.rs is now decoupled: a parent only hides its children if it explicitly has display: none or opacity: 0.

Cascading Session Invalidation Loop (Session Expired)

When agents injected heavy discovery scripts that exhausted the QuickJS heap (js_out_of_memory) or exceeded the CPU budget, the EngineAdapter aggressively destroyed the entire browser session via broker.remove(). This trapped agents in a permanent "Session Expired" loop. The fail-fast logic in engine.rs and evaluate.rs was removed; the Tier1Pool now isolates and discards the dirty QuickJS runtime while keeping the core Session (URL, cookies, CCT) fully intact.

Storage Permission Denied (os error 13)

The PHANTOM_STORAGE_DIR environment variable previously defaulted to /data/storage, an absolute path restricted by Linux user permissions. This caused browser_session_clone and sqlite initialization to fail immediately. The .env.example default is now set to ./storage, safely isolating data within the project directory.

The Agent-Engine Trust Gap

General-purpose agents treated Phantom as a generic browser, injecting heavy JavaScript via browser_evaluate to discover elements, bypassing the engine's token-efficient CCT. The tool definitions in stdio.rs have been completely overhauled. browser_get_scene_graph is now explicitly labeled as the "SOURCE OF TRUTH", commanding agents to trust the natively computed layout data and explicitly warning against using browser_evaluate for DOM discovery.

Affected Files

• phantom-mcp/src/stdio.rs — implemented Stdio transport and overhauled tool descriptions.
• phantom-mcp/src/bin/phantom.rs — added --stdio CLI flag routing.
• phantom-mcp/src/engine.rs — removed session destruction on resource budget exhaustion.
• phantom-mcp/src/tools/evaluate.rs — removed session destruction on QuickJS timeouts and OOMs.
• phantom-serializer/src/visibility.rs — fixed 0-height parent visibility cascading.
• .env.example — updated default storage directory path.

Upgrade Notes

No direct action is required for existing integrations, but agents using the Phantom MCP server will automatically benefit from the improved tool descriptions upon restarting their connection. If you are experiencing os error 13, ensure your local .env contains PHANTOM_STORAGE_DIR=./storage.

v0.2.1-alpha: Environment Configuration Fixes

Release Notes — v0.2.1-alpha

This patch fixes three silent configuration bugs where environment variables defined in .env were ignored by the engine at runtime. Users who had customized PHANTOM_STORAGE_DIR, PHANTOM_LOG_FORMAT, or PHANTOM_V8_POOL_SIZE were unknowingly running on hardcoded defaults.

Bug Fixes

PHANTOM_STORAGE_DIR was ignored

The SessionStorageManager in engine.rs was initialized with a hardcoded "./storage" path. The PHANTOM_STORAGE_DIR variable defined in .env was never read. A new EngineAdapter::new_with_storage() constructor now accepts and propagates the configured path. The original new() method delegates to it with the default, preserving backward compatibility.

PHANTOM_LOG_FORMAT was silently mismatched

The telemetry module read LOG_FORMAT from the environment, but the .env file and ph setup init both write PHANTOM_LOG_FORMAT. This naming mismatch caused the log format to always fall back to compact, regardless of what was configured. The variable name in telemetry.rs now matches the documented convention.

PHANTOM_V8_POOL_SIZE was hardcoded

The V8 pool size was passed as a literal 5 in the EngineAdapter::new() call inside phantom.rs. The PHANTOM_V8_POOL_SIZE environment variable was defined in .env and written by ph setup init, but never consumed. It is now read and parsed alongside PHANTOM_QUICKJS_POOL_SIZE.

Affected Files

• phantom-mcp/src/bin/phantom.rs — reads PHANTOM_V8_POOL_SIZE and PHANTOM_STORAGE_DIR
• phantom-mcp/src/engine.rs — new new_with_storage() constructor
• phantom-mcp/src/telemetry.rs — corrected env var name

Upgrade Notes

No action required. If you were relying on the hardcoded defaults, your existing .env values will now take effect. Verify your PHANTOM_STORAGE_DIR path exists before starting the engine.

v0.2.0

Release Notes

[0.2.0-alpha]

Core Update: Quik Transport Layer Integration

The v0.2.0-alpha release introduces the proprietary Quik transport layer, a critical evolution in the Phantom Engine's networking capabilities. This update transitions the project from third-party dependencies to a custom-engineered stack designed for absolute network identity parity.

High-Fidelity Network Identity

The integration of Quik enables bit-perfect replication of Chrome 134 network fingerprints. By operating at the byte level of the TLS and HTTP/2 protocols, the engine now presents a cryptographic and behavioral profile that is indistinguishable from a standard Chromium instance.

• TLS Precision: Implementation of JA4-compliant handshakes, including GREASE extension permutation and Post-Quantum hybrid key exchange.
• HTTP/2 Signaling: Strict enforcement of Chromium-identical frame sequencing, window updates, and pseudo-header ordering (:method, :authority, :scheme, :path).
• WAF Transparency: Successfully validated against top-tier bot detection systems, ensuring seamless navigation through heavily protected infrastructure.

Advanced Navigation Orchestration

The navigation pipeline has been hardened to support complex, stateful web interactions:

• Stealth Redirect Handling: Proprietary state machine for managing multi-hop redirects while maintaining accurate Chromium behavioral metadata (e.g., sec-fetch-* header mutations).
• Resource Resolution Integrity: Added comprehensive tracking of final-hop URLs to ensure correct resolution of relative assets and subresources.

System Stabilization

• Workspace Synchronization: Unified all 11+ internal crates under the v0.2.0 specification for cross-module consistency.
• Dependency Hardening: Streamlined the dependency graph and resolved transitive version conflicts to ensure a robust, production-ready build environment.

---

For detailed technical specifications and implementation details, refer to the Quik Documentation.

v0.1.2-alpha: Dynamic Resource Orchestration

Release Notes — v0.1.2-alpha

This release transitions the Phantom Engine from hardcoded resource limits to a configurable, production-ready orchestration model. We've focused on eliminating systemic bottlenecks that previously restricted high-concurrency browser automation and complex JavaScript execution.

Core Infrastructure

Resource Budgeting and Scaling

• Configurable CPU Quotas: Replaced the hardcoded 1000ms per-second CPU limit with PHANTOM_CPU_QUOTA_MS. This allows the engine to handle heavy layout calculations and long-running JS execution without triggering budget-exceeded errors.
• Dynamic Tier 1 Pools: Introduced PHANTOM_QUICKJS_POOL_SIZE. The execution pool is no longer locked at 5 sessions; it can now be scaled up based on available system memory to support high-concurrency workloads.
• Native Environment Loading: Integrated dotenvy directly into the MCP entry point. The server now automatically bootstraps its environment from .env files in the working directory.

Tooling and Developer Experience

Interactive CLI Bootstrap

• ph setup init: Rewrote the setup command as an interactive wizard. It now prompts for API keys, session limits, and pool sizes while maintaining secure defaults for internal encryption keys.
• Enhanced Diagnostics: Updated ph setup doctor to verify system-level requirements, including storage permissions and environment variable integrity.

Stability and Bug Fixes

• Session Lifecycle: Resolved a systemic race condition where sessions would terminate prematurely on high-latency pages.
• Configuration Propagation: Fixed an issue where engine parameters were not correctly synchronized from the MCP entry point to the session adapter.
• Workspace Alignment: Synchronized all 10 project crates to version 0.1.2-alpha to ensure dependency compatibility across the workspace.

---

Upgrade Note: New configuration variables (PHANTOM_CPU_QUOTA_MS, PHANTOM_QUICKJS_POOL_SIZE) are required. Run ph setup init to generate a fresh .env or update your existing configuration manually.

v0.1.1-alpha

Phantom Engine v0.1.1-alpha

We're moving fast. This release is all about making the engine actually usable for humans, not just agents. We finally built a real CLI so you can stop wrestling with raw JSON-RPC if you just want to test something.

🎮 The New Phantom CLI (ph)

We added a native Rust CLI to the workspace. No more curl madness.

• Instant Setup: ph setup init handles your .env and directory tree.
• Interactive Mode: A proper REPL shell for live engine debugging.
• DOM Inspection: ph scene-graph and ph inspect to see what the engine sees.
• Live Stream: ph watch lets you tap into the SSE delta stream directly.

🛡️ Stability & Audit

After a massive line-by-line audit, we've hardened the core.

• Zero Unwraps: Cleaned up the remaining panic points in the navigation pipeline.
• Budget Enforcement: Fixed the CPU budget leaks that were causing session hangs on heavy sites.
• Storage Isolation: Tightened unix permissions on session data (0o700 by default).

🚀 What's New

• Updated all workspace crates to 0.1.1-alpha.
• Added phantom-cli as a first-class citizen in the repo.
• Fixed the circuit breaker logic for Tier 1 (QuickJS) execution.

---

To get started with the new CLI:

cargo install --path phantom-cli
ph setup doctor

0.1.0-alpha

Phantom Engine v0.1-alpha

This is the first public release of Phantom Engine — a headless browser engine written in Rust, built specifically for AI agents. Core flows are working and stable. Some sites may break.

What ships in this release

Browser pipeline
A complete parse → style → layout → serialize pipeline. HTML is parsed by html5ever into a real DOM, CSS is cascaded with full selector matching and inheritance, layout is computed by Taffy (flexbox and grid), and the result is serialized into a Compressed Content Tree (CCT) — a structured, token-efficient format that tells agents exactly what is visible on screen, where it is, and whether it is interactive.

JavaScript execution
A two-tier runtime pool. QuickJS handles fast, stateless evaluation with sub-10µs exec times. V8 via Deno Core handles stateful, modern JS workloads. A circuit breaker sits in front of both pools — if a runtime starts failing, new requests fast-fail immediately rather than queuing.

Full storage layer
Per-session, disk-persisted cookies, localStorage, IndexedDB, and Cache API — all isolated by session UUID and validated against path traversal. Snapshots are archived as zstd-compressed tar files with HMAC-SHA256 signed manifests for tamper detection.

Session management
Sessions track their own resource budgets (heap, CPU, network) and enforce them on every operation. Sessions can be suspended, resumed, and cloned copy-on-write without reloading the page.

Anti-detection
Five browser persona profiles across Chrome 133 and 134 on Windows and macOS. TLS fingerprints, JA3/JA4 signatures, User-Agent, WebGL strings, canvas noise seeds, and behavioral timing are all consistent per persona. Network transport uses wreq — Chrome-emulating TLS, not reqwest.

MCP server
JSON-RPC 2.0 over HTTP with bearer token auth, rate limiting, session limits, Prometheus metrics, and structured tracing. Docker image ships as polymit/phantom:latest.

Observability
Prometheus metrics, Grafana provisioning, alerting rules for engine-down / circuit breaker open / storage pressure, and k6 load test scripts included in the repository.

Known limitations

• Some JavaScript-heavy single-page applications may not fully render without V8 session initialization
• HTTP/3 (QUIC) transport is detected and tracked via Alt-Svc but not yet active — deferred to v0.2
• No GUI or visual debugging interface in this release

Performance highlights

Operation	Result
JS eval (simple expression)	5.30 µs
CCT full serialization (1,000 nodes)	4.67 ms
CCT delta mutation (10 nodes)	8.46 µs
Session creation (QuickJS)	1.56 µs
Suspend / resume	121.07 ns

Get started

docker run -d \
  -p 8080:8080 \
  -e PHANTOM_API_KEY=your-secret-key \
  -v phantom-data:/data \
  polymit/phantom:latest

Full documentation: github.com/polymit/phantom-engine

---