Run Mockspace locally

Before you start#

Work from the application repository that contains .mockspace/config.mjs. Install Mockspace using the installation guide, and make sure the application's own dependencies are installed.

Mockspace does not start the application. The config records the app URL, command, and environment so every contributor can run the same capture target.

Validate the workspace#

Run check before starting the canvas:

mockspace check --project .

The output names the workspace, the exact application start command, flows, screens, frame count, states, alternate orders, mocking strategy, and missing declared source paths. A nonzero exit means the spec needs attention before capture.

If the Mockspace files live in a nested application, pass that directory instead of ..

Start the application#

Copy the app command printed by mockspace check and run it in its own terminal. This is the config's app.start, or the combination of app.env and app.command.

Confirm the configured app.url answers with the expected development data. A different process on that port can produce a valid-looking capture of the wrong checkout.

Open the live canvas#

In another terminal, run:

mockspace dev --project .

The command prints the viewer URL, the upstream app URL and start command, and an MCP registration command. The default viewer is http://localhost:4310; use --port when that port is occupied.

The live canvas proxies the running application. Changes under .mockspace/ reload after a short quiet period while preserving camera and selection. Invalid metadata leaves the previous valid spec in place and reports the problem. Application source changes remain the application's hot-reload responsibility.

Create an inert local build#

When the live result is correct and the app is running, capture a static build:

mockspace build --project . --out dist

The output contains index.html for the canvas, screens.html for a sidebar-and-screen reader, and one inert document per frame under frames/. The app does not need to run when someone later reads those generated files.

Use --app <url> to capture from a different running origin, such as an isolated branch port. Use --only <frame-or-prefix> with --reuse <dir> for an incremental recapture; without --reuse, the current output directory is the reuse source.

Stop and recover#

Stop mockspace dev with the terminal interrupt. It does not own the application process, so stop that separately.

If every frame suddenly shows sign-in or stale content, verify the process that owns the configured app port and restart the app after changing a boot-time fixture layer. Continue with Troubleshooting.