Dev

.eslintignore

@@ -0,0 +1,6 @@
+# The example apps carry their own eslint configs and their own node_modules.
+# Linting them from the library root fails on configs that aren't installed here.
+examples/
+
+dist/
+node_modules/

.eslintrc.json

@@ -1,4 +1,9 @@
 {
+    "root": true,
+    "ignorePatterns": [
+        "dist/",
+        "examples/"
+    ],
     "env": {
         "browser": true,
         "es2021": true,
@@ -7,6 +12,7 @@
     "extends": [
         "eslint:recommended",
         "plugin:react/recommended",
+        "plugin:react-hooks/recommended",
         "plugin:@typescript-eslint/recommended"
     ],
     "parser": "@typescript-eslint/parser",
@@ -19,6 +25,7 @@
     },
     "plugins": [
         "react",
+        "react-hooks",
         "@typescript-eslint"
     ],
     "settings": {

.github/workflows/ci.yml

@@ -2,35 +2,71 @@ name: CI
 on:
   push:
     branches:
+      # `main` must stay here: release.yml is gated on a successful CI run for
+      # main, so dropping it would leave releases unable to ever fire.
       - main
+      - dev
   pull_request:
 
 jobs:
-  lint:
+  verify:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 9
+      # No `version:` — action-setup reads the `packageManager` field in
+      # package.json, so CI cannot drift from the lockfile's pnpm major.
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
           cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
-      - run: pnpm lint
-      # - run: pnpm tsc --noEmit # Uncomment when strict mode is fully clean
 
-  test:
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      # Coverage thresholds live in jest.config.js and fail the build when a
+      # change drops below them.
+      - name: Unit tests with coverage gate
+        run: pnpm test:coverage
+
+      - name: Build
+        run: pnpm build
+
+  # Separate job: it needs a browser and the example app, and it is the only
+  # place the HttpOnly claim is checked against a real browser.
+  e2e:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 9
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
           cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
-      - run: pnpm test
+
+      # The example depends on the library by path, so it must be built first.
+      - name: Build library
+        run: pnpm build
+
+      - name: Install example dependencies
+        run: pnpm install --dir examples/next-js --no-frozen-lockfile
+
+      - name: Install Playwright browser
+        run: pnpm exec playwright install chromium --with-deps
+
+      - name: End-to-end tests
+        run: pnpm test:e2e
+        env:
+          AUTH_SECRET: e2e-test-secret-at-least-32-characters!!
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: test-results/
+          retention-days: 7

.github/workflows/release.yml

@@ -1,6 +1,12 @@
 name: Release
+
+# Gated on CI. `needs:` only works inside a single workflow, so this waits for
+# the CI run on main to finish and refuses to publish unless it went green.
 on:
-  push:
+  workflow_run:
+    workflows: ['CI']
+    types:
+      - completed
     branches:
       - main
 
@@ -12,22 +18,55 @@ permissions:
 
 jobs:
   release:
+    if: github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
+          # Full history and tags: the guard below needs to see existing tags,
+          # and the changelog is generated from commit history.
           fetch-depth: 0
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 9
+          ref: main
+
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
-      - run: git config --global user.name "github-actions[bot]"
-      - run: git config --global user.email "github-actions[bot]@users.noreply.github.com"
-      - run: pnpm release-it --ci
+
+      # This workflow fires on every successful CI run on main, but the version
+      # only changes when someone bumps it. Without this guard every later merge
+      # would try to republish the same version and fail.
+      - name: Has this version already been released?
+        id: check
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "v$VERSION is already tagged — nothing to release."
+          else
+            echo "released=false" >> "$GITHUB_OUTPUT"
+            echo "v$VERSION is not tagged yet — releasing."
+          fi
+
+      - name: Configure git identity
+        if: steps.check.outputs.released == 'false'
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      # `--no-increment` publishes exactly the version in package.json rather
+      # than deriving one from commit messages, so the released version is
+      # whatever the committed manifest says and nothing else.
+      #
+      # `prepublishOnly` re-runs lint, typecheck, tests and build before the
+      # tarball is uploaded, so a broken tree cannot reach npm.
+      - name: Release v${{ steps.check.outputs.version }}
+        if: steps.check.outputs.released == 'false'
+        run: pnpm release-it --ci --no-increment
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,4 +1,28 @@
-npm-debug.log
+# dependencies
 node_modules
+
+# build output
 build/*
 dist
+
+# caches
+.jest-cache
+*.tsbuildinfo
+coverage
+
+# playwright
+test-results
+playwright-report
+.playwright
+
+# next.js (examples)
+.next
+.env.local
+
+# logs
+npm-debug.log
+yarn-error.log
+*.log
+
+# os / editor
+.DS_Store