ActivityPub-federated video streaming platform using P2P directly in your web browser
Use AGENTS.md
Chocobozzz4ccda4656d7f
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mddeleted file mode 100644index a219e7b442..0000000000--- a/.github/copilot-instructions.md+++ /dev/null@@ -1,222 +0,0 @@-# PeerTube Copilot Instructions--## Repository Overview--PeerTube is an open-source, ActivityPub-federated video streaming platform using P2P technology directly in web browsers. It's developed by Framasoft and provides a decentralized alternative to centralized video platforms like YouTube.--**Repository Stats:**-- **Size**: Large monorepo (~350MB, ~15k files)-- **Type**: Full-stack web application-- **Languages**: TypeScript (backend), Angular (frontend), Shell scripts-- **Target Runtime**: Node.js >=20.x, PostgreSQL >=10.x, Redis >=6.x-- **Package Manager**: Yarn 1.x (NOT >=2.x)-- **Architecture**: Express.js API server + Angular SPA client + P2P video delivery--## Critical: Client Directory Exclusion--**π« ALWAYS IGNORE `client/` directory** - it contains a separate Angular frontend project with its own build system, dependencies, and development workflow. Focus only on the server-side backend code.--## Build & Development Commands--### Prerequisites (Required)-1. **Dependencies**: Node.js >=20.x, Yarn 1.x, PostgreSQL >=10.x, Redis >=6.x, FFmpeg >=4.3, Python >=3.8-2. **PostgreSQL Setup**:- ```bash- sudo -u postgres createuser -P peertube- sudo -u postgres createdb -O peertube peertube_dev- sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev- sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev- ```-3. **Services**: Start PostgreSQL and Redis before development--### Installation & Build (Execute in Order)-```bash-# 1. ALWAYS install dependencies first (takes ~2-3 minutes)-yarn install --frozen-lockfile--# 2. Build server (required for most operations, takes ~3-5 minutes)-npm run build:server--# 3. Optional: Build full application (takes ~10-15 minutes)-npm run build-```--**β οΈ Critical Notes:**-- Always run `yarn install --frozen-lockfile` before any build operation-- Server build is prerequisite for testing and development-- Never use `npm install` - always use `yarn`-- Build failures often indicate missing PostgreSQL extensions or wrong Node.js version--### Development Commands-```bash-# Server-only development (recommended for backend work)-npm run dev:server # Starts server on localhost:9000 with hot reload--# Full stack development (NOT recommended if only working on server)-npm run dev # Starts both server (9000) and client (3000)--# Development credentials:-# Username: root-# Password: test-```--### Testing Commands (Execute in Order)-```bash-# 1. Prepare test environment (required before first test run)-sudo -u postgres createuser $(whoami) --createdb --superuser-npm run clean:server:test--# 2. Build (required before testing)-npm run build--# 3. Run specific test suites (recommended over full test)-npm run ci -- api-1 # API tests part 1-npm run ci -- api-2 # API tests part 2-npm run ci -- lint # Linting only-npm run ci -- client # Client tests--# 4. Run single test file-npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts--# 5. Full test suite (takes ~45-60 minutes, avoid unless necessary)-npm run test-```--**β οΈ Test Environment Notes:**-- Tests require PostgreSQL user with createdb/superuser privileges-- Some tests need Docker containers for S3/LDAP simulation-- Test failures often indicate missing system dependencies or DB permissions-- Set `DISABLE_HTTP_IMPORT_TESTS=true` to skip flaky import tests--### Validation Commands-```bash-# Lint code (runs ESLint + OpenAPI validation)-npm run lint--# Validate OpenAPI spec-npm run swagger-cli -- validate support/doc/api/openapi.yaml--# Build server-npm run build:server-```--## Project Architecture & Layout--### Server-Side Structure (Primary Focus)-```-server/core/-βββ controllers/api/ # Express route handlers (add new endpoints here)-β βββ index.ts # Main API router registration-β βββ videos/ # Video-related endpoints-β βββ users/ # User-related endpoints-βββ models/ # Sequelize database models-β βββ video/ # Video, channel, playlist models-β βββ user/ # User, account models-βββ lib/ # Business logic services-β βββ job-queue/ # Background job processing-β βββ emailer.ts # Email service-βββ middlewares/ # Express middleware-β βββ validators/ # Input validation (always required)-β βββ auth.ts # Authentication middleware-βββ helpers/ # Utility functions-βββ initializers/ # App startup and constants-```--### Key Configuration Files-- `package.json` - Main dependencies and scripts-- `server/package.json` - Server-specific config-- `eslint.config.mjs` - Linting rules-- `tsconfig.base.json` - TypeScript base config-- `config/default.yaml` - Default app configuration-- `.mocharc.cjs` - Test runner configuration--### Shared Packages (`packages/`)-```-packages/-βββ models/ # Shared TypeScript interfaces (modify for API changes)-βββ core-utils/ # Common utilities-βββ ffmpeg/ # Video processing-βββ server-commands/ # Test helpers-βββ tests/ # Test files-```--### Scripts Directory (`scripts/`)-- `scripts/build/` - Build automation-- `scripts/dev/` - Development helpers-- `scripts/ci.sh` - Continuous integration runner-- `scripts/test.sh` - Test runner--## Continuous Integration Pipeline--**GitHub Actions** (`.github/workflows/test.yml`):-1. **Matrix Strategy**: Tests run in parallel across different suites-2. **Required Services**: PostgreSQL, Redis, LDAP, S3, Keycloak containers-3. **Test Suites**: `types-package`, `client`, `api-1` through `api-5`, `transcription`, `cli-plugin`, `lint`, `external-plugins`-4. **Environment**: Ubuntu 22.04, Node.js 20.x-5. **Typical Runtime**: 15-30 minutes per suite--**Pre-commit Checks**: ESLint, TypeScript compilation, OpenAPI validation--## Making Code Changes--### Adding New API Endpoint-1. Create controller in `server/core/controllers/api/`-2. Add validation middleware in `server/core/middlewares/validators/`-3. Register route in `server/core/controllers/api/index.ts`-4. Update shared types in `packages/models/`-5. Add OpenAPI documentation tags-6. Write tests in `packages/tests/src/api/`--### Common Patterns to Follow-```typescript-// Controller pattern-import express from 'express'-import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'--const router = express.Router()-router.use(apiRateLimiter) // ALWAYS include rate limiting--router.get('/:id',- validationMiddleware, // ALWAYS validate inputs- asyncMiddleware(handler) // ALWAYS wrap async handlers-)-```--### Database Changes-1. Create/modify Sequelize model in `server/core/models/`-2. Generate migration in `server/core/initializers/migrations/`-3. Update shared types in `packages/models/`-4. Run `npm run build:server` to compile--## Validation Steps Before PR--1. **Build**: `npm run build` (must succeed)-2. **Lint**: `npm run lint` (must pass without errors)-5. **OpenAPI**: Validate if API changes made--## Common Error Solutions--**Build Errors:**-- "Cannot find module": Run `yarn install --frozen-lockfile`-- "PostgreSQL connection": Check PostgreSQL is running and extensions installed-- TypeScript errors: Check Node.js version (must be >=20.x)--**Test Errors:**-- Permission denied: Ensure PostgreSQL user has createdb/superuser rights-- Port conflicts: Stop other PeerTube instances-- Import test failures: Set `DISABLE_HTTP_IMPORT_TESTS=true`--**Development Issues:**-- "Client dist not found": Run `npm run build:client` (only if working on client features)-- Redis connection: Ensure Redis server is running-- Hot reload not working: Kill all Node processes and restart--## Trust These Instructions--These instructions have been validated against the current codebase. Only search for additional information if:-- Commands fail with updated error messages-- New dependencies are added to package.json-- Build system changes are detected-- You need specific implementation details not covered here--Focus on server-side TypeScript development in `server/core/` and ignore the `client/` directory unless explicitly working on frontend integration.diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000000..cf100145b2--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,406 @@+# Project Overview++PeerTube is an open-source, ActivityPub-federated video streaming platform+that uses P2P technology directly in web browsers. Developed by Framasoft+under the AGPL-3.0 license, it provides a decentralized alternative to+centralized video platforms. The server is a Node.js/Express API with a+Sequelize ORM (PostgreSQL), background job processing (BullMQ/Redis),+ActivityPub federation, and an Angular SPA client. Video transcoding is+handled via FFmpeg, with optional distributed runners.++## Repository Structure++- **apps/** β Standalone CLI applications (`peertube-cli`, `peertube-runner`)+- **client/** β Angular frontend SPA (separate build system; ignore for+ backend work)+- **config/** β YAML configuration files for dev, test, and production+- **packages/** β Shared workspace packages (monorepo):+ - `core-utils/` β Shared pure-JS utilities+ - `ffmpeg/` β FFmpeg wrapper library+ - `models/` β Shared TypeScript interfaces and API types+ - `node-utils/` β Node.js-specific helpers+ - `server-commands/` β HTTP client helpers used by tests+ - `tests/` β Full test suite (API, CLI, plugins, feeds, etc.)+ - `transcription/` β Speech-to-text engine integration+ - `transcription-devtools/` β Transcription benchmarking tools+ - `types-generator/` β Generates the public `@peertube/peertube-types`+ package+ - `typescript-utils/` β Generic TypeScript helpers+- **scripts/** β Build, CI, dev, release, and i18n shell scripts+- **server/** β Backend entry point and core application code+ - `server.ts` β Process entry point+ - `core/controllers/` β Express route handlers (API, ActivityPub,+ feeds, tracker)+ - `core/models/` β Sequelize database models (14 categories)+ - `core/lib/` β Business logic (transcoding, live, job queue,+ ActivityPub, plugins, runners, notifications, etc.)+ - `core/middlewares/` β Auth, rate-limiting, validation, caching, CSP+ - `core/helpers/` β Utility functions and custom validators+ - `core/initializers/` β App bootstrap, constants, DB migrations,+ config loading+ - `core/types/` β Internal TypeScript type augmentations+- **support/** β Documentation, Docker, Nginx configs, OpenAPI spec++## Build & Development Commands++### Prerequisites++- Node.js >= 20.x+- pnpm >= 10.9 (do **not** use npm or yarn for install)+- PostgreSQL >= 10 with `pg_trgm` and `unaccent` extensions+- Redis >= 6.x+- FFmpeg >= 4.3+- Python >= 3.8 (for some test tooling)++### Install dependencies++```bash+pnpm install --frozen-lockfile+```++### Build++```bash+# Build server only (backend work)+npm run build:server++# Build full application (server + client)+npm run build++# Build tests+npm run build:tests++# Build individual apps+npm run build:peertube-cli+npm run build:peertube-runner+```++### Development++```bash+# Server-only with hot reload (recommended for backend work)+npm run dev:server # http://localhost:9000++# Full stack (server + Angular client)+npm run dev # server :9000, client :3000++# Dev credentials: root / test+```++### Lint & type-check++```bash+# Full lint (ESLint + OpenAPI validation)+npm run lint++# ESLint only+npm run eslint++# Validate OpenAPI spec+npm run swagger-cli -- validate support/doc/api/openapi.yaml++# TypeScript compilation check+npm run tsc -b server/tsconfig.json+```++### Run in production++```bash+npm run start # server + client+npm run start:server # server only (--no-client)+```++## Code Style & Conventions++### Formatting (enforced by ESLint)++| Rule | Value |+|---------------------|---------------------------------------|+| Semicolons | **never** (`@stylistic/semi`) |+| Max line length | 140 characters |+| Quotes | Single quotes (TypeScript default) |+| Array brackets | Spaces inside `[ 'a', 'b' ]` |+| Trailing newline | Required (`eol-last`) |+| Indentation | 2 spaces (TypeScript convention) |++### Naming patterns++- Database models: `VideoModel`, `UserModel` β PascalCase + `Model` suffix+- Internal type aliases: `MVideo`, `MVideoWithChannel` β `M` prefix for+ Sequelize model types with specific association requirements+- Controllers: one file per resource, registered in parent `index.ts`+- Validators: mirror controller structure under+ `server/core/middlewares/validators/`++### Controller pattern++```typescript+import express from 'express'+import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'++const router = express.Router()+router.use(apiRateLimiter) // always include rate limiting++router.get('/:id',+ validationMiddleware, // always validate inputs+ asyncMiddleware(handler) // always wrap async handlers+)+```++### Commit messages++No formal commit-message template.++### ESLint config++Defined in `eslint.config.mjs`. Extends `eslint-config-love` with+`@stylistic/eslint-plugin`. Applies to `server/**/*.ts`,+`scripts/**/*.ts`, `packages/**/*.ts`, `apps/**/*.ts`. The `client/`+directory has its own lint config.++## Architecture Notes++```+ ββββββββββββββββββββββββββββββββββββββββββββ+ β Reverse Proxy (Nginx) β+ ββββββββββββββββ¬ββββββββββββββββββββββββββββ+ β+ ββββββββββββββββββββΌβββββββββββββββββββββββ+ β Express.js API Server β+ β (server/server.ts β core/controllers/) β+ β β+ β βββββββββββ ββββββββββββ ββββββββββββ β+ β β REST β βActivity- β β Feeds/ β β+ β β API β β Pub β β oEmbed β β+ β β /api/* β β /inbox β β /feeds β β+ β ββββββ¬βββββ ββββββ¬ββββββ ββββββ¬ββββββ β+ β β β β β+ β ββββββΌββββββββββββΌββββββββββββββΌβββββ β+ β β Middleware Pipeline β β+ β β (auth, validators, rate-limit) β β+ β ββββββββββββββββββ¬ββββββββββββββββββββ β+ β β β+ β ββββββββββββββββββΌββββββββββββββββββββ β+ β β Business Logic (lib/) β β+ β β videos, live, transcoding, β β+ β β federation, notifications, β β+ β β plugins, runners β β+ β ββββ¬βββββββββββ¬βββββββββββββββ¬ββββ β+ βββββββΌβββββββββββΌβββββββββββββββΌββββββββ+ β β β+ ββββββββββΌβββ βββββββΌββββββ ββββββββΌβββββββ+ βPostgreSQL β β Redis β β FFmpeg / β+ β(Sequelize)β β (BullMQ β β Runners β+ β β β + cache) β β β+ βββββββββββββ βββββββββββββ βββββββββββββββ+```++**Startup sequence** (`server/server.ts`):++1. Register OpenTelemetry tracing+2. Pre-init checks (config, FFmpeg, Node.js version)+3. Connect to PostgreSQL, run migrations+4. Initialize Sequelize models and load i18n+5. Configure Express middleware stack (proxy trust, CSP, CORS,+ rate-limiting, OAuth2 auth, express-validator)+6. Mount route controllers and start listening++**Key data flows**:++- **Video upload**: REST API β validator middleware β `lib/video.ts` β+ job queue β FFmpeg transcoding β HLS/web-video files β object+ storage or local filesystem+- **Federation**: Incoming ActivityPub requests β signature+ verification β `lib/activitypub/` processors β local DB updates ++ outgoing fan-out+- **Live streaming**: RTMP ingest β FFmpeg segmenter β HLS manifest β+ P2P delivery via WebSocket tracker++## Testing Strategy++### Test framework++- **Mocha** for all server/API tests+- **GNU Parallel** for running test files concurrently in CI+- Tests live in `packages/tests/src/` (TypeScript source) and are+ compiled to `packages/tests/dist/`++### Preparation++```bash+# Create PostgreSQL superuser for test DB management+sudo -u postgres createuser $(whoami) --createdb --superuser++# Clean test databases+npm run clean:server:test++# Build server + tests+npm run build:server+npm run build:tests+```++### Running tests++```bash+# Full suite (slow, ~45-60 min)+npm run test++# Run a specific CI suite+npm run ci -- api-1 # check-params, notifications, search+npm run ci -- api-2 # live, server plugins, users+npm run ci -- api-3 # videos, stats+npm run ci -- api-4 # moderation, redundancy, object-storage,+ # activitypub+npm run ci -- api-5 # transcoding, runners+npm run ci -- client # feeds, client, misc-endpoints, plugins+npm run ci -- cli-plugin # CLI and plugin tests+npm run ci -- lint # ESLint + OpenAPI validation + client lint+npm run ci -- transcription+npm run ci -- external-plugins++# Run a single test file+npm run mocha -- --timeout 30000 --exit --bail \+ packages/tests/src/api/videos/single-server.ts+```++### External test dependencies (Docker)++Some tests require these containers:++```bash+docker run -p 9444:9000 chocobozzz/s3-ninja+docker run -p 10389:10389 chocobozzz/docker-test-openldap+docker run -p 8082:8080 \+ -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \+ -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \+ chocobozzz/peertube-tests-keycloak+```++### CI pipeline++GitHub Actions (`.github/workflows/test.yml`), Ubuntu 22.04, Node.js+20.x. Matrix strategy runs suites in parallel: `types-package`,+`client`, `api-1`β`api-5`, `cli-plugin`, `lint`, `transcription`,+`external-plugins`.++Services provisioned per job: PostgreSQL 10, Redis, LDAP, S3 Ninja,+Keycloak.++### Environment variables for tests++| Variable | Purpose |+|--------------------------------------------|-----------------------------|+| `DISABLE_HTTP_IMPORT_TESTS=true` | Skip flaky HTTP import tests|+| `DISABLE_HTTP_YOUTUBE_IMPORT_TESTS=true` | Skip YouTube import tests |+| `ENABLE_OBJECT_STORAGE_TESTS=true` | Enable S3 tests |++## Security & Compliance++- **License**: AGPL-3.0 β all network-facing modifications must be+ published under the same license.+- **Secrets**: The `secrets.peertube` key in `config/*.yaml` must be+ generated via `openssl rand -hex 32`. Never commit secrets; use+ `config/local-*.json` overrides (gitignored) or environment variables.+- **OAuth2**: Access tokens expire in 1 day; refresh tokens in 2 weeks+ (configurable in `config/default.yaml`).+- **Rate limiting**: All API endpoints are rate-limited by default+ (`apiRateLimiter` middleware). Specific limits per category (login,+ signup, ActivityPub, etc.) are configured in `config/default.yaml`.+- **CSP**: Content-Security-Policy headers are configurable and applied+ via `server/core/middlewares/csp.ts`.+- **Input validation**: Every controller uses express-validator+ middleware defined in `server/core/middlewares/validators/`.+- **Vulnerability reporting**: `[email protected]` β+ see `SECURITY.md`.+- **Dependency scanning**: No automated scanner configuration found in+ the repo.++## Agent Guardrails++### Files and directories agents must NOT modify++- `config/local-*.json` β User-local config overrides (gitignored)+- `config/production.yaml.example` β Template; changes need release+ coordination+- `server/core/initializers/migrations/` β Existing migration files are+ immutable once released; only append new ones+- `pnpm-lock.yaml` β Regenerated by `pnpm install`; never edit manually+- `support/doc/api/openapi.yaml` β Must stay in sync with controllers;+ validate with `npm run swagger-cli -- validate`++### Required checks before pushing++1. `npm run build:server` must succeed+2. `npm run lint` must pass+3. If API surface changed: `npm run swagger-cli -- validate+ support/doc/api/openapi.yaml`+4. If database schema changed: create a new migration file **and**+ increment `LAST_MIGRATION_VERSION` in+ `server/core/initializers/constants.ts`++### Boundaries++- Do not run `pnpm install` without `--frozen-lockfile`+- Do not use `npm install` or `yarn` β this project uses **pnpm**+- Do not add dependencies without explicit approval+- Do not modify test Docker images or CI service definitions without+ review+- Maximum concurrency for background jobs is configured in constants;+ do not change without benchmarking++## Extensibility Hooks++### Plugin system++PeerTube supports server and client plugins via a hook-based+architecture. Plugins register `filter`, `action`, and `static`+hooksβsee `support/doc/plugins/guide.md`.++- Plugin names follow `peertube-plugin-*` (themes: `peertube-theme-*`)+- Server hooks are registered in `server/core/lib/plugins/`+- Plugin management API: `/api/v1/plugins`+- Install/uninstall scripts: `npm run plugin:install`,+ `npm run plugin:uninstall`++### Configuration++All runtime configuration is in YAML under `config/`. Local overrides+use `config/local-*.json` files (gitignored). Key env vars:++| Variable | Purpose |+|-----------------------|--------------------------------------|+| `NODE_ENV` | `production`, `development`, `test` |+| `NODE_CONFIG_DIR` | Override config directory |+| `LOGGER_LEVEL` | `debug`, `info`, `warn`, `error` |+| `PT_INITIAL_ROOT_PASSWORD` | Set root password on first run |++### Runners (distributed transcoding)++External `peertube-runner` processes poll the API for transcoding jobs.+Configured in `server/core/lib/runners/` and managed through the+`/api/v1/runners` endpoints.++### OpenTelemetry++Tracing and metrics are instrumented via `@opentelemetry/*` packages.+Export to Jaeger (tracing) or Prometheus (metrics) is configurable in+`config/default.yaml` under the `open_telemetry` key.++## Further Reading++- [support/doc/development/server.md](support/doc/development/server.md)+ β Server code conventions and new-feature walkthrough+- [support/doc/development/tests.md](support/doc/development/tests.md)+ β Test setup and execution guide+- [support/doc/plugins/guide.md](support/doc/plugins/guide.md)+ β Plugin & theme development guide+- [support/doc/api/openapi.yaml](support/doc/api/openapi.yaml)+ β OpenAPI 3.0 specification+- [support/doc/production.md](support/doc/production.md)+ β Production deployment guide+- [support/doc/docker.md](support/doc/docker.md)+ β Docker deployment guide+- [support/doc/development/lib.md](support/doc/development/lib.md)+ β Library / business-logic documentation+- [SECURITY.md](SECURITY.md) β Vulnerability disclosure policy+- [FAQ.md](FAQ.md) β Frequently asked questionsdiff --git a/client/AGENTS.md b/client/AGENTS.mdnew file mode 100644index 0000000000..7dab716b32--- /dev/null+++ b/client/AGENTS.md@@ -0,0 +1,240 @@+# Client β Angular Frontend SPA++PeerTube's web client is an Angular single-page application served+under `/client/`. It communicates with the backend exclusively through+the REST API (`/api/v1/`). A separate Vite-built embed player lives+in `src/standalone/` for third-party iframe embedding.++## Directory Structure++- **src/app/** β Main Angular application+ - `+about/`, `+admin/`, `+home/`, `+login/`, `+signup/`, etc. β+ Lazy-loaded route modules (prefixed with `+`)+ - `core/` β Singleton services: auth, routing, plugins, theme,+ server config, notifications, screen-size helpers+ - `shared/` β Reusable components & directives organized by domain+ (`shared-video/`, `shared-forms/`, `shared-moderation/`, etc.)+ - `header/`, `menu/`, `modal/` β App shell layout components+ - `helpers/` β Client-side utility functions+ - `hotkeys/` β Keyboard shortcut definitions+ - `app.routes.ts` β Top-level route definitions (lazy-loaded)+ - `app.component.ts` β Root component+- **src/root-helpers/** β Framework-agnostic helpers (logger, storage,+ theme manager, translations, plugin manager) shared between the+ main app and standalone builds+- **src/standalone/** β Independently built artifacts:+ - `player/` β PeerTube video player (Vite build, HLS.js + P2P)+ - `embed-player-api/` β Public npm package for programmatic+ embed control (`@peertube/embed-api`)+ - `videos/` β Embed page (`embed.html`) and test harness+- **src/sass/** β Global SCSS: Bootstrap overrides, PrimeNG theme,+ utility classes, z-index scale, fonts+- **src/locale/** β Angular XLIFF translation files+- **src/assets/** β Static images and assets+- **src/environments/** β Angular environment configs+- **e2e/** β End-to-end tests (WebdriverIO + Mocha)+- **proxy.config.json** β Dev-server proxy to backend (:9000)++## Build & Development Commands++All commands run from the **repository root** unless noted.++### Development++```bash+# Full stack: server (:9000) + Angular dev server (:3000)+npm run dev++# Client only (requires a running backend on :9000)+npm run dev:client++# Embed player only+npm run dev:embed+```++The Angular dev server proxies `/api`, `/plugins`, `/themes`,+`/static`, `/lazy-static`, `/socket.io`, and `/client/assets` to the+backend at `http://127.0.0.1:9000` (see `proxy.config.json`).++### Build++```bash+# Full client build (production)+npm run build:client++# Embed player build+npm run build:embed+```++Output goes to `client/dist/` with per-locale sub-directories+(e.g. `client/dist/en-US/`, `client/dist/fr-FR/`).++### Lint++```bash+# From repository root+cd client++# TypeScript + Angular templates (ESLint)+npm run lint-ts++# SCSS (Stylelint)+npm run lint-scss++# Both+npm run lint+```++### E2E tests++```bash+# Local browser (from repo root)+npm run e2e:local++# BrowserStack+npm run e2e:browserstack+```++E2E uses **WebdriverIO** with a **Mocha** framework. Config files are+in `e2e/` (`wdio.local.conf.ts`, `wdio.browserstack.conf.ts`).++## Code Style & Conventions++### TypeScript / ESLint++The client has its own `eslint.config.mjs` extending+`eslint-config-love` and `angular-eslint`. Key rules match the+server:++| Rule | Value |+|---------------------|-----------------------------------|+| Semicolons | **never** (`@stylistic/semi`) |+| Max line length | 140 characters |+| Array brackets | Spaces inside `[ 'a', 'b' ]` |+| Trailing newline | Required (`eol-last`) |+| Indentation | 2 spaces |++### Angular-specific rules++| Rule | Value |+|------------------------------------------|--------------------------|+| Component selector prefix | `my-` (kebab-case) |+| Directive selector prefix | `my` (camelCase) |+| View encapsulation | Required (enforced) |++### SCSS / Stylelint++Configured in `.stylelintrc.json`, extends+`stylelint-config-sass-guidelines` with `stylelint-order`. Key rules:++- Declaration order: custom properties β declarations β `@include`+- Max nesting depth: 8+- Max compound selectors: 9+- `::ng-deep` pseudo-element allowed++### Naming patterns++- Lazy-loaded route folders: `+feature-name/` (e.g. `+admin/`,+ `+video-watch/`)+- Shared modules: `shared-domain/` (e.g. `shared-video/`,+ `shared-forms/`)+- Services: PascalCase with `Service` suffix+ (`AuthService`, `ServerService`)+- Components: PascalCase with `Component` suffix, selector prefixed+ `my-` (`my-video-miniature`)+- Path aliases: `@app/*` β `src/app/*`,+ `@root-helpers/*` β `src/root-helpers/*`++### Internationalization++- Source locale: `en` (base href `/client/en-US/`)+- Translation files: XLIFF format in `src/locale/`+- Merge tool: `@peertube/xliffmerge` (config: `.xliffmerge.json`)+- Use Angular `$localize` / `i18n` attributes; do NOT use raw strings+ for user-visible text++## Architecture Notes++```+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+β Angular SPA (client/) β+β β+β ββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β+β β Routes β β Core β β Shared β β+β β (+about, β β (auth, REST, β β (forms, video β β+β β +admin, ββββ plugins, ββββ miniature, β β+β β +videos) β β server, β β moderation...) β β+β β β β theme) β β β β+β ββββββββββββ ββββββββ¬ββββββββ ββββββββββββββββββββ β+β β β+β βββββββββββββββββββββββΌβββββββββββββββββββββββββββββ β+β β root-helpers (no Angular dep) β β+β β logger, storage, plugins-manager, theme, i18n β β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β+β βββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β standalone/ (Vite builds) β β+β β player/ β embed-player-api/ β videos/embed β β+β βββββββββββββββββββββββββββββββββββββββββββββββββββ β+ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ+ β HTTP (REST API)+ βΌ+ ββββββββββββββββββββββββ+ β Express Backend β+ β (:9000 /api/v1/*) β+ ββββββββββββββββββββββββ+```++- **Lazy loading**: Each `+feature/` folder exports route configs+ loaded via `loadChildren` in `app.routes.ts`+- **Core services**: Singletons bootstrapped in `main.ts` via+ `getCoreProviders()` β auth, REST client, server config polling,+ plugin hooks, theme manager+- **Plugin hooks**: Client-side plugins register via+ `HooksService` / `PluginService` in `core/plugins/`+- **State management**: No dedicated store library; services hold+ state, components subscribe via RxJS observables+- **UI framework**: Bootstrap 5 + PrimeNG + ng-bootstrap;+ global SCSS in `src/sass/`+- **Video player**: Custom build in `standalone/player/` using+ Video.js + HLS.js + P2P Media Loader; embedded via+ `standalone/videos/embed.html`++## Agent Guardrails++### Files agents must NOT modify++- `src/locale/*.xlf` β Generated translation files; updated via+ `npm run i18n:update` only+- `dist/` β Build output; never edit manually+- `node_modules/` β Managed by pnpm+- `.angular/` β Angular build cache++### Required checks before pushing++1. `cd client && npm run lint` must pass (TS + SCSS)+2. Production build must succeed: `npm run build:client`+ (from repo root)+3. If new user-visible strings added: extract with+ `npm run i18n:create-custom-files` and verify XLIFF++### Boundaries++- Do not import from `server/` β the client communicates with the+ backend exclusively via the REST API+- Do not import Angular-specific code in `root-helpers/` or+ `standalone/` β these must remain framework-agnostic+- Shared API types come from `@peertube/peertube-models` and+ `@peertube/peertube-core-utils` (workspace packages)+- Do not add new npm dependencies without explicit approval++## Further Reading++- [../support/doc/plugins/guide.md](../support/doc/plugins/guide.md)+ β Plugin & theme development (client hooks)+- [src/standalone/embed-player-api/README.md](src/standalone/embed-player-api/README.md)+ β Embed player API documentation+- [../support/doc/api/embeds.md](../support/doc/api/embeds.md)+ β Embed integration guide+- [../AGENTS.md](../AGENTS.md)+ β Root project AGENTS.md (server, build, CI, testing)