@awflow/avatar-export 1.0.0 → 1.1.0

package/README.md

@@ -14,7 +14,14 @@ Every function returns a `Promise<Uint8Array>`. In Node, Bun and Deno the
 wasm loads on first use; nothing to set up.
 
 ```ts
-import { toApng, toGif, toPng, toSprite } from '@awflow/avatar-export'
+import {
+  svgToPng,
+  toApng,
+  toGif,
+  toPng,
+  toSprite,
+} from '@awflow/avatar-export'
+import { frames } from '@awflow/avatar'
 
 // a still PNG, 256 px square by default
 const png = await toPng('Linh', { expression: 'happy' }, { size: 512 })
@@ -25,6 +32,20 @@ const apng = await toApng('Linh', { reaction: 'hop' }, { fps: 30, seconds: 3 })
 // a GIF with one 256-colour palette, transparent where nothing is drawn
 const gif = await toGif('Linh', { frame: 'none', activity: 'done' })
 
+// a script: idle, then working from 1 s, a cheer at 3 s, idle again at 4 s
+const story = await toGif('Linh', {
+  timeline: [
+    { at: 1, activity: 'working' },
+    { at: 3, reaction: 'celebrate' },
+    { at: 4, activity: 'idle' },
+  ],
+}, { fps: 25, seconds: 5 })
+
+// any SVG string, such as one frame of frames(), at a given width
+const still = await svgToPng(frames('Linh', {}, { fps: 1, seconds: 1 })[0], {
+  size: 128,
+})
+
 // many avatars on one sheet: 3 columns of 64 px tiles, 4 px apart
 const sheet = await toSprite(['Ada', 'Linh', 'Sam'], {}, {
   size: 64,
@@ -40,7 +61,14 @@ Write the bytes anywhere: `await Bun.write('linh.png', png)`,
 ## Browsers
 
 Load the wasm once with `init` before the first export. It takes a
-`fetch()` response (or its promise), an `ArrayBuffer`, typed array or a `URL`:
+`fetch()` response (or its promise), an `ArrayBuffer`, typed array or a `URL`.
+The wasm file comes from `@resvg/resvg-wasm`, which this package depends on.
+Importing it by path from your own code needs it as a direct dependency under
+strict package managers (pnpm), at the exact version this package uses:
+
+```sh
+npm install @resvg/resvg-wasm@2.6.2
+```
 
 ```ts
 import { init, toPng } from '@awflow/avatar-export'
@@ -58,13 +86,21 @@ return at once.
 `LIMITS` is
 `{ maxFrames: 600, maxSize: 1024, maxSprite: 400, maxSheet: 16777216 }`, with
 `maxFrames` taken from the core's `FRAME_LIMITS` (1 to 120 fps, up to 60
-seconds). `maxSheet` caps a sprite sheet's area at 4096 by 4096 pixels. Frames are `round(fps * seconds)`, checked before anything is
+seconds). `maxSheet` caps a sprite sheet's area, and an `svgToPng` image's,
+at 4096 by 4096 pixels. A `timeline` holds at most `maxFrames` cues. Frames are `round(fps * seconds)`, checked before anything is
 drawn. A value out of range, or not a finite number, throws a `RangeError`
 that names the limit.
 
 GIF counts time in hundredths of a second and browsers slow down frames
 shorter than 2/100 s, so keep GIFs at 50 fps or less. APNG timing is exact.
 
+Rasterising is synchronous CPU work on the calling thread. On a recent laptop
+a 1024 px, 60-frame export takes about 13 s as a GIF and 17 s as an APNG, and
+a sheet of 256 tiles at 256 px about 11 s. The worst case the limits allow,
+600 frames at 1024 px, is minutes of CPU. On a server, cap `size`, `fps` and
+`seconds` well below `LIMITS` for untrusted input, and run exports in a worker
+or a queue rather than on the request path.
+
 ## Docs
 
 Full documentation: <https://github.com/awflow/agent-avatar#readme>
@@ -72,7 +108,9 @@ Full documentation: <https://github.com/awflow/agent-avatar#readme>
 ## Credits
 
 Built on Peek by Doan Labs (MIT). Rasterising by
