Previewing Changes#

This guide shows how to see what an edit would do before you commit it through the raw WebAssembly exports. It covers previewing a drag or a resize, keeping previews in sync with the project's baseline, checking the resource load a change would cause, and trying multi-step edits or a leveling run on a copy of the project.

How previews work#

A solved JsonProject holds one accepted baseline: the dates from its last solve or level. Every preview starts from that baseline.

preview(changes_json, options_json) copies the baseline, applies a SchedulingChanges payload to the copy and schedules it. The copy is dropped when the call returns. The project stays as it was, so you can call preview as often as the UI needs, for example on every mouse move during a drag.

The envelope carries a regular ScheduleResult:

updates are relative to the baseline. They list the tasks the change would move and the tasks the change itself touched, like the solve(undefined, …) after an apply. An empty change set ("{}") gives empty updates.
conflicts, cycles and notes describe the previewed state. A preview can show the cycle a new link would create, and the project never holds that cycle.
baselineId names the baseline the preview read.

A preview differs from apply in two ways. It isn't partial. If any operation in the change set is invalid, the whole call returns a validation error envelope for the first rejected operation. It also needs a clean, solved baseline. Before the first solve, and after any apply until the next solve, it returns a project error with code no-baseline.

For a change that takes more than one step, or for a level run, use clone() instead. The clone is a new handle that shares immutable state with the original until one of them is edited, so it's cheap to create. Edit, solve or level the clone, and the original stays as it was.

You want to see	Use
The effect of one change set (a drag, a resize, a new link)	`preview`
The load a change would put on resources	`preview` with `profile` in the options
Several edits in a row, each solved	`clone()`, then `apply` + `solve(undefined, …)` on the copy
What leveling would do	`clone()`, then `level` on the copy

Preview#

Build the edit as a SchedulingChanges payload, the same JSON you'd pass to apply, and pass it to preview.

const { JsonProject } = require("./pkg-node/plen_wasm.js");

function unwrap(text) {
  const response = JSON.parse(text);
  if (!response.ok) {
    const { kind, code, message, path } = response.error;
    throw new Error(`${kind} ${code ?? ""}: ${message} (at ${path})`);
  }
  return response.result;
}

const data = {
  // All time is working time: plain day arithmetic, no weekends.
  config: { use_calendars: false },
  tasks: [
    { id: "a", start_date: "2026-01-01", duration: 2 },
    { id: "b", start_date: "2026-01-01", duration: 1 },
  ],
  links: [{ id: "ab", source: "a", target: "b", type: "fs" }],
};

const project = new JsonProject("{}");
try {
  unwrap(project.solve(JSON.stringify(data), "{}"));

  // The user drags task "b" to January 5.
  const drag = { tasks: { update: [{ id: "b", start_date: "2026-01-05" }] } };
  const preview = unwrap(project.preview(JSON.stringify(drag), "{}"));
  for (const update of preview.updates) {
    console.log(`task ${update.id}: ${update.start_date} .. ${update.end_date}`);
  }

  // The project still holds the solved dates: "b" starts on January 3.
  const current = unwrap(project.solve(undefined, "{}"));
  console.log(current.updates.every((u) => u.start_date !== "2026-01-05 00:00")); // true
} finally {
  project.free();
}

The solve puts b right after a, on January 3. The preview prints task b: 2026-01-05 00:00 .. 2026-01-06 00:00. The project doesn't change: the next solve(undefined, "{}") returns the cached result of the first solve.

When the user drops the task, send the same change set to apply and then call solve(undefined, …). See Editing a project.

The preview options take the same diagnostic switches as SolveOptions:

subtree previews only one branch.
reasons: true adds a reason to each update, which tells you why a task would move.
analytics adds the critical path and slack of the previewed state.

Previews stay sparse: there's no includeUnchanged option. The full option list is on the preview reference.

Guarding with baseline tokens#

