# Apas Content (.apc) block reference

> Every block of an Apas Content (.apc) document, with its attributes and a live example: text, maths, scripts, plots, diagrams, questions, slides, notebooks and mindmaps.

This file is generated from the engine's own data: every example here is compiled by the engine before the file is published. The page with live examples is https://apasscript.com/docs/apc-blocks.html and the full function reference is https://apasscript.com/docs/.

An `.apc` file is a lesson, worksheet, question set, notebook or slide deck written as plain text. It is an ordered list of blocks. The same file is shown on the web and printed as a PDF.

## Rules every file follows

1. A file is a flat list of blocks from top to bottom. There is no `<page>`, `<section>`, `<html>` or `<body>` wrapper; those are errors.
2. Every line at the top level starts a block or belongs to one that is open. Prose goes in `<p>...</p>`. Markdown headings (`#`), bullets (`-`), numbered lines and code fences are not understood.
3. Put each block's tags on their own lines, as in the examples. An opening tag and its attributes stay on one line.
4. Only the tags on this page exist. An unknown tag is an error, not ignored.
5. Inline formatting is `**bold**`, `*italic*`, `$maths$` and code between backticks, each on one line.
6. Numbers are exact: `1/3` stays a fraction, `sqrt(2)` a surd. Ask for a decimal with `decimal(x)`.
7. A picture is written, not attached: a plot or diagram is a `<script>` block that ends with the graph or diagram.
8. Each `<script>` and `<code>` block runs on its own. `<calc>` and `<params>` names are shared by the whole page. In a notebook (`<cell>`) everything is shared.

## Text and structure

The blocks every lesson is made of. Headings give the document its outline; there is no page or section wrapper.

### `<h1> to <h6>`

A heading, level 1 to 6.

One line, with the closing tag on the same line. Inline maths and formatting work inside it. The first `<h1>` is the document title in a PDF.

```apc
<h1>Newton's second law</h1>
<h2>Force and acceleration</h2>
<h3>The case $F = m*a$</h3>
```

### `<p>`

A paragraph of prose with inline maths and formatting.

All prose goes inside `<p>...</p>`; a bare line of text is an error. A paragraph may run over several lines and ends at `</p>`.

Inline formatting: `**bold**`, `*italic*`, `$maths$`, and code between backticks. Each is a flat span on one line; they do not nest. Put a backslash before `$`, `*` or a backtick to get the character itself. An unclosed `$` or `*` is shown as plain text, never an error.

Write `<` and `>` as they are. Text is escaped when it is drawn, so HTML tags inside a paragraph are shown as text, not run.

```apc
<p>The net force is $F = m*a$, where $m$ is the **mass** and $a$ the *acceleration*.</p>
<p>Call `sqrt(2)` for a square root. A ticket costs \$5, and 3 < 5.</p>
```

### `<ul> and <ol>`

A bullet list or a numbered list.

Each item is one `<li>...</li>` on its own line, with the same inline maths and formatting as a paragraph. Items cannot hold other blocks and lists do not nest; for richer items use a heading or a callout.

```apc
<ul>
<li>The discriminant is $D = b^2 - 4*a*c$.</li>
<li>$D > 0$ gives two distinct real roots.</li>
</ul>
<ol>
<li>Compute $D$.</li>
<li>Apply the quadratic formula.</li>
</ol>
```

### `<table>`

A table written as rows of cells separated by |.

The first row is the header. Every row must have the same number of cells; the leading and trailing `|` are optional. A cell takes inline maths and formatting, including values computed in a `<calc>` block. There is no separator row of dashes.

```apc
<table>
| Quantity | Symbol | SI unit |
| Displacement | $s$ | m |
| Velocity | $v$ | m/s |
| Acceleration | $a$ | $\mathrm{m/s^2}$ |
</table>
```

### `<callout>`

A labelled box: definition, theorem, example, note, exercise, answer, or any other label.

One generic box. `type` is free text and becomes the label ("Definition.", "Worked example."), so a new kind of box needs no new tag. The body is any blocks: paragraphs, maths, tables, scripts, even another callout.

An exercise's answer is simply the next callout with `type="answer"`. Inside a `<slide>`, a callout with `type="speaker notes"` is shown only to the presenter.

Attributes:

- `type`: Free-text label, title-cased when shown. Optional.
- `cite`: Free-text source shown in brackets after the label, such as "JEE Main 2025". Optional.

```apc
<callout type="definition">
<p>**Momentum** is the product of mass and velocity:</p>
$$
p = m*v
$$
</callout>
<callout type="exercise" cite="JEE Main 2025">
<p>Solve $x^2 - 7x + 12 = 0$ by factorisation.</p>
</callout>
<callout type="answer">
<p>$(x-3)(x-4) = 0$, so $x = 3$ or $x = 4$.</p>
</callout>
```

## Mathematics

Maths is written either as a plain expression, the way a calculator or ApasScript takes it (`(a+b)/(c+d)`, `sqrt(x)`, `x^2`), or as LaTeX (`\frac{a}{b}`, `\vec{F}`, `\int_0^1`). Both work between dollar signs.

### `$...$`

Maths inside a line of text.

Allowed wherever text is: headings, paragraphs, list items, table cells, options, answers and hints. It stays on one line.

A plain expression is typeset for you: `(a+b)/2` becomes a fraction, `sqrt(x)` a root, `x^2` a power, `*` a product. So is an equation whose sides are plain expressions: `D = b^2 - 4*a*c`, `x^2 - 7*x + 12 = 0`.

Anything else is passed to the page as LaTeX, exactly as written: vectors, limits, integrals, Greek letters. If either side of an equation is LaTeX, the whole span is. Write a unit as `\mathrm{m/s^2}`, or it is read as m divided by s squared.

When a `<calc>` block has given a name a value, `$name$` shows the value (see `<calc>`).

```apc
<p>Plain: $(a+b)/(c+d)$, $sqrt(x^2 + 1)$, $3*x^2 - 2*x + 1$, $x^2 - 7*x + 12 = 0$.</p>
<p>LaTeX: $\vec{F} = m\vec{a}$, $\int_0^1 x^2\,dx = \frac{1}{3}$, $v = 12\,\mathrm{m/s}$.</p>
```

### `$$ ... $$`

Display maths: one equation per line, aligned on the equals sign.

A line holding only `$$` opens the block and another closes it. With several lines, each is split on its first `=` and the equals signs line up.

`$$align` instead takes the alignment point from an `&` you place yourself, as LaTeX's `align` does. Use it when a line has no `=`, or when the alignment is not at the first one.

Aligned on =:

```apc
$$
2*x + 3 = 7
2*x = 4
x = 2
$$
```

Explicit alignment with &:

```apc
$$align
(x+1)^2 &= x^2 + 2*x + 1
&= x*(x + 2) + 1
$$
```

### `<calc>`

Silent calculation: computes values and shows nothing; later text can quote them.

The body is ApasScript, one `name = expression` per line. Nothing is displayed. After it, `$name$` anywhere on the page shows the computed value, and an expression such as `$2*D$` is worked out from it. All `<calc>` blocks on a page share one set of names.

Values are exact: `1/3` stays a fraction and `sqrt(8)` becomes `2sqrt(2)`. Use `$decimal(x)$` to show a decimal.

A span containing `=` is always shown as a formula and never assigns. Keep calculated names different from letters you use purely as symbols on the same page, or the symbol will be replaced by the value.

```apc
<calc>
mass = 12
acc = 3/2
force = mass*acc
</calc>
<p>A body of mass $mass$ kg accelerating at $acc$ $\mathrm{m/s^2}$ needs a force of $force$ N, which is $decimal(force/1000)$ kN.</p>
<table>
| Quantity | Value |
| Mass | $mass$ kg |
| Force | $force$ N |
</table>
```

### `<formula>`

One formula of a chapter: checked by the engine, shown with its symbols.

The first line is the formula, written as `solve` takes it (`V = I*R`, `1/f = 1/v - 1/u`). Each line after it describes one symbol as `name: meaning | unit`; leave the unit out for a pure number. An optional `applies:` line says when the formula holds. `id`, `topic` and `name` on the tag identify it.

The block is checked where it is compiled: every name in the formula must be described, and with the units given, both sides must come to the same unit. A formula that fails says what is wrong in its place.

Follow it with a worked example for the reader: a `<callout type="example">` holding the problem in words, its given values as quantities in `<calc>`, and the working in `<steps>`. A student then reads the formula, the values put in with their units and the answer, and never a script.

```apc
<formula id="ohms-law" topic="ohms_law" name="Ohm's law">
V = I*R
V: potential difference | V
I: current | A
R: resistance | ohm
applies: a conductor at constant temperature
</formula>
<callout type="example">
<p>A potential difference of 12 V is applied across a resistance of 4 ohm. Find the current.</p>
<calc>
V = quantity(12, "V")
R = quantity(4, "ohm")
</calc>
<steps>
I = solve(V = I*R, I)
</steps>
</callout>
```

## Scripts and code

Three ways to put ApasScript on a page. `<script>` shows working and pictures; `<code>` shows a listing and its output; `<calc>` (above) computes silently.

### `<script>`

Runs ApasScript and shows each line's result: worked calculations, plots and diagrams.

The body is ApasScript source, exactly as in the playground. Each line shows `name = value` typeset as maths; a line starting with `#` is prose. A plot or diagram value is drawn as a picture.

Wrap setup lines in `quiet { ... }` so only the last line is shown; this is the normal shape for a picture (see Plots and Diagrams below).

Each `<script>` runs on its own: names from one script are not visible in the next, nor in `<calc>`. In a notebook (a document made of `<cell>` blocks) all scripts share their names.

Worked calculation:

```apc
<script>
# Roots of the quadratic
a = 1
b = -7
c = 12
D = b^2 - 4*a*c
x1 = (-b + sqrt(D))/(2*a)
x2 = (-b - sqrt(D))/(2*a)
</script>
```

In a PDF: Calculation lines become aligned equations; plots and diagrams are drawn as vector figures (the final state only). Flowcharts, 3D surfaces and animations have no PDF form.

### `<code>`

A code listing. ApasScript listings are also run and their output is shown.

Use it to teach the code itself. With no `lang`, or `lang="as"`, the listing is run and its real output is printed under it, so the output is never typed by hand. Any other `lang` (Python, C, ...) is shown as a listing only.

Attributes:

- `lang`: "as" (the default) runs the listing. Any other language name shows it without running.

ApasScript: listing and output:

```apc
<code>
solve(x^2 + 6*x + 5 = 0, x)
</code>
```

Another language, with typed output:

```apc
<code lang="python">
for i in range(3):
    print(i * i)
</code>
<output>
0
1
4
</output>
```

### `<output>`

Typed output shown verbatim, to pair with a listing in another language.

Never run or checked: what is written is what shows. An ApasScript `<code>` block makes its own output and does not need this.

```apc
<output>
Enter a number: 7
7 is prime
</output>
```

### `<pseudocode>`

Textbook pseudocode, shown as a numbered listing and a flowchart.

Never run. Only each line's leading keyword and its indentation matter: `if` / `else if` / `else`, `while`, `for`, `repeat ... until`, `do ... while`, `return`, `break`, `continue`, and an optional `algorithm` or `procedure` header on the first line. The rest of the line is free text.

A block that does not fit together (an `else` with no `if`, an `until` with no `repeat`) is an error, not a wrong chart.

Attributes:

- `title`: Shown above the listing. Optional.

```apc
<pseudocode title="Largest of three numbers">
algorithm Largest(a, b, c)
  max ← a
  if b > max
    max ← b
  if c > max
    max ← c
  return max
</pseudocode>
```

In a PDF: The numbered listing only; the flowchart is a web feature.

## Plots

A plot is a `<script>` block whose last line is a graph. Build the graph inside `quiet { ... }`, then name it on the last line so only the picture shows.

`graph()` fits its axes to the data; `graph(xmin, xmax, ymin, ymax)` fixes them. Colours are CSS names or hex. Line styles are `"solid"`, `"dashed"` and `"dotted"`. The full list of functions is on the Plotting page.

### Function plot

One or more curves y = f(x) with a legend.

`plot(g, "expression in x", xmin, xmax, colour, style, label)`. The expression is quoted. Add a line per curve.

```apc
<script>
quiet {
g = graph()
plot(g, "sin(x)", 0, 2*pi, "tomato", "solid", "sin x")
plot(g, "cos(x)", 0, 2*pi, "steelblue", "dashed", "cos x")
title(g, "Sine and cosine")
xticks(g, 1)
}
g
</script>
```

### Data: line, scatter and area

Measured values held in arrays.

`plot(g, xs, ys, ...)` joins the points; `scatter(g, xs, ys, colour, label)` shows them as dots; `area(g, xs, ys)` fills down to the axis. With one array, x counts 1, 2, 3, ...

```apc
<script>
quiet {
t = [0, 1, 2, 3, 4, 5]
v = [0, 9.8, 19.6, 29.4, 39.2, 49]
g = graph()
plot(g, t, v, "steelblue", "solid", "v = 9.8 t")
scatter(g, t, v, "tomato", "readings")
title(g, "Speed of a falling body")
}
g
</script>
```

### Bar chart, pie chart and histogram

Counts by category, parts of a whole, or raw data sorted into bins.

`bar(g, xs, ys, colour, label)` draws one bar per value. With names for xs, `bar(g, ["Mon", "Tue"], ys)`, each bar is named on the axis; `stacked(g)` stands several bar series on one another.

`pie(g, names, values)` draws parts of a whole with each name, value and share beside it; a fourth argument such as `0.6` leaves a hole, which makes a ring.

`histogram(g, data, bins)` bins raw data itself. `graph(w, h)` sets the size of any of them in pixels.

Bar chart:

```apc
<script>
quiet {
g = graph()
bar(g, [1, 2, 3, 4, 5], [4, 9, 2, 7, 5], "goldenrod", "Students")
title(g, "Marks out of 5")
}
g
</script>
```

Named bars, stacked:

```apc
<script>
quiet {
g = graph(560, 300)
days = ["Mon", "Tue", "Wed", "Thu", "Fri"]
bar(g, days, [2, 4, 1, 3, 2], "#3987e5", "Lessons read")
bar(g, days, [1, 2, 3, 0, 4], "#d95926", "Questions answered")
stacked(g)
}
g
</script>
```

