@cssints/gradient-2d 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# @cssints/gradient-2d
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`mesh-gradient()` and `freeform-gradient()` for [cssints](../../README.md), as styles of `cssints/plugin` `scope()`.
+Where the browser has the CSS function, the style uses it. Where it does not, a runtime draws the gradient on a canvas and
+sets the drawing as the background. **No browser has either function yet**, so today the runtime draws every gradient; the
+first paint is freeform's stack of radial gradients or mesh's average colour.
+
+**Status (2026-10-17).** The CSSWG adopted mesh and freeform gradients into css-images-5 on 2026-10-14, as an explainer
+([css-images-5/explainers/2d-gradients.md](https://github.com/w3c/csswg-drafts/blob/main/css-images-5/explainers/2d-gradients.md)).
+That is not a spec draft: the syntax can still change. Freeform may be renamed `diffusion-gradient()`, and neither
+function's rendering rule is public, so both drawings here are **this package's algorithm**, not a browser's or
+Illustrator's.
+
+```ts
+import { cn, color } from "cssints" with { type: "cssints" };
+import { freeformGradient, meshGradient } from "@cssints/gradient-2d" with { type: "cssints" };
+
+export const hero = cn(meshGradient("red, blue; green, yellow"), color("white"));
+export const panel = freeformGradient("red top left, gold 4 60% 40%, yellow bottom right");
+```
+
+```css
+@layer _.k {
+  ._gradient2d-core {
+    background-image: var(--gradient2d-fallback);
+    background-repeat: no-repeat;
+    background-size: 100% 100%;
+  }
+  /* only where the browser parses the function */
+  @supports (background-image: mesh-gradient(red, blue; green, yellow)) {
+    ._gradient2d-core {
+      background-image: var(--gradient2d-native);
+    }
+  }
+  ._gradient2d-ff {
+    background-image: var(--gradient2d-ff-fallback);
+    background-repeat: no-repeat;
+    background-size: 100% 100%;
+  }
+  @supports (background-image: freeform-gradient(red top left, blue bottom right)) {
+    ._gradient2d-ff {
+      background-image: var(--gradient2d-ff-native);
+    }
+  }
+}
+@layer _.a {
+  ._1gxhgq5 {
+    --gradient2d-native: mesh-gradient(red, blue; green, yellow);
+    --gradient2d-fallback: linear-gradient(#918d78, #918d78);
+    --gradient2d-data: '{"space":"oklab","rows":[[[1,0,0,1],[0,0,1,1]],[[0,0.502,0,1],[1,1,0,1]]]}';
+  }
+  ._1ps31mi {
+    --gradient2d-ff-native: freeform-gradient(red top left, gold 4 60% 40%, yellow bottom right);
+    --gradient2d-ff-fallback:
+      radial-gradient(circle at 0% 0%, #ff0000, transparent),
+      radial-gradient(circle at 60% 40%, #ffd700, transparent),
+      radial-gradient(circle at 100% 100%, #ffff00, transparent);
+    --gradient2d-ff-data: '{"space":"oklab","points":[[0,0,1,[1,0,0,1]],[0.6,0.4,4,[1,0.8431,0,1]],[1,1,1,[1,1,0,1]]]}';
+  }
+}
+```
+
+The native value is the spec's text, as written. The data is the stops or points as sRGB numbers, for the runtime. Mesh's
+fallback is the average colour of its stops, in oklab; freeform's is a radial layer per point.
+
+## Syntax
+
+### `meshGradient(mesh)`
+
+- **`meshGradient(mesh)`**, one string: rows of stops, rows separated by `;` from the top of the box down, stops by `,`
+  from the left. A stop is a colour: `red`, `#888`, `oklch(...)`, or `var(--token)`.
+- **`in oklab`** or **`in srgb`** may open the text, as the spec has it: `meshGradient("in oklab, red, blue; green, yellow")`.
+  A colour after it (`in oklab red, ...`) is the colour outside the mesh. It is checked and kept in the native value, but
+  never drawn: the grid covers the whole box.
+- **Build errors**, at the call: rows of different lengths, fewer than 2 rows of 2 stops, a colour that does not parse,
+  another colour space than oklab or srgb, and a stop with a position, `by` or `with`.
+- **Not supported yet:** positions (`red 0% 0%`) and the control points (`by`, `with`). The grid is regular: the corners
+  sit at the corners of the box and the other stops are spaced evenly. A position needs the grid warped, which the
+  runtime does not do yet. Both are build errors, not ignored.
+- **`var(--token)` stops** work. The browser resolves them: the drawing waits for the runtime, and the first paint has no
+  fallback (`--gradient2d-fallback: none`).
+
+### `freeformGradient(points)`
+
+- **`freeformGradient(points)`**, one string: points separated by `,`, each `<color> <number>? <position>`. The number is
+  the point's **spread**, its weight against the others (1 when it is left out). The position is a keyword
+  (`top left`, `bottom right`, `center`) or one or two percentages, as `background-position` reads it
+  (`gold 4 60% 40%`, `blue right 10%` is 90% across).
+- **`in oklab`** or **`in srgb`** may open the text, as the spec has it: `freeformGradient("in srgb, red 20% 30%, blue")`.
+  The function has no colour outside the points, so a colour after the method is a build error.
+- **Build errors**, at the call: a point without a position, fewer than 2 points, two points at the same position (their
+  weights are both infinite there), a colour that does not parse, a length (`10px` needs the box), a line (a point with
+  more than one position, the spec's future work) and a shape.
+- **Not supported yet:** lines, shapes and lengths, as above. A `var(--token)` point works: the browser resolves it, in
+  the fallback too.
+
+## Browsers
+
+- **Native**: neither function is in any browser. The installed Chrome of `test:browser` reports no support, so the
+  runtime draws. The `@supports` tests are the spec's simplest examples: `mesh-gradient(red, blue; green, yellow)` and
+  `freeform-gradient(red top left, blue bottom right)`. The two are decided apart, so a browser with mesh and without
+  freeform takes mesh's branch only (`_gradient2d-ff` is a class of its own).
+- **The runtime** is in every build whose browserslist targets include a browser that BCD tracks. The table in
+  `@cssints/css-grammar` says every such browser lacks `css.types.gradient.mesh-gradient` and
+  `css.types.gradient.freeform-gradient` (BCD has no entry for either). When BCD or the table has a browser with one of
+  them, the runtime ships only to the targets that lack it.
+- **The runtime needs** `ResizeObserver`, canvas and `MutationObserver` (where the page has them, the drawing works).
+
+## The runtime
+
+- **The algorithm is this package's, not the spec's and not Illustrator's.** Mesh is a bicubic (Catmull-Rom) through the
+  4 × 4 stops around a point; the spec interpolates a tensor-product patch with Bézier control points, which this package
+  does not model. Freeform is **inverse-distance weighting**: the colour at a point is the weighted mean of the stops,
+  the weight of a stop `spread / d²`, in oklab. The spec suggests a Delaunay triangulation; freeform's rendering rule is
+  not public (Josh Tumath, 2026-06-25), so no browser or editor agrees on it yet. IDW was chosen over a Delaunay because
+  every pixel of the box then has a weight: a triangulation paints only the points' convex hull and leaves the rest of
+  the box undefined (the spike in `docs/research/2d-gradients.md` saw exactly that hard hull edge; this package's own
+  reading of an IDW render is soft round blobs, one per stop, with the spread visible). The drawing is a close relative
+  of a browser's freeform, not the same surface. Compare by eye.
+- **Resolution.** The canvas is a quarter of the box (64 px at least) and the browser stretches it to the box. A large box
+  is soft, not sharp. In Chrome (the installed one, 1000 × 600, median of six resizes between 800 and 1000 px, the canvas
+  250 × 150, the time to the new background, layout and PNG encoding included): the mesh redraws in 49 ms, the freeform in
+  34 ms. The distances of freeform are measured in the box's pixels (height / width), as the fallback's radial layers are,
+  so a point's influence is a circle on screen and not an ellipse.
+- **Size.** 3.9 kB minified, 1.9 kB gzipped for both rules (measured with rolldown's minifier; the `dist/runtime.mjs` of
+  `vp pack` is not minified). Mesh alone is 2.9 kB / 1.6 kB, as it was before freeform joined it; `@cssints/balance`'s
+  script is 552 bytes.
+- **Data and tokens.** The runtime reads `--gradient2d-data` or `--gradient2d-ff-data` (JSON in a CSS string). A `var()`
+  stop is read through a hidden child of the element, so it inherits the element's custom properties, and a 1 × 1 canvas
+  turns the computed colour into sRGB.
+- **Redraw.** On a size change, and when an element gets the marker class (added to the page or given the class later).
+  Both rules share one `ResizeObserver` and one `MutationObserver` (src/canvas.ts). A drawing that is outdated when a newer
+  one finishes is dropped. A previous blob URL is revoked.
+- **First paint without JS.** Freeform's fallback is a stack of radial gradients, one layer per point: its colour at the
+  point fading to transparent at the farthest corner of the box. It is an approximation with its own blend (alpha, in the
+  browser's space, not `spread / d²` in oklab; the spread is not in it), and it holds a `var()` point, which mesh's
+  average colour cannot.
+- **CSP.** The fallback is a `blob:` URL. The page needs `img-src blob:` (or `img-src` with `blob:` in it) for the drawing.
+- **SSR.** The runtime does nothing without `document`. The first paint is the kernel's fallback.
+
+## Limits
+
+- **Freeform's fallback and its drawing do not agree pixel for pixel.** The stack of radial gradients is a low-fidelity
+  first paint, not the IDW rule: its blend is linear in the distance and in the browser's colour space.
+- **A condition can change the data, and the runtime reads it at the draw.** `hover(meshGradient(...))` puts the data
+  under `:hover` (checked: the engine prints it); the drawing does not change on hover, only on the next resize.
+- **An element removed from the page keeps its observer and its blob URL** until the page unloads. Fine for pages, not
+  for a long single-page app that churns gradients; a fix would observe removals.
+- **Printing** takes the raster fallback. A PDF of a browser's freeform is a patch shading, not a bitmap, and freeform is
+  large in PDF.
+- **The syntax can change** until the spec draft, and freeform's name with it (`diffusion-gradient()`); the build error
+  messages name the part they reject.
+
+```bash
+cd packages/gradient-2d && bun run test           # the maths in Node, the engine (kernels, data, errors, the runtime by targets)
+cd packages/gradient-2d && bun run typecheck      # and the type tests
+cd packages/gradient-2d && bun run test:browser   # Chrome (installed): both first paints, the pixels against the maths, resize, an added element
+```

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+//#region src/index.d.ts
+declare const mesh: import("cssints/plugin").Scope<"gradient2d", {
+  readonly "#core": {
+    readonly css: "&{background-image:var(--_fallback);background-repeat:no-repeat;background-size:100% 100%}@supports (background-image:mesh-gradient(red,blue;green,yellow)){&{background-image:var(--_native)}}";
+  };
+  readonly "#script": {
+    readonly polyfills: ["css.types.gradient.mesh-gradient"];
+    readonly script: "@cssints/gradient-2d/runtime";
+  };
+  readonly "#ff": {
+    readonly css: "&{background-image:var(--_ff-fallback);background-repeat:no-repeat;background-size:100% 100%}@supports (background-image:freeform-gradient(red top left, blue bottom right)){&{background-image:var(--_ff-native)}}";
+  };
+  readonly "#ffScript": {
+    readonly polyfills: ["css.types.gradient.freeform-gradient"];
+    readonly script: "@cssints/gradient-2d/runtime";
+  };
+  readonly meshGradient: {
+    readonly args: import("cssints/plugin").Typed<string>;
+    readonly uses: readonly ["core", "script"];
+  };
+  readonly freeformGradient: {
+    readonly args: import("cssints/plugin").Typed<string>;
+    readonly uses: readonly ["ff", "ffScript"];
+  };
+}>;
+type Members = ReturnType<typeof mesh.export>;
+/**
+ * `meshGradient("red, blue; green, yellow")`: a mesh gradient of a grid of colour stops (rows `;`, stops `,`), with the
+ * spec's `in oklab` first if wanted. The native `mesh-gradient()` where the browser has it, else drawn by the runtime.
+ * A build error for ragged rows, fewer than 2 by 2, a colour it cannot read, and a position, `by` or `with`.
+ */
+export declare const meshGradient: Members["meshGradient"];
+/**
+ * `freeformGradient("red top left, gold 4 60% 40%, yellow bottom right")`: a freeform (diffusion) gradient of points,
+ * each `<color> <number>? <position>` (the number is the spread), with the spec's `in oklab` first if wanted. The native
+ * `freeform-gradient()` where the browser has it; where it does not, a stack of radial gradients paints the first one
+ * and the runtime redraws it. A build error for a point without a position, two points at one position, fewer than 2
+ * points, a colour it cannot read, a length, a line and a shape.
+ */
+export declare const freeformGradient: Members["freeformGradient"];
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,255 @@
+import { arg, scope } from "cssints/plugin";
+import { formatHex, formatHex8, parse, rgb } from "culori";
+//#region src/grid.ts
+const lin = (c) => c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+const gam = (c) => c <= .0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - .055;
+const toOklab = ([r, g, b, a]) => {
+	const R = lin(r);
+	const G = lin(g);
+	const B = lin(b);
+	const l = Math.cbrt(.4122214708 * R + .5363325363 * G + .0514459929 * B);
+	const m = Math.cbrt(.2119034982 * R + .6806995451 * G + .1073969566 * B);
+	const s = Math.cbrt(.0883024619 * R + .2817188376 * G + .6299787005 * B);
+	return [
+		.2104542553 * l + .793617785 * m - .0040720468 * s,
+		1.9779984951 * l - 2.428592205 * m + .4505937099 * s,
+		.0259040371 * l + .7827717662 * m - .808675766 * s,
+		a
+	];
+};
+const toSrgb = ([L, A, B, a]) => {
+	const l = (L + .3963377774 * A + .2158037573 * B) ** 3;
+	const m = (L - .1055613458 * A - .0638541728 * B) ** 3;
+	const s = (L - .0894841775 * A - 1.291485548 * B) ** 3;
+	return [
+		gam(4.0767416621 * l - 3.3077115913 * m + .2309699292 * s),
+		gam(-1.2684380046 * l + 2.6097574011 * m - .3413193965 * s),
+		gam(-.0041960863 * l - .7034186147 * m + 1.707614701 * s),
+		a
+	];
+};
+const fromSpace = (space, q) => space === "oklab" ? toSrgb(q) : q;
+const mean = (qs) => [
+	0,
+	1,
+	2,
+	3
+].map((k) => qs.reduce((s, q) => s + q[k], 0) / qs.length);
+//#endregion
+//#region src/index.ts
+const cut = (text, sep) => {
+	const { out, cur } = [...text].reduce((acc, ch) => {
+		const depth = acc.depth + Number(ch === "(") - Number(ch === ")");
+		return depth === 0 && sep(ch) ? {
+			out: [...acc.out, acc.cur.trim()],
+			cur: "",
+			depth
+		} : {
+			out: acc.out,
+			cur: acc.cur + ch,
+			depth
+		};
+	}, {
+		out: [],
+		cur: "",
+		depth: 0
+	});
+	return [...out, cur.trim()];
+};
+const colour = (text, call) => {
+	if (text.includes("var(")) return text;
+	const c = parse(text);
+	if (!c) throw new Error(`${call}(): ${JSON.stringify(text)} is not a colour`);
+	const { r, g, b, alpha = 1 } = rgb(c);
+	return [
+		r,
+		g,
+		b,
+		alpha
+	];
+};
+const parseMesh = (text) => {
+	const rows = cut(text, (c) => c === ";").map((row) => cut(row, (c) => c === ","));
+	const head = /^in\s+(\S+)(?:\s+(.*))?$/i.exec(rows[0]?.[0] ?? "");
+	const [, method = "oklab", outside = ""] = head ?? [];
+	if (method !== "oklab" && method !== "srgb") throw new Error(`meshGradient(): in ${method} is not supported yet (oklab and srgb)`);
+	if (outside) colour(outside, "meshGradient");
+	const space = method === "srgb" ? "srgb" : "oklab";
+	const stops = (head ? [rows[0].slice(1), ...rows.slice(1)] : rows).map((row) => row.map((p) => {
+		if (cut(p, (c) => /\s/.test(c)).length > 1) throw new Error(`meshGradient(): ${JSON.stringify(p)}: a stop is one colour, its position, by and with are not supported yet`);
+		return colour(p, "meshGradient");
+	}));
+	const lengths = stops.map((r) => r.length);
+	if (lengths.some((n) => n !== lengths[0])) throw new Error(`meshGradient(): the rows have ${lengths.join(", ")} stops: every row needs the same number`);
+	if (stops.length < 2 || lengths[0] < 2) throw new Error(`meshGradient(): a mesh needs at least 2 rows of 2 stops, not ${stops.length} of ${lengths[0] ?? 0}`);
+	return {
+		space,
+		rows: stops
+	};
+};
+const clamp = (x) => Math.min(1, Math.max(0, x));
+const hex = ([r, g, b, a]) => {
+	const c = {
+		mode: "rgb",
+		r: clamp(r),
+		g: clamp(g),
+		b: clamp(b),
+		alpha: clamp(a)
+	};
+	return c.alpha < 1 ? formatHex8(c) : formatHex(c);
+};
+const average = (stops) => {
+	const known = stops.filter((s) => typeof s !== "string");
+	if (known.length < stops.length) return "none";
+	const h = hex(fromSpace("oklab", mean(known.map((q) => toOklab(q)))));
+	return `linear-gradient(${h}, ${h})`;
+};
+const KEYWORD = /^(left|right|top|bottom|center)$/;
+const PERCENT = /^(-?\d*\.?\d+)%$/;
+const NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)$/;
+const LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)[a-z]+$/;
+const A_LINE_OR_SHAPE = /^(line|shape|curve)\b/;
+const CALL = "freeformGradient";
+const position = (words) => {
+	const pct = (w) => Number(PERCENT.exec(w)[1]) / 100;
+	const axis = (w) => w === "left" || w === "right" ? "x" : w === "top" || w === "bottom" ? "y" : "c";
+	const edge = (w) => w === "left" || w === "top" ? 0 : 1;
+	const [a, b] = words;
+	if (b === void 0) {
+		if (!KEYWORD.test(a)) return [pct(a), .5];
+		if (a === "center") return [.5, .5];
+		return axis(a) === "x" ? [edge(a), .5] : [.5, edge(a)];
+	}
+	const ka = KEYWORD.test(a);
+	const kb = KEYWORD.test(b);
+	if (!ka && !kb) return [pct(a), pct(b)];
+	if (ka && kb) {
+		const x = [a, b].find((w) => axis(w) === "x");
+		const y = [a, b].find((w) => axis(w) === "y");
+		return [x ? edge(x) : .5, y ? edge(y) : .5];
+	}
+	if (ka) {
+		if (axis(a) === "y") return [.5, a === "top" ? pct(b) : 1 - pct(b)];
+		if (axis(a) === "x") return [a === "left" ? pct(b) : 1 - pct(b), .5];
+		return [.5, pct(b)];
+	}
+	return axis(b) === "y" ? [pct(a), edge(b)] : [pct(a), .5];
+};
+const point = (text) => {
+	const words = cut(text, (c) => /\s/.test(c));
+	const c = words[0] ?? "";
+	const all = words.slice(1);
+	const wants = () => /* @__PURE__ */ new Error(`${CALL}(): ${JSON.stringify(text)}: a point needs a position, \`<color> <number>? <position>\``);
+	if (all.length === 0) throw wants();
+	const spread = NUMBER.test(all[0]) ? Number(all[0]) : 1;
+	const rest = NUMBER.test(all[0]) ? all.slice(1) : all;
+	if (rest.length === 0) throw wants();
+	const part = rest.find((w) => A_LINE_OR_SHAPE.test(w));
+	if (part) throw new Error(`${CALL}(): ${JSON.stringify(part)}: a line or a shape is not supported yet`);
+	const len = rest.find((w) => LENGTH.test(w));
+	if (len) throw new Error(`${CALL}(): ${JSON.stringify(len)} is a length: a position is a percentage or a keyword`);
+	if (rest.length > 2) {
+		const bad = rest.find((w) => !KEYWORD.test(w) && !PERCENT.test(w));
+		throw new Error(bad ? `${CALL}(): ${JSON.stringify(bad)} is not a position: a keyword (top, left, ...) or a percentage` : `${CALL}(): ${JSON.stringify(text)}: a line (a point with more than one position) is not supported yet`);
+	}
+	const [u = .5, v = .5] = position(rest);
+	return {
+		q: colour(c, CALL),
+		u,
+		v,
+		spread
+	};
+};
+const parseFreeform = (text) => {
+	const items = cut(text, (c) => c === ",");
+	const head = /^in\s+(\S+)(?:\s+(.*))?$/i.exec(items[0] ?? "");
+	const [, method = "oklab", extra = ""] = head ?? [];
+	if (method !== "oklab" && method !== "srgb") throw new Error(`${CALL}(): in ${method} is not supported yet (oklab and srgb)`);
+	if (extra) throw new Error(`${CALL}(): ${JSON.stringify(items[0])}: the interpolation method takes no colour (freeform-gradient() has none)`);
+	const space = method === "srgb" ? "srgb" : "oklab";
+	const body = head ? items.slice(1) : items;
+	if (body.length < 2) throw new Error(`${CALL}(): a gradient needs at least 2 points, not ${body.length}`);
+	const points = body.map(point);
+	const seen = /* @__PURE__ */ new Map();
+	for (const [i, p] of points.entries()) {
+		const at = `${p.u},${p.v}`;
+		const had = seen.get(at);
+		if (had !== void 0) throw new Error(`${CALL}(): ${JSON.stringify(had)} and ${JSON.stringify(body[i])} are the same position: every point needs its own`);
+		seen.set(at, body[i]);
+	}
+	return {
+		space,
+		points
+	};
+};
+const pct = (x) => `${Math.round(x * 1e6) / 1e4}%`;
+const radials = (points) => points.map((p) => {
+	const c = typeof p.q === "string" ? p.q : hex(p.q);
+	return `radial-gradient(circle at ${pct(p.u)} ${pct(p.v)}, ${c}, transparent)`;
+}).join(", ");
+const members = scope("gradient2d", {
+	"#core": { css: "&{background-image:var(--_fallback);background-repeat:no-repeat;background-size:100% 100%}@supports (background-image:mesh-gradient(red,blue;green,yellow)){&{background-image:var(--_native)}}" },
+	"#script": {
+		polyfills: ["css.types.gradient.mesh-gradient"],
+		script: "@cssints/gradient-2d/runtime"
+	},
+	"#ff": { css: "&{background-image:var(--_ff-fallback);background-repeat:no-repeat;background-size:100% 100%}@supports (background-image:freeform-gradient(red top left, blue bottom right)){&{background-image:var(--_ff-native)}}" },
+	"#ffScript": {
+		polyfills: ["css.types.gradient.freeform-gradient"],
+		script: "@cssints/gradient-2d/runtime"
+	},
+	meshGradient: {
+		args: arg(),
+		uses: ["core", "script"]
+	},
+	freeformGradient: {
+		args: arg(),
+		uses: ["ff", "ffScript"]
+	}
+}).build({
+	meshGradient: (text) => {
+		const { space, rows } = parseMesh(text);
+		const data = {
+			space,
+			rows: rows.map((row) => row.map((s) => typeof s === "string" ? s : s.map((n) => Math.round(n * 1e4) / 1e4)))
+		};
+		return { decls: [
+			["--_native", `mesh-gradient(${text})`],
+			["--_fallback", average(rows.flat())],
+			["--_data", JSON.stringify(JSON.stringify(data))]
+		] };
+	},
+	freeformGradient: (text) => {
+		const { space, points } = parseFreeform(text);
+		const data = {
+			space,
+			points: points.map((p) => [
+				Math.round(p.u * 1e4) / 1e4,
+				Math.round(p.v * 1e4) / 1e4,
+				p.spread,
+				typeof p.q === "string" ? p.q : p.q.map((n) => Math.round(n * 1e4) / 1e4)
+			])
+		};
+		return { decls: [
+			["--_ff-native", `freeform-gradient(${text})`],
+			["--_ff-fallback", radials(points)],
+			["--_ff-data", JSON.stringify(JSON.stringify(data))]
+		] };
+	}
+}).export();
+/**
+* `meshGradient("red, blue; green, yellow")`: a mesh gradient of a grid of colour stops (rows `;`, stops `,`), with the
+* spec's `in oklab` first if wanted. The native `mesh-gradient()` where the browser has it, else drawn by the runtime.
+* A build error for ragged rows, fewer than 2 by 2, a colour it cannot read, and a position, `by` or `with`.
+*/
+const meshGradient = members.meshGradient;
+/**
+* `freeformGradient("red top left, gold 4 60% 40%, yellow bottom right")`: a freeform (diffusion) gradient of points,
+* each `<color> <number>? <position>` (the number is the spread), with the spec's `in oklab` first if wanted. The native
+* `freeform-gradient()` where the browser has it; where it does not, a stack of radial gradients paints the first one
+* and the runtime redraws it. A build error for a point without a position, two points at one position, fewer than 2
+* points, a colour it cannot read, a length, a line and a shape.
+*/
+const freeformGradient = members.freeformGradient;
+//#endregion
+export { freeformGradient, meshGradient };

package/dist/runtime.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/runtime.mjs

@@ -0,0 +1,207 @@
+//#region src/canvas.ts
+const drawn = /* @__PURE__ */ new WeakMap();
+const resolve = (el, text, ctx) => {
+	const probe = document.createElement("span");
+	probe.hidden = true;
+	probe.style.color = text;
+	el.append(probe);
+	const css = getComputedStyle(probe).color;
+	probe.remove();
+	ctx.clearRect(0, 0, 1, 1);
+	ctx.fillStyle = css;
+	ctx.fillRect(0, 0, 1, 1);
+	const px = ctx.getImageData(0, 0, 1, 1).data;
+	return [
+		px[0] / 255,
+		px[1] / 255,
+		px[2] / 255,
+		px[3] / 255
+	];
+};
+const draw = (el, d) => {
+	if (!el.clientWidth || !el.clientHeight) return;
+	const w = Math.max(64, Math.round(el.clientWidth / 4));
+	const h = Math.max(64, Math.round(el.clientHeight / 4));
+	const cv = document.createElement("canvas");
+	cv.width = w;
+	cv.height = h;
+	const ctx = cv.getContext("2d");
+	if (!ctx) return;
+	ctx.putImageData(d.paint(el, ctx, w, h), 0, 0);
+	const s = drawn.get(el) ?? { id: 0 };
+	const id = ++s.id;
+	drawn.set(el, s);
+	cv.toBlob((blob) => {
+		if (!blob || drawn.get(el)?.id !== id) return;
+		if (s.url) URL.revokeObjectURL(s.url);
+		s.url = URL.createObjectURL(blob);
+		el.style.setProperty(d.fallback, `url("${s.url}")`);
+	}, "image/png");
+};
+const run = (drawings) => {
+	const live = drawings.filter((d) => !CSS.supports("background-image", d.native));
+	if (!live.length) return;
+	const sized = new ResizeObserver((es) => {
+		for (const e of es) {
+			const el = e.target;
+			for (const d of live) if (el.classList.contains(d.marker)) draw(el, d);
+		}
+	});
+	const scan = (root) => {
+		for (const d of live) for (const el of root.matches(`.${d.marker}`) ? [root] : root.querySelectorAll(`.${d.marker}`)) sized.observe(el);
+	};
+	new MutationObserver((rs) => {
+		for (const r of rs) if (r.type === "attributes") scan(r.target);
+		else for (const n of r.addedNodes) if (n.nodeType === 1) scan(n);
+	}).observe(document.documentElement, {
+		subtree: true,
+		childList: true,
+		attributes: true,
+		attributeFilter: ["class"]
+	});
+	scan(document.documentElement);
+};
+//#endregion
+//#region src/grid.ts
+const lin = (c) => c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+const gam = (c) => c <= .0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - .055;
+const toOklab = ([r, g, b, a]) => {
+	const R = lin(r);
+	const G = lin(g);
+	const B = lin(b);
+	const l = Math.cbrt(.4122214708 * R + .5363325363 * G + .0514459929 * B);
+	const m = Math.cbrt(.2119034982 * R + .6806995451 * G + .1073969566 * B);
+	const s = Math.cbrt(.0883024619 * R + .2817188376 * G + .6299787005 * B);
+	return [
+		.2104542553 * l + .793617785 * m - .0040720468 * s,
+		1.9779984951 * l - 2.428592205 * m + .4505937099 * s,
+		.0259040371 * l + .7827717662 * m - .808675766 * s,
+		a
+	];
+};
+const toSrgb = ([L, A, B, a]) => {
+	const l = (L + .3963377774 * A + .2158037573 * B) ** 3;
+	const m = (L - .1055613458 * A - .0638541728 * B) ** 3;
+	const s = (L - .0894841775 * A - 1.291485548 * B) ** 3;
+	return [
+		gam(4.0767416621 * l - 3.3077115913 * m + .2309699292 * s),
+		gam(-1.2684380046 * l + 2.6097574011 * m - .3413193965 * s),
+		gam(-.0041960863 * l - .7034186147 * m + 1.707614701 * s),
+		a
+	];
+};
+const toSpace = (space, q) => space === "oklab" ? toOklab(q) : q;
+const fromSpace = (space, q) => space === "oklab" ? toSrgb(q) : q;
+const cr = (p0, p1, p2, p3, t) => p1 + .5 * t * (p2 - p0 + t * (2 * p0 - 5 * p1 + 4 * p2 - p3 + t * (3 * (p1 - p2) + p3 - p0)));
+const sample = (g, u, v) => {
+	const rows = g.length;
+	const cols = g[0].length;
+	const x = u * (cols - 1);
+	const y = v * (rows - 1);
+	const i = Math.min(Math.floor(x), cols - 2);
+	const j = Math.min(Math.floor(y), rows - 2);
+	const tx = x - i;
+	const ty = y - j;
+	const at = (r, c) => g[Math.min(Math.max(r, 0), rows - 1)][Math.min(Math.max(c, 0), cols - 1)];
+	const line = (r) => {
+		const p = [
+			-1,
+			0,
+			1,
+			2
+		].map((d) => at(r, i + d));
+		return [
+			0,
+			1,
+			2,
+			3
+		].map((k) => cr(p[0][k], p[1][k], p[2][k], p[3][k], tx));
+	};
+	const q = [
+		-1,
+		0,
+		1,
+		2
+	].map((d) => line(j + d));
+	return [
+		0,
+		1,
+		2,
+		3
+	].map((k) => cr(q[0][k], q[1][k], q[2][k], q[3][k], ty));
+};
+//#endregion
+//#region src/points.ts
+const freeform = (points, u, v, ratio = 1) => {
+	const ws = points.map((p) => {
+		const du = u - p.u;
+		const dv = (v - p.v) * ratio;
+		return {
+			p,
+			d2: du * du + dv * dv
+		};
+	});
+	const hit = ws.find((x) => x.d2 < 1e-12);
+	if (hit) return hit.p.q;
+	const w = ws.map((x) => Math.max(0, x.p.spread) / x.d2);
+	const sum = w.reduce((s, x) => s + x, 0);
+	if (!(sum > 0)) return points[0].q;
+	return [
+		0,
+		1,
+		2,
+		3
+	].map((k) => ws.reduce((s, x, i) => s + w[i] * x.p.q[k], 0) / sum);
+};
+//#endregion
+//#region src/runtime.ts
+const mesh = {
+	marker: "_gradient2d-core",
+	fallback: "--gradient2d-fallback",
+	native: "mesh-gradient(red, blue; green, yellow)",
+	paint: (el, ctx, w, h) => {
+		const raw = getComputedStyle(el).getPropertyValue("--gradient2d-data").trim();
+		const { space, rows } = JSON.parse(JSON.parse(raw));
+		const grid = rows.map((row) => row.map((s) => toSpace(space, typeof s === "string" ? resolve(el, s, ctx) : s)));
+		const img = ctx.createImageData(w, h);
+		Array.from({ length: w * h }, (_, i) => i).forEach((i) => {
+			const q = fromSpace(space, sample(grid, (i % w + .5) / w, (Math.floor(i / w) + .5) / h));
+			img.data.set([
+				q[0] * 255,
+				q[1] * 255,
+				q[2] * 255,
+				q[3] * 255
+			], 4 * i);
+		});
+		return img;
+	}
+};
+const points = {
+	marker: "_gradient2d-ff",
+	fallback: "--gradient2d-ff-fallback",
+	native: "freeform-gradient(red top left, blue bottom right)",
+	paint: (el, ctx, w, h) => {
+		const raw = getComputedStyle(el).getPropertyValue("--gradient2d-ff-data").trim();
+		const { space, points } = JSON.parse(JSON.parse(raw));
+		const ratio = h / w;
+		const ps = points.map(([u, v, spread, c]) => ({
+			u,
+			v,
+			spread,
+			q: toSpace(space, typeof c === "string" ? resolve(el, c, ctx) : c)
+		}));
+		const img = ctx.createImageData(w, h);
+		Array.from({ length: w * h }, (_, i) => i).forEach((i) => {
+			const q = fromSpace(space, freeform(ps, (i % w + .5) / w, (Math.floor(i / w) + .5) / h, ratio));
+			img.data.set([
+				q[0] * 255,
+				q[1] * 255,
+				q[2] * 255,
+				q[3] * 255
+			], 4 * i);
+		});
+		return img;
+	}
+};
+if (typeof document !== "undefined" && typeof ResizeObserver !== "undefined") run([mesh, points]);
+//#endregion

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@cssints/gradient-2d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "mesh-gradient() and freeform-gradient() for cssints: the native function where the browser has it, else a canvas drawn by a runtime",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/gradient-2d"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/runtime.ts",
+    "./dist/runtime.mjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "default": "./dist/runtime.mjs"
+    }
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "peerDependencies": {
+    "cssints": "^0.5.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}