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.

fix: Validate expression-backed API inputs (#5854)

Oleg Isonen371a6d6b8adf
diff --git a/packages/cli/src/commands/man.test.ts b/packages/cli/src/commands/man.test.ts
index 8b0292377e..48b3408693 100644
--- a/packages/cli/src/commands/man.test.ts
+++ b/packages/cli/src/commands/man.test.ts
@@ -267,6 +267,17 @@ test("prints llm manual with discovery rules", () => {
expect(output).toContain("## LLM Implementation Process");
expect(output).toContain("## Visual Design Workflow");
expect(output).toContain("## Generated Files Guardrails");
+ expect(output).toContain("## Values vs Bindings");
+ expect(output).toContain(
+ "Use `bind-props` only when the prop must stay dynamic"
+ );
+ expect(output).toContain('"\\"Pricing | Acme\\""');
+ expect(output).toContain(
+ '{"pageId":"page-id","values":{"title":"\\"Pricing | Acme\\"","meta":{"description":"\\"Plans for teams\\""}}}'
+ );
+ expect(output).toContain(
+ '{"resourceId":"resource-id","values":{"url":"\\"https://api.example.com/items\\""}}'
+ );
expect(output).toContain(
"Make edits through Webstudio semantic commands/MCP tools"
);
@@ -315,12 +326,27 @@ test("prints llm manual as json with implementation process", () => {
expect.stringContaining("Generated files are build artifacts"),
])
);
+ expect(output.valuesVsBindings).toEqual(
+ expect.arrayContaining([
+ expect.stringContaining("Use direct value tools for fixed content"),
+ expect.stringContaining(
+ "Use bind-props only when the prop must stay dynamic"
+ ),
+ expect.stringContaining("Page metadata fields"),
+ ])
+ );
expect(output.rules).toContain(
"Pass --json only to commands whose help/schema documents it. Do not add --json to top-level commands such as sync unless supported."
);
expect(output.rules).toContain(
"For visual/design work, verify the rendered result with vision before finishing."
);
+ expect(output.rules).toContain(
+ "Use direct values for static strings and bindings only for dynamic expressions/resources/actions."
+ );
+ expect(output.rules).toContain(
+ "For expression-backed fields that need fixed text, encode the fixed text as a quoted JavaScript string literal expression."
+ );
expect(output.visionVerificationLoop).toContain(
getVisionVerificationLoop({ includeDiff: true })[1]
);
@@ -402,6 +428,29 @@ test("prints mcp manual as json", () => {
text: "Launch faster",
},
]);
+ expect(output.mcpArgumentExamples["update-props"]).toEqual([
+ {
+ updates: [
+ {
+ instanceId: "button-id",
+ name: "aria-label",
+ type: "string",
+ value: "Open menu",
+ },
+ ],
+ },
+ ]);
+ expect(output.mcpArgumentExamples["bind-props"]).toEqual([
+ {
+ bindings: [
+ {
+ instanceId: "link-id",
+ name: "href",
+ binding: { type: "expression", value: "currentPost.url" },
+ },
+ ],
+ },
+ ]);
});
test("prints available topics for unknown manual topic", () => {
diff --git a/packages/cli/src/docs.generated.ts b/packages/cli/src/docs.generated.ts
index 08f7b26afc..1be56da4d0 100644
--- a/packages/cli/src/docs.generated.ts
+++ b/packages/cli/src/docs.generated.ts
@@ -2,11 +2,11 @@
// Edit markdown files in src/docs instead.
export const cliDocs = {
"api-use-cases":
- '# CLI API Use Cases\n\n## Link/configure one project\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n\nNotes:\n\n- Writes local project id and global origin/token config.\n\n## Import synced project bundle into another project\n\nCommands:\n\n- webstudio sync\n- webstudio import --to <destination-share-link>\n- MCP tool: import {"to":"<destination-share-link>"}\n\nNotes:\n\n- Imports local `.webstudio/data.json` into the destination project.\n- Destination share link must allow build/import access.\n- Use `--skip-assets` only when asset rows and files should not be imported.\n\n## Identify current token\n\nCommands:\n\n- MCP tool: whoami {}\n\n## Check token permissions\n\nCommands:\n\n- webstudio permissions --json\n\n## Inspect project/build/version\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["pages","instances","styles"]}\n\n## Discover CLI/API capabilities\n\nCommands:\n\n- webstudio schema api --json\n- webstudio man api --json\n- webstudio man llm --json\n- webstudio man mcp --json\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"Create a pricing page"}\n- MCP tool: meta.get_more_tools {"brief":"update-styles"}\n\nNotes:\n\n- Use `tools/list` for machine-readable MCP tool schemas.\n- Use `resources/list` and `resources/read` for longer MCP resources such as `webstudio://project/tools` and `webstudio://project/guide`.\n\n## Inspect and refresh MCP session cache\n\nCommands:\n\n- MCP tool: status {}\n- MCP tool: refresh {"namespaces":["pages","instances","styles"]}\n- MCP tool: reset-session {}\n\nNotes:\n\n- Use status before a task to understand the cached ProjectSession state.\n- Use refresh when project data may have changed outside the current MCP session.\n- Use reset-session when local cached state is corrupt or incompatible.\n\n## Visually verify rendered work with AI vision\n\nCommands:\n\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: preview.status {}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot.diff {"baselinePath":"before.png","currentPath":"current.png","outputDir":".webstudio/screenshots"}\n- MCP tool: vision.install-ocr {"confirm":true}\n\nNotes:\n\n- Use this after page/content/style mutations and after generated project files are current so a vision-capable AI can see what was actually built.\n- Use waitForSelector when the rendered app has a reliable ready marker, waitUntil:"networkidle" for network-heavy pages, and waitForTimeout only for final visual settling.\n- For a fresh checkout, copied fixture, or newly generated app, run npm install or pnpm install in the generated project before preview.start or webstudio preview.\n- If preview fails with a missing generated-app command/package such as react-router or vite, install the generated app dependencies and retry.\n- When a baseline exists, use screenshot.diff to get changed regions, OCR textAnalysis, and diff artifact paths before deciding whether the result matches.\n- If screenshot.diff reports OCR unavailable and the user agrees to install it, call vision.install-ocr {"confirm":true}; otherwise continue with pixel diff and visual inspection.\n- Compare the PNG, OCR text evidence, and diff artifacts against the user\'s intent for layout, typography, colors, spacing, imagery, and responsive framing; then iterate with focused mutations.\n- Root CLI equivalent: webstudio preview --template ssg, then webstudio screenshot <url> --output current.png.\n\n## List pages\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n\n## Read page by id\n\nCommands:\n\n- MCP tool: get-page {"pageId":"<pageId>"}\n\n## Read page by path\n\nCommands:\n\n- MCP tool: get-page-by-path {"path":"/pricing"}\n\n## Create page\n\nCommands:\n\n- MCP tool: create-page {"name":"Pricing","path":"/pricing"}\n\n## Update page settings/metadata\n\nCommands:\n\n- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans","status":"200"}\n- MCP tool: update-page {"pageId":"<pageId>","auth":{"login":"<login>","password":"<password>"}}\n\n## Read project settings\n\nCommands:\n\n- MCP tool: get-project-settings {}\n\n## Update project settings\n\nCommands:\n\n- MCP tool: update-project-settings {"settings":"project-settings.json contents"}\n\n## List redirects\n\nCommands:\n\n- MCP tool: list-redirects {}\n\n## Create redirect\n\nCommands:\n\n- MCP tool: create-redirect {"oldPath":"/old","newPath":"/new","status":301}\n\n## Update redirect\n\nCommands:\n\n- MCP tool: update-redirect {"oldPath":"/old","newPath":"/newer","status":302}\n- MCP tool: update-redirect {"oldPath":"/old","status":null}\n\n## Delete redirect\n\nCommands:\n\n- MCP tool: delete-redirect {"oldPath":"/old"}\n\n## List breakpoints\n\nCommands:\n\n- MCP tool: list-breakpoints {}\n\n## Create breakpoint\n\nCommands:\n\n- MCP tool: create-breakpoint {"breakpointId":"tablet","label":"Tablet","maxWidth":991}\n\n## Update breakpoint\n\nCommands:\n\n- MCP tool: update-breakpoint {"breakpointId":"tablet","label":"Tablet","maxWidth":1023}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","condition":null,"minWidth":768}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","minWidth":null,"maxWidth":null,"condition":"(hover: hover)"}\n\n## Delete breakpoint\n\nCommands:\n\n- MCP tool: delete-breakpoint {"breakpointId":"tablet","confirm":true}\n\n## Duplicate page\n\nCommands:\n\n- MCP tool: duplicate-page {"pageId":"<pageId>","name":"Pricing Copy","path":"/pricing-copy"}\n\n## List page templates\n\nCommands:\n\n- MCP tool: list-page-templates {}\n\n## Create page from template\n\nCommands:\n\n- MCP tool: create-page-from-template {"templateId":"<templateId>","name":"Landing","path":"/landing"}\n\n## Delete page\n\nCommands:\n\n- MCP tool: delete-page {"pageId":"<pageId>"}\n\n## List folders\n\nCommands:\n\n- MCP tool: list-folders {"includePages":true}\n\n## Create folder\n\nCommands:\n\n- MCP tool: create-folder {"name":"Blog","slug":"blog"}\n\n## Update folder\n\nCommands:\n\n- MCP tool: update-folder {"folderId":"<folderId>","name":"Blog","slug":"blog"}\n\n## Delete folder\n\nCommands:\n\n- MCP tool: delete-folder {"folderId":"<folderId>"}\n\n## List element instances\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":3}\n\n## Inspect one element instance\n\nCommands:\n\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n\n## Append/prepend/replace child elements\n\nCommands:\n\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n\n## Move elements\n\nCommands:\n\n- MCP tool: move-instance {"moves":"moves.json contents"}\n\n## Clone element subtree\n\nCommands:\n\n- MCP tool: clone-instance {"sourceInstanceId":"<instanceId>","parentInstanceId":"<targetParentId>"}\n\n## Delete element subtree\n\nCommands:\n\n- MCP tool: delete-instance {"instanceId":"<instanceId>"}\n\n## List text/expression children\n\nCommands:\n\n- MCP tool: list-texts {"pagePath":"/"}\n\n## Update text child\n\nCommands:\n\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n\n## Update props\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n\n## Delete props\n\nCommands:\n\n- MCP tool: delete-props {"deletions":"props.json contents"}\n\n## Bind props to expressions/resources/actions\n\nCommands:\n\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\n## Read styles\n\nCommands:\n\n- MCP tool: get-styles {"instanceId":"<instanceId>","includeTokens":true}\n\n## Update local styles\n\nCommands:\n\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\n## Delete local styles\n\nCommands:\n\n- MCP tool: delete-styles {"deletions":"styles.json contents"}\n\n## Replace matching style values\n\nCommands:\n\n- MCP tool: replace-styles {"replacements":"replace.json contents"}\n\n## List design tokens\n\nCommands:\n\n- MCP tool: list-design-tokens {"withUsage":true}\n\n## Create design tokens\n\nCommands:\n\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n\n## Update design token styles\n\nCommands:\n\n- MCP tool: update-design-token-styles {"styleSourceId":"<tokenId>","updates":"styles.json contents"}\n\n## Delete design token styles\n\nCommands:\n\n- MCP tool: delete-design-token-styles {"styleSourceId":"<tokenId>","deletions":"styles.json contents"}\n\n## Attach design token to instances\n\nCommands:\n\n- MCP tool: attach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Detach design token from instances\n\nCommands:\n\n- MCP tool: detach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Extract design token from local styles\n\nCommands:\n\n- MCP tool: extract-design-token {"token":"token.json contents"}\n\n## List CSS variables\n\nCommands:\n\n- MCP tool: list-css-variables {"withUsage":true}\n\n## Define CSS variables\n\nCommands:\n\n- MCP tool: define-css-variable {"variables":"vars.json contents"}\n\n## Delete CSS variables\n\nCommands:\n\n- MCP tool: delete-css-variable {"names":"names.json contents","confirm":true}\n\n## Rewrite CSS variable references\n\nCommands:\n\n- MCP tool: rewrite-css-variable-refs {"variables":"variables.json contents"}\n\n## List data variables\n\nCommands:\n\n- MCP tool: list-variables {}\n\n## Create data variable\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n\n## Update data variable\n\nCommands:\n\n- MCP tool: update-variable {"variableId":"<variableId>","value":{"type":"json","value":{"count":1}}}\n\n## Delete data variable\n\nCommands:\n\n- MCP tool: delete-variable {"variableId":"<variableId>"}\n\n## List resources\n\nCommands:\n\n- MCP tool: list-resources {}\n\n## Create resource\n\nCommands:\n\n- MCP tool: create-resource {"name":"Posts","method":"get","url":"https://api.example.com/posts"}\n\n## Update resource\n\nCommands:\n\n- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}\n\n## Delete resource\n\nCommands:\n\n- MCP tool: delete-resource {"resourceId":"<resourceId>"}\n\n## List assets\n\nCommands:\n\n- MCP tool: list-assets {"withUsage":true}\n\n## Upload one asset\n\nCommands:\n\n- MCP tool: upload-asset {"asset":"asset.json contents","assetsDir":".webstudio/assets"}\n\n## Upload asset batch\n\nCommands:\n\n- MCP tool: upload-assets {"assets":"assets.json contents","assetsDir":".webstudio/assets"}\n\n## Find asset usage\n\nCommands:\n\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n\n## Replace asset references\n\nCommands:\n\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>","confirm":true}\n\n## Delete assets\n\nCommands:\n\n- MCP tool: delete-asset {"assetId":"<assetId>","confirm":true}\n\n## Publish project\n\nCommands:\n\n- webstudio publish deploy --target production --json\n\n## List publishes\n\nCommands:\n\n- webstudio publish list --json\n\n## Check publish job\n\nCommands:\n\n- webstudio publish status --job <buildId> --json\n\n## Unpublish\n\nCommands:\n\n- webstudio publish unpublish --target production --confirm --json\n\n## List domains\n\nCommands:\n\n- webstudio domains list --json\n\n## Create domain\n\nCommands:\n\n- webstudio domains create --domain example.com --json\n\n## Update domain\n\nCommands:\n\n- webstudio domains update --domain-id <domainId> --domain www.example.com --json\n\n## Delete domain\n\nCommands:\n\n- webstudio domains delete --domain-id <domainId> --confirm --json\n\n## Verify domain\n\nCommands:\n\n- webstudio domains verify --domain-id <domainId> --json\n\n## Make arbitrary store-level changes\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["<namespace>"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use only when no semantic command exists.\n\n## Manage marketplace metadata\n\nCommands:\n\n- MCP tool: snapshot {"include":["marketplaceProduct"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nPatch namespaces:\n\n- marketplaceProduct\n\n## Search and inspect safely\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":5}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: list-assets {"withUsage":true}\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n- MCP tool: snapshot {"include":["pages","instances","props","resources","assets"]}\n\nNotes:\n\n- Use this for finding elements by label, type, href/resource patterns, HTML snippets, missing accessibility metadata, or asset usage.\n\n## Refactor targeted content\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/"}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans"}\n- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>","confirm":true}\n- MCP tool: replace-styles {"replacements":"replace.json contents"}\n- MCP tool: rewrite-css-variable-refs {"variables":"variables.json contents"}\n\nNotes:\n\n- Use focused reads first, then mutate only matching instances, props, metadata, resource URLs, assets, or style references.\n\n## Optimize existing project\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans"}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: list-breakpoints {}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","maxWidth":1023}\n- MCP tool: get-styles {"instanceId":"<instanceId>","includeTokens":true}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: attach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n- MCP tool: update-project-settings {"settings":"project-settings.json contents"}\n\nNotes:\n\n- Use this for SEO metadata, accessibility labels, responsive behavior, token consistency, and project settings.\n\n## Connect external data\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-resource {"name":"Posts","method":"get","url":"https://api.example.com/posts"}\n- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n\nNotes:\n\n- Use this for CMS sections, blog listings, Ghost/headless CMS pages, n8n-style integrations, and API URLs built from variables.\n\n## Support dynamic runtime behavior\n\nCommands:\n\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: create-resource {"name":"Seats","method":"get","url":"https://api.example.com/seats"}\n- MCP tool: snapshot {"include":["instances","props","resources"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use existing scripts/resources for behavior, then move presentational structure into editable Webstudio instances where possible.\n- There is no dedicated semantic command yet for converting script-generated UI into editable Webstudio structure.\n\n## Build authenticated pages\n\nCommands:\n\n- MCP tool: create-page {"name":"Account","path":"/account"}\n- MCP tool: update-page {"pageId":"<pageId>","auth":{"login":"<login>","password":"<password>"}}\n- MCP tool: create-resource {"name":"Session","method":"get","url":"https://api.example.com/session"}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"user","value":{"type":"json","value":{}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Basic auth is semantic today. Provider-specific Supabase/Firebase setup still requires manual resources, props, embeds, or patches.\n\n## Generate from design input\n\nCommands:\n\n- MCP tool: create-page {"name":"Landing","path":"/landing"}\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n- MCP tool: define-css-variable {"variables":"vars.json contents"}\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n\nNotes:\n\n- Use this after external design interpretation. There is no dedicated import command for Figma, screenshots, Inception output, or design.md yet.\n\n## Cross-project maintenance\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n- webstudio permissions --json\n- webstudio mcp\n\nNotes:\n\n- Public API and CLI intentionally operate on one configured project at a time. Use an external script to loop over projects.\n\n# Known CLI Gaps\n\n## General project search and audit\n\nMissing:\nNo single semantic command searches across instance labels, props, hrefs, resource URLs, HTML embeds, asset references, and missing accessibility metadata.\n\nCurrent fallback:\nUse focused MCP reads such as list-instances, list-texts, list-assets, find-asset-usage, and snapshot.\n\nSuggested commands:\n\n- search-project\n- audit-accessibility\n- find-prop-usage\n\n## Save and manage page templates\n\nMissing:\nCLI can list page templates and create pages from existing templates, but cannot save a page as a template or update/delete templates semantically.\n\nCurrent fallback:\nUse MCP snapshot and apply-patch only when the template data model is understood.\n\nSuggested commands:\n\n- create-page-template\n- update-page-template\n- delete-page-template\n\n## Semantic marketplace metadata\n\nMissing:\nMarketplace metadata is only available through MCP snapshot/apply-patch, not dedicated semantic commands.\n\nCurrent fallback:\nUse MCP snapshot --include marketplaceProduct and apply-patch.\n\nSuggested commands:\n\n- get-marketplace\n- update-marketplace\n\n## Provider-specific authenticated pages\n\nMissing:\nCLI supports page basic auth and generic resources/props/embeds, but not guided Supabase/Firebase auth setup.\n\nCurrent fallback:\nCreate the page, resources, variables, props, and embeds manually with existing MCP semantic tools.\n\nSuggested commands:\n\n- setup-auth-page\n\n## Dynamic script/runtime integration helpers\n\nMissing:\nCLI can manipulate props/resources/embeds, but has no semantic workflow for converting script-generated UI into editable Webstudio structures.\n\nCurrent fallback:\nUse MCP append-instance, props, resources, and raw patch where necessary.\n\nSuggested commands:\n\n- integrate-runtime-ui\n\n## Generate from design input\n\nMissing:\nNo command imports Figma, screenshots, Inception output, or design.md and turns it into pages/tokens/layout.\n\nCurrent fallback:\nUse external generation, then apply semantic CLI commands or apply-patch.\n\nSuggested commands:\n\n- generate-from-design\n\n## Built-in cross-project maintenance\n\nMissing:\nPublic API and CLI intentionally operate on one configured project at a time; there is no built-in multi-project discovery or loop runner.\n\nCurrent fallback:\nRun the CLI from an external script that reconfigures one project/session at a time.\n\nSuggested commands:\n\n- none\n',
+ '# CLI API Use Cases\n\n## Link/configure one project\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n\nNotes:\n\n- Writes local project id and global origin/token config.\n\n## Import synced project bundle into another project\n\nCommands:\n\n- webstudio sync\n- webstudio import --to <destination-share-link>\n- MCP tool: import {"to":"<destination-share-link>"}\n\nNotes:\n\n- Imports local `.webstudio/data.json` into the destination project.\n- Destination share link must allow build/import access.\n- Use `--skip-assets` only when asset rows and files should not be imported.\n\n## Identify current token\n\nCommands:\n\n- MCP tool: whoami {}\n\n## Check token permissions\n\nCommands:\n\n- webstudio permissions --json\n\n## Inspect project/build/version\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["pages","instances","styles"]}\n\n## Discover CLI/API capabilities\n\nCommands:\n\n- webstudio schema api --json\n- webstudio man api --json\n- webstudio man llm --json\n- webstudio man mcp --json\n- MCP tool: meta.index {}\n- MCP tool: meta.guide {"brief":"Create a pricing page"}\n- MCP tool: meta.get_more_tools {"brief":"update-styles"}\n\nNotes:\n\n- Use `tools/list` for machine-readable MCP tool schemas.\n- Use `resources/list` and `resources/read` for longer MCP resources such as `webstudio://project/tools` and `webstudio://project/guide`.\n\n## Inspect and refresh MCP session cache\n\nCommands:\n\n- MCP tool: status {}\n- MCP tool: refresh {"namespaces":["pages","instances","styles"]}\n- MCP tool: reset-session {}\n\nNotes:\n\n- Use status before a task to understand the cached ProjectSession state.\n- Use refresh when project data may have changed outside the current MCP session.\n- Use reset-session when local cached state is corrupt or incompatible.\n\n## Visually verify rendered work with AI vision\n\nCommands:\n\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: preview.status {}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n- MCP tool: screenshot.diff {"baselinePath":"before.png","currentPath":"current.png","outputDir":".webstudio/screenshots"}\n- MCP tool: vision.install-ocr {"confirm":true}\n\nNotes:\n\n- Use this after page/content/style mutations and after generated project files are current so a vision-capable AI can see what was actually built.\n- Use waitForSelector when the rendered app has a reliable ready marker, waitUntil:"networkidle" for network-heavy pages, and waitForTimeout only for final visual settling.\n- For a fresh checkout, copied fixture, or newly generated app, run npm install or pnpm install in the generated project before preview.start or webstudio preview.\n- If preview fails with a missing generated-app command/package such as react-router or vite, install the generated app dependencies and retry.\n- When a baseline exists, use screenshot.diff to get changed regions, OCR textAnalysis, and diff artifact paths before deciding whether the result matches.\n- If screenshot.diff reports OCR unavailable and the user agrees to install it, call vision.install-ocr {"confirm":true}; otherwise continue with pixel diff and visual inspection.\n- Compare the PNG, OCR text evidence, and diff artifacts against the user\'s intent for layout, typography, colors, spacing, imagery, and responsive framing; then iterate with focused mutations.\n- Root CLI equivalent: webstudio preview --template ssg, then webstudio screenshot <url> --output current.png.\n\n## List pages\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n\n## Read page by id\n\nCommands:\n\n- MCP tool: get-page {"pageId":"<pageId>"}\n\n## Read page by path\n\nCommands:\n\n- MCP tool: get-page-by-path {"path":"/pricing"}\n\n## Create page\n\nCommands:\n\n- MCP tool: create-page {"name":"Pricing","path":"/pricing"}\n\n## Update page settings/metadata\n\nCommands:\n\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\\"Pricing\\"","meta":{"description":"\\"Plans\\"","status":"200"}}}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n\nNotes:\n\n- Page title and metadata text fields are expression-backed. For fixed text, send a quoted JavaScript string literal expression such as `"\\"Pricing\\""`.\n\n## Read project settings\n\nCommands:\n\n- MCP tool: get-project-settings {}\n\n## Update project settings\n\nCommands:\n\n- MCP tool: update-project-settings {"settings":"project-settings.json contents"}\n\n## List redirects\n\nCommands:\n\n- MCP tool: list-redirects {}\n\n## Create redirect\n\nCommands:\n\n- MCP tool: create-redirect {"oldPath":"/old","newPath":"/new","status":301}\n\n## Update redirect\n\nCommands:\n\n- MCP tool: update-redirect {"oldPath":"/old","newPath":"/newer","status":302}\n- MCP tool: update-redirect {"oldPath":"/old","status":null}\n\n## Delete redirect\n\nCommands:\n\n- MCP tool: delete-redirect {"oldPath":"/old"}\n\n## List breakpoints\n\nCommands:\n\n- MCP tool: list-breakpoints {}\n\n## Create breakpoint\n\nCommands:\n\n- MCP tool: create-breakpoint {"breakpointId":"tablet","label":"Tablet","maxWidth":991}\n\n## Update breakpoint\n\nCommands:\n\n- MCP tool: update-breakpoint {"breakpointId":"tablet","label":"Tablet","maxWidth":1023}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","condition":null,"minWidth":768}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","minWidth":null,"maxWidth":null,"condition":"(hover: hover)"}\n\n## Delete breakpoint\n\nCommands:\n\n- MCP tool: delete-breakpoint {"breakpointId":"tablet","confirm":true}\n\n## Duplicate page\n\nCommands:\n\n- MCP tool: duplicate-page {"pageId":"<pageId>","name":"Pricing Copy","path":"/pricing-copy"}\n\n## List page templates\n\nCommands:\n\n- MCP tool: list-page-templates {}\n\n## Create page from template\n\nCommands:\n\n- MCP tool: create-page-from-template {"templateId":"<templateId>","name":"Landing","path":"/landing"}\n\n## Delete page\n\nCommands:\n\n- MCP tool: delete-page {"pageId":"<pageId>"}\n\n## List folders\n\nCommands:\n\n- MCP tool: list-folders {"includePages":true}\n\n## Create folder\n\nCommands:\n\n- MCP tool: create-folder {"name":"Blog","slug":"blog"}\n\n## Update folder\n\nCommands:\n\n- MCP tool: update-folder {"folderId":"<folderId>","name":"Blog","slug":"blog"}\n\n## Delete folder\n\nCommands:\n\n- MCP tool: delete-folder {"folderId":"<folderId>"}\n\n## List element instances\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":3}\n\n## Inspect one element instance\n\nCommands:\n\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n\n## Append/prepend/replace child elements\n\nCommands:\n\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n\n## Move elements\n\nCommands:\n\n- MCP tool: move-instance {"moves":"moves.json contents"}\n\n## Clone element subtree\n\nCommands:\n\n- MCP tool: clone-instance {"sourceInstanceId":"<instanceId>","parentInstanceId":"<targetParentId>"}\n\n## Delete element subtree\n\nCommands:\n\n- MCP tool: delete-instance {"instanceId":"<instanceId>"}\n\n## List text/expression children\n\nCommands:\n\n- MCP tool: list-texts {"pagePath":"/"}\n\n## Update text child\n\nCommands:\n\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n\n## Update props\n\nCommands:\n\n- MCP tool: update-props {"updates":"props.json contents"}\n\nNotes:\n\n- Use this for fixed prop values such as `aria-label`, `alt`, `id`, static `href`, and other direct string/number/boolean/json prop values.\n- Do not use bindings just to set static text.\n\n## Delete props\n\nCommands:\n\n- MCP tool: delete-props {"deletions":"props.json contents"}\n\n## Bind props to expressions/resources/actions\n\nCommands:\n\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Use this only when the prop should remain dynamic: expression, parameter, resource, or action binding.\n- For a fixed string value, use `update-props` with `type:"string"` and a direct `value` instead.\n\n## Read styles\n\nCommands:\n\n- MCP tool: get-styles {"instanceId":"<instanceId>","includeTokens":true}\n\n## Update local styles\n\nCommands:\n\n- MCP tool: update-styles {"updates":"styles.json contents"}\n\n## Delete local styles\n\nCommands:\n\n- MCP tool: delete-styles {"deletions":"styles.json contents"}\n\n## Replace matching style values\n\nCommands:\n\n- MCP tool: replace-styles {"replacements":"replace.json contents"}\n\n## List design tokens\n\nCommands:\n\n- MCP tool: list-design-tokens {"withUsage":true}\n\n## Create design tokens\n\nCommands:\n\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n\n## Update design token styles\n\nCommands:\n\n- MCP tool: update-design-token-styles {"styleSourceId":"<tokenId>","updates":"styles.json contents"}\n\n## Delete design token styles\n\nCommands:\n\n- MCP tool: delete-design-token-styles {"styleSourceId":"<tokenId>","deletions":"styles.json contents"}\n\n## Attach design token to instances\n\nCommands:\n\n- MCP tool: attach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Detach design token from instances\n\nCommands:\n\n- MCP tool: detach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n\n## Extract design token from local styles\n\nCommands:\n\n- MCP tool: extract-design-token {"token":"token.json contents"}\n\n## List CSS variables\n\nCommands:\n\n- MCP tool: list-css-variables {"withUsage":true}\n\n## Define CSS variables\n\nCommands:\n\n- MCP tool: define-css-variable {"variables":"vars.json contents"}\n\n## Delete CSS variables\n\nCommands:\n\n- MCP tool: delete-css-variable {"names":"names.json contents","confirm":true}\n\n## Rewrite CSS variable references\n\nCommands:\n\n- MCP tool: rewrite-css-variable-refs {"variables":"variables.json contents"}\n\n## List data variables\n\nCommands:\n\n- MCP tool: list-variables {}\n\n## Create data variable\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n\n## Update data variable\n\nCommands:\n\n- MCP tool: update-variable {"variableId":"<variableId>","value":{"type":"json","value":{"count":1}}}\n\n## Delete data variable\n\nCommands:\n\n- MCP tool: delete-variable {"variableId":"<variableId>"}\n\n## List resources\n\nCommands:\n\n- MCP tool: list-resources {}\n\n## Create resource\n\nCommands:\n\n- MCP tool: create-resource {"name":"Posts","method":"get","url":"\\"https://api.example.com/posts\\""}\n\n## Update resource\n\nCommands:\n\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\\"https://api.example.com/posts\\""}}\n\n## Delete resource\n\nCommands:\n\n- MCP tool: delete-resource {"resourceId":"<resourceId>"}\n\n## List assets\n\nCommands:\n\n- MCP tool: list-assets {"withUsage":true}\n\n## Upload one asset\n\nCommands:\n\n- MCP tool: upload-asset {"asset":"asset.json contents","assetsDir":".webstudio/assets"}\n\n## Upload asset batch\n\nCommands:\n\n- MCP tool: upload-assets {"assets":"assets.json contents","assetsDir":".webstudio/assets"}\n\n## Find asset usage\n\nCommands:\n\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n\n## Replace asset references\n\nCommands:\n\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>","confirm":true}\n\n## Delete assets\n\nCommands:\n\n- MCP tool: delete-asset {"assetId":"<assetId>","confirm":true}\n\n## Publish project\n\nCommands:\n\n- webstudio publish deploy --target production --json\n\n## List publishes\n\nCommands:\n\n- webstudio publish list --json\n\n## Check publish job\n\nCommands:\n\n- webstudio publish status --job <buildId> --json\n\n## Unpublish\n\nCommands:\n\n- webstudio publish unpublish --target production --confirm --json\n\n## List domains\n\nCommands:\n\n- webstudio domains list --json\n\n## Create domain\n\nCommands:\n\n- webstudio domains create --domain example.com --json\n\n## Update domain\n\nCommands:\n\n- webstudio domains update --domain-id <domainId> --domain www.example.com --json\n\n## Delete domain\n\nCommands:\n\n- webstudio domains delete --domain-id <domainId> --confirm --json\n\n## Verify domain\n\nCommands:\n\n- webstudio domains verify --domain-id <domainId> --json\n\n## Make arbitrary store-level changes\n\nCommands:\n\n- MCP tool: inspect {}\n- MCP tool: snapshot {"include":["<namespace>"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use only when no semantic command exists.\n\n## Manage marketplace metadata\n\nCommands:\n\n- MCP tool: snapshot {"include":["marketplaceProduct"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nPatch namespaces:\n\n- marketplaceProduct\n\n## Search and inspect safely\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/","maxDepth":5}\n- MCP tool: inspect-instance {"instanceId":"<instanceId>","include":["props","styles","children"]}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: list-assets {"withUsage":true}\n- MCP tool: find-asset-usage {"assetId":"<assetId>"}\n- MCP tool: snapshot {"include":["pages","instances","props","resources","assets"]}\n\nNotes:\n\n- Use this for finding elements by label, type, href/resource patterns, HTML snippets, missing accessibility metadata, or asset usage.\n\n## Refactor targeted content\n\nCommands:\n\n- MCP tool: list-instances {"pagePath":"/"}\n- MCP tool: list-texts {"pagePath":"/"}\n- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\\"Pricing\\"","meta":{"description":"\\"Plans\\""}}}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\\"https://api.example.com/posts\\""}}\n- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>","confirm":true}\n- MCP tool: replace-styles {"replacements":"replace.json contents"}\n- MCP tool: rewrite-css-variable-refs {"variables":"variables.json contents"}\n\nNotes:\n\n- Use focused reads first, then mutate only matching instances, props, metadata, resource URLs, assets, or style references.\n\n## Optimize existing project\n\nCommands:\n\n- MCP tool: list-pages {"includeFolders":true}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\\"Pricing\\"","meta":{"description":"\\"Plans\\""}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: list-breakpoints {}\n- MCP tool: update-breakpoint {"breakpointId":"tablet","maxWidth":1023}\n- MCP tool: get-styles {"instanceId":"<instanceId>","includeTokens":true}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: attach-design-token {"styleSourceId":"<tokenId>","instanceIds":"instances.json contents"}\n- MCP tool: update-project-settings {"settings":"project-settings.json contents"}\n\nNotes:\n\n- Use this for SEO metadata, accessibility labels, responsive behavior, token consistency, and project settings.\n\n## Connect external data\n\nCommands:\n\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}\n- MCP tool: create-resource {"name":"Posts","method":"get","url":"\\"https://api.example.com/posts\\""}\n- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\\"https://api.example.com/posts\\""}}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n\nNotes:\n\n- Use this for CMS sections, blog listings, Ghost/headless CMS pages, n8n-style integrations, and API URLs built from variables.\n\n## Support dynamic runtime behavior\n\nCommands:\n\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n- MCP tool: create-resource {"name":"Seats","method":"get","url":"\\"https://api.example.com/seats\\""}\n- MCP tool: snapshot {"include":["instances","props","resources"]}\n- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}\n\nNotes:\n\n- Use existing scripts/resources for behavior, then move presentational structure into editable Webstudio instances where possible.\n- There is no dedicated semantic command yet for converting script-generated UI into editable Webstudio structure.\n\n## Build authenticated pages\n\nCommands:\n\n- MCP tool: create-page {"name":"Account","path":"/account"}\n- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}\n- MCP tool: create-resource {"name":"Session","method":"get","url":"\\"https://api.example.com/session\\""}\n- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"user","value":{"type":"json","value":{}}}\n- MCP tool: update-props {"updates":"props.json contents"}\n- MCP tool: bind-props {"bindings":"bindings.json contents"}\n\nNotes:\n\n- Basic auth is semantic today. Provider-specific Supabase/Firebase setup still requires manual resources, props, embeds, or patches.\n\n## Generate from design input\n\nCommands:\n\n- MCP tool: create-page {"name":"Landing","path":"/landing"}\n- MCP tool: create-design-token {"tokens":"tokens.json contents"}\n- MCP tool: define-css-variable {"variables":"vars.json contents"}\n- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}\n- MCP tool: update-styles {"updates":"styles.json contents"}\n- MCP tool: preview.start {"host":"127.0.0.1","port":5173}\n- MCP tool: screenshot {"path":"/","output":"current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}\n\nNotes:\n\n- Use this after external design interpretation. There is no dedicated import command for Figma, screenshots, Inception output, or design.md yet.\n\n## Cross-project maintenance\n\nCommands:\n\n- webstudio init --link <api-share-link> --json\n- webstudio permissions --json\n- webstudio mcp\n\nNotes:\n\n- Public API and CLI intentionally operate on one configured project at a time. Use an external script to loop over projects.\n\n# Known CLI Gaps\n\n## General project search and audit\n\nMissing:\nNo single semantic command searches across instance labels, props, hrefs, resource URLs, HTML embeds, asset references, and missing accessibility metadata.\n\nCurrent fallback:\nUse focused MCP reads such as list-instances, list-texts, list-assets, find-asset-usage, and snapshot.\n\nSuggested commands:\n\n- search-project\n- audit-accessibility\n- find-prop-usage\n\n## Save and manage page templates\n\nMissing:\nCLI can list page templates and create pages from existing templates, but cannot save a page as a template or update/delete templates semantically.\n\nCurrent fallback:\nUse MCP snapshot and apply-patch only when the template data model is understood.\n\nSuggested commands:\n\n- create-page-template\n- update-page-template\n- delete-page-template\n\n## Semantic marketplace metadata\n\nMissing:\nMarketplace metadata is only available through MCP snapshot/apply-patch, not dedicated semantic commands.\n\nCurrent fallback:\nUse MCP snapshot --include marketplaceProduct and apply-patch.\n\nSuggested commands:\n\n- get-marketplace\n- update-marketplace\n\n## Provider-specific authenticated pages\n\nMissing:\nCLI supports page basic auth and generic resources/props/embeds, but not guided Supabase/Firebase auth setup.\n\nCurrent fallback:\nCreate the page, resources, variables, props, and embeds manually with existing MCP semantic tools.\n\nSuggested commands:\n\n- setup-auth-page\n\n## Dynamic script/runtime integration helpers\n\nMissing:\nCLI can manipulate props/resources/embeds, but has no semantic workflow for converting script-generated UI into editable Webstudio structures.\n\nCurrent fallback:\nUse MCP append-instance, props, resources, and raw patch where necessary.\n\nSuggested commands:\n\n- integrate-runtime-ui\n\n## Generate from design input\n\nMissing:\nNo command imports Figma, screenshots, Inception output, or design.md and turns it into pages/tokens/layout.\n\nCurrent fallback:\nUse external generation, then apply semantic CLI commands or apply-patch.\n\nSuggested commands:\n\n- generate-from-design\n\n## Built-in cross-project maintenance\n\nMissing:\nPublic API and CLI intentionally operate on one configured project at a time; there is no built-in multi-project discovery or loop runner.\n\nCurrent fallback:\nRun the CLI from an external script that reconfigures one project/session at a time.\n\nSuggested commands:\n\n- none\n',
"manual-api":
'# Webstudio API CLI Manual\n\nThe API commands operate on the single project configured by:\n\n- .webstudio/config.json: projectId\n- global Webstudio config: origin and token\n\n- Pass --json to API/discovery commands that support it. Do not add --json to top-level commands unless their help/schema documents it.\n- Never pass a project id. Commands use configured project only.\n- Read ids before writing. Do not invent ids for existing records.\n- stdout is one JSON object. stderr is diagnostics.\n- Prefer MCP semantic tools for detailed project edits. Use MCP apply-patch only when no semantic tool exists.\n\n## Start\n\n{{start}}\n\n## Read First\n\n{{readFirst}}\n\n## Project Session Cache\n\n- CLI commands use one local ProjectSession snapshot for the configured project.\n- Local-capable reads use cached namespaces when compatible and fetch only missing or stale namespaces.\n- Local-capable mutations build patches from the local snapshot, then commit with the cached build version.\n- Successful mutation commits update the local snapshot only after the remote commit succeeds.\n- Server-only commands run remotely and invalidate/refetch namespaces declared by the operation catalog.\n- Use --refresh on local-capable commands to refresh required namespaces before running.\n- Successful JSON responses include meta.session with operationId, buildId, version, source, committed, compatibility, namespace freshness, and diagnostics.\n\n## CLI Capability Inventory\n\n### Top-Level Commands\n\n{{topLevelCapabilityIndex}}\n\n### High-Level API Commands By Area\n\n{{apiCapabilityIndex}}\n\n### MCP-Only Operations\n\nThese are intentionally exposed through `webstudio mcp`, not as top-level shell commands:\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": "unique-client-transaction-id",\n"payload": [\n{\n"namespace": "pages",\n"patches": [\n{ "op": "replace", "path": ["meta", "siteName"], "value": "New Site" }\n]\n}\n]\n}\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: site metadata, redirects, page records, folders, 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\nCommit raw patch:\n\nMCP tool: apply-patch\n\n## Raw Patch Examples\n\nRename the site:\n\n[\n{\n"id": "tx-site-name",\n"payload": [\n{\n"namespace": "pages",\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": "tx-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": "tx-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 a data variable:\n\n[\n{\n"id": "tx-variable",\n"payload": [\n{\n"namespace": "dataSources",\n"patches": [\n{\n"op": "add",\n"path": ["variable-id"],\n"value": {\n"type": "variable",\n"id": "variable-id",\n"scopeInstanceId": "instance-id",\n"name": "headline",\n"value": { "type": "string", "value": "Launch faster" }\n}\n}\n]\n}\n]\n}\n]\n\nCreate a design token:\n\n[\n{\n"id": "tx-token",\n"payload": [\n{\n"namespace": "styleSources",\n"patches": [\n{ "op": "add", "path": ["token-id"], "value": { "type": "token", "id": "token-id", "name": "Brand Primary" } }\n]\n},\n{\n"namespace": "styles",\n"patches": [\n{\n"op": "add",\n"path": ["token-id:base:color:"],\n"value": {\n"styleSourceId": "token-id",\n"breakpointId": "base",\n"property": "color",\n"value": { "type": "keyword", "value": "red" }\n}\n}\n]\n}\n]\n}\n]\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- Generate new unique ids when adding records.\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\n## Always\n\n1. webstudio permissions --json\n2. webstudio mcp\n3. Read MCP resource webstudio://project/tools.\n4. Pick focused MCP read tool.\n5. Pick semantic MCP write tool.\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 llm --json`, `webstudio schema api --json`, and MCP `meta.index` or `webstudio://project/tools`.\n2. Inspect current project state with semantic reads such as `list-pages`, `get-page-by-path`, `list-instances`, `inspect-instance`, `get-styles`, `list-assets`, `list-breakpoints`, and `snapshot` only when needed.\n3. Mutate the Webstudio project with semantic MCP write tools first. Prefer `append-instance`, `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## 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- Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.\n- Use webstudio schema api --json for machine-readable command metadata.\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\n## Always\n\n1. webstudio permissions --json\n2. webstudio mcp\n3. Read MCP resource webstudio://project/tools.\n4. Pick focused MCP read tool.\n5. Pick semantic MCP write tool.\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 llm --json`, `webstudio schema api --json`, and MCP `meta.index` or `webstudio://project/tools`.\n2. Inspect current project state with semantic reads such as `list-pages`, `get-page-by-path`, `list-instances`, `inspect-instance`, `get-styles`, `list-assets`, `list-breakpoints`, and `snapshot` only when needed.\n3. Mutate the Webstudio project with semantic MCP write tools first. Prefer `append-instance`, `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\n- Use direct value tools for fixed content. For visible text, use `update-text` with plain `text`. 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, parameter, resource result, or action. 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 are expression-backed strings. For fixed text, pass a JavaScript string literal expression with JSON quoting, for example `JSON.stringify("Pricing | Acme")` in code or `"\\"Pricing | Acme\\""` in JSON. Never pass raw multi-word text such as `"Pricing | Acme"` as an expression.\n- Page metadata update example: use `update-page` with `{"pageId":"page-id","values":{"title":"\\"Pricing | Acme\\"","meta":{"description":"\\"Plans for teams\\""}}}`.\n- Resource URL, header, search-param, and body fields are also expression-backed. For a fixed URL, use a string literal expression such as `"\\"https://api.example.com/items\\""`.\n- Resource update example: use `update-resource` with `{"resourceId":"resource-id","values":{"url":"\\"https://api.example.com/items\\""}}`.\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- For expression-backed fields that need fixed text, encode the fixed text as a quoted JavaScript string literal expression.\n- Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.\n- Use webstudio schema api --json for machine-readable command metadata.\n\n## Known Gaps\n\n{{knownCliGapIndex}}\n',
"manual-mcp":
"# Webstudio MCP Manual\n\n`webstudio mcp` starts a stdio MCP server for the configured project.\n\n## Startup\n\n1. Configure a project with `webstudio init --link <api-share-link> --json`.\n2. Check capabilities with `webstudio permissions --json`.\n3. Start the server with `webstudio mcp`.\n4. In the MCP client, read `webstudio://project/guide` before editing, or call `meta.index` and `meta.guide`.\n\nWhile the server is running, stdout is reserved for MCP JSON-RPC messages. Do not print human text from the server process.\n\n## Discovery\n\nUse MCP itself after startup:\n\n- `tools/list`: machine-readable available tools\n- `resources/list`: available longer JSON resources\n- `meta.index`: concise capability catalog\n- `meta.guide`: workflow for a user goal\n- `meta.get_more_tools`: detailed params, examples, namespaces, and local/server behavior\n\nUseful resources:\n\n- `webstudio://project/status`: current ProjectSession status\n- `webstudio://project/tools`: operation catalog\n- `webstudio://project/guide`: concise discovery guide\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.\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":
@@ -71,6 +71,16 @@ export const cliDocSections = {
"Generated files are build artifacts and may be overwritten by webstudio build.",
"If a task truly requires generated app customization, keep it outside app/__generated__ where possible and explain that it is not editable Webstudio content.",
],
+ valuesVsBindings: [
+ "Use direct value tools for fixed content. For visible text, use update-text with plain text. 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.",
+ "Use bind-props only when the prop must stay dynamic: an expression, parameter, resource result, or action. Do not use bind-props just to set a fixed string.",
+ 'Direct prop string example: {"updates":[{"instanceId":"button-id","name":"aria-label","type":"string","value":"Open menu"}]}.',
+ '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 are expression-backed strings. For fixed text, pass a JavaScript string literal expression with JSON quoting, for example JSON.stringify("Pricing | Acme") in code or "\\"Pricing | Acme\\"" in JSON. Never pass raw multi-word text such as "Pricing | Acme" as an expression.',
+ 'Page metadata update example: use update-page with {"pageId":"page-id","values":{"title":"\\"Pricing | Acme\\"","meta":{"description":"\\"Plans for teams\\""}}}.',
+ 'Resource URL, header, search-param, and body fields are also expression-backed. For a fixed URL, use a string literal expression such as "\\"https://api.example.com/items\\"".',
+ 'Resource update example: use update-resource with {"resourceId":"resource-id","values":{"url":"\\"https://api.example.com/items\\""}}.',
+ ],
rules: [
"Never guess ids for existing records. Read them first.",
"Never use project ids from user input. Commands use the configured project.",
@@ -80,6 +90,8 @@ export const cliDocSections = {
"Treat stdout JSON as the API contract and stderr as diagnostics.",
"For visual/design work, verify the rendered result with vision before finishing.",
"Do not edit generated files for normal Webstudio content/design requests.",
+ "Use direct values for static strings and bindings only for dynamic expressions/resources/actions.",
+ "For expression-backed fields that need fixed text, encode the fixed text as a quoted JavaScript string literal expression.",
"Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.",
"Use webstudio schema api --json for machine-readable command metadata.",
],
diff --git a/packages/cli/src/docs/api-use-cases.md b/packages/cli/src/docs/api-use-cases.md
index f4c5d7afeb..0a7d4a435e 100644
--- a/packages/cli/src/docs/api-use-cases.md
+++ b/packages/cli/src/docs/api-use-cases.md
@@ -123,8 +123,12 @@ Commands:
Commands:
-- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans","status":"200"}
-- MCP tool: update-page {"pageId":"<pageId>","auth":{"login":"<login>","password":"<password>"}}
+- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\"Pricing\"","meta":{"description":"\"Plans\"","status":"200"}}}
+- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}
+
+Notes:
+
+- Page title and metadata text fields are expression-backed. For fixed text, send a quoted JavaScript string literal expression such as `"\"Pricing\""`.
## Read project settings
@@ -291,6 +295,11 @@ Commands:
- MCP tool: update-props {"updates":"props.json contents"}
+Notes:
+
+- Use this for fixed prop values such as `aria-label`, `alt`, `id`, static `href`, and other direct string/number/boolean/json prop values.
+- Do not use bindings just to set static text.
+
## Delete props
Commands:
@@ -303,6 +312,11 @@ Commands:
- MCP tool: bind-props {"bindings":"bindings.json contents"}
+Notes:
+
+- Use this only when the prop should remain dynamic: expression, parameter, resource, or action binding.
+- For a fixed string value, use `update-props` with `type:"string"` and a direct `value` instead.
+
## Read styles
Commands:
@@ -427,13 +441,13 @@ Commands:
Commands:
-- MCP tool: create-resource {"name":"Posts","method":"get","url":"https://api.example.com/posts"}
+- MCP tool: create-resource {"name":"Posts","method":"get","url":"\"https://api.example.com/posts\""}
## Update resource
Commands:
-- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}
+- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\"https://api.example.com/posts\""}}
## Delete resource
@@ -577,8 +591,8 @@ Commands:
- MCP tool: list-texts {"pagePath":"/"}
- MCP tool: update-text {"instanceId":"<instanceId>","childIndex":0,"text":"Launch faster"}
- MCP tool: update-props {"updates":"props.json contents"}
-- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans"}
-- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}
+- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\"Pricing\"","meta":{"description":"\"Plans\""}}}
+- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\"https://api.example.com/posts\""}}
- MCP tool: replace-asset {"fromAssetId":"<oldAssetId>","toAssetId":"<newAssetId>","confirm":true}
- MCP tool: replace-styles {"replacements":"replace.json contents"}
- MCP tool: rewrite-css-variable-refs {"variables":"variables.json contents"}
@@ -592,7 +606,7 @@ Notes:
Commands:
- MCP tool: list-pages {"includeFolders":true}
-- MCP tool: update-page {"pageId":"<pageId>","title":"Pricing","description":"Plans"}
+- MCP tool: update-page {"pageId":"<pageId>","values":{"title":"\"Pricing\"","meta":{"description":"\"Plans\""}}}
- MCP tool: update-props {"updates":"props.json contents"}
- MCP tool: list-breakpoints {}
- MCP tool: update-breakpoint {"breakpointId":"tablet","maxWidth":1023}
@@ -610,8 +624,8 @@ Notes:
Commands:
- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"title","value":{"type":"string","value":"Hello"}}
-- MCP tool: create-resource {"name":"Posts","method":"get","url":"https://api.example.com/posts"}
-- MCP tool: update-resource {"resourceId":"<resourceId>","url":"https://api.example.com/posts"}
+- MCP tool: create-resource {"name":"Posts","method":"get","url":"\"https://api.example.com/posts\""}
+- MCP tool: update-resource {"resourceId":"<resourceId>","values":{"url":"\"https://api.example.com/posts\""}}
- MCP tool: bind-props {"bindings":"bindings.json contents"}
- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}
@@ -626,7 +640,7 @@ Commands:
- MCP tool: append-instance {"parentInstanceId":"<instanceId>","children":"children.json contents"}
- MCP tool: update-props {"updates":"props.json contents"}
- MCP tool: bind-props {"bindings":"bindings.json contents"}
-- MCP tool: create-resource {"name":"Seats","method":"get","url":"https://api.example.com/seats"}
+- MCP tool: create-resource {"name":"Seats","method":"get","url":"\"https://api.example.com/seats\""}
- MCP tool: snapshot {"include":["instances","props","resources"]}
- MCP tool: apply-patch {"baseVersion":"<version>","transactions":"patch.json contents"}
@@ -640,8 +654,8 @@ Notes:
Commands:
- MCP tool: create-page {"name":"Account","path":"/account"}
-- MCP tool: update-page {"pageId":"<pageId>","auth":{"login":"<login>","password":"<password>"}}
-- MCP tool: create-resource {"name":"Session","method":"get","url":"https://api.example.com/session"}
+- MCP tool: update-page {"pageId":"<pageId>","values":{"meta":{"auth":{"login":"<login>","password":"<password>"}}}}
+- MCP tool: create-resource {"name":"Session","method":"get","url":"\"https://api.example.com/session\""}
- MCP tool: create-variable {"scopeInstanceId":"<instanceId>","name":"user","value":{"type":"json","value":{}}}
- MCP tool: update-props {"updates":"props.json contents"}
- MCP tool: bind-props {"bindings":"bindings.json contents"}
diff --git a/packages/cli/src/docs/manual-llm.md b/packages/cli/src/docs/manual-llm.md
index 935189307b..2ca65a3e20 100644
--- a/packages/cli/src/docs/manual-llm.md
+++ b/packages/cli/src/docs/manual-llm.md
@@ -58,6 +58,19 @@ For responsive page work, use Builder breakpoints as the source of truth:
- Generated files are build artifacts and may be overwritten by `webstudio build`.
- If a task truly requires generated app customization, keep it outside `app/__generated__` where possible and explain that it is not editable Webstudio content.
+::doc-section{field="valuesVsBindings"}
+
+## Values vs Bindings
+
+- Use direct value tools for fixed content. For visible text, use `update-text` with plain `text`. 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.
+- Use `bind-props` only when the prop must stay dynamic: an expression, parameter, resource result, or action. Do not use `bind-props` just to set a fixed string.
+- Direct prop string example: `{"updates":[{"instanceId":"button-id","name":"aria-label","type":"string","value":"Open menu"}]}`.
+- 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 are expression-backed strings. For fixed text, pass a JavaScript string literal expression with JSON quoting, for example `JSON.stringify("Pricing | Acme")` in code or `"\"Pricing | Acme\""` in JSON. Never pass raw multi-word text such as `"Pricing | Acme"` as an expression.
+- Page metadata update example: use `update-page` with `{"pageId":"page-id","values":{"title":"\"Pricing | Acme\"","meta":{"description":"\"Plans for teams\""}}}`.
+- Resource URL, header, search-param, and body fields are also expression-backed. For a fixed URL, use a string literal expression such as `"\"https://api.example.com/items\""`.
+- Resource update example: use `update-resource` with `{"resourceId":"resource-id","values":{"url":"\"https://api.example.com/items\""}}`.
+
## Pick Read Command
{{readFirst}}
@@ -90,6 +103,8 @@ MCP tools receive JSON argument objects, not CLI flags. Use these shapes:
- Treat stdout JSON as the API contract and stderr as diagnostics.
- For visual/design work, verify the rendered result with vision before finishing.
- Do not edit generated files for normal Webstudio content/design requests.
+- Use direct values for static strings and bindings only for dynamic expressions/resources/actions.
+- For expression-backed fields that need fixed text, encode the fixed text as a quoted JavaScript string literal expression.
- Confirm destructive commands with --confirm only when user requested deletion/unpublish/replacement.
- Use webstudio schema api --json for machine-readable command metadata.
diff --git a/packages/project-build/src/docs.generated.ts b/packages/project-build/src/docs.generated.ts
index 4981d0f1c6..cd10b6f677 100644
--- a/packages/project-build/src/docs.generated.ts
+++ b/packages/project-build/src/docs.generated.ts
@@ -2,7 +2,7 @@
// Edit markdown files in src/docs instead.
export const projectBuildDocs = {
"mcp-startup-guidance":
- "Before editing a Webstudio project, read `webstudio://project/guide` and `webstudio://project/tools`, or call `meta.index` and `meta.guide`. Follow the guide: read ids and Builder breakpoints first, prefer semantic tools over `apply-patch`, do not edit generated files for normal content/design changes, and use `preview.start` plus screenshot/vision for visual work.\n",
+ "Before editing a Webstudio project, read `webstudio://project/guide` and `webstudio://project/tools`, or call `meta.index` and `meta.guide`. Follow the guide: read ids and Builder breakpoints first, prefer semantic tools over `apply-patch`, use direct value tools for fixed text/props, use bindings only for dynamic expressions/resources/actions, quote fixed text for expression-backed fields such as page metadata and resource URLs, put page/resource update fields under `values`, do not edit generated files for normal content/design changes, and use `preview.start` plus screenshot/vision for visual work.\n",
} as const;
export type ProjectBuildDocName = keyof typeof projectBuildDocs;
diff --git a/packages/project-build/src/docs/mcp-startup-guidance.md b/packages/project-build/src/docs/mcp-startup-guidance.md
index 12903a020d..10917fd028 100644
--- a/packages/project-build/src/docs/mcp-startup-guidance.md
+++ b/packages/project-build/src/docs/mcp-startup-guidance.md
@@ -1 +1 @@
-Before editing a Webstudio project, read `webstudio://project/guide` and `webstudio://project/tools`, or call `meta.index` and `meta.guide`. Follow the guide: read ids and Builder breakpoints first, prefer semantic tools over `apply-patch`, do not edit generated files for normal content/design changes, and use `preview.start` plus screenshot/vision for visual work.
+Before editing a Webstudio project, read `webstudio://project/guide` and `webstudio://project/tools`, or call `meta.index` and `meta.guide`. Follow the guide: read ids and Builder breakpoints first, prefer semantic tools over `apply-patch`, use direct value tools for fixed text/props, use bindings only for dynamic expressions/resources/actions, quote fixed text for expression-backed fields such as page metadata and resource URLs, put page/resource update fields under `values`, do not edit generated files for normal content/design changes, and use `preview.start` plus screenshot/vision for visual work.
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index 5b4dff3971..87d7593724 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -506,6 +506,11 @@ describe("project session mcp adapter", () => {
expect.objectContaining({
readThisFirst: expect.stringContaining("webstudio://project/guide"),
startHere: expect.arrayContaining(["meta.guide"]),
+ rules: expect.arrayContaining([
+ expect.stringContaining(
+ "Use direct value tools for fixed text/props"
+ ),
+ ]),
capabilities: expect.arrayContaining([
expect.objectContaining({
area: "publish",
@@ -549,8 +554,9 @@ describe("project session mcp adapter", () => {
inputFields: ["target", "domains"],
mcpExamples: [{ target: "production" }],
cliExamples: [],
- inputNote:
- "MCP tool arguments are public API input objects. Examples show intent, but do not imply MCP flag names.",
+ inputNote: expect.stringContaining(
+ "Use direct value tools for fixed text/props"
+ ),
}),
]),
})
@@ -1181,6 +1187,11 @@ describe("project session mcp adapter", () => {
expect.objectContaining({
readThisFirst: expect.stringContaining("webstudio://project/guide"),
startHere: expect.arrayContaining(["meta.index"]),
+ rules: expect.arrayContaining([
+ expect.stringContaining(
+ "Use direct value tools for fixed text/props"
+ ),
+ ]),
})
);
});
diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.ts
index d0939a742c..1744437bf3 100644
--- a/packages/project-build/src/mcp.ts
+++ b/packages/project-build/src/mcp.ts
@@ -433,6 +433,53 @@ export const mcpArgumentExamples: Record<string, readonly unknown[]> = {
text: "Launch faster",
},
],
+ "update-page": [
+ {
+ pageId: "page-id",
+ values: {
+ title: '"Pricing"',
+ meta: {
+ description: '"Pricing plans"',
+ },
+ },
+ },
+ ],
+ "update-props": [
+ {
+ updates: [
+ {
+ instanceId: "button-id",
+ name: "aria-label",
+ type: "string",
+ value: "Open menu",
+ },
+ ],
+ },
+ ],
+ "bind-props": [
+ {
+ bindings: [
+ {
+ instanceId: "link-id",
+ name: "href",
+ binding: { type: "expression", value: "currentPost.url" },
+ },
+ ],
+ },
+ ],
+ "create-resource": [
+ {
+ name: "Posts",
+ method: "get",
+ url: '"https://api.example.com/posts"',
+ },
+ ],
+ "update-resource": [
+ {
+ resourceId: "resource-id",
+ values: { url: '"https://api.example.com/posts"' },
+ },
+ ],
"update-styles": [
{
updates: [
@@ -1069,6 +1116,8 @@ const filterCapabilities = (tools: readonly ProjectSessionMcpTool[]) => {
};
const startupGuidance = readProjectBuildDoc("mcp-startup-guidance").trim();
+const valuesVsBindingsRule =
+ 'Use direct value tools for fixed text/props. Use bindings only for dynamic expressions, parameters, resources, or actions. Expression-backed fixed strings such as page metadata and resource URLs must be quoted JavaScript string literal expressions, for example "\\"Pricing\\"". Page and resource updates put changed fields under values.';
const getMetaIndex = (
tools: readonly ProjectSessionMcpTool[],
@@ -1094,6 +1143,7 @@ const getMetaIndex = (
"Operate on the configured project only.",
"Read ids before writing.",
"Prefer semantic tools over apply-patch.",
+ valuesVsBindingsRule,
"Use status/refresh when cached data may be stale.",
guidance?.visualVerificationRule,
].filter((rule): rule is string => rule !== undefined),
@@ -1129,6 +1179,7 @@ const getMetaGuide = (
: undefined,
"Use focused read tools to collect ids and current values.",
"Use the smallest semantic mutation tool that matches the requested change.",
+ valuesVsBindingsRule,
"Use apply-patch only when no semantic mutation tool fits.",
canVerifyVisually && guidance !== undefined
? guidance.getVisionWorkflowSummary({ includeDiff: canDiffScreenshots })
@@ -1161,8 +1212,7 @@ const getMoreTools = (
mcpExamples: tool.mcpExamples ?? [],
cliRequiredOptions: tool.cliRequiredOptions ?? [],
cliExamples: tool.cliExamples ?? [],
- inputNote:
- "MCP tool arguments are public API input objects. Examples show intent, but do not imply MCP flag names.",
+ inputNote: `MCP tool arguments are public API input objects. Examples show intent, but do not imply MCP flag names. ${valuesVsBindingsRule}`,
annotations: tool.annotations,
})),
});
diff --git a/packages/project-build/src/runtime/data.test.tsx b/packages/project-build/src/runtime/data.test.tsx
index 31b62fd715..9ba15c89c6 100644
--- a/packages/project-build/src/runtime/data.test.tsx
+++ b/packages/project-build/src/runtime/data.test.tsx
@@ -1514,6 +1514,23 @@ describe("createResourceValue", () => {
).toThrow();
});
+ test("reject invalid resource expressions", () => {
+ expect(() =>
+ resourceFieldsInput.parse({
+ name: "Users",
+ method: "get",
+ url: "https://example.com/users",
+ searchParams: [],
+ headers: [],
+ })
+ ).toThrow();
+ expect(() =>
+ resourceFieldsUpdateInput.parse({
+ searchParams: [{ name: "page", value: "page value" }],
+ })
+ ).toThrow();
+ });
+
test("creates resource values through the sdk schema", () => {
expect(
createResourceValue({
diff --git a/packages/project-build/src/runtime/data.ts b/packages/project-build/src/runtime/data.ts
index d4d1e2a574..a92d961470 100644
--- a/packages/project-build/src/runtime/data.ts
+++ b/packages/project-build/src/runtime/data.ts
@@ -11,7 +11,6 @@ import {
getAllPages,
getExpressionIdentifiers,
getStyleDeclKey,
- lintExpression,
ROOT_INSTANCE_ID,
resource,
SYSTEM_VARIABLE_ID,
@@ -42,6 +41,7 @@ import {
import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
import { throwBuilderRuntimeError } from "./errors";
+import { getNamedExpressionErrors } from "./expression-validation";
import { createRuntimeMutation } from "./mutation";
const getRequiredDataSources = (state: Pick<BuilderState, "dataSources">) => {
@@ -1149,11 +1149,33 @@ export const findResource = (
}
};
-export const resourceFieldsInput = resource
+const addExpressionIssues = (
+ context: z.RefinementCtx,
+ errors: readonly string[]
+) => {
+ for (const message of errors) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ message,
+ });
+ }
+};
+
+const resourceFieldsInputBase = resource
.omit({ id: true })
.extend({ control: z.enum(["system", "graphql"]).optional() });
-export const resourceFieldsUpdateInput = resourceFieldsInput.partial();
+export const resourceFieldsInput = resourceFieldsInputBase.superRefine(
+ (fields, context) => {
+ addExpressionIssues(context, getResourceExpressionErrors(fields));
+ }
+);
+
+export const resourceFieldsUpdateInput = resourceFieldsInputBase
+ .partial()
+ .superRefine((fields, context) => {
+ addExpressionIssues(context, getResourceExpressionErrors(fields));
+ });
export const createResourceValue = ({
id,
@@ -1190,14 +1212,7 @@ export const getResourceExpressionErrors = (
) => {
const errors: string[] = [];
const validate = (name: string, expression: string | undefined) => {
- if (expression === undefined) {
- return;
- }
- for (const diagnostic of lintExpression({ expression })) {
- if (diagnostic.severity === "error") {
- errors.push(`${name}: ${diagnostic.message}`);
- }
- }
+ errors.push(...getNamedExpressionErrors(name, expression));
};
validate("url", fields.url);
validate("body", fields.body);
diff --git a/packages/project-build/src/runtime/expression-validation.ts b/packages/project-build/src/runtime/expression-validation.ts
new file mode 100644
index 0000000000..f06c744e32
--- /dev/null
+++ b/packages/project-build/src/runtime/expression-validation.ts
@@ -0,0 +1,18 @@
+import { lintExpression } from "@webstudio-is/sdk";
+
+export const getExpressionErrors = (expression: string) =>
+ lintExpression({ expression })
+ .filter((diagnostic) => diagnostic.severity === "error")
+ .map((diagnostic) => diagnostic.message);
+
+export const getNamedExpressionErrors = (
+ name: string,
+ expression: string | undefined
+) => {
+ if (expression === undefined) {
+ return [];
+ }
+ return getExpressionErrors(expression).map(
+ (message) => `${name}: ${message}`
+ );
+};
diff --git a/packages/project-build/src/runtime/instances.ts b/packages/project-build/src/runtime/instances.ts
index 31a70605f2..62de17af25 100644
--- a/packages/project-build/src/runtime/instances.ts
+++ b/packages/project-build/src/runtime/instances.ts
@@ -1,7 +1,6 @@
import {
elementComponent,
getStyleDeclKey,
- lintExpression,
type DataSource,
type Instance,
type Instances,
@@ -17,6 +16,7 @@ import {
import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
import { throwBuilderRuntimeError } from "./errors";
+import { getExpressionErrors } from "./expression-validation";
import { createRuntimeMutation } from "./mutation";
import { findSerializedPageByInput, getSerializedPages } from "./pages";
import { createPropClonePatches } from "./props";
@@ -1060,9 +1060,7 @@ export const getTextContentErrors = ({
if (type === "text") {
return [];
}
- return lintExpression({ expression: value })
- .filter((diagnostic) => diagnostic.severity === "error")
- .map((diagnostic) => diagnostic.message);
+ return getExpressionErrors(value);
};
export const setTextContentMutable = (
diff --git a/packages/project-build/src/runtime/pages.test.ts b/packages/project-build/src/runtime/pages.test.ts
index f97430d825..5f9bf61f5b 100644
--- a/packages/project-build/src/runtime/pages.test.ts
+++ b/packages/project-build/src/runtime/pages.test.ts
@@ -31,6 +31,7 @@ import {
getFolderDeletionTargets,
getHomePageRootInstanceId,
getParentFolderId,
+ getPageExpressionErrors,
getSerializedPagePath,
getSerializedPages,
isPathAvailable,
@@ -40,6 +41,7 @@ import {
serializePageDetails,
serializePageDetailsByInput,
serializePageSummary,
+ updatePage,
} from "./pages";
const createPages = () =>
@@ -94,7 +96,7 @@ test("creates a page with title defaulting to name", () => {
id: "page",
name: "Page",
path: "/page",
- title: "Page",
+ title: `"Page"`,
rootInstanceId: "root",
meta: {},
});
@@ -510,32 +512,59 @@ describe("page input schemas", () => {
pageFieldsInput.parse({
name: "About",
path: "/about",
- title: "About",
+ title: `"About"`,
parentFolderId: "folder",
meta: {
- description: "About us",
+ description: `"About us"`,
excludePageFromSearch: true,
documentType: "html",
- custom: [{ property: "og:title", content: "About" }],
+ custom: [{ property: "og:title", content: `"About"` }],
},
})
).toEqual({
name: "About",
path: "/about",
- title: "About",
+ title: `"About"`,
parentFolderId: "folder",
meta: {
- description: "About us",
+ description: `"About us"`,
excludePageFromSearch: true,
documentType: "html",
- custom: [{ property: "og:title", content: "About" }],
+ custom: [{ property: "og:title", content: `"About"` }],
},
});
});
- test("reject empty page names and invalid document types", () => {
+ test("reject empty page names, invalid document types, and invalid expressions", () => {
expect(() => pageFieldsInput.parse({ name: "" })).toThrow();
expect(() => pageMetaInput.parse({ documentType: "json" })).toThrow();
+ expect(() =>
+ pageFieldsInput.parse({
+ title: "About us",
+ meta: { description: "About us" },
+ })
+ ).toThrow();
+ expect(() =>
+ pageMetaInput.parse({
+ custom: [{ property: "og:title", content: "About us" }],
+ })
+ ).toThrow();
+ });
+
+ test("reports page expression errors", () => {
+ expect(
+ getPageExpressionErrors({
+ title: "About us",
+ meta: {
+ description: "About us",
+ custom: [{ property: "og:title", content: "About us" }],
+ },
+ })
+ ).toEqual([
+ expect.stringMatching(/^title:/),
+ expect.stringMatching(/^meta.description:/),
+ expect.stringMatching(/^meta.custom.0.content:/),
+ ]);
});
});
@@ -902,3 +931,59 @@ describe("getFolderDeletionTargets", () => {
});
});
});
+
+describe("updatePage", () => {
+ test("rejects invalid page metadata expressions before patching", () => {
+ const pages = createPages();
+
+ expect(() =>
+ updatePage(
+ { pages },
+ {
+ pageId: "page",
+ values: {
+ title: "Pricing Plans",
+ meta: {
+ description: "Plans for teams",
+ },
+ },
+ }
+ )
+ ).toThrow(/title:/);
+ });
+
+ test("accepts string literal page metadata expressions", () => {
+ const pages = createPages();
+
+ expect(
+ updatePage(
+ { pages },
+ {
+ pageId: "page",
+ values: {
+ title: `"Pricing Plans"`,
+ meta: {
+ description: `"Plans for teams"`,
+ },
+ },
+ }
+ ).payload
+ ).toEqual([
+ {
+ namespace: "pages",
+ patches: [
+ {
+ op: "replace",
+ path: ["pages", "page", "title"],
+ value: `"Pricing Plans"`,
+ },
+ {
+ op: "add",
+ path: ["pages", "page", "meta", "description"],
+ value: `"Plans for teams"`,
+ },
+ ],
+ },
+ ]);
+ });
+});
diff --git a/packages/project-build/src/runtime/pages.ts b/packages/project-build/src/runtime/pages.ts
index de289a91a1..7f8c9e459f 100644
--- a/packages/project-build/src/runtime/pages.ts
+++ b/packages/project-build/src/runtime/pages.ts
@@ -18,6 +18,7 @@ import {
import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
import { throwBuilderRuntimeError } from "./errors";
+import { getNamedExpressionErrors } from "./expression-validation";
import {
collectExclusiveInstanceIds,
createInstanceCleanupPayload,
@@ -520,7 +521,7 @@ export const createPageValue = ({
pageId,
name,
path,
- title = name,
+ title = JSON.stringify(name),
rootInstanceId,
meta = {},
}: {
@@ -548,6 +549,15 @@ const emptyStringRemovesMetaFields = new Set<keyof PageMeta>([
"socialImageUrl",
]);
+const pageMetaExpressionFields = [
+ "description",
+ "language",
+ "redirect",
+ "socialImageUrl",
+ "status",
+ "content",
+] as const satisfies readonly (keyof PageMetaPatchInput)[];
+
export const normalizePageMetaValue = <Name extends keyof PageMeta>(
name: Name,
value: PageMeta[Name]
@@ -580,7 +590,19 @@ type PageFieldsPatchInput = Partial<{
meta: PageMetaPatchInput;
}>;
-export const pageMetaInput = z.object({
+const addExpressionIssues = (
+ context: z.RefinementCtx,
+ errors: readonly string[]
+) => {
+ for (const message of errors) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ message,
+ });
+ }
+};
+
+const pageMetaInputBase = z.object({
description: z.string().optional(),
language: z.string().optional(),
redirect: z.string().optional(),
@@ -596,14 +618,45 @@ export const pageMetaInput = z.object({
.optional(),
});
-export const pageFieldsInput = z.object({
- name: z.string().min(1).optional(),
- path: z.string().optional(),
- title: z.string().optional(),
- parentFolderId: z.string().optional(),
- meta: pageMetaInput.optional(),
+export const getPageExpressionErrors = (input: PageFieldsPatchInput) => {
+ const errors: string[] = [];
+ errors.push(...getNamedExpressionErrors("title", input.title));
+ if (input.meta !== undefined) {
+ for (const name of pageMetaExpressionFields) {
+ const expression = input.meta[name];
+ if (expression === "" && emptyStringRemovesMetaFields.has(name)) {
+ continue;
+ }
+ errors.push(...getNamedExpressionErrors(`meta.${name}`, expression));
+ }
+ for (const [index, customMeta] of (input.meta.custom ?? []).entries()) {
+ errors.push(
+ ...getNamedExpressionErrors(
+ `meta.custom.${index}.content`,
+ customMeta.content
+ )
+ );
+ }
+ }
+ return errors;
+};
+
+export const pageMetaInput = pageMetaInputBase.superRefine((meta, context) => {
+ addExpressionIssues(context, getPageExpressionErrors({ meta }));
});
+export const pageFieldsInput = z
+ .object({
+ name: z.string().min(1).optional(),
+ path: z.string().optional(),
+ title: z.string().optional(),
+ parentFolderId: z.string().optional(),
+ meta: pageMetaInputBase.optional(),
+ })
+ .superRefine((fields, context) => {
+ addExpressionIssues(context, getPageExpressionErrors(fields));
+ });
+
export const pageMetaToPatchValue = (meta: PageMetaPatchInput) => {
const result: Record<string, unknown> = {};
for (const [name, value] of Object.entries(meta)) {
@@ -738,6 +791,10 @@ export const createPage = (
const pages = getRequiredPages(state);
const parentFolderId = input.parentFolderId ?? pages.rootFolderId;
const parentFolder = getFolderOrThrow(pages, parentFolderId);
+ const expressionErrors = getPageExpressionErrors(input);
+ if (expressionErrors.length > 0) {
+ return throwBuilderRuntimeError("BAD_REQUEST", expressionErrors.join("\n"));
+ }
const pageId = input.pageId ?? context.createId();
if (pages.pages.has(pageId)) {
return throwBuilderRuntimeError("CONFLICT", "Page id already exists");
@@ -789,6 +846,10 @@ export const updatePage = (
if (page === undefined) {
return throwBuilderRuntimeError("NOT_FOUND", "Page not found");
}
+ const expressionErrors = getPageExpressionErrors(input.values);
+ if (expressionErrors.length > 0) {
+ return throwBuilderRuntimeError("BAD_REQUEST", expressionErrors.join("\n"));
+ }
if (
(input.values.path !== undefined ||
input.values.parentFolderId !== undefined) &&
diff --git a/packages/project-build/src/runtime/props.test.ts b/packages/project-build/src/runtime/props.test.ts
index b135464c08..17260b6767 100644
--- a/packages/project-build/src/runtime/props.test.ts
+++ b/packages/project-build/src/runtime/props.test.ts
@@ -120,6 +120,23 @@ describe("prop input creators", () => {
binding: { type: "string", value: "Label" },
})
).toThrow();
+
+ expect(() =>
+ propValueInput.parse({
+ instanceId: "instance-id",
+ name: "label",
+ type: "expression",
+ value: "invalid {",
+ })
+ ).toThrow();
+
+ expect(() =>
+ propBindingInput.parse({
+ instanceId: "instance-id",
+ name: "value",
+ binding: { type: "expression", value: "invalid {" },
+ })
+ ).toThrow();
});
test("creates prop values and bindings from input", () => {
diff --git a/packages/project-build/src/runtime/props.ts b/packages/project-build/src/runtime/props.ts
index 71b2411737..8dc022bda8 100644
--- a/packages/project-build/src/runtime/props.ts
+++ b/packages/project-build/src/runtime/props.ts
@@ -1,12 +1,12 @@
import { z } from "zod";
import {
- lintExpression,
prop as propSchema,
type Instance,
type Prop,
} from "@webstudio-is/sdk";
import type { BuilderState } from "../state/builder-state";
import { throwBuilderRuntimeError } from "./errors";
+import { getExpressionErrors } from "./expression-validation";
import { createRuntimeMutation } from "./mutation";
export const findProp = (
@@ -64,49 +64,6 @@ export const createPropBindingFromInput = ({
value: binding.value,
});
-export const propValueInput = z.object({
- propId: z.string().optional(),
- instanceId: z.string(),
- name: z.string(),
- type: z.enum([
- "number",
- "string",
- "boolean",
- "json",
- "asset",
- "page",
- "string[]",
- "parameter",
- "resource",
- "expression",
- "action",
- "animationAction",
- ]),
- value: z.unknown(),
- required: z.boolean().optional(),
-});
-
-export const propBindingInput = z.object({
- propId: z.string().optional(),
- instanceId: z.string(),
- name: z.string(),
- binding: z.discriminatedUnion("type", [
- z.object({ type: z.literal("expression"), value: z.string() }),
- z.object({ type: z.literal("parameter"), value: z.string() }),
- z.object({ type: z.literal("resource"), value: z.string() }),
- z.object({
- type: z.literal("action"),
- value: z.array(
- z.object({
- type: z.literal("execute"),
- args: z.array(z.string()),
- code: z.string(),
- })
- ),
- }),
- ]),
-});
-
export const getPropValueErrors = ({
type,
value,
@@ -117,11 +74,81 @@ export const getPropValueErrors = ({
if (type !== "expression") {
return [];
}
- return lintExpression({ expression: String(value) })
- .filter((diagnostic) => diagnostic.severity === "error")
- .map((diagnostic) => diagnostic.message);
+ return getExpressionErrors(String(value));
};
+const addExpressionIssues = (
+ context: z.RefinementCtx,
+ errors: readonly string[],
+ path: (string | number)[] = []
+) => {
+ for (const message of errors) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ message,
+ path,
+ });
+ }
+};
+
+export const propValueInput = z
+ .object({
+ propId: z.string().optional(),
+ instanceId: z.string(),
+ name: z.string(),
+ type: z.enum([
+ "number",
+ "string",
+ "boolean",
+ "json",
+ "asset",
+ "page",
+ "string[]",
+ "parameter",
+ "resource",
+ "expression",
+ "action",
+ "animationAction",
+ ]),
+ value: z.unknown(),
+ required: z.boolean().optional(),
+ })
+ .superRefine((value, context) => {
+ addExpressionIssues(context, getPropValueErrors(value), ["value"]);
+ });
+
+export const propBindingInput = z
+ .object({
+ propId: z.string().optional(),
+ instanceId: z.string(),
+ name: z.string(),
+ binding: z.discriminatedUnion("type", [
+ z.object({ type: z.literal("expression"), value: z.string() }),
+ z.object({ type: z.literal("parameter"), value: z.string() }),
+ z.object({ type: z.literal("resource"), value: z.string() }),
+ z.object({
+ type: z.literal("action"),
+ value: z.array(
+ z.object({
+ type: z.literal("execute"),
+ args: z.array(z.string()),
+ code: z.string(),
+ })
+ ),
+ }),
+ ]),
+ })
+ .superRefine((value, context) => {
+ addExpressionIssues(
+ context,
+ getPropValueErrors({
+ type: value.binding.type,
+ value: value.binding.value,
+ }),
+ ["binding", "value"]
+ );
+ });
+
type ValidatedPropInputResult =
| { success: true; prop: Prop }
| { success: false; errors: string[] };
diff --git a/packages/protocol/src/builder-api/operation-docs.ts b/packages/protocol/src/builder-api/operation-docs.ts
index e4c92dd5e1..466fed3998 100644
--- a/packages/protocol/src/builder-api/operation-docs.ts
+++ b/packages/protocol/src/builder-api/operation-docs.ts
@@ -70,7 +70,7 @@ export const publicApiOperationDocumentation: readonly PublicApiOperationDocumen
description: "Update page settings and metadata",
requiredOptions: ["page", "json"],
examples: [
- 'webstudio update-page --page page-id --title Pricing --description "Pricing plans" --json',
+ 'webstudio update-page --page page-id --title "\\"Pricing\\"" --description "\\"Pricing plans\\"" --json',
],
},
{
@@ -248,7 +248,7 @@ export const publicApiOperationDocumentation: readonly PublicApiOperationDocumen
{
command: "update-props",
description:
- "Create or update element props; editor tokens are limited to content-mode props",
+ "Create or update direct element prop values; use this for fixed strings, numbers, booleans, JSON, assets, pages, parameters, and resources. Editor tokens are limited to content-mode props",
requiredOptions: ["input", "json"],
examples: ["webstudio update-props --input props.json --json"],
},
@@ -262,7 +262,7 @@ export const publicApiOperationDocumentation: readonly PublicApiOperationDocumen
{
command: "bind-props",
description:
- "Bind element props to expressions, parameters, resources, or actions",
+ "Bind element props to dynamic expressions, parameters, resources, or actions. Do not use for fixed string values; use update-props instead",
requiredOptions: ["input", "json"],
examples: ["webstudio bind-props --input bindings.json --json"],
},