pdf-lite 1.0.0

package/.commitlintrc.cjs

@@ -0,0 +1,25 @@
+module.exports = {
+    extends: ['@commitlint/config-conventional'],
+    rules: {
+        'type-empty': [2, 'never'],
+        'type-enum': [
+            2,
+            'always',
+            [
+                'ci',
+                'feat',
+                'fix',
+                'refactor',
+                'revert',
+                'style',
+                'chore',
+                'docs',
+                'test',
+                'bump',
+                'perf',
+                'security',
+                'release',
+            ],
+        ],
+    },
+}

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/workflows/docs.yaml

@@ -0,0 +1,93 @@
+name: Deploy Docs
+
+on:
+    push:
+        branches:
+            - master
+            - docs/* # Useful for testing changes to docs
+        tags:
+            - 'v*.*.*' # Trigger on version tags like v1.0.0, v2.1.3, etc.
+            - 'v*'
+            - 'latest'
+
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: 'pages'
+    cancel-in-progress: false
+
+defaults:
+    run:
+        shell: bash
+
+jobs:
+    build:
+        name: Build Docs for ${{ matrix.version }}
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                version:
+                    - ${{ github.ref_name }}
+        steps:
+            - name: Checkout ${{ matrix.version }}
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+              with:
+                  ref: ${{ matrix.version }}
+            - name: Get formatted ref name
+              id: formatted-ref-name
+              run: echo "formatted_ref_name=${{ matrix.version }}" | sed 's/\//_/g' >> $GITHUB_OUTPUT
+            - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+              with:
+                  run_install: true
+            - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
+              with:
+                  node-version: '24'
+                  cache: 'pnpm'
+            - name: Setup Pages
+              id: pages
+              uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b #v5
+            - name: Compile TypeScript
+              run: pnpm compile
+            - name: Build docs
+              run: pnpm docs:gen ${{ steps.formatted-ref-name.outputs.formatted_ref_name }}
+            - name: Copy latest to root
+              if: matrix.version == 'latest'
+              run: cp -r docs-html/latest/* docs-html/
+            - name: Upload artifact
+              uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+              with:
+                  name: docs-${{ steps.formatted-ref-name.outputs.formatted_ref_name }}
+                  path: ./docs-html
+                  retention-days: 1
+            - name: Where to find the docs
+              run: echo "You can find the documentation for version ${{ matrix.version }} at https://jacobshirley.github.io/pdf-lite/${{ steps.formatted-ref-name.outputs.formatted_ref_name }}" >> $GITHUB_STEP_SUMMARY
+    combine:
+        name: Combine Docs
+        runs-on: ubuntu-latest
+        needs: build
+        steps:
+            - name: Download artifacts
+              uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+              with:
+                  merge-multiple: true
+                  path: ./docs-html
+            - name: Upload combined artifact
+              uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+              with:
+                  path: ./docs-html
+                  retention-days: 1
+                  name: 'github-pages'
+
+    deploy:
+        name: Deploy
+        runs-on: ubuntu-latest
+        needs: combine
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e #v4

package/.github/workflows/prepare-release.yaml

@@ -0,0 +1,79 @@
+name: Prepare Release
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: 'Version to prepare as (e.g. patch, minor, major)'
+                type: choice
+                options:
+                    - patch
+                    - minor
+                    - major
+                    - prepatch
+                    - preminor
+                    - premajor
+                    - prerelease
+                required: true
+            preid:
+                description: 'Prerelease identifier (e.g. alpha, beta, rc). Only used if version is a prerelease type'
+                type: choice
+                required: false
+                options:
+                    - alpha
+                    - beta
+                    - rc
+            force:
+                description: 'Force prepare even if no changes detected'
+                required: false
+                type: boolean
+    push:
+        branches:
+            - release/**
+permissions:
+    actions: write
+    checks: write
+    contents: write
+    pull-requests: write
+jobs:
+    prepare-release:
+        runs-on: ubuntu-latest
+        name: Prepare Release
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+            - name: Set up pnpm
+              uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+              with:
+                  run_install: true
+            - name: Set up Node.js
+              uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
+              with:
+                  node-version: '24'
+                  cache: 'pnpm'
+            - name: Compile
+              run: pnpm compile
+            - name: Bump version
+              run: ./scripts/bump-version.sh ${{ github.event.inputs.version }} --preid='${{ github.event.inputs.preid }}'
+            - name: Generate docs
+              run: pnpm docs:gen:md
+            - name: Set up committer
+              run: |
+                  git config --global user.name "github-actions[bot]"
+                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+            - name: Prepare release
+              if: github.event_name == 'workflow_dispatch'
+              run: ./scripts/prepare-release.sh --create-pr --force=${{ github.event.inputs.force }}
+              env:
+                  GH_TOKEN: ${{ github.token }}
+            - name: Get release version
+              id: get_release_version
+              run: echo "version=$(cat .release-version)" >> $GITHUB_OUTPUT
+            - name: Pack
+              run: pnpm pack -r
+            - name: Push artifacts
+              uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+              with:
+                  name: pdf-lite-${{ steps.get_release_version.outputs.version }}
+                  path: ./*.tgz
+            - name: Test publish
+              run: pnpm publish -r --dry-run --publish-branch=$(git branch --show-current) --no-git-checks

package/.github/workflows/release.yaml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+    push:
+        branches:
+            - 'master'
+
+    # Manual trigger
+    workflow_dispatch:
+permissions:
+    contents: read
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+        name: Publish to npm
+        permissions:
+            contents: write
+            id-token: write
+        if: github.event_name == 'workflow_dispatch' || contains( github.event.head_commit.message, 'release' )
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+            - name: Set up pnpm
+              uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+              with:
+                  run_install: true
+            - name: Set up Node.js
+              uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
+              with:
+                  node-version: '24'
+                  cache: 'pnpm'
+            - name: Get release version
+              id: get_release_version
+              run: echo "version=$(jq -r .version ./package.json)" >> $GITHUB_OUTPUT
+            - name: Compile
+              run: pnpm compile
+            - name: Publish packages
+              run: pnpm -r publish --tag=latest --provenance
+            - name: Tag version
+              run: |
+                  git config --global user.name "github-actions[bot]"
+                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+                  git tag v${{ steps.get_release_version.outputs.version }} --force
+                  MAJOR_VERSION=$(echo ${{ steps.get_release_version.outputs.version }} | cut -d. -f1)
+                  git tag v${MAJOR_VERSION} --force
+                  git tag latest --force
+                  git push origin v${{ steps.get_release_version.outputs.version }} --force
+                  git push origin v${MAJOR_VERSION} --force
+                  git push origin latest --force
+              env:
+                  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            - name: Pack
+              run: pnpm -r pack
+            - name: Push artifacts
+              uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+              with:
+                  name: pdf-lite-${{ steps.get_release_version.outputs.version }}
+                  path: ./*.tgz
+    github-release:
+        runs-on: ubuntu-latest
+        name: Create GitHub Release
+        needs: publish
+        permissions:
+            contents: write
+        steps:
+            - name: Download artifacts
+              uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+            - name: Get release version
+              id: get_release_version
+              run: VERSION_FILE=$(ls *.tgz | head -n 1) && echo "version=$(echo $VERSION_FILE | sed -E 's/^pdf-lite-(.*)\.tgz$/\1/')" >> $GITHUB_OUTPUT
+            - name: Create Release
+              id: create_release
+              uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2
+              with:
+                  draft: false
+                  prerelease: ${{ contains(steps.get_release_version.outputs.version, '-') }}
+                  generate_release_notes: true
+                  tag_name: v${{ steps.get_release_version.outputs.version }}
+                  files: './*.tgz'

package/.github/workflows/test.yaml

@@ -0,0 +1,35 @@
+name: Test
+on:
+    push:
+        branches:
+            - master
+            - ci/test # For testing changes to this workflow
+    pull_request:
+        branches:
+            - master
+    merge_group:
+    workflow_dispatch:
+    workflow_call:
+permissions:
+    contents: read
+    actions: read
+    checks: write
+jobs:
+    Tests:
+        runs-on: ubuntu-latest
+        name: Tests
+        steps:
+            - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+            - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+              with:
+                  run_install: true
+            - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
+              with:
+                  node-version: '24'
+                  cache: 'pnpm'
+            - name: Install Playwright Browsers
+              run: pnpm exec playwright install chromium --only-shell
+            - name: Compile
+              run: pnpm compile
+            - name: Run tests
+              run: pnpm test

package/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm lint:commit

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint:staged

package/.prettierignore

@@ -0,0 +1,4 @@
+**/*.autogenerated.*
+**/*.generated.*
+**/*.gen.*
+pnpm-lock.yaml

