Imported from AndyStubbs/pijs (AGENTS.md). Install upstream with npx skills add AndyStubbs/pijs. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Pi.js is a browser-only WebGL 2 graphics, sound, and input library. Source code lives in src/: public API modules are under src/api/, rendering code under src/renderer/, core state and utilities under src/core/, and bitmap-font support under src/text/. Optional features are organized as separate packages in plugins/. Build tooling is in scripts/, while generated bundles go to build/; do not edit generated bundles directly. Documentation belongs in docs/, release snapshots in releases/, and development utilities in tools/. The package is ESM ("type": "module"). Node tooling is ESM .js under scripts/, test/scripts/, test/unit/, and test/performance/benchmark/.

Visual regression fixtures are split between test/tests/html-core/ and test/tests/html-plugins/. Their approved PNG baselines live in test/tests/screenshots/. Manual demos and performance checks have dedicated directories under test/.

Build, Test, and Development Commands

• npm install installs the Node 18+ development dependencies.
• npm run build uses esbuild to produce full, lite, ESM, IIFE, and plugin bundles.
• npm run server serves the repository at http://localhost:8080/ for demos and tests.
• npm test runs the complete correctness workflow: test build, Node/browser regressions, metadata/types, and full/lite/plugin visual tests.
• npm run test:unit, npm run test:browser, and npm run test:types run focused checks.
• npm run test:visual -- --mode=full runs a focused visual suite with its own server.
• npm run test:grep -- "Circle" runs matching visual tests only.
• npm run test:plugins runs plugin visuals; wrappers support Windows and POSIX.

Coding Style & Naming Conventions

Follow .editorconfig and .cursorrules: indent with tabs (width 4), use LF endings, keep lines under 100 characters, and use double-quoted strings. Put spaces inside call parentheses (draw( x, y )), but none before control parentheses (if( ready )). Quote object keys and prefer explicit if/else over ternaries. Use camelCase for functions and variables, UPPER_CASE for true constants, and m_ for module-private state. Add file-level JSDoc and document public functions.

Import JavaScript modules with import * as g_moduleName, using camelCase after g_, and access their members through that namespace. Access existing default exports through .default. Keep default imports for shader/font assets and bare imports used for side effects. Consolidate imports from the same module. Reserve g_ for imported bindings and use m_ for private module state.

Comments may divide large blocks into sections, but should describe each section's purpose or responsibility. Preserve explanations of intent and constraints; remove boilerplate such as "Import required modules." Put comments above code with an empty line before each comment block.

Documentation Guidelines

General documentation, including API references, metadata, and LLM references, must describe current behavior only. Do not include change history, removed APIs, before/after comparisons, or migration instructions. Keep those details in dedicated upgrade guides, migration documents, or changelogs.

Testing Guidelines

Tests use Playwright plus deterministic PNG comparison. Name fixtures descriptively with numbered suffixes, such as circle_01.html, and include the required TOML metadata block. Review images in test/test-results/<mode>/screenshots/; never replace approved baselines without deliberate visual review. Reports, logs, and traces are separated by full, lite, and plugins under test/test-results/ and test/playwright-report/. See test/README.md.

Commit & Pull Request Guidelines

Recent history uses short, imperative summaries such as Added custom shaders and Fixed font case. Keep each commit focused and reference an issue when applicable. Pull requests should explain behavior changes, list validation commands, link related issues, and include before/after screenshots for rendering changes. Do not commit build outputs or updated visual baselines unless they are intentional and reviewed.