release: v3.0.0

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml,json}]
+indent_size = 2

.github/ISSUE_TEMPLATE/engineering_task.md

@@ -0,0 +1,29 @@
+---
+name: Engineering task
+title: "[Chore]: "
+about: Internal engineering work — refactoring, tooling, CI, testing infrastructure
+labels: "type: chore"
+assignees: ''
+---
+
+## Objective
+
+What needs to be done and why?
+
+## Scope
+
+Files and areas affected:
+
+-
+
+## Acceptance criteria
+
+- [ ]
+
+## References
+
+Links to related issues, docs, or prior art.
+
+## Additional context
+
+Add any other context here.

.github/pull_request_template.md

@@ -1,5 +1,9 @@
 <!--
-Thank you for contributing! Please fill out the checklist below.
+Thank you for contributing! Please read CONTRIBUTING.md before opening a PR
+(branch naming, commit conventions, dev workflow):
+https://github.com/Rajesh-Royal/Broprint.js/blob/develop/CONTRIBUTING.md
+
+Then fill out the checklist below.
 -->
 
 ## Summary
@@ -16,8 +20,9 @@ Explain the change (what & why).
 
 ## Checklist
 
-- [ ] Code builds locally (npm run build:npm)
-- [ ] Linting/format (if applicable) passes
+- [ ] I have read [CONTRIBUTING.md](../blob/develop/CONTRIBUTING.md)
+- [ ] Code builds locally (`npm run build`)
+- [ ] `npm run lint` and `npm run format:check` pass
 - [ ] Updated documentation (README / docs) if needed
 - [ ] Added tests or explanation why not (project currently lacks tests)
 - [ ] Version bump NOT included (handled by release process)

.github/workflows/ci.yml

@@ -2,23 +2,45 @@ name: CI
 
 on:
   pull_request:
-    branches: [ develop, master ]
+    branches: [develop, master]
   push:
-    branches: [ develop ]
+    branches: [develop]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 5
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [18, 20, 22]
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: ${{ matrix.node-version }}
           cache: 'npm'
       - name: Install deps
         run: npm ci || npm install --no-audit --no-fund
+      - name: Lint
+        run: npm run lint
+      - name: Format check
+        run: npm run format:check
+      - name: Type check
+        run: npx tsc --noEmit
+      - name: Test + coverage
+        run: npm run test:coverage
+      - name: Upload coverage to Codecov
+        if: matrix.node-version == 20
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          flags: unittests
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       - name: Build
         run: npm run build:npm
-      - name: Package size (approx)
-        run: du -sh lib || true
+      - name: Bundle size budget
+        run: npm run size

.gitignore

@@ -1 +1,5 @@
 /node_modules
+/coverage
+/.vscode
+/todo.md
+/docs/api

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.prettierignore

@@ -0,0 +1,8 @@
+lib/
+node_modules/
+example/
+docs/
+coverage/
+.husky/
+package-lock.json
+*.min.js

.prettierrc

@@ -0,0 +1,17 @@
+{
+    "tabWidth": 4,
+    "useTabs": false,
+    "singleQuote": true,
+    "trailingComma": "none",
+    "semi": true,
+    "printWidth": 100,
+    "endOfLine": "lf",
+    "overrides": [
+        {
+            "files": ["*.json", "*.yml", "*.yaml"],
+            "options": {
+                "tabWidth": 2
+            }
+        }
+    ]
+}

CONTRIBUTING.md

