diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..bafa512 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ + + +See [AGENTS.md](../AGENTS.md) for project overview, setup, commands, coding conventions, testing, CI/CD, pull request workflow, and AI agent context. diff --git a/.github/instructions/ci-cd.instructions.md b/.github/instructions/ci-cd.instructions.md new file mode 100644 index 0000000..7f17984 --- /dev/null +++ b/.github/instructions/ci-cd.instructions.md @@ -0,0 +1,35 @@ +--- +applyTo: ".github/workflows/**" +name: webrtc-core CI/CD +description: Use when analyzing or changing GitHub Actions workflows or semantic-release publish configuration. +--- + +# CI/CD Instructions — webrtc-core + +Read the current files under `.github/workflows/` before analyzing or modifying CI configuration. + +## Pipeline (GitHub Actions) + +- **Pull requests:** `.github/workflows/pull-request-checks.yml` — checkout, Node (see workflow for version), `yarn install`, `yarn test:lint`, `yarn test:coverage` (Jest). +- **Main branch:** `.github/workflows/npm-publish.yml` — `yarn build`, then `npx semantic-release` with registry tokens from GitHub secrets (never log or commit tokens). + +Node version in workflows should stay aligned with `.nvmrc` when you change either. + +## Release + +- semantic-release runs on **`main`** after merge (publish workflow). +- Next version comes from **conventional commit** types on merged commits. +- Publishes `@webex/webrtc-core` to the npm public registry. +- Release may update generated files (`CHANGELOG.md`, `package.json`, lockfile) via semantic-release plugins. + +## Failure triage + +- **Lint or Jest failure in a PR** — fix code or tests; do not rerun hoping for green. +- **Infra failure** (runner, registry, transient network) — rerun after infra is healthy. +- **Release failure on main** — treat as an incident; do not publish locally without coordination. + +## Safety + +- Never expose or log CI secrets (`CI_TOKEN`, `NPM_TOKEN`, `GITHUB_TOKEN`). +- Only rerun for infrastructure failures, not code failures. +- Do not run `yarn release` / `semantic-release` locally unless intentionally publishing with team approval. diff --git a/.github/instructions/code-review.instructions.md b/.github/instructions/code-review.instructions.md new file mode 100644 index 0000000..8a7571a --- /dev/null +++ b/.github/instructions/code-review.instructions.md @@ -0,0 +1,26 @@ +--- +applyTo: "src/**/*.ts" +name: webrtc-core Code Review +description: Use when reviewing or preparing changes under src/ — correctness, public API, PeerConnection lifecycle, local streams, events, and media-effects integration. +--- + +# Code Review Instructions — webrtc-core + +When reviewing changes in `src/`: + +## Priorities + +1. Correctness — edge cases, error paths handled (especially getUserMedia, track lifecycle, constraint handling). +2. Public API — additions/removals in `src/index.ts` noted with semver impact. +3. Browser quirks — adapter, permissions API differences (Firefox/Safari), fake-device test assumptions. +4. Event contracts — no silent removal/rename of typed events on streams and `PeerConnection`. +5. Media effects integration — changes to effect processors and effect lifecycle handling must stay consistent with `@webex/web-media-effects` contracts. + +## Checks + +- JSDoc present on all new/modified functions, classes, methods (enforced by ESLint). +- No `any` without documented reason. +- No swallowed errors without explicit justification. +- Unit tests (`*.spec.ts`) added/updated for behavioral changes; consider Karma integration tests for real-browser capture paths when behavior is browser-specific. +- Comments explain *why*, not *what*. No ticket IDs or dates in code comments. +- No secrets, absolute paths, `.pem`, or `.env` values in the diff. diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md new file mode 100644 index 0000000..35a22be --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,44 @@ +--- +applyTo: "src/**/*.spec.ts" +name: webrtc-core Unit Tests +description: Use when writing or reviewing Jest unit tests co-located with source under src/. +--- + +# Testing Instructions — webrtc-core (Jest) + +When writing or reviewing **unit** tests in `src/**/*.spec.ts`: + +## Framework + +- Jest + ts-jest use the jsdom environment. Authoritative versions and options live in `package.json` and `jest.config.js`; check those files instead of assuming versions here. +- Co-located `*.spec.ts` files alongside source. +- Mocks: `src/mocks/` (RTCPeerConnection, MediaStream, navigator, etc.). + +## Integration tests (Karma + Mocha) + +- Browser integration tests use **`*.integration-test.ts`** and Karma (`karma.conf.js`). +- `yarn test` uses the `test:*` pattern and includes all four Karma integration scripts. Run individual test scripts when you do not want to run browser integration tests. +- Run local integration tests with `yarn test:integration:chrome`; the local Karma configuration always launches Chrome through Puppeteer. +- The Firefox, Edge, and Safari scripts select their named browser matrices only when `SAUCE=true` and valid Sauce Labs credentials are provided. Without Sauce, those scripts also launch local Chrome and must not be treated as validation in the named browser. +- The checked-in pull request workflow runs Jest coverage, not Karma. Run relevant Karma tests locally when changing browser capture, permissions, or media behavior. + +## Patterns + +- `describe` blocks named after the module/class under test. +- `it` blocks with descriptive scenario + expected outcome. +- `expect.assertions(n)` for async tests when the repo already uses it in that file. +- Mock at boundaries (`jest.mock` for factories and stubs under `src/mocks/`). +- `clearMocks: true` in `jest.config.js` clears mock calls, instances, contexts, and results before each test. It does not restore changed implementations or return values; tests that replace them must restore or reset them explicitly. + +## Naming + +- Files: **`kebab-case.spec.ts`** next to `kebab-case.ts`. +- Prefer **`should …`** phrasing for new tests unless extending a file with an established style. +- Integration files: **`*.integration-test.ts`** (see `src/media.integration-test.ts`). + +## Rules + +- GitHub Actions / team CI results are authoritative over local-only runs when they disagree. +- Bug fixes should include or extend a regression test when behavior changed. +- Tests must be independent — no shared mutable state between tests. +- Allowed hooks: `beforeAll`, `beforeEach`, `afterAll`, `afterEach` (ESLint `jest/no-hooks`). diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index cb90cc9..f60d257 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,5 @@ ## Description - + ## This change implements... - [ ] A new feature diff --git a/.github/skills/pr-description/SKILL.md b/.github/skills/pr-description/SKILL.md new file mode 100644 index 0000000..6f9f845 --- /dev/null +++ b/.github/skills/pr-description/SKILL.md @@ -0,0 +1,49 @@ +--- +name: pr-description +description: Draft accurate webrtc-core pull request descriptions from the repository template and committed changes. Use when creating, updating, or reviewing a PR description for this repository. +--- + +# PR Description + +Create a concise PR description that helps reviewers understand the change and verify it. + +## Sources + +Read these before drafting: + +1. `.github/pull_request_template.md` +2. The complete committed branch diff against the PR base branch +3. Branch commits +4. Test output supplied by the author or produced in the current session +5. Linked public issues or design context when available + +Repository files and observed test results are authoritative. Do not invent motivation, test evidence, issue links, screenshots, or compatibility claims. + +## Workflow + +1. Confirm the PR base branch. Use `main` when no other base is specified. +2. Review the complete diff, not only the latest commit. +3. Check `git status`. If uncommitted changes exist, warn the author and exclude them from the PR description until they are committed. +4. Identify the change type and whether public API, browser behavior, media lifecycle, or compatibility changes. +5. Before drafting the final description, ask what manual testing was performed. Request the tested scenario, browser when relevant, and result. If no manual testing was needed, ask the author to confirm why. +6. Ask only for other facts that cannot be derived, such as a public issue link, screenshots, or the GAI usage category. +7. Produce the completed repository template without removing headings or policy checkboxes. + +## Description Rules + +- Start with one to three bullets explaining what changed and why. +- Describe the behavior or developer outcome rather than listing files. +- Link a relevant public issue when available. +- Add a short `Testing` subsection under `Description` with commands and manual checks that actually ran. +- Mention breaking changes, migration steps, public API impact, dependency pin changes, or downstream version bumps only when the diff requires it. +- Include screenshots only for visible UI changes. +- Keep unchecked boxes when the answer is unknown. +- Never mark the test certification checkbox without evidence. +- Never choose a GAI disclosure category for the author. +- Do not add a dedicated risk assessment section. + +## Output + +Return the proposed PR description as one Markdown block that can be pasted into GitHub. + +After the block, list unresolved author questions separately. Do not place placeholders such as `TBD` inside an otherwise final description. diff --git a/.gitignore b/.gitignore index 069ee71..cc35d19 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ dist .idea/ coverage/ .scannerwork/ +docs/temp/ +docs/api-reference/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0a7992 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,245 @@ +# AGENTS.md + +## Project Overview + +`@webex/webrtc-core` is an open-source TypeScript library of reusable browser WebRTC primitives. It wraps `RTCPeerConnection`, models local and remote media streams, provides device and permission helpers, and connects local streams to `@webex/web-media-effects`. + +The public [Webex JS SDK](https://github.com/webex/webex-js-sdk) exposes application-facing meetings and media APIs. This repository documents only webrtc-core's browser primitives and direct dependencies, not private application implementation paths. + +New contributors should use this file for setup, development, testing, and contribution guidance. For the package's place in the wider media stack, start with the [knowledge base](docs/knowledge-base/README.md). + +## General Guidelines + +- Be analytical, straightforward, and technical. No fluff or overly agreeable responses. +- Derive commands, versions, and conventions from this repository's checked-in files — do not guess. +- For stack and onboarding questions, read the [knowledge base](docs/knowledge-base/README.md) before wide repository searches. +- When a plan or approach is ready, present it to the user and wait for confirmation before executing large or irreversible changes. +- When guidance conflicts, this repository's configuration, scripts, and policy files win. + +## Agent Rules (Interactive Sessions) + +These rules apply to interactive (terminal / IDE) agent sessions only. + +1. Statements backed by evidence should cite a repository path, config key, or stable public link so a human can verify. +2. Never commit secrets, credentials, `.pem` files, or decrypted `.env` values. +3. Do not copy content from private systems, private URLs, hostnames, or internal identifiers into the repository. Use a sanitized summary instead. + +### Committing files (agents) + +- Never use `git add .` or `git add -A`. Stage **explicit paths** only. +- Stage **only files you created or modified in this session**. Do not include pre-existing untracked or unrelated changes, such as local notes, keys, or scratch Markdown at the repository root. +- Before every commit, run `git status` and confirm no `*.pem`, `.env`, keys, or credentials are staged. Use `git restore --staged ` if the wrong files appear. +- Create commits **only when the user asks** (unless their tooling rules say otherwise). + +### Knowledge base (`docs/knowledge-base/`) + +**What it is:** Curated, repository-local notes for agents and contributors, including architecture summaries, dependency roles, and links to deeper sources. It is separate from generated API documentation. + +**When to read it (before heavy searching):** + +- Questions about webrtc-core’s **public scope** or **media-effects boundary**. +- **Onboarding-style** “how does this repo fit together?” or “which module handles X?” +- You need a **map of modules or dependencies**. Open [architecture/webrtc-core-overview.md](docs/knowledge-base/architecture/webrtc-core-overview.md) through the [knowledge base index](docs/knowledge-base/README.md). + +**When code wins:** Implementation details, dependency pins, and scripts live in source and `package.json`. If the knowledge base and code disagree, trust the repository and correct the knowledge base. + +**Optional growth:** After answering a repeatable research question, ask the user whether they want a short article under `docs/knowledge-base/architecture/`, linked from [docs/knowledge-base/README.md](docs/knowledge-base/README.md). Do not add or rewrite knowledge base files without agreement. + +## Maintaining this file + +Keep `AGENTS.md`, scoped instructions, and repository skills aligned with checked-in facts. + +**Update in the same PR when you change:** `package.json` scripts or dependency pins, `.nvmrc`, `packageManager`, ESLint, Prettier, Jest, Karma, Rollup, release configuration, `.github/workflows/`, or the public API in `src/index.ts`. + +**Also refresh when:** A release changes documented dependency relationships. + +**How:** Edit these files directly in the webrtc-core repository. Do not reference external authoring workspaces inside committed files. + +If this document disagrees with `package.json`, workflows, or source code, **the repository wins**. Correct this document and remove rules that no longer apply. + +**Last verified:** 2026-08-10. + +## Repository layout + +``` +webrtc-core/ ← package root (@webex/webrtc-core) +├── src/ ← TypeScript source + co-located tests +├── dist/ ← build output (ESM, CJS, UMD, types) +├── docs/api-reference/ ← generated API Markdown (not committed) +├── docs/contributing/ ← maintained contribution guidance +├── docs/knowledge-base/ ← maintained architecture context +├── .github/workflows/ ← GitHub Actions (PR checks, publish) +├── package.json +├── tsconfig.json +├── rollup.config.js +├── jest.config.js +├── karma.conf.js +└── cspell.json +``` + +## Setup + +```bash +nvm install # Node version from .nvmrc +corepack enable # enables the package manager declared by package.json +yarn install # from repo root +``` + +Use Yarn for repository commands. The required package manager and version are defined by `engines` and `packageManager` in `package.json`. + +## Development commands + +Run from the repo root: + +| Command | Purpose | +|---|---| +| `yarn build` | Production build (clean + rollup) | +| `yarn test` | Sequential build plus every `test:*` script, including all four Karma integration commands | +| `yarn test:unit` | Jest unit tests only | +| `yarn test:coverage` | Jest with coverage (matches PR CI) | +| `yarn test:lint` | ESLint on `src/` | +| `yarn test:prettier` | Prettier check on `src/**/*.ts` | +| `yarn test:spelling` | cspell for source and contributor documentation | +| `yarn test:integration:chrome` | Karma integration tests in local Chrome via Puppeteer | +| `yarn test:integration:firefox` | Firefox matrix on Sauce Labs when `SAUCE=true`; otherwise local Chrome | +| `yarn test:integration:edge` | Edge matrix on Sauce Labs when `SAUCE=true`; otherwise local Chrome | +| `yarn test:integration:safari` | Safari matrix on Sauce Labs when `SAUCE=true`; otherwise local Chrome | +| `yarn transpile:validate` | TypeScript type check (`tsc --noEmit`) | +| `yarn fix` | Auto-fix prettier + eslint | +| `yarn watch` | Rollup watch mode | + +Reproduce PR CI locally: `yarn test:lint` and `yarn test:coverage` after `yarn install`. + +## Coding conventions + +### TypeScript + +- TypeScript strict mode, `noImplicitAny`, `strictNullChecks`, and `noImplicitReturns` are enabled. +- The compilation target and module format are defined in `tsconfig.json`. + +### Formatting and lint + +- Prettier uses a 100-character print width, single quotes, two-space indentation, and ES5 trailing commas. See `.prettierrc`. +- ESLint combines Airbnb Base, TypeScript, Jest, JSDoc, and Prettier rules. See `.eslintrc.js`. +- Staged TypeScript files run Prettier, ESLint with zero warnings, and cspell through `lint-staged`. + +### Naming + +- Files: `kebab-case.ts`. Unit tests: `kebab-case.spec.ts` (co-located). +- Integration tests: `*.integration-test.ts` (Karma). +- Classes: PascalCase. + +### JSDoc + +JSDoc is enforced by ESLint on functions, classes, and methods: + +- Full-sentence description. +- `@param name - description` (hyphen before param description). +- `@returns` for return values. + +### Error handling + +- Use domain errors from `errors.ts` where applicable. +- Never swallow errors silently without explicit, documented reason. + +### Events + +- Typed patterns via `event-emitter.ts` and `@webex/ts-events` where used. +- Preserve event names and payloads when changing public stream or connection classes. + +### Imports + +- No file extensions in TypeScript imports (ESLint `import/extensions`). + +## Key dependencies + +`@webex/web-media-effects` is an **exact pin** in `package.json`. See the [architecture overview](docs/knowledge-base/architecture/webrtc-core-overview.md) for its direct role. Any version change must be intentional, compatibility-tested, and called out in the pull request. + +## Testing + +- **Unit:** Jest + ts-jest, jsdom — see `package.json` and `jest.config.js`. +- **Integration:** Karma + Mocha + `karma-typescript` — see `karma.conf.js` and `*.integration-test.ts`. +- **Location:** Co-located specs under `src/`; mocks in `src/mocks/`. +- **Run:** Use `yarn test:unit` for fast feedback. `yarn test` expands `test:*`, so it runs lint, Prettier, spelling, unit tests, coverage, and every Karma integration script; it is not a non-integration-only check. +- **Non-integration validation:** Run the required build, lint, Prettier, spelling, unit, or coverage scripts explicitly. There is no single non-integration aggregate script. +- **Cross-browser:** Firefox, Edge, and Safari are selected only with `SAUCE=true` and valid Sauce Labs credentials. Without Sauce, every integration script launches local Chrome, regardless of the browser suffix. + +Path-scoped detail: `.github/instructions/testing.instructions.md`. + +## Code review priorities + +1. **Correctness** — capture, track stop/replace, constraint and effects edge cases. +2. **Public API changes** — exports in `src/index.ts` have semver impact. +3. **Browser differences** — permissions, adapter, Safari/Firefox quirks. +4. **Event contracts** — no silent breaking changes on streams or `PeerConnection`. +5. **Media effects integration** — local stream behavior remains compatible with `@webex/web-media-effects`. + +Path-scoped detail: `.github/instructions/code-review.instructions.md`. + +## CI/CD + +- **Pull requests:** GitHub Actions — lint + Jest coverage (see `.github/workflows/pull-request-checks.yml`). +- **Main:** semantic-release publish workflow (see `.github/workflows/npm-publish.yml`). +- **Release:** semantic-release runs on `main` and derives versions from conventional commits. +- **Registry:** npm public (`@webex/webrtc-core`). + +Path-scoped detail: `.github/instructions/ci-cd.instructions.md`. + +## PR conventions + +- **Branches and commits:** Follow [docs/contributing/GIT_CONVENTIONS.md](docs/contributing/GIT_CONVENTIONS.md). Commitlint enforces Conventional Commits. +- **Release versioning:** semantic-release on **`main`** analyzes merged commit messages, not the PR title alone. +- **Description:** Use [.github/skills/pr-description/SKILL.md](.github/skills/pr-description/SKILL.md) to complete `.github/pull_request_template.md` from the committed diff and verified test evidence. +- **GAI disclosure:** Required checkbox in PR template. + +## Security + +- Never commit `.pem`, `.key`, `.env`, or credential files. Remove stray keys from the working tree before staging. +- Do not put absolute paths, tokens, customer/PII, or raw internal credentials in committed files. +- Do not log or paste internal hostnames, tokens, or meeting identifiers into agent context files. +- If a secret was committed locally: **do not push**; remove from history per team process, rotate the credential, and follow incident response. + +## Comments + +Comments explain *why*, not *what*: + +- Delete obvious comments that restate code. +- Keep JSDoc tight: description + `@param` + `@returns`. +- Flag counterintuitive browser or WebRTC behavior with a brief reason. +- No ticket IDs, dates, or author names in code comments. +- Prefer full sentences in `//` comments. Avoid semicolons to chain clauses and avoid dashes ( `-` or `—` ) mid-sentence as a pause or aside. Use two short sentences instead. + +## Writing for humans (README, docs, and code) + +These apply to people and to agents editing the repo. + +### README and markdown + +- **Lead with the reader’s goal** in one or two plain sentences. +- **Short paragraphs and lists:** Keep one idea per bullet. +- **Physical lines:** Keep each prose sentence, blockquote paragraph, and list item on one physical line. Start a new line only for a new structural element. +- **Name the action:** Write “Run `yarn test` from the repository root” instead of passive phrasing. +- **Link instead of duplicating:** Point to `AGENTS.md`, the knowledge base, or the external source for depth. +- **Diagrams in committed Markdown:** Use [Mermaid](https://mermaid.js.org/) fenced blocks in documentation. Do not add new ASCII box diagrams. + +### Code comments and JSDoc + +- **Why, not what:** Explain constraints, browser quirks, and protocol assumptions. +- **Complete sentences** in JSDoc descriptions. +- **Avoid noise** — no commented-out code, no ticket IDs in comments. + +### Tone + +- Direct and professional; active voice preferred. +- Define acronyms once when needed, then use the short form. + +Agents should follow the same rules when proposing README or comment edits. + +## Knowledge sources + +When researching requirements, design, or incidents: + +| Source | Use | +|---|---| +| [docs/knowledge-base/](docs/knowledge-base/README.md) | Public scope, direct dependency roles, and source module map | +| **GitHub** | [webex/webrtc-core](https://github.com/webex/webrtc-core) | diff --git a/README.md b/README.md index a74eb13..1579b54 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # webrtc-core -Handles the WebRTC core functionality and provides media helper function on browser. +Handles WebRTC core functionality and provides media helper functions in the browser. ## Development @@ -9,6 +9,20 @@ Handles the WebRTC core functionality and provides media helper function on brow 3. `yarn test` 4. `yarn watch` +`yarn test` runs the build and every `test:*` script, including the Karma integration tests. Make sure local Chrome can run before using this command. + +Run Karma integration tests locally with `yarn test:integration:chrome`. The Firefox, Edge, and Safari scripts select their named browser matrices only when `SAUCE=true` and valid Sauce Labs credentials are provided; without Sauce, they also launch local Chrome. + +## AI-assisted development + +Contributors and coding agents should start with [`AGENTS.md`](AGENTS.md) for setup, commands, pull request conventions, and security rules. GitHub Copilot loads the same guidance through [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Read the [`docs/knowledge-base/`](docs/knowledge-base/README.md) index for architecture and dependency context before a broad code search. + +## Contributing + +Use the [PR description skill](.github/skills/pr-description/SKILL.md) to draft the [PR template](.github/pull_request_template.md) from committed changes and verified test evidence. + +Follow the [branch and commit conventions](docs/contributing/GIT_CONVENTIONS.md). Semantic-release determines the next npm version from the commits merged into `main`, not from the PR title alone. + ## Usage -This library uses [cspell](https://github.com/streetsidesoftware/cspell) to check spelling throughout the codebase. Any words that need to be ignored (e.g., package names, protocols, etc.), should be added to the `ignoreWords` field in the [cspell.json](./cspell.json) configuration file. +This library uses [cspell](https://github.com/streetsidesoftware/cspell) to check spelling throughout the codebase. Add accepted package names, protocols, and other project terms to the `words` list in [cspell.json](./cspell.json). diff --git a/cspell.json b/cspell.json index cc4eac8..a5b85cf 100644 --- a/cspell.json +++ b/cspell.json @@ -11,6 +11,7 @@ "circleci", "codecov", "commitlint", + "corepack", "cpaas", "createansweronsuccess", "createofferonsuccess", @@ -24,8 +25,10 @@ "exponentiate", "globby", "gohri", + "hostnames", "libauth", "mkdir", + "multistream", "negotiatedneeded", "peerconnectionstatechange", "preprocessors", diff --git a/docs/contributing/GIT_CONVENTIONS.md b/docs/contributing/GIT_CONVENTIONS.md new file mode 100644 index 0000000..699007b --- /dev/null +++ b/docs/contributing/GIT_CONVENTIONS.md @@ -0,0 +1,40 @@ +# Branch and Commit Conventions + +Use these rules for branch names and commit messages. PR description guidance lives in [the PR description skill](../../.github/skills/pr-description/SKILL.md). + +## Branch Names + +- Start new work from the current `main` branch. +- Use `/` for a branch in this repository. +- A branch in a contributor fork may use ``. +- Keep names lowercase, short, and separated with hyphens. + +Examples: + +- `developer/pr-description-guidance` +- `fix-missing-track-stop` + +## Commit Messages + +Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) because commitlint validates them and semantic-release analyzes commits merged into `main`. + +Use this format: + +```text +(): +``` + +Common types: + +- `feat`: new behavior that normally produces a minor release +- `fix`: corrected behavior that normally produces a patch release +- `docs`: documentation-only change +- `refactor`: internal restructuring without a behavior change +- `test`: test-only change +- `chore`, `ci`, or `build`: maintenance and delivery work + +Keep the subject direct, lowercase, and under 100 characters. Use the body when the reason or trade-off is not clear from the subject. + +Mark an intentional breaking change with `!` after the type or scope, or add a `BREAKING CHANGE:` footer. Breaking changes can produce a major release. + +Semantic-release reads the commits that land on `main`. Do not assume the PR title alone controls the published version. diff --git a/docs/knowledge-base/README.md b/docs/knowledge-base/README.md new file mode 100644 index 0000000..14890ac --- /dev/null +++ b/docs/knowledge-base/README.md @@ -0,0 +1,14 @@ +# Knowledge Base + +This knowledge base gives contributors and coding agents a short map of webrtc-core's public scope, direct dependencies, and source modules. Repository guidance lives in [AGENTS.md](../../AGENTS.md). + +| Link | What you get | +|---|---| +| [architecture/webrtc-core-overview.md](architecture/webrtc-core-overview.md) | Public scope, direct dependencies, source module map, and release behavior | +| [README.md](../../README.md) | Setup, build, test entry points | + +New articles belong under `architecture/` and should be linked here. Agents should only add them after the user asks to capture repeatable knowledge (see [AGENTS.md](../../AGENTS.md)). + +Use **Mermaid** for architecture and flow diagrams in knowledge base Markdown. See [architecture/webrtc-core-overview.md](architecture/webrtc-core-overview.md) for examples. + +When writing or editing KB markdown, follow **Writing for humans** in [AGENTS.md](../../AGENTS.md#writing-for-humans-readme-docs-and-code). diff --git a/docs/knowledge-base/architecture/webrtc-core-overview.md b/docs/knowledge-base/architecture/webrtc-core-overview.md new file mode 100644 index 0000000..63f3cb9 --- /dev/null +++ b/docs/knowledge-base/architecture/webrtc-core-overview.md @@ -0,0 +1,61 @@ +# webrtc-core — Architecture Overview + +> High-level design for `@webex/webrtc-core`: browser WebRTC primitives, local and remote streams, device helpers, and integration with `@webex/web-media-effects`. Verify behavior in `src/` and the exports in `src/index.ts`. + +--- + +## 1. Public scope and ownership boundary + +webrtc-core packages browser WebRTC behavior for reuse instead of requiring each application to implement peer connections, stream classes, device access, and browser differences independently. + +The public [Webex JS SDK](https://github.com/webex/webex-js-sdk) provides application-facing meetings and media APIs. This repository documents only webrtc-core's browser primitives and direct dependencies, not private application implementation paths. + +```mermaid +flowchart LR + Core["@webex/webrtc-core"] + Core --> Browser["Browser WebRTC APIs"] + Core --> Effects["@webex/web-media-effects"] +``` + +webrtc-core wraps browser WebRTC APIs and consumes `@webex/web-media-effects` to attach effect processors to local streams. + +--- + +## 2. Key dependencies + +The root `package.json` is authoritative for the complete dependency list and current versions. The packages below have direct architectural roles in webrtc-core. + +| Package | Pin | Role | +|---|---|---| +| `@webex/web-media-effects` | exact | Media effect processors attached through local stream effect APIs | +| `@webex/web-capabilities` | semver | `BrowserInfo` and capability probes used in connection/stream code | +| `@webex/ts-events` | semver | Typed event surfaces shared with other media packages | +| `webrtc-adapter` | semver | Browser normalization for RTCPeerConnection and getUserMedia | + +--- + +## 3. Key source modules + +| Area | Files (under `src/`) | +|---|---| +| Public exports | `index.ts` — semver impact for any export change | +| Peer connection | `peer-connection.ts`, `peer-connection-utils.ts`, `rtc-peer-connection-factory.ts`, `connection-state-handler.ts` | +| Local media and effects | `media/local-stream.ts`, `media/local-audio-stream.ts`, `media/local-video-stream.ts`, `media/local-camera-stream.ts`, `media/local-microphone-stream.ts`, `media/local-display-stream.ts`, `media/local-system-audio-stream.ts` | +| Remote media | `media/remote-stream.ts`, `media/stream.ts` | +| Device APIs | `device/device-management.ts`, `media/index.ts` (getUserMedia, enumerateDevices, permissions) | + +--- + +## 4. Releases + +semantic-release publishes `@webex/webrtc-core` from `main`. Conventional commits determine the next version, and public API changes must follow semantic-versioning expectations. + +--- + +## 5. Further reading + +- [Webex JS SDK](https://github.com/webex/webex-js-sdk) — public SDK that exposes meetings and media helpers +- [Web Media Effects on npm](https://www.npmjs.com/package/@webex/web-media-effects) — exact-pinned effect processor dependency +- [Knowledge base index](../README.md) — repository-local context index +- [AGENTS.md](../../../AGENTS.md) — commands and contribution conventions +- [README.md](../../../README.md) — local setup and test commands diff --git a/package.json b/package.json index 0f51fa3..56e50d8 100644 --- a/package.json +++ b/package.json @@ -85,9 +85,9 @@ "clean": "npm run transpile:clean && npm run docs:clean", "compile": "rollup -c ./rollup.config.js", "docs": "npm run docs:clean && npm run docs:extract && npm run docs:generate", - "docs:clean": "rimraf ./docs", + "docs:clean": "rimraf ./docs/temp ./docs/api-reference ./docs/index.md \"./docs/webrtc-core*.md\"", "docs:extract": "api-extractor run -c ./api-extractor.json", - "docs:generate": "api-documenter markdown -i ./docs/temp -o ./docs", + "docs:generate": "api-documenter markdown -i ./docs/temp -o ./docs/api-reference", "fix": "run-s fix:*", "fix:prettier": "prettier \"src/**/*.ts\" --write", "fix:lint": "eslint src --ext .ts --fix", @@ -96,7 +96,7 @@ "test": "run-s build test:*", "test:lint": "eslint src --ext .ts", "test:prettier": "prettier \"src/**/*.ts\" --list-different", - "test:spelling": "cspell \"{README.md,.github/*.md,src/**/*.ts}\"", + "test:spelling": "cspell \"{README.md,AGENTS.md,docs/**/*.md,.github/**/*.md,src/**/*.ts}\"", "test:unit": "jest", "test:coverage": "jest --coverage", "test:integration:safari": "karma start --integration --safari",