Focus Laravel Package

Technical Evaluation

Architecture fit. Focus is a build-time asset generator, not a runtime dependency. It belongs in require-dev alongside static analysis and test tooling, and its failure domain is the documentation and artwork pipeline — never a production request path. That is the single most important architectural fact for a TPM: the criticality is low (a failure blocks regenerating images, not shipping code), which means it can be owned by one engineer on a bounded budget without a support rotation.

The v1.0 shape is what makes it governable. The durable surface is the declarative manifest API — ScreenshotSuite, Screenshot, Card — and everything behind it (Runtime\*, Manifest\*, Console\*, Capture, ScreenshotSuite::plan()) is explicitly marked @internal and can change in any release. That is a clean seam: what we own is the manifest; what we rent is the renderer. It keeps the tool swappable and keeps review conversations about declared assets rather than diffed pixels.

Integration feasibility. Low friction, with one boundary that extends past Composer. Installation is a dev dependency plus a CLI whose commands, options, exit codes, and output filenames are all inside the 1.0 semver promise. That last point is the business case: it promotes screenshot generation from a pre-release chore into an automatable, reviewable pass/fail CI step. A tool whose exit code is contractual is a gate; a tool whose output is a human's judgement is a task. Focus is the former.

The strongest feasibility signal is internal to the release note: the 0.3 API was already used across eleven packages to generate documentation screenshots and share cards before being frozen as 1.0. That is real dogfooding at exactly our intended consumption pattern, and it is worth considerably more than the 5 stars and 0 dependents suggest.

The real integration work is not PHP. It is standing up headless Chromium plus a defined font set on whatever executes the CLI. That is the under-planned boundary in every rollout of this class of tool.

Technical risk. Four items, descending:

1. Pixel non-determinism (dominant, inherent). Chromium is not pinned to a Focus release, and the maintainers state plainly that a browser or OS font update can change pixels — with the guidance to generate a repository's images on one machine. This is acknowledged behaviour, not a bug awaiting a patch. It converts image generation from a reproducible build step into a machine-scoped one, and no future release fixes it. Planning consequence: we nominate one reference render host and document it as a process rule, and we never promise cross-environment pixel determinism to anyone.
2. Narrowed @internal surface at 1.0. Anyone who reached past the manifest API has breakage exposure that semver will not protect them from, and 1.0 is the moment that surface became mutable in any release. A pre-bump grep turns a routine dependency bump into a known quantity instead of a refactor.
3. Description/repo mismatch. The short description describes an unrelated product — a Filament admin "focus mode" UI plugin — while the release notes and docs describe a Playwright screenshot generator. These are not the same artifact. Until we confirm, every downstream estimate carries a confidence discount, and public discoverability and documentation should be assumed weak. Budget internal onboarding notes rather than relying on upstream docs.
4. PHP 8.3 floor. The only upgrade-blocking change between 0.3 and 1.0, and it propagates from this dev dependency into the CI matrix of every consuming package. Verify before committing, not after.

Two risks are reduced by 1.0: it adds no features, so there is no behavioural surprise; and the published semver scope — including the rule that an output-changing default requires a major — gives us a pre-agreed definition of "breaking" for a tool whose primary output is binary images. That removes the usual ambiguity about whether an upgrade is safe to take.

Key questions.

• Which artifact are we actually adopting, given the description/docs conflict? Resolve before a pilot.
• Which repositories import from Runtime\*, Manifest\*, Console\*, Capture, or call ScreenshotSuite::plan() directly? This is the only question that turns a bump into a refactor.
• Is PHP 8.3 already the floor across our Laravel matrix, or does this dev dependency silently raise the minimum for packages still testing 8.1/8.2?
• Do generated images get committed to the repo or built as CI artifacts? Committed binaries make drift a reviewable diff; artifacts make drift invisible until someone opens the docs. For customer-facing imagery, commit.
• Do we have a single reference machine or container image we can nominate as canonical, and does the org accept that constraint as a documented rule?
• Who owns the pinned Chromium and font set, given Focus does not pin them?
• Is a single-maintainer OSS dependency acceptable for a documentation pipeline — low criticality, but non-zero?

Integration Approach

Stack fit. Native to Laravel/PHP and consistent with how the rest of our dev tooling is sourced. The stack boundary extends to headless Chromium plus a defined font set on the executing host — CI runner, container image, or laptop. Treat the render environment as a first-class deliverable of the rollout, with an owner, not as an incidental prerequisite.

Migration path. Mechanical for manifest-API consumers, potentially non-mechanical for everyone else:

