0 Fork 0

mirror of https://github.com/webstudio-is/webstudio.git synced 2026-10-29 08:07:48 +09:00

Files

T

Oleg Isonen d186d24501 feat: Improve MCP project audits, visual verification, and dynamic content authoring (#5874 )

This update helps AI agents understand, audit, and visually verify
Webstudio projects more reliably. It also adds clearer guidance for
expressions, Collections, screenshots, and responsive rendered audits.

### Audit complete projects

- Run one `audit` command across accessibility, SEO, security, assets,
styles, and performance.
- Audit the whole project or focus on a specific page, scope, or
severity.
- Receive stable findings with locations, explanations, and recommended
fixes.
- Continue large result sets through pagination without repeating
general guidance.

### Audit the rendered website

- Build and inspect the generated website, rather than relying only on
stored project data.
- Check every static page at representative mobile, tablet, and desktop
widths.
- Use one suitable viewport inside each configured breakpoint range.
- Reuse the same browser and resize pages between captures for
substantially faster audits.
- Process multiple pages concurrently while keeping resource use
bounded.
- Supply concrete examples for dynamic routes such as blog posts.
- Review and confirm unusually large screenshot plans before they run.

### Find visual and performance problems

Rendered audits can detect:

- Horizontal page overflow.
- Broken images.
- Images loaded eagerly below the fold.
- Images that are much larger than their rendered size.
- Render-blocking resources.
- Legacy font formats.
- Pages that fail to load or redirect somewhere unexpected.
- Pages captured before their layout becomes stable.

Detailed screenshots, measurements, failures, and timing evidence are
saved locally for further inspection.

### Capture generated pages directly

- Capture a project route with `webstudio screenshot --path /route`.
- Automatically generate and start a temporary production-style preview.
- Stop the temporary preview after the screenshot is captured.
- Return navigation, responsive layout, and page-size evidence with JSON
output.
- Allow external image domains needed by the generated preview.

### Reuse generated previews

- Cache generated preview builds when the project has not changed.
- Reuse preview dependencies across regenerations.
- Keep preview dependencies isolated from the user’s project
dependencies.
- Surface preview build and startup failures with useful diagnostic
output.
- Include local project assets in generated previews.

### Author Collections correctly

- Explain when Collection is required for arrays and objects.
- Guide agents to bind the complete iterable instead of one item or the
response wrapper.
- Explain how Collection repeats its children for every entry.
- Explain current-item and current-key scope.
- Preserve Webstudio’s generated Collection parameters.
- Guide agents to use stable values for repeated interactive components.

### Write expressions with fewer mistakes

- Add a dedicated `webstudio://project/expressions` reference.
- Document expression scope, supported syntax, and supported methods.
- Explain how resources, variables, Collections, actions, and `system`
values are accessed.
- Distinguish fixed values from runtime expressions.
- Provide valid examples for text, props, resource URLs, headers, query
parameters, and bodies.
- Warn agents that valid syntax does not guarantee that runtime data has
the expected shape.

### Improve agent discovery

- Make Collection and expression workflows discoverable through
`meta.guide`.
- Return Collection-specific instructions through `components.get`.
- Point relevant command schemas to the expression reference.
- Keep detailed guidance available without placing it in every tool
response.

### Improve audit reliability

- Report which rendered captures passed, found issues, failed, or were
skipped.
- Distinguish planning, preview, capture, and cleanup failures.
- Include actionable retry instructions with rendered failures.
- Preserve completed evidence when part of an audit fails.
- Detect stale or conflicting preview servers more clearly.
- Support cancellation and bounded capture timeouts.

### Improve packaged CLI verification

- Add a release-shaped CLI smoke test.
- Install the packed CLI in an isolated temporary project.
- Fail on peer-dependency warning floods.
- Verify preview, screenshots, MCP calls, rendered audits, and generated
assets.
- Confirm that generic React Router previews do not include Docker-only
image dependencies.
- Keep CLI and MCP stdout machine-readable while progress remains on
stderr.

## User Impact

Agents can now audit a real rendered Webstudio site, inspect responsive
behavior, find concrete visual and performance problems, and provide
evidence for their conclusions. They also receive much clearer
instructions when turning API data into repeated content or writing
dynamic expressions.

2026-07-14 13:52:09 +02:00

1.8 KiB

Raw Permalink Blame History

Webstudio Fixtures

Fixtures are test projects that ensure the CLI and build process work correctly across different deployment targets.

Updating Fixtures After Changes

# From repository root - updates all fixtures
pnpm fixtures

This command will:

Link all fixtures to their respective projects
Sync the latest data from the development environment
Build all fixtures with the latest code

Working with Individual Fixtures

# Go to fixture folder
cd fixtures/webstudio-features

# Link to project
pnpm fixtures:link

# Sync latest data
pnpm fixtures:sync

# Build fixture
pnpm fixtures:build

# Start it
pnpm run dev

Adding Assets to Fixtures

To add a new asset (image, video, audio, etc.) to a fixture:

Publish to staging
- Make your changes in the builder
- Publish to the staging environment
Get the build ID from CI
- After publishing, check the CI logs
- Find the build ID that was created
Update the fixture's build ID
- Edit fixtures/[fixture-name]/package.json
- Update the --buildId parameter in the fixtures:sync script
```
"fixtures:sync": "pnpm cli sync --buildId NEW_BUILD_ID_HERE && pnpm oxfmt ./.webstudio/"
```

Sync with the correct environment

# Go to fixture folder
cd fixtures/webstudio-features

# Sync from staging environment (replace with your branch)
BUILDER_HOST=fix-assets.staging.webstudio.is pnpm run fixtures

Fix the origin URL
- After syncing, edit .webstudio/data.json
- Change the origin back to:
```
"origin": "https://main.development.webstudio.is"
```
- This is necessary because sync changes it to the current branch

Commit the changes

git add fixtures/
git commit -m "chore: update fixtures with new assets"
git push

1.8 KiB Raw Permalink Blame History

Webstudio Fixtures

Updating Fixtures After Changes

Working with Individual Fixtures

Adding Assets to Fixtures

1.8 KiB

Raw Permalink Blame History