feat(svg): add native p5.svg experimental feature module and contributor docs by VANSH3104 · Pull Request #9123 · processing/p5.js

VANSH3104 · 2026-09-02T09:00:41Z

Resolves #4630

Note: This work is related to GSoC 2026 development for native SVG support in p5.js.

Changes:

Native SVG Module (src/shape/svg/): Added core SVG export, import, and shape recording capabilities:
- svg_recorder.js: ShapeRecorder AST node graph (ScopeNode, ShapeNode, BackgroundNode, ClearNode, ImageNode) and TransformStack.
- svg_export.js: SVGExportAddon, SVGVisitor XML DOM renderer, and public APIs (createShape(), buildShape(), getSVG(), shape(), saveSVG()).
- svg_import.js: SVGImportAddon, path command parser (M, L, C, S, Q, A, Z), element converters, and public APIs (createSVG(), async loadSVG()).
- p5.svg.js: SVG module entry point combining export and import addons.
Core Addon Registration (src/app.js): Registered svg addon via p5.registerAddon(svg), bundling SVG capabilities directly into main lib/p5.js.
Experimental Warning System (src/core/experimental.js): Added 'p5.svg' message to experimentalMessages and wrapped public SVG prototype methods with markExperimental('p5.svg', p5) warning decorators.
Contributor Documentation (contributor_docs/p5.svg.md): Created contributor guide covering project goals, API ergonomics, technical architecture, and community guidelines.

PR Checklist

npm run lint passes
Inline reference is included / updated

…ibutor guide

…nterceptor

…nverters

…gister in src/app.js

p5-bot · 2026-09-02T09:01:34Z

Continuous Release

CDN link

https://raw.esm.sh/pr/p5@fff96be/lib/p5.min.js

Published Packages

https://pkg.pr.new/p5@fff96be

Commit hash: fff96be

Previous deployments

`1595975`

`77a3f33`

`12c3451`

`d9b6031`

`742b58b`

`7aa0121`

`87854f6`

`8b7e241`

`141d8e5`

`ff5f532`

`ff8c36d`

This is an automated message.

VANSH3104 · 2026-09-02T09:05:32Z

@davepagurek I’ve added the code for this. Let me know what you think or if anything needs to be changed!

ksen0

Very exciting to see this! Added some high-level documentation comments. Non blocking

ksen0 · 2026-09-03T09:43:36Z

+
+# p5.svg Overview
+
+`p5.svg` is an experimental native vector graphics system provided in p5.js starting from version 2. It aims to bring resolution-independent vector rendering, SVG file importing, and SVG XML exporting directly into p5.js without requiring external third-party addons. It allows users to record 2D drawing operations using familiar p5 APIs (`rect`, `circle`, `path`, `fill`, `stroke`, `translate`, `rotate`, etc.) and convert them into scalable vector structures.


nitpick: from version 2.4

ksen0 · 2026-09-03T09:48:34Z

+
+`p5.svg` addresses several key goals:
+
+- **Resolution-Independent Vector Output**: Traditional canvas rendering in p5.js is raster (pixel) based. `p5.svg` enables artists, designers, and educators to generate scalable vector graphics suitable for high-DPI displays, print, pen plotters, CNC routers, laser cutters, and embroidery machines.


"p5.svg enables artists, designers, and educators to generate scalable vector graphics suitable for high-DPI displays, print, pen plotters, CNC routers, laser cutters, and embroidery machines." Feels like it should be in the opening paragraph?

ksen0 · 2026-09-03T09:50:14Z

+`p5.svg` addresses several key goals:
+
+- **Resolution-Independent Vector Output**: Traditional canvas rendering in p5.js is raster (pixel) based. `p5.svg` enables artists, designers, and educators to generate scalable vector graphics suitable for high-DPI displays, print, pen plotters, CNC routers, laser cutters, and embroidery machines.
+- **Familiar p5 Drawing Workflow**: Rather than introducing a complex vector editing paradigm, `p5.svg` hooks directly into the existing 2D drawing pipeline. You can record shapes using standard p5 drawing functions inside `createShape()` or `buildShape()`.


I think this phrasing should be simplified, eg not "Rather than introducing a complex vector editing paradigm, p5.svg hooks directly into the existing 2D drawing pipeline. You can record shapes using standard p5 drawing functions inside createShape() or buildShape()." but, "to create SVG output, the only thing you need to do differently is use crateshape and build shape. Inside these functions, use standard drawing API (rect, circle, path, fill, stroke, translate, rotate, etc.) as you usually would

