Virtual Runtime Environment

Read the content of a file from the VFS. Returns null if the file does not exist.

const html = vre.readFile('/index.html');
const css  = vre.readFile('/style.css');
console.log(html.length); // character count

Update an existing file's content and hot-reload the preview. Throws if the file does not exist — use addFile to create new files.

vre.updateFile('/style.css', 'body { background: red; }');

Add a new file to the VFS. Throws if the path already exists unless overwrite is true.

vre.addFile('/utils.js', 'export const add = (a, b) => a + b;');
vre.addFile('/style.css', 'body {}', { overwrite: true });
vre.addFile('/data.json', '{"key":"value"}', { mimetype: 'application/json' });

Remove a file from the VFS. Throws { code: 'NOT_FOUND' } if the path does not exist.

vre.deleteFile('/old-script.js');

Move or rename a file within the VFS.

vre.renameFile('/app.js', '/src/app.js');

List all files in the VFS as a flat metadata array. Does not include directory entries.

const files    = vre.listFiles();
const jsFiles  = vre.listFiles({ extensions: ['js'] });
const srcFiles = vre.listFiles({ prefix: '/src' });

Line-by-line diff between the current file content and a new string.

const diff = vre.diffFile('/app.js', newCode);
diff.forEach(line => {
  if (line.type === 'add')    console.log('+', line.text);
  if (line.type === 'remove') console.log('-', line.text);
});

Save and restore the entire filesystem state. snapshotFilesystem() returns an opaque token string.

const token = vre.snapshotFilesystem();
vre.updateFile('/style.css', 'body { background: red; }');
vre.restoreSnapshot(token); // rolls back

Replace or read back the entire filesystem object.

vre.setFileSystem(newFs, { entryPath: '/index.html' });
const fs = vre.getFileSystem();

run() starts or restarts the preview. stop() returns to idle. reload() is an alias for run(). destroy() stops and removes the shell from the DOM entirely.

vre.run();
vre.run(newFs, { entryPath: '/index.html' });
vre.stop();
vre.destroy();

getStatus() returns a plain serialisable object safe to pass directly to an LLM. isRunning() and isReady() return booleans.

const status = vre.getStatus();
// { running, ready, entryPath, inspecting, activeTab, devtoolsOpen }

onReady() resolves when the engine becomes ready (immediately if already ready). waitForLoad() resolves when the preview finishes loading. reset() hard-resets and clears all devtools state.

await vre.onReady();
vre.run();
const { entryPath } = await vre.waitForLoad({ timeout: 15000 });
vre.reset({ fileSystem: newFs, entryPath: '/index.html' });

Navigate to a path. open() starts the preview if not already running. Pass { push: false } to skip history.

vre.open('/about/index.html');
vre.open('/contact.html', { push: false });
vre.back(); vre.forward();

Set the entry path without navigating. getEntryPath() returns the current entry path string.

vre.setEntryPath('/about/index.html');
console.log(vre.getEntryPath()); // '/index.html'

setViewport() accepts a named preset ('mobile' 390px, 'tablet' 768px, 'desktop' full) or an explicit { width } object.

vre.setViewport('mobile');
vre.setViewport({ width: 480 });
const history = vre.getHistory();
// ['/index.html', '/about/index.html']

Open or close the preview in a separate browser window.

vre.setExternalMode(true);  // opens external window
vre.setExternalMode(false); // returns to embedded preview

All captured console entries since last clear. Filter by level, filter (text), or limit. getErrors() is a shorthand for error-level only.

const errors = vre.getConsoleLogs({ level: 'error' });
const recent = vre.getConsoleLogs({ limit: 20 });
const errs   = vre.getErrors();

All captured network requests since last clear. Filter by method, status, filter, or limit.

const failed = vre.getNetworkLog({ status: 404 });
const api    = vre.getNetworkLog({ filter: '/api/' });

All source files captured by the engine, as a flat array.

const sources = vre.getSources();
// [{ domain: 'my-project', path: '/app.js', fullUrl: '/app.js' }, ...]

Set the maximum number of console/network entries kept in memory. Default is 500.

vre.setLogBuffer(1000);

Tab options: 'console' · 'network' · 'sources' · 'elements'. getActiveTab() returns the currently active tab id. getDevtoolsOpen() returns true if the panel is visible. clearDevtools() clears all panels at once.

