@rin-ts/sticker 0.2.0 → 0.2.1

package/README.md

@@ -1,84 +1,47 @@
 # @rin-ts/sticker
 
-`@rin-ts/sticker` converts media into WhatsApp-compatible WebP stickers for
-Rin. It keeps codec and pixel work in a persistent native C++ worker, while
-the Bun/TypeScript API manages requests and returns the finished WebP bytes.
+[![npm](https://img.shields.io/npm/v/%40rin-ts%2Fsticker?logo=npm)](https://www.npmjs.com/package/@rin-ts/sticker)
+[![CI](https://img.shields.io/github/actions/workflow/status/rin-ts/sticker/ci.yml?branch=main&label=CI)](https://github.com/rin-ts/sticker/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/%40rin-ts%2Fsticker)](LICENSE)
 
-The design is intended for fast, predictable server-side processing: requests
-are serialized per worker, source and output sizes are bounded, and a worker
-that times out or returns an invalid response is replaced before later work is
-accepted.
+Native WhatsApp WebP sticker conversion for Bun and TypeScript. Media decoding,
+pixel processing, and WebP encoding run in a persistent C++ worker; the
+TypeScript API sends bytes and returns validated sticker bytes.
 
-## Supported media
+## Highlights
 
-- PNG, JPEG, static WebP, animated WebP, and videos decoded by FFmpeg
-  (including MP4, MOV, WebM, MKV, and AVI)
-- Transparency, alpha trimming, proportional 512 × 512 sizing, and optional
-  alpha-aware outlines
-- Static and animated WhatsApp-compatible WebP output
-
-GIF, APNG, and Lottie/Telegram `.tgs` remain rejected. Videos are decoded
-directly from the supplied bytes; audio streams are ignored.
+- PNG, JPEG, static WebP, animated WebP, and FFmpeg-decoded video input
+- 512 × 512 static or animated WebP output validated against conservative
+  WhatsApp sticker limits
+- Alpha trimming, proportional sizing, and alpha-aware outlines
+- Fast high-quality lossy output by default, with an opt-in lossless static attempt
+- Persistent workers, per-request deadlines, bounded input, and automatic
+  worker replacement after a transport failure or timeout
 
 ## Install
 
-Published packages include a prebuilt worker for Linux x64 and Linux ARM64.
-They are available from the public npm registry, so no registry configuration
-or authentication is needed.
-
 ```bash
 bun add @rin-ts/sticker
 ```
 
-The optional platform worker is selected automatically. Set `workerPath` only
-when you supply a custom worker binary.
-
-## Publishing
-
-Maintain a matching `v<version>` Git tag and package versions, then a
-maintainer runs the **Publish packages** workflow from GitHub Actions with that
-tag and the intended npm distribution tag. The workflow publishes the Linux
-packages before the main package and safely skips versions already on npm.
-GitHub requires repository write access to start this manual workflow.
-
-Before the first release, configure an npm trusted publisher for each package:
-`@rin-ts/sticker`, `@rin-ts/sticker-linux-x64-gnu`, and
-`@rin-ts/sticker-linux-arm64-gnu`. Use GitHub organization `rin-ts`,
-repository `sticker`, workflow filename `release.yml`, and allow direct
-`npm publish`. This uses GitHub OIDC credentials rather than a stored npm
-token.
-
-## Build from source
-
-The native build requires Bun, CMake 3.20+, a C++20 compiler, `pkg-config`,
-and development packages for libpng, libjpeg, libwebp, libwebpmux,
-libwebpdemux, libavformat, libavcodec, libavutil, and libswscale. On Void,
-install these FFmpeg headers with `sudo xbps-install -S ffmpeg6-devel`.
-
-```bash
-bun install
-bun run build:native
-```
+Prebuilt workers are selected automatically on Linux x64 and Linux ARM64.
+Pass `workerPath` only when using a custom native worker executable.
+Keep a custom worker on the same package version as its TypeScript wrapper. A
+newer wrapper can send ordinary requests to an older worker, but that worker
+keeps its older encoding default; `preferLossless: true` is rejected by an
+older worker.
 
-This produces `build/native/bin/sticker_worker`.
+## Quick start
 
-## Usage
-
-Create one worker when the application starts, then reuse it for every sticker
-request. Supply already-bounded media bytes; the worker accepts at most 16 MiB
-per source asset.
+Create a worker once during application startup and reuse it for requests.
 
 ```ts
 import { createNativeStickerWorker } from "@rin-ts/sticker";
 
-const stickerWorker = createNativeStickerWorker({
-  // workerPath: "/opt/rin/sticker_worker",
-  timeoutMs: 15_000,
-});
-
+const worker = createNativeStickerWorker({ timeoutMs: 15_000 });
 const source = await Bun.file("./photo.png").arrayBuffer();
 
-const sticker = await stickerWorker.transcode(source, {
+const sticker = await worker.transcode(source, {
   trim: true,
   alphaThreshold: 4,
   outline: {
@@ -87,34 +50,139 @@ const sticker = await stickerWorker.transcode(source, {
   },
 });
 
-// For a Zapo/Rin handler:
 await context.reply({ type: "sticker", media: sticker.data });
+await worker.close();
+```
+
+`transcode()` resolves to:
+
+| Field | Description |
+| --- | --- |
+| `data` | Validated WebP sticker bytes |
+| `width`, `height` | Always `512` on success |
+| `frameCount`, `durationMs` | Animation metadata; static stickers have one frame and zero duration |
+| `isAnimated` | Whether the output contains multiple frames |
+
+## Input support
+
+| Input | Result |
+| --- | --- |
+| PNG, JPEG, static WebP | Static WebP sticker |
+| Animated WebP | Animated WebP sticker |
+| FFmpeg-supported video such as MP4, MOV, WebM, MKV, and AVI | Animated WebP sticker; audio is ignored |
+| GIF, APNG, Lottie/Telegram `.tgs` | Rejected |
 
-// During application shutdown:
-await stickerWorker.close();
+The worker receives bytes only; it is not a file-path CLI or an HTTP service.
+
+## API
+
+```ts
+const worker = createNativeStickerWorker({
+  workerPath: "/opt/rin/sticker_worker", // optional
+  workerArgs: [],                        // optional
+  timeoutMs: 30_000,                     // optional
+});
 ```
 
-`transcode()` returns `data` (the WebP bytes), `width`, `height`,
-`frameCount`, `durationMs`, and `isAnimated`.
+`worker.transcode(source, options)` accepts an `ArrayBuffer` or any typed-array
+view. `options` are:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `trim` | `true` | Remove fully transparent outer rows and columns |
+| `alphaThreshold` | `0` | Alpha value treated as transparent while trimming |
+| `outline.width` | `0` | Outline radius, from 0 through 64 pixels |
+| `outline.color` | opaque white | `{ red, green, blue, alpha? }`, each channel 0 through 255 |
+| `preferLossless` | `false` | Attempt lossless static WebP before lossy fallback; it still falls back when output exceeds 100 KiB |
+| `timeoutMs` | worker default (30,000 ms) | Deadline for writing, conversion, and reading the response |
+
+Calls to one worker are intentionally serialized. Use a finite pool of workers
+when parallel conversion is required. `close()` stops new work, drains already
+accepted work, and terminates the child process.
+
+## Limits and production behavior
 
-## Output and operational limits
+- Source assets are limited to 16 MiB.
+- Output is always 512 × 512 WebP.
+- Static output is limited to 100 KiB.
+- Animated output is limited to 500 KiB, 10 seconds, and requires multiple
+  frames with delays of at least 8 ms.
 
-Successful output is validated as 512 × 512 WebP. Static stickers are capped
-at 100 KiB; animated stickers are capped at 500 KiB, must contain more than
-one frame, use frame delays of at least 8 ms, and last no more than 10 seconds.
-These are conservative WhatsApp sticker-pack compatibility targets.
+The worker is discarded after a timeout, malformed protocol response, or
+transport failure; the next queued call starts a clean process. Still enforce
+download limits before calling this package, set an appropriate worker-pool
+size, and apply OS-level CPU and memory limits in production.
 
-The worker is an isolated stdin/stdout subprocess, not a file-path CLI or an
-HTTP server. It accepts bytes and rendering options only. For production,
-continue to enforce download limits in the application, use finite worker
-pools, and run workers with appropriate OS-level CPU and memory limits.
+## Benchmarking
 
-For development:
+Run the repeatable end-to-end suite:
 
 ```bash
-bun run test:native
+bun run benchmark
 ```
 
+It builds the native worker, generates deterministic full-size media fixtures
+locally, then reports cold latency (worker spawn plus first conversion) and
+warm latency (a reused worker). File I/O is excluded from warm measurements.
+The default fixtures cover a 1280 × 854 image as PNG, JPEG, and static WebP; a
+1024 × 1024 transparent graphic; a three-frame animated WebP; and a
+three-frame 640 × 360 MP4. They are real encoded media files, not 1 × 1 test
+pixels, and no fixture is downloaded.
+
+Use your own media to measure the inputs your application handles:
+
+```bash
+bun run build:native
+# Compare the fast default and lossless preference using the same source:
+bun run benchmarks/benchmark.ts --iterations 10 ./artwork.webp
+bun run benchmarks/benchmark.ts --iterations 10 --prefer-lossless ./artwork.webp
+```
+
+The report includes source and output size, cold latency, warm median and p95,
+and warm throughput. Performance varies with codec library versions, CPU,
+source dimensions, frame count, transparency, and how often an output must be
+re-encoded to meet its byte limit; compare results on the deployment hardware.
+Static output uses the high-quality lossy path by default for predictable
+latency. Set `preferLossless: true` when lower latency is not important and a
+lossless attempt is worthwhile; output still falls back to lossy above 100 KiB.
+
+## Development
+
+### Build from source
+
+The native build requires Bun, CMake 3.20+, a C++20 compiler, `pkg-config`,
+and development packages for libpng, libjpeg, libwebp, libwebpmux,
+libwebpdemux, libavformat, libavcodec, libavutil, and libswscale. On Void,
+install FFmpeg headers with:
+
+```bash
+sudo xbps-install -S ffmpeg6-devel
+```
+
+Then build:
+
+```bash
+bun install
+bun run build:native
+```
+
+The worker is written to `build/native/bin/sticker_worker`.
+
+### Test
+
+```bash
+bun run test
+```
+
+## Publishing
+
+Maintain matching package versions and a `v<version>` tag, then run the
+repository’s **Publish packages** GitHub Actions workflow with the intended npm
+distribution tag. It publishes the platform packages before the main package
+and skips package versions already present on npm. Configure npm trusted
+publishers for the main and Linux platform packages after the initial release;
+the workflow file is [`release.yml`](.github/workflows/release.yml).
+
 ## License
 
 GPL-3.0-only. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rin-ts/sticker",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Native C++ WhatsApp WebP sticker worker for Rin.",
   "license": "GPL-3.0-only",
   "type": "module",
@@ -23,6 +23,8 @@
   },
   "scripts": {
     "build:native": "bun run scripts/build-native.ts",
+    "benchmark:fixtures": "bun run build:native && bun run benchmarks/generate-fixtures.ts",
+    "benchmark": "bun run benchmark:fixtures && bun run benchmarks/benchmark.ts",
     "test": "bun run typecheck && bun run test:native",
     "test:native": "bun run build:native && ctest --test-dir build/native --output-on-failure && bun test ./tests/native_bridge.test.ts",
     "typecheck": "bun check"
@@ -34,7 +36,7 @@
     "typescript": "^7"
   },
   "optionalDependencies": {
-    "@rin-ts/sticker-linux-arm64-gnu": "0.2.0",
-    "@rin-ts/sticker-linux-x64-gnu": "0.2.0"
+    "@rin-ts/sticker-linux-arm64-gnu": "0.2.1",
+    "@rin-ts/sticker-linux-x64-gnu": "0.2.1"
   }
 }

package/src/native/sticker_pipeline.cpp

@@ -1379,11 +1379,14 @@ private:
     }
   } else {
     config.lossless = 0;
-    config.method = 6;
+    // The default static path favors bounded latency. Transparent artwork can
+    // spend seconds optimizing a lossless-quality alpha plane at method 6.
+    // Method 4 keeps alpha edges exact without exhaustive analysis.
+    config.method = 4;
     config.alpha_quality = 100;
     config.thread_level = 1;
     config.exact = 0;
-    config.use_sharp_yuv = 1;
+    config.use_sharp_yuv = 0;
   }
   if (WebPValidateConfig(&config) == 0) {
     fail(ErrorCode::kInternal, "invalid WebP encoder configuration");
@@ -1452,10 +1455,14 @@ encode_static(const Image &image, const int quality, const bool lossless) {
   };
 }
 
-[[nodiscard]] StickerResult encode_static_limited(const Image &image) {
-  std::vector<Byte> encoded = encode_static(image, 100, true);
-  if (encoded.size() <= kMaximumStaticStickerBytes) {
-    return validate_output(std::move(encoded), false);
+[[nodiscard]] StickerResult encode_static_limited(const Image &image,
+                                                  const bool prefer_lossless) {
+  std::vector<Byte> encoded;
+  if (prefer_lossless) {
+    encoded = encode_static(image, 100, true);
+    if (encoded.size() <= kMaximumStaticStickerBytes) {
+      return validate_output(std::move(encoded), false);
+    }
   }
 
   constexpr std::array<int, 9U> kQualityCandidates = {90, 80, 70, 60, 50,
@@ -1804,7 +1811,7 @@ encode_video_animation_limited(const std::span<const Byte> source,
   Image rendered =
       render_frame(decoded.rgba, decoded.width, decoded.height, geometry);
   apply_outline(rendered, options);
-  return encode_static_limited(rendered);
+  return encode_static_limited(rendered, options.prefer_lossless);
 }
 
 [[nodiscard]] StickerResult
@@ -1812,8 +1819,10 @@ transcode_animated_webp(const std::span<const Byte> source,
                         const WebpInfo &info, const TranscodeOptions &options) {
   const AnimationPlan plan = plan_animation(source, info, options);
   if (plan.selections.size() == 1U) {
-    return encode_static_limited(render_animation_frame(
-        source, info, plan, plan.selections.front().source_index, options));
+    return encode_static_limited(
+        render_animation_frame(source, info, plan,
+                               plan.selections.front().source_index, options),
+        options.prefer_lossless);
   }
   return encode_animation_limited(source, info, plan, options);
 }
@@ -1824,8 +1833,10 @@ transcode_animated_video(const std::span<const Byte> source,
                          const TranscodeOptions &options) {
   const AnimationPlan plan = plan_video_animation(source, info, options);
   if (plan.selections.size() == 1U) {
-    return encode_static_limited(render_video_animation_frame(
-        source, info, plan, plan.selections.front().source_index, options));
+    return encode_static_limited(
+        render_video_animation_frame(
+            source, info, plan, plan.selections.front().source_index, options),
+        options.prefer_lossless);
   }
   return encode_video_animation_limited(source, info, plan, options);
 }

package/src/native/sticker_pipeline.hpp

@@ -40,6 +40,7 @@ struct TranscodeOptions {
   std::uint8_t alpha_threshold = 0U;
   std::uint8_t outline_width = 0U;
   RgbaColor outline_color{};
+  bool prefer_lossless = false;
 };
 
 struct StickerResult {

package/src/native/sticker_worker.cpp

@@ -22,7 +22,10 @@ constexpr std::array<Byte, 4U> kResponseMagic = {'S', 'T', 'R', '1'};
 constexpr Byte kProtocolVersion = 1U;
 constexpr Byte kCommandTranscode = 1U;
 constexpr Byte kTrimFlag = 1U << 0U;
-constexpr Byte kUnsupportedRequestFlags = static_cast<Byte>(~kTrimFlag);
+constexpr Byte kPreferLosslessFlag = 1U << 1U;
+constexpr Byte kSupportedRequestFlags = kTrimFlag | kPreferLosslessFlag;
+constexpr Byte kUnsupportedRequestFlags =
+    static_cast<Byte>(~kSupportedRequestFlags);
 constexpr std::size_t kRequestHeaderSize = 18U;
 constexpr std::size_t kResponseHeaderSize = 26U;
 constexpr std::size_t kMaximumFrameBytes =
@@ -166,6 +169,7 @@ void write_u32(
                       .blue = frame[12U],
                       .alpha = frame[13U],
                   },
+              .prefer_lossless = (flags & kPreferLosslessFlag) != 0,
           },
       .input = std::vector<Byte>(
           frame.begin() + static_cast<std::ptrdiff_t>(kRequestHeaderSize),

package/src/native.ts

@@ -8,6 +8,7 @@ const RESPONSE_MAGIC = "STR1";
 const PROTOCOL_VERSION = 1;
 const COMMAND_TRANSCODE = 1;
 const TRIM_FLAG = 1 << 0;
+const PREFER_LOSSLESS_FLAG = 1 << 1;
 const REQUEST_HEADER_BYTES = 18;
 const RESPONSE_HEADER_BYTES = 26;
 const FRAME_LENGTH_BYTES = 4;
@@ -21,6 +22,15 @@ const textDecoder = new TextDecoder("utf-8", { fatal: true });
 
 type WorkerProcess = Bun.Subprocess<"pipe", "pipe", "ignore">;
 
+type Uint8ArrayReadResult =
+  | { readonly done: true; readonly value?: Uint8Array }
+  | { readonly done: false; readonly value: Uint8Array };
+
+interface Uint8ArrayReader {
+  read(): Promise<Uint8ArrayReadResult>;
+  cancel(reason?: unknown): Promise<void>;
+}
+
 interface WorkerSession {
   readonly process: WorkerProcess;
   readonly stdin: WorkerProcess["stdin"];
@@ -53,6 +63,12 @@ export interface NativeStickerTranscodeOptions {
   readonly alphaThreshold?: number;
   /** Optional outline rendered behind the source image. */
   readonly outline?: OutlineOptions;
+  /**
+   * Attempt lossless WebP output before lossy encoding for static results.
+   * Defaults to false because it can take substantially longer for transparent
+   * artwork and still falls back to lossy output when it exceeds the size limit.
+   */
+  readonly preferLossless?: boolean;
   /**
    * Per-request deadline, including writes and reading the complete response.
    * A timed-out worker is killed and a fresh worker is used for a later call.
@@ -126,7 +142,7 @@ class WorkerProtocolError extends NativeStickerWorkerTransportError {
 }
 
 class BufferedReader {
-  readonly #reader: ReadableStreamDefaultReader<Uint8Array>;
+  readonly #reader: Uint8ArrayReader;
   #current: Uint8Array | undefined;
   #offset = 0;
 
@@ -249,6 +265,12 @@ function encodeRequest(
   if (options.trim !== undefined && typeof options.trim !== "boolean") {
     throw new TypeError("trim must be a boolean.");
   }
+  if (
+    options.preferLossless !== undefined
+    && typeof options.preferLossless !== "boolean"
+  ) {
+    throw new TypeError("preferLossless must be a boolean.");
+  }
 
   const input = sourceBytes(source);
   if (input.byteLength > MAXIMUM_SOURCE_BYTES) {
@@ -277,7 +299,9 @@ function encodeRequest(
   frame[header + 3] = REQUEST_MAGIC.charCodeAt(3);
   frame[header + 4] = PROTOCOL_VERSION;
   frame[header + 5] = COMMAND_TRANSCODE;
-  frame[header + 6] = (options.trim ?? true) ? TRIM_FLAG : 0;
+  frame[header + 6] =
+    ((options.trim ?? true) ? TRIM_FLAG : 0)
+    | ((options.preferLossless ?? false) ? PREFER_LOSSLESS_FLAG : 0);
   frame[header + 7] = 0;
   frame[header + 8] = alphaThreshold;
   frame[header + 9] = outlineWidth;