ksen0 · 2026-09-03T09:51:43Z

+
+# p5.svg Overview
+
+`p5.svg` is an experimental native vector graphics system provided in p5.js starting from version 2. It aims to bring resolution-independent vector rendering, SVG file importing, and SVG XML exporting directly into p5.js without requiring external third-party addons. It allows users to record 2D drawing operations using familiar p5 APIs (`rect`, `circle`, `path`, `fill`, `stroke`, `translate`, `rotate`, etc.) and convert them into scalable vector structures.


I think this paragraph should use very simple terms, nothing significantly technical (ie not "resolution-independent")

ksen0 · 2026-09-03T10:01:22Z

+
+The main ways you can help develop `p5.svg` are:
+
+- **API Ergonomics & Shape API**: Test vector shape recording and rendering functions like `createSVG()`, `loadSVG()`, `buildShape()`, `createShape()`, `shape()`, `getSVG()`, and `saveSVG()`. Share feedback on `shape()` playback, coordinate bounds, positioning, scaling options, and alignment modes (`CORNER`, `CENTER`, `VIEWBOX`).


This section could be just "Shape API". I do not recommend the phrase "ergonomics," because in general API ergonomics does not imply a focus on learning and beginners as a user group, which is a specific focus in p5.js (part of access statement that relates to this feature)

In this case, in the whole feedback section, maybe it is useful top provide a bit more context on what the priorities are: maintaining familiarity with rest of p5.js; creating non-OOP, top-level, readable function calls to allow smooth svg recording / loading. The question is not ergonomics generally but: "how does this feel as a beginner?" or "if you teach with p5.js, do you see API choices that would be tricky for students?"

That's still quite broad, but for example, feedback like "I think this should be more compact / more OOP" would not really be relevant/applicable.

Just a general feedback, please feel free to implement as much as it makes sense

ksen0 · 2026-09-03T10:01:44Z

 import strands from './strands/p5.strands';
 p5.registerAddon(strands);
+import svg from './shape/svg/p5.svg';
+p5.registerAddon(svg);


davepagurek · 2026-09-13T14:32:54Z

