The .scritch scene format

Start from a working example

flowchart.scritch is a complete diagram — bound elbow arrows, labels on shapes and on arrows, a wrapped caption. Download it, drop it on the canvas, then open it in an editor to see how each piece is written.

Getting a file onto the canvas

There are three ways in, and they all run the same validation:

• The import button in the toolbar — the one beside Download. It works on an empty canvas.
• Drag and drop a .scritch file anywhere onto the canvas.
• Sketches menu (the folder icon) → “Open .scritch file…”. The same menu has “Save as .scritch file” to get one back out.
• Scripted — window.scritch.load(), covered at the bottom.

Opening a file replaces the canvas, but it lands on the undo stack — ⌘Z brings your drawing back.

The smallest useful file

A bare array of shapes is accepted, so the shortest thing that draws something is one line. Ids, colours and stroke widths all have defaults.

[
  { "type": "rect", "x": 0, "y": 0, "w": 160, "h": 80 }
]

The full wrapper adds a type tag and a version, and is what “Save as .scritch file” writes:

{
  "type": "scritch",
  "version": 1,
  "shapes": [
    { "id": 1, "type": "rect", "x": 40, "y": 40, "w": 200, "h": 100,
      "color": "#3b82f6", "width": 4 },
    { "id": 2, "type": "text", "text": "for each card",
      "size": 22, "color": "#3b82f6", "containerId": 1 },

    { "id": 3, "type": "diamond", "x": 480, "y": 260, "w": 220, "h": 140,
      "color": "#f97316", "width": 4 },
    { "id": 4, "type": "text", "text": "threw?",
      "size": 22, "color": "#f97316", "containerId": 3 },

    { "id": 5, "type": "arrow", "x1": 240, "y1": 90, "x2": 480, "y2": 330,
      "color": "#64748b", "width": 4,
      "startBinding": 1, "endBinding": 3, "route": "orthogonal" },
    { "id": 6, "type": "text", "text": "next",
      "size": 18, "color": "#64748b", "containerId": 5 }
  ]
}

That example is worth reading twice: the two labels have no coordinates because containerId centres them in their box, and the arrow needs no elbow maths because startBinding/endBinding plus route let the renderer work out the path.

Every shape

Each entry needs a type. Coordinates are world pixels — y grows downwards, and there is no canvas size to stay inside.

Everything the canvas can do, and how to write it

Anything you can draw or set in the UI has a field here — with two exceptions noted below, the file is the complete picture. Working the other way, a few things are only reachable by writing the file.

What a scene file doesn’t hold

A .scritch file is the drawing, not the session. These live in your browser and are deliberately left out, so opening someone’s file can’t disturb your setup:

• Pan and zoom. Opening a file frames the drawing for you; load(scene, { fit: false }) leaves the view alone.
• Saved sketches and their names. Those are a browser-local library — a file is one drawing. Use the Sketches menu to name and keep it.
• Tool and panel state — the selected tool, snap-to-grid, canvas lock, and the styles queued up for the next shape you draw.
• Presentation mode and any laser marks made during it. Marks are never persisted at all.
• Undo history. Opening a file is itself one undoable step.

Sharing the whole thing instead? The share button packs the same shapes into a link, and the workspace backup in the top bar exports every sketch, snippet and setting at once.

What gets refused, and why

Import is strict on purpose, and it tells you what it did rather than failing silently. A shape is dropped if its type is unknown, its required geometry is missing, or it reuses an id. A field is stripped if it isn’t in this page or its value is the wrong type — so a typo means a missing colour, never an unnoticed one.

• Colours must match the notations above. A colour is written straight into an SVG attribute when you export, so free-form strings aren’t accepted.
• Images must be raster data URLs. An image/svg+xml data URL can carry script that would run when someone opens your exported SVG.
• A binding or containerId pointing at a shape that didn’t survive is cleared, so nothing dangles.
• Up to 5,000 shapes per file. A file claiming a version newer than 1 is refused rather than half-read.

Driving the canvas from code

While /scritch is open it exposes window.scritch. Everything goes through the same validation and the same canvas state as the UI — no storage key to guess at, and no reload.

// On /scritch, in the console or a Playwright script:
await new Promise((r) => (window.scritch ? r() : setTimeout(r, 100)));

window.scritch.load(scene);              // replace the canvas (undoable)
const png = await window.scritch.exportPng({ scale: 2 });
const svg = await window.scritch.exportSvg();

window.scritch.save();                   // -> a .scritch scene object
window.scritch.getShapes();              // -> the raw shapes array
window.scritch.bounds(3);                // -> a shape's box (or the scene's)
window.scritch.route(5);                 // -> an elbow route's points
window.scritch.clear();
window.scritch.fit();

load() takes a scene object, a bare shapes array, or the JSON text of either, and returns { ok, count, dropped, strippedFields } so you can see what it refused. Exports always frame the whole drawing, never the visible viewport — the scale option multiplies the bitmap, and is lowered automatically if the result would exceed what a browser canvas can hold.