Pie chart:

```apc
<script>
quiet {
p = graph(460, 260)
pie(p, ["Physics", "Chemistry", "Mathematics", "Biology"], [40, 25, 20, 15])
title(p, "Questions by subject")
}
p
</script>
```

Ring:

```apc
<script>
quiet {
p = graph(460, 240)
pie(p, ["Correct at the first try", "Correct after another try", "Not correct yet"], [15, 3, 4], 0.6)
}
p
</script>
```

Histogram:

```apc
<script>
quiet {
heights = [150, 152, 155, 155, 158, 160, 160, 161, 163, 165, 165, 166, 170, 172, 178]
g = graph()
histogram(g, heights, 6)
title(g, "Heights in a class (cm)")
}
g
</script>
```

### Parametric and polar curves

Curves given by x(t), y(t) or by r(theta).

`plotParametric(g, "x(t)", "y(t)", tmin, tmax, ...)` and `plotPolar(g, "r(theta)", thetaMin, thetaMax, ...)`. `aspect(g, true)` gives both axes the same scale, so a circle looks like a circle.

`tracePlot(g, seconds)` makes every curve of the graph draw itself in over that many seconds, a function from left to right, a parametric or polar curve in the order of its parameter. It works for `plot`, `plotParametric` and `plotPolar` alike; in a PDF the finished curves are shown. In one line: `tracePlot(g, "sin(x)", 0, 2*pi, 4)`, `tracePolar(g, "1 + cos(theta)", 0, 2*pi, 4)` and `traceParametric(g, "3*cos(t)", "2*sin(t)", 0, 2*pi, 4)` plot the curve and trace it, with the colour, line type and label after the seconds.

```apc
<script>
quiet {
g = graph()
plotParametric(g, "3*cos(t)", "2*sin(t)", 0, 2*pi, "steelblue", "solid", "ellipse")
plotPolar(g, "1 + cos(theta)", 0, 2*pi, "tomato", "solid", "cardioid")
aspect(g, true)
}
g
</script>
```

### Logarithmic axis

Growth and decay over many powers of ten.

`logScale(g, "x")`, `logScale(g, "y")` or `logScale(g, "both")`.

```apc
<script>
quiet {
n = [1, 2, 3, 4, 5, 6, 7, 8]
cells = [2, 4, 8, 16, 32, 64, 128, 256]
g = graph()
plot(g, n, cells, "seagreen", "solid", "cells")
logScale(g, "y")
title(g, "Doubling every generation")
}
g
</script>
```

## Diagrams

A diagram is a `<script>` block whose last line is a diagram. Create it with `d = diagram(width, height)`, set `xrangeOn` and `yrangeOn`, draw into it with the functions ending in `On`, and put `d` on the last line.

Coordinates are ordinary x, y units inside the ranges you set. Angles are in degrees, counter-clockwise from the positive x-axis. Styles come after the geometry, in order: colour, label, then a fill colour (shapes) or arrows (`"one"`, `"two"`, `"none"`). Leave a label as `""` and place it yourself with `textOn` when its position matters. `textOn(d, point, "text")` starts the text at the point and runs to the right; text is 14 px high whatever the ranges are, so leave room for it. To centre text on a point (a name inside a box, a tick value under an axis, a charge sign) write `labelAtOn(d, point, "text", "center")`: with `textOn` the same coordinates put the text to the right of the point and above it, on top of whatever is there. `labelAtOn(d, point, "text", side)` puts a label beside a point instead (`"above"`, `"below"`, `"left"`, `"right"`), clear of what is drawn there. Every function is listed on the Diagrams page.

A diagram is drawn on a white surface, on the web and in a PDF. A shape, label or text with no colour of its own is drawn in dark ink; give it a colour to make it stand out.

### Points, segments and circles

The basic shapes and how a diagram is set up.

`drawOn(d, shape, colour, label, fill)` draws a `point`, `circle`, `ellipse` or `line`. `drawOn(d, pointA, pointB, ...)` draws the segment between two points. Turn the axes and grid off for a geometry figure.

```apc
<script>
quiet {
d = diagram(480, 360)
xrangeOn(d, -4, 4)
yrangeOn(d, -3, 3)
axesOn(d, false)
gridOn(d, false)
O = point(0, 0)
P = point(2, 0)
drawOn(d, circle(O, 2), "steelblue", "", withAlpha("steelblue", 0.15))
drawOn(d, O, P, "tomato", "r = 2")
drawOn(d, O, "black", "O")
drawOn(d, P, "black", "P")
}
d
</script>
```

### Triangles and angle markers

A polygon with its sides and angles labelled.

`polygonOn(d, A, B, C, colour, label, fill)` takes any number of corners. `angleMarkerOn(d, vertex, pointOnRay1, pointOnRay2, radius, label, colour)` draws the arc and its label; `rightAngleMarkerOn(d, vertex, pointOnRay1, pointOnRay2, size, label, colour)` draws the square. Neither needs you to work out an angle.

```apc
<script>
quiet {
d = diagram(480, 380)
xrangeOn(d, -1, 6)
yrangeOn(d, -1, 5)
axesOn(d, false)
gridOn(d, false)
A = point(0, 0)
B = point(5, 0)
C = point(0, 4)
polygonOn(d, A, B, C, "steelblue", "", withAlpha("steelblue", 0.15))
rightAngleMarkerOn(d, A, B, C, 0.4, "", "black")
angleMarkerOn(d, B, C, A, 0.9, "θ", "tomato")
textOn(d, point(2.5, -0.4), "5 cm", "black")
textOn(d, point(-0.7, 2), "4 cm", "black")
textOn(d, point(-0.3, -0.3), "A", "black")
textOn(d, point(5.3, -0.3), "B", "black")
textOn(d, point(-0.3, 4.3), "C", "black")
}
d
</script>
```

### Vectors and force diagrams

Arrows from a point, by components or by length and angle.

`drawOn(d, point, vec(dx, dy), colour, label, arrows)` draws an arrow by its components. `vectorFromOn(d, point, length, degrees, colour, label)` draws one by length and direction, and `segmentFromOn` the same without an arrowhead.

`drawOn(d, p1, p2, colour, label)` with two points draws a plain line between them, with no arrowhead: a wire, a side, a plate, a ray path. For an arrow from `p1` to `p2`, add `"one"` after the label; `"two"` puts a head at both ends (a dimension line).

Free-body diagram:

```apc
<script>
quiet {
d = diagram(480, 380)
xrangeOn(d, -4, 4)
yrangeOn(d, -4, 4)
axesOn(d, false)
gridOn(d, false)
c = point(0, 0)
polygonOn(d, point(-1, -0.6), point(1, -0.6), point(1, 0.6), point(-1, 0.6),
  "gray", "", withAlpha("gray", 0.3))
vectorFromOn(d, c, 3, 90, "seagreen", "N")
vectorFromOn(d, c, 3, 270, "tomato", "mg")
vectorFromOn(d, c, 2.5, 0, "steelblue", "F")
vectorFromOn(d, c, 1.5, 180, "darkgoldenrod", "f")
}
d
</script>
```

### Curves, arcs and text

Smooth paths between points, circular arcs and free labels.

`curveBetweenOn(d, a, b, bend, colour, label, style, width)` bends a line between two points; `bend` is signed, and 0 is straight. `curveOn(d, p0, control, p1)` is a Bezier curve. `arcAtOn(d, centre, radius, startDegrees, sweepDegrees, colour)` is part of a circle. `textOn(d, point, "text", colour, fontSize)` places a label.

```apc
<script>
quiet {
d = diagram(480, 320)
xrangeOn(d, -1, 7)
yrangeOn(d, -1, 4)
axesOn(d, false)
gridOn(d, false)
A = point(0, 0)
B = point(6, 0)
drawOn(d, A, B, "gray", "")
curveBetweenOn(d, A, B, -0.45, "tomato", "", "dashed", 2)
arcAtOn(d, A, 1.2, 0, 60, "darkgoldenrod")
textOn(d, point(1.5, 0.7), "60°", "darkgoldenrod", 14)
textOn(d, point(3, 3.1), "path of the ball", "tomato", 14)
}
d
</script>
```

### A graph of a function inside a diagram

For a coordinate-geometry figure: axes, a line or curve, and marked points.

Leave the axes and grid on. A `line` is drawn across the whole diagram; a parabola or other curve is a `plot` on a `graph()` (see Plots), which can sit next to a diagram in the same document.

```apc
<script>
quiet {
d = diagram(480, 400)
xrangeOn(d, -5, 5)
yrangeOn(d, -5, 5)
A = point(-2, -3)
B = point(3, 2)
drawOn(d, line(A, B), "steelblue", "y = x - 1")
drawOn(d, A, "tomato", "A(-2, -3)")
drawOn(d, B, "tomato", "B(3, 2)")
drawOn(d, circle(point(0, 0), 3), "seagreen", "x² + y² = 9")
}
d
</script>
```

### Solids

Textbook cubes, prisms, cylinders and spheres, with marked corners and edges.

`cubeOn(d, origin, size, dx, dy, colour)` draws a cube in a slanted view; `dx`, `dy` is the offset of the back face. It returns a record whose `vertices` are the exact corner points, so markers and labels attach to the figure. `prismOn`, `cylinderOn` and `sphereOn` work the same way.

`cornerMarkerOn(d, point, label, colour)` puts a labelled dot on a corner; `edgeMarkerOn(d, a, b, fraction, label, colour)` puts one part-way along an edge.

```apc
<script>
quiet {
d = diagram(480, 380)
xrangeOn(d, -1, 5)
yrangeOn(d, -1, 4.5)
axesOn(d, false)
gridOn(d, false)
s = cubeOn(d, point(0, 0), 3, 1, 1, "steelblue")
cornerMarkerOn(d, s.vertices[0], "A", "tomato")
edgeMarkerOn(d, s.vertices[0], s.vertices[1], 1/2, "M", "darkgoldenrod")
}
d
</script>
```

### Springs, coils and fields

Ready-made physics shapes and field pictures.

`springOn(d, start, end, amplitude, turns, colour)`, `coilOn` and `inductorOn` draw between two attachment points. `vectorFieldOn(d, "Fx", "Fy", xmin, xmax, ymin, ymax, nx, ny, mode, scale, colour)` draws a grid of arrows; the mode is `"direction"`, `"scaled"` or `"capped"`. `pointChargeLinesOn(d, centre, charge, lineCount, xmin, xmax, ymin, ymax)` draws the field lines of one charge, and `fieldLineOn` traces one line of any field.

Spring and mass:

```apc
<script>
quiet {
d = diagram(520, 260)
xrangeOn(d, -1, 8)
yrangeOn(d, -2, 2)
axesOn(d, false)
gridOn(d, false)
drawOn(d, point(0, -1.5), point(0, 1.5), "gray", "")
springOn(d, point(0, 0), point(5, 0), 0.4, 8, "steelblue")
polygonOn(d, point(5, -0.7), point(6.4, -0.7), point(6.4, 0.7), point(5, 0.7),
  "tomato", "", withAlpha("tomato", 0.3))
textOn(d, point(5.7, 0), "m", "black")
textOn(d, point(2.5, 0.9), "k", "black")
}
d
</script>
```

Field of a positive charge:

```apc
<script>
quiet {
d = diagram(420, 420)
xrangeOn(d, -3, 3)
yrangeOn(d, -3, 3)
axesOn(d, false)
gridOn(d, false)
pointChargeLinesOn(d, point(0, 0), 1, 12, -3, 3, -3, 3)
}
d
</script>
```

### Circuits

Resistors, cells, meters and the other circuit symbols, one call each.

Name the corners of the circuit as points, then put one component on each branch: `resistorOn(d, a, b, label)`, `cellOn`, `batteryOn(d, a, b, cells, label)`, `capacitorOn`, `bulbOn`, `variableResistorOn`, `inductorOn(d, a, b, label)`, `acSourceOn`, `diodeOn` and `zenerDiodeOn` (the triangle points from `a` to `b`), `meterOn(d, a, b, "A", label)` and `switchKeyOn(d, a, b, "open", label)`. Each draws its symbol in the middle of the branch and the lead wires out to both points, so do not draw the zigzag or the leads yourself. A cell's positive (long) plate faces its second point.

The label is an argument, not a separate `textOn`: the engine puts it beside the symbol and clear of it, outside the circuit by default. Add a side (`"above"`, `"below"`, `"left"`, `"right"`) after the label to choose. `wireOn(d, p1, p2, p3)` joins the remaining corners, `junctionOn(d, p, "A")` marks and names a node, `currentArrowOn(d, a, b, "I")` shows a current on a wire, `terminalOn(d, p, "A")` ends a wire in an open ring, `groundOn(d, p)` earths a point and `labelAtOn(d, p, "+", "left")` writes beside a point.

Three symbols take more than two points. `transistorOn(d, base, collector, emitter, "npn", label)` draws the transistor and its three leads: put the collector and emitter one above the other and the base to one side, level with their middle. `gateOn(d, "nand", inputA, inputB, output, label)` draws a logic gate (`"and"`, `"or"`, `"not"` with one input, `"nand"`, `"nor"`, `"xor"`, `"xnor"`) with its leads; give one gate's output point as the next gate's input to connect them. `twoWaySwitchOn(d, pivot, contactA, contactB, "a", label)` draws a switch thrown to contact `"a"` or `"b"`, or `"open"`.

Symbols have a fixed size on the page, so set `xrangeOn` and `yrangeOn` first, and choose ranges that give each branch about 80 px or more: at least 2 units when the diagram shows 40 px per unit.

Two resistors in parallel, with an ammeter:

```apc
<script>
quiet {
d = diagram(420, 300)
xrangeOn(d, -1.5, 7.5)
yrangeOn(d, -1.2, 4.2)
axesOn(d, false)
gridOn(d, false)
A = point(0, 3)
B = point(3, 3)
C = point(6, 3)
D = point(6, 0)
E = point(3, 0)
F = point(0, 0)
cellOn(d, F, A, "12 V")
resistorOn(d, A, B, "4 Ω")
meterOn(d, B, C, "A")
resistorOn(d, C, D, "6 Ω")
resistorOn(d, B, E, "3 Ω", "right")
switchKeyOn(d, E, D, "closed", "K")
wireOn(d, E, F)
junctionOn(d, B, "P")
junctionOn(d, E, "Q")
}
d
</script>
```

