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: Add draft pages (#5885)

Oleg Isonend579607ed8f4
diff --git a/apps/builder/app/builder/features/command-panel/groups/pages-group.tsx b/apps/builder/app/builder/features/command-panel/groups/pages-group.tsx
index 9fb06ad4df..5da4c4bd90 100644
--- a/apps/builder/app/builder/features/command-panel/groups/pages-group.tsx
+++ b/apps/builder/app/builder/features/command-panel/groups/pages-group.tsx
@@ -14,6 +14,7 @@ import { selectPage } from "~/shared/nano-states";
import { setActiveSidebarPanel } from "~/builder/shared/nano-states";
import { closeCommandPanel, $isCommandPanelOpen } from "../command-state";
import type { BaseOption } from "../shared/types";
+import { getPageDisplayName } from "~/builder/features/pages/page-utils";
export type PageOption = BaseOption & {
type: "page";
@@ -33,7 +34,7 @@ export const $pageOptions = computed(
continue;
}
pageOptions.push({
- terms: ["pages", page.name],
+ terms: ["pages", getPageDisplayName(page)],
type: "page",
page,
});
@@ -75,7 +76,7 @@ export const PagesGroup = ({ options }: { options: PageOption[] }) => {
}
}}
>
- <Text>{page.name}</Text>
+ <Text>{getPageDisplayName(page)}</Text>
</CommandItem>
))}
</CommandGroup>
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 5f1df5bfb1..e428f46b63 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
@@ -23,6 +23,7 @@ import { $activeInspectorPanel } from "~/builder/shared/nano-states";
import { $selectedPageId, selectInstance } from "~/shared/nano-states";
import { useAutoSelectFirstItem } from "./auto-select";
import { InstancePathFooter } from "./instance-path-footer";
+import { getPageDisplayName } from "~/builder/features/pages/page-utils";
export type InstanceOption = {
label: string;
@@ -63,7 +64,7 @@ export const InstanceList = ({
label: getInstanceLabel(instance),
id: instance.id,
path,
- pageName: page?.name ?? "",
+ pageName: page === undefined ? "" : getPageDisplayName(page),
});
}
const [search, setSearch] = useState("");
diff --git a/apps/builder/app/builder/features/pages/confirmation-dialogs.tsx b/apps/builder/app/builder/features/pages/confirmation-dialogs.tsx
index f959cb2535..2d9c829abc 100644
--- a/apps/builder/app/builder/features/pages/confirmation-dialogs.tsx
+++ b/apps/builder/app/builder/features/pages/confirmation-dialogs.tsx
@@ -10,6 +10,7 @@ import {
theme,
} from "@webstudio-is/design-system";
import type { Page, Folder, PageTemplate } from "@webstudio-is/sdk";
+import { getPageDisplayName } from "./page-utils";
type DeletePageConfirmationDialogProps = {
onClose: () => void;
@@ -34,7 +35,7 @@ export const DeletePageConfirmationDialog = ({
<DialogContent>
<DialogTitle>Delete page</DialogTitle>
<Flex gap="3" direction="column" css={{ padding: theme.panel.padding }}>
- <Text>{`Are you sure you want to delete "${page.name}"?`}</Text>
+ <Text>{`Are you sure you want to delete "${getPageDisplayName(page)}"?`}</Text>
<Text>
You can undo it even if you delete the page as long as you don't
reload.
diff --git a/apps/builder/app/builder/features/pages/page-item-actions.tsx b/apps/builder/app/builder/features/pages/page-item-actions.tsx
index 3a73fea653..e5a9b9f399 100644
--- a/apps/builder/app/builder/features/pages/page-item-actions.tsx
+++ b/apps/builder/app/builder/features/pages/page-item-actions.tsx
@@ -12,6 +12,7 @@ import {
theme,
} from "@webstudio-is/design-system";
import { EllipsesIcon } from "@webstudio-is/icons";
+import type { ReactNode } from "react";
export type PageItemActions = {
paste?: () => void;
@@ -87,7 +88,11 @@ export const PageItemContextMenuActions = ({
export const PageItemActionsDropdown = ({
actions,
label = "Actions",
-}: PageItemActionsMenuItemsProps & { label?: string }) => {
+ additionalItems,
+}: PageItemActionsMenuItemsProps & {
+ label?: string;
+ additionalItems?: ReactNode;
+}) => {
return (
<DropdownMenu>
<Tooltip content={label} side="bottom">
@@ -101,6 +106,7 @@ export const PageItemActionsDropdown = ({
</DropdownMenuTrigger>
</Tooltip>
<DropdownMenuContent align="end">
+ {additionalItems}
{items
.filter((item) => item.name !== "paste")
.map((item) => {
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 60e9e00d11..b2cbe1f12f 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
@@ -3,6 +3,8 @@ import { useStore } from "@nanostores/react";
import {
type Page,
findPageByIdOrPath,
+ getPageDraftabilityError,
+ isPageDraft,
isLiteralExpression,
} from "@webstudio-is/sdk";
import {
@@ -18,6 +20,7 @@ import {
DialogClose,
DialogTitle,
DialogTitleActions,
+ DropdownMenuItem,
} from "@webstudio-is/design-system";
import {
$authPermit,
@@ -114,6 +117,7 @@ export const FormFields = ({
canEditName = true,
canEditPath = true,
showHomePageControl = true,
+ canSetHomePage = true,
showPathField = true,
showStatusField = isEditorContext === false,
showRedirectField = isEditorContext === false,
@@ -133,6 +137,7 @@ export const FormFields = ({
canEditName?: boolean;
canEditPath?: boolean;
showHomePageControl?: boolean;
+ canSetHomePage?: boolean;
showPathField?: boolean;
showStatusField?: boolean;
showRedirectField?: boolean;
@@ -190,6 +195,7 @@ export const FormFields = ({
canEditName={canEditName}
canEditPath={canEditPath}
showHomePageControl={showHomePageControl}
+ canSetHomePage={canSetHomePage}
showPathField={showPathField}
showStatusField={showStatusField}
showRedirectField={showRedirectField}
@@ -422,6 +428,14 @@ export const PageSettings = ({
const isContentMode = useStore($isContentMode);
const isHomePage = page?.id === pages?.homePageId;
+ const canChangeDraftState =
+ page !== undefined &&
+ pages !== undefined &&
+ getPageDraftabilityError({
+ pageId: page.id,
+ pagePath: page.path,
+ homePageId: pages.homePageId,
+ }) === undefined;
const [refreshDebounce, setRefreshDebounce] = useState(0);
let errors: PageSettingsErrors = {};
@@ -512,6 +526,24 @@ export const PageSettings = ({
});
}
}}
+ draftAction={
+ canChangeDraftState === false
+ ? undefined
+ : {
+ label: isPageDraft(page)
+ ? "Stage for publish"
+ : "Mark as draft",
+ onSelect: () => {
+ executeRuntimeMutation({
+ id: "pages.update",
+ input: {
+ pageId,
+ values: { isDraft: isPageDraft(page) === false },
+ },
+ });
+ },
+ }
+ }
>
<FormFields
errors={errors}
@@ -523,6 +555,7 @@ export const PageSettings = ({
isContentMode,
path: page.path,
})}
+ canSetHomePage={isPageDraft(page) === false}
onChange={handleChange}
/>
</PageSettingsView>
@@ -563,12 +596,14 @@ const PageSettingsView = ({
onDelete,
onDuplicate,
onClose,
+ draftAction,
children,
}: {
onCopy: () => void;
onDelete?: () => void;
onDuplicate: () => void;
onClose: () => void;
+ draftAction?: { label: string; onSelect: () => void };
children: JSX.Element;
}) => {
const isDesignMode = useStore($isDesignMode);
@@ -586,6 +621,13 @@ const PageSettingsView = ({
{isDesignMode && (
<PageItemActionsDropdown
label="Page actions"
+ additionalItems={
+ draftAction && (
+ <DropdownMenuItem onSelect={draftAction.onSelect}>
+ {draftAction.label}
+ </DropdownMenuItem>
+ )
+ }
actions={{
copy: onCopy,
duplicate: onDuplicate,
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 91c7e61d9b..fa56b5891a 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
@@ -287,6 +287,7 @@ export const GeneralSection = ({
canEditName = true,
canEditPath = true,
showHomePageControl = true,
+ canSetHomePage = true,
showPathField = true,
showStatusField = true,
showRedirectField = true,
@@ -303,6 +304,7 @@ export const GeneralSection = ({
canEditName?: boolean;
canEditPath?: boolean;
showHomePageControl?: boolean;
+ canSetHomePage?: boolean;
showPathField?: boolean;
showStatusField?: boolean;
showRedirectField?: boolean;
@@ -348,6 +350,13 @@ export const GeneralSection = ({
“{values.name}” is the home page
</Text>
</>
+ ) : canSetHomePage === false ? (
+ <>
+ <HomeIcon color={rawTheme.colors.foregroundSubtle} />
+ <Text color="subtle">
+ Stage this page for publish before setting it as the home page
+ </Text>
+ </>
) : values.parentFolderId !== pages.rootFolderId ? (
<>
<HomeIcon color={rawTheme.colors.foregroundSubtle} />
diff --git a/apps/builder/app/builder/features/pages/page-utils.test.ts b/apps/builder/app/builder/features/pages/page-utils.test.ts
index 345e911c52..a2b2468fb5 100644
--- a/apps/builder/app/builder/features/pages/page-utils.test.ts
+++ b/apps/builder/app/builder/features/pages/page-utils.test.ts
@@ -16,6 +16,7 @@ import {
$pageRootScope,
duplicateFolder,
duplicateTemplate,
+ getPageDisplayName,
instantiateTemplate,
isFolder,
} from "./page-utils";
@@ -41,6 +42,22 @@ import { $resourcesCache, getResourceKey } from "~/shared/resources";
setEnv("*");
registerContainers();
+test("prefixes draft page display names without changing the stored name", () => {
+ const page = {
+ id: "page",
+ name: "Pricing",
+ path: "/pricing",
+ title: `"Pricing"`,
+ rootInstanceId: "root",
+ meta: {},
+ isDraft: true,
+ } satisfies Page;
+
+ expect(getPageDisplayName(page)).toBe("[Draft] Pricing");
+ expect(page.name).toBe("Pricing");
+ expect(getPageDisplayName({ ...page, isDraft: false })).toBe("Pricing");
+});
+
const initialSystem = {
origin: "https://undefined.wstd.work",
params: {},
diff --git a/apps/builder/app/builder/features/pages/page-utils.ts b/apps/builder/app/builder/features/pages/page-utils.ts
index 2d0e06ca09..51769b1afb 100644
--- a/apps/builder/app/builder/features/pages/page-utils.ts
+++ b/apps/builder/app/builder/features/pages/page-utils.ts
@@ -12,12 +12,16 @@ import {
ROOT_INSTANCE_ID,
systemParameter,
SYSTEM_VARIABLE_ID,
+ isPageDraft,
} 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";
import { $selectedPage, getInstanceKey } from "~/shared/nano-states";
+export const getPageDisplayName = (page: Page) =>
+ isPageDraft(page) ? `[Draft] ${page.name}` : page.name;
+
export const $pageRootScope = computed(
[$selectedPage, $variableValuesByInstanceSelector, $dataSources],
(page, variableValuesByInstanceSelector, dataSources) => {
diff --git a/apps/builder/app/builder/features/pages/pages.tsx b/apps/builder/app/builder/features/pages/pages.tsx
index a52a0a557e..b3ec2caa0c 100644
--- a/apps/builder/app/builder/features/pages/pages.tsx
+++ b/apps/builder/app/builder/features/pages/pages.tsx
@@ -60,7 +60,7 @@ import {
getAllChildrenAndSelf,
getStoredPageDropTarget,
} from "@webstudio-is/project-build/runtime";
-import { duplicateFolder, isFolder } from "./page-utils";
+import { duplicateFolder, getPageDisplayName, isFolder } from "./page-utils";
import {
FolderSettings,
NewFolderSettings,
@@ -450,7 +450,7 @@ const PagesTree = ({
role: "group",
"aria-label":
item.type === "page"
- ? `Page ${item.page.name}`
+ ? `Page ${getPageDisplayName(item.page)}`
: `Folder ${item.folder.name}`,
}}
buttonProps={{
@@ -519,7 +519,7 @@ const PagesTree = ({
)
}
>
- {item.page.name}
+ {getPageDisplayName(item.page)}
</TreeNodeLabel>
)}
</TreeNode>
diff --git a/apps/builder/app/builder/features/publish/restricted-features.test.ts b/apps/builder/app/builder/features/publish/restricted-features.test.ts
index b59de621d1..b53f71bbef 100644
--- a/apps/builder/app/builder/features/publish/restricted-features.test.ts
+++ b/apps/builder/app/builder/features/publish/restricted-features.test.ts
@@ -67,19 +67,62 @@ const getFeatures = ({
pages,
projectSettings,
permissions,
+ dataSources = new Map<string, DataSource>(),
+ instances = new Map<string, Instance>(),
}: {
pages: Pages | undefined;
projectSettings?: ProjectSettings;
permissions: Partial<RestrictedFeaturesPermissions>;
+ dataSources?: Map<string, DataSource>;
+ instances?: Map<string, Instance>;
}) =>
getRestrictedFeatures({
pages,
projectSettings,
- dataSources: new Map<string, DataSource>(),
- instances: new Map<string, Instance>(),
+ dataSources,
+ instances,
permissions: { ...defaultPermissions, ...permissions },
});
+const getPageRestrictedFeatures = (isDraft: boolean) => {
+ const page = createPage({
+ id: isDraft ? "draft" : "published",
+ path: isDraft ? "/draft/:slug" : "/published/:slug",
+ isDraft,
+ meta: {
+ auth: { method: "basic", login: "admin", password: "secret" },
+ redirect: `"/redirect"`,
+ },
+ });
+ return getFeatures({
+ pages: createPages({ pages: [homePage, page] }),
+ permissions: { allowAuth: false, allowDynamicData: false },
+ instances: new Map([
+ [
+ page.rootInstanceId,
+ {
+ type: "instance",
+ id: page.rootInstanceId,
+ component: "ws:element",
+ children: [],
+ },
+ ],
+ ]),
+ dataSources: new Map([
+ [
+ "resource-variable",
+ {
+ type: "resource",
+ id: "resource-variable",
+ resourceId: "resource",
+ scopeInstanceId: page.rootInstanceId,
+ name: "resourceVariable",
+ },
+ ],
+ ]),
+ });
+};
+
describe("getRestrictedFeatures", () => {
test("restricts project authentication when auth is not allowed", () => {
const features = getFeatures({
@@ -163,4 +206,17 @@ describe("getRestrictedFeatures", () => {
expect(features.has("Project auth")).toBe(false);
expect(features.has("Page auth")).toBe(false);
});
+
+ test("ignores restricted features used only by draft pages", () => {
+ expect(getPageRestrictedFeatures(true).size).toBe(0);
+ });
+
+ test("restricts dynamic features used by publishable pages", () => {
+ expect([...getPageRestrictedFeatures(false).keys()]).toEqual([
+ "Page auth",
+ "Dynamic path",
+ "Redirect",
+ "Resource variable",
+ ]);
+ });
});
diff --git a/apps/builder/app/builder/features/publish/restricted-features.ts b/apps/builder/app/builder/features/publish/restricted-features.ts
index 9bdb9b027f..884631bf16 100644
--- a/apps/builder/app/builder/features/publish/restricted-features.ts
+++ b/apps/builder/app/builder/features/publish/restricted-features.ts
@@ -1,6 +1,6 @@
import type { ReactNode } from "react";
import {
- getAllPages,
+ getPublishablePages,
isPathnamePattern,
type DataSource,
type Instance,
@@ -40,6 +40,8 @@ export const getRestrictedFeatures = ({
if (pages === undefined) {
return features;
}
+ const publishablePages = getPublishablePages(pages);
+ const publishablePageIds = new Set(publishablePages.map((page) => page.id));
const projectMeta = projectSettings?.meta;
if (
permissions.maxContactEmailsPerProject === 0 &&
@@ -51,7 +53,7 @@ export const getRestrictedFeatures = ({
if ((projectMeta?.auth ?? "").trim()) {
features.set("Project auth", undefined);
}
- for (const page of getAllPages(pages)) {
+ for (const page of publishablePages) {
if (page.meta.auth !== undefined) {
features.set("Page auth", {
navigate: {
@@ -64,7 +66,7 @@ export const getRestrictedFeatures = ({
}
}
if (permissions.allowDynamicData === false) {
- for (const page of getAllPages(pages)) {
+ for (const page of publishablePages) {
const navigate = {
pageId: page.id,
instanceSelector: [page.rootInstanceId],
@@ -79,12 +81,16 @@ export const getRestrictedFeatures = ({
for (const dataSource of dataSources.values()) {
if (dataSource.type === "resource") {
const instanceId = dataSource.scopeInstanceId ?? "";
+ const navigate = findPageAndSelectorByInstanceId(
+ pages,
+ instances,
+ instanceId
+ );
+ if (publishablePageIds.has(navigate.pageId) === false) {
+ continue;
+ }
features.set("Resource variable", {
- navigate: findPageAndSelectorByInstanceId(
- pages,
- instances,
- instanceId
- ),
+ navigate,
});
}
}
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 160c13134b..3c2bcd6d9f 100644
--- a/apps/builder/app/builder/features/settings-panel/controls/url.tsx
+++ b/apps/builder/app/builder/features/settings-panel/controls/url.tsx
@@ -35,6 +35,7 @@ import {
} from "~/builder/shared/binding-popover";
import { validatePrimitiveValue } from "@webstudio-is/project-build/runtime";
import { useDraftValue } from "~/builder/shared/use-draft-value";
+import { getPageDisplayName } from "~/builder/features/pages/page-utils";
import {
type ControlProps,
VerticalLayout,
@@ -384,7 +385,7 @@ const BasePage = ({ prop, onChange }: BaseControlProps) => {
{pages.map((page) => {
return (
<SelectItem key={page.id} value={page.id}>
- {page.name}
+ {getPageDisplayName(page)}
</SelectItem>
);
})}
diff --git a/apps/builder/app/builder/shared/topbar.tsx b/apps/builder/app/builder/shared/topbar.tsx
index fe5cc56020..71e4edb2ae 100644
--- a/apps/builder/app/builder/shared/topbar.tsx
+++ b/apps/builder/app/builder/shared/topbar.tsx
@@ -38,6 +38,7 @@ import { BuilderModeDropDown } from "~/builder/features/builder-mode";
import { SafeModeButton } from "~/builder/features/safe-mode";
import { NotificationPopover } from "~/shared/notifications/notification-popover";
import { $notifications } from "~/shared/notifications/subscription";
+import { getPageDisplayName } from "~/builder/features/pages/page-utils";
const topbarContainerStyle = css({
position: "relative",
@@ -138,7 +139,7 @@ const PagesButton = () => {
tabIndex={0}
>
<Text truncate css={{ maxWidth: theme.spacing[24] }}>
- {page.name}
+ {isPage(page) ? getPageDisplayName(page) : page.name}
</Text>
</ToolbarButton>
</Tooltip>
diff --git a/apps/builder/e2e/tests/pages-actions.[shard-3].e2e.ts b/apps/builder/e2e/tests/pages-actions.[shard-3].e2e.ts
index 50946d76aa..d4afca249a 100644
--- a/apps/builder/e2e/tests/pages-actions.[shard-3].e2e.ts
+++ b/apps/builder/e2e/tests/pages-actions.[shard-3].e2e.ts
@@ -155,7 +155,12 @@ const selectHeaderAction = async ({
}: {
page: Page;
menuLabel: string;
- action: "Copy" | "Duplicate" | "Delete";
+ action:
+ | "Copy"
+ | "Duplicate"
+ | "Delete"
+ | "Mark as draft"
+ | "Stage for publish";
}) => {
await page.getByRole("button", { name: menuLabel }).click();
await page.getByRole("menuitem", { name: action }).click();
@@ -210,7 +215,7 @@ test.beforeAll(async () => {
});
});
-test("Builder can copy, duplicate, and delete a page from the header menu", async () => {
+test("Builder can draft, stage, copy, duplicate, and delete a page from the header menu", async () => {
const { page, close } = await newIsolatedPage();
const pageName = "Actions Menu Page";
const renamedPageName = "Renamed Actions Menu Page";
@@ -262,6 +267,33 @@ test("Builder can copy, duplicate, and delete a page from the header menu", asyn
await waitForPageRow({ page, pageName: renamedPageName });
await expectPageRowHidden({ page, pageName });
+ const draftSave = waitForChangeToBeSaved({ page });
+ await selectHeaderAction({
+ page,
+ menuLabel: "Page actions",
+ action: "Mark as draft",
+ });
+ await draftSave;
+ await waitForPageRow({ page, pageName: `[Draft] ${renamedPageName}` });
+
+ await openPageSettings({
+ page,
+ pageName: `[Draft] ${renamedPageName}`,
+ });
+ await page
+ .getByText(
+ "Stage this page for publish before setting it as the home page"
+ )
+ .waitFor();
+ const stageSave = waitForChangeToBeSaved({ page });
+ await selectHeaderAction({
+ page,
+ menuLabel: "Page actions",
+ action: "Stage for publish",
+ });
+ await stageSave;
+ await waitForPageRow({ page, pageName: renamedPageName });
+
await openPageSettings({ page, pageName: renamedPageName });
await selectHeaderAction({
page,
diff --git a/fixtures/react-router-cloudflare/.webstudio/data.json b/fixtures/react-router-cloudflare/.webstudio/data.json
index a3a39cdc2e..ae78057340 100644
--- a/fixtures/react-router-cloudflare/.webstudio/data.json
+++ b/fixtures/react-router-cloudflare/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "f565d527-32e7-4731-bc71-aca9e9574587",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/react-router-docker/.webstudio/data.json b/fixtures/react-router-docker/.webstudio/data.json
index a3a39cdc2e..ae78057340 100644
--- a/fixtures/react-router-docker/.webstudio/data.json
+++ b/fixtures/react-router-docker/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "f565d527-32e7-4731-bc71-aca9e9574587",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/react-router-netlify/.webstudio/data.json b/fixtures/react-router-netlify/.webstudio/data.json
index a3a39cdc2e..ae78057340 100644
--- a/fixtures/react-router-netlify/.webstudio/data.json
+++ b/fixtures/react-router-netlify/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "f565d527-32e7-4731-bc71-aca9e9574587",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/react-router-vercel/.webstudio/data.json b/fixtures/react-router-vercel/.webstudio/data.json
index a3a39cdc2e..ae78057340 100644
--- a/fixtures/react-router-vercel/.webstudio/data.json
+++ b/fixtures/react-router-vercel/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "f565d527-32e7-4731-bc71-aca9e9574587",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/ssg-cloudflare-pages/.webstudio/data.json b/fixtures/ssg-cloudflare-pages/.webstudio/data.json
index 929ce962ee..766549deda 100644
--- a/fixtures/ssg-cloudflare-pages/.webstudio/data.json
+++ b/fixtures/ssg-cloudflare-pages/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "a2e8de30-03d5-4514-a3a6-406b3266a3af",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/ssg-netlify-by-project-id/.webstudio/data.json b/fixtures/ssg-netlify-by-project-id/.webstudio/data.json
index 47a0d4bba5..f4b42f6af6 100644
--- a/fixtures/ssg-netlify-by-project-id/.webstudio/data.json
+++ b/fixtures/ssg-netlify-by-project-id/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "8f0fdff2-e76b-4f86-9203-ea7df5f1143c",
"projectId": "8a7358b1-7de3-459d-b7b1-56dddfb6ce1e",
diff --git a/fixtures/webstudio-cloudflare-template/.webstudio/data.json b/fixtures/webstudio-cloudflare-template/.webstudio/data.json
index 929ce962ee..766549deda 100644
--- a/fixtures/webstudio-cloudflare-template/.webstudio/data.json
+++ b/fixtures/webstudio-cloudflare-template/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "a2e8de30-03d5-4514-a3a6-406b3266a3af",
"projectId": "d845c167-ea07-4875-b08d-83e97c09dcce",
diff --git a/fixtures/webstudio-features/.webstudio/data.json b/fixtures/webstudio-features/.webstudio/data.json
index e426b92eaa..f0a10094eb 100644
--- a/fixtures/webstudio-features/.webstudio/data.json
+++ b/fixtures/webstudio-features/.webstudio/data.json
@@ -1,5 +1,5 @@
{
- "bundleVersion": "bundle-u14gh7",
+ "bundleVersion": "bundle-19n82kd",
"build": {
"id": "1b66ee06-8ea5-4420-9a0e-e0d3a67aca32",
"projectId": "cddc1d44-af37-4cb6-a430-d300cf6f932d",
diff --git a/packages/cli/src/docs.generated.ts b/packages/cli/src/docs.generated.ts
index cf845fa928..44d6abeef3 100644
--- a/packages/cli/src/docs.generated.ts
+++ b/packages/cli/src/docs.generated.ts
@@ -6,7 +6,7 @@ export const cliDocs = {
"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 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',
+ '# 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- Draft a page with `update-page` and `{"pageId":"page-id","values":{"isDraft":true}}`. It remains editable and previewable but is omitted from every publish target, including staging, and from sitemap output.\n- Stage a draft page for a future publish with `{"pageId":"page-id","values":{"isDraft":false}}`. This clears draft state but does not deploy the site. The home page and `/*` catch-all page cannot be drafts.\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":
@@ -78,6 +78,8 @@ export const cliDocSections = {
'Expression binding example: {"bindings":[{"instanceId":"link-id","name":"href","binding":{"type":"expression","value":"currentPost.url"}}]}.',
'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".',
'Page metadata update example: use update-page with {"pageId":"page-id","values":{"title":"Pricing | Acme","meta":{"description":"Plans for teams"}}}.',
+ 'Draft a page with update-page and {"pageId":"page-id","values":{"isDraft":true}}. It remains editable and previewable but is omitted from every publish target, including staging, and from sitemap output.',
+ 'Stage a draft page for a future publish with {"pageId":"page-id","values":{"isDraft":false}}. This clears draft state but does not deploy the site. The home page and /* catch-all page cannot be drafts.',
'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" }.',
'Resource update example: use update-resource with {"resourceId":"resource-id","values":{"url":"https://api.example.com/items"}}.',
"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.",
diff --git a/packages/cli/src/docs/manual-llm.md b/packages/cli/src/docs/manual-llm.md
index d42638f968..3845be40e2 100644
--- a/packages/cli/src/docs/manual-llm.md
+++ b/packages/cli/src/docs/manual-llm.md
@@ -420,6 +420,8 @@ Before authoring unfamiliar expressions, read `webstudio://project/expressions`
- Expression binding example: `{"bindings":[{"instanceId":"link-id","name":"href","binding":{"type":"expression","value":"currentPost.url"}}]}`.
- 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"`.
- Page metadata update example: use `update-page` with `{"pageId":"page-id","values":{"title":"Pricing | Acme","meta":{"description":"Plans for teams"}}}`.
+- Draft a page with `update-page` and `{"pageId":"page-id","values":{"isDraft":true}}`. It remains editable and previewable but is omitted from every publish target, including staging, and from sitemap output.
+- Stage a draft page for a future publish with `{"pageId":"page-id","values":{"isDraft":false}}`. This clears draft state but does not deploy the site. The home page and `/*` catch-all page cannot be drafts.
- 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" }`.
- Resource update example: use `update-resource` with `{"resourceId":"resource-id","values":{"url":"https://api.example.com/items"}}`.
- 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.
diff --git a/packages/cli/src/prebuild.test.ts b/packages/cli/src/prebuild.test.ts
index ab455eb40a..e26c413f93 100644
--- a/packages/cli/src/prebuild.test.ts
+++ b/packages/cli/src/prebuild.test.ts
@@ -75,6 +75,7 @@ const createSiteData = (
path: string;
rootInstanceId: string;
meta: Record<string, unknown>;
+ isDraft?: boolean;
}>;
instances?: Array<
[
@@ -286,6 +287,55 @@ describe("generateRedirectsModule", () => {
});
describe("prebuild", () => {
+ test("excludes draft pages from published output", async () => {
+ await writeSiteData(
+ createSiteData({
+ pages: [
+ {
+ id: "home",
+ name: "Home",
+ title: "Home",
+ path: "",
+ rootInstanceId: "root",
+ meta: {},
+ },
+ {
+ id: "published",
+ name: "Published",
+ title: "Published",
+ path: "/published",
+ rootInstanceId: "root",
+ meta: {},
+ },
+ {
+ id: "draft",
+ name: "Draft",
+ title: "Draft",
+ path: "/draft",
+ rootInstanceId: "root",
+ meta: {},
+ isDraft: true,
+ },
+ ],
+ })
+ );
+
+ await prebuild({ assets: false, template: ["react-router"] });
+
+ await expect(
+ readFile("app/routes/[published]._index.tsx", "utf8")
+ ).resolves.toContain("../__generated__/[published]._index");
+ await expect(
+ readFile("app/routes/[draft]._index.tsx", "utf8")
+ ).rejects.toThrow("ENOENT");
+ await expect(
+ readFile("app/__generated__/[draft]._index.tsx", "utf8")
+ ).rejects.toThrow("ENOENT");
+ await expect(
+ readFile("app/__generated__/$resources.sitemap.xml.ts", "utf8")
+ ).resolves.not.toContain('"path": "/draft"');
+ });
+
test("scaffolds generated files and stores redirects as data", async () => {
await mkdir("app/__generated__", { recursive: true });
await mkdir("app/routes", { recursive: true });
diff --git a/packages/cli/src/prebuild.ts b/packages/cli/src/prebuild.ts
index 404c5cb80d..dbd18b0826 100644
--- a/packages/cli/src/prebuild.ts
+++ b/packages/cli/src/prebuild.ts
@@ -28,7 +28,7 @@ import {
createScope,
findTreeInstanceIds,
getPagePath,
- getAllPages,
+ getPublishablePages,
generateResources,
generatePageMeta,
getStaticSiteMapXml,
@@ -351,7 +351,7 @@ export const prebuild = async (options: {
Object.entries(coreMetas)
);
const pages = migratePages(siteData.build.pages);
- const allPages = getAllPages(pages);
+ const publishablePages = getPublishablePages(pages);
await writeWsAuthResources(
generatedDir,
pages,
@@ -371,7 +371,7 @@ export const prebuild = async (options: {
source: "prebuild",
});
- for (const page of allPages) {
+ for (const page of publishablePages) {
const instanceMap = new Map(siteData.build.instances);
const pageInstanceSet = findTreeInstanceIds(
instanceMap,
@@ -427,7 +427,7 @@ export const prebuild = async (options: {
dataSources,
resources,
},
- pages: allPages,
+ pages: publishablePages,
page,
assets: siteData.assets,
};
@@ -514,7 +514,7 @@ export const prebuild = async (options: {
await createFileIfNotExists(join(generatedDir, "index.css"), cssText);
- for (const page of allPages) {
+ for (const page of publishablePages) {
const scope = createScope([
// manually maintained list of occupied identifiers
"useState",
diff --git a/packages/http-client/src/index.ts b/packages/http-client/src/index.ts
index b6fcd0c830..1d01938cc2 100644
--- a/packages/http-client/src/index.ts
+++ b/packages/http-client/src/index.ts
@@ -731,6 +731,7 @@ type PageFieldsInput = {
name?: string;
path?: string;
title?: string;
+ isDraft?: boolean;
parentFolderId?: string;
meta?: PageMetaInput;
};
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 d1ae67ef43..bc8622cc3a 100644
--- a/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts
+++ b/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts
@@ -48,6 +48,11 @@ export const runtimeOperationContractData = [
isHome: {
type: "boolean",
},
+ isDraft: {
+ description:
+ "True when the page is a draft. Missing or false means the page is publishable.",
+ type: "boolean",
+ },
},
required: [
"id",
@@ -139,6 +144,11 @@ export const runtimeOperationContractData = [
isHome: {
type: "boolean",
},
+ isDraft: {
+ description:
+ "True when the page is a draft. Missing or false means the page is publishable.",
+ type: "boolean",
+ },
meta: {
type: "object",
properties: {
@@ -287,6 +297,11 @@ export const runtimeOperationContractData = [
isHome: {
type: "boolean",
},
+ isDraft: {
+ description:
+ "True when the page is a draft. Missing or false means the page is publishable.",
+ type: "boolean",
+ },
meta: {
type: "object",
properties: {
@@ -452,6 +467,11 @@ export const runtimeOperationContractData = [
isHome: {
type: "boolean",
},
+ isDraft: {
+ description:
+ "True when the page is a draft. Missing or false means the page is publishable.",
+ type: "boolean",
+ },
meta: {
type: "object",
properties: {
@@ -763,6 +783,11 @@ export const runtimeOperationContractData = [
'Plain fixed text is accepted, for example "Plans for teams". For computed values, pass one Webstudio JavaScript expression such as `pageTitle ?? "Plans for teams"`. Read webstudio://project/expressions for syntax and scope rules.',
type: "string",
},
+ isDraft: {
+ type: "boolean",
+ description:
+ "Set true to mark the page as draft. Draft pages remain editable and previewable in Builder but are omitted from every publish target, including staging, and from sitemap output. Set false to stage the page for a future publish; this does not deploy the site. The home page and /* catch-all page cannot be drafts.",
+ },
parentFolderId: {
type: "string",
},
@@ -2943,6 +2968,11 @@ export const runtimeOperationContractData = [
isHome: {
type: "boolean",
},
+ isDraft: {
+ description:
+ "True when the page is a draft. Missing or false means the page is publishable.",
+ type: "boolean",
+ },
},
required: [
"id",
diff --git a/packages/project-build/src/contracts/builder-runtime.test.ts b/packages/project-build/src/contracts/builder-runtime.test.ts
index e05385c89d..d596cda15f 100644
--- a/packages/project-build/src/contracts/builder-runtime.test.ts
+++ b/packages/project-build/src/contracts/builder-runtime.test.ts
@@ -4,7 +4,12 @@ import {
runtimeOperationContracts,
type RuntimeOperationId,
} from "./builder-runtime";
-import { pageExpressionFieldHint, pagePathFieldHint } from "../runtime/pages";
+import {
+ pageDraftFieldHint,
+ pageExpressionFieldHint,
+ pagePathFieldHint,
+} from "../runtime/pages";
+import { pageDraftOutputHint } from "../runtime/output-schemas";
import { getBuilderRuntimeOperationInputSchema } from "../runtime/registry";
const knownOperationId: RuntimeOperationId = "pages.list";
@@ -188,6 +193,28 @@ describe("builder runtime operation contracts", () => {
});
});
+ test("explains draft-page behavior in generated MCP contracts", () => {
+ const updatePageInputSchema = getContract("pages.update").inputSchema;
+ const updatePageProperties = getSchemaProperties(updatePageInputSchema);
+ const updatePageValueProperties = getSchemaProperties(
+ updatePageProperties.values
+ );
+
+ expect(updatePageValueProperties.isDraft).toMatchObject({
+ type: "boolean",
+ description: pageDraftFieldHint,
+ });
+
+ const listPagesOutputSchema = getContract("pages.list").outputSchema;
+ const listPagesProperties = getSchemaProperties(listPagesOutputSchema);
+ const listPageItems = getSchemaItems(listPagesProperties.pages);
+ const listPageProperties = getSchemaProperties(listPageItems);
+ expect(listPageProperties.isDraft).toMatchObject({
+ type: "boolean",
+ description: pageDraftOutputHint,
+ });
+ });
+
test("loads full tree namespaces for mutations that can remove referenced records", () => {
const namespaces = [
"pages",
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 2a17d24156..6aa23736f1 100644
--- a/packages/project-build/src/runtime/content-mode-permissions.test.ts
+++ b/packages/project-build/src/runtime/content-mode-permissions.test.ts
@@ -2602,6 +2602,21 @@ describe("content mode permissions", () => {
success: false,
error: "Page patch is not editable in content mode.",
});
+ expect(
+ validateContentModeTransaction({
+ capabilities,
+ transaction: transaction("pages", [
+ {
+ op: "add",
+ path: ["pages", "page-1", "isDraft"],
+ value: true,
+ },
+ ]),
+ })
+ ).toEqual({
+ success: false,
+ error: "Page patch is not editable in content mode.",
+ });
expect(
validateContentModeTransaction({
capabilities,
diff --git a/packages/project-build/src/runtime/output-schemas.ts b/packages/project-build/src/runtime/output-schemas.ts
index 5bc85ba69e..5f6fbe6357 100644
--- a/packages/project-build/src/runtime/output-schemas.ts
+++ b/packages/project-build/src/runtime/output-schemas.ts
@@ -34,6 +34,9 @@ const patchChange = z.object({
patches: z.array(builderPatchSchema),
});
+export const pageDraftOutputHint =
+ "True when the page is a draft. Missing or false means the page is publishable.";
+
export const createRuntimeMutationExecutionSchema = <
Result extends z.ZodTypeAny,
>(
@@ -56,6 +59,7 @@ const pageSummary = looseObject({
rootInstanceId: id,
parentFolderId: id.optional(),
isHome: z.boolean(),
+ isDraft: z.boolean().optional().describe(pageDraftOutputHint),
});
const pageDetails = pageSummary.extend({
meta: looseObject({
diff --git a/packages/project-build/src/runtime/page-copy.test.tsx b/packages/project-build/src/runtime/page-copy.test.tsx
index eb8c33cd96..5c05bc48cf 100644
--- a/packages/project-build/src/runtime/page-copy.test.tsx
+++ b/packages/project-build/src/runtime/page-copy.test.tsx
@@ -334,6 +334,7 @@ describe("insert page copy", () => {
title: `"Title"`,
meta: {},
rootInstanceId: "bodyId",
+ isDraft: true,
},
],
folders: [
@@ -370,6 +371,7 @@ describe("insert page copy", () => {
id: result.result.pageId,
name: "Copy",
path: "/copy",
+ isDraft: true,
}),
},
{
diff --git a/packages/project-build/src/runtime/pages.test.ts b/packages/project-build/src/runtime/pages.test.ts
index 185e2c84f7..b72e1d11d4 100644
--- a/packages/project-build/src/runtime/pages.test.ts
+++ b/packages/project-build/src/runtime/pages.test.ts
@@ -1618,6 +1618,15 @@ describe("isPathAvailable", () => {
).toBe(false);
});
+ test("draft pages continue to reserve their path", () => {
+ const page = pages.pages.get("page2")!;
+ page.isDraft = true;
+ expect(
+ isPathAvailable({ pages, path: "/page", parentFolderId: "folder2" })
+ ).toBe(false);
+ delete page.isDraft;
+ });
+
test("/folder2/page1 new page", () => {
expect(
isPathAvailable({ pages, path: "/page1", parentFolderId: "folder2" })
@@ -1834,6 +1843,62 @@ describe("createPage", () => {
});
describe("updatePage", () => {
+ test("sets and clears draft", () => {
+ const pages = createPages();
+
+ expect(
+ updatePage({ pages }, { pageId: "page", values: { isDraft: true } })
+ .payload
+ ).toEqual([
+ {
+ namespace: "pages",
+ patches: [
+ {
+ op: "add",
+ path: ["pages", "page", "isDraft"],
+ value: true,
+ },
+ ],
+ },
+ ]);
+
+ pages.pages.get("page")!.isDraft = true;
+ expect(
+ updatePage({ pages }, { pageId: "page", values: { isDraft: true } })
+ .payload
+ ).toEqual([]);
+ expect(
+ updatePage({ pages }, { pageId: "page", values: { isDraft: false } })
+ .payload
+ ).toEqual([
+ {
+ namespace: "pages",
+ patches: [{ op: "remove", path: ["pages", "page", "isDraft"] }],
+ },
+ ]);
+ });
+
+ test("rejects drafting home and catch-all pages", () => {
+ const pages = createPages();
+ expect(() =>
+ updatePage({ pages }, { pageId: "home", values: { isDraft: true } })
+ ).toThrow("Home page can't be draft");
+
+ pages.pages.get("page")!.path = "/*";
+ expect(() =>
+ updatePage({ pages }, { pageId: "page", values: { isDraft: true } })
+ ).toThrow("Catch-all 404 page can't be draft");
+ });
+
+ test("rejects changing a draft page to the catch-all path", () => {
+ const pages = createPages();
+ pages.pages.get("page")!.isDraft = true;
+
+ expect(() =>
+ updatePage({ pages }, { pageId: "page", values: { path: "/*" } })
+ ).toThrow("Catch-all 404 page can't be draft");
+ });
+
test("accepts fixed page metadata text and stores expression string literals", () => {
const pages = createPages();
@@ -2183,6 +2248,15 @@ describe("savePagePathInHistory", () => {
});
describe("setHomePage", () => {
+ test("rejects setting a draft page as home", () => {
+ const pages = createPages();
+ pages.pages.get("page")!.isDraft = true;
+
+ expect(() => setHomePage({ pages }, { pageId: "page" })).toThrow(
+ "Home page can't be draft"
+ );
+ });
+
test("sets home page and keeps a single root folder reference", () => {
const pages = createPages();
const rootFolder = pages.folders.get(ROOT_FOLDER_ID);
diff --git a/packages/project-build/src/runtime/pages.ts b/packages/project-build/src/runtime/pages.ts
index 08619388a2..8ba9c5a243 100644
--- a/packages/project-build/src/runtime/pages.ts
+++ b/packages/project-build/src/runtime/pages.ts
@@ -6,6 +6,7 @@ import {
getAllPages,
getHomePage,
getFolderById,
+ getPageDraftabilityError,
getPagePath,
ROOT_FOLDER_ID,
folder as sdkFolder,
@@ -20,6 +21,7 @@ import {
documentTypes,
type PageAuth,
type Pages,
+ isPageDraft,
} from "@webstudio-is/sdk";
import { serializePages } from "@webstudio-is/project-migrations/pages";
import * as bcp47 from "bcp-47";
@@ -63,6 +65,7 @@ export type SerializedPageSummary = {
rootInstanceId: Page["rootInstanceId"];
parentFolderId: Folder["id"] | undefined;
isHome: boolean;
+ isDraft?: boolean;
};
export type SerializedPageDetails = SerializedPageSummary & {
@@ -193,6 +196,7 @@ export const serializePageSummary = (
rootInstanceId: page.rootInstanceId,
parentFolderId: findParentFolderId(pages.folders, page.id),
isHome: page.id === pages.homePageId,
+ ...(isPageDraft(page) ? { isDraft: true } : {}),
});
export const serializePageDetails = (
@@ -841,10 +845,14 @@ const pageExpressionStringInput = z
export const pagePathFieldHint =
'Plain page path. For a new non-home page, start with "/", for example "/pricing". The home page path is the empty string ""; do not use an empty path when creating a new page.';
+export const pageDraftFieldHint =
+ "Set true to mark the page as draft. Draft pages remain editable and previewable in Builder but are omitted from every publish target, including staging, and from sitemap output. Set false to stage the page for a future publish; this does not deploy the site. The home page and /* catch-all page cannot be drafts.";
+
const pageCreatePathInput = pagePath.describe(pagePathFieldHint);
const pageUpdatePathInput = z
.union([homePagePath, pagePath])
.describe(pagePathFieldHint);
+const pageDraftInput = z.boolean().describe(pageDraftFieldHint);
export const normalizePageMetaValue = <Name extends keyof PageMeta>(
name: Name,
@@ -874,6 +882,7 @@ type PageFieldsPatchInput = Partial<{
name: Page["name"];
path: Page["path"];
title: Page["title"];
+ isDraft: boolean;
parentFolderId: string;
meta: PageMetaPatchInput;
}>;
@@ -1059,6 +1068,7 @@ export const pageFieldsInput = z.object({
name: z.string().min(1).optional(),
path: pageUpdatePathInput.optional(),
title: pageExpressionStringInput.optional(),
+ isDraft: pageDraftInput.optional(),
parentFolderId: z.string().optional(),
meta: pageMetaInputBase.optional(),
});
@@ -1671,6 +1681,15 @@ export const createPageUpdatePatches = ({
if (input.title !== undefined) {
replace(["pages", page.id, "title"], input.title);
}
+ if (input.isDraft === true && isPageDraft(page) === false) {
+ patches.push({
+ op: page.isDraft === undefined ? "add" : "replace",
+ path: ["pages", page.id, "isDraft"],
+ value: true,
+ });
+ } else if (input.isDraft === false && page.isDraft !== undefined) {
+ patches.push({ op: "remove", path: ["pages", page.id, "isDraft"] });
+ }
if (input.meta !== undefined) {
for (const [name, value] of Object.entries(
pageMetaToPatchValue(input.meta)
@@ -1802,6 +1821,16 @@ export const updatePage = (
return throwBuilderRuntimeError("NOT_FOUND", "Page not found");
}
const normalizedValues = normalizePageFieldsExpressionInputs(input.values);
+ const nextPath = normalizedValues.path ?? page.path;
+ const nextIsDraft = normalizedValues.isDraft ?? isPageDraft(page);
+ const draftabilityError = getPageDraftabilityError({
+ pageId: page.id,
+ pagePath: nextPath,
+ homePageId: pages.homePageId,
+ });
+ if (nextIsDraft && draftabilityError !== undefined) {
+ return throwBuilderRuntimeError("BAD_REQUEST", draftabilityError);
+ }
const expressionIssues =
collectPageExpressionValidationIssues(normalizedValues);
if (expressionIssues.length > 0) {
@@ -2176,6 +2205,14 @@ export const setHomePage = (
if (newHomePage === undefined) {
return throwBuilderRuntimeError("NOT_FOUND", "Page not found");
}
+ const draftabilityError = getPageDraftabilityError({
+ pageId: newHomePage.id,
+ pagePath: newHomePage.path,
+ homePageId: newHomePage.id,
+ });
+ if (isPageDraft(newHomePage) && draftabilityError !== undefined) {
+ return throwBuilderRuntimeError("BAD_REQUEST", draftabilityError);
+ }
if (rootFolder === undefined) {
return throwBuilderRuntimeError("NOT_FOUND", "Root folder not found");
}
diff --git a/packages/project-migrations/src/pages.test.ts b/packages/project-migrations/src/pages.test.ts
index 4d094d745e..ca8a8d1a1d 100644
--- a/packages/project-migrations/src/pages.test.ts
+++ b/packages/project-migrations/src/pages.test.ts
@@ -2,7 +2,7 @@ import { expect, test } from "vitest";
import type { Pages } from "@webstudio-is/sdk";
import { migratePages, serializePages } from "./pages";
-test("keeps current pages shape unchanged when page templates exist", () => {
+test("keeps current pages shape and draft flags unchanged", () => {
const pages: Pages = {
homePageId: "home",
rootFolderId: "root",
@@ -18,6 +18,18 @@ test("keeps current pages shape unchanged when page templates exist", () => {
rootInstanceId: "homeRoot",
},
],
+ [
+ "draft",
+ {
+ id: "draft",
+ name: "Draft",
+ path: "/draft",
+ title: `"Draft"`,
+ meta: {},
+ rootInstanceId: "draftRoot",
+ isDraft: true,
+ },
+ ],
]),
pageTemplates: new Map(),
folders: new Map([
@@ -27,13 +39,18 @@ test("keeps current pages shape unchanged when page templates exist", () => {
id: "root",
name: "Root",
slug: "",
- children: ["home"],
+ children: ["home", "draft"],
},
],
]),
};
expect(migratePages(pages)).toBe(pages);
+ const serialized = serializePages(pages);
+ expect(serialized.pages.find((page) => page.id === "draft")?.isDraft).toBe(
+ true
+ );
+ expect(migratePages(serialized).pages.get("draft")?.isDraft).toBe(true);
});
test("adds missing page templates map to current pages shape", () => {
diff --git a/packages/sdk/src/page-utils.test.ts b/packages/sdk/src/page-utils.test.ts
index 1a4af097de..0dc39b6c48 100644
--- a/packages/sdk/src/page-utils.test.ts
+++ b/packages/sdk/src/page-utils.test.ts
@@ -1,8 +1,9 @@
import { describe, expect, test } from "vitest";
-import type { Pages } from "./schema/pages";
+import type { Page, Pages } from "./schema/pages";
import {
findPageByIdOrPath,
findParentFolderByChildId,
+ getPublishablePages,
getPagePath,
getStaticSiteMapXml,
isPage,
@@ -235,4 +236,27 @@ describe("getStaticSiteMapXml", () => {
},
]);
});
+
+ test("excludes draft pages", () => {
+ const pagesWithDraft: Pages = {
+ ...pages,
+ pages: new Map<string, Page>(pages.pages)
+ .set("home", { ...pages.pages.get("home")!, isDraft: false })
+ .set("page-1", {
+ ...pages.pages.get("page-1")!,
+ isDraft: true,
+ }),
+ };
+
+ expect(getPublishablePages(pagesWithDraft).map((page) => page.id)).toEqual([
+ "home",
+ ]);
+ expect(getStaticSiteMapXml(pagesWithDraft, "2026-04-30")).not.toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: "/folder-1/folder-1-1/folder-1-1-1/page-1",
+ }),
+ ])
+ );
+ });
});
diff --git a/packages/sdk/src/page-utils.ts b/packages/sdk/src/page-utils.ts
index a2c0c631c4..fd24b9c5e3 100644
--- a/packages/sdk/src/page-utils.ts
+++ b/packages/sdk/src/page-utils.ts
@@ -1,5 +1,6 @@
import { executeExpression } from "./expression";
import {
+ isPageDraft,
type Folder,
type Page,
type PageTemplate,
@@ -48,6 +49,9 @@ export const getAllPages = (pages: Pages): Page[] => {
return Array.from(pages.pages.values());
};
+export const getPublishablePages = (pages: Pages): Page[] =>
+ getAllPages(pages).filter((page) => isPageDraft(page) === false);
+
export const getAllFolders = (pages: Pages): Folder[] => {
return Array.from(pages.folders.values());
};
@@ -149,7 +153,7 @@ export const getPagePath = (id: Folder["id"] | Page["id"], pages: Pages) => {
};
export const getStaticSiteMapXml = (pages: Pages, updatedAt: string) => {
- const allPages = getAllPages(pages);
+ const allPages = getPublishablePages(pages);
return (
allPages
.filter((page) => (page.meta.documentType ?? "html") === "html")
diff --git a/packages/sdk/src/schema/pages.test.ts b/packages/sdk/src/schema/pages.test.ts
index 0a6ed9ec97..82038a0896 100644
--- a/packages/sdk/src/schema/pages.test.ts
+++ b/packages/sdk/src/schema/pages.test.ts
@@ -8,6 +8,7 @@ import {
projectMeta,
projectNewRedirectPath,
} from "./pages";
+import type { Page } from "./pages";
const validPages = {
homePageId: "home",
@@ -72,7 +73,7 @@ test("validates home page path is empty", () => {
expect(
pages.safeParse({
...validPages,
- pages: new Map(validPages.pages).set("home", {
+ pages: new Map<string, Page>(validPages.pages).set("home", {
...validPages.pages.get("home")!,
path: "/home",
}),
@@ -85,6 +86,49 @@ test("validates home page path is empty", () => {
]);
});
+test("validates home page is not draft", () => {
+ expect(
+ pages.safeParse({
+ ...validPages,
+ pages: new Map<string, Page>(validPages.pages).set("home", {
+ ...validPages.pages.get("home")!,
+ isDraft: true,
+ }),
+ }).error?.issues
+ ).toEqual([
+ expect.objectContaining({
+ path: ["pages", "home", "isDraft"],
+ message: "Home page can't be draft",
+ }),
+ ]);
+});
+
+test("validates catch-all 404 page is not draft", () => {
+ expect(
+ pages.safeParse({
+ ...validPages,
+ pages: new Map<string, Page>(validPages.pages).set("not-found", {
+ id: "not-found",
+ name: "404",
+ path: "/*",
+ title: `"Page not found"`,
+ meta: { status: "404" },
+ rootInstanceId: "notFoundRoot",
+ isDraft: true,
+ }),
+ folders: new Map(validPages.folders).set("root", {
+ ...validPages.folders.get("root")!,
+ children: ["home", "not-found"],
+ }),
+ }).error?.issues
+ ).toEqual([
+ expect.objectContaining({
+ path: ["pages", "not-found", "isDraft"],
+ message: "Catch-all 404 page can't be draft",
+ }),
+ ]);
+});
+
test("validates non-home page path is not empty", () => {
expect(
pages.safeParse({
diff --git a/packages/sdk/src/schema/pages.ts b/packages/sdk/src/schema/pages.ts
index 90f70b6669..e8135c9904 100644
--- a/packages/sdk/src/schema/pages.ts
+++ b/packages/sdk/src/schema/pages.ts
@@ -197,6 +197,7 @@ export const pagePath = defaultPagePath.refine(
export const page = z.object({
...commonPageFields,
path: z.union([homePagePath, pagePath]),
+ isDraft: z.boolean().optional(),
});
export const pageTemplate = z.object({
@@ -250,6 +251,26 @@ export type CompilerSettings = z.infer<typeof compilerSettings>;
export type Page = z.infer<typeof page>;
+export const isPageDraft = (page: Pick<Page, "isDraft">) =>
+ page.isDraft === true;
+
+export const getPageDraftabilityError = ({
+ pageId,
+ pagePath,
+ homePageId,
+}: {
+ pageId: Page["id"];
+ pagePath: Page["path"];
+ homePageId: Page["id"];
+}) => {
+ if (pageId === homePageId) {
+ return "Home page can't be draft";
+ }
+ if (pagePath === "/*") {
+ return "Catch-all 404 page can't be draft";
+ }
+};
+
export const pages = z
.object({
meta: projectMeta.optional(),
@@ -302,6 +323,18 @@ export const pages = z
message: "Page path can't be empty",
});
}
+ const draftabilityError = getPageDraftabilityError({
+ pageId,
+ pagePath: page.path,
+ homePageId: pages.homePageId,
+ });
+ if (isPageDraft(page) && draftabilityError !== undefined) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ["pages", pageId, "isDraft"],
+ message: draftabilityError,
+ });
+ }
}
for (const [templateId, template] of pages.pageTemplates ?? []) {
if (template.id !== templateId) {