vre.switchTab('network');
console.log(vre.getActiveTab()); // 'network'
vre.setDevtoolsOpen(true);
if (!vre.getDevtoolsOpen()) vre.setDevtoolsOpen(true);
vre.clearDevtools();

Manually refresh the Sources or Network panel.

vre.refreshSources();
vre.refreshNetwork();

getDOM() returns the last full DOM snapshot (async). queryDOM() runs a CSS-selector query against it (sync). Supports: tag, .class, #id, [attr], [attr=value].

await vre.getDOM({ fresh: true });
const buttons = vre.queryDOM('button');
const cards   = vre.queryDOM('.card');
const inputs  = vre.queryDOM('[type=text]');
console.log(buttons[0].tag);        // 'button'
console.log(buttons[0].attributes); // [{ name, value }, ...]
console.log(buttons[0].path);       // [0, 1, 3, ...] — path for getElement()

Get full inspect detail for a DOM node by its path array (from queryDOM()). Returns tag, id, classList, computedStyle, boundingRect, and more.

const el = await vre.getElement(buttons[0].path);
console.log(el.tag);       // 'button'
console.log(el.classList); // ['btn', 'btn-primary']

Shorthand — returns just the computed styles map for a node.

const css = await vre.getComputedStyles(buttons[0].path);
console.log(css['font-size']); // '13px'

getBoxModel() returns the full CSS box model (margin, border, padding, content). getLayout() returns just the bounding box in iframe viewport coordinates.

const box  = await vre.getBoxModel(buttons[0].path);
// { margin, border, padding, content: { x, y, width, height } }
const rect = await vre.getLayout(buttons[0].path);
// { x: 32, y: 88, width: 94, height: 32 }

Returns a role/name accessibility tree derived from the DOM snapshot.

const a11y = await vre.getAccessibilityTree();
// { role: 'generic', tag: 'html', children: [...] }

Highlight a DOM node in the preview (same as hovering in the Elements panel). clearHighlight() removes any active highlight overlay.

vre.highlightElement(buttons[0].path); // by path array
vre.highlightElement('.hero');          // by CSS selector
vre.clearHighlight();

patchStyle() live-patches a CSS property and writes back to the VFS source. applyCSS() injects arbitrary CSS without touching the VFS — pass { id } to overwrite on subsequent calls.

vre.patchStyle('.hero', 'background', 'red');
vre.patchStyle('.card', 'padding', '32px', { sourceFile: '/style.css' });
vre.applyCSS('.hero { display: none; }', { id: 'hide-hero' });

refreshDOM() forces a fresh DOM snapshot and re-renders the Elements panel. inspectStart() activates the element picker. inspectStop() deactivates it. isInspecting() returns true if the picker is active.

vre.refreshDOM();
vre.inspectStart();
if (vre.isInspecting()) vre.inspectStop();

The single most important agent method. Returns a complete serialisable snapshot of everything — status, files, DOM, errors, logs, network — in one call. Pass this directly into an LLM prompt.

const ctx = await vre.getContext({
  includeDom:   true,  // default true
  includeFiles: true,  // default true
  domDepth:     4,     // DOM tree depth
  logLimit:     50,    // max log entries
});
// ctx: { status, files, errors, consoleLogs, networkLog, sources, dom, timestamp }

Evaluate a JavaScript expression inside the live preview iframe. evalAsync() wraps code in an async IIFE for await expressions. Rejects with EVAL_ERROR or TIMEOUT.

const title = await vre.eval('document.title');
const data  = await vre.evalAsync('return await fetch("/api").then(r => r.json())');

Take a PNG screenshot of the current preview viewport. Returns an ArrayBuffer of PNG bytes. captureElement() is a shorthand for capture({ selector }).

const png     = await vre.capture();
const cardPng = await vre.captureElement('.hero');

Simulate a click by CSS selector or page coordinates.

await vre.click('#btn-run');
await vre.click(100, 200); // by coordinates

Type text into an input or textarea. Fires input and change events. Pass { clear: true } to clear existing value first.

await vre.type('#email', 'user@example.com', { clear: true });

scroll() accepts { x, y } or { selector }. hover() fires mouseenter and mouseover. focus() focuses an element.

await vre.scroll({ selector: '.footer' });
await vre.scroll({ x: 0, y: 500 });
await vre.hover('.card');
await vre.focus('#search-input');

