Compiling

What runs before a reader sees anything: an attribute refined from the text it was written as, the semantic pass over the result, the manifest a plugin declares, and the service that compiles a document.

@internote/canvas-sdk@internote/canvas-sdk/compile36 exports

On this page

Compiling turns Chalk source into the document a host mounts. dotchalkService does the whole job: it compiles the source, refines the values the compiler left as text, and runs the semantic pass. It runs on the server only.

import { dotchalkService } from '@internote/canvas-sdk/compile';

const result = dotchalkService.compile(source);
if (!result.ok) throw new Error(result.error);

Register every environment the document uses before compiling. A compile with none registered throws.

An environment that invents a value type of its own parses it here. The compiler accepts the value as a string, and a refiner you register reads it afterwards. These helpers are the ones the built-in environments' refiners use:

splitTopLevelCommas, splitCoordinatePairs and splitInterval break a value into its parts.
referenceValue reads a #id or #id.member reference.
colourValue reads a colour.

runCanvasSemanticPass checks the rules that span a document, and returns SemanticDiagnostics: an error fails the compile, and a warning comes back with a successful one.

#Functions

buildCanvasElement

Builds a vocabulary element from values a reader supplied, for an environment that lets the reader add elements without a compiler in the loop.

Refines a paint attribute value, storing it in its canonical spelling or refusing it with a message listing the colours allowed.

A value as a fill style, or undefined where it names none.

formatSemanticDiagnostic

Formats a diagnostic as the one-line string the compile service reports, such as [semantic] Unknown environment 'plot' (notes.chalk:12).

Refines a heatmap, contour or choropleth colour: colourValue, but accepting only the plain hues and the hex(…) and rgb(…) literals.

parametisedCoordinateList

Refines a run of coordinate pairs such as (1, 2), (t, t^2), each half a number or an expression in parameters, into a coordinate list.

Refines a #id or #id.member reference written as text, such as #gdp.value inside a keyframe chain, into the binding object the renderer resolves.

refineCanvasAttr

Refines one attribute's text as its declared type, for a reader editing an element that was authored in chalk.

refineInternoteDocument

Refines a freshly compiled internote in place, re-parsing custom-typed attribute values into the shapes renderers read.

runCanvasSemanticPass

Checks a compiled, refined document against the canvas rules the library schema cannot express, and returns what it found.

splitCoordinatePairs

Splits a list of coordinates such as (1, 2), (t+1, 2t) into [x, y] text pairs, or returns an error if the brackets do not pair up.

Splits interval notation such as [0, 10] or [>0, <8] into its two ends and whether each is included, or returns why it could not.

splitTopLevelCommas

Splits a value at the commas that are not inside parentheses, so max(a, b), 3 gives two pieces.

A value as a stroke style, or undefined where it names none.

styleValueTypes

Returns what an environment's spec needs to declare its style attributes: their value types for the compiler.

validateCanvasManifest

Checks that a value is a well-formed plugin manifest, throwing with a message naming the first problem.

#Classes

DotchalkCompilationService

Compiles chalk source into an internote document, with the canvas environments' refinement and validation applied.

#Constants

How a shape is filled: flat; ruled with diagonal lines or stippled with dots, over a pale wash of its colour; or not at all, its edge alone.

Matches a node id as the compiler emits it: lower case, with dots, dashes and underscores allowed, and — for an id a @define template declares — the hygienic suffix ~<n> (D36).

Matches a bare numeric literal, which a refiner tests for before reaching for the expression parser.

RAMP_PAINT_TYPE

The type of one look of a ramping colour: a literal colour, or a ramp's name or a bare hue.

How a stroke is drawn: whole, in dashes, or in dots.

dotchalkService

A shared DotchalkCompilationService.

#Interfaces

BuiltElementError

Why buildCanvasElement could not build an element.

An element buildCanvasElement built.

CanvasPluginChalkSpec

The chalk a plugin adds: its environment name, and the attributes and vocabulary it declares.

CanvasPluginManifest

Describes a canvas-environment plugin, so a host can validate it before running any of its code.

An interval's two ends as written, and whether each one is in it.

SemanticDiagnostic

One problem the semantic pass found.

SemanticPassResult

Everything the semantic pass found, split by severity.

StyleAttributeSpec

One style attribute: the kind of look it gives each item, and the type of one look.

#Types

How a shape is filled.

RefineDocumentResult

The outcome of refineInternoteDocument: success, or the first refinement error as a message.

How a stroke is drawn.

The kinds of look a style attribute gives an item.

What a compile returns: the document and any warnings when ok is true, or an error message when it is false.

Last updated 26 September 2026