Generated Screenshot Recapture Plan - 2026-05-22

Goal

Every package and theme screenshot must be regenerated from a real installed Capell app state, then checked against the current packages/*/docs/screenshots.json manifest entry. A screenshot is not accepted just because it exists or is nonblank.

Acceptance Gates

Every manifest entry must pass these gates before the screenshot is approved:

1. The output filename exactly matches the current manifest screenshotPath.
2. The browser is on the intended resource/page/route/widget/modal, not the dashboard or a fallback page.
3. Filament/admin CSS is loaded, with normal sidebar/header sizing and styled form/table controls.
4. Required seeded data is present unless the manifest explicitly asks for an empty state.
5. Create/edit form screenshots show the required fields, including package-injected fields.
6. Layout Builder screenshots show the layout field, layout tab, content-first editor, block form tabs, or rendered layout area required by the manifest.
7. Frontend screenshots show package-specific public output and no admin/editor metadata.
8. Theme screenshots show the actual theme renderer sections: navigation, hero, features, proof, content listing, CTA, and footer where the theme declares those sections.
9. Browser console errors, CSS/JS 404s, Livewire request failures, and redirects to dashboard/login fail the capture.

Runner Findings

The live screenshot runner exists at ../capell-screenshot-runner. A dry run against this packages repo expanded the manifests to 466 light/dark capture entries:

CAPELL_PACKAGES_REPO=/Users/ben/Sites/packages/capell/capell-packages-4 npm run validate -- --repo /Users/ben/Sites/packages/capell/capell-packages-4

Result:

• Captured: 0
• Skipped: 466
• Failed: 0

That dry run only proves the manifests can be expanded. It does not prove target correctness, CSS health, field visibility, seeded data, or frontend output quality.

The runner needs stricter validation before the next full capture:

• Add defaults for current resource targets such as BlockResource, ArticleResource, current ThemeResource:index entries, and all renamed manifest IDs.
• Fail if an admin capture lands on Dashboard when the manifest target is a resource/form/widget/modal.
• Fail if a waitFor: form entry does not expose expected labels/fields from the manifest or source.
• Fail if Filament sidebar SVG/icons render at raw unstyled dimensions.
• Fail if frontend screenshots contain only the generic Demo placeholder when package-specific content is expected.
• Fail if the output path differs from the manifest screenshotPath.
• Record console errors, failed network requests, final URL, page title, and matched selectors for every screenshot.

Current Package Status

Fail means a present screenshot is known wrong. Missing means the current manifest path is absent. Recapture means the file exists but the required seeded state is not evidenced. Review means the file exists and is plausible, but still needs browser assertions before approval.

Package	Entries	Fail	Missing	Recapture	Review	Notes
access-gate	10	0	10	0	0	Full package capture missing.
address	5	0	0	3	2	Styled admin shell exists, but seeded countries/addresses/site settings state must be proven.
agent-bridge	5	0	0	1	4	Existing screens need target/state assertions; several look like the same prompt builder surface.
ai-orchestrator	3	0	0	0	3	Optional integration states need consuming-package proof.
api	4	0	4	0	0	Full API route capture missing.
block-library	3	0	3	0	0	Current manifest entries missing; old block-library gallery screenshots are stale.
blog	10	4	5	1	0	Article form is Dashboard; frontend outputs are Demo placeholders; widgets/block outputs missing.
campaign-studio	6	0	2	4	0	Admin forms need seeded state; dashboard and frontend campaign block outputs missing.
content-sections	5	0	5	0	0	Full package capture missing.
dashboard-reports	3	0	3	0	0	Dashboard widgets/settings missing.
demo-kit	3	0	3	0	0	Full package capture missing.
deployments	2	0	1	0	1	Connection page exists; widget missing.
diagnostics	6	0	1	0	5	Admin pages plausible; command palette missing and widget/page data needs browser proof.
document-lifecycle	4	0	4	0	0	Full package capture missing.
email-studio	0	0	0	0	0	Manifest intentionally has no visible entries.
events	11	0	11	0	0	Full package capture missing.
form-builder	5	1	0	0	4	Frontend form output is Demo placeholder; admin screens need form/schema/submission assertions.
foundation-theme	4	1	1	0	2	Frontend page is placeholder; header layout area missing; settings/assets need browser proof.
frontend-authoring	5	0	3	0	2	Admin config images exist; public authoring-enabled desktop/mobile captures missing.
frontend-optimizer	2	0	2	0	0	Full package capture missing.
ga4-reports	3	0	3	0	0	Full package capture missing.
hero	2	0	2	0	0	Full package capture missing.
html-cache	7	0	7	0	0	Current manifest outputs missing; existing html-optimizer screenshots are stale.
insights	5	1	0	0	4	Frontend tracker output is placeholder; widgets/settings need seeded data proof.
layout-builder	10	0	10	0	0	Current manifest outputs missing. Stale files do not show layout field/editor requirements.
login-audit	6	0	2	0	4	Settings/logs plausible; user access summary/relation manager missing.
media-ai	1	0	1	0	0	Optional/blocked screenshot missing.
media-library	4	0	0	0	4	Admin pages exist but empty; seed media health/migration/curator field states.
migration-assistant	6	0	1	0	5	Existing screens appear repetitive; relation/export/rollback states need proof.
navigation	5	1	0	0	4	Frontend menu output is Demo placeholder; admin/page relation states need assertions.
newsletter	13	0	13	0	0	Full package capture missing.
notes	4	0	4	0	0	Full package capture missing.
password-policy	3	0	3	0	0	Full package capture missing.
public-actions	8	0	8	0	0	Full package capture missing.
publishing-studio	13	2	2	0	9	Live preview/preview banner are placeholders; responsibility screenshots missing.
search	6	2	0	0	4	Frontend search output is placeholder; widgets/settings need seeded data proof.
seo-suite	11	0	6	0	5	Many current outputs missing; existing pages need distinct target verification.
site-discovery	5	0	5	0	0	Full package capture missing.
tags	4	0	0	0	4	Admin screens exist; relation/page form state needs seeded tagged records.
theme-agency	3	1	1	0	1	Frontend page is placeholder/arc output; admin list/preview need theme record proof.
theme-corporate	3	1	1	0	1	Frontend page is placeholder/arc output; admin list/preview need theme record proof.
theme-saas	3	1	1	0	1	Frontend page is placeholder/arc output; admin list/preview need theme record proof.
translation-manager	5	0	5	0	0	Full package capture missing.
welcome-tour	4	0	4	0	0	Full package capture missing.
wordpress-importer	3	0	3	0	0	Full package capture missing.

Theme-Specific Preview Requirements

The theme packages register section renderers in code, so the screenshot runner must verify those sections visually rather than only checking a theme row exists.

foundation-theme

Required previews:

• Settings screen with Foundation Theme fields visible.
• Public page rendered through Foundation Theme with header, footer, tokens, and components.
• Generated Tailwind asset output review with actual generated asset evidence.
• Header Layout Builder area with a seeded header-area block.

Current issue:

• The public page is a generic placeholder.
• The header-area screenshot is missing.

theme-agency

Required previews:

• Themes admin list showing an Agency theme record.
• /theme-agency-demo rendered through Agency navigation, hero, features, proof, content listing, CTA, and footer.
• Signed preview URL output for the Agency theme.

Current issue:

• Frontend output is a placeholder/arc image, not the Agency renderer.
• The current manifest theme-admin-list-showing-agency.png is missing; stale theme-preset-selection-showing-agency.png exists instead.

theme-corporate

Required previews:

• Themes admin list showing a Corporate theme record.
• /theme-corporate-demo rendered through Corporate navigation, hero, features, proof, content listing, CTA, and footer.
• Signed preview URL output for the Corporate theme.

Current issue:

• Frontend output is a placeholder/arc image, not the Corporate renderer.
• The current manifest theme-admin-list-showing-corporate.png is missing; stale theme-preset-selection-showing-corporate.png exists instead.

theme-saas

Required previews:

• Themes admin list showing a SaaS theme record.
• /theme-saas-demo rendered through SaaS navigation, hero, features, proof, content listing, CTA, and footer.
• Signed preview URL output for the SaaS theme.

Current issue:

• Frontend output is a placeholder/arc image, not the SaaS renderer.
• The current manifest theme-admin-list-showing-saas.png is missing; stale theme-preset-selection-showing-saas.png exists instead.

High-Risk Form/Layout Checks

These entries must be explicitly asserted in browser automation because the existing screenshots either show the wrong screen or do not prove the fields are present.

Package	Entry	Required proof
blog	create-edit-article-form	Article create/edit form with site, layout_id, tags, publish controls, translations/content, settings, and media fields.
layout-builder	create-edit-block-form	Block form with resolved configurator tabs for component, display, settings, translations, and assets.
layout-builder	page-layout-content-first-editor	Page edit screen with Layout tab/content-first layout editor visible and seeded editable block assets.
layout-builder	page-hero-editor	Page edit screen with hero-specific fields injected by the package.
content-sections	sections-create	Blueprint selector visible and controlling available fields.
content-sections	sections-edit-with-assets	Section translations and at least one related block asset/relation manager visible.
campaign-studio	campaign-conversion-goals-form	Goal type, attribution model, active state, and seeded campaign group options.
campaign-studio	cta-block-form	Title, body, button/action, style, tracking, campaign group, and target URL/page fields.
campaign-studio	page campaign extension	Campaign group, landing page toggle, primary goal, UTM content, and UTM term in page sidebar fields.
form-builder	create-edit-form-schema-screen	Form schema builder fields, submission handling settings, and styled controls.
navigation	page-form-navigation-tab	Page form navigation tab with seeded navigation metadata controls.
tags	article-or-page-form-using-tagsinput	Tags input rendered inside an article/page form with seeded tags.

Recapture Order

1. Fix runner correctness first: fail on target fallback, missing CSS, console errors, and missing manifest output path.
2. Recapture layout-builder, blog, foundation-theme, and theme-* first because they underpin the most visible docs and prove layout/theme rendering.
3. Recapture packages with all screenshots missing: access-gate, events, newsletter, public-actions, html-cache, site-discovery, translation-manager, welcome-tour, wordpress-importer, and related packages.
4. Recapture packages with placeholder frontend output: blog, campaign-studio, form-builder, foundation-theme, insights, navigation, publishing-studio, search, and all theme-* packages.
5. Remove stale screenshots after replacement so docs cannot accidentally reference outdated files.