Gui/site builder

[vibegui]

Summary by cubic

Ship the new Site Editor plugin and SITE_BINDING to let teams compose pages from typed React sections, scan code for JSON Schemas, live‑preview changes, and manage branches/history. Adds a starter template and routing/SDK updates to support local filesystem projects and per‑plugin routes.

• New Features

  • Define SITE_BINDING (file ops) with optional branch and history tools; alias-aware binder matching.
  • Add mesh-plugin-site-editor (client + server):
    • Client: Pages/Sections/Loaders views, Page Composer with live iframe preview, block/loader pickers, undo/redo, branch switcher, publish bar, history and diff.
    • Server: Page CRUD, block/loader scan/list/get/register, branch create/list/merge/delete, file history/read-at; MCP-aware site proxy.
  • Local-first setup: “Choose local folder” in binding selector creates filesystem MCP; preview panel stores tunnel/local URL; guided empty state.
  • Router: per-plugin static routes and pathless layout IDs to prevent collisions; object-storage updated accordingly.
  • Starter template: React 19 + Vite + Tailwind with typed sections, loader, and .deco scaffolding.

• Migration

  • Connect a site: open Site Editor → Choose local folder → pick your project.
  • Start your dev server and set the Preview URL (or run “deco link” and paste the tunnel URL).
  • Optional: run block/loader scans or use the starter template to bootstrap .deco files.

