@jant/core 0.5.3 → 0.6.0

package/src/lib/__tests__/image-dimensions.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Image dimensions parser tests.
+ *
+ * Each test constructs the minimal valid header bytes for a format and
+ * verifies that {@link parseImageDimensions} extracts width/height.
+ */
+
+import { describe, expect, it } from "vitest";
+import { parseImageDimensions } from "../image-dimensions.js";
+
+describe("parseImageDimensions", () => {
+  describe("PNG", () => {
+    it("parses width and height from the IHDR chunk", () => {
+      const bytes = buildPng(1280, 720);
+      expect(parseImageDimensions("image/png", bytes)).toEqual({
+        width: 1280,
+        height: 720,
+      });
+    });
+
+    it("returns null when the PNG signature is wrong", () => {
+      const bytes = buildPng(10, 10);
+      bytes[0] = 0;
+      expect(parseImageDimensions("image/png", bytes)).toBeNull();
+    });
+
+    it("returns null when the buffer is too short", () => {
+      expect(parseImageDimensions("image/png", new Uint8Array(10))).toBeNull();
+    });
+  });
+
+  describe("JPEG", () => {
+    it("parses dimensions from the SOF0 marker", () => {
+      const bytes = buildJpeg(800, 600);
+      expect(parseImageDimensions("image/jpeg", bytes)).toEqual({
+        width: 800,
+        height: 600,
+      });
+    });
+
+    it("skips APP segments before reaching SOF", () => {
+      const bytes = buildJpegWithApp(1920, 1080);
+      expect(parseImageDimensions("image/jpeg", bytes)).toEqual({
+        width: 1920,
+        height: 1080,
+      });
+    });
+
+    it("returns null when SOI marker is missing", () => {
+      const bytes = new Uint8Array([0x00, 0x00, 0xff, 0xc0]);
+      expect(parseImageDimensions("image/jpeg", bytes)).toBeNull();
+    });
+  });
+
+  describe("GIF", () => {
+    it("parses width and height from the logical screen descriptor", () => {
+      const bytes = buildGif(640, 480);
+      expect(parseImageDimensions("image/gif", bytes)).toEqual({
+        width: 640,
+        height: 480,
+      });
+    });
+  });
+
+  describe("WebP", () => {
+    it("parses VP8 (lossy) dimensions", () => {
+      const bytes = buildWebpVp8(1024, 768);
+      expect(parseImageDimensions("image/webp", bytes)).toEqual({
+        width: 1024,
+        height: 768,
+      });
+    });
+
+    it("parses VP8L (lossless) dimensions", () => {
+      const bytes = buildWebpVp8L(300, 200);
+      expect(parseImageDimensions("image/webp", bytes)).toEqual({
+        width: 300,
+        height: 200,
+      });
+    });
+
+    it("parses VP8X (extended) dimensions", () => {
+      const bytes = buildWebpVp8X(4096, 4096);
+      expect(parseImageDimensions("image/webp", bytes)).toEqual({
+        width: 4096,
+        height: 4096,
+      });
+    });
+
+    it("returns null when RIFF header is missing", () => {
+      const bytes = buildWebpVp8(10, 10);
+      bytes[0] = 0;
+      expect(parseImageDimensions("image/webp", bytes)).toBeNull();
+    });
+  });
+
+  describe("AVIF", () => {
+    it("parses dimensions from the ispe box", () => {
+      const bytes = buildAvif(2000, 1500);
+      expect(parseImageDimensions("image/avif", bytes)).toEqual({
+        width: 2000,
+        height: 1500,
+      });
+    });
+
+    it("accepts AVIF declared via compatible_brands", () => {
+      const bytes = buildAvif(500, 500, { majorBrand: "mif1" });
+      expect(parseImageDimensions("image/avif", bytes)).toEqual({
+        width: 500,
+        height: 500,
+      });
+    });
+  });
+
+  describe("unsupported types", () => {
+    it("returns null for SVG", () => {
+      const bytes = new TextEncoder().encode(
+        '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"/>',
+      );
+      expect(parseImageDimensions("image/svg+xml", bytes)).toBeNull();
+    });
+
+    it("returns null for unknown mime types", () => {
+      expect(parseImageDimensions("image/bmp", new Uint8Array(64))).toBeNull();
+      expect(parseImageDimensions("text/plain", new Uint8Array(64))).toBeNull();
+    });
+  });
+});
+
+// ── Fixture builders ──────────────────────────────────────────────────
+
+function buildPng(width: number, height: number): Uint8Array {
+  // Signature + IHDR chunk header. Only the first 24 bytes are inspected.
+  const bytes = new Uint8Array(24);
+  bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(8, 13, false); // IHDR chunk length
+  bytes.set([0x49, 0x48, 0x44, 0x52], 12); // "IHDR"
+  view.setUint32(16, width, false);
+  view.setUint32(20, height, false);
+  return bytes;
+}
+
+function buildJpeg(width: number, height: number): Uint8Array {
+  // SOI + SOF0(payload: 8 bytes precision/height/width/components)
+  const bytes = new Uint8Array(2 + 2 + 8);
+  bytes[0] = 0xff;
+  bytes[1] = 0xd8;
+  bytes[2] = 0xff;
+  bytes[3] = 0xc0; // SOF0
+  bytes[4] = 0x00;
+  bytes[5] = 0x08; // segment length
+  bytes[6] = 0x08; // precision (8-bit)
+  bytes[7] = (height >> 8) & 0xff;
+  bytes[8] = height & 0xff;
+  bytes[9] = (width >> 8) & 0xff;
+  bytes[10] = width & 0xff;
+  bytes[11] = 0x03; // components
+  return bytes;
+}
+
+function buildJpegWithApp(width: number, height: number): Uint8Array {
+  // SOI + APP0 (length 16) + SOF0
+  const appPayload = 14; // 16-byte segment - 2 length bytes
+  const total = 2 + 2 + 2 + appPayload + 2 + 8;
+  const bytes = new Uint8Array(total);
+  let i = 0;
+  bytes[i++] = 0xff;
+  bytes[i++] = 0xd8;
+  bytes[i++] = 0xff;
+  bytes[i++] = 0xe0; // APP0
+  bytes[i++] = 0x00;
+  bytes[i++] = 0x10; // length 16
+  i += appPayload;
+  bytes[i++] = 0xff;
+  bytes[i++] = 0xc2; // SOF2 (progressive — also recognized)
+  bytes[i++] = 0x00;
+  bytes[i++] = 0x08;
+  bytes[i++] = 0x08;
+  bytes[i++] = (height >> 8) & 0xff;
+  bytes[i++] = height & 0xff;
+  bytes[i++] = (width >> 8) & 0xff;
+  bytes[i++] = width & 0xff;
+  bytes[i] = 0x03;
+  return bytes;
+}
+
+function buildGif(width: number, height: number): Uint8Array {
+  const bytes = new Uint8Array(10);
+  bytes.set([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]); // GIF89a
+  bytes[6] = width & 0xff;
+  bytes[7] = (width >> 8) & 0xff;
+  bytes[8] = height & 0xff;
+  bytes[9] = (height >> 8) & 0xff;
+  return bytes;
+}
+
+function buildWebpHeader(chunk: string, payloadLen: number): Uint8Array {
+  const totalChunk = 8 + payloadLen;
+  const bytes = new Uint8Array(12 + totalChunk);
+  bytes.set([0x52, 0x49, 0x46, 0x46]); // RIFF
+  const view = new DataView(bytes.buffer);
+  view.setUint32(4, 4 + totalChunk, true); // file size minus 8
+  bytes.set([0x57, 0x45, 0x42, 0x50], 8); // WEBP
+  for (let i = 0; i < 4; i += 1) {
+    bytes[12 + i] = chunk.charCodeAt(i);
+  }
+  view.setUint32(16, payloadLen, true);
+  return bytes;
+}
+
+function buildWebpVp8(width: number, height: number): Uint8Array {
+  // VP8 chunk: 10-byte frame header + signature 0x9d 0x01 0x2a + width/height
+  const payloadLen = 16;
+  const bytes = buildWebpHeader("VP8 ", payloadLen);
+  bytes[23] = 0x9d;
+  bytes[24] = 0x01;
+  bytes[25] = 0x2a;
+  bytes[26] = width & 0xff;
+  bytes[27] = (width >> 8) & 0x3f;
+  bytes[28] = height & 0xff;
+  bytes[29] = (height >> 8) & 0x3f;
+  return bytes;
+}
+
+function buildWebpVp8L(width: number, height: number): Uint8Array {
+  const payloadLen = 5;
+  const bytes = buildWebpHeader("VP8L", payloadLen);
+  bytes[20] = 0x2f; // signature
+  const w = width - 1;
+  const h = height - 1;
+  bytes[21] = w & 0xff;
+  bytes[22] = ((w >> 8) & 0x3f) | ((h & 0x03) << 6);
+  bytes[23] = (h >> 2) & 0xff;
+  bytes[24] = (h >> 10) & 0x0f;
+  return bytes;
+}
+
+function buildWebpVp8X(width: number, height: number): Uint8Array {
+  const payloadLen = 10;
+  const bytes = buildWebpHeader("VP8X", payloadLen);
+  // bytes[20..23] flags + reserved
+  const w = width - 1;
+  const h = height - 1;
+  bytes[24] = w & 0xff;
+  bytes[25] = (w >> 8) & 0xff;
+  bytes[26] = (w >> 16) & 0xff;
+  bytes[27] = h & 0xff;
+  bytes[28] = (h >> 8) & 0xff;
+  bytes[29] = (h >> 16) & 0xff;
+  return bytes;
+}
+
+interface AvifFixtureOptions {
+  majorBrand?: string;
+}
+
+function buildAvif(
+  width: number,
+  height: number,
+  opts: AvifFixtureOptions = {},
+): Uint8Array {
+  const majorBrand = opts.majorBrand ?? "avif";
+  const ispe = makeBox(
+    "ispe",
+    concat([new Uint8Array(4), u32BE(width), u32BE(height)]),
+  );
+  const ipco = makeBox("ipco", ispe);
+  const iprp = makeBox("iprp", ipco);
+  const meta = makeBox(
+    "meta",
+    concat([new Uint8Array(4), iprp]), // FullBox version/flags + iprp
+  );
+  // ftyp: major_brand + minor_version + compatible_brands ("avif")
+  const ftypPayload = concat([
+    asciiBytes(majorBrand),
+    u32BE(0),
+    asciiBytes("avif"),
+  ]);
+  const ftyp = makeBox("ftyp", ftypPayload);
+  return concat([ftyp, meta]);
+}
+
+function makeBox(type: string, payload: Uint8Array): Uint8Array {
+  const size = 8 + payload.length;
+  const bytes = new Uint8Array(size);
+  new DataView(bytes.buffer).setUint32(0, size, false);
+  bytes.set(asciiBytes(type), 4);
+  bytes.set(payload, 8);
+  return bytes;
+}
+
+function asciiBytes(s: string): Uint8Array {
+  const bytes = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i += 1) bytes[i] = s.charCodeAt(i);
+  return bytes;
+}
+
+function u32BE(value: number): Uint8Array {
+  const bytes = new Uint8Array(4);
+  new DataView(bytes.buffer).setUint32(0, value, false);
+  return bytes;
+}
+
+function concat(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, c) => sum + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}

