# Capell Frontend

## Package docs status

This page is generated from public package documentation in `capell-4 core packages` and the package manifest checked into the source repository.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/frontend` |
| Package slug | `frontend` |
| Product group | Capell Foundation |
| Tier | free |
| Bundle | `foundation` |
| Runtime contexts | `frontend`, `console` |
| Capell version | `^4.0` |
| Source repository | `capell-app/capell` |
| Source path | `packages/frontend` |
| Docs source | `packages/frontend/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/capell/edit/4.x/packages/frontend/capell.json) |

[![Latest Version on Packagist](https://img.shields.io/packagist/v/capell-app/frontend.svg?style=flat-square)](https://packagist.org/packages/capell-app/frontend)
[![Documentation](https://img.shields.io/badge/docs-docs.capell.app-blue?style=flat-square)](https://docs.capell.app)

`capell-app/frontend` is the public rendering package for Capell CMS. It resolves Core page, site, language, layout, and theme records into Laravel responses and exposes the frontend extension points used by themes and frontend add-ons.

Use this package when a Capell install needs public page routing. It is infrastructure for public delivery, not the default theme or in-page editor.

## Package Boundary

Frontend owns:

- public page routes, frontend middleware, context resolution, page rendering actions, frontend settings, and page-view/cache integration hooks
- Blade components, Livewire page integration, render hooks, frontend asset manifests, Tailwind source aggregation, and cache invalidation registries
- frontend install, after-install, upgrade, static HTML generation, and public render performance reporting commands

Frontend does not own:

- editor UI, settings pages, or admin dashboards; those are Admin surfaces
- theme templates and default visual components; those are theme packages such as `capell-app/foundation-theme`
- generated static HTML cache packages; those are optional cache packages layered on top
- in-page authoring controls; those must load after page load from an authenticated admin-only beacon package

## Install

```bash
composer require capell-app/frontend
php artisan capell:frontend-install
php artisan capell:frontend-after-install
```

For Vite development builds, both install commands accept `--dev`.

On existing apps, use:

```bash
php artisan capell:frontend-upgrade
```

Public routing depends on the host app's web server sending unmatched public page requests to Laravel. See the server configuration docs before debugging route fall-through issues.

## Runtime Surfaces

- Provider: `Capell\Frontend\Providers\FrontendServiceProvider`
- Config: `packages/frontend/config/capell-frontend.php`
- Routes: `packages/frontend/routes/web.php`
- Controller: `Capell\Frontend\Http\Controllers\PageController`
- Middleware aliases: `frontend.resolve`, `frontend.etag`, `frontend.model_events`
- Main commands: `capell:frontend-install`, `capell:frontend-after-install`, `capell:frontend-upgrade`, `capell:generate-html`
- Main extension registries: `RenderHookRegistry`, `CriticalAssetRegistry`, `CacheInvalidationRegistry`, `ReservedFrontendPathRegistry`, `FrontendRouteMiddlewareRegistry`, `FrontendComponentRegistry`, `FrontendRuleConditionRegistry`, `FrontendResponseRendererRegistry`, `TailwindAssetsRegistry`

The package always registers `index.php` and a fallback page route. `/` is only registered when `CAPELL_FRONTEND_REGISTER_HOME_ROUTE=true`. Reserved paths prevent internal or package-owned routes from falling through to public theme rendering.

## Public Output Safety

Public frontend responses must not expose admin/editor implementation details. Blade views, cached HTML, theme output, and public assets should not include authoring JavaScript, editable markers, model IDs, field paths, package names, signed editor URLs, or permission hints.

Frontend authoring must be a post-load admin feature. The public page loads as ordinary HTML; only an authenticated admin beacon response may add edit controls.

When changing public rendering, cache behavior, themes, or beacon integration, keep or add tests that prove anonymous and non-admin responses contain no authoring surface.

## Data And Cache Behavior

Frontend reads Core records and owns frontend settings. Its main persistence impact is settings state; generated page cache files are owned by optional cache/static packages.

Cache invalidation is model-event aware and can run through queues depending on package configuration. If async invalidation is enabled, a queue worker must be running.

Tailwind source/import generation depends on installed packages declaring their frontend sources. Missing package sources usually show up as incomplete generated CSS, not as PHP exceptions.

## Verification

Run package tests after changing frontend routing, render actions, cache invalidation, or public safety checks:

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

For public output changes, include the safety-focused tests:

```bash
vendor/bin/pest packages/frontend/tests/Feature/StaticBladeRenderingTest.php packages/frontend/tests/Feature/MediaComponentMetadataTest.php --configuration=phpunit.xml
```

For browser-level regressions in the demo frontend, run:

```bash
npm run test:demo-smoke
```

Screenshot capture and validation are run from the monorepo root:

```bash
npm run screenshots
npm run screenshots:check
```

## Troubleshooting

- A Capell route catching admin or package URLs usually means the frontend route regex or reserved path registry needs checking.
- Published pages returning 404 should be debugged through site, domain, language, page URL, and layout resolution before changing theme code.
- Stale public output usually means cache invalidation did not run, the queue worker is stopped, or the optional cache package has stale artifacts.
- Missing Tailwind styles usually mean a package did not register its source/import path or frontend assets were not regenerated.
- If `/` does not resolve, check `CAPELL_FRONTEND_REGISTER_HOME_ROUTE`; the package does not register the home route by default.

## Further Reading

| Page                                                         | Covers                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| [Frontend overview](overview.md)                        | Frontend responsibilities and the package docs index.                  |
| [Page and site loading](page-site-loading.md)           | Site, page, language, theme, and layout resolution.                    |
| [Security](security.md)                                 | Package-specific public rendering safety notes.                        |
| [Server configuration](server-config.md)                | Static-cache fallback and web server routing rules.                    |
| [Tailwind assets](tailwind-assets.md)                   | Package Tailwind source and import registration.                       |
| [Render hooks](extending-render-hooks.md)               | Public render hook registration.                                       |
| [Testing frontend](testing-frontend.md)                 | Frontend package test patterns.                                        |
| [Frontend documentation index](../../docs/frontend/index.md) | Host-level frontend rendering, public HTML safety, media, and widgets. |
| [Frontend guide](../../docs/frontend/guide.md)               | Public rendering flow and extension guidance.                          |