-[resvg](https://github.com/linebender/resvg), GIF encoding by
+[resvg](https://github.com/linebender/resvg) through
+[`@resvg/resvg-wasm`](https://www.npmjs.com/package/@resvg/resvg-wasm)
+(MPL-2.0), GIF encoding by
 [gifenc](https://github.com/mattdesl/gifenc), compression by
 [fflate](https://github.com/101arrowz/fflate).
 

package/dist/animated.d.ts

@@ -1,6 +1,12 @@
-import { type AvatarOptions, type Reaction } from '@awflow/avatar';
+import { type AvatarOptions, type Cue, type Reaction } from '@awflow/avatar';
+/**
+ * What to animate: any avatar options (a registered `character` included),
+ * a `reaction` from the first frame, and a `timeline` of later cues: an
+ * activity, an expression or a reaction at a time in seconds.
+ */
 export type AnimatedOptions = AvatarOptions & {
     reaction?: Reaction;
+    timeline?: readonly Cue[];
 };
 export type AnimationSettings = {
     /** Side in pixels, 1 to LIMITS.maxSize. Default 256. */

package/dist/index.d.ts

@@ -6,6 +6,14 @@ export type { WasmSource } from './raster.js';
 export { init } from './raster.js';
 export type { SpriteSettings } from './sprite.js';
 export { toSprite } from './sprite.js';
+/**
+ * Any avatar SVG (one frame of `frames()`, or a sheet of them) as a PNG,
+ * `size` pixels wide (default 256, at most LIMITS.maxSize). The height
+ * follows the SVG's aspect ratio.
+ */
+export declare function svgToPng(svg: string, o?: {
+    size?: number;
+}): Promise<Uint8Array>;
 /** The avatar as a still PNG, `size` pixels square (default 256). */
 export declare function toPng(name: string, opts?: AvatarOptions, o?: {
     size?: number;

package/dist/index.js

@@ -101,8 +101,13 @@ var options = (size) => ({
   fitTo: { mode: "width", value: size },
   font: { loadSystemFonts: false }
 });
-function png(svg, size) {
+function png(svg, size, maxPixels) {
   const resvg = new Resvg(svg, options(size));
+  const area = resvg.width > 0 ? size * size * (resvg.height / resvg.width) : 0;
+  if (maxPixels !== undefined && area > maxPixels) {
+    resvg.free();
+    throw new RangeError(`svgToPng(): ${Math.round(area)} pixels is above maxSheet ${maxPixels}`);
+  }
   const image = resvg.render();
   try {
     return image.asPng();
@@ -134,7 +139,9 @@ function rgba(svg, size) {
 }
 
 // src/animated.ts
-import { frames } from "@awflow/avatar";
+import {
+  frames
+} from "@awflow/avatar";
 import * as gifenc from "gifenc";
 
 // src/png.ts
@@ -392,6 +399,13 @@ async function toSprite(names, opts = {}, o = {}) {
 }
 
 // src/index.ts
+async function svgToPng(svg, o = {}) {
+  const size = checkSize("svgToPng()", o.size);
+  if (typeof svg !== "string" || !svg.trimStart().startsWith("<svg"))
+    throw new TypeError("svgToPng(): svg must be an SVG string");
+  await ensure();
+  return png(svg, size, LIMITS.maxSheet);
+}
 async function toPng(name, opts = {}, o = {}) {
   const size = checkSize("toPng()", o.size);
   await ensure();
@@ -402,6 +416,7 @@ export {
   toPng,
   toGif,
   toApng,
+  svgToPng,
   init,
   LIMITS,
   DEFAULTS

package/dist/raster.d.ts

@@ -9,8 +9,12 @@ export type WasmSource = ArrayBuffer | ArrayBufferView | Response | URL | WebAss
 export declare function init(wasm?: WasmSource | PromiseLike<WasmSource>): Promise<void>;
 /** The export functions wait on this: init() with no argument when needed. */
 export declare const ensure: () => Promise<void>;
-/** One SVG as a PNG, size pixels wide, encoded by resvg. */
-export declare function png(svg: string, size: number): Uint8Array;
+/**
+ * One SVG as a PNG, size pixels wide, encoded by resvg. With `maxPixels`,
+ * an SVG whose height would take the image past that area is refused before
+ * any pixel is drawn.
+ */
+export declare function png(svg: string, size: number, maxPixels?: number): Uint8Array;
 /**
  * One SVG as straight (not premultiplied) RGBA pixels, size by size. resvg
  * hands premultiplied pixels back; they are demultiplied the way its own PNG

package/dist/sprite.d.ts

@@ -12,4 +12,4 @@ export type SpriteSettings = {
  * (columns - 1) * gap, height likewise for the rows used. The same options
  * apply to every tile. The sheet's area is at most LIMITS.maxSheet pixels. Name i sits at column i % columns, row i / columns.
  */
-export declare function toSprite(names: string[], opts?: AvatarOptions, o?: SpriteSettings): Promise<Uint8Array>;
+export declare function toSprite(names: readonly string[], opts?: AvatarOptions, o?: SpriteSettings): Promise<Uint8Array>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awflow/avatar-export",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -21,13 +21,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@awflow/avatar": "^1.0.0",
+    "@awflow/avatar": "^1.1.0",
     "@resvg/resvg-wasm": "2.6.2",
     "fflate": "0.8.3",
     "gifenc": "1.0.3"
   },
   "description": "Rasterise AWFlow avatars to PNG, APNG, GIF and sprite sheets, in Node and the browser.",
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "author": "AWFlow",
   "homepage": "https://github.com/awflow/agent-avatar",
   "repository": {