Oleg Isonen
d186d24501
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.
Builder e2e
Fast local reruns
Use the full command for CI-like validation:
pnpm e2e:builder
For local test authoring, keep the e2e backend and Builder dev server running and rerun only the matching test. This avoids rebuilding Builder and avoids restarting Docker for every edit.
Terminal 1:
pnpm e2e:builder:dev:backend
Terminal 2:
pnpm dev
Terminal 3:
E2E_TEST_FILTER="Builder can copy, duplicate, and delete a page" pnpm e2e:builder:dev
E2E_TEST_FILTER is a substring match against the test name. It is not a
regular expression. If the filter matches no tests, the runner fails and prints
the available test names before starting Docker or building Builder.
Use E2E_TEST_FILTERS for a newline-separated list of exact or substring
matches. Each entry is matched against both the test name and
<suite> › <test>.
E2E_TEST_FILTERS='Builder can insert through the engine bridge
Builder-created data variables and resources persist' pnpm e2e:builder
CI shards the full e2e suite by file name tags such as
pages-actions.[shard-3].e2e.ts. Use E2E_TEST_SHARD=shard-3 to run one shard.
The goal is to keep all coverage while preventing one long serial e2e command
from hitting the command timeout.
When adding a new e2e file, include one shard tag in the filename:
my-workflow.[shard-1].e2e.ts
my-workflow.[shard-2].e2e.ts
my-workflow.[shard-3].e2e.ts
If one workflow file grows too slow, split it by scenario into files with the same base name and different shard tags:
large-workflow.[shard-1].e2e.ts
large-workflow.[shard-2].e2e.ts
large-workflow.[shard-3].e2e.ts
Choose the shard by current CI timing, not by feature ownership. Put new or expensive files into the fastest shard, and rebalance later by renaming files. CI retries a failed shard once because a single shard rerun is cheap enough to absorb occasional browser/backend flakes.
pnpm e2e:builder:dev defaults to E2E_BUILDER_URL=https://127.0.0.1:3000,
so it runs against the already-running Vite dev server instead of building and
serving the production bundle. Override E2E_BUILDER_URL when the dev server is
running on another port. The E2E harness maps wstd.dev and project subdomains
to loopback for Chromium when this URL is loopback, so focused local runs do not
require machine-level host-file edits.
The dev backend uses E2E_DB_BOOTSTRAP=if-empty and keeps Docker containers
running. The e2e runner still resets test data before each run.
When you need a clean backend:
E2E_SKIP_CLEANUP=false pnpm e2e:builder