Getting Started

pathogen-lang is a language that extends SVG path syntax with variables, expressions, control flow, and functions. It compiles to standard SVG path data that works in any browser or graphics application.

Your First Path

Try this simple example in the playground:

define ViewBox(0, 0, 200, 200);
define default PathLayer('main-path-layer') ${
  fill: #bbb;
  stroke: #222;
  stroke-width: 1;
};

// A simple rectangle using variables
let size = 50
let x = 10
let y = 10

M x y
h size
v size
h calc(-size)
Z

Every Pathogen program starts with a define ViewBox declaring the canvas, and typically one or more layer definitions describing how strokes and fills should look.

This creates a rectangle by:

1. Moving to position (10, 10)
2. Drawing a horizontal line of length 50
3. Drawing a vertical line of length 50
4. Drawing a horizontal line back
5. Closing the path

Why pathogen-lang?

SVG paths are powerful but writing them by hand is tedious:

// Standard SVG - repetitive coordinates
M 20 20 L 80 20 L 80 80 L 20 80 Z
M 100 20 L 160 20 L 160 80 L 100 80 Z
M 180 20 L 240 20 L 240 80 L 180 80 Z

With pathogen-lang, you can use variables and loops:

// pathogen-lang - DRY and readable
let size = 60
for (i in 0..3) {
  rect(calc(20 + i * 80), 20, size, size)
}

Key Features

Variables

Store and reuse values:

let width = 200
let height = 100
let centerX = calc(width / 2)

Expressions with calc()

Use math in path commands:

let r = 50
M calc(100 - r) 100
L calc(100 + r) 100

Loops

Repeat patterns easily:

for (i in 0..10) {
  circle(calc(20 + i * 30), 100, 10)
}

Functions

Define reusable shapes:

fn square(x, y, size) {
  rect(x, y, size, size)
}

square(10, 10, 50)
square(70, 10, 50)

Built-in Shapes

Common shapes are included:

circle(100, 100, 50)
rect(10, 10, 80, 60)
polygon(100, 100, 40, 6)  // hexagon
star(100, 100, 50, 25, 5)

Next Steps

• Syntax Reference - Learn all the language features
• Standard Library - Explore built-in functions
• Examples - See practical patterns and recipes

Syntax Reference

pathogen-lang is a superset of SVG path syntax that adds variables, expressions, control flow, functions, and path blocks.

Path Commands

All standard SVG path commands are supported:

Uppercase commands use absolute coordinates; lowercase use relative coordinates.

M 0 0 L 100 100 Z

Variables

Declare variables with let:

let width = 200;
let height = 100;
let centerX = 100;

Use variables directly in path commands:

let x = 50;
let y = 75;
M x y L 100 100

Two naming rules:

• pi, deg, and rad are reserved. They are angle unit suffixes, and only that: let pi = …, fn deg(…) { }, or using one as a loop or function parameter is a compile error, and referencing one standalone (calc(pi)) errors with a pointer at the forms that do exist — the suffix (0.5pi, 90deg, 1.5rad) and the standard-library calls (PI(), deg(x) / rad(x)), which remain untouched.
• Single letters that are path commands (m l h v c s q t a z, either case) can be declared, but cannot be referenced bare in path-argument position — there they always read as commands. let m = 25; L m 40 is a compile error naming this rule; L calc(m) 40 works. Prefer longer names.

Strings and Template Literals

String values use double quotes:

let name = "World";

Template literals use backticks with ${expression} interpolation:

let greeting = `Hello ${name}!`;          // "Hello World!"
let msg = `Score: ${2 + 3}`;             // "Score: 5"
let pos = `(${ctx.position.x}, ${ctx.position.y})`;
let word = `${n > 1 ? 'pieces' : 'piece'}`;   // any expression works,
                                              // ternaries included

Template literals are the sole string construction mechanism — the + operator stays strictly numeric. String equality works with == and !=:

let mode = "dark";
if (mode == "dark") { /* ... */ }
if (mode != "light") { /* ... */ }

.length

Returns the number of characters in the string:

let str = `Hello`;
log(str.length);  // 5

.empty()

Returns 1 (truthy) if the string has no characters, 0 (falsy) otherwise:

let str = ``;
if (str.empty()) {
  // string is empty
}

Index Access

Access individual characters by zero-based index using [expr]:

let str = `Hello`;
let first = str[0];   // "H"
let last = str[4];     // "o"

Out-of-bounds access throws an error.

.split()

Splits a string into an array of individual characters:

let str = `abc`;
let chars = str.split();  // ["a", "b", "c"]
for (ch in chars) {
  log(ch);
}

.append(value)

Returns a new string with the given value appended to the end:

let str = `Hello`;
let result = str.append(` World`);  // "Hello World"

.prepend(value)

Returns a new string with the given value prepended to the beginning:

let str = `World`;
let result = str.prepend(`Hello `);  // "Hello World"

.includes(substring)

Returns 1 (truthy) if the string contains the given substring, 0 (falsy) otherwise:

let str = `Hello World`;
if (str.includes(`World`)) {
  // found it
}

.slice(start, end)

Returns a substring from start (inclusive) to end (exclusive). Negative indices count from the end:

let str = `Hello World`;
let sub = str.slice(0, 5);    // "Hello"
let end = str.slice(6, 11);   // "World"
let last3 = str.slice(-3, 11); // "rld"

Color Literals

Hex color codes and CSS color functions are first-class expressions:

