Merge branch 'main' into fix/strands-hook-lifecycle-errors

Author: davepagurek

.all-contributorsrc

@@ -7621,6 +7621,15 @@
         "test",
         "bug"
       ]
+    },
+    {
+      "login": "shakeelmohamed",
+      "name": "Shakeel Mohamed",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1480063?v=4",
+      "profile": "https://github.com/shakeelmohamed",
+      "contributions": [
+        "test"
+      ]
     }
   ],
   "repoType": "github",

CONTRIBUTORS.md

@@ -1137,6 +1137,7 @@
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/okra-sf"><img src="https://avatars.githubusercontent.com/u/110788460?v=4?s=64" width="64px;" alt="okra-sf"/><br /><sub><b>okra-sf</b></sub></a><br /><a href="https://github.com/processing/p5.js/commits?author=okra-sf" title="Code">💻</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/Danyccsf"><img src="https://avatars.githubusercontent.com/u/186502464?v=4?s=64" width="64px;" alt="Dany Valverde Caldas"/><br /><sub><b>Dany Valverde Caldas</b></sub></a><br /><a href="https://github.com/processing/p5.js/commits?author=Danyccsf" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/Pcmhacker-piro"><img src="https://avatars.githubusercontent.com/u/181658297?v=4?s=64" width="64px;" alt="Prakash Meena"/><br /><sub><b>Prakash Meena</b></sub></a><br /><a href="https://github.com/processing/p5.js/commits?author=Pcmhacker-piro" title="Code">💻</a> <a href="https://github.com/processing/p5.js/commits?author=Pcmhacker-piro" title="Tests">⚠️</a> <a href="https://github.com/processing/p5.js/issues?q=author%3APcmhacker-piro" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/shakeelmohamed"><img src="https://avatars.githubusercontent.com/u/1480063?v=4?s=64" width="64px;" alt="Shakeel Mohamed"/><br /><sub><b>Shakeel Mohamed</b></sub></a><br /><a href="https://github.com/processing/p5.js/commits?author=shakeelmohamed" title="Tests">⚠️</a></td>
     </tr>
   </tbody>
 </table>

contributor_docs/p5.strands.md