^{Written for commit e36e343. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Should a new version be published when this PR is merged?

React with an emoji to vote on the release type:

Reaction	Type	Next Version
👍	Prerelease	2.99.1-alpha.1
🎉	Patch	2.99.1
❤️	Minor	2.100.0
🚀	Major	3.0.0

Current version: 2.99.0

Deployment

• Deploy to production (triggers ArgoCD sync after Docker image is published)

[cubic-dev-ai]

34 issues found across 102 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/mesh-plugin-site-editor/client/components/pages-list.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/pages-list.tsx:40">
P2: `toLocaleDateString` only formats the date portion, so the hour/minute options won’t be reflected. Use `toLocaleString` if you want the time included for “Last Updated.”</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/client/components/pages-list.tsx:228">
P2: Avoid nesting a `<Button>` inside the row `<button>`—nested buttons are invalid HTML and can break accessibility/interaction. Use a non-button container for the row (e.g., a `<div role="button">`) or render the action as a non-button element.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/loaders-list.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/loaders-list.tsx:100">
P2: The “Scan Codebase” button is non-functional (only logs to console), which is misleading for users. Until the scan action is wired, disable the button or hook it to the real scan handler.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/lib/branch-api.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/client/lib/branch-api.ts:30">
P2: Catching all errors and returning null hides real failures (e.g., network/auth errors) and makes them indistinguishable from “tool not supported.” Consider only returning null for the unsupported-tool error and rethrowing others.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx:109">
P2: SelectWidget always passes a string to RJSF. For numeric/boolean enum options this changes the value type (e.g., 1 → "1"), which can break schema validation. Map the selected string back to the original enum option value before calling onChange.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/branch-merge.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/branch-merge.ts:42">
P2: The schema description says the target defaults to "main", but the handler passes `target` through as `undefined`. This can lead to inconsistent behavior if the MCP tool doesn’t apply its own default. Apply the default in the handler (or in the schema) to match the documented behavior.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/block-picker.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/block-picker.tsx:77">
P2: New blocks are always created with empty props because the picker passes `{}` instead of the block definition defaults. This skips any default props defined in the block schema and can lead to missing required values on insert.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/publish-bar.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/publish-bar.tsx:49">
P2: The success flash is unreachable after publishing because the component returns null as soon as currentBranch becomes "main". This prevents the "Published successfully" banner from ever displaying.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/page-delete.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/page-delete.ts:22">
P1: Validate/sanitize pageId before building the file path; as written, arbitrary path segments (e.g., "../") can escape `.deco/pages` and delete/overwrite unintended files.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/loader-get.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/loader-get.ts:18">
P1: Validate `loaderId` to prevent path traversal before using it in a file path.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/block-list.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/block-list.ts:85">
P2: Ensure `label` is always a string before pushing to `blocks`, otherwise `localeCompare` can throw and the output schema is violated for blocks missing a label.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/branch-create.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/branch-create.ts:37">
P2: The handler advertises a default source branch of "main" but forwards `from` as-is. If `from` is omitted, the call sends `from: undefined`, so the default may not be applied. Provide an explicit default when building the tool arguments.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts:71">
P2: Avoid invalidating all React Query caches here; it triggers unnecessary refetches. Invalidate only the connections query (or the specific query backing `connection` metadata).</violation>
</file>

<file name="apps/mesh/src/web/layouts/plugin-layout.tsx">

<violation number="1" location="apps/mesh/src/web/layouts/plugin-layout.tsx:165">
P2: `PUT_FILE` response adapter unconditionally returns `{ success: true }` without inspecting the actual result. Consider checking `rawResult` for error indicators (e.g., `isError` field) to avoid silently masking write failures.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/lib/page-api.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/client/lib/page-api.ts:169">
P2: Prevent updating tombstoned pages; updating a deleted page will write a malformed Page because the tombstone lacks id/path/blocks. Add a deleted check after parsing and fail early (or return) instead of applying updates.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts:30">
P1: Avoid using "*" for postMessage targetOrigin; restrict it to the iframe’s expected origin to prevent data leakage if the iframe navigates to a different site.</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts:37">
P2: Validate `e.origin` before handling messages so a navigated or compromised iframe can’t send trusted messages from an unexpected origin.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx:49">
P2: Draft detection is hardcoded to `main`, which can mislabel the published/default branch when it isn’t named `main`. Use the draft prefix (or default branch from data) to determine draft status.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/page-composer.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/page-composer.tsx:119">
P1: Side effect during render: `queueMicrotask(() => send(...))` is called in the render body. React render functions should be pure — in Strict Mode, React double-invokes render, so this will send duplicate `deco:page-config` messages to the iframe. Move this to a `useEffect` keyed on `blocks`.</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/client/components/page-composer.tsx:132">
P2: `useSyncExternalStore` is misused here as an event listener registration mechanism. The snapshot always returns `null`, so `notify()` never causes re-renders — the actual work is done via refs as side effects. Use a `useEffect` instead, which is the standard pattern for DOM event listeners and is much clearer to readers.</violation>
</file>

<file name="apps/mesh/src/web/components/binding-selector.tsx">

<violation number="1" location="apps/mesh/src/web/components/binding-selector.tsx:201">
P3: Folder name extraction only splits on `/`, so Windows paths with backslashes produce incorrect titles. Split on both separators to derive the final folder name reliably.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/scanner/schema.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/scanner/schema.ts:115">
P2: Inlining $ref discards sibling keywords (description/title/default), so metadata on a $ref node is lost after resolution. Merge the resolved definition with the original node (excluding $ref) to preserve overrides.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts:56">
P2: `postMessage(msg, "*")` sends editor data (page config, block selections) to any origin. If the iframe navigates to an untrusted page, sensitive data could be leaked. Consider passing the expected site origin instead of `"*"`.</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts:121">
P2: `removeEventListener("load", handleIframeLoad)` will silently fail because `handleIframeLoad` is a new function reference each render. The function passed to `addEventListener` in a prior render is a different object than the one passed to `removeEventListener` here. Store the handler in a ref to guarantee the same reference is used for both add and remove.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/site-proxy.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/site-proxy.ts:78">
P1: Normalize relative paths to prevent `..` segments from escaping the allowed root directory before concatenating them.</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/server/site-proxy.ts:147">
P2: Preserve error responses from the underlying MCP tool before transforming LIST_FILES output so failures aren’t silently treated as empty results.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/preview-panel.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/preview-panel.tsx:75">
P2: Validate the user-provided preview URL before persisting it; otherwise a `javascript:`/`data:` URL can be stored and executed when the iframe loads.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/loader-scan.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/loader-scan.ts:77">
P2: Handle MCP proxy creation inside the try/catch so connection failures are captured in `errors` instead of crashing the tool.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/page-get.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/page-get.ts:28">
P1: Validate/sanitize pageId before using it in the file path to prevent path traversal (e.g., only allow expected page ID format).</violation>
</file>

<file name="packages/mesh-plugin-site-editor/client/components/block-detail.tsx">

<violation number="1" location="packages/mesh-plugin-site-editor/client/components/block-detail.tsx:73">
P2: Avoid calling setFormData during render. Render-phase updates can cause extra render passes and warnings in concurrent rendering; sync block defaults in a useEffect instead.</violation>
</file>

<file name="packages/bindings/src/core/plugin-router.tsx">

<violation number="1" location="packages/bindings/src/core/plugin-router.tsx:41">
P2: `prependBasePath` now removes the first path segment for all absolute plugin routes, which drops legitimate segments when the path does not include an ID-only layout prefix (e.g., `"/$appName"` becomes just the base path). Guard the stripping logic so it only removes known layout IDs (e.g., segments ending in `-layout`) and otherwise preserve the original absolute path.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/tools/loader-list.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/tools/loader-list.ts:87">
P2: Guard against missing `label` values before sorting. As written, an undefined label from a malformed loader JSON will cause `localeCompare` to throw and the tool to fail.</violation>
</file>

<file name="packages/mesh-plugin-site-editor/server/scanner/discover.ts">

<violation number="1" location="packages/mesh-plugin-site-editor/server/scanner/discover.ts:32">
P2: The bare `"Element"` pattern is too broad for a substring match. It will match any return type containing the word "Element" (e.g., `HTMLElement`, `SVGElement`, `CustomElement`), causing false positives in component detection and false negatives in loader detection. The legitimate cases are already covered by `"JSX.Element"` and `"ReactElement"`.</violation>

<violation number="2" location="packages/mesh-plugin-site-editor/server/scanner/discover.ts:289">
P2: Bug: JSDoc is never extracted for arrow function components. The parent traversal stops one level too short — `fn.getParent().getParent()` reaches `VariableDeclarationList`, not `VariableStatement` (which is where JSDoc is attached in the TS AST). You need to go up one more level.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Validate/sanitize pageId before building the file path; as written, arbitrary path segments (e.g., "../") can escape .deco/pages and delete/overwrite unintended files.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/tools/page-delete.ts, line 22:

<comment>Validate/sanitize pageId before building the file path; as written, arbitrary path segments (e.g., "../") can escape `.deco/pages` and delete/overwrite unintended files.</comment>

<file context>
@@ -0,0 +1,70 @@
+  description: "Delete a CMS page by ID.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    pageId: z.string().describe("Page ID to delete"),
+  }),
+  outputSchema: z.object({
</file context>

[cubic-dev-ai]

P1: Validate loaderId to prevent path traversal before using it in a file path.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/tools/loader-get.ts, line 18:

<comment>Validate `loaderId` to prevent path traversal before using it in a file path.</comment>

<file context>
@@ -0,0 +1,77 @@
+    "Get a single CMS loader definition by ID, including its full input and output JSON Schemas.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    loaderId: z.string().describe('Loader ID (e.g., "loaders--productList")'),
+  }),
+  outputSchema: z.object({
</file context>

[cubic-dev-ai]

P1: Avoid using "*" for postMessage targetOrigin; restrict it to the iframe’s expected origin to prevent data leakage if the iframe navigates to a different site.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts, line 30:

<comment>Avoid using "*" for postMessage targetOrigin; restrict it to the iframe’s expected origin to prevent data leakage if the iframe navigates to a different site.</comment>

<file context>
@@ -0,0 +1,44 @@
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+): UseEditorMessagesResult {
+  const send = (msg: EditorMessage) => {
+    iframeRef.current?.contentWindow?.postMessage(msg, "*");
+  };
+
</file context>

[cubic-dev-ai]

P1: Side effect during render: queueMicrotask(() => send(...)) is called in the render body. React render functions should be pure — in Strict Mode, React double-invokes render, so this will send duplicate deco:page-config messages to the iframe. Move this to a useEffect keyed on blocks.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/client/components/page-composer.tsx, line 119:

<comment>Side effect during render: `queueMicrotask(() => send(...))` is called in the render body. React render functions should be pure — in Strict Mode, React double-invokes render, so this will send duplicate `deco:page-config` messages to the iframe. Move this to a `useEffect` keyed on `blocks`.</comment>

<file context>
@@ -0,0 +1,543 @@
+  const prevBlocksRef = useRef<BlockInstance[]>(blocks);
+  if (localPage && blocks !== prevBlocksRef.current) {
+    prevBlocksRef.current = blocks;
+    queueMicrotask(() => {
+      if (localPage) {
+        send({ type: "deco:page-config", page: localPage });
</file context>

[cubic-dev-ai]

P1: Normalize relative paths to prevent .. segments from escaping the allowed root directory before concatenating them.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/site-proxy.ts, line 78:

<comment>Normalize relative paths to prevent `..` segments from escaping the allowed root directory before concatenating them.</comment>

<file context>
@@ -0,0 +1,184 @@
+ */
+function toAbsolute(rootDir: string | null, relativePath: string): string {
+  if (!rootDir || relativePath.startsWith("/")) return relativePath;
+  return `${rootDir.replace(/\/$/, "")}/${relativePath}`;
+}
+
</file context>

[cubic-dev-ai]

P2: prependBasePath now removes the first path segment for all absolute plugin routes, which drops legitimate segments when the path does not include an ID-only layout prefix (e.g., "/$appName" becomes just the base path). Guard the stripping logic so it only removes known layout IDs (e.g., segments ending in -layout) and otherwise preserve the original absolute path.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/bindings/src/core/plugin-router.tsx, line 41:

<comment>`prependBasePath` now removes the first path segment for all absolute plugin routes, which drops legitimate segments when the path does not include an ID-only layout prefix (e.g., `"/$appName"` becomes just the base path). Guard the stripping logic so it only removes known layout IDs (e.g., segments ending in `-layout`) and otherwise preserve the original absolute path.</comment>

<file context>
@@ -28,15 +33,36 @@ function prependBasePath(
+    // e.g., "/site-editor-layout/pages/$pageId" → "/pages/$pageId"
+    // e.g., "/site-editor-layout/" → "/"
+    // e.g., "/site-editor-layout" → ""
+    const rest = to.substring(1); // "site-editor-layout/pages/$pageId"
+    const slashIdx = rest.indexOf("/");
+    const urlPath = slashIdx >= 0 ? rest.substring(slashIdx) : "";
</file context>

Suggested change

	const rest = to.substring(1); // "site-editor-layout/pages/$pageId"
	const slashIdx = rest.indexOf("/");
	const urlPath = slashIdx >= 0 ? rest.substring(slashIdx) : "";
	return `/${org}/${project}/${pluginId}${urlPath}`;
	const rest = to.substring(1); // "site-editor-layout/pages/$pageId"
	const slashIdx = rest.indexOf("/");
	const firstSegment = slashIdx >= 0 ? rest.substring(0, slashIdx) : rest;
	const urlPath = firstSegment.endsWith("-layout")
	? slashIdx >= 0
	? rest.substring(slashIdx)
	: ""
	: `/${rest}`;
	return `/${org}/${project}/${pluginId}${urlPath}`;

[cubic-dev-ai]

P2: Guard against missing label values before sorting. As written, an undefined label from a malformed loader JSON will cause localeCompare to throw and the tool to fail.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/tools/loader-list.ts, line 87:

<comment>Guard against missing `label` values before sorting. As written, an undefined label from a malformed loader JSON will cause `localeCompare` to throw and the tool to fail.</comment>

<file context>
@@ -0,0 +1,105 @@
+          loaders.push({
+            id: loader.id,
+            source: loader.source,
+            label: loader.label,
+            category: loader.category ?? "Other",
+            inputParamsCount,
</file context>

[cubic-dev-ai]

P2: The bare "Element" pattern is too broad for a substring match. It will match any return type containing the word "Element" (e.g., HTMLElement, SVGElement, CustomElement), causing false positives in component detection and false negatives in loader detection. The legitimate cases are already covered by "JSX.Element" and "ReactElement".

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/scanner/discover.ts, line 32:

<comment>The bare `"Element"` pattern is too broad for a substring match. It will match any return type containing the word "Element" (e.g., `HTMLElement`, `SVGElement`, `CustomElement`), causing false positives in component detection and false negatives in loader detection. The legitimate cases are already covered by `"JSX.Element"` and `"ReactElement"`.</comment>

<file context>
@@ -0,0 +1,546 @@
+  "ReactElement",
+  "React.FC",
+  "React.FunctionComponent",
+  "Element",
+];
+
</file context>

[cubic-dev-ai]

P2: Bug: JSDoc is never extracted for arrow function components. The parent traversal stops one level too short — fn.getParent().getParent() reaches VariableDeclarationList, not VariableStatement (which is where JSDoc is attached in the TS AST). You need to go up one more level.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mesh-plugin-site-editor/server/scanner/discover.ts, line 289:

<comment>Bug: JSDoc is never extracted for arrow function components. The parent traversal stops one level too short — `fn.getParent().getParent()` reaches `VariableDeclarationList`, not `VariableStatement` (which is where JSDoc is attached in the TS AST). You need to go up one more level.</comment>

<file context>
@@ -0,0 +1,546 @@
+  if (!parent) return "";
+
+  // Walk up to the variable statement which can hold JSDoc
+  const varStatement = parent.getParent();
+  if (varStatement?.isKind(SyntaxKind.VariableStatement)) {
+    const jsDocs = varStatement.getJsDocs();
</file context>

[cubic-dev-ai]

P3: Folder name extraction only splits on /, so Windows paths with backslashes produce incorrect titles. Split on both separators to derive the final folder name reliably.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/binding-selector.tsx, line 201:

<comment>Folder name extraction only splits on `/`, so Windows paths with backslashes produce incorrect titles. Split on both separators to derive the final folder name reliably.</comment>

<file context>
@@ -149,8 +165,82 @@ export function BindingSelector({
+      if (!folderPath) return;
+
+      const folderName =
+        folderPath.split("/").filter(Boolean).pop() ?? "folder";
+
+      // For object storage bindings, use the local-object-storage bridge
</file context>

Suggested change

	folderPath.split("/").filter(Boolean).pop() ?? "folder";
	folderPath.split(/[/\\]/).filter(Boolean).pop() ?? "folder";