A UI that previews in the background can run into a race. Another request applies an edit or reloads the data, and the preview now runs against a baseline the user never saw. Baseline tokens catch this.

Every solve and level result carries baselineId, an opaque token for the accepted baseline. Send it back as baselineId in the preview options (or in the change set). If the token no longer names the current baseline, preview returns a project error with code stale-baseline instead of dates for the wrong state.

const { JsonProject } = require("./pkg-node/plen_wasm.js");

const data = {
  config: { use_calendars: false },
  tasks: [{ id: "a", start_date: "2026-01-01", duration: 2 }],
};
const resize = JSON.stringify({ tasks: { update: [{ id: "a", duration: 3 }] } });

const project = new JsonProject("{}");
try {
  const loaded = JSON.parse(project.solve(JSON.stringify(data), "{}")).result;

  // The UI keeps the token of the dates it shows.
  const shown = loaded.baselineId;
  const guarded = JSON.stringify({ baselineId: shown });

  const preview = JSON.parse(project.preview(resize, guarded));
  // A preview reports the baseline it read, so its token works for the next preview too.
  console.log(preview.result.baselineId === shown); // true

  // Meanwhile, another edit is committed.
  project.apply(resize);

  // Until the next solve there is no baseline to preview against.
  const early = JSON.parse(project.preview(resize, "{}"));
  console.log(early.error.code); // "no-baseline"

  const latest = JSON.parse(project.solve(undefined, "{}")).result;

  // The old token no longer names the baseline.
  const stale = JSON.parse(project.preview(resize, guarded));
  if (!stale.ok && stale.error.code === "stale-baseline") {
    // Refresh the view from `latest`, then preview with its token.
    const fresh = JSON.stringify({ baselineId: latest.baselineId });
    const retry = JSON.parse(project.preview(resize, fresh));
    console.log(retry.ok); // true
  }
} finally {
  project.free();
}

The stale call returns this envelope:

{
  "ok": false,
  "error": {
    "kind": "project",
    "code": "stale-baseline",
    "message": "stale-baseline",
    "path": null
  }
}

A few rules for tokens:

Take the token from the latest solve or level result. A preview result carries the token it read, so a chain of previews during one drag can reuse it.
The token changes whenever the data changes: new data, an apply, a solve that moves dates, leveling edits.
Tokens are opaque. Don't parse them, store them across runs or compare them between runs. The same data can get a new token on a repeat run.
preview checks baselineId in the options and baselineId in the change set separately. Leave both out to skip the check.

For how to handle stale-baseline and the other project errors, see Error handling.

Preview with load#

Add a profile query to the preview options to see the resource load a change would cause. The result then has profile, the same per-bucket load and capacity that loadProfile returns, but computed on the previewed dates. Use it to show a resource histogram while the user drags a task.

const { JsonProject } = require("./pkg-node/plen_wasm.js");

function unwrap(text) {
  const response = JSON.parse(text);
  if (!response.ok) {
    const { kind, code, message, path } = response.error;
    throw new Error(`${kind} ${code ?? ""}: ${message} (at ${path})`);
  }
  return response.result;
}

const data = {
  config: { use_calendars: false },
  tasks: [
    { id: "a", start_date: "2026-01-01", duration: 2 },
    { id: "b", start_date: "2026-01-03", duration: 1 },
  ],
  resources: [{ id: "dev", capacity: 1 }],
  assignments: [
    { task: "a", resource: "dev", value: 1 },
    { task: "b", resource: "dev", value: 1 },
  ],
};

const project = new JsonProject("{}");
try {
  unwrap(project.solve(JSON.stringify(data), "{}"));

  // Drag "b" one day earlier, onto the last day of "a".
  const drag = { tasks: { update: [{ id: "b", start_date: "2026-01-02" }] } };
  const options = {
    profile: { from: "2026-01-01", to: "2026-01-05", tasks: "overallocated" },
  };
  const preview = unwrap(project.preview(JSON.stringify(drag), JSON.stringify(options)));

  for (const resource of preview.profile.resources) {
    for (const bucket of resource.buckets.filter((b) => b.load > b.capacity)) {
      console.log(
        `${resource.resource} overloaded at ${bucket.start}: ` +
          `${bucket.load} of ${bucket.capacity} (${bucket.tasks.join(", ")})`,
      );
    }
  }
} finally {
  project.free();
}

