@awflow/avatar-export 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Doan Labs
+Copyright (c) 2026 AWFlow
+
+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

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @awflow/avatar-export
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AWFlow avatars as PNG, animated PNG, GIF and sprite sheets, in Node and the
+browser. Rasterised by resvg compiled to WebAssembly, so the same name and
+options give the same bytes on every machine. Built on Peek by Doan Labs.
+
+```sh
+npm install @awflow/avatar-export @awflow/avatar
+```
+
+## Use
+
+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'
+
+// a still PNG, 256 px square by default
+const png = await toPng('Linh', { expression: 'happy' }, { size: 512 })
+
+// an animated PNG: lossless, full alpha, 24 fps for 2 s by default
+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' })
+
+// many avatars on one sheet: 3 columns of 64 px tiles, 4 px apart
+const sheet = await toSprite(['Ada', 'Linh', 'Sam'], {}, {
+  size: 64,
+  columns: 3,
+  gap: 4,
+})
+```
+
+Write the bytes anywhere: `await Bun.write('linh.png', png)`,
+`fs.writeFileSync('linh.gif', gif)`, or
+`URL.createObjectURL(new Blob([png], { type: 'image/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`.
+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'
+import wasmUrl from '@resvg/resvg-wasm/index_bg.wasm?url' // Vite
+
+await init(fetch(wasmUrl))
+const png = await toPng('Linh')
+```
+
+`init` is idempotent: concurrent calls share one load, and later calls
+return at once.
+
+## Limits
+
+`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
+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>
+
+## Credits
+
+Built on Peek by Doan Labs (MIT). Rasterising 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).
+
+[MIT](./LICENSE) © Doan Labs, © AWFlow

package/bin/awflow-avatar-export.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/* `npx @awflow/avatar-export Linh --png 256`: the core CLI with this package
+ * guaranteed to be the export module. */
+import { run } from '@awflow/avatar/cli'
+
+await run(process.argv.slice(2), () => import('../dist/index.js'))

package/dist/animated.d.ts

@@ -0,0 +1,37 @@
+import { type AvatarOptions, type Reaction } from '@awflow/avatar';
+export type AnimatedOptions = AvatarOptions & {
+    reaction?: Reaction;
+};
+export type AnimationSettings = {
+    /** Side in pixels, 1 to LIMITS.maxSize. Default 256. */
+    size?: number;
+    /** Frames per second, FRAME_LIMITS.minFps to maxFps. Default 24. */
+    fps?: number;
+    /** Length in seconds, above 0 up to FRAME_LIMITS.maxSeconds. Default 2. */
+    seconds?: number;
+};
+/**
+ * One palette for a whole animation, from an even sample of at most
+ * SAMPLE_PIXELS pixels across all frames. Transparency is looked for in every
+ * pixel, not only the sample, so a small clear area is never lost: when there
+ * is one, the palette always keeps a fully transparent entry (forced in if
+ * quantising dropped it). Exported for the tests, not from the package.
+ */
+export declare function paletteFor(count: number, pixels: number, frame: (i: number) => Uint8Array): {
+    format: 'rgb565' | 'rgb444' | 'rgba4444';
+    palette: number[][];
+    transparentIndex: number;
+};
+/**
+ * An animated PNG of `seconds` of the live avatar at `fps`, looping forever.
+ * Lossless with full alpha. A `reaction` in the options starts on frame one.
+ */
+export declare function toApng(name: string, opts?: AnimatedOptions, o?: AnimationSettings): Promise<Uint8Array>;
+/**
+ * An animated GIF of `seconds` of the live avatar at `fps`, looping forever.
+ * One 256-colour palette is quantised for the whole animation (gifenc). The
+ * background is transparent wherever the avatar draws nothing, e.g. with
+ * `frame: 'none'`. GIF counts time in hundredths of a second: frame delays
+ * are rounded so the total stays exact.
+ */
+export declare function toGif(name: string, opts?: AnimatedOptions, o?: AnimationSettings): Promise<Uint8Array>;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { AvatarOptions } from '@awflow/avatar';
+export type { AnimatedOptions, AnimationSettings, } from './animated.js';
+export { toApng, toGif } from './animated.js';
+export { DEFAULTS, LIMITS } from './limits.js';
+export type { WasmSource } from './raster.js';
+export { init } from './raster.js';
+export type { SpriteSettings } from './sprite.js';
+export { toSprite } from './sprite.js';
+/** The avatar as a still PNG, `size` pixels square (default 256). */
+export declare function toPng(name: string, opts?: AvatarOptions, o?: {
+    size?: number;
+}): Promise<Uint8Array>;

package/dist/index.js

@@ -0,0 +1,408 @@
+// src/index.ts
+import { toSvg as toSvg2 } from "@awflow/avatar";
+
+// src/limits.ts
+import { FRAME_LIMITS } from "@awflow/avatar";
+var LIMITS = Object.freeze({
+  maxFrames: FRAME_LIMITS.maxFrames,
+  maxSize: 1024,
+  maxSprite: 400,
+  maxSheet: 16777216
+});
+var DEFAULTS = Object.freeze({ size: 256, fps: 24, seconds: 2 });
+function whole(fn, what, value, fallback, min, limit) {
+  if (value === undefined)
+    return fallback;
+  const max = LIMITS[limit];
+  if (!Number.isInteger(value) || value < min || value > max)
+    throw new RangeError(`${fn}: ${what} ${value} must be a whole number from ${min} to ${limit} ${max}`);
+  return value;
+}
+var checkSize = (fn, size) => whole(fn, "size", size, DEFAULTS.size, 1, "maxSize");
+var checkGap = (fn, gap) => whole(fn, "gap", gap, 0, 0, "maxSize");
+function checkSprite(fn, names, columns) {
+  const n = names.length;
+  if (n < 1 || n > LIMITS.maxSprite)
+    throw new RangeError(`${fn}: ${n} names must be from 1 to maxSprite ${LIMITS.maxSprite}`);
+  return whole(fn, "columns", columns, Math.ceil(Math.sqrt(n)), 1, "maxSprite");
+}
+function checkTiming(fn, o) {
+  const L = FRAME_LIMITS;
+  const fps = o.fps ?? DEFAULTS.fps;
+  const seconds = o.seconds ?? DEFAULTS.seconds;
+  if (!Number.isFinite(fps))
+    throw new RangeError(`${fn}: fps ${fps} must be a finite number from minFps ${L.minFps} to maxFps ${L.maxFps}`);
+  if (fps < L.minFps)
+    throw new RangeError(`${fn}: fps ${fps} is below minFps ${L.minFps}`);
+  if (fps > L.maxFps)
+    throw new RangeError(`${fn}: fps ${fps} is above maxFps ${L.maxFps}`);
+  if (!Number.isFinite(seconds) || seconds <= 0)
+    throw new RangeError(`${fn}: seconds ${seconds} must be a finite number above 0, up to maxSeconds ${L.maxSeconds}`);
+  if (seconds > L.maxSeconds)
+    throw new RangeError(`${fn}: seconds ${seconds} is above maxSeconds ${L.maxSeconds}`);
+  const count = Math.round(fps * seconds);
+  if (count > LIMITS.maxFrames)
+    throw new RangeError(`${fn}: ${count} frames is above maxFrames ${LIMITS.maxFrames}`);
+  if (count < 1)
+    throw new RangeError(`${fn}: fps ${fps} for ${seconds} seconds rounds to 0 frames, at least 1 is needed`);
+  return { fps, seconds, count };
+}
+function checkSheet(fn, w, h) {
+  if (w * h > LIMITS.maxSheet)
+    throw new RangeError(`${fn}: a ${w}x${h} sheet is ${w * h} pixels, above maxSheet ${LIMITS.maxSheet}`);
+}
+
+// src/raster.ts
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+var ready;
+function init(wasm) {
+  ready ??= load(wasm).catch((error) => {
+    ready = undefined;
+    throw error;
+  });
+  return ready;
+}
+var ensure = () => ready ?? init();
+async function load(given) {
+  const bytes = await source(await given);
+  try {
+    await initWasm(bytes);
+  } catch (error) {
+    if (!/already initiali[sz]ed/i.test(String(error)))
+      throw error;
+  }
+}
+async function source(wasm) {
+  if (wasm === undefined)
+    return bundled();
+  if (wasm instanceof URL)
+    return source(await fetch(wasm));
+  if (wasm instanceof ArrayBuffer || ArrayBuffer.isView(wasm))
+    return wasm;
+  if (typeof wasm.arrayBuffer === "function") {
+    const res = wasm;
+    if (!res.ok)
+      throw new Error(`init(): fetching the wasm failed with ${res.status}`);
+    return res.arrayBuffer();
+  }
+  return wasm;
+}
+async function bundled() {
+  const proc = globalThis.process;
+  if (!proc?.versions?.node)
+    throw new TypeError("init(): in a browser pass the resvg wasm, e.g. init(fetch(wasmUrl)) with the URL of @resvg/resvg-wasm/index_bg.wasm");
+  const load2 = (id) => import(id);
+  const { createRequire } = await load2("node:module");
+  const { readFile } = await load2("node:fs/promises");
+  const path = createRequire(import.meta.url).resolve("@resvg/resvg-wasm/index_bg.wasm");
+  return new Uint8Array(await readFile(path));
+}
+var options = (size) => ({
+  fitTo: { mode: "width", value: size },
+  font: { loadSystemFonts: false }
+});
+function png(svg, size) {
+  const resvg = new Resvg(svg, options(size));
+  const image = resvg.render();
+  try {
+    return image.asPng();
+  } finally {
+    image.free();
+    resvg.free();
+  }
+}
+function rgba(svg, size) {
+  const resvg = new Resvg(svg, options(size));
+  const image = resvg.render();
+  try {
+    const px = image.pixels.slice();
+    if (image.width !== size || image.height !== size)
+      throw new Error(`rasterising gave ${image.width}x${image.height}, expected ${size}x${size}`);
+    for (let i = 0;i < px.length; i += 4) {
+      const a = px[i + 3];
+      if (a === 255 || a === 0)
+        continue;
+      px[i] = Math.round(px[i] * 255 / a);
+      px[i + 1] = Math.round(px[i + 1] * 255 / a);
+      px[i + 2] = Math.round(px[i + 2] * 255 / a);
+    }
+    return px;
+  } finally {
+    image.free();
+    resvg.free();
+  }
+}
+
+// src/animated.ts
+import { frames } from "@awflow/avatar";
+import * as gifenc from "gifenc";
+
+// src/png.ts
+import { zlibSync } from "fflate";
+var SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+var CRC = new Uint32Array(256);
+for (let n = 0;n < 256; n++) {
+  let c = n;
+  for (let k = 0;k < 8; k++)
+    c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  CRC[n] = c >>> 0;
+}
+function crc32(bytes, crc = 4294967295) {
+  for (let i = 0;i < bytes.length; i++)
+    crc = CRC[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  return crc;
+}
+
+class Writer {
+  parts = [Uint8Array.from(SIGNATURE)];
+  chunk(type, data) {
+    const head = new Uint8Array(8);
+    const view = new DataView(head.buffer);
+    view.setUint32(0, data.length);
+    for (let i = 0;i < 4; i++)
+      head[4 + i] = type.charCodeAt(i);
+    const tail = new Uint8Array(4);
+    const crc = crc32(data, crc32(head.subarray(4)));
+    new DataView(tail.buffer).setUint32(0, (crc ^ 4294967295) >>> 0);
+    this.parts.push(head, data, tail);
+  }
+  bytes() {
+    const out = new Uint8Array(this.parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of this.parts) {
+      out.set(p, at);
+      at += p.length;
+    }
+    return out;
+  }
+}
+function fields(...values) {
+  const out = new Uint8Array(values.reduce((n, [, b]) => n + b, 0));
+  const view = new DataView(out.buffer);
+  let at = 0;
+  for (const [v, b] of values) {
+    if (b === 4)
+      view.setUint32(at, v);
+    else if (b === 2)
+      view.setUint16(at, v);
+    else
+      view.setUint8(at, v);
+    at += b;
+  }
+  return out;
+}
+var ihdr = (w, h) => fields([w, 4], [h, 4], [8, 1], [6, 1], [0, 1], [0, 1], [0, 1]);
+var paeth = (a, b, c) => {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+};
+function compress(px, stride, x, y, w, h) {
+  const row = w * 4;
+  const raw = new Uint8Array(h * (row + 1));
+  const tries = Array.from({ length: 5 }, () => new Uint8Array(row));
+  for (let r = 0;r < h; r++) {
+    const at = ((y + r) * stride + x) * 4;
+    const cur = px.subarray(at, at + row);
+    const prev = r ? px.subarray(at - stride * 4, at - stride * 4 + row) : null;
+    let best = 0;
+    let bestSum = Number.POSITIVE_INFINITY;
+    for (let f = 0;f < 5; f++) {
+      const out = tries[f];
+      let sum = 0;
+      for (let i = 0;i < row; i++) {
+        const a = i >= 4 ? cur[i - 4] : 0;
+        const b = prev ? prev[i] : 0;
+        const c = prev && i >= 4 ? prev[i - 4] : 0;
+        const pred = f === 0 ? 0 : f === 1 ? a : f === 2 ? b : f === 3 ? a + b >> 1 : paeth(a, b, c);
+        const v = cur[i] - pred & 255;
+        out[i] = v;
+        sum += v < 128 ? v : 256 - v;
+      }
+      if (sum < bestSum) {
+        bestSum = sum;
+        best = f;
+      }
+    }
+    const o = r * (row + 1);
+    raw[o] = best;
+    raw.set(tries[best], o + 1);
+  }
+  return zlibSync(raw, { level: 9 });
+}
+function encodePng(px, w, h) {
+  const png2 = new Writer;
+  png2.chunk("IHDR", ihdr(w, h));
+  png2.chunk("IDAT", compress(px, w, 0, 0, w, h));
+  png2.chunk("IEND", new Uint8Array(0));
+  return png2.bytes();
+}
+function changed(a, b, w, h) {
+  const A = new Uint32Array(a.buffer, a.byteOffset, w * h);
+  const B = new Uint32Array(b.buffer, b.byteOffset, w * h);
+  let x0 = w;
+  let y0 = h;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0;y < h; y++) {
+    const o = y * w;
+    for (let x = 0;x < w; x++) {
+      if (A[o + x] === B[o + x])
+        continue;
+      if (x < x0)
+        x0 = x;
+      if (x > x1)
+        x1 = x;
+      if (y < y0)
+        y0 = y;
+      y1 = y;
+    }
+  }
+  return x1 < 0 ? { x: 0, y: 0, w: 1, h: 1 } : { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 };
+}
+function encodeApng(count, frame, w, h, delay) {
+  const png2 = new Writer;
+  png2.chunk("IHDR", ihdr(w, h));
+  png2.chunk("acTL", fields([count, 4], [0, 4]));
+  let seq = 0;
+  let prev;
+  for (let i = 0;i < count; i++) {
+    const px = frame(i);
+    const box = prev ? changed(prev, px, w, h) : { x: 0, y: 0, w, h };
+    png2.chunk("fcTL", fields([seq++, 4], [box.w, 4], [box.h, 4], [box.x, 4], [box.y, 4], [delay[0], 2], [delay[1], 2], [0, 1], [0, 1]));
+    const data = compress(px, w, box.x, box.y, box.w, box.h);
+    if (i === 0)
+      png2.chunk("IDAT", data);
+    else {
+      const fd = new Uint8Array(4 + data.length);
+      new DataView(fd.buffer).setUint32(0, seq++);
+      fd.set(data, 4);
+      png2.chunk("fdAT", fd);
+    }
+    prev = px;
+  }
+  png2.chunk("IEND", new Uint8Array(0));
+  return png2.bytes();
+}
+
+// src/animated.ts
+var gif = "GIFEncoder" in gifenc && typeof gifenc.GIFEncoder === "function" ? gifenc : gifenc.default;
+var KEEP_BYTES = 64 * 1024 * 1024;
+var SAMPLE_PIXELS = 1 << 21;
+function paletteFor(count, pixels, frame) {
+  const stride = Math.max(1, Math.ceil(count * pixels / SAMPLE_PIXELS));
+  const sample = new Uint8Array(Math.ceil(count * pixels / stride) * 4);
+  let taken = 0;
+  let next = 0;
+  let clear = false;
+  for (let i = 0;i < count; i++) {
+    const px = frame(i);
+    if (!clear) {
+      for (let a = 3;a < px.length; a += 4)
+        if (px[a] < 128) {
+          clear = true;
+          break;
+        }
+    }
+    const base = i * pixels;
+    for (;next < base + pixels; next += stride) {
+      const at = (next - base) * 4;
+      sample.set(px.subarray(at, at + 4), taken * 4);
+      taken++;
+    }
+  }
+  const format = clear ? "rgba4444" : "rgb565";
+  const palette = gif.quantize(sample.subarray(0, taken * 4), 256, {
+    format,
+    oneBitAlpha: clear
+  });
+  if (!clear)
+    return { format, palette, transparentIndex: -1 };
+  let transparentIndex = palette.findIndex((c) => c[3] === 0);
+  if (transparentIndex < 0) {
+    transparentIndex = Math.min(palette.length, 255);
+    palette[transparentIndex] = [0, 0, 0, 0];
+  }
+  return { format, palette, transparentIndex };
+}
+async function prepare(fn, name, opts, o) {
+  const size = checkSize(fn, o.size);
+  const { fps, seconds, count } = checkTiming(fn, o);
+  await ensure();
+  const svgs = frames(name, opts, { fps, seconds });
+  return { size, fps, svgs, count };
+}
+async function toApng(name, opts = {}, o = {}) {
+  const { size, fps, svgs, count } = await prepare("toApng()", name, opts, o);
+  const delay = [100, Math.round(fps * 100)];
+  return encodeApng(count, (i) => rgba(svgs[i], size), size, size, delay);
+}
+async function toGif(name, opts = {}, o = {}) {
+  const { size, fps, svgs, count } = await prepare("toGif()", name, opts, o);
+  const pixels = size * size;
+  const keep = count * pixels * 4 <= KEEP_BYTES;
+  const held = [];
+  const frame = (i) => held[i] ?? rgba(svgs[i], size);
+  const { format, palette, transparentIndex } = paletteFor(count, pixels, (i) => {
+    const px = frame(i);
+    if (keep)
+      held[i] = px;
+    return px;
+  });
+  const transparent = transparentIndex >= 0;
+  const out = gif.GIFEncoder();
+  for (let i = 0;i < count; i++) {
+    const index = gif.applyPalette(frame(i), palette, format);
+    const cs = Math.round((i + 1) * 100 / fps) - Math.round(i * 100 / fps);
+    out.writeFrame(index, size, size, {
+      palette: i === 0 ? palette : undefined,
+      delay: cs * 10,
+      repeat: 0,
+      transparent,
+      transparentIndex: transparent ? transparentIndex : 0,
+      dispose: transparent ? 2 : 1
+    });
+  }
+  out.finish();
+  return out.bytes();
+}
+// src/sprite.ts
+import { toSvg } from "@awflow/avatar";
+async function toSprite(names, opts = {}, o = {}) {
+  const fn = "toSprite()";
+  const columns = checkSprite(fn, names, o.columns);
+  const size = checkSize(fn, o.size);
+  const gap = checkGap(fn, o.gap);
+  const rows = Math.ceil(names.length / columns);
+  const w = columns * size + (columns - 1) * gap;
+  const h = rows * size + (rows - 1) * gap;
+  checkSheet(fn, w, h);
+  await ensure();
+  const sheet = new Uint8Array(w * h * 4);
+  names.forEach((name, i) => {
+    const tile = rgba(toSvg(name, opts), size);
+    const x = i % columns * (size + gap);
+    const y = Math.floor(i / columns) * (size + gap);
+    for (let r = 0;r < size; r++)
+      sheet.set(tile.subarray(r * size * 4, (r + 1) * size * 4), ((y + r) * w + x) * 4);
+  });
+  return encodePng(sheet, w, h);
+}
+
+// src/index.ts
+async function toPng(name, opts = {}, o = {}) {
+  const size = checkSize("toPng()", o.size);
+  await ensure();
+  return png(toSvg2(name, opts), size);
+}
+export {
+  toSprite,
+  toPng,
+  toGif,
+  toApng,
+  init,
+  LIMITS,
+  DEFAULTS
+};

package/dist/limits.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The export caps: `maxFrames` is the core's own (FRAME_LIMITS, one source of
+ * truth), `maxSize` bounds the side of an image in pixels, `maxSprite` the
+ * number of names on one sheet and `maxSheet` a sheet's area in pixels
+ * (4096 squared).
+ */
+export declare const LIMITS: Readonly<{
+    maxFrames: 600;
+    maxSize: 1024;
+    maxSprite: 400;
+    maxSheet: 16777216;
+}>;
+export declare const DEFAULTS: Readonly<{
+    size: 256;
+    fps: 24;
+    seconds: 2;
+}>;
+export declare const checkSize: (fn: string, size: number | undefined) => number;
+/** Tile gap in pixels: 0 up to maxSize. */
+export declare const checkGap: (fn: string, gap: number | undefined) => number;
+/** A sprite sheet's names and columns. */
+export declare function checkSprite(fn: string, names: readonly string[], columns: number | undefined): number;
+/**
+ * fps and seconds against FRAME_LIMITS, then the frame count round(fps *
+ * seconds) against maxFrames, all before rendering.
+ */
+export declare function checkTiming(fn: string, o: {
+    fps?: number;
+    seconds?: number;
+}): {
+    fps: number;
+    seconds: number;
+    count: number;
+};
+/** A sprite sheet's area, w * h, against maxSheet, before any allocation. */
+export declare function checkSheet(fn: string, w: number, h: number): void;

package/dist/png.d.ts

@@ -0,0 +1,10 @@
+/** A still PNG of an RGBA buffer. */
+export declare function encodePng(px: Uint8Array, w: number, h: number): Uint8Array;
+/**
+ * An animated PNG that loops forever. `frame(i)` gives frame i as RGBA;
+ * frames are pulled one at a time so only two are held at once. Each frame
+ * after the first stores only the box that changed, replacing those pixels
+ * (blend source) over the previous frame left in place (dispose none).
+ * `delay` is each frame's length as a [numerator, denominator] of seconds.
+ */
+export declare function encodeApng(count: number, frame: (i: number) => Uint8Array, w: number, h: number, delay: readonly [number, number]): Uint8Array;

package/dist/raster.d.ts

@@ -0,0 +1,19 @@
+/** What init() accepts: wasm bytes, a fetch() Response, or a URL to fetch. */
+export type WasmSource = ArrayBuffer | ArrayBufferView | Response | URL | WebAssembly.Module;
+/**
+ * Loads the resvg wasm once. Idempotent and safe to call concurrently: every
+ * caller shares one in-flight promise, and a failed load can be retried.
+ * In Node (and Bun or Deno) a call without an argument loads the wasm bundled
+ * in `@resvg/resvg-wasm`; in a browser pass it, e.g. `init(fetch(wasmUrl))`.
+ */
+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 straight (not premultiplied) RGBA pixels, size by size. resvg
+ * hands premultiplied pixels back; they are demultiplied the way its own PNG
+ * encoder does it, so a tile reads as the PNG of the same avatar would.
+ */
+export declare function rgba(svg: string, size: number): Uint8Array;

package/dist/sprite.d.ts

@@ -0,0 +1,15 @@
+import { type AvatarOptions } from '@awflow/avatar';
+export type SpriteSettings = {
+    /** Each tile's side in pixels, 1 to LIMITS.maxSize. Default 256. */
+    size?: number;
+    /** Tiles per row, 1 to LIMITS.maxSprite. Default ceil(sqrt(names)). */
+    columns?: number;
+    /** Transparent pixels between tiles, 0 to LIMITS.maxSize. Default 0. */
+    gap?: number;
+};
+/**
+ * The names as one PNG grid, `columns` tiles wide: width is columns * size +
+ * (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: readonly string[], opts?: AvatarOptions, o?: SpriteSettings): Promise<Uint8Array>;

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@awflow/avatar-export",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "awflow-avatar-export": "./bin/awflow-avatar-export.mjs"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@awflow/avatar": "^1.0.1",
+    "@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": {
+    "type": "git",
+    "url": "git+https://github.com/awflow/agent-avatar.git",
+    "directory": "packages/avatar-export"
+  },
+  "keywords": [
+    "avatar",
+    "png",
+    "apng",
+    "gif",
+    "sprite",
+    "deterministic"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}