package/.prettierrc

@@ -0,0 +1,4 @@
+trailingComma: 'all'
+tabWidth: 4
+semi: false
+singleQuote: true

package/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to PDF-Lite
+
+Thank you for contributing to PDF-Lite! This guide will help you understand the project structure and maintain consistency.
+
+## Project Structure
+
+```
+packages/pdf-lite/
+├── src/
+│   ├── core/       # PDF primitives (objects, parser, tokenizer, streams)
+│   ├── pdf/        # High-level PDF document handling
+│   ├── crypto/     # Encryption algorithms (RC4, AES)
+│   ├── security/   # Security handlers
+│   ├── signing/    # Digital signature support
+│   ├── filters/    # Compression filters (Flate, LZW, etc.)
+│   └── utils/      # Utility functions
+├── test/
+│   ├── unit/       # Unit tests
+│   └── acceptance/ # Acceptance tests
+examples/           # Numbered example scripts (001-create-pdf.ts, etc.)
+```
+
+## Development
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Commands
+
+```bash
+pnpm test           # Run all tests
+pnpm compile        # Compile TypeScript
+pnpm format         # Format code with Prettier
+```
+
+### Making Changes
+
+1. Create a branch: `git checkout -b feature/your-feature-name`
+2. Make your changes
+3. Ensure tests pass: `pnpm test`
+4. Format code: `pnpm format`
+5. Check for TypeScript errors: `pnpm compile`
+6. Submit a pull request
+
+### Commit Guidelines
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+feat: add support for XYZ PDF feature
+fix: correct parsing of encrypted streams
+docs: update encryption examples
+test: add tests for compression algorithms
+refactor: simplify stream processing logic
+```
+
+Other valid types: `ci`, `chore`, `bump`, `perf`, `security`, `release`, `revert`, `style`
+
+## Code Standards
+
+### File Naming
+
+Use kebab-case for all files: `pdf-dictionary.ts`, `pdf-stream.ts`
+
+### Documentation
+
+Use JSDoc comments for public APIs:
+
+```typescript
+/**
+ * Encrypts a PDF stream using the specified algorithm.
+ *
+ * @param stream - The stream to encrypt
+ * @param algorithm - The encryption algorithm to use
+ * @returns The encrypted stream
+ */
+export function encryptStream(stream: PdfStream, algorithm: string): PdfStream {
+    // Implementation
+}
+```
+
+### Testing
+
+Tests are located in `packages/pdf-lite/test/`:
+
+- `unit/` - Unit tests for individual components
+- `acceptance/` - Integration tests with real PDFs
+
+Use Vitest for testing:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+
+describe('Component', () => {
+    it('should do something', () => {
+        expect(result).toBe(expected)
+    })
+})
+```
+
+## Getting Help
+
+- **Issues**: Open an issue for bugs or feature requests
+- **Examples**: Check the `examples/` folder for reference implementations
+
+Thank you for contributing! 🎉