cursedbelt 5.76.0 → 5.78.0

package/src/react/media/gifEncode.spec.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  clampGifSection,
+  formatGifBytes,
+  formatGifTime,
+  gifFileName,
+  gifFrameTimes,
+  gifSectionAt,
+  gifSize,
+  MAX_GIF_SECONDS,
+  MIN_GIF_SECONDS,
+} from './gifClip.js';
+import { GifWriter, lzwEncode, quantizeFrame } from './gifEncode.js';
+
+/**
+ * A GIF decoder small enough to read here — the spec's independent half. It knows the format
+ * from the 89a spec, not from `gifEncode.ts`: a header, a loop block, and per frame a graphic
+ * control, a descriptor with a local table, and LZW sub-blocks.
+ */
+function decodeGif(bytes: Uint8Array) {
+  const text = (at: number, n: number) => String.fromCharCode(...bytes.subarray(at, at + n));
+  const u16 = (at: number) => (bytes[at] as number) | ((bytes[at + 1] as number) << 8);
+  expect(text(0, 6)).toBe('GIF89a');
+  const width = u16(6);
+  const height = u16(8);
+  let at = 13 + (((bytes[10] as number) & 0x80) ? 3 << (((bytes[10] as number) & 7) + 1) : 0);
+  let loop: number | null = null;
+  const frames: { delay: number; rgb: number[][] }[] = [];
+  let delay = 0;
+  while (bytes[at] !== 0x3b) {
+    const kind = bytes[at];
+    if (kind === 0x21) {
+      const label = bytes[at + 1];
+      if (label === 0xff && text(at + 3, 11) === 'NETSCAPE2.0') loop = u16(at + 16);
+      if (label === 0xf9) delay = u16(at + 4);
+      at += 2;
+      while (bytes[at] !== 0) at += (bytes[at] as number) + 1;
+      at += 1;
+    } else if (kind === 0x2c) {
+      const w = u16(at + 5);
+      const h = u16(at + 7);
+      const packed = bytes[at + 9] as number;
+      expect(packed & 0x80).toBe(0x80);
+      const entries = 1 << ((packed & 7) + 1);
+      const table = bytes.subarray(at + 10, at + 10 + entries * 3);
+      at += 10 + entries * 3;
+      const minCode = bytes[at++] as number;
+      const data: number[] = [];
+      while (bytes[at] !== 0) {
+        const n = bytes[at] as number;
+        data.push(...bytes.subarray(at + 1, at + 1 + n));
+        at += n + 1;
+      }
+      at += 1;
+      const indices = lzwDecode(Uint8Array.from(data), minCode, w * h);
+      frames.push({
+        delay,
+        rgb: indices.map((i) => [table[i * 3] as number, table[i * 3 + 1] as number, table[i * 3 + 2] as number]),
+      });
+    } else throw new Error(`unexpected block 0x${kind?.toString(16)} at ${at}`);
+  }
+  return { width, height, loop, frames };
+}
+
+function lzwDecode(data: Uint8Array, minCode: number, pixels: number): number[] {
+  const clear = 1 << minCode;
+  const end = clear + 1;
+  let width = minCode + 1;
+  let dict: number[][] = [];
+  const reset = () => {
+    dict = Array.from({ length: clear + 2 }, (_, i) => (i < clear ? [i] : []));
+    width = minCode + 1;
+  };
+  reset();
+  const out: number[] = [];
+  let bitPos = 0;
+  let previous: number[] | null = null;
+  while (bitPos + width <= data.length * 8) {
+    let code = 0;
+    for (let b = 0; b < width; b++, bitPos++)
+      code |= (((data[bitPos >> 3] as number) >> (bitPos & 7)) & 1) << b;
+    if (code === clear) {
+      reset();
+      previous = null;
+      continue;
+    }
+    if (code === end) break;
+    let entry: number[];
+    if (code < dict.length) entry = dict[code] as number[];
+    else if (previous && code === dict.length) entry = [...previous, previous[0] as number];
+    else throw new Error(`bad code ${code} (dictionary ${dict.length})`);
+    out.push(...entry);
+    if (previous) dict.push([...previous, entry[0] as number]);
+    previous = entry;
+    if (dict.length === 1 << width && width < 12) width++;
+  }
+  expect(out.length).toBe(pixels);
+  return out;
+}
+
+/** RGBA from a function of the pixel position. */
+const paint = (w: number, h: number, at: (x: number, y: number) => [number, number, number]) => {
+  const rgba = new Uint8ClampedArray(w * h * 4);
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      const [r, g, b] = at(x, y);
+      rgba.set([r, g, b, 255], (y * w + x) * 4);
+    }
+  return rgba;
+};
+
+describe('the GIF encoder', () => {
+  test('🔴 a frame of a few flat colours comes back pixel for pixel, looping forever', () => {
+    const colours: [number, number, number][] = [
+      [255, 0, 0],
+      [0, 128, 255],
+      [16, 16, 16],
+      [248, 248, 248],
+    ];
+    const rgba = paint(37, 23, (x, y) => colours[(x * 3 + y) % 4] as [number, number, number]);
+    const gif = new GifWriter(37, 23);
+    gif.addFrame(rgba, 100);
+    const read = decodeGif(gif.finish());
+    expect(read).toMatchObject({ width: 37, height: 23, loop: 0 });
+    expect(read.frames).toHaveLength(1);
+    expect(read.frames[0]?.delay).toBe(10);
+    const back = read.frames[0]?.rgb ?? [];
+    for (let i = 0; i < 37 * 23; i++)
+      expect(back[i]).toEqual([...rgba.subarray(i * 4, i * 4 + 3)]);
+  });
+
+  test('🔴 a frame big and busy enough to fill the LZW table decodes intact — the clear-and-regrow path', () => {
+    // 200×150 of noise: tens of thousands of codes, so the table hits 4096 and clears many times.
+    let seed = 7;
+    const rand = () => {
+      seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+      return seed;
+    };
+    const rgba = paint(200, 150, () => [(rand() >> 16) & 0xf8, (rand() >> 16) & 0xf8, (rand() >> 16) & 0xf8]);
+    const { palette, indices } = quantizeFrame(rgba);
+    const encoded = lzwEncode(indices, 8);
+    expect(lzwDecode(encoded, 8, indices.length)).toEqual([...indices]);
+    expect(palette.length).toBe(256 * 3);
+  });
+
+  test('a gradient with more than 256 colours keeps every pixel within a few levels of the truth', () => {
+    const rgba = paint(256, 64, (x, y) => [x, (y * 4) & 255, 255 - x]);
+    const { palette, indices } = quantizeFrame(rgba);
+    let worst = 0;
+    for (let p = 0; p < indices.length; p++) {
+      const e = (indices[p] as number) * 3;
+      for (let c = 0; c < 3; c++)
+        worst = Math.max(worst, Math.abs((palette[e + c] as number) - (rgba[p * 4 + c] as number)));
+    }
+    expect(worst).toBeLessThanOrEqual(24);
+  });
+
+  test('a 15 fps clip carries the hundredths GIF cannot write, so it plays for its real length', () => {
+    const gif = new GifWriter(2, 2);
+    const black = new Uint8ClampedArray(16);
+    for (let i = 0; i < 45; i++) gif.addFrame(black, 1000 / 15);
+    const delays = decodeGif(gif.finish()).frames.map((f) => f.delay);
+    expect(delays.reduce((a, b) => a + b, 0)).toBe(300);
+    expect(new Set(delays)).toEqual(new Set([6, 7]));
+  });
+
+  test('a frame of the wrong size is refused with its sizes', () => {
+    expect(() => new GifWriter(4, 4).addFrame(new Uint8ClampedArray(10), 100)).toThrow('4×4');
+  });
+});
+
+describe('a GIF section', () => {
+  test('opens at the playhead, three seconds long, and stays inside the video', () => {
+    expect(gifSectionAt(10, 60)).toEqual({ startSeconds: 10, endSeconds: 13 });
+    expect(gifSectionAt(59, 60)).toEqual({ startSeconds: 59, endSeconds: 60 });
+    expect(gifSectionAt(60, 60).startSeconds).toBeCloseTo(60 - MIN_GIF_SECONDS);
+  });
+
+  test('🔴 moving one end past the limit moves the OTHER end, never the one in hand', () => {
+    expect(clampGifSection({ startSeconds: 0, endSeconds: 40 }, 60, 'end')).toEqual({
+      startSeconds: 40 - MAX_GIF_SECONDS,
+      endSeconds: 40,
+    });
+    expect(clampGifSection({ startSeconds: 5, endSeconds: 40 }, 60, 'start')).toEqual({
+      startSeconds: 5,
+      endSeconds: 5 + MAX_GIF_SECONDS,
+    });
+    expect(clampGifSection({ startSeconds: 9, endSeconds: 3 }, 60, 'end')).toEqual({
+      startSeconds: 3 - MIN_GIF_SECONDS,
+      endSeconds: 3,
+    });
+  });
+
+  test('is sampled from its start, every 1/fps, the last frame before its end', () => {
+    expect(gifFrameTimes({ startSeconds: 2, endSeconds: 3 }, 10).map((t) => Math.round(t * 10) / 10)).toEqual([
+      2, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9,
+    ]);
+  });
+
+  test('is never wider than the crop it comes from, and keeps its shape', () => {
+    expect(gifSize({ sw: 1920, sh: 1080 }, 480)).toEqual({ width: 480, height: 270 });
+    expect(gifSize({ sw: 300, sh: 200 }, 640)).toEqual({ width: 300, height: 200 });
+  });
+
+  test('says its times to the tenth, its weight, and a file name with no path in it', () => {
+    expect(formatGifTime(72.44)).toBe('1:12.4');
+    expect(formatGifTime(5)).toBe('0:05.0');
+    expect(formatGifBytes(2.4 * 1024 * 1024)).toBe('2.4 MB');
+    expect(formatGifBytes(840 * 1024)).toBe('840 KB');
+    expect(gifFileName('Holiday/Beach.mp4', 12.4)).toBe('Holiday Beach @ 0-12.4.gif');
+    expect(gifFileName(undefined, 0)).toBe('clip @ 0-00.0.gif');
+  });
+});