### Sliders and animation

A picture the reader can change, or one that moves.

`slider(label, min, max, step, start)` gives a value the reader can drag; the script runs again with the new value. `animate(tmin, tmax, frames, f)` calls your function `f(t)` once per frame; each call draws one frame with the functions that have no `On` (`draw`, `text`, `vectorFrom`, ...).

Slider:

```apc
<script>
n = slider("sides", 3, 12, 1, 6)
regularPolygon(point(0, 0), 3, n, 90, "teal", "", withAlpha("teal", 0.3))
</script>
```

Animation:

```apc
<script>
quiet {
xrange(-5, 5)
yrange(-5, 5)
}
fn frame(t) {
  draw(circle(point(0, 0), 4), "gray")
  draw(point(4*cos(t), 4*sin(t)), "tomato", "P")
}
animate(0, 2*pi, 60, frame)
</script>
```

In a PDF: A slider shows its starting value. An animation has no PDF form.

### 3D surfaces

A surface z = f(x, y) the reader can turn.

`surf("expression in x and y", xmin, xmax, ymin, ymax)` draws a shaded surface; `mesh` a wireframe; `surfc` adds contour lines on the floor.

```apc
<script>
surf("sin(sqrt(x^2 + y^2))", -5, 5, -5, 5)
</script>
```

In a PDF: None. Export a PNG from the web page and include it with `<image>`.

## Images, audio and video

Files that already exist. The path or address may be written between the tags or as a `src` attribute; use one form consistently.

### `<image>`

A picture from a file or web address.

Use it for photographs, scans and drawings made elsewhere. A diagram you can describe is better written as a `<script>` diagram: it stays sharp, editable and exact.

```apc
<image>diagrams/pulley.png</image>
<image src="https://example.com/figures/cell.png">
```

### `<audio>`

An audio player.

Nothing is downloaded until the reader presses play.

```apc
<audio src="https://example.com/lesson/pronunciation.mp3">
```

In a PDF: A link to the file.

### `<video>`

A video player.

Nothing is downloaded until the reader presses play.

```apc
<video src="https://example.com/lesson/demo.mp4">
```

In a PDF: A link to the file.

## Questions

An assessment item the reader can answer on the page, and that prints as a question with its key.

### `<question>`

A question with options, answer, hint and solution.

The prompt is ordinary blocks (paragraphs, maths, tables, a diagram script). Then, each on its own line: `<option label="A">...</option>` for every choice, `<answer>...</answer>`, `<hint>...</hint>`, and a `<solution>` holding blocks. Answer, hint and solution are optional; leave them out to hide them.

Without `format`, it is worked out: options with one answer give `single_correct`, several answer labels (`A, C`) give `multiple_correct`; with no options a whole number gives `integer`, a decimal or fraction `numerical`, anything else `subjective`. Two options that come out equal are reported as an error.

Attributes:

- `id`: A stable name for the question. Optional but recommended.
- `format`: single_correct, multiple_correct, integer, numerical, true_false, assertion_reason, matrix_match, subjective. Optional; inferred when left out.
- `marks`: Marks for a correct answer. Optional.
- `shuffle`: A bare flag: the option texts are put in a random order and the answer follows them.
- `template`: A bare flag marking a question whose numbers are drawn at random (see `<params>`).

Single correct:

```apc
<question id="satellite-energy" format="single_correct" marks="4">
<p>For a satellite in a circular orbit, the ratio $KE/abs(PE)$ is:</p>
<option label="A">$1/2$</option>
<option label="B">$1$</option>
<option label="C">$2$</option>
<option label="D">$4$</option>
<answer>A</answer>
<hint>For a circular orbit, $PE = -2*KE$.</hint>
<solution>
<p>Since the size of $PE$ is twice $KE$, the ratio is $1/2$.</p>
</solution>
</question>
```

Integer answer, format inferred:

```apc
<question id="carbon-electrons" marks="2">
<p>How many electrons does a neutral carbon atom have?</p>
<answer>6</answer>
<solution>
<p>The atomic number of carbon is 6, so a neutral atom has 6 electrons.</p>
</solution>
</question>
```

### `<ordering>`

Arrange items in the correct order.

Each <item> holds one piece to order.

```apc
<ordering title="Steps">
<item>First</item>
<item>Second</item>
</ordering>
```

### `<params> and <steps>`

A question template: numbers drawn at random, with working that follows them.

`<params>` is ApasScript that draws the values: `randInt(lo, hi)` for a whole number, `randDecimal(lo, hi, step)` for an exact decimal on a grid, `choose([...])` for one item of a list. `require(condition)` lines make it draw again until they hold. It shows nothing and its names are visible on the whole page, like `<calc>`.

`<steps>` holds one `name = expression` per line, optionally followed by `| unit`. Each line prints the formula, then the formula with the values put in, then the result. `<steps decimal>` writes decimals instead of fractions.

A value in the working may be a quantity (`u = quantity(10, "m/s")` in `<params>` or `<calc>`): the line with the values put in then shows each with its unit, and the answer has the unit the engine arrives at. `| unit` after such a step gives the answer in that unit (`| km/h`). A step that is a `solve(...)` call is shown as the equation it solves. A `//` comment at the end of a step is not shown.

The page always uses the same numbers unless a seed is given, so a worksheet and its answer key agree.

```apc
<question id="car-accel" format="numerical" template>
<params>
u = randInt(10, 30)
a = randInt(2, 5)
t = randInt(2, 6)
require(u + a*t < 60)
</params>
<p>A car moving at $u$ m/s accelerates at $a$ $\mathrm{m/s^2}$ for $t$ s. Find its final speed.</p>
<answer>$v$ m/s</answer>
<solution>
<steps>
v = u + a*t | m/s
</steps>
</solution>
</question>
```

## Slides, notebooks and mindmaps

Three blocks that change what the whole document is.

### `<sequence>`

A timed sequence of content frames.

Each <frame> contains ordinary content blocks and an optional duration in milliseconds.

```apc
<sequence title="Steps">
<frame duration="1000">
<p>First</p>
</frame>
<frame duration="1000">
<p>Second</p>
</frame>
</sequence>
```

### `<slide>`

One slide of a presentation.

A presentation is a list of `<slide>` blocks at the top level; everything else goes inside a slide. A heading inside a slide does not start a new one. Slides cannot be nested.

A callout with `type="speaker notes"` is shown to the presenter only.

Attributes:

- `id`: A stable name for the slide. Optional.
- `title`: The slide title; takes inline maths and formatting. Optional. Write `&quot;` for a quotation mark inside it.

```apc
<slide id="second-law" title="Newton's second law">
<p>For a constant mass:</p>
$$
F = m*a
$$
<callout type="speaker notes">
<p>Ask what happens when the mass doubles.</p>
</callout>
</slide>
<slide id="your-turn" title="Your turn">
<question>
<p>A 2 kg body accelerates at $3\,\mathrm{m/s^2}$. Find the force in newtons.</p>
<answer>6</answer>
</question>
</slide>
```

### `<cell>`

One cell of a notebook.

A document containing any `<cell>` is a notebook. Text and question cells hold ordinary blocks; a code cell's body is ApasScript. All code in a notebook shares its names, top to bottom, so a later cell and later `$x$` maths can use an earlier value. Cells cannot be nested.

The cell tags stand on their own lines. Each `id` must be unique in the document.

Attributes:

- `id`: Required and unique.
- `type`: text (the default), code or question.

```apc
<cell id="intro" type="text">
<h2>Kinetic energy</h2>
<p>We compute $E = m*v^2/2$ for a 3 kg body at 4 m/s.</p>
</cell>
<cell id="work" type="code">
m = 3
v = 4
E = m*v^2/2
</cell>
<cell id="result" type="text">
<p>The energy is $E$ J.</p>
</cell>
```

### `<mindmap>`

A mindmap, concept map or pathway: nodes joined by branches and arrows.

`<node id="...">text</node>` makes a node; the text takes inline maths and formatting. Place a node with `x` and `y`, or relative to another with `parent` plus `direction` (`left`, `right`, `up`, `down`) or `angle` in degrees, and `distance`. A node with a parent gets a branch to it automatically.

`<connect from="a" to="b" .../>` adds a connection. `path` is `straight` or `curved` (with `bend`), `arrow` is `none`, `start`, `middle`, `end`, `both` or a percentage, `label` is text on the line, `line-type` is `solid`, `dashed` or `dotted`. Every opening tag stays on one line.

Node shapes: `rounded` (default), `rectangle`, `circle`, `ellipse`, `diamond`, `text`. `color` sets the outline and `fill` the background.

Attributes:

- `id`: A name for the map. Optional.

```apc
<mindmap id="states">
<node id="matter" x="0" y="0">States of matter</node>
<node id="solid" parent="matter" direction="left" distance="260" shape="rectangle">Solid</node>
<node id="liquid" parent="matter" direction="down" distance="170" shape="ellipse">Liquid</node>
<node id="gas" parent="matter" direction="right" distance="260" shape="circle">Gas</node>
<connect from="solid" to="liquid" path="curved" bend="-0.3" arrow="end" label="melting"/>
<connect from="liquid" to="gas" path="curved" bend="-0.3" arrow="end" label="boiling"/>
</mindmap>
```

## Agent and application blocks

Compact result cards for AI agents and applications: status, numbers, sources, data, files and approvals. They are drawn on the web only and left out of a PDF. Quote an attribute value that contains spaces. Rows use `|` between cells, as in `<table>`.

### `<tool>`

The status of a step an agent ran.

The body is plain text.

Attributes:

- `name`: What the step was.
- `state`: running, complete, failed or approval_required.

```apc
<tool name="Analyse dataset" state="complete">
Read 1,240 sales rows.
</tool>
```

### `<risk>`

A notice the reader should see before relying on the result.

The body is plain text.

Attributes:

- `level`: info, warning or danger.
- `title`: The notice's heading.

```apc
<risk level="warning" title="Educational analysis only">
This is general information, not investment advice.
</risk>
```

### `<metrics>`

A row of headline numbers.

Holds one `<metric>` line per number. Each takes `label`, `value`, and optionally `change` and `tone` (`positive` or `negative`).

Attributes:

- `title`: Heading for the group. Optional.

```apc
<metrics title="Campaign performance">
<metric label="Reach" value="40.5K" change="+12.4%" tone="positive">
<metric label="Conversions" value="1,284" change="-3.1%" tone="negative">
</metrics>
```

### `<sources>`

A list of the sources behind a result.

Holds one `<source>` line per source, with optional `title`, `url`, `publisher`, `published_at` and `retrieved_at`.

Attributes:

- `title`: Heading for the list. Optional.

```apc
<sources title="Data sources">
<source title="Quarterly report" url="https://example.com/report" publisher="Example Company" retrieved_at="Retrieved today">
</sources>
```

### `<actions>`

Buttons the host application handles.

Holds one `<action>` line per button, with `id`, `label` and the bare flags `primary` and `disabled`. The page passes the `id` to the application; the document itself does nothing.

Attributes:

- `title`: Heading for the group. Optional.

```apc
<actions title="Next steps">
<action id="download_png" label="Download PNG" primary>
<action id="copy_chart" label="Copy chart">
</actions>
```

### `<dataset>`

A preview of an uploaded or loaded dataset.

`<column name="..." type="...">` lines declare the columns, then one `<row>...</row>` per record with its cells in the same order.

Attributes:

- `name`: The dataset's name.
- `sheet`: Sheet or table name. Optional.
- `rows`: Total number of rows in the full dataset.
- `preview_limit`: How many rows to show.

```apc
<dataset name="Q3 Sales" sheet="Revenue" rows="1240" preview_limit="8">
<column name="month" type="date">
<column name="region" type="string">
<column name="revenue" type="number">
<row>2026-07-01 | North | 42000</row>
<row>2026-08-01 | West | 38900</row>
</dataset>
```

### `<data>`

A paged data table with typed columns.

Like `<dataset>`: `<column>` lines (with `name`, an optional display `label` and `type`), then `<row>` lines. Use `<table>` for a table in a lesson; use this for records an application shows.

Attributes:

- `title`: Heading for the table.
- `page_size`: Rows per page.

```apc
<data title="Monthly revenue" page_size="3">
<column name="month" label="Month">
<column name="revenue" label="Revenue" type="number">
<row>Jan | 42000</row>
<row>Feb | 38900</row>
</data>
```

### `<file>`

A card for a file the reader can download.

A single opening tag with no closing tag.

Attributes:

- `title`: Card heading.
- `name`: File name.
- `type`: Kind of file, such as PDF.
- `size`: Size as text.
- `description`: One line about the file.
- `url`: Where to download it.
- `link_label`: Text of the link.

```apc
<file title="Generated report" name="q3-summary.pdf" type="PDF" size="1.8 MB" description="Generated from Q3 campaign data" url="https://example.com/q3-summary.pdf" link_label="Download">
```

### `<social>`

A draft social-media post.

The body is the post text, followed by any number of one-line `<tag>...</tag>` hashtags.

Attributes:

- `platform`: Where it will be posted.
- `image_url`: Picture shown with the post. Optional.
- `image_alt`: Description of the picture. Optional.

```apc
<social platform="LinkedIn">
Our Q3 campaign reached 40.5K people.
<tag>MarketingAnalytics</tag>
<tag>Growth</tag>
</social>
```

### `<approval>`

A request for the reader's go-ahead before something is published.

The body is the summary, followed by `<action>` lines for the choices.

Attributes:

- `title`: The question being asked.
- `platform`: Where it will be published.
- `destination`: The page or account.
- `scheduled_at`: When, as text.

```apc
<approval title="Ready to publish?" platform="LinkedIn" destination="Company page" scheduled_at="Today, 6:00 PM">
The post and visual are ready for final review.
<action id="approve_publish" label="Approve and publish" primary>
<action id="edit_draft" label="Edit draft">
</approval>
```

## Function reference for pictures

These are ApasScript functions, called inside a `<script>` block. Only functions listed in the ApasScript documentation exist; do not invent one.

### Plotting

- `graph(xmin, xmax, ymin, ymax)` -- Creates a new plotting canvas: graph() for defaults, graph(w, h) for a size in pixels with the range fitted to what is plotted, graph(xmin, xmax, ymin, ymax) sized automatically from the data range, or graph(w, h, xmin, xmax, ymin, ymax) with explicit pixel dimensions.
  ```
  graph(-5, 5, -1, 1)
  ```