let c = #cc0000;                      // 6-digit hex
let c = #f00;                         // 3-digit shorthand
let c = #cc000080;                    // 8-digit with alpha
let c = rgb(255, 0, 0);              // CSS color function
let c = hsl(0, 100%, 50%);           // % is literal inside parens
let c = oklch(0.6 0.15 30);          // any CSS color space
let lighter = (#cc0000).lighten(20%); // method chaining via parens

See the Color documentation for full details.

Percent Suffix

The % suffix converts a number to a fraction: 50% becomes 0.5.

let half = 50%;          // 0.5
let third = 33.3%;       // 0.333
let c = (#ff0000).lighten(20%);  // lighten by 0.2

Disambiguation: 20% (no space) is a percent literal (= 0.2). 20 % 5 (with spaces) is the modulus operator (= 0).

Expressions with calc()

For mathematical expressions, wrap them in calc():

let r = 50;
M calc(100 - r) 100
L calc(100 + r) 100

calc() computes on values. Percent suffixes are converted at the literal (20% → 0.2), so they always produce plain numbers. Angle suffixes (deg, rad, pi) are different: an angle-suffixed literal produces an Angle value, and calc() arithmetic keeps angle-ness where it makes sense — scaling an angle by a plain number is still an angle, a ratio of two angles is a plain number. An angle is an angle wherever it flows: it survives being stored in a variable, put in an array, or passed through a function. See Angle Units.

Separately, the compiler still reads the expression as written to reject nonsense at compile time, like calc(0.25pi + 5) — see the mismatch rules under Angle Units.

Supported Operators

Operator precedence follows standard mathematical conventions.

Conditional (Ternary) Expressions

cond ? a : b evaluates to a when the condition is truthy, b otherwise — and the branches can be any values, strings included:

let count = 2;
let label = count > 1 ? 'pieces' : 'piece';

// Works inside template interpolation…
let caption = `${count} ${count > 1 ? 'pieces' : 'piece'} total`;

// …and inside style-block values:
let hot = PathLayer('mark') ${ stroke-width: count > 1 ? 4 : 1; };

Ternaries also work inside a path argument's calc() — L calc(count > 1 ? 40 : 10) 0.

The alternative to a ternary is plain reassignment — variables are mutable, and reassigning inside an if branch is the natural spelling when the choice takes more than one expression:

let tone = 'cool';
if (temperature > 30) {
  tone = 'warm';
}

Style Blocks

Style blocks are CSS-like key-value maps wrapped in ${ }. They're used for layer styles but are also first-class values — you can store them in variables, merge them, and read their properties.

Literals

let styles = ${
  stroke: #cc0000;
  stroke-width: 3;
  fill: none;
};

Each property is a name: value; declaration. The trailing ; is required on every declaration, including the last one before } — a declaration missing its ; is a compile error. Values are try-evaluated as expressions — if the value parses as a valid expression (like a variable reference, backtick template literal, arithmetic, a ternary, a function call, or calc()), its result is used. Otherwise the raw string is kept (e.g., rgb(...), #hex). See Variables and Interpolation in Values for dynamic values.

CSS Function Values

Style-block values are native CSS syntax, not Pathogen call syntax. This matters for CSS functions whose grammar is space-separated — the CSS filter functions (blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, opacity, saturate, sepia) take space-separated arguments, and commas inside them are a compile error:

// ✗ Compile error — Pathogen-style commas are not valid CSS here
filter: drop-shadow(4px, 4px, 4px, shadowColor);
// drop-shadow() uses space-separated CSS syntax:
// drop-shadow(4px 4px 4px color) — remove the commas

// ✓ Native CSS syntax — space-separated
filter: drop-shadow(4px 4px 4px shadowColor);

Filter chains are also space-separated: filter: blur(2px) brightness(1.2); — a comma between chained filter functions is likewise a compile error.

Functions whose CSS grammar genuinely uses commas keep them, exactly as in CSS: rgba(0, 0, 0, 0.5), color-mix(in oklch, red, blue), translate(10px, 20px), cubic-bezier(0.4, 0, 0.2, 1), polygon(0 0, 100% 0, 50% 100%), and font-family fallback lists.

Pathogen variables still work anywhere inside a CSS function value — drop-shadow(4px 4px 4px shadowColor) resolves shadowColor to its CSS color at compile time, and a numeric variable substitutes as a bare number (brightness(level) → brightness(1.4)). Substitution is not unit-aware, and the compiler checks the result — arguments that need a unit want a template fragment instead: blur(`${softness}`px). See Argument Units below and Variables and Interpolation in Values.

Argument Units

CSS is strict about units per function, and a wrong one makes the browser drop the whole declaration silently. Pathogen checks the final value — after any variable substitution or interpolation — and fails with a fix-it message instead:

The table above is the complete list of checked functions. Any CSS function not listed — including rotate, translate, skew, perspective, the color functions, and path() — passes through unchecked.

filter: blur(4);              // ✗ blur() takes a length — "4" needs a unit (try 4px)
filter: blur(4px);            // ✓
filter: hue-rotate(90);       // ✗ hue-rotate() takes an angle — "90" needs a unit (try 90deg)
filter: hue-rotate(90deg);    // ✓
filter: opacity(50%);         // ✓ percentages are fine for filter amounts
transform: scale(2px);        // ✗ scale() takes plain numbers — "2px" must not have a unit
transform: scale(0.5);        // ✓

let softness = 4;
filter: blur(softness);       // ✗ substituted values are checked the same way
filter: blur(`${softness}`px); // ✓

Zero is always allowed bare — blur(0) and polygon(0 0, 100% 0, 50% 100%) are valid CSS and pass unchanged.

Why Some Functions Are Unchecked

Pathogen checks a function's units only where CSS and SVG agree on the right answer.

Color functions (oklch, rgb, color-mix, …) accept numbers, percentages, and angles interchangeably depending on the channel, so there is no single rule to enforce — they are left alone.

Most transform functions are emitted into SVG's transform attribute, whose grammar takes unitless user units. transform: rotate(45) and translate(100, 200) are correct there and are exactly what Pathogen's own transform convenience properties generate, while the CSS grammar for the same functions requires units. Because the two grammars disagree, Pathogen accepts both forms and checks neither — translate(10px, 20px) is accepted too.

scale* and matrix* are the exception, which is why they appear in the table. A unit is invalid in both grammars — SVG's is scale(<number>) and matrix(<number>×6) — so there is one correct answer and Pathogen enforces it.

Functions Must Match the Property

A function also has to belong to the property it is used on — fill: rotate(45); is a compile error, since a transform function means nothing to fill:

fill: rotate(45);             // ✗ rotate() is not valid on "fill" — that property takes color functions
fill: oklch(0.7 0.15 240);    // ✓
clip-path: blur(4px);         // ✗ blur() is not valid on "clip-path" — that property takes basic shapes
clip-path: circle(50%);       // ✓

The mapping is:

Any property not in this table accepts any allow-listed function. Nesting is unaffected: drop-shadow(4px 4px 8px oklch(0.65 0.26 357)) is fine, because only the outermost function is matched against the property.

Merge (<<)

The << operator merges two values of the same type. The right side overrides the left on key conflicts:

// Style blocks
let base = ${ stroke: red; stroke-width: 2; };
let merged = base << ${ stroke-width: 4; fill: blue; };
// Result: stroke: red, stroke-width: 4, fill: blue

// Objects
let a = { x: 1, y: 2 };
let b = a << { y: 99, z: 3 };
// Result: {x: 1, y: 99, z: 3}

Multiple merges can be chained: a << b << c. See also Objects — Merging.

Applying workers (<<)

<< has a second job: it applies a worker function to a callback builtin. The parentheses parameterize the call; << supplies the function that does the work. (The shape rhymes with PathLayer('name') << styles — though that one is mechanically a merge, the reading "feed the right side into the left" is the same.)

let doubler = {|v| return calc(v * 2); };
let doubled = [1, 2, 3].map() << doubler;

let cells = Grid(4, 4, { xDim: 25, yDim: 25 });
cells.fill() << {|row, col| return calc(row * 4 + col); };

let total = [1, 2, 3].reduce(0) << {|acc, v| return calc(acc + v); };

let spine = @{ l 120 0 };
let ribbon = spine.variableOffset() << {|go, pb|
  go.stop(0, 4, CurveContinuity.G1);
  go.stop(1, 12, CurveContinuity.G1);
};

The rule is structural: when the left side is one of the nine callback builtins — array .map/.filter/.reduce/.sort, Grid.fill/.forEach/.map, variableOffset/compoundVariableOffset — written without a trailing block, << provides its callback. The right side may be a lambda variable, a named fn, or a lambda literal. Anywhere else, << is the ordinary merge above.

Evaluation order: the receiver, then the parenthesized arguments (e.g. reduce's initial value), then the worker expression, then the iteration.

A few consequences of the structural rule:

• A trailing block and a << worker are mutually exclusive. If the call already carries a literal block, << falls back to merge — so spine.variableOffset() {|go, pb| ... } << edge still means "build the offset, then concatenate the edge path block", exactly as before. (And arr.map {|v| ... } << f errors: the block completed the call, and a function is not a mergeable value.)
• Application happens once. arr.map() << f << g applies f, and the second << then sees an array on its left — already a value, so the error says exactly that. Apply then merge is fine when the types line up: spine.compoundVariableOffset() << mk << tail builds the ribbon and concatenates tail.
• Passing the worker inside the parentheses (map(f)) is not supported — the error message points you to <<.

Property Access

Use dot notation with camelCase names to read kebab-case properties:

let s = ${ stroke-width: 4; };
let sw = s.strokeWidth;  // "4" (reads 'stroke-width')

Property values are always strings.

Usage in Layers

Style blocks are used in layer definitions and can be passed as per-element styles on text() and tspan(). See Layers for full details.

Null

The null literal represents the absence of a value. It is returned by .pop() and .shift(), and by the .first and .last properties, on empty arrays, and can be used in variable assignments and conditionals.

let x = null;

Truthiness

null is falsy in conditionals:

let x = null;
if (x) {
  // not reached
} else {
  M 0 0  // this branch runs
}

Equality

null is only equal to itself:

if (x == null) { /* x is null */ }
if (x != null) { /* x has a value */ }

null == 0 evaluates to 0 (false) — null is distinct from zero.

Error Behavior

Using null in arithmetic or as a path argument throws a descriptive error:

let x = null;
let y = x + 1;     // Error: Cannot use null in arithmetic expression
M x 0               // Error: Cannot use null as a path argument

Booleans

The true and false keywords represent boolean values. They are a semantic subtype of number — true is 1, false is 0 — but display as true/false in logs and template literals.

let flag = true;
let check = false;

Numeric Equivalence

Booleans participate in arithmetic as their numeric values:

true + 1     // 2
true + true  // 2
false + 1    // 1
true == 1    // true
false == 0   // true

Display

Booleans display as true or false, and comparisons return booleans:

log(true);       // true
log(5 > 3);      // true
log(1 > 5);      // false
log(`${true}`);  // true

Truthiness

false is falsy (like 0 and null); true is truthy:

if (true) { /* runs */ }
if (false) { /* skipped */ }

let result = 5 > 3;  // true (BooleanValue)
if (result) { /* runs */ }

Logical Operators

!true         // false
!false        // true
true && false // false
false || true // true

Arc Flags

Booleans can be used directly as arc flag arguments, converting to 1/0 in the SVG output:

let largeArc = true;
let sweep = false;
M 0 0 A 50 50 0 largeArc sweep 100 0
// → M 0 0 A 50 50 0 1 0 100 0

Enums

Built-in Enums

Pathogen provides built-in enums for gradient and geometry properties. Enum members resolve to the string values accepted by these properties:

topo.easing = Easing.Smoothstep;       // equivalent to 'smoothstep'
grad.interpolation = Interpolation.OKLCH;

Enum values are interchangeable with their string equivalents:

Easing.Linear == 'linear'  // true

The Easing curves are also callable as stdlib functions (easeIn, easeOut, easeInOut, smoothstep) — the formulas and the enum↔function mapping are documented in the stdlib's Easing section.

User-Defined Enums

Define custom enums with enum:

// Auto-valued — member name lowercased to a string
enum Symmetry { None, Bilateral, Radial, Rotational }
log(Symmetry.Bilateral);  // bilateral

// Explicit string values
enum Season { Spring = 'vernal', Summer = 'estival' }

// Explicit typed values — number, angle, color, boolean
enum Turn { Quarter = 90deg, Half = 180deg, Full = 360deg }
enum Palette { Primary = #0066ff, Accent = #ff6600, Muted = #999 }
enum Weight { Thin = 1, Normal = 2, Bold = 4 }
enum Toggle { On = true, Off = false }

Auto-valued members always produce the lowercase string of the member name. Other types require an explicit = value.

Enum members are accessed with dot notation and can be used in conditionals:

let d = Dir.Up;
if (d == 'up') { M 10 20 }

Points

Points represent 2D coordinates and provide geometric operations for SVG path construction.

Constructor

Create a point with Point(x, y):

let center = Point(200, 200);
let origin = Point(0, 0);

Properties

let pt = Point(100, 200);
M pt.x pt.y           // M 100 200
L calc(pt.x + 10) pt.y  // L 110 200

Methods

All angles are in radians, consistent with the standard library. Angle values are accepted anywhere an angle goes in (.rotate(90deg, c)); angles that come out (.angleTo()) are plain numbers in radians.

.translate(dx, dy)

Returns a new point offset by the given deltas:

let pt = Point(100, 100);
let moved = pt.translate(10, -20);  // Point(110, 80)

.polarTranslate(angle, distance)

Returns a new point offset by angle and distance:

let pt = Point(100, 100);
let moved = pt.polarTranslate(0, 50);     // Point(150, 100)
let up = pt.polarTranslate(-0.5pi, 30);   // 30 units upward

.midpoint(other)

Returns the midpoint between two points:

let a = Point(0, 0);
let b = Point(100, 100);
let mid = a.midpoint(b);  // Point(50, 50)

.lerp(other, t)

Linear interpolation between two points. t=0 returns this point, t=1 returns the other:

let a = Point(0, 0);
let b = Point(100, 200);
let quarter = a.lerp(b, 0.25);  // Point(25, 50)

.rotate(angle, origin)

Rotates this point around a center point:

let pt = Point(100, 0);
let center = Point(0, 0);
let rotated = pt.rotate(90deg, center);  // Point(0, 100) approximately

.distanceTo(other)

Returns the Euclidean distance between two points:

let a = Point(0, 0);
let b = Point(3, 4);
log(a.distanceTo(b));  // 5

.angleTo(other)

Returns the angle in radians from this point to another:

let a = Point(0, 0);
let b = Point(1, 0);
log(a.angleTo(b));  // 0 (pointing right)

.offset(other)

Returns an object with dx and dy properties representing the vector from this point to other. Useful for applying the same relative displacement to multiple points:

let ref = Point(200, 200);
let target = Point(100, 300);
let off = ref.offset(target);
// off.dx = -100, off.dy = 100

// Apply the same offset to a different point
let other = Point(50, 75);
M calc(other.x + off.dx) calc(other.y + off.dy)

Display

log() shows points in a readable format:

let pt = Point(100, 200);
log(pt);  // Point(100, 200)

Template Literals

Points display as Point(x, y) when interpolated in template literals:

let pt = Point(42, 99);
let msg = `position: ${pt}`;  // "position: Point(42, 99)"

Arrays

Arrays hold ordered collections of values. Elements can be numbers, strings, style blocks, other arrays, or null.

Literals

let empty = [];
let nums = [1, 2, 3];
let mixed = [10, "hello", [4, 5]];

Spread (...)

Use the spread operator to expand an array's elements into another array literal:

let a = [1, 2, 3];
let b = [0, ...a, 4, 5];     // [0, 1, 2, 3, 4, 5]
let c = [...a, ...b];         // combine two arrays

Spread works anywhere inside an array literal and can be mixed with regular elements:

let head = [10, 20];
let tail = [40, 50];
let full = [...head, 30, ...tail];  // [10, 20, 30, 40, 50]

Index Access

Access elements by zero-based index using [expr]:

let list = [10, 20, 30];
let first = list[0];         // 10
let second = list[1];        // 20
M list[0] list[1]            // M 10 20

Out-of-bounds access throws an error.

.length

Returns the number of elements:

let list = [1, 2, 3];
log(list.length);  // 3

.first

Returns the first element, or null if the array is empty (see Null) — unlike list[0], which throws when the array is empty. The array is not modified (unlike .shift(), which removes the element it returns).

let list = [10, 20, 30];
log(list.first);   // 10

let empty = [];
log(empty.first);  // null

Note: If the first element is itself null, the result is indistinguishable from the empty-array case (the same is true of .last, .pop(), and .shift()). Check .length when the distinction matters.

.last

Returns the last element, or null if the array is empty (see Null) — unlike list[list.length - 1], which throws when the array is empty. The array is not modified (unlike .pop(), which removes the element it returns). The empty-vs-null-element ambiguity noted under .first applies here too.

let list = [10, 20, 30];
log(list.last);    // 30

let empty = [];
log(empty.last);   // null

.empty()

Returns 1 (truthy) if the array has no elements, 0 (falsy) otherwise:

let list = [];
if (list.empty()) {
  // list is empty
}

Methods

The four mutating methods — .push(), .pop(), .unshift(), and .shift() — throw if called while the array is being iterated (see Reference Semantics).

.push(value)

Appends a value to the end. Returns the new length.

let list = [1, 2];
let len = list.push(3);  // list is now [1, 2, 3], len is 3

.pop()

Removes and returns the last element. Returns null if the array is empty.

let list = [1, 2, 3];
let last = list.pop();   // last is 3, list is now [1, 2]
let empty = [];
let x = empty.pop();     // x is null

.unshift(value)

Prepends a value to the start. Returns the new length.

let list = [2, 3];
list.unshift(1);  // list is now [1, 2, 3]

.shift()

Removes and returns the first element. Returns null if the array is empty.

let list = [1, 2, 3];
let first = list.shift();  // first is 1, list is now [2, 3]

.slice(start, end?)

Returns a new array containing elements from start to end (inclusive). Negative indexes count from the end. If end is omitted, returns from start to the end of the array.

Note: Array .slice() uses inclusive end indexes, while string .slice() uses exclusive end indexes (matching JavaScript string behavior).

let arr = [10, 20, 30, 40, 50];

let mid = arr.slice(1, 3);    // [20, 30, 40] — indices 1, 2, 3
let tail = arr.slice(3);      // [40, 50]     — from index 3 to end
let last2 = arr.slice(-2);    // [40, 50]     — last 2 elements
let head = arr.slice(0, -2);  // [10, 20, 30, 40] — up to second-to-last

.map {|item| ... } / .map {|item, index, arrayRef| ... }

Transforms each element using a trailing block, returning a new array. Use return to specify the mapped value. If no return is executed, the element maps to null. A reusable worker applies with << — prices.map() << f; (see Applying workers).

The block receives up to three parameters:

• item — the current element
• index (optional) — the zero-based index
• arrayRef (optional) — a reference to the original array (reading is fine; mutating it throws — see Reference Semantics)

let prices = [10, 25, 50];
let doubled = prices.map {|price|
  return calc(price * 2);
};
// doubled is [20, 50, 100]

// Block body supports full language features
let labels = [1, 2, 3].map {|n|
  let prefix = `item-`;
  return `${prefix}${n}`;
};
// labels is ["item-1", "item-2", "item-3"]

Use the index parameter for position-aware transforms:

let items = [10, 20, 30];
let indexed = items.map {|val, i|
  return calc(val + i);
};
// indexed is [10, 21, 32]

Use the array reference for look-ahead or look-behind:

let arr = [1, 2, 3, 4];
let pairs = arr.map {|item, idx, ref|
  if (idx < ref.length - 1) {
    return calc(item + ref[idx + 1]);
  }
  return item;
};
// pairs is [3, 5, 7, 4]

The block has access to variables from the enclosing scope:

let offset = 100;
let shifted = [1, 2, 3].map {|x|
  return calc(x + offset);
};
// shifted is [101, 102, 103]

.filter {|item| ... } / .filter {|item, index, arrayRef| ... }

Returns a new array containing only the elements for which the trailing block returns a truthy value. Filtering is how you keep only the points inside a region, drop whitespace glyphs before layout, or cull segments below a size threshold before drawing.

null, 0, and false are falsy; non-zero numbers, true, and non-empty strings are truthy (see Null and Booleans). The original array is not modified. If no return is executed, the block produces null, which is falsy — the element is dropped. A reusable worker applies with << — nums.filter() << isPositive; (see Applying workers).

The block receives up to three parameters:

• item — the current element
• index (optional) — the zero-based index
• arrayRef (optional) — a reference to the original array (reading is fine; mutating it throws — see Reference Semantics)

let nums = [4, -2, 7, 0, -5];
let positive = nums.filter {|n|
  return n > 0;
};
// positive is [4, 7]
// nums is still [4, -2, 7, 0, -5]

Use the index parameter for position-aware filtering:

let items = [10, 20, 30, 40];
let evens = items.filter {|val, i|
  return calc(i % 2) == 0;
};
// evens is [10, 30] — elements at even indexes

Use the array reference to compare against neighbors:

let arr = [1, 5, 3, 8, 2];
let rising = arr.filter {|item, idx, ref|
  if (idx == 0) { return true; }
  return item > ref[idx - 1];
};
// rising is [1, 5, 8] — elements greater than their predecessor

.reduce(initialValue) {|accumulator, item, index, arrayRef| ... }

Iterates the array, threading an accumulator through each step. The initialValue argument sets the starting accumulator. The block must return the new accumulator value; if no return is executed, the accumulator becomes null.

The block receives up to four parameters:

• accumulator — the current accumulated value
• item (optional) — the current element
• index (optional) — the zero-based index
• arrayRef (optional) — a reference to the original array (reading is fine; mutating it throws — see Reference Semantics)

let sum = [1, 2, 3, 4].reduce(0) {|acc, n|
  return calc(acc + n);
};
// sum is 10

let csv = ['a', 'b', 'c'].reduce('') {|acc, s, i|
  if (i == 0) { return s; }
  return `${acc},${s}`;
};
// csv is "a,b,c"

On an empty array, reduce returns initialValue unchanged:

let result = [].reduce(42) {|acc, n| return calc(acc + n); };
// result is 42

A reusable worker applies with << — the initial value stays in the parentheses: values.reduce(0) << sumFn; (see Applying workers).

.mapSlice(length)

Returns a new array where each element is a sub-array (slice) of length elements starting at that element's index. Near the end of the array, slices are shorter as they extend past the bounds.

let arr = [1, 2, 3, 4];
let slices = arr.mapSlice(2);
// slices is [[1, 2], [2, 3], [3, 4], [4]]

let triples = [10, 20, 30, 40, 50].mapSlice(3);
// triples is [[10, 20, 30], [20, 30, 40], [30, 40, 50], [40, 50], [50]]

.reverse()

Returns a new array with the elements in reverse order. The original array is not modified.

let arr = [1, 2, 3];
let rev = arr.reverse();
// rev is [3, 2, 1]
// arr is still [1, 2, 3]

.sort() / .sort {|a, b| ... }

Returns a new array with the elements sorted. Sorting is how you z-order shapes by area, order gradient stops by offset, or arrange points by angle before drawing.

Note: Unlike JavaScript, .sort() and .reverse() do not sort or reverse in place — they return new arrays and leave the original untouched. Of the array methods, .push(), .pop(), .unshift(), and .shift() mutate the array; .slice(), .map(), .filter(), .mapSlice(), .reverse(), and .sort() return copies. The mutating methods throw while the array is being iterated — see Reference Semantics for the iteration lock and why the mutate-vs-copy distinction matters when an array has more than one binding.

Called without a block, .sort() sorts in natural ascending order — numbers sort numerically, strings by character code order:

let source = [10, 2, -1];
let nums = source.sort();
// nums is [-1, 2, 10] — numeric, not lexicographic
// source is still [10, 2, -1]

let names = ["cherry", "apple", "banana"].sort();
// names is ["apple", "banana", "cherry"]

String order compares character codes, not locale rules — uppercase letters sort before lowercase, and digits before letters:

let mixed = ["apple", "Banana"].sort();
// mixed is ["Banana", "apple"] — "B" (66) precedes "a" (97)

For locale-aware or any other custom ordering, supply a comparator block.

The natural order is only defined when every element is a number, or every element is a string. Sorting anything else without a comparator — Points, Colors, null, or mixed types — is an error:

let mixed = [1, "two", Point(0, 0)];
let bad = mixed.sort();
// Error: sort() without a comparator requires all-number or all-string
// elements — use sort {|a, b| return ...; } to define the order

NaN has no defined order, so a numeric array containing NaN is also an error. An empty array sorts to an empty array. A single-element array of an unsortable type still errors — the element check does not depend on the array's size.

For custom ordering, supply a comparator as a trailing block or apply one with << (values.sort() << cmp — see Applying workers). .sort() takes no parenthesized arguments:

let points = [Point(30, 0), Point(10, 0), Point(20, 0)];
let byX = points.sort {|a, b|
  return calc(a.x - b.x);
};
// byX is [Point(10, 0), Point(20, 0), Point(30, 0)]

The comparator block receives exactly two parameters — unlike .map and .reduce, there is no index or array reference:

• a — the first element being compared
• b — the second element being compared

The block must return a number:

• negative — a sorts before b
• positive — b sorts before a
• zero — keep the original relative order

The sort is stable: elements that compare equal keep their original relative order.

Note: The comparator must return a number — a comparison operator will not do. return a < b; can only produce two outcomes, but a comparator needs three: a first, b first, or equal. Subtract instead: return calc(a - b);

Returning anything other than a number (including NaN) raises: sort() comparator must return a number (negative = a first, positive = b first, zero = keep order) — e.g. return calc(a - b);

let descending = [3, 1, 2].sort {|a, b|
  return calc(b - a);
};
// descending is [3, 2, 1]

The comparator can read variables from the enclosing scope, but any path commands it emits are discarded — a comparator is for ordering only. The array being sorted is locked while comparators run: mutating it from inside the block is an error (see Reference Semantics).

Reference Semantics

Arrays are passed by reference. Mutations through one binding are visible through all others:

let a = [1, 2, 3];
let b = a;
b.push(4);
log(a.length);  // 4 — same underlying array

Iteration Lock

Because every binding — including the arrayRef parameter that .map, .filter, and .reduce pass to their blocks — refers to the same array, an array is read-only while it is being iterated. Calling .push(), .pop(), .shift(), or .unshift() on it, or assigning to an element (arr[i] = x), from inside a .map/.filter/.reduce/.sort block or a for (item in arr) body is an error:

let nums = [1, 2, 3];
let bad = nums.filter {|n, i, ref|
  ref.push(99);  // Error!
  return n > 1;
};

Cannot call push() on an array while it is being iterated — callbacks and for-each bodies receive the array read-only. Iterate a copy with .slice(0) if you need to mutate.

Assigning to an element raises the same guidance: Cannot assign to an element of an array while it is being iterated — ...

The lock belongs to the array value, not to the syntax you wrote: it is held until every in-progress iteration of that array finishes, it applies equally to callbacks applied with << workers, and a mutation throws wherever it happens — including inside a helper fn called from the loop body. Reading is always fine — nested iteration of the same array is legal (the lock stacks) — and so is mutating a different array (building a result array inside a callback is the normal pattern). Unlike JavaScript — where map/filter capture the length up front so appended elements are silently never visited, and for...of or index loops can skip or revisit elements after a shift/unshift — Pathogen fails loudly. If you need to append while walking an array, iterate a snapshot:

let queue = [1, 2, 3];
for (item in queue.slice(0)) {
  queue.push(calc(item * 10));  // fine — the loop iterates the copy
}
// queue is [1, 2, 3, 10, 20, 30]
// The loop ran three times: appended elements belong to queue,
// not the snapshot, so they are never visited.

For-Each Iteration

Iterate over array elements with for (item in list):

let points = [10, 20, 30];
for (p in points) {
  M p 0
}
// Produces: M 10 0 M 20 0 M 30 0

Destructure to get both item and index with for ([item, index] in list):

let sizes = [5, 10, 15];
for ([size, i] in sizes) {
  circle(calc(i * 40 + 20), 50, size)
}

The array is locked during the loop — mutating it from inside the body (points.push(...), points[i] = x) is an error. To append to an array while walking it, iterate a snapshot — for (p in list.slice(0)) — but note the loop visits only the elements the snapshot captured; anything appended during the loop is not visited (see Reference Semantics).

Iterating over an empty array produces no output.

Destructuring

Extract array elements into individual variables with destructuring in let declarations:

let [a, b, c] = [1, 2, 3];
log(a);  // 1
log(b);  // 2
log(c);  // 3

If the array has more elements than bindings, extras are silently ignored:

let [first, second] = [10, 20, 30, 40];
// first is 10, second is 20 — 30 and 40 ignored

If the array has fewer elements than bindings, missing values are null:

let [x, y, z] = [1, 2];
// x is 1, y is 2, z is null

Use the rest pattern (...name) to collect remaining elements into a new array:

let [head, ...tail] = [1, 2, 3, 4, 5];
// head is 1, tail is [2, 3, 4, 5]

let [only, ...rest] = [42];
// only is 42, rest is []

The rest pattern must be the last binding in the destructuring pattern.

Object destructuring works on object literals and on fixed-shape struct values such as Point, Grid, Color, and ctx.position — see Destructuring in the Objects guide:

let { x, y } = Point(20, 20);

The one-name syntax also works in the other direction: { x, y } builds an object with those variables as values — see Shorthand Properties in the Objects guide.

Angle Units

Numbers can have angle unit suffixes:

The three suffix names are reserved words: they exist only as suffixes, so pi, deg, and rad cannot be declared as variables or referenced standalone (see Variables). The spellings that exist: 0.5pi (an Angle), PI() (the number π), deg(x)/rad(x) (the unit converters).

An angle-suffixed literal produces an Angle value — radians on the inside, with the written unit remembered for display. An angle is an angle wherever it flows: it survives variables, arrays, function parameters, return values, and angle-preserving standard-library functions like clamp, lerp, and randomRange. In angle-accepting positions — path arguments, trig and polar functions, comparisons, loop bounds, calc() arithmetic, rotation and orient properties, gradient from/to, filter angles — an Angle reads as its radians value, so sin(45deg) and sin(rad(45)) are identical. Slots that want a plain count or dimension still reject an Angle: Grid(90deg, 4) errors with "must be a positive integer". The one place radians are not the reading is the degree-based color API — see Angle Display below.

Behavior change: Angle units used to be consumed at the literal — let t = 0.5pi; c.hueShift(t) shifted 1.57°, not 90°. Angles are now values that survive variables, so that program shifts 90°. Likewise Color(0.6, 0.15, 90deg) now stores hue 90 (was 1.5708), interpolating an Angle prints 90deg rather than a radians number, and sort() orders Angle arrays instead of erroring. Angle-preserving standard-library calls now pass the angle through too — randomRange(-0.5pi, 0.5pi) returns an Angle, not bare radians.

let quarter = 90deg;      // an Angle — prints "90deg", auto-converts for hue methods
M sin(quarter) cos(quarter)

// Only inside sin() are these equivalent — an Angle reads as radians there.
// rad(45) itself returns a plain number, not an Angle:
M sin(rad(45)) cos(rad(45))

The pi suffix multiplies the number by π. This is especially convenient for polar coordinates and angles expressed as fractions of π:

let eighth = 0.25pi;   // π/4
let half = 0.5pi;      // π/2
let full = 2pi;        // 2π
M sin(eighth) cos(eighth)

Angle Members

An Angle value exposes its measure in whichever unit you need:

All members return plain numbers:

let a = 90deg;
log(a.deg);    // 90
log(a.rad);    // 1.5707963267948966
log(a.pi);     // 0.5
log(a.turns);  // 0.25

Unit Re-tagging

.toDeg(), .toRad(), .toPi(), and .toTurns() return the same angle with a different display unit — the value is unchanged (it still compares equal and reads as the same radians everywhere), only how it prints changes:

let a = 90deg;
log(a.toPi());          // 0.5pi
log(a.toRad());         // 1.5707963267948966rad
log(a.toTurns());       // 0.25turns
log(a.toPi() == 0.5pi); // true — same angle, different label

turns exists only as a display unit — there is no 0.25turns literal; write calc(0.25 * 2pi) (or 90deg) and re-tag with .toTurns() when you want it displayed that way.

Where Angles come from. Only angle-suffixed literals — plus calc() arithmetic over them and angle-preserving standard-library functions fed an Angle (clamp(90deg, 0deg, 1pi) is an Angle) — produce Angle values. Standard-library functions that compute an angle return plain numbers in radians: atan2(), .angleTo(), tangent(t).angle, PolarVector.angle, and deg()/rad()/mpi(). That matters most for the degree-based color methods below, which read a bare number as degrees — write c.hueShift(deg(p.angleTo(q))), not c.hueShift(p.angleTo(q)).

Angle Arithmetic

calc() arithmetic keeps angle-ness where it makes sense:

• Adding or subtracting angles gives an angle: calc(90deg + 0.5pi).
• Scaling an angle by a plain number keeps the angle: calc(2 * 45deg), calc(2pi / 4), and calc(i / 9 * 2pi) are all angles.
• A ratio of two angles is a plain number: calc(1pi / 2pi) is 0.5.
• Everything else (%, comparisons, boolean logic) reads the radians value and produces a plain number.

Unit mismatch checking rejects nonsense at compile time, reading the expression as written:

• calc(0.25pi + 5) throws — adding an angle to a unitless number is ambiguous (% counts as unitless for this check).
• calc(90deg * 45deg) throws — multiplying two angles has no meaning here.
• Angle-ness propagates through a product: calc((90deg * 2) + 5) throws, because the product is still an angle.
• The static check only sees literals: calc(x + 5) is never rejected, even when x holds an angle. At runtime the result is still an angle — the plain 5 is read as radians.

Angle Display

Interpolating an Angle into a template literal or log() shows it in its written unit — 90deg, 0.5pi, 1.5708rad — not the raw radians number. Use .rad or .deg when you need a bare number in text.

Degree-based color methods: hueShift, analogous, and splitComplementary read a bare number argument in degrees. An Angle value — however it arrives: literal, variable, array element, or the return value of a function you defined — is converted exactly, so hueShift(90deg), hueShift(90), and let turn = 0.5pi; hueShift(turn) all shift by 90°. Everywhere else in the language, a bare number is radians.

Color(L, C, H) follows the same rule: a bare H is degrees, and an Angle H auto-converts — Color(0.6, 0.15, 90deg) stores a hue of 90. The .hue property returns a plain number in degrees. See Color § Hue.

Note: The pi suffix only works on numeric literals. To scale π by a variable, multiply inside calc() — calc(x * 1pi) — which keeps the result an Angle. mpi(x) also multiplies by π but returns a plain number, so it reads as radians in numeric slots and as degrees in the color methods above.

For Loops

Repeat path commands with for:

for (i in 0..10) {
  L calc(i * 20) calc(i * 10)
}

The range 0..10 includes both endpoints (0 through 10, giving 11 iterations). Both bounds are ordinary expressions — variables, member accesses, indexes, and function calls all work without a calc() wrapper: for (i in 1..points.length), for (i in first[0]..limits.max). (Remember ranges are inclusive: to visit array indexes, prefer for (p in points) or for ([p, i] in points) over computing bounds.)

Descending Ranges

Ranges automatically count down when start > end:

// Countdown from 5 to 1
for (i in 5..1) {
  M calc(i * 20) 0
}
// Produces: M 100 0 M 80 0 M 60 0 M 40 0 M 20 0

Nested Loops

for (row in 0..2) {
  for (col in 0..2) {
    circle(calc(col * 50 + 25), calc(row * 50 + 25), 10)
  }
}

This creates a 3x3 grid (rows 0, 1, 2 and cols 0, 1, 2).

Loop Control: continue and break

continue; skips the rest of the current iteration and moves to the next one; break; exits the loop entirely:

// Draw circles at 0, 20, 40, 80, 100 — skipping 60
for (i in 0..5) {
  if (i == 3) {
    continue;
  }
  circle(calc(i * 20), 50, 8);
}

// Stop the first time a threshold is crossed
for (i in 0..100) {
  if (calc(i * i) > 500) {
    break;
  }
  M calc(i * 10) calc(i * i)
}

Both work in range loops and for-each loops (over arrays and objects), and inside loops in text blocks. A typical use with glyph layout — skip whitespace without drawing:

for (g in glyphs) {
  if (g.isWhitespace) {
    x = calc(x + g.advanceWidth);
    continue;
  }
  M x y
  g.draw()
  x = calc(x + g.advanceWidth);
}

Placement rules:

• In nested loops, continue/break control the innermost enclosing loop.
• They may appear directly in a loop body or inside if/else branches nested in it.
• Everything else is a boundary: fn bodies, lambdas, callback blocks (Grid.fill, .map, …), apply { } blocks, path blocks (@{ }), and text blocks (outside their own loops). Using continue or break there — or outside any loop — is a compile error: 'continue' is only valid inside a for loop.
• break and continue are reserved words and cannot be used as variable names.

Note: the loop-size safety limit (32,000 iterations) is checked against the range before the loop runs, so a break cannot make an over-limit range acceptable.

Conditionals

Use if, else if, and else for conditional path generation:

let size = 100;

if (size > 75) {
  M 0 0 L 100 100
} else if (size > 50) {
  M 0 0 L 75 75
} else {
  M 0 0 L 50 50
}

You can chain as many else if blocks as needed. Comparison results are numeric: 1 for true, 0 for false.

Functions

Defining Functions

Create reusable path generators with fn:

fn square(x, y, size) {
  rect(x, y, size, size);
}

Calling Functions

square(10, 10, 50);
square(70, 10, 50);

Functions can call other functions and use all language features.

Functions are values: pass one to another function by name and call it through the parameter.

fn double(x) { return calc(x * 2); }
fn callWith(f, v) { return f(v); }

let n = callWith(double, 5);   // 10

(Note: apply is reserved for layer blocks and can't be used as a function name.)

A function body may either return a value, or fall through after emitting path commands — in that case the call produces a path segment that can be used directly in path context:

fn square(x, y, size) {
  rect(x, y, size, size);
}
square(10, 10, 50);          // emits the rect's path commands

Scoping: functions vs lambdas

Named functions are dynamically scoped: a free name inside the body (one that isn't a parameter or a local let) resolves against the caller's scope at call time. Because top-level lets are visible from almost every call site, this usually behaves the way you'd expect — but a caller-local variable of the same name will take precedence:

fn f() { return amt; }
fn g() { let amt = 7; return f(); }
let amt = 1;
let a = f();   // 1  — resolves from the top level
let b = g();   // 7  — resolves from g's scope, the call site

If you need a function that remembers the variables where it was written, use a lambda.

Lambdas

A lambda is a function literal, written with the same block syntax used by array methods and other builders, and stored or passed like any other value:

let add = {|a, b| return a + b; };
let one = {|| return 1; };          // zero parameters

let three = add(1, 2);

Unlike named functions, lambdas are lexically scoped: the body captures the scope where the lambda was written (a closure), not the caller's scope.

let scale = 3;
let times = {|x| return calc(x * scale); };

fn caller() {
  let scale = 100;      // does NOT affect the lambda
  return times(2);
}
let six = caller();     // 6

Capture is by reference — if a captured variable is reassigned later, the lambda sees the new value. Loops create a fresh scope per iteration, so lambdas created inside a loop each capture that iteration's values:

let fns = [];
for (i in 1..3) {
  fns.push({|| return i; });
}
let first = fns[0];
let last = fns[2];
// first() is 1, last() is 3  (bind to a name before calling — see limitations)

Lambda bodies have the same dual mode as named functions: return a value, or fall through after path commands to produce a path segment.

Applying workers with <<. Anywhere a callback builtin accepts a trailing block, a lambda (or a named function) can do the same job — applied with the << operator, never passed inside the parentheses. (Constructor binding blocks are the exception — see the limitations below.) A worker earns its keep when it's reused:

let ease = {|t| return calc(t * t * (3 - 2 * t)); };
let rows = [0.2, 0.5, 0.9].map() << ease;
let cols = [0.1, 0.6].map() << ease;

let doubler = {|v| return calc(v * 2); };

let a = [1, 2, 3].map() << doubler;      // same as .map {|v| ...}
let b = [1, 2, 3].map() << {|v| return calc(v * 2); };   // inline literal

let grid = Grid(4, 4, { xDim: 25, yDim: 25 });
grid.fill() << {|row, col| return calc(row * 4 + col); };

This works for array .map/.filter/.reduce/.sort, Grid.fill/.forEach/.map, and variableOffset/compoundVariableOffset. The parentheses keep their ordinary parameters — reduce(init) << f — and the worker stays outside them. The full rules (evaluation order, chaining, interaction with merge) live in Applying workers under the << operator. The old argument form (map(f)) was removed before any production use; it now errors with a pointer to <<.

Current limitations:

• A lambda must be called through a plain name (f(1, 2)). Calling the result of an expression — fns[0](5), obj.f(1), or an immediately-invoked literal — is not yet supported: assign to a let first.
• A lambda literal cannot appear inside a call in path-argument position (M use({|x| ...}) 0) — path arguments stop at |. Bind the lambda to a variable and pass the name instead. (Worker application is unaffected: << {|x| ... } sits in ordinary expression position.)
• Constructor binding blocks (LinearGradient(...) {|g| ...}, Marker, Pattern, filters, Grid(...) {|g| ...}) still require a literal trailing block — << worker application is a possible future extension there.

Comments

Line comments start with //:

// This is a comment
let x = 50;  // inline comment
M x 0

Path Context (ctx)

When using compileWithContext(), a ctx object tracks the current drawing state:

M 10 20
L 30 40
L calc(ctx.position.x + 10) ctx.position.y  // L 40 40

ctx is an ambient global — so is viewbox, which exposes the dimensions set by define ViewBox(…); see Reading the viewbox.

ctx Properties

How Position Updates

• M/m: Sets position and subpath start
• L/l, H/h, V/v: Updates position to endpoint
• C/c, S/s, Q/q, T/t: Updates position to curve endpoint
• A/a: Updates position to arc endpoint
• Z/z: Returns to subpath start

Lowercase (relative) commands add to current position; uppercase (absolute) set it directly.

log() Function

Use log() to inspect the context during evaluation:

M 10 20
log(ctx)           // Logs full context as JSON
log(ctx.position)  // Logs just position object
log(ctx.position.x) // Logs just the x value
L 30 40

The logs are captured in the logs array returned by compileWithContext().

Example: Drawing Relative to Current Position

M 100 100
L 150 150
// Continue from current position
L calc(ctx.position.x + 50) ctx.position.y
L ctx.position.x calc(ctx.position.y + 50)
Z

Complete Example

// Draw a grid of circles with varying sizes
let cols = 5;
let rows = 5;
let spacing = 40;

for (row in 0..rows) {
  for (col in 0..cols) {
    let x = calc(col * spacing + 20);
    let y = calc(row * spacing + 20);
    let r = calc(5 + col + row);
    circle(x, y, r)
  }
}

Standard Library Reference

pathogen-lang includes built-in functions for math operations and common SVG shapes.

Math Functions

Trigonometry

All trigonometric functions use radians.

// Draw a point on a circle
let angle = 0.5;
let r = 50;
M calc(100 + cos(angle) * r) calc(100 + sin(angle) * r)

Angle Conversion

// Use degrees instead of radians
let angle = rad(45);
M calc(cos(angle) * 50) calc(sin(angle) * 50)

These return plain numbers, not Angle values — handy when a bare number is what you want (e.g. in a template literal). For carrying an angle through your program, an angle-suffixed literal (45deg) does the same job and keeps its unit; its .deg/.rad members cover most conversion needs.

Exponential & Logarithmic

Rounding

Utility

Interpolation & Clamping

// Interpolate between two positions
let t = 0.5;
M calc(lerp(0, 100, t)) calc(lerp(0, 50, t))

// Clamp a value
let x = clamp(150, 0, 100);  // Result: 100

// Ease a width profile in over the first quarter of a stroke
let w = smoothstep(0, 0.25, t);  // t = 0.5 → 1 (fully eased in)

smoothstep. smoothstep uses the GLSL argument order and formula: x is clamped into the [edge0, edge1] range as t = clamp((x - edge0) / (edge1 - edge0), 0, 1), then eased as t * t * (3 - 2 * t). The result rises smoothly from 0 to 1 with zero slope at both edges. Values of x outside the range saturate at 0 or 1. Swapping the edges reverses the ramp — GLSL leaves that case undefined; Pathogen defines and tests it. When edge0 === edge1 the ramp collapses to a hard step: 0 for x below the edge, 1 above it, and NaN exactly at x === edge0.

bump. bump(t, center, spread) is the raised-cosine kernel for building width envelopes: it peaks at exactly 1 when t === center, eases smoothly down to 0 as |t − center| approaches spread, and is exactly 0 (with zero slope at the boundary) everywhere outside that window — a self-contained hill you can sum with other bumps. The formula is 0.5 * (1 + cos(PI() * clamp(abs(t - center) / spread, 0, 1))). spread must be positive: a spread of 0 returns 0 everywhere (and NaN exactly at t === center), and a negative spread clamps the ratio to 0 and returns 1 everywhere. Because it uses cosine, bump is deterministic on any one engine but not bit-pinned across engines the way the hash family is.

// Two bumps summed into one asymmetric envelope (a width profile)
M 20 100
for (i in 1..48) {
  let t = i / 48;
  L calc(20 + t * 160) calc(100 - 10 * bump(t, 0.35, 0.3) - 6 * bump(t, 0.78, 0.18))
}

Angle-Preserving Functions

These functions return a value in the same space as their inputs, so an Angle in means an Angle out — the result keeps its unit for display and for the degree-based color methods. Bare-number inputs produce bare numbers.

Arguments outside those slots are plain numbers by contract — lerp's t is a ratio, and map's result lives in its output range, which is why only outMin/outMax decide the unit. The display unit comes from the first Angle among the deciding arguments — lerp(0deg, 0.5pi, t) prints in degrees. (randomRange and hashRange are defined under Random and Hash & Noise.)

Don't mix bare numbers and Angles in the deciding slots. A bare number there is read as radians, and the result still takes the Angle's unit — min(90deg, 1) is 57.2957795131deg, not 1deg. Give every deciding argument a unit, or give none of them one.

// Random hue jitter, reproducible on every recompile — the pi-suffixed
// range keeps each hashRange result an Angle, so hueShift reads ±90°
let c = Color('#c00');
for (i in 1..9) {
  let swatch = PathLayer(`jitter-${i}`) ${
    stroke: none;
    fill: c.hueShift(hashRange(i, -0.5pi, 0.5pi));
  };
  swatch.apply { rect(0, calc(i * 24), 20, 20); }
}

Everything else is unchanged: functions that consume angles into a plain result (sin, cos, deg, polarX, the rounding family — round(90deg) is 2, because it rounds the radians) still return bare numbers, and functions that compute an angle (atan2, rad, mpi) still return plain radians — see Angle Units.

Behavior change: these functions used to flatten angles to bare radians — c.hueShift(randomRange(-0.5pi, 0.5pi)) shifted by at most ±1.57° because the color methods read bare numbers as degrees. The angle now survives the call, so that program shifts within ±90°. Interpolating such a result also prints with its unit: ${lerp(0deg, 90deg, 0.5)} is 45deg, no longer 0.7853981633974483.

Easing

The easing trio — easeIn(t), easeOut(t), easeInOut(t) — are the callable forms of the Easing enum members used for gradient easing. Same formulas, so the curve easeInOut(t) traces is the curve the gradient renderer applies for Easing.EaseInOut:

These are quadratic eases — CSS's ease-in family is cubic-bézier, close but not identical. Inputs outside [0, 1] clamp to the nearer end.

Constants

// Draw a semicircle
let r = 50;
for (i in 0..20) {
  let angle = calc(i / 20 * PI());
  L calc(100 + cos(angle) * r) calc(100 + sin(angle) * r)
}

Random

Note: Random functions are not deterministic. Each call produces a different value, and recompiling the same program produces different output. For reproducible randomness use hash01(i) with a loop or element index — hashRange(i, min, max) is the deterministic randomRange — see Hash & Noise.

Hash & Noise

Deterministic randomness: the same inputs always produce the same output, so recompiles are repeatable and a "seed" is just another argument.

// Jittered tick marks — identical on every recompile
for (i in 0..18) {
  let x = i * 10 + hash01(i) * 4;
  M x 0
  L x calc(10 + hash01(i, 1) * 20)
}

Determinism. hash01 — and the noise functions built on it — use only integer bit-mixing and exactly-specified IEEE arithmetic (floor, no trigonometry), so they return identical values for identical arguments on every machine and JavaScript engine: CLI, playground, and VS Code preview agree, today and on every future recompile. The hash constants are a fixed contract; changing them would be a breaking change.

Seeds. The optional seed (default 0, so hash01(i) is hash01(i, 0)) selects an independent stream: hash01(i, 0) and hash01(i, 1) are two unrelated sequences over the same indices. Use it to give each layer or element family its own randomness — hash01(i, layerIndex) — instead of ad-hoc arithmetic like hash01(i * 7 + layerIndex * 1013).

Ranges. hash11(n, seed?) is hash01 remapped to [-1, 1) — the natural shape for signed jitter, e.g. 1 + hash11(i, layerIndex) * 0.2 for a ±20% wobble factor. hashRange(n, min, max, seed?) scales the same hash into [min, max): a drop-in deterministic replacement for randomRange(min, max) — just give it the index you want the value pinned to.

Integers only. Every hash function truncates n and seed to 32-bit integers before hashing: hash01(0.9) equals hash01(0), and non-finite inputs (NaN, Infinity) truncate to 0 rather than propagating. Smoothly varying a continuous input is what noise() is for.

Noise. noise(x, seed?) interpolates hash01 smoothly along the number line: at every integer k, noise(k) equals hash01(k) exactly, and between integers the two neighboring lattice values are blended with a smoothstep fade, so the result is continuous with zero slope at each lattice point. This is value noise (lattice values interpolated), not gradient/Perlin noise, so 2D fields show some axis-aligned structure. Unlike hash01, noise locates the lattice with floor — negative inputs interpolate as expected, and a non-finite x yields NaN rather than truncating to 0 (the seed still truncates like hash01's).

Frequency and seeds. Scale the input to set the wobble frequency — noise(t * 8) wobbles eight times as fast as noise(t) — and pass a seed for independent streams, exactly as with hash01.

2D noise. noise2(x, y, seed?) extends the same construction to two dimensions, bilinearly blending the four surrounding lattice corners with the fade on both axes. At integer corners it returns a hash of the coordinate pair (there is no exposed 2D hash).

// A smooth wandering line — noise wobbles, hash01 jitters
M 10 calc(100 - noise(0) * 40)
for (i in 1..60) {
  let t = i / 60;
  L calc(10 + t * 180) calc(100 - noise(t * 6) * 40)
}

vs. Cycler. Cycler (below) is the other deterministic tool: it assigns values round-robin by call order, while the hash family assigns them positionally by index.

Cycler

A Cycler wraps an array and cycles through it sequentially via .pick(), returning to the beginning after reaching the end. Useful for deterministic round-robin assignment of colors, layer names, styles, etc.

Cycler(array, shuffle?)

Creates a cycler from an array. If the optional shuffle argument is truthy, the array is shuffled once at construction (the shuffled order is stable across all cycles).

let c = Cycler(['red', 'green', 'blue']);
c.pick()  // 'red'
c.pick()  // 'green'
c.pick()  // 'blue'
c.pick()  // 'red' (wraps around)

// Shuffled cycler — stable order across wraps
let r = Cycler(['a', 'b', 'c'], true);

.pick()

Returns the next element in the cycle, advancing the internal index. Wraps around to the beginning after the last element.

.length

Returns the number of items in the cycler.

let c = Cycler([1, 2, 3]);
log(c.length);  // 3

PolarVector

A PolarVector represents a direction and distance in polar coordinates. It is used to define bezier control point positions relative to anchor points — you specify "which direction and how far" rather than computing absolute x, y coordinates.

PolarVector(angle, distance)

Creates a polar vector. Angle is in radians (use rad() or deg suffix for degrees).

let pv = PolarVector(0.25 * PI(), 30);
let pv2 = PolarVector(rad(45), 30);      // equivalent

.angle

Returns the angle as a plain number in radians (not an Angle value).

.distance

Returns the distance.

.turn(deltaAngle)

Returns a new PolarVector with the angle rotated by deltaAngle. Distance is unchanged.

let pv = PolarVector(0, 20);
let turned = pv.turn(0.5 * PI());  // angle is now π/2, distance still 20

.scale(factor)

Returns a new PolarVector with the distance multiplied by factor. Angle is unchanged.

let pv = PolarVector(0, 20);
let wider = pv.scale(1.5);  // angle still 0, distance is now 30

.mirror()

Returns a new PolarVector with the angle rotated by π (180°). Distance is unchanged. This is the key operation for achieving C1 (smooth) continuity when chaining bezier curves — the outgoing handle mirrors the incoming handle.

let pv = PolarVector(0.25 * PI(), 20);
let mirrored = pv.mirror();  // angle is now 1.25π, distance still 20

Path Functions

These functions generate complete path segments.

circle(cx, cy, r)

Draws a circle centered at (cx, cy) with radius r.

circle(100, 100, 50)

Output: A full circle using two arc commands.

rect(x, y, width, height)

Draws a rectangle.

rect(10, 10, 80, 60)

roundRect(x, y, width, height, radius)

Draws a rectangle with rounded corners.

roundRect(10, 10, 80, 60, 10)

polygon(cx, cy, radius, sides)

Draws a regular polygon.

polygon(100, 100, 50, 6)  // Hexagon
polygon(100, 100, 50, 8)  // Octagon

star(cx, cy, outerRadius, innerRadius, points)

Draws a star shape.

star(100, 100, 50, 25, 5)  // 5-pointed star

line(x1, y1, x2, y2)

Draws a line segment.

line(0, 0, 100, 100)

arc(rx, ry, rotation, largeArc, sweep, x, y)

Draws an arc to (x, y). This is a direct wrapper around the SVG A command.

M 50 100
arc(50, 50, 0, 1, 1, 150, 100)

quadratic(x1, y1, cx, cy, x2, y2)

Draws a quadratic bezier curve from (x1, y1) to (x2, y2) with control point (cx, cy).

quadratic(0, 100, 50, 0, 100, 100)

cubic(x1, y1, c1x, c1y, c2x, c2y, x2, y2)

Draws a cubic bezier curve.

cubic(0, 100, 25, 0, 75, 0, 100, 100)

polarCubicBezier(start, pv1, pv2, end)

Draws a cubic bezier curve where control points are defined as polar vectors relative to the start and end points. start and end are Point values; pv1 and pv2 are PolarVector values.

• pv1 — direction and distance from start to the first control point
• pv2 — direction and distance from end to the second control point

let a = Point(0, 100);
let b = Point(100, 100);
polarCubicBezier(a, PolarVector(rad(-60), 40), PolarVector(rad(-120), 40), b)

Output: m (relative move) followed by c (relative cubic) — matches the spline function convention.

PolarVector methods compose naturally for handle manipulation:

let handle = PolarVector(rad(-45), 30);
// Symmetric curve: mirror the handle for the other end
polarCubicBezier(a, handle, handle.mirror(), b)

// Wider version: scale the handle distance
polarCubicBezier(a, handle.scale(1.5), handle.mirror().scale(1.5), b)

moveTo(x, y)

Returns a move command. Useful inside functions.

moveTo(50, 50)

lineTo(x, y)

Returns a line command.

lineTo(100, 100)

closePath()

Returns a close path command.

closePath()

cubicSpline(points)

Draws a chain of cubic bezier curves with explicit tangent angle and handle length at each point. Adjacent curves share a common tangent direction at join points, guaranteeing G1 (smooth) continuity.

Point schema:

cubicSpline([
  { x: 0, y: 100, angle: 0, exit: 30 },
  { x: 50, y: 0, angle: 0, entry: 20, exit: 25 },
  { x: 100, y: 100, angle: 0, entry: 30 }
])

Output: m (relative move) followed by one c (relative cubic) command per segment. A single-point array emits only m. All spline functions use relative commands so they work naturally inside path blocks.

quadSpline(start, points, end)

Draws a chain of quadratic bezier curves with implicit angle derivation. Only the start point specifies an explicit angle; intermediate points derive their tangent angle from the geometry of the previous control point.

Start: { x, y, angle, exit } Intermediate: { x, y, exit } End: { x, y }

quadSpline(
  { x: 0, y: 0, angle: 0, exit: 30 },
  [{ x: 60, y: 0, exit: 30 }],
  { x: 120, y: 0 }
)

Output: m followed by one q (relative quadratic) command per segment.

clippedQuadSpline(start, points, end)

Extends quadSpline by splitting the implicit shared control point into two cubic control points using time-based fractions (exitTime/entryTime). This allows dampening curve eccentricity while preserving the quadratic geometry.

Start: { x, y, angle, exit, exitTime } Intermediate: { x, y, exit, exitTime, entryTime } End: { x, y, entryTime }

• exitTime = 1, entryTime = 1: mathematically equivalent to quadratic
• exitTime = 0.5, entryTime = 0.5: control points at half arm length (moderate dampening)
• exitTime = 0, entryTime = 0: linear segments

clippedQuadSpline(
  { x: 0, y: 0, angle: 0, exit: 100, exitTime: 0.5 },
  [],
  { x: 200, y: 0, entryTime: 0.5 }
)

Output: m followed by one c (relative cubic) command per segment — not q.

Grid Functions

These functions generate complete grid patterns as path segments. Each accepts a GridPatternType enum (or string) that controls the visual style:

Not to be confused with the Grid() constructor — that's a data container for 2D values mapped to canvas coordinates (flow fields, heatmaps, sampling). The functions below produce SVG path data for visual lattices.

squareGrid(type, x, y, width, height, cellSize)

Generates a square grid pattern within the bounding rectangle starting at (x, y).

• type — GridPatternType enum value or string ('shape', 'dot', 'intersection', 'partial')
• x, y — Top-left origin of the grid
• width, height — Bounding dimensions
• cellSize — Side length of each square cell

The grid contains floor(width / cellSize) columns and floor(height / cellSize) rows. Extra space is ignored.

gridLayer.apply {
  squareGrid(GridPatternType.Shape, 0, 0, 200, 200, 20);
}

triangleGrid(type, x, y, width, height, cellSize)

Generates an equilateral triangle grid. cellSize is the triangle height (altitude). Triangles have flat bases with alternating up/down orientation.

gridLayer.apply {
  triangleGrid(GridPatternType.Shape, 0, 0, 200, 200, 20);
}

The triangle side length is derived from the height: side = 2 * cellSize / sqrt(3).

hexagonGrid(type, x, y, width, height, cellSize, orientation?)

Generates a hexagonal grid. cellSize is the flat-to-flat height of each hexagon.

• orientation — Optional. HexagonOrientation.Edge (default, flat-top) or HexagonOrientation.Vertex (pointy-top)

// Flat-top hexagons (default)
gridLayer.apply {
  hexagonGrid(GridPatternType.Shape, 0, 0, 200, 200, 20);
}

// Pointy-top hexagons
gridLayer.apply {
  hexagonGrid(GridPatternType.Shape, 0, 0, 200, 200, 20, HexagonOrientation.Vertex);
}

Usage with Layers and Transforms

Grid functions return path data and are typically used inside layer.apply {} blocks. Rotation and styling are handled via the layer:

let gridStyles = ${ stroke: #88f; stroke-width: 0.25; fill: none; };
let gridLayer = PathLayer('grid') << gridStyles;

gridLayer.ctx.transform.rotate.set(0.125pi);
gridLayer.apply {
  squareGrid(GridPatternType.Partial, 0, 0, 400, 400, 20);
}

A convenience wrapper for one-line grid drawing:

fn drawGridToLayer(layer, gridFn, type, angle, x, y, w, h, s) {
  layer.ctx.transform.rotate.set(angle);
  layer.apply { gridFn(type, x, y, w, h, s); }
}

Context-Aware Functions

These functions use the current path context (position, tangent direction) to generate path segments. They maintain path continuity and are ideal for building complex shapes programmatically.

Polar Movement

polarPoint(angle, distance)

Returns a point at a polar offset from current position. Does not emit any path commands.

M 100 100
let p = polarPoint(0, 50);
L p.x p.y  // Line to (150, 100)

polarOffset(angle, distance)

Returns {x, y} coordinates at a polar offset. Similar to polarPoint.

polarMove(angle, distance)

Emits a line command (L) moving in the specified direction. Updates position but draws a visible line.

M 100 100
polarMove(0, 50)  // Draws line to (150, 100)

polarLine(angle, distance)

Emits a line command (L) in the specified direction. Same as polarMove.

M 100 100
polarLine(45deg, 70.7)  // Draws line diagonally

Arc Functions

arcFromCenter(dcx, dcy, radius, startAngle, endAngle, clockwise)

Draws an arc defined by center offset and angles. Returns {point, angle} with endpoint and tangent.

• dcx, dcy: Offset from current position to arc center
• radius: Arc radius
• startAngle, endAngle: Start and end angles in radians
• clockwise: 1 for clockwise, 0 for counter-clockwise

Warning: If current position doesn't match the calculated arc start point, a line segment (L) will be drawn to the arc start. For guaranteed continuous arcs, use arcFromPolarOffset.

M 50 50
arcFromCenter(50, 0, 50, 180deg, 270deg, 1)
// Center at (100, 50), arc from (50, 50) to (100, 100)

arcFromPolarOffset(angle, radius, angleOfArc)

Draws an arc where the center is at a polar offset from current position. The current position is guaranteed to be on the circle, so only an A command is emitted (no M or L). Returns {point, angle} with endpoint and tangent.

• angle: Direction from current position to arc center (radians)
• radius: Arc radius
• angleOfArc: Sweep angle (positive = clockwise, negative = counter-clockwise)

This function is ideal for creating continuous curved paths because it never emits extra line segments.

M 100 100
arcFromPolarOffset(0, 50, 90deg)
// Center at (150, 100), sweeps 90° clockwise
// Ends at (150, 50)

Comparison with arcFromCenter:

Heading Control

Angles follow SVG coordinate conventions: 0 is rightward, positive angles rotate clockwise (toward the positive y-axis, which points down in SVG).

heading(angle)

Sets the heading to an absolute angle. No command is emitted and the cursor does not move. This enables tangentArc and tangentLine immediately after M without needing a dummy segment like h 0.01.

M 50 100
heading(0)           // Set heading to rightward
tangentArc(20, 90deg) // Works immediately — no dummy segment needed

Inside path blocks, heading() avoids the offset artifacts that h 0.01 causes with z closePath:

let cLike = @{
  heading(0)
  tangentArc(20, 90deg)
  tangentArc(20, -90deg)
  z  // Closes cleanly to start — no tiny offset
};

turn(delta)

Adds delta to the current heading (relative change). Requires an existing heading — either from heading() or from a previous drawing command. Negative deltas turn counter-clockwise.

M 50 100
heading(0)          // Start heading rightward
turn(90deg)         // Now heading downward
tangentLine(30)     // Draws 30px down

After drawing commands:

M 0 0  L 50 0      // Heading is 0 (rightward)
turn(45deg)         // Heading is now 45°
tangentLine(20)     // Continues at 45°

ctx.heading

The current heading (read-only), readable via the context object. Set by heading(), turn(), or any drawing command that establishes direction. M (moveTo) clears the heading.

M 0 0  L 50 0
log(ctx.heading)   // 0 (rightward)
heading(90deg)
log(ctx.heading)   // π/2 (downward)
M 200 200
log(ctx.heading)   // undefined (M clears the heading)

Tangent Functions

These functions continue from the current heading. Any path command that establishes a direction — including native SVG commands (L, H, V, C, S, Q, T, A, Z) and stdlib path functions — sets a heading that tangentLine and tangentArc can follow.

You can also set the heading explicitly with heading(), adjust it with turn(), or read it via ctx.heading.

M (moveTo) clears the heading since a move does not establish a direction.

tangentLine(length)

Draws a line continuing in the tangent direction from the previous command.

arcFromPolarOffset(0, 50, 90deg)
tangentLine(30)  // Continues in the arc's exit direction

After native SVG commands:

M 50 100  L 150 100
tangentLine(30)  // Continues rightward to (180, 100)

tangentArc(radius, sweepAngle)

Draws an arc continuing tangent to the previous command.

arcFromPolarOffset(0, 50, 90deg)
tangentArc(30, 45deg)  // Smooth continuation with a smaller arc

After native SVG commands:

M 50 100  L 150 100
tangentArc(30, 90deg)  // Smooth arc curving down from the line's endpoint

Color

The Color type provides first-class color manipulation in OKLCH color space. See the full Color documentation for constructor forms, methods, properties, and examples.

let c = Color('#e63946');
let lighter = c.lighten(0.2);
let comp = c.complement();

CSSVar

The CSSVar type creates CSS custom property references (var()) for use in style blocks. See the full CSSVar documentation for constructor forms, properties, and examples.

let fg = CSSVar('--foreground', '#333');
define PathLayer('main') ${ stroke: fg; }

Using Functions Inside calc()

Math functions can be used inside calc():

M calc(sin(0.5) * 100) calc(cos(0.5) * 100)
L calc(lerp(0, 100, 0.5)) calc(clamp(150, 0, 100))

Path functions are called at the statement level:

circle(100, 100, calc(25 + 25))  // calc() inside arguments

ViewBox

Every Pathogen program renders into an SVG with a viewBox. The define ViewBox statement specifies that viewBox directly in code, making the program self-contained and reproducible across the CLI, playground, and VS Code preview.

Syntax

define ViewBox(originX, originY, width, height);

The four arguments become the SVG viewBox="originX originY width height" attribute on the root <svg> element. The root width and height attributes default to the same width and height values.

define ViewBox(0, 0, 200, 200);
M 50 50 L 150 150

Renders to <svg viewBox="0 0 200 200" width="200" height="200">…</svg>.

Arguments

Arguments are expressions and may use variables, calc(), member accesses (sheet.w), array indexes (sizes[0]), function calls, or any other expression form:

let W = 400;
let H = 300;
define ViewBox(0, 0, W, H);

define ViewBox(0, 0, calc(100 * 4), calc(100 * 3));

Negative Origin

originX and originY may be negative — useful for centering geometry around (0, 0):

define ViewBox(-100, -100, 200, 200);
M -50 -50 L 50 50

Reading the viewbox

The viewbox global (lowercase) exposes the values set by define ViewBox as a read-only struct. This removes the update-two-places pattern: a full-canvas background no longer repeats the canvas dimensions, so changing the viewBox is a one-line edit:

define ViewBox(0, 0, 880, 280);
define default PathLayer('base') ${ fill: #fff; };
let {width, height} = viewbox;
rect(0, 0, width, height);

The struct's type is ViewBox — a typo like viewbox.w errors with Property 'w' does not exist on ViewBox.

All the usual access forms work — dot access, destructuring, and rest patterns:

define ViewBox(-100, -100, 200, 200);
let cx = calc(viewbox.originX + viewbox.width / 2);
let {originX, originY, ...size} = viewbox;

viewbox is available anywhere after the define ViewBox statement has executed — inside fn bodies, layer().apply { } blocks, and path blocks alike. The rule is execution order, not source order: a function declared above the define can still read viewbox when it is called after the define has run, because the lookup happens at call time.

Reading before defining is an error

Reading viewbox before define ViewBox(…) has executed — including in a program with no define ViewBox at all — is an error:

// Error: viewbox is not available until define ViewBox(...) has run
let {width} = viewbox;
define ViewBox(0, 0, 200, 200);

The implicit 0 0 200 200 default (Default ViewBox) applies to rendering only; the viewbox global never falls back to it. To read the viewbox, declare it.

Shadowing and read-only semantics

• The struct is read-only: assigning to a member (viewbox.width = 5;) is a compile error — Cannot assign to property 'width'.
• Each read returns a fresh copy, so let a = viewbox; gives you an independent snapshot.
• A user variable named viewbox shadows the global — let viewbox = 5; is legal and existing programs keep their meaning. The shadow follows normal scope rules: a let viewbox inside a block shadows only within that block, and the global is visible again outside it. Within a scope that shadows it, there is no way to reach the ambient global.
• Capitalized ViewBox remains a keyword and is only valid in define ViewBox(…).

Default ViewBox

If a program contains no define ViewBox statement, the rendered viewBox defaults to 0 0 200 200. This default applies to rendering only — the viewbox global does not inherit it and errors when read in a program without define ViewBox (see Reading the viewbox).

Placement

define ViewBox is a top-level statement. It may appear anywhere among other top-level statements, but not inside a layer().apply { } block, a path block, or a text block.

// OK
define ViewBox(0, 0, 200, 200);
define default PathLayer('main') ${ stroke: #222; };
M 0 0 L 200 200

// Error: ViewBox must appear at top level
layer('main').apply {
  define ViewBox(0, 0, 200, 200);
  M 0 0
}

Errors

The compiler rejects:

• Duplicate define ViewBox — only one viewBox per program.
• Zero or negative width or height — these are invalid SVG dimensions.
• default modifier — define default ViewBox(…) is not allowed; only PathLayer and TextLayer accept default.
• Non-numeric arguments — every argument must evaluate to a finite number.
• Reading viewbox before define ViewBox has run — see Reading before defining is an error.
• Assigning to a viewbox member — the struct is read-only; see Shadowing and read-only semantics.

Precedence with the CLI

The CLI accepts --viewBox, --width, and --height flags. When the source contains a define ViewBox statement, the source wins; the CLI flags are used only when the source does not define a viewBox:

This lets inline -e snippets supply a viewBox via the CLI while persistent programs declare it in source.

The viewbox global reads only from define ViewBox. When the viewBox comes from a CLI flag (or the implicit default), reading viewbox still errors — the flag affects rendering, not the program's variables. A program that reads viewbox must declare its viewBox in source.

Why source, not configuration

Storing viewBox in source code (rather than in workspace metadata, comments, or external configuration) keeps a program self-contained: copying the code anywhere reproduces the same image. It also lets editor tooling (completion, hover, formatting) reason about the viewBox the same way it reasons about any other statement.

Related

• Layers — the rest of the define family (PathLayer, TextLayer, GroupLayer)
• CLI — using --viewBox/--width/--height flags alongside source-defined viewBox
• Path Context (ctx) — the other ambient global, tracking the pen position during evaluation

Layers

Layers let you output multiple <path> elements from a single program, each with its own styles and independent pen tracking.

See also define ViewBox for declaring the SVG viewBox — a sibling define-family statement that controls the canvas dimensions.

Defining Layers

Use define to create a named layer with a style block:

define PathLayer('outline') ${
  stroke: #cc0000;
  stroke-width: 3;
  fill: none;
}

Layer names must be unique strings. The style block uses CSS/SVG property syntax — any SVG presentation attribute works (stroke, fill, opacity, stroke-dasharray, etc.).

Breaking change: Style blocks now use ${ } syntax instead of { }. Update existing layer definitions: { stroke: red; } → ${ stroke: red; }.

Default Layer

Every program has exactly one default layer — the layer that receives all bare path commands (commands outside any layer().apply block). You don't create it; it always exists. define default PathLayer('name') simply names and styles that one layer:

define default PathLayer('main') ${
  stroke: #333;
  stroke-width: 2;
  fill: none;
}

// These commands go to 'main' — the default layer
M 10 10
L 90 10
L 90 90
Z

If you never write define default PathLayer, the default layer is still there: bare commands flow into it and it appears in the output named 'default' (with no styles). There is no separate "global" layer alongside the default — bare commands, the pen position (ctx), and any top-level transform all belong to this single default layer, whether or not you have named it.

Writing to Layers

Use layer('name').apply { ... } to send commands to a specific layer:

define PathLayer('grid') ${
  stroke: #ddd;
  stroke-width: 0.5;
}

define default PathLayer('shape') ${
  stroke: #333;
  stroke-width: 2;
  fill: none;
}

// Draw a grid on the 'grid' layer
layer('grid').apply {
  for (i in 0..10) {
    M calc(i * 20) 0
    V 200
    M 0 calc(i * 20)
    H 200
  }
}

// These go to 'shape' (the default)
M 40 40
L 160 40
L 100 160
Z

Context Isolation

Each layer has its own pen position. Commands in one layer don't affect another layer's ctx:

define default PathLayer('a') ${ stroke: red; }
define PathLayer('b') ${ stroke: blue; }

M 100 100    // layer 'a' position: (100, 100)

layer('b').apply {
  M 50 50    // layer 'b' position: (50, 50)
}

// Back in layer 'a', position is still (100, 100)
L 200 200

Querying Labeled Geometry

Path commands inside apply { } blocks can carry as segment(...) / as endpoint(...) labels. A labeled layer answers geometry queries by name from anywhere:

let pl = PathLayer('outline') ${ stroke: #333; fill: none; };
pl.apply {
  M 10 10
  h 60 as segment('top');
  v 40 as endpoint('corner');
}

let top = layer('outline').segment('top');   // ProjectedPath (absolute coords)
let c = layer('outline').point('corner');    // Point(70, 50)

segment('name') returns a ProjectedPath with the full sampling API (get, tangent, partition, boundingBox, ...); point('name') returns the labeled vertex as a Point. See Segment Labels & Corner Suffixes for the full query surface.

Accessing Layer Context

Use layer('name').ctx to read a layer's pen state from anywhere:

define default PathLayer('main') ${ stroke: #333; }
define PathLayer('markers') ${ stroke: red; fill: red; }

M 50 50
L 150 80
L 100 150

// Draw markers at the main layer's current position
layer('markers').apply {
  let px = layer('main').ctx.position.x
  let py = layer('main').ctx.position.y
  circle(px, py, 4)
}

Available context properties:

Dynamic Layer Names

Layer names can be any expression — a variable, a template literal, an array element, a member access, or a function call — both where a layer is defined and where layer(...) routes to it:

let target = 'overlay'
define PathLayer(target) ${ stroke: blue; }

layer(target).apply {
  M 0 0 L 100 100
}

Expression names make routing data-driven. Round-robin styling, for example, needs no if-chain — compute the name, or index into a list of layer values:

let shards = [shard0, shard1, shard2];   // layer values from PathLayer(...)
for ([piece, i] in pieces) {
  layer(`shard${i % 3}`).apply {          // by computed name…
    piece.draw();
  }
  // …or equivalently: layer(shards[calc(i % 3)]).apply { ... }
}

Dynamic Layer Creation

Layers can also be created as first-class values using PathLayer() and TextLayer() constructor expressions. This allows storing layers in variables, appending styles after creation, and using .apply { } directly on the variable.

Constructor Expression

let myLayer = PathLayer('unique-name') ${ stroke: red; fill: none; };
myLayer.apply { M 0 0 L 100 100 }

The style block is optional:

let myLayer = PathLayer('unique-name');
myLayer.apply { M 0 0 }

Style Mutation with <<

The << operator on a layer reference merges styles in place and returns the reference for chaining:

let l = PathLayer('outline');
l << ${ stroke: red; } << ${ fill: blue; };
l.apply { M 0 0 L 100 100 }
// l.styles: stroke: red, fill: blue

Explicit .styles Property

Read or replace a layer's styles via the .styles property:

let l = PathLayer('outline') ${ stroke: red; };

// Read: returns a StyleBlockValue copy
let s = l.styles;
log(s.stroke)  // "red"

// Write: replaces all styles
l.styles = l.styles << ${ fill: blue; };

TextLayer Constructor

let labels = TextLayer('labels') ${ font-size: 14; font-family: monospace; };
labels.apply { text(50, 45)`Start` }

Accessing Layer Properties

Dynamic layers support the same properties as layer() references:

Coexistence with define

Both approaches work together. The define syntax supports the default modifier; dynamic constructors do not:

define default PathLayer('main') ${ stroke: #333; fill: none; }
let overlay = PathLayer('overlay') ${ stroke: red; };

M 10 10 L 90 90          // goes to 'main' (default)
overlay.apply { M 50 50 L 60 60 }

// layer() function works for both:
layer('overlay').apply { M 70 70 }

Layers render in definition order regardless of how they were created.

Style Properties

Style properties map directly to SVG presentation attributes. Common properties:

Each property is a semicolon-terminated declaration:

define PathLayer('dashed') ${
  stroke: #0066cc;
  stroke-width: 2;
  stroke-dasharray: 8 4;
  fill: none;
}

Output Format

When using the JavaScript API, compile() returns a structured result:

import { compile } from 'pathogen-lang';

const result = compile(`
  define default PathLayer('bg') ${
    stroke: #ddd;
    fill: none;
  }
  define PathLayer('fg') ${
    stroke: #333;
    stroke-width: 2;
    fill: none;
  }

  M 0 0 H 100 V 100 H 0 Z

  layer('fg').apply {
    M 20 20 L 80 80
  }
`);

// result.layers is an array of LayerOutput:
// [
//   {
//     name: 'bg',
//     type: 'path',
//     data: 'M 0 0 H 100 V 100 H 0 Z',
//     styles: { stroke: '#ddd', fill: 'none' },
//     isDefault: true
//   },
//   {
//     name: 'fg',
//     type: 'path',
//     data: 'M 20 20 L 80 80',
//     styles: { stroke: '#333', 'stroke-width': '2', fill: 'none' },
//     isDefault: false
//   }
// ]

Programs without any define statements produce a single implicit layer:

compile('M 0 0 L 100 100').layers
// [{ name: 'default', type: 'path', data: 'M 0 0 L 100 100', styles: {}, isDefault: true }]

Full Example

A multi-layer illustration with a background grid, main shape, and annotation markers:

// Layer definitions
define PathLayer('grid') ${
  stroke: #e0e0e0;
  stroke-width: 0.5;
}

define default PathLayer('shape') ${
  stroke: #333333;
  stroke-width: 2;
  fill: none;
  stroke-linejoin: round;
}

define PathLayer('points') ${
  stroke: #cc0000;
  fill: #cc0000;
}

// Grid
layer('grid').apply {
  for (i in 0..10) {
    M calc(i * 20) 0  V 200
    M 0 calc(i * 20)  H 200
  }
}

// Shape (goes to default layer)
let cx = 100
let cy = 100
let r = 60
let sides = 6

for (i in 0..sides) {
  let angle = calc(i * 360 / sides - 90)
  let x = calc(cx + r * cos(radians(angle)))
  let y = calc(cy + r * sin(radians(angle)))
  if (i == 0) { M x y } else { L x y }
}
Z

// Mark each vertex
layer('points').apply {
  for (i in 0..sides) {
    let angle = calc(i * 360 / sides - 90)
    let x = calc(cx + r * cos(radians(angle)))
    let y = calc(cy + r * sin(radians(angle)))
    circle(x, y, 3)
  }
}

TextLayer

TextLayers produce SVG <text> elements instead of <path> elements.

Defining a TextLayer

define TextLayer('labels') ${
  font-size: 14;
  font-family: monospace;
  fill: #333;
}

text() — Two Forms

Inline form — simple text content:

layer('labels').apply {
  text(50, 45)`Start`
  text(150, 75, 30deg)`End`    // rotation uses angle units (deg/rad/pi)
}

Block form — mixed text runs and tspan children:

layer('labels').apply {
  text(10, 180) {
    `Hello `
    tspan(0, 0, 30deg)`world`
    ` and more`
  }
}

The block form maps to SVG's mixed content model: <text x="10" y="180">Hello <tspan rotate="30">world</tspan> and more</text>

Note: 30deg in the source becomes rotate="30" (degrees) in SVG output.

tspan() — Only Inside text() Blocks

tspan()`content`                   // no offset
tspan(dx, dy)`content`             // with offsets
tspan(dx, dy, 45deg)`content`      // with offsets and rotation

Position arguments (x, y, dx, dy) are plain numbers. Rotation follows the standard angle unit convention — bare numbers are radians, use deg/rad/pi suffixes for explicit units. Content is always a template literal.

Template Literals

Template literals use backtick syntax with ${expression} interpolation. They work everywhere — text content, log messages, variable values:

let name = "World"
let x = `Hello ${name}!`              // "Hello World!"
let msg = `Score: ${2 + 3}`           // "Score: 5"
log(`Position: ${ctx.position.x}`)    // in log messages

Template literals are the sole string construction mechanism — + stays strictly numeric. String equality (==/!=) works for conditionals:

let mode = "dark"
if (mode == "dark") { /* ... */ }
if (mode != "light") { /* ... */ }

TextLayer Output Format

const result = compile(`
  define TextLayer('labels') ${ font-size: 14; fill: #333; }
  layer('labels').apply {
    text(50, 45)\`Start\`
    text(10, 180) {
      tspan()\`Multi-\`
      tspan(0, 16)\`line\`
    }
  }
`);

// result.layers[0]:
// {
//   name: 'labels',
//   type: 'text',
//   data: 'Start Multi-line',
//   textElements: [
//     { x: 50, y: 45, children: [{ type: 'run', text: 'Start' }] },
//     { x: 10, y: 180, children: [
//       { type: 'tspan', text: 'Multi-' },
//       { type: 'tspan', text: 'line', dx: 0, dy: 16 },
//     ]},
//   ],
//   styles: { 'font-size': '14', fill: '#333' },
//   isDefault: false,
// }

Restrictions

• text() can only be used inside a layer().apply block targeting a TextLayer
• tspan() can only appear inside a text() { } block
• Path commands (M, L, etc.) cannot be used inside a TextLayer apply block
• If a TextLayer is the default layer, bare path commands will throw an error

Style Blocks

Style blocks are first-class values that can be stored in variables, merged, and accessed via dot notation.

Style Block Literals

let styles = ${
  stroke-dasharray: 0.01 20;
  stroke-linecap: round;
  stroke-width: 8.4;
};

Merge Operator (<<)

The << operator merges two style blocks, with the right side overriding the left:

let base = ${ stroke: red; stroke-width: 2; };
let merged = base << ${ stroke-width: 4; fill: blue; };
// merged has: stroke: red, stroke-width: 4, fill: blue

Property Access

Use dot notation with camelCase to read kebab-case properties:

let styles = ${ stroke-width: 4; };
let sw = styles.strokeWidth;  // reads 'stroke-width' → "4"

Expression Evaluation in Values

Style block values are try-evaluated: if a value parses and evaluates as an expression, its result is used. Otherwise the raw string is kept:

let dynamic = ${
  font-size: calc(12 + 15);       // evaluates to "27"
  stroke-width: randomRange(2, 8); // evaluates to a random number
  stroke: rgb(232, 74, 166);       // kept as raw string
  fill: #996633;                   // kept as raw string
};

Variables and Interpolation in Values

This is the same expression evaluation from the previous section applied to variables: a bare identifier is just an expression that resolves to its value, and a backtick template is an expression that interpolates with ${...}:

let family = "Noto Sans";
let size = 16;

let textStyles = ${
  font-family: family;              // resolves to "Noto Sans"
  font-size: `${size * 2}`;         // interpolates to "32"
};

Double-quoted strings are always literal — they never interpolate. font-family: "family"; is the literal family name family, not the variable; use a bare identifier or backticks for dynamic values. (Inside a ${...} interpolation, at most one nested level of { } braces is supported.)

Dynamic Function Arguments

A template doesn't have to span the whole value — a backtick fragment can sit anywhere inside it, including function arguments. Each fragment evaluates and splices into the surrounding text before the value is checked:

let amount = randomRange(1.1, 2.2);

define PathLayer('soft') ${
  fill: hotpink;
  filter: blur(`${amount}`px);   // splices to e.g. "blur(1.63px)"
};
layer('soft').apply { circle(100, 100, 60); }

These four forms are all available, and all produce blur(1.5px) brightness(1.4) for softness = 1.5, level = 1.4:

The quoting rule above still applies to fragments: a backtick inside a double- or single-quoted string is literal text, not a splice point.

A bare identifier works as a function argument when the variable holds a number — the compiler substitutes the value, as it already does for Color and CSSVar() references:

let level = 1.4;
define PathLayer('bright') ${ filter: brightness(level); };

Substitution is not unit-aware, and the compiler checks the result. A numeric variable substitutes as a bare number, so filter: blur(amount); would emit blur(4) — a unitless length, which is invalid CSS. Rather than emit a declaration the browser silently drops, Pathogen rejects it:

blur() takes a length — "4" needs a unit (try 4px). Lengths without a valid
unit are invalid CSS and the browser drops the whole declaration.

The check runs on the final value, so it catches the mistake whether the number was typed literally, substituted from a variable, or interpolated. Use a bare identifier for the unitless filter functions (brightness, contrast, grayscale, invert, opacity, saturate, sepia); whenever the argument is a length or an angle, attach the unit with a template fragment. Literal arguments written with units (blur(2px), hue-rotate(-90deg)) are always left exactly as typed. See CSS Function Values for the full per-function unit rules.

Interpolation is a convenience, not an escape hatch: every interpolated result — whole-value or fragment — is validated against the same style-value allow-list as hand-written values (see the security model). Note the two calc()s are different things: an unquoted calc(12 + 15) is Pathogen arithmetic resolved before emission, while a calc() that survives into the emitted CSS string — including via interpolation — is rejected.

Layer Definitions with Style Expressions

Layer definitions accept any expression that evaluates to a style block:

let baseStyles = ${ stroke: red; stroke-width: 2; };
define PathLayer('main') baseStyles << ${ fill: none; }

Per-Element Styles on Text and Tspan

Pass style blocks as the 4th argument to text() or tspan():

let bold = ${ font-weight: bold; };
layer('labels').apply {
  text(10, 20, 0, bold)`Hello`
  text(50, 80) {
    tspan(0, 0, 0, ${ fill: red; })`colored`
  }
}

Transforms

Apply SVG matrix transformations (translate, rotate, scale) at the layer level. Transforms are set via method calls on ctx.transform and rendered as SVG transform attributes on the output elements.

Translate

define PathLayer('shape') ${ stroke: #333; fill: none; }

layer('shape').ctx.transform.translate.set(50, 50)

layer('shape').apply {
  M 0 0 L 100 0 L 100 100 Z
}
// Output: <path d="..." transform="translate(50, 50)"/>

Rotate

Angles are in radians (consistent with polar commands). Use deg suffix for degrees — Angle values work here whether written inline or carried in a variable:

layer('shape').ctx.transform.rotate.set(45deg)         // around origin
layer('shape').ctx.transform.rotate.set(45deg, 50, 50) // around (50, 50)

Scale

layer('shape').ctx.transform.scale.set(2, 2)             // uniform scale
layer('shape').ctx.transform.scale.set(2, 2, 50, 50)     // scale around (50, 50)

Reset

layer('shape').ctx.transform.translate.reset()  // clear translate only
layer('shape').ctx.transform.rotate.reset()     // clear rotate only
layer('shape').ctx.transform.scale.reset()      // clear scale only
layer('shape').ctx.transform.reset()            // clear all transforms

Read Access

layer('shape').ctx.transform.translate.x    // 0 if not set
layer('shape').ctx.transform.translate.y
layer('shape').ctx.transform.rotate.angle   // 0 if not set
layer('shape').ctx.transform.scale.x        // 1 if not set (default scale)
layer('shape').ctx.transform.scale.y        // 1 if not set

Default Layer Context

Outside any layer().apply block, ctx refers to the default layer's context — including its transform. This is true whether or not you have named the default layer with define default PathLayer:

ctx.transform.translate.set(25, 25)
ctx.transform.rotate.set(45deg)
M 0 0 L 100 0

Inside Apply Blocks

Inside a layer().apply block, ctx refers to the active layer's context:

layer('shape').apply {
  ctx.transform.translate.set(10, 20)
  M 0 0 L 50 50
}

Combined Transforms

When multiple transforms are set, they are applied in SVG order: translate → rotate → scale (translate applied last visually):

layer('shape').ctx.transform.translate.set(10, 20)
layer('shape').ctx.transform.rotate.set(90deg)
layer('shape').ctx.transform.scale.set(2, 2)
// Output: transform="translate(10, 20) rotate(90) scale(2, 2)"

Transform Convenience Properties

Style blocks support individual transform properties as an alternative to transform: ... or the imperative API. These work on PathLayer, GroupLayer, and TextLayer:

define PathLayer('p') ${
  translate-x: 50;
  translate-y: 100;
  scale-x: 2;
  scale-y: 2;
  rotate: 0.25pi;
}
// Output: transform="translate(50, 100) rotate(45) scale(2, 2)"

Shorthands for translate and scale accept comma-separated values:

define PathLayer('p') ${ translate: 50, 100; scale: 2, 3; }
// Output: transform="translate(50, 100) scale(2, 3)"

Single-value scale uses the same value for both axes:

define PathLayer('p') ${ scale: 2; }
// Output: transform="scale(2, 2)"

The rotate value is an expression in radians (angle units like deg and pi work normally):

define PathLayer('p') ${ rotate: 45deg; }
// Output: transform="rotate(45)"

Precedence: An explicit transform property overrides convenience properties. Convenience properties override imperative ctx.transform calls. The individual translate-x/translate-y properties override the translate shorthand (and similarly for scale).

Convenience properties are removed from the output styles — they only affect the transform attribute.

Per-Layer Isolation

Each layer has independent transforms — setting a transform on one layer does not affect others:

define PathLayer('a') ${ stroke: red; }
define PathLayer('b') ${ stroke: blue; }

layer('a').ctx.transform.translate.set(10, 10)
layer('b').ctx.transform.scale.set(2, 2)
// Layer 'a' gets translate(10, 10), layer 'b' gets scale(2, 2)

GroupLayer

GroupLayers map to SVG <g> elements and organize child layers via .append(). They support transforms through style blocks and the imperative ctx.transform API, but do not support apply blocks.

Definition

// Define a group with styles
let panel = GroupLayer('panel') ${ opacity: 0.8; };

// Or with define (cannot be default)
define GroupLayer('panel') ${ opacity: 0.8; }

GroupLayers cannot be the default layer — define default GroupLayer(...) is an error.

Adding Children with .append()

Use .append(ref1, ref2, ...) to add layers as children of a group. All arguments must be layer references:

let panel = GroupLayer('panel') ${};
let bg = PathLayer('bg') ${ fill: #eee; };
bg.apply { rect(0, 0, 200, 200) }

let label = TextLayer('label') ${ font-size: 14; fill: #333; };
label.apply { text(10, 20)`Panel Title` }

// Append children to group
panel.append(bg, label)

Output SVG:

<g>
  <path d="..." fill="#eee" .../>
  <text x="10" y="20" font-size="14" fill="#333">Panel Title</text>
</g>

Appended layers are removed from the top-level output and rendered inside the group.

Nesting Groups

Groups can contain other groups, up to a maximum nesting depth of 10:

let inner = GroupLayer('inner') ${};
let child = PathLayer('child') ${};
child.apply { M 5 5 }
inner.append(child)

let outer = GroupLayer('outer') ${};
outer.append(inner)

Transforms

GroupLayers support both style block transforms and imperative transforms:

// Style block transform
let panel = GroupLayer('panel') ${ transform: translate(50, 100); };

// Imperative transform
panel.ctx.transform.rotate.set(0.785)
panel.ctx.transform.scale.set(2, 2)

When both are present, the style block transform takes precedence.

Moving Layers Between Groups

Appending a layer that already belongs to another group moves it. A warning log is emitted:

let g1 = GroupLayer('g1') ${};
let g2 = GroupLayer('g2') ${};
let child = PathLayer('child') ${};
g1.append(child)  // child is in g1
g2.append(child)  // child moves to g2, warning logged

No Apply Blocks

GroupLayers do not support .apply blocks. Use .append() to add children:

// This is an error:
// g.apply { M 0 0 }

// Use .append() instead:
g.append(myPath)

Limitations

• No nesting apply blocks — layer().apply blocks cannot be nested inside each other
• Layer order — layers render in definition order (first defined = bottom)
• GroupLayer nesting — maximum depth of 10 levels
• PathLayer transforms only — transforms are currently available on PathLayers and GroupLayers via ctx.transform; TextLayer transform support can be added later

Path Blocks

Path Blocks let you define reusable, introspectable paths without immediately drawing them. A PathBlock captures relative path commands and exposes metadata (length, vertices, endpoints) for positioning other elements relative to the path.

Syntax

let myPath = @{
  v 20
  h 30
  v -20
};

@{ opens a Path Block, } closes it. The body contains relative path commands, control flow, variables, and function calls. The result is a PathBlock value — no path commands are emitted.

Drawing a Path Block

Use .draw() to emit the path's commands at the current cursor position:

let shape = @{ v 20 h 20 v -20 z };

M 10 10
shape.draw()     // emits: v 20 h 20 v -20 z
M 50 50
shape.draw()     // reuse at a different position

draw() advances the cursor to the path's endpoint and returns a ProjectedPath with absolute coordinates.

Assigning the draw result

let shape = @{ v 20 h 20 };
M 10 10
let proj = shape.draw();
// proj.startPoint = Point(10, 10)
// proj.endPoint = Point(30, 30)

Drawing at a specific position

Use .drawTo(x, y) to emit M x y followed by the path's commands in a single call. This combines positioning and drawing — no separate M command needed.

let shape = @{ v 20 h 20 v -20 z };

shape.drawTo(10, 10)     // emits: M 10 10 v 20 h 20 v -20 z
shape.drawTo(50, 50)     // reuse at a different position

drawTo() returns a ProjectedPath with absolute coordinates, just like draw():

let shape = @{ v 20 h 30 };
let proj = shape.drawTo(10, 10);
// proj.startPoint = Point(10, 10)
// proj.endPoint = Point(40, 30)

drawTo() also works on ProjectedPath values — it re-positions the projected path to the new origin:

let shape = @{ h 50 v 30 };
let proj = shape.project(0, 0);
proj.drawTo(100, 100)    // emits: M 100 100 h 50 v 30

Drawing a ProjectedPath in place

A ProjectedPath already knows where it lives, so .draw() on one draws it exactly there — no anchor arguments, no cursor dependence:

let pieces = plate.cut(knife);
let placed = pieces[0].project(40, 60);
placed.draw()                    // the piece, exactly where placed says it is

for (seam in placed.segmentAll('cut')) {
  seam.draw()                    // each healed seam, stroked on itself
}

This is the idiom for decorating query results — seams, labeled runs, offsets — where the value's own coordinates are the target. The cursor advances to the path's endpoint, and the same ProjectedPath comes back for chaining.

The drawTo anchor contract. drawTo(x, y) places the value's startPoint — the first inked point — at (x, y). There used to be a trap here: a cut piece's startPoint reported the frame origin rather than where the piece's ink actually starts, so drawTo(p.startPoint.x, p.startPoint.y) silently shifted whole pieces. startPoint is now truthful for every value (get(0) always agrees with it), so drawTo anchors the ink at the target for pieces and seams alike. .draw() remains the one-word spelling for drawing a projected value in place.

One distinction worth knowing: proj.drawTo(x, y) puts the ink at (x, y); M x y followed by block.draw() seats the pen there and lets a leading m in the block offset from it. For blocks with no leading move the two agree exactly.

Projecting Without Drawing

Use .project(x, y) to compute absolute coordinates without emitting commands or moving the cursor:

let shape = @{ v 20 h 30 };
let proj = shape.project(10, 10);
// proj.startPoint = Point(10, 10)
// proj.endPoint = Point(40, 30)
// No path commands emitted, cursor unchanged

Properties

PathBlock

ProjectedPath

Same properties as PathBlock but with absolute coordinates.

subPathCommands entries

Each entry in subPathCommands is an object with:

{
  command: "v",           // lowercase command letter
  args: [20],             // numeric arguments
  start: Point(0, 0),     // cursor before command
  end: Point(0, 20)       // cursor after command
}

Control Flow Inside Path Blocks

Variables, for loops, foreach loops, if statements, and function calls all work inside path blocks:

let zigzag = @{
  for (i in 0..4) {
    v 10
    h calc(i % 2 == 0 ? 10 : -10)
  }
};

Context-aware functions like arcFromPolarOffset, tangentLine, and tangentArc work against the block's temporary path context.

Accessing Outer Variables

Path blocks can read variables from enclosing scope:

let size = 20;
let box = @{ v size h size v calc(-size) z };

First-Class Values

PathBlocks can be passed as function arguments and returned from functions:

fn makeStep(dx, dy) {
  return @{ h dx v dy };
}

let step = makeStep(10, 5);
M 0 0
step.draw()    // emits: h 10 v 5

Using Path Metadata

Access path properties for layout calculations:

let segment = @{ v 20 h 30 };

// Use length to create a matching horizontal line
let total = segment.length;       // 50

// Use endpoint for positioning
let end = segment.endPoint;       // Point(30, 20)
M end.x end.y                     // Position at path endpoint

Restrictions

Path blocks enforce these rules at runtime:

1. Relative commands only — All path commands must be lowercase (m, l, h, v, etc.). Uppercase (absolute) commands throw an error.
2. No layer definitions — define PathLayer/TextLayer is not allowed
3. No layer apply blocks — layer().apply { } is not allowed
4. No text statements — text() / tspan() are not allowed
5. No nesting — Path blocks cannot contain other @{ } expressions
6. No draw/project inside blocks — Calling .draw() or .project() inside a path block throws an error

Parametric Sampling

Parametric sampling lets you query points, tangent directions, and normal directions at any position along a path. The parameter t is a fraction from 0 (start) to 1 (end) measured by arc length.

These methods work on both PathBlock values and ProjectedPath values.

get(t) → Point

Returns the point at arc-length fraction t along the path.

let p = @{ v 50 h 100 };
let mid = p.get(0.5);       // Point roughly at distance 75 along path
M mid.x mid.y               // position at midpoint

tangent(t) → { point, angle }

Returns the point and tangent angle at fraction t. The angle is the direction of travel, as a plain number in radians.

let p = @{ v 50 h 100 };
let tan = p.tangent(0.0);
log(tan.point);              // Point(0, 0)
log(tan.angle);              // ~1.5708 (π/2, pointing down)

normal(t) → { point, angle }

Returns the point and left-hand normal angle at fraction t. The normal angle equals the tangent angle minus π/2.

let p = @{ h 100 };
let n = p.normal(0.5);
log(n.point);                // Point(50, 0)
log(n.angle);                // ~-1.5708 (pointing up — left-hand normal of rightward path)

On cut and boolean results, the normal points away from the piece's material — guaranteed. cut() and the boolean operations each canonicalize their result's winding so material always lies on the same side of the direction of travel, and the normal is a fixed rotation of that travel — so on any seam or boundary edge of a piece, normal(t) faces out of the piece: glue tabs, ticks, and offsets aimed along it point away from the material with no direction test needed. Two footnotes: on a hole's boundary, "away from the material" points into the hole (that is the outside of the material there); and on hand-authored paths there is no such guarantee — the normal is simply left-of-travel, and which side is "outside" depends on how you wound the path.

partition(n) → OrientedPoint[]

Divides the path into n equal-length segments, returning n + 1 oriented points (endpoints inclusive). Each oriented point has point, angle, and t properties.

let p = @{ h 100 };
let pts = p.partition(4);    // 5 points at x = 0, 25, 50, 75, 100
for (op in pts) {
  log(op.point.x, op.angle, op.t);
}
// t values: 0, 0.25, 0.5, 0.75, 1

Sampling on ProjectedPath

Projected paths return absolute coordinates:

let p = @{ h 100 };
let proj = p.project(10, 20);
let mid = proj.get(0.5);    // Point(60, 20) — offset by projection origin

Curve Support

Sampling works on all command types including cubic/quadratic Bézier curves and arcs. Curves use arc-length parameterization so that t = 0.5 always represents the geometric midpoint, not the parametric midpoint.

Transforms

Transforms create new paths from existing ones — reversing direction, computing bounding boxes, and constructing parallel paths. These methods work on both PathBlock values and ProjectedPath values.

reverse() → PathBlock / ProjectedPath

Returns a new path with reversed direction of travel. The reversed path starts where the original ended and ends where the original started.

let p = @{ h 50 v 30 };
let r = p.reverse();
log(r.endPoint);             // Point(-50, -30) — reversed from original
M 100 100
r.draw()                     // draws the path in reverse

Smooth commands (S/T) are automatically converted to their explicit forms (C/Q) before reversal. Closed paths (ending with z) preserve closure.

let closed = @{ h 30 v 30 h -30 z };
let rev = closed.reverse();  // reversed, still ends with z

boundingBox() → { x, y, width, height }

Returns the axis-aligned bounding box of the path. Accounts for Bézier curve extrema and arc extrema — not just endpoints.

let p = @{ c 0 -40 50 -40 50 0 };
let bb = p.boundingBox();
log(bb.y);                    // negative — curve extends above endpoints
log(bb.width, bb.height);    // full extent of the curve

For a straight-line path the bounding box matches the endpoint coordinates:

let line = @{ h 100 };
let bb = line.boundingBox();
// bb = { x: 0, y: 0, width: 100, height: 0 }

intersects(geometry) → Boolean

AABB overlap test — returns true if this path's bounding box overlaps the argument's bounding box. Works on both PathBlock and ProjectedPath values.

Accepted arguments:

let a = @{ h 60 v 40 h -60 z };
let b = @{ h 40 v 30 h -40 z };

// Overlapping — both start at origin
let projA = a.project(0, 0);
let projB = b.project(10, 10);
log(projA.intersects(projB));        // true

// Non-overlapping
let projC = b.project(200, 200);
log(projA.intersects(projC));        // false

Testing against a rectangle object:

let shape = @{ h 50 v 50 h -50 z };
let proj = shape.project(10, 10);
log(proj.intersects({x: 0, y: 0, width: 100, height: 100}));    // true
log(proj.intersects({x: 200, y: 200, width: 10, height: 10}));  // false

Works on unprojected PathBlocks too (bounding box computed from relative coordinates):

let a = @{ h 60 v 40 h -60 z };
let b = @{ h 40 v 30 h -40 z };
log(a.intersects(b));                // true (both at origin)

intersectionPoints(geometry) → Array<Point>

Returns the intersection points between this path's bounding box edges and the geometry's line segments. Works on both PathBlock and ProjectedPath values.

Accepted arguments:

let box = @{ h 100 v 100 h -100 z };
let line = @{ m -10 50 h 120 };

let projBox = box.project(0, 0);
let projLine = line.project(0, 0);
let pts = projBox.intersectionPoints(projLine);
// pts contains the points where the line crosses the box's bounding box edges

Non-overlapping paths return an empty array:

let a = @{ h 50 v 50 h -50 z };
let b = @{ h 10 v 10 h -10 z };
let projA = a.project(0, 0);
let projB = b.project(200, 200);
let pts = projA.intersectionPoints(projB);
log(pts.length);                     // 0

offset(distance, options?) → PathBlock / ProjectedPath

Creates a parallel path offset by distance units. Positive values offset to the left of the travel direction, negative to the right. On pieces produced by cut() and results of boolean operations, winding is canonicalized with material on the left, so a positive distance always grows the piece outward — including through hole boundaries.

let p = @{ h 60 v 40 };
let outer = p.offset(5);     // 5 units left of travel
let inner = p.offset(-5);    // 5 units right of travel

Corners. Where two segments meet, the join is chosen by the corner and the join option:

• Gentle corners between two straight segments keep a sharp miter (the true corner point), up to a miter length of 2× the offset distance — so rectangular offsets stay rectangles.
• Sharper corners, and every corner involving a curve, get a bevel: each segment is offset with its own normals and a short connecting line bridges the gap. Join geometry is never folded into a curve's own shape — a sharp corner cannot distort the curve next to it.
• offset(d, { join: 'round' }) replaces the bevels with circular arcs of radius |distance| centered on the original corner — the offset a rolling pen would draw. { join: 'bevel' } forces bevels even at gentle straight corners; the default is 'miter' (miter where safe, bevel beyond the limit).
• Join options apply only to convex corners — the side the offset opens a gap on. Concave corners are always trimmed back to where the two offset sides cross (exactly for straight segments, by curve subdivision for curves), never given an external connector. One current limitation: a concave corner where an arc segment meets the join falls back to a connector; and an offset distance large enough to swallow a feature entirely (an inward offset wider than half the shape) can still self-intersect rather than collapsing.

A connector between two segments that carry the same segment label inherits that label, so a labeled edge that turns a corner still answers as one run.

Curves. Cubic and quadratic segments are offset as true parallel curves: the curve is subdivided where it bends strongly and each piece is offset via its control polygon, so a deep scoop's offset stays distance away along its whole length — at the cost of the output containing more curve segments than the input. Arcs offset by radius adjustment, quadratics are emitted as cubics.

let curve = @{ c 0 -40 50 -40 50 0 };
let parallel = curve.offset(3);
M 0 50
curve.draw()
M 0 50
parallel.draw()              // parallel curve 3 units to the left

mirror(angle) → PathBlock / ProjectedPath

Reflects the path across a line through the start point at the given angle. The angle uses standard language units (radians).

let p = @{ h 60 v 40 };
let m = p.mirror(0.5pi);       // reflect across vertical axis → goes left
M 100 100
m.draw()

Common angles:

• mirror(0) — horizontal axis (y → -y)
• mirror(0.5pi) — vertical axis (x → -x)
• mirror(0.25pi) — diagonal (swaps x and y)

Mirror preserves path length and curve types. Arc commands have their sweep flag flipped (reflection reverses chirality) and their rotation parameter adjusted.

let curve = @{ c 0 -40 50 -40 50 0 };
let flipped = curve.mirror(0);
M 0 50
curve.draw()
M 0 50
flipped.draw()               // curve reflected below the axis

rotateAtVertexIndex(index, angle) → PathBlock / ProjectedPath

Rotates the path around the vertex at index (from the .vertices array) by angle radians. PathBlockValue results are normalized to (0, 0) start.

let p = @{ h 50 v 50 };
// p.vertices = [Point(0,0), Point(50,0), Point(50,50)]
let r = p.rotateAtVertexIndex(1, 0.5pi);  // rotate around corner
M 10 10
r.draw()

The index must be a non-negative integer within range. The rotation preserves path length and curve types. Arc commands have their rotation parameter adjusted.

// Create a radial pattern by rotating around the first vertex
let arm = @{ h 50 v 10 };
for (i in 0..5) {
  let angle = calc(i * 2 * 3.14159265358979 / 6);
  let r = arm.rotateAtVertexIndex(0, angle);
  M 100 100
  r.draw()
}

rotate(angle, origin?) → PathBlock / ProjectedPath

Rotates the path by angle around origin — a Point, defaulting to the block origin (0, 0) when omitted. The angle accepts plain radians or Angle values (0.5pi, 45deg).

let arm = @{
  h 50
  v 10
};
let quarter = arm.rotate(0.5pi);          // about the block origin
let spun = arm.rotate(45deg, Point(25, 5));  // about the arm's center

Unlike rotateAtVertexIndex, the result is not re-based: the geometry rotates about the pivot inside the block's own coordinate frame and stays where it is. A piece that carries placement — a cut() shard, for example — keeps that placement, so rotating it in place needs no compensation:

let plate = @{
  h 60
  v 40
  h -60
  z
};
let knife = @{
  m 30 -10
  l 0 60
};
let pieces = plate.cut(knife);
for ([p, i] in pieces) {
  let pb = p.boundingBox();
  let c = Point(calc(pb.x + pb.width / 2), calc(pb.y + pb.height / 2));
  let spunPiece = p.rotate(0.1, c);
  M 20 20
  spunPiece.draw();
}

rotate(a) with no origin is equivalent to rotateAtVertexIndex(0, a) when the path starts at the origin. Rotation preserves path length and curve types; arc commands have their rotation parameter adjusted. Segment and endpoint labels survive (see Labels Survive Derived Paths).

scale(sx, sy) → PathBlock / ProjectedPath

Scales the path from its start point. sx scales x-coordinates, sy scales y-coordinates.

let p = @{ h 50 v 30 };
let doubled = p.scale(2, 2);      // endPoint (100, 60)
let wide = p.scale(3, 1);         // endPoint (150, 30)
let flipped = p.scale(-1, 1);     // mirror across y-axis

Uniform scaling (sx == sy) preserves shape and scales arc radii proportionally. Non-uniform scaling (sx != sy) performs full ellipse eigendecomposition to compute new arc radii and rotation. Negative scale values flip the arc sweep flag (reflection reverses chirality).

let arc = @{ a 25 25 0 0 1 50 0 };
let wide = arc.scale(2, 1);       // stretched elliptical arc
let big = arc.scale(3, 3);        // uniform: radii tripled

subPath(startT, endT) → PathBlock

Extracts the geometric portion of a path between two arc-length fractions. Both startT and endT must be between 0 and 1. Always returns a PathBlock (normalized to (0, 0) origin), even when called on a ProjectedPath.

let p = @{ h 100 v 100 };
let first = p.subPath(0, 0.5);    // first half of the path
let second = p.subPath(0.5, 1);   // second half of the path
M 10 10
first.draw()
M 10 10
second.draw()                      // visually reconstructs the original

If startT > endT, the result is reversed (equivalent to .subPath(endT, startT).reverse()):

let p = @{ h 100 };
let rev = p.subPath(1, 0);        // full path, reversed direction

Use .get() on the ProjectedPath to find the absolute position, then .draw() the extracted PathBlock:

let p = @{ h 100 v 50 };
let proj = p.project(10, 20);
let start = proj.get(0.2);
let sub = proj.subPath(0.2, 0.8);  // PathBlock, normalized to (0,0)
M start.x start.y
sub.draw()                          // draws the middle 60% at the right position

Edge cases:

• subPath(0, 1) returns approximately the original path
• subPath(t, t) returns an empty PathBlock (not an error)
• Works with all command types including curves and arcs

let curve = @{ c 0 -40 50 -40 50 0 };
let front = curve.subPath(0, 0.5);
M 0 50
curve.draw()
M 0 80
front.draw()                        // first half of the Bézier curve

Transforms on ProjectedPath

Projected paths return results in absolute coordinates:

let p = @{ h 100 };
let proj = p.project(10, 20);
let bb = proj.boundingBox();
// bb.x = 10, bb.y = 20 — absolute coordinates

let rev = proj.reverse();
log(rev.startPoint);         // Point(110, 20) — starts at original end

For mirror() on a ProjectedPath, the mirror line passes through the projection's start point. For rotateAtVertexIndex(), the rotation center is the absolute vertex position. For rotate(), the origin is an absolute point; when omitted, the pivot defaults to the projection's start point.

let p = @{ h 50 };
let proj = p.project(100, 100);
let m = proj.mirror(0.5pi);
// Mirrors across vertical line through (100, 100)
// startPoint stays at (100, 100), endPoint moves to (50, 100)

For scale() on a ProjectedPath, the scale center is the projection's start point:

let p = @{ h 50 v 30 };
let proj = p.project(10, 20);
let s = proj.scale(2, 2);
// startPoint stays at (10, 20), endPoint moves to (110, 80)

Concatenation (<<)

The << operator joins two PathBlocks end-to-end. The right path's relative commands continue from where the left path ends.

let a = @{ h 50 };
let b = @{ v 30 };
let c = calc(a << b);               // endPoint (50, 30)
M 10 10
c.draw()                             // draws "h 50 v 30"

Chaining works naturally since << is left-associative and the result is a PathBlock:

let a = @{ h 50 };
let b = @{ v 30 };
let d = calc(a << b << a);          // endPoint (100, 30)

Self-concatenation repeats the path:

let p = @{ h 50 };
let doubled = calc(p << p);         // endPoint (100, 0)

Concatenated paths support all PathBlock methods — draw, project, sampling, and transforms:

let combined = calc(a << b);
let rev = combined.reverse();
let mid = combined.get(0.5);

The << operator also works for style block merging. The operand types must match — mixing PathBlocks and style blocks throws an error. << has one more job on PathBlocks: applying a worker function to a variableOffset()/compoundVariableOffset() call written without a trailing block.

Chamfers

Chamfers cut corners by replacing a vertex with a straight line segment. The incoming and outgoing edges are trimmed by the specified distance, and a line connects the two trim points.

chamfer(distance) → PathBlock / ProjectedPath

Chamfers all corner vertices with equal distance on both sides:

let box = @{ h 60 v 40 h -60 z };
let chamfered = box.chamfer(8);
M 10 10
chamfered.draw()

chamfer(d1, d2) → PathBlock / ProjectedPath

Asymmetric chamfer — d1 is the trim distance on the incoming edge, d2 on the outgoing edge:

let box = @{ h 60 v 40 h -60 z };
let asym = box.chamfer(5, 15);
M 10 10
asym.draw()

chamferAtVertex(index, distance) → PathBlock / ProjectedPath

Chamfers a single vertex by index (from the .vertices array):

let box = @{ h 60 v 40 h -60 z };
// box.vertices: Point(0,0), Point(60,0), Point(60,40), Point(0,40)
let oneCorner = box.chamferAtVertex(1, 10);
M 10 10
oneCorner.draw()

chamferAtVertex(index, d1, d2) → PathBlock / ProjectedPath

Asymmetric chamfer at a single vertex:

let box = @{ h 60 v 40 h -60 z };
let asym = box.chamferAtVertex(2, 5, 15);
M 10 10
asym.draw()

Edge cases

If the chamfer distance exceeds the available edge length, it is clamped to the edge length and a warning is logged. If the vertex index is out of range, an error is thrown.

Chamfers work with all command types — lines, curves, and arcs. For curves, the trim operation uses arc-length parameterization to find the exact split point.

Fillets

Fillets round corners by replacing a vertex with a circular arc. The incoming and outgoing edges are trimmed, and an arc tangent to both edges is inserted.

Scope: Line-line junctions only. At curve junctions, the fillet is skipped and a warning is logged.

Name-based alternative: instead of a numeric vertex index, you can label a vertex with as endpoint('name') and round it with pb.vertex('name').fillet(radius) — or attach the fillet where you draw the corner with with fillet(radius). Labels don't break when commands are added earlier in the path. See Segment Labels & Corner Suffixes.

fillet(radius) → PathBlock / ProjectedPath

Fillets all corner vertices with the given radius:

let box = @{ h 60 v 40 h -60 z };
let rounded = box.fillet(8);
M 10 10
rounded.draw()

filletAtVertex(index, radius) → PathBlock / ProjectedPath

Fillets a single vertex:

let box = @{ h 60 v 40 h -60 z };
let oneRound = box.filletAtVertex(1, 12);
M 10 10
oneRound.draw()

If the radius is too large for the available edge length, it is clamped and a warning is logged. If the vertex index is out of range, an error is thrown.

Elliptical Fillets

Elliptical fillets replace a corner with an elliptical arc instead of a circular one, allowing for more expressive corner shapes.

Scope: Line-line junctions only (same as circular fillets).

ellipticalFillet(rx, ry) → PathBlock / ProjectedPath

Fillets all corners with an elliptical arc of radii rx and ry:

let box = @{ h 60 v 40 h -60 z };
let eFilleted = box.ellipticalFillet(12, 6);
M 10 10
eFilleted.draw()

ellipticalFillet(rx, ry, rotation) → PathBlock / ProjectedPath

Elliptical fillet with a rotated ellipse (rotation in radians, default 0):

let box = @{ h 60 v 40 h -60 z };
let rotated = box.ellipticalFillet(12, 6, 0.3);
M 10 10
rotated.draw()

ellipticalFilletAtVertex(index, rx, ry) → PathBlock / ProjectedPath

Elliptical fillet at a single vertex:

let box = @{ h 60 v 40 h -60 z };
let one = box.ellipticalFilletAtVertex(1, 15, 8);
M 10 10
one.draw()

ellipticalFilletAtVertex(index, rx, ry, rotation) → PathBlock / ProjectedPath

Elliptical fillet at a single vertex with rotation:

let box = @{ h 60 v 40 h -60 z };
let one = box.ellipticalFilletAtVertex(2, 15, 8, 0.5);
M 10 10
one.draw()

Boolean Operations

The four set operations — union, difference, intersection, and xor — combine two closed paths. Both operands must be closed (end with z or have coincident start and end points). The result preserves original curve types — no linearization. To slice a path along open cut lines instead, see Cutting Paths.

See also: Standard Library path functions for creating shapes to use with boolean operations.

union(other) → PathBlock

Combines two paths into their union (outer boundary):

let a = @{ circle(0, 0, 30); };
let b = @{ circle(0, 0, 30); };
let combined = a.project(50, 50).union(b.project(70, 50));

difference(other) → PathBlock

Subtracts other from the path:

let plate = @{ circle(0, 0, 40); };
let hole = @{ circle(0, 0, 15); };
let result = plate.project(50, 50).difference(hole.project(50, 50));

intersection(other) → PathBlock

Returns only the overlapping region:

let a = @{ circle(0, 0, 30); };
let b = @{ circle(0, 0, 30); };
let overlap = a.project(50, 50).intersection(b.project(70, 50));

xor(other) → PathBlock

Returns the symmetric difference — everything in either path but not both:

let a = @{ circle(0, 0, 30); };
let b = @{ circle(0, 0, 30); };
let exclusive = a.project(50, 50).xor(b.project(70, 50));

Requirements and behavior

• Both paths must be closed for union, difference, intersection, and xor. Open paths throw an error. (cut() is the exception — its cutter is usually open, and its subject may be too.)
• The other argument can be a PathBlock or ProjectedPath.
• Multi-component results produce multiple subpaths (M...z M...z).
• All curve types (lines, cubics, quadratics, arcs) are preserved through the operation.
• Results are always returned as PathBlock values (normalized to (0, 0) origin).
• Segment and endpoint labels from both operands survive into the result (see Labels Survive Derived Paths).

Cutting Paths

Where the set operations combine two closed shapes, cut() slices one shape along cut lines — like drawing a knife across it — and hands back the resulting pieces. Each piece is a complete PathBlock, healed shut along the lines that cut it (a cut open path is the exception: its pieces stay open fragments).

Debug mode: cut() is not yet supported in the CLI's --annotated debug mode. It works normally everywhere else — CLI compilation, the playground, and the VS Code preview.

cut(cutter) → array of PathBlock

Cuts the path along every stroke of cutter and returns the pieces. The cutter may be a single PathBlock or ProjectedPath, or an array of them — every knife in the array cuts, exactly as if their strokes lived in one block. Arrays make cutters compositional: build knives in a loop and hand the whole set to one cut() call.

One conversion caveat: each array element is its own block, so its m/l deltas resolve relative to that block's own origin — not to where the previous knife in the array left off. If you're splitting an existing multi-stroke knife block into an array, recompute each knife's starting move relative to the origin rather than copying a chained delta verbatim; a copied delta compiles fine and cuts in the wrong place.

let disc = @{
  circle(0, 0, 90);
};
let knives = [];
for (k in 0..7) {
  let spokeAngle = calc(k * PI() / 4);
  knives.push(@{
    m calc(36 * cos(spokeAngle)) calc(36 * sin(spokeAngle))
    l calc(76 * cos(spokeAngle)) calc(76 * sin(spokeAngle))
  });
}
knives.push(@{
  circle(0, 0, 36);    // the ring the spokes anchor to
});
let panes = disc.cut(knives);    // eight ring panes + the medallion

let box = @{
  h 60
  v 40
  h -60
  z
};
let knife = @{
  m 30 -10
  l 0 60
};
let pieces = box.cut(knife);
log(pieces.length);    // 2

Each subpath of the cutter is one knife stroke, and strokes may be lines or curves. An open stroke slices the shape wherever it crosses. A closed loop acts as a cookie cutter, stamping out the region inside it — and the loop doesn't have to be authored with z: separate strokes whose endpoints meet are recognized as a loop geometrically:

let box = @{
  h 60
  v 40
  h -60
  z
};
let stamp = @{ circle(0, 0, 10); };
let pieces = box.cut(stamp.project(30, 20));
log(pieces.length);    // 2 — the stamped-out disk, and the box now carrying a hole

Alignment works exactly like the set operations: both blocks are overlaid in block-local coordinates, and you position the cutter with project():

let plate = @{ circle(0, 0, 40); };
let knife = @{
  l 100 20
};
let pieces = plate.project(50, 50).cut(knife.project(0, 40));
log(pieces.length);    // 2

Pieces keep their original placement inside the subject, so drawing them all at the same position reassembles the shape — and offsetting each one produces an exploded view:

let box = @{
  h 60
  v 40
  h -60
  z
};
let knife = @{
  m 30 -10
  l 0 60
};
let pieces = box.cut(knife);

for ([piece, i] in pieces) {
  M calc(20 + i * 10) 20
  piece.draw()
}

Cutting works on multi-contour subjects — a glyph, a donut, a shape with holes. Here the knife crosses both contours of an 'O' (from PathBlock.fromGlyph), so each piece's boundary follows the outer edge, the cut line, and the inner edge — two C-shapes:

@font "Inter";
let styles = ${ font-family: Inter; font-size: 96; };
let glyphs = PathBlock.fromGlyph("O", styles);
let knife = @{ m -10 -40 l 90 8 };
let pieces = glyphs[0].cut(knife);
log(pieces.length);    // 2 — two C-shaped pieces

A hole the cut misses isn't lost — it rides along as an extra subpath inside whichever piece contains it (inspect it with contours).

Open subjects can be cut too. Cutting an open path severs it at each crossing and returns the open fragments — no healing, since there is no interior to close:

let wave = @{
  q 20 -20 40 0
  q 20 20 40 0
};
let knife = @{
  m 30 -30
  l 0 60
};
let parts = wave.cut(knife);    // 2 open fragments

Because every piece is a full PathBlock, styling them individually is just iteration — cut once, then route pieces to differently-styled layers:

let warm = PathLayer(`warm`) ${ fill: #e0b17c; stroke: #40311f; stroke-width: 1; };
let cool = PathLayer(`cool`) ${ fill: #7c9ce0; stroke: #1f2540; stroke-width: 1; };

let disc = @{ circle(0, 0, 40); };
let knives = @{
  m -20 -50
  l 0 100
  m 20 -100
  l 0 100
  m 20 -100
  l 0 100
};
let slices = disc.cut(knives);    // 4 slices

for ([piece, i] in slices) {
  if (calc(i % 2) == 0) {
    warm.apply {
      M calc(50 + i * 6) 50
      piece.draw()
    }
  } else {
    cool.apply {
      M calc(50 + i * 6) 50
      piece.draw()
    }
  }
}

seams() → array of PathBlock

Every interior seam exists twice in the pieces — once in each adjacent piece — so decorating seams per piece draws each one twice (visible with dashed strokes, whose opposite-direction passes fill each other's gaps). seams(), called on the array cut() returns, answers with each physical seam exactly once:

let pieces = card.cut(creases);
for (seam in pieces.seams()) {
  foldLayer.apply {
    seam.project(20, 30).draw();    // each fold drawn once, by contract
  }
}

The returned seams are PathBlocks that keep subject-local placement, exactly like the pieces themselves — draw them at the same origin you draw the pieces (M x y + seam.draw(), or seam.project(x, y).draw()) and they land on the cuts. Each seam's direction of travel is unspecified (it comes from whichever piece was encountered first). A cookie cutter's ring is one closed seam (it closes with z, so dashes wrap); a knife split by a crossing knife counts as one seam per crossing-bounded fragment.

Details worth knowing:

• Seam normals face outward. On any piece's seams and boundary edges, normal(t) points away from the piece's material — guaranteed by the same winding canonicalization that powers the cut (see the normal(t) docs for the hole footnote).
• Chained cuts compose. Cut a piece again and its inherited seams stay identified: subPieces.seams() returns the new cut's seams plus each surviving fragment of the older seams, every physical stretch exactly once.
• Severing an open path creates no healed boundary, so seams() on an open subject's fragments is empty.
• seams() is answered from identity the cut records into the pieces — call it on arrays whose elements came from cut(). Hand-built pieces don't carry it, and transformed copies may change how sides pair (after offset() the two sides of a seam are genuinely different curves, so both return; corner-shaping ops may drop the identity entirely). When in doubt, query seams() on the cut result itself and transform the seams.

Cutting behavior

Arguments and results

• The cutter argument can be a PathBlock or ProjectedPath; so can the receiver. Pieces always come back as PathBlock values, even from a ProjectedPath receiver.
• Pieces keep their original placement inside the subject (like the set operations, results are normalized to a (0, 0) origin). Drawing every piece at one position reassembles the shape.
• Piece order is deterministic but unspecified — style pieces by iterating, not by assuming which index is which.
• Labels survive: pieces keep the subject's as segment(...) / as endpoint(...) names on their surviving boundary fragments, and every healed seam edge carries the automatic segment label cut (query the seams with segmentAll('cut')). See Labels Survive Derived Paths.
• Name your knives. A cutter edge labeled as segment('valley') stamps the seams it heals with the sub-label cut.valley. segmentAll('cut') still returns every seam — sub-labeled or not, merged into runs exactly as before — while segmentAll('cut.valley') answers just that knife's seams. Unlabeled cutter edges, cookie boundaries, and bridging segments stay plain cut (a bridge that seals a gap inside one named knife's seam inherits that knife's name, so the run stays contiguous). Because cut() takes an array of cutters, each knife can carry its own name: mountain and valley folds, cut in one call, dashed differently. Query pseudo-selectors compose with the namespace — segment('cut:first'), segmentAll('cut.valley:atomic'). The cutter's endpoint labels do not propagate — seam identity is a per-edge affair.

Tolerances and fidelity

• A cutter endpoint that lands on the subject's boundary — or close to it — snaps onto the boundary and completes the cut there (a T-junction). "Close" means about half a unit for typical viewBox-scale drawings, growing with the drawing's size (max(0.5, bounding-box diagonal × 0.001)) — so on very small coordinate systems the snap is proportionally generous. The same snapping applies when a stroke passes through a subject vertex.
• All curve types are preserved through the cut; the healed edges follow the cutter's own geometry.

Strokes that don't cut

• A stroke that ends deep inside the shape without reaching the far boundary does not cut — that stroke is ignored and the region stays whole. Cutting never invents geometry beyond the tolerance snap.
• A stroke that only grazes the boundary tangentially, or runs collinear along an edge, also leaves the shape whole.
• Portions of the cutter outside the shape (or inside a hole) are ignored.
• A cutter that never touches the shape — or has no drawable strokes at all — returns a single-element array containing the original. Cutting an empty PathBlock returns an empty array.

Compound cases

• Strokes crossing each other inside the shape subdivide it together: an X of two strokes produces four pieces from one region.
• A subject mixing closed and open subpaths returns both kinds of pieces: healed closed pieces for the closed contours, open fragments for the open ones.
• In rare degenerate cases — a fragment that can't be traced cleanly, or a sliver thinner than the geometric tolerance — cut() drops the fragment and emits a [warn] entry in the log output rather than failing.

Font Integration

Font integration lets you convert text characters into PathBlock values — turning each glyph into vector paths you can draw, transform, sample, and combine with boolean operations.

@font Directive

The @font directive declares a font for use in the program. It must appear at the top level (not inside a function or block).

@font "Inter";
@font "Roboto Mono" 700;
@font "./fonts/CustomFont.ttf";

The source can also be a variable, as long as it is a top-level let bound to a plain string literal:

let family = "Inter";

@font family;
@font family 700;

Syntax:

@font "family-or-path" [weight];
@font <variable> [weight];