+// on p5.prototype. It hooks into predraw and postdraw lifecycles to automatically capture drawing commands
+// when saveSVG() is called without explicit shape parameters.
+export function SVGExportAddon(p5, fn, lifecycles) {
+  let pendingExport = null;


To make this work with multiple p5 instances, should we make this a property on the instance rather than effectively a global? I believe doing fn.pendingExport = null at the start and then referring to this.pendingExport in addon lifecycles and functions would make it instance state (see #7742 (comment))

davepagurek · 2026-09-13T14:38:49Z

+
+  // RecordedShape manages the lifecycle of a recorded vector shape session.
+  // Calling begin() starts ShapeRecorder capture, and end() finalizes the AST data graph.
+  class RecordedShape {


To make TypeScript types and FES work for these, we may need to add some minimal doc comments. We probably also will need to move this class out of the addon function and then put p5.RecordedShape = RecordedShape within the addon function to make it exportable + referenceable in the jsdoc as p5.RecordedShape. (Maybe also worth a last thought to see if that's the right name for it?) We can then add the @beta tag to it to make it clear it's experimental. See notes on documenting classes here: https://p5js.org/contribute/contributing_to_the_p5js_reference/#creating-and-documenting-classes

We can use p5.SVGShape as an alternative, or do you have something else in mind?

davepagurek · 2026-09-13T14:40:33Z

+  }
+
+  // Instantiates a new RecordedShape vector container.
+  fn.createShape = function () {


We should probably add some possibly initially minimal jsdoc comments to these. If your examples can be easily added then that's great too

Yes, examples can be easily fitted.

davepagurek · 2026-09-13T14:42:43Z

+        }
+
+        visitRect(node, context) {
+            const w = this.num(node, "width");


btw pretty minor but p5 currently uses 2-space tabs, might be worth doing a quick find-and-replace with before merging?

davepagurek · 2026-09-13T14:50:34Z

Looking good! My main notes before merging are around getting it to a point where it integrates with p5's docs, FES, and TypeScript types, which all comes down to adding jsdoc I believe.

…generation

VANSH3104 · 2026-09-14T14:24:25Z

I’ve addressed all the PR comments and added the JSDoc comments with examples. I also checked the examples on the website, and they look like this:

I added a keypress to the examples so that saveSVG() doesn’t download the SVG automatically.

However, on the website, all the export-related APIs seem to work, but the import APIs don’t behave the same way. The keypress also doesn’t trigger saveSVG() to download the SVG. I’m not sure what the issue is, because the same code works correctly in a sketch but not on the website.

Could there be a difference in how the website handles the loadSVG() API? It seems like the export API uses the recorded shape, while the import API handles the shape differently, but I’m not completely sure.

VANSH3104 · 2026-09-17T10:14:28Z

I’ve added the unit tests to this PR. Once the review is complete, I’ll add the visual tests to the same PR as well. Please let me know if there are any changes or additional test cases you’d like me to consider.

VANSH3104 added 5 commits September 2, 2026 13:59

docs(experimental): add p5.svg experimental warning message and contr…

2323cc4

…ibutor guide

feat(svg): add ShapeRecorder AST node hierarchy and transform stack i…

e9bf36e

…nterceptor

feat(svg): add SVGExportAddon and SVGVisitor renderer implementation

dfa6255

feat(svg): add SVGImportAddon, path command tokenizer, and element co…

e8e0eac

…nverters

feat(svg): add p5.svg entry point with experimental decorators and re…

ff8c36d

…gister in src/app.js

ksen0 reviewed Sep 3, 2026

View reviewed changes

docs(svg): update contributor documentation based on review feedback

8b7e241

VANSH3104 force-pushed the feat/svg-integration branch from 141d8e5 to 8b7e241 Compare September 3, 2026 17:20

davepagurek reviewed Sep 13, 2026

View reviewed changes

VANSH3104 added 4 commits September 14, 2026 14:31

fix(svg): isolate pendingExport state per p5 instance

82482ec

refactor(svg): move RecordedShape to module scope and expose on p5

ff24d5f

docs(svg): add file metadata and fix JSDoc examples

9aa34ad

style(svg): format svg_import.js with 2-space tabs

d9b6031

VANSH3104 force-pushed the feat/svg-integration branch from 742b58b to d9b6031 Compare September 14, 2026 14:06

fix(svg): remove @Property tags from RecordedShape JSDoc to fix type …

77a3f33

…generation

VANSH3104 force-pushed the feat/svg-integration branch from 12c3451 to 77a3f33 Compare September 14, 2026 14:21

Merge branch 'main' into feat/svg-integration

1595975

VANSH3104 mentioned this pull request Sep 16, 2026

test(svg): add unit test suite for native p5.svg module #9181

Closed

3 tasks

VANSH3104 added 4 commits September 17, 2026 15:36

test(svg): add unit tests for shape recorder and transform stack

bbeabbc

test(svg): add unit tests for svg export visitor and XML generation

5f19161

test(svg): add unit tests for svg importer and path command parser

6a7c35e

test(svg): add unit tests for public p5.svg addon APIs and lifecycles

fff96be


		# p5.svg Overview

		`p5.svg` is an experimental native vector graphics system provided in p5.js starting from version 2. It aims to bring resolution-independent vector rendering, SVG file importing, and SVG XML exporting directly into p5.js without requiring external third-party addons. It allows users to record 2D drawing operations using familiar p5 APIs (`rect`, `circle`, `path`, `fill`, `stroke`, `translate`, `rotate`, etc.) and convert them into scalable vector structures.


		`p5.svg` addresses several key goals:

		- Resolution-Independent Vector Output: Traditional canvas rendering in p5.js is raster (pixel) based. `p5.svg` enables artists, designers, and educators to generate scalable vector graphics suitable for high-DPI displays, print, pen plotters, CNC routers, laser cutters, and embroidery machines.


		The main ways you can help develop `p5.svg` are:

		- API Ergonomics & Shape API: Test vector shape recording and rendering functions like `createSVG()`, `loadSVG()`, `buildShape()`, `createShape()`, `shape()`, `getSVG()`, and `saveSVG()`. Share feedback on `shape()` playback, coordinate bounds, positioning, scaling options, and alignment modes (`CORNER`, `CENTER`, `VIEWBOX`).

Uh oh!

Uh oh!

Conversation

VANSH3104 commented Sep 2, 2026

Changes:

PR Checklist

Uh oh!

p5-bot Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Continuous Release

CDN link

Published Packages

Uh oh!

VANSH3104 commented Sep 2, 2026

Uh oh!

ksen0 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davepagurek commented Sep 13, 2026

Uh oh!

VANSH3104 commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

VANSH3104 commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

p5-bot Bot commented Sep 2, 2026 •

edited

Loading

VANSH3104 commented Sep 14, 2026 •

edited

Loading