Frontend Authoring

Frontend Authoring

Frontend authoring bridge and in-page editing for Capell frontend.

At A Glance

• Package: capell-app/frontend-authoring
• Namespace: Capell\FrontendAuthoring\
• Surfaces: Livewire, HTTP
• Service providers: packages/frontend-authoring/src/Providers/FrontendAuthoringServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/frontend, capell-app/html-cache
• Third-party dependencies: spatie/laravel-package-tools

Why It Helps Your Capell Workflow

• Lets authenticated admins edit page fields from the public site context without exposing authoring controls to anonymous visitors.
• Protects static caching because the public page loads as ordinary HTML and the admin-only beacon adds editing affordances later.
• Helps editors fix content in place while developers keep signed edit URLs, permissions, and field paths out of public Blade.

Best Used With

• HTML Cache
• Layout Builder
• API

What It Adds

• Frontend authoring bridge and in-page editing for Capell frontend.
• Livewire components: EditRegionField.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin
• Capell Frontend
• Capell HTML Cache

Open-source packages used here

• Spatie Laravel Package Tools - Laravel package bootstrapping for config, migrations, commands, translations, and service provider setup.

Linked package previews

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

The documentation screenshots include the package working inside capell-app: the runner logs in as an admin, opens the public homepage, waits for the beacon to decorate editable regions, and hovers the first region so the edit control is visible.

Code Map

Runtime Surface

• Livewire: EditRegionField.
• Controllers: BeaconController, EditRegionController.
• Routes: packages/frontend-authoring/routes/web.php.

Diagnostics

The package manifest registers FrontendAuthoringHealthCheck as a critical Diagnostics health check. It verifies the beacon route is registered, the enabled config flag is readable, app.key is present for signing, and the editable region registry, editor surface registry, and region signer resolve from the container.

Data And Persistence

• Config: packages/frontend-authoring/config/capell-frontend-authoring.php.
• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install And Setup

• Install with composer require capell-app/frontend-authoring in the host Capell application.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Docs

• docs index
• credits-and-acknowledgements.md
• editable-regions.md
• in-page-editing.md
• overview.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/frontend-authoring/tests --configuration=phpunit.xml

Maintenance Notes

• Never render authoring controls, model identifiers, field paths, selectors, signed editor URLs, or package hints into public HTML. Add editing affordances only after an authenticated admin beacon response.
• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.

Frontend Authoring

Frontend Authoring replaces the old frontend toolbar package. It keeps the beacon route and adds cache-safe in-page editing for rendered frontend pages.

See In-page editing for the full admin flow, screenshot, screenshot-package requirements, and browser-test contract.

Runtime Flow

1. The frontend page renders normally and can be served from HTML cache.
2. The frontend beacon client posts the current URL to capell-frontend.beacon.
3. The beacon resolves the PageUrl and checks admin access.
4. Only for admins with frontend authoring permission for the resolved page, the beacon returns the authoring script and editable region metadata.
5. The browser decorates matching DOM selectors with edit controls.
6. Editing opens a signed route in a modal.
7. The editor revalidates the signed region against the current page manifest, saves the field, clears every cached URL recorded for that model, and refreshes the page.

Cache Rule

Authoring metadata is not rendered into cached Blade, theme output, or public frontend assets. Editable regions are selector-based and returned only from an authenticated admin beacon response. Anonymous and non-admin users must not receive editor HTML, editor JavaScript, labels, selectors, model IDs, field paths, package hints, or signed editor URLs.

If another frontend package wants editable content, it registers regions here. It should not smuggle authoring data into its Blade templates.

Built-In Regions

• Page title: Translation.title
• Page description: Translation.meta.description
• Page content: Translation.content

Additional packages can register regions via the capell-frontend-authoring:editable-regions tag.

Registered regions must be tied to the current page URL, site, language, and a stable region key so signed editor links can be rejected when a region becomes stale or unauthorized.