# Overview.Admin ## What it does Frontend Authoring lets authorised administrators edit selected fields while viewing the public site. The public HTML remains ordinary cacheable output: after the page loads, the browser calls an authenticated beacon and only that response can add the authoring toolbar, editable-region metadata, and signed editor links. ## Setup requirements Install Admin, Core, Frontend, and HTML Cache first. Frontend Authoring has no migrations or settings screen. Its host configuration controls whether it is enabled, the page selectors, and whether compatible edits require approval: - `CAPELL_FRONTEND_AUTHORING` enables the beacon runtime and defaults to true; - `CAPELL_FRONTEND_AUTHORING_REQUIRE_APPROVAL` enables the Publishing Studio path and defaults to false; and - `CAPELL_FRONTEND_AUTHORING_WORKSPACE_NAME` names approval workspaces. The host application must grant the `frontend-authoring.edit` gate, or the underlying record's `editContent`/`update` ability, for the requested page. The package's fallback gate denies access. Being recognised as an administrator is necessary but does not grant edit regions by itself. Package-supplied regions can require additional gates too. The administrator's session cookie must be valid on the public site's origin. The beacon deliberately starts only an existing session; it does not create a guest session or cookie. There is no queue worker or scheduler requirement. ## Edit a page Sign in as an administrator, open the enabled public Page URL on the same origin, and use **Show edit areas** in the toolbar. The built-in regions are the current language's page title, meta description, and content. Other packages can register more regions. A region appears only when its gate allows it, its record still matches the current editable manifest, and its configured CSS selector matches the rendered page. Select a control to open its editor. Editor URLs require authentication, admin access, an unmodified payload, and a temporary Laravel signature; the URL expires after 15 minutes. Reload the public page to obtain fresh controls when a link expires or the page, language, site, selector, or region registration has changed. The editor rechecks the current page identity, site, language, region definition, and permissions on mount and again on save. Fields are required and limited to 65,535 characters. The default regions write only `title`, `content`, or a registered `meta.*` path; a signed payload cannot be changed to expose another model field. ## Live save versus approval With approval disabled, Save writes the live record immediately. Frontend Authoring then finds every HTML-cache URL indexed against that record and clears it; the current URL is requested for refresh, while other affected URLs follow the host's automatic cache-refresh setting. If the edited content is reused on several pages, the cleared count can be greater than one. Reload and verify the public result when cache infrastructure reports an error. With approval enabled, the package uses Publishing Studio only for records that expose a `workspace_id` boundary. It creates a new workspace for the edit, copies the value into that workspace, submits it for approval, and redirects the administrator to a workspace preview. Live content and live HTML cache are not changed by that save. Publishing Studio must be installed, its tables available, and that model registered for workspaces; otherwise the save is rejected with HTTP 409. Records without a workspace boundary still save live even when approval is enabled, so verify each contributed region before relying on approval as a universal gate. Approval submission failures are surfaced rather than silently publishing live. Review the new workspace and its status before retrying, because a failed request may have created workspace state before the approval step failed. ## Content safety boundary Page content HTML is stored exactly as the trusted administrator submits it. Frontend Authoring does not sanitise that field. Grant edit permission only to users trusted to author raw HTML. Output safety for content, titles, and metadata remains the responsibility of the normal public rendering and theme layer; this editor does not add a second sanitisation boundary. Anonymous visitors and authenticated non-admin users receive an empty beacon response with no authoring script, selectors, model IDs, fields, permission names, or signed URLs. Guests also receive no session cookie from the beacon. The beacon is CSRF-exempt so it can compose with cached public HTML, but it accepts only same-origin requests and posted URLs and is throttled to 60 requests per minute. The editor route remains authenticated and signed. Keep `APP_KEY` stable because it signs the encoded region payloads and Laravel editor URLs. Rotating it invalidates outstanding links, which is safe but requires administrators to reload the page. ## Troubleshooting - No toolbar: confirm the package and runtime flag are enabled, the administrator session cookie reaches the public origin, and the beacon URL is same-origin. - Toolbar but no edit controls: confirm `frontend-authoring.edit` or record update permission, the current language has an enabled Page URL and translation, and the configured selectors match the theme markup. - HTTP 403: the user is not an accepted administrator, the gate now denies the region, or its signed/encoded manifest is stale or modified. Reload rather than reusing the URL. - HTTP 404 from the beacon: its posted URL did not resolve to a configured Site Domain. - HTTP 409 on save: approval was requested but Publishing Studio or the model's workspace registration is unavailable. - HTTP 422 or 429 from the beacon: the posted URL failed validation or the per-minute throttle was exceeded. The package stores no separate authoring history. Direct-save history and audit behaviour belong to the edited model; approval history belongs to Publishing Studio.