# Contributing

Thanks for your interest! This is a small, focused module — contributions that fit
its shape are very welcome, especially anything in the untested columns of the
README's **Status** table (Linux capture and real-app verification, plus additional
Windows/WebView2 configurations).

## Ground rules

- **Stay app-agnostic.** The module (C++ and `src/*.mts`) knows DOM + the generic
  JUCE `__juce__invoke` bridge — never a specific app's selectors, native-function
  names, or page globals. App-specific helpers belong in *your* project as thin
  wrappers over `backend` / `fireBackend` / `readBig` (see the README's
  "Agnostic by design" note).
- **Zero third-party client dependencies.** Generated `tools/*.mjs` must keep working with
  nothing but Node ≥ 22 built-ins — no npm packages. Facts both clients share
  (discovery, NDJSON framing, the default port) live once in `src/shared.mts`;
  don't re-copy them into a client. Edit `src/`, then run `npm run build`; never
  hand-edit the generated `.mjs`/`.d.mts` files under `tools/`.
- **The capture script must never break the page.** Everything in
  `juce_webview_agent_bridge/detail/CaptureScript.h` is wrapped defensively on purpose;
  keep new interceptors fail-silent.
- **Debug-only stays debug-only.** The bridge is gated to `JUCE_DEBUG` via
  `WEB_AGENT_BRIDGE_ENABLED`; nothing may weaken that default or the
  loopback-only bind.
- **Behavior changes need a test.** Both suites run without any host app.

## Running the tests

```bash
# JS client — zero dependencies
npm test

# Maintainer build + public TypeScript API check
npm ci --ignore-scripts
npm run build
npm run test:types

# C++ bridge — fetches JUCE + Catch2 on first configure
cmake -S tests -B build/test          # add -DWAB_JUCE_DIR=/path/to/JUCE to reuse a local checkout
cmake --build build/test
ctest --test-dir build/test --output-on-failure
```

Please run both before opening a PR. CI (`.github/workflows/tests.yml`) runs the
JS suites on Node 22/24 and the C++ suite on macOS, Windows, and Linux — all
required. (Live-app usage on Linux is still unverified — see the README's
**Status** table — but the suites gate every change.)

## Repo layout

- `juce_webview_agent_bridge/` — the JUCE module itself (the directory name must equal the
  module ID, so it is nested rather than being the repo root).
- `src/` — strict TypeScript source for both clients and their shared transport.
- `tools/` — committed JavaScript clients and declarations generated by `npm run build`;
  these are what bare Node and the npm package execute.
- `tests/` — standalone JS (`node:test` vs a mock bridge) and C++ (Catch2 vs the
  real loopback server) suites.
- `skills/juce-webview-agent-bridge/` — the [agent skill](https://skills.sh) teaching a coding
  agent to drive the bridge.

## Protocol changes

The wire protocol (newline-delimited JSON, documented in the README's **Protocol**
table) is consumed by both bundled clients and by third parties. Additive changes
(new ops, new optional fields) are fine — advertise them in the `hello` reply's
`ops` list. Breaking changes need a `protocolVersion` bump and a very good reason.

## Releases (maintainer)

Use the manual **release** workflow in GitHub Actions and choose `patch`, `minor`,
or `major`. It calls the same complete test workflow used by PRs (including C++
on macOS, Windows, and Linux); only after every job passes does it bump all
version sites, commit, tag, create the GitHub Release, and publish the matching
`juce-webview-agent-bridge` package to npm. It also refuses to release if `main`
changed while the tests were running.

The npm package trusts this repository's `release.yml` workflow through npm
Trusted Publishing. GitHub Actions authenticates with short-lived OIDC
credentials, so the release does not use or require an npm access token.

`npm run release [patch|minor|major|X.Y.Z]` remains the underlying maintainer
script for recovery or a deliberate local release. Do not run it in parallel
with the Actions workflow.

## Security

The bridge evaluates arbitrary JS in the host's WebView; the loopback bind is the
trust boundary (see the README's security note). If you find a way to reach the
bridge from off-host or bypass the session token, please report it privately via
GitHub's **Report a vulnerability** (Security tab) rather than a public issue.