- `title(g, text)` -- Sets a graph's title.
  ```
  g = graph()
  title(g, "My Plot")
  ```
- `xticks(g, spacing)` -- Sets a graph's x-axis tick spacing.
  ```
  g = graph()
  xticks(g, 1)
  ```
- `yticks(g, spacing)` -- Sets a graph's y-axis tick spacing.
  ```
  g = graph()
  yticks(g, 1)
  ```
- `plot(g, data, style)` -- Adds a line series to a graph: plot(g, ys) auto-indexes x = 1..n, plot(g, xs, ys) uses an explicit x array, or plot(g, "expr", min, max) samples an expression in x over a range. Optional trailing color/linetype/label style args.
  ```
  g = graph()
  plot(g, "sin(x)", 0, 6.28)
  ```
- `axes(g, show)` -- Shows or hides a graph's axes.
  ```
  g = graph()
  axes(g, false)
  ```
- `grid(g, show)` -- Shows or hides a graph's grid lines.
  ```
  g = graph()
  grid(g, false)
  ```
- `aspect(g, equal)` -- Forces a graph's x and y axes to use equal pixels-per-unit scaling, so geometric shapes aren't visually distorted.
  ```
  g = graph()
  aspect(g, true)
  ```
- `tracePlot(g, seconds)` -- Makes the curves of a graph draw themselves in: each line traces from the start of its range to the end (x for plot, t for plotParametric, theta for plotPolar) over the given number of seconds, with a dot at the moving end. Leave the seconds out for 4; at most 60; 0 turns it off. On a page the reader can click the picture to play it again. SVG, PNG and PDF output show the finished curves. One-line form: tracePlot(g, "expr", min, max, seconds, color, linetype, label) plots the function and traces it in one call; tracePolar and traceParametric do the same for the other two kinds of curve. All curves of one graph draw together, over the time given last.
  ```
  g = graph()
  plotPolar(g, "1 + cos(theta)", 0, 2*pi)
  tracePlot(g, 3)
  ```
- `tracePolar(g, rExpr, thetaMin, thetaMax, seconds)` -- plotPolar and tracePlot in one line: adds the polar curve r(theta) to the graph and makes the graph's curves draw themselves in over the given number of seconds (4 if left out, at most 60). The optional color, line type and label follow the seconds, as in plotPolar.
  ```
  g = graph()
  tracePolar(g, "1 + cos(theta)", 0, 2*pi, 3, "tomato", "solid", "cardioid")
  aspect(g, true)
  ```
- `traceParametric(g, xExpr, yExpr, tmin, tmax, seconds)` -- plotParametric and tracePlot in one line: adds the curve (x(t), y(t)) to the graph and makes the graph's curves draw themselves in over the given number of seconds (4 if left out, at most 60). The optional color, line type and label follow the seconds, as in plotParametric.
  ```
  g = graph()
  traceParametric(g, "3*cos(t)", "2*sin(t)", 0, 2*pi, 4, "steelblue")
  aspect(g, true)
  ```
- `plotParametric(g, xExpr, yExpr, tmin, tmax)` -- Adds a parametric curve series (x(t), y(t)) to a graph, sampled over an explicit t range.
  ```
  g = graph()
  plotParametric(g, "cos(t)", "sin(t)", 0, 6.28)
  ```
- `plotPolar(g, rExpr, thetaMin, thetaMax)` -- Adds a polar curve series r(theta) to a graph, sampled over an explicit theta range.
  ```
  g = graph()
  plotPolar(g, "1 + cos(theta)", 0, 6.28)
  ```
- `scatter(g, xs, ys)` -- Adds a scatter (points only, no line) series to a graph: scatter(g, ys) auto-indexes x, scatter(g, xs, ys) uses an explicit x array.
  ```
  g = graph()
  scatter(g, [1, 4, 9, 16])
  ```
- `bar(g, xs, ys)` -- Adds a bar series to a graph: bar(g, ys) auto-indexes x, bar(g, xs, ys) uses an explicit x array. When xs is a list of names, bar(g, ["Mon", "Tue"], ys), each bar is named on the x axis and drawn as a thin bar with a rounded end. Several bar series on one graph are told apart by colour and label; stacked(g) stands them on one another.
  ```
  g = graph()
  bar(g, [3, 7, 2, 5])
  ```
- `stacked(g, on)` -- Stands the bar series of a graph on one another instead of one in front of the other: at each x the first series is at the bottom and each later one starts where the one before it ends. Values above zero stack upwards and values below zero downwards. stacked(g, false) turns it off again.
- `pie(g, names, values, hole, colors)` -- Draws values as parts of a whole: pie(g, names, values) gives one slice for each value, starting at twelve o'clock and going clockwise, with each name, value and share listed beside it. A fourth argument between 0 and 1 leaves a hole of that part of the radius, which makes a ring. A list of colours, one for each slice, may be given last. The values must be zero or more, with at least one above zero.
  ```
  p = graph(460, 260)
  pie(p, ["Physics", "Chemistry", "Mathematics", "Biology"], [40, 25, 20, 15])
  title(p, "Questions by subject")
  ```
- `area(g, xs, ys)` -- Adds a filled-area line series (filled to y=0) to a graph.
  ```
  g = graph()
  area(g, [0, 1, 2, 3], [0, 1, 4, 9])
  ```
- `bubble(g, xs, ys, sizes)` -- Adds a bubble series to a graph -- a scatter plot where a third array sets each point's marker size.
  ```
  g = graph()
  bubble(g, [1, 2, 3], [2, 4, 1], [10, 20, 15])
  ```
- `histogram(g, data, numBins)` -- Bins raw data into equal-width buckets and adds it to a graph as a bar series.
  ```
  g = graph()
  histogram(g, [1, 2, 2, 3, 3, 3, 4, 4, 5])
  ```
- `candlestick(g, xs, opens, highs, lows, closes)` -- Adds a candlestick (OHLC) series to a graph, typically indexed by date().
  ```
  g = graph()
  candlestick(g, [1, 2, 3], [10, 11, 12], [12, 13, 14], [9, 10, 11], [11, 12, 13])
  ```
- `logScale(g, axis)` -- Switches a graph's x, y, or both axes to a logarithmic scale.
  ```
  g = graph()
  logScale(g, "y")
  ```

### Diagrams

- `draw(shape, style)` -- Draws a shape (point, vector, circle, ellipse, or line) or a point-to-point segment into the single implicit default diagram. Optional trailing color/label style args, plus a 4th slot that means arrows ("none"/"one"/"two") on a vector or a fill color on a closed shape (circle/ellipse). A vector, draw(v) or draw(p, v), is an arrow by default ("one"). Two points, draw(p1, p2), are a plain line with no arrowhead by default ("none"); pass "one" for an arrow from p1 to p2 or "two" for heads at both ends.
  ```
  draw(circle(point(0, 0), 5), "red", "C", "gold")
  ```
- `xrange(min, max)` -- Sets the x-axis range of the implicit default diagram.
  ```
  xrange(-5, 5)
  ```
- `yrange(min, max)` -- Sets the y-axis range of the implicit default diagram.
  ```
  yrange(-5, 5)
  ```
- `diagramTitle(text)` -- Sets the title of the implicit default diagram.
  ```
  diagramTitle("Force diagram")
  ```
- `curve(points, style)` -- Draws a quadratic (3 points) or cubic (4 points) Bezier curve into the implicit default diagram.
  ```
  curve(point(0, 0), point(1, 3), point(4, 0))
  ```
- `curveBetween(a, b, bend, style)` -- Draws a smooth quadratic curve between two fixed points. bend is signed and dimensionless: 0 is straight, positive bows left from a to b, negative bows right; midpoint offset is bend times half the chord length. Optional styles are color, label, line type (solid, dashed, dotted), and line width.
  ```
  curveBetween(point(1, 1), point(5, 1), 0.2, "red", "arc", "dashed", 3)
  ```
- `vectorFrom(p, length, degrees, style)` -- Draws a vector from a point with a length and direction in degrees. Positive angles are counter-clockwise from +x; negative angles clockwise.
  ```
  vectorFrom(point(2, 3), 5, 30, "blue", "v")
  ```
- `segmentFrom(p, length, degrees, style)` -- Draws an unarrowed finite segment from a point with a length and direction in degrees.
  ```
  segmentFrom(point(2, 3), 5, -30, "gray", "s")
  ```
- `diagram(w, h)` -- Creates a new, independently-named diagram: diagram() for defaults, diagram(w, h) with explicit pixel dimensions.
  ```
  diagram(800, 500)
  ```
- `drawOn(d, shape, style)` -- Draws a shape or a point-to-point segment into a named diagram (see draw() for the implicit-diagram form). drawOn(d, p, vec(dx, dy)) is an arrow by default; drawOn(d, p1, p2) with two points is a plain line by default, and takes "one" or "two" after the label for arrowheads.
  ```
  d = diagram()
  drawOn(d, point(2, 3), vec(1, 1))
  ```
- `vectorFromOn(d, p, length, degrees, style)` -- Draws a degree-directed vector into a named diagram.
  ```
  d = diagram()
  vectorFromOn(d, point(0, 0), 4, 45)
  ```
- `segmentFromOn(d, p, length, degrees, style)` -- Draws a degree-directed unarrowed segment into a named diagram.
  ```
  d = diagram()
  segmentFromOn(d, point(0, 0), 4, -45)
  ```
- `xrangeOn(d, min, max)` -- Sets the x-axis range of a named diagram.
  ```
  d = diagram()
  xrangeOn(d, -5, 5)
  ```
- `yrangeOn(d, min, max)` -- Sets the y-axis range of a named diagram.
  ```
  d = diagram()
  yrangeOn(d, 0, 20)
  ```
- `titleOn(d, text)` -- Sets the title of a named diagram.
  ```
  d = diagram()
  titleOn(d, "Projectile path")
  ```
- `curveOn(d, points, style)` -- Draws a quadratic or cubic Bezier curve into a named diagram (see curve() for the implicit-diagram form).
  ```
  d = diagram()
  curveOn(d, point(0, 0), point(1, 3), point(4, 0))
  ```
- `curveBetweenOn(d, a, b, bend, style)` -- Named-diagram version of curveBetween; draws a smooth quadratic curve between two fixed points. bend is signed and dimensionless: 0 is straight, positive bows left from a to b, negative bows right. Optional styles are color, label, line type (solid, dashed, dotted), and line width.
  ```
  d = diagram()
  curveBetweenOn(d, point(1, 1), point(5, 1), -0.2, "blue", "ray", "dotted", 2)
  ```
- `curveFromLineOn(d, lineStart, join, end, bend, style)` -- Draws a cubic curve starting at join with its tangent aligned to the segment lineStart-to-join. bend adds signed bow near the end. Optional styles are color, label, line type (solid, dashed, dotted), and line width.
  ```
  d = diagram()
  curveFromLineOn(d, point(0, 0), point(1, 0), point(3, 2), 0.1, "red", "path", "dashed", 2)
  ```
- `curveToLineOn(d, start, join, lineEnd, bend, style)` -- Draws a cubic curve ending at join with its tangent aligned to the segment join-to-lineEnd. bend adds signed bow near the start. Optional styles are color, label, line type (solid, dashed, dotted), and line width.
  ```
  d = diagram()
  curveToLineOn(d, point(1, 3), point(3, 2), point(4, 2), -0.1, "blue", "path", "dotted", 2)
  ```
- `polygon(points, style)` -- Draws a closed N-gon (N >= 3) through the given points into the implicit default diagram. Also polygon(corners) with one list of points -- e.g. a transformed shape: polygon(rotate(tri, 90)).
  ```
  polygon(point(0, 0), point(4, 0), point(0, 3), "green", "tri", "lime")
  ```
- `polygonOn(d, points, style)` -- Draws a closed N-gon (N >= 3) into a named diagram (see polygon() for the implicit-diagram form).
  ```
  d = diagram()
  polygonOn(d, point(0, 0), point(4, 0), point(0, 3))
  ```
- `regularPolygon(centre, radius, sides, rotation, style)` -- Draws a regular N-gon (N >= 3 equally-spaced vertices around a circle) into the implicit default diagram.
  ```
  regularPolygon(point(0, 0), 3, 6)
  ```
- `regularPolygonOn(d, centre, radius, sides, rotation, style)` -- Draws a regular N-gon into a named diagram (see regularPolygon() for the implicit-diagram form).
  ```
  d = diagram()
  regularPolygonOn(d, point(0, 0), 3, 6, -90)
  ```
- `arcAt(centre, radius, startAngle, sweepAngle, style)` -- Draws a circular arc (centre, radius, start angle, sweep angle -- degrees, 0 = +x, positive = counter-clockwise) into the implicit default diagram.
  ```
  arcAt(point(0, 0), 4, 0, 90, "red", "quarter turn")
  ```
- `arcAtOn(d, centre, radius, startAngle, sweepAngle, style)` -- Draws a circular arc into a named diagram (see arcAt() for the implicit-diagram form).
  ```
  d = diagram()
  arcAtOn(d, point(0, 0), 4, 0, 90, "red")
  ```
- `arcArrowOn(d, centre, radius, startAngle, sweepAngle, color, lineWidth, ends)` -- An arc with an arrowhead at its end, on a named diagram: which way an angle is measured. A positive sweep turns anticlockwise, a negative one clockwise. A sweep of more than 360 degrees is drawn as a spiral that widens, so that 420 degrees is seen to be one turn and 60 degrees more. Use it for the turn from the initial side of an angle to its terminal side; angleMarkerOn draws a plain arc with a label.
- `arcArrow(centre, radius, startAngle, sweepAngle, color, lineWidth)` -- Implicit-diagram version of arcArrowOn.
  ```
  xrange(-2, 2)
  yrange(-2, 2)
  arcArrow(point(0, 0), 1, 0, 420, "steelblue")
  ```
- `sectorOn(d, centre, radius, startAngle, sweepAngle, color, fill)` -- A sector of a circle on a named diagram: the two radii and the arc between them, filled when a fill colour is given. Angles are in degrees from the positive x direction; the sign of the sweep gives the direction (180/pi degrees is one radian). A sweep of 360 or more is the whole disc.
- `sector(centre, radius, startAngle, sweepAngle, color, fill)` -- Implicit-diagram version of sectorOn.
  ```
  xrange(-2, 2)
  yrange(-2, 2)
  sector(point(0, 0), 1.5, 30, 120, "steelblue", "#e6f0fa")
  ```
