Save this content to: AGENTS.md

# packstub/filament-form-builder

Free Filament v4/v5 plugin: a form builder — forms designed in a Filament resource, rendered on the site with Blade, Livewire or a JSON API, submissions stored, emailed, exported and passed to sinks.

## Commands

```bash
composer test               # Pest suite
composer test:filter <name>
composer lint               # Pint
```

## Layout

- `src/Fields/` the field system: `Field` (value object built from the stored JSON), `FieldType` (base class: editor schema, rules, normalisation, Blade view, Filament component), `FieldTypeRegistry`, `Types/` the built-ins.
- `src/Submissions/` the pipeline: `Submitter` (availability → spam → validation → store → events), `SpamGuard` + `ProtectionToken` (honeypot, time trap), `SubmissionContext`, `SubmissionResult`.
- `src/Http/` `SubmitFormController` (HTML redirect back or JSON), `FormDefinitionController`, `ShowFormController` (hosted page), `FormState` (success / errors / old input from the session or the `fb_success` / `fb_state` query params).
- `src/View/Components/Form.php` + `resources/views/components/form.blade.php` + `resources/views/fields/*` the Blade renderer; `resources/css/form-builder.css` and `resources/js/form-builder.js` are inlined once per page.
- `src/Livewire/FormBuilderForm.php` the Livewire renderer (`<livewire:form-builder>`); `src/Livewire/LivewireAssets.php` injects Filament's frontend into the response (like Livewire does its script) and links `resources/dist/livewire.css`, compiled by `npm run build` from `resources/css/livewire.css`, a pick of Filament's component source files (rebuild after a Filament update; `LivewireStylesheetTest` guards the pick).
- `src/Filament/` `FormResource` (Tabs: Fields / Settings / Embed), `FieldBlocks` (the Builder), `SubmissionsRelationManager`, `SubmissionsCsv`.
- `src/FormBuilder.php` (+ facade): field type registration, sinks, `find()`, `submit()` from code. `FormBuilderPlugin` registers types and the resource on a panel.
- `config/packstub-form-builder.php`, `database/migrations/create_form_builder_tables.php.stub`, `resources/lang/en/form-builder.php` (every UI string).
- `docs/` customer docs, synced to packstub.dev by CI (`docs-sync.yml`, needs the `STORE_DEPLOY_KEY` secret).
- `art/` listing art (`banner.jpg`); the source views live in the store repo under `resources/views/art/form-builder/`, rendered with `php artisan packstub:art:render form-builder.banner`.

## Conventions

- Every change needs a test and a `CHANGELOG.md` line. A version's section becomes the top of its GitHub release (the workflow appends the merged pull requests), so keep it short and plain: an optional lead sentence, at most ~6 one-line bullets saying what a user gets, method names only when needed to use them; always keep breaking changes (an `**Upgrading:**` line), security fixes, new minimum versions and migrations to run.
- No hard dependency beyond Filament and `spatie/laravel-package-tools`; anything optional is detected, never required.
- The Blade renderer must keep working without a session and without JavaScript; the Livewire renderer brings Filament's frontend assets itself and must never reset the host page's styles.
- Migrations are additive: a schema change lands in `create_*` and in a guarded `add_*` migration; never rename or drop a column inside a major.