package/src/react/media/gifEncode.ts

@@ -0,0 +1,298 @@
+// ── A looping GIF, encoded in the browser ────────────────────────────────────────────
+// Owner, 2026-10-11: *"In collections and the cb media player in general allow making a
+// looping gif out of a section of a video."* This is the encoder that ask needs, and only
+// that: GIF89a, a local 256-colour palette per frame, the NETSCAPE2.0 loop block, LZW.
+//
+// 🔴 Written here rather than taken as a dependency. The media entry's heavy libraries are
+// OPTIONAL peers an app has to install and dedupe (see `index.ts`), and the encoder this
+// feature needs is ~200 lines of a frozen 1989 format — smaller than the declaration file,
+// lockfile churn and peer table one more package would cost every app that shows a video.
+// Pure functions over typed arrays, so `gifEncode.spec.ts` decodes what it writes and
+// checks the pixels came back.
+//
+// Per-frame palettes rather than one global one: a clip is captured a frame at a time and
+// a global palette would need every frame in memory first — 300 frames of 640×360 RGBA is
+// 276 MB. Each frame is quantized, written and dropped.
+
+/** The colours one frame is reduced to, and each pixel's index into them. */
+export interface QuantizedFrame {
+  /** `r,g,b` triples — at most 256 of them. */
+  palette: Uint8Array;
+  indices: Uint8Array;
+}
+
+const BINS = 1 << 15; // 5 bits a channel
+
+const binOf = (r: number, g: number, b: number): number => ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3);
+
+/**
+ * Median-cut an RGBA frame to at most `maxColors` colours.
+ *
+ * Pixels are first counted into 32,768 bins (5 bits a channel) holding their true 8-bit
+ * sums, so a palette entry is the real average of what it stands for rather than a bin's
+ * corner. The box split is the one with the most pixels × widest channel, at its weighted
+ * median — the textbook cut, which keeps a big flat sky from eating every entry. A frame with
+ * no more than `maxColors` distinct binned colours keeps them all.
+ */
+export function quantizeFrame(rgba: Uint8Array | Uint8ClampedArray, maxColors = 256): QuantizedFrame {
+  const pixels = rgba.length >> 2;
+  const count = new Uint32Array(BINS);
+  const sumR = new Float64Array(BINS);
+  const sumG = new Float64Array(BINS);
+  const sumB = new Float64Array(BINS);
+  for (let p = 0, i = 0; p < pixels; p++, i += 4) {
+    const r = rgba[i] as number;
+    const g = rgba[i + 1] as number;
+    const b = rgba[i + 2] as number;
+    const bin = binOf(r, g, b);
+    count[bin] = (count[bin] as number) + 1;
+    sumR[bin] = (sumR[bin] as number) + r;
+    sumG[bin] = (sumG[bin] as number) + g;
+    sumB[bin] = (sumB[bin] as number) + b;
+  }
+  const used: number[] = [];
+  for (let bin = 0; bin < BINS; bin++) if (count[bin]) used.push(bin);
+
+  const channel = (bin: number, c: 0 | 1 | 2): number => (bin >> (10 - 5 * c)) & 31;
+  type Box = { bins: number[]; pixels: number; c: 0 | 1 | 2; range: number };
+  // A box's widest channel is measured once, when it is made — the split loop asks for it
+  // of every box on every pass, and re-scanning 32k bins 256 times a frame is the cost here.
+  const boxOf = (bins: number[]): Box => {
+    let pixels = 0;
+    const lo = [31, 31, 31];
+    const hi = [0, 0, 0];
+    for (const bin of bins) {
+      pixels += count[bin] as number;
+      for (const c of [0, 1, 2] as const) {
+        const v = channel(bin, c);
+        if (v < (lo[c] as number)) lo[c] = v;
+        if (v > (hi[c] as number)) hi[c] = v;
+      }
+    }
+    const ranges = [0, 1, 2].map((c) => (hi[c] as number) - (lo[c] as number));
+    const c = ranges.indexOf(Math.max(...ranges)) as 0 | 1 | 2;
+    return { bins, pixels, c, range: ranges[c] as number };
+  };
+
+  const boxes: Box[] = [boxOf(used)];
+  while (boxes.length < maxColors) {
+    let pick = -1;
+    let score = 0;
+    for (let i = 0; i < boxes.length; i++) {
+      const box = boxes[i] as Box;
+      if (box.bins.length < 2) continue;
+      const s = box.pixels * (box.range + 1);
+      if (s > score) {
+        score = s;
+        pick = i;
+      }
+    }
+    if (pick < 0) break; // every box is one colour
+    const box = boxes[pick] as Box;
+    const { c } = box;
+    box.bins.sort((a, b) => channel(a, c) - channel(b, c));
+    let seen = 0;
+    let cut = 1;
+    for (let i = 0; i < box.bins.length - 1; i++) {
+      seen += count[box.bins[i] as number] as number;
+      cut = i + 1;
+      if (seen * 2 >= box.pixels) break;
+    }
+    boxes.splice(pick, 1, boxOf(box.bins.slice(0, cut)), boxOf(box.bins.slice(cut)));
+  }
+
+  const palette = new Uint8Array(Math.max(1, boxes.length) * 3);
+  const lut = new Uint8Array(BINS);
+  boxes.forEach((box, entry) => {
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    for (const bin of box.bins) {
+      r += sumR[bin] as number;
+      g += sumG[bin] as number;
+      b += sumB[bin] as number;
+    }
+    const n = Math.max(1, box.pixels);
+    palette[entry * 3] = Math.round(r / n);
+    palette[entry * 3 + 1] = Math.round(g / n);
+    palette[entry * 3 + 2] = Math.round(b / n);
+  });
+  // Each bin maps to its NEAREST palette entry, not merely the box it fell in: a box's
+  // average can sit closer to a neighbour's members than to some of its own.
+  const entries = palette.length / 3;
+  for (const bin of used) {
+    const n = count[bin] as number;
+    const r = (sumR[bin] as number) / n;
+    const g = (sumG[bin] as number) / n;
+    const b = (sumB[bin] as number) / n;
+    let best = 0;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let e = 0; e < entries; e++) {
+      const dr = r - (palette[e * 3] as number);
+      const dg = g - (palette[e * 3 + 1] as number);
+      const db = b - (palette[e * 3 + 2] as number);
+      const d = dr * dr + dg * dg + db * db;
+      if (d < bestDistance) {
+        bestDistance = d;
+        best = e;
+      }
+    }
+    lut[bin] = best;
+  }
+  const indices = new Uint8Array(pixels);
+  for (let p = 0, i = 0; p < pixels; p++, i += 4)
+    indices[p] = lut[binOf(rgba[i] as number, rgba[i + 1] as number, rgba[i + 2] as number)] as number;
+  return { palette, indices };
+}
+
+/**
+ * GIF's variable-width LZW over 8-bit indices, as the bytes between the minimum code size and
+ * the block terminator (before they are cut into 255-byte sub-blocks).
+ *
+ * 🔴 The code width grows when the NEXT code to be assigned reaches `1 << width`, and only
+ * then — the decoder learns each entry one code later than the encoder makes it, and growing
+ * a code early or late desynchronises every code after it into noise.
+ */
+export function lzwEncode(indices: Uint8Array, minCodeSize = 8): Uint8Array {
+  const clear = 1 << minCodeSize;
+  const end = clear + 1;
+  const out: number[] = [];
+  let width = minCodeSize + 1;
+  let next = end + 1;
+  let bits = 0;
+  let held = 0;
+  const emit = (code: number): void => {
+    held |= code << bits;
+    bits += width;
+    while (bits >= 8) {
+      out.push(held & 0xff);
+      held >>>= 8;
+      bits -= 8;
+    }
+  };
+  let table = new Map<number, number>();
+  emit(clear);
+  if (indices.length === 0) {
+    emit(end);
+    if (bits > 0) out.push(held & 0xff);
+    return Uint8Array.from(out);
+  }
+  let prefix = indices[0] as number;
+  for (let i = 1; i < indices.length; i++) {
+    const k = indices[i] as number;
+    const key = (prefix << 8) | k;
+    const known = table.get(key);
+    if (known !== undefined) {
+      prefix = known;
+      continue;
+    }
+    emit(prefix);
+    if (next === 4096) {
+      emit(clear);
+      table = new Map();
+      width = minCodeSize + 1;
+      next = end + 1;
+    } else {
+      if (next >= 1 << width) width++;
+      table.set(key, next++);
+    }
+    prefix = k;
+  }
+  emit(prefix);
+  emit(end);
+  if (bits > 0) out.push(held & 0xff);
+  return Uint8Array.from(out);
+}
+
+/** A GIF built a frame at a time. `finish()` closes it and hands back the file. */
+export class GifWriter {
+  private readonly parts: Uint8Array[] = [];
+  /** Centiseconds owed to the next frame — see {@link addFrame}. */
+  private carry = 0;
+
+  constructor(
+    readonly width: number,
+    readonly height: number,
+    /** 0 loops forever, which is what a GIF made from a clip is for. */
+    loop = 0,
+  ) {
+    if (width < 1 || height < 1 || width > 0xffff || height > 0xffff) throw new Error(`A GIF cannot be ${width}×${height}.`);
+    const head = new Uint8Array(13 + 19);
+    head.set([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]); // GIF89a
+    put16(head, 6, width);
+    put16(head, 8, height);
+    // No global colour table: every frame carries its own.
+    head.set([0x00, 0x00, 0x00], 10);
+    // NETSCAPE2.0 application extension — the loop count.
+    head.set([0x21, 0xff, 0x0b, ...ascii("NETSCAPE2.0"), 0x03, 0x01], 13);
+    put16(head, 29, loop);
+    head[31] = 0x00;
+    this.parts.push(head);
+  }
+
+  /**
+   * One frame of `width × height` RGBA, shown for `delayMs`.
+   *
+   * GIF counts delay in hundredths of a second, so 15 fps (6.67 cs) cannot be written
+   * exactly. The remainder is carried into the next frame rather than rounded away, so a
+   * 3-second clip plays for 3 seconds instead of drifting to 2.7 or 3.5.
+   */
+  addFrame(rgba: Uint8Array | Uint8ClampedArray, delayMs: number): void {
+    if (rgba.length !== this.width * this.height * 4)
+      throw new Error(`A ${this.width}×${this.height} frame is ${this.width * this.height * 4} bytes, not ${rgba.length}.`);
+    const exact = delayMs / 10 + this.carry;
+    const delay = Math.max(2, Math.round(exact));
+    this.carry = exact - delay;
+
+    const { palette, indices } = quantizeFrame(rgba);
+    const tableBits = Math.max(1, Math.ceil(Math.log2(palette.length / 3)));
+    const table = new Uint8Array(3 << tableBits);
+    table.set(palette);
+
+    const control = new Uint8Array(8);
+    control.set([0x21, 0xf9, 0x04, 0x04]); // graphic control, disposal 1: leave the frame in place
+    put16(control, 4, delay);
+    const descriptor = new Uint8Array(10);
+    descriptor[0] = 0x2c;
+    put16(descriptor, 5, this.width);
+    put16(descriptor, 7, this.height);
+    descriptor[9] = 0x80 | (tableBits - 1); // a local colour table of 2^tableBits entries
+
+    // The minimum code size follows the table (never below GIF's floor of 2), so every index
+    // is a root code — what every decoder, Safari's included, expects.
+    const minCodeSize = Math.max(2, tableBits);
+    const data = lzwEncode(indices, minCodeSize);
+    const blocks = new Uint8Array(1 + data.length + Math.ceil(data.length / 255) + 1);
+    blocks[0] = minCodeSize;
+    let at = 1;
+    for (let i = 0; i < data.length; i += 255) {
+      const piece = data.subarray(i, i + 255);
+      blocks[at++] = piece.length;
+      blocks.set(piece, at);
+      at += piece.length;
+    }
+    blocks[at] = 0x00;
+    this.parts.push(control, descriptor, table, blocks);
+  }
+
+  finish(): Uint8Array {
+    this.parts.push(Uint8Array.of(0x3b));
+    const total = this.parts.reduce((n, part) => n + part.length, 0);
+    const file = new Uint8Array(total);
+    let at = 0;
+    for (const part of this.parts) {
+      file.set(part, at);
+      at += part.length;
+    }
+    return file;
+  }
+}
+
+function put16(bytes: Uint8Array, at: number, value: number): void {
+  bytes[at] = value & 0xff;
+  bytes[at + 1] = (value >> 8) & 0xff;
+}
+
+function ascii(text: string): number[] {
+  return [...text].map((ch) => ch.charCodeAt(0));
+}

