Back to all guides

Preview and iterate

Watch your app run live inside Castforge, switch device frames, and rewind through snapshots with the Time Machine as your agents work.

Overview

Castforge can run your project's development server and show the running app in a live Preview panel, right next to the conversation with your agents. The dev server starts as soon as the project becomes active, so the Preview is already warm by the time you open it. As your agents change code, the dev server hot-reloads and the Preview updates, and Castforge also nudges a refresh as agents finish cards, so you can see your app take shape without leaving the app.

This live Preview is for Web app projects. A project whose type is Unreal Engine opens to a dedicated Unreal panel instead of the web Preview, covered in "The Unreal panel" below. You can change a project's type at any time from settings, and the surface re-routes right away. Everything from "The live Preview panel" onward describes the web Preview.

This page covers:

The Unreal panel

If your project's type is Unreal Engine, opening Preview takes you to a dedicated Unreal panel instead of the web Preview described in the rest of this page. You can change a project's type at any time from project settings, and the surface re-routes right away.

Connecting to your editor

The panel header shows a connection pill telling you what Castforge sees:

Click Reconnect at any time to re-check for a running editor. When no editor is connected, the panel shows a calm Open your Unreal editor state instead of an error: open the project in Unreal, then choose Reconnect. This is an Unreal project, so the web live preview stays off.

The viewport

Once connected, the viewport shows a captured frame of your Unreal editor's own view. Click Refresh to capture the viewport on demand, or turn on Near-live to have the panel keep refreshing on a short throttle while it stays open. A helper line under the toggle reads "Live view pauses when you leave this panel," and that is a real guarantee, not just a description: near-live only runs while the panel is the active, mounted view, so it never captures in the background.

A row of controls above the viewport lets you shape what the next capture shows:

Changing either fires a fresh capture immediately.

The UE Time Machine

The panel has its own inline Time Machine strip, separate from the web Preview's Time Machine drawer covered later on this page. It captures a keyframe of the viewport each time an agent finishes a card, laid out oldest to newest, left to right, using the same Keyframes density setting (Every card, Milestones only, or Manual only) to decide which card completions append one.

Click a past keyframe to peek at it as a still image: the viewport pauses on that frame and an amber banner names the card it came from. Choose Return to live (or press Escape) to come back to the live viewport.

The Tool palette

Below the viewport, the Tool palette lets you search your Unreal editor's tools and run one yourself. Type in the search box to find a tool by name; results are grouped by category, and each row carries a risk badge so you can see at a glance what a tool does.

Select a tool to open its detail view. Tools with a known parameter shape show a simple typed form (text, number, and checkbox fields); tools without one fall back to a plain parameters box where you can enter JSON arguments or raw Python. Choose Run to run it. The result comes back in a scrollable panel, and long output is trimmed with a "Result truncated for display" note so the panel stays responsive.

Running a tool is gated by risk:

Like the rest of the panel, the palette does no work while it is hidden: searches and runs are on demand only, and anything in flight stops when you leave the panel.

The Asset gallery

Below the Tool palette, the Asset gallery lets you browse your Unreal project's assets in a grid. A row of type chips across the top lets you narrow the grid to a single kind of asset (meshes, materials, textures, and so on); choose All to see everything again.

Each tile shows a live thumbnail of its asset, rendered fresh from your open Unreal editor. Thumbnails load only when a tile scrolls into view, never all at once, and once a thumbnail loads it is cached, so scrolling back to a tile you already saw does not re-render it. That cache is memory-bounded and self-evicting: it keeps a capped number of thumbnails and drops the oldest ones as you browse, so opening the gallery on a large project stays fast and light instead of growing without limit. A tile that has not loaded yet shows a calm dark placeholder rather than a blank white box.

Click any tile to open its read-only detail view. It shows the asset's name, type, and path, plus any extra information your editor reports for that asset. If those extra details are not available, the view still shows the name, type, and path, so you never hit a dead end. Choose Close or press Escape to return to the grid.

Like the rest of the panel, the gallery does no work while it is hidden: the asset list and each thumbnail load on demand only, and anything in flight stops when you leave the panel. The gallery is read-only, so browsing it never changes your project.

