@munusshih/p5.export 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,5 +1,14 @@
 # p5.export
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/munusshih/p5.export/main/p5.export.png" alt="p5.export panel previewing an animated p5.js sketch" width="900">
+</p>
+
+[![npm version](https://img.shields.io/npm/v/%40munusshih%2Fp5.export?logo=npm&color=cb3837)](https://www.npmjs.com/package/@munusshih/p5.export)
+[![npm downloads](https://img.shields.io/npm/dm/%40munusshih%2Fp5.export?logo=npm)](https://www.npmjs.com/package/@munusshih/p5.export)
+[![license](https://img.shields.io/npm/l/%40munusshih%2Fp5.export)](./LICENSE)
+[![publish status](https://github.com/munusshih/p5.export/actions/workflows/publish-npm.yml/badge.svg?branch=main)](https://github.com/munusshih/p5.export/actions/workflows/publish-npm.yml)
+
 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.
@@ -9,11 +18,19 @@ Works with **p5.js 1.x and 2.x**. p5 is brought by you (CDN or bundler); this pa
 ### Drop-in `<script>`
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@munusshih/p5.export"></script>
+<script src="https://unpkg.com/p5@latest/lib/p5.min.js"></script>
+<script src="https://unpkg.com/@munusshih/p5.export@latest"></script>
 <script src="sketch.js"></script>
 ```
 
+`@latest` follows npm's current `latest` release. For a reproducible production
+site, replace it with the exact version shown by the npm badge above, for
+example:
+
+```html
+<script src="https://unpkg.com/@munusshih/p5.export@0.1.0-beta.8/dist/p5.export.min.js"></script>
+```
+
 ### npm + bundler
 
 ```bash
@@ -22,7 +39,19 @@ npm install @munusshih/p5.export
 
 ```js
 import 'p5';          // however you bring p5 onto the page
-import '@munusshih/p5.export';   // auto-registers against the global p5
+import '@munusshih/p5.export';   // auto-registers
+```
+
+This auto-registers even under bundlers: p5 2.x's ESM build never assigns
+`window.p5`, so the add-on falls back to resolving `p5` as a module. For
+**guaranteed registration order** (recommended for instance-mode sketches or
+strict bundlers), register explicitly instead:
+
+```js
+import p5 from 'p5';
+import { register } from '@munusshih/p5.export';
+
+register(p5);   // before you create the sketch / define setup()
 ```
 
 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()`.
@@ -51,6 +80,7 @@ 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
+saveSVG('artwork', { outlineText: false })   // keep text() as editable <text> (default is outlined)
 
 savePDF('artwork')
 savePDF('artwork', { scale: 2 })
@@ -58,6 +88,20 @@ 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.
 
+#### Text and fonts
+
+By default `text()` is exported as **vector glyph outlines**, which render identically everywhere with no fonts installed. This is the default because fonts loaded via `loadFont()` are drawn by p5 in a way `canvas2svg` can't capture as `<text>` — they'd otherwise drop out of the SVG entirely. Outlining works for fonts loaded from an uncompressed `.ttf`/`.otf` (p5 can't read glyph data from `.woff2`); system/string fonts have no outline data and fall back to `<text>`.
+
+Pass `{ outlineText: false }` to keep text as **editable `<text>`** instead (font-family reference; the font must be available wherever the SVG is opened, or it falls back).
+
+```js
+saveSVG('poster', { outlineText: false });  // per-call, keep editable <text>
+setSVGTextMode('text');                      // make editable <text> the default for this sketch
+// also: window.p5ExportConfig = { svgTextOutlines: false } before the sketch loads
+```
+
+In the export GUI, pick **SVG (vector)**; **Outline (vector)** is ticked by default — untick it for editable `<text>`. See `examples/fonts/` for a multi-typeface demo.
+
 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
@@ -81,7 +125,13 @@ function setup() {
 ### Video (record once, export to multiple formats)
 
 ```js
-const buffer = createVideoBuffer({ duration: 3, fps: 30 });   // starts immediately
+// Starts immediately. By default, export timing follows the rate set by
+// frameRate(), so a frameRate(1) sketch remains one frame per second.
+const buffer = createVideoBuffer({ duration: 3 });
+
+// Record a sharper 2× render. Set fps only when you intentionally want to
+// override the sketch's target frame rate.
+const hiResBuffer = createVideoBuffer({ duration: 3, scale: 2, fps: 30 });
 
 // later, after the buffer auto-stops or you call `stopVideoBuffer()`:
 await exportVideoBuffer(buffer, { format: 'mp4',  filename: 'clip' });
@@ -90,7 +140,7 @@ await exportVideoBuffer(buffer, { format: 'webp', filename: 'clip' });  // anima
 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.
+Frames are captured in real RGBA at the sketch's target frame rate. Set `scale` from 1–4 to render the recording at that pixel density instead of enlarging the encoded pixels afterward. `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.
 
@@ -117,7 +167,7 @@ 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.
+Drag from the header to move it. The two tabs (Image / Video) share the same compact form. The Video tab includes a 1×–4× recording scale and shows a low-res preview with a scrubbable timeline before you commit to encoding.
 
 ## Browser support
 
@@ -146,11 +196,30 @@ MP4 falls back to WebM automatically if the browser's `MediaRecorder` can't enco
 ```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 dev             # Vite dev server; opens the live GUI preview
+npm run dev:gui         # explicitly open /test/manual/gui-preview.html
 npm run test:sketches   # headless harness over examples/ — exports each format
+npm run test:svg-path2d # p5 2.3+ vector primitive regression
 npm run test:webp       # sanity test for the animated WebP encoder
 ```
 
+Every push to `main` finds the highest published `0.1.0-beta.N`, publishes the
+next beta number, and assigns it to npm's `latest` tag. The workflow then reads
+`@munusshih/p5.export@latest` back from npm and fails unless it matches the
+version just published. Publishing uses npm Trusted Publishing (OIDC), with no
+long-lived npm token. Configure the package's trusted publisher on npmjs.com
+with these exact values:
+
+- Provider: **GitHub Actions**
+- Organization or user: **munusshih**
+- Repository: **p5.export**
+- Workflow filename: **publish-npm.yml**
+- Environment: leave blank
+- Allowed action: **npm publish**
+
+The workflow filename is matched exactly by npm and lives at
+`.github/workflows/publish-npm.yml`.
+
 ## License
 
 [MIT](./LICENSE)