Generated Screenshot Audit - 2026-05-22

Scope

Reviewed committed generated screenshots under public/docs/screenshots/packages against the package screenshot contracts in packages/*/docs/screenshots.json.

This audit checks more than file presence:

Screenshot manifest coverage and stale outputs.
Whether CSS/admin styling appears loaded and correctly scoped.
Whether the requested target screen is captured instead of a dashboard, placeholder, theme page, or unrelated surface.
Whether required form fields and layout/content controls are visible when the manifest or source requires them.
Whether frontend screenshots show seeded package content instead of the generic demo shell.

Summary

The generated screenshot set is not correct and should not be published as package documentation.

The manifests themselves validate structurally with node scripts/validate-screenshot-manifests.js, but the generated output directory is stale, incomplete, and visually unreliable. There are 346 generated image files, 233 manifest entries with expected screenshotPath values, 140 missing expected files, and 99 stale non-dark output files that no longer match current manifest paths.

Blockers

1. Content Blocks admin screenshots have catastrophic CSS/layout failure

Example: public/docs/screenshots/packages/content-blocks/content-blocks-admin-create.png

Observed:

The capture is a very tall page dominated by huge unstyled sidebar icons.
Form content is pushed far down the page and is not usable as documentation.
Many admin captures are 11,675-12,798px tall, which is not consistent with normal Filament admin screens.

Affected examples:

content-blocks-admin-accordion.png
content-blocks-admin-assets.png
content-blocks-admin-call-to-action.png
content-blocks-admin-create.png
content-blocks-admin-hero.png
content-blocks-admin-pricing.png
content-blocks-admin-tabs.png
content-blocks-admin-timeline.png

Expected:

A correctly styled admin shell with sidebar, header, form/table content, and block-specific fields visible in the viewport or normal full-page capture.

Assessment:

These are failed screenshots. They show CSS or viewport styling broken during capture.

2. Current layout-builder manifest screenshots are missing

The current packages/layout-builder/docs/screenshots.json requires:

blocks-admin-index.png
create-edit-block-form.png
block-layouts-relation-manager.png
layouts-admin-index.png
page-layout-content-first-editor.png
page-hero-editor.png
public-main-content-render.png
public-layout-area-render.png
layout-health-widget.png
recent-activity-widget.png

None of those files exist in public/docs/screenshots/packages/layout-builder.

The existing files are stale names:

layout-builder-screen.png
create-edit-widget-form.png
widgets-admin-index.png
sections-admin-index.png
frontend-page-rendering-layout-builder-widgets.png

Observed target failure:

public/docs/screenshots/packages/layout-builder/create-edit-widget-form.png renders the dashboard, not a create/edit block or widget form.

Expected from source:

packages/layout-builder/src/Filament/Resources/Blocks/Schemas/BlockForm.php resolves a block configurator and should show block-specific form controls.
packages/layout-builder/src/Filament/Resources/Pages/Schemas/Extenders/PageSchemaExtender.php injects the Layout tab when layout editing is enabled.

Assessment:

Layout Builder screenshots are not valid. The current required layout field/editor captures are absent.

3. Blog create/edit article form is the wrong screen

Example: public/docs/screenshots/packages/blog/create-edit-article-form.png

Observed:

The image renders the dashboard.
It does not show an article form.
It does not show the layout field.
It does not show article translation/content fields, tags, publish controls, or media fields.

Expected from packages/blog/src/Filament/Configurators/Articles/ArticlePageConfigurator.php:

SiteSelect::make()
LayoutSelect::make('layout_id')
TagsInput::make('tags')
PublishSchema::make($configurator)
Translation/content form schema
Settings schema and publish section on edit

Assessment:

Failed target resolution. This screenshot cannot be used as evidence that the article form or layout field renders correctly.

4. Many frontend screenshots show a generic Demo placeholder, not package output

Examples:

public/docs/screenshots/packages/blog/blog-page-frontend-output.png
public/docs/screenshots/packages/blog/archive-page-frontend-output.png
public/docs/screenshots/packages/blog/tag-page-frontend-output.png
public/docs/screenshots/packages/campaign-studio/frontend-landing-page-with-campaign-widgets.png
public/docs/screenshots/packages/form-builder/frontend-form-output.png
public/docs/screenshots/packages/foundation-theme/frontend-page-using-the-foundation-theme.png
public/docs/screenshots/packages/insights/frontend-page-with-tracker-active.png
public/docs/screenshots/packages/navigation/frontend-menu-output.png
public/docs/screenshots/packages/publishing-studio/live-preview.png
public/docs/screenshots/packages/search/frontend-search-results-page.png
public/docs/screenshots/packages/theme-agency/frontend-page-rendered-with-agency-theme.png
public/docs/screenshots/packages/theme-corporate/frontend-page-rendered-with-corporate-theme.png
public/docs/screenshots/packages/theme-saas/frontend-page-rendered-with-saas-theme.png

Observed:

These are visually near-identical placeholder pages with small “Demo” content.
They do not show seeded blog articles, campaign blocks, forms, navigation menus, search results, theme presentation, or package-specific frontend output.

Expected:

Public package surfaces with seeded package content and no admin/editor metadata.

Assessment:

Failed data seeding or URL resolution. These are not valid frontend package screenshots.

5. Admin screenshots often capture a generic dashboard or unrelated admin page

Examples:

public/docs/screenshots/packages/layout-builder/create-edit-widget-form.png captures Dashboard.
public/docs/screenshots/packages/blog/create-edit-article-form.png captures Dashboard.
Several publishing-studio outputs capture Dashboard or generic Pages/Content Scheduler views regardless of the manifest use case.
Login Audit widget output captures a general dashboard, not a login-audit-specific widget state.

Expected:

The screenshot runner must resolve each manifest entry to the exact resource, relation manager, page, widget, modal, tab, or form state requested.

Assessment:

The runner likely falls back to a default admin URL after target resolution fails.

Manifest Coverage Failures

Missing expected files by package:

Package	Missing expected screenshots
newsletter	13
events	11
access-gate	10
layout-builder	10
public-actions	8
html-cache	7
seo-suite	6
blog	5
content-sections	5
site-discovery	5
translation-manager	5
api	4
document-lifecycle	4
notes	4
welcome-tour	4
block-library	3
dashboard-reports	3
demo-kit	3
frontend-authoring	3
ga4-reports	3
password-policy	3
wordpress-importer	3
campaign-studio	2
frontend-optimizer	2
hero	2
login-audit	2
publishing-studio	2
deployments	1
diagnostics	1
foundation-theme	1
media-ai	1
migration-assistant	1
theme-agency	1
theme-corporate	1
theme-saas	1

Package-Level Assessment

Package output present	Assessment
address	Partially valid. Admin index/form screenshots render with Filament styling, but tables are mostly empty and should be reseeded before final documentation.
admin-preview	Invalid. Captures show a generic frontend/theme placeholder with a large arc, not preview panel workflows.
agent-bridge	Invalid/partial. Most captures show the same prompt builder page; server health, token setup, audit entry, and confirmation flows are not distinguishable.
ai-orchestrator	Invalid/partial. Captures show Extensions/Layout pages or placeholders, not the declared approval/capability/layout-preview workflows.
block-library	Stale. Existing 38 outputs are mostly visually coherent, but current manifest expects only 3 different diagnostic/consuming-package screenshots.
blog	Invalid. Admin index is plausible, but create/edit form is Dashboard and frontend pages are generic Demo placeholders. Required article form and layout field are not shown.
campaign-studio	Partial. Campaign group/landing page/form screens are styled, but indexes are empty and frontend campaign block output is a Demo placeholder. Current manifest expects `campaign-dashboard-blocks` and `frontend-landing-page-with-campaign-blocks`, while stale `widgets` names exist.
content-blocks	Invalid. Admin captures have severe CSS/layout failure; frontend block previews are coherent but this output set is stale relative to current `block-library` manifest ownership.
deployments	Partial. Connection page appears styled, but only one of the expected outputs is present.
diagnostics	Mostly plausible. Site health/dashboard pages render with admin styling, but one expected command palette screenshot is missing.
form-builder	Invalid/partial. Admin screens show form mappings, but frontend form output is a Demo placeholder and expected form builder schema/submission screens need direct verification.
foundation-theme	Invalid/partial. Settings screen renders, but frontend/theme screenshots are placeholders or large arc artifacts rather than a styled Foundation theme page/header area.
frontend-authoring	Invalid. Existing images do not include the required public homepage with post-load authoring regions. The admin settings screenshots do not prove the beacon/admin overlay workflow.
html-optimizer	Invalid. Captures show raw/simple frontend content or placeholder arc output, not before/after HTML inspection or middleware registration proof.
insights	Invalid/partial. Settings screen is styled, but frontend tracker and overview/widget screenshots are empty or generic dashboard-like captures.
layout-builder	Invalid. Current required files are missing; stale outputs include wrong target screens. Layout/editor fields are not proven.
login-audit	Partial. Settings and authentication log index render, but data/widgets are empty or generic. Missing user access summary and relation manager outputs.
media-library	Partial. Media admin pages render but are empty; media-ai expected screenshot is missing.
migration-assistant	Invalid/partial. Outputs repeatedly show Import Batches, not the distinct validation, relation resolution, export intent, rollback, and recovery screens.
navigation	Partial. Navigation admin/create screens render; frontend menu output is Demo placeholder and page/site relation captures need target verification.
publishing-studio	Invalid/partial. Some workflow/admin pages render, but several outputs are dashboard/placeholders and current manifest still misses responsibility screenshots.
redirects	Partial. Admin screens render, but generated outputs are stale relative to manifest and need seeded data/import/export state verification.
search	Invalid/partial. Settings screen renders; frontend search results are Demo placeholder; widgets are empty/generic.
seo-suite	Partial. Some admin pages render with styling, but several current manifest outputs are missing and generated pages look generic/repeated.
tags	Partial. Tag admin/form screens render; relation manager/page form context should be verified with seeded tagged records.
theme-agency	Invalid/partial. Theme admin list renders; frontend theme page is placeholder/arc output.
theme-corporate	Invalid/partial. Theme admin list renders; frontend theme page is placeholder/arc output.
theme-saas	Invalid/partial. Theme admin list renders; frontend theme page is placeholder/arc output.

Required Follow-Up Checks Before Regenerating

The screenshot runner should fail a screenshot entry when any of these checks fail:

Requested file path matches the current manifest screenshotPath.
Target URL/resource/page resolves to the intended screen, not Dashboard.
Admin CSS is loaded:
- No giant raw sidebar icons.
- Sidebar/header dimensions match Filament shell.
- Forms/tables render as styled controls, not raw HTML.
Required form fields are visible for create/edit form captures:
- Blog article create/edit must show site, layout, tags, publish controls, translation/content/settings fields.
- Campaign page extension must show campaign group, landing page toggle, primary goal, UTM content, and UTM term when capturing page campaign settings.
- Layout Builder block form must show resolved component/display/settings/translations/asset tabs.
- Layout Builder page editor must show the Layout tab/content-first editor when layout editing is enabled.
Required frontend content is visible:
- Blog screenshots must show article lists/archive/tag output.
- Campaign frontend screenshot must show campaign hero/CTA/form blocks.
- Form Builder frontend screenshot must show a rendered form.
- Navigation frontend screenshot must show a rendered menu.
- Theme screenshots must show the active theme page, not placeholder arc output.
Seeded data is present for table/widget screenshots:
- Empty tables are acceptable only when the manifest explicitly asks for an empty state.
- Dashboard widgets must show package-specific widget state, not generic dashboard fallback.
Browser console/network capture should be retained for each run:
- CSS/JS 404s fail the run.
- Livewire/Filament request failures fail the run.
- Redirect to login/dashboard when a resource was requested fails the run.

Commands Run

node scripts/validate-screenshot-manifests.js
find public/docs/screenshots/packages -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.webp' \) | sort | wc -l

Additional local image checks were run with ImageMagick to identify dimensions, very low visual variance, tiny files, and repeated thumbnail signatures.

Review Artifacts

Temporary contact sheets were generated at:

/tmp/capell-screenshot-review/sheets

These sheets group screenshots by package for faster visual review.

Detailed Follow-Ups

The full entry-by-entry matrix is in docs/generated-screenshot-entry-audit-2026-05-22.md.

The package recapture and preview checklist is in docs/generated-screenshot-recapture-plan-2026-05-22.md.