Files
webstudio/apps/builder/app/shared/db/canvas.server.test.ts
Oleg IsonenandClaude Fable 5 071a4d9a85 feat: MCP update 3 (#5864)
## Summary

This update adds new MCP and CLI capabilities for project auditing,
structured data, project-specific agent instructions, focused project
search, safer bulk editing, image descriptions, font discovery, visual
verification, and external registry inspection.

## New Capabilities

### Audit projects

- Run a single `audit` command across accessibility, SEO, security,
assets, styles, and performance.
- Limit an audit to selected scopes, pages, or severity levels.
- Receive stable findings with locations and suggested fixes.
- Run rendered audits across desktop, mobile, and Builder breakpoint
widths.
- Detect horizontal overflow, broken images, oversized images, eager
below-fold images, render-blocking resources, and legacy font formats.
- Identify unused assets, tokens, CSS variables, local styles, and
breakpoints.
- Identify duplicate token declarations.
- Detect accessibility issues involving names, labels, headings,
landmarks, IDs, keyboard focus, ARIA, iframes, and autoplaying media.
- Detect SEO issues involving titles, descriptions, language, social
images, and structured data.
- Detect unsafe new-tab links and write resources exposed during page
rendering.

### Search an entire project

- Search project text, labels, props, resources, assets, and styles
through `search-project`.
- Find relevant records without downloading and reparsing the full
project snapshot.
- Scope searches to the relevant project-data areas.

### Add validated JSON-LD

- Add structured data with a dedicated JSON-LD component.
- Place JSON-LD inside the page Head Slot.
- Edit JSON in a purpose-built code editor.
- Prevent structurally invalid JSON-LD from being saved.
- Validate Schema.org types, properties, and values.
- Find invalid, missing, unknown, deprecated, or incompatible structured
data through the SEO audit.
- Let agents discover the correct JSON-LD workflow without using page
custom metadata or a generic HTML embed.

### Configure project-specific agent instructions

- Add AI-agent instructions from the new **Agents** section in Project
Settings.
- Synchronize those instructions into a managed root `AGENTS.md`.
- Update or remove the managed file automatically during project sync.
- Protect existing user-owned `AGENTS.md` files from being overwritten.
- Share the instructions with authenticated CLI and MCP agents.
- Keep agent instructions out of publicly readable production bundles.

### Generate and manage image descriptions

- Audit image assets for missing descriptions.
- Let a vision-capable agent inspect each image in its rendered context.
- Save generated descriptions to multiple image assets in one operation.
- Mark images as intentionally decorative.
- Reuse the saved asset description wherever the image is used.
- Re-run the audit to verify that missing-description findings are
resolved.

### Perform bounded bulk replacements

- Replace matching literal text across selected pages with
`replace-text`.
- Replace matching fixed prop text with `replace-prop-text`.
- Replace matching resource names or URLs with `replace-resource-text`.
- Restrict replacements by page, instance, prop, resource, field, match
mode, and maximum change count.
- Leave dynamic expressions unchanged.

### Inspect element ancestry

- Return an element’s direct parent in instance listings.
- Request the complete ancestor chain when inspecting an element.
- Understand tree placement without rebuilding the instance hierarchy
from raw project data.

### Discover available fonts

- List uploaded font families through `list-fonts`.
- Discover available system font stacks.
- Inspect font family, style, weight, format, and associated asset
information before applying typography.

### Inspect external component registries

- Inspect a local or remote shadcn-style registry item.
- Read its description, files, dependencies, targets, and documentation.
- Receive an explicit Webstudio compatibility report.
- Inspect registry metadata without installing or executing external
code.

### Capture generated project routes directly

- Run `webstudio screenshot --path /route` against the configured
project.
- Generate a temporary production-style preview automatically.
- Capture the requested route.
- Stop the temporary preview after capture.
- Avoid manually building and starting a preview for a single
screenshot.

### Assert visual changes

- Add expected text to screenshot comparisons.
- Set maximum pixel mismatch limits.
- Set minimum or maximum changed-region counts.
- Assert whether overall brightness or a color channel moved in the
expected direction.
- Use these assertions as pass/fail evidence for visual changes.

### Require compatible CLI versions

- Send the project-bundle contract version with CLI synchronization
requests.
- Stop incompatible CLI versions before they receive incomplete project
data.
- Tell users exactly how to update the CLI or run the latest version
once.
- Prevent older clients from silently dropping project settings.

## Upgrade Note

This branch introduces a new synchronized project-bundle contract. Older
CLI versions must update before synchronizing against the new API.

```sh
npm install -g webstudio@latest
```

Or run the latest version once:

```sh
npx webstudio@latest <command>
```

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-12 11:27:58 +02:00

145 lines
4.2 KiB
TypeScript

import { expect, test, vi } from "vitest";
import type { Asset } from "@webstudio-is/sdk";
import type { StyleValue } from "@webstudio-is/css-engine";
import {
createImageAssetFixture,
createPublishedProjectBundleFixture,
createSerializedBuildFixture,
} from "@webstudio-is/protocol/fixtures";
import { migratePages } from "@webstudio-is/project-migrations/pages";
import { __testing__ } from "./canvas.server";
const { createLoadPublishedProjectBundleByProjectId, serializeProjectBundle } =
__testing__;
type BundleBuild = Parameters<typeof serializeProjectBundle>[0]["build"];
const createBundleBuild = (
overrides: Partial<BundleBuild> = {}
): BundleBuild => {
const serializedBuild = createSerializedBuildFixture();
return {
...serializedBuild,
pages: migratePages(serializedBuild.pages),
breakpoints: [],
styles: [],
styleSources: [],
styleSourceSelections: [],
props: [],
instances: [],
dataSources: [],
resources: [],
deployment: undefined,
marketplaceProduct: {
category: "pageTemplates",
name: "Test product",
thumbnailAssetId: "asset-id",
author: "Author",
email: "author@example.com",
description: "Description",
},
projectSettings: { meta: {}, compiler: {} },
...overrides,
};
};
test("serializes dev builds into project bundles without requiring deployment", () => {
const build = createBundleBuild();
const asset = createImageAssetFixture({ projectId: build.projectId });
const bundle = serializeProjectBundle({
build,
assets: [asset],
});
expect(bundle.build.id).toBe(build.id);
expect(bundle.build.deployment).toBeUndefined();
expect(bundle.page.path).toBe("");
expect(bundle.assets).toEqual([asset]);
});
test("keeps font assets referenced from nested style values", () => {
const build = createBundleBuild({
styles: [
{
styleSourceId: "token",
breakpointId: "base",
property: "fontFamily",
value: {
type: "layers",
value: [
{
type: "fontFamily",
value: ["TokenFont", "sans-serif"],
},
],
} as unknown as StyleValue,
},
],
});
const fontAsset: Asset = {
id: "font-asset",
projectId: build.projectId,
name: "TokenFont.woff2",
type: "font",
createdAt: "2024-01-01T00:00:00.000Z",
format: "woff2",
size: 100,
meta: { family: "TokenFont", style: "normal", weight: 400 },
};
const bundle = serializeProjectBundle({
build,
assets: [fontAsset],
});
expect(bundle.assets).toEqual([fontAsset]);
});
test("loads project-id bundles from the published build", async () => {
const data = createPublishedProjectBundleFixture();
const project = {
id: "project-id",
latestBuildVirtual: { buildId: "published-build-id" },
} as never;
const context = { context: true } as never;
const loadProductionCanvasDataAndProject = vi.fn().mockResolvedValue({
data,
project,
});
const addProjectMetadata = vi.fn().mockResolvedValue(data);
const loadProjectById = vi.fn().mockResolvedValue(project);
const loadPublishedProjectBundleByProjectId =
createLoadPublishedProjectBundleByProjectId({
addProjectMetadata,
loadProductionCanvasDataAndProject,
loadProjectById,
});
await expect(
loadPublishedProjectBundleByProjectId("project-id", context)
).resolves.toBe(data);
expect(loadProjectById).toHaveBeenCalledWith("project-id", context);
expect(loadProductionCanvasDataAndProject).toHaveBeenCalledWith(
"published-build-id",
context,
project
);
expect(addProjectMetadata).toHaveBeenCalledWith(data, project, context);
});
test("rejects project-id bundle loads for unpublished projects", async () => {
const loadPublishedProjectBundleByProjectId =
createLoadPublishedProjectBundleByProjectId({
addProjectMetadata: vi.fn(),
loadProductionCanvasDataAndProject: vi.fn(),
loadProjectById: vi
.fn()
.mockResolvedValue({ latestBuildVirtual: null } as never),
});
await expect(
loadPublishedProjectBundleByProjectId("project-id", {} as never)
).rejects.toThrow("The project is not published yet");
});