v1.0.0

Focus 1.0

Focus is stable. From this release it follows semantic versioning. The Versioning docs say what that covers:

• The manifest API: ScreenshotSuite, Screenshot and Card.
• The enums, contracts and exceptions.
• The CLI: its commands, options and exit codes.
• The output file names.
• The card template contract.
• Output-changing defaults: a default that changes existing images needs a new major version.

1.0 adds no features. It is the 0.3 API, now promised. It has been used across eleven packages to generate their documentation screenshots and share cards.

Upgrading from 0.3

• PHP 8.3 or later is now required.
• Internal classes: classes and methods outside the public API are marked @internal, including Runtime\*, Manifest\*, Console\*, Capture and ScreenshotSuite::plan(). Code that used them directly should move to the manifest API. They can change in any release.
• Branch: development continues on the 1.x branch, which is now the default.

Update the constraint to "awcodes/focus": "^1.0", or "^0.3|^1.0" to allow both.

Not in 1.0

Chromium is not pinned to a Focus release yet. A browser or OS font update can change pixels, so generate a repository's images on one machine.

Full changelog: v0.3.0...v1.0.0

v0.3.0

Network fixtures

Captures no longer depend on the network for remote images. Serve any remote URL from a file in your repository:

ScreenshotSuite::make()
    ->fixture('https://www.gravatar.com/avatar/**', 'workbench/fixtures/avatar.png')

The pattern is matched against the whole URL, query string included. Pass a closure instead of a path to choose a file per request. A fixture whose file is missing fails the capture with Fixture failed instead of writing an image with a broken asset.

Filament's default avatar works with no setup. Requests to ui-avatars.com are answered locally with the same initials and colours, so top-bar captures keep a realistic avatar. You no longer need hide('.fi-user-avatar').

Remote request warnings. After each capture, Focus warns about every remote URL that loaded over the network without a fixture, one warning per origin. Accept the ones that should load with allowRemote():

->allowRemote('https://fonts.bunny.net/**')

The themes and stability docs cover fixtures in full. They also explain why pages styled with the system font can differ between runs on macOS, and how to fix that.

Full changelog: v0.2.1...v0.3.0

v0.2.1

Filament size preset

Size::Filament renders the 2560×1440 thumbnails the Filament plugin directory uses. Like the other presets it is a CSS size rendered at the default scale 2, so it needs no scale() call:

Card::make('filament')
    ->template('two-up')
    ->screenshots(['editor', 'picker'])
    ->sizes([Size::Filament]),

The card is written as art/filament-filament-dark.png at exactly 2560×1440. The cards documentation now lists each preset's image size at the default scale.

Full changelog: v0.2.0...v0.2.1

v0.2.0

Cards

Focus can now render cards: share images such as Open Graph cards, GitHub social previews, and video thumbnails. Cards are built from HTML templates, filled with your package's name, description, and install command from composer.json, and the screenshots captured in the same run, so one composer focus keeps your documentation screenshots and share images in step.

return ScreenshotSuite::make()
    ->screenshots([/* ... */])
    ->cardTemplates('https://github.com/awcodes/focus-templates/tree/v1.0.0/dist')
    ->cards([
        Card::make('social')
            ->template('two-up-wide')
            ->screenshots(['editor', 'picker'])
            ->sizes([Size::OpenGraph, Size::GitHubSocial]),
    ]);

• Templates are plain built HTML. A template directory can come from any static site generator; elements with data-focus attributes are filled with values and screenshots. Templates are served from a local origin with network access blocked, so cards render the same way every time.
• Fixed canvases. A template declares its design size with <meta name="focus:canvas" content="2560x1440">, and Focus draws it sharply at every card size, cropping the centre when the aspect ratio differs and warning when it does.
• Templates from GitHub. cardTemplates() accepts a local path or a GitHub reference. Refs are resolved to commits and cached, private repositories work with GITHUB_TOKEN, and offline runs use the cache.
• CLI. Cards render after screenshots in the same browser, and a card whose screenshot failed is not rendered. New options: --cards-only (no Workbench needed), --no-cards, and --refresh-templates. --only and --list include cards.

See the Cards documentation. awcodes/focus-templates is a complete example template repository built with Astro and Tailwind.

Upgrading

• RunObserver has two new methods, cardStarting() and cardFinished(). Implementations outside Focus need to add them.
• A suite with only cards is now valid, and the --only error for an unknown name now reads "Unknown screenshot(s) or card(s)".

Nothing else changes for manifests without cards.

Full changelog: v0.1.1...v0.2.0