@jackuait/blok 0.16.1 → 0.18.0

package/src/tools/audio/uploader.ts

@@ -0,0 +1,76 @@
+import type { AudioConfig } from '../../../types/tools/audio';
+import { resolveMaxSize } from '../../components/utils/max-size';
+import { matchesMime } from '../../components/utils/mime-match';
+import { DEFAULT_MAX_SIZE, DEFAULT_MIME_TYPES } from './constants';
+
+export interface UploadResult {
+  url: string;
+  fileName?: string;
+}
+
+export interface UploadOptions {
+  onProgress?: (percent: number) => void;
+}
+
+export class AudioUploadError extends Error {
+  public readonly detail?: string;
+
+  constructor(public readonly code: string, detail?: string) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = 'AudioUploadError';
+    this.detail = detail;
+  }
+}
+
+function parseUrl(raw: string): URL | null {
+  try {
+    return new URL(raw);
+  } catch {
+    return null;
+  }
+}
+
+export class Uploader {
+  constructor(private readonly config: AudioConfig) {}
+
+  public async handleUrl(raw: string, options: UploadOptions = {}): Promise<UploadResult> {
+    this.validateUrl(raw);
+    if (this.config.uploader?.uploadByUrl) {
+      return this.config.uploader.uploadByUrl(raw, { onProgress: options.onProgress });
+    }
+
+    return { url: raw };
+  }
+
+  public async handleFile(file: File, options: UploadOptions = {}): Promise<UploadResult> {
+    this.validateFile(file);
+    if (this.config.uploader?.uploadByFile) {
+      return this.config.uploader.uploadByFile(file, { onProgress: options.onProgress });
+    }
+
+    return { url: URL.createObjectURL(file), fileName: file.name };
+  }
+
+  private validateUrl(raw: string): void {
+    const parsed = parseUrl(raw);
+
+    if (!parsed) {
+      throw new AudioUploadError('INVALID_URL', raw);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new AudioUploadError('INVALID_URL', parsed.protocol);
+    }
+  }
+
+  private validateFile(file: File): void {
+    const types = this.config.types ?? [...DEFAULT_MIME_TYPES];
+    const maxSize = resolveMaxSize(this.config.maxSize, file.type, DEFAULT_MAX_SIZE);
+
+    if (file.type && !matchesMime(file.type, types)) {
+      throw new AudioUploadError('UNSUPPORTED_TYPE', file.type);
+    }
+    if (file.size > maxSize) {
+      throw new AudioUploadError('FILE_TOO_LARGE', `${file.size} > ${maxSize}`);
+    }
+  }
+}

package/src/tools/audio/waveform.ts

