@munusshih/p5.export 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Munus Shih
+
+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

@@ -0,0 +1,156 @@
+# p5.export
+
+A [p5.js](https://p5js.org) add-on for one-line exports — **PNG, JPG, WebP, animated WebP, GIF, MP4, WebM, SVG, PDF, STL, OBJ** — with an optional floating GUI panel.
+
+Works with **p5.js 1.x and 2.x**. p5 is brought by you (CDN or bundler); this package only ships the add-on.
+
+## Install
+
+### Drop-in `<script>`
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/p5.export"></script>
+<script src="sketch.js"></script>
+```
+
+### npm + bundler
+
+```bash
+npm install p5.export
+```
+
+```js
+import 'p5';          // however you bring p5 onto the page
+import 'p5.export';   // auto-registers against the global p5
+```
+
+That's it. The GUI auto-mounts after `setup()` runs. Disable it with `window.p5ExportConfig = { autoGUI: false }` declared before this script loads, or remove it later with `removeExportGUI()`.
+
+## API
+
+Every export attaches to the p5 prototype, so the calls work like any other p5 function — global mode or instance mode.
+
+### Images
+
+```js
+savePNG('artwork')            // 'artwork.png'
+saveJPG('artwork', { quality: 0.9 })
+saveWebP('artwork')
+saveImage('png', 'artwork', { scale: 2 })   // any of png/jpg/webp/jpeg
+
+// `scale` re-renders at 1×–4× pixelDensity. Trails / fade overlays are
+// preserved by replaying the recorded draw history (no `redraw()` reset).
+savePNG('big', { scale: 4 })
+```
+
+### Vector
+
+```js
+saveSVG('artwork')
+saveSVG('artwork', { forceVector: true })    // skip raster-fallback threshold
+saveSVG('artwork', { raster: true })         // embed canvas PNG inside an SVG
+saveSVG('artwork', { silent: true })         // skip the fallback confirm dialog
+
+savePDF('artwork')
+savePDF('artwork', { scale: 2 })
+```
+
+`saveSVG()` records every Canvas2D draw call as the sketch runs and replays them onto an SVG context. Trails, fade rects, blend modes, gradients (linear / radial — emitted as native SVG gradients), and `drawingContext.setLineDash` all survive. WebGL renderers can only be embedded as a single raster `<image>`; the function prompts before doing so unless `{ silent: true }` or `{ raster: true }` is passed.
+
+For dense sketches whose vector replay would balloon past 2 million ops, the export falls back to raster-in-SVG and asks the user to confirm. To force vector regardless of size, pass `{ forceVector: true }`.
+
+#### Hybrid SVG
+
+Mark expensive sections of your draw so they get rasterised inside the otherwise-vector SVG:
+
+```js
+function setup() {
+  createCanvas(800, 800);
+  // …vector shapes…
+  beginRasterRegion();
+  for (let i = 0; i < 8000; i++) {
+    fill(random(255), random(255), random(255), 80);
+    rect(random(width), random(height), 2, 2);
+  }
+  endRasterRegion();
+  // …more vector shapes on top…
+}
+```
+
+### Video (record once, export to multiple formats)
+
+```js
+const buffer = createVideoBuffer({ duration: 3, fps: 30 });   // starts immediately
+
+// later, after the buffer auto-stops or you call `stopVideoBuffer()`:
+await exportVideoBuffer(buffer, { format: 'mp4',  filename: 'clip' });
+await exportVideoBuffer(buffer, { format: 'webm', filename: 'clip' });
+await exportVideoBuffer(buffer, { format: 'webp', filename: 'clip' });  // animated WebP
+await exportVideoBuffer(buffer, { format: 'gif',  filename: 'clip' });
+```
+
+Frames are captured in real RGBA at the canvas's native resolution. `exportVideoBuffer()` is re-callable on the same buffer — no re-recording — so users can pick the format they want from the GUI without losing the take.
+
+You can also do a one-shot `recordVideo({ format: 'mp4', duration: 3, filename: 'clip' })` if you don't need the multi-format buffer.
+
+### 3D (WEBGL only)
+
+```js
+const myModel = buildGeometry(() => sphere(50));
+saveSTL(myModel, 'sphere.stl');
+saveSTL(myModel, 'sphere.stl', { binary: true });
+
+// Or pass a callback that p5 will run inside buildGeometry for you:
+saveSTL(() => { sphere(50); cone(20, 40); }, 'scene.stl');
+saveOBJ(() => { sphere(50); }, 'scene.obj');
+```
+
+These delegate to p5.js 2.x's native `p5.Geometry.saveStl` / `saveObj`, so the encoded files match what p5 itself produces.
+
+### GUI
+
+The panel auto-mounts post-setup. You can also drive it manually:
+
+```js
+createExportGUI({ title: 'my sketch', filename: 'artwork', collapsed: false });
+removeExportGUI();
+```
+
+Drag from the header to move it. The two tabs (Image / Video) share the same compact form. The Video tab shows a low-res preview with a scrubbable timeline before you commit to encoding.
+
+## Browser support
+
+| Feature | Chrome | Firefox | Safari |
+|---|---|---|---|
+| PNG / JPG / WebP image | ✓ | ✓ | ✓ (WebP 16+) |
+| SVG (vector replay) | ✓ | ✓ | ✓ |
+| PDF | ✓ | ✓ | ✓ |
+| GIF | ✓ | ✓ | ✓ |
+| Animated WebP | ✓ | ✓ | ✓ (16+) |
+| MP4 (WebCodecs / MediaRecorder) | ✓ | partial | partial |
+| WebM (WebCodecs / MediaRecorder) | ✓ | ✓ | partial |
+| STL / OBJ (p5 2.x WEBGL) | ✓ | ✓ | ✓ |
+
+MP4 falls back to WebM automatically if the browser's `MediaRecorder` can't encode H.264.
+
+## Notes
+
+- **p5 1.x**: image, GIF, WebM/MP4, PDF, SVG, and the GUI all work. The SVG path uses a getter-based rebind on the prototype globals so `p5.pattern` and similar 1.x add-ons keep working through the recorder.
+- **STL/OBJ** require a `p5.Geometry`, which only exists in p5 2.x's WEBGL renderer.
+- The GUI's status row uses the `hidden` attribute, so empty messages take no vertical space.
+- The vector SVG recorder caps at 60 frames of draw history by default. Override with `setSVGRecordingFrames(n)` (use `Infinity` to keep everything; expect memory growth on long-running sketches).
+
+## Develop
+
+```bash
+npm install
+npm run build           # writes dist/p5.export.js + dist/p5.export.min.js
+npm run dev             # vite dev server at /examples/index.html
+npm run test:sketches   # headless harness over examples/ — exports each format
+npm run test:webp       # sanity test for the animated WebP encoder
+```
+
+## License
+
+[MIT](./LICENSE)