Focus Laravel Package

Product Decisions This Supports

• Build vs. buy for documentation and share-card imagery. Focus replaces hand-captured screenshots and one-off OG-card design with a declarative PHP manifest (ScreenshotSuite, Screenshot, Card) plus a CLI. Recommendation: adopt for standard docs screenshots and social cards; keep engineering effort for genuinely bespoke visuals that fall outside the card template contract.
• Turning a recurring manual chore into a release gate. The 1.0 semver promise explicitly covers the CLI's commands, options, exit codes, and output filenames. That is the single most PM-relevant fact in the release: screenshot generation stops being a pre-release scramble and becomes an automatable, pass/fail CI step. The business case rests here, not on any feature.
• One visual standard across a package portfolio. The 0.3 API was already used across eleven packages to generate documentation screenshots and share cards. For a PM running multiple Laravel packages, that is evidence for a single shared visual identity instead of N ad-hoc approaches and N sets of stale images.
• A pre-agreed definition of "breaking." The versioned surface is named: manifest API, enums, contracts, exceptions, CLI behavior, output filenames, card template contract — with the rule that an output-changing default requires a major. For a tool whose output is binary images, that removes the usual ambiguity over whether an upgrade is safe to take.
• Roadmap framing for 1.0 itself. 1.0 ships no new features; the only upgrade-blocking change is PHP 8.3+. The "what do we get" answer is stability and a contract, not capability. Present the upgrade as risk reduction and budget it as a dependency bump plus one image regeneration — not as a feature release.
• Ownership and resourcing. Criticality is low: a failure blocks regenerating artwork, not shipping code. That makes it viable for one engineer on a bounded budget — provided the render-host decision is made explicitly and written down rather than left implicit.

When to Consider This Package

Adopt when:

• You are a Laravel/PHP package or app needing repeatable documentation screenshots, visual examples, or share cards, generated from source rather than hand-captured.
• You want a manifest-driven, CI-friendly workflow where the CLI exit code is a real quality gate.
• Every consuming package can sit on PHP 8.3+. This propagates from a dev dependency into each consumer's CI matrix — verify before committing, not after.
• You want a semver-backed contract over the manifest, CLI, output filenames, and card template, giving internal onboarding docs a stable target.
• You can nominate a single reference machine or container as the canonical render host, and you accept that as a documented process rule.
• Your team will treat Runtime\*, Manifest\*, Console\*, Capture, and ScreenshotSuite::plan() as internal and port any direct usage to the manifest API.

Look elsewhere when:

• The stack isn't PHP/Laravel, or the PHP 8.3 floor blocks versions you still support.
• You need cross-machine pixel determinism out of the box. Chromium is not pinned to a Focus release, and the maintainers state plainly that a browser or OS font update can change pixels. This is inherent and acknowledged, not a bug awaiting a patch.
• You need a runtime screenshot or dynamic image service rather than build-time assets.
• You need heavily bespoke card layouts beyond the documented template contract.
• You are on 0.3 with direct dependencies on internal classes and no appetite to migrate.

Due-diligence flags — as product/process risks, not engineering objections:

• Description/repo mismatch. The package blurb describes an unrelated product (a Filament "focus mode" admin UI plugin) while the release notes and docs describe a Playwright screenshot generator for Workbench apps. Resolve which artifact you are adopting before any pilot, and assume public discoverability and documentation are weak — budget internal onboarding notes rather than relying on upstream docs.
• Thin adoption signals. 5 stars, 0 dependents, single maintainer. Low criticality makes this tolerable, and because the manifest is plain PHP an exit ramp exists — but price in the cost of rewriting card templates as the switching cost if the project stalls.
• Committed images vs. CI artifacts. Committed binaries make pixel drift a reviewable diff; CI artifacts make drift invisible until someone opens the docs. For anything customer-facing, prefer committed images.

How to Pitch It (Stakeholders)

Executives — 60 seconds. Focus automates our documentation screenshots and social share cards from code. Version 1.0 is a stability release, not a feature release: it freezes a public manifest API and a CLI whose behavior, exit codes, and output filenames are now semver-protected. It has already produced imagery for eleven packages, which weakens the case for maintaining our own image scripts. Expected outcome: less manual design effort, a consistent visual identity across releases, and screenshot generation folded into CI instead of done by hand. Cost is small and bounded — a dev-only Composer dependency, a one-time PHP 8.3 bump, and one nominated machine for rendering.

Engineering — the ask. Move consumers to "awcodes/focus": "^1.0"; use ^0.3|^1.0 only as a transitional widening with an expiry date and a named owner, since it leaves two rendering paths live. Before the bump, grep for direct use of Runtime\*, Manifest\*, Console\*, Capture, and plan() — that is the only thing that turns a routine bump into a refactor. Then: confirm PHP 8.3 across the CI matrix; stand up a documented render image supplying Chromium and the expected fonts; regenerate all committed images on that one host in a separate commit so the pixel diff is auditable apart from the dependency change; wire the CLI into CI using its exit code as the gate; and record the reference-host decision in the repo.

The one risk to own explicitly. Chromium is not pinned to a Focus release, so generated pixels are machine-scoped, not reproducible. Treat image generation as a controlled build step on one host and do not promise cross-environment pixel determinism to anyone. Watch for the worst failure shape: a missing font renders visibly wrong images that still pass at the exit-code level.

Decision requested: approve adoption for the docs pipeline, approve the PHP 8.3 floor, and name an owner for the reference render host.