MMnode/AGENTS.md
turtle89431 4ea8431cd0
Some checks are pending
Publish to Comfy registry / Publish Custom Node to registry (push) Waiting to run
init
2026-09-26 11:11:23 -07:00

108 lines
5.7 KiB
Markdown

# ComfyUI Easy Media
## Tech Stack
- **Backend**: Python, using comfyui-nodes-** skills to develop.
- **Frontend**: React v19, shadcn/ui + Tailwind CSS v4 for components, Lucide for icons, Bun for package manager and build, Vitest for testing.
---
## Build, Test, and Development Commands
### Adding shadcn/ui components
```bash
# From repo root
bunx shadcn add <component-name>
```
## Build
```bash
# Dev build (unminified, outputs to dist/dev) — use during normal development
bun run dev # watch mode with hot reload → dist/dev
bun run build # one-shot dev build → dist/dev
# Release build (minified, outputs to dist/release) — REQUIRED before git commit
bun run build:release # production build → dist/release
```
## Skill Synchronization
- **Keep Codex skills in sync** — When changing any skill in this project, overwrite the corresponding Codex skill with the updated project version so both copies remain identical
## Code Style
### Backend
- **Reuse utils first** — Before writing new code, check `utils/` for existing utility functions; if none exists, add it there instead of duplicating code
- **File naming** — `kebab_case.py` for nodes、utils、modules; `PascalCase.py` for classes
- **Type hints** — Use type hints for all public methods and function parameters
- **Error handling** — Use `try/except` to explicitly catch exceptions; never swallow exceptions silently
### Frontend
- **TypeScript first** — strict mode, no `any` without reason
- **File naming** — `PascalCase.tsx` for components, `camelCase` for dir, `kebab-case.ts` for modules
- **Import aliases** — use `@/*` for `src/` paths
- **React components** — functional only, hooks-based
- **Reusable hooks** — When component logic has reusable state/effect behavior, write it directly in `src/hooks` and call it from components instead of duplicating the logic inline
- **Test location** — Write test cases separately under `src/tests`; do not colocate test files with components or other source modules
- **Never use raw HTML elements** for interactive controls — use shadcn/ui equivalents (`<Button>` not `<button>`, `<Input>` not `<input>`, `<Textarea>` not `<textarea>`, `<Select>` not `<select>`). Exception: `src/components/ui/**` (the shadcn/ui primitives themselves may use raw elements)
- **Error handling** — always handle errors explicitly; never swallow exceptions silently
- **Color tokens only** — All colors are defined as CSS custom properties in `src/styles/global.css` and mapped to Tailwind utilities via `@theme inline`; use theme tokens instead of hardcoded values
- **No raw Tailwind colors** — Do not use raw color utilities such as `text-zinc-*`, `border-slate-*`, `bg-[#...]`, or `text-[#...]`; use classes like `bg-background`, `border-border`, `text-foreground`, and `text-muted-foreground`
- **Color exceptions** — `bg-white` and `bg-black` are allowed for canvas/node editor backgrounds when explicit backgrounds are intentional
- **Adding colors** — Add new colors as CSS custom property tokens in `src/styles/index.css` under `@theme inline`, then consume them through Tailwind utilities
### Sampling Preview Regression Guards
- Tiny VAE preview decoders may return either normalized float pixels (`0..1`) or `uint8` pixels (`0..255`). When interpolating `uint8` preview frames, preserve that scale and cast the result back to `uint8` before generic float conversion. Passing interpolated `0..255` floats through a `0..1` clamp saturates the preview to white.
- Keep `tests/test_sampling_preview.py::test_decode_preview_frames_resamples_uint8_without_clipping_to_white` as a regression test for the white-preview failure.
- The sampling preview belongs to the `easy multitrackProject` node itself. It is not part of `TRACK_DATA` or `MultiTrackWidget`. Keep its DOM widget inside the node layout with bounded min/max height and bounded pointer hit-testing.
---
## Git Workflow
### Branch Strategy
- Switch to `main` and ensure it is up to date before creating a new feature branch when the task requires branch work
- If a matching feature branch already exists, use it instead of creating a duplicate
- For code changes, create feature branches from `main`; documentation-only or assistant-rules changes do not require a new branch unless requested
- When fixing code from an issue, create a branch specifically for that issue
- Before switching or committing, check whether the current branch is behind `main` with conflicting changes; rebase `main` into the current branch if needed
### Commit Rules
- Group commits by feature or responsibility, not only by file type
- Keep `dist/` changes separate from feature/source commits when frontend builds update generated output
- Use `git diff` to inspect changes and decide logical commit grouping before committing
- Use conventional commit messages:
```text
<type>: <description>
<optional body>
```
- Allowed commit types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`
### Pull Request Workflow
- After pushing a branch to remote, create a corresponding PR when requested or when completing branch-based work
- If a similar PR is already open, ask whether to contribute to that PR instead
- When creating PRs, analyze the full branch history, not only the latest commit
- Use `git diff [base-branch]...HEAD` to review the full change set
- Include a concise PR summary and a test plan
- Push with `-u` when publishing a new branch
### Pre-Push Review
- Run applicable reviews before pushing substantial code changes:
- Frontend changes: React/TypeScript review
- Backend changes: Python/ComfyUI node review
- Localization changes: i18n review
- Address review findings and re-run review after major changes