From f7fbb4e12ba9702bc4f7021cdb086a43fad83605 Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Mon, 10 Aug 2026 17:57:30 +0200 Subject: [PATCH 1/7] docs(agents): add AGENTS.md, knowledge base, and Copilot context --- .github/copilot-instructions.md | 3 + .github/instructions/ci-cd.instructions.md | 35 +++ .../instructions/code-review.instructions.md | 27 ++ .github/instructions/testing.instructions.md | 42 +++ .github/skills/confluence-mcp/SKILL.md | 50 ++++ .github/skills/jira-mcp/SKILL.md | 57 ++++ AGENTS.md | 250 ++++++++++++++++++ README.md | 10 +- cspell.json | 3 + docs/knowledge-base/README.md | 14 + .../architecture/webrtc-core-overview.md | 77 ++++++ package.json | 4 +- 12 files changed, 568 insertions(+), 4 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/ci-cd.instructions.md create mode 100644 .github/instructions/code-review.instructions.md create mode 100644 .github/instructions/testing.instructions.md create mode 100644 .github/skills/confluence-mcp/SKILL.md create mode 100644 .github/skills/jira-mcp/SKILL.md create mode 100644 AGENTS.md create mode 100644 docs/knowledge-base/README.md create mode 100644 docs/knowledge-base/architecture/webrtc-core-overview.md 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..6db1b4c --- /dev/null +++ b/.github/instructions/code-review.instructions.md @@ -0,0 +1,27 @@ +--- +applyTo: "src/**/*.ts" +name: webrtc-core Code Review +description: Use when reviewing or preparing changes under src/ — correctness, exact pins on web-media-effects, public API, PeerConnection lifecycle, local streams, and events. +--- + +# 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. Exact-pin discipline — `@webex/web-media-effects` is an **exact** pin; bumps must be intentional with stated reason and downstream ripple (WCME, internal-media-core). +3. Public API — additions/removals in `src/index.ts` noted with semver impact. +4. Browser quirks — adapter, permissions API differences (Firefox/Safari), fake-device test assumptions. +5. Event contracts — no silent removal/rename of typed events on streams and `PeerConnection`. +6. 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..13eef9d --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,42 @@ +--- +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`). +- Run locally with `yarn test:integration:chrome` or the corresponding Firefox, Edge, or Safari script in `package.json`. +- 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` — mocks auto-reset between tests. + +## 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/skills/confluence-mcp/SKILL.md b/.github/skills/confluence-mcp/SKILL.md new file mode 100644 index 0000000..649a1ee --- /dev/null +++ b/.github/skills/confluence-mcp/SKILL.md @@ -0,0 +1,50 @@ +--- +name: confluence-mcp +description: Search, read, and update Cisco Confluence pages through the `confluence` MCP server — search and update only, never create pages. +source_url: https://confluence-eng-gpk2.cisco.com/conf/pages/viewpage.action?pageId=836486519 +source_hash: 76a778ba20043ae1c056cffcb8c1c60669125354d2d7b46d995295f14c079f47 +last_verified: 2026-07-29 +--- + +# Confluence MCP Skill + +## Usage Policy: Search and Update Only + +> **Do not create new Confluence pages with this MCP.** +> +> We do **not** have permission to delete pages. If the agent creates pages incorrectly or creates too many, there is no way to clean them up. + +**Do:** +- Search for existing pages via CQL. +- Fetch pages by ID, title, or URL. +- Read and summarize pages. +- Update existing pages when explicitly requested. + +**Do not:** +- Create new pages via the MCP. +- Delete pages (not possible regardless). + +## Available Tools + +| Tool | Purpose | +|---|---| +| `search_confluence_pages` | Search using CQL (Confluence Query Language). | +| `get_confluence_page_by_id` | Fetch a page by its numeric ID. | +| `get_confluence_page_by_title` | Fetch a page by its title. | +| `get_confluence_page_by_url` | Fetch a page by its URL. | +| `call_confluence_rest_api` | Generic REST access. **Reads and updates only.** | + +## Format Requirements + +- **Updates** must use Confluence storage-format XHTML, or wiki markup where the API explicitly accepts it. +- Never send raw Markdown as a page body. It will render as plain text. +- Escape text correctly and use CDATA for code content. +- **Prose style:** follow [Writing for humans](../../../AGENTS.md#writing-for-humans-readme-docs-and-code). Use plain language and avoid semicolons or dash punctuation in page prose. + +## Safety + +- Probe the MCP only when the task needs it. +- Stop clearly if the connector is unavailable. +- Never copy tokens or auth details into context files. +- Requires Cisco network/VPN access. +- Do not copy raw page content into committed repo files — use a sanitized summary and stable link instead. diff --git a/.github/skills/jira-mcp/SKILL.md b/.github/skills/jira-mcp/SKILL.md new file mode 100644 index 0000000..0ffd0eb --- /dev/null +++ b/.github/skills/jira-mcp/SKILL.md @@ -0,0 +1,57 @@ +--- +name: jira-mcp +description: Search, read, and update Cisco Jira issues through the `jira` MCP server — search and update only, never create issues. +source_url: https://confluence-eng-gpk2.cisco.com/conf/spaces/webexmedia/pages/836486533/Jira+MCP +source_hash: e0e65762072f4623998729bf065a39e43b511d170c46e604c48030a3d2202c84 +last_verified: 2026-07-29 +--- + +# Jira MCP Skill + +## Usage Policy: Search and Update Only + +> **Do not create new Jira issues with this MCP.** +> +> Keep the MCP scoped to searching and updating existing issues. The agent can create issues incorrectly or create too many, and cleanup is painful. + +**Do:** +- Search for existing issues via JQL. +- Read and summarize issues. +- Update fields on existing issues when explicitly requested. +- Add labels to existing issues (non-destructive, preserves existing labels). + +**Do not:** +- Create new issues via the MCP. +- Delete issues. +- Overwrite existing labels (use `add_labels` instead). + +## Available Tools + +| Tool | Purpose | +|---|---| +| `add_labels` | Add labels without overriding existing labels. | +| `get_field_info` | Look up field IDs and types by name or search term. | +| `call_jira_rest_api` | Generic REST access. **Reads and updates only.** | + +## Resources (Read-Only Context) + +| Resource | Description | +|---|---| +| `jira://current-user` | Current authenticated user details. | +| `jira://auth-status` | Authentication status and configuration. | +| `jira://fieldIDs` | Mapping of field names to IDs. | +| `jira://server-info` | Server information (check for Cloud vs Server). | + +## Format Requirements + +- **Jira Server (v2 API):** Use Jira wiki markup for description and comment fields. Never send raw Markdown. +- **Jira Cloud:** Use ADF JSON. Check `jira://server-info` to determine which. +- Use Jira emoticons (`(!)`, `(x)`, `(/)`, `(i)`) not Unicode emoji. +- Use `get_field_info` before changing unfamiliar fields. + +## Safety + +- Probe the MCP only when the task needs it. +- Stop clearly if the connector is unavailable. +- Never copy tokens or auth details into context files. +- Requires Cisco network/VPN access. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2d69797 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,250 @@ +# 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`. + +In the public Webex application stack, [Webex Web Client](https://github.com/webex/webex-web-client) uses the meetings and media APIs from the [Webex JS SDK](https://github.com/webex/webex-js-sdk). The SDK reaches this library through `@webex/internal-media-core` and `@webex/web-client-media-engine` (WCME). This dependency path explains where changes are consumed; it does not make webrtc-core responsible for meeting join, multistream signaling, or SDP munging. + +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 the source (file path, config key, stable link, or Confluence page URL) so a human can verify. +2. Do not create Jira issues or Confluence pages via MCP. Search and update existing items only — see `.github/skills/jira-mcp/SKILL.md` and `.github/skills/confluence-mcp/SKILL.md`. +3. Never commit secrets, credentials, `.pem` files, or decrypted `.env` values. +4. Do not copy raw Confluence or Jira content into the repo — summarize and link. + +### 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 **role in the Webex stack** or **WCME / effects** boundaries. +- **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/` or `docs/knowledge-base/questions/`, 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 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:** Cisco MCP policy changes or 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/knowledge-base/ ← architecture pointers for agents +├── .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` | Full local check: build, lint, Prettier, spelling, unit tests, and coverage | +| `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 (Chrome via Puppeteer) | +| `yarn test:integration:firefox` | Karma integration tests (Firefox) | +| `yarn test:integration:edge` | Karma integration tests (Edge) | +| `yarn test:integration:safari` | Karma integration tests (Safari) | +| `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`. WCME also pins webrtc-core exactly downstream. See the [architecture overview](docs/knowledge-base/architecture/webrtc-core-overview.md) for dependency roles and delivery impact. Any exact-pin change must be intentional 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 and `yarn test` for the full non-integration check. Run the relevant `yarn test:integration:` script separately for browser integration coverage. + +Path-scoped detail: `.github/instructions/testing.instructions.md`. + +## Code review priorities + +1. **Correctness** — capture, track stop/replace, constraint and effects edge cases. +2. **Exact-pin discipline** — especially `@webex/web-media-effects` and downstream WCME pins. +3. **Public API changes** — exports in `src/index.ts` have semver impact. +4. **Browser differences** — permissions, adapter, Safari/Firefox quirks. +5. **Event contracts** — no silent breaking changes on streams or `PeerConnection`. + +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 + +- **Branch:** Use `/`. +- **Title:** Conventional commit format (`type(scope): subject`). +- **Commits:** Husky **commitlint** with `@commitlint/config-conventional`. +- **Description:** Fill `.github/pull_request_template.md` — summary, test evidence, linked **Jira** in the PR body (not in code comments). Call out **exact-pin** or **public API** changes and downstream ripple. +- **Validation:** Run lint and unit tests before pushing. Run spelling checks when documentation changes. +- **GAI disclosure:** Required checkbox in PR template. + +## Downstream impact + +After a release from `main`, `@webex/web-client-media-engine` must deliberately update its exact webrtc-core pin to consume the release. Changes then continue through downstream packages according to their own pins. Plan this delivery work when changing published behavior or the `@webex/web-media-effects` pin. + +## 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 consumer path, dependency roles, and source module map | +| **GitHub** | [webex/webrtc-core](https://github.com/webex/webrtc-core) | +| **Jira** | Project `SPARK` — search for webrtc-core / WCME / media labels before updates. **Updates:** Jira wiki markup in v2 description/comments, not Markdown (see Jira MCP skill). | +| **MCP skills** | `.github/skills/jira-mcp/SKILL.md`, `.github/skills/confluence-mcp/SKILL.md` — search/update only, never create | diff --git a/README.md b/README.md index a74eb13..9f7479e 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,12 @@ Handles the WebRTC core functionality and provides media helper function on brow 3. `yarn test` 4. `yarn watch` +Integration tests (Karma): `yarn test:integration:chrome` and sibling scripts in `package.json`. + +## 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. + ## 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/knowledge-base/README.md b/docs/knowledge-base/README.md new file mode 100644 index 0000000..e4caea0 --- /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 and its place between browser WebRTC APIs and public Webex applications. Repository guidance lives in [AGENTS.md](../../AGENTS.md). + +| Link | What you get | +|---|---| +| [architecture/webrtc-core-overview.md](architecture/webrtc-core-overview.md) | Public consumer path, key dependencies, source module map, and release impact | +| [README.md](../../README.md) | Setup, build, test entry points | + +New articles belong under `architecture/` or `questions/` 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..4cf2ed0 --- /dev/null +++ b/docs/knowledge-base/architecture/webrtc-core-overview.md @@ -0,0 +1,77 @@ +# 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 use 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. + +[Webex Web Client](https://github.com/webex/webex-web-client) consumes `@webex/plugin-meetings` from the [Webex JS SDK](https://github.com/webex/webex-js-sdk). The SDK's meetings plugin and media helpers consume `@webex/internal-media-core`; internal-media-core consumes WCME; and WCME exact-pins webrtc-core. The middle packages explain dependency ownership, while Webex JS SDK and Webex Web Client show where this behavior reaches SDK consumers and application code. + +```mermaid +flowchart LR + WebClient["Webex Web Client"] --> SDK["Webex JS SDK
plugin-meetings · media-helpers"] + SDK --> IMC["@webex/internal-media-core"] + IMC --> WCME["@webex/web-client-media-engine"] + WCME --> Core["@webex/webrtc-core"] + Core --> Browser["Browser WebRTC APIs"] + Core --> Effects["@webex/web-media-effects"] +``` + +Each arrow points from a consumer to what it uses. The main path ends at browser APIs, while webrtc-core also consumes `@webex/web-media-effects` to attach effect processors to local streams. + +--- + +## 2. Key dependencies + +Dependency versions come from the root `package.json`. `@webex/web-media-effects` is an **exact pin**; other `@webex/*` packages use semver ranges. + +| 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 | +| `js-logger` | semver | Logging | +| `typed-emitter` | semver | Type-safe event emitter (`event-emitter.ts`) | +| `events` | semver | Node-compatible EventEmitter backing | + +--- + +## 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 capture | `media/local-audio-stream.ts`, `local-video-stream.ts`, `local-camera-stream.ts`, `local-microphone-stream.ts`, `local-display-stream.ts`, `local-system-audio-stream.ts`, `local-stream.ts` | +| Remote | `media/remote-stream.ts`, `media/stream.ts` | +| Device APIs | `device/device-management.ts`, `media/index.ts` (getUserMedia, enumerateDevices, permissions) | +| Shared | `errors.ts`, `event-emitter.ts`, `util/logger.ts` | +| Tests | Co-located `*.spec.ts` (Jest); `media.integration-test.ts` (Karma) | +| Mocks | `mocks/` for unit and integration tests | + +--- + +## 4. Release impact + +After a published release of `@webex/webrtc-core`, consumers with exact pins must update deliberately: + +- `@webex/web-client-media-engine` pins webrtc-core exactly. +- `@webex/internal-media-core` consumes WCME and receives webrtc-core through WCME's dependency chain. + +Treat exact-pin bumps in downstream repos as part of delivery when changing published behavior or dependencies. + +--- + +## 5. Further reading + +- [Webex JS SDK](https://github.com/webex/webex-js-sdk) — public SDK that exposes meetings and media helpers +- [Webex Web Client](https://github.com/webex/webex-web-client) — public application that consumes the SDK +- [Web Client Media Engine](https://github.com/webex/web-client-media-engine) — direct consumer that exact-pins webrtc-core +- [Web Media Effects](https://github.com/webex/web-media-effects) — exact-pinned effect processor dependency +- [Knowledge base index](../README.md) — repository-local context index +- [AGENTS.md](../../../AGENTS.md) — commands, conventions, Jira/MCP sources +- [README.md](../../../README.md) — local setup and test commands diff --git a/package.json b/package.json index 0f51fa3..14dee30 100644 --- a/package.json +++ b/package.json @@ -85,7 +85,7 @@ "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/*.md", "docs:extract": "api-extractor run -c ./api-extractor.json", "docs:generate": "api-documenter markdown -i ./docs/temp -o ./docs", "fix": "run-s 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", From 156587a5d4f962d7b3a6e6ebd446924564a5d8f4 Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Mon, 17 Aug 2026 18:47:56 +0200 Subject: [PATCH 2/7] docs(agents): remove private and invalid links Keep open-source agent context public-safe and point downstream package references to verified public resources. --- .github/skills/confluence-mcp/SKILL.md | 7 ++----- .github/skills/jira-mcp/SKILL.md | 6 ++---- AGENTS.md | 6 +++--- docs/knowledge-base/README.md | 4 ++-- .../architecture/webrtc-core-overview.md | 12 +++++------- 5 files changed, 14 insertions(+), 21 deletions(-) diff --git a/.github/skills/confluence-mcp/SKILL.md b/.github/skills/confluence-mcp/SKILL.md index 649a1ee..7f00b5e 100644 --- a/.github/skills/confluence-mcp/SKILL.md +++ b/.github/skills/confluence-mcp/SKILL.md @@ -1,9 +1,6 @@ --- name: confluence-mcp description: Search, read, and update Cisco Confluence pages through the `confluence` MCP server — search and update only, never create pages. -source_url: https://confluence-eng-gpk2.cisco.com/conf/pages/viewpage.action?pageId=836486519 -source_hash: 76a778ba20043ae1c056cffcb8c1c60669125354d2d7b46d995295f14c079f47 -last_verified: 2026-07-29 --- # Confluence MCP Skill @@ -46,5 +43,5 @@ last_verified: 2026-07-29 - Probe the MCP only when the task needs it. - Stop clearly if the connector is unavailable. - Never copy tokens or auth details into context files. -- Requires Cisco network/VPN access. -- Do not copy raw page content into committed repo files — use a sanitized summary and stable link instead. +- Requires an authenticated enterprise MCP connection. +- Do not copy raw page content, private URLs, hostnames, or page IDs into committed repository files. Use a sanitized summary instead. diff --git a/.github/skills/jira-mcp/SKILL.md b/.github/skills/jira-mcp/SKILL.md index 0ffd0eb..35f3ce9 100644 --- a/.github/skills/jira-mcp/SKILL.md +++ b/.github/skills/jira-mcp/SKILL.md @@ -1,9 +1,6 @@ --- name: jira-mcp description: Search, read, and update Cisco Jira issues through the `jira` MCP server — search and update only, never create issues. -source_url: https://confluence-eng-gpk2.cisco.com/conf/spaces/webexmedia/pages/836486533/Jira+MCP -source_hash: e0e65762072f4623998729bf065a39e43b511d170c46e604c48030a3d2202c84 -last_verified: 2026-07-29 --- # Jira MCP Skill @@ -54,4 +51,5 @@ last_verified: 2026-07-29 - Probe the MCP only when the task needs it. - Stop clearly if the connector is unavailable. - Never copy tokens or auth details into context files. -- Requires Cisco network/VPN access. +- Requires an authenticated enterprise MCP connection. +- Do not copy private URLs, hostnames, or internal issue content into committed repository files. Use a sanitized summary instead. diff --git a/AGENTS.md b/AGENTS.md index 2d69797..2e0ba1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ `@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`. -In the public Webex application stack, [Webex Web Client](https://github.com/webex/webex-web-client) uses the meetings and media APIs from the [Webex JS SDK](https://github.com/webex/webex-js-sdk). The SDK reaches this library through `@webex/internal-media-core` and `@webex/web-client-media-engine` (WCME). This dependency path explains where changes are consumed; it does not make webrtc-core responsible for meeting join, multistream signaling, or SDP munging. +The public [Webex JS SDK](https://github.com/webex/webex-js-sdk) exposes application-facing meetings and media APIs. Its media dependency chain reaches this library through `@webex/internal-media-core` and `@webex/web-client-media-engine` (WCME). This dependency path explains where changes are consumed; it does not make webrtc-core responsible for meeting join, multistream signaling, or SDP munging. 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). @@ -20,10 +20,10 @@ New contributors should use this file for setup, development, testing, and contr These rules apply to interactive (terminal / IDE) agent sessions only. -1. Statements backed by evidence should cite the source (file path, config key, stable link, or Confluence page URL) so a human can verify. +1. Statements backed by evidence should cite a repository path, config key, or stable public link so a human can verify. 2. Do not create Jira issues or Confluence pages via MCP. Search and update existing items only — see `.github/skills/jira-mcp/SKILL.md` and `.github/skills/confluence-mcp/SKILL.md`. 3. Never commit secrets, credentials, `.pem` files, or decrypted `.env` values. -4. Do not copy raw Confluence or Jira content into the repo — summarize and link. +4. Do not copy raw Confluence or Jira content, private URLs, hostnames, or page IDs into the repository. Use a sanitized summary instead. ### Committing files (agents) diff --git a/docs/knowledge-base/README.md b/docs/knowledge-base/README.md index e4caea0..3747476 100644 --- a/docs/knowledge-base/README.md +++ b/docs/knowledge-base/README.md @@ -1,10 +1,10 @@ # Knowledge Base -This knowledge base gives contributors and coding agents a short map of webrtc-core and its place between browser WebRTC APIs and public Webex applications. Repository guidance lives in [AGENTS.md](../../AGENTS.md). +This knowledge base gives contributors and coding agents a short map of webrtc-core and its place between browser WebRTC APIs and downstream Webex packages. Repository guidance lives in [AGENTS.md](../../AGENTS.md). | Link | What you get | |---|---| -| [architecture/webrtc-core-overview.md](architecture/webrtc-core-overview.md) | Public consumer path, key dependencies, source module map, and release impact | +| [architecture/webrtc-core-overview.md](architecture/webrtc-core-overview.md) | Downstream package path, key dependencies, source module map, and release impact | | [README.md](../../README.md) | Setup, build, test entry points | New articles belong under `architecture/` or `questions/` and should be linked here. Agents should only add them after the user asks to capture repeatable knowledge (see [AGENTS.md](../../AGENTS.md)). diff --git a/docs/knowledge-base/architecture/webrtc-core-overview.md b/docs/knowledge-base/architecture/webrtc-core-overview.md index 4cf2ed0..5a87ebd 100644 --- a/docs/knowledge-base/architecture/webrtc-core-overview.md +++ b/docs/knowledge-base/architecture/webrtc-core-overview.md @@ -4,16 +4,15 @@ --- -## 1. Public use and ownership boundary +## 1. Downstream use 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. -[Webex Web Client](https://github.com/webex/webex-web-client) consumes `@webex/plugin-meetings` from the [Webex JS SDK](https://github.com/webex/webex-js-sdk). The SDK's meetings plugin and media helpers consume `@webex/internal-media-core`; internal-media-core consumes WCME; and WCME exact-pins webrtc-core. The middle packages explain dependency ownership, while Webex JS SDK and Webex Web Client show where this behavior reaches SDK consumers and application code. +`@webex/web-client-media-engine` (WCME) is a direct consumer that exact-pins webrtc-core. WCME is consumed through `@webex/internal-media-core` by the public [Webex JS SDK](https://github.com/webex/webex-js-sdk). These package relationships explain where changes are consumed; they do not make webrtc-core responsible for higher-level meeting or multistream behavior. ```mermaid flowchart LR - WebClient["Webex Web Client"] --> SDK["Webex JS SDK
plugin-meetings · media-helpers"] - SDK --> IMC["@webex/internal-media-core"] + SDK["Webex JS SDK"] --> IMC["@webex/internal-media-core"] IMC --> WCME["@webex/web-client-media-engine"] WCME --> Core["@webex/webrtc-core"] Core --> Browser["Browser WebRTC APIs"] @@ -69,9 +68,8 @@ Treat exact-pin bumps in downstream repos as part of delivery when changing publ ## 5. Further reading - [Webex JS SDK](https://github.com/webex/webex-js-sdk) — public SDK that exposes meetings and media helpers -- [Webex Web Client](https://github.com/webex/webex-web-client) — public application that consumes the SDK -- [Web Client Media Engine](https://github.com/webex/web-client-media-engine) — direct consumer that exact-pins webrtc-core -- [Web Media Effects](https://github.com/webex/web-media-effects) — exact-pinned effect processor dependency +- [Web Client Media Engine on npm](https://www.npmjs.com/package/@webex/web-client-media-engine) — direct consumer that exact-pins webrtc-core +- [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, conventions, Jira/MCP sources - [README.md](../../../README.md) — local setup and test commands From 23f1281bbc4a31e3483b74690c09e0b3aadfbe52 Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Tue, 18 Aug 2026 15:58:23 +0200 Subject: [PATCH 3/7] docs: update Jira and confluence links --- .github/skills/confluence-mcp/SKILL.md | 47 ---------------- .github/skills/jira-mcp/SKILL.md | 55 ------------------- AGENTS.md | 15 ++--- .../architecture/webrtc-core-overview.md | 2 +- 4 files changed, 7 insertions(+), 112 deletions(-) delete mode 100644 .github/skills/confluence-mcp/SKILL.md delete mode 100644 .github/skills/jira-mcp/SKILL.md diff --git a/.github/skills/confluence-mcp/SKILL.md b/.github/skills/confluence-mcp/SKILL.md deleted file mode 100644 index 7f00b5e..0000000 --- a/.github/skills/confluence-mcp/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: confluence-mcp -description: Search, read, and update Cisco Confluence pages through the `confluence` MCP server — search and update only, never create pages. ---- - -# Confluence MCP Skill - -## Usage Policy: Search and Update Only - -> **Do not create new Confluence pages with this MCP.** -> -> We do **not** have permission to delete pages. If the agent creates pages incorrectly or creates too many, there is no way to clean them up. - -**Do:** -- Search for existing pages via CQL. -- Fetch pages by ID, title, or URL. -- Read and summarize pages. -- Update existing pages when explicitly requested. - -**Do not:** -- Create new pages via the MCP. -- Delete pages (not possible regardless). - -## Available Tools - -| Tool | Purpose | -|---|---| -| `search_confluence_pages` | Search using CQL (Confluence Query Language). | -| `get_confluence_page_by_id` | Fetch a page by its numeric ID. | -| `get_confluence_page_by_title` | Fetch a page by its title. | -| `get_confluence_page_by_url` | Fetch a page by its URL. | -| `call_confluence_rest_api` | Generic REST access. **Reads and updates only.** | - -## Format Requirements - -- **Updates** must use Confluence storage-format XHTML, or wiki markup where the API explicitly accepts it. -- Never send raw Markdown as a page body. It will render as plain text. -- Escape text correctly and use CDATA for code content. -- **Prose style:** follow [Writing for humans](../../../AGENTS.md#writing-for-humans-readme-docs-and-code). Use plain language and avoid semicolons or dash punctuation in page prose. - -## Safety - -- Probe the MCP only when the task needs it. -- Stop clearly if the connector is unavailable. -- Never copy tokens or auth details into context files. -- Requires an authenticated enterprise MCP connection. -- Do not copy raw page content, private URLs, hostnames, or page IDs into committed repository files. Use a sanitized summary instead. diff --git a/.github/skills/jira-mcp/SKILL.md b/.github/skills/jira-mcp/SKILL.md deleted file mode 100644 index 35f3ce9..0000000 --- a/.github/skills/jira-mcp/SKILL.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -name: jira-mcp -description: Search, read, and update Cisco Jira issues through the `jira` MCP server — search and update only, never create issues. ---- - -# Jira MCP Skill - -## Usage Policy: Search and Update Only - -> **Do not create new Jira issues with this MCP.** -> -> Keep the MCP scoped to searching and updating existing issues. The agent can create issues incorrectly or create too many, and cleanup is painful. - -**Do:** -- Search for existing issues via JQL. -- Read and summarize issues. -- Update fields on existing issues when explicitly requested. -- Add labels to existing issues (non-destructive, preserves existing labels). - -**Do not:** -- Create new issues via the MCP. -- Delete issues. -- Overwrite existing labels (use `add_labels` instead). - -## Available Tools - -| Tool | Purpose | -|---|---| -| `add_labels` | Add labels without overriding existing labels. | -| `get_field_info` | Look up field IDs and types by name or search term. | -| `call_jira_rest_api` | Generic REST access. **Reads and updates only.** | - -## Resources (Read-Only Context) - -| Resource | Description | -|---|---| -| `jira://current-user` | Current authenticated user details. | -| `jira://auth-status` | Authentication status and configuration. | -| `jira://fieldIDs` | Mapping of field names to IDs. | -| `jira://server-info` | Server information (check for Cloud vs Server). | - -## Format Requirements - -- **Jira Server (v2 API):** Use Jira wiki markup for description and comment fields. Never send raw Markdown. -- **Jira Cloud:** Use ADF JSON. Check `jira://server-info` to determine which. -- Use Jira emoticons (`(!)`, `(x)`, `(/)`, `(i)`) not Unicode emoji. -- Use `get_field_info` before changing unfamiliar fields. - -## Safety - -- Probe the MCP only when the task needs it. -- Stop clearly if the connector is unavailable. -- Never copy tokens or auth details into context files. -- Requires an authenticated enterprise MCP connection. -- Do not copy private URLs, hostnames, or internal issue content into committed repository files. Use a sanitized summary instead. diff --git a/AGENTS.md b/AGENTS.md index 2e0ba1f..2e305b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,9 +21,8 @@ New contributors should use this file for setup, development, testing, and contr 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. Do not create Jira issues or Confluence pages via MCP. Search and update existing items only — see `.github/skills/jira-mcp/SKILL.md` and `.github/skills/confluence-mcp/SKILL.md`. -3. Never commit secrets, credentials, `.pem` files, or decrypted `.env` values. -4. Do not copy raw Confluence or Jira content, private URLs, hostnames, or page IDs into the repository. Use a sanitized summary instead. +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) @@ -48,11 +47,11 @@ These rules apply to interactive (terminal / IDE) agent sessions only. ## Maintaining this file -Keep `AGENTS.md`, scoped instructions, and skills aligned with checked-in facts. +Keep `AGENTS.md` and scoped instructions 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:** Cisco MCP policy changes or a release changes documented dependency relationships. +**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. @@ -187,7 +186,7 @@ Path-scoped detail: `.github/instructions/ci-cd.instructions.md`. - **Branch:** Use `/`. - **Title:** Conventional commit format (`type(scope): subject`). - **Commits:** Husky **commitlint** with `@commitlint/config-conventional`. -- **Description:** Fill `.github/pull_request_template.md` — summary, test evidence, linked **Jira** in the PR body (not in code comments). Call out **exact-pin** or **public API** changes and downstream ripple. +- **Description:** Fill `.github/pull_request_template.md` — summary, test evidence, and a linked issue when available. Call out **exact-pin** or **public API** changes and downstream ripple. - **Validation:** Run lint and unit tests before pushing. Run spelling checks when documentation changes. - **GAI disclosure:** Required checkbox in PR template. @@ -244,7 +243,5 @@ When researching requirements, design, or incidents: | Source | Use | |---|---| -| [docs/knowledge-base/](docs/knowledge-base/README.md) | Public consumer path, dependency roles, and source module map | +| [docs/knowledge-base/](docs/knowledge-base/README.md) | Downstream package path, dependency roles, and source module map | | **GitHub** | [webex/webrtc-core](https://github.com/webex/webrtc-core) | -| **Jira** | Project `SPARK` — search for webrtc-core / WCME / media labels before updates. **Updates:** Jira wiki markup in v2 description/comments, not Markdown (see Jira MCP skill). | -| **MCP skills** | `.github/skills/jira-mcp/SKILL.md`, `.github/skills/confluence-mcp/SKILL.md` — search/update only, never create | diff --git a/docs/knowledge-base/architecture/webrtc-core-overview.md b/docs/knowledge-base/architecture/webrtc-core-overview.md index 5a87ebd..c48f113 100644 --- a/docs/knowledge-base/architecture/webrtc-core-overview.md +++ b/docs/knowledge-base/architecture/webrtc-core-overview.md @@ -71,5 +71,5 @@ Treat exact-pin bumps in downstream repos as part of delivery when changing publ - [Web Client Media Engine on npm](https://www.npmjs.com/package/@webex/web-client-media-engine) — direct consumer that exact-pins webrtc-core - [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, conventions, Jira/MCP sources +- [AGENTS.md](../../../AGENTS.md) — commands and contribution conventions - [README.md](../../../README.md) — local setup and test commands From 1b7b769cebbab25857e261f85d1926d3009c322b Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Tue, 18 Aug 2026 16:26:02 +0200 Subject: [PATCH 4/7] docs: update skills + add new git conventions --- .../instructions/code-review.instructions.md | 11 ++--- .github/instructions/testing.instructions.md | 4 +- .github/pull_request_template.md | 2 +- .github/skills/pr-description/SKILL.md | 49 +++++++++++++++++++ AGENTS.md | 46 ++++++++--------- README.md | 10 +++- docs/contributing/GIT_CONVENTIONS.md | 40 +++++++++++++++ docs/knowledge-base/README.md | 6 +-- .../architecture/webrtc-core-overview.md | 32 ++++-------- 9 files changed, 140 insertions(+), 60 deletions(-) create mode 100644 .github/skills/pr-description/SKILL.md create mode 100644 docs/contributing/GIT_CONVENTIONS.md diff --git a/.github/instructions/code-review.instructions.md b/.github/instructions/code-review.instructions.md index 6db1b4c..8a7571a 100644 --- a/.github/instructions/code-review.instructions.md +++ b/.github/instructions/code-review.instructions.md @@ -1,7 +1,7 @@ --- applyTo: "src/**/*.ts" name: webrtc-core Code Review -description: Use when reviewing or preparing changes under src/ — correctness, exact pins on web-media-effects, public API, PeerConnection lifecycle, local streams, and events. +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 @@ -11,11 +11,10 @@ When reviewing changes in `src/`: ## Priorities 1. Correctness — edge cases, error paths handled (especially getUserMedia, track lifecycle, constraint handling). -2. Exact-pin discipline — `@webex/web-media-effects` is an **exact** pin; bumps must be intentional with stated reason and downstream ripple (WCME, internal-media-core). -3. Public API — additions/removals in `src/index.ts` noted with semver impact. -4. Browser quirks — adapter, permissions API differences (Firefox/Safari), fake-device test assumptions. -5. Event contracts — no silent removal/rename of typed events on streams and `PeerConnection`. -6. Media effects integration — changes to effect processors and effect lifecycle handling must stay consistent with `@webex/web-media-effects` contracts. +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 diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md index 13eef9d..d7e35da 100644 --- a/.github/instructions/testing.instructions.md +++ b/.github/instructions/testing.instructions.md @@ -17,7 +17,9 @@ When writing or reviewing **unit** tests in `src/**/*.spec.ts`: ## Integration tests (Karma + Mocha) - Browser integration tests use **`*.integration-test.ts`** and Karma (`karma.conf.js`). -- Run locally with `yarn test:integration:chrome` or the corresponding Firefox, Edge, or Safari script in `package.json`. +- `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 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/AGENTS.md b/AGENTS.md index 2e305b5..90fe550 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ `@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. Its media dependency chain reaches this library through `@webex/internal-media-core` and `@webex/web-client-media-engine` (WCME). This dependency path explains where changes are consumed; it does not make webrtc-core responsible for meeting join, multistream signaling, or SDP munging. +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). @@ -37,17 +37,17 @@ These rules apply to interactive (terminal / IDE) agent sessions only. **When to read it (before heavy searching):** -- Questions about webrtc-core’s **role in the Webex stack** or **WCME / effects** boundaries. +- 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/` or `docs/knowledge-base/questions/`, linked from [docs/knowledge-base/README.md](docs/knowledge-base/README.md). Do not add or rewrite knowledge base files without agreement. +**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` and scoped instructions aligned with checked-in facts. +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`. @@ -92,16 +92,16 @@ Run from the repo root: | Command | Purpose | |---|---| | `yarn build` | Production build (clean + rollup) | -| `yarn test` | Full local check: build, lint, Prettier, spelling, unit tests, and coverage | +| `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 (Chrome via Puppeteer) | -| `yarn test:integration:firefox` | Karma integration tests (Firefox) | -| `yarn test:integration:edge` | Karma integration tests (Edge) | -| `yarn test:integration:safari` | Karma integration tests (Safari) | +| `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 | @@ -151,24 +151,26 @@ JSDoc is enforced by ESLint on functions, classes, and methods: ## Key dependencies -`@webex/web-media-effects` is an **exact pin** in `package.json`. WCME also pins webrtc-core exactly downstream. See the [architecture overview](docs/knowledge-base/architecture/webrtc-core-overview.md) for dependency roles and delivery impact. Any exact-pin change must be intentional and called out in the pull request. +`@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 and `yarn test` for the full non-integration check. Run the relevant `yarn test:integration:` script separately for browser integration coverage. +- **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. **Exact-pin discipline** — especially `@webex/web-media-effects` and downstream WCME pins. -3. **Public API changes** — exports in `src/index.ts` have semver impact. -4. **Browser differences** — permissions, adapter, Safari/Firefox quirks. -5. **Event contracts** — no silent breaking changes on streams or `PeerConnection`. +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`. @@ -183,17 +185,11 @@ Path-scoped detail: `.github/instructions/ci-cd.instructions.md`. ## PR conventions -- **Branch:** Use `/`. -- **Title:** Conventional commit format (`type(scope): subject`). -- **Commits:** Husky **commitlint** with `@commitlint/config-conventional`. -- **Description:** Fill `.github/pull_request_template.md` — summary, test evidence, and a linked issue when available. Call out **exact-pin** or **public API** changes and downstream ripple. -- **Validation:** Run lint and unit tests before pushing. Run spelling checks when documentation changes. +- **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. -## Downstream impact - -After a release from `main`, `@webex/web-client-media-engine` must deliberately update its exact webrtc-core pin to consume the release. Changes then continue through downstream packages according to their own pins. Plan this delivery work when changing published behavior or the `@webex/web-media-effects` pin. - ## Security - Never commit `.pem`, `.key`, `.env`, or credential files. Remove stray keys from the working tree before staging. @@ -243,5 +239,5 @@ When researching requirements, design, or incidents: | Source | Use | |---|---| -| [docs/knowledge-base/](docs/knowledge-base/README.md) | Downstream package path, dependency roles, and source module map | +| [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 9f7479e..1579b54 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,20 @@ Handles WebRTC core functionality and provides media helper functions in the bro 3. `yarn test` 4. `yarn watch` -Integration tests (Karma): `yarn test:integration:chrome` and sibling scripts in `package.json`. +`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. Add accepted package names, protocols, and other project terms to the `words` list in [cspell.json](./cspell.json). 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 index 3747476..14890ac 100644 --- a/docs/knowledge-base/README.md +++ b/docs/knowledge-base/README.md @@ -1,13 +1,13 @@ # Knowledge Base -This knowledge base gives contributors and coding agents a short map of webrtc-core and its place between browser WebRTC APIs and downstream Webex packages. Repository guidance lives in [AGENTS.md](../../AGENTS.md). +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) | Downstream package path, key dependencies, source module map, and release impact | +| [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/` or `questions/` and should be linked here. Agents should only add them after the user asks to capture repeatable knowledge (see [AGENTS.md](../../AGENTS.md)). +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. diff --git a/docs/knowledge-base/architecture/webrtc-core-overview.md b/docs/knowledge-base/architecture/webrtc-core-overview.md index c48f113..63f3cb9 100644 --- a/docs/knowledge-base/architecture/webrtc-core-overview.md +++ b/docs/knowledge-base/architecture/webrtc-core-overview.md @@ -4,28 +4,26 @@ --- -## 1. Downstream use and ownership boundary +## 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. -`@webex/web-client-media-engine` (WCME) is a direct consumer that exact-pins webrtc-core. WCME is consumed through `@webex/internal-media-core` by the public [Webex JS SDK](https://github.com/webex/webex-js-sdk). These package relationships explain where changes are consumed; they do not make webrtc-core responsible for higher-level meeting or multistream behavior. +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 - SDK["Webex JS SDK"] --> IMC["@webex/internal-media-core"] - IMC --> WCME["@webex/web-client-media-engine"] - WCME --> Core["@webex/webrtc-core"] + Core["@webex/webrtc-core"] Core --> Browser["Browser WebRTC APIs"] Core --> Effects["@webex/web-media-effects"] ``` -Each arrow points from a consumer to what it uses. The main path ends at browser APIs, while webrtc-core also consumes `@webex/web-media-effects` to attach effect processors to local streams. +webrtc-core wraps browser WebRTC APIs and consumes `@webex/web-media-effects` to attach effect processors to local streams. --- ## 2. Key dependencies -Dependency versions come from the root `package.json`. `@webex/web-media-effects` is an **exact pin**; other `@webex/*` packages use semver ranges. +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 | |---|---|---| @@ -33,9 +31,6 @@ Dependency versions come from the root `package.json`. `@webex/web-media-effects | `@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 | -| `js-logger` | semver | Logging | -| `typed-emitter` | semver | Type-safe event emitter (`event-emitter.ts`) | -| `events` | semver | Node-compatible EventEmitter backing | --- @@ -45,30 +40,21 @@ Dependency versions come from the root `package.json`. `@webex/web-media-effects |---|---| | 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 capture | `media/local-audio-stream.ts`, `local-video-stream.ts`, `local-camera-stream.ts`, `local-microphone-stream.ts`, `local-display-stream.ts`, `local-system-audio-stream.ts`, `local-stream.ts` | -| Remote | `media/remote-stream.ts`, `media/stream.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) | -| Shared | `errors.ts`, `event-emitter.ts`, `util/logger.ts` | -| Tests | Co-located `*.spec.ts` (Jest); `media.integration-test.ts` (Karma) | -| Mocks | `mocks/` for unit and integration tests | --- -## 4. Release impact +## 4. Releases -After a published release of `@webex/webrtc-core`, consumers with exact pins must update deliberately: - -- `@webex/web-client-media-engine` pins webrtc-core exactly. -- `@webex/internal-media-core` consumes WCME and receives webrtc-core through WCME's dependency chain. - -Treat exact-pin bumps in downstream repos as part of delivery when changing published behavior or dependencies. +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 Client Media Engine on npm](https://www.npmjs.com/package/@webex/web-client-media-engine) — direct consumer that exact-pins webrtc-core - [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 From be186da13605ae8451c9dd8dcd349b3ece417bbd Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Tue, 18 Aug 2026 16:44:27 +0200 Subject: [PATCH 5/7] docs: update docs commands --- .gitignore | 2 ++ AGENTS.md | 4 +++- package.json | 4 ++-- 3 files changed, 7 insertions(+), 3 deletions(-) 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 index 90fe550..b0a7992 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,7 +65,9 @@ If this document disagrees with `package.json`, workflows, or source code, **the webrtc-core/ ← package root (@webex/webrtc-core) ├── src/ ← TypeScript source + co-located tests ├── dist/ ← build output (ESM, CJS, UMD, types) -├── docs/knowledge-base/ ← architecture pointers for agents +├── 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 diff --git a/package.json b/package.json index 14dee30..625c31e 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/temp ./docs/*.md", + "docs:clean": "rimraf ./docs/temp ./docs/api-reference", "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", From 339321d8fe3abab41716bee4573619430470a2b0 Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Tue, 18 Aug 2026 16:46:07 +0200 Subject: [PATCH 6/7] docs: update clearMocks info --- .github/instructions/testing.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md index d7e35da..35a22be 100644 --- a/.github/instructions/testing.instructions.md +++ b/.github/instructions/testing.instructions.md @@ -28,7 +28,7 @@ When writing or reviewing **unit** tests in `src/**/*.spec.ts`: - `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` — mocks auto-reset between tests. +- `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 From 7724466135f7e61e46b0c8c5703ddf129fa56870 Mon Sep 17 00:00:00 2001 From: Anna Tsukanova Date: Tue, 18 Aug 2026 20:35:22 +0200 Subject: [PATCH 7/7] docs: clean docs:clean --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 625c31e..56e50d8 100644 --- a/package.json +++ b/package.json @@ -85,7 +85,7 @@ "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/temp ./docs/api-reference", + "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/api-reference", "fix": "run-s fix:*",