Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

feat: Improve MCP authoring, compact output, and agent onboarding (#5883)

Oleg Isonendde30ffb54bc
diff --git a/apps/builder/app/builder/features/address-bar.tsx b/apps/builder/app/builder/features/address-bar.tsx
index e64067084a..a6e31b2eac 100644
--- a/apps/builder/app/builder/features/address-bar.tsx
+++ b/apps/builder/app/builder/features/address-bar.tsx
@@ -32,7 +32,7 @@ import {
isPathnamePattern,
matchPathnamePattern,
tokenizePathnamePattern,
-} from "@webstudio-is/project-build/runtime/url-pattern";
+} from "@webstudio-is/project-build/runtime";
import {
$selectedPage,
$selectedPagePath,
diff --git a/apps/builder/app/builder/features/breakpoints/breakpoints-container.tsx b/apps/builder/app/builder/features/breakpoints/breakpoints-container.tsx
index 7a58bc2bde..bace730670 100644
--- a/apps/builder/app/builder/features/breakpoints/breakpoints-container.tsx
+++ b/apps/builder/app/builder/features/breakpoints/breakpoints-container.tsx
@@ -12,7 +12,7 @@ import { BreakpointsMenu } from "./breakpoints-menu";
import { BreakpointsEditor } from "./breakpoints-editor";
import { ConfirmationDialog } from "./confirmation-dialog";
import { $breakpointsMenuView } from "~/shared/breakpoints";
-import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime/breakpoints";
+import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime";
import { setCanvasWidth } from "../../shared/calc-canvas-width";
import type { Breakpoint } from "@webstudio-is/sdk";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
diff --git a/apps/builder/app/builder/features/breakpoints/breakpoints-editor.tsx b/apps/builder/app/builder/features/breakpoints/breakpoints-editor.tsx
index 0fedea91e6..ebb874d142 100644
--- a/apps/builder/app/builder/features/breakpoints/breakpoints-editor.tsx
+++ b/apps/builder/app/builder/features/breakpoints/breakpoints-editor.tsx
@@ -26,7 +26,7 @@ import {
groupBreakpoints,
hasReachedBreakpointLimit,
isBaseBreakpoint,
-} from "@webstudio-is/project-build/runtime/breakpoints";
+} from "@webstudio-is/project-build/runtime";
import { ConditionInput } from "./condition-input";
import { CssValueInput } from "~/builder/features/style-panel/shared/css-value-input";
import { useDraftValue } from "~/builder/shared/use-draft-value";
diff --git a/apps/builder/app/builder/features/breakpoints/breakpoints-menu.tsx b/apps/builder/app/builder/features/breakpoints/breakpoints-menu.tsx
index 2c88a24bfb..77f711721c 100644
--- a/apps/builder/app/builder/features/breakpoints/breakpoints-menu.tsx
+++ b/apps/builder/app/builder/features/breakpoints/breakpoints-menu.tsx
@@ -12,7 +12,7 @@ import {
Button,
} from "@webstudio-is/design-system";
import { EllipsesIcon } from "@webstudio-is/icons";
-import { groupBreakpoints } from "@webstudio-is/project-build/runtime/breakpoints";
+import { groupBreakpoints } from "@webstudio-is/project-build/runtime";
import { $selectedBreakpointId } from "~/shared/nano-states";
import { setCanvasWidth } from "../../shared/calc-canvas-width";
diff --git a/apps/builder/app/builder/features/breakpoints/breakpoints-selector.tsx b/apps/builder/app/builder/features/breakpoints/breakpoints-selector.tsx
index 4a05906f66..a8ff1c1ac5 100644
--- a/apps/builder/app/builder/features/breakpoints/breakpoints-selector.tsx
+++ b/apps/builder/app/builder/features/breakpoints/breakpoints-selector.tsx
@@ -20,7 +20,7 @@ import { $breakpoints } from "~/shared/sync/data-stores";
import {
groupBreakpoints,
isBaseBreakpoint,
-} from "@webstudio-is/project-build/runtime/breakpoints";
+} from "@webstudio-is/project-build/runtime";
import { setCanvasWidth } from "../../shared/calc-canvas-width";
import { $canvasWidth } from "~/builder/shared/nano-states";
import { useDebouncedCallback } from "use-debounce";
diff --git a/apps/builder/app/builder/features/breakpoints/cascade-indicator.tsx b/apps/builder/app/builder/features/breakpoints/cascade-indicator.tsx
index f44d0a6dc2..d8997db9a5 100644
--- a/apps/builder/app/builder/features/breakpoints/cascade-indicator.tsx
+++ b/apps/builder/app/builder/features/breakpoints/cascade-indicator.tsx
@@ -3,7 +3,7 @@ import { useStore } from "@nanostores/react";
import { css, theme } from "@webstudio-is/design-system";
import type { Breakpoint, Breakpoints } from "@webstudio-is/sdk";
import { $breakpoints } from "~/shared/sync/data-stores";
-import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime/breakpoints";
+import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime";
const cascadeIndicatorStyle = css({
position: "absolute",
diff --git a/apps/builder/app/builder/features/command-panel/groups/components-group.tsx b/apps/builder/app/builder/features/command-panel/groups/components-group.tsx
index d77874b9c8..ebebe5e9b9 100644
--- a/apps/builder/app/builder/features/command-panel/groups/components-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/components-group.tsx
@@ -12,7 +12,7 @@ import {
flattenBuilderComponentPanelItems,
listBuilderComponentPanelItems,
type BuilderComponentPanelItem,
-} from "@webstudio-is/project-build/runtime/component-catalog";
+} from "@webstudio-is/project-build/runtime";
import {
$registeredComponentMetas,
$registeredTemplates,
diff --git a/apps/builder/app/builder/features/command-panel/groups/convert-group.tsx b/apps/builder/app/builder/features/command-panel/groups/convert-group.tsx
index ce4c96f345..3c21b00a15 100644
--- a/apps/builder/app/builder/features/command-panel/groups/convert-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/convert-group.tsx
@@ -21,7 +21,7 @@ import {
getInstanceLabel,
InstanceIcon,
} from "~/builder/shared/instance-label";
-import { canConvertInstance } from "@webstudio-is/project-build/runtime/instances";
+import { canConvertInstance } from "@webstudio-is/project-build/runtime";
import {
$commandContent,
$isCommandPanelOpen,
diff --git a/apps/builder/app/builder/features/command-panel/groups/data-variables-group.tsx b/apps/builder/app/builder/features/command-panel/groups/data-variables-group.tsx
index 75ae627ee6..23e3c68ea2 100644
--- a/apps/builder/app/builder/features/command-panel/groups/data-variables-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/data-variables-group.tsx
@@ -32,7 +32,7 @@ import {
import type { BaseOption } from "../shared/types";
import { formatUsageCount, getUsageSearchTerms } from "../shared/usage-utils";
import { getInstanceLabel } from "~/builder/shared/instance-label";
-import { findVariableUsagesByInstance } from "@webstudio-is/project-build/runtime/data";
+import { findVariableUsagesByInstance } from "@webstudio-is/project-build/runtime";
export type DataVariableOption = BaseOption & {
type: "dataVariable";
diff --git a/apps/builder/app/builder/features/command-panel/groups/duplicate-tokens-group.tsx b/apps/builder/app/builder/features/command-panel/groups/duplicate-tokens-group.tsx
index 4e3692b87d..700b814d96 100644
--- a/apps/builder/app/builder/features/command-panel/groups/duplicate-tokens-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/duplicate-tokens-group.tsx
@@ -20,7 +20,7 @@ import type { Instance, StyleSource } from "@webstudio-is/sdk";
import { $styleSources } from "~/shared/sync/data-stores";
import { $selectedStyleSources } from "~/shared/nano-states";
import { $styles, $breakpoints } from "~/shared/sync/data-stores";
-import { findDuplicateTokens } from "@webstudio-is/project-build/runtime/styles";
+import { findDuplicateTokens } from "@webstudio-is/project-build/runtime";
import { $styleSourceUsages } from "~/builder/shared/style-source-actions";
import { InstanceList, showInstance } from "../shared/instance-list";
import {
diff --git a/apps/builder/app/builder/features/command-panel/groups/instances-group.tsx b/apps/builder/app/builder/features/command-panel/groups/instances-group.tsx
index 4c220e309f..a28d40c256 100644
--- a/apps/builder/app/builder/features/command-panel/groups/instances-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/instances-group.tsx
@@ -12,7 +12,7 @@ import type { Instance } from "@webstudio-is/sdk";
import { $instances, $pages } from "~/shared/sync/data-stores";
import { getInstanceLabel } from "~/builder/shared/instance-label";
import { $selectedPageId, selectInstance } from "~/shared/nano-states";
-import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime/lookup";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
import {
closeCommandPanel,
$commandSearch,
diff --git a/apps/builder/app/builder/features/command-panel/groups/tags-group.tsx b/apps/builder/app/builder/features/command-panel/groups/tags-group.tsx
index ee92b69e35..34eaf5d91e 100644
--- a/apps/builder/app/builder/features/command-panel/groups/tags-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/tags-group.tsx
@@ -19,7 +19,7 @@ import { $instances } from "~/shared/sync/data-stores";
import { $props } from "~/shared/sync/data-stores";
import { insertWebstudioFragmentAt } from "~/shared/instance-utils/insert";
import { InstanceIcon } from "~/builder/shared/instance-label";
-import { getValidElementChildTags } from "@webstudio-is/project-build/runtime/instances";
+import { getValidElementChildTags } from "@webstudio-is/project-build/runtime";
import { closeCommandPanel, $isCommandPanelOpen } from "../command-state";
import type { BaseOption } from "../shared/types";
import { allowsHtmlMutations } from "../shared/document-utils";
diff --git a/apps/builder/app/builder/features/command-panel/groups/wrap-group.test.tsx b/apps/builder/app/builder/features/command-panel/groups/wrap-group.test.tsx
index e04e8b0bd4..ade504c49d 100644
--- a/apps/builder/app/builder/features/command-panel/groups/wrap-group.test.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/wrap-group.test.tsx
@@ -10,7 +10,7 @@ import { $pages, $props } from "~/shared/sync/data-stores";
import { registerContainers } from "~/shared/sync/sync-stores";
import { $selectedPageId } from "~/shared/nano-states";
import { selectInstance } from "~/shared/nano-states";
-import { canWrapInstance } from "@webstudio-is/project-build/runtime/instances";
+import { canWrapInstance } from "@webstudio-is/project-build/runtime";
registerContainers();
diff --git a/apps/builder/app/builder/features/command-panel/groups/wrap-group.tsx b/apps/builder/app/builder/features/command-panel/groups/wrap-group.tsx
index 1d64644de5..3bf3af636b 100644
--- a/apps/builder/app/builder/features/command-panel/groups/wrap-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/wrap-group.tsx
@@ -25,7 +25,7 @@ import {
getInstanceLabel,
InstanceIcon,
} from "~/builder/shared/instance-label";
-import { canWrapInstance } from "@webstudio-is/project-build/runtime/instances";
+import { canWrapInstance } from "@webstudio-is/project-build/runtime";
import {
$commandContent,
$isCommandPanelOpen,
diff --git a/apps/builder/app/builder/features/command-panel/shared/instance-list.tsx b/apps/builder/app/builder/features/command-panel/shared/instance-list.tsx
index 4d6bf568d0..5f1df5bfb1 100644
--- a/apps/builder/app/builder/features/command-panel/shared/instance-list.tsx
+++ b/apps/builder/app/builder/features/command-panel/shared/instance-list.tsx
@@ -18,7 +18,7 @@ import { $instances, $pages } from "~/shared/sync/data-stores";
import { getInstanceLabel } from "~/builder/shared/instance-label";
import { buildInstancePath } from "~/shared/instance-utils/lookup";
import { $commandContent } from "~/builder/features/command-panel/command-state";
-import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime/lookup";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
import { $activeInspectorPanel } from "~/builder/shared/nano-states";
import { $selectedPageId, selectInstance } from "~/shared/nano-states";
import { useAutoSelectFirstItem } from "./auto-select";
diff --git a/apps/builder/app/builder/features/components/components.tsx b/apps/builder/app/builder/features/components/components.tsx
index c79478c5aa..fb5da134e0 100644
--- a/apps/builder/app/builder/features/components/components.tsx
+++ b/apps/builder/app/builder/features/components/components.tsx
@@ -8,7 +8,7 @@ import {
type BuilderComponentPanelItem,
listBuilderComponentPanelItems,
listComponentCatalogAvailableComponents,
-} from "@webstudio-is/project-build/runtime/component-catalog";
+} from "@webstudio-is/project-build/runtime";
import {
theme,
Flex,
diff --git a/apps/builder/app/builder/features/marketplace/templates.tsx b/apps/builder/app/builder/features/marketplace/templates.tsx
index 780d82bde5..d6a7c2d3f4 100644
--- a/apps/builder/app/builder/features/marketplace/templates.tsx
+++ b/apps/builder/app/builder/features/marketplace/templates.tsx
@@ -4,7 +4,7 @@ import {
detectFragmentTokenConflicts,
detectPageTokenConflicts,
extractWebstudioFragment,
-} from "@webstudio-is/project-build/runtime/fragment";
+} from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import { useMemo } from "react";
import {
diff --git a/apps/builder/app/builder/features/navigator/navigator-tree.tsx b/apps/builder/app/builder/features/navigator/navigator-tree.tsx
index 5afd92bb5f..fed26bb58a 100644
--- a/apps/builder/app/builder/features/navigator/navigator-tree.tsx
+++ b/apps/builder/app/builder/features/navigator/navigator-tree.tsx
@@ -34,7 +34,7 @@ import {
type Instance,
} from "@webstudio-is/sdk";
import { animationCanPlayOnCanvasProperty } from "@webstudio-is/sdk/runtime";
-import { showAttributeMeta } from "@webstudio-is/project-build/runtime/props";
+import { showAttributeMeta } from "@webstudio-is/project-build/runtime";
import {
EyeClosedIcon,
EyeOpenIcon,
@@ -71,11 +71,11 @@ import {
canDropInstanceSelector,
isDescendantOrSelf,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
import { emitCommand } from "~/builder/shared/commands";
import { useContentEditable } from "~/shared/dom-hooks";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
-import { isRichTextContent } from "@webstudio-is/project-build/runtime/content-model";
+import { isRichTextContent } from "@webstudio-is/project-build/runtime";
import {
getInstanceLabel,
InstanceIcon,
diff --git a/apps/builder/app/builder/features/pages/custom-metadata.tsx b/apps/builder/app/builder/features/pages/custom-metadata.tsx
index fe01529b7c..7d7885614c 100644
--- a/apps/builder/app/builder/features/pages/custom-metadata.tsx
+++ b/apps/builder/app/builder/features/pages/custom-metadata.tsx
@@ -12,7 +12,7 @@ import {
} from "@webstudio-is/design-system";
import { TrashIcon, PlusIcon } from "@webstudio-is/icons";
import { isLiteralExpression } from "@webstudio-is/sdk";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import {
BindingControl,
BindingPopover,
diff --git a/apps/builder/app/builder/features/pages/folder-settings.tsx b/apps/builder/app/builder/features/pages/folder-settings.tsx
index f15aafbcf9..d7b0da18a4 100644
--- a/apps/builder/app/builder/features/pages/folder-settings.tsx
+++ b/apps/builder/app/builder/features/pages/folder-settings.tsx
@@ -25,7 +25,7 @@ import {
validateFolderSettings,
type FolderSettingsFieldErrors,
type FolderSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { useState, type FocusEventHandler } from "react";
import { useIds } from "~/shared/form-utils";
import { $pages } from "~/shared/sync/data-stores";
diff --git a/apps/builder/app/builder/features/pages/image-info.tsx b/apps/builder/app/builder/features/pages/image-info.tsx
index e456c71a1e..716db637e2 100644
--- a/apps/builder/app/builder/features/pages/image-info.tsx
+++ b/apps/builder/app/builder/features/pages/image-info.tsx
@@ -12,7 +12,7 @@ import {
ImageIcon,
} from "@webstudio-is/icons";
import type { ImageAsset } from "@webstudio-is/sdk";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
import { getFormattedAspectRatio } from "~/builder/shared/asset-manager";
type ImageInfoProps = {
diff --git a/apps/builder/app/builder/features/pages/page-settings/page-settings.tsx b/apps/builder/app/builder/features/pages/page-settings/page-settings.tsx
index 8f836646cf..60e9e00d11 100644
--- a/apps/builder/app/builder/features/pages/page-settings/page-settings.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/page-settings.tsx
@@ -38,11 +38,11 @@ import {
validatePageSettings,
type PageSettingsErrors,
type PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
-import { findMatchingRedirect } from "@webstudio-is/project-build/runtime/redirect-source";
+} from "@webstudio-is/project-build/runtime";
+import { findMatchingRedirect } from "@webstudio-is/project-build/runtime";
import { CollapsibleSection } from "~/builder/shared/collapsible-section";
import { Form } from "../form";
-import { isContentModePagePath } from "@webstudio-is/project-build/runtime/content-mode-permissions";
+import { isContentModePagePath } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import { AuthSection } from "./section-auth";
import { CustomMetadataSection } from "./section-custom-metadata";
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-auth.tsx b/apps/builder/app/builder/features/pages/page-settings/section-auth.tsx
index fba0f5568c..aaf9f52be2 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-auth.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-auth.tsx
@@ -18,7 +18,7 @@ import { InfoCircleIcon } from "@webstudio-is/icons";
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import type { OnChange } from "./shared";
const emptyAuth: PageSettingsValues["auth"] = {
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-custom-metadata.tsx b/apps/builder/app/builder/features/pages/page-settings/section-custom-metadata.tsx
index 01c1e218e7..52efa8835a 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-custom-metadata.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-custom-metadata.tsx
@@ -3,7 +3,7 @@ import { CustomMetadata } from "../custom-metadata";
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import type { OnChange } from "./shared";
export const CustomMetadataSection = ({
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-general.tsx b/apps/builder/app/builder/features/pages/page-settings/section-general.tsx
index d6fc8a3e26..91c7e61d9b 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-general.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-general.tsx
@@ -26,13 +26,13 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import { $permissions } from "~/shared/nano-states";
import { $pageRootScope } from "../page-utils";
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { computePageSettingsText, type OnChange } from "./shared";
const autoSelectHandler: FocusEventHandler<HTMLInputElement> = (event) =>
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-marketplace.tsx b/apps/builder/app/builder/features/pages/page-settings/section-marketplace.tsx
index e3d669bd7b..697b8524c7 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-marketplace.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-marketplace.tsx
@@ -13,7 +13,7 @@ import { ImageControl } from "~/shared/project-settings";
import { $assets } from "~/shared/sync/data-stores";
import { Card } from "../../marketplace/card";
import { ImageInfo } from "../image-info";
-import type { PageSettingsValues } from "@webstudio-is/project-build/runtime/pages";
+import type { PageSettingsValues } from "@webstudio-is/project-build/runtime";
import { computePageSettingsText, type OnChange } from "./shared";
export const MarketplaceSection = ({
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-search.tsx b/apps/builder/app/builder/features/pages/page-settings/section-search.tsx
index 38444b13e8..a02b288530 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-search.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-search.tsx
@@ -15,11 +15,11 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { useStore } from "@nanostores/react";
import { $assets, $projectSettings } from "~/shared/sync/data-stores";
import { $pageRootScope } from "../page-utils";
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-social-image.tsx b/apps/builder/app/builder/features/pages/page-settings/section-social-image.tsx
index bb9cd67a9a..20bfbc90f8 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-social-image.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-social-image.tsx
@@ -14,7 +14,7 @@ import {
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { ImageControl } from "~/shared/project-settings";
import { $assets } from "~/shared/sync/data-stores";
import { isLiteralExpression } from "@webstudio-is/sdk";
diff --git a/apps/builder/app/builder/features/pages/page-settings/section-text-content.tsx b/apps/builder/app/builder/features/pages/page-settings/section-text-content.tsx
index bc7329196d..e7bae20e50 100644
--- a/apps/builder/app/builder/features/pages/page-settings/section-text-content.tsx
+++ b/apps/builder/app/builder/features/pages/page-settings/section-text-content.tsx
@@ -6,11 +6,11 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import type {
PageSettingsErrors,
PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { $pageRootScope } from "../page-utils";
import type { OnChange } from "./shared";
diff --git a/apps/builder/app/builder/features/pages/page-settings/shared.ts b/apps/builder/app/builder/features/pages/page-settings/shared.ts
index 9b47895bbb..a6ad59b643 100644
--- a/apps/builder/app/builder/features/pages/page-settings/shared.ts
+++ b/apps/builder/app/builder/features/pages/page-settings/shared.ts
@@ -1,11 +1,11 @@
import { useStore } from "@nanostores/react";
import { getPagePath } from "@webstudio-is/sdk";
-import type { PageSettingsValues } from "@webstudio-is/project-build/runtime/pages";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import type { PageSettingsValues } from "@webstudio-is/project-build/runtime";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import {
compilePathnamePattern,
tokenizePathnamePattern,
-} from "@webstudio-is/project-build/runtime/url-pattern";
+} from "@webstudio-is/project-build/runtime";
import { $publishedOrigin } from "~/shared/nano-states";
import { $pages } from "~/shared/sync/data-stores";
import { $currentSystem } from "~/shared/system";
diff --git a/apps/builder/app/builder/features/pages/page-utils.ts b/apps/builder/app/builder/features/pages/page-utils.ts
index 00648f8104..2d0e06ca09 100644
--- a/apps/builder/app/builder/features/pages/page-utils.ts
+++ b/apps/builder/app/builder/features/pages/page-utils.ts
@@ -15,7 +15,7 @@ import {
} from "@webstudio-is/sdk";
import { $variableValuesByInstanceSelector } from "~/shared/nano-states";
import { $dataSources, $pages, $project } from "~/shared/sync/data-stores";
-import { nameToPath } from "@webstudio-is/project-build/runtime/pages";
+import { nameToPath } from "@webstudio-is/project-build/runtime";
import { $selectedPage, getInstanceKey } from "~/shared/nano-states";
export const $pageRootScope = computed(
diff --git a/apps/builder/app/builder/features/pages/pages.tsx b/apps/builder/app/builder/features/pages/pages.tsx
index aa01ba117c..a52a0a557e 100644
--- a/apps/builder/app/builder/features/pages/pages.tsx
+++ b/apps/builder/app/builder/features/pages/pages.tsx
@@ -59,7 +59,7 @@ import {
canDropPageTarget,
getAllChildrenAndSelf,
getStoredPageDropTarget,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { duplicateFolder, isFolder } from "./page-utils";
import {
FolderSettings,
@@ -75,7 +75,7 @@ import {
getFolderById,
} from "@webstudio-is/sdk";
import { atom, computed } from "nanostores";
-import { isPathnamePattern } from "@webstudio-is/project-build/runtime/url-pattern";
+import { isPathnamePattern } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import { $selectedPage } from "~/shared/nano-states";
import { selectPage } from "~/shared/nano-states";
diff --git a/apps/builder/app/builder/features/pages/template-settings.test.ts b/apps/builder/app/builder/features/pages/template-settings.test.ts
index 703c74363f..29760f3e75 100644
--- a/apps/builder/app/builder/features/pages/template-settings.test.ts
+++ b/apps/builder/app/builder/features/pages/template-settings.test.ts
@@ -3,7 +3,7 @@ import { __testing__ } from "./template-settings";
import {
pageSettingsDefaultValues,
type PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
const { getEditorCreatePageValues } = __testing__;
diff --git a/apps/builder/app/builder/features/pages/template-settings.tsx b/apps/builder/app/builder/features/pages/template-settings.tsx
index f2d02b21d2..8306a2a17a 100644
--- a/apps/builder/app/builder/features/pages/template-settings.tsx
+++ b/apps/builder/app/builder/features/pages/template-settings.tsx
@@ -14,8 +14,8 @@ import {
} from "@webstudio-is/design-system";
import { $isContentMode, $isDesignMode } from "~/shared/nano-states";
import { $pages } from "~/shared/sync/data-stores";
-import { isContentModePagePath } from "@webstudio-is/project-build/runtime/content-mode-permissions";
-import type { BuilderRuntimeOperationInput } from "@webstudio-is/project-build/runtime/registry";
+import { isContentModePagePath } from "@webstudio-is/project-build/runtime";
+import type { BuilderRuntimeOperationInput } from "@webstudio-is/project-build/runtime";
import {
nameToPath,
pageSettingsDefaultValues,
@@ -23,7 +23,7 @@ import {
validatePageSettings,
type PageSettingsErrors,
type PageSettingsValues,
-} from "@webstudio-is/project-build/runtime/pages";
+} from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import {
$pageRootScope,
diff --git a/apps/builder/app/builder/features/publish/publish-url.test.ts b/apps/builder/app/builder/features/publish/publish-url.test.ts
index 9d98814ea5..cef8162bca 100644
--- a/apps/builder/app/builder/features/publish/publish-url.test.ts
+++ b/apps/builder/app/builder/features/publish/publish-url.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
import {
compilePathnamePattern,
tokenizePathnamePattern,
-} from "@webstudio-is/project-build/runtime/url-pattern";
+} from "@webstudio-is/project-build/runtime";
import { getPublishUrl } from "./publish-url";
describe("getPublishUrl", () => {
diff --git a/apps/builder/app/builder/features/publish/publish.tsx b/apps/builder/app/builder/features/publish/publish.tsx
index 34151e0e88..d21b84c4cb 100644
--- a/apps/builder/app/builder/features/publish/publish.tsx
+++ b/apps/builder/app/builder/features/publish/publish.tsx
@@ -93,7 +93,7 @@ import {
import {
formatBuildIntegrityError,
getBuildIntegrityIssues,
-} from "@webstudio-is/project-build/build-integrity";
+} from "@webstudio-is/project-build/runtime";
type ChangeProjectDomainProps = {
project: Project;
diff --git a/apps/builder/app/builder/features/publish/restricted-features.ts b/apps/builder/app/builder/features/publish/restricted-features.ts
index 2cc5140a79..9bdb9b027f 100644
--- a/apps/builder/app/builder/features/publish/restricted-features.ts
+++ b/apps/builder/app/builder/features/publish/restricted-features.ts
@@ -6,7 +6,7 @@ import {
type Instance,
type Pages,
} from "@webstudio-is/sdk";
-import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime/lookup";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
import type { ProjectSettings } from "@webstudio-is/project-build";
export type RestrictedFeature =
diff --git a/apps/builder/app/builder/features/settings-panel/controls/boolean.tsx b/apps/builder/app/builder/features/settings-panel/controls/boolean.tsx
index 38a58dbc3b..6433d5de6b 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/boolean.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/boolean.tsx
@@ -4,7 +4,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import {
type ControlProps,
$selectedInstanceScope,
diff --git a/apps/builder/app/builder/features/settings-panel/controls/code.tsx b/apps/builder/app/builder/features/settings-panel/controls/code.tsx
index fe98b2782c..46d688bf0d 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/code.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/code.tsx
@@ -22,8 +22,8 @@ import {
import {
validateHtmlEmbedCode,
type HtmlEmbedCodeError,
-} from "@webstudio-is/project-build/runtime/html";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+} from "@webstudio-is/project-build/runtime";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import {
type ControlProps,
diff --git a/apps/builder/app/builder/features/settings-panel/controls/file.tsx b/apps/builder/app/builder/features/settings-panel/controls/file.tsx
index 2047cdad0e..1301eb1be0 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/file.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/file.tsx
@@ -5,7 +5,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import {
type ControlProps,
diff --git a/apps/builder/app/builder/features/settings-panel/controls/resource-control.tsx b/apps/builder/app/builder/features/settings-panel/controls/resource-control.tsx
index afea6a11bd..a2effc003e 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/resource-control.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/resource-control.tsx
@@ -23,7 +23,7 @@ import {
BindingPopover,
type BindingVariant,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { $variableValuesByInstanceSelector } from "~/shared/nano-states";
import { $dataSources } from "~/shared/sync/data-stores";
import { $props, $resources } from "~/shared/sync/data-stores";
@@ -31,7 +31,7 @@ import {
computeExpression,
createResourceFieldsFromResource,
createResourceValueFromFormData,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import {
$selectedInstance,
diff --git a/apps/builder/app/builder/features/settings-panel/controls/select-asset.tsx b/apps/builder/app/builder/features/settings-panel/controls/select-asset.tsx
index 15279f08ca..1c75c2782d 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/select-asset.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/select-asset.tsx
@@ -7,7 +7,7 @@ import { acceptToMimeCategories } from "@webstudio-is/sdk";
import { $assets } from "~/shared/sync/data-stores";
import { AssetManager } from "~/builder/shared/asset-manager";
import { type ControlProps } from "../shared";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
import { AssetUpload } from "~/builder/shared/assets";
// tests whether we can use AssetManager for the given "accept" value
diff --git a/apps/builder/app/builder/features/settings-panel/controls/tag-control.tsx b/apps/builder/app/builder/features/settings-panel/controls/tag-control.tsx
index 9d6e535bfc..91c6abd87c 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/tag-control.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/tag-control.tsx
@@ -5,7 +5,7 @@ import { Box, Combobox, Select, theme } from "@webstudio-is/design-system";
import { elementsByTag } from "@webstudio-is/html-data";
import { $selectedInstance, $selectedInstancePath } from "~/shared/nano-states";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
-import { getValidTagsForInstance } from "@webstudio-is/project-build/runtime/instances";
+import { getValidTagsForInstance } from "@webstudio-is/project-build/runtime";
import { $registeredComponentMetas } from "~/shared/nano-states";
import { $instances } from "~/shared/sync/data-stores";
import { $props } from "~/shared/sync/data-stores";
diff --git a/apps/builder/app/builder/features/settings-panel/controls/text-content.tsx b/apps/builder/app/builder/features/settings-panel/controls/text-content.tsx
index e055a1d142..151af05bbf 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/text-content.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/text-content.tsx
@@ -17,7 +17,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import { CodeEditor } from "~/shared/code-editor";
diff --git a/apps/builder/app/builder/features/settings-panel/controls/text.tsx b/apps/builder/app/builder/features/settings-panel/controls/text.tsx
index f784467460..b02bce288c 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/text.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/text.tsx
@@ -5,7 +5,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import {
type ControlProps,
diff --git a/apps/builder/app/builder/features/settings-panel/controls/time-zone.tsx b/apps/builder/app/builder/features/settings-panel/controls/time-zone.tsx
index ede3ab399d..e5199807ca 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/time-zone.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/time-zone.tsx
@@ -6,7 +6,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import { $props } from "~/shared/sync/data-stores";
import {
diff --git a/apps/builder/app/builder/features/settings-panel/controls/url.tsx b/apps/builder/app/builder/features/settings-panel/controls/url.tsx
index b3ec6dc679..160c13134b 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/url.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/url.tsx
@@ -33,7 +33,7 @@ import {
BindingControl,
BindingPopover,
} from "~/builder/shared/binding-popover";
-import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime/props";
+import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
import {
type ControlProps,
diff --git a/apps/builder/app/builder/features/settings-panel/property-label.tsx b/apps/builder/app/builder/features/settings-panel/property-label.tsx
index 8245f58e8d..fb89f95769 100644
--- a/apps/builder/app/builder/features/settings-panel/property-label.tsx
+++ b/apps/builder/app/builder/features/settings-panel/property-label.tsx
@@ -21,7 +21,7 @@ import {
$isContentMode,
$selectedInstance,
} from "~/shared/nano-states";
-import { getPropIdsToDelete } from "@webstudio-is/project-build/runtime/props";
+import { getPropIdsToDelete } from "@webstudio-is/project-build/runtime";
import { $props } from "~/shared/sync/data-stores";
import {
$selectedInstanceInitialPropNames,
diff --git a/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.test.ts b/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.test.ts
index 5171dd8e4c..4e8b03565b 100644
--- a/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.test.ts
+++ b/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
import type { Prop, PropMeta } from "@webstudio-is/sdk";
import { textContentAttribute } from "@webstudio-is/react-sdk";
import { __testing__ } from "./use-props-logic";
-import type { ContentModeCapabilities } from "@webstudio-is/project-build/runtime/content-mode-permissions";
+import type { ContentModeCapabilities } from "@webstudio-is/project-build/runtime";
const { isPropVisibleInContentMode, getAndDelete } = __testing__;
diff --git a/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.ts b/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.ts
index f17a853937..f49301fa34 100644
--- a/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.ts
+++ b/apps/builder/app/builder/features/settings-panel/props-section/use-props-logic.ts
@@ -5,7 +5,7 @@ import { descendantComponent } from "@webstudio-is/sdk";
import {
getContentModeCapabilities,
type ContentModeCapabilities,
-} from "@webstudio-is/project-build/runtime/content-mode-permissions";
+} from "@webstudio-is/project-build/runtime";
import {
reactPropsToStandardAttributes,
showAttribute,
@@ -22,12 +22,12 @@ import { $styleSources } from "~/shared/sync/data-stores";
import {
isRichText,
isRichTextTree,
-} from "@webstudio-is/project-build/runtime/content-model";
+} from "@webstudio-is/project-build/runtime";
import {
createStartingPropValueFromMeta,
getDefaultPropMetaForType,
showAttributeMeta,
-} from "@webstudio-is/project-build/runtime/props";
+} from "@webstudio-is/project-build/runtime";
import { $selectedInstancePath } from "~/shared/nano-states";
import {
$selectedInstanceInitialPropNames,
diff --git a/apps/builder/app/builder/features/settings-panel/resource-panel.tsx b/apps/builder/app/builder/features/settings-panel/resource-panel.tsx
index 91c3a7c7dc..f444bf0a14 100644
--- a/apps/builder/app/builder/features/settings-panel/resource-panel.tsx
+++ b/apps/builder/app/builder/features/settings-panel/resource-panel.tsx
@@ -67,14 +67,14 @@ import {
$selectedPage,
getInstanceKey,
} from "~/shared/nano-states";
-import type { InstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import type { InstancePath } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import {
createResourceFieldsFromFormData,
validateResourceBodyExpression,
validateResourceUrlExpression,
type ResourceBodyInputType,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
import { parseCurl, type CurlRequest } from "./curl";
export const UrlField = ({
diff --git a/apps/builder/app/builder/features/settings-panel/shared.tsx b/apps/builder/app/builder/features/settings-panel/shared.tsx
index a9bf4c8fb5..d8a1033ac7 100644
--- a/apps/builder/app/builder/features/settings-panel/shared.tsx
+++ b/apps/builder/app/builder/features/settings-panel/shared.tsx
@@ -18,14 +18,14 @@ import {
showAttribute,
standardAttributesToReactProps,
} from "@webstudio-is/react-sdk";
-import { showAttributeMeta } from "@webstudio-is/project-build/runtime/props";
+import { showAttributeMeta } from "@webstudio-is/project-build/runtime";
import {
decodeDataSourceVariable,
encodeDataSourceVariable,
SYSTEM_VARIABLE_ID,
systemParameter,
} from "@webstudio-is/sdk";
-import { getContentModePropNamesByTag } from "@webstudio-is/project-build/runtime/content-mode-permissions";
+import { getContentModePropNamesByTag } from "@webstudio-is/project-build/runtime";
import type { PropMeta, Prop, Asset } from "@webstudio-is/sdk";
import { InfoCircleIcon } from "@webstudio-is/icons";
import {
diff --git a/apps/builder/app/builder/features/settings-panel/variable-popover.tsx b/apps/builder/app/builder/features/settings-panel/variable-popover.tsx
index 1ee04122bc..74ee890e78 100644
--- a/apps/builder/app/builder/features/settings-panel/variable-popover.tsx
+++ b/apps/builder/app/builder/features/settings-panel/variable-popover.tsx
@@ -76,7 +76,7 @@ import {
validateDataVariableJsonValue,
validateDataVariableNumberValue,
validateDataVariableStringArrayValue,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
import { validateDataVariableName } from "~/builder/shared/data-variable-utils";
import {
GraphqlResourceForm,
diff --git a/apps/builder/app/builder/features/settings-panel/variables-section.tsx b/apps/builder/app/builder/features/settings-panel/variables-section.tsx
index 32fc5adfff..7837574d6f 100644
--- a/apps/builder/app/builder/features/settings-panel/variables-section.tsx
+++ b/apps/builder/app/builder/features/settings-panel/variables-section.tsx
@@ -44,7 +44,7 @@ import {
import {
findAvailableVariables,
findUsedVariables,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
import {
DeleteDataVariableDialog,
deleteDataVariable,
diff --git a/apps/builder/app/builder/features/style-panel/controls/image/image-control.tsx b/apps/builder/app/builder/features/style-panel/controls/image/image-control.tsx
index 41404eff97..9d2df55a97 100644
--- a/apps/builder/app/builder/features/style-panel/controls/image/image-control.tsx
+++ b/apps/builder/app/builder/features/style-panel/controls/image/image-control.tsx
@@ -14,7 +14,7 @@ import {
getRepeatedStyleItem,
setRepeatedStyleItem,
} from "../../shared/repeated-style";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
import { AssetUpload } from "~/builder/shared/assets";
const isValidURL = (value: string) => {
diff --git a/apps/builder/app/builder/features/style-panel/sections/backgrounds/background-thumbnail.tsx b/apps/builder/app/builder/features/style-panel/sections/backgrounds/background-thumbnail.tsx
index f3ffcfa673..a86041df97 100644
--- a/apps/builder/app/builder/features/style-panel/sections/backgrounds/background-thumbnail.tsx
+++ b/apps/builder/app/builder/features/style-panel/sections/backgrounds/background-thumbnail.tsx
@@ -15,7 +15,7 @@ import {
getComputedRepeatedItem,
getRepeatedStyleItem,
} from "../../shared/repeated-style";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
import { parseAnyGradient, isSolidLinearGradient } from "./gradient-utils";
export const repeatedProperties = [
diff --git a/apps/builder/app/builder/features/style-panel/sections/layout/shared/grid-utils.ts b/apps/builder/app/builder/features/style-panel/sections/layout/shared/grid-utils.ts
index 05fc1596a6..1d436cc603 100644
--- a/apps/builder/app/builder/features/style-panel/sections/layout/shared/grid-utils.ts
+++ b/apps/builder/app/builder/features/style-panel/sections/layout/shared/grid-utils.ts
@@ -1,4 +1,4 @@
export {
isAutoGridPlacement,
resetGridChildPlacement,
-} from "@webstudio-is/project-build/runtime/style-utils";
+} from "@webstudio-is/project-build/runtime";
diff --git a/apps/builder/app/builder/features/style-panel/shared/model.tsx b/apps/builder/app/builder/features/style-panel/shared/model.tsx
index 4049494b91..8b691866cf 100644
--- a/apps/builder/app/builder/features/style-panel/shared/model.tsx
+++ b/apps/builder/app/builder/features/style-panel/shared/model.tsx
@@ -38,8 +38,8 @@ import {
type StyleObjectModel,
} from "~/shared/style-object-model";
import { $selectedInstancePathWithRoot } from "~/shared/nano-states";
-import type { InstancePath } from "@webstudio-is/project-build/runtime/lookup";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstancePath } from "@webstudio-is/project-build/runtime";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
const propertyNameCollator = new Intl.Collator();
diff --git a/apps/builder/app/builder/features/style-panel/shared/use-style-data.ts b/apps/builder/app/builder/features/style-panel/shared/use-style-data.ts
index 8f31c8e7cc..e3c514e9b9 100644
--- a/apps/builder/app/builder/features/style-panel/shared/use-style-data.ts
+++ b/apps/builder/app/builder/features/style-panel/shared/use-style-data.ts
@@ -7,7 +7,7 @@ import {
} from "~/shared/nano-states";
import { $ephemeralStyles } from "~/canvas/stores";
import { $selectedInstance } from "~/shared/nano-states";
-import { isStyleSourceLocked } from "@webstudio-is/project-build/runtime/styles";
+import { isStyleSourceLocked } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
type StyleUpdate =
diff --git a/apps/builder/app/builder/features/style-panel/style-panel.tsx b/apps/builder/app/builder/features/style-panel/style-panel.tsx
index 033d60902b..61a1589c65 100644
--- a/apps/builder/app/builder/features/style-panel/style-panel.tsx
+++ b/apps/builder/app/builder/features/style-panel/style-panel.tsx
@@ -27,7 +27,7 @@ import {
$selectedInstanceRenderState,
$selectedStyleSource,
} from "~/shared/nano-states";
-import { isStyleSourceLocked } from "@webstudio-is/project-build/runtime/styles";
+import { isStyleSourceLocked } from "@webstudio-is/project-build/runtime";
import { ReadonlyProvider } from "./shared/readonly";
import { $selectedInstance } from "~/shared/nano-states";
import { CollapsibleProvider } from "~/builder/shared/collapsible-section";
diff --git a/apps/builder/app/builder/features/style-panel/style-source-section.tsx b/apps/builder/app/builder/features/style-panel/style-source-section.tsx
index 2bcfa7aefd..370abb109c 100644
--- a/apps/builder/app/builder/features/style-panel/style-source-section.tsx
+++ b/apps/builder/app/builder/features/style-panel/style-source-section.tsx
@@ -8,7 +8,7 @@ import {
type StyleSourceToken,
type StyleDecl,
} from "@webstudio-is/sdk";
-import { type RenameStyleSourceError } from "@webstudio-is/project-build/runtime/styles";
+import { type RenameStyleSourceError } from "@webstudio-is/project-build/runtime";
import { type ItemSource, StyleSourceInput } from "./style-source";
import {
renameStyleSource,
diff --git a/apps/builder/app/builder/features/workspace/canvas-tools/block-editor-context-menu.tsx b/apps/builder/app/builder/features/workspace/canvas-tools/block-editor-context-menu.tsx
index e91294a95a..98de45896d 100644
--- a/apps/builder/app/builder/features/workspace/canvas-tools/block-editor-context-menu.tsx
+++ b/apps/builder/app/builder/features/workspace/canvas-tools/block-editor-context-menu.tsx
@@ -14,8 +14,8 @@ import { TemplatesMenu } from "./outline/block-instance-outline";
import { insertTemplateAt } from "./outline/block-utils";
import { useCallback, useEffect, useState } from "react";
import { useEffectEvent } from "~/shared/hook-utils/effect-event";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
-import { findBlockTemplates } from "@webstudio-is/project-build/runtime/block";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
+import { findBlockTemplates } from "@webstudio-is/project-build/runtime";
import type { Instance } from "@webstudio-is/sdk";
import { shallowEqual } from "shallow-equal";
diff --git a/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-instance-outline.tsx b/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-instance-outline.tsx
index b508c55fe1..12197f8916 100644
--- a/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-instance-outline.tsx
+++ b/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-instance-outline.tsx
@@ -31,12 +31,12 @@ import {
} from "~/shared/nano-states";
import { $instances } from "~/shared/sync/data-stores";
import { $clampingRect, $scale } from "~/builder/shared/nano-states";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import {
canDeleteInstanceInContentMode,
findBlockSelector,
findBlockTemplates,
-} from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
import { skipInertHandlersAttribute } from "~/builder/shared/inert-handlers";
import { useEffectEvent } from "~/shared/hook-utils/effect-event";
import { insertTemplateAt } from "./block-utils";
diff --git a/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-utils.ts b/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-utils.ts
index 94fc6ccb06..4983305201 100644
--- a/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-utils.ts
+++ b/apps/builder/app/builder/features/workspace/canvas-tools/outline/block-utils.ts
@@ -1,5 +1,5 @@
import type { WebstudioFragment } from "@webstudio-is/sdk";
-import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime/lookup";
+import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime";
import {
executeRuntimeMutationAsync,
getWebstudioData,
@@ -8,7 +8,7 @@ import { insertWebstudioFragmentAt } from "~/shared/instance-utils/insert";
import {
detectFragmentTokenConflicts,
extractWebstudioFragment,
-} from "@webstudio-is/project-build/runtime/fragment";
+} from "@webstudio-is/project-build/runtime";
import {
$selectedInstanceSelector,
selectInstance,
@@ -24,11 +24,11 @@ import { $project } from "~/shared/sync/data-stores";
import type {
DroppableTarget,
InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
import {
findBlockSelector,
getBlockTemplateInsertionIndex,
-} from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
const getTemplateTokenConflicts = ({
fragment,
diff --git a/apps/builder/app/builder/features/workspace/canvas-tools/outline/hovered-instance-outline.tsx b/apps/builder/app/builder/features/workspace/canvas-tools/outline/hovered-instance-outline.tsx
index cf649cbd03..51477f19cb 100644
--- a/apps/builder/app/builder/features/workspace/canvas-tools/outline/hovered-instance-outline.tsx
+++ b/apps/builder/app/builder/features/workspace/canvas-tools/outline/hovered-instance-outline.tsx
@@ -10,7 +10,7 @@ import {
import { $instances } from "~/shared/sync/data-stores";
import { $clampingRect, $scale } from "~/builder/shared/nano-states";
import { findClosestSlot } from "~/shared/instance-utils/slot";
-import { isDescendantOrSelf } from "@webstudio-is/project-build/runtime/tree";
+import { isDescendantOrSelf } from "@webstudio-is/project-build/runtime";
import { Outline } from "./outline";
import { Label } from "./label";
import { applyScale } from "../apply-scale";
diff --git a/apps/builder/app/builder/features/workspace/canvas-tools/outline/selected-instance-outline.tsx b/apps/builder/app/builder/features/workspace/canvas-tools/outline/selected-instance-outline.tsx
index d2101c7f4c..9fb7d7c68e 100644
--- a/apps/builder/app/builder/features/workspace/canvas-tools/outline/selected-instance-outline.tsx
+++ b/apps/builder/app/builder/features/workspace/canvas-tools/outline/selected-instance-outline.tsx
@@ -4,7 +4,7 @@ import {
$selectedInstanceOutlines,
$textEditingInstanceSelector,
} from "~/shared/nano-states";
-import { isDescendantOrSelf } from "@webstudio-is/project-build/runtime/tree";
+import { isDescendantOrSelf } from "@webstudio-is/project-build/runtime";
import { Outline } from "./outline";
import { applyScale } from "../apply-scale";
import { $clampingRect, $scale } from "~/builder/shared/nano-states";
diff --git a/apps/builder/app/builder/shared/asset-manager/asset-info.tsx b/apps/builder/app/builder/shared/asset-manager/asset-info.tsx
index e6e72a0079..2645b5e461 100644
--- a/apps/builder/app/builder/shared/asset-manager/asset-info.tsx
+++ b/apps/builder/app/builder/shared/asset-manager/asset-info.tsx
@@ -55,7 +55,7 @@ import { $openProjectSettings } from "~/shared/nano-states/project-settings";
import { $styles } from "~/shared/sync/data-stores";
import { selectInstance } from "~/shared/nano-states";
import { selectPage } from "~/shared/nano-states";
-import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime/lookup";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
import { $selectedPageId } from "~/shared/nano-states";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import { deleteAssets, replaceAsset } from "~/builder/shared/assets";
@@ -73,14 +73,14 @@ import {
import {
formatAssetName,
parseAssetName,
-} from "@webstudio-is/project-build/runtime/assets";
+} from "@webstudio-is/project-build/runtime";
import { getAssetUrl } from "~/builder/shared/assets/asset-utils";
import { getFormattedAspectRatio } from "./utils";
import { CopyToClipboard } from "~/shared/copy-to-clipboard";
import {
calculateUsagesByAssetId,
type AssetUsage,
-} from "@webstudio-is/project-build/runtime/assets";
+} from "@webstudio-is/project-build/runtime";
const $usagesByAssetId = computed(
[$pages, $projectSettings, $props, $styles, $assets],
diff --git a/apps/builder/app/builder/shared/asset-manager/asset-thumbnail.tsx b/apps/builder/app/builder/shared/asset-manager/asset-thumbnail.tsx
index a9c702e339..7d0c00096c 100644
--- a/apps/builder/app/builder/shared/asset-manager/asset-thumbnail.tsx
+++ b/apps/builder/app/builder/shared/asset-manager/asset-thumbnail.tsx
@@ -11,7 +11,7 @@ import { theme } from "@webstudio-is/design-system";
import {
formatAssetName,
parseAssetName,
-} from "@webstudio-is/project-build/runtime/assets";
+} from "@webstudio-is/project-build/runtime";
import type { IconComponent } from "@webstudio-is/icons";
import type { AllowedFileExtension } from "@webstudio-is/sdk";
import {
diff --git a/apps/builder/app/builder/shared/asset-manager/delete-unused-assets.tsx b/apps/builder/app/builder/shared/asset-manager/delete-unused-assets.tsx
index 76cdc96977..ff60386c68 100644
--- a/apps/builder/app/builder/shared/asset-manager/delete-unused-assets.tsx
+++ b/apps/builder/app/builder/shared/asset-manager/delete-unused-assets.tsx
@@ -23,8 +23,8 @@ import {
$styles,
} from "~/shared/sync/data-stores";
import { deleteAssets } from "~/builder/shared/assets";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
-import { calculateUsagesByAssetId } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
+import { calculateUsagesByAssetId } from "@webstudio-is/project-build/runtime";
const $isDeleteUnusedAssetsDialogOpen = atom(false);
diff --git a/apps/builder/app/builder/shared/assets/upload-assets.tsx b/apps/builder/app/builder/shared/assets/upload-assets.tsx
index d75712e181..6995e4792a 100644
--- a/apps/builder/app/builder/shared/assets/upload-assets.tsx
+++ b/apps/builder/app/builder/shared/assets/upload-assets.tsx
@@ -18,7 +18,7 @@ import { $project } from "~/shared/sync/data-stores";
import { onNextTransactionComplete } from "~/shared/sync/project-queue";
import { invalidateAssets } from "~/shared/resources";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
-import { formatAssetName } from "@webstudio-is/project-build/runtime/assets";
+import { formatAssetName } from "@webstudio-is/project-build/runtime";
import {
getFileName,
getMimeType,
diff --git a/apps/builder/app/builder/shared/binding-popover.tsx b/apps/builder/app/builder/shared/binding-popover.tsx
index b43b431197..339cde2ca9 100644
--- a/apps/builder/app/builder/shared/binding-popover.tsx
+++ b/apps/builder/app/builder/shared/binding-popover.tsx
@@ -36,12 +36,12 @@ import {
decodeDataSourceVariable,
getExpressionIdentifiers,
} from "@webstudio-is/sdk";
-import { getExpressionErrorMessages } from "@webstudio-is/project-build/runtime/expression-validation";
+import { getExpressionErrorMessages } from "@webstudio-is/project-build/runtime";
import { $dataSourceVariables, $isDesignMode } from "~/shared/nano-states";
import {
computeExpressionWithinScope,
encodeDataVariableName,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
import {
ExpressionEditor,
formatValuePreview,
diff --git a/apps/builder/app/builder/shared/calc-canvas-width.ts b/apps/builder/app/builder/shared/calc-canvas-width.ts
index bd49cf132d..cc66d9116b 100644
--- a/apps/builder/app/builder/shared/calc-canvas-width.ts
+++ b/apps/builder/app/builder/shared/calc-canvas-width.ts
@@ -4,7 +4,7 @@ import type { Breakpoint } from "@webstudio-is/sdk";
import {
groupBreakpoints,
isBaseBreakpoint,
-} from "@webstudio-is/project-build/runtime/breakpoints";
+} from "@webstudio-is/project-build/runtime";
import { minCanvasWidth } from "~/shared/breakpoints-utils";
import { $workspaceRect, $canvasWidth } from "~/builder/shared/nano-states";
import { $isPreviewMode, $selectedBreakpoint } from "~/shared/nano-states";
diff --git a/apps/builder/app/builder/shared/commands.ts b/apps/builder/app/builder/shared/commands.ts
index 374297b915..84321bba21 100644
--- a/apps/builder/app/builder/shared/commands.ts
+++ b/apps/builder/app/builder/shared/commands.ts
@@ -3,7 +3,7 @@ import {
deleteSelectedInstance,
reparentInstance,
} from "~/shared/instance-utils/mutation";
-import { sortInstancePathsForChildMutation } from "@webstudio-is/project-build/runtime/tree";
+import { sortInstancePathsForChildMutation } from "@webstudio-is/project-build/runtime";
import { toggleInstanceShow } from "~/shared/instance-utils/mutation";
import { insertWebstudioFragmentAt } from "~/shared/instance-utils/insert";
import { toast } from "@webstudio-is/design-system";
@@ -43,7 +43,7 @@ import {
selectBreakpointByOrder,
} from "~/shared/breakpoints";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
-import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime/block";
+import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime";
import { serverSyncStore } from "~/shared/sync/sync-stores";
import { $publisher } from "~/shared/pubsub";
import {
@@ -64,7 +64,7 @@ import {
import {
getInstancePath,
type InstancePath,
-} from "@webstudio-is/project-build/runtime/lookup";
+} from "@webstudio-is/project-build/runtime";
import { openCommandPanel } from "../features/command-panel";
import { showWrapComponentsList } from "../features/command-panel/groups/wrap-group";
import { showConvertComponentsList } from "../features/command-panel/groups/convert-group";
@@ -72,7 +72,7 @@ import { showDuplicateTokensView } from "../features/command-panel/groups/duplic
import { builderApi } from "~/shared/builder-api";
import { readClipboardText } from "~/shared/clipboard";
import { getSetting, setSetting } from "./client-settings";
-import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime/html";
+import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime";
import { generateFragmentFromTailwind } from "~/shared/tailwind/tailwind";
import { denormalizeSrcProps } from "~/shared/copy-paste/asset-upload";
import { isSyncIdle } from "~/shared/sync/project-queue";
@@ -94,9 +94,9 @@ import {
getPageActionTarget,
} from "~/shared/page-action-target";
import { getDirectSharedSlotChildBoundary } from "~/shared/instance-utils/slot";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
-import { areInstanceSelectorsEqual } from "@webstudio-is/project-build/runtime/tree";
-import { findChildReferenceIndex } from "@webstudio-is/project-build/runtime/instances";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
+import { areInstanceSelectorsEqual } from "@webstudio-is/project-build/runtime";
+import { findChildReferenceIndex } from "@webstudio-is/project-build/runtime";
const makeBreakpointCommand = <CommandName extends string>(
name: CommandName,
diff --git a/apps/builder/app/builder/shared/css-variable-utils.tsx b/apps/builder/app/builder/shared/css-variable-utils.tsx
index 996cbe5733..bffbf2dd85 100644
--- a/apps/builder/app/builder/shared/css-variable-utils.tsx
+++ b/apps/builder/app/builder/shared/css-variable-utils.tsx
@@ -27,8 +27,8 @@ import {
getReferencedCssVariables,
getUnusedCssVariableNames,
validateCssVariableNameWithStyles,
-} from "@webstudio-is/project-build/runtime/styles";
-import { type CssVariableNameError } from "@webstudio-is/project-build/runtime/styles";
+} from "@webstudio-is/project-build/runtime";
+import { type CssVariableNameError } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
const $isDeleteUnusedCssVariablesDialogOpen = atom(false);
diff --git a/apps/builder/app/builder/shared/data-variable-utils.tsx b/apps/builder/app/builder/shared/data-variable-utils.tsx
index 48915876f3..3ad850415d 100644
--- a/apps/builder/app/builder/shared/data-variable-utils.tsx
+++ b/apps/builder/app/builder/shared/data-variable-utils.tsx
@@ -25,8 +25,8 @@ import {
import {
findUnusedDataVariableIds,
validateDataVariableNameWithSources,
-} from "@webstudio-is/project-build/runtime/data";
-import { type DataVariableNameError } from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
+import { type DataVariableNameError } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
const $isDeleteUnusedDataVariablesDialogOpen = atom(false);
diff --git a/apps/builder/app/builder/shared/expression-editor.tsx b/apps/builder/app/builder/shared/expression-editor.tsx
index 741d9e83c3..fd6f8671b9 100644
--- a/apps/builder/app/builder/shared/expression-editor.tsx
+++ b/apps/builder/app/builder/shared/expression-editor.tsx
@@ -47,7 +47,7 @@ import {
encodeDataVariableName,
restoreExpressionVariables,
unsetExpressionVariables,
-} from "@webstudio-is/project-build/runtime/data";
+} from "@webstudio-is/project-build/runtime";
export type { EditorApi };
diff --git a/apps/builder/app/builder/shared/instance-context-menu.test.ts b/apps/builder/app/builder/shared/instance-context-menu.test.ts
index d91e9aadc3..b71f181115 100644
--- a/apps/builder/app/builder/shared/instance-context-menu.test.ts
+++ b/apps/builder/app/builder/shared/instance-context-menu.test.ts
@@ -9,7 +9,7 @@ import {
type Page,
type Pages,
} from "@webstudio-is/sdk";
-import type { InstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import type { InstancePath } from "@webstudio-is/project-build/runtime";
import { $selectedPageId } from "~/shared/nano-states";
import { $pages } from "~/shared/sync/data-stores";
import { __testing__ } from "./instance-context-menu";
diff --git a/apps/builder/app/builder/shared/instance-context-menu.tsx b/apps/builder/app/builder/shared/instance-context-menu.tsx
index 210c58a18d..d3b4242084 100644
--- a/apps/builder/app/builder/shared/instance-context-menu.tsx
+++ b/apps/builder/app/builder/shared/instance-context-menu.tsx
@@ -26,8 +26,8 @@ import {
import {
getInstancePath,
type InstancePath,
-} from "@webstudio-is/project-build/runtime/lookup";
-import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
+import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime";
import { $instances } from "~/shared/sync/data-stores";
import {
isComponentDetachable,
diff --git a/apps/builder/app/builder/shared/style-source-actions.tsx b/apps/builder/app/builder/shared/style-source-actions.tsx
index d4e07d65ad..8ef08604ed 100644
--- a/apps/builder/app/builder/shared/style-source-actions.tsx
+++ b/apps/builder/app/builder/shared/style-source-actions.tsx
@@ -15,7 +15,7 @@ import {
toast,
} from "@webstudio-is/design-system";
import type { StyleSource } from "@webstudio-is/sdk";
-import type { RenameStyleSourceError } from "@webstudio-is/project-build/runtime/styles";
+import type { RenameStyleSourceError } from "@webstudio-is/project-build/runtime";
import {
$selectedStyleSources,
$selectedStyleState,
@@ -28,7 +28,7 @@ import {
findUnusedTokens,
getStyleSourceUsages,
validateStyleSourceName,
-} from "@webstudio-is/project-build/runtime/styles";
+} from "@webstudio-is/project-build/runtime";
import { $selectedInstance } from "~/shared/nano-states";
import { executeRuntimeMutation } from "~/shared/instance-utils/data";
diff --git a/apps/builder/app/canvas/elements.tsx b/apps/builder/app/canvas/elements.tsx
index 4fe91762ff..437955a8a0 100644
--- a/apps/builder/app/canvas/elements.tsx
+++ b/apps/builder/app/canvas/elements.tsx
@@ -7,7 +7,7 @@ import {
} from "react";
import type { Instance, Instances } from "@webstudio-is/sdk";
import type { Components } from "@webstudio-is/react-sdk";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
export type WebstudioComponentProps = {
instance: Instance;
diff --git a/apps/builder/app/canvas/features/text-editor/text-editor.tsx b/apps/builder/app/canvas/features/text-editor/text-editor.tsx
index 3a15731330..3876a7216b 100644
--- a/apps/builder/app/canvas/features/text-editor/text-editor.tsx
+++ b/apps/builder/app/canvas/features/text-editor/text-editor.tsx
@@ -1,4 +1,4 @@
-import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime/lookup";
+import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime";
import { color } from "@webstudio-is/css-engine";
import {
useState,
@@ -61,8 +61,8 @@ import {
import {
isDescendantOrSelf,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+} from "@webstudio-is/project-build/runtime";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
import { ToolbarConnectorPlugin } from "./toolbar-connector";
import { type Refs, $convertToLexical, $convertToUpdates } from "./interop";
import { useEffectEvent } from "~/shared/hook-utils/effect-event";
@@ -80,7 +80,7 @@ import { $instances } from "~/shared/sync/data-stores";
import {
findBlockChildSelector,
findBlockTemplates,
-} from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
import {
getElementByInstanceSelector,
getVisibleElementsByInstanceSelector,
@@ -98,7 +98,7 @@ import {
insertListItemAt,
insertTemplateAt,
} from "~/builder/features/workspace/canvas-tools/outline/block-utils";
-import { richTextPlaceholders } from "@webstudio-is/project-build/runtime/content-model";
+import { richTextPlaceholders } from "@webstudio-is/project-build/runtime";
const BindInstanceToNodePlugin = ({
refs,
diff --git a/apps/builder/app/canvas/features/webstudio-component/webstudio-component.tsx b/apps/builder/app/canvas/features/webstudio-component/webstudio-component.tsx
index c419a5cbef..c1e1f46a28 100644
--- a/apps/builder/app/canvas/features/webstudio-component/webstudio-component.tsx
+++ b/apps/builder/app/canvas/features/webstudio-component/webstudio-component.tsx
@@ -60,8 +60,8 @@ import { $instances } from "~/shared/sync/data-stores";
import {
type InstanceSelector,
areInstanceSelectorsEqual,
-} from "@webstudio-is/project-build/runtime/tree";
-import { findBlockSelector } from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
+import { findBlockSelector } from "@webstudio-is/project-build/runtime";
import { inflateInstance } from "~/canvas/inflator";
import { getIsVisuallyHidden } from "~/shared/visually-hidden";
import { TextEditor } from "../text-editor";
@@ -79,7 +79,7 @@ import {
editablePlaceholderAttribute,
editingPlaceholderVariable,
} from "~/canvas/shared/styles";
-import { richTextPlaceholders } from "@webstudio-is/project-build/runtime/content-model";
+import { richTextPlaceholders } from "@webstudio-is/project-build/runtime";
const computeComponentKey = (props: Record<string, unknown>) => {
const assetId = props.$webstudio$canvasOnly$assetId;
diff --git a/apps/builder/app/canvas/grid-guide-utils.ts b/apps/builder/app/canvas/grid-guide-utils.ts
index 93e454bac8..98e56b8cd8 100644
--- a/apps/builder/app/canvas/grid-guide-utils.ts
+++ b/apps/builder/app/canvas/grid-guide-utils.ts
@@ -7,7 +7,7 @@ import { $instances } from "~/shared/sync/data-stores";
import { $gridCellData, type GridCellData } from "~/shared/nano-states";
import { subscribeScrollState } from "~/canvas/shared/scroll-state";
import { subscribeWindowResize } from "~/shared/dom-hooks";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import { $selectedInstanceSelector } from "~/shared/nano-states";
import { getElementByInstanceSelector } from "~/shared/dom-utils";
import { parseGridTemplateTrackList } from "@webstudio-is/css-data";
diff --git a/apps/builder/app/canvas/instance-hovering.ts b/apps/builder/app/canvas/instance-hovering.ts
index 218b30156c..bfd63c7050 100644
--- a/apps/builder/app/canvas/instance-hovering.ts
+++ b/apps/builder/app/canvas/instance-hovering.ts
@@ -15,8 +15,8 @@ import { subscribeScrollState } from "./shared/scroll-state";
import {
isDescendantOrSelf,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
-import { findBlockChildSelector } from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
+import { findBlockChildSelector } from "@webstudio-is/project-build/runtime";
import { $selectedInstanceSelector } from "~/shared/nano-states";
type TimeoutId = undefined | ReturnType<typeof setTimeout>;
diff --git a/apps/builder/app/canvas/instance-selection-events.ts b/apps/builder/app/canvas/instance-selection-events.ts
index 77534de933..484075d72f 100644
--- a/apps/builder/app/canvas/instance-selection-events.ts
+++ b/apps/builder/app/canvas/instance-selection-events.ts
@@ -18,11 +18,11 @@ import { $instances } from "~/shared/sync/data-stores";
import { $ephemeralStyles } from "~/canvas/stores";
import { emitCommand } from "./shared/commands";
import { shallowEqual } from "shallow-equal";
-import { findClosestRichText } from "@webstudio-is/project-build/runtime/content-model";
+import { findClosestRichText } from "@webstudio-is/project-build/runtime";
import {
areInstanceSelectorsEqual,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
import { isTextEditableInContentMode } from "./shared/content-mode";
type SelectionAnchor = {
diff --git a/apps/builder/app/canvas/interceptor.ts b/apps/builder/app/canvas/interceptor.ts
index c57aff1bc2..23e28ec8b3 100644
--- a/apps/builder/app/canvas/interceptor.ts
+++ b/apps/builder/app/canvas/interceptor.ts
@@ -3,7 +3,7 @@ import {
compilePathnamePattern,
matchPathnamePattern,
tokenizePathnamePattern,
-} from "@webstudio-is/project-build/runtime/url-pattern";
+} from "@webstudio-is/project-build/runtime";
import { $selectedPage } from "~/shared/nano-states";
import { selectPage } from "~/shared/nano-states";
import { $isPreviewMode, $selectedPageHash } from "~/shared/nano-states";
diff --git a/apps/builder/app/canvas/selected-instance-effects.ts b/apps/builder/app/canvas/selected-instance-effects.ts
index 224af5c1a4..aa6cf0dc97 100644
--- a/apps/builder/app/canvas/selected-instance-effects.ts
+++ b/apps/builder/app/canvas/selected-instance-effects.ts
@@ -34,7 +34,7 @@ import { inflateInstance } from "~/canvas/inflator";
import {
areInstanceSelectorsEqual,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
const toRect = (rect: DOMRect) => ({
top: rect.top,
diff --git a/apps/builder/app/canvas/shared/commands.ts b/apps/builder/app/canvas/shared/commands.ts
index 09b0da06c1..e6ae124e7e 100644
--- a/apps/builder/app/canvas/shared/commands.ts
+++ b/apps/builder/app/canvas/shared/commands.ts
@@ -2,7 +2,7 @@ import { FORMAT_TEXT_COMMAND } from "lexical";
import { TOGGLE_LINK_COMMAND } from "@lexical/link";
import { createCommandsEmitter } from "~/shared/commands-emitter";
import { getElementByInstanceSelector } from "~/shared/dom-utils";
-import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime/lookup";
+import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime";
import {
$allSelectedInstanceSelectors,
$isContentMode,
@@ -24,9 +24,9 @@ import {
import {
isDescendantOrSelf,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
import { deleteSelectedInstance } from "~/shared/instance-utils/mutation";
-import { findClosestRichText } from "@webstudio-is/project-build/runtime/content-model";
+import { findClosestRichText } from "@webstudio-is/project-build/runtime";
import { getDeletablePageActionTarget } from "~/shared/page-action-target";
import { isTextEditableInContentMode } from "./content-mode";
diff --git a/apps/builder/app/canvas/shared/content-mode.ts b/apps/builder/app/canvas/shared/content-mode.ts
index 792e3b77c1..ced62d01a0 100644
--- a/apps/builder/app/canvas/shared/content-mode.ts
+++ b/apps/builder/app/canvas/shared/content-mode.ts
@@ -1,5 +1,5 @@
-import { getContentModeEditableInstanceIds } from "@webstudio-is/project-build/runtime/content-mode-permissions";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import { getContentModeEditableInstanceIds } from "@webstudio-is/project-build/runtime";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import type { Instances } from "@webstudio-is/sdk";
export const isTextEditableInContentMode = ({
diff --git a/apps/builder/app/canvas/shared/styles.ts b/apps/builder/app/canvas/shared/styles.ts
index fd521ee5cb..291ce8dbad 100644
--- a/apps/builder/app/canvas/shared/styles.ts
+++ b/apps/builder/app/canvas/shared/styles.ts
@@ -49,8 +49,8 @@ import {
$selectedInstanceSelector,
$selectedPage,
} from "~/shared/nano-states";
-import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime/lookup";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import { findAllEditableInstanceSelector } from "@webstudio-is/project-build/runtime";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import { getAllElementsByInstanceSelector } from "~/shared/dom-utils";
import { createComputedStyleDeclStore } from "~/builder/features/style-panel/shared/model";
diff --git a/apps/builder/app/canvas/shared/use-drag-drop.ts b/apps/builder/app/canvas/shared/use-drag-drop.ts
index 5c78ec836c..9ffbe2bcc0 100644
--- a/apps/builder/app/canvas/shared/use-drag-drop.ts
+++ b/apps/builder/app/canvas/shared/use-drag-drop.ts
@@ -27,8 +27,8 @@ import {
type InstanceSelector,
areInstanceSelectorsEqual,
findClosestDroppableInstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
-import { findClosestRichText } from "@webstudio-is/project-build/runtime/content-model";
+} from "@webstudio-is/project-build/runtime";
+import { findClosestRichText } from "@webstudio-is/project-build/runtime";
declare module "~/shared/pubsub" {
export interface PubsubMap {
diff --git a/apps/builder/app/routes/rest.assets_.$name.tsx b/apps/builder/app/routes/rest.assets_.$name.tsx
index 382501e8a7..5893076cb8 100644
--- a/apps/builder/app/routes/rest.assets_.$name.tsx
+++ b/apps/builder/app/routes/rest.assets_.$name.tsx
@@ -18,7 +18,7 @@ import {
getBrowserAssetFormat,
parseAssetType,
type AssetInfoFallback,
-} from "@webstudio-is/project-build/runtime/assets";
+} from "@webstudio-is/project-build/runtime";
import { getBrowserUploadBody } from "~/services/asset-upload.server";
const createAssetUploadResponse = async ({
diff --git a/apps/builder/app/services/api-build.server.test.ts b/apps/builder/app/services/api-build.server.test.ts
index ace0c5485f..89a9b53857 100644
--- a/apps/builder/app/services/api-build.server.test.ts
+++ b/apps/builder/app/services/api-build.server.test.ts
@@ -12,7 +12,7 @@ import type { AppContext } from "@webstudio-is/trpc-interface/index.server";
import { authorizeProject } from "@webstudio-is/trpc-interface/index.server";
import { db as authDb } from "@webstudio-is/authorization-token/index.server";
import * as projectApi from "@webstudio-is/project/index.server";
-import * as projectBuild from "@webstudio-is/project-build/index.server";
+import * as projectBuild from "@webstudio-is/project-build/server";
import type { z } from "zod";
import {
commitBuildPatch,
diff --git a/apps/builder/app/services/api-build.server.ts b/apps/builder/app/services/api-build.server.ts
index d3637f262b..eab5a4ac52 100644
--- a/apps/builder/app/services/api-build.server.ts
+++ b/apps/builder/app/services/api-build.server.ts
@@ -5,7 +5,7 @@ import type { CompactBuild } from "@webstudio-is/project-build";
import {
loadBuildById,
loadDevBuildByProjectId,
-} from "@webstudio-is/project-build/index.server";
+} from "@webstudio-is/project-build/server";
import { buildPatchTransaction } from "@webstudio-is/protocol/schema";
import type { AppContext } from "@webstudio-is/trpc-interface/index.server";
import { serializePages } from "@webstudio-is/project-migrations/pages";
diff --git a/apps/builder/app/services/api-permits.server.ts b/apps/builder/app/services/api-permits.server.ts
index 3b7591f8c5..f6dcb47f2d 100644
--- a/apps/builder/app/services/api-permits.server.ts
+++ b/apps/builder/app/services/api-permits.server.ts
@@ -5,7 +5,7 @@ import {
type AuthPermit,
} from "@webstudio-is/trpc-interface/index.server";
import { db as authDb } from "@webstudio-is/authorization-token/index.server";
-import type { BuilderApiCapability } from "@webstudio-is/project-build/contracts/permissions";
+import type { BuilderApiCapability } from "@webstudio-is/project-build/contracts";
type ApiPermit = BuilderApiCapability;
type ProjectApiPermit = Extract<AuthPermit, BuilderApiCapability>;
diff --git a/apps/builder/app/services/api-router-introspection.server.ts b/apps/builder/app/services/api-router-introspection.server.ts
index 9f5b57cd1b..0ca0c8b8ab 100644
--- a/apps/builder/app/services/api-router-introspection.server.ts
+++ b/apps/builder/app/services/api-router-introspection.server.ts
@@ -5,7 +5,7 @@ import {
isHiddenPublicApiInputField,
mergeInputSchemaMetadata,
type InputSchemaMetadata,
-} from "@webstudio-is/project-build/contracts/input-schema";
+} from "@webstudio-is/project-build/contracts";
export type ApiRouterProcedure = {
_def?: {
diff --git a/apps/builder/app/services/api-router.server.test.ts b/apps/builder/app/services/api-router.server.test.ts
index 3db3ffbcd7..3a1f05a9d8 100644
--- a/apps/builder/app/services/api-router.server.test.ts
+++ b/apps/builder/app/services/api-router.server.test.ts
@@ -4,7 +4,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
import { z } from "zod";
import { createDefaultPages } from "@webstudio-is/project-build";
import type { CompactBuild } from "@webstudio-is/project-build";
-import * as projectBuild from "@webstudio-is/project-build/index.server";
+import * as projectBuild from "@webstudio-is/project-build/server";
import * as projectApi from "@webstudio-is/project/index.server";
import {
buildPatchTransaction,
@@ -728,7 +728,9 @@ describe("api instance queries", () => {
maxDepth: 1,
labelContains: "Hero",
})
- ).resolves.toEqual({
+ ).resolves.toMatchObject({
+ detail: "compact",
+ total: 1,
instances: [
{
id: "hero-1",
@@ -880,13 +882,14 @@ describe("api instance queries", () => {
projectId: "project-1",
withUsage: true,
})
- ).resolves.toEqual({
+ ).resolves.toMatchObject({
+ detail: "compact",
+ total: 1,
tokens: [
{
id: "token-1",
name: "Primary",
declarationCount: 1,
- styles: undefined,
usageCount: 1,
},
],
diff --git a/apps/builder/app/services/api-router.server.ts b/apps/builder/app/services/api-router.server.ts
index 55f1b2ce7c..880722e977 100644
--- a/apps/builder/app/services/api-router.server.ts
+++ b/apps/builder/app/services/api-router.server.ts
@@ -8,7 +8,7 @@ import {
type AuthPermit,
} from "@webstudio-is/trpc-interface/index.server";
import { loadById } from "@webstudio-is/project/index.server";
-import { loadDevBuildByProjectId } from "@webstudio-is/project-build/index.server";
+import { loadDevBuildByProjectId } from "@webstudio-is/project-build/server";
import {
createProjectDomain,
createUnpublishJobId,
@@ -22,7 +22,7 @@ import {
unpublishProjectDomains,
verifyProjectDomain,
} from "@webstudio-is/domain/index.server";
-import { getBuilderRuntimeOperationInputSchema } from "@webstudio-is/project-build/runtime/registry";
+import { getBuilderRuntimeOperationInputSchema } from "@webstudio-is/project-build/runtime";
import { loadAssetsByProject } from "@webstudio-is/asset-uploader/index.server";
import { buildPatchTransaction } from "@webstudio-is/protocol/schema";
import {
@@ -40,15 +40,15 @@ import { type Asset } from "@webstudio-is/sdk";
import {
applyContentModeTransaction,
getContentModeCapabilities,
-} from "@webstudio-is/project-build/runtime/content-mode-permissions";
+} from "@webstudio-is/project-build/runtime";
import type { CompactBuild } from "@webstudio-is/project-build";
import {
runtimeOperationContracts,
type RuntimeOperationId,
-} from "@webstudio-is/project-build/contracts/builder-runtime";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
-import type { BuilderNamespace } from "@webstudio-is/project-build/contracts/namespaces";
-import type { BuilderApiCapability } from "@webstudio-is/project-build/contracts/permissions";
+} from "@webstudio-is/project-build/contracts";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
+import type { BuilderNamespace } from "@webstudio-is/project-build/contracts";
+import type { BuilderApiCapability } from "@webstudio-is/project-build/contracts";
import {
buildGetInput,
buildPatchInput,
diff --git a/apps/builder/app/services/api-runtime.server.test.ts b/apps/builder/app/services/api-runtime.server.test.ts
index a2f295603f..4f2c1bd527 100644
--- a/apps/builder/app/services/api-runtime.server.test.ts
+++ b/apps/builder/app/services/api-runtime.server.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
import { TRPCError } from "@trpc/server";
import { createDefaultPages } from "@webstudio-is/project-build";
import type { CompactBuild } from "@webstudio-is/project-build";
-import { createEmptyWebstudioFragment } from "@webstudio-is/project-build/runtime/component-template";
+import { createEmptyWebstudioFragment } from "@webstudio-is/project-build/runtime";
import type { Asset } from "@webstudio-is/sdk";
import {
createBuilderRuntimeState,
diff --git a/apps/builder/app/services/api-runtime.server.ts b/apps/builder/app/services/api-runtime.server.ts
index 712804d588..f3dd5cfeee 100644
--- a/apps/builder/app/services/api-runtime.server.ts
+++ b/apps/builder/app/services/api-runtime.server.ts
@@ -1,11 +1,11 @@
import type { CompactBuild } from "@webstudio-is/project-build";
-import type { RuntimeOperationId } from "@webstudio-is/project-build/contracts/builder-runtime";
-import { executeBuilderRuntimeOperation } from "@webstudio-is/project-build/runtime/registry";
-import { BuilderRuntimeError } from "@webstudio-is/project-build/runtime/errors";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
-import { type BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime/mutation";
-import type { BuilderState } from "@webstudio-is/project-build/state/builder-state";
-import { createBuilderStateFromCompactBuild } from "@webstudio-is/project-build/state/adapters";
+import type { RuntimeOperationId } from "@webstudio-is/project-build/contracts";
+import { executeBuilderRuntimeOperation } from "@webstudio-is/project-build/runtime";
+import { BuilderRuntimeError } from "@webstudio-is/project-build/runtime";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
+import { type BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime";
+import type { BuilderState } from "@webstudio-is/project-build/state";
+import { createBuilderStateFromCompactBuild } from "@webstudio-is/project-build/state";
import { type Asset } from "@webstudio-is/sdk";
import { throwApiError } from "./api-errors.server";
diff --git a/apps/builder/app/services/build-router.server.ts b/apps/builder/app/services/build-router.server.ts
index 82fb138574..77ff3d5302 100644
--- a/apps/builder/app/services/build-router.server.ts
+++ b/apps/builder/app/services/build-router.server.ts
@@ -19,8 +19,8 @@ import {
import { normalizePatchRequest } from "~/shared/sync/patch/patch-normalize.server";
import { loadById } from "@webstudio-is/project/index.server";
import type { BuildPatchTransaction } from "@webstudio-is/project/index.server";
-import { loadDevBuildByProjectId } from "@webstudio-is/project-build/index.server";
-import { parseWebstudioJsxFragment } from "@webstudio-is/project-build/runtime/jsx";
+import { loadDevBuildByProjectId } from "@webstudio-is/project-build/server";
+import { parseWebstudioJsxFragment } from "@webstudio-is/project-build/transfer/server";
import { serializePages } from "@webstudio-is/project-migrations/pages";
import { loadAssetsByProject } from "@webstudio-is/asset-uploader/index.server";
import {
@@ -29,7 +29,7 @@ import {
bundleVersion,
publishedProjectBundle,
} from "@webstudio-is/protocol";
-import { removeAgentInstructionsFromProjectSettings } from "@webstudio-is/project-build/shared/project-settings";
+import { removeAgentInstructionsFromProjectSettings } from "@webstudio-is/project-build";
import {
loadProjectBundleByBuildId,
loadPublishedProjectBundleByProjectId,
diff --git a/apps/builder/app/services/project-import.server.ts b/apps/builder/app/services/project-import.server.ts
index 838dbc42cd..2c2587646c 100644
--- a/apps/builder/app/services/project-import.server.ts
+++ b/apps/builder/app/services/project-import.server.ts
@@ -4,10 +4,12 @@ import {
type AppContext,
} from "@webstudio-is/trpc-interface/index.server";
import {
- loadDevBuildByProjectId,
serializeConfig,
serializeData,
-} from "@webstudio-is/project-build/index.server";
+ serializeStyles,
+ serializeStyleSourceSelections,
+} from "@webstudio-is/project-build/persistence";
+import { loadDevBuildByProjectId } from "@webstudio-is/project-build/server";
import {
migratePages,
serializePages,
@@ -15,9 +17,7 @@ import {
import {
createProjectSettingsFromPages,
removeLegacyProjectSettingsFromPages,
-} from "@webstudio-is/project-build/shared/project-settings";
-import { serializeStyles } from "@webstudio-is/project-build/styles.server";
-import { serializeStyleSourceSelections } from "@webstudio-is/project-build/style-source-selections.server";
+} from "@webstudio-is/project-build";
import {
isAssetFileName,
getMissingImportedAssetFilesMessage,
diff --git a/apps/builder/app/shared/$resources/sitemap.xml.server.ts b/apps/builder/app/shared/$resources/sitemap.xml.server.ts
index 4d4604a179..c1e97ac580 100644
--- a/apps/builder/app/shared/$resources/sitemap.xml.server.ts
+++ b/apps/builder/app/shared/$resources/sitemap.xml.server.ts
@@ -1,5 +1,5 @@
import { json } from "@remix-run/server-runtime";
-import { parsePages } from "@webstudio-is/project-build/index.server";
+import { parsePages } from "@webstudio-is/project-build/persistence";
import { getStaticSiteMapXml } from "@webstudio-is/sdk";
import { parseBuilderUrl } from "@webstudio-is/protocol";
import { isBuilder } from "../router-utils";
diff --git a/apps/builder/app/shared/awareness.test.tsx b/apps/builder/app/shared/awareness.test.tsx
index 5b7d1f8a53..8d08ace27b 100644
--- a/apps/builder/app/shared/awareness.test.tsx
+++ b/apps/builder/app/shared/awareness.test.tsx
@@ -2,7 +2,7 @@ import { afterEach, expect, test, vi } from "vitest";
import { $awareness, startPointerTracking, __testing__ } from "./awareness";
const { $pointerPosition, getUserAwareness } = __testing__;
-import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime/lookup";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
import { selectInstance, selectInstances } from "./nano-states/instances";
import { $selectedPageId } from "./nano-states";
import { $user } from "./nano-states/misc";
diff --git a/apps/builder/app/shared/breakpoints/select-breakpoint-by-order.ts b/apps/builder/app/shared/breakpoints/select-breakpoint-by-order.ts
index 721e499715..036c76f8e2 100644
--- a/apps/builder/app/shared/breakpoints/select-breakpoint-by-order.ts
+++ b/apps/builder/app/shared/breakpoints/select-breakpoint-by-order.ts
@@ -1,4 +1,4 @@
-import { groupBreakpoints } from "@webstudio-is/project-build/runtime/breakpoints";
+import { groupBreakpoints } from "@webstudio-is/project-build/runtime";
import { $selectedBreakpointId } from "../nano-states";
import { $breakpoints } from "~/shared/sync/data-stores";
import { setCanvasWidth } from "~/builder/shared/calc-canvas-width";
diff --git a/apps/builder/app/shared/copy-paste/asset-upload.test.tsx b/apps/builder/app/shared/copy-paste/asset-upload.test.tsx
index 8fcd8af664..ca53588f45 100644
--- a/apps/builder/app/shared/copy-paste/asset-upload.test.tsx
+++ b/apps/builder/app/shared/copy-paste/asset-upload.test.tsx
@@ -2,7 +2,7 @@ import { expect, test, vi } from "vitest";
import { $, AssetValue, renderTemplate } from "@webstudio-is/template";
import type { StyleDecl, WebstudioFragment } from "@webstudio-is/sdk";
import { denormalizeSrcProps } from "./asset-upload";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
test("extractSrcProps works well", async () => {
const data = renderTemplate(
diff --git a/apps/builder/app/shared/copy-paste/asset-upload.ts b/apps/builder/app/shared/copy-paste/asset-upload.ts
index 520af63bbc..6b4d5fe593 100644
--- a/apps/builder/app/shared/copy-paste/asset-upload.ts
+++ b/apps/builder/app/shared/copy-paste/asset-upload.ts
@@ -1,6 +1,6 @@
import type { WebstudioFragment } from "@webstudio-is/sdk";
import { builderApi } from "../builder-api";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
import { produce, enablePatches, type Patch, applyPatches } from "immer";
enablePatches();
diff --git a/apps/builder/app/shared/copy-paste/fragment-utils.ts b/apps/builder/app/shared/copy-paste/fragment-utils.ts
index df9bccf870..785114c4e6 100644
--- a/apps/builder/app/shared/copy-paste/fragment-utils.ts
+++ b/apps/builder/app/shared/copy-paste/fragment-utils.ts
@@ -1,5 +1,5 @@
import type { WebstudioFragment } from "@webstudio-is/sdk";
-import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime/breakpoints";
+import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime";
import {
insertWebstudioFragmentAt,
type Insertable,
diff --git a/apps/builder/app/shared/copy-paste/plugin-html.ts b/apps/builder/app/shared/copy-paste/plugin-html.ts
index 45502beabe..31c933b126 100644
--- a/apps/builder/app/shared/copy-paste/plugin-html.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-html.ts
@@ -1,5 +1,5 @@
import type { WebstudioFragment } from "@webstudio-is/sdk";
-import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime/html";
+import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime";
import { generateFragmentFromTailwind } from "../tailwind/tailwind";
import { denormalizeSrcProps } from "./asset-upload";
import { pasteHandled, pasteIgnored, type Plugin } from "./copy-paste";
diff --git a/apps/builder/app/shared/copy-paste/plugin-instance.ts b/apps/builder/app/shared/copy-paste/plugin-instance.ts
index bf92bcbc2e..8851ba9c19 100644
--- a/apps/builder/app/shared/copy-paste/plugin-instance.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-instance.ts
@@ -5,14 +5,14 @@ import {
getCommonAncestorSelector,
getPasteRootInstanceIds,
mergeWebstudioFragments,
-} from "@webstudio-is/project-build/runtime/fragment";
+} from "@webstudio-is/project-build/runtime";
import {
instanceTransferDataVersion,
instancesTransferDataVersion,
parseInstanceTransferData,
type InstanceTransferData,
type InstancesTransferData,
-} from "@webstudio-is/project-build/runtime/data-formats/instance-transfer";
+} from "@webstudio-is/project-build/transfer";
import { findClosestInsertable } from "../instance-utils/insert";
import {
executeRuntimeMutationAsync,
@@ -30,8 +30,8 @@ import { $instances } from "~/shared/sync/data-stores";
import {
type InstanceSelector,
sortInstancePathsForChildMutation,
-} from "@webstudio-is/project-build/runtime/tree";
-import { findChildReferenceIndex } from "@webstudio-is/project-build/runtime/instances";
+} from "@webstudio-is/project-build/runtime";
+import { findChildReferenceIndex } from "@webstudio-is/project-build/runtime";
import { deleteInstanceBySelector } from "../instance-utils/mutation";
import {
$allSelectedInstanceSelectors,
@@ -40,10 +40,10 @@ import {
$selectedInstanceSelector,
selectInstances,
} from "~/shared/nano-states";
-import { getInstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import { getInstancePath } from "@webstudio-is/project-build/runtime";
import { builderApi } from "../builder-api";
import { pasteHandled, pasteIgnored, type Plugin } from "./copy-paste";
-import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime/breakpoints";
+import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime";
const invalidPasteDataMessage =
"Could not paste Webstudio instance data. The clipboard data appears to be incomplete or invalid.";
diff --git a/apps/builder/app/shared/copy-paste/plugin-jsx.test.ts b/apps/builder/app/shared/copy-paste/plugin-jsx.test.ts
index 9f5aa39f8d..c68961382d 100644
--- a/apps/builder/app/shared/copy-paste/plugin-jsx.test.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-jsx.test.ts
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, test, vi } from "vitest";
-import { createEmptyWebstudioFragment } from "@webstudio-is/project-build/runtime/component-template";
-import { inspectWebstudioJsxFragmentSyntax } from "@webstudio-is/project-build/runtime/jsx/syntax";
+import { createEmptyWebstudioFragment } from "@webstudio-is/project-build/runtime";
+import { inspectWebstudioJsxFragmentSyntax } from "@webstudio-is/project-build/transfer";
import { isLikelyWebstudioJsx, jsx } from "./plugin-jsx";
import { $project } from "../sync/data-stores";
import { pasteHandled, pasteIgnored } from "./copy-paste";
diff --git a/apps/builder/app/shared/copy-paste/plugin-jsx.ts b/apps/builder/app/shared/copy-paste/plugin-jsx.ts
index 3d08b42b52..674e83fcc7 100644
--- a/apps/builder/app/shared/copy-paste/plugin-jsx.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-jsx.ts
@@ -1,6 +1,6 @@
import { nativeClient } from "../trpc/trpc-client";
import { $project } from "../sync/data-stores";
-import { isLikelyWebstudioJsxFragment } from "@webstudio-is/project-build/runtime/jsx/utils";
+import { isLikelyWebstudioJsxFragment } from "@webstudio-is/project-build/transfer";
import { pasteHandled, pasteIgnored, type Plugin } from "./copy-paste";
import { insertFragmentWithBreakpointWarning } from "./fragment-utils";
diff --git a/apps/builder/app/shared/copy-paste/plugin-markdown.ts b/apps/builder/app/shared/copy-paste/plugin-markdown.ts
index 0c48d6e236..c659990ccb 100644
--- a/apps/builder/app/shared/copy-paste/plugin-markdown.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-markdown.ts
@@ -1,7 +1,7 @@
import { gfm, gfmHtml } from "micromark-extension-gfm";
import { micromark } from "micromark";
import { denormalizeSrcProps } from "./asset-upload";
-import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime/html";
+import { generateFragmentFromHtml } from "@webstudio-is/project-build/runtime";
import { pasteHandled, pasteIgnored, type Plugin } from "./copy-paste";
import {
hasFragmentData,
diff --git a/apps/builder/app/shared/copy-paste/plugin-page.ts b/apps/builder/app/shared/copy-paste/plugin-page.ts
index 43d73e90c9..db5cc4bdba 100644
--- a/apps/builder/app/shared/copy-paste/plugin-page.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-page.ts
@@ -12,13 +12,13 @@ import {
type PageTemplate,
} from "@webstudio-is/sdk";
import { $pages, $project } from "~/shared/sync/data-stores";
-import { detectFragmentTokenConflicts } from "@webstudio-is/project-build/runtime/fragment";
+import { detectFragmentTokenConflicts } from "@webstudio-is/project-build/runtime";
import { builderApi } from "../builder-api";
import {
createFolderCopyData,
createPageCopyData,
createTemplateCopyData,
-} from "@webstudio-is/project-build/runtime/page-copy";
+} from "@webstudio-is/project-build/runtime";
import {
pageTransferDataVersion,
parsePageTransferData,
@@ -26,11 +26,11 @@ import {
type PageTransferData,
type PageTransferItem,
type TemplateTransferData,
-} from "@webstudio-is/project-build/runtime/data-formats/page-transfer";
+} from "@webstudio-is/project-build/transfer";
import { $selectedPage } from "../nano-states";
import { getPageActionTarget } from "../page-action-target";
import { pasteHandled, pasteIgnored, type Plugin } from "./copy-paste";
-import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime/breakpoints";
+import { breakpointPasteLimitWarning } from "@webstudio-is/project-build/runtime";
const invalidPasteDataMessage =
"Could not paste Webstudio page data. The clipboard data appears to be incomplete or invalid.";
diff --git a/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.test.tsx b/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.test.tsx
index 78b482397f..eda8e33b45 100644
--- a/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.test.tsx
+++ b/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.test.tsx
@@ -17,7 +17,7 @@ import { $registeredComponentMetas } from "../../nano-states";
import { $breakpoints } from "~/shared/sync/data-stores";
import { $project, $styleSources, $styles } from "~/shared/sync/data-stores";
import invariant from "tiny-invariant";
-import { wfData } from "@webstudio-is/project-build/runtime/webflow/schema";
+import { wfData } from "@webstudio-is/project-build/transfer";
import { pasteIgnored } from "../copy-paste";
const { toWebstudioFragment } = __testing__;
diff --git a/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.ts b/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.ts
index 04d0cb7817..e786a5008c 100644
--- a/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.ts
+++ b/apps/builder/app/shared/copy-paste/plugin-webflow/plugin-webflow.ts
@@ -8,14 +8,14 @@ import {
type WfNode,
type WfStyle,
type WfAsset,
-} from "@webstudio-is/project-build/runtime/webflow/schema";
-import { addInstanceAndProperties } from "@webstudio-is/project-build/runtime/webflow/instances-properties";
-import { addStyles } from "@webstudio-is/project-build/runtime/webflow/styles";
+} from "@webstudio-is/project-build/transfer";
+import { addInstanceAndProperties } from "@webstudio-is/project-build/transfer";
+import { addStyles } from "@webstudio-is/project-build/transfer";
import { builderApi } from "~/shared/builder-api";
import { denormalizeSrcProps } from "../asset-upload";
import { nanoHash } from "~/shared/nano-hash";
import { pasteHandled, pasteIgnored, type Plugin } from "../copy-paste";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
import {
hasFragmentData,
insertFragmentWithBreakpointWarning,
diff --git a/apps/builder/app/shared/db/canvas.server.ts b/apps/builder/app/shared/db/canvas.server.ts
index 6a32ee5209..383929a058 100644
--- a/apps/builder/app/shared/db/canvas.server.ts
+++ b/apps/builder/app/shared/db/canvas.server.ts
@@ -6,8 +6,8 @@ import {
import {
loadBuildById,
loadDevBuildByProjectId,
-} from "@webstudio-is/project-build/index.server";
-import { collectFontFamiliesFromStyleDecls } from "@webstudio-is/project-build/runtime/style-utils";
+} from "@webstudio-is/project-build/server";
+import { collectFontFamiliesFromStyleDecls } from "@webstudio-is/project-build/runtime";
import { loadAssetsByProject } from "@webstudio-is/asset-uploader/index.server";
import type { AppContext } from "@webstudio-is/trpc-interface/index.server";
import {
diff --git a/apps/builder/app/shared/dom-utils.ts b/apps/builder/app/shared/dom-utils.ts
index f0321756ae..03bb60816b 100644
--- a/apps/builder/app/shared/dom-utils.ts
+++ b/apps/builder/app/shared/dom-utils.ts
@@ -1,6 +1,6 @@
import type { Instance } from "@webstudio-is/sdk";
import { idAttribute, selectorIdAttribute } from "@webstudio-is/react-sdk";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import { getIsVisuallyHidden } from "./visually-hidden";
export const getInstanceIdFromElement = (
diff --git a/apps/builder/app/shared/instance-utils/data.test.tsx b/apps/builder/app/shared/instance-utils/data.test.tsx
index f5f9d4bb28..87948e86d9 100644
--- a/apps/builder/app/shared/instance-utils/data.test.tsx
+++ b/apps/builder/app/shared/instance-utils/data.test.tsx
@@ -1,7 +1,8 @@
import { describe, expect, test } from "vitest";
import type { Asset, Instance, PageTemplate } from "@webstudio-is/sdk";
-import { createDefaultPages, findCycles } from "@webstudio-is/project-build";
-import type { BuilderRuntimeOperationInput } from "@webstudio-is/project-build/runtime/registry";
+import { createDefaultPages } from "@webstudio-is/project-build";
+import { findCycles } from "@webstudio-is/project-build/runtime";
+import type { BuilderRuntimeOperationInput } from "@webstudio-is/project-build/runtime";
import {
executeRuntimeMutation,
executeRuntimeMutationAsync,
diff --git a/apps/builder/app/shared/instance-utils/data.ts b/apps/builder/app/shared/instance-utils/data.ts
index 45d2cd8bbf..e4f224e799 100644
--- a/apps/builder/app/shared/instance-utils/data.ts
+++ b/apps/builder/app/shared/instance-utils/data.ts
@@ -8,9 +8,9 @@ import {
type BuilderRuntimeOperationInput,
type BuilderRuntimeOperationId,
type BuilderRuntimeOperationResult,
-} from "@webstudio-is/project-build/runtime/registry";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
-import { type BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime/mutation";
+} from "@webstudio-is/project-build/runtime";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
+import { type BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime";
import { $canOpenPageTemplates, $selectedPage } from "../nano-states";
import { createTransactionFromBuilderPatchPayload } from "../sync/builder-patch";
import {
diff --git a/apps/builder/app/shared/instance-utils/fragment.test.tsx b/apps/builder/app/shared/instance-utils/fragment.test.tsx
index cf9dc31f3f..ec6a7b60bc 100644
--- a/apps/builder/app/shared/instance-utils/fragment.test.tsx
+++ b/apps/builder/app/shared/instance-utils/fragment.test.tsx
@@ -1,10 +1,10 @@
import {
- __testing__,
+ fragmentTesting,
detectFragmentTokenConflicts,
detectPageTokenConflicts,
extractWebstudioFragment,
insertWebstudioFragmentCopy,
-} from "@webstudio-is/project-build/runtime/fragment";
+} from "@webstudio-is/project-build/runtime";
import { getWebstudioData } from "./data";
import { enableMapSet } from "immer";
import { describe, test, expect, beforeEach } from "vitest";
@@ -46,14 +46,14 @@ import {
$resources,
} from "~/shared/sync/data-stores";
import { registerContainers } from "../sync/sync-stores";
-import { getInstancePath } from "@webstudio-is/project-build/runtime/lookup";
-import { isFragmentContentModeCopyableProp } from "@webstudio-is/project-build/runtime/content-mode-copy-policy";
+import { getInstancePath } from "@webstudio-is/project-build/runtime";
+import { isFragmentContentModeCopyableProp } from "@webstudio-is/project-build/runtime";
const {
getFragmentInstancesData,
insertFragmentAssetsMutable,
insertFragmentBreakpointsMutable,
-} = __testing__;
+} = fragmentTesting;
enableMapSet();
registerContainers();
diff --git a/apps/builder/app/shared/instance-utils/insert.test.tsx b/apps/builder/app/shared/instance-utils/insert.test.tsx
index ccb06c7efc..372b839c60 100644
--- a/apps/builder/app/shared/instance-utils/insert.test.tsx
+++ b/apps/builder/app/shared/instance-utils/insert.test.tsx
@@ -40,7 +40,7 @@ import {
$resources,
} from "~/shared/sync/data-stores";
import { registerContainers } from "../sync/sync-stores";
-import { getInstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import { getInstancePath } from "@webstudio-is/project-build/runtime";
import { selectPage } from "../nano-states";
import { selectInstance } from "../nano-states";
import { $selectedPageId } from "../nano-states/pages";
diff --git a/apps/builder/app/shared/instance-utils/insert.ts b/apps/builder/app/shared/instance-utils/insert.ts
index 7a6211e45d..e3b3bb4dba 100644
--- a/apps/builder/app/shared/instance-utils/insert.ts
+++ b/apps/builder/app/shared/instance-utils/insert.ts
@@ -17,9 +17,9 @@ import {
resolveComponentInsertTarget,
resolveFragmentInsertTarget,
type InsertTarget,
-} from "@webstudio-is/project-build/runtime/insert-target";
-import { createComponentTemplateFragment } from "@webstudio-is/project-build/runtime/component-template";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+} from "@webstudio-is/project-build/runtime";
+import { createComponentTemplateFragment } from "@webstudio-is/project-build/runtime";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
import { getInstanceLabel } from "~/builder/shared/instance-label";
import { executeRuntimeMutation } from "./data";
diff --git a/apps/builder/app/shared/instance-utils/lookup.ts b/apps/builder/app/shared/instance-utils/lookup.ts
index 0a7324d783..2503e1be20 100644
--- a/apps/builder/app/shared/instance-utils/lookup.ts
+++ b/apps/builder/app/shared/instance-utils/lookup.ts
@@ -2,7 +2,7 @@ import type { Instance, Instances, Pages } from "@webstudio-is/sdk";
import {
findPageAndSelectorByInstanceId,
getInstancePath,
-} from "@webstudio-is/project-build/runtime/lookup";
+} from "@webstudio-is/project-build/runtime";
import { getInstanceLabel } from "~/builder/shared/instance-label";
/**
diff --git a/apps/builder/app/shared/instance-utils/mutation.test.tsx b/apps/builder/app/shared/instance-utils/mutation.test.tsx
index a694b28887..350861e442 100644
--- a/apps/builder/app/shared/instance-utils/mutation.test.tsx
+++ b/apps/builder/app/shared/instance-utils/mutation.test.tsx
@@ -11,11 +11,11 @@ import { enableMapSet } from "immer";
import { describe, test, expect, beforeEach } from "vitest";
import type { Project } from "@webstudio-is/project";
import { createDefaultPages } from "@webstudio-is/project-build";
-import { builderRuntimeContext } from "@webstudio-is/project-build/runtime/context";
+import { builderRuntimeContext } from "@webstudio-is/project-build/runtime";
import {
canConvertInstance,
reparentInstanceMutable,
-} from "@webstudio-is/project-build/runtime/instances";
+} from "@webstudio-is/project-build/runtime";
import { $, ws, expression, renderData } from "@webstudio-is/template";
import * as defaultMetas from "@webstudio-is/sdk-components-react/metas";
import * as radixMetas from "@webstudio-is/sdk-components-react-radix/metas";
@@ -35,7 +35,7 @@ import {
} from "@webstudio-is/sdk";
import { showAttribute } from "@webstudio-is/react-sdk";
import type { StyleProperty, StyleValue } from "@webstudio-is/css-engine";
-import type { InstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import type { InstancePath } from "@webstudio-is/project-build/runtime";
import { $registeredComponentMetas } from "../nano-states";
import {
$instances,
@@ -55,7 +55,7 @@ import {
import type {
DroppableTarget,
InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
enableMapSet();
registerContainers();
diff --git a/apps/builder/app/shared/instance-utils/mutation.ts b/apps/builder/app/shared/instance-utils/mutation.ts
index cd1179b7c4..5458d37841 100644
--- a/apps/builder/app/shared/instance-utils/mutation.ts
+++ b/apps/builder/app/shared/instance-utils/mutation.ts
@@ -15,15 +15,15 @@ import {
$textEditingInstanceSelector,
selectInstance,
} from "../nano-states";
-import type { InstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import type { InstancePath } from "@webstudio-is/project-build/runtime";
import { $instances, $props } from "../sync/data-stores";
import { $instanceTags } from "~/builder/features/style-panel/shared/model";
import {
type DroppableTarget,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
-import { canUnwrapInstancePath } from "@webstudio-is/project-build/runtime/instances";
-import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime/block";
+} from "@webstudio-is/project-build/runtime";
+import { canUnwrapInstancePath } from "@webstudio-is/project-build/runtime";
+import { canDeleteInstanceInContentMode } from "@webstudio-is/project-build/runtime";
import { executeRuntimeMutation } from "./data";
export const reparentInstance = (
diff --git a/apps/builder/app/shared/instance-utils/selection.ts b/apps/builder/app/shared/instance-utils/selection.ts
index 83cb66e3cc..71e91eecf9 100644
--- a/apps/builder/app/shared/instance-utils/selection.ts
+++ b/apps/builder/app/shared/instance-utils/selection.ts
@@ -3,7 +3,7 @@ import {
areInstanceSelectorsEqual,
isDescendantOrSelf,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
export const areSelectorListsEqual = (
left: InstanceSelector[],
diff --git a/apps/builder/app/shared/instance-utils/slot.ts b/apps/builder/app/shared/instance-utils/slot.ts
index 5ee1b14213..21aab9386d 100644
--- a/apps/builder/app/shared/instance-utils/slot.ts
+++ b/apps/builder/app/shared/instance-utils/slot.ts
@@ -7,7 +7,7 @@ import {
getSharedSlotBoundary,
getSlotFragmentId,
type SharedSlotBoundary,
-} from "@webstudio-is/project-build/runtime/slot";
+} from "@webstudio-is/project-build/runtime";
export {
countInstanceChildReferences,
diff --git a/apps/builder/app/shared/instance-utils/tree.test.ts b/apps/builder/app/shared/instance-utils/tree.test.ts
index 4a92814edd..17c97fa331 100644
--- a/apps/builder/app/shared/instance-utils/tree.test.ts
+++ b/apps/builder/app/shared/instance-utils/tree.test.ts
@@ -2,7 +2,7 @@ import { expect, test } from "vitest";
import {
areInstanceSelectorsEqual,
isDescendantOrSelf,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
test("compares instance selectors", () => {
expect(areInstanceSelectorsEqual(["child", "body"], ["child", "body"])).toBe(
diff --git a/apps/builder/app/shared/marketplace/db.server.ts b/apps/builder/app/shared/marketplace/db.server.ts
index e3f51c6007..f0db77d328 100644
--- a/apps/builder/app/shared/marketplace/db.server.ts
+++ b/apps/builder/app/shared/marketplace/db.server.ts
@@ -1,9 +1,7 @@
import { marketplaceProduct } from "@webstudio-is/project-build";
import type { MarketplaceOverviewItem } from "./types";
-import {
- loadApprovedProdBuildByProjectId,
- parseConfig,
-} from "@webstudio-is/project-build/index.server";
+import { loadApprovedProdBuildByProjectId } from "@webstudio-is/project-build/server";
+import { parseConfig } from "@webstudio-is/project-build/persistence";
import type { AppContext } from "@webstudio-is/trpc-interface/index.server";
import type { Project } from "@webstudio-is/project";
import { loadAssetsByProject } from "@webstudio-is/asset-uploader/index.server";
diff --git a/apps/builder/app/shared/nano-states/breakpoints.ts b/apps/builder/app/shared/nano-states/breakpoints.ts
index 056c77c78a..000f2b32b9 100644
--- a/apps/builder/app/shared/nano-states/breakpoints.ts
+++ b/apps/builder/app/shared/nano-states/breakpoints.ts
@@ -1,7 +1,7 @@
import { atom, computed } from "nanostores";
import type { Breakpoint } from "@webstudio-is/sdk";
import { $breakpoints } from "../sync/data-stores";
-import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime/breakpoints";
+import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime";
export const $selectedBreakpointId = atom<undefined | Breakpoint["id"]>(
undefined
diff --git a/apps/builder/app/shared/nano-states/canvas.ts b/apps/builder/app/shared/nano-states/canvas.ts
index a7e300337d..57b005b136 100644
--- a/apps/builder/app/shared/nano-states/canvas.ts
+++ b/apps/builder/app/shared/nano-states/canvas.ts
@@ -3,7 +3,7 @@ import type { Instance, Instances } from "@webstudio-is/sdk";
import type { FontWeight } from "@webstudio-is/fonts";
import type { Rect } from "@webstudio-is/design-system";
import { $instances } from "../sync/data-stores";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
export type TextToolbarState = {
selectionRect: undefined | DOMRect;
diff --git a/apps/builder/app/shared/nano-states/components.ts b/apps/builder/app/shared/nano-states/components.ts
index 799e8ce546..caa3c07fe7 100644
--- a/apps/builder/app/shared/nano-states/components.ts
+++ b/apps/builder/app/shared/nano-states/components.ts
@@ -13,7 +13,7 @@ import {
type Instance,
type WsComponentMeta,
} from "@webstudio-is/sdk";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import { $props, $instances } from "../sync/data-stores";
import { $memoryProps } from "./misc";
import { $selectedPage } from "./pages";
diff --git a/apps/builder/app/shared/nano-states/instance-selection.ts b/apps/builder/app/shared/nano-states/instance-selection.ts
index 0bae3adf4a..fca5ad7396 100644
--- a/apps/builder/app/shared/nano-states/instance-selection.ts
+++ b/apps/builder/app/shared/nano-states/instance-selection.ts
@@ -2,7 +2,7 @@ import { atom, computed } from "nanostores";
import {
areInstanceSelectorsEqual,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
import {
areSelectorListsEqual,
canResolveInstanceSelector,
diff --git a/apps/builder/app/shared/nano-states/instances.ts b/apps/builder/app/shared/nano-states/instances.ts
index e83d1c2a8f..4f08447ef4 100644
--- a/apps/builder/app/shared/nano-states/instances.ts
+++ b/apps/builder/app/shared/nano-states/instances.ts
@@ -6,8 +6,8 @@ import {
rootComponent,
} from "@webstudio-is/sdk";
import { $instances } from "../sync/data-stores";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
-import { getInstancePath } from "@webstudio-is/project-build/runtime/lookup";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
+import { getInstancePath } from "@webstudio-is/project-build/runtime";
import { $selectedPage } from "./pages";
import { $selectedInstanceSelector } from "./instance-selection";
export {
diff --git a/apps/builder/app/shared/nano-states/misc.ts b/apps/builder/app/shared/nano-states/misc.ts
index a4906bf6d3..59b5a61bdd 100644
--- a/apps/builder/app/shared/nano-states/misc.ts
+++ b/apps/builder/app/shared/nano-states/misc.ts
@@ -25,7 +25,7 @@ import type { CssProperty, UnitValue } from "@webstudio-is/css-engine";
import type { TokenPermissions } from "@webstudio-is/authorization-token";
import type { AssetType } from "@webstudio-is/asset-uploader";
import type { DragStartPayload } from "~/canvas/shared/use-drag-drop";
-import { type InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import { type InstanceSelector } from "@webstudio-is/project-build/runtime";
import type { ChildrenOrientation } from "@webstudio-is/design-system";
import { $selectedInstance, $selectedInstanceSelector } from "./instances";
import { getPermissions } from "../permissions";
diff --git a/apps/builder/app/shared/nano-states/project-settings.ts b/apps/builder/app/shared/nano-states/project-settings.ts
index fd499fb65b..9e9ad41607 100644
--- a/apps/builder/app/shared/nano-states/project-settings.ts
+++ b/apps/builder/app/shared/nano-states/project-settings.ts
@@ -3,6 +3,7 @@ import { atom } from "nanostores";
export type SectionName =
| "general"
| "agents"
+ | "connectAgent"
| "auth"
| "redirects"
| "publish"
diff --git a/apps/builder/app/shared/nano-states/props.ts b/apps/builder/app/shared/nano-states/props.ts
index cc366b2e9a..2dee8a7328 100644
--- a/apps/builder/app/shared/nano-states/props.ts
+++ b/apps/builder/app/shared/nano-states/props.ts
@@ -26,12 +26,12 @@ import { $instances } from "../sync/data-stores";
import { $dataSources, $props, $assets, $resources } from "../sync/data-stores";
import { $uploadingFilesDataStore, $memoryProps, $isPreviewMode } from "./misc";
import { $pages } from "../sync/data-stores";
-import type { InstanceSelector } from "@webstudio-is/project-build/runtime/tree";
+import type { InstanceSelector } from "@webstudio-is/project-build/runtime";
import { $dataSourceVariables } from "./variables";
import { uploadingFileDataToAsset } from "~/builder/shared/assets/asset-utils";
import { $selectedPage } from "./pages";
import { getInstanceKey } from "./instances";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import { $currentSystem } from "../system";
import {
$resourcesCache,
diff --git a/apps/builder/app/shared/project-settings/import-redirects-dialog.tsx b/apps/builder/app/shared/project-settings/import-redirects-dialog.tsx
index 7a89bd838c..c63948c0bd 100644
--- a/apps/builder/app/shared/project-settings/import-redirects-dialog.tsx
+++ b/apps/builder/app/shared/project-settings/import-redirects-dialog.tsx
@@ -25,9 +25,9 @@ import {
parseRedirects,
type ParsedRedirect,
type SkippedLine,
-} from "@webstudio-is/project-build/runtime/redirect-parsers";
-import { detectLoopsInBatch } from "@webstudio-is/project-build/runtime/redirect-loop-detection";
-import { normalizeRedirectSource } from "@webstudio-is/project-build/runtime/redirect-source";
+} from "@webstudio-is/project-build/runtime";
+import { detectLoopsInBatch } from "@webstudio-is/project-build/runtime";
+import { normalizeRedirectSource } from "@webstudio-is/project-build/runtime";
type ImportStep = "input" | "preview";
type MergeMode = "add" | "replace";
diff --git a/apps/builder/app/shared/project-settings/project-settings.tsx b/apps/builder/app/shared/project-settings/project-settings.tsx
index f078214649..b4f16e913d 100644
--- a/apps/builder/app/shared/project-settings/project-settings.tsx
+++ b/apps/builder/app/shared/project-settings/project-settings.tsx
@@ -22,6 +22,7 @@ import { $isDesignMode } from "~/shared/nano-states";
import { leftPanelWidth, rightPanelWidth } from "./utils";
import { SectionGeneral } from "./section-general";
import { SectionAgents } from "./section-agents";
+import { SectionConnectAgent } from "./section-connect-agent";
import { SectionAuth } from "./section-auth";
import { SectionRedirects } from "./section-redirects";
import { SectionPublish } from "./section-publish";
@@ -35,6 +36,7 @@ const sections = new Map<
>([
["general", SectionGeneral],
["agents", SectionAgents],
+ ["connectAgent", SectionConnectAgent],
["redirects", SectionRedirects],
["publish", SectionPublish],
["marketplace", SectionMarketplace],
@@ -44,6 +46,7 @@ const sections = new Map<
const sectionLabels = new Map<SectionName, string>([
["auth", "Authentication"],
+ ["connectAgent", "Connect your Agent"],
]);
export const ProjectSettingsDialog = ({
diff --git a/apps/builder/app/shared/project-settings/section-auth.tsx b/apps/builder/app/shared/project-settings/section-auth.tsx
index 3f59b8aa5e..9789004140 100644
--- a/apps/builder/app/shared/project-settings/section-auth.tsx
+++ b/apps/builder/app/shared/project-settings/section-auth.tsx
@@ -26,7 +26,7 @@ import {
serializeWsAuth,
type WsAuthRoute,
} from "@webstudio-is/wsauth";
-import { validateBasicAuthCredentials } from "@webstudio-is/project-build/runtime/auth";
+import { validateBasicAuthCredentials } from "@webstudio-is/project-build/runtime";
import { $permissions } from "~/shared/nano-states";
import { $pages, $projectSettings } from "~/shared/sync/data-stores";
import { getExistingRoutePaths, sectionSpacing } from "./utils";
@@ -34,7 +34,7 @@ import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import {
parseProjectAuthRoutes,
validateProjectAuthRoute,
-} from "@webstudio-is/project-build/runtime/project-settings";
+} from "@webstudio-is/project-build/contracts";
const saveAuthRoutes = (authRoutes: WsAuthRoute[]) => {
executeRuntimeMutation({
diff --git a/apps/builder/app/shared/project-settings/section-connect-agent.tsx b/apps/builder/app/shared/project-settings/section-connect-agent.tsx
new file mode 100644
index 0000000000..83a09e87ef
--- /dev/null
+++ b/apps/builder/app/shared/project-settings/section-connect-agent.tsx
@@ -0,0 +1,95 @@
+import { useEffect, useState } from "react";
+import { useStore } from "@nanostores/react";
+import {
+ Button,
+ Grid,
+ Select,
+ Text,
+ TextArea,
+} from "@webstudio-is/design-system";
+import { CopyIcon } from "@webstudio-is/icons";
+import {
+ agentClients,
+ createAgentClientConfiguration,
+ createAgentShareUrl,
+ createAgentSetupCommand,
+ type AgentClient,
+} from "@webstudio-is/protocol";
+import { CopyToClipboard } from "~/shared/copy-to-clipboard";
+import { $authToken } from "~/shared/nano-states";
+import { sectionSpacing } from "./utils";
+
+const clientLabels: Record<AgentClient, string> = {
+ claude: "Claude Code",
+ codex: "Codex",
+ cursor: "Cursor",
+ vscode: "VS Code",
+};
+const clientOptions = agentClients.map((value) => ({
+ value,
+ label: clientLabels[value],
+}));
+
+export const SectionConnectAgent = () => {
+ const authToken = useStore($authToken);
+ const [client, setClient] = useState<AgentClient>("claude");
+ const [shareUrl, setShareUrl] = useState<string>();
+
+ useEffect(() => {
+ if (authToken === undefined) {
+ setShareUrl(undefined);
+ return;
+ }
+ setShareUrl(
+ createAgentShareUrl({
+ builderUrl: window.location.href,
+ authToken,
+ })
+ );
+ }, [authToken]);
+
+ const configuration = createAgentClientConfiguration(client);
+ const setupCommand =
+ shareUrl === undefined
+ ? undefined
+ : createAgentSetupCommand({ client, shareUrl });
+
+ return (
+ <Grid gap={3} css={sectionSpacing}>
+ <Text variant="titles">Connect your Agent</Text>
+ <Select
+ options={clientOptions}
+ value={clientOptions.find(({ value }) => value === client)}
+ getValue={({ value }) => value}
+ getLabel={({ label }) => label}
+ onChange={(option) => setClient(option.value)}
+ />
+ {setupCommand === undefined ? (
+ <Text color="subtle">
+ Create or replace an editable link from Share, then open it and return
+ here. Revoking that link also revokes agent access.
+ </Text>
+ ) : (
+ <Grid gap={1}>
+ <Text variant="labels">Run in your local project folder</Text>
+ <TextArea variant="mono" rows={5} readOnly value={setupCommand} />
+ <CopyToClipboard text={setupCommand} copyText="Copy setup command">
+ <Button prefix={<CopyIcon />} css={{ justifySelf: "start" }}>
+ Copy setup command
+ </Button>
+ </CopyToClipboard>
+ </Grid>
+ )}
+ <Grid gap={1}>
+ <Text variant="labels">Configuration: {configuration.path}</Text>
+ <TextArea
+ variant="mono"
+ rows={8}
+ readOnly
+ value={configuration.content}
+ />
+ <Text color="subtle">{configuration.hint}</Text>
+ </Grid>
+ </Grid>
+ );
+};
diff --git a/apps/builder/app/shared/project-settings/section-general.tsx b/apps/builder/app/shared/project-settings/section-general.tsx
index fc8246eaa0..1cedbde219 100644
--- a/apps/builder/app/shared/project-settings/section-general.tsx
+++ b/apps/builder/app/shared/project-settings/section-general.tsx
@@ -19,7 +19,7 @@ import {
import { CopyIcon, InfoCircleIcon } from "@webstudio-is/icons";
import { Image, wsImageLoader } from "@webstudio-is/image";
import type { ProjectMeta } from "@webstudio-is/sdk";
-import { validateContactEmail } from "@webstudio-is/project-build/runtime/project-settings";
+import { validateContactEmail } from "@webstudio-is/project-build/contracts";
import { ImageControl } from "./image-control";
import { $assets, $project } from "~/shared/sync/data-stores";
import { $permissions } from "~/shared/nano-states";
diff --git a/apps/builder/app/shared/project-settings/section-marketplace.tsx b/apps/builder/app/shared/project-settings/section-marketplace.tsx
index 45988606f8..6899f95041 100644
--- a/apps/builder/app/shared/project-settings/section-marketplace.tsx
+++ b/apps/builder/app/shared/project-settings/section-marketplace.tsx
@@ -22,7 +22,7 @@ import {
type MarketplaceProduct,
marketplaceCategories,
} from "@webstudio-is/project-build";
-import { marketplaceProductUpdateInput } from "@webstudio-is/project-build/runtime/project-settings";
+import { marketplaceProductUpdateInput } from "@webstudio-is/project-build/runtime";
import { ImageControl } from "./image-control";
import {
$assets,
diff --git a/apps/builder/app/shared/project-settings/section-redirects.tsx b/apps/builder/app/shared/project-settings/section-redirects.tsx
index 8c773df685..ae7c2679d7 100644
--- a/apps/builder/app/shared/project-settings/section-redirects.tsx
+++ b/apps/builder/app/shared/project-settings/section-redirects.tsx
@@ -41,11 +41,11 @@ import { executeRuntimeMutation } from "~/shared/instance-utils/data";
import {
LOOP_ERROR,
wouldCreateLoop,
-} from "@webstudio-is/project-build/runtime/redirect-loop-detection";
+} from "@webstudio-is/project-build/runtime";
import {
validateRedirectSource,
validateRedirectTarget,
-} from "@webstudio-is/project-build/runtime/project-settings";
+} from "@webstudio-is/project-build/runtime";
const statusCodeOptions = ["301", "302"] as const;
diff --git a/apps/builder/app/shared/resources.ts b/apps/builder/app/shared/resources.ts
index 38724f9f8b..b2a6eed53b 100644
--- a/apps/builder/app/shared/resources.ts
+++ b/apps/builder/app/shared/resources.ts
@@ -1,7 +1,7 @@
import { atom, computed } from "nanostores";
import type { DataSource, Resource, ResourceRequest } from "@webstudio-is/sdk";
import { restResourcesLoader } from "./router-utils";
-import { computeExpression } from "@webstudio-is/project-build/runtime/data";
+import { computeExpression } from "@webstudio-is/project-build/runtime";
import { fetch } from "./fetch.client";
import { getResourceKey } from "./resource-utils";
diff --git a/apps/builder/app/shared/sync/builder-patch.test.ts b/apps/builder/app/shared/sync/builder-patch.test.ts
index ef91f1af94..f02fc23bed 100644
--- a/apps/builder/app/shared/sync/builder-patch.test.ts
+++ b/apps/builder/app/shared/sync/builder-patch.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
import type { Instance, WebstudioData } from "@webstudio-is/sdk";
import { createDefaultPages } from "@webstudio-is/project-build";
import type { ProjectSettings } from "@webstudio-is/project-build";
-import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts/patch";
+import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts";
import {
createSyncChangesFromBuilderPatchPayload,
createTransactionFromBuilderPatchPayload,
diff --git a/apps/builder/app/shared/sync/builder-patch.ts b/apps/builder/app/shared/sync/builder-patch.ts
index b1bbc60aa1..730f0147ec 100644
--- a/apps/builder/app/shared/sync/builder-patch.ts
+++ b/apps/builder/app/shared/sync/builder-patch.ts
@@ -3,13 +3,13 @@ import { produceWithPatches, type Patch } from "immer";
import type {
BuilderPatch,
BuilderPatchChange,
-} from "@webstudio-is/project-build/contracts/patch";
+} from "@webstudio-is/project-build/contracts";
import type { WebstudioData } from "@webstudio-is/sdk";
import type {
MarketplaceProduct,
ProjectSettings,
} from "@webstudio-is/project-build";
-import * as builderStatePatch from "@webstudio-is/project-build/state/patch";
+import * as builderStatePatch from "@webstudio-is/project-build/state";
import { serverSyncStore } from "./sync-stores";
type BuilderPatchData = WebstudioData & {
diff --git a/apps/builder/app/shared/sync/command-queue.test.ts b/apps/builder/app/shared/sync/command-queue.test.ts
index df7ac326e4..32a079a2d0 100644
--- a/apps/builder/app/shared/sync/command-queue.test.ts
+++ b/apps/builder/app/shared/sync/command-queue.test.ts
@@ -1,5 +1,5 @@
import { describe, test, expect, beforeEach } from "vitest";
-import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts/patch";
+import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts";
import type { Transaction } from "@webstudio-is/sync-client";
import { enqueue, dequeueAll } from "./command-queue";
diff --git a/apps/builder/app/shared/sync/command-queue.ts b/apps/builder/app/shared/sync/command-queue.ts
index 35e0e9a0c4..d5d8955f18 100644
--- a/apps/builder/app/shared/sync/command-queue.ts
+++ b/apps/builder/app/shared/sync/command-queue.ts
@@ -1,6 +1,6 @@
import type { Project } from "@webstudio-is/project";
import type { Build } from "@webstudio-is/project-build";
-import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts/patch";
+import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts";
import type { Transaction } from "@webstudio-is/sync-client";
type Command =
diff --git a/apps/builder/app/shared/sync/patch/patch-auth.server.test.ts b/apps/builder/app/shared/sync/patch/patch-auth.server.test.ts
index 3c23a6ba22..c13f3ad079 100644
--- a/apps/builder/app/shared/sync/patch/patch-auth.server.test.ts
+++ b/apps/builder/app/shared/sync/patch/patch-auth.server.test.ts
@@ -55,7 +55,7 @@ vi.mock("@webstudio-is/trpc-interface/index.server", () => {
};
});
-vi.mock("@webstudio-is/project-build/runtime/content-mode-permissions", () => ({
+vi.mock("@webstudio-is/project-build/runtime", () => ({
applyContentModeTransaction,
getContentModeCapabilities,
}));
diff --git a/apps/builder/app/shared/sync/patch/patch-auth.server.ts b/apps/builder/app/shared/sync/patch/patch-auth.server.ts
index 0df04b8ee1..0b72db8b25 100644
--- a/apps/builder/app/shared/sync/patch/patch-auth.server.ts
+++ b/apps/builder/app/shared/sync/patch/patch-auth.server.ts
@@ -7,7 +7,7 @@ import {
import {
applyContentModeTransaction,
getContentModeCapabilities,
-} from "@webstudio-is/project-build/runtime/content-mode-permissions";
+} from "@webstudio-is/project-build/runtime";
import {
type Breakpoint,
type Prop,
@@ -16,9 +16,9 @@ import {
import {
parseData,
parseInstanceData,
-} from "@webstudio-is/project-build/build-parser.server";
-import { parseStyleSourceSelections } from "@webstudio-is/project-build/style-source-selections.server";
-import { parseStyles } from "@webstudio-is/project-build/styles.server";
+ parseStyleSourceSelections,
+ parseStyles,
+} from "@webstudio-is/project-build/persistence";
import env from "~/env/env.server";
import { readAccessToken } from "~/services/token.server";
import { componentMetas } from "~/shared/component-metas.server";
diff --git a/apps/builder/app/shared/sync/project-queue.test.ts b/apps/builder/app/shared/sync/project-queue.test.ts
index acdce5c3b4..1944a846b2 100644
--- a/apps/builder/app/shared/sync/project-queue.test.ts
+++ b/apps/builder/app/shared/sync/project-queue.test.ts
@@ -46,7 +46,7 @@ vi.mock("~/shared/builder-data", () => ({
// Imports (after mocks)
-import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts/patch";
+import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts";
import {
$hasUnsavedSyncChanges,
$syncStatus,
diff --git a/apps/builder/app/shared/sync/project-queue.ts b/apps/builder/app/shared/sync/project-queue.ts
index ea7b0b257f..b6887a4636 100644
--- a/apps/builder/app/shared/sync/project-queue.ts
+++ b/apps/builder/app/shared/sync/project-queue.ts
@@ -2,7 +2,7 @@ import { useEffect } from "react";
import { atom } from "nanostores";
import type { Project } from "@webstudio-is/project";
import type { Build } from "@webstudio-is/project-build";
-import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts/patch";
+import type { BuilderPatchChange } from "@webstudio-is/project-build/contracts";
import type { AuthPermit } from "@webstudio-is/trpc-interface/index.server";
import { toast } from "@webstudio-is/design-system";
import {
diff --git a/apps/builder/app/shared/sync/sync-stores.ts b/apps/builder/app/shared/sync/sync-stores.ts
index 8f8055438f..ea6b61a415 100644
--- a/apps/builder/app/shared/sync/sync-stores.ts
+++ b/apps/builder/app/shared/sync/sync-stores.ts
@@ -84,7 +84,7 @@ import { $resourcesCache } from "../resources";
import {
areInstanceSelectorsEqual,
type InstanceSelector,
-} from "@webstudio-is/project-build/runtime/tree";
+} from "@webstudio-is/project-build/runtime";
enableMapSet();
// safari structuredClone fix
diff --git a/apps/builder/app/shared/system.ts b/apps/builder/app/shared/system.ts
index e93a1da2ea..3a856a0135 100644
--- a/apps/builder/app/shared/system.ts
+++ b/apps/builder/app/shared/system.ts
@@ -4,7 +4,7 @@ import {
compilePathnamePattern,
matchPathnamePattern,
tokenizePathnamePattern,
-} from "@webstudio-is/project-build/runtime/url-pattern";
+} from "@webstudio-is/project-build/runtime";
import { $selectedPage } from "./nano-states/pages";
import { $pages } from "./sync/data-stores";
import { $publishedOrigin } from "./nano-states/misc";
diff --git a/apps/builder/app/shared/tailwind/tailwind.ts b/apps/builder/app/shared/tailwind/tailwind.ts
index 5dfb6e67c6..b60ad488a4 100644
--- a/apps/builder/app/shared/tailwind/tailwind.ts
+++ b/apps/builder/app/shared/tailwind/tailwind.ts
@@ -15,7 +15,7 @@ import {
type Prop,
type WebstudioFragment,
} from "@webstudio-is/sdk";
-import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime/breakpoints";
+import { isBaseBreakpoint } from "@webstudio-is/project-build/runtime";
import { preflight } from "./__generated__/preflight";
// breakpoints used to map tailwind classes to webstudio breakpoints
diff --git a/apps/builder/app/shared/token-conflict-dialog.tsx b/apps/builder/app/shared/token-conflict-dialog.tsx
index 901f012667..bb42c0609c 100644
--- a/apps/builder/app/shared/token-conflict-dialog.tsx
+++ b/apps/builder/app/shared/token-conflict-dialog.tsx
@@ -15,7 +15,7 @@ import {
Radio,
Label,
} from "@webstudio-is/design-system";
-import type { TokenConflict } from "@webstudio-is/project-build/runtime/style-copy";
+import type { TokenConflict } from "@webstudio-is/project-build/runtime";
export type ConflictResolution = "ours" | "theirs" | "merge";
diff --git a/apps/builder/e2e/tests/project-settings-runtime.[shard-2].e2e.ts b/apps/builder/e2e/tests/project-settings-runtime.[shard-2].e2e.ts
index b9404ae3f9..ac90c31420 100644
--- a/apps/builder/e2e/tests/project-settings-runtime.[shard-2].e2e.ts
+++ b/apps/builder/e2e/tests/project-settings-runtime.[shard-2].e2e.ts
@@ -1,6 +1,6 @@
import type { Page as PlaywrightPage } from "playwright";
import type { Page as WebstudioPage } from "@webstudio-is/sdk";
-import { parseProjectAuthRoutes } from "@webstudio-is/project-build/runtime/project-settings";
+import { parseProjectAuthRoutes } from "@webstudio-is/project-build/contracts";
import { loadDevBuild, updateProject } from "../db";
import { openProjectBuilder, waitForCanvasText } from "../flows/builder";
import { loginWithSecret } from "../flows/dashboard";
diff --git a/packages/cli/scripts/release-smoke.ts b/packages/cli/scripts/release-smoke.ts
index daa87abb3f..1448c850d3 100644
--- a/packages/cli/scripts/release-smoke.ts
+++ b/packages/cli/scripts/release-smoke.ts
@@ -20,9 +20,9 @@ import {
publicApiOperations,
} from "@webstudio-is/protocol";
import type { Instance } from "@webstudio-is/sdk";
-import type { BuilderState } from "@webstudio-is/project-build/state/builder-state";
-import type { BuilderPatchTransaction } from "@webstudio-is/project-build/contracts/patch";
-import type { BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime/mutation";
+import type { BuilderState } from "@webstudio-is/project-build/state";
+import type { BuilderPatchTransaction } from "@webstudio-is/project-build/contracts";
+import type { BuilderRuntimeMutation } from "@webstudio-is/project-build/runtime";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import React from "react";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -33,6 +33,11 @@ const buildId = "release-smoke-build";
const projectVersion = 1;
const sessionVersion = "cli-project-session-v1";
const releaseVersionPlaceholder = "0.0.0-webstudio-version";
+const agentSmokeClients = [
+ { connect: "claude", name: "claude-code" },
+ { connect: "codex", name: "codex" },
+ { connect: "cursor", name: "cursor" },
+] as const;
const reportPhase = (phase: string, startedAt = Date.now()) => {
process.stderr.write(
@@ -40,6 +45,25 @@ const reportPhase = (phase: string, startedAt = Date.now()) => {
);
};
+const runAgentWorkflowStep = async <Result>({
+ step,
+ recovery,
+ run,
+}: {
+ step: string;
+ recovery: string;
+ run: () => Promise<Result>;
+}) => {
+ try {
+ return await run();
+ } catch (error) {
+ throw new Error(
+ `Agent connection workflow stopped at "${step}": ${error instanceof Error ? error.message : String(error)} Recovery: ${recovery}`,
+ { cause: error }
+ );
+ }
+};
+
const replaceReleaseVersion = async (
directory: string,
releaseVersion: string,
@@ -447,9 +471,24 @@ const startFixtureApi = async (
const operationPath = new URL(
requestUrl,
"http://127.0.0.1"
- ).pathname.replace(/^\/trpc\/api\./, "");
+ ).pathname.replace(/^\/trpc\/(?:api\.)?/, "");
let data: unknown;
- if (operationPath === "build.patch") {
+ if (operationPath === "build.loadProjectBundleByProjectId") {
+ data = fixture.data;
+ } else if (operationPath === "projects.get") {
+ data = {
+ id: projectId,
+ name: "Release smoke project",
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ buildId,
+ version,
+ homePageId: "home",
+ features: {},
+ };
+ } else if (operationPath === "publish.create") {
+ data = { jobId: "release-smoke-staging-job" };
+ } else if (operationPath === "build.patch") {
const input = (await readTrpcInput(request)) as {
transactions?: BuilderPatchTransaction[];
};
@@ -656,11 +695,11 @@ const run = async () => {
statePatch,
] = await Promise.all([
import("@webstudio-is/project-migrations/pages"),
- import("@webstudio-is/project-build/state/adapters"),
- import("@webstudio-is/project-build/contracts/namespaces"),
+ import("@webstudio-is/project-build/state"),
+ import("@webstudio-is/project-build/contracts"),
import("@webstudio-is/project-build/project-session"),
- import("@webstudio-is/project-build/runtime/registry"),
- import("@webstudio-is/project-build/state/patch"),
+ import("@webstudio-is/project-build/runtime"),
+ import("@webstudio-is/project-build/state"),
]);
const temp = await mkdtemp(join(tmpdir(), "webstudio-release-smoke-"));
let preview: ChildProcess | undefined;
@@ -730,16 +769,47 @@ const run = async () => {
}
reportPhase("installed packed CLI", installStartedAt);
- await writeFile(
- join(projectDirectory, ".webstudio", "data.json"),
- JSON.stringify(fixture.data),
- "utf8"
+ const bin = join(projectDirectory, "node_modules", ".bin", "webstudio");
+ const env = {
+ ...process.env,
+ WEBSTUDIO_CONFIG_DIR: configDirectory,
+ };
+ const globalConfigPath = join(configDirectory, "webstudio-config.json");
+ await mkdir(dirname(globalConfigPath), { recursive: true });
+ await writeFile(globalConfigPath, "{}", "utf8");
+ const workflowStartedAt = Date.now();
+ const runCliStep = (step: string, recovery: string, args: string[]) =>
+ runAgentWorkflowStep({
+ step,
+ recovery,
+ run: () =>
+ execFileAsync(bin, args, {
+ cwd: projectDirectory,
+ env,
+ maxBuffer: 20 * 1024 * 1024,
+ }),
+ });
+
+ const shareLink = `${fixtureApi.origin}/builder/${projectId}?authToken=fixture`;
+ const initialized = await runCliStep(
+ "link",
+ "Create a fresh editable API share link and rerun webstudio init --link <share-link> --json.",
+ ["init", "--link", shareLink, "--json"]
);
- await writeFile(
- join(projectDirectory, ".webstudio", "config.json"),
- JSON.stringify({ projectId }),
- "utf8"
+ await assertJsonStdout(initialized.stdout, "agent workflow link");
+ await runCliStep(
+ "sync",
+ "Verify the share link has API access, then run webstudio sync again.",
+ ["sync"]
);
+ for (const { connect: client } of agentSmokeClients) {
+ await runCliStep(
+ `connect ${client}`,
+ `Run webstudio connect ${client} again and reload ${client}.`,
+ ["connect", client]
+ );
+ }
+
const state = adapters.createBuilderStateFromBuildData({
...fixture.build,
pages: pagesModule.migratePages(fixture.persistedPages),
@@ -778,21 +848,6 @@ const run = async () => {
}),
"utf8"
);
- const globalConfigPath = join(configDirectory, "webstudio-config.json");
- await mkdir(dirname(globalConfigPath), { recursive: true });
- await writeFile(
- globalConfigPath,
- JSON.stringify({
- [projectId]: { origin: fixtureApi.origin, token: "fixture" },
- }),
- "utf8"
- );
-
- const bin = join(projectDirectory, "node_modules", ".bin", "webstudio");
- const env = {
- ...process.env,
- WEBSTUDIO_CONFIG_DIR: configDirectory,
- };
const invoke = async (label: string, args: string[]) => {
const result = await execFileAsync(bin, args, {
cwd: projectDirectory,
@@ -803,6 +858,23 @@ const run = async () => {
return JSON.parse(result.stdout) as Record<string, unknown>;
};
+ const stagingPublish = await invoke("agent workflow staging publish", [
+ "publish",
+ "deploy",
+ "--target",
+ "staging",
+ "--json",
+ ]);
+ if (
+ stagingPublish.ok !== true ||
+ getRecord(stagingPublish.data, "staging publish data").jobId !==
+ "release-smoke-staging-job"
+ ) {
+ throw new Error(
+ `Agent connection workflow stopped at "staging publish": ${JSON.stringify(stagingPublish)} Recovery: Verify edit permission and retry webstudio publish deploy --target staging --json.`
+ );
+ }
+
const docs = await readFile(
join(import.meta.dirname, "../src/docs/api-use-cases.md"),
"utf8"
@@ -910,6 +982,39 @@ const run = async () => {
force: true,
});
const stdioStartedAt = Date.now();
+ for (const { name: clientName } of agentSmokeClients) {
+ await runAgentWorkflowStep({
+ step: `${clientName} connection smoke`,
+ recovery: `Reload ${clientName}, then verify its Webstudio MCP command starts in the linked project folder.`,
+ run: async () => {
+ const transport = new StdioClientTransport({
+ command: bin,
+ args: ["mcp"],
+ cwd: projectDirectory,
+ env: Object.fromEntries(
+ Object.entries(env).filter(
+ (entry): entry is [string, string] =>
+ typeof entry[1] === "string"
+ )
+ ),
+ stderr: "pipe",
+ });
+ transport.stderr?.on("data", () => {});
+ const client = new Client({ name: clientName, version: "1.0.0" });
+ await client.connect(transport);
+ try {
+ const tools = await client.listTools();
+ if (
+ tools.tools.some(({ name }) => name === "meta.index") === false
+ ) {
+ throw new Error("Webstudio connected but meta.index is missing.");
+ }
+ } finally {
+ await client.close();
+ }
+ },
+ });
+ }
const stdioTransport = new StdioClientTransport({
command: bin,
args: ["mcp"],
@@ -947,6 +1052,12 @@ const run = async () => {
};
await stdioClient.connect(stdioTransport);
try {
+ const inspection = await callTool("inspect");
+ if (inspection.id !== projectId) {
+ throw new Error(
+ `Inspect returned the wrong project: ${JSON.stringify(inspection)}`
+ );
+ }
const initialPages = await callTool("list-pages", {
includeFolders: true,
});
@@ -1068,6 +1179,17 @@ const run = async () => {
});
await callTool("preview.stop");
+ const workflowDuration = Date.now() - workflowStartedAt;
+ if (workflowDuration >= 10 * 60_000) {
+ throw new Error(
+ `Agent connection workflow exceeded ten minutes (${workflowDuration}ms). Recovery: Inspect the reported release-smoke phase timings and optimize the slowest blocked step.`
+ );
+ }
+ reportPhase(
+ "completed ten-minute agent connection workflow",
+ workflowStartedAt
+ );
+
const finalPages = await callTool("list-pages");
const finalPageNames = Array.isArray(finalPages.pages)
? finalPages.pages.map((page) => getRecord(page, "final page").name)
diff --git a/packages/cli/src/commands/api-command-docs.test.ts b/packages/cli/src/commands/api-command-docs.test.ts
index 92a791d8a0..5bec1c16af 100644
--- a/packages/cli/src/commands/api-command-docs.test.ts
+++ b/packages/cli/src/commands/api-command-docs.test.ts
@@ -1,7 +1,7 @@
import { expect, test } from "vitest";
import { createProjectSessionMcpCore } from "@webstudio-is/project-build/mcp";
-import { getRuntimeGeneratedInputPaths } from "@webstudio-is/project-build/contracts/input-schema";
-import { builderRuntimeOperations } from "@webstudio-is/project-build/runtime/registry";
+import { getRuntimeGeneratedInputPaths } from "@webstudio-is/project-build/contracts";
+import { builderRuntimeOperations } from "@webstudio-is/project-build/runtime";
import { publicApiOperations } from "@webstudio-is/protocol";
import {
apiCommandMetadata,
diff --git a/packages/cli/src/commands/api-command.test.ts b/packages/cli/src/commands/api-command.test.ts
index 7fc055e0bc..9a11c1dd9a 100644
--- a/packages/cli/src/commands/api-command.test.ts
+++ b/packages/cli/src/commands/api-command.test.ts
@@ -1828,6 +1828,9 @@ test("passes style token inclusion through to the api", async () => {
property: undefined,
propertyFilter: undefined,
includeTokens: true,
+ cursor: undefined,
+ limit: undefined,
+ verbose: undefined,
},
});
});
@@ -1837,16 +1840,18 @@ test("lists design tokens with filters", async () => {
options: {
command: "list-design-tokens",
filter: "brand",
- includeStyles: true,
+ verbose: true,
withUsage: true,
sort: "usage",
},
call: apiCalls.listDesignTokens,
connection: {
filter: "brand",
- includeStyles: true,
withUsage: true,
sort: "usage",
+ cursor: undefined,
+ limit: undefined,
+ verbose: true,
},
});
});
diff --git a/packages/cli/src/commands/api-command.ts b/packages/cli/src/commands/api-command.ts
index f50d1af407..4a455d2a5b 100644
--- a/packages/cli/src/commands/api-command.ts
+++ b/packages/cli/src/commands/api-command.ts
@@ -71,6 +71,21 @@ export const apiCommandOptions = (yargs: CommonYargsArgv) =>
"Refresh required local project namespaces from the remote project before running a local-capable command.",
});
+const outputDetailCommandOptions = (yargs: CommonYargsArgv) =>
+ yargs
+ .option("cursor", {
+ type: "string",
+ describe: "Pagination cursor returned by the previous call",
+ })
+ .option("limit", {
+ type: "number",
+ describe: "Maximum records to return",
+ })
+ .option("verbose", {
+ type: "boolean",
+ describe: "Expand compact records with complete values and diagnostics",
+ });
+
const requiredInputOption = (yargs: CommonYargsArgv, describe: string) =>
yargs.option("input", {
type: "string",
@@ -557,7 +572,7 @@ export const deleteFolderCommandOptions = (yargs: CommonYargsArgv) =>
});
export const instanceListCommandOptions = (yargs: CommonYargsArgv) =>
- apiCommandOptions(yargs)
+ outputDetailCommandOptions(apiCommandOptions(yargs))
.option("page", {
type: "string",
describe: "Limit results to a page id",
@@ -734,7 +749,7 @@ export const textUpdateCommandOptions = (yargs: CommonYargsArgv) =>
});
export const stylesCommandOptions = (yargs: CommonYargsArgv) =>
- apiCommandOptions(yargs)
+ outputDetailCommandOptions(apiCommandOptions(yargs))
.option("instance", {
type: "string",
describe: "Limit declarations to one instance id",
@@ -789,15 +804,11 @@ export const replaceStylesCommandOptions = (yargs: CommonYargsArgv) =>
);
export const designTokensCommandOptions = (yargs: CommonYargsArgv) =>
- apiCommandOptions(yargs)
+ outputDetailCommandOptions(apiCommandOptions(yargs))
.option("filter", {
type: "string",
describe: "Only return design tokens whose name contains this text",
})
- .option("include-styles", {
- type: "boolean",
- describe: "Include full inline style declarations for each design token",
- })
.option("with-usage", {
type: "boolean",
default: true,
@@ -1134,7 +1145,7 @@ export const verifyDomainCommandOptions = (yargs: CommonYargsArgv) =>
});
export const assetsCommandOptions = (yargs: CommonYargsArgv) =>
- apiCommandOptions(yargs)
+ outputDetailCommandOptions(apiCommandOptions(yargs))
.option("type", {
choices: ["image", "font"] as const,
describe: "Only return assets of this type",
@@ -1146,14 +1157,6 @@ export const assetsCommandOptions = (yargs: CommonYargsArgv) =>
.option("with-usage", {
type: "boolean",
describe: "Include how many build references point to each asset",
- })
- .option("cursor", {
- type: "string",
- describe: "Pagination cursor returned as nextCursor by the previous call",
- })
- .option("limit", {
- type: "number",
- describe: "Maximum number of assets to return",
});
export const auditCommandOptions = (yargs: CommonYargsArgv) =>
@@ -1356,7 +1359,6 @@ export type ApiCommandOptions = {
position?: "before-local" | "after-local" | "before" | "after";
filter?: string;
withUsage?: boolean;
- includeStyles?: boolean;
includeSystem?: boolean;
scopeInstance?: string;
type?: "image" | "font" | "file";
@@ -1832,6 +1834,7 @@ export const printAuditReport = (value: unknown) => {
pagePaths?: string[];
}>;
renderedFailureCount?: number;
+ renderedState?: "complete" | "partial" | "confirmation-required" | "failed";
renderedPlan?: {
captureCount?: number;
confirmationToken?: string;
@@ -1871,7 +1874,7 @@ export const printAuditReport = (value: unknown) => {
}
if (result.renderedCheckCount !== undefined) {
console.info(
- `Rendered: ${result.renderedCheckCount} checks, ${result.renderedIssueCount ?? 0} issues, ${result.renderedFailureCount ?? 0} failures.`
+ `Rendered (${result.renderedState ?? "complete"}): ${result.renderedCheckCount} checks, ${result.renderedIssueCount ?? 0} issues, ${result.renderedFailureCount ?? 0} failures.`
);
for (const summary of result.renderedIssueSummaries ?? []) {
const pages = summary.pagePaths?.join(", ");
@@ -2351,6 +2354,9 @@ const apiCommandHandlers: Partial<Record<ApiCommandName, ApiCommandHandler>> = {
component: options.component,
tag: options.tag,
labelContains: options.label,
+ cursor: options.cursor,
+ limit: options.limit,
+ verbose: options.verbose,
};
return runProjectSessionCommand(
"list-instances",
@@ -2499,6 +2505,9 @@ const apiCommandHandlers: Partial<Record<ApiCommandName, ApiCommandHandler>> = {
property: options.property,
propertyFilter: options.propertyFilter,
includeTokens: options.includeTokens,
+ cursor: options.cursor,
+ limit: options.limit,
+ verbose: options.verbose,
};
return runProjectSessionCommand(
"get-styles",
@@ -2548,8 +2557,10 @@ const apiCommandHandlers: Partial<Record<ApiCommandName, ApiCommandHandler>> = {
const input = {
filter: options.filter,
withUsage: options.withUsage,
- includeStyles: options.includeStyles,
sort: designTokenSortOption(options.sort),
+ cursor: options.cursor,
+ limit: options.limit,
+ verbose: options.verbose,
};
return runProjectSessionCommand(
"list-design-tokens",
@@ -2889,6 +2900,7 @@ const apiCommandHandlers: Partial<Record<ApiCommandName, ApiCommandHandler>> = {
withUsage: options.withUsage,
cursor: options.cursor,
limit: options.limit,
+ verbose: options.verbose,
};
return runProjectSessionCommand(
"list-assets",
diff --git a/packages/cli/src/commands/audit.test.ts b/packages/cli/src/commands/audit.test.ts
index bc15c0fe0c..39aeb12e4e 100644
--- a/packages/cli/src/commands/audit.test.ts
+++ b/packages/cli/src/commands/audit.test.ts
@@ -122,7 +122,7 @@ describe("audit CLI input", () => {
"Audit: 0 findings (0 errors, 0 warnings, 0 info)"
);
expect(info).toHaveBeenCalledWith(
- "Rendered: 2 checks, 1 issues, 0 failures."
+ "Rendered (complete): 2 checks, 1 issues, 0 failures."
);
expect(info).toHaveBeenCalledWith(
" oversized-image: 1 occurrences across 1 captures (/)."
diff --git a/packages/cli/src/commands/connect.ts b/packages/cli/src/commands/connect.ts
index b42694422b..c6b031ba49 100644
--- a/packages/cli/src/commands/connect.ts
+++ b/packages/cli/src/commands/connect.ts
@@ -2,6 +2,15 @@ import { readFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { cwd } from "node:process";
import { log } from "@clack/prompts";
+import {
+ agentClients,
+ agentClientTargets,
+ agentServerName,
+ createAgentServerEntry,
+ createCodexAgentSnippet,
+ defaultAgentServerCommand,
+ type AgentClient,
+} from "@webstudio-is/protocol";
import {
createFolderIfNotExists,
isFileExists,
@@ -14,12 +23,10 @@ import type {
StrictYargsOptionsToInterface,
} from "./yargs-types";
-export const connectClients = ["claude", "codex", "cursor", "vscode"] as const;
-export type ConnectClient = (typeof connectClients)[number];
-
-export const defaultServerCommand = "npx -y webstudio@latest mcp";
-
-export const mcpServerName = "webstudio";
+export const connectClients = agentClients;
+export type ConnectClient = AgentClient;
+export const defaultServerCommand = defaultAgentServerCommand;
+export const mcpServerName = agentServerName;
export type ConnectFileResult =
| "created"
@@ -27,71 +34,9 @@ export type ConnectFileResult =
| "unchanged"
| "blocked-by-invalid-json";
-type JsonClientTarget = {
- /**
- * Config file path relative to the project root.
- */
- path: string;
- /**
- * Root object key holding server entries in the client config schema.
- */
- rootKey: "mcpServers" | "servers";
- /**
- * Extra fields required by the client config schema.
- */
- extraServerFields?: Record<string, unknown>;
- /**
- * One-line reload hint printed after the config is written.
- */
- hint: string;
-};
-
-const jsonClientTargets: Record<
- Exclude<ConnectClient, "codex">,
- JsonClientTarget
-> = {
- claude: {
- path: ".mcp.json",
- rootKey: "mcpServers",
- hint: "Restart Claude Code in this directory and approve the webstudio server.",
- },
- cursor: {
- path: join(".cursor", "mcp.json"),
- rootKey: "mcpServers",
- hint: "Reload Cursor and enable the webstudio server in MCP settings.",
- },
- vscode: {
- path: join(".vscode", "mcp.json"),
- rootKey: "servers",
- extraServerFields: { type: "stdio" },
- hint: "Reload VS Code and start the webstudio server from the MCP view.",
- },
-};
-
-const parseServerCommand = (serverCommand: string) => {
- const [command, ...args] = serverCommand.trim().split(/\s+/);
- if (command === undefined || command === "") {
- throw new Error("--command must not be empty.");
- }
- return { command, args };
-};
-
-export const createServerEntry = (
- serverCommand: string,
- extraServerFields?: Record<string, unknown>
-) => {
- const { command, args } = parseServerCommand(serverCommand);
- return { ...extraServerFields, command, args };
-};
-
-export const createCodexSnippet = (serverCommand: string) => {
- const { command, args } = parseServerCommand(serverCommand);
- return [
- `[mcp_servers.${mcpServerName}]`,
- `command = ${JSON.stringify(command)}`,
- `args = [${args.map((arg) => JSON.stringify(arg)).join(", ")}]`,
- ].join("\n");
-};
+const jsonClientTargets = agentClientTargets;
+export const createServerEntry = createAgentServerEntry;
+export const createCodexSnippet = createCodexAgentSnippet;
const isJsonObject = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && Array.isArray(value) === false;
@@ -233,7 +178,7 @@ export const connect = async (
const target = jsonClientTargets[client];
const serverEntry = createServerEntry(
serverCommand,
- target.extraServerFields
+ "extraServerFields" in target ? target.extraServerFields : undefined
);
if (options.print === true) {
diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts
index 03400c7cff..46af49dc1e 100644
--- a/packages/cli/src/commands/mcp.ts
+++ b/packages/cli/src/commands/mcp.ts
@@ -6,8 +6,8 @@ import {
createProjectSessionMcpCore,
createMcpStdioTransport,
} from "@webstudio-is/project-build/mcp";
-import type { BuilderNamespace } from "@webstudio-is/project-build/contracts/namespaces";
-import { diffPngFiles } from "@webstudio-is/project-build/visual/screenshot-diff";
+import type { BuilderNamespace } from "@webstudio-is/project-build/contracts";
+import { diffPngFiles } from "@webstudio-is/project-build/visual";
import {
publicApiOperationRequiresServerSupport,
publicApiOperations,
@@ -15,7 +15,7 @@ import {
import { importProjectBundleWithAssets } from "@webstudio-is/http-client";
import packageJson from "../../package.json" with { type: "json" };
import type { ProjectSessionSnapshot } from "@webstudio-is/project-build/project-session";
-import type { SemanticValidationIssue } from "@webstudio-is/project-build/runtime/errors";
+import type { SemanticValidationIssue } from "@webstudio-is/project-build/runtime";
import { resolveApiConnection } from "../api-connection";
import {
getCliErrorIssues,
diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts
index 039f5e0db6..db8e20d072 100644
--- a/packages/cli/src/commands/preview.ts
+++ b/packages/cli/src/commands/preview.ts
@@ -17,7 +17,7 @@ import { join } from "node:path";
import { chdir, cwd } from "node:process";
import { promisify } from "node:util";
import { log } from "@clack/prompts";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
import { prebuild } from "../prebuild";
import { LOCAL_CONFIG_FILE, LOCAL_DATA_FILE } from "../config";
import { HandledCliError } from "../errors";
diff --git a/packages/cli/src/commands/schema.test.ts b/packages/cli/src/commands/schema.test.ts
index 4847966bd7..e03308e098 100644
--- a/packages/cli/src/commands/schema.test.ts
+++ b/packages/cli/src/commands/schema.test.ts
@@ -18,7 +18,7 @@ afterEach(() => {
test("prints api command schema as json", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
- schema({ topic: "api", json: true });
+ schema({ topic: "api", json: true, verbose: true, limit: 200 });
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.projectScope).toContain("single project");
@@ -127,13 +127,14 @@ test("prints api command schema as json by default", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.name).toBe("webstudio-cli");
- expect(output.requiredOutputMode).toContain("always JSON");
+ expect(output.detail).toBe("compact");
+ expect(output).not.toHaveProperty("commandGroups");
});
-test("prints tiny mcp tool overview as json by default", () => {
+test("prints compact mcp tool summaries as json by default", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
- schema({ topic: "mcp", json: true });
+ schema({ topic: "mcp", json: true, limit: 200 });
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
const expectedTools = listProjectSessionMcpTools(publicApiOperations, {
@@ -145,10 +146,10 @@ test("prints tiny mcp tool overview as json by default", () => {
});
expect(output.name).toBe("webstudio-mcp");
- expect(output.detail).toBe("overview");
+ expect(output.detail).toBe("compact");
expect(output).not.toHaveProperty("callCommand");
expect(output.singleOpCallCommand).toContain("webstudio mcp single-op-call");
- expect(output.usage).toContain("--detail summary");
+ expect(output.usage).toContain("--verbose");
expect(output.discovery).toContain(
`webstudio mcp single-op-call meta.get_more_tools '{"tools":["insert-fragment"]}'`
);
@@ -160,20 +161,6 @@ test("prints tiny mcp tool overview as json by default", () => {
);
expect(output.resources).toEqual(listProjectSessionMcpResources());
expect(output.toolCount).toBe(expectedTools.length);
- expect(output.tools).toEqual(expectedTools.map((tool) => tool.name));
- expect(output.tools).toContain("insert-fragment");
- expect(output.tools).toContain("insert-component");
- expect(output.tools).not.toContain("append-instance");
-});
-
-test("prints mcp tool summary when requested", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- schema({ topic: "mcp", json: true, detail: "summary" });
-
- const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
-
- expect(output.detail).toBe("summary");
expect(output.tools).toEqual(
expect.arrayContaining([
expect.objectContaining({
@@ -215,11 +202,11 @@ test("prints mcp tool summary when requested", () => {
test("prints full mcp tool input schemas when requested", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
- schema({ topic: "mcp", json: true, detail: "full" });
+ schema({ topic: "mcp", json: true, verbose: true, limit: 200 });
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
- expect(output.detail).toBe("full");
+ expect(output.detail).toBe("verbose");
expect(output.tools).toEqual(
expect.arrayContaining([
expect.objectContaining({
@@ -261,6 +248,65 @@ test("prints full mcp tool input schemas when requested", () => {
);
});
+test("compact schema discovery is materially smaller but remains actionable", () => {
+ const info = vi.spyOn(console, "info").mockImplementation(() => undefined);
+
+ schema({ topic: "mcp", json: true, limit: 200 });
+ const compactText = String(info.mock.calls.at(-1)?.[0]);
+ const compact = JSON.parse(compactText);
+ schema({ topic: "mcp", json: true, verbose: true, limit: 200 });
+ const verboseText = String(info.mock.calls.at(-1)?.[0]);
+ const verbose = JSON.parse(verboseText);
+
+ expect(compact.toolCount).toBe(verbose.toolCount);
+ expect(compact.tools).toHaveLength(verbose.tools.length);
+ expect(compact.tools).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ name: "insert-fragment",
+ method: "mutation",
+ requiredInputFields: ["parentInstanceId", "fragment"],
+ }),
+ ])
+ );
+ expect(compactText).not.toContain("/packages/");
+ expect(compactText.length).toBeLessThan(verboseText.length * 0.5);
+});
+
+test("paginates compact and verbose schema discovery over the same tools", () => {
+ vi.spyOn(console, "info").mockImplementation(() => undefined);
+
+ schema({ topic: "mcp", json: true, limit: 2 });
+ const compact = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
+ schema({ topic: "mcp", json: true, verbose: true, limit: 2 });
+ const verbose = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
+ schema({
+ topic: "mcp",
+ json: true,
+ verbose: true,
+ cursor: verbose.nextCursor,
+ limit: 2,
+ });
+ const nextPage = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
+
+ expect(compact).toMatchObject({
+ detail: "compact",
+ returnedCount: 2,
+ nextCursor: "2",
+ });
+ expect(verbose).toMatchObject({
+ detail: "verbose",
+ returnedCount: 2,
+ nextCursor: "2",
+ });
+ expect(verbose.tools.map(({ name }: { name: string }) => name)).toEqual(
+ compact.tools.map(({ name }: { name: string }) => name)
+ );
+ expect(nextPage.tools.map(({ name }: { name: string }) => name)).not.toEqual(
+ verbose.tools.map(({ name }: { name: string }) => name)
+ );
+});
+
test("prints focused mcp tool schema with tool option", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
@@ -268,7 +314,7 @@ test("prints focused mcp tool schema with tool option", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
- expect(output.detail).toBe("full");
+ expect(output.detail).toBe("verbose");
expect(output.focusedToolNames).toEqual(["insert-fragment"]);
expect(output.toolCount).toBe(1);
expect(output.tools).toEqual([
@@ -286,7 +332,7 @@ test("prints focused mcp tool schema when topic is a tool name", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
- expect(output.detail).toBe("full");
+ expect(output.detail).toBe("verbose");
expect(output.focusedToolNames).toEqual(["insert-fragment"]);
expect(output.tools).toEqual([
expect.objectContaining({
@@ -305,7 +351,7 @@ test("prints mcp tool overview as json without json flag", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.name).toBe("webstudio-mcp");
- expect(output.detail).toBe("overview");
+ expect(output.detail).toBe("compact");
});
test("reports unknown schema topics with available topics", () => {
diff --git a/packages/cli/src/commands/schema.ts b/packages/cli/src/commands/schema.ts
index f9893344b9..bd28c40684 100644
--- a/packages/cli/src/commands/schema.ts
+++ b/packages/cli/src/commands/schema.ts
@@ -5,6 +5,8 @@ import {
import {
listProjectSessionMcpResources,
listProjectSessionMcpTools,
+ paginateOutput,
+ projectOutput,
} from "@webstudio-is/project-build/mcp";
import { HandledCliError } from "../errors";
import { printJson } from "../json-output";
@@ -35,11 +37,17 @@ export const schemaOptions = (yargs: CommonYargsArgv) =>
"Accepted for compatibility. Schema output is always machine-readable JSON",
default: false,
})
- .option("detail", {
+ .option("verbose", {
+ type: "boolean",
+ describe: "Include complete command and tool schemas",
+ })
+ .option("cursor", {
type: "string",
- choices: ["overview", "summary", "full"] as const,
- describe:
- "Schema detail. For mcp, overview is tiny, summary lists tools, full includes every input schema.",
+ describe: "Pagination cursor returned by the previous schema call",
+ })
+ .option("limit", {
+ type: "number",
+ describe: "Maximum schemas to return, from 1 to 200",
})
.option("tool", {
type: "string",
@@ -47,15 +55,15 @@ export const schemaOptions = (yargs: CommonYargsArgv) =>
"Focus MCP schema on one or more comma-separated tool names, for example insert-fragment",
});
-type SchemaDetail = "overview" | "summary" | "full";
-
type SchemaOptions = Omit<
StrictYargsOptionsToInterface<typeof schemaOptions>,
- "topic" | "detail" | "tool"
+ "topic" | "tool" | "verbose" | "cursor" | "limit"
> & {
topic?: string;
- detail?: string;
tool?: string;
+ verbose?: boolean;
+ cursor?: string;
+ limit?: number;
};
const topLevelCommands = topLevelCliCommandMetadata.map(
@@ -124,23 +132,29 @@ const mcpToolSummary = mcpToolSchema.map(
serverOnly: annotations.serverOnly,
})
);
+const mcpToolSummaryByName = new Map(
+ mcpToolSummary.map((summary) => [summary.name, summary])
+);
-const getSchemaDetail = (
- detail: string | undefined,
- hasToolFilter = false
-): SchemaDetail => {
- if (
- detail === undefined ||
- detail === "overview" ||
- detail === "summary" ||
- detail === "full"
- ) {
- return detail ?? (hasToolFilter ? "full" : "overview");
- }
- throw new Error(
- `Unknown schema detail "${detail}". Available details: overview, summary, full`
- );
-};
+const paginateSchemas = <Item extends object, Compact extends object>(
+ items: readonly Item[],
+ options: Pick<SchemaOptions, "cursor" | "limit" | "verbose">,
+ compact: (item: Item) => Compact
+) =>
+ paginateOutput({
+ items: items.map((item) =>
+ projectOutput({
+ input: options,
+ compact: compact(item),
+ expanded: () => item,
+ })
+ ),
+ cursor: options.cursor,
+ limit: options.limit,
+ filters: {},
+ verbose: options.verbose,
+ invalidCursorMessage: "Invalid schema cursor",
+ });
const getSelectedMcpToolSchemas = (toolFilter: string | undefined) => {
if (toolFilter === undefined || toolFilter.trim() === "") {
@@ -165,56 +179,56 @@ const getSelectedMcpToolSchemas = (toolFilter: string | undefined) => {
return selectedTools;
};
-const getMcpSchemaTools = (
- detail: SchemaDetail,
- tools: typeof mcpToolSchema
-) => {
- if (detail === "full") {
- return tools;
- }
- if (detail === "summary") {
- const selectedToolNames = new Set(tools.map((tool) => tool.name));
- return mcpToolSummary.filter((tool) => selectedToolNames.has(tool.name));
- }
- return tools.map(({ name }) => name);
-};
-
const createMcpSchema = (
- detail: SchemaDetail,
+ options: Pick<SchemaOptions, "cursor" | "limit" | "verbose">,
selectedTools: typeof mcpToolSchema = mcpToolSchema
-) => ({
- name: "webstudio-mcp",
- version: 1,
- command: "webstudio mcp",
- singleOpCallCommand: "webstudio mcp single-op-call <tool> '<json>'",
- focusedToolNames:
- selectedTools.length === mcpToolSchema.length
- ? undefined
- : selectedTools.map(({ name }) => name),
- detail,
- usage:
- selectedTools.length !== mcpToolSchema.length
+) => {
+ const focused = selectedTools.length !== mcpToolSchema.length;
+ const detailOptions = {
+ ...options,
+ verbose: options.verbose ?? focused,
+ };
+ const { items, ...pagination } = paginateSchemas(
+ selectedTools,
+ detailOptions,
+ (tool) => {
+ const summary = mcpToolSummaryByName.get(tool.name);
+ if (summary === undefined) {
+ throw new Error(`Missing compact schema for MCP tool "${tool.name}".`);
+ }
+ return summary;
+ }
+ );
+ return {
+ name: "webstudio-mcp",
+ version: 1,
+ command: "webstudio mcp",
+ singleOpCallCommand: "webstudio mcp single-op-call <tool> '<json>'",
+ focusedToolNames: focused
+ ? selectedTools.map(({ name }) => name)
+ : undefined,
+ usage: focused
? "Focused MCP tool schema. Use this when you know the tool name and need exact input fields."
- : detail === "full"
- ? "Full MCP tool schema. This output is large; prefer summary detail plus focused meta.get_more_tools/components.* calls for normal LLM workflows."
- : detail === "summary"
- ? 'MCP tool summary. Use this to inspect all tool descriptions and fields without full schemas. For exact tool schemas use webstudio schema mcp --detail full, or prefer focused webstudio mcp single-op-call meta.get_more_tools \'{"tools":["insert-fragment"]}\'.'
- : "Tiny MCP overview. Use this first to discover tool names. For all descriptions use --detail summary; for exact schemas use --detail full or --tool <name>; for normal LLM workflows prefer focused meta.get_more_tools and components.* calls.",
- discovery: [
- "webstudio mcp single-op-call meta.index",
- `webstudio mcp single-op-call meta.guide '{"brief":"Create a design system page using every component"}'`,
- `webstudio mcp single-op-call meta.get_more_tools '{"tools":["insert-fragment"]}'`,
- `webstudio mcp single-op-call components.list '{"source":"all"}'`,
- "webstudio mcp single-op-call components.coverage-plan",
- `webstudio mcp single-op-call components.search '{"brief":"radix select"}'`,
- `webstudio mcp single-op-call components.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}'`,
- "webstudio mcp single-op-call templates.list",
- `webstudio mcp single-op-call templates.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}'`,
- ],
- resources: listProjectSessionMcpResources(),
- toolCount: selectedTools.length,
- tools: getMcpSchemaTools(detail, selectedTools),
-});
+ : detailOptions.verbose
+ ? "Full MCP tool schema. This output is large; prefer compact output plus focused meta.get_more_tools/components.* calls for normal LLM workflows."
+ : "Compact MCP tool summary. Use --verbose only when complete input and output schemas are needed.",
+ discovery: [
+ "webstudio mcp single-op-call meta.index",
+ `webstudio mcp single-op-call meta.guide '{"brief":"Create a design system page using every component"}'`,
+ `webstudio mcp single-op-call meta.get_more_tools '{"tools":["insert-fragment"]}'`,
+ `webstudio mcp single-op-call components.list '{"source":"all"}'`,
+ "webstudio mcp single-op-call components.coverage-plan",
+ `webstudio mcp single-op-call components.search '{"brief":"radix select"}'`,
+ `webstudio mcp single-op-call components.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}'`,
+ "webstudio mcp single-op-call templates.list",
+ `webstudio mcp single-op-call templates.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}'`,
+ ],
+ resources: listProjectSessionMcpResources(),
+ toolCount: selectedTools.length,
+ tools: items,
+ ...pagination,
+ };
+};
const apiSchema = {
name: "webstudio-cli",
@@ -286,24 +300,60 @@ const apiSchema = {
export const schema = (options: SchemaOptions) => {
try {
+ if (
+ options.limit !== undefined &&
+ (Number.isInteger(options.limit) === false ||
+ options.limit < 1 ||
+ options.limit > 200)
+ ) {
+ throw new Error("--limit must be an integer from 1 to 200.");
+ }
const topic = options.topic ?? "api";
if (topic === "api") {
- printJson(apiSchema);
+ const { items, ...pagination } = paginateSchemas(
+ cliCommands,
+ options,
+ ({ name, operation, summary, requiredOptions }) => ({
+ name,
+ operation,
+ summary,
+ requiredOptions,
+ })
+ );
+ const pageCommandNames = new Set(items.map(({ name }) => name));
+ printJson(
+ projectOutput({
+ input: options,
+ compact: {
+ name: apiSchema.name,
+ version: apiSchema.version,
+ topLevelCommands,
+ commands: items,
+ ...pagination,
+ },
+ expanded: () => ({
+ ...apiSchema,
+ commands: items,
+ commandGroups: commandGroups.map((group) => ({
+ ...group,
+ commands: group.commands.filter(({ name }) =>
+ pageCommandNames.has(name)
+ ),
+ })),
+ ...pagination,
+ }),
+ })
+ );
return;
}
if (topic === "mcp") {
const selectedTools = getSelectedMcpToolSchemas(options.tool);
- printJson(
- createMcpSchema(
- getSchemaDetail(options.detail, selectedTools !== undefined),
- selectedTools
- )
- );
+ printJson(createMcpSchema(options, selectedTools));
return;
}
const focusedTool = getSelectedMcpToolSchemas(topic);
if (focusedTool !== undefined) {
- printJson(createMcpSchema("full", focusedTool));
+ printJson(createMcpSchema(options, focusedTool));
return;
}
if (availableSchemaTopics.includes(topic as never) === false) {
diff --git a/packages/cli/src/commands/screenshot.ts b/packages/cli/src/commands/screenshot.ts
index 7f866d81a3..59a04648f1 100644
--- a/packages/cli/src/commands/screenshot.ts
+++ b/packages/cli/src/commands/screenshot.ts
@@ -8,7 +8,7 @@ import {
screenshotWaitUntilValues,
type ScreenshotBrowser,
type ScreenshotWaitUntil,
-} from "@webstudio-is/project-build/visual/screenshot-browser";
+} from "@webstudio-is/project-build/visual";
import { printJson } from "../json-output";
import { HandledCliError } from "../errors";
import {
diff --git a/packages/cli/src/docs.generated.ts b/packages/cli/src/docs.generated.ts
index 4945b1a407..cf845fa928 100644
--- a/packages/cli/src/docs.generated.ts
+++ b/packages/cli/src/docs.generated.ts
@@ -2,11 +2,11 @@
// Edit markdown files in src/docs instead.
export const cliDocs = {
"api-use-cases":
- '# CLI API Use Cases\n\n## Link/configure one project\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n\nNotes:\n\n- Writes local project id and global origin/token config.\n\n## Import synced project bundle into another project\n\nCommands:\n\n- webstudio sync\n- webstudio import --to <destination-share-link>\n- MCP tool: import {"to":"<destination-share-link>"}\n\nNotes:\n\n- Imports local `.webstudio/data.json` into the destination project.\n- Destination share link must allow build/import access.\n- Use `--skip-assets` only when asset rows and files should not be imported.\n\n## Identify current token\n\nCommands:\n\n- MCP tool: whoami {}\n\n## Check token permissions\n\nCommands:\n\n- webstudio permissions --json\n\n## Inspect project/build/version\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["pages","instances","styles"]}\n\n## Discover CLI/API capabilities\n\nCommands:\n\n- webstudio schema api\n- webstudio schema mcp\n- webstudio man --json\n- webstudio man llm --json\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"Create a pricing page"}\n- MCP tool: meta.get_more_tools {"brief":"update-styles"}\n- webstudio mcp list-resources\n- webstudio mcp read-resource webstudio://project/guide\n- webstudio mcp read-resource webstudio://project/expressions\n\nNotes:\n\n- Use `webstudio schema mcp` for a tiny machine-readable MCP tool overview. Use `webstudio schema mcp --detail summary` for all tool descriptions, and `webstudio schema mcp --detail full` or focused `meta.get_more_tools` calls only when exact input schemas are needed.\n- Use focused MCP tools for discovery first: `meta.index`, `meta.guide`, `meta.get_more_tools`, `components.list`, `components.summary`, `components.search`, `components.get`, `templates.list`, and `templates.get`. Protocol clients can use `resources/list` and `resources/read`; shell agents can use `webstudio mcp list-resources` and `webstudio mcp read-resource <uri>`. Read longer resources such as `webstudio://project/tools` and `webstudio://project/components` only when focused tools are insufficient.\n- Read `webstudio://project/expressions` before authoring unfamiliar computed text, prop bindings, resource expressions, actions, or Collection item bindings.\n- From a shell, call one MCP tool with the shortcut form `webstudio <tool> \'<json>\'`, for example `webstudio components.summary`. The explicit equivalent is `webstudio mcp single-op-call <tool> \'<json>\'`. Use `--input-file` for large payloads.\n\n## Inspect external shadcn registry items\n\nCommands:\n\n- webstudio registry inspect --source https://example.com/r/registry.json --item button --json\n- webstudio registry inspect --source ./registry.json --item dialog --json\n- webstudio registry inspect --source https://example.com/r/button.json --json\n\nNotes:\n\n- Reads a local or remote registry item without installing files or changing the configured Webstudio project.\n- Returns the item name, description, package and registry dependencies, file paths/targets, available docs, and a read-only compatibility report.\n- The report explicitly says whether installation or editable-component conversion is supported, lists declared requirements and manual steps, and says when arbitrary source code was not analyzed.\n- This is an inspection step only. It does not install files or change the configured project.\n\n## Understand what MCP can do\n\nCommands:\n\n- webstudio man mcp\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"What can Webstudio MCP do?"}\n\nMCP lets agents work on one configured Webstudio project. Agents can:\n\n- Inspect the linked project, token permissions, and latest editable build.\n- Read selected project data for audits, migrations, and repair.\n- Search labels, text, props, resource URLs, asset metadata, and styles.\n- Audit accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, and unused or duplicate style data.\n- Create and edit pages, folders, redirects, breakpoints, and page templates.\n- Create pages from reusable templates.\n- Update page metadata, SEO fields, auth settings, and marketplace metadata.\n- Insert components and styled JSX sections.\n- Create data-driven lists, grids, cards, and similar repeated UI from array or object data in one Collection operation.\n- Move, copy, wrap, unwrap, convert, rename, retag, and delete elements.\n- Update text, rich text, props, bindings, and actions.\n- Create and update local styles, design tokens, style sources, and CSS variables.\n- Create static data variables and JSON variables.\n- Create HTTP, GraphQL, and system resources.\n- Use system resources for sitemap, current date, and assets.\n- Bind resources to rendered data or form/action props.\n- Upload, replace, delete, and inspect asset usage.\n- Publish, unpublish, inspect publish jobs, and manage custom domains.\n- Start preview, capture screenshots, compare screenshot diffs, and use OCR when installed.\n\n## Inspect and refresh MCP session cache\n\nCommands:\n\n- MCP tool: status {}\n- MCP tool: status {"verbose":true}\n- MCP tool: refresh {"namespaces":["pages","instances","styles"]}\n- MCP tool: reset-session {}\n\nNotes:\n\n- Use status before a task to understand the cached ProjectSession state.\n- Use status with `{"verbose":true}` only when debugging full namespaces, freshness, compatibility, or diagnostics.\n- Use refresh when project data may have changed outside the current MCP session.\n- Use reset-session when local cached state is corrupt or incompatible.\n\n## Visually verify rendered work with AI vision\n\nCommands:\n\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: preview.status {}\n- MCP tool: preview.stop {}\n- MCP tool: screenshot {"path":"/","output":".webstudio/screenshots/home-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff"}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedText":["Pricing","Start free"]}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedVisual":{"maxMismatchPercentage":2,"maxChangedRegions":3,"dominantColorChange":{"channel":"luminance","direction":"increase","minMagnitude":10}}}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/pricing-before.png","currentPath":".webstudio/screenshots/pricing-current.png","outputDir":".webstudio/screenshots/diff"}\n- MCP tool: vision.install-ocr {"confirm":true}\n\nNotes:\n\n- Use this after page/content/style mutations and after generated project files are current so a vision-capable AI can see the production-like generated site.\n- For multi-page work, capture every changed page by `path` through the same preview server; no click navigation is required.\n- After MCP mutations, path screenshots regenerate/restart preview as needed before capture; when preview is fresh, repeated path screenshots reuse the running server.\n- Do not call `preview.start` through one-shot `webstudio mcp single-op-call`: it is long-lived. From a shell, use `webstudio mcp run` with preview.start, screenshot, and preview.stop in one shared process, or use a real long-running MCP client.\n- From one-shot shell calls or another process, pass `baseUrl` with `path` to capture an already-running preview/site without generating, building, starting, or restarting preview.\n- Use preview.stop only in the same long-running MCP server or `webstudio mcp run` process that started preview. A separate one-shot `single-op-call` process does not own another process\'s preview controller.\n- Use waitForSelector when the rendered app has a reliable ready marker, waitUntil:"networkidle" for network-heavy pages, and waitForTimeout only for final visual settling.\n- Preview installs generated app dependencies under `.webstudio/preview` and reuses them across regenerations.\n- Do not add generated-preview dependencies to the repository root `package.json` or `pnpm-lock.yaml`.\n- If dependency installation fails, check npm and network configuration, then reinstall or update the Webstudio CLI if the problem persists.\n- When a baseline exists, use screenshot.diff once per baseline/current page or viewport pair to get changed regions, OCR textAnalysis, and diff artifact paths before deciding whether the result matches. Pass expectedText for explicit pass/fail current-screen text assertions with found and missing text. Pass expectedVisual for pass/fail limits on pixel mismatch percentage, changed-region count, or the overall dominant color/brightness direction.\n- If screenshot.diff reports OCR unavailable and the user agrees to install it, call vision.install-ocr {"confirm":true}; otherwise continue with pixel diff and visual inspection.\n- Compare the PNG, OCR text evidence, and diff artifacts against the user\'s intent for layout, typography, colors, spacing, imagery, and responsive framing; then iterate with focused mutations.\n- Root CLI equivalent: `webstudio screenshot --path /pricing --output pricing.png` generates a temporary production preview, captures that route, and stops the server. For repeated captures, keep `webstudio preview` running and pass its absolute URL to `webstudio screenshot`.\n\n## List pages\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n\n## Read page by id\n\nCommands:\n\n- MCP tool: get-page {"pageId":"<pageId>"}\n\n## Read page by path\n\nCommands:\n\n- MCP tool: get-page-by-path {"path":"/pricing"}\n\n## Create page\n\nCommands:\n\n- MCP tool: create-page {"name":"Pricing","path":"/pricing"}\n- MCP tool: create-page {"name":"Pricing","path":"/pricing","title":"Pricing","meta":{"description":"Plans for teams"}}\n\nNotes:\n\n- `name`, `path`, page `title`, and metadata text fields accept plain fixed values.\n- For computed page titles or metadata, send JavaScript expression code such as `pageTitle ?? "Pricing"`.\n\n## Update page settings/metadata\n\nCommands:\n\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans","status":"200"}}}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n\nNotes:\n\n- Page `title` and metadata text fields accept plain fixed values.\n- For computed page titles or metadata, send JavaScript expression code such as `pageTitle ?? "Pricing"`.\n\n## Read project settings\n\nCommands:\n\n- MCP tool: get-project-settings {}\n\nNotes:\n\n- Read `meta.agentInstructions` before making project changes. It contains the project\'s own guidance for AI agents.\n- Agent instructions are shared project guidance. Do not store credentials or other secrets there.\n\n## Update project settings\n\nCommands:\n\n- MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}\n- MCP tool: update-project-settings {"meta":{"agentInstructions":"Use existing design tokens and keep product copy concise."}}\n\n## Read marketplace product\n\nCommands:\n\n- MCP tool: get-marketplace-product {}\n\n## Update marketplace product\n\nCommands:\n\n- MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"asset-id","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}\n\n## List redirects\n\nCommands:\n\n- MCP tool: list-redirects {}\n\n## Create redirect\n\nCommands:\n\n- MCP tool: create-redirect {"old":"/old","new":"/new","status":301}\n\n## Update redirect\n\nCommands:\n\n- MCP tool: update-redirect {"old":"/old","values":{"new":"/newer","status":302}}\n- MCP tool: update-redirect {"old":"/old","values":{"status":null}}\n\n## Delete redirect\n\nCommands:\n\n- MCP tool: delete-redirect {"old":"/old"}\n\n## Set redirects\n\nCommands:\n\n- MCP tool: set-redirects {"redirects":[{"old":"/old","new":"/new","status":"301"}]}\n\n## List breakpoints\n\nCommands:\n\n- MCP tool: list-breakpoints {}\n\n## Create breakpoint\n\nCommands:\n\n- MCP tool: create-breakpoint {"label":"Tablet","maxWidth":991}\n\n## Update breakpoint\n\nCommands:\n\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"label":"Tablet","maxWidth":1023}}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"condition":null,"minWidth":768}}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"minWidth":null,"maxWidth":null,"condition":"(hover: hover)"}}\n\n## Delete breakpoint\n\nCommands:\n\n- MCP tool: delete-breakpoint {"breakpointId":"tablet"}\n\n## Duplicate page\n\nCommands:\n\n- MCP tool: duplicate-page {"pageId":"<pageId>","name":"Pricing Copy","path":"/pricing-copy"}\n\n## List page templates\n\nCommands:\n\n- MCP tool: list-page-templates {}\n\n## Create page template\n\nCommands:\n\n- MCP tool: create-page-template {"name":"Landing Template","title":"Landing"}\n\n## Update page template\n\nCommands:\n\n- MCP tool: update-page-template {"templateId":"<templateId>","values":{"name":"Article Template","meta":{"description":"Reusable article layout"}}}\n\n## Delete page template\n\nCommands:\n\n- MCP tool: delete-page-template {"templateId":"<templateId>"}\n\n## Duplicate page template\n\nCommands:\n\n- MCP tool: duplicate-page-template {"templateId":"<templateId>"}\n\n## Reorder page template\n\nCommands:\n\n- MCP tool: reorder-page-template {"sourceTemplateId":"<sourceTemplateId>","targetTemplateId":"<targetTemplateId>","position":"before"}\n\n## Create page from template\n\nCommands:\n\n- MCP tool: create-page-from-template {"templateId":"<templateId>","name":"Landing","path":"/landing"}\n\n## Delete page\n\nCommands:\n\n- MCP tool: delete-page {"pageId":"<pageId>"}\n\n## List folders\n\nCommands:\n\n- MCP tool: list-folders {"includePages":true}\n\n## Create folder\n\nCommands:\n\n- MCP tool: create-folder {"name":"Blog","slug":"blog"}\n\n## Update folder\n\nCommands:\n\n- MCP tool: update-folder {"folderId":"<folderId>","values":{"name":"Blog","slug":"blog"}}\n\n## Delete folder\n\nCommands:\n\n- MCP tool: delete-folder {"folderId":"<folderId>"}\n\n## List element instances\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":3}\n\n## Inspect one element instance\n\nCommands:\n\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n\n## Insert authored JSX or one component template\n\nCommands:\n\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px;`}><ws.element ws:tag=\\"h2\\">Product OS</ws.element><radix.Switch><radix.SwitchThumb /></radix.Switch></ws.element>"}\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"@webstudio-is/sdk-components-react-radix:Switch"}\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"Form"}\n\nNotes:\n\n- Use MCP `insert-fragment` as the default way to author styled component trees. It converts JSX to a structured fragment before mutation.\n- Use only exact component ids returned by `components.search`, `components.get`, or `templates.get`. Never derive or guess component ids.\n- The `ws:` namespace contains specific Webstudio core components; it is not HTML-tag shorthand. Use `<ws.element ws:tag="div">` for a native `div` and `<ws.element ws:tag="form">` for a native form, never `<ws.div>` or `<ws.form>`.\n- For Webstudio\'s complete form structure, discover the Form component and insert its automatic template with `insert-component` using component `"Form"`.\n- MCP receives JSX as a JSON string because MCP arguments are JSON. The CLI converts it locally before the runtime mutation, so the project session receives structured Webstudio data, not JSX source.\n- In `insert-fragment` JSX, use `ws:style={css\\`...\\`}`for Webstudio-native CSS, or use React-style object syntax such as`style={{ padding: 24 }}` when that is simpler. Both forms create editable Webstudio style data.\n- Do not access host globals or dynamic code APIs in JSX fragments, including `process`, `globalThis`, `eval`, `Function`, or `constructor`.\n- Use Webstudio prop names such as `class` and `for`; do not use React aliases `className` or `htmlFor`.\n- Use Webstudio actions for event/action props, for example `onClick={new ActionValue(["event"], expression\\`console.log(event)\\`)}`. Do not pass JavaScript functions such as `onClick={() => ...}`.\n- Plain prop values must be JSON-compatible: `null`, strings, booleans, finite numbers, arrays, and plain objects. Do not pass `undefined`, `Symbol`, `BigInt`, `NaN`, `Infinity`, `Date`, `Map`, `Set`, class instances, or circular objects; omit the prop, use plain data, or use `expression`/`ActionValue` when the value is dynamic.\n- Template-backed components used in JSX must include required child/part components explicitly under the same parent structure as the template, for example `<radix.Switch><radix.SwitchThumb /></radix.Switch>`.\n- Webstudio applies a registered template automatically when using `insert-component`, so composed components such as Switch include required child parts and styles.\n- Use `components.list`, `components.summary`, `components.search`, `components.get`, `templates.list`, and `templates.get` to discover known registry items, component ids, props, templates, insertability, and content model. Read `webstudio://project/components` only when those focused tools are insufficient.\n- Component/template registry items use a shadcn-compatible top-level shape plus Webstudio-specific superset metadata in `meta`. They are for Builder/MCP discovery, not a published shadcn install registry yet.\n- Known components with `contentModel.category: "none"` are not standalone-insertable; insert their root component template instead so required providers/parents are included.\n- Unknown custom component ids are a low-level extension mechanism, not a discovery fallback. Agents must not synthesize them.\n\n## Make a region editable in Content mode\n\nCommands:\n\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"ws:block"}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["children"]}\n\nNotes:\n\n- When a page will be handed to a Content-mode editor, wrap every region they should be able to edit in a Content Block (`ws:block`). Content-mode editors can edit text and supported props only in Content Block descendants. Content outside those blocks remains read-only, even when it looks like ordinary editable text.\n- Put reusable insertable options inside the Content Block\'s `ws:block-template` child. A template is source material, not editor content: editors cannot edit or delete it directly. When an editor inserts a template, its copy becomes a direct child of the Content Block and is editable.\n- Before handing off a page, verify with `inspect-instance` that the intended text, images, and links are inside a Content Block, and that templates include all required styling because Content-mode editors cannot use the Style panel.\n\n## Move elements\n\nCommands:\n\n- MCP tool: move-instance {"moves":"moves.json contents"}\n\nNotes:\n\n- Use `position: "end"` to append an instance. Repeating this for A and then B preserves the final order A, B.\n- A numeric `insertIndex` addresses the target parent\'s children before the moved instance is removed. Use it for exact placement; do not calculate the last index to append.\n- Moves in one `moves` array are applied sequentially in array order.\n\n## Clone element subtree\n\nCommands:\n\n- MCP tool: clone-instance {"sourceInstanceId":"<instanceId>","targetParentInstanceId":"<targetParentId>"}\n\n## Delete element subtree\n\nCommands:\n\n- MCP tool: delete-instance {"instanceIds":["<instanceId>"]}\n\n## List text/expression children\n\nCommands:\n\n- MCP tool: list-texts {"pagePath":"/"}\n\n## Update text child\n\nCommands:\n\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n\n## Replace bounded literal text\n\nCommands:\n\n- MCP tool: replace-text {"find":"Start free","replace":"Get started","match":"exact","pagePath":"/pricing","limit":20}\n\nNotes:\n\n- This changes only literal text children, never expression children. Scope it to pagePath or pageId and set a limit before a broad replacement.\n\n## Replace bounded static prop text\n\nCommands:\n\n- MCP tool: replace-prop-text {"find":"old.example.com","replace":"www.example.com","match":"substring","names":["href","code"],"limit":20}\n\nNotes:\n\n- This changes only static string props such as href, alt, aria-label, title, and HTML embed code. It never changes expressions, resources, actions, assets, or other dynamic bindings. Use names or instanceIds and a limit to narrow the change.\n\n## Replace bounded resource text\n\nCommands:\n\n- MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}\n\nNotes:\n\n- This changes resource names and fixed URL literals only. It skips dynamic URL expressions, headers, search parameters, request bodies, and GraphQL query code.\n\n## Update props\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: replace-prop-text {"find":"Old label","replace":"New label","names":["aria-label","title"],"limit":20}\n\nNotes:\n\n- Use this for fixed prop values such as `aria-label`, `alt`, `id`, static `href`, and other direct string/number/boolean/json prop values.\n\n## Add JSON-LD structured data\n\nCommands:\n\n- MCP tool: components.get {"component":"JsonLd"}\n- MCP tool: insert-component {"parentInstanceId":"<headSlotInstanceId>","component":"JsonLd"}\n- MCP tool: update-props {"updates":[{"instanceId":"<jsonLdInstanceId>","name":"code","type":"string","value":"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Organization\\",\\"name\\":\\"Acme\\"}"}]}\n- MCP tool: audit {"scopes":["seo"],"pagePath":"/"}\n\nNotes:\n\n- Prefer placing `JsonLd` inside `HeadSlot`.\n- Store `code` as a JSON object or array encoded as a compact string. The Builder formats it for editing.\n- The semantic prop update rejects malformed JSON and structurally invalid fixed JSON-LD with a precise JSON path.\n- The SEO audit also warns about a missing top-level `@context`, unknown or superseded Schema.org terms, properties unsupported by the supplied type, and incompatible primitive value types.\n- Schema.org vocabulary findings are warnings because custom vocabularies and extensions remain valid. Dynamic JSON-LD is marked as skipped for rendered validation.\n- Do not use bindings just to set static text.\n\n## Delete props\n\nCommands:\n\n- MCP tool: delete-props {"deletions":"props.json contents"}\n\n## Bind props to expressions/resources/actions\n\nCommands:\n\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Use this only when the prop should remain dynamic: expression, resource, action, or an existing scoped runtime context value such as `system`.\n- For a fixed string value, use `update-props` with `type:"string"` and a direct `value` instead.\n\n## Read styles\n\nCommands:\n\n- MCP tool: get-styles {"instanceIds":["<instanceId>"],"includeTokens":true}\n\n## Update local styles\n\nCommands:\n\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\n## Delete local styles\n\nCommands:\n\n- MCP tool: delete-styles {"deletions":"styles.json contents"}\n\n## Replace matching style values\n\nCommands:\n\n- MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}\n\n## List design tokens\n\nCommands:\n\n- MCP tool: list-design-tokens {}\n- MCP tool: list-design-tokens {"withUsage":true}\n- MCP tool: list-design-tokens {"includeStyles":true}\n\nNotes:\n\n- The default response is compact and includes token id, name, declaration count, and optional usage count.\n- Use `includeStyles:true` only when you need the full inline style declarations.\n\n## Create design tokens\n\nCommands:\n\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n\n## Update design token styles\n\nCommands:\n\n- MCP tool: update-design-token-styles {"designTokenId":"<tokenId>","updates":"styles.json contents"}\n\n## Delete design token styles\n\nCommands:\n\n- MCP tool: delete-design-token-styles {"designTokenId":"<tokenId>","deletions":"styles.json contents"}\n\n## Attach design token to instances\n\nCommands:\n\n- MCP tool: attach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Detach design token from instances\n\nCommands:\n\n- MCP tool: detach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Extract design token from local styles\n\nCommands:\n\n- MCP tool: extract-design-token {"instanceIds":["<instanceId>"],"name":"Brand Primary","removeLocalProps":["color"]}\n\n## List CSS variables\n\nCommands:\n\n- MCP tool: list-css-variables {"withUsage":true}\n\n## Define CSS variables\n\nCommands:\n\n- MCP tool: define-css-variable {"vars":"vars.json contents"}\n\n## Delete CSS variables\n\nCommands:\n\n- MCP tool: delete-css-variable {"names":"names.json contents","force":true}\n\n## Rewrite CSS variable references\n\nCommands:\n\n- MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}\n\n## List data variables\n\nCommands:\n\n- MCP tool: list-variables {}\n- MCP tool: list-variables {"scopeInstanceId":"<instanceId>"}\n\nNotes:\n\n- Data variables live in the internal `dataSources` namespace.\n- For raw `snapshot`, request the public `variables` namespace rather than the internal `dataSources` name. Raw patch payloads still use `dataSources` when applying direct changes.\n- Scope variables to the instance where they should become available. Descendants can use them in expressions, and nested variables with the same name mask outer variables.\n\n## Create data variable\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"count","value":{"type":"number","value":3}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"featured","value":{"type":"boolean","value":true}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"tags","value":{"type":"string[]","value":["news","product"]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"filters","value":{"type":"json","value":{"tag":"news"}}}\n\nNotes:\n\n- Data variable values support `string`, `number`, `boolean`, `string[]`, and `json`.\n- Parameters are internal scoped runtime values provided by pages, collections, or components. They are not a public authoring surface: do not create, update, or delete parameter records. Use data variables/resources for user-authored data, and reference documented context values such as `system` only where they are already in scope.\n\n## Update data variable\n\nCommands:\n\n- MCP tool: update-variable {"dataSourceId":"<variableId>","values":{"value":{"type":"json","value":{"count":1}}}}\n\n## Delete data variable\n\nCommands:\n\n- MCP tool: delete-variable {"dataSourceId":"<variableId>"}\n\n## List resources\n\nCommands:\n\n- MCP tool: list-resources {}\n- MCP tool: list-resources {"scopeInstanceId":"<instanceId>"}\n\n## Create resource\n\nCommands:\n\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"https://api.example.com/posts","headers":[]}}\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"\\"https://api.example.com/posts?tag=\\" + filters.tag","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Filtered Posts","method":"get","url":"https://api.example.com/posts","searchParams":[{"name":"tag","value":"filters.tag"},{"name":"source","value":{"type":"literal","value":"website"}}],"headers":[{"name":"Authorization","value":"\\"Bearer \\" + auth.token"}]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Post GraphQL","control":"graphql","method":"post","url":"https://api.example.com/graphql","headers":[{"name":"Content-Type","value":{"type":"literal","value":"application/json"}}],"body":"{ query: \\"query Post($slug: String!) { post(slug: $slug) { title } }\\", variables: { slug: system.params.slug } }"},"scopeInstanceId":"<instanceId>","dataSourceName":"post"}\n- MCP tool: create-resource {"resource":{"name":"Current Date","control":"system","method":"get","url":"/$resources/current-date","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"currentDate"}\n\nNotes:\n\n- Resource `url` accepts plain fixed URLs and paths such as `https://api.example.com/posts` and `/$resources/current-date`.\n- Resource `url` can also be a JavaScript expression when it is computed, such as `"https://api.example.com/posts?tag=" + filters.tag`.\n- Header values, search parameter values, and body accept expressions for dynamic values. For fixed text, use `{"type":"literal","value":"application/json"}`; Webstudio stores the required string expression for you.\n- Search parameter values, header values, and body expressions can read scoped variables and documented runtime context values such as `system` when they are available at the resource scope.\n- Add `scopeInstanceId` and `dataSourceName` when the resource result should be exposed as a scoped read data variable. Scoped resources are generated into the page resource `data` map and may be loaded during page rendering. Use this for read-oriented resources such as GET CMS/API data.\n- For submit/write/action resources, create the resource without `scopeInstanceId`, then bind a component prop such as a Form `action` with `bind-props` and `binding.type: "resource"`. Prop-bound resources are generated into the page resource `action` map instead of the read `data` map. Use this for POST, PUT, DELETE, webhooks, GraphQL submissions, and other explicit action flows.\n- Resource `method` can be `get`, `post`, `put`, or `delete`. Use GET for read data, POST for creates/GraphQL/webhooks/form submissions, PUT for full updates or replacements, and DELETE for deletion actions.\n- Optional `control` values are `graphql` and `system`. Use `graphql` for GraphQL-style requests, usually POST with a query body. Use `system` for built-in resources such as `"/$resources/sitemap.xml"`, `"/$resources/current-date"`, and `"/$resources/assets"` and when the resource should use the built-in `system` parameter. System fields are `system.origin`, `system.pathname`, `system.params`, and `system.search`.\n\n## Update resource\n\nCommands:\n\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}\n\n## Delete resource\n\nCommands:\n\n- MCP tool: delete-resource {"resourceId":"<resourceId>"}\n\n## List assets\n\nCommands:\n\n- MCP tool: list-assets {"withUsage":true}\n\nNotes:\n\n- Image asset descriptions are the default alt text for asset-backed Image components.\n- To generate missing descriptions, inspect the image in its rendered page or asset source, write a concise description of its purpose, and save it on the asset rather than duplicating it on each Image instance.\n\n## Update asset metadata\n\nCommands:\n\n- MCP tool: update-asset {"assetId":"<assetId>","values":{"description":"Team collaborating around a whiteboard"}}\n\nNotes:\n\n- Use an empty description only when the image is intentionally decorative.\n- Updating an image asset description updates the default alt text wherever that asset is used with an asset-backed alt prop.\n\n## Generate missing image descriptions with an agent\n\nCommands:\n\n- MCP tool: audit {"scopes":["accessibility"],"verbose":true}\n- MCP tool: set-image-descriptions {"updates":[{"assetId":"hero-id","description":"Team collaborating around a whiteboard"},{"assetId":"texture-id","decorative":true}]}\n- MCP tool: audit {"scopes":["accessibility"]}\n\nNotes:\n\n- Start from `missing-image-description` findings. Inspect each image in its rendered page context before writing text.\n- The vision-capable agent generates the wording; the CLI validates and stores it but does not contain its own vision model.\n- Use `decorative:true` only when the image adds no information. This intentionally stores an empty description so later audits do not report it as missing.\n- Re-run the accessibility audit after the update. Asset-backed Image components use the saved asset description as their default alt text.\n\n## Manage fonts\n\nCommands:\n\n- MCP tool: list-fonts {"includeSystem":true}\n- MCP tool: list-assets {"type":"font"}\n- MCP tool: upload-asset {"asset":{"name":"acme-sans.woff2","type":"font","format":"woff2","meta":{"family":"Acme Sans","style":"normal","weight":400}},"assetsDir":".webstudio/assets"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\nNotes:\n\n- Use `list-fonts` to discover uploaded families and system stacks. Upload/delete fonts through the existing asset tools, then apply a family with a `font-family` style declaration.\n\n## Upload one asset\n\nCommands:\n\n- MCP tool: upload-asset {"asset":{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}},"assetsDir":".webstudio/assets"}\n\n## Upload asset batch\n\nCommands:\n\n- MCP tool: upload-assets {"assets":[{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}}],"assetsDir":".webstudio/assets"}\n\n## Find asset usage\n\nCommands:\n\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n\n## Replace asset references\n\nCommands:\n\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>"}\n\n## Delete assets\n\nCommands:\n\n- MCP tool: delete-asset {"assetIdsOrPrefixes":["<assetId>"],"force":true}\n\n## Publish project\n\nCommands:\n\n- webstudio publish deploy --target production --json\n\n## List publishes\n\nCommands:\n\n- webstudio publish list --json\n\n## Check publish job\n\nCommands:\n\n- webstudio publish status --job <buildId> --json\n\n## Unpublish\n\nCommands:\n\n- webstudio publish unpublish --target production --confirm --json\n\n## List domains\n\nCommands:\n\n- webstudio domains list --json\n\n## Create domain\n\nCommands:\n\n- webstudio domains create --domain example.com --json\n\n## Update domain\n\nCommands:\n\n- webstudio domains update --domain-id <domainId> --domain www.example.com --json\n\n## Delete domain\n\nCommands:\n\n- webstudio domains delete --domain-id <domainId> --confirm --json\n\n## Verify domain\n\nCommands:\n\n- webstudio domains verify --domain-id <domainId> --json\n\n## Make arbitrary store-level changes\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["<namespace>"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use only when no semantic command exists.\n\n## Manage marketplace metadata\n\nCommands:\n\n- MCP tool: get-marketplace-product {}\n- MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"asset-id","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}\n\nPatch namespaces:\n\n- marketplaceProduct\n\n## Search and inspect safely\n\nCommands:\n\n- MCP tool: search-project {"query":"pricing"}\n- MCP tool: search-project {"query":"api.example.com","scopes":["resources"]}\n- MCP tool: list-instances {"pagePath":"/","maxDepth":5}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: list-assets {"withUsage":true}\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n- MCP tool: snapshot {"include":["pages","instances","props","resources","assets"]}\n\nNotes:\n\n- Use `search-project` for query-driven lookup across labels, text, prop values, resource URLs, asset metadata, and styles. Use `audit` for project health findings.\n\n## Audit project quality\n\nCommands:\n\n- webstudio audit --json\n- webstudio audit --scopes accessibility --scopes seo --json\n- webstudio audit --page-path /pricing --json\n- webstudio audit --scopes accessibility --verbose --json\n- webstudio audit --rendered --page-path /pricing --json\n- webstudio audit --rendered --route-example post=/blog/hello --json\n- webstudio audit --rendered --image-domain images.example.com --json\n- MCP tool: audit {}\n- MCP tool: audit {"scopes":["accessibility","security"],"severities":["error","warning"]}\n- MCP tool: audit {"scopes":["accessibility"],"verbose":true}\n- MCP tool: audit {"rendered":true,"verbose":true}\n\nNotes:\n\n- With no scopes, `audit` checks accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, non-GET resources exposed as render-time data, and unused or duplicate style data.\n- The `performance` scope reports disabled atomic CSS generation. A rendered audit also measures broken, eager below-fold, and oversized images, browser-marked render-blocking resources, and legacy font formats.\n- Rendered image and resource metrics run only when the selected scopes include `performance`; responsive layout dimensions remain available whenever `rendered:true` is requested.\n- Compact findings include stable ids, severity, message, and location. Use `--verbose` or `{"verbose":true}` for evidence, explanation, suggested remediation, skipped-check details, and manual-check workflows.\n- `summary` counts all findings before severity filtering and pagination.\n- `contractVersion` identifies the audit response contract. Handle a new value before assuming existing fields retain the same meaning.\n- Expression-, resource-, and parameter-backed values that cannot be checked reliably appear in `skippedChecks`; they are not treated as passing or failing.\n- Page filters apply to page-owned accessibility, security, and SEO checks. Asset and style usage remain project-wide to avoid false unused findings.\n- Continue paginated results with `cursor`. Restart the audit if the project version changes.\n- Verbose skipped-check and manual-check details are included on the first findings page only; their total counts remain available on every page.\n- `manualChecks` describes responsive, hierarchy, and contrast checks that require preview screenshots and vision.\n- Focused audits return only manual checks relevant to their selected scopes.\n- In a long-lived MCP session, `{"rendered":true}` reuses preview and screenshot\n tools to capture every static page at mobile, desktop, and Builder breakpoint\n edges. Compact output reports rendered check/issue/failure counts; verbose\n output includes screenshot paths and measured layout dimensions.\n- Dynamic route templates are skipped unless `--route-example <pageId>=<path>`\n (or MCP `routeExamples`) supplies a concrete path. The path must not contain\n unresolved `:` or `*` parameters.\n- Plans above 120 captures return a short-lived confirmation token. Review the\n unchanged plan, then rerun with `--confirm-large-run` and\n `--confirmation-token`.\n- Detailed rendered evidence is stored in a versioned manifest under\n `.webstudio/audits`; compact output includes its path and screenshot count.\n- Rendered checks also report broken images, eager images below the fold, and\n image sources more than 2x their rendered dimensions in both axes, including\n Webstudio instance ids and measured dimensions when available.\n- Rendered checks include sanitized Resource Timing evidence and report\n browser-marked render-blocking resources plus legacy `.ttf`, `.otf`, and\n `.woff` fonts without applying a universal transfer-size threshold.\n- Fix findings through semantic mutation commands, then rerun `audit` to confirm their deterministic finding ids disappeared.\n\n## Refactor targeted content\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/"}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n- MCP tool: replace-text {"find":"Old headline","replace":"New headline","match":"exact","pagePath":"/pricing","limit":20}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans"}}}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>"}\n- MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}\n- MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}\n\nNotes:\n\n- Use focused reads first, then mutate only matching instances, props, metadata, resource URLs, assets, or style references. Use `replace-text` for bounded literal text changes, `replace-prop-text` for bounded static prop text, `replace-resource-text` for fixed resource names/URLs, and `update-text` for one known child or expressions.\n\n## Optimize existing project\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans"}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: list-breakpoints {}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"maxWidth":1023}}\n- MCP tool: get-styles {"instanceIds":["<instanceId>"],"includeTokens":true}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: attach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n- MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}\n\nNotes:\n\n- Use this for SEO metadata, accessibility labels, responsive behavior, token consistency, and project settings.\n\n## Connect external data\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"tags","value":{"type":"string[]","value":["news","product"]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"filters","value":{"type":"json","value":{"tag":"news"}}}\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"https://api.example.com/posts","searchParams":[{"name":"tag","value":"filters.tag"},{"name":"source","value":{"type":"literal","value":"website"}}],"headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Post GraphQL","control":"graphql","method":"post","url":"https://api.example.com/graphql","headers":[{"name":"Content-Type","value":{"type":"literal","value":"application/json"}}],"body":"{ query: \\"query Post($slug: String!) { post(slug: $slug) { title } }\\", variables: { slug: system.params.slug } }"},"scopeInstanceId":"<instanceId>","dataSourceName":"post"}\n- MCP tool: create-resource {"resource":{"name":"Current Date","control":"system","method":"get","url":"/$resources/current-date","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"currentDate"}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.collection>{/_ collection content _/}</ws.collection>"}\n\nNotes:\n\n- Use this for CMS sections, blog listings, Ghost/headless CMS pages, n8n-style integrations, and API URLs built from variables.\n- For read data, expose GET resources as scoped data variables with `scopeInstanceId`/`dataSourceName` and read the loaded result from the resource result wrapper, usually `.data`.\n- For writes, webhooks, GraphQL submissions, and deletes, prefer unscoped resources bound to Form `action` props so they become action resources instead of auto-loaded read resources.\n- Use direct props for fixed values and prop bindings only when a prop must read a data variable, resource, action, or documented runtime context value such as `system`.\n\n## Render an array or object as repeated content\n\nCommands:\n\n- MCP tool: insert-collection {"parentInstanceId":"<instanceId>","data":{"type":"expression","value":"posts.data.items"},"itemFragment":"<ws.element ws:tag=\\"article\\"><ws.element ws:tag=\\"h2\\">{expression`collectionItem.title`}</ws.element></ws.element>"}\n- MCP tool: inspect-instance {"instanceId":"<collectionId>","include":["props","bindings","children"]}\n\nNotes:\n\n- Use Collection whenever an array or object from a resource or data variable should render a list, grid, cards, table rows, options, tabs, or other repeated UI.\n- Pass `insert-collection` the complete array or object. Do not pass the resource response wrapper or one indexed item. External resource arrays are commonly nested under the scoped resource result\'s `data` field or deeper.\n- Pass one repeated-item Webstudio JSX root. The command creates the Collection, its private current-item/current-key parameters, the iterable binding, and descendant item bindings atomically.\n- Collection renders the item root once for every entry. Use `expression` values such as `collectionItem.title` in descendant text and props. Object iteration also exposes `collectionItemKey`.\n- Wrap multiple repeated sibling instances in one Element inside Collection.\n- For repeated Radix items such as accordion items, tabs, or menu options, bind a stable unique id or slug to every required `value` prop.\n- See the [Collection documentation](https://docs.webstudio.is/university/core-components/collection) for the equivalent Builder workflow.\n\n## Support dynamic runtime behavior\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: create-resource {"resource":{"name":"Seats","method":"get","url":"https://api.example.com/seats","headers":[]}}\n- MCP tool: snapshot {"include":["instances","props","resources"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use existing scripts/resources for behavior, then move presentational structure into editable Webstudio instances where possible.\n- There is no dedicated semantic command yet for converting script-generated UI into editable Webstudio structure.\n\n## Build authenticated pages\n\nCommands:\n\n- MCP tool: create-page {"name":"Account","path":"/account"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n- MCP tool: create-resource {"resource":{"name":"Session","method":"get","url":"https://api.example.com/session","headers":[]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"user","value":{"type":"json","value":{}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Basic auth is semantic today. Provider-specific Supabase/Firebase setup still requires manual resources, props, embeds, or patches.\n\n## Generate from design input\n\nCommands:\n\n- MCP tool: create-page {"name":"Landing","path":"/landing"}\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n- MCP tool: define-css-variable {"vars":"vars.json contents"}\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.element ws:tag=\\"section\\"><ws.element ws:tag=\\"p\\">Section copy</ws.element></ws.element>"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n\nNotes:\n\n- Use this after external design interpretation. There is no dedicated import command for Figma, screenshots, Inception output, or design.md yet.\n\n## Cross-project maintenance\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n- webstudio permissions --json\n- webstudio mcp\n\nNotes:\n\n- Public API and CLI intentionally operate on one configured project at a time. Use an external script to loop over projects.\n\n# Known CLI Gaps\n\n## Provider-specific authenticated pages\n\nMissing:\nCLI supports page basic auth and generic resources/props/embeds, but not guided Supabase/Firebase auth setup.\n\nCurrent fallback:\nCreate the page, resources, variables, props, and embeds manually with existing MCP semantic tools.\n\nSuggested commands:\n\n- setup-auth-page\n\n## Dynamic script/runtime integration helpers\n\nMissing:\nCLI can manipulate props/resources/embeds, but has no semantic workflow for converting script-generated UI into editable Webstudio structures.\n\nCurrent fallback:\nUse MCP props, resources, and raw patch where necessary.\n\nSuggested commands:\n\n- integrate-runtime-ui\n\n## Generate from design input\n\nMissing:\nNo command imports Figma, screenshots, Inception output, or design.md and turns it into pages/tokens/layout.\n\nCurrent fallback:\nUse external generation, then apply semantic CLI commands or apply-patch.\n\nSuggested commands:\n\n- generate-from-design\n\n## Built-in cross-project maintenance\n\nMissing:\nPublic API and CLI intentionally operate on one configured project at a time; there is no built-in multi-project discovery or loop runner.\n\nCurrent fallback:\nRun the CLI from an external script that reconfigures one project/session at a time.\n\nSuggested commands:\n\n- none\n',
+ '# CLI API Use Cases\n\n## Link/configure one project\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n\nNotes:\n\n- Writes local project id and global origin/token config.\n\n## Import synced project bundle into another project\n\nCommands:\n\n- webstudio sync\n- webstudio import --to <destination-share-link>\n- MCP tool: import {"to":"<destination-share-link>"}\n\nNotes:\n\n- Imports local `.webstudio/data.json` into the destination project.\n- Destination share link must allow build/import access.\n- Use `--skip-assets` only when asset rows and files should not be imported.\n\n## Identify current token\n\nCommands:\n\n- MCP tool: whoami {}\n\n## Check token permissions\n\nCommands:\n\n- webstudio permissions --json\n\n## Inspect project/build/version\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["pages","instances","styles"]}\n\n## Discover CLI/API capabilities\n\nCommands:\n\n- webstudio schema api\n- webstudio schema mcp\n- webstudio man --json\n- webstudio man llm --json\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"Create a pricing page"}\n- MCP tool: meta.get_more_tools {"brief":"update-styles"}\n- webstudio mcp list-resources\n- webstudio mcp read-resource webstudio://project/guide\n- webstudio mcp read-resource webstudio://project/expressions\n\nNotes:\n\n- Use `webstudio schema mcp` for a compact machine-readable MCP tool overview. Add `--verbose` or use focused `meta.get_more_tools` calls only when exact input schemas are needed.\n- Use focused MCP tools for discovery first: `meta.index`, `meta.guide`, `meta.get_more_tools`, `components.list`, `components.summary`, `components.search`, `components.get`, `templates.list`, and `templates.get`. Protocol clients can use `resources/list` and `resources/read`; shell agents can use `webstudio mcp list-resources` and `webstudio mcp read-resource <uri>`. Read longer resources such as `webstudio://project/tools` and `webstudio://project/components` only when focused tools are insufficient.\n- Read `webstudio://project/expressions` before authoring unfamiliar computed text, prop bindings, resource expressions, actions, or Collection item bindings.\n- From a shell, call one MCP tool with the shortcut form `webstudio <tool> \'<json>\'`, for example `webstudio components.summary`. The explicit equivalent is `webstudio mcp single-op-call <tool> \'<json>\'`. Use `--input-file` for large payloads.\n\n## Inspect external shadcn registry items\n\nCommands:\n\n- webstudio registry inspect --source https://example.com/r/registry.json --item button --json\n- webstudio registry inspect --source ./registry.json --item dialog --json\n- webstudio registry inspect --source https://example.com/r/button.json --json\n\nNotes:\n\n- Reads a local or remote registry item without installing files or changing the configured Webstudio project.\n- Returns the item name, description, package and registry dependencies, file paths/targets, available docs, and a read-only compatibility report.\n- The report explicitly says whether installation or editable-component conversion is supported, lists declared requirements and manual steps, and says when arbitrary source code was not analyzed.\n- This is an inspection step only. It does not install files or change the configured project.\n\n## Understand what MCP can do\n\nCommands:\n\n- webstudio man mcp\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"What can Webstudio MCP do?"}\n\nMCP lets agents work on one configured Webstudio project. Agents can:\n\n- Inspect the linked project, token permissions, and latest editable build.\n- Read selected project data for audits, migrations, and repair.\n- Search labels, text, props, resource URLs, asset metadata, and styles.\n- Audit accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, and unused or duplicate style data.\n- Create and edit pages, folders, redirects, breakpoints, and page templates.\n- Create pages from reusable templates.\n- Update page metadata, SEO fields, auth settings, and marketplace metadata.\n- Insert components and styled JSX sections.\n- Create data-driven lists, grids, cards, and similar repeated UI from array or object data in one Collection operation.\n- Move, copy, wrap, unwrap, convert, rename, retag, and delete elements.\n- Update text, rich text, props, bindings, and actions.\n- Create and update local styles, design tokens, style sources, and CSS variables.\n- Create static data variables and JSON variables.\n- Create HTTP, GraphQL, and system resources.\n- Use system resources for sitemap, current date, and assets.\n- Bind resources to rendered data or form/action props.\n- Upload, replace, delete, and inspect asset usage.\n- Publish, unpublish, inspect publish jobs, and manage custom domains.\n- Start preview, capture screenshots, compare screenshot diffs, and use OCR when installed.\n\n## Inspect and refresh MCP session cache\n\nCommands:\n\n- MCP tool: status {}\n- MCP tool: status {"verbose":true}\n- MCP tool: refresh {"namespaces":["pages","instances","styles"]}\n- MCP tool: reset-session {}\n\nNotes:\n\n- Use status before a task to understand the cached ProjectSession state.\n- Use status with `{"verbose":true}` only when debugging full namespaces, freshness, compatibility, or diagnostics.\n- Use refresh when project data may have changed outside the current MCP session.\n- Use reset-session when local cached state is corrupt or incompatible.\n\n## Visually verify rendered work with AI vision\n\nCommands:\n\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: preview.status {}\n- MCP tool: preview.stop {}\n- MCP tool: screenshot {"path":"/","output":".webstudio/screenshots/home-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff"}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedText":["Pricing","Start free"]}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedVisual":{"maxMismatchPercentage":2,"maxChangedRegions":3,"dominantColorChange":{"channel":"luminance","direction":"increase","minMagnitude":10}}}\n- MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/pricing-before.png","currentPath":".webstudio/screenshots/pricing-current.png","outputDir":".webstudio/screenshots/diff"}\n- MCP tool: vision.install-ocr {"confirm":true}\n\nNotes:\n\n- Use this after page/content/style mutations and after generated project files are current so a vision-capable AI can see the production-like generated site.\n- For multi-page work, capture every changed page by `path` through the same preview server; no click navigation is required.\n- After MCP mutations, path screenshots regenerate/restart preview as needed before capture; when preview is fresh, repeated path screenshots reuse the running server.\n- Do not call `preview.start` through one-shot `webstudio mcp single-op-call`: it is long-lived. From a shell, use `webstudio mcp run` with preview.start, screenshot, and preview.stop in one shared process, or use a real long-running MCP client.\n- From one-shot shell calls or another process, pass `baseUrl` with `path` to capture an already-running preview/site without generating, building, starting, or restarting preview.\n- Use preview.stop only in the same long-running MCP server or `webstudio mcp run` process that started preview. A separate one-shot `single-op-call` process does not own another process\'s preview controller.\n- Use waitForSelector when the rendered app has a reliable ready marker, waitUntil:"networkidle" for network-heavy pages, and waitForTimeout only for final visual settling.\n- Preview installs generated app dependencies under `.webstudio/preview` and reuses them across regenerations.\n- Do not add generated-preview dependencies to the repository root `package.json` or `pnpm-lock.yaml`.\n- If dependency installation fails, check npm and network configuration, then reinstall or update the Webstudio CLI if the problem persists.\n- When a baseline exists, use screenshot.diff once per baseline/current page or viewport pair to get changed regions, OCR textAnalysis, and diff artifact paths before deciding whether the result matches. Pass expectedText for explicit pass/fail current-screen text assertions with found and missing text. Pass expectedVisual for pass/fail limits on pixel mismatch percentage, changed-region count, or the overall dominant color/brightness direction.\n- If screenshot.diff reports OCR unavailable and the user agrees to install it, call vision.install-ocr {"confirm":true}; otherwise continue with pixel diff and visual inspection.\n- Compare the PNG, OCR text evidence, and diff artifacts against the user\'s intent for layout, typography, colors, spacing, imagery, and responsive framing; then iterate with focused mutations.\n- Root CLI equivalent: `webstudio screenshot --path /pricing --output pricing.png` generates a temporary production preview, captures that route, and stops the server. For repeated captures, keep `webstudio preview` running and pass its absolute URL to `webstudio screenshot`.\n\n## List pages\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n\n## Read page by id\n\nCommands:\n\n- MCP tool: get-page {"pageId":"<pageId>"}\n\n## Read page by path\n\nCommands:\n\n- MCP tool: get-page-by-path {"path":"/pricing"}\n\n## Create page\n\nCommands:\n\n- MCP tool: create-page {"name":"Pricing","path":"/pricing"}\n- MCP tool: create-page {"name":"Pricing","path":"/pricing","title":"Pricing","meta":{"description":"Plans for teams"}}\n\nNotes:\n\n- `name`, `path`, page `title`, and metadata text fields accept plain fixed values.\n- For computed page titles or metadata, send JavaScript expression code such as `pageTitle ?? "Pricing"`.\n\n## Update page settings/metadata\n\nCommands:\n\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans","status":"200"}}}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n\nNotes:\n\n- Page `title` and metadata text fields accept plain fixed values.\n- For computed page titles or metadata, send JavaScript expression code such as `pageTitle ?? "Pricing"`.\n\n## Read project settings\n\nCommands:\n\n- MCP tool: get-project-settings {}\n\nNotes:\n\n- Read `meta.agentInstructions` before making project changes. It contains the project\'s own guidance for AI agents.\n- Agent instructions are shared project guidance. Do not store credentials or other secrets there.\n\n## Update project settings\n\nCommands:\n\n- MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}\n- MCP tool: update-project-settings {"meta":{"agentInstructions":"Use existing design tokens and keep product copy concise."}}\n\n## Read marketplace product\n\nCommands:\n\n- MCP tool: get-marketplace-product {}\n\n## Update marketplace product\n\nCommands:\n\n- MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"asset-id","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}\n\n## List redirects\n\nCommands:\n\n- MCP tool: list-redirects {}\n\n## Create redirect\n\nCommands:\n\n- MCP tool: create-redirect {"old":"/old","new":"/new","status":301}\n\n## Update redirect\n\nCommands:\n\n- MCP tool: update-redirect {"old":"/old","values":{"new":"/newer","status":302}}\n- MCP tool: update-redirect {"old":"/old","values":{"status":null}}\n\n## Delete redirect\n\nCommands:\n\n- MCP tool: delete-redirect {"old":"/old"}\n\n## Set redirects\n\nCommands:\n\n- MCP tool: set-redirects {"redirects":[{"old":"/old","new":"/new","status":"301"}]}\n\n## List breakpoints\n\nCommands:\n\n- MCP tool: list-breakpoints {}\n\n## Create breakpoint\n\nCommands:\n\n- MCP tool: create-breakpoint {"label":"Tablet","maxWidth":991}\n\n## Update breakpoint\n\nCommands:\n\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"label":"Tablet","maxWidth":1023}}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"condition":null,"minWidth":768}}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"minWidth":null,"maxWidth":null,"condition":"(hover: hover)"}}\n\n## Delete breakpoint\n\nCommands:\n\n- MCP tool: delete-breakpoint {"breakpointId":"tablet"}\n\n## Duplicate page\n\nCommands:\n\n- MCP tool: duplicate-page {"pageId":"<pageId>","name":"Pricing Copy","path":"/pricing-copy"}\n\n## List page templates\n\nCommands:\n\n- MCP tool: list-page-templates {}\n\n## Create page template\n\nCommands:\n\n- MCP tool: create-page-template {"name":"Landing Template","title":"Landing"}\n\n## Update page template\n\nCommands:\n\n- MCP tool: update-page-template {"templateId":"<templateId>","values":{"name":"Article Template","meta":{"description":"Reusable article layout"}}}\n\n## Delete page template\n\nCommands:\n\n- MCP tool: delete-page-template {"templateId":"<templateId>"}\n\n## Duplicate page template\n\nCommands:\n\n- MCP tool: duplicate-page-template {"templateId":"<templateId>"}\n\n## Reorder page template\n\nCommands:\n\n- MCP tool: reorder-page-template {"sourceTemplateId":"<sourceTemplateId>","targetTemplateId":"<targetTemplateId>","position":"before"}\n\n## Create page from template\n\nCommands:\n\n- MCP tool: create-page-from-template {"templateId":"<templateId>","name":"Landing","path":"/landing"}\n\n## Delete page\n\nCommands:\n\n- MCP tool: delete-page {"pageId":"<pageId>"}\n\n## List folders\n\nCommands:\n\n- MCP tool: list-folders {"includePages":true}\n\n## Create folder\n\nCommands:\n\n- MCP tool: create-folder {"name":"Blog","slug":"blog"}\n\n## Update folder\n\nCommands:\n\n- MCP tool: update-folder {"folderId":"<folderId>","values":{"name":"Blog","slug":"blog"}}\n\n## Delete folder\n\nCommands:\n\n- MCP tool: delete-folder {"folderId":"<folderId>"}\n\n## List element instances\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":3}\n\n## Inspect one element instance\n\nCommands:\n\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n\n## Insert authored JSX or one component template\n\nCommands:\n\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px;`}><ws.element ws:tag=\\"h2\\">Product OS</ws.element><radix.Switch><radix.SwitchThumb /></radix.Switch></ws.element>"}\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"@webstudio-is/sdk-components-react-radix:Switch"}\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"Form"}\n\nNotes:\n\n- Use MCP `insert-fragment` as the default way to author styled component trees. It converts JSX to a structured fragment before mutation.\n- Use only exact component ids returned by `components.search`, `components.get`, or `templates.get`. Never derive or guess component ids.\n- The `ws:` namespace contains specific Webstudio core components; it is not HTML-tag shorthand. Use `<ws.element ws:tag="div">` for a native `div` and `<ws.element ws:tag="form">` for a native form, never `<ws.div>` or `<ws.form>`.\n- For Webstudio\'s complete form structure, discover the Form component and insert its automatic template with `insert-component` using component `"Form"`.\n- MCP receives JSX as a JSON string because MCP arguments are JSON. The CLI converts it locally before the runtime mutation, so the project session receives structured Webstudio data, not JSX source.\n- In `insert-fragment` JSX, use `ws:style={css\\`...\\`}`for Webstudio-native CSS, or use React-style object syntax such as`style={{ padding: 24 }}` when that is simpler. Both forms create editable Webstudio style data.\n- Do not access host globals or dynamic code APIs in JSX fragments, including `process`, `globalThis`, `eval`, `Function`, or `constructor`.\n- Use Webstudio prop names such as `class` and `for`; do not use React aliases `className` or `htmlFor`.\n- Use Webstudio actions for event/action props, for example `onClick={new ActionValue(["event"], expression\\`console.log(event)\\`)}`. Do not pass JavaScript functions such as `onClick={() => ...}`.\n- Plain prop values must be JSON-compatible: `null`, strings, booleans, finite numbers, arrays, and plain objects. Do not pass `undefined`, `Symbol`, `BigInt`, `NaN`, `Infinity`, `Date`, `Map`, `Set`, class instances, or circular objects; omit the prop, use plain data, or use `expression`/`ActionValue` when the value is dynamic.\n- Template-backed components used in JSX must include required child/part components explicitly under the same parent structure as the template, for example `<radix.Switch><radix.SwitchThumb /></radix.Switch>`.\n- Webstudio applies a registered template automatically when using `insert-component`, so composed components such as Switch include required child parts and styles.\n- Use `components.list`, `components.summary`, `components.search`, `components.get`, `templates.list`, and `templates.get` to discover known registry items, component ids, props, templates, insertability, and content model. Read `webstudio://project/components` only when those focused tools are insufficient.\n- Component/template registry items use a shadcn-compatible top-level shape plus Webstudio-specific superset metadata in `meta`. They are for Builder/MCP discovery, not a published shadcn install registry yet.\n- Known components with `contentModel.category: "none"` are not standalone-insertable; insert their root component template instead so required providers/parents are included.\n- Unknown custom component ids are a low-level extension mechanism, not a discovery fallback. Agents must not synthesize them.\n\n## Make a region editable in Content mode\n\nCommands:\n\n- MCP tool: insert-component {"parentInstanceId":"<instanceId>","component":"ws:block"}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["children"]}\n\nNotes:\n\n- When a page will be handed to a Content-mode editor, wrap every region they should be able to edit in a Content Block (`ws:block`). Content-mode editors can edit text and supported props only in Content Block descendants. Content outside those blocks remains read-only, even when it looks like ordinary editable text.\n- Put reusable insertable options inside the Content Block\'s `ws:block-template` child. A template is source material, not editor content: editors cannot edit or delete it directly. When an editor inserts a template, its copy becomes a direct child of the Content Block and is editable.\n- Before handing off a page, verify with `inspect-instance` that the intended text, images, and links are inside a Content Block, and that templates include all required styling because Content-mode editors cannot use the Style panel.\n\n## Move elements\n\nCommands:\n\n- MCP tool: move-instance {"moves":"moves.json contents"}\n\nNotes:\n\n- Use `position: "end"` to append an instance. Repeating this for A and then B preserves the final order A, B.\n- A numeric `insertIndex` addresses the target parent\'s children before the moved instance is removed. Use it for exact placement; do not calculate the last index to append.\n- Moves in one `moves` array are applied sequentially in array order.\n\n## Clone element subtree\n\nCommands:\n\n- MCP tool: clone-instance {"sourceInstanceId":"<instanceId>","targetParentInstanceId":"<targetParentId>"}\n\n## Delete element subtree\n\nCommands:\n\n- MCP tool: delete-instance {"instanceIds":["<instanceId>"]}\n\n## List text/expression children\n\nCommands:\n\n- MCP tool: list-texts {"pagePath":"/"}\n\n## Update text child\n\nCommands:\n\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n\n## Replace bounded literal text\n\nCommands:\n\n- MCP tool: replace-text {"find":"Start free","replace":"Get started","match":"exact","pagePath":"/pricing","limit":20}\n\nNotes:\n\n- This changes only literal text children, never expression children. Scope it to pagePath or pageId and set a limit before a broad replacement.\n\n## Replace bounded static prop text\n\nCommands:\n\n- MCP tool: replace-prop-text {"find":"old.example.com","replace":"www.example.com","match":"substring","names":["href","code"],"limit":20}\n\nNotes:\n\n- This changes only static string props such as href, alt, aria-label, title, and HTML embed code. It never changes expressions, resources, actions, assets, or other dynamic bindings. Use names or instanceIds and a limit to narrow the change.\n\n## Replace bounded resource text\n\nCommands:\n\n- MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}\n\nNotes:\n\n- This changes resource names and fixed URL literals only. It skips dynamic URL expressions, headers, search parameters, request bodies, and GraphQL query code.\n\n## Update props\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: replace-prop-text {"find":"Old label","replace":"New label","names":["aria-label","title"],"limit":20}\n\nNotes:\n\n- Use this for fixed prop values such as `aria-label`, `alt`, `id`, static `href`, and other direct string/number/boolean/json prop values.\n\n## Add JSON-LD structured data\n\nCommands:\n\n- MCP tool: components.get {"component":"JsonLd"}\n- MCP tool: insert-component {"parentInstanceId":"<headSlotInstanceId>","component":"JsonLd"}\n- MCP tool: update-props {"updates":[{"instanceId":"<jsonLdInstanceId>","name":"code","type":"string","value":"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Organization\\",\\"name\\":\\"Acme\\"}"}]}\n- MCP tool: audit {"scopes":["seo"],"pagePath":"/"}\n\nNotes:\n\n- Prefer placing `JsonLd` inside `HeadSlot`.\n- Store `code` as a JSON object or array encoded as a compact string. The Builder formats it for editing.\n- The semantic prop update rejects malformed JSON and structurally invalid fixed JSON-LD with a precise JSON path.\n- The SEO audit also warns about a missing top-level `@context`, unknown or superseded Schema.org terms, properties unsupported by the supplied type, and incompatible primitive value types.\n- Schema.org vocabulary findings are warnings because custom vocabularies and extensions remain valid. Dynamic JSON-LD is marked as skipped for rendered validation.\n- Do not use bindings just to set static text.\n\n## Delete props\n\nCommands:\n\n- MCP tool: delete-props {"deletions":"props.json contents"}\n\n## Bind props to expressions/resources/actions\n\nCommands:\n\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Use this only when the prop should remain dynamic: expression, resource, action, or an existing scoped runtime context value such as `system`.\n- For a fixed string value, use `update-props` with `type:"string"` and a direct `value` instead.\n\n## Read styles\n\nCommands:\n\n- MCP tool: get-styles {"instanceIds":["<instanceId>"],"includeTokens":true}\n\n## Update local styles\n\nCommands:\n\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\n## Delete local styles\n\nCommands:\n\n- MCP tool: delete-styles {"deletions":"styles.json contents"}\n\n## Replace matching style values\n\nCommands:\n\n- MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}\n\n## List design tokens\n\nCommands:\n\n- MCP tool: list-design-tokens {}\n- MCP tool: list-design-tokens {"withUsage":true}\n- MCP tool: list-design-tokens {"verbose":true}\n\nNotes:\n\n- The default response is compact and includes token id, name, declaration count, and optional usage count.\n- Use `verbose:true` only when you need the full inline style declarations.\n\n## Create design tokens\n\nCommands:\n\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n\n## Update design token styles\n\nCommands:\n\n- MCP tool: update-design-token-styles {"designTokenId":"<tokenId>","updates":"styles.json contents"}\n\n## Delete design token styles\n\nCommands:\n\n- MCP tool: delete-design-token-styles {"designTokenId":"<tokenId>","deletions":"styles.json contents"}\n\n## Attach design token to instances\n\nCommands:\n\n- MCP tool: attach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Detach design token from instances\n\nCommands:\n\n- MCP tool: detach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Extract design token from local styles\n\nCommands:\n\n- MCP tool: extract-design-token {"instanceIds":["<instanceId>"],"name":"Brand Primary","removeLocalProps":["color"]}\n\n## List CSS variables\n\nCommands:\n\n- MCP tool: list-css-variables {"withUsage":true}\n\n## Define CSS variables\n\nCommands:\n\n- MCP tool: define-css-variable {"vars":"vars.json contents"}\n\n## Delete CSS variables\n\nCommands:\n\n- MCP tool: delete-css-variable {"names":"names.json contents","force":true}\n\n## Rewrite CSS variable references\n\nCommands:\n\n- MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}\n\n## List data variables\n\nCommands:\n\n- MCP tool: list-variables {}\n- MCP tool: list-variables {"scopeInstanceId":"<instanceId>"}\n\nNotes:\n\n- Data variables live in the internal `dataSources` namespace.\n- For raw `snapshot`, request the public `variables` namespace rather than the internal `dataSources` name. Raw patch payloads still use `dataSources` when applying direct changes.\n- Scope variables to the instance where they should become available. Descendants can use them in expressions, and nested variables with the same name mask outer variables.\n\n## Create data variable\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"count","value":{"type":"number","value":3}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"featured","value":{"type":"boolean","value":true}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"tags","value":{"type":"string[]","value":["news","product"]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"filters","value":{"type":"json","value":{"tag":"news"}}}\n\nNotes:\n\n- Data variable values support `string`, `number`, `boolean`, `string[]`, and `json`.\n- Parameters are internal scoped runtime values provided by pages, collections, or components. They are not a public authoring surface: do not create, update, or delete parameter records. Use data variables/resources for user-authored data, and reference documented context values such as `system` only where they are already in scope.\n\n## Update data variable\n\nCommands:\n\n- MCP tool: update-variable {"dataSourceId":"<variableId>","values":{"value":{"type":"json","value":{"count":1}}}}\n\n## Delete data variable\n\nCommands:\n\n- MCP tool: delete-variable {"dataSourceId":"<variableId>"}\n\n## List resources\n\nCommands:\n\n- MCP tool: list-resources {}\n- MCP tool: list-resources {"scopeInstanceId":"<instanceId>"}\n\n## Create resource\n\nCommands:\n\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"https://api.example.com/posts","headers":[]}}\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"\\"https://api.example.com/posts?tag=\\" + filters.tag","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Filtered Posts","method":"get","url":"https://api.example.com/posts","searchParams":[{"name":"tag","value":"filters.tag"},{"name":"source","value":{"type":"literal","value":"website"}}],"headers":[{"name":"Authorization","value":"\\"Bearer \\" + auth.token"}]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Post GraphQL","control":"graphql","method":"post","url":"https://api.example.com/graphql","headers":[{"name":"Content-Type","value":{"type":"literal","value":"application/json"}}],"body":"{ query: \\"query Post($slug: String!) { post(slug: $slug) { title } }\\", variables: { slug: system.params.slug } }"},"scopeInstanceId":"<instanceId>","dataSourceName":"post"}\n- MCP tool: create-resource {"resource":{"name":"Current Date","control":"system","method":"get","url":"/$resources/current-date","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"currentDate"}\n\nNotes:\n\n- Resource `url` accepts plain fixed URLs and paths such as `https://api.example.com/posts` and `/$resources/current-date`.\n- Resource `url` can also be a JavaScript expression when it is computed, such as `"https://api.example.com/posts?tag=" + filters.tag`.\n- Header values, search parameter values, and body accept expressions for dynamic values. For fixed text, use `{"type":"literal","value":"application/json"}`; Webstudio stores the required string expression for you.\n- Search parameter values, header values, and body expressions can read scoped variables and documented runtime context values such as `system` when they are available at the resource scope.\n- Add `scopeInstanceId` and `dataSourceName` when the resource result should be exposed as a scoped read data variable. Scoped resources are generated into the page resource `data` map and may be loaded during page rendering. Use this for read-oriented resources such as GET CMS/API data.\n- For submit/write/action resources, create the resource without `scopeInstanceId`, then bind a component prop such as a Form `action` with `bind-props` and `binding.type: "resource"`. Prop-bound resources are generated into the page resource `action` map instead of the read `data` map. Use this for POST, PUT, DELETE, webhooks, GraphQL submissions, and other explicit action flows.\n- Resource `method` can be `get`, `post`, `put`, or `delete`. Use GET for read data, POST for creates/GraphQL/webhooks/form submissions, PUT for full updates or replacements, and DELETE for deletion actions.\n- Optional `control` values are `graphql` and `system`. Use `graphql` for GraphQL-style requests, usually POST with a query body. Use `system` for built-in resources such as `"/$resources/sitemap.xml"`, `"/$resources/current-date"`, and `"/$resources/assets"` and when the resource should use the built-in `system` parameter. System fields are `system.origin`, `system.pathname`, `system.params`, and `system.search`.\n\n## Update resource\n\nCommands:\n\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}\n\n## Delete resource\n\nCommands:\n\n- MCP tool: delete-resource {"resourceId":"<resourceId>"}\n\n## List assets\n\nCommands:\n\n- MCP tool: list-assets {"withUsage":true}\n\nNotes:\n\n- Image asset descriptions are the default alt text for asset-backed Image components.\n- To generate missing descriptions, inspect the image in its rendered page or asset source, write a concise description of its purpose, and save it on the asset rather than duplicating it on each Image instance.\n\n## Update asset metadata\n\nCommands:\n\n- MCP tool: update-asset {"assetId":"<assetId>","values":{"description":"Team collaborating around a whiteboard"}}\n\nNotes:\n\n- Use an empty description only when the image is intentionally decorative.\n- Updating an image asset description updates the default alt text wherever that asset is used with an asset-backed alt prop.\n\n## Generate missing image descriptions with an agent\n\nCommands:\n\n- MCP tool: audit {"scopes":["accessibility"],"verbose":true}\n- MCP tool: set-image-descriptions {"updates":[{"assetId":"hero-id","description":"Team collaborating around a whiteboard"},{"assetId":"texture-id","decorative":true}]}\n- MCP tool: audit {"scopes":["accessibility"]}\n\nNotes:\n\n- Start from `missing-image-description` findings. Inspect each image in its rendered page context before writing text.\n- The vision-capable agent generates the wording; the CLI validates and stores it but does not contain its own vision model.\n- Use `decorative:true` only when the image adds no information. This intentionally stores an empty description so later audits do not report it as missing.\n- Re-run the accessibility audit after the update. Asset-backed Image components use the saved asset description as their default alt text.\n\n## Manage fonts\n\nCommands:\n\n- MCP tool: list-fonts {"includeSystem":true}\n- MCP tool: list-assets {"type":"font"}\n- MCP tool: upload-asset {"asset":{"name":"acme-sans.woff2","type":"font","format":"woff2","meta":{"family":"Acme Sans","style":"normal","weight":400}},"assetsDir":".webstudio/assets"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\nNotes:\n\n- Use `list-fonts` to discover uploaded families and system stacks. Upload/delete fonts through the existing asset tools, then apply a family with a `font-family` style declaration.\n\n## Upload one asset\n\nCommands:\n\n- MCP tool: upload-asset {"asset":{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}},"assetsDir":".webstudio/assets"}\n\n## Upload asset batch\n\nCommands:\n\n- MCP tool: upload-assets {"assets":[{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}}],"assetsDir":".webstudio/assets"}\n\n## Find asset usage\n\nCommands:\n\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n\n## Replace asset references\n\nCommands:\n\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>"}\n\n## Delete assets\n\nCommands:\n\n- MCP tool: delete-asset {"assetIdsOrPrefixes":["<assetId>"],"force":true}\n\n## Publish project\n\nCommands:\n\n- webstudio publish deploy --target production --json\n\n## List publishes\n\nCommands:\n\n- webstudio publish list --json\n\n## Check publish job\n\nCommands:\n\n- webstudio publish status --job <buildId> --json\n\n## Unpublish\n\nCommands:\n\n- webstudio publish unpublish --target production --confirm --json\n\n## List domains\n\nCommands:\n\n- webstudio domains list --json\n\n## Create domain\n\nCommands:\n\n- webstudio domains create --domain example.com --json\n\n## Update domain\n\nCommands:\n\n- webstudio domains update --domain-id <domainId> --domain www.example.com --json\n\n## Delete domain\n\nCommands:\n\n- webstudio domains delete --domain-id <domainId> --confirm --json\n\n## Verify domain\n\nCommands:\n\n- webstudio domains verify --domain-id <domainId> --json\n\n## Make arbitrary store-level changes\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["<namespace>"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use only when no semantic command exists.\n\n## Manage marketplace metadata\n\nCommands:\n\n- MCP tool: get-marketplace-product {}\n- MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"asset-id","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}\n\nPatch namespaces:\n\n- marketplaceProduct\n\n## Search and inspect safely\n\nCommands:\n\n- MCP tool: search-project {"query":"pricing"}\n- MCP tool: search-project {"query":"api.example.com","scopes":["resources"]}\n- MCP tool: list-instances {"pagePath":"/","maxDepth":5}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: list-assets {"withUsage":true}\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n- MCP tool: snapshot {"include":["pages","instances","props","resources","assets"]}\n\nNotes:\n\n- Use `search-project` for query-driven lookup across labels, text, prop values, resource URLs, asset metadata, and styles. Use `audit` for project health findings.\n\n## Audit project quality\n\nCommands:\n\n- webstudio audit --json\n- webstudio audit --scopes accessibility --scopes seo --json\n- webstudio audit --page-path /pricing --json\n- webstudio audit --scopes accessibility --verbose --json\n- webstudio audit --rendered --page-path /pricing --json\n- webstudio audit --rendered --route-example post=/blog/hello --json\n- webstudio audit --rendered --image-domain images.example.com --json\n- MCP tool: audit {}\n- MCP tool: audit {"scopes":["accessibility","security"],"severities":["error","warning"]}\n- MCP tool: audit {"scopes":["accessibility"],"verbose":true}\n- MCP tool: audit {"rendered":true,"verbose":true}\n\nNotes:\n\n- With no scopes, `audit` checks accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, non-GET resources exposed as render-time data, and unused or duplicate style data.\n- The `performance` scope reports disabled atomic CSS generation. A rendered audit also measures broken, eager below-fold, and oversized images, browser-marked render-blocking resources, and legacy font formats.\n- Rendered image and resource metrics run only when the selected scopes include `performance`; responsive layout dimensions remain available whenever `rendered:true` is requested.\n- Compact findings include stable ids, severity, message, and location. Use `--verbose` or `{"verbose":true}` for evidence, explanation, suggested remediation, skipped-check details, and manual-check workflows.\n- `summary` counts all findings before severity filtering and pagination.\n- `contractVersion` identifies the audit response contract. Handle a new value before assuming existing fields retain the same meaning.\n- Expression-, resource-, and parameter-backed values that cannot be checked reliably appear in `skippedChecks`; they are not treated as passing or failing.\n- Page filters apply to page-owned accessibility, security, and SEO checks. Asset and style usage remain project-wide to avoid false unused findings.\n- Continue paginated results with `cursor`. Restart the audit if the project version changes.\n- Verbose skipped-check and manual-check details are included on the first findings page only; their total counts remain available on every page.\n- `manualChecks` describes responsive, hierarchy, and contrast checks that require preview screenshots and vision.\n- Focused audits return only manual checks relevant to their selected scopes.\n- In a long-lived MCP session, `{"rendered":true}` reuses preview and screenshot\n tools to capture every static page at mobile, desktop, and Builder breakpoint\n edges. Compact output reports rendered check/issue/failure counts; verbose\n output includes screenshot paths and measured layout dimensions.\n- Dynamic route templates are skipped unless `--route-example <pageId>=<path>`\n (or MCP `routeExamples`) supplies a concrete path. The path must not contain\n unresolved `:` or `*` parameters.\n- Plans above 120 captures return a short-lived confirmation token. Review the\n unchanged plan, then rerun with `--confirm-large-run` and\n `--confirmation-token`.\n- Detailed rendered evidence is stored in a versioned manifest under\n `.webstudio/audits`; compact output includes its path and screenshot count.\n- Rendered checks also report broken images, eager images below the fold, and\n image sources more than 2x their rendered dimensions in both axes, including\n Webstudio instance ids and measured dimensions when available.\n- Rendered checks include sanitized Resource Timing evidence and report\n browser-marked render-blocking resources plus legacy `.ttf`, `.otf`, and\n `.woff` fonts without applying a universal transfer-size threshold.\n- Fix findings through semantic mutation commands, then rerun `audit` to confirm their deterministic finding ids disappeared.\n\n## Refactor targeted content\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/"}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n- MCP tool: replace-text {"find":"Old headline","replace":"New headline","match":"exact","pagePath":"/pricing","limit":20}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans"}}}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>"}\n- MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}\n- MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}\n\nNotes:\n\n- Use focused reads first, then mutate only matching instances, props, metadata, resource URLs, assets, or style references. Use `replace-text` for bounded literal text changes, `replace-prop-text` for bounded static prop text, `replace-resource-text` for fixed resource names/URLs, and `update-text` for one known child or expressions.\n\n## Optimize existing project\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"Pricing","meta":{"description":"Plans"}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: list-breakpoints {}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"maxWidth":1023}}\n- MCP tool: get-styles {"instanceIds":["<instanceId>"],"includeTokens":true}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: attach-design-token {"designTokenId":"<tokenId>","instanceIds":"instances.json contents"}\n- MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}\n\nNotes:\n\n- Use this for SEO metadata, accessibility labels, responsive behavior, token consistency, and project settings.\n\n## Connect external data\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"tags","value":{"type":"string[]","value":["news","product"]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"filters","value":{"type":"json","value":{"tag":"news"}}}\n- MCP tool: create-resource {"resource":{"name":"Posts","method":"get","url":"https://api.example.com/posts","searchParams":[{"name":"tag","value":"filters.tag"},{"name":"source","value":{"type":"literal","value":"website"}}],"headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"posts"}\n- MCP tool: create-resource {"resource":{"name":"Post GraphQL","control":"graphql","method":"post","url":"https://api.example.com/graphql","headers":[{"name":"Content-Type","value":{"type":"literal","value":"application/json"}}],"body":"{ query: \\"query Post($slug: String!) { post(slug: $slug) { title } }\\", variables: { slug: system.params.slug } }"},"scopeInstanceId":"<instanceId>","dataSourceName":"post"}\n- MCP tool: create-resource {"resource":{"name":"Current Date","control":"system","method":"get","url":"/$resources/current-date","headers":[]},"scopeInstanceId":"<instanceId>","dataSourceName":"currentDate"}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"https://api.example.com/posts"}}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.collection>{/_ collection content _/}</ws.collection>"}\n\nNotes:\n\n- Use this for CMS sections, blog listings, Ghost/headless CMS pages, n8n-style integrations, and API URLs built from variables.\n- For read data, expose GET resources as scoped data variables with `scopeInstanceId`/`dataSourceName` and read the loaded result from the resource result wrapper, usually `.data`.\n- For writes, webhooks, GraphQL submissions, and deletes, prefer unscoped resources bound to Form `action` props so they become action resources instead of auto-loaded read resources.\n- Use direct props for fixed values and prop bindings only when a prop must read a data variable, resource, action, or documented runtime context value such as `system`.\n\n## Render an array or object as repeated content\n\nCommands:\n\n- MCP tool: insert-collection {"parentInstanceId":"<instanceId>","data":{"type":"expression","value":"posts.data.items"},"itemFragment":"<ws.element ws:tag=\\"article\\"><ws.element ws:tag=\\"h2\\">{expression`collectionItem.title`}</ws.element></ws.element>"}\n- MCP tool: inspect-instance {"instanceId":"<collectionId>","include":["props","bindings","children"]}\n\nNotes:\n\n- Use Collection whenever an array or object from a resource or data variable should render a list, grid, cards, table rows, options, tabs, or other repeated UI.\n- Pass `insert-collection` the complete array or object. Do not pass the resource response wrapper or one indexed item. External resource arrays are commonly nested under the scoped resource result\'s `data` field or deeper.\n- Pass one repeated-item Webstudio JSX root. The command creates the Collection, its private current-item/current-key parameters, the iterable binding, and descendant item bindings atomically.\n- Collection renders the item root once for every entry. Use `expression` values such as `collectionItem.title` in descendant text and props. Object iteration also exposes `collectionItemKey`.\n- Wrap multiple repeated sibling instances in one Element inside Collection.\n- For repeated Radix items such as accordion items, tabs, or menu options, bind a stable unique id or slug to every required `value` prop.\n- See the [Collection documentation](https://docs.webstudio.is/university/core-components/collection) for the equivalent Builder workflow.\n\n## Support dynamic runtime behavior\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: create-resource {"resource":{"name":"Seats","method":"get","url":"https://api.example.com/seats","headers":[]}}\n- MCP tool: snapshot {"include":["instances","props","resources"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use existing scripts/resources for behavior, then move presentational structure into editable Webstudio instances where possible.\n- There is no dedicated semantic command yet for converting script-generated UI into editable Webstudio structure.\n\n## Build authenticated pages\n\nCommands:\n\n- MCP tool: create-page {"name":"Account","path":"/account"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n- MCP tool: create-resource {"resource":{"name":"Session","method":"get","url":"https://api.example.com/session","headers":[]}}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"user","value":{"type":"json","value":{}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Basic auth is semantic today. Provider-specific Supabase/Firebase setup still requires manual resources, props, embeds, or patches.\n\n## Generate from design input\n\nCommands:\n\n- MCP tool: create-page {"name":"Landing","path":"/landing"}\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n- MCP tool: define-css-variable {"vars":"vars.json contents"}\n- MCP tool: insert-fragment {"parentInstanceId":"<instanceId>","fragment":"<ws.element ws:tag=\\"section\\"><ws.element ws:tag=\\"p\\">Section copy</ws.element></ws.element>"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n\nNotes:\n\n- Use this after external design interpretation. There is no dedicated import command for Figma, screenshots, Inception output, or design.md yet.\n\n## Cross-project maintenance\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n- webstudio permissions --json\n- webstudio mcp\n\nNotes:\n\n- Public API and CLI intentionally operate on one configured project at a time. Use an external script to loop over projects.\n\n# Known CLI Gaps\n\n## Provider-specific authenticated pages\n\nMissing:\nCLI supports page basic auth and generic resources/props/embeds, but not guided Supabase/Firebase auth setup.\n\nCurrent fallback:\nCreate the page, resources, variables, props, and embeds manually with existing MCP semantic tools.\n\nSuggested commands:\n\n- setup-auth-page\n\n## Dynamic script/runtime integration helpers\n\nMissing:\nCLI can manipulate props/resources/embeds, but has no semantic workflow for converting script-generated UI into editable Webstudio structures.\n\nCurrent fallback:\nUse MCP props, resources, and raw patch where necessary.\n\nSuggested commands:\n\n- integrate-runtime-ui\n\n## Generate from design input\n\nMissing:\nNo command imports Figma, screenshots, Inception output, or design.md and turns it into pages/tokens/layout.\n\nCurrent fallback:\nUse external generation, then apply semantic CLI commands or apply-patch.\n\nSuggested commands:\n\n- generate-from-design\n\n## Built-in cross-project maintenance\n\nMissing:\nPublic API and CLI intentionally operate on one configured project at a time; there is no built-in multi-project discovery or loop runner.\n\nCurrent fallback:\nRun the CLI from an external script that reconfigures one project/session at a time.\n\nSuggested commands:\n\n- none\n',
"manual-api":
'# Webstudio API CLI Manual\n\nThe API commands operate on the single project configured by:\n\n- .webstudio/config.json: projectId\n- global Webstudio config: origin and token\n\n- Pass --json to API/discovery commands that support it. Do not add --json to top-level commands unless their help/schema documents it.\n- Never pass a project id. Commands use configured project only.\n- Read ids before writing. Do not invent ids for existing records.\n- stdout is one JSON object. stderr is diagnostics.\n- Prefer MCP semantic tools for detailed project edits. Use MCP apply-patch only when no semantic tool exists.\n\n## Start\n\n{{start}}\n\n## Read First\n\n{{readFirst}}\n\n## Project Session Cache\n\n- CLI commands use one local ProjectSession snapshot for the configured project.\n- Local-capable reads use cached namespaces when compatible and fetch only missing or stale namespaces.\n- Local-capable mutations build patches from the local snapshot, then commit with the cached build version.\n- Successful mutation commits update the local snapshot only after the remote commit succeeds.\n- Server-only commands run remotely and invalidate/refetch namespaces declared by the operation catalog.\n- Use --refresh on local-capable commands to refresh required namespaces before running.\n- Successful JSON responses include compact meta.session with operationId, buildId, version, source, committed, namespaceCounts, diagnosticCount, non-empty diagnostic summaries, and optional compatibilityVersion.\n\n## CLI Capability Inventory\n\nFor a short end-consumer summary of what MCP can do, see\n`manual mcp` / `webstudio man mcp`. The MCP inventory describes the same\nproject, page, element, style, data, asset, publish, domain, and visual\nverification capabilities without internal command names.\n\n### Top-Level Commands\n\n{{topLevelCapabilityIndex}}\n\n### High-Level API Commands By Area\n\n{{apiCapabilityIndex}}\n\n### MCP Tool Operations\n\nThese are MCP tools. From a shell, call them with the shortcut form `webstudio <tool> \'<json>\'` or with the explicit form `webstudio mcp single-op-call <tool> \'<json>\'`:\n\n{{mcpOnlyCommandIndex}}\n\n## Task Recipes\n\n{{taskRecipeIndex}}\n\n## Use Case Index\n\n{{useCaseIndex}}\n\n## Known CLI Gaps\n\n{{knownCliGapIndex}}\n\n## Input File Shapes\n\n{{inputFileShapeIndex}}\n\n## Raw Patch Fallback\n\napply-patch accepts either BuildPatchTransaction[] or { "transactions": BuildPatchTransaction[] }.\n\nEach transaction has:\n\n{\n"id": "patch-transaction-label",\n"payload": [\n{\n"namespace": "projectSettings",\n"patches": [\n{ "op": "replace", "path": ["meta", "siteName"], "value": "New Site" }\n]\n}\n]\n}\n\nThe transaction id is a patch label used for optimistic synchronization. It is\nnot a Builder record id. Do not invent ids for pages, instances, props,\nbreakpoints, resources, variables, folders, assets, or other project records.\n\nPatch paths are JSON-patch-like paths into Builder store data. Map-like namespaces use ids as the first path item.\n\nSupported namespaces:\n\n- pages: redirects, page records, and folders\n- projectSettings: project-wide metadata and compiler settings\n- instances: element instances and children, including text/expression children\n- props: element props, bindings, page references, resource bindings\n- styles: CSS declarations keyed by style declaration key\n- styleSources: local style sources and reusable design tokens\n- styleSourceSelections: instance-to-style-source connections\n- dataSources: data variables, parameters, and resource data sources\n- resources: data resource definitions\n- assets: project asset records handled by the existing asset patch path\n- breakpoints: responsive breakpoints\n- marketplaceProduct: marketplace metadata\n\n## Data Sources\n\n`dataSources` is the internal Builder namespace for variables. Public API, CLI,\nand MCP tools expose it through two user-facing groups:\n\n- data variables: `list-variables`, `create-variable`, `update-variable`, and\n `delete-variable`\n- data resources: `list-resources`, `create-resource`, `update-resource`, and\n `delete-resource`\n\nFor raw `snapshot`, request the public `variables` namespace rather than the\ninternal `dataSources` name. Raw patch payloads still use `dataSources` when\napplying direct changes.\n\nVariables can be scoped to an instance. Expressions under that instance can use\nthe variable by name; nested variables with the same name mask outer variables.\nVariable values support `string`, `number`, `boolean`, `string[]`, and `json`.\nUse `string[]` for lists of strings such as tags or selected categories; use\n`json` for objects, arrays with mixed shapes, or nested API filter state.\nParameters are internal scoped runtime values provided by pages, collections,\nor components. They are not a public authoring surface: do not create, update,\nor delete parameter records. Public tools should preserve existing parameter\nrecords and may reference documented context values such as `system` in\nexpressions where they are already in scope.\n\nResource `url` accepts plain fixed URLs and paths, for example\n`https://api.example.com/posts` or `/$resources/current-date`. Dynamic URLs can\ncombine strings and variables, for example\n`"https://api.example.com/posts?tag=" + filters.tag`. Prefer `searchParams` for\nquery parameters that should be encoded separately:\n`[{ "name": "tag", "value": "filters.tag" }]`. Header values, search parameter\nvalues, and bodies are expressions for dynamic content. For fixed text, use\n`{ "type": "literal", "value": "application/json" }`; Webstudio stores the\nrequired string expression. Headers can still read variables such as\n`"Bearer " + auth.token`, and GraphQL bodies can return objects such as\n`{ query: "...", variables: { slug: system.params.slug } }`.\n\nCreate a GET resource with `scopeInstanceId` when the fetched resource result\nshould be available as a read data variable. Scoped GET resources default to\n`exposeAsDataSource: true`, are generated into the page resource `data` map,\nand may be loaded during page rendering. Use `dataSourceName` to choose the\nvariable name.\n\nFor submit/write/action resources, create the resource without\n`scopeInstanceId`, then bind a component prop such as a Form `action` to the\nresource with `bind-props` and `binding.type: "resource"`. Prop-bound resources\nare generated into the page resource `action` map instead of the read `data`\nmap. Use this shape for POST, PUT, DELETE, webhook, and other resources that\nshould run only from an explicit form/action flow, not merely because the page\nrendered.\n\nPOST, PUT, and DELETE resources default to `exposeAsDataSource: false` even\nwhen a scope is supplied. Set `exposeAsDataSource: true` only when a write-method\nresource intentionally provides render-time data, such as a read-only GraphQL\nPOST query. A scope is required, and the result includes a warning because the\nrequest may execute during page rendering. Set `exposeAsDataSource: false` on\n`update-resource` to detach an existing render-time data source.\n\nResource `method` can be `get`, `post`, `put`, or `delete`. Use GET for read\ndata. Use POST for creates, GraphQL requests, webhooks, and form submissions.\nUse PUT for full updates/replacements. Use DELETE for deletion actions.\nOptional `control` values are `graphql` and `system`: `graphql` marks a\nGraphQL-style resource, usually POST with a query body; `system` marks a\nresource intended to use the built-in `system` parameter or one of the built-in\nlocal resource URLs: `"/$resources/sitemap.xml"`,\n`"/$resources/current-date"`, and `"/$resources/assets"`. The system parameter\nfields are `system.origin`, `system.pathname`, `system.params`, and\n`system.search`.\n\nUse prop bindings for dynamic values that read variables or resources; use\ndirect props for static values.\n\nCommit raw patch:\n\nMCP tool: apply-patch\n\n## Raw Patch Examples\n\nRename the site:\n\n[\n{\n"id": "patch-site-name",\n"payload": [\n{\n"namespace": "projectSettings",\n"patches": [\n{ "op": "add", "path": ["meta", "siteName"], "value": "Acme Studio" }\n]\n}\n]\n}\n]\n\nUpdate page title metadata:\n\n[\n{\n"id": "patch-page-title",\n"payload": [\n{\n"namespace": "pages",\n"patches": [\n{ "op": "replace", "path": ["pages", "page-id", "meta", "title"], "value": "Pricing" }\n]\n}\n]\n}\n]\n\nUpdate a text child on an element:\n\n[\n{\n"id": "patch-text",\n"payload": [\n{\n"namespace": "instances",\n"patches": [\n{ "op": "replace", "path": ["instance-id", "children", 0, "value"], "value": "Launch faster" }\n]\n}\n]\n}\n]\n\nCreate records with semantic operations such as create-variable,\ncreate-resource, create-design-token, create-page, create-folder,\nand create-breakpoint. Raw patch rejects generated record\ncreation, collection replacement, record replacement with a different `id`, and\nrecord id field mutations in id-keyed namespaces because Webstudio must generate\nand preserve record ids.\n\n## Safety Rules\n\n- For MCP apply-patch, read the latest version with MCP snapshot before writing.\n- Reuse ids from MCP snapshot output when updating existing records.\n- Do not create generated records, replace generated record collections, replace records with different ids, or mutate record id fields with raw patch. Use semantic create operations so Webstudio generates ids.\n- If apply-patch reports a version conflict, read the latest build and regenerate the patch.\n- Prefer semantic MCP read tools for discovery, then use MCP snapshot for exact patch paths.\n\n## Command Index\n\n{{commandIndex}}\n',
"manual-llm":
- '# Webstudio CLI Manual for LLMs\n\nUse this order. Stop only when a command returns ok:false.\n\nIf you are inside the Webstudio monorepo, the first command discovery should use\nthe local CLI exactly as `node packages/cli/local.js ...` from the repo root. Do\nnot use `packages/cli/bin.js` for local source-tree work; it is the packaged\nbuild entry and may use stale built output. Do not use `pnpm exec webstudio`,\n`pnpm --filter webstudio exec webstudio`, or a global `webstudio`: they can\nresolve an older binary.\n\nFor delegated design-system or “use every component” tasks, skip the generic warm-up sequence and start with exactly one MCP command: `webstudio workflow.next \'{"goal":"design-system-page"}\'`. Report that returned checkpoint to the parent/user and stop until continued.\n\n## Always\n\n1. webstudio permissions --json\n2. For bounded shell workflows, call MCP tools directly through the CLI shortcut, for example `webstudio meta.index` or `webstudio insert-fragment \'<json>\' --dry-run`. The explicit form `webstudio mcp single-op-call <tool> \'<json>\'` is equivalent and useful when you need to make the MCP boundary obvious. Use `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'` for multiple calls in one shared CLI session. Use a normal JSON file path for large batches. Use long-running `webstudio mcp` only when your environment is a real MCP client. Do not manually send raw JSON-RPC to `webstudio mcp` from a shell or PTY.\n3. Read MCP `meta.index`, for example `webstudio meta.index`.\n4. Use focused MCP calls with concrete JSON: `webstudio meta.guide \'{"brief":"Create a design system page using every component"}\'`, `webstudio meta.get_more_tools \'{"tools":["insert-fragment"]}\'`, `webstudio components.list \'{"source":"all"}\'`, `webstudio components.coverage-plan`, `webstudio components.search \'{"brief":"radix select"}\'`, `webstudio components.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'`, `webstudio templates.list`, and `webstudio templates.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'`.\n5. Read overview resources `webstudio://project/tools-overview` or `webstudio://project/components-overview` when useful. Read full resources `webstudio://project/tools` or `webstudio://project/components` only when focused tools are insufficient.\n6. Pick focused MCP read tool.\n7. Pick semantic MCP write tool.\n\nUse `webstudio schema mcp` for a tiny MCP tool overview. Use `webstudio schema mcp --detail summary` for all tool descriptions, and `webstudio schema mcp --detail full` only when exact input schemas for all tools are truly needed; otherwise prefer focused `meta.get_more_tools` and `components.*` calls.\n\nRun these commands from the linked project root. Use the MCP startup status line\'s absolute root for local files; write temporary scripts and artifacts under `<project root>/.temp`, not under a parent workspace.\n\nMonorepo quick path for a simple styled section:\n\n```sh\nnode packages/cli/local.js mcp single-op-call meta.index\nnode packages/cli/local.js mcp single-op-call meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nnode packages/cli/local.js mcp single-op-call insert-fragment \'{"parentInstanceId":"parent-id","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px; display: grid; gap: 12px;`}><ws.element ws:tag="h2">Launch Kit</ws.element><ws.element ws:tag="p">A focused section created with Webstudio JSX.</ws.element><ws.element ws:tag="button">Get started</ws.element></ws.element>"}\' --dry-run\n```\n\nThe same local shortcut form is shorter and preferred for simple shell steps:\n\n```sh\nnode packages/cli/local.js meta.index\nnode packages/cli/local.js meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nnode packages/cli/local.js insert-fragment \'{"parentInstanceId":"parent-id","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px; display: grid; gap: 12px;`}><ws.element ws:tag="h2">Launch Kit</ws.element><ws.element ws:tag="p">A focused section created with Webstudio JSX.</ws.element><ws.element ws:tag="button">Get started</ws.element></ws.element>"}\' --dry-run\n```\n\nFor this simple path, do not grep source files, dump full MCP resources, or write parser scripts first. Use `list-pages`, `get-page-by-path`, or `list-instances` only to get the target `parentInstanceId`.\n\nWhen authoring JSX for `insert-fragment`, use Webstudio component helpers and Webstudio style syntax. Use `ws:style={css\\`...\\`}`for Webstudio-native CSS, or use React-style object syntax such as`style={{ padding: 24 }}` when that is simpler. Both forms create editable Webstudio style data.\n\nWhen the task says another user will edit a page in Content mode, use a Content Block (`ws:block`) around every editable region. Content-mode users can edit text and supported props only in descendants of that block; content outside it is read-only. Put reusable insertable options in the block\'s `ws:block-template` child. Do not put intended editor content inside that template container: templates are protected source material, while an inserted template copy becomes an editable direct child of the Content Block. Verify this structure before handoff.\n\nDo not access host globals or dynamic code APIs in JSX fragments, including `process`, `globalThis`, `eval`, `Function`, or `constructor`. JSX fragments are declarative project data; use the built-in Webstudio helpers instead.\n\nUse Webstudio prop names in JSX: `class`, `for`, `aria-label`, and other HTML/Webstudio names. Do not use React-only aliases such as `className` or `htmlFor`; the runtime rejects them with the Webstudio prop name to use.\n\nUse Webstudio actions for event/action props. Do not pass JavaScript functions such as `onClick={() => ...}`; the runtime rejects them because functions cannot be persisted as Webstudio project data.\n\n```tsx\n<ws.element\n ws:tag="button"\n onClick={new ActionValue(["event"], expression`console.log(event)`)}\n>\n Open\n</ws.element>\n```\n\nPlain JSX prop values must be JSON-compatible: `null`, strings, booleans, finite numbers, arrays, and plain objects. Do not pass `undefined`, `Symbol`, `BigInt`, `NaN`, `Infinity`, `Date`, `Map`, `Set`, class instances, or circular objects; omit the prop, use plain data, or use `expression`/`ActionValue` when the value is dynamic.\n\nIf a component has a registered template with required parts, JSX must include those parts explicitly under the same parent structure as the template, for example `<radix.Switch><radix.SwitchThumb /></radix.Switch>`. Use `insert-component` when you want Webstudio to apply one component template automatically.\n\n## Animation Components\n\nBefore creating animation examples, inspect the exact components with focused discovery:\n\n```sh\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:AnimateChildren"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:AnimateText"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:StaggerAnimation"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:VideoAnimation"}\'\n```\n\nUse Animation Group (`AnimateChildren`) as the controller. Put normal instances directly inside it, or put Text Animation, Stagger Animation, or Video Animation directly inside it. Text, Stagger, and Video are helper components with `contentModel.category: "none"` and should not be used as standalone section roots.\n\nDefine timing and CSS changes on the Animation Group `action` prop. Use `type:"view"` for viewport entry/exit progress and `type:"scroll"` for scroll-progress timelines. For in animations, keep the canvas styles as the final state and use `fill:"backwards"` with keyframes that describe the starting state. For out animations, use `fill:"forwards"` with keyframes that describe the ending state.\n\nText Animation settings: `slidingWindow` defaults to `5`, `easing` defaults to `linear`, and `splitBy` defaults to `char`. Use `splitBy:"space"` for word-by-word animation. The parent Animation Group keyframes provide the actual opacity, translate, scale, or other styles.\n\nStagger Animation settings: `slidingWindow` defaults to `1` and `easing` defaults to `linear`. It applies parent Animation Group progress across its direct children. Use `slidingWindow:0` for instant sequential steps, `1` for one child at a time, and values above `1` for overlapping waves.\n\nVideo Animation settings: `timeline` is a boolean. Prefer `insert-component` for Video Animation so the Video child template is inserted, then configure the Video child asset/source. Use short, seek-friendly videos for smooth scroll-linked playback.\n\nUse JSX fragments for authored animation structures when you need styled, editable examples. Put the final visual state in `ws:style` and put the starting or ending animated state in the Animation Group `action` keyframes. Include an explicit `offset` on every keyframe: use `offset: 0` for starting-state keyframes with `fill:"backwards"` and `offset: 1` for ending-state keyframes with `fill:"forwards"`.\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n axis: "block",\n animations: [\n {\n name: "Fade up on entry",\n timing: {\n fill: "backwards",\n rangeStart: ["entry", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["entry", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: 24, unit: "px" },\n ],\n },\n },\n },\n ],\n },\n ],\n }}\n>\n <ws.element\n ws:tag="section"\n ws:style={css`\n display: grid;\n gap: 16px;\n padding: 48px;\n border-radius: 24px;\n background: #111827;\n color: white;\n `}\n >\n <ws.element ws:tag="h2">Launch metrics</ws.element>\n <ws.element ws:tag="p">\n A polished card that fades up as it enters the viewport.\n </ws.element>\n </ws.element>\n</animation.AnimateChildren>\n```\n\nFor Text Animation, keep `animation.AnimateText` as the direct child of Animation Group and place the text-containing element inside it:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n name: "Parallax In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: 100, unit: "px" },\n ],\n },\n },\n },\n ],\n },\n {\n name: "Opacity In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n {\n name: "Scale In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n scale: {\n type: "tuple",\n value: [\n { type: "unit", value: 5, unit: "number" },\n { type: "unit", value: 5, unit: "number" },\n ],\n },\n },\n },\n ],\n },\n {\n name: "Parallax Out",\n timing: {\n fill: "forwards",\n rangeStart: ["cover", { type: "unit", value: 50, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [\n {\n offset: 1,\n styles: {\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: -100, unit: "px" },\n ],\n },\n scale: {\n type: "tuple",\n value: [\n { type: "unit", value: 5, unit: "number" },\n { type: "unit", value: 5, unit: "number" },\n ],\n },\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n ],\n insetStart: { type: "unit", value: 5, unit: "%" },\n insetEnd: { type: "unit", value: 5, unit: "%" },\n isPinned: true,\n }}\n>\n <animation.AnimateText\n splitBy="space"\n slidingWindow={5}\n easing="easeOutQuart"\n >\n <ws.element ws:tag="h2">Animate words with controlled rhythm</ws.element>\n </animation.AnimateText>\n</animation.AnimateChildren>\n```\n\nFor Stagger Animation, put the repeated cards or rows directly inside `animation.StaggerAnimation`:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n timing: {\n fill: "backwards",\n rangeStart: ["contain", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["contain", { type: "unit", value: 30, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n ],\n }}\n>\n <animation.StaggerAnimation>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Plan\n </ws.element>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Build\n </ws.element>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Launch\n </ws.element>\n </animation.StaggerAnimation>\n</animation.AnimateChildren>\n```\n\nFor Video Animation, use the registered template via `insert-component` when possible. If you author JSX, include the Video child explicitly:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n name: "Video progress",\n timing: {\n fill: "both",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [{ offset: 0, styles: {} }],\n },\n ],\n }}\n>\n <animation.VideoAnimation timeline={true}>\n <$.Video\n preload="auto"\n autoPlay={true}\n muted={true}\n playsInline={true}\n crossOrigin="anonymous"\n />\n </animation.VideoAnimation>\n</animation.AnimateChildren>\n```\n\n## Command Surface Boundary\n\n- Use top-level `webstudio ...` shell commands for setup, sync/import/build/preview/screenshot, permissions, publish/domains, schema, registry inspection, man, and starting MCP.\n- Use MCP tools for Builder project data manipulation: pages, instances/components, props, text, styles, tokens, variables, resources, assets, breakpoints, redirects, and raw patches.\n- From a shell, call MCP tools with the shortcut form `webstudio <tool> \'<json>\'`, for example `webstudio insert-fragment \'<json>\' --dry-run`. The explicit equivalent is `webstudio mcp single-op-call <tool> \'<json>\'`. Use `--input-file` for large payloads.\n- Inside the Webstudio monorepo, call the local CLI as its own command: `node packages/cli/local.js ...`. Do not wrap the CLI call in `pwd && ...`, command substitution, `pnpm exec webstudio`, `pnpm --filter webstudio exec webstudio`, or a global `webstudio`.\n- For experiments, pass `--dry-run` to local-capable mutation calls. Read the computed transaction from `meta.session.transaction` and its base build version from `meta.session.version`. Copying a `.webstudio` folder is not an isolated project clone; `.webstudio/config.json` still points to the same remote project, so non-dry-run mutations can commit to that project.\n- For bounded multi-step shell work, run inline JSON with `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'`; this reuses one CLI session without raw JSON-RPC. For large batches, write `{ "calls": [{ "tool": "..." }] }` to a normal JSON file and run `webstudio mcp run .temp/mcp-calls.json`.\n- Use JSON strings for `brief` fields. Never pass boolean flags such as `{"brief":true}`.\n- Treat `webstudio mcp single-op-call` and `webstudio mcp run` stderr lines as progress checkpoints; stdout remains JSON on both success and failure. On failure, parse stdout for `{ "ok": false, "error": { "code": "...", "message": "..." } }` before deciding what to fix.\n- If a CLI/MCP tool crashes, hangs, gives a confusing error, needs an undocumented workaround, or forces source-code inspection for normal usage, ask the user to report it in Discord `#help` at https://wstd.us/community. Give them a complete copy-paste report with the goal, expected behavior, actual error, exact command/tool call, stdout JSON, stderr/lifecycle logs, environment, workaround, and secrets redacted.\n- Run one-shot `webstudio mcp single-op-call` commands sequentially against a linked `.webstudio` folder. If a command returns `PROJECT_SESSION_BUSY`, another CLI/MCP process is updating the local session; wait a moment and retry sequentially.\n- In delegated or non-streaming agent environments, do not batch many MCP calls silently and do not wrap many shortcut or `webstudio mcp single-op-call` commands in a shell loop. Treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one shortcut command such as `webstudio meta.index` or one explicit `webstudio mcp single-op-call` command, report that command/result, then wait for the parent to continue. Do not take a broad task such as creating a full design-system page as one execution unit. Call `workflow.next {"goal":"design-system-page"}`, report the returned phase/checkpoint, wait until the parent continues, call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`, complete exactly that bounded phase, and return: discovery, page creation, one dry-run JSX section, one committed JSX section, one `components.coverage-insert-next` call, or one presentation pass. Phase commands do not include nextPhase in their own output. After the parent continues, acknowledge the previous checkpoint first, then call `workflow.next` with the next phase. For all-component design-system pages, checkpoint after workflow planning, discovery, page creation, call `components.coverage-insert-next` once before checkpointing again, then finish with `workflow.next {"goal":"design-system-page","phase":"presentation-pass"}`. Coverage 72/72 is necessary but not sufficient: the page must be organized into styled, real-world examples, not raw unstyled component dumps.\n- For design-system or “use every component” tasks, start with compact `webstudio components.coverage-plan`, checkpoint, then request component coverage details with `webstudio components.coverage-plan \'{"detail":"roots","offset":20}\'` or `{"detail":"parts"}` only when needed. Do not pass `detail` to `list-pages`; use `list-pages {}` or `get-page-by-path` for page lookup.\n- MCP tool shortcuts are only for MCP tools. If a shortcut is ambiguous with a real top-level command, the real top-level command wins; use `webstudio mcp single-op-call <tool> \'<json>\'` to force the MCP path.\n\n## LLM Implementation Process\n\nUse this process for user requests that change Webstudio content, layout, styles, assets, pages, redirects, resources, or publishing state:\n\n1. Discover capabilities with `webstudio man --json`, `webstudio schema api`, `webstudio schema mcp`, MCP `meta.index`, `meta.guide`, `meta.get_more_tools`, `components.list`, `components.summary`, `components.coverage-plan`, `components.search`, `components.get`, `templates.list`, and `templates.get`. From a shell, prefer shortcut calls such as `webstudio meta.index` and `webstudio components.search \'{"brief":"button"}\'` for these focused tool calls; use `webstudio mcp single-op-call` when you need the explicit MCP form. Read full resources such as `webstudio://project/tools` and `webstudio://project/components` only when needed. Do not write scripts to parse full MCP discovery JSON for normal lookup.\n2. Inspect current project state with semantic reads such as `get-project-settings`, `list-pages`, `get-page-by-path`, `list-instances`, `inspect-instance`, `get-styles`, `list-assets`, `list-breakpoints`, and `snapshot` only when needed. Before changing a project, read `get-project-settings` and follow any non-empty `meta.agentInstructions`. These are shared project instructions, not a place for secrets.\n3. Mutate the Webstudio project with semantic MCP write tools first. Prefer MCP `insert-fragment` for authored/styled sections, use `insert-component` only for one automatic component template, then `update-text`, `update-props`, `update-styles`, `upload-asset`, `create-page`, and page/project settings tools over raw patches.\n4. Use `apply-patch` only when no semantic tool covers the required change, and only after reading the latest snapshot/version.\n5. For visual/design work, regenerate or preview the generated app, capture a screenshot, inspect it with vision, and iterate before final response.\n6. Report what changed and what verification ran.\n\n## Visual Design Workflow\n\nFor requests involving visible HTML/CSS, layout, typography, colors, imagery, responsive behavior, or screenshots:\n\n1. Read editable Webstudio structure first: pages, instances, props, styles, breakpoints, assets, and relevant text.\n2. Do not use generated route/component files as the source of truth for editable content.\n3. Make edits through Webstudio semantic commands/MCP tools so the result stays editable in Builder and survives the next `webstudio build`.\n4. Keep generated project files current, start preview, and capture the changed page with `screenshot`.\n5. Use `screenshot.diff` when a baseline exists and inspect screenshot/diff artifacts with vision before finishing.\n6. If vision or screenshot tooling is unavailable, state that explicitly and explain what fallback verification was used.\n\n## Responsive Verification Workflow\n\nFor responsive page work, use Builder breakpoints as the source of truth:\n\n1. Read breakpoints with `list-breakpoints` before deciding responsive behavior.\n2. Apply responsive styles with existing Builder breakpoint ids; do not invent CSS media queries or breakpoint names when Webstudio breakpoint data exists.\n3. Pick screenshot viewport widths from the project breakpoints: include a desktop width, each defined max-width or min-width edge, and a narrow mobile width.\n4. Capture each viewport with `screenshot`, for example `{"path":"/","output":"home-375.png","viewport":{"width":375,"height":812}}` and `{"path":"/","output":"home-1440.png","viewport":{"width":1440,"height":900}}`.\n5. Inspect every viewport screenshot with vision before finishing, checking layout, overflow, hidden content, text wrapping, and breakpoint-specific style changes.\n6. If any viewport fails, update styles through semantic Webstudio tools and repeat screenshots for the affected breakpoints.\n\n## Generated Files Guardrails\n\n- Do not edit `app/__generated__`, generated route files, generated page files, generated CSS, or build output for normal Webstudio content/design requests.\n- Do not replace generated page components with handcrafted app code unless the user explicitly asks for code-only export customization.\n- Generated files are build artifacts and may be overwritten by `webstudio build`.\n- If a task truly requires generated app customization, keep it outside `app/__generated__` where possible and explain that it is not editable Webstudio content.\n\n## Values vs Bindings\n\nBefore authoring unfamiliar expressions, read `webstudio://project/expressions` with MCP `resources/read` or `webstudio mcp read-resource webstudio://project/expressions`. It documents the supported expression subset, method allowlist, scope, Collection context, and validation limits.\n\n- Use direct value tools for fixed content. For one visible text child, use `update-text` with plain `text`. For a bounded multi-instance literal replacement, use `replace-text` with `find`, `replace`, `pagePath` or `pageId`, and `limit`; it does not change expression children. Use `replace-prop-text` for bounded changes inside static string props, optionally limited to prop names or instance ids; it never changes dynamic bindings. For static props such as `aria-label`, `alt`, `id`, `class`, `href`, or button labels stored as props, use `update-props` with the prop\'s direct type/value.\n- Use `bind-props` only when the prop must stay dynamic: an expression, resource result, action, or existing scoped runtime context such as `system`. Do not use `bind-props` just to set a fixed string.\n- Direct prop string example: `{"updates":[{"instanceId":"button-id","name":"aria-label","type":"string","value":"Open menu"}]}`.\n- Expression binding example: `{"bindings":[{"instanceId":"link-id","name":"href","binding":{"type":"expression","value":"currentPost.url"}}]}`.\n- Page metadata fields such as `title`, `description`, `language`, `redirect`, `status`, and custom meta content accept plain fixed text. For computed values, pass JavaScript expression code such as `pageTitle ?? "Pricing | Acme"`.\n- Page metadata update example: use `update-page` with `{"pageId":"page-id","values":{"title":"Pricing | Acme","meta":{"description":"Plans for teams"}}}`.\n- Resource `url` accepts plain fixed URLs and paths. For computed URLs, pass JavaScript expression code such as `"https://api.example.com/items?tag=" + filters.tag`. Resource header values, search parameter values, and text bodies accept expressions for dynamic values; for fixed text, use `{ "type": "literal", "value": "application/json" }`.\n- Resource update example: use `update-resource` with `{"resourceId":"resource-id","values":{"url":"https://api.example.com/items"}}`.\n- Data variable values support `string`, `number`, `boolean`, `string[]`, and `json`. Use `string[]` only for arrays where every item is a string; use `json` for objects, mixed arrays, filters, and nested data.\n- Parameters are internal scoped runtime values from pages, collections, or components. They are not a public authoring surface: do not create, update, or delete parameter records. Public tools should preserve existing parameter records and may reference documented context values such as `system` in expressions where they are already in scope.\n- Use scoped resources for read data. A GET resource created with `scopeInstanceId`/`dataSourceName` defaults to `exposeAsDataSource:true`, becomes a scoped resource data variable, is generated into the page resource `data` map, and may be loaded while rendering the page. Read the loaded resource result from its wrapper, usually `.data`.\n- Use prop-bound resources for actions. A resource created without `scopeInstanceId` and bound to a component prop such as Form `action` with `bind-props` and `binding.type: "resource"` becomes an action resource in the page resource `action` map. Use this for POST, PUT, DELETE, webhooks, GraphQL submissions, and anything that should run only from an explicit form/action flow.\n- POST, PUT, and DELETE resources default to `exposeAsDataSource:false`, even with a scope. Set `exposeAsDataSource:true` only for an intentional render-time read such as a GraphQL POST query; provide `scopeInstanceId` and inspect the returned warning. Set it to `false` during `update-resource` to detach existing render-time exposure.\n- For dynamic resource query parameters prefer `searchParams`, for example `{"name":"tag","value":"filters.tag"}`. Use `{"type":"literal","value":"website"}` for fixed request text. Header values can be expressions such as `"\\"Bearer \\" + auth.token"`. Body can be an object expression, including GraphQL payloads such as `{ query: "...", variables: { slug: system.params.slug } }`.\n- Resource methods are `get`, `post`, `put`, and `delete`. Optional resource controls are `graphql` and `system`. Use `control:"graphql"` for GraphQL POST resources with query bodies. Use `control:"system"` for built-in local resource URLs such as `"/$resources/current-date"` and for resources reading the built-in `system` parameter. The built-in system fields are `system.origin`, `system.pathname`, `system.params`, and `system.search`; do not use `system.path`.\n- Whenever an array or object from a resource or data variable should render repeated UI, call `insert-collection` with the complete iterable and one repeated-item JSX root. The command creates the Collection, private item parameters, iterable binding, and descendant item bindings atomically. Use `collectionItem` and `collectionItemKey` expressions in the item JSX. Wrap multiple repeated siblings in one Element, and give repeated Radix items stable unique `value` bindings.\n- Expressions are single JavaScript expressions, not statements or functions. Functions, arrow functions, classes, `new`, `this`, `await`, imports, arbitrary calls, increment/decrement, and assignment outside actions are unsupported. Prefer optional chaining, nullish coalescing, ternaries, property/index access, operators, and the documented string/array methods.\n\n## Pick Read Command\n\n{{readFirst}}\n\n## Pick Write Command\n\n{{taskRecipeIndex}}\n\n## Raw Patch Only If Needed\n\n1. Use MCP tool: snapshot.\n2. Write BuildPatchTransaction[].\n3. Use MCP tool: apply-patch.\n\n## MCP Argument Examples\n\nMCP tools receive JSON argument objects, not CLI flags. Use these shapes:\n\n{{mcpArgumentExampleIndex}}\n\n## Rules\n\n- Never guess ids for existing records. Read them first.\n- Never use project ids from user input. Commands use the configured project.\n- Use --refresh before a local-capable command when cached data may be stale.\n- Pass --json only to commands whose help/schema documents it. Do not add --json to top-level commands such as sync unless supported.\n- On VERSION_CONFLICT, read MCP snapshot again, regenerate the patch, then retry.\n- Treat stdout JSON as the API contract and stderr as diagnostics.\n- For visual/design work, verify the rendered result with vision before finishing.\n- Do not edit generated files for normal Webstudio content/design requests.\n- Use direct values for static strings and bindings only for dynamic expressions/resources/actions.\n- Use plain fixed text where documented. Only encode a quoted JavaScript string literal when a field is explicitly documented as an expression-only value.\n- Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.\n- Use webstudio schema api for machine-readable top-level command metadata and webstudio schema mcp for MCP tool schemas.\n\n## Known Gaps\n\n{{knownCliGapIndex}}\n',
+ '# Webstudio CLI Manual for LLMs\n\nUse this order. Stop only when a command returns ok:false.\n\nIf you are inside the Webstudio monorepo, the first command discovery should use\nthe local CLI exactly as `node packages/cli/local.js ...` from the repo root. Do\nnot use `packages/cli/bin.js` for local source-tree work; it is the packaged\nbuild entry and may use stale built output. Do not use `pnpm exec webstudio`,\n`pnpm --filter webstudio exec webstudio`, or a global `webstudio`: they can\nresolve an older binary.\n\nFor delegated design-system or “use every component” tasks, skip the generic warm-up sequence and start with exactly one MCP command: `webstudio workflow.next \'{"goal":"design-system-page"}\'`. Report that returned checkpoint to the parent/user and stop until continued.\n\n## Always\n\n1. webstudio permissions --json\n2. For bounded shell workflows, call MCP tools directly through the CLI shortcut, for example `webstudio meta.index` or `webstudio insert-fragment \'<json>\' --dry-run`. The explicit form `webstudio mcp single-op-call <tool> \'<json>\'` is equivalent and useful when you need to make the MCP boundary obvious. Use `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'` for multiple calls in one shared CLI session. Use a normal JSON file path for large batches. Use long-running `webstudio mcp` only when your environment is a real MCP client. Do not manually send raw JSON-RPC to `webstudio mcp` from a shell or PTY.\n3. Read MCP `meta.index`, for example `webstudio meta.index`.\n4. Use focused MCP calls with concrete JSON: `webstudio meta.guide \'{"brief":"Create a design system page using every component"}\'`, `webstudio meta.get_more_tools \'{"tools":["insert-fragment"]}\'`, `webstudio components.list \'{"source":"all"}\'`, `webstudio components.coverage-plan`, `webstudio components.search \'{"brief":"radix select"}\'`, `webstudio components.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'`, `webstudio templates.list`, and `webstudio templates.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'`.\n5. Read overview resources `webstudio://project/tools-overview` or `webstudio://project/components-overview` when useful. Read full resources `webstudio://project/tools` or `webstudio://project/components` only when focused tools are insufficient.\n6. Pick focused MCP read tool.\n7. Pick semantic MCP write tool.\n\nUse `webstudio schema mcp` for a compact MCP tool overview. Add `--verbose` only when exact input schemas for all tools are truly needed; otherwise prefer focused `meta.get_more_tools` and `components.*` calls.\n\nRun these commands from the linked project root. Use the MCP startup status line\'s absolute root for local files; write temporary scripts and artifacts under `<project root>/.temp`, not under a parent workspace.\n\nMonorepo quick path for a simple styled section:\n\n```sh\nnode packages/cli/local.js mcp single-op-call meta.index\nnode packages/cli/local.js mcp single-op-call meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nnode packages/cli/local.js mcp single-op-call insert-fragment \'{"parentInstanceId":"parent-id","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px; display: grid; gap: 12px;`}><ws.element ws:tag="h2">Launch Kit</ws.element><ws.element ws:tag="p">A focused section created with Webstudio JSX.</ws.element><ws.element ws:tag="button">Get started</ws.element></ws.element>"}\' --dry-run\n```\n\nThe same local shortcut form is shorter and preferred for simple shell steps:\n\n```sh\nnode packages/cli/local.js meta.index\nnode packages/cli/local.js meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nnode packages/cli/local.js insert-fragment \'{"parentInstanceId":"parent-id","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px; display: grid; gap: 12px;`}><ws.element ws:tag="h2">Launch Kit</ws.element><ws.element ws:tag="p">A focused section created with Webstudio JSX.</ws.element><ws.element ws:tag="button">Get started</ws.element></ws.element>"}\' --dry-run\n```\n\nFor this simple path, do not grep source files, dump full MCP resources, or write parser scripts first. Use `list-pages`, `get-page-by-path`, or `list-instances` only to get the target `parentInstanceId`.\n\nWhen authoring JSX for `insert-fragment`, use Webstudio component helpers and Webstudio style syntax. Use `ws:style={css\\`...\\`}`for Webstudio-native CSS, or use React-style object syntax such as`style={{ padding: 24 }}` when that is simpler. Both forms create editable Webstudio style data.\n\nWhen the task says another user will edit a page in Content mode, use a Content Block (`ws:block`) around every editable region. Content-mode users can edit text and supported props only in descendants of that block; content outside it is read-only. Put reusable insertable options in the block\'s `ws:block-template` child. Do not put intended editor content inside that template container: templates are protected source material, while an inserted template copy becomes an editable direct child of the Content Block. Verify this structure before handoff.\n\nDo not access host globals or dynamic code APIs in JSX fragments, including `process`, `globalThis`, `eval`, `Function`, or `constructor`. JSX fragments are declarative project data; use the built-in Webstudio helpers instead.\n\nUse Webstudio prop names in JSX: `class`, `for`, `aria-label`, and other HTML/Webstudio names. Do not use React-only aliases such as `className` or `htmlFor`; the runtime rejects them with the Webstudio prop name to use.\n\nUse Webstudio actions for event/action props. Do not pass JavaScript functions such as `onClick={() => ...}`; the runtime rejects them because functions cannot be persisted as Webstudio project data.\n\n```tsx\n<ws.element\n ws:tag="button"\n onClick={new ActionValue(["event"], expression`console.log(event)`)}\n>\n Open\n</ws.element>\n```\n\nPlain JSX prop values must be JSON-compatible: `null`, strings, booleans, finite numbers, arrays, and plain objects. Do not pass `undefined`, `Symbol`, `BigInt`, `NaN`, `Infinity`, `Date`, `Map`, `Set`, class instances, or circular objects; omit the prop, use plain data, or use `expression`/`ActionValue` when the value is dynamic.\n\nIf a component has a registered template with required parts, JSX must include those parts explicitly under the same parent structure as the template, for example `<radix.Switch><radix.SwitchThumb /></radix.Switch>`. Use `insert-component` when you want Webstudio to apply one component template automatically.\n\n## Animation Components\n\nBefore creating animation examples, inspect the exact components with focused discovery:\n\n```sh\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:AnimateChildren"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:AnimateText"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:StaggerAnimation"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-animation:VideoAnimation"}\'\n```\n\nUse Animation Group (`AnimateChildren`) as the controller. Put normal instances directly inside it, or put Text Animation, Stagger Animation, or Video Animation directly inside it. Text, Stagger, and Video are helper components with `contentModel.category: "none"` and should not be used as standalone section roots.\n\nDefine timing and CSS changes on the Animation Group `action` prop. Use `type:"view"` for viewport entry/exit progress and `type:"scroll"` for scroll-progress timelines. For in animations, keep the canvas styles as the final state and use `fill:"backwards"` with keyframes that describe the starting state. For out animations, use `fill:"forwards"` with keyframes that describe the ending state.\n\nText Animation settings: `slidingWindow` defaults to `5`, `easing` defaults to `linear`, and `splitBy` defaults to `char`. Use `splitBy:"space"` for word-by-word animation. The parent Animation Group keyframes provide the actual opacity, translate, scale, or other styles.\n\nStagger Animation settings: `slidingWindow` defaults to `1` and `easing` defaults to `linear`. It applies parent Animation Group progress across its direct children. Use `slidingWindow:0` for instant sequential steps, `1` for one child at a time, and values above `1` for overlapping waves.\n\nVideo Animation settings: `timeline` is a boolean. Prefer `insert-component` for Video Animation so the Video child template is inserted, then configure the Video child asset/source. Use short, seek-friendly videos for smooth scroll-linked playback.\n\nUse JSX fragments for authored animation structures when you need styled, editable examples. Put the final visual state in `ws:style` and put the starting or ending animated state in the Animation Group `action` keyframes. Include an explicit `offset` on every keyframe: use `offset: 0` for starting-state keyframes with `fill:"backwards"` and `offset: 1` for ending-state keyframes with `fill:"forwards"`.\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n axis: "block",\n animations: [\n {\n name: "Fade up on entry",\n timing: {\n fill: "backwards",\n rangeStart: ["entry", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["entry", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: 24, unit: "px" },\n ],\n },\n },\n },\n ],\n },\n ],\n }}\n>\n <ws.element\n ws:tag="section"\n ws:style={css`\n display: grid;\n gap: 16px;\n padding: 48px;\n border-radius: 24px;\n background: #111827;\n color: white;\n `}\n >\n <ws.element ws:tag="h2">Launch metrics</ws.element>\n <ws.element ws:tag="p">\n A polished card that fades up as it enters the viewport.\n </ws.element>\n </ws.element>\n</animation.AnimateChildren>\n```\n\nFor Text Animation, keep `animation.AnimateText` as the direct child of Animation Group and place the text-containing element inside it:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n name: "Parallax In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: 100, unit: "px" },\n ],\n },\n },\n },\n ],\n },\n {\n name: "Opacity In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n {\n name: "Scale In",\n timing: {\n fill: "backwards",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 70, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n scale: {\n type: "tuple",\n value: [\n { type: "unit", value: 5, unit: "number" },\n { type: "unit", value: 5, unit: "number" },\n ],\n },\n },\n },\n ],\n },\n {\n name: "Parallax Out",\n timing: {\n fill: "forwards",\n rangeStart: ["cover", { type: "unit", value: 50, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [\n {\n offset: 1,\n styles: {\n translate: {\n type: "tuple",\n value: [\n { type: "unit", value: 0, unit: "number" },\n { type: "unit", value: -100, unit: "px" },\n ],\n },\n scale: {\n type: "tuple",\n value: [\n { type: "unit", value: 5, unit: "number" },\n { type: "unit", value: 5, unit: "number" },\n ],\n },\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n ],\n insetStart: { type: "unit", value: 5, unit: "%" },\n insetEnd: { type: "unit", value: 5, unit: "%" },\n isPinned: true,\n }}\n>\n <animation.AnimateText\n splitBy="space"\n slidingWindow={5}\n easing="easeOutQuart"\n >\n <ws.element ws:tag="h2">Animate words with controlled rhythm</ws.element>\n </animation.AnimateText>\n</animation.AnimateChildren>\n```\n\nFor Stagger Animation, put the repeated cards or rows directly inside `animation.StaggerAnimation`:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n timing: {\n fill: "backwards",\n rangeStart: ["contain", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["contain", { type: "unit", value: 30, unit: "%" }],\n },\n keyframes: [\n {\n offset: 0,\n styles: {\n opacity: { type: "unit", value: 0, unit: "number" },\n },\n },\n ],\n },\n ],\n }}\n>\n <animation.StaggerAnimation>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Plan\n </ws.element>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Build\n </ws.element>\n <ws.element\n ws:tag="article"\n ws:style={css`\n padding: 20px;\n border: 1px solid #d1d5db;\n border-radius: 16px;\n `}\n >\n Launch\n </ws.element>\n </animation.StaggerAnimation>\n</animation.AnimateChildren>\n```\n\nFor Video Animation, use the registered template via `insert-component` when possible. If you author JSX, include the Video child explicitly:\n\n```tsx\n<animation.AnimateChildren\n action={{\n type: "view",\n animations: [\n {\n name: "Video progress",\n timing: {\n fill: "both",\n rangeStart: ["cover", { type: "unit", value: 0, unit: "%" }],\n rangeEnd: ["cover", { type: "unit", value: 100, unit: "%" }],\n },\n keyframes: [{ offset: 0, styles: {} }],\n },\n ],\n }}\n>\n <animation.VideoAnimation timeline={true}>\n <$.Video\n preload="auto"\n autoPlay={true}\n muted={true}\n playsInline={true}\n crossOrigin="anonymous"\n />\n </animation.VideoAnimation>\n</animation.AnimateChildren>\n```\n\n## Command Surface Boundary\n\n- Use top-level `webstudio ...` shell commands for setup, sync/import/build/preview/screenshot, permissions, publish/domains, schema, registry inspection, man, and starting MCP.\n- Use MCP tools for Builder project data manipulation: pages, instances/components, props, text, styles, tokens, variables, resources, assets, breakpoints, redirects, and raw patches.\n- From a shell, call MCP tools with the shortcut form `webstudio <tool> \'<json>\'`, for example `webstudio insert-fragment \'<json>\' --dry-run`. The explicit equivalent is `webstudio mcp single-op-call <tool> \'<json>\'`. Use `--input-file` for large payloads.\n- Inside the Webstudio monorepo, call the local CLI as its own command: `node packages/cli/local.js ...`. Do not wrap the CLI call in `pwd && ...`, command substitution, `pnpm exec webstudio`, `pnpm --filter webstudio exec webstudio`, or a global `webstudio`.\n- For experiments, pass `--dry-run` to local-capable mutation calls. Read the computed transaction from `meta.session.transaction` and its base build version from `meta.session.version`. Copying a `.webstudio` folder is not an isolated project clone; `.webstudio/config.json` still points to the same remote project, so non-dry-run mutations can commit to that project.\n- For bounded multi-step shell work, run inline JSON with `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'`; this reuses one CLI session without raw JSON-RPC. For large batches, write `{ "calls": [{ "tool": "..." }] }` to a normal JSON file and run `webstudio mcp run .temp/mcp-calls.json`.\n- Use JSON strings for `brief` fields. Never pass boolean flags such as `{"brief":true}`.\n- Treat `webstudio mcp single-op-call` and `webstudio mcp run` stderr lines as progress checkpoints; stdout remains JSON on both success and failure. On failure, parse stdout for `{ "ok": false, "error": { "code": "...", "message": "..." } }` before deciding what to fix.\n- If a CLI/MCP tool crashes, hangs, gives a confusing error, needs an undocumented workaround, or forces source-code inspection for normal usage, ask the user to report it in Discord `#help` at https://wstd.us/community. Give them a complete copy-paste report with the goal, expected behavior, actual error, exact command/tool call, stdout JSON, stderr/lifecycle logs, environment, workaround, and secrets redacted.\n- Run one-shot `webstudio mcp single-op-call` commands sequentially against a linked `.webstudio` folder. If a command returns `PROJECT_SESSION_BUSY`, another CLI/MCP process is updating the local session; wait a moment and retry sequentially.\n- In delegated or non-streaming agent environments, do not batch many MCP calls silently and do not wrap many shortcut or `webstudio mcp single-op-call` commands in a shell loop. Treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one shortcut command such as `webstudio meta.index` or one explicit `webstudio mcp single-op-call` command, report that command/result, then wait for the parent to continue. Do not take a broad task such as creating a full design-system page as one execution unit. Call `workflow.next {"goal":"design-system-page"}`, report the returned phase/checkpoint, wait until the parent continues, call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`, complete exactly that bounded phase, and return: discovery, page creation, one dry-run JSX section, one committed JSX section, one `components.coverage-insert-next` call, or one presentation pass. Phase commands do not include nextPhase in their own output. After the parent continues, acknowledge the previous checkpoint first, then call `workflow.next` with the next phase. For all-component design-system pages, checkpoint after workflow planning, discovery, page creation, call `components.coverage-insert-next` once before checkpointing again, then finish with `workflow.next {"goal":"design-system-page","phase":"presentation-pass"}`. Coverage 72/72 is necessary but not sufficient: the page must be organized into styled, real-world examples, not raw unstyled component dumps.\n- For design-system or “use every component” tasks, start with compact `webstudio components.coverage-plan`, checkpoint, then request component coverage details with `webstudio components.coverage-plan \'{"detail":"roots","offset":20}\'` or `{"detail":"parts"}` only when needed. Do not pass `detail` to `list-pages`; use `list-pages {}` or `get-page-by-path` for page lookup.\n- MCP tool shortcuts are only for MCP tools. If a shortcut is ambiguous with a real top-level command, the real top-level command wins; use `webstudio mcp single-op-call <tool> \'<json>\'` to force the MCP path.\n\n## LLM Implementation Process\n\nUse this process for user requests that change Webstudio content, layout, styles, assets, pages, redirects, resources, or publishing state:\n\n1. Discover capabilities with `webstudio man --json`, `webstudio schema api`, `webstudio schema mcp`, MCP `meta.index`, `meta.guide`, `meta.get_more_tools`, `components.list`, `components.summary`, `components.coverage-plan`, `components.search`, `components.get`, `templates.list`, and `templates.get`. From a shell, prefer shortcut calls such as `webstudio meta.index` and `webstudio components.search \'{"brief":"button"}\'` for these focused tool calls; use `webstudio mcp single-op-call` when you need the explicit MCP form. Read full resources such as `webstudio://project/tools` and `webstudio://project/components` only when needed. Do not write scripts to parse full MCP discovery JSON for normal lookup.\n2. Inspect current project state with semantic reads such as `get-project-settings`, `list-pages`, `get-page-by-path`, `list-instances`, `inspect-instance`, `get-styles`, `list-assets`, `list-breakpoints`, and `snapshot` only when needed. Before changing a project, read `get-project-settings` and follow any non-empty `meta.agentInstructions`. These are shared project instructions, not a place for secrets.\n3. Mutate the Webstudio project with semantic MCP write tools first. Prefer MCP `insert-fragment` for authored/styled sections, use `insert-component` only for one automatic component template, then `update-text`, `update-props`, `update-styles`, `upload-asset`, `create-page`, and page/project settings tools over raw patches.\n4. Use `apply-patch` only when no semantic tool covers the required change, and only after reading the latest snapshot/version.\n5. For visual/design work, regenerate or preview the generated app, capture a screenshot, inspect it with vision, and iterate before final response.\n6. Report what changed and what verification ran.\n\n## Visual Design Workflow\n\nFor requests involving visible HTML/CSS, layout, typography, colors, imagery, responsive behavior, or screenshots:\n\n1. Read editable Webstudio structure first: pages, instances, props, styles, breakpoints, assets, and relevant text.\n2. Do not use generated route/component files as the source of truth for editable content.\n3. Make edits through Webstudio semantic commands/MCP tools so the result stays editable in Builder and survives the next `webstudio build`.\n4. Keep generated project files current, start preview, and capture the changed page with `screenshot`.\n5. Use `screenshot.diff` when a baseline exists and inspect screenshot/diff artifacts with vision before finishing.\n6. If vision or screenshot tooling is unavailable, state that explicitly and explain what fallback verification was used.\n\n## Responsive Verification Workflow\n\nFor responsive page work, use Builder breakpoints as the source of truth:\n\n1. Read breakpoints with `list-breakpoints` before deciding responsive behavior.\n2. Apply responsive styles with existing Builder breakpoint ids; do not invent CSS media queries or breakpoint names when Webstudio breakpoint data exists.\n3. Pick screenshot viewport widths from the project breakpoints: include a desktop width, each defined max-width or min-width edge, and a narrow mobile width.\n4. Capture each viewport with `screenshot`, for example `{"path":"/","output":"home-375.png","viewport":{"width":375,"height":812}}` and `{"path":"/","output":"home-1440.png","viewport":{"width":1440,"height":900}}`.\n5. Inspect every viewport screenshot with vision before finishing, checking layout, overflow, hidden content, text wrapping, and breakpoint-specific style changes.\n6. If any viewport fails, update styles through semantic Webstudio tools and repeat screenshots for the affected breakpoints.\n\n## Generated Files Guardrails\n\n- Do not edit `app/__generated__`, generated route files, generated page files, generated CSS, or build output for normal Webstudio content/design requests.\n- Do not replace generated page components with handcrafted app code unless the user explicitly asks for code-only export customization.\n- Generated files are build artifacts and may be overwritten by `webstudio build`.\n- If a task truly requires generated app customization, keep it outside `app/__generated__` where possible and explain that it is not editable Webstudio content.\n\n## Values vs Bindings\n\nBefore authoring unfamiliar expressions, read `webstudio://project/expressions` with MCP `resources/read` or `webstudio mcp read-resource webstudio://project/expressions`. It documents the supported expression subset, method allowlist, scope, Collection context, and validation limits.\n\n- Use direct value tools for fixed content. For one visible text child, use `update-text` with plain `text`. For a bounded multi-instance literal replacement, use `replace-text` with `find`, `replace`, `pagePath` or `pageId`, and `limit`; it does not change expression children. Use `replace-prop-text` for bounded changes inside static string props, optionally limited to prop names or instance ids; it never changes dynamic bindings. For static props such as `aria-label`, `alt`, `id`, `class`, `href`, or button labels stored as props, use `update-props` with the prop\'s direct type/value.\n- Use `bind-props` only when the prop must stay dynamic: an expression, resource result, action, or existing scoped runtime context such as `system`. Do not use `bind-props` just to set a fixed string.\n- Direct prop string example: `{"updates":[{"instanceId":"button-id","name":"aria-label","type":"string","value":"Open menu"}]}`.\n- Expression binding example: `{"bindings":[{"instanceId":"link-id","name":"href","binding":{"type":"expression","value":"currentPost.url"}}]}`.\n- Page metadata fields such as `title`, `description`, `language`, `redirect`, `status`, and custom meta content accept plain fixed text. For computed values, pass JavaScript expression code such as `pageTitle ?? "Pricing | Acme"`.\n- Page metadata update example: use `update-page` with `{"pageId":"page-id","values":{"title":"Pricing | Acme","meta":{"description":"Plans for teams"}}}`.\n- Resource `url` accepts plain fixed URLs and paths. For computed URLs, pass JavaScript expression code such as `"https://api.example.com/items?tag=" + filters.tag`. Resource header values, search parameter values, and text bodies accept expressions for dynamic values; for fixed text, use `{ "type": "literal", "value": "application/json" }`.\n- Resource update example: use `update-resource` with `{"resourceId":"resource-id","values":{"url":"https://api.example.com/items"}}`.\n- Data variable values support `string`, `number`, `boolean`, `string[]`, and `json`. Use `string[]` only for arrays where every item is a string; use `json` for objects, mixed arrays, filters, and nested data.\n- Parameters are internal scoped runtime values from pages, collections, or components. They are not a public authoring surface: do not create, update, or delete parameter records. Public tools should preserve existing parameter records and may reference documented context values such as `system` in expressions where they are already in scope.\n- Use scoped resources for read data. A GET resource created with `scopeInstanceId`/`dataSourceName` defaults to `exposeAsDataSource:true`, becomes a scoped resource data variable, is generated into the page resource `data` map, and may be loaded while rendering the page. Read the loaded resource result from its wrapper, usually `.data`.\n- Use prop-bound resources for actions. A resource created without `scopeInstanceId` and bound to a component prop such as Form `action` with `bind-props` and `binding.type: "resource"` becomes an action resource in the page resource `action` map. Use this for POST, PUT, DELETE, webhooks, GraphQL submissions, and anything that should run only from an explicit form/action flow.\n- POST, PUT, and DELETE resources default to `exposeAsDataSource:false`, even with a scope. Set `exposeAsDataSource:true` only for an intentional render-time read such as a GraphQL POST query; provide `scopeInstanceId` and inspect the returned warning. Set it to `false` during `update-resource` to detach existing render-time exposure.\n- For dynamic resource query parameters prefer `searchParams`, for example `{"name":"tag","value":"filters.tag"}`. Use `{"type":"literal","value":"website"}` for fixed request text. Header values can be expressions such as `"\\"Bearer \\" + auth.token"`. Body can be an object expression, including GraphQL payloads such as `{ query: "...", variables: { slug: system.params.slug } }`.\n- Resource methods are `get`, `post`, `put`, and `delete`. Optional resource controls are `graphql` and `system`. Use `control:"graphql"` for GraphQL POST resources with query bodies. Use `control:"system"` for built-in local resource URLs such as `"/$resources/current-date"` and for resources reading the built-in `system` parameter. The built-in system fields are `system.origin`, `system.pathname`, `system.params`, and `system.search`; do not use `system.path`.\n- Whenever an array or object from a resource or data variable should render repeated UI, call `insert-collection` with the complete iterable and one repeated-item JSX root. The command creates the Collection, private item parameters, iterable binding, and descendant item bindings atomically. Use `collectionItem` and `collectionItemKey` expressions in the item JSX. Wrap multiple repeated siblings in one Element, and give repeated Radix items stable unique `value` bindings.\n- Expressions are single JavaScript expressions, not statements or functions. Functions, arrow functions, classes, `new`, `this`, `await`, imports, arbitrary calls, increment/decrement, and assignment outside actions are unsupported. Prefer optional chaining, nullish coalescing, ternaries, property/index access, operators, and the documented string/array methods.\n\n## Pick Read Command\n\n{{readFirst}}\n\n## Pick Write Command\n\n{{taskRecipeIndex}}\n\n## Raw Patch Only If Needed\n\n1. Use MCP tool: snapshot.\n2. Write BuildPatchTransaction[].\n3. Use MCP tool: apply-patch.\n\n## MCP Argument Examples\n\nMCP tools receive JSON argument objects, not CLI flags. Use these shapes:\n\n{{mcpArgumentExampleIndex}}\n\n## Rules\n\n- Never guess ids for existing records. Read them first.\n- Never use project ids from user input. Commands use the configured project.\n- Use --refresh before a local-capable command when cached data may be stale.\n- Pass --json only to commands whose help/schema documents it. Do not add --json to top-level commands such as sync unless supported.\n- On VERSION_CONFLICT, read MCP snapshot again, regenerate the patch, then retry.\n- Treat stdout JSON as the API contract and stderr as diagnostics.\n- For visual/design work, verify the rendered result with vision before finishing.\n- Do not edit generated files for normal Webstudio content/design requests.\n- Use direct values for static strings and bindings only for dynamic expressions/resources/actions.\n- Use plain fixed text where documented. Only encode a quoted JavaScript string literal when a field is explicitly documented as an expression-only value.\n- Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.\n- Use webstudio schema api for machine-readable top-level command metadata and webstudio schema mcp for MCP tool schemas.\n\n## Known Gaps\n\n{{knownCliGapIndex}}\n',
"manual-mcp":
'# Webstudio MCP Manual\n\n`webstudio mcp` starts a stdio MCP server for real MCP clients. Shell users can call MCP tools with the shortcut form `webstudio <tool> \'<json>\'`, for example `webstudio meta.index` or `webstudio insert-fragment \'<json>\' --dry-run`. `webstudio mcp single-op-call` is the explicit equivalent and prints the structured JSON result. `webstudio mcp run` runs multiple MCP tool calls from inline JSON or a normal JSON file in one shared CLI session. Do not manually type or pipe raw JSON-RPC frames into `webstudio mcp` from an interactive shell or PTY.\n\n## Startup\n\n1. Configure a project with `webstudio init --link <api-share-link> --json`.\n2. Generate the client configuration with `webstudio connect claude`,\n `webstudio connect codex`, `webstudio connect cursor`, or\n `webstudio connect vscode`. Use `--print` to preview file-based config.\n3. Check capabilities with `webstudio permissions --json`.\n4. For shell-driven agents, use shortcut calls such as `webstudio meta.index` and `webstudio insert-fragment \'<json>\' --dry-run` for individual MCP tool calls. Use the explicit equivalent `webstudio mcp single-op-call <tool> \'<json>\'` when you need to force the MCP path, or `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'` for bounded multi-call workflows. Use `webstudio mcp run .temp/mcp-calls.json` for large batches.\n5. For MCP clients, start the server with `webstudio mcp`.\n6. Start discovery with `meta.index`, then call focused tools with concrete JSON, for example `webstudio mcp single-op-call meta.guide \'{"brief":"Create a design system page using every component"}\'`.\n\nStart MCP from the linked Webstudio project root. The lifecycle status line prints that absolute root; create local scripts, screenshots, and temporary artifacts under that root, for example `<project root>/.temp/script.mjs`. If the shell starts in a parent workspace, `cd` into the project root first or use absolute paths.\n\nWhen developing inside the Webstudio monorepo, start the local CLI exactly as `node packages/cli/local.js mcp` from the repo root. Do not use `pnpm exec webstudio`, `pnpm --filter webstudio exec webstudio`, or a global `webstudio`: they can resolve an older binary.\n\nWhile the server is running, stdout is reserved for MCP JSON-RPC messages. Do not print human text from the server process. The server advertises MCP `logging` capability and emits sparse `notifications/message` logs for ready state and tool lifecycle checkpoints such as `tool preview.start started`, `tool preview.start still running after 10000ms`, and `tool preview.start succeeded in 1234ms`; stderr also mirrors these sparse lifecycle fallback lines prefixed with `[webstudio mcp]`.\n\n## One-Shot Tool Calls\n\nUse the shortcut `webstudio <tool> \'<json>\'` when you are operating from a shell and need one MCP tool result. The explicit form `webstudio mcp single-op-call <tool> \'<json>\'` is equivalent and avoids writing temporary Node.js stdio client scripts.\n\nExamples:\n\n```sh\nwebstudio mcp single-op-call meta.index\nwebstudio mcp single-op-call meta.guide \'{"brief":"Create a design system page using every component"}\'\nwebstudio mcp single-op-call meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nwebstudio mcp single-op-call components.list \'{"source":"all"}\'\nwebstudio mcp single-op-call components.coverage-plan\nwebstudio mcp single-op-call components.search \'{"brief":"radix select"}\'\nwebstudio mcp single-op-call components.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'\nwebstudio mcp single-op-call templates.list\nwebstudio mcp single-op-call templates.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'\nwebstudio mcp single-op-call insert-fragment --input-file .temp/insert-fragment.json\n```\n\nShortcut equivalents:\n\n```sh\nwebstudio meta.index\nwebstudio meta.guide \'{"brief":"Create a design system page using every component"}\'\nwebstudio meta.get_more_tools \'{"tools":["insert-fragment"]}\'\nwebstudio components.list \'{"source":"all"}\'\nwebstudio components.coverage-plan\nwebstudio components.search \'{"brief":"radix select"}\'\nwebstudio components.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'\nwebstudio templates.list\nwebstudio templates.get \'{"component":"@webstudio-is/sdk-components-react-radix:Select"}\'\nwebstudio insert-fragment --input-file .temp/insert-fragment.json\n```\n\nRules:\n\n- Inside the Webstudio monorepo, replace `webstudio` in the examples above with `node packages/cli/local.js`, for example `node packages/cli/local.js meta.index`.\n- For a simple authored/styled section, run `meta.index`, then `meta.get_more_tools \'{"tools":["insert-fragment"]}\'`, then `insert-fragment`. Do not grep source files, dump full MCP resources, or write parser scripts first.\n- In `insert-fragment` JSX, use `ws:style={css\\`...\\`}`for Webstudio-native CSS, or use React-style object syntax such as`style={{ padding: 24 }}` when that is simpler. Both forms create editable Webstudio style data.\n- Prefer JSX for authored/styled content. Common `insert-fragment` inputs:\n\n```jsonl\n{"parentInstanceId":"root-id","fragment":"<ws.element ws:tag=\\"section\\" ws:style={css`padding: 32px; display: grid; gap: 16px;`}><ws.element ws:tag="h2">Northstar Product OS</ws.element><ws.element ws:tag="p">Reusable patterns for teams.</ws.element></ws.element>"}\n{"parentInstanceId":"root-id","fragment":"<ws.element ws:tag=\\"section\\" style={{ padding: 32, borderRadius: 16 }}><ws.element ws:tag="h2">Operations Console</ws.element><ws.element ws:tag="p">React-style object styles become editable Webstudio styles.</ws.element></ws.element>"}\n{"parentInstanceId":"root-id","fragment":"<ws.element ws:tag=\\"section\\" ws:tokens={[token(\\"accent\\", css`color: #0f766e;`)]}><ws.element ws:tag="button" onClick={new ActionValue([\\"event\\"], expression`console.log(event)`)}>Track launch</ws.element></ws.element>"}\n{"parentInstanceId":"root-id","fragment":"<ws.element ws:tag=\\"section\\"><radix.Switch><radix.SwitchThumb /></radix.Switch></ws.element>"}\n```\n\n- Do not access host globals or dynamic code APIs in JSX fragments, including `process`, `globalThis`, `eval`, `Function`, or `constructor`.\n- Use Webstudio prop names such as `class` and `for`; do not use React aliases `className` or `htmlFor`.\n- Use Webstudio actions for event/action props, for example `onClick={new ActionValue(["event"], expression\\`console.log(event)\\`)}`. Do not pass JavaScript functions such as `onClick={() => ...}`.\n- Plain prop values must be JSON-compatible: `null`, strings, booleans, finite numbers, arrays, and plain objects. Do not pass `undefined`, `Symbol`, `BigInt`, `NaN`, `Infinity`, `Date`, `Map`, `Set`, class instances, or circular objects; omit the prop, use plain data, or use `expression`/`ActionValue` when the value is dynamic.\n- Template-backed components used in JSX must include required child/part components explicitly under the same parent structure as the template, for example `<radix.Switch><radix.SwitchThumb /></radix.Switch>`. Use `insert-component` when you want one automatic registered component template.\n- The positional input is JSON and defaults to `{}`.\n- Use `--input-file` for large mutation payloads.\n- Use `--dry-run` with local-capable mutation tools when you need a patch plan without committing. The computed transaction is returned in `meta.session.transaction`, and `meta.session.version` is its base build version. Copying a `.webstudio` folder is not an isolated project clone; `.webstudio/config.json` still points to the same remote project, so non-dry-run mutations can commit to that project.\n- The command prints JSON to stdout for both success and failure. Success uses the same `structuredContent` shape MCP tools return: `{ "ok": true, "data": ..., "meta": ... }`. Failure prints `{ "ok": false, "error": { "code": "...", "message": "..." }, "meta": ... }` and exits nonzero.\n- The command writes sparse progress to stderr, including start, success/failure, elapsed time, and committed status when the tool returns session metadata.\n- Invalid argument types fail loudly with path-specific messages, for example `meta.guide input.brief must be a string when provided`.\n- Run one-shot shortcut or `mcp single-op-call` commands sequentially against the same linked `.webstudio` folder. If you receive `PROJECT_SESSION_BUSY`, another CLI/MCP process is updating the local session; wait a moment and retry sequentially.\n- If you are a delegated agent and your parent cannot see live stderr/stdout, do not run a long sequence of shortcut or `mcp single-op-call` commands silently and do not wrap many calls in a shell loop. Treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one `webstudio <tool>` or `webstudio mcp single-op-call` command, report that command/result, then wait before the next MCP command. For all-component design-system pages, checkpoint after discovery, checkpoint after page creation, call `components.coverage-insert-next` once before checkpointing again, then finish with the `presentation-pass` workflow phase. Coverage alone is not completion; organize examples into styled sections/cards.\n\n## Reporting CLI/MCP Issues\n\nIf a CLI/MCP tool gives a confusing error, crashes, hangs, produces invalid output, requires an undocumented workaround, or makes you inspect source code to understand normal usage, ask the user to report it in the Webstudio Discord `#help` channel: https://wstd.us/community.\n\nGive the user a complete copy-paste report. Include only non-secret values: never include auth tokens, private URLs, cookies, API keys, passwords, or proprietary project data. Redact them as `<redacted>`.\n\nCopy-paste template:\n\n````md\nWebstudio CLI/MCP issue report\n\nWhat I was trying to do:\n<short user goal, for example "Create a resource from an external API and render it in a collection">\n\nWhat I expected:\n<what should have happened>\n\nWhat happened instead:\n<exact error, confusing behavior, hang, missing docs, or workaround required>\n\nCommand/tool used:\n\n```sh\n<exact command or MCP tool call, with tokens/secrets redacted>\n```\n\nStructured output / error:\n\n```json\n<stdout JSON or MCP structuredContent, if available, with secrets redacted>\n```\n\nStderr / lifecycle logs:\n\n```txt\n<stderr lines, timings, checkpoint messages, or stack trace, with secrets redacted>\n```\n\nEnvironment:\n\n- CLI command path: <webstudio / node packages/cli/local.js / other>\n- Webstudio CLI version: <from command output if known>\n- OS: <macOS / Windows / Linux / unknown>\n- Node version: <node -v if known>\n- Project/session state: <linked project, local .webstudio session, preview, MCP server, or unknown>\n\nWorkaround tried:\n<what the agent/user tried next, and whether it worked>\n\nWhy this should be improved:\n<one sentence: better error message, docs, schema, tool behavior, etc.>\n````\n\n## Shared-Session Shell Runs\n\nUse `webstudio mcp run \'[{"tool":"components.find","input":{"brief":"button"}}]\'` when you are operating from a shell and need several MCP tool calls to share one CLI session without hand-writing JSON-RPC. For large batches, pass a normal JSON file path such as `.temp/mcp-calls.json`. Do not use shell process substitution like `<(...)`; use inline JSON or a real file.\n\nUse `mcp run` for long-lived tools such as `preview.start`. A one-shot `mcp single-op-call preview.start` cannot keep ownership of a preview server for a later screenshot or stop call. Put `preview.start`, `screenshot`, and `preview.stop` in one shared `mcp run` process, or use a real long-running MCP client.\n\nInput shape:\n\n```json\n{\n "calls": [\n { "tool": "meta.index" },\n { "tool": "components.find", "input": { "brief": "radix select" } }\n ]\n}\n```\n\nRules:\n\n- The command prints JSON to stdout for both success and failure. It stops at the first failed call and prints partial results in `{ "ok": false, "error": ..., "data": { "completedCalls": ..., "results": [...] }, "meta": ... }`, then exits nonzero.\n- If a call returns `checkpoint.required`, `mcp run` stops immediately before later calls and prints partial results with `CHECKPOINT_REQUIRED`. Stop now and report the checkpoint to the parent/user. Only after the parent/user continues, call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}` before continuing.\n- For `mcp single-op-call`, checkpoint requirements persist across later one-shot CLI processes until you call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`.\n- Use this instead of manually sending JSON-RPC frames to `webstudio mcp` from a shell.\n\n## Discovery\n\nUse MCP itself after startup, or call the same tools with `webstudio mcp single-op-call`:\n\n- `tools/list`: machine-readable available tools\n- `resources/list`: available overview and full JSON resources\n- `meta.index`: concise capability catalog\n- `meta.guide`: workflow for a user goal; call with a string brief such as `{"brief":"Create a pricing page"}`\n- `meta.get_more_tools`: detailed params, examples, namespaces, and local/server behavior; prefer exact names such as `{"tools":["insert-fragment"]}` when you know them\n- `components.list`: shadcn-compatible registry items for visible components and templates\n- `components.summary`: compact structured component catalog with insertability and template hints\n- `components.coverage-plan`: compact paged plan for design-system coverage tasks that need every component; default returns counts plus the first root page, use `{"detail":"roots"}`, `{"detail":"parts"}`, or `{"detail":"full"}` for more\n- `components.coverage-status`: page-specific covered/missing component report with `missingRoots` and `missingParts`\n- `components.search`: focused component/template search by id, namespace, label, category, or content model\n- `components.find`: compatibility alias for focused component search\n- `components.get`: full metadata for one component id\n- `templates.list`: shadcn-compatible registry items for template-backed insertions only\n- `templates.get`: full registry item and payload metadata for one template\n\nComponent and template registry items use a shadcn-compatible top-level shape plus Webstudio-specific superset metadata in `meta`. Use `meta.runtime` for component ids, props, states, content model, and source identity; `meta.authoring` for composition and accessibility guidance; and `meta.builder` for template insertion details and expected project-data namespaces. These items are for Builder/MCP discovery and are not a published shadcn install registry yet.\n\nPrefer the focused `components.*` tools over dumping `webstudio://project/components`. Do not write local scripts to parse full MCP discovery JSON for common component lookup.\nFor “use every component” or design-system pages, start with compact `components.coverage-plan`, checkpoint, then page through roots/parts instead of dumping the full catalog.\n\n## Consumer Capabilities\n\nMCP lets agents work on one configured Webstudio project at a time. In consumer\nterms, agents can:\n\n- Check which project they are connected to.\n- Check what the share link is allowed to do.\n- Inspect project metadata and the latest editable build.\n- Read selected project data for audits and repair.\n- Apply precise project changes against a known version.\n- List, inspect, create, update, delete, duplicate, copy, and reorder pages.\n- Set the home page.\n- Preserve old page paths for redirects or history.\n- Read and update page titles, descriptions, metadata, auth settings, and SEO fields.\n- List, create, update, duplicate, move, and delete page folders.\n- List, create, update, delete, duplicate, reorder, and reuse page templates.\n- Create pages from reusable templates.\n- Read and update project site settings.\n- Read and update marketplace product metadata.\n- List, create, update, delete, and replace redirects.\n- List, create, update, and delete responsive breakpoints.\n- List and inspect page elements.\n- Insert registered components.\n- Insert styled JSX fragments.\n- Move, reparent, clone, duplicate, wrap, unwrap, convert, rename, retag, and delete elements.\n- Fill grid cells.\n- List and update text children.\n- Update plain text and expression text.\n- Update structured rich text.\n- Add, update, delete, and bind element props.\n- Bind props to expressions, resources, actions, and runtime system values.\n- Read, add, update, delete, and replace local styles.\n- Update selected style-source styles.\n- List, create, update, attach, detach, extract, duplicate, rename, lock, unlock, reorder, clear, and delete design tokens and style sources.\n- List, define, rename, delete, and rewrite CSS variables.\n- List, create, update, and delete static data variables.\n- Create string, number, boolean, string list, and JSON variables.\n- Delete unused data variables.\n- List, create, update, upsert, bind, and delete resources.\n- Create HTTP resources.\n- Create GraphQL resources.\n- Create system resources.\n- Use built-in system resources for sitemap, current date, and assets.\n- List, upload, add, update, find usage for, replace, and delete assets.\n- Publish to staging or production.\n- Publish to selected domains.\n- List publish builds.\n- Check publish job status.\n- Unpublish staging or production deployments.\n- List, create, update, delete, and verify custom domains.\n- Start and stop preview.\n- Capture screenshots of generated pages.\n- Compare screenshots against baselines.\n- Install OCR support for richer visual checks.\n\nUseful resources:\n\n- `webstudio://project/status`: compact current ProjectSession status\n- `webstudio://project/tools-overview`: small operation overview by capability area\n- `webstudio://project/components-overview`: small component overview with ids, labels, namespaces, and categories\n- `webstudio://project/tools`: full operation catalog; read only when focused metadata is insufficient\n- `webstudio://project/components`: full component catalog with props, states, and content model composition constraints; read only when `components.summary`, `components.find`, and `components.get` are insufficient\n- `webstudio://project/guide`: concise discovery guide\n- `webstudio://project/expressions`: expression syntax, scope, supported methods, bindings, Collection iteration context, and verification\n- `webstudio://project/accessibility-review`: evidence-based LLM accessibility-review workflow using project checks, preview, and screenshots\n\n## MCP SDK Client Imports\n\nWhen writing a local Node.js MCP client script, use the official MCP SDK package and these exact ESM imports:\n\nInside the Webstudio monorepo this package is available at the repo root. In another project, install it first with `pnpm add -D @modelcontextprotocol/sdk`.\n\n```js\nimport { Client } from "@modelcontextprotocol/sdk/client/index.js";\nimport { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";\nimport { LoggingMessageNotificationSchema } from "@modelcontextprotocol/sdk/types.js";\n```\n\nMinimal stdio client for the local Webstudio CLI:\n\n```js\nconst client = new Client({ name: "webstudio-agent", version: "1.0.0" });\n\nclient.setNotificationHandler(\n LoggingMessageNotificationSchema,\n (notification) => {\n console.error(`[mcp] ${notification.params.data}`);\n }\n);\n\nconst transport = new StdioClientTransport({\n command: "node",\n args: ["packages/cli/local.js", "mcp"],\n cwd: process.cwd(),\n stderr: "inherit",\n});\n\nawait client.connect(transport);\n\nconst index = await client.callTool({\n name: "meta.index",\n arguments: {},\n});\nconsole.log(JSON.stringify(index.structuredContent, null, 2));\n\nawait client.close();\n```\n\nUse `node packages/cli/local.js mcp` from the Webstudio monorepo root for local development, or `webstudio mcp` from a linked project where the CLI is installed. Keep stdout for JSON-RPC/structured results and surface MCP logging notifications or stderr lifecycle lines as progress.\n\n## Core Rules\n\n- stdout is reserved for MCP JSON-RPC while the server is running.\n- Operate on the configured project only.\n- Read ids before writing.\n- Prefer semantic tools over `apply-patch`.\n- Use `status` and `refresh` when cached namespaces may be stale. Pass `status {"verbose":true}` only when debugging full namespace arrays, freshness, compatibility, or diagnostic details.\n- A mutation is durable only when `meta.session.committed` is true.\n- For visual/design work, verify the rendered result with vision before finishing.\n\n## Vision Verification Loop\n\nVision-capable AI can use MCP to see what it is building:\n\n{{mcpVisionVerificationLoopMarkdown}}\n\nGenerated app setup:\n\n{{mcpGeneratedAppDependencyNotes}}\n\n## MCP Argument Examples\n\nMCP tools receive JSON argument objects:\n\n{{mcpArgumentExampleIndex}}\n\n## Screenshot Verification\n\n{{screenshotVerificationSummary}}\n',
"mcp-startup-epilogue":
diff --git a/packages/cli/src/docs/api-use-cases.md b/packages/cli/src/docs/api-use-cases.md
index 215ec66063..78a4070948 100644
--- a/packages/cli/src/docs/api-use-cases.md
+++ b/packages/cli/src/docs/api-use-cases.md
@@ -60,7 +60,7 @@ Commands:
Notes:
-- Use `webstudio schema mcp` for a tiny machine-readable MCP tool overview. Use `webstudio schema mcp --detail summary` for all tool descriptions, and `webstudio schema mcp --detail full` or focused `meta.get_more_tools` calls only when exact input schemas are needed.
+- Use `webstudio schema mcp` for a compact machine-readable MCP tool overview. Add `--verbose` or use focused `meta.get_more_tools` calls only when exact input schemas are needed.
- Use focused MCP tools for discovery first: `meta.index`, `meta.guide`, `meta.get_more_tools`, `components.list`, `components.summary`, `components.search`, `components.get`, `templates.list`, and `templates.get`. Protocol clients can use `resources/list` and `resources/read`; shell agents can use `webstudio mcp list-resources` and `webstudio mcp read-resource <uri>`. Read longer resources such as `webstudio://project/tools` and `webstudio://project/components` only when focused tools are insufficient.
- Read `webstudio://project/expressions` before authoring unfamiliar computed text, prop bindings, resource expressions, actions, or Collection item bindings.
- From a shell, call one MCP tool with the shortcut form `webstudio <tool> '<json>'`, for example `webstudio components.summary`. The explicit equivalent is `webstudio mcp single-op-call <tool> '<json>'`. Use `--input-file` for large payloads.
@@ -560,12 +560,12 @@ Commands:
- MCP tool: list-design-tokens {}
- MCP tool: list-design-tokens {"withUsage":true}
-- MCP tool: list-design-tokens {"includeStyles":true}
+- MCP tool: list-design-tokens {"verbose":true}
Notes:
- The default response is compact and includes token id, name, declaration count, and optional usage count.
-- Use `includeStyles:true` only when you need the full inline style declarations.
+- Use `verbose:true` only when you need the full inline style declarations.
## Create design tokens
diff --git a/packages/cli/src/docs/manual-llm.md b/packages/cli/src/docs/manual-llm.md
index b87e96dff9..d42638f968 100644
--- a/packages/cli/src/docs/manual-llm.md
+++ b/packages/cli/src/docs/manual-llm.md
@@ -21,7 +21,7 @@ For delegated design-system or “use every component” tasks, skip the generic
6. Pick focused MCP read tool.
7. Pick semantic MCP write tool.
-Use `webstudio schema mcp` for a tiny MCP tool overview. Use `webstudio schema mcp --detail summary` for all tool descriptions, and `webstudio schema mcp --detail full` only when exact input schemas for all tools are truly needed; otherwise prefer focused `meta.get_more_tools` and `components.*` calls.
+Use `webstudio schema mcp` for a compact MCP tool overview. Add `--verbose` only when exact input schemas for all tools are truly needed; otherwise prefer focused `meta.get_more_tools` and `components.*` calls.
Run these commands from the linked project root. Use the MCP startup status line's absolute root for local files; write temporary scripts and artifacts under `<project root>/.temp`, not under a parent workspace.
diff --git a/packages/cli/src/error-codes.test.ts b/packages/cli/src/error-codes.test.ts
index c44222e6ad..52d242a899 100644
--- a/packages/cli/src/error-codes.test.ts
+++ b/packages/cli/src/error-codes.test.ts
@@ -4,7 +4,7 @@ import {
getStableErrorCode,
isMissingApiAccessError,
} from "./error-codes";
-import { BuilderRuntimeError } from "@webstudio-is/project-build/runtime/errors";
+import { BuilderRuntimeError } from "@webstudio-is/project-build/runtime";
describe("getStableErrorCode", () => {
test("reads direct stable error codes", () => {
diff --git a/packages/cli/src/error-codes.ts b/packages/cli/src/error-codes.ts
index a4fee757c6..44944167c8 100644
--- a/packages/cli/src/error-codes.ts
+++ b/packages/cli/src/error-codes.ts
@@ -5,7 +5,7 @@ import {
import {
formatValidationIssues,
getValidationIssues,
-} from "@webstudio-is/project-build/runtime/errors";
+} from "@webstudio-is/project-build/runtime";
const missingProjectOwnerForTokenPattern =
/^Project owner can't be found for token\b/;
diff --git a/packages/cli/src/prebuild.ts b/packages/cli/src/prebuild.ts
index a1762b60a8..404c5cb80d 100644
--- a/packages/cli/src/prebuild.ts
+++ b/packages/cli/src/prebuild.ts
@@ -42,7 +42,7 @@ import {
toRuntimeAsset,
} from "@webstudio-is/sdk";
import { migratePages } from "@webstudio-is/project-migrations/pages";
-import { collectFontFamiliesFromStyleDecls } from "@webstudio-is/project-build/runtime/style-utils";
+import { collectFontFamiliesFromStyleDecls } from "@webstudio-is/project-build/runtime";
import {
publishedProjectBundle,
type PublishedProjectBundle,
diff --git a/packages/cli/src/project-session-api.ts b/packages/cli/src/project-session-api.ts
index 7446589089..232a269865 100644
--- a/packages/cli/src/project-session-api.ts
+++ b/packages/cli/src/project-session-api.ts
@@ -3,8 +3,8 @@ import {
publicApiOperationRequiresServerSupport,
type PublicApiCommand,
} from "@webstudio-is/protocol";
-import type { RuntimeOperationId } from "@webstudio-is/project-build/contracts/builder-runtime";
-import type { BuilderNamespace } from "@webstudio-is/project-build/contracts/namespaces";
+import type { RuntimeOperationId } from "@webstudio-is/project-build/contracts";
+import type { BuilderNamespace } from "@webstudio-is/project-build/contracts";
import {
serializeProjectSessionMeta,
type ProjectSessionEnvelope,
diff --git a/packages/cli/src/project-session.test.ts b/packages/cli/src/project-session.test.ts
index 502bed2805..63b45bb82b 100644
--- a/packages/cli/src/project-session.test.ts
+++ b/packages/cli/src/project-session.test.ts
@@ -2,8 +2,8 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { afterEach, describe, expect, test, vi } from "vitest";
-import { createBuilderStateFromSnapshot } from "@webstudio-is/project-build/state/adapters";
-import { createBuilderStateFreshness } from "@webstudio-is/project-build/state/freshness";
+import { createBuilderStateFromSnapshot } from "@webstudio-is/project-build/state";
+import { createBuilderStateFreshness } from "@webstudio-is/project-build/state";
import {
createLocalProjectBundleFromSessionSnapshot,
createCliProjectSessionStorage,
diff --git a/packages/cli/src/project-session.ts b/packages/cli/src/project-session.ts
index b1033e66e6..fe1aeff577 100644
--- a/packages/cli/src/project-session.ts
+++ b/packages/cli/src/project-session.ts
@@ -25,16 +25,16 @@ import {
type ProjectSessionStorage,
type ProjectSessionTransport,
} from "@webstudio-is/project-build/project-session";
-import type { BuilderNamespace } from "@webstudio-is/project-build/contracts/namespaces";
+import type { BuilderNamespace } from "@webstudio-is/project-build/contracts";
import {
createBuilderStateFromBuildData,
createBuilderStateFromSerializedSnapshot,
createSerializedBuilderStateSnapshotFromState,
type BuilderBuildDataSnapshot,
type SerializedBuilderStateSnapshot,
-} from "@webstudio-is/project-build/state/adapters";
-import { removeLegacyProjectSettingsFromPages } from "@webstudio-is/project-build/shared/project-settings";
-import type { BuilderStateFreshness } from "@webstudio-is/project-build/state/freshness";
+} from "@webstudio-is/project-build/state";
+import { removeLegacyProjectSettingsFromPages } from "@webstudio-is/project-build";
+import type { BuilderStateFreshness } from "@webstudio-is/project-build/state";
import { LOCAL_CONFIG_FILE, LOCAL_DATA_FILE } from "./config";
import { getStableErrorCode } from "./error-codes";
import { writeFileAtomic } from "./fs-utils";
diff --git a/packages/cli/src/screenshot-browser-cdp.ts b/packages/cli/src/screenshot-browser-cdp.ts
index 4d905e48e9..163aa407b6 100644
--- a/packages/cli/src/screenshot-browser-cdp.ts
+++ b/packages/cli/src/screenshot-browser-cdp.ts
@@ -3,7 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { spawn, type ChildProcess } from "node:child_process";
-import type { ScreenshotWaitUntil } from "@webstudio-is/project-build/visual/screenshot-browser";
+import type { ScreenshotWaitUntil } from "@webstudio-is/project-build/visual";
type BrowserProcess = Pick<ChildProcess, "kill" | "once">;
diff --git a/packages/cli/src/screenshot.ts b/packages/cli/src/screenshot.ts
index dd6957a59c..270653ff60 100644
--- a/packages/cli/src/screenshot.ts
+++ b/packages/cli/src/screenshot.ts
@@ -11,7 +11,7 @@ import {
defaultScreenshotWaitUntil,
type ScreenshotBrowser,
type ScreenshotWaitUntil,
-} from "@webstudio-is/project-build/visual/screenshot-browser";
+} from "@webstudio-is/project-build/visual";
import {
captureBrowserScreenshot,
createBrowserScreenshotSession,
diff --git a/packages/domain/src/db/domain.ts b/packages/domain/src/db/domain.ts
index 261e7a4edf..d62376a504 100644
--- a/packages/domain/src/db/domain.ts
+++ b/packages/domain/src/db/domain.ts
@@ -6,7 +6,7 @@ import {
getPlanFeaturesByOwnerId,
} from "@webstudio-is/trpc-interface/index.server";
import * as projectApi from "@webstudio-is/project/index.server";
-import { unpublishBuild } from "@webstudio-is/project-build/index.server";
+import { unpublishBuild } from "@webstudio-is/project-build/server";
import { validateDomain } from "./validate";
import { cnameFromUserId } from "./cname-from-user-id";
import type { Project } from "@webstudio-is/project";
diff --git a/packages/domain/src/project-domain-api.server.ts b/packages/domain/src/project-domain-api.server.ts
index 2f0be31dac..a2ba52fec6 100644
--- a/packages/domain/src/project-domain-api.server.ts
+++ b/packages/domain/src/project-domain-api.server.ts
@@ -3,9 +3,9 @@ import { z } from "zod";
import * as projectApi from "@webstudio-is/project/index.server";
import {
createProductionBuild,
- parseDeployment,
unpublishBuild,
-} from "@webstudio-is/project-build/index.server";
+} from "@webstudio-is/project-build/server";
+import { parseDeployment } from "@webstudio-is/project-build/persistence";
import {
templates as templateSchema,
type Deployment,
diff --git a/packages/project-build/package.json b/packages/project-build/package.json
index 78e8d042ba..8120f32061 100644
--- a/packages/project-build/package.json
+++ b/packages/project-build/package.json
@@ -12,40 +12,28 @@
"webstudio": "./src/index.ts",
"partykit": "./src/index.ts"
},
- "./schema": {
- "webstudio": "./src/schema.ts",
- "import": "./src/schema.ts",
- "default": "./src/schema.ts"
+ "./contracts": {
+ "webstudio": "./src/contracts.ts",
+ "import": "./src/contracts.ts",
+ "default": "./src/contracts.ts"
},
- "./shared/project-settings": {
- "webstudio": "./src/shared/project-settings.ts",
- "import": "./src/shared/project-settings.ts",
- "default": "./src/shared/project-settings.ts"
+ "./runtime": {
+ "webstudio": "./src/runtime.ts",
+ "import": "./src/runtime.ts",
+ "default": "./src/runtime.ts"
},
- "./contracts/builder-runtime": {
- "webstudio": "./src/contracts/builder-runtime.ts",
- "import": "./src/contracts/builder-runtime.ts",
- "default": "./src/contracts/builder-runtime.ts"
+ "./transfer": {
+ "webstudio": "./src/transfer.ts",
+ "import": "./src/transfer.ts",
+ "default": "./src/transfer.ts"
},
- "./contracts/input-schema": {
- "webstudio": "./src/contracts/input-schema.ts",
- "import": "./src/contracts/input-schema.ts",
- "default": "./src/contracts/input-schema.ts"
+ "./transfer/server": {
+ "webstudio": "./src/transfer.server.ts"
},
- "./contracts/namespaces": {
- "webstudio": "./src/contracts/namespaces.ts",
- "import": "./src/contracts/namespaces.ts",
- "default": "./src/contracts/namespaces.ts"
- },
- "./contracts/permissions": {
- "webstudio": "./src/contracts/permissions.ts",
- "import": "./src/contracts/permissions.ts",
- "default": "./src/contracts/permissions.ts"
- },
- "./contracts/patch": {
- "webstudio": "./src/contracts/patch.ts",
- "import": "./src/contracts/patch.ts",
- "default": "./src/contracts/patch.ts"
+ "./state": {
+ "webstudio": "./src/state.ts",
+ "import": "./src/state.ts",
+ "default": "./src/state.ts"
},
"./project-session": {
"webstudio": "./src/project-session.ts",
@@ -53,279 +41,23 @@
"default": "./src/project-session.ts"
},
"./mcp": {
- "webstudio": "./src/mcp.ts",
- "import": "./src/mcp.ts",
- "default": "./src/mcp.ts"
- },
- "./build-integrity": {
- "webstudio": "./src/build-integrity.ts",
- "import": "./src/build-integrity.ts",
- "default": "./src/build-integrity.ts"
- },
- "./state/adapters": {
- "webstudio": "./src/state/adapters.ts",
- "import": "./src/state/adapters.ts",
- "default": "./src/state/adapters.ts"
- },
- "./state/builder-state": {
- "webstudio": "./src/state/builder-state.ts",
- "import": "./src/state/builder-state.ts",
- "default": "./src/state/builder-state.ts"
- },
- "./state/freshness": {
- "webstudio": "./src/state/freshness.ts",
- "import": "./src/state/freshness.ts",
- "default": "./src/state/freshness.ts"
- },
- "./state/patch": {
- "webstudio": "./src/state/patch.ts",
- "import": "./src/state/patch.ts",
- "default": "./src/state/patch.ts"
- },
- "./visual/screenshot-diff": {
- "webstudio": "./src/visual/screenshot-diff.ts",
- "import": "./src/visual/screenshot-diff.ts",
- "default": "./src/visual/screenshot-diff.ts"
- },
- "./visual/screenshot-browser": {
- "webstudio": "./src/visual/screenshot-browser.ts",
- "import": "./src/visual/screenshot-browser.ts",
- "default": "./src/visual/screenshot-browser.ts"
- },
- "./runtime/assets": {
- "webstudio": "./src/runtime/assets.ts",
- "import": "./src/runtime/assets.ts",
- "default": "./src/runtime/assets.ts"
- },
- "./runtime/auth": {
- "webstudio": "./src/runtime/auth.ts",
- "import": "./src/runtime/auth.ts",
- "default": "./src/runtime/auth.ts"
- },
- "./runtime/breakpoints": {
- "webstudio": "./src/runtime/breakpoints.ts",
- "import": "./src/runtime/breakpoints.ts",
- "default": "./src/runtime/breakpoints.ts"
- },
- "./runtime/block": {
- "webstudio": "./src/runtime/block.ts",
- "import": "./src/runtime/block.ts",
- "default": "./src/runtime/block.ts"
- },
- "./runtime/data": {
- "webstudio": "./src/runtime/data.ts",
- "import": "./src/runtime/data.ts",
- "default": "./src/runtime/data.ts"
- },
- "./runtime/data-formats/data-envelope": {
- "webstudio": "./src/runtime/data-formats/data-envelope.ts",
- "import": "./src/runtime/data-formats/data-envelope.ts",
- "default": "./src/runtime/data-formats/data-envelope.ts"
- },
- "./runtime/data-formats/instance-transfer": {
- "webstudio": "./src/runtime/data-formats/instance-transfer.ts",
- "import": "./src/runtime/data-formats/instance-transfer.ts",
- "default": "./src/runtime/data-formats/instance-transfer.ts"
- },
- "./runtime/data-formats/page-transfer": {
- "webstudio": "./src/runtime/data-formats/page-transfer.ts",
- "import": "./src/runtime/data-formats/page-transfer.ts",
- "default": "./src/runtime/data-formats/page-transfer.ts"
- },
- "./runtime/errors": {
- "webstudio": "./src/runtime/errors.ts",
- "import": "./src/runtime/errors.ts",
- "default": "./src/runtime/errors.ts"
- },
- "./runtime/expression-validation": {
- "webstudio": "./src/runtime/expression-validation.ts",
- "import": "./src/runtime/expression-validation.ts",
- "default": "./src/runtime/expression-validation.ts"
- },
- "./runtime/fragment": {
- "webstudio": "./src/runtime/fragment.ts",
- "import": "./src/runtime/fragment.ts",
- "default": "./src/runtime/fragment.ts"
- },
- "./runtime/html": {
- "webstudio": "./src/runtime/html.ts",
- "import": "./src/runtime/html.ts",
- "default": "./src/runtime/html.ts"
- },
- "./runtime/jsx": {
- "webstudio": "./src/runtime/jsx/index.ts",
- "import": "./src/runtime/jsx/index.ts",
- "default": "./src/runtime/jsx/index.ts"
- },
- "./runtime/jsx/syntax": {
- "webstudio": "./src/runtime/jsx/syntax.ts",
- "import": "./src/runtime/jsx/syntax.ts",
- "default": "./src/runtime/jsx/syntax.ts"
- },
- "./runtime/jsx/utils": {
- "webstudio": "./src/runtime/jsx/utils.ts",
- "import": "./src/runtime/jsx/utils.ts",
- "default": "./src/runtime/jsx/utils.ts"
- },
- "./runtime/instances": {
- "webstudio": "./src/runtime/instances.ts",
- "import": "./src/runtime/instances.ts",
- "default": "./src/runtime/instances.ts"
- },
- "./runtime/insert-target": {
- "webstudio": "./src/runtime/insert-target.ts",
- "import": "./src/runtime/insert-target.ts",
- "default": "./src/runtime/insert-target.ts"
- },
- "./runtime/lookup": {
- "webstudio": "./src/runtime/lookup.ts",
- "import": "./src/runtime/lookup.ts",
- "default": "./src/runtime/lookup.ts"
- },
- "./runtime/instance-duplicate": {
- "webstudio": "./src/runtime/instance-duplicate.ts",
- "import": "./src/runtime/instance-duplicate.ts",
- "default": "./src/runtime/instance-duplicate.ts"
- },
- "./runtime/mutation": {
- "webstudio": "./src/runtime/mutation.ts",
- "import": "./src/runtime/mutation.ts",
- "default": "./src/runtime/mutation.ts"
- },
- "./runtime/page-copy": {
- "webstudio": "./src/runtime/page-copy.ts",
- "import": "./src/runtime/page-copy.ts",
- "default": "./src/runtime/page-copy.ts"
- },
- "./runtime/pages": {
- "webstudio": "./src/runtime/pages.ts",
- "import": "./src/runtime/pages.ts",
- "default": "./src/runtime/pages.ts"
- },
- "./runtime/project-settings": {
- "webstudio": "./src/runtime/project-settings.ts",
- "import": "./src/runtime/project-settings.ts",
- "default": "./src/runtime/project-settings.ts"
- },
- "./runtime/redirect-source": {
- "webstudio": "./src/runtime/redirect-source.ts",
- "import": "./src/runtime/redirect-source.ts",
- "default": "./src/runtime/redirect-source.ts"
- },
- "./runtime/redirect-loop-detection": {
- "webstudio": "./src/runtime/redirect-loop-detection.ts",
- "import": "./src/runtime/redirect-loop-detection.ts",
- "default": "./src/runtime/redirect-loop-detection.ts"
- },
- "./runtime/redirect-parsers": {
- "webstudio": "./src/runtime/redirect-parsers.ts",
- "import": "./src/runtime/redirect-parsers.ts",
- "default": "./src/runtime/redirect-parsers.ts"
- },
- "./runtime/props": {
- "webstudio": "./src/runtime/props.ts",
- "import": "./src/runtime/props.ts",
- "default": "./src/runtime/props.ts"
- },
- "./runtime/registry": {
- "webstudio": "./src/runtime/registry.ts",
- "import": "./src/runtime/registry.ts",
- "default": "./src/runtime/registry.ts"
- },
- "./runtime/slot": {
- "webstudio": "./src/runtime/slot.ts",
- "import": "./src/runtime/slot.ts",
- "default": "./src/runtime/slot.ts"
- },
- "./runtime/content-model": {
- "webstudio": "./src/runtime/content-model.ts",
- "import": "./src/runtime/content-model.ts",
- "default": "./src/runtime/content-model.ts"
- },
- "./runtime/content-mode-copy-policy": {
- "webstudio": "./src/runtime/content-mode-copy-policy.ts",
- "import": "./src/runtime/content-mode-copy-policy.ts",
- "default": "./src/runtime/content-mode-copy-policy.ts"
- },
- "./runtime/content-mode-permissions": {
- "webstudio": "./src/runtime/content-mode-permissions.ts",
- "import": "./src/runtime/content-mode-permissions.ts",
- "default": "./src/runtime/content-mode-permissions.ts"
- },
- "./runtime/context": {
- "webstudio": "./src/runtime/context.ts",
- "import": "./src/runtime/context.ts",
- "default": "./src/runtime/context.ts"
- },
- "./runtime/component-template": {
- "webstudio": "./src/runtime/component-template.ts",
- "import": "./src/runtime/component-template.ts",
- "default": "./src/runtime/component-template.ts"
- },
- "./runtime/component-catalog": {
- "webstudio": "./src/runtime/component-catalog.ts",
- "import": "./src/runtime/component-catalog.ts",
- "default": "./src/runtime/component-catalog.ts"
- },
- "./runtime/style-copy": {
- "webstudio": "./src/runtime/style-copy.ts",
- "import": "./src/runtime/style-copy.ts",
- "default": "./src/runtime/style-copy.ts"
- },
- "./runtime/style-utils": {
- "webstudio": "./src/runtime/style-utils.ts",
- "import": "./src/runtime/style-utils.ts",
- "default": "./src/runtime/style-utils.ts"
- },
- "./runtime/tree": {
- "webstudio": "./src/runtime/tree.ts",
- "import": "./src/runtime/tree.ts",
- "default": "./src/runtime/tree.ts"
- },
- "./runtime/matcher": {
- "webstudio": "./src/runtime/matcher.ts",
- "import": "./src/runtime/matcher.ts",
- "default": "./src/runtime/matcher.ts"
- },
- "./runtime/url-pattern": {
- "webstudio": "./src/runtime/url-pattern.ts",
- "import": "./src/runtime/url-pattern.ts",
- "default": "./src/runtime/url-pattern.ts"
- },
- "./runtime/webflow/instances-properties": {
- "webstudio": "./src/runtime/webflow/instances-properties.ts",
- "import": "./src/runtime/webflow/instances-properties.ts",
- "default": "./src/runtime/webflow/instances-properties.ts"
- },
- "./runtime/webflow/schema": {
- "webstudio": "./src/runtime/webflow/schema.ts",
- "import": "./src/runtime/webflow/schema.ts",
- "default": "./src/runtime/webflow/schema.ts"
- },
- "./runtime/webflow/styles": {
- "webstudio": "./src/runtime/webflow/styles.ts",
- "import": "./src/runtime/webflow/styles.ts",
- "default": "./src/runtime/webflow/styles.ts"
- },
- "./runtime/styles": {
- "webstudio": "./src/runtime/styles.ts",
- "import": "./src/runtime/styles.ts",
- "default": "./src/runtime/styles.ts"
- },
- "./index.server": {
- "webstudio": "./src/index.server.ts"
+ "webstudio": "./src/mcp.ts"
},
- "./build-parser.server": {
- "webstudio": "./src/db/build-parser.ts"
+ "./visual": {
+ "webstudio": "./src/visual.ts"
},
- "./style-source-selections.server": {
- "webstudio": "./src/db/style-source-selections.ts"
+ "./persistence": {
+ "webstudio": "./src/persistence.ts",
+ "import": "./src/persistence.ts",
+ "default": "./src/persistence.ts"
},
- "./styles.server": {
- "webstudio": "./src/db/styles.ts"
+ "./server": {
+ "webstudio": "./src/server.ts"
}
},
- "sideEffects": false,
+ "sideEffects": [
+ "./src/state/immer.ts"
+ ],
"scripts": {
"generate-docs": "node scripts/generate-docs.mjs && oxfmt src/docs.generated.ts",
"generate-runtime-operation-contracts": "tsx --import ../../scripts/register-react-global.ts --conditions=webstudio scripts/generate-runtime-operation-contracts.ts && oxfmt src/contracts/__generated__/runtime-operation-contracts.ts",
diff --git a/packages/project-build/src/contracts.ts b/packages/project-build/src/contracts.ts
new file mode 100644
index 0000000000..77dafdc100
--- /dev/null
+++ b/packages/project-build/src/contracts.ts
@@ -0,0 +1,7 @@
+export * from "./schema";
+export * from "./contracts/builder-runtime";
+export * from "./contracts/input-schema";
+export * from "./contracts/namespaces";
+export * from "./contracts/permissions";
+export * from "./contracts/patch";
+export * from "./contracts/project-settings";
diff --git a/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts b/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts
index 3ce22edab4..d1ae67ef43 100644
--- a/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts
+++ b/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts
@@ -25210,6 +25210,19 @@ export const runtimeOperationContractData = [
labelContains: {
type: "string",
},
+ cursor: {
+ type: "string",
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 200,
+ },
+ verbose: {
+ description:
+ "Expand the same result with complete records and diagnostics. Omit for compact output.",
+ type: "boolean",
+ },
},
required: [],
},
@@ -25251,13 +25264,125 @@ export const runtimeOperationContractData = [
minimum: -9007199254740991,
maximum: 9007199254740991,
},
+ record: {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "instance",
+ },
+ id: {
+ type: "string",
+ },
+ component: {
+ type: "string",
+ minLength: 1,
+ },
+ tag: {
+ type: "string",
+ minLength: 1,
+ description:
+ "Optional HTML tag override for component rendering. Omit for component defaults; never pass an empty string.",
+ },
+ label: {
+ type: "string",
+ },
+ children: {
+ type: "array",
+ items: {
+ anyOf: [
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "id",
+ },
+ value: {
+ type: "string",
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "text",
+ },
+ value: {
+ type: "string",
+ },
+ placeholder: {
+ type: "boolean",
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "expression",
+ },
+ value: {
+ type: "string",
+ },
+ },
+ required: ["type", "value"],
+ },
+ ],
+ },
+ },
+ },
+ required: ["type", "id", "component", "children"],
+ },
},
required: ["id", "component", "childCount", "depth"],
additionalProperties: {},
},
},
+ detail: {
+ type: "string",
+ enum: ["compact", "verbose"],
+ },
+ total: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ returnedCount: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ nextCursor: {
+ anyOf: [
+ {
+ type: "string",
+ },
+ {
+ type: "null",
+ },
+ ],
+ },
+ filters: {
+ type: "object",
+ properties: {},
+ additionalProperties: {},
+ required: [],
+ },
},
- required: ["instances"],
+ required: [
+ "instances",
+ "detail",
+ "total",
+ "returnedCount",
+ "nextCursor",
+ "filters",
+ ],
additionalProperties: {},
},
readNamespaces: ["pages", "instances", "props"],
@@ -27624,7 +27749,20 @@ export const runtimeOperationContractData = [
property: {
type: "string",
},
- value: {},
+ value: {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ description: "CSS value kind",
+ },
+ hidden: {
+ type: "boolean",
+ },
+ },
+ required: ["type"],
+ additionalProperties: {},
+ },
breakpoint: {
type: "string",
},
@@ -27640,6 +27778,7 @@ export const runtimeOperationContractData = [
"instanceId",
"styleSourceId",
"property",
+ "value",
"breakpoint",
"source",
],
@@ -32906,6 +33045,10 @@ export const runtimeOperationContractData = [
minimum: 0,
maximum: 9007199254740991,
},
+ renderedState: {
+ type: "string",
+ enum: ["complete", "partial", "confirmation-required", "failed"],
+ },
renderedPlan: {
anyOf: [
{
@@ -33414,6 +33557,7 @@ export const runtimeOperationContractData = [
"renderedCheckCount",
"renderedIssueCount",
"renderedFailureCount",
+ "renderedState",
"renderedPlan",
"renderedCaptureSummary",
"renderedCaptureStatuses",
@@ -33565,6 +33709,10 @@ export const runtimeOperationContractData = [
minimum: 0,
maximum: 9007199254740991,
},
+ renderedState: {
+ type: "string",
+ enum: ["complete", "partial", "confirmation-required", "failed"],
+ },
renderedPlan: {
anyOf: [
{
@@ -34517,6 +34665,7 @@ export const runtimeOperationContractData = [
"renderedCheckCount",
"renderedIssueCount",
"renderedFailureCount",
+ "renderedState",
"renderedPlan",
"renderedCaptureSummary",
"renderedCaptureStatuses",
@@ -40410,6 +40559,63 @@ export const runtimeOperationContractData = [
itemKeyParameterId: {
type: "string",
},
+ warnings: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
+ },
+ },
},
required: [
"instanceIds",
@@ -47236,6 +47442,63 @@ export const runtimeOperationContractData = [
type: "string",
},
},
+ warnings: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
+ },
+ },
},
required: ["propIds"],
additionalProperties: {},
@@ -47506,46 +47769,103 @@ export const runtimeOperationContractData = [
type: "string",
},
},
- },
- required: ["propIds"],
- additionalProperties: {},
- },
- readNamespaces: ["instances", "props", "dataSources", "resources"],
- writeNamespaces: ["props"],
- invalidatesNamespaces: ["props"],
- retryOnConflict: false,
- },
- {
- id: "instances.listTexts",
- command: "list-texts",
- client: "listTexts",
- kind: "read",
- inputSchema: {
- type: "object",
- properties: {
- pageId: {
- type: "string",
- },
- pagePath: {
- type: "string",
- },
- instanceId: {
- type: "string",
- },
- mode: {
- type: "string",
- enum: ["text", "expression", "all"],
- },
- contains: {
- type: "string",
- },
- maxValueLength: {
- type: "integer",
- minimum: 0,
- maximum: 9007199254740991,
- },
- },
- required: [],
+ warnings: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
+ },
+ },
+ },
+ required: ["propIds"],
+ additionalProperties: {},
+ },
+ readNamespaces: ["instances", "props", "dataSources", "resources"],
+ writeNamespaces: ["props"],
+ invalidatesNamespaces: ["props"],
+ retryOnConflict: false,
+ },
+ {
+ id: "instances.listTexts",
+ command: "list-texts",
+ client: "listTexts",
+ kind: "read",
+ inputSchema: {
+ type: "object",
+ properties: {
+ pageId: {
+ type: "string",
+ },
+ pagePath: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ mode: {
+ type: "string",
+ enum: ["text", "expression", "all"],
+ },
+ contains: {
+ type: "string",
+ },
+ maxValueLength: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: [],
},
outputSchema: {
type: "object",
@@ -47645,6 +47965,63 @@ export const runtimeOperationContractData = [
type: "string",
enum: ["text", "expression"],
},
+ warnings: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
+ },
+ },
},
required: ["instanceId", "childIndex", "mode"],
additionalProperties: {},
@@ -47808,6 +48185,63 @@ export const runtimeOperationContractData = [
type: "string",
enum: ["text", "expression"],
},
+ warnings: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
+ },
+ },
},
required: ["instanceId", "operation"],
additionalProperties: {},
@@ -48079,6 +48513,19 @@ export const runtimeOperationContractData = [
includeTokens: {
type: "boolean",
},
+ cursor: {
+ type: "string",
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 200,
+ },
+ verbose: {
+ description:
+ "Expand the same result with complete records and diagnostics. Omit for compact output.",
+ type: "boolean",
+ },
},
required: [],
},
@@ -48099,7 +48546,6 @@ export const runtimeOperationContractData = [
property: {
type: "string",
},
- value: {},
breakpoint: {
type: "string",
},
@@ -48110,6 +48556,23 @@ export const runtimeOperationContractData = [
type: "string",
enum: ["local", "token"],
},
+ valueType: {
+ type: "string",
+ },
+ value: {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ description: "CSS value kind",
+ },
+ hidden: {
+ type: "boolean",
+ },
+ },
+ required: ["type"],
+ additionalProperties: {},
+ },
},
required: [
"instanceId",
@@ -48117,12 +48580,50 @@ export const runtimeOperationContractData = [
"property",
"breakpoint",
"source",
+ "valueType",
],
additionalProperties: {},
},
},
+ detail: {
+ type: "string",
+ enum: ["compact", "verbose"],
+ },
+ total: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ returnedCount: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ nextCursor: {
+ anyOf: [
+ {
+ type: "string",
+ },
+ {
+ type: "null",
+ },
+ ],
+ },
+ filters: {
+ type: "object",
+ properties: {},
+ additionalProperties: {},
+ required: [],
+ },
},
- required: ["declarations"],
+ required: [
+ "declarations",
+ "detail",
+ "total",
+ "returnedCount",
+ "nextCursor",
+ "filters",
+ ],
additionalProperties: {},
},
readNamespaces: [
@@ -48442,14 +48943,23 @@ export const runtimeOperationContractData = [
description: "Include usage counts. Defaults to true.",
type: "boolean",
},
- includeStyles: {
- description: "Include full inline style declarations for each token.",
- type: "boolean",
- },
sort: {
type: "string",
enum: ["name", "usage"],
},
+ cursor: {
+ type: "string",
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 200,
+ },
+ verbose: {
+ description:
+ "Expand the same result with complete records and diagnostics. Omit for compact output.",
+ type: "boolean",
+ },
},
required: [],
},
@@ -48477,7 +48987,20 @@ export const runtimeOperationContractData = [
propertyNames: {
type: "string",
},
- additionalProperties: {},
+ additionalProperties: {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ description: "CSS value kind",
+ },
+ hidden: {
+ type: "boolean",
+ },
+ },
+ required: ["type"],
+ additionalProperties: {},
+ },
},
usageCount: {
type: "integer",
@@ -48489,8 +49012,45 @@ export const runtimeOperationContractData = [
additionalProperties: {},
},
},
+ detail: {
+ type: "string",
+ enum: ["compact", "verbose"],
+ },
+ total: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ returnedCount: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ nextCursor: {
+ anyOf: [
+ {
+ type: "string",
+ },
+ {
+ type: "null",
+ },
+ ],
+ },
+ filters: {
+ type: "object",
+ properties: {},
+ additionalProperties: {},
+ required: [],
+ },
},
- required: ["tokens"],
+ required: [
+ "tokens",
+ "detail",
+ "total",
+ "returnedCount",
+ "nextCursor",
+ "filters",
+ ],
additionalProperties: {},
},
readNamespaces: ["styles", "styleSources", "styleSourceSelections"],
@@ -52131,9 +52691,78 @@ export const runtimeOperationContractData = [
scopeInstanceId: {
type: "string",
},
- value: {},
+ value: {
+ anyOf: [
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "number",
+ },
+ value: {
+ type: "number",
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "string",
+ },
+ value: {
+ type: "string",
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "boolean",
+ },
+ value: {
+ type: "boolean",
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "string[]",
+ },
+ value: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ },
+ required: ["type", "value"],
+ },
+ {
+ type: "object",
+ properties: {
+ type: {
+ type: "string",
+ const: "json",
+ },
+ value: {},
+ },
+ required: ["type"],
+ },
+ ],
+ },
},
- required: ["id", "name"],
+ required: ["id", "name", "value"],
additionalProperties: {},
},
},
@@ -52690,7 +53319,58 @@ export const runtimeOperationContractData = [
warnings: {
type: "array",
items: {
- type: "string",
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
},
},
},
@@ -52895,7 +53575,58 @@ export const runtimeOperationContractData = [
warnings: {
type: "array",
items: {
- type: "string",
+ type: "object",
+ properties: {
+ severity: {
+ type: "string",
+ const: "warning",
+ },
+ code: {
+ type: "string",
+ },
+ path: {
+ type: "array",
+ items: {
+ type: "string",
+ },
+ },
+ message: {
+ type: "string",
+ },
+ range: {
+ type: "object",
+ properties: {
+ from: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ to: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ },
+ required: ["from", "to"],
+ },
+ remediation: {
+ type: "string",
+ },
+ instanceId: {
+ type: "string",
+ },
+ resourceId: {
+ type: "string",
+ },
+ },
+ required: [
+ "severity",
+ "code",
+ "path",
+ "message",
+ "range",
+ "remediation",
+ ],
},
},
},
@@ -53509,7 +54240,12 @@ export const runtimeOperationContractData = [
limit: {
type: "integer",
minimum: 1,
- maximum: 9007199254740991,
+ maximum: 200,
+ },
+ verbose: {
+ description:
+ "Expand the same result with complete records and diagnostics. Omit for compact output.",
+ type: "boolean",
},
},
required: [],
@@ -53531,16 +54267,6 @@ export const runtimeOperationContractData = [
filename: {
type: "string",
},
- description: {
- anyOf: [
- {
- type: "string",
- },
- {
- type: "null",
- },
- ],
- },
type: {
type: "string",
enum: ["font", "image", "file"],
@@ -53551,26 +54277,87 @@ export const runtimeOperationContractData = [
contentType: {
type: "string",
},
- createdAt: {
- type: "string",
- },
usageCount: {
type: "integer",
minimum: -9007199254740991,
maximum: 9007199254740991,
},
+ record: {
+ type: "object",
+ properties: {
+ id: {
+ type: "string",
+ },
+ projectId: {
+ type: "string",
+ },
+ name: {
+ type: "string",
+ },
+ filename: {
+ type: "string",
+ },
+ description: {
+ anyOf: [
+ {
+ type: "string",
+ },
+ {
+ type: "null",
+ },
+ ],
+ },
+ type: {
+ type: "string",
+ enum: ["font", "image", "file"],
+ },
+ size: {
+ type: "number",
+ },
+ format: {
+ type: "string",
+ },
+ createdAt: {
+ type: "string",
+ },
+ meta: {
+ type: "object",
+ properties: {},
+ additionalProperties: {},
+ required: [],
+ },
+ },
+ required: [
+ "id",
+ "projectId",
+ "name",
+ "type",
+ "size",
+ "format",
+ "createdAt",
+ "meta",
+ ],
+ additionalProperties: {},
+ },
},
- required: [
- "id",
- "name",
- "type",
- "size",
- "contentType",
- "createdAt",
- ],
+ required: ["id", "name", "type", "size", "contentType"],
additionalProperties: {},
},
},
+ detail: {
+ type: "string",
+ enum: ["compact", "verbose"],
+ },
+ total: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
+ returnedCount: {
+ type: "integer",
+ minimum: 0,
+ maximum: 9007199254740991,
+ },
nextCursor: {
anyOf: [
{
@@ -53581,8 +54368,21 @@ export const runtimeOperationContractData = [
},
],
},
+ filters: {
+ type: "object",
+ properties: {},
+ additionalProperties: {},
+ required: [],
+ },
},
- required: ["items", "nextCursor"],
+ required: [
+ "items",
+ "detail",
+ "total",
+ "returnedCount",
+ "nextCursor",
+ "filters",
+ ],
additionalProperties: {},
},
readNamespaces: [
diff --git a/packages/project-build/src/contracts/project-settings.ts b/packages/project-build/src/contracts/project-settings.ts
new file mode 100644
index 0000000000..9ff397829f
--- /dev/null
+++ b/packages/project-build/src/contracts/project-settings.ts
@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { parseWsAuth, type WsAuthRoute } from "@webstudio-is/wsauth";
+
+const emailAddress = z.string().email();
+
+const getContactEmails = (contactEmail: string) => {
+ const trimmedContactEmail = contactEmail.trim();
+ if (trimmedContactEmail.length === 0) {
+ return [];
+ }
+ return trimmedContactEmail.split(/\s*,\s*/);
+};
+
+export const validateContactEmail = (
+ contactEmail: string,
+ maxContactEmailsPerProject?: number
+) => {
+ const emails = getContactEmails(contactEmail);
+ if (emails.length === 0) {
+ return;
+ }
+ if (
+ maxContactEmailsPerProject !== undefined &&
+ emails.length > maxContactEmailsPerProject
+ ) {
+ if (maxContactEmailsPerProject === 0) {
+ return `Upgrade to PRO to customize the contact email.`;
+ }
+ return `Only ${maxContactEmailsPerProject} emails are allowed.`;
+ }
+ if (
+ emails.every((email) => emailAddress.safeParse(email).success) === false
+ ) {
+ return "Contact email is invalid.";
+ }
+};
+
+export const validateProjectAuth = (auth: string) => {
+ const result = parseWsAuth(auth);
+ if (result.errors.length === 0) {
+ return;
+ }
+ return result.errors
+ .map((error) => `${error.path}: ${error.message}`)
+ .join("\n");
+};
+
+export const parseProjectAuthRoutes = (auth: string | undefined) =>
+ parseWsAuth(auth ?? "");
+
+export const validateProjectAuthRouteSyntax = (route: string) => {
+ const result = parseWsAuth(
+ JSON.stringify({
+ version: 1,
+ routes: {
+ [route]: {
+ method: "basic",
+ login: "login",
+ password: "password",
+ },
+ },
+ })
+ );
+ return result.errors.find((error) =>
+ error.path.startsWith(`routes.${JSON.stringify(route)}`)
+ )?.message;
+};
+
+export const validateProjectAuthRoute = (
+ route: string,
+ authRoutes: readonly WsAuthRoute[]
+) => {
+ const errors: string[] = [];
+ if (route === "") {
+ errors.push("Route is required");
+ return errors;
+ }
+ const routeError = validateProjectAuthRouteSyntax(route);
+ if (routeError !== undefined) {
+ errors.push(routeError);
+ }
+ if (authRoutes.some((authRoute) => authRoute.route === route)) {
+ errors.push("This route already requires authentication");
+ }
+ return errors;
+};
diff --git a/packages/project-build/src/docs.generated.ts b/packages/project-build/src/docs.generated.ts
index 1d04d9b15f..ad0fb2d2ca 100644
--- a/packages/project-build/src/docs.generated.ts
+++ b/packages/project-build/src/docs.generated.ts
@@ -4,7 +4,7 @@ export const projectBuildDocs = {
"accessibility-review":
'<!-- Adapted for Webstudio MCP from Community-Access/accessibility-agents, web-accessibility-wizard/SKILL.md (MIT): https://github.com/Community-Access/accessibility-agents/blob/main/codex-skills/web-accessibility-wizard/SKILL.md -->\n\n# Webstudio Accessibility Review\n\nUse this workflow when creating or reviewing a page, component, form, menu,\ndialog, or responsive layout. It is an LLM-assisted review, not proof of WCAG\nconformance. Do not claim that a page is accessible solely because this review\nhas no findings.\n\n## Evidence First\n\n1. Read `meta.index` and use focused project tools. Do not inspect Webstudio\n source code or generated files for normal project reviews.\n2. Run `audit` with `{"scopes":["accessibility"]}` before changing\n anything. It detects deterministic metadata issues such as labels, landmark\n structure, positive tabindex values, invalid static ARIA states, and unmuted\n autoplay. Fix confirmed static findings first.\n3. For each changed route, use `preview.start` and capture screenshots with\n `screenshot` at desktop, tablet, and mobile widths. Use `waitForSelector`\n or `waitForTimeout` only when the page has an actual delayed ready state.\n4. Use `get-page-by-path`, `list-instances`, `inspect-instance`, and focused\n prop/style reads to verify semantics and authored state that screenshots\n cannot prove.\n5. Make only supported, evidence-based fixes with semantic MCP tools. Recheck\n the affected route and the static accessibility search after every fix.\n\n## Review Areas\n\nReview these areas in priority order. Record the evidence for every finding.\n\n### 1. Names, Semantics, and Structure\n\n- Every image has purposeful alternative text or an explicitly empty alt when\n decorative. Image-submit inputs need a non-empty alt label describing their\n action.\n- For `missing-image-description` findings, inspect the rendered image in its\n page context and call `set-image-descriptions` with either a concise generated\n description or `decorative: true`. Re-run the audit after saving the decision.\n- Buttons, links, icon-only controls, and form controls have accessible names.\n- Prefer native HTML semantics over ARIA roles.\n- Non-native elements using `role="button"` or `role="link"` must be\n keyboard-focusable.\n- Use one sensible page h1, ordered heading levels, meaningful link text, and\n a main landmark.\n- Iframes have titles. Static HTML ids are unique, ARIA reference props point\n to real ids, and static boolean/select/numeric ARIA values are valid.\n- Focusable controls must not be hidden from assistive technology with\n `aria-hidden`.\n\n### 2. Keyboard and Focus\n\n- Interactive controls should be native or have a documented keyboard model.\n- Visible focus must not be removed without a visible replacement.\n- Hover-only information or controls need a keyboard-accessible equivalent.\n- Do not use positive tabindex values.\n- Mark keyboard behavior as **manual verification required** when the available\n evidence cannot prove tab order, Escape handling, or focus restoration.\n\n### 3. Dialogs, Menus, and Other Overlays\n\n- Dialogs need an accessible name and a close action.\n- Opening an overlay should move focus into it, trap focus where appropriate,\n and restore focus to its trigger on close.\n- Menus, popovers, disclosures, and tabs must expose their expanded/selected\n state and remain usable without a pointer.\n- If the current MCP/browser tools cannot exercise the interaction, report it\n as a manual verification item instead of guessing.\n\n### 4. Forms and Errors\n\n- Inputs have labels, required state, helpers, and errors associated with the\n right control.\n- Invalid controls expose `aria-invalid` when applicable.\n- Error, loading, and success feedback is not conveyed only by color or a\n transient visual toast.\n- Submit controls do not become unexplained dead ends when disabled.\n\n### 5. Visual, Responsive, Media, and Motion\n\n- At each target width, text remains readable, controls remain reachable, and\n no content is clipped, overlapped, or dependent on hover alone.\n- Do not rely only on color, position, shape, or iconography to convey meaning.\n- Keep non-text contrast, text contrast, focus indicators, and small text as\n visual review items unless measured evidence is available.\n- Videos with meaningful speech need captions; non-essential motion should\n respect reduced-motion preferences. Do not autoplay sound.\n\n### 6. Dynamic Content and Data\n\n- Loading, empty, error, and success states have understandable visible text.\n- Important dynamic updates and validation feedback need an appropriate\n announcement strategy.\n- Check repeated resource-driven content for unique labels, headings, ids, and\n meaningful empty states.\n\n## Findings and Fixes\n\nClassify every item as one of:\n\n- **Confirmed:** directly shown by `audit`, project data, or a rendered\n screenshot.\n- **Likely:** a credible issue inferred from rendered evidence; explain what\n would confirm it.\n- **Manual verification required:** needs keyboard, screen-reader, contrast, or\n interaction testing that the available tools cannot prove.\n\nFor each item include: severity (`critical`, `high`, `medium`, or `low`), page\npath, affected element or instance id when known, evidence, short user impact,\nand the smallest supported fix. Fix critical and high items first. Do not add\nARIA attributes, alt text, labels, or live regions when their meaning cannot be\nknown from the project; ask the user or report the missing context.\n\nFinish with a concise summary of fixed findings, remaining findings, and manual\nverification items. Use screenshots as evidence of the rendered state, not as\nproof of accessibility compliance.\n',
expressions:
- '# Webstudio Expressions\n\nUse an expression only when a value must be computed at runtime from scoped\ndata. Use direct text and direct prop values for fixed content.\n\n## Source Format\n\nExpression-capable MCP fields receive JavaScript expression source as a JSON\nstring. Send one expression, without a `return` statement or surrounding\nfunction. For example:\n\n```json\n{ "binding": { "type": "expression", "value": "post.title ?? \\"Untitled\\"" } }\n```\n\nDo not send a fixed prop string as an expression. Use `update-props` with\n`type:"string"`. Page metadata and resource URLs accept plain fixed strings and\nnormalize them for storage. Expression-only resource headers, search parameters,\nand bodies accept `{ "type": "literal", "value": "fixed text" }` when the\nvalue is not dynamic.\n\n## Scope\n\n- Data variables are available on their scope instance and descendants.\n- An inner variable with the same name masks the outer variable.\n- A scoped resource result is a variable. Read its payload from its result\n wrapper, usually `resourceName.data`; APIs may nest the desired value deeper.\n- Collection creates internal `collectionItem` and `collectionItemKey`\n parameters. They are available only to that Collection\'s descendants.\n Preserve those generated parameters and do not reuse encoded parameter ids\n copied from another Collection.\n- Array Collection iteration exposes the current item. Object iteration exposes\n the current key and value.\n- The built-in `system` context is available only where supplied by the runtime.\n Its documented fields are `system.origin`, `system.pathname`, `system.params`,\n and `system.search`. There is no `system.path`.\n- Actions expose only their declared arguments, such as `event`, plus data that\n is in scope.\n\nRead `list-variables`, `list-resources`, `inspect-instance`, and existing\nbindings before writing an expression. Do not guess identifier names. Syntax is\nvalidated when a mutation is submitted, but an identifier that is unavailable\nat the final render scope may require preview verification to detect.\n\n## Supported Syntax\n\nExpressions support literals, arrays, objects, property and index access,\noptional chaining, unary and arithmetic operators, comparisons, logical\noperators, nullish coalescing, ternaries, and template literals.\n\nSupported string methods:\n\n{{allowedStringMethods}}\n\nSupported array methods:\n\n{{allowedArrayMethods}}\n\nOther values support `toString`. Arbitrary global functions and arbitrary\nmethod calls are not supported.\n\n## Unsupported Syntax\n\nDo not use statements, declarations, functions, arrow functions, classes,\n`new`, `this`, `await`, imports, tagged templates, sequence expressions,\nincrement/decrement, or destructuring assignment. Assignment is allowed only\ninside actions. Use an explicit assignment there rather than `++` or `--`.\n\n## Common Examples\n\n- Text: `post.title ?? "Untitled"`\n- Prop: `post.url`\n- Nested API array for Collection: `posts.data.items`\n- Resource URL: `"https://api.example.com/posts?tag=" + filters.tag`\n- Header: `"Bearer " + auth.token`\n- Search parameter: `String(filters.page ?? 1)` is not supported because global\n function calls are forbidden; use `(filters.page ?? 1).toString()` instead.\n- Resource body: `{ query: queryText, variables: { slug: system.params.slug } }`\n- Conditional: `featured ? "Featured" : "Standard"`\n- Safe nested access: `post.author?.name ?? "Unknown author"`\n\n## Collections\n\nWhenever an array or object should render repeated UI, call `insert-collection`\nwith the complete iterable and one repeated-item JSX root. Do not pass the\nresponse wrapper or one indexed item. The command creates the Collection and\nits private item parameters atomically, then renders the item root once per\nentry. Bind descendants with expressions such as `collectionItem.name`; for\nobject iteration, `collectionItemKey` contains the current key. Wrap multiple\nrepeated siblings in one `ws.element` root.\n\n## Verification\n\nAfter changing expressions, preview the affected page and verify representative\ndata, empty/null data, and Collection item counts. Use `audit` for relevant\nstructural findings, but do not treat a successful syntax parse as proof that\nruntime data has the expected shape.\n',
+ '# Webstudio Expressions\n\nUse an expression only when a value must be computed at runtime from scoped\ndata. Use direct text and direct prop values for fixed content.\n\n## Source Format\n\nExpression-capable MCP fields receive JavaScript expression source as a JSON\nstring. Send one expression, without a `return` statement or surrounding\nfunction. For example:\n\n```json\n{ "binding": { "type": "expression", "value": "post.title ?? \\"Untitled\\"" } }\n```\n\nDo not send a fixed prop string as an expression. Use `update-props` with\n`type:"string"`. Page metadata and resource URLs accept plain fixed strings and\nnormalize them for storage. Expression-only resource headers, search parameters,\nand bodies accept `{ "type": "literal", "value": "fixed text" }` when the\nvalue is not dynamic.\n\n## Scope\n\n- Data variables are available on their scope instance and descendants.\n- An inner variable with the same name masks the outer variable.\n- A scoped resource result is a variable. Read its payload from its result\n wrapper, usually `resourceName.data`; APIs may nest the desired value deeper.\n- Collection creates internal `collectionItem` and `collectionItemKey`\n parameters. They are available only to that Collection\'s descendants.\n Preserve those generated parameters and do not reuse encoded parameter ids\n copied from another Collection.\n- Array Collection iteration exposes the current item. Object iteration exposes\n the current key and value.\n- The built-in `system` context is available only where supplied by the runtime.\n Its documented fields are `system.origin`, `system.pathname`, `system.params`,\n and `system.search`. There is no `system.path`.\n- Actions expose only their declared arguments, such as `event`, plus data that\n is in scope.\n\nRead `list-variables`, `list-resources`, `inspect-instance`, and existing\nbindings before writing an expression. Do not guess identifier names. Syntax is\nvalidated when a mutation is submitted. A valid expression that references an\nidentifier unavailable in that scope is accepted with a structured warning\ncontaining the field path, source range, affected record, and remediation.\n\n## Supported Syntax\n\nExpressions support literals, arrays, objects, property and index access,\noptional chaining, unary and arithmetic operators, comparisons, logical\noperators, nullish coalescing, ternaries, and template literals.\n\nSupported string methods:\n\n{{allowedStringMethods}}\n\nSupported array methods:\n\n{{allowedArrayMethods}}\n\nOther values support `toString`. Arbitrary global functions and arbitrary\nmethod calls are not supported.\n\n## Unsupported Syntax\n\nDo not use statements, declarations, functions, arrow functions, classes,\n`new`, `this`, `await`, imports, tagged templates, sequence expressions,\nincrement/decrement, or destructuring assignment. Assignment is allowed only\ninside actions. Use an explicit assignment there rather than `++` or `--`.\n\n## Common Examples\n\n- Text: `post.title ?? "Untitled"`\n- Prop: `post.url`\n- Nested API array for Collection: `posts.data.items`\n- Resource URL: `"https://api.example.com/posts?tag=" + filters.tag`\n- Header: `"Bearer " + auth.token`\n- Search parameter: `String(filters.page ?? 1)` is not supported because global\n function calls are forbidden; use `(filters.page ?? 1).toString()` instead.\n- Resource body: `{ query: queryText, variables: { slug: system.params.slug } }`\n- Conditional: `featured ? "Featured" : "Standard"`\n- Safe nested access: `post.author?.name ?? "Unknown author"`\n\n## Collections\n\nWhenever an array or object should render repeated UI, call `insert-collection`\nwith the complete iterable and one repeated-item JSX root. Do not pass the\nresponse wrapper or one indexed item. The command creates the Collection and\nits private item parameters atomically, then renders the item root once per\nentry. Bind descendants with expressions such as `collectionItem.name`; for\nobject iteration, `collectionItemKey` contains the current key. Wrap multiple\nrepeated siblings in one `ws.element` root.\n\n## Verification\n\nInspect every returned expression warning. Correct warnings that indicate a\nmisspelled or unavailable variable, then read the affected record and preview\nthe page. A warning does not roll back the mutation, and a successful syntax\nparse does not prove runtime data has the expected shape. Verify representative\ndata, empty/null data, and Collection item counts; use `audit` for relevant\nstructural findings.\n',
"mcp-startup-guidance":
'If you are inside the Webstudio monorepo, use the local CLI exactly as `node packages/cli/local.js ...` as your first command path. Do not use `packages/cli/bin.js` for local source-tree work; it is the packaged build entry and may use stale built output. Before editing a Webstudio project, do one small discovery step, then act. For delegated design-system or “use every component” tasks, the first MCP command is `workflow.next {"goal":"design-system-page"}`; report that returned checkpoint to the parent/user and stop until continued. For a simple authored/styled section, the intended path is literal: call `meta.index`, call `meta.get_more_tools` with `{"tools":["insert-fragment"]}`, read the target parent id with `list-pages`/`get-page-by-path`/`list-instances` only if needed, then call `insert-fragment`. Prefer `insert-fragment` for authored/styled sections; use `insert-component` only when inserting one automatic component template. Do not grep source files, dump full MCP resources, or write parser scripts before trying focused MCP calls. Good first calls are `meta.index` for orientation, `meta.guide` for a goal workflow, `workflow.next` for one bounded delegated phase, `meta.get_more_tools` for exact tool schemas, and `components.coverage-plan`, `components.coverage-insert-next`, `components.find`, or `components.get` for component work. Do not call every discovery tool up front. For delegated or non-streaming agents whose parent cannot see live stderr/stdout, treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one shortcut command such as `webstudio meta.index` or one explicit `webstudio mcp single-op-call` command, report its command/result, and wait for the parent before the next MCP command. Do not run long shell loops of shortcut or `webstudio mcp single-op-call` commands; they hide progress from the parent. Do not take a broad task such as creating a full design-system page as one execution unit. Instead call `workflow.next {"goal":"design-system-page"}`, report the returned phase/checkpoint to the parent, wait until the parent continues, call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`, complete exactly that bounded phase, and return: discovery, page creation, one dry-run JSX section, one committed JSX section, one `components.coverage-insert-next` call, or one presentation pass. Phase commands do not include nextPhase in their own output. After the parent continues, acknowledge the previous checkpoint first, then call `workflow.next` with the next phase. For design-system or “use every component” tasks, start with `workflow.next`, acknowledge its checkpoint only after parent/user continuation, then run compact `components.coverage-plan`, checkpoint, create the page, checkpoint, then call `components.coverage-insert-next` once per coverage checkpoint, and finish with the `presentation-pass` workflow phase. Coverage 72/72 is necessary but not sufficient: the page must be organized into styled, real-world design-system examples instead of raw unstyled component dumps. Request component coverage details with `components.coverage-plan {"detail":"roots"}` or `components.coverage-plan {"detail":"parts"}` only when needed. `list-pages` does not accept `detail`; use `list-pages {}` or `get-page-by-path` for page lookup. Read overview resources such as `webstudio://project/guide`, `webstudio://project/tools-overview`, and `webstudio://project/components-overview` only when focused tools are insufficient. Do not dump or parse full resources such as `webstudio://project/tools` or `webstudio://project/components` unless the focused tools are insufficient. Run one-shot shortcut or explicit `webstudio mcp single-op-call` commands sequentially against the same linked `.webstudio` folder. For experiments, pass `--dry-run` to local-capable mutations. Copying a `.webstudio` folder is not an isolated project clone; `.webstudio/config.json` still points to the same remote project, so non-dry-run mutations can commit to that project. If a one-shot call returns checkpoint.required, the CLI persists `CHECKPOINT_REQUIRED` across later one-shot calls until you report the checkpoint, wait until continued, and call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`. If you receive `PROJECT_SESSION_BUSY`, another CLI/MCP process is updating the local session; wait a moment and retry sequentially. Complete one bounded phase and return a checkpoint before continuing. Follow the guide: read ids and Builder breakpoints first, use focused component discovery for component ids, props, and content model composition, prefer semantic tools over `apply-patch`, use direct value tools for fixed text/props, use bindings only for dynamic expressions/resources/actions, page metadata and fixed resource URLs accept plain strings, put page/resource update fields under `values`, do not edit generated files for normal content/design changes, and use `preview.start` plus screenshot/vision for visual work.\n',
} as const;
diff --git a/packages/project-build/src/docs/expressions.md b/packages/project-build/src/docs/expressions.md
index 4f7f8ddc7c..b5905c1cf9 100644
--- a/packages/project-build/src/docs/expressions.md
+++ b/packages/project-build/src/docs/expressions.md
@@ -39,8 +39,9 @@ value is not dynamic.
Read `list-variables`, `list-resources`, `inspect-instance`, and existing
bindings before writing an expression. Do not guess identifier names. Syntax is
-validated when a mutation is submitted, but an identifier that is unavailable
-at the final render scope may require preview verification to detect.
+validated when a mutation is submitted. A valid expression that references an
+identifier unavailable in that scope is accepted with a structured warning
+containing the field path, source range, affected record, and remediation.
## Supported Syntax
@@ -91,7 +92,9 @@ repeated siblings in one `ws.element` root.
## Verification
-After changing expressions, preview the affected page and verify representative
-data, empty/null data, and Collection item counts. Use `audit` for relevant
-structural findings, but do not treat a successful syntax parse as proof that
-runtime data has the expected shape.
+Inspect every returned expression warning. Correct warnings that indicate a
+misspelled or unavailable variable, then read the affected record and preview
+the page. A warning does not roll back the mutation, and a successful syntax
+parse does not prove runtime data has the expected shape. Verify representative
+data, empty/null data, and Collection item counts; use `audit` for relevant
+structural findings.
diff --git a/packages/project-build/src/entrypoints.test.ts b/packages/project-build/src/entrypoints.test.ts
new file mode 100644
index 0000000000..1f46c6cfd1
--- /dev/null
+++ b/packages/project-build/src/entrypoints.test.ts
@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+
+type PackageExport = Record<string, string>;
+
+const packageJson = JSON.parse(
+ readFileSync(new URL("../package.json", import.meta.url), "utf8")
+) as { exports: Record<string, PackageExport> };
+
+describe("package entrypoints", () => {
+ test("exposes architectural surfaces instead of source-file paths", () => {
+ const entrypoints = Object.keys(packageJson.exports);
+
+ expect(entrypoints.length).toBeLessThanOrEqual(11);
+ expect(
+ entrypoints.filter((entrypoint) => entrypoint.split("/").length > 2)
+ ).toEqual(["./transfer/server"]);
+ });
+
+ test("does not expose Node-only surfaces through generic conditions", () => {
+ for (const entrypoint of [
+ "./mcp",
+ "./visual",
+ "./transfer/server",
+ "./server",
+ ]) {
+ expect(packageJson.exports[entrypoint]).toEqual({
+ webstudio: expect.any(String),
+ });
+ }
+ });
+});
diff --git a/packages/project-build/src/index.ts b/packages/project-build/src/index.ts
index 3bbf931553..09d7804f7f 100644
--- a/packages/project-build/src/index.ts
+++ b/packages/project-build/src/index.ts
@@ -1,9 +1,4 @@
export * from "./types";
-export * from "./db/build-parser";
-export * from "./db/pages";
-export * from "./db/style-source-selections";
-export * from "./db/styles";
export * from "./shared/pages-utils";
export * from "./shared/marketplace";
export * from "./shared/project-settings";
-export * from "./shared/graph-utils";
diff --git a/packages/project-build/src/mcp-rendered-audit.test.ts b/packages/project-build/src/mcp-rendered-audit.test.ts
index c1e9bb5b4b..306b471298 100644
--- a/packages/project-build/src/mcp-rendered-audit.test.ts
+++ b/packages/project-build/src/mcp-rendered-audit.test.ts
@@ -493,6 +493,40 @@ describe("rendered audit evidence", () => {
).not.toHaveProperty("failureCode");
});
+ test("does not hide real failures behind a confirmation state", () => {
+ const result = mergeRenderedAudit({
+ envelope: {
+ operationId: "project.audit",
+ source: "remote",
+ projectId: "project",
+ buildId: "build",
+ version: 1,
+ committed: false,
+ result: { scopes: ["performance"], manualCheckCount: 0 },
+ } as never,
+ input: { rendered: true },
+ checks: [],
+ failures: [
+ {
+ code: "RENDERED_AUDIT_CONFIRMATION_REQUIRED",
+ phase: "planning",
+ retryable: false,
+ remediation: "Confirm the planned run.",
+ message: "Confirmation required.",
+ },
+ {
+ code: "RENDERED_AUDIT_SCREENSHOT_FAILED",
+ phase: "capture",
+ retryable: true,
+ remediation: "Retry the capture.",
+ message: "Capture failed.",
+ },
+ ],
+ });
+
+ expect(result.result).toMatchObject({ renderedState: "failed" });
+ });
+
test("summarizes rendered issue kinds in compact results", () => {
const result = mergeRenderedAudit({
envelope: {
@@ -738,6 +772,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "failed",
renderedCheckCount: 0,
renderedFailureCount: 1,
renderedCaptureSummary: {
@@ -820,6 +855,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "complete",
renderedCheckCount: 1,
renderedFailureCount: 0,
renderedCaptureSummary: {
@@ -832,6 +868,74 @@ describe("rendered audit evidence", () => {
});
});
+ test("returns partial evidence when one capture succeeds and one fails", async () => {
+ const stopPreview = vi.fn();
+ const result = await augmentAuditWithRenderedChecks({
+ envelope: {
+ operationId: "project.audit",
+ source: "remote",
+ projectId: "project",
+ buildId: "build",
+ version: 1,
+ committed: false,
+ result: {
+ scopes: ["performance"],
+ manualCheckCount: 0,
+ verbose: true,
+ },
+ } as never,
+ input: { rendered: true, verbose: true },
+ executeRead: async (command) =>
+ ({
+ result:
+ command === "list-pages"
+ ? {
+ pages: [
+ { id: "good", path: "/good" },
+ { id: "bad", path: "/bad" },
+ ],
+ }
+ : { breakpoints: [] },
+ }) as never,
+ startPreview: vi.fn(),
+ stopPreview,
+ captureScreenshot: vi.fn(async (input) => {
+ if (input.path === "/bad") {
+ throw new Error("browser page closed");
+ }
+ return {
+ output: "/tmp/good.png",
+ browserPath: "/usr/bin/chromium",
+ browser: "chromium" as const,
+ viewport: input.viewport,
+ fullPage: true,
+ elapsedMs: 1,
+ warnings: [],
+ navigation: getNavigation("/good"),
+ layout,
+ };
+ }),
+ });
+
+ expect(result.result).toMatchObject({
+ renderedState: "partial",
+ renderedCheckCount: 1,
+ renderedFailureCount: 1,
+ renderedCaptureSummary: {
+ planned: 2,
+ passed: 1,
+ failed: 1,
+ },
+ renderedFailures: [
+ expect.objectContaining({
+ code: "RENDERED_AUDIT_SCREENSHOT_FAILED",
+ retryable: true,
+ }),
+ ],
+ });
+ expect(stopPreview).toHaveBeenCalledOnce();
+ });
+
test("accepts a generated non-HTML document without an HTML marker", async () => {
const result = await augmentAuditWithRenderedChecks({
envelope: {
@@ -875,6 +979,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "complete",
renderedCheckCount: 1,
renderedFailureCount: 0,
renderedCaptureSummary: {
@@ -919,6 +1024,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "failed",
renderedCheckCount: 0,
renderedFailureCount: 1,
renderedCaptureSummary: {
@@ -965,6 +1071,7 @@ describe("rendered audit evidence", () => {
expect(captureScreenshot).not.toHaveBeenCalled();
expect(result.result).toMatchObject({
+ renderedState: "failed",
renderedFailureCount: 1,
renderedCaptureSummary: { planned: 1, failed: 1 },
renderedFailures: [
@@ -1032,6 +1139,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "confirmation-required",
renderedPlan: {
version: 1,
pages: expect.arrayContaining([
@@ -1091,6 +1199,7 @@ describe("rendered audit evidence", () => {
});
expect(confirmed.result).toMatchObject({
+ renderedState: "complete",
renderedCheckCount: 122,
renderedFailureCount: 0,
renderedCaptureSummary: {
@@ -1144,6 +1253,7 @@ describe("rendered audit evidence", () => {
captureScreenshot,
});
expect(stale.result).toMatchObject({
+ renderedState: "confirmation-required",
renderedCheckCount: 0,
renderedFailures: [
expect.objectContaining({
@@ -1191,6 +1301,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "failed",
renderedPlan: {
pages: [],
excludedPages: [
@@ -1261,6 +1372,7 @@ describe("rendered audit evidence", () => {
});
expect(result.result).toMatchObject({
+ renderedState: "failed",
renderedCheckCount: 0,
renderedCaptureSummary: {
planned: 1,
diff --git a/packages/project-build/src/mcp-rendered-audit.ts b/packages/project-build/src/mcp-rendered-audit.ts
index 51210c3767..f1f017c8e6 100644
--- a/packages/project-build/src/mcp-rendered-audit.ts
+++ b/packages/project-build/src/mcp-rendered-audit.ts
@@ -698,6 +698,20 @@ const mergeRenderedAudit = ({
isVerbose && Array.isArray(result.manualChecks)
? result.manualChecks
: undefined;
+ const confirmationRequired =
+ failures.length > 0 &&
+ failures.every(
+ ({ code }) =>
+ code === "RENDERED_AUDIT_CONFIRMATION_REQUIRED" ||
+ code === "RENDERED_AUDIT_CONFIRMATION_INVALID"
+ );
+ const renderedState = confirmationRequired
+ ? ("confirmation-required" as const)
+ : failures.length === 0
+ ? ("complete" as const)
+ : checks.length === 0
+ ? ("failed" as const)
+ : ("partial" as const);
return {
...envelope,
result: {
@@ -705,6 +719,7 @@ const mergeRenderedAudit = ({
renderedCheckCount: checks.length,
renderedIssueCount,
renderedFailureCount: failures.length,
+ renderedState,
renderedPlan: plan ?? null,
renderedCaptureSummary,
renderedCaptureStatuses,
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index 6b8578850f..86e508fd2e 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -1492,6 +1492,7 @@ describe("project session mcp adapter", () => {
);
expect(accessibilityResult.structuredContent.data).toMatchObject({
scopes: ["accessibility"],
+ renderedState: "complete",
renderedCheckCount: 2,
renderedIssueCount: 1,
renderedChecks: [
@@ -1579,6 +1580,7 @@ describe("project session mcp adapter", () => {
},
});
expect(result.structuredContent.data).toMatchObject({
+ renderedState: "failed",
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 1,
@@ -1660,6 +1662,7 @@ describe("project session mcp adapter", () => {
});
expect(result.structuredContent.data).toMatchObject({
+ renderedState: "failed",
renderedFailureCount: 1,
renderedFailureSummaries: [
{
@@ -1758,6 +1761,7 @@ describe("project session mcp adapter", () => {
expect(result.structuredContent).toMatchObject({
ok: true,
data: {
+ renderedState: "confirmation-required",
renderedPlan: {
captureCount: 121,
confirmationToken: expect.any(String),
diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.ts
index 31a4c15b99..1abad49505 100644
--- a/packages/project-build/src/mcp.ts
+++ b/packages/project-build/src/mcp.ts
@@ -16,7 +16,6 @@ import type { BuilderApiCapability } from "./contracts/permissions";
import path from "node:path";
import {
projectSessionBusyMessage,
- serializeProjectSessionDebug,
serializeProjectSessionMeta,
type ProjectSessionEnvelope,
} from "./project-session";
@@ -77,6 +76,8 @@ import {
} from "./runtime/errors";
import { z } from "zod";
+export { paginateOutput, projectOutput } from "./runtime/output";
+
type PublicMcpOperationMethod = "query" | "mutation";
type PublicMcpOperationPermit = BuilderApiCapability;
@@ -2281,9 +2282,7 @@ type ProjectSessionMcpStructuredContent =
ok: true;
data: unknown;
meta: {
- session?:
- | ReturnType<typeof serializeProjectSessionMeta>
- | ReturnType<typeof serializeProjectSessionDebug>;
+ session?: ReturnType<typeof serializeProjectSessionMeta>;
};
}
| {
@@ -2291,9 +2290,7 @@ type ProjectSessionMcpStructuredContent =
data: unknown;
error: McpStructuredError;
meta: {
- session?:
- | ReturnType<typeof serializeProjectSessionMeta>
- | ReturnType<typeof serializeProjectSessionDebug>;
+ session?: ReturnType<typeof serializeProjectSessionMeta>;
};
};
@@ -4762,10 +4759,9 @@ const toCallResult = (
} = {}
): ProjectSessionMcpToolResult => {
const meta = {
- session:
- options.verboseSession === true
- ? serializeProjectSessionDebug(envelope)
- : serializeProjectSessionMeta(envelope),
+ session: serializeProjectSessionMeta(envelope, {
+ verbose: options.verboseSession,
+ }),
};
const structuredContent: ProjectSessionMcpStructuredContent =
options.error === undefined
@@ -4799,39 +4795,23 @@ const getRenderedAuditError = (
if (rendered === false || isRecord(envelope.result) === false) {
return undefined;
}
- const failureCount = envelope.result.renderedFailureCount;
- if (typeof failureCount !== "number" || failureCount === 0) {
- return undefined;
- }
- const failures = Array.isArray(envelope.result.renderedFailures)
- ? envelope.result.renderedFailures
- : envelope.result.renderedFailureSummaries;
- const confirmationRequired =
- Array.isArray(failures) &&
- failures.length > 0 &&
- failures.every(
- (failure) =>
- isRecord(failure) &&
- failure.code === "RENDERED_AUDIT_CONFIRMATION_REQUIRED"
- );
- if (confirmationRequired) {
+ const state = envelope.result.renderedState;
+ if (state === "complete" || state === "confirmation-required") {
return undefined;
}
- const checkCount =
- typeof envelope.result.renderedCheckCount === "number"
- ? envelope.result.renderedCheckCount
- : 0;
- return checkCount === 0
+ return state === "failed"
? {
code: "RENDERED_AUDIT_FAILED",
message:
"The static audit completed, but the requested rendered audit completed no rendered checks.",
}
- : {
- code: "RENDERED_AUDIT_PARTIAL",
- message:
- "The static audit completed, but some requested rendered checks failed.",
- };
+ : state === "partial"
+ ? {
+ code: "RENDERED_AUDIT_PARTIAL",
+ message:
+ "The static audit completed, but some requested rendered checks failed.",
+ }
+ : undefined;
};
const toResourceContent = (
diff --git a/packages/project-build/src/persistence.ts b/packages/project-build/src/persistence.ts
new file mode 100644
index 0000000000..ebcadc3d82
--- /dev/null
+++ b/packages/project-build/src/persistence.ts
@@ -0,0 +1,5 @@
+export * from "./db/build-parser";
+export * from "./db/deployment";
+export * from "./db/pages";
+export * from "./db/styles";
+export * from "./db/style-source-selections";
diff --git a/packages/project-build/src/project-session.test.ts b/packages/project-build/src/project-session.test.ts
index 62216515b4..e7d8363567 100644
--- a/packages/project-build/src/project-session.test.ts
+++ b/packages/project-build/src/project-session.test.ts
@@ -515,6 +515,40 @@ describe("project session", () => {
},
],
});
+ const compact = serializeProjectSessionMeta(result);
+ const verbose = serializeProjectSessionMeta(result, { verbose: true });
+ expect(compact).not.toHaveProperty("namespaces");
+ expect(verbose).toMatchObject({
+ ...compact,
+ namespaces: result.namespaces,
+ freshness: result.state.freshness,
+ });
+ expect(JSON.stringify(compact).length).toBeLessThan(
+ JSON.stringify(verbose).length * 0.75
+ );
+
+ const withSecretDiagnostic = {
+ ...result,
+ diagnostics: [
+ ...result.diagnostics,
+ {
+ level: "warning" as const,
+ code: "TEST_DIAGNOSTIC",
+ message:
+ "A credential was rejected at https://example.com/?authToken=also-never-print-this.",
+ details: { authToken: "never-print-this" },
+ },
+ ],
+ };
+ expect(
+ JSON.stringify(serializeProjectSessionMeta(withSecretDiagnostic))
+ ).not.toContain("never-print-this");
+ const redactedVerbose = JSON.stringify(
+ serializeProjectSessionMeta(withSecretDiagnostic, { verbose: true })
+ );
+ expect(redactedVerbose).not.toContain("never-print-this");
+ expect(redactedVerbose).not.toContain("also-never-print-this");
+ expect(redactedVerbose).toContain("[redacted]");
expect(transport.commits).toEqual([]);
expect(storage.saved).toHaveLength(0);
});
diff --git a/packages/project-build/src/project-session.ts b/packages/project-build/src/project-session.ts
index 972651495f..2257c96d06 100644
--- a/packages/project-build/src/project-session.ts
+++ b/packages/project-build/src/project-session.ts
@@ -8,6 +8,7 @@ import type { BuilderNamespace } from "./contracts/namespaces";
import type { BuilderPatchTransaction } from "./contracts/patch";
import { hasGeneratedRecordWritePatch } from "./contracts/patch";
import type { BuilderApiCapability } from "./contracts/permissions";
+import { projectOutput } from "./runtime/output";
import {
builderRuntimeContext,
type BuilderRuntimeContext,
@@ -15,6 +16,7 @@ import {
import {
BuilderRuntimeError,
getValidationIssues,
+ sanitizeValidationDetail,
type SemanticValidationIssue,
} from "./runtime/errors";
import type { BuilderRuntimeMutation } from "./runtime/mutation";
@@ -166,17 +168,18 @@ const getNamespaceCounts = (envelope: ProjectSessionEnvelope) =>
) as Record<keyof ProjectSessionEnvelope["namespaces"], number>;
export const serializeProjectSessionMeta = (
- envelope: ProjectSessionEnvelope
+ envelope: ProjectSessionEnvelope,
+ input: { verbose?: boolean } = {}
) => {
const diagnostics = envelope.diagnostics.map(({ level, code, message }) => ({
level,
code,
- message,
+ message: sanitizeValidationDetail(message),
}));
const diagnosticErrorCount = diagnostics.filter(
(diagnostic) => diagnostic.level === "error"
).length;
- return {
+ const compact = {
operationId: envelope.operationId,
projectId: envelope.projectId,
...(envelope.buildId === undefined ? {} : { buildId: envelope.buildId }),
@@ -196,18 +199,18 @@ export const serializeProjectSessionMeta = (
? {}
: { transaction: envelope.transaction }),
};
+ return projectOutput({
+ input,
+ compact,
+ expanded: () => ({
+ namespaces: envelope.namespaces,
+ freshness: envelope.state.freshness,
+ compatibility: envelope.state.compatibility,
+ diagnostics: redactProjectSessionValue(envelope.diagnostics),
+ }),
+ });
};
-export const serializeProjectSessionDebug = (
- envelope: ProjectSessionEnvelope
-) => ({
- ...serializeProjectSessionMeta(envelope),
- namespaces: envelope.namespaces,
- freshness: envelope.state.freshness,
- compatibility: envelope.state.compatibility,
- diagnostics: envelope.diagnostics,
-});
-
export type ProjectSessionMutationOptions = {
dryRun?: boolean;
permit?: BuilderApiCapability;
@@ -435,6 +438,9 @@ export const redactProjectSessionValue = (value: unknown): unknown => {
if (Array.isArray(value)) {
return value.map(redactProjectSessionValue);
}
+ if (typeof value === "string") {
+ return sanitizeValidationDetail(value);
+ }
if (typeof value !== "object" || value === null) {
return value;
}
diff --git a/packages/project-build/src/runtime.ts b/packages/project-build/src/runtime.ts
new file mode 100644
index 0000000000..f840337f09
--- /dev/null
+++ b/packages/project-build/src/runtime.ts
@@ -0,0 +1,38 @@
+export * from "./build-integrity";
+export * from "./shared/graph-utils";
+export * from "./runtime/assets";
+export * from "./runtime/auth";
+export * from "./runtime/block";
+export * from "./runtime/breakpoints";
+export * from "./runtime/component-catalog";
+export * from "./runtime/component-template";
+export * from "./runtime/content-mode-copy-policy";
+export * from "./runtime/content-mode-permissions";
+export * from "./runtime/content-model";
+export * from "./runtime/context";
+export * from "./runtime/data";
+export * from "./runtime/errors";
+export * from "./runtime/expression-validation";
+export * from "./runtime/fragment";
+export * from "./runtime/html";
+export * from "./runtime/insert-target";
+export * from "./runtime/instance-path";
+export * from "./runtime/instance-duplicate";
+export * from "./runtime/instances";
+export * from "./runtime/lookup";
+export * from "./runtime/matcher";
+export * from "./runtime/mutation";
+export * from "./runtime/page-copy";
+export * from "./runtime/pages";
+export * from "./runtime/project-settings";
+export * from "./runtime/props";
+export * from "./runtime/redirect-loop-detection";
+export * from "./runtime/redirect-parsers";
+export * from "./runtime/redirect-source";
+export * from "./runtime/registry";
+export * from "./runtime/slot";
+export * from "./runtime/style-copy";
+export * from "./runtime/style-utils";
+export * from "./runtime/styles";
+export * from "./runtime/tree";
+export * from "./runtime/url-pattern";
diff --git a/packages/project-build/src/runtime/assets.test.ts b/packages/project-build/src/runtime/assets.test.ts
index d759c67305..e2024daa5f 100644
--- a/packages/project-build/src/runtime/assets.test.ts
+++ b/packages/project-build/src/runtime/assets.test.ts
@@ -253,7 +253,7 @@ describe("asset runtime operations", () => {
test("lists assets with usage counts", () => {
expect(listAssets(state, { sort: "usage" })).toMatchObject({
items: [
- { id: "asset", description: null, usageCount: 1 },
+ { id: "asset", usageCount: 1 },
{ id: "next", usageCount: 0 },
{ id: "unused", usageCount: 0 },
],
@@ -261,19 +261,33 @@ describe("asset runtime operations", () => {
});
});
- test("lists asset descriptions used as image alt text", () => {
+ test("expands asset descriptions only in verbose output", () => {
const asset = imageAsset("described");
- asset.description = "Team collaborating around a whiteboard";
- expect(
- listAssets({ ...state, assets: new Map([[asset.id, asset]]) })
- ).toMatchObject({
+ asset.description = `Team collaborating around a whiteboard. ${"Detailed visual context. ".repeat(80)}`;
+ const assetState = { ...state, assets: new Map([[asset.id, asset]]) };
+ const compact = listAssets(assetState);
+ const verbose = listAssets(assetState, { verbose: true });
+ expect(compact).toMatchObject({
+ detail: "compact",
+ items: [{ id: "described" }],
+ });
+ expect(compact.items[0]).not.toHaveProperty("description");
+ expect(verbose).toMatchObject({
+ detail: "verbose",
items: [
{
id: "described",
- description: "Team collaborating around a whiteboard",
+ record: {
+ description: expect.stringContaining(
+ "Team collaborating around a whiteboard"
+ ),
+ },
},
],
});
+ expect(JSON.stringify(compact).length).toBeLessThan(
+ JSON.stringify(verbose).length * 0.5
+ );
});
test("lists editable filenames separately from immutable asset names", () => {
diff --git a/packages/project-build/src/runtime/assets.ts b/packages/project-build/src/runtime/assets.ts
index 451c18ccfc..05e22142d4 100644
--- a/packages/project-build/src/runtime/assets.ts
+++ b/packages/project-build/src/runtime/assets.ts
@@ -21,6 +21,11 @@ import {
imageAsset,
} from "@webstudio-is/sdk";
import type { BuilderPatchChange } from "../contracts/patch";
+import {
+ paginateOutput,
+ projectOutput,
+ type PaginatedOutputInput,
+} from "./output";
import type { BuilderState } from "../state/builder-state";
import type { CompactBuild } from "../types";
import type { ProjectSettings } from "../shared/project-settings";
@@ -754,11 +759,9 @@ const serializeAssetSummary = (asset: Asset) => ({
id: asset.id,
name: asset.name,
filename: asset.filename,
- description: asset.description,
type: asset.type,
size: asset.size,
contentType: asset.format,
- createdAt: asset.createdAt,
});
export const serializeAssetList = ({
@@ -768,12 +771,10 @@ export const serializeAssetList = ({
}: {
assets: Asset[];
build?: AssetReferenceBuild;
- input: {
+ input: PaginatedOutputInput & {
type?: "image" | "font";
withUsage?: boolean;
sort?: "name" | "size" | "createdAt" | "usage";
- cursor?: string;
- limit?: number;
};
}) => {
const shouldCountUsage = input.withUsage === true || input.sort === "usage";
@@ -781,14 +782,9 @@ export const serializeAssetList = ({
shouldCountUsage && build !== undefined
? getAssetUsageCounts(build, assets)
: undefined;
- const sorted = assets
- .filter((asset) => input.type === undefined || asset.type === input.type)
- .map((asset) => ({
- ...serializeAssetSummary(asset),
- usageCount: shouldCountUsage
- ? (usageCounts?.get(asset.id) ?? 0)
- : undefined,
- }));
+ const sorted = assets.filter(
+ (asset) => input.type === undefined || asset.type === input.type
+ );
sorted.sort((left, right) => {
switch (input.sort) {
case "size":
@@ -796,23 +792,38 @@ export const serializeAssetList = ({
case "createdAt":
return right.createdAt.localeCompare(left.createdAt);
case "usage":
- return (right.usageCount ?? 0) - (left.usageCount ?? 0);
+ return (
+ (usageCounts?.get(right.id) ?? 0) - (usageCounts?.get(left.id) ?? 0)
+ );
case "name":
default:
return left.name.localeCompare(right.name);
}
});
- const start = input.cursor === undefined ? 0 : Number(input.cursor);
- if (Number.isInteger(start) === false || start < 0) {
- throw new Error("Invalid asset cursor");
- }
- const limit = input.limit ?? sorted.length;
- const items = sorted.slice(start, start + limit);
- const nextIndex = start + items.length;
- return {
- items,
- nextCursor: nextIndex < sorted.length ? String(nextIndex) : null,
- };
+ const projected = sorted.map((asset) =>
+ projectOutput({
+ input,
+ compact: {
+ ...serializeAssetSummary(asset),
+ usageCount: shouldCountUsage
+ ? (usageCounts?.get(asset.id) ?? 0)
+ : undefined,
+ },
+ expanded: () => ({ record: asset }),
+ })
+ );
+ return paginateOutput({
+ items: projected,
+ cursor: input.cursor,
+ limit: input.limit,
+ filters: {
+ type: input.type,
+ withUsage: input.withUsage,
+ sort: input.sort,
+ },
+ verbose: input.verbose,
+ invalidCursorMessage: "Invalid asset cursor",
+ });
};
export const createAssetUsageList = ({
@@ -915,12 +926,10 @@ export const listAssets = (
| "resources"
| "dataSources"
>,
- input: {
+ input: PaginatedOutputInput & {
type?: "image" | "font";
withUsage?: boolean;
sort?: "name" | "size" | "createdAt" | "usage";
- cursor?: string;
- limit?: number;
} = {}
) => {
try {
diff --git a/packages/project-build/src/runtime/audit.ts b/packages/project-build/src/runtime/audit.ts
index c26aa6aacd..b96a0572a3 100644
--- a/packages/project-build/src/runtime/audit.ts
+++ b/packages/project-build/src/runtime/audit.ts
@@ -419,6 +419,12 @@ const auditResultBase = z.object({
renderedCheckCount: z.number().int().nonnegative(),
renderedIssueCount: z.number().int().nonnegative(),
renderedFailureCount: z.number().int().nonnegative(),
+ renderedState: z.enum([
+ "complete",
+ "partial",
+ "confirmation-required",
+ "failed",
+ ]),
renderedPlan: renderedAuditPlan.nullable(),
renderedCaptureSummary: renderedAuditCaptureSummary,
renderedCaptureStatuses: z.array(renderedAuditCaptureStatus),
@@ -1237,6 +1243,7 @@ export function audit(
renderedIssueCount: 0,
renderedIssueSummaries: [],
renderedFailureCount: 0,
+ renderedState: "complete",
renderedFailureSummaries: [],
renderedPlan: null,
renderedCaptureSummary: {
diff --git a/packages/project-build/src/runtime/content-mode-copy-policy.ts b/packages/project-build/src/runtime/content-mode-copy-policy.ts
index 63c777f18d..4a40403b39 100644
--- a/packages/project-build/src/runtime/content-mode-copy-policy.ts
+++ b/packages/project-build/src/runtime/content-mode-copy-policy.ts
@@ -1,7 +1,7 @@
import {
getContentModeCapabilities,
isContentModeCopyableProp,
-} from "@webstudio-is/project-build/runtime/content-mode-permissions";
+} from "./content-mode-permissions";
import type {
Instance,
Prop,
diff --git a/packages/project-build/src/runtime/content-mode-permissions.test.ts b/packages/project-build/src/runtime/content-mode-permissions.test.ts
index 141036a8c6..2a17d24156 100644
--- a/packages/project-build/src/runtime/content-mode-permissions.test.ts
+++ b/packages/project-build/src/runtime/content-mode-permissions.test.ts
@@ -11,7 +11,7 @@ import type {
WsComponentMeta,
} from "@webstudio-is/sdk";
import {
- __testing__,
+ contentModePermissionsTesting,
applyContentModeTransaction,
getContentModeCapabilities,
getContentModeEditableInstanceIds,
@@ -28,7 +28,7 @@ const {
isContentModePageMetaValue,
isContentModePropPatchValue,
validateEditableInstanceReferences,
-} = __testing__;
+} = contentModePermissionsTesting;
const metas = new Map<string, WsComponentMeta>([
[
diff --git a/packages/project-build/src/runtime/content-mode-permissions.ts b/packages/project-build/src/runtime/content-mode-permissions.ts
index ffe1c13c15..817bd68738 100644
--- a/packages/project-build/src/runtime/content-mode-permissions.ts
+++ b/packages/project-build/src/runtime/content-mode-permissions.ts
@@ -1093,7 +1093,7 @@ const validateEditableInstanceReferences = (
return { success: true };
};
-export const __testing__ = {
+export const contentModePermissionsTesting = {
isContentModePageMetaValue,
hasOnlyContentModePageMeta,
hasOnlyAddedInstancesInSubtree,
diff --git a/packages/project-build/src/runtime/content-model.ts b/packages/project-build/src/runtime/content-model.ts
index 5bc0cdb227..696e9f7999 100644
--- a/packages/project-build/src/runtime/content-model.ts
+++ b/packages/project-build/src/runtime/content-model.ts
@@ -11,8 +11,7 @@ import {
type WsComponentMeta,
} from "@webstudio-is/sdk";
import { setIsSubsetOf } from "./set-utils";
-
-export type InstanceSelector = Instance["id"][];
+import type { InstanceSelector } from "./instance-path";
type Metas = Map<Instance["component"], WsComponentMeta>;
type HtmlTagsByInstanceId = Map<Instance["id"], string>;
diff --git a/packages/project-build/src/runtime/data.test.tsx b/packages/project-build/src/runtime/data.test.tsx
index 99f588ed39..8644af644e 100644
--- a/packages/project-build/src/runtime/data.test.tsx
+++ b/packages/project-build/src/runtime/data.test.tsx
@@ -2435,7 +2435,13 @@ describe("resource patch helpers", () => {
expect(result.result).toMatchObject({
dataSourceId: "data-source-id",
warnings: [
- "The POST resource is explicitly exposed as render-time data and may execute while rendering the page.",
+ expect.objectContaining({
+ code: "render_time_mutation_resource",
+ path: ["resource", "method"],
+ resourceId: "resource-id",
+ message: expect.stringContaining("may execute while rendering"),
+ remediation: expect.stringContaining("explicit action"),
+ }),
],
});
expect(result.payload).toContainEqual(
@@ -3225,7 +3231,12 @@ describe("resource patch helpers", () => {
expect(result.result).toMatchObject({
resourceId: "resource",
dataSourceId: "data-source",
- warnings: [],
+ warnings: [
+ expect.objectContaining({
+ code: "render_time_mutation_resource",
+ resourceId: "resource",
+ }),
+ ],
});
expect(result.payload).not.toContainEqual({
namespace: "dataSources",
@@ -3233,6 +3244,30 @@ describe("resource patch helpers", () => {
});
});
+ test("reports updated resource expression warnings at input paths", () => {
+ const state = createResourceState();
+ state.resources.set("resource", resource);
+
+ const result = updateResource(
+ state,
+ {
+ resourceId: "resource",
+ values: { body: "missingPayload" },
+ },
+ { createId: () => "unused-id" }
+ );
+
+ expect(result.result).toMatchObject({
+ warnings: [
+ expect.objectContaining({
+ code: "expression_lint_warning",
+ path: ["values", "body"],
+ resourceId: "resource",
+ }),
+ ],
+ });
+ });
+
test("can explicitly attach and detach render data on update", () => {
const state = createResourceState();
state.instances.set("body", {
@@ -3257,7 +3292,13 @@ describe("resource patch helpers", () => {
expect(attached.result).toMatchObject({
dataSourceId: "data-source",
warnings: [
- "The POST resource is explicitly exposed as render-time data and may execute while rendering the page.",
+ expect.objectContaining({
+ code: "render_time_mutation_resource",
+ path: ["values", "method"],
+ resourceId: "resource",
+ message: expect.stringContaining("may execute while rendering"),
+ remediation: expect.stringContaining("explicit action"),
+ }),
],
});
expect(attached.payload).toContainEqual(
diff --git a/packages/project-build/src/runtime/data.ts b/packages/project-build/src/runtime/data.ts
index b7442519b4..87e2a9838b 100644
--- a/packages/project-build/src/runtime/data.ts
+++ b/packages/project-build/src/runtime/data.ts
@@ -56,6 +56,7 @@ import { getStaticStringLiteral, replaceTextValue } from "./text-replacement";
import {
getNamedExpressionErrors,
getNamedExpressionValidationIssues,
+ getExpressionWarnings,
hasExpressionDiagnostics,
} from "./expression-validation";
import { runtimeGeneratedIdInput } from "./generated-id-input";
@@ -1860,22 +1861,90 @@ export const validateResourceBodyExpression = (
return typeof value === "string" ? "" : "Expected string in body";
};
+type ResourceExpressionFields = Partial<
+ Pick<Resource, "url" | "body" | "headers" | "searchParams">
+>;
+
+const listResourceExpressions = (
+ fields: ResourceExpressionFields,
+ pathPrefix: string[] = []
+) => [
+ ...(fields.url === undefined
+ ? []
+ : [{ path: [...pathPrefix, "url"], expression: fields.url }]),
+ ...(fields.body === undefined
+ ? []
+ : [{ path: [...pathPrefix, "body"], expression: fields.body }]),
+ ...(fields.headers ?? []).map((header, index) => ({
+ path: [...pathPrefix, "headers", String(index), "value"],
+ expression: header.value,
+ })),
+ ...(fields.searchParams ?? []).map((param, index) => ({
+ path: [...pathPrefix, "searchParams", String(index), "value"],
+ expression: param.value,
+ })),
+];
+
const getResourceExpressionValidationIssues = (
- fields: Partial<Pick<Resource, "url" | "body" | "headers" | "searchParams">>
-) => {
- const issues: SemanticValidationIssue[] = [];
- const validate = (name: string, expression: string | undefined) => {
- issues.push(...getNamedExpressionValidationIssues(name, expression));
- };
- validate("url", fields.url);
- validate("body", fields.body);
- for (const [index, header] of (fields.headers ?? []).entries()) {
- validate(`headers.${index}.value`, header.value);
- }
- for (const [index, searchParam] of (fields.searchParams ?? []).entries()) {
- validate(`searchParams.${index}.value`, searchParam.value);
+ fields: ResourceExpressionFields
+): SemanticValidationIssue[] =>
+ listResourceExpressions(fields).flatMap(({ path, expression }) =>
+ getNamedExpressionValidationIssues(path.join("."), expression)
+ );
+
+const getResourceWarnings = ({
+ fields,
+ state,
+ scopeInstanceId,
+ resourceId,
+ exposeAsDataSource = false,
+ fieldPath = ["resource"],
+ methodPath = ["resource", "method"],
+}: {
+ fields: Pick<
+ Resource,
+ "method" | "url" | "body" | "headers" | "searchParams"
+ >;
+ state: Pick<BuilderState, "instances" | "dataSources">;
+ scopeInstanceId?: string;
+ resourceId: string;
+ exposeAsDataSource?: boolean;
+ fieldPath?: string[];
+ methodPath?: string[];
+}) => {
+ const availableVariables = new Set(
+ scopeInstanceId === undefined ||
+ state.instances === undefined ||
+ state.dataSources === undefined
+ ? ["system"]
+ : findAvailableVariables({
+ startingInstanceId: scopeInstanceId,
+ instances: state.instances,
+ dataSources: state.dataSources,
+ }).map(({ name }) => name)
+ );
+ const warnings = listResourceExpressions(fields, fieldPath).flatMap(
+ ({ path, expression }) =>
+ getExpressionWarnings({
+ expression,
+ availableVariables,
+ path,
+ resourceId,
+ })
+ );
+ if (exposeAsDataSource && fields.method !== "get") {
+ warnings.push({
+ severity: "warning",
+ code: "render_time_mutation_resource",
+ path: methodPath,
+ message: `The ${fields.method.toUpperCase()} resource is explicitly exposed as render-time data and may execute while rendering the page.`,
+ range: { from: 0, to: 0 },
+ remediation:
+ "Expose GET resources for render-time data, or trigger mutating resources from an explicit action.",
+ resourceId,
+ });
}
- return issues;
+ return warnings;
};
export const getResourceExpressionErrors = (
@@ -2450,6 +2519,14 @@ export const createResource = (
headers: resourceInput.headers,
body: resourceInput.body,
});
+ const warnings = getResourceWarnings({
+ fields: resource,
+ state,
+ scopeInstanceId: input.scopeInstanceId,
+ resourceId,
+ exposeAsDataSource,
+ methodPath: ["resource", "method"],
+ });
return createRuntimeMutation({
payload: createResourceUpsertPatchPayload({
build,
@@ -2462,12 +2539,7 @@ export const createResource = (
result: {
resourceId,
dataSourceId,
- warnings:
- exposeAsDataSource && resourceInput.method !== "get"
- ? [
- `The ${resourceInput.method.toUpperCase()} resource is explicitly exposed as render-time data and may execute while rendering the page.`,
- ]
- : [],
+ warnings,
},
invalidatesNamespaces: [
"pages",
@@ -2549,6 +2621,15 @@ export const updateResource = (
const dataSourceId = exposeAsDataSource
? (dataSource?.id ?? context.createId())
: dataSource?.id;
+ const warnings = getResourceWarnings({
+ fields: nextResource,
+ state,
+ scopeInstanceId,
+ resourceId: resource.id,
+ exposeAsDataSource,
+ fieldPath: ["values"],
+ methodPath: ["values", "method"],
+ });
return createRuntimeMutation({
payload: createResourceUpsertPatchPayload({
build,
@@ -2561,12 +2642,7 @@ export const updateResource = (
result: {
resourceId: resource.id,
dataSourceId: exposeAsDataSource ? dataSourceId : undefined,
- warnings:
- input.exposeAsDataSource === true && nextResource.method !== "get"
- ? [
- `The ${nextResource.method.toUpperCase()} resource is explicitly exposed as render-time data and may execute while rendering the page.`,
- ]
- : [],
+ warnings,
},
invalidatesNamespaces: [
"pages",
diff --git a/packages/project-build/src/runtime/expression-validation.ts b/packages/project-build/src/runtime/expression-validation.ts
index 5d3e2d9239..a2f75b2084 100644
--- a/packages/project-build/src/runtime/expression-validation.ts
+++ b/packages/project-build/src/runtime/expression-validation.ts
@@ -1,11 +1,7 @@
import { lintExpression } from "@webstudio-is/sdk";
+import { z } from "zod";
import type { SemanticValidationIssue } from "./errors";
-export const getExpressionErrors = (expression: string) =>
- lintExpression({ expression })
- .filter((diagnostic) => diagnostic.severity === "error")
- .map((diagnostic) => diagnostic.message);
-
export const getExpressionErrorMessages = (
options: Parameters<typeof lintExpression>[0]
) =>
@@ -13,10 +9,53 @@ export const getExpressionErrorMessages = (
.filter((diagnostic) => diagnostic.severity === "error")
.map((diagnostic) => diagnostic.message);
+export const getExpressionErrors = (expression: string) =>
+ getExpressionErrorMessages({ expression });
+
export const hasExpressionDiagnostics = (
options: Parameters<typeof lintExpression>[0]
) => lintExpression(options).length > 0;
+export const expressionWarningSchema = z.object({
+ severity: z.literal("warning"),
+ code: z.string(),
+ path: z.array(z.string()),
+ message: z.string(),
+ range: z.object({
+ from: z.number().int().nonnegative(),
+ to: z.number().int().nonnegative(),
+ }),
+ remediation: z.string(),
+ instanceId: z.string().optional(),
+ resourceId: z.string().optional(),
+});
+
+export type ExpressionWarning = z.infer<typeof expressionWarningSchema>;
+
+export const getExpressionWarnings = ({
+ path,
+ instanceId,
+ resourceId,
+ ...options
+}: Parameters<typeof lintExpression>[0] & {
+ path: string[];
+ instanceId?: string;
+ resourceId?: string;
+}): ExpressionWarning[] =>
+ lintExpression(options)
+ .filter(({ severity }) => severity !== "error")
+ .map(({ from, to, message }) => ({
+ severity: "warning",
+ code: "expression_lint_warning",
+ path,
+ message,
+ range: { from, to },
+ remediation:
+ "Use a variable available at this element or resource scope, then verify the rendered dynamic value.",
+ ...(instanceId === undefined ? {} : { instanceId }),
+ ...(resourceId === undefined ? {} : { resourceId }),
+ }));
+
export const getNamedExpressionValidationIssues = (
name: string,
expression: string | undefined,
diff --git a/packages/project-build/src/runtime/fragment.ts b/packages/project-build/src/runtime/fragment.ts
index b47ec43902..a6d7503aeb 100644
--- a/packages/project-build/src/runtime/fragment.ts
+++ b/packages/project-build/src/runtime/fragment.ts
@@ -29,7 +29,7 @@ import {
unsetExpressionVariables,
} from "./data";
import { cloneInstanceWithNewIds } from "./instances";
-import { clonePropForInstance } from "./props";
+import { clonePropForInstance, listPropExpressions } from "./props";
import { buildMergedBreakpointIds, maxBreakpoints } from "./breakpoints";
import {
collectStyleSourcesFromInstances,
@@ -58,6 +58,35 @@ export type FragmentInsertTarget = {
position: number | "end" | "after";
};
+export const listFragmentExpressions = (fragment: WebstudioFragment) => [
+ ...fragment.instances.flatMap((instance, instanceIndex) =>
+ instance.children.flatMap((child, childIndex) =>
+ child.type === "expression"
+ ? [
+ {
+ expression: child.value,
+ allowAssignment: false,
+ variables: [] as string[],
+ path: [
+ "instances",
+ String(instanceIndex),
+ "children",
+ String(childIndex),
+ "value",
+ ],
+ },
+ ]
+ : []
+ )
+ ),
+ ...fragment.props.flatMap((prop, propIndex) =>
+ listPropExpressions(prop).map((entry) => ({
+ ...entry,
+ path: ["props", String(propIndex), "value", ...entry.path],
+ }))
+ ),
+];
+
const mergeById = <Item extends { id: string }>(items: Item[]) =>
Array.from(new Map(items.map((item) => [item.id, item])).values());
@@ -492,7 +521,7 @@ const insertFragmentBreakpointsMutable = ({
return { mergedBreakpointIds, didMergeBreakpointsDueToLimit };
};
-export const __testing__ = {
+export const fragmentTesting = {
getFragmentInstancesData,
insertFragmentAssetsMutable,
insertFragmentBreakpointsMutable,
diff --git a/packages/project-build/src/runtime/instance-path.ts b/packages/project-build/src/runtime/instance-path.ts
new file mode 100644
index 0000000000..1f24c3012e
--- /dev/null
+++ b/packages/project-build/src/runtime/instance-path.ts
@@ -0,0 +1,10 @@
+import type { Instance } from "@webstudio-is/sdk";
+
+export type InstanceSelector = Instance["id"][];
+
+export type InstancePathItem = {
+ instance: Instance;
+ instanceSelector: InstanceSelector;
+};
+
+export type InstancePath = InstancePathItem[];
diff --git a/packages/project-build/src/runtime/instances.ts b/packages/project-build/src/runtime/instances.ts
index d75f0dd845..fa2e671eb3 100644
--- a/packages/project-build/src/runtime/instances.ts
+++ b/packages/project-build/src/runtime/instances.ts
@@ -20,6 +20,11 @@ import {
compactBuilderPatchPayload,
type BuilderPatchChange,
} from "../contracts/patch";
+import {
+ paginateOutput,
+ projectOutput,
+ type PaginatedOutputInput,
+} from "./output";
import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
import {
@@ -3466,7 +3471,7 @@ const getPageFilteredRootInstanceIds = (
export const listInstances = (
state: Pick<BuilderState, "pages" | "instances">,
- input: {
+ input: PaginatedOutputInput & {
pageId?: string;
pagePath?: string;
rootInstanceId?: string;
@@ -3511,11 +3516,36 @@ export const listInstances = (
) {
continue;
}
+ const compact = serializeInstanceSummary(
+ instance,
+ depth,
+ parents.get(instance.id)
+ );
results.push(
- serializeInstanceSummary(instance, depth, parents.get(instance.id))
+ projectOutput({
+ input,
+ compact,
+ expanded: () => ({ record: instance }),
+ })
);
}
- return { instances: results };
+ const { items, ...pagination } = paginateOutput({
+ items: results,
+ cursor: input.cursor,
+ limit: input.limit,
+ filters: {
+ pageId: input.pageId,
+ pagePath: input.pagePath,
+ rootInstanceId: input.rootInstanceId,
+ maxDepth: input.maxDepth,
+ topLevelOnly: input.topLevelOnly,
+ component: input.component,
+ tag: input.tag,
+ labelContains: input.labelContains,
+ },
+ verbose: input.verbose,
+ });
+ return { instances: items, ...pagination };
};
export const listTextInstances = (
diff --git a/packages/project-build/src/runtime/lookup.ts b/packages/project-build/src/runtime/lookup.ts
index fb773a2cc6..56ebbbd54c 100644
--- a/packages/project-build/src/runtime/lookup.ts
+++ b/packages/project-build/src/runtime/lookup.ts
@@ -7,12 +7,9 @@ import type {
} from "@webstudio-is/sdk";
import { getAllPages } from "@webstudio-is/sdk";
import { isRichTextTree } from "./content-model";
-import type { InstanceSelector } from "./tree";
+import type { InstancePath, InstanceSelector } from "./instance-path";
-export type InstancePath = Array<{
- instance: Instance;
- instanceSelector: InstanceSelector;
-}>;
+export type { InstancePath } from "./instance-path";
export const getInstancePath = (
instanceSelector: InstanceSelector,
diff --git a/packages/project-build/src/runtime/output-schemas.ts b/packages/project-build/src/runtime/output-schemas.ts
index 9d8fba5d95..5bc85ba69e 100644
--- a/packages/project-build/src/runtime/output-schemas.ts
+++ b/packages/project-build/src/runtime/output-schemas.ts
@@ -2,25 +2,32 @@ import { z } from "zod";
import {
assetType,
compilerSettings,
+ dataSourceVariableValue,
documentTypes,
pageAuth,
pageRedirect,
pageTemplate as sdkPageTemplate,
projectMeta,
prop,
+ instance,
} from "@webstudio-is/sdk";
+import { paginatedOutputMetadataSchema } from "./output";
import { builderNamespaces } from "../contracts/namespaces";
import { builderPatchSchema } from "../contracts/patch";
import { marketplaceProduct } from "../shared/marketplace";
import { auditResult } from "./audit";
import { insertCollectionResult } from "./collection";
import { componentInsertResult } from "./component-insert-contract";
+import { expressionWarningSchema } from "./expression-validation";
const looseObject = <Shape extends z.ZodRawShape>(shape: Shape) =>
z.looseObject(shape);
const id = z.string();
const stringArray = z.array(z.string());
-const unknownRecord = z.record(z.string(), z.unknown());
+const styleValue = looseObject({
+ type: z.string().describe("CSS value kind"),
+ hidden: z.boolean().optional(),
+});
const patchChange = z.object({
namespace: z.enum(builderNamespaces),
@@ -104,6 +111,7 @@ const instanceSummary = looseObject({
parentId: id.optional(),
indexWithinParent: z.number().int().optional(),
});
+const outputPage = paginatedOutputMetadataSchema.shape;
const breakpoint = looseObject({
id,
label: z.string(),
@@ -129,16 +137,20 @@ const declaration = looseObject({
instanceId: id,
styleSourceId: id,
property: z.string(),
- value: z.unknown(),
+ value: styleValue,
breakpoint: id,
state: z.string().optional(),
source: z.enum(["local", "token"]),
});
+const declarationSummary = declaration.omit({ value: true }).extend({
+ valueType: z.string(),
+ value: styleValue.optional(),
+});
const token = looseObject({
id,
name: z.string(),
declarationCount: z.number().int(),
- styles: unknownRecord.optional(),
+ styles: z.record(z.string(), styleValue).optional(),
usageCount: z.number().int().optional(),
});
const cssVariable = looseObject({
@@ -151,7 +163,7 @@ const variable = looseObject({
id,
name: z.string(),
scopeInstanceId: id.optional(),
- value: z.unknown(),
+ value: dataSourceVariableValue,
});
const resource = looseObject({
id,
@@ -166,13 +178,24 @@ const asset = looseObject({
id,
name: z.string(),
filename: z.string().optional(),
- description: z.string().nullable().optional(),
type: assetType,
size: z.number(),
contentType: z.string(),
- createdAt: z.string(),
usageCount: z.number().int().optional(),
});
+const assetRecord = looseObject({
+ id,
+ projectId: id,
+ name: z.string(),
+ filename: z.string().optional(),
+ description: z.string().nullable().optional(),
+ type: assetType,
+ size: z.number(),
+ format: z.string(),
+ createdAt: z.string(),
+ meta: looseObject({}),
+});
+const assetListItem = asset.extend({ record: assetRecord.optional() });
const assetUsage = looseObject({
namespace: z.enum([
"props",
@@ -235,10 +258,11 @@ const resourceReplacementMatch = looseObject({
before: z.string(),
after: z.string(),
});
+const expressionWarnings = z.array(expressionWarningSchema);
const resourceMutationResult = looseObject({
resourceId: id,
dataSourceId: id.optional(),
- warnings: stringArray,
+ warnings: expressionWarnings,
});
export const runtimeOutputSchemas = {
@@ -314,7 +338,10 @@ export const runtimeOutputSchemas = {
}),
"pageTree.move": looseObject({ childId: id }),
"pageTree.reparentOrphans": looseObject({}),
- "instances.list": looseObject({ instances: z.array(instanceSummary) }),
+ "instances.list": looseObject({
+ instances: z.array(instanceSummary.extend({ record: instance.optional() })),
+ ...outputPage,
+ }),
"instances.inspect": instanceSummary.extend({
ancestors: z.array(instanceSummary).optional(),
props: z.array(prop).optional(),
@@ -332,7 +359,9 @@ export const runtimeOutputSchemas = {
}),
"project.audit": auditResult,
"instances.insertComponent": componentInsertResult,
- "instances.insertCollection": insertCollectionResult,
+ "instances.insertCollection": insertCollectionResult.extend({
+ warnings: expressionWarnings.optional(),
+ }),
"instances.insertFragment": fragmentInsertResult,
"instances.move": instanceIdsResult,
"instances.reparent": looseObject({
@@ -355,7 +384,10 @@ export const runtimeOutputSchemas = {
instanceIds: stringArray,
instanceSelector: stringArray.optional(),
}),
- "instances.updateProps": looseObject({ propIds: stringArray }),
+ "instances.updateProps": looseObject({
+ propIds: stringArray,
+ warnings: expressionWarnings.optional(),
+ }),
"instances.replacePropText": looseObject({
changedCount: z.number().int(),
matchingPropCount: z.number().int(),
@@ -363,12 +395,16 @@ export const runtimeOutputSchemas = {
matches: z.array(propReplacementMatch),
}),
"instances.deleteProps": looseObject({ propIds: stringArray }),
- "instances.bindProps": looseObject({ propIds: stringArray }),
+ "instances.bindProps": looseObject({
+ propIds: stringArray,
+ warnings: expressionWarnings.optional(),
+ }),
"instances.listTexts": looseObject({ texts: z.array(textMatch) }),
"instances.updateText": looseObject({
instanceId: id,
childIndex: z.number().int(),
mode: z.enum(["text", "expression"]),
+ warnings: expressionWarnings.optional(),
}),
"instances.replaceText": looseObject({
changedCount: z.number().int(),
@@ -380,6 +416,7 @@ export const runtimeOutputSchemas = {
instanceId: id,
operation: z.enum(["set", "reset"]),
mode: z.enum(["text", "expression"]).optional(),
+ warnings: expressionWarnings.optional(),
}),
"instances.updateTextTree": looseObject({
rootInstanceId: id,
@@ -392,14 +429,15 @@ export const runtimeOutputSchemas = {
label: z.string(),
}),
"styles.getDeclarations": looseObject({
- declarations: z.array(declaration),
+ declarations: z.array(declarationSummary),
+ ...outputPage,
}),
"styles.updateDeclarations": styleKeysResult,
"styles.deleteDeclarations": styleKeysResult,
"styles.updateSelectedDeclarations": styleKeysResult,
"styles.deleteSelectedDeclarations": styleKeysResult,
"styles.replaceValues": styleKeysResult,
- "designTokens.list": looseObject({ tokens: z.array(token) }),
+ "designTokens.list": looseObject({ tokens: z.array(token), ...outputPage }),
"designTokens.create": looseObject({ tokenIds: stringArray }),
"designTokens.createAttached": looseObject({ tokenIds: stringArray }),
"designTokens.updateStyles": looseObject({
@@ -477,8 +515,8 @@ export const runtimeOutputSchemas = {
propIds: stringArray,
}),
"assets.list": looseObject({
- items: z.array(asset),
- nextCursor: z.string().nullable(),
+ items: z.array(assetListItem),
+ ...outputPage,
}),
"fonts.list": looseObject({
uploaded: z.array(uploadedFont),
diff --git a/packages/project-build/src/runtime/output.test.ts b/packages/project-build/src/runtime/output.test.ts
new file mode 100644
index 0000000000..11c27c6bd9
--- /dev/null
+++ b/packages/project-build/src/runtime/output.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { paginateOutput, projectOutput } from "./output";
+
+describe("output detail", () => {
+ test("keeps compact fields unchanged and only expands on request", () => {
+ const compact = { id: "item-1", count: 2 };
+ expect(
+ projectOutput({ input: {}, compact, expanded: () => ({ value: "full" }) })
+ ).toEqual(compact);
+ expect(
+ projectOutput({
+ input: { verbose: true },
+ compact,
+ expanded: () => ({ value: "full" }),
+ })
+ ).toEqual({ ...compact, value: "full" });
+ });
+
+ test("returns stable pagination metadata and active filters", () => {
+ expect(
+ paginateOutput({
+ items: ["a", "b", "c"],
+ cursor: "1",
+ limit: 1,
+ filters: { type: "image" },
+ })
+ ).toEqual({
+ detail: "compact",
+ items: ["b"],
+ total: 3,
+ returnedCount: 1,
+ nextCursor: "2",
+ filters: { type: "image" },
+ });
+ });
+
+ test("rejects invalid cursors", () => {
+ expect(() =>
+ paginateOutput({ items: [], cursor: "nope", filters: {} })
+ ).toThrow("Invalid pagination cursor");
+ });
+
+ test.each([0, 201, 1.5])("rejects invalid limits: %s", (limit) => {
+ expect(() => paginateOutput({ items: [], limit, filters: {} })).toThrow();
+ });
+});
diff --git a/packages/project-build/src/runtime/output.ts b/packages/project-build/src/runtime/output.ts
new file mode 100644
index 0000000000..ebffd20289
--- /dev/null
+++ b/packages/project-build/src/runtime/output.ts
@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+export const outputDetailInputSchema = z.object({
+ verbose: z
+ .boolean()
+ .optional()
+ .describe(
+ "Expand the same result with complete records and diagnostics. Omit for compact output."
+ ),
+});
+const outputLimitSchema = z.number().int().min(1).max(200);
+export const paginatedOutputInputSchema = z.object({
+ cursor: z.string().optional(),
+ limit: outputLimitSchema.optional(),
+ ...outputDetailInputSchema.shape,
+});
+
+export const paginatedOutputMetadataSchema = z.object({
+ detail: z.enum(["compact", "verbose"]),
+ total: z.number().int().nonnegative(),
+ returnedCount: z.number().int().nonnegative(),
+ nextCursor: z.string().nullable(),
+ filters: z.looseObject({}),
+});
+
+export type OutputDetailInput = z.input<typeof outputDetailInputSchema>;
+export type PaginatedOutputInput = z.input<typeof paginatedOutputInputSchema>;
+
+export const projectOutput = <Compact extends object, Expanded extends object>({
+ input,
+ compact,
+ expanded,
+}: {
+ input: OutputDetailInput;
+ compact: Compact;
+ expanded: () => Expanded;
+}): Compact | (Compact & Expanded) =>
+ input.verbose === true ? { ...compact, ...expanded() } : compact;
+
+const parseCursor = (
+ cursor: string | undefined,
+ invalidCursorMessage: string
+) => {
+ if (cursor === undefined) {
+ return 0;
+ }
+ const offset = Number(cursor);
+ if (Number.isInteger(offset) === false || offset < 0) {
+ throw new Error(invalidCursorMessage);
+ }
+ return offset;
+};
+
+export const paginateOutput = <Item, Filters extends object>({
+ items,
+ cursor,
+ limit = 50,
+ filters,
+ verbose,
+ invalidCursorMessage = "Invalid pagination cursor",
+}: {
+ items: readonly Item[];
+ cursor?: string;
+ limit?: number;
+ filters: Filters;
+ verbose?: boolean;
+ invalidCursorMessage?: string;
+}) => {
+ const offset = parseCursor(cursor, invalidCursorMessage);
+ const parsedLimit = outputLimitSchema.parse(limit);
+ const page = items.slice(offset, offset + parsedLimit);
+ const nextOffset = offset + page.length;
+ const activeFilters = Object.fromEntries(
+ Object.entries(filters).filter(([, value]) => value !== undefined)
+ ) as Partial<Filters>;
+ return {
+ detail: verbose === true ? ("verbose" as const) : ("compact" as const),
+ items: page,
+ total: items.length,
+ returnedCount: page.length,
+ nextCursor: nextOffset < items.length ? String(nextOffset) : null,
+ filters: activeFilters,
+ };
+};
diff --git a/packages/project-build/src/runtime/page-copy.test.tsx b/packages/project-build/src/runtime/page-copy.test.tsx
index 18e50aa2a9..eb8c33cd96 100644
--- a/packages/project-build/src/runtime/page-copy.test.tsx
+++ b/packages/project-build/src/runtime/page-copy.test.tsx
@@ -17,7 +17,7 @@ import {
createRootFolder,
} from "@webstudio-is/project-build";
import {
- __testing__,
+ pageCopyTesting,
createPageTemplate,
createPageFromTemplate,
createPageDuplicatePayload,
@@ -43,7 +43,7 @@ import {
} from "@webstudio-is/template";
import { nanoid } from "nanoid";
-const { deduplicateName, deduplicatePath, joinPath } = __testing__;
+const { deduplicateName, deduplicatePath, joinPath } = pageCopyTesting;
const toMap = <T extends { id: string }>(list: T[]) =>
new Map(list.map((item) => [item.id, item]));
diff --git a/packages/project-build/src/runtime/page-copy.ts b/packages/project-build/src/runtime/page-copy.ts
index bfa953907f..c71e0b4b39 100644
--- a/packages/project-build/src/runtime/page-copy.ts
+++ b/packages/project-build/src/runtime/page-copy.ts
@@ -500,7 +500,7 @@ const copyAndTransformPageMeta = (
}
};
-export const __testing__ = {
+export const pageCopyTesting = {
deduplicateName,
deduplicatePath,
joinPath,
diff --git a/packages/project-build/src/runtime/project-settings.test.ts b/packages/project-build/src/runtime/project-settings.test.ts
index d3104e9caf..4e7512c7fc 100644
--- a/packages/project-build/src/runtime/project-settings.test.ts
+++ b/packages/project-build/src/runtime/project-settings.test.ts
@@ -1,6 +1,12 @@
import { describe, expect, test } from "vitest";
import { createBasicAuthRoute } from "@webstudio-is/wsauth";
import type { BuilderState } from "../state/builder-state";
+import {
+ parseProjectAuthRoutes,
+ validateContactEmail,
+ validateProjectAuth,
+ validateProjectAuthRoute,
+} from "../contracts/project-settings";
import {
breakpointFieldsInput,
breakpointUpdateFieldsInput,
@@ -13,7 +19,6 @@ import {
listBreakpoints,
listRedirects,
marketplaceProductUpdateInput,
- parseProjectAuthRoutes,
projectSettingsUpdateInput,
redirectFieldsInput,
redirectUpdateFieldsInput,
@@ -22,9 +27,6 @@ import {
updateMarketplaceProduct,
updateProjectSettings,
updateRedirect,
- validateContactEmail,
- validateProjectAuth,
- validateProjectAuthRoute,
} from "./project-settings";
const createState = (): BuilderState =>
diff --git a/packages/project-build/src/runtime/project-settings.ts b/packages/project-build/src/runtime/project-settings.ts
index 83f21becb7..11a1d7549b 100644
--- a/packages/project-build/src/runtime/project-settings.ts
+++ b/packages/project-build/src/runtime/project-settings.ts
@@ -8,11 +8,14 @@ import {
redirectSourcePath,
} from "@webstudio-is/sdk";
import { z } from "zod";
-import { parseWsAuth, type WsAuthRoute } from "@webstudio-is/wsauth";
import {
compactBuilderPatchPayload,
type BuilderPatchChange,
} from "../contracts/patch";
+import {
+ validateContactEmail,
+ validateProjectAuth,
+} from "../contracts/project-settings";
import type { BuilderState } from "../state/builder-state";
import { hasReachedBreakpointLimit, isBaseBreakpoint } from "./breakpoints";
import type { BuilderRuntimeContext } from "./context";
@@ -36,6 +39,14 @@ import {
stripRedirectSourceFragment,
} from "./redirect-source";
+export {
+ parseProjectAuthRoutes,
+ validateContactEmail,
+ validateProjectAuth,
+ validateProjectAuthRoute,
+ validateProjectAuthRouteSyntax,
+} from "../contracts/project-settings";
+
const getRequiredBreakpoints = (state: Pick<BuilderState, "breakpoints">) => {
if (state.breakpoints === undefined) {
return throwBuilderRuntimeError(
@@ -101,91 +112,6 @@ export const projectSettingsUpdateInput = z
export const marketplaceProductUpdateInput = marketplaceProduct;
-const emailAddress = z.string().email();
-
-const getContactEmails = (contactEmail: string) => {
- const trimmedContactEmail = contactEmail.trim();
- if (trimmedContactEmail.length === 0) {
- return [];
- }
- return trimmedContactEmail.split(/\s*,\s*/);
-};
-
-export const validateContactEmail = (
- contactEmail: string,
- maxContactEmailsPerProject?: number
-) => {
- const emails = getContactEmails(contactEmail);
- if (emails.length === 0) {
- return;
- }
- if (
- maxContactEmailsPerProject !== undefined &&
- emails.length > maxContactEmailsPerProject
- ) {
- if (maxContactEmailsPerProject === 0) {
- return `Upgrade to PRO to customize the contact email.`;
- }
- return `Only ${maxContactEmailsPerProject} emails are allowed.`;
- }
- if (
- emails.every((email) => emailAddress.safeParse(email).success) === false
- ) {
- return "Contact email is invalid.";
- }
-};
-
-export const validateProjectAuth = (auth: string) => {
- const result = parseWsAuth(auth);
- if (result.errors.length === 0) {
- return;
- }
- return result.errors
- .map((error) => `${error.path}: ${error.message}`)
- .join("\n");
-};
-
-export const parseProjectAuthRoutes = (auth: string | undefined) => {
- return parseWsAuth(auth ?? "");
-};
-
-export const validateProjectAuthRouteSyntax = (route: string) => {
- const result = parseWsAuth(
- JSON.stringify({
- version: 1,
- routes: {
- [route]: {
- method: "basic",
- login: "login",
- password: "password",
- },
- },
- })
- );
- return result.errors.find((error) =>
- error.path.startsWith(`routes.${JSON.stringify(route)}`)
- )?.message;
-};
-
-export const validateProjectAuthRoute = (
- route: string,
- authRoutes: readonly WsAuthRoute[]
-) => {
- const errors: string[] = [];
- if (route === "") {
- errors.push("Route is required");
- return errors;
- }
- const routeError = validateProjectAuthRouteSyntax(route);
- if (routeError !== undefined) {
- errors.push(routeError);
- }
- if (authRoutes.some((authRoute) => authRoute.route === route)) {
- errors.push("This route already requires authentication");
- }
- return errors;
-};
-
const validateProjectMetaUpdate = (
values: z.infer<typeof projectMetaUpdateInput>
) => {
diff --git a/packages/project-build/src/runtime/props.ts b/packages/project-build/src/runtime/props.ts
index af35052563..61eae173ec 100644
--- a/packages/project-build/src/runtime/props.ts
+++ b/packages/project-build/src/runtime/props.ts
@@ -9,7 +9,10 @@ import { validateJsonLd } from "@webstudio-is/sdk/runtime";
import type { BuilderState } from "../state/builder-state";
import { addZodValidationIssue, throwBuilderRuntimeError } from "./errors";
import { replaceTextValue } from "./text-replacement";
-import { getExpressionErrors } from "./expression-validation";
+import {
+ getExpressionErrorMessages,
+ getExpressionErrors,
+} from "./expression-validation";
import { runtimeGeneratedIdInput } from "./generated-id-input";
import { validateHtmlEmbedCode } from "./html";
import { createRuntimeMutation } from "./mutation";
@@ -80,6 +83,35 @@ export const createPropBindingFromInput = ({
value: binding.value,
});
+export const listPropExpressions = ({
+ type,
+ value,
+}: {
+ type: Prop["type"];
+ value: unknown;
+}) => {
+ if (type === "expression" && typeof value === "string") {
+ return [
+ {
+ expression: value,
+ allowAssignment: false,
+ variables: [] as string[],
+ path: [] as string[],
+ },
+ ];
+ }
+ if (type !== "action" || Array.isArray(value) === false) {
+ return [];
+ }
+ const actions = value as Extract<Prop, { type: "action" }>["value"];
+ return actions.map((action, index) => ({
+ expression: action.code,
+ allowAssignment: true,
+ variables: action.args,
+ path: [String(index), "code"],
+ }));
+};
+
export const getPropValueErrors = ({
type,
value,
@@ -88,7 +120,14 @@ export const getPropValueErrors = ({
value?: unknown;
}) => {
if (type !== "expression") {
- return [];
+ return listPropExpressions({ type, value }).flatMap(
+ ({ expression, allowAssignment, variables }) =>
+ getExpressionErrorMessages({
+ expression,
+ allowAssignment,
+ availableVariables: new Set(variables),
+ })
+ );
}
return getExpressionErrors(String(value));
};
diff --git a/packages/project-build/src/runtime/registry.test.ts b/packages/project-build/src/runtime/registry.test.ts
index 7a23adfec3..25d8e6bc4f 100644
--- a/packages/project-build/src/runtime/registry.test.ts
+++ b/packages/project-build/src/runtime/registry.test.ts
@@ -23,6 +23,7 @@ import {
} from "./styles";
import {
inspectInstance,
+ listInstances,
listTextInstances,
updateTextInstance,
} from "./instances";
@@ -66,6 +67,11 @@ const mutationOperationIds = runtimeOperationContracts
.filter((contract) => contract.kind === "mutation")
.map((contract) => contract.id);
+const getMutationResult = (operation: unknown): unknown => {
+ expect(operation).toHaveProperty("result");
+ return (operation as { result: unknown }).result;
+};
+
test.each([
{
family: "page",
@@ -198,9 +204,21 @@ test("validates structured runtime operation results", () => {
getRuntimeOutputSchema("resources.update").parse({
resourceId: "resource",
dataSourceId: "data-source",
- warnings: ["warning"],
+ warnings: [
+ {
+ severity: "warning",
+ code: "expression_lint_warning",
+ path: ["resource", "url"],
+ message: '"missing" is not defined in the scope',
+ range: { from: 0, to: 7 },
+ remediation: "Use an in-scope variable.",
+ },
+ ],
})
- ).toMatchObject({ dataSourceId: "data-source", warnings: ["warning"] });
+ ).toMatchObject({
+ dataSourceId: "data-source",
+ warnings: [{ code: "expression_lint_warning" }],
+ });
expect(
getRuntimeOutputSchema("instances.deleteBySelector").safeParse({
@@ -320,6 +338,50 @@ describe("builder runtime pages", () => {
});
describe("builder runtime read families", () => {
+ test("keeps instance lists compact and paginates verbose expansion", () => {
+ const instances: BuilderState["instances"] = new Map(state.instances);
+ const largeState: BuilderState = {
+ ...state,
+ instances,
+ };
+ instances.set("body", {
+ ...state.instances.get("body")!,
+ children: [
+ ...Array.from({ length: 100 }, (_, index) => ({
+ type: "id" as const,
+ value: `repeated-child-${index}-${"detail-".repeat(10)}`,
+ })),
+ { type: "id" as const, value: "heading" },
+ ],
+ });
+ const compact = listInstances(largeState, { limit: 1 });
+ const verbose = listInstances(largeState, { limit: 1, verbose: true });
+
+ expect(compact).toMatchObject({
+ detail: "compact",
+ total: 2,
+ returnedCount: 1,
+ nextCursor: "1",
+ instances: [{ id: "body" }],
+ });
+ expect(compact.instances[0]).not.toHaveProperty("record");
+ expect(verbose).toMatchObject({
+ detail: "verbose",
+ total: compact.total,
+ returnedCount: compact.returnedCount,
+ nextCursor: compact.nextCursor,
+ instances: [
+ expect.objectContaining({
+ ...compact.instances[0],
+ record: expect.objectContaining({ id: "body" }),
+ }),
+ ],
+ });
+ expect(JSON.stringify(compact).length).toBeLessThan(
+ JSON.stringify(verbose).length * 0.5
+ );
+ });
+
test("reads instances and text nodes", () => {
expect(
executeBuilderRuntimeOperation({
@@ -597,6 +659,183 @@ describe("builder runtime read families", () => {
).toThrow(/data source "stale".*not available/);
});
+ test("returns non-blocking expression warnings with actionable locations", () => {
+ const text = executeBuilderRuntimeOperation({
+ id: "instances.updateText",
+ state,
+ input: {
+ instanceId: "heading",
+ childIndex: 0,
+ text: "missingTitle",
+ mode: "expression",
+ },
+ context,
+ });
+ expect(getMutationResult(text)).toMatchObject({
+ warnings: [
+ {
+ code: "expression_lint_warning",
+ path: ["text"],
+ instanceId: "heading",
+ range: { from: 0, to: 12 },
+ remediation: expect.stringContaining("available"),
+ },
+ ],
+ });
+
+ const prop = executeBuilderRuntimeOperation({
+ id: "instances.bindProps",
+ state,
+ input: {
+ bindings: [
+ {
+ instanceId: "heading",
+ name: "title",
+ binding: { type: "expression", value: "missingTitle" },
+ },
+ {
+ instanceId: "heading",
+ name: "onClick",
+ binding: {
+ type: "action",
+ value: [
+ {
+ type: "execute",
+ args: ["event"],
+ code: "missingValue = event",
+ },
+ ],
+ },
+ },
+ ],
+ },
+ context,
+ });
+ expect(getMutationResult(prop)).toMatchObject({
+ warnings: [
+ expect.objectContaining({
+ path: ["bindings", "0", "binding", "value"],
+ instanceId: "heading",
+ }),
+ expect.objectContaining({
+ path: ["bindings", "1", "binding", "value", "0", "code"],
+ instanceId: "heading",
+ }),
+ ],
+ });
+
+ const resource = executeBuilderRuntimeOperation({
+ id: "resources.create",
+ state,
+ input: {
+ resource: {
+ name: "Create post",
+ method: "post",
+ url: "https://api.example.com/posts",
+ headers: [],
+ body: "missingPayload",
+ },
+ },
+ context: {
+ ...context,
+ createId: (() => {
+ const ids = ["warning-resource", "warning-data-source"];
+ return () => ids.shift() ?? "id";
+ })(),
+ },
+ });
+ expect(getMutationResult(resource)).toMatchObject({
+ warnings: [
+ expect.objectContaining({
+ path: ["resource", "body"],
+ resourceId: "warning-resource",
+ }),
+ ],
+ });
+
+ const collection = executeBuilderRuntimeOperation({
+ id: "instances.insertCollection",
+ state,
+ input: {
+ parentInstanceId: "body",
+ data: { type: "json", value: [{ name: "Starter" }] },
+ itemFragment: {
+ children: [{ type: "id", value: "item" }],
+ instances: [
+ {
+ type: "instance",
+ id: "item",
+ component: "Text",
+ children: [
+ { type: "expression", value: "collectionItem.name" },
+ { type: "expression", value: "missingCollectionItem.name" },
+ ],
+ },
+ ],
+ props: [],
+ dataSources: [],
+ resources: [],
+ styleSources: [],
+ styleSourceSelections: [],
+ styles: [],
+ breakpoints: [],
+ assets: [],
+ },
+ },
+ context: {
+ ...context,
+ createId: (() => {
+ const ids = [
+ "collection",
+ "collection-data-prop",
+ "collection-item",
+ "collection-item-key",
+ ];
+ return () => ids.shift() ?? "generated-id";
+ })(),
+ },
+ });
+ expect(getMutationResult(collection)).toMatchObject({
+ warnings: [
+ expect.objectContaining({
+ path: ["itemFragment", "instances", "0", "children", "1", "value"],
+ message: expect.stringContaining("missingCollectionItem"),
+ }),
+ ],
+ });
+
+ try {
+ executeBuilderRuntimeOperation({
+ id: "instances.bindProps",
+ state,
+ input: {
+ bindings: [
+ {
+ instanceId: "heading",
+ name: "onClick",
+ binding: {
+ type: "action",
+ value: [{ type: "execute", args: ["event"], code: "event +" }],
+ },
+ },
+ ],
+ },
+ context,
+ });
+ expect.unreachable("Expected invalid action syntax to be rejected");
+ } catch (error) {
+ expect(error).toMatchObject({
+ code: "INVALID_INPUT",
+ issues: [
+ expect.objectContaining({
+ path: ["bindings", "0", "binding", "value"],
+ detail: expect.stringMatching(/Unexpected token/),
+ }),
+ ],
+ });
+ }
+ });
+
test("binds Collection data and item names in their respective scopes", () => {
const collectionState = {
...state,
@@ -669,6 +908,7 @@ describe("builder runtime read families", () => {
context,
})
).toMatchObject({
+ result: { propIds: ["id"] },
payload: [
{
namespace: "props",
@@ -683,19 +923,18 @@ describe("builder runtime read families", () => {
],
});
- expect(
- executeBuilderRuntimeOperation({
- id: "instances.updateText",
- state: collectionState,
- input: {
- instanceId: "item",
- childIndex: 0,
- text: "collectionItem.name",
- mode: "expression",
- },
- context,
- })
- ).toMatchObject({
+ const validItemBinding = executeBuilderRuntimeOperation({
+ id: "instances.updateText",
+ state: collectionState,
+ input: {
+ instanceId: "item",
+ childIndex: 0,
+ text: "collectionItem.name",
+ mode: "expression",
+ },
+ context,
+ });
+ expect(validItemBinding).toMatchObject({
payload: [
{
namespace: "instances",
@@ -709,6 +948,27 @@ describe("builder runtime read families", () => {
},
],
});
+
+ const invalidItemBinding = executeBuilderRuntimeOperation({
+ id: "instances.updateText",
+ state: collectionState,
+ input: {
+ instanceId: "item",
+ childIndex: 0,
+ text: "missingCollectionItem.name",
+ mode: "expression",
+ },
+ context,
+ });
+ expect(getMutationResult(invalidItemBinding)).toMatchObject({
+ warnings: [
+ expect.objectContaining({
+ path: ["text"],
+ instanceId: "item",
+ message: expect.stringContaining("missingCollectionItem"),
+ }),
+ ],
+ });
});
test("replaces bounded static prop text without changing dynamic bindings", () => {
@@ -818,7 +1078,7 @@ describe("builder runtime read families", () => {
tokens: [{ id: "token", declarationCount: 1, usageCount: 1 }],
});
expect(
- listDesignTokens(state, { withUsage: true, includeStyles: true })
+ listDesignTokens(state, { withUsage: true, verbose: true })
).toMatchObject({
tokens: [{ id: "token", styles: { color: expect.any(Object) } }],
});
diff --git a/packages/project-build/src/runtime/registry.ts b/packages/project-build/src/runtime/registry.ts
index c7febb4203..b528776a9d 100644
--- a/packages/project-build/src/runtime/registry.ts
+++ b/packages/project-build/src/runtime/registry.ts
@@ -4,6 +4,8 @@ import {
type BuilderNamespace,
} from "../contracts/namespaces";
import type { BuilderApiCapability } from "../contracts/permissions";
+import { paginatedOutputInputSchema } from "./output";
+import { getExpressionWarnings } from "./expression-validation";
import {
getInputSchemaMetadata,
isHiddenPublicApiInputField,
@@ -34,6 +36,7 @@ import {
type RuntimeOutputSchemaId,
} from "./output-schemas";
import type { BuilderRuntimeMutation } from "./mutation";
+import { listFragmentExpressions } from "./fragment";
export type BuilderRuntimeOperation<
Id extends string = string,
@@ -157,6 +160,77 @@ const bindExpressionInput = (
});
};
+const getScopedExpressionWarnings = (
+ state: BuilderState,
+ instanceId: string,
+ path: string[],
+ expression: string,
+ allowAssignment = false,
+ additionalVariables: readonly string[] = []
+) => {
+ if (state.instances === undefined || state.dataSources === undefined) {
+ return [];
+ }
+ const availableVariables = new Set(
+ data
+ .findAvailableVariables({
+ startingInstanceId: instanceId,
+ instances: state.instances,
+ dataSources: state.dataSources,
+ })
+ .map(({ name }) => name)
+ );
+ for (const name of additionalVariables) {
+ availableVariables.add(name);
+ }
+ return getExpressionWarnings({
+ expression,
+ availableVariables,
+ allowAssignment,
+ path,
+ instanceId,
+ });
+};
+
+const getScopedPropWarnings = ({
+ state,
+ instanceId,
+ path,
+ prop,
+ variables = [],
+}: {
+ state: BuilderState;
+ instanceId: string;
+ path: string[];
+ prop: Parameters<typeof props.listPropExpressions>[0];
+ variables?: readonly string[];
+}) =>
+ props
+ .listPropExpressions(prop)
+ .flatMap((entry) =>
+ getScopedExpressionWarnings(
+ state,
+ instanceId,
+ [...path, ...entry.path],
+ entry.expression,
+ entry.allowAssignment,
+ [...variables, ...entry.variables]
+ )
+ );
+
+const withExpressionWarnings = <
+ Mutation extends { result: Record<string, unknown> },
+>(
+ mutation: Mutation,
+ warnings: ReturnType<typeof getExpressionWarnings>
+) =>
+ warnings.length === 0
+ ? mutation
+ : {
+ ...mutation,
+ result: { ...mutation.result, warnings },
+ };
+
const runtimeOperation = <
Id extends RuntimeOutputSchemaId,
Schema extends z.ZodTypeAny,
@@ -310,6 +384,7 @@ const instanceListInput = instanceFilterInput.extend({
maxDepth: z.number().int().nonnegative().optional(),
topLevelOnly: z.boolean().optional(),
labelContains: z.string().optional(),
+ ...paginatedOutputInputSchema.shape,
});
const instanceInspectInput = z.object({
instanceId: z.string(),
@@ -344,6 +419,7 @@ const styleDeclarationsListInput = z.object({
property: z.string().optional(),
propertyFilter: z.string().optional(),
includeTokens: z.boolean().optional(),
+ ...paginatedOutputInputSchema.shape,
});
const designTokenListInput = z.object({
filter: z.string().optional(),
@@ -351,11 +427,8 @@ const designTokenListInput = z.object({
.boolean()
.optional()
.describe("Include usage counts. Defaults to true."),
- includeStyles: z
- .boolean()
- .optional()
- .describe("Include full inline style declarations for each token."),
sort: z.enum(["name", "usage"]).optional(),
+ ...paginatedOutputInputSchema.shape,
});
const cssVariableListInput = z.object({
filter: z.string().optional(),
@@ -368,8 +441,7 @@ const assetListInput = z.object({
type: z.enum(["image", "font"]).optional(),
sort: z.enum(["name", "size", "createdAt", "usage"]).optional(),
withUsage: z.boolean().optional(),
- cursor: z.string().optional(),
- limit: z.number().int().min(1).optional(),
+ ...paginatedOutputInputSchema.shape,
});
const assetUsageInput = z.object({ assetId: z.string() });
@@ -849,8 +921,32 @@ export const builderRuntimeOperations = [
writeNamespaces: components.componentInsertNamespaces,
}),
collection.insertCollectionInput,
- ({ state, input, context }) =>
- components.insertCollection(state, input, context)
+ ({ state, input, context }) => {
+ const warnings = [
+ ...(input.data.type === "expression"
+ ? getScopedExpressionWarnings(
+ state,
+ input.parentInstanceId,
+ ["data", "value"],
+ input.data.value
+ )
+ : []),
+ ...listFragmentExpressions(input.itemFragment).flatMap((entry) =>
+ getScopedExpressionWarnings(
+ state,
+ input.parentInstanceId,
+ ["itemFragment", ...entry.path],
+ entry.expression,
+ entry.allowAssignment,
+ ["collectionItem", "collectionItemKey", ...entry.variables]
+ )
+ ),
+ ];
+ return withExpressionWarnings(
+ components.insertCollection(state, input, context),
+ warnings
+ );
+ }
),
runtimeOperation(
"instances.insertFragment",
@@ -1035,25 +1131,37 @@ export const builderRuntimeOperations = [
writeNamespaces: ["props"],
}),
props.propUpdatesInput,
- ({ state, input, context }) =>
- props.updateProps(
- state,
- {
- updates: input.updates.map((update) =>
- update.type === "expression"
- ? {
- ...update,
- value: bindExpressionInput(
- state,
- update.instanceId,
- update.value
- ),
- }
- : update
- ),
- },
- context
- )
+ ({ state, input, context }) => {
+ const warnings = input.updates.flatMap((update, index) =>
+ getScopedPropWarnings({
+ state,
+ instanceId: update.instanceId,
+ path: ["updates", String(index), "value"],
+ prop: update,
+ })
+ );
+ return withExpressionWarnings(
+ props.updateProps(
+ state,
+ {
+ updates: input.updates.map((update) =>
+ update.type === "expression"
+ ? {
+ ...update,
+ value: bindExpressionInput(
+ state,
+ update.instanceId,
+ update.value
+ ),
+ }
+ : update
+ ),
+ },
+ context
+ ),
+ warnings
+ );
+ }
),
runtimeOperation(
"instances.replacePropText",
@@ -1084,28 +1192,40 @@ export const builderRuntimeOperations = [
writeNamespaces: ["props"],
}),
props.propBindingsInput,
- ({ state, input, context }) =>
- props.bindProps(
- state,
- {
- bindings: input.bindings.map((binding) =>
- binding.binding.type === "expression"
- ? {
- ...binding,
- binding: {
- ...binding.binding,
- value: bindExpressionInput(
- state,
- binding.instanceId,
- binding.binding.value
- ),
- },
- }
- : binding
- ),
- },
- context
- )
+ ({ state, input, context }) => {
+ const warnings = input.bindings.flatMap((binding, index) =>
+ getScopedPropWarnings({
+ state,
+ instanceId: binding.instanceId,
+ path: ["bindings", String(index), "binding", "value"],
+ prop: binding.binding,
+ })
+ );
+ return withExpressionWarnings(
+ props.bindProps(
+ state,
+ {
+ bindings: input.bindings.map((binding) =>
+ binding.binding.type === "expression"
+ ? {
+ ...binding,
+ binding: {
+ ...binding.binding,
+ value: bindExpressionInput(
+ state,
+ binding.instanceId,
+ binding.binding.value
+ ),
+ },
+ }
+ : binding
+ ),
+ },
+ context
+ ),
+ warnings
+ );
+ }
),
runtimeOperation(
"instances.listTexts",
@@ -1123,16 +1243,29 @@ export const builderRuntimeOperations = [
retryOnConflict: true,
}),
instances.updateTextInstanceInput,
- ({ state, input }) =>
- instances.updateTextInstance(
- state,
+ ({ state, input }) => {
+ const warnings =
input.mode === "expression"
- ? {
- ...input,
- text: bindExpressionInput(state, input.instanceId, input.text),
- }
- : input
- )
+ ? getScopedExpressionWarnings(
+ state,
+ input.instanceId,
+ ["text"],
+ input.text
+ )
+ : [];
+ return withExpressionWarnings(
+ instances.updateTextInstance(
+ state,
+ input.mode === "expression"
+ ? {
+ ...input,
+ text: bindExpressionInput(state, input.instanceId, input.text),
+ }
+ : input
+ ),
+ warnings
+ );
+ }
),
runtimeOperation(
"instances.replaceText",
@@ -1154,16 +1287,29 @@ export const builderRuntimeOperations = [
retryOnConflict: true,
}),
instances.setTextContentInput,
- ({ state, input }) =>
- instances.setTextContent(
- state,
+ ({ state, input }) => {
+ const warnings =
input.operation === "set" && input.mode === "expression"
- ? {
- ...input,
- text: bindExpressionInput(state, input.instanceId, input.text),
- }
- : input
- )
+ ? getScopedExpressionWarnings(
+ state,
+ input.instanceId,
+ ["text"],
+ input.text
+ )
+ : [];
+ return withExpressionWarnings(
+ instances.setTextContent(
+ state,
+ input.operation === "set" && input.mode === "expression"
+ ? {
+ ...input,
+ text: bindExpressionInput(state, input.instanceId, input.text),
+ }
+ : input
+ ),
+ warnings
+ );
+ }
),
runtimeOperation(
"instances.updateTextTree",
diff --git a/packages/project-build/src/runtime/slot.ts b/packages/project-build/src/runtime/slot.ts
index 2060848025..5eb475e4c7 100644
--- a/packages/project-build/src/runtime/slot.ts
+++ b/packages/project-build/src/runtime/slot.ts
@@ -4,21 +4,19 @@ import {
extractWebstudioFragment,
insertWebstudioFragmentCopy,
} from "./fragment";
+import type {
+ InstancePath,
+ InstancePathItem,
+ InstanceSelector,
+} from "./instance-path";
+
+export type { InstancePath, InstancePathItem } from "./instance-path";
type SlotDropTarget = {
parentSelector: Instance["id"][];
position: number | "end";
};
-export type InstanceSelector = Instance["id"][];
-
-export type InstancePathItem = {
- instance: Instance;
- instanceSelector: InstanceSelector;
-};
-
-export type InstancePath = InstancePathItem[];
-
export type SharedSlotBoundary = {
slotIndex: number;
fragmentItem: InstancePathItem;
diff --git a/packages/project-build/src/runtime/styles.test.ts b/packages/project-build/src/runtime/styles.test.ts
index 58b43d7546..549381df52 100644
--- a/packages/project-build/src/runtime/styles.test.ts
+++ b/packages/project-build/src/runtime/styles.test.ts
@@ -46,6 +46,7 @@ import {
getInstanceIdByStyleSourceId,
getReferencedCssVariables,
getStyleSourceInsertionIndex,
+ getStyleDeclarations,
getUnusedCssVariableNames,
performCssVariableRename,
renameCssVariable,
@@ -1602,6 +1603,11 @@ describe("serializeDesignTokens", () => {
withUsage: true,
})
).toEqual({
+ detail: "compact",
+ filters: { filter: "Primary", withUsage: true },
+ nextCursor: null,
+ returnedCount: 1,
+ total: 1,
tokens: [
{
id: "primary",
@@ -1629,30 +1635,46 @@ describe("serializeDesignTokens", () => {
).toEqual(["secondary", "primary"]);
});
- test("includes full token styles only when requested", () => {
- expect(
- serializeDesignTokens({
- styleSources: sources([token("primary", "Primary")]),
- styles: createStyleDeclMap([
- createStyleDecl("primary", "base", "color", {
- type: "keyword",
- value: "red",
- }),
- ]),
- styleSourceSelections: [],
- includeStyles: true,
- })
- ).toEqual({
+ test("includes full token styles only in verbose output", () => {
+ const tokenValue = {
+ type: "unparsed" as const,
+ value: `linear-gradient(${"red 0 1px, blue 1px 2px, ".repeat(80)}red)`,
+ };
+ const compact = serializeDesignTokens({
+ styleSources: sources([token("primary", "Primary")]),
+ styles: createStyleDeclMap([
+ createStyleDecl("primary", "base", "backgroundImage", tokenValue),
+ ]),
+ styleSourceSelections: [],
+ });
+ const verbose = serializeDesignTokens({
+ styleSources: sources([token("primary", "Primary")]),
+ styles: createStyleDeclMap([
+ createStyleDecl("primary", "base", "backgroundImage", tokenValue),
+ ]),
+ styleSourceSelections: [],
+ verbose: true,
+ });
+ expect(verbose).toEqual({
+ detail: "verbose",
+ filters: {},
+ nextCursor: null,
+ returnedCount: 1,
+ total: 1,
tokens: [
{
id: "primary",
name: "Primary",
declarationCount: 1,
- styles: { color: { type: "keyword", value: "red" } },
+ styles: { backgroundImage: tokenValue },
usageCount: 0,
},
],
});
+ expect(verbose.tokens[0]).toMatchObject(compact.tokens[0] ?? {});
+ expect(JSON.stringify(compact).length).toBeLessThan(
+ JSON.stringify(verbose).length * 0.5
+ );
});
test("includes usage by default and allows omitting it", () => {
@@ -1669,6 +1691,50 @@ describe("serializeDesignTokens", () => {
});
});
+test("expands style values without changing pagination or filters", () => {
+ const largeValue = {
+ type: "unparsed" as const,
+ value: `linear-gradient(${"red 0 1px, blue 1px 2px, ".repeat(80)}red)`,
+ };
+ const largeStyle = { ...displayStyle, value: largeValue };
+ const styleState = {
+ pages: undefined,
+ instances: undefined,
+ styles: new Map([[displayStyleKey, largeStyle]]),
+ styleSources: new Map([[localStyleSource.id, localStyleSource]]),
+ styleSourceSelections: new Map([
+ ["box", { instanceId: "box", values: [localStyleSource.id] }],
+ ]),
+ };
+ const compact = getStyleDeclarations(styleState, { limit: 1 });
+ const verbose = getStyleDeclarations(styleState, {
+ limit: 1,
+ verbose: true,
+ });
+
+ expect(compact).toMatchObject({
+ detail: "compact",
+ returnedCount: 1,
+ declarations: [{ property: "display", valueType: "unparsed" }],
+ });
+ expect(compact.declarations[0]).not.toHaveProperty("value");
+ expect(verbose).toMatchObject({
+ detail: "verbose",
+ total: compact.total,
+ returnedCount: compact.returnedCount,
+ nextCursor: compact.nextCursor,
+ declarations: [
+ expect.objectContaining({
+ ...compact.declarations[0],
+ value: largeValue,
+ }),
+ ],
+ });
+ expect(JSON.stringify(compact).length).toBeLessThan(
+ JSON.stringify(verbose).length * 0.5
+ );
+});
+
describe("getLocalStyleSourceId", () => {
test("returns local style source id from selection", () => {
const styleSources = sources([
diff --git a/packages/project-build/src/runtime/styles.ts b/packages/project-build/src/runtime/styles.ts
index 6747f8947f..167d093f92 100644
--- a/packages/project-build/src/runtime/styles.ts
+++ b/packages/project-build/src/runtime/styles.ts
@@ -19,6 +19,11 @@ import {
type Styles,
} from "@webstudio-is/sdk";
import type { BuilderPatch, BuilderPatchChange } from "../contracts/patch";
+import {
+ paginateOutput,
+ projectOutput,
+ type PaginatedOutputInput,
+} from "./output";
import type { BuilderState } from "../state/builder-state";
import {
findSerializedPageByInput,
@@ -40,9 +45,11 @@ export const serializeDesignTokens = ({
styleSourceSelections,
filter,
withUsage,
- includeStyles,
sort,
-}: {
+ cursor,
+ limit,
+ verbose,
+}: PaginatedOutputInput & {
styleSources: Iterable<StyleSource> | Map<string, StyleSource>;
styles: Iterable<StyleDecl> | Map<string, StyleDecl>;
styleSourceSelections:
@@ -50,7 +57,6 @@ export const serializeDesignTokens = ({
| Map<string, StyleSourceSelection>;
filter?: string;
withUsage?: boolean;
- includeStyles?: boolean;
sort?: "name" | "usage";
}) => {
const shouldCountUsage = withUsage !== false || sort === "usage";
@@ -76,18 +82,21 @@ export const serializeDesignTokens = ({
const usageCount = selections.filter((selection) =>
selection.values.includes(styleSource.id)
).length;
- return {
+ const compact = {
id: styleSource.id,
name: styleSource.name,
declarationCount: tokenDecls.length,
- styles:
- includeStyles === true
- ? Object.fromEntries(
- tokenDecls.map((style) => [style.property, style.value])
- )
- : undefined,
usageCount: shouldCountUsage ? usageCount : undefined,
};
+ return projectOutput({
+ input: { verbose },
+ compact,
+ expanded: () => ({
+ styles: Object.fromEntries(
+ tokenDecls.map((style) => [style.property, style.value])
+ ),
+ }),
+ });
});
tokens.sort((left, right) =>
@@ -95,7 +104,15 @@ export const serializeDesignTokens = ({
? (right.usageCount ?? 0) - (left.usageCount ?? 0)
: left.name.localeCompare(right.name)
);
- return { tokens };
+ const { items, ...pagination } = paginateOutput({
+ items: tokens,
+ cursor,
+ limit,
+ filters: { filter, withUsage, sort },
+ verbose,
+ invalidCursorMessage: "Invalid design token cursor",
+ });
+ return { tokens: items, ...pagination };
};
const getRequiredStyleState = (
@@ -123,7 +140,7 @@ export const getStyleDeclarations = (
BuilderState,
"pages" | "instances" | "styles" | "styleSources" | "styleSourceSelections"
>,
- input: {
+ input: PaginatedOutputInput & {
instanceIds?: string[];
pageId?: string;
pagePath?: string;
@@ -168,19 +185,41 @@ export const getStyleDeclarations = (
pageInstanceIds.has(instanceId)
)
);
- return {
- declarations: serializeStyleDeclarations({
- styles: styleState.styles.values(),
- styleSources: styleState.styleSources.values(),
- styleSourceSelections: styleState.styleSourceSelections.values(),
- instanceIds,
+ const declarations = serializeStyleDeclarations({
+ styles: styleState.styles.values(),
+ styleSources: styleState.styleSources.values(),
+ styleSourceSelections: styleState.styleSourceSelections.values(),
+ instanceIds,
+ breakpoint: input.breakpoint,
+ state: input.state,
+ property,
+ propertyFilter: input.propertyFilter,
+ includeTokens: input.includeTokens,
+ }).map(({ value, ...compact }) =>
+ projectOutput({
+ input,
+ compact: { ...compact, valueType: value.type },
+ expanded: () => ({ value }),
+ })
+ );
+ const { items, ...pagination } = paginateOutput({
+ items: declarations,
+ cursor: input.cursor,
+ limit: input.limit,
+ filters: {
+ instanceIds: input.instanceIds,
+ pageId: input.pageId,
+ pagePath: input.pagePath,
breakpoint: input.breakpoint,
state: input.state,
- property,
+ property: input.property,
propertyFilter: input.propertyFilter,
includeTokens: input.includeTokens,
- }),
- };
+ },
+ verbose: input.verbose,
+ invalidCursorMessage: "Invalid style cursor",
+ });
+ return { declarations: items, ...pagination };
};
export const listDesignTokens = (
@@ -188,10 +227,9 @@ export const listDesignTokens = (
BuilderState,
"styles" | "styleSources" | "styleSourceSelections"
>,
- input: {
+ input: PaginatedOutputInput & {
filter?: string;
withUsage?: boolean;
- includeStyles?: boolean;
sort?: "name" | "usage";
} = {}
) => serializeDesignTokens({ ...getRequiredStyleState(state), ...input });
diff --git a/packages/project-build/src/runtime/tree.ts b/packages/project-build/src/runtime/tree.ts
index 6fa9d04548..2e65742cca 100644
--- a/packages/project-build/src/runtime/tree.ts
+++ b/packages/project-build/src/runtime/tree.ts
@@ -14,9 +14,10 @@ import {
isTreeSatisfyingContentModel,
} from "./content-model";
import { findClosestInstanceMatchingFragment } from "./matcher";
-import { getSlotFragmentDropTargetMutable, type InstancePath } from "./slot";
+import { getSlotFragmentDropTargetMutable } from "./slot";
+import type { InstancePath, InstanceSelector } from "./instance-path";
-export type InstanceSelector = Instance["id"][];
+export type { InstanceSelector } from "./instance-path";
export type DroppableTarget = {
parentSelector: InstanceSelector;
diff --git a/packages/project-build/src/schema.ts b/packages/project-build/src/schema.ts
index 72952995eb..ca1789c90c 100644
--- a/packages/project-build/src/schema.ts
+++ b/packages/project-build/src/schema.ts
@@ -60,7 +60,7 @@ const serializedBuildShape = {
deployment: deployment.optional(),
} satisfies SchemaShape<SerializedBuild>;
-// Canonical project-build schema entrypoint for API-facing serialized builds.
+// Canonical project-build contract for API-facing serialized builds.
// API packages compose this schema; they should not copy or maintain it.
export const serializedBuild: z.ZodObject<typeof serializedBuildShape> =
z.object(serializedBuildShape);
diff --git a/packages/project-build/src/server.ts b/packages/project-build/src/server.ts
new file mode 100644
index 0000000000..f04101500d
--- /dev/null
+++ b/packages/project-build/src/server.ts
@@ -0,0 +1 @@
+export * from "./index.server";
diff --git a/packages/project-build/src/state.ts b/packages/project-build/src/state.ts
new file mode 100644
index 0000000000..905214b329
--- /dev/null
+++ b/packages/project-build/src/state.ts
@@ -0,0 +1,4 @@
+export * from "./state/adapters";
+export * from "./state/builder-state";
+export * from "./state/freshness";
+export * from "./state/patch";
diff --git a/packages/project-build/src/state/patch.ts b/packages/project-build/src/state/patch.ts
index 8217a4b6ec..9b782f67f1 100644
--- a/packages/project-build/src/state/patch.ts
+++ b/packages/project-build/src/state/patch.ts
@@ -9,8 +9,8 @@ import { compactBuilderPatchPayload } from "../contracts/patch";
import type { BuilderState } from "./builder-state";
import type { BuilderNamespace } from "../contracts/namespaces";
-// Keep initialization attached to the patch implementation. A bare side-effect
-// import can be removed because project-build declares sideEffects: false.
+// Initialize when this module is imported directly, independently of bundler
+// side-effect handling.
enableImmerPatchPlugins();
export class MissingBuilderStateNamespaceError extends Error {
diff --git a/packages/project-build/src/transfer.server.ts b/packages/project-build/src/transfer.server.ts
new file mode 100644
index 0000000000..6dbce90a59
--- /dev/null
+++ b/packages/project-build/src/transfer.server.ts
@@ -0,0 +1 @@
+export { parseWebstudioJsxFragment } from "./runtime/jsx";
diff --git a/packages/project-build/src/transfer.ts b/packages/project-build/src/transfer.ts
new file mode 100644
index 0000000000..b23bab08a6
--- /dev/null
+++ b/packages/project-build/src/transfer.ts
@@ -0,0 +1,8 @@
+export * from "./runtime/data-formats/data-envelope";
+export * from "./runtime/data-formats/instance-transfer";
+export * from "./runtime/data-formats/page-transfer";
+export * from "./runtime/jsx/syntax";
+export * from "./runtime/jsx/utils";
+export * from "./runtime/webflow/instances-properties";
+export * from "./runtime/webflow/schema";
+export * from "./runtime/webflow/styles";
diff --git a/packages/project-build/src/visual.ts b/packages/project-build/src/visual.ts
new file mode 100644
index 0000000000..237a684159
--- /dev/null
+++ b/packages/project-build/src/visual.ts
@@ -0,0 +1,2 @@
+export * from "./visual/screenshot-browser";
+export * from "./visual/screenshot-diff";
diff --git a/packages/project/src/db/build-patch-core.ts b/packages/project/src/db/build-patch-core.ts
index 96b4cc1f12..14cbfa4c63 100644
--- a/packages/project/src/db/build-patch-core.ts
+++ b/packages/project/src/db/build-patch-core.ts
@@ -27,10 +27,12 @@ import {
getHomePage,
} from "@webstudio-is/sdk";
import {
- findCycles,
type MarketplaceProduct,
type ProjectSettings,
marketplaceProduct,
+} from "@webstudio-is/project-build";
+import { findCycles } from "@webstudio-is/project-build/runtime";
+import {
parsePages,
serializePages,
parseStyleSourceSelections,
@@ -42,12 +44,12 @@ import {
parseInstanceData,
serializeConfig,
serializeData,
-} from "@webstudio-is/project-build";
+} from "@webstudio-is/project-build/persistence";
import type {
BuilderPatch,
BuilderPatchTransaction,
-} from "@webstudio-is/project-build/contracts/patch";
-import { applyBuilderNamespacePatches } from "@webstudio-is/project-build/state/patch";
+} from "@webstudio-is/project-build/contracts";
+import { applyBuilderNamespacePatches } from "@webstudio-is/project-build/state";
import type { Database } from "@webstudio-is/postgrest/index.server";
type TouchedKeys = {
diff --git a/packages/project/src/db/build-patch-permissions.test.ts b/packages/project/src/db/build-patch-permissions.test.ts
index 57ccf4ac9e..d1c0a25801 100644
--- a/packages/project/src/db/build-patch-permissions.test.ts
+++ b/packages/project/src/db/build-patch-permissions.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, test } from "vitest";
import { getRequiredPermitForBuildPatchTransaction } from "./build-patch-permissions";
import type { BuildPatchTransaction } from "./build-patch-core";
-import type { ContentModeCapabilities } from "@webstudio-is/project-build/runtime/content-mode-permissions";
+import type { ContentModeCapabilities } from "@webstudio-is/project-build/runtime";
const transaction = (
namespace: string,
diff --git a/packages/project/src/db/build-patch-permissions.ts b/packages/project/src/db/build-patch-permissions.ts
index 394dc72eb8..f12dd90fe1 100644
--- a/packages/project/src/db/build-patch-permissions.ts
+++ b/packages/project/src/db/build-patch-permissions.ts
@@ -3,7 +3,7 @@ import type { BuildPatchTransaction } from "./build-patch-core";
import {
validateContentModeTransaction,
type ContentModeCapabilities,
-} from "@webstudio-is/project-build/runtime/content-mode-permissions";
+} from "@webstudio-is/project-build/runtime";
export const getRequiredPermitForBuildPatchTransaction = (
transaction: BuildPatchTransaction,
diff --git a/packages/project/src/db/build-patch.ts b/packages/project/src/db/build-patch.ts
index 213e2be763..5b0273495e 100644
--- a/packages/project/src/db/build-patch.ts
+++ b/packages/project/src/db/build-patch.ts
@@ -1,6 +1,6 @@
import { patchAssets } from "@webstudio-is/asset-uploader/index.server";
import type { Build } from "@webstudio-is/project-build";
-import { loadRawBuildById } from "@webstudio-is/project-build/index.server";
+import { loadRawBuildById } from "@webstudio-is/project-build/server";
import type { Database } from "@webstudio-is/postgrest/index.server";
import type { AppContext } from "@webstudio-is/trpc-interface/index.server";
import type { Project } from "./project";
diff --git a/packages/project/src/db/project.ts b/packages/project/src/db/project.ts
index ed71a16230..3a69991e06 100644
--- a/packages/project/src/db/project.ts
+++ b/packages/project/src/db/project.ts
@@ -5,7 +5,7 @@ import {
AuthorizationError,
getPlanFeaturesByOwnerId,
} from "@webstudio-is/trpc-interface/index.server";
-import { createBuild } from "@webstudio-is/project-build/index.server";
+import { createBuild } from "@webstudio-is/project-build/server";
import { projectTitle } from "../shared/project-schema";
import type { MarketplaceApprovalStatus } from "../shared/marketplace-schema";
import { generateDomain, validateProjectDomain } from "./project-domain";
diff --git a/packages/protocol/README.md b/packages/protocol/README.md
index c27ff778aa..a58c1ecba7 100644
--- a/packages/protocol/README.md
+++ b/packages/protocol/README.md
@@ -26,7 +26,7 @@ Webstudio-owned data before falling back to other formats.
`InstanceTransferData`, `InstancesTransferData`, and `PageTransferData`.
Transfer data is portable and detached from a project; insertion/import remaps
ids and merges it into authoritative project state. Runtime-owned transfer
-formats live in `@webstudio-is/project-build/runtime/data-formats/*`.
+formats live in `@webstudio-is/project-build/transfer`.
**Clipboard data** is a UI transport concern. Builder copy/paste may serialize
transfer data into a data envelope and place it on the browser clipboard, but
diff --git a/packages/protocol/src/builder-api/local-operation-inputs.ts b/packages/protocol/src/builder-api/local-operation-inputs.ts
index 0c06e9495f..644adf0cf1 100644
--- a/packages/protocol/src/builder-api/local-operation-inputs.ts
+++ b/packages/protocol/src/builder-api/local-operation-inputs.ts
@@ -1,5 +1,5 @@
import { z } from "zod";
-import { getInputSchemaMetadata } from "@webstudio-is/project-build/contracts/input-schema";
+import { getInputSchemaMetadata } from "@webstudio-is/project-build/contracts";
import type { InputJsonSchema } from "@webstudio-is/sdk";
import type { PublicApiOperationNamespace } from "./runtime-contracts";
diff --git a/packages/protocol/src/builder-api/runtime-contracts.test.ts b/packages/protocol/src/builder-api/runtime-contracts.test.ts
index c323333713..9e82755c17 100644
--- a/packages/protocol/src/builder-api/runtime-contracts.test.ts
+++ b/packages/protocol/src/builder-api/runtime-contracts.test.ts
@@ -1,8 +1,8 @@
import { readFile } from "node:fs/promises";
import { expect, test } from "vitest";
-import { runtimeOperationContracts } from "@webstudio-is/project-build/contracts/builder-runtime";
-import { builderApiCapabilities } from "@webstudio-is/project-build/contracts/permissions";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
+import { runtimeOperationContracts } from "@webstudio-is/project-build/contracts";
+import { builderApiCapabilities } from "@webstudio-is/project-build/contracts";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
import {
publicApiOperationNamespaces,
publicApiOperationPermits,
diff --git a/packages/protocol/src/builder-api/runtime-contracts.ts b/packages/protocol/src/builder-api/runtime-contracts.ts
index 94a2afffc1..96f165ca76 100644
--- a/packages/protocol/src/builder-api/runtime-contracts.ts
+++ b/packages/protocol/src/builder-api/runtime-contracts.ts
@@ -1,6 +1,6 @@
-import { runtimeOperationContracts } from "@webstudio-is/project-build/contracts/builder-runtime";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
-import { builderApiCapabilities } from "@webstudio-is/project-build/contracts/permissions";
+import { runtimeOperationContracts } from "@webstudio-is/project-build/contracts";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
+import { builderApiCapabilities } from "@webstudio-is/project-build/contracts";
import type { InputJsonSchema } from "@webstudio-is/sdk";
export type { InputJsonSchema };
diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts
index a2a274783c..2e46f9088a 100644
--- a/packages/protocol/src/index.ts
+++ b/packages/protocol/src/index.ts
@@ -9,3 +9,4 @@ export * from "./builder-api/errors";
export * from "./builder-api/runtime-contracts";
export * from "./builder-api/operations";
export * from "./builder-api/url";
+export * from "./mcp-client";
diff --git a/packages/protocol/src/mcp-client.test.ts b/packages/protocol/src/mcp-client.test.ts
new file mode 100644
index 0000000000..236496945b
--- /dev/null
+++ b/packages/protocol/src/mcp-client.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import {
+ agentClients,
+ createAgentClientConfiguration,
+ createAgentShareUrl,
+ createAgentSetupCommand,
+ defaultAgentServerCommand,
+} from "./mcp-client";
+
+describe("agent connection configuration", () => {
+ test.each(agentClients)("generates a valid %s configuration", (client) => {
+ const configuration = createAgentClientConfiguration(client);
+
+ expect(configuration.client).toBe(client);
+ expect(configuration.content).toContain("webstudio");
+ expect(configuration.content).toContain("webstudio@latest");
+ expect(configuration.hint.length).toBeGreaterThan(10);
+
+ if (client === "codex") {
+ expect(configuration.path).toBe("~/.codex/config.toml");
+ expect(configuration.content).toContain("[mcp_servers.webstudio]");
+ return;
+ }
+
+ const parsed = JSON.parse(configuration.content);
+ const root = client === "vscode" ? parsed.servers : parsed.mcpServers;
+ expect(root.webstudio).toMatchObject({
+ command: "npx",
+ args: ["-y", "webstudio@latest", "mcp"],
+ });
+ });
+
+ test("keeps authentication in the setup command, not client configuration", () => {
+ const shareUrl =
+ "https://p-project.wstd.dev/?authToken=secret-token&mode=design";
+ const command = createAgentSetupCommand({ client: "claude", shareUrl });
+ const configuration = createAgentClientConfiguration("claude");
+
+ expect(command).toContain(`init --link '${shareUrl}' --json`);
+ expect(command).toContain("sync");
+ expect(command).toContain("connect claude");
+ expect(command.match(/secret-token/g)).toHaveLength(1);
+ expect(configuration.content).not.toContain("secret-token");
+ });
+
+ test("quotes share links without changing the shared server command", () => {
+ const command = createAgentSetupCommand({
+ client: "codex",
+ shareUrl: "https://example.com/project?name=O'Brien",
+ });
+
+ expect(command).toContain(`O'\"'\"'Brien`);
+ expect(createAgentClientConfiguration("codex").content).toContain(
+ `args = ["-y", "webstudio@latest", "mcp"]`
+ );
+ expect(defaultAgentServerCommand).toBe("npx -y webstudio@latest mcp");
+ });
+});
+
+test("creates a minimal revocable Builder share URL", () => {
+ expect(
+ createAgentShareUrl({
+ builderUrl:
+ "https://p-project.wstd.dev:5173/?authToken=stale&mode=preview&private=value#fragment",
+ authToken: "fresh token",
+ })
+ ).toBe("https://p-project.wstd.dev:5173/?authToken=fresh+token&mode=design");
+});
diff --git a/packages/protocol/src/mcp-client.ts b/packages/protocol/src/mcp-client.ts
new file mode 100644
index 0000000000..730efc3578
--- /dev/null
+++ b/packages/protocol/src/mcp-client.ts
@@ -0,0 +1,109 @@
+export const agentClients = ["claude", "codex", "cursor", "vscode"] as const;
+export type AgentClient = (typeof agentClients)[number];
+
+export const defaultAgentServerCommand = "npx -y webstudio@latest mcp";
+export const agentServerName = "webstudio";
+
+export const agentClientTargets = {
+ claude: {
+ path: ".mcp.json",
+ rootKey: "mcpServers",
+ hint: "Restart Claude Code in this directory and approve the webstudio server.",
+ },
+ cursor: {
+ path: ".cursor/mcp.json",
+ rootKey: "mcpServers",
+ hint: "Reload Cursor and enable the webstudio server in MCP settings.",
+ },
+ vscode: {
+ path: ".vscode/mcp.json",
+ rootKey: "servers",
+ extraServerFields: { type: "stdio" },
+ hint: "Reload VS Code and start the webstudio server from the MCP view.",
+ },
+} as const;
+
+export const parseAgentServerCommand = (serverCommand: string) => {
+ const [command, ...args] = serverCommand.trim().split(/\s+/);
+ if (command === undefined || command === "") {
+ throw new Error("--command must not be empty.");
+ }
+ return { command, args };
+};
+
+export const createAgentServerEntry = (
+ serverCommand: string,
+ extraServerFields?: Record<string, unknown>
+) => ({ ...extraServerFields, ...parseAgentServerCommand(serverCommand) });
+
+export const createCodexAgentSnippet = (serverCommand: string) => {
+ const { command, args } = parseAgentServerCommand(serverCommand);
+ return [
+ `[mcp_servers.${agentServerName}]`,
+ `command = ${JSON.stringify(command)}`,
+ `args = [${args.map((arg) => JSON.stringify(arg)).join(", ")}]`,
+ ].join("\n");
+};
+
+export const createAgentClientConfiguration = (
+ client: AgentClient,
+ serverCommand = defaultAgentServerCommand
+) => {
+ if (client === "codex") {
+ return {
+ client,
+ path: "~/.codex/config.toml",
+ content: createCodexAgentSnippet(serverCommand),
+ hint: "Restart Codex so it loads the webstudio MCP server.",
+ };
+ }
+ const target = agentClientTargets[client];
+ return {
+ client,
+ path: target.path,
+ content: `${JSON.stringify(
+ {
+ [target.rootKey]: {
+ [agentServerName]: createAgentServerEntry(
+ serverCommand,
+ "extraServerFields" in target ? target.extraServerFields : undefined
+ ),
+ },
+ },
+ null,
+ 2
+ )}\n`,
+ hint: target.hint,
+ };
+};
+
+const quoteShellArgument = (value: string) =>
+ `'${value.replaceAll("'", `'"'"'`)}'`;
+
+export const createAgentSetupCommand = ({
+ client,
+ shareUrl,
+}: {
+ client: AgentClient;
+ shareUrl: string;
+}) =>
+ [
+ `npx -y webstudio@latest init --link ${quoteShellArgument(shareUrl)} --json`,
+ "npx -y webstudio@latest sync",
+ `npx -y webstudio@latest connect ${client}`,
+ ].join(" && ");
+
+export const createAgentShareUrl = ({
+ builderUrl,
+ authToken,
+}: {
+ builderUrl: string;
+ authToken: string;
+}) => {
+ const url = new URL(builderUrl);
+ url.search = "";
+ url.hash = "";
+ url.searchParams.set("authToken", authToken);
+ url.searchParams.set("mode", "design");
+ return url.href;
+};
diff --git a/packages/protocol/src/schema.test.ts b/packages/protocol/src/schema.test.ts
index dd56b7fdbd..b3fa8ef7fd 100644
--- a/packages/protocol/src/schema.test.ts
+++ b/packages/protocol/src/schema.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, test } from "vitest";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
-import { builderPatchTransactionSchema } from "@webstudio-is/project-build/contracts/patch";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
+import { builderPatchTransactionSchema } from "@webstudio-is/project-build/contracts";
import {
isAssetFileName,
getMissingImportedAssetFilesMessage,
diff --git a/packages/protocol/src/schema.ts b/packages/protocol/src/schema.ts
index 2e6fec0fd7..fa2d365e15 100644
--- a/packages/protocol/src/schema.ts
+++ b/packages/protocol/src/schema.ts
@@ -1,10 +1,10 @@
import { asset, page } from "@webstudio-is/sdk/schema";
-import { builderNamespaces } from "@webstudio-is/project-build/contracts/namespaces";
+import { builderNamespaces } from "@webstudio-is/project-build/contracts";
import {
builderPatchSchema as internalBuilderPatchSchema,
builderPatchTransactionSchema as internalBuilderPatchTransactionSchema,
-} from "@webstudio-is/project-build/contracts/patch";
-import { serializedBuild } from "@webstudio-is/project-build/schema";
+} from "@webstudio-is/project-build/contracts";
+import { serializedBuild } from "@webstudio-is/project-build/contracts";
import { wsAuthConfig } from "@webstudio-is/wsauth/schema";
import { z } from "zod";
import { createContractVersion } from "./contract-version";