@awflow/avatar-export 1.0.1 → 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,
@@ -65,7 +86,8 @@ 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.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awflow/avatar-export",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -21,7 +21,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@awflow/avatar": "^1.0.1",
+    "@awflow/avatar": "^1.1.0",
     "@resvg/resvg-wasm": "2.6.2",
     "fflate": "0.8.3",
     "gifenc": "1.0.3"