HTML Cache Overview

HTML Cache adds static public HTML caching, cache dependency indexing, stale-regeneration queues, and admin tools for maintenance-page cache generation.

What It Adds

• Frontend middleware aliases for cache serving, model-event tracking, and session-cookie prevention on cacheable requests.
• CachedModelUrlResource for inspecting cached URL dependencies.
• MaintenanceCachePage for generating and toggling static maintenance pages.
• Dashboard widgets for cache overview, cache coverage URLs, and regeneration queue status.
• Site health cache-map Livewire component and public cached HTML safety diagnostics.
• Commands for clearing HTML cache, processing stale cache records, and generating static sites.

Install Impact

• Requires capell-app/admin, capell-app/core, and capell-app/frontend.
• Adds cached_model_urls and stale cached URL tables.
• Registers permissions capell-html-cache.view and capell-html-cache.clear.
• Adds frontend cache middleware to the frontend route middleware registry.
• Registers a page_cache filesystem disk when missing.

Admin Surfaces

Surface	URL/route expectation	Notes
Maintenance cache page	/admin/maintenance-cache	Generates maintenance page cache and toggles global/per-site maintenance state.
Cached model URLs resource	Admin resource under Monitoring	Lists cached URLs, model dependencies, site/language scope, and clear/open actions.
Dashboard widgets	Main admin dashboard	Shows cache overview, coverage URLs, and stale queue status.
Page table extender	Core Pages resource	Adds cache state/action context to page tables.
Site header action extender	Core Sites resource	Adds maintenance/cache actions to site-level admin context.
Site health cache map	Site Health page	Shows cache-map diagnostics and public output safety checks.

Frontend Surfaces

Surface	Use case	Screenshot
Cached public page response	Verify cacheable anonymous output is served without session cookies or authoring markers.	html-cache-public-cache-hit
Static maintenance page	Verify generated maintenance HTML for a site/domain.	html-cache-maintenance-page

Demo Setup

Install the core baseline and capell-app/html-cache, run migrations, warm at least one public page, then capture both admin monitoring screens and anonymous public output. For maintenance screenshots, generate a site maintenance page from the admin page before capture.

Screenshot Coverage

The screenshot contract should cover the maintenance page, cached URL index, dashboard widgets, page/site admin extensions, site health cache-map output, a public cache hit, and a static maintenance page.

Public Safety Checks

Anonymous cached HTML must not expose authoring HTML, editor JavaScript, editable markers, model IDs, field paths, permissions, package names, selectors, or signed editor URLs. Keep this check in every final screenshot run for this package.

Verification

Run package tests from the repository root:

vendor/bin/pest packages/html-cache/tests --configuration=phpunit.xml