@@ -0,0 +1,175 @@
+# Contributing to Broprint.js
+
+Thanks for your interest in improving Broprint.js! This document covers everything you need to get a working dev setup and ship a clean pull request.
+
+## Prerequisites
+
+- **Node.js** `>= 18` (LTS recommended; we test on 18, 20, 22 in CI).
+- **npm** `>= 9` (ships with Node 18.19+). Yarn/pnpm are not used by maintainers, but should also work.
+- A modern browser available for manual testing of canvas/audio fingerprinting (Chromium, Firefox, or WebKit).
+
+## Setup
+
+```sh
+# 1. Fork the repo on GitHub, then clone your fork
+git clone https://github.com/<your-username>/Broprint.js.git
+cd Broprint.js
+
+# 2. Install dependencies (this also installs husky pre-commit hooks via the
+#    `prepare` script — no extra step needed)
+npm install
+
+# 3. Build the package
+npm run build
+```
+
+The build produces ESM, CJS, and IIFE bundles plus type declarations under `lib/`.
+
+## Project structure
+
+```
+.
+├── src/                      Source code (TypeScript)
+│   ├── index.ts              Public API entry — exports getCurrentBrowserFingerPrint
+│   └── code/
+│       ├── EncryptDecrypt.ts        Hash utilities (cyrb53 + reference impls)
+│       ├── FingerPrint.ts           Local-testing driver (not bundled)
+│       ├── GenerateCanvasFingerprint.ts  Canvas-based entropy source
+│       └── generateTheAudioPrints.ts     OfflineAudioContext entropy source
+├── lib/                      Build output (committed; generated by `npm run build`)
+├── example/                  Browser examples consumed by the live demo
+├── docs/                     Static docs site (Netlify)
+├── eslint.config.mjs         ESLint flat config
+├── .prettierrc               Prettier config
+├── .editorconfig             Editor defaults
+├── tsconfig.json             TS compiler options
+└── package.json              Scripts, deps, lint-staged config
+```
+
+## Development workflow
+
+| Task                   | Command                |
+| ---------------------- | ---------------------- |
+| Lint                   | `npm run lint`         |
+| Lint + auto-fix        | `npm run lint:fix`     |
+| Format (Prettier)      | `npm run format`       |
+| Format check           | `npm run format:check` |
+| Type-check + bundle    | `npm run build`        |
+| Type declarations only | `npm run build:types`  |
+| Bundles only           | `npm run build:bundle` |
+| Bundle size budget     | `npm run size`         |
+| Why is the bundle big? | `npm run size:why`     |
+| Generate API docs      | `npm run docs`         |
+
+Typical loop:
+
+1. Create a branch off `develop` (see [Branch naming](#branch-naming)).
+2. Make your change in `src/`.
+3. Run `npm run lint && npm run format:check && npm run build` locally.
+4. Commit — the pre-commit hook will auto-fix staged files via lint-staged.
+5. Push and open a PR against `develop`.
+
+## Code style
+
+Code style is enforced by ESLint + Prettier — **don't waste review cycles on style nits**, the tools handle them:
+
+- `eslint.config.mjs` extends `typescript-eslint/recommended` with a few rules loosened for legacy patterns (see the file for the full list).
+- `.prettierrc` mandates 4-space indent, single quotes, no trailing commas, semis, `printWidth: 100`, LF.
+- A `pre-commit` hook (husky + lint-staged) auto-fixes staged `.ts`/`.tsx` files via ESLint and Prettier. If the hook can't fix something, the commit is blocked.
+
+If you must bypass the hook (rare — for example, a WIP commit on a private branch), use `git commit --no-verify`, but understand that CI will still run the same checks on the PR.
+
+## Testing
+
+The project does **not yet have an automated test suite**; one is being added under issue #32 (Vitest + jsdom). Until then:
+
+- Manually verify changes in `example/` by serving the directory locally and opening it in a browser.
+- For hash logic, you can write a quick Node script that imports `cyrb53` and asserts deterministic output.
+- When the Vitest setup lands, tests will live alongside source as `*.test.ts` and run with `npm test`.
+
+If you're adding non-trivial logic, please at minimum describe how you verified it in your PR description.
+
+## Pull request process
+
+### Branch naming
+
+Use a short, hyphenated prefix that matches the change type:
+
+- `feat/<short-description>` — new feature
+- `fix/<short-description>` — bug fix
+- `chore/<short-description>` — tooling, deps, refactors with no behavior change
+- `docs/<short-description>` — docs only
+
+Example: `chore/husky-lint-staged-contributing`.
+
+### Commit messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>: <short summary>
+
+<optional body explaining the why>
+<optional footer, e.g. "Closes #30">
+```
+
+Allowed types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `build`.
+
+### Opening the PR
+
+1. Push your branch and open a PR **against `develop`** (not `master`).
+2. Fill out the [PR template](.github/pull_request_template.md) — every checkbox matters.
+3. Link the issue you're closing (`Closes #N`).
+4. Keep PRs focused: one concern per PR is much easier to review than a bundled change.
+
+CI will run lint, format check, type-check, and build. Failures must be fixed before review.
+
+## Architecture overview
+
+`getCurrentBrowserFingerPrint()` produces a stable browser identifier by combining two entropy sources and hashing the result:
+
+```
+                    ┌────────────────────────────────┐
+                    │  generateTheAudioFingerPrint   │
+                    │  ────────────────────────────  │
+  Audio entropy ──▶ │  OfflineAudioContext renders   │ ──▶ float sum (string)
+                    │  500 frames (idx 4500-4999)    │
+                    │  through a DynamicsCompressor; │
+                    │  sum |channelData| samples.    │
+                    └────────────────────────────────┘
+                                     │
+                                     ▼  base64 encode
+                    ┌────────────────────────────────┐
+                    │     getCanvasFingerprint       │
+                    │  ────────────────────────────  │
+  Canvas entropy ──▶│  Draw layered text + shapes    │ ──▶ canvas.toDataURL()
+                    │  and read back the data URI    │
+                    │  (varies by GPU / font stack). │
+                    └────────────────────────────────┘
+                                     │
+                                     ▼  concat
+                    ┌────────────────────────────────┐
+                    │           cyrb53               │ ──▶ 53-bit numeric hash
+                    │  (custom, no deps, ~10 lines)  │     coerced to string
+                    └────────────────────────────────┘
+                                     │
+                                     ▼
+                              fingerprint
+```
+
+If audio fingerprinting fails (some browsers block `OfflineAudioContext` in privacy modes), the catch path falls back to a **canvas-only** hash so the function still resolves. It only rejects if both sources fail.
+
+### Design constraints to respect
+
+- **No runtime dependencies.** Bundle size is a feature; the custom `cyrb53` is in-tree precisely to avoid pulling crypto-js.
+- **Bundle size budget: 2 KB brotli per format.** Enforced by `size-limit` (`npm run size`) and CI. Current sizes are well under (~1.0–1.3 KB). If a change needs to bump the budget, justify it in the PR description and bump deliberately.
+- **Deterministic output.** Don't introduce time-, locale-, or network-derived signals. `Date.now()` and randomness break the contract.
+- **Browser-only APIs.** No Node-only modules (`fs`, `path`, etc.) on the import path.
+- **Tree-shake friendly.** Avoid side-effectful top-level code beyond the one global-export shim already in `index.ts`.
+- **Public API stability.** The signature of `getCurrentBrowserFingerPrint` is stable. New options must be additive (an optional `{ ... }` parameter with defaults) and bump the minor version.
+
+For deeper context on AI-assisted contributions, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).
+
+## Questions
+
+Open an issue or discussion on GitHub. Security concerns: see [`SECURITY.md`](SECURITY.md).