- `text(point, text, color, fontSize, rotation)` -- Places a standalone text label into the implicit default diagram (unlike every other shape's `label`, which is attached to a shape -- here the text IS the shape). The text starts at the point and runs to the right of it; its size is in pixels and does not change with the ranges. For a label beside a point or a circuit component, labelAt() and the component's own label argument place it clear automatically.
  ```
  text(point(0, 3), "v = u + at", "gold", 16)
  ```
- `textOn(d, point, text, color, fontSize, rotation)` -- Places a standalone text label into a named diagram (see text() for the implicit-diagram form). The text starts at the point and runs to the right of it; its size is in pixels and does not change with the ranges. For a label beside a point or a circuit component, labelAt() and the component's own label argument place it clear automatically.
  ```
  d = diagram()
  textOn(d, point(0, 3), "v = u + at")
  ```
- `diagramAxes(show)` -- Shows or hides the axes of the implicit default diagram.
  ```
  diagramAxes(false)
  ```
- `axesOn(d, show)` -- Shows or hides the axes of a named diagram.
  ```
  d = diagram()
  axesOn(d, false)
  ```
- `diagramGrid(show)` -- Shows or hides the grid of the implicit default diagram.
  ```
  diagramGrid(false)
  ```
- `traceDraw(seconds)` -- Makes the default diagram draw itself: its shapes are drawn in one after another, in the order the script drew them, over the given number of seconds. A line grows from its first point to its second, a circle or arc sweeps round, a curve runs from start to end, and text fades in. Leave the seconds out for 4; at most 60; 0 turns it off. On a page it plays when it comes into view and again on a click. SVG, PNG and PDF output show the finished picture.
  ```
  draw(point(0, 0), point(4, 0))
  draw(point(4, 0), point(4, 3))
  draw(point(4, 3), point(0, 0), "tomato")
  traceDraw(3)
  ```
- `traceDrawOn(d, seconds)` -- Named-diagram version of traceDraw: the shapes of diagram d are drawn in one after another, in the order they were drawn, over the given number of seconds (4 if left out, at most 60, 0 turns it off). A circuit builds up branch by branch, a construction step by step.
- `gridOn(d, show)` -- Shows or hides the grid of a named diagram.
  ```
  d = diagram()
  gridOn(d, false)
  ```
- `cube(origin, size, dx, dy, color)` -- Paper-style cube in an up/right oblique view. Returns a record with diagram and exact projected vertices [A,B,C,D,E,F,G,H]. size is the front square edge; dx/dy are drawing offsets, not physical edge lengths. All dimensions must be positive. Draws into the implicit diagram.
  ```
  s = cube(point(0,0), 2, 1, 1)
  p = s.vertices[0]
  ```
- `cubeOn(d, origin, size, dx, dy, color)` -- Paper-style cube in an up/right oblique view. Returns a record with diagram and exact projected vertices [A,B,C,D,E,F,G,H]. size is the front square edge; dx/dy are drawing offsets, not physical edge lengths. All dimensions must be positive. Draws into the named diagram.
  ```
  d = diagram()
  s = cubeOn(d, point(0,0), 2, 1, 1)
  p = s.vertices[0]
  ```
- `prism(origin, width, height, dx, dy, color)` -- Paper-style triangular prism with a centered front apex and up/right depth offset. Returns diagram and exact projected vertices [A,B,C,D,E,F]. Positive dimensions required; projected lengths are not true 3D measurements. Draws into the implicit diagram.
  ```
  s = prism(point(0,0), 3, 2, 1, 1)
  p = s.vertices[0]
  ```
- `prismOn(d, origin, width, height, dx, dy, color)` -- Paper-style triangular prism with a centered front apex and up/right depth offset. Returns diagram and exact projected vertices [A,B,C,D,E,F]. Positive dimensions required; projected lengths are not true 3D measurements. Draws into the named diagram.
  ```
  d = diagram()
  s = prismOn(d, point(0,0), 3, 2, 1, 1)
  p = s.vertices[0]
  ```
- `cylinder(base, radius, height, rimDepth, color)` -- Paper-style upright cylinder. Returns diagram and exact projected vertices [bottomLeft,bottomRight,topLeft,topRight,bottomCenter,topCenter]. Positive dimensions and rimDepth < radius required. Half-rims use approximate cubic ellipse guides; rimDepth controls the drawing, not physical size. Draws into the implicit diagram.
  ```
  s = cylinder(point(0,0), 2, 3, 1/2)
  p = s.vertices[0]
  ```
- `cylinderOn(d, base, radius, height, rimDepth, color)` -- Paper-style upright cylinder. Returns diagram and exact projected vertices [bottomLeft,bottomRight,topLeft,topRight,bottomCenter,topCenter]. Positive dimensions and rimDepth < radius required. Half-rims use approximate cubic ellipse guides; rimDepth controls the drawing, not physical size. Draws into the named diagram.
  ```
  d = diagram()
  s = cylinderOn(d, point(0,0), 2, 3, 1/2)
  p = s.vertices[0]
  ```
- `sphere(center, radius, equatorDepth, color)` -- Paper-style sphere outline and equator guide. Returns diagram and exact projected vertices [center,left,right]. Positive radius and 0 < equatorDepth < radius required. The approximate cubic equator is a guide, not an edge. Draws into the implicit diagram.
  ```
  s = sphere(point(0,0), 2, 1/2)
  p = s.vertices[0]
  ```
- `sphereOn(d, center, radius, equatorDepth, color)` -- Paper-style sphere outline and equator guide. Returns diagram and exact projected vertices [center,left,right]. Positive radius and 0 < equatorDepth < radius required. The approximate cubic equator is a guide, not an edge. Draws into the named diagram.
  ```
  d = diagram()
  s = sphereOn(d, point(0,0), 2, 1/2)
  p = s.vertices[0]
  ```
- `edgePoint(a, b, t)` -- Exact interpolation along a straight projected edge. t in [0,1], with t=0 at a and t=1 at b. Returns point2d without drawing. Coincident endpoints and out-of-range/nonfinite t are errors. Native exact arithmetic reports overflow; physical 3D geometry is not inferred.
  ```
  p = edgePoint(point(-2,1), point(4,5), 1/3)
  p.y
  ```
- `cornerMarker(p, label, color, radius, labelDx, labelDy, labelSize)` -- Draws a device-sized labelled dot at a corner or any supplied point. Returns the target diagram. Labels are annotations, not physics verification. Draw the solid first, then markers. Default radius is 7 px with 14 px labels. Edge labels are offset perpendicular to the edge, preferring the right side (up for horizontal edges), at radius+labelSize+6 pixels. Corner labels use offsets (radius+5, -(radius+13)). This is local placement, not whole-diagram collision detection. Optional radius, labelDx, labelDy and labelSize follow color; positive labelDy moves down. Custom offsets prevent crowding; marker coordinates stay on the requested geometry.
  ```
  s = cube(point(0,0), 2, 1, 1)
  cornerMarker(s.vertices[0], "m", "gold")
  ```
- `cornerMarkerOn(d, p, label, color, radius, labelDx, labelDy, labelSize)` -- Draws a device-sized labelled dot at a corner or any supplied point. Returns the target diagram. Labels are annotations, not physics verification. Draw the solid first, then markers. Default radius is 7 px with 14 px labels. Edge labels are offset perpendicular to the edge, preferring the right side (up for horizontal edges), at radius+labelSize+6 pixels. Corner labels use offsets (radius+5, -(radius+13)). This is local placement, not whole-diagram collision detection. Optional radius, labelDx, labelDy and labelSize follow color; positive labelDy moves down. Custom offsets prevent crowding; marker coordinates stay on the requested geometry.
  ```
  d = diagram()
  s = cubeOn(d, point(0,0), 2, 1, 1)
  cornerMarkerOn(d, s.vertices[0], "m", "gold")
  ```
- `edgeMarker(a, b, t, label, color, radius, labelDx, labelDy, labelSize)` -- Draws a device-sized labelled dot at fraction t along the straight edge. Returns the target diagram. Labels are annotations, not physics verification. Draw the solid first, then markers. Default radius is 7 px with 14 px labels. Edge labels are offset perpendicular to the edge, preferring the right side (up for horizontal edges), at radius+labelSize+6 pixels. Corner labels use offsets (radius+5, -(radius+13)). This is local placement, not whole-diagram collision detection. Optional radius, labelDx, labelDy and labelSize follow color; positive labelDy moves down. Custom offsets prevent crowding; marker coordinates stay on the requested geometry.
  ```
  s = cube(point(0,0), 2, 1, 1)
  edgeMarker(s.vertices[0], s.vertices[1], 1/2, "+q", "red")
  ```
- `edgeMarkerOn(d, a, b, t, label, color, radius, labelDx, labelDy, labelSize)` -- Draws a device-sized labelled dot at fraction t along the straight edge. Returns the target diagram. Labels are annotations, not physics verification. Draw the solid first, then markers. Default radius is 7 px with 14 px labels. Edge labels are offset perpendicular to the edge, preferring the right side (up for horizontal edges), at radius+labelSize+6 pixels. Corner labels use offsets (radius+5, -(radius+13)). This is local placement, not whole-diagram collision detection. Optional radius, labelDx, labelDy and labelSize follow color; positive labelDy moves down. Custom offsets prevent crowding; marker coordinates stay on the requested geometry.
  ```
  d = diagram()
  s = cubeOn(d, point(0,0), 2, 1, 1)
  edgeMarkerOn(d, s.vertices[0], s.vertices[1], 1/2, "+q", "red")
  ```
- `angleMarker(vertex, rayA, rayB, radius, label, color, direction, labelOffset, labelSize, lineType, lineWidth)` -- Draws a labelled circular angle marker into the implicit diagram. The vertex and two points define rays; the points need not be equally distant. direction is optional: minor (default) selects the shorter signed sweep, major the reflex sweep, ccw the counter-clockwise sweep from rayA to rayB, and cw the clockwise sweep. labelOffset is the radial distance beyond the arc in diagram units (default 0.55*radius). Zero-length and collinear rays, nonpositive radius/font/line width, and a label position at or behind the vertex are errors. Returns the target diagram.
  ```
  angleMarker(point(0,0), point(3,0), point(2,2), 0.6, "θ", "green")
  ```
- `angleMarkerOn(d, vertex, rayA, rayB, radius, label, color, direction, labelOffset, labelSize, lineType, lineWidth)` -- Named-diagram angle marker. The vertex and two points define rays; the points need not be equally distant. direction is optional: minor (default) selects the shorter signed sweep, major the reflex sweep, ccw the counter-clockwise sweep from rayA to rayB, and cw the clockwise sweep. labelOffset is the radial distance beyond the arc in diagram units (default 0.55*radius). Zero-length and collinear rays, nonpositive radius/font/line width, and a label position at or behind the vertex are errors. Returns the target diagram.
  ```
  d = diagram()
  angleMarkerOn(d, point(0,0), point(3,0), point(2,2), 0.6, "θ", "green")
  ```
- `rightAngleMarker(vertex, rayA, rayB, size, label, color, labelOffset, labelSize, lineType, lineWidth)` -- Draws a labelled right-angle square into the implicit diagram. The vertex and two points define the rays; the function verifies that they are perpendicular instead of merely decorating a non-right angle. labelOffset is the radial distance beyond the square's outer corner in diagram units (default 0.75*size). Zero-length rays, nonperpendicular rays, nonpositive size/font/line width, and a label position at or behind the vertex are errors. Returns the target diagram.
  ```
  rightAngleMarker(point(0,0), point(3,0), point(0,3), 0.4, "90°")
  ```
- `rightAngleMarkerOn(d, vertex, rayA, rayB, size, label, color, labelOffset, labelSize, lineType, lineWidth)` -- Named-diagram right-angle square. The vertex and two points define the rays; the function verifies that they are perpendicular instead of merely decorating a non-right angle. labelOffset is the radial distance beyond the square's outer corner in diagram units (default 0.75*size). Zero-length rays, nonperpendicular rays, nonpositive size/font/line width, and a label position at or behind the vertex are errors. Returns the target diagram.
  ```
  d = diagram()
  rightAngleMarkerOn(d, point(0,0), point(3,0), point(0,3), 0.4, "90°")
  ```
- `spiral(centre, startRadius, endRadius, turns, startDegrees, style)` -- Implicit-diagram version, compatible with animate(). An Archimedean spiral with linearly varying radius. Signed turns select winding direction; start angle is degrees. Radii must be nonnegative, turns nonzero with magnitude at most 100. Optional styles: color, label, line type, line width.
  ```
  spiral(point(0,0), 0.1, 2, 3, 0, "#2563eb")
  ```
- `spiralOn(d, centre, startRadius, endRadius, turns, startDegrees, style)` -- Named-diagram version. An Archimedean spiral with linearly varying radius. Signed turns select winding direction; start angle is degrees. Radii must be nonnegative, turns nonzero with magnitude at most 100. Optional styles: color, label, line type, line width.
  ```
  d = diagram()
  spiralOn(d, point(0,0), 0.1, 2, 3, 0, "#2563eb")
  ```
- `spring(start, end, radius, turns, style)` -- Implicit-diagram version, compatible with animate(). A sinusoidal side-view spring with exact attachment endpoints. Turns are integer 1..100 and radius is positive. Geometry only; no spring forces are calculated. Optional styles: color, label, line type, line width.
  ```
  spring(point(0,0), point(6,0), 0.5, 6, "#2563eb")
  ```
- `springOn(d, start, end, radius, turns, style)` -- Named-diagram version. A sinusoidal side-view spring with exact attachment endpoints. Turns are integer 1..100 and radius is positive. Geometry only; no spring forces are calculated. Optional styles: color, label, line type, line width.
  ```
  d = diagram()
  springOn(d, point(0,0), point(6,0), 0.5, 6, "#2563eb")
  ```
- `coil(start, end, radius, turns, projectionDepth, style)` -- Implicit-diagram version, compatible with animate(). A projected helical coil between exact attachment endpoints. Integer turns 1..100; positive radius; projection depth 0..1. This is drawing geometry, not a magnetic-field model. Optional styles: color, label, line type, line width.
  ```
  coil(point(0,0), point(6,0), 0.8, 8, 0.65, "#2563eb")
  ```
- `coilOn(d, start, end, radius, turns, projectionDepth, style)` -- Named-diagram version. A projected helical coil between exact attachment endpoints. Integer turns 1..100; positive radius; projection depth 0..1. This is drawing geometry, not a magnetic-field model. Optional styles: color, label, line type, line width.
  ```
  d = diagram()
  coilOn(d, point(0,0), point(6,0), 0.8, 8, 0.65, "#2563eb")
  ```
- `inductor(start, end, loopHeight, loops, style)` -- Implicit-diagram version, compatible with animate(). A circuit inductor made from repeated half-ellipse loops with exact attachment endpoints. Integer loops 1..100; positive height. Add lead wires separately. Optional styles: color, label, line type, line width. In a circuit, leave out the loop height and count: inductor(a, b, label, side) draws the inductor symbol in the middle of the branch with its lead wires and a label placed clear of it, like resistor().
  ```
  inductor(point(0,0), point(6,0), 0.8, 5, "#2563eb")
  ```
- `inductorOn(d, start, end, loopHeight, loops, style)` -- Named-diagram version. A circuit inductor made from repeated half-ellipse loops with exact attachment endpoints. Integer loops 1..100; positive height. Add lead wires separately. Optional styles: color, label, line type, line width. In a circuit, leave out the loop height and count: inductor(a, b, label, side) draws the inductor symbol in the middle of the branch with its lead wires and a label placed clear of it, like resistor().
  ```
  d = diagram()
  inductorOn(d, point(0,0), point(6,0), 0.8, 5, "#2563eb")
  ```
- `resistor(a, b, label, side, color, lineWidth)` -- A resistor between two points: the zigzag symbol in the middle and lead wires out to both points, in one call. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  resistor(point(0, 0), point(4, 0), "R = 10 Ω")
  ```
- `resistorOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A resistor between two points: the zigzag symbol in the middle and lead wires out to both points, in one call. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  resistorOn(d, point(0, 2), point(4, 2), "R₁")
  ```
- `variableResistor(a, b, label, side, color, lineWidth)` -- A variable resistor (rheostat) between two points: a resistor with an arrow through it, and its lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  variableResistor(point(0, 0), point(4, 0), "Rh")
  ```
- `variableResistorOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A variable resistor (rheostat) between two points: a resistor with an arrow through it, and its lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  variableResistorOn(d, point(0, 2), point(4, 2), "Rh")
  ```
- `cell(a, b, label, side, color, lineWidth)` -- A cell between two points, with its lead wires. The long thin plate (positive) is on the side of the second point, the short thick plate (negative) on the side of the first. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  cell(point(0, 0), point(4, 0), "ε = 2 V")
  ```
- `cellOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A cell between two points, with its lead wires. The long thin plate (positive) is on the side of the second point, the short thick plate (negative) on the side of the first. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  cellOn(d, point(0, 0), point(0, 3), "12 V")
  ```
- `battery(a, b, cells, label, side, color, lineWidth)` -- A battery of 1 to 8 cells between two points, with its lead wires. Each cell's positive plate faces the second point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  battery(point(0, 0), point(4, 0), 3, "ε")
  ```
- `batteryOn(d, a, b, cells, label, side, color, lineWidth)` -- Named-diagram version. A battery of 1 to 8 cells between two points, with its lead wires. Each cell's positive plate faces the second point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  batteryOn(d, point(0, 0), point(0, 3), 3, "6 V")
  ```
- `capacitor(a, b, label, side, color, lineWidth)` -- A capacitor between two points: two equal parallel plates, with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  capacitor(point(0, 0), point(4, 0), "C = 2 μF")
  ```
- `capacitorOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A capacitor between two points: two equal parallel plates, with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  capacitorOn(d, point(0, 2), point(4, 2), "C₁")
  ```
- `meter(a, b, letter, label, side, color, lineWidth)` -- A meter between two points: a circle with a letter in it ("A" ammeter, "V" voltmeter, "G" galvanometer), with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  meter(point(0, 0), point(4, 0), "A")
  ```
- `meterOn(d, a, b, letter, label, side, color, lineWidth)` -- Named-diagram version. A meter between two points: a circle with a letter in it ("A" ammeter, "V" voltmeter, "G" galvanometer), with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  meterOn(d, point(0, 2), point(4, 2), "V", "8 V")
  ```
- `bulb(a, b, label, side, color, lineWidth)` -- A lamp between two points: a circle with a cross, with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  bulb(point(0, 0), point(4, 0), "L")
  ```
- `bulbOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A lamp between two points: a circle with a cross, with lead wires. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  bulbOn(d, point(0, 2), point(4, 2), "60 W")
  ```
- `switchKey(a, b, state, label, side, color, lineWidth)` -- A switch (key) between two points, open or closed, with lead wires. The blade is hinged on the side of the first point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  switchKey(point(0, 0), point(4, 0), "open", "K")
  ```
- `switchKeyOn(d, a, b, state, label, side, color, lineWidth)` -- Named-diagram version. A switch (key) between two points, open or closed, with lead wires. The blade is hinged on the side of the first point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  switchKeyOn(d, point(0, 0), point(4, 0), "closed", "S")
  ```
- `diode(a, b, label, side, color, lineWidth)` -- A diode between two points, with its lead wires: the triangle points from the first point to the second (the direction conventional current is allowed to flow), and the bar is on the side of the second point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  diode(point(0, 0), point(4, 0), "D")
  ```
- `diodeOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A diode between two points, with its lead wires: the triangle points from the first point to the second (the direction conventional current is allowed to flow), and the bar is on the side of the second point. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  diodeOn(d, point(0, 2), point(4, 2), "D₁")
  ```
- `zenerDiode(a, b, label, side, color, lineWidth)` -- A Zener diode between two points, with its lead wires: a diode whose bar has bent ends. The triangle points from the first point to the second, so for a regulator (reverse biased) put the second point on the positive side. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  zenerDiode(point(0, 0), point(0, 3), "4 V")
  ```
- `zenerDiodeOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. A Zener diode between two points, with its lead wires: a diode whose bar has bent ends. The triangle points from the first point to the second, so for a regulator (reverse biased) put the second point on the positive side. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  zenerDiodeOn(d, point(2, 0), point(2, 3), "Vz = 4 V", "right")
  ```
- `acSource(a, b, label, side, color, lineWidth)` -- An alternating voltage source between two points, with its lead wires: a circle with one period of a sine wave in it. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  acSource(point(0, 0), point(0, 3), "220 V, 50 Hz")
  ```
- `acSourceOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. An alternating voltage source between two points, with its lead wires: a circle with one period of a sine wave in it. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange before drawing it.
  ```
  d = diagram()
  acSourceOn(d, point(0, 0), point(0, 3), "V = V₀ sin ωt")
  ```
- `terminal(p, label, side, color)` -- An open terminal: a small ring where a wire ends, with an optional name placed beside it. Draw it after the wire that ends there.
  ```
  wire(point(0, 0), point(2, 0))
  terminal(point(2, 0), "A", "right")
  ```
- `terminalOn(d, p, label, side, color)` -- Named-diagram version. An open terminal: a small ring where a wire ends, with an optional name placed beside it. Draw it after the wire that ends there.
  ```
  d = diagram()
  wireOn(d, point(0, 0), point(2, 0))
  terminalOn(d, point(2, 0), "A", "right")
  ```
- `transistor(base, collector, emitter, kind, label, color, lineWidth)` -- A bipolar transistor joined to three points. The symbol is drawn at the middle of the collector-emitter line, on the base's side, and leads run to all three points, so put the collector and emitter in line (one above the other) and the base to one side, level with their middle. The emitter arrow points outwards for "npn" and inwards for "pnp". The label goes on the side away from the base. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange first.
  ```
  transistor(point(0, 2), point(2, 4), point(2, 0), "npn", "T")
  ```
- `transistorOn(d, base, collector, emitter, kind, label, color, lineWidth)` -- Named-diagram version. A bipolar transistor joined to three points. The symbol is drawn at the middle of the collector-emitter line, on the base's side, and leads run to all three points, so put the collector and emitter in line (one above the other) and the base to one side, level with their middle. The emitter arrow points outwards for "npn" and inwards for "pnp". The label goes on the side away from the base. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange first.
  ```
  d = diagram()
  transistorOn(d, point(0, 2), point(2, 4), point(2, 0), "npn", "T")
  ```
- `gate(kind, inputA, inputB, output, label, color, lineWidth)` -- A logic gate between its input points and its output point: "and", "or", "not", "nand", "nor", "xor" or "xnor". Give two input points (one for "not") and then the output point. The body is drawn midway, facing the output, and a lead runs from each point to its pin, so a gate's output point can be given again as an input of the next gate. Passing the same point twice joins both inputs to it. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange first.
  ```
  gate("nand", point(0, 3), point(0, 1), point(4, 2))
  ```
- `gateOn(d, kind, inputA, inputB, output, label, color, lineWidth)` -- Named-diagram version. A logic gate between its input points and its output point: "and", "or", "not", "nand", "nor", "xor" or "xnor". Give two input points (one for "not") and then the output point. The body is drawn midway, facing the output, and a lead runs from each point to its pin, so a gate's output point can be given again as an input of the next gate. Passing the same point twice joins both inputs to it. The symbol keeps the same size on the page whatever the ranges are, so set xrange and yrange first.
  ```
  d = diagram()
  gateOn(d, "nand", point(0, 3), point(0, 1), point(4, 2), "G₁")
  ```
- `twoWaySwitch(pivot, contactA, contactB, position, label, color, lineWidth)` -- A two-way switch: a pivot and two contacts, with the blade on contact a, on contact b, or between them ("open"). The contacts are the points given; draw the wires to them separately. The label goes beside the pivot, to one side of the line from pivot to contacts.
  ```
  twoWaySwitch(point(2, 0), point(1, 2), point(3, 2), "a", "S")
  ```
- `twoWaySwitchOn(d, pivot, contactA, contactB, position, label, color, lineWidth)` -- Named-diagram version. A two-way switch: a pivot and two contacts, with the blade on contact a, on contact b, or between them ("open"). The contacts are the points given; draw the wires to them separately. The label goes beside the pivot, to one side of the line from pivot to contacts.
  ```
  d = diagram()
  twoWaySwitchOn(d, point(2, 0), point(1, 2), point(3, 2), "a", "S")
  ```
- `currentArrow(a, b, label, side, color, lineWidth)` -- An arrowhead half-way between two points, pointing to the second: the direction of a current on a wire. It draws no wire of its own, so draw the wire or component separately.
  ```
  wire(point(0, 0), point(4, 0))
  currentArrow(point(0, 0), point(4, 0), "I")
  ```
- `currentArrowOn(d, a, b, label, side, color, lineWidth)` -- Named-diagram version. An arrowhead half-way between two points, pointing to the second: the direction of a current on a wire. It draws no wire of its own, so draw the wire or component separately.
  ```
  d = diagram()
  wireOn(d, point(0, 0), point(4, 0))
  currentArrowOn(d, point(0, 0), point(4, 0), "I")
  ```
- `wire(points, color, lineWidth)` -- A wire through two or more points in order: plain segments with no arrowheads, for the corners of a circuit.
  ```
  wire(point(0, 0), point(0, 3), point(4, 3))
  ```
- `wireOn(d, points, color, lineWidth)` -- Named-diagram version. A wire through two or more points in order: plain segments with no arrowheads, for the corners of a circuit.
  ```
  d = diagram()
  wireOn(d, point(0, 0), point(0, 3), point(4, 3))
  ```
- `junction(p, label, side, color)` -- A junction dot where wires meet, with an optional name placed beside it, clear of the dot.
  ```
  junction(point(2, 3), "A")
  ```
- `junctionOn(d, p, label, side, color)` -- Named-diagram version. A junction dot where wires meet, with an optional name placed beside it, clear of the dot.
  ```
  d = diagram()
  junctionOn(d, point(2, 3), "A", "above")
  ```
- `ground(p, color, lineWidth)` -- The earth symbol hanging below a point: a short stem and three bars.
  ```
  ground(point(0, 0))
  ```
- `groundOn(d, p, color, lineWidth)` -- Named-diagram version. The earth symbol hanging below a point: a short stem and three bars.
  ```
  d = diagram()
  groundOn(d, point(0, 0))
  ```
- `labelAt(p, text, side, color, fontSize)` -- Text placed beside a point instead of on it: the engine moves it to the side asked for, by half its own size plus a small gap, so it stays clear of whatever is at the point. Use it for terminal signs and names next to a drawing; text() starts the text exactly at its point.
  ```
  labelAt(point(0, 3), "+", "left")
  ```
- `labelAtOn(d, p, text, side, color, fontSize)` -- Named-diagram version. Text placed beside a point instead of on it: the engine moves it to the side asked for, by half its own size plus a small gap, so it stays clear of whatever is at the point. Use it for terminal signs and names next to a drawing; text() starts the text exactly at its point.
  ```
  d = diagram()
  labelAtOn(d, point(0, 3), "+", "left")
  ```
- `vectorField(Fx, Fy, xmin, xmax, ymin, ymax, nx, ny, mode, scale, style)` -- Implicit-diagram form, compatible with animate(). Samples two vector component expressions over a grid. Arrows are centred on sample points. Direction mode uses equal arrow length; scaled mode displays magnitude times scale; capped mode caps lengths to 80% of the smaller grid spacing. Zero and nonfinite vectors and division-by-zero samples are omitted. Other expression errors reject the entire drawing. Sample x/y bindings are restored. This draws a field; it does not simulate motion.
  ```
  vectorField("-y", "x", -3, 3, -3, 3, 9, 9, "direction", 0.5, "#2563eb")
  ```
- `vectorFieldOn(d, Fx, Fy, xmin, xmax, ymin, ymax, nx, ny, mode, scale, style)` -- Named-diagram form. Samples two vector component expressions over a grid. Arrows are centred on sample points. Direction mode uses equal arrow length; scaled mode displays magnitude times scale; capped mode caps lengths to 80% of the smaller grid spacing. Zero and nonfinite vectors and division-by-zero samples are omitted. Other expression errors reject the entire drawing. Sample x/y bindings are restored. This draws a field; it does not simulate motion.
  ```
  d = diagram()
  vectorFieldOn(d, "-y", "x", -3, 3, -3, 3, 9, 9, "direction", 0.5, "#2563eb")
  ```
- `fieldLine(Fx, Fy, seed, xmin, xmax, ymin, ymax, step, maxSteps, options)` -- Implicit-diagram form, compatible with animation. Traces a 2D field using gtmath vector RK4 on normalized components. Directions: forward, backward, both (default). Arrows always follow the physical field direction, including backward traces. Stops at bounds, exclusion circles, division by zero, nonfinite/near-zero fields, a closed return to the seed, stalled motion or the step budget. This is a distance-based field curve; a streamline of a time-varying field is not a particle trajectory. Expressions must be side-effect free. x/y bindings are restored, and expression errors leave the diagram unchanged.
  ```
  fieldLine("-y", "x", point(1,0), -3, 3, -3, 3, 0.05, 200, "both", 0.8, "purple")
  ```
- `fieldLineOn(d, Fx, Fy, seed, xmin, xmax, ymin, ymax, step, maxSteps, options)` -- Named-diagram form. Traces a 2D field using gtmath vector RK4 on normalized components. Directions: forward, backward, both (default). Arrows always follow the physical field direction, including backward traces. Stops at bounds, exclusion circles, division by zero, nonfinite/near-zero fields, a closed return to the seed, stalled motion or the step budget. This is a distance-based field curve; a streamline of a time-varying field is not a particle trajectory. Expressions must be side-effect free. x/y bindings are restored, and expression errors leave the diagram unchanged.
  ```
  d = diagram()
  fieldLineOn(d, "-y", "x", point(1,0), -3, 3, -3, 3, 0.05, 200, "both", 0.8, "purple")
  ```
- `streamline(Fx, Fy, seed, xmin, xmax, ymin, ymax, step, maxSteps, options)` -- Implicit-diagram form, compatible with animation. Traces a 2D field using gtmath vector RK4 on normalized components. Directions: forward, backward, both (default). Arrows always follow the physical field direction, including backward traces. Stops at bounds, exclusion circles, division by zero, nonfinite/near-zero fields, a closed return to the seed, stalled motion or the step budget. This is a distance-based field curve; a streamline of a time-varying field is not a particle trajectory. Expressions must be side-effect free. x/y bindings are restored, and expression errors leave the diagram unchanged.
  ```
  streamline("-y", "x", point(1,0), -3, 3, -3, 3, 0.05, 200, "both", 0.8, "purple")
  ```
- `streamlineOn(d, Fx, Fy, seed, xmin, xmax, ymin, ymax, step, maxSteps, options)` -- Named-diagram form. Traces a 2D field using gtmath vector RK4 on normalized components. Directions: forward, backward, both (default). Arrows always follow the physical field direction, including backward traces. Stops at bounds, exclusion circles, division by zero, nonfinite/near-zero fields, a closed return to the seed, stalled motion or the step budget. This is a distance-based field curve; a streamline of a time-varying field is not a particle trajectory. Expressions must be side-effect free. x/y bindings are restored, and expression errors leave the diagram unchanged.
  ```
  d = diagram()
  streamlineOn(d, "-y", "x", point(1,0), -3, 3, -3, 3, 0.05, 200, "both", 0.8, "purple")
  ```
- `pointChargeLines(centre, charge, lineCount, xmin, xmax, ymin, ymax, options)` -- Isolated point-charge field-line preset with evenly spaced circular seeds and a signed charge marker. Arrows point outwards for positive charge and inwards for negative charge. Charge magnitude does not encode field strength or line density; this is normalized direction geometry, not a quantitative field calculation. The seed circle must fit inside bounds. Traces start at the seed radius; marker radius is 60% of it. lineCount*maxSteps must not exceed 4000. Explicit calls on separate charges do not superpose their fields. Implicit form works in the existing recorder.
  ```
  pointChargeLines(point(0,0), 1, 12, -3, 3, -3, 3)
  ```
- `pointChargeLinesOn(d, centre, charge, lineCount, xmin, xmax, ymin, ymax, options)` -- Isolated point-charge field-line preset with evenly spaced circular seeds and a signed charge marker. Arrows point outwards for positive charge and inwards for negative charge. Charge magnitude does not encode field strength or line density; this is normalized direction geometry, not a quantitative field calculation. The seed circle must fit inside bounds. Traces start at the seed radius; marker radius is 60% of it. lineCount*maxSteps must not exceed 4000. Explicit calls on separate charges do not superpose their fields. Implicit form works in the existing recorder.
  ```
  d = diagram()
  pointChargeLinesOn(d, point(0,0), 1, 12, -3, 3, -3, 3)
  ```
- `chargeField(charges, xmin, xmax, ymin, ymax, nx, ny, arrowLength)` -- Draw electric field arrows for point charges. Charges are [x, y, q, ...].
  ```
  chargeField([0, 0, 1], -3, 3, -3, 3, 9, 9, 0.4)
  ```
- `chargeFieldOn(d, charges, xmin, xmax, ymin, ymax, nx, ny, arrowLength)` -- Draw electric field arrows for point charges. Charges are [x, y, q, ...].
  ```
  d = diagram()
  chargeFieldOn(d, [0, 0, 1], -3, 3, -3, 3, 9, 9, 0.4)
  ```
- `potentialContours(charges, xmin, xmax, ymin, ymax, nx, ny, levels)` -- Draw equipotential contours for point charges at the listed levels.
  ```
  potentialContours([0, 0, 1], -3, 3, -3, 3, 31, 31, [0.5, 1, 2])
  ```
- `potentialContoursOn(d, charges, xmin, xmax, ymin, ymax, nx, ny, levels)` -- Draw equipotential contours for point charges at the listed levels.
  ```
  d = diagram()
  potentialContoursOn(d, [0, 0, 1], -3, 3, -3, 3, 31, 31, [0.5, 1, 2])
  ```
- `chargeStreamlines(charges, seeds, xmin, xmax, ymin, ymax, step, maxSteps)` -- Trace electric field lines from seed coordinates for point charges.
  ```
  chargeStreamlines([0, 0, 1], [0.3, 0], -3, 3, -3, 3, 0.08, 100)
  ```
- `chargeStreamlinesOn(d, charges, seeds, xmin, xmax, ymin, ymax, step, maxSteps)` -- Trace electric field lines from seed coordinates for point charges.
  ```
  d = diagram()
  chargeStreamlinesOn(d, [0, 0, 1], [0.3, 0], -3, 3, -3, 3, 0.08, 100)
  ```
- `biology(kind, at, size)` -- Appends a named Zig biology motif to the implicit diagram. Motifs include animal_cell, plant_cell, nucleus, mitochondrion, chloroplast, dna_helix, bacterium and enveloped_virus. Use biologyOn to compose named diagrams.
  ```
  biology("nucleus", point(0, 0), 1)
  ```
- `biologyOn(diagram, kind, at, size)` -- Appends a Zig biology motif to a named diagram, composing with existing drawing and circuit calls.
  ```
  d = diagram()
  biologyOn(d, "nucleus", point(0, 0), 1)
  ```
- `biologyKeyOn(diagram, centre, halfWidth, halfHeight, anchor, label, ...)` -- Adds numbered markers at biology structures and automatically orders a two-column key outside the art. Pass one or more anchor/label pairs. No leader lines or label boxes are drawn.
  ```
  d = diagram()
  biologyKeyOn(d, point(0,0), 4, 3, point(-1,1), "Nucleus", point(2,-1), "Mitochondrion")
  ```
- `biologyKey(centre, halfWidth, halfHeight, anchor, label, ...)` -- Implicit-diagram version of biologyKeyOn; places numbered biology labels in an outside key.
  ```
  biologyKey(point(0,0), 4, 3, point(-1,1), "Nucleus")
  ```
- `vennOn(diagram, cx, cy, scale, outside, Aonly, both, Bonly, region, text, ...)` -- A Venn diagram of two sets on a named diagram: a rectangle 5.2 by 3.2 times the scale with U in its corner, circle A outlined steelblue and B tomato with each letter inside its own part, and the four regions shaded as asked ("" leaves one clear). Optional region-number/text pairs write elements in a region, clear of the letters.
  ```
  d = diagram()
  vennOn(d, 0, 0, 1, "white", "skyblue", "gold", "salmon")
  ```
- `venn3On(diagram, cx, cy, scale, region0, ..., region7, region, text, ...)` -- A Venn diagram of three sets, A and B above and C (seagreen) below, with each of the eight regions shaded as asked.
  ```
  d = diagram()
  venn3On(d, 0, 0, 1, "white", "gold", "gold", "gold", "gold", "gold", "gold", "orange")
  ```
- `venn(cx, cy, scale, outside, Aonly, both, Bonly, region, text, ...)` -- Implicit-diagram version of vennOn, including inside animation frames.
  ```
  venn(0, 0, 1, "white", "skyblue", "gold", "salmon")
  ```
- `venn3(cx, cy, scale, region0, ..., region7, region, text, ...)` -- Implicit-diagram version of venn3On, including inside animation frames.
  ```
  venn3(0, 0, 1, "white", "gold", "gold", "gold", "gold", "gold", "gold", "orange")
  ```
- `numberLineOn(diagram, min, max, tickStep, lower, upper, lowerClosed, upperClosed, color)` -- A number line with arrowheads, ticks and their numbers below it, and an interval marked on it: a hollow circle at an end left out, a filled one at an end taken in, an arrowhead where it runs on without end.
  ```
  d = diagram()
  numberLineOn(d, -4, 6, 1, -3, 5, false, true, "steelblue")
  ```
- `arrowDiagramOn(diagram, cx, cy, scale, A, B, R, nameA, nameB, color)` -- An arrow diagram of a relation on a named diagram: two ovals side by side with the elements of each set written down the middle, and an arrow from x to y for each ordered pair (x, y). The elements stand one scale apart; the ovals' centres are 2.25 times the scale either side of (cx, cy).
- `arrowDiagram(cx, cy, scale, A, B, R, nameA, nameB, color)` -- Implicit-diagram version of arrowDiagramOn, also inside animation frames.
- `coordinatePlaneOn(diagram, xmin, xmax, ymin, ymax, xstep, ystep, yscale)` -- A ruled coordinate plane readable on a white page, on a named diagram: a light grid, the two axes with arrowheads, numbered marks, and the letters X, Y and O. Marks a fraction of pi apart, from a fraction of pi, are named in pi (a step of pi/2 gives -π, -π/2, π/2, π, 3π/2), so a trigonometric graph is marked as a textbook prints it. Numbers that would touch one another are thinned to round ones (every second, every fifth mark). It sets the diagram's ranges (three quarters of a step of x beyond the plane all round, 20 px at least) and turns the faint built-in axes off. functionGraphOn, openPointOn and closedPointOn then draw on it. planeNumbersOn, planeNamesOn and planeGridOn, called before it, change its numbers, the names of its axes and its grid.
  ```
  d = diagram(420, 420)
  coordinatePlaneOn(d, -3, 3, -1, 5)
  functionGraphOn(d, "x^2", -3, 3)
  d
  ```
- `coordinatePlane(xmin, xmax, ymin, ymax, xstep, ystep, yscale)` -- Implicit-diagram version of coordinatePlaneOn, also inside animation frames.
  ```
  coordinatePlane(-4, 4, -2, 2)
  functionGraph("sin(x)", -4, 4)
  ```
- `functionGraphOn(diagram, f, a, b, color, width, dash)` -- The graph of y = f(x) for a <= x <= b on the plane drawn by coordinatePlaneOn, or on any diagram whose two ranges are set (xrangeOn, yrangeOn), so on axes drawn by hand as well. The curve is broken where the function jumps (a step function, an asymptote) or has no value, and is cut at the top and bottom of the plane (of the picture, without a plane). f is a rule in x as text, or the name of a function defined with fn. A number of the plane (or its O) that a line drawn on the plane so far runs through is moved beside its mark, as a textbook sets -π to one side of the point where the curve crosses the axis; so draw asymptotes and other lines before the graph.
- `functionGraph(f, a, b, color, width, dash)` -- Implicit-diagram version of functionGraphOn, also inside animation frames. Call coordinatePlane first, or set xrange and yrange.
  ```
  coordinatePlane(-3, 3, -1, 3)
  functionGraph("abs(x)", -3, 3, "seagreen")
  ```
- `openPointOn(diagram, x, y, color)` -- A hollow circle at (x, y) on the coordinate plane: the end of a piece of a graph that the graph does not reach.
- `openPoint(x, y, color)` -- Implicit-diagram version of openPointOn.
  ```
  coordinatePlane(-1, 3, -1, 2)
  openPoint(1, 0)
  ```
- `closedPointOn(diagram, x, y, color)` -- A filled circle at (x, y) on the coordinate plane: the end of a piece of a graph that belongs to it.
  ```
  d = diagram(420, 300)
  coordinatePlaneOn(d, -1, 3, -1, 2)
  closedPointOn(d, 1, 1, "tomato")
  d
  ```
- `closedPoint(x, y, color)` -- Implicit-diagram version of closedPointOn.
  ```
  coordinatePlane(-1, 3, -1, 2)
  closedPoint(1, 1)
  ```
- `planeNumbersOn(diagram, xevery, yevery)` -- How far apart the numbers of the plane are, on a named diagram; called before coordinatePlaneOn. Each distance is a whole number of the plane's steps: on a plane ruled every pi/2, planeNumbersOn(d, pi, 1) names -π, π, 2π and leaves the half marks bare. 0 is no numbers on that axis. Without this call the plane numbers every mark and thins them only where they would touch.
- `planeNumbers(xevery, yevery)` -- Implicit-diagram version of planeNumbersOn; before coordinatePlane.
  ```
  planeNumbers(2, 2)
  coordinatePlane(-6, 6, -4, 4)
  functionGraph("x/2", -6, 6)
  ```
- `planeNamesOn(diagram, x, y, xback, yback)` -- What the ends of the plane's axes are called, on a named diagram; called before coordinatePlaneOn. Two names are the positive ends (X and Y without this call); four add the negative ends, as a textbook writes X′ and Y′. An empty name leaves that end bare.
- `planeNames(x, y, xback, yback)` -- Implicit-diagram version of planeNamesOn; before coordinatePlane.
  ```
  planeNames("t", "v")
  coordinatePlane(0, 6, 0, 4)
  functionGraph("x/2 + 1", 0, 6)
  ```
- `planeGridOn(diagram, show)` -- With false the plane drawn next on a named diagram has no grid: each mark is a short stroke across its axis, as on a textbook's axes. Called before coordinatePlaneOn.
- `planeGrid(show)` -- Implicit-diagram version of planeGridOn; before coordinatePlane.
  ```
  planeGrid(false)
  coordinatePlane(-4, 4, -2, 2)
  functionGraph("sin(x)", -4, 4)
  ```
- `planeLabelOn(d, x, y, text, side, color, size)` -- A label at the point (x, y) of the coordinate plane on a named diagram, in the plane's own coordinates. On a plane drawn with a scale for y (coordinatePlaneOn's last argument) the label stands where the graph's point (x, y) is drawn; labelAtOn takes the picture's coordinates, where y must be multiplied by that scale by hand. Use it for anything named on a plane: the rule of a curve, a point, a value on an axis.
- `planeLabel(x, y, text, side, color, size)` -- Implicit-diagram version of planeLabelOn.
  ```
  coordinatePlane(-3, 3, 0, 9, 1, 3, 1/3)
  functionGraph("x^2", -3, 3)
  planeLabel(2.3, 3.6, "(2, 4)", "right")
  ```
- `unitCircleOn(d, points, angles, chords, fill)` -- The unit circle as a textbook draws it, on a named diagram, from one call: the axes with X, Y, X′, Y′ and O, the circle of radius 1 about the origin, a dot and a radius for each named point, each angle once at the centre as an arc with an arrowhead and its letter (the arcs a book repeats along the circle are not drawn), the chords between points and one filled region. It sets the diagram's ranges, so the circle is round and the names have room; call it first on its diagram. More is then drawn in the plane's own coordinates (drawOn, labelAtOn): the circle's radius is 1.
  ```
  d = diagram(560, 520)
  unitCircleOn(d, [[55, "P (a, b)"], [-55, "Q (a, −b)"], [0, "A (1, 0)"]], [[0, 55, "x"], [0, -55, "−x"]], [[1, 2]], [0, 1, 2])
  d
  ```
- `unitCircle(points, angles, chords, fill)` -- Implicit-diagram version of unitCircleOn.
  ```
  unitCircle([[55, "P (a, b)"], [-55, "Q (a, −b)"]], [[0, 55, "x"], [0, -55, "−x"]], [[1, 2]], [0, 1, 2])
  ```
- `textbookGraphOn(d, f, xmin, xmax, ymin, ymax, rule, color)` -- The graph of a function as a textbook prints it, on a named diagram, from one call: axes without a grid, named X, Y, X′ and Y′; the x-axis marked every π/2 when both its ends are fractions of π (every π when that would be more than 20 marks), otherwise in round numbers; a unit of y drawn as tall as the picture has room for; a dashed line at each vertical asymptote, also at the ends of the range; the curve; and its rule written under the plane. Call it first on its diagram. More curves, points and labels are then added with functionGraphOn, closedPointOn and planeLabelOn.
  ```
  d = diagram(560, 440)
  textbookGraphOn(d, "tan(x)", -pi, 2*pi, -3, 3, "y = tan x")
  d
  ```
- `textbookGraph(f, xmin, xmax, ymin, ymax, rule, color)` -- Implicit-diagram version of textbookGraphOn.
  ```
  textbookGraph("cosec(x)", -pi, 2*pi, -3, 3, "y = cosec x")
  ```

### Coordinate Geometry

Details: https://apasscript.com/docs/coordinate-geometry.html

- `point(x, y)` -- Constructs a 2D point.
- `line(a, b, c)` -- Constructs a 2D line in general form a*x + b*y + c = 0; line(P, Q) is the line through two points.
- `lineFromPoints(p, q)` -- Constructs the line through two points.
- `lineFromSlope(m, k)` -- Constructs the line y = m*x + k from a slope and y-intercept.
- `linePointSlope(p, m)` -- Constructs the line through a point with a given slope.
- `lineFromAngle(p, degrees)` -- Constructs an infinite line through a point at a direction in degrees.
- `lineFromIntercepts(xIntercept, yIntercept)` -- Constructs the line with given x- and y-intercepts.
- `lineVertical(k)` -- Constructs the vertical line x = k.
- `lineHorizontal(k)` -- Constructs the horizontal line y = k.
- `circle(centre, r)` -- Constructs a circle from a centre point and radius.
- `ellipse(centre, rx, ry)` -- Constructs an axis-aligned ellipse from a centre point and horizontal/vertical semi-axis lengths.
- `circleFromGeneral(g, f, c)` -- Constructs a circle from its general-form coefficients (x^2 + y^2 + 2gx + 2fy + c = 0).
- `ratios(a, b, c)` -- Constructs a 3D direction ratios value (l, m, n) -- unnormalized direction cosines.
- `midpoint(p, q)` -- The midpoint of two points.
- `sectionInternal(p, q, m, n)` -- The point dividing segment pq internally in the ratio m:n.
- `sectionExternal(p, q, m, n)` -- The point dividing segment pq externally in the ratio m:n.
- `collinear(p, q, r)` -- True if three points lie on a common line.
- `distance(a, b)` -- The distance between two values: point-point, point-line (either order), line-line (parallel only), or circle-circle (between centres).
- `intersect(a, b)` -- The intersection of two values: line-line (a point, or explanatory text if parallel/coincident) or line-circle (either order).
- `positionOf(p, x)` -- A point's position relative to a line ("above"/"on"/"below") or a circle ("inside"/"on"/"outside").
- `areParallel(a, b)` -- True if two lines, or two direction ratios, are parallel.
- `arePerpendicular(a, b)` -- True if two lines, or two direction ratios, are perpendicular.
- `angleBetweenLines(a, b)` -- The angle, in radians, between two lines, or between two direction ratios.
- `slope(l)` -- The slope of a line.
- `yIntercept(l)` -- A line's y-intercept.
- `xIntercept(l)` -- A line's x-intercept.
- `isVertical(l)` -- True if a line is vertical.
- `isHorizontal(l)` -- True if a line is horizontal.
- `areCoincident(l1, l2)` -- True if two lines are the same line.
- `footOfPerpendicular(p, l)` -- The foot of the perpendicular from a point to a line.
- `imageOfPoint(p, l)` -- The mirror image of a point reflected across a line.
- `familyThroughIntersection(l1, l2, lambda)` -- A line in the family l1 + lambda*l2 passing through the intersection of two lines.
- `parallelThrough(p, l)` -- The line through a point, parallel to a given line.
- `perpendicularThrough(p, l)` -- The line through a point, perpendicular to a given line.
- `sameSide(p, q, l)` -- True if two points lie on the same side of a line.
- `circleArea(c)` -- The area of a circle.
- `circumference(c)` -- The circumference of a circle.
- `diameter(c)` -- The diameter of a circle.
- `radiusSq(c)` -- The square of a circle's radius.
- `tangentAt(c, p)` -- The tangent line to a circle at a point on it.
- `radicalAxis(c1, c2)` -- The radical axis of two circles.
- `relativePosition(c1, c2)` -- How two circles relate to each other (e.g.
- `triangleArea(p, q, r)` -- The area of the triangle formed by three points.
- `triangleAreaSigned(p, q, r)` -- The signed area of the triangle formed by three points -- positive for counterclockwise winding, negative for clockwise.
- `isDegenerate(p, q, r)` -- True if three points are collinear (form a degenerate triangle with zero area).
- `classify(p, q, r)` -- Classifies a triangle formed by three points (e.g.
- `perimeter(p, q, r)` -- The perimeter of the triangle formed by three points.
- `centroid(p, q, r)` -- The centroid of the triangle formed by three points.
- `incentre(p, q, r)` -- The incentre of the triangle formed by three points.
- `circumcentre(p, q, r)` -- The circumcentre of the triangle formed by three points.
- `orthocentre(p, q, r)` -- The orthocentre of the triangle formed by three points.
- `eulerLine(p, q, r)` -- The Euler line of the triangle formed by three points (through the centroid, orthocentre, and circumcentre).
- `ninePointCentre(p, q, r)` -- The nine-point centre of the triangle formed by three points.
- `sideA(p, q, r)` -- The length of side a (opposite p) of the triangle formed by three points.
- `sideB(p, q, r)` -- The length of side b (opposite q) of the triangle formed by three points.
- `sideC(p, q, r)` -- The length of side c (opposite r) of the triangle formed by three points.
- `toCosines(r)` -- Converts direction ratios to direction cosines, as a 3-element array.
- `ratioDot(r1, r2)` -- The dot product of two direction ratios.
- `ratioMagSq(r)` -- The squared magnitude of a direction ratios value.
- `generalForm(c)` -- g, f, c of a circle written as x^2 + y^2 + 2gx + 2fy + c = 0.

### Vectors

Details: https://apasscript.com/docs/vectors.html

- `vec(x, y, z)` -- Constructs a 2D vector from vec(x, y), or a 3D vector from vec(x, y, z) -- dispatches on argument count.
- `add(a, b)` -- Adds two vectors of the same dimension (both 2D or both 3D).
- `sub(a, b)` -- Subtracts b from a, for two vectors of the same dimension.
- `scale(v, s)` -- Multiplies a vector by a scalar.
- `neg(v)` -- Negates a vector, reversing its direction.
- `normalize(v)` -- Scales a vector to unit length, keeping its direction.
- `rotate(v, theta)` -- Rotates a 2D vector by an angle, in radians.
- `dot(a, b)` -- The dot product of two vectors of the same dimension.
- `mag(v)` -- The magnitude (length) of a vector.
- `cross(a, b)` -- The cross product of two vectors of the same dimension -- a scalar (the z-component) for two 2D vectors, a vector for two 3D vectors.
- `angle(v)` -- The angle, in radians, a 2D vector makes with the x-axis.
- `angleBetween(a, b)` -- The angle, in radians, between two vectors of the same dimension.
- `projScalar(a, b)` -- The scalar projection of a onto b -- the length of a's component along b.
- `projVector(a, b)` -- The vector projection of a onto b -- a's component along b, as a vector.
- `reject(a, b)` -- The vector rejection of a from b -- a's component perpendicular to b.
- `scalarTriple(a, b, c)` -- The scalar triple product a .
- `vectorTriple(a, b, c)` -- The vector triple product a x (b x c), for three 3D vectors.

### Colors

Details: https://apasscript.com/docs/colors.html

- `rgb(r, g, b)` -- A colour from red, green and blue channels, each 0-255 (out-of-range values are clamped).
- `rgba(r, g, b, a)` -- rgb() with an opacity a from 0 (transparent) to 1 (opaque); the result is "#rrggbbaa".
- `hsl(h, s, l)` -- A colour from hue (degrees round the colour wheel: 0 red, 120 green, 240 blue), saturation and lightness (both in percent, 0-100) -- CSS hsl(h, s%, l%).
- `hsla(h, s, l, a)` -- hsl() with an opacity a from 0 to 1.
- `mix(c1, c2, t)` -- The colour t of the way from c1 (t = 0) to c2 (t = 1), mixed in sRGB like CSS color-mix().
- `lighter(c, p)` -- The colour with its HSL lightness raised by p percentage points.
- `darker(c, p)` -- The colour with its HSL lightness lowered by p percentage points.
- `withAlpha(c, a)` -- The same colour with opacity a (0 transparent, 1 opaque).
- `rainbow(n)` -- A list of n evenly spaced hues (full saturation, lightness 50%), starting at red.

### Transformations

Details: https://apasscript.com/docs/transformations.html

- `translate(shape, dx, dy)` -- Moves a shape by (dx, dy), or by a vector.
- `rotate(shape, degrees, centre)` -- Turns a shape counter-clockwise by an angle in DEGREES, about the origin or a given centre -- exact for quarter turns and, where the point allows, 30/45/60 degrees.
- `scale(shape, k, centre)` -- Enlarges a shape by a scale factor k about the origin or a centre, or by kx across and ky up (a negative factor also turns it round).
- `reflect(shape, mirror)` -- Reflects a shape in a line, in a point, or in a named mirror: "x-axis", "y-axis", "y=x", "y=-x", "origin".
- `shear(shape, kx, ky)` -- Shears a shape: x' = x + kx*y, y' = y + ky*x.

### 3d Surfaces

Details: https://apasscript.com/docs/3d-surfaces.html

- `surf(expr, xmin, xmax, ymin, ymax, nx, ny, colormap)` -- Samples z = f(x, y) on the CPU into a filled, colormap-shaded 3D surface, rendered live in the browser via WebGL2 (works in any WebGL2-capable browser, unlike webgpu-shaders' surface3d()).
- `mesh(expr, xmin, xmax, ymin, ymax, nx, ny, colormap)` -- Same sampling as surf(), rendered as a colormap-colored wireframe only (no filled faces) -- matches MATLAB's own mesh().
- `surfc(expr, xmin, xmax, ymin, ymax, nx, ny, colormap)` -- surf() plus a set of contour lines projected onto the floor of the plot (the z = z_min plane) -- matches MATLAB's own surfc().
- `contour3(expr, xmin, xmax, ymin, ymax, numLevels, nx, ny)` -- Draws only the iso-lines of z = f(x, y) at numLevels evenly spaced heights, each drawn at its own height on the surface (not projected to the floor) -- matches MATLAB's own contour3().

### Animation

Details: https://apasscript.com/docs/animation.html

- `animate(tmin, tmax, n, f)` -- An animation: calls f(t) for n values of t from tmin to tmax, each call drawing one frame with draw()/text()/...
- `sketch(n, setup, draw, fps)` -- Frame-by-frame animation with memory, like Processing: setup() runs once -- what it draws is the background of every frame, and what it returns is the starting state -- then draw(i, state) draws frame i (0 to n-1) and returns the next state.

### Interaction

Details: https://apasscript.com/docs/interaction.html

- `slider(label, min, max, step, default)` -- A number the reader can change with a slider: from min to max in steps of step, starting at default.
- `checkbox(label, default)` -- true or false, as a checkbox the reader can tick; changing it runs the script again.
- `colorPicker(label, default)` -- A colour the reader can pick; changing it runs the script again.