@@ -0,0 +1,171 @@
+import { WAVEFORM_BUCKETS } from './constants';
+
+/**
+ * Reduce raw mono samples to `buckets` peak values normalized to 0..1.
+ * Each bucket holds the max absolute amplitude across its slice; the whole
+ * array is then divided by the global max so the loudest bucket is 1.
+ */
+
+function bucketPeak(channel: Float32Array, start: number, end: number): number {
+  return channel.slice(start, end).reduce((max, v) => Math.max(max, Math.abs(v)), 0);
+}
+
+export function computePeaks(channel: Float32Array, buckets = WAVEFORM_BUCKETS): number[] {
+  if (channel.length === 0) return new Array<number>(buckets).fill(0);
+
+  const step = channel.length / buckets;
+  const out = Array.from({ length: buckets }, (_, b) => {
+    const start = Math.floor(b * step);
+    const end = Math.min(channel.length, Math.floor((b + 1) * step));
+    return bucketPeak(channel, start, end);
+  });
+
+  const globalMax = Math.max(0, ...out);
+  if (globalMax <= 0) return out;
+  return out.map((v) => v / globalMax);
+}
+
+interface ChannelSource {
+  numberOfChannels: number;
+  length: number;
+  getChannelData(ch: number): Float32Array;
+}
+
+/** Average all channels into one mono track, then reduce to peaks. */
+export function peaksFromAudioBuffer(buffer: ChannelSource, buckets = WAVEFORM_BUCKETS): number[] {
+  const { numberOfChannels, length } = buffer;
+  if (numberOfChannels <= 1) return computePeaks(buffer.getChannelData(0), buckets);
+
+  const mono = new Float32Array(length);
+  Array.from({ length: numberOfChannels }, (_, ch) => buffer.getChannelData(ch)).forEach((data) => {
+    data.forEach((v, i) => { mono[i] += v / numberOfChannels; });
+  });
+  return computePeaks(mono, buckets);
+}
+
+export function ratioFromPointer(clientX: number, rect: { left: number; width: number }): number {
+  if (rect.width <= 0) return 0;
+  const r = (clientX - rect.left) / rect.width;
+  return Math.min(1, Math.max(0, r));
+}
+
+type AudioContextCtor = typeof AudioContext;
+
+function getAudioContextCtor(): AudioContextCtor | null {
+  const w = globalThis as unknown as {
+    AudioContext?: AudioContextCtor;
+    webkitAudioContext?: AudioContextCtor;
+  };
+  return w.AudioContext ?? w.webkitAudioContext ?? null;
+}
+
+export interface DecodedAudio {
+  peaks: number[];
+  duration: number;
+}
+
+export async function decodePeaks(file: File): Promise<DecodedAudio | null> {
+  const Ctor = getAudioContextCtor();
+  if (!Ctor) return null;
+  try {
+    const ctx = new Ctor();
+    try {
+      const buffer = await ctx.decodeAudioData(await file.arrayBuffer());
+      return { peaks: peaksFromAudioBuffer(buffer), duration: buffer.duration };
+    } finally {
+      void ctx.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+export interface WaveformHandle {
+  destroy(): void;
+}
+
+export function attachWaveform(opts: {
+  mount: HTMLElement;
+  media: HTMLAudioElement;
+  peaks: number[];
+}): WaveformHandle {
+  const { mount, media, peaks } = opts;
+  const canvas = document.createElement('canvas');
+  canvas.setAttribute('data-role', 'audio-waveform-canvas');
+  canvas.className = 'blok-audio-waveform__canvas';
+  mount.appendChild(canvas);
+
+  const draw = (): void => {
+    const rect = canvas.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return;
+    const dpr = globalThis.devicePixelRatio || 1;
+    canvas.width = Math.round(rect.width * dpr);
+    canvas.height = Math.round(rect.height * dpr);
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    ctx.scale(dpr, dpr);
+    const played = media.duration ? media.currentTime / media.duration : 0;
+    const slot = rect.width / peaks.length;
+    const gap = Math.min(2, slot * 0.34);
+    const barW = Math.max(1, slot - gap);
+    const radius = Math.min(barW / 2, 2);
+    const styles = getComputedStyle(canvas);
+    const playedColor = styles.getPropertyValue('--blok-audio-bar-played').trim() || '#222';
+    const baseColor = styles.getPropertyValue('--blok-audio-bar').trim() || '#ccc';
+    peaks.forEach((peak, i) => {
+      const h = Math.max(2, peak * rect.height * 0.92);
+      const x = i * slot;
+      const y = (rect.height - h) / 2;
+      ctx.fillStyle = i / peaks.length < played ? playedColor : baseColor;
+      if (typeof ctx.roundRect === 'function') {
+        ctx.beginPath();
+        ctx.roundRect(x, y, barW, h, radius);
+        ctx.fill();
+      } else {
+        ctx.fillRect(x, y, barW, h);
+      }
+    });
+  };
+
+  const rafState = { id: 0 };
+  const onTime = (): void => {
+    if (rafState.id) return;
+    rafState.id = requestAnimationFrame(() => {
+      rafState.id = 0;
+      mount.style.setProperty(
+        '--blok-audio-seek-pct',
+        String(media.duration ? (media.currentTime / media.duration) * 100 : 0),
+      );
+      draw();
+    });
+  };
+
+  const seek = (clientX: number): void => {
+    if (!media.duration) return;
+    media.currentTime = ratioFromPointer(clientX, canvas.getBoundingClientRect()) * media.duration;
+    draw();
+  };
+  const drag = { active: false };
+  const onDown = (e: PointerEvent): void => { drag.active = true; seek(e.clientX); };
+  const onMove = (e: PointerEvent): void => { if (drag.active) seek(e.clientX); };
+  const onUp = (): void => { drag.active = false; };
+
+  canvas.addEventListener('pointerdown', onDown);
+  globalThis.addEventListener('pointermove', onMove);
+  globalThis.addEventListener('pointerup', onUp);
+  media.addEventListener('timeupdate', onTime);
+  media.addEventListener('loadedmetadata', draw);
+  draw();
+
+  return {
+    destroy(): void {
+      if (rafState.id) cancelAnimationFrame(rafState.id);
+      canvas.removeEventListener('pointerdown', onDown);
+      globalThis.removeEventListener('pointermove', onMove);
+      globalThis.removeEventListener('pointerup', onUp);
+      media.removeEventListener('timeupdate', onTime);
+      media.removeEventListener('loadedmetadata', draw);
+      canvas.remove();
+    },
+  };
+}

package/src/tools/file/constants.ts

@@ -1,8 +1,7 @@
-/** Non-image MIME prefixes claimed for paste/drop routing. Image files stay with the Image tool. */
+/** Non-image MIME prefixes claimed for paste/drop routing. Image files stay with the Image tool. Audio files route to the Audio tool. */
 export const PASTE_MIME_TYPES = [
   'application/*',
   'text/*',
-  'audio/*',
   'video/*',
   'font/*',
   'model/*',
@@ -13,7 +12,10 @@ export const PASTE_EXTENSIONS = [
   'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx',
   'zip', 'rar', '7z', 'gz', 'tar',
   'csv', 'txt', 'rtf', 'md', 'json',
-  'mp3', 'wav', 'ogg', 'mp4', 'mov', 'avi', 'mkv',
+  'mp4', 'mov', 'avi', 'mkv',
 ] as const;
 
+/** Default upload ceiling (bytes) when the consumer does not configure `maxSize`. */
+export const DEFAULT_MAX_SIZE = 30 * 1024 * 1024; // 30 MiB
+
 export const DEFAULT_CAPTION_PLACEHOLDER = 'Write a caption…';

package/src/tools/file/index.ts

@@ -11,12 +11,15 @@ import type {
 import type { MenuConfig } from '../../../types/tools/menu-config';
 import type { FileConfig, FileData, FileUploadResult } from '../../../types/tools/file';
 import type { ImageData } from '../../../types/tools/image';
+import type { VideoData } from '../../../types/tools/video';
 import { IconCaption, IconCopy, IconDownload, IconFile, IconReplace } from '../../components/icons';
 import { DEFAULT_CAPTION_PLACEHOLDER, PASTE_EXTENSIONS, PASTE_MIME_TYPES } from './constants';
 import { renderEmptyState, type EmptyStateElement } from './empty-state';
 import { renderUploadingState, type UploadingStateElement } from './uploading-state';
 import { renderCaptionRow, renderFileCard } from './ui';
 import { Uploader } from './uploader';
+import { FileToolError } from './errors';
+import { uploadErrorMessage } from '../../components/utils/upload-error-message';
 import { safeHttpHref } from './url';
 import { isPreviewable } from './preview';
 import { openFilePreview } from './preview-modal';
@@ -26,6 +29,9 @@ type ToolState = 'EMPTY' | 'LOADING' | 'RENDERED' | 'ERROR';
 /** Image filenames/URLs that should auto-convert the File block into an Image. */
 const IMAGE_EXTENSION_RE = /\.(png|jpe?g|gif|webp|svg)(?:[?#]|$)/i;
 
+/** Video filenames/URLs that should auto-convert the File block into a Video. */
+const VIDEO_EXTENSION_RE = /\.(mp4|webm|ogg|mov|m4v)(?:[?#]|$)/i;
+
 export class FileTool implements BlockTool {
   private readonly api: API;
   private readonly block: BlockAPI;
@@ -37,9 +43,12 @@ export class FileTool implements BlockTool {
   private state: ToolState;
   private uploadingEl: UploadingStateElement | null = null;
   private lastFileName: string | null = null;
+  private errorMessage: string | null = null;
   private previewTeardown: (() => void) | null = null;
   /** When the pending upload is an image, the result converts to an Image block. */
   private pendingImageConversion = false;
+  /** When the pending upload is a video, the result converts to a Video block. */
+  private pendingVideoConversion = false;
 
   constructor(options: BlockToolConstructorOptions<FileData, FileConfig>) {
     this.api = options.api;
@@ -153,26 +162,29 @@ export class FileTool implements BlockTool {
   private startUpload(file: File): void {
     this.lastFileName = file.name;
     this.pendingImageConversion = file.type.startsWith('image/') || IMAGE_EXTENSION_RE.test(file.name);
+    this.pendingVideoConversion = file.type.startsWith('video/') || VIDEO_EXTENSION_RE.test(file.name);
     this.state = 'LOADING';
     this.renderState();
     void this.uploader
       .handleFile(file, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
       .then((result) => this.applyResult(result))
-      .catch(() => this.applyError());
+      .catch((err) => this.applyError(err));
   }
 
   private startUrl(url: string): void {
     this.lastFileName = null;
     this.pendingImageConversion = IMAGE_EXTENSION_RE.test(url);
+    this.pendingVideoConversion = VIDEO_EXTENSION_RE.test(url);
     this.state = 'LOADING';
     this.renderState();
     void this.uploader
       .handleUrl(url, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
       .then((result) => this.applyResult(result))
-      .catch(() => this.applyError());
+      .catch((err) => this.applyError(err));
   }
 
   private applyResult(result: FileUploadResult): void {
+    this.errorMessage = null;
     this.data = {
       ...this.data,
       url: result.url,
@@ -180,6 +192,9 @@ export class FileTool implements BlockTool {
       size: result.size ?? this.data.size,
       mimeType: result.mimeType ?? this.data.mimeType,
     };
+    if (this.pendingVideoConversion && this.convertToVideo()) {
+      return;
+    }
     if (this.pendingImageConversion && this.convertToImage()) {
       return;
     }
@@ -207,7 +222,33 @@ export class FileTool implements BlockTool {
     return true;
   }
 
-  private applyError(): void {
+  /**
+   * Swap this File block for a Video block carrying the just-uploaded url.
+   * Mirrors {@link convertToImage}: File and Video declare no conversionConfig,
+   * so we replace in place. Returns false (keep the file card) when the block
+   * can no longer be located.
+   */
+  private convertToVideo(): boolean {
+    const index = this.api.blocks.getBlockIndex(this.block.id);
+    if (index === undefined) {
+      return false;
+    }
+    const videoData: VideoData = { url: this.data.url };
+    if (this.data.fileName !== undefined) videoData.fileName = this.data.fileName;
+    if (this.data.mimeType !== undefined) videoData.mimeType = this.data.mimeType;
+    if ((this.data.caption ?? '') !== '') videoData.caption = this.data.caption;
+    if (this.data.captionVisible !== undefined) videoData.captionVisible = this.data.captionVisible;
+    this.api.blocks.insert('video', videoData, {}, index, false, true);
+    return true;
+  }
+
+  private applyError(err?: unknown): void {
+    this.errorMessage = err instanceof FileToolError
+      ? uploadErrorMessage(err, (key) => this.api.i18n.t(key), {
+        tooLarge: 'tools.file.errorFileTooLarge',
+        generic: 'tools.file.errorUploadFailed',
+      })
+      : null;
     this.state = 'ERROR';
     this.renderState();
   }
@@ -331,7 +372,7 @@ export class FileTool implements BlockTool {
     wrap.setAttribute('data-role', 'file-error');
 
     const message = document.createElement('span');
-    message.textContent = i18n.t('tools.file.errorUploadFailed');
+    message.textContent = this.errorMessage ?? i18n.t('tools.file.errorUploadFailed');
 
     const retry = document.createElement('button');
     retry.type = 'button';

package/src/tools/file/uploader.ts

@@ -1,4 +1,6 @@
 import type { FileConfig, FileUploadResult } from '../../../types/tools/file';
+import { resolveMaxSize } from '../../components/utils/max-size';
+import { DEFAULT_MAX_SIZE } from './constants';
 import { FileToolError } from './errors';
 
 export interface UploadOptions {
@@ -120,12 +122,13 @@ export class Uploader {
   }
 
   private validateFile(file: File): void {
-    const { types, maxSize } = this.config;
+    const { types } = this.config;
+    const maxSize = resolveMaxSize(this.config.maxSize, file.type, DEFAULT_MAX_SIZE);
 
     if (types !== undefined && !types.includes(file.type)) {
       throw new FileToolError('UNSUPPORTED_TYPE', file.type || 'unknown');
     }
-    if (maxSize !== undefined && file.size > maxSize) {
+    if (file.size > maxSize) {
       throw new FileToolError('FILE_TOO_LARGE', `${file.size} > ${maxSize}`);
     }
   }

package/src/tools/image/constants.ts

@@ -1,12 +1,7 @@
-export const DEFAULT_MIME_TYPES = [
-  'image/jpeg',
-  'image/png',
-  'image/gif',
-  'image/webp',
-  'image/svg+xml',
-] as const;
+// Accept any image type by default; consumers restrict via the `types` config.
+export const DEFAULT_MIME_TYPES = ['image/*'] as const;
 
-export const DEFAULT_MAX_SIZE = 10 * 1024 * 1024; // 10 MiB
+export const DEFAULT_MAX_SIZE = 30 * 1024 * 1024; // 30 MiB
 
 export const DEFAULT_CAPTION_PLACEHOLDER = 'Write a caption…';
 

package/src/tools/image/converted-uploader.ts

@@ -0,0 +1,30 @@
+import type { API } from '../../../types';
+import type { ImageConfig } from '../../../types/tools/image';
+
+export type ConvertedUploadFn = (
+  file: File,
+  ctx?: { onProgress?: (percent: number) => void },
+) => Promise<{ url: string; fileName?: string }>;
+
+interface UploaderHolder { uploader?: { uploadByFile?: ConvertedUploadFn } }
+
+function asUploaderHolder(value: unknown): UploaderHolder | undefined {
+  return typeof value === 'object' && value !== null ? (value as UploaderHolder) : undefined;
+}
+
+/**
+ * Resolve which `uploadByFile` to use for a converted WebM file:
+ * the video tool's uploader (if registered under the `video` key), else the
+ * image tool's own uploader, else undefined (caller uses a blob URL).
+ */
+export function resolveConvertedUploader(
+  api: API,
+  imageConfig: ImageConfig,
+): ConvertedUploadFn | undefined {
+  const videoEntry = asUploaderHolder(api.tools.getToolsConfig().tools?.video);
+  // Tool settings carry the config under `.config`; support a flat shape too.
+  const videoConfig = asUploaderHolder((videoEntry as { config?: unknown })?.config) ?? videoEntry;
+  const videoUpload = videoConfig?.uploader?.uploadByFile;
+
+  return videoUpload ?? imageConfig.uploader?.uploadByFile;
+}

package/src/tools/image/gif-to-webm.ts

@@ -0,0 +1,170 @@
+// Minimal structural types for the WebCodecs surface we use (avoids relying on
+// lib.dom types that may not be present in the project's TS target).
+interface DecodedFrame {
+  displayWidth: number;
+  displayHeight: number;
+  duration: number | null;
+  timestamp: number;
+  close(): void;
+}
+
+interface ImageDecoderLike {
+  tracks: { ready: Promise<void>; selectedTrack?: { frameCount: number } };
+  decode(opts: { frameIndex: number }): Promise<{ image: DecodedFrame; complete: boolean }>;
+  close(): void;
+}
+
+interface EncodedChunk { type: string; }
+
+interface VideoEncoderLike {
+  configure(config: Record<string, unknown>): void;
+  encode(frame: DecodedFrame, opts?: { keyFrame?: boolean }): void;
+  flush(): Promise<void>;
+  close(): void;
+}
+
+interface VideoEncoderCtor {
+  new (init: {
+    output: (chunk: EncodedChunk, meta: unknown) => void;
+    error: (err: unknown) => void;
+  }): VideoEncoderLike;
+  isConfigSupported(config: Record<string, unknown>): Promise<{ supported?: boolean }>;
+}
+
+const KEYFRAME_INTERVAL = 30;
+
+function hasWebCodecs(): boolean {
+  const g = globalThis as Record<string, unknown>;
+  return typeof g.ImageDecoder !== 'undefined' && typeof g.VideoEncoder !== 'undefined';
+}
+
+async function pickCodec(
+  Encoder: VideoEncoderCtor,
+  width: number,
+  height: number,
+): Promise<{ encoderCodec: string; muxerCodec: 'V_VP9' | 'V_VP8' } | null> {
+  const candidates: Array<{ encoderCodec: string; muxerCodec: 'V_VP9' | 'V_VP8' }> = [
+    { encoderCodec: 'vp09.00.10.08', muxerCodec: 'V_VP9' },
+    { encoderCodec: 'vp8', muxerCodec: 'V_VP8' },
+  ];
+  for (const c of candidates) {
+    const probe = await Encoder.isConfigSupported({ codec: c.encoderCodec, width, height });
+    if (probe.supported) return c;
+  }
+  return null;
+}
+
+/**
+ * Convert an animated GIF (raw bytes) into a WebM Blob using WebCodecs.
+ * Returns null whenever the caller should keep the original GIF: WebCodecs
+ * unavailable, a static/single-frame GIF, an unsupported codec, or any error.
+ */
+export async function convertGifToWebm(
+  data: ArrayBuffer,
+  opts: { onProgress?: (percent: number) => void } = {},
+): Promise<Blob | null> {
+  if (!hasWebCodecs()) return null;
+
+  const g = globalThis as Record<string, unknown>;
+  const DecoderCtor = g.ImageDecoder as new (init: { data: ArrayBuffer; type: string }) => ImageDecoderLike;
+  const EncoderCtor = g.VideoEncoder as VideoEncoderCtor;
+
+  const resources: { decoder?: ImageDecoderLike; encoder?: VideoEncoderLike } = {};
+  const openFrames: DecodedFrame[] = [];
+
+  try {
+    const decoder = new DecoderCtor({ data, type: 'image/gif' });
+    resources.decoder = decoder;
+    await decoder.tracks.ready;
+    const frameCount = decoder.tracks.selectedTrack?.frameCount ?? 0;
+    if (frameCount <= 1) return null;
+
+    const first = await decoder.decode({ frameIndex: 0 });
+    openFrames.push(first.image);
+    const width = first.image.displayWidth;
+    const height = first.image.displayHeight;
+
+    const codec = await pickCodec(EncoderCtor, width, height);
+    if (!codec) return null;
+
+    const { Muxer, ArrayBufferTarget } = await import('webm-muxer');
+    const target = new ArrayBufferTarget();
+    const muxer = new Muxer({
+      target,
+      video: { codec: codec.muxerCodec, width, height },
+      firstTimestampBehavior: 'offset',
+    });
+
+    const encoder = new EncoderCtor({
+      output: (chunk, meta) => muxer.addVideoChunk(chunk as never, meta as never),
+      error: () => undefined,
+    });
+    resources.encoder = encoder;
+    encoder.configure({
+      codec: codec.encoderCodec,
+      width,
+      height,
+      bitrate: Math.max(200_000, width * height * 4),
+    });
+
+    const indices = Array.from({ length: frameCount }, (_unused, i) => i);
+    // Running timestamp held in a const cursor so each frame is re-stamped to be
+    // monotonic from the accumulated GIF delays (µs) without a mutable `let`.
+    const cursor = { timestamp: 0 };
+    for (const i of indices) {
+      const frame = await getFrame(i, first.image, decoder);
+      cursor.timestamp = encodeFrame(encoder, frame, i, cursor.timestamp);
+      collectFrame(openFrames, frame, i);
+      opts.onProgress?.(Math.round(((i + 1) / frameCount) * 100));
+    }
+
+    await encoder.flush();
+    muxer.finalize();
+    return new Blob([target.buffer], { type: 'video/webm' });
+  } catch {
+    return null;
+  } finally {
+    openFrames.forEach((f) => {
+      try { f.close(); } catch { /* already closed */ }
+    });
+    try { resources.encoder?.close(); } catch { /* noop */ }
+    try { resources.decoder?.close(); } catch { /* noop */ }
+  }
+}
+
+/**
+ * Resolve a decoded frame for the given index. Frame 0 reuses the already
+ * decoded first image; later frames are decoded on demand.
+ */
+async function getFrame(
+  index: number,
+  first: DecodedFrame,
+  decoder: ImageDecoderLike,
+): Promise<DecodedFrame> {
+  if (index === 0) return first;
+  return (await decoder.decode({ frameIndex: index })).image;
+}
+
+/**
+ * Encode one frame at the given timestamp and return the timestamp for the
+ * next frame (current + this frame's GIF delay, in µs).
+ */
+function encodeFrame(
+  encoder: VideoEncoderLike,
+  frame: DecodedFrame,
+  index: number,
+  timestamp: number,
+): number {
+  const stamped = frame as DecodedFrame & { timestamp: number };
+  stamped.timestamp = timestamp;
+  encoder.encode(frame, { keyFrame: index % KEYFRAME_INTERVAL === 0 });
+  return timestamp + (frame.duration ?? 100_000);
+}
+
+/**
+ * Track later frames so they can be closed in the finally block. Frame 0 is
+ * already tracked by the caller.
+ */
+function collectFrame(openFrames: DecodedFrame[], frame: DecodedFrame, index: number): void {
+  if (index !== 0) openFrames.push(frame);
+}