Data-driven pages — DraftMesh documentation

Build a live dashboard from an HTML document that reads JSON files in the same workspace, using the window.draftmesh bridge. Complete worked example.

An HTML document can read JSON files from its own workspace and refresh itself when the data changes. That turns a workspace into a small live dashboard: the numbers live in a .json file anyone (or any agent) can update, and the .html page presents them.

An HTML dashboard rendering data from a workspace JSON file

How a page reads data

Inside a DraftMesh-rendered HTML document, a window.draftmesh bridge is available:

window.draftmesh.readJson(path) — returns a Promise of the parsed contents of a JSON file in the same workspace (the path is relative to the workspace root, e.g. "metrics.json" or "data/sales.json").
window.draftmesh.onDataChange(path, callback) — calls your callback whenever that file changes, so the page can re-read and re-render. No polling needed.

Pages can only read .json files from their own workspace — the bridge is not a general file or network API.

A complete example

Create metrics.json:

{
  "quarter": "Q3",
  "signups": [
    { "week": "W1", "count": 42 },
    { "week": "W2", "count": 58 }
  ]
}

And dashboard.html:

<!doctype html>
<html>
<head><meta charset="utf-8"><title>Signups</title></head>
<body>
<h1>Signups</h1>
<div id="out">Loading…</div>
<script>
  function render(data) {
    document.getElementById("out").textContent =
      data.quarter + ": " +
      data.signups.map(function (s) { return s.week + "=" + s.count; }).join(", ");
  }
  function load() {
    window.draftmesh.readJson("metrics.json").then(render);
    window.draftmesh.onDataChange("metrics.json", function () {
      window.draftmesh.readJson("metrics.json").then(render);
    });
  }
  if (window.draftmesh) { load(); } else { window.addEventListener("draftmesh-ready", load); }
</script>
</body>
</html>

The last line is the recommended startup pattern: use the bridge if it’s already there, otherwise wait for the draftmesh-ready event.

If a read fails, the Promise rejects with a reason you can show honestly: not_found (no such file), invalid_json (the file doesn’t parse), or unsupported_path (not a .json file in this workspace).

Updating the data

Anything that changes the JSON file updates every open page watching it:

In DraftMesh — open the .json file in Code mode and edit it. Saves are validated, so you can’t ship a syntax error to your dashboards.
Any other tool — the file is just a file. Edit it in your code editor, write it from a script or a scheduled job; DraftMesh notices the change on disk, versions it, and notifies open pages.
An AI assistant — a connected agent can update the file with its document-saving tool, with the same validation and the change attributed to the agent in history. See AI assistants (MCP).

Every update lands in version history, so a bad number can always be traced and rolled back.