# Repository Guidelines

## Project Structure & Module Organization
TypeScript sources live in `src/`, organized by EBML component (decoder, encoder, reader, tools). Run `npm run build` to emit compiled JavaScript and type declarations into `lib/`; browser bundles land in `dist/`. Playwright exercises the generated files in `lib/run_test.js`, while demo fixtures and reference WebM assets sit under `test/` and `matroska-test-files/`. Documentation assets are generated into `doc/` via Typedoc, and config files such as `tsconfig.json` and `playwright.config.js` stay at the root.

## Build, Test & Development Commands
Use `npm run build` for a clean TypeScript compile plus browser bundles. `npm run test` installs required Playwright browsers, starts `http-server`, and runs the end-to-end regression suite in headless Chromium. Lint with `npm run lint`; format TypeScript sources using `npm run fmt`. During doc work, run `npm run doc` to refresh API references, and `npm run serve` to host the dist bundle while debugging samples.

## Coding Style & Naming Conventions
Adopt TypeScript with ES module syntax and 2-space indentation. Prefer named exports for reusable utilities, default exports only for primary classes (Decoder, Encoder, Reader). Follow Prettier defaults and let ESLint (@typescript-eslint + prettier config) surface style or safety issues before committing. Keep filenames in `src/` PascalCase when exporting classes and camelCase for utility modules.

## Testing Guidelines
Rebuild before testing so `lib/` and `dist/` stay current. Write Playwright scenarios alongside the generated JS in `src/run_test.ts`, then rebuild to refresh `lib/run_test.js`. Add media fixtures to `matroska-test-files/` when decoding edge cases, keeping files small and licensed for redistribution. Capture failing cases with descriptive assertions so power-assert output remains actionable.

## Commit & Pull Request Guidelines
Use imperative, present-tense messages; Conventional Commit prefixes such as `fix:` and `feat:` match the existing history and ease changelog generation. Each PR should describe the EBML behavior change, list manual verification steps, and reference issues when applicable. Run `npm run build` and `npm run test` locally before requesting review, and attach screenshots or console snippets when the change affects browser demos.

## Security & Tooling Tips
Playwright downloads browsers into your user cache; clear with `npx playwright install --with-deps` when CI environments change. Keep encoded samples private until verified for redistribution, and avoid committing large proprietary media—link to reproduction steps instead.