package/src/react/media/gifRecord.ts

@@ -0,0 +1,103 @@
+// ── Making the GIF: seek, draw, encode ────────────────────────────────────────────────
+// Loaded on demand by the focus viewer (see `gifClip.ts`'s header) — it and `gifEncode.ts` are
+// the bytes of this feature, and a gallery that never makes a GIF should not pay for them.
+//
+// 🔴 Frames are taken by SEEKING the element to each moment, never by playing it and
+// sampling what goes past. Playback drops and repeats frames whenever the machine is busy —
+// and encoding is what keeps it busy — so a played capture stutters exactly as much as the
+// encoder is slow. A seek lands on the frame for that time however long the last one took.
+
+import { formatGifTime, type GifSection, gifFrameTimes, gifSize } from "./gifClip.js";
+import { GifWriter } from "./gifEncode.js";
+
+export interface RecordGifOptions extends GifSection {
+  fps: number;
+  /** Requested output width; see {@link gifSize}. */
+  width: number;
+  /** The source rectangle, in video pixels — what is on screen in a zoomed viewer. Whole frame when omitted. */
+  crop?: { sx: number; sy: number; sw: number; sh: number } | null;
+  /** A CSS filter baked into every frame, the same string the preview shows. */
+  filter?: string;
+  onProgress?: (done: number, total: number) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Seek `video` through the section and encode what it shows as a looping GIF.
+ *
+ * The element is paused for the capture and handed back where it was, paused or playing.
+ * Rejects with an `AbortError` when `signal` aborts, and with a sentence when a frame cannot
+ * be read (a cross-origin source without CORS taints the canvas) or a seek never lands.
+ */
+export async function recordGifClip(video: HTMLVideoElement, options: RecordGifOptions): Promise<Blob> {
+  if (!video.videoWidth || !video.videoHeight) throw new Error("The video has not decoded a frame yet.");
+  const crop = options.crop ?? { sx: 0, sy: 0, sw: video.videoWidth, sh: video.videoHeight };
+  const size = gifSize(crop, options.width);
+  const times = gifFrameTimes(options, options.fps);
+  const canvas = document.createElement("canvas");
+  canvas.width = size.width;
+  canvas.height = size.height;
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  if (!ctx) throw new Error("This browser cannot capture a frame.");
+  ctx.imageSmoothingEnabled = true;
+  ctx.imageSmoothingQuality = "high";
+
+  const was = { at: video.currentTime, playing: !video.paused };
+  video.pause();
+  const writer = new GifWriter(size.width, size.height);
+  try {
+    for (const [i, at] of times.entries()) {
+      if (options.signal?.aborted) throw new DOMException("The GIF was cancelled.", "AbortError");
+      await seekForCapture(video, at);
+      if (options.filter && "filter" in ctx) ctx.filter = options.filter;
+      ctx.drawImage(video, crop.sx, crop.sy, crop.sw, crop.sh, 0, 0, size.width, size.height);
+      let frame: ImageData;
+      try {
+        frame = ctx.getImageData(0, 0, size.width, size.height);
+      } catch {
+        throw new Error("This video's frames cannot be read — it may be cross-origin.");
+      }
+      writer.addFrame(frame.data, 1000 / options.fps);
+      options.onProgress?.(i + 1, times.length);
+    }
+    return new Blob([writer.finish() as BlobPart], { type: "image/gif" });
+  } finally {
+    video.currentTime = was.at;
+    if (was.playing) void video.play().catch(() => undefined);
+  }
+}
+
+/** How long one seek may take before the capture gives up and says so. */
+const SEEK_TIMEOUT_MS = 8_000;
+
+/**
+ * Move to `seconds` and wait until that frame is the one a canvas will read.
+ *
+ * `seeked` says the element has the data; on WebKit the PAINTED frame can still be the old one
+ * for a tick after it, so where `requestVideoFrameCallback` exists the capture also waits for
+ * the new frame to be presented — bounded, because a seek to the frame already showing
+ * presents nothing new.
+ */
+async function seekForCapture(video: HTMLVideoElement, seconds: number): Promise<void> {
+  if (Math.abs(video.currentTime - seconds) < 1e-4 && !video.seeking && video.readyState >= 2) return;
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      video.removeEventListener("seeked", done);
+      reject(new Error(`The video stopped answering at ${formatGifTime(seconds)} — try a shorter section.`));
+    }, SEEK_TIMEOUT_MS);
+    function done(): void {
+      clearTimeout(timer);
+      resolve();
+    }
+    video.addEventListener("seeked", done, { once: true });
+    video.currentTime = seconds;
+  });
+  const presented = (video as HTMLVideoElement & {
+    requestVideoFrameCallback?: (callback: () => void) => number;
+  }).requestVideoFrameCallback;
+  if (typeof presented === "function")
+    await Promise.race([
+      new Promise<void>((resolve) => presented.call(video, () => resolve())),
+      new Promise<void>((resolve) => setTimeout(resolve, 150)),
+    ]);
+}

