Configuration reference

Files and loading#

Mockspace looks for .mockspace/config.mjs, .mockspace/config.js, mockspace.config.mjs, or mockspace.config.js in the project directory. The preferred layout keeps all declarations under .mockspace/ and screen metadata beside the application pages it describes.

The config is a native JavaScript module with a default export. Files it references are resolved from the project root.

Core config#

export default {
  name: "travel-app",
  purpose: "Help an agent prepare and confirm a trip.",
  audience: "Travel specialists reviewing several options under time pressure.",
  designPrinciples: ["Every price-changing decision keeps its previous context visible."],

  app: {
    url: "http://localhost:3000",
    command: "pnpm dev",
    env: { NEXT_PUBLIC_MSW_ENABLED: "true", API_KEY: "" },
  },

  defaultViewport: 1440,
  stateAddressing: "A fixture id in the trip route selects one coherent data world.",
  globalSources: ["src/app/globals.css", "src/app/layout.tsx"],
  testSources: ["src/test/fixtures.ts"],
  components: {
    ResultCard: { source: "src/components/result-card.tsx", purpose: "Compare one offer." },
  },
  auth: { cookies: {} },
  scenarios: "/api/mockspace/scenarios",
  flows: "./.mockspace/flows.mjs",
};

name, purpose, audience, and designPrinciples are the product context returned to agents. Keep them specific and verifiable.

app.url is the upstream application. Mockspace never starts it. When app.start is absent, string values in app.env are joined with app.command into the start command shown by check and dev. An explicit app.start wins; env remains documentation in that case.

defaultViewport supplies the frame width when a screen has no override. globalSources identifies files whose edit can affect every frame. testSources and component sources participate in the source-management boundary.

stateAddressing explains how this application selects fixtures. scenarios optionally points to a development catalogue whose labels and endpoint notes enrich states. auth.cookies are sent by the local proxy and capture when a noninteractive cookie is enough to cross the app gate.

Capture and diff settings#

export default {
  capture: { timeout: 20000, parsedTimeout: 10000 },
  diff: {
    ignoreSelectors: ["[data-testid=generation-elapsed]"],
    ignore: ["\\d+ minutes ago"],
  },
};

Capture waits for the DOM to become quiet and pauses animations before taking the result. capture.timeout controls the network-idle wait and capture.parsedTimeout the document-parsed fallback.

Use diff.ignoreSelectors only for values whose job is to vary, such as a clock or random seed. The element keeps its box and its text is masked during capture. diff.ignore is a later text-axis regular expression and does not stabilize structure, style, or screenshots.

Screen modules#

A page-owned module exports meta and states:

export const meta = {
  id: "inventory",
  name: "Inventory",
  route: "/trips/[id]/inventory",
  purpose: "Compare offers.",
  notes: ["An empty completed search is different from a failed search."],
  sources: ["src/app/trips/[id]/inventory/page.tsx"],
  components: ["ResultCard"],
  api: ["GET /api/trips/:id/inventory"],
  viewport: 1440,
};

export const states = [
  { id: "default", url: "/trips/trip-searched/inventory" },
  { id: "no-results", url: "/trips/trip-searched-none/inventory", purpose: "Completed empty search." },
];

The default state's URL becomes the screen URL. Other states require an ID and URL. Optional purpose, act, expect, and reachedBy explain and reach conditions beyond the default page.

Small workspaces may declare equivalent screen objects inline in a flow. Do not declare the same screen twice under different IDs.

Flow modules#

The file named by flows default-exports an array. A flow has id, name, purpose, optional levels and notes, ordered screens, and optional labelled edges.

import * as inventory from "../src/app/trips/[id]/inventory/page.mockspace.mjs";

export default [
  {
    id: "request-to-booked",
    name: "Request to booked trip",
    levels: ["Booking", "Flights"],
    purpose: "Review the booking journey end to end.",
    screens: [inventory],
    edges: [],
  },
];

levels is an optional array of non-empty group names ordered from outermost to innermost. Surrounding whitespace is trimmed. Omit it or use [] for an ungrouped flow. Levels organize only the flow navigator; they do not change canvas ordering, IDs, or links. The build context and local and hosted MCP flow metadata include these levels.

Run mockspace check --project <dir> after changing any declaration. Read Flows and Screens and states for modeling guidance.

Optional publishing context#

repo and tracker may name provenance destinations. thumbnail is one frame ID used as a build cover. prototype can describe a same-app interactive starting path; its origin comes from where the viewer runs, not the workspace.

ship declares how an accepted request leaves the workbench: target branch, default pr or issue, and an optional issuePipeline label. These fields describe repository policy; they do not grant access or perform a handoff.