Poll the live preview until a condition is met. All reject with { code: 'TIMEOUT' } on expiry. waitForConsole() accepts a string or predicate function. waitForRequest() accepts a substring or regex.

await vre.waitForElement('.results', { timeout: 10000 });
await vre.waitFor('window.appReady === true');
await vre.waitForConsole('[app.js] Init complete');
const req = await vre.waitForRequest('/api/data', { method: 'POST' });

Run a declarative sequence of API actions. Never throws — collects errors and returns { results, errors }.

const { results, errors } = await vre.runScript([
  { action: 'eval',           args: ['document.title'] },
  { action: 'click',          args: ['#btn-run'] },
  { action: 'waitForConsole', args: ['Init complete'] },
  { action: 'capture',        args: [] },
]);

Standard subscribe/unsubscribe pattern. once() auto-unsubscribes after first firing. clearListeners() with no argument clears all events.

vre.on('consoleLog', e => console.log('[preview]', e.level, e.message));
vre.on('error', e => console.warn('Preview error:', e.message));
vre.on('networkLog', e => console.log(e.method, e.url, e.status));
vre.on('fileChange', e => console.log(`File ${e.type}:`, e.path));
vre.once('load', e => console.log('First load:', e.entryPath));

Switch the shell colour theme. Built-in values: 'dark', 'light', 'system'. Pass a token object for a custom theme.

vre.setTheme('light');
vre.setTheme('dark');

Show or hide the entire toolbar. Pass false for embed-only mode.

vre.setToolbarVisible(false); // hide for embed mode
vre.setToolbarVisible(true);

Set the devtools panel height in pixels.

vre.setDevtoolsHeight(400);

Lock the preview — hides play/stop/URL bar, disables inspector pick and style editing. Pass true for viewer mode, false to restore editing.

vre.setReadOnly(true);  // viewer mode
vre.setReadOnly(false); // restore editing

Set placeholder text in the URL bar.

vre.setTitle('My Sandbox');

Add a custom button to the toolbar. Returns a handle with a remove() method.

const btn = vre.addToolbarButton({
  icon: '<svg>...</svg>',
  title: 'Export',
  id: 'btn-export',
  onClick: () => console.log(vre.exportProject())
});
btn.remove();

Show a transient notification banner inside the shell. Types: 'info' (default) · 'success' · 'warn' · 'error'. Duration in ms, default 3000. Set to 0 for no auto-dismiss.

vre.showNotification({ message: 'Saved!', type: 'success' });
const n = vre.showNotification({ message: 'Working...', type: 'info', duration: 0 });
n.dismiss();

getIframe() returns the raw preview <iframe> element. getRoot() returns the shell root <div> element.

const iframe = vre.getIframe();
const root   = vre.getRoot();

Temporarily places an interaction shield over the preview iframe. Useful when a host IDE or outer shell has resize handles that may drag across the iframe. Common cursor values: 'ew-resize', 'ns-resize', 'grabbing'.

splitter.addEventListener('mousedown', () => {
  vre.setIframeInteractionBlocked(true, 'ew-resize');
});
document.addEventListener('mouseup', () => {
  vre.setIframeInteractionBlocked(false);
});

Send a raw postMessage to the preview iframe.

vre.postMessage({ type: 'myCustomEvent', data: { foo: 'bar' } });

Add or remove URL substring patterns to hide from console, network, and sources panels. Case-insensitive substring matches against the full URL.

vre.blockPatterns(['hotjar', 'segment', 'intercom']);
vre.unblockPatterns('hotjar');
console.log(vre.getBlockedPatterns());

Write multiple files in one shot — hot-reloads the preview once at the end instead of once per file.

vre.writeFiles([
  { path: '/index.html', content: newHtml },
  { path: '/style.css',  content: newCss },
  { path: '/app.js',     content: newJs },
], { entryPath: '/dashboard.html' });

Export the entire filesystem as a serialisable JSON object — useful for saving and sharing. importProject() restores it, optionally running on import. Pass { includeContent: false } to export metadata only.

const project = vre.exportProject();
// { meta: { exportedAt, entryPath, fileCount }, files, filesystem }

localStorage.setItem('my-project', JSON.stringify(project));

const saved = JSON.parse(localStorage.getItem('my-project'));
vre.importProject(saved, { run: true });