# Frontend Page & Site Loading Overview

This document explains how Capell's frontend resolves a request into a rendered page, the services involved, and the kernel pipeline steps.

## High-level flow

- A request enters the app and the Frontend middleware invokes the Frontend Kernel.
- The Kernel builds a FrontendWork with the HTTP request and a FrontendState (scoped per request).
- The Kernel runs a sequence of steps (a Laravel Pipeline) to resolve site/domain/language, page, layout, theme, and build a renderable context.
- The result is a FrontendBootstrapResult that may contain:
    - redirect: if the request should be redirected (e.g., default site redirect)
    - error: HTTP error details (e.g., 404 for bots)
    - context: a resolved FrontendContext for rendering

## Container bindings (service provider)

The FrontendServiceProvider registers the key interfaces used by the pipeline:

- UrlSignatureVerifierInterface → FrontendUrlSignatureService
- AssetsRegistryInterface → FrontendAssetsService
- ModelServingInterface → ModelRetrievalTracker
- FrontendSettingsReaderInterface → FrontendSettingsReader
- SettingsMigrationProviderInterface → FrontendSettingsMigrationProvider
- FontMimeTypeResolverInterface → FontMimeTypeResolver

Scoped state:

- FrontendState (scoped per request)
- FrontendContextReader resolves to FrontendState

Kernel registration:

- FrontendKernelInterface is bound to a FrontendKernel with the steps from `config('frontend.kernel.steps')`. Defaults:
1. ParseUrlStep
2. SiteResolveStep
3. NormalizeDomainPathStep
4. VerifyRevisionSignatureStep
5. PageResolveStep
6. ResolveLayoutStep
7. ResolveThemeStep
8. BuildContextStep
9. CommitContextStep
10. RegisterThemeViewsStep
11. NotifySubscribersStep

Aux services:

- ThemeViewRegistrar (singleton)
- FrontendCachePolicy (singleton)
- WidgetRegistry from `capell/core` for legacy block component aliases
- OnFrontendContextResolved listener (singleton)
- Url generator binding switches to SiteUrlGenerator when `capell-frontend.use_site_domain_for_urls` is true; otherwise Laravel UrlGenerator.

## Runtime manifest contributors

`ResolveFrontendRuntimeAction` owns the generic Blade, Livewire, and Inertia runtime decision. Optional packages that need extra public frontend runtime flags should not be referenced directly from `capell/frontend`; they should implement `Capell\Frontend\Contracts\FrontendRuntimeManifestContributor` and tag the implementation with `FrontendRuntimeManifestContributor::TAG`.

Contributors receive the resolved `FrontendContextReader` and mutable `FrontendRuntimeManifestData`, letting add-ons contribute runtime flags while frontend remains safe to install on its own.

## Pipeline steps (summary)

- ParseUrlStep: Normalizes the request path (leading slash, index.php → /, trailing slash alignment) and saves it into state.
- SiteResolveStep: Resolves the site, language, domain, and normalized path from the full URL; optionally issues a redirect to the default site when enabled.
- NormalizeDomainPathStep: Removes the domain path prefix (e.g., `/en`) from the effective URL to obtain the page-relative path.
- VerifyRevisionSignatureStep: Verifies access to a specific page revision when present.
- PageResolveStep: Resolves the target Page; supports wildcard routes, error page fallback, and returns 404 for bot UA when no page is found.
- ResolveLayoutStep: Chooses the layout for the resolved page.
- ResolveThemeStep: Chooses the theme for rendering.
- BuildContextStep: Builds the FrontendContext (data required for rendering).
- CommitContextStep: Commits the context to state for later access.
- RegisterThemeViewsStep: Registers theme view paths for Blade.
- NotifySubscribersStep: Emits FrontendContextResolved to notify listeners.

## Error and redirect handling

- Redirects short-circuit the pipeline and return immediately from the Kernel.
- Errors also short-circuit; bots receive an immediate 404 when the page cannot be resolved.

## Config toggles

- `capell-frontend.redirect_default_site`: When true, unresolved domains redirect to the default enabled SiteDomain.
- `capell-frontend.use_site_domain_for_urls`: Switches URL generation to include site domain rules.
- `capell-frontend.debug_log`: Adds extra debug logging in resolution steps.

## Caching

- FrontendCachePolicy and HtmlCacheMiddleware manage cache behavior.
- Read the [Frontend guide](../../../docs/frontend/guide.md) for HTML caching details.

## Testing coverage

Unit and integration tests validate the pipeline contracts:

- Integration: FrontendKernelTest boots the kernel end-to-end.
- Unit: ResolveLayoutStepTest, ResolveThemeStepTest, VerifyRevisionSignatureStepTest, plus additional tests covering ParseUrlStep, NormalizeDomainPathStep, SiteResolveStep default redirect, and PageResolveStep bot 404.