nanotracker-api-sdk: Skill for Codex

Subscribe to nanoTracker changes (from outside the page)

When to use

You need to react to changes the user makes in the editor (or that another agent makes via the API) — for example, regenerating a visualisation, syncing to an external sequencer, logging edits.

Why subscribe doesn't cross the relay

window.nanoTracker.subscribe(fn) exists in the page, but it fires local React effects. The relay forwards request/reply pairs, not event streams. So external callers must poll.

The good news: getProjectSummary is dirt cheap. A 1 Hz poll is totally fine. A 10 Hz poll is fine for small projects. Don't go faster — the relay's rate limit is 20 batches/sec across all sources.

Cheap-revision pattern

let lastSig = "";
async function poll() {
  const out = await call("read", { op: "getProjectSummary" });
  const sig = JSON.stringify(out.data);
  if (sig !== lastSig) {
    lastSig = sig;
    onChange(out.data);
  }
  setTimeout(poll, 1000);
}
poll();

getProjectSummary returns scalars — bpm, speed, channels, patternCount, orderListLength, sampleCount, instrumentTableSize. The JSON is short and stable; comparing as a string works.

Detecting cell-level changes

Project summary catches structural changes (pattern added, bpm changed). It doesn't catch a single cell edit. For finer detection, add getPatternList:

const list = await call("read", { op: "getPatternList" });
const fp   = list.data.map(p => `${p.id}:${p.filledCells}`).join(",");

filledCells increments/decrements with every cell edit. Combine with the summary signature to catch most changes cheaply.

Cell-exact diffing

If you really need to know which cell changed, you have to fetch the range and diff client-side. Do that lazily — only when one of the cheaper signatures has changed.

Don't busy-loop on errors

If the page disconnects you'll start seeing errors with code: "internal", message: "no nanoTracker tab connected". Back off:

let backoff = 1000;
async function poll() {
  try {
    /* ... */
    backoff = 1000;
  } catch (e) {
    backoff = Math.min(backoff * 2, 30000);
  }
  setTimeout(poll, backoff);
}