byte-codec 0.0.0 → 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,254 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  commitlint:
+    name: Commitlint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@v6
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      code-quality: write # to upload the cobertura coverage report below
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+
+  test-smoke:
+    name: Smoke test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build && node -e "require('./dist/index.cjs')" && node --input-type=module -e "import('./dist/index.js').then(m => console.log(Object.keys(m).length + ' exports'))"
+
+  release:
+    name: Release
+    needs: [commitlint, lint, typecheck, test, test-smoke]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write # to push the release commit/tag and create the GitHub Release
+      issues: write # to comment on released issues
+      pull-requests: write # to comment on released pull requests
+      id-token: write # OIDC identity for npm trusted publishing (no NPM_TOKEN)
+    outputs:
+      published: ${{ steps.before.outputs.version != steps.after.outputs.version }}
+      version: ${{ steps.after.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # semantic-release analyses the full commit history since the last release.
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+          # registry-url is deliberately absent. Setting it makes setup-node write an .npmrc containing an _authToken line, and that line wins over the OIDC token exchange -- so the setting that looks like it configures the registry is exactly the one that would stop trusted publishing working.
+      - run: pnpm install --frozen-lockfile
+      - name: Read pre-release version
+        id: before
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+      - name: Upgrade npm for OIDC trusted publishing (needs npm CLI >=11.5.1)
+        run: npm install -g npm@latest
+      - name: Release
+        # HUSKY=0 so the commit-msg hook never fires against the automated release commit.
+        run: HUSKY=0 pnpm exec semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Blanked, not omitted -- an inherited NPM_TOKEN/NODE_AUTH_TOKEN from a workflow-level env block, reusable workflow, or composite action would otherwise be used in preference to the OIDC exchange.
+          NPM_TOKEN: ''
+          NODE_AUTH_TOKEN: ''
+      - name: Read post-release version
+        id: after
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
+  notify-downstream:
+    name: Notify downstream repositories
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - name: Generate a token for cross-repo dispatch
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: '4473709'
+          private-key: ${{ secrets.AUTOMERGE_APP_PRIVATE_KEY }}
+          repositories: |
+            documents.js
+      - name: Dispatch sibling-released event to downstream repos
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          version="${{ needs.release.outputs.version }}"
+          for repo in documents.js; do
+            gh api "repos/ExaDev/$repo/dispatches" \
+              -f event_type=sibling-released \
+              -F "client_payload[package]=byte-codec" \
+              -F "client_payload[version]=$version"
+          done
+
+  publish-github-packages:
+    name: Publish alias to GitHub Packages
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main # the release commit semantic-release just pushed
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+          registry-url: 'https://npm.pkg.github.com'
+          # Explicit, not inferred: setup-node's scope default only matches the scoped package.json name if package.json is already scoped by the time this step runs, and the rewrite below happens after it.
+          scope: '@exadev'
+          # GitHub Packages has no OIDC trusted-publishing exchange, so this job (unlike release above) authenticates with a token -- GITHUB_TOKEN is sufficient and needs no separate secret.
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Rewrite package name and registry for the GitHub Packages scope
+        # GitHub Packages requires the npm package name to be scoped to the repo owner. Rewriting the fields rather than keeping a second package.json means this alias cannot drift away from the real package's metadata. publishConfig.registry has to be overridden too: it takes precedence over the .npmrc registry-url set by setup-node above, so without this the publish silently targets registry.npmjs.org instead -- confirmed failure mode, not a hypothetical (404 on the npmjs.org registry, since GITHUB_TOKEN isn't a credential it recognises).
+        run: |
+          npm pkg set name="@exadev/byte-codec"
+          npm pkg set publishConfig.registry="https://npm.pkg.github.com"
+      - run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-aliases:
+    name: Publish aliases (${{ matrix.name }})
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write # OIDC identity for npm trusted publishing -- every leg in this job targets npmjs.org. The GitHub Packages alias is a separate job above specifically so it never holds this permission: pnpm attempts an OIDC exchange whenever id-token: write is available regardless of target registry, and GitHub Packages has no such exchange to attempt -- confirmed the hard way in a sibling repo when this leg used to share that job and failed with "401 Unauthorized - authentication token not provided" even with GITHUB_TOKEN correctly set, because the failed OIDC attempt never fell through to it.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { name: document-bytes, registry: 'https://registry.npmjs.org' }
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main # the release commit semantic-release just pushed
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+          # registry-url is deliberately absent. Setting it makes setup-node write an .npmrc containing an _authToken line, and that line wins over the OIDC exchange -- so the setting that looks like it configures the registry is exactly the one that would break trusted publishing.
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Rewrite package name for this alias
+        # Rewriting the checked-out package.json rather than keeping a package.json per alias means no alias can drift away from the real package's metadata -- each matrix leg gets its own fresh runner and checkout, so there is no cross-contamination between legs.
+        run: npm pkg set name="${{ matrix.name }}"
+      - run: pnpm publish --access public --no-git-checks
+        env:
+          # Blanked, not omitted -- an inherited NODE_AUTH_TOKEN would otherwise be used in preference to the OIDC exchange, matching the release job's own convention above.
+          NODE_AUTH_TOKEN: ''
+
+  attest:
+    name: Attest SBOM and build provenance
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main # the release commit semantic-release just pushed
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      # Pack into a directory of its own, separate from dist/ (tsdown's raw build output). The attestation subject has to be the artefact that actually ships -- attesting dist/ itself would mix in files that never leave the repo, producing digests that match nothing a consumer can download.
+      - run: pnpm pack --pack-destination release-artifact
+      - run: pnpm sbom --sbom-format spdx --prod > release-artifact/sbom.spdx.json
+      # attest-sbom/attest-build-provenance are deprecated wrappers around actions/attest; called as two steps (sbom-path present vs. absent) rather than one, since actions/attest's docs don't clearly state whether passing both together attests SBOM and provenance in a single call or SBOM only -- two steps is the unambiguous equivalent of what this replaced.
+      - name: Attest SBOM
+        uses: actions/attest@v4
+        with:
+          subject-path: release-artifact/*.tgz
+          sbom-path: release-artifact/sbom.spdx.json
+      - name: Attest build provenance
+        uses: actions/attest@v4
+        with:
+          subject-path: release-artifact/*.tgz

package/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,64 @@
+name: Dependabot auto-merge
+
+# Two auto-merge policies in one workflow. Sibling ExaDev packages (document-schema.js) merge unconditionally once green -- no cooldown, matching this family's existing convention. Every other (third-party) dependency merges only for a minor or patch bump; a major bump still opens a PR via Dependabot but is left for manual review. Third-party updates additionally carry dependabot.yml's own 7-day cooldown before Dependabot proposes them at all. Auto-merge is enforced by main's own CI actually passing on the PR's head commit -- this workflow only requests the merge, GitHub itself withholds it until checks conclude. The merge itself authenticates via a GitHub App installation token rather than GITHUB_TOKEN, so the resulting push to main triggers downstream workflow runs (ci.yml, release) instead of being silently skipped by GitHub's anti-recursion protection.
+
+on:
+  # pull_request_target, not pull_request -- a workflow run triggered by dependabot[bot]'s own pull_request
+  # event gets NO secret access at all (a hard GitHub Actions security restriction against a compromised
+  # dependency update exfiltrating secrets), so secrets.AUTOMERGE_APP_PRIVATE_KEY would resolve empty
+  # regardless of how correctly the secret itself is configured. pull_request_target runs using the base
+  # branch's own workflow file and normal secret access instead. Safe here specifically because this job
+  # never checks out or executes the PR's own code -- it only calls the GitHub API (fetch-metadata, gh pr
+  # merge), which is exactly the case pull_request_target's own security guidance calls out as safe.
+  pull_request_target:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+      - name: Decide whether to auto-merge
+        id: decide
+        env:
+          DEPENDENCY_NAMES: ${{ steps.metadata.outputs.dependency-names }}
+          UPDATE_TYPE: ${{ steps.metadata.outputs.update-type }}
+        run: |
+          siblings="document-schema.js"
+          is_sibling=false
+          for name in $(echo "$DEPENDENCY_NAMES" | tr ',' ' '); do
+            name=$(echo "$name" | xargs)
+            for sib in $siblings; do
+              if [ "$name" = "$sib" ]; then
+                is_sibling=true
+              fi
+            done
+          done
+          if [ "$is_sibling" = "true" ]; then
+            echo "merge=true" >> "$GITHUB_OUTPUT"
+          elif [ "$UPDATE_TYPE" = "version-update:semver-minor" ] || [ "$UPDATE_TYPE" = "version-update:semver-patch" ]; then
+            echo "merge=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "merge=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Generate a token for the merge
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: "4473709"
+          private-key: ${{ secrets.AUTOMERGE_APP_PRIVATE_KEY }}
+      - name: Enable auto-merge
+        if: steps.decide.outputs.merge == 'true'
+        run: gh pr merge --auto --rebase "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}

package/.github/workflows/sibling-dependency-update.yml

@@ -0,0 +1,174 @@
+name: Sibling dependency instant update
+
+# Triggered the moment a sibling ExaDev package this repo depends on publishes a new version -- the publishing repo own ci.yml sends this repository_dispatch event right after semantic-release completes, instead of waiting for Dependabot own daily scheduled scan to notice. Bumps the named dependency, opens a PR, and requests auto-merge. The branch push and the PR-open call both authenticate via a freshly-minted GitHub App installation token, not the default GITHUB_TOKEN -- GITHUB_TOKEN-authenticated actions (a push OR opening a PR) do not cascade into further workflow runs, so a GITHUB_TOKEN-created PR would never trigger this repo own ci.yml pull_request checks at all, leaving nothing for auto-merge to wait on and letting GitHub treat the PR as already mergeable the instant it opens. Even with the App token making that cascade happen for real, there is a second, narrower race: GitHub can take a few seconds to actually register ci.yml own check-runs against the new PR, and calling gh pr merge --auto before any check has registered gets rejected with "Pull request is in clean status" -- confirmed happening in production even after the App-token fix landed. The wait step below polls for ci.yml own Test check-run to actually appear before requesting auto-merge, closing that race. This workflow never pushes directly to main -- the PR still only merges once this repo own CI genuinely passes on it. Note: every repo in this family also enforces a minimumReleaseAge pnpm supply-chain gate (see pnpm-workspace.yaml); pnpm add itself can refuse to install a version published within that window, in which case this workflow run fails cleanly and the bump is left for Dependabot own next daily scan to pick up once the window has passed -- a neutral fallback, not a regression, since that scan would have handled it anyway.
+
+on:
+  repository_dispatch:
+    types: [sibling-released]
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  bump-and-open-pr:
+    if: github.event_name == 'repository_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - name: Bump the released dependency
+        env:
+          PACKAGE: ${{ github.event.client_payload.package }}
+          VERSION: ${{ github.event.client_payload.version }}
+        run: pnpm add "$PACKAGE@$VERSION"
+      - name: Check whether anything actually changed
+        id: diff
+        run: |
+          if git diff --quiet -- package.json pnpm-lock.yaml; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Generate a token for the branch push and PR
+        if: steps.diff.outputs.changed == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: '4473709'
+          private-key: ${{ secrets.AUTOMERGE_APP_PRIVATE_KEY }}
+      - name: Commit and open a PR
+        if: steps.diff.outputs.changed == 'true'
+        id: pr
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          PACKAGE: ${{ github.event.client_payload.package }}
+          VERSION: ${{ github.event.client_payload.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="sibling-update/${PACKAGE}-${VERSION}"
+          git checkout -b "$branch"
+          git add package.json pnpm-lock.yaml
+          body=$(printf 'Triggered instantly via repository_dispatch when %s published its own release,\nrather than waiting for the next scheduled Dependabot scan.' "$PACKAGE")
+          git commit -m "build(deps): bump ${PACKAGE} to ${VERSION}" -m "$body"
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
+          git push origin "$branch"
+          pr_url=$(gh pr create --title "build(deps): bump ${PACKAGE} to ${VERSION}" --body "Automatic dependency bump triggered instantly by the ${PACKAGE} release." --base main --head "$branch")
+          echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "head_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+      - name: Wait for this repo own real CI to register on the PR
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          for i in $(seq 1 30); do
+            found=$(gh api "repos/${{ github.repository }}/commits/${{ steps.pr.outputs.head_sha }}/check-runs" --jq '[.check_runs[] | select(.name == "Test")] | length')
+            if [ "$found" -gt 0 ]; then
+              echo "ci.yml own Test check has registered after $((i * 3))s"
+              exit 0
+            fi
+            sleep 3
+          done
+          echo "::warning::ci.yml own Test check never registered after 90s -- proceeding anyway, but auto-merge may reject the PR as already clean or merge it immediately" >&2
+      - name: Enable auto-merge
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: gh pr merge --auto --rebase "${{ steps.pr.outputs.pr_url }}"
+
+  heal-stranded-prs:
+    # gh pr merge --auto above only ever fires once, right after a PR opens. If enough other commits land on main before this repo's own CI finishes on that PR, the PR's branch falls behind and GitHub marks it CONFLICTING -- and a conflicting PR can never auto-merge, no matter how green its own CI is, with nothing to ever retry it. This job runs on every push to main (the only time a previously-clean PR can newly become conflicting) and regenerates any bump PR this same workflow opened that is now stuck: closes the stale PR/branch and re-runs the identical bump against the new main, rather than attempting a real git rebase -- a plain `pnpm add <package>@<version>` is fully idempotent and deterministic, so there is no conflict to resolve, only a fresh diff to produce.
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+      - name: Generate a token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: '4473709'
+          private-key: ${{ secrets.AUTOMERGE_APP_PRIVATE_KEY }}
+      - name: Regenerate every conflicting sibling-update PR
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
+
+          # gh pr list's own `mergeable` field never computes a real value (always reports UNKNOWN) -- only a per-PR `gh pr view` triggers GitHub's own mergeable-status computation, and even that is asynchronous. So list candidates in bulk (reliable), then poll each one individually until its real status resolves.
+          candidates=$(gh pr list --state open --json number,headRefName \
+            --jq '[.[] | select(.headRefName | startswith("sibling-update/"))] | .[]')
+          if [ -z "$candidates" ]; then
+            echo "No open sibling-update PRs found."
+            exit 0
+          fi
+
+          echo "$candidates" | jq -c '.' | while read -r entry; do
+            number=$(echo "$entry" | jq -r '.number')
+            branch=$(echo "$entry" | jq -r '.headRefName')
+
+            mergeable="UNKNOWN"
+            for _attempt in $(seq 1 10); do
+              mergeable=$(gh pr view "$number" --json mergeable --jq '.mergeable')
+              if [ "$mergeable" != "UNKNOWN" ]; then
+                break
+              fi
+              sleep 3
+            done
+
+            if [ "$mergeable" != "CONFLICTING" ]; then
+              echo "PR #${number} (${branch}) is ${mergeable}, not stranded -- skipping."
+              continue
+            fi
+
+            package_version="${branch#sibling-update/}"
+            package="${package_version%-*}"
+            version="${package_version##*-}"
+            echo "Regenerating stranded PR #${number} (${branch}) for ${package}@${version}"
+
+            gh pr close "$number" --comment "Regenerating -- this branch fell behind main and could no longer auto-merge."
+
+            git fetch origin main
+            git checkout -B "$branch" origin/main
+            pnpm add "${package}@${version}"
+
+            if git diff --quiet -- package.json pnpm-lock.yaml; then
+              echo "main already has ${package}@${version} or newer -- nothing left to bump."
+              continue
+            fi
+
+            git add package.json pnpm-lock.yaml
+            git commit -m "build(deps): bump ${package} to ${version}"
+            git push --force origin "$branch"
+            pr_url=$(gh pr create --title "build(deps): bump ${package} to ${version}" \
+              --body "Regenerated automatically after the original PR fell behind main." \
+              --base main --head "$branch")
+            head_sha=$(git rev-parse HEAD)
+
+            for _attempt in $(seq 1 30); do
+              found=$(gh api "repos/${{ github.repository }}/commits/${head_sha}/check-runs" \
+                --jq '[.check_runs[] | select(.name == "Test")] | length')
+              if [ "$found" -gt 0 ]; then
+                break
+              fi
+              sleep 3
+            done
+
+            gh pr merge --auto --rebase "$pr_url"
+          done

package/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm exec commitlint --edit "$1"

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+# Lint and auto-fix staged TypeScript files.
+pnpm exec lint-staged

package/.husky/pre-push

@@ -0,0 +1,2 @@
+# Run the full test suite before push to catch breakage early.
+pnpm test

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 1.0.0 (2026-08-05)
+
+
+### Bug Fixes
+
+* ci test and smoke steps for byte-codec's script set ([a64531d](https://github.com/ExaDev/byte-codec/commit/a64531df7cec8969ffe2f99cb4b100020b549ad4))
+* ci yaml — remove stray key, fix job name, correct alias ([c1c6291](https://github.com/ExaDev/byte-codec/commit/c1c629166831899be2b07f761fafdd130babbe78))
+
+
+### Features
+
+* initial byte-codec package — generic byte/image utilities ([698c6ab](https://github.com/ExaDev/byte-codec/commit/698c6abd755e72e40759569a3ffa6b0f2f5d9f21))

package/README.md

@@ -0,0 +1,43 @@
+# byte-codec
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/byte-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/byte-codec) [![Release](https://img.shields.io/github/v/release/ExaDev/byte-codec)](https://github.com/ExaDev/byte-codec/releases/latest)
+
+> Generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate) and PNG/JPEG image encoding/decoding with zero PDF knowledge — the shared utility package for the documents.js family.
+
+Extracted from [pdf-codec](https://github.com/ExaDev/pdf-codec), where these utilities lived as a directory-isolated subgraph under `src/bytes/` + `src/image/` with no PDF imports. Both pdf-codec and documents.js consume them from this neutral home rather than one fetching byte utilities from a backend.
+
+## Getting started
+
+Requires Node.js `>=20` and pnpm `11.6.0`.
+
+```sh
+pnpm install
+pnpm build      # tsdown -> dist/ (ESM + CJS + .d.ts)
+pnpm test       # vitest
+pnpm typecheck  # tsc --noEmit
+```
+
+## What it provides
+
+| Module | Exports |
+|---|---|
+| `bytes/writer` | `ByteWriter` (chunked growable byte-output builder), `concatBytes` |
+| `bytes/reader` | `ByteReader` (sequential big/little-endian byte reader), `isAsciiWhitespace` |
+| `bytes/crc32` | `crc32` (IEEE 802.3 / ZIP / PNG polynomial table-driven CRC-32) |
+| `bytes/flate` | `deflate`, `inflate`, `inflateTolerant` (fflate-backed DEFLATE compression/decompression with a safety cap) |
+| `image/png-encode` | `encodePng` (raw RGB/RGBA pixels → PNG bytes) |
+| `image/png-decode` | `decodePng` (PNG bytes → raw pixels), `RawImage` |
+| `image/png-filter` | `filterScanlines`, `unfilterScanlines` (the five PNG scanline filters) |
+| `image/jpeg-info` | `readJpegInfo` (JPEG header reader: dimensions, components, progressive flag — no sample decoding) |
+
+## Install
+
+```sh
+pnpm add byte-codec
+# or
+npm install byte-codec
+```
+
+## License
+
+MIT

package/commitlint.config.ts

@@ -0,0 +1,8 @@
+import { commitTypes } from './release.config';
+
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [2, 'always', commitTypes.map((t) => t.type)],
+  },
+};

package/eslint.config.ts

@@ -0,0 +1,19 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: { ...globals.node },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+);

package/package.json

@@ -1,5 +1,66 @@
 {
   "name": "byte-codec",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.0",
+  "description": "Generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate) and PNG/JPEG image encoding/decoding with zero PDF knowledge — the shared utility package for the documents.js family.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/byte-codec.git"
+  },
+  "homepage": "https://github.com/ExaDev/byte-codec#readme",
+  "bugs": {
+    "url": "https://github.com/ExaDev/byte-codec/issues"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": {
+        "import": "./dist/*.d.ts",
+        "require": "./dist/*.d.cts"
+      },
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --fix --cache --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "husky",
+    "lint:check": "eslint . --max-warnings 0"
+  },
+  "packageManager": "pnpm@11.6.0",
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.8.0",
+    "globals": "^17.8.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.2.0",
+    "semantic-release": "^25.0.8",
+    "tsdown": "^0.12.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  },
+  "lint-staged": {
+    "*.ts": "eslint --fix"
+  }
 }