Node inspectors

Below the Asset gallery, the Node inspector lets you look inside a graph asset from your Unreal project. Pick a kind, Behavior Tree, State Tree, Blueprint, or Niagara, enter the asset's path, then choose Refresh to read the graph from your editor and draw it: nodes as labeled boxes, connections as arrows between them.

Refresh is on demand only. The inspector never polls in the background, so the graph you see is exactly what your editor reported the last time you asked, and switching to a different kind or asset path does not fetch anything until you Refresh again. If your editor's graph changes, choose Refresh to pull the latest version.

For a very large graph, the inspector caps how much it draws and shows a "Showing the first N nodes" notice, so a huge Blueprint or Niagara graph stays responsive instead of freezing the view.

Like the rest of the panel, the Node inspector does no work while it is hidden: nothing loads and nothing refreshes until you open the panel and choose Refresh yourself. The Node inspector is read-only, so inspecting a graph never changes your project.

Dashboards

Below the Node inspector, the Dashboards region gathers three cockpit cards for reading and editing project data from your open Unreal editor: Data Tables, a drop-rate simulation, and perf traces. Every card loads on demand only, so the Dashboards do no work until you ask.

Data Tables. The Data Tables card shows a Data Table asset as an editable grid. Enter a Data Table asset path, then choose Load to read its rows and columns. Edit cells inline, add rows with Add row, or remove a row with its trash button; a summary line tells you how many cells changed and how many rows were added or removed. Your edits stay local until you save: choose Save and Castforge shows a confirmation dialog listing exactly what will change (which cells, which added rows, which removed rows). Nothing is written to your project until you confirm in that dialog. This confirm gate is enforced by Castforge itself, so a Data Table edit can never be written without your explicit confirmation. A large table is capped for display with a "Table truncated for display" note so the grid stays responsive.

Drop-rate simulation. The Simulation card runs a gameplay-event drop-rate simulation and charts the result. Enter optional parameters, then choose Run sim. The result comes back as a bar chart, one bar per event bucket, with a small table of the exact rates beneath it. A run that returns no buckets shows a calm "No drop-rate buckets to chart" state rather than an empty box, and a large result set is capped with a "Results truncated for display" note. The sim runs only when you choose Run sim; it never runs in the background.

Perf traces. The Perf trace card captures an Unreal Insights perf-trace summary and shows before and after deltas across captures. Choose Capture snapshot to read the current metrics. Capture again and each metric shows how it changed since the previous capture: the change is shown as a signed number, a direction arrow, and a direction word ("up", "down", or "no change") together with color, so the direction is always readable, not color alone. The before and after values also appear as a small paired mini-bar per metric. The comparison is kept in memory while you work, so leaving the panel and coming back keeps your last two snapshots, and it resets when you restart Castforge.

Like the rest of the panel, the Dashboards do no work while they are hidden: the Data Table load, the simulation, and the perf capture all run on demand only, and anything in flight stops when you leave the panel.

The live Preview panel

Open the Preview view for a project to see a split layout: your conversation on the left and the live Preview on the right. Because the dev server starts when the project becomes active (not when you click the Preview tab), the app is usually already loaded the moment you open Preview. The Preview area shows your running development server inside an embedded view (an iframe) pointed at localhost on the port your dev server picked.

The Preview is read-from-your-machine: Castforge does not host anything here. It simply runs the same dev server you would run in a terminal (npm run dev, or the equivalent for your package manager) and frames the result so you can watch it update.

A small status dot in the URL bar tells you what the preview is doing:

Starting the preview

Auto-start (the default)

When a project becomes active (you open the project and its workspace), Castforge starts the preview for you automatically, before you ever click the Preview tab. You see the amber "starting" dot, then the green "running" dot once the port is ready. Because the server is already warm, opening the Preview view shows an already-loaded app. This happens on the very first open too, so for most projects you never click anything to get a live preview.