package/src/styles-areas/analytics.css

@@ -18,7 +18,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 155 candidate(s).
+ * 153 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -31,13 +31,13 @@
 @source inline("@max-4xl:p-0! @max-4xl:text-[length:0] @max-4xl:w-0! @max-6xl:[&>*]:hidden @max-6xl:border-0");
 @source inline("@max-6xl:invisible @max-6xl:min-w-0! @max-6xl:p-0! @max-6xl:text-[length:0] @max-6xl:w-0!");
 @source inline("@max-xl:contents @xl:basis-auto @xl:block @xl:hidden [&>*]:hidden [&>*]:max-w-none");
-@source inline("[&>svg]:size-3.5 [&_svg]:size-3 [overflow-wrap:anywhere] active:cursor-grabbing appearance-none");
-@source inline("basis basis-full bg-[var(--cb-frozen-bg)] bg-card/95 bg-gradient-to-t bg-muted/30 bg-muted/50");
-@source inline("border-accent-solid border-accent/60 border-field-error border-solid border-t-2 col collapse");
-@source inline("cursor-grab data-[ending-style]:opacity-0 data-[ending-style]:scale-95");
-@source inline("data-[highlighted]:bg-accent/10 data-[highlighted]:text-accent-strong");
-@source inline("data-[starting-style]:opacity-0 data-[starting-style]:scale-95 disabled:opacity-40 duration-100");
-@source inline("fade-in focus-visible:ring-field-ring/40 focus-within:border-field-ring focus-within:ring-2");
+@source inline("[&>svg]:size-3.5 [&_svg]:size-3 [overflow-wrap:anywhere] active:cursor-grabbing basis basis-full");
+@source inline("bg-[var(--cb-frozen-bg)] bg-card/95 bg-gradient-to-t bg-muted/30 bg-muted/50 border-accent-solid");
+@source inline("border-accent/60 border-field-error border-solid border-t-2 col collapse cursor-grab");
+@source inline("data-[ending-style]:opacity-0 data-[ending-style]:scale-95 data-[highlighted]:bg-accent/10");
+@source inline("data-[highlighted]:text-accent-strong data-[starting-style]:opacity-0");
+@source inline("data-[starting-style]:scale-95 disabled:opacity-40 duration-100 fade-in");
+@source inline("focus-visible:ring-field-ring/40 focus-within:border-field-ring focus-within:ring-2");
 @source inline("focus-within:ring-field-ring/30 from-card gap-x-6 h-105");
 @source inline("has-[[aria-invalid=true]]:border-field-error hover:bg-background hover:bg-muted/40");
 @source inline("hover:border-field-ring hover:text-warning italic justify-self-end last:border-0 left-11");