package/src/lib/__tests__/mp4-track-flags.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import { zeroTrackAlternateGroups } from "../mp4-track-flags.js";
+
+const str4 = (s: string): number[] => [...s].map((c) => c.charCodeAt(0));
+const u32 = (n: number): number[] => [
+  (n >>> 24) & 0xff,
+  (n >>> 16) & 0xff,
+  (n >>> 8) & 0xff,
+  n & 0xff,
+];
+const u16 = (n: number): number[] => [(n >>> 8) & 0xff, n & 0xff];
+const box = (type: string, ...payload: number[][]): number[] => {
+  const body = payload.flat();
+  return [...u32(body.length + 8), ...str4(type), ...body];
+};
+
+/** A `tkhd` box with a given version and alternate_group value. */
+function tkhd(version: 0 | 1, alternateGroup: number): number[] {
+  // creation, modification, trackID, reserved: 4 fields, 4 or 8 bytes each.
+  const idAndTimes =
+    version === 1 ? new Array(24).fill(0) : new Array(16).fill(0);
+  const duration = version === 1 ? new Array(8).fill(0) : new Array(4).fill(0);
+  return box(
+    "tkhd",
+    [version, 0, 0, 0], // version + flags
+    idAndTimes,
+    duration,
+    new Array(8).fill(0), // reserved[2]
+    u16(0), // layer
+    u16(alternateGroup),
+    new Array(48).fill(0), // volume, reserved, matrix, width, height
+  );
+}
+
+describe("zeroTrackAlternateGroups", () => {
+  it("zeroes a non-zero alternate_group in every tkhd (v0)", () => {
+    const bytes = new Uint8Array(
+      box(
+        "moov",
+        box("trak", tkhd(0, 1), box("mdia", [])),
+        box("trak", tkhd(0, 2), box("mdia", [])),
+      ),
+    );
+    zeroTrackAlternateGroups(bytes.buffer);
+
+    const view = new DataView(bytes.buffer);
+    // Locate both tkhd boxes and confirm alternate_group is now 0.
+    const groups: number[] = [];
+    for (let i = 0; i + 8 <= bytes.length; i++) {
+      if (
+        String.fromCharCode(
+          bytes[i + 4],
+          bytes[i + 5],
+          bytes[i + 6],
+          bytes[i + 7],
+        ) === "tkhd"
+      ) {
+        groups.push(view.getUint16(i + 8 + 4 + 20 + 8 + 2));
+      }
+    }
+    expect(groups).toEqual([0, 0]);
+  });
+
+  it("handles version 1 tkhd boxes", () => {
+    const bytes = new Uint8Array(box("moov", box("trak", tkhd(1, 7))));
+    zeroTrackAlternateGroups(bytes.buffer);
+
+    const view = new DataView(bytes.buffer);
+    let offset = -1;
+    for (let i = 0; i + 8 <= bytes.length; i++) {
+      if (
+        String.fromCharCode(
+          bytes[i + 4],
+          bytes[i + 5],
+          bytes[i + 6],
+          bytes[i + 7],
+        ) === "tkhd"
+      ) {
+        offset = i + 8 + 4 + 32 + 8 + 2;
+      }
+    }
+    expect(view.getUint16(offset)).toBe(0);
+  });
+
+  it("touches nothing but the alternate_group field", () => {
+    const original = new Uint8Array(
+      box(
+        "moov",
+        box("trak", tkhd(0, 0x0102), box("mdia", box("mdhd", u32(0)))),
+      ),
+    );
+    const copy = new Uint8Array(original);
+    zeroTrackAlternateGroups(copy.buffer);
+
+    const diffs: number[] = [];
+    for (let i = 0; i < original.length; i++) {
+      if (original[i] !== copy[i]) diffs.push(i);
+    }
+    // Exactly the two bytes of one alternate_group field changed.
+    expect(diffs).toHaveLength(2);
+    expect(diffs[1]).toBe(diffs[0] + 1);
+  });
+
+  it("leaves an already-zero alternate_group untouched", () => {
+    const original = new Uint8Array(box("moov", box("trak", tkhd(0, 0))));
+    const copy = new Uint8Array(original);
+    zeroTrackAlternateGroups(copy.buffer);
+    expect([...copy]).toEqual([...original]);
+  });
+
+  it("ignores files with no tkhd box", () => {
+    const original = new Uint8Array(box("ftyp", str4("isom")));
+    const copy = new Uint8Array(original);
+    zeroTrackAlternateGroups(copy.buffer);
+    expect([...copy]).toEqual([...original]);
+  });
+});