Castforge runs your project's dev script. It detects your framework (Next.js when your package.json lists next, otherwise Vite) and uses the right adapter. The package manager (npm, pnpm, or yarn) is resolved from your lockfile, so the underlying npm run dev runs correctly even if you use pnpm or yarn.

The Auto-start toggle

A small Auto-start switch sits in the Preview header. It is on by default and controls the per-project setting:

  1. When Auto-start is on, the preview starts when the project becomes active.
  2. When Auto-start is off, the preview waits for you to start it by hand, and you see a Start preview button instead.

Turn Auto-start off for a project if you would rather control the server yourself. Castforge never starts a preview on app launch; it starts when you open a project (and only then if Auto-start is on). When you switch to another project or leave the workspace, Castforge stops the server it started for you, so exactly one preview server runs at a time.

Brand-new projects: waiting for setup

Castforge only starts the preview once the project is actually ready to run one. A brand-new project (its package.json was just written, but its dependencies are not installed yet) or a project still being scaffolded has nothing to serve, so starting a dev server would only fail. In that case the Preview shows a calm "Waiting for project setup" message instead of a crash. As soon as the setup finishes (dependencies install, the framework files land), Castforge notices and starts the preview on its own, then keeps it running. You do not need to click anything.

If the preview crashes

If a running preview crashes, Castforge tries to restart it automatically a couple of times (with a short back-off) before giving up. If it still cannot start, you see the stopped state with the last error and a Try again button (see Empty and error states below).

The URL bar and reload

The URL bar in the Preview header shows:

Click reload, or press Ctrl+R while focused in Preview, to refresh the embedded view. A brief flash confirms the reload. The reload button is disabled when the dev server is not started or has crashed (there is nothing to reload yet).

Device frames

Use the device-frame toggle at the left of the Preview header to wrap your app in a device chrome. Four options are available, in order:

  1. Web (globe icon): no device frame. Your app fills the available width.
  2. Phone (smartphone icon): a 375 by 812 phone canvas.
  3. Tablet (tablet icon): a 768 by 1024 tablet canvas.
  4. Desktop (monitor icon): a 1280 by 800 desktop canvas.

Switching frames scales the canvas to fit the available space and does not reload your app, so you can flip between sizes quickly to check responsive layouts. Your chosen frame is saved per project.

Empty and error states

The Preview area shows a clear message instead of your app in these cases:

If the embedded view is blank but the status dot is green, try the reload button. If it stays blank, confirm the app actually serves a page at the shown localhost address.

Inspect and the visual editor (partial)

The Preview header includes an Inspect toggle (the eye icon). It is enabled only while the dev server is running.

In the current build, the Inspect toggle stores the on/off state, but the on-canvas inspect overlay and the click-to-edit visual editor popover are not yet active in the Preview. The design intent is to let you hover and click an element to outline it, see its size, edit text and color inline, and send a request about that exact element to your agent. Treat Inspect and the visual editor as a work in progress for now: the toggle is present, but the full inspect-and-edit flow is not yet wired into the live Preview.

The Time Machine

The Time Machine drawer lives in the Preview view, pinned to the bottom of the preview column. It opens automatically when you enter Preview, and you can collapse it any time with the chevron (the next time you open Preview it opens again by default). It captures a snapshot, called a keyframe, each time an agent finishes a card, so you can scroll back through your project's recent visual history and peek at any past state.

Reading the drawer

You can move focus across keyframes with the Left and Right arrow keys.

Peeking at a past state

Click a past keyframe to peek at it. Peeking opens that historical state in the Preview behind an amber glow and shows a banner: "Peeking keyframe {N}, agent writes continue in live state (this is view-only)."

Peeking is view-only. Your agents keep working against the live state while you look back; peeking does not pause them and does not change your files. The banner stays until you leave peek mode.

Rewinding or resuming

From the peek banner you have two actions:

Common questions

My Preview is blank or will not load. What should I check?

In order: is the status dot green (running)? If amber, wait for it to finish starting. If it is dim, Auto-start is off, so click Start preview. If it is red, Castforge has already tried to restart it automatically; read the error tail in the stopped state, fix it the way you would in a terminal, then click Try again. If the dot is green but the view is blank, click reload, and confirm your app serves a page at the localhost address shown in the URL bar.

