Skip to content

AGENTS.md

Latest commit

 

History

History
54 lines (39 loc) · 4.28 KB

AGENTS.md

File metadata and controls

54 lines (39 loc) · 4.28 KB
Raw

SolidJS 2 Beta

  • This project uses SolidJS 2 beta, not SolidJS 1.x.
  • All SolidJS code must strictly follow doc/MIGRATION.md.
  • Before adding or changing SolidJS APIs, patterns, imports, JSX types, effects, lifecycle hooks, list rendering, stores, or reactive behavior, consult the migration guide and use the SolidJS 2 beta form.
  • Do not introduce SolidJS 1.x-only APIs or patterns. In particular, createEffect must use the SolidJS 2 compute/apply signature described in the migration guide.

UnoCSS and Wind3

  • This project uses UnoCSS, not Tailwind CSS. Styling utilities are generated by the UnoCSS Vite plugin and configured in uno.config.ts.
  • The utility preset is presetWind3() from unocss. All utility classes must follow the Wind3-compatible syntax already used by the project.
  • Do not introduce Tailwind configuration files, Tailwind-specific plugins or directives, presetWind4(), or another UnoCSS preset unless the project explicitly migrates to it.
  • Before adding utility syntax that may be preset-specific, verify that it is supported by the installed UnoCSS version and presetWind3().
  • Preserve the existing presetIcons() integration and use the configured UnoCSS icon utilities for icons already covered by the project icon system.

Feature Design and Reuse

  • Avoid implementing features as layers of narrowly scoped patches, duplicated state, callbacks, or special-case branches.
  • Before adding new logic, identify and reuse the existing components, state flows, interaction handling, and abstractions that already cover the behavior.
  • If the existing design is not compatible with the feature, prefer a focused refactor that simplifies and generalizes the shared logic before adding the new behavior.
  • Keep feature changes cohesive: each piece of state should have a clear owner, related behavior should use one code path, and tests should verify the shared behavior rather than implementation-specific workarounds.
  • Prefer extracting logic into small, side-effect-free pure functions with explicit inputs and outputs so it can be covered by focused unit tests. Keep state management, I/O, and UI interaction at the boundaries.
  • Organize code by clear ownership. Keep related state and behavior together, and let higher-level modules compose lower-level APIs.

Modules and Public APIs

  • Keep cohesive modules in one file. Create a directory only when the module genuinely needs multiple files.
  • Use index.ts as an intentional public entry point, not a forwarding layer. Avoid wildcard exports and chains of re-exports.
  • Keep public APIs minimal. Export only what consumers need; internal code and tests should import implementation files directly.

Version Control

  • Use git as the primary version control system for this repository.
  • Prefer git commands and workflows for status checks, history inspection, branches, commits, and pushes.
  • When asked to "separately push" multiple changes, treat that as separate commits pushed sequentially to main by default, not separate branches or pull requests, unless explicitly requested.

Commit Messages

  • All commit messages must follow Conventional Commits: <type>(<scope>): <summary>.
  • Example: chore(init): initial import.

Testing

  • Do not run end-to-end (e2e) tests unless the user explicitly requests them.
  • Do not add or maintain UI tests. This includes component rendering tests, DOM interaction tests, visual or snapshot tests, and browser/end-to-end UI flows.
  • Validate UI-only changes with type checking, linting, and production builds instead of automated UI tests.
  • Co-locate unit tests with the source they cover using *.test.ts or *.test.tsx; split tests that cover unrelated modules.
  • Keep only shared fixtures in tests/fixtures, and do not expand public APIs for tests.

Portrait Centering

  • doc/PORTRAIT_CENTERING.md is the maintenance reference for portrait centering, face detection, target selection, recovery scanning, coordinate mapping, camera motion, motion prediction, and adaptive inference scheduling. UI behavior is outside its scope.
  • Any change to those algorithms must update doc/PORTRAIT_CENTERING.md in the same change.
  • Update the corresponding portrait-centering unit tests whenever an algorithm changes.