Add implementation plan, test fixtures, and test utilities

- Create phased implementation plan (.agents/plans/0001-implementation.md)
  covering 12 phases from io through pdfwriter (~665 classes)

- Add 21 PDF test fixtures (254KB) from PDFBox test suite organized by:
  - basic/: minimal PDFs for core parsing tests
  - xref/: XRef table and stream parsing (incl. object streams)
  - filter/: compression tests (Flate, LZW, ASCII85)
  - encryption/: password-protected PDFs (RC4, AES 40/128/256-bit)
  - malformed/: error handling and recovery tests
  - text/: text extraction tests

- Add test utilities (src/test-utils.ts) for fixture loading,
  byte array helpers, and PDF header validation

- Enhance vitest.config.ts with path aliases, coverage config,
  and longer timeout for PDF parsing tests

- Expand ARCHITECTURE.md with detailed porting patterns for
  numeric types, method overloading, equals/hashCode, and more

- Add test:coverage script to package.json

Author: Mythie

.agents/ARCHITECTURE.md

@@ -6,10 +6,14 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  ci:
+  lint:
+    name: Lint
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -23,8 +27,34 @@ jobs:
       - name: Lint
         run: bun run lint
 
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Type check
         run: bun run typecheck
 
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Test
         run: bun run test:run

.agents/plans/0001-implementation.md

@@ -1,5 +1,14 @@
 # AGENTS.md
 
+This file provides instructions for AI agents porting Apache PDFBox from Java to TypeScript.
+
+## Quick Start
+
+1. Read `.agents/ARCHITECTURE.md` for type mappings and patterns
+2. Check `.agents/PROGRESS.md` for what to port next
+3. Follow the porting order: io → cos → pdfparser → pdmodel → fontbox
+4. After porting a class, update PROGRESS.md and commit
+
 ## Commands
 - `bun install` - Install dependencies
 - `bun run test` - Run tests in watch mode
@@ -9,6 +18,13 @@
 - `bun run lint` - Check linting/formatting
 - `bun run lint:fix` - Auto-fix linting/formatting
 
+## Validation Checklist
+Before committing, ensure:
+1. `bun run typecheck` passes
+2. `bun run lint` passes (or run `lint:fix`)
+3. `bun run test:run` passes
+4. Update `.agents/PROGRESS.md` to mark class as ✅
+
 ## Code Style
 - **Formatting**: Tabs for indentation, double quotes for strings (enforced by Biome)
 - **Imports**: Auto-organized by Biome; use `import type` for type-only imports (verbatimModuleSyntax)
@@ -36,3 +52,227 @@ For packages not listed, follow the same pattern and add to `package.json` impor
 ## Project Context
 This is a 1:1 TypeScript port of Apache PDFBox. Reference implementation is in `checkouts/pdfbox/`.
 See `.agents/ARCHITECTURE.md` for detailed architecture overview and `.agents/PROGRESS.md` for porting status.
