fix: address multiple critical issues and refactor appearance generator

- Fix quadraticCurveTo to properly convert quadratic to cubic Bezier
  curves with current-point tracking
- Make ContentTokenizer lenient on unexpected delimiters (warns instead
  of throwing)
- Split appearance-generator.ts (1600+ lines) into smaller modules:
  appearance-utils, text-appearance, button-appearance, choice-appearance
- Fix memory leak in PdfName/PdfRef static caches using LRU cache with
  bounded size (10k/20k entries)
- Add validation for XRef stream field widths to prevent integer overflow
- Use multiplication instead of bitwise shift for large field values
- Cache TextDecoder instance in token-reader.ts hot paths
- Document PdfStream data state machine and getEncodedData() behavior

Author: Mythie

src/api/drawing/path-builder.test.ts

@@ -44,6 +44,36 @@ describe("PathBuilder", () => {
       expect(content).toContain("10 20 30 40 50 60 c");
     });
 
+    it("quadraticCurveTo converts to cubic Bezier correctly", () => {
+      const { builder, appendContent } = createBuilder();
+
+      // Start at (0, 0), control point at (50, 100), end at (100, 0)
+      builder.moveTo(0, 0).quadraticCurveTo(50, 100, 100, 0).stroke();
+
+      const content = appendContent.mock.calls[0][0];
+      // Quadratic to cubic conversion:
+      // CP1 = P0 + 2/3 * (QCP - P0) = (0,0) + 2/3 * (50,100) = (33.333, 66.667)
+      // CP2 = P  + 2/3 * (QCP - P)  = (100,0) + 2/3 * (50-100, 100-0) = (100,0) + 2/3 * (-50, 100) = (66.667, 66.667)
+      expect(content).toContain("0 0 m");
+      // Check for curve operator with approximately correct values
+      expect(content).toMatch(/33\.333.*66\.666.*66\.666.*66\.666.*100 0 c/);
+    });
+
+    it("quadraticCurveTo tracks current point correctly", () => {
+      const { builder, appendContent } = createBuilder();
+
+      // Chain two quadratic curves - the second should use end of first as start
+      builder
+        .moveTo(0, 0)
+        .quadraticCurveTo(25, 50, 50, 0) // First curve: (0,0) -> (50,0)
+        .quadraticCurveTo(75, 50, 100, 0) // Second curve: (50,0) -> (100,0)
+        .stroke();
+
+      const content = appendContent.mock.calls[0][0];
+      // Should have two curve operators
+      expect((content.match(/ c\n/g) || []).length).toBe(2);
+    });
+
     it("close adds close-path operator", () => {
       const { builder, appendContent } = createBuilder();
 

src/api/drawing/path-builder.ts

@@ -47,6 +47,14 @@ export class PathBuilder {
   private readonly appendContent: ContentAppender;
   private readonly registerGraphicsState: GraphicsStateRegistrar;
 
+  /** Current point for quadratic-to-cubic conversion */
+  private currentX = 0;
+  private currentY = 0;
+
+  /** Start point of current subpath (for close operations) */
+  private subpathStartX = 0;
+  private subpathStartY = 0;
+
   constructor(appendContent: ContentAppender, registerGraphicsState: GraphicsStateRegistrar) {
     this.appendContent = appendContent;
     this.registerGraphicsState = registerGraphicsState;
@@ -62,6 +70,11 @@ export class PathBuilder {
   moveTo(x: number, y: number): this {
     this.pathOps.push(moveTo(x, y));
 
+    this.currentX = x;
+    this.currentY = y;
+    this.subpathStartX = x;
+    this.subpathStartY = y;
+
     return this;
   }
 
@@ -71,6 +84,9 @@ export class PathBuilder {
   lineTo(x: number, y: number): this {
     this.pathOps.push(lineTo(x, y));
 
+    this.currentX = x;
+    this.currentY = y;
+
     return this;
   }
 
@@ -87,27 +103,41 @@ export class PathBuilder {
   curveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): this {
     this.pathOps.push(curveTo(cp1x, cp1y, cp2x, cp2y, x, y));
 
+    this.currentX = x;
+    this.currentY = y;
+
     return this;
   }
 
   /**
    * Draw a quadratic Bezier curve from the current point to (x, y).
    *
-   * Converted internally to a cubic Bezier curve.
+   * Converted internally to a cubic Bezier curve using the standard
+   * quadratic-to-cubic conversion formula:
+   * - CP1 = P0 + 2/3 * (QCP - P0)
+   * - CP2 = P  + 2/3 * (QCP - P)
+   *
+   * Where P0 is the current point, QCP is the quadratic control point,
+   * and P is the end point.
    *
    * @param cpx - Control point X
    * @param cpy - Control point Y
    * @param x - End point X
    * @param y - End point Y
    */
   quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): this {
-    // Quadratic to cubic conversion requires current point
-    // For simplicity, we approximate by using the control point for both control points
-    // This is a rough approximation - proper conversion needs current point tracking
-    // cp1 = p0 + 2/3 * (cp - p0)
-    // cp2 = p  + 2/3 * (cp - p)
-    // For now, use the control point as both (less accurate but functional)
-    this.pathOps.push(curveTo(cpx, cpy, cpx, cpy, x, y));
+    // Quadratic to cubic conversion:
+    // CP1 = P0 + 2/3 * (QCP - P0) = P0 * 1/3 + QCP * 2/3
+    // CP2 = P  + 2/3 * (QCP - P)  = P  * 1/3 + QCP * 2/3
+    const cp1x = this.currentX + (2 / 3) * (cpx - this.currentX);
+    const cp1y = this.currentY + (2 / 3) * (cpy - this.currentY);
+    const cp2x = x + (2 / 3) * (cpx - x);
+    const cp2y = y + (2 / 3) * (cpy - y);
+
+    this.pathOps.push(curveTo(cp1x, cp1y, cp2x, cp2y, x, y));
+
+    this.currentX = x;
+    this.currentY = y;
 
     return this;
   }
@@ -117,6 +147,9 @@ export class PathBuilder {
    */
   close(): this {
     this.pathOps.push(closePath());
+    // After close, the current point returns to the subpath start
+    this.currentX = this.subpathStartX;
+    this.currentY = this.subpathStartY;
 
     return this;
   }
@@ -129,13 +162,12 @@ export class PathBuilder {
    * Add a rectangle to the current path.
    */
   rectangle(x: number, y: number, width: number, height: number): this {
-    this.pathOps.push(moveTo(x, y));
-    this.pathOps.push(lineTo(x + width, y));
-    this.pathOps.push(lineTo(x + width, y + height));
-    this.pathOps.push(lineTo(x, y + height));
-    this.pathOps.push(closePath());
-
-    return this;
+    // Use fluent methods to ensure current point is tracked
+    return this.moveTo(x, y)
+      .lineTo(x + width, y)
+      .lineTo(x + width, y + height)
+      .lineTo(x, y + height)
+      .close();
   }
 
   /**
@@ -152,14 +184,13 @@ export class PathBuilder {
     const kx = rx * KAPPA;
     const ky = ry * KAPPA;
 
-    this.pathOps.push(moveTo(cx - rx, cy));
-    this.pathOps.push(curveTo(cx - rx, cy + ky, cx - kx, cy + ry, cx, cy + ry));
-    this.pathOps.push(curveTo(cx + kx, cy + ry, cx + rx, cy + ky, cx + rx, cy));
-    this.pathOps.push(curveTo(cx + rx, cy - ky, cx + kx, cy - ry, cx, cy - ry));
-    this.pathOps.push(curveTo(cx - kx, cy - ry, cx - rx, cy - ky, cx - rx, cy));
-    this.pathOps.push(closePath());
-
-    return this;
+    // Use fluent methods to ensure current point is tracked
+    return this.moveTo(cx - rx, cy)
+      .curveTo(cx - rx, cy + ky, cx - kx, cy + ry, cx, cy + ry)
+      .curveTo(cx + kx, cy + ry, cx + rx, cy + ky, cx + rx, cy)
+      .curveTo(cx + rx, cy - ky, cx + kx, cy - ry, cx, cy - ry)
+      .curveTo(cx - kx, cy - ry, cx - rx, cy - ky, cx - rx, cy)
+      .close();
   }
 
   // ─────────────────────────────────────────────────────────────────────────────
@@ -175,6 +206,7 @@ export class PathBuilder {
       borderColor: options.borderColor ?? options.color,
       color: undefined, // Don't fill
     };
+
     this.paint(effectiveOptions);
   }
 
@@ -186,6 +218,7 @@ export class PathBuilder {
       ...options,
       borderColor: undefined, // Don't stroke
     };
+
     this.paint(effectiveOptions);
   }
 
@@ -253,6 +286,7 @@ export class PathBuilder {
    */
   private emitOps(ops: Operator[]): void {
     const content = ops.map(op => op.toString()).join("\n");
+
     this.appendContent(content);
   }
 }

src/content/parsing/content-tokenizer.test.ts

@@ -216,6 +216,24 @@ describe("ContentTokenizer", () => {
     });
   });
 
+  describe("lenient parsing", () => {
+    it("skips unexpected closing bracket and continues", () => {
+      const tokenizer = new ContentTokenizer(encode("] q Q"));
+
+      // Should skip the ] and return q
+      expect(tokenizer.nextToken()).toEqual({ type: "operator", name: "q" });
+      expect(tokenizer.nextToken()).toEqual({ type: "operator", name: "Q" });
+    });
+
+    it("skips unexpected >> and continues", () => {
+      const tokenizer = new ContentTokenizer(encode(">> 42 m"));
+
+      // Should skip the >> and return 42
+      expect(tokenizer.nextToken()).toEqual({ type: "number", value: 42 });
+      expect(tokenizer.nextToken()).toEqual({ type: "operator", name: "m" });
+    });
+  });
+
   describe("peek and eof", () => {
     it("peek returns same token until consumed", () => {
       const tokenizer = new ContentTokenizer(encode("q Q"));

src/content/parsing/content-tokenizer.ts

@@ -90,16 +90,23 @@ export class ContentTokenizer {
   }
 
   private readNext(): ContentOrOperatorToken | null {
-    const token = this.reader.nextToken();
+    while (true) {
+      const token = this.reader.nextToken();
 
-    if (token.type === "eof") {
-      return null;
-    }
+      if (token.type === "eof") {
+        return null;
+      }
 
-    return this.convertToken(token);
+      const result = this.convertToken(token);
+
+      // If convertToken returns null (skipped token), try the next one
+      if (result !== null) {
+        return result;
+      }
+    }
   }
 
-  private convertToken(token: Token): ContentOrOperatorToken {
+  private convertToken(token: Token): ContentOrOperatorToken | null {
     switch (token.type) {
       case "number":
         return { type: "number", value: token.value };
@@ -142,7 +149,7 @@ export class ContentTokenizer {
     return { type: "operator", name: value };
   }
 
-  private handleDelimiter(value: string): ContentToken {
+  private handleDelimiter(value: string): ContentToken | null {
     if (value === "[") {
       return this.readArray();
     }
@@ -152,7 +159,11 @@ export class ContentTokenizer {
     }
 
     // Unexpected delimiters (], >>) - shouldn't happen in valid content stream
-    throw new Error(`Unexpected delimiter: ${value}`);
+    // Be lenient: warn and skip the token rather than throwing
+    console.warn(
+      `ContentTokenizer: Unexpected delimiter '${value}' at position ${this.scanner.position} - skipping`,
+    );
+    return null;
   }
 
   private readArray(): ArrayToken {