Modernize tooling and add VitePress docs

.editorconfig

@@ -0,0 +1,33 @@
+# Defines the coding style for different editors and IDEs.
+# https://editorconfig.org/
+
+# top-most EditorConfig file
+root = true
+
+# Rules for source code.
+[*]
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+max_line_length = 80
+
+[*.{py,pyi}]
+indent_size = 4
+
+# Documentation.
+[*.md]
+max_line_length = 0
+trim_trailing_whitespace = false
+
+# Git commit messages.
+[COMMIT_EDITMSG]
+max_line_length = 0
+trim_trailing_whitespace = false
+
+# Makefiles require tabs.
+[Makefile]
+indent_style = tab
+indent_size = 8

.github/workflows/checks.yml

@@ -1,29 +1,36 @@
 name: Checks
 
 on:
-  pull_request: # push is handled in the deploy workflows
+  push:
+    branches: [main]
+  pull_request:
     branches: ["**"]
   workflow_call:
 
+concurrency:
+  # Skip concurrency restriction when called from another workflow
+  # This prevents deadlocks between parent workflow and this one
+  group:
+    ${{ github.event_name == 'workflow_call' && format('{0}-{1}', github.workflow,
+    github.run_id) || format('{0}-{1}', github.workflow, github.ref) }}
+  cancel-in-progress: true
+
 jobs:
   verify:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        command: [check-types, check-format, lint, test]
+        command: [check-types, check-format, check-lint, test]
     name: ${{ matrix.command }}
-    permissions:
-      contents: read
-      id-token: write
 
     steps:
       - uses: actions/checkout@v4
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
 
       - name: Enable corepack
         run: corepack enable pnpm
@@ -39,15 +46,14 @@ jobs:
         with:
           path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
           key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          # First tries exact match with lock file hash. If not found,
-          # falls back to any cache starting with 'pnpm-store-'.
-          # This way we get exact cache on repeated runs, but can still
-          # use older cache as starting point when dependencies change.
           restore-keys: |
             ${{ runner.os }}-pnpm-store-
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Build
+        run: pnpm build
+
       - name: Run ${{ matrix.command }}
         run: pnpm ${{ matrix.command }}

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Enable corepack
+        run: corepack enable pnpm
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,157 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - prepatch
+          - preminor
+          - premajor
+          - prerelease
+      preid:
+        description: "Prerelease identifier (alpha, beta, rc). Only used with pre* bumps."
+        required: false
+        type: string
+      explicit_version:
+        description: "Explicit version (e.g. 2.0.0-beta.1). Overrides bump and preid when set."
+        required: false
+        type: string
+      dry_run:
+        description: "Dry run — skip publish, push, and release"
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    if: github.ref == 'refs/heads/main' || startsWith(inputs.bump, 'pre') || inputs.explicit_version != ''
+    uses: ./.github/workflows/checks.yml
+
+  publish:
+    if: github.ref == 'refs/heads/main' || startsWith(inputs.bump, 'pre') || inputs.explicit_version != ''
+    needs: checks
+    runs-on: ubuntu-latest
+    # Authentication is handled via OIDC trusted publishing (id-token),
+    # so no NPM_TOKEN secret is needed.
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Enable corepack
+        run: corepack enable pnpm
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        id: version
+        env:
+          BUMP: ${{ inputs.bump }}
+          PREID: ${{ inputs.preid }}
+          EXPLICIT_VERSION: ${{ inputs.explicit_version }}
+        run: |
+          if [[ -n "$EXPLICIT_VERSION" ]]; then
+            npm version "$EXPLICIT_VERSION" --git-tag-version true
+          else
+            ARGS=("$BUMP")
+            if [[ "$BUMP" == pre* && -n "$PREID" ]]; then
+              ARGS+=(--preid "$PREID")
+            fi
+            npm version "${ARGS[@]}" --git-tag-version true
+          fi
+
+          VERSION=$(node -p "require('./package.json').version")
+          TAG="v${VERSION}"
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+
+          if [[ "$VERSION" == *-* ]]; then
+            echo "dist_tag=next" >> $GITHUB_OUTPUT
+            echo "prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "dist_tag=latest" >> $GITHUB_OUTPUT
+            echo "prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish summary
+        run: |
+          echo "### Publish Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Version:** ${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Tag:** ${{ steps.version.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Dist tag:** ${{ steps.version.outputs.dist_tag }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Prerelease:** ${{ steps.version.outputs.prerelease }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Dry run:** ${{ inputs.dry_run }}" >> $GITHUB_STEP_SUMMARY
+
+      # Publish before push: npm publish is not retryable (same version
+      # can't be published twice), while git push is idempotent. If push
+      # fails after a successful publish, it can simply be retried manually.
+      - name: Publish to npm
+        if: ${{ inputs.dry_run == false }}
+        run: |
+          npm publish --provenance --tag ${{ steps.version.outputs.dist_tag }}
+
+      - name: Push version commit
+        if: ${{ inputs.dry_run == false }}
+        run: git push origin HEAD
+
+      - name: Push version tag
+        if: ${{ inputs.dry_run == false }}
+        run: git push origin ${{ steps.version.outputs.tag }}
+
+      - name: Create GitHub Release
+        if: ${{ inputs.dry_run == false }}
+        run: |
+          PRERELEASE_FLAG=""
+          if [[ "${{ steps.version.outputs.prerelease }}" == "true" ]]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --generate-notes \
+            $PRERELEASE_FLAG
+        env:
+          GH_TOKEN: ${{ github.token }}

.gitignore

@@ -1,3 +1,5 @@
 /node_modules
 /dist
 /tsconfig.tsbuildinfo
+docs/.vitepress/cache
+docs/.vitepress/dist

.oxfmtignore

@@ -0,0 +1,2 @@
+dist
+pnpm-lock.yaml

.oxfmtrc.jsonc

@@ -0,0 +1,12 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+}

.oxlintrc.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "perf": "warn"
+  },
+  "rules": {
+    "typescript/no-floating-promises": "error",
+    "typescript/no-misused-promises": "error",
+    "typescript/await-thenable": "error",
+    "typescript/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+    "typescript/no-unsafe-type-assertion": "off",
+    "no-await-in-loop": "off"
+  },
+  "ignorePatterns": ["*.d.ts", "*.d.mts"]
+}