AGENTS.md

Workspace instructions for coding agents working on this repository.

Scope

• Project type: GNOME Shell extension in GJS with a GTK4 renderer subprocess and a native OpenGL helper.
• Primary goal: keep shell-side code robust and non-blocking while preserving visual/audio parity behavior.
• Canonical high-level docs:
  • README.md
  • CLAUDE.md
  • docs/architecture.md
  • docs/development.md

Quick Start Commands

Run all commands from the repository root.

• Build helper:
  • meson setup build
  • meson compile -C build
• Unit/integration tests:
  • gjs -m tests/run.js
• Parity tests:
  • gjs -m tests/run-parity.js
• Benchmarks:
  • gjs -m tests/bench/run.js
  • gjs -m tests/bench/run.js -- --json
• Local development via just:
  • just install
  • just reinstall
  • just nested
  • just renderer
  • just logs

Mandatory Constraints

• Runtime is GJS, not Node.js. Do not add npm/webpack/transpilation assumptions.
• Do not use eval() or new Function() in expression code.
• Shell process safety first: code under src/extension/ runs in GNOME Shell PID.
• Keep IPC non-blocking; respect bounded queues and backpressure behavior.
• Treat GNOME 47, 48, and 49 compatibility as explicit when touching shell internals.
• Prefer minimal, targeted changes; avoid unrelated refactors.

Architecture Boundaries

• src/extension/: shell-side lifecycle, monitor orchestration, audio capture, evaluator, presets, IPC server.
• src/renderer/: GTK4 renderer process, GtkGLArea, GL bridge/client.
• src/renderer/gl-helper.c: native OpenGL helper and readback path.
• src/shared/: protocol/shared constants.

Before changing cross-process behavior, review:

• docs/architecture.md
• src/shared/ipc-protocol.js
• src/extension/ipc.js
• src/renderer/ipc-client.js

Testing Expectations

• Any change in src/extension/expr/, evaluator, parser, or preset loading should run:
  • gjs -m tests/run.js
  • gjs -m tests/run-parity.js
• Any performance-sensitive or parsing-path change should also run:
  • gjs -m tests/bench/run.js
• Any change touching src/renderer/gl-helper.c should rebuild with Meson before tests.

Known Pitfalls

• GJS introspection APIs may return tuples for getters (for example GStreamer structure integer getters).
• Preset handling must remain crash-resilient; avoid weakening probe/quarantine safeguards.
• GLib idle/timeout callbacks can race with teardown; guard against stale object references.
• Bench and parity tooling assumes repository-root cwd.

Link-First Reference Index

• Architecture and process model: docs/architecture.md
• Development/debug workflows: docs/development.md
• Expression semantics: docs/milkdrop-expression-spec.md
• Parity progress and context: docs/parity-validation-progress.md, docs/projectm-parity.md
• Known decisions and open questions: QUESTIONS.md
• Refactor guardrails: REFACTOR_CHECKLIST.md

Agent Working Style

• Prefer read-only exploration first, then smallest safe patch.
• Preserve existing module boundaries and naming unless change requires otherwise.
• Include concise rationale in commit/patch summaries: what changed, why, and which tests were run.
• If unsure about process ownership (shell vs renderer vs helper), stop and verify before editing.