package/src/lib/__tests__/telegram-entities.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from "vitest";
+import { entitiesToMarkdown } from "../telegram-entities.js";
+import type { TelegramMessageEntity } from "../telegram.js";
+
+function ents(
+  ...entries: Array<
+    Partial<TelegramMessageEntity> & {
+      type: string;
+      offset: number;
+      length: number;
+    }
+  >
+): TelegramMessageEntity[] {
+  return entries as TelegramMessageEntity[];
+}
+
+describe("entitiesToMarkdown", () => {
+  it("returns text unchanged when entities is empty or undefined", () => {
+    expect(entitiesToMarkdown("hello", [])).toBe("hello");
+    expect(entitiesToMarkdown("hello", undefined)).toBe("hello");
+  });
+
+  it("preserves user-typed markdown that sits outside any entity", () => {
+    // No entities → byte-for-byte passthrough. This is the case where the
+    // user typed literal markdown into Telegram instead of using its
+    // formatting menu.
+    expect(entitiesToMarkdown("**already bold** _italic_", [])).toBe(
+      "**already bold** _italic_",
+    );
+  });
+
+  it("wraps bold, italic, and strikethrough spans", () => {
+    expect(
+      entitiesToMarkdown(
+        "bold italic strike",
+        ents(
+          { type: "bold", offset: 0, length: 4 },
+          { type: "italic", offset: 5, length: 6 },
+          { type: "strikethrough", offset: 12, length: 6 },
+        ),
+      ),
+    ).toBe("**bold** *italic* ~~strike~~");
+  });
+
+  it("wraps text_link entities with the url", () => {
+    expect(
+      entitiesToMarkdown(
+        "see Jant for details",
+        ents({
+          type: "text_link",
+          offset: 4,
+          length: 4,
+          url: "https://jant.example/",
+        }),
+      ),
+    ).toBe("see [Jant](https://jant.example/) for details");
+  });
+
+  it("escapes parentheses in link URLs", () => {
+    expect(
+      entitiesToMarkdown(
+        "ref",
+        ents({
+          type: "text_link",
+          offset: 0,
+          length: 3,
+          url: "https://en.wikipedia.org/wiki/Foo_(bar)",
+        }),
+      ),
+    ).toBe("[ref](https://en.wikipedia.org/wiki/Foo_\\(bar\\))");
+  });
+
+  it("uses the shortest non-colliding fence for inline code with backticks", () => {
+    // Content has a single backtick, so a double-backtick fence is required.
+    expect(
+      entitiesToMarkdown(
+        "use `code` here",
+        ents({ type: "code", offset: 4, length: 6 }),
+      ),
+    ).toBe("use `` `code` `` here");
+  });
+
+  it("emits fenced code blocks with the entity language", () => {
+    expect(
+      entitiesToMarkdown(
+        "print(1)",
+        ents({ type: "pre", offset: 0, length: 8, language: "python" }),
+      ),
+    ).toBe("```python\nprint(1)\n```");
+  });
+
+  it("escapes markdown delimiters that appear inside a styled span", () => {
+    // Without escaping, the inner `_underscore_` would render as italic
+    // when the post body is parsed as markdown, even though the user only
+    // asked for bold.
+    expect(
+      entitiesToMarkdown(
+        "a _b_ c",
+        ents({ type: "bold", offset: 0, length: 7 }),
+      ),
+    ).toBe("**a \\_b\\_ c**");
+  });
+
+  it("handles nested entities (italic inside bold)", () => {
+    // "bold and italic" — bold covers the whole span, italic covers "italic"
+    expect(
+      entitiesToMarkdown(
+        "bold and italic",
+        ents(
+          { type: "bold", offset: 0, length: 15 },
+          { type: "italic", offset: 9, length: 6 },
+        ),
+      ),
+    ).toBe("**bold and *italic***");
+  });
+
+  it("renders a bold link as a bold-wrapped markdown link", () => {
+    expect(
+      entitiesToMarkdown(
+        "click here",
+        ents(
+          { type: "bold", offset: 0, length: 10 },
+          {
+            type: "text_link",
+            offset: 6,
+            length: 4,
+            url: "https://example.com/",
+          },
+        ),
+      ),
+    ).toBe("**click [here](https://example.com/)**");
+  });
+
+  it("leaves auto-detected url/mention/hashtag entities as plain text", () => {
+    // Telegram tags these automatically; markdown will auto-link the URL.
+    expect(
+      entitiesToMarkdown(
+        "visit https://jant.example/ @alice #news",
+        ents(
+          { type: "url", offset: 6, length: 21 },
+          { type: "mention", offset: 28, length: 6 },
+          { type: "hashtag", offset: 35, length: 5 },
+        ),
+      ),
+    ).toBe("visit https://jant.example/ @alice #news");
+  });
+
+  it("renders blockquote entities with `> ` per line", () => {
+    expect(
+      entitiesToMarkdown(
+        "line one\nline two",
+        ents({ type: "blockquote", offset: 0, length: 17 }),
+      ),
+    ).toBe("> line one\n> line two");
+  });
+
+  it("uses UTF-16 offsets so surrogate-pair emoji align correctly", () => {
+    // The emoji is one Telegram "character" but two JS code units. Telegram
+    // sends offset 3 / length 4 for "bold" — that lands on indices 3..7 in
+    // the JS string, which is exactly what slice expects.
+    const text = "👋 hi bold tail";
+    // wave emoji is two UTF-16 units, so the string is 15 long, not 14.
+    expect(text.length).toBe(15);
+    expect(text.slice(6, 10)).toBe("bold");
+    expect(
+      entitiesToMarkdown(text, ents({ type: "bold", offset: 6, length: 4 })),
+    ).toBe("👋 hi **bold** tail");
+  });
+
+  it("does not escape markdown chars between top-level entities", () => {
+    // Bold span at the end; the **literal asterisks** the user typed before
+    // it must pass through unchanged.
+    expect(
+      entitiesToMarkdown(
+        "**typed** styled",
+        ents({ type: "bold", offset: 10, length: 6 }),
+      ),
+    ).toBe("**typed** **styled**");
+  });
+});