@@ -23,6 +23,60 @@ At this point, the general technical framework has been set up (see the technica
 
 Finally, since the system is still so new and is still changing, it lacks extensive tutorials and examples. If you want to write or make videos to help people understand how to use p5.strands, or show examples illustrating the kinds of things you can make with it, reach out!
 
+## Transforms and matrices
+
+p5.strands includes a set of functions for building and applying transformation matrices inside a shader. They are newer than the rest of p5.strands, so using them logs a console warning that points here: they are the part of the API most likely to still change, and we want to hear how they work out for you.
+
+The functions look like the transforms you already use on the canvas:
+
+- `transform2D()` creates a 3x3 matrix that can move, turn, scale, and slant 2D points, such as the texture coordinates in a filter shader. `transform3D()` creates a 4x4 matrix that does the same for 3D positions. Both start out as the identity transform, which leaves points exactly where they are. They are the same functions as `mat3()` and `mat4()`, and `mat2()` exists for plain 2x2 math, but a 2x2 matrix has no room to store a move, so there is no transform alias for it.
+- `translate()`, `rotate()`, `scale()`, `shearX()`, and `shearY()` add a step to a transform, and `rotateX()`, `rotateY()`, `rotateZ()`, and `rotateAxisAngle()` do the same for 3D transforms. Unlike their canvas counterparts, they don't change anything in place: each returns a new transform, so the result has to be assigned back, as in `t = translate(t, 20, 0, 0)`. Steps combine the way they do on the canvas, so translating and then rotating turns a shape in place before moving it.
+- `transformPoint()` applies a transform to a position, and `transformNormal()` applies it to a surface direction, which has to ignore the move part of the transform to stay correct.
+
+`translate()`, `rotate()`, `scale()`, `shearX()`, `shearY()`, and `rotateX()`/`rotateY()`/`rotateZ()` share their names with the regular p5 functions, so p5.strands only takes over when their first argument is a transform created inside a shader callback, and `translate(20, 0)` on the canvas works the same as it always has. The rest of these functions only exist inside a shader callback. Angles inside a shader are always in radians, since `angleMode()` doesn't reach inside the shader.
+
+A typical use is placing many copies of a shape at once, giving each instance its own transform based on `instanceIndex`:
+
+```js
+let myShader;
+let count = 10;
+
+function setup() {
+  createCanvas(200, 200, WEBGL);
+  myShader = buildMaterialShader(placeOnRing);
+}
+
+function placeOnRing() {
+  worldInputs.begin();
+  let angle = instanceIndex * TWO_PI / count;
+  let t = transform3D();
+  t = rotateY(t, angle);
+  t = translate(t, 65, 0, 0);
+  worldInputs.position = transformPoint(t, worldInputs.position);
+  worldInputs.normal = transformNormal(t, worldInputs.normal);
+  worldInputs.end();
+}
+
+function draw() {
+  background(220);
+  lights();
+  noStroke();
+  fill('red');
+  shader(myShader);
+  instances(count).box(18);
+}
+```
+
+The reference pages for [`transform2D()`](https://p5js.org/reference/p5/transform2D/) and [`transform3D()`](https://p5js.org/reference/p5/transform3D/) have more examples.
+
+### What we want feedback on
+
+The most useful thing you can do is to try the transforms out in a real sketch and let us know how it went: what you were trying to make, what took longest to figure out, and where the names or the way the functions fit together tripped you up. These functions are the newest part of p5.strands, so now is the best time to tell us what feels awkward, before the API settles.
+
+Bugs are just as welcome. If something renders differently from what the same transforms would do on the canvas, or an error message leaves you stuck, please report it (and help fix it if you are up for it!).
+
+Finally, since these functions are so new, there are very few examples of them in use. Sketches, write-ups, or videos showing what you have made with them help others get started, and help us see which parts need more explanation. For any of this, file an issue on GitHub or talk to us on Discord.
+
 ## Technical overview
 
 At its core, p5.strands works in four steps:

contributor_docs/p5.svg.md

@@ -0,0 +1,105 @@
+<!-- An overview of the goals of p5's native SVG export, import, and vector shape recording system. -->
+
+# p5.svg Overview
+
+`p5.svg` is an experimental native vector graphics system provided in p5.js starting from version 2.4. It allows you to create, import, and export vector graphics directly in p5.js without needing external addons. With `p5.svg`, artists, designers, and educators can generate graphics that scale smoothly for high-DPI displays, print, pen plotters, CNC routers, laser cutters, and embroidery machines using familiar p5.js drawing functions.
+
+The specifics of these APIs are currently experimental and subject to evolution based on community feedback. A valuable contribution to the project is testing these APIs, reporting edge cases, and sharing feedback on usability and performance!
+
+## Project Goals
+
+`p5.svg` addresses several key goals:
+
+- **Vector Graphics**: `p5.svg` allows p5.js drawings to be saved as vector graphics that can scale to different sizes without losing sharpness.
+- **Familiar p5 Drawing Workflow**: To create SVG output, the only thing you need to do differently is use `createShape()` and `buildShape()`. Inside these functions, use the standard drawing API (`rect`, `circle`, `path`, `fill`, `stroke`, `translate`, `rotate`, etc.) as you usually would.
+- **Import and Export SVG Files**: `p5.svg` allows you to load existing SVG files with `loadSVG()` and save p5.js drawings as SVG files using `saveSVG()` or `getSVG()`.
+
+## What Needs Feedback
+
+The main ways you can help develop `p5.svg` are:
+
+- **Shape API**: Test vector shape functions like `createSVG()`, `loadSVG()`, `buildShape()`, `createShape()`, `shape()`, `getSVG()`, and `saveSVG()`. We want feedback on whether the API feels familiar to someone learning p5.js, whether the functions are easy to understand for beginners, and whether they are easy to use when teaching p5.js. Let us know if any choices feel confusing or tricky for students, or if anything feels inconsistent with the rest of p5.js.
+- **SVG Path Parsing**: Test importing SVGs generated by vector design tools (Adobe Illustrator, Inkscape, Figma). Report any unsupported path commands (`M`, `L`, `H`, `V`, `C`, `S`, `Q`, `T`, `A`, `Z`) or malformed elements.
+- **Styling and CSS Properties**: Help verify that stroke weights, colors, fill rules, opacities, gradients, and transform stacks behave consistently across export and import pipelines.
+- **Performance & Memory**: Test large or complex SVG scenes to help identify bottlenecks in DOM parsing, AST construction, or XML string generation.
+
+## Technical Overview
+
+Behind the scenes, `p5.svg` operates in three main layers:
+
+1. **Shape Recording (`src/shape/svg/svg_recorder.js`)**:
+   - Intercepts 2D drawing calls (`rect`, `ellipse`, `line`, `beginShape`/`endShape`, `fill`, `stroke`, `push`, `pop`, `translate`, `rotate`, `scale`, `applyMatrix`).
+   - Builds an Abstract Syntax Tree (AST) composed of node instances (`ScopeNode`, `ShapeNode`, `BackgroundNode`, `ClearNode`, `ImageNode`).
+   - Tracks coordinate transformations using an internal `TransformStack`.
+
+2. **SVG Export & Visitor (`src/shape/svg/svg_export.js`)**:
+   - Implements `SVGExportAddon` and `SVGVisitor` (extending `p5.PrimitiveVisitor`).
+   - Traverses the shape AST to output standard SVG 2.0 XML markup string via `getSVG()` or triggers browser file downloads via `saveSVG()`.
+
+3. **SVG Import & Parsing (`src/shape/svg/svg_import.js`)**:
+   - Implements `SVGImportAddon` to parse external SVG DOM trees.
+   - Tokenizes path data commands (`PATH_COMMANDS`) and converts SVG elements (`<path>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<polyline>`, `<polygon>`, `<g>`) into internal p5 `ShapeCollection` structures ready for playback via `shape()`.
+
+## Usage Example
+
+### Exporting an SVG
+
+```js
+function setup() {
+  createCanvas(400, 400);
+
+  // Record drawing commands into a vector shape
+  const record = buildShape(() => {
+    background(245);
+    fill(99, 102, 241);
+    stroke(0);
+    strokeWeight(2);
+    circle(200, 200, 150);
+  });
+
+  // Save as vector file
+  saveSVG(record, 'my-vector.svg');
+}
+```
+
+### Importing and Replaying an SVG
+
+```js
+let botLogo;
+
+async function setup() {
+  createCanvas(500, 500);
+
+  try {
+    // loadSVG returns a promise; await the resolved ShapeCollection
+    botLogo = await loadSVG('assets/robot.svg');
+    console.log('SVG Loaded successfully!');
+  } catch (err) {
+    console.error('Failed to load SVG:', err);
+  }
+}
+
+function draw() {
+  background(255);
+
+  // Render the SVG once it is fully loaded
+  if (botLogo) {
+    shape(botLogo, 100, 100);
+  } else {
+    fill(100);
+    text('Loading SVG...', 20, 30);
+  }
+}
+```
+
+## Contributing
+
+We welcome contributions to `p5.svg`! You can get involved by:
+
+* **Testing existing SVG workflows** and reporting bugs or unexpected behavior on GitHub.
+* **Proposing and implementing new SVG features**, such as expanded SVG element support, clipping paths, gradients, filters, and custom SVG attributes.
+* **Improving SVG import and parsing**, including support for additional path commands and CSS/SVG attributes.
+* **Adding tests and examples** to validate new functionality and demonstrate real-world SVG workflows.
+* **Creating tutorials and creative coding examples** that showcase how `p5.svg` can be used in p5.js projects.
+* **Reviewing and providing feedback on experimental APIs** to help improve their usability, consistency, and performance.
+

contributor_docs/performance_testing.md

@@ -0,0 +1,34 @@
+<!-- Guide to writing performance tests for p5.js source code.  -->
+
+# Performance Testing
+
+Performance testing is an essential part of measuring how fast isolated code paths take to execute under a known range of conditions.
+
+Implementation notes:
+
+- All pre-existing benchmarks included the full p5 instance setup which adds ~50ms to each test. The typography performance tests show how to isolate performance testing away from setup overhead.
+- The `textToPoints() single word, with render` test draws the calculated points, others just run `textToPoints()`.
+
+## Typography Tests
+
+To isolate typography tests, run the following:
+
+```shell
+npx vitest bench test/bench/typography.bench.js --reporter=verbose
+```
+
+### Manual tests on v1.x
+
+These manual tests are useful to loosely check performance against v2.x as a baseline. The test harness is compatible with the one in `test/bench/typography.bench.js`. 
+
+To manually run typography tests against p5.js v1.x, open the following files in a browser:
+
+- `textToPoints()`: `test/bench/v1_manual/text_to_points.html`
+
+Note: you will need to use a [local server](https://github.com/processing/p5.js/wiki/Local-server) to avoid CORS issues when loading fonts. For example, from the root of the repo:
+
+```shell
+npx http-server -c-1
+```
+
+Then tests can be accessed at `http://localhost:8080/test/bench/v1_manual/text_to_points.html`.

src/app.js

@@ -61,6 +61,8 @@ import shader from './webgl/p5.Shader';
 p5.registerAddon(shader);
 import strands from './strands/p5.strands';
 p5.registerAddon(strands);
+import svg from './shape/svg/p5.svg';
+p5.registerAddon(svg);
 
 import { waitForDocumentReady, _globalInit } from './core/init';
 waitForDocumentReady().then(_globalInit);

src/color/p5.Color.js

@@ -319,7 +319,7 @@ class Color {
     return this._array;
   }
 
-  lerp(color, amt, mode){
+  lerp(color, amt, mode) {
     let lerpMode = mode;
     if (typeof amt === 'object') {
       // Passing in options object
@@ -726,13 +726,7 @@ class Color {
   }
 
   _getRGBA(maxes = [1, 1, 1, 1]) {
-    // Get colorjs maxes
     const colorjsMaxes = Color.#colorjsMaxes[RGB];
-
-    // Normalize everything to 0,1 or the provided range (map)
-    let coords = structuredClone(to(this._color, 'srgb').coords);
-    coords.push(this._color.alpha);
-
     const rangeMaxes = maxes.map(v => {
       if (!Array.isArray(v)) {
         return [0, v];
@@ -741,7 +735,15 @@ class Color {
       }
     });
 
-    coords = coords.map((coord, i) => {
+    let coords;
+    if (this.mode === RGB) {
+      coords = [...this._color.coords, this._color.alpha];
+    } else {
+      coords = structuredClone(to(this._color, 'srgb').coords);
+      coords.push(this._color.alpha);
+    }
+
+    return coords.map((coord, i) => {
       return map(
         coord,
         colorjsMaxes[i][0],
@@ -750,8 +752,6 @@ class Color {
         rangeMaxes[i][1]
       );
     });
-
-    return coords;
   }
 
   _getMode() {

src/core/experimental.js

@@ -8,7 +8,10 @@ import { FES } from '../friendly_errors/fes';
  * - Create a name for the subject area, e.g. 'webgpu'
  * - Write a document in the contributor_docs folder for the subject area
  *   describing its goals and what we want feedback on. The file should match
- *   the subject area name, plus the .md suffix.
+ *   the subject area name, plus the .md suffix. If the subject area is a part of
+ *   a larger experimental area, e.g. 'p5.strands.transforms' within 'p5.strands',
+ *   it doesn't need a whole doc of its own: add a section to the larger area's doc
+ *   instead, and point to it in experimentalDocSections below.
  * - Write a message below that will show up in the console when functionality
  *   from that subject area. A link to the doc will be automatically appended. Index
  *   the message by the same subject area name.
@@ -29,13 +32,33 @@ import { FES } from '../friendly_errors/fes';
  *
  *   ...or, if you need to conditionally warn about experimental functionality, you
  *   can directly call warnExperimental(p5, pInst, subjectArea) inside a function.
+ *   This is also the way to go when a function is only experimental some of the
+ *   time, e.g. translate() is a regular p5 function unless it's given a p5.strands
+ *   transform, and regular use shouldn't log a warning. Note that FES is switched
+ *   off while a p5.strands callback runs, so functions used inside one add their
+ *   subject area to strandsContext.experimentalFeaturesUsed instead, and modify()
+ *   calls warnExperimental for each once the callback is done.
  */
 
 const experimentalMessages = {
   webgpu: 'WEBGPU mode is experimental, so its functions and constants may change in future versions. You can get involved by giving feedback to help direct its development!',
   'p5.strands': 'p5.strands shaders are experimental, so functions for building shaders and the hooks available within them may change in future versions. You can get involved by giving feedback to help direct its development!',
+  'p5.strands.transforms': 'p5.strands transforms are experimental, so transform2D(), transform3D(), the matrix constructors, and the functions that build on them may change in future versions. You can get involved by giving feedback to help direct their development!',
+  'p5.svg': 'SVG features are experimental, so SVG export, import, and shape recording functions may change in future versions. You can get involved by giving feedback to help direct its development!'
 };
 
+// By default, a subject area links to the contributor doc with the same name. A
+// subject area that is a part of a larger one can instead point to a section of
+// that area's doc, so that it doesn't need a whole doc of its own.
+const experimentalDocSections = {
+  'p5.strands.transforms': { doc: 'p5.strands', section: 'transforms-and-matrices' },
+};
+
+function experimentalDocURL(subjectArea) {
+  const { doc = subjectArea, section } = experimentalDocSections[subjectArea] || {};
+  return `https://p5js.org/contribute/${doc}/${section ? `#${section}` : ''}`;
+}
+
 // Just in case it's not possible to get access to the p5 instance from something,
 // we still don't want to make logs super noisy from repeated warnings, so we'll
 // fall back on this global cache. It means if you create a second p5 instance, it
@@ -49,7 +72,9 @@ export function warnExperimental(p5, pInst, subjectArea) {
     target.warnedExperimental = target.warnedExperimental || {};
     target.warnedExperimental[subjectArea] = true;
 
-    FES.log`${experimentalMessages[subjectArea]} For more info, see https://p5js.org/contribute/${subjectArea}/`();
+    const message = experimentalMessages[subjectArea];
+    const url = experimentalDocURL(subjectArea);
+    FES.log`${message} For more info, see ${url}`();
   }
 }
 

src/core/main.js

@@ -394,11 +394,7 @@ class p5 {
       this._removeAbortController.abort();
 
       // remove DOM elements created by p5
-      for (const e of this._elements) {
-        if (e.elt && e.elt.parentNode) {
-          e.elt.parentNode.removeChild(e.elt);
-        }
-      }
+      this._elements.slice().forEach(e => e.remove());
 
       // Run `remove` hooks
       await this._runLifecycleHook('remove');