@@ -45,7 +45,7 @@
 @source inline("max-sm:min-w-24 max-sm:min-w-32 max-sm:ml-13.5 max-sm:w-auto max-w-32 max-w-36 max-w-45 max-w-48");
 @source inline("max-w-60 min-h-20 min-h-dvh min-w-0! min-w-20 min-w-24 min-w-52 min-w-[var(--anchor-width)]");
 @source inline("min-w-max ml-1.5 mr-2 mt-1.5 mt-3 mt-4 not-italic ordinal p-0! pb-1.5 pl-1.5 pl-2 pr-0.5 pr-1");
-@source inline("pr-10 pr-16 pr-3 pr-9 pt-1 resize-none resize-y right-3 ring-field-error/30 self self-stretch");
+@source inline("pr-10 pr-16 pr-3 pt-1 resize-none resize-y right-3 ring-field-error/30 self self-stretch");
 @source inline("shadow-[1px_0_0_0_var(--color-border)] shrink-[2] size-7 slide-in-from-top-1 table-fixed");
 @source inline("text-[length:0] text-accent-solid-foreground text-field-placeholder text-success text-xl");
 @source inline("to-transparent top-3 transition-[transform,opacity] w-0 w-0! w-11 w-12 w-20 w-32 w-36 w-40 w-88");