Which dev servers does Preview support?

Castforge runs your project's package.json dev script. It has first-class detection for Next.js (when next is a dependency) and Vite, and falls back to running the generic dev script otherwise. Your package manager (npm, pnpm, or yarn) is detected from your lockfile.

Why did the preview not start?

By default Castforge auto-starts the preview when the project becomes active, so it is usually already warm before you open the Preview view. If you see "Waiting for project setup", the project is brand-new or still being scaffolded and its dependencies are not installed yet; Castforge starts the preview on its own the moment setup finishes, so you can leave it. Otherwise, check that the Auto-start switch in the Preview header is on, and that the project is a web project Castforge can serve (it runs your package.json dev script). If the preview started and then crashed, Castforge retries a couple of times before showing the stopped state with a Try again button.

Does Castforge host my running app?

No. The Preview runs your dev server locally on your own machine and frames localhost. Hosting and public links are part of publishing, covered in the publishing and deploying guide.

Can I edit elements visually by clicking them in the Preview?

Not yet in the current build. The Inspect toggle is present (and only active while the dev server runs), but the click-to-edit overlay and visual editor are still being wired into the live Preview.

Are Time Machine snapshots automatic?

The Time Machine captures a keyframe each time an agent finishes a card. If your drawer shows "No keyframes yet", run an agent through a card to begin building history. Peeking is always view-only and never interrupts your agents.

Does peeking at an old keyframe stop my agents or change my files?

No. Peeking is view-only. Agents continue writing to the live state while you look back, and your files are untouched until you explicitly choose Rewind to here, which creates a new branch.

My project is Unreal Engine. Where is the live Preview?

Unreal Engine projects do not use the web Preview. Opening Preview shows the dedicated Unreal panel instead: a viewport captured from your running Unreal editor, camera and show-flag controls, a connection pill with one-click Reconnect, and its own inline UE Time Machine strip. See "The Unreal panel" above. You can change a project's type from settings if you want the web Preview instead.

Can I run Unreal editor tools from the panel?

Yes, from the Tool palette below the viewport. Search for a tool by name, select it to see its details, fill in the typed form (or the raw Python fallback for tools without a known parameter shape), and choose Run. Safe tools, reads like get, list, or search, run right away. Tools that change or delete project state open a confirm dialog first, with a stronger warning for destructive ones, and only run after you explicitly confirm. This gate is enforced by Castforge itself, so it cannot be skipped from the UI alone.

Can I browse my Unreal project's assets?

Yes, from the Asset gallery below the Tool palette. It shows your assets in a grid you can filter by type, with thumbnails that load only as tiles scroll into view so large projects stay fast. Click any tile for a read-only detail view with the asset's name, type, path, and any extra details your editor reports. The gallery is read-only: browsing it never changes your project.

Can I inspect a Behavior Tree, Blueprint, or Niagara graph?

Yes, from the Node inspector below the Asset gallery. Pick a kind, Behavior Tree, State Tree, Blueprint, or Niagara, enter the asset's path, and choose Refresh to draw the graph read from your editor. Refresh is on demand only, so nothing loads or refreshes in the background, and a very large graph shows a "Showing the first N nodes" notice instead of trying to draw everything at once. The Node inspector is read-only: inspecting a graph never changes your project.

Can I edit Data Tables or run a drop-rate sim and perf trace?

Yes, from the Dashboards below the Node inspector. The Data Tables card loads a Data Table as an editable grid; your edits stay local until you choose Save, which opens a confirmation dialog listing exactly what will change, and nothing is written to your project until you confirm. That confirm gate is enforced by Castforge itself, so a Data Table write can never happen without your explicit confirmation. The Simulation card runs a gameplay-event drop-rate sim on demand and charts the buckets. The Perf trace card captures an Unreal Insights summary and, on a second capture, shows before and after deltas paired with a direction arrow and word so the change is readable without relying on color. Like the rest of the panel, the Dashboards load on demand only and do no work while the panel is hidden.