+
+## Workflow Guidelines
+
+### Commits
+- Commit often with meaningful messages
+- Each commit should represent a logical unit of work
+- Use conventional commit style when appropriate (e.g., `feat:`, `fix:`, `refactor:`)
+
+### Planning & Documentation
+Write plans and notes to the `.agents/` directory:
+
+| Directory | Purpose | Format |
+|-----------|---------|--------|
+| `.agents/plans/` | Implementation plans before starting work | `[NNNN]-[filename].md` (e.g., `0001-cos-objects.md`) |
+| `.agents/scratch/` | Temporary notes, things to remember between sessions/compaction | Free-form |
+| `.agents/justifications/` | Decisions that deviate from 1:1 port or significant design choices | `[NNNN]-[topic].md` |
+
+### Justifications
+Document in `.agents/justifications/` when you:
+- Deviate from the Java implementation
+- Choose a different algorithm or data structure
+- Use TypeScript idioms instead of direct Java translation
+- Make performance trade-offs
+- Skip or significantly modify functionality
+
+### External Dependencies
+Consider using external dependencies when they make the code significantly cleaner or provide functionality that would be complex to implement. Examples:
+- **Graphics**: e.g., `skia-canvas` or `@napi-rs/canvas` for rendering operations
+- **Compression**: e.g., native libraries for zlib/deflate if needed
+- **Crypto**: e.g., Node's built-in `crypto` module
+
+Always document dependency decisions in `.agents/justifications/`.
+
+## Porting Workflow
+
+### Step-by-Step Process
+1. **Pick a class** from `.agents/PROGRESS.md` (follow dependency order)
+2. **Read the Java source** in `checkouts/pdfbox/`
+3. **Check for Java tests** in `src/test/java/...` — port these too
+4. **Create the TypeScript file** following package mapping
+5. **Port the code** using patterns from `.agents/ARCHITECTURE.md`
+6. **Write/port tests** as `*.test.ts` alongside the source
+7. **Run validation** (typecheck, lint, test)
+8. **Update PROGRESS.md** to mark as ✅
+9. **Commit** with meaningful message
+
+### Dependency Order
+Port classes in order of dependencies. A class cannot be ported until its dependencies exist:
+
+```
+1. io/          → Foundation (RandomAccessRead, etc.)
+2. cos/         → Depends on io (COSBase, COSName, COSDictionary, etc.)
+3. pdfparser/   → Depends on cos, io
+4. pdmodel/     → Depends on cos, pdfparser
+5. fontbox/     → Can be ported in parallel after io
+6. filter/      → Depends on cos, io
+7. text/        → Depends on pdmodel, contentstream
+8. rendering/   → Depends on pdmodel, graphics
+```
+
+### Handling Circular Dependencies
+PDFBox has some circular dependencies. Strategies:
+1. **Forward declarations**: Use `type` imports for circular type references
+2. **Lazy initialization**: Defer imports using dynamic `import()`
+3. **Interface extraction**: Create interfaces in separate files
+4. Document any circular dependency solutions in `.agents/justifications/`
+
+### Stub Dependencies
+If you need a class that isn't ported yet:
+1. Create a minimal stub with `// TODO: implement` comments
+2. Mark it as 🟡 (in progress) in PROGRESS.md
+3. Implement just enough to unblock current work
+4. Add a note in `.agents/scratch/` about what needs completion
+
+## Common Patterns
+
+### Static Factory Methods
+```typescript
+// Java: COSInteger.get(long val)
+// TypeScript: Use static method with caching
+class COSInteger {
+  private static readonly CACHE: COSInteger[] = [];
+  
+  static get(val: number): COSInteger {
+    // Check cache first
+    if (val >= -100 && val <= 256) {
+      return COSInteger.CACHE[val + 100] ??= new COSInteger(val);
+    }
+    return new COSInteger(val);
+  }
+  
+  private constructor(private readonly value: number) {}
+}
+```
+
+### Visitor Pattern
+```typescript
+// Java uses accept(ICOSVisitor)
+// TypeScript: Same pattern with interface
+interface ICOSVisitor<T> {
+  visitFromArray(obj: COSArray): T;
+  visitFromBoolean(obj: COSBoolean): T;
+  visitFromDictionary(obj: COSDictionary): T;
+  // ...
+}
+
+abstract class COSBase {
+  abstract accept<T>(visitor: ICOSVisitor<T>): T;
+}
+```
+
+### Resource Management
+```typescript
+// Java: try-with-resources / Closeable
+// TypeScript: Use Symbol.dispose (requires TS 5.2+) or explicit close()
+
+interface Closeable {
+  close(): void;
+}
+
+// Or with using declaration (TS 5.2+)
+class RandomAccessReadBuffer implements Disposable {
+  [Symbol.dispose](): void {
+    this.close();
+  }
+}
+```
+
+### Streams and Iteration
+```typescript
+// Java: InputStream with read()
+// TypeScript: Use Uint8Array and views
+
+class RandomAccessReadBuffer {
+  private buffer: Uint8Array;
+  private position: number = 0;
+  
+  read(): number {
+    if (this.position >= this.buffer.length) return -1;
+    return this.buffer[this.position++];
+  }
+  
+  readBytes(length: number): Uint8Array {
+    const result = this.buffer.slice(this.position, this.position + length);
+    this.position += result.length;
+    return result;
+  }
+}
+```
+
+### Synchronized/Thread Safety
+```typescript
+// Java: synchronized keyword
+// TypeScript: JavaScript is single-threaded, usually not needed
+// If porting synchronized code, just remove the keyword
+// Document in justifications if there are concerns about Worker threads
+```
+
+## Error Handling
+
+### Custom Exceptions
+```typescript
+// Create error classes matching Java exceptions
+export class IOException extends Error {
+  constructor(message: string, public readonly cause?: Error) {
+    super(message);
+    this.name = "IOException";
+  }
+}
+
+// Usage
+throw new IOException("Failed to read PDF", originalError);
+```
+
+### Checked vs Unchecked
+Java has checked exceptions; TypeScript does not. Strategies:
+1. **Document throws** in JSDoc comments
+2. **Use Result types** for recoverable errors (optional)
+3. **Let errors propagate** for unrecoverable errors
+
+## Testing
+
+### Test File Location
+```
+src/core/cos/COSName.ts      → src/core/cos/COSName.test.ts
+src/io/RandomAccessRead.ts   → src/io/RandomAccessRead.test.ts
+```
+
+### Test Structure
+```typescript
+import { describe, it, expect } from "vitest";
+import { COSName } from "./COSName.ts";
+
+describe("COSName", () => {
+  describe("getPDFName", () => {
+    it("should return name for standard names", () => {
+      const name = COSName.getPDFName("Type");
+      expect(name.getName()).toBe("Type");
+    });
+  });
+});
+```
+
+### Porting Java Tests
+1. Find test in `checkouts/pdfbox/pdfbox/src/test/java/org/apache/pdfbox/...`
+2. Convert JUnit assertions to Vitest:
+   - `assertEquals(expected, actual)` → `expect(actual).toBe(expected)`
+   - `assertTrue(condition)` → `expect(condition).toBe(true)`
+   - `assertNotNull(obj)` → `expect(obj).not.toBeNull()`
+   - `assertThrows(Exception.class, () -> ...)` → `expect(() => ...).toThrow()`
+
+## Debugging Tips
+
+### When Stuck
+1. Check if there's a similar pattern already ported
+2. Read the Java tests for expected behavior
+3. Look at PDFBox JIRA for context on complex code
+4. Write a note in `.agents/scratch/` and move on
+
+### Common Issues
+- **Import cycles**: Use `import type` or restructure
+- **Null vs undefined**: Java null → TypeScript `null | undefined`
+- **Generics**: TypeScript generics are erased; may need runtime checks
+- **Reflection**: PDFBox uses some reflection; may need alternative approaches