feat!: v3 modernization and migration notes

.githooks/pre-commit

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mapfile -t files < <(git diff --cached --name-only --diff-filter=ACM)
+
+if [ ${#files[@]} -eq 0 ]; then
+  exit 0
+fi
+
+format_files=()
+for file in "${files[@]}"; do
+  case "$file" in
+    *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs|*.json|*.jsonc|*.md|*.css|*.html|*.graphql|*.gql|*.yml|*.yaml)
+      format_files+=("$file")
+      ;;
+  esac
+done
+
+if [ ${#format_files[@]} -eq 0 ]; then
+  exit 0
+fi
+
+bunx prettier --write --ignore-unknown -- "${format_files[@]}"
+
+git add -- "${format_files[@]}"

.github/workflows/browser.yml

@@ -0,0 +1,20 @@
+name: Browser Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  browser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: "1.3.1"
+      - name: Install dependencies
+        run: bun install --no-progress --registry https://registry.npmjs.org/
+      - name: Install Playwright browsers
+        run: bunx playwright install --with-deps chromium
+      - name: Browser tests (Playwright)
+        run: bun run test:browser

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: "1.3.1"
+      - name: Install dependencies
+        run: bun install --no-progress --registry https://registry.npmjs.org/
+      - name: Unit tests (Bun)
+        run: bun test --coverage
+      - name: Type tests (tsc)
+        run: bun run typecheck:tests
+      - name: Install Playwright browsers
+        run: bunx playwright install --with-deps chromium
+      - name: Browser tests (Playwright)
+        run: bun run test:browser

.gitignore

@@ -2,4 +2,8 @@
 node_modules
 npm-debug.log
 lib-cov
-test/coverage.html
+coverage
+playwright-report
+tmp/
+bun.lockb
+dist/

.prettierignore

@@ -0,0 +1,13 @@
+# build/artifacts
+node_modules/
+dist/
+coverage/
+playwright-report/
+test-results/
+
+# locks
+bun.lock
+bun.lockb
+
+# misc
+.DS_Store

BENCHMARKS.md

@@ -0,0 +1,21 @@
+# Benchmarks
+
+## Commands
+
+- bun run bench
+- bun run bench:constraints
+- bun run bench:patterns
+- bun run bench:structures
+- bun run bench:node
+- bun run bench:node:constraints
+- bun run bench:node:patterns
+- bun run bench:node:structures
+- bun run bench:browser
+- bun run bench:all
+
+## Environment
+
+- Date: 2026-02-07
+- Bun: 1.3.1
+- Node: 20.x
+- Browser: Playwright Chromium

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 3.0.0 - 2026-02-07
+
+### Breaking Changes
+
+- `generatePassword()` is now async and returns a `Promise<string>`.
+- ESM-only package output (`type: module`); CommonJS `require()` is no longer supported.
+- Node 20+ is required.
+- Defaults are now non-memorable with `length: 12`.
+- Security recommendations enforce a minimum entropy threshold unless `ignoreSecurityRecommendations: true` is set.
+- Legacy UMD/global builds and Bower/Ender integrations were removed.
+
+### Migration (v2 -> v3)
+
+- Update calls to `await generatePassword(...)` or use `generatePasswordWithOptions` with `await`.
+- Switch CommonJS `require()` to ESM `import` and ensure Node 20+.
+- If you used short lengths, restrictive patterns, or memorable mode, handle new security recommendations by increasing length/pattern breadth or passing `ignoreSecurityRecommendations: true`.
+- Update CLI expectations: defaults are non-memorable, `-m` uses a longer length, and `-s/-sN` generates passphrases.
+
+### Added
+
+- TypeScript-first core with strict typing.
+- WebCrypto-based randomness for Node and browser.
+- Deterministic entropy option for tests and simulations.
+- Passphrase mode via `words` (memorable 3-7 letter words).
+- Bun build/test pipeline, type tests, and Playwright browser checks.
+- Benchmark harness and documentation.
+
+### Changed
+
+- CLI now calls the async API and supports secure defaults.
+- CLI adds `-s` / `-sN` for passphrase generation.
+- Build output ships as ESM with explicit exports and declaration files.