feat(blueprints): scope get to one field or set

[JorisOrangeStudio]

Description

The format spec for a page builder is proportional to every set it can hold, so on a real blueprint get runs to hundreds of kilobytes and there is no depth that is both usable and returnable: deep enough to describe a component is too large, small enough to return leaves nested groups and bard empty.

Adds a field parameter taking a dot path that narrows the response to one field or set:

field: "page_builder"                          -> that field
field: "page_builder.ContentSection"           -> the fields of that set
field: "page_builder.ContentSection.media"     -> deeper still

Both include_config and include_format_spec are scoped with it.

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🔧 Tool enhancement
• 📝 Documentation
• ♻️ Refactoring

Related Issue

None. Found trying to write a page-builder entry from the tools alone. On a blueprint with eleven component sets, get with include_format_spec returns 193KB at the default max_format_depth: 2 and 217KB on a sibling collection — past the response guard, and past what a client will accept even with the guard raised. Dropping to depth 1 fits at 51.5KB but returns group_fields: [] and no bard set definitions, which is exactly the part you need to write a component.

Testing

• Tests pass (composer test)
• Code quality checks pass (composer quality)
• Tested manually with Statamic

tests/Feature/Routers/BlueprintFieldScopeTest.php — 10 cases: the whole blueprint still comes back without the parameter, a field path, a set path, a path descending into a group, config scoped, format spec scoped, a scoped response smaller than the whole, and three error paths (unknown top-level segment, unknown set, descending into a leaf).

Full gate green — pint, PHPStan level 9, 1116 tests / 5633 assertions.

Environment

• Statamic: v6.31.0
• Laravel: v13.30.1
• PHP: 8.4.25

Checklist

• My code follows the project style
• I've added/updated tests if needed
• Tool responses follow the standard format

Notes

Segments are the handles the spec already publishes — allowed_set_types for a set, group_fields for a group — so an agent can walk down from what it has already read. A path that does not resolve reports the valid segments at the level it failed, which makes the parameter self-teaching in the same way the field-handle errors are.

The truncation message changes with it. It currently says to re-fetch with a higher max_format_depth, which on a large blueprint walks the caller straight into the size guard; it now points at field instead.

Shape: a field path returns blueprint.field, a set path returns blueprint.fields, and both carry blueprint.field_path so a response is self-describing. Without the parameter nothing changes.

Bard is handled by the Replicator check, since Bard extends Replicator.

Touches the same method as #43, so whichever merges second will want the icon_sets block re-applied inside the scoped branch — one line, no semantic conflict.