Investigate Scheduler API for canceling stale Waypoints UI work

[acodebeard]

Summary

Investigate whether the browser Scheduler API can improve Waypoints responsiveness by canceling stale queued UI work when the visitor changes search/category/route inputs quickly.

This came from looking at scheduler.postTask() with AbortController support. The main idea is not to make heavy work magically interruptible, but to avoid running queued work that is already obsolete.

Potential Waypoints use cases

• Cancel stale search/result rendering after the visitor types or changes category.
• Cancel stale map marker updates when the result set changes.
• Cancel stale route preview/reorder calculations when waypoints are added, removed, or reordered.
• Run non-urgent work at background/user-visible priority instead of immediately blocking the main thread.

Important limitation

postTask() can cancel queued tasks before they run. It does not automatically stop a synchronous heavyCalc() once that function is already executing.

For genuinely heavy work, the implementation may still need one or more of:

• chunked work that checks signal.aborted between chunks;
• cooperative cancellation inside loops;
• requestIdleCallback() fallback where appropriate;
• a Web Worker for expensive route/result calculations;
• normal AbortController use for fetch requests.

Research tasks

• Check current browser support for scheduler.postTask() and its signal option.
• Decide whether this is safe for production now, progressive enhancement only, or too early.
• Identify the specific Waypoints functions where stale work can currently overwrite newer UI state.
• Prototype a small wrapper such as scheduleWaypointTask(fn, options) with fallback behavior.
• Confirm that aborting an old task prevents old results/map markers from rendering after newer input.
• Add comments/tests around cancellation so future changes do not reintroduce stale UI updates.

Possible implementation sketch

let currentController = null;

function scheduleWaypointRender(results) {
  if (currentController) {
    currentController.abort();
  }

  currentController = new AbortController();
  const { signal } = currentController;

  const run = () => {
    if (signal.aborted) return;

    renderWaypointResults(results);

    if (signal.aborted) return;

    updateMapMarkers(results);
  };

  if ('scheduler' in window && typeof scheduler.postTask === 'function') {
    return scheduler.postTask(run, {
      signal,
      priority: 'user-visible'
    });
  }

  return Promise.resolve().then(run);
}

Acceptance criteria

• Rapid input/category changes do not cause older results to render after newer results.
• Map markers stay in sync with the latest result set.
• Unsupported browsers keep the current behavior or use a safe fallback.
• No new hard dependency on an experimental API without a fallback.
• Any heavy synchronous work remains explicitly cooperative/chunked or is left for a separate worker-focused issue.