Both tasks need dev on January 2, so that bucket's load goes over its capacity of 1, and the code prints dev overloaded at 2026-01-02 00:00: 2 of 1 (a, b). With tasks: "overallocated", each overloaded bucket also lists the tasks that share it.

The query covers buckets that start in [from, to). By default it reports every resource, with the bucket size (basis) derived from config.duration_unit. Narrow it with resources, or switch basis. The profile object has no baselineId of its own. A baselineId inside it is an unknown field and fails with a parse error, so put the token at the top level of the preview options. Every preview also reports overallocations when the project has assignments, so you can skip the profile if you need only the overloaded windows. See Resource load and the LoadProfile reference.

Cloning a project#

preview takes one change set. To see the result of several edits in a row, each one solved before the next, clone the project and work on the copy.

const { JsonProject } = require("./pkg-node/plen_wasm.js");

function unwrap(text) {
  const response = JSON.parse(text);
  if (!response.ok) {
    const { kind, code, message, path } = response.error;
    throw new Error(`${kind} ${code ?? ""}: ${message} (at ${path})`);
  }
  return response.result;
}

function resize(id, duration) {
  return JSON.stringify({ tasks: { update: [{ id, duration }] } });
}

const data = {
  config: { use_calendars: false },
  tasks: [
    { id: "a", start_date: "2026-01-01", duration: 2 },
    { id: "b", start_date: "2026-01-01", duration: 1 },
  ],
  links: [{ id: "ab", source: "a", target: "b", type: "fs" }],
};

let project = new JsonProject("{}");
unwrap(project.solve(JSON.stringify(data), "{}"));

// A cheap copy: it shares state with `project` until it's edited.
const draft = project.clone();
unwrap(draft.apply(resize("a", 4)));
unwrap(draft.solve(undefined, "{}"));
unwrap(draft.apply(resize("b", 3)));
const outcome = unwrap(draft.solve(undefined, "{}"));

for (const update of outcome.updates) {
  console.log(`draft task ${update.id}: ${update.start_date} .. ${update.end_date}`);
}

// The original is untouched and still previews against its own baseline.
console.log(unwrap(project.preview("{}", "{}")).updates.length); // 0

// The user accepts the draft: keep it as the project, free the old handle.
project.free();
project = draft;
unwrap(project.solve(undefined, "{}"));
project.free();

The last draft solve prints draft task b: 2026-01-05 00:00 .. 2026-01-08 00:00. Edits on one copy never affect the other. The copy is a full JsonProject with its own baseline, cache and baselineId, so you can preview, level, evaluate or keep editing it.

To accept the draft, replace the original with it, or replay the same change sets on the original with apply. To discard it, call free() on it. A clone is a separate handle in WebAssembly memory, so free each one on its own. See Module and handles.

Clone before level too. level changes the project and accepts the leveled dates as the new baseline, so running it on a copy is how you show the user a leveling proposal before committing it:

function levelingProposal(project) {
  const draft = project.clone();
  try {
    const response = JSON.parse(draft.level("{}"));
    if (!response.ok) throw new Error(response.error.message);
    for (const update of response.result.updates) {
      console.log(`task ${update.id} delay ${update.leveling_delay}`);
    }
  } finally {
    draft.free();
  }
}

The step-by-step version is in Preview leveling. To compare several alternative change sets with scores, use evaluate instead. It works on disposable copies internally. See Evaluating alternatives.

Every export is synchronous and blocks the thread that calls it. A module instance is single-threaded, so to keep previews off the UI thread, run the project in a Web Worker or a worker thread. See Run in a worker.