Data

The board produces two forms, for two different jobs.

Keep the JSON and the drawing can be reopened and edited. Keep only the SVG and it can only be displayed.

Reading out#

board.getDocument()       // → Envelope
board.getDocumentJSON()   // → string
board.toSVG(options)      // → string | null
board.toPNG(options)      // → Promise<Blob>
board.exportImage(format, options)   // → Promise<ExportPayload>

Envelope is an opaque object: { format, version, doc, view }. The structure inside doc is an internal detail and changes between versions — keep it intact, do not edit it by hand.

Typical sizes: 0.9 KB of JSON for a labelled triangle; 8 KB for a drawing of 70 objects. SVG runs about one and a half times the size of the JSON.

Writing in#

MathCanvas.init('#board', { document: envelope });
board.setDocument(envelope);

Accepts an Envelope, a bare Document ({ points, shapes }), or the JSON string of either.

Input is validated and sanitised before it is applied: broken or unrecognised objects are dropped and the rest is kept. Input that cannot be read at all leaves the state untouched and throws nothing.

MathCanvas.parseDocument(raw) applies the same rules without an instance and returns null when nothing can be recovered.

version is raised when the schema changes in a breaking way; older documents always open in a newer build.

Export options#

The frame hugs what is actually drawn — text included: point names, axis numbers, variation-table labels — plus padding on each side. The background grid and interaction overlays are excluded.

Empty drawing: toSVG() returns null; toPNG() and exportImage() reject with Error('Chưa có hình để xuất'). board.isEmpty() tells you in advance.

Handing images to the page#

By default the SVG and PNG buttons trigger a file download. With onExport, or exportMode: 'handoff', they switch to an upward arrow and call onExport once per press instead of downloading.

MathCanvas.init('#board', {
  exportLabels: { svg: 'Insert', png: 'Insert image' },
  onExport: (payload) => { /* … */ },
});

Exceptions thrown from onExport are caught and logged to the console.

Registering through the event requires turning the mode on explicitly:

const board = MathCanvas.init('#board', { exportMode: 'handoff' });
board.on('export', (payload) => { /* … */ });

Keeping the download behaviour despite onExport: { exportMode: 'download' }.

ExportPayload#

board.downloadSVG(name, options) / board.downloadPNG(name, options)#

What the SVG string contains#

Static SVG: geometry elements, <text> and presentation attributes. No <script>, no <foreignObject>, no on* attributes, no external references. Point and text labels are user-entered text, escaped during serialisation.

The bundle neither signs nor verifies the string once it leaves the browser.

Storing in the browser#

With storageKey, the board writes to localStorage 400 ms after each change. Off by default. board.clearStorage() removes that record.