Save this content to: .cursor/rules/bundle-ux.mdc

# Bundle UX — Stimulus & AssetMapper

## File Naming

- `{name}_controller.js` (snake_case) in `assets/controllers/`
- Stimulus identifier: `vendor--bundle-name--controller` (auto-generated, mandatory namespace)

## Controller Rules

- `/* stimulusFetch: 'lazy' */` mandatory on non-critical controllers
- `disconnect()` cleanup mandatory: abort controllers, destroy instances, `removeEventListener`
- Values: camelCase JS (`debounceValue`) → kebab-case HTML
- Targets: camelCase JS (`inputTarget`) → kebab-case HTML

## Communication

- **Events** (loose coupling, preferred): `CustomEvent` with `bubbles: true`, format `{noun}:{verb}`
- **Outlets** (tight coupling): parent-child only

## Distribution

- Always provide `assets/dist/` with pre-compiled output
- `package.json` with `symfony.controllers` metadata (critical for discovery)
- CSS class names prefixed with bundle name (`acme-blog-`)
- JS packages via `importmap:require` only

## FORBIDDEN

- `node_modules`, `package.json` npm, jQuery, npm/yarn
- `DOMContentLoaded`, `window.onload`, `document.querySelector` (incompatible Turbo)
- Manual `data-controller` / `data-action` / `data-*-target` in Twig (use helpers)
- `"fetch": "eager"` for heavy controllers
- `removeComments: true` in tsconfig (breaks `stimulusFetch: 'lazy'`)
- Business logic in controllers — delegate to server via fetch
- Assets in `public/` — use `assets/` + AssetMapper
- Bare `<script src="">` in Twig templates
- CDN links for JS/CSS libraries — use AssetMapper or inline for self-contained pages

## After Every Change

Run `make quality` to validate the full pipeline.