@@ -2,6 +2,18 @@
 
 ## 3.12.0
 
+### New
+
+- Variable fonts: `renderText()` renders the instance `TextStyle.variations` asks for, by axis names (`weight`,
+  `width`, `slant`, `italic`, `opticalSize`) or tags (like Roboto Flex's `GRAD`), clamped to the axes' ranges; the
+  optical size is the font size unless given, like browsers' `font-optical-sizing: auto`. `renderSVG()` maps
+  `font-weight`, `font-stretch` and `font-style` to the axes like browsers and resvg do, with `font-optical-sizing`
+  and `font-variation-settings`, and matches a variable font's ranges of weights and stretches like several faces.
+  TrueType outlines (gvar, with the interpolation of untouched points), advances (HVAR, else gvar's phantom points),
+  metrics (MVAR), GPOS adjustments and anchors (variation indices), feature variations and hinting (cvar) vary;
+  CFF2 outlines aren't supported yet. Outlines and advances are the same as fontTools' and HarfBuzz's, shaping is
+  within HarfBuzz's rounding, and all 14 of resvg's `font-variation-settings` tests pass.
+
 ### Changes
 
 - AVIFs without an ICC profile whose nclx box (or sequence header) gives other color primaries than sRGB's (Display
 
@@ -56,7 +56,7 @@ and encoded as GIF, APNG or WebP, all at once or
 P3, Adobe RGB, ...) are converted to sRGB when decoding, so images look the way browsers show them.
 
 - [Text rendering](https://imagescript.matmen.dev/classes/Image.html#rendertext) with TrueType and OpenType fonts:
-  all scripts, color emoji
+  all scripts, color emoji, variable fonts
 - [SVG rendering](https://imagescript.matmen.dev/classes/Image.html#rendersvg), including text (with fonts you pass
   or fonts embedded in the SVG)
 - [Resizing](https://imagescript.matmen.dev/classes/Image.html#resize),
 
@@ -1,10 +1,9 @@
 # Writes tests/fonts/resvg: resvg's test fonts (github.com/linebender/resvg, crates/resvg/tests/fonts, with their
 # licenses) subset to the characters of the test cases in tests/svgs/resvg and the ones their letters and
-# marks compose to (the shaper composes them where a font has them), with all names and layout features. Its small
-# subsets (emoji, CFF and sbix) are copied as they are, Roboto Flex (variable fonts aren't supported) left out. Needs
-# fontTools:
+# marks compose to (the shaper composes them where a font has them), with all names and layout features (and the
+# variations of Roboto Flex). Its other small subsets (emoji, CFF and sbix) are copied as they are. Needs fontTools:
 #   RESVG_FONTS=path/to/resvg/crates/resvg/tests/fonts python scripts/resvg-test-fonts.py
-import os, shutil, unicodedata
+import os, re, shutil, unicodedata
 from pathlib import Path
 from fontTools import subset
 from fontTools.ttLib import TTFont
@@ -19,19 +18,23 @@
     content = case.read_text(encoding='utf-8')
     if '<text' in content:
         used |= set(content)
+# (Roboto Flex, variable with many axes, only the characters of the cases that use it)
+flex = set()
+for case in (root / 'tests' / 'svgs' / 'resvg').rglob('*.svg'):
+    content = case.read_text(encoding='utf-8')
+    if 'Roboto Flex' in content:
+        flex |= set(''.join(re.findall(r'>([^<]*)</text>', content)))
 marks = [c for c in used if unicodedata.combining(c)]
 composed = {unicodedata.normalize('NFC', b + m) for b in used for m in marks}
 characters = sorted(ord(c) for c in used | {c for c in composed if len(c) == 1})
 
 for path in sorted(source.iterdir()):
     name = path.name
-    if name.startswith('RobotoFlex'):
-        continue
     if path.suffix not in ('.ttf', '.otf'):
         if 'LICENSE' in name or 'OFL' in name:
             shutil.copy(path, target / name)
         continue
-    if '.subset.' in name or name.startswith('CFF-and-SBIX'):
+    if ('.subset.' in name and not name.startswith('RobotoFlex')) or name.startswith('CFF-and-SBIX'):
         shutil.copy(path, target / name)
         continue
     options = subset.Options()
@@ -44,6 +47,6 @@
     options.legacy_kern = True
     font = TTFont(path)
     subsetter = subset.Subsetter(options)
-    subsetter.populate(unicodes=characters)
+    subsetter.populate(unicodes=sorted(ord(c) for c in flex) if name.startswith('RobotoFlex') else characters)
     subsetter.subset(font)
     font.save(target / name)
@@ -292,6 +292,15 @@ export interface TextStyle {
      * `kern`), a number picks an alternate (`salt: 2`). Fonts without a feature ignore it. Default: `{}`
      */
     features?: Record<string, boolean | number>;
+    /**
+     * The instance of variable fonts, by their axes: `weight` (1-1000, like CSS's `font-weight`: 400 regular, 700
+     * bold), `width` (percent of the normal width: 75 condensed, 125 expanded), `slant` (degrees, negative leans
+     * right), `italic` (`true`/`false`), `opticalSize` (the size the glyphs are designed for, in pixels; default: the
+     * font size, like browsers' `font-optical-sizing: auto`), and other axes by their 4-character tag (like Roboto
+     * Flex's `GRAD: 50`). Values outside an axis's range are clamped, axes a font doesn't have are ignored, fonts
+     * without axes aren't affected. Default: `{}` (the fonts' default instances)
+     */
+    variations?: Record<string, number | boolean>;
 }
 
 /** Options of {@link Image.cropCircle} */
@@ -2429,7 +2438,8 @@ export class Image {
     static renderText(font: BinaryData | BinaryData[], size: number, text: string, color?: Color, layout?: TextLayout, style?: TextStyle): Promise<Image>;
     static async renderText(font: BinaryData | BinaryData[], size: number, text: string, colorOrOptions: Color | TextOptions = 0xffffffff, layoutArgument?: TextLayout, styleArgument: TextStyle = {}): Promise<Image> {
         const options: TextOptions = isOptions(colorOrOptions) ? colorOrOptions : { ...styleArgument, color: colorOrOptions, layout: layoutArgument };
-        const { color = 0xffffffff, layout = new TextLayout(), strokeWidth = 0, strokeColor = 0x000000ff, hinting = true, features = {} } = options;
+        const { color = 0xffffffff, layout = new TextLayout(), strokeWidth = 0, strokeColor = 0x000000ff, hinting = true, features = {}, variations = {} } = options;
+        const axes = textRenderer.axisValues(variations);
         size = finite(size, 'font size');
         if (finite(strokeWidth, 'stroke width') < 0)
             throw new RangeError('Invalid stroke width');
@@ -2438,7 +2448,7 @@ export class Image {
 
         const [r, g, b, a] = Image.colorToRGBA(color);
         // color glyph layers in the text color take it without its alpha, which applies to the whole color glyph
-        const rendered = await textRenderer.render(fonts.map(view), size, text, layout, hinting, (r << 24 | g << 16 | b << 8 | 255) >>> 0, featureList(features));
+        const rendered = await textRenderer.render(fonts.map(view), size, text, layout, hinting, (r << 24 | g << 16 | b << 8 | 255) >>> 0, featureList(features), axes);
 
         // the outline needs room around the glyphs
         const pad = Math.ceil(strokeWidth);
 
@@ -214,6 +214,9 @@ export class Hinter {
         const cvt = table('cvt ');
         this.cvt = new Int16Array(cvt.length >> 1);
         for (let i = 0; i < this.cvt.length; i++) this.cvt[i] = font.i16(font.tables['cvt '].offset + i * 2);
+        // (a variable font's instance: the values moved by cvar's deltas, rounded to font units like FreeType does)
+        const deltas = font.cvtDeltas(this.cvt.length);
+        if (deltas) for (let i = 0; i < this.cvt.length; i++) this.cvt[i] = Math.round(this.cvt[i] + deltas[i]);
 
         const maxp = font.tables.maxp.offset;
         const version = font.u32(maxp);
 
@@ -40,6 +40,9 @@ export interface FontFace {
     style: FontStyle;
     /** 1 (ultra-condensed) - 9 (ultra-expanded), 5 is normal */
     stretch: number;
+    /** a variable font's ranges: of weights and stretches (its wght and wdth axes), whether it has italics (ital) and
+     * obliques (negative slnt); null for other fonts */
+    ranges: { weight: [number, number] | null, stretch: [number, number] | null, italic: boolean, oblique: boolean } | null;
     /** the generic families it fits (serif, sans-serif, monospace, cursive, fantasy) */
     generic: Set<string>;
     /** metrics in font units */
@@ -122,8 +125,20 @@ export function fontFace(data: Uint8Array, descriptors?: { family?: string, weig
     else if ((familyType === 2 && serifStyle >= 2 && serifStyle <= 10) || (familyClass >= 1 && familyClass <= 7 && familyClass !== 6)) generic.add('serif');
     else if ((familyType === 2 && serifStyle >= 11 && serifStyle <= 15) || familyClass === 8) generic.add('sans-serif');
 
+    // (a variable font's: by its axes)
+    const axis = (tag: string) => font.axes.find(a => a.tag === tag);
+    const wght = axis('wght'), wdth = axis('wdth'), ital = axis('ital'), slnt = axis('slnt');
+    const classes = (min: number, max: number): [number, number] | null => {
+        const lo = STRETCH_PERCENT.findIndex(p => p >= min), hi = STRETCH_PERCENT.filter(p => p <= max).length - 1;
+        return lo >= 0 && hi >= lo ? [lo + 1, hi + 1] : null;
+    };
+    const ranges = font.axes.length ? {
+        weight: wght ? [wght.min, wght.max] as [number, number] : null, stretch: wdth ? classes(wdth.min, wdth.max) : null,
+        italic: !!ital && ital.max >= 1, oblique: !!slnt && slnt.min < 0,
+    } : null;
+
     const face: FontFace = {
-        font, families: families.map(name => name.toLowerCase()), weight, style, stretch, generic,
+        font, families: families.map(name => name.toLowerCase()), weight, style, stretch, ranges, generic,
         ascent, descent, xHeight,
         underlinePosition: post >= 0 ? font.i16(post + 8) : -Math.trunc(units / 9),
         underlineThickness,
@@ -141,12 +156,26 @@ export interface FontQuery {
     weight: number;
     style: FontStyle;
     stretch: number;
+    /** font-variation-settings: axis values by tag */
+    variations: Record<string, number>;
+    /** font-optical-sizing: whether a variable font's optical size is the font size (auto) */
+    opticalSizing: boolean;
 }
 
+// the percentages of the stretches 1-9 (CSS font-stretch keywords)
+const STRETCH_PERCENT = [50, 62.5, 75, 87.5, 100, 112.5, 125, 150, 200];
+
 const GENERIC = new Set(['serif', 'sans-serif', 'monospace', 'cursive', 'fantasy']);
 
-// the face of a family that matches the query best (CSS Fonts' font matching: stretch, then style, then weight)
-function bestMatch(candidates: FontFace[], query: FontQuery): FontFace {
+// the face of a family that matches the query best (CSS Fonts' font matching: stretch, then style, then weight; a
+// variable font's ranges match what they include, else by their nearest end)
+function bestMatch(faces: FontFace[], query: FontQuery): FontFace {
+    const clamp = (v: number, range: [number, number] | null | undefined, own: number): number => range ? Math.min(Math.max(v, range[0]), range[1]) : own;
+    const candidates = faces.map(f => !f.ranges ? f : {
+        ...f, face: f, weight: clamp(query.weight, f.ranges.weight, f.weight), stretch: clamp(query.stretch, f.ranges.stretch, f.stretch),
+        style: query.style === 'italic' && f.ranges.italic ? 'italic' : query.style === 'oblique' && f.ranges.oblique ? 'oblique' : f.style,
+    });
+    const original = (f: FontFace): FontFace => (f as FontFace & { face?: FontFace }).face ?? f;
     const pick = (values: number[], wanted: number, below: boolean): number => {
         if (values.includes(wanted)) return wanted;
         const lower = values.filter(v => v < wanted).sort((a, b) => b - a), higher = values.filter(v => v > wanted).sort((a, b) => a - b);
@@ -166,7 +195,32 @@ function bestMatch(candidates: FontFace[], query: FontQuery): FontFace {
         const up = weights.filter(v => v > w && v <= 500).sort((a, b) => a - b)[0];
         weight = up ?? pick(weights.filter(v => v < w || v > 500), w, true);
     } else weight = pick(weights, w, w < 400);
-    return list.find(f => f.weight === weight) as FontFace;
+    return original(list.find(f => f.weight === weight) as FontFace);
+}
+
+const variedFaces = new WeakMap<FontFace, Map<string, FontFace>>();
+
+/**
+ * A face at a span's instance of its variable font (like usvg's): wght by the weight, wdth by the stretch, ital for
+ * italic, slnt -12 for oblique, opsz by the font size (with optical sizing), then font-variation-settings; the face
+ * itself for other fonts
+ */
+export function variedFace(face: FontFace, query: FontQuery, fontSize: number): FontFace {
+    if (!face.font.axes.length) return face;
+    const values: Record<string, number> = { wght: query.weight };
+    if (query.stretch !== 5) values.wdth = STRETCH_PERCENT[query.stretch - 1];
+    if (query.style === 'italic') values.ital = 1;
+    if (query.style === 'oblique') values.slnt = -12;
+    if (query.opticalSizing) values.opsz = fontSize;
+    const font = face.font.withVariations({ ...values, ...query.variations });
+    if (font === face.font) return face;
+    let byCoords = variedFaces.get(face);
+    if (!byCoords) variedFaces.set(face, byCoords = new Map<string, FontFace>());
+    const key = font.coords.join(',');
+    let varied = byCoords.get(key);
+    // (the ascent and descent moved like the font's, by MVAR)
+    if (!varied) byCoords.set(key, varied = { ...face, font, ascent: face.ascent + font.ascender - face.font.ascender, descent: face.descent + font.descender - face.font.descender });
+    return varied;
 }
 
 /**
@@ -256,6 +310,20 @@ function colorKind(face: FontFace, glyph: number, fontSize: number): ColorKind |
     return null;
 }
 
+/**
+ * font-variation-settings: normal, or quoted 4-character tags with a number each (comma separated; invalid ones are
+ * left out, the last of a tag counts)
+ */
+export function parseVariationSettings(value: string): Record<string, number> {
+    const out: Record<string, number> = {};
+    if (value.trim().toLowerCase() === 'normal') return out;
+    for (const part of value.split(',')) {
+        const m = /^\s*(["'])(.{4})\1\s+([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*$/i.exec(part);
+        if (m) out[m[2]] = Number(m[3]);
+    }
+    return out;
+}
+
 /** the generic and named families of a font-family value, lowercase */
 export function parseFontFamilies(value: string): string[] {
     const families: string[] = [];
@@ -418,7 +486,10 @@ function shapeChunk<S>(chunk: ChunkInput<S>, fonts: FontFace[], primary: Map<Spa
         if (base) {
             const grapheme = cps.slice(start, end);
             let face: FontFace = base;
-            if (!grapheme.every(c => isDefaultIgnorableCodepoint(c) || base.font.glyphIndex(c))) face = fallbackFont(fonts, base, grapheme, new Set([base])) ?? base;
+            if (!grapheme.every(c => isDefaultIgnorableCodepoint(c) || base.font.glyphIndex(c))) {
+                const other = fallbackFont(fonts, base, grapheme, new Set([base]));
+                face = other && span ? variedFace(other, span.font, span.fontSize) : base;
+            }
             faceOf.fill(face, start, end);
             if (face !== base) fallback.fill(face, start, end);
         }
@@ -902,7 +973,7 @@ export function layOutText<S>(text: TextInput<S>, fonts: FontFace[]): TextOutput
     const primary = new Map<SpanInput<S>, FontFace>();
     for (const chunk of text.chunks) for (const span of chunk.spans) {
         const face = matchFont(fonts, span.font);
-        if (face) primary.set(span, face);
+        if (face) primary.set(span, variedFace(face, span.font, span.fontSize));
     }
 
     const spans: SpanOutput<S>[] = [];
 
@@ -17,7 +17,7 @@ import { base64 } from '../util/bytes.ts';
 import { gunzip } from '../codecs/zlib.ts';
 import { applyFilter, Filter, Primitive, Kind, Input, Transfer, ColorMatrix, Pixmap, Light } from './filter.ts';
 import { BLEND_MODES, blendPixel } from './blend.ts';
-import { FontFace, FontStyle, fontFace, layOutText, parseFontFamilies, pathLength, placeOutline, colorTablesOf, TextInput, ChunkInput, SpanInput, TextOutput, SpanOutput, Baseline } from './svg-text.ts';
+import { FontFace, FontStyle, fontFace, layOutText, parseFontFamilies, parseVariationSettings, pathLength, placeOutline, colorTablesOf, TextInput, ChunkInput, SpanInput, TextOutput, SpanOutput, Baseline } from './svg-text.ts';
 import { rasterizeGlyph } from './text.ts';
 import { renderPaintGlyph } from './colr.ts';
 import { decodeSync as decodePNG } from '../codecs/png.ts';
@@ -30,7 +30,7 @@ const INHERITED = new Set(['fill', 'fill-opacity', 'fill-rule', 'stroke', 'strok
     'stroke-miterlimit', 'stroke-dasharray', 'stroke-dashoffset', 'color', 'visibility', 'clip-rule', 'font-size', 'marker-start', 'marker-mid',
     'marker-end', 'image-rendering', 'color-interpolation-filters', 'paint-order', 'shape-rendering',
     'font-family', 'font-weight', 'font-style', 'font-stretch', 'font-variant', 'text-anchor', 'letter-spacing', 'word-spacing', 'dominant-baseline',
-    'writing-mode', 'kerning', 'font-kerning', 'text-rendering']);
+    'writing-mode', 'kerning', 'font-kerning', 'text-rendering', 'font-variation-settings', 'font-optical-sizing']);
 
 // elements a switch may choose from
 // properties that aren't presentation attributes
@@ -145,6 +145,7 @@ const DEFAULTS: Record<string, string> = {
     'stop-color': 'black', 'stop-opacity': '1', 'marker-start': 'none', 'marker-mid': 'none', 'marker-end': 'none',
     'image-rendering': 'auto', 'filter': 'none', 'flood-color': 'black', 'flood-opacity': '1', 'color-interpolation-filters': 'linearRGB',
     'lighting-color': 'white', 'shape-rendering': 'auto', 'font-weight': '400', 'font-style': 'normal', 'font-stretch': 'normal',
+    'font-variation-settings': 'normal', 'font-optical-sizing': 'auto',
     'font-variant': 'normal', 'text-anchor': 'start', 'letter-spacing': 'normal', 'word-spacing': 'normal', 'dominant-baseline': 'auto',
     'writing-mode': 'lr-tb', 'text-rendering': 'auto'
 };
@@ -1178,7 +1179,10 @@ class Document {
             const fontStyle = style['font-style'] === 'italic' || style['font-style'] === 'oblique' ? style['font-style'] as FontStyle : 'normal';
             return {
                 start, end, paint: style, visible: style.visibility === 'visible',
-                font: { families: parseFontFamilies(style['font-family'] ?? ''), weight: Number(style['font-weight']), style: fontStyle, stretch },
+                font: {
+                    families: parseFontFamilies(style['font-family'] ?? ''), weight: Number(style['font-weight']), style: fontStyle, stretch,
+                    variations: parseVariationSettings(style['font-variation-settings'] ?? ''), opticalSizing: style['font-optical-sizing'] !== 'none',
+                },
                 fontSize, smallCaps: style['font-variant'] === 'small-caps',
                 kerning: !(style.kerning !== undefined && style.kerning !== 'auto' && parseLength(style.kerning, viewport, fontSize, 'x') === 0) && style['font-kerning'] !== 'none',
                 letterSpacing: spacing(style['letter-spacing']), wordSpacing: spacing(style['word-spacing']),