docs: tsover usage (#2209)

Author: iwoplaza

apps/typegpu-docs/src/content/docs/fundamentals/data-schemas.mdx

@@ -120,8 +120,15 @@ const firstElement = mat[0]; // 1.1 in JS, but resolves to invalid WGSL!
 
 ### Operators
 
-As you may know, it is currently impossible to overload operators in JavaScript.
-For that reason, TypeGPU provides `std` functions imitating those.
+For performing math operations on vectors and matrices, you can either use the standard JavaScript operators like
+`+`, `-`, `*`, `/` and `%` when inside functions marked with `'use gpu'`, use functions provided on the `std` namespace,
+or `.add`, `.sub`, `.mul`, `.div` and `.mod` functions on the values themselves.
+
+:::note
+Use of `tsover` is required for operator overloading support, [refer to their documentation on how to set it up in your project](https://software-mansion-labs.github.io/tsover/docs).
+
+When operating on scalars, you can still use `+`, `<=`, `!` etc., whether you adopt `tsover` or not.
+:::
 
 ```ts twoslash
 import { d, std } from 'typegpu';
@@ -130,6 +137,12 @@ const vec1 = d.vec3f(1, 2, 3);
 const vec2 = std.add(vec1, 3); // d.vec3f(4, 5, 6)
 //    ^?
 
+function foo() {
+  'use gpu';
+  const vec1 = d.vec3f(1, 2, 3) * 2; // d.vec3f(2, 4, 6)
+  //    ^?
+}
+
 const mat = d.mat3x3f(
   2, 0, 0,
   0, 4, 0,
@@ -143,14 +156,14 @@ const comparison = std.le(d.vec3f(2, 3, 4), d.vec3f(3)); // d.vec3b(true, true,
 //    ^?
 ```
 
-Currently, implemented operators include:
+Currently, implemented `std` operations include:
 
 - arithmetic operators `add`, `sub`, `mul`, `div`, `mod`, `neg`,
 - comparison operators `eq`, `ne`, `lt`, `le`, `gt`, `ge`,
 - logical operators `not`, `and`, `or`.
 
-When operating on scalars, you can still use `+`, `<=`, `!` etc.,
-the purpose of these `std` functions is to enable working on vectors and matrices.
+Vectors currently overload the binary `+`, `-`, `*`, `/` and `%` operators, while matrices
+overload `+`, `-` and  `*`.
 
 For arithmetic operators, you can also use the infix notation.
 

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

@@ -82,7 +82,7 @@ fn main() -> vec2f {
 ```
 
 You can already notice a few things about TypeGPU functions:
-- Using operators like `+`, `-`, `*`, `/`, etc. is perfectly valid on numbers.
+- Using operators like `+`, `-`, `*`, `/`, etc. is perfectly valid on numbers (and on vectors/matrices thanks to [`tsover`](https://software-mansion-labs.github.io/tsover/)).
 - TS types are properly inferred, feel free to hover over the variables to see their types.
 - The generated code closely matches your source code.
 
@@ -287,9 +287,9 @@ Our aim with TypeGPU functions is not to allow arbitrary JavaScript to be suppor
 :::
 
 * **Operators** --
-JavaScript does not support operator overloading.
-This means that, while you can still use operators for numbers,
-you have to use supplementary functions from `typegpu/std` (*add, mul, eq, lt, ge...*) for operations involving vectors and matrices, or use a fluent interface (*abc.mul(xyz), ...*)
+We support using regular operators on vectors and matrices with full type inference thanks to [tsover](https://software-mansion-labs.github.io/tsover/).
+Without it, you can still use operators for numbers,
+but for vectors and matrices you have to use supplementary functions from `typegpu/std` (*add, mul, eq, lt, ge...*), or use a fluent interface (*abc.mul(xyz), ...*)
 
 * **Calling other functions** --
 Only functions marked with `'use gpu'` can be called from within a shader. There are two exceptions to that rule: [`console.log`](/TypeGPU/fundamentals/utils#consolelog), which allows for tracking runtime behavior
@@ -440,11 +440,7 @@ Writing shader code in JavaScript has a few significant advantages.
 It allows defining utilities once and using them both on the GPU and CPU,
 as well as enables complete syntax highlighting and autocomplete in TypeGPU function definitions, leading to a better developer experience.
 
-However, there are cases where WGSL might be more suitable.
-Since JavaScript doesn't support operator overloading, functions including complex matrix or vector operations can be more readable in WGSL.
-Writing WGSL becomes a necessity whenever TypeGPU does not yet support some feature or standard library function yet.
-
-Luckily, you don't have to choose one or the other for the entire project. It is possible to mix and match WGSL and JavaScript at every step of the way, so you're not locked into one or the other.
+However, there are cases where WGSL might be more suitable. Writing WGSL becomes a necessity whenever TypeGPU does not yet support some feature or standard library function yet. Luckily, you don't have to choose one or the other for the entire project. It is possible to mix and match WGSL and JavaScript at every step of the way, so you're not locked into one or the other.
 
 ## Entry functions
 

apps/typegpu-docs/src/content/docs/getting-started.mdx

@@ -63,6 +63,20 @@ Then add the following to your `tsconfig.json`:
 TypeGPU features related to writing shaders in JavaScript/TypeScript rely on an [additional build tool that hooks into existing bundlers called unplugin-typegpu](/TypeGPU/tooling/unplugin-typegpu). Make sure to set it up as well if you plan on using these features.
 :::
 
+:::tip
+For overloaded operator support in JavaScript/TypeScript shaders, [setup `tsover` in your project](https://software-mansion-labs.github.io/tsover/docs).
+
+```ts twoslash
+import { d } from 'typegpu';
+// ---cut-before---
+function foo() {
+  'use gpu';
+  const value = d.vec3f() * 20 - 0.5;
+  //    ^?
+}
+```
+:::
+
 ## Live Examples
 
 Our [live examples](/TypeGPU/examples) showcase many use-cases of TypeGPU. Feel free to check them out! You can also open each of them on StackBlitz in order to edit the code and see the preview update live, or to bootstrap your own project.