Package Screenshot Automation

Deployment can generate package screenshots from the committed screenshot manifests. Each package owns a packages/{package}/docs/screenshots.json file, and the aggregate manifest is package-screenshot-manifest.json.

How Deployment Should Use It

1. Install the package and its declared dependencies from capell.json.
2. If the screenshot manifest declares composerRequires, Composer require every listed package before seeding demo data. This is required for cross-package screenshots such as frontend authoring, where the editable page depends on core, admin, frontend, a theme beacon, and the authoring package.
3. Run migrations and package setup/demo commands listed in docs/overview.md.
4. Authenticate as an admin user with the required role or permission.
5. Resolve admin-surface targets through Filament resources or pages.
6. Resolve frontend-url targets through seeded demo routes or package route names.
7. Capture desktop and mobile screenshots. Use scripts/capture-admin-screenshots.mjs for admin surfaces when a manifest declares it, and keep SCREENSHOT_FULL_PAGE=true so long admin form builders are captured in full.
8. Execute any browserTests declared by the package manifest. These tests must run against the installed browser surface, not only server-rendered Blade.
9. Write files to public/docs/screenshots/packages/{package}.

Manifest Contract

• package: package slug.
• composerName: Composer package name where available.
• composerRequires: optional list of Composer packages the screenshot/demo environment must require before capture.
• outputDirectory: deployment output path.
• entries[].surface: admin or frontend.
• entries[].targetType: admin-surface or frontend-url.
• entries[].target: resource/page class name when known, otherwise deployment resolves from seeded content.
• entries[].docsPage: optional markdown page where the screenshot is referenced.
• entries[].output: optional concrete output file when the package commits a docs screenshot or requires a stable filename.
• browserTests: optional browser scenario contracts the deployment runner must execute after package installation.
• runner: optional screenshot runner path, such as scripts/capture-admin-screenshots.mjs.
• capture.fullPage: when true, the runner should capture the full scrollable page instead of only the viewport.

Notes

The package repo does not need to run a browser during docs generation. It commits the contract that the demo/docs deployment can consume after package installation.