@hyperframes/pag

PAG (Portable Animated Graphics) frame adapter for HyperFrames.

Conforms to the FrameAdapter contract from @hyperframes/core — supports arbitrary seek order, idempotent seeks, no wall-clock dependencies, no render-time network fetches.

Installation

npm install @hyperframes/pag

Requires @hyperframes/core as a peer dependency.

Usage

import { createPAGFrameAdapter } from "@hyperframes/pag";
import type { FrameAdapterContext } from "@hyperframes/core";

const response = await fetch("/animation.pag");
const pagData = await response.arrayBuffer();

const adapter = createPAGFrameAdapter({
  id: "my-animation",
  pagData,
});

const ctx: FrameAdapterContext = {
  compositionId: "my-animation",
  fps: 30,
  width: 1920,
  height: 1080,
};

await adapter.init(ctx);

console.log(adapter.getDurationFrames()); // total frame count

await adapter.seekFrame(42); // seek to frame 42
await adapter.seekFrame(0);  // first frame
await adapter.seekFrame(adapter.getDurationFrames() - 1); // last frame

await adapter.destroy(); // cleanup

API

createPAGFrameAdapter(options)

| Option | Type | Description | |---|---|---| | id | string | Stable identifier for this adapter instance | | pagData | ArrayBuffer | Pre-loaded .pag file contents (no render-time fetches) | | createCanvas | (w, h) => OffscreenCanvas \| HTMLCanvasElement | Optional canvas factory; defaults to new OffscreenCanvas(w, h) |

FrameAdapter methods

| Method | Description | |---|---| | init(ctx) | Initialize PAG engine, load file, create view. Idempotent. | | getDurationFrames() | Return total frame count | | seekFrame(frame) | Seek to a specific frame and render. Arbitrary seek order is supported. | | destroy() | Release PAG view and WASM module reference |

Frame calculation

totalFrames = ceil(duration_microseconds × frameRate / 1_000_000)
progress = frame / max(1, totalFrames - 1)

The host normalizes frame index via clamp(Math.floor(frame), 0, durationFrames) before passing to the adapter.

License

MIT