• Move the constraint to "awcodes/focus": "^1.0".
• Use "^0.3|^1.0" only as a transitional widening for packages that cannot reach PHP 8.3 immediately. It buys time but leaves two rendering paths live, so it needs an expiry date and a named owner, otherwise it becomes permanent.
• Grep the org for direct references to the newly-internal namespaces and plan(). Rewrite anything found against the manifest API before the bump, not after.
• Track the 1.x branch as the source of truth for examples; 0.3 branch content is no longer the reference.

Compatibility. Two constraints must both be satisfied per consumer: PHP 8.3+ in the CI matrix, and a Chromium/font set matching the nominated reference host. Note that Focus pins neither — so "compatible" is a property of our environment contract, not of the package version alone. Version compatibility with Focus is the easy half.

Sequencing (each step independently revertible):

1. Resolve the description/repo mismatch; confirm the artifact and read the 1.0 upgrade notes directly.
2. Grep for internal-namespace usage across consumers; convert hits to the manifest API.
3. Confirm PHP 8.3 across every consuming CI matrix; identify blockers and set an expiry for any ^0.3|^1.0 widening.
4. Build and document the reference render image (Chromium + fonts), and record the reference-host decision in the repo.
5. Regenerate all committed images on that one host in a separate commit, so the pixel diff is auditable apart from the dependency change. This is the step whose omission makes rollback a guessing game.
6. Wire the CLI into CI and use its exit code as the gate.
7. Only then begin net-new screenshot and share-card work.

Steps 1–4 are prerequisites disguised as overhead. Skipping 4 or 5 is how teams end up with images nobody can reproduce and a diff nobody can attribute.

Operational Impact

Maintenance. Low and predictable. The manifest API is semver-protected through 1.x, and the project's stated policy — an output-changing default requires a major — means routine upgrades are safe to absorb without regenerating every image on spec. The maintenance that is ours is environmental: keeping the reference host's Chromium and fonts stable, and re-baselining deliberately rather than incidentally. Because the manifest is plain PHP, an exit ramp exists — but price in rewriting card templates as the real switching cost if the project stalls.

Support. Single maintainer, 5 stars, 0 dependents. Low criticality makes that tolerable for a docs pipeline, and the @internal boundary limits how deep our coupling goes. The support posture to adopt: depend on the manifest only, and write short internal onboarding notes rather than assuming upstream docs will carry a new engineer — the description mismatch signals that public documentation is not a reliable resource.

Scaling. Scales well along one dimension and poorly along another. More packages and more screenshots is nearly free: one shared visual standard, one card template, one CLI invocation pattern, versus N bespoke scripts and N sets of stale images. That portfolio consistency is the compounding benefit and the main reason to standardise early. What does not scale is render-host proliferation — every additional machine that generates images is a new source of undetected drift. Constrain generation to the reference host; let everyone else consume committed output.

Failure modes, ranked by how quietly they fail:

1. Silent pixel drift from a font or Chromium change. The worst shape, and the one to own explicitly: a missing font renders visibly wrong images that still pass at the exit-code level. The gate is green and the artifact is bad. Mitigations are procedural — pin the render host, commit the images so drift appears as a reviewable diff, and inspect a sample of regenerated output rather than trusting the exit code alone.
2. Undeclared coupling to @internal classes. Breaks without a semver signal, on any release. Preventable only by the pre-bump grep.
3. PHP 8.3 floor silently raising a consumer's minimum. Surfaces as a CI failure on an unrelated package, attributed to the wrong cause.
4. Committed-vs-artifact ambiguity. Choose explicitly. Committed binaries make drift reviewable; CI artifacts make drift invisible until someone opens the docs.
5. Abandonment. Non-zero but bounded. The manifest is plain PHP and the card template contract is documented, so the migration is a rewrite of templates — costed, not catastrophic.

Ramp-up. Roughly a day for an engineer already fluent in Laravel dev tooling: installation, one manifest, one successful local render. The schedule risk is not learning the API — it is provisioning the render environment and establishing the one-host discipline, which is process work, not code. Budget the first adoption as a bounded pilot on one package with a real manifest, then template the pattern across the portfolio. Have that engineer write the internal onboarding note as part of the pilot; with weak upstream discoverability, the second adopter will otherwise repeat the first one's work.

One decision to own explicitly. Chromium is not pinned to Focus, so generated pixels are machine-scoped, not reproducible. Adopt on the basis that image generation is a controlled build step on one nominated host